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

package/docs/table-of-contents.json

@@ -0,0 +1,553 @@
+{
+  "family": "table-of-contents",
+  "ui": "table-of-contents",
+  "binding": "angular",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Links to page headings with the current one."
+  },
+  "axes": {
+    "layout": [
+      "vertical",
+      "horizontal",
+      "collapsed"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "sticky": [
+      false,
+      true
+    ],
+    "history": [
+      "push",
+      "replace",
+      "none"
+    ],
+    "numbered": [
+      false,
+      true
+    ],
+    "landmark": [
+      true,
+      false
+    ],
+    "levels": [
+      [
+        2,
+        3
+      ]
+    ],
+    "offset": [
+      0
+    ]
+  },
+  "members": {
+    "tableOfContents": {
+      "nativeElement": "nav",
+      "defaults": {
+        "layout": "vertical",
+        "size": "md",
+        "sticky": false,
+        "history": "push",
+        "numbered": false,
+        "landmark": true,
+        "levels": [
+          2,
+          3
+        ],
+        "offset": 0
+      },
+      "capabilities": [
+        "current",
+        "open",
+        "size",
+        "appearance",
+        "loading",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "current",
+        "open",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "label",
+        "trigger",
+        "current",
+        "indicator",
+        "panel",
+        "list",
+        "item",
+        "link",
+        "group",
+        "marker",
+        "skeleton"
+      ],
+      "defaultsReason": "Axis defaults only. The uncontrolled starting values are the state models' own uncontrolled names and exist in React alone; Angular ships one model() for each of value and open"
+    }
+  },
+  "docs": {
+    "tableOfContents": {
+      "imports": {
+        "source": "import { provideTableOfContentsDefaults, SlTableOfContents, SlTableOfContentsLabel, SlTableOfContentsLink } from '@slotted/angular/table-of-contents';",
+        "selector": "[slTableOfContents]",
+        "exportAs": "slTableOfContents"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the consumer’s own nav, or div, with slTableOfContents on it",
+          "required": true,
+          "purpose": "The landmark. It carries data-ui=\"table-of-contents\", data-layout, data-size, and data-sticky, data-numbered, data-open, data-loading and data-empty while each holds. Named by aria-labelledby when there is a label and by aria-label from the messages when there is not; a name written on the element wins."
+        },
+        {
+          "part": "label",
+          "element": "div, or a span inside the trigger",
+          "required": false,
+          "purpose": "The list’s title, from the label input or the slTableOfContentsLabel template. Outside the collapsed layout it stands above the list and names the landmark; inside it, it is the trigger’s fixed text."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": false,
+          "purpose": "The collapsed layout’s button: aria-expanded, aria-controls naming the panel, Enter and Space from the platform, ArrowDown opening the list onto its first link."
+        },
+        {
+          "part": "current",
+          "element": "span",
+          "required": false,
+          "purpose": "Inside the trigger: the current link’s text, cut at the end when the row is too narrow, so a reader on a phone knows where they are without opening the list."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The trigger’s chevron: the chevron-down Glyph element in an icon box, turned half a turn while open."
+        },
+        {
+          "part": "panel",
+          "element": "div",
+          "required": true,
+          "purpose": "The region holding the list: the scrolling body of a sticky column, the inline scroller of the bar, the layer under the trigger when collapsed. It carries the id aria-controls names and, in the bar, data-overflow for the fade."
+        },
+        {
+          "part": "list",
+          "element": "ol",
+          "required": true,
+          "purpose": "The first level. An ordered list because the order is the document’s; the track stands on its start edge in the column, and numbered draws counters on it."
+        },
+        {
+          "part": "item",
+          "element": "li",
+          "required": true,
+          "purpose": "One entry, with data-depth from 1, data-value, and data-current while its link is current — so a theme may paint the row and not only the words."
+        },
+        {
+          "part": "link",
+          "element": "a",
+          "required": true,
+          "purpose": "A real anchor to the fragment. aria-current=\"location\" and data-current while current. Its content is the entry’s label, or the slTableOfContentsLink template; a modifier click is left to the platform."
+        },
+        {
+          "part": "group",
+          "element": "ol",
+          "required": false,
+          "purpose": "An item’s children, indented one --slotted-table-of-contents-indent per level. Not shown in the horizontal layout."
+        },
+        {
+          "part": "marker",
+          "element": "div",
+          "required": true,
+          "purpose": "The segment that slides along the track to the current link, aria-hidden and positioned by the family from a measurement. Zero size while nothing is current."
+        },
+        {
+          "part": "skeleton",
+          "element": "li",
+          "required": false,
+          "purpose": "A row with an item’s geometry whose text is a skeleton bar; four of them while loading."
+        }
+      ],
+      "api": [
+        {
+          "name": "items",
+          "type": "TableOfContentsItemData[]",
+          "defaultValue": "—",
+          "appliesTo": "slTableOfContents",
+          "description": "The list as data: { id, label, children? }. Wins over source"
+        },
+        {
+          "name": "source",
+          "type": "ElementRef<HTMLElement> | HTMLElement",
+          "defaultValue": "—",
+          "appliesTo": "slTableOfContents",
+          "description": "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"
+        },
+        {
+          "name": "levels",
+          "type": "[number, number]",
+          "defaultValue": "2,3",
+          "appliesTo": "slTableOfContents",
+          "description": "The lowest and highest heading level source keeps, inclusive"
+        },
+        {
+          "name": "exclude",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slTableOfContents",
+          "description": "A selector: a heading matching it, or inside an element matching it, is left out of source"
+        },
+        {
+          "name": "scroller",
+          "type": "ElementRef<HTMLElement> | HTMLElement | null",
+          "defaultValue": "—",
+          "appliesTo": "slTableOfContents",
+          "description": "The element that scrolls. Unset, it is the first target’s nearest scrolling ancestor; null is the viewport"
+        },
+        {
+          "name": "offset",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "slTableOfContents",
+          "description": "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"
+        },
+        {
+          "name": "value",
+          "type": "model<string | null>",
+          "defaultValue": "null",
+          "appliesTo": "slTableOfContents",
+          "description": "The current target’s id. Two-way: the list asks through valueChangeRequest and moves it once the request is accepted"
+        },
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "slTableOfContents",
+          "description": "Whether the collapsed list is shown. Two-way, through openChangeRequest"
+        },
+        {
+          "name": "layout",
+          "type": "'vertical' | 'horizontal' | 'collapsed'",
+          "defaultValue": "vertical",
+          "appliesTo": "slTableOfContents",
+          "description": "The column, the bar, or the trigger with the list under it. The consumer’s breakpoint decides; the family never decides by width"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slTableOfContents",
+          "description": "The row step, on the control scale: height, type and inset"
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTableOfContents",
+          "description": "Pins the column under the page’s chrome and gives it the rest of the viewport; the panel scrolls. Ignored in the collapsed layout"
+        },
+        {
+          "name": "history",
+          "type": "'push' | 'replace' | 'none'",
+          "defaultValue": "push",
+          "appliesTo": "slTableOfContents",
+          "description": "What a press does to the URL: pushState, replaceState, or nothing. scrollTo() never writes it"
+        },
+        {
+          "name": "numbered",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTableOfContents",
+          "description": "Counters per level before each link"
+        },
+        {
+          "name": "landmark",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "slTableOfContents",
+          "description": "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"
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slTableOfContents",
+          "description": "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"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTableOfContents",
+          "description": "Four rows of skeleton in the list’s place, and aria-busy on the host"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<TableOfContentsMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slTableOfContents",
+          "description": "Words laid over the language in force: the landmark’s name when there is no label, and the collapsed trigger’s fixed text (navigation)"
+        }
+      ],
+      "composition": [
+        {
+          "name": "slTableOfContentsLink",
+          "type": "ng-template, let-entry let-current=\"current\"",
+          "defaultValue": "—",
+          "appliesTo": "a child of the host",
+          "description": "The content of every link, handed the entry and whether it is current. Without one the link shows the entry’s label"
+        },
+        {
+          "name": "slTableOfContentsLabel",
+          "type": "ng-template",
+          "defaultValue": "—",
+          "appliesTo": "a child of the host",
+          "description": "The list’s title as a template, for a title with a mark or a count in it"
+        },
+        {
+          "name": "exportAs slTableOfContents",
+          "type": "SlTableOfContents",
+          "defaultValue": "—",
+          "appliesTo": "the host",
+          "description": "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"
+        },
+        {
+          "name": "provideTableOfContentsDefaults",
+          "type": "{ layout, size, sticky, history, numbered, landmark, levels, offset }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The decisions an application takes once. A list that states any of them itself still wins"
+        },
+        {
+          "name": "aria-label, aria-labelledby, id, class",
+          "type": "the host’s own attributes",
+          "defaultValue": "—",
+          "appliesTo": "the host",
+          "description": "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": "valueChangeRequest",
+          "payload": "ChangeRequest<string | null>",
+          "when": "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."
+        },
+        {
+          "name": "openChangeRequest",
+          "payload": "ChangeRequest<boolean>",
+          "when": "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."
+        },
+        {
+          "name": "valueChange, openChange",
+          "payload": "string | null; boolean",
+          "when": "After each model moves: the two-way halves of [(value)] and [(open)], for a template that binds one directly."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The customer record beside its list. Scroll the document and watch the marker slide to the section in view; press a link and the section lands under the top edge with focus on it. The controls below drive every axis.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" label=\"Nesta página\"></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, named",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" [(value)]=\"section\">\n  <ng-template slTableOfContentsLabel>Nesta página</ng-template>\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "source",
+      "title": "Read from the document’s own headings",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents label=\"Neste artigo\" [levels]=\"[2, 3]\" [source]=\"article\"></nav>\n<div #article slProse>…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "items",
+      "title": "The list as data, from a pipeline",
+      "note": "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.",
+      "language": "ts",
+      "source": "import { nestOutline } from '@slotted/core/outline';\n\nconst items = nestOutline(toc); // [{ id, label, level }]\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sticky",
+      "title": "A column that stays while the document scrolls",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" label=\"Nesta página\" sticky></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "horizontal",
+      "title": "The bar under a page title",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slPageHeaderTabs>\n  <nav slTableOfContents [items]=\"sections\" layout=\"horizontal\"></nav>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "collapsed",
+      "title": "A phone’s bar",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav\n  slTableOfContents\n  [items]=\"sections\"\n  label=\"Nesta página\"\n  [layout]=\"phone() ? 'collapsed' : 'vertical'\"\n></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "numbered",
+      "title": "Clauses, numbered",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"clauses\" label=\"Cláusulas\" numbered></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "size",
+      "title": "Three steps on the control scale",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" size=\"sm\"></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the contract declares",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" [(value)]=\"section\"></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "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.",
+      "language": "ts",
+      "source": "const items = [\n  { id: 'ambito', label: 'Âmbito de aplicação e definições utilizadas neste documento' },\n  { id: 'ref', label: 'REF-2026-09-16-DEVOLUCAO-INDUSTRIAL-000482915' },\n];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "loading",
+      "title": "While the document is still arriving",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections() ?? []\" [loading]=\"!sections()\"></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "history",
+      "title": "What a press does to the URL",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" history=\"replace\"></nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "defaults",
+      "title": "Decided once for the application",
+      "note": "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.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [\n    provideTableOfContentsDefaults({\n      history: 'replace',\n      levels: [2, 4],\n      size: 'sm',\n      sticky: true,\n    }),\n  ],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Beside a resizable column, and with its own link",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\">\n  <ng-template slTableOfContentsLink let-entry let-current=\"current\">\n    <span slText [weight]=\"current ? 'semibold' : 'regular'\">{{ entry.label }}</span>\n  </ng-template>\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Every key the contract lists",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents #list=\"slTableOfContents\" [items]=\"sections\"></nav>\n<button slButton (click)=\"list.focus()\">Focar o índice</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a screen reader hears",
+      "note": "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.",
+      "language": "html",
+      "source": "<nav slTableOfContents [items]=\"sections\" label=\"Nesta página\"></nav>\n<!-- <nav aria-labelledby=\"…-label\"> … <a aria-current=\"location\"> -->\n",
+      "verdict": "excerpt"
+    }
+  ]
+}