@justai/cuts 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "A persona's named parts — the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -24,7 +24,8 @@
     "./ground.css": "./src/ground.css",
     "./FilePicker.astro": "./src/FilePicker.astro",
     "./ActionList.astro": "./src/ActionList.astro",
-    "./ActionRow.astro": "./src/ActionRow.astro"
+    "./ActionRow.astro": "./src/ActionRow.astro",
+    "./Files.astro": "./src/FilePicker.astro"
   },
   "peerDependencies": {
     "astro": ">=5"

package/src/FilePicker.astro

@@ -49,8 +49,19 @@ import Sheet from "./Sheet.astro";
  *
  * One element rather than two cuts, because it is one room: two frames would be two documents,
  * two atrium routers and two copies of the same kernel open at once, to ask the same file system
- * a question in each direction. The name stays `FilePicker` for now and that is a small debt —
- * what it actually is, is the persona's door to its files.
+ * a question in each direction.
+ *
+ * ── THE NAME (settled 2026-07-27) ────────────────────────────────────────────────────────────
+ *
+ * It was called `FilePicker` when picking was all it did, and by the time it could pick, save and
+ * read, the name described a third of it. A name that has to be explained is a name that is wrong:
+ * a builder reading "picker" in the catalogue has no reason to look here for saving.
+ *
+ * So it is exported as **`Files.astro`** — the persona's door to its files, which is what it is.
+ * `FilePicker.astro` still resolves to the same component and always will: eleven personas import
+ * it under that name, and breaking them to correct a word would be charging the fleet for the
+ * ecosystem's own late naming. An alias costs one line in `exports`; a rename costs eleven repos,
+ * eleven deploys, and one of them forgotten. New consumers import `Files`.
  *
  * A method on the element rather than a global, so two pickers on one page are two pickers and
  * nothing has to be coordinated through a name only one of them can own.
@@ -72,7 +83,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;