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

package/dist/surface-scaffold.d.ts

@@ -82,6 +82,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;
     /**
@@ -196,7 +210,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. */

package/dist/surface-scaffold.js

@@ -1,4 +1,4 @@
-export { DialogSurface, PopoverDialogSurface, PopupSurface } from './chunk-TAHR457X.js';
+export { DialogSurface, PopoverDialogSurface, PopupSurface } from './chunk-6CDILXF4.js';
 export { closeDialog, openDialog } from './chunk-ATGAJVZ6.js';
 
 

package/dist/text-field.d.ts

@@ -50,6 +50,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). */
@@ -78,6 +84,6 @@ 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 };

package/dist/text-field.js

@@ -1,4 +1,4 @@
-export { TextField } from './chunk-WU57BYYM.js';
+export { TextField } from './chunk-YVZCKXR3.js';
 
 
 

package/dist/toolbar-control-group.d.ts

@@ -19,7 +19,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 {
@@ -82,7 +82,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;

package/dist/toolbar-control-group.js

@@ -1,4 +1,4 @@
-export { ToolbarActionLink, ToolbarControlGroup } from './chunk-2PXZBFEC.js';
+export { ToolbarActionLink, ToolbarControlGroup } from './chunk-5J6Z4BWY.js';
 
 
 

package/dist/toolbar.d.ts

@@ -9,6 +9,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;
@@ -73,6 +78,6 @@ 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 };

package/dist/toolbar.js

@@ -1,3 +1,3 @@
-export { Toolbar } from './chunk-CMLPFIC5.js';
+export { Toolbar } from './chunk-ZN7KUMPY.js';
 
 //# sourceMappingURL=toolbar.js.map

package/dist/wire-catalog.js

@@ -1,4 +1,4 @@
-import { wireWorkbench } from './chunk-QLA25V2K.js';
+import { wireWorkbench } from './chunk-WPNIKZMJ.js';
 
 import { wireScrollDividers } from './chunk-OZ6X76G5.js';
 import { loadUxReviewProject } from './chunk-6C6DLP3W.js';

package/dist/wire-color-fields.js

@@ -1,5 +1,5 @@
-import { wireColorPickers } from './chunk-ACUKTVS3.js';
-import { ColorPicker } from './chunk-EKBMUXFV.js';
+import { wireColorPickers } from './chunk-XWNXGFX3.js';
+import { ColorPicker } from './chunk-3Z7N2NAZ.js';
 
 
 import { openAnchoredSurface } from './chunk-3WYREXW4.js';

package/dist/wire-color-pickers.d.ts

@@ -19,9 +19,10 @@ interface WireColorPickersOptions {
 }
 /**
  * Make every ColorPicker under `root` interactive. The area takes pointer
- * drags and the arrow keys (Shift for steps of 10%); the hue and opacity
- * sliders are native ranges; channel, hex, and opacity fields commit on Enter
- * or blur; the model menu switches the channel fields; the screen sampler
+ * drags and the arrow keys (Shift for steps of 10%); the model's channel
+ * sliders and the opacity slider are native ranges, each changing only its
+ * own channel; channel, hex, and opacity fields commit on Enter or blur; the
+ * model menu switches the channel sliders and fields; the screen sampler
  * opens the EyeDropper where the browser has it; preset and sample swatches
  * apply their color. Each change updates the picker at once, dispatches a
  * bubbling `kui-color-input` (or `kui-color-change` when committed) event

package/dist/wire-color-pickers.js

@@ -1,4 +1,4 @@
-export { wireColorPickers } from './chunk-ACUKTVS3.js';
+export { wireColorPickers } from './chunk-XWNXGFX3.js';
 
 
 

package/dist/wire-comboboxes.js

@@ -1,4 +1,4 @@
-export { wireComboboxes } from './chunk-GCAK23PU.js';
+export { wireComboboxes } from './chunk-MVKHSAKE.js';
 
 
 //# sourceMappingURL=wire-comboboxes.js.map

package/dist/wire-workbench.js

@@ -1,4 +1,4 @@
-export { wireWorkbench } from './chunk-QLA25V2K.js';
+export { wireWorkbench } from './chunk-WPNIKZMJ.js';
 
 
 

package/dist/workbench-dialog.d.ts

@@ -34,8 +34,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`. */
@@ -92,6 +101,6 @@ 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 };

package/dist/workbench-dialog.js

@@ -1,7 +1,7 @@
-import { DialogSurface } from './chunk-TAHR457X.js';
+import { DialogSurface } from './chunk-6CDILXF4.js';
 export { closeDialog, openDialog } from './chunk-ATGAJVZ6.js';
 
-import { Workbench } from './chunk-DDSCVEO5.js';
+import { Workbench } from './chunk-CPSGUGAY.js';
 
 
 
@@ -10,7 +10,7 @@ import { ToolbarText } from './chunk-EKHDLBRP.js';
 
 
 
-import { ToolbarControlGroup } from './chunk-2PXZBFEC.js';
+import { ToolbarControlGroup } from './chunk-5J6Z4BWY.js';
 
 
 
@@ -33,6 +33,7 @@ function WorkbenchDialog({
   label,
   title,
   description,
+  describedBy,
   leading,
   actions,
   main,
@@ -59,6 +60,7 @@ function WorkbenchDialog({
     {
       id,
       label,
+      describedBy: describedBy ?? (description === void 0 ? void 0 : `${id}-description`),
       withoutHeader: true,
       lightDismiss,
       closeLabel,
@@ -88,6 +90,7 @@ function WorkbenchDialog({
               {
                 text: title,
                 description,
+                descriptionId: description === void 0 ? void 0 : `${id}-description`,
                 size: "xlarge",
                 id: `${id}-title`,
                 headingLevel: 2

package/dist/workbench-dialog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/surfaces/workbench-dialog/workbench-dialog.tsx"],"names":[],"mappings":"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","file":"workbench-dialog.js","sourcesContent":["import { X } from 'lucide';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport type { CssLength } from '../../../shared/styles/css-values.js';\nimport { remify } from '../../../shared/styles/css-values.js';\nimport { ToolbarControlGroup } from '../../actions/toolbar-control-group/toolbar-control-group.js';\nimport { ToolbarText } from '../../actions/toolbar-text/toolbar-text.js';\nimport {\n  Workbench,\n  type WorkbenchMainBottomToolbar,\n  type WorkbenchPanel,\n} from '../../layout/workbench/workbench.js';\nimport { LucideIcon } from '../../media/lucide-icon/lucide-icon.js';\nimport {\n  DialogSurface,\n  type DialogSurfaceHeight,\n  type DialogSurfaceMaxHeight,\n  type DialogSurfaceRootAttributes,\n  type DialogSurfaceSize,\n} from '../surface-scaffold/surface-scaffold.js';\n\n// Open and close it like any DialogSurface, from the same import.\nexport {\n  closeDialog,\n  type DialogCloseSource,\n  type DialogRequestCloseDetail,\n  openDialog,\n} from '../surface-scaffold/surface-scaffold.js';\n\n/**\n * Application `data-*` identity on the dialog root, such as `data-key`; the\n * dialog's own configuration attributes stay protected.\n */\nexport type WorkbenchDialogRootAttributes = DialogSurfaceRootAttributes;\n\nexport interface WorkbenchDialogProps {\n  /**\n   * The dialog's id, for `openDialog(document.getElementById(id))`. The\n   * Workbench inside is `<id>-workbench`, so its rails are\n   * `<id>-workbench-left-rail` and `<id>-workbench-right-rail`.\n   */\n  id: string;\n  /** The dialog's accessible name. */\n  label: string;\n  /** The dialog's primary title: an xl heading in the work area's toolbar. */\n  title: string;\n  /** A short supporting line under the title. */\n  description?: string;\n  /** Groups after the title in the work area's toolbar. */\n  leading?: KerfUiContent;\n  /** Header controls before the close control, such as a `ToolbarControlGroup`. */\n  actions?: KerfUiContent;\n  /** The work area. */\n  main: KerfUiContent;\n  /** Fixed content over the work area's bottom toolbar, such as a status line. */\n  mainFooter?: KerfUiContent;\n  /** The work area's bottom toolbar, usually the dialog's buttons. */\n  mainBottomToolbar?: WorkbenchMainBottomToolbar;\n  /**\n   * Side rails with their own toolbars. On compact devices each presents as\n   * an overlay over the work area; the app starts it collapsed and its\n   * `toolbar.toggle` shows it.\n   */\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  /** A bottom drawer under the work area. */\n  bottomDrawer?: WorkbenchPanel;\n  /**\n   * Fill the screen with the rails as overlays: derive from\n   * `deviceClass().value.compact`.\n   */\n  compact?: boolean;\n  /** The close control's accessible name (default `Close`). */\n  closeLabel?: string;\n  /** Close on a press on the backdrop; otherwise the panel pulses. */\n  lightDismiss?: boolean;\n  /** Roomy preferred width preset (default `large`). */\n  size?: DialogSurfaceSize;\n  /** Roomy preferred width; takes precedence over `size`. */\n  preferredWidth?: CssLength;\n  /** Roomy definite height (default 560px), bounded by the viewport. */\n  height?: DialogSurfaceHeight;\n  /** Roomy height cap in place of a definite height. */\n  maxHeight?: DialogSurfaceMaxHeight;\n  /** Roomy edge clearance from the viewport. */\n  viewportGutter?: CssLength;\n  /** Minimum work-area width beside inline rails, in px (Workbench default 320). */\n  mainMinSize?: number;\n  rootAttributes?: WorkbenchDialogRootAttributes;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/** A rail presents as an overlay in a compact dialog, as the app left it otherwise. */\nfunction compactRail(\n  panel: WorkbenchPanel | undefined,\n  compact: boolean,\n): WorkbenchPanel | undefined {\n  return panel && compact ? { ...panel, presentation: 'overlay' } : panel;\n}\n\n/**\n * A workbench dialog: a modal whose body is a `Workbench`. The work area's\n * toolbar carries the dialog's primary title, its actions, and the close\n * control; side rails keep their own toolbars and run the dialog's full\n * height. On compact devices it fills the screen and its rails become\n * overlays over the work area, shown by their toolbar toggles, so the work\n * area keeps its width. Open it with `openDialog()`; the app owns each\n * rail's `collapsed` state, and `wireWorkbench` closes an overlay rail on\n * Escape or a press outside it before the dialog sees the Escape. Built from\n * `DialogSurface` and `Workbench`.\n */\nexport function WorkbenchDialog({\n  id,\n  label,\n  title,\n  description,\n  leading,\n  actions,\n  main,\n  mainFooter,\n  mainBottomToolbar,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  compact = false,\n  closeLabel = 'Close',\n  lightDismiss = false,\n  size = 'large',\n  preferredWidth,\n  height,\n  maxHeight,\n  viewportGutter,\n  mainMinSize,\n  rootAttributes,\n  className = '',\n  slot,\n}: WorkbenchDialogProps) {\n  return (\n    <DialogSurface\n      id={id}\n      label={label}\n      withoutHeader\n      lightDismiss={lightDismiss}\n      closeLabel={closeLabel}\n      size={size}\n      presentation={compact ? 'fullscreen' : 'modal'}\n      preferredWidth={preferredWidth}\n      height={\n        compact\n          ? undefined\n          : maxHeight === undefined\n            ? (height ?? remify(560))\n            : height\n      }\n      maxHeight={compact ? undefined : maxHeight}\n      viewportGutter={compact ? undefined : viewportGutter}\n      bodyInset=\"none\"\n      bodyLayout=\"fill\"\n      rootAttributes={{\n        ...rootAttributes,\n        'data-dialog-layout': 'workbench',\n      }}\n      className={className}\n      slot={slot}\n    >\n      <Workbench\n        id={`${id}-workbench`}\n        label={label}\n        mainToolbar={{\n          label: title,\n          title: (\n            <ToolbarText\n              text={title}\n              description={description}\n              size=\"xlarge\"\n              id={`${id}-title`}\n              headingLevel={2}\n            />\n          ),\n          leading,\n          trailing: actions,\n          // After any hidden right rail's toggle, so Close stays outermost.\n          end: (\n            <ToolbarControlGroup appearance=\"borderless\" single>\n              <button\n                type=\"button\"\n                aria-label={closeLabel}\n                data-dialog-close=\"\"\n              >\n                <LucideIcon icon={X} name=\"x\" />\n              </button>\n            </ToolbarControlGroup>\n          ),\n        }}\n        main={main}\n        mainFooter={mainFooter}\n        mainBottomToolbar={mainBottomToolbar}\n        leftRail={compactRail(leftRail, compact)}\n        rightRail={compactRail(rightRail, compact)}\n        bottomDrawer={bottomDrawer}\n        mainMinSize={mainMinSize}\n      />\n    </DialogSurface>\n  );\n}\n"]}
+{"version":3,"sources":["../src/components/surfaces/workbench-dialog/workbench-dialog.tsx"],"names":[],"mappings":"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","file":"workbench-dialog.js","sourcesContent":["import { X } from 'lucide';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport type { CssLength } from '../../../shared/styles/css-values.js';\nimport { remify } from '../../../shared/styles/css-values.js';\nimport { ToolbarControlGroup } from '../../actions/toolbar-control-group/toolbar-control-group.js';\nimport { ToolbarText } from '../../actions/toolbar-text/toolbar-text.js';\nimport {\n  Workbench,\n  type WorkbenchMainBottomToolbar,\n  type WorkbenchPanel,\n} from '../../layout/workbench/workbench.js';\nimport { LucideIcon } from '../../media/lucide-icon/lucide-icon.js';\nimport {\n  DialogSurface,\n  type DialogSurfaceHeight,\n  type DialogSurfaceMaxHeight,\n  type DialogSurfaceRootAttributes,\n  type DialogSurfaceSize,\n} from '../surface-scaffold/surface-scaffold.js';\n\n// Open and close it like any DialogSurface, from the same import.\nexport {\n  closeDialog,\n  type DialogCloseSource,\n  type DialogRequestCloseDetail,\n  openDialog,\n} from '../surface-scaffold/surface-scaffold.js';\n\n/**\n * Application `data-*` identity on the dialog root, such as `data-key`; the\n * dialog's own configuration attributes stay protected.\n */\nexport type WorkbenchDialogRootAttributes = DialogSurfaceRootAttributes;\n\nexport interface WorkbenchDialogProps {\n  /**\n   * The dialog's id, for `openDialog(document.getElementById(id))`. The\n   * Workbench inside is `<id>-workbench`, so its rails are\n   * `<id>-workbench-left-rail` and `<id>-workbench-right-rail`.\n   */\n  id: string;\n  /** The dialog's accessible name. */\n  label: string;\n  /** The dialog's primary title: an xl heading in the work area's toolbar. */\n  title: string;\n  /**\n   * A short supporting line under the title. It is the dialog's accessible\n   * description (`aria-describedby` to its `<id>-description`) unless\n   * `describedBy` names other content.\n   */\n  description?: string;\n  /**\n   * Id of the element whose text is the dialog's accessible description, in\n   * place of `description`, such as app-owned summary copy in `main`.\n   */\n  describedBy?: string;\n  /** Groups after the title in the work area's toolbar. */\n  leading?: KerfUiContent;\n  /** Header controls before the close control, such as a `ToolbarControlGroup`. */\n  actions?: KerfUiContent;\n  /** The work area. */\n  main: KerfUiContent;\n  /** Fixed content over the work area's bottom toolbar, such as a status line. */\n  mainFooter?: KerfUiContent;\n  /** The work area's bottom toolbar, usually the dialog's buttons. */\n  mainBottomToolbar?: WorkbenchMainBottomToolbar;\n  /**\n   * Side rails with their own toolbars. On compact devices each presents as\n   * an overlay over the work area; the app starts it collapsed and its\n   * `toolbar.toggle` shows it.\n   */\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  /** A bottom drawer under the work area. */\n  bottomDrawer?: WorkbenchPanel;\n  /**\n   * Fill the screen with the rails as overlays: derive from\n   * `deviceClass().value.compact`.\n   */\n  compact?: boolean;\n  /** The close control's accessible name (default `Close`). */\n  closeLabel?: string;\n  /** Close on a press on the backdrop; otherwise the panel pulses. */\n  lightDismiss?: boolean;\n  /** Roomy preferred width preset (default `large`). */\n  size?: DialogSurfaceSize;\n  /** Roomy preferred width; takes precedence over `size`. */\n  preferredWidth?: CssLength;\n  /** Roomy definite height (default 560px), bounded by the viewport. */\n  height?: DialogSurfaceHeight;\n  /** Roomy height cap in place of a definite height. */\n  maxHeight?: DialogSurfaceMaxHeight;\n  /** Roomy edge clearance from the viewport. */\n  viewportGutter?: CssLength;\n  /** Minimum work-area width beside inline rails, in px (Workbench default 320). */\n  mainMinSize?: number;\n  rootAttributes?: WorkbenchDialogRootAttributes;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/** A rail presents as an overlay in a compact dialog, as the app left it otherwise. */\nfunction compactRail(\n  panel: WorkbenchPanel | undefined,\n  compact: boolean,\n): WorkbenchPanel | undefined {\n  return panel && compact ? { ...panel, presentation: 'overlay' } : panel;\n}\n\n/**\n * A workbench dialog: a modal whose body is a `Workbench`. The work area's\n * toolbar carries the dialog's primary title, its actions, and the close\n * control; side rails keep their own toolbars and run the dialog's full\n * height. On compact devices it fills the screen and its rails become\n * overlays over the work area, shown by their toolbar toggles, so the work\n * area keeps its width. Open it with `openDialog()`; the app owns each\n * rail's `collapsed` state, and `wireWorkbench` closes an overlay rail on\n * Escape or a press outside it before the dialog sees the Escape. Built from\n * `DialogSurface` and `Workbench`.\n */\nexport function WorkbenchDialog({\n  id,\n  label,\n  title,\n  description,\n  describedBy,\n  leading,\n  actions,\n  main,\n  mainFooter,\n  mainBottomToolbar,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  compact = false,\n  closeLabel = 'Close',\n  lightDismiss = false,\n  size = 'large',\n  preferredWidth,\n  height,\n  maxHeight,\n  viewportGutter,\n  mainMinSize,\n  rootAttributes,\n  className = '',\n  slot,\n}: WorkbenchDialogProps) {\n  return (\n    <DialogSurface\n      id={id}\n      label={label}\n      describedBy={\n        describedBy ??\n        (description === undefined ? undefined : `${id}-description`)\n      }\n      withoutHeader\n      lightDismiss={lightDismiss}\n      closeLabel={closeLabel}\n      size={size}\n      presentation={compact ? 'fullscreen' : 'modal'}\n      preferredWidth={preferredWidth}\n      height={\n        compact\n          ? undefined\n          : maxHeight === undefined\n            ? (height ?? remify(560))\n            : height\n      }\n      maxHeight={compact ? undefined : maxHeight}\n      viewportGutter={compact ? undefined : viewportGutter}\n      bodyInset=\"none\"\n      bodyLayout=\"fill\"\n      rootAttributes={{\n        ...rootAttributes,\n        'data-dialog-layout': 'workbench',\n      }}\n      className={className}\n      slot={slot}\n    >\n      <Workbench\n        id={`${id}-workbench`}\n        label={label}\n        mainToolbar={{\n          label: title,\n          title: (\n            <ToolbarText\n              text={title}\n              description={description}\n              descriptionId={\n                description === undefined ? undefined : `${id}-description`\n              }\n              size=\"xlarge\"\n              id={`${id}-title`}\n              headingLevel={2}\n            />\n          ),\n          leading,\n          trailing: actions,\n          // After any hidden right rail's toggle, so Close stays outermost.\n          end: (\n            <ToolbarControlGroup appearance=\"borderless\" single>\n              <button\n                type=\"button\"\n                aria-label={closeLabel}\n                data-dialog-close=\"\"\n              >\n                <LucideIcon icon={X} name=\"x\" />\n              </button>\n            </ToolbarControlGroup>\n          ),\n        }}\n        main={main}\n        mainFooter={mainFooter}\n        mainBottomToolbar={mainBottomToolbar}\n        leftRail={compactRail(leftRail, compact)}\n        rightRail={compactRail(rightRail, compact)}\n        bottomDrawer={bottomDrawer}\n        mainMinSize={mainMinSize}\n      />\n    </DialogSurface>\n  );\n}\n"]}

package/dist/workbench.js

@@ -1,4 +1,4 @@
-export { Workbench } from './chunk-DDSCVEO5.js';
+export { Workbench } from './chunk-CPSGUGAY.js';
 
 
 

package/docs/accessibility.md

@@ -364,7 +364,16 @@ holds an optional icon `ToolbarControlGroup` and a direct extra-large
 `ToolbarText`; controls belong in a trailing `ToolbarControlGroup`. By default
 the title carries no native heading role, so for a **dialog or panel** the
 application connects the title id and optional supporting-copy id to the owning
-host through `aria-labelledby` and `aria-describedby`. For a **page or view**
+host through `aria-labelledby` and `aria-describedby`. `DialogSurface` and
+`PopoverDialogSurface` take these as `labelledBy` and `describedBy`, so the
+supporting line (or app-owned summary copy in the body) is the dialog's
+accessible description; `WorkbenchDialog` wires its title `description`
+automatically (`<id>-description`), and `ListDetailDialog` takes an explicit
+`describedBy`, since its detail description describes the selection, not the
+dialog. A `DialogSurface` that asks before a destructive action ("Delete this
+topic?") sets `alert`, which renders `role="alertdialog"` on the native
+`<dialog>`; pair it with `describedBy` on the message so it is announced, and
+leave `lightDismiss` off so the person answers it. For a **page or view**
 title, pass `headingLevel` (usually `1`) to `ToolbarText`: it then exposes
 `role="heading"` with a matching `aria-level`, giving the view a heading landmark
 so screen-reader heading navigation and "main heading" semantics work — the same
@@ -473,7 +482,9 @@ controls; Enter and Space use native button activation. The application handles
 the supplied `data-action`, reads `data-segment-value`, updates `value`, and
 re-renders. Keep labels unique and meaningful even when `content` shows only an
 icon. The filled track uses the normal neutral text role for readable unselected
-labels in light and dark themes. Use tabs—not a segmented control—when choices switch page regions that
+labels in light and dark themes. A whole-control `disabled` disables every
+native button and marks the group `aria-disabled` while `aria-pressed` still
+reports the current choice. Use tabs—not a segmented control—when choices switch page regions that
 need `tab`/`tabpanel` semantics.
 
 ## ChoiceChips
@@ -533,6 +544,12 @@ its label; the input itself reports `required`. The focus ring is drawn on the
 box around the input (`:focus-within`), 3px with a 1px offset like every Kerf
 control.
 
+For `type="number"`, `min`, `max`, and `step` pass through to the native input.
+Each accepts a number or string; `step="any"` allows arbitrary decimals.
+They are omitted for other input types and `multiline` textareas. Native
+constraint validation (`rangeUnderflow`, `rangeOverflow`, and `stepMismatch`)
+then applies without custom field wiring.
+
 `clearable` adds a native `<button>` named by `clearLabel` (default "Clear")
 after the input. It is hidden while the field is empty, is a normal Tab stop,
 and with `wireTextFields(root)` empties the field, dispatches bubbling `input`
@@ -542,6 +559,36 @@ disabled or read-only field's clear button is disabled. `showCount` (with
 `wireTextFields` keeps current. Compact text grows to 16px on coarse-pointer
 touch screens so focusing a field never zooms the page in iOS.
 
+## Button and SplitButton focus
+
+`Button` and each `SplitButton` half draw the 3px focus ring 1px outside the
+box, against the surrounding surface, because a loud fill can share the ring's
+hue (the brand fill matches the focus color in both schemes). An ancestor that
+clips overflow would crop that ring, so `focusRingInset` draws it inside the
+box instead, the name and meaning `Select` uses. An inset ring alone would
+touch the fill (1.0:1 on brand, at most 2.3:1 on any loud fill), so the inset
+ring is two-tone: the ring color on the outer 3px and a 3px surface-colored
+line inside it. The ring then meets a surface color on both edges and clears
+3:1 against each on every tone (about 4.0:1 in light, 9.9:1 in dark against
+the line), whatever the fill. Forced-colors mode drops the line and keeps the
+system ring.
+
+The line paints the surface the control sits on, not always the base surface:
+a surface that changes the background behind its children publishes the
+surface context (`--kui-color-surface-current`, `-region`, and `-tint`; see
+`docs/component-contract.md`), and the line layers it the same way the page
+does. On a sunken panel, a quiet `ContentItem`, a lowered `FramedList`, a
+raised `List`, popup, or dialog, a highlighted `FramedList` row, a sunken
+Pane, Workbench area, or TabNavigator scene, or a Pane or TabNavigator app
+`background`, the line matches the pixels outside the box, so it reads as a
+cut through the fill instead of a light halo. On a doubly sunken surface the
+brand ring still clears 3:1 against the line (about 3.2:1 in light, 6.9:1 in
+dark). A sunken surface's grain is not part of the line. Translucent glass
+chrome (an overlay header, bar, or bottom toolbar, a dialog's floating
+header) has no single color over scrolling content, so the line paints the
+material over the surface beneath it: exact at rest, an approximation while
+content scrolls under the bar.
+
 ## Checkbox, RadioGroup, and Switch
 
 Each control is a native input inside its `<label>`, positioned invisibly over
@@ -563,6 +610,13 @@ forced-colors mode paints checked state with `Highlight`.
   its `aria-description`; `error` sets `aria-invalid` on the group, `required`
   sets native `required` on each radio plus `aria-required` on the group, and a
   choice's `hint` is that radio's `aria-description`.
+- `CheckboxGroup` is a `<fieldset>` (natively a group) of `Checkbox`es, named
+  by its `<legend>` (`label`), `ariaLabel`, or `labelledBy`. Each checkbox
+  is its own Tab stop and Space toggles it; every checked value submits under
+  `name`. The group's `hint` and `error` form its `aria-description`; `error`
+  sets `aria-invalid` on the group and the danger border on each box, and a
+  choice's `hint` is that checkbox's `aria-description`. `disabled` disables
+  the fieldset and so, natively, every checkbox in it.
 - `Switch` is an `<input type="checkbox" role="switch">`, so assistive
   technology announces on and off; Space toggles it. Its `hint` is its
   `aria-description`. The thumb's slide is skipped when reduced motion is
@@ -747,7 +801,8 @@ the Tab order while collapsed or not inline. `wireWorkbench`, given a panel's
 `collapsed` signal, returns focus stranded in a closing panel to the control that
 opened it, else the restore control, else a control whose `aria-controls` names the
 panel; an open overlay panel takes focus and keeps Tab inside it (the ARIA dialog
-pattern). See [`workbench.md`](workbench.md).
+pattern), whether its own toggle or a persistent toggle outside the Workbench
+opened it, as soon as the panel can take focus. See [`workbench.md`](workbench.md).
 
 ## Chrome material
 

package/docs/anchored-surface.md

@@ -26,7 +26,12 @@ help that leaves focus on its trigger. Escape and an outside press dismiss it;
 `placement` (`bottom` or `top`), `align` (`start` or `end`), `gap`, and
 `viewportMargin` feed the shared `kerfjs/overlay` positioning core: it flips
 vertically when the other side fits, keeps the surface `viewportMargin` (default
-8px) inside the viewport edges, and follows scroll and resize. The surface fits
+8px) inside the viewport edges, and follows scroll, resize, and changes to the
+anchor's own size. Anchor help for a field to the whole field rather than to a
+button inside it: the surface then clears every line of a field that wraps, and
+moves as the field grows (a SearchField's trailing help action opens beside
+`[data-component="search-field"]`, which also keeps typing in the field from
+dismissing it). The surface fits
 its height to the room beside the anchor: when neither side holds it, it opens
 on the roomier side, caps its height to that room, and scrolls its content.
 The room is exposed to the content as `--kui-anchored-surface-available-height`

package/docs/catalog.md

@@ -219,7 +219,32 @@ for a control whose own inline padding contributes about 8px, and
 8px inset (such as a plain `PopupMenu` trigger), so its text lines up with the
 example label past the trigger's own padding and border. Use
 `align="none"` (the default) for a content item or composition that owns its
-geometry.
+geometry. Every form field specimen (TextField, Select, ColorField, TagField,
+Slider, Switch, Checkbox, RadioGroup, CheckboxGroup, ColorSwatches) uses
+`inline-control`, so field borders and label text share one column across the
+catalog; a field that already insets itself by 8px (Combobox) stays at `none`.
+A field is a control a person fills in or picks a value with inline, swatch
+pickers included. A field composition (fields in a `Grid` or a form `List`)
+uses `inline-control` too. A width-sized content specimen — one that fills a
+sized `viewport` or its container rather than its content, such as a
+ProgressBar, a group-title `Text`, or Web Awesome's Progress Bar and Skeleton —
+joins the same column with `inline-control`, so a bar's label lines up with the
+example label and note text. Web Awesome integration specimens follow their
+Kerf counterpart's demo: controls and control compositions (Button, Button
+Group, Dropdown, Dropdown Item, the Tab family, Badge, Tag, Avatar, Progress
+Ring, Toast and Toast Item, the dialog, drawer, popover, and tooltip triggers,
+Animation, and the intersection, mutation, and resize observer compositions)
+use `inline-control`, as the Kerf Button demo does, so the control box sits on
+the 8px column; a specimen led by bare text or a bare glyph (Copy Button,
+Breadcrumb and Breadcrumb Item, Divider, Markdown, Relative Time, Pagination's
+summary, Stepper and Step markers, Spinner, Icon) uses `glyph`, as Kerf's flush
+`Text`, `LoadingSpinner`, and `LucideIcon` demos do, so its text lands on the
+text column instead of flush at the example's edge. A panel — a multi-part picker or
+a drop zone such as ColorPicker and FilePicker, or a framed specimen such as
+Web Awesome's Zoomable Frame — owns its geometry and stays flush at `none`, as
+does an edge-to-edge composition (a toolbar, tab bar, or pane). A sized
+`viewport` takes the alignment offset out of its width, so it still ends at the
+example's inline-end edge.
 
 ```tsx
 import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";

package/docs/color-picker.md

@@ -3,8 +3,15 @@
 `@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 slider for each channel of the color model — red, green, and blue (RGB);
+  hue, saturation, and lightness (HSL); hue, saturation, and brightness
+  (HSB); or one gray level (Grayscale) — each track painting the colors that
+  channel produces while the others hold, except the hue track, which always
+  shows the full-saturation, full-brightness rainbow so a dark or gray color
+  still shows every hue; and, optionally, an opacity slider on a
+  checkerboard;
+- a color-model menu (RGB, HSL, HSB, Grayscale) that switches the channel
+  sliders and fields together;
 - 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.
@@ -28,7 +35,8 @@ const stop = wireColorPickers(root, {
 - `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.
+- `mode`: `rgb` (default), `hsl`, `hsb`, or `gray` — which channel sliders
+  and 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.
@@ -49,7 +57,9 @@ 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.
+- **Channel and opacity sliders** are native range inputs (arrow keys, Page
+  Up and Down, Home and End). Each changes only its own channel; a slider and
+  the field of the same channel always agree.
 - **Fields** commit on Enter or blur; Escape restores the shown value; invalid
   text restores it too.
 - **Swatches** (presets and samples) apply their color.
@@ -59,13 +69,34 @@ Each change dispatches a bubbling `kui-color-input` (live) or
 `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.
+drift: switching models never changes the color, and a channel edit keeps
+every other channel's exact value (an HSL saturation survives lightness
+reaching black or white). The 2D area stays in every model as the primary
+picking surface; the sliders are the precise, per-channel controls.
 
 ## 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.
+Brightness" whose spoken value gives both. Each channel slider is named for
+its channel (Red, Hue, Lightness, Gray Level) and speaks its unit (`210°`,
+`40%`, or a plain 0–255 byte); the opacity slider speaks a percentage. Every
+field is named the same way (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; the sliders form one group 8px apart.
+
+The saturation and brightness area and every slider track draw a 1px inner
+edge halfway between the text color and the color under it, so an area or a
+track as dark as a dark surface (the area's black bottom, a hue at low
+brightness, a faint opacity) or as light as a light one keeps a boundary of at
+least 3:1 against the surface around it. Increased contrast draws the edge in
+the full text color and forced colors in `CanvasText`.
+
+Every thumb draws a two-tone ring: a white border inside a dark outline. The
+white holds at least 3:1 against a dark color and the outline against a light
+one, so a thumb stays findable wherever it sits.
+
+Every track runs in the writing direction, as the native range does: in
+right-to-left text the gradient starts at the right, so the thumb at a
+channel's minimum (or at no opacity) sits over the color it sets.
 
 Use `ColorSwatches` for a small fixed palette.

package/docs/component-contract.md

@@ -65,6 +65,14 @@ diagnostic even when both the wrapper and a rendered root reject that parent.
 When one catalog entry exports another JSX component with different placement,
 `jsxExports` gives that export its own parent contract. The extra export does
 not stand for the entry's root when a parent zone is checked.
+An entry whose own geometry an owner already provides in some configuration
+declares `insetFreeChildren`: `{ prop, equals }` conditions under which its
+direct JSX children must bring no content-item inset (`Disclosure` with
+`appearance="embedded"`). A child brings that inset when its
+`layout.geometry` owns its margin, border, and padding (`self` on all three),
+unless one of its own `insetFreeWhen` conditions holds (`Text` with `flush` or
+`variant="span"`). `ui-composition` reports a child that statically brings the
+inset as `KUI-L204` and names the child's inset-free form when it has one.
 Generated `boundaries.rootClass` prefers the public `kui-<entry-id>` class when
 present, so a sibling export's class cannot become the entry's root class.
 
@@ -411,6 +419,30 @@ a `Pane` overlay header, through `wireScrollDividers`, on its own Pane root).
 A scroll owner reads it only through its own `scrollClearance` prop, or, for an
 overlay-header Pane's content, through its own `headerPresentation`.
 
+The surface context needs no exception either. A component that changes the
+background behind its children publishes, on its own painted element, the
+foundation tokens `--kui-color-surface-current` (the opaque surface beneath:
+a raised `DialogSurface`, popover dialog, `AnchoredSurface`, or `List`
+`surface`, and a sunken Pane's opaque auto chrome, set it and clear both
+layers), `--kui-color-surface-current-region` (a layout region's fill: a sunken
+`Pane`, `Workbench` area, or `TabNavigator` scene, and a `Pane`'s or
+`TabNavigator`'s app `background`), and `--kui-color-surface-current-tint` (a
+content surface's fill: a `SunkenPanel`, a sunken `Disclosure`, a lowered
+`FramedList` and its highlighted row, a quiet, hovered, pressed, or selected
+`ContentItem`, a `TabBar` strip, and translucent glass chrome at rest — a
+`Pane` overlay header, `NavStack` overlay chrome or bottom toolbar, a
+`TabNavigator` overlay bar, and a dialog's floating header; clear chrome
+paints nothing and keeps the inherited context). Interactive rows (`ListItem`,
+`ListActionRow`, `SummaryRow`) are buttons or links themselves, so no control
+nests on their hover or selection fill and they publish nothing. They are undeclared at `:root`
+and a scoped `[data-kui-tint]` resets them. A control that must match what
+lies behind it (the inset focus ring's inner line on `Button` and
+`SplitButton`) layers tint over region over the opaque color, falling back to
+`--kui-color-surface`. Custom properties cannot fold an inherited value into a
+new one, so a content surface inside a sunken region composes exactly while a
+third translucent level keeps only the innermost content tint. An application
+surface that paints its own background sets the same tokens on its own root.
+
 Applications and component packages built on the package follow the same
 rules, and the downstream tools enforce them against the composition catalog
 instead of package source: `kerf-ui-analyze` / `kerf-ui-doctor` report a rule
@@ -609,7 +641,14 @@ preferences remove that entrance animation.
 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.
+remain visible. In a `responsive="trailing-priority"` Toolbar, use
+`visibility="yield-to-priority-row"` instead: the group leaves exactly while
+the expanded trailing control has its own row, from the same container query
+as the row at the Toolbar's `responsiveAt` (832px for `narrow`, 704px for
+`compact`, both inclusive). Do not restate that width with `hideBelow`, which
+hides strictly below its threshold: at exactly 704px the row is active while
+`hideBelow={rem(44)}` still shows the group, which then wraps onto a third
+row.
 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
@@ -624,14 +663,19 @@ compact segment never becomes an oval. An icon-only `Select` joins a group as
 one more segment with its siblings' inset, radius, hover, and focus ring; only a
 lone Select grows the group to its icon-and-caret pill.
 
-Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.
+Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. A listbox (like a PopupMenu menu) shifts only along its trigger's edge, never over the trigger: when neither side fits, it opens on the side with more room and scrolls inside its capped height, so a second press on the trigger still closes it. Keep popup sizing and position repairs out of consumer CSS.
 
 For a rail view heading, use `Select presentation="title"`: its intrinsic
 36px borderless trigger has a bold large label flush with its leading edge and
 a caret beside that label. Set `focusRingInset` when a NavStack or panel clips
 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.
+application `::part()` override. `Button` and `SplitButton` take the same
+`focusRingInset` for a clipping ancestor: the ring moves inside the box (each
+half's, for a SplitButton) with a line inside it in the color of the surface
+it sits on (the surface context), so it stays visible on a loud fill of its
+own hue without a halo on a sunken or tinted surface. Never re-offset their outline from
+application CSS.
 
 Set `menuInset` to configure the menu surface
 without application `::part(menu)` CSS; the default `standard` keeps each menu's