@the-inclusionist/engine 9.0.0 → 11.0.0

package/dist-pkg/ui/settings-visual.d.ts

@@ -1,26 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import type { HcRoleKey } from '../render/hc-role-data.js';
-import { type VizMode } from '../render/viz-modes.js';
-export type { HcRoleKey as RoleKey } from '../render/hc-role-data.js';
-type RoleKey = HcRoleKey;
-export type RGB = readonly [number, number, number];
-/** Contrast levels, in cycle order — mirrors game.js's HC_SEQ (also used there by the physical contrast-cycle button). */
-export declare const CONTRAST_LEVELS: readonly string[];
-/**
- * TUDO que este menu escreve em `p.viz`: os 4 níveis de contraste MAIS as 3 correções de daltonismo, que
- * mudaram de casa por decisão do Dev (#60). Elas moravam no Modo empatia, onde a criança daltônica precisava
- * entrar no menu "sentir como é ter uma deficiência" para achar a correção da deficiência que ela tem.
- *
- * Os sete vivem num CONTROLE SÓ, e isso não é economia de espaço: `p.viz` guarda UM valor. Dois controles
- * separados se sobrescreveriam em silêncio — a criança escolheria a correção, depois o contraste, e perderia
- * a correção sem nada dizer que perdeu. Uma lista só conta a verdade sobre a exclusividade.
- */
-export declare const VISUAL_MODES: readonly string[];
-/** Short announcement labels — mirrors game.js's HC_LABEL. */
-export declare const CONTRAST_LABELS: Readonly<Record<string, string>>;
-export declare const ROLE_KEYS: readonly RoleKey[];
-/** Readable labels for the color-blocking roles — mirrors game.js's ROLE_LBL. */
-export declare const ROLE_LABELS: Readonly<Record<RoleKey, string>>;
+import type { Translate } from '../core/i18n.js';
+import { type RGB, type RoleKey } from './visual-choices.js';
 /** Live snapshot of the state this panel does not own — read fresh on every render(). */
 export interface VisualSettings {
     lq: number;
@@ -31,33 +11,30 @@ export interface VisualSettings {
     roleColors: Record<RoleKey, RGB>;
 }
 export interface SettingsVisualCtx {
-    /** Quantos jogadores/telas. Estado de RODADA (ADR-0038): vem da instância que a raiz possui.
-     *  Era `numPlayers`, um `let` de `core/state` importado como binding vivo — e um `let` de módulo
-     *  é compartilhado por qualquer segundo jogo que a mesma página carregue (D13 do `demos`). */
+    /** Translates in the page's language — the root's translator (ADR-0232 D3). REQUIRED: text built from nowhere is a raw key. */
+    t: Translate;
+    /** How many players/screens. ROUND state (ADR-0038): it comes from the instance the root owns — a module `let` would
+     *  be shared by any second game the same page loads. */
     getNumPlayers: () => number;
-    /** Os jogadores. Estado de RODADA, pelo mesmo motivo. `readonly unknown[]` porque cada consumidor
-     *  estreita para a SUA fatia — o tipo real é do jogo, não da engine (ADR-0033). */
+    /** The players. ROUND state, for the same reason. `readonly unknown[]` because each consumer narrows to ITS slice —
+     *  the real type is the game's, not the engine's (ADR-0033). */
     getPlayers: () => readonly unknown[];
     $: <T extends Element = Element>(sel: string) => T | null;
     srSay: (text: string) => void;
-    /** Fresh read of lq/ownerColors/cbSafe/outlineFg/outlineBg/roleColors (game.js live vars). */
+    /** Fresh read of lq/ownerColors/cbSafe/outlineFg/outlineBg/roleColors (the host's live values). */
     getVisualSettings: () => VisualSettings;
-    /** `selVizPlayer` — shared with the Empathy panel; owned by game.js. */
+    /** The selected player — shared with the Empathy panel; owned by the host. */
     getSelectedPlayer: () => number;
     setSelectedPlayer: (i: number) => void;
     /** Same setPlayerViz used by the Empathy panel and the physical contrast-cycle shortcut. */
     setPlayerViz: (i: number, mode: string) => void;
-    /** Desenha UMA lista de rádio de modos visuais (+ abas por jogador). O MESMO helper que o painel de
-     *  empatia usa — de propósito: as três correções mudaram de menu, e mudar junto a aparência delas faria a
-     *  criança ter de reaprender um controle que ela já conhecia. */
     /**
-     * Os DOIS eixos deste painel (#104). Substituiu o `renderVizGroup`, que fica com o painel de EMPATIA.
+     * The TWO axes of this panel (#104). The Empathy panel keeps `renderVizGroup`.
      *
-     * ⚠️ A lista de sete que este painel oferecia era a forma honesta de contar uma exclusividade REAL, e o
-     * `VISUAL_MODES` explica-a em prosa logo acima. Ela deixou de existir: o estado tem dois eixos, e os
-     * escritores por eixo mexem num sem tocar no outro.
+     * ⚠️ The state has two axes, and the per-axis writers change one without touching the other — a single exclusive list
+     * would no longer tell the truth about it.
      */
-    renderEixosVisuais: (listSel: string, tabsSel: string) => void;
+    renderVisualAxes: (listSel: string, tabsSel: string) => void;
     setLq: (t: number) => void;
     setOwnerColors: (on: boolean) => void;
     setCbSafe: (on: boolean) => void;
@@ -66,64 +43,29 @@ export interface SettingsVisualCtx {
     setRoleColor: (key: RoleKey, hex: string) => void;
     resetRoleColors: () => void;
     /**
-     * Move a prosa das linhas para o rodapé (`ui/settings-panel` → `fillExplain`). Chamado a CADA render.
+     * Moves the rows' prose to the footer (`ui/settings-panel` → `fillExplain`). Called on EVERY render.
      *
-     * ⚠️ NÃO É OPCIONAL POR ELEGÂNCIA: `fillExplain` roda uma vez quando o overlay é frontalizado e move o
-     * `.opt-hint` de dentro de cada linha para o rodapé. Este painel RECONSTRÓI as linhas, e as linhas novas
-     * voltam com a prosa lá dentro — então a explicação aparece duas vezes, no rodapé e sob o rótulo, a
-     * partir do primeiro clique. O `CLAUDE.md` §4 regista exatamente isto, e a issue #109 já o consertou
-     * uma vez noutros painéis.
+     * ⚠️ Relabelling a row puts its `.opt-hint` back inside it — so without this call the explanation appears twice, in
+     * the footer and under the label, from the first click. `CLAUDE.md` §4 records exactly this (issue #109).
      *
-     * Opcional na assinatura porque um consumidor pode montar o painel sem a casca (um teste, o segundo
-     * consumidor): sem casca não há rodapé para duplicar.
+     * Optional in the signature because a consumer can mount the panel without the shell (a test): without the shell
+     * there is no footer to duplicate.
      */
     fillExplain?: (card: HTMLElement | null) => void;
+    /** Which host-specific rows to draw (see `VisualRowsOffered`). Absent = all, as before. */
+    offer?: VisualRowsOffered;
 }
 /**
- * `viz` quando ele é um modo DESTE menu (contraste ou correção), senão 'normal'.
- *
- * Chamava-se `resolveContrastValue` enquanto o menu só tinha contraste. O nome antigo passaria a mentir ao
- * devolver `fix-deuter`, e um nome que mente sobre o que devolve é pior que um nome comprido.
- */
-export declare function resolveVisualMode(viz: string): string;
-/** i18n KEY of a contrast level's label; unknown modes fall back to the 'off' key. Resolve with `t()`. */
-export declare function contrastLabel(mode: string): string;
-export declare function clamp01(t: number): number;
-/**
- * i18n KEY of the L->Q slider label ('lq.off'/'lq.linear'/'lq.mixed'/'lq.quadratic'). The label belongs to the
- * L->Q feature, so it lives with the filter that owns it (render/lq-filter) and is re-exported here under the
- * name this overlay has always used. Two copies of one rule is one copy too many: only the owner may change
- * what the levels mean. Callers resolve with `t()` — see the note on lqName about the `t` shadowing.
- */
-export { lqName as lqLabel } from '../render/lq-filter.js';
-/** t (0..1) -> slider percent (0..100, rounded) — mirrors `Math.round(lqT*100)`. */
-export declare function lqPercent(t: number): number;
-/** slider percent (any number) -> clamped t (0..1) — mirrors `+lq.value/100` fed into setLq's clamp. */
-export declare function lqFromPercent(pct: number): number;
-/** Defensive clamp when the player count shrank — mirrors `if(selVizPlayer>=numPlayers)selVizPlayer=0`. */
-export declare function clampSelectedPlayer(selected: number, playerCount: number): number;
-/** [r,g,b] (0..255) -> '#rrggbb' — mirrors game.js's rgbHex. */
-export declare function rgbToHex(rgb: RGB): string;
-/** Shared on/off button label used by this panel's toggle buttons. */
-export declare function onOffLabel(on: boolean): string;
-/** Builds the #visual-list innerHTML — pure string templating, no DOM access. Mirrors renderVisual()'s markup. */
-/**
- * Os 7 modos como o painel os OFERECE: uma lista de rádio, com nome e descrição em cada linha.
+ * The rows a host OFFERS beyond the two every host can drive (contrast enhancement and the safe palette).
  *
- * A primeira versão desta mudança usou um `<select>`, e foi um erro que o Dev pegou na hora: no menu de
- * empatia as três correções eram LINHAS VISÍVEIS, com descrição; dentro de um `<select>` viraram uma linha
- * fechada dentro de uma caixa fechada. Para um controle cuja razão de existir é ser ACHADO por quem enxerga
- * mal, esconder atrás de um clique é quase o mesmo que não ter movido. Voltam a ser linhas, e pelo mesmo
- * renderizador que o painel de empatia usa — o que a criança já sabia procurar continua com a mesma cara.
- *
- * Rádio, e não sete botões: `p.viz` guarda UM valor, e a exclusividade fica dita pela forma do controle em
- * vez de ser descoberta ao perder a correção que se acabou de escolher.
+ * ⚠️ Owner colours and the colour-blocking roles belong to a game that has item owners and «lava, ladder, water, gate»
+ * roles; the engine's own panel (`createGame`) has no writer for either and must not describe a game it does not know.
+ * The default keeps every existing consumer's panel exactly as it was.
  */
-export declare const VISUAL_MODE_LIST: readonly VizMode[];
-export declare function renderVisualPanelHtml(_contrastValue: string, s: VisualSettings): string;
-/** Duas cores de papel são a mesma? Comparação por componente — `[0,0,0] === [0,0,0]` é `false` em JS, e
- *  esse `false` diria "alterado" para uma cor que ninguém tocou, mandando a criança desfazer o que não fez. */
-export declare function sameRgb(a: RGB | undefined, b: RGB | undefined): boolean;
+export interface VisualRowsOffered {
+    readonly owner: boolean;
+    readonly roles: boolean;
+}
 export interface SettingsVisual {
     /** Rebuilds #visual-list and (re)wires its controls — call whenever the panel should reflect fresh state. */
     render: () => void;