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

package/docs/grid.json

@@ -0,0 +1,176 @@
+{
+  "family": "grid",
+  "ui": "grid",
+  "binding": "angular",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Columns that reflow by available width."
+  },
+  "axes": {
+    "gap": [
+      "0",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+      "10",
+      "11",
+      "12"
+    ],
+    "align": [
+      "start",
+      "center",
+      "end",
+      "stretch"
+    ],
+    "justify": [
+      "start",
+      "center",
+      "end",
+      "stretch"
+    ],
+    "columns": [
+      "auto",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+      "10",
+      "11",
+      "12"
+    ],
+    "minItemWidth": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ]
+  },
+  "members": {
+    "grid": {
+      "nativeElement": "div",
+      "defaults": {
+        "gap": "6",
+        "minItemWidth": "md"
+      },
+      "capabilities": [
+        "arrangement"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "grid": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "gap",
+          "type": "0 | 1 | … | 12",
+          "defaultValue": "6",
+          "appliesTo": "slGrid",
+          "description": "Separation between cells, as a step on the space scale"
+        },
+        {
+          "name": "columns",
+          "type": "1 | 2 | … | 12",
+          "defaultValue": "auto",
+          "appliesTo": "slGrid",
+          "description": "At most this many tracks; absent, the grid fits as many as it can"
+        },
+        {
+          "name": "minItemWidth",
+          "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
+          "defaultValue": "md",
+          "appliesTo": "slGrid",
+          "description": "The narrowest a cell may become before a column is dropped"
+        },
+        {
+          "name": "align",
+          "type": "'start' | 'center' | 'end' | 'stretch'",
+          "defaultValue": "—",
+          "appliesTo": "slGrid",
+          "description": "Positions a child across the flow, inside its own cell"
+        },
+        {
+          "name": "justify",
+          "type": "'start' | 'center' | 'end' | 'stretch'",
+          "defaultValue": "—",
+          "appliesTo": "slGrid",
+          "description": "Positions a child along the flow, inside its own cell"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "This is not the APG grid widget. There is no role=\"grid\", no cell and no arrow-key navigation: the family lays children out, and the children keep whatever semantics they already had.",
+        "The directive selector is an attribute, so the element is always the consumer’s. Write ul when the children are list items.",
+        "There is no input that reorders or places children. Visual order stays DOM order, which is what WCAG 2.2 SC 1.3.2 asks for (technique C27, failure F1) and what keeps the Tab order matching the page.",
+        "A stated count is a ceiling the container may lower. Twelve columns become six and then one as the container narrows, so a page reflows to 320 CSS pixels without scrolling in two dimensions, as WCAG 1.4.10 requires.",
+        "The reflow is measured against the grid’s own inline size, not the viewport, so a grid inside a narrow panel behaves the same as one inside a narrow window."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-grid-columns",
+    "--slotted-grid-min-item-width-lg",
+    "--slotted-grid-min-item-width-md",
+    "--slotted-grid-min-item-width-sm",
+    "--slotted-grid-min-item-width-xl",
+    "--slotted-grid-min-item-width-xs",
+    "--slotted-space-1",
+    "--slotted-space-10",
+    "--slotted-space-11",
+    "--slotted-space-12",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-7",
+    "--slotted-space-8",
+    "--slotted-space-9"
+  ],
+  "examples": [
+    {
+      "id": "grid-angular-cards",
+      "title": "As many cards as fit, never narrower than a card should be",
+      "note": null,
+      "language": "html",
+      "source": "<div slGrid [gap]=\"6\" minItemWidth=\"md\">\n  @for (workspace of workspaces; track workspace.id) {\n    <app-card [workspace]=\"workspace\" />\n  }\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "grid-angular-ceiling",
+      "title": "Three columns at most, fewer when the container narrows",
+      "note": null,
+      "language": "html",
+      "source": "<div slGrid [columns]=\"3\" [gap]=\"4\" minItemWidth=\"sm\">\n  <app-metric label=\"Revenue\" />\n  <app-metric label=\"Refunds\" />\n  <app-metric label=\"Disputes\" />\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "grid-angular-span",
+      "title": "A child that crosses two tracks says so on itself",
+      "note": null,
+      "language": "html",
+      "source": "<div slGrid [columns]=\"2\" [gap]=\"6\">\n  <section style=\"grid-column: span 2\">Summary</section>\n  <section>Left</section>\n  <section>Right</section>\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/grid.md

@@ -0,0 +1,74 @@
+<!-- index: ./index.md -->
+# grid
+
+`data-ui="grid"` · Columns that reflow by available width.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slGrid [gap]="6" minItemWidth="md">
+  @for (workspace of workspaces; track workspace.id) {
+    <app-card [workspace]="workspace" />
+  }
+</div>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `gap` | `0 \| 1 \| … \| 12` | 6 | slGrid | Separation between cells, as a step on the space scale |
+| `columns` | `1 \| 2 \| … \| 12` | auto | slGrid | At most this many tracks; absent, the grid fits as many as it can |
+| `minItemWidth` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | slGrid | The narrowest a cell may become before a column is dropped |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | slGrid | Positions a child across the flow, inside its own cell |
+| `justify` | `'start' \| 'center' \| 'end' \| 'stretch'` | — | slGrid | Positions a child along the flow, inside its own cell |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `gap` | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12` | `6` |
+| `align` | `start`, `center`, `end`, `stretch` | — |
+| `justify` | `start`, `center`, `end`, `stretch` | — |
+| `columns` | `auto`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12` | — |
+| `minItemWidth` | `xs`, `sm`, `md`, `lg`, `xl` | `md` |
+
+## Rules
+
+- This is not the APG grid widget. There is no role="grid", no cell and no arrow-key navigation: the family lays children out, and the children keep whatever semantics they already had.
+- The directive selector is an attribute, so the element is always the consumer’s. Write ul when the children are list items.
+- There is no input that reorders or places children. Visual order stays DOM order, which is what WCAG 2.2 SC 1.3.2 asks for (technique C27, failure F1) and what keeps the Tab order matching the page.
+- A stated count is a ceiling the container may lower. Twelve columns become six and then one as the container narrows, so a page reflows to 320 CSS pixels without scrolling in two dimensions, as WCAG 1.4.10 requires.
+- The reflow is measured against the grid’s own inline size, not the viewport, so a grid inside a narrow panel behaves the same as one inside a narrow window.
+
+## Tokens
+
+`--slotted-grid-columns`, `--slotted-grid-min-item-width-lg`, `--slotted-grid-min-item-width-md`, `--slotted-grid-min-item-width-sm`, `--slotted-grid-min-item-width-xl`, `--slotted-grid-min-item-width-xs`, `--slotted-space-1`, `--slotted-space-10`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`
+
+## Examples
+
+### Three columns at most, fewer when the container narrows
+
+Excerpt — not a complete module
+
+```html
+<div slGrid [columns]="3" [gap]="4" minItemWidth="sm">
+  <app-metric label="Revenue" />
+  <app-metric label="Refunds" />
+  <app-metric label="Disputes" />
+</div>
+```
+
+### A child that crosses two tracks says so on itself
+
+Excerpt — not a complete module
+
+```html
+<div slGrid [columns]="2" [gap]="6">
+  <section style="grid-column: span 2">Summary</section>
+  <section>Left</section>
+  <section>Right</section>
+</div>
+```

package/docs/highlight.json

@@ -0,0 +1,279 @@
+{
+  "family": "highlight",
+  "ui": "highlight",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Marks matches of a query inside text."
+  },
+  "axes": {
+    "occurrences": [
+      "all",
+      "first"
+    ],
+    "sensitivity": [
+      "base",
+      "accent",
+      "case",
+      "variant"
+    ]
+  },
+  "members": {
+    "highlight": {
+      "nativeElement": "span",
+      "defaults": {
+        "occurrences": "all",
+        "sensitivity": "base",
+        "locale": null,
+        "current": null,
+        "disabled": false
+      },
+      "capabilities": [
+        "content",
+        "disabled"
+      ],
+      "states": [
+        "default",
+        "current",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "match"
+      ]
+    }
+  },
+  "docs": {
+    "highlight": {
+      "imports": {
+        "source": "import { SlHighlight, provideHighlightDefaults } from '@slotted/angular/highlight';",
+        "selector": "[slHighlight]",
+        "exportAs": "slHighlight"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "span",
+          "required": true,
+          "purpose": "The element the directive is written on — the one that holds the text. Carries data-ui=\"highlight\", data-disabled when the marks step down, and every attribute the consumer wrote. Inside a host it sits inside the host’s label part."
+        },
+        {
+          "part": "match",
+          "element": "mark",
+          "required": false,
+          "purpose": "One per contiguous span the query found, in the element the HTML Standard defines for the term searched for inside a result. Carries data-current on the match a find bar is standing on. Absent when nothing matched."
+        }
+      ],
+      "api": [
+        {
+          "name": "text",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "The text, whole. The only content the family renders; nothing in it is HTML, and every run is a slice of it"
+        },
+        {
+          "name": "query",
+          "type": "string | readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "One query or several. Empty and whitespace-only entries find nothing; overlapping matches merge into one run"
+        },
+        {
+          "name": "ranges",
+          "type": "readonly [number, number][]",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "Spans already found, in the text’s own code units. Wins over query and matcher; clipped, ordered, merged and widened to graphemes"
+        },
+        {
+          "name": "matcher",
+          "type": "(text, queries) => ranges",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "Replaces the default collator scan. Receives the queries trimmed of empties; loses to ranges"
+        },
+        {
+          "name": "occurrences",
+          "type": "'all' | 'first'",
+          "defaultValue": "all",
+          "appliesTo": "SlHighlight",
+          "description": "all marks every place a query appears; first marks one span per query"
+        },
+        {
+          "name": "sensitivity",
+          "type": "'base' | 'accent' | 'case' | 'variant'",
+          "defaultValue": "base",
+          "appliesTo": "SlHighlight",
+          "description": "The collator’s own steps. base treats a, á and A as one letter, which is what typeahead and the filters compare at"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "null",
+          "appliesTo": "SlHighlight",
+          "description": "BCP 47. Unset asks the runtime; a host passes the locale its filter used. Falls back to provideHighlightDefaults"
+        },
+        {
+          "name": "current",
+          "type": "number",
+          "defaultValue": "null",
+          "appliesTo": "SlHighlight",
+          "description": "The match a find bar is standing on, counting matches only; that mark carries data-current. Out of range marks nothing"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlHighlight",
+          "description": "Writes data-disabled on the root: the marks give up the tone and keep the rule. Any ancestor’s data-disabled does the same"
+        }
+      ],
+      "composition": [
+        {
+          "name": "[slHighlight]",
+          "type": "attribute selector",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "Written on the consumer’s own element — the span in a label, the p under a find bar — which is the element that holds the text. The mark inside is fixed: it is the element that carries the semantics"
+        },
+        {
+          "name": "exportAs: slHighlight",
+          "type": "SlHighlight",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "Reaches the instance: runs() is the list a find bar counts matches from"
+        },
+        {
+          "name": "…native",
+          "type": "attributes on the host element",
+          "defaultValue": "—",
+          "appliesTo": "SlHighlight",
+          "description": "lang, dir, class, aria-* and every other attribute the consumer wrote stay on the element; the family adds data-ui, data-part and data-disabled beside them"
+        },
+        {
+          "name": "provideHighlightDefaults",
+          "type": "{ locale, sensitivity, occurrences }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets all three once for everything below it; an explicit input on a mark still wins"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "There is no highlight pattern in the WAI-ARIA Authoring Practices, and the HTML Standard defines mark for exactly this — “a run of text marked or highlighted for reference purposes, due to its relevance in another context”, with the term searched for inside a result as its example. The family therefore renders mark and writes no role, no aria-label and no aria-hidden.",
+        "The text a reader hears is the text: every run is a slice of the string handed in, nothing is parsed and nothing is hidden. A label holding <b> reads <b>.",
+        "Most screen readers do not announce mark by default (MDN, Accessibility). The family injects no hidden “highlight start” before each match: a five-match option would become ten announcements. An application that needs the announcement writes the ::before rule in its own scope, over [data-ui=\"highlight\"] [data-part=\"match\"].",
+        "The mark changes no metric of the word — weight, spacing and padding are the label’s own — so a filter that marks a different span on every keystroke never reflows the label under the reader’s eyes.",
+        "The current match is not a stronger band: 0.075 is the share the 7:1 promise caps in high-contrast, and doubling it leaves 6.5:1. It takes the accent’s solid ground and the ink the theme pairs with it, and under forced colours the Highlight and HighlightText pair the user agent draws its own find match in.",
+        "A disabled row’s mark gives up the tone and keeps the rule, so the reader still sees which span matched on the one option they cannot take, and the loudest colour on the surface is not on it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-width-thin",
+    "--slotted-highlight-background",
+    "--slotted-highlight-color",
+    "--slotted-highlight-current-background",
+    "--slotted-highlight-current-color",
+    "--slotted-highlight-disabled-background",
+    "--slotted-highlight-rule-color",
+    "--slotted-highlight-tint-opacity",
+    "--slotted-radius-none",
+    "--slotted-space-1",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One supplier name and the query typed against it, driven by the controls below the canvas. Change the query and watch the marks move without the word moving.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Açaí do Vale Ltda.\" query=\"aca\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "query",
+      "title": "A query, compared the way the reader’s locale compares",
+      "note": "The comparison is Intl.Collator at base sensitivity: aca finds Açaí, resume finds Résumé and strasse finds Straße. Nothing is a regular expression — C++ and a.b are text.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Açaí do Vale Ltda.\" query=\"aca\"></span>\n<span slHighlight text=\"Résumé Serviços\" query=\"RESUME\"></span>\n<span slHighlight text=\"Straße 12\" query=\"strasse\"></span>\n<span slHighlight text=\"C++ Consultoria a.b\" query=\"c++\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "multiple",
+      "title": "Several queries at once",
+      "note": "An array marks every query, and two that overlap or touch become one run: an and na over banana is one mark, never a mark inside a mark.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Banana Brasil Alimentos\" [query]=\"['an', 'na']\"></span>\n<span slHighlight text=\"Nota fiscal nº 2026-0441\" [query]=\"['nota', '0441']\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "occurrences",
+      "title": "Every occurrence, or the first",
+      "note": "all marks every place the query appears, which is the default; first marks one span per query, for a list that reads the mark as “why this row is here”.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Ana Banana Santana\" query=\"an\"></span>\n<span slHighlight text=\"Ana Banana Santana\" query=\"an\" occurrences=\"first\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "ranges",
+      "title": "Spans a server already found",
+      "note": "ranges wins over query: the marks are the indexes the search engine returned, in the text’s own code units. A span past the end is clipped, an inverted one is turned round, and one inside an emoji is widened to the whole character.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Fornecedor homologado em 2024\" [ranges]=\"[[11, 21]]\"></span>\n<span\n  slHighlight\n  text=\"🇧🇷 Brasil Cabos\"\n  [ranges]=\"[\n    [1, 2],\n    [12, 40],\n  ]\"\n></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "matcher",
+      "title": "A matcher of the consumer’s own",
+      "note": "matcher replaces the collator scan and receives the queries already trimmed of empties. Here it marks whole words only — the one capability Chakra ships as exactMatch, written in three lines over what the family exports.",
+      "language": "ts",
+      "source": "import { matchRanges } from '@slotted/core/highlight';\n\nfunction boundary(text: string, at: number) {\n  const around = text.slice(Math.max(0, at - 1), at + 1);\n  return at === 0 || at === text.length || /\\W/.test(around);\n}\nexport function wholeWords(text: string, queries: readonly string[]) {\n  const inside = ([start, end]: readonly [number, number]) =>\n    boundary(text, start) && boundary(text, end);\n  return matchRanges(text, queries).filter(inside);\n}\n\n// <span slHighlight text=\"Cabo de aço e cabos de rede\" query=\"cabo\" [matcher]=\"wholeWords\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "current",
+      "title": "The match a find bar is standing on",
+      "note": "current names one match by index, counting matches only, and that mark takes the accent’s solid ground and ink. The family never moves it: the arrows belong to the find bar, and scrolling to it is the consumer’s, through the element.",
+      "language": "html",
+      "source": "<span slHighlight [text]=\"clause\" query=\"fornecedor\" [current]=\"current()\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Disabled, from the root or from the row above it",
+      "note": "A disabled mark gives up the tone and keeps the rule, so the reader still sees which span matched on an option they cannot take. The state is read from data-disabled on the root or on any ancestor, so a host’s option says it once.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Cloudberry Logística\" query=\"berr\" disabled></span>\n\n<div data-disabled>\n  <span slHighlight text=\"Gooseberry Transportes\" query=\"berr\"></span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "context",
+      "title": "Where the family lives",
+      "note": "A supplier search: the results list is what combobox, select, multi-select and command-palette render, one root inside each label. The family is content inside a host; the host owns the row, the keyboard and the count.",
+      "language": "html",
+      "source": "<sl-combobox>\n  <sl-combobox-item value=\"acai\" label=\"Açaí do Vale Ltda.\"></sl-combobox-item>\n</sl-combobox>\n\n<!-- What the item renders once the reader has typed \"aca\": -->\n<span data-part=\"label\">\n  <span slHighlight text=\"Açaí do Vale Ltda.\" query=\"aca\"></span>\n</span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A run that wraps is two boxes and both carry the band; a mark inside Arabic sits where the logical indexes put it in either direction; a query inside a flag or a decomposed accent widens to the whole character; a thousand-character label with a one-letter query answers under a millisecond.",
+      "language": "html",
+      "source": "<span slHighlight text=\"Relatório consolidado anual de vendas\" query=\"consolidado anual\"></span>\n<span slHighlight text=\"شركة النور للتجارة\" query=\"النور\"></span>\n<span slHighlight text=\"🇧🇷 Brasil · Crème\" [query]=\"['bra', 'e']\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "The text is the text: the runs are slices of the string and nothing is hidden. mark is not announced by most screen readers by default, and the family injects no hidden “highlight start” — five matches in an option would be ten announcements.",
+      "language": "css",
+      "source": "/* In the application's own stylesheet, where the announcement is wanted. */\n[data-ui='highlight'] [data-part='match']::before {\n  content: ' [match] ';\n  clip-path: inset(100%);\n  position: absolute;\n}\n",
+      "verdict": "excerpt"
+    }
+  ]
+}