From c85b8d9f1f9638b8c34959c30f1de6ce535de9a9 Mon Sep 17 00:00:00 2001 From: Albert Yu Date: Thu, 7 Nov 2024 14:46:38 +0800 Subject: [PATCH] Update docs --- .../accordion/AccordionIntroduction.js | 59 +++++ .../accordion/AccordionIntroduction.tsx | 59 +++++ .../UnstyledAccordionIntroduction.js | 61 ----- .../UnstyledAccordionIntroduction.tsx | 61 ----- docs/data/components/accordion/accordion.mdx | 50 ++-- .../components/accordion/styles.module.css | 21 +- .../components/collapsible/collapsible.mdx | 30 ++- .../accordion-panel/accordion-panel.json | 2 +- .../accordion-root/accordion-root.json | 2 +- .../app/experiments/accordion-animations.tsx | 23 +- docs/src/app/experiments/accordion.tsx | 220 ------------------ .../app/experiments/collapsible-framer.tsx | 1 + .../src/Accordion/Panel/AccordionPanel.tsx | 4 +- .../src/Accordion/Root/AccordionRoot.tsx | 8 +- 14 files changed, 208 insertions(+), 393 deletions(-) create mode 100644 docs/data/components/accordion/AccordionIntroduction.js create mode 100644 docs/data/components/accordion/AccordionIntroduction.tsx delete mode 100644 docs/data/components/accordion/UnstyledAccordionIntroduction.js delete mode 100644 docs/data/components/accordion/UnstyledAccordionIntroduction.tsx delete mode 100644 docs/src/app/experiments/accordion.tsx diff --git a/docs/data/components/accordion/AccordionIntroduction.js b/docs/data/components/accordion/AccordionIntroduction.js new file mode 100644 index 0000000000..327f651ef6 --- /dev/null +++ b/docs/data/components/accordion/AccordionIntroduction.js @@ -0,0 +1,59 @@ +'use client'; +import * as React from 'react'; +import { Accordion } from '@base_ui/react/Accordion'; +import classes from './styles.module.css'; + +export default function AccordionIntroduction() { + return ( + + + + + Trigger 1 + + + + + This is the contents of Accordion.Panel 1 + + + + + + Trigger 2 + + + + + This is the contents of Accordion.Panel 2 + + + + + + Trigger 3 + + + + + This is the contents of Accordion.Panel 3 + + + + ); +} + +function ExpandMoreIcon(props) { + return ( + + + + ); +} diff --git a/docs/data/components/accordion/AccordionIntroduction.tsx b/docs/data/components/accordion/AccordionIntroduction.tsx new file mode 100644 index 0000000000..e7e23e994d --- /dev/null +++ b/docs/data/components/accordion/AccordionIntroduction.tsx @@ -0,0 +1,59 @@ +'use client'; +import * as React from 'react'; +import { Accordion } from '@base_ui/react/Accordion'; +import classes from './styles.module.css'; + +export default function AccordionIntroduction() { + return ( + + + + + Trigger 1 + + + + + This is the contents of Accordion.Panel 1 + + + + + + Trigger 2 + + + + + This is the contents of Accordion.Panel 2 + + + + + + Trigger 3 + + + + + This is the contents of Accordion.Panel 3 + + + + ); +} + +function ExpandMoreIcon(props: React.SVGProps) { + return ( + + + + ); +} diff --git a/docs/data/components/accordion/UnstyledAccordionIntroduction.js b/docs/data/components/accordion/UnstyledAccordionIntroduction.js deleted file mode 100644 index 378b8c0bad..0000000000 --- a/docs/data/components/accordion/UnstyledAccordionIntroduction.js +++ /dev/null @@ -1,61 +0,0 @@ -'use client'; -import * as React from 'react'; -import { Accordion } from '@base_ui/react/Accordion'; -import classes from './styles.module.css'; - -export default function UnstyledAccordionIntroduction() { - return ( -
- - - - - Trigger 1 - - - - - This is the contents of Accordion.Panel 1 - - - - - - Trigger 2 - - - - - This is the contents of Accordion.Panel 2 - - - - - - Trigger 3 - - - - - This is the contents of Accordion.Panel 3 - - - -
- ); -} - -function ExpandMoreIcon(props) { - return ( - - - - ); -} diff --git a/docs/data/components/accordion/UnstyledAccordionIntroduction.tsx b/docs/data/components/accordion/UnstyledAccordionIntroduction.tsx deleted file mode 100644 index 09f316335f..0000000000 --- a/docs/data/components/accordion/UnstyledAccordionIntroduction.tsx +++ /dev/null @@ -1,61 +0,0 @@ -'use client'; -import * as React from 'react'; -import { Accordion } from '@base_ui/react/Accordion'; -import classes from './styles.module.css'; - -export default function UnstyledAccordionIntroduction() { - return ( -
- - - - - Trigger 1 - - - - - This is the contents of Accordion.Panel 1 - - - - - - Trigger 2 - - - - - This is the contents of Accordion.Panel 2 - - - - - - Trigger 3 - - - - - This is the contents of Accordion.Panel 3 - - - -
- ); -} - -function ExpandMoreIcon(props: React.SVGProps) { - return ( - - - - ); -} diff --git a/docs/data/components/accordion/accordion.mdx b/docs/data/components/accordion/accordion.mdx index 86f5ca9aae..64647277de 100644 --- a/docs/data/components/accordion/accordion.mdx +++ b/docs/data/components/accordion/accordion.mdx @@ -15,7 +15,7 @@ packageName: '@base_ui/react' ## Introduction - + ## Installation @@ -31,7 +31,7 @@ Accordions are implemented using a collection of related components: - `` is a heading (`h3` by default) that wraps the `Trigger` - `` is the element that contains content in a `Item` -```tsx +```jsx @@ -57,7 +57,7 @@ The open state of the accordion is represented an array holding the `value`s of You can optionally specify a custom `value` prop on `Item`: -```tsx +```jsx @@ -78,7 +78,7 @@ You can optionally specify a custom `value` prop on `Item`: When uncontrolled, use the `defaultValue` prop to set the initial state of the accordion: -```tsx +```jsx @@ -115,7 +115,7 @@ When uncontrolled, use the `defaultValue` prop to set the initial state of the a When controlled, pass the `value` and `onValueChange` props to `Accordion.Root`: -```tsx +```jsx const [value, setValue] = React.useState(['a']); return ( @@ -142,7 +142,7 @@ return ( By default, all accordion items can be opened at the same time. Use the `openMultiple` prop to only allow one open item at a time: -```tsx +```jsx {/* subcomponents */} ``` @@ -150,7 +150,7 @@ By default, all accordion items can be opened at the same time. Use the `openMul Use controlled mode to always keep one `Item` open: -```tsx +```jsx const [value, setValue] = React.useState([0]); const handleValueChange = (newValue) => { @@ -168,9 +168,9 @@ return ( ## Horizontal -Use the `orientation` prop to configure a horizontal accordion. In a horizontal accordion, focus will move between `Accordion.Trigger`s with the Right Arrow and Left Arrow keys, instead of Down/Up. +Use the `orientation` prop to configure a horizontal accordion. In a horizontal accordion, focus will move between `Accordion.Trigger`s with the Right Arrow and Left Arrow keys, instead of Down/Up. -```tsx +```jsx {/* subcomponents */} ``` @@ -178,11 +178,21 @@ Use the `orientation` prop to configure a horizontal accordion. In a horizontal Use the `direction` prop to configure a RTL accordion: -```tsx +```jsx {/* subcomponents */} ``` -When a horizontal accordion is set to `direction="rtl"`, keyboard actions are reversed accordingly - Left Arrow moves focus to the next trigger and Right Arrow moves focus to the previous trigger. +When a horizontal accordion is set to `direction="rtl"`, keyboard actions are reversed accordingly - Left Arrow moves focus to the next trigger and Right Arrow moves focus to the previous trigger. + +## Hidden state + +``s are unmounted from the DOM by default when the component is closed. You can use the `keepMounted` prop to to keep them mounted when closed, and instead rely on the `hidden` attribute to hide the content: + +```jsx +{/* accordion items */} +``` + +Alternatively `keepMounted` can be passed to `Accordion.Panel`s directly to enable this for only one `Item` instead of the whole accordion. ## Improving searchability of hidden content @@ -194,16 +204,18 @@ When a horizontal accordion is set to `direction="rtl"`, keyboard actions are re Content hidden by `Accordion.Panel` components can be made accessible only to a browser's find-in-page functionality with the `hiddenUntilFound` prop to improve searchability: -```js -{/* subcomponents */} +```jsx + + {/* accordion items */} + ``` +Be aware that this must be used together with `keepMounted`. + Alternatively `hiddenUntilFound` can be passed to `Accordion.Panel`s directly to enable this for only one `Item` instead of the whole accordion. We recommend using [CSS animations](#css-animations) for animated accordions that use this feature. Currently there is browser bug that does not highlight the found text inside elements that have a [CSS transition](#css-transitions) applied. -This relies on the HTML `hidden="until-found"` attribute which only has [partial browser support](https://caniuse.com/mdn-html_global_attributes_hidden_until-found_value) as of August 2024, but automatically falls back to the default `hidden` state in unsupported browsers. - ## Animations Accordion uses [`Collapsible`](/components/react-collapsible) internally, and can be animated in a [similar way](/components/react-collapsible#animations). @@ -290,13 +302,13 @@ When using CSS transitions, styles for the `Panel` must be applied to three stat ### JavaScript Animations -When using external libraries for animation, for example `framer-motion`, be aware that `Accordion.Item`s hides content using the HTML `hidden` attribute in the closed state, and does not unmount from the DOM. +Use the `keepMounted` prop lets an external library control the mounting, for example `framer-motion`: -```js +```jsx function App() { const [value, setValue] = useState([0]); return ( - + Toggle @@ -304,7 +316,7 @@ function App() { ` is the trigger element, a ` - - - - - - - Trigger 3 - - - - This is the contents of Accordion.Panel 3 - MUI - - - - - - - Trigger 4 - - - - This is the contents of Accordion.Panel 4 - - - - - - - Trigger 5 - - - - This is the contents of Accordion.Panel 5 - - - - -
- -

Controlled

- - - - - - Trigger 1 - - - - This is the contents of Accordion.Panel 1, the value is "one" - - - - - - - Trigger 2 - - - - This is the contents of Accordion.Panel 2, the value is "two" - - - - - - - Trigger 3 - - - - This is the contents of Accordion.Panel 3, the value is "three" - - - - -
- -

Controlled, at least one section must remain open

- - { - if (Array.isArray(newValue) && newValue.length > 0) { - setVal2(newValue); - } - }} - aria-label="Controlled Accordion, one section must remain open" - openMultiple={openMultiple} - > - - - - Trigger 1 - - - - This is the contents of Accordion.Panel 1, the value is "one" - - - - - - - Trigger 2 - - - - This is the contents of Accordion.Panel 2, the value is "two" - - - - - - - Trigger 3 - - - - This is the contents of Accordion.Panel 3, the value is "three" - - - - - ); -} - -function CheckIcon(props: React.SVGProps) { - return ( - - - - ); -} - -export function ExpandMoreIcon(props: React.SVGProps) { - return ( - - - - ); -} diff --git a/docs/src/app/experiments/collapsible-framer.tsx b/docs/src/app/experiments/collapsible-framer.tsx index dbfd17c567..68338968fc 100644 --- a/docs/src/app/experiments/collapsible-framer.tsx +++ b/docs/src/app/experiments/collapsible-framer.tsx @@ -19,6 +19,7 @@ export default function CollapsibleFramer() {