@kerfjs/ui 5.0.0-beta.50 → 5.0.0-beta.51

package/dist/text.d.ts

@@ -2,14 +2,14 @@ import * as kerfjs from 'kerfjs';
 import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
+type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
 type TextSize = 'default' | 'compact';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
 type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
-    /** Native heading or paragraph element to render. Defaults to `p`. */
+    /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
     tone?: TextTone;
@@ -24,7 +24,8 @@ type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     className?: string;
 };
 /**
- * Semantic heading or paragraph text with the standard content-item padding.
+ * Semantic heading, paragraph, or inline text. Block variants use the standard
+ * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
 declare function Text({ variant: Variant, tone, size, font, border, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;

package/dist/text.js

@@ -1,3 +1,3 @@
-export { Text } from './chunk-ZNZ2JDBW.js';
+export { Text } from './chunk-7IUSV4XG.js';
 
 //# sourceMappingURL=text.js.map

package/dist/toolbar-text.js

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

package/dist/toolbar.d.ts

@@ -1,5 +1,6 @@
 import * as kerfjs from 'kerfjs';
 import { D as DividerSides } from './divider-sides-BzB6rphT.js';
+import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ToolbarProps {
@@ -11,14 +12,34 @@ interface ToolbarProps {
     dividerSides?: DividerSides;
     /** Horizontal treatment of the center zone. Defaults to centered content. */
     centerAlign?: 'center' | 'stretch';
-    /** Component-owned responsive layout; applications choose the policy rather than restyling toolbar internals. */
-    responsive?: 'none' | 'stack' | 'center-priority';
+    /**
+     * Component-owned responsive layout; applications choose the policy rather
+     * than restyling toolbar internals. Under every policy the trailing zone
+     * wraps its groups instead of clipping an action.
+     * - `none` keeps one row; the leading identity truncates first.
+     * - `stack` stacks the zones at `responsiveAt`, wrapping stacked control
+     *   groups onto further rows.
+     * - `wrap` keeps one row while every zone fits at its natural width, and
+     *   otherwise moves the trailing zone below a whole leading identity.
+     * - `center-priority` gives an expanded center control the full row.
+     */
+    responsive?: 'none' | 'stack' | 'wrap' | 'center-priority';
     /** Container width at which `responsive="stack"` activates. */
     responsiveAt?: 'compact' | 'narrow';
+    /**
+     * Screen edges this toolbar claims for device safe-area compensation, for an
+     * app bar or bottom bar that sits directly at a screen edge rather than in a
+     * Pane header or footer. Each listed side pads by the inset its surrounding
+     * layout reports through `--kui-edge-inset-*`, or the full device inset when
+     * nothing routes that edge, while the toolbar's box and dividers paint
+     * through. Omitted, the toolbar pads only the inline edges an owner such as
+     * a Pane header hands it, and never a block edge.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
 export { DividerSides, Toolbar, type ToolbarProps };

package/dist/toolbar.js

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

package/dist/{types-CzgSrFXP.d.ts → types-CEsieBZi.d.ts}

@@ -40,6 +40,9 @@ interface CatalogBrand {
     /** Logo image URL (rendered decorative). Omit for a text-only brand. */
     logoUrl?: string;
 }
+type CatalogStageRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-stage'?: never;
+}>;
 interface CatalogProps {
     brand: CatalogBrand;
     sections: readonly CatalogSection[];
@@ -52,6 +55,8 @@ interface CatalogProps {
     sidebarFooter?: KerfUiContent;
     status?: KerfUiContent;
     geometryOverlay?: boolean;
+    /** Consumer-owned data attributes applied to the preview stage. */
+    stageRootAttributes?: CatalogStageRootAttributes;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
@@ -61,4 +66,4 @@ interface CatalogProps {
     slot?: string;
 }
 
-export type { CatalogResource as C, CatalogProps as a, CatalogBrand as b, CatalogEntry as c, CatalogRelated as d, CatalogSecondaryGroup as e, CatalogSection as f };
+export type { CatalogResource as C, CatalogProps as a, CatalogBrand as b, CatalogEntry as c, CatalogRelated as d, CatalogSecondaryGroup as e, CatalogSection as f, CatalogStageRootAttributes as g };

package/dist/value-table.js

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

package/dist/wire-resizable-regions.js

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

package/dist/wire-sidebar.d.ts

@@ -14,9 +14,18 @@ interface WireSidebarPanel {
     collapsed: Signal<boolean>;
     /** `data-action` value the panel's toggle button(s) carry. */
     toggleAction: string;
-    /** When set, the collapsed state is loaded from and saved to `storage` under
-     *  this key (a persistence hook), so the panel remembers its state. */
+    /** When set, the panel's inline collapsed state is loaded from and saved to
+     *  `storage` under this key (a persistence hook), so the panel remembers the
+     *  user's inline choice. A compact overlay's open/closed state is transient
+     *  and is never persisted. */
     storageKey?: string;
+    /** The panel's inline (non-compact) collapsed state when `storage` holds no
+     *  choice for it; wire-up seeds the signal with it. Defaults to the signal's
+     *  own value. Set it when the app seeds the signal from the device class
+     *  (`signal(device.value.compact)`) so a compact first render already starts
+     *  collapsed while a later crossing to a wide class still restores this
+     *  inline default. */
+    inlineCollapsed?: boolean;
 }
 interface WireSidebarOptions {
     panels: readonly WireSidebarPanel[];
@@ -26,6 +35,12 @@ interface WireSidebarOptions {
      * dismissable backdrop, Escape and backdrop-click collapse it, and focus is
      * trapped within the open panel (the ARIA dialog pattern). Without it the panel
      * is always inline.
+     *
+     * An overlay is transient and user-initiated: whenever the compact overlay
+     * presentation begins (wire-up on a compact device, or a crossing from a wide
+     * class), every panel starts collapsed so nothing blocks the page until the
+     * user opens it. The inline state is remembered and restored when the device
+     * crosses back to a wide class (and on disposal).
      */
     deviceClass?: ReadonlySignal<DeviceClass>;
     /** Compact devices either overlay the panels (default) or hide them in favor
@@ -41,7 +56,7 @@ interface WireSidebarOptions {
  * delegation with focus restore, focus-into on open, an optional compact overlay
  * (backdrop + Escape + focus trap) driven by {@link deviceClass}, and an optional
  * persistence hook. The app owns each `collapsed` signal and the layout; this wire
- * owns the interaction. Returns a disposer. See `docs/24-collapsible-panel.md`.
+ * owns the interaction. Returns a disposer. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
 declare function wireSidebar(root: HTMLElement, { panels, deviceClass, compactPresentation, exclusiveCompact, storage, }: WireSidebarOptions): () => void;
 

package/dist/wire-sidebar.js

@@ -23,14 +23,41 @@ function wireSidebar(root, {
   const byAction = new Map(panels.map((panel) => [panel.toggleAction, panel]));
   const returnFocus = /* @__PURE__ */ new Map();
   const disposers = [];
+  const adapting = /* @__PURE__ */ new Set();
+  const overlayActive = () => Boolean(deviceClass?.value.compact) && compactPresentation === "overlay";
+  let inlineState;
+  const setAll = (value) => {
+    for (const panel of panels) {
+      const next = value(panel);
+      if (panel.collapsed.peek() === next) continue;
+      adapting.add(panel);
+      panel.collapsed.value = next;
+    }
+  };
+  const restoreInline = () => {
+    const remembered = inlineState;
+    if (!remembered) return;
+    inlineState = void 0;
+    setAll((panel) => remembered.get(panel));
+  };
+  if (overlayActive()) inlineState = /* @__PURE__ */ new Map();
+  for (const panel of panels) {
+    const stored = panel.storageKey && storage ? storage.getItem(panel.storageKey) : null;
+    const seed = stored === "true" || stored === "false" ? stored === "true" : panel.inlineCollapsed;
+    if (inlineState) {
+      inlineState.set(panel, seed ?? panel.collapsed.peek());
+      panel.collapsed.value = true;
+    } else if (seed !== void 0) {
+      panel.collapsed.value = seed;
+    }
+  }
   for (const panel of panels) {
     if (!panel.storageKey || !storage) continue;
-    const stored = storage.getItem(panel.storageKey);
-    if (stored === "true" || stored === "false")
-      panel.collapsed.value = stored === "true";
     disposers.push(
       effect(() => {
-        storage.setItem(panel.storageKey, String(panel.collapsed.value));
+        const collapsed = panel.collapsed.value;
+        if (overlayActive()) return;
+        storage.setItem(panel.storageKey, String(collapsed));
       })
     );
   }
@@ -47,12 +74,21 @@ function wireSidebar(root, {
       returnFocus.set(panel.id, trigger);
       const next = !panel.collapsed.value;
       panel.collapsed.value = next;
-      if (!next && exclusiveCompact && deviceClass?.value.compact && compactPresentation === "overlay") {
+      if (!next && exclusiveCompact && overlayActive()) {
         for (const other of panels)
           if (other !== panel) other.collapsed.value = true;
       }
     })
   );
+  const restoreFocus = (panel) => {
+    const element = panelElement(panel.id);
+    const trigger = returnFocus.get(panel.id);
+    const target = trigger?.isConnected && !element?.contains(trigger) ? trigger : [...root.querySelectorAll("[data-action]")].find(
+      (candidate) => candidate.dataset.action === panel.toggleAction && !element?.contains(candidate)
+    );
+    target?.focus();
+    return target !== void 0;
+  };
   for (const panel of panels) {
     let previous = panel.collapsed.value;
     disposers.push(
@@ -61,48 +97,92 @@ function wireSidebar(root, {
         if (collapsed === previous) return;
         previous = collapsed;
         const element = panelElement(panel.id);
+        if (adapting.delete(panel)) {
+          if (collapsed && element?.contains(ownerDocument.activeElement))
+            restoreFocus(panel);
+          return;
+        }
         const replaced = deviceClass?.value.compact && compactPresentation === "hidden";
         if (!collapsed && element && !replaced) {
           (focusables(element)[0] ?? element).focus();
-        } else if (collapsed) {
-          returnFocus.get(panel.id)?.focus();
+        } else if (collapsed && !restoreFocus(panel)) {
+          globalThis.queueMicrotask(() => {
+            if (panel.collapsed.peek()) restoreFocus(panel);
+          });
         }
       })
     );
   }
   if (deviceClass) {
     let backdrop;
+    let hostResponsive;
+    let hostOverlay;
+    let backdropFor;
     const openPanel = () => panels.find((panel) => !panel.collapsed.value);
     const removeBackdrop = () => {
       backdrop?.remove();
       backdrop = void 0;
+      backdropFor = void 0;
+    };
+    const setHostData = (name, value) => {
+      if (root.dataset[name] === value) return;
+      if (value === void 0) delete root.dataset[name];
+      else root.dataset[name] = value;
+    };
+    const syncHost = () => {
+      setHostData("collapsibleResponsive", hostResponsive);
+      setHostData("collapsibleOverlay", hostOverlay);
+      if (!backdrop || backdropFor === void 0) return;
+      const element = panelElement(backdropFor);
+      if (element && backdrop.nextElementSibling !== element)
+        element.parentElement?.insertBefore(backdrop, element);
     };
     disposers.push(
       effect(() => {
         const compact = deviceClass.value.compact;
         const overlay = compact && compactPresentation === "overlay";
-        const open = overlay ? openPanel() : void 0;
-        root.dataset.collapsibleResponsive = compact ? compactPresentation : "inline";
-        root.dataset.collapsibleOverlay = String(overlay);
-        if (overlay && open) {
+        for (const panel of panels) void panel.collapsed.value;
+        if (overlay && !inlineState) {
+          inlineState = new Map(
+            panels.map((panel) => [panel, panel.collapsed.peek()])
+          );
+          setAll(() => true);
+        } else if (!overlay) {
+          restoreInline();
+        }
+        const open = overlay ? panels.find((panel) => !panel.collapsed.peek()) : void 0;
+        hostResponsive = compact ? compactPresentation : "inline";
+        hostOverlay = compact ? String(overlay) : void 0;
+        if (open) {
           if (!backdrop) {
             backdrop = ownerDocument.createElement("button");
             backdrop.type = "button";
             backdrop.className = "kui-collapsible-panel__backdrop";
             backdrop.setAttribute("aria-label", "Close");
+            backdrop.dataset.morphPreserve = "";
             backdrop.addEventListener("click", () => {
               const current = openPanel();
               if (current) collapse(current);
             });
-            const element = panelElement(open.id);
-            element?.parentElement?.insertBefore(backdrop, element);
           }
+          backdropFor = open.id;
         } else {
           removeBackdrop();
-          if (!compact) delete root.dataset.collapsibleOverlay;
         }
+        syncHost();
       })
     );
+    const observer = new MutationObserver(syncHost);
+    observer.observe(root, {
+      attributes: true,
+      attributeFilter: [
+        "data-collapsible-responsive",
+        "data-collapsible-overlay"
+      ],
+      childList: true,
+      subtree: true
+    });
+    disposers.push(() => observer.disconnect());
     const onKeydown = (event) => {
       if (!deviceClass.value.compact || compactPresentation !== "overlay")
         return;
@@ -137,6 +217,7 @@ function wireSidebar(root, {
   }
   return () => {
     for (const dispose of disposers.splice(0)) dispose();
+    restoreInline();
     delete root.dataset.collapsibleOverlay;
     delete root.dataset.collapsibleResponsive;
   };

package/dist/wire-sidebar.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/wire-sidebar.ts"],"names":[],"mappings":"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","file":"wire-sidebar.js","sourcesContent":["import { delegate, effect, type ReadonlySignal, type Signal } from 'kerfjs';\n\nimport type { DeviceClass } from './device-class.js';\n\n/** Minimal `localStorage`-shaped store, so the persistence hook is testable. */\nexport interface SidebarStorage {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n}\n\nexport interface WireSidebarPanel {\n  /** The panel id — matches `CollapsiblePanel`'s `id` and a toggle's `panelId`. */\n  id: string;\n  /** The app-owned collapsed signal. `wireSidebar` reads it (focus, overlay) and\n   *  writes it (toggle, Escape, backdrop, persistence). */\n  collapsed: Signal<boolean>;\n  /** `data-action` value the panel's toggle button(s) carry. */\n  toggleAction: string;\n  /** When set, the collapsed state is loaded from and saved to `storage` under\n   *  this key (a persistence hook), so the panel remembers its state. */\n  storageKey?: string;\n}\n\nexport interface WireSidebarOptions {\n  panels: readonly WireSidebarPanel[];\n  /**\n   * When provided, the sidebar adopts a compact **overlay** presentation while\n   * `deviceClass.compact` is true: an open panel floats over the content with a\n   * dismissable backdrop, Escape and backdrop-click collapse it, and focus is\n   * trapped within the open panel (the ARIA dialog pattern). Without it the panel\n   * is always inline.\n   */\n  deviceClass?: ReadonlySignal<DeviceClass>;\n  /** Compact devices either overlay the panels (default) or hide them in favor\n   *  of an application-owned responsive replacement. */\n  compactPresentation?: 'overlay' | 'hidden';\n  /** Collapse the other panels when one opens in compact overlay mode. */\n  exclusiveCompact?: boolean;\n  /** Persistence store (default `globalThis.localStorage`, if present). */\n  storage?: SidebarStorage;\n}\n\nconst FOCUSABLE =\n  'a[href],area[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\nfunction focusables(panel: HTMLElement): HTMLElement[] {\n  // Focus only ever targets an OPEN panel, so the selector (which already drops\n  // disabled controls and tabindex=\"-1\") is sufficient without a layout-based\n  // visibility check that a headless DOM can't answer.\n  return [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];\n}\n\nfunction defaultStorage(): SidebarStorage | undefined {\n  try {\n    return globalThis.localStorage ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The reusable sidebar-semantics layer for {@link CollapsiblePanel}s: toggle\n * delegation with focus restore, focus-into on open, an optional compact overlay\n * (backdrop + Escape + focus trap) driven by {@link deviceClass}, and an optional\n * persistence hook. The app owns each `collapsed` signal and the layout; this wire\n * owns the interaction. Returns a disposer. See `docs/24-collapsible-panel.md`.\n */\nexport function wireSidebar(\n  root: HTMLElement,\n  {\n    panels,\n    deviceClass,\n    compactPresentation = 'overlay',\n    exclusiveCompact = true,\n    storage = defaultStorage(),\n  }: WireSidebarOptions,\n): () => void {\n  const ownerDocument = root.ownerDocument;\n  const byAction = new Map(panels.map((panel) => [panel.toggleAction, panel]));\n  const returnFocus = new Map<string, HTMLElement>();\n  const disposers: Array<() => void> = [];\n\n  // Persistence: seed from storage, then mirror on change.\n  for (const panel of panels) {\n    if (!panel.storageKey || !storage) continue;\n    const stored = storage.getItem(panel.storageKey);\n    if (stored === 'true' || stored === 'false')\n      panel.collapsed.value = stored === 'true';\n    disposers.push(\n      effect(() => {\n        storage.setItem(panel.storageKey!, String(panel.collapsed.value));\n      }),\n    );\n  }\n\n  const panelElement = (id: string): HTMLElement | null =>\n    root.querySelector<HTMLElement>(`[data-collapsible-panel=\"${id}\"]`);\n\n  const collapse = (panel: WireSidebarPanel): void => {\n    if (panel.collapsed.value) return;\n    panel.collapsed.value = true;\n  };\n\n  // Toggle delegation. The trigger is remembered so focus restores to it on close.\n  disposers.push(\n    delegate(root, 'click', '[data-action]', (_event, element) => {\n      const trigger = element as HTMLElement;\n      const panel = byAction.get(trigger.dataset.action ?? '');\n      if (!panel) return;\n      returnFocus.set(panel.id, trigger);\n      const next = !panel.collapsed.value;\n      panel.collapsed.value = next;\n      if (\n        !next &&\n        exclusiveCompact &&\n        deviceClass?.value.compact &&\n        compactPresentation === 'overlay'\n      ) {\n        for (const other of panels)\n          if (other !== panel) other.collapsed.value = true;\n      }\n    }),\n  );\n\n  // Focus: move into the panel when it opens; restore to the trigger when it closes.\n  for (const panel of panels) {\n    let previous = panel.collapsed.value;\n    disposers.push(\n      effect(() => {\n        const collapsed = panel.collapsed.value;\n        if (collapsed === previous) return;\n        previous = collapsed;\n        const element = panelElement(panel.id);\n        const replaced =\n          deviceClass?.value.compact && compactPresentation === 'hidden';\n        if (!collapsed && element && !replaced) {\n          (focusables(element)[0] ?? element).focus();\n        } else if (collapsed) {\n          returnFocus.get(panel.id)?.focus();\n        }\n      }),\n    );\n  }\n\n  // Compact overlay: a dismissable backdrop + Escape + focus trap while compact\n  // and a panel is open.\n  if (deviceClass) {\n    let backdrop: HTMLButtonElement | undefined;\n    const openPanel = (): WireSidebarPanel | undefined =>\n      panels.find((panel) => !panel.collapsed.value);\n    const removeBackdrop = (): void => {\n      backdrop?.remove();\n      backdrop = undefined;\n    };\n    disposers.push(\n      effect(() => {\n        const compact = deviceClass.value.compact;\n        const overlay = compact && compactPresentation === 'overlay';\n        const open = overlay ? openPanel() : undefined;\n        root.dataset.collapsibleResponsive = compact\n          ? compactPresentation\n          : 'inline';\n        root.dataset.collapsibleOverlay = String(overlay);\n        if (overlay && open) {\n          if (!backdrop) {\n            backdrop = ownerDocument.createElement('button');\n            backdrop.type = 'button';\n            backdrop.className = 'kui-collapsible-panel__backdrop';\n            backdrop.setAttribute('aria-label', 'Close');\n            backdrop.addEventListener('click', () => {\n              const current = openPanel();\n              if (current) collapse(current);\n            });\n            const element = panelElement(open.id);\n            element?.parentElement?.insertBefore(backdrop, element);\n          }\n        } else {\n          removeBackdrop();\n          if (!compact) delete root.dataset.collapsibleOverlay;\n        }\n      }),\n    );\n\n    const onKeydown = (event: KeyboardEvent): void => {\n      if (!deviceClass.value.compact || compactPresentation !== 'overlay')\n        return;\n      const open = openPanel();\n      if (!open) return;\n      if (event.key === 'Escape') {\n        event.preventDefault();\n        collapse(open);\n        return;\n      }\n      if (event.key !== 'Tab') return;\n      const element = panelElement(open.id);\n      if (!element) return;\n      const items = focusables(element);\n      if (items.length === 0) return;\n      const first = items[0]!;\n      const last = items[items.length - 1]!;\n      const active = ownerDocument.activeElement;\n      if (event.shiftKey && active === first) {\n        event.preventDefault();\n        last.focus();\n      } else if (!event.shiftKey && active === last) {\n        event.preventDefault();\n        first.focus();\n      }\n    };\n    ownerDocument.addEventListener('keydown', onKeydown);\n    disposers.push(() =>\n      ownerDocument.removeEventListener('keydown', onKeydown),\n    );\n    disposers.push(removeBackdrop);\n  }\n\n  return () => {\n    for (const dispose of disposers.splice(0)) dispose();\n    delete root.dataset.collapsibleOverlay;\n    delete root.dataset.collapsibleResponsive;\n  };\n}\n"]}
+{"version":3,"sources":["../src/wire-sidebar.ts"],"names":[],"mappings":"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","file":"wire-sidebar.js","sourcesContent":["import { delegate, effect, type ReadonlySignal, type Signal } from 'kerfjs';\n\nimport type { DeviceClass } from './device-class.js';\n\n/** Minimal `localStorage`-shaped store, so the persistence hook is testable. */\nexport interface SidebarStorage {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n}\n\nexport interface WireSidebarPanel {\n  /** The panel id — matches `CollapsiblePanel`'s `id` and a toggle's `panelId`. */\n  id: string;\n  /** The app-owned collapsed signal. `wireSidebar` reads it (focus, overlay) and\n   *  writes it (toggle, Escape, backdrop, persistence). */\n  collapsed: Signal<boolean>;\n  /** `data-action` value the panel's toggle button(s) carry. */\n  toggleAction: string;\n  /** When set, the panel's inline collapsed state is loaded from and saved to\n   *  `storage` under this key (a persistence hook), so the panel remembers the\n   *  user's inline choice. A compact overlay's open/closed state is transient\n   *  and is never persisted. */\n  storageKey?: string;\n  /** The panel's inline (non-compact) collapsed state when `storage` holds no\n   *  choice for it; wire-up seeds the signal with it. Defaults to the signal's\n   *  own value. Set it when the app seeds the signal from the device class\n   *  (`signal(device.value.compact)`) so a compact first render already starts\n   *  collapsed while a later crossing to a wide class still restores this\n   *  inline default. */\n  inlineCollapsed?: boolean;\n}\n\nexport interface WireSidebarOptions {\n  panels: readonly WireSidebarPanel[];\n  /**\n   * When provided, the sidebar adopts a compact **overlay** presentation while\n   * `deviceClass.compact` is true: an open panel floats over the content with a\n   * dismissable backdrop, Escape and backdrop-click collapse it, and focus is\n   * trapped within the open panel (the ARIA dialog pattern). Without it the panel\n   * is always inline.\n   *\n   * An overlay is transient and user-initiated: whenever the compact overlay\n   * presentation begins (wire-up on a compact device, or a crossing from a wide\n   * class), every panel starts collapsed so nothing blocks the page until the\n   * user opens it. The inline state is remembered and restored when the device\n   * crosses back to a wide class (and on disposal).\n   */\n  deviceClass?: ReadonlySignal<DeviceClass>;\n  /** Compact devices either overlay the panels (default) or hide them in favor\n   *  of an application-owned responsive replacement. */\n  compactPresentation?: 'overlay' | 'hidden';\n  /** Collapse the other panels when one opens in compact overlay mode. */\n  exclusiveCompact?: boolean;\n  /** Persistence store (default `globalThis.localStorage`, if present). */\n  storage?: SidebarStorage;\n}\n\nconst FOCUSABLE =\n  'a[href],area[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\nfunction focusables(panel: HTMLElement): HTMLElement[] {\n  // Focus only ever targets an OPEN panel, so the selector (which already drops\n  // disabled controls and tabindex=\"-1\") is sufficient without a layout-based\n  // visibility check that a headless DOM can't answer.\n  return [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];\n}\n\nfunction defaultStorage(): SidebarStorage | undefined {\n  try {\n    return globalThis.localStorage ?? undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The reusable sidebar-semantics layer for {@link CollapsiblePanel}s: toggle\n * delegation with focus restore, focus-into on open, an optional compact overlay\n * (backdrop + Escape + focus trap) driven by {@link deviceClass}, and an optional\n * persistence hook. The app owns each `collapsed` signal and the layout; this wire\n * owns the interaction. Returns a disposer. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.\n */\nexport function wireSidebar(\n  root: HTMLElement,\n  {\n    panels,\n    deviceClass,\n    compactPresentation = 'overlay',\n    exclusiveCompact = true,\n    storage = defaultStorage(),\n  }: WireSidebarOptions,\n): () => void {\n  const ownerDocument = root.ownerDocument;\n  const byAction = new Map(panels.map((panel) => [panel.toggleAction, panel]));\n  const returnFocus = new Map<string, HTMLElement>();\n  const disposers: Array<() => void> = [];\n  // Panels whose next collapsed change is presentation-driven, not a user\n  // action, so it must not move focus the way a toggle does. A set rather than\n  // a flag: writes made inside an effect are batched, so the focus effects run\n  // after the writer returns.\n  const adapting = new Set<WireSidebarPanel>();\n  const overlayActive = (): boolean =>\n    Boolean(deviceClass?.value.compact) && compactPresentation === 'overlay';\n\n  // Initial-state contract: an overlay is transient and only ever opens on a\n  // user action. Entering the overlay presentation (at wire-up or on a wide →\n  // compact crossing) remembers each panel's inline state and collapses it;\n  // leaving it (compact → wide, or disposal) restores the remembered state.\n  let inlineState: Map<WireSidebarPanel, boolean> | undefined;\n  const setAll = (value: (panel: WireSidebarPanel) => boolean): void => {\n    for (const panel of panels) {\n      const next = value(panel);\n      if (panel.collapsed.peek() === next) continue;\n      adapting.add(panel);\n      panel.collapsed.value = next;\n    }\n  };\n  const restoreInline = (): void => {\n    const remembered = inlineState;\n    if (!remembered) return;\n    inlineState = undefined;\n    setAll((panel) => remembered.get(panel)!);\n  };\n\n  // Seed each panel's inline state from storage or `inlineCollapsed`. On a\n  // compact overlay device the seed is only remembered: the panel starts\n  // collapsed, synchronously and before any effect exists, so the first render\n  // after wire-up already has no overlay open.\n  if (overlayActive()) inlineState = new Map();\n  for (const panel of panels) {\n    const stored =\n      panel.storageKey && storage ? storage.getItem(panel.storageKey) : null;\n    const seed =\n      stored === 'true' || stored === 'false'\n        ? stored === 'true'\n        : panel.inlineCollapsed;\n    if (inlineState) {\n      inlineState.set(panel, seed ?? panel.collapsed.peek());\n      panel.collapsed.value = true;\n    } else if (seed !== undefined) {\n      panel.collapsed.value = seed;\n    }\n  }\n\n  // Persistence mirrors inline changes only. An overlay's open/closed state is\n  // transient, so it is never written.\n  for (const panel of panels) {\n    if (!panel.storageKey || !storage) continue;\n    disposers.push(\n      effect(() => {\n        const collapsed = panel.collapsed.value;\n        if (overlayActive()) return;\n        storage.setItem(panel.storageKey!, String(collapsed));\n      }),\n    );\n  }\n\n  const panelElement = (id: string): HTMLElement | null =>\n    root.querySelector<HTMLElement>(`[data-collapsible-panel=\"${id}\"]`);\n\n  const collapse = (panel: WireSidebarPanel): void => {\n    if (panel.collapsed.value) return;\n    panel.collapsed.value = true;\n  };\n\n  // Toggle delegation. The trigger is remembered so focus restores to it on close.\n  disposers.push(\n    delegate(root, 'click', '[data-action]', (_event, element) => {\n      const trigger = element as HTMLElement;\n      const panel = byAction.get(trigger.dataset.action ?? '');\n      if (!panel) return;\n      returnFocus.set(panel.id, trigger);\n      const next = !panel.collapsed.value;\n      panel.collapsed.value = next;\n      if (!next && exclusiveCompact && overlayActive()) {\n        for (const other of panels)\n          if (other !== panel) other.collapsed.value = true;\n      }\n    }),\n  );\n\n  // Where focus goes when a panel closes: the trigger that toggled it, unless\n  // that trigger sits inside the now-hidden panel (the documented\n  // collapse-inside placement) or was re-rendered away. Then it goes to the\n  // panel's toggle outside it — the always-visible expand toggle, which an app\n  // may render only while the panel is collapsed. Returns whether it moved.\n  const restoreFocus = (panel: WireSidebarPanel): boolean => {\n    const element = panelElement(panel.id);\n    const trigger = returnFocus.get(panel.id);\n    const target =\n      trigger?.isConnected && !element?.contains(trigger)\n        ? trigger\n        : [...root.querySelectorAll<HTMLElement>('[data-action]')].find(\n            (candidate) =>\n              candidate.dataset.action === panel.toggleAction &&\n              !element?.contains(candidate),\n          );\n    target?.focus();\n    return target !== undefined;\n  };\n\n  // Focus: move into the panel when it opens; restore it when it closes.\n  for (const panel of panels) {\n    let previous = panel.collapsed.value;\n    disposers.push(\n      effect(() => {\n        const collapsed = panel.collapsed.value;\n        if (collapsed === previous) return;\n        previous = collapsed;\n        const element = panelElement(panel.id);\n        if (adapting.delete(panel)) {\n          // A presentation change, not a user action: only rescue focus that\n          // the collapse would strand inside the now-hidden panel.\n          if (collapsed && element?.contains(ownerDocument.activeElement))\n            restoreFocus(panel);\n          return;\n        }\n        const replaced =\n          deviceClass?.value.compact && compactPresentation === 'hidden';\n        if (!collapsed && element && !replaced) {\n          (focusables(element)[0] ?? element).focus();\n        } else if (collapsed && !restoreFocus(panel)) {\n          // An app that renders after this effect has not produced its\n          // expand toggle yet; look again once the current batch settles.\n          globalThis.queueMicrotask(() => {\n            if (panel.collapsed.peek()) restoreFocus(panel);\n          });\n        }\n      }),\n    );\n  }\n\n  // Compact overlay: a dismissable backdrop + Escape + focus trap while compact\n  // and a panel is open.\n  if (deviceClass) {\n    let backdrop: HTMLButtonElement | undefined;\n    // The host state this wire owns, recorded so it can be re-applied: the\n    // app re-renders (and morphs) the root for reasons that never touch a\n    // panel signal (a nav selection, say), and a morph strips attributes and\n    // nodes the template doesn't emit.\n    let hostResponsive: string | undefined;\n    let hostOverlay: string | undefined;\n    let backdropFor: string | undefined;\n    const openPanel = (): WireSidebarPanel | undefined =>\n      panels.find((panel) => !panel.collapsed.value);\n    const removeBackdrop = (): void => {\n      backdrop?.remove();\n      backdrop = undefined;\n      backdropFor = undefined;\n    };\n    const setHostData = (\n      name: 'collapsibleResponsive' | 'collapsibleOverlay',\n      value: string | undefined,\n    ): void => {\n      if (root.dataset[name] === value) return;\n      if (value === undefined) delete root.dataset[name];\n      else root.dataset[name] = value;\n    };\n    // Idempotent, so the observer below settles after one corrective write.\n    const syncHost = (): void => {\n      setHostData('collapsibleResponsive', hostResponsive);\n      setHostData('collapsibleOverlay', hostOverlay);\n      if (!backdrop || backdropFor === undefined) return;\n      const element = panelElement(backdropFor);\n      if (element && backdrop.nextElementSibling !== element)\n        element.parentElement?.insertBefore(backdrop, element);\n    };\n    disposers.push(\n      effect(() => {\n        const compact = deviceClass.value.compact;\n        const overlay = compact && compactPresentation === 'overlay';\n        // A crossing adapts the panels here, in the same effect that owns the\n        // host state. Every panel's state is read so an open or close moves\n        // the backdrop; re-renders that touch no panel are covered by the\n        // observer below.\n        for (const panel of panels) void panel.collapsed.value;\n        if (overlay && !inlineState) {\n          inlineState = new Map(\n            panels.map((panel) => [panel, panel.collapsed.peek()]),\n          );\n          setAll(() => true);\n        } else if (!overlay) {\n          restoreInline();\n        }\n        const open = overlay\n          ? panels.find((panel) => !panel.collapsed.peek())\n          : undefined;\n        hostResponsive = compact ? compactPresentation : 'inline';\n        hostOverlay = compact ? String(overlay) : undefined;\n        if (open) {\n          if (!backdrop) {\n            backdrop = ownerDocument.createElement('button');\n            backdrop.type = 'button';\n            backdrop.className = 'kui-collapsible-panel__backdrop';\n            backdrop.setAttribute('aria-label', 'Close');\n            // Injected after render: the morph's removal pass must skip it.\n            backdrop.dataset.morphPreserve = '';\n            backdrop.addEventListener('click', () => {\n              const current = openPanel();\n              if (current) collapse(current);\n            });\n          }\n          backdropFor = open.id;\n        } else {\n          removeBackdrop();\n        }\n        syncHost();\n      }),\n    );\n    const observer = new MutationObserver(syncHost);\n    observer.observe(root, {\n      attributes: true,\n      attributeFilter: [\n        'data-collapsible-responsive',\n        'data-collapsible-overlay',\n      ],\n      childList: true,\n      subtree: true,\n    });\n    disposers.push(() => observer.disconnect());\n\n    const onKeydown = (event: KeyboardEvent): void => {\n      if (!deviceClass.value.compact || compactPresentation !== 'overlay')\n        return;\n      const open = openPanel();\n      if (!open) return;\n      if (event.key === 'Escape') {\n        event.preventDefault();\n        collapse(open);\n        return;\n      }\n      if (event.key !== 'Tab') return;\n      const element = panelElement(open.id);\n      if (!element) return;\n      const items = focusables(element);\n      if (items.length === 0) return;\n      const first = items[0]!;\n      const last = items[items.length - 1]!;\n      const active = ownerDocument.activeElement;\n      if (event.shiftKey && active === first) {\n        event.preventDefault();\n        last.focus();\n      } else if (!event.shiftKey && active === last) {\n        event.preventDefault();\n        first.focus();\n      }\n    };\n    ownerDocument.addEventListener('keydown', onKeydown);\n    disposers.push(() =>\n      ownerDocument.removeEventListener('keydown', onKeydown),\n    );\n    disposers.push(removeBackdrop);\n  }\n\n  return () => {\n    for (const dispose of disposers.splice(0)) dispose();\n    // After every effect is gone, so handing the inline state back cannot\n    // re-create overlay chrome or persist anything.\n    restoreInline();\n    delete root.dataset.collapsibleOverlay;\n    delete root.dataset.collapsibleResponsive;\n  };\n}\n"]}

package/docs/accessibility.md

@@ -10,7 +10,7 @@ These are normative contracts for package components and consuming applications.
 - `ListHeader` owns action naming, disabled state, and disclosure `aria-expanded`. Toggle mode supplies one decorative 18px `DisclosureArrow` when `actionIcon` is omitted; it mirrors `expanded` while the native button's accessible name stays stable. The application must update that controlled state and reveal or hide real content. A valid `count` is visually rendered in an `aria-hidden` neutral pill while the required localized `countLabel` becomes part of the owning heading or disclosure button's accessible name; zero remains a real count. Its narrow `triggerAttributes` slot may describe a native popover or controlled-content relationship with `popoverTarget`, `popoverTargetAction`, `aria-controls`, and `aria-haspopup`; the application owns the target surface and its focus/dismissal behavior.
 - Dispose `wireTabBars` and `wireTokenSearchFields` with their owning view. Disposal cancels queued controlled-render focus restoration, so a torn-down view cannot reclaim focus from its successor.
 - `wireNavStack` moves focus into every newly active top view and remembers the last focused descendant of each mounted view for pop restoration. Mark a preferred initial heading or control with `data-nav-focus` (and `tabindex="-1"` when it is not normally tabbable); otherwise the helper uses the first enabled focusable descendant, then a programmatically focusable view-container fallback.
-- In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; do not reduce the target to the visible icon.
+- In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square; a transparent hit layer extends the pointer target to at least 44 × 44 around that square without moving layout or enlarging the painted surface. Compact headers are 36px tall like the rest of the compact List family, so their action target is 44px wide and clamped to the 36px header height instead of reaching into a neighboring row. Do not reduce the target to the visible icon, and do not force the button itself to 44px.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
 - `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
@@ -29,10 +29,23 @@ adding height or spacing. This also applies to `renderSelected`: selected conten
 stays separate from the control's stable accessible name. Applications do not
 need shadow-DOM patches or extra label styling.
 
-Use `presentation="toolbar-borderless"` with `size="compact"` inside a
-`ToolbarControlGroup`; set `focusRingOwner="group"` when that parent paints the
-composed focus ring. `selectedPresentation="icon-only"` hides only the visible
-selected label—the required `label` or `ariaLabel` still names the combobox.
+Use `presentation="toolbar-borderless"` inside a `ToolbarControlGroup`, with
+`size="compact"` in a compact group; set `focusRingOwner="group"` when that
+parent paints the composed focus ring. `selectedPresentation="icon-only"` hides
+only the visible selected label—the required `label` or `ariaLabel` still names
+the combobox. An icon-only trigger keeps its disclosure caret: the selected icon
+and caret form one pill with the same geometry as a popup-menu `wa-dropdown`
+trigger (8px inline padding on both sides, 12px from the icon to the caret, a
+40px default or 32px compact control height), so the caret still signals a
+choice list. Inside a group the trigger is inset evenly on every side (2px in a
+default group, 1px in a compact one) with a concentric radius; the group grows
+to the trigger's width, so a single group is wider than it is tall and its
+focus ring follows the pill while focused and while its listbox is open.
+Beside other controls in one group, the icon-only trigger is one more segment:
+it keeps the group's gap and its siblings' block inset, height, item radius,
+and hover pill. In a group with per-control rings (`focusRing="control"`, the
+default) it paints the same ring as its sibling buttons, even when
+`focusRingOwner="group"` was set, because no group ring would show focus.
 Navigation selects can use intrinsic `presentation="navigation"` plus
 `labelMaxWidth` for component-owned ellipsis. These props own the control's
 appearance; its parent continues to own outer placement.
@@ -96,7 +109,27 @@ The handle exposes separator role, orientation, name, minimum, maximum, and curr
 - Shift+Arrow in 64 px steps;
 - Home and End for minimum and maximum;
 - primary-pointer drag with clamping;
-- preview callbacks while dragging and one commit callback on release.
+- a visible maximum: when a parent clamps the track below the requested size
+  (a `max-width` stage, a narrow container), pointer and keyboard resizing stop
+  at the size actually shown, and the handle announces that size in
+  `aria-valuenow` and that bound in `aria-valuemax`. Focusing the handle
+  reports a stale larger committed size as the shown size without committing
+  it, so the first key press moves the visible separator. The reported values
+  also stay current at rest: a `ResizeObserver` on each region and its parent
+  re-clamps them when the space changes, and a `MutationObserver` re-clamps
+  them after a re-render writes the rendered props back, so assistive
+  technology never reads an unclamped size between interactions (the
+  disposer disconnects both observers);
+- a whole hit target and focus ring at a clamped edge: when the separator has
+  less room past it than the handle's 10px overhang (a parent clamps the track
+  to its own edge), the region carries `data-handle-inset` and the handle sits
+  wholly inside it, so a clipping ancestor cannot cut off half the handle or
+  its focus ring. The ring is drawn inside the handle's box, so the region's
+  ends meeting a clipping edge never shave it either;
+- preview callbacks while dragging and one commit callback on release;
+- a live size that also resizes slide-motion content, so the content tracks the
+  separator during a drag or key press instead of waiting for the app to
+  re-render the committed size.
 
 The application owns persistence and collapsed/expanded policy. Keep the last expanded size outside the component and restore it when reopening. An optional `handleIcon` replaces only decorative dormant content; it must not contain controls or interactive roles because the separator remains the sole focus and interaction owner.
 
@@ -247,9 +280,13 @@ standard per-side collapse/expand glyph (`PanelLeft*` / `PanelRight*` /
 `PanelBottom*`); place a collapse toggle inside the panel and an expand toggle in
 an always-visible location so it is reachable while collapsed. `wireSidebar()`
 moves focus into the panel when it opens and restores it to the trigger when it
-closes. When a `deviceClass()` reports `compact`, an open panel becomes an overlay
+closes; a trigger inside the now-hidden panel hands focus to the panel's toggle
+outside it instead, so an app may render the expand toggle only while the panel
+is collapsed. When a `deviceClass()` reports `compact`, an open panel becomes an overlay
 with a dismissable backdrop, Escape and backdrop-click collapse it, and Tab is
-trapped within it (the ARIA dialog pattern). The application owns each `collapsed`
+trapped within it (the ARIA dialog pattern). That modal state only ever begins
+from a user action: at wire-up on a compact device and on a wide → compact
+crossing, every panel starts collapsed, so no page load or resize traps focus. The application owns each `collapsed`
 signal, the panels, their sizes, and content; the wire may persist the collapsed
 state per panel.
 

package/docs/app-layouts.md

@@ -19,6 +19,79 @@ Derive responsiveness from `deviceClass()`: `compact` (a handset or portrait
 tablet) means "one pane at a time"; `atLeast('tablet')` / `atLeast('desktop')`
 gate the roomier presentations.
 
+Full-height shells retain `height: 100%` so they remain embeddable. Give a
+top-level shell a definite height chain by importing `@kerfjs/ui/document.css`
+and applying `.kui-app-root` to the direct mount container; see the
+[document baseline](document-baseline.md). Do not replace an embeddable shell's
+height with `100dvh`.
+
+## Safe areas
+
+On a device with unsafe areas (a notch, rounded corners, a home indicator) and a
+page that opts into them with `<meta name="viewport" content="…, viewport-fit=cover">`,
+the layouts handle the insets for you. There is nothing to configure:
+
+- **Surfaces paint edge to edge.** Pane and panel backgrounds, separators, and
+  dividers run through the unsafe area. A collapsible rail or drawer grows by
+  the inset it reaches, so its content keeps its configured width or height.
+- **Content is padded on the sides it touches.** Inline insets pad the sides a
+  region actually reaches. Block insets become padding _inside_ the scroll
+  container (with matching `scroll-padding`), so content scrolls under the
+  status bar or home indicator but its first and last items can always be
+  scrolled clear.
+- **Interior edges get nothing.** A `Workbench` center next to an expanded rail,
+  a `SplitView` detail beside its list, or a `NavStack` view under its chrome is
+  not inset on that edge. Collapse the rail and the center picks up the edge.
+- **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. 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.
+
+A plain `Pane` follows the same rules. It assumes it may touch every screen edge
+unless its layout says otherwise. When your own markup puts panes side by side,
+say which sides each pane reaches with `safeAreaEdges`:
+
+```tsx
+<div class="app-columns">
+  <Pane label="Library" safeAreaEdges={['block-start', 'block-end', 'inline-start']}>…</Pane>
+  <Pane label="Reader" safeAreaEdges={['block-start', 'block-end', 'inline-end']}>…</Pane>
+</div>
+```
+
+An app bar or bottom bar that sits directly at a screen edge, outside any
+`Pane` header or footer, claims its edges the same way. A `Toolbar` only pads
+the inline edges an owner hands it until you list the sides it reaches:
+
+```tsx
+<List fill>
+  <Toolbar
+    label="App bar"
+    safeAreaEdges={['block-start', 'inline-start', 'inline-end']}
+    leading={<ToolbarText text="Atlas" />}
+  />
+  <Row gap="none" flex>…panes that list block-end and their outer side…</Row>
+</List>
+```
+
+Each claimed side pads by the edge context, or the full device inset when
+nothing routes that edge, while the bar's surface and divider still reach the
+screen edge. A claimed toolbar inside a `Pane` header or footer adds nothing
+extra, because the pane already owns those edges.
+
+Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. For a
+region you own, set `--kui-edge-inset-block-start`, `--kui-edge-inset-block-end`,
+`--kui-edge-inset-inline-start`, or `--kui-edge-inset-inline-end` to `0px` on the
+region for each edge it does not reach, and kerf descendants follow. A
+`CollapsiblePanel` does this for its direct flex siblings automatically. A
+panel wrapped in your own grid cell cannot see its siblings, so route those
+edges yourself.
+
+The device insets come from `--kui-safe-area-block-start`, `-block-end`,
+`-inline-start`, and `-inline-end`, which default to `env(safe-area-inset-*)`.
+Override them on `:root` to reserve room for app-owned chrome or to simulate a
+device in tests.
+
 ## Decision matrix
 
 | Situation                                                                    | Layout                                                                                          | Device threshold                                                                                                                   |