@kerfjs/ui 5.0.0-beta.77 → 5.0.0-beta.79

package/dist/surface-scaffold-register.js

@@ -0,0 +1,59 @@
+import WaDialog from '@awesome.me/webawesome/dist/components/dialog/dialog.js';
+
+// src/components/surfaces/surface-scaffold/register/surface-scaffold-register.ts
+
+// src/components/surfaces/surface-scaffold/internal/install-dialog-label.ts
+var installed = /* @__PURE__ */ new WeakSet();
+var observed = /* @__PURE__ */ new WeakSet();
+var ownedNames = /* @__PURE__ */ new WeakMap();
+function installDialogLabel(prototype) {
+  if (installed.has(prototype)) return;
+  installed.add(prototype);
+  const target = prototype;
+  const update = target.update;
+  target.update = function(changed) {
+    update.call(this, changed);
+    if (!this.parentElement?.classList.contains("kui-dialog-surface")) return;
+    if (!observed.has(this)) {
+      observed.add(this);
+      new MutationObserver(() => syncDialogLabel(this)).observe(this, {
+        attributes: true,
+        attributeFilter: ["aria-label"]
+      });
+    }
+    syncDialogLabel(this);
+  };
+}
+function syncDialogLabel(host) {
+  if (!host.parentElement?.classList.contains("kui-dialog-surface")) return;
+  const panel = host.dialog;
+  if (!panel) return;
+  const previous = ownedNames.get(panel);
+  const externalName = ["aria-label", "aria-labelledby"].some((attribute2) => {
+    const value2 = panel.getAttribute(attribute2);
+    return value2 !== null && !(previous?.attribute === attribute2 && previous.value === value2);
+  });
+  if (externalName) {
+    if (previous && panel.getAttribute(previous.attribute) === previous.value)
+      panel.removeAttribute(previous.attribute);
+    ownedNames.delete(panel);
+    return;
+  }
+  const explicit = host.getAttribute("aria-label")?.trim();
+  const title = host.shadowRoot?.getElementById("title");
+  const attribute = !explicit && !host.withoutHeader && title ? "aria-labelledby" : "aria-label";
+  const value = attribute === "aria-labelledby" ? "title" : explicit || host.label;
+  if (previous && previous.attribute !== attribute)
+    panel.removeAttribute(previous.attribute);
+  if (panel.getAttribute(attribute) !== value)
+    panel.setAttribute(attribute, value);
+  ownedNames.set(panel, { attribute, value });
+}
+
+// src/components/surfaces/surface-scaffold/register/surface-scaffold-register.ts
+installDialogLabel(WaDialog.prototype);
+var surfaceScaffoldElementsRegistered = true;
+
+export { surfaceScaffoldElementsRegistered };
+
+//# sourceMappingURL=surface-scaffold-register.js.map

package/dist/surface-scaffold-register.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/surfaces/surface-scaffold/internal/install-dialog-label.ts","../src/components/surfaces/surface-scaffold/register/surface-scaffold-register.ts"],"names":["attribute","value"],"mappings":"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","file":"surface-scaffold-register.js","sourcesContent":["interface NamedDialog extends HTMLElement {\n  dialog?: HTMLDialogElement;\n  label: string;\n  withoutHeader: boolean;\n  update(changed: unknown): void;\n}\n\nconst installed = new WeakSet<object>();\nconst observed = new WeakSet<HTMLElement>();\nconst ownedNames = new WeakMap<\n  HTMLElement,\n  { attribute: string; value: string }\n>();\n\n/** Repair Web Awesome's missing native dialog name before its first modal open. */\nexport function installDialogLabel(prototype: object): void {\n  if (installed.has(prototype)) return;\n  installed.add(prototype);\n  const target = prototype as NamedDialog;\n  const update = target.update;\n  target.update = function (this: NamedDialog, changed: unknown): void {\n    update.call(this, changed);\n    if (!this.parentElement?.classList.contains('kui-dialog-surface')) return;\n    if (!observed.has(this)) {\n      observed.add(this);\n      new MutationObserver(() => syncDialogLabel(this)).observe(this, {\n        attributes: true,\n        attributeFilter: ['aria-label'],\n      });\n    }\n    syncDialogLabel(this);\n  };\n}\n\nfunction syncDialogLabel(host: NamedDialog): void {\n  if (!host.parentElement?.classList.contains('kui-dialog-surface')) return;\n  const panel = host.dialog;\n  if (!panel) return;\n  const previous = ownedNames.get(panel);\n  const externalName = ['aria-label', 'aria-labelledby'].some((attribute) => {\n    const value = panel.getAttribute(attribute);\n    return (\n      value !== null &&\n      !(previous?.attribute === attribute && previous.value === value)\n    );\n  });\n  if (externalName) {\n    if (previous && panel.getAttribute(previous.attribute) === previous.value)\n      panel.removeAttribute(previous.attribute);\n    ownedNames.delete(panel);\n    return;\n  }\n  const explicit = host.getAttribute('aria-label')?.trim();\n  const title = host.shadowRoot?.getElementById('title');\n  const attribute =\n    !explicit && !host.withoutHeader && title\n      ? 'aria-labelledby'\n      : 'aria-label';\n  const value =\n    attribute === 'aria-labelledby' ? 'title' : explicit || host.label;\n  if (previous && previous.attribute !== attribute)\n    panel.removeAttribute(previous.attribute);\n  if (panel.getAttribute(attribute) !== value)\n    panel.setAttribute(attribute, value);\n  ownedNames.set(panel, { attribute, value });\n}\n","import WaDialog from '@awesome.me/webawesome/dist/components/dialog/dialog.js';\n\nimport { installDialogLabel } from '../internal/install-dialog-label.js';\n\ninstallDialogLabel(WaDialog.prototype);\n\n/** Importing this module registers wa-dialog and repairs wrapped native names. */\nexport const surfaceScaffoldElementsRegistered = true;\n"]}

package/dist/surface-scaffold.d.ts

@@ -1,21 +1,29 @@
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 type DialogSurfaceSize = 'small' | 'medium' | 'large';
 type DialogSurfacePresentation = 'modal' | 'side-sheet' | 'fullscreen';
 type SurfaceInset = 'none' | 'compact' | 'comfortable';
+type DialogSurfaceMaxHeight = CssLength | 'viewport';
 interface DialogSurfaceProps {
     children: KerfUiContent;
     size?: DialogSurfaceSize;
     presentation?: DialogSurfacePresentation;
+    /** Modal preferred width. Takes precedence over size, within the viewport cap. */
+    preferredWidth?: CssLength;
     bodyInset?: SurfaceInset;
     footerInset?: SurfaceInset;
+    /** Modal edge clearance. Omit to retain Web Awesome's default viewport cap. */
+    viewportGutter?: CssLength;
+    /** Modal height cap, bounded by the dynamic viewport minus both gutters. */
+    maxHeight?: DialogSurfaceMaxHeight;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, bodyInset, footerInset, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
 interface PopupSurfaceProps {
     children: KerfUiContent;
@@ -27,4 +35,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 DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+export { DialogSurface, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };

package/dist/surface-scaffold.js

@@ -1,3 +1,3 @@
-export { DialogSurface, PopupSurface } from './chunk-XIZRXI7N.js';
+export { DialogSurface, PopupSurface } from './chunk-A7DYEERU.js';
 
 //# sourceMappingURL=surface-scaffold.js.map

package/dist/{tab-scaffold.d.ts → tab-navigator.d.ts}

@@ -2,7 +2,7 @@ import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { PaneAppearance } from './pane.js';
 
-interface TabScaffoldTabBase<Id extends string> {
+interface TabNavigatorTabBase<Id extends string> {
     id: Id;
     label: string;
     /** Decorative icon shown above the label in the bottom bar. */
@@ -11,9 +11,11 @@ interface TabScaffoldTabBase<Id extends string> {
     content: KerfUiContent;
     /** Background of this scene's scrolling work surface. */
     appearance?: PaneAppearance;
+    /** Add an extra 8px inline gutter to a plain scene's scrolling content. */
+    deepInset?: boolean;
 }
 /** A tab with an optional count or short-status badge. */
-interface TabScaffoldTabCountBadge {
+interface TabNavigatorTabCountBadge {
     /**
      * Optional count or short status shown as a solid danger `Badge` at the
      * top-trailing corner of the tab icon (the iOS tab-bar badge). Omitted, `''`,
@@ -31,7 +33,7 @@ interface TabScaffoldTabCountBadge {
     badgeLabel?: string;
 }
 /** A tab with the text-free dot badge (new content without a count). */
-interface TabScaffoldTabDotBadge {
+interface TabNavigatorTabDotBadge {
     /**
      * `true` shows a solid danger dot `Badge` at the top-trailing corner of the
      * tab icon — the iOS tab-bar dot for new content without a count.
@@ -45,12 +47,12 @@ interface TabScaffoldTabDotBadge {
     badgeLabel: string;
 }
 /** One bottom-bar destination: its label, optional icon and badge, and content. */
-type TabScaffoldTab<Id extends string = string> = TabScaffoldTabBase<Id> & (TabScaffoldTabCountBadge | TabScaffoldTabDotBadge);
-interface TabScaffoldProps<Id extends string = string> {
+type TabNavigatorTab<Id extends string = string> = TabNavigatorTabBase<Id> & (TabNavigatorTabCountBadge | TabNavigatorTabDotBadge);
+interface TabNavigatorProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
     label: string;
-    tabs: readonly TabScaffoldTab<Id>[];
+    tabs: readonly TabNavigatorTab<Id>[];
     /** The controlled active tab id (the app owns selection). */
     active: NoInfer<Id>;
     /**
@@ -68,13 +70,13 @@ interface TabScaffoldProps<Id extends string = string> {
     slot?: string;
 }
 /**
- * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches
+ * A mobile-first, iOS-like bottom tab navigator: a bottom tab bar that switches
  * between major sections, each tab keeping its own content (usually a `NavStack`)
  * mounted so its stack and scroll survive a switch. Controlled — the app owns
- * `active`; wire selection with `@kerfjs/ui/wire-tab-scaffold`'s `wireTabScaffold`.
+ * `active`; wire selection with `@kerfjs/ui/wire-tab-navigator`'s `wireTabNavigator`.
  * 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 TabScaffold<Id extends string>({ id, label, tabs, active, chromeDividers, className, slot, }: TabScaffoldProps<Id>): SafeHtml;
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
 
-export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
+export { TabNavigator, type TabNavigatorProps, type TabNavigatorTab };

package/dist/{tab-scaffold.js → tab-navigator.js}

@@ -1,7 +1,7 @@
 import { Badge } from './chunk-J3AWE5I4.js';
 import { jsxs, jsx } from 'kerfjs/jsx-runtime';
 
-function TabScaffold({
+function TabNavigator({
   id,
   label,
   tabs,
@@ -27,6 +27,7 @@ function TabScaffold({
             "data-tab-scaffold-scene": tab.id,
             "data-active": String(tab.id === active),
             "data-appearance": tab.appearance === "sunken" ? "sunken" : void 0,
+            "data-deep-inset": tab.deepInset ? "true" : void 0,
             "aria-hidden": String(tab.id !== active),
             children: tab.content
           }
@@ -85,6 +86,6 @@ function normalizeBadge(badge) {
   return void 0;
 }
 
-export { TabScaffold };
+export { TabNavigator };
 
-//# sourceMappingURL=tab-scaffold.js.map
+//# sourceMappingURL=tab-navigator.js.map

package/dist/tab-navigator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/navigation/tab-scaffold/tab-scaffold.tsx"],"names":[],"mappings":";;;AAwFO,SAAS,YAAA,CAAgC;AAAA,EAC9C,EAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,MAAA;AAAA,EACA,cAAA,GAAiB,QAAA;AAAA,EACjB,SAAA,GAAY,EAAA;AAAA,EACZ;AACF,CAAA,EAA0B;AACxB,EAAA,uBACE,IAAA;AAAA,IAAC,SAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MAC5C,EAAA;AAAA,MACA,gBAAA,EAAe,cAAA;AAAA,MACf,sBAAA,EAAsB,EAAA;AAAA,MACtB,sBAAA,EACE,cAAA,KAAmB,QAAA,IAAY,cAAA,KAAmB,SAC9C,cAAA,GACA,MAAA;AAAA,MAEN,IAAA;AAAA,MAEA,QAAA,EAAA;AAAA,wBAAA,GAAA,CAAC,SAAI,KAAA,EAAM,0BAAA,EACR,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,qBACT,GAAA;AAAA,UAAC,KAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,yBAAA;AAAA,YACN,2BAAyB,GAAA,CAAI,EAAA;AAAA,YAC7B,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YACrC,iBAAA,EAAiB,GAAA,CAAI,UAAA,KAAe,QAAA,GAAW,QAAA,GAAW,MAAA;AAAA,YAC1D,iBAAA,EAAiB,GAAA,CAAI,SAAA,GAAY,MAAA,GAAS,MAAA;AAAA,YAC1C,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YAEpC,QAAA,EAAA,GAAA,CAAI;AAAA;AAAA,SAER,CAAA,EACH,CAAA;AAAA,wBACA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EAAwB,IAAA,EAAK,SAAA,EAAU,YAAA,EAAY,KAAA,EAC3D,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,KAAQ;AACjB,UAAA,MAAM,GAAA,GAAM,IAAI,KAAA,KAAU,IAAA;AAC1B,UAAA,MAAM,SAAA,GAAY,GAAA,GAAM,MAAA,GAAY,cAAA,CAAe,IAAI,KAAK,CAAA;AAC5D,UAAA,MAAM,QAAA,GAAW,OAAO,SAAA,KAAc,MAAA;AACtC,UAAA,MAAM,QAAQ,QAAA,oBACZ,GAAA;AAAA,YAAC,MAAA;AAAA,YAAA;AAAA,cACC,KAAA,EAAM,6BAAA;AAAA,cACN,iBAAA,EAAiB,MAAM,KAAA,GAAQ,MAAA;AAAA,cAE9B,QAAA,EAAA,SAAA,KAAc,MAAA,mBACb,GAAA,CAAC,KAAA,EAAA,EAAM,IAAA,EAAK,UAAS,IAAA,EAAK,KAAA,EAAM,UAAA,EAAU,IAAA,EAAC,CAAA,mBAE3C,GAAA;AAAA,gBAAC,KAAA;AAAA,gBAAA;AAAA,kBACC,IAAA,EAAK,QAAA;AAAA,kBACL,UAAA,EAAW,OAAA;AAAA,kBACX,IAAA,EAAK,SAAA;AAAA,kBACL,UAAA,EAAU,IAAA;AAAA,kBAET,QAAA,EAAA;AAAA;AAAA;AACH;AAAA,WAEJ;AAIF,UAAA,MAAM,aAAa,QAAA,GACf,GAAA,CAAI,UAAA,EAAY,IAAA,MAAU,SAAA,GAC1B,MAAA;AACJ,UAAA,uBACE,IAAA;AAAA,YAAC,QAAA;AAAA,YAAA;AAAA,cACC,IAAA,EAAK,QAAA;AAAA,cACL,KAAA,EAAM,uBAAA;AAAA,cACN,IAAA,EAAK,KAAA;AAAA,cACL,yBAAuB,GAAA,CAAI,EAAA;AAAA,cAC3B,eAAA,EAAe,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,cACvC,QAAA,EAAU,GAAA,CAAI,EAAA,KAAO,MAAA,GAAS,GAAA,GAAM,IAAA;AAAA,cACpC,YAAA,EACE,eAAe,MAAA,GACX,MAAA,GACA,GAAG,GAAA,CAAI,KAAK,KAAK,UAAU,CAAA,CAAA;AAAA,cAEjC,gBAAA,EAAgB,WAAW,MAAA,GAAS,MAAA;AAAA,cAEnC,QAAA,EAAA;AAAA,gBAAA,GAAA,CAAI,uBACH,IAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,4BAAA,EAA6B,eAAY,MAAA,EAClD,QAAA,EAAA;AAAA,kBAAA,GAAA,CAAI,IAAA;AAAA,kBACJ;AAAA,iBAAA,EACH,CAAA,GAEA,KAAA;AAAA,gCAEF,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,6BAAA,EAA+B,cAAI,KAAA,EAAM;AAAA;AAAA;AAAA,WACvD;AAAA,QAEJ,CAAC,CAAA,EACH;AAAA;AAAA;AAAA,GACF;AAEJ;AAEA,SAAS,eACP,KAAA,EACoB;AACpB,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA;AACnB,IAAA,OAAO,OAAO,QAAA,CAAS,KAAK,CAAA,GAAI,MAAA,CAAO,KAAK,CAAA,GAAI,MAAA;AAClD,EAAA,IAAI,OAAO,UAAU,QAAA,IAAY,KAAA,CAAM,MAAK,EAAG,OAAO,MAAM,IAAA,EAAK;AACjE,EAAA,OAAO,MAAA;AACT","file":"tab-navigator.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.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 an extra 8px inline gutter to a plain scene's scrolling content. */\n  deepInset?: 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 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` never, even when wired. The line is the bar's own 1px top\n   * 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  chromeDividers = 'scroll',\n  className = '',\n  slot,\n}: TabNavigatorProps<Id>) {\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-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            aria-hidden={String(tab.id !== active)}\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.js

@@ -1,4 +1,4 @@
-export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-G4VKQP7B.js';
+export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-3SXWV2IR.js';
 
 
 

package/dist/wire-catalog.js

@@ -1,6 +1,6 @@
 import { wireWorkbench } from './chunk-5BZBIRQG.js';
 
-import { wireScrollDividers } from './chunk-QYXKMLHO.js';
+import { wireScrollDividers } from './chunk-3CXRQAYT.js';
 
 
 import { delegate } from 'kerfjs';

package/dist/wire-scroll-dividers.d.ts

@@ -28,7 +28,7 @@ interface WireScrollDividersOptions {
     /**
      * App-owned scroll arrangements to pair beyond the ones found by structure
      * (every `Pane`'s header and footer around its content, every `NavStack`'s
-     * and `TabScaffold`'s chrome around its active region, and every `TabBar`
+     * and `TabNavigator`'s chrome around its active region, and every `TabBar`
      * strip).
      */
     targets?: readonly ScrollDividerTarget[];
@@ -48,11 +48,11 @@ type Root = HTMLElement | Document;
  * - every `Pane` with a header or footer: its header shows a bottom divider and
  *   its footer a top divider (drawn by the Pane, per its `chromeDividers`);
  * - every `NavStack`'s top chrome and bottom toolbar around its active view,
- *   and every `TabScaffold`'s bar under its active scene: the chrome shows a
+ *   and every `TabNavigator`'s bar under its active scene: the chrome shows a
  *   bottom (top chrome) or top (bottom toolbar, bar) divider. The scroller is
  *   whichever element actually scrolls there: the view or scene itself, or,
  *   through a sole child with no chrome of its own on that edge, a `Pane`'s
- *   content or a nested `NavStack` / `TabScaffold` region (a Pane's own header
+ *   content or a nested `NavStack` / `TabNavigator` region (a Pane's own header
  *   or footer draws that boundary instead);
  * - every `TabBar` strip: the bar draws a divider on each side of the strip
  *   whose tabs are scrolled out of view;

package/dist/wire-scroll-dividers.js

@@ -1,3 +1,3 @@
-export { wireScrollDividers } from './chunk-QYXKMLHO.js';
+export { wireScrollDividers } from './chunk-3CXRQAYT.js';
 
 //# sourceMappingURL=wire-scroll-dividers.js.map

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

@@ -0,0 +1,11 @@
+interface WireTabNavigatorOptions {
+    /** Invoked with the selected tab id when a bottom-bar tab is activated. */
+    onSelect: (tabId: string) => void;
+}
+/**
+ * Wire a `TabNavigator`'s bottom tab bar: clicking a tab calls `onSelect` with its
+ * id (the app then updates its controlled `active`). Returns a disposer.
+ */
+declare function wireTabNavigator(root: Element, options: WireTabNavigatorOptions): () => void;
+
+export { type WireTabNavigatorOptions, wireTabNavigator };

package/dist/{wire-tab-scaffold.js → wire-tab-navigator.js}

@@ -1,7 +1,7 @@
 import { delegate } from 'kerfjs';
 
 // src/components/navigation/tab-scaffold/wiring/wire-tab-scaffold.ts
-function wireTabScaffold(root, options) {
+function wireTabNavigator(root, options) {
   const section = root.matches('[data-component="tab-scaffold"]') ? root : root.querySelector('[data-component="tab-scaffold"]');
   if (!(section instanceof HTMLElement)) return () => {
   };
@@ -16,6 +16,6 @@ function wireTabScaffold(root, options) {
   );
 }
 
-export { wireTabScaffold };
+export { wireTabNavigator };
 
-//# sourceMappingURL=wire-tab-scaffold.js.map
+//# sourceMappingURL=wire-tab-navigator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/navigation/tab-scaffold/wiring/wire-tab-scaffold.ts"],"names":[],"mappings":";;;AAWO,SAAS,gBAAA,CACd,MACA,OAAA,EACY;AACZ,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,CAAQ,iCAAiC,IAC1D,IAAA,GACA,IAAA,CAAK,cAAc,iCAAiC,CAAA;AACxD,EAAA,IAAI,EAAE,OAAA,YAAmB,WAAA,CAAA,EAAc,OAAO,MAAM;AAAA,EAAC,CAAA;AACrD,EAAA,OAAO,QAAA;AAAA,IACL,OAAA;AAAA,IACA,OAAA;AAAA,IACA,yBAAA;AAAA,IACA,CAAC,QAAQ,MAAA,KAAW;AAClB,MAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,YAAA,CAAa,uBAAuB,CAAA;AACzD,MAAA,IAAI,KAAA,EAAO,OAAA,CAAQ,QAAA,CAAS,KAAK,CAAA;AAAA,IACnC;AAAA,GACF;AACF","file":"wire-tab-navigator.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireTabNavigatorOptions {\n  /** Invoked with the selected tab id when a bottom-bar tab is activated. */\n  onSelect: (tabId: string) => void;\n}\n\n/**\n * Wire a `TabNavigator`'s bottom tab bar: clicking a tab calls `onSelect` with its\n * id (the app then updates its controlled `active`). Returns a disposer.\n */\nexport function wireTabNavigator(\n  root: Element,\n  options: WireTabNavigatorOptions,\n): () => void {\n  const section = root.matches('[data-component=\"tab-scaffold\"]')\n    ? root\n    : root.querySelector('[data-component=\"tab-scaffold\"]');\n  if (!(section instanceof HTMLElement)) return () => {};\n  return delegate(\n    section,\n    'click',\n    '[data-tab-scaffold-tab]',\n    (_event, target) => {\n      const tabId = target.getAttribute('data-tab-scaffold-tab');\n      if (tabId) options.onSelect(tabId);\n    },\n  );\n}\n"]}

package/dist/wire-token-search-fields.js

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-VLPE6OPN.js';
+export { wireTokenSearchFields } from './chunk-62VMNBV2.js';
 
 
 

package/dist/wire-toolbar-visibility.js

@@ -1,3 +1,3 @@
-export { wireToolbarVisibility } from './chunk-WJN3V2H5.js';
+export { wireToolbarVisibility } from './chunk-2GOCOLQL.js';
 
 //# sourceMappingURL=wire-toolbar-visibility.js.map

package/dist/workbench.d.ts

@@ -1,15 +1,15 @@
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { b as NavPane, N as NavStackProps } from './nav-stack-B1Qc2e5q.js';
 import { ListConfig } from './list.js';
-import { NavStackProps } from './nav-stack.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
+import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
 import { ToolbarConfig } from './toolbar.js';
+import './toolbar-text.js';
+import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
-import './css-values.js';
-import './toolbar-text.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -131,19 +131,11 @@ interface WorkbenchPanelBase {
     restorePosition?: ResizableRegionRestorePosition;
 }
 /** The original static panel body: one toolbar, optional fixed chrome, and one Pane. */
-interface WorkbenchStaticPanel extends WorkbenchPanelBase {
-    content: KerfUiContent;
+interface WorkbenchStaticPanel extends WorkbenchPanelBase, NavPane<WorkbenchPanelToolbar, WorkbenchPanelBottomToolbar> {
     /** The composed toolbar; marked groups and its toggle relocate on collapse. */
     toolbar?: WorkbenchPanelToolbar;
-    header?: KerfUiContent;
-    headerList?: ListConfig;
     headerPlacement?: WorkbenchChromePlacement;
-    footer?: KerfUiContent;
-    footerList?: ListConfig;
-    bottomToolbar?: WorkbenchPanelBottomToolbar;
     footerPlacement?: WorkbenchChromePlacement;
-    /** Configuration for the static toolbar panel's Pane. */
-    pane?: PaneConfig;
     navStack?: never;
 }
 /** A panel whose active NavStack view supplies the toolbar, fixed header, and scroll body. */

package/dist/workbench.js

@@ -1,4 +1,4 @@
-export { Workbench } from './chunk-6VQPLV3O.js';
+export { Workbench } from './chunk-DSLRNR43.js';
 
 
 

package/docs/app-layouts.md

@@ -9,7 +9,7 @@ changes. The layouts:
 - [`NavStack`](nav-stack.md) — push/pop navigation (a single pane is a one-entry stack).
 - [`SplitView`](split-view.md) — list-detail (two panes, collapsing to a stack).
 - [`Workbench`](workbench.md) — the Xcode-like collapsible rails + drawer.
-- [`TabScaffold`](tab-scaffold.md) — the iOS bottom tab bar (each tab a stack).
+- [`TabNavigator`](tab-navigator.md) — the iOS bottom tab bar (each tab a stack).
 - [`CollapsiblePanel` + `wireSidebar`](collapsible-panel.md) — a standalone
   collapsible rail or bottom drawer (with `CollapsiblePanelToggle`), outside a full
   shell: the standard collapse animation, icon convention, and `wireSidebar`
@@ -45,7 +45,7 @@ the layouts handle the insets for you. There is nothing to configure:
 - **No double inset.** Whichever region applies an inset clears it for its
   descendants. A layout region whose only child is a `Pane` or another layout
   lets that child own the insets. That child fills the region — a `Workbench`
-  area or panel, a `NavStack` view, a `TabScaffold` scene — so a sole `Pane`'s
+  area or panel, a `NavStack` view, a `TabNavigator` scene — so a sole `Pane`'s
   header stays pinned while its own content scrolls. A `Pane` header or footer whose only child is
   a `Toolbar` hands the inline insets to the toolbar, so the toolbar's dividers
   still reach the edge.
@@ -96,15 +96,48 @@ The device insets come from `--kui-safe-area-block-start`, `-block-end`,
 Override them on `:root` to reserve room for app-owned chrome or to simulate a
 device in tests.
 
+### Edge-to-edge content inside a Pane
+
+The Pane's scrolling slot publishes its resolved horizontal padding as
+`--kui-pane-content-inset-inline-start` and
+`--kui-pane-content-inset-inline-end`. Both inherited values include the safe
+area on the corresponding side, plus the extra 8px when `deepInset` is true.
+An app component can use them to let a row background or divider reach the
+Pane edge while its text stays on the ordinary content axis:
+
+```css
+.orders-table {
+  margin-inline-start: calc(-1 * var(--kui-pane-content-inset-inline-start));
+  margin-inline-end: calc(-1 * var(--kui-pane-content-inset-inline-end));
+}
+
+.orders-table th:first-child,
+.orders-table td:first-child {
+  padding-inline-start: calc(var(--kui-pane-content-inset-inline-start) + 17px);
+}
+
+.orders-table th:last-child,
+.orders-table td:last-child {
+  padding-inline-end: calc(var(--kui-pane-content-inset-inline-end) + 17px);
+}
+```
+
+Here 17px is the app's chosen text offset from the content slot: a default
+`ContentItem` uses 8px outer margin, 1px border, and 8px inner padding. Adjust
+that offset to match the neighboring content. Keep the table inside the Pane's
+single scrolling slot; the negative margins change only its inline reach. The
+[`Pane` UX catalog example](../ux-demo/demos/pane.tsx) shows both `deepInset`
+states with the same table component.
+
 ## Decision matrix
 
-| Situation                                                                    | Layout                                                                                          | Device threshold                                                                                                                   |
-| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Simple app, a few flat sections                                              | `NavStack` with one entry (single pane); add `TabScaffold` for 2–5 co-equal sections on handset | `TabScaffold` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')`                                  |
-| Drill-down browsing (list → item → sub-item)                                 | `NavStack`; upgrade to `SplitView` once list + detail fit together                              | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact`                                   |
-| Two related panes, selecting on the left updates the right                   | `SplitView`                                                                                     | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact`                                                 |
-| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench`                                                                                     | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
-| Mobile app with 2–5 top-level destinations, each its own drill-down          | `TabScaffold`, each tab a `NavStack`                                                            | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')`                                                          |
+| Situation                                                                    | Layout                                                                                           | Device threshold                                                                                                                   |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Simple app, a few flat sections                                              | `NavStack` with one entry (single pane); add `TabNavigator` for 2–5 co-equal sections on handset | `TabNavigator` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')`                                 |
+| Drill-down browsing (list → item → sub-item)                                 | `NavStack`; upgrade to `SplitView` once list + detail fit together                               | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact`                                   |
+| Two related panes, selecting on the left updates the right                   | `SplitView`                                                                                      | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact`                                                 |
+| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench`                                                                                      | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
+| Mobile app with 2–5 top-level destinations, each its own drill-down          | `TabNavigator`, each tab a `NavStack`                                                            | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')`                                                          |
 
 ### Worked examples
 
@@ -129,13 +162,13 @@ device in tests.
   default) and shrink in proportion when the window narrows; the bottom drawer
   leaves it `mainMinHeight` (120px by default) and shrinks when the window gets
   shorter.
-- **Social app (tabbed):** `TabScaffold` with Home / Search / Profile tabs, each
+- **Social app (tabbed):** `TabNavigator` with Home / Search / Profile tabs, each
   `content` a `NavStack`. On a tablet/desktop, render the same sections as a
   `Workbench` left rail instead of a bottom bar.
 
 Whatever the layout, call `wireScrollDividers(appRoot)` from
 `@kerfjs/ui/wire-scroll-dividers` once: every `Pane` a layout renders, every
-`NavStack`'s top chrome and bottom toolbar, and every `TabScaffold` bar then
+`NavStack`'s top chrome and bottom toolbar, and every `TabNavigator` bar then
 draw the line between the pinned chrome and the scrolling content only while
 content is scrolled beneath them, and toolbars need no divider of their own. See [Scroll dividers](layout.md#scroll-dividers).
 

package/docs/component-contract.md

@@ -713,7 +713,7 @@ helpers. Its collapse behavior was _rich and error-prone_ — reveal, focus
 transfer, Escape, empty-blur collapse, focus return — the kind of transient chrome
 apps kept reimplementing inconsistently, so the helper owns it. Everywhere else the
 app's state is **domain or persisted, not transient chrome, and stays app-owned**: a
-`NavStack`'s view stack is navigation history, a `TabBar`/`TabScaffold`'s selection
+`NavStack`'s view stack is navigation history, a `TabBar`/`TabNavigator`'s selection
 and tab order are data, a `ResizableRegion`'s committed size and a
 `Workbench`/`SplitView` rail's `collapsed` flag are persisted layout preferences.
 Each helper already owns only the _ephemeral mechanics_ around that state —
@@ -890,7 +890,14 @@ leave the item visible under this width policy. Server-rendered content is visib
 until wiring runs; without browser observers, initial wiring and window resize
 still update it. Probe context and lengths are reconciled only when their CSSOM
 values change, so unrelated DOM observers can redraw without feeding an ongoing
-mutation loop. Dispose to remove measurement probes and restore prior markers.
+mutation loop. Probes are helper-owned imperative nodes preserved across Kerf
+rerenders, preventing repeated probe creation and resize/DOM observer churn.
+Invisible preserved state children keep actual CSS visibility stable while a render
+removes transient parent markers, so post-render geometry measurements cannot
+feed a show/hide render loop. These children never enter layout, focus or the
+accessible tree. Toolbar replacement or deliberate internal-node removal is
+still repaired. Dispose to
+remove measurement probes and restore prior markers.
 
 Hidden controls leave layout and keyboard navigation. A hidden busy group also
 hides only its own adjacent busy status. Keep primary actions always available;