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

package/dist/docs/kbd.md

@@ -0,0 +1,216 @@
+<!-- index: ./index.md -->
+# kbd
+
+`data-ui="kbd"` · Keyboard key or shortcut.
+
+## Import
+
+```tsx
+import { Kbd, KbdDefaultsProvider, Shortcut } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Kbd keyName="mod" />;
+
+// Or a word this library has never heard of.
+<Kbd>Any key</Kbd>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | kbd | yes |
+| `legend` | span | yes |
+| `name` | span | no |
+| `shortcut` | kbd | no |
+| `separator` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `keyName` | `string` | — | Kbd | A token from the vocabulary — mod, meta, ctrl, alt, shift, fn, enter, escape, tab, space, backspace, delete, capslock, pageup, pagedown, home, end, plus, up, down, left, right — or an alias such as cmd, option, esc or arrowup. Wins over children where both are written |
+| `keys` | `string` | — | Shortcut | The whole combination: + joins keys pressed together, whitespace joins the steps of a sequence |
+| `platform` | `'auto' \| 'mac' \| 'windows' \| 'linux' \| 'other'` | auto | Kbd, Shortcut | Which keyboard the legends are drawn for. auto reads the browser; state it where the page is server-rendered |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'inherit'` | md | Kbd, Shortcut | xs to lg are fixed heights of 16, 20, 24 and 28 pixels whose legend answers density; inherit reads the text around the key and stays inside its line |
+| `variant` | `'raised' \| 'outline' \| 'soft' \| 'plain'` | raised | Kbd, Shortcut | raised is a key with a bottom edge, outline owns no ground, soft is the tinted chip, plain takes the colour of the text it sits in |
+| `disabled` | `boolean` | false | Kbd, Shortcut | Dims the key without writing aria-disabled, which kbd may not carry. The item the shortcut belongs to owns the semantics |
+| `separator` | `string` | + | Shortcut | Between two simultaneous keys. A Mac joins with nothing whatever this says |
+| `messages` | `PartialMessages<KeysMessages>` | — | Kbd, Shortcut | Words laid over the keys catalog of the language in force, key by key: legends.*, names.*, and then — the word between two steps of a sequence, read aloud |
+| `legends` | `Record<string, string>` | — | Shortcut | Replaces what the eye sees, per key token: { ctrl: "Strg" }. Falls back to the provider |
+| `names` | `Record<string, string>` | — | Shortcut | Replaces what a reader hears, per key token: { ctrl: "Steuerung" }. Falls back to the provider |
+| `children` | `ReactNode` | — | Kbd | The legend written verbatim — the application’s own word, neither resolved nor given a hidden name |
+| `children` | `ReactNode` | — | Shortcut | Keys authored one by one. They are rendered in the order written, which is the way out of the platform reordering |
+| `render` | `(props: KbdRootProps) => ReactNode` | — | Kbd, Shortcut | Substitutes the rendered element. Every data attribute and every part are handed to it |
+| `ref` | `Ref<HTMLElement>` | — | Kbd, Shortcut | Reaches the kbd element. There is no imperative handle beyond it: the family has no action a page cannot express declaratively |
+| `KbdDefaultsProvider` | `{ platform, size, variant, separator, legends, names }` | — | a subtree | Sets all six once for everything below it; an explicit prop on a key still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `xs`, `sm`, `md`, `lg`, `inherit` | `md` |
+| `variant` | `raised`, `outline`, `soft`, `plain` | `raised` |
+| `platform` | `auto`, `mac`, `windows`, `linux`, `other` | `auto` |
+
+## Rules
+
+- There is no kbd pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry — and ARIA in HTML (W3C Recommendation, 11 August 2026) maps the kbd element to no corresponding role and declares it Naming Prohibited. The family therefore writes no role, no aria-label and no aria-disabled, and every word a reader hears is content.
+- A key in the vocabulary hides its legend with aria-hidden and carries the word in a name part the family clips from view itself. ⌘ is U+2318 PLACE OF INTEREST SIGN and would otherwise be read as one; Ctrl is an abbreviation whose pronunciation belongs to the screen reader’s dictionary. Both are announced “Control” or “Command” here.
+- The plus between two keys is aria-hidden — it is punctuation joining two caps, and “Command Shift K” is what the operating systems announce for the same shortcut. The word between two steps of a sequence is not hidden, because it is the only thing that distinguishes “G then I” from “G and I together”.
+- Nothing here is focusable and nothing here binds a key. WCAG 2.2 2.1.4 Character Key Shortcuts belongs to whoever registers the shortcut, because only the application knows whether a single-character shortcut can be turned off.
+- The keys inside a combination keep their left-to-right order in a right-to-left document. A combination is one formula, the bidi algorithm renders the same string as one left-to-right run inside an Arabic paragraph, and a mirrored K + ⌘ is a shortcut no operating system displays. The combination as a whole still sits where the paragraph puts it.
+- An arrow legend is never mirrored: ← is the physical Left arrow key, not a direction of travel.
+- A key label is never truncated. A shortcut too wide for its column wraps between caps and never inside one, because half a key name is a wrong instruction where a wrapped shortcut is only a taller row.
+- The legends and the spoken names are both replaceable, per application through the provider and per shortcut through legends and names, so Strg, Échap and Entrar are one decision rather than one per shortcut.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-inner-size`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-font-family-sans`, `--slotted-font-weight-medium`, `--slotted-kbd-base-width`, `--slotted-kbd-border-width`, `--slotted-kbd-font-family`, `--slotted-kbd-font-weight`, `--slotted-kbd-radius`, `--slotted-kbd-symbol-font-family`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`
+
+## Examples
+
+### How the key is painted
+
+raised is the only value that looks like an object; outline owns no ground, so it survives on a solid surface where raised would cut a white hole.
+
+Excerpt — not a complete module
+
+```tsx
+<Shortcut keys="mod+b" />;
+<Shortcut keys="mod+b" variant="outline" />;
+<Shortcut keys="mod+b" variant="soft" />;
+<Shortcut keys="mod+b" variant="plain" />;
+```
+
+### How large the key is
+
+Four absolute heights, 16, 20, 24 and 28 pixels, that no legend and no variant changes; the legend reads the control type scale, so it shrinks with density inside the same box. xs fits a caption or a tooltip. inherit reads the text around it and stays inside its line, which is the step a heading and a footnote both need.
+
+Excerpt — not a complete module
+
+```tsx
+<Kbd keyName="escape" size="xs" />;
+<Kbd keyName="escape" size="sm" />;
+<Kbd keyName="escape" size="lg" />;
+
+<h2>
+  Press <Kbd keyName="escape" size="inherit" /> to close
+</h2>;
+```
+
+### A whole combination
+
+One kbd nested inside another, which is what the HTML Standard says a combination is. The plus is a part of its own, so an application can restyle or replace it.
+
+Excerpt — not a complete module
+
+```tsx
+<Shortcut keys="mod+shift+p" />;
+```
+
+### The same string on three keyboards
+
+The modifiers are reordered into each platform’s own convention and the legends redrawn; on a Mac the separator is not rendered at all, because a Mac joins with nothing.
+
+Excerpt — not a complete module
+
+```tsx
+<Shortcut keys="mod+shift+alt+p" platform="mac" />;
+<Shortcut keys="mod+shift+alt+p" platform="windows" />;
+
+// Left to itself it asks the reader’s browser.
+<Shortcut keys="mod+shift+alt+p" />;
+```
+
+### One key after another
+
+Whitespace between two groups is a step break, so “g i” is G then I. The word is read aloud where the plus is not, because it is the only thing that tells a sequence from a chord.
+
+Excerpt — not a complete module
+
+```tsx
+<Shortcut keys="g i" />;
+<Shortcut keys="mod+k mod+s" />;
+```
+
+### Where a shortcut actually lives
+
+A menu, where the label takes the room and the shortcut takes the end of the row. plain inherits the row’s colour, so a row that dims dims its shortcut with no state to set.
+
+Excerpt — not a complete module
+
+```tsx
+<li>
+  <span>Open command palette</span>
+  <Shortcut keys="mod+k" variant="plain" />
+</li>;
+```
+
+### Available and unavailable
+
+disabled dims the ground, the rim and the ink, and writes no aria-disabled: kbd may carry only the global ARIA attributes, so the item owns the semantics.
+
+Excerpt — not a complete module
+
+```tsx
+<Shortcut keys="mod+z" />;
+<Shortcut disabled keys="mod+z" />;
+```
+
+### Content the family did not choose
+
+The longest real key name, a German legend replaced through the provider, and a four-key combination in a 320-pixel column: it wraps between caps and never inside one.
+
+Excerpt — not a complete module
+
+```tsx
+<KbdDefaultsProvider
+  legends={{ ctrl: 'Strg', shift: 'Umschalt', delete: 'Entf' }}
+  names={{ ctrl: 'Steuerung', delete: 'Entfernen' }}
+  platform="windows"
+>
+  <Shortcut keys="mod+shift+delete" />
+</KbdDefaultsProvider>;
+```
+
+### Composition and escape hatches
+
+Keys written by hand are rendered in the order written, which is the way out of the platform reordering. render substitutes the element, and the provider decides for a whole application.
+
+Excerpt — not a complete module
+
+```tsx
+<Shortcut>
+  <Kbd keyName="mod" />
+  <Kbd>K</Kbd>
+</Shortcut>;
+
+<Kbd keyName="escape" render={(props) => <abbr {...props} />} />;
+
+<KbdDefaultsProvider platform="mac" size="sm" variant="plain">
+  <App />
+</KbdDefaultsProvider>;
+```
+
+### What a reader hears
+
+Every mark and every abbreviation hides its legend and carries the word beside it, so ⌘ is announced “Command” rather than “place of interest sign” and Ctrl is not left to a pronunciation dictionary.
+
+Excerpt — not a complete module
+
+```tsx
+// “Command Shift K”
+<Shortcut keys="mod+shift+k" platform="mac" />;
+
+// “G then I”
+<Shortcut keys="g i" />;
+
+// “Any key” — a word the page wrote, so the page owns it.
+<Kbd>Any key</Kbd>;
+```

package/dist/docs/link.json

@@ -0,0 +1,269 @@
+{
+  "family": "link",
+  "ui": "link",
+  "binding": "react",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Text link to another page or resource."
+  },
+  "axes": {
+    "underline": [
+      "always",
+      "hover",
+      "none"
+    ],
+    "variant": [
+      "accent",
+      "neutral",
+      "inverse"
+    ]
+  },
+  "members": {
+    "link": {
+      "nativeElement": "a",
+      "defaults": {
+        "underline": "always",
+        "variant": "accent",
+        "visited": false,
+        "external": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "appearance",
+        "underline",
+        "external",
+        "disabled"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "external-icon",
+        "external-hint"
+      ]
+    }
+  },
+  "docs": {
+    "link": {
+      "imports": {
+        "source": "import { Link, LinkDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "a",
+          "required": true,
+          "purpose": "The link itself. Carries data-ui=\"link\", the axes as data attributes, and every native anchor attribute the consumer passes."
+        },
+        {
+          "part": "external-icon",
+          "element": "span",
+          "required": false,
+          "purpose": "The marker a new tab earns: the external Glyph inside a directional icon box, sized to the text and hidden from assistive technology. Rendered only when the resolved target is _blank."
+        },
+        {
+          "part": "external-hint",
+          "element": "span",
+          "required": false,
+          "purpose": "The same warning in words, clipped from view and appended to the accessible name. Rendered with the visually-hidden family."
+        }
+      ],
+      "api": [
+        {
+          "name": "underline",
+          "type": "'always' | 'hover' | 'none'",
+          "defaultValue": "always",
+          "appliesTo": "Link",
+          "description": "When the underline is drawn"
+        },
+        {
+          "name": "variant",
+          "type": "'accent' | 'neutral' | 'inverse'",
+          "defaultValue": "accent",
+          "appliesTo": "Link",
+          "description": "Accent, the colour of the surrounding text, or a solid surface"
+        },
+        {
+          "name": "external",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Link",
+          "description": "Opens a new tab and warns that it does"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<LinkMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Link",
+          "description": "Words laid over the language in force: the wording of that warning (externalHint)"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Link",
+          "description": "Withholds the destination, keeps the role, the state and the tab stop"
+        },
+        {
+          "name": "visited",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Link",
+          "description": "Paints a destination the reader already followed"
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Link",
+          "description": "The destination, and every other anchor attribute — target, rel, download, hreflang — reaches the element unchanged"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: LinkRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Link",
+          "description": "Substitutes the rendered element. The destination and every data attribute are handed to it, so a router link keeps both."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLAnchorElement>",
+          "defaultValue": "—",
+          "appliesTo": "Link",
+          "description": "Reaches the anchor, and focus() with it"
+        },
+        {
+          "name": "onClick, onAuxClick, onKeyDown",
+          "type": "EventHandler",
+          "defaultValue": "—",
+          "appliesTo": "Link",
+          "description": "Composed rather than replaced. While disabled the family refuses first and the handler is not called."
+        },
+        {
+          "name": "LinkDefaultsProvider",
+          "type": "underline | variant | visited",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets those three once for everything below it; a prop on the link still wins"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The rendered element is a plain anchor with an href, so the link role, Enter, the context menu and every modified click come from the platform. Space does not activate a link, and nothing here makes it.",
+        "underline=\"always\" is the default because colour alone does not distinguish a link: the accent text colour clears 4.5:1 against the surface and not 3:1 against the body text beside it.",
+        "variant=\"neutral\" takes the colour of the text around it, so it belongs where nothing on the line could be mistaken for it — a cell, a title, a row — and never inside a sentence.",
+        "Whatever the underline axis says, the underline returns under forced-colors, where the palette flattens the colour contrast a bare link relies on.",
+        "A new browsing context is announced in the accessible name and marked with a glyph, and both follow the resolved target: a target=\"_blank\" written by hand is warned about exactly like external.",
+        "external also sets rel=\"noopener noreferrer\"; a rel or target the consumer passed is kept instead of rewritten.",
+        "A disabled link renders no href, which is what stops a middle click as well as a left one, and keeps role=\"link\", aria-disabled and its place in the tab sequence so the state can be discovered.",
+        "The current page is painted from aria-current, the attribute a router already writes; the family invents no prop for it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-radius",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-link-color",
+    "--slotted-link-color-active",
+    "--slotted-link-color-current",
+    "--slotted-link-color-disabled",
+    "--slotted-link-color-hover",
+    "--slotted-link-color-visited",
+    "--slotted-link-external-icon-gap",
+    "--slotted-link-external-icon-size",
+    "--slotted-link-focus-ring-offset",
+    "--slotted-link-radius",
+    "--slotted-link-underline-color",
+    "--slotted-link-underline-offset",
+    "--slotted-link-underline-thickness",
+    "--slotted-text",
+    "--slotted-text-inverse",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Every axis on one link inside a sentence, driven by the controls below the canvas. Change underline and watch what a reader has left to recognize the link by.",
+      "language": "tsx",
+      "source": "<p>\n  Read the <Link href=\"/terms\">terms of service</Link> before continuing.\n</p>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "underline",
+      "title": "When the underline is drawn",
+      "note": "always is the default and the only value safe inside a sentence: the accent text colour clears 4.5:1 against the surface but not 3:1 against the body text beside it.",
+      "language": "tsx",
+      "source": "<Link href=\"/invoices\">Underlined always</Link>;\n<Link href=\"/invoices\" underline=\"hover\">\n  Underlined on hover\n</Link>;\n<Link href=\"/invoices\" underline=\"none\">\n  Never underlined\n</Link>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "How the link is painted",
+      "note": "accent invites, neutral takes the colour of the text around it for a cell or a title, and inverse is the link on a solid surface. Hover moves each one toward the strongest text colour its context has.",
+      "language": "tsx",
+      "source": "<Link href=\"/history\">payment history</Link>;\n<Link href=\"/invoices/0041\" underline=\"hover\" variant=\"neutral\">\n  INV-2026-08-0041\n</Link>;\n<Link href=\"/plans\" variant=\"inverse\">\n  Choose a plan\n</Link>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "external",
+      "title": "Leaving the application",
+      "note": "One fact told three ways: the safe rel, the marker for the eye, the warning in the accessible name. All three follow the resolved target, so a target written by hand is announced the same way.",
+      "language": "tsx",
+      "source": "<Link external href=\"https://example.com/docs\">\n  Documentation\n</Link>;\n\n// The same warning, from the attribute instead of the prop.\n<Link href=\"https://example.com/docs\" target=\"_blank\">\n  Documentation\n</Link>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Hover darkens the text and fills the underline, press goes one step further, and an unavailable link keeps its underline so it still reads as a link rather than as plain text.",
+      "language": "tsx",
+      "source": "<Link href=\"/invoices\">At rest</Link>;\n<Link href=\"/invoices\" visited>\n  Followed before\n</Link>;\n<Link disabled href=\"/invoices/0042\">\n  Unavailable until the invoice is issued\n</Link>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "current",
+      "title": "The page you are on",
+      "note": "aria-current is the input, because it is the attribute a router already writes. The link takes the body colour and keeps its underline, and no width changes, so the column beside it does not shift.",
+      "language": "tsx",
+      "source": "<nav aria-label=\"Workspace\">\n  <Link aria-current=\"page\" href=\"/invoices\" underline=\"hover\">\n    Invoices\n  </Link>\n  <Link href=\"/members\" underline=\"hover\">\n    Members\n  </Link>\n</nav>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the link did not choose",
+      "note": "A pasted URL with no spaces, a long German compound, and an Arabic sentence. The first two break inside the column instead of widening it; the third mirrors the marker without mirroring the Latin island beside it.",
+      "language": "tsx",
+      "source": "<Link href=\"/reconciliation\">\n  https://billing.example.com/accounts/8412/invoices/2026-08/reconciliation-report\n</Link>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "note": "render substitutes the element for a router link and hands it the destination, and LinkDefaultsProvider decides for a whole application what a link looks like. An explicit prop still wins over both.",
+      "language": "tsx",
+      "source": "<Link href=\"/invoices\" render={(props) => <RouterLink {...props} to={props.href} />}>\n  Invoices\n</Link>;\n\n<LinkDefaultsProvider underline=\"hover\">\n  <App />\n</LinkDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "Keyboard and announcement",
+      "note": "Tab reaches every link including the unavailable one, Enter follows the one that has a destination, and Space does nothing because Space does not activate a link.",
+      "language": "tsx",
+      "source": "<Link href=\"/invoices\">A link with a destination</Link>;\n<Link external href=\"https://example.com/status\">\n  A link that leaves the application\n</Link>;\n<Link disabled href=\"/invoices/0042\">\n  A link that is unavailable\n</Link>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}