@kerfjs/ui 5.0.0-beta.97 → 5.0.0-beta.99

package/dist/surface-scaffold.d.ts

@@ -11,9 +11,24 @@ type DialogSurfaceHeight = CssLength | 'viewport';
 /**
  * How the dialog body lays out its children: `flow` (default) scrolls ordinary
  * content in the body; `fill` gives one child the body's whole height and
- * lets it own scrolling (a SplitView, a Pane, an editor).
+ * lets it own scrolling (a SplitView, a Pane, an editor); `fill-last` stacks
+ * the leading children at their natural height and gives the last child the
+ * remaining height to own its scrolling (a heading and notices above a
+ * scrolling transcript).
  */
-type DialogSurfaceBodyLayout = 'flow' | 'fill';
+type DialogSurfaceBodyLayout = 'flow' | 'fill' | 'fill-last';
+/**
+ * Where the dialog footer sits: `docked` (default) below the body, or
+ * `floating` over the body's block end, inset from the panel's inline and
+ * block-end edges on a transparent background (a chat composer).
+ */
+type DialogSurfaceFooterPresentation = 'docked' | 'floating';
+/**
+ * Where the dialog header sits: `docked` (default) above the body, or
+ * `floating` over the body's block-start edge on the translucent chrome
+ * material, so content scrolls visibly beneath the title bar.
+ */
+type DialogSurfaceHeaderPresentation = 'docked' | 'floating';
 /**
  * Application `data-*` identity on the DialogSurface root, such as
  * `data-key`; the surface's own configuration attributes stay protected.
@@ -36,8 +51,43 @@ interface DialogSurfaceProps {
      * height to fill. Takes precedence over `maxHeight`.
      */
     height?: DialogSurfaceHeight;
-    /** Body layout (default `flow`); `fill` lets one child own the body. */
+    /**
+     * Body layout (default `flow`); `fill` lets one child own the body and
+     * `fill-last` stacks fixed rows above one filling last child.
+     */
     bodyLayout?: DialogSurfaceBodyLayout;
+    /**
+     * Header placement (default `docked`); `floating` lays the dialog's header
+     * (its title and close control) over the body's block-start edge on the
+     * translucent chrome material (`--kui-chrome-material-raised`, opaque under
+     * `prefers-reduced-transparency`, increased contrast, forced colors, or
+     * without `backdrop-filter`). The `/register` entry measures the header;
+     * the body reserves that height before its own inset, so its first content
+     * rests below the title bar. A `fill`/`fill-last` child that is the body's
+     * only child and opts into block-start `scrollClearance` (a `List` or
+     * `Pane`) takes the clearance inside its own scroll area instead, published
+     * as `--kui-scroll-clearance-block-start`, so its content scrolls visibly
+     * beneath the header. Unmeasured (without the register), the header stays
+     * docked. Keep header text in the normal text color: quiet text can fall
+     * below AA over the content passing beneath it.
+     */
+    headerPresentation?: DialogSurfaceHeaderPresentation;
+    /**
+     * Footer placement (default `docked`); `floating` lays the footer over the
+     * body's block end. The body reserves the footer's measured height so its
+     * last content is never hidden beneath it. A `fill`/`fill-last` child that
+     * opts into block-end `scrollClearance` (a `List` or `Pane`) takes that
+     * clearance inside its own scroll area instead, published as
+     * `--kui-scroll-clearance-block-end`, so its content scrolls visibly beneath
+     * the transparent footer.
+     */
+    footerPresentation?: DialogSurfaceFooterPresentation;
+    /**
+     * A floating footer's clearance from the panel's inline and block-end edges
+     * (default the 16px container inset). Choose a phone value such as
+     * `remify(8)` from `deviceClass()`; the scaffold adds no breakpoint.
+     */
+    footerOffset?: CssLength;
     /**
      * Safe `data-*` identity on the root. Give sibling dialogs distinct
      * `data-key`s so a re-render morphs each surface into itself instead of
@@ -50,7 +100,7 @@ interface DialogSurfaceProps {
     slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, bodyLayout, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, 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. */
@@ -65,6 +115,12 @@ type PopoverDialogSurfaceName = {
 type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
     /** The root id: what an opening control's `popovertarget` names. */
     id?: string;
+    /**
+     * Id of the element whose text is the dialog's accessible description,
+     * such as a title `ToolbarText`'s `descriptionId`; rendered as
+     * `aria-describedby` on the `role="dialog"` root.
+     */
+    describedBy?: string;
     children: KerfUiContent;
     /**
      * `overlay` (default) is a native `popover="auto"` in the top layer:
@@ -82,7 +138,10 @@ type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
     maxHeight?: DialogSurfaceMaxHeight;
     /** Edge clearance on each side of the viewport (default 16px). */
     viewportGutter?: CssLength;
-    /** Body layout (default `flow`); `fill` lets one child own the surface. */
+    /**
+     * Body layout (default `flow`); `fill` lets one child own the surface and
+     * `fill-last` stacks fixed rows above one filling last child.
+     */
     bodyLayout?: DialogSurfaceBodyLayout;
     rootAttributes?: PopoverDialogSurfaceDataAttributes;
     className?: string;
@@ -96,7 +155,7 @@ type PopoverDialogSurfaceProps = PopoverDialogSurfaceName & {
  * dismisses and leaves the page interactive. Use `DialogSurface` with
  * `wa-dialog` when the task must block the page.
  */
-declare function PopoverDialogSurface({ id, children, label, labelledBy, presentation, size, preferredWidth, height, maxHeight, viewportGutter, bodyLayout, rootAttributes, className, slot, }: PopoverDialogSurfaceProps): kerfjs.SafeHtml;
+declare function PopoverDialogSurface({ id, children, label, labelledBy, describedBy, presentation, size, preferredWidth, height, maxHeight, viewportGutter, bodyLayout, rootAttributes, className, slot, }: PopoverDialogSurfaceProps): kerfjs.SafeHtml;
 type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
 interface PopupSurfaceProps {
     children: KerfUiContent;
@@ -108,4 +167,4 @@ interface PopupSurfaceProps {
 /** Configure recurring Web Awesome dropdown-menu geometry without consumer ::part() CSS. */
 declare function PopupSurface({ children, inset, className, slot, }: PopupSurfaceProps): kerfjs.SafeHtml;
 
-export { DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+export { DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceFooterPresentation, type DialogSurfaceHeaderPresentation, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };

package/dist/surface-scaffold.js

@@ -1,4 +1,4 @@
-export { DialogSurface, PopoverDialogSurface, PopupSurface } from './chunk-JYD7G4RG.js';
+export { DialogSurface, PopoverDialogSurface, PopupSurface } from './chunk-PIVY32AE.js';
 
 
 //# sourceMappingURL=surface-scaffold.js.map

package/dist/tab-navigator.d.ts

@@ -1,6 +1,7 @@
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { PaneAppearance } from './pane.js';
+import './scroll-clearance-BikHljTc.js';
 
 interface TabNavigatorTabBase<Id extends string> {
     id: Id;
@@ -52,6 +53,12 @@ interface TabNavigatorTabDotBadge {
 }
 /** One bottom-bar destination: its label, optional icon and badge, and content. */
 type TabNavigatorTab<Id extends string = string> = TabNavigatorTabBase<Id> & (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);
+/**
+ * How a {@link TabNavigator}'s tab bar relates to the active scene: `docked`
+ * below it, or `overlay` laid over its bottom edge on the translucent chrome
+ * material, so the scene's content scrolls visibly beneath the bar.
+ */
+type TabNavigatorBarPresentation = 'docked' | 'overlay';
 interface TabNavigatorProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
@@ -76,6 +83,20 @@ interface TabNavigatorProps<Id extends string = string> {
      * is the bar's own 1px top border, so no state moves the bar or a tab.
      */
     chromeDividers?: 'scroll' | 'always' | 'none';
+    /**
+     * `docked` (default) gives the tab bar its own band below the scenes.
+     * `overlay` lays it over the active scene's bottom edge on the translucent
+     * chrome material (opaque under reduced transparency, increased contrast,
+     * or without `backdrop-filter`; `Canvas` in forced colors), so content
+     * scrolls visibly beneath it, as under an iOS tab bar. `wireTabNavigator`
+     * measures the live bar (bottom safe area included) and the scenes hand
+     * its height to their content as the block-end `--kui-edge-inset-*`
+     * context, so a plain scene, a sole `Pane`, or a `NavStack` (and its own
+     * bottom toolbar, which then sits above the bar) rests its last item clear
+     * of it. Until then it stays docked. Unselected tab labels lift halfway
+     * toward the normal text color to keep AA over the content beneath.
+     */
+    barPresentation?: TabNavigatorBarPresentation;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -88,6 +109,6 @@ interface TabNavigatorProps<Id extends string = string> {
  * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
  * a bottom bar. See `docs/23-app-layouts.md` §3.4.
  */
-declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, barPresentation, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
 
-export { TabNavigator, type TabNavigatorProps, type TabNavigatorTab };
+export { TabNavigator, type TabNavigatorBarPresentation, type TabNavigatorProps, type TabNavigatorTab };

package/dist/tab-navigator.js

@@ -10,6 +10,7 @@ function TabNavigator({
   active,
   separator = "auto",
   chromeDividers = "scroll",
+  barPresentation = "docked",
   className = "",
   slot
 }) {
@@ -23,6 +24,7 @@ function TabNavigator({
       "data-tab-scaffold-id": id,
       "data-separator": separator,
       "data-chrome-dividers": chromeDividers === "always" || chromeDividers === "none" ? chromeDividers : void 0,
+      "data-bar-presentation": barPresentation === "overlay" ? "overlay" : void 0,
       slot,
       children: [
         /* @__PURE__ */ jsx("div", { class: "kui-tab-scaffold__scenes", children: tabs.map((tab) => /* @__PURE__ */ jsx(

package/dist/tab-navigator.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/navigation/tab-navigator/tab-navigator.tsx"],"names":[],"mappings":"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","file":"tab-navigator.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport { ensureSunkenTexture } from '../../../shared/styles/sunken-texture.js';\nimport { Badge } from '../../feedback/badge/badge.js';\nimport type { PaneAppearance } from '../../layout/pane/pane.js';\n\ninterface TabNavigatorTabBase<Id extends string> {\n  id: Id;\n  label: string;\n  /** Decorative icon shown above the label in the bottom bar. */\n  icon?: SafeHtml;\n  /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */\n  content: KerfUiContent;\n  /** Background of this scene's scrolling work surface. */\n  appearance?: PaneAppearance;\n  /** Add 8px to every side of a plain scene's scrolling content. */\n  deepInset?: boolean;\n  /** Opt into keyboard (`0`) or programmatic (`-1`) focus on this scene. */\n  tabIndex?: 0 | -1;\n  /** Keep the standard focus outline visible while this scene is active. */\n  outlined?: boolean;\n}\n\n/** A tab with an optional count or short-status badge. */\ninterface TabNavigatorTabCountBadge {\n  /**\n   * Optional count or short status shown as a solid danger `Badge` at the\n   * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,\n   * or non-finite numbers render no badge. The visual badge is `aria-hidden`;\n   * its meaning reaches assistive technology through `badgeLabel`.\n   *\n   * Pass `true` instead for the text-free dot (new content without a count).\n   */\n  badge?: string | number;\n  /**\n   * Localized phrase folded into the tab's accessible name as\n   * `\"<label>, <badgeLabel>\"` (for example `\"3 unread\"` → `\"Inbox, 3 unread\"`).\n   * Defaults to the badge text itself. Ignored when no badge renders.\n   */\n  badgeLabel?: string;\n}\n\n/** A tab with the text-free dot badge (new content without a count). */\ninterface TabNavigatorTabDotBadge {\n  /**\n   * `true` shows a solid danger dot `Badge` at the top-trailing corner of the\n   * tab icon — the iOS tab-bar dot for new content without a count.\n   */\n  badge: true;\n  /**\n   * Required localized phrase folded into the tab's accessible name as\n   * `\"<label>, <badgeLabel>\"` (for example `\"New activity\"` →\n   * `\"Feed, New activity\"`). A dot has no text, so this is its only meaning.\n   */\n  badgeLabel: string;\n}\n\n/** One bottom-bar destination: its label, optional icon and badge, and content. */\nexport type TabNavigatorTab<Id extends string = string> =\n  TabNavigatorTabBase<Id> &\n    (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);\n\nexport interface TabNavigatorProps<Id extends string = string> {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: readonly TabNavigatorTab<Id>[];\n  /** The controlled active tab id (the app owns selection). */\n  active: NoInfer<Id>;\n  /**\n   * The bar's top separator. `auto` (default) draws it against a sunken active\n   * work surface and otherwise follows `chromeDividers`; `hidden` suppresses\n   * the line, including a scroll divider.\n   */\n  separator?: 'auto' | 'hidden';\n  /**\n   * The line over the tab bar, where it meets the active scene. `scroll`\n   * (default) shows it only while more of the scene's content lies below —\n   * never at the scroll end or when the content fits — once\n   * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above\n   * the scaffold; unwired, it does not show. `always` shows it without the\n   * wiring; `none` suppresses that scroll divider. A sunken active work\n   * surface still draws the separator unless `separator=\"hidden\"`. The line\n   * is the bar's own 1px top border, so no state moves the bar or a tab.\n   */\n  chromeDividers?: 'scroll' | 'always' | 'none';\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/**\n * A mobile-first, iOS-like bottom tab navigator: a bottom tab bar that switches\n * between major sections, each tab keeping its own content (usually a `NavStack`)\n * mounted so its stack and scroll survive a switch. Controlled — the app owns\n * `active`; wire selection with `@kerfjs/ui/wire-tab-navigator`'s `wireTabNavigator`.\n * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of\n * a bottom bar. See `docs/23-app-layouts.md` §3.4.\n */\nexport function TabNavigator<Id extends string>({\n  id,\n  label,\n  tabs,\n  active,\n  separator = 'auto',\n  chromeDividers = 'scroll',\n  className = '',\n  slot,\n}: TabNavigatorProps<Id>) {\n  if (tabs.some((tab) => tab.appearance === 'sunken')) ensureSunkenTexture();\n  return (\n    <section\n      class={`kui-tab-scaffold ${className}`.trim()}\n      id={id}\n      data-component=\"tab-scaffold\"\n      data-tab-scaffold-id={id}\n      data-separator={separator}\n      data-chrome-dividers={\n        chromeDividers === 'always' || chromeDividers === 'none'\n          ? chromeDividers\n          : undefined\n      }\n      slot={slot}\n    >\n      <div class=\"kui-tab-scaffold__scenes\">\n        {tabs.map((tab) => (\n          <div\n            class=\"kui-tab-scaffold__scene\"\n            data-tab-scaffold-scene={tab.id}\n            data-active={String(tab.id === active)}\n            data-appearance={tab.appearance === 'sunken' ? 'sunken' : undefined}\n            data-deep-inset={tab.deepInset ? 'true' : undefined}\n            data-outlined={\n              tab.id === active && tab.outlined ? 'true' : undefined\n            }\n            role={tab.tabIndex === undefined ? undefined : 'tabpanel'}\n            aria-label={tab.tabIndex === undefined ? undefined : tab.label}\n            aria-hidden={String(tab.id !== active)}\n            tabindex={\n              tab.id === active\n                ? tab.tabIndex\n                : tab.tabIndex === undefined\n                  ? undefined\n                  : -1\n            }\n          >\n            {tab.content}\n          </div>\n        ))}\n      </div>\n      <nav class=\"kui-tab-scaffold__bar\" role=\"tablist\" aria-label={label}>\n        {tabs.map((tab) => {\n          const dot = tab.badge === true;\n          const badgeText = dot ? undefined : normalizeBadge(tab.badge);\n          const hasBadge = dot || badgeText !== undefined;\n          const badge = hasBadge && (\n            <span\n              class=\"kui-tab-scaffold__tab-badge\"\n              data-badge-kind={dot ? 'dot' : 'text'}\n            >\n              {badgeText === undefined ? (\n                <Badge tone=\"danger\" size=\"dot\" ariaHidden />\n              ) : (\n                <Badge\n                  tone=\"danger\"\n                  appearance=\"solid\"\n                  size=\"compact\"\n                  ariaHidden\n                >\n                  {badgeText}\n                </Badge>\n              )}\n            </span>\n          );\n          // A dot has no text fallback: without a usable badgeLabel (reachable\n          // only from untyped callers) the tab keeps its plain accessible name.\n          const badgeLabel = hasBadge\n            ? tab.badgeLabel?.trim() || badgeText\n            : undefined;\n          return (\n            <button\n              type=\"button\"\n              class=\"kui-tab-scaffold__tab\"\n              role=\"tab\"\n              data-tab-scaffold-tab={tab.id}\n              aria-selected={String(tab.id === active)}\n              tabindex={tab.id === active ? '0' : '-1'}\n              aria-label={\n                badgeLabel === undefined\n                  ? undefined\n                  : `${tab.label}, ${badgeLabel}`\n              }\n              data-has-badge={hasBadge ? 'true' : undefined}\n            >\n              {tab.icon ? (\n                <span class=\"kui-tab-scaffold__tab-icon\" aria-hidden=\"true\">\n                  {tab.icon}\n                  {badge}\n                </span>\n              ) : (\n                badge\n              )}\n              <span class=\"kui-tab-scaffold__tab-label\">{tab.label}</span>\n            </button>\n          );\n        })}\n      </nav>\n    </section>\n  );\n}\n\nfunction normalizeBadge(\n  badge: string | number | undefined,\n): string | undefined {\n  if (typeof badge === 'number')\n    return Number.isFinite(badge) ? String(badge) : undefined;\n  if (typeof badge === 'string' && badge.trim()) return badge.trim();\n  return undefined;\n}\n"]}
+{"version":3,"sources":["../src/components/navigation/tab-navigator/tab-navigator.tsx"],"names":[],"mappings":"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","file":"tab-navigator.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport { ensureSunkenTexture } from '../../../shared/styles/sunken-texture.js';\nimport { Badge } from '../../feedback/badge/badge.js';\nimport type { PaneAppearance } from '../../layout/pane/pane.js';\n\ninterface TabNavigatorTabBase<Id extends string> {\n  id: Id;\n  label: string;\n  /** Decorative icon shown above the label in the bottom bar. */\n  icon?: SafeHtml;\n  /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */\n  content: KerfUiContent;\n  /** Background of this scene's scrolling work surface. */\n  appearance?: PaneAppearance;\n  /** Add 8px to every side of a plain scene's scrolling content. */\n  deepInset?: boolean;\n  /** Opt into keyboard (`0`) or programmatic (`-1`) focus on this scene. */\n  tabIndex?: 0 | -1;\n  /** Keep the standard focus outline visible while this scene is active. */\n  outlined?: boolean;\n}\n\n/** A tab with an optional count or short-status badge. */\ninterface TabNavigatorTabCountBadge {\n  /**\n   * Optional count or short status shown as a solid danger `Badge` at the\n   * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,\n   * or non-finite numbers render no badge. The visual badge is `aria-hidden`;\n   * its meaning reaches assistive technology through `badgeLabel`.\n   *\n   * Pass `true` instead for the text-free dot (new content without a count).\n   */\n  badge?: string | number;\n  /**\n   * Localized phrase folded into the tab's accessible name as\n   * `\"<label>, <badgeLabel>\"` (for example `\"3 unread\"` → `\"Inbox, 3 unread\"`).\n   * Defaults to the badge text itself. Ignored when no badge renders.\n   */\n  badgeLabel?: string;\n}\n\n/** A tab with the text-free dot badge (new content without a count). */\ninterface TabNavigatorTabDotBadge {\n  /**\n   * `true` shows a solid danger dot `Badge` at the top-trailing corner of the\n   * tab icon — the iOS tab-bar dot for new content without a count.\n   */\n  badge: true;\n  /**\n   * Required localized phrase folded into the tab's accessible name as\n   * `\"<label>, <badgeLabel>\"` (for example `\"New activity\"` →\n   * `\"Feed, New activity\"`). A dot has no text, so this is its only meaning.\n   */\n  badgeLabel: string;\n}\n\n/** One bottom-bar destination: its label, optional icon and badge, and content. */\nexport type TabNavigatorTab<Id extends string = string> =\n  TabNavigatorTabBase<Id> &\n    (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);\n\n/**\n * How a {@link TabNavigator}'s tab bar relates to the active scene: `docked`\n * below it, or `overlay` laid over its bottom edge on the translucent chrome\n * material, so the scene's content scrolls visibly beneath the bar.\n */\nexport type TabNavigatorBarPresentation = 'docked' | 'overlay';\n\nexport interface TabNavigatorProps<Id extends string = string> {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: readonly TabNavigatorTab<Id>[];\n  /** The controlled active tab id (the app owns selection). */\n  active: NoInfer<Id>;\n  /**\n   * The bar's top separator. `auto` (default) draws it against a sunken active\n   * work surface and otherwise follows `chromeDividers`; `hidden` suppresses\n   * the line, including a scroll divider.\n   */\n  separator?: 'auto' | 'hidden';\n  /**\n   * The line over the tab bar, where it meets the active scene. `scroll`\n   * (default) shows it only while more of the scene's content lies below —\n   * never at the scroll end or when the content fits — once\n   * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above\n   * the scaffold; unwired, it does not show. `always` shows it without the\n   * wiring; `none` suppresses that scroll divider. A sunken active work\n   * surface still draws the separator unless `separator=\"hidden\"`. The line\n   * is the bar's own 1px top border, so no state moves the bar or a tab.\n   */\n  chromeDividers?: 'scroll' | 'always' | 'none';\n  /**\n   * `docked` (default) gives the tab bar its own band below the scenes.\n   * `overlay` lays it over the active scene's bottom edge on the translucent\n   * chrome material (opaque under reduced transparency, increased contrast,\n   * or without `backdrop-filter`; `Canvas` in forced colors), so content\n   * scrolls visibly beneath it, as under an iOS tab bar. `wireTabNavigator`\n   * measures the live bar (bottom safe area included) and the scenes hand\n   * its height to their content as the block-end `--kui-edge-inset-*`\n   * context, so a plain scene, a sole `Pane`, or a `NavStack` (and its own\n   * bottom toolbar, which then sits above the bar) rests its last item clear\n   * of it. Until then it stays docked. Unselected tab labels lift halfway\n   * toward the normal text color to keep AA over the content beneath.\n   */\n  barPresentation?: TabNavigatorBarPresentation;\n  className?: string;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\n/**\n * A mobile-first, iOS-like bottom tab navigator: a bottom tab bar that switches\n * between major sections, each tab keeping its own content (usually a `NavStack`)\n * mounted so its stack and scroll survive a switch. Controlled — the app owns\n * `active`; wire selection with `@kerfjs/ui/wire-tab-navigator`'s `wireTabNavigator`.\n * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of\n * a bottom bar. See `docs/23-app-layouts.md` §3.4.\n */\nexport function TabNavigator<Id extends string>({\n  id,\n  label,\n  tabs,\n  active,\n  separator = 'auto',\n  chromeDividers = 'scroll',\n  barPresentation = 'docked',\n  className = '',\n  slot,\n}: TabNavigatorProps<Id>) {\n  if (tabs.some((tab) => tab.appearance === 'sunken')) ensureSunkenTexture();\n  return (\n    <section\n      class={`kui-tab-scaffold ${className}`.trim()}\n      id={id}\n      data-component=\"tab-scaffold\"\n      data-tab-scaffold-id={id}\n      data-separator={separator}\n      data-chrome-dividers={\n        chromeDividers === 'always' || chromeDividers === 'none'\n          ? chromeDividers\n          : undefined\n      }\n      data-bar-presentation={\n        barPresentation === 'overlay' ? 'overlay' : undefined\n      }\n      slot={slot}\n    >\n      <div class=\"kui-tab-scaffold__scenes\">\n        {tabs.map((tab) => (\n          <div\n            class=\"kui-tab-scaffold__scene\"\n            data-tab-scaffold-scene={tab.id}\n            data-active={String(tab.id === active)}\n            data-appearance={tab.appearance === 'sunken' ? 'sunken' : undefined}\n            data-deep-inset={tab.deepInset ? 'true' : undefined}\n            data-outlined={\n              tab.id === active && tab.outlined ? 'true' : undefined\n            }\n            role={tab.tabIndex === undefined ? undefined : 'tabpanel'}\n            aria-label={tab.tabIndex === undefined ? undefined : tab.label}\n            aria-hidden={String(tab.id !== active)}\n            tabindex={\n              tab.id === active\n                ? tab.tabIndex\n                : tab.tabIndex === undefined\n                  ? undefined\n                  : -1\n            }\n          >\n            {tab.content}\n          </div>\n        ))}\n      </div>\n      <nav class=\"kui-tab-scaffold__bar\" role=\"tablist\" aria-label={label}>\n        {tabs.map((tab) => {\n          const dot = tab.badge === true;\n          const badgeText = dot ? undefined : normalizeBadge(tab.badge);\n          const hasBadge = dot || badgeText !== undefined;\n          const badge = hasBadge && (\n            <span\n              class=\"kui-tab-scaffold__tab-badge\"\n              data-badge-kind={dot ? 'dot' : 'text'}\n            >\n              {badgeText === undefined ? (\n                <Badge tone=\"danger\" size=\"dot\" ariaHidden />\n              ) : (\n                <Badge\n                  tone=\"danger\"\n                  appearance=\"solid\"\n                  size=\"compact\"\n                  ariaHidden\n                >\n                  {badgeText}\n                </Badge>\n              )}\n            </span>\n          );\n          // A dot has no text fallback: without a usable badgeLabel (reachable\n          // only from untyped callers) the tab keeps its plain accessible name.\n          const badgeLabel = hasBadge\n            ? tab.badgeLabel?.trim() || badgeText\n            : undefined;\n          return (\n            <button\n              type=\"button\"\n              class=\"kui-tab-scaffold__tab\"\n              role=\"tab\"\n              data-tab-scaffold-tab={tab.id}\n              aria-selected={String(tab.id === active)}\n              tabindex={tab.id === active ? '0' : '-1'}\n              aria-label={\n                badgeLabel === undefined\n                  ? undefined\n                  : `${tab.label}, ${badgeLabel}`\n              }\n              data-has-badge={hasBadge ? 'true' : undefined}\n            >\n              {tab.icon ? (\n                <span class=\"kui-tab-scaffold__tab-icon\" aria-hidden=\"true\">\n                  {tab.icon}\n                  {badge}\n                </span>\n              ) : (\n                badge\n              )}\n              <span class=\"kui-tab-scaffold__tab-label\">{tab.label}</span>\n            </button>\n          );\n        })}\n      </nav>\n    </section>\n  );\n}\n\nfunction normalizeBadge(\n  badge: string | number | undefined,\n): string | undefined {\n  if (typeof badge === 'number')\n    return Number.isFinite(badge) ? String(badge) : undefined;\n  if (typeof badge === 'string' && badge.trim()) return badge.trim();\n  return undefined;\n}\n"]}

package/dist/token-search-field.d.ts

@@ -1,3 +1,3 @@
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-DTcTXWMS.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, l as TokenSearchTrailingActionAttributes, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-aYR0YAei.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';

package/dist/token-search-field.js

@@ -1,4 +1,4 @@
-export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-ROZLJULF.js';
+export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-MF6ZUUJZ.js';
 
 
 

package/dist/{token-search-model-DTcTXWMS.d.ts → token-search-model-aYR0YAei.d.ts}

@@ -7,12 +7,42 @@ interface TokenSearchToken {
     offset?: number;
     accessibleLabel?: string;
 }
-interface TokenSearchTrailingAction {
+/**
+ * Domain `data-*` metadata for a trailing action button. The component owns
+ * `data-action` (pass `action`) and its state attributes.
+ */
+type TokenSearchTrailingActionAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-action'?: never;
+    'data-component'?: never;
+    'data-key'?: never;
+}>;
+interface TokenSearchTrailingActionBase {
+    /** Decorative glyph, such as a `LucideIcon`. */
     icon: SafeHtml;
+    /** Accessible name and tooltip, in title style ("Search Help"). */
     label: string;
+    /** Delegated `data-action` value. */
     action: string;
     id?: string;
+    /** `aria-controls`: the id of the surface this button opens or toggles. */
+    controls?: string;
+    /** `aria-haspopup` for a button that opens a dialog, menu, or listbox. */
+    haspopup?: 'dialog' | 'menu' | 'listbox' | 'true';
+    /** Domain `data-*` metadata for the app's delegated handler. */
+    attributes?: TokenSearchTrailingActionAttributes;
 }
+/**
+ * A compact icon button in the field's trailing slot, sized and styled like
+ * the clear button. Pass `expanded` for a disclosure (a help surface it opens)
+ * or `pressed` for a toggle; the button shows the state with its hover fill.
+ */
+type TokenSearchTrailingAction = TokenSearchTrailingActionBase & ({
+    expanded?: boolean;
+    pressed?: never;
+} | {
+    expanded?: never;
+    pressed?: boolean;
+});
 type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-key'?: never;
@@ -151,4 +181,4 @@ interface TokenSearchModelOptions<Result> {
 /** Opt-in state, token parsing, suggestions, and evaluation for TokenSearchField. */
 declare function createTokenSearchModel<Result = unknown>({ rules, initial, evaluate, onSubmit, }?: TokenSearchModelOptions<Result>): TokenSearchModel<Result>;
 
-export { type TokenSearchEditorAttributes as T, TokenSearchField as a, type TokenSearchFieldProps as b, type TokenSearchFieldValue as c, type TokenSearchModel as d, type TokenSearchModelOptions as e, type TokenSearchResolvedToken as f, type TokenSearchRule as g, type TokenSearchState as h, type TokenSearchSuggestion as i, type TokenSearchToken as j, type TokenSearchTrailingAction as k, createTokenSearchModel as l, placeTokenSearchCaret as p, readTokenSearchField as r };
+export { type TokenSearchEditorAttributes as T, TokenSearchField as a, type TokenSearchFieldProps as b, type TokenSearchFieldValue as c, type TokenSearchModel as d, type TokenSearchModelOptions as e, type TokenSearchResolvedToken as f, type TokenSearchRule as g, type TokenSearchState as h, type TokenSearchSuggestion as i, type TokenSearchToken as j, type TokenSearchTrailingAction as k, type TokenSearchTrailingActionAttributes as l, createTokenSearchModel as m, placeTokenSearchCaret as p, readTokenSearchField as r };

package/dist/token-search-model.d.ts

@@ -1,3 +1,3 @@
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-model-DTcTXWMS.js';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, m as createTokenSearchModel } from './token-search-model-aYR0YAei.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';

package/dist/toolbar-control-group.js

@@ -1,4 +1,4 @@
-export { ToolbarActionLink, ToolbarControlGroup } from './chunk-YXOMI7ES.js';
+export { ToolbarActionLink, ToolbarControlGroup } from './chunk-QIG4IGUP.js';
 
 
 

package/dist/toolbar-text.js

@@ -1,4 +1,4 @@
-export { ToolbarText } from './chunk-IGTWXPTN.js';
+export { ToolbarText } from './chunk-HGV7J4T6.js';
 
 
 

package/dist/toolbar.d.ts

@@ -2,6 +2,7 @@ import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 import { PaneSeparatorSide } from './pane.js';
+import './scroll-clearance-BikHljTc.js';
 
 type ToolbarPosition = 'header' | 'footer';
 /** Control-band density: `default` (60px with 44px groups) or `compact`. */

package/dist/value-table.js

@@ -1,4 +1,4 @@
-export { ValueTable, ValueTableRow } from './chunk-GZE2XVKC.js';
+export { ValueTable, ValueTableRow } from './chunk-DZJ4GBSP.js';
 
 
 

package/dist/wire-catalog.d.ts

@@ -4,13 +4,14 @@ import './toolbar.js';
 import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
+import './scroll-clearance-BikHljTc.js';
 import './workbench.js';
-import './nav-stack-BvSKY448.js';
+import './nav-stack-VXTumzKa.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
-import './panel-toolbar-CL9tYOkh.js';
+import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
 import './toolbar-text.js';

package/dist/wire-catalog.js

@@ -1,9 +1,9 @@
 import { wireWorkbench } from './chunk-QLA25V2K.js';
+import { wireScrollDividers } from './chunk-CXZXHZTR.js';
 
-import { wireScrollDividers } from './chunk-6STQXRT4.js';
 import { loadUxReviewProject } from './chunk-6C6DLP3W.js';
 
-import { readTokenSearchField } from './chunk-ROZLJULF.js';
+import { readTokenSearchField } from './chunk-MF6ZUUJZ.js';
 
 
 

package/dist/wire-composers.d.ts

@@ -0,0 +1,16 @@
+type Root = HTMLElement | Document;
+/**
+ * Enter-to-send for every `Composer` rendered with `submitOnEnter` below
+ * root. In its field, Enter (alone or with Cmd or Ctrl) activates the
+ * composer's first trailing action, so a keyboard send runs the same
+ * delegated handler as a click. Shift+Enter and Alt+Enter insert a newline.
+ * Nothing is sent, and no newline is inserted, when the message is empty or
+ * whitespace-only, the key is auto-repeating, or the first action is
+ * disabled, loading, or `aria-disabled`. An Enter that commits an IME
+ * composition (`isComposing`, keyCode 229, or between `compositionstart` and
+ * `compositionend`) is left to the input method. Dispose with the owning
+ * application.
+ */
+declare function wireComposers(root: Root): () => void;
+
+export { wireComposers };

package/dist/wire-composers.js

@@ -0,0 +1,3 @@
+export { wireComposers } from './chunk-ELCMSQNJ.js';
+
+//# sourceMappingURL=wire-composers.js.map

package/dist/wire-composers.js.map

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

package/dist/wire-list-focus-scroll.d.ts

@@ -0,0 +1,16 @@
+type Root = HTMLElement | Document;
+/**
+ * Bring a keyboard-focused row of a `scrollable` List below `root` fully into
+ * view, focus ring included. Engines differ on how `focus()` scrolls a partly
+ * hidden row: Chromium scrolls it to the nearest edge plus scroll padding,
+ * Firefox waits until about half of it is hidden and then centers it, and
+ * WebKit leaves it where it is. On `focusin`, when the newly focused element
+ * matches `:focus-visible` and its ring crosses the nearest scrollable List's
+ * clip, this calls `scrollIntoView({ block: 'nearest', inline: 'nearest' })`,
+ * which honors the List's ring-room scroll padding in every engine. Pointer
+ * focus is left alone, so a click never scrolls the row out from under the
+ * pointer. Returns a disposer.
+ */
+declare function wireListFocusScroll(root: Root): () => void;
+
+export { wireListFocusScroll };

package/dist/wire-list-focus-scroll.js

@@ -0,0 +1,3 @@
+export { wireListFocusScroll } from './chunk-QDSZTQXL.js';
+
+//# sourceMappingURL=wire-list-focus-scroll.js.map

package/dist/wire-list-focus-scroll.js.map

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

package/dist/wire-nav-stack.js

@@ -2,6 +2,27 @@ import { delegate } from 'kerfjs';
 
 // src/components/navigation/nav-stack/wiring/wire-nav-stack.ts
 var DEFAULT_DURATION = 200;
+var CHROME_OVERLAY = "data-chrome-overlay";
+var BOTTOM_TOOLBAR_OVERLAY = "data-bottom-toolbar-overlay";
+var OVERLAY_EDGES = [
+  {
+    presentation: "data-chrome-presentation",
+    element: ":scope > [data-nav-stack-chrome]:not([data-nav-chrome-copy])",
+    blockSize: "--_kui-nav-stack-chrome-block-size",
+    scrollbarInlineSize: "--_kui-nav-stack-scrollbar-inline-size",
+    // A Pane header lies beneath the chrome and starts its content below it.
+    paneChrome: ":scope > :is(.kui-pane__header, .kui-pane__toolbar)"
+  },
+  {
+    presentation: "data-bottom-toolbar-presentation",
+    element: ":scope > [data-nav-stack-bottom]:not([data-nav-chrome-copy])",
+    blockSize: "--_kui-nav-stack-bottom-block-size",
+    scrollbarInlineSize: "--_kui-nav-stack-bottom-scrollbar-inline-size",
+    // A Pane footer lies beneath the toolbar and ends its content above it.
+    paneChrome: ":scope > .kui-pane__footer"
+  }
+];
+var NESTED_LAYOUT = ["nav-stack", "split-view", "workbench", "tab-scaffold"].map((name) => `[data-component="${name}"]`).join(", ");
 var FOCUSABLE_SELECTOR = [
   "a[href]",
   "button:not([disabled])",
@@ -144,6 +165,109 @@ function wireNavStack(root, options = {}) {
     }
     targetView.focus({ preventScroll: true });
   };
+  const edges = OVERLAY_EDGES.map((edge) => [
+    edge,
+    { covers: false }
+  ]);
+  const measuredEdge = (state) => state.element !== void 0 && state.size !== void 0;
+  let measuredScroller;
+  let scrollbarSize = 0;
+  const writeProperty = (name, value) => {
+    if (section.style.getPropertyValue(name) === value) return;
+    if (value) section.style.setProperty(name, value);
+    else section.style.removeProperty(name);
+  };
+  const publishOverlay = () => {
+    for (const [edge, state] of edges) {
+      const measured = measuredEdge(state);
+      writeProperty(edge.blockSize, measured ? `${state.size}px` : "");
+      writeProperty(
+        edge.scrollbarInlineSize,
+        measured && state.covers && scrollbarSize > 0 ? `${scrollbarSize}px` : ""
+      );
+    }
+    if (section.getAttribute("style") === "") section.removeAttribute("style");
+    const [top, bottom] = edges.map(([, state]) => measuredEdge(state));
+    if (top && section.getAttribute(CHROME_OVERLAY) !== "measured")
+      section.setAttribute(CHROME_OVERLAY, "measured");
+    else if (!top && section.hasAttribute(CHROME_OVERLAY))
+      section.removeAttribute(CHROME_OVERLAY);
+    if (bottom && section.getAttribute(BOTTOM_TOOLBAR_OVERLAY) !== "measured")
+      section.setAttribute(BOTTOM_TOOLBAR_OVERLAY, "measured");
+    else if (!bottom && section.hasAttribute(BOTTOM_TOOLBAR_OVERLAY))
+      section.removeAttribute(BOTTOM_TOOLBAR_OVERLAY);
+  };
+  const activeScroller = () => {
+    const top = topView(viewport);
+    const only = top?.children.length === 1 ? top.children[0] : void 0;
+    if (!only) return { scroller: top };
+    if (only.matches(".kui-pane"))
+      return {
+        scroller: only.querySelector(":scope > .kui-pane__content") ?? void 0,
+        pane: only
+      };
+    return { scroller: only.matches(NESTED_LAYOUT) ? void 0 : top };
+  };
+  const measureScrollbar = () => {
+    const scroller = measuredScroller;
+    if (!scroller) {
+      scrollbarSize = 0;
+      return;
+    }
+    const style = view.getComputedStyle(scroller);
+    scrollbarSize = Math.max(
+      0,
+      scroller.offsetWidth - scroller.clientWidth - (Number.parseFloat(style.borderLeftWidth) || 0) - (Number.parseFloat(style.borderRightWidth) || 0)
+    );
+  };
+  const chromeObserver = view.ResizeObserver ? new view.ResizeObserver((entries) => {
+    for (const entry of entries) {
+      const state = edges.find(
+        ([, edgeState]) => edgeState.element === entry.target
+      )?.[1];
+      if (state)
+        state.size = entry.borderBoxSize?.[0]?.blockSize ?? entry.target.getBoundingClientRect().height;
+      else if (entry.target === measuredScroller) measureScrollbar();
+    }
+    publishOverlay();
+  }) : void 0;
+  const syncOverlay = () => {
+    for (const [edge, state] of edges) {
+      const element = section.getAttribute(edge.presentation) === "overlay" ? section.querySelector(edge.element) ?? void 0 : void 0;
+      if (element === state.element) continue;
+      if (state.element) chromeObserver?.unobserve(state.element);
+      state.element = element;
+      if (!element) state.size = void 0;
+      else {
+        if (state.size === void 0 || !chromeObserver)
+          state.size = element.getBoundingClientRect().height;
+        chromeObserver?.observe(element, { box: "border-box" });
+      }
+    }
+    const { scroller, pane } = activeScroller();
+    for (const [edge, state] of edges)
+      state.covers = state.element !== void 0 && scroller !== void 0 && !pane?.querySelector(edge.paneChrome);
+    const covered = edges.some(([, state]) => state.covers) ? scroller : void 0;
+    if (covered !== measuredScroller) {
+      if (measuredScroller) chromeObserver?.unobserve(measuredScroller);
+      measuredScroller = covered;
+      measureScrollbar();
+      if (measuredScroller) chromeObserver?.observe(measuredScroller);
+    }
+    publishOverlay();
+  };
+  const overlayObserver = new MutationObserver(syncOverlay);
+  overlayObserver.observe(section, {
+    childList: true,
+    attributes: true,
+    attributeFilter: [
+      ...OVERLAY_EDGES.map((edge) => edge.presentation),
+      CHROME_OVERLAY,
+      BOTTOM_TOOLBAR_OVERLAY,
+      "style"
+    ]
+  });
+  syncOverlay();
   const onFocusIn = (event) => rememberFocusedView(event.target);
   section.addEventListener("focusin", onFocusIn);
   rememberFocusedView(section.ownerDocument.activeElement);
@@ -231,6 +355,7 @@ function wireNavStack(root, options = {}) {
       focusInto(top);
     }
     activeKey = currentKey;
+    syncOverlay();
   });
   observer.observe(viewport, {
     childList: true,
@@ -242,6 +367,16 @@ function wireNavStack(root, options = {}) {
     disposeBack();
     section.removeEventListener("focusin", onFocusIn);
     observer.disconnect();
+    overlayObserver.disconnect();
+    chromeObserver?.disconnect();
+    for (const [, state] of edges) {
+      state.element = void 0;
+      state.size = void 0;
+      state.covers = false;
+    }
+    measuredScroller = void 0;
+    scrollbarSize = 0;
+    publishOverlay();
     finishTransition();
     for (const [element, previousTabIndex] of generatedFallbacks) {
       if (!element.isConnected || element.tabIndex !== -1) continue;