@justai/cuts 0.45.0 → 0.46.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justai/cuts",
-  "version": "0.45.0",
-  "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
+  "version": "0.46.1",
+  "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",

package/src/Base.astro

@@ -40,7 +40,20 @@ import ConfirmSheet from "./ConfirmSheet.astro";
 
 interface Props {
   lang: string;
-  t: Record<string, string>;
+  /**
+   * The persona's strings, in the shape the persona keeps them.
+   *
+   * NOT `Record<string, string>` — that was the declaration for a year and it was wrong for every
+   * consumer: a persona's dictionary is NESTED (`t.share.title`, `t.types.wifi`), so the one type
+   * this layout advertised was the one type nobody passes. It compiled everywhere because nobody
+   * ran a typechecker over a page; qr turned one on and the framework's own contract was the first
+   * thing it caught.
+   *
+   * This layout only ever reads a handful of top-level strings off it and forwards the rest to the
+   * cuts, so what it actually requires is "an object of strings, possibly nested" — stated here
+   * rather than narrowed to a shape only this package would recognise.
+   */
+  t: Record<string, unknown>;
   /** The persona's own origin, e.g. https://tabata.app.zone — canonical, hreflang and OG all read it. */
   site: string;
   /** From the consuming repo's src/i18n — never from this package. */

package/src/Sheet.astro

@@ -57,6 +57,24 @@ interface Props {
   title?: string;
   /** How tall it opens. `medium` is iOS's half-height default; drag up promotes it to large. */
   detent?: "medium" | "large";
+  // queries: a sheet opened over another looks like going back · stacked sheet height · floor ·
+  //          why is the second sheet shorter · going deeper should not look like retreating
+  //
+  // A STACK MUST NEVER APPEAR TO MOVE BACKWARDS (founder, 2026-07-28).
+  //
+  // A sheet that opens SHORTER than the one beneath it reads as a retreat: the content area
+  // shrinks, the dim jumps, and the feeling is "something closed" rather than "I went deeper".
+  // So an opened sheet takes the height of the one below as a FLOOR.
+  //
+  // It does not make depth visible on its own — two `large` sheets are still the same height —
+  // and it is not meant to. Paired with the ceiling of two, it guarantees the only thing that
+  // matters at two levels: the movement always reads forward.
+  //
+  // `false` opts out, and ConfirmSheet does. A question that must be READ is served by being
+  // small and focused; stretching an alert to match whatever it was asked from would weaken the
+  // one surface whose whole job is to be taken seriously. Apple keeps alerts small regardless of
+  // context, for the same reason.
+  floorToParent?: boolean;
   // queries: should a sheet have a Done button · how do I close a full height sheet · sheet done ·
   //          the exit is not obvious · dismiss a large sheet
   //
@@ -79,7 +97,7 @@ interface Props {
   // hardcoded the English would be a component making its consumer's copy decisions.
   done?: string | false;
 }
-const { id, title, detent = "medium", done } = Astro.props;
+const { id, title, detent = "medium", done, floorToParent = true } = Astro.props;
 // Default: shown at large, absent at medium. `false` removes it, a string replaces the word.
 const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done" : null));
 ---
@@ -89,7 +107,7 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
     exposes. A surface that translates at RUNTIME (the vault, the feed — one bundle, thirteen
     languages, no per-locale routes) renders this cut in English and re-labels it from its own
     dictionary. Without the hook such a consumer cannot adopt the cut at all, and writes its own. */}
-<dialog class="sheet" id={id} data-detent={detent} aria-labelledby={title ? `${id}-title` : undefined} aria-label={title ? undefined : "Sheet"}>
+<dialog class="sheet" id={id} data-detent={detent} data-floor={floorToParent ? "" : undefined} aria-labelledby={title ? `${id}-title` : undefined} aria-label={title ? undefined : "Sheet"}>
   {/* tabindex="-1" so the PANEL can take the focus when the sheet opens. Without it, showModal()
       hands focus to the first focusable descendant — which for a picker is the search field, and on
       a phone that throws the software keyboard over the list the visitor opened the sheet to read.
@@ -295,6 +313,7 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
     // `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);
@@ -302,6 +321,24 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
       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");
+    }
+
     function wire(sheet: HTMLDialogElement) {
       if (wired.has(sheet) || !sheet.showModal) return;
       wired.add(sheet);
@@ -311,6 +348,8 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
         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]");
@@ -359,7 +398,28 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
     // 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.
-    const wireAll = () => document.querySelectorAll<HTMLDialogElement>("dialog.sheet").forEach(wire);
+    // 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();