@kerfjs/ui 4.4.1

package/dist/empty-state.d.ts

@@ -0,0 +1,13 @@
+import { SafeHtml } from 'kerfjs';
+
+interface EmptyStateProps {
+    title: string;
+    detail?: string;
+    icon?: SafeHtml;
+    action?: SafeHtml;
+    busy?: boolean;
+    className?: string;
+}
+declare function EmptyState({ title, detail, icon, action, busy, className }: EmptyStateProps): SafeHtml;
+
+export { EmptyState, type EmptyStateProps };

package/dist/empty-state.js

@@ -0,0 +1,4 @@
+export { EmptyState } from './chunk-WVPYVDXY.js';
+
+
+//# sourceMappingURL=empty-state.js.map

package/dist/empty-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"empty-state.js"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { AppTab, AppTabProps } from './app-tab.js';
+export { DialogHeader, DialogHeaderProps } from './dialog-header.js';
+export { EmptyState, EmptyStateProps } from './empty-state.js';
+export { LoadingSpinner, LoadingSpinnerProps } from './loading-spinner.js';
+export { LucideIcon, LucideIconProps, LucideNode } from './lucide-icon.js';
+export { MenuHeader, MenuHeaderProps } from './menu-header.js';
+export { MenuItem, MenuItemProps } from './menu-item.js';
+export { PageHeader, PageHeaderProps } from './page-header.js';
+export { ResizableRegion, ResizableRegionAxis, ResizableRegionEdge, ResizableRegionProps, clampRegionSize, resizeRegionFromPointer } from './resizable-region.js';
+export { SegmentedControl, SegmentedControlAppearance, SegmentedControlChoice, SegmentedControlLayout, SegmentedControlProps, SegmentedControlShape, SegmentedControlSize } from './segmented-control.js';
+export { Select, SelectChoice, SelectProps } from './select.js';
+export { StateBanner, StateBannerProps, StateBannerTone } from './state-banner.js';
+export { TabBar, TabBarProps } from './tab-bar.js';
+export { Toolbar, ToolbarProps } from './toolbar.js';
+export { ToolbarControlGroup, ToolbarControlGroupProps } from './toolbar-control-group.js';
+export { ToolbarText, ToolbarTextProps, ToolbarTextSize } from './toolbar-text.js';
+export { ValueTable, ValueTableProps } from './value-table.js';
+export { ResizeCommit, WireResizableRegionsOptions, wireResizableRegions } from './wire-resizable-regions.js';
+export { TabDropPosition, TabReorder, TabReorderSource, WireTabBarsOptions, reorderTabs, wireTabBars } from './wire-tab-bars.js';
+import 'kerfjs';
+import 'lucide';

package/dist/index.js

@@ -0,0 +1,21 @@
+export { ToolbarText } from './chunk-GY5WH7TO.js';
+export { Toolbar } from './chunk-DAFFDO33.js';
+export { ValueTable } from './chunk-VKH2JLDZ.js';
+export { wireResizableRegions } from './chunk-4HHCYSGT.js';
+export { reorderTabs, wireTabBars } from './chunk-MQIZAD4A.js';
+export { PageHeader } from './chunk-2PES33HS.js';
+export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-3O7ZEUW2.js';
+export { SegmentedControl } from './chunk-TRNBHPNW.js';
+export { Select } from './chunk-NHXX4JI5.js';
+export { StateBanner } from './chunk-VHW5YNIB.js';
+export { TabBar } from './chunk-MBR3TYNL.js';
+export { ToolbarControlGroup } from './chunk-MFKMHK5W.js';
+export { AppTab } from './chunk-T5XNMVOI.js';
+export { DialogHeader } from './chunk-723YNJBH.js';
+export { EmptyState } from './chunk-WVPYVDXY.js';
+export { LoadingSpinner } from './chunk-55DATV3A.js';
+export { LucideIcon } from './chunk-W2FK7ZNY.js';
+export { MenuHeader } from './chunk-OPCJRCYO.js';
+export { MenuItem } from './chunk-WY4CAEPG.js';
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/loading-spinner.d.ts

@@ -0,0 +1,10 @@
+import * as kerfjs from 'kerfjs';
+
+interface LoadingSpinnerProps {
+    className?: string;
+    label?: string;
+}
+/** Stable viewBox-centered progress ring based on svg-spinners' MIT-licensed 180-ring. */
+declare function LoadingSpinner({ className, label }: LoadingSpinnerProps): kerfjs.SafeHtml;
+
+export { LoadingSpinner, type LoadingSpinnerProps };

package/dist/loading-spinner.js

@@ -0,0 +1,3 @@
+export { LoadingSpinner } from './chunk-55DATV3A.js';
+
+//# sourceMappingURL=loading-spinner.js.map

package/dist/loading-spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"loading-spinner.js"}

package/dist/lucide-icon.d.ts

@@ -0,0 +1,14 @@
+import * as kerfjs from 'kerfjs';
+import { IconNode } from 'lucide';
+
+type LucideNode = IconNode;
+interface LucideIconProps {
+    icon: LucideNode;
+    name: string;
+    className?: string;
+    label?: string;
+}
+/** Render a Lucide-compatible icon node without copying icon SVG strings. */
+declare function LucideIcon({ icon, name, className, label }: LucideIconProps): kerfjs.SafeHtml;
+
+export { LucideIcon, type LucideIconProps, type LucideNode };

package/dist/lucide-icon.js

@@ -0,0 +1,3 @@
+export { LucideIcon } from './chunk-W2FK7ZNY.js';
+
+//# sourceMappingURL=lucide-icon.js.map

package/dist/lucide-icon.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"lucide-icon.js"}

package/dist/menu-header.d.ts

@@ -0,0 +1,15 @@
+import { SafeHtml } from 'kerfjs';
+
+interface MenuHeaderProps {
+    label: string;
+    action?: string;
+    actionLabel?: string;
+    actionIcon?: SafeHtml;
+    actionDisabled?: boolean;
+    disabledReason?: string;
+    expanded?: boolean;
+    toggle?: boolean;
+}
+declare function MenuHeader({ label, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle }: MenuHeaderProps): SafeHtml;
+
+export { MenuHeader, type MenuHeaderProps };

package/dist/menu-header.js

@@ -0,0 +1,3 @@
+export { MenuHeader } from './chunk-OPCJRCYO.js';
+
+//# sourceMappingURL=menu-header.js.map

package/dist/menu-header.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"menu-header.js"}

package/dist/menu-item.d.ts

@@ -0,0 +1,22 @@
+import { SafeHtml } from 'kerfjs';
+
+interface MenuItemProps {
+    label: string | SafeHtml;
+    icon?: SafeHtml;
+    trailing?: SafeHtml;
+    selected?: boolean;
+    action: string;
+    itemId?: string;
+    className?: string;
+    style?: string;
+    pressed?: boolean;
+    accessibleLabel?: string;
+    title?: string;
+    multiline?: boolean;
+    state?: string;
+    disabled?: boolean;
+    tabIndex?: number;
+}
+declare function MenuItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex }: MenuItemProps): SafeHtml;
+
+export { MenuItem, type MenuItemProps };

package/dist/menu-item.js

@@ -0,0 +1,3 @@
+export { MenuItem } from './chunk-WY4CAEPG.js';
+
+//# sourceMappingURL=menu-item.js.map

package/dist/menu-item.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"menu-item.js"}

package/dist/page-header.d.ts

@@ -0,0 +1,9 @@
+import { SafeHtml } from 'kerfjs';
+
+interface PageHeaderProps {
+    title: string | SafeHtml;
+    action?: SafeHtml;
+}
+declare function PageHeader({ title, action }: PageHeaderProps): SafeHtml;
+
+export { PageHeader, type PageHeaderProps };

package/dist/page-header.js

@@ -0,0 +1,3 @@
+export { PageHeader } from './chunk-2PES33HS.js';
+
+//# sourceMappingURL=page-header.js.map

package/dist/page-header.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"page-header.js"}

package/dist/resizable-region.d.ts

@@ -0,0 +1,21 @@
+import { SafeHtml } from 'kerfjs';
+
+type ResizableRegionAxis = 'horizontal' | 'vertical';
+type ResizableRegionEdge = 'start' | 'end';
+interface ResizableRegionProps {
+    id: string;
+    label: string;
+    size: number;
+    min: number;
+    max: number;
+    axis?: ResizableRegionAxis;
+    edge?: ResizableRegionEdge;
+    collapsed?: boolean;
+    transitioning?: boolean;
+    children: SafeHtml | SafeHtml[];
+}
+declare const clampRegionSize: (size: number, min: number, max: number) => number;
+declare const resizeRegionFromPointer: (startSize: number, delta: number, edge: ResizableRegionEdge) => number;
+declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, children }: ResizableRegionProps): SafeHtml;
+
+export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionEdge, type ResizableRegionProps, clampRegionSize, resizeRegionFromPointer };

package/dist/resizable-region.js

@@ -0,0 +1,3 @@
+export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-3O7ZEUW2.js';
+
+//# sourceMappingURL=resizable-region.js.map

package/dist/resizable-region.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"resizable-region.js"}

package/dist/segmented-control.d.ts

@@ -0,0 +1,28 @@
+import { SafeHtml } from 'kerfjs';
+
+type SegmentedControlAppearance = 'filled' | 'outlined' | 'toolbar';
+type SegmentedControlShape = 'rounded' | 'pill';
+type SegmentedControlSize = 'small' | 'default';
+type SegmentedControlLayout = 'content' | 'equal';
+interface SegmentedControlChoice {
+    value: string;
+    label: string;
+    content?: SafeHtml;
+    title?: string;
+    disabled?: boolean;
+}
+interface SegmentedControlProps {
+    id: string;
+    label: string;
+    value: string;
+    choices: readonly SegmentedControlChoice[];
+    action?: string;
+    appearance?: SegmentedControlAppearance;
+    shape?: SegmentedControlShape;
+    size?: SegmentedControlSize;
+    layout?: SegmentedControlLayout;
+    className?: string;
+}
+declare function SegmentedControl({ id, label, value, choices, action, appearance, shape, size, layout, className, }: SegmentedControlProps): SafeHtml;
+
+export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };

package/dist/segmented-control.js

@@ -0,0 +1,3 @@
+export { SegmentedControl } from './chunk-TRNBHPNW.js';
+
+//# sourceMappingURL=segmented-control.js.map

package/dist/segmented-control.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"segmented-control.js"}

package/dist/select-register.d.ts

@@ -0,0 +1,4 @@
+/** Marker export for tests and tooling; importing this module performs registration. */
+declare const selectElementsRegistered = true;
+
+export { selectElementsRegistered };

package/dist/select-register.js

@@ -0,0 +1,10 @@
+import '@awesome.me/webawesome/dist/components/divider/divider.js';
+import '@awesome.me/webawesome/dist/components/option/option.js';
+import '@awesome.me/webawesome/dist/components/select/select.js';
+
+// src/select-register.ts
+var selectElementsRegistered = true;
+
+export { selectElementsRegistered };
+
+//# sourceMappingURL=select-register.js.map

package/dist/select-register.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/select-register.ts"],"names":[],"mappings":";;;;;AAKO,IAAM,wBAAA,GAA2B","file":"select-register.js","sourcesContent":["import '@awesome.me/webawesome/dist/components/divider/divider.js';\nimport '@awesome.me/webawesome/dist/components/option/option.js';\nimport '@awesome.me/webawesome/dist/components/select/select.js';\n\n/** Marker export for tests and tooling; importing this module performs registration. */\nexport const selectElementsRegistered = true;\n"]}

package/dist/select.d.ts

@@ -0,0 +1,28 @@
+import { SafeHtml } from 'kerfjs';
+import { LucideNode } from './lucide-icon.js';
+import 'lucide';
+
+interface SelectChoice<Value extends string = string> {
+    value: Value;
+    label: string;
+    icon?: LucideNode;
+    iconName?: string;
+    color?: string;
+    group?: string;
+    separatorBefore?: boolean;
+}
+interface SelectProps<Value extends string = string> {
+    name: string;
+    value: Value;
+    label?: string;
+    ariaLabel?: string;
+    choices: readonly SelectChoice<Value>[];
+    className?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    fitMenu?: boolean;
+    renderSelected?: (choice: SelectChoice<Value>) => SafeHtml;
+}
+declare function Select<Value extends string>({ name, value, label, ariaLabel, choices, className, placeholder, disabled, fitMenu, renderSelected }: SelectProps<Value>): SafeHtml;
+
+export { Select, type SelectChoice, type SelectProps };

package/dist/select.js

@@ -0,0 +1,4 @@
+export { Select } from './chunk-NHXX4JI5.js';
+
+
+//# sourceMappingURL=select.js.map

package/dist/select.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"select.js"}

package/dist/state-banner.d.ts

@@ -0,0 +1,15 @@
+import { SafeHtml } from 'kerfjs';
+
+type StateBannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
+interface StateBannerProps {
+    title: string;
+    detail?: string;
+    icon?: SafeHtml;
+    action?: SafeHtml;
+    tone?: StateBannerTone;
+    urgency?: 'status' | 'alert';
+    className?: string;
+}
+declare function StateBanner({ title, detail, icon, action, tone, urgency, className }: StateBannerProps): SafeHtml;
+
+export { StateBanner, type StateBannerProps, type StateBannerTone };

package/dist/state-banner.js

@@ -0,0 +1,3 @@
+export { StateBanner } from './chunk-VHW5YNIB.js';
+
+//# sourceMappingURL=state-banner.js.map

package/dist/state-banner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"state-banner.js"}

package/dist/tab-bar.d.ts

@@ -0,0 +1,14 @@
+import { SafeHtml } from 'kerfjs';
+
+interface TabBarProps {
+    id: string;
+    label: string;
+    children: SafeHtml | readonly SafeHtml[];
+    leading?: SafeHtml;
+    trailing?: SafeHtml;
+    className?: string;
+}
+/** Render a controlled tab strip. The application owns selection, order, and persistence. */
+declare function TabBar({ id, label, children, leading, trailing, className }: TabBarProps): SafeHtml;
+
+export { TabBar, type TabBarProps };

package/dist/tab-bar.js

@@ -0,0 +1,3 @@
+export { TabBar } from './chunk-MBR3TYNL.js';
+
+//# sourceMappingURL=tab-bar.js.map

package/dist/tab-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"tab-bar.js"}

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

@@ -0,0 +1,15 @@
+import { SafeHtml } from 'kerfjs';
+
+interface ToolbarControlGroupProps {
+    children: SafeHtml | SafeHtml[];
+    label?: string;
+    className?: string;
+    expanded?: boolean;
+    single?: boolean;
+    appearance?: 'contained' | 'borderless';
+    tone?: 'default' | 'dark';
+    buttonAppearance?: 'plain' | 'push';
+}
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance }: ToolbarControlGroupProps): SafeHtml;
+
+export { ToolbarControlGroup, type ToolbarControlGroupProps };

package/dist/toolbar-control-group.js

@@ -0,0 +1,3 @@
+export { ToolbarControlGroup } from './chunk-MFKMHK5W.js';
+
+//# sourceMappingURL=toolbar-control-group.js.map

package/dist/toolbar-control-group.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"toolbar-control-group.js"}

package/dist/toolbar-text.d.ts

@@ -0,0 +1,11 @@
+import * as kerfjs from 'kerfjs';
+
+type ToolbarTextSize = 'large' | 'default' | 'small';
+interface ToolbarTextProps {
+    text: string;
+    size?: ToolbarTextSize;
+    className?: string;
+}
+declare function ToolbarText({ text, size, className }: ToolbarTextProps): kerfjs.SafeHtml;
+
+export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };

package/dist/toolbar-text.js

@@ -0,0 +1,3 @@
+export { ToolbarText } from './chunk-GY5WH7TO.js';
+
+//# sourceMappingURL=toolbar-text.js.map

package/dist/toolbar-text.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"toolbar-text.js"}

package/dist/toolbar.d.ts

@@ -0,0 +1,13 @@
+import { SafeHtml } from 'kerfjs';
+
+interface ToolbarProps {
+    leading?: SafeHtml;
+    center?: SafeHtml;
+    trailing?: SafeHtml;
+    label?: string;
+    divider?: boolean;
+    className?: string;
+}
+declare function Toolbar({ leading, center, trailing, label, divider, className }: ToolbarProps): SafeHtml;
+
+export { Toolbar, type ToolbarProps };

package/dist/toolbar.js

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

package/dist/toolbar.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"toolbar.js"}

package/dist/value-table.d.ts

@@ -0,0 +1,10 @@
+import { SafeHtml } from 'kerfjs';
+
+interface ValueTableProps {
+    label: string;
+    className?: string;
+    children: SafeHtml | SafeHtml[];
+}
+declare function ValueTable({ label, className, children }: ValueTableProps): SafeHtml;
+
+export { ValueTable, type ValueTableProps };

package/dist/value-table.js

@@ -0,0 +1,3 @@
+export { ValueTable } from './chunk-VKH2JLDZ.js';
+
+//# sourceMappingURL=value-table.js.map

package/dist/value-table.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"value-table.js"}

package/dist/wire-resizable-regions.d.ts

@@ -0,0 +1,15 @@
+interface ResizeCommit {
+    id: string;
+    size: number;
+    source: 'keyboard' | 'pointer';
+}
+interface WireResizableRegionsOptions {
+    step?: number;
+    largeStep?: number;
+    onPreview?: (change: ResizeCommit) => void;
+    onCommit: (change: ResizeCommit) => void;
+}
+/** Wire pointer and separator-keyboard behavior for every ResizableRegion below root. */
+declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit }: WireResizableRegionsOptions): () => void;
+
+export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };

package/dist/wire-resizable-regions.js

@@ -0,0 +1,4 @@
+export { wireResizableRegions } from './chunk-4HHCYSGT.js';
+
+
+//# sourceMappingURL=wire-resizable-regions.js.map

package/dist/wire-resizable-regions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-resizable-regions.js"}

package/dist/wire-tab-bars.d.ts

@@ -0,0 +1,17 @@
+type TabReorderSource = 'pointer' | 'keyboard';
+type TabDropPosition = 'before' | 'after';
+interface TabReorder {
+    barId: string;
+    sourceId: string;
+    targetId: string;
+    position: TabDropPosition;
+    source: TabReorderSource;
+}
+interface WireTabBarsOptions {
+    onReorder: (change: TabReorder) => void;
+}
+declare function reorderTabs<T>(items: readonly T[], getId: (item: T) => string, sourceId: string, targetId: string, position: TabDropPosition): T[];
+/** Wire reordering and keyboard navigation while leaving controlled state in the application. */
+declare function wireTabBars(root: HTMLElement | Document, { onReorder }: WireTabBarsOptions): () => void;
+
+export { type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };

package/dist/wire-tab-bars.js

@@ -0,0 +1,3 @@
+export { reorderTabs, wireTabBars } from './chunk-MQIZAD4A.js';
+
+//# sourceMappingURL=wire-tab-bars.js.map

package/dist/wire-tab-bars.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-tab-bars.js"}

package/docs/accessibility.md

@@ -0,0 +1,56 @@
+# Accessibility and keyboard contracts
+
+These are normative contracts for package components and consuming applications.
+
+## Shared rules
+
+- All controls have accessible names and visible `:focus-visible` treatment.
+- Decorative `LucideIcon` output is `aria-hidden`; pass `label` only when the SVG itself conveys meaning.
+- `MenuItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. It deliberately does not emit `role="menuitem"` in isolation—a true ARIA menu must own arrow, Home/End, Escape, and focus behavior as one widget.
+- `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
+- `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure.
+- `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
+- `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone.
+
+## ResizableRegion
+
+The handle exposes separator role, orientation, name, minimum, maximum, and current values. `wireResizableRegions()` adds:
+
+- the axis arrow keys in 16 px steps by default;
+- Shift+Arrow in 64 px steps;
+- Home and End for minimum and maximum;
+- primary-pointer drag with clamping;
+- preview callbacks while dragging and one commit callback on release.
+
+The application owns persistence and collapsed/expanded policy. Keep the last expanded size outside the component and restore it when reopening.
+
+## Tabs
+
+`AppTab` renders one controlled tab. `TabBar` supplies the containing tab list,
+fixed leading/trailing regions, and a horizontally scrollable strip.
+`wireTabBars()` adds Left/Right wrapping, Home/End, Delete/Backspace close
+activation, same-bar pointer reordering, `Alt+Shift+ArrowLeft/ArrowRight`
+reordering, focus restoration, scroll-into-view, and pointer-proximity
+autoscroll at either horizontal edge. Edge autoscroll is direct manipulation,
+stops on drop/drag end/disposal, and does not change keyboard behavior. It
+returns a disposer.
+
+The application owns the ordered tab array, selection, panels, close policy,
+routing, and persistence. On `onReorder`, synchronously render the reported
+order so the helper can restore focus to the moved tab. Pair tabs with
+`tabpanel` elements and keep exactly one selected tab at `tabindex="0"`.
+
+## SegmentedControl
+
+`SegmentedControl` labels its native-button group and projects the controlled
+selection through both `aria-pressed` and `data-selected`. Every enabled choice
+stays in sequential Tab order, matching Hot Sheet 2's compact view and inspector
+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. Use tabs—not a segmented control—when choices switch page regions that
+need `tab`/`tabpanel` semantics.
+
+## Verification matrix
+
+For each changed component, inspect default, hover, focus, disabled, selected/pressed, busy/error, long-content, wide, narrow, light, dark, increased-contrast, reduced-motion, keyboard-only, and 200%-zoom states where applicable. DOM order must match reading and focus order, with no clipping or unreachable action.

package/docs/apple-hig.md

@@ -0,0 +1,40 @@
+# Translating Apple HIG principles to Kerf UI
+
+Native Apple applications should use native platform controls and follow the Human Interface Guidelines directly. `@kerfjs/ui` is a web package: it translates the HIG's interaction, hierarchy, writing, accessibility, and feedback principles into semantic HTML and CSS. It does not imitate macOS chrome or materials.
+
+## Foundations
+
+- Accessibility is behavior: every workflow is keyboard-operable; focus is visible; DOM and reading order agree; controls have accessible names; decorative icons are hidden.
+- Use adaptive semantic colors. Every custom role needs usable light, dark, and increased-contrast behavior. Never rely on color alone.
+- Use the system UI font stack and allow browser zoom through 200%. Avoid thin weights and hard minimums that clip enlarged text.
+- Group with space and alignment before adding borders. Keep essential content in the leading reading path and secondary detail in progressive disclosure.
+- Use one icon family and one metaphor per action. Directional icons may mirror in RTL; checkmarks, logos, and real-world objects do not.
+- Motion is brief, causal, and optional. Honor reduced-motion and reduced-transparency preferences; repeating indicators stop moving under reduced motion.
+- Writing is concise, specific, and action-led. Labels describe the result, not implementation details.
+
+## Interaction
+
+- Prefer native buttons, links, headings, lists, and form controls so browser keyboard behavior comes for free.
+- Use 28 px targets by preference, 20 px as the absolute package floor, and 44 px where the layout allows.
+- Do not move focus after background updates. After a destructive foreground action, move it predictably to the nearest logical survivor.
+- Distinguish selection, focus, pressed, disabled, pending, success, and failure in both semantics and presentation.
+- Use `role="status"` for passive updates. Reserve `role="alert"` for failures requiring attention.
+- Do not timer-dismiss essential feedback. A transient notice that disappears must not be the only record of an important outcome.
+- Place controls near the content they affect. Avoid modal presentation when an inline or popover interaction preserves context safely.
+- Use segmented controls for a small set of mutually exclusive modes. Keep every choice named and keyboard reachable, make the selected mode visible without relying on color alone, and choose rounded or pill geometry to fit the surrounding toolbar or content surface.
+
+## Layout and appearance
+
+- Browser surfaces are HIG-shaped, not HIG-skinned: no fake traffic lights, title bars, SF Symbols, or CSS imitation of Liquid Glass.
+- Logical CSS properties support language direction. Truncation and wrapping decisions are explicit; identifiers retain useful leading and trailing context.
+- At constrained widths, remove or move secondary information before shrinking controls or text below usable sizes.
+- Test light, dark, increased contrast, reduced motion, keyboard-only use, 200% zoom, and narrow/wide layouts.
+
+## AI experiences
+
+- Identify AI-generated or AI-modified content when that fact affects trust or review.
+- State meaningful uncertainty and consequences in plain language.
+- Keep people in control with reviewable changes and adjacent Edit, Undo, Retry, Reject, or Report actions.
+- Do not use anthropomorphic animation or decoration to imply confidence, agency, or authorship.
+
+These rules are a portable implementation guide, not a replacement for current Apple documentation when building a native client.