@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/ai/components/color-swatches.md

@@ -0,0 +1,82 @@
+# ColorSwatches
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:color-swatches` · Kerf UI · component · Controls
+
+A fixed palette: a native radio group of round color swatches with no visible text, each named by its color, the chosen one ringed independently of hue, with a struck-through no-color swatch, compact size, and disabled state.
+
+## When to use
+
+Let a person choose one color from a small fixed palette (a label, tag, or command color), or no color.
+
+- A setting takes one color from a small, curated palette (a label, calendar, or command color): render ColorSwatches with name, a label, swatches, and value, and read the choice on change.
+- No color is a valid choice: include a swatch with color 'transparent'.
+
+**Not when:**
+
+- Do not use it when any color is allowed; use a ColorPicker or ColorField.
+- Do not use it for choices that are not colors; use ChoiceChips or a RadioGroup.
+- Do not put text in the swatches; the color's label names each one.
+
+**Alternatives:**
+
+- [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips with swatches when each color also needs a visible name.
+- [RadioGroup](./radio-group.md) (nearest) — Use a RadioGroup for choices that are not colors.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/color-swatches` — exports `ColorSwatches`, `ColorSwatchesProps`, `ColorSwatch`, `ColorSwatchesSize`, `ColorSwatchesRootAttributes`.
+- CSS: the browser build of `@kerfjs/ui/color-swatches` pulls its CSS automatically; import `@kerfjs/ui/color-swatches.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/color-swatches`](../public-api-signatures-v1.md#kerfjsuicolor-swatches) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- fixed palette with a visible label
+- a no-color swatch
+- compact size
+- disabled
+- ariaLabel without a visible label
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the palette and its color names; the chosen value (read it on change through action); the field name and form association.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The group takes the shared block-content inset (a transparent 1px border and 8px padding), so its label sits on the text column; each swatch keeps 4px of room for its ring, pulled back at the row's edges.
+
+## Accessibility
+
+- It is a native radio group: Tab reaches it once and the arrow keys move the choice; each radio is named by its color label, also shown as the swatch's hover hint.
+- The chosen swatch wears a ring in the text color set off by a gap, so the choice never depends on hue; forced colors draw it in Highlight.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-color-swatches`, `kui-color-swatches__label`, `kui-color-swatches__list`, `kui-color-swatches__swatch`, `kui-color-swatches__input`, `kui-color-swatches__dot`.
+
+Never put `kui-color-swatches`, `kui-color-swatches__label`, `kui-color-swatches__list`, `kui-color-swatches__swatch`, `kui-color-swatches__input`, `kui-color-swatches__dot` on an element you write; render `ColorSwatches` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ChoiceChips](./choice-chips.md), [RadioGroup](./radio-group.md).
+- Docs: [`docs/color-swatches.md`](../../docs/color-swatches.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=color-swatches`.

package/ai/components/column-track.md

@@ -0,0 +1,78 @@
+# ColumnTrack
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:column-track` · Kerf UI · component · Structure
+
+A horizontal track of equal, min-width columns that scrolls sideways, or pages one column at a time with peek and snapping.
+
+## When to use
+
+Lay out a board of columns (kanban) as one horizontal scroll owner: equal columns that never shrink below a minimum, or a paged phone layout with a peeking next column and start snapping, without app track CSS.
+
+- A board shows several parallel columns (kanban lanes) that must keep a readable width and scroll sideways, or page one at a time on a phone.
+
+**Not when:**
+
+- Do not use for a responsive grid that wraps; use Grid.
+- Do not use for two resizable panes; use SplitView or ResizableRegion.
+- Do not re-track a Grid from application CSS to get overflowing columns.
+
+**Alternatives:**
+
+- [Grid](./grid.md) (nearest) — Use Grid when columns should wrap or collapse instead of scrolling.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/column-track` — exports `ColumnTrack`.
+- CSS: the browser build of `@kerfjs/ui/column-track` pulls its CSS automatically; import `@kerfjs/ui/column-track.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/column-track`](../public-api-signatures-v1.md#kerfjsuicolumn-track) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- scroll with a minimum column width
+- paged with peek and mandatory snapping
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the columns and their content; choosing scroll or paged layout (for example by device class); drag and drop between columns.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The track pads 8px inline and fills its parent's height; columns sit flush and own their insets and vertical scrolling.
+
+## Accessibility
+
+- Name the track with aria-label through rootAttributes when it is a landmark-like region; give each column a region name. Paged scrolling is smooth unless reduced motion is preferred.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-column-track`, `kui-column-track__columns`.
+
+Never put `kui-column-track`, `kui-column-track__columns` on an element you write; render `ColumnTrack` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-layout-inline-margin`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Grid](./grid.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=column-track`.

package/ai/components/combobox.md

@@ -0,0 +1,90 @@
+# Combobox
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:combobox` · Kerf UI · component · Controls
+
+A free-text field with a filtered suggestion list that can also create a new value.
+
+## When to use
+
+Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.
+
+- People type to find an existing value among many, or create a new one (tags, labels, recipients).
+
+**Not when:**
+
+- Do not use when only existing values are allowed and nothing needs typing; use Select.
+- Do not use for free text plus removable filter tokens in one editor; use SearchField.
+- Do not style a native input with a datalist from app CSS.
+
+**Alternatives:**
+
+- [Select](./select.md) (nearest) — Use Select when only existing values are allowed.
+- [SearchField](./search-field.md) (nearest) — Use SearchField for search text with removable filter tokens.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/combobox` — exports `Combobox`, `wireComboboxes`.
+- CSS: the browser build of `@kerfjs/ui/combobox` pulls its CSS automatically; import `@kerfjs/ui/combobox.css` manually only without the `browser` export condition.
+- Wiring: `wireComboboxes` from `@kerfjs/ui/wire-comboboxes` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/combobox`](../public-api-signatures-v1.md#kerfjsuicombobox) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- with create
+- suggestions only (createLabel={false})
+- hint
+- disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the suggestions and the committed values; normalizing and validating created values; clearing the field after a commit.
+
+**Wiring:** `wireComboboxes` is required.
+
+- Filters suggestions, moves the active option, and reports commits; without it the list never opens.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-value` on `the create option (kui-combobox__option[data-create])` (`wireComboboxes`): The typed text the create option would commit; rewritten as the person types.
+- `data-placement` on `kui-combobox__listbox` (`wireComboboxes`): The side the open listbox was placed on (bottom-start, or top-start after a flip when the field is near the viewport's bottom).
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Label and hint sit on the value's text column (1px border + 8px padding); the 44px field matches a themed wa-input.
+
+## Accessibility
+
+- Native input with role=combobox, aria-autocomplete=list, aria-expanded, aria-controls, and aria-activedescendant; options are role=option in a listbox. The visible label is a real label; the hint is aria-describedby.
+- The suggestion listbox is a manual popover in the top layer, placed below the field at its width and flipped when short, so a clipping or scrolling ancestor (an AnchoredSurface, a dialog, a scrolling List) never cuts it off.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-combobox`, `kui-combobox__label`, `kui-combobox__hint`, `kui-combobox__control`, `kui-combobox__input`, `kui-combobox__listbox`, `kui-combobox__option`.
+
+Never put `kui-combobox`, `kui-combobox__label`, `kui-combobox__hint`, `kui-combobox__control`, `kui-combobox__input`, `kui-combobox__listbox`, `kui-combobox__option` on an element you write; render `Combobox` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-text-link`, `--kui-color-brand-fill-quiet`, `--kui-font-xs`, `--kui-font-s`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-shadow-l`, `--kui-space-2xs`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Select](./select.md), [SearchField](./search-field.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=combobox`.

package/ai/components/content-item.md

@@ -0,0 +1,101 @@
+# ContentItem
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:content-item` · Kerf UI · component · Structure
+
+One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.
+
+## When to use
+
+Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
+
+- An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
+- A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
+- A content item needs the base surface or a coordinated semantic status treatment: pass appearance="surface" or a semantic appearance such as success or danger.
+- A content item should follow a pill control's 22px radius: pass shape="pill".
+- A selectable rich card needs nested controls: use selectionMode="multiple" inside a labeled List multi-select grid.
+
+**Not when:**
+
+- Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.
+- Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.
+- Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.
+- Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface.
+
+**Alternatives:**
+
+- [ListInsetText](./list-inset-text.md) (nearest) — Use ListInsetText when bare text only needs to align with neighboring content items.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered, filled surface around a vertical stack.
+- [Application Layout](./layout.md) (composes-with) — Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-item` — exports `ContentItem`.
+- JavaScript: `@kerfjs/ui/selection` — exports `applySelection`, `selectionGesture`, `isApplePlatform`.
+- CSS: the browser build of `@kerfjs/ui/content-item` pulls its CSS automatically; import `@kerfjs/ui/content-item.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures-v1.md#kerfjsuicontent-item), [`@kerfjs/ui/selection`](../public-api-signatures-v1.md#kerfjsuiselection) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- unframed rounded item
+- framed rounded item
+- pill item
+- framed pill item
+- base surface item
+- neutral, info, pop, success, warning, or danger semantic item
+- brand-loud item (solid brand fill, on-loud foreground)
+- chat bubble at the start or end of the row (bubble), fit to its content up to 80%
+- named focus-target region
+- multi-select rich grid row
+- gridRow: a non-selectable row (role="row" with a gridcell) between selectable rows of a multi-select List or Grid
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; whether the item needs a surface or semantic appearance; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; optional static-item Tab stop and persistent focus outline; the selection set and Shift/Cmd extension for multi-select rich cards.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The 1px border is always reserved; transparent items paint it only when frame="framed", while surface and semantic appearances coordinate its color with their background and foreground.
+
+## Accessibility
+
+- An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role="region").
+- focusTarget makes the item a programmatic focus target (tabindex="-1", never a tab stop), such as a NavStack view's data-nav-focus target.
+- The frame is decorative and never the only signal of state.
+- selectionMode="multiple" renders a focusable row with aria-selected and a gridcell for nested controls; place it in a labeled List selectionMode="multiple" grid. wireContentItems moves focus among rows with Up/Down and Home/End while nested controls retain those keys. Enter and Space activate the card with a click that carries the key's Shift, Ctrl, and Cmd state, so one delegated click handler implements range and toggle selection for pointer and keyboard alike. Guard the app's delegated card action with isContentItemActivation so a nested control does not select the row.
+- In a multi-select List or Grid, wireContentItems keeps one roving Tab stop (the last focused row, else the first selected, else the first enabled) across re-renders. A gridRow item is a row with a gridcell and no aria-selected or Tab stop; arrow keys skip it and its controls stay reachable by Tab.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+Classes an application may place on its own elements: `kui-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+A plain `<div>` carrying them is exactly what `ContentItem` renders: render `ContentItem` instead (`KUI-L103`), and place the classes only on another carrier element.
+
+Public tokens it reads: `--kui-content-item-border`, `--kui-content-item-radius`, `--kui-content-item-background`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ListInsetText](./list-inset-text.md), [SunkenPanel](./sunken-panel.md), [Application Layout](./layout.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#content-items`](../../docs/layout.md#content-items).
+- UX catalog route: `?component=content-item`.

package/ai/components/content-swap.md

@@ -0,0 +1,78 @@
+# ContentSwap
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:content-swap` · Kerf UI · component · Structure
+
+Two content sides sharing one cell, swapped in place with a push, a crossfade, or no motion.
+
+## When to use
+
+Swap arbitrary content in place (a dialog body that steps to a second page, a label or footer whose actions change) with Kerf-owned push or crossfade motion, reduced-motion handling, and an inert, hidden inactive side.
+
+- A region swaps between two contents in place, such as a dialog's two steps or a footer's action sets, and the change should read as motion.
+
+**Not when:**
+
+- Do not use for full navigation views with their own toolbars; use NavStack.
+- Do not use to swap more than two states at once; render the current pair.
+- Do not hand-roll stacked cells, inert handling, or push keyframes in app CSS.
+
+**Alternatives:**
+
+- [NavStack](./nav-stack.md) (nearest) — Use NavStack for full views with toolbars and back navigation.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-swap` — exports `ContentSwap`.
+- CSS: the browser build of `@kerfjs/ui/content-swap` pulls its CSS automatically; import `@kerfjs/ui/content-swap.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-swap`](../public-api-signatures-v1.md#kerfjsuicontent-swap) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- push forward or backward
+- crossfade
+- none
+- full-width slot region
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** which side is active and the push direction; both sides' content; the region's name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Both sides share one grid cell; the region keeps the active side's height and clips the motion.
+
+## Accessibility
+
+- The inactive side is inert and aria-hidden; label makes the swap a named region. Push mirrors in right-to-left documents. Reduced motion replaces the slide with a short fade.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-content-swap`, `kui-content-swap__side`.
+
+Never put `kui-content-swap`, `kui-content-swap__side` on an element you write; render `ContentSwap` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [NavStack](./nav-stack.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=content-swap`.

package/ai/components/corner-status.md

@@ -0,0 +1,88 @@
+# CornerStatus
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:corner-status` · Kerf UI · component · Feedback
+
+Non-dismissible app-level status pinned to a viewport corner in the top layer, hosting StateBanner.
+
+## When to use
+
+Show ongoing app-level progress such as "Loading…" or "Updating Tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+
+- Show ongoing app-level progress or status that has no better home beside the affected work and must stay visible until the work ends.
+
+**Not when:**
+
+- Do not use for transient, dismissible confirmation; use a toast.
+- Do not use for status that belongs beside the affected work; place a StateBanner there.
+- Do not position a StateBanner with fixed-position application CSS; use CornerStatus.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (composes-with) — Compose one or more StateBanners (urgency="status") inside it; they stack.
+- [Toast](./wa-toast.md) (prefer-over) — A toast item is transient and always dismissible; CornerStatus stays until the application removes it.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/corner-status` — exports `CornerStatus`, `wireCornerStatus`.
+- CSS: the browser build of `@kerfjs/ui/corner-status` pulls its CSS automatically; import `@kerfjs/ui/corner-status.css` manually only without the `browser` export condition.
+- Wiring: `wireCornerStatus` from `@kerfjs/ui/wire-corner-status` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/corner-status`](../public-api-signatures-v1.md#kerfjsuicorner-status) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- bottom-end
+- bottom-start
+- top-end
+- top-start
+- embedded (in flow)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md).
+
+## State and wiring
+
+**The app owns:** status lifetime (render while the work runs, remove when it ends); the composed StateBanner copy and progress; corner placement.
+
+**Wiring:** `wireCornerStatus` is required.
+
+- Opens each overlay host in the top layer as renders insert it; without it the Popover API keeps the host hidden.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Placement owns the 16px viewport gutter plus device safe-area insets; a StateBanner inside drops its inline margin and gains elevation.
+
+## Accessibility
+
+- The host adds no role; the composed StateBanner with urgency="status" is the polite live region.
+- Opening never moves focus, and there is no close button, light dismiss, or Escape handling to compete with dialogs.
+- A modal dialog opened while it shows stacks above it and makes it inert (unannounced); show progress the dialog's task depends on inside the dialog.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-corner-status`.
+
+Never put `kui-corner-status` on an element you write; render `CornerStatus` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-corner-status-gutter`, `--kui-corner-status-z-index`, `--kui-safe-area-block-end`, `--kui-safe-area-block-start`, `--kui-safe-area-inline-end`, `--kui-safe-area-inline-start`, `--kui-space-m`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [StateBanner](./state-banner.md), [Toast](./wa-toast.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
+- UX catalog route: `?component=corner-status`.

package/ai/components/disclosure-arrow.md

@@ -0,0 +1,77 @@
+# DisclosureArrow
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:disclosure-arrow` · Kerf UI · component · Foundation
+
+Root-scaled 18px animated open and closed disclosure indicator with configurable directions, shortest-path rotation, and right-oriented replacement icon content.
+
+## When to use
+
+Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
+
+- Add a shortest-path rotating indicator to a control that owns open and closed state; author replacement icon content facing right before direction transforms are applied.
+
+**Not when:**
+
+- Do not use the arrow as the interactive control or accessible name by itself.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/disclosure-arrow` — exports `DisclosureArrow`.
+- CSS: the browser build of `@kerfjs/ui/disclosure-arrow` pulls its CSS automatically; import `@kerfjs/ui/disclosure-arrow.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/disclosure-arrow`](../public-api-signatures-v1.md#kerfjsuidisclosure-arrow) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- open
+- closed
+- custom directions
+- replacement icon
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `size`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `size={remify(24)}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** open state; interaction; accessible control label.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The arrow is decorative; expose expanded state through aria-expanded on its owning control and keep that control's accessible name stable.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-disclosure-arrow`.
+
+Never put `kui-disclosure-arrow` on an element you write; render `DisclosureArrow` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-disclosure-arrow-duration`, `--kui-disclosure-arrow-size`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=disclosure-arrow`.