primer · langermank · Nov 2, 2021 · Oct 4, 2021 · Oct 4, 2021 · Oct 5, 2021
diff --git a/docs/package.json b/docs/package.json
@@ -17,7 +17,7 @@
     "@primer/gatsby-theme-doctocat": "2.0.0",
     "@primer/octicons": "16.1.0",
     "@primer/octicons-react": "16.0.0",
-    "@primer/primitives": "6.0.0",
+    "@primer/primitives": "6.1.0-rc.9f1f534",
     "@svgr/webpack": "5.5.0",
     "autoprefixer": "10.3.7",
     "babel-preset-gatsby": "^2.0.0",

@@ -55,6 +55,8 @@
 - title: Components
   url: /components
   children:
+    - title: Action List
+      url: /components/action-list
     - title: Alerts
       url: /components/alerts
     - title: Autocomplete

@@ -0,0 +1,180 @@
+import {Meta, Story, Canvas} from '@storybook/addon-docs'
+
+<Meta title="Components/ActionList/Accessibility" />
+
+### Action List
+
+An action list is a vertical list of interactive <strong>actions</strong> or <strong>options</strong>.
+
+|         |                                       |
+| :------ | :------------------------------------ |
+| Actions | links `a href` or events `onclick`    |
+| Options | checkbox role `checked` or `selected` |
+
+### Semantic markup
+
+The markup for Action List changes depending on the intended use case.
+
+In all cases, the basic structure is as follows:
+
+```html
+<ul>
+  <li><span>Content with action</span></li>
+  <li><a href="/">Content as link</a></li>
+  <li>
+    <ul>
+      <li>Nested list</li>
+    </ul>
+  </li>
+</ul>
+```
+
+Pay close attention to `role` attributes throughout the documentation, and find the use case that best suits your needs.
+
+### Menu
+
+[Menu spec](https://www.w3.org/TR/wai-aria-practices-1.1/#menu)
+
+Note: JS is required for to provide keyboard handling along with [tab-index](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_roving_tabindex)
+
+| Element | Role                            |
+| :------ | :------------------------------ |
+| `ul`    | `role="menu"`                   |
+| `li`    | no child link `role="menuitem"` |
+| `li`    | has child link `role="none"`    |
+| `a`     | `role="menuitem"`               |
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--menu-with-section-divider" />
+</Canvas>
+
+### Navigational menu
+
+[Menu spec](https://www.w3.org/TR/wai-aria-practices-1.1/#menu)
+
+Note: JS is required for to provide keyboard handling along with [tab-index](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_roving_tabindex)
+
+| Element | Role                                     |
+| :------ | :--------------------------------------- |
+| `nav`   | no role needed                           |
+| `ul`    | `role="menu"`                            |
+| `li`    | no child link `role="menuitem"`          |
+| `li`    | has child link `role="none"`             |
+| `li`    | nested menu `aria-haspopup="true"`       |
+| `li`    | nested menu `aria-expanded="true/false"` |
+| `a`     | `role="menuitem"`                        |
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--nav-with-sub-items" />
+</Canvas>
+
+### Multi select menu
+
+[Menu spec](https://www.w3.org/TR/wai-aria-practices-1.1/examples/menubar/menubar-2/menubar-2.html)
+
+Note: JS is required for to provide keyboard handling along with [tab-index](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_roving_tabindex)
+
+| Element | Role                                    |
+| :------ | :-------------------------------------- |
+| `ul`    | `role="menu"`                           |
+| `li`    | no child link `role="menuitemcheckbox"` |
+| `li`    | `aria-checked="true/false"`             |
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--menu-multi-select" />
+</Canvas>
+
+### Single select menu
+
+[Menu spec](https://www.w3.org/TR/wai-aria-practices-1.1/examples/menubar/menubar-2/menubar-2.html)
+
+Note: JS is required for to provide keyboard handling along with [tab-index](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_roving_tabindex)
+
+| Element | Role                                 |
+| :------ | :----------------------------------- |
+| `ul`    | `role="menu"`                        |
+| `li`    | no child link `role="menuitemradio"` |
+| `li`    | `aria-checked="true/false"`          |
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--menu-single-select" />
+</Canvas>
+
+### Multi select listbox
+
+[Menu spec](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox)
+
+Note: JS is required for to provide [keyboard handling](https://www.w3.org/TR/wai-aria-practices-1.1/#listbox_kbd_interaction)
+
+| Element | Role                          |
+| :------ | :---------------------------- |
+| `ul`    | `role="listbox"`              |
+| `ul`    | `aria-multiselectable="true"` |
+| `li`    | `role="option"`               |
+| `li`    | `aria-selected="true/false"`  |
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--list-multi-select" />
+</Canvas>
+
+### Single select listbox
+
+[Menu spec](https://www.w3.org/TR/wai-aria-practices-1.1/#Listbox)
+
+Note: JS is required for to provide [keyboard handling](https://www.w3.org/TR/wai-aria-practices-1.1/#listbox_kbd_interaction)
+
+| Element | Role                         |
+| :------ | :--------------------------- |
+| `ul`    | `role="listbox"`             |
+| `li`    | `role="option"`              |
+| `li`    | `aria-selected="true/false"` |
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--list-single-select" />
+</Canvas>
+
+### List of links
+
+No roles needed
+
+#### Example
+
+<Canvas>
+  <Story id="components-actionlist-patterns--list" />
+</Canvas>
+
+### Dividers
+
+| Element | Role               |
+| :------ | :----------------- |
+| `li`    | `role="separator"` |
+
+#### Empty example
+
+<Canvas>
+  <Story id="components-actionlist-actionlistitem-features--divider-empty" />
+</Canvas>
+
+| Element | Role                                        |
+| :------ | :------------------------------------------ |
+| `li`    | `role="presentation"`                       |
+| `li`    | id for nested group `id="group-id"`         |
+| `li`    | if it has id for group `aria-hidden="true"` |
+
+#### With title example
+
+<Canvas>
+  <Story id="components-actionlist-actionlistitem-features--divider-text" />
+</Canvas>
@@ -0,0 +1,113 @@
+import React from 'react'
+import clsx from 'clsx'
+import {ListItemTemplate} from './ActionListItem.stories'
+
+export default {
+  title: 'Components/ActionList',
+  excludeStories: ['ListTemplate'],
+  parameters: {
+    design: {
+      type: 'figma',
+      url: 'https://www.figma.com/file/oMiRuexZW6gqVbMhQd6lwP/Storybook-Docs?node-id=23%3A30843'
+    }
+  },
+  argTypes: {
+    showDividers: {
+      control: {type: 'boolean'},
+      description: 'Show dividers between items',
+      table: {
+        category: 'CSS'
+      }
+    },
+    role: {
+      options: [0, 1, 2, 3, 4, 5, 6], // iterator
+      mapping: ['menu', 'group', 'listbox', 'menubar', 'none', 'radiogroup', 'list'], // values
+      control: {
+        type: 'select',
+        labels: ['menu', 'group', 'listbox', 'menubar', 'none', 'radiogroup', 'list']
+      },
+      description: 'Semantic list role',
+      table: {
+        category: 'HTML'
+      }
+    },
+    ariaLabel: {
+      name: 'ariaLabel',
+      type: 'string',
+      description: 'Descriptive label for menu contents',
+      table: {
+        category: 'HTML'
+      }
+    },
+    ariaLabelledBy: {
+      name: 'ariaLabelledBy',
+      type: 'string',
+      description: 'Reference ID of section divider',
+      table: {
+        category: 'HTML'
+      }
+    },
+    groupId: {
+      name: 'groupId',
+      type: 'string',
+      description: 'Menu group id',
+      table: {
+        category: 'HTML'
+      }
+    },
+    children: {
+      table: {
+        category: 'HTML'
+      }
+    },
+    subGroup: {
+      control: {type: 'boolean'},
+      description: 'If ActionList is nested within an ActionList',
+      table: {
+        category: 'CSS'
+      }
+    },
+    listboxMultiSelect: {
+      name: 'listboxMultiSelect',
+      type: 'string',
+      description: 'If ActionList has listbox role + multiselect children',
+      table: {
+        category: 'HTML'
+      }
+    }
+  }
+}
+
+export const ListTemplate = ({
+  showDividers,
+  children,
+  role,
+  ariaLabel,
+  ariaLabelledBy,
+  subGroup,
+  listboxMultiSelect
+}) => (
+  <ul
+    className={clsx('ActionList', showDividers && 'ActionList--divided', subGroup && 'ActionList--subGroup')}
+    role={role}
+    aria-label={ariaLabel && ariaLabel}
+    aria-labelledby={ariaLabelledBy && ariaLabelledBy}
+    aria-multiselectable={listboxMultiSelect ? 'true' : undefined}
+  >
+    <>{children}</>
+  </ul>
+)
+
+export const Playground = ListTemplate.bind({})
+Playground.args = {
+  role: 'menu',
+  ariaLabel: 'Menu description',
+  subGroup: false,
+  showDividers: false,
+  children: (
+    <>
+      <ListItemTemplate text="Action list item" />
+      <ListItemTemplate text="Action list item" />
+    </>
+  )
+}
@@ -0,0 +1,81 @@
+import React from 'react'
+import clsx from 'clsx'
+
+export default {
+  title: 'Components/ActionList/ActionListDivider',
+  excludeStories: ['DividerTemplate'],
+  parameters: {
+    design: {
+      type: 'figma',
+      url: 'https://www.figma.com/file/oMiRuexZW6gqVbMhQd6lwP/Storybook?node-id=2%3A2'
+    }
+  },
+  argTypes: {
+    variant: {
+      options: [0, 1], // iterator
+      mapping: ['', 'ActionList-sectionDivider--filled'], // values
+      control: {
+        type: 'select',
+        labels: ['subtle', 'filled']
+      },
+      table: {
+        category: 'CSS'
+      }
+    },
+    title: {
+      defaultValue: '',
+      type: 'string',
+      name: 'title',
+      description: 'string',
+      table: {
+        category: 'HTML'
+      }
+    },
+    description: {
+      defaultValue: '',
+      type: 'string',
+      name: 'description',
+      description: 'string',
+      table: {
+        category: 'HTML'
+      }
+    },
+    id: {
+      defaultValue: '',
+      type: 'string',
+      name: 'id',
+      description: 'Used for aria-labelledby',
+      table: {
+        category: 'HTML'
+      }
+    }
+  },
+  decorators: [
+    Story => (
+      <ul className="ActionList" role="menu">
+        <Story />
+      </ul>
+    )
+  ]
+}
+
+export const DividerTemplate = ({title, description, variant, id}) => (
+  <>
+    <li
+      className={clsx('ActionList-sectionDivider', variant && `${variant}`)}
+      role={title ? 'presentation' : 'separator'}
+      id={id}
+      aria-hidden={title ? true : undefined}
+    >
+      {title}
+      {description && <span className="ActionList-item-description">{description}</span>}
+    </li>
+  </>
+)
+
+export const Playground = DividerTemplate.bind({})
+Playground.args = {
+  title: 'Section title',
+  description: 'Section description',
+  variant: 'subtle'
+}