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

package/dist/docs/highlight.md

@@ -0,0 +1,209 @@
+<!-- index: ./index.md -->
+# highlight
+
+`data-ui="highlight"` · Marks matches of a query inside text.
+
+## Import
+
+```tsx
+import { Highlight, HighlightDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Highlight text="Açaí do Vale Ltda." query="aca" />;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | span | yes |
+| `match` | mark | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `text` | `string` | — | Highlight | 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[]` | — | Highlight | One query or several. Empty and whitespace-only entries find nothing; overlapping matches merge into one run |
+| `ranges` | `readonly [number, number][]` | — | Highlight | 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` | — | Highlight | Replaces the default collator scan. Receives the queries trimmed of empties; loses to ranges |
+| `occurrences` | `'all' \| 'first'` | all | Highlight | all marks every place a query appears; first marks one span per query |
+| `sensitivity` | `'base' \| 'accent' \| 'case' \| 'variant'` | base | Highlight | 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 | Highlight | BCP 47. Unset asks the runtime; a host passes the locale its filter used. Falls back to the provider |
+| `current` | `number` | null | Highlight | The match a find bar is standing on, counting matches only; that mark carries data-current. Out of range marks nothing |
+| `disabled` | `boolean` | false | Highlight | Writes data-disabled on the root: the marks give up the tone and keep the rule. Any ancestor’s data-disabled does the same |
+| `render` | `(props: HighlightRootProps) => ReactNode` | — | Highlight | Substitutes the root element and hands it the runs as children with every data attribute. The mark inside is fixed: it is the element that carries the semantics |
+| `ref` | `Ref<HTMLSpanElement>` | — | Highlight | Reaches the root. A find bar scrolls to its current match through it: querySelector("[data-current]").scrollIntoView() |
+| `…native` | `ComponentPropsWithRef<"span">` | — | Highlight | lang, dir, className, aria-* and every other native attribute reach the root |
+| `HighlightDefaultsProvider` | `{ locale, sensitivity, occurrences }` | — | a subtree | Sets all three once for everything below it; an explicit prop 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
+
+```tsx
+<Highlight text="Açaí do Vale Ltda." query="aca" />;
+<Highlight text="Résumé Serviços" query="RESUME" />;
+<Highlight text="Straße 12" query="strasse" />;
+<Highlight text="C++ Consultoria a.b" query="c++" />;
+```
+
+### 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
+
+```tsx
+<Highlight text="Banana Brasil Alimentos" query={['an', 'na']} />;
+<Highlight text="Nota fiscal nº 2026-0441" query={['nota', '0441']} />;
+```
+
+### 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
+
+```tsx
+<Highlight text="Ana Banana Santana" query="an" />;
+<Highlight text="Ana Banana Santana" query="an" occurrences="first" />;
+```
+
+### 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
+
+```tsx
+<Highlight text="Fornecedor homologado em 2024" ranges={[[11, 21]]} />;
+<Highlight
+  text="🇧🇷 Brasil Cabos"
+  ranges={[
+    [1, 2],
+    [12, 40],
+  ]}
+/>;
+```
+
+### 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
+
+```tsx
+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);
+}
+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);
+}
+
+<Highlight text="Cabo de aço e cabos de rede" query="cabo" matcher={wholeWords} />;
+```
+
+### 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 ref.
+
+Excerpt — not a complete module
+
+```tsx
+const [current, setCurrent] = useState(1);
+
+<Highlight text={clause} query="fornecedor" current={current} />;
+```
+
+### 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
+
+```tsx
+<Highlight text="Cloudberry Logística" query="berr" disabled />;
+
+<div data-disabled>
+  <Highlight text="Gooseberry Transportes" query="berr" />
+</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
+
+```tsx
+<Combobox>
+  <ComboboxItem value="acai">Açaí do Vale Ltda.</ComboboxItem>
+</Combobox>;
+
+// What the item renders once the reader has typed "aca":
+<span data-part="label">
+  <Highlight text="Açaí do Vale Ltda." query="aca" />
+</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
+
+```tsx
+<Highlight text="Relatório consolidado anual de vendas" query="consolidado anual" />;
+<Highlight text="شركة النور للتجارة" query="النور" />;
+<Highlight text="🇧🇷 Brasil · Crème" query={['bra', 'e']} />;
+```
+
+### 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/dist/docs/hover-card.json

@@ -0,0 +1,273 @@
+{
+  "family": "hover-card",
+  "ui": "hover-card",
+  "binding": "react",
+  "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 { HoverCard, HoverCardTrigger, HoverCardContent, HoverCardDefaultsProvider } from '@slotted/react';\nimport { PopoverBody, PopoverTitle, PopoverFooter } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "a, or the element render returns",
+          "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": "boolean | undefined",
+          "defaultValue": "—",
+          "appliesTo": "HoverCard",
+          "description": "Whether the card shows. Present at all puts the card in controlled mode: it asks and waits."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "HoverCard",
+          "description": "The value an uncontrolled card starts from, read once."
+        },
+        {
+          "name": "onOpenChange",
+          "type": "(open, request) => void",
+          "defaultValue": "—",
+          "appliesTo": "HoverCard",
+          "description": "Asked before the card opens or closes, with the reason and the originating event, and refusable."
+        },
+        {
+          "name": "openDelay",
+          "type": "number",
+          "defaultValue": "600",
+          "appliesTo": "HoverCard",
+          "description": "Milliseconds the pointer rests on the trigger before the card opens. Focus never waits."
+        },
+        {
+          "name": "closeDelay",
+          "type": "number",
+          "defaultValue": "300",
+          "appliesTo": "HoverCard",
+          "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": "HoverCard",
+          "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": "HoverCard",
+          "description": "The card never opens. The link keeps working, and carries no disabled state."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number",
+          "defaultValue": "4",
+          "appliesTo": "HoverCard",
+          "description": "The popover’s own axis, 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": "PopoverProps",
+          "defaultValue": "—",
+          "appliesTo": "HoverCard",
+          "description": "Every prop of Popover except autoFocus, which the family forces off, reaches the popover it renders."
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "HoverCardTrigger",
+          "description": "Renders the consumer's own element as the trigger — a Link, an avatar button — with the identity, the state and the listeners on it."
+        }
+      ],
+      "composition": [
+        {
+          "name": "HoverCardDefaultsProvider",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets openDelay, closeDelay, navigable and disabled once for a subtree. A card that states one itself still wins. The panel reads PopoverDefaultsProvider."
+        },
+        {
+          "name": "PopoverHeader, PopoverTitle, PopoverBody, PopoverFooter, PopoverClose, …",
+          "type": "components",
+          "defaultValue": "—",
+          "appliesTo": "Inside HoverCardContent",
+          "description": "The card is the popover family unchanged, and nothing is re-exported: its title names a navigable card, its Close is the touch reader’s Escape."
+        },
+        {
+          "name": "HoverCardContent",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Inside a HoverCard",
+          "description": "The popover’s layer and panel in one, with the family’s pointer handlers on the layer and the panel’s role decided by navigable. Its props reach the panel; the arrow is rendered under the popover’s arrow axis."
+        },
+        {
+          "name": "ref",
+          "type": "prop",
+          "defaultValue": "—",
+          "appliesTo": "HoverCard",
+          "description": "A PopoverHandle carrying open(), close() and reposition()."
+        },
+        {
+          "name": "native props",
+          "type": "attributes",
+          "defaultValue": "—",
+          "appliesTo": "HoverCardTrigger",
+          "description": "Anything an anchor takes — href, rel, target — reaches the link, and a consumer's own onPointerEnter or onFocus runs before the family's; preventDefault from it stops the family."
+        }
+      ],
+      "events": [
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: HoverCardChangeRequest)",
+          "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": "tsx",
+      "source": "<HoverCard>\n  <HoverCardTrigger href=\"/people/ana\">@ana.souza</HoverCardTrigger>\n  <HoverCardContent>\n    <PopoverBody>…</PopoverBody>\n  </HoverCardContent>\n</HoverCard>;\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": "tsx",
+      "source": "<HoverCard defaultOpen>\n  <HoverCardTrigger href=\"/people/ana\">@ana.souza</HoverCardTrigger>\n  <HoverCardContent>\n    <PopoverBody>\n      <Avatar name=\"Ana Souza\" />…\n    </PopoverBody>\n  </HoverCardContent>\n</HoverCard>;\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": "tsx",
+      "source": "<HoverCard>\n  <HoverCardTrigger href=\"/specs/checkout-pricing\">\n    Checkout redesign — pricing table\n  </HoverCardTrigger>\n  <HoverCardContent>\n    <PopoverHeader>\n      <PopoverTitle>Checkout redesign — pricing table</PopoverTitle>\n      <PopoverDescription>Product spec · updated 2 hours ago</PopoverDescription>\n    </PopoverHeader>\n    <PopoverBody>…</PopoverBody>\n  </HoverCardContent>\n</HoverCard>;\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": "tsx",
+      "source": "<HoverCard navigable>\n  <HoverCardTrigger href=\"/people/ana\">@ana.souza</HoverCardTrigger>\n  <HoverCardContent>\n    <PopoverHeader>\n      <PopoverTitle>Ana Souza</PopoverTitle>\n    </PopoverHeader>\n    <PopoverBody>…</PopoverBody>\n    <PopoverFooter>\n      <Button size=\"sm\">Follow</Button>\n    </PopoverFooter>\n  </HoverCardContent>\n</HoverCard>;\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": "tsx",
+      "source": "<HoverCard openDelay={0} closeDelay={1000}>\n  …\n</HoverCard>;\n\n<HoverCardDefaultsProvider openDelay={400}>\n  <App />\n</HoverCardDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shared",
+      "title": "One card, many mentions",
+      "note": "A thread with four handles and one HoverCard 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": "tsx",
+      "source": "const [handle, setHandle] = useState<string | null>(null);\n\n<HoverCard\n  onOpenChange={(open, request) => {\n    const target = (request.source as Event | undefined)?.currentTarget;\n    if (open && target instanceof HTMLElement) setHandle(target.dataset['handle'] ?? null);\n  }}\n>\n  <p>\n    <HoverCardTrigger data-handle=\"ana.souza\" href=\"/people/ana\">\n      @ana.souza\n    </HoverCardTrigger>{' '}\n    and{' '}\n    <HoverCardTrigger data-handle=\"marcus.lee\" href=\"/people/marcus\">\n      @marcus.lee\n    </HoverCardTrigger>\n  </p>\n  <HoverCardContent>{people[handle]}</HoverCardContent>\n</HoverCard>;\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": "tsx",
+      "source": "<HoverCard>\n  <HoverCardTrigger href=\"/people/ana\">@ana.souza</HoverCardTrigger>\n  <HoverCardContent>…</HoverCardContent>\n</HoverCard>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "On another family’s link",
+      "note": "The trigger rendered onto Link: the link keeps its own paint and its identity, and takes only the state and the listeners from this family. The Close part inside the card is the popover’s, and it is what a touch reader has in place of Escape.",
+      "language": "tsx",
+      "source": "<HoverCard>\n  <HoverCardTrigger href=\"/people/ana\" render={(props) => <Link {...props} variant=\"neutral\" />}>\n    Ana Souza\n  </HoverCardTrigger>\n  <HoverCardContent>\n    <PopoverHeader>\n      <PopoverTitle>Ana Souza</PopoverTitle>\n      <PopoverClose />\n    </PopoverHeader>\n  </HoverCardContent>\n</HoverCard>;\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": "tsx",
+      "source": "<HoverCard onOpenChange={(open, request) => log(request.reason)}>\n  <HoverCardTrigger href=\"/people/ana\">@ana.souza</HoverCardTrigger>\n  <HoverCardContent>…</HoverCardContent>\n</HoverCard>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}