ice-web-components 1.0.0 → 1.2.0

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

@@ -108,4 +108,7 @@ export * from './model/ICEMinesweeperModel';
 export * from './model/ICETetrisModel';
 export * from './model/ICESnakeModel';
 export * from './model/ICEHighScoreModel';
+export * from './model/ICEChip8Model';
 export * from './model/ICE2048Model';
+export * from './model/ICEHistoryModel';
+export * from './model/ICEPixelModel';

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

@@ -0,0 +1,86 @@
+/**
+ * CHIP-8 虚拟机（纯逻辑，不碰 canvas）。
+ *
+ * 掌机的第四块卡带用它：前三个模型是"某款游戏的规则"，这是一个**真的微处理器模拟器**——
+ * 4KB 内存、16 个 8 位寄存器、16 位地址寄存器 I、64×32 单色显存、两个 60Hz 定时器、16 键键盘。
+ * 画面交给 `ICETileMap`（2048 格仍然只有 1 个节点）画，音效走掌机那套 WebAudio。
+ *
+ * 支持指令（跑 demo / 小 ROM 足够）：00E0 / 00EE / 1NNN / 2NNN / 3XNN / 4XNN / 5XY0 / 9XY0 /
+ * 6XNN / 7XNN / 8XY0-8XYE / 9XY0 / ANNN / BNNN / CXNN / DXYN / EX9E / EXA1 / FX07 / FX0A /
+ * FX15 / FX18 / FX1E / FX29 / FX33 / FX55 / FX65。
+ */
+export declare const ICE_CHIP8_KEYS: readonly ["1", "2", "3", "C", "4", "5", "6", "D", "7", "8", "9", "E", "A", "0", "B", "F"];
+/**
+ * 自带的 demo ROM（自写，不依赖任何外部 ROM，避开版权）。
+ *
+ * 它做的事：清屏 → 在 (V0,V1) 画一个 8×8 笑脸 → 按 (V2,V3) 走一步 → 撞到边就把速度取反 → 跳回清屏重画。
+ * 也就是**在屏幕里来回弹**的笑脸：既不会裂到对边，也把条件跳过（4XNN）、补码减法（7XNN / 6XNN 的 0xFE）
+ * 和自建循环这几条最常用的指令演了一遍。
+ * 地址：程序 0x200 起（20 条指令 = 40 字节），精灵数据在 0x228（8 字节）。
+ */
+export declare const ICE_CHIP8_DEMO_ROM: number[];
+export declare const ICE_CHIP8_WIDTH = 64;
+export declare const ICE_CHIP8_HEIGHT = 32;
+/** 状态变化通知（掌机外壳拿它驱动重绘，和另外三个游戏模型是同一套契约）。 */
+export declare type ICEChip8Listener = (model: ICEChip8Model) => void;
+export declare class ICEChip8Model {
+    private memory;
+    private v;
+    private i;
+    private pc;
+    private sp;
+    private stack;
+    private display;
+    private keys;
+    private delay;
+    private sound;
+    private cycles;
+    private random;
+    private paused;
+    /** 本条指令改了显存 → 执行完统一通知一次（别在 600 条/秒的频率上惊动渲染） */
+    private displayDirty;
+    private listeners;
+    /** FX0A 正在等按键时记住键位寄存器 */
+    private waitingForKey;
+    constructor(options?: {
+        random?: () => number;
+    });
+    getPC(): number;
+    getI(): number;
+    getV(index: number): number;
+    getDisplay(): Uint8Array;
+    getPixel(row: number, col: number): number;
+    getDelayTimer(): number;
+    getSoundTimer(): number;
+    getCycles(): number;
+    isWaitingForKey(): boolean;
+    memoryRead(address: number): number;
+    isKeyDown(index: number): boolean;
+    /** 暂停中（调试/切走标签页）：`step()` 与 `tickTimers()` 都不推进。 */
+    isPaused(): boolean;
+    /** VM 没有"输赢"，但掌机外壳按统一契约询问，这里老实回答"没结束"。 */
+    isGameOver(): boolean;
+    pause(): void;
+    resume(): void;
+    /**
+     * 订阅状态变化：显存画了新东西、按键变了、定时器走了、机器复位了都会通知。
+     * 返回取消订阅的函数（和其它模型一致）。
+     */
+    addChangeListener(listener: ICEChip8Listener): () => void;
+    loadProgram(bytes: ArrayLike<number>, address?: number): void;
+    memoryWrite(address: number, value: number): void;
+    setKey(index: number, down: boolean): void;
+    /** 清掉所有按键（切卡带/失焦时用）。 */
+    clearKeys(): void;
+    setVForTest(index: number, value: number): void;
+    reset(): void;
+    /** 60Hz：递减延时/声音定时器。 */
+    tickTimers(): void;
+    /** 执行一条指令（FX0A 等按键时 PC 不动，直接返回）。 */
+    step(): void;
+    private notify;
+    private __alu;
+    /** DXYN：按位异或画精灵；撞到亮点就把 VF 置 1。 */
+    private __draw;
+    private __misc;
+}

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.0.0",
+  "version": "1.2.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",