ice-web-components 1.0.0

package/dist/types/model/ICEHighScoreModel.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 排行榜的纯逻辑模型（不碰 canvas，也不直接依赖 localStorage）。
+ *
+ * - `add(score)` 插入后按**分数降序**排，并列时保持先来后到，超过 `maxEntries` 截断；
+ * - `getBest()` 给最高分（空榜 0）；`isInTop(score)` 判断「这一局值不值得炫耀」；
+ * - 存储通过构造函数注入（默认 `globalThis.localStorage`）：key 按卡带隔离；
+ * - 存档损坏（非法 JSON / 结构不对 / 里层字段不合法）一律降级成空榜，绝不抛；
+ * - 写盘失败（隐私模式、配额满）不影响内存里的成绩。
+ */
+export interface ICEHighScoreEntry {
+    score: number;
+    /** 可选标签（用户名 / 备注） */
+    label?: string;
+    /** 可选时间戳 */
+    at?: number;
+}
+/** 只需要这两个方法，注入内存实现即可在 node 里测。 */
+export interface ICEHighScoreStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
+}
+export interface ICEHighScoreOptions {
+    /** 榜单标识（一般用卡带 key：tetris / snake…） */
+    key: string;
+    /** 最多保留几条，默认 5 */
+    maxEntries?: number;
+    /** 存储实现；传 null 表示只放内存；不传则用 globalThis.localStorage（没有就退化成内存） */
+    storage?: ICEHighScoreStorage | null;
+    /** 存储键前缀，默认 `ice-arcade-scores-` */
+    prefix?: string;
+}
+export declare class ICEHighScoreModel {
+    private key;
+    private maxEntries;
+    private storage;
+    private prefix;
+    private entries;
+    constructor(options: ICEHighScoreOptions);
+    getKey(): string;
+    getStorageKey(): string;
+    getMaxEntries(): number;
+    /** 榜单拷贝（降序）。 */
+    getScores(): ICEHighScoreEntry[];
+    /** 最高分（空榜为 0）。 */
+    getBest(): number;
+    /** 这个分数能不能进榜（榜没满一律能进；并列最小分也算能进）。 */
+    isInTop(score: number): boolean;
+    /** 记一笔成绩，返回更新后的榜单。非法分数直接忽略。 */
+    add(score: number, options?: {
+        label?: string;
+        at?: number;
+    }): ICEHighScoreEntry[];
+    clear(): void;
+    /** 从存储重新读一遍（多标签页/多窗口场景）。 */
+    reload(): ICEHighScoreEntry[];
+    private __defaultStorage;
+    private __load;
+    private __save;
+}

package/dist/types/model/ICEMinesweeperModel.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 扫雷的纯逻辑模型（不碰 canvas）。
+ *
+ * 规则按 Windows XP 扫雷：
+ * - **首次点击安全**：第一次掀开格子时才布雷，且排除该格及其 8 邻域（空间够时）——
+ *   所以第一下永远不会炸，也常常一下展开一片；
+ * - **揭示**：相邻雷数为 0 时洪水填充展开整片空白；
+ * - **插旗循环**：无 → 🚩 → ❓ → 无（`questionMarks: false` 时只有旗）；
+ * - **chord**（双击数字）：周围旗数等于数字时，掀开其余未插旗的邻格（可能炸）；
+ * - **胜负**：掀开所有非雷格 = 胜；掀开雷 = 负（把所有雷亮出来）；
+ * - **计时**：由调用方 `tick()`（每秒一次）驱动；**只有 playing 才累加**（XP 的计时从第一次点击开始），
+ *   结束或还没开始都不动 —— 测试里可直接手动推进。
+ *
+ * 布雷用注入的 `random`（默认 `Math.random`），测试传固定序列即可复现棋局。
+ */
+export interface ICEMinesweeperDifficulty {
+    key: string;
+    label: string;
+    rows: number;
+    cols: number;
+    mines: number;
+}
+/** XP 扫雷的三档标准难度。 */
+export declare const ICE_MINESWEEPER_DIFFICULTIES: ICEMinesweeperDifficulty[];
+export declare type ICEMinesweeperState = 'ready' | 'playing' | 'won' | 'lost';
+export interface ICEMinesweeperCell {
+    row: number;
+    col: number;
+    mine: boolean;
+    revealed: boolean;
+    flagged: boolean;
+    question: boolean;
+    /** 周围 8 格的雷数 */
+    adjacent: number;
+}
+export interface ICEMinesweeperOptions {
+    rows?: number;
+    cols?: number;
+    mines?: number;
+    /** 随机源（0..1），默认 Math.random —— 测试可注入固定序列 */
+    random?: () => number;
+    /** 首次点击安全（默认 true） */
+    firstClickSafe?: boolean;
+    /** 插旗循环里是否带问号（默认 true） */
+    questionMarks?: boolean;
+}
+export declare type ICEMinesweeperListener = (model: ICEMinesweeperModel) => void;
+export declare class ICEMinesweeperModel {
+    private rows;
+    private cols;
+    private mineCount;
+    private random;
+    private firstClickSafe;
+    private questionMarks;
+    private grid;
+    private state;
+    private minesPlaced;
+    private elapsed;
+    private listeners;
+    constructor(options?: ICEMinesweeperOptions);
+    getRows(): number;
+    getCols(): number;
+    getMineCount(): number;
+    getState(): ICEMinesweeperState;
+    isWon(): boolean;
+    isLost(): boolean;
+    isOver(): boolean;
+    getElapsed(): number;
+    getFlags(): number;
+    /** 剩余雷数 = 总雷数 - 已插旗数（可能为负，和 XP 一样显示负数）。 */
+    getMinesLeft(): number;
+    getRevealedCount(): number;
+    getCells(): ICEMinesweeperCell[];
+    getCell(row: number, col: number): ICEMinesweeperCell | null;
+    /** 雷是否已经布好（首点安全时，第一次 reveal 之后才会布）。 */
+    areMinesPlaced(): boolean;
+    /** 相邻 8 格的坐标。 */
+    neighbors(row: number, col: number): Array<[number, number]>;
+    /** 掀开格子（插旗的会被忽略）。首次掀开时布雷（首点安全）。 */
+    reveal(row: number, col: number): this;
+    /** 右键：无 → 旗 → 问号 → 无。 */
+    toggleFlag(row: number, col: number): this;
+    /** 双击已掀开的数字：周围旗数够时掀开其余邻格。 */
+    chord(row: number, col: number): this;
+    /**
+     * 计时 +1 秒（调用方按秒驱动）。只有 `playing` 才累加：
+     * 还没点第一下（ready）不计时（和 XP 一致），胜负已分之后也不计。
+     */
+    tick(): this;
+    /** 重开（可顺带换难度）。 */
+    reset(options?: ICEMinesweeperOptions): this;
+    addChangeListener(listener: ICEMinesweeperListener): () => void;
+    private __inBounds;
+    private __at;
+    private __resetGrid;
+    /** 布雷：`safe` 是首点坐标（连同 8 邻域一起排除）。 */
+    private __placeMines;
+    /** 掀开一格：是雷就结束，是 0 就递归展开。 */
+    private __revealCell;
+    private __checkFinish;
+    private __notify;
+}

package/dist/types/model/ICESelectionModel.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 选择模型：列表 / 树 / 穿梭框共用的选择状态。
+ *
+ * 与其它模型（ICEButtonModel / ICEToggleModel / ICEBoundedRangeModel）同风格：
+ * 纯状态 + 监听器，UI 组件只负责把状态画出来。
+ */
+export declare type ICESelectionMode = 'single' | 'multiple';
+export interface ICESelectionModelOptions {
+    mode?: ICESelectionMode;
+    selected?: string[];
+}
+export declare type ICESelectionListener = (model: ICESelectionModel) => void;
+export declare class ICESelectionModel {
+    private mode;
+    private selected;
+    private listeners;
+    constructor(options?: ICESelectionModelOptions);
+    getMode(): ICESelectionMode;
+    setMode(mode: ICESelectionMode): this;
+    getSelectedKeys(): string[];
+    isSelected(key: string): boolean;
+    /** 选中（single 替换；multiple 追加，已选中则不变）。 */
+    select(key: string): this;
+    /** 切换选中状态（点一下选中、再点取消）。 */
+    toggle(key: string): this;
+    setSelected(keys: string[]): this;
+    clear(): this;
+    addChangeListener(listener: ICESelectionListener): () => void;
+    private __normalize;
+    private __notify;
+}

package/dist/types/model/ICESnakeModel.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 贪吃蛇的纯逻辑模型（不碰 canvas）。
+ *
+ * 规则按经典街机 / Nokia 贪吃蛇：
+ * - **前进**：`tick()` 让头往前走一格、尾巴收一格（长度不变）；
+ * - **吃食物**：头落到食物上 → 长度 +1、加分、食物重新生成（绝不落在蛇身上）；
+ * - **转向**：可以排队两个转向依次生效；**不能 180° 掉头**（向右时按左无效）；
+ * - **撞墙即死**；`wrap: true` 时穿墙（从左边出去从右边回来）；
+ * - **撞自己即死**，但「正在移开的尾巴」不算 —— 那格这一步就空出来了；
+ * - **越吃越快**：每 5 个升一级，`getTickInterval()` 按等级递减并有下限（70ms）；
+ * - 暂停时 `tick()` 与转向都无效；食物位置由注入的 `random` 决定，测试可复现。
+ *
+ * 蛇身是 `[row, col]` 数组，**头在最前**（`body[0]`），和 `ICETetrisModel` 的坐标约定一致。
+ */
+/** 四个方向。 */
+export declare type ICESnakeDirection = 'up' | 'right' | 'down' | 'left';
+/** 按上、右、下、左顺序排列的方向表（UI 画方向盘可以直接用）。 */
+export declare const ICE_SNAKE_DIRECTIONS: ICESnakeDirection[];
+/** 棋盘上的一格。 */
+export declare type ICESnakePoint = [number, number];
+export interface ICESnakeOptions {
+    rows?: number;
+    cols?: number;
+    /** 随机源（0..1），默认 `Math.random` —— 测试注入固定序列即可复现食物位置 */
+    random?: () => number;
+    /** 撞墙时穿墙而不是死（默认 false） */
+    wrap?: boolean;
+    /** 初始长度（默认 3，最小 2） */
+    initialLength?: number;
+}
+export declare type ICESnakeListener = (model: ICESnakeModel) => void;
+export declare class ICESnakeModel {
+    private rows;
+    private cols;
+    private random;
+    private wrap;
+    private initialLength;
+    private body;
+    private food;
+    private direction;
+    /** 待生效的转向（最多两个，按顺序 consume） */
+    private queue;
+    private score;
+    private eaten;
+    private gameOver;
+    private paused;
+    private listeners;
+    constructor(options?: ICESnakeOptions);
+    getRows(): number;
+    getCols(): number;
+    /** 蛇身（头在最前）。 */
+    getBody(): ICESnakePoint[];
+    /** 头的坐标。 */
+    getHead(): ICESnakePoint;
+    getLength(): number;
+    getFood(): ICESnakePoint | null;
+    getDirection(): ICESnakeDirection;
+    /** 排队中的转向（UI 可以拿它显示「已接收输入」）。 */
+    getPendingDirections(): ICESnakeDirection[];
+    getScore(): number;
+    /** 已经吃掉的food个数。 */
+    getEaten(): number;
+    /** 每 5 个食物升一级，从 1 开始。 */
+    getLevel(): number;
+    /** 当前等级下的步进间隔（毫秒），等级越高越短，下限 70ms。 */
+    getTickInterval(): number;
+    isGameOver(): boolean;
+    isPaused(): boolean;
+    addChangeListener(listener: ICESnakeListener): () => void;
+    /**
+     * 掉头请求会被忽略并返回 `false`；重复的「当前方向」算接受（`true`）但不占队列；
+     * 队列满（已有两个待生效转向）也会被忽略。
+     */
+    setDirection(direction: ICESnakeDirection): boolean;
+    /** 前进一步；撞墙 / 撞自己则进入 game over 并返回 false。 */
+    tick(): boolean;
+    pause(): void;
+    resume(): void;
+    /** 重置：可只覆盖部分选项（行列、随机源、穿墙、初始长度）。 */
+    reset(options?: ICESnakeOptions): void;
+    /** 直接摆一条蛇（造题、读档、UI demo 都用得上）。 */
+    setBodyForTest(cells: ICESnakePoint[], direction?: ICESnakeDirection): void;
+    /** 直接摆一个食物。 */
+    setFoodForTest(row: number, col: number): void;
+    private __resetBoard;
+    private __die;
+    /** 在所有空格里随机挑一个放食物（挑不到说明棋盘满了）。 */
+    private __spawnFood;
+    private notify;
+}

package/dist/types/model/ICETetrisModel.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 俄罗斯方块的纯逻辑模型（不碰 canvas）。
+ *
+ * 规则按现代标准俄罗斯方块（SRS-lite）：
+ * - **7-bag 随机**：每 7 个方块恰好包含 7 种各一次（公平性），可用注入的 `random` 复现同一局；
+ * - 移动/旋转受墙与已落方块阻挡；旋转带简易踢墙（0 / ±1 / ±2 依次尝试）；
+ * - 重力由 `tick()` 驱动（下落一行），间隔随等级变快；
+ * - 消行计分：1/2/3/4 行 = 100/300/500/800 × 等级；每 10 行升一级；
+ * - 软降 +1 分/格、硬降 +2 分/格；
+ * - 生成位置被占 → game over；暂停时所有操作无效。
+ *
+ * 棋盘格存的直接是方块类型（`'I' | 'O' | ... | null`），UI 层拿它当调色板的 key 用。
+ */
+/** 七种方块。 */
+export declare type ICETetrominoType = 'I' | 'O' | 'T' | 'S' | 'Z' | 'J' | 'L';
+/** 棋盘格子：落了方块就是它的类型，否则 null。 */
+export declare type ICETetrisCell = ICETetrominoType | null;
+/** 方块内的一格，用 `[row, col]` 相对（或绝对）坐标表示。 */
+export declare type ICETetrisOffset = [number, number];
+/** 方块类型 → 4 个旋转状态，每个状态是 4 个 `[row, col]` 偏移。 */
+export declare type ICETetrominoShape = ICETetrisOffset[];
+/**
+ * 七种方块 × 4 个旋转状态。
+ * 旋转在固定的方阵内进行（不做归一化），因此 O 转完还是 O、I 会躺平/立起来。
+ */
+export declare const ICE_TETROMINOES: Record<ICETetrominoType, ICETetrominoShape[]>;
+/** 当前正在下落的方块。 */
+export interface ICETetrisPiece {
+    type: ICETetrominoType;
+    /** 旋转状态下标 0..3 */
+    rotation: number;
+    /** 方块左上角在棋盘上的行 */
+    row: number;
+    /** 方块左上角在棋盘上的列 */
+    col: number;
+    /** 四个格子的**绝对**棋盘坐标 */
+    cells: ICETetrisOffset[];
+}
+export interface ICETetrisOptions {
+    rows?: number;
+    cols?: number;
+    /** 随机源（0..1），默认 `Math.random` —— 测试注入固定序列即可复现 */
+    random?: () => number;
+}
+export declare type ICETetrisListener = (model: ICETetrisModel) => void;
+/** 消 1/2/3/4 行的基础分（再乘等级），经典数值。 */
+export declare const ICE_TETRIS_LINE_SCORES: number[];
+export declare class ICETetrisModel {
+    private rows;
+    private cols;
+    private random;
+    private board;
+    private queue;
+    private current;
+    private score;
+    private lines;
+    private gameOver;
+    private paused;
+    private lastCleared;
+    private listeners;
+    constructor(options?: ICETetrisOptions);
+    getRows(): number;
+    getCols(): number;
+    getBoard(): ICETetrisCell[][];
+    getCurrent(): ICETetrisPiece;
+    /** 预览队列（下一个方块在 `[0]`）。 */
+    getNextQueue(): ICETetrominoType[];
+    isGameOver(): boolean;
+    isPaused(): boolean;
+    getScore(): number;
+    getLines(): number;
+    /** 上一次锁定消掉了几行（0 表示没消；UI 用它做特效/连击提示）。 */
+    getLastClearedLines(): number;
+    /** 每 10 行升一级，从 1 开始。 */
+    getLevel(): number;
+    /** 当前等级下的自动下落间隔（毫秒），等级越高越短。 */
+    getDropInterval(): number;
+    /** 当前方块笔直落下去会停在哪（画幽灵投影用）。 */
+    getGhost(): ICETetrisOffset[];
+    addChangeListener(listener: ICETetrisListener): () => void;
+    moveLeft(): boolean;
+    moveRight(): boolean;
+    /** 顺时针旋转（带上踢墙）。 */
+    rotateCW(): boolean;
+    /** 逆时针旋转（带上踢墙）。 */
+    rotateCCW(): boolean;
+    /** 重力：下落一行；到底就锁定。 */
+    tick(): boolean;
+    /** 软降：下落一行并 +1 分；到底就锁定。 */
+    softDrop(): boolean;
+    /** 硬降：一步落到底、锁定，按落下的格数 +2 分/格。 */
+    hardDrop(): boolean;
+    pause(): void;
+    resume(): void;
+    /** 重置：可只覆盖部分选项（行列、随机源），其余沿用构造时的配置。 */
+    reset(options?: ICETetrisOptions): void;
+    /** 直接摆一格（造题、读档、UI demo 都用得上）。 */
+    setCellForTest(row: number, col: number, type: ICETetrominoType | null): void;
+    /** 直接改累计消行数（测试升级曲线用）。 */
+    setLinesForTest(lines: number): void;
+    private __resetBoard;
+    /** 暂停 / 结束 / 没有当前方块时，一切输入无效。 */
+    private blocked;
+    private tryMove;
+    /** 移动但不通知（硬降内部用，避免一次操作刷屏）。 */
+    private tryMoveQuiet;
+    /** 旋转 + 踢墙：依次尝试 (0,0) → 左右各 1 → 左右各 2 → 上抬一格。 */
+    private tryRotate;
+    private stepDown;
+    /** 把当前方块写进棋盘 → 消行 → 出下一个；顶到天花板就 game over。 */
+    private lock;
+    private clearLines;
+    private spawn;
+    /** 队列见底就补一袋（保证预览里永远有下一袋可看）。 */
+    private refillQueue;
+    private collides;
+    private notify;
+}

package/dist/types/model/ICEToggleModel.d.ts

@@ -0,0 +1,14 @@
+export declare type ICEToggleModelListener = (model: ICEToggleModel) => void;
+export declare class ICEToggleModel {
+    private selected;
+    private listeners;
+    constructor(options?: {
+        selected?: boolean;
+    });
+    isSelected(): boolean;
+    setSelected(selected: boolean): this;
+    toggle(): this;
+    addChangeListener(listener: ICEToggleModelListener): this;
+    removeChangeListener(listener: ICEToggleModelListener): this;
+    private __notify;
+}

package/dist/types/theme/ICEArcadeTheme.d.ts

@@ -0,0 +1,22 @@
+import { ICEThemeTokens } from './ICETheme';
+import { ICETileMapPalette } from '../components/ICETileMap';
+/**
+ * 街机主题：给「掌机 / 游戏」这类深色场景用的一套 token。
+ *
+ * 为什么要有它：arcade 示例一开始把方块和蛇的颜色写死在页面里，结果是**面板文字跟着主题走、
+ * 游戏美术不跟** —— 一个页面两套配色来源。现在游戏配色也收进 token：
+ *
+ * ```ts
+ * iceUIManager.registerTheme('arcade', ICE_ARCADE_THEME).setTheme('arcade');
+ * const board = new ICETileMap({ rows, cols, palette: ICE_ARCADE_PALETTE });
+ * ```
+ *
+ * 它是**完整主题**（不是补丁）：token 组与内置 dark 完全一致，只换颜色，所以任何组件切过去
+ * 都不会缺 token。
+ */
+export declare const ICE_ARCADE_THEME: ICEThemeTokens;
+/**
+ * 游戏调色板：方块 7 种 + 蛇头 / 蛇身 / 食物。
+ * 颜色取 Bootstrap 语义色，描边统一是填充色压暗 35%（和页面里 `shade(color, -0.35)` 一致）。
+ */
+export declare const ICE_ARCADE_PALETTE: ICETileMapPalette;

package/dist/types/theme/ICETheme.d.ts

@@ -0,0 +1,120 @@
+export declare type ICEColor = string;
+/** 阴影：直接给引擎认的四个数值字段（比自己再造一套 shadow 名字更可控）。 */
+export declare type ICEShadowTokens = {
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+};
+export declare type ICEThemeTokens = {
+    colors: {
+        primary: ICEColor;
+        primaryHover: ICEColor;
+        primaryActive: ICEColor;
+        primaryBg: ICEColor;
+        primaryBorder: ICEColor;
+        primaryText: ICEColor;
+        background: ICEColor;
+        surface: ICEColor;
+        elevated: ICEColor;
+        border: ICEColor;
+        borderSecondary: ICEColor;
+        text: ICEColor;
+        textSecondary: ICEColor;
+        textTertiary: ICEColor;
+        textDisabled: ICEColor;
+        muted: ICEColor;
+        disabled: ICEColor;
+        disabledText: ICEColor;
+        success: ICEColor;
+        successBg: ICEColor;
+        successBorder: ICEColor;
+        warning: ICEColor;
+        warningBg: ICEColor;
+        warningBorder: ICEColor;
+        error: ICEColor;
+        errorBg: ICEColor;
+        errorBorder: ICEColor;
+        info: ICEColor;
+        infoBg: ICEColor;
+        infoBorder: ICEColor;
+        /**
+         * 强调文字色（Bootstrap 的 `*-text-emphasis`）：用在 **subtle 底**上的文字。
+         * 直接把 `warning: #ffc107` 这样的亮色当文字压不住（对比度不足），
+         * 所以浅底场景（Alert/Tag/Badge）统一取这一组深色。
+         */
+        primaryTextEmphasis: ICEColor;
+        successTextEmphasis: ICEColor;
+        warningTextEmphasis: ICEColor;
+        errorTextEmphasis: ICEColor;
+        infoTextEmphasis: ICEColor;
+        /** 聚焦态描边色（Bootstrap 的 `$input-btn-focus-color` / 聚焦输入框边框 `#86b7fe`）。 */
+        focusRing: ICEColor;
+    };
+    spacing: {
+        xxs: number;
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+        xxl: number;
+    };
+    radius: {
+        xs: number;
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+        pill: number;
+    };
+    font: {
+        family: string;
+        size: number;
+        sizeSmall: number;
+        sizeLarge: number;
+        weightNormal: string;
+        weightMedium: string;
+        weightSemibold: string;
+        weightBold: string;
+    };
+    control: {
+        heightSmall: number;
+        height: number;
+        heightLarge: number;
+        paddingXXS: number;
+        paddingXS: number;
+        paddingSmall: number;
+        padding: number;
+        paddingLarge: number;
+        lineWidth: number;
+        lineWidthFocused: number;
+        switchWidth: number;
+        switchHeight: number;
+        switchHandle: number;
+        checkboxSize: number;
+        radioSize: number;
+        progressHeight: number;
+        sliderTrackHeight: number;
+        sliderHandle: number;
+    };
+    shadows: {
+        sm: ICEShadowTokens;
+        md: ICEShadowTokens;
+        lg: ICEShadowTokens;
+    };
+};
+export declare const ICE_LIGHT_THEME: ICEThemeTokens;
+export declare const ICE_DARK_THEME: ICEThemeTokens;
+/**
+ * Windows XP 经典主题（Luna 蓝 + 米灰控件）。
+ *
+ * 用途：桌面 / 怀旧风格的应用。用 `iceUIManager.registerTheme('xp', ICE_XP_THEME).setTheme('xp')`
+ * 切换（主题在组件构造时读取，先切主题再建组件）。
+ *
+ * 取色要点：
+ * - 主色取 XP 选择蓝 `#316ac5`，控件面 `#ece9d8`（经典米灰），输入框白底 + `#7f9db9` 边框；
+ * - 圆角压到 2~3px、控件更矮更紧凑（XP 的按钮比 Bootstrap 小一圈）；
+ * - 阴影几乎不用（XP 是描边风格，不是投影风格）。
+ */
+export declare const ICE_XP_THEME: ICEThemeTokens;

package/dist/types/util/ICEAccessibilityMirror.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 无障碍（a11y）DOM 镜像层。
+ *
+ * canvas 内容对屏幕阅读器完全不可见（`<canvas>` 只是位图），所以必须有一层隐藏 DOM 把
+ * 语义暴露出去。引擎负责产出快照（见引擎 `src/a11y/accessibility.ts`：
+ * id / 角色建议 / `state.ariaLabel` / 屏幕盒 / tab 顺序），**这里负责把快照变成 DOM**：
+ *
+ * ```ts
+ * const mirror = mountICEAccessibilityMirror(ice);
+ * // 场景变化后（换页、开窗、列表刷新……）调一次
+ * mirror.refresh();
+ * ```
+ *
+ * 元素是「透明但存在」的（`opacity: 0`，不是 `display:none` —— 后者会把语义一起藏掉），
+ * 位置与画布组件对齐，键盘 Tab 能进去、屏幕阅读器能读到、点它等于点画布组件。
+ * 容器默认 `pointer-events: none`，只有可交互元素打开指针事件，避免挡住画布本身。
+ */
+export interface ICEAccessibleNodeLike {
+    id: string;
+    role: string;
+    label: string;
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    visible: boolean;
+    interactive: boolean;
+    focusable: boolean;
+    tabIndex: number;
+    selected: boolean;
+    level: number;
+    parentId: string | null;
+}
+export interface ICEA11yMirrorOptions {
+    /** 注入 document（测试用假对象）；不传取全局 document */
+    doc?: any;
+    /** 挂载容器（默认挂到 document.body） */
+    container?: any;
+    /** 容器 id，默认 `ice-a11y-mirror` */
+    id?: string;
+    /** 是否包含不可见组件（默认 false，跟引擎默认一致） */
+    includeHidden?: boolean;
+    /** 自定义角色映射：引擎给的是「建议」，产品语义可以覆盖 */
+    roleMap?: (node: ICEAccessibleNodeLike, component: any) => string | null;
+}
+export interface ICEA11yMirrorHandle {
+    isMounted(): boolean;
+    getContainer(): any;
+    getElements(): any[];
+    refresh(): void;
+    unmount(): void;
+}
+export declare function mountICEAccessibilityMirror(ice: any, options?: ICEA11yMirrorOptions): ICEA11yMirrorHandle;