@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/src/chrome/viewport-client.ts

@@ -0,0 +1,405 @@
+// The viewport — the controls in the navbar (./ViewportControls.astro) driving the canvas
+// (./ViewportStage.astro). Ported from the standalone viewport configurator, which it replaces.
+//
+// State is { w, h, z }: the frame's LOGICAL size in CSS px, and the zoom — a number, or "fit",
+// which is the default and re-fits as the window changes. Precedence on load: the URL
+// (?w=&h=&z=) > the last size used for this kind of thing (sections, components and pages each
+// remember their own) > the page's defaults. Every committed change (drag end, field change,
+// preset, key) rewrites the URL with replaceState and the memory; a live drag only redraws —
+// Safari throttles replaceState to 100 calls per 30 s, and a drag would spend that in a second.
+//
+// The controls are the device switch and ONE Viewport field (decided 2026-09-24, ASTROL-19 option
+// B): width × height typed in place, and a button naming the band and the zoom that opens the
+// Presets menu — rotate, the breakpoint edges, the devices and the zoom row. Every render
+// announces itself as a `lab:viewport` event on the stage's root, which the pins overlay
+// (./navbar-client.ts) follows.
+//
+// The viewport rides along on every link marked data-lab-keep-viewport (the variant menu, previous
+// and next), so stepping through variants compares like with like.
+
+declare global {
+  interface Window {
+    __labIgnoreKey?: (event: KeyboardEvent) => boolean;
+  }
+}
+
+const controls = document.querySelector<HTMLElement>("[data-lab-vp-controls]");
+const vp = document.querySelector<HTMLElement>("[data-lab-vp]");
+
+if (controls && vp) {
+  const $ = <T extends Element>(selector: string, scope: ParentNode = document) => scope.querySelector<T>(selector)!;
+  const stage = $<HTMLElement>("[data-lab-vp-stage]", vp);
+  const box = $<HTMLElement>("[data-lab-vp-box]", vp);
+  const wrapper = $<HTMLElement>("[data-lab-vp-wrapper]", vp);
+  const frame = $<HTMLIFrameElement>("[data-lab-vp-frame]", vp);
+  const live = $<HTMLElement>("[data-lab-vp-live]", vp);
+  const field = $<HTMLElement>("[data-lab-vpf]", controls);
+  const inputW = $<HTMLInputElement>("[data-lab-vp-w]", controls);
+  const inputH = $<HTMLInputElement>("[data-lab-vp-h]", controls);
+  const band = $<HTMLElement>("[data-lab-vp-band]", controls);
+  const zoomLabel = $<HTMLElement>("[data-lab-vp-zoom-label]", controls);
+  const menuButton = band.closest<HTMLElement>("button")!;
+  const zoomButtons = [...controls.querySelectorAll<HTMLElement>("[data-lab-vp-zoom]")];
+  const sizeButtons = [...controls.querySelectorAll<HTMLElement>("[data-lab-vp-width]")];
+  const copySize = document.querySelector<HTMLElement>("[data-lab-copy-size]");
+
+  const MIN = 240;
+  const ZOOM_MIN = 0.1;
+  const ZOOM_MAX = 2;
+  const STAGE_PAD = 32;
+  const kind = controls.dataset.kind || "component";
+  const STORE_KEY = `lab-viewport:${kind}`;
+  const defaults = { w: Number(controls.dataset.defaultW) || 1440, h: Number(controls.dataset.defaultH) || 900 };
+  const stepWidths = (controls.dataset.stepWidths || "").split(",").map(Number).filter((n) => n > 0);
+  const breakpoints: { name: string; min: number }[] = (() => {
+    try {
+      return JSON.parse(controls.dataset.breakpoints || "[]");
+    } catch {
+      return [];
+    }
+  })();
+
+  type Zoom = number | "fit";
+  const clampSize = (n: number, fallback: number) => (Number.isFinite(n) && n >= MIN ? Math.round(n) : fallback);
+  const clampZoom = (z: number) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, z));
+  const parseZoom = (raw: unknown, fallback: Zoom): Zoom => {
+    if (raw === "fit") return "fit";
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? clampZoom(n) : fallback;
+  };
+
+  const readStore = (): { w?: number; h?: number; z?: Zoom } => {
+    try {
+      return JSON.parse(localStorage.getItem(STORE_KEY) || "{}") || {};
+    } catch {
+      return {};
+    }
+  };
+
+  const state = (() => {
+    const q = new URLSearchParams(location.search);
+    const fromUrl = q.has("w") || q.has("h") || q.has("z");
+    const base = fromUrl ? {} : readStore();
+    return {
+      w: clampSize(Number(q.get("w") ?? base.w), defaults.w),
+      h: clampSize(Number(q.get("h") ?? base.h), defaults.h),
+      z: parseZoom(q.get("z") ?? base.z, "fit") as Zoom,
+    };
+  })();
+
+  const fitZoom = () => {
+    const availW = Math.max(1, stage.clientWidth - STAGE_PAD * 2);
+    const availH = Math.max(1, stage.clientHeight - STAGE_PAD * 2);
+    // Never enlarge past 100% to "fit": a small component at fit reads at its real size.
+    return Math.min(1, Math.floor(Math.min(availW / state.w, availH / state.h) * 100) / 100);
+  };
+  const scale = () => (state.z === "fit" ? fitZoom() : state.z);
+
+  /** The band a width falls in, and its range — the field names the band, its tooltip the range. */
+  const bandOf = (w: number) => {
+    const i = breakpoints.findIndex((b) => w >= b.min);
+    if (i === -1) return null;
+    const b = breakpoints[i]!;
+    const upper = i > 0 ? breakpoints[i - 1]!.min - 1 : null;
+    const range = upper === null ? `≥ ${b.min}` : b.min === 0 ? `≤ ${upper}` : `${b.min}–${upper}`;
+    return { name: b.name, range };
+  };
+
+  // ---- render ---------------------------------------------------------------------------------
+  const render = () => {
+    const z = scale();
+    wrapper.style.width = `${state.w}px`;
+    wrapper.style.height = `${state.h}px`;
+    wrapper.style.transform = `scale(${z})`;
+    box.style.width = `${Math.round(state.w * z)}px`;
+    box.style.height = `${Math.round(state.h * z)}px`;
+    if (document.activeElement !== inputW) inputW.value = String(state.w);
+    if (document.activeElement !== inputH) inputH.value = String(state.h);
+    live.textContent = `${state.w} × ${state.h}`;
+    const b = bandOf(state.w);
+    band.textContent = b ? b.name : `${state.w}px`;
+    zoomLabel.textContent = state.z === "fit" ? "Fit" : `${Math.round(state.z * 100)}%`;
+    menuButton.title = `${b ? `${b.name} · ${b.range}` : `${state.w}px`} — ${
+      state.z === "fit" ? `Fit · ${Math.round(z * 100)}%` : `${Math.round(z * 100)}%`
+    }. Rotate, breakpoints, devices and zoom.`;
+    if (copySize) copySize.textContent = `${state.w} × ${state.h}`;
+    // Where the frame is now: the device switch presses the width it is at, the menu ticks the edge
+    // or device it matches, and the zoom row the zoom — a width that is none of them presses nothing.
+    for (const button of sizeButtons) {
+      const w = Number(button.dataset.labVpWidth);
+      const h = button.dataset.labVpHeight ? Number(button.dataset.labVpHeight) : null;
+      const on = w === state.w && (h === null || h === state.h);
+      if (button.hasAttribute("aria-pressed")) button.setAttribute("aria-pressed", String(on));
+      else button.setAttribute("aria-checked", String(on));
+    }
+    const zoomValue = state.z === "fit" ? "fit" : String(Math.round(state.z * 100) / 100);
+    for (const button of zoomButtons) button.setAttribute("aria-checked", String(button.dataset.labVpZoom === zoomValue));
+    vp.dispatchEvent(new CustomEvent("lab:viewport", { detail: { w: state.w, h: state.h, z } }));
+  };
+
+  // ---- commit ---------------------------------------------------------------------------------
+  const query = () => {
+    const params = new URLSearchParams(location.search);
+    params.set("w", String(state.w));
+    params.set("h", String(state.h));
+    params.set("z", state.z === "fit" ? "fit" : String(Math.round(state.z * 100) / 100));
+    return params;
+  };
+  const commit = () => {
+    render();
+    const url = new URL(location.href);
+    url.search = query().toString();
+    history.replaceState(history.state, "", url);
+    try {
+      localStorage.setItem(STORE_KEY, JSON.stringify(state));
+    } catch {
+      /* private mode — the URL still carries the state */
+    }
+    for (const link of document.querySelectorAll<HTMLAnchorElement>("a[data-lab-keep-viewport]")) {
+      const target = new URL(link.href, location.href);
+      for (const key of ["w", "h", "z"]) target.searchParams.set(key, url.searchParams.get(key)!);
+      link.href = target.pathname + target.search;
+    }
+  };
+  const setSize = (w: number, h: number) => {
+    state.w = clampSize(w, state.w);
+    state.h = clampSize(h, state.h);
+    commit();
+  };
+  const setZoom = (z: Zoom) => {
+    state.z = z === "fit" ? "fit" : clampZoom(z);
+    commit();
+  };
+  const rotate = () => setSize(state.h, state.w);
+
+  // ---- controls -------------------------------------------------------------------------------
+  inputW.addEventListener("change", () => setSize(Number(inputW.value), state.h));
+  inputH.addEventListener("change", () => setSize(state.w, Number(inputH.value)));
+  for (const input of [inputW, inputH]) {
+    // Shift+arrow steps by 10 (the native step is 1).
+    input.addEventListener("keydown", (event) => {
+      if (!event.shiftKey || (event.key !== "ArrowUp" && event.key !== "ArrowDown")) return;
+      event.preventDefault();
+      const value = clampSize(Number(input.value) + (event.key === "ArrowUp" ? 10 : -10), MIN);
+      if (input === inputW) setSize(value, state.h);
+      else setSize(state.w, value);
+    });
+  }
+  // Choosing from the presets menu closes it, as choosing from any menu does.
+  const closeMenu = (el: HTMLElement) => el.closest<HTMLElement>("[popover]")?.hidePopover?.();
+  const rotateItem = $<HTMLElement>("[data-lab-vp-rotate]", controls);
+  rotateItem.addEventListener("click", () => {
+    rotate();
+    closeMenu(rotateItem);
+  });
+  for (const button of zoomButtons) {
+    button.addEventListener("click", () => {
+      setZoom(parseZoom(button.dataset.labVpZoom, "fit"));
+      closeMenu(button);
+    });
+  }
+  for (const button of sizeButtons) {
+    button.addEventListener("click", () => {
+      const h = button.dataset.labVpHeight ? Number(button.dataset.labVpHeight) : state.h;
+      setSize(Number(button.dataset.labVpWidth), h);
+      closeMenu(button);
+    });
+  }
+  new ResizeObserver(() => {
+    if (state.z === "fit") render();
+  }).observe(stage);
+
+  // ---- drag handles ---------------------------------------------------------------------------
+  // Pointer capture keeps the moves on the handle even across the iframe, which is also made inert
+  // for the drag. Screen deltas are divided by the zoom, so the frame grows by the pixels dragged.
+  // A drag at "fit" freezes the zoom at what fit was, or the frame would shrink under the pointer,
+  // and fits again on release. The field's numbers follow the drag live, in violet.
+  for (const handle of vp.querySelectorAll<HTMLElement>(".lab-vp-handle")) {
+    const axis = handle.dataset.axis || "xy";
+    let startX = 0;
+    let startY = 0;
+    let startW = 0;
+    let startH = 0;
+    let z = 1;
+    let wasFit = false;
+    handle.addEventListener("pointerdown", (event) => {
+      if (event.button !== 0) return;
+      event.preventDefault();
+      handle.setPointerCapture(event.pointerId);
+      startX = event.clientX;
+      startY = event.clientY;
+      startW = state.w;
+      startH = state.h;
+      z = scale();
+      wasFit = state.z === "fit";
+      if (wasFit) state.z = z;
+      vp.dataset.dragging = axis;
+      field.dataset.dragging = axis;
+      frame.style.pointerEvents = "none";
+    });
+    handle.addEventListener("pointermove", (event) => {
+      if (!handle.hasPointerCapture(event.pointerId)) return;
+      if (axis.includes("x")) state.w = clampSize(startW + (event.clientX - startX) / z, MIN);
+      if (axis.includes("y")) state.h = clampSize(startH + (event.clientY - startY) / z, MIN);
+      render();
+    });
+    const end = (event: PointerEvent) => {
+      if (!handle.hasPointerCapture(event.pointerId)) return;
+      handle.releasePointerCapture(event.pointerId);
+      delete vp.dataset.dragging;
+      delete field.dataset.dragging;
+      frame.style.pointerEvents = "";
+      if (wasFit) state.z = "fit"; // back to fitting the new size, as the field still says
+      commit();
+    };
+    handle.addEventListener("pointerup", end);
+    handle.addEventListener("pointercancel", end);
+  }
+
+  // ---- keys -----------------------------------------------------------------------------------
+  // [ ] step through the widths, r rotates, f fits, 0 is 100%. The shared keyboard guard
+  // (../LabHead.astro) keeps them quiet while anything is being typed, the pin composer included.
+  const stepWidth = (direction: 1 | -1) => {
+    const candidates = direction > 0 ? stepWidths.filter((w) => w > state.w) : stepWidths.filter((w) => w < state.w);
+    if (!candidates.length) return;
+    setSize(direction > 0 ? candidates[0]! : candidates[candidates.length - 1]!, state.h);
+  };
+  const onKey = (event: KeyboardEvent) => {
+    if (event.metaKey || event.ctrlKey || event.altKey || window.__labIgnoreKey?.(event)) return;
+    switch (event.key) {
+      case "[":
+        stepWidth(-1);
+        break;
+      case "]":
+        stepWidth(1);
+        break;
+      case "r":
+        rotate();
+        break;
+      case "f":
+        setZoom("fit");
+        break;
+      case "0":
+        setZoom(1);
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+  };
+  document.addEventListener("keydown", onKey);
+  // Same-origin, so the keys also work while focus is inside the frame — j/k too, handed to the
+  // page's own handler by re-dispatching on this document.
+  frame.addEventListener("load", () => {
+    try {
+      frame.contentDocument?.addEventListener("keydown", (event) => {
+        onKey(event);
+        if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return;
+        if ((event.key === "j" || event.key === "k") && !window.__labIgnoreKey?.(event)) {
+          document.dispatchEvent(new KeyboardEvent("keydown", { key: event.key }));
+        }
+      });
+    } catch {
+      /* cross-origin — keys work on the page only */
+    }
+  });
+
+  // ---- actions --------------------------------------------------------------------------------
+  for (const button of document.querySelectorAll<HTMLElement>("[data-lab-copy-link]")) {
+    button.addEventListener("click", async () => {
+      commit();
+      const label = button.querySelector<HTMLElement>("[data-lab-copy-label]");
+      try {
+        await navigator.clipboard.writeText(location.href);
+        if (label) label.textContent = "Link copied";
+      } catch {
+        if (label) label.textContent = "Copy failed";
+      }
+      setTimeout(() => {
+        if (label) label.textContent = "Copy link to this exact size";
+      }, 1500);
+    });
+  }
+  for (const button of document.querySelectorAll<HTMLElement>("[data-lab-reload]")) {
+    button.addEventListener("click", () => {
+      try {
+        frame.contentWindow?.location.reload();
+      } catch {
+        frame.src = frame.src;
+      }
+    });
+  }
+
+  // ---- the preview's own theme ----------------------------------------------------------------
+  // Separate from the chrome's (decided 2026-09-24): it is ⋯ › Preview › Dark mode, a checkbox row
+  // that appears only when the site in the frame has something to switch — a `.dark` or
+  // `[data-theme]` rule, or a dark colour-scheme query. Ticking it does both things a site might
+  // listen to — the frame's theme script (the same `astrobook:set-theme` message the thumbnails
+  // have always used) and the iframe's color-scheme, which is what `prefers-color-scheme` reads
+  // inside it.
+  const themeItem = document.querySelector<HTMLElement>("[data-lab-preview-theme]");
+  const themeGroup = document.querySelector<HTMLElement>("[data-lab-preview-group]");
+  const PREVIEW_THEME_KEY = "theme-toggle";
+  const previewTheme = () => {
+    try {
+      const stored = localStorage.getItem(PREVIEW_THEME_KEY);
+      return stored === "dark" ? "dark" : "light";
+    } catch {
+      return "light";
+    }
+  };
+  const paintPreviewTheme = (theme: "light" | "dark") => {
+    frame.dataset.theme = theme;
+    themeItem?.setAttribute("aria-checked", String(theme === "dark"));
+  };
+  const supportsDark = (doc: Document) => {
+    const scan = (rules: CSSRuleList | undefined): boolean => {
+      for (const rule of rules ?? []) {
+        if (rule instanceof CSSStyleRule && /\.dark\b|\[data-theme/.test(rule.selectorText)) return true;
+        if (rule instanceof CSSMediaRule && /prefers-color-scheme:\s*dark/.test(rule.conditionText)) return true;
+        if ("cssRules" in rule && scan((rule as CSSGroupingRule).cssRules)) return true;
+      }
+      return false;
+    };
+    for (const sheet of doc.styleSheets) {
+      try {
+        if (scan(sheet.cssRules)) return true;
+      } catch {
+        /* a cross-origin sheet — unreadable, and not the site's own theme anyway */
+      }
+    }
+    return false;
+  };
+  paintPreviewTheme(previewTheme());
+  frame.addEventListener("load", () => {
+    try {
+      if (themeGroup && frame.contentDocument) themeGroup.hidden = !supportsDark(frame.contentDocument);
+    } catch {
+      /* cross-origin */
+    }
+  });
+  themeItem?.addEventListener("click", () => {
+    const next = previewTheme() === "dark" ? "light" : "dark";
+    try {
+      localStorage.setItem(PREVIEW_THEME_KEY, next);
+    } catch {
+      /* private mode — the message still flips the frame */
+    }
+    paintPreviewTheme(next);
+    frame.contentWindow?.postMessage({ type: "astrobook:set-theme", theme: next }, location.origin);
+  });
+
+  // ---- the parameters drawer --------------------------------------------------------------------
+  // Present only for a story that registers parameters through @orbytes/astrolab/params. The
+  // drawer — its rows, groups, footer, storage and Esc — is ./params-client.ts.
+  mountParamsDrawer(vp.querySelector<HTMLElement>("[data-lab-params]"), frame);
+
+  render();
+  commit(); // the URL always names the viewport, even when it came from memory or defaults
+}
+
+// Hoisted like every import. It stands here, beside the one call that uses it, so the drawer's
+// wiring is in one place in this file.
+import { mountParamsDrawer } from "./params-client";
+
+export {};

package/src/chrome/views/Assets.astro

@@ -0,0 +1,125 @@
+---
+// Assets — <subpath>/assets, injected by ../../../index.mjs. Every image under src/ and public/,
+// with its size, its pixel dimensions where Astro knows them, and which source files reference it
+// — so the one question worth asking of a pile of images ("what does nothing use?") is a filter.
+//
+// src/ images are shown through Astro's own import (a glob of image metadata: the URL and the
+// dimensions, never the pixels); public/ images at their public URL. Neither loads until scrolled
+// into view.
+import Shell from "../Shell.astro";
+import Tree from "../Tree.astro";
+import { hrefs, type FilterOption } from "../model";
+import { assetsTree, formatBytes, siteAssetsModel } from "../site-data";
+
+type Meta = { src?: string; width?: number; height?: number };
+const imported = import.meta.glob<Meta>("/src/**/*.{png,jpg,jpeg,webp,avif,gif,svg}", {
+  eager: true,
+  import: "default",
+});
+const base = import.meta.env.BASE_URL.replace(/\/+$/, "");
+
+const assets = siteAssetsModel().map((asset) => {
+  const meta = asset.where === "src" ? imported[`/${asset.file}`] : undefined;
+  const url = asset.where === "public" ? `${base}/${asset.file.slice("public/".length)}` : (meta?.src ?? null);
+  return { ...asset, url, width: meta?.width ?? null, height: meta?.height ?? null };
+});
+const unused = assets.filter((a) => a.usedBy.length === 0).length;
+const total = assets.reduce((n, a) => n + a.bytes, 0);
+const filters: FilterOption[] = [
+  { value: "used", label: "Referenced" },
+  { value: "unused", label: "Referenced by nothing" },
+];
+---
+
+<Shell
+  title="Assets"
+  active="assets"
+  navbarClass="lab-navbar--listing"
+  panel={{
+    label: "Assets",
+    crumbs: [{ label: "Site" }, { label: "Assets", href: hrefs.assets }],
+    filters,
+    filterLabel: "Show images",
+    searchPlaceholder: "Search images",
+  }}
+>
+  <Tree slot="panel" nodes={assetsTree(assets)} />
+
+  <Fragment slot="navbar">
+    <div class="lab-listing-bar">
+      <h1 class="lab-listing-bar__title">Assets</h1>
+      <p class="lab-listing-bar__counts">
+        {[`${assets.length} image${assets.length === 1 ? "" : "s"}`, formatBytes(total), unused > 0 ? `${unused} unused` : null]
+          .filter(Boolean)
+          .join(" · ")}
+      </p>
+      {/* The same filter as level 2's menu (../shell-client.ts). */}
+      <div class="lab-chips" role="radiogroup" aria-label="Show images">
+        {
+          [
+            { value: "", label: "All", n: assets.length },
+            { value: "used", label: "Referenced", n: assets.length - unused },
+            { value: "unused", label: "Unused", n: unused },
+          ].map((chip) => (
+            <button class="lab-chip" type="button" role="radio" aria-checked={String(chip.value === "")} data-lab-filter={chip.value}>
+              {chip.label} {chip.n}
+            </button>
+          ))
+        }
+      </div>
+    </div>
+  </Fragment>
+
+  <div class="lab-page">
+    {
+      assets.length === 0 ? (
+        <div class="lab-empty">
+          <strong>No images</strong>
+          Nothing under <code>src/</code> or <code>public/</code> ends in .png, .jpg, .webp, .avif, .gif or .svg.
+        </div>
+      ) : (
+        <div class="lab-cards">
+          {assets.map((asset) => (
+            <article
+              class="lab-card lab-asset"
+              id={asset.id}
+              data-lab-search={`${asset.file} ${asset.ext}`.toLowerCase()}
+              data-lab-facets={asset.usedBy.length ? "used" : "unused"}
+            >
+              <span class="lab-card__thumb">
+                {asset.url ? <img src={asset.url} alt="" loading="lazy" decoding="async" /> : null}
+              </span>
+              <span class="lab-card__body">
+                <span class="lab-card__name" title={asset.file}>
+                  <span>{asset.name}</span>
+                </span>
+                <dl class="lab-kv">
+                  <dt>Folder</dt>
+                  <dd title={asset.folder}>{asset.folder}</dd>
+                  <dt>Size</dt>
+                  <dd>
+                    {formatBytes(asset.bytes)}
+                    {asset.width && asset.height ? ` · ${asset.width} × ${asset.height}` : ""}
+                  </dd>
+                  <dt>Used by</dt>
+                  <dd title={asset.usedBy.join("\n")}>
+                    {asset.usedBy.length === 0
+                      ? "nothing"
+                      : asset.usedBy.length === 1
+                        ? asset.usedBy[0]!.split("/").pop()
+                        : `${asset.usedBy[0]!.split("/").pop()} and ${asset.usedBy.length - 1} more`}
+                  </dd>
+                </dl>
+                {asset.usedBy.length === 0 && (
+                  <span class="lab-card__pills">
+                    <span class="lab-pill lab-pill--unresponsive">unused</span>
+                  </span>
+                )}
+              </span>
+            </article>
+          ))}
+        </div>
+      )
+    }
+  </div>
+</Shell>