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

package/docs/collapsible.json

@@ -0,0 +1,456 @@
+{
+  "family": "collapsible",
+  "ui": "collapsible",
+  "binding": "angular",
+  "catalog": {
+    "group": "Layout",
+    "summary": "One region whose content shows or hides."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "plain",
+      "ruled",
+      "framed"
+    ],
+    "indicator": [
+      "chevron",
+      "plus-minus",
+      "none"
+    ],
+    "togglePlacement": [
+      "end",
+      "start"
+    ],
+    "level": [
+      "none",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6"
+    ],
+    "mount": [
+      "active",
+      "lazy",
+      "eager",
+      "until-found"
+    ]
+  },
+  "members": {
+    "collapsible": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "plain",
+        "indicator": "chevron",
+        "togglePlacement": "end",
+        "level": "none",
+        "mount": "eager",
+        "truncate": false,
+        "region": false,
+        "disabled": false,
+        "loading": false
+      },
+      "capabilities": [
+        "open",
+        "size",
+        "appearance",
+        "disabled",
+        "loading",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open",
+        "disabled",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "header",
+        "trigger",
+        "indicator",
+        "label",
+        "description",
+        "actions",
+        "panel",
+        "content"
+      ]
+    }
+  },
+  "docs": {
+    "collapsible": {
+      "imports": {
+        "source": "import { SlCollapsible, SlCollapsibleActions, SlCollapsibleContent, SlCollapsibleHeader, SlCollapsiblePanel, SlCollapsibleTrigger } from '@slotted/angular/collapsible';",
+        "selector": "[slCollapsible], [slCollapsibleHeader], button[slCollapsibleTrigger], [slCollapsibleActions], [slCollapsiblePanel], ng-template[slCollapsibleContent]",
+        "exportAs": "slCollapsible, slCollapsibleHeader, slCollapsibleTrigger, slCollapsiblePanel"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element carrying slCollapsible",
+          "required": true,
+          "purpose": "The family. A two-column, two-row grid carrying data-ui=\"collapsible\", the six axes, data-open, data-disabled, data-loading and data-value. It is also its own container, so the header reflows on its own inline size rather than the viewport’s."
+        },
+        {
+          "part": "header",
+          "element": "the element the consumer wrote — h1 to h6, or anything else",
+          "required": true,
+          "purpose": "The heading. A native heading is left alone; anything else is given role=\"heading\" and the aria-level the disclosure resolved, which is the alternative the pattern names. Its only child is the trigger."
+        },
+        {
+          "part": "trigger",
+          "element": "button[slCollapsibleTrigger]",
+          "required": true,
+          "purpose": "The control. Holds aria-expanded, aria-controls, the identifier, and every native attribute the consumer wrote on the button. Enter and Space are the platform’s, so the family binds no key of its own."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The mark, drawn as a mask from a glyph token. A chevron turns between down and up; plus-minus swaps one bar for the pair. indicator=\"none\" draws nothing at all."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "The title, holding whatever the trigger projects. A box of its own, so text-overflow has something to clip under truncate and so a title in another script reads its own way."
+        },
+        {
+          "part": "description",
+          "element": "span",
+          "required": false,
+          "purpose": "A second line under the title, from the description input. It is inside the trigger, so it is part of the accessible name — “Entrega, 3 de 12 itens” is what a reader hears."
+        },
+        {
+          "part": "actions",
+          "element": "the element carrying slCollapsibleActions",
+          "required": false,
+          "purpose": "The always-visible controls beside the header, on its own row and outside the button. What belongs in it is an slToolbar. Below 22rem it takes a row of its own."
+        },
+        {
+          "part": "panel",
+          "element": "the element carrying slCollapsiblePanel",
+          "required": true,
+          "purpose": "The box the trigger controls: aria-labelledby its trigger, inert while closed, and hidden=\"until-found\" under that mount. The box always exists, so aria-controls never names an element that is gone."
+        },
+        {
+          "part": "content",
+          "element": "div",
+          "required": true,
+          "purpose": "What the panel’s grid track clips. Its content-visibility takes closed content out of the tab sequence, out of the accessibility tree and out of the browser’s page search. mount decides whether it is built at all, and an ng-template[slCollapsibleContent] inside it is what makes lazy actually lazy."
+        }
+      ],
+      "api": [
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "slCollapsible",
+          "description": "Whether the panel is open. A model, so [(open)] is both the value and the write-back — the initial value is the uncontrolled start and a bound signal is the controlled one. Inside an slAccordion the set owns it instead"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slCollapsible, slAccordion, provideCollapsibleDefaults",
+          "description": "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"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'ruled' | 'framed'",
+          "defaultValue": "plain",
+          "appliesTo": "slCollapsible, provideCollapsibleDefaults",
+          "description": "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 slAccordion hands its items the one its own variant maps onto"
+        },
+        {
+          "name": "indicator",
+          "type": "'chevron' | 'plus-minus' | 'none'",
+          "defaultValue": "chevron",
+          "appliesTo": "slCollapsible, slAccordion, provideCollapsibleDefaults",
+          "description": "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"
+        },
+        {
+          "name": "togglePlacement",
+          "type": "'end' | 'start'",
+          "defaultValue": "end",
+          "appliesTo": "slCollapsible, slAccordion, provideCollapsibleDefaults",
+          "description": "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"
+        },
+        {
+          "name": "level",
+          "type": "'none' | '1' | '2' | '3' | '4' | '5' | '6'",
+          "defaultValue": "none",
+          "appliesTo": "slCollapsible, provideCollapsibleDefaults",
+          "description": "The heading level the header answers to. A native heading element is left alone; anything else is given role=\"heading\" and this level. none writes no heading semantics at all"
+        },
+        {
+          "name": "mount",
+          "type": "'active' | 'lazy' | 'eager' | 'until-found'",
+          "defaultValue": "eager",
+          "appliesTo": "slCollapsible, slAccordion, provideCollapsibleDefaults",
+          "description": "When the panel’s content exists. The box always does, so aria-controls never names an element that is gone. lazy needs an ng-template[slCollapsibleContent], because projected content is built whether or not it is inserted"
+        },
+        {
+          "name": "truncate",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slCollapsible, slAccordion, provideCollapsibleDefaults",
+          "description": "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"
+        },
+        {
+          "name": "region",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slCollapsible",
+          "description": "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"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slCollapsible",
+          "description": "Reaches the trigger as the native attribute, which is also what stops the press. Unstated rather than false, so the disclosure defers to the slAccordion around it"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slCollapsible",
+          "description": "The panel keeps a line’s height and carries aria-busy; what stands in for the content is slSkeleton, composed by the consumer"
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "from SlCollapsibleIdFactory",
+          "appliesTo": "slCollapsible",
+          "description": "What this disclosure is called inside an slAccordion. It is identity rather than state, and it reaches the DOM as data-value"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slCollapsibleTrigger",
+          "description": "A second line under the title, inside the trigger and therefore inside its accessible name"
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs",
+          "type": "'slCollapsible' | 'slCollapsibleHeader' | 'slCollapsibleTrigger' | 'slCollapsiblePanel'",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the instance from the template: #panel=\"slCollapsible\" gives isOpen(), toggle(next, reason) and the resolved axes without a component class in between"
+        },
+        {
+          "name": "slCollapsibleContent",
+          "type": "ng-template",
+          "defaultValue": "—",
+          "appliesTo": "inside slCollapsiblePanel",
+          "description": "Content built the first time the panel opens. ng-content is instantiated whether or not it is inserted, so lazy needs a template — which is Angular Material’s own matExpansionPanelContent"
+        },
+        {
+          "name": "provideCollapsibleDefaults",
+          "type": "(defaults: Partial<CollapsibleDefaults>) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The seven decisions an application takes once. An slAccordion sits between it and the item, and a disclosure that states any of them itself still wins"
+        },
+        {
+          "name": "the element each directive is on",
+          "type": "any",
+          "defaultValue": "—",
+          "appliesTo": "slCollapsible, slCollapsibleHeader, slCollapsibleActions, slCollapsiblePanel",
+          "description": "Every part but the trigger attaches to the consumer’s own element, so a disclosure can be a section and a heading can be an h2 without a render prop existing"
+        }
+      ],
+      "events": [
+        {
+          "name": "openChange",
+          "payload": "boolean",
+          "when": "The write-back half of the two-way binding. `[(open)]=\"open\"` keeps a signal in step with the panel, which is the form this ecosystem expects of a value a component and a template share."
+        },
+        {
+          "name": "openChangeRequest",
+          "payload": "ChangeRequest<boolean>",
+          "when": "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 slAccordion it still fires, so a consumer may watch one panel without unpacking the set’s array."
+        },
+        {
+          "name": "click, focus, keydown, on the trigger",
+          "payload": "the element’s own events",
+          "when": "Whenever the button fires them. The listener is on the host, so a consumer’s own (click) runs beside it rather than in place of it, and preventDefault() refuses the toggle."
+        }
+      ],
+      "accessibility": [
+        "The pattern is the WAI-ARIA APG’s Disclosure (w3.org/WAI/ARIA/apg/patterns/disclosure/), and inside an slAccordion 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 an application-scoped factory, so two applications rendering in one server process do not collide and the server and client sequences match. 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.",
+        "The heading is the element the consumer wrote. A native h1 to h6 is left exactly as it is; anything else is given role=\"heading\" and the resolved aria-level, which the pattern names as the alternative to a native element. React reads the element off level instead, because there the component owns the tag; both reach the same accessibility tree.",
+        "A closed panel is out of the tab sequence and out of the accessibility tree twice over: the stylesheet with content-visibility, and the directive 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.",
+        "aria-disabled appears on the trigger only when an slAccordion 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 a template can bind, a request that carries a reason, and a panel that animates without interpolate-size."
+      ]
+    }
+  },
+  "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One disclosure with every input on it, driven by the controls below the canvas. Tab lands on the trigger; Enter and Space are the platform’s.",
+      "language": "html",
+      "source": "<div slCollapsible [(open)]=\"open\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Endereço de entrega</button>\n  </h3>\n  <div slCollapsiblePanel>Rua das Laranjeiras, 402 — Rio de Janeiro.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "The three ways it is drawn",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible variant=\"framed\" [open]=\"true\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Formas de pagamento</button>\n  </h3>\n  <div slCollapsiblePanel>Cartão de crédito, boleto e Pix.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the header sits at",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible size=\"lg\" [open]=\"true\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger description=\"3 de 12 itens\">Resumo</button>\n  </h3>\n  <div slCollapsiblePanel>Entrega prevista para 12 de setembro.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "indicator",
+      "title": "The mark, and which side it stands on",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible indicator=\"plus-minus\" togglePlacement=\"start\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Nota fiscal</button>\n  </h3>\n  <div slCollapsiblePanel>Emitida em 3 de setembro.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "heading",
+      "title": "Where it sits in the outline",
+      "note": "The element is the consumer’s own: a real heading is left alone, and anything else is given role=\"heading\" and the level — the alternative the pattern names.",
+      "language": "html",
+      "source": "<div slCollapsible level=\"3\">\n  <div slCollapsibleHeader>\n    <button slCollapsibleTrigger>Condições de devolução</button>\n  </div>\n  <div slCollapsiblePanel>Trinta dias corridos.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "description",
+      "title": "A summary that stays visible",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slCollapsibleTrigger description=\"2 regras ativas\">Regras de frete</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "A control beside the heading",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible variant=\"framed\" [open]=\"true\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Regras de frete</button>\n  </h3>\n  <div slCollapsibleActions>\n    <div slToolbar aria-label=\"Ações da regra\" size=\"sm\">\n      <button slButton size=\"sm\" variant=\"ghost\">Editar</button>\n    </div>\n  </div>\n  <div slCollapsiblePanel>Frete grátis acima de R$ 250,00.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "mount",
+      "title": "When the content exists",
+      "note": "eager builds it up front so the panel can transition closed, lazy waits for the first open, active drops it each time, and until-found lets the browser’s page search open the panel.",
+      "language": "html",
+      "source": "<div slCollapsible mount=\"lazy\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Histórico de entregas</button>\n  </h3>\n  <div slCollapsiblePanel>\n    <ng-template slCollapsibleContent>{{ history() }}</ng-template>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the family paints",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible [loading]=\"true\" [open]=\"true\" mount=\"lazy\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Histórico de entregas</button>\n  </h3>\n  <div slCollapsiblePanel>\n    <span slSkeleton shape=\"text\"></span>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible [truncate]=\"true\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Condições de devolução para pedidos internacionais</button>\n  </h3>\n  <div slCollapsiblePanel>Trinta dias corridos.</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "provideCollapsibleDefaults carries the seven decisions an application takes once, exportAs reaches the instance, and a disclosure nests inside another’s panel without the outer one opening it.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideCollapsibleDefaults({ variant: 'framed', size: 'sm' })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The pattern’s table, and which device asked",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slCollapsible (openChangeRequest)=\"reason.set($event.reason)\">\n  <h3 slCollapsibleHeader>\n    <button slCollapsibleTrigger>Com o ponteiro, depois com o teclado</button>\n  </h3>\n  <div slCollapsiblePanel>A razão muda com o dispositivo.</div>\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}