@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/PasswordInput.md

@@ -0,0 +1,45 @@
+# `<PasswordInput>` — password field with eye toggle + optional warnings
+
+```tsx
+<PasswordInput name="password" placeholder="Password" />
+<PasswordInput capsLockWarning wrongLayoutWarning name="password" required />
+<PasswordInput revealable={false} placeholder="Locked-down (no toggle)" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Field height + type scale. Same scale as `<Input>`. Defaults to `'md'`. |
+| `invalid` | `boolean` | no | Toggles the error visual + sets `aria-invalid="true"`. |
+| `revealed` | `boolean` | no | Controlled revealed state. Pair with `onRevealChange`. |
+| `defaultRevealed` | `boolean` | no | Initial revealed state for uncontrolled use. Defaults to `false`. |
+| `onRevealChange` | `((revealed: boolean) => void)` | no | Called when the user clicks the eye toggle. Receives the next revealed state. |
+| `revealable` | `boolean` | no | Whether to render the eye toggle button. Defaults to `true`. Set `revealable={false}` for compliance / kiosk screens where revealing is forbidden — the input then behaves like a plain locked-down `<input type='password'>`. |
+| `capsLockWarning` | `boolean` | no | Opt-in caps-lock detection. When `true`, on every keypress the input reads `event.getModifierState('CapsLock')`; when active, a warning icon + polite `aria-live` announce it. Cleared on blur. Defaults to `false`. Opt in on screens where caps-lock matters (login, password creation, password confirmation). |
+| `wrongLayoutWarning` | `boolean` | no | Opt-in wrong-keyboard-layout detection. When `true`, detects keystrokes that produce non-ASCII single characters (e.g., Cyrillic `ф` from a Russian layout). Shows a warning icon + polite live region. Cleared on blur. Heuristic, not deterministic — any non-ASCII keystroke triggers. Only enable when the system expects Latin-only password input. Defaults to `false`. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Renders a real `<input type='password' | 'text'>` underneath — full autofill, RHF/Zod, form-submission integration.
+- Eye toggle (`Eye` / `EyeOff`) flips `type`; `aria-pressed` exposes the state to AT. Toggle aria-labels come from `passwordInput.show` / `passwordInput.hide` in the i18n catalog.
+- Both warnings can stack — they render in separate slots with separate live regions.
+- Sizes: `sm` / `md` (default) / `lg`. Same scale as `<Input>`.
+- `Omit<…, 'size' | 'type'>` — component locks `type` to password/text and shadows native `size`.
+
+Pair with `<PasswordStrengthMeter>` for the canonical signup form, and controlled reveal via `revealed` / `onRevealChange`:
+
+```tsx
+<PasswordInput name="password" capsLockWarning wrongLayoutWarning aria-describedby="pw-strength" />
+<PasswordStrengthMeter id="pw-strength" value={password} />
+```
+
+**When NOT to use:** non-secret single-line text — `<Input>`; multi-line secrets (paste-only API tokens) — `<Textarea>` (not shipped); systems that allow non-Latin passwords — do not set `wrongLayoutWarning`.
+
+- ❌ `revealable={false}` plus a non-password `<Input>` next to it for "Show in plaintext" UX — use `<Input>` directly.
+- ❌ Wrapping it in another `<label>` outside the component — it already renders the input; an outer label nests poorly.
+- ❌ Treating the default `<PasswordStrengthMeter>` scoring as a security control — it is a UX hint; pass `score` from zxcvbn or server-side validation.

package/docs/components/PasswordStrengthMeter.md

@@ -0,0 +1,27 @@
+# `<PasswordStrengthMeter>` — 4-segment strength visualization
+
+```tsx
+<PasswordStrengthMeter value={password} />
+// or, with a real scorer (zxcvbn / server-side):
+<PasswordStrengthMeter score={zxcvbnScore(password)} />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | no | The password to evaluate. Required UNLESS `score` is provided. Evaluated via the default scoring heuristic or a consumer-supplied `scoreFn`. |
+| `score` | `0 \| 1 \| 2 \| 3 \| 4` | no | Pre-computed score (0–4). Wins over `value` + `scoreFn` when both are present. Use this when scoring is done by zxcvbn or server-side. |
+| `scoreFn` | `((value: string) => PasswordStrengthScore)` | no | Custom scoring fn. Receives the password, returns 0–4. Defaults to a length + character-class heuristic — fine for prototypes, NOT a security control. Production should pass a real scorer via `score`. |
+| `showLabel` | `boolean` | no | Render the textual label next to the segments. Defaults to `true`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Two driving modes: `value` (uses default heuristic) or `score` (consumer-provided 0–4). `score` wins when both are set.
+- **Default scoring is a UX hint, NOT a security control.** The heuristic flags long+mixed passwords as "Strong" even if they're in a breach corpus. Production deployments should pass `score` from a real scorer.
+- Polite `aria-live` region announces label changes ("Weak" → "Fair" → "Strong") so screen-reader users hear progress as they type.
+- Use `aria-describedby` on the paired `<PasswordInput>` to associate the meter with the field for AT.

package/docs/components/PersonDisplay.md

@@ -0,0 +1,153 @@
+# `<PersonDisplay>` — Avatar + name (+ optional description lines)
+
+```tsx
+// Canonical: avatar + linked name + email
+<PersonDisplay size="md">
+  <PersonDisplay.Avatar name="Sarah Chen" src="/avatars/sarah.png" />
+  <PersonDisplay.Name href="/contacts/sarah-chen">Sarah Chen</PersonDisplay.Name>
+  <PersonDisplay.Description>sarah@acme.com</PersonDisplay.Description>
+</PersonDisplay>
+
+// Multiple description lines (email + role)
+<PersonDisplay size="md">
+  <PersonDisplay.Avatar name="Marcus Vega" />
+  <PersonDisplay.Name>Marcus Vega</PersonDisplay.Name>
+  <PersonDisplay.Description>marcus@acme.com</PersonDisplay.Description>
+  <PersonDisplay.Description>Account Executive</PersonDisplay.Description>
+</PersonDisplay>
+
+// Tight table cell — sm; name only
+<PersonDisplay size="sm">
+  <PersonDisplay.Avatar name="Avery Liu" />
+  <PersonDisplay.Name>Avery Liu</PersonDisplay.Name>
+</PersonDisplay>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `PersonDisplayProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `size` | `'inline' \| 'sm' \| 'md' \| 'lg'` | no | Visual size of the entire composition. `md` is the default — suits sidebars, members lists, and most card / table contexts. `sm` is the compact density for tight table cells; `lg` is the detail-page hero size. Propagates to the Avatar size and the Name / Description text sizes via context. `inline` fits a person into a text row: the Avatar is one line tall (`1lh`) and the Name inherits the surrounding text's size and weight (and colour, unless it has an `href` — then it's a subtle Link), so a person in a `DefinitionList` value or a table cell is exactly as tall as its plain-text neighbours. Follows the text size; no size decision per call site. Skip Descriptions — a second line defeats it. The root is a `<div>`, so not inside a `<p>`; in a line that also holds something taller than one line it top-aligns rather than sharing the baseline. |
+| `shrink` | `boolean` | no | Force the composition to shrink-wrap to its content (avatar + name) instead of stretching to fill a parent. Default `false`. The root is `inline-flex` and shrink-wraps on its own — but as a child of a *stretching* flex/grid container (a detail/sidebar card column with `align-items: stretch` / `justify-self: stretch`) CSS blockifies it and the parent stretches it to the full column width. The avatar+name then sit in the left portion and the trailing empty space joins the box, so a `Popover.Trigger` / `Tooltip` cloned onto the PersonDisplay anchors to that wide box and centers far to the right of the person. Set `shrink` on such an overlay trigger to keep it content-width (`width: fit-content`) regardless of the parent, so the overlay anchors to the visible avatar+name. |
+| `children` | `ReactNode` | yes | `<PersonDisplay.Avatar>` (or `<PersonDisplay.AgentAvatar>`) + `<PersonDisplay.Name>` (+ optional `<PersonDisplay.OnBehalfOf>` and repeating `<PersonDisplay.Description>`) subcomponents in any order — Root sorts the avatar into its own slot. With an `OnBehalfOf`, Name and OnBehalfOf share one truncating row above the Descriptions. |
+| …native | | | plus native `<div>` attributes |
+
+### `PersonDisplayAgentAvatarProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes | Agent label. Not announced here: the avatar is decorative, and the visible `PersonDisplay.Name` (pass the same label) names the agent. |
+| `mark` | `ReactNode` | no | Agent mark, inherits `currentColor` (a neutral foreground), so pass a glyph drawn with `fill`/`stroke="currentColor"`; marks with hard-coded fills keep their colours (the app's responsibility). Defaults to a lucide `Bot`. |
+| `member` | `AgentAvatarMember \| null` | no | The member the agent acts for. Omit for an agent alone (no badge); `null` or an empty name for an erased member (placeholder badge). |
+| …native | | | plus native HTML attributes |
+
+### `PersonDisplayAvatarProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes | The person's name. Required — used as the `alt`/`aria-label`, as the source of the initials, and as the seed for the deterministic fallback color. The same name always renders the same color. When `tooltip` is true, also used as the tooltip body. |
+| `src` | `string` | no | Image URL. When provided, the `<img>` is rendered with `alt={name}`. Empty/whitespace strings are treated as missing. If the image fails to load (404, network), the component automatically falls back to initials. |
+| `status` | `'online' \| 'busy' \| 'away' \| 'offline'` | no | Presence dot in the bottom-right. - `'online'` — green. - `'busy'` — red. - `'away'` — amber (the categorical amber, dark enough to read at dot size). - `'offline'` — gray. Omit to render no dot at all. Setting `status` changes the accessible name to `"{name}, {status}"` (localized), because colour alone cannot carry the status (WCAG 1.4.1); query with `getByRole('img', { name: 'Alex, online' })`. Each status also renders a distinct shape (filled / half / barred / hollow), so it survives colour-vision deficiency and greyscale; the dot stays `aria-hidden` so nothing is announced twice. |
+| `tooltip` | `boolean` | no | Whether to wrap the avatar in a `<Tooltip>` showing `name`. Defaults to `false` (back-compat — existing renders don't gain a hover affordance). Inside `<AvatarGroup>`, the group's `tooltip` prop becomes the default (which itself defaults to `true` for grouped avatars); explicit per-child still wins. |
+| …native | | | plus native HTML attributes |
+
+### `PersonDisplayDescriptionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | One line of descriptive metadata — email, role, company, etc. Repeat the subcomponent for additional lines; each renders on its own row beneath the name. Accepts arbitrary `ReactNode` children so consumers can inline a `<Badge>` or other small decoration. |
+| …native | | | plus native `<span>` attributes |
+
+### `PersonDisplayNameProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `href` | `string` | no | When set, the name renders as a `<Link>` to this URL. Use for navigable people (contacts, members) where the row links to a detail page. Omit for read-only displays (audit actor, activity timeline) where the name is plain text. |
+| `children` | `ReactNode` | yes | The person's display name — usually a plain string. |
+| …native | | | plus native HTML attributes |
+
+### `PersonDisplayOnBehalfOfProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | no | The member the agent acts for, rendered after a muted "for" prefix. A plain name, or a `<Link>` to the member. Omit (or pass an empty string) when the member was erased: renders "for a former member". Plain-text children (a string, a number, or text-only nodes like `{first} {last}`) give the member box a hover `title` of the full "for {member}" text (the erased copy when erased), which shadows a consumer `title` on OnBehalfOf; a `<Link>` or other element child gets none. The root span is `display: contents` (its prefix and member join the Name's row), so box styles passed via `className`/`style` on it don't paint. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- Compound: `<PersonDisplay>` + `<PersonDisplay.Avatar>` (or `<PersonDisplay.AgentAvatar>`) + `<PersonDisplay.Name>` (+ `<PersonDisplay.OnBehalfOf>`) + repeating `<PersonDisplay.Description>`. Inside the agent row, Name always renders before OnBehalfOf whatever the child order.
+- `<PersonDisplay.Name href="...">` renders the name as a `<Link variant="subtle">` (real `<a>`) — `Link`'s `variant="subtle"` is **not** deprecated, unlike `Text`/`Title`'s `tone="subtle"`; do not "fix" it. Omit `href` for read-only displays (audit actor, activity timeline).
+- **A Description clips itself on the inline axis** (`overflow-x: clip`, `white-space: nowrap`), so a long unbroken value cannot paint outside a narrow container such as a DataTable stacked card. Put **interactive** content in `<PersonDisplay.Name href=…>`, which does not clip (except inside the agent row, where the Name clips on the inline axis like the OnBehalfOf next to it): a control flush with the Description line's left or right edge loses those bands of its focus ring, and that residual is recorded in `tests/focus-ring-geometry.baseline.json` rather than hidden. The block axis is deliberately left `visible`, so a ring is never clipped top or bottom.
+- All Avatar props (`name`, `src`, `status`, `tooltip`) flow through `<PersonDisplay.Avatar>` except `size`.
+- **Use for the standard "person row" — Avatar + name + 0–2 muted lines.** Not for Avatar-only badges (use `<Avatar>`), avatar stacks (use `<AvatarGroup>`), or click-anywhere row interactions (wrap PersonDisplay in your own Link).
+
+```tsx
+// Inline — a DefinitionList value, as tall as the text rows around it
+<PersonDisplay size="inline">
+  <PersonDisplay.Avatar name="Avery Liu" />
+  <PersonDisplay.Name href="/members/avery">Avery Liu</PersonDisplay.Name>
+</PersonDisplay>
+```
+
+`<PersonDisplay.Avatar>` is a thin wrapper around `<Avatar>`; it reads its size from the root and all other Avatar props (`status`, etc.) flow through. `<PersonDisplay.Name>` text size also follows the root `size`.
+
+- This is always a horizontal avatar-left layout; for a "profile hero" with a centered avatar above the name, compose by hand.
+
+**Anti-patterns**
+
+- ❌ Wrapping the whole PersonDisplay in a `<Link>` just to link the person — the Name owns that via `href`. (Wrap it only for click-anywhere row interactions, as above.)
+- ❌ `size="sm"` for a person among text values (a `DefinitionList`, a sentence) — the 24px avatar makes that row taller than its neighbours. Use `size="inline"`.
+- ❌ Descriptions under `size="inline"` — the second line is exactly the extra height `inline` exists to avoid.
+- ❌ Wrapping `<PersonDisplay.Avatar>` in a Fragment or a custom component — the root identifies the Avatar slot by element type, so a wrapped Avatar lands in the text column. Render it as a direct child; use `{shouldShow ? <PersonDisplay.Avatar … /> : null}` for conditional rendering (`null`/`false` are ignored).
+
+## Agent acting for a member
+
+```tsx
+// AI agent acting on behalf of a member
+<PersonDisplay size="md">
+  <PersonDisplay.AgentAvatar name="Scout" member={{ name: 'Sarah Chen', src: '/avatars/sarah.png' }} />
+  <PersonDisplay.Name>Scout</PersonDisplay.Name>
+  <PersonDisplay.OnBehalfOf>Sarah Chen</PersonDisplay.OnBehalfOf>
+  <PersonDisplay.Description>Enrichment agent</PersonDisplay.Description>
+</PersonDisplay>
+
+// Member erased: placeholder badge + "for a former member"
+<PersonDisplay size="md">
+  <PersonDisplay.AgentAvatar name="Scout" member={null} />
+  <PersonDisplay.Name>Scout</PersonDisplay.Name>
+  <PersonDisplay.OnBehalfOf />
+</PersonDisplay>
+
+// Inline: a text row, no member badge; Name + "for Sarah Chen" read as one line
+<PersonDisplay size="inline">
+  <PersonDisplay.AgentAvatar name="Scout" member={{ name: 'Sarah Chen' }} />
+  <PersonDisplay.Name>Scout</PersonDisplay.Name>
+  <PersonDisplay.OnBehalfOf>Sarah Chen</PersonDisplay.OnBehalfOf>
+</PersonDisplay>
+```
+
+- **Three member states** (pass the same state to `AgentAvatar.member` and `OnBehalfOf`): a member (`{ name, src? }` / name child) shows the badge and "for {member}"; `member` omitted = agent alone (no badge, no `OnBehalfOf`); `member={null}` or an empty name = erased, placeholder badge and "for a former member".
+- `PersonDisplay.AgentAvatar` takes the `AgentAvatar` props minus `size` (from the root) and `decorative`. It is **decorative** inside PersonDisplay (`aria-hidden`): the visible Name and `OnBehalfOf` already carry both identities, so nothing is announced twice. The standalone `AgentAvatar` is `role="img"` unless you pass `decorative` (see [AgentAvatar](AgentAvatar.md)).
+- `OnBehalfOf` children: a plain name or a `<Link>` to the member. The "for" prefix is localized.
+- Name and `OnBehalfOf` share one truncating row: the prefix never shrinks, the member ellipsises down to roughly 6ch, then the Name ellipsises. Descriptions sit below.
+- A `<Link>` in `OnBehalfOf` keeps its whole focus ring: the member box pads both inline ends by the ring's extent. Only a member Link that is itself truncated loses its trailing ring band, because the Link runs past the clip edge; its start, top and bottom bands stay.
+- As a flex item (e.g. an activity row `<Cluster wrap={false}>` of IconTile + PersonDisplay + timestamp) the root shrinks (`min-width: 0`) and truncates instead of overflowing. Its siblings shrink too unless you keep them whole: wrap them in `<Constrain flex="none">`.
+- `OnBehalfOf`'s root is `display: contents`, so box styles (background, border, padding) passed via `className` / `style` on it don't paint; style the child you pass. When its children are plain text (a string, a number, or text-only nodes like `{first} {last}`), or the member is erased, the member box gets a hover `title` with the full "for {member}" text (or the erased copy). Over the member box that shadows a consumer `title` passed to `OnBehalfOf`. A `<Link>` or other element child gets no `title`.
+- `inline` hides the member badge and keeps the agent on one text line.
+
+**Agent anti-patterns**
+
+- ❌ Using the agent parts for a human. Agents only; a person is `PersonDisplay.Avatar`.
+- ❌ Passing a multi-colour brand `mark` and expecting it to come out neutral. The tile only sets `color` (a neutral foreground); draw the glyph with `fill`/`stroke="currentColor"`. Hard-coded fills keep their colours, which is the app's responsibility.
+- ❌ Deriving the brand `mark` from a client-chosen name. Pick the mark from a trusted, server-known agent identity, or an agent can impersonate another product.
+- ❌ Adding a "bot" / "AI" kind chip next to the Name. The tile and "for {member}" already signal it.

package/docs/components/PhoneInput.md

@@ -0,0 +1,54 @@
+# `<PhoneInput>`
+
+International phone field: searchable country picker (DS `Select`) + national-number `Input`, controlled on a single `value: string | null` (**E.164**), `onChange(e164 | null)`. `defaultCountry` (ISO alpha-2) seeds the picker when empty; `countries` restricts the list; `size`/`invalid`/`disabled` pass through. Country names are localized via `Intl.DisplayNames`; metadata/validation via `libphonenumber-js`. Validate with the exported `isValidPhone(e164)` and drive `invalid` (or wrap in `<Field error>`). `countryDisplay` sets how the SELECTED country shows in the trigger — `"code"` (default, `+1`), `"iso"` (`US +1`), `"name"` (`United States +1`), or `"flag"` (`🇺🇸 +1`; emoji flags don't render on Windows Chrome/Edge). Dropdown rows always show the full name + code (searchable); opening the picker selects the text for instant type-to-search; the country can't be cleared. The picker's accessible name is composed from the group's (`<Field label="Phone">` → "Phone Country"), so it never collides with a form's own Country field; `countryLabel` overrides it. Store the emitted E.164, not the formatted display.
+
+```tsx
+const [phone, setPhone] = useState<string | null>(null);
+<PhoneInput value={phone} onChange={setPhone} defaultCountry="GB" />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string \| null` | yes | Controlled E.164 value (e.g. `"+442071838750"`); `null` = empty. |
+| `onChange` | `(e164: string \| null) => void` | yes | Fires with canonical E.164 on every edit; `null` when empty. |
+| `defaultCountry` | `string` | no | ISO 3166-1 alpha-2 country used to seed the picker when `value` is empty. Default `"US"`. |
+| `countries` | `string[]` | no | Restrict the picker to this ISO-code subset. Defaults to all libphonenumber-js countries. An empty array is treated as all countries. |
+| `countryDisplay` | `'flag' \| 'iso' \| 'name' \| 'code'` | no | How the SELECTED country renders in the picker trigger. Default `"code"`. - `"code"` — calling code only (`+1`). - `"iso"` — ISO code + code (`US +1`). - `"name"` — full country name + code (`United States +1`). - `"flag"` — emoji flag + code (`🇺🇸 +1`). Note: emoji flags don't render on Windows Chrome/Edge (they show the letters), so prefer `"iso"` there. The dropdown rows always show the full country name + code (plus a flag in `"flag"` mode) so they stay searchable + identifiable regardless of this. |
+| `countryLabel` | `string` | no | Overrides the country picker's full accessible name. By default the picker is named after the group — "<group label> Country" (e.g. "Phone Country") — so it never collides with a form's own Country field; with no group label it is just "Country". Set this when that composed name reads badly. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Control size, forwarded to the Select + Input. Default `"md"`. |
+| `invalid` | `boolean` | no | Error chrome on both controls (host/Field-driven). |
+| `disabled` | `boolean` | no | Disable both controls. |
+| `required` | `boolean` | no | Mark required (forwarded for Field semantics). |
+| `locale` | `string` | no | BCP-47 locale for country-name localization. Defaults to the i18n locale, else `"en"`. |
+| `id` | `string` | no | Stable id; placed on the number field so an external `<label htmlFor>` focuses it. |
+| `aria-label` | `string` | no | Accessible name when used STANDALONE (outside `<Field>`). A standalone PhoneInput MUST be named via `aria-label` or `aria-labelledby`, else the country/number group is unnamed. Inside `<Field>` the label is wired automatically via `aria-labelledby`. |
+| `aria-labelledby` | `string` | no | Ids of elements labelling the group (injected by `<Field>`; takes precedence over `aria-label`). |
+| `aria-describedby` | `string` | no | Ids of description/error elements; forwarded to the number field so it is announced on focus (injected by `<Field>`). |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+Inside a `<Field>` the label and error wiring are injected:
+
+```tsx
+<Field label="Mobile" error={isValidPhone(phone) ? undefined : 'Invalid number'}>
+  <PhoneInput value={phone} onChange={setPhone} />
+</Field>
+```
+
+**When NOT to use:** a non-phone numeric field — `<Input type="tel">` or `<Input inputMode="numeric">`.
+
+**Anti-patterns**
+
+- ❌ Treating it as uncontrolled — feed `onChange`'s E.164 back into `value`.
+- ❌ Storing the formatted national string — persist the emitted E.164; the display is reconstructed from it.
+- ❌ Validating by hand — call `isValidPhone(e164)` and pass `invalid` (or wire it through `<Field error>`).
+
+**Known limitations**
+
+- Format-as-you-type moves the caret to the end of the number field after each reformat; editing in the middle of the number bounces the caret to the end.

package/docs/components/PillMenu.md

@@ -0,0 +1,91 @@
+# `<PillMenu>` — coloured value menu (status, type, priority…)
+
+Renamed from `StatusMenu` — `StatusMenu` / `StatusMenuProps` / `StatusMenuStatus` / `StatusMenuCategory` no longer exist; use `PillMenu` / `PillMenuProps` / `PillMenuOption` / `PillMenuCategory`. Component tokens are `--pill-menu-*`, the i18n namespace is `pillMenu`.
+
+```tsx
+<PillMenu
+  current={{ id: 'todo', name: 'To do', category: 'to_do' }}
+  options={[
+    { id: 'in_progress', name: 'In progress', category: 'in_progress' },
+    { id: 'done', name: 'Done', category: 'done' },
+  ]}
+  onSelect={(id) => updateStatus(task.id, id)}
+/>
+
+// Read-only chip — omit `options` for a static colored chip, no menu:
+<PillMenu current={{ id: 'won', name: 'Won', category: 'won' }} />
+
+// Not a status: label the trigger and add per-value icons:
+<PillMenu
+  label="type"
+  current={{ id: 'bug', name: 'Bug', color: 'red', icon: <Bug size={14} /> }}
+  options={[{ id: 'story', name: 'Story', color: 'green', icon: <BookOpen size={14} /> }]}
+  onSelect={setType}
+/>
+// → trigger announced "Change type: Bug"
+
+// Say what it picks AND the value — visible caption, muted, before a middle dot:
+<PillMenu caption="Pipeline" current={pipeline} options={pipelines} onSelect={setPipeline} />
+// → shows "Pipeline · Faeton", announced "Change Pipeline: Faeton" (a string caption names the trigger when `label` is absent)
+
+// Pass `label` too when the name needs another form (e.g. ru accusative) — keep the caption's words in it:
+<PillMenu label="воронку" caption="Воронка" current={pipeline} options={pipelines} onSelect={setPipeline} />
+// → announced "Изменить воронку: Faeton"
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `current` | `PillMenuOption` | yes | The value currently shown on the trigger (or the read-only chip). |
+| `label` | `string` | no | What the value IS, for the trigger's accessible name: `label="type"` → "Change type: Bug". Default: a string `caption` ("Change Pipeline: …"), else the localized "status" ("Change status: …"). Pass it as it reads right after "Change" / "Изменить", lower-case, in the UI's language — it is data, not a translatable string. In ru that is the accusative: `label="категорию"`, not "категория". Inside a `<Field>`, pass the field's label here (`label="priority"` under "Priority"): the trigger keeps its own name, so the visible field label reaches AT only through this (WCAG 2.5.3). A dev warning fires if it's missing there. |
+| `caption` | `ReactNode` | no | Visible caption rendered inside the pill before the value, separated by a middle dot: `caption="Pipeline"` → "Pipeline · Faeton". For a trigger that must say both what it picks and the current value. Names the trigger only as a fallback: `label` wins ("Change pipeline: Faeton"); with no `label`, a non-blank string caption is used ("Change Pipeline: Faeton") so the visible words stay in the accessible name (WCAG 2.5.3 label-in-name). A non-string caption never names it — pass `label` then, containing the caption's words. In the read-only chip (no accessible name override) the caption text is read along with the value; the dot is `aria-hidden` in both. Muted by weight (regular vs the value's medium), not colour: the palette fills leave no contrast headroom for a dimmer foreground. Omitted or blank → no caption, no dot. |
+| `options` | `PillMenuOption[]` | no | Transition targets, offered in the dropdown. Omitted or empty renders read-only mode: a static colored chip with no button, no menu, no aria-haspopup. |
+| `onSelect` | `((id: string \| number) => void)` | no | Fired with the chosen option's `id` when a transition target is picked. |
+| `disabled` | `boolean` | no | Disables the trigger. Stays colored, dims via opacity. |
+| `busy` | `boolean` | no | Transition in flight: the trigger is non-interactive and keeps its color. Announced from a polite live region the component owns — `aria-busy` is also set but reaches no screen reader on its own. The trigger's accessible name does not change (contrast `EntityChip`): you activated this control, so the change is announced rather than folded into the name. No effect in read-only mode (no `options`), which renders no trigger and so has nothing to mark busy. |
+| `fullWidth` | `boolean` | no | Stretch the trigger (or read-only chip) to its container's width, for a form column of full-width controls (`Input`, `Select`, `DatePicker` in vertical `Field`s). Icon + name stay at the start, the chevron moves to the end edge like a `Select` trigger, and the menu is at least as wide as the trigger. Keeps the full-colour fill. Defaults to `false` (content-width pill). |
+| `invalid` | `boolean` | no | Error state — sets `aria-invalid` on the trigger. `<Field error>` injects it for you. No visual change: the fill IS the value's colour, and the Field's error text carries the error. The read-only chip ignores it (a non-focusable chip isn't a control AT can report invalid). |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- A coloured pill trigger that opens a menu of values, each row coloured to its own value — a workflow status, a task type, a priority. Composes `<DropdownMenu>` internally.
+- `icon?: ReactNode` on `current` and on each option renders before the name in the pill and in its row, `aria-hidden` (decorative — the name is announced). Size it to the text (~14px, at most 16px — menu rows use a fixed 16px slot).
+- `current` / each option: `{ id, name, category?, color? }`. `category` (`to_do` / `in_progress` / `open` / `done` / `won` / `lost`) maps to a default palette color (slate / blue / violet / green / green / red); `color` (a `PaletteColor`) overrides it per-status.
+- `attrs` (``Record<`data-${string}`, string>``) on `current` is spread onto the trigger button (or the read-only chip); on an option, onto its menu row. It goes before the component's own attributes, so a key can't override the `id`/`role`/`aria-*`/handlers the component owns (on a menu row, also the row's `data-tone`). A `data-*` passed on `<PillMenu>` itself beats `current.attrs`. **Anti-pattern:** when `current` is the same object as an entry in `options` (`current={options.find(...)}`), its attrs land on both the pill and that menu row, so two elements carry the same `data-tour` while the menu is open. Give `current` its own attrs: `current={{ ...opt, attrs: { 'data-tour': 'stage-pill' } }}`. Use it to target a pill from a `Tour` or to add a test/analytics id: `current={{ id: 1, name: 'Open', attrs: { 'data-tour': 'status-pill' } }}`, then `<Tour steps={[{ target: 'status-pill', title: '...' }]} />`.
+- Not for a plain action menu (use `<DropdownMenu>`), a non-interactive status with no transition (use `<Badge>`), or picking from a long searchable list (use `<Select>`).
+
+Per-state colour override (`color` wins over `category`):
+
+```tsx
+<PillMenu
+  current={{ id: 'triage', name: 'Triage', color: 'amber' }}
+  options={[{ id: 'won', name: 'Won', category: 'won', color: 'emerald' }]}
+  onSelect={(id) => setStage(id)}
+/>
+```
+
+In a form column beside full-width Selects/Inputs, pass `fullWidth` and `label` (the trigger keeps its own name, "Change priority: High"):
+
+```tsx
+<Field label="Priority" error={errors.priority}>
+  <PillMenu
+    fullWidth
+    label="priority"
+    current={priority}
+    options={priorities}
+    onSelect={setPriority}
+  />
+</Field>
+```
+
+**Anti-patterns**
+
+- ❌ A small `<Badge>` wrapped inside a neutral `<Button>` to fake a coloured status trigger — that is what `PillMenu` replaces.
+- ❌ Raw hex strings in `color` — it is a `PaletteColor` name (`'amber'`, `'violet'`, …), not a CSS colour value.
+- ❌ A non-string (or blank) `caption` without `label` — only a non-blank string caption falls back as the name; a node leaves "Change status: …", which fails WCAG 2.5.3 label-in-name. Pass `label` containing the caption's words.
+- ❌ Omitting `options` to "disable" the menu — that is read-only mode (no interactivity at all). For a transition that is temporarily blocked, keep `options` and pass `disabled`.

package/docs/components/Popover.md

@@ -0,0 +1,127 @@
+# `<Popover>` — non-modal floating panel for interactive content
+
+```tsx
+<Popover>
+  <Popover.Trigger>
+    <Button variant="secondary">Filters</Button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <Stack gap="sm">
+      <Popover.Heading>Filter results</Popover.Heading>
+      {/* …form controls… */}
+      <Cluster justify="end" gap="sm">
+        <Popover.Close>
+          <Button variant="secondary" size="sm">
+            Cancel
+          </Button>
+        </Popover.Close>
+        <Popover.Close>
+          <Button size="sm" onClick={apply}>
+            Apply
+          </Button>
+        </Popover.Close>
+      </Cluster>
+    </Stack>
+  </Popover.Content>
+</Popover>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `PopoverProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Must contain exactly one `<Popover.Trigger>` (or `<Popover.Anchor>` for a controlled popover whose anchor owns its own toggle + ARIA) and one `<Popover.Content>`. `<Popover.Heading>` and `<Popover.Close>` are optional and may appear anywhere inside `<Popover.Content>`. |
+| `open` | `boolean` | no | Controlled open state. Provide alongside `onOpenChange` to drive open externally. Omit both to let Popover own its state (the common case). |
+| `onOpenChange` | `((open: boolean) => void)` | no | Fired whenever Popover wants to change open state. Required when `open` is provided. |
+| `defaultOpen` | `boolean` | no | Default open state for uncontrolled usage. Defaults to `false`. |
+| `modal` | `boolean` | no | Reserved future hint. v1 ignores the value and always renders non-modal. Will gate focus-trap + inert-background once `<Modal>` lands. |
+
+### `PopoverAnchorProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element that accepts a ref. Unlike `Popover.Trigger`, Anchor injects ONLY the floating-positioning ref — no `onClick`, no keyboard handler, and no `aria-haspopup` / `aria-expanded` / `aria-controls`. Use it when the anchor element already owns its open-toggle and ARIA (e.g. an interactive `FilterChip` whose body `<button>` self-manages `aria-haspopup`/`aria-expanded`), and you drive the popover's open state yourself (controlled `open` + `onOpenChange`). The child must accept a ref (`forwardRef`); raw DOM elements and this library's components qualify, and it should be focusable (a `<button>` or `tabIndex` host) so Escape can return focus to it on close. Wrapping such a chip in `Popover.Trigger` instead would stamp that ARIA onto its `role="group"` root, not the body button. |
+
+### `PopoverCloseProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element. The Close clones this element to inject an `onClick` that closes the popover, chained with the child's existing `onClick` (consumer runs first). |
+
+### `PopoverContentProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | no | Preferred side. Default `'bottom'`. Auto-flips on collision via Floating UI. |
+| `align` | `'start' \| 'center' \| 'end'` | no | Edge alignment. Default `'center'`. |
+| `sideOffset` | `number` | no | Gap in px between trigger and panel. Default `10` (room for the arrow). |
+| `minWidth` | `string \| number` | no | Minimum width in px or any CSS length. Defaults to the token `--size-popover-min-width` (220px) applied via SCSS. |
+| `maxWidth` | `string \| number` | no | Maximum width in px or any CSS length, overriding the default cap (`--popover-max-width`, 360px). Use for wide content — calendars, tables — that would otherwise overflow the panel. Accepts a number (px), `'fit-content'`, `'none'` to remove the cap, or any CSS length. |
+| …native | | | plus native `<div>` attributes |
+
+### `PopoverHeadingProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `as` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | no | Heading level. Defaults to `'h3'`. Pick the level that fits the surrounding document outline (Popover content is usually a level 3 inside a level 2 section). |
+| …native | | | plus native `<h1–h6>` attributes |
+
+### `PopoverTriggerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element that accepts a ref. The Trigger clones this element to inject `aria-haspopup`, `aria-expanded`, `aria-controls`, a click handler that toggles the popover, and a keydown handler that opens on Enter/Space. `<Button>` and raw `<button>` both qualify; a custom component without `forwardRef` does not. |
+| `aria-haspopup` | `'true' \| 'false' \| 'dialog' \| 'grid' \| 'listbox' \| 'menu' \| 'tree'` | no | Override the `aria-haspopup` value injected onto the trigger child. Defaults to `'dialog'` (matching the role of `Popover.Content`). Pass `'listbox'` for picker-style compound usages where the popover surfaces a listbox rather than a generic dialog. |
+
+<!-- props:end -->
+
+- Compound API: `<Popover>` is the provider; `<Popover.Trigger>` clones its single child to inject ARIA + click; `<Popover.Content>` portals to `document.body` and positions via Floating UI; `<Popover.Heading>` (optional) wires `aria-labelledby`; `<Popover.Close>` clones its child to inject a close-onClick.
+- Trigger child must accept a ref (`forwardRef`). `<Button>` does.
+- **Non-modal**: focus moves to the panel on open; Tab traverses INTO content, then OUT to the page behind. Click-outside or Escape dismisses. Page is NOT inert.
+- Opens with a short scale-fade from the trigger side (140ms). Closes instantly. Respects `prefers-reduced-motion: reduce`.
+- **From a DropdownMenu item.** Wrap a `<DropdownMenu.Item closeOnSelect={false}>` as the `<Popover.Trigger>` child — the Item itself becomes the trigger, so the full highlighted row opens the popover. `closeOnSelect={false}` keeps the menu open while the popover is shown.
+- Z-layer `--z-popover: 1050` — above dropdown, below modal/toast/tooltip.
+- **Overlay host for nested floating surfaces.** A `Popover.Content` (and a `DropdownMenu` content panel) acts as an overlay host: any floating surface (`DropdownMenu` / `Popover` / `ConfirmationPopover` / `Select` / `DatePicker` / `DateRangePicker` / `TimeField` / the `Rail.Group` flyout) whose trigger sits inside it auto-elevates to `--z-overlay-floating` (1190), so a kebab menu, nested popover, or confirm dialog opened from within a Popover panel stacks ABOVE the panel instead of rendering behind it. No prop needed — it keys off the existing `[data-popover-content]` / `[data-dropdown-menu-content]` markers, plus `[data-in-overlay]` itself (elevation is transitive: a surface nested inside an elevated surface elevates too). The Popover also won't dismiss itself when you interact with such a nested surface (its content portals to `document.body`, so a click inside it would otherwise read as "outside") — so a kebab menu item or its confirm dialog stays usable without collapsing the host.
+- **Escape is innermost-first across nested surfaces.** When one floating surface is open inside another — a `Select` listbox inside a `Popover`, a `ConfirmationPopover` opened from a `DropdownMenu` item, etc. — the first `Escape` closes only the **innermost** surface; the outer one (and any host `Modal`/`Drawer`) survives that press. Each press peels exactly one layer. Surfaces coordinate via the shared overlay registry (`isTopFloating`) — the most-recently-opened is innermost — so no per-pair wiring is needed.
+- **Tall content:** a Popover is capped at the viewport only when it holds a `<ScrollArea>`. Wrap the long part (a feed, a list) in `<ScrollArea maxHeight="md">`; the header above it stays put. Without one, a tall popover runs off-screen. Recipe (notification centre): `Popover.Content minWidth={380}` → `Stack` → header `Cluster` (`Popover.Heading` + "Mark all as read" Button) + `ScrollArea maxHeight="md" aria-label="Notifications"`.
+- For passive hover/focus hints → `<Tooltip>`. For lists of actions → `<DropdownMenu>`. For focus-locked dialogs → `<Modal>`.
+
+- `<Popover.Content>` is `role="dialog"` with `aria-modal="false"` and `tabIndex={-1}` so it can take focus on open, and renders an `aria-hidden` arrow that tracks the trigger.
+- `<Popover.Close>` wraps exactly one React element child (it throws otherwise); the child's own `onClick` chains and runs first. `<Popover.Heading>` unsubscribes its `aria-labelledby` registration on unmount.
+- **`<ScrollArea>` placement:** keep it a direct child of `<Popover.Content>`, or inside one wrapper element that is a direct child. That wrapper must lay its children out as a column — a `<Stack>`, or a plain element (div/form/Card). A row wrapper such as `<Cluster>` is not supported (the popover caps but the feed overflows it); deeper nesting leaves the popover uncapped. The popover then caps itself at the viewport and only the ScrollArea shrinks.
+- Controlled use is rare — usually let Popover manage state: `<Popover open={open} onOpenChange={setOpen}>…</Popover>`.
+- When you need a focus-locked confirmation, prefer `<Modal>`.
+
+`Popover.Anchor` with a controlled popover on an interactive `FilterChip`:
+
+```tsx
+const [open, setOpen] = useState(false);
+<Popover open={open} onOpenChange={setOpen}>
+  <Popover.Anchor>
+    <FilterChip onActivate={() => setOpen((o) => !o)} expanded={open} onDismiss={remove}>
+      <FilterChip.Label>Range</FilterChip.Label>
+      <FilterChip.Value>Jun 1 – Jul 31</FilterChip.Value>
+    </FilterChip>
+  </Popover.Anchor>
+  <Popover.Content maxWidth={520}>
+    <RangePicker />
+  </Popover.Content>
+</Popover>;
+```
+
+**Anti-patterns**
+
+- ❌ `<Popover.Trigger><Button disabled>…</Button></Popover.Trigger>` — disabled buttons do not fire click. Use `aria-disabled="true"` and intercept the click, or wrap in `<span>`.
+- ❌ `<Popover.Content>` with no `<Popover.Close>` and content that is not obviously dismissable by clicking outside — keyboard / screen-reader users get no clear close affordance. Rely on outside-click only when the popover is small and obvious.
+- ❌ Multiple `<Popover.Heading>` in one `<Popover.Content>` — the second mount overwrites `aria-labelledby`. One Heading per Popover.
+- ❌ A tall panel with no `<ScrollArea>` — it is not capped at the viewport and runs off-screen.

package/docs/components/Progress.md

@@ -0,0 +1,56 @@
+# `<Progress>` — linear progress bar
+
+```tsx
+<Progress value={45} />                            // 45% determinate
+<Progress value={67} label />                      // shows "67%" on the right
+<Progress value={85} tone="warning" label />       // dark-amber fill (state coding)
+<Progress />                                       // value omitted = indeterminate slide
+<Progress value={3} max={10} label={`3 of 10`} />  // custom label slot
+```
+
+The track is `--color-border` (as are `CircularProgress` and `Slider` tracks), so it stays visible on white, muted (`bg-muted`) and card surfaces alike — no per-surface `--progress-track-bg` override needed. For a quota meter in a KPI tile use `StatTile`'s `progress` prop.
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `number` | no | Current progress value. Omit (or pass `undefined`) to render the indeterminate animation. Two-channel behavior for out-of-range and degenerate values: - **Visual fill** is clamped to [0%, 100%]. Values outside [0, max] render at the nearest valid bound. - **ARIA `aria-valuenow`** reports the raw number — this is the right screen-reader behavior so consumer bugs (a value drifting past max) surface in audits and SR announcements. Degenerate inputs fall back to the indeterminate animation: `NaN`, `Infinity`, `-Infinity`, and the case where `max <= 0`. This is the common file-upload race condition (`bytes_uploaded / total_bytes` before `total_bytes` is known produces NaN). |
+| `max` | `number` | no | Upper bound. Defaults to `100`. Consumers using fraction values (0.0–1.0) pass `max={1}`. Consumers tracking a count ("3 of 10") pass `max={10}`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Track height. - `sm` — 4px (compact / inside form rows) - `md` — 8px (default) - `lg` — 12px (page-level emphasis) |
+| `tone` | `'default' \| 'success' \| 'warning' \| 'danger'` | no | Fill color tone. Defaults to `'default'` (accent blue). Tone applies ONLY to determinate mode; indeterminate always uses the accent tone because state-color semantics don't apply to an unknown total. - `default` — `--color-accent` - `success` — `--color-success` - `warning` — `--color-warning-strong` - `danger` — `--color-danger` |
+| `label` | `ProgressLabel` | no | Optional label rendered to the RIGHT of the bar. - `false` (default) — no label - `true` — render `{Math.round((value / max) * 100)}%` when determinate. Auto-suppressed when indeterminate (there's no percentage to show). - `ReactNode` — render the node as-is, in BOTH determinate and indeterminate modes. Consumers wanting "Loading…" text next to an indeterminate bar pass `label="Loading…"`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- `role="progressbar"` is locked — `Omit<HTMLAttributes, 'role'>` prevents the consumer from overriding it.
+- Indeterminate `aria-valuetext` falls back to consumer-passed `aria-label`, then to the translated `progress.indeterminate` — not a hardcoded English string.
+
+Use for per-file upload bars, wizard step indicators, form-completion meters and disk-usage gauges — anything with a known total. Storage-usage panel:
+
+```tsx
+<Stack gap="xs">
+  <Title order={3} size="md">
+    Storage
+  </Title>
+  <Progress value={85} max={100} tone="warning" label />
+  <Text size="sm" tone="muted">
+    85 GB of 100 GB used
+  </Text>
+</Stack>
+```
+
+**When NOT to use**
+
+- An inline loading affordance next to a button — use indeterminate `<CircularProgress>`.
+- Celebrating completion — a done bar is a done bar; leave the default tone. `tone` communicates state during progress (warning near a threshold, danger when over), not success-on-finish (so no `tone="success"` at `value={100}`).
+- Arbitrary horizontal lines — use `<Divider>`.
+
+**Anti-patterns**
+
+- ❌ A hand-rolled `<div style={{ width: `${n}%`, … }}>` bar — use the primitive.
+- ❌ `<Progress role="…">` — `role` is locked to `progressbar`; TypeScript rejects the override.
+- ❌ A separate consumer-rendered label element — the `label` slot already handles spacing, font size and tabular-nums for stable digit widths.

package/docs/components/QrCode.md

@@ -0,0 +1,34 @@
+# `<QrCode>` — scannable QR code
+
+```tsx
+<QrCode value="https://example.com/i/42" aria-label="QR code for invoice 42" />;
+<QrCode value={inviteUrl} logo={brandMark} aria-label="Invite link" />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | The string to encode — a URL, an ID, a vCard. Encoded as UTF-8, so any script works. An empty string, or one past the largest symbol's capacity at the chosen `level` (~1273 bytes at `'H'`, ~2953 at `'L'`), renders a **disabled** button carrying a localized "unavailable" message instead of a code. It never throws — a long CRM field cannot white-screen a page. |
+| `logo` | `string` | no | URL of a **single-colour** SVG to place in the centre. It is used as a CSS alpha mask and filled with the code's current ink, so it recolours itself in both themes and in the inverted state — the file's own colours are discarded. Full-colour artwork and photographs are not supported. Setting this also raises the default `level` to `'H'`, because the punch-out destroys modules outright. |
+| `level` | `'L' \| 'M' \| 'Q' \| 'H'` | no | Error-correction level — how much damage the symbol survives. `'L'` ~7%, `'M'` ~15%, `'Q'` ~25%, `'H'` ~30%. Higher levels need a larger symbol for the same data. Defaults to `'H'` when `logo` is set, `'M'` otherwise. |
+| …native | | | plus native `<button>` attributes |
+
+<!-- props:end -->
+
+- Encodes `value` as UTF-8, so Cyrillic and every other script work.
+- **Follows the theme** — dark modules on light paper in light mode, inverted in dark. Clicking the code swaps ink and paper back, for a scanner that refuses an inverted symbol. That click is the component's only interaction.
+- The whole code is a `<button>` with `aria-pressed`. **Never nest it inside another clickable element** — invalid HTML, and it swallows the outer click.
+- **No `size` prop** — it fills its container's width; the parent owns the box. Wrap in `<Constrain>` or a sized element, and keep it above ~100px or a dense symbol stops resolving.
+- The symbol **snaps down to a whole number of device pixels per module and centres itself**, so the painted code can sit up to one module short of the container — measuring the button gives you the box, not the code. Size the container to a whole multiple of the module count and the shortfall disappears. Where snapping would give up more than an eighth of the width, it renders fluid and antialiased instead: a bigger blurry code scans, a smaller pixel-exact one does not. The ~100px floor applies to the painted symbol, not to the box.
+- There is no `label` prop — pass the native `aria-label`. It defaults to a bare localized "QR code", which tells a screen-reader user nothing about what the code points at.
+- An empty `value`, or one over capacity for the level (~1273 bytes at `'H'`), renders a **disabled** button on a muted filled plate — no border — carrying a localized "unavailable" message instead of throwing. A long CRM field cannot white-screen a page. Your `aria-label` is prefixed to that message as visible text, so the name reads "Invoice 42 — QR code unavailable" and a browse-mode user can tell which code failed.
+- Clicking inverts; `title` carries a localized hint describing that, exposed as the accessible description. Pass your own `title` to override it.
+- Always render the underlying URL as selectable text too. The code is unusable to a screen-reader user, and to anyone reading on the device that shows it.
+- Treat the value as public. Anyone who can see the screen can scan it.
+
+- `logo` raises `level` to `'H'`, which packs more modules into the same box — each comes out smaller, so size the container up when you use it.
+- Pair the code with a visible caption (e.g. `<Text size="sm" tone="muted">Scan at the door</Text>` in a `<Stack align="center">`) for sighted users.