@the-inclusionist/engine 9.0.0 → 11.0.0

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

@@ -1,103 +1,129 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-// ui/panel-shell — A CASCA DE UM PAINEL DE AJUSTES, construída em vez de exigida.
+// ui/panel-shell — THE SHELL OF A SETTINGS PANEL, built instead of required.
 //
-// ========================= O ACHADO QUE ISTO CONSERTA =========================
-// O segundo consumidor (a etapa C da issue #63) mediu-o e escreveu-o no achado 6:
+// ========================= WHAT THIS FIXES =========================
+// A second consumer (issue #63) measured it: a panel's ctx asks for `$` and `store`, but what it REALLY requires is
+// that the consumer's document contain five ids (`#typo`, `#typo-list`, `#typo-close`, …). Nothing in the type says so;
+// it is found by trial, and the failure mode is the worst possible one — the panel opens EMPTY, with no error.
 //
-//     «O CONTRATO DE MARKUP É INVISÍVEL. O ctx do painel pede `$` e `store`; o que ele REALMENTE exige é que
-//      o documento do consumidor contenha `#typo`, `#typo-list`, `#typo-preview`, `#typo-close` e
-//      `#typo-reset`. Nada no tipo diz isso — descobre-se por tentativa, e o modo de falhar é o pior
-//      possível: o painel abre VAZIO, sem erro.»
+// Each `ui/settings-*.ts` fills the INSIDE of its panel; this module builds the OUTSIDE — the veil, the card, the title,
+// the actions row and the reset button — and returns the ids it created, so the contract is stated instead of
+// discovered.
 //
-// Cada `ui/settings-*.ts` preenche o INTERIOR do seu painel; o EXTERIOR — o véu, o cartão, o título, o
-// rodapé de ações e o botão de restaurar — vinha do `app/index.html`, que saiu com o cartucho (#111). Desde
-// então a engine EXIGE cinco ids por painel e não os declara em lado nenhum.
+// ⚠️ AND THE MENU RULE OF `CLAUDE.md` §4 IS BUILT IN, not remembered. A panel's introduction goes in the card's
+// `data-explain-idle` — never in a `<p>` of prose at the top —, because a menu that explains item by item makes the
+// child READ EVERYTHING to find what they want (issue #62). The shell has no way to receive a `<p>` at the top.
 //
-// ⚠️ E A REGRA DE MENU DO `CLAUDE.md` §4 DEPENDIA DE ALGUÉM SE LEMBRAR DELA. A introdução de um painel vai no
-// `data-explain-idle` do cartão — nunca num `<p>` de prosa no topo —, porque um menu que explica item a item
-// obriga a criança a LER TUDO para achar o que procura. A issue #62 mandava editar seis blocos de markup para
-// isso; o markup saiu, e a regra ficou sem alvo. Aqui ela deixa de ser lembrete e passa a ser construção: a
-// casca não tem por onde receber um `<p>` no topo.
-//
-// ========================= A FORMA, QUE FOI MEDIDA E NÃO INVENTADA =========================
-// É a do painel de tipografia do `app/quiz.html`, que é o único que sobrou e o que o segundo consumidor
-// exercitou de facto:
+// ========================= THE SHAPE =========================
 //
 //     <div id="X" class="overlay" hidden>
 //       <div class="overlay__card" role="dialog" aria-modal="true" aria-labelledby="X-title" [data-explain-idle]>
 //         <h2 id="X-title">…</h2>
-//         <div id="X-list" class="ctrl-list" role="group" aria-label="…"></div>   ← o interior, do settings-*
+//         <button id="X-close">…</button>                                           ← item 1 (ADR-0158)
+//         <div id="X-list" class="ctrl-list" role="group" aria-label="…"></div>   ← the inside, from settings-*
 //         <div class="overlay__actions">
-//           <button id="X-reset">…</button>  <button id="X-close">…</button>
+//           <button id="X-reset">…</button>
 //         </div>
 //       </div>
 //     </div>
 //
-// ⚠️ O RODAPÉ `.opt-explain` NÃO É CRIADO AQUI, e isso é deliberado: `ui/settings-panel.fillExplain` cria-o
-// quando move a primeira dica para lá. Criá-lo vazio aqui daria uma região `aria-live` que anuncia nada, e
-// duas mãos a criar o mesmo nó é como ele acabaria duplicado.
+// ⚠️ THE `.opt-explain` FOOTER IS NOT CREATED HERE, on purpose: `ui/settings-panel.fillExplain` creates it when it moves
+// the first hint there. Creating it empty here would give an `aria-live` region that announces nothing, and two hands
+// creating the same node is how it would end up duplicated.
 //
-// Sem `innerHTML`: tudo por `criar` + `textContent`, no molde de `ui/loop-crash` e `ui/focus-trap`. O título
-// e o rótulo da lista vêm do CHAMADOR já resolvidos — este módulo não traduz, para poder ser exercitado sem
-// dicionário.
+// No `innerHTML`: everything through `create` + `textContent`, like `ui/loop-crash` and `ui/focus-trap`. The title and
+// the list label come from the CALLER already resolved — this module does not translate, so it can be exercised with no
+// dictionary.
 //
-// ⚠️ E NÃO IMPORTA NADA. Uma casca que não usa `innerHTML` também não precisa de escapar texto: `textContent`
-// escapa por construção. Chegou a haver aqui um `escaparHtml` importado «por conveniência» — que é como um
-// módulo-folha deixa de o ser, e como um leitor futuro passa a procurar a interpolação que não existe.
-/** Os ids que um painel de `id` ocupa. Exportado porque um gate e um consumidor precisam de os nomear. */
-export function idsDaCasca(id) {
-    return { overlay: id, title: `${id}-title`, lista: `${id}-list`, reset: `${id}-reset`, fechar: `${id}-close` };
+// ⚠️ AND IT IMPORTS NOTHING. A shell that does not use `innerHTML` does not need to escape text either: `textContent`
+// escapes by construction. An import "for convenience" is how a leaf module stops being one, and how a future reader
+// starts looking for an interpolation that does not exist.
+/** The ids a panel of `id` occupies. Exported because a gate and a consumer need to name them. */
+export function shellIds(id, customListId) {
+    return {
+        overlay: id,
+        title: `${id}-title`,
+        list: customListId ?? `${id}-list`,
+        reset: `${id}-reset`,
+        close: `${id}-close`,
+    };
 }
 /**
- * Monta (ou reaproveita) a casca do painel `spec.id` e devolve as suas partes.
+ * Mounts (or reuses) the shell of panel `spec.id` and returns its parts.
  *
- * IDEMPOTENTE: se já existir um `#id`, ele é reutilizado e o conteúdo do cartão é reconstruído. Um painel que
- * a raiz monte duas vezes não pode acabar com dois véus — e a raiz monta mais do que uma vez, porque a
- * contagem de jogadores muda a grade de telas.
+ * IDEMPOTENT: if a `#id` already exists, it is reused and the card's content is rebuilt. A panel mounted twice cannot
+ * end up with two veils — and it can be mounted more than once (two cartridges on one page, ADR-0139).
  */
-export function montarCasca(ctx, spec) {
-    const ids = idsDaCasca(spec.id);
-    const overlay = ctx.procurar('#' + ids.overlay) ?? ctx.criar('div');
+export function mountShell(ctx, spec) {
+    const ids = shellIds(spec.id, spec.listId);
+    const overlay = ctx.find('#' + ids.overlay) ?? ctx.create('div');
     overlay.id = ids.overlay;
     overlay.className = 'overlay';
     overlay.hidden = true;
     while (overlay.firstChild)
         overlay.removeChild(overlay.firstChild);
-    const card = ctx.criar('div');
+    const card = ctx.create('div');
     card.className = 'overlay__card';
     card.setAttribute('role', 'dialog');
     card.setAttribute('aria-modal', 'true');
     card.setAttribute('aria-labelledby', ids.title);
-    // A introdução do painel é o texto de REPOUSO do rodapé (CLAUDE.md §4), nunca um `<p>` no topo.
-    if (spec.introducao)
-        card.setAttribute('data-explain-idle', spec.introducao);
-    const h2 = ctx.criar('h2');
+    const h2 = ctx.create('h2');
     h2.id = ids.title;
-    h2.textContent = spec.titulo;
     card.appendChild(h2);
-    const lista = ctx.criar('div');
-    lista.id = ids.lista;
-    lista.className = 'ctrl-list';
-    lista.setAttribute('role', 'group');
-    lista.setAttribute('aria-label', spec.rotuloDaLista);
-    card.appendChild(lista);
-    const acoes = ctx.criar('div');
-    acoes.className = 'overlay__actions';
-    const reset = botao(ctx, ids.reset, spec.rotuloReset, 'mode-btn');
-    const fechar = botao(ctx, ids.fechar, spec.rotuloFechar, 'mode-btn is-on');
-    acoes.appendChild(reset);
-    acoes.appendChild(fechar);
-    card.appendChild(acoes);
+    // ADR-0158: «Voltar» is item 1 and nothing closes the panel after its rows. The way out is where the cursor lands
+    // when the panel opens — a close button at the bottom made the child walk every row to leave. The id stays
+    // `#X-close`, which is contract; only its place and its word changed.
+    const backButton = button(ctx, ids.close, 'mode-btn overlay__back');
+    card.appendChild(backButton);
+    const listNode = ctx.create('div');
+    listNode.id = ids.list;
+    listNode.className = 'ctrl-list';
+    listNode.setAttribute('role', 'group');
+    card.appendChild(listNode);
+    const actionsRow = ctx.create('div');
+    actionsRow.className = 'overlay__actions';
+    const reset = button(ctx, ids.reset, 'mode-btn');
+    actionsRow.appendChild(reset);
+    card.appendChild(actionsRow);
     overlay.appendChild(card);
-    return { overlay, card, lista, reset, fechar, ids };
+    const shell = { overlay, card, title: h2, list: listNode, reset, close: backButton, ids };
+    applyLabels(shell, spec);
+    return shell;
+}
+/**
+ * WRITES THE SHELL'S WORDS — separate from construction because they change AFTER it exists.
+ *
+ * 🔴 `initI18n` applies the fallback language synchronously — so the page is never blank — and, if the preferred
+ * language is another, REQUESTS the switch, which is asynchronous. Anything JavaScript builds in that gap captures the
+ * fallback text and nothing rebuilds it; and the language can also change mid-game.
+ *
+ * ⚠️ AND REBUILDING THE SHELL TO FIX THE TITLE DOES NOT WORK. `mountShell` empties the card, and each `ui/settings-*`
+ * wires its `#X-reset` ONCE, at `init` — remounting leaves the reset button in the document with no listener, a dead
+ * button that looks alive (ADR-0106 §5). Writing only the words touches no listener.
+ *
+ * IDEMPOTENT: writing the same labels twice is writing the same labels.
+ */
+export function applyLabels(shell, r) {
+    shell.title.textContent = r.title;
+    shell.list.setAttribute('aria-label', r.listLabel);
+    shell.reset.textContent = r.resetLabel;
+    shell.close.textContent = r.closeLabel;
+    // the arrow is drawn by the stylesheet, out of the name (ADR-0159 rule 12)
+    shell.close.setAttribute('data-glifo', '↩');
+    // The panel's introduction is the footer's RESTING text (CLAUDE.md §4), never a `<p>` at the top.
+    // ⚠️ ABSENCE HAS TO ERASE, not just stop writing: on a retranslation into a dictionary without the key, the old
+    // attribute would survive and the footer would rest in the previous language.
+    if (r.intro)
+        shell.card.setAttribute('data-explain-idle', r.intro);
+    else
+        shell.card.removeAttribute('data-explain-idle');
 }
-function botao(ctx, id, rotulo, classe) {
-    const b = ctx.criar('button');
+function button(ctx, id, cssClass) {
+    const b = ctx.create('button');
     b.id = id;
-    b.className = classe;
+    b.className = cssClass;
     b.setAttribute('type', 'button');
-    // `textContent` e não `innerHTML`: um rótulo traduzido é dado de fora como qualquer outro, e um dicionário
-    // de consumidor pode trazer o que quiser dentro dele.
-    b.textContent = rotulo;
+    // The label comes in through `applyLabels`, by `textContent` and not `innerHTML`: a translated label is outside data
+    // like any other, and a consumer's dictionary can bring anything inside it.
     return b;
 }

package/dist-pkg/ui/panel-widgets.d.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { PanelShellCtx } from './panel-shell.js';
+/**
+ * The control's SHAPE, not its tag — because the question a panel asks is "does this turn on and off?", not "is this a
+ * `<button>`?".
+ *
+ * 📏 The first three came from measuring the panels: `interruptor` (a switch) covers most of the controls they reach,
+ * `escolha` (a select) and `cursor` (a slider) the rest. A new shape enters when a panel demands it, not before.
+ */
+export type ControlShape = 'interruptor' | 'escolha' | 'cursor' | 'radio' | 'button';
+export interface ControlRowSpec {
+    /** The CONTROL's id — `opt-facil`, `cane-div`. It is how the `settings-*` finds it. */
+    readonly id: string;
+    /** The SHORT label, already translated. It goes in the `<strong>`, and it is the only thing in view on the row. */
+    readonly label: string;
+    /**
+     * The explanation, already translated. It goes into a SINGLE `.opt-hint`, which `fillExplain` moves to the footer.
+     *
+     * 📌 Absent = this row has no explanation, which is a legitimate answer. The footer then rests on the panel's text
+     * (`data-explain-idle`) while the cursor is on it.
+     */
+    readonly hint?: string;
+    /** The control's shape. Absent: `interruptor`, the most common case. */
+    readonly shape?: ControlShape;
+    /**
+     * The name a screen reader announces, when it is not the label.
+     *
+     * ⚠️ IT EXISTS BECAUSE A SWITCH'S TEXT IS ITS STATE, not its name: a `<button>` whose `textContent` says "Off"
+     * announces "Off, button" and the person does not know off WHAT. The `<strong>` beside it solves that for whoever SEES
+     * the whole row; for whoever navigates control by control, this attribute solves it. Absent, it falls back to
+     * `label` — which is the right answer, not a fallback.
+     */
+    readonly ariaLabel?: string;
+}
+export interface ControlRow {
+    /** The whole `.ctrl-row`. It is where ADR-0029's `markChanged` puts the left-the-default mark. */
+    readonly row: HTMLElement;
+    /** The control itself, with the requested id. */
+    readonly control: HTMLElement;
+}
+/**
+ * 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 declare function controlRow(ctx: PanelShellCtx, spec: ControlRowSpec): ControlRow;
+/**
+ * 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 declare function labelRow(rowNode: HTMLElement, spec: ControlRowSpec): void;
+/**
+ * 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 declare function sectionHeader(ctx: PanelShellCtx, title: string, tag: string, rows: number): HTMLElement | null;
+/**
+ * What a steps control needs: a name, the positions (already translated) and the current one.
+ *
+ * 🎯 THE DEV ASKED FOR IT, with an exact shape: the contrast boost «deve funcionar trocando entre desligado, linear,
+ * misto e quadrático da mesma forma que se troca o número de jogadores, isto é, apertando botões direita e esquerda, e
+ * não através de uma barra», and the rounded corners «também». A slider hides how many positions there are; a dropdown
+ * hides them all until it opens. Steps always say where you are.
+ *
+ * 🔴 AND THE SHAPE IS A SINGLE LINE: «◀ Rótulo: valor ▶» (ADR-0130 errata, rule 3) — the Dev: «Não faça essa coisa
+ * estranha. Escreva "< Rounded corner: off >"». It is the way to cycle between FEW positions — up to five; above that,
+ * a dropdown.
+ */
+export interface StepsSpec {
+    /** The control's spoken name — it goes to `aria-label`. */
+    readonly label: string;
+    /** The positions, in order, already translated. */
+    readonly values: readonly string[];
+    /** The index of the current position. */
+    readonly current: number;
+}
+/**
+ * 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 declare function nextStep(from: number, total: number, delta: number): number;
+/**
+ * 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 declare function mountSteps(ctx: PanelShellCtx, spec: StepsSpec): HTMLElement;
+/**
+ * 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 declare const MAX_CYCLE_POSITIONS = 5;
+/** One position of an exclusive choice: what is stored, and what is shown and heard (already translated). */
+export interface ChoicePosition {
+    readonly value: string;
+    readonly label: string;
+}
+/** An exclusive choice: its spoken name, its positions in order, and the value in use. */
+export interface ChoiceSpec {
+    readonly label: string;
+    readonly values: readonly ChoicePosition[];
+    readonly current: string;
+}
+/**
+ * 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 declare function mountChoice(ctx: PanelShellCtx, spec: ChoiceSpec, pick: (value: string) => void): HTMLElement;
+/**
+ * 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 declare function updateChoice(el: HTMLElement, spec: ChoiceSpec): void;
+/** Reflects the current position: the written value, what is heard, and the ends that no longer move. */
+export declare function updateSteps(el: HTMLElement, spec: StepsSpec): void;