@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/dist/wire-pane-chrome.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/layout/pane/wiring/wire-pane-chrome.ts"],"names":[],"mappings":"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","file":"wire-pane-chrome.js","sourcesContent":["import { effect, type Signal } from 'kerfjs';\n\n/** The app-owned open state of a Pane's `overlay` compact chrome. */\nexport interface WirePaneChromeOptions {\n  /** The signal the Pane renders as `compactChromeOpen.header`. */\n  header?: Signal<boolean>;\n  /** The signal the Pane renders as `compactChromeOpen.footer`. */\n  footer?: Signal<boolean>;\n}\n\ntype Slot = 'header' | 'footer';\n\n/**\n * Make a Pane's open `overlay` compact chrome transient, like a Workbench's\n * overlay rail: Escape, or a press that starts and ends outside the open\n * chrome, sets its signal back to false, and focus left inside the closed\n * chrome returns to the control that had focus when it opened. `root` holds\n * the Pane (its NavStack, dialog, or Workbench); the app still opens the\n * chrome from its own control, and a press on that control toggles as usual\n * because the dismissal is decided at the click. Returns a disposer.\n */\nexport function wirePaneChrome(\n  root: HTMLElement,\n  { header, footer }: WirePaneChromeOptions,\n): () => void {\n  const doc = root.ownerDocument;\n  const slots = (\n    [\n      ['header', header],\n      ['footer', footer],\n    ] as const\n  ).filter((entry): entry is [Slot, Signal<boolean>] => entry[1] !== undefined);\n  const elementOf = (slot: Slot) =>\n    root.querySelector<HTMLElement>(\n      `.kui-pane[data-compact-${slot}=\"overlay\"] > .kui-pane__${slot}`,\n    );\n  const open = () => slots.filter(([, state]) => state.peek());\n  const openers = new Map<Slot, Element | null>();\n\n  const stops = slots.map(([slot, state]) => {\n    let was = state.peek();\n    return effect(() => {\n      const now = state.value;\n      if (now && !was) openers.set(slot, doc.activeElement);\n      if (!now && was) {\n        // Focus stranded in the closed chrome goes back to its opener.\n        const element = elementOf(slot);\n        const opener = openers.get(slot);\n        if (\n          element?.contains(doc.activeElement) &&\n          opener instanceof HTMLElement\n        )\n          opener.focus({ preventScroll: true });\n        openers.delete(slot);\n      }\n      was = now;\n    });\n  });\n\n  const onKeydown = (event: KeyboardEvent) => {\n    if (event.key !== 'Escape' || event.defaultPrevented) return;\n    const shown = open();\n    if (shown.length === 0) return;\n    event.preventDefault();\n    // The chrome holding focus closes first; otherwise the last one opened.\n    const [, state] =\n      shown.find(([slot]) => elementOf(slot)?.contains(doc.activeElement)) ??\n      shown[shown.length - 1]!;\n    state.value = false;\n  };\n\n  let pressed: Slot[] = [];\n  const outside = (slot: Slot, path: EventTarget[]) => {\n    const element = elementOf(slot);\n    return !element || !path.includes(element);\n  };\n  const onPointerdown = (event: PointerEvent) => {\n    const path = event.composedPath();\n    pressed = open()\n      .map(([slot]) => slot)\n      .filter((slot) => outside(slot, path));\n  };\n  const onClick = (event: MouseEvent) => {\n    const candidates = pressed;\n    pressed = [];\n    const path = event.composedPath();\n    for (const [slot, state] of open())\n      if (candidates.includes(slot) && outside(slot, path)) state.value = false;\n  };\n\n  doc.addEventListener('keydown', onKeydown);\n  doc.addEventListener('pointerdown', onPointerdown, true);\n  doc.addEventListener('click', onClick);\n  return () => {\n    for (const stop of stops) stop();\n    doc.removeEventListener('keydown', onKeydown);\n    doc.removeEventListener('pointerdown', onPointerdown, true);\n    doc.removeEventListener('click', onClick);\n  };\n}\n"]}

package/dist/wire-resizable-regions.d.ts

@@ -9,7 +9,8 @@ interface WireResizableRegionsOptions {
     onPreview?: (change: ResizeCommit) => void;
     onCommit: (change: ResizeCommit) => void;
 }
+
 /** Wire pointer and separator-keyboard behavior for every ResizableRegion below root. */
-declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit }: WireResizableRegionsOptions): () => void;
+declare function wireResizableRegions(root: HTMLElement, options: WireResizableRegionsOptions): () => void;
 
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };

package/dist/wire-resizable-regions.js

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

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

@@ -0,0 +1,87 @@
+/**
+ * An app-owned scroll arrangement outside a `Pane`: the `id` of the element
+ * that scrolls and the `id`s of the pinned chrome on each physical side of it.
+ * Each named chrome element shows its divider on the side facing the scroller
+ * while content is scrolled away beyond that side. Ids are resolved below the
+ * wired root on every refresh, so a re-render that replaces an element keeps
+ * the pairing.
+ */
+interface ScrollDividerTarget {
+    /** The `id` of the scrolling element. */
+    scroller: string;
+    /** Chrome above the scroller: shows its bottom divider once scrolled down. */
+    top?: string;
+    /**
+     * Chrome right of the scroller: shows its left divider while content is
+     * hidden beyond the scroller's right edge (never when nothing overflows).
+     */
+    right?: string;
+    /**
+     * Chrome below the scroller: shows its top divider while content is hidden
+     * beyond the scroller's bottom edge (never when nothing overflows).
+     */
+    bottom?: string;
+    /** Chrome left of the scroller: shows its right divider once scrolled right. */
+    left?: string;
+}
+interface WireScrollDividersOptions {
+    /**
+     * App-owned scroll arrangements to pair beyond the ones found by structure
+     * (every `Pane`'s header and footer around its content, every `NavStack`'s
+     * and `TabNavigator`'s chrome around its active region, and every `TabBar`
+     * strip).
+     */
+    targets?: readonly ScrollDividerTarget[];
+}
+type Root = HTMLElement | Document;
+/**
+ * Wire scroll dividers below `root`: a divider between pinned chrome and the
+ * content that scrolls beside it shows only while content is scrolled away
+ * from that edge. Near edges (top, left) hide at the scroll start; far edges
+ * (bottom, right) hide at the scroll end and whenever nothing overflows.
+ *
+ * The wiring only reports scroll state; each component draws its own divider
+ * from it. It writes `data-scroll-overflow` (the edges with hidden content, in
+ * canonical `t`/`r`/`b`/`l` order) on each scroller, and `data-scroll-divider`
+ * (the sides to draw) on each paired chrome element:
+ *
+ * - every `Pane` with a header or footer: its header shows a bottom divider and
+ *   its footer a top divider (drawn by the Pane, per its `chromeDividers`);
+ * - every `NavStack`'s top chrome and bottom toolbar around its active view,
+ *   and every `TabNavigator`'s bar under its active scene: the chrome shows a
+ *   bottom (top chrome) or top (bottom toolbar, bar) divider. The scroller is
+ *   whichever element actually scrolls there: the view or scene itself, or,
+ *   through a sole child with no chrome of its own on that edge, a `Pane`'s
+ *   content or a nested `NavStack` / `TabNavigator` region (a Pane's own header
+ *   or footer draws that boundary instead);
+ * - every `TabBar` strip: the bar draws a divider on each side of the strip
+ *   whose tabs are scrolled out of view;
+ * - each app-owned `targets` pairing: a `Toolbar` or `List` named as chrome
+ *   draws the divider on its facing side.
+ *
+ * It also measures every `Pane` header laid over its content
+ * (`headerPresentation="overlay"`, with fixed chrome placement): it publishes
+ * the header's border-box block size on the Pane root as the inherited
+ * `--kui-scroll-clearance-block-start` context, and marks the root
+ * `data-header-overlay="measured"`, which moves the header over the content
+ * and has the content clear it. The measurement follows the header as it
+ * wraps, zooms, or changes content, and both are restored before paint if a
+ * re-render drops them.
+ *
+ * Structure is re-read after every DOM change below root that can change a
+ * pairing — a structural element or target id added, removed, or re-classed;
+ * mutations inside scrolled content (a row's class, a list's rows) do not
+ * re-read it. Either way the scrollers are re-measured once the next frame
+ * has laid out, before it paints, so a large render never forces a layout
+ * (where `ResizeObserver` is missing, structure is measured at once and
+ * content in the next animation frame) — and a re-render that drops the
+ * attributes gets them back before paint.
+ * Scroll is tracked with one capturing listener per registered root, and size
+ * changes of each scroller and its children with a `ResizeObserver`. Overlapping registrations
+ * share one attribute writer; each disposer removes its registration, and the
+ * final disposer removes the wiring-owned attributes. See
+ * `docs/23-app-layouts.md` §3.7.
+ */
+declare function wireScrollDividers(root: Root, { targets }?: WireScrollDividersOptions): () => void;
+
+export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDividers };

package/dist/wire-scroll-dividers.js

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

package/dist/wire-scroll-dividers.js.map

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

package/dist/{wire-token-search-fields.d.ts → wire-search-fields.d.ts}

@@ -1,11 +1,13 @@
 import { Signal } from 'kerfjs';
+import { b as SearchFieldModel } from './search-field-CrGTN5sa.js';
+import './semantic-content-BbzjvSu9.js';
 
-interface TokenSearchSubmit {
+interface SearchFieldSubmit {
     id: string;
     editor: HTMLElement;
 }
-/** Reported to {@link WireTokenSearchFieldsOptions.onEdit} on every editor input. */
-interface TokenSearchEdit extends TokenSearchSubmit {
+/** Reported to {@link WireSearchFieldsOptions.onEdit} on every editor input. */
+interface SearchFieldEdit extends SearchFieldSubmit {
     /**
      * The `InputEvent` that mutated the editor — read `event.inputType` / `event.data`
      * to gate commit behavior (e.g. only parse a chip on whitespace-terminated input)
@@ -14,7 +16,7 @@ interface TokenSearchEdit extends TokenSearchSubmit {
     event: InputEvent;
 }
 /** Reported when adjacent-token keyboard deletion asks the app to drop a chip. */
-interface TokenSearchTokenRemoval {
+interface SearchFieldTokenRemoval {
     id: string;
     /** The `data-token-value` of the token the app should remove from its state. */
     value: string;
@@ -25,44 +27,49 @@ interface TokenSearchTokenRemoval {
 /**
  * Opt-in keyboard behavior for the atomic token chips. Off unless `keyboard` is
  * set; each piece defaults on once opted in. The helper never mutates app state:
- * a removal is reported through {@link TokenSearchKeyboardOptions.onRemoveToken}
+ * a removal is reported through {@link SearchFieldKeyboardOptions.onRemoveToken}
  * for the caller to apply, while caret movement past a chip is a pure ephemeral
  * mechanic the helper performs itself.
  */
-interface TokenSearchKeyboardOptions {
+interface SearchFieldKeyboardBaseOptions {
     /**
      * From a collapsed caret with no selection, Backspace removes the token
      * immediately before it and Delete the token immediately after — reported via
      * `onRemoveToken` — instead of deleting a character. Default: true.
      */
-    removeAdjacentToken?: boolean;
     /**
      * ArrowRight moves the caret past a trailing atomic token so text typed next
      * lands after the chip. Default: true.
      */
     moveCaretPastToken?: boolean;
-    /** Apply the reported removal to your controlled state, then re-render. */
-    onRemoveToken?: (removal: TokenSearchTokenRemoval) => void;
 }
+type SearchFieldKeyboardOptions = SearchFieldKeyboardBaseOptions & ({
+    removeAdjacentToken?: true;
+    /** Apply the reported removal to your controlled state, then re-render. */
+    onRemoveToken: (removal: SearchFieldTokenRemoval) => void;
+} | {
+    removeAdjacentToken: false;
+    onRemoveToken?: never;
+});
 /**
- * Managed collapsible behavior for the iconic TokenSearchField. Every piece is on
+ * Managed collapsible behavior for the iconic SearchField. Every piece is on
  * by default; disable a specific one to own it in the app. Provide `signals` to
  * drive app-owned `expanded` signals per field id instead of helper-created ones.
  */
-interface TokenSearchCollapsibleOptions {
+interface SearchFieldCollapsibleOptions {
     /** Expand the field and focus its editor when the iconic trigger is activated. Default: true. */
     expandOnActivate?: boolean;
     /** Collapse the field when focus leaves it while it is empty. Default: true. */
     collapseOnEmptyBlur?: boolean;
     /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
     collapseOnEscape?: boolean;
-    /** Focus the editor on expand and the trigger on Escape-collapse. Default: true. */
+    /** Focus the editor on expand/controlled clear and the trigger on Escape-collapse. Default: true. */
     manageFocus?: boolean;
     /**
      * Keep an empty field expanded when focus moves to a caller-owned surface
      * rendered outside the field — a suggestions dropdown, date picker, or help
      * popover shown beside it. Return true for any focus target that must NOT
-     * trigger collapse-on-empty-blur. An element carrying `data-token-search-keep-open`
+     * trigger collapse-on-empty-blur. An element carrying `data-search-field-keep-open`
      * (or any node inside one) is always exempt, so this predicate is only needed
      * for surfaces you cannot mark declaratively.
      */
@@ -70,22 +77,24 @@ interface TokenSearchCollapsibleOptions {
     /** App-owned `expanded` signals keyed by field id; adopted instead of helper-created. */
     signals?: Readonly<Record<string, Signal<boolean>>>;
 }
-interface WireTokenSearchFieldsOptions {
-    onSubmit?: (submission: TokenSearchSubmit) => void;
+interface WireSearchFieldsOptions {
+    /** Optional automatic grammar/suggestion models, keyed by SearchField id. */
+    models?: Readonly<Record<string, SearchFieldModel>>;
+    onSubmit?: (submission: SearchFieldSubmit) => void;
     /** Fired on every editor `input`, after the browser mutates it, so a caller can drop its own `input` listener. */
-    onEdit?: (edit: TokenSearchEdit) => void;
+    onEdit?: (edit: SearchFieldEdit) => void;
     /** Managed collapsible transient behavior. `true`/omitted = on with defaults; `false` = fully off. */
-    collapsible?: boolean | TokenSearchCollapsibleOptions;
-    /** Opt-in atomic-chip keyboard behavior (off by default). `true` = on with defaults. */
-    keyboard?: boolean | TokenSearchKeyboardOptions;
+    collapsible?: boolean | SearchFieldCollapsibleOptions;
+    /** Opt-in atomic-chip keyboard behavior (off by default). */
+    keyboard?: false | SearchFieldKeyboardOptions;
 }
 /**
- * The value returned from {@link wireTokenSearchFields}: call it (or `dispose()`) to
+ * The value returned from {@link wireSearchFields}: call it (or `dispose()`) to
  * tear down. When collapsible behavior is managed, it also exposes the transient
  * `expanded` state per field id so the app can read it in render, hand in its own
  * signal, or drive it imperatively.
  */
-interface TokenSearchFieldsHandle {
+interface SearchFieldsHandle {
     (): void;
     dispose(): void;
     /** The managed `expanded` signal for a field id (adopted or helper-created); undefined when unmanaged. */
@@ -96,11 +105,11 @@ interface TokenSearchFieldsHandle {
     close(id: string): void;
 }
 /**
- * Wire every TokenSearchField under `root`: submit on Enter, preserve the caret across
+ * Wire every SearchField under `root`: submit on Enter, preserve the caret across
  * controlled token deletion, and (by default) manage the collapsible field's transient
- * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
+ * expand/collapse/focus. Returns a {@link SearchFieldsHandle} — a disposer that also
  * exposes the managed `expanded` state per field id.
  */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+declare function wireSearchFields(root: HTMLElement, { models, onSubmit, onEdit, collapsible, keyboard, }?: WireSearchFieldsOptions): SearchFieldsHandle;
 
-export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
+export { type SearchFieldCollapsibleOptions, type SearchFieldEdit, type SearchFieldKeyboardOptions, type SearchFieldSubmit, type SearchFieldTokenRemoval, type SearchFieldsHandle, type WireSearchFieldsOptions, wireSearchFields };

package/dist/wire-search-fields.js

@@ -0,0 +1,6 @@
+export { wireSearchFields } from './chunk-UMNHJSIO.js';
+
+
+
+
+//# sourceMappingURL=wire-search-fields.js.map

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

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

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,8 +35,19 @@ 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
+     *  of an application-owned responsive replacement. */
+    compactPresentation?: 'overlay' | 'hidden';
+    /** Collapse the other panels when one opens in compact overlay mode. */
+    exclusiveCompact?: boolean;
     /** Persistence store (default `globalThis.localStorage`, if present). */
     storage?: SidebarStorage;
 }
@@ -36,8 +56,8 @@ 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, storage }: WireSidebarOptions): () => void;
+declare function wireSidebar(root: HTMLElement, { panels, deviceClass, compactPresentation, exclusiveCompact, storage, }: WireSidebarOptions): () => void;
 
 export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wireSidebar };

package/dist/wire-sidebar.js

@@ -1,6 +1,6 @@
 import { effect, delegate } from 'kerfjs';
 
-// src/wire-sidebar.ts
+// src/components/layout/collapsible-panel/wiring/wire-sidebar.ts
 var FOCUSABLE = 'a[href],area[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
 function focusables(panel) {
   return [...panel.querySelectorAll(FOCUSABLE)];
@@ -12,73 +12,183 @@ function defaultStorage() {
     return void 0;
   }
 }
-function wireSidebar(root, { panels, deviceClass, storage = defaultStorage() }) {
+function wireSidebar(root, {
+  panels,
+  deviceClass,
+  compactPresentation = "overlay",
+  exclusiveCompact = true,
+  storage = defaultStorage()
+}) {
   const ownerDocument = root.ownerDocument;
   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));
-    }));
+    disposers.push(
+      effect(() => {
+        const collapsed = panel.collapsed.value;
+        if (overlayActive()) return;
+        storage.setItem(panel.storageKey, String(collapsed));
+      })
+    );
   }
   const panelElement = (id) => root.querySelector(`[data-collapsible-panel="${id}"]`);
   const collapse = (panel) => {
     if (panel.collapsed.value) return;
     panel.collapsed.value = true;
   };
-  disposers.push(delegate(root, "click", "[data-action]", (_event, element) => {
-    const trigger = element;
-    const panel = byAction.get(trigger.dataset.action ?? "");
-    if (!panel) return;
-    returnFocus.set(panel.id, trigger);
-    panel.collapsed.value = !panel.collapsed.value;
-  }));
+  disposers.push(
+    delegate(root, "click", "[data-action]", (_event, element) => {
+      const trigger = element;
+      const panel = byAction.get(trigger.dataset.action ?? "");
+      if (!panel) return;
+      returnFocus.set(panel.id, trigger);
+      const next = !panel.collapsed.value;
+      panel.collapsed.value = next;
+      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(effect(() => {
-      const collapsed = panel.collapsed.value;
-      if (collapsed === previous) return;
-      previous = collapsed;
-      const element = panelElement(panel.id);
-      if (!collapsed && element) {
-        (focusables(element)[0] ?? element).focus();
-      } else if (collapsed) {
-        returnFocus.get(panel.id)?.focus();
-      }
-    }));
+    disposers.push(
+      effect(() => {
+        const collapsed = panel.collapsed.value;
+        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({ preventScroll: true });
+        } else if (collapsed && !restoreFocus(panel)) {
+          const retry = (frames) => {
+            if (!panel.collapsed.peek() || restoreFocus(panel) || frames === 0)
+              return;
+            globalThis.requestAnimationFrame(() => retry(frames - 1));
+          };
+          globalThis.queueMicrotask(() => retry(3));
+        }
+      })
+    );
   }
   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 open = compact ? openPanel() : void 0;
-      root.dataset.collapsibleOverlay = String(compact);
-      if (compact && open) {
-        if (!backdrop) {
-          backdrop = ownerDocument.createElement("button");
-          backdrop.type = "button";
-          backdrop.className = "kui-collapsible-panel__backdrop";
-          backdrop.setAttribute("aria-label", "Close");
-          backdrop.addEventListener("click", () => collapse(open));
-          const element = panelElement(open.id);
-          element?.parentElement?.insertBefore(backdrop, element);
+    disposers.push(
+      effect(() => {
+        const compact = deviceClass.value.compact;
+        const overlay = compact && compactPresentation === "overlay";
+        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();
         }
-      } else {
-        removeBackdrop();
-        if (!compact) delete root.dataset.collapsibleOverlay;
-      }
-    }));
+        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);
+            });
+          }
+          backdropFor = open.id;
+        } else {
+          removeBackdrop();
+        }
+        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) return;
+      if (!deviceClass.value.compact || compactPresentation !== "overlay")
+        return;
       const open = openPanel();
       if (!open) return;
       if (event.key === "Escape") {
@@ -103,12 +213,16 @@ function wireSidebar(root, { panels, deviceClass, storage = defaultStorage() })
       }
     };
     ownerDocument.addEventListener("keydown", onKeydown);
-    disposers.push(() => ownerDocument.removeEventListener("keydown", onKeydown));
+    disposers.push(
+      () => ownerDocument.removeEventListener("keydown", onKeydown)
+    );
     disposers.push(removeBackdrop);
   }
   return () => {
     for (const dispose of disposers.splice(0)) dispose();
+    restoreInline();
     delete root.dataset.collapsibleOverlay;
+    delete root.dataset.collapsibleResponsive;
   };
 }