@kerfjs/ui 4.4.1 → 5.0.0-beta.11

package/dist/wire-catalog.js

@@ -0,0 +1,48 @@
+import { delegate } from 'kerfjs';
+
+// src/wire-catalog.ts
+function wireCatalog(root, {
+  onSelect,
+  onToggleSidebar,
+  onToggleTheme,
+  onToggleSecondary,
+  urlParam,
+  selectAction = "catalog-select",
+  toggleSidebarAction = "catalog-toggle-sidebar",
+  toggleThemeAction = "catalog-toggle-theme",
+  toggleSecondaryAction = "catalog-toggle-secondary"
+}) {
+  const select = (id) => {
+    onSelect(id);
+    const view = root.ownerDocument.defaultView;
+    if (urlParam && view) {
+      const url = new URL(view.location.href);
+      url.searchParams.set(urlParam, id);
+      view.history.replaceState(null, "", url);
+    }
+  };
+  const disposers = [
+    // Sidebar items AND the footer's related-entry popup-menu items both carry
+    // `data-action={selectAction}` + `data-item-id`, so one delegated click covers both.
+    delegate(root, "click", `[data-action="${selectAction}"]`, (_event, element) => {
+      const id = element.dataset.itemId;
+      if (id) select(id);
+    })
+  ];
+  if (onToggleSidebar) {
+    disposers.push(delegate(root, "click", `[data-action="${toggleSidebarAction}"]`, () => onToggleSidebar()));
+  }
+  if (onToggleTheme) {
+    disposers.push(delegate(root, "click", `[data-action="${toggleThemeAction}"]`, () => onToggleTheme()));
+  }
+  if (onToggleSecondary) {
+    disposers.push(delegate(root, "click", `[data-action="${toggleSecondaryAction}"]`, () => onToggleSecondary()));
+  }
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose();
+  };
+}
+
+export { wireCatalog };
+
+//# sourceMappingURL=wire-catalog.js.map

package/dist/wire-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-catalog.ts"],"names":[],"mappings":";;;AA0BO,SAAS,YACd,IAAA,EACA;AAAA,EACE,QAAA;AAAA,EACA,eAAA;AAAA,EACA,aAAA;AAAA,EACA,iBAAA;AAAA,EACA,QAAA;AAAA,EACA,YAAA,GAAe,gBAAA;AAAA,EACf,mBAAA,GAAsB,wBAAA;AAAA,EACtB,iBAAA,GAAoB,sBAAA;AAAA,EACpB,qBAAA,GAAwB;AAC1B,CAAA,EACY;AACZ,EAAA,MAAM,MAAA,GAAS,CAAC,EAAA,KAAe;AAC7B,IAAA,QAAA,CAAS,EAAE,CAAA;AACX,IAAA,MAAM,IAAA,GAAO,KAAK,aAAA,CAAc,WAAA;AAChC,IAAA,IAAI,YAAY,IAAA,EAAM;AACpB,MAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,IAAA,CAAK,SAAS,IAAI,CAAA;AACtC,MAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,QAAA,EAAU,EAAE,CAAA;AACjC,MAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,IAAA,EAAM,EAAA,EAAI,GAAG,CAAA;AAAA,IACzC;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,SAAA,GAA+B;AAAA;AAAA;AAAA,IAGnC,QAAA,CAAS,MAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,YAAY,CAAA,EAAA,CAAA,EAAM,CAAC,QAAQ,OAAA,KAAY;AAC9E,MAAA,MAAM,EAAA,GAAM,QAAwB,OAAA,CAAQ,MAAA;AAC5C,MAAA,IAAI,EAAA,SAAW,EAAE,CAAA;AAAA,IACnB,CAAC;AAAA,GACH;AACA,EAAA,IAAI,eAAA,EAAiB;AACnB,IAAA,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,mBAAmB,CAAA,EAAA,CAAA,EAAM,MAAM,eAAA,EAAiB,CAAC,CAAA;AAAA,EAC3G;AACA,EAAA,IAAI,aAAA,EAAe;AACjB,IAAA,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,iBAAiB,CAAA,EAAA,CAAA,EAAM,MAAM,aAAA,EAAe,CAAC,CAAA;AAAA,EACvG;AACA,EAAA,IAAI,iBAAA,EAAmB;AACrB,IAAA,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,qBAAqB,CAAA,EAAA,CAAA,EAAM,MAAM,iBAAA,EAAmB,CAAC,CAAA;AAAA,EAC/G;AACA,EAAA,OAAO,MAAM;AACX,IAAA,KAAA,MAAW,OAAA,IAAW,SAAA,CAAU,MAAA,CAAO,CAAC,GAAG,OAAA,EAAQ;AAAA,EACrD,CAAA;AACF","file":"wire-catalog.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireCatalogOptions {\n  /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */\n  onSelect: (id: string) => void;\n  /** Invoked when the sidebar collapse/expand control is activated. */\n  onToggleSidebar?: () => void;\n  /** Invoked when the theme toggle is activated. */\n  onToggleTheme?: () => void;\n  /** Invoked when the secondary (ecosystem) group's disclosure toggle is activated. */\n  onToggleSecondary?: () => void;\n  /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */\n  urlParam?: string;\n  selectAction?: string;\n  toggleSidebarAction?: string;\n  toggleThemeAction?: string;\n  toggleSecondaryAction?: string;\n}\n\n/**\n * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar\n * item selection (and the related-entry popup menu), the sidebar collapse toggle, and\n * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates\n * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.\n * Returns a disposer.\n */\nexport function wireCatalog(\n  root: HTMLElement,\n  {\n    onSelect,\n    onToggleSidebar,\n    onToggleTheme,\n    onToggleSecondary,\n    urlParam,\n    selectAction = 'catalog-select',\n    toggleSidebarAction = 'catalog-toggle-sidebar',\n    toggleThemeAction = 'catalog-toggle-theme',\n    toggleSecondaryAction = 'catalog-toggle-secondary',\n  }: WireCatalogOptions,\n): () => void {\n  const select = (id: string) => {\n    onSelect(id);\n    const view = root.ownerDocument.defaultView;\n    if (urlParam && view) {\n      const url = new URL(view.location.href);\n      url.searchParams.set(urlParam, id);\n      view.history.replaceState(null, '', url);\n    }\n  };\n\n  const disposers: Array<() => void> = [\n    // Sidebar items AND the footer's related-entry popup-menu items both carry\n    // `data-action={selectAction}` + `data-item-id`, so one delegated click covers both.\n    delegate(root, 'click', `[data-action=\"${selectAction}\"]`, (_event, element) => {\n      const id = (element as HTMLElement).dataset.itemId;\n      if (id) select(id);\n    }),\n  ];\n  if (onToggleSidebar) {\n    disposers.push(delegate(root, 'click', `[data-action=\"${toggleSidebarAction}\"]`, () => onToggleSidebar()));\n  }\n  if (onToggleTheme) {\n    disposers.push(delegate(root, 'click', `[data-action=\"${toggleThemeAction}\"]`, () => onToggleTheme()));\n  }\n  if (onToggleSecondary) {\n    disposers.push(delegate(root, 'click', `[data-action=\"${toggleSecondaryAction}\"]`, () => onToggleSecondary()));\n  }\n  return () => {\n    for (const dispose of disposers.splice(0)) dispose();\n  };\n}\n"]}

package/dist/wire-nav-stack.d.ts

@@ -0,0 +1,15 @@
+interface WireNavStackOptions {
+    /** Invoked when the back control is activated. The app pops its own stack. */
+    onBack?: () => void;
+    /** Transition duration in ms (default 200). Set 0 to disable animation. */
+    duration?: number;
+}
+/**
+ * Animate a `NavStack`'s push/pop transitions and wire its back control. The app
+ * owns the stack (a signal of `NavStackView[]`) and re-renders `NavStack` when it
+ * changes; this helper slides the content and settles the chrome across each
+ * change, and calls `onBack` when the back control is used. Returns a disposer.
+ */
+declare function wireNavStack(root: Element, options?: WireNavStackOptions): () => void;
+
+export { type WireNavStackOptions, wireNavStack };

package/dist/wire-nav-stack.js

@@ -0,0 +1,88 @@
+import { delegate } from 'kerfjs';
+
+// src/wire-nav-stack.ts
+var DEFAULT_DURATION = 200;
+function viewsOf(viewport) {
+  return Array.from(viewport.querySelectorAll(":scope > .kui-nav-stack__view"));
+}
+function topView(viewport) {
+  const live = viewsOf(viewport).filter((view) => view.dataset.navExiting !== "true");
+  return live[live.length - 1];
+}
+function reducedMotion(view) {
+  return typeof view.matchMedia === "function" && view.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function wireNavStack(root, options = {}) {
+  const section = root.matches('[data-component="nav-stack"]') ? root : root.querySelector('[data-component="nav-stack"]');
+  const viewport = section?.querySelector("[data-nav-stack-viewport]");
+  if (!(section instanceof HTMLElement) || !viewport) return () => {
+  };
+  const view = section.ownerDocument.defaultView ?? window;
+  const duration = options.duration ?? DEFAULT_DURATION;
+  const disposeBack = delegate(section, "click", "[data-nav-back]", () => options.onBack?.());
+  let activeKey = topView(viewport)?.dataset.navKey;
+  const timers = /* @__PURE__ */ new Set();
+  const settle = (fn) => {
+    if (duration <= 0 || reducedMotion(view)) {
+      fn();
+      return;
+    }
+    const timer = view.setTimeout(() => {
+      timers.delete(timer);
+      fn();
+    }, duration);
+    timers.add(timer);
+  };
+  const play = (el, kind) => {
+    const animated = duration > 0 && !reducedMotion(view);
+    if (kind === "entering") {
+      el.classList.add("kui-nav-stack__view--entering");
+      if (animated) {
+        void el.offsetWidth;
+        view.requestAnimationFrame(() => el.classList.remove("kui-nav-stack__view--entering"));
+      } else {
+        el.classList.remove("kui-nav-stack__view--entering");
+      }
+    } else if (animated) {
+      view.requestAnimationFrame(() => el.classList.add("kui-nav-stack__view--exiting"));
+    } else {
+      el.classList.add("kui-nav-stack__view--exiting");
+    }
+  };
+  const observer = new MutationObserver((records) => {
+    const removed = [];
+    let added = false;
+    for (const record of records) {
+      record.removedNodes.forEach((node) => {
+        if (node instanceof HTMLElement && node.classList.contains("kui-nav-stack__view") && node.dataset.navExiting !== "true") removed.push(node);
+      });
+      record.addedNodes.forEach((node) => {
+        if (node instanceof HTMLElement && node.classList.contains("kui-nav-stack__view")) added = true;
+      });
+    }
+    const top = topView(viewport);
+    const currentKey = top?.dataset.navKey;
+    const poppedTop = removed.find((node) => node.dataset.navKey === activeKey);
+    if (poppedTop && currentKey !== activeKey) {
+      poppedTop.dataset.navExiting = "true";
+      poppedTop.setAttribute("aria-hidden", "true");
+      viewport.append(poppedTop);
+      play(poppedTop, "exiting");
+      settle(() => poppedTop.remove());
+    } else if (added && currentKey !== activeKey && top) {
+      play(top, "entering");
+    }
+    activeKey = currentKey;
+  });
+  observer.observe(viewport, { childList: true });
+  return () => {
+    disposeBack();
+    observer.disconnect();
+    for (const timer of timers) view.clearTimeout(timer);
+    timers.clear();
+  };
+}
+
+export { wireNavStack };
+
+//# sourceMappingURL=wire-nav-stack.js.map

package/dist/wire-nav-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-nav-stack.ts"],"names":[],"mappings":"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","file":"wire-nav-stack.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireNavStackOptions {\n  /** Invoked when the back control is activated. The app pops its own stack. */\n  onBack?: () => void;\n  /** Transition duration in ms (default 200). Set 0 to disable animation. */\n  duration?: number;\n}\n\nconst DEFAULT_DURATION = 200;\n\nfunction viewsOf(viewport: Element): HTMLElement[] {\n  return Array.from(viewport.querySelectorAll<HTMLElement>(':scope > .kui-nav-stack__view'));\n}\n\nfunction topView(viewport: Element): HTMLElement | undefined {\n  const live = viewsOf(viewport).filter((view) => view.dataset.navExiting !== 'true');\n  return live[live.length - 1];\n}\n\nfunction reducedMotion(view: Window): boolean {\n  return typeof view.matchMedia === 'function' && view.matchMedia('(prefers-reduced-motion: reduce)').matches;\n}\n\n/**\n * Animate a `NavStack`'s push/pop transitions and wire its back control. The app\n * owns the stack (a signal of `NavStackView[]`) and re-renders `NavStack` when it\n * changes; this helper slides the content and settles the chrome across each\n * change, and calls `onBack` when the back control is used. Returns a disposer.\n */\nexport function wireNavStack(root: Element, options: WireNavStackOptions = {}): () => void {\n  const section = root.matches('[data-component=\"nav-stack\"]') ? root : root.querySelector('[data-component=\"nav-stack\"]');\n  const viewport = section?.querySelector('[data-nav-stack-viewport]');\n  if (!(section instanceof HTMLElement) || !viewport) return () => {};\n\n  const view = section.ownerDocument.defaultView ?? window;\n  const duration = options.duration ?? DEFAULT_DURATION;\n  const disposeBack = delegate(section, 'click', '[data-nav-back]', () => options.onBack?.());\n\n  let activeKey = topView(viewport)?.dataset.navKey;\n  const timers = new Set<number>();\n\n  const settle = (fn: () => void): void => {\n    if (duration <= 0 || reducedMotion(view)) {\n      fn();\n      return;\n    }\n    const timer = view.setTimeout(() => {\n      timers.delete(timer);\n      fn();\n    }, duration);\n    timers.add(timer);\n  };\n\n  const play = (el: HTMLElement, kind: 'entering' | 'exiting'): void => {\n    const animated = duration > 0 && !reducedMotion(view);\n    if (kind === 'entering') {\n      // Push: start the incoming view off the trailing edge, then release it so\n      // it slides to rest (translateX(100%) → 0).\n      el.classList.add('kui-nav-stack__view--entering');\n      if (animated) {\n        // Force a reflow so the starting transform applies before we clear it.\n        void el.offsetWidth;\n        view.requestAnimationFrame(() => el.classList.remove('kui-nav-stack__view--entering'));\n      } else {\n        el.classList.remove('kui-nav-stack__view--entering');\n      }\n    } else if (animated) {\n      // Pop: the outgoing view is at rest; add the off-edge class on the next\n      // frame so it slides OUT (translateX(0) → 100%), not in.\n      view.requestAnimationFrame(() => el.classList.add('kui-nav-stack__view--exiting'));\n    } else {\n      el.classList.add('kui-nav-stack__view--exiting');\n    }\n  };\n\n  const observer = new MutationObserver((records) => {\n    const removed: HTMLElement[] = [];\n    let added = false;\n    for (const record of records) {\n      record.removedNodes.forEach((node) => {\n        if (node instanceof HTMLElement && node.classList.contains('kui-nav-stack__view') && node.dataset.navExiting !== 'true') removed.push(node);\n      });\n      record.addedNodes.forEach((node) => {\n        if (node instanceof HTMLElement && node.classList.contains('kui-nav-stack__view')) added = true;\n      });\n    }\n\n    const top = topView(viewport);\n    const currentKey = top?.dataset.navKey;\n    const poppedTop = removed.find((node) => node.dataset.navKey === activeKey);\n\n    if (poppedTop && currentKey !== activeKey) {\n      // Pop: bring the removed node back briefly to slide it out over the revealed view.\n      poppedTop.dataset.navExiting = 'true';\n      poppedTop.setAttribute('aria-hidden', 'true');\n      viewport.append(poppedTop);\n      play(poppedTop, 'exiting');\n      settle(() => poppedTop.remove());\n    } else if (added && currentKey !== activeKey && top) {\n      // Push: slide the new top in.\n      play(top, 'entering');\n    }\n\n    activeKey = currentKey;\n  });\n  observer.observe(viewport, { childList: true });\n\n  return () => {\n    disposeBack();\n    observer.disconnect();\n    for (const timer of timers) view.clearTimeout(timer);\n    timers.clear();\n  };\n}\n"]}

package/dist/wire-resizable-regions.js

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

package/dist/wire-sidebar.d.ts

@@ -0,0 +1,43 @@
+import { Signal, ReadonlySignal } from 'kerfjs';
+import { DeviceClass } from './device-class.js';
+
+/** Minimal `localStorage`-shaped store, so the persistence hook is testable. */
+interface SidebarStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+interface WireSidebarPanel {
+    /** The panel id — matches `CollapsiblePanel`'s `id` and a toggle's `panelId`. */
+    id: string;
+    /** The app-owned collapsed signal. `wireSidebar` reads it (focus, overlay) and
+     *  writes it (toggle, Escape, backdrop, persistence). */
+    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. */
+    storageKey?: string;
+}
+interface WireSidebarOptions {
+    panels: readonly WireSidebarPanel[];
+    /**
+     * When provided, the sidebar adopts a compact **overlay** presentation while
+     * `deviceClass.compact` is true: an open panel floats over the content with a
+     * 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.
+     */
+    deviceClass?: ReadonlySignal<DeviceClass>;
+    /** Persistence store (default `globalThis.localStorage`, if present). */
+    storage?: SidebarStorage;
+}
+/**
+ * The reusable sidebar-semantics layer for {@link CollapsiblePanel}s: toggle
+ * 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`.
+ */
+declare function wireSidebar(root: HTMLElement, { panels, deviceClass, storage }: WireSidebarOptions): () => void;
+
+export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wireSidebar };

package/dist/wire-sidebar.js

@@ -0,0 +1,117 @@
+import { effect, delegate } from 'kerfjs';
+
+// src/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)];
+}
+function defaultStorage() {
+  try {
+    return globalThis.localStorage ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function wireSidebar(root, { panels, deviceClass, storage = defaultStorage() }) {
+  const ownerDocument = root.ownerDocument;
+  const byAction = new Map(panels.map((panel) => [panel.toggleAction, panel]));
+  const returnFocus = /* @__PURE__ */ new Map();
+  const disposers = [];
+  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 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;
+  }));
+  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();
+      }
+    }));
+  }
+  if (deviceClass) {
+    let backdrop;
+    const openPanel = () => panels.find((panel) => !panel.collapsed.value);
+    const removeBackdrop = () => {
+      backdrop?.remove();
+      backdrop = void 0;
+    };
+    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);
+        }
+      } else {
+        removeBackdrop();
+        if (!compact) delete root.dataset.collapsibleOverlay;
+      }
+    }));
+    const onKeydown = (event) => {
+      if (!deviceClass.value.compact) return;
+      const open = openPanel();
+      if (!open) return;
+      if (event.key === "Escape") {
+        event.preventDefault();
+        collapse(open);
+        return;
+      }
+      if (event.key !== "Tab") return;
+      const element = panelElement(open.id);
+      if (!element) return;
+      const items = focusables(element);
+      if (items.length === 0) return;
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = ownerDocument.activeElement;
+      if (event.shiftKey && active === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    ownerDocument.addEventListener("keydown", onKeydown);
+    disposers.push(() => ownerDocument.removeEventListener("keydown", onKeydown));
+    disposers.push(removeBackdrop);
+  }
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose();
+    delete root.dataset.collapsibleOverlay;
+  };
+}
+
+export { wireSidebar };
+
+//# sourceMappingURL=wire-sidebar.js.map

package/dist/wire-sidebar.js.map

@@ -0,0 +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  /** Persistence store (default `globalThis.localStorage`, if present). */\n  storage?: SidebarStorage;\n}\n\nconst FOCUSABLE = '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(root: HTMLElement, { panels, deviceClass, storage = defaultStorage() }: WireSidebarOptions): () => 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') panel.collapsed.value = stored === 'true';\n    disposers.push(effect(() => {\n      storage.setItem(panel.storageKey!, String(panel.collapsed.value));\n    }));\n  }\n\n  const panelElement = (id: string): HTMLElement | null => 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(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    panel.collapsed.value = !panel.collapsed.value;\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(effect(() => {\n      const collapsed = panel.collapsed.value;\n      if (collapsed === previous) return;\n      previous = collapsed;\n      const element = panelElement(panel.id);\n      if (!collapsed && element) {\n        (focusables(element)[0] ?? element).focus();\n      } else if (collapsed) {\n        returnFocus.get(panel.id)?.focus();\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 => panels.find((panel) => !panel.collapsed.value);\n    const removeBackdrop = (): void => {\n      backdrop?.remove();\n      backdrop = undefined;\n    };\n    disposers.push(effect(() => {\n      const compact = deviceClass.value.compact;\n      const open = compact ? openPanel() : undefined;\n      root.dataset.collapsibleOverlay = String(compact);\n      if (compact && 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', () => collapse(open));\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    const onKeydown = (event: KeyboardEvent): void => {\n      if (!deviceClass.value.compact) 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(() => ownerDocument.removeEventListener('keydown', onKeydown));\n    disposers.push(removeBackdrop);\n  }\n\n  return () => {\n    for (const dispose of disposers.splice(0)) dispose();\n    delete root.dataset.collapsibleOverlay;\n  };\n}\n"]}

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

@@ -7,11 +7,24 @@ interface TabReorder {
     position: TabDropPosition;
     source: TabReorderSource;
 }
+type TabActivation = 'automatic' | 'manual';
 interface WireTabBarsOptions {
     onReorder: (change: TabReorder) => void;
+    /**
+     * How arrow / Home / End keys activate tabs (default `'automatic'`):
+     * - `'automatic'` moves roving focus **and** selects the focused tab (clicks it).
+     * - `'manual'` moves roving focus only; the user selects with Enter / Space / click
+     *   (the ARIA Tabs manual-activation pattern). Use this when activation is a heavy or
+     *   side-effecting action (e.g. a tab that loads a project) so arrowing through the
+     *   strip doesn't trigger it on every tab.
+     *
+     * A per-bar `data-tab-activation="manual" | "automatic"` attribute (see the `TabBar`
+     * `activation` prop) overrides this option for that strip.
+     */
+    activation?: TabActivation;
 }
 declare function reorderTabs<T>(items: readonly T[], getId: (item: T) => string, sourceId: string, targetId: string, position: TabDropPosition): T[];
 /** Wire reordering and keyboard navigation while leaving controlled state in the application. */
-declare function wireTabBars(root: HTMLElement | Document, { onReorder }: WireTabBarsOptions): () => void;
+declare function wireTabBars(root: HTMLElement | Document, { onReorder, activation }: WireTabBarsOptions): () => void;
 
-export { type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
+export { type TabActivation, type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };

package/dist/wire-tab-bars.js

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

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

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

package/dist/wire-tab-scaffold.js

@@ -0,0 +1,16 @@
+import { delegate } from 'kerfjs';
+
+// src/wire-tab-scaffold.ts
+function wireTabScaffold(root, options) {
+  const section = root.matches('[data-component="tab-scaffold"]') ? root : root.querySelector('[data-component="tab-scaffold"]');
+  if (!(section instanceof HTMLElement)) return () => {
+  };
+  return delegate(section, "click", "[data-tab-scaffold-tab]", (_event, target) => {
+    const tabId = target.getAttribute("data-tab-scaffold-tab");
+    if (tabId) options.onSelect(tabId);
+  });
+}
+
+export { wireTabScaffold };
+
+//# sourceMappingURL=wire-tab-scaffold.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-tab-scaffold.ts"],"names":[],"mappings":";;;AAWO,SAAS,eAAA,CAAgB,MAAe,OAAA,EAA6C;AAC1F,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,CAAQ,iCAAiC,IAAI,IAAA,GAAO,IAAA,CAAK,cAAc,iCAAiC,CAAA;AAC7H,EAAA,IAAI,EAAE,OAAA,YAAmB,WAAA,CAAA,EAAc,OAAO,MAAM;AAAA,EAAC,CAAA;AACrD,EAAA,OAAO,SAAS,OAAA,EAAS,OAAA,EAAS,yBAAA,EAA2B,CAAC,QAAQ,MAAA,KAAW;AAC/E,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,YAAA,CAAa,uBAAuB,CAAA;AACzD,IAAA,IAAI,KAAA,EAAO,OAAA,CAAQ,QAAA,CAAS,KAAK,CAAA;AAAA,EACnC,CAAC,CAAA;AACH","file":"wire-tab-scaffold.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireTabScaffoldOptions {\n  /** Invoked with the selected tab id when a bottom-bar tab is activated. */\n  onSelect: (tabId: string) => void;\n}\n\n/**\n * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its\n * id (the app then updates its controlled `active`). Returns a disposer.\n */\nexport function wireTabScaffold(root: Element, options: WireTabScaffoldOptions): () => void {\n  const section = root.matches('[data-component=\"tab-scaffold\"]') ? root : root.querySelector('[data-component=\"tab-scaffold\"]');\n  if (!(section instanceof HTMLElement)) return () => {};\n  return delegate(section, 'click', '[data-tab-scaffold-tab]', (_event, target) => {\n    const tabId = target.getAttribute('data-tab-scaffold-tab');\n    if (tabId) options.onSelect(tabId);\n  });\n}\n"]}

package/dist/wire-token-search-fields.d.ts

@@ -0,0 +1,106 @@
+import { Signal } from 'kerfjs';
+
+interface TokenSearchSubmit {
+    id: string;
+    editor: HTMLElement;
+}
+/** Reported to {@link WireTokenSearchFieldsOptions.onEdit} on every editor input. */
+interface TokenSearchEdit extends TokenSearchSubmit {
+    /**
+     * 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)
+     * without keeping a separate `input` listener.
+     */
+    event: InputEvent;
+}
+/** Reported when adjacent-token keyboard deletion asks the app to drop a chip. */
+interface TokenSearchTokenRemoval {
+    id: string;
+    /** The `data-token-value` of the token the app should remove from its state. */
+    value: string;
+    editor: HTMLElement;
+    /** `'backward'` = the token before the caret (Backspace); `'forward'` = after (Delete). */
+    direction: 'backward' | 'forward';
+}
+/**
+ * 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}
+ * for the caller to apply, while caret movement past a chip is a pure ephemeral
+ * mechanic the helper performs itself.
+ */
+interface TokenSearchKeyboardOptions {
+    /**
+     * 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;
+}
+/**
+ * Managed collapsible behavior for the iconic TokenSearchField. 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 {
+    /** 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. */
+    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`
+     * (or any node inside one) is always exempt, so this predicate is only needed
+     * for surfaces you cannot mark declaratively.
+     */
+    keepOpenOn?: (target: Node | null) => boolean;
+    /** 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;
+    /** Fired on every editor `input`, after the browser mutates it, so a caller can drop its own `input` listener. */
+    onEdit?: (edit: TokenSearchEdit) => 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;
+}
+/**
+ * The value returned from {@link wireTokenSearchFields}: 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 {
+    (): void;
+    dispose(): void;
+    /** The managed `expanded` signal for a field id (adopted or helper-created); undefined when unmanaged. */
+    expanded(id: string): Signal<boolean> | undefined;
+    /** Expand the field (and, when focus is managed, focus its editor). */
+    open(id: string): void;
+    /** Collapse the field (and, when focus is managed, restore focus to its trigger). */
+    close(id: string): void;
+}
+/**
+ * Wire every TokenSearchField 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
+ * exposes the managed `expanded` state per field id.
+ */
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+
+export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };

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

@@ -0,0 +1,5 @@
+export { wireTokenSearchFields } from './chunk-LCOBDOCC.js';
+
+
+
+//# sourceMappingURL=wire-token-search-fields.js.map

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

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

package/dist/workbench.d.ts

@@ -0,0 +1,33 @@
+import { SafeHtml } from 'kerfjs';
+
+/** A collapsible Workbench panel — a side rail or the bottom drawer. */
+interface WorkbenchPanel {
+    content: SafeHtml;
+    /** Whether the panel is currently collapsed (the app owns this). */
+    collapsed?: boolean;
+    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    size?: number;
+    /** Accessible name for the panel region. */
+    label?: string;
+}
+interface WorkbenchProps {
+    id: string;
+    label: string;
+    /** The central work area. */
+    main: SafeHtml;
+    leftRail?: WorkbenchPanel;
+    rightRail?: WorkbenchPanel;
+    bottomDrawer?: WorkbenchPanel;
+    className?: string;
+}
+/**
+ * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
+ * bottom drawer around a central work area (any absent). Collapsing snaps the
+ * panel's track to zero in one reflow while its fixed-size content slides out via
+ * a composited transform — the instant-width / sliding-content technique, so the
+ * work area relayouts once, not per frame. The app owns each `collapsed` flag;
+ * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
+ */
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className }: WorkbenchProps): SafeHtml;
+
+export { Workbench, type WorkbenchPanel, type WorkbenchProps };

package/dist/workbench.js

@@ -0,0 +1,17 @@
+import { jsxs, jsx } from 'kerfjs/jsx-runtime';
+
+// src/workbench.tsx
+function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className = "" }) {
+  return /* @__PURE__ */ jsxs("section", { class: `kui-workbench ${className}`.trim(), id, "data-component": "workbench", "aria-label": label, children: [
+    leftRail && /* @__PURE__ */ jsx("aside", { class: "kui-workbench__rail kui-workbench__rail--left", "data-workbench-rail": "left", "data-collapsed": String(leftRail.collapsed ?? false), "aria-label": leftRail.label || void 0, style: leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : void 0, children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: leftRail.content }) }),
+    /* @__PURE__ */ jsxs("div", { class: "kui-workbench__center", children: [
+      /* @__PURE__ */ jsx("div", { class: "kui-workbench__main", "data-workbench-main": true, children: main }),
+      bottomDrawer && /* @__PURE__ */ jsx("section", { class: "kui-workbench__drawer", "data-workbench-drawer": true, "data-collapsed": String(bottomDrawer.collapsed ?? false), "aria-label": bottomDrawer.label || void 0, style: bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : void 0, children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: bottomDrawer.content }) })
+    ] }),
+    rightRail && /* @__PURE__ */ jsx("aside", { class: "kui-workbench__rail kui-workbench__rail--right", "data-workbench-rail": "right", "data-collapsed": String(rightRail.collapsed ?? false), "aria-label": rightRail.label || void 0, style: rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : void 0, children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: rightRail.content }) })
+  ] });
+}
+
+export { Workbench };
+
+//# sourceMappingURL=workbench.js.map

package/dist/workbench.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":";;;AAgCO,SAAS,SAAA,CAAU,EAAE,EAAA,EAAI,KAAA,EAAO,IAAA,EAAM,UAAU,SAAA,EAAW,YAAA,EAAc,SAAA,GAAY,EAAA,EAAG,EAAmB;AAChH,EAAA,uBAAO,IAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAO,CAAA,cAAA,EAAiB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK,EAAG,EAAA,EAAQ,gBAAA,EAAe,WAAA,EAAY,YAAA,EAAY,KAAA,EACxG,QAAA,EAAA;AAAA,IAAA,QAAA,oBAAY,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,+CAAA,EAAgD,qBAAA,EAAoB,MAAA,EAAO,gBAAA,EAAgB,MAAA,CAAO,QAAA,CAAS,SAAA,IAAa,KAAK,CAAA,EAAG,cAAY,QAAA,CAAS,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,QAAA,CAAS,IAAA,GAAO,CAAA,4BAAA,EAA+B,QAAA,CAAS,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAC3Q,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,QAAA,CAAS,SAAQ,CAAA,EAC9D,CAAA;AAAA,oBACA,IAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EACT,QAAA,EAAA;AAAA,sBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,qBAAA,EAAsB,qBAAA,EAAmB,MAAE,QAAA,EAAA,IAAA,EAAK,CAAA;AAAA,MAC1D,YAAA,oBAAgB,GAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAM,uBAAA,EAAwB,uBAAA,EAAqB,IAAA,EAAC,gBAAA,EAAgB,MAAA,CAAO,YAAA,CAAa,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,YAAA,CAAa,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,YAAA,CAAa,IAAA,GAAO,CAAA,+BAAA,EAAkC,aAAa,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EACvQ,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,YAAA,CAAa,SAAQ,CAAA,EAClE;AAAA,KAAA,EACF,CAAA;AAAA,IACC,SAAA,oBAAa,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,gDAAA,EAAiD,qBAAA,EAAoB,OAAA,EAAQ,gBAAA,EAAgB,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,SAAA,CAAU,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,SAAA,CAAU,IAAA,GAAO,CAAA,4BAAA,EAA+B,UAAU,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAClR,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,SAAA,CAAU,SAAQ,CAAA,EAC/D;AAAA,GAAA,EACF,CAAA;AACF","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: SafeHtml;\n  /** Whether the panel is currently collapsed (the app owns this). */\n  collapsed?: boolean;\n  /** Rail width, or drawer height, in px. Overrides the CSS default. */\n  size?: number;\n  /** Accessible name for the panel region. */\n  label?: string;\n}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: SafeHtml;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  className?: string;\n}\n\n/**\n * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and\n * bottom drawer around a central work area (any absent). Collapsing snaps the\n * panel's track to zero in one reflow while its fixed-size content slides out via\n * a composited transform — the instant-width / sliding-content technique, so the\n * work area relayouts once, not per frame. The app owns each `collapsed` flag;\n * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className = '' }: WorkbenchProps) {\n  return <section class={`kui-workbench ${className}`.trim()} id={id} data-component=\"workbench\" aria-label={label}>\n    {leftRail && <aside class=\"kui-workbench__rail kui-workbench__rail--left\" data-workbench-rail=\"left\" data-collapsed={String(leftRail.collapsed ?? false)} aria-label={leftRail.label || undefined} style={leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n    </aside>}\n    <div class=\"kui-workbench__center\">\n      <div class=\"kui-workbench__main\" data-workbench-main>{main}</div>\n      {bottomDrawer && <section class=\"kui-workbench__drawer\" data-workbench-drawer data-collapsed={String(bottomDrawer.collapsed ?? false)} aria-label={bottomDrawer.label || undefined} style={bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : undefined}>\n        <div class=\"kui-workbench__panel-content\">{bottomDrawer.content}</div>\n      </section>}\n    </div>\n    {rightRail && <aside class=\"kui-workbench__rail kui-workbench__rail--right\" data-workbench-rail=\"right\" data-collapsed={String(rightRail.collapsed ?? false)} aria-label={rightRail.label || undefined} style={rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n    </aside>}\n  </section>;\n}\n"]}