aimeat 2.2.0 → 2.3.0

package/dist/static/sdk-libs/game/overlay.js

@@ -0,0 +1,193 @@
+/**
+ * @file game/overlay.js
+ * @description The three things that appear over a view: the modal dialog, the transient toast,
+ *   and the promise-returning confirm for anything irreversible.
+ *
+ *   CORRECT AT A SHORT VIEWPORT. The dialog centres with `margin: auto` inside a scrolling
+ *   container instead of `align-items: center`, so at 1280x460 its top edge stays on screen and
+ *   the close control stays reachable. The stylesheet carries that rule; this file only makes
+ *   sure the structure it needs exists.
+ *
+ *   FOCUS is taken on open and given back on close, Escape closes a dismissible dialog, and Tab
+ *   is kept inside it — a dialog you can Tab out of behind the scrim is worse than no dialog.
+ * @structure modal(spec) · toast(msg, kind, opts) · confirm(spec) → Promise<boolean>
+ * @usage  const ok = await AIMEAT.game.confirm({ title: 'Delete run?', danger: true });
+ *         AIMEAT.game.toast('Saved', 'ok');
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, append, clear, uid } from './dom.js';
+import { t } from './i18n.js';
+
+/** Elements that can hold focus inside a dialog. */
+const FOCUSABLE = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+/** The mark shown on a toast, per kind. Functional glyphs only. */
+const TOAST_MARK = { ok: '✓', err: '✗', warn: '!', info: 'i' };
+
+/**
+ * @typedef {object} OverlayAction
+ * @property {string} id
+ * @property {string} label
+ * @property {'primary'|'ghost'|'danger'|'plain'} [kind]
+ * @property {(action: OverlayAction) => void} [onClick]
+ */
+
+/**
+ * An overlay dialog.
+ * @param {{
+ *   title: string, body?: any, actions?: OverlayAction[], onClose?: () => void,
+ *   dismissible?: boolean, closeLabel?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, body: HTMLElement, set: (patch: any) => void, close: () => void, destroy: () => void }}
+ */
+export function modal(spec) {
+  const dismissible = spec.dismissible !== false;
+  const titleId = uid('ag-modal-title');
+  const returnTo = /** @type {HTMLElement|null} */ (document.activeElement);
+
+  const heading = el('h2', { class: 'ag-title', id: titleId, text: spec.title });
+  const closeBtn = el('button', {
+    type: 'button', class: 'ag-btn ag-btn--ghost', 'aria-label': spec.closeLabel || t('close'),
+    on: { click: function () { api.close(); } },
+  }, '✗');
+  const head = el('div', { class: 'ag-modal__head' }, [heading, dismissible ? closeBtn : null]);
+
+  const body = el('div', { class: 'ag-modal__body ag-scroll' });
+  if (spec.body != null) append(body, spec.body);
+
+  const bar = el('div', { class: 'ag-modal__actions' });
+
+  const dialog = el('div', {
+    class: 'ag-modal__dialog', role: 'dialog', 'aria-modal': 'true', 'aria-labelledby': titleId, tabindex: '-1',
+  }, [head, body, bar]);
+
+  const root = el('div', {
+    class: 'ag-root ag-modal',
+    on: {
+      mousedown: function (ev) { if (dismissible && ev.target === root) api.close(); },
+      keydown: onKey,
+    },
+  }, dialog);
+
+  document.body.appendChild(root);
+  dialog.focus();
+
+  /** @param {KeyboardEvent} ev */
+  function onKey(ev) {
+    if (ev.key === 'Escape' && dismissible) { ev.preventDefault(); api.close(); return; }
+    if (ev.key !== 'Tab') return;
+    const items = /** @type {HTMLElement[]} */ (Array.prototype.slice.call(dialog.querySelectorAll(FOCUSABLE)))
+      .filter(function (n) { return !(/** @type {HTMLButtonElement} */ (n).disabled); });
+    if (!items.length) return;
+    const first = items[0];
+    const last = items[items.length - 1];
+    if (ev.shiftKey && document.activeElement === first) { ev.preventDefault(); last.focus(); }
+    else if (!ev.shiftKey && document.activeElement === last) { ev.preventDefault(); first.focus(); }
+  }
+
+  /** @param {OverlayAction[]} actions */
+  function renderActions(actions) {
+    clear(bar);
+    for (const action of actions) {
+      const kind = action.kind || 'plain';
+      bar.appendChild(el('button', {
+        type: 'button',
+        class: 'ag-btn' + (kind === 'plain' ? '' : ' ag-btn--' + kind),
+        'data-ag-id': action.id,
+        on: { click: function () { if (action.onClick) action.onClick(action); } },
+      }, action.label));
+    }
+  }
+
+  renderActions(spec.actions || []);
+
+  const api = {
+    el: root,
+    body: body,
+
+    /** @param {{ title?: string, body?: any, actions?: OverlayAction[] }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.title != null) heading.textContent = patch.title;
+      if (patch.body !== undefined) { clear(body); append(body, patch.body); }
+      if (patch.actions) renderActions(patch.actions);
+    },
+
+    close() {
+      api.destroy();
+      if (spec.onClose) spec.onClose();
+    },
+
+    destroy() {
+      if (root.parentNode) root.parentNode.removeChild(root);
+      if (returnTo && typeof returnTo.focus === 'function') returnTo.focus();
+    },
+  };
+
+  return api;
+}
+
+/** The lazily created stack every toast lands in. @returns {HTMLElement} */
+function toastHost() {
+  let host = document.getElementById('ag-toasts');
+  if (!host) {
+    host = el('div', { class: 'ag-root ag-toasts', id: 'ag-toasts', role: 'status', 'aria-live': 'polite' });
+    document.body.appendChild(host);
+  }
+  return /** @type {HTMLElement} */ (host);
+}
+
+/**
+ * Transient feedback.
+ * @param {string} msg
+ * @param {'info'|'ok'|'warn'|'err'} [kind]
+ * @param {{ ms?: number }} [opts]  Time on screen (default 3200ms; 0 keeps it until closed).
+ * @returns {{ el: HTMLElement, close: () => void }}
+ */
+export function toast(msg, kind, opts) {
+  const k = kind || 'info';
+  const node = el('div', { class: 'ag-toast ag-toast--' + k }, [
+    el('span', { class: 'ag-toast__mark', text: TOAST_MARK[k] || 'i', 'aria-hidden': 'true' }),
+    el('span', { text: msg }),
+  ]);
+  toastHost().appendChild(node);
+  const close = function () { if (node.parentNode) node.parentNode.removeChild(node); };
+  const ms = opts && opts.ms != null ? opts.ms : 3200;
+  if (ms > 0) setTimeout(close, ms);
+  return { el: node, close: close };
+}
+
+/**
+ * Ask before something irreversible. Resolves true on confirm, false on cancel/dismiss.
+ * @param {{
+ *   title: string, body?: any, confirmLabel?: string, cancelLabel?: string, danger?: boolean
+ * }} spec
+ * @returns {Promise<boolean>}
+ */
+export function confirm(spec) {
+  return new Promise(function (resolveWith) {
+    let settled = false;
+    /** @param {boolean} answer */
+    const finish = function (answer) {
+      if (settled) return;
+      settled = true;
+      resolveWith(answer);
+    };
+    const dialog = modal({
+      title: spec.title,
+      body: spec.body,
+      onClose: function () { finish(false); },
+      actions: [
+        {
+          id: 'cancel', label: spec.cancelLabel || t('cancel'), kind: 'ghost',
+          onClick: function () { finish(false); dialog.destroy(); },
+        },
+        {
+          id: 'confirm', label: spec.confirmLabel || t('confirm'), kind: spec.danger ? 'danger' : 'primary',
+          onClick: function () { finish(true); dialog.destroy(); },
+        },
+      ],
+    });
+  });
+}

package/dist/static/sdk-libs/game/progress.js

@@ -0,0 +1,280 @@
+/**
+ * @file game/progress.js
+ * @description Progression components: the step rail, the labelled meter, the counting number and
+ *   the streak tracker. Each takes a spec, returns a handle with `set()` / `destroy()`, and holds
+ *   no state of its own beyond what it was last told.
+ *
+ *   ONE SIZING EVERYWHERE. The rail and the meter read their size from the theming contract
+ *   (`--ag-rail-dot`, `--ag-meter-h`), never from the spec — so two rails on one page always
+ *   match, and a skin can make every rail in an app denser in one line.
+ *
+ *   REDUCED MOTION. The counter checks the viewer's preference and lands on the final value
+ *   immediately; the CSS transitions collapse for the same reason. An animation is a nicety, and
+ *   a nicety that ignores an accessibility preference is a defect.
+ * @structure rail(spec) · meter(spec) · counter(spec) · streak(spec)
+ * @usage  const m = AIMEAT.game.meter({ label: 'Readiness', value: 62, threshold: 70 });
+ *         m.set({ value: 71 });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear, reducedMotion } from './dom.js';
+import { t, i18n } from './i18n.js';
+
+/** Clamp to the 0..100 the meter and the rail both speak. */
+function pct(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(100, v));
+}
+
+/**
+ * @typedef {object} RailStep
+ * @property {string} id
+ * @property {string} label
+ * @property {'future'|'current'|'done'} [state]
+ */
+
+/**
+ * A horizontal step rail: where the player is, what is behind them, what is left.
+ * @param {RailStep[]|{ steps: RailStep[], onPick?: (step: RailStep, index: number) => void }} spec
+ * @returns {{ el: HTMLElement, set: (steps: RailStep[]) => void, destroy: () => void }}
+ */
+export function rail(spec) {
+  const cfg = Array.isArray(spec) ? { steps: spec } : (spec || { steps: [] });
+  let steps = cfg.steps || [];
+  const root = el('div', { class: 'ag-root ag-rail', role: 'list' });
+
+  function render() {
+    clear(root);
+    steps.forEach(function (step, i) {
+      const st = step.state || 'future';
+      const mark = st === 'done' ? '✓' : String(i + 1);
+      const kids = [
+        el('span', { class: 'ag-rail__dot', 'aria-hidden': 'true', text: mark }),
+        el('span', { class: 'ag-rail__name', text: step.label }),
+      ];
+      const attrs = {
+        class: 'ag-rail__step ag-rail__step--' + st,
+        role: 'listitem',
+        'data-ag-id': step.id,
+        'aria-current': st === 'current' ? 'step' : null,
+        'aria-label': step.label + ' — ' + t(st === 'done' ? 'done' : st === 'current' ? 'now' : 'later'),
+      };
+      if (cfg.onPick) {
+        root.appendChild(el('button', Object.assign({ type: 'button' }, attrs, {
+          on: { click: function () { if (cfg.onPick) cfg.onPick(step, i); } },
+        }), kids));
+      } else {
+        root.appendChild(el('div', attrs, kids));
+      }
+    });
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {RailStep[]} next */
+    set(next) { if (next) steps = next; render(); },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}
+
+/**
+ * A labelled 0..100 meter with an optional threshold marker ("you need 70 to list this").
+ * @param {{
+ *   label: string, value: number, threshold?: number, hint?: string,
+ *   tone?: 'accent'|'ok'|'warn'|'err', suffix?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function meter(spec) {
+  const state = {
+    label: spec.label,
+    value: pct(spec.value),
+    threshold: spec.threshold,
+    hint: spec.hint,
+    tone: spec.tone || 'accent',
+    suffix: spec.suffix != null ? spec.suffix : '%',
+  };
+
+  const name = el('span', { class: 'ag-label' });
+  const value = el('span', { class: 'ag-meter__value ag-num' });
+  const top = el('div', { class: 'ag-meter__top' }, [name, value]);
+  const fill = el('div', { class: 'ag-meter__fill' });
+  const track = el('div', {
+    class: 'ag-meter__track', role: 'progressbar',
+    'aria-valuemin': '0', 'aria-valuemax': '100',
+  }, fill);
+  const hint = el('p', { class: 'ag-meter__hint' });
+  const root = el('div', { class: 'ag-root ag-meter' }, [top, track, hint]);
+
+  function render() {
+    root.className = 'ag-root ag-meter ag-meter--' + state.tone;
+    name.textContent = state.label;
+    value.textContent = Math.round(state.value) + state.suffix;
+    // The percentage is data: it goes in as a custom property the stylesheet consumes.
+    fill.style.setProperty('--ag-fill', state.value + '%');
+    track.setAttribute('aria-valuenow', String(Math.round(state.value)));
+    track.setAttribute('aria-label', state.label);
+
+    const existing = track.querySelector('.ag-meter__mark');
+    if (existing) track.removeChild(existing);
+    if (state.threshold != null) {
+      track.appendChild(el('div', {
+        class: 'ag-meter__mark', 'aria-hidden': 'true',
+        vars: { '--ag-at': pct(state.threshold) + '%' },
+      }));
+    }
+
+    const text = state.hint || (state.threshold != null ? t('target', { n: Math.round(pct(state.threshold)) + state.suffix }) : '');
+    hint.textContent = text;
+    hint.hidden = !text;
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ value?: number, label?: string, threshold?: number, hint?: string, tone?: 'accent'|'ok'|'warn'|'err' }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.value != null) state.value = pct(patch.value);
+      if (patch.label != null) state.label = patch.label;
+      if (patch.threshold !== undefined) state.threshold = patch.threshold;
+      if (patch.hint !== undefined) state.hint = patch.hint;
+      if (patch.tone) state.tone = patch.tone;
+      render();
+    },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}
+
+/**
+ * A large number that counts to its target — and simply IS its target when the viewer prefers
+ * reduced motion.
+ * @param {{
+ *   value: number, label?: string, from?: number, durationMs?: number,
+ *   format?: (n: number) => string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (value: number|{ value?: number, label?: string }) => void, destroy: () => void }}
+ */
+export function counter(spec) {
+  const format = spec.format || function (n) { return String(Math.round(n)); };
+  const duration = spec.durationMs || 900;
+  let shown = spec.from != null ? spec.from : 0;
+  let target = Number(spec.value) || 0;
+  let frame = 0;
+
+  const num = el('span', { class: 'ag-counter__n ag-num' });
+  const label = el('span', { class: 'ag-label' });
+  const root = el('div', { class: 'ag-root ag-counter' }, [num, label]);
+
+  function paintLabel() {
+    label.textContent = spec.label || '';
+    label.hidden = !spec.label;
+  }
+
+  /** @param {number} to */
+  function animate(to) {
+    if (frame) cancelAnimationFrame(frame);
+    if (reducedMotion() || duration <= 0) {
+      shown = to;
+      num.textContent = format(shown);
+      return;
+    }
+    const from = shown;
+    const started = performance.now();
+    const step = function (now) {
+      const p = Math.min(1, (now - started) / duration);
+      const eased = 1 - Math.pow(1 - p, 3);
+      shown = from + (to - from) * eased;
+      num.textContent = format(shown);
+      if (p < 1) frame = requestAnimationFrame(step);
+      else { frame = 0; shown = to; num.textContent = format(shown); }
+    };
+    frame = requestAnimationFrame(step);
+  }
+
+  paintLabel();
+  num.textContent = format(shown);
+  animate(target);
+
+  return {
+    el: root,
+    /** @param {number|{ value?: number, label?: string }} next */
+    set(next) {
+      if (typeof next === 'number') { target = next; animate(target); return; }
+      if (!next) return;
+      if (next.label !== undefined) { spec.label = next.label; paintLabel(); }
+      if (next.value != null) { target = next.value; animate(target); }
+    },
+    destroy() {
+      if (frame) cancelAnimationFrame(frame);
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+}
+
+/**
+ * A consecutive-period tracker — for any app whose loop is a habit. The period is the caller's
+ * word ("day", "week", "session"), never the component's.
+ * @param {{
+ *   count: number, periods?: Array<{ label: string, done: boolean }>, best?: number,
+ *   unitLabel?: string
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function streak(spec) {
+  const state = {
+    count: Number(spec.count) || 0,
+    periods: spec.periods || [],
+    best: spec.best,
+    unitLabel: spec.unitLabel,
+  };
+
+  const count = el('span', { class: 'ag-streak__count ag-num' });
+  const unit = el('span', { class: 'ag-label' });
+  const best = el('span', { class: 'ag-dim' });
+  const top = el('div', { class: 'ag-streak__top' }, [count, unit, best]);
+  const cells = el('div', { class: 'ag-streak__cells' });
+  const root = el('div', { class: 'ag-root ag-streak' }, [top, cells]);
+
+  function render() {
+    count.textContent = t('inARow', { n: state.count });
+    unit.textContent = state.unitLabel || '';
+    unit.hidden = !state.unitLabel;
+    best.textContent = state.best != null ? t('best', { n: state.best }) : '';
+    best.hidden = state.best == null;
+
+    clear(cells);
+    for (const p of state.periods) {
+      cells.appendChild(el('div', {
+        class: 'ag-streak__cell' + (p.done ? ' ag-streak__cell--done' : ''),
+        title: p.label,
+      }, [
+        el('span', { class: 'ag-streak__box', 'aria-hidden': 'true', text: p.done ? '✓' : '' }),
+        el('span', { class: 'ag-streak__tick', text: p.label }),
+      ]));
+    }
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ count?: number, periods?: any[], best?: number, unitLabel?: string }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.count != null) state.count = patch.count;
+      if (patch.periods) state.periods = patch.periods;
+      if (patch.best !== undefined) state.best = patch.best;
+      if (patch.unitLabel !== undefined) state.unitLabel = patch.unitLabel;
+      render();
+    },
+    destroy() { stopLang(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}

package/dist/static/sdk-libs/game/score.js

@@ -0,0 +1,134 @@
+/**
+ * @file game/score.js
+ * @description The score breakdown — the component this kit exists for. A score shown as one
+ *   number tells a player they are losing; a score shown as its PARTS tells them what to do next.
+ *   Each row is a category with its points, its maximum and a one-line reason, and every row is a
+ *   button that reports which part was picked, so the host can jump straight to fixing it.
+ *
+ *   That is the whole trick that makes any scored experience playable: the number becomes a
+ *   to-do list. A quiz uses it for topics missed, an onboarding for steps skipped, a training
+ *   tracker for muscle groups, a business simulation for the parts of a listing that are thin.
+ *
+ *   The row colour is derived, never passed: full marks read as done, partial as in progress,
+ *   zero as untouched. A host that wants a different reading passes `tone` explicitly.
+ * @structure scoreBreakdown(spec) → handle { el, set, destroy }
+ * @usage  AIMEAT.game.scoreBreakdown({ rows, onPick(row) { openFix(row.id); } });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear } from './dom.js';
+import { t, i18n } from './i18n.js';
+import { meter } from './progress.js';
+
+/**
+ * @typedef {object} ScoreRow
+ * @property {string} id
+ * @property {string} label
+ * @property {number} points
+ * @property {number} max
+ * @property {string} [reason]   One line: why these points, or what is missing.
+ * @property {'full'|'part'|'zero'} [tone]
+ */
+
+/**
+ * A score, broken into the parts a player can act on.
+ * @param {{
+ *   title?: string, rows: ScoreRow[], onPick?: (row: ScoreRow) => void,
+ *   total?: { points: number, max: number }, totalLabel?: string, showTotal?: boolean,
+ *   threshold?: number
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, destroy: () => void }}
+ */
+export function scoreBreakdown(spec) {
+  const state = {
+    title: spec.title,
+    rows: spec.rows || [],
+    total: spec.total,
+    threshold: spec.threshold,
+  };
+
+  const big = el('span', { class: 'ag-score__big ag-num' });
+  const bar = meter({
+    label: spec.totalLabel || t('total'),
+    value: 0,
+    threshold: spec.threshold,
+  });
+  const totalBox = el('div', { class: 'ag-score__total' }, [big, bar.el]);
+  const rows = el('div', { class: 'ag-score__rows' });
+  const heading = el('h3', { class: 'ag-title' });
+  const root = el('div', { class: 'ag-root ag-score' }, [heading, totalBox, rows]);
+
+  /** The summed total, unless the host gave one. */
+  function totals() {
+    if (state.total) return state.total;
+    let points = 0;
+    let max = 0;
+    for (const r of state.rows) { points += Number(r.points) || 0; max += Number(r.max) || 0; }
+    return { points: points, max: max };
+  }
+
+  /** @param {ScoreRow} row @returns {string} */
+  function toneOf(row) {
+    if (row.tone) return row.tone;
+    const p = Number(row.points) || 0;
+    const m = Number(row.max) || 0;
+    if (m > 0 && p >= m) return 'full';
+    return p > 0 ? 'part' : 'zero';
+  }
+
+  function render() {
+    heading.textContent = state.title || '';
+    heading.hidden = !state.title;
+
+    const sum = totals();
+    const share = sum.max > 0 ? (sum.points / sum.max) * 100 : 0;
+    big.textContent = String(Math.round(sum.points));
+    bar.set({
+      value: share,
+      label: (spec.totalLabel || t('total')) + ' · ' + t('points', { a: Math.round(sum.points), b: Math.round(sum.max) }),
+    });
+    totalBox.hidden = spec.showTotal === false;
+
+    clear(rows);
+    if (!state.rows.length) {
+      rows.appendChild(el('p', { class: 'ag-empty', text: t('empty') }));
+      return;
+    }
+    for (const row of state.rows) {
+      const tone = toneOf(row);
+      rows.appendChild(el('button', {
+        type: 'button',
+        class: 'ag-score__row ag-score__row--' + tone,
+        'data-ag-id': row.id,
+        'aria-label': row.label + ' — ' + t('points', { a: row.points, b: row.max }),
+        on: { click: function () { if (spec.onPick) spec.onPick(row); } },
+      }, [
+        el('span', {}, [
+          el('span', { class: 'ag-score__name', text: row.label }),
+          row.reason ? el('span', { class: 'ag-score__why', text: row.reason }) : null,
+        ]),
+        el('span', { class: 'ag-score__pts' }, [
+          el('span', { text: t('points', { a: row.points, b: row.max }) }),
+          el('span', { class: 'ag-score__go', text: '→', 'aria-hidden': 'true' }),
+        ]),
+      ]));
+    }
+  }
+
+  const stopLang = i18n.onChange(render);
+  render();
+
+  return {
+    el: root,
+    /** @param {{ rows?: ScoreRow[], total?: any, title?: string, threshold?: number }} patch */
+    set(patch) {
+      if (!patch) return;
+      if (patch.rows) state.rows = patch.rows;
+      if (patch.total !== undefined) state.total = patch.total;
+      if (patch.title !== undefined) state.title = patch.title;
+      if (patch.threshold !== undefined) { state.threshold = patch.threshold; bar.set({ threshold: patch.threshold }); }
+      render();
+    },
+    destroy() { stopLang(); bar.destroy(); if (root.parentNode) root.parentNode.removeChild(root); },
+  };
+}