improve documentation

Author: haschek

src/components/ContextOverlay/ContextMenu.stories.tsx

@@ -23,11 +23,12 @@ const Template: StoryFn<typeof ContextMenu> = (args) => (
 
 export const Default = Template.bind({});
 Default.args = {
+    role: "menu",
     children: [
-        <MenuItem key="m0" text={"First option"} />,
-        <MenuItem key="m1" text={"Item two"}>
-            <MenuItem key="m2" text={"First sub option"} />
-            <MenuItem key="m3" text={"Sub item two"} />
+        <MenuItem key="m0" roleStructure="menuitem" text={"First option"} />,
+        <MenuItem key="m1" roleStructure="menuitem" text={"Item two"}>
+            <MenuItem key="m2" roleStructure="menuitem" text={"First sub option"} />
+            <MenuItem key="m3" roleStructure="menuitem" text={"Sub item two"} />
         </MenuItem>,
     ],
 };

src/components/Menu/Menu.tsx

@@ -18,9 +18,11 @@ type SupportedMenuRole = "menu" | "navigation" | "list" | "listbox" | "none" | "
 export interface MenuProps extends BlueprintMenuProps {
     /**
      * Sets the ARIA role of the menu.
-     * For `menu`, `navigation`, `list`, `listbox`, `none` and `presentation` it checks if the `MenuItems` using a correct `roleStructure`,
-     * or set it automatically.
-     * Other roles are set as they are, the children are not processed then.
+     * It may become mandatory in a future version.
+     * Setting a `role` checks whether `MenuItem` and `MenuDivider` children use a correct `roleStructure`, or sets it automatically.
+     * The automatic checks only work if `MenuItem` and `MenuDivider` are used as direct children or inside a `Fragment`.
+     * The checks only work for `menu`, `navigation`, `list`, `listbox`, `none` and `presentation`.
+     * Other roles are applied as they are, and the children are not processed.
      */
     role?: SupportedMenuRole | AriaRole;
 }

src/components/Menu/MenuItem.tsx

@@ -34,10 +34,18 @@ export interface MenuItemProps
      * Visual intent color to apply to element.
      */
     intent?: BlueprintMenuItemProps["intent"] | "accent";
+    /**
+     * Defines the ARIA role structure that is used for the menu item element and its inner target element.
+     * It is recommended to set it, even if it is optional right now.
+     * The value is checked if a `role` is set on the parent `Menu`.
+     * It may become mandatory in a future version.
+     */
+    roleStructure?: BlueprintMenuItemProps["roleStructure"];
 }
 
 /**
  * Single item, used as child inside `Menu`.
+ * It is recommended to use it as a direct child and not to wrap it inside other elements, except `Fragment`.
  */
 export const MenuItem = React.forwardRef<HTMLLIElement, MenuItemProps>(
     ({ children, className = "", icon, onClick, href, text, tooltip, intent, ...restProps }, ref) => {

src/components/Menu/Stories/Menu.stories.tsx

@@ -25,18 +25,21 @@ const MenuExample: StoryFn<typeof Menu> = (args) => (
 
 export const Default = MenuExample.bind({});
 Default.args = {
+    role: "menu",
     children: (
         <>
             {ContentMenuStory.args.children}
-            <MenuDivider title="Second menu part" />
+            <MenuDivider role="separator" title="Second menu part" />
             <MenuItem {...MenuItemStory.args} active />
         </>
     ),
 };
 
 /**
  * Use `role="navigation"` for a list of links, e.g. as main or sidebar navigation.
- * The `MenuItem` elements get `roleStructure="listitem"` automatically.
+ * The `MenuItem` elements need `roleStructure="listitem"`, it is set automatically if missing.
+ * `MenuDivider` elements need `role="listitem"` because `separator` is not allowed inside a list,
+ * it is set automatically if missing. Dividers without `title` get `aria-hidden` automatically.
  * `Menu` does not add a `nav` element, so you need to wrap it on your own.
  */
 const NavigationExample: StoryFn<typeof Menu> = (args) => (
@@ -51,9 +54,18 @@ export const Navigation = NavigationExample.bind({});
 Navigation.args = {
     role: "navigation",
     children: [
-        <MenuItem key="1" text="Dashboard" icon="application-homepage" href="#dashboard" active aria-current="page" />,
-        <MenuItem key="2" text="Projects" icon="artefact-project" href="#projects" />,
-        <MenuItem key="3" text="Datasets" icon="artefact-dataset" href="#datasets" />,
-        <MenuItem key="4" text="Settings" icon="application-useraccount" href="#settings" />,
+        <MenuItem
+            key="1"
+            roleStructure="listitem"
+            text="Dashboard"
+            icon="application-homepage"
+            href="#dashboard"
+            active
+            aria-current="page"
+        />,
+        <MenuItem key="2" roleStructure="listitem" text="Projects" icon="artefact-project" href="#projects" />,
+        <MenuItem key="3" roleStructure="listitem" text="Datasets" icon="artefact-dataset" href="#datasets" />,
+        <MenuDivider key="d1" role="listitem" />,
+        <MenuItem key="4" roleStructure="listitem" text="Settings" icon="application-useraccount" href="#settings" />,
     ],
 };

src/components/Menu/Stories/MenuItem.stories.tsx

@@ -29,7 +29,7 @@ export default {
 
 const MenuExample: StoryFn<typeof MenuItem> = (args) => (
     <OverlaysProvider>
-        <Menu style={{ width: "200px" }}>
+        <Menu role="menu" style={{ width: "200px" }}>
             <MenuItem {...args} />
         </Menu>
     </OverlaysProvider>
@@ -39,10 +39,11 @@ export const Default = MenuExample.bind({});
 Default.args = {
     children: (
         <>
-            <MenuItem key="m6" text={"Sub option 1"} />
-            <MenuItem key="m7" text={"Sub option 2"} />
+            <MenuItem key="m6" roleStructure="menuitem" text={"Sub option 1"} />
+            <MenuItem key="m7" roleStructure="menuitem" text={"Sub option 2"} />
         </>
     ),
     text: "Parent option",
+    roleStructure: "menuitem",
     key: "m4",
 };