From 4b0207ad7153d7e983c7a961d8dd09bc38fd0791 Mon Sep 17 00:00:00 2001 From: Adam Wathan Date: Wed, 16 Sep 2020 15:07:02 -0400 Subject: [PATCH] docs: Document React Menu, tweak Transition and Vue docs to be consistent --- packages/@headlessui-react/README.md | 549 +++++++++++++++++++++++++-- packages/@headlessui-vue/README.md | 86 ++--- 2 files changed, 541 insertions(+), 94 deletions(-) diff --git a/packages/@headlessui-react/README.md b/packages/@headlessui-react/README.md index f2c904f..1024da0 100644 --- a/packages/@headlessui-react/README.md +++ b/packages/@headlessui-react/README.md @@ -25,29 +25,46 @@ yarn add @headlessui/react ## Components +_This project is still in early development. New components will be added regularly over the coming months._ + +- [Transition](#menu-button-dropdown) +- [Menu Button (Dropdown)](#menu-button-dropdown) + +### Roadmap + This project is still in early development, but the plan is to build out all of the primitives we need to provide interactive React examples of all of the components included in [Tailwind UI](https://tailwindui.com), the commercial component directory that helps us fund the development of our open-source work like [Tailwind CSS](https://tailwindcss.com). This includes things like: -- Dropdowns +- Listboxes - Toggles - Modals - Tabs - Slide-overs - Mobile menus -- Listboxes - Accordions ...and more in the future. -We decided to start with an enter/leave [Transition](#transition) component that is tailor-made for Tailwind's utility-first CSS approach, to help bring the React experience up to parity with what's already possible in the Vue ecosystem. - We'll be continuing to develop new components on an on-going basis, with a goal of reaching a pretty fleshed out v1.0 by the end of the year. -### Transition +--- + +## Transition The `Transition` component lets you add enter/leave transitions to conditionally rendered elements, using CSS classes to control the actual transition styles in the different stages of the transition. +- [Basic example](#basic-example) +- [Showing and hiding content](#showing-and-hiding-content) +- [Animating transitions](#animating-transitions) +- [Co-ordinating multiple transitions](#co-ordinating-multiple-transitions) +- [Transitioning on initial mount](#transitioning-on-initial-mount) +- [Component API](#component-api) + +### Basic example + +The `Transition` accepts a `show` prop that controls whether the children should be shown or hidden, and a set of lifecycle props (like `enterFrom`, and `leaveTo`) that let you add CSS classes at specific phases of a transition. + ```tsx import { Transition } from '@headlessui/react' import { useState } from 'react' @@ -74,7 +91,7 @@ function MyComponent() { } ``` -#### Showing and hiding the Transition content +### Showing and hiding content Wrap the content that should be conditionally rendered in a `` component, and use the `show` prop to control whether the content should be visible or hidden. @@ -150,7 +167,7 @@ function MyComponent() { Be sure to attach the `ref` or your transitions will not work correctly. -#### Animating transitions +### Animating transitions By default, a `Transition` will enter and leave instantly, which is probably not what you're looking for if you're using this library. @@ -201,7 +218,7 @@ It will start as completely opaque (the `opacity-100` in the `leaveFrom` phase), All of these props are optional, and will default to just an empty string. -#### Co-ordinating multiple transitions +### Co-ordinating multiple transitions Sometimes you need to transition multiple elements with different animations but all based on the same state. For example, say the user clicks a button to open a sidebar that slides over the screen, and you also need to fade-in a background overlay at the same time. @@ -213,32 +230,29 @@ import { Transition } from '@headlessui/react' function Sidebar({ isOpen }) { return ( - {/* Shared parent */} -
- {/* Background overlay */} - - {/* ... */} - + {/* Background overlay */} + + {/* ... */} + - {/* Sliding sidebar */} - - {/* ... */} - -
+ {/* Sliding sidebar */} + + {/* ... */} + ) } @@ -248,7 +262,7 @@ The `Transition.Child` component has the exact same API as the `Transition` comp Parent `Transition` components will always automatically wait for all children to finish transitioning before unmounting, so you don't need to manage any of that timing yourself. -#### Transitioning on initial mount +### Transitioning on initial mount If you want an element to transition the very first time it's rendered, set the `appear` prop to `true`. @@ -274,3 +288,470 @@ function MyComponent({ isShowing }) { ) } ``` + +### Component API + +#### Transition + +```jsx + + {/* Your content goes here*/} + +``` + +##### Props + +| Prop | Type | Description | +| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------- | +| `show` | Boolean | Whether the children should be shown or hidden. | +| `as` | String Component _(Default: `'div'`)_ | The element or component to render in place of the `Transition` itself. | +| `appear` | Boolean _(Default: `false`)_ | Whether the transition should run on initial mount. | +| `enter` | String _(Default: '')_ | Classes to add to the transitioning element during the entire enter phase. | +| `enterFrom` | String _(Default: '')_ | Classes to add to the transitioning element before the enter phase starts. | +| `enterTo` | String _(Default: '')_ | Classes to add to the transitioning element immediately after the enter phase starts. | +| `leave` | String _(Default: '')_ | Classes to add to the transitioning element during the entire leave phase. | +| `leaveFrom` | String _(Default: '')_ | Classes to add to the transitioning element before the leave phase starts. | +| `leaveTo` | String _(Default: '')_ | Classes to add to the transitioning element immediately after the leave phase starts. | + +##### Render prop arguments + +| Prop | Type | Description | +| ----- | ---------------------- | ----------------------------------------------------------------------------------- | +| `ref` | React.MutableRefObject | A ref that needs to be manually added to the child node when using the render prop. | + +#### Transition.Child + +```jsx + + + {/* ... */} + + {/* ... */} + +``` + +##### Props + +| Prop | Type | Description | +| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------- | +| `as` | String Component _(Default: `'div'`)_ | The element or component to render in place of the `Transition.Child` itself. | +| `appear` | Boolean _(Default: `false`)_ | Whether the transition should run on initial mount. | +| `enter` | String _(Default: '')_ | Classes to add to the transitioning element during the entire enter phase. | +| `enterFrom` | String _(Default: '')_ | Classes to add to the transitioning element before the enter phase starts. | +| `enterTo` | String _(Default: '')_ | Classes to add to the transitioning element immediately after the enter phase starts. | +| `leave` | String _(Default: '')_ | Classes to add to the transitioning element during the entire leave phase. | +| `leaveFrom` | String _(Default: '')_ | Classes to add to the transitioning element before the leave phase starts. | +| `leaveTo` | String _(Default: '')_ | Classes to add to the transitioning element immediately after the leave phase starts. | + +##### Render prop arguments + +| Prop | Type | Description | +| ----- | ---------------------- | ----------------------------------------------------------------------------------- | +| `ref` | React.MutableRefObject | A ref that needs to be manually added to the child node when using the render prop. | + +--- + +## Menu Button (Dropdown) + +The `Menu` component and related child components are used to quickly build custom dropdown components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard navigation support. + +- [Basic example](#basic-example-1) +- [Styling the active item](#styling-the-active-item) +- [Showing/hiding the menu](#showinghiding-the-menu) +- [Disabling an item](#disabling-an-item) +- [Transitions](#transitions) +- [Rendering additional content](#rendering-additional-content) +- [Rendering a different element for a component](#rendering-a-different-element-for-a-component) +- [Component API](#component-api-1) + +### Basic example + +Menu Buttons are built using the `Menu`, `Menu.Button`, `Menu.Items`, and `Menu.Item` components. + +The `Menu.Button` will automatically open/close the `Menu.Items` when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + More + + + {({ active }) => ( + + Account settings + + )} + + + {({ active }) => ( + + Documentation + + )} + + + Invite a friend (coming soon!) + + + + ) +} +``` + +### Styling the active item + +This is a headless component so there are no styles included by default. Instead, the components expose useful information via [render props](https://reactjs.org/docs/render-props.html) that you can use to apply the styles you'd like to apply yourself. + +To style the active `Menu.Item` you can read the `active` render prop argument, which tells you whether or not that menu item is the item that is currently focused via the mouse or keyboard. + +You can use this state to conditionally apply whatever active/focus styles you like, for instance a blue background like is typical in most operating systems. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + More + + {/* Use the `active` state to conditionally style the active item. */} + + {({ active }) => ( + + Account settings + + )} + + {/* ... */} + + + ) +} +``` + +### Showing/hiding the menu + +By default, your `Menu.Items` instance will be shown/hidden automatically based on the internal `open` state tracked within the `Menu` component itself. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + More + + {/* By default, this will automatically show/hide when the Menu.Button is pressed. */} + + {/* ... */} + {/* ... */} + + + ) +} +``` + +If you'd rather handle this yourself (perhaps because you need to add an extra wrapper element for one reason or another), you can add a `static` prop to the `Menu.Items` instance to tell it to always render, and inspect the `open` slot prop provided by the `Menu` to control which element is shown/hidden yourself. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + {({ open }) => ( + More + {open && ( +
+ {/* Using `static`, `Menu.Items` is always rendered and ignores the `open` state. */} + + {/* ... */} + {/* ... */} + +
+ )} + )} + + ) +} +``` + +### Disabling an item + +Use the `disabled` prop to disable a `Menu.Item`. This will make it unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + More + + {/* ... */} + + {/* This item will be skipped by keyboard navigation. */} + + Invite a friend (coming soon!) + + + {/* ... */} + + + ) +} +``` + +### Transitions + +To animate the opening/closing of the menu panel, use jsx's built-in `transition` component. All you need to do is wrap your `Menu.Items` instance in a `` element and the transition will be applied automatically. + +```jsx +import { Menu, Transition } from '@headlessui/react' + +function MyDropdown() { + return ( + + {({ open }) => ( + More + + {/* Use the Transition + open render prop argument to add transitions. */} + + + {/* ... */} + {/* ... */} + + + )} + + ) +} +``` + +### Rendering additional content + +The `Menu` component is not limited to rendering only its related subcomponents. You can render anything you like within a menu, which gives you complete control over exactly what you are building. + +For example, if you'd like to add a little header section to the menu with some extra information in it, just render an extra `div` with your content in it. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + More + +
+

Signed in as

+

tom@example.com

+
+ + {({ active }) => ( + + Account settings + + )} + + + {/* ... */} + + + ) +} +``` + +Note that only `Menu.Item` instances will be navigable via the keyboard. + +### Rendering a different element for a component + +By default, the `Menu` and its subcomponents each render a default element that is sensible for that component. + +For example, `Menu.Button` renders a `button` by default, and `Menu.Items` renders a `div`. `Menu` and `Menu.Item` interestingly _do not render an extra element_, and instead render their children directly by default. + +This is easy to change using the `as` prop, which exists on every component. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + {/* Render a `div` instead of no wrapper element */} + + More + {/* Render a `ul` instead of a `div` */} + + {/* Render an `li` instead of no wrapper element */} + + {({ active }) => ( + + Account settings + + )} + + + {/* ... */} + + + ) +} +``` + +To tell an element to render its children directly with no wrapper element, use `as={React.Fragment}`. + +```jsx +import { Menu } from '@headlessui/react' + +function MyDropdown() { + return ( + + {/* Render no wrapper, instead pass in a button manually. */} + + + + + + {({ active }) => ( + + Account settings + + )} + + {/* ... */} + + + ) +} +``` + +### Component API + +#### Menu + +```jsx + + More + + {/* ... */} + {/* ... */} + + +``` + +##### Props + +| Prop | Type | Default | Description | +| ---- | ------------------- | --------------------------------------- | ----------------------------------------------------- | +| `as` | String \| Component | `React.Fragment` _(no wrapper element_) | The element or component the `Menu` should render as. | + +##### Render prop object + +| Prop | Type | Description | +| ------ | ------- | -------------------------------- | +| `open` | Boolean | Whether or not the menu is open. | + +#### Menu.Button + +```jsx + + {({ open }) => ( + <> + More options + + + )} + +``` + +##### Props + +| Prop | Type | Default | Description | +| ---- | ------------------- | -------- | ------------------------------------------------------------ | +| `as` | String \| Component | `button` | The element or component the `Menu.Button` should render as. | + +##### Render prop object + +| Prop | Type | Description | +| ------ | ------- | -------------------------------- | +| `open` | Boolean | Whether or not the menu is open. | + +#### Menu.Items + +```jsx + + {/* ... */}> + {/* ... */}> + +``` + +##### Props + +| Prop | Type | Default | Description | +| -------- | ------------------- | ------- | --------------------------------------------------------------------------- | +| `as` | String \| Component | `div` | The element or component the `Menu.Items` should render as. | +| `static` | Boolean | `false` | Whether the element should ignore the internally managed open/closed state. | + +##### Render prop object + +| Prop | Type | Description | +| ------ | ------- | -------------------------------- | +| `open` | Boolean | Whether or not the menu is open. | + +#### Menu.Item + +```jsx + + {({ active }) => ( + + Account settings + + )} + +``` + +##### Props + +| Prop | Type | Default | Description | +| ---------- | ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------- | +| `as` | String \| Component | `React.Fragment` _(no wrapper element)_ | The element or component the `Menu.Item` should render as. | +| `disabled` | Boolean | `false` | Whether or not the item should be disabled for keyboard navigation and ARIA purposes. | + +##### Render prop object + +| Prop | Type | Description | +| ---------- | ------- | ---------------------------------------------------------------------------------- | +| `active` | Boolean | Whether or not the item is the active/focused item in the list. | +| `disabled` | Boolean | Whether or not the item is the disabled for keyboard navigation and ARIA purposes. | diff --git a/packages/@headlessui-vue/README.md b/packages/@headlessui-vue/README.md index 6682ca7..a956c52 100644 --- a/packages/@headlessui-vue/README.md +++ b/packages/@headlessui-vue/README.md @@ -49,6 +49,8 @@ This includes things like: We'll be continuing to develop new components on an on-going basis, with a goal of reaching a pretty fleshed out v1.0 by the end of the year. +--- + ## Menu Button (Dropdown) [View complete demo on CodeSandbox](https://codesandbox.io/s/flamboyant-glade-b2jb4?file=/src/App.vue) @@ -69,24 +71,16 @@ The `MenuButton` will automatically open/close the `MenuItems` when clicked, and ```vue