@skra/ui 0.2.0 → 0.3.0

package/consumer-guide/README.md

@@ -1,84 +1,84 @@
-# Consuming Skra — Agent Guide (Core)
-
-> **DRAFT (2026-06-25).** All 7 sections drafted. Snippets are grounded in source (verified
-> against `libs/ui/*`) + the `apps/dogfood` friction journal (`F-n`) + the Iron Boundaries.
-> Still draft: not yet referenced from a real consumer repo, not lint-gated against ADR drift,
-> and cross-engine/Safari caveats inherit Skra's own open item O-9.
-
-This guide is for an **agent working inside a repository that consumes Skra** (imports
-`@skra/*`), not for authoring Skra itself. It is written to be **copied into / referenced
-from a consumer repo**.
-
----
-
-## How to use this guide (read this first — it is the point)
-
-This file is **tiered on purpose** (same model as `FORGE_ADR_SUMMARY.md`). To keep token
-cost low:
-
-1. **Always load this core** (it is small) — the Iron Rules + the Section Router below.
-2. Then load **at most the ONE section** that matches your current task (the Router maps
-   task → file). Do **not** read every section "to be safe" — that defeats the design.
-3. Open the full Skra ADR / spec only when a section explicitly points you there.
-
----
-
-## Iron Rules of Consumption (the 6 a consumer breaks on day one)
-
-Violating these is a review blocker in a consumer repo just as inside Skra.
-
-1. **Import only from public `@skra/ui/*` entry points** — never a deep relative `libs/...`
-   path. Skra ships as one package, `@skra/ui`, with a secondary entry point per component
-   (e.g. `@skra/ui/button`, `@skra/ui/typography`, `@skra/ui/select`); the primary
-   `@skra/ui` exports nothing. (Full entry-point list → `setup-and-gotchas.md`.)
-2. **You own the value.** Skra form atoms do **not** implement `ControlValueAccessor` /
-   `FormValueControl` (ADR 037). Native-host atoms take `[formField]`/`[formControl]`/
-   `[(ngModel)]`; value-owned overlays need an explicit `[value]`/`(valueChange)` bridge.
-   (How → `forms-and-binding.md`.)
-3. **Accessible name has exactly ONE path** (ADR 033). No Skra atom exposes an `ariaLabel`
-   input; never put `aria-label` next to visible text on the same host. (Paths →
-   `accessible-names.md`.)
-4. **Inside `<skra-field>`, do not pass `id` / `for` / `aria-describedby` by hand** — the
-   DI context wires label↔control↔hint↔error automatically (ADR 013).
-5. **Under Signal Forms, native constraint attributes go in the schema, not the template.**
-   `name` on grouped radios and `maxlength` / `min` / `pattern` on a `[formField]` host raise
-   `NG8022` — Signal Forms owns them (F-1/F-2). (Details → `forms-and-binding.md`.)
-6. **Never theme with inline styles.** No `[style.--skra-*]` bindings or `style="…"` (breaks
-   CSP, ADR 021). Override tokens via a CSS class / `data-skra-*` scope; components are
-   `margin: 0` (ADR 022) — spacing comes from layout atoms, never a margin on the component.
-
----
-
-## Section Router — load the ONE that matches your task
-
-| Section                     | File                           | Load when                                                                                                   | Status   |
-| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------- |
-| **Setup & gotchas**         | `setup-and-gotchas.md`         | First integration; import fails; which `@skra/*` package exports what; boolean-attribute & theming pitfalls | ✅ draft |
-| **Forms & value binding**   | `forms-and-binding.md`         | Wiring an input / select / checkbox / rating to Signal Forms, Reactive Forms, or `ngModel`                  | ✅ draft |
-| **Accessible names**        | `accessible-names.md`          | Naming buttons, icon-only controls, overlays; using `skra-sr-only`                                         | ✅ draft |
-| **Theming & encapsulation** | `theming-and-encapsulation.md` | Skins, dark mode, density; mounting under Shadow DOM / a microfrontend / an iframe                          | ✅ draft |
-| **Overlays**                | `overlays.md`                  | Dialog / tooltip / popover / menu / select in the top layer; shadow & iframe limits                         | ✅ draft |
-| **Layout**                  | `layout.md`                    | Spacing & composition with Stack / Box / Grid; the gap scale                                                | ✅ draft |
-| **Wrapping Skra**          | `wrapping-patterns.md`         | Building your own higher-level components over Skra atoms (simplified API)                                 | ✅ draft |
-
----
-
-## Quick reference — task → section
-
-| I want to…                                                                 | Go to                                     |
-| -------------------------------------------------------------------------- | ----------------------------------------- |
-| Add `@skra/ui/*` to a project and import an atom                           | `setup-and-gotchas.md`                    |
-| Bind a text input / textarea to a form                                     | `forms-and-binding.md`                    |
-| Bind a `skra-select` / `skra-datepicker` / `skra-star-rating` to a form | `forms-and-binding.md` (the value bridge) |
-| Name an icon-only button                                                   | `accessible-names.md`                     |
-| Switch skin / dark mode at runtime                                         | `theming-and-encapsulation.md`            |
-| Mount Skra inside a Web Component / microfrontend                         | `theming-and-encapsulation.md`            |
-| Open a dialog or tooltip                                                   | `overlays.md`                             |
-| Space components apart                                                     | `layout.md`                               |
-| Wrap a Skra atom in a project-specific component                          | `wrapping-patterns.md`                    |
-
----
-
-_Source of truth for the rules: Skra `FORGE_ADR_SUMMARY.md` + `adr/decisions/`. Real
-consumption evidence: `apps/dogfood/FRICTION_JOURNAL.md`. This guide restates the consumer
-slice of those — on divergence, the ADRs win._
+# Consuming Skra — Agent Guide (Core)
+
+> **DRAFT (2026-06-25).** All 7 sections drafted. Snippets are grounded in source (verified
+> against `libs/ui/*`) + the `apps/dogfood` friction journal (`F-n`) + the Iron Boundaries.
+> Still draft: not yet referenced from a real consumer repo, not lint-gated against ADR drift,
+> and cross-engine/Safari caveats inherit Skra's own open item O-9.
+
+This guide is for an **agent working inside a repository that consumes Skra** (imports
+`@skra/*`), not for authoring Skra itself. It is written to be **copied into / referenced
+from a consumer repo**.
+
+---
+
+## How to use this guide (read this first — it is the point)
+
+This file is **tiered on purpose** (same model as `FORGE_ADR_SUMMARY.md`). To keep token
+cost low:
+
+1. **Always load this core** (it is small) — the Iron Rules + the Section Router below.
+2. Then load **at most the ONE section** that matches your current task (the Router maps
+   task → file). Do **not** read every section "to be safe" — that defeats the design.
+3. Open the full Skra ADR / spec only when a section explicitly points you there.
+
+---
+
+## Iron Rules of Consumption (the 6 a consumer breaks on day one)
+
+Violating these is a review blocker in a consumer repo just as inside Skra.
+
+1. **Import only from public `@skra/ui/*` entry points** — never a deep relative `libs/...`
+   path. Skra ships as one package, `@skra/ui`, with a secondary entry point per component
+   (e.g. `@skra/ui/button`, `@skra/ui/typography`, `@skra/ui/select`); the primary
+   `@skra/ui` exports nothing. (Full entry-point list → `setup-and-gotchas.md`.)
+2. **You own the value.** Skra form atoms do **not** implement `ControlValueAccessor` /
+   `FormValueControl` (ADR 037). Native-host atoms take `[formField]`/`[formControl]`/
+   `[(ngModel)]`; value-owned overlays need an explicit `[value]`/`(valueChange)` bridge.
+   (How → `forms-and-binding.md`.)
+3. **Accessible name has exactly ONE path** (ADR 033). No Skra atom exposes an `ariaLabel`
+   input; never put `aria-label` next to visible text on the same host. (Paths →
+   `accessible-names.md`.)
+4. **Inside `<skra-field>`, do not pass `id` / `for` / `aria-describedby` by hand** — the
+   DI context wires label↔control↔hint↔error automatically (ADR 013).
+5. **Under Signal Forms, native constraint attributes go in the schema, not the template.**
+   `name` on grouped radios and `maxlength` / `min` / `pattern` on a `[formField]` host raise
+   `NG8022` — Signal Forms owns them (F-1/F-2). (Details → `forms-and-binding.md`.)
+6. **Never theme with inline styles.** No `[style.--skra-*]` bindings or `style="…"` (breaks
+   CSP, ADR 021). Override tokens via a CSS class / `data-skra-*` scope; components are
+   `margin: 0` (ADR 022) — spacing comes from layout atoms, never a margin on the component.
+
+---
+
+## Section Router — load the ONE that matches your task
+
+| Section                     | File                           | Load when                                                                                                   | Status   |
+| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------- |
+| **Setup & gotchas**         | `setup-and-gotchas.md`         | First integration; import fails; which `@skra/*` package exports what; boolean-attribute & theming pitfalls | ✅ draft |
+| **Forms & value binding**   | `forms-and-binding.md`         | Wiring an input / select / checkbox / rating to Signal Forms, Reactive Forms, or `ngModel`                  | ✅ draft |
+| **Accessible names**        | `accessible-names.md`          | Naming buttons, icon-only controls, overlays; using `skra-sr-only`                                         | ✅ draft |
+| **Theming & encapsulation** | `theming-and-encapsulation.md` | Skins, dark mode, density; mounting under Shadow DOM / a microfrontend / an iframe                          | ✅ draft |
+| **Overlays**                | `overlays.md`                  | Dialog / tooltip / popover / menu / select in the top layer; shadow & iframe limits                         | ✅ draft |
+| **Layout**                  | `layout.md`                    | Spacing & composition with Stack / Box / Grid; the gap scale                                                | ✅ draft |
+| **Wrapping Skra**          | `wrapping-patterns.md`         | Building your own higher-level components over Skra atoms (simplified API)                                 | ✅ draft |
+
+---
+
+## Quick reference — task → section
+
+| I want to…                                                                 | Go to                                     |
+| -------------------------------------------------------------------------- | ----------------------------------------- |
+| Add `@skra/ui/*` to a project and import an atom                           | `setup-and-gotchas.md`                    |
+| Bind a text input / textarea to a form                                     | `forms-and-binding.md`                    |
+| Bind a `skra-select` / `skra-datepicker` / `skra-star-rating` to a form | `forms-and-binding.md` (the value bridge) |
+| Name an icon-only button                                                   | `accessible-names.md`                     |
+| Switch skin / dark mode at runtime                                         | `theming-and-encapsulation.md`            |
+| Mount Skra inside a Web Component / microfrontend                         | `theming-and-encapsulation.md`            |
+| Open a dialog or tooltip                                                   | `overlays.md`                             |
+| Space components apart                                                     | `layout.md`                               |
+| Wrap a Skra atom in a project-specific component                          | `wrapping-patterns.md`                    |
+
+---
+
+_Source of truth for the rules: Skra `FORGE_ADR_SUMMARY.md` + `adr/decisions/`. Real
+consumption evidence: `apps/dogfood/FRICTION_JOURNAL.md`. This guide restates the consumer
+slice of those — on divergence, the ADRs win._

package/consumer-guide/forms-and-binding.md

@@ -22,15 +22,31 @@ directives attach to the same host, so `[formField]`, `[formControl]`/`formContr
 
 ```html
 <!-- text: Signal Forms / Reactive / ngModel — all valid -->
-<input skraInput [formField]="form().email" />
-<input skraInput [formControl]="emailCtrl" />
-<input skraInput [(ngModel)]="email" />
+<skra-field>
+  <label skraLabelFor>Email</label>
+  <input skraInput [formField]="form().email" />
+</skra-field>
+
+<skra-field>
+  <label skraLabelFor>Email</label>
+  <input skraInput [formControl]="emailCtrl" />
+</skra-field>
+
+<skra-field>
+  <label skraLabelFor>Email</label>
+  <input skraInput [(ngModel)]="email" />
+</skra-field>
 
 <!-- checkbox / switch: native checked + change (or any form directive) -->
 <input type="checkbox" skraCheckbox
        [checked]="accepted()" (change)="accepted.set($any($event.target).checked)" />
 ```
 
+> The `<skra-field>` wrapper above is about the **label**, not the binding — the form
+> directive attaches to the native host either way. A control that needs no visible label,
+> hint or error can stand alone (`<label>Search <input skraInput /></label>`); see
+> `setup-and-gotchas.md` Gotcha 5.
+
 **Radios group natively** — `<fieldset skraFieldset>` + `<legend skraLegend>`, with
 selection coordinated through the shared `name`:
 

package/consumer-guide/layout.md

@@ -15,6 +15,25 @@ a native host** (a bounded allowlist of `div`/`section`/`nav`/`ul`/…), **never
 <ul skraStack gap="sm">…</ul>                 <!-- list markers normalized, restorable -->
 ```
 
+## Sizing container-filling components (e.g. `skra-select`)
+
+Layout isolation (ADR 022) means a component never imposes its own outer size either. Some
+components are **`display: block` and fill their container's inline size** by design — the
+form controls especially (`skra-select`, `skra-combobox`, `input[skraInput]`, …), because
+their primary home is a full-width form field. A **standalone** one (a toolbar select, a
+filter control) therefore needs the consumer to size it — give it a width-bearing wrapper:
+
+```html
+<div style="inline-size: 16rem"><skra-select …>…</skra-select></div>
+```
+
+**Gotcha:** dropped straight into a `display: flex` / `display: grid` row with no explicit
+`flex` / `inline-size` / `min-inline-size`, a container-filling component collapses toward its
+content width — and when it holds no value yet it can shrink to just its padding + icon (looks
+"broken"). This is the isolation contract working as intended, not a component bug: size the
+component (wrapper width, a `skraGrid` track, or a `flex` basis), don't expect an intrinsic
+width.
+
 ## Stack — 1D flex (`[skraStack]`)
 
 Arranges children in a row or column.

package/consumer-guide/overlays.md

@@ -1,100 +1,100 @@
-# Overlays
-
-> Load this for: opening a dialog, tooltip, popover, or menu in the native top layer, and the
-> shadow/iframe limits. Governed by ADR 0044 (native top-layer substrate — no CDK portal, no
-> z-index). For `select` / `combobox` / `datepicker` **value binding**, see `forms-and-binding.md`
-> (they are value-owned overlays).
-
-## Shared model
-
-All Skra overlays render in the **browser top layer** via native platform APIs (`<dialog>` +
-the Popover API), not a `document.body` portal. Consequences for you:
-
-- **No z-index management.** Stacking is invocation-order; nesting is always correct.
-- **Escape, light-dismiss, `::backdrop`** are platform-owned (per overlay, below).
-- They open correctly **from inside a Shadow DOM root**; per-context limits at the bottom.
-
-## Dialog (modal) — `dialog[skraDialog]`
-
-A Component on the native `<dialog>`, opened with the **native** `showModal()` and closed with
-`close()`. `role="dialog"`, `aria-modal`, Escape, the `::backdrop` scrim, scroll-lock and focus
-containment are native:
-
-```html
-<button skraButton (click)="dlg.showModal()">Delete…</button>
-
-<dialog skraDialog #dlg aria-labelledby="confirm-title" size="sm">
-  <h2 id="confirm-title">Delete item?</h2>
-  <p>This can't be undone.</p>
-  <button skraButton autofocus (click)="dlg.close()">Cancel</button>
-  <button skraButton (click)="confirm(); dlg.close()">Delete</button>
-</dialog>
-```
-
-- **Name it** with `aria-labelledby` → a projected heading (no `ariaLabel` input — ADR 033).
-- **Initial focus** is the consumer-placed native `autofocus` attribute.
-- `size` is `sm | md | lg` (ADR 035).
-
-## Tooltip — `[skraTooltip]` on your own trigger
-
-A supplementary, non-interactive **description** shown on hover AND focus. It is **not** the
-accessible name — it merges into the trigger's `aria-describedby`:
-
-```html
-<button skraButton [skraTooltip]="'Open settings'" aria-label="Settings">⚙</button>
-```
-
-An icon-only trigger **still needs its own accessible name** (Path 3 — see
-`accessible-names.md`); the tooltip never substitutes for it.
-
-## Popover (non-modal panel) — `skra-popover`
-
-A Component on the panel with projected interactive content. The trigger is **your own button**
-linked by the native `popovertarget`; toggle, light-dismiss, Escape, and stacking are
-platform-owned. **You MUST give the panel an `id`:**
-
-```html
-<button skraButton popovertarget="account-menu">Account</button>
-<skra-popover id="account-menu" aria-labelledby="account-menu-title">
-  <h3 id="account-menu-title">Signed in as…</h3>
-  <!-- interactive content -->
-</skra-popover>
-```
-
-Focus is **not** trapped/force-moved (non-modal). Name via `aria-labelledby` → projected
-heading.
-
-## Menu (commands) — `skra-menu` + `button[skraMenuItem]`
-
-A WAI-ARIA APG menu-button: a homogeneous command set, arrow-key navigated, activating an item
-closes it. Trigger is your own button with `popovertarget` + `aria-haspopup="menu"`; **give the
-panel an `id`**. Focus moves **into** the menu on open:
-
-```html
-<button skraButton popovertarget="row-actions" aria-haspopup="menu">Actions</button>
-<skra-menu id="row-actions">
-  <button skraMenuItem (click)="edit()">Edit</button>
-  <button skraMenuItem disabled (click)="archive()">Archive</button>
-  <button skraMenuItem (click)="remove()">Delete</button>
-</skra-menu>
-```
-
-- **Side effects on open/close:** bind the **native `(toggle)`** event — there is no Skra
-  output (native-first).
-- A right-click context menu is **not** a menu trigger mode — use a visible button (SRP +
-  WCAG 2.1.1).
-
-## Selection overlays — value binding lives elsewhere
-
-`skra-select`, `skra-multi-select`, `skra-combobox`, `skra-datepicker` render their listbox
-in the top layer like the above, **but their value is consumer-owned** — bind with the
-`[value]`/`(valueChange)` bridge documented in `forms-and-binding.md` (class B). The combobox
-filters with consumer-owned data (ADR 0049): you own the filtered option list.
-
-## Limits across boundaries (same as theming — recap)
-
-- Overlays **open** from inside a Shadow DOM root (top layer + positioning cross the boundary,
-  F-10). But the global-slice pieces — `::backdrop` scrim and `html:has()` scroll-lock — need
-  the bridge / don't pierce the boundary (F-6/F-7). See `theming-and-encapsulation.md`.
-- **iframe**: overlays are contained to the frame's own top layer — they cannot overlay the
-  parent app (F-11).
+# Overlays
+
+> Load this for: opening a dialog, tooltip, popover, or menu in the native top layer, and the
+> shadow/iframe limits. Governed by ADR 0044 (native top-layer substrate — no CDK portal, no
+> z-index). For `select` / `combobox` / `datepicker` **value binding**, see `forms-and-binding.md`
+> (they are value-owned overlays).
+
+## Shared model
+
+All Skra overlays render in the **browser top layer** via native platform APIs (`<dialog>` +
+the Popover API), not a `document.body` portal. Consequences for you:
+
+- **No z-index management.** Stacking is invocation-order; nesting is always correct.
+- **Escape, light-dismiss, `::backdrop`** are platform-owned (per overlay, below).
+- They open correctly **from inside a Shadow DOM root**; per-context limits at the bottom.
+
+## Dialog (modal) — `dialog[skraDialog]`
+
+A Component on the native `<dialog>`, opened with the **native** `showModal()` and closed with
+`close()`. `role="dialog"`, `aria-modal`, Escape, the `::backdrop` scrim, scroll-lock and focus
+containment are native:
+
+```html
+<button skraButton (click)="dlg.showModal()">Delete…</button>
+
+<dialog skraDialog #dlg aria-labelledby="confirm-title" size="sm">
+  <h2 id="confirm-title">Delete item?</h2>
+  <p>This can't be undone.</p>
+  <button skraButton autofocus (click)="dlg.close()">Cancel</button>
+  <button skraButton (click)="confirm(); dlg.close()">Delete</button>
+</dialog>
+```
+
+- **Name it** with `aria-labelledby` → a projected heading (no `ariaLabel` input — ADR 033).
+- **Initial focus** is the consumer-placed native `autofocus` attribute.
+- `size` is `sm | md | lg` (ADR 035).
+
+## Tooltip — `[skraTooltip]` on your own trigger
+
+A supplementary, non-interactive **description** shown on hover AND focus. It is **not** the
+accessible name — it merges into the trigger's `aria-describedby`:
+
+```html
+<button skraButton [skraTooltip]="'Open settings'" aria-label="Settings">⚙</button>
+```
+
+An icon-only trigger **still needs its own accessible name** (Path 3 — see
+`accessible-names.md`); the tooltip never substitutes for it.
+
+## Popover (non-modal panel) — `skra-popover`
+
+A Component on the panel with projected interactive content. The trigger is **your own button**
+linked by the native `popovertarget`; toggle, light-dismiss, Escape, and stacking are
+platform-owned. **You MUST give the panel an `id`:**
+
+```html
+<button skraButton popovertarget="account-menu">Account</button>
+<skra-popover id="account-menu" aria-labelledby="account-menu-title">
+  <h3 id="account-menu-title">Signed in as…</h3>
+  <!-- interactive content -->
+</skra-popover>
+```
+
+Focus is **not** trapped/force-moved (non-modal). Name via `aria-labelledby` → projected
+heading.
+
+## Menu (commands) — `skra-menu` + `button[skraMenuItem]`
+
+A WAI-ARIA APG menu-button: a homogeneous command set, arrow-key navigated, activating an item
+closes it. Trigger is your own button with `popovertarget` + `aria-haspopup="menu"`; **give the
+panel an `id`**. Focus moves **into** the menu on open:
+
+```html
+<button skraButton popovertarget="row-actions" aria-haspopup="menu">Actions</button>
+<skra-menu id="row-actions">
+  <button skraMenuItem (click)="edit()">Edit</button>
+  <button skraMenuItem disabled (click)="archive()">Archive</button>
+  <button skraMenuItem (click)="remove()">Delete</button>
+</skra-menu>
+```
+
+- **Side effects on open/close:** bind the **native `(toggle)`** event — there is no Skra
+  output (native-first).
+- A right-click context menu is **not** a menu trigger mode — use a visible button (SRP +
+  WCAG 2.1.1).
+
+## Selection overlays — value binding lives elsewhere
+
+`skra-select`, `skra-multi-select`, `skra-combobox`, `skra-datepicker` render their listbox
+in the top layer like the above, **but their value is consumer-owned** — bind with the
+`[value]`/`(valueChange)` bridge documented in `forms-and-binding.md` (class B). The combobox
+filters with consumer-owned data (ADR 0049): you own the filtered option list.
+
+## Limits across boundaries (same as theming — recap)
+
+- Overlays **open** from inside a Shadow DOM root (top layer + positioning cross the boundary,
+  F-10). But the global-slice pieces — `::backdrop` scrim and `html:has()` scroll-lock — need
+  the bridge / don't pierce the boundary (F-6/F-7). See `theming-and-encapsulation.md`.
+- **iframe**: overlays are contained to the frame's own top layer — they cannot overlay the
+  parent app (F-11).