@kerfjs/ui 5.0.0-beta.104 → 5.0.0-beta.105

package/docs/color-field.md

@@ -0,0 +1,65 @@
+# ColorField
+
+`@kerfjs/ui/color-field` puts a color in a form or inspector without keeping a
+full picker open. It is a label above a trigger that shows the color as a
+swatch (over a checkerboard, so opacity reads) and its hex value. Pressing the
+trigger opens a [`ColorPicker`](./color-picker.md) in an `AnchoredSurface`
+below it.
+
+```tsx
+import { ColorField } from "@kerfjs/ui/color-field";
+import { wireColorFields } from "@kerfjs/ui/wire-color-fields";
+
+<ColorField id="fill" label="Fill" value={fill.value} mode={mode.value} name="fill" />;
+
+const stop = wireColorFields(root, {
+  onChange: ({ value, mode: next }) => {
+    fill.value = value;
+    mode.value = next;
+  },
+  pickers: { fill: { presets } },
+});
+```
+
+## Props
+
+- `id` (required): the trigger's id; it prefixes the label, value, hint, and
+  error ids.
+- `label`, or `ariaLabel` for a field without a visible label.
+- `value` (required): CSS color text; invalid text shows black.
+- `mode`: the picker's model when it opens — `rgb` (default), `hsl`, `hsb`,
+  or `gray`.
+- `alpha` (default true): offer opacity. Without it the value is opaque.
+- `name`, `form`: a hidden input submits the hex value.
+- `hint`, `error` (an error marks the field invalid), `required`, `disabled`.
+- `size`: `default` or `compact`, matching TextField's sizes.
+- `className`, `rootAttributes`, `slot`.
+
+## Wiring and values
+
+`wireColorFields(root, { onInput?, onChange?, pickers? })` wires every
+ColorField under `root`:
+
+- Pressing a trigger opens a ColorPicker with the field's value, model, and
+  opacity, plus any `pickers[id]` options (`presets`, `samples`,
+  `addSampleAction`, `eyedropper`).
+- Edits preview at once on the trigger's swatch, hex, and hidden input.
+  Live edits go to `onInput`; committed edits go to `onChange` with
+  `{ id, value, mode }`. Re-render the field with the reported value and mode.
+- Escape or a press outside closes the picker, and focus returns to the
+  trigger. The surface stays on screen, flipping above the field or
+  scrolling the picker when space is short.
+- The disposer removes the wiring and closes an open picker.
+
+The value is `#rrggbb`, or `#rrggbbaa` below full opacity.
+
+## Accessibility and geometry
+
+The trigger is a button named by the label and the current hex value, with
+`aria-haspopup="dialog"` and `aria-expanded`; the hint and error describe it.
+The picker opens in a non-modal surface named by the label. The trigger
+matches TextField's box, label, hint, and error geometry.
+
+Use an inline `ColorPicker` when choosing the color is the view's main task,
+and `ColorSwatches` for a small fixed palette. `ColorField` replaces
+`wa-color-picker`, which is Discouraged.

package/docs/color-picker.md

@@ -0,0 +1,71 @@
+# ColorPicker
+
+`@kerfjs/ui/color-picker` is a full inline color picker panel:
+
+- a saturation and brightness area;
+- a hue slider and, optionally, an opacity slider on a checkerboard;
+- a color-model menu (RGB, HSL, HSB, Grayscale) with its channel fields;
+- a hex field (8 digits below full opacity) and an opacity field;
+- a screen sampler where the browser offers the EyeDropper API;
+- optional preset and sample swatches.
+
+```tsx
+import { ColorPicker } from "@kerfjs/ui/color-picker";
+import { wireColorPickers } from "@kerfjs/ui/wire-color-pickers";
+
+<ColorPicker id="fill" label="Fill Color" value={fill.value} mode={mode.value} />;
+
+const stop = wireColorPickers(root, {
+  onChange: ({ id, value, mode: next }) => {
+    fill.value = value;
+    mode.value = next;
+  },
+});
+```
+
+## Props
+
+- `id` and `label` (required): identity and the picker's accessible name.
+- `value` (required): CSS color text (`#rrggbb[aa]`, `rgb()`, `hsl()`);
+  invalid text shows black.
+- `mode`: `rgb` (default), `hsl`, `hsb`, or `gray` — which channel fields show.
+- `alpha` (default true): the opacity slider and field. Without it the value
+  is always opaque.
+- `name`, `form`: a hidden input submits the hex value.
+- `eyedropper` (default true): the screen sampler, shown only where the
+  browser has the EyeDropper API.
+- `presets`: a row of `ColorSwatches` under the controls. `samples`: titled
+  groups (`{ title, swatches }`), such as "Document Colors".
+  `addSampleAction`: a `data-action` for an "Add to Samples" button; read
+  the picker's value and add it to your samples.
+- `disabled`, `className`, `rootAttributes`, `slot`.
+
+## Wiring and values
+
+`wireColorPickers(root, { onInput?, onChange? })` makes every picker under
+`root` interactive. The interactive surface belongs to the wiring after the
+first render, so a drag never fights a re-render. When the app re-renders a
+picker with a new `value` (or `mode`), the picker adopts it.
+
+- **The area** takes pointer drags and the arrow keys (Shift for 10% steps);
+  Page Up and Down change brightness, Home and End saturation.
+- **Hue and opacity** are native range inputs.
+- **Fields** commit on Enter or blur; Escape restores the shown value; invalid
+  text restores it too.
+- **Swatches** (presets and samples) apply their color.
+
+Each change dispatches a bubbling `kui-color-input` (live) or
+`kui-color-change` (committed) event with `{ value, mode }` and calls
+`onInput` or `onChange`. The value is `#rrggbb`, or `#rrggbbaa` below full
+opacity. The picker keeps hue, saturation, and brightness as its own state,
+so a hue survives while the color is gray, and conversions round-trip without
+drift.
+
+## Accessibility and geometry
+
+The picker is a named group. The area is a slider named "Saturation and
+Brightness" whose spoken value gives both; every field is named (Red, Hue,
+Hex Color, Opacity). The panel takes the shared block-content inset, fills
+its container up to 320px, and spaces its rows 12px apart.
+
+Use `ColorSwatches` for a small fixed palette.

package/docs/color-swatches.md

@@ -0,0 +1,46 @@
+# ColorSwatches
+
+`@kerfjs/ui/color-swatches` chooses one color from a small fixed palette: a
+row of round swatches with no visible text. It is a native radio group, so
+the chosen value submits under `name` and the platform owns the keyboard.
+
+```tsx
+import { ColorSwatches } from "@kerfjs/ui/color-swatches";
+import { fillColor } from "@kerfjs/ui/css-values";
+
+<ColorSwatches
+  name="command-color"
+  label="Command Color"
+  value={color.value}
+  action="pick-color"
+  swatches={[
+    { value: "none", label: "No Color", color: "transparent" },
+    { value: "#ff3b30", label: "Red", color: fillColor("#ff3b30") },
+    { value: "#0a84ff", label: "Blue", color: fillColor("#0a84ff") },
+  ]}
+/>;
+```
+
+## Props
+
+- `name` (required): the radio group the chosen value submits under.
+- `swatches` (required): `{ value, label, color }`. `label` names the swatch
+  for assistive technology and shows as its hover hint. `color` is a
+  `CssColor` (`uiColor()`, `colorVar()`, or `fillColor()`) or `'transparent'`
+  for the no-color swatch, drawn outlined and struck through.
+- `value`: the chosen swatch.
+- `label` (a visible legend) or `ariaLabel` names the group.
+- `size` `default` (24px swatches) or `compact` (20px), `disabled`, `form`,
+  and `action` (a `data-action` on each radio; listen for `change`).
+
+## Behavior and geometry
+
+Tab reaches the group once; the arrow keys move the choice; Space chooses the
+focused swatch. The chosen swatch wears a 2px ring in the text color, set off
+from the dot by a 2px gap, so the choice never depends on the swatch's hue;
+forced colors draw it in `Highlight`. The group takes the shared
+block-content inset (a transparent 1px border and 8px padding), and the
+swatches wrap with the 8px control gap.
+
+Use `ChoiceChips` with swatches when each color also needs a visible name,
+and the ColorPicker when any color is allowed.

package/docs/component-contract.md

@@ -234,13 +234,14 @@ See the
 [`application-ui-profile.json`](./examples/application-ui-profile.json) example.
 
 The package defaults avoid every `Discouraged` Web Awesome entry — each
-`webawesome` catalog entry whose `recommendation` is not `supported`, except the
-encouraged `wa-popup` primitive — under a concept whose `preferred` value is the
+`webawesome` catalog entry whose `recommendation` is not `supported` — under a concept whose `preferred` value is the
 Kerf component that wraps or replaces it (`command-menu` → `PopupMenu`,
 `value-selection` → `Select`, `application-tabs` → `TabBar`, `icon` →
 `LucideIcon`, `resizable-pane` → `ResizableRegion`, `exclusive-choice` →
 `SegmentedControl`, `hierarchy-navigation` → `List`, `embedded-media` →
-`ContentItem`). `eslint-plugin-kerfjs` `ui-preferences` (`KUI-L301`, also run by
+`ContentItem`, `anchored-surface` → `AnchoredSurface`, `content-container` →
+`ContentItem`, `inline-status` → `StateBanner`, `application-shell` → the
+app-shell recipe, `modal-dialog` → `DialogSurface`). `eslint-plugin-kerfjs` `ui-preferences` (`KUI-L301`, also run by
 `kerf-ui-doctor`) therefore reports a Discouraged element written directly as a
 JSX tag (`<wa-dropdown>`) as well as through an imported component. A declared
 component's own source file is exempt, because that wrapper is the sanctioned
@@ -303,7 +304,7 @@ paths each entry owns, relative to the consumer package root.
 - Consumers configure presentation through component props and documented `--kui-*` semantic tokens. Foundation tokens provide opinionated neutral, brand/info, non-status pop, success, warning, and danger fill/border/foreground roles. Application stylesheets must not select package component classes or descendants. If genuinely new structure needs CSS, encapsulate that structure and its stylesheet in an application-owned component; configure any nested Kerf components through their public APIs. A thin composition that only connects other components should normally have no stylesheet. It may style only raw elements or layout it owns, never its component children.
 
 `ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
-`ListHeader.rootAttributes`, `AppTab.rootAttributes`,
+`ListHeader.rootAttributes`, `TabBarItem.rootAttributes`,
 `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` accept
 application-owned `data-*` metadata without
 adding product fields to the shared API. A `ListActionRow` trailing action uses
@@ -317,7 +318,7 @@ component or helper writes its protected attributes after the accepted metadata.
 structurally widened, and JavaScript callers therefore cannot replace its
 contract.
 
-`AppTab.closeIcon` and `ResizableRegion.handleIcon` replace dormant decorative
+`TabBarItem.closeIcon` and `ResizableRegion.handleIcon` replace dormant decorative
 glyph content only. They must not contain controls or interactive roles. The
 component continues to own the named close button or focusable separator, and
 `wireTabBars()` / `wireResizableRegions()` continue to own transient behavior
@@ -359,10 +360,10 @@ the child's own class (or one of the child's own unclassed internals below
 it), and the child reads context values the parent provides under the
 parent's name. `ResizableRegion` widens its edge extent by the unsafe inset a
 split `SplitView` provides, and a `Skeleton` derives its fill from a solid
-`Badge`'s on-solid color, both in their own stylesheets; an `AppTab` rounds its
+`Badge`'s on-solid color, both in their own stylesheets; an `TabBarItem` rounds its
 outer corners in a segmented `TabBar` and shares a fill-allocated strip from
-`app-tab.css`. An inspector `TabBar` uses the shared 12px rounded rectangle
-radius on its strip; its segmented `AppTab` corners follow that strip's inner
+`tab-bar-item.css`. An inspector `TabBar` uses the shared 12px rounded rectangle
+radius on its strip; its segmented `TabBarItem` corners follow that strip's inner
 curve, while an ordinary segmented strip keeps its pill ends and smaller
 interior corners. A `PopupMenu` sizes
 its trigger and applies a group's `menuInset` in its own stylesheet, and an
@@ -382,8 +383,7 @@ colocated component source:
   appear only in an ancestor compound or inside `:has()` / `:not()`; the
   styled compound is the stylesheet's own class.
 - **Owned Web Awesome tags.** Kerf components are named by class, never by a
-  `wa-*` tag they render. A tag another component renders (`wa-dropdown`,
-  `wa-select`, `wa-option`, a `PopupMenu`'s trigger `wa-button`) — as the
+  `wa-*` tag they render. A tag another component renders — as the
   subject, or as an ancestor whose internals the rule reaches — must be scoped
   to that component by its class or excluded with `:not()`. A direct child
   that cannot be the owner's internal
@@ -493,7 +493,7 @@ mode; the detail reads as secondary through its smaller, regular-weight type, an
 only the neutral tone quiets it, to `--kui-color-neutral-on-quiet`. Its five built-in
 tones can be rethemed globally with
 `--kui-state-banner-{tone}-{background|border|foreground}`. Toolbar control,
-segmented-control, app-tab, and tab-bar colors likewise use their public
+segmented-control, tab-bar-item, and tab-bar colors likewise use their public
 `--kui-*-*` variables. `SegmentedControl` exposes surface, border, foreground,
 hover, and selected-state variables, so rounded, pill, and toolbar presentations
 remain opinionated but locally overridable. Its label color switches with the
@@ -565,7 +565,10 @@ multiple actions, put sibling buttons in a static ContentItem (or use
 For an interactive ContentItem, `wireContentItems` activates the card on Enter
 or Space only when the key event originated from the card itself. A nested
 native control, including one inside a custom element's shadow root, keeps its
-own keyboard activation.
+own keyboard activation. The activation click carries the key's Shift, Ctrl,
+and Cmd state (Space uses the state at press), so one delegated click handler
+implements range and toggle selection for pointer and keyboard alike.
+Alt-modified keys are left to the platform.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
@@ -587,12 +590,12 @@ Use `sizing="grow"` on an expanded search group in a wrapping zone: it grows fro
 row at 480px container width or less. The basis remains its intrinsic minimum
 in a wider, non-stacked Toolbar, so sibling trailing groups can share the
 row. The collapsed search stays icon-sized. The group owns the open and
-close motion: its flex size animates while a collapsible `TokenSearchField`
+close motion: its flex size animates while a collapsible `SearchField`
 inside fills it on every frame, laid out at least basis-wide and clipped by the
 group, so a query never wraps or leaves an empty band mid-transition. At 480px
 container width or less, and under reduced motion, it opens in one frame.
 A plain collapsible search group (no `sizing`) animates its own width the same
-way: the `TokenSearchField` follows the group on every frame and keeps its
+way: the `SearchField` follows the group on every frame and keeps its
 query on one line until the opening ends, so it never shows an empty band or a
 query wrapped in a narrow, still-opening field.
 Use `sizing="fill"` for a group, including a non-search segmented control,
@@ -607,7 +610,7 @@ Use `visibility="yield-to-expanded-sibling"` on trailing groups that should
 leave a 480px-or-narrower toolbar while a sibling trailing group is expanded.
 They return when it collapses or the toolbar widens; leading and center zones
 remain visible.
-Reach for `wa-button` only when you need a Web Awesome feature; a popup menu is a `PopupMenu`, which renders its own
+A group's controls are plain `<button>`s (a standalone `Button` belongs outside a group); a popup menu is a `PopupMenu`, which renders its own
 trigger. By default a group stays on one row: each icon sits beside its label,
 and the enclosing `Toolbar`'s responsive policy relocates whole groups. Set
 `overflow="wrap"` only for independent links that should move as whole actions
@@ -630,7 +633,7 @@ outside painting; the Select keeps its focus outline 3px inside the trigger
 and drops it while the listbox is open. Both settings belong to Select, not an
 application `::part()` override.
 
-Set `menuInset` to configure the dropdown menu surface
+Set `menuInset` to configure the menu surface
 without application `::part(menu)` CSS; the default `standard` keeps each menu's
 own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
 `PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
@@ -650,26 +653,22 @@ group title rather than the farther-in Select option label. Checked submenu
 items keep their checkmark inside the submenu surface with the same check-column
 advance as the top level. Compact mixed controls retain the standard
 item padding, omit an internal separator, and let the raised selected item paint
-over the outer border instead of shrinking to an inset highlight. The Web
-Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
-and the shadow caret determine the width without a fixed host measurement.
-With `popup-menu/register` loaded, PopupMenu and a raw dropdown inside
-`PopupSurface` preserve item navigation made during the Web Awesome show
-animation across its final initial-focus handoff.
+over the outer border instead of shrinking to an inset highlight. The
+PopupMenu trigger sizes to max-content, so icons, localized text, and the caret
+determine the width without a fixed measurement.
 At viewport widths of 480px or less, `PopupMenu` places an open submenu above
 or below its parent menu, choosing the side with room and constraining the
-submenu to the viewport. It never paints over the parent list. The submenu
-remains a native Web Awesome `menu`: the reverse horizontal arrow (ArrowLeft in
-LTR, ArrowRight in RTL) returns focus to its parent item, Escape dismisses the
-menu, and choosing a child dispatches the normal
-`data-action` and `wa-select` events. Wider viewports retain the side cascade.
+submenu to the viewport. It never paints over the parent list. The reverse
+horizontal arrow (ArrowLeft in LTR, ArrowRight in RTL) returns focus to its
+parent item, Escape closes it, and choosing a child dispatches the normal
+`data-action` and `kui-menu-select` events. Wider viewports retain the side cascade.
 The enclosing `Toolbar` owns zone alignment and responsive topology: use
 `centerAlign="stretch"` when the center group should consume its track, and
 choose `responsive="stack"` with `responsiveAt="compact" | "narrow"`,
 `responsive="wrap"` for a heading whose title must stay whole, or
 `responsive="center-priority"` instead of selecting its zone classes from a
 parent stylesheet. No policy clips an action: the trailing zone wraps whole
-groups and its standalone primary `wa-button` onto another row; a stacked
+groups and its standalone primary `Button` onto another row; a stacked
 center zone wraps its groups. The center zone never
 compresses below its content width, so when the leading identity, center, and
 trailing zones share a row that is too narrow, the leading title is what gives
@@ -743,7 +742,7 @@ overrides load later in the cascade or set scoped `--kui-*` variables. JavaScrip
 modules are pure except the browser style wrappers and `@kerfjs/ui/select/register`,
 which registers exactly the Web Awesome elements used by `Select`. Eventful
 helpers such as `wireResizableRegions` and `wireTabBars` attach listeners only
-when called and return disposers. `wireTokenSearchFields` goes one step further:
+when called and return disposers. `wireSearchFields` goes one step further:
 by default it also owns the collapsible field's transient expand/collapse/focus
 (activate to reveal and focus, Escape or empty blur to collapse), holding that
 state in a signal it exposes on the returned handle. An app reads that signal in
@@ -758,7 +757,7 @@ renders in a microtask in that same click task, so the click's render and the
 collapse share one style recalculation and layout. A click that stops
 propagating before the window, or a press without a click, collapses in the
 next task instead.
-`TokenSearchField.trailingAction` supplies an icon, accessible `label`, delegated
+`SearchField.trailingAction` supplies an icon, accessible `label`, delegated
 `action`, and optional `id`; the field renders a 24px wide button that fills its
 34px line slot (32px in `toolbar-group`), including the hit target, disabled
 state, hover, focus ring, and the clear button's radius in each presentation.
@@ -781,7 +780,7 @@ entrypoint only re-exports the folder modules, and the CSS entrypoint only
 imports their owner stylesheets. A shared public name is not permission to put
 several component implementations or visual contracts back into one file.
 
-`wireTokenSearchFields` is a deliberate exception, not the rule for `wire…`
+`wireSearchFields` is a deliberate exception, not the rule for `wire…`
 helpers. Its collapse behavior was _rich and error-prone_ — reveal, focus
 transfer, Escape, empty-blur collapse, focus return — the kind of transient chrome
 apps kept reimplementing inconsistently, so the helper owns it. Everywhere else the
@@ -804,7 +803,7 @@ the only shrinking, horizontally scrolling region; `leading`, `trailing`, and
 trailing action belongs immediately after the final tab and use `end` for a
 separate action pinned to the far edge. Applications own the action content,
 but must not restyle TabBar descendants to recreate that allocation.
-When a leading AppTab is pinned, the leading scroll divider appears at that
+When a leading TabBarItem is pinned, the leading scroll divider appears at that
 tab's trailing edge while peer tabs scroll beneath it, including in RTL.
 With `snapTabs`, `wireTabBars` measures the pinned tab and settles peers at
 whole-tab starts after scroll and selection changes, reserving end room so the