@justai/cuts 0.46.0 → 0.47.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justai/cuts",
-  "version": "0.46.0",
-  "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
+  "version": "0.47.0",
+  "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

@@ -118,6 +118,28 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
         the thing you see is the thing you can grab. Hidden from AX: Escape and the backdrop are the
         keyboard/assistive paths, and a decorative pill announced as a control is noise. */}
     <div class="sheet-grip" data-grip aria-hidden="true"><span></span></div>
+    {/* queries: back button in a sheet · sheet navigation · go deeper without opening another sheet
+        · in-sheet push · a second sheet loses the context · sheet breadcrumb
+
+        DEPTH WITHOUT A SECOND SHEET.
+
+        Stacking works — an opened sheet takes the one below as a height floor, so it never reads as
+        a retreat. What stacking cannot do is keep you ORIENTED: a full-height sheet over a
+        full-height sheet covers the thing you came from, and the only way back is a dismissal that
+        looks exactly like leaving altogether.
+
+        So a sheet may hold PAGES, and push between them. `<button data-sheet-push="versions">`
+        moves to the element carrying `data-sheet-page="versions"`; this chevron appears with the
+        previous page's title beside it and pops one level. Escape and the backdrop pop too, and
+        only close the sheet at the root — the platform behaviour a person already expects from a
+        navigation stack anywhere else.
+
+        NO HOMEWORK: a consumer writes markup and two attributes. No script, and the sheet still
+        works exactly as before for the consumers that never declare a page. */}
+    <button class="sheet-back" id={`${id}-back`} type="button" data-sheet-back hidden>
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 18l-6-6 6-6"/></svg>
+      <span data-sheet-back-label></span>
+    </button>
     {title && <h2 class="sheet-title" id={`${id}-title`}>{title}</h2>}
     {/* `id`-suffixed for the same reason the title is: a surface that translates at RUNTIME needs a
         stable hook to re-label it from its own dictionary. */}
@@ -143,6 +165,36 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
 
   /* Trailing and level with the title, where a navigation bar's right-hand action lives — the one
      place a thumb looks for "I am finished here". */
+  /* The back control mirrors Done across the header: same band, same weight, same restraint. It is
+     the accent colour because it is a NAVIGATION affordance rather than a destructive one, and the
+     chevron sits tight against the label the way iOS sets a back item. */
+  .sheet-back {
+    position: absolute; inset-inline-start: 12px; inset-block-start: 10px;
+    display: inline-flex; align-items: center; gap: 2px;
+    border: 0; background: none; padding: 6px 8px 6px 4px; cursor: pointer;
+    color: var(--accent); font: inherit; font-size: var(--fs-sm); font-weight: 500;
+    max-width: 42%;
+  }
+  .sheet-back[hidden] { display: none; }
+  .sheet-back svg { width: 20px; height: 20px; flex: none; }
+  .sheet-back span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sheet-back:active { opacity: 0.6; }
+  .sheet-back:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; border-radius: 8px; }
+
+  /* queries: sheet page transition · in-sheet push animation · the pages slide
+
+     Only one page is in the layout at a time, so the body's height is the CURRENT page's — which is
+     what makes the sheet grow and shrink around the content the way a navigation stack does. The
+     slide is 220ms and is skipped for reduced motion, where the pages simply swap. */
+  :global([data-sheet-page]) { display: none; }
+  :global([data-sheet-page].is-current) { display: block; animation: sheet-push 0.22s var(--ease-out) both; }
+  :global([data-sheet-page].is-popping) { display: block; animation: sheet-pop 0.22s var(--ease-out) both; }
+  @keyframes sheet-push { from { transform: translateX(18%); opacity: 0; } }
+  @keyframes sheet-pop { from { transform: translateX(-14%); opacity: 0; } }
+  @media (prefers-reduced-motion: reduce) {
+    :global([data-sheet-page].is-current), :global([data-sheet-page].is-popping) { animation: none; }
+  }
+
   .sheet-done {
     position: absolute; inset-block-start: 0; inset-inline-end: 0;
     background: none; border: 0; cursor: pointer; padding: 12px 16px;
@@ -339,6 +391,91 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
       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);
@@ -356,11 +493,17 @@ const doneLabel = done === false ? null : (done ?? (detent === "large" ? "Done"
       if (!panel) return;
 
       // A tap on the stage (outside the panel) dismisses — the one behaviour <dialog> lacks.
-      sheet.addEventListener("click", (e) => { if (e.target === sheet) sheet.close(); });
+      // 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;