@justai/cuts 0.133.0 → 0.139.0

package/src/behaviour/sheet.ts

@@ -0,0 +1,300 @@
+// queries: sheet behaviour · drag to dismiss · sheet script · where did Sheet.astro's script go ·
+//          testing a component's behaviour · component script is not type checked
+//
+// THE SHEET'S BEHAVIOUR, OUT OF THE COMPONENT AND INTO A MODULE THAT CAN BE READ.
+//
+// It lived inside `Sheet.astro` — 288 lines of TypeScript that NOTHING checked. A hoisted Astro
+// script goes to esbuild, which STRIPS types without ever reading them, and this package had no
+// tsconfig and no `astro check` anywhere in its CI. Every annotation in here bought exactly nothing
+// until the file moved out and a compiler could open it.
+//
+// It is also the only way any of this becomes testable. A behaviour that exists only inside a
+// template can be exercised in one way: render the whole page and poke it. A module can be called.
+import { chromeCopy } from "@justai/core";
+
+// The sheet's behaviour, once, for every persona that mounts one. Consumers write no JavaScript:
+// an element with data-sheet-open="<id>" is a trigger, and that is the whole contract.
+//
+// Note what is NOT here any more: a matchMedia guard. The drag worked only below 768px while this
+// component still had a desktop branch; now that there is one behaviour, there is one code path,
+// and a mouse can pull the grabber exactly as a finger does.
+(function () {
+  // queries: sheet says Cancel in English · the picker's cancel is not translated · Done stays
+  //          English · translate the sheet bar · why does the cut translate itself
+  //
+  // THE BAR SAYS ITS OWN WORDS, IN THE PAGE'S LANGUAGE.
+  //
+  // Found on an Arabic page: every word in the picker in Arabic, and `Cancel` in English in the
+  // sheet's own bar — because the cut rendered the literal and left translating it to whoever
+  // mounted it.
+  //
+  // WHY AT RUNTIME rather than at build. There is no locale to read at build. The fleet routes
+  // languages through a `[lang]` PARAMETER, not Astro's i18n config, so `Astro.currentLocale` is
+  // undefined in every persona that has one — and the two surfaces that need this most (`files`
+  // and `/me`) are ONE bundle serving thirteen languages, so no build-time answer could be right
+  // for them anyway. `<html lang>` is the one place every one of them agrees.
+  //
+  // A CONSUMER'S WORD ALWAYS WINS. `<Sheet cancel="Not now">` is a deliberate choice and this must
+  // not overwrite it — so only the DEFAULTS carry `data-chrome`, and only those are rewritten.
+  // That is also what keeps the runtime-translating surfaces working: they re-label by id from
+  // their own dictionary, which is the older contract and still the more specific one.
+  const say = () => {
+    const w = chromeCopy(document.documentElement.lang);
+    for (const el of document.querySelectorAll<HTMLElement>("[data-chrome]")) {
+      const word = w[el.dataset.chrome as "cancel" | "done"];
+      if (word) el.textContent = word;
+    }
+  };
+  say();
+  // The child personas set `<html lang>` from their own storage AFTER this module runs — a sheet
+  // translated only at load would be correct on a host and English inside a guest. Cheaper than a
+  // MutationObserver and exact: the attribute cannot change without the element being replaced.
+  new MutationObserver(say).observe(document.documentElement, { attributeFilter: ["lang"] });
+  const DRAG_CLOSE = 0.28;   // fraction of the panel's height that dismisses on release
+  const FLICK = 0.55;        // px/ms — a fast flick dismisses regardless of distance
+  const wired = new WeakSet<HTMLDialogElement>();
+
+  // queries: background scroll lock · html data-sheet-locked · nested sheets unlock too early ·
+  //          how does the sheet know it opened
+  //
+  // COUNTED, NOT TOGGLED. Sheets nest — qr's share sheet opens the file door on top of itself —
+  // so unlocking on the first `close` would free the page while a second sheet is still up. The
+  // count goes 0→1 to lock and 1→0 to unlock, and nothing in between touches it.
+  //
+  // WATCHED WITH A MutationObserver, because `<dialog>` has no "opened" event and consumers call
+  // `showModal()` themselves (qr does, from its own script). Hooking only the delegated opener
+  // would lock for sheets opened one way and not the other — which is worse than not locking at
+  // all, because it would work in testing and fail in the persona.
+  const locked = new WeakSet<HTMLDialogElement>();
+  let openCount = 0;
+  const relock = (delta: number) => {
+    openCount = Math.max(0, openCount + delta);
+    if (openCount > 0) document.documentElement.setAttribute("data-sheet-locked", "");
+    else document.documentElement.removeAttribute("data-sheet-locked");
+  };
+
+  // Measure the tallest sheet ALREADY open and use it as this one's floor. Measured rather than
+  // derived from the detent, because a `medium` sheet whose content is short is shorter than its
+  // detent allows — the floor has to be what is actually on the screen, not what was permitted.
+  function floorOnto(sheet: HTMLDialogElement) {
+    if (!sheet.hasAttribute("data-floor")) return;
+    const panel = sheet.querySelector<HTMLElement>("[data-panel]");
+    if (!panel) return;
+    let floor = 0;
+    for (const other of document.querySelectorAll<HTMLDialogElement>("dialog.sheet[open]")) {
+      if (other === sheet) continue;
+      const p = other.querySelector<HTMLElement>("[data-panel]");
+      if (p) floor = Math.max(floor, p.getBoundingClientRect().height);
+    }
+    // Never taller than the screen, and never a floor of zero — this is the first sheet then.
+    if (floor > 0) panel.style.minHeight = Math.min(floor, window.innerHeight) + "px";
+    else panel.style.removeProperty("min-height");
+  }
+
+  // ── in-sheet navigation ────────────────────────────────────────────────────────────────────
+  // queries: sheet push pop · back button in a sheet · data-sheet-push · escape pops instead of
+  //          closing · in-sheet navigation stack
+  //
+  // A STACK PER SHEET, held on the element rather than in a module variable, because two sheets
+  // can be open at once and each has its own history. Empty means "at the root", which is also the
+  // state every sheet that never declares a page is permanently in — that is what makes this
+  // addition free for the consumers who do not use it.
+  const stacks = new WeakMap<HTMLDialogElement, string[]>();
+
+  const pageOf = (sheet: HTMLDialogElement, key: string) =>
+    sheet.querySelector<HTMLElement>(`[data-sheet-page="${CSS.escape(key)}"]`);
+
+  // The name a person reads on the way back. The page's own `data-sheet-page-title` if it has one,
+  // otherwise the sheet's heading — which is the honest answer at the root, since that IS where
+  // back goes.
+  const titleAt = (sheet: HTMLDialogElement, key: string | undefined) =>
+    (key ? pageOf(sheet, key)?.dataset.sheetPageTitle : null)
+      ?? sheet.querySelector<HTMLElement>(".sheet-title")?.textContent?.trim()
+      ?? "";
+
+  function show(sheet: HTMLDialogElement, popping: boolean) {
+    const stack = stacks.get(sheet) ?? [];
+    const pages = sheet.querySelectorAll<HTMLElement>("[data-sheet-page]");
+    if (!pages.length) return;
+    const current = stack[stack.length - 1];
+    for (const el of pages) {
+      const on = current ? el.dataset.sheetPage === current : el.hasAttribute("data-sheet-root");
+      el.classList.toggle("is-current", on && !popping);
+      el.classList.toggle("is-popping", on && popping);
+    }
+    const back = sheet.querySelector<HTMLElement>("[data-sheet-back]");
+    const label = sheet.querySelector<HTMLElement>("[data-sheet-back-label]");
+    if (back) back.hidden = stack.length === 0;
+    // The label names WHERE BACK GOES — the level beneath the current one — which is the whole
+    // convention iOS set. Naming the current page instead is the mistake that makes a back button
+    // read as a title.
+    if (label) label.textContent = stack.length ? titleAt(sheet, stack[stack.length - 2]) : "";
+  }
+
+  function push(sheet: HTMLDialogElement, key: string) {
+    if (!pageOf(sheet, key)) return;
+    const stack = stacks.get(sheet) ?? [];
+    stacks.set(sheet, [...stack, key]);
+    show(sheet, false);
+  }
+
+  function pop(sheet: HTMLDialogElement) {
+    const stack = stacks.get(sheet) ?? [];
+    if (!stack.length) return false;
+    stacks.set(sheet, stack.slice(0, -1));
+    show(sheet, true);
+    return true;
+  }
+
+  document.addEventListener("click", (e) => {
+    const t = (e.target as HTMLElement)?.closest?.("[data-sheet-push]");
+    if (t) {
+      const sheet = t.closest("dialog.sheet") as HTMLDialogElement | null;
+      if (sheet) { e.preventDefault(); push(sheet, t.getAttribute("data-sheet-push") || ""); }
+      return;
+    }
+    const b = (e.target as HTMLElement)?.closest?.("[data-sheet-back]");
+    if (b) { e.preventDefault(); pop(b.closest("dialog.sheet") as HTMLDialogElement); }
+  });
+
+  // ESCAPE POPS BEFORE IT CLOSES, and the backdrop does the same. Anywhere else in a browser, Back
+  // at depth means "up one level"; a sheet that jumps straight out from three levels down throws
+  // away everything the person navigated through, and they cannot tell the two gestures apart
+  // beforehand. `preventDefault` on `cancel` is what keeps <dialog> from closing underneath us.
+  document.addEventListener("cancel", (e) => {
+    const sheet = e.target as HTMLDialogElement;
+    if (sheet?.classList?.contains("sheet") && pop(sheet)) e.preventDefault();
+  }, true);
+
+  // A sheet always REOPENS AT ITS ROOT. Coming back to a surface and finding it three levels deep
+  // where you left it is the behaviour of a window, not of a sheet — and nobody expects a sheet to
+  // remember.
+  document.addEventListener("click", (e) => {
+    const t = (e.target as HTMLElement)?.closest?.("[data-sheet-open]");
+    if (!t) return;
+    const sheet = document.getElementById(t.getAttribute("data-sheet-open") || "") as HTMLDialogElement | null;
+    if (sheet) { stacks.set(sheet, []); show(sheet, false); }
+  }, true);
+
+  function wire(sheet: HTMLDialogElement) {
+    if (wired.has(sheet) || !sheet.showModal) return;
+    wired.add(sheet);
+    let wasOpen = sheet.open;
+    if (wasOpen) relock(1);
+    new MutationObserver(() => {
+      if (sheet.open === wasOpen) return;
+      wasOpen = sheet.open;
+      relock(wasOpen ? 1 : -1);
+      if (wasOpen) floorOnto(sheet);
+      else sheet.querySelector<HTMLElement>("[data-panel]")?.style.removeProperty("min-height");
+    }).observe(sheet, { attributes: true, attributeFilter: ["open"] });
+    const panel = sheet.querySelector<HTMLElement>("[data-panel]");
+    const grip = sheet.querySelector<HTMLElement>("[data-grip]");
+    if (!panel) return;
+
+    // A tap on the stage (outside the panel) dismisses — the one behaviour <dialog> lacks.
+    // A tap on the stage pops one level first, for the same reason Escape does.
+    sheet.addEventListener("click", (e) => { if (e.target === sheet && !pop(sheet)) sheet.close(); });
+    sheet.addEventListener("close", () => {
+      sheet.removeAttribute("data-expanded");
+      panel.style.transform = "";
+      // Back to the root on the way out, whichever way it was dismissed — see the reopen note.
+      if (stacks.get(sheet)?.length) { stacks.set(sheet, []); show(sheet, false); }
+    });
+    // A sheet that ships pages must show one from the very first frame, or its body is empty until
+    // somebody navigates. The root is whichever page carries `data-sheet-root`.
+    show(sheet, false);
+
+    // ── drag: the grabber follows the pointer, and the release decides ──
+    let id: number | null = null, y0 = 0, t0 = 0, dy = 0;
+    grip?.addEventListener("pointerdown", (e: PointerEvent) => {
+      id = e.pointerId; y0 = e.clientY; t0 = e.timeStamp; dy = 0;
+      grip.setPointerCapture(id);
+      sheet.setAttribute("data-dragging", "");
+    });
+    grip?.addEventListener("pointermove", (e: PointerEvent) => {
+      if (id !== e.pointerId) return;
+      dy = e.clientY - y0;
+      // Downward drag travels 1:1. Upward is RUBBER-BANDED rather than free: pulling up past the
+      // detent must feel like resistance, not like a second scroll surface.
+      panel.style.transform = dy > 0 ? `translateY(${dy}px)` : `translateY(${dy / 4}px)`;
+    });
+    const release = (e: PointerEvent) => {
+      if (id !== e.pointerId) return;
+      const dt = Math.max(1, e.timeStamp - t0);
+      const v = dy / dt;
+      sheet.removeAttribute("data-dragging");
+      panel.style.transform = "";
+      id = null;
+      if (dy > panel.offsetHeight * DRAG_CLOSE || v > FLICK) sheet.close();
+      // A decisive pull upwards promotes the medium detent to large — iOS's two-detent sheet.
+      else if (dy < -40) sheet.setAttribute("data-expanded", "");
+    };
+    grip?.addEventListener("pointerup", release);
+    grip?.addEventListener("pointercancel", release);
+  }
+
+  // WIRED ON LOAD, not on the first trigger click.
+  //
+  // It used to be lazy, and the cost of that surfaced the moment a sheet was first opened by
+  // something other than a `data-sheet-open` trigger — <FilePicker> calls showModal() itself,
+  // because its sheet opens when a persona ASKS for a file rather than when a person presses a
+  // button. A sheet opened that way had no backdrop-dismiss and no drag: two of the three ways out
+  // of it, missing, with nothing to indicate it. The laziness saved nothing worth that.
+  // queries: does the confirm dialog lock the page too · scroll behind ConfirmSheet
+  //
+  // ConfirmSheet is its own `<dialog class="confirm">` rather than a `<Sheet>` — deliberately, it
+  // is an alert and not a surface. But the page scrolling behind it is the same defect on the
+  // same person's thumb, so the LOCK covers it while the floor and the drag do not. A rule about
+  // how a modal feels belongs to every modal, not to one component.
+  function lockOnly(d: HTMLDialogElement) {
+    if (locked.has(d)) return;
+    locked.add(d);
+    let was = d.open;
+    if (was) relock(1);
+    new MutationObserver(() => {
+      if (d.open === was) return;
+      was = d.open;
+      relock(was ? 1 : -1);
+    }).observe(d, { attributes: true, attributeFilter: ["open"] });
+  }
+
+  const wireAll = () => {
+    document.querySelectorAll<HTMLDialogElement>("dialog.sheet").forEach(wire);
+    document.querySelectorAll<HTMLDialogElement>("dialog.confirm").forEach(lockOnly);
+  };
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", wireAll);
+  else wireAll();
+
+  // Done closes, and NOTHING ELSE. It is not a commit — a sheet whose changes are live has
+  // nothing to commit — so it must not become a hook consumers hang saving off, or the word
+  // starts meaning two things in two personas.
+  document.addEventListener("click", (e) => {
+    const d = (e.target as HTMLElement)?.closest?.("[data-sheet-done]");
+    if (!d) return;
+    (d.closest("dialog.sheet") as HTMLDialogElement | null)?.close();
+  });
+
+  // Cancel closes too, and the difference is not in what it DOES — it is in what the caller may
+  // conclude. A sheet that resolves a promise reads its own `close` event and settles null there,
+  // so a cancel, a backdrop tap and a drag down are one path with one answer. Two words, one exit,
+  // and no second place for a caller to be told something different.
+  document.addEventListener("click", (e) => {
+    const c = (e.target as HTMLElement)?.closest?.("[data-sheet-cancel]");
+    if (!c) return;
+    (c.closest("dialog.sheet") as HTMLDialogElement | null)?.close();
+  });
+
+  document.addEventListener("click", (e) => {
+    const t = (e.target as HTMLElement)?.closest?.("[data-sheet-open]");
+    if (!t) return;
+    const sheet = document.getElementById(t.getAttribute("data-sheet-open") || "") as HTMLDialogElement | null;
+    if (!sheet) return;
+    e.preventDefault();
+    wire(sheet);
+    if (!sheet.open) sheet.showModal();
+    // Land the focus on the PANEL, not on whatever control happens to be first inside it — the
+    // keyboard-over-the-list failure described on the tabindex attribute above.
+    sheet.querySelector<HTMLElement>("[data-panel]")?.focus({ preventScroll: true });
+  });
+})();

package/src/behaviour/toolbar.ts

@@ -0,0 +1,89 @@
+// queries: toolbar behaviour · toolbar script · where did Toolbar.astro's script go ·
+//          testing a component's behaviour · component script is not type checked
+//
+// The toolbar — the persona's row, its mark and the scroll spy it hands off to core.
+//
+// Lifted out of `Toolbar.astro`, where it was TypeScript that nothing read: a hoisted Astro script
+// goes to esbuild, which strips annotations WITHOUT checking them, and this package had no tsconfig.
+// Out here a compiler can open it and a test can call it. What stays in the component is the markup
+// and the CSS, which is what a component is.
+// queries: where does the toolbar's scroll behaviour live · land on the kernel · scroll spy ·
+//          title strip · why is the scroll code not in this file any more
+//
+// The BEHAVIOUR moved to @justai/core (`personaScroll`); what stays here is the markup and the CSS.
+//
+// It moved because this cut can only serve pages that adopt its markup, and three surfaces cannot:
+// `/me` and `/files` carry extra navigation of their own and the feed is a different build. All
+// three hand-wrote the same eighty lines, and by the third copy they had drifted — `/files` opened
+// on the profile with an empty title strip, and its hash writer clobbered the query string where
+// this one preserved it. One implementation, four consumers.
+//
+// The defaults ARE this cut's contract — the three cut ids, `nav<Cut>`, `#tbTitle`/`#tbTitleText`,
+// `.toolbar`, `#below` — so a persona using the shell passes nothing at all.
+import { personaScroll, adoptMark } from "@justai/core";
+
+// queries: the parent icon in a child toolbar has a background · navParent tile · the child's row
+//          does not match the persona's · who removes the ground for a child persona
+//
+// THE ROW TAKES CARE OF ITS OWN MARK. Every other icon here is an ink; `parent` renders the host's
+// avatar file, which is a TILE, so a child's row is the one place in the fleet where a background
+// still shows. The persona's own mark is derived at build time from a file the repo imports — a
+// child has only a URL, so `adoptMark` fetches it and runs the same derivation in the browser,
+// measuring the box from the drawing instead of being told it.
+//
+// Here rather than in the three children because this cut is what rendered `#navParent`: three
+// consumers each remembering a line is O(N), and the third one always forgets.
+if (document.getElementById("navParent")) adoptMark({ id: "navParent" });
+
+// queries: the persona mark is an image · the golden rule does not apply · currentColor img ·
+//          the mark keeps its colours when I did not pass profileIcon
+//
+// THE FALLBACK HAS TO OBEY THE RULE TOO. A persona that passes `profileIcon` hands over a mark
+// derived at build time — ink, ground-less, sized. A persona that passes nothing gets the `<img>`
+// above, and an image obeys nothing: it cannot take `currentColor`, so it wears its own colours
+// while another cut is current, which is exactly what the accent must never do.
+//
+// It is the child persona's problem in a different costume — a mark known only as a URL — so it
+// takes the child's answer: fetch it and derive it here. Same function, same three edits, and the
+// row's own `.tb-nav` / `.tb-nav.active` rules reach it afterwards like any glyph.
+//
+// The build-time path stays the better one and stays the default advice: it costs no request and
+// no frame of the wrong picture. This is the floor under a persona that has not got there yet.
+const ownMark = document.querySelector("#navProfile img");
+if (ownMark) adoptMark({ id: "navProfile" });
+
+// Both or neither — see the props above. When both are set the strip names the SECTIONS; core's
+// default, which names the persona and its handle, is left entirely alone otherwise. Nothing here
+// reproduces that default, which is the point: `.pname` and `.handle` stay core's business.
+// ── the stage: the row stays LIVE, and using it pauses the game ───────────────────────────
+// queries: toolbar during a game · tapping posts while playing · auto pause · data-stage-silent
+//
+// The row went inert for one version and the founder unlocked it: every control stays enabled,
+// and touching ANY of them while a game is playing asks the game to pause first — so a player who
+// reaches for the posts mid-flight gets a paused gull and the feed, in one tap. The event is not
+// blocked: the action proceeds naturally while the pause lands beside it (a locked page still
+// scrolls programmatically, so even the hash navigation works before the unlock).
+//
+// Declarative seam, as asked: an element that must NOT pause the game opts out by carrying
+// `data-stage-silent` — on itself or any ancestor. Everything else pauses by default, because a
+// rule with a default and an opt-out survives a fleet; a per-element opt-in is the third copy
+// that forgets.
+document.querySelector(".toolbar")?.addEventListener(
+  "click",
+  (e) => {
+    if (document.documentElement.dataset.stage !== "playing") return;
+    const hit = (e.target as Element | null)?.closest?.("a, button, select, [role=button]");
+    if (!hit || hit.closest("[data-stage-silent]")) return;
+    document.dispatchEvent(new CustomEvent("justai:pause-request"));
+  },
+  true,
+);
+
+const bar = document.querySelector(".toolbar") as HTMLElement | null;
+const kt = bar?.dataset.kernelTitle;
+const pt = bar?.dataset.postsTitle;
+personaScroll(
+  kt && pt
+    ? { titleFor: (id: string) => (id === "kernel" ? kt : id === "posts" ? pt : "") }
+    : undefined,
+);