From 495cfe34212f81cc9ec13fab08d4018300aa5d87 Mon Sep 17 00:00:00 2001 From: Jan Hassel Date: Fri, 24 Feb 2023 09:09:10 +0100 Subject: [PATCH] docs: add docs for menu and useContextMenu (#13209) * docs(menu): add docs * docs(useContextMenu): add docs * docs(useContextMenu): clarify that react refs can also be passed * docs(useContextMenu): update live demo meta * docs(menu): add live demo meta --------- Co-authored-by: Andrea N. Cardona Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> --- .../components/ContextMenu/docs/overview.mdx | 6 +- .../components/ContextMenu/useContextMenu.mdx | 65 +++++++ ...u.stories.js => useContextMenu.stories.js} | 35 +++- packages/react/src/components/Menu/Menu.mdx | 162 ++++++++++++++++++ .../react/src/components/Menu/Menu.stories.js | 6 + .../src/components/Menu/docs/overview.mdx | 13 ++ 6 files changed, 281 insertions(+), 6 deletions(-) create mode 100644 packages/react/src/components/ContextMenu/useContextMenu.mdx rename packages/react/src/components/ContextMenu/{ContextMenu.stories.js => useContextMenu.stories.js} (81%) create mode 100644 packages/react/src/components/Menu/Menu.mdx create mode 100644 packages/react/src/components/Menu/docs/overview.mdx diff --git a/packages/react/src/components/ContextMenu/docs/overview.mdx b/packages/react/src/components/ContextMenu/docs/overview.mdx index 8620a9c55c4b..c4ee614bf3d1 100644 --- a/packages/react/src/components/ContextMenu/docs/overview.mdx +++ b/packages/react/src/components/ContextMenu/docs/overview.mdx @@ -7,11 +7,7 @@ variants={[ { label: 'Default', - variant: 'experimental-unstable-menu-contextmenu--context-menu' + variant: 'experimental-unstable-usecontextmenu--use-context-menu' }, - { - label: 'Multiple Groups', - variant: 'experimental-unstable-menu-contextmenu--multiple-groups' - } ]} /> diff --git a/packages/react/src/components/ContextMenu/useContextMenu.mdx b/packages/react/src/components/ContextMenu/useContextMenu.mdx new file mode 100644 index 000000000000..ecf4656f41ff --- /dev/null +++ b/packages/react/src/components/ContextMenu/useContextMenu.mdx @@ -0,0 +1,65 @@ +import { ArgsTable, Canvas, Story } from '@storybook/addon-docs'; + +# useContextMenu + +[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Menu) + + + + +- [Overview](#overview) +- [Component API](#component-api) +- [Feedback](#feedback) + + + +## Overview + +The `useContextMenu` hook is meant to be used in conjunction with `Menu` (see this [component's documentation](http://localhost:3000/?path=/docs/experimental-unstable-menu--playground) for more details). It provides an easy way to generate the necessary props for `Menu`. + +By default, it will listen to the `contextmenu` event on `document`. In most cases you'll want to restrict a context menu to a certain element or group of elements only. You can pass that element as the argument for `useContextMenu`. + +```jsx +function SomeComponent() { + const el = useRef(null); + const menuProps = useContextMenu(el); + + return ( + <> +
+ … +
+ + + + + + + + ); +} +``` + +Be aware that the following props are not set by `useContextMenu` and can therefore be configured by the user: +- className +- label +- size +- target + +## Component API + +```js +// returns an object with 'x', 'y', 'open' and 'onClose' set accordingly intended +// to be passed as pros to the component. +const menuProps = useContextMenu( + // the DOM element or react ref the "contextmenu" event should be attached to. + // defaults to document. + trigger, +); +``` + +## Feedback + +Help us improve this component by providing feedback, asking questions on Slack, +or updating this file on +[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/ContextMenu/useContextMenu.mdx). diff --git a/packages/react/src/components/ContextMenu/ContextMenu.stories.js b/packages/react/src/components/ContextMenu/useContextMenu.stories.js similarity index 81% rename from packages/react/src/components/ContextMenu/ContextMenu.stories.js rename to packages/react/src/components/ContextMenu/useContextMenu.stories.js index 8e52e6673146..109a88bafedf 100644 --- a/packages/react/src/components/ContextMenu/ContextMenu.stories.js +++ b/packages/react/src/components/ContextMenu/useContextMenu.stories.js @@ -5,9 +5,10 @@ * LICENSE file in the root directory of this source tree. */ -import React from 'react'; +import React, { useRef } from 'react'; import { action } from '@storybook/addon-actions'; +import { usePrefix } from '../../internal/usePrefix'; import CodeSnippet from '../CodeSnippet'; import UnorderedList from '../UnorderedList'; import ListItem from '../ListItem'; @@ -15,10 +16,16 @@ import ListItem from '../ListItem'; import { Menu, MenuItem, MenuItemDivider, MenuItemRadioGroup } from '../Menu'; import { useContextMenu } from './'; +import mdx from './useContextMenu.mdx'; export default { title: 'Experimental/unstable__useContextMenu', component: useContextMenu, + parameters: { + docs: { + page: mdx, + }, + }, }; const Text = () => ( @@ -88,3 +95,29 @@ export const _useContextMenu = () => { ); }; + +export const SpecificElement = () => { + const prefix = usePrefix(); + + const el = useRef(null); + const menuProps = useContextMenu(el); + + return ( + <> +
+ Right click this element +
+ + + + + + ); +}; diff --git a/packages/react/src/components/Menu/Menu.mdx b/packages/react/src/components/Menu/Menu.mdx new file mode 100644 index 000000000000..407cc767725b --- /dev/null +++ b/packages/react/src/components/Menu/Menu.mdx @@ -0,0 +1,162 @@ +import { ArgsTable, Canvas, Story } from '@storybook/addon-docs'; + +# Menu + +[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Menu) + + + + +- [Overview](#overview) +- [Positioning](#positioning) +- [Subcomponents](#subcomponents) + - [MenuItem](#menuitem) + - [MenuItemDivider](#menuitemdivider) + - [MenuItemGroup](#menuitemgroup) + - [MenuItemSelectable](#menuitemselectable) + - [MenuItemRadioGroup](#menuitemradiogroup) +- [Context menu (right-click menu)](#context-menu-right-click-menu) +- [Component API](#component-api) +- [Feedback](#feedback) + + + +## Overview + +`Menu` is a versatile component that can be used in a variety of situations. It implements the [menu design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) defined in the ARIA Authoring Practices Guide (APG). + +The `Menu` component's `children` must be a collection of any of these subcomponents: +- [MenuItem](#menuitem) +- [MenuItemDivider](#menuitemdivider) +- [MenuItemGroup](#menuitemgroup) +- [MenuItemSelectable](#menuitemselectable) +- [MenuItemRadioGroup](#menuitemradiogroup) + +## Positioning + +You must provide a reference point for the `Menu` to position itself at. The props `x` and `y` either accept a single number each or an array of two numbers. + +The latter option is used to specify the trigger boundaries. For example, Carbon uses this for the [OverflowMenuV2](http://localhost:3000/?path=/story/experimental-unstable-overflowmenuv2--overflow-menu-v-2) where it passes `[x, x + width]` and `[y, y + height]` of the trigger button. This way, the `Menu` is able to automatically determine its ideal position on the screen (which side to open at and in which direction) while always staying visually attached to the trigger. +Each `MenuItem` that has `children` and therfore a submenu uses the same approach under the hood to correctly position the submenu. + +## Subcomponents + +### MenuItem + +A `MenuItem` renders a basic menu item with a label an optionally a shortcut hint (_note: the component only renders this hint and doesn't actually register the shortcut in the browser_). Each `MenuItem` can be clicked unless it's marked as `disabled`. If it triggers a destructive action, you can pass it `kind="danger"` to highlight it specially on hover and focus. + +```jsx + + + + + +``` + +In order to render a submenu, you can pass any of the above mentioned subcomponents as `children` of a `MenuItem`. + +```jsx + + + + + + + + + +``` + +### MenuItemDivider + +The `MenuItemDivider` renders a thin dividing line, visually separating menu items. Use this to enhance grouping of related items. + +```jsx + + + + + + + +``` + +### MenuItemGroup + +You can logically group multiple menu items by wrapping them inside a `MenuItemGroup`. This doesn't affect the visual rendering but can tremendously improve the experience for assistive technology users. You'll always want to use a `MenuItemGroup` if you have multiple [`MenuItemSelectable`](#menuitemselectable) that are relatd to each other. + +### MenuItemSelectable + +`MenuItemSelectable` is a checkbox in a menu context. Each `MenuItemSelectable` can be checked and unchecked unrelated to other items. If multiple items are related to each other, you'll want to wrap them in a `MenuItemGroup` for improved accessibility. + +```jsx + + + + + + +``` + +### MenuItemRadioGroup +`MenuItemRadioGroup` is a radio button group in a menu context. Only one item can be selected at a time. The component automatically wraps itself in a `MenuItemGroup`, so you won't have to nest it manually. + +```jsx + + + + + +``` + +The `items` prop is designed to accept arbitrary items to best match your data structure. If you pass your items as anything that doesn't support `.toString()` out of the box, you'll need to pass a custom `itemToString` function that will be used for rendering the labels. + +```jsx +const items = [ + { weight: 100, label: 'Thin' }, + { weight: 200, label: 'Extralight' }, + { weight: 300, label: 'Light' }, + { weight: 400, label: 'Regular' }, + { weight: 500, label: 'Medium' }, + { weight: 600, label: 'Semibold' }, + { weight: 700, label: 'Bold' }, +]; + + item.label} +/> +``` + +## Context menu (right-click menu) + +The `Menu` component is suited to be used as a context menu for complex web applications. To make this easy, Carbon provides a [`useContextMenu`](http://localhost:3000/?path=/story/experimental-unstable-usecontextmenu--use-context-menu) react hook. Please refer to the [hook's documentation](http://localhost:3000/?path=/docs/experimental-unstable-usecontextmenu--use-context-menu) for more details. + +## Component API + + + +## Feedback + +Help us improve this component by providing feedback, asking questions on Slack, +or updating this file on +[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/Menu/Menu.mdx). diff --git a/packages/react/src/components/Menu/Menu.stories.js b/packages/react/src/components/Menu/Menu.stories.js index a72be4eaaf77..6b48370b1f72 100644 --- a/packages/react/src/components/Menu/Menu.stories.js +++ b/packages/react/src/components/Menu/Menu.stories.js @@ -16,6 +16,7 @@ import { MenuItemRadioGroup, MenuItemDivider, } from './'; +import mdx from './Menu.mdx'; export default { title: 'Experimental/unstable__Menu', @@ -27,6 +28,11 @@ export default { MenuItemRadioGroup, MenuItemDivider, }, + parameters: { + docs: { + page: mdx, + }, + }, }; export const Playground = (args) => { diff --git a/packages/react/src/components/Menu/docs/overview.mdx b/packages/react/src/components/Menu/docs/overview.mdx new file mode 100644 index 000000000000..91bd96db9f2a --- /dev/null +++ b/packages/react/src/components/Menu/docs/overview.mdx @@ -0,0 +1,13 @@ +## Live demo + +