aimeat 2.1.0 → 2.3.0

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

@@ -0,0 +1,260 @@
+/**
+ * @file game/menu.js
+ * @description The full-screen menu — the shell an app opens on. Entries carry a label, an
+ *   optional sublabel, a state (`available` / `locked` / `done`), an optional badge and, when
+ *   locked, a reason the viewer can read instead of guessing.
+ *
+ *   A LOCKED ENTRY IS NOT A DEAD BUTTON. It stays readable, says why it is locked, and still
+ *   reports the pick so the host can point the player at what unlocks it. That difference is the
+ *   whole reason this is a component rather than a list of divs.
+ *
+ *   NESTING replaces the list in place and leaves a back affordance (↩ and Escape), rather than
+ *   stacking overlays — which is what keeps it correct at 1280x460 and on a phone.
+ *
+ *   KEYBOARD: Up/Down/Home/End move, Enter/Space pick, Escape goes back one level and closes at
+ *   the root. Focus follows navigation but never moves on a `set()`, so a live update cannot
+ *   snatch the keyboard out of the player's hands.
+ * @structure menu(spec) → handle { el, set, open, close, path, destroy }
+ * @usage  const m = AIMEAT.game.menu({ title: 'Chapters', entries, onPick(e) {…} });
+ *         m.set({ entries: next });   // updates in place, keeps position and focus
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 01).
+ */
+import { el, clear, resolve, uid } from './dom.js';
+import { t, i18n } from './i18n.js';
+
+/**
+ * @typedef {object} MenuEntry
+ * @property {string} id
+ * @property {string} label
+ * @property {string} [sublabel]
+ * @property {'available'|'locked'|'done'} [state]
+ * @property {string} [badge]        Short marker shown on the right (a count, a level, a tag).
+ * @property {string} [lockReason]   Shown under a locked entry — say what unlocks it.
+ * @property {MenuEntry[]} [entries] Nested submenu.
+ */
+
+/**
+ * A full-screen menu.
+ * @param {{
+ *   target?: string|Element, full?: boolean, head?: boolean, title: string, subtitle?: string, entries: MenuEntry[],
+ *   onPick?: (entry: MenuEntry, path: string[]) => void,
+ *   onClose?: () => void, closeLabel?: string, open?: boolean
+ * }} spec
+ * @returns {{ el: HTMLElement, set: (patch: any) => void, open: () => void, close: () => void,
+ *   path: () => string[], destroy: () => void }}
+ */
+export function menu(spec) {
+  const state = {
+    title: spec.title,
+    subtitle: spec.subtitle,
+    entries: spec.entries || [],
+    /** @type {MenuEntry[]} the chain of opened submenus */
+    trail: [],
+  };
+  const titleId = uid('ag-menu-title');
+
+  const heading = el('h2', { class: 'ag-title', id: titleId });
+  const sub = el('p', { class: 'ag-menu__sub' });
+  const crumb = el('div', { class: 'ag-menu__crumb' });
+  const titles = el('div', { class: 'ag-menu__titles' }, [crumb, heading, sub]);
+  const closeBtn = el('button', {
+    type: 'button', class: 'ag-btn ag-btn--ghost',
+    on: { click: function () { api.close(); } },
+  }, spec.closeLabel || t('close'));
+  // `head: false` drops the title strip, for a host that already draws its own (a hub screen
+  // with a logo above the entries). The entries, the keyboard and the nesting are unchanged.
+  const head = spec.head === false ? null : el('div', { class: 'ag-menu__head' }, [titles, closeBtn]);
+  const list = el('div', {
+    class: 'ag-menu__list ag-scroll', role: 'menu', 'aria-labelledby': titleId,
+    on: { keydown: onKey },
+  });
+  // Full-screen by default; `full: false` fills the container it is mounted into instead, which is
+  // what a menu living inside a panel (or a documentation page) needs.
+  const full = spec.full !== false;
+  const root = el('div', {
+    class: 'ag-root ag-menu' + (full ? '' : ' ag-menu--inline') + (head ? '' : ' ag-menu--nohead'),
+    role: full ? 'dialog' : 'group',
+    'aria-modal': full ? 'true' : null,
+    'aria-labelledby': titleId,
+  }, head ? [head, list] : [list]);
+
+  const host = resolve(spec.target, document.body);
+  host.appendChild(root);
+
+  const stopLang = i18n.onChange(function () { render(false); });
+
+  /** The entries at the current depth. @returns {MenuEntry[]} */
+  function level() {
+    const last = state.trail[state.trail.length - 1];
+    return last ? (last.entries || []) : state.entries;
+  }
+
+  /** @returns {string[]} the ids of the opened submenus, outermost first */
+  function pathIds() {
+    return state.trail.map(function (e) { return e.id; });
+  }
+
+  /** @param {boolean} moveFocus */
+  function render(moveFocus) {
+    const depth = state.trail.length;
+    const here = state.trail[depth - 1];
+    heading.textContent = here ? here.label : state.title;
+    const subText = here ? (here.sublabel || '') : (state.subtitle || '');
+    sub.textContent = subText;
+    sub.hidden = !subText;
+
+    clear(crumb);
+    if (depth) {
+      crumb.appendChild(el('button', {
+        type: 'button', class: 'ag-btn ag-btn--ghost',
+        on: { click: back },
+      }, '↩ ' + t('back')));
+      crumb.appendChild(el('span', { class: 'ag-label', text: state.title }));
+    }
+
+    clear(list);
+    // With no head there is no crumb to go back from, so the way out becomes the first entry.
+    // Escape works either way, but a pointer user must never be stranded in a submenu.
+    if (!head && depth) {
+      list.appendChild(el('div', {
+        class: 'ag-menu__item ag-menu__item--back', role: 'menuitem', tabindex: '0',
+        on: { click: back },
+      }, el('div', { class: 'ag-menu__inner' }, el('span', {}, el('span', { class: 'ag-menu__label', text: '↩ ' + t('back') })))));
+    }
+
+    const entries = level();
+    if (!entries.length) {
+      list.appendChild(el('p', { class: 'ag-empty', text: t('empty') }));
+      return;
+    }
+    for (const entry of entries) list.appendChild(item(entry));
+    if (moveFocus) {
+      const first = /** @type {HTMLElement|null} */ (list.querySelector('.ag-menu__item'));
+      if (first) first.focus();
+    }
+  }
+
+  /**
+   * @param {MenuEntry} entry
+   * @returns {HTMLElement}
+   */
+  function item(entry) {
+    const st = entry.state || 'available';
+    const locked = st === 'locked';
+    const nested = !!(entry.entries && entry.entries.length);
+    const marks = el('div', { class: 'ag-menu__marks' });
+    if (entry.badge) marks.appendChild(el('span', { class: 'ag-chip ag-chip--accent', text: entry.badge }));
+    if (st === 'done') marks.appendChild(el('span', { class: 'ag-chip ag-chip--ok', text: '✓ ' + t('done') }));
+    if (locked) marks.appendChild(el('span', { class: 'ag-chip', text: t('locked') }));
+    if (nested && !locked) marks.appendChild(el('span', { class: 'ag-menu__arrow', text: '→', 'aria-hidden': 'true' }));
+
+    const body = el('span', {}, [
+      el('span', { class: 'ag-menu__label', text: entry.label }),
+      entry.sublabel ? el('span', { class: 'ag-menu__sublabel', text: entry.sublabel }) : null,
+      locked && entry.lockReason ? el('span', { class: 'ag-menu__reason', text: entry.lockReason }) : null,
+    ]);
+
+    // NOT a <button>. A button's box refuses to grow with a nested multi-line child in Chrome,
+    // so a two-line entry spills over its own border at any display face the skin picks — which
+    // is exactly the kind of thing a library must not leave to the author to discover. A
+    // role=menuitem element sizes normally; Enter and Space are handled on the list.
+    return el('div', {
+      class: 'ag-menu__item' + (locked ? ' ag-menu__item--locked' : '') + (st === 'done' ? ' ag-menu__item--done' : ''),
+      role: 'menuitem',
+      tabindex: '0',
+      'data-ag-id': entry.id,
+      'aria-disabled': locked ? 'true' : null,
+      on: { click: function () { pick(entry); } },
+    }, el('div', { class: 'ag-menu__inner' }, [body, marks]));
+  }
+
+  /** @param {MenuEntry} entry */
+  function pick(entry) {
+    const path = pathIds();
+    if (spec.onPick) spec.onPick(entry, path);
+    if ((entry.state || 'available') === 'locked') return;
+    if (entry.entries && entry.entries.length) {
+      state.trail.push(entry);
+      render(true);
+    }
+  }
+
+  function back() {
+    if (!state.trail.length) return api.close();
+    state.trail.pop();
+    render(true);
+  }
+
+  /** @param {KeyboardEvent} ev */
+  function onKey(ev) {
+    if (ev.key === 'Escape') { ev.preventDefault(); back(); return; }
+    if (ev.key === 'Enter' || ev.key === ' ' || ev.key === 'Spacebar') {
+      const active = /** @type {HTMLElement|null} */ (document.activeElement);
+      if (active && active.classList.contains('ag-menu__item')) { ev.preventDefault(); active.click(); }
+      return;
+    }
+    const items = /** @type {HTMLElement[]} */ (Array.prototype.slice.call(list.querySelectorAll('.ag-menu__item')));
+    if (!items.length) return;
+    const at = items.indexOf(/** @type {HTMLElement} */ (document.activeElement));
+    let next = -1;
+    if (ev.key === 'ArrowDown' || ev.key === 'ArrowRight') next = at < 0 ? 0 : (at + 1) % items.length;
+    else if (ev.key === 'ArrowUp' || ev.key === 'ArrowLeft') next = at < 0 ? items.length - 1 : (at - 1 + items.length) % items.length;
+    else if (ev.key === 'Home') next = 0;
+    else if (ev.key === 'End') next = items.length - 1;
+    if (next < 0) return;
+    ev.preventDefault();
+    items[next].focus();
+  }
+
+  const api = {
+    el: root,
+
+    /**
+     * Update in place. Position and focus are kept — a live update never moves the player.
+     * @param {{ title?: string, subtitle?: string, entries?: MenuEntry[] }} patch
+     */
+    set(patch) {
+      if (!patch) return;
+      if (patch.title != null) state.title = patch.title;
+      if (patch.subtitle != null) state.subtitle = patch.subtitle;
+      if (patch.entries) {
+        state.entries = patch.entries;
+        // Re-resolve the open trail against the new data so a submenu survives its own update.
+        const ids = pathIds();
+        state.trail = [];
+        let scope = state.entries;
+        for (const id of ids) {
+          const found = scope.find(function (e) { return e.id === id; });
+          if (!found || !found.entries) break;
+          state.trail.push(found);
+          scope = found.entries;
+        }
+      }
+      render(false);
+    },
+
+    open() {
+      root.hidden = false;
+      render(true);
+    },
+
+    close() {
+      root.hidden = true;
+      if (spec.onClose) spec.onClose();
+    },
+
+    path() { return pathIds(); },
+
+    destroy() {
+      stopLang();
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+
+  root.hidden = spec.open === false;
+  // A full-screen menu takes focus on arrival, because it IS the screen. An inline one does not:
+  // stealing focus into a panel would scroll the host page out from under the reader.
+  render(full && spec.open !== false);
+  return api;
+}

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(); },
+        },
+      ],
+    });
+  });
+}