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

package/ai/components/radio-group.md

@@ -24,6 +24,7 @@ Choose exactly one of a few options that should stay visible with room for a lab
 - [Radio](./wa-radio.md) (prefer-over)
 - [Select](./select.md) (nearest) — Use Select for a long list.
 - [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips for wrapping pill choices.
+- [CheckboxGroup](./checkbox-group.md) (nearest) — Use CheckboxGroup when people may choose several.
 
 ## Imports
 
@@ -62,7 +63,7 @@ No wiring helper.
 
 Margin: none · border: none · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- The label and hint sit on the text column (1px + 8px); the choices sit on the 8px control column, 12px apart.
+- The label and hint sit on the text column (1px + 8px); each choice's 20px circle (18px compact) sits on the group's inline-start edge, where a Checkbox draws its box, 8px (7px) before its label; choices stack 8px apart (--kui-space-xs), the same 28px pitch as Checkboxes in a List gap="xs", and a choice hint aligns with its label text.
 
 ## Accessibility
 
@@ -77,12 +78,12 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-radio-group`, `kui-radio-group__label`, `kui-radio-group__choices`, `kui-radio-group__choice`, `kui-radio-group__row`, `kui-radio-group__control`, `kui-radio-group__input`, `kui-radio-group__circle`, `kui-radio-group__choice-label`, `kui-radio-group__choice-hint`, `kui-radio-group__hint`, `kui-radio-group__error` on an element you write; render `RadioGroup` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-quiet`, `--kui-layout-item-padding`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-neutral-border-normal`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-quiet`, `--kui-layout-item-padding`, `--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: [Radio Group](./wa-radio-group.md), [Radio](./wa-radio.md), [Select](./select.md), [ChoiceChips](./choice-chips.md).
+- Components: [Radio Group](./wa-radio-group.md), [Radio](./wa-radio.md), [Select](./select.md), [ChoiceChips](./choice-chips.md), [CheckboxGroup](./checkbox-group.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=radio-group`.

package/ai/components/split-button.md

@@ -8,7 +8,7 @@ A primary action with an attached options trigger on one loud semantic fill.
 
 ## When to use
 
-Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
+Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a rounded or pill shape, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
 
 - A prominent primary action has a closely related set of options chosen from an attached trigger, such as Drive with a provider menu or Deploy with targets.
 
@@ -37,8 +37,10 @@ Exact prop names and types: [`@kerfjs/ui/split-button`](../public-api-signatures
 
 - brand, neutral, success, warning, or danger tone
 - content width or fill
+- rounded or pill shape
 - busy
 - disabled primary or options
+- focusRingInset: each half's focus ring drawn inside its box for an ancestor that clips overflow
 
 ## Composition
 
@@ -60,6 +62,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 ## Accessibility
 
 - Both halves are native buttons in a group; the options trigger exposes aria-haspopup, aria-expanded, and optional aria-controls, and needs optionsLabel. busy sets aria-busy on the primary.
+- Each half draws the focus ring 1px outside its box; with focusRingInset it is drawn inside, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on every loud fill.
 
 ## Styling boundary
 
@@ -69,7 +72,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-split-button`, `kui-split-button__options`, `kui-split-button__icon`, `kui-split-button__label` on an element you write; render `SplitButton` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-focus-ring`, `--kui-font-weight-semibold`, `--kui-layout-rounded-radius`, `--kui-space-s`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-focus-ring`, `--kui-font-weight-semibold`, `--kui-layout-pill-radius`, `--kui-layout-rounded-radius`, `--kui-space-s`, `--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`).
 

package/ai/components/surface-scaffold.md

@@ -56,6 +56,7 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - core kerfjs/overlay confirm/prompt/form/choice as a bottom sheet styled by @kerfjs/ui/overlay-sheet.css
 - resizable core kerfjs/overlay bottom sheet: the kui-overlay-sheet-resizable class plus wireOverlaySheets adds the resizable DialogSurface sheet grabber
 - header with label text or heading content, headerActions, a close button, and an optional footer; withoutHeader for content that owns its heading and close control
+- accessible description by describedBy: the heading ToolbarText descriptionId or app-owned body summary copy
 - light dismiss (a backdrop press closes; otherwise the panel pulses)
 
 **CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
@@ -87,7 +88,7 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 
 - DialogSurface is a native \<dialog> opened modally (showModal): it is in the top layer, the rest of the page is inert, focus stays inside, and it returns to the opener on close. Focus starts on an autofocus element, otherwise on the panel.
 - Name it with label (also its title text) or labelledBy (the id of a heading, such as a ToolbarText). The close button is named Close (closeLabel) and Escape asks to close; the cancelable kui-request-close event reports source close-button, escape, or backdrop.
-- Name a PopoverDialogSurface with label or labelledBy, and describe it with describedBy (rendered as aria-describedby), usually a title ToolbarText descriptionId.
+- Name a PopoverDialogSurface with label or labelledBy. Describe either surface with describedBy (rendered as aria-describedby on the dialog root), usually the heading ToolbarText descriptionId or app-owned summary copy in the body; rootAttributes accepts only data-\* attributes, so it never sets aria-describedby.
 - A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
 - A resizable bottom sheet's grabber is a focusable horizontal separator ("Resize sheet") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion is skipped under prefers-reduced-motion.
 - Use popup surfaces only for real dropdown menus with named triggers.

package/ai/components/switch.md

@@ -56,7 +56,7 @@ No wiring helper.
 
 Margin: none · border: self · padding: none (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- A 35×20 track (31.5×18 compact) 8px (7px) before its label; the hint aligns with the label text.
+- A 35×20 track (31.5×18 compact) 8px (7px) before its label; the hint sits directly under the label, on its text column, like a Checkbox hint.
 
 ## Accessibility
 

package/ai/components/text.md

@@ -64,6 +64,8 @@ Margin: self · border: self · padding: self (layout role: structure). `self` m
 - Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin by default, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.
 - controlMargins adds the shared control gutter outside selected physical edges without changing border or padding; avoid duplicating a parent inset. Spans retain inline display and native inline margin behavior.
 
+Inset-free (no margin, border, or padding) when `flush` or `variant="span"`: the form to use inside a parent that expects inset-free content (`KUI-L204`).
+
 ## Accessibility
 
 - Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.

package/ai/components/wa-checkbox-group.md

@@ -6,18 +6,18 @@
 
 ## When to use
 
-Ecosystem checkbox group; use Kerf Checkbox rows or ChoiceChips.
+Ecosystem checkbox group; use Kerf CheckboxGroup or ChoiceChips.
 
 - Labels and validates a related set of checkboxes.
 
 **Not when:**
 
-- Do not use it in Kerf UI; use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
+- Do not use it in Kerf UI; use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
 
 **Alternatives:**
 
-- [Checkbox](./checkbox.md) (prefer-kerf) — Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
-- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use Checkbox rows in a List, or ChoiceChips multiple for wrapping pills.
+- [CheckboxGroup](./checkbox-group.md) (prefer-kerf) — Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
+- [ChoiceChips](./choice-chips.md) (prefer-kerf) — Use CheckboxGroup for a labeled set of options, or ChoiceChips multiple for wrapping pills.
 
 ## Imports
 
@@ -57,6 +57,6 @@ Theme it only through `@kerfjs/ui/webawesome.css` and cataloged tokens. Do not r
 
 ## Related
 
-- Components: [Checkbox](./wa-checkbox.md), [Checkbox](./checkbox.md), [ChoiceChips](./choice-chips.md).
+- Components: [Checkbox](./wa-checkbox.md), [CheckboxGroup](./checkbox-group.md), [ChoiceChips](./choice-chips.md).
 - Docs: [`docs/webawesome-theme.md#coverage`](../../docs/webawesome-theme.md#coverage).
 - UX catalog route: `?component=wa-checkbox-group`.

package/ai/components/workbench-dialog.md

@@ -75,7 +75,7 @@ Margin: parent · border: self · padding: child (layout role: structure). `self
 ## Accessibility
 
 - It is a native modal \<dialog> named by label: the page is inert, focus stays inside, Escape asks to close, and focus returns to the opener on close.
-- The title is a level-2 heading; the close control is named Close (closeLabel) and stays the outermost trailing control. An open overlay rail takes focus, keeps Tab inside it, and closes on Escape before the dialog does.
+- The title is a level-2 heading, and its description (id \<id>-description) is the dialog's accessible description unless describedBy names other content; the close control is named Close (closeLabel) and stays the outermost trailing control. An open overlay rail takes focus, keeps Tab inside it, and closes on Escape before the dialog does.
 
 ## Styling boundary
 

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.105` and `kerfjs@5.0.0-beta.105`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.107` and `kerfjs@5.0.0-beta.107`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -602,7 +602,11 @@ type PopupMenuProps = PopupMenuTrigger & {
     /** Trigger icon, typically a `LucideIcon`, before any visible text. */
     icon?: KerfUiContent;
     items: readonly PopupMenuEntry[];
-    /** Where the menu opens relative to its trigger. Defaults to `bottom-start`. */
+    /**
+     * Where the menu opens relative to its trigger, or to its anchor point for
+     * a `context` menu (`top-start` opens above the point). Defaults to
+     * `bottom-start`.
+     */
     placement?: PopupMenuPlacement;
     /** Show the disclosure caret after the trigger content. Defaults to true. */
     caret?: boolean;
@@ -616,13 +620,19 @@ type PopupMenuProps = PopupMenuTrigger & {
 type PopupMenuElement = HTMLElement;
 /**
  * Open a PopupMenu at viewport pointer coordinates. A `context` menu rendered
- * without `anchor` moves its invisible anchor there (a menu rendered with
- * `anchor` opens with `openPopupMenu` instead). A button-triggered menu (such
+ * without `anchor` moves its invisible anchor there and opens at its
+ * `placement` (a menu rendered with `anchor` opens with `openPopupMenu`
+ * instead). A button-triggered menu (such
  * as a `ListActionRow` trailing menu) opens `bottom-start` from the point,
  * like a context menu, for this opening only; its next opening returns to its
- * trigger and placement. Needs the `/register` entry.
+ * trigger and placement. `options.placement` sets the placement at the point
+ * for this opening instead (`top-start` sits above it, say), for either kind
+ * of menu; flipping, shifting, and the height cap still apply. Needs the
+ * `/register` entry.
  */
-declare function openPopupMenuAt(menu: PopupMenuElement, x: number, y: number): void;
+declare function openPopupMenuAt(menu: PopupMenuElement, x: number, y: number, options?: {
+    placement?: PopupMenuPlacement;
+}): void;
 /**
  * Open a PopupMenu from its trigger, or a context PopupMenu at the `anchor`
  * it was rendered with (or the point a previous `openPopupMenuAt` set).
@@ -664,6 +674,7 @@ type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undef
     'data-divider'?: never;
     'data-inline'?: never;
     'data-width'?: never;
+    'data-wrap'?: never;
     'data-indicator-tone'?: never;
     'data-toggle'?: never;
 }>;
@@ -685,6 +696,12 @@ interface ListHeaderBaseProps {
     inline?: boolean;
     /** Fill the available row or shrink-wrap while retaining normal header geometry. */
     width?: 'fill' | 'content';
+    /**
+     * Wrap a long label onto further lines instead of truncating it to one
+     * ellipsized line. Default false. Use it where the whole label must stay
+     * readable in a narrow column, such as a specimen or form-section heading.
+     */
+    wrap?: boolean;
     indicatorTone?: 'neutral' | 'accent' | 'pop' | 'danger';
     /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
     placeholder?: boolean;
@@ -745,7 +762,7 @@ type ListHeaderIndicatorProps = {
     status?: SafeHtml | undefined;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, size, headingLevel, count, countLabel, badge, status, density, divider, inline, width, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, size, headingLevel, count, countLabel, badge, status, density, divider, inline, width, wrap, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, slot, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -4123,8 +4140,8 @@ export { type SearchFieldCollapsibleOptions, type SearchFieldEdit, type SearchFi
 ## `kerfjs/actions`
 
 ```ts
-import { A as AttrSpec } from './attrSelector-Cmu2ZoGO.js';
-import { D as DelegateOptions } from './delegate-CL9VTZFb.js';
+import { A as AttrSpec } from './attr-Cmu2ZoGO.js';
+import { D as DelegateOptions } from './delegate--CrfgYtC.js';
 
 /**
  * `kerfjs/actions` — the delegated action-table helper.
@@ -4678,6 +4695,12 @@ type DialogSurfaceProps = DialogSurfaceName & DialogSurfaceOptions;
 interface DialogSurfaceOptions {
     /** The dialog's id, for `openDialog(document.getElementById(id))`. */
     id?: string;
+    /**
+     * Id of the element whose text is the dialog's accessible description,
+     * such as the `heading` ToolbarText's `descriptionId` or app-owned summary
+     * copy in the body; rendered as `aria-describedby` on the `<dialog>`.
+     */
+    describedBy?: string;
     /** The body content. */
     children: KerfUiContent;
     /**
@@ -4792,7 +4815,7 @@ interface DialogSurfaceOptions {
  * floating header and footer measurement, the bottom sheet's keyboard
  * clearance and grabber, and re-render resilience while open.
  */
-declare function DialogSurface({ id, label, labelledBy, heading, headerActions, footer, withoutHeader, lightDismiss, closeLabel, children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, minHeight, resizable, enterMotion, exitMotion, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ id, label, labelledBy, describedBy, heading, headerActions, footer, withoutHeader, lightDismiss, closeLabel, children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, minHeight, resizable, enterMotion, exitMotion, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 /** Where a PopoverDialogSurface appears: the top layer, or in flow. */
 type PopoverDialogSurfacePresentation = 'overlay' | 'embedded';
 /** Application `data-*` metadata on the surface root. */
@@ -4937,6 +4960,12 @@ interface ListDetailDialogProps {
     id: string;
     /** The dialog's accessible name. */
     label: string;
+    /**
+     * Id of the element whose text is the dialog's accessible description,
+     * such as app-owned summary copy. The detail's `description` describes the
+     * selection, not the dialog, so it is not wired automatically.
+     */
+    describedBy?: string;
     list: ListDetailDialogList;
     detail: ListDetailDialogDetail;
     /**
@@ -4979,7 +5008,7 @@ interface ListDetailDialogProps {
  * stack's back control dispatches `nav-back`). Built from `DialogSurface`,
  * `SplitView`, and `Pane`.
  */
-declare function ListDetailDialog({ id, label, list, detail, compact, detailActive, backLabel, closeLabel, lightDismiss, size, preferredWidth, height, maxHeight, viewportGutter, rootAttributes, className, slot, }: ListDetailDialogProps): kerfjs.SafeHtml;
+declare function ListDetailDialog({ id, label, describedBy, list, detail, compact, detailActive, backLabel, closeLabel, lightDismiss, size, preferredWidth, height, maxHeight, viewportGutter, rootAttributes, className, slot, }: ListDetailDialogProps): kerfjs.SafeHtml;
 
 export { ListDetailDialog, type ListDetailDialogDetail, type ListDetailDialogList, type ListDetailDialogProps, type ListDetailDialogRootAttributes };
 ```
@@ -5023,8 +5052,17 @@ interface WorkbenchDialogProps {
     label: string;
     /** The dialog's primary title: an xl heading in the work area's toolbar. */
     title: string;
-    /** A short supporting line under the title. */
+    /**
+     * A short supporting line under the title. It is the dialog's accessible
+     * description (`aria-describedby` to its `<id>-description`) unless
+     * `describedBy` names other content.
+     */
     description?: string;
+    /**
+     * Id of the element whose text is the dialog's accessible description, in
+     * place of `description`, such as app-owned summary copy in `main`.
+     */
+    describedBy?: string;
     /** Groups after the title in the work area's toolbar. */
     leading?: KerfUiContent;
     /** Header controls before the close control, such as a `ToolbarControlGroup`. */
@@ -5081,7 +5119,7 @@ interface WorkbenchDialogProps {
  * Escape or a press outside it before the dialog sees the Escape. Built from
  * `DialogSurface` and `Workbench`.
  */
-declare function WorkbenchDialog({ id, label, title, description, leading, actions, main, mainFooter, mainBottomToolbar, leftRail, rightRail, bottomDrawer, compact, closeLabel, lightDismiss, size, preferredWidth, height, maxHeight, viewportGutter, mainMinSize, rootAttributes, className, slot, }: WorkbenchDialogProps): kerfjs.SafeHtml;
+declare function WorkbenchDialog({ id, label, title, description, describedBy, leading, actions, main, mainFooter, mainBottomToolbar, leftRail, rightRail, bottomDrawer, compact, closeLabel, lightDismiss, size, preferredWidth, height, maxHeight, viewportGutter, mainMinSize, rootAttributes, className, slot, }: WorkbenchDialogProps): kerfjs.SafeHtml;
 
 export { WorkbenchDialog, type WorkbenchDialogProps, type WorkbenchDialogRootAttributes };
 ```
@@ -5603,10 +5641,12 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 /**
  * The Disclosure's surface: `plain` (default) on the surrounding surface,
- * `framed` with the standard neutral border, or `sunken` on the lowered,
- * textured work surface with a border.
+ * `framed` with the standard neutral border, `sunken` on the lowered,
+ * textured work surface with a border, or `embedded` inside owner chrome such
+ * as a `ContentItem`: no margin, border, or padding of its own and a compact
+ * summary row, so the arrow sits on the owner's content inset.
  */
-type DisclosureAppearance = 'plain' | 'framed' | 'sunken';
+type DisclosureAppearance = 'plain' | 'framed' | 'sunken' | 'embedded';
 /**
  * Application `data-*` identity on the `<details>` root, such as `data-key`;
  * the Disclosure's own configuration attributes stay protected.
@@ -5631,6 +5671,11 @@ interface DisclosureProps {
      * where opening one closes the others (the native `<details name>`).
      */
     name?: string;
+    /**
+     * Surface treatment; defaults to `plain`. Use `embedded` only inside chrome
+     * that already owns the content-item inset, such as a `ContentItem`, and
+     * give it content that draws no inset of its own (`Text flush`).
+     */
     appearance?: DisclosureAppearance;
     /**
      * A `data-action` value on the `<details>` root, for a delegated listener of
@@ -5648,7 +5693,9 @@ interface DisclosureProps {
  * Content a person shows and hides under a summary row: a native `<details>`
  * with a `<summary>` that carries a `DisclosureArrow` and the title, on the
  * shared content-item geometry (8px inline margin, a 1px border, 8px
- * padding, the rounded radius). Keyboard and screen-reader behavior is the
+ * padding, the rounded radius). `appearance="embedded"` drops that geometry
+ * for a Disclosure inside owner chrome (a `ContentItem`) that already insets
+ * it. Keyboard and screen-reader behavior is the
  * platform's: the summary is a button that Enter and Space toggle, and it
  * reports its expanded state. Disclosures sharing a `name` form an accordion.
  */
@@ -5805,22 +5852,47 @@ interface ColorPickerProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-/** The labels, accessible names, and maximum of each channel field per mode. */
+/**
+ * The labels, accessible names, maximum, and spoken unit of each channel per
+ * mode; the mode's sliders and fields both follow it.
+ */
 declare const COLOR_PICKER_CHANNELS: Record<ColorPickerMode, readonly {
     short: string;
     name: string;
     max: number;
+    unit: '' | '%' | '°';
 }[]>;
 /** The rounded channel values a mode shows for an HSV color. */
 declare function colorPickerChannels(mode: ColorPickerMode, hsv: Hsva): number[];
+/** One channel slider's attributes; see {@link colorPickerSlider}. */
+interface ColorPickerSliderState {
+    max: number;
+    value: string;
+    label: string;
+    valueText: string;
+    style: string;
+}
+/**
+ * The attributes of one channel slider for a mode's exact channel values:
+ * its range, value, accessible name and spoken value, and an inline style
+ * with the track gradient of the colors that channel produces while the
+ * others hold (the full rainbow for the HSL and HSB hue) and the color under
+ * the thumb.
+ * `undefined` for a slot the mode does not use.
+ */
+declare function colorPickerSlider(mode: ColorPickerMode, index: number, values: readonly number[]): ColorPickerSliderState | undefined;
 /** The area's spoken value. */
 declare function colorPickerAreaText(hsv: Hsva): string;
 /** The CSS custom properties that place the thumbs and paint the tracks. */
 declare function colorPickerStyle(hsv: Hsva): string;
 /**
- * A full color picker panel: a saturation and brightness area, a hue slider,
- * an optional opacity slider on a checkerboard, a color-model menu (RGB, HSL,
- * HSB, Grayscale) with its channel fields, a hex field (8 digits below full
+ * A full color picker panel: a saturation and brightness area; a slider for
+ * each channel of the color model (red, green, and blue; hue, saturation, and
+ * lightness or brightness; or one gray level), each track painting the colors
+ * that channel produces while the others hold (the hue track the full
+ * rainbow); an optional 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, an optional screen sampler (EyeDropper), and
  * optional preset and sample swatches. The controlled `value` renders it;
  * wire `wireColorPickers` from `@kerfjs/ui/wire-color-pickers` to make it
@@ -5830,7 +5902,7 @@ declare function colorPickerStyle(hsv: Hsva): string;
  */
 declare function ColorPicker({ id, label, value, mode, alpha, name, form, eyedropper, presets, samples, addSampleAction, disabled, className, rootAttributes, slot, }: ColorPickerProps): kerfjs.SafeHtml;
 
-export { COLOR_PICKER_CHANNELS, COLOR_PICKER_SWATCH_ACTION, ColorPicker, type ColorPickerMode, type ColorPickerProps, type ColorPickerRootAttributes, type ColorPickerSamples, colorPickerAreaText, colorPickerChannels, colorPickerStyle };
+export { COLOR_PICKER_CHANNELS, COLOR_PICKER_SWATCH_ACTION, ColorPicker, type ColorPickerMode, type ColorPickerProps, type ColorPickerRootAttributes, type ColorPickerSamples, type ColorPickerSliderState, colorPickerAreaText, colorPickerChannels, colorPickerSlider, colorPickerStyle };
 ```
 
 ## `@kerfjs/ui/color-field`
@@ -6137,6 +6209,81 @@ declare function Checkbox({ label, checked, indeterminate, name, value, hint, er
 export { Checkbox, type CheckboxProps, type CheckboxRootAttributes, type CheckboxSize };
 ```
 
+## `@kerfjs/ui/checkbox-group`
+
+```ts
+import * as kerfjs from 'kerfjs';
+
+/** `default` is a 20px box beside 16px text; `compact` 18px and 14px. */
+type CheckboxGroupSize = 'default' | 'compact';
+/** `vertical` stacks the choices; `horizontal` lines them up and wraps. */
+type CheckboxGroupOrientation = 'vertical' | 'horizontal';
+/** Application `data-*` metadata; the CheckboxGroup's own markers stay protected. */
+type CheckboxGroupRootAttributes = Readonly<Record<`data-${string}`, string | undefined>>;
+interface CheckboxGroupChoice<Value extends string = string> {
+    value: Value;
+    /** Visible label; it is also the checkbox's accessible name. */
+    label: string;
+    /** Supporting text under this choice's label, also its description. */
+    hint?: string;
+    disabled?: boolean;
+}
+/**
+ * A group is named by a visible `label` (its legend), by `ariaLabel`, or by
+ * `labelledBy`, the id of a visible heading elsewhere that names it.
+ */
+type CheckboxGroupName = {
+    label: string;
+    ariaLabel?: never;
+    labelledBy?: never;
+} | {
+    label?: never;
+    ariaLabel: string;
+    labelledBy?: never;
+} | {
+    label?: never;
+    ariaLabel?: never;
+    labelledBy: string;
+};
+interface CheckboxGroupOptions<Value extends string = string> {
+    /** Native input `name`: the form field every checked value submits under. */
+    name: string;
+    choices: readonly CheckboxGroupChoice<Value>[];
+    /** The checked values. Omit for none. */
+    value?: readonly NoInfer<Value>[];
+    /** Supporting text below the choices, also the group's description. */
+    hint?: string;
+    /** A validation message: shown in the danger color and marking it invalid. */
+    error?: string;
+    size?: CheckboxGroupSize;
+    orientation?: CheckboxGroupOrientation;
+    /** Disable the whole group. */
+    disabled?: boolean;
+    /** Delegated `data-action` on every checkbox; listen for `change`. */
+    action?: string;
+    /** Associate the checkboxes with a form outside their ancestor chain. */
+    form?: string;
+    /** The fieldset's id. */
+    id?: string;
+    className?: string;
+    /** Safe `data-*` metadata (a `data-key`). */
+    rootAttributes?: CheckboxGroupRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+type CheckboxGroupProps<Value extends string = string> = CheckboxGroupName & CheckboxGroupOptions<Value>;
+/**
+ * Any number of related options among a few visible choices: a native
+ * fieldset of `Checkbox`es with the group label above and hint and error text
+ * below, laid out like a `RadioGroup` so stacked checkboxes and radios share
+ * one control column and one 28px pitch. Every checked value submits under
+ * `name`.
+ */
+declare function CheckboxGroup<Value extends string>({ label, ariaLabel, labelledBy, name, choices, value, hint, error, size, orientation, disabled, action, form, id, className, rootAttributes, slot, }: CheckboxGroupProps<Value>): kerfjs.SafeHtml;
+
+export { CheckboxGroup, type CheckboxGroupChoice, type CheckboxGroupName, type CheckboxGroupOptions, type CheckboxGroupOrientation, type CheckboxGroupProps, type CheckboxGroupRootAttributes, type CheckboxGroupSize };
+```
+
 ## `@kerfjs/ui/radio-group`
 
 ```ts
@@ -6450,6 +6597,12 @@ interface ButtonOptions {
     size?: ButtonSize;
     /** Corner shape (default `rounded`). */
     shape?: ButtonShape;
+    /**
+     * Span the full width of the parent instead of sizing to the label, as on
+     * `SplitButton`. The label stays centered and ellipsizes when it no longer
+     * fits.
+     */
+    fill?: boolean;
     /**
      * Make it a toggle: `aria-pressed` reports the state, and a pressed look is
      * drawn on top of the tone and emphasis. The application owns the state and
@@ -6475,6 +6628,12 @@ interface ButtonOptions {
     target?: '_self' | '_blank' | '_parent' | '_top';
     /** Delegated `data-action` the application handles. */
     action?: string;
+    /**
+     * Keep the button's focus ring inside its box when an ancestor clips
+     * overflow. The inset ring is two-tone, a surface-colored line inside the
+     * ring color, so it stays visible on a loud fill of the ring's own hue.
+     */
+    focusRingInset?: boolean;
     /**
      * A count, short text, or `true` for a text-free dot over the button's
      * top-trailing corner, such as how many items a filter hides. It stays out
@@ -6503,12 +6662,13 @@ interface ButtonOptions {
  * A standalone action button: a native `<button>` (or a link with `href`)
  * in one of three tones and three emphases, at the 44px control height or
  * compact, with a label or as an icon-only square, rounded or pill-shaped,
- * and optionally a `pressed` toggle. Inside a
+ * sized to its label or filling its parent's width, and optionally a
+ * `pressed` toggle. Inside a
  * `ToolbarControlGroup`, use a plain `<button>`, which the group styles; use
  * Button for a dialog footer, a form, or a standalone action beside other
  * content.
  */
-declare function Button({ children, tone, emphasis, size, shape, pressed, icon, loading, disabled, type, name, value, form, href, target, action, badge, badgeLabel, badgeTone, ariaLabel, title, id, className, rootAttributes, slot, }: ButtonProps): kerfjs.SafeHtml;
+declare function Button({ children, tone, emphasis, size, shape, fill, pressed, icon, loading, disabled, type, name, value, form, href, target, action, focusRingInset, badge, badgeLabel, badgeTone, ariaLabel, title, id, className, rootAttributes, slot, }: ButtonProps): kerfjs.SafeHtml;
 
 export { Button, type ButtonContent, type ButtonEmphasis, type ButtonLabel, type ButtonOptions, type ButtonProps, type ButtonRootAttributes, type ButtonShape, type ButtonSize, type ButtonTone, type ButtonType };
 ```
@@ -6520,11 +6680,15 @@ import { SafeHtml } from 'kerfjs';
 
 /** The loud fill the whole split button paints. */
 type SplitButtonTone = 'brand' | 'neutral' | 'success' | 'warning' | 'danger';
+/** Corner shape: the shared `rounded` control radius (default) or a full `pill`, as on `Button`. */
+type SplitButtonShape = 'rounded' | 'pill';
 type SplitButtonRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-tone'?: never;
     'data-fill'?: never;
     'data-busy'?: never;
+    'data-shape'?: never;
+    'data-focus-ring-inset'?: never;
 }>;
 interface SplitButtonProps {
     /** Visible primary label. */
@@ -6549,6 +6713,14 @@ interface SplitButtonProps {
     tone?: SplitButtonTone;
     /** Span the full width of the parent instead of sizing to the label. */
     fill?: boolean;
+    /** Corner shape (default `rounded`); `pill` fully rounds both outer ends. */
+    shape?: SplitButtonShape;
+    /**
+     * Keep each half's focus ring inside its box when an ancestor clips
+     * overflow. The inset ring is two-tone, a surface-colored line inside the
+     * ring color, so it stays visible on every loud fill.
+     */
+    focusRingInset?: boolean;
     /** Show work in progress: a spinner replaces the icon and the primary is `aria-busy`. */
     busy?: boolean;
     /** Disable the primary half. */
@@ -6570,9 +6742,9 @@ interface SplitButtonProps {
  * technology directly; the application opens its own menu from the options
  * action and owns the running state.
  */
-declare function SplitButton({ label, action, icon, accessibleLabel, optionsLabel, optionsAction, optionsExpanded, optionsPopup, optionsControls, tone, fill, busy, disabled, optionsDisabled, title, className, rootAttributes, slot, }: SplitButtonProps): SafeHtml;
+declare function SplitButton({ label, action, icon, accessibleLabel, optionsLabel, optionsAction, optionsExpanded, optionsPopup, optionsControls, tone, fill, shape, focusRingInset, busy, disabled, optionsDisabled, title, className, rootAttributes, slot, }: SplitButtonProps): SafeHtml;
 
-export { SplitButton, type SplitButtonProps, type SplitButtonTone };
+export { SplitButton, type SplitButtonProps, type SplitButtonShape, type SplitButtonTone };
 ```
 
 ## `@kerfjs/ui/file-picker`