@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/src/chrome/params-client.ts

@@ -0,0 +1,434 @@
+// The parameters drawer — built from the Figma components Parameters drawer (20074:3489), Drawer
+// group (20072:259700) and Param row (20072:259490) in the Astrolab file.
+//
+// Present only for a story that registers parameters through @orbytes/astrolab/params, which puts
+// them on the FRAME's window and announces each with a `lab:params` event there. The frame is
+// same-origin, so the drawer reads that array directly and calls each group's own set() across the
+// boundary — the values object is shared, never copied.
+//
+// It overlays the canvas's right edge and never resizes it: resizing would change the preview's
+// width and trip its breakpoints. Whether it is open, and which groups are collapsed, is
+// remembered in this browser. The navbar's Parameters button, the drawer's ✕ and Esc all close it.
+//
+// Every row is a <label> whose input is named by the label's text (aria-labelledby), so a row's
+// readout or unit never leaks into its accessible name. Typing into any of them is safe from the
+// lab's single-key shortcuts: every input and select here is one of the elements
+// window.__labIgnoreKey stands down for (../LabHead.astro).
+import type { IconName } from "./icons";
+import {
+  formatLabLength,
+  labUnitsOf,
+  parseLabLength,
+  type LabParamControl,
+  type LabParamEntry,
+} from "../shell/lab-params";
+
+const DRAWER_KEY = "lab-params-open";
+const COLLAPSE_KEY = "lab-params-collapsed";
+
+const readJson = <T,>(key: string, fallback: T): T => {
+  try {
+    return JSON.parse(localStorage.getItem(key) || "null") ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+const writeJson = (key: string, value: unknown) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    /* private mode — the drawer still works, it just forgets */
+  }
+};
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, text?: string) => {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+};
+
+// The chrome's icons are <symbol>s in ./Sprite.astro, on every lab page; this points at one.
+const SVG_NS = "http://www.w3.org/2000/svg";
+const icon = (name: IconName, className = "") => {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("class", `lab-icon lab-icon--sm ${className}`.trim());
+  svg.setAttribute("aria-hidden", "true");
+  const use = document.createElementNS(SVG_NS, "use");
+  use.setAttribute("href", `#lab-i-${name}`);
+  svg.append(use);
+  return svg;
+};
+
+const iconButton = (name: IconName, label: string, tooltip: string) => {
+  const button = el("button", "vpp__icon-btn");
+  button.type = "button";
+  button.title = tooltip;
+  button.setAttribute("aria-label", label);
+  button.append(icon(name));
+  return button;
+};
+
+let uid = 0;
+const nextId = (stem: string) => `lab-params-${stem}-${++uid}`;
+
+const decimalsOf = (step: number) => {
+  const text = String(step);
+  const dot = text.indexOf(".");
+  return dot === -1 ? 0 : text.length - dot - 1;
+};
+
+// <input type="color"> only takes #rrggbb; a declared #abc or #rrggbbaa would otherwise read as
+// black in the picker while the hex beside it says something else.
+const toPickerHex = (hex: string) =>
+  /^#[0-9a-f]{3,4}$/i.test(hex)
+    ? `#${[...hex.slice(1, 4)].map((c) => c + c).join("")}`
+    : hex.slice(0, 7);
+
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+// ---- the footer ---------------------------------------------------------------------------------
+// One line for the drawer as a whole, aria-live: what the last action did (Reset, Copy settings).
+// Hidden until there is something to say. It is also where the drawer would report on saving;
+// that is not built here.
+const makeFooter = () => {
+  const footer = el("footer", "vpp__footer");
+  const line = el("p", "vpp__footer-line");
+  line.setAttribute("aria-live", "polite");
+  footer.append(line);
+  footer.hidden = true;
+  return {
+    node: footer,
+    say(text: string) {
+      line.textContent = text;
+      footer.hidden = !text;
+    },
+  };
+};
+type Footer = ReturnType<typeof makeFooter>;
+
+// ---- one row per control ------------------------------------------------------------------------
+// Each returns its node and a `sync` that pulls the input back from the live values — Reset
+// changes the values behind the inputs' backs.
+const buildRow = (entry: LabParamEntry, control: LabParamControl) => {
+  const row = el("label", `vpp__row vpp__row--${control.kind}`);
+  const labelId = nextId("label");
+  const name = el("span", "vpp__label");
+  const text = el("span", "vpp__label-text", control.label);
+  text.id = labelId;
+  name.append(text);
+  let noteId = "";
+  if (control.note) {
+    row.title = control.note;
+    name.append(icon("help", "vpp__help"));
+    const note = el("span", "lab-visually-hidden", control.note);
+    note.id = noteId = nextId("note");
+    name.append(note);
+  }
+  const slot = el("span", "vpp__control");
+  row.append(name, slot);
+  const named = <T extends HTMLElement>(input: T) => {
+    input.setAttribute("aria-labelledby", labelId);
+    if (noteId) input.setAttribute("aria-describedby", noteId);
+    return input;
+  };
+  const set = (value: string | number | boolean) => entry.set(control.id, value);
+
+  switch (control.kind) {
+    case "toggle": {
+      const input = named(el("input", "vpp__switch"));
+      input.type = "checkbox";
+      input.setAttribute("role", "switch");
+      input.addEventListener("change", () => set(input.checked));
+      slot.append(input);
+      const sync = () => (input.checked = entry.values[control.id] === true);
+      sync();
+      return { node: row, sync };
+    }
+    case "select": {
+      const select = named(el("select", "vpp__select"));
+      for (const option of control.options) {
+        const node = el("option", undefined, option.label);
+        node.value = option.value;
+        select.append(node);
+      }
+      select.addEventListener("change", () => set(select.value));
+      slot.append(select);
+      const sync = () => (select.value = String(entry.values[control.id]));
+      sync();
+      return { node: row, sync };
+    }
+    case "color": {
+      const field = el("span", "vpp__field vpp__field--color");
+      const input = named(el("input", "vpp__swatch"));
+      input.type = "color";
+      const out = el("output", "vpp__hex");
+      out.setAttribute("aria-hidden", "true"); // the picker already announces its own value
+      input.addEventListener("input", () => {
+        out.textContent = input.value;
+        set(input.value);
+      });
+      field.append(input, out);
+      slot.append(field);
+      const sync = () => {
+        const hex = String(entry.values[control.id]);
+        input.value = toPickerHex(hex);
+        out.textContent = hex;
+      };
+      sync();
+      return { node: row, sync };
+    }
+    case "number": {
+      // Decided 2026-09-24: a size is typed, not dragged, and says what unit it is in. The value
+      // handed to the component is the number and unit joined ("72px"); changing the unit keeps
+      // the number and changes what it means, because px → rem depends on a root size the lab
+      // cannot know.
+      const units = labUnitsOf(control);
+      const field = el("span", "vpp__field vpp__field--number");
+      const input = named(el("input", "vpp__number"));
+      input.type = "number";
+      input.inputMode = "decimal";
+      input.step = String(control.step ?? 1);
+      if (control.min !== undefined) input.min = String(control.min);
+      if (control.max !== undefined) input.max = String(control.max);
+      const unit = el("select", "vpp__unit");
+      unit.setAttribute("aria-label", `${control.label} unit`);
+      for (const value of units) {
+        const option = el("option", undefined, value || "—");
+        option.value = value;
+        if (!value) option.title = "No unit";
+        unit.append(option);
+      }
+      unit.disabled = units.length < 2;
+      field.append(input, unit);
+      slot.append(field);
+
+      const current = () =>
+        parseLabLength(entry.values[control.id]) ?? { value: control.value, unit: control.unit };
+      const commit = (value: number) => {
+        const bounded = Math.min(control.max ?? Infinity, Math.max(control.min ?? -Infinity, value));
+        set(formatLabLength(bounded, unit.value));
+      };
+      // Live while typing, so the section follows the field. A half-typed value ("-", "1e") has
+      // no number yet and changes nothing; leaving the field shows what is actually applied.
+      input.addEventListener("input", () => {
+        if (input.value !== "" && Number.isFinite(input.valueAsNumber)) commit(input.valueAsNumber);
+      });
+      unit.addEventListener("change", () => commit(current().value));
+      const sync = () => {
+        const { value, unit: which } = current();
+        input.value = String(value);
+        unit.value = which;
+      };
+      input.addEventListener("change", sync);
+      sync();
+      return { node: row, sync };
+    }
+    case "range": {
+      const step = control.step ?? 1;
+      const places = decimalsOf(step);
+      const input = named(el("input", "vpp__range"));
+      input.type = "range";
+      input.min = String(control.min);
+      input.max = String(control.max);
+      input.step = String(step);
+      const out = el("output", "vpp__readout");
+      out.setAttribute("aria-hidden", "true"); // the slider announces its own value
+      const paint = () => {
+        const value = Number(input.value);
+        out.textContent = `${value.toFixed(places)}${control.unit ?? ""}`;
+        const span = control.max - control.min;
+        const fill = span > 0 ? ((value - control.min) / span) * 100 : 0;
+        input.style.setProperty("--lab-params-fill", `${fill}%`);
+      };
+      input.addEventListener("input", () => {
+        paint();
+        set(Number(input.value));
+      });
+      slot.append(input, out);
+      const sync = () => {
+        input.value = String(entry.values[control.id]);
+        paint();
+      };
+      sync();
+      return { node: row, sync };
+    }
+  }
+};
+
+// ---- one <details> per registered group ---------------------------------------------------------
+// Nothing interactive sits inside <summary>: the source link, Reset and Copy live in the body and
+// are positioned up into the header row, so they show only while the group is open.
+const buildGroup = (entry: LabParamEntry, collapsed: Record<string, boolean>, footer: Footer) => {
+  const group = entry.group;
+  const details = el("details", "vpp__group");
+  details.open = collapsed[group.id] !== true;
+  if (group.source) details.dataset.source = "";
+
+  const summary = el("summary", "vpp__summary");
+  summary.append(
+    icon("chevron-down", "vpp__chev"),
+    el("span", "vpp__title", group.title),
+    el("span", "vpp__summary-count", plural(group.controls.length, "control")),
+  );
+  details.append(summary);
+
+  if (group.source) {
+    const link = el("a", "vpp__source", group.source.label);
+    link.href = group.source.href;
+    link.target = "_blank";
+    link.rel = "noreferrer";
+    const arrow = el("span", "vpp__source-arrow", " ↗");
+    arrow.setAttribute("aria-hidden", "true");
+    link.append(arrow);
+    details.append(link);
+  }
+
+  const reset = iconButton("reset", `Reset ${group.title} to its defaults`, "Reset to defaults");
+  const copy = iconButton("copy", `Copy ${group.title} settings`, "Copy settings");
+  const actions = el("div", "vpp__actions");
+  actions.append(reset, copy);
+  details.append(actions);
+
+  if (group.note) details.append(el("p", "vpp__note", group.note));
+
+  const list = el("div", "vpp__controls");
+  const syncers: (() => void)[] = [];
+  for (const control of group.controls) {
+    const built = buildRow(entry, control);
+    syncers.push(built.sync);
+    list.append(built.node);
+  }
+
+  // The component's own status line (panel.status()) — WebGL state, frame cost, an error. Hidden
+  // until the component says something.
+  const status = el("p", "vpp__status");
+  status.setAttribute("aria-live", "polite");
+  const showStatus = (text: string) => {
+    status.textContent = text;
+    status.hidden = !text;
+  };
+  showStatus(entry.lastStatus);
+  entry.onStatus = showStatus;
+  details.append(list, status);
+
+  reset.addEventListener("click", () => {
+    entry.resetAll();
+    for (const sync of syncers) sync();
+    footer.say(`${group.title} reset to its defaults`);
+  });
+  copy.addEventListener("click", async () => {
+    const json = entry.json();
+    try {
+      await navigator.clipboard.writeText(json);
+      footer.say(`${group.title} settings copied as JSON`);
+    } catch {
+      showStatus(json);
+      footer.say("The clipboard is blocked — the settings are shown in the group");
+    }
+  });
+
+  details.addEventListener("toggle", () => {
+    const map = readJson<Record<string, boolean>>(COLLAPSE_KEY, {});
+    if (details.open) delete map[group.id];
+    else map[group.id] = true;
+    writeJson(COLLAPSE_KEY, map);
+  });
+  return details;
+};
+
+const buildDrawer = (drawer: HTMLElement, groups: LabParamEntry[], close: () => void) => {
+  const header = el("header", "vpp__header");
+  const heading = el("div", "vpp__heading");
+  const title = el("h2", "vpp__heading-title", "Parameters");
+  title.id = nextId("title");
+  const total = groups.reduce((sum, entry) => sum + entry.group.controls.length, 0);
+  const count = el("span", "vpp__count", String(total));
+  count.append(el("span", "lab-visually-hidden", total === 1 ? " control" : " controls"));
+  heading.append(title, count);
+  const closeButton = iconButton("close", "Close parameters", "Close (Esc)");
+  closeButton.addEventListener("click", close);
+  header.append(heading, closeButton);
+
+  const footer = makeFooter();
+  const body = el("div", "vpp__scroll");
+  const collapsed = readJson<Record<string, boolean>>(COLLAPSE_KEY, {});
+  for (const entry of groups) body.append(buildGroup(entry, collapsed, footer));
+
+  drawer.setAttribute("aria-labelledby", title.id);
+  drawer.replaceChildren(header, body, footer.node);
+};
+
+export function mountParamsDrawer(drawer: HTMLElement | null, frame: HTMLIFrameElement) {
+  if (!drawer) return;
+  const button = document.querySelector<HTMLElement>("[data-lab-params-toggle]");
+  drawer.id ||= "lab-params";
+  button?.setAttribute("aria-controls", drawer.id);
+
+  let groups: LabParamEntry[] = [];
+  const wantsOpen = () => readJson(DRAWER_KEY, true) !== false;
+  const paint = () => {
+    const present = groups.length > 0;
+    const open = present && wantsOpen();
+    drawer.hidden = !open;
+    if (!button) return;
+    button.hidden = !present;
+    button.setAttribute("aria-pressed", String(open));
+  };
+  const setOpen = (open: boolean) => {
+    writeJson(DRAWER_KEY, open);
+    paint();
+  };
+  const close = () => {
+    const hadFocus = drawer.contains(document.activeElement);
+    setOpen(false);
+    if (hadFocus) button?.focus();
+  };
+  button?.addEventListener("click", () => setOpen(!wantsOpen()));
+
+  // Esc closes it — from inside the drawer always, from elsewhere only when nothing is being typed
+  // and no menu is open (an open popover takes the Esc itself).
+  document.addEventListener("keydown", (event) => {
+    if (event.key !== "Escape" || drawer.hidden || event.defaultPrevented) return;
+    const inside = drawer.contains(document.activeElement);
+    if (!inside && window.__labIgnoreKey?.(event)) return;
+    try {
+      if (document.querySelector(":popover-open")) return;
+    } catch {
+      /* no popover support — so no popover to defer to */
+    }
+    close();
+  });
+
+  const build = () => {
+    try {
+      groups = frame.contentWindow?.__labParams ?? [];
+    } catch {
+      groups = []; // a lab preview is always same-origin, but the drawer must never throw
+    }
+    if (groups.length) buildDrawer(drawer, groups, close);
+    else drawer.replaceChildren();
+    paint();
+  };
+  let queued = false;
+  const queueBuild = () => {
+    if (queued) return;
+    queued = true;
+    queueMicrotask(() => {
+      queued = false;
+      build();
+    });
+  };
+  const readParams = () => {
+    queueBuild();
+    try {
+      // Groups registered after load (an async setup) announce themselves; ones registered during
+      // module evaluation are already in the array queueBuild just read.
+      frame.contentWindow?.addEventListener("lab:params", queueBuild);
+    } catch {
+      /* cross-origin — the drawer stays as built */
+    }
+  };
+  frame.addEventListener("load", readParams);
+  if (frame.contentDocument?.readyState === "complete") readParams();
+}

package/src/chrome/pins-data.ts

@@ -0,0 +1,63 @@
+// Pin-board tickets counted per source file and per page, for the Properties panel behind the
+// navbar's eye. Dev only: `labConfig.tasks` is null in every build, and then this returns empty
+// counts without touching the disk.
+//
+// The markers drawn on the framed preview do not come from here. They come from the dev toolbar's
+// pin app, which re-reads the board after every write (../pin/toolbar.js › `orbytes-pin:state`),
+// so a pin appears on the frame the moment it is created rather than on the next page load.
+import { labConfig } from "./model";
+
+/** Open and resolved tickets. Cancelled ones are an archive and are counted nowhere. */
+export interface PinTally {
+  open: number;
+  resolved: number;
+}
+
+export interface PinCounts {
+  /** open tickets whose source file ends with the given site-relative path */
+  openFor: (file: string | null | undefined) => number;
+  /** open and resolved tickets whose source file ends with the given site-relative path */
+  forFile: (file: string | null | undefined) => PinTally;
+  /** open and resolved tickets left on the given page address (`/`, `/about`) */
+  forUrl: (url: string | null | undefined) => PinTally;
+  total: number;
+  review: number;
+}
+
+const zero: PinTally = { open: 0, resolved: 0 };
+const none: PinCounts = { openFor: () => 0, forFile: () => zero, forUrl: () => zero, total: 0, review: 0 };
+
+/** `/a/` and `/a` are the same page; a query string is part of the address. */
+const samePath = (a: string, b: string) => {
+  const norm = (value: string) => {
+    const cut = value.indexOf("?");
+    const path = cut === -1 ? value : value.slice(0, cut);
+    return (path.length > 1 ? path.replace(/\/+$/, "") : path) + (cut === -1 ? "" : value.slice(cut));
+  };
+  return norm(a) === norm(b);
+};
+
+export const pinCounts = async (): Promise<PinCounts> => {
+  if (!labConfig.tasks) return none;
+  try {
+    const { collectTickets, OPEN_STATUSES, READY_FOR_REVIEW, RESOLVED } = await import("../pin/board.mjs");
+    const { tickets } = collectTickets(labConfig.tasks.repoRoot, { backlogDir: labConfig.tasks.backlogDir }) as {
+      tickets: { status: string; source?: string | null; url?: string | null }[];
+    };
+    const open = tickets.filter((t) => OPEN_STATUSES.includes(t.status));
+    const resolved = tickets.filter((t) => t.status === RESOLVED);
+    // A ticket's source is repo-relative and a lab path is site-relative; in a monorepo the site
+    // sits below the repo root, so the comparison is on the tail.
+    const bySource = (file: string) => (t: { source?: string | null }) => t.source === file || Boolean(t.source?.endsWith(`/${file}`));
+    const byUrl = (url: string) => (t: { url?: string | null }) => Boolean(t.url) && samePath(t.url!, url);
+    return {
+      openFor: (file) => (file ? open.filter(bySource(file)).length : 0),
+      forFile: (file) => (file ? { open: open.filter(bySource(file)).length, resolved: resolved.filter(bySource(file)).length } : zero),
+      forUrl: (url) => (url ? { open: open.filter(byUrl(url)).length, resolved: resolved.filter(byUrl(url)).length } : zero),
+      total: open.length,
+      review: open.filter((t) => t.status === READY_FOR_REVIEW).length,
+    };
+  } catch {
+    return none;
+  }
+};