Update docs

mj12albert · Nov 14, 2024 · 169ba04 · 169ba04
1 parent 3a2fd7e
commit 169ba04
Show file tree

Hide file tree

Showing 14 changed files with 208 additions and 393 deletions.
diff --git a/docs/data/components/accordion/AccordionIntroduction.js 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 (
+    <Accordion.Root className={classes.root} aria-label="Base UI Accordion">
+      <Accordion.Item className={classes.item}>
+        <Accordion.Header className={classes.header}>
+          <Accordion.Trigger className={classes.trigger}>
+            Trigger 1
+            <ExpandMoreIcon />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel className={classes.panel}>
+          This is the contents of Accordion.Panel 1
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item className={classes.item}>
+        <Accordion.Header className={classes.header}>
+          <Accordion.Trigger className={classes.trigger}>
+            Trigger 2
+            <ExpandMoreIcon />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel className={classes.panel}>
+          This is the contents of Accordion.Panel 2
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item className={classes.item}>
+        <Accordion.Header className={classes.header}>
+          <Accordion.Trigger className={classes.trigger}>
+            Trigger 3
+            <ExpandMoreIcon />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel className={classes.panel}>
+          This is the contents of Accordion.Panel 3
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}
+
+function ExpandMoreIcon(props) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      className={classes.icon}
+      {...props}
+    >
+      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
+    </svg>
+  );
+}
diff --git a/docs/data/components/accordion/AccordionIntroduction.tsx 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 (
+    <Accordion.Root className={classes.root} aria-label="Base UI Accordion">
+      <Accordion.Item className={classes.item}>
+        <Accordion.Header className={classes.header}>
+          <Accordion.Trigger className={classes.trigger}>
+            Trigger 1
+            <ExpandMoreIcon />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel className={classes.panel}>
+          This is the contents of Accordion.Panel 1
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item className={classes.item}>
+        <Accordion.Header className={classes.header}>
+          <Accordion.Trigger className={classes.trigger}>
+            Trigger 2
+            <ExpandMoreIcon />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel className={classes.panel}>
+          This is the contents of Accordion.Panel 2
+        </Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item className={classes.item}>
+        <Accordion.Header className={classes.header}>
+          <Accordion.Trigger className={classes.trigger}>
+            Trigger 3
+            <ExpandMoreIcon />
+          </Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel className={classes.panel}>
+          This is the contents of Accordion.Panel 3
+        </Accordion.Panel>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}
+
+function ExpandMoreIcon(props: React.SVGProps<SVGSVGElement>) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      className={classes.icon}
+      {...props}
+    >
+      <path d="M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z" fill="currentColor" />
+    </svg>
+  );
+}
diff --git a/docs/data/components/accordion/UnstyledAccordionIntroduction.js b/docs/data/components/accordion/UnstyledAccordionIntroduction.js
diff --git a/docs/data/components/accordion/UnstyledAccordionIntroduction.tsx b/docs/data/components/accordion/UnstyledAccordionIntroduction.tsx
diff --git a/docs/data/components/accordion/accordion.mdx b/docs/data/components/accordion/accordion.mdx
@@ -15,7 +15,7 @@ packageName: '@base_ui/react'
 
 ## Introduction
 
-<Demo demo="UnstyledAccordionIntroduction" defaultCodeOpen="false" bg="gradient" />
+<Demo demo="AccordionIntroduction" defaultCodeOpen="false" bg="gradient" />
 
 ## Installation
 
@@ -31,7 +31,7 @@ Accordions are implemented using a collection of related components:
 - `<Accordion.Header />` is a heading (`h3` by default) that wraps the `Trigger`
 - `<Accordion.Panel />` is the element that contains content in a `Item`
 
-```tsx
+```jsx
 <Accordion.Root>
   <Accordion.Item>
     <Accordion.Header>
@@ -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
 <Accordion.Root>
   <Accordion.Item value="one">
     <Accordion.Header>
@@ -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
 <Accordion.Root defaultValue={[0]}>
   <Accordion.Item {/* `value={0}` by default */}>
     <Accordion.Header>
@@ -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,15 +142,15 @@ 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
 <Accordion.Root openMultiple={false}>{/* subcomponents */}</Accordion.Root>
 ```
 
 ### At least one `Item` remains open
 
 Use controlled mode to always keep one `Item` open:
 
-```tsx
+```jsx
 const [value, setValue] = React.useState([0]);
 
 const handleValueChange = (newValue) => {
@@ -168,21 +168,31 @@ return (
 
 ## Horizontal
 
-Use the `orientation` prop to configure a horizontal accordion. In a horizontal accordion, focus will move between `Accordion.Trigger`s with the <kbd class="key">Right Arrow</kbd> and <kbd class="key">Left Arrow</kbd> 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 <kbd>Right Arrow</kbd> and <kbd>Left Arrow</kbd> keys, instead of Down/Up.
 
-```tsx
+```jsx
 <Accordion.Root orientation="horizontal">{/* subcomponents */}</Accordion.Root>
 ```
 
 ## RTL
 
 Use the `direction` prop to configure a RTL accordion:
 
-```tsx
+```jsx
 <Accordion.Root direction="rtl">{/* subcomponents */}</Accordion.Root>
 ```
 
-When a horizontal accordion is set to `direction="rtl"`, keyboard actions are reversed accordingly - <kbd class="key">Left Arrow</kbd> moves focus to the next trigger and <kbd class="key">Right Arrow</kbd> moves focus to the previous trigger.
+When a horizontal accordion is set to `direction="rtl"`, keyboard actions are reversed accordingly - <kbd>Left Arrow</kbd> moves focus to the next trigger and <kbd>Right Arrow</kbd> moves focus to the previous trigger.
+
+## Hidden state
+
+`<Accordion.Panel />`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.Root keepMounted>{/* accordion items */}</Accordion.Root>
+```
+
+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
-<Accordion.Root hiddenUntilFound>{/* subcomponents */}</Accordion.Root>
+```jsx
+<Accordion.Root hiddenUntilFound keepMounted>
+  {/* accordion items */}
+</Accordion.Root>
 ```
 
+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,21 +302,21 @@ 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 (
-    <Accordion.Root value={value} onValueChange={setValue}>
+    <Accordion.Root value={value} onValueChange={setValue} keepMounted>
       <Accordion.Item>
         <Accordion.Header>
           <Accordion.Trigger>Toggle</Accordion.Trigger>
         </Accordion.Header>
         <Accordion.Panel
           render={
             <motion.div
-              key="AccordionPanel"
+              key="MyAnimatedAccordionPanel"
               initial={false}
               animate={open ? 'open' : 'closed'}
               exit={!open ? 'open' : 'closed'}