@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/collapsible.md

@@ -0,0 +1,260 @@
+<!-- index: ./index.md -->
+# collapsible
+
+`data-ui="collapsible"` · One region whose content shows or hides.
+
+## Import
+
+```tsx
+import { Collapsible, CollapsibleActions, CollapsibleDefaultsProvider, CollapsibleHeader, CollapsiblePanel, CollapsibleTrigger } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible defaultOpen>
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Endereço de entrega</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Rua das Laranjeiras, 402 — Rio de Janeiro.</CollapsiblePanel>
+</Collapsible>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `header` | h1 to h6, or a div at level="none" | yes |
+| `trigger` | button | yes |
+| `indicator` | span | no |
+| `label` | span | yes |
+| `description` | span | no |
+| `actions` | div, or the element render returns | no |
+| `panel` | div, optionally role="region" | yes |
+| `content` | div | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | Collapsible | Present means the consumer owns the state, for the life of the component. Inside an Accordion the set owns it instead, and an explicit open still wins over both |
+| `defaultOpen` | `boolean` | — | Collapsible | The value an uncontrolled disclosure starts from, read once. A later change to it does not silently become new state |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Collapsible, Accordion, CollapsibleDefaultsProvider | The step the header sits at. The title comes from the type scale and everything geometric from the control scales, so a density changes the rhythm rather than the reading size |
+| `variant` | `'plain' \| 'ruled' \| 'framed'` | plain | Collapsible, CollapsibleDefaultsProvider | plain paints no chrome, ruled draws a hairline above the header so a stack reads as one list, and framed is its own card. An Accordion hands its items the one its own variant maps onto |
+| `indicator` | `'chevron' \| 'plus-minus' \| 'none'` | chevron | Collapsible, Accordion, CollapsibleDefaultsProvider | The mark, drawn from a glyph token. The chevron turns between down and up rather than pointing along the inline axis, so nothing is mirrored for a right-to-left document |
+| `togglePlacement` | `'end' \| 'start'` | end | Collapsible, Accordion, CollapsibleDefaultsProvider | Which side of the words the mark stands on. With it at the start the panel’s content is indented to line up with the title rather than with the mark |
+| `level` | `'none' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6'` | none | Collapsible, CollapsibleDefaultsProvider | The heading element the trigger is wrapped in. none renders a div and writes no heading semantics; an Accordion sets it for a whole set through headingLevel |
+| `mount` | `'active' \| 'lazy' \| 'eager' \| 'until-found'` | eager | Collapsible, Accordion, CollapsibleDefaultsProvider | When the panel’s content exists. The box always does, so aria-controls never names an element that is gone. until-found writes hidden="until-found" and answers beforematch by opening |
+| `truncate` | `boolean` | false | Collapsible, Accordion, CollapsibleDefaultsProvider | Clips the title to one line instead of letting the row grow. The whole string stays in the DOM, which the library decided once for every family |
+| `region` | `boolean` | false | Collapsible | Makes the panel a region landmark. Off by default, because the pattern’s own example warns that a landmark per panel fills the landmark list |
+| `disabled` | `boolean` | false | Collapsible | Reaches the trigger as the native attribute, which is also what stops the press. Unstated rather than false, so the disclosure defers to the Accordion around it |
+| `loading` | `boolean` | false | Collapsible | The panel keeps a line’s height and carries aria-busy; what stands in for the content is Skeleton, composed by the consumer |
+| `value` | `string` | from useId | Collapsible | What this disclosure is called inside an Accordion. It is identity rather than state, and it reaches the DOM as data-value |
+| `description` | `ReactNode` | — | CollapsibleTrigger | A second line under the title, inside the trigger and therefore inside its accessible name |
+| `render` | `(props) => ReactNode` | — | Collapsible, CollapsibleHeader, CollapsibleTrigger, CollapsibleActions, CollapsiblePanel | Substitutes any of the five roots and hands it every attribute — a disclosure can be a section, a panel an article. The heading may become another element, but the trigger has to stay its only child |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the element itself, so focus() and click() are the platform’s and no imperative handle is invented for what it already ships |
+| `useCollapsible()` | `() => CollapsibleContextValue` | — | inside Collapsible | What the parts read: the open state, the identifiers, the mount strategy, whether the group holds this one open, and toggle(next, reason). It throws outside a family rather than rendering a control that does nothing |
+| `CollapsibleDefaultsProvider` | `{ size, variant, indicator, togglePlacement, level, mount, truncate }` | — | a subtree | The seven decisions an application takes once. An Accordion sits between it and the item, and a disclosure that states any of them itself still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `(open: boolean, request: ChangeRequest<boolean>)` | Before the panel moves. The request carries the new value, the value it replaces, the reason (pointer, keyboard, select or programmatic), the originating event, and cancel(), which refuses the move before anything commits. Inside an Accordion it still fires, so a consumer may watch one panel without unpacking the set’s array. |
+| `onClick, onFocus, onKeyDown, on the trigger` | `the element’s own events` | Whenever the button fires them. The family composes with a consumer’s handler rather than replacing it: the consumer’s runs first, and preventDefault() in onClick refuses the toggle as well. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `ruled`, `framed` | `plain` |
+| `indicator` | `chevron`, `plus-minus`, `none` | `chevron` |
+| `togglePlacement` | `end`, `start` | `end` |
+| `level` | `none`, `1`, `2`, `3`, `4`, `5`, `6` | `none` |
+| `mount` | `active`, `lazy`, `eager`, `until-found` | `eager` |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG’s Disclosure (w3.org/WAI/ARIA/apg/patterns/disclosure/), and inside an Accordion it answers the Accordion pattern as well. Its whole keyboard table is the platform’s: the trigger is a button, so Enter and Space toggle without the family binding a key, and Tab reaches it like any other control — the pattern requires every focusable element in an accordion to be in the page tab sequence, which is why nothing here writes tabindex.
+- The trigger carries aria-expanded and aria-controls; the panel carries aria-labelledby pointing back. Both identifiers come from useId, so a server response and the first client render agree. The panel’s box is never removed — mount drops its content, not the box — because aria-controls naming an element that is not there is a reference a screen reader has to make sense of.
+- A closed panel is out of the tab sequence and out of the accessibility tree twice over: the stylesheet with content-visibility, and the binding with inert, so a browser without the property still cannot put focus inside it. Under mount="until-found" neither applies: hidden="until-found" is what lets the browser’s page search reach the text and open the panel, and beforematch is what tells the family to.
+- The heading is real. level renders h1 to h6 and the trigger is its only element, which is what the pattern requires; an accordion sets the level once for a whole set. level="none" writes no heading semantics at all, for a disclosure that belongs to no outline.
+- aria-disabled appears on the trigger only when an Accordion refuses to let this panel close. That is the pattern’s own instruction for a set that requires one panel to stay open, and it leaves the control focusable and announced rather than removing it from the reader’s path.
+- The element is a button and a region rather than details and summary. What that costs is written down: a page with JavaScript disabled cannot open a panel. What it buys is the accordion pattern — a summary cannot be wrapped in a heading — a value the consumer can own, a request that carries a reason, and a panel that animates without interpolate-size.
+- The mark is never the only thing that says the state: aria-expanded says it to a reader, and the indicator turns rather than changing colour, so the high-contrast scheme and forced colours both keep it.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-collapsible-active-background`, `--slotted-collapsible-background`, `--slotted-collapsible-color`, `--slotted-collapsible-description-color`, `--slotted-collapsible-hover-background`, `--slotted-collapsible-hover-color`, `--slotted-collapsible-indicator-color`, `--slotted-collapsible-padding-inline`, `--slotted-collapsible-panel-color`, `--slotted-collapsible-radius`, `--slotted-collapsible-rule-color`, `--slotted-collapsible-surface`, `--slotted-control-font-family`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-letter-spacing`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-line-height-md`, `--slotted-radius-md`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### The three ways it is drawn
+
+plain paints no chrome, ruled puts a hairline above the header so a stack reads as one list, and framed is a card. All three keep the same geometry.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible variant="framed" defaultOpen>
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Formas de pagamento</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Cartão de crédito, boleto e Pix.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### The step the header sits at
+
+The title comes from the type scale, because a header is prose; the row’s height, padding, gap and mark come from the control scales, so a dense page is tighter rather than smaller.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible size="lg" defaultOpen>
+  <CollapsibleHeader>
+    <CollapsibleTrigger description="3 de 12 itens">Resumo</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Entrega prevista para 12 de setembro.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### The mark, and which side it stands on
+
+The chevron turns rather than pointing along the inline axis, so a right-to-left document needs no mirrored artwork; plus-minus is one pair drawn on one grid, and none draws nothing.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible indicator="plus-minus" togglePlacement="start">
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Nota fiscal</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Emitida em 3 de setembro.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### Where it sits in the outline
+
+level renders the heading element itself, so a screen reader’s heading list holds the disclosure at the right depth. none renders a div, for a control that belongs to no outline.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible level="3">
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Condições de devolução</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Trinta dias corridos.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### A summary that stays visible
+
+The second line is inside the trigger and therefore inside the accessible name, which is what the pattern means by a snippet of the hidden content staying visible.
+
+Excerpt — not a complete module
+
+```tsx
+<CollapsibleTrigger description="2 regras ativas">Regras de frete</CollapsibleTrigger>;
+```
+
+### A control beside the heading
+
+It is a sibling of the heading rather than a child, because the pattern requires the button to be the only element inside it — and a control inside a button is invalid besides.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible variant="framed" defaultOpen>
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Regras de frete</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsibleActions>
+    <Toolbar aria-label="Ações da regra" size="sm">
+      <Button size="sm" variant="ghost">
+        Editar
+      </Button>
+    </Toolbar>
+  </CollapsibleActions>
+  <CollapsiblePanel>Frete grátis acima de R$ 250,00.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### When the content exists
+
+eager builds it up front so the panel can transition closed, lazy builds it on the first open, active drops it each time, and until-found lets the browser’s own page search open the panel.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible mount="until-found">
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Histórico de entregas</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Entregue em 2 de setembro por Ana Ribeiro.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### Every state the family paints
+
+Hover lays a wash under the row and press goes one step further; disabled answers neither, because the browser has already taken the control out of action; loading holds the box open and says so.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible loading defaultOpen mount="lazy">
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Histórico de entregas</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>
+    <Skeleton shape="text" />
+  </CollapsiblePanel>
+</Collapsible>;
+```
+
+### Content the family did not choose
+
+A long title grows the row instead of pushing the mark off the line, truncate clips it to one line with the whole string still in the DOM, and a title in another script reads its own way.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible truncate>
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Condições de devolução para pedidos internacionais</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>Trinta dias corridos.</CollapsiblePanel>
+</Collapsible>;
+```
+
+### Setting it once, and reaching past it
+
+The provider carries the seven decisions an application takes once, render substitutes every root, and a disclosure nests inside another’s panel without the outer one opening it.
+
+Excerpt — not a complete module
+
+```tsx
+<CollapsibleDefaultsProvider variant="framed" size="sm">
+  <Collapsible>…</Collapsible>
+</CollapsibleDefaultsProvider>;
+```
+
+### The pattern’s table, and which device asked
+
+Enter and Space toggle because the trigger is a button; Tab reaches it like any other control, because the pattern keeps every disclosure in the page tab sequence.
+
+Excerpt — not a complete module
+
+```tsx
+<Collapsible onOpenChange={(open, request) => report(request.reason)}>
+  <CollapsibleHeader>
+    <CollapsibleTrigger>Com o ponteiro, depois com o teclado</CollapsibleTrigger>
+  </CollapsibleHeader>
+  <CollapsiblePanel>A razão muda com o dispositivo.</CollapsiblePanel>
+</Collapsible>;
+```