ice-web-components 1.0.0

package/dist/types/core/ICEMessageManager.d.ts

@@ -0,0 +1,80 @@
+import { ICEWidget } from './ICEWidget';
+import { ICEEasing, ICEFrameDriver } from '../util/ICEAnimation';
+/**
+ * 全局提示（Message / Notification）。
+ *
+ * - 消息挂在**独立的工具层容器**上，与浮层系统解耦：打开 Modal / Popover 不会清掉消息，
+ *   消息也不参与浮层的 exclusive 关闭；
+ * - `show()` 顶部居中堆叠（Ant 的 message），`notification()` 右下角倒序堆叠；
+ * - duration 到期自动淡出后移除（0 表示常驻）；每条消息返回 handle 可单独关闭。
+ */
+export declare type ICEMessageType = 'info' | 'success' | 'warning' | 'error' | 'loading';
+export interface ICEMessageOptions {
+    text: string;
+    type?: ICEMessageType;
+    /** 毫秒；0 表示不自动消失（默认 3000） */
+    duration?: number;
+    /** 关闭后回调 */
+    onClose?: () => void;
+    animation?: {
+        duration?: number;
+        delay?: number;
+        easing?: ICEEasing;
+        driver?: ICEFrameDriver;
+    };
+}
+export interface ICENotificationOptions {
+    title: string;
+    description?: string;
+    type?: ICEMessageType;
+    duration?: number;
+    onClose?: () => void;
+    animation?: {
+        duration?: number;
+        delay?: number;
+        easing?: ICEEasing;
+        driver?: ICEFrameDriver;
+    };
+}
+export interface ICEMessageHandle {
+    close(): void;
+    isOpen(): boolean;
+    getNode(): any;
+}
+export declare class ICEMessageManager {
+    private ice;
+    private layer;
+    private entries;
+    private bound;
+    constructor(ice: any);
+    /** 幂等：创建消息容器（挂 ICE 工具层）。 */
+    start(): this;
+    stop(): this;
+    getLayer(): ICEWidget | null;
+    /** 顶部居中消息。 */
+    show(options: ICEMessageOptions): ICEMessageHandle;
+    /** 右下角通知（带标题、说明与关闭按钮）。 */
+    notification(options: ICENotificationOptions): ICEMessageHandle;
+    closeAll(): void;
+    isOpen(): boolean;
+    private __push;
+    private __closeEntry;
+    /** 顶部居中：自上而下；右下角：自下而上。 */
+    private __relayout;
+    private __typeColor;
+    private __typeIcon;
+}
+export declare function getICEMessageManager(ice: any): ICEMessageManager;
+/** 便捷入口：`ICEMessage.success(ice, '已保存')`。 */
+export declare const ICEMessage: {
+    show(ice: any, text: string, options?: Omit<ICEMessageOptions, 'text'>): ICEMessageHandle;
+    success(ice: any, text: string, options?: Omit<ICEMessageOptions, 'text' | 'type'>): ICEMessageHandle;
+    error(ice: any, text: string, options?: Omit<ICEMessageOptions, 'text' | 'type'>): ICEMessageHandle;
+    warning(ice: any, text: string, options?: Omit<ICEMessageOptions, 'text' | 'type'>): ICEMessageHandle;
+    info(ice: any, text: string, options?: Omit<ICEMessageOptions, 'text' | 'type'>): ICEMessageHandle;
+    loading(ice: any, text: string, options?: Omit<ICEMessageOptions, 'text' | 'type'>): ICEMessageHandle;
+};
+/** 便捷入口：`ICENotification.open(ice, { title, description })`。 */
+export declare const ICENotification: {
+    open(ice: any, options: ICENotificationOptions): ICEMessageHandle;
+};

package/dist/types/core/ICEOverlayManager.d.ts

@@ -0,0 +1,92 @@
+import { ICEOverlayPlacement } from '../util/ICEOverlayPosition';
+import { ICEEasing, ICEFrameDriver } from '../util/ICEAnimation';
+/**
+ * 弹层/浮层底座。
+ *
+ * 所有需要「浮在其它组件之上」的组件（Modal、Dropdown、Select、Tooltip、Popover、
+ * 右键菜单…）都走这一层，避免每个组件各自实现锚点定位、z 序、点外关闭、Esc 关闭。
+ *
+ * 实现要点：
+ * - 浮层根节点挂在 **ICE 的工具层**（`ice.addTool`）：工具层会被递归渲染、绘制在所有
+ *   组件之上，且不参与 getComponentById 查找；根节点 `interactive:false`，所以它自身
+ *   不会被命中，只有浮层内容可交互。
+ * - 浮层内容是根节点的子组件，位置由 `resolveICEOverlayPosition()` 按锚点世界盒算出来
+ *   （支持 12 种 placement、空间不足自动翻转、夹进可见范围；带视口缩放/平移也正确）。
+ * - 关闭：点击浮层与锚点之外、Esc、或调用 handle.close()。
+ */
+export declare type ICEOverlayCloseReason = 'api' | 'outside' | 'esc' | 'exclusive';
+export interface ICEOverlayOptions {
+    /** 触发组件（浮层贴着它定位）；用 `centered` 时可省略 */
+    anchor?: any;
+    /** 居中放置（不依赖锚点）—— Modal / Drawer 这类全屏浮层用 */
+    centered?: boolean;
+    /** 浮层内容组件；所有权交给管理器 —— 关闭时会被移除并销毁 */
+    content: any;
+    placement?: ICEOverlayPlacement;
+    offset?: number;
+    padding?: number;
+    flip?: boolean;
+    /** 点击浮层与锚点之外时关闭（默认 true） */
+    closeOnOutsideClick?: boolean;
+    /** 按下 Esc 时关闭（默认 true） */
+    closeOnEsc?: boolean;
+    /** 打开时先关闭其它浮层（默认 true） */
+    exclusive?: boolean;
+    /**
+     * 键盘接管：该浮层打开期间，方向键/Enter/Space 归它处理，
+     * ICEFocusManager 不再把 Enter/Space 当作「激活当前焦点控件」（否则会先点掉触发按钮）。
+     */
+    keyboardCaptured?: boolean;
+    /**
+     * 阻断型浮层（Modal 的遮罩）：z 序在最上，且**不会被后来打开的非阻断浮层关掉**
+     * （否则鼠标扫过页面触发 Tooltip 就会把模态一起关掉）。
+     */
+    blocking?: boolean;
+    /** 入场动效：none（默认）/ fade / scale（淡入 + 轻微放大） */
+    enterAnimation?: 'none' | 'fade' | 'scale';
+    /** 出场动效：none（默认，立即移除）/ fade（淡出后再移除） */
+    exitAnimation?: 'none' | 'fade';
+    /** 动效参数（时长/缓动/帧驱动，测试可注入 driver） */
+    animation?: {
+        duration?: number;
+        delay?: number;
+        easing?: ICEEasing;
+        driver?: ICEFrameDriver;
+    };
+    onClose?: (reason: ICEOverlayCloseReason) => void;
+}
+export interface ICEOverlayHandle {
+    close(): void;
+    isOpen(): boolean;
+    /** 锚点移动 / 内容尺寸变化后重算位置 */
+    update(): void;
+}
+export declare class ICEOverlayManager {
+    private ice;
+    private layer;
+    private entries;
+    private bound;
+    constructor(ice: any);
+    /**
+     * 幂等：创建浮层根节点（挂到 ICE 工具层）并绑定关闭事件。
+     * `open()` 会自动调用，通常不需要手动调。
+     */
+    start(): this;
+    /** 解绑并移除浮层根节点（关闭所有浮层）。 */
+    stop(): this;
+    open(options: ICEOverlayOptions): ICEOverlayHandle;
+    close(handle: ICEOverlayHandle, reason?: ICEOverlayCloseReason): void;
+    closeAll(reason?: ICEOverlayCloseReason): void;
+    isOpen(): boolean;
+    /** 是否有浮层正在接管键盘（见 ICEOverlayOptions.keyboardCaptured）。 */
+    isKeyboardCaptured(): boolean;
+    getLayer(): any;
+    private __destroyEntry;
+    private __place;
+    /** 可见世界矩形（含视口缩放/平移）；拿不到视口信息时退回画布尺寸。 */
+    private __visibleWorldRect;
+    private __markDirty;
+    private __onMouseDown;
+    private __onKeyDown;
+}
+export declare function getICEOverlayManager(ice: any): ICEOverlayManager;

package/dist/types/core/ICEPainter.d.ts

@@ -0,0 +1,12 @@
+import type { ICEThemeTokens } from '../theme/ICETheme';
+export interface ICEPaintContext {
+    ctx: any;
+    theme: ICEThemeTokens;
+    component: any;
+}
+export interface ICEPainter {
+    install?(component: any): void;
+    uninstall?(component: any): void;
+    getPreferredSize?(component: any): [number, number];
+    paint(context: ICEPaintContext): void;
+}

package/dist/types/core/ICEWidget.d.ts

@@ -0,0 +1,86 @@
+import { ICEGroup } from 'ice-render';
+import type { ICEPainter } from './ICEPainter';
+/**
+ * 所有 UI 组件的基类（继承引擎 ICEGroup）。
+ *
+ * 在引擎的绘制能力之上只加四件事：交互态（enabled / hovered / focused）、键盘焦点
+ * （`focusable` / `activate()`）、表单校验态（`validateStatus`）、表单取值约定
+ * （`getFormValue` / `setFormValue`）。
+ */
+export declare class ICEWidget extends ICEGroup {
+    protected painter: ICEPainter | null;
+    protected preferredWidth: number;
+    protected preferredHeight: number;
+    protected enabled: boolean;
+    protected hovered: boolean;
+    /**
+     * 是否参与键盘焦点轮转（Tab）。默认 false：容器与展示类组件不该拿到焦点，
+     * 控件在自己的构造函数里置 true；调用方也可用 `props.focusable` 覆盖。
+     */
+    protected focusable: boolean;
+    protected focused: boolean;
+    /** 表单校验状态（由 ICEFormItem 设置；控件可覆盖 __applyValidateState 做视觉反馈） */
+    protected validateStatus: 'default' | 'error' | 'warning' | 'success';
+    /**
+     * 焦点环策略（`:focus-visible` 的语义）：
+     * - `keyboard`（默认）：只有键盘（Tab / Shift+Tab）聚焦才画环 —— 鼠标点一下按钮、
+     *   拖一下滑块都冒蓝框会很怪；
+     * - `always`：鼠标聚焦也画环（文本类控件需要「正在输入」的反馈）；
+     * - `never`：从不画。
+     */
+    protected focusRingMode: 'keyboard' | 'always' | 'never';
+    constructor(props?: any);
+    getFocusRingMode(): 'keyboard' | 'always' | 'never';
+    setFocusRingMode(mode: 'keyboard' | 'always' | 'never'): this;
+    /** 按聚焦来源判断要不要画焦点环（ICEFocusManager 调用）。 */
+    shouldShowFocusRing(origin: 'mouse' | 'keyboard' | 'api'): boolean;
+    setEnabled(enabled: boolean): this;
+    /**
+     * 无障碍：可读名称。
+     *
+     * 引擎的 a11y 快照优先读 `state.ariaLabel`（见 ice-render 的 `a11y/accessibility.ts`），
+     * 拿不到才回退到文本 / id。控件应当给出有意义的名称（按钮用文字、输入框用占位符……），
+     * 否则屏幕阅读器会念出一串 id。
+     */
+    setAriaLabel(label: string): this;
+    getAriaLabel(): string;
+    isEnabled(): boolean;
+    isHovered(): boolean;
+    /**
+     * 是否可聚焦：显式声明 + 启用 + 可交互 + 最终可见（祖先 display:false 时不可聚焦）。
+     */
+    isFocusable(): boolean;
+    setFocusable(focusable: boolean): this;
+    isFocused(): boolean;
+    /** 由 ICEFocusManager 调用；默认只记录状态（视觉表现由焦点环负责，子类可覆盖）。 */
+    setFocused(focused: boolean): this;
+    /**
+     * 键盘激活（Enter / Space）。默认等价于一次 click；
+     * 有自己语义的控件（勾选、开关、单选）覆盖成对应的切换动作。
+     */
+    activate(): void;
+    protected __applyFocusState(): void;
+    getValidateStatus(): 'default' | 'error' | 'warning' | 'success';
+    setValidateStatus(status: 'default' | 'error' | 'warning' | 'success'): this;
+    /** 校验状态变化后的视觉反馈钩子（默认不变，控件按需覆盖）。 */
+    protected __applyValidateState(): void;
+    /**
+     * 表单取值约定：控件覆盖这两个方法即可被 ICEForm 直接读写。
+     * 默认读写 `state.value`（对没有值语义的组件无害）。
+     */
+    getFormValue(): any;
+    setFormValue(value: any): void;
+    setHovered(hovered: boolean): this;
+    setPreferredSize(width: number, height: number): this;
+    getPreferredSize(): [number, number];
+    setPainter(painter: ICEPainter | null): this;
+    getPainter(): ICEPainter | null;
+    protected __applyHoverState(): void;
+    /**
+     * UI 组件内部的图元只负责外观，不参与画布级拖拽、变换、连线。
+     * 只有真正的 UI 组件（ICEWidget）保留自己的交互配置。
+     */
+    addChild(child: any, markDirty?: boolean): void;
+    revalidate(): this;
+    protected theme(): import("..").ICEThemeTokens;
+}

package/dist/types/i18n/ICEI18n.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 国际化（i18n）：把组件里写死的内置文案收进可切换的语言包。
+ *
+ * ```ts
+ * import { setICELocale, t } from 'ice-web-components';
+ * setICELocale('en-US');        // 之后新建/重排的组件用英文文案
+ * t('table.empty');             // 'No data'
+ * t('pagination.total', { total: 42 });   // '42 in total'
+ * ```
+ *
+ * 约定：
+ * - 默认语言 `zh-CN`；内置 `en-US`；`registerICELocale()` 可以加自己的包；
+ * - `t(key, vars)` 的兜底链：**当前语言 → 默认语言 → key 本身**（永远有东西可显示）；
+ * - 组件在「构造 / 重排」时读文案，所以切语言之后需要重建组件或触发一次重排；
+ * - `setICELocale()` 只认注册过的语言，没注册过就忽略（不抛异常、也不切换）。
+ */
+export declare type ICELocaleMessages = Record<string, string>;
+/** 默认语言。 */
+export declare const ICE_DEFAULT_LOCALE = "zh-CN";
+/** 内置中文包（组件的默认文案）。 */
+export declare const ICE_LOCALE_ZH_CN: ICELocaleMessages;
+/** 内置英文包。 */
+export declare const ICE_LOCALE_EN_US: ICELocaleMessages;
+/** 注册（或覆盖）一个语言包。 */
+export declare function registerICELocale(locale: string, messages: ICELocaleMessages): void;
+/** 切换语言；未注册的语言会被忽略。 */
+export declare function setICELocale(locale: string): void;
+export declare function getICELocale(): string;
+export declare function getICELocaleNames(): string[];
+/** 取当前语言的完整包（拷贝，避免外部改坏内置包）。 */
+export declare function getICELocaleMessages(locale?: string): ICELocaleMessages;
+/**
+ * 取文案：当前语言 → 默认语言 → key 本身；`{name}` 会被 `vars` 里的值替换。
+ */
+export declare function t(key: string, vars?: Record<string, string | number>): string;

package/dist/types/index.d.ts

@@ -0,0 +1,111 @@
+export * from './theme/ICETheme';
+export * from './theme/ICEArcadeTheme';
+export * from './core/ICEManager';
+export * from './core/ICEHoverManager';
+export * from './core/ICEPainter';
+export * from './core/ICEOverlayManager';
+export * from './core/ICEFocusManager';
+export * from './core/ICEMessageManager';
+export * from './core/ICEWidget';
+export * from './core/ICEContainer';
+/**
+ * 布局类（`ICEFlowLayout` / `ICEBoxLayout` / `ICELayoutManager`）**不在这里再导出**：
+ * 它们本来就是 `ice-render` 的东西，用户直接从 `ice-render` 取。
+ * 这样本包的导出集合与引擎完全不重叠，「同时 import 两个包」永远不会撞名。
+ */
+export * from './util/ICEOverlayPosition';
+export * from './util/ICEWorldBox';
+export * from './util/ICEAnimation';
+export * from './util/ICEDragReorder';
+export * from './util/ICEAccessibilityMirror';
+export * from './i18n/ICEI18n';
+export * from './util/ICEStyle';
+export * from './components/ICELabel';
+export * from './components/ICEButton';
+export * from './components/ICEPanel';
+export * from './components/ICEBadge';
+export * from './components/ICETag';
+export * from './components/ICETooltip';
+export * from './components/ICEPopover';
+export * from './components/ICEPopconfirm';
+export * from './components/ICEModal';
+export * from './components/ICEPagination';
+export * from './components/ICEDropdown';
+export * from './components/ICESelect';
+export * from './components/ICEDrawer';
+export * from './components/ICEList';
+export * from './components/ICETree';
+export * from './components/ICESegmented';
+export * from './components/ICEEmpty';
+export * from './components/ICESkeleton';
+export * from './components/ICECollapse';
+export * from './components/ICEDescriptions';
+export * from './components/ICETimeline';
+export * from './components/ICESpin';
+export * from './components/ICERate';
+export * from './components/ICESteps';
+export * from './components/ICEResult';
+export * from './components/ICEInputNumber';
+export * from './components/ICEAutoComplete';
+export * from './components/ICETreeSelect';
+export * from './components/ICECascader';
+export * from './components/ICETransfer';
+export * from './components/ICEUpload';
+export * from './components/ICECarousel';
+export * from './components/ICEDatePicker';
+export * from './components/ICETimePicker';
+export * from './components/ICEComment';
+export * from './components/ICEColorPicker';
+export * from './components/ICEImageView';
+export * from './components/ICEAvatar';
+export * from './components/ICEAvatarGroup';
+export * from './components/ICEIcon';
+export * from './components/ICESvgIcon';
+export * from './components/ICESeparator';
+export * from './components/ICECheckBox';
+export * from './components/ICERadioButton';
+export * from './components/ICESwitch';
+export * from './components/ICEProgressBar';
+export * from './components/ICESlider';
+export * from './components/ICEScrollPane';
+export * from './components/ICEFormItem';
+export * from './components/ICEForm';
+export * from './components/ICECard';
+export * from './components/ICETabs';
+export * from './components/ICETextField';
+export * from './components/ICETextArea';
+export * from './components/ICEPasswordField';
+export * from './components/ICEAlert';
+export * from './components/ICETable';
+export * from './components/ICEMenu';
+export * from './components/ICEStatCard';
+export * from './components/ICEStatistic';
+export * from './components/ICEBreadcrumb';
+export * from './components/ICERadioGroup';
+export * from './components/ICECheckboxGroup';
+export * from './components/ICESplitter';
+export * from './components/ICEWatermark';
+export * from './components/ICETileMap';
+export * from './components/ICEVirtualList';
+export * from './components/ICEKanban';
+export * from './components/ICETypography';
+export * from './components/ICEBackTop';
+export * from './components/ICEAnchor';
+export * from './components/ICEImagePreview';
+export * from './components/ICETour';
+export * from './components/ICECalendar';
+export * from './components/ICEWindow';
+export * from './components/ICEIconTile';
+export * from './components/ICESpace';
+export * from './components/ICEGrid';
+export * from './components/ICEFloatButton';
+export * from './model/ICEButtonModel';
+export * from './model/ICEToggleModel';
+export * from './model/ICEBoundedRangeModel';
+export * from './model/ICEFormModel';
+export * from './model/ICESelectionModel';
+export * from './model/ICEMinesweeperModel';
+export * from './model/ICETetrisModel';
+export * from './model/ICESnakeModel';
+export * from './model/ICEHighScoreModel';
+export * from './model/ICE2048Model';

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

@@ -0,0 +1,90 @@
+/**
+ * 2048 的纯逻辑模型（不碰 canvas）。
+ *
+ * 规则按经典的 Gabriele Cirulli 版 2048：
+ * - 开局两个块，值只能是 2 或 4（4 的概率由 `spawnFourChance` 控制，默认 10%）；
+ * - `move(dir)` 把整盘往一个方向推：**同一次移动里每个块最多合并一次** ——
+ *   `2,2,2,2` 往左是 `4,4`（不是 `8`），`2,2,4` 往左是 `4,4`（新合出来的 4 不会再吞掉后面的 4）；
+ * - 合并得分 = 合并出来的值（4+4→8 得 8 分）；
+ * - **只有真的动了才生成新块、才计一步**：推不动的方向返回 `false`，什么都不变；
+ * - 棋盘填满且相邻无可合并 → game over；合并出 `target`（默认 2048）即 `isWon`，
+ *   但**不结束**，可以继续冲高分；
+ * - 新块位置由注入的 `random` 决定，测试可复现；`spawnAfterMove: false` 是「不刷新」的练习模式。
+ */
+/** 四个方向。 */
+export declare type ICE2048Direction = 'up' | 'right' | 'down' | 'left';
+/** 按上、右、下、左顺序排列（UI 画方向提示可以直接用）。 */
+export declare const ICE_2048_DIRECTIONS: ICE2048Direction[];
+export declare type ICE2048Cell = number | null;
+export interface ICE2048Options {
+    rows?: number;
+    cols?: number;
+    /** 随机源（0..1），默认 `Math.random` */
+    random?: () => number;
+    /** 合并出这个值算赢，默认 2048 */
+    target?: number;
+    /** 新块是 4 的概率，默认 0.1（其余是 2） */
+    spawnFourChance?: number;
+    /** 移动成功后是否生成新块，默认 true（关掉就是练习模式，便于测试断言整盘） */
+    spawnAfterMove?: boolean;
+}
+export declare type ICE2048Listener = (model: ICE2048Model) => void;
+export declare class ICE2048Model {
+    private rows;
+    private cols;
+    private random;
+    private target;
+    private spawnFourChance;
+    private spawnAfterMove;
+    private cells;
+    private score;
+    private moves;
+    private won;
+    private gameOver;
+    private paused;
+    /** 上一次移动里「合并落在哪几格」（UI 拿它做高亮 / 特效） */
+    private lastMerged;
+    private listeners;
+    constructor(options?: ICE2048Options);
+    getRows(): number;
+    getCols(): number;
+    /** 一维盘面（行优先），空格是 null。 */
+    getCells(): ICE2048Cell[];
+    getCell(row: number, col: number): ICE2048Cell;
+    getScore(): number;
+    getMoves(): number;
+    getTarget(): number;
+    /** 盘面上最大的块（空盘为 0）。 */
+    getBestTile(): number;
+    isWon(): boolean;
+    isGameOver(): boolean;
+    isPaused(): boolean;
+    /** 上一次移动发生合并的格子（`[row, col]`）；没合并就是空数组。 */
+    getLastMerged(): Array<[number, number]>;
+    /** 暂停：棋盘类页面（掌机）共用同一套 pause/resume 契约，这里暂停只挡输入。 */
+    pause(): void;
+    resume(): void;
+    /** 还有没有任何一个方向推得动。 */
+    canMove(): boolean;
+    addChangeListener(listener: ICE2048Listener): () => void;
+    /** 往一个方向推；推得动才返回 true（并计一步、生成新块）。 */
+    move(direction: ICE2048Direction): boolean;
+    /** 重置：可只覆盖部分选项。 */
+    reset(options?: ICE2048Options): void;
+    /** 直接摆盘（长度必须等于 rows*cols，否则抛）。 */
+    setCellsForTest(cells: ICE2048Cell[]): void;
+    private __resetBoard;
+    /** 在随机空格里放一个块：值 = 4 的概率由 spawnFourChance 控制。 */
+    private __spawnTile;
+    private __lineCount;
+    /**
+     * 第 index 条线在给定方向下的**遍历顺序**（始终是「先碰到的在前」）：
+     * 向左：从左到右；向右：从右到左；向上：从上到下；向下：从下到上。
+     */
+    private __lineIndices;
+    /** 只算「推得动吗」，不改盘面（复制一份跑一遍）。 */
+    private __wouldMove;
+    /** 满盘且四邻都没有相同的块 → 结束。 */
+    private __refreshGameOver;
+    private notify;
+}

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

@@ -0,0 +1,20 @@
+export declare type ICEBoundedRangeModelListener = (model: ICEBoundedRangeModel) => void;
+export declare class ICEBoundedRangeModel {
+    private value;
+    private min;
+    private max;
+    private listeners;
+    constructor(options?: {
+        value?: number;
+        min?: number;
+        max?: number;
+    });
+    getValue(): number;
+    getMinimum(): number;
+    getMaximum(): number;
+    setValue(value: number): this;
+    addChangeListener(listener: ICEBoundedRangeModelListener): this;
+    removeChangeListener(listener: ICEBoundedRangeModelListener): this;
+    private __clamp;
+    private __notify;
+}

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

@@ -0,0 +1,16 @@
+export declare type ICEButtonModelListener = (model: ICEButtonModel) => void;
+export declare class ICEButtonModel {
+    private enabled;
+    private pressed;
+    private listeners;
+    constructor(options?: {
+        enabled?: boolean;
+    });
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): this;
+    isPressed(): boolean;
+    setPressed(pressed: boolean): this;
+    addChangeListener(listener: ICEButtonModelListener): this;
+    removeChangeListener(listener: ICEButtonModelListener): this;
+    private __notify;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * 表单校验模型：字段值 + 规则 + 错误 + 变更通知。
+ *
+ * 纯逻辑、不碰 canvas —— UI 层（ICEFormItem / ICEForm）只负责把值与错误**画出来**。
+ * 规则语义：一条规则失败即停止（取第一条错误信息）。
+ */
+export interface ICEFormRule {
+    /** 必填：null/undefined/空串/空数组/false 都算缺失（开关与多选同样适用） */
+    required?: boolean;
+    /** 自定义错误文案（不填用默认文案） */
+    message?: string;
+    /** 数值下界 / 上界（值可转成数字时生效） */
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    /** 自定义校验：返回错误文案表示失败，返回 null/undefined 表示通过 */
+    validator?: (value: any, values: Record<string, any>) => string | null | undefined;
+    /**
+     * 异步校验（如「用户名是否被占用」）。
+     *
+     * 只在显式调用 `validateFieldAsync` / `validateAsync` 时执行 —— 值变化触发的自动校验
+     * 只跑同步规则，避免每次按键都发请求。
+     */
+    asyncValidator?: (value: any, values: Record<string, any>) => Promise<string | null | undefined>;
+}
+export interface ICEFormFieldOptions {
+    name: string;
+    label?: string;
+    rules?: ICEFormRule[];
+    /**
+     * 依赖的字段名：**这些字段变化时本字段自动重算**。
+     * 典型场景「确认密码」「结束日期 ≥ 开始日期」——本字段的合法性取决于别的字段。
+     */
+    dependencies?: string[];
+    value?: any;
+}
+export interface ICEFormModelOptions {
+    /** 改值时是否自动重算该字段（默认 change；'none' 表示只在手动校验时算） */
+    validateTrigger?: 'change' | 'none';
+}
+export declare type ICEFormModelListener = (model: ICEFormModel) => void;
+interface ICEFormField {
+    name: string;
+    label: string;
+    rules: ICEFormRule[];
+    dependencies: string[];
+    value: any;
+    initialValue: any;
+    error: string | null;
+    validating: boolean;
+}
+export declare class ICEFormModel {
+    private fields;
+    private listeners;
+    private validateTrigger;
+    constructor(options?: ICEFormModelOptions);
+    addField(options: ICEFormFieldOptions): this;
+    removeField(name: string): this;
+    getField(name: string): ICEFormField | undefined;
+    getFieldNames(): string[];
+    /** 直接依赖 `name` 的字段（反向查询）。 */
+    getDependents(name: string): string[];
+    getLabel(name: string): string;
+    getValue(name: string): any;
+    getValues(): Record<string, any>;
+    /**
+     * 设置字段值。默认按 `validateTrigger` 决定是否立刻重算该字段（默认重算），
+     * `silent: true` 表示只写值、不重算也不通知（批量初始化用）。
+     */
+    setValue(name: string, value: any, options?: {
+        silent?: boolean;
+    }): this;
+    setValues(values: Record<string, any>, options?: {
+        silent?: boolean;
+    }): this;
+    /** 依赖 `name` 的字段重算（静默：调用方统一 __notify）。 */
+    private __validateDependents;
+    getError(name: string): string | null | undefined;
+    /** 只返回有错误的字段（无错误时为空对象） */
+    getErrors(): Record<string, string>;
+    hasErrors(): boolean;
+    /** 校验单个字段并写回错误；返回错误文案（null 表示通过）。 */
+    validateField(name: string, options?: {
+        silent?: boolean;
+    }): string | null;
+    /** 校验全部字段并返回是否全部通过。 */
+    validate(): boolean;
+    /** 该字段是否正在异步校验中（UI 可显示「校验中…」）。 */
+    isValidating(name: string): boolean;
+    /**
+     * 单字段异步校验：先跑同步规则（失败即短路、不发请求），再依次跑异步校验器。
+     * 返回错误文案（null 表示通过）。
+     */
+    validateFieldAsync(name: string): Promise<string | null>;
+    /** 校验全部字段（同步 + 异步），返回是否全部通过。 */
+    validateAsync(): Promise<boolean>;
+    /** 回到初始值并清空错误。 */
+    reset(): this;
+    addChangeListener(listener: ICEFormModelListener): () => void;
+    private __check;
+    private __notify;
+}
+export {};