ice-web-components 1.1.0 → 1.3.0

package/dist/types/components/ICELabel.d.ts

@@ -8,6 +8,14 @@ export declare class ICELabel extends ICEWidget {
     constructor(props?: any);
     setText(text: string): this;
     getText(): string;
+    /**
+     * 改文字颜色（动态强调 / 置灰用，比如 BIOS 自检行的灰→黄→绿、菜单选中态）。
+     *
+     * 必须走内层 `ICEText`：文字是它画的，构造期 `style` 已经下沉到那一层，
+     * 之后再 `setState({ style })` 只会改到外壳容器，屏幕上的字纹丝不动。
+     * 只覆盖 `fillStyle`，字号 / 字体 / 对齐这些原样保留。
+     */
+    setTextColor(color: string): this;
     /**
      * 让标签自身占据文字的实测尺寸。
      *

package/dist/types/components/ICETileMap.d.ts

@@ -90,6 +90,9 @@ export declare class ICETileMap extends ICEWidget {
     private highlightColor;
     private labelFontSize;
     private labelColor;
+    /** 构造期是否显式给过 width/height（`props` 里已被默认值填过，只能在这里记一笔） */
+    private explicitWidth;
+    private explicitHeight;
     /** 自绘流程执行次数（浏览器里由 render() 驱动；单测可直接调 paintBoard()） */
     private paintCount;
     constructor(props: ICETileMapOptions);
@@ -97,6 +100,15 @@ export declare class ICETileMap extends ICEWidget {
     getCols(): number;
     getCellSize(): number;
     getGap(): number;
+    /**
+     * 换网格尺寸（行列 / 格子大小一起换），并清空格子数据与高亮。
+     *
+     * 为什么必须有这个方法：`rows/cols/cellSize` 在构造期就被缓存进实例字段，
+     * 只 `setState({ rows, cols })` 的话**内部字段还是旧的** —— 下一次 `setTiles` 会按旧尺寸
+     * 抛错（像素编辑器把 32×32 切成 16×16 时就是这么炸的）。
+     * 显式给过 `width/height` 的（想自己留白）保持不动，没给过的跟着格子尺寸重算。
+     */
+    setSize(rows: number, cols: number, cellSize?: number): this;
     /** 格子在组件内的矩形（gap 均分在两边）。 */
     getCellRect(row: number, col: number): {
         left: number;

package/dist/types/index.d.ts

@@ -110,3 +110,6 @@ export * from './model/ICESnakeModel';
 export * from './model/ICEHighScoreModel';
 export * from './model/ICEChip8Model';
 export * from './model/ICE2048Model';
+export * from './model/ICEHistoryModel';
+export * from './model/ICEPixelModel';
+export * from './model/ICEBiosModel';

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

@@ -0,0 +1,124 @@
+/**
+ * 掌机 BIOS 的纯逻辑（不碰 canvas、不碰 DOM）。
+ *
+ * 掌机开机先跑一段「自检 → 菜单」的引导，然后才把控制权交给卡带：
+ * 自检**按时序推进**（页面每帧调 `tick(dt)`），菜单是**光标 + 确认**的老式控制台交互。
+ * 页面只负责把 `getSteps()` / `getMenuEntries()` 画成文字，并执行 `confirm()` 返回的动作 ——
+ * 状态机与渲染分开，所以「自检要跑多久、菜单怎么绕、设置存到哪」都能在 node 里单测。
+ *
+ * 约定：
+ * - 自检项由 `steps` 注入（默认 5 项：CPU / RAM / VRAM / SOUND / CART），每项有自己的耗时；
+ * - 相位机：`post`（自检中）→ `menu`（启动菜单）或 `boot`（直接启动，快速启动开着时）；
+ *   `settings`（设置页）从菜单进、`back()` 回菜单；
+ * - 菜单光标上下**循环**（到头绕回去，老式 BIOS 都这样），进设置前记下位置、回来还停在那儿；
+ * - 设置（快速启动 / 默认卡带）落到注入的存储里；坏数据、写盘失败一律降级，绝不抛。
+ */
+export declare type ICEBiosPhase = 'post' | 'menu' | 'settings' | 'boot';
+export interface ICEBiosStep {
+    /** 稳定 key（页面拿它做节点 id / 维护增量更新） */
+    key: string;
+    label: string;
+    detail: string;
+    /** 这一项「检测」要花多久（毫秒） */
+    duration: number;
+}
+export interface ICEBiosStepState extends ICEBiosStep {
+    state: 'pending' | 'running' | 'ok';
+    /** 当前项的进度 0..1；非当前项是 0 或 1 */
+    progress: number;
+}
+export interface ICEBiosCartridge {
+    key: string;
+    label: string;
+}
+export interface ICEBiosMenuEntry {
+    key: string;
+    label: string;
+    type: 'cartridge' | 'settings' | 'boot';
+}
+export interface ICEBiosSettings {
+    /** 开着就跳过菜单直接启动默认卡带（开机自检还是要跑） */
+    quickBoot: boolean;
+    defaultCartridge: string;
+}
+export declare type ICEBiosAction = {
+    type: 'boot';
+    cartridge: string;
+} | {
+    type: 'settings';
+} | {
+    type: 'menu';
+} | {
+    type: 'none';
+};
+export interface ICEBiosStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface ICEBiosOptions {
+    cartridges: ICEBiosCartridge[];
+    /** 自检项，默认 `ICE_BIOS_DEFAULT_STEPS` */
+    steps?: ICEBiosStep[];
+    /** 初始设置（优先级低于存储里的值） */
+    settings?: Partial<ICEBiosSettings>;
+    /** 存储实现；传 null 表示只放内存；不传则用 globalThis.localStorage（没有就退化成内存） */
+    storage?: ICEBiosStorage | null;
+    /** 存储键前缀，默认 `ice-arcade-bios-` */
+    prefix?: string;
+}
+export declare type ICEBiosListener = (model: ICEBiosModel) => void;
+/** 默认自检项：每一项都是一句「老式 BIOS 会印在屏幕上的话」。 */
+export declare const ICE_BIOS_DEFAULT_STEPS: ICEBiosStep[];
+export declare class ICEBiosModel {
+    private steps;
+    private cartridges;
+    private storage;
+    private storageKey;
+    private listeners;
+    private phase;
+    private elapsed;
+    private cursor;
+    private cursorBeforeSettings;
+    private settings;
+    constructor(options: ICEBiosOptions);
+    getPhase(): ICEBiosPhase;
+    getCartridges(): ICEBiosCartridge[];
+    getPostElapsed(): number;
+    /** 自检总时长（毫秒）。 */
+    getPostDuration(): number;
+    /** 自检进度 0..1（按时间算，页面拿它画进度条）。 */
+    getPostProgress(): number;
+    /** 自检项与它们此刻的状态（当前项 running、前面的 ok）。 */
+    getSteps(): ICEBiosStepState[];
+    /** 菜单项：卡带列表 + 设置 + 退出并启动。 */
+    getMenuEntries(): ICEBiosMenuEntry[];
+    getCursor(): number;
+    getSelectedEntry(): ICEBiosMenuEntry | null;
+    getSettings(): ICEBiosSettings;
+    isQuickBoot(): boolean;
+    getDefaultCartridge(): string;
+    /** 推进自检（页面每帧调用），返回是否发生了变化。 */
+    tick(delta: number): boolean;
+    moveCursor(delta: number): void;
+    setCursor(index: number): void;
+    /** 确认当前项：只返回动作，执行动作是页面的事（好测）。 */
+    confirm(): ICEBiosAction;
+    /** 返回上一层（设置 → 菜单）。 */
+    back(): void;
+    /** 从游戏里回到 BIOS 菜单（掌机的「复位」）。 */
+    openMenu(): void;
+    /** 重新跑一遍自检（再开一次机）。 */
+    restart(): void;
+    toggleQuickBoot(): boolean;
+    setDefaultCartridge(key: string): void;
+    addChangeListener(listener: ICEBiosListener): () => void;
+    private __alignCursorToDefault;
+    /** 卡带 key 必须真的存在，否则回退到第一个卡带。 */
+    private __normalizeCartridge;
+    private __load;
+    private __readStorage;
+    private __save;
+    private __defaultStorage;
+    private notify;
+}
+export default ICEBiosModel;

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

@@ -0,0 +1,45 @@
+/**
+ * 撤销 / 重做栈（纯逻辑，泛型）。
+ *
+ * 不是给某个画板专用的：任何「编辑 → 提交 → 后悔」的界面都能用（像素画板、看板、
+ * 表格编辑、表单草稿…），所以它只认泛型快照，不认识 canvas、颜色和数据结构。
+ *
+ * 约定：
+ * - `push(state)` 入栈并**清空 redo 栈** —— 从历史中间改一下，原来那条「未来」就作废了；
+ * - `undo()` / `redo()` 返回目标快照，到边界返回 `null`（调用方据此把按钮置灰）；
+ * - 超过 `limit` 丢**最旧**的一条（默认 50：够用，且内存不会无限涨）；
+ * - 变更通知带 `reason`（push / undo / redo / clear），页面按需刷新按钮态；
+ * - 快照的存取由调用方负责 `slice()` / 深拷贝 —— 栈只存引用，不做深拷贝（性能）。
+ */
+export declare type ICEHistoryReason = 'push' | 'undo' | 'redo' | 'clear';
+export declare type ICEHistoryListener<T> = (model: ICEHistoryModel<T>, reason: ICEHistoryReason) => void;
+export interface ICEHistoryOptions<T> {
+    /** 最多保留多少个**可撤销**的快照，默认 50 */
+    limit?: number;
+    /** 初始当前值（不占历史深度） */
+    initial?: T;
+}
+export declare class ICEHistoryModel<T> {
+    private limit;
+    /** 已提交的快照，最后一个就是当前值 */
+    private past;
+    private future;
+    private listeners;
+    constructor(options?: ICEHistoryOptions<T>);
+    getLimit(): number;
+    getCurrent(): T | null;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** 栈深：undo = 还能撤销几步，redo = 还能重做几步。 */
+    getDepth(): {
+        undo: number;
+        redo: number;
+    };
+    push(state: T): void;
+    undo(): T | null;
+    redo(): T | null;
+    clear(initial?: T): void;
+    addChangeListener(listener: ICEHistoryListener<T>): () => void;
+    private notify;
+}
+export default ICEHistoryModel;

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

@@ -0,0 +1,89 @@
+export interface ICEPixelModelOptions {
+    rows?: number;
+    cols?: number;
+    /** 调色板（`#rgb` / `#rrggbb`），下标就是画布上存的值；不传给一组默认色 */
+    palette?: string[];
+    /** 背景色下标，默认 0 */
+    background?: number;
+    /** 最多能撤销几步，默认 50 */
+    limit?: number;
+}
+export interface ICEPixelSVGOptions {
+    /** 每个像素在 SVG 里占多少单位，默认 16 */
+    cellSize?: number;
+    /** 是否画一层背景矩形，默认 true */
+    background?: boolean;
+}
+export declare type ICEPixelListener = (model: ICEPixelModel) => void;
+/** 默认调色板：Bootstrap 语义色 + 黑白灰（够画像素画，也不刺眼）。 */
+export declare const ICE_PIXEL_DEFAULT_PALETTE: string[];
+/** `#rgb` / `#rrggbb` → [r, g, b]；认不出来当黑色（画布上永远有个确定的结果）。 */
+export declare function icePixelParseColor(color: string): [number, number, number];
+export declare class ICEPixelModel {
+    private rows;
+    private cols;
+    private palette;
+    private background;
+    private cells;
+    private history;
+    private listeners;
+    private dirty;
+    constructor(options?: ICEPixelModelOptions);
+    getRows(): number;
+    getCols(): number;
+    getPalette(): string[];
+    getBackground(): number;
+    /** 画布副本（行优先）。 */
+    getCells(): number[];
+    getPixel(row: number, col: number): number;
+    /** 有没提交的改动（页面据此把「保存 / 导出」按钮点亮）。 */
+    isDirty(): boolean;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getHistoryDepth(): {
+        undo: number;
+        redo: number;
+    };
+    /**
+     * 画一个像素。返回「真的改了」—— 越界、颜色非法、值没变都返回 false，
+     * 这样页面可以放心地在拖动回调里调用它（不会刷出一堆无意义的重绘）。
+     */
+    setPixel(row: number, col: number, color: number): boolean;
+    /** Bresenham 直线（铅笔拖动、直线工具都走它）。 */
+    drawLine(row0: number, col0: number, row1: number, col1: number, color: number): boolean;
+    /**
+     * 直线经过的格子坐标（Bresenham）。
+     * 单独暴露出来是给**预览**用的：拖直线 / 拖矩形时先拿坐标点亮高亮层，松手才真正落笔。
+     */
+    getLineCells(row0: number, col0: number, row1: number, col1: number): Array<[number, number]>;
+    /** 矩形**描边**经过的格子坐标（和 drawRect 同一套口径，供预览用）。 */
+    getRectCells(row0: number, col0: number, row1: number, col1: number): Array<[number, number]>;
+    /** 矩形描边（只画框，不填内部）。 */
+    drawRect(row0: number, col0: number, row1: number, col1: number, color: number): boolean;
+    /**
+     * 四邻域油漆桶（迭代版，不用递归 —— 大画布上递归会爆栈）。
+     * 目标和填充色相同、或起点越界时返回 false。
+     */
+    fill(row: number, col: number, color: number): boolean;
+    /** 整块刷成某个颜色（清空 / 填充背景）。 */
+    clear(color?: number): boolean;
+    /** 换尺寸：重新铺一块空画布（旧内容不留，历史也重开）。 */
+    resize(rows: number, cols: number): void;
+    /** 把当前画布落一次历史（一次笔画 / 一次图形操作调用一次）。返回是否真的入了栈。 */
+    commit(): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    toSVG(options?: ICEPixelSVGOptions): string;
+    /** 给 `new ImageData(rgba, cols * scale, rows * scale)` 用的 RGBA 数组。 */
+    toRGBA(scale?: number): Uint8ClampedArray;
+    toJSON(): string;
+    /** 反序列化；坏数据抛错而不是静默给一块白板（导入失败得让人看见）。 */
+    static fromJSON(json: string): ICEPixelModel;
+    addChangeListener(listener: ICEPixelListener): () => void;
+    private __inside;
+    /** 非法下标一律当背景：画布上永远只有调色板里真实存在的颜色。 */
+    private __normalizeColor;
+    private __restore;
+    private notify;
+}
+export default ICEPixelModel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ice-web-components",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Swing-style Canvas UI components built on ice-render.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -22,6 +22,7 @@
     "qa:workbench": "node scripts/qa-workbench.mjs",
     "qa:xp": "node scripts/qa-xp.mjs",
     "qa:arcade": "node scripts/qa-arcade.mjs",
+    "qa:pixel": "node scripts/qa-pixel.mjs",
     "docs:api": "node scripts/gen-docs.mjs",
     "docs:check": "node scripts/check-docs.mjs",
     "docs": "npm run docs:api && npm run docs:check",