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

package/docs/table-of-contents.md

@@ -0,0 +1,289 @@
+<!-- index: ./index.md -->
+# table-of-contents
+
+`data-ui="table-of-contents"` · Links to page headings with the current one.
+
+## Import
+
+```ts
+import { provideTableOfContentsDefaults, SlTableOfContents, SlTableOfContentsLabel, SlTableOfContentsLink } from '@slotted/angular/table-of-contents';
+```
+
+Selector: `[slTableOfContents]` · exportAs: `slTableOfContents`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<nav slTableOfContents [items]="sections" label="Nesta página"></nav>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own nav, or div, with slTableOfContents on it | 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 | yes |
+| `link` | a | yes |
+| `group` | ol | no |
+| `marker` | div | yes |
+| `skeleton` | li | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `TableOfContentsItemData[]` | — | slTableOfContents | The list as data: { id, label, children? }. Wins over source |
+| `source` | `ElementRef<HTMLElement> \| HTMLElement` | — | slTableOfContents | A region whose headings make the list, read after the view is built and again when its subtree changes. A heading without an id is given one from its text |
+| `levels` | `[number, number]` | 2,3 | slTableOfContents | The lowest and highest heading level source keeps, inclusive |
+| `exclude` | `string` | — | slTableOfContents | A selector: a heading matching it, or inside an element matching it, is left out of source |
+| `scroller` | `ElementRef<HTMLElement> \| HTMLElement \| null` | — | slTableOfContents | The element that scrolls. Unset, it is the first target’s nearest scrolling ancestor; null is the viewport |
+| `offset` | `number` | 0 | slTableOfContents | 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` | `model<string \| null>` | null | slTableOfContents | The current target’s id. Two-way: the list asks through valueChangeRequest and moves it once the request is accepted |
+| `open` | `model<boolean>` | false | slTableOfContents | Whether the collapsed list is shown. Two-way, through openChangeRequest |
+| `layout` | `'vertical' \| 'horizontal' \| 'collapsed'` | vertical | slTableOfContents | 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 | slTableOfContents | The row step, on the control scale: height, type and inset |
+| `sticky` | `boolean` | false | slTableOfContents | 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 | slTableOfContents | What a press does to the URL: pushState, replaceState, or nothing. scrollTo() never writes it |
+| `numbered` | `boolean` | false | slTableOfContents | Counters per level before each link |
+| `landmark` | `boolean` | true | slTableOfContents | Whether the host takes the landmark’s name. The element is the consumer’s: a nav is the landmark, a div inside one that already has a name is not |
+| `label` | `string` | — | slTableOfContents | The list’s title, rendered as the label part and used as the landmark’s name. A slTableOfContentsLabel template wins over it. In the collapsed layout it is the trigger’s fixed text |
+| `loading` | `boolean` | false | slTableOfContents | Four rows of skeleton in the list’s place, and aria-busy on the host |
+| `messages` | `Partial<TableOfContentsMessages>` | — | slTableOfContents | Words laid over the language in force: the landmark’s name when there is no label, and the collapsed trigger’s fixed text (navigation) |
+| `slTableOfContentsLink` | `ng-template, let-entry let-current="current"` | — | a child of the host | The content of every link, handed the entry and whether it is current. Without one the link shows the entry’s label |
+| `slTableOfContentsLabel` | `ng-template` | — | a child of the host | The list’s title as a template, for a title with a mark or a count in it |
+| `exportAs slTableOfContents` | `SlTableOfContents` | — | the host | 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 |
+| `provideTableOfContentsDefaults` | `{ layout, size, sticky, history, numbered, landmark, levels, offset }` | — | an injector | The decisions an application takes once. A list that states any of them itself still wins |
+| `aria-label, aria-labelledby, id, class` | `the host’s own attributes` | — | the host | Every attribute written on the element stays. A name the consumer writes wins over the label and the messages, read through HostAttributeToken before the family writes its own |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChangeRequest` | `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. [(value)] moves after the request is accepted. |
+| `openChangeRequest` | `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. [(open)] moves after the request is accepted. |
+| `valueChange, openChange` | `string \| null; boolean` | After each model moves: the two-way halves of [(value)] and [(open)], for a template that binds one directly. |
+
+## 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
+
+```html
+<nav slTableOfContents [items]="sections" [(value)]="section">
+  <ng-template slTableOfContentsLabel>Nesta página</ng-template>
+</nav>
+```
+
+### 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 the view is built, 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
+
+```html
+<nav slTableOfContents label="Neste artigo" [levels]="[2, 3]" [source]="article"></nav>
+<div #article slProse>…</div>
+```
+
+### The list as data, from a pipeline
+
+A Markdown pipeline hands over a flat array with a level on each heading. nestOutline from the core outline module folds it into the tree items takes, and the same list renders on the server, which source cannot.
+
+Excerpt — not a complete module
+
+```ts
+import { nestOutline } from '@slotted/core/outline';
+
+const items = nestOutline(toc); // [{ id, label, level }]
+```
+
+### 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
+
+```html
+<nav slTableOfContents [items]="sections" label="Nesta página" sticky></nav>
+```
+
+### 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
+
+```html
+<div slPageHeaderTabs>
+  <nav slTableOfContents [items]="sections" layout="horizontal"></nav>
+</div>
+```
+
+### 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
+
+```html
+<nav
+  slTableOfContents
+  [items]="sections"
+  label="Nesta página"
+  [layout]="phone() ? 'collapsed' : 'vertical'"
+></nav>
+```
+
+### 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
+
+```html
+<nav slTableOfContents [items]="clauses" label="Cláusulas" numbered></nav>
+```
+
+### 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
+
+```html
+<nav slTableOfContents [items]="sections" size="sm"></nav>
+```
+
+### 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
+
+```html
+<nav slTableOfContents [items]="sections" [(value)]="section"></nav>
+```
+
+### 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
+
+```ts
+const 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
+
+```html
+<nav slTableOfContents [items]="sections() ?? []" [loading]="!sections()"></nav>
+```
+
+### 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
+
+```html
+<nav slTableOfContents [items]="sections" history="replace"></nav>
+```
+
+### 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
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideTableOfContentsDefaults({
+      history: 'replace',
+      levels: [2, 4],
+      size: 'sm',
+      sticky: true,
+    }),
+  ],
+});
+```
+
+### 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. Each link’s content is the consumer’s to shape: the template is handed the entry and whether it is current.
+
+Excerpt — not a complete module
+
+```html
+<nav slTableOfContents [items]="sections">
+  <ng-template slTableOfContentsLink let-entry let-current="current">
+    <span slText [weight]="current ? 'semibold' : 'regular'">{{ entry.label }}</span>
+  </ng-template>
+</nav>
+```
+
+### 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
+
+```html
+<nav slTableOfContents #list="slTableOfContents" [items]="sections"></nav>
+<button slButton (click)="list.focus()">Focar o índice</button>
+```
+
+### 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
+
+```html
+<nav slTableOfContents [items]="sections" label="Nesta página"></nav>
+<!-- <nav aria-labelledby="…-label"> … <a aria-current="location"> -->
+```