@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/src/chrome/shell-client.ts

@@ -0,0 +1,468 @@
+// The chrome's behaviour — one module, run once per page (./Shell.astro has no client router, so
+// there is no swapped document to re-initialise and no guard against running twice).
+//
+//   · the two collapses: level 1 ⇄ icon rail (⌘⇧B), level 2 open ⇄ closed (⌘B), both (⌘.), each
+//     remembered in localStorage and applied before paint by the inline script in Shell.astro
+//   · the peek: level 2 closed, pointer at the stage's left edge → the panel slides out OVER the
+//     stage, below the navbar, for as long as the pointer stays on it. Over, not beside: pushing
+//     the stage would resize the preview frame and trip its breakpoints
+//   · level 1 groups (Site, Tasks) folding, remembered
+//   · the lab's own light/dark (the moon in level 1)
+//   · the tree: closed groups remembered, scroll restored, the current row kept in view, and the
+//     Sections tree's sort (slot or name), remembered
+//   · search (⌘K) and the filter menu, applied to the tree AND to any cards in the content that
+//     carry the same data-lab-search / data-lab-facets attributes
+//   · j / k: the navbar's own previous/next links when the page has them, the tree's rows when not
+//   · popover menus placed under the button that opened them
+//   · Astro's dev toolbar hidden in every frame, so the lab page's own is the only one
+//
+// Every shortcut asks window.__labIgnoreKey first (../LabHead.astro › THE KEYBOARD GUARD).
+
+declare global {
+  interface Window {
+    __labIgnoreKey?: (event: KeyboardEvent) => boolean;
+    labTheme?: { setTheme: (theme: "light" | "dark") => void; getTheme: () => "light" | "dark" };
+  }
+}
+
+const root = document.documentElement;
+const panel = document.getElementById("lab-l2");
+const page = root.dataset.labPage || "lab";
+
+const read = (key: string, store: Storage = localStorage): string | null => {
+  try {
+    return store.getItem(key);
+  } catch {
+    return null;
+  }
+};
+const write = (key: string, value: string | null, store: Storage = localStorage) => {
+  try {
+    if (value === null) store.removeItem(key);
+    else store.setItem(key, value);
+  } catch {
+    /* private mode — the state holds for this page and is forgotten after */
+  }
+};
+const ignoreKey = (event: KeyboardEvent) => window.__labIgnoreKey?.(event) ?? false;
+
+// ---- the two collapses ---------------------------------------------------------------------------
+// The collapse button's name follows what it will do; the tooltip's title switches in CSS.
+const l1Button = document.querySelector<HTMLElement>(".lab-l1 [data-lab-l1-btn]");
+const nameL1Button = () => l1Button?.setAttribute("aria-label", l1Rail() ? "Expand menu" : "Collapse menu");
+const setL1 = (rail: boolean) => {
+  if (rail) root.dataset.labL1 = "rail";
+  else delete root.dataset.labL1;
+  write("lab-l1", rail ? "rail" : "open");
+  nameL1Button();
+};
+// Level 2's own header button hides the panel when it is docked and keeps it open while it only
+// peeks, so its name says which (decided 2026-09-24: a label must match its action).
+const l2Button = panel?.querySelector<HTMLElement>("[data-lab-l2-btn]");
+const nameL2Button = () => {
+  const label = "labPeek" in root.dataset ? "Keep panel open" : "Hide panel";
+  l2Button?.setAttribute("aria-label", label);
+  l2Button?.setAttribute("title", `${label} · ⌘B`);
+};
+const setL2 = (closed: boolean) => {
+  if (!panel) return;
+  if (closed) root.dataset.labL2 = "closed";
+  else delete root.dataset.labL2;
+  delete root.dataset.labPeek;
+  nameL2Button();
+  write("lab-l2", closed ? "closed" : null);
+};
+const l1Rail = () => root.dataset.labL1 === "rail";
+const l2Closed = () => root.dataset.labL2 === "closed";
+nameL1Button();
+const toggleL1 = () => setL1(!l1Rail());
+const toggleL2 = () => setL2(!l2Closed());
+// Focus mode: both away if either is showing, both back if both are away.
+const toggleFocus = () => {
+  const away = l1Rail() && (l2Closed() || !panel);
+  setL1(!away);
+  setL2(!away);
+};
+
+for (const button of document.querySelectorAll<HTMLElement>("[data-lab-toggle]")) {
+  button.addEventListener("click", () => (button.dataset.labToggle === "l1" ? toggleL1() : toggleL2()));
+}
+
+// Clicking the level 1 item you are already on toggles level 2, rather than reloading the page you
+// are looking at — the activity-bar behaviour.
+if (panel) {
+  for (const link of document.querySelectorAll<HTMLAnchorElement>('.lab-l1 a[aria-current="page"]')) {
+    link.addEventListener("click", (event) => {
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.button !== 0) return;
+      event.preventDefault();
+      toggleL2();
+    });
+  }
+}
+
+// ---- the peek -----------------------------------------------------------------------------------
+// The peek and its trigger strip start where the navbar ends, so the panel covers the stage and
+// never the navbar (decided 2026-09-24). The navbar is one row or two depending on the width it
+// gets, so its height is measured, not assumed.
+const navbar = document.querySelector<HTMLElement>("[data-lab-navbar]");
+if (panel && navbar) {
+  const measure = () => root.style.setProperty("--lab-peek-top", `${navbar.offsetHeight}px`);
+  measure();
+  new ResizeObserver(measure).observe(navbar);
+}
+if (panel) {
+  const zone = document.querySelector<HTMLElement>("[data-lab-peek-zone]");
+  let openTimer = 0;
+  let closeTimer = 0;
+  const peek = (on: boolean) => {
+    if (on && l2Closed()) root.dataset.labPeek = "";
+    else delete root.dataset.labPeek;
+    nameL2Button();
+  };
+  zone?.addEventListener("mouseenter", () => {
+    clearTimeout(closeTimer);
+    openTimer = window.setTimeout(() => peek(true), 120);
+  });
+  zone?.addEventListener("mouseleave", () => clearTimeout(openTimer));
+  panel.addEventListener("mouseenter", () => clearTimeout(closeTimer));
+  panel.addEventListener("mouseleave", () => {
+    if (!("labPeek" in root.dataset)) return;
+    closeTimer = window.setTimeout(() => peek(false), 250);
+  });
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape" && "labPeek" in root.dataset) peek(false);
+  });
+}
+
+// ---- level 1 groups -----------------------------------------------------------------------------
+const GROUPS_KEY = "lab-nav-collapsed";
+const collapsedGroups = new Set<string>((read(GROUPS_KEY) || "").split(",").filter(Boolean));
+for (const group of document.querySelectorAll<HTMLElement>("[data-lab-group]")) {
+  const id = group.dataset.labGroup!;
+  const button = group.querySelector<HTMLButtonElement>("[data-lab-group-toggle]");
+  const apply = (collapsed: boolean) => {
+    group.toggleAttribute("data-collapsed", collapsed);
+    button?.setAttribute("aria-expanded", String(!collapsed));
+  };
+  // The group holding the current page is always open — you are in it.
+  apply(collapsedGroups.has(id) && !group.hasAttribute("data-lab-holds-current"));
+  button?.addEventListener("click", () => {
+    // In the rail the header is an icon whose items fly out on hover; a click goes to the first.
+    if (l1Rail()) {
+      const first = group.querySelector<HTMLAnchorElement>(".lab-nav-group__items a");
+      if (first) location.href = first.href;
+      return;
+    }
+    const collapsed = !group.hasAttribute("data-collapsed");
+    apply(collapsed);
+    if (collapsed) collapsedGroups.add(id);
+    else collapsedGroups.delete(id);
+    write(GROUPS_KEY, [...collapsedGroups].join(",") || null);
+  });
+}
+
+// ---- theme --------------------------------------------------------------------------------------
+// The moon beside the logo: the LAB's light/dark, never the preview's. It is a toggle for dark, so
+// it reports its state as pressed rather than swapping its icon.
+for (const button of document.querySelectorAll<HTMLElement>("[data-lab-theme-toggle]")) {
+  const mark = () => button.setAttribute("aria-pressed", String(window.labTheme?.getTheme() === "dark"));
+  mark();
+  button.addEventListener("click", () => {
+    const next = window.labTheme?.getTheme() === "dark" ? "light" : "dark";
+    window.labTheme?.setTheme(next);
+    mark();
+  });
+}
+
+// ---- the tree -----------------------------------------------------------------------------------
+const tree = document.querySelector<HTMLElement>("[data-lab-tree]");
+const body = document.querySelector<HTMLElement>("[data-lab-l2-body]");
+const CLOSED_KEY = "lab-tree-closed";
+const closedIds = new Set<string>((read(CLOSED_KEY) || "").split("\n").filter(Boolean));
+let searching = false;
+
+const applyStoredOpen = () => {
+  for (const details of tree?.querySelectorAll<HTMLDetailsElement>("details[data-lab-tree-id]") ?? []) {
+    const shut = closedIds.has(details.dataset.labTreeId!) && !details.hasAttribute("data-lab-holds-current");
+    details.open = !shut;
+  }
+};
+
+if (tree) {
+  applyStoredOpen();
+  tree.addEventListener(
+    "toggle",
+    (event) => {
+      const details = event.target as HTMLDetailsElement;
+      const id = details.dataset?.labTreeId;
+      if (!id || searching) return; // a search opens groups; that is not the reader's choice
+      if (details.open) closedIds.delete(id);
+      else closedIds.add(id);
+      write(CLOSED_KEY, [...closedIds].join("\n") || null);
+    },
+    true,
+  );
+}
+
+if (body) {
+  const SCROLL_KEY = `lab-l2-scroll:${page}`;
+  const saved = Number(read(SCROLL_KEY, sessionStorage));
+  if (saved) body.scrollTop = saved;
+  body.addEventListener("scrollend", () => write(SCROLL_KEY, String(body.scrollTop), sessionStorage));
+  const current = tree?.querySelector<HTMLElement>('[aria-current="page"]');
+  current?.scrollIntoView({ block: "nearest" });
+}
+
+// ---- the Sections tree's sort -------------------------------------------------------------------
+// Slot number or Name (A–Z), remembered per viewer. The inline script in Shell.astro already put
+// the stored choice on <html> and CSS `order` drew it; this moves the rows themselves to match, so
+// screen readers, Tab and j / k meet them in the order they are shown. Either way the unslotted
+// group stays under its heading, below the slotted one — the ranks from ./trees.ts guarantee it.
+const SORT_KEY = "lab-tree-sort";
+const stree = document.querySelector<HTMLElement>("[data-lab-stree]");
+if (stree) {
+  const sortItems = [...document.querySelectorAll<HTMLElement>("[data-lab-sort-by]")];
+  const rank = (el: HTMLElement, by: string) =>
+    Number(el.style.getPropertyValue(by === "name" ? "--lab-o-name" : "--lab-o-slot")) || 0;
+  const applySort = (by: string) => {
+    if (by === "name") root.dataset.labSort = "name";
+    else delete root.dataset.labSort;
+    const rows = [...stree.querySelectorAll<HTMLElement>(":scope > li")];
+    rows.sort((a, b) => rank(a, by) - rank(b, by));
+    stree.append(...rows);
+    for (const item of sortItems) item.setAttribute("aria-checked", String(item.dataset.labSortBy === by));
+  };
+  applySort(read(SORT_KEY) === "name" ? "name" : "slot");
+  for (const item of sortItems) {
+    item.addEventListener("click", () => {
+      const by = item.dataset.labSortBy === "name" ? "name" : "slot";
+      write(SORT_KEY, by === "name" ? "name" : null);
+      applySort(by);
+      item.closest<HTMLElement>("[popover]")?.hidePopover?.();
+    });
+  }
+}
+
+// ---- search and filter --------------------------------------------------------------------------
+const search = document.querySelector<HTMLInputElement>("[data-lab-tree-search]");
+const filterButton = document.querySelector<HTMLElement>("[data-lab-filter-btn]");
+const FILTER_KEY = `lab-filter:${page}`;
+let facet = read(FILTER_KEY, sessionStorage) || "";
+
+const matches = (el: HTMLElement, terms: string[]) => {
+  const hay = el.dataset.labSearch || "";
+  if (!terms.every((term) => hay.includes(term))) return false;
+  if (!facet) return true;
+  return (el.dataset.labFacets || "").split(/\s+/).includes(facet);
+};
+
+/** Show a tree node when it, or anything beneath it, matches. Returns whether it is shown. */
+const filterNode = (li: HTMLElement, terms: string[]): boolean => {
+  const children = [...li.querySelectorAll<HTMLElement>(":scope > details > ul > .lab-tree__node")];
+  let shown: boolean;
+  if (children.length) {
+    const any = children.map((child) => filterNode(child, terms)).some(Boolean);
+    // A group whose own name matches shows everything under it (unless a facet is narrowing).
+    shown = any || (!facet && terms.length > 0 && matches(li, terms));
+    if (shown && !any) for (const child of children) showAll(child);
+    const details = li.querySelector<HTMLDetailsElement>(":scope > details");
+    if (details && (terms.length || facet) && any) details.open = true;
+  } else {
+    shown = matches(li, terms);
+  }
+  li.toggleAttribute("data-lab-hidden", !shown);
+  return shown;
+};
+const showAll = (li: HTMLElement) => {
+  li.removeAttribute("data-lab-hidden");
+  for (const child of li.querySelectorAll<HTMLElement>(".lab-tree__node")) child.removeAttribute("data-lab-hidden");
+};
+
+const applyFilter = () => {
+  const text = (search?.value || "").trim().toLowerCase();
+  const terms = text ? text.split(/\s+/) : [];
+  searching = terms.length > 0 || Boolean(facet);
+  if (tree) {
+    if (!searching) applyStoredOpen();
+    for (const li of tree.querySelectorAll<HTMLElement>(":scope > .lab-tree__node")) filterNode(li, terms);
+    // The Sections tree's "Unslotted" heading goes when nothing under it is left to show.
+    for (const heading of tree.querySelectorAll<HTMLElement>(":scope > [data-lab-tree-heading]")) {
+      heading.hidden = !tree.querySelector(':scope > [data-lab-slot-group="unslotted"]:not([data-lab-hidden])');
+    }
+    let empty = tree.parentElement?.querySelector<HTMLElement>("[data-lab-tree-none]");
+    const anyShown = tree.querySelector(":scope > .lab-tree__node:not([data-lab-hidden])");
+    if (!anyShown && tree.children.length) {
+      if (!empty) {
+        empty = document.createElement("p");
+        empty.className = "lab-tree__empty";
+        empty.dataset.labTreeNone = "";
+        empty.textContent = "Nothing matches.";
+        tree.after(empty);
+      }
+    } else empty?.remove();
+  }
+  // The content's cards follow the same search and filter, so one box narrows both.
+  for (const card of document.querySelectorAll<HTMLElement>(".lab-content [data-lab-search]")) {
+    card.toggleAttribute("data-lab-hidden", !matches(card, terms));
+  }
+  for (const section of document.querySelectorAll<HTMLElement>(".lab-content [data-lab-filter-section]")) {
+    const any = section.querySelector("[data-lab-search]:not([data-lab-hidden])");
+    section.hidden = !any;
+  }
+  filterButton?.setAttribute("aria-pressed", String(Boolean(facet)));
+};
+
+search?.addEventListener("input", applyFilter);
+search?.addEventListener("keydown", (event) => {
+  if (event.key !== "Escape") return;
+  if (search.value) {
+    search.value = "";
+    applyFilter();
+  } else search.blur();
+});
+
+const filterItems = [...document.querySelectorAll<HTMLElement>("[data-lab-filter]")];
+const markFilter = () => {
+  for (const item of filterItems) item.setAttribute("aria-checked", String(item.dataset.labFilter === facet));
+};
+if (filterItems.length && !filterItems.some((item) => item.dataset.labFilter === facet)) facet = "";
+for (const item of filterItems) {
+  item.addEventListener("click", () => {
+    facet = item.dataset.labFilter || "";
+    write(FILTER_KEY, facet || null, sessionStorage);
+    markFilter();
+    applyFilter();
+    item.closest<HTMLElement>("[popover]")?.hidePopover?.();
+  });
+}
+markFilter();
+if (facet) applyFilter();
+
+// ---- keys ---------------------------------------------------------------------------------------
+const stepLinks = () => {
+  // A page with its own previous/next (a story or a page view) steps through those.
+  const prev = document.querySelector<HTMLAnchorElement>('a[data-lab-step="prev"]');
+  const next = document.querySelector<HTMLAnchorElement>('a[data-lab-step="next"]');
+  if (prev || next || document.querySelector("[data-lab-step]")) return { prev, next };
+  // Otherwise the tree's visible leaves.
+  const leaves = [...(tree?.querySelectorAll<HTMLAnchorElement>("a[data-lab-leaf]") ?? [])].filter(
+    (a) => a.offsetParent !== null,
+  );
+  const at = leaves.findIndex((a) => a.getAttribute("aria-current") === "page");
+  return {
+    prev: at > 0 ? leaves[at - 1] : at === -1 ? leaves[leaves.length - 1] : null,
+    next: at === -1 ? leaves[0] : leaves[at + 1] ?? null,
+  };
+};
+
+document.addEventListener("keydown", (event) => {
+  const key = event.key.toLowerCase();
+  const mod = event.metaKey || event.ctrlKey;
+
+  // ⌘K stays live inside the lab's own search box, where it means "select what is there".
+  if (mod && key === "k") {
+    if (event.target !== search && ignoreKey(event)) return;
+    if (!search) return;
+    event.preventDefault();
+    if (l2Closed()) setL2(false);
+    search.focus();
+    search.select();
+    return;
+  }
+  if (ignoreKey(event)) return;
+  if (mod && key === "b") {
+    event.preventDefault();
+    if (event.shiftKey) toggleL1();
+    else toggleL2();
+    return;
+  }
+  if (mod && key === ".") {
+    event.preventDefault();
+    toggleFocus();
+    return;
+  }
+  if (mod || event.altKey || event.shiftKey || event.isComposing) return;
+  if (key !== "j" && key !== "k") return;
+  const { prev, next } = stepLinks();
+  const target = key === "j" ? next : prev;
+  if (!target) return;
+  event.preventDefault();
+  target.click();
+});
+
+// ---- popover menus ------------------------------------------------------------------------------
+// Placed under the button that opened them. CSS anchor positioning would do this with no script,
+// but it is not in every browser yet; this is twelve lines.
+for (const menu of document.querySelectorAll<HTMLElement>(".lab-menu[popover]")) {
+  menu.addEventListener("toggle", (event) => {
+    if ((event as ToggleEvent).newState !== "open") return;
+    const invoker = document.querySelector<HTMLElement>(`[popovertarget="${menu.id}"]`);
+    if (!invoker) return;
+    const box = invoker.getBoundingClientRect();
+    const width = menu.offsetWidth;
+    const alignEnd = menu.dataset.labAlign === "end";
+    let left = alignEnd ? box.right - width : box.left;
+    left = Math.max(8, Math.min(left, window.innerWidth - width - 8));
+    let top = box.bottom + 4;
+    if (top + menu.offsetHeight > window.innerHeight - 8) top = Math.max(8, box.top - menu.offsetHeight - 4);
+    menu.style.left = `${left}px`;
+    menu.style.top = `${top}px`;
+  });
+}
+
+// ---- card thumbnails ----------------------------------------------------------------------------
+// Each thumbnail is the real bare render in an <iframe> sized to a virtual viewport
+// (data-frame-w × data-frame-h), scaled down to the card. One observer for all of them.
+const thumbs = document.querySelectorAll<HTMLElement>("[data-frame-w]");
+if (thumbs.length) {
+  const fit = (thumb: HTMLElement) => {
+    const frame = thumb.querySelector<HTMLElement>("iframe");
+    if (!frame) return;
+    const w = Number(thumb.dataset.frameW) || 1440;
+    const h = Number(thumb.dataset.frameH) || 900;
+    const scale = thumb.clientWidth / w;
+    frame.style.width = `${w}px`;
+    frame.style.height = `${h}px`;
+    frame.style.transform = `scale(${scale})`;
+    thumb.style.aspectRatio = `${w} / ${h}`;
+  };
+  const observer = new ResizeObserver((entries) => {
+    for (const entry of entries) fit(entry.target as HTMLElement);
+  });
+  for (const thumb of thumbs) {
+    fit(thumb);
+    observer.observe(thumb);
+  }
+}
+
+// ---- the dev toolbar inside frames --------------------------------------------------------------
+// The dev server puts Astro's toolbar in every page it serves, framed ones included, so without
+// this a lab page shows a second, scaled toolbar over whatever it frames. Decided 2026-09-24: the
+// lab page's own toolbar is the only one — its pin picker already descends into same-origin
+// frames. The bare story hides its own before first paint (../ui/components/preview-layout.astro);
+// this covers the frames the lab does not render itself — the site's pages in the Pages view and
+// its cards, and any page a framed link navigates to. `load` does not bubble, so it is caught on
+// the way down, once per navigation of every frame, present or added later; a frame that finished
+// loading before this module ran is swept once here.
+const hideFramedToolbar = (frame: HTMLIFrameElement) => {
+  try {
+    const doc = frame.contentDocument;
+    if (!doc?.head || doc.getElementById("lab-hide-dev-toolbar")) return;
+    const style = doc.createElement("style");
+    style.id = "lab-hide-dev-toolbar";
+    style.textContent = "astro-dev-toolbar { display: none !important; }";
+    doc.head.append(style);
+  } catch {
+    /* cross-origin — not a lab frame */
+  }
+};
+document.addEventListener(
+  "load",
+  (event) => {
+    if (event.target instanceof HTMLIFrameElement) hideFramedToolbar(event.target);
+  },
+  true,
+);
+for (const frame of document.querySelectorAll("iframe")) hideFramedToolbar(frame);
+
+export {};