@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

package/dist/collapsible-panel.js

@@ -0,0 +1,136 @@
+import { collapsiblePanelToggleIcon, composedPanelBody, relocatedPanelGroups } from './chunk-TTGIHMDR.js';
+export { collapsiblePanelToggleIcon } from './chunk-TTGIHMDR.js';
+
+
+
+
+
+import { LucideIcon } from './chunk-NP3FSLNX.js';
+
+
+
+
+import { jsx, jsxs, Fragment } from 'kerfjs/jsx-runtime';
+
+var toggleAttributes = (panelId) => ({
+  "data-collapsible-target": panelId,
+  // Keyed, so the morph never reuses a (possibly focused) toggle's button for
+  // another control as the toggle moves between toolbars.
+  "data-key": `${panelId}-toggle`
+});
+function CollapsiblePanelToggle({
+  side,
+  collapsed,
+  action,
+  panelId,
+  label,
+  className = "",
+  slot
+}) {
+  const glyph = collapsiblePanelToggleIcon(side, collapsed);
+  const accessible = label ?? (collapsed ? "Expand" : "Collapse");
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      class: `kui-collapsible-panel__toggle ${className}`.trim(),
+      "data-action": action,
+      "data-collapsible-target": panelId,
+      "aria-expanded": String(!collapsed),
+      "aria-label": accessible,
+      slot,
+      children: /* @__PURE__ */ jsx(LucideIcon, { icon: glyph.icon, name: glyph.name })
+    }
+  );
+}
+function CollapsiblePanel({
+  id,
+  side,
+  collapsed = false,
+  size,
+  label,
+  tabIndex,
+  outlined = false,
+  children,
+  toolbar,
+  header,
+  headerList,
+  headerPlacement,
+  footer,
+  footerList,
+  bottomToolbar,
+  footerPlacement,
+  pane,
+  separator = "auto",
+  collapseMotion = "slide",
+  contentOverflow = "clip",
+  presentation = "inline",
+  restoreControl,
+  restorePosition = side === "left" ? "bottom-start" : "bottom-end",
+  className = ""
+}) {
+  const sizeVar = side === "bottom" ? "--kui-collapsible-panel-height" : "--kui-collapsible-panel-width";
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
+      "aside",
+      {
+        class: `kui-collapsible-panel kui-collapsible-panel--${side} ${className}`.trim(),
+        "data-component": "collapsible-panel",
+        "data-collapsible-panel": id,
+        "data-side": side,
+        "data-collapsed": String(collapsed),
+        "data-outlined": !collapsed && presentation !== "hidden" && outlined ? "true" : void 0,
+        "data-separator": separator,
+        "data-collapse-motion": collapseMotion,
+        "data-content-overflow": contentOverflow,
+        "data-presentation": presentation,
+        "aria-label": label || void 0,
+        "aria-hidden": collapsed || presentation === "hidden" ? "true" : void 0,
+        tabindex: collapsed || presentation === "hidden" ? tabIndex === void 0 ? void 0 : -1 : tabIndex,
+        inert: collapsed,
+        style: size ? `${sizeVar}: ${size}px` : void 0,
+        children: /* @__PURE__ */ jsx("div", { class: "kui-collapsible-panel__content", children: toolbar ? composedPanelBody({
+          toolbar,
+          side,
+          collapsed,
+          attributes: toggleAttributes(id),
+          pane,
+          header,
+          headerList,
+          headerPlacement,
+          footer,
+          footerList,
+          bottomToolbar,
+          footerPlacement,
+          content: children
+        }) : children })
+      }
+    ),
+    collapsed && restoreControl && presentation !== "hidden" && /* @__PURE__ */ jsx(
+      "div",
+      {
+        class: "kui-collapsible-panel__restore",
+        "data-panel-restore": id,
+        "data-position": restorePosition,
+        children: restoreControl
+      }
+    )
+  ] });
+}
+function CollapsiblePanelRelocated({
+  panelId,
+  side,
+  collapsed,
+  toolbar
+}) {
+  return /* @__PURE__ */ jsx(Fragment, { children: relocatedPanelGroups(
+    toolbar,
+    side,
+    collapsed,
+    toggleAttributes(panelId)
+  ) });
+}
+
+export { CollapsiblePanel, CollapsiblePanelRelocated, CollapsiblePanelToggle };
+
+//# sourceMappingURL=collapsible-panel.js.map

package/dist/collapsible-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/layout/collapsible-panel/collapsible-panel.tsx"],"names":[],"mappings":"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","file":"collapsible-panel.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport {\n  collapsiblePanelToggleIcon,\n  composedPanelBody,\n  type PanelBottomToolbar,\n  type PanelChromePlacement,\n  type PanelSide,\n  type PanelToggle,\n  type PanelToggleAttributes,\n  type PanelToolbar,\n  relocatedPanelGroups,\n} from '../../../shared/panels/panel-toolbar.js';\nimport type { ListConfig } from '../../collections/list/list.js';\nimport { LucideIcon } from '../../media/lucide-icon/lucide-icon.js';\nimport type { PaneConfig } from '../pane/pane.js';\nimport type {\n  ResizableRegionCollapseMotion,\n  ResizableRegionContentOverflow,\n  ResizableRegionPresentation,\n  ResizableRegionRestorePosition,\n  ResizableRegionSeparator,\n} from '../resizable-region/resizable-region.js';\n\nexport { collapsiblePanelToggleIcon } from '../../../shared/panels/panel-toolbar.js';\n\n/** Which edge a {@link CollapsiblePanel} docks to. */\nexport type CollapsiblePanelSide = PanelSide;\n\n/** The standard toggle a panel toolbar renders (see {@link CollapsiblePanelToolbar}). */\nexport type CollapsiblePanelToolbarToggle = PanelToggle;\n\n/**\n * A panel's composed top toolbar. Its groups occupy `leading`, `center`, and\n * `trailing` while open; groups marked `relocateOnCollapse` and the standard\n * toggle move to the work-area toolbar through\n * {@link CollapsiblePanelRelocated} while it is collapsed.\n */\nexport type CollapsiblePanelToolbar = PanelToolbar;\nexport type CollapsiblePanelBottomToolbar = PanelBottomToolbar;\nexport type CollapsiblePanelChromePlacement = PanelChromePlacement;\n\n/** A CollapsiblePanel toggle's `wireSidebar` hook. */\nconst toggleAttributes = (panelId: string): PanelToggleAttributes => ({\n  'data-collapsible-target': panelId,\n  // Keyed, so the morph never reuses a (possibly focused) toggle's button for\n  // another control as the toggle moves between toolbars.\n  'data-key': `${panelId}-toggle`,\n});\n\nexport interface CollapsiblePanelToggleProps {\n  /** The panel this toggle controls. */\n  side: CollapsiblePanelSide;\n  /** The panel's current collapsed state (drives the icon direction). */\n  collapsed: boolean;\n  /** `data-action` the button carries so `wireSidebar` can delegate its click. */\n  action: string;\n  /** The panel id the button targets (`data-tab-panel`-style: `data-collapsible-panel`). */\n  panelId?: string;\n  /** Accessible label; defaults to \"Collapse\"/\"Expand\". */\n  label?: string;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/**\n * A standard collapse/expand toggle button for a {@link CollapsiblePanel}: the\n * recognizable per-side icon (see {@link collapsiblePanelToggleIcon}) plus the\n * `data-action` / `aria-expanded` `wireSidebar` reads. Placement is the app's —\n * put it in the panel's own header (to collapse) and somewhere always-visible\n * (to expand while collapsed).\n */\nexport function CollapsiblePanelToggle({\n  side,\n  collapsed,\n  action,\n  panelId,\n  label,\n  className = '',\n  slot,\n}: CollapsiblePanelToggleProps) {\n  const glyph = collapsiblePanelToggleIcon(side, collapsed);\n  const accessible = label ?? (collapsed ? 'Expand' : 'Collapse');\n  return (\n    <button\n      type=\"button\"\n      class={`kui-collapsible-panel__toggle ${className}`.trim()}\n      data-action={action}\n      data-collapsible-target={panelId}\n      aria-expanded={String(!collapsed)}\n      aria-label={accessible}\n      slot={slot}\n    >\n      <LucideIcon icon={glyph.icon} name={glyph.name} />\n    </button>\n  );\n}\n\nexport interface CollapsiblePanelProps {\n  /** A stable id for the panel — `wireSidebar` targets it and toggles reference it. */\n  id: string;\n  /** Which edge the panel docks to: a left/right rail or a bottom drawer. */\n  side: CollapsiblePanelSide;\n  /** Whether the panel is currently collapsed (the app owns this signal). */\n  collapsed?: boolean;\n  /** Rail width or drawer height in px. Overrides the CSS default. */\n  size?: number;\n  /** Accessible label for the panel region. */\n  label?: string;\n  /** Opt into keyboard (`0`) or programmatic (`-1`) focus on the panel region. */\n  tabIndex?: 0 | -1;\n  /** Keep the standard focus outline visible while the panel is expanded. */\n  outlined?: boolean;\n  /** Panel content. */\n  children?: KerfUiContent;\n  /**\n   * The panel's top toolbar, composed so its groups follow the panel's open\n   * state. With it, `children` renders in a `Pane` below the toolbar; render\n   * {@link CollapsiblePanelRelocated} in the app's work-area toolbar so the\n   * marked groups and toggle stay reachable while the panel is collapsed.\n   */\n  toolbar?: CollapsiblePanelToolbar;\n  /** Fixed content below a toolbar panel's top toolbar. */\n  header?: KerfUiContent;\n  headerList?: ListConfig;\n  headerPlacement?: CollapsiblePanelChromePlacement;\n  /** Fixed content above a toolbar panel's bottom toolbar. */\n  footer?: KerfUiContent;\n  footerList?: ListConfig;\n  bottomToolbar?: CollapsiblePanelBottomToolbar;\n  footerPlacement?: CollapsiblePanelChromePlacement;\n  /**\n   * Configuration for a `toolbar` panel's `Pane` (`contentElement`,\n   * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example\n   * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation\n   * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored\n   * without a `toolbar`, where `children` renders as given.\n   */\n  pane?: PaneConfig;\n  separator?: ResizableRegionSeparator;\n  collapseMotion?: ResizableRegionCollapseMotion;\n  contentOverflow?: ResizableRegionContentOverflow;\n  presentation?: ResizableRegionPresentation;\n  /** Control shown while collapsed, in a safe-area-aware corner of the panel's container (not the viewport). */\n  restoreControl?: SafeHtml;\n  restorePosition?: ResizableRegionRestorePosition;\n  className?: string;\n}\n\n/**\n * A standalone collapsible side rail or bottom drawer, outside the full\n * {@link Workbench} shell. It owns only the presentation: a fixed-size content\n * area that stays laid out while the panel's track snaps to zero and the content\n * slides out via `transform` (one reflow, composited — the same technique\n * `Workbench` and the catalog sidebar use). Bottom-drawer content stays anchored\n * to the panel's fixed bottom edge, so the track cannot move its layout origin\n * underneath the transform transition. A collapsed panel renders `inert` (with\n * `aria-hidden`), so neither Tab, pointer, nor assistive technology reaches\n * content that has slid out of view; its `restoreControl` renders outside the\n * panel and stays reachable.\n * The app owns the `collapsed` signal;\n * pair it with `wireSidebar` for the toggle, focus, compact-overlay, keyboard,\n * and persistence semantics, and with `CollapsiblePanelToggle` for the standard\n * affordance. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.\n */\nexport function CollapsiblePanel({\n  id,\n  side,\n  collapsed = false,\n  size,\n  label,\n  tabIndex,\n  outlined = false,\n  children,\n  toolbar,\n  header,\n  headerList,\n  headerPlacement,\n  footer,\n  footerList,\n  bottomToolbar,\n  footerPlacement,\n  pane,\n  separator = 'auto',\n  collapseMotion = 'slide',\n  contentOverflow = 'clip',\n  presentation = 'inline',\n  restoreControl,\n  restorePosition = side === 'left' ? 'bottom-start' : 'bottom-end',\n  className = '',\n}: CollapsiblePanelProps) {\n  const sizeVar =\n    side === 'bottom'\n      ? '--kui-collapsible-panel-height'\n      : '--kui-collapsible-panel-width';\n  return (\n    <>\n      <aside\n        class={`kui-collapsible-panel kui-collapsible-panel--${side} ${className}`.trim()}\n        data-component=\"collapsible-panel\"\n        data-collapsible-panel={id}\n        data-side={side}\n        data-collapsed={String(collapsed)}\n        data-outlined={\n          !collapsed && presentation !== 'hidden' && outlined\n            ? 'true'\n            : undefined\n        }\n        data-separator={separator}\n        data-collapse-motion={collapseMotion}\n        data-content-overflow={contentOverflow}\n        data-presentation={presentation}\n        aria-label={label || undefined}\n        aria-hidden={\n          collapsed || presentation === 'hidden' ? 'true' : undefined\n        }\n        tabindex={\n          collapsed || presentation === 'hidden'\n            ? tabIndex === undefined\n              ? undefined\n              : -1\n            : tabIndex\n        }\n        inert={collapsed}\n        style={size ? `${sizeVar}: ${size}px` : undefined}\n      >\n        <div class=\"kui-collapsible-panel__content\">\n          {toolbar\n            ? composedPanelBody({\n                toolbar,\n                side,\n                collapsed,\n                attributes: toggleAttributes(id),\n                pane,\n                header,\n                headerList,\n                headerPlacement,\n                footer,\n                footerList,\n                bottomToolbar,\n                footerPlacement,\n                content: children,\n              })\n            : children}\n        </div>\n      </aside>\n      {collapsed && restoreControl && presentation !== 'hidden' && (\n        <div\n          class=\"kui-collapsible-panel__restore\"\n          data-panel-restore={id}\n          data-position={restorePosition}\n        >\n          {restoreControl}\n        </div>\n      )}\n    </>\n  );\n}\n\nexport interface CollapsiblePanelRelocatedProps {\n  /** The panel's `id`. */\n  panelId: string;\n  side: CollapsiblePanelSide;\n  /** The panel's current collapsed state. */\n  collapsed: boolean;\n  /** The same `toolbar` the panel receives. */\n  toolbar: CollapsiblePanelToolbar;\n}\n\n/**\n * A collapsed {@link CollapsiblePanel}'s marked groups and standard\n * toggle, for the app's work-area toolbar — nothing while the panel is open.\n * Put it first in the leading zone for a left rail, last in the trailing zone\n * for a right rail, and last in a bottom toolbar (or a `FloatingToolbar`\n * `restoreControl`) for a bottom drawer. `wireSidebar` hands focus to it when\n * the panel closes from its own toggle.\n */\nexport function CollapsiblePanelRelocated({\n  panelId,\n  side,\n  collapsed,\n  toolbar,\n}: CollapsiblePanelRelocatedProps) {\n  return (\n    <>\n      {relocatedPanelGroups(\n        toolbar,\n        side,\n        collapsed,\n        toggleAttributes(panelId),\n      )}\n    </>\n  );\n}\n"]}

package/dist/content-item.d.ts

@@ -0,0 +1,99 @@
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
+
+/** Base surface treatment or semantic status colors. */
+type ContentItemAppearance = 'transparent' | 'surface' | SemanticTone;
+/** Whether the item's always-reserved 1px border is transparent or visible. */
+type ContentItemFrame = 'none' | 'framed';
+/** Corner shape: the 12px rounded rectangle or the 22px pill. */
+type ContentItemShape = 'rounded' | 'pill';
+/** `single` uses an option; `multiple` uses a grid row; `toggle` uses a pressed button. */
+type ContentItemSelectionMode = 'none' | 'single' | 'multiple' | 'toggle';
+type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-appearance'?: never;
+    'data-outlined'?: never;
+}>;
+type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-appearance'?: never;
+    'data-outlined'?: never;
+    'data-action'?: never;
+    'data-item-id'?: never;
+    'data-interactive'?: never;
+    'data-selected'?: never;
+    'data-disabled'?: never;
+    'data-selection-mode'?: never;
+    'data-kui-pressed'?: never;
+}>;
+interface ContentItemBaseProps {
+    /**
+     * Coordinated background, border, and foreground colors. `transparent`
+     * preserves the surrounding surface; `surface` paints the base surface;
+     * semantic values match StateBanner. Defaults to `transparent`.
+     */
+    appearance?: ContentItemAppearance;
+    /** Item content; a plain string is allowed for bare copy. */
+    children?: KerfUiContent | string;
+    /**
+     * `framed` paints the standard neutral border in the 1px the item always
+     * reserves, so framing never changes geometry. Frame only an item that
+     * marks a real distinction. Defaults to `none` (transparent border).
+     */
+    frame?: ContentItemFrame;
+    /** Remove block padding and block borders while retaining inline geometry. */
+    flush?: boolean;
+    /** Corner shape. Defaults to `rounded`. */
+    shape?: ContentItemShape;
+    /** Native hover tooltip. */
+    title?: string;
+    /**
+     * Names the item as a distinct region (`role="region"`). Omit it for an
+     * ordinary item, which stays a non-landmark grouping.
+     */
+    ariaLabel?: string;
+    /**
+     * Makes the item a programmatic focus target (`tabindex="-1"`, never a tab
+     * stop), for example the preferred initial focus of a NavStack view when
+     * combined with `data-nav-focus` in `rootAttributes`.
+     */
+    focusTarget?: boolean;
+    /** Keep the standard focus outline visible, such as for a drop target. */
+    outlined?: boolean;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+type ContentItemProps = ContentItemBaseProps & ({
+    interactive?: false;
+    action?: never;
+    itemId?: never;
+    selectionMode?: never;
+    selected?: never;
+    disabled?: never;
+    /** Opt into keyboard (`0`) or programmatic (`-1`) focus. */
+    tabIndex?: 0 | -1;
+    /** Existing static `data-*` metadata remains available. */
+    rootAttributes?: ContentItemRootAttributes;
+} | {
+    /** Enable a keyboard reachable card; wire `wireContentItems` once on its containing root. */
+    interactive: true;
+    /** Delegated action dispatched by pointer, Enter, or Space. */
+    action: string;
+    itemId?: string;
+    selectionMode?: ContentItemSelectionMode;
+    selected?: boolean;
+    disabled?: boolean;
+    tabIndex?: never;
+    /** Safe app metadata; interaction attributes are component-owned. */
+    rootAttributes?: ContentItemInteractiveRootAttributes;
+});
+/**
+ * One self-contained `.kui-content` child: an 8px inline margin, a real 1px
+ * border (transparent unless `framed`), 8px padding, and a rounded or pill
+ * radius. It owns that whole geometry, so wrappers must not add more.
+ */
+declare function ContentItem({ appearance, children, frame, flush, shape, title, ariaLabel, focusTarget, outlined, tabIndex, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+
+export { ContentItem, type ContentItemAppearance, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };

package/dist/content-item.js

@@ -0,0 +1,4 @@
+export { ContentItem } from './chunk-B3TROLC2.js';
+
+
+//# sourceMappingURL=content-item.js.map

package/dist/content-item.js.map

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

package/dist/css-values.d.ts

@@ -0,0 +1,119 @@
+declare const cssValueBrand: unique symbol;
+declare const cssLengthBrand: unique symbol;
+declare const cssLengthExpressionBrand: unique symbol;
+declare const cssFlexBrand: unique symbol;
+declare const cssColorBrand: unique symbol;
+declare const cssForegroundColorBrand: unique symbol;
+/**
+ * A complete typed CSS value minted by a property-specific Kerf UI builder.
+ *
+ * This brand is an authoring correctness aid, not a sanitizer or security
+ * boundary. Prefer the narrower property grammar, such as {@link CssLength},
+ * whenever one is available.
+ */
+type CssValue = string & {
+    readonly [cssValueBrand]: 'CssValue';
+};
+/**
+ * A complete CSS length-percentage value suitable for dimension-valued UI
+ * props. Despite the concise name, percentages are intentionally included.
+ */
+type CssLength = CssValue & {
+    readonly [cssLengthBrand]: 'CssLength';
+};
+/**
+ * An incomplete arithmetic expression. Wrap it with {@link calc} before
+ * passing it to a prop that accepts {@link CssLength}.
+ */
+type CssLengthExpression = string & {
+    readonly [cssLengthExpressionBrand]: 'CssLengthExpression';
+};
+/** A complete CSS `flex` shorthand. It is not interchangeable with a length. */
+type CssFlex = CssValue & {
+    readonly [cssFlexBrand]: 'CssFlex';
+};
+/** A complete CSS color value. It is not interchangeable with a length. */
+type CssColor = CssValue & {
+    readonly [cssColorBrand]: 'CssColor';
+};
+/**
+ * A complete CSS color meant to paint a foreground: text or an icon drawn over
+ * a surface. Mint it with {@link uiColor} and a foreground token name
+ * ({@link UiForegroundColorName}) or with {@link foregroundColorVar}. It is a
+ * {@link CssColor}, but a plain `CssColor` is not a foreground color: fill,
+ * border, and surface tokens are pale backgrounds that leave a foreground
+ * nearly invisible.
+ */
+type CssForegroundColor = CssColor & {
+    readonly [cssForegroundColorBrand]: 'CssForegroundColor';
+};
+type CssFlexKeyword = 'none' | 'auto' | 'initial';
+type CssFlexBasis = CssLength | 'auto' | 'content' | 'min-content' | 'max-content' | 'fit-content';
+type CssSizeKeyword = 'auto' | 'min-content' | 'max-content' | 'fit-content';
+/** A complete width/height value accepted by dimension-valued UI props. */
+type CssSize = CssLength | CssSizeKeyword;
+declare const uiColorNames: readonly ["brand-border-loud", "brand-border-normal", "brand-border-quiet", "brand-fill-loud", "brand-fill-normal", "brand-fill-quiet", "brand-on-fill", "brand-on-loud", "brand-on-normal", "brand-on-quiet", "danger-border-loud", "danger-border-normal", "danger-border-quiet", "danger-fill-loud", "danger-fill-normal", "danger-fill-quiet", "danger-on-fill", "danger-on-loud", "danger-on-normal", "danger-on-quiet", "neutral-border-loud", "neutral-border-normal", "neutral-border-quiet", "neutral-fill-loud", "neutral-fill-normal", "neutral-fill-quiet", "neutral-on-loud", "neutral-on-normal", "neutral-on-quiet", "pop-border-loud", "pop-border-normal", "pop-border-quiet", "pop-fill-loud", "pop-fill-normal", "pop-fill-quiet", "pop-on-fill", "pop-on-loud", "pop-on-normal", "pop-on-quiet", "success-border-loud", "success-border-normal", "success-border-quiet", "success-fill-loud", "success-fill-normal", "success-fill-quiet", "success-on-fill", "success-on-loud", "success-on-normal", "success-on-quiet", "surface", "surface-lowered", "surface-raised", "text", "text-link", "text-quiet", "warning-border-loud", "warning-border-normal", "warning-border-quiet", "warning-fill-loud", "warning-fill-normal", "warning-fill-quiet", "warning-on-fill", "warning-on-loud", "warning-on-normal", "warning-on-quiet"];
+/** Names of the public `--kui-color-*` semantic tokens. */
+type UiColorName = (typeof uiColorNames)[number];
+/** The semantic tokens that paint a foreground: the `*-on-*` and text roles. */
+type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | 'text' | 'text-quiet' | 'text-link'>;
+/** Kerf UI's complete spacing-token vocabulary. `s` and `xl` are exceptions. */
+type UiSpaceName = 'none' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
+/** A token or complete typed length for one gap axis. */
+type UiGapValue = UiSpaceName | CssLength;
+/** A shared gap or independent column and row gaps. */
+type UiGap = UiGapValue | Readonly<{
+    column: UiGapValue;
+    row: UiGapValue;
+}>;
+/** Create a complete pixel length. */
+declare function px(value: number): CssLength;
+/** Create a complete root-font-relative length. */
+declare function rem(value: number): CssLength;
+/** Converts a pixel value into rem units by dividing by 16. */
+declare function remify(value: number): CssLength;
+/** Create a complete current-font-relative length. */
+declare function em(value: number): CssLength;
+/** Create a complete percentage length. */
+declare function pct(value: number): CssLength;
+/** Resolve a Kerf UI spacing step to its public custom property. */
+declare function space(name: UiSpaceName): CssLength;
+/**
+ * Reference an application-owned custom property whose contract is a CSS
+ * length-percentage. The deliberately narrow name grammar keeps this helper
+ * from becoming an arbitrary CSS-string constructor.
+ */
+declare function lengthVar(name: `--${string}`, fallback?: CssLength): CssLength;
+/** Combine two or more complete lengths into a non-standalone sum. */
+declare function plus(first: CssLength, second: CssLength, ...rest: readonly CssLength[]): CssLengthExpression;
+/** Turn a typed length expression into a complete CSS `calc()` value. */
+declare function calc(expression: CssLengthExpression): CssLength;
+/** Build a complete, structured CSS flex shorthand. */
+declare function flex(grow: number, shrink?: number, basis?: CssFlexBasis): CssFlex;
+/**
+ * The brand {@link uiColor} returns for a token name: a
+ * {@link CssForegroundColor} for a foreground token, otherwise a plain
+ * {@link CssColor}.
+ */
+type UiColor<Name extends UiColorName> = Name extends UiForegroundColorName ? CssForegroundColor : CssColor;
+/**
+ * Resolve a public Kerf UI semantic color token. A foreground token name
+ * (`success-on-quiet`, `text-quiet`, …) returns a {@link CssForegroundColor};
+ * any other token returns a plain {@link CssColor}.
+ */
+declare function uiColor<Name extends UiColorName>(name: Name): UiColor<Name>;
+/** Reference an application-owned custom property whose contract is a color. */
+declare function colorVar(name: `--${string}`, fallback?: CssColor): CssColor;
+/**
+ * Reference an application-owned custom property whose contract is a
+ * foreground color (text or an icon over a surface). Use it where a prop
+ * accepts only {@link CssForegroundColor}, such as `SelectChoice.color`.
+ */
+declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroundColor): CssForegroundColor;
+/**
+ * Use an application-chosen CSS color for foreground content. The browser
+ * resolves the color syntax; this checks only that it is one declaration value.
+ */
+declare function foregroundColor(value: string): CssForegroundColor;
+
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiGap, type UiGapValue, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };

package/dist/css-values.js

@@ -0,0 +1,3 @@
+export { calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor } from './chunk-U657IHFB.js';
+
+//# sourceMappingURL=css-values.js.map

package/dist/css-values.js.map

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

package/dist/device-class.js

@@ -1,14 +1,25 @@
 import { computed, signal } from 'kerfjs';
 
-// src/device-class.ts
+// src/shared/environment/device-class.ts
 var DEFAULT_BREAKPOINTS = {
   mobile: 360,
   tablet: 720,
   desktop: 1024,
   "xl-desktop": 1440
 };
-var SIZE_ORDER = ["xs-mobile", "mobile", "tablet", "desktop", "xl-desktop"];
-var SSR_VIEWPORT = { width: 1024, height: 768, segments: 1, verticalSegments: 1 };
+var SIZE_ORDER = [
+  "xs-mobile",
+  "mobile",
+  "tablet",
+  "desktop",
+  "xl-desktop"
+];
+var SSR_VIEWPORT = {
+  width: 1024,
+  height: 768,
+  segments: 1,
+  verticalSegments: 1
+};
 function classifyViewport(width, orientation, segments = 1, verticalSegments = 1, breakpoints = DEFAULT_BREAKPOINTS) {
   const size = width >= breakpoints["xl-desktop"] ? "xl-desktop" : width >= breakpoints.desktop ? "desktop" : width >= breakpoints.tablet ? "tablet" : width >= breakpoints.mobile ? "mobile" : "xs-mobile";
   const rank = SIZE_ORDER.indexOf(size);
@@ -57,16 +68,33 @@ function orientationOf(view) {
   return view.height > view.width ? "portrait" : "landscape";
 }
 function deviceClass(options = {}) {
-  const breakpoints = { ...DEFAULT_BREAKPOINTS, ...options.breakpoints };
+  const breakpoints = {
+    ...DEFAULT_BREAKPOINTS,
+    ...options.breakpoints
+  };
   const view = browserWindow();
   if (!view) {
     const snapshot = { ...SSR_VIEWPORT, ...options.ssr };
-    return computed(() => classifyViewport(snapshot.width, orientationOf(snapshot), snapshot.segments, snapshot.verticalSegments, breakpoints));
+    return computed(
+      () => classifyViewport(
+        snapshot.width,
+        orientationOf(snapshot),
+        snapshot.segments,
+        snapshot.verticalSegments,
+        breakpoints
+      )
+    );
   }
   const source = viewportSource(view);
   return computed(() => {
     const v = source.value;
-    return classifyViewport(v.width, orientationOf(v), v.segments, v.verticalSegments, breakpoints);
+    return classifyViewport(
+      v.width,
+      orientationOf(v),
+      v.segments,
+      v.verticalSegments,
+      breakpoints
+    );
   });
 }
 

package/dist/device-class.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/device-class.ts"],"names":[],"mappings":"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","file":"device-class.js","sourcesContent":["import { computed, type ReadonlySignal, signal } from 'kerfjs';\n\n/**\n * Reactive device-class detection for `@kerfjs/ui` (see `docs/23-app-layouts.md`\n * §2). `deviceClass()` returns a `ReadonlySignal<DeviceClass>` describing the\n * current viewport as a size bucket × orientation × viewport-segment count, so a\n * layout can pick its presentation reactively instead of hand-wiring `matchMedia`.\n *\n * One shared viewport source backs every reader; the pure `classifyViewport`\n * core is DOM-free and directly unit-tested.\n */\n\nexport type DeviceSize = 'xs-mobile' | 'mobile' | 'tablet' | 'desktop' | 'xl-desktop';\nexport type DeviceOrientation = 'portrait' | 'landscape';\n\n/** Minimum widths (px) at which each larger bucket begins. `xs-mobile` is 0. */\nexport interface DeviceBreakpoints {\n  mobile: number;\n  tablet: number;\n  desktop: number;\n  'xl-desktop': number;\n}\n\nexport interface DeviceClass {\n  size: DeviceSize;\n  orientation: DeviceOrientation;\n  /** Horizontal viewport segments (foldables / dual-screen); 1 on ordinary devices. */\n  segments: number;\n  /** Vertical viewport segments; 1 on ordinary devices. */\n  verticalSegments: number;\n  /** Small phones — `xs-mobile` or `mobile`. */\n  handset: boolean;\n  /** \"One pane at a time\" — a handset or a portrait tablet. */\n  compact: boolean;\n  /** True when the current size is `size` or larger, e.g. `atLeast('tablet')`. */\n  atLeast(size: DeviceSize): boolean;\n}\n\n/** A raw viewport snapshot, before breakpoints are applied. */\nexport interface Viewport {\n  width: number;\n  height: number;\n  segments: number;\n  verticalSegments: number;\n}\n\nexport interface DeviceClassOptions {\n  /** Override any of the default bucket thresholds. */\n  breakpoints?: Partial<DeviceBreakpoints>;\n  /** The viewport assumed when there is no DOM (SSR). Defaults to 1024×768, one segment. */\n  ssr?: Partial<Viewport>;\n}\n\nexport const DEFAULT_BREAKPOINTS: DeviceBreakpoints = {\n  mobile: 360,\n  tablet: 720,\n  desktop: 1024,\n  'xl-desktop': 1440,\n};\n\nconst SIZE_ORDER: readonly DeviceSize[] = ['xs-mobile', 'mobile', 'tablet', 'desktop', 'xl-desktop'];\n\nconst SSR_VIEWPORT: Viewport = { width: 1024, height: 768, segments: 1, verticalSegments: 1 };\n\n/**\n * Classify a raw viewport into a {@link DeviceClass}. Pure and DOM-free — the\n * single source of truth for the bucketing rules.\n */\nexport function classifyViewport(\n  width: number,\n  orientation: DeviceOrientation,\n  segments = 1,\n  verticalSegments = 1,\n  breakpoints: DeviceBreakpoints = DEFAULT_BREAKPOINTS,\n): DeviceClass {\n  const size: DeviceSize =\n    width >= breakpoints['xl-desktop']\n      ? 'xl-desktop'\n      : width >= breakpoints.desktop\n        ? 'desktop'\n        : width >= breakpoints.tablet\n          ? 'tablet'\n          : width >= breakpoints.mobile\n            ? 'mobile'\n            : 'xs-mobile';\n  const rank = SIZE_ORDER.indexOf(size);\n  return {\n    size,\n    orientation,\n    segments,\n    verticalSegments,\n    handset: rank <= 1,\n    compact: rank <= 1 || (size === 'tablet' && orientation === 'portrait'),\n    atLeast: (target) => rank >= SIZE_ORDER.indexOf(target),\n  };\n}\n\n/** Count viewport segments along one axis, feature-detecting the media query. */\nfunction countSegments(axis: 'horizontal' | 'vertical', view: Window): number {\n  const mq = view.matchMedia;\n  if (typeof mq !== 'function') return 1;\n  for (let n = 4; n >= 2; n--) {\n    if (mq.call(view, `(${axis}-viewport-segments: ${n})`).matches) return n;\n  }\n  return 1;\n}\n\n/** Read the current viewport from a browser window. */\nfunction readViewport(view: Window): Viewport {\n  return {\n    width: view.innerWidth,\n    height: view.innerHeight,\n    segments: countSegments('horizontal', view),\n    verticalSegments: countSegments('vertical', view),\n  };\n}\n\n/** The browser window, or `undefined` when running without a DOM (SSR). */\nfunction browserWindow(): Window | undefined {\n  return typeof window === 'undefined' ? undefined : window;\n}\n\nlet sharedSource: ReturnType<typeof signal<Viewport>> | undefined;\n\n/**\n * The shared reactive viewport source. Installed lazily on first read and kept\n * for the life of the page — there is only ever one viewport, so a single\n * listener set backs every `deviceClass()` reader.\n */\nfunction viewportSource(view: Window): ReturnType<typeof signal<Viewport>> {\n  if (sharedSource) return sharedSource;\n  const source = signal(readViewport(view));\n  sharedSource = source;\n  const update = (): void => {\n    source.value = readViewport(view);\n  };\n  view.addEventListener('resize', update);\n  view.addEventListener('orientationchange', update);\n  return source;\n}\n\nfunction orientationOf(view: Viewport): DeviceOrientation {\n  return view.height > view.width ? 'portrait' : 'landscape';\n}\n\n/**\n * A reactive signal of the current {@link DeviceClass}. Reading it inside an\n * `effect`/`computed` re-runs when the viewport crosses a breakpoint, rotates,\n * or changes its segment count. Without a DOM it resolves to `options.ssr`\n * (default 1024×768, landscape, one segment).\n */\nexport function deviceClass(options: DeviceClassOptions = {}): ReadonlySignal<DeviceClass> {\n  const breakpoints: DeviceBreakpoints = { ...DEFAULT_BREAKPOINTS, ...options.breakpoints };\n  const view = browserWindow();\n  if (!view) {\n    const snapshot: Viewport = { ...SSR_VIEWPORT, ...options.ssr };\n    return computed(() => classifyViewport(snapshot.width, orientationOf(snapshot), snapshot.segments, snapshot.verticalSegments, breakpoints));\n  }\n  const source = viewportSource(view);\n  return computed(() => {\n    const v = source.value;\n    return classifyViewport(v.width, orientationOf(v), v.segments, v.verticalSegments, breakpoints);\n  });\n}\n"]}
+{"version":3,"sources":["../src/shared/environment/device-class.ts"],"names":[],"mappings":"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","file":"device-class.js","sourcesContent":["import { computed, type ReadonlySignal, signal } from 'kerfjs';\n\n/**\n * Reactive device-class detection for `@kerfjs/ui` (see `docs/23-app-layouts.md`\n * §2). `deviceClass()` returns a `ReadonlySignal<DeviceClass>` describing the\n * current viewport as a size bucket × orientation × viewport-segment count, so a\n * layout can pick its presentation reactively instead of hand-wiring `matchMedia`.\n *\n * One shared viewport source backs every reader; the pure `classifyViewport`\n * core is DOM-free and directly unit-tested.\n */\n\nexport type DeviceSize =\n  'xs-mobile' | 'mobile' | 'tablet' | 'desktop' | 'xl-desktop';\nexport type DeviceOrientation = 'portrait' | 'landscape';\n\n/** Minimum widths (px) at which each larger bucket begins. `xs-mobile` is 0. */\nexport interface DeviceBreakpoints {\n  mobile: number;\n  tablet: number;\n  desktop: number;\n  'xl-desktop': number;\n}\n\nexport interface DeviceClass {\n  size: DeviceSize;\n  orientation: DeviceOrientation;\n  /** Horizontal viewport segments (foldables / dual-screen); 1 on ordinary devices. */\n  segments: number;\n  /** Vertical viewport segments; 1 on ordinary devices. */\n  verticalSegments: number;\n  /** Small phones — `xs-mobile` or `mobile`. */\n  handset: boolean;\n  /** \"One pane at a time\" — a handset or a portrait tablet. */\n  compact: boolean;\n  /** True when the current size is `size` or larger, e.g. `atLeast('tablet')`. */\n  atLeast(size: DeviceSize): boolean;\n}\n\n/** A raw viewport snapshot, before breakpoints are applied. */\nexport interface Viewport {\n  width: number;\n  height: number;\n  segments: number;\n  verticalSegments: number;\n}\n\nexport interface DeviceClassOptions {\n  /** Override any of the default bucket thresholds. */\n  breakpoints?: Partial<DeviceBreakpoints>;\n  /** The viewport assumed when there is no DOM (SSR). Defaults to 1024×768, one segment. */\n  ssr?: Partial<Viewport>;\n}\n\nexport const DEFAULT_BREAKPOINTS: DeviceBreakpoints = {\n  mobile: 360,\n  tablet: 720,\n  desktop: 1024,\n  'xl-desktop': 1440,\n};\n\nconst SIZE_ORDER: readonly DeviceSize[] = [\n  'xs-mobile',\n  'mobile',\n  'tablet',\n  'desktop',\n  'xl-desktop',\n];\n\nconst SSR_VIEWPORT: Viewport = {\n  width: 1024,\n  height: 768,\n  segments: 1,\n  verticalSegments: 1,\n};\n\n/**\n * Classify a raw viewport into a {@link DeviceClass}. Pure and DOM-free — the\n * single source of truth for the bucketing rules.\n */\nexport function classifyViewport(\n  width: number,\n  orientation: DeviceOrientation,\n  segments = 1,\n  verticalSegments = 1,\n  breakpoints: DeviceBreakpoints = DEFAULT_BREAKPOINTS,\n): DeviceClass {\n  const size: DeviceSize =\n    width >= breakpoints['xl-desktop']\n      ? 'xl-desktop'\n      : width >= breakpoints.desktop\n        ? 'desktop'\n        : width >= breakpoints.tablet\n          ? 'tablet'\n          : width >= breakpoints.mobile\n            ? 'mobile'\n            : 'xs-mobile';\n  const rank = SIZE_ORDER.indexOf(size);\n  return {\n    size,\n    orientation,\n    segments,\n    verticalSegments,\n    handset: rank <= 1,\n    compact: rank <= 1 || (size === 'tablet' && orientation === 'portrait'),\n    atLeast: (target) => rank >= SIZE_ORDER.indexOf(target),\n  };\n}\n\n/** Count viewport segments along one axis, feature-detecting the media query. */\nfunction countSegments(axis: 'horizontal' | 'vertical', view: Window): number {\n  const mq = view.matchMedia;\n  if (typeof mq !== 'function') return 1;\n  for (let n = 4; n >= 2; n--) {\n    if (mq.call(view, `(${axis}-viewport-segments: ${n})`).matches) return n;\n  }\n  return 1;\n}\n\n/** Read the current viewport from a browser window. */\nfunction readViewport(view: Window): Viewport {\n  return {\n    width: view.innerWidth,\n    height: view.innerHeight,\n    segments: countSegments('horizontal', view),\n    verticalSegments: countSegments('vertical', view),\n  };\n}\n\n/** The browser window, or `undefined` when running without a DOM (SSR). */\nfunction browserWindow(): Window | undefined {\n  return typeof window === 'undefined' ? undefined : window;\n}\n\nlet sharedSource: ReturnType<typeof signal<Viewport>> | undefined;\n\n/**\n * The shared reactive viewport source. Installed lazily on first read and kept\n * for the life of the page — there is only ever one viewport, so a single\n * listener set backs every `deviceClass()` reader.\n */\nfunction viewportSource(view: Window): ReturnType<typeof signal<Viewport>> {\n  if (sharedSource) return sharedSource;\n  const source = signal(readViewport(view));\n  sharedSource = source;\n  const update = (): void => {\n    source.value = readViewport(view);\n  };\n  view.addEventListener('resize', update);\n  view.addEventListener('orientationchange', update);\n  return source;\n}\n\nfunction orientationOf(view: Viewport): DeviceOrientation {\n  return view.height > view.width ? 'portrait' : 'landscape';\n}\n\n/**\n * A reactive signal of the current {@link DeviceClass}. Reading it inside an\n * `effect`/`computed` re-runs when the viewport crosses a breakpoint, rotates,\n * or changes its segment count. Without a DOM it resolves to `options.ssr`\n * (default 1024×768, landscape, one segment).\n */\nexport function deviceClass(\n  options: DeviceClassOptions = {},\n): ReadonlySignal<DeviceClass> {\n  const breakpoints: DeviceBreakpoints = {\n    ...DEFAULT_BREAKPOINTS,\n    ...options.breakpoints,\n  };\n  const view = browserWindow();\n  if (!view) {\n    const snapshot: Viewport = { ...SSR_VIEWPORT, ...options.ssr };\n    return computed(() =>\n      classifyViewport(\n        snapshot.width,\n        orientationOf(snapshot),\n        snapshot.segments,\n        snapshot.verticalSegments,\n        breakpoints,\n      ),\n    );\n  }\n  const source = viewportSource(view);\n  return computed(() => {\n    const v = source.value;\n    return classifyViewport(\n      v.width,\n      orientationOf(v),\n      v.segments,\n      v.verticalSegments,\n      breakpoints,\n    );\n  });\n}\n"]}

package/dist/disclosure-arrow.d.ts

@@ -1,4 +1,5 @@
 import { SafeHtml } from 'kerfjs';
+import { CssLength } from './css-values.js';
 
 type DisclosureDirection = 'up' | 'down' | 'left' | 'right';
 interface DisclosureArrowProps {
@@ -7,8 +8,12 @@ interface DisclosureArrowProps {
     closedDirection?: DisclosureDirection;
     /** Replacement icons should use right as their unrotated orientation. */
     icon?: SafeHtml;
+    /** Typed box size for the square visual. Default: `remify(18px)`. */
+    size?: CssLength;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function DisclosureArrow({ open, openDirection, closedDirection, icon, className, }: DisclosureArrowProps): SafeHtml;
+declare function DisclosureArrow({ open, openDirection, closedDirection, icon, size, className, slot, }: DisclosureArrowProps): SafeHtml;
 
 export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };

package/dist/disclosure-arrow.js

@@ -1,4 +1,5 @@
-export { DisclosureArrow } from './chunk-56RJXPHG.js';
+export { DisclosureArrow } from './chunk-2YPPNFYT.js';
+
 
 
 //# sourceMappingURL=disclosure-arrow.js.map

package/dist/empty-state.d.ts

@@ -1,13 +1,16 @@
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface EmptyStateProps {
     title: string;
     detail?: string;
     icon?: SafeHtml;
-    action?: SafeHtml;
+    action?: KerfUiContent;
     busy?: boolean;
     className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function EmptyState({ title, detail, icon, action, busy, className }: EmptyStateProps): SafeHtml;
+declare function EmptyState({ title, detail, icon, action, busy, className, slot, }: EmptyStateProps): SafeHtml;
 
 export { EmptyState, type EmptyStateProps };

package/dist/empty-state.js

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

package/dist/flex-alignment-4ms8ZbV8.d.ts

@@ -0,0 +1,5 @@
+type HorizontalAlignment = 'left' | 'l' | 'flex-start' | 'center' | 'c' | 'space-around' | 'right' | 'r' | 'flex-end' | 'full' | 'f' | 'space-between';
+type VerticalAlignment = 'top' | 't' | 'flex-start' | 'middle' | 'm' | 'c' | 'space-around' | 'bottom' | 'b' | 'flex-end' | 'full' | 'f' | 'space-between' | 'baseline';
+type ListVerticalAlignment = Exclude<VerticalAlignment, 'baseline'>;
+
+export type { HorizontalAlignment as H, ListVerticalAlignment as L, VerticalAlignment as V };

package/dist/floating-toolbar.d.ts

@@ -0,0 +1,51 @@
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
+
+/** Where a {@link FloatingToolbar} floats within its positioned container. */
+type FloatingToolbarPosition = 'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end';
+interface FloatingToolbarProps {
+    /** Toolbar contents — normally one or more `ToolbarControlGroup`s. */
+    children: KerfUiContent;
+    /** Accessible name for the toolbar (required — it exposes `role="toolbar"`). */
+    label: string;
+    /**
+     * Corner or edge it floats to inside its nearest positioned ancestor.
+     * Default: `'bottom-end'`.
+     */
+    position?: FloatingToolbarPosition;
+    /** Keep the toolbar in normal document flow instead of floating over content. */
+    placement?: 'floating' | 'inline';
+    /**
+     * Distance from the container edges named by `position`. Default:
+     * `space('m')` (16px, 8px past a top toolbar's own inset). Omit it inside a
+     * `Workbench`, `CollapsiblePanel`, or `ResizableRegion` restore corner: the
+     * corner owns the inset there and sets it to zero.
+     */
+    inset?: CssLength;
+    /** Add device or layout-routed safe-area insets to the positioned edges. */
+    safeAreaInsets?: boolean;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/**
+ * A toolbar that floats above the main content of its nearest positioned
+ * ancestor — a transparent, forced-dark cluster of controls (e.g. a drawer
+ * restore button) that sits over the content but NOT over dialogs or overlays
+ * (it is not in the top layer). It is inset from the container edges by
+ * `inset` (default `--kui-space-m`, i.e. 8px more than a top toolbar's own
+ * inset); pass a typed length to move it. Inside a `Workbench`, `CollapsiblePanel`, or
+ * `ResizableRegion` restore corner the corner owns the inset, so the toolbar
+ * floats from the corner's own position. While one of those layouts has a
+ * side overlay open over the toolbar's region (a Workbench rail overlay, a
+ * `wireSidebar` compact overlay, an overlay `CollapsiblePanel` or horizontal
+ * `ResizableRegion`), the toolbar is hidden — unfocusable and out of the
+ * accessibility tree — until the overlay closes. The app owns the controls
+ * and their behavior — wire them with `delegate()` as usual. Set
+ * `placement="inline"` for normal flow when an owner already positions the
+ * control; floating placement can add safe-area insets to its per-edge tokens.
+ */
+declare function FloatingToolbar({ children, label, position, placement, inset, safeAreaInsets, className, slot, }: FloatingToolbarProps): kerfjs.SafeHtml;
+
+export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };

package/dist/floating-toolbar.js

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

package/dist/floating-toolbar.js.map

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