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

package/docs/toggle-group.json

@@ -0,0 +1,417 @@
+{
+  "family": "toggle-group",
+  "ui": "toggle-group",
+  "binding": "angular",
+  "catalog": {
+    "group": "Actions",
+    "summary": "Set of toggles, single or multiple."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "ghost"
+    ],
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ]
+  },
+  "members": {
+    "toggleGroup": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "orientation": "horizontal",
+        "attached": true,
+        "fullWidth": false,
+        "multiple": false,
+        "deselectable": true,
+        "loop": true,
+        "disabled": false
+      },
+      "capabilities": [
+        "selection",
+        "orientation",
+        "size",
+        "appearance",
+        "arrangement",
+        "content",
+        "fullWidth",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "pressed",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "item",
+        "icon",
+        "label"
+      ]
+    }
+  },
+  "docs": {
+    "toggleGroup": {
+      "imports": {
+        "source": "import {\n  provideToggleGroupDefaults,\n  SlToggleGroup,\n  SlToggleGroupIcon,\n  SlToggleGroupItem,\n} from '@slotted/angular/toggle-group';",
+        "selector": "[slToggleGroup]",
+        "exportAs": "slToggleGroup"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the consumer’s own element, with slToggleGroup on it",
+          "required": true,
+          "purpose": "The group. It carries role=\"group\", data-ui=\"toggle-group\", the axes, and one tab stop for the whole set. It states no frame of its own: a joined bar has one edge, and the items make it between them, which is also what keeps the bar exactly one control tall."
+        },
+        {
+          "part": "item",
+          "element": "button, with slToggleGroupItem on it",
+          "required": true,
+          "purpose": "One two-state control. It carries aria-pressed in both states and data-pressed when it is on, and its border is always present so that turning it on changes a colour and never the geometry."
+        },
+        {
+          "part": "icon",
+          "element": "the consumer’s own element, with slToggleGroupIcon on it",
+          "required": false,
+          "purpose": "The mark an item was given, sized from the control glyph scale and hidden from the reading order. An item with a mark and no words takes its accessible name from the aria-label the consumer writes."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": false,
+          "purpose": "The words the item projects. A box of their own, so a label the bar made too narrow clips at the ellipsis instead of wrapping the item onto a second line — and the string stays whole in the DOM."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "slToggleGroup",
+          "description": "Present means the consumer owns the set, for the life of the component. Absent, the group owns it and starts from defaultValue"
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "slToggleGroup",
+          "description": "What an uncontrolled group starts from, read once in ngOnInit. A later change to it does not silently become new state"
+        },
+        {
+          "name": "multiple",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether more than one item may be on at a time. The value stays an array either way, so one signal holds it in every mode"
+        },
+        {
+          "name": "deselectable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether the last item on may be turned off. Ignored while multiple is true, where a set may always empty"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slToggleGroup",
+          "description": "The control step the bar and every item sit at. It reads the control scale, so the bar is as tall as the field beside it"
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'ghost'",
+          "defaultValue": "outline",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether the bar draws its own edge. There is no tone axis: “on” is one colour across the system"
+        },
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "slToggleGroup",
+          "description": "How the items flow, and which pair of arrows moves focus. A vertical group writes aria-orientation"
+        },
+        {
+          "name": "attached",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether the items are joined into one bar or spaced apart. A joined bar overlaps its items by one border so a shared column holds one line"
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether the items share the whole line. Left alone the bar is as wide as its labels"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether the arrows wrap past the ends of the set"
+        },
+        {
+          "name": "rovingFocus",
+          "type": "boolean",
+          "defaultValue": "inferred",
+          "appliesTo": "slToggleGroup",
+          "description": "Whether the group holds a tab stop of its own. Unstated it is inferred after the first render: a group inside a toolbar stands down"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slToggleGroup",
+          "description": "Unstated rather than false, so an item may state its own. Stated, it reaches every item as the native attribute"
+        },
+        {
+          "name": "value, on slToggleGroupItem",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slToggleGroupItem",
+          "description": "What this item turns on, and what the group’s value holds. It is required: an item with no value is a control that changes nothing"
+        },
+        {
+          "name": "disabled, on slToggleGroupItem",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slToggleGroupItem",
+          "description": "One item out of action while the rest of the bar stays live. An item that is on and unavailable keeps saying both"
+        }
+      ],
+      "composition": [
+        {
+          "name": "slToggleGroupItem",
+          "type": "directive on a button",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s element",
+          "description": "The item is a directive, so the button is the consumer’s own: every attribute, every listener and every structural directive around it stay exactly as they were written"
+        },
+        {
+          "name": "slToggleGroupIcon",
+          "type": "directive on any element",
+          "defaultValue": "—",
+          "appliesTo": "inside an item",
+          "description": "The mark, projected into the item and hidden from the reading order. An ng-icon, an inline svg or a span all work and none of them loses its own semantics"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slToggleGroup' | 'slToggleGroupItem'",
+          "defaultValue": "—",
+          "appliesTo": "a template reference",
+          "description": "Reaches the instance, so a template can read selection(), resolvedSize() or an item’s pressed() without the component owning a second copy of the state"
+        },
+        {
+          "name": "provideToggleGroupDefaults()",
+          "type": "(defaults: Partial<ToggleGroupDefaults>) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The six decisions an application takes once, at the root or on one route. A group that states any of them itself still wins"
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "defaultValue": "group",
+          "appliesTo": "slToggleGroup",
+          "description": "Read from the host with HostAttributeToken before the host bindings write, so a consumer’s own survives. The family writes group and never toolbar: toolbar is a keyboard model, and it is the toolbar family"
+        }
+      ],
+      "events": [
+        {
+          "name": "valueChange",
+          "payload": "ChangeRequest<readonly string[]>",
+          "when": "Before the value moves. The request carries the new array, the array it replaces, the reason — pointer or keyboard — the originating event, and cancel(), which refuses the move before anything commits. Nothing is emitted for a value equal to the one the group already holds."
+        },
+        {
+          "name": "click, focus, blur, on each item",
+          "payload": "the element’s own events",
+          "when": "Whenever that item’s button fires them. The item is a directive on the consumer’s own element, so every listener the consumer bound is on the element itself and runs exactly as it was written."
+        }
+      ],
+      "accessibility": [
+        "There is no APG pattern called “toggle group”. The container is a group, each item is the Button pattern’s toggle button (w3.org/WAI/ARIA/apg/patterns/button/), and the movement between them is the Toolbar pattern’s roving tabindex (w3.org/WAI/ARIA/apg/patterns/toolbar/). Citing one and implying the other is how a family ends up with half a keyboard.",
+        "So the arrows move focus and never toggle, which is the one place this family and segmented-control genuinely differ and the one a reader feels. Space and Enter turn the focused item on or off; Home and End reach the ends; a horizontal group ignores the cross axis so the page keeps scrolling with focus inside it.",
+        "aria-pressed is written in both states, so an item is announced as a toggle rather than as a button that happens to be pressed — and the label never changes with the state, which the Button pattern calls critical. An item with only a mark takes its name from an aria-label the consumer writes on the button.",
+        "Inside a toolbar the group gives its keyboard up: the bar is found in the DOM by its public identifier rather than by injecting the other family, so neither depends on the other. rovingFocus states it outright for a bar this library did not write.",
+        "disabled is the native attribute, because that is also what makes the browser refuse focus and what makes the ring skip the item. The group is not a form control and implements no ControlValueAccessor: a set of choices a form submits is checkbox-group for many and segmented-control for one.",
+        "The target is the item itself, never narrower than it is tall, so the WCAG 2.2 minimum of 24 by 24 holds at the smallest step and the tightest density — and the theme grows every control to 44 under a coarse pointer."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-font-weight",
+    "--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-line-height",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-instant",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-text",
+    "--slotted-toggle-group-active-background",
+    "--slotted-toggle-group-border-color",
+    "--slotted-toggle-group-color",
+    "--slotted-toggle-group-disabled-border-color",
+    "--slotted-toggle-group-disabled-color",
+    "--slotted-toggle-group-disabled-pressed-background",
+    "--slotted-toggle-group-hover-background",
+    "--slotted-toggle-group-pressed-background",
+    "--slotted-toggle-group-pressed-border-color",
+    "--slotted-toggle-group-pressed-color",
+    "--slotted-toggle-group-pressed-hover-background",
+    "--slotted-toggle-group-radius",
+    "--slotted-toggle-group-shadow",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One bar with every axis on it, driven by the controls below the canvas. Tab into it once: the whole group is a single stop, and the arrows move focus from there without changing anything.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Período do gráfico\" [defaultValue]=\"['week']\">\n  <button slToggleGroupItem value=\"day\">Dia</button>\n  <button slToggleGroupItem value=\"week\">Semana</button>\n  <button slToggleGroupItem value=\"month\">Mês</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "selection",
+      "title": "One at a time, several at once, or none",
+      "note": "The value is an array in both modes: multiple caps it at every item rather than at one. Press the item that is already on — the set empties, unless deselectable says it may not.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Estilo do texto\" multiple [defaultValue]=\"['bold']\">\n  <button slToggleGroupItem value=\"bold\">Negrito</button>\n  <button slToggleGroupItem value=\"italic\">Itálico</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "Framed, or bare",
+      "note": "outline draws the bar’s own edge; ghost draws none, for a bar that sits inside something already framed — a toolbar, a card header. The colour of an item that is on is the same in both.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Densidade\" variant=\"ghost\" [defaultValue]=\"['compact']\">\n  <button slToggleGroupItem value=\"comfortable\">Confortável</button>\n  <button slToggleGroupItem value=\"compact\">Compacta</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The three control steps",
+      "note": "Each step reads the control scale, so a bar is exactly as tall as the text field and the button beside it at every size and at every density.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Ordenação\" size=\"sm\" [defaultValue]=\"['newest']\">\n  <button slToggleGroupItem value=\"newest\">Mais recentes</button>\n  <button slToggleGroupItem value=\"oldest\">Mais antigos</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "Along the line, or down the page",
+      "note": "A vertical bar moves with ArrowUp and ArrowDown and writes aria-orientation; a horizontal one leaves the cross axis to the page, so scrolling still works with focus inside the group.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Alinhamento\" orientation=\"vertical\" [defaultValue]=\"['center']\">\n  <button slToggleGroupItem value=\"start\">Início</button>\n  <button slToggleGroupItem value=\"center\">Centro</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "attached",
+      "title": "Joined, or spaced apart",
+      "note": "A joined bar overlaps its items by one border so the shared column holds one line rather than two — which is what keeps the edge even at 110%, 150% and 175% zoom.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Camadas\" multiple [attached]=\"false\" [defaultValue]=\"['roads']\">\n  <button slToggleGroupItem value=\"roads\">Ruas</button>\n  <button slToggleGroupItem value=\"terrain\">Relevo</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the contract declares",
+      "note": "Hover, focus, press, on, unavailable, and unavailable while on — that last one keeps both facts, because the state a reader cannot change is still one they have to be able to read.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Formato\" [defaultValue]=\"['csv']\">\n  <button slToggleGroupItem value=\"csv\">CSV</button>\n  <button slToggleGroupItem value=\"xlsx\" disabled>XLSX</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "iconOnly",
+      "title": "Marks without words",
+      "note": "An item with only a mark draws square and takes its accessible name from aria-label, which is the one thing the family cannot supply for a consumer’s own artwork.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Estilo do texto\" multiple [defaultValue]=\"['bold']\">\n  <button slToggleGroupItem value=\"bold\" aria-label=\"Negrito\">\n    <ng-icon slToggleGroupIcon name=\"lucideBold\" />\n  </button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "width",
+      "title": "Content width, or the whole line",
+      "note": "Left alone the bar is as wide as its labels; fullWidth makes the items share the line. Either way an item gives way rather than pushing the layout, and its label clips at the ellipsis.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Cobrança\" fullWidth [defaultValue]=\"['monthly']\">\n  <button slToggleGroupItem value=\"monthly\">Mensal</button>\n  <button slToggleGroupItem value=\"yearly\">Anual</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "toolbar",
+      "title": "Inside a toolbar, the bar owns the keyboard",
+      "note": "A toolbar is already one tab stop with arrow navigation across every control it holds, so the group stands down rather than putting a second stop inside the first. Nothing has to be passed.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Formatação\">\n  <div\n    slToggleGroup\n    aria-label=\"Estilo do texto\"\n    multiple\n    variant=\"ghost\"\n    [defaultValue]=\"['bold']\"\n  >\n    <button slToggleGroupItem value=\"bold\" aria-label=\"Negrito\">\n      <ng-icon slToggleGroupIcon name=\"lucideBold\" />\n    </button>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A label nine words long, one unbroken token, and a right-to-left string inside a left-to-right page. Each clips at the ellipsis and keeps its whole text in the DOM.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Frequência\" fullWidth [defaultValue]=\"['now']\">\n  <button slToggleGroupItem value=\"now\">Imediatamente</button>\n  <button slToggleGroupItem value=\"digest\">Uma vez por dia, no resumo da noite</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The directive on the consumer’s own element, and the defaults once",
+      "note": "Every part is a directive, so the element is always the consumer’s; provideToggleGroupDefaults states the axes once for a whole application or one route.",
+      "language": "ts",
+      "source": "providers: [provideToggleGroupDefaults({ size: 'sm', variant: 'ghost' })];\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard, key by key",
+      "note": "Tab reaches the group once; the arrows move focus and never toggle; Home and End reach the ends; Space and Enter turn the focused item on and off. An item is a button, and that is why.",
+      "language": "html",
+      "source": "<div slToggleGroup aria-label=\"Período\" [loop]=\"false\" [defaultValue]=\"['week']\">\n  <button slToggleGroupItem value=\"day\">Dia</button>\n  <button slToggleGroupItem value=\"week\">Semana</button>\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}