|
1 | | -import React from "react"; |
2 | | -import { Menu as BlueprintMenu, MenuProps as BlueprintMenuProps } from "@blueprintjs/core"; |
| 1 | +import React, { AriaRole } from "react"; |
| 2 | +import { |
| 3 | + Menu as BlueprintMenu, |
| 4 | + MenuItem as BlueprintMenuItem, |
| 5 | + MenuProps as BlueprintMenuProps, |
| 6 | +} from "@blueprintjs/core"; |
3 | 7 |
|
4 | 8 | import { CLASSPREFIX as eccgui } from "../../configuration/constants"; |
5 | 9 |
|
6 | | -export type MenuProps = BlueprintMenuProps; |
| 10 | +import MenuDivider, { MenuDividerProps } from "./MenuDivider"; |
| 11 | +import MenuItem, { MenuItemProps } from "./MenuItem"; |
| 12 | + |
| 13 | +/** |
| 14 | + * Roles that are supported by the automatic `roleStructure` handling of the `MenuItem` children. |
| 15 | + */ |
| 16 | +type SupportedMenuRole = "menu" | "navigation" | "list" | "listbox" | "none" | "presentation"; |
| 17 | + |
| 18 | +export interface MenuProps extends BlueprintMenuProps { |
| 19 | + /** |
| 20 | + * Sets the ARIA role of the menu. |
| 21 | + * It may become mandatory in a future version. |
| 22 | + * Setting a `role` checks whether `MenuItem` and `MenuDivider` children use a correct `roleStructure`, or sets it automatically. |
| 23 | + * The automatic checks only work if `MenuItem` and `MenuDivider` are used as direct children or inside a `Fragment`. |
| 24 | + * The checks only work for `menu`, `navigation`, `list`, `listbox`, `none` and `presentation`. |
| 25 | + * Other roles are applied as they are, and the children are not processed. |
| 26 | + */ |
| 27 | + role?: SupportedMenuRole | AriaRole; |
| 28 | +} |
| 29 | + |
| 30 | +const roleMapping: Partial<Record<SupportedMenuRole, AriaRole>> = { |
| 31 | + navigation: "list", |
| 32 | +}; |
| 33 | + |
| 34 | +const allowedRoleStructure: Record<SupportedMenuRole, NonNullable<MenuItemProps["roleStructure"]>[]> = { |
| 35 | + menu: ["menuitem"], |
| 36 | + navigation: ["listitem"], |
| 37 | + list: ["listitem"], |
| 38 | + listbox: ["listoption"], |
| 39 | + none: ["none"], |
| 40 | + presentation: ["none"], |
| 41 | +}; |
| 42 | + |
| 43 | +/** |
| 44 | + * Allowed values for an explicitly set `role` on `MenuItem` children, regarding their (explicitly or automatically set) `roleStructure`. |
| 45 | + * Blueprint sets this `role` on the inner target element of the item, where it overwrites the role defined by `roleStructure`, |
| 46 | + * so it must fit to the role of the `li` element that is defined by `roleStructure`. |
| 47 | + * A `roleStructure` without entry does not restrict the item role. |
| 48 | + */ |
| 49 | +const allowedItemRole: Partial<Record<NonNullable<MenuItemProps["roleStructure"]>, AriaRole[]>> = { |
| 50 | + menuitem: ["menuitem", "menuitemcheckbox", "menuitemradio"], |
| 51 | + listitem: ["link", "button", "none", "presentation"], |
| 52 | + // the `li` element already has the `option` role, so the target element must not have an own role |
| 53 | + listoption: ["none", "presentation"], |
| 54 | +}; |
| 55 | + |
| 56 | +/** |
| 57 | + * `MenuDivider` children get this role if their `role="separator"` is not allowed inside the (mapped) menu role. |
| 58 | + */ |
| 59 | +const dividerRoleMapping: Partial<Record<AriaRole, AriaRole>> = { |
| 60 | + list: "listitem", |
| 61 | + listbox: "none", |
| 62 | +}; |
| 63 | + |
| 64 | +/** |
| 65 | + * Blueprint uses this `roleStructure` by default, so it does not need to be set explicitly. |
| 66 | + */ |
| 67 | +const defaultRoleStructure: MenuItemProps["roleStructure"] = "menuitem"; |
| 68 | + |
| 69 | +/** |
| 70 | + * Represents a list of items, used as menu, navigation, options, or only for presentation. |
| 71 | + * It sets automatically `roleStructure` for its direct `MenuItem` children (also inside fragments) regarding the set `role`, |
| 72 | + * or it emits a console warning if it does not fit to an already set `roleStructure`. |
| 73 | + * It also emits a console warning if an explicitly set `role` of a `MenuItem` does not fit to its `roleStructure`. |
| 74 | + * On `MenuDivider` children without role or with `role="separator"` it sets `role="listitem"` in lists |
| 75 | + * (`role="list"` or `role="navigation"`) and `role="none"` in listboxes, because `separator` is not allowed there. |
| 76 | + * It also sets `aria-hidden` then if the divider has no `title` and no own `aria-hidden` value. |
| 77 | + * It does not add a `nav` wrapper on `role="navigation"`, you need to do it on your own. |
| 78 | + */ |
| 79 | +export const Menu = ({ children, className = "", role = "menu", ...restProps }: MenuProps) => { |
| 80 | + const isSupportedRole = Object.prototype.hasOwnProperty.call(allowedRoleStructure, role); |
| 81 | + const roleMapped = (isSupportedRole && roleMapping[role as SupportedMenuRole]) || role; |
| 82 | + const subroles = isSupportedRole ? allowedRoleStructure[role as SupportedMenuRole] : undefined; |
| 83 | + const dividerRole = Object.prototype.hasOwnProperty.call(dividerRoleMapping, roleMapped) |
| 84 | + ? dividerRoleMapping[roleMapped] |
| 85 | + : undefined; |
| 86 | + |
| 87 | + // warnings are collected while rendering and emitted by an effect, so they are not repeated on each re-render |
| 88 | + const warnings: string[] = []; |
| 89 | + |
| 90 | + const processItems = ( |
| 91 | + nodes: React.ReactNode, |
| 92 | + subroles: NonNullable<MenuItemProps["roleStructure"]>[], |
| 93 | + ): React.ReactNode => |
| 94 | + React.Children.map(nodes, (child) => { |
| 95 | + if (React.isValidElement<{ children?: React.ReactNode }>(child) && child.type === React.Fragment) { |
| 96 | + return <React.Fragment key={child.key}>{processItems(child.props.children, subroles)}</React.Fragment>; |
| 97 | + } |
| 98 | + if (React.isValidElement<MenuDividerProps>(child) && child.type === MenuDivider) { |
| 99 | + if (!dividerRole) { |
| 100 | + return child; |
| 101 | + } |
| 102 | + const { role: ownRole, title, "aria-hidden": ariaHidden } = child.props; |
| 103 | + return React.cloneElement(child, { |
| 104 | + // `separator` is not allowed here, other explicitly set roles are kept |
| 105 | + ...(!ownRole || ownRole === "separator" ? { role: dividerRole } : {}), |
| 106 | + ...(!title && ariaHidden === undefined ? { "aria-hidden": true } : {}), |
| 107 | + }); |
| 108 | + } |
| 109 | + if ( |
| 110 | + !React.isValidElement<MenuItemProps>(child) || |
| 111 | + (child.type !== MenuItem && child.type !== BlueprintMenuItem) |
| 112 | + ) { |
| 113 | + return child; |
| 114 | + } |
| 115 | + const { roleStructure, role: itemRole } = child.props; |
| 116 | + const roleStructureUsed = roleStructure ?? subroles[0]; |
| 117 | + const itemRoles = allowedItemRole[roleStructureUsed]; |
| 118 | + if (itemRole && itemRoles && !itemRoles.includes(itemRole)) { |
| 119 | + warnings.push( |
| 120 | + `Menu: MenuItem with role="${itemRole}" does not fit to its roleStructure="${roleStructureUsed}"${ |
| 121 | + roleStructure ? "" : ` (set automatically for Menu role="${role}")` |
| 122 | + }, allowed: ${itemRoles.map((allowedRole) => `"${allowedRole}"`).join(", ")}.`, |
| 123 | + ); |
| 124 | + } |
| 125 | + if (!roleStructure) { |
| 126 | + // prevent unnecessary cloning if Blueprint's default is used anyway |
| 127 | + return subroles[0] === defaultRoleStructure |
| 128 | + ? child |
| 129 | + : React.cloneElement(child, { roleStructure: subroles[0] }); |
| 130 | + } |
| 131 | + if (!subroles.includes(roleStructure)) { |
| 132 | + warnings.push( |
| 133 | + `Menu: MenuItem with roleStructure="${roleStructure}" does not fit into Menu with role="${role}", allowed: ${subroles |
| 134 | + .map((subrole) => `"${subrole}"`) |
| 135 | + .join(", ")}.`, |
| 136 | + ); |
| 137 | + } |
| 138 | + return child; |
| 139 | + }); |
| 140 | + |
| 141 | + const items = subroles ? processItems(children, subroles) : children; |
| 142 | + |
| 143 | + // only emit warnings again if they changed |
| 144 | + const warningsKey = warnings.join("\n"); |
| 145 | + React.useEffect(() => { |
| 146 | + if (!warningsKey) { |
| 147 | + return; |
| 148 | + } |
| 149 | + warningsKey.split("\n").forEach((warning) => { |
| 150 | + // eslint-disable-next-line no-console |
| 151 | + console.warn(warning); |
| 152 | + }); |
| 153 | + }, [warningsKey]); |
7 | 154 |
|
8 | | -export const Menu = ({ children, className = "", ...restProps }: MenuProps) => { |
9 | 155 | return ( |
10 | | - <BlueprintMenu {...restProps} className={`${eccgui}-menu__list ` + className}> |
11 | | - {children} |
| 156 | + <BlueprintMenu role={roleMapped} {...restProps} className={`${eccgui}-menu__list ` + className}> |
| 157 | + {items} |
12 | 158 | </BlueprintMenu> |
13 | 159 | ); |
14 | 160 | }; |
|
0 commit comments