@contentful/f36-menu 4.0.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2018-present Contentful GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.mdx

@@ -0,0 +1,159 @@
+---
+title: 'Menu'
+slug: /components/menu/
+github: 'https://github.com/contentful/forma-36/tree/forma-v4/packages/components/menu'
+typescript: ./src/Menu.tsx,./src/MenuItem/MenuItem.tsx,./src/MenuList/MenuList.tsx
+---
+
+Menu is a component that offers a list of choices to the user, such as a set of actions or links.
+Menu uses Popover component as a base.
+
+## Import
+
+```jsx static=true
+import { Menu } from '@contentful/f36-components';
+```
+
+## Examples
+
+You can use following components to build a menu:
+
+1. `<Menu>`: The main wrapper that provides nested components with all the context and state.
+1. `<Menu.Trigger>` The wrapper for the menu list trigger. Must be a direct child of `<Menu>`.
+   NOTE: 🚨 Ensure that the component that you pass accepts `ref`. Consider using `forwardRef` for functional components.
+1. `<Menu.List>`: The wrapper for the menu items. Must be a direct child of `<Menu>`.
+1. `<Menu.Item>` The trigger that handles menu selection. Must be a direct child of `<Menu.List>`.
+1. `<Menu.Divider>` A visual separator for menu items.
+1. `<Menu.SectionTitle>` A title that you can use in the menu list.
+1. `<Menu.ListHeader>` The wrapper for one menu item that will be sticked to the top of the menu list. `<Menu.Item>` must be provided as a child.
+1. `<Menu.ListFooter>` The wrapper for one menu item that will be sticked to the bottom of the menu list. `<Menu.Item>` must be provided as a child.
+1. `<Menu.Submenu>` The wrapper for for submenu components. Structure of the children remains the same like in `<Menu>`, except you should use `<Menu.SubmenuTrigger>` instead of `<Menu.Trigger>`.
+1. `<Menu.SubmenuTrigger>` The wrapper for the submenu list trigger. Must be a direct child of `<Menu.Submenu>`.
+
+### Basic usage
+
+```tsx file=examples/BasicMenu.tsx
+
+```
+
+### With simple Button as a trigger
+
+```tsx file=examples/MenuWithButtonAsTrigger.tsx
+
+```
+
+### With Menu.SectionTitle and Menu.Divider
+
+```jsx file=examples/MenuWithTitle.tsx
+
+```
+
+### Controlled Menu
+
+By default the Menu component is uncontrolled. So when user clicks on the trigger, the menu opens/closes.
+But you can control it by passing `isOpen` prop and `onClose`, `onOpen` callbacks.
+
+```jsx file=examples/ControlledMenu.tsx
+function ControlledMenu() {
+  const [isOpen, setIsOpen] = React.useState(false);
+  return (
+    <Menu
+      isOpen={isOpen}
+      onOpen={() => setIsOpen(true)}
+      onClose={() => setIsOpen(false)}
+    >
+      <Menu.Trigger>
+        <IconButton
+          variant="secondary"
+          icon={<MenuIcon />}
+          aria-label="toggle menu"
+        />
+      </Menu.Trigger>
+      <Menu.List>
+        <Menu.Item>Create an entry</Menu.Item>
+        <Menu.Item>Remove an entry</Menu.Item>
+        <Menu.Item>Embed existing entry</Menu.Item>
+      </Menu.List>
+    </Menu>
+  );
+}
+```
+
+### Controlled Menu with custom trigger onClick callback
+
+In most cases, you will use the [controlled approach](#controlled-menu).
+But if you have to provide your own toggle menu logic on the trigger component, you can do this by providing `onClick` callback on trigger component and omitting `onOpen` callback on the Menu component.
+
+```jsx file=examples/ControlledMenuWithCustomTriggerLogic.tsx
+
+```
+
+### With Menu list maximum height
+
+```jsx file=examples/MenuWithMaxHeight.tsx
+
+```
+
+### With disabled items
+
+```jsx file=examples/MenuWithDisabledItems.tsx
+
+```
+
+### With menu open by default
+
+```jsx static=true file=examples/MenuOpenByDefault.tsx
+
+```
+
+### With sticky header and footer
+
+```jsx file=examples/MenuWithStickyHeaderFooter.tsx
+
+```
+
+### With React Router links
+
+```jsx static=true file=examples/MenuWithReactRouterLinks.tsx
+
+```
+
+### With predefined focused menu item
+
+```jsx file=examples/MenuWithPredefinedFocusedMenuItem.tsx
+
+```
+
+### With submenu
+
+By default props like `closeOnSelect`, `closeOnBlur`, `closeOnEsc` that you pass to `Menu` will be shared to all submenus
+But you can redefine them on any submenu by passing those props directly to that `Submenu`.
+
+```jsx file=examples/MenuWithSubmenu.tsx
+
+```
+
+### Menu
+
+<Props of="Menu" storybookPath="/story/components-menu--basic" />
+
+### Menu.Item
+
+<Props of="MenuItem" />
+
+### Menu.List
+
+<Props of="MenuList" />
+
+## Content guidelines
+
+- Use an interactive element such as `button` for `Menu.Trigger`
+
+## Accessibility
+
+- When the menu is opened, focus is moved to the first menu item. If you set `autoFocus`to `false`, it will not move the focus.
+- When the menu is closed, focus returned back to the trigger element.
+- You can use arrow keys (`ArrowUp` and `ArrowDown`) to navigate through menu items.
+- When the menu is open, click on `Esc` key will close the popover. If you set `closeOnEsc` to `false`, it will not close.
+- When the menu is open, click outside menu or blurring out will close the menu. If you set `closeOnBlur` to `false`, it will not close.
+- All the necessary a11y attributes for `Menu.List`, `Menu.Trigger` and `Menu.Item` are provided.