create-pmos 0.52.0 → 0.53.1

package/workspace/public/pm/initiatives-timeline.js

@@ -0,0 +1,410 @@
+/* pm/initiatives-timeline.js — Initiatives › Timeline (pm-os-absorb Run 4, slice 4C; PRD R20 A).
+ *
+ * Months across, one row per initiative, grouped by horizon (Now, Next, Later). A bar is drawn by the Timeline bar
+ * primitive (primitives.js timelineBar, slice 4B), split by stage, with a diamond for each milestone, and one line marks
+ * today. An initiative with no dated item sits below the chart in a "Not dated" section, grouped by horizon the same way.
+ *
+ *   - THE ROWS COME FROM `GET /api/timeline?ws=` (lib/routes-timeline.js): the dates are the items' own start and due.
+ *     Nothing is derived here, and no number is written to a record by this page.
+ *   - A ROW REORDERS BY ITS GRIP, inside its horizon and nowhere else: a `placed` line through POST /api/placements
+ *     (Run 2, slice 2C), `after` = the row it now follows, or null for the top. One line is enough while every row above
+ *     the new place has a placement line of its own. A row that only reads Later by default (`placed: false`) has none,
+ *     so a line that names it as `after` cannot find it: the move then writes a line for each row from the first row
+ *     it changes to the last row that has no line (`moveEvents`), in one request, and the page says so. The same move is on the keyboard
+ *     (Alt+ArrowUp/Down on the title) and in the row's ⋯ menu (To top, Up, Down). Moving to another horizon is the
+ *     Roadmap's act, where the PM's press for Now is asked for.
+ *   - A BAR NEVER DRAGS. The drag handle is the grip only: a drag that starts on a bar, or anywhere else on a row, writes
+ *     nothing. Dates change in the Breakdown, on the item.
+ *   - ▸ shows the stage rows of an initiative: the stage, its done and total items, and its own bar.
+ *   - At 390 px the chart scrolls sideways inside itself and the page never scrolls sideways. The name of a row stays at
+ *     the left edge while its months scroll under it. The chart opens with today in view.
+ *   - THE VIEW WATCHES its own GET with sig-watch.js watchSig (seams §4.9), because /api/sessions `ledgers` covers
+ *     plan-items only. Each read is compared with the sig of the answer on screen, so a write that lands between the
+ *     first read and the first tick is caught, and a changed answer is drawn from the read that found it (no second
+ *     GET). It never rebuilds while a drag is live.
+ *   - TODAY and THE RANGE come from the route (the server's local date; at most 24 months). A date outside the range is
+ *     cut off, and a note says so.
+ *
+ * Registers itself as the Initiatives view `timeline`; slice 2D's View control shows it when it is registered. The mount
+ * ctx is the frozen initiativesViewCtx: { repo, ws, rows, sig, openInitiative, setState }. `rows` and `sig` are the
+ * Roadmap's, so this view reads neither of them: it asks for its own rows.
+ */
+
+import { registerInitiativesView } from './registry.js';
+import { el, setChildren } from './dom.js';
+import { FIXTURE } from './state.js';
+import { pmGet, pmPost } from './http.js';
+import { watchSig } from './sig-watch.js';
+import { SEL, button, iconButton, row, menu, empty, toast, timelineBar, dragHandle, ensureComponentsCss, layer } from './primitives.js';
+import { ensureSprite } from './icons.js';
+import { loadSortable, baseOptions, dragSet } from './bd-drag.js';
+import { COPY, monthLabel, spanText } from './initiatives-timeline-copy.js';
+
+const HORIZONS = ['now', 'next', 'later'];
+const DAY = 86400000;
+const day = (ymd) => Date.parse(ymd + 'T00:00:00Z');
+
+const views = new WeakMap();   // host -> view state
+
+/* ── the chart's axis ────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** The months of a range: [{ start: 'YYYY-MM-01', days }], so a month is as wide as it has days. */
+function monthsOf(range) {
+  const out = [];
+  let y = Number(range.start.slice(0, 4)); let m = Number(range.start.slice(5, 7));
+  const endY = Number(range.end.slice(0, 4)); const endM = Number(range.end.slice(5, 7));
+  while (y < endY || (y === endY && m <= endM)) {
+    out.push({ start: `${y}-${String(m).padStart(2, '0')}-01`, days: new Date(Date.UTC(y, m, 0)).getUTCDate() });
+    m += 1; if (m > 12) { m = 1; y += 1; }
+  }
+  return out;
+}
+
+function todayPercent(range, d) {
+  const total = day(range.end) + DAY - day(range.start);
+  const at = day(String(d.today || d.now).slice(0, 10)) - day(range.start);
+  return Math.max(0, Math.min(100, (at / total) * 100));
+}
+
+/** A segment cut to the range, or null when it lies wholly outside it. */
+function clip(range, g) {
+  if (!range || !g.start) return null;
+  if (g.due < range.start || g.start > range.end) return null;
+  return { stage: g.stage, start: g.start < range.start ? range.start : g.start, due: g.due > range.end ? range.end : g.due };
+}
+
+/* ── one row ─────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+const listOf = (V, r) => V.data.horizons[r.horizon].filter((x) => x.dated === r.dated);
+
+/* A part of the meta line (lane, count, dates) never breaks inside itself: its spaces are no-break spaces. (The row's
+ * meta is a primitive's, so the view does not restyle it, R28-9.) */
+const unbroken = (t) => String(t).replace(/ /g, '\u00a0');
+function metaOf(r) {
+  return [r.lane, COPY.progress(r.progress.done, r.progress.total), r.span ? spanText(r.span) : null].filter(Boolean).map(unbroken);
+}
+
+function nameCell(V, r) {
+  const open = V.open.has(r.id);
+  const lead = [dragHandle({ label: COPY.aria.reorder(r.title) })];
+  if (!r.stages.length) lead.push(el('span', { class: 'tl-init-lead-gap', 'aria-hidden': 'true' }));   // keeps the title where ▸ would leave it
+  if (r.stages.length) {
+    lead.push(iconButton({
+      icon: open ? 'chevron-down' : 'chevron-right', size: 'sm', expanded: open,
+      ariaLabel: open ? COPY.aria.hide(r.title) : COPY.aria.show(r.title),
+      onClick: (e) => { e.stopPropagation(); if (V.open.has(r.id)) V.open.delete(r.id); else V.open.add(r.id); render(V); },
+      attrs: { 'data-tl-toggle': r.id },
+    }));
+  }
+  const more = iconButton({
+    icon: 'ellipsis', size: 'sm', ariaLabel: COPY.aria.more(r.title),
+    onClick: (e) => { e.stopPropagation(); openMenu(V, e.currentTarget, r); },
+    attrs: { 'aria-haspopup': 'menu', 'data-tl-more': r.id },
+  });
+  return row({
+    title: r.title, meta: metaOf(r), lead, trail: [more],
+    onOpen: () => open_(V, r.id), attrs: { class: 'tl-init-name' }, openAttrs: { 'data-tl-open': r.id },
+  });
+}
+
+function trackCell(V, r) {
+  const bar = timelineBar({
+    label: COPY.aria.bar(r.title, r.span),
+    segments: r.stages.map((s) => clip(V.data.range, { stage: s.id, start: s.start, due: s.due })).filter(Boolean),
+    milestones: r.milestones.filter((m) => m >= V.data.range.start && m <= V.data.range.end), range: V.data.range,
+  });
+  return el('div', { class: 'tl-init-track', 'data-tl-track': r.id }, bar);
+}
+
+function stageRow(V, r, s) {
+  const seg = clip(V.data.range, { stage: s.id, start: s.start, due: s.due });
+  const track = seg
+    ? el('div', { class: 'tl-init-track' }, timelineBar({
+      label: COPY.aria.stageBar(r.title, s.label, { start: s.start, due: s.due }),
+      segments: [seg], milestones: [], range: V.data.range,
+    }))
+    : (V.data.range && r.dated ? el('div', { class: 'tl-init-track' }, el('span', { class: 'tl-init-sub__none' }, COPY.noDatedItems)) : null);
+  return el('div', { class: 'tl-init-row tl-init-row--stage', 'data-tl-stage': s.id },
+    el('div', { class: 'tl-init-name tl-init-sub' }, COPY.stageLine(s.label, s.done, s.total)), track);
+}
+
+function itemEl(V, r) {
+  const kids = [el('div', { class: 'tl-init-row' }, nameCell(V, r), r.dated && V.data.range ? trackCell(V, r) : null)];
+  if (V.open.has(r.id)) for (const s of r.stages) kids.push(stageRow(V, r, s));
+  return el('div', {
+    class: 'tl-init-item', role: 'listitem', 'data-tl-row': r.id, 'data-id': r.id, 'data-horizon': r.horizon, 'data-dated': r.dated ? '1' : '0',
+  }, kids);
+}
+
+function listEl(V, h, rows, dated) {
+  return el('div', { class: 'tl-init-list', role: 'list', 'data-tl-list': h, 'data-dated': dated ? '1' : '0', 'aria-label': COPY.aria.group(COPY.horizon[h]) },
+    rows.map((r) => itemEl(V, r)));
+}
+
+/* ── the chart and the undated section ───────────────────────────────────────────────────────────────────────────── */
+
+function chartEl(V, groups) {
+  const d = V.data;
+  const months = monthsOf(d.range);
+  const chart = el('div', { class: 'tl-init-chart', 'data-tl-chart': '', role: 'region', tabindex: '0', 'aria-label': COPY.aria.chart });
+  chart.style.setProperty('--tl-init-months', String(months.length));
+  chart.style.setProperty('--tl-init-cols', months.map((m) => m.days + 'fr').join(' '));
+  chart.style.setProperty('--tl-init-today', todayPercent(d.range, d).toFixed(2) + '%');
+  const head = el('div', { class: 'tl-init-head' }, el('div', { class: 'tl-init-corner' }),
+    el('div', { class: 'tl-init-months', 'data-tl-months': '' }, months.map((m, i) => el('div', { class: 'tl-init-month' }, monthLabel(m.start, i === 0)))));
+  const body = [head];
+  for (const g of groups) {
+    body.push(el('div', { class: 'tl-init-group', 'data-tl-group': g.h }, el('div', { class: 'tl-init-gname' }, COPY.horizon[g.h]), el('div', null)));
+    body.push(listEl(V, g.h, g.rows, true));
+  }
+  body.push(el('div', { class: 'tl-init-plot', 'aria-hidden': 'true' },
+    el('div', { class: 'tl-init-today', 'data-tl-today': '' }, el('span', { class: 'tl-init-today__label' }, COPY.today))));
+  chart.appendChild(el('div', { class: 'tl-init-inner' }, body));
+  return chart;
+}
+
+function undatedEl(V, groups) {
+  const kids = [el('h3', { class: 'tl-init-undated__title' }, COPY.undatedHead), el('p', { class: 'tl-init-undated__note' }, COPY.undatedNote)];
+  for (const g of groups) {
+    kids.push(el('div', { class: 'tl-init-gname tl-init-gname--undated', 'data-tl-group': g.h }, COPY.horizon[g.h]));
+    kids.push(listEl(V, g.h, g.rows, false));
+  }
+  return el('section', { class: 'tl-init-undated', 'data-tl-undated': '' }, kids);
+}
+
+function bodyOf(V) {
+  if (!V.ctx.ws) return [empty({ text: COPY.readFailed(COPY.why.noWs) })];
+  if (!V.data) {
+    if (V.error) return [empty({ text: COPY.readFailed(V.error), attrs: { role: 'alert', 'data-tl-error': '' } }), button({ label: COPY.retry, onClick: () => load(V), attrs: { 'data-tl-retry': '' } })];
+    return [empty({ text: COPY.reading })];
+  }
+  const d = V.data;
+  const groups = (dated) => HORIZONS.map((h) => ({ h, rows: d.horizons[h].filter((r) => r.dated === dated) })).filter((g) => g.rows.length);
+  const datedGroups = groups(true);
+  const undatedGroups = groups(false);
+  if (!datedGroups.length && !undatedGroups.length) return [empty({ text: COPY.none, attrs: { 'data-tl-none': '' } })];
+  const out = [];
+  if (V.error) out.push(empty({ text: COPY.readFailed(V.error), attrs: { role: 'alert', 'data-tl-error': '' } }));
+  if (datedGroups.length && d.range) {
+    out.push(chartEl(V, datedGroups));
+    if (d.range.clipped) out.push(el('p', { class: 'tl-init-note', 'data-tl-clipped': '' }, COPY.clipped(monthLabel(d.range.start, true), monthLabel(d.range.end, true))));
+  }
+  else out.push(empty({ text: COPY.noDates, attrs: { 'data-tl-nodates': '' } }));
+  if (undatedGroups.length) out.push(undatedEl(V, undatedGroups));
+  return out;
+}
+
+/* ── render, drag, reorder ───────────────────────────────────────────────────────────────────────────────────────── */
+
+function render(V) {
+  if (V.disposed) return;
+  V.drags.destroy();
+  const old = V.root.querySelector('.tl-init-chart');
+  const left = old ? old.scrollLeft : null;
+  setChildren(V.root, bodyOf(V));
+  const chart = V.root.querySelector('.tl-init-chart');
+  if (chart) {
+    if (left !== null) chart.scrollLeft = left;
+    else if (!V.scrolled) { V.scrolled = true; showToday(chart); }
+  }
+  if (V.focusId) {
+    const b = V.root.querySelector(`[data-tl-open="${CSS.escape(V.focusId)}"]`);
+    V.focusId = null;
+    if (b) b.focus();
+  }
+  bindDrag(V);
+}
+
+/** A chart wider than its box opens with today about a third of the way in, not on its first month. */
+function showToday(chart) {
+  if (chart.scrollWidth <= chart.clientWidth) return;
+  const plot = chart.querySelector('.tl-init-plot');
+  const today = chart.querySelector('.tl-init-today');
+  if (!plot || !today) return;
+  chart.scrollLeft = Math.max(0, plot.offsetLeft + today.offsetLeft - Math.round(chart.clientWidth / 3));
+}
+
+function bindDrag(V) {
+  loadSortable().then((Sortable) => {
+    if (!Sortable || V.disposed || V.drags.size || !V.data) return;
+    for (const list of V.root.querySelectorAll('.tl-init-list')) {
+      V.drags.add(new Sortable(list, baseOptions({
+        handle: SEL.drag, draggable: '.tl-init-item',
+        ghostClass: 'tl-init-ghost', chosenClass: 'tl-init-chosen', dragClass: 'tl-init-dragging', fallbackClass: 'tl-init-fallback',
+        onStart: () => { V.dragging = true; },
+        onEnd: (evt) => { V.dragging = false; drop(V, list, evt); },
+      })));
+    }
+  });
+}
+
+function drop(V, list, evt) {
+  const dirty = V.dirty; V.dirty = false;
+  const item = evt.item;
+  const id = item && item.getAttribute('data-id');
+  const r = id && V.data && V.data.horizons[item.getAttribute('data-horizon')].find((x) => x.id === id);
+  if (!r || evt.oldIndex === evt.newIndex) { if (dirty) render(V); return; }
+  const next = [...list.querySelectorAll(':scope > .tl-init-item')].map((n) => n.getAttribute('data-id'));
+  place(V, r, moveEvents(listOf(V, r), next, id));
+}
+
+/**
+ * The `placed` events that make the list `list` (rows of one horizon and one group, in the order shown) read as `next`
+ * (the same ids with `moved` in its new place). The ledger puts a row after the row `after` names, and a row it holds no
+ * line for is not found: such a row (`placed: false`) reads after every row that has a line, in id order. So:
+ *   - one event, `moved` after the row above it, when that row has a line (or there is none: the top) — the rows below
+ *     keep the order they read in;
+ *   - else one event for each row from the first row the move changes (or the first row with no line, if that is
+ *     earlier) to the last row that must have a line. The rows after that point have no line and are already in id order.
+ */
+export function moveEvents(list, next, moved) {
+  const horizon = list[0].horizon;
+  const cur = list.map((x) => x.id);
+  const has = new Map(list.map((x) => [x.id, !!x.placed]));
+  const line = (k) => ({ ev: 'placed', initiative: next[k], horizon, after: k ? next[k - 1] : null });
+  const to = next.indexOf(moved);
+  if (!to || has.get(next[to - 1])) return [line(to)];
+  const a = Math.min(next.findIndex((id, k) => id !== cur[k]), next.findIndex((id) => !has.get(id)));
+  const order = cur.filter((id) => !has.get(id));
+  let b = next.length;
+  let at = order.length;
+  while (b > a) {   // the tail of rows with no line that keep their id order
+    const k = order.indexOf(next[b - 1]);
+    if (k < 0 || k >= at) break;
+    at = k; b -= 1;
+  }
+  if (a < 0 || a >= b) return [line(to)];
+  const out = [];
+  for (let k = a; k < b; k++) out.push(line(k));
+  return out;
+}
+
+/** Write the `placed` events of one move. The page then reads the rows again. */
+async function place(V, r, events) {
+  if (V.busy) return;
+  V.busy = true;
+  V.focusId = r.id;
+  let res;
+  try { res = await pmPost('/api/placements', { ws: V.ctx.ws, events }); }
+  catch (e) { res = { ok: false, error: String((e && e.message) || e) }; }
+  V.busy = false;
+  if (V.disposed) return;
+  if (res && res.ok) {
+    if (events.length > 1) toast({ text: COPY.alsoPlaced(r.title, events.length - 1, COPY.horizon[r.horizon]) });
+    await load(V);
+    return;
+  }
+  toast({ text: COPY.moveFailed(r.title, (res && res.error) || COPY.why.noAnswer), tone: 'error' });
+  render(V);
+}
+
+/** Move `r` by `dir` places inside its own list (-1 up, 1 down), or to the top (dir 'top'). */
+function reorder(V, r, dir) {
+  const list = listOf(V, r);
+  const i = list.findIndex((x) => x.id === r.id);
+  const j = dir === 'top' ? 0 : i + dir;
+  if (i < 0 || j < 0 || j >= list.length || j === i) return;
+  const next = list.map((x) => x.id);
+  next.splice(i, 1); next.splice(j, 0, r.id);
+  place(V, r, moveEvents(list, next, r.id));
+}
+
+function openMenu(V, anchor, r) {
+  const list = listOf(V, r);
+  const i = list.findIndex((x) => x.id === r.id);
+  const items = [{ label: COPY.menu.open, onSelect: () => open_(V, r.id) }];
+  if (i > 0) items.push({ label: COPY.menu.top, onSelect: () => reorder(V, r, 'top') }, { label: COPY.menu.up, onSelect: () => reorder(V, r, -1) });
+  if (i >= 0 && i < list.length - 1) items.push({ label: COPY.menu.down, onSelect: () => reorder(V, r, 1) });
+  menu({ anchor, items, ariaLabel: COPY.aria.more(r.title) });
+}
+
+const open_ = (V, id) => { if (typeof V.ctx.openInitiative === 'function') V.ctx.openInitiative(V.ctx.repo, id); };
+
+function onKey(V, e) {
+  if (!e.altKey || (e.key !== 'ArrowUp' && e.key !== 'ArrowDown')) return;
+  const item = e.target && e.target.closest ? e.target.closest('.tl-init-item') : null;
+  if (!item) return;
+  const r = V.data && V.data.horizons[item.getAttribute('data-horizon')].find((x) => x.id === item.getAttribute('data-id'));
+  if (!r) return;
+  e.preventDefault(); e.stopPropagation();
+  reorder(V, r, e.key === 'ArrowUp' ? -1 : 1);
+}
+
+/* ── load, watch, mount ──────────────────────────────────────────────────────────────────────────────────────────── */
+
+const urlOf = (ws) => '/api/timeline?ws=' + encodeURIComponent(ws);
+
+/** Draw an answer of the route. During a drag it only marks the page dirty: the rows must not move under the pointer. */
+function apply(V, j) {
+  V.data = j; V.error = null;
+  if (V.dragging) V.dirty = true; else render(V);
+}
+
+async function load(V) {
+  if (!V.ctx.ws) { render(V); return; }
+  const seq = ++V.seq;
+  const j = await pmGet(urlOf(V.ctx.ws));
+  if (V.disposed || seq !== V.seq) return;
+  if (!j || j.ok === false) {
+    V.error = (j && j.error) || COPY.why.noAnswer;
+    if (!V.dragging) render(V);
+    return;
+  }
+  apply(V, j);
+  if (!V.stop) V.stop = watch(V);
+}
+
+/** The watcher's first read is the answer already on screen (no GET); every later read is compared with the sig drawn. */
+function watch(V) {
+  let first = true;
+  return watchSig(async () => {
+    if (first) { first = false; return JSON.stringify(V.data.sig); }
+    const seq = V.seq;   // a load that starts meanwhile draws its own answer, and this one is dropped
+    const k = await pmGet(urlOf(V.ctx.ws));
+    if (!k || k.ok === false || !k.sig) return null;
+    const sig = JSON.stringify(k.sig);
+    if (!V.disposed && seq === V.seq && sig !== JSON.stringify(V.data.sig)) apply(V, k);
+    return sig;
+  }, () => {}, { everyMs: 10000 });
+}
+
+function create(host, ctx) {
+  const V = {
+    host, ctx, ws: ctx.ws, root: el('div', { class: 'tl-init-root', 'data-tl-init': '' }), data: null, error: null, open: new Set(),
+    drags: dragSet(), dragging: false, dirty: false, busy: false, disposed: false, seq: 0, scrolled: false, stop: null, focusId: null,
+  };
+  V.root.addEventListener('keydown', (e) => onKey(V, e));
+  return V;
+}
+
+function dispose(host) {
+  const V = views.get(host);
+  if (!V) return;
+  views.delete(host);
+  V.disposed = true;
+  if (V.stop) V.stop();
+  V.drags.destroy();
+  if (V.root.parentNode === host) V.root.remove();
+}
+
+function mount(host, ctx) {
+  if (FIXTURE) return;
+  let V = views.get(host);
+  if (V && V.ws !== ctx.ws) { dispose(host); V = null; }
+  if (!V) {
+    ensureComponentsCss(); layer(); ensureSprite();
+    V = create(host, ctx);
+    views.set(host, V);
+    setChildren(host, [V.root]);
+    render(V);
+    load(V);
+    return;
+  }
+  V.ctx = ctx;
+  if (host.firstChild !== V.root || host.childNodes.length !== 1) setChildren(host, [V.root]);
+}
+
+registerInitiativesView('timeline', { label: COPY.view, mount, dispose });
+
+/* for the browser suites: the state of the view mounted in a host, read-only */
+export function _viewOf(host) { return views.get(host) || null; }

package/workspace/public/pm/initiatives-ui.js

@@ -0,0 +1,123 @@
+/* pm/initiatives-ui.js — the small pieces the Initiatives modules share (pm-os-absorb Run 2, slice 2D).
+ *
+ *   healthSignal(health)            the health reason as text plus a 6px dot, or null when on track (R8: on track shows nothing)
+ *   horizonLabel(h)                 "Now", "Next" or "Later"
+ *   progressText(row)               "7 of 12" or "no breakdown", from the server's own label
+ *   confirmSheet({…})               a sheet that asks for one press (a PM-only act): an optional choice, a reason, Cancel, Confirm
+ *   checkBySheet({…})               a sheet with a date and Save or Clear
+ *   say(out, ok)                    a toast for the answer of a write: the success text, or the server's refusal
+ * No native dialog is used anywhere here. Every control is a primitive (primitives.js).
+ */
+
+import { el } from './dom.js';
+import { button, field, signal, sheet, tabs, toast } from './primitives.js';
+import { COPY } from './initiatives-copy.js';
+
+export const horizonLabel = (h) => COPY.horizons[h] || h;
+export const progressText = (row) => (row && row.progress && row.progress.label) || '';
+
+/** The most severe reason of a health answer, as a signal. `on` shows nothing. */
+export function healthSignal(health) {
+  if (!health || health.level === 'on' || !Array.isArray(health.reasons) || !health.reasons.length) return null;
+  const top = health.reasons[0];
+  const tone = health.level === 'off' ? 'destructive' : health.level === 'at-risk' ? 'warning' : 'muted';
+  return signal({ text: top.text || COPY.healthUnknown, tone, title: top.source || null, attrs: { 'data-health': health.level } });
+}
+
+/** A toast for the answer of a write. A refusal shows the server's own words. */
+export function say(out, okText) {
+  if (out && out.ok) { if (okText) toast({ text: okText, timeout: 4000 }); return true; }
+  toast({ text: COPY.refused((out && out.error) || 'The server did not answer.'), tone: 'error', timeout: 8000 });
+  return false;
+}
+
+/**
+ * A sheet that asks for one press.
+ *   confirmSheet({ title, body, confirmLabel, reason: boolean, choice?: { label, items: [{ id, label }], value }, onConfirm(reason, choice) → Promise<{ ok, error? }> })
+ * `choice` is a row of radio buttons inside the sheet (the bulk lifecycle's state), so the choice and the confirm are one sheet and
+ * the default needs no press. A refusal stays in the sheet, in words, and the buttons come back; success closes it. Returns the sheet handle.
+ */
+export function confirmSheet({ title, body, confirmLabel, reason, choice, onConfirm }) {
+  let rf = null;
+  let picked = choice ? choice.value : null;
+  const err = el('p', { class: 'in-error', role: 'alert', 'data-in-error': '' });
+  err.hidden = true;
+  const note = el('p', { class: 'in-note' }, body || '');
+  const kids = [note];
+  if (choice) {
+    const holder = el('div', { 'data-in-choice': '' });
+    const draw = (focus) => {
+      holder.replaceChildren(tabs({ variant: 'segmented', role: 'radiogroup', items: choice.items, value: picked, ariaLabel: choice.label, full: true, onChange: (id) => { picked = id; draw(true); } }));
+      if (focus) { const b = holder.querySelector('[data-tab="' + picked + '"]'); if (b) b.focus(); }
+    };
+    draw(false);
+    kids.push(el('p', { class: 'in-note' }, choice.label), holder);
+  }
+  if (reason) { rf = field({ label: COPY.reason, kind: 'text', attrs: { 'data-in-reason': '' } }); kids.push(rf); }
+  kids.push(err);
+  let busy = false;
+  const go = button({
+    label: confirmLabel || COPY.confirm, variant: 'primary', attrs: { 'data-in-confirm': '' },
+    onClick: async () => {
+      if (busy) return;
+      busy = true; go.disabled = true; err.hidden = true;
+      let out;
+      try { out = await onConfirm(rf ? rf.control.value.trim() : '', picked); } catch (e) { out = { ok: false, error: String((e && e.message) || e) }; }
+      busy = false; go.disabled = false;
+      if (out && out.ok) { s.close(); return; }
+      err.textContent = COPY.refused((out && out.error) || 'The server did not answer.');
+      err.hidden = false;
+    },
+  });
+  const s = sheet({
+    mode: 'auto', title, body: kids, attrs: { 'data-in-sheet': 'confirm' },
+    actions: [button({ label: COPY.cancel, variant: 'outline', onClick: () => s.close(), attrs: { 'data-in-cancel': '' } }), go],
+  });
+  return s;
+}
+
+/** A sheet with one date. `onSave(date | null)` answers `{ ok, error? }`; Clear saves null. */
+export function checkBySheet({ title, value, onSave }) {
+  const f = field({ label: COPY.sheet.checkByLabel, kind: 'date', value: value || '', attrs: { 'data-in-date': '' } });
+  const err = el('p', { class: 'in-error', role: 'alert', 'data-in-error': '' });
+  err.hidden = true;
+  const run = async (date) => {
+    let out;
+    try { out = await onSave(date); } catch (e) { out = { ok: false, error: String((e && e.message) || e) }; }
+    if (out && out.ok) { s.close(); return; }
+    err.textContent = COPY.refused((out && out.error) || 'The server did not answer.');
+    err.hidden = false;
+  };
+  const s = sheet({
+    mode: 'auto', title, body: [f, err], attrs: { 'data-in-sheet': 'check-by' },
+    actions: [
+      button({ label: COPY.sheet.clear, variant: 'outline', onClick: () => run(null), attrs: { 'data-in-clear': '' } }),
+      button({ label: COPY.sheet.save, variant: 'primary', onClick: () => run(f.control.value || null), attrs: { 'data-in-save': '' } }),
+    ],
+  });
+  return s;
+}
+
+let rightDown = false;   // the right button is down: the menu waits for its release (see onContextMenu)
+let afterUp = [];
+if (typeof document !== 'undefined') {
+  document.addEventListener('pointerdown', (e) => { if (e.button === 2) rightDown = true; }, true);
+  const up = () => { rightDown = false; const run = afterUp; afterUp = []; for (const f of run) setTimeout(f, 0); };
+  document.addEventListener('pointerup', up, true);
+  document.addEventListener('pointercancel', up, true);
+}
+
+/**
+ * The context menu of a card or a row on a desk: a right click, or the menu key on a focused one. `find(target)` answers
+ * `{ anchor, id }` for the node under the pointer, or null. The menu is a popover that closes on a pointer-up outside it, so a
+ * right click that opens it between the button's down and up would close it at once: the open waits for the up.
+ */
+export function onContextMenu(root, find, open) {
+  root.addEventListener('contextmenu', (e) => {
+    const hit = find(e.target);
+    if (!hit) return;
+    e.preventDefault();
+    if (!rightDown) { open(hit.anchor, hit.id); return; }
+    afterUp.push(() => open(hit.anchor, hit.id));
+  });
+}