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

package/dist/docs/table-of-contents.md

@@ -0,0 +1,301 @@
+<!-- index: ./index.md -->
+# table-of-contents
+
+`data-ui="table-of-contents"` · Links to page headings with the current one.
+
+## Import
+
+```tsx
+import { TableOfContents, TableOfContentsItem, TableOfContentsLink, TableOfContentsGroup, TableOfContentsDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents items={sections} label="Nesta página" />;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | nav, or a div under landmark={false}, or the element render returns | yes |
+| `label` | div, or a span inside the trigger | no |
+| `trigger` | button | no |
+| `current` | span | no |
+| `indicator` | span | no |
+| `panel` | div | yes |
+| `list` | ol | yes |
+| `item` | li, or the element render returns | yes |
+| `link` | a, or the element render returns | yes |
+| `group` | ol, or the element render returns | no |
+| `marker` | div | yes |
+| `skeleton` | li | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `TableOfContentsItemData[]` | — | TableOfContents | The list as data: { id, label, children? }. children written as parts win over it |
+| `source` | `RefObject<HTMLElement> \| HTMLElement` | — | TableOfContents | A region whose headings make the list, read after mount and again when its subtree changes. A heading without an id is given one from its text |
+| `levels` | `[number, number]` | 2,3 | TableOfContents | The lowest and highest heading level source keeps, inclusive |
+| `exclude` | `string` | — | TableOfContents | A selector: a heading matching it, or inside an element matching it, is left out of source |
+| `scroller` | `RefObject<HTMLElement> \| HTMLElement \| null` | — | TableOfContents | The element that scrolls. Unset, it is the first target’s nearest scrolling ancestor; null is the viewport |
+| `offset` | `number` | 0 | TableOfContents | CSS pixels added under the page’s chrome, for the reading line and for where a target lands. The chrome itself is read from --slotted-page-sticky-top |
+| `value` | `string \| null` | — | TableOfContents | The current target’s id. Present means the consumer owns it for the life of the component |
+| `defaultValue` | `string \| null` | null | TableOfContents | What an uncontrolled list starts from, read once |
+| `open` | `boolean` | — | TableOfContents | Whether the collapsed list is shown. Present means the consumer owns it |
+| `defaultOpen` | `boolean` | false | TableOfContents | What an uncontrolled collapsed list starts from |
+| `layout` | `'vertical' \| 'horizontal' \| 'collapsed'` | vertical | TableOfContents | The column, the bar, or the trigger with the list under it. The consumer’s breakpoint decides; the family never decides by width |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | TableOfContents | The row step, on the control scale: height, type and inset |
+| `sticky` | `boolean` | false | TableOfContents | Pins the column under the page’s chrome and gives it the rest of the viewport; the panel scrolls. Ignored in the collapsed layout |
+| `history` | `'push' \| 'replace' \| 'none'` | push | TableOfContents | What a press does to the URL: pushState, replaceState, or nothing. scrollTo() never writes it |
+| `numbered` | `boolean` | false | TableOfContents | Counters per level before each link |
+| `landmark` | `boolean` | true | TableOfContents | Whether the root is a nav with a name. false renders a div, for a list inside a landmark that already has one |
+| `label` | `ReactNode` | — | TableOfContents | The list’s title, rendered as the label part and used as the landmark’s name. In the collapsed layout it is the trigger’s fixed text |
+| `loading` | `boolean` | false | TableOfContents | Four rows of skeleton in the list’s place, and aria-busy on the root |
+| `messages` | `Partial<TableOfContentsMessages>` | — | TableOfContents | Words laid over the language in force: the landmark’s name when there is no label, and the collapsed trigger’s fixed text (navigation) |
+| `value` | `string` | — | TableOfContentsItem | The target’s id, without the hash. The link inside takes its href from it |
+| `href` | `string` | #<value> | TableOfContentsLink | The fragment. Defaults to the item’s value; a different one is followed as written |
+| `TableOfContentsItem, TableOfContentsLink, TableOfContentsGroup` | `parts` | — | children | The list written by hand: an item per target, a link inside it, a group for its children. The root draws the label, the panel, the list and the marker around them |
+| `render` | `(props) => ReactNode` | — | TableOfContents, TableOfContentsItem, TableOfContentsLink, TableOfContentsGroup | Substitutes the element and hands it every attribute the family was going to write. The trigger, the panel and the marker are fixed: the keyboard, aria-controls and the measurement are theirs |
+| `ref` | `Ref<TableOfContentsHandle>` | — | TableOfContents | focus() lands on the first link or the trigger; refresh() reads the headings and measures again; scrollTo(id) lands on a target with the reason programmatic and leaves the URL; root is the element |
+| `TableOfContentsDefaultsProvider` | `{ layout, size, sticky, history, numbered, landmark, levels, offset }` | — | a subtree | The decisions an application takes once. A list that states any of them itself still wins |
+| `aria-label, aria-labelledby, id, className, data-*` | `the element’s own attributes` | — | every part | Every native attribute reaches its element unchanged. A name the consumer writes on the root wins over the label and the messages |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: string \| null, request: ChangeRequest<string \| null>)` | Before the current target moves. The request carries the new id, the id it replaces, the reason — scroll from the observer, pointer or keyboard from a press, programmatic from scrollTo() — the originating event when there is one, and cancel(). A refused scroll request keeps the value; a refused press still scrolls, because the navigation is the anchor’s. |
+| `onOpenChange` | `(open: boolean, request: ChangeRequest<boolean>)` | Before the collapsed list opens or closes. The reason is pointer or keyboard on the trigger, select for a link chosen inside, escape and outsidePress from the layer, programmatic from a consumer. |
+| `onClick, onKeyDown, onFocus, onBlur` | `the element’s own events` | Whenever the link or the root fires them. The consumer’s handler runs first and always runs; preventDefault() in a link’s onClick leaves the press to the platform. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `layout` | `vertical`, `horizontal`, `collapsed` | `vertical` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `sticky` | `false`, `true` | `false` |
+| `history` | `push`, `replace`, `none` | `push` |
+| `numbered` | `false`, `true` | `false` |
+| `landmark` | `true`, `false` | `true` |
+| `levels` | `2,3` | `2,3` |
+| `offset` | `0` | `0` |
+
+## Rules
+
+- The APG has no pattern for a table of contents (w3.org/WAI/ARIA/apg/patterns/, read 2026-09-16). What applies is a navigation landmark with a name, real links, and aria-current="location" from ARIA 1.2 — the token for the current place within a context — on exactly one link at a time.
+- The platform supplies the landmark, the list of N items and the links; the family adds the name, the current token, and the arrow keys the Disclosure Navigation Menu example lists as optional, for the keyboard user who runs no screen reader. Every link stays in the tab sequence: nothing rolls.
+- After a press, focus moves to the target with tabindex="-1" lent to it until it blurs, so a screen reader continues reading from the section and not from the list. A fragment navigation on its own moves only the sequential focus starting point.
+- The collapsed trigger is a native button with aria-expanded and aria-controls; ArrowDown opens the list onto its first link, Escape closes it back onto the button, and a press outside closes it through the same dismissable layer every overlay in the library uses.
+- The scroll is smooth unless the reader asked for reduced motion, read from prefers-reduced-motion; the marker’s travel and the chevron’s turn read the motion scale, which the theme collapses under the same query.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--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-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-sm`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-sm`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-shadow-md`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-5`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-table-of-contents-color`, `--slotted-table-of-contents-color-current`, `--slotted-table-of-contents-color-hover`, `--slotted-table-of-contents-indent`, `--slotted-table-of-contents-marker-color`, `--slotted-table-of-contents-track-color`, `--slotted-table-of-contents-track-width`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-text`, `--slotted-z-index-popover`
+
+## Examples
+
+### Every part, named
+
+The label above, the track on the list’s start edge, the marker on the current row, the group indented under its parent. Hover a link: the ink darkens and nothing moves. The current link is said twice, by its ink and by the marker, and never by the marker alone.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents label="Nesta página">
+  <TableOfContentsItem value="dados-gerais">
+    <TableOfContentsLink>Dados gerais</TableOfContentsLink>
+  </TableOfContentsItem>
+  <TableOfContentsItem value="enderecos">
+    <TableOfContentsLink>Endereços</TableOfContentsLink>
+    <TableOfContentsGroup>
+      <TableOfContentsItem value="faturacao">
+        <TableOfContentsLink>Faturação</TableOfContentsLink>
+      </TableOfContentsItem>
+    </TableOfContentsGroup>
+  </TableOfContentsItem>
+</TableOfContents>;
+```
+
+### Read from the document’s own headings
+
+The returns policy is prose; nobody wrote a list for it. source points at the article, the family reads its h2 and h3 after mount, writes an id on each heading that has none — “Prazos de devolução” becomes #prazos-de-devolucao — and rebuilds the list when the article changes.
+
+Excerpt — not a complete module
+
+```tsx
+const article = useRef<HTMLElement>(null);
+
+<TableOfContents label="Neste artigo" levels={[2, 3]} source={article} />;
+<div ref={article}>
+  <Prose>…</Prose>
+</div>;
+```
+
+### The list as data, from a pipeline
+
+A Markdown pipeline hands over a flat array with a level on each heading. nestOutline from @slotted/core/outline folds it into the tree items takes, and the same list renders on the server, which source cannot.
+
+Excerpt — not a complete module
+
+```tsx
+import { nestOutline } from '@slotted/core/outline';
+
+const items = nestOutline(toc); // [{ id, label, level }]
+
+<TableOfContents items={items} label="Neste artigo" />;
+```
+
+### A column that stays while the document scrolls
+
+sticky pins the list under the page’s chrome and gives it the rest of the viewport; with more links than fit, the panel scrolls and keeps the current link in view without moving the page. Scroll the document past the tenth section and watch the column follow.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents items={sections} label="Nesta página" sticky />;
+```
+
+### The bar under a page title
+
+In page-header’s tabs slot, the first level only, one line that scrolls sideways rather than squeezing its labels — the fade at the edge says there is more. Scroll the page: the header collapses, the bar stays, and the marker follows the section under it.
+
+Excerpt — not a complete module
+
+```tsx
+<PageHeaderTabs>
+  <TableOfContents items={sections} layout="horizontal" />
+</PageHeaderTabs>;
+```
+
+### A phone’s bar
+
+One row: the title, the current section, a chevron. Press it and the list opens in a layer under it; choose a link and it closes, Escape closes it back onto the button, a press outside closes it. The layout is chosen by the consumer’s breakpoint, not by width — the sidebar column is narrower than this bar.
+
+Excerpt — not a complete module
+
+```tsx
+const phone = useMediaQuery('(max-width: 640px)');
+
+<TableOfContents items={sections} layout={phone ? 'collapsed' : 'vertical'} />;
+```
+
+### Clauses, numbered
+
+A supplier contract is read by clause number. numbered draws counters per level — 2., 2.1, 2.2 — in tabular figures, so a column of numbers lines up and a reader on the phone with legal can say “cláusula 3.2” and mean the same line.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents items={clauses} label="Cláusulas" numbered />;
+```
+
+### Three steps on the control scale
+
+Each step is the control’s height, type and inset at that step, so a list at sm reads beside a small toolbar and one at lg beside a page title. The density switch in the toolbar moves all three.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents items={sections} size="sm" />;
+```
+
+### Every state the contract declares
+
+Hover darkens the muted ink toward the page’s text; press goes all the way; the current link takes the accent ink and one step of weight; focus draws the ring inside the row so it never crosses the track. Nothing shifts by a pixel between any two of them.
+
+Excerpt — not a complete module
+
+```tsx
+const [section, setSection] = useState<string | null>('enderecos');
+
+<TableOfContents items={sections} onValueChange={setSection} value={section} />;
+```
+
+### Content the family did not choose
+
+A heading of eleven words wraps to three lines and stays whole; an order reference with no space breaks inside itself rather than widening the column; an Arabic heading reads from the right. The bar cuts nothing either: it scrolls.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents
+  items={[
+    { id: 'ambito', label: 'Âmbito de aplicação e definições utilizadas neste documento' },
+    { id: 'ref', label: 'REF-2026-09-16-DEVOLUCAO-INDUSTRIAL-000482915' },
+  ]}
+/>;
+```
+
+### While the document is still arriving
+
+A record loaded from the server has no sections yet. loading draws four rows of skeleton with an item’s geometry, so the column keeps its width; a list with no entries and nothing loading draws nothing at all.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents items={sections ?? []} loading={sections === undefined} />;
+```
+
+### What a press does to the URL
+
+push writes a history entry per section, so Back retraces the reading; replace keeps one entry and updates the hash, which is what a record page wants; none leaves the URL alone. The scroll and the focus are the same in all three; only the address bar differs.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents history="replace" items={sections} />;
+```
+
+### Decided once for the application
+
+The provider sets the levels a document outlines, whether the column pins, and what a press does to the URL — and every list under it reads them. The landmark’s name comes from the language in force. A list that states an axis itself still wins: the second one here is lg under a provider that said sm.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContentsDefaultsProvider history="replace" levels={[2, 4]} size="sm" sticky>
+  <App />
+</TableOfContentsDefaultsProvider>;
+```
+
+### Beside a resizable column, and with its own link
+
+The list sits in a region a splitter sizes; the document scrolls in the body beside it, and the family finds that scroller from the first section without being told. The link is the consumer’s to shape: render hands every attribute to whatever element they return.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContentsLink render={(props) => <RouterLink {...props} />}>
+  Dados gerais
+</TableOfContentsLink>;
+```
+
+### Every key the contract lists
+
+Tab reaches each link in order. ArrowDown and ArrowUp walk them, Home and End jump to the ends, and in the bar ArrowRight and ArrowLeft do the same along the line. Enter follows the link and lands focus on the section, so the next Tab continues inside it.
+
+Excerpt — not a complete module
+
+```tsx
+const list = useRef<TableOfContentsHandle>(null);
+
+<TableOfContents items={sections} ref={list} />;
+// a page shortcut: list.current?.focus()
+```
+
+### What a screen reader hears
+
+A navigation landmark named “Nesta página”, a list of six items, and one link announced as “current location”. After Enter the reader hears the section’s heading, because focus moved there. The collapsed trigger announces expanded and collapsed, and Escape returns to it.
+
+Excerpt — not a complete module
+
+```tsx
+<TableOfContents items={sections} label="Nesta página" />;
+// <nav aria-labelledby="…-label"> … <a aria-current="location">
+```