@kerfjs/ui 5.0.0-beta.61 → 5.0.0-beta.62

package/dist/styles/workbench.css

@@ -91,21 +91,11 @@
   flex-direction: column;
 }
 
-.kui-workbench:has(
-    > .kui-workbench__rail--left[data-presentation="inline"]:not(
-        [data-collapsed="true"]
-      )
-  )
-  > .kui-workbench__center {
+.kui-workbench[data-left-inline-expanded="true"] > .kui-workbench__center {
   --kui-edge-inset-inline-start: 0px;
 }
 
-.kui-workbench:has(
-    > .kui-workbench__rail--right[data-presentation="inline"]:not(
-        [data-collapsed="true"]
-      )
-  )
-  > .kui-workbench__center {
+.kui-workbench[data-right-inline-expanded="true"] > .kui-workbench__center {
   --kui-edge-inset-inline-end: 0px;
 }
 
@@ -115,18 +105,64 @@
   overflow: auto;
 }
 
-.kui-workbench__main:has(
-  ~ .kui-workbench__drawer[data-presentation="inline"]:not(
-      [data-collapsed="true"]
-    )
-) {
-  --kui-edge-inset-block-end: 0px;
+/* When no Pane chrome is composed, the Workbench region owns its scroll.
+   A resizable auto-overflow panel instead scrolls its content box so its
+   separator handle remains fixed. Paint only that owner. */
+.kui-workbench__main[data-appearance="sunken"],
+:is(.kui-workbench__rail, .kui-workbench__drawer)[data-appearance="sunken"] {
+  background: var(
+    --kui-sunken-panel-background,
+    var(--kui-color-surface-lowered)
+  );
+}
+
+:is(
+    .kui-workbench__rail,
+    .kui-workbench__drawer
+  )[data-appearance="sunken"][data-resizable="true"][data-content-overflow="auto"] {
+  background: transparent;
+}
+
+:is(
+    .kui-workbench__rail,
+    .kui-workbench__drawer
+  )[data-appearance="sunken"][data-resizable="true"][data-content-overflow="auto"]
+  > .kui-workbench__panel-content {
+  background: var(
+    --kui-sunken-panel-background,
+    var(--kui-color-surface-lowered)
+  );
+}
+
+.kui-workbench__main[data-drawer-inline-expanded="true"] {
+  --_kui-workbench-content-edge-block-end: 0px;
 }
 
 /* The main area and each panel's content are the consumers: they pad for the
    edges their region still touches, the main area inside its scroller so
    content scrolls under an unsafe edge but can always be scrolled clear. A
    region whose only child is a Pane or layout lets that child own the insets. */
+.kui-workbench__center,
+.kui-workbench__rail,
+.kui-workbench__drawer {
+  --_kui-workbench-content-edge-block-start: var(--kui-edge-inset-block-start);
+  --_kui-workbench-content-edge-block-end: var(--kui-edge-inset-block-end);
+  --_kui-workbench-content-edge-inline-start: var(
+    --kui-edge-inset-inline-start
+  );
+  --_kui-workbench-content-edge-inline-end: var(--kui-edge-inset-inline-end);
+}
+
+.kui-workbench__main,
+.kui-workbench__panel-content {
+  /* Clear the public context at the region, so arbitrary app children inherit
+     zero without a selector whose subject is every child in the document. */
+  --kui-edge-inset-block-start: 0px;
+  --kui-edge-inset-block-end: 0px;
+  --kui-edge-inset-inline-start: 0px;
+  --kui-edge-inset-inline-end: 0px;
+}
+
 .kui-workbench__main:not(
   :has(
     > :is(
@@ -149,44 +185,24 @@
       ):only-child
   )
 ) {
-  padding-block: var(--kui-edge-inset-block-start)
-    var(--kui-edge-inset-block-end);
-  padding-inline: var(--kui-edge-inset-inline-start)
-    var(--kui-edge-inset-inline-end);
-  scroll-padding-block: var(--kui-edge-inset-block-start)
-    var(--kui-edge-inset-block-end);
-}
-
-/* Every other child sees a cleared context. The exemption is tested on the
-   child itself, never as `region:not(:has(…)) > *`: a `:has()` before a
-   universal child makes each child of the region re-check the region's
-   `:has()` on every DOM change (~46ms per restyle for 1000 rows in Chromium).
-   SplitView, NavStack, TabScaffold, and CollapsiblePanel content use the same
-   shape. */
-.kui-workbench__main
-  > :not(
-    :is(
-      [data-component="pane"],
-      [data-component="nav-stack"],
-      [data-component="split-view"],
-      [data-component="workbench"],
-      [data-component="tab-scaffold"]
-    ):only-child
-  ),
-.kui-workbench__panel-content
-  > :not(
-    :is(
-      [data-component="pane"],
-      [data-component="nav-stack"],
-      [data-component="split-view"],
-      [data-component="workbench"],
-      [data-component="tab-scaffold"]
-    ):only-child
-  ) {
-  --kui-edge-inset-block-start: 0px;
-  --kui-edge-inset-block-end: 0px;
-  --kui-edge-inset-inline-start: 0px;
-  --kui-edge-inset-inline-end: 0px;
+  padding-block: var(--_kui-workbench-content-edge-block-start)
+    var(--_kui-workbench-content-edge-block-end);
+  padding-inline: var(--_kui-workbench-content-edge-inline-start)
+    var(--_kui-workbench-content-edge-inline-end);
+  scroll-padding-block: var(--_kui-workbench-content-edge-block-start)
+    var(--_kui-workbench-content-edge-block-end);
+}
+
+/* A nested Workbench owns its safe-area insets. Other sole layout children
+   restore this context from their own stylesheets. */
+:is(.kui-workbench__main, .kui-workbench__panel-content)
+  > [data-component="workbench"]:only-child {
+  --kui-edge-inset-block-start: var(--_kui-workbench-content-edge-block-start);
+  --kui-edge-inset-block-end: var(--_kui-workbench-content-edge-block-end);
+  --kui-edge-inset-inline-start: var(
+    --_kui-workbench-content-edge-inline-start
+  );
+  --kui-edge-inset-inline-end: var(--_kui-workbench-content-edge-inline-end);
 }
 
 /* A region whose only child is a Pane or layout lets it fill the region, so a
@@ -231,6 +247,11 @@
   overflow: visible;
 }
 
+.kui-workbench__rail:has(wa-dropdown[open]),
+.kui-workbench__drawer:has(wa-dropdown[open]) {
+  z-index: var(--kui-workbench-popup-z, 5);
+}
+
 /* The fixed-size sliding content. The rail/drawer keeps a definite size on its
    content so the transform reads as a slide, not a squeeze. */
 .kui-workbench__rail .kui-workbench__panel-content {
@@ -254,6 +275,11 @@
   transition: none;
 }
 
+:is(.kui-workbench__rail, .kui-workbench__drawer)[data-resizing="true"]
+  > .kui-workbench__panel-content {
+  transition: none;
+}
+
 .kui-workbench__rail[data-collapse-motion="fade-slide"][data-collapsed="true"]
   .kui-workbench__panel-content,
 .kui-workbench__drawer[data-collapse-motion="fade-slide"][data-collapsed="true"]
@@ -579,10 +605,7 @@
    `responsiveFillAt`), and inline above it. The Workbench becomes a named
    inline-size container only when a panel opts in. The work area keeps its
    safe-area inset under an overlay panel. */
-.kui-workbench:has(
-  > .kui-workbench__rail[data-responsive-overlay-at],
-  > .kui-workbench__center > .kui-workbench__drawer[data-responsive-overlay-at]
-) {
+.kui-workbench[data-responsive-overlay="true"] {
   container: kui-workbench / inline-size;
 }
 
@@ -622,16 +645,12 @@
     display: none;
   }
 
-  .kui-workbench:has(
-      > .kui-workbench__rail--left[data-responsive-overlay-at="narrow"][data-presentation="inline"]
-    )
+  .kui-workbench[data-left-responsive-inline="narrow"]
     > .kui-workbench__center {
     --kui-edge-inset-inline-start: var(--_kui-workbench-safe-inline-start);
   }
 
-  .kui-workbench:has(
-      > .kui-workbench__rail--right[data-responsive-overlay-at="narrow"][data-presentation="inline"]
-    )
+  .kui-workbench[data-right-responsive-inline="narrow"]
     > .kui-workbench__center {
     --kui-edge-inset-inline-end: var(--_kui-workbench-safe-inline-end);
   }
@@ -665,10 +684,10 @@
     display: none;
   }
 
-  .kui-workbench__main:has(
-    ~ .kui-workbench__drawer[data-responsive-overlay-at="narrow"][data-presentation="inline"]
-  ) {
-    --kui-edge-inset-block-end: var(--_kui-workbench-safe-block-end);
+  .kui-workbench__main[data-drawer-responsive-inline="narrow"] {
+    --_kui-workbench-content-edge-block-end: var(
+      --_kui-workbench-safe-block-end
+    );
   }
 }
 
@@ -708,16 +727,12 @@
     display: none;
   }
 
-  .kui-workbench:has(
-      > .kui-workbench__rail--left[data-responsive-overlay-at="compact"][data-presentation="inline"]
-    )
+  .kui-workbench[data-left-responsive-inline="compact"]
     > .kui-workbench__center {
     --kui-edge-inset-inline-start: var(--_kui-workbench-safe-inline-start);
   }
 
-  .kui-workbench:has(
-      > .kui-workbench__rail--right[data-responsive-overlay-at="compact"][data-presentation="inline"]
-    )
+  .kui-workbench[data-right-responsive-inline="compact"]
     > .kui-workbench__center {
     --kui-edge-inset-inline-end: var(--_kui-workbench-safe-inline-end);
   }
@@ -751,13 +766,28 @@
     display: none;
   }
 
-  .kui-workbench__main:has(
-    ~ .kui-workbench__drawer[data-responsive-overlay-at="compact"][data-presentation="inline"]
-  ) {
-    --kui-edge-inset-block-end: var(--_kui-workbench-safe-block-end);
+  .kui-workbench__main[data-drawer-responsive-inline="compact"] {
+    --_kui-workbench-content-edge-block-end: var(
+      --_kui-workbench-safe-block-end
+    );
   }
 }
 
+/* Release the panel and its sliding/scrolling content while a PopupMenu or
+   Web Awesome dropdown is open. This comes after resize clipping and keeps
+   the popup in place through wa-show/wa-after-hide without a prop change. */
+.kui-workbench__rail:not([data-collapsed="true"]):has(wa-dropdown[open]),
+.kui-workbench__drawer:not([data-collapsed="true"]):has(wa-dropdown[open]) {
+  overflow: visible;
+  clip-path: none;
+}
+.kui-workbench__rail:not([data-collapsed="true"]):has(wa-dropdown[open])
+  > .kui-workbench__panel-content,
+.kui-workbench__drawer:not([data-collapsed="true"]):has(wa-dropdown[open])
+  > .kui-workbench__panel-content {
+  overflow: visible;
+}
+
 /* A collapsed panel's restore control floats in a corner of the Workbench
    itself, never of the viewport, so an embedded Workbench cannot float it over
    page chrome outside it. It is inset from the corner plus the unsafe area of
@@ -860,20 +890,15 @@
    the open rail), so the overlay's own floating controls stay; FloatingToolbar
    and the layouts' restore corners read it. A direct child
    resolves the Workbench's own container query, never a nested one's. */
-.kui-workbench:has(
-    > .kui-workbench__rail[data-presentation="overlay"]:not(
-        [data-collapsed="true"]
-      )
-  )
+.kui-workbench[data-rail-overlay-expanded="true"]
   > :is(.kui-workbench__center, .kui-workbench__restore) {
   --_kui-workbench-covered: hidden;
 }
 
 @container kui-workbench (max-width: 44rem) {
-  .kui-workbench:has(
-      > .kui-workbench__rail[data-responsive-overlay-at="narrow"][data-presentation="inline"]:not(
-          [data-collapsed="true"]
-        )
+  .kui-workbench:is(
+      [data-left-responsive-expanded="narrow"],
+      [data-right-responsive-expanded="narrow"]
     )
     > :is(.kui-workbench__center, .kui-workbench__restore) {
     --_kui-workbench-covered: hidden;
@@ -881,10 +906,9 @@
 }
 
 @container kui-workbench (max-width: 28rem) {
-  .kui-workbench:has(
-      > .kui-workbench__rail[data-responsive-overlay-at="compact"][data-presentation="inline"]:not(
-          [data-collapsed="true"]
-        )
+  .kui-workbench:is(
+      [data-left-responsive-expanded="compact"],
+      [data-right-responsive-expanded="compact"]
     )
     > :is(.kui-workbench__center, .kui-workbench__restore) {
     --_kui-workbench-covered: hidden;

package/dist/tab-bar.d.ts

@@ -5,6 +5,8 @@ type TabActivation = 'automatic' | 'manual';
 type TabBarAllocation = 'intrinsic' | 'fill';
 type TabBarPresentation = 'rail' | 'segmented' | 'inspector';
 type TabBarTrailingPlacement = 'separate' | 'adjacent';
+/** Tablist width where segmented AppTabs switch to icon-only. */
+type TabBarIconOnlyAt = 'wide' | 'narrow' | 'compact';
 interface TabBarProps {
     id: string;
     label: string;
@@ -28,12 +30,14 @@ interface TabBarProps {
     allocation?: TabBarAllocation;
     /** Named strip chrome for application rails, segmented tabs, or inspectors. */
     presentation?: TabBarPresentation;
+    /** Switch segmented AppTabs to icon-only at tablist widths of 832, 704, or 448px. Each tab needs a leading icon. */
+    iconOnlyAt?: TabBarIconOnlyAt;
     /** Keep a trailing action beside the final tab or at the far edge of the bar. */
     trailingPlacement?: TabBarTrailingPlacement;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, end, className, activation, allocation, presentation, trailingPlacement, slot, }: TabBarProps): kerfjs.SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, end, className, activation, allocation, presentation, iconOnlyAt, trailingPlacement, slot, }: TabBarProps): kerfjs.SafeHtml;
 
-export { type TabActivation, TabBar, type TabBarAllocation, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };
+export { type TabActivation, TabBar, type TabBarAllocation, type TabBarIconOnlyAt, type TabBarPresentation, type TabBarProps, type TabBarTrailingPlacement };

package/dist/tab-bar.js

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

package/dist/tab-scaffold.d.ts

@@ -1,4 +1,5 @@
 import { SafeHtml } from 'kerfjs';
+import { PaneAppearance } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface TabScaffoldTabBase<Id extends string> {
@@ -8,6 +9,8 @@ interface TabScaffoldTabBase<Id extends string> {
     icon?: SafeHtml;
     /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
     content: KerfUiContent;
+    /** Background of this scene's scrolling work surface. */
+    appearance?: PaneAppearance;
 }
 /** A tab with an optional count or short-status badge. */
 interface TabScaffoldTabCountBadge {

package/dist/tab-scaffold.js

@@ -26,6 +26,7 @@ function TabScaffold({
             class: "kui-tab-scaffold__scene",
             "data-tab-scaffold-scene": tab.id,
             "data-active": String(tab.id === active),
+            "data-appearance": tab.appearance === "sunken" ? "sunken" : void 0,
             "aria-hidden": String(tab.id !== active),
             children: tab.content
           }

package/dist/tab-scaffold.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tab-scaffold.tsx"],"names":[],"mappings":"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","file":"tab-scaffold.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport { Badge } from './badge.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\ninterface TabScaffoldTabBase<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}\n\n/** A tab with an optional count or short-status badge. */\ninterface TabScaffoldTabCountBadge {\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 TabScaffoldTabDotBadge {\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 TabScaffoldTab<Id extends string = string> =\n  TabScaffoldTabBase<Id> & (TabScaffoldTabCountBadge | TabScaffoldTabDotBadge);\n\nexport interface TabScaffoldProps<Id extends string = string> {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: readonly TabScaffoldTab<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 scaffold: 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-scaffold`'s `wireTabScaffold`.\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 TabScaffold<Id extends string>({\n  id,\n  label,\n  tabs,\n  active,\n  chromeDividers = 'scroll',\n  className = '',\n  slot,\n}: TabScaffoldProps<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            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"]}
+{"version":3,"sources":["../src/tab-scaffold.tsx"],"names":[],"mappings":"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","file":"tab-scaffold.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nimport { Badge } from './badge.js';\nimport type { PaneAppearance } from './pane.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\ninterface TabScaffoldTabBase<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}\n\n/** A tab with an optional count or short-status badge. */\ninterface TabScaffoldTabCountBadge {\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 TabScaffoldTabDotBadge {\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 TabScaffoldTab<Id extends string = string> =\n  TabScaffoldTabBase<Id> & (TabScaffoldTabCountBadge | TabScaffoldTabDotBadge);\n\nexport interface TabScaffoldProps<Id extends string = string> {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: readonly TabScaffoldTab<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 scaffold: 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-scaffold`'s `wireTabScaffold`.\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 TabScaffold<Id extends string>({\n  id,\n  label,\n  tabs,\n  active,\n  chromeDividers = 'scroll',\n  className = '',\n  slot,\n}: TabScaffoldProps<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            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/toolbar-text.d.ts

@@ -1,6 +1,6 @@
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small' | 'xsmall';
+type ToolbarTextSize = 'xlarge' | 'xlarge-fixed' | 'large' | 'default' | 'small' | 'xsmall';
 /** ARIA heading level for a title exposed as a heading landmark. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextBaseProps {

package/dist/toolbar-text.js

@@ -1,4 +1,4 @@
-export { ToolbarText } from './chunk-3SXMEK3B.js';
+export { ToolbarText } from './chunk-V3DX3K65.js';
 
 
 

package/dist/toolbar.d.ts

@@ -17,8 +17,8 @@ interface ToolbarProps {
      * then draws its facing side the same way.
      */
     dividerSides?: Sides;
-    /** Horizontal treatment of the center zone. Defaults to centered content. */
-    centerAlign?: 'center' | 'stretch';
+    /** `balanced` gives both side zones equal tracks, centering the middle zone on the toolbar even if only one side has controls. */
+    centerAlign?: 'center' | 'stretch' | 'balanced';
     /**
      * Component-owned responsive layout; applications choose the policy rather
      * than restyling toolbar internals. Under every policy the trailing zone

package/dist/toolbar.js

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

package/dist/wire-tab-bars.js

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

package/dist/workbench.js

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

package/docs/collapsible-panel.md

@@ -80,9 +80,10 @@ and that of the components it renders (`Pane`, `Toolbar`, `ToolbarControlGroup`,
   corners, with typed `restoreInset` for the corner distance. Set
   `restorePlacement="inline"` when the container should place the control in
   normal flow. An inline region's surface uses
-  `--kui-resizable-region-background`; set `contentOverflow="visible"` while
-  an anchored popup must escape the region's content box, then return to the
-  normal overflow policy when it closes.
+  `--kui-resizable-region-background`; an open descendant `PopupMenu` or Web
+  Awesome dropdown releases clipping and raises the popup layer for its
+  lifecycle. Set `contentOverflow="visible"` for other anchored content that
+  must escape the region's content box.
   Overlay presentation also clamps fixed-size animated content to the configured
   responsive overlay maximum, so a remembered desktop size cannot escape a narrow
   viewport.

package/docs/component-selection.md

@@ -176,10 +176,16 @@ an upstream component or recipe request.
 
 ## Ambiguous choices
 
+For a lowered background behind an entire scrolling work area, choose
+`Pane appearance="sunken"` or the appearance option on the layout that owns
+the scroll viewport. Use `SunkenPanel` for a padded content group that does
+not introduce scrolling. See [Lowered work surfaces](./layout.md#lowered-work-surfaces).
+
 Set `ResizableRegion`'s `--kui-resizable-region-background` for an inline
-surface. Use `contentOverflow="visible"` while an anchored popup must escape
-the region; this also raises the region on its public popup layer. A collapsed
-region can place `restoreControl` in a top or bottom corner with
+surface. An open descendant `PopupMenu` or Web Awesome dropdown automatically
+releases clipping and raises the region on its public popup layer. Set
+`contentOverflow="visible"` for other anchored content that must escape the
+region. A collapsed region can place `restoreControl` in a top or bottom corner with
 `restorePosition`, set its typed `restoreInset`, or use
 `restorePlacement="inline"` for a control in normal flow.
 
@@ -212,7 +218,9 @@ name. Disabled and loading links omit `href` and leave the tab order. Use
 Use `Toolbar responsive="trailing-priority"` for a collapsible search in the
 trailing zone that should take a full second row when expanded. `responsiveAt`
 chooses the compact or narrow container breakpoint. The leading identity stays
-in the first row. `--kui-toolbar-leading-min-width`,
+in the first row. Set `centerAlign="balanced"` when the center zone must sit on
+the toolbar's midpoint despite unequal or empty side content; it gives the
+leading and trailing zones equal tracks. `--kui-toolbar-leading-min-width`,
 `--kui-toolbar-trailing-gap`, `--kui-toolbar-trailing-justify`, and the
 `--kui-toolbar-*-padding-inline` zone tokens adjust local geometry without
 selecting toolbar anatomy from application CSS.
@@ -225,8 +233,10 @@ For compact dialog copy, use `Text flush lineHeight="tight"`; block Text still
 resets native margins. `ValueTable density="compact"` reduces row padding and
 gap. Its `--kui-value-table-row-columns`, `--kui-value-table-row-padding-block`,
 and `--kui-value-table-row-gap` tokens support a specific metadata layout.
-Use `ToolbarText size="xsmall"` for a dense rail heading. A
-`TokenSearchField` editor can shrink to zero minimum width inside a narrow
+Use `ToolbarText size="xsmall"` for a dense rail heading. Use
+`size="xlarge-fixed"` for a toolbar heading at the fixed 20px step; `xlarge`
+retains the responsive page-title clamp. Pass `headingLevel` when the text is
+a section landmark. A `TokenSearchField` editor can shrink to zero minimum width inside a narrow
 group; set `--kui-token-search-editor-min-width` only when a wider editor is
 required.
 
@@ -234,7 +244,11 @@ required.
 - `TabBar` changes tabpanels and supports overflow/reorder; `SegmentedControl` chooses among a few compact views; `Select` handles a longer value list.
 
 Use `AppTab presentation="icon-only"` with its `name` kept as the accessible
-tab name, and `labelMaxWidth` for an ellipsized visible name. Set `attention`
+tab name. For segmented tabs that should show names in a wide reader and icons
+in a narrower container, set `TabBar iconOnlyAt="wide"` (832px), `"narrow"`
+(704px), or `"compact"` (448px), and give each segmented `AppTab` a leading
+icon. The tablist's own width controls the switch; the visually hidden name
+remains its accessible name. Use `labelMaxWidth` for an ellipsized visible name. Set `attention`
 to color a tab's name with `--kui-app-tab-attention-color`. Set `dropTarget`
 while an app drag is over a tab's content; the tab keeps its selection semantics
 and uses the `--kui-app-tab-drop-target-*` tokens for its highlight. Set
@@ -246,7 +260,9 @@ its internal classes. `--kui-tab-bar-trailing-flex` controls the trailing zone.
 Set `pinned` on the first `AppTab` when that tab must remain visible as peers
 scroll. It stays inside the tablist and keyboard order. Set the public
 `--kui-app-tab-pinned-background` token if the surrounding surface differs from
-the default; the pinned tab must cover peers as they scroll beneath it.
+the default; the pinned tab must cover peers as they scroll beneath it. Call
+`wireTabBars` for keyboard selection and reorder behavior and its WebKit RTL
+scroll correction.
 
 - `StateBanner` persists beside affected work; `EmptyState` replaces absent content; `wa-callout` is contextual ecosystem content; `wa-toast` and `wa-toast-item` are transient and must not carry the only copy of important state.
 
@@ -258,6 +274,9 @@ stacked copy's spacing at an instance boundary.
 
 For a compact `Select`, set `triggerWidth` to `"fit-content"`, `"max-content"`,
 or `"fill"` and cap it with `--kui-select-trigger-max-width` when needed.
+For a round icon-only toolbar trigger, set `selectedPresentation="icon-only"`
+and `caret={false}`. The control keeps its accessible name, current choice help
+tag, and keyboard-operated listbox; the default keeps the visible caret.
 Custom `renderSelected` text inherits the control color by default; the
 `--kui-select-selected-color`, `--kui-select-selected-font-size`, and
 `--kui-select-selected-font-weight` tokens configure its typography. Plain

package/docs/layout.md

@@ -36,6 +36,37 @@ size) tall, and below that lets the whole pane scroll as one column, header,
 content, and footer together, so the content keeps its natural height. The
 default `fixed` always pins them.
 
+### Lowered work surfaces
+
+Set `appearance="sunken"` when the work area itself should use the lowered
+surface color, including blank space below short content and the scroll
+viewport. The default appearance is unchanged. The fixed Pane paints its
+content scroller; with `chromePlacement="auto"`, the Pane root paints the
+surface because it becomes the scroller in a short viewport. Header and footer
+chrome stay on the normal surface. No second scroll container or
+`SunkenPanel` wrapper is needed.
+For custom chrome colors in auto mode, set `--kui-pane-chrome-background`
+on the Pane; it defaults to `--kui-color-surface`.
+
+```tsx
+<Pane appearance="sunken" footer={<Composer />}>
+  <Conversation />
+</Pane>
+```
+
+`PaneConfig.appearance` forwards through Workbench `mainPane`, panel `pane`,
+and CollapsiblePanel `pane`. Workbench also applies that choice to its main or
+panel region when it renders no Pane chrome. Set `appearance: "sunken"` on a
+`NavStackView` or `TabScaffoldTab` when its view or scene owns scrolling.
+For a `SplitView`, put a `Pane` in the list or detail region and set its
+appearance; SplitView only arranges the regions and does not own their scroll.
+Choose the innermost owner when composing layouts.
+
+The color uses `--kui-sunken-panel-background`, falling back to
+`--kui-color-surface-lowered`, just like `SunkenPanel`. Select one scroll owner
+in a nested layout so a translucent override paints once. The public color
+override may be set at a Pane or layout boundary.
+
 Pass any combination of logical sides to `separators`: `block-start`,
 `block-end`, `inline-start`, and `inline-end`. Every line is off by default and
 each enabled side uses `--kui-pane-separator-width` (1px) and

package/docs/nav-stack.md

@@ -60,6 +60,11 @@ optional per-view `bottomToolbar`. The component-level
 The back control appears automatically once the stack has more than one entry;
 `wireNavStack`'s `onBack` is where the app pops its own signal.
 
+Set a view's `appearance: "sunken"` to paint its scroll viewport with the
+shared lowered-surface color, including space after short content. When the
+view holds a `Pane` as its only child, set the appearance on the Pane instead
+if its content owns scrolling. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+
 ## The top toolbar
 
 The top chrome is a real `Toolbar`, so it follows the same zone,

package/docs/split-view.md

@@ -26,6 +26,11 @@ shared interior edge. A pane whose only child is a `Pane` lets that child own
 the insets, and the compact form hands them to its `NavStack`. See
 [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
 
+For a lowered list or detail background, render a `Pane` in that region with
+`appearance="sunken"`. SplitView arranges regions but does not own their
+vertical scroll; its compact NavStack form can use the view's or nested Pane's
+appearance. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+
 ## Responsive by device class
 
 `SplitView` is declarative; the app derives `compact` from the device class and