@kerfjs/ui 5.0.0-beta.106 → 5.0.0-beta.108

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.106` and `kerfjs@5.0.0-beta.106`. 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.108` and `kerfjs@5.0.0-beta.108`. 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`
 
@@ -172,6 +172,11 @@ type ToolbarPosition = 'header' | 'footer';
 /** Control-band density: `default` (60px with 44px groups) or `compact`. */
 type ToolbarDensity = 'default' | 'compact';
 interface ToolbarProps {
+    /**
+     * The toolbar's id, so app code can address it: name it as a scrolling
+     * List's chrome in `wireScrollDividers({ targets })`, or find it in tests.
+     */
+    id?: string;
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
@@ -236,7 +241,7 @@ interface ToolbarProps {
  * toolbar) forwards, so the app configures that toolbar instead of styling it.
  */
 type ToolbarConfig = Pick<ToolbarProps, 'density' | 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
-declare function Toolbar({ leading, center, trailing, label, position, density, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ id, leading, center, trailing, label, position, density, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
 export { Sides, Toolbar, type ToolbarConfig, type ToolbarDensity, type ToolbarPosition, type ToolbarProps };
 ```
@@ -347,7 +352,7 @@ type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 type ToolbarControlGroupOverflow = 'visible' | 'scroll' | 'wrap';
 type ToolbarControlGroupExpandedOverflow = 'clip' | 'visible';
 type ToolbarControlGroupMenuInset = 'standard' | 'compact' | 'list-zero';
-type ToolbarControlGroupVisibility = 'always' | 'compact-only' | 'hide-collapsed-tiny' | 'yield-to-expanded-sibling';
+type ToolbarControlGroupVisibility = 'always' | 'compact-only' | 'hide-collapsed-tiny' | 'yield-to-expanded-sibling' | 'yield-to-priority-row';
 type ToolbarControlGroupSizing = 'content' | 'grow' | 'fill';
 type ToolbarControlGroupPlacement = 'start' | 'end';
 interface ToolbarActionLinkProps {
@@ -410,7 +415,13 @@ interface ToolbarControlGroupProps {
     overflow?: ToolbarControlGroupOverflow;
     /** Let app-owned anchored surfaces extend outside an expanded search group. Collapsed searches retain their clipping. */
     expandedOverflow?: ToolbarControlGroupExpandedOverflow;
-    /** Responsive visibility owned by the enclosing Toolbar container. */
+    /**
+     * Responsive visibility owned by the enclosing Toolbar container.
+     * `yield-to-priority-row` hides this trailing group exactly while its
+     * Toolbar's `responsive="trailing-priority"` row is active (an expanded
+     * trailing sibling at the Toolbar's `responsiveAt` width), so the app never
+     * restates that breakpoint with `hideBelow`.
+     */
     visibility?: ToolbarControlGroupVisibility;
     /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
     hideBelow?: CssLength;
@@ -602,7 +613,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 +631,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 +685,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 +707,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 +773,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 };
 ```
@@ -876,6 +904,12 @@ interface ListProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
+    /**
+     * The list's id, so app code can address it: name it as a
+     * `wireScrollDividers` scroller (with a `Toolbar` above it as its chrome),
+     * or find it in tests.
+     */
+    id?: string;
     /**
      * Safe `data-*`, `aria-*`, and structural `role` metadata (a named drop
      * `region`, `aria-busy`); List-owned structural attributes remain
@@ -893,7 +927,7 @@ interface ListProps {
  */
 type ListConfig = Pick<ListProps, 'gap' | 'hAlign' | 'vAlign' | 'dividerSides' | 'textInsets' | 'controlInsets'>;
 /** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
-declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, scrollClearance, frame, maxHeight, minHeight, surface, inset, contentWidth, contentAlign, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
+declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, scrollClearance, frame, maxHeight, minHeight, surface, inset, contentWidth, contentAlign, dividerSides, textInsets, controlInsets, className, id, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListContentWidth, type ListInset, type ListProps, type ListSurface, ListVerticalAlignment, ScrollClearance, Sides, UiGap };
 ```
@@ -3430,10 +3464,12 @@ interface SegmentedControlProps<Value extends string = string> {
     className?: string;
     /** Render as a loading placeholder: every choice keeps its live label or icon, none is selected, and every segment is disabled. */
     placeholder?: boolean;
+    /** Disable the whole control: every segment is disabled and dimmed, the selection stays visible, and the group reports `aria-disabled`. A choice's own `disabled` still disables just that segment. */
+    disabled?: boolean;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, slot, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
+declare function SegmentedControl<Value extends string>({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, disabled, slot, }: SegmentedControlProps<Value>): kerfjs.SafeHtml;
 
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
@@ -4307,6 +4343,19 @@ import './css-values.js';
  * and derives its fill, border, and focus ring from `currentColor`.
  */
 type ChipTone = SemanticTone | 'inherit';
+/** Safe `data-*` identity on a Chip root; Chip-owned attributes are protected. */
+type ChipRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-tone'?: never;
+    'data-appearance'?: never;
+    'data-shape'?: never;
+    'data-size'?: never;
+    'data-disabled'?: never;
+    'data-truncate'?: never;
+    'data-item-id'?: never;
+    'data-link'?: never;
+    'data-action'?: never;
+}>;
 interface ChipCommonProps {
     /** Decorative leading icon, normally an unsized LucideIcon. */
     icon?: SafeHtml;
@@ -4317,6 +4366,11 @@ interface ChipCommonProps {
     disabled?: boolean;
     /** Record identifier available to an application delegated action handler. */
     itemId?: string;
+    /**
+     * Safe `data-*` identity on the chip root (a plain, link, or action chip),
+     * for tests and delegated handlers; use `itemId` for the record id.
+     */
+    rootAttributes?: ChipRootAttributes;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -4392,9 +4446,9 @@ type ChipProps = ChipCommonProps & ChipLabelProps & (({
  * `href` is set, or a native button when `action` is set. The application
  * owns removal, the link destination, and the action handler.
  */
-declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, action, actionLabel, }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, rootAttributes, className, slot, href, download, external, removeAction, removeLabel, action, actionLabel, }: ChipProps): SafeHtml;
 
-export { Chip, type ChipProps, type ChipTone };
+export { Chip, type ChipProps, type ChipRootAttributes, type ChipTone };
 ```
 
 ## `@kerfjs/ui/lucide-icon`
@@ -4678,6 +4732,20 @@ 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;
+    /**
+     * An alert dialog: a confirmation that interrupts the person to report
+     * something urgent or ask before a destructive action ("Delete this
+     * topic?"). Renders `role="alertdialog"` on the `<dialog>`; set
+     * `describedBy` to the element holding the message, and leave
+     * `lightDismiss` off so the person answers it.
+     */
+    alert?: boolean;
     /** The body content. */
     children: KerfUiContent;
     /**
@@ -4792,7 +4860,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, alert, 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 +5005,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 +5053,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 +5097,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 +5164,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 +5686,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 +5716,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 +5738,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 +5897,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 +5947,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`
@@ -6054,6 +6171,12 @@ interface TextFieldOptions {
     showCount?: boolean;
     /** Single-line value kind (default `text`). */
     type?: TextFieldType;
+    /** Native lower bound for `type="number"` (number or numeric string). */
+    min?: number | string;
+    /** Native upper bound for `type="number"` (number or numeric string). */
+    max?: number | string;
+    /** Native number increment (number, numeric string, or `"any"`). */
+    step?: number | string;
     /** A multi-line field: a `<textarea>`. */
     multiline?: boolean;
     /** A multi-line field's height in lines (default 3). */
@@ -6082,7 +6205,7 @@ interface TextFieldOptions {
  * The whole field is one `<label>`, so clicking anywhere on it focuses the
  * input; the input is named by `label` (or `ariaLabel`) directly.
  */
-declare function TextField({ label, ariaLabel, value, name, placeholder, hint, error, size, icon, clearable, clearLabel, maxLength, showCount, type, multiline, rows, maxRows, disabled, readOnly, required, autocomplete, id, className, rootAttributes, slot, }: TextFieldProps): kerfjs.SafeHtml;
+declare function TextField({ label, ariaLabel, value, name, placeholder, hint, error, size, icon, clearable, clearLabel, maxLength, showCount, type, min, max, step, multiline, rows, maxRows, disabled, readOnly, required, autocomplete, id, className, rootAttributes, slot, }: TextFieldProps): kerfjs.SafeHtml;
 
 export { TextField, type TextFieldName, type TextFieldOptions, type TextFieldProps, type TextFieldRootAttributes, type TextFieldSize, type TextFieldType };
 ```
@@ -6137,6 +6260,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
@@ -6409,8 +6607,8 @@ import { BadgeTone } from './badge.js';
 import './css-values.js';
 import './semantic-tone-CdW013KF.js';
 
-/** The color family: `neutral` (default), `brand` for the main action, `danger` for a destructive one. */
-type ButtonTone = 'neutral' | 'brand' | 'danger';
+/** The color family: `neutral` (default), `brand` for the main action, `success` for a positive one, `danger` for a destructive one. */
+type ButtonTone = 'neutral' | 'brand' | 'success' | 'danger';
 /**
  * How loudly it asks: `primary` (default) fills the button, `secondary`
  * outlines it, and `plain` shows only its text until hovered.
@@ -6450,6 +6648,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 +6679,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
@@ -6501,14 +6711,15 @@ 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
+ * in one of four 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 +6731,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 +6764,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 +6793,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`