@justai/cuts 0.42.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {

package/src/FilePicker.astro

@@ -72,7 +72,11 @@ interface Props {
 const { id, title = "Choose a file", src = "/files" } = Astro.props;
 ---
 
-<Sheet id={`${id}-sheet`} title={title} detent="large">
+{/* NO `Done` here, deliberately. This sheet is a QUESTION, and its answer is a row being
+    tapped inside the frame — so a Done that merely closed would be a Cancel wearing the word for
+    finishing, on the one surface where the difference decides what the caller receives. The kernel
+    inside shows its own Cancel, worded as the choice it actually is. */}
+<Sheet id={`${id}-sheet`} title={title} detent="large" done={false}>
   <div class="jfp" id={id} data-picker={id} data-src={src}>
     {/* Empty until the first open. `title` is the accessible name of the document inside — a frame
         announced as "frame" is the one control on the page that says nothing about itself. */}

package/src/Sheet.astro

@@ -57,8 +57,31 @@ 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: 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
+  //
+  // DONE MEANS FINISHED, NOT APPLIED — and that distinction decides whether it belongs.
+  //
+  // A sheet whose changes are STAGED needs a commit: Done applies, Cancel discards. A sheet whose
+  // changes are LIVE — every tap already redrawn behind you — has nothing to commit, and a button
+  // labelled Save or Apply on one of those is a lie about what pressing it does.
+  //
+  // So why offer it at all? THE EXIT. At the medium detent the page is visible behind the sheet and
+  // the grabber sits in plain sight, so leaving is obvious. At `large` the sheet is the screen: a
+  // person has to already know that a swipe down or an Escape will work, and "already knowing" is
+  // not an affordance. iOS answers the same way — its half-height sheets carry no Done and its
+  // full-height ones do.
+  //
+  // Hence the rule this cut applies: **offered at `large`, absent at `medium`.** A consumer that
+  // wants it anyway passes a label; one that wants it gone passes `done={false}`.
+  //
+  // It is a LABEL rather than a boolean because the fleet speaks thirteen languages, and a cut that
+  // hardcoded the English would be a component making its consumer's copy decisions.
+  done?: string | false;
 }
-const { id, title, detent = "medium" } = Astro.props;
+const { id, title, detent = "medium", done } = 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));
 ---
 
 {/* aria-labelledby over aria-label when there IS a title, so the accessible name and the visible
@@ -78,11 +101,26 @@ const { id, title, detent = "medium" } = Astro.props;
         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>
     {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. */}
+    {doneLabel && (
+      <button class="sheet-done" id={`${id}-done`} type="button" data-sheet-done>{doneLabel}</button>
+    )}
     <div class="sheet-body"><slot /></div>
   </div>
 </dialog>
 
 <style>
+  /* 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". */
+  .sheet-done {
+    position: absolute; inset-block-start: 0; inset-inline-end: 0;
+    background: none; border: 0; cursor: pointer; padding: 12px 16px;
+    font: inherit; font-size: var(--fs-sm); font-weight: 600; color: var(--accent);
+  }
+  .sheet-done:active { opacity: 0.6; }
+  .sheet-done:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; border-radius: 8px; }
+
   .sheet {
     /* The dialog is the full-screen STAGE; the PANEL is the sheet.
        `position: fixed` is written out rather than inherited: the UA gives a dialog
@@ -127,6 +165,7 @@ const { id, title, detent = "medium" } = Astro.props;
   }
 
   .sheet-panel {
+    position: relative;   /* the Done action is positioned against this */
     display: flex;
     flex-direction: column;
     /* THE ONE SIZING RULE, and there is no media query anywhere in this file. The persona's column
@@ -275,6 +314,15 @@ const { id, title, detent = "medium" } = Astro.props;
     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();
+    });
+
     document.addEventListener("click", (e) => {
       const t = (e.target as HTMLElement)?.closest?.("[data-sheet-open]");
       if (!t) return;