Cleanup & document a11y migration

MIGRATION.md

@@ -6,7 +6,8 @@
   - [Options addon deprecated](#options-addon-deprecated)
   - [Individual story decorators](#individual-story-decorators)
   - [Addon backgrounds uses parameters](#addon-backgrounds-uses-parameters)
-  - [Addon viewport uses parameters](#addon-backgrounds-uses-parameters)
+  - [Addon viewport uses parameters](#addon-viewport-uses-parameters)
+  - [Addon a11y uses parameters](#addon-a11y-uses-parameters-decorator-renamed)
 - [From version 4.0.x to 4.1.x](#from-version-40x-to-41x)
   - [Private addon config](#private-addon-config)
   - [React 15.x](#react-15x)
@@ -204,7 +205,31 @@ addParameters({ viewport: options });
 
 The `withViewport` decorator is also no longer supported and should be replaced with a parameter based API as above. Also the `onViewportChange` callback is no longer supported.
 
-See the [README](https://github.com/storybooks/storybook/blob/master/addons/viewport/README.md) for the viewport addon for more information.
+See the [viewport addon README](https://github.com/storybooks/storybook/blob/master/addons/viewport/README.md) for more information.
+
+## Addon a11y uses parameters, decorator renamed
+
+Similarly, `@storybook/addon-a11y` uses parameters to pass a11y options. If you previously had:
+
+```js
+import { configureA11y } from `@storybook/addon-a11y`;
+
+configureA11y(options);
+```
+
+You should replace it with:
+
+```js
+import { addParameters } from '@storybook/react'; // or others
+
+addParameters({ a11y: options });
+```
+
+You can pass `a11y` parameters at the global level (via `addParameters` imported from `@storybook/react` et al.), and the story level (via the third argument to `.add()`).
+
+Furthermore, the decorator `checkA11y` has been deprecated and renamed to `withA11y` to make it consistent with other Storybook decorators.
+
+See the [a11y addon README](https://github.com/storybooks/storybook/blob/master/addons/a11y/README.md) for more information.
 
 ## From version 4.0.x to 4.1.x
 
@@ -237,16 +262,16 @@ Also, here's the error you'll get if you're running an older version of React:
 ```
 
 core.browser.esm.js:15 Uncaught TypeError: Object(...) is not a function
-  at Module../node_modules/@emotion/core/dist/core.browser.esm.js (core.browser.esm.js:15)
-  at __webpack_require__ (bootstrap:724)
-  at fn (bootstrap:101)
-  at Module../node_modules/@emotion/styled-base/dist/styled-base.browser.esm.js (styled-base.browser.esm.js:1)
-  at __webpack_require__ (bootstrap:724)
-  at fn (bootstrap:101)
-  at Module../node_modules/@emotion/styled/dist/styled.esm.js (styled.esm.js:1)
-  at __webpack_require__ (bootstrap:724)
-  at fn (bootstrap:101)
-  at Object../node_modules/@storybook/components/dist/navigation/MenuLink.js (MenuLink.js:12)
+at Module../node_modules/@emotion/core/dist/core.browser.esm.js (core.browser.esm.js:15)
+at **webpack_require** (bootstrap:724)
+at fn (bootstrap:101)
+at Module../node_modules/@emotion/styled-base/dist/styled-base.browser.esm.js (styled-base.browser.esm.js:1)
+at **webpack_require** (bootstrap:724)
+at fn (bootstrap:101)
+at Module../node_modules/@emotion/styled/dist/styled.esm.js (styled.esm.js:1)
+at **webpack_require** (bootstrap:724)
+at fn (bootstrap:101)
+at Object../node_modules/@storybook/components/dist/navigation/MenuLink.js (MenuLink.js:12)
 
 ```
 

addons/a11y/README.md

@@ -20,16 +20,16 @@ Add this line to your `addons.js` file (create this file inside your storybook c
 import '@storybook/addon-a11y/register';
 ```
 
-import the `withA11Y` decorator to check your stories for violations within your components.
+import the `withA11y` decorator to check your stories for violations within your components.
 
 ```js
 import React from 'react';
 import { storiesOf } from '@storybook/react';
-import { withA11Y } from '@storybook/addon-a11y';
+import { withA11y } from '@storybook/addon-a11y';
 
 // should only be added once
 // best place is in config.js
-addDecorator(withA11Y)
+addDecorator(withA11y)
 
 storiesOf('button', module)
   .add('Accessible', () => (
@@ -51,9 +51,9 @@ You can override these options at story level too.
 import React from 'react';
 import { storiesOf, addDecorator, addParameters } from '@storybook/react';
 
-import { withA11Y } from '@storybook/addon-a11y';
+import { withA11y } from '@storybook/addon-a11y';
 
-addDecorator(withA11Y)
+addDecorator(withA11y)
 addParameters({
   a11y: {
     // ... axe options

addons/a11y/src/index.js

@@ -3,7 +3,7 @@ import axe from 'axe-core';
 import deprecate from 'util-deprecate';
 import { stripIndents } from 'common-tags';
 
-import addons, { makeDecorator } from '@storybook/addons';
+import addons from '@storybook/addons';
 import { STORY_RENDERED } from '@storybook/core-events';
 import EVENTS, { PARAM_KEY } from './constants';
 
@@ -24,35 +24,31 @@ const report = input => {
   channel.emit(EVENTS.RESULT, input);
 };
 
-const run = (c, o) => {
+const run = (config, options) => {
   progress = progress.then(() => {
     axe.reset();
-    if (c) {
-      axe.configure(c);
+    if (config) {
+      axe.configure(config);
     }
     return axe
       .run(
         getElement(),
-        o || {
+        options || {
           restoreScroll: true,
         }
       )
       .then(report);
   });
 };
 
-export const withA11Y = makeDecorator({
-  name: 'withA11Y',
-  parameterName: PARAM_KEY,
-  skipIfNoParametersOrOptions: false,
-  allowDeprecatedUsage: false,
-
-  wrapper: (getStory, context, opt) => {
-    setup = opt.parameters || opt.options || {};
-
-    return getStory(context);
-  },
-});
+// NOTE: we should add paramaters to the STORY_RENDERED event and deprecate this
+export const withA11y = (getStory, context) => {
+  const params = context.parameters[PARAM_KEY];
+  if (params) {
+    setup = params;
+  }
+  return getStory(context);
+};
 
 channel.on(STORY_RENDERED, () => run(setup.config, setup.options));
 channel.on(EVENTS.REQUEST, () => run(setup.config, setup.options));
@@ -63,8 +59,8 @@ if (module && module.hot && module.hot.decline) {
 
 // TODO: REMOVE at v6.0.0
 export const checkA11y = deprecate(
-  (...args) => withA11Y(...args),
-  'checkA11y has been replaced with withA11Y'
+  (...args) => withA11y(...args),
+  'checkA11y has been renamed withA11y'
 );
 
 // TODO: REMOVE at v6.0.0

examples/html-kitchen-sink/stories/addon-a11y.stories.js

@@ -1,11 +1,11 @@
 import { document, setTimeout } from 'global';
 import { storiesOf } from '@storybook/html';
-import { withA11Y } from '@storybook/addon-a11y';
+import { withA11y } from '@storybook/addon-a11y';
 
 const text = 'Testing the a11y addon';
 
 storiesOf('Addons|a11y', module)
-  .addDecorator(withA11Y)
+  .addDecorator(withA11y)
   .addParameters({ options: { selectedPanel: 'storybook/a11y/panel' } })
   .add('Default', () => `<button></button>`)
   .add('Label', () => `<button>${text}</button>`)

examples/official-storybook/config.js

@@ -3,7 +3,7 @@ import { storiesOf, configure, addDecorator, addParameters } from '@storybook/re
 import { Global, ThemeProvider, themes, createReset } from '@storybook/theming';
 
 import { withCssResources } from '@storybook/addon-cssresources';
-import { withA11Y } from '@storybook/addon-a11y';
+import { withA11y } from '@storybook/addon-a11y';
 import { withNotes } from '@storybook/addon-notes';
 
 import 'storybook-chromatic';
@@ -28,7 +28,7 @@ addHeadWarning('preview-head-not-loaded', 'Preview head not loaded');
 addHeadWarning('dotenv-file-not-loaded', 'Dotenv file not loaded');
 
 addDecorator(withCssResources);
-addDecorator(withA11Y);
+addDecorator(withA11y);
 addDecorator(withNotes);
 
 addDecorator(storyFn => (

examples/official-storybook/stories/__snapshots__/addon-a11y.stories.storyshot

@@ -357,6 +357,12 @@ exports[`Storyshots Addons|A11y/Image Without alt 1`] = `
 />
 `;
 
+exports[`Storyshots Addons|A11y/Image Without alt but unchecked 1`] = `
+<img
+  src="http://placehold.it/350x150"
+/>
+`;
+
 exports[`Storyshots Addons|A11y/Typography Correct 1`] = `
 Array [
   <h1>

examples/official-storybook/stories/addon-a11y.stories.js

@@ -56,6 +56,15 @@ storiesOf('Addons|A11y/Image', module)
   .addParameters({ options: { selectedPanel: 'storybook/a11y/panel' } })
   /* eslint-disable jsx-a11y/alt-text */
   .add('Without alt', () => <img src={image} />)
+  .add('Without alt but unchecked', () => <img src={image} />, {
+    a11y: {
+      config: {
+        disableOtherRules: true,
+        rules: [],
+      },
+      options: {},
+    },
+  })
   .add('With alt', () => <img src={image} alt={text} />)
   .add('Presentation', () => <img role="presentation" src={image} />);