create-pmos 0.52.0 → 0.53.0

package/workspace/public/pm/primitives.js

@@ -0,0 +1,656 @@
+/* pm/primitives.js — the R27 primitives the Breakdown needs (pm-os-absorb Run 1).
+ *
+ * Every `pmc-` class name is written in this file (and the icon class in icons.js) and nowhere else. A module that needs
+ * to find a primitive in the DOM uses the selector constants in `SEL`; a module that needs a primitive calls a factory.
+ * The conformance gate (workspace/conformance-gate.js, R28-9) fails any other module that writes `pmc-`, so a primitive
+ * cannot be restyled or rebuilt by hand somewhere else.
+ *
+ * The look is components.css's primitives section: radius 0, neutral primary, uppercase tracked labels on buttons and
+ * tabs, underlined fields, 32px controls and 36px rows, 44px and 48px under a coarse pointer. Colour comes only from
+ * tokens.css.
+ *
+ * Overlays (the sheet, menus, toasts) live in one layer, `body > .pmc-layer > .pmc-layer__theme`, which mirrors the app
+ * root's `data-pm-theme` so the tokens resolve to the same theme. The sheet is a modal <dialog>; menus and toasts are
+ * popovers. Each Escape handler here stops propagation, because app.js closes the active tab on an Escape that reaches
+ * the window.
+ */
+
+import { el } from './dom.js';
+import { icon } from './icons.js';
+
+/** Selectors for the primitives, for the modules that query the DOM (drag handles, filters, tests). */
+export const SEL = Object.freeze({
+  layer: '.pmc-layer',
+  theme: '.pmc-layer__theme',
+  sprite: '.pmc-sprite',
+  icon: 'svg.pmc-icon',
+  btn: '.pmc-btn',
+  primary: '.pmc-btn--primary',
+  row: '.pmc-row',
+  owed: '.pmc-row--owed',
+  rowOpen: '.pmc-row__open',
+  rowTitle: '.pmc-row__title',
+  rowMeta: '.pmc-row__meta',
+  card: '.pmc-card',
+  cardOpen: '.pmc-card__open',
+  cardTitle: '.pmc-card__title',
+  cardMeta: '.pmc-card__meta',
+  title: '.pmc-row__title, .pmc-card__title',
+  meta: '.pmc-row__meta, .pmc-card__meta',
+  signal: '.pmc-signal',
+  drag: '.pmc-drag',
+  tabs: '.pmc-tabs',
+  tab: '.pmc-tabs__tab',
+  menu: '.pmc-menu',
+  menuItem: '.pmc-menu__item',
+  sheet: '.pmc-sheet',
+  sheetBody: '.pmc-sheet__body',
+  sheetActions: '.pmc-sheet__actions',
+  toast: '.pmc-toast',
+  fieldInput: '.pmc-field__input',
+  needsDot: '.pmc-needs-dot',
+  needsCount: '.pmc-needs-count',
+  meter: '.pmc-meter',
+  tlbar: '.pmc-tlbar',
+  tlbarSeg: '.pmc-tlbar__seg',
+  tlbarEnd: '.pmc-tlbar__end',
+  tlbarMilestone: '.pmc-tlbar__milestone',
+  tlbarToday: '.pmc-tlbar__today',
+});
+
+/* ── stylesheet and layer ─────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** Link /pm/components.css once. index.html is not edited: the sheet arrives with the first Breakdown. */
+export function ensureComponentsCss() {
+  if (typeof document === 'undefined' || document.querySelector('link[data-pmc]')) return;
+  const l = document.createElement('link');
+  l.rel = 'stylesheet';
+  l.href = '/pm/components.css';
+  l.setAttribute('data-pmc', '');
+  document.head.appendChild(l);
+}
+
+let layerTheme = null;
+let themeWatch = null;
+
+function themeSource() {
+  return document.querySelector('body > [data-pm-theme]') || document.querySelector('[data-pm-theme]:not(.pmc-layer__theme)');
+}
+
+/**
+ * The overlay layer: `body > div.pmc-layer > div.pmc-layer__theme[data-pm-theme]`, created once. The outer div carries no
+ * theme attribute, because mobile.css places `body > [data-pm-theme]` in the phone grid. Returns the theme div.
+ */
+export function layer() {
+  if (typeof document === 'undefined' || !document.body) return null;
+  if (layerTheme && layerTheme.isConnected) return layerTheme;
+  const outer = document.createElement('div');
+  outer.className = 'pmc-layer';
+  layerTheme = document.createElement('div');
+  layerTheme.className = 'pmc-layer__theme';
+  outer.appendChild(layerTheme);
+  document.body.appendChild(outer);
+  const mirror = () => {
+    const src = themeSource();
+    layerTheme.setAttribute('data-pm-theme', (src && src.getAttribute('data-pm-theme')) || 'dark');
+  };
+  mirror();
+  if (themeWatch) themeWatch.disconnect();
+  const src = themeSource();
+  if (src && typeof MutationObserver !== 'undefined') {
+    themeWatch = new MutationObserver(mirror);
+    themeWatch.observe(src, { attributes: true, attributeFilter: ['data-pm-theme'] });
+  }
+  return layerTheme;
+}
+
+/** The element an overlay opened now belongs in: the open sheet (so it is not inert under the modal), else the layer. */
+function overlayHost(anchor) {
+  const inSheet = anchor && anchor.closest ? anchor.closest('dialog.pmc-sheet[open]') : null;
+  if (inSheet) return inSheet;
+  const open = layer() && layer().querySelectorAll('dialog.pmc-sheet[open]');
+  return open && open.length ? open[open.length - 1] : layer();
+}
+
+let uid = 0;
+const nextId = (p) => p + '-' + (++uid);
+const cx = (...names) => names.filter(Boolean).join(' ');
+/** Spread `attrs` onto a primitive while keeping its own classes: `attrs.class` is added to them, never put in their place. */
+const withClass = (base, attrs) => {
+  const out = { ...(attrs || {}) };
+  const extra = out.class; delete out.class;
+  out.class = cx(base, extra);
+  return out;
+};
+
+/* ── button, icon button ─────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * button({ label, variant: 'primary'|'outline'|'ghost'|'danger', size: 'sm'?, icon?, iconEnd?, block?, onClick?, attrs? })
+ * A pane has at most one primary.
+ */
+export function button({ label, variant = 'outline', size, icon: lead, iconEnd, block, onClick, attrs, disabled } = {}) {
+  return el('button', {
+    type: 'button', onClick, disabled: !!disabled,
+    ...withClass(cx('pmc-btn', 'pmc-btn--' + variant, size && 'pmc-btn--' + size, block && 'pmc-btn--block'), attrs),
+  }, lead ? icon(lead) : null, el('span', { class: 'pmc-btn__label' }, label), iconEnd ? icon(iconEnd) : null);
+}
+
+/** iconButton({ icon, ariaLabel, onClick?, attrs?, expanded?, pressed? }). Throws without an aria-label. */
+export function iconButton({ icon: name, ariaLabel, onClick, attrs, expanded, size } = {}) {
+  if (!ariaLabel || !String(ariaLabel).trim()) throw new Error('iconButton(' + name + ') needs an ariaLabel');
+  const b = el('button', {
+    type: 'button', 'aria-label': ariaLabel, title: ariaLabel, onClick,
+    ...withClass(cx('pmc-btn', 'pmc-btn--ghost', 'pmc-btn--icon', size && 'pmc-btn--' + size), attrs),
+  }, icon(name));
+  if (expanded !== undefined) b.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+  return b;
+}
+
+/* ── field ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * field({ label, kind: 'text'|'title'|'textarea'|'select'|'date'|'check', value, options:[{value,label}], placeholder,
+ *         onCommit(value), hideLabel?, attrs? })
+ * Text commits on Enter or blur when the value changed; a textarea commits on blur; select, date and check commit on
+ * change. Escape in a text input with an edit restores the last committed value and stops there; with no edit inside a
+ * dialog it reaches the dialog, which closes. Returns the wrapper; the control is
+ * `wrapper.control`.
+ */
+export function field({ label, kind = 'text', value, options, placeholder, onCommit, hideLabel, attrs } = {}) {
+  const id = nextId('pmc-f');
+  let input;
+  if (kind === 'check') {
+    input = el('input', { type: 'checkbox', id, checked: !!value, ...withClass('pmc-check__box', attrs) });
+    input.addEventListener('change', () => { if (onCommit) onCommit(input.checked); });
+    const wrap = el('label', { class: 'pmc-check', for: id }, input, el('span', { class: 'pmc-check__label' }, label));
+    // a <label> already has a read-only `control` getter; an own property gives the same answer before it is attached
+    Object.defineProperty(wrap, 'control', { value: input });
+    return wrap;
+  }
+  if (kind === 'select') {
+    input = el('select', { id, ...withClass(cx('pmc-field__input', 'pmc-field__input--select'), attrs) },
+      ...(options || []).map((o) => el('option', { value: o.value, selected: String(o.value) === String(value), disabled: !!o.disabled }, o.label)));
+    input.addEventListener('change', () => { if (onCommit) onCommit(input.value); });
+  } else if (kind === 'textarea') {
+    input = el('textarea', { id, rows: 3, placeholder, ...withClass(cx('pmc-field__input', 'pmc-field__input--area'), attrs) });
+    input.value = value || '';
+  } else {
+    input = el('input', {
+      id, type: kind === 'date' ? 'date' : 'text', placeholder, autocomplete: 'off',
+      ...withClass(cx('pmc-field__input', kind === 'title' && 'pmc-field__input--title'), attrs),
+    });
+    input.value = value || '';
+  }
+  if (kind === 'date') input.addEventListener('change', () => { if (onCommit) onCommit(input.value || null); });
+  if (kind === 'text' || kind === 'title' || kind === 'textarea') {
+    let last = input.value;
+    const commit = () => { if (input.value !== last) { last = input.value; if (onCommit) onCommit(input.value); } };
+    input.addEventListener('blur', commit);
+    input.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' && kind !== 'textarea') { e.preventDefault(); e.stopPropagation(); commit(); }
+      else if (e.key === 'Escape') {
+        // an edit to drop: restore it and stop. Nothing to drop inside a dialog: let the dialog close.
+        if (input.value === last && input.closest('dialog')) return;
+        e.preventDefault(); e.stopPropagation(); input.value = last; input.blur();
+      }
+    });
+    input.resetCommitted = (v) => { last = v; input.value = v; };
+  }
+  const wrap = el('div', { class: 'pmc-field' },
+    el('label', { class: cx('pmc-field__label', hideLabel && 'pmc-field__label--hidden'), for: id }, label), input);
+  wrap.control = input;
+  return wrap;
+}
+
+/* ── badge, signal, dots ─────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** badge({ text, tone: 'muted'|'outline'|'warning'|'destructive' }): a small caps label. */
+export function badge({ text, tone = 'muted', attrs } = {}) {
+  return el('span', withClass(cx('pmc-badge', 'pmc-badge--' + tone), attrs), text);
+}
+
+/** signal({ text, tone: 'muted'|'warning'|'destructive', title?, wrap? }). Warning and destructive add a 6px dot.
+ * `wrap` lets a long text wrap inside its box (the Timeline's health reason), not stay on one line. */
+export function signal({ text, tone = 'muted', title, attrs, wrap = false } = {}) {
+  return el('span', { title, ...withClass(cx('pmc-signal', 'pmc-signal--' + tone, wrap && 'pmc-signal--wrap'), attrs) },
+    tone === 'warning' || tone === 'destructive' ? el('span', { class: 'pmc-signal__dot', 'aria-hidden': 'true' }) : null,
+    el('span', null, text));
+}
+
+/** The needs-you dot: with the count below, the only place the brand colour appears. */
+export function needsDot() {
+  return el('span', { class: 'pmc-needs-dot', 'aria-hidden': 'true' });
+}
+
+/** The Today count beside the dot: the number in the brand colour. Everything else stays neutral. */
+export function needsCount(text, attrs) {
+  return el('span', withClass('pmc-needs-count', attrs), text);
+}
+
+/** A paragraph of a dialog sheet (dialogs.js): the question's own words, line breaks kept. */
+export function dialogText(text) {
+  return el('p', { class: 'pmc-dialog__text' }, text);
+}
+
+/** A grip for pointer dragging. Not focusable and not a control: the keyboard path is Alt+Arrow and the menus. */
+export function dragHandle({ label } = {}) {
+  return el('span', { class: 'pmc-drag', 'aria-hidden': 'true', title: label || null }, icon('grip-vertical'));
+}
+
+/* ── row, card ───────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function titleLine(cls, title, titleIcon) {
+  return el('span', { class: cls }, titleIcon ? icon(titleIcon) : null, el('span', { class: 'pmc-title__text' }, title));
+}
+
+function metaLine(cls, meta, signals) {
+  const parts = (meta || []).filter((m) => m !== null && m !== undefined && m !== '');
+  const sigs = (signals || []).filter(Boolean).slice(0, 2);
+  if (!parts.length && !sigs.length) return null;
+  const kids = [];
+  parts.forEach((p, i) => { if (i) kids.push(el('span', { class: 'pmc-sep', 'aria-hidden': 'true' }, '·')); kids.push(el('span', null, p)); });
+  sigs.forEach((s) => { if (kids.length) kids.push(el('span', { class: 'pmc-sep', 'aria-hidden': 'true' }, '·')); kids.push(s); });
+  return el('span', { class: cls }, kids);
+}
+
+/**
+ * row({ title, titleIcon?, meta?: string[], signals?: Node[] (2 at most), lead?: Node[], trail?: Node[], onOpen?, openLabel?,
+ *       owed?: boolean, done?: boolean, attrs? })
+ * One title, one meta line holding at most two signals. With `onOpen` the title and meta are one button (the row's
+ * focus target); without it they are plain text.
+ */
+export function row({ title, titleIcon, meta, signals, lead, trail, onOpen, openLabel, owed, done, proposed, attrs, openAttrs } = {}) {
+  const body = [titleLine('pmc-row__title', title, titleIcon), metaLine('pmc-row__meta', meta, signals)];
+  const main = onOpen
+    ? el('button', { type: 'button', class: 'pmc-row__open', 'aria-label': openLabel || null, onClick: onOpen, ...(openAttrs || {}) }, body)
+    : el('span', { class: 'pmc-row__main' }, body);
+  return el('div', withClass(cx('pmc-row', owed && 'pmc-row--owed', done && 'pmc-row--done', proposed && 'pmc-row--proposed'), attrs),
+  lead && lead.length ? el('span', { class: 'pmc-row__lead' }, lead) : null,
+  main,
+  trail && trail.length ? el('span', { class: 'pmc-row__trail' }, trail) : null);
+}
+
+/** card({ title, titleIcon?, meta?, signals?, lead?, trail?, onOpen, openLabel?, attrs? }): a raised card with one open button. */
+export function card({ title, titleIcon, meta, signals, lead, trail, onOpen, openLabel, muted, attrs, openAttrs } = {}) {
+  // the open button holds the title and the meta line, as a row's does: one column, and one tall target on a phone
+  const open = el('button', { type: 'button', class: 'pmc-card__open', 'aria-label': openLabel || null, onClick: onOpen, ...(openAttrs || {}) },
+    titleLine('pmc-card__title', title, titleIcon), metaLine('pmc-card__meta', meta, signals));
+  return el('div', withClass(cx('pmc-card', muted && 'pmc-card--muted'), attrs),
+    el('div', { class: 'pmc-card__top' },
+      lead && lead.length ? el('span', { class: 'pmc-card__lead' }, lead) : null,
+      open,
+      trail && trail.length ? el('span', { class: 'pmc-card__trail' }, trail) : null));
+}
+
+/* ── tabs ────────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/**
+ * tabs({ variant: 'segmented'|'line', role: 'tablist'|'radiogroup', items: [{ id, label, count? }], value, onChange(id),
+ *        ariaLabel, full? })
+ * Arrow keys move focus between tabs. In a tablist the focused tab is also selected; in a radiogroup (the item sheet's
+ * state buttons, where a press writes) selection needs Space or Enter, so moving focus writes nothing.
+ */
+export function tabs({ variant = 'segmented', role = 'tablist', items, value, onChange, ariaLabel, full, attrs } = {}) {
+  const radio = role === 'radiogroup';
+  const btns = (items || []).map((it) => {
+    const on = it.id === value;
+    return el('button', {
+      type: 'button', class: 'pmc-tabs__tab', role: radio ? 'radio' : 'tab', 'data-tab': it.id,
+      'aria-selected': radio ? null : (on ? 'true' : 'false'), 'aria-checked': radio ? (on ? 'true' : 'false') : null,
+      tabindex: on || (value == null && it === items[0]) ? '0' : '-1',
+      onClick: () => { if (onChange) onChange(it.id); },
+    }, el('span', null, it.label), it.count !== undefined && it.count !== null ? el('span', { class: 'pmc-tabs__count' }, String(it.count)) : null);
+  });
+  const box = el('div', { role, 'aria-label': ariaLabel, ...withClass(cx('pmc-tabs', 'pmc-tabs--' + variant, full && 'pmc-tabs--full'), attrs) }, btns);
+  box.addEventListener('keydown', (e) => {
+    const keys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'];
+    if (!keys.includes(e.key) || e.altKey || e.metaKey || e.ctrlKey) return;
+    const i = btns.indexOf(document.activeElement);
+    if (i < 0) return;
+    e.preventDefault(); e.stopPropagation();
+    let j = i;
+    if (e.key === 'Home') j = 0; else if (e.key === 'End') j = btns.length - 1;
+    else j = (i + (e.key === 'ArrowLeft' || e.key === 'ArrowUp' ? -1 : 1) + btns.length) % btns.length;
+    btns.forEach((b, k) => b.setAttribute('tabindex', k === j ? '0' : '-1'));
+    btns[j].focus();
+    if (!radio && onChange) onChange(items[j].id);
+  });
+  return box;
+}
+
+/* ── menu ────────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+let openMenu = null;
+let lastMenuClose = { anchor: null, at: 0 };
+
+/**
+ * menu({ anchor, items: [{ label, onSelect, danger?, sep? }], ariaLabel }): opens a popover menu under `anchor`.
+ * Arrow keys move, Enter or Space chooses, Escape closes and returns focus to the anchor. Pressing the anchor again
+ * closes it.
+ */
+export function menu({ anchor, items, ariaLabel } = {}) {
+  if (openMenu && openMenu.anchor === anchor) { openMenu.close(); return null; }
+  if (openMenu) openMenu.close();
+  if (lastMenuClose.anchor === anchor && Date.now() - lastMenuClose.at < 250) return null;
+  const host = overlayHost(anchor);
+  const btns = [];
+  const node = el('div', { class: 'pmc-menu', role: 'menu', 'aria-label': ariaLabel, popover: 'auto' });
+  let closed = false;
+  const close = (refocus) => {
+    if (closed) return; closed = true;
+    lastMenuClose = { anchor, at: Date.now() };
+    try { if (node.matches(':popover-open')) node.hidePopover(); } catch { /* not shown */ }
+    node.remove();
+    if (anchor) anchor.setAttribute('aria-expanded', 'false');
+    if (openMenu && openMenu.node === node) openMenu = null;
+    if (refocus && anchor && anchor.isConnected) anchor.focus();
+  };
+  for (const it of items || []) {
+    if (it.sep) { node.appendChild(el('div', { class: 'pmc-menu__sep', role: 'separator' })); continue; }
+    const b = el('button', {
+      type: 'button', role: 'menuitem', tabindex: '-1', class: cx('pmc-menu__item', it.danger && 'pmc-menu__item--danger'),
+      onClick: (e) => { e.stopPropagation(); close(false); if (it.onSelect) it.onSelect(); },
+    }, it.icon ? icon(it.icon) : null, el('span', null, it.label));
+    btns.push(b); node.appendChild(b);
+  }
+  node.addEventListener('toggle', (e) => { if (e.newState === 'closed') close(false); });
+  node.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); close(true); return; }
+    if (e.key === 'Tab') { close(false); return; }
+    if (['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) {
+      e.preventDefault(); e.stopPropagation();
+      const i = btns.indexOf(document.activeElement);
+      let j = e.key === 'Home' ? 0 : e.key === 'End' ? btns.length - 1 : (i + (e.key === 'ArrowUp' ? -1 : 1) + btns.length) % btns.length;
+      if (i < 0 && e.key === 'ArrowUp') j = btns.length - 1;
+      if (btns[j]) btns[j].focus();
+    }
+  });
+  host.appendChild(node);
+  try { node.showPopover(); } catch { /* popover unsupported: still positioned and shown */ }
+  const r = anchor ? anchor.getBoundingClientRect() : { left: 16, right: 16, top: 16, bottom: 16 };
+  const w = node.offsetWidth; const h = node.offsetHeight;
+  const vw = window.innerWidth; const vh = window.innerHeight;
+  const x = Math.max(8, Math.min(vw - w - 8, r.right - w));
+  const y = r.bottom + 4 + h > vh - 8 ? Math.max(8, r.top - 4 - h) : r.bottom + 4;
+  node.style.setProperty('--pmc-x', Math.round(x) + 'px');
+  node.style.setProperty('--pmc-y', Math.round(y) + 'px');
+  if (anchor) { anchor.setAttribute('aria-expanded', 'true'); anchor.setAttribute('aria-haspopup', 'menu'); }
+  if (btns[0]) btns[0].focus();
+  openMenu = { node, anchor, close };
+  return openMenu;
+}
+
+/* ── sheet ───────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** True when a sheet should come up from the bottom: the app's own phone breakpoint. */
+export function narrowViewport() {
+  return typeof matchMedia === 'function' && matchMedia('(max-width: 760px)').matches;
+}
+
+/**
+ * sheet({ mode: 'auto'|'side'|'bottom', title, sub, body: Node[], actions: Node[], onClose, attrs })
+ * A modal <dialog> in the layer: 420px at the side above 760px, a bottom sheet below. Escape and the backdrop close it.
+ * On a phone the sheet follows the on-screen keyboard through visualViewport. Returns { dialog, body, close, setHead }.
+ */
+export function sheet({ mode = 'auto', title, sub, body, actions, onClose, attrs } = {}) {
+  const m = mode === 'auto' ? (narrowViewport() ? 'bottom' : 'side') : mode;
+  const tid = nextId('pmc-sheet-t');
+  const titleEl = el('h2', { class: 'pmc-sheet__title', id: tid }, title || '');
+  const subEl = el('div', { class: 'pmc-sheet__sub' }, sub || '');
+  const bodyEl = el('div', { class: 'pmc-sheet__body' }, body || []);
+  let closed = false;
+  const dialog = el('dialog', { 'aria-modal': 'true', 'aria-labelledby': tid, tabindex: '-1', ...withClass(cx('pmc-sheet', 'pmc-sheet--' + m), attrs) },
+  m === 'bottom' ? el('div', { class: 'pmc-sheet__handle', 'aria-hidden': 'true' }) : null,
+  el('div', { class: 'pmc-sheet__head' }, el('div', { class: 'pmc-sheet__heading' }, titleEl, subEl),
+    iconButton({ icon: 'x', ariaLabel: 'Close', onClick: () => close() })),
+  bodyEl,
+  actions && actions.length ? el('div', { class: 'pmc-sheet__actions' }, actions) : null);
+
+  const vv = typeof window !== 'undefined' ? window.visualViewport : null;
+  const fit = () => {
+    if (!vv) return;
+    const kb = Math.max(0, window.innerHeight - (vv.height + vv.offsetTop));
+    dialog.style.setProperty('--pmc-kb', Math.round(kb) + 'px');
+    dialog.style.setProperty('--pmc-vvh', Math.round(vv.height) + 'px');
+  };
+  const close = () => {
+    if (closed) return; closed = true;
+    if (vv && m === 'bottom') { vv.removeEventListener('resize', fit); vv.removeEventListener('scroll', fit); }
+    try { if (dialog.open) dialog.close(); } catch { /* already closed */ }
+    // A toast raised while the sheet was open (an Undo, say) outlives the sheet: it moves to the layer.
+    for (const t of [...dialog.querySelectorAll(':scope > .pmc-toast')]) {
+      layer().appendChild(t);
+      try { t.showPopover(); } catch { /* popover unsupported */ }
+    }
+    dialog.remove();
+    if (onClose) onClose();
+  };
+  dialog.addEventListener('cancel', (e) => { e.preventDefault(); close(); });
+  dialog.addEventListener('keydown', (e) => { if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); close(); } });
+  dialog.addEventListener('click', (e) => { if (e.target === dialog) close(); });
+  layer().appendChild(dialog);
+  if (vv && m === 'bottom') { vv.addEventListener('resize', fit); vv.addEventListener('scroll', fit); fit(); }
+  dialog.showModal();
+  return {
+    dialog, body: bodyEl, close, mode: m,
+    get open() { return !closed; },
+    setHead(t, s) { titleEl.textContent = t || ''; subEl.textContent = s || ''; },
+  };
+}
+
+/* ── meter, toast, empty ─────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** meter({ done, total, label }): a 2px bar and its label ("7 of 12", or "no breakdown" with an empty track). */
+export function meter({ done = 0, total = 0, label } = {}) {
+  const fill = el('span', { class: 'pmc-meter__fill' });
+  fill.style.setProperty('--pmc-value', (total > 0 ? Math.round((100 * done) / total) : 0) + '%');
+  return el('span', { class: 'pmc-meter' },
+    el('span', { class: 'pmc-meter__track', 'aria-hidden': 'true' }, fill),
+    el('span', { class: 'pmc-meter__label' }, label));
+}
+
+const toasts = [];
+function restack() {
+  toasts.forEach((t, i) => t.node.style.setProperty('--pmc-toast-i', String(toasts.length - 1 - i)));
+}
+
+/**
+ * toast({ text, actionLabel?, icon?, onAction?, timeout = 6000, tone? }): a short message at the bottom, stacked when
+ * several are up. Returns { close }. The action button closes the toast before it calls onAction.
+ */
+export function toast({ text, actionLabel, icon: ic, onAction, timeout = 6000, tone } = {}) {
+  const host = overlayHost(null);
+  let timer = null;
+  const node = el('div', { class: cx('pmc-toast', tone && 'pmc-toast--' + tone), role: 'status', 'aria-live': 'polite', popover: 'manual' },
+    el('span', { class: 'pmc-toast__text' }, text));
+  const t = { node };
+  const close = () => {
+    if (timer) clearTimeout(timer); timer = null;
+    const i = toasts.indexOf(t); if (i >= 0) toasts.splice(i, 1);
+    try { if (node.matches(':popover-open')) node.hidePopover(); } catch { /* not shown */ }
+    node.remove(); restack();
+  };
+  t.close = close;
+  if (actionLabel) {
+    node.appendChild(button({
+      label: actionLabel, variant: 'ghost', size: 'sm', icon: ic,
+      onClick: (e) => {
+        e.stopPropagation();
+        // The pressed button goes with the toast. Focus would fall to <body>, where the next Escape closes the tab:
+        // give it back to the sheet the toast sits in, so Escape closes only the sheet.
+        const home = node.closest('dialog');
+        close();
+        if (onAction) onAction();
+        if (home && home.isConnected && (document.activeElement === document.body || !document.activeElement)) home.focus({ preventScroll: true });
+      },
+    }));
+  }
+  host.appendChild(node);
+  try { node.showPopover(); } catch { /* popover unsupported */ }
+  toasts.push(t); restack();
+  if (timeout > 0) timer = setTimeout(close, timeout);
+  return t;
+}
+
+/** empty({ text }): the quiet line an empty list shows. */
+export function empty({ text, attrs } = {}) {
+  return el('div', withClass('pmc-empty', attrs), text);
+}
+
+/* ── timeline bar ────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/* Calendar days, never shifted by the viewer's time zone: 'YYYY-MM-DD' -> days since 1970-01-01. */
+const TL_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const tlDay = (d) => (TL_DATE.test(String(d || '')) ? Math.round(Date.UTC(+d.slice(0, 4), +d.slice(5, 7) - 1, +d.slice(8, 10)) / 86400000) : NaN);
+const tlDate = (n) => new Date(n * 86400000).toISOString().slice(0, 10);
+const tlClamp = (v) => Math.max(0, Math.min(100, v));
+
+/**
+ * timelinePct(range, date, { end }): where `date` falls on the axis `range` ({ start, end }, both days inside it), in
+ * percent of the axis width: the start of that day, or its end with `end: true`. The month ticks and the today label of
+ * a chart use it, so they line up with the bars. NaN for a bad date or range.
+ */
+export function timelinePct(range, date, { end = false } = {}) {
+  const a = tlDay(range && range.start); const b = tlDay(range && range.end); const d = tlDay(date);
+  if (Number.isNaN(a) || Number.isNaN(b) || Number.isNaN(d) || b < a) return NaN;
+  return ((d - a + (end ? 1 : 0)) / (b - a + 1)) * 100;
+}
+
+const tlPlace = (node, range, start, due) => {
+  const l = tlClamp(timelinePct(range, start));
+  const r = tlClamp(timelinePct(range, due, { end: true }));
+  node.style.setProperty('--pmc-tl-left', l.toFixed(3) + '%');
+  node.style.setProperty('--pmc-tl-width', Math.max(0, r - l).toFixed(3) + '%');
+  node.setAttribute('data-start', start || '');
+  node.setAttribute('data-due', due || '');
+};
+
+/**
+ * timelineBar({ label, segments, milestones, range, today, attrs, drag }): one row's bar on a time axis, split by stage,
+ * with a ◆ for each milestone and the line for today. Breakdown › Timeline (Run 4, 4B) and Initiatives › Timeline (4C)
+ * both draw their rows with it. The bars are grey; colour appears only for health (R8: `health` 'risk' or 'off').
+ *   segments    [{ stage, start, due, label?, health?, done?, muted? }]   dates 'YYYY-MM-DD', both days inside the
+ *               segment; a done segment is drawn darker, a muted one (a proposal not kept) lighter with a dashed edge.
+ *               Each segment after the first starts with a 2px gap, so stages that touch or overlap stay apart
+ *   milestones  [date | { date, health? }]
+ *   range       { start, end }   the axis, both days inside it; every row of one chart passes the same range
+ *   today       date             optional: a 1px line at the start of that day (rows stack, so the lines join)
+ *   drag        optional. Each segment becomes a button that moves its dates. Without it the bar is a picture (role img)
+ *               and nothing on it reacts, which is how an initiative bar stays still (PRD R20).
+ *     onCommit({ index, start, due, mode })   once per gesture: mode 'move' shifts both dates, 'end' changes the due
+ *     onOpen(index)                           a press with no movement
+ *     onStart(), onEnd()                      around a pointer gesture, so the caller can hold its re-render
+ * Pointer: drag the segment to move it, or its end (the last 12px, 24px under a coarse pointer, and at most a third of
+ * the segment) to change the due date; a segment narrower than 24px always moves whole. Under a coarse pointer a
+ * movable segment takes touches at least 44px wide, centred on its dates; what it draws keeps its true width.
+ * A day is the bar's width over the axis days; a move of less than 4px is a press. Keyboard: Left and Right move by a
+ * day, Shift with Left or Right changes the due date, Enter saves, Escape puts it back; leaving the segment with a change
+ * saves it. Each gesture calls onCommit at most once, so one drag writes one line. The segment shows the new dates while
+ * it moves.
+ */
+export function timelineBar({ label, segments = [], milestones = [], range, today, attrs, drag } = {}) {
+  const canDrag = !!(drag && typeof drag.onCommit === 'function' && range);
+  const bar = el('div', {
+    role: canDrag ? 'group' : 'img', 'aria-label': label || null, 'data-range': range ? range.start + '/' + range.end : null,
+    ...withClass(cx('pmc-tlbar', canDrag && 'pmc-tlbar--drag'), attrs),
+  });
+  segments.forEach((g, index) => {
+    const health = g.health === 'risk' || g.health === 'off' ? g.health : null;
+    const cls = cx('pmc-tlbar__seg', g.done && 'pmc-tlbar__seg--done', g.muted && 'pmc-tlbar__seg--muted', health && 'pmc-tlbar__seg--' + health);
+    const fill = el('span', { class: 'pmc-tlbar__fill', 'aria-hidden': 'true' });
+    const node = canDrag
+      ? el('button', { type: 'button', class: cls, 'aria-label': g.label || null, 'data-stage': g.stage || '', 'data-index': String(index) },
+        fill, el('span', { class: 'pmc-tlbar__end', 'aria-hidden': 'true' }))
+      : el('span', { class: cls, 'data-stage': g.stage || '', 'data-index': String(index) }, fill);
+    if (health) node.setAttribute('data-health', health);
+    if (range) tlPlace(node, range, g.start, g.due);
+    else { node.setAttribute('data-start', g.start || ''); node.setAttribute('data-due', g.due || ''); }
+    if (canDrag) tlDraggable(bar, node, g, index, range, drag);
+    bar.appendChild(node);
+  });
+  for (const m of milestones) {
+    const d = typeof m === 'string' ? m : m && m.date;
+    const health = m && typeof m === 'object' && (m.health === 'risk' || m.health === 'off') ? m.health : null;
+    const node = el('span', { class: cx('pmc-tlbar__milestone', health && 'pmc-tlbar__milestone--' + health), 'data-date': d || '', 'aria-hidden': 'true' });
+    if (range) node.style.setProperty('--pmc-tl-left', tlClamp((timelinePct(range, d) + timelinePct(range, d, { end: true })) / 2).toFixed(3) + '%');
+    bar.appendChild(node);
+  }
+  if (today && range && today >= range.start && today <= range.end) {
+    const t = el('span', { class: 'pmc-tlbar__today', 'data-date': today, 'aria-hidden': 'true' });
+    t.style.setProperty('--pmc-tl-left', tlClamp(timelinePct(range, today)).toFixed(3) + '%');
+    bar.appendChild(t);
+  }
+  return bar;
+}
+
+/* One segment's pointer and keyboard moves. `g` holds the saved dates; `cur` is what the segment shows. */
+function tlDraggable(bar, node, g, index, range, drag) {
+  if (Number.isNaN(tlDay(g.start)) || Number.isNaN(tlDay(g.due))) return;
+  const total = tlDay(range.end) - tlDay(range.start) + 1;
+  let cur = { start: g.start, due: g.due, mode: null };
+  /* `days` after the saved dates: 'move' shifts both, 'end' moves the due and never before the start */
+  const show = (mode, days) => {
+    const s0 = tlDay(g.start); const d0 = tlDay(g.due);
+    const start = mode === 'move' ? tlDate(s0 + days) : g.start;
+    const due = mode === 'move' ? tlDate(d0 + days) : tlDate(Math.max(s0, d0 + days));
+    cur = { start, due, mode: start === g.start && due === g.due ? null : mode };
+    tlPlace(node, range, start, due);
+  };
+  const reset = () => { cur = { start: g.start, due: g.due, mode: null }; tlPlace(node, range, g.start, g.due); };
+  const commit = () => {
+    if (!cur.mode) return;
+    const out = { index, start: cur.start, due: cur.due, mode: cur.mode };
+    // the segment keeps the new dates until the caller draws again from the saved ledger
+    g = { ...g, start: cur.start, due: cur.due };
+    cur = { start: g.start, due: g.due, mode: null };
+    drag.onCommit(out);
+  };
+  let p = null;   // the pointer gesture: { id, x0, mode, w, moved }
+  let swallowClick = false;
+  node.addEventListener('pointerdown', (e) => {
+    if (e.button !== 0 || p) return;
+    // a segment under 24px is all handle to a finger or a mouse: it moves whole, and its due date changes by keyboard
+    const end = e.target && e.target.closest && e.target.closest('.pmc-tlbar__end') && node.getBoundingClientRect().width >= 24;
+    p = { id: e.pointerId, x0: e.clientX, mode: end ? 'end' : 'move', w: bar.getBoundingClientRect().width || 1, moved: false };
+    try { node.setPointerCapture(e.pointerId); } catch { /* the pointer is gone */ }
+  });
+  node.addEventListener('pointermove', (e) => {
+    if (!p || e.pointerId !== p.id) return;
+    const dx = e.clientX - p.x0;
+    if (!p.moved && Math.abs(dx) < 4) return;
+    if (!p.moved) { p.moved = true; node.classList.add('pmc-tlbar__seg--moving'); if (typeof drag.onStart === 'function') drag.onStart(); }
+    e.preventDefault();
+    show(p.mode, Math.round((dx / p.w) * total));
+  });
+  const finish = (e, cancelled) => {
+    if (!p || e.pointerId !== p.id) return;
+    const moved = p.moved;
+    p = null;
+    node.classList.remove('pmc-tlbar__seg--moving');
+    if (!moved) return;
+    swallowClick = true;
+    setTimeout(() => { swallowClick = false; }, 0);
+    if (cancelled) reset(); else commit();
+    if (typeof drag.onEnd === 'function') drag.onEnd();
+  };
+  node.addEventListener('pointerup', (e) => finish(e, false));
+  node.addEventListener('pointercancel', (e) => finish(e, true));
+  node.addEventListener('lostpointercapture', (e) => finish(e, false));
+  node.addEventListener('click', (e) => {
+    if (swallowClick) { swallowClick = false; e.preventDefault(); return; }
+    if (!cur.mode && typeof drag.onOpen === 'function') drag.onOpen(index);
+  });
+  node.addEventListener('keydown', (e) => {
+    if (e.altKey || e.ctrlKey || e.metaKey) return;
+    if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+      e.preventDefault(); e.stopPropagation();
+      const mode = e.shiftKey ? 'end' : 'move';
+      if (cur.mode && cur.mode !== mode) reset();   // changing what moves starts again from the saved dates
+      const step = e.key === 'ArrowLeft' ? -1 : 1;
+      show(mode, (mode === 'move' ? tlDay(cur.start) - tlDay(g.start) : tlDay(cur.due) - tlDay(g.due)) + step);
+    } else if (e.key === 'Enter' && cur.mode) { e.preventDefault(); e.stopPropagation(); commit(); }
+    else if (e.key === 'Escape' && cur.mode) { e.preventDefault(); e.stopPropagation(); reset(); }
+  });
+  node.addEventListener('blur', () => { if (cur.mode) commit(); });
+}