@justai/cuts 0.68.0 → 0.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justai/cuts",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "A persona's named parts \u2014 the page shell that holds them, and the cuts themselves.",
   "license": "UNLICENSED",
   "repository": {
@@ -21,6 +21,7 @@
     "./Profile.astro": "./src/Profile.astro",
     "./ConfirmSheet.astro": "./src/ConfirmSheet.astro",
     "./Sheet.astro": "./src/Sheet.astro",
+    "./Segmented.astro": "./src/Segmented.astro",
     "./ground.css": "./src/ground.css",
     "./FilePicker.astro": "./src/FilePicker.astro",
     "./ActionList.astro": "./src/ActionList.astro",

package/src/Segmented.astro

@@ -0,0 +1,216 @@
+---
+// THE GROUND rides with the control, same as every cut — law 1 is a file it imports, not a promise.
+import "./ground.css";
+/**
+ * <Segmented> — one question, two or three answers, all of them visible.
+ *
+ * queries: segmented control · tab group · button group · toggle between two things · iOS picker ·
+ *          two buttons side by side · switch between device and cloud · PHOTO or VIDEO · radiogroup
+ *
+ * ── WHAT IT IS, AND WHY IT IS THIS AND NOT TABS ──────────────────────────────────────────────
+ *
+ * iOS has one answer for "which of these few?" and it is the SEGMENTED CONTROL: a single track with
+ * the options inside it and a pill sliding to the chosen one. It is not a tab bar — a tab bar
+ * changes the SECTION you are in and lives at an edge of the screen. A segmented control changes
+ * what the view in front of you is SHOWING, and sits inside that view.
+ *
+ * The distinction decides where it may be used. `On this device` / `In the cloud` is the same room
+ * showing a different shelf, so it is this. `PHOTO` / `VIDEO` is the same camera in a different
+ * mode, so it is this too. Moving between a persona's profile and its kernel is not — that is the
+ * toolbar's job.
+ *
+ * ── WHY IT IS A CUT, WITH THE COUNT ──────────────────────────────────────────────────────────
+ *
+ * Four of these already existed, hand-rolled, in three repos: `files` has two (the storage tabs and
+ * the camera's mode), `time` has one in its toolbar, and `qr` has FOUR MORE behind one module whose
+ * own comment says it — *"four groups on this page are the same control wearing different clothes:
+ * the colour swatches, the module shape, the raster size, and the centre logo."*
+ *
+ * And they had split the work in half, each keeping the piece the other lost:
+ *
+ *   · **qr had the BEHAVIOUR right** — `role=radiogroup`, roving tabindex, arrow keys. That is an
+ *     accessibility pattern, and the part that is easy to get subtly wrong: leaving every option at
+ *     `tabIndex 0` is invisible to a mouse and makes a keyboard press Tab six times to pass a row.
+ *   · **time had the LOOK right** — a `surface-2` track, a hairline gap, the chosen segment raised
+ *     on its own rounded fill.
+ *   · **files had neither**, twice.
+ *
+ * That is what a copied control does: it does not diverge in one direction, it diverges in as many
+ * directions as there are copies, and each is right about something the others forgot.
+ *
+ * ── USE ──────────────────────────────────────────────────────────────────────────────────────
+ *
+ *     <Segmented id="where" value="device" options={[
+ *       { value: "device", label: t.onDevice },
+ *       { value: "cloud",  label: t.inCloud, disabled: true },
+ *     ]} />
+ *
+ *     const seg = document.getElementById("where");
+ *     seg.addEventListener("change", (e) => render(e.detail.value));
+ *     seg.value = "cloud";                       // set it from code; the event does not re-fire
+ *
+ * NO HOMEWORK (law 1): no script to copy, no class names to learn, no keyboard handling to
+ * remember. A consumer names the options and listens.
+ */
+export interface Option {
+  value: string;
+  label: string;
+  /** Shown, never hidden — an option a person can see and not reach explains itself; one that
+   *  vanishes reads as a feature that was removed. */
+  disabled?: boolean;
+  /**
+   * A translation key, for a consumer that swaps its words after render.
+   *
+   * queries: translate a segmented control · data-i · the labels stay English · one bundle many
+   *          languages
+   *
+   * THE ECOSYSTEM'S OWN CONVENTION, carried by the component rather than left to the caller. A
+   * mounted child persona (`/files`, `/me`) is ONE static bundle on every host, so it cannot have
+   * per-locale routes and translates in the browser by sweeping `[data-i]`. A control that renders
+   * its label as bare text is a control whose words stay English in thirteen languages — and the
+   * consumer's only fix would be to reach inside and add the attribute itself, which is the
+   * homework law 1 exists to refuse.
+   */
+  i18n?: string;
+}
+interface Props {
+  id: string;
+  options: Option[];
+  /** Which one is on. Defaults to the first, because a segmented control is never in no state. */
+  value?: string;
+  /** An accessible name for the group. The question the options answer. */
+  label?: string;
+  /** `full` stretches to the container (a view's own switch); `inline` hugs its content (a toolbar). */
+  width?: "full" | "inline";
+}
+const { id, options, value, label = "", width = "full" } = Astro.props as Props;
+const on = value && options.some((o) => o.value === value) ? value : options[0]?.value;
+---
+
+<div class="jseg" id={id} role="radiogroup" aria-label={label} data-width={width} data-value={on}>
+  {options.map((o) => (
+    <button
+      class="jseg-item"
+      type="button"
+      role="radio"
+      data-value={o.value}
+      aria-checked={o.value === on ? "true" : "false"}
+      aria-disabled={o.disabled ? "true" : undefined}
+      tabindex={o.value === on ? 0 : -1}
+    >
+      <slot name={`icon-${o.value}`} />
+      <span class="jseg-label" data-i={o.i18n}>{o.label}</span>
+    </button>
+  ))}
+</div>
+
+<style>
+  /* queries: segmented control styles · the chosen segment · ios segmented look
+     ONE TRACK, THE CHOSEN ONE RAISED. The track is recessed and the selection sits on top of it —
+     which is what makes a segmented control read as "these are the options" rather than as a row of
+     buttons where one happens to be coloured. */
+  .jseg {
+    /* ITS OWN BOX MODEL, not the consumer's. `width: 100%` plus a padding and a border comes out
+       SIX pixels wider than its parent unless something has already said `border-box` — and on a
+       bare page nothing has. Inheriting a reset is homework (law 1), and this is the shape that
+       homework takes when nobody notices: a control that fits everywhere it was tried. */
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: stretch;
+    gap: 2px;
+    padding: 2px;
+    border-radius: var(--radius-md);
+    background: var(--surface-2);
+    border: 1px solid var(--border);
+    /* A control is one tab stop. The roving tabindex below is what makes that true for the keyboard;
+       this is what makes it true for the eye. */
+    isolation: isolate;
+  }
+  .jseg[data-width="full"] { display: flex; width: 100%; }
+  .jseg[data-width="full"] .jseg-item { flex: 1; }
+
+  .jseg-item {
+    box-sizing: border-box;
+    display: inline-flex; align-items: center; justify-content: center; gap: 6px;
+    min-width: 0; padding: 7px 12px;
+    border: 0; border-radius: calc(var(--radius-md) - 3px);
+    background: transparent; color: var(--text-dim);
+    font: inherit; font-size: var(--fs-sm); font-weight: 500; line-height: 1.2;
+    cursor: pointer;
+    transition: background 0.18s var(--ease-out), color 0.18s var(--ease-out);
+  }
+  .jseg-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .jseg-item :global(svg) { width: 16px; height: 16px; flex: none; }
+
+  /* THE CHOSEN ONE. `--surface` against a `--surface-2` track is the raise; the accent names it. */
+  .jseg-item[aria-checked="true"] {
+    background: var(--surface);
+    color: var(--accent);
+    box-shadow: 0 1px 2px rgb(0 0 0 / 0.06);
+  }
+  .jseg-item[aria-disabled="true"] { opacity: 0.45; cursor: default; }
+  .jseg-item:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+  /* Motion is never forced on somebody who asked it off. */
+  @media (prefers-reduced-motion: reduce) {
+    .jseg-item { transition: none; }
+  }
+</style>
+
+<script>
+  // queries: segmented control keyboard · arrow keys · roving tabindex · aria-checked · change event
+  //
+  // ROVING TABINDEX IS THE WHOLE OF THE KEYBOARD. A radiogroup is ONE tab stop: Tab reaches the
+  // chosen option and the arrows move within the group. Leaving every option at `tabIndex 0` is the
+  // common mistake and it is invisible to anyone using a mouse — a person on a keyboard suddenly has
+  // to press Tab three times to get past a control they were not using.
+  //
+  // Lifted from qr, which had it right and had it alone.
+  const wire = (root: HTMLElement) => {
+    const items = () => Array.from(root.querySelectorAll<HTMLElement>('[role="radio"]'));
+
+    const set = (el: HTMLElement, focus?: boolean, quiet?: boolean) => {
+      if (el.getAttribute("aria-disabled") === "true") return;
+      const next = el.dataset.value!;
+      if (root.dataset.value === next) { if (focus) el.focus(); return; }
+      for (const r of items()) {
+        const chosen = r === el;
+        r.setAttribute("aria-checked", String(chosen));
+        r.tabIndex = chosen ? 0 : -1;
+      }
+      root.dataset.value = next;
+      if (focus) el.focus();
+      // Setting `.value` from code does NOT re-announce — a caller that just said what it wants does
+      // not need to be told, and a listener that reacts by setting the value would loop.
+      if (!quiet) root.dispatchEvent(new CustomEvent("change", { detail: { value: next }, bubbles: true }));
+    };
+
+    for (const el of items()) el.addEventListener("click", () => set(el, true));
+
+    root.addEventListener("keydown", (e) => {
+      const key = (e as KeyboardEvent).key;
+      const all = items().filter((r) => r.getAttribute("aria-disabled") !== "true");
+      const at = all.findIndex((r) => r.getAttribute("aria-checked") === "true");
+      let to = -1;
+      if (key === "ArrowRight" || key === "ArrowDown") to = (at + 1) % all.length;
+      else if (key === "ArrowLeft" || key === "ArrowUp") to = (at - 1 + all.length) % all.length;
+      else if (key === "Home") to = 0;
+      else if (key === "End") to = all.length - 1;
+      if (to < 0 || !all[to]) return;
+      e.preventDefault();
+      set(all[to], true);
+    });
+
+    // The one thing a caller needs beyond listening: saying what it wants.
+    Object.defineProperty(root, "value", {
+      get: () => root.dataset.value,
+      set: (v: string) => {
+        const el = items().find((r) => r.dataset.value === v);
+        if (el) set(el, false, true);
+      },
+      configurable: true,
+    });
+  };
+
+  for (const root of document.querySelectorAll<HTMLElement>(".jseg")) wire(root);
+</script>