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

package/docs/highlight.md

@@ -0,0 +1,210 @@
+<!-- index: ./index.md -->
+# highlight
+
+`data-ui="highlight"` · Marks matches of a query inside text.
+
+## Import
+
+```ts
+import { SlHighlight, provideHighlightDefaults } from '@slotted/angular/highlight';
+```
+
+Selector: `[slHighlight]` · exportAs: `slHighlight`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Açaí do Vale Ltda." query="aca"></span>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | span | yes |
+| `match` | mark | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `text` | `string` | — | SlHighlight | The text, whole. The only content the family renders; nothing in it is HTML, and every run is a slice of it |
+| `query` | `string \| readonly string[]` | — | SlHighlight | One query or several. Empty and whitespace-only entries find nothing; overlapping matches merge into one run |
+| `ranges` | `readonly [number, number][]` | — | SlHighlight | Spans already found, in the text’s own code units. Wins over query and matcher; clipped, ordered, merged and widened to graphemes |
+| `matcher` | `(text, queries) => ranges` | — | SlHighlight | Replaces the default collator scan. Receives the queries trimmed of empties; loses to ranges |
+| `occurrences` | `'all' \| 'first'` | all | SlHighlight | all marks every place a query appears; first marks one span per query |
+| `sensitivity` | `'base' \| 'accent' \| 'case' \| 'variant'` | base | SlHighlight | The collator’s own steps. base treats a, á and A as one letter, which is what typeahead and the filters compare at |
+| `locale` | `string` | null | SlHighlight | BCP 47. Unset asks the runtime; a host passes the locale its filter used. Falls back to provideHighlightDefaults |
+| `current` | `number` | null | SlHighlight | The match a find bar is standing on, counting matches only; that mark carries data-current. Out of range marks nothing |
+| `disabled` | `boolean` | false | SlHighlight | Writes data-disabled on the root: the marks give up the tone and keep the rule. Any ancestor’s data-disabled does the same |
+| `[slHighlight]` | `attribute selector` | — | SlHighlight | 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 |
+| `exportAs: slHighlight` | `SlHighlight` | — | SlHighlight | Reaches the instance: runs() is the list a find bar counts matches from |
+| `…native` | `attributes on the host element` | — | SlHighlight | 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 |
+| `provideHighlightDefaults` | `{ locale, sensitivity, occurrences }` | — | an injector | Sets all three once for everything below it; an explicit input on a mark still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `occurrences` | `all`, `first` | `all` |
+| `sensitivity` | `base`, `accent`, `case`, `variant` | `base` |
+
+## Rules
+
+- 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
+
+### A query, compared the way the reader’s locale compares
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Açaí do Vale Ltda." query="aca"></span>
+<span slHighlight text="Résumé Serviços" query="RESUME"></span>
+<span slHighlight text="Straße 12" query="strasse"></span>
+<span slHighlight text="C++ Consultoria a.b" query="c++"></span>
+```
+
+### Several queries at once
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Banana Brasil Alimentos" [query]="['an', 'na']"></span>
+<span slHighlight text="Nota fiscal nº 2026-0441" [query]="['nota', '0441']"></span>
+```
+
+### Every occurrence, or the first
+
+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”.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Ana Banana Santana" query="an"></span>
+<span slHighlight text="Ana Banana Santana" query="an" occurrences="first"></span>
+```
+
+### Spans a server already found
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Fornecedor homologado em 2024" [ranges]="[[11, 21]]"></span>
+<span
+  slHighlight
+  text="🇧🇷 Brasil Cabos"
+  [ranges]="[
+    [1, 2],
+    [12, 40],
+  ]"
+></span>
+```
+
+### A matcher of the consumer’s own
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+import { matchRanges } from '@slotted/core/highlight';
+
+function boundary(text: string, at: number) {
+  const around = text.slice(Math.max(0, at - 1), at + 1);
+  return at === 0 || at === text.length || /\W/.test(around);
+}
+export function wholeWords(text: string, queries: readonly string[]) {
+  const inside = ([start, end]: readonly [number, number]) =>
+    boundary(text, start) && boundary(text, end);
+  return matchRanges(text, queries).filter(inside);
+}
+
+// <span slHighlight text="Cabo de aço e cabos de rede" query="cabo" [matcher]="wholeWords"></span>
+```
+
+### The match a find bar is standing on
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight [text]="clause" query="fornecedor" [current]="current()"></span>
+```
+
+### Disabled, from the root or from the row above it
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Cloudberry Logística" query="berr" disabled></span>
+
+<div data-disabled>
+  <span slHighlight text="Gooseberry Transportes" query="berr"></span>
+</div>
+```
+
+### Where the family lives
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<sl-combobox>
+  <sl-combobox-item value="acai" label="Açaí do Vale Ltda."></sl-combobox-item>
+</sl-combobox>
+
+<!-- What the item renders once the reader has typed "aca": -->
+<span data-part="label">
+  <span slHighlight text="Açaí do Vale Ltda." query="aca"></span>
+</span>
+```
+
+### Content the family did not choose
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<span slHighlight text="Relatório consolidado anual de vendas" query="consolidado anual"></span>
+<span slHighlight text="شركة النور للتجارة" query="النور"></span>
+<span slHighlight text="🇧🇷 Brasil · Crème" [query]="['bra', 'e']"></span>
+```
+
+### What a reader hears
+
+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.
+
+Excerpt — not a complete module
+
+```css
+/* In the application's own stylesheet, where the announcement is wanted. */
+[data-ui='highlight'] [data-part='match']::before {
+  content: ' [match] ';
+  clip-path: inset(100%);
+  position: absolute;
+}
+```

package/docs/hover-card.json

@@ -0,0 +1,254 @@
+{
+  "family": "hover-card",
+  "ui": "hover-card",
+  "binding": "angular",
+  "catalog": {
+    "group": "Overlays",
+    "summary": "Preview card that opens on hover or focus."
+  },
+  "axes": {
+    "navigable": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "hoverCard": {
+      "nativeElement": "a",
+      "defaults": {
+        "navigable": false,
+        "disabled": false,
+        "openDelay": 600,
+        "closeDelay": 300,
+        "sideOffset": 4
+      },
+      "capabilities": [
+        "open",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "open"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "hoverCard": {
+      "imports": {
+        "source": "import { SlHoverCard, SlHoverCardTrigger, provideHoverCardDefaults } from '@slotted/angular/hover-card';\nimport { SlPopoverLayer, SlPopoverContent, SlPopoverBody } from '@slotted/angular/popover';",
+        "selector": "[slHoverCard], [slHoverCardTrigger]",
+        "exportAs": "slHoverCard"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "a[slHoverCardTrigger], the consumer’s own anchor",
+          "required": true,
+          "purpose": "The trigger: the link the card is about. It carries data-ui=\"hover-card\", data-open while its card shows, and — only when the card is navigable — aria-haspopup=\"dialog\", aria-expanded and aria-controls. The card itself is the popover family unchanged, data-ui=\"popover\", so this family declares no other part."
+        }
+      ],
+      "api": [
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "slHoverCard",
+          "description": "Whether the card shows. Two-way: [(open)] on the container; a bound [open] alone makes the card controlled."
+        },
+        {
+          "name": "openDelay",
+          "type": "number",
+          "defaultValue": "600",
+          "appliesTo": "slHoverCard",
+          "description": "Milliseconds the pointer rests on the trigger before the card opens. Focus never waits."
+        },
+        {
+          "name": "closeDelay",
+          "type": "number",
+          "defaultValue": "300",
+          "appliesTo": "slHoverCard",
+          "description": "Milliseconds after the pointer has left trigger and card before it closes; a pointer on its way to the card is not counted as gone."
+        },
+        {
+          "name": "navigable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slHoverCard",
+          "description": "Whether the card holds controls a keyboard reader can reach. On, the panel is a dialog, the link announces it and Tab enters it; off, the panel is presentation."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slHoverCard",
+          "description": "The card never opens. The link keeps working, and carries no disabled state."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number",
+          "defaultValue": "4",
+          "appliesTo": "slHoverCard",
+          "description": "The popover’s own input, with the family’s default: the halo the open mark draws plus the same again of air, so the arrow’s tip stands off the word."
+        },
+        {
+          "name": "side, align, size, width, arrow, mount, …",
+          "type": "SlPopover inputs",
+          "defaultValue": "—",
+          "appliesTo": "slHoverCard",
+          "description": "Every input of slPopover except autoFocus, which the family forces off: slHoverCard extends SlPopover and provides itself as one."
+        }
+      ],
+      "composition": [
+        {
+          "name": "provideHoverCardDefaults()",
+          "type": "provider",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets openDelay, closeDelay and navigable once for an injector. A card that states one itself still wins; the panel reads providePopoverDefaults()."
+        },
+        {
+          "name": "slPopoverLayer, slPopoverContent, slPopoverBody, slPopoverClose, …",
+          "type": "directives",
+          "defaultValue": "—",
+          "appliesTo": "Inside slHoverCard",
+          "description": "The card is the popover family unchanged, and nothing is re-exported: slHoverCard provides itself as SlPopover, so every popover part inside it reaches the card. The panel’s role follows navigable."
+        },
+        {
+          "name": "exportAs",
+          "type": "template reference",
+          "defaultValue": "—",
+          "appliesTo": "slHoverCard",
+          "description": "A template reaches the card — #card=\"slHoverCard\" — for show(), hide() and the resolved delays; the trigger as #mention=\"slHoverCardTrigger\"."
+        },
+        {
+          "name": "many triggers",
+          "type": "composition",
+          "defaultValue": "—",
+          "appliesTo": "slHoverCard",
+          "description": "Several a[slHoverCardTrigger] inside one container share one card; the one that starts an opening registers itself as the anchor."
+        },
+        {
+          "name": "host attributes",
+          "type": "attributes",
+          "defaultValue": "—",
+          "appliesTo": "slHoverCardTrigger",
+          "description": "The trigger is the consumer’s own anchor: href, rel and target are theirs, and a data-part they wrote is kept beside the identity."
+        }
+      ],
+      "events": [
+        {
+          "name": "openChangeRequest",
+          "payload": "ChangeRequest<boolean>",
+          "when": "Before the card opens or closes. The request carries pointer (hover in, hover out, a tap), keyboard (focus arriving, a focus guard), escape, outsidePress, blur (focus leaving the trigger), dismiss (the Close part) or programmatic, the originating event, and cancel()."
+        }
+      ],
+      "accessibility": [
+        "The platform supplies the link: it is a native anchor, so Enter follows it, a middle click opens it in a tab and a screen reader hears a link. The card never takes focus when it opens — autoFocus is forced off on the popover it holds — so the reader’s focus stays on the word under the pointer.",
+        "The family answers WCAG 2.2 SC 1.4.13 item by item: the card is dismissible with Escape and no pointer movement, hoverable because the pointer may move onto it and the grace area keeps it open on the way, and persistent because it stays until hover and focus have left both link and card.",
+        "A card the keyboard cannot enter is role=\"presentation\" and the link says nothing about it, because a popup the announced means cannot reach would be a lie a screen reader repeats. A navigable card is the APG’s non-modal dialog, named by its title, with aria-haspopup=\"dialog\", aria-expanded and aria-controls on the link, and Tab from the link enters it.",
+        "Focus the family itself puts back on the link — after Escape inside the card, after a focus guard — does not reopen the card; the link holds the reopening back until focus has left it once. Without that rule a guard would close the card, focus the link, and open the card again."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-width-thick",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-highlight-tint-opacity",
+    "--slotted-hover-card-color",
+    "--slotted-hover-card-halo",
+    "--slotted-hover-card-radius",
+    "--slotted-hover-card-tint",
+    "--slotted-hover-card-underline-color",
+    "--slotted-radius-xs",
+    "--slotted-space-1",
+    "--slotted-tone-accent-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Rest the pointer on the mention, or Tab to it: the card opens after the delay under the pointer and at once under focus. The controls under the canvas move both delays and make the card navigable.",
+      "language": "html",
+      "source": "<ng-container slHoverCard>\n  <a slHoverCardTrigger href=\"/people/ana\">&#64;ana.souza</a>\n  <ng-template slPopoverLayer>\n    <div slPopoverContent>\n      <div slPopoverBody>…</div>\n      <div slPopoverArrow></div>\n    </div>\n  </ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "mention",
+      "title": "A person",
+      "note": "The card a review thread shows for a handle: avatar, name, team and what they own, under the word it is about. While it shows, the word carries a tint and a halo that grow the inline box without moving the line — the sentence under it has not shifted.",
+      "language": "html",
+      "source": "<ng-container slHoverCard [open]=\"true\">\n  <a slHoverCardTrigger href=\"/people/ana\">&#64;ana.souza</a>\n  <ng-template slPopoverLayer>\n    <div slPopoverContent>\n      <div slPopoverBody>\n        <span slAvatar name=\"Ana Souza\"></span>\n        …\n      </div>\n    </div>\n  </ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "link-preview",
+      "title": "A document",
+      "note": "The card a link to a spec shows: its title, who touched it last and its first lines. The trigger stays a link — Enter follows it, a middle click opens it in a tab — and the card adds nothing the destination does not have.",
+      "language": "html",
+      "source": "<ng-container slHoverCard>\n  <a slHoverCardTrigger href=\"/specs/checkout-pricing\">Checkout redesign — pricing table</a>\n  <ng-template slPopoverLayer>\n    <div slPopoverContent>\n      <div slPopoverHeader>\n        <div slPopoverTitle>Checkout redesign — pricing table</div>\n        <p slPopoverDescription>Product spec · updated 2 hours ago</p>\n      </div>\n      <div slPopoverBody>…</div>\n    </div>\n  </ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "navigable",
+      "title": "Navigable",
+      "note": "The card holds a control, so the page says so with navigable: the panel becomes a dialog named by its title, the link announces the popup, and Tab from the open link enters the card. Past its last control a focus guard closes it and puts focus back on the link, which does not reopen.",
+      "language": "html",
+      "source": "<ng-container slHoverCard navigable>\n  <a slHoverCardTrigger href=\"/people/ana\">&#64;ana.souza</a>\n  <ng-template slPopoverLayer>\n    <div slPopoverContent>\n      <div slPopoverHeader><div slPopoverTitle>Ana Souza</div></div>\n      <div slPopoverBody>…</div>\n      <div slPopoverFooter><button slButton size=\"sm\">Follow</button></div>\n    </div>\n  </ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "delay",
+      "title": "The delays",
+      "note": "Two of the same card: the left opens after the default 600 ms and closes 300 ms after the pointer has left; the right answers at once and holds for a second, for a page where the preview is the point. Focus never waits on either.",
+      "language": "html",
+      "source": "<ng-container slHoverCard [openDelay]=\"0\" [closeDelay]=\"1000\">…</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shared",
+      "title": "One card, many mentions",
+      "note": "A thread with four handles and one slHoverCard around all of them. The mention the pointer rests on registers itself as the anchor, and the request carries the event whose currentTarget names the person, so the card fills from one state instead of mounting four.",
+      "language": "html",
+      "source": "<ng-container slHoverCard (openChangeRequest)=\"remember($event)\">\n  <p>\n    <a slHoverCardTrigger data-handle=\"ana.souza\" href=\"/people/ana\">&#64;ana.souza</a>\n    and\n    <a slHoverCardTrigger data-handle=\"marcus.lee\" href=\"/people/marcus\">&#64;marcus.lee</a>\n  </p>\n  <ng-template slPopoverLayer>\n    <div slPopoverContent>{{ people[handle()] }}</div>\n  </ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "touch",
+      "title": "On touch",
+      "note": "There is no hover on a touch screen: the first tap on the mention opens the card instead of following the link, and a tap on the open mention follows it. The cost is one extra tap to navigate; the alternative is a preview no touch reader ever sees.",
+      "language": "html",
+      "source": "<ng-container slHoverCard>\n  <a slHoverCardTrigger href=\"/people/ana\">&#64;ana.souza</a>\n  <ng-template slPopoverLayer><div slPopoverContent>…</div></ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "On the consumer’s own link",
+      "note": "The trigger is a component on the consumer’s anchor, and two components do not share one element: a[slLink] cannot also carry it, so the family paints the link itself and a data-part the consumer wrote is kept. The Close part inside the card is the popover’s, and it is what a touch reader has in place of Escape.",
+      "language": "html",
+      "source": "<ng-container slHoverCard>\n  <a slHoverCardTrigger href=\"/people/ana\" data-part=\"mention\">Ana Souza</a>\n  <ng-template slPopoverLayer>\n    <div slPopoverContent>\n      <div slPopoverHeader>\n        <div slPopoverTitle>Ana Souza</div>\n        <button slPopoverClose></button>\n      </div>\n    </div>\n  </ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "From the keyboard",
+      "note": "Tab onto the mention: the card opens in the same task, without the pointer's delay. Escape closes it and leaves focus where it is, and the mention does not reopen until focus has left it once. Tab on moves focus down the page and closes the card with the reason blur.",
+      "language": "html",
+      "source": "<ng-container slHoverCard (openChangeRequest)=\"log($event.reason)\">\n  <a slHoverCardTrigger href=\"/people/ana\">&#64;ana.souza</a>\n  <ng-template slPopoverLayer><div slPopoverContent>…</div></ng-template>\n</ng-container>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}