@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/panel-widgets.js

@@ -0,0 +1,294 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Builds a menu row: a short label, a hint that goes to the footer, and a control.
+ *
+ * The row is NOT inserted anywhere — whoever mounts it decides the order, which in this project's menus is part of the
+ * decision (ADR-0044 §2).
+ */
+export function controlRow(ctx, spec) {
+    const rowNode = ctx.create('div');
+    rowNode.className = 'ctrl-row';
+    const text = ctx.create('span');
+    const shortLabel = ctx.create('strong');
+    shortLabel.textContent = spec.label;
+    text.appendChild(shortLabel);
+    if (spec.hint) {
+        // ⚠️ ONLY ONE, and it is what `fillExplain` looks for. Two `.opt-hint`s on one row would give the control two
+        // descriptions, and the footer would show the first — the other would stay on the row, exactly the defect rule §4
+        // exists to prevent.
+        const explanation = ctx.create('span');
+        explanation.className = 'opt-hint';
+        explanation.textContent = spec.hint;
+        text.appendChild(explanation);
+    }
+    rowNode.appendChild(text);
+    const control = buildControl(ctx, spec);
+    control.id = spec.id;
+    control.setAttribute('aria-label', spec.ariaLabel ?? spec.label);
+    rowNode.appendChild(control);
+    return { row: rowNode, control: control };
+}
+/**
+ * REWRITES THE WORDS OF A ROW THAT ALREADY EXISTS — the counterpart of `ui/panel-shell.applyLabels`, one level down.
+ *
+ * 🔴 The inside of a panel is mounted once, and anything mounted at boot captures the fallback language's text:
+ * `initI18n` applies the fallback synchronously and REQUESTS the preferred one, which arrives later — a panel would serve
+ * its TITLE in one language and its ROWS in another, on the same screen.
+ *
+ * ⚠️ AND NO UNIT TEST CATCHES IT, because they all run in a single language.
+ *
+ * ⚠️ REWRITE AND NOT REBUILD, for the reason `applyLabels` already states: each `ui/settings-*` wires its controls'
+ * clicks ONCE, at boot. Remaking the row would leave a control in the document with no listener — a dead button that
+ * looks alive (ADR-0106 §5).
+ */
+export function labelRow(rowNode, spec) {
+    const shortLabel = rowNode.querySelector('strong');
+    if (shortLabel)
+        shortLabel.textContent = spec.label;
+    const explanation = rowNode.querySelector('.opt-hint');
+    // ⚠️ A hint that DISAPPEARS has to be erased, not just left unwritten: on a retranslation into a dictionary without
+    // the key, the old text would survive and the footer would rest in the previous language.
+    if (explanation)
+        explanation.textContent = spec.hint ?? '';
+    // The control is found by COMPARING its id, not by building a selector from it: a selector needs the id escaped, escaping
+    // needs `CSS.escape`, and `CSS` is a browser global that THROWS where it does not exist — it took down a boot in a case's fake
+    // document once (2026-09-21). No selector, nothing to escape, no global (ADR-0221 step 7d).
+    const control = [...rowNode.querySelectorAll('[id]')].find((el) => el.id === spec.id);
+    if (control)
+        control.setAttribute('aria-label', spec.ariaLabel ?? spec.label);
+}
+function buildControl(ctx, spec) {
+    const controlShape = spec.shape ?? 'interruptor';
+    if (controlShape === 'escolha') {
+        const s = ctx.create('select');
+        s.className = 'vol';
+        return s;
+    }
+    if (controlShape === 'cursor') {
+        const i = ctx.create('input');
+        i.className = 'vol';
+        i.setAttribute('type', 'range');
+        // The volume slider's bounds, the same the audio panel reads: 0..100 in steps of 1, converted to the project's
+        // 0..1 volume by the panel.
+        i.setAttribute('min', '0');
+        i.setAttribute('max', '100');
+        i.setAttribute('step', '1');
+        return i;
+    }
+    if (controlShape === 'button') {
+        /*
+         * 🎯 THE ONE SHAPE THAT HOLDS NO VALUE: the others answer "which position am I in", this one DOES something.
+         * `ui/settings-controls` demands it — its button opens the capture of a key.
+         *
+         * 📌 No `aria-pressed` and no `role`: a button that acts already IS a button to whoever listens, and an announced
+         * state that does not exist is worse than no state. The panel puts the FACE on it — for remapping, the current
+         * keys —, because only the panel knows what the button shows.
+         */
+        const a = ctx.create('button');
+        a.className = 'mode-btn';
+        a.setAttribute('type', 'button');
+        return a;
+    }
+    if (controlShape === 'radio') {
+        /*
+         * 🔴 A CHOICE IS NOT A SWITCH, and the difference is what the ADR-0012 amendment says in so many words: «THE MENU IS
+         * A CHOICE, NOT A TOGGLE […] One font is active; the others are alternatives, not switches.» Hence three
+         * differences: no `switch` class (which draws a 52×28 px knob, the drawing of a state that does not exist),
+         * `role="radio"`, and `aria-checked` instead of `aria-pressed` — independent switches would announce on/off to
+         * choose ONE thing.
+         *
+         * 📌 `ui/settings-typo` demands it. The panel, not the kit, groups the `role="radio"`s in a `role="radiogroup"`,
+         * because the panel knows whether exclusivity covers a section or the whole menu.
+         */
+        const r = ctx.create('button');
+        r.className = 'mode-btn';
+        r.setAttribute('type', 'button');
+        r.setAttribute('role', 'radio');
+        r.setAttribute('aria-checked', 'false');
+        return r;
+    }
+    const b = ctx.create('button');
+    // `switch` is the class this project's CSS gives switches, and `aria-pressed` is what tells the state to whoever
+    // listens. The panel reflects the value; what is born here is the HONEST state of something that has read nothing
+    // yet: off.
+    b.className = 'mode-btn switch';
+    b.setAttribute('type', 'button');
+    b.setAttribute('aria-pressed', 'false');
+    return b;
+}
+/* ===================== THE SECTION HEADER — whose turn it is to act ===================== */
+/**
+ * The header of a panel section: a title and a tag that qualifies it.
+ *
+ * 📏 It is in the kit because several panels wrote it by hand, with the `.panel-sub__tag` markup copied into each — the
+ * same reason as `controlRow`: a rule repeated across files is a rule that drifts.
+ *
+ * ⚠️ AND IT REFUSES TO EXIST OVER NOTHING, which is the behaviour that makes it worth a function. An "awaiting
+ * negotiation" heading with no row under it tells the reader something is there when nothing is, and the person looks
+ * for what the title promises. `rows` is the NUMBER of rows the section will have — passing it is what makes this rule
+ * exercisable by a case, instead of an `if` no fixed tree reaches.
+ *
+ * 📌 The title and tag arrive ALREADY TRANSLATED, as in `controlRow`: the kit does not decide language, it builds shape.
+ */
+export function sectionHeader(ctx, title, tag, rows) {
+    if (rows === 0)
+        return null;
+    const h = ctx.create('h3');
+    h.className = 'panel-sub';
+    h.textContent = title + ' ';
+    const mark = ctx.create('span');
+    mark.className = 'panel-sub__tag';
+    mark.textContent = tag;
+    h.appendChild(mark);
+    return h;
+}
+/**
+ * The next step, CLAMPED at the ends — not a ring, and the difference is the decision.
+ *
+ * ⚠️ In a ring, right from the largest position would return to off: whoever adjusts looking for the maximum would pass
+ * it without warning and switch off what they wanted to raise. Clamped, the end is a wall you feel — the number of
+ * players, the model the Dev gave, does not wrap either.
+ */
+export function nextStep(from, total, delta) {
+    if (total <= 0)
+        return 0;
+    return Math.max(0, Math.min(total - 1, from + Math.sign(delta)));
+}
+/**
+ * Builds the control: ONE focusable element (`role="spinbutton"`) with the two arrows inside.
+ *
+ * ⚠️ THE ARROWS ARE NOT BUTTONS, on purpose: menu navigation treats every `button` as an item, and three items for one
+ * adjustment would make the cursor stop twice on nameless arrows. Focus belongs to the control; the arrows are FINGER
+ * targets (`data-passo`), outside the accessibility tree — whoever listens gets the `aria-valuetext`.
+ *
+ * The control emits `passo` (`CustomEvent<number>`, -1 or +1): a tapped arrow emits it from here, and the keyboard's and
+ * controller's left and right emit it through `ui/menu-nav`. The user listens to a single event.
+ */
+export function mountSteps(ctx, spec) {
+    const el = ctx.create('div');
+    el.className = 'passos';
+    el.setAttribute('role', 'spinbutton');
+    el.setAttribute('tabindex', '0');
+    el.setAttribute('data-passos', '');
+    const arrow = (delta, glyph) => {
+        const s = ctx.create('span');
+        s.className = 'passo-seta';
+        s.setAttribute('data-passo', String(delta));
+        s.setAttribute('aria-hidden', 'true');
+        s.textContent = glyph;
+        s.addEventListener('click', () => el.dispatchEvent(new CustomEvent('passo', { detail: delta, bubbles: true })));
+        return s;
+    };
+    const value = ctx.create('span');
+    value.className = 'passo-valor';
+    el.appendChild(arrow(-1, '◀'));
+    el.appendChild(value);
+    el.appendChild(arrow(1, '▶'));
+    updateSteps(el, spec);
+    return el;
+}
+/* ===================== ONE EXCLUSIVE CHOICE, DRAWN BY ITS SIZE (ADR-0130 rule 3 and erratum) ===================== */
+/**
+ * How many positions still CYCLE. The Dev's number (ADR-0130 erratum, 2026-09-12): «Acima de cinco itens deve ser dropdown».
+ * Five or fewer are one row «◀ Label: value ▶» — every position is one step away and the row always says where it is;
+ * more than five, a dropdown, because a cycle that long is walked more than it is chosen.
+ */
+export const MAX_CYCLE_POSITIONS = 5;
+/**
+ * Builds the control for ONE EXCLUSIVE CHOICE, and its SIZE picks the control, not the panel's author (ADR-0130 rule 3):
+ * up to `MAX_CYCLE_POSITIONS` a steps control (`mountSteps`), more a `<select>`. A choice whose size depends on the moment —
+ * the game's named positions, the audio outputs plugged in — takes the control its size asks for NOW, drawn again when it
+ * changes.
+ *
+ * Both shapes answer the same way, so whoever builds a row does not branch: `pick(value)` runs when the child chooses, the
+ * value in use is in `data-value`, and a bubbling `change` follows the pick — a list that listens for `change` hears either.
+ * A value not among the positions shows the first, as a `<select>` does.
+ */
+export function mountChoice(ctx, spec, pick) {
+    if (spec.values.length <= MAX_CYCLE_POSITIONS) {
+        const steps = mountSteps(ctx, stepsOf(spec));
+        writeCycle(steps, spec);
+        steps.addEventListener('passo', (ev) => {
+            // read back from the element, never from this closure: an `updateChoice` since may have brought other words
+            const live = readCycle(steps);
+            const from = indexOfValue(live);
+            const to = nextStep(from, live.values.length, ev.detail);
+            if (to === from)
+                return; // at the wall nothing moved, and nothing is picked
+            const value = live.values[to].value;
+            writeCycle(steps, { ...live, current: value });
+            pick(value);
+            steps.dispatchEvent(new Event('change', { bubbles: true }));
+        });
+        return steps;
+    }
+    const list = ctx.create('select');
+    list.className = 'vol';
+    fillList(list, spec);
+    list.addEventListener('change', () => { list.dataset.value = list.value; pick(list.value); });
+    return list;
+}
+/** Where the current value sits among the positions; one not among them shows the first, as a `<select>` does. */
+const indexOfValue = (s) => Math.max(0, s.values.findIndex((v) => v.value === s.current));
+const stepsOf = (s) => ({ label: s.label, values: s.values.map((v) => v.label), current: indexOfValue(s) });
+/**
+ * A cycle row keeps its whole choice ON THE ELEMENT — the positions in `data-positions`, the value in `data-value`, the
+ * name in `aria-label` — so the control carries no state of its own that a redraw could leave behind.
+ */
+function writeCycle(el, s) {
+    el.dataset.positions = JSON.stringify(s.values);
+    el.dataset.value = s.current;
+    updateSteps(el, stepsOf(s));
+}
+function readCycle(el) {
+    return {
+        label: el.getAttribute('aria-label') ?? '',
+        values: JSON.parse(el.dataset.positions ?? '[]'),
+        current: el.dataset.value ?? '',
+    };
+}
+function fillList(list, s) {
+    // a `<select>` whose label is a sibling is announced as «combo box» and nothing else without its own name
+    list.setAttribute('aria-label', s.label);
+    while (list.firstChild)
+        list.removeChild(list.firstChild);
+    for (const v of s.values) {
+        const option = list.ownerDocument.createElement('option');
+        option.value = v.value;
+        option.textContent = v.label; // text, never markup: a game's word goes through here
+        list.appendChild(option);
+    }
+    list.value = s.current;
+    list.dataset.value = list.value;
+}
+/**
+ * REWRITES a choice built by `mountChoice`: its name, its positions' words and the value in use — the redraw a panel does
+ * on every open, after a language change or when the value moved elsewhere. The SHAPE stays: a choice whose size can
+ * cross five is built again, not updated.
+ */
+export function updateChoice(el, spec) {
+    if (el.tagName === 'SELECT')
+        fillList(el, spec);
+    // read by the attribute `writeCycle` always writes, and not by `hasAttribute`: a host's minimal document may lack it
+    else if (el.dataset?.positions !== undefined)
+        writeCycle(el, spec);
+}
+/** Reflects the current position: the written value, what is heard, and the ends that no longer move. */
+export function updateSteps(el, spec) {
+    const lastIndex = Math.max(0, spec.values.length - 1);
+    const from = Math.max(0, Math.min(lastIndex, spec.current));
+    const text = spec.values[from] ?? '';
+    el.setAttribute('aria-label', spec.label);
+    el.setAttribute('aria-valuemin', '0');
+    el.setAttribute('aria-valuemax', String(lastIndex));
+    el.setAttribute('aria-valuenow', String(from));
+    el.setAttribute('aria-valuetext', text);
+    const value = el.querySelector('.passo-valor');
+    // THE LABEL GOES INTO THE TEXT: the whole row is the control, «◀ Cantos arredondados: pequeno ▶». Whoever listens gets
+    // the same in two parts — the name in `aria-label` and the position in `aria-valuetext` —, without the name repeated.
+    if (value)
+        value.textContent = spec.label ? `${spec.label}: ${text}` : text;
+    // The end that no longer moves is marked — otherwise a wall's arrow looks like a broken button.
+    el.querySelector('[data-passo="-1"]')?.classList.toggle('no-limite', from === 0);
+    el.querySelector('[data-passo="1"]')?.classList.toggle('no-limite', from === lastIndex);
+}

package/dist-pkg/ui/pause-buttons.d.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** One row of the per-screen pause menu. `letra` marks the label that ABC/abc rewrites live. */
+export interface PauseBtnDef {
+    readonly act: string;
+    /**
+     * RAW label, used only when the button has a dynamic label (`dynamicLabel`/`level`).
+     *
+     * Optional because `pmBtnMarkup` resolves every ordinary button through `t('pause.' + act)`, so text here would
+     * never reach a screen — it would be raw text inside an ENGINE module, waiting for someone to trust it. No entry
+     * today sets a dynamic label; the `pause.*` key is the source, and it exists in all three languages.
+     */
+    readonly lbl?: string;
+    readonly dynamicLabel?: boolean;
+    readonly level?: boolean;
+}
+/** The pause menu's items — MENU DATA, so it lives with the other menu tables. The pause slice (ui/pause-icons)
+ *  receives it through its own ctx instead of re-declaring it; nobody owns two copies of a list of buttons. */
+export declare const PM_BTNS: readonly PauseBtnDef[];
+/**
+ * THE THIRD LIST: what belongs to THIS game (ADR-0146, ADR-0145).
+ *
+ * ⚠️ IT STARTS WITH THE BACK ITEM AND NOTHING ELSE, and the emptiness is the decision: the engine does not know what a
+ * game has of its own — the game declares it. A list the engine filled in would be the wheelchair in chess again.
+ *
+ * 📌 And that is why the door drops by itself: `rootThatActs` drops a door whose room is empty, and with this list
+ * reduced to `pmback` that is exactly the case of a game that declares nothing.
+ */
+export declare const PM_GAME_BTNS: readonly PauseBtnDef[];
+/**
+ * THE INCLUSION SETTINGS SUBMENU — the panels, in the order the Dev dictated (ADR-0151).
+ *
+ * The way out comes FIRST here too, for the same reason `resume` comes first there: ADR-0044's rule is about menus,
+ * not about one menu. A submenu you cannot leave is the same trap, one level down.
+ */
+export declare const PM_OPTIONS_BTNS: readonly PauseBtnDef[];

package/dist-pkg/ui/pause-buttons.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// ui/pause-buttons — the items of the pause card the engine mounts: root, the game's options and the inclusion settings.
+//
+// Menu data for `ui/pause-icons`. They lived in `ui/activities-menu`, the platformer's title menu, which left the engine
+// (ADR-0174, issue #171); the card is the engine's, so its buttons stay.
+/** The pause menu's items — MENU DATA, so it lives with the other menu tables. The pause slice (ui/pause-icons)
+ *  receives it through its own ctx instead of re-declaring it; nobody owns two copies of a list of buttons. */
+export const PM_BTNS = [
+    // ===================== THE ORDER IS THE DECISION (ADR-0044 §2) =====================
+    // A menu you cannot leave is a trap, and the trap costs most to whoever cannot see it. `resume` comes FIRST because
+    // that is what a pause is for. `quit` comes LAST because it is its least wanted outcome — and, since the list is a
+    // RING, one key UP from `resume` reaches it: far in reading order, near to the finger.
+    //
+    // The settings panels live in `PM_OPTIONS_BTNS`.
+    //
+    // 🔴 SIX (ADR-0151), and the number is MEASURED, not taste: at 640×360, the target screen, seven items fit exactly
+    // and more overflow, while the target ruler is already at its floor (ADR-0095: «tela menor mostra menos itens, não
+    // alvos menores»).
+    //
+    // 📌 The accessibility bar and the print view are reached through SELECT — «basta apertar SELECT que se tem a visão
+    // apropriada pra print», in the Dev's words. Their `act`s still exist and work for whoever passes a list of their own.
+    { act: 'resume' },
+    // Help — how to play comes SECOND: it is the first thing someone who paused without knowing how to play looks for.
+    { act: 'ajuda' },
+    // ⚠️ The `act` stays `addplayer` and the LABEL is the number of players (ADR-0147 §3): `ui/shell.ts` implements
+    // `pauseActs.addplayer`, and cases in `shell.browser.test.js` call it.
+    { act: 'addplayer' },
+    // Inclusion settings: what the child CARRIES between games (ADR-0146, named by ADR-0151).
+    { act: 'options' },
+    // Game options: what belongs to THIS game. The door drops by itself when the game declares nothing of its own.
+    { act: 'opcoesdojogo' },
+    { act: 'quit' },
+];
+/**
+ * THE THIRD LIST: what belongs to THIS game (ADR-0146, ADR-0145).
+ *
+ * ⚠️ IT STARTS WITH THE BACK ITEM AND NOTHING ELSE, and the emptiness is the decision: the engine does not know what a
+ * game has of its own — the game declares it. A list the engine filled in would be the wheelchair in chess again.
+ *
+ * 📌 And that is why the door drops by itself: `rootThatActs` drops a door whose room is empty, and with this list
+ * reduced to `pmback` that is exactly the case of a game that declares nothing.
+ */
+export const PM_GAME_BTNS = [
+    { act: 'pmback' },
+];
+/**
+ * THE INCLUSION SETTINGS SUBMENU — the panels, in the order the Dev dictated (ADR-0151).
+ *
+ * The way out comes FIRST here too, for the same reason `resume` comes first there: ADR-0044's rule is about menus,
+ * not about one menu. A submenu you cannot leave is the same trap, one level down.
+ */
+export const PM_OPTIONS_BTNS = [
+    // 📌 Not here, and each has somewhere to go (ADR-0151): letter case walks the communication cycle of the bar's
+    // eleventh button, and typography — «quem escolhe a tipografia é o jogo, o jogador escolhe suas fontes via o menu de
+    // acessibilidade rápida».
+    // 📏 AND THE NUMBER IS WHAT FITS at 640×360; the submenu has its own case in the 44 px gate, not only the root.
+    // ✅ The audio panel (music, ambience, interaction, earcons), separate from hearing accessibility, is listed because
+    // the panel it opens exists — a door to a panel that does not exist would be ADR-0106 §5's dead button.
+    { act: 'pmback' },
+    { act: 'empatia' },
+    { act: 'audio' },
+    { act: 'som' },
+    { act: 'motora' },
+    { act: 'visual' },
+    { act: 'anim' },
+];