ice-web-components 1.0.0

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

@@ -0,0 +1,65 @@
+import { ICEWidget } from '../core/ICEWidget';
+import { ICELabel } from './ICELabel';
+import type { ICEFormRule } from '../model/ICEFormModel';
+/**
+ * 表单项：标签 + 控件 + 错误文案。
+ *
+ * 只负责「摆位置 + 显示错误」；值的读写与校验规则由 ICEForm / ICEFormModel 管。
+ * 控件必须实现取值约定（`getFormValue` / `setFormValue`）。
+ *
+ * 布局：
+ * - `vertical`（默认）：标签在上一行，控件居中，错误文案在最下（高度预留，避免校验时抖动）；
+ * - `horizontal`：标签占左侧 labelWidth，控件与错误文案在右侧。
+ */
+export interface ICEFormItemOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    name: string;
+    label?: string;
+    control: any;
+    /** 校验规则（透传给 ICEFormModel） */
+    rules?: ICEFormRule[];
+    /**
+     * 依赖的字段名：这些字段变化时本项自动重算（跨字段校验，如「确认密码」）。
+     * 透传给 ICEFormModel。
+     */
+    dependencies?: string[];
+    layout?: 'vertical' | 'horizontal';
+    labelWidth?: number;
+    width?: number;
+    /** 标签行高 / 错误行高 / 间距 */
+    labelHeight?: number;
+    errorHeight?: number;
+    gap?: number;
+}
+export declare class ICEFormItem extends ICEWidget {
+    private name;
+    private labelText;
+    private control;
+    private rules;
+    private dependencies;
+    private validating;
+    private itemLayout;
+    private labelWidth;
+    private labelHeight;
+    private errorHeight;
+    private itemGap;
+    private labelNode;
+    private errorNode;
+    constructor(props: ICEFormItemOptions);
+    getName(): string;
+    getLabel(): string;
+    getRules(): ICEFormRule[];
+    /** 依赖的字段名（跨字段重校验用）。 */
+    getDependencies(): string[];
+    getControl(): any;
+    getLabelNode(): ICELabel;
+    getErrorNode(): ICELabel;
+    getErrorText(): string;
+    isValidating(): boolean;
+    /** 异步校验中：错误行显示「校验中…」（错误文案让位，校验完再由 setError 接管）。 */
+    setValidating(pending: boolean): this;
+    /** 设置错误文案（null / '' 表示通过）；同时把控件切到 error / default 状态。 */
+    setError(message: string | null): this;
+    private __layoutChildren;
+}

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

@@ -0,0 +1,59 @@
+import { ICEContainer } from '../core/ICEContainer';
+/**
+ * 24 栅格列（Ant `Col`）：`span` 占多少格、`offset` 左边空多少格，`content` 是列内容。
+ *
+ * 一般配合 `ICEGrid`（行）使用，由行统一算宽度与位置，不需要手动设 width。
+ */
+export interface ICEGridColOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    /** 占多少格（1..24），默认 24 */
+    span?: number;
+    /** 左侧空出多少格，默认 0 */
+    offset?: number;
+    /** 列内容 */
+    content?: any;
+    height?: number;
+}
+export declare class ICEGridCol extends ICEContainer {
+    readonly span: number;
+    readonly offset: number;
+    private content;
+    constructor(props?: ICEGridColOptions);
+    getContent(): any;
+    /** 由 `ICEGrid` 调用：设置列宽并把内容撑满列宽。 */
+    applyLayout(left: number, top: number, width: number): void;
+}
+/**
+ * 24 栅格行（Ant `Row`）：把若干 `ICEGridCol` 排成一行，放不下自动换行。
+ *
+ * 规则：先按 `span + offset` 把列分行（每行不超过 24 格），再按
+ * `unit = (width - gutter × (列数 - 1)) / 24` 算每格宽度；
+ * 行高取该行最高列，行间距离是 `gutterY`。
+ */
+export interface ICEGridOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    /** 列间距，默认 16 */
+    gutter?: number;
+    /** 行间距，默认 16 */
+    gutterY?: number;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+}
+export declare class ICEGrid extends ICEContainer {
+    private cols;
+    private gutter;
+    private gutterY;
+    private autoHeight;
+    constructor(props?: ICEGridOptions);
+    getCols(): ICEGridCol[];
+    addCol(col: ICEGridCol): this;
+    setGutter(gutter: number, gutterY?: number): this;
+    private __rows;
+    private __layout;
+    private __contentHeight;
+    revalidate(): this;
+}

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

@@ -0,0 +1,9 @@
+import { ICEWidget } from '../core/ICEWidget';
+/**
+ * 图标：一个居中的字形（★ ✓ ℹ …），字号与颜色可配。
+ */
+export declare class ICEIcon extends ICEWidget {
+    private textNode;
+    constructor(props?: any);
+    setIcon(icon: string): this;
+}

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

@@ -0,0 +1,53 @@
+import { ICEWidget } from '../core/ICEWidget';
+/**
+ * 图标磁贴（桌面图标 / 应用宫格）：大图标字形 + 下方文字标签。
+ *
+ * - 单击选中（标签变蓝底白字，XP 桌面的选择样式），再点一下取消；
+ * - **双击打开**（`dblclick` → `open` 事件 + `onOpen`），Enter/Space 等价（键盘可达）；
+ * - `selected` 为受控初始值，`setSelected()` 是程序式接口（取消全选时用）。
+ */
+export interface ICEIconTileOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    /** 图标字形（emoji 或单个符号） */
+    icon: string;
+    /**
+     * 自绘图标节点（给了它就代替 `icon` 字形）。
+     *
+     * 需要「画」出来的图标（拟物、彩色、多图层）时用：传一个组件，磁贴会把它在图标区居中。
+     */
+    iconNode?: any;
+    label: string;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    iconSize?: number;
+    fontSize?: number;
+    selected?: boolean;
+    onSelect?: (selected: boolean) => void;
+    onOpen?: (label: string) => void;
+}
+export declare class ICEIconTile extends ICEWidget {
+    private iconNode;
+    private labelNode;
+    private labelBackground;
+    private selected;
+    private onSelect;
+    private onOpen;
+    private readonly labelText;
+    constructor(props: ICEIconTileOptions);
+    getLabel(): string;
+    isSelected(): boolean;
+    setSelected(selected: boolean): this;
+    /** 单击切换选中（桌面图标的标准行为）。 */
+    toggle(): this;
+    /** 打开（双击 / Enter / Space）。 */
+    open(): this;
+    /** 键盘激活 = 打开（与双击同义）。 */
+    activate(): void;
+    getLabelColor(): string;
+    getLabelBackground(): string;
+    protected __applyHoverState(): void;
+    private __sync;
+}

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

@@ -0,0 +1,91 @@
+import { ICEButton } from './ICEButton';
+import { ICEImageView } from './ICEImageView';
+import { ICEPanel } from './ICEPanel';
+import { ICEWidget } from '../core/ICEWidget';
+import { ICEOverlayManager } from '../core/ICEOverlayManager';
+import { ICEFocusManager } from '../core/ICEFocusManager';
+/**
+ * 图片预览（Ant `Image.PreviewGroup`）：全屏遮罩 + 居中图片 + 底部工具栏。
+ *
+ * - 上一张 / 下一张循环切换（`change` 事件 + `onIndexChange`）；
+ * - 缩放（步进 + 上下限）与 90° 旋转，`reset()` 复位；
+ * - 关闭途径：工具栏关闭按钮、遮罩点击、Esc；打开期间接管 ←/→/+/− 快捷键；
+ * - 浮层挂在引擎工具层（复用 `ICEOverlayManager`），关闭后自动移除。
+ */
+export declare type ICEImagePreviewCloseReason = 'close' | 'mask' | 'esc' | 'api';
+export interface ICEImagePreviewOptions {
+    images: string[];
+    /** 初始索引，默认 0 */
+    index?: number;
+    /** 每次缩放的步进，默认 0.25 */
+    zoomStep?: number;
+    /** 缩放下限，默认 0.25 */
+    minZoom?: number;
+    /** 缩放上限，默认 3 */
+    maxZoom?: number;
+    maskClosable?: boolean;
+    closeOnEsc?: boolean;
+    onIndexChange?: (index: number) => void;
+    onClose?: (reason: ICEImagePreviewCloseReason) => void;
+    manager?: ICEOverlayManager;
+    focusManager?: ICEFocusManager;
+}
+declare type ICEPreviewToolbarButton = 'zoomOut' | 'zoomIn' | 'rotateLeft' | 'rotateRight' | 'prev' | 'next' | 'close';
+export declare class ICEImagePreview {
+    private ice;
+    private options;
+    private manager;
+    private focus;
+    private handle;
+    private mask;
+    private frame;
+    private image;
+    private buttons;
+    private index;
+    private zoom;
+    private rotation;
+    private bound;
+    private pendingReason;
+    constructor(ice: any, options: ICEImagePreviewOptions);
+    isOpen(): boolean;
+    getIndex(): number;
+    getZoom(): number;
+    getRotation(): number;
+    getMask(): ICEPanel | null;
+    getFrame(): ICEWidget | null;
+    getImageNode(): ICEImageView | null;
+    getToolbarButton(name: ICEPreviewToolbarButton): ICEButton | null;
+    getImages(): string[];
+    open(index?: number): this;
+    close(reason?: ICEImagePreviewCloseReason): this;
+    setIndex(index: number): this;
+    next(): this;
+    prev(): this;
+    zoomIn(): this;
+    zoomOut(): this;
+    rotateLeft(): this;
+    rotateRight(): this;
+    /** 缩放与旋转同时复位。 */
+    reset(): this;
+    /** 事件总线（组件自身不是画布节点，所以直接转发给实例上的 emitter）。 */
+    private listeners;
+    on(name: string, handler: (evt: any) => void): this;
+    off(name: string, handler: (evt: any) => void): this;
+    trigger(name: string, evt: any, param?: any): this;
+    private __clampIndex;
+    private __currentSrc;
+    private __zoomStep;
+    private __setZoom;
+    private __setRotation;
+    /** 图片按缩放铺在 frame 内（超出部分被 frame 裁掉），旋转走引擎 transform。 */
+    private __syncImage;
+    private __createToolbar;
+    private __bindKeyboard;
+    private __unbindKeyboard;
+    private __onKeyDown;
+    private __handleClosed;
+    private __visibleRect;
+}
+/** 便捷入口：`openImagePreview(ice, { images: [...], index: 0 })`。 */
+export declare function openImagePreview(ice: any, options: ICEImagePreviewOptions): ICEImagePreview;
+export {};

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

@@ -0,0 +1,62 @@
+import { ICEImage as EngineImage } from 'ice-render';
+import { ICEWidget } from '../core/ICEWidget';
+/**
+ * 图片视图（基于引擎原语 `ICEImage`）。
+ *
+ * 名字带 `View` 后缀是为了避开引擎自己的 `ICEImage`（图片原语）——两个包同名不同物，
+ * 同时 import 会撞名，所以本库的控件一律叫 `ICEImageView`。
+ *
+ * - 适配模式 `fill`（拉伸）/ `contain`（留白）/ `cover`（裁剪填满，居中）；
+ * - 原始尺寸未知时先按容器盒铺满，图片载入后由引擎的 ImageCache 回调重排；
+ * - 视口开 `clipChildren`，cover 溢出的部分被裁掉；
+ * - 载入失败标记错误态（保留占位底）。
+ */
+export declare type ICEImageFit = 'fill' | 'contain' | 'cover';
+export interface ICEImageOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    src?: string;
+    width?: number;
+    height?: number;
+    fit?: ICEImageFit;
+    /** 底衬颜色（未加载 / 加载失败时可见） */
+    placeholder?: string;
+    left?: number;
+    top?: number;
+}
+export interface ICEImageContentBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export declare class ICEImageView extends ICEWidget {
+    private src;
+    private fit;
+    private natural;
+    private errored;
+    private viewport;
+    private imageNode;
+    private hookedSrc;
+    constructor(props?: ICEImageOptions);
+    protected afterAddHandler(): void;
+    /** 按 fill/contain/cover 计算内容矩形（原始尺寸未知时铺满容器盒）。 */
+    static computeFit(naturalWidth: number, naturalHeight: number, boxWidth: number, boxHeight: number, fit: ICEImageFit): ICEImageContentBox;
+    getSrc(): string;
+    setSrc(src: string): this;
+    getFit(): ICEImageFit;
+    setFit(fit: ICEImageFit): this;
+    isLoaded(): boolean;
+    isErrored(): boolean;
+    markError(): this;
+    /** 已知原始尺寸时直接设定（图片 onload 回调 / 单测使用）。 */
+    setNaturalSize(width: number, height: number): this;
+    getContentBox(): ICEImageContentBox;
+    getViewportNode(): ICEWidget | null;
+    getImageNode(): EngineImage | null;
+    private __render;
+    private __layout;
+    private __computeContentBox;
+    /** 图片就绪后按原始尺寸重排（引擎 ImageCache 负责真实加载）。 */
+    private __syncFromCache;
+}

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

@@ -0,0 +1,54 @@
+import { ICEWidget } from '../core/ICEWidget';
+import { ICEButton } from './ICEButton';
+/**
+ * 数字输入框（Ant InputNumber / Swing JSpinner 的最小版）。
+ *
+ * - 左右步进按钮 + 键盘 ↑/↓ 步进，按 min/max 夹取，结果按 precision 取整；
+ * - 支持直接输入数字（数字键 / 小数点 / 负号 / Backspace）；
+ * - 表单集成：`getFormValue` / `setFormValue`，错误态边框标红。
+ */
+export interface ICEInputNumberOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    disabled?: boolean;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    onChange?: (value: number) => void;
+}
+export declare class ICEInputNumber extends ICEWidget {
+    private currentValue;
+    private min;
+    private max;
+    private step;
+    private precision;
+    private disabled;
+    private onChange;
+    private textLabel;
+    private decreaseButton;
+    private increaseButton;
+    private buffer;
+    private running;
+    constructor(props?: ICEInputNumberOptions);
+    protected afterAddHandler(): void;
+    getValue(): number;
+    setValue(value: number): this;
+    getFormValue(): any;
+    setFormValue(value: any): void;
+    getText(): string;
+    getIncreaseButton(): ICEButton | null;
+    getDecreaseButton(): ICEButton | null;
+    setEnabled(enabled: boolean): this;
+    private __applyValue;
+    private __stepBy;
+    private __onKeyDown;
+    private __clamp;
+    private __format;
+    private __render;
+}

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

@@ -0,0 +1,85 @@
+import { ICEWidget } from '../core/ICEWidget';
+/**
+ * 看板：列 + 卡片，卡片可以**跨列拖拽**（CRM / 项目管理最常见的那块界面）。
+ *
+ * 结构很直白：
+ * ```
+ * ICEKanban
+ *   ├── column[todo]   ← 列标题 + 卡片（等距竖排）
+ *   ├── column[doing]
+ *   └── column[done]
+ * ```
+ *
+ * 拖拽的「落点」复用列表那套：列由指针的 **x** 决定，列内插入位置由 **y** 决定
+ * （`computeDropTarget` 的上下半格语义），真正的数据搬运交给纯函数 `moveKanbanCard`。
+ */
+export interface ICEKanbanCard {
+    key: string;
+    title: string;
+    [field: string]: any;
+}
+export interface ICEKanbanColumn {
+    key: string;
+    title: string;
+    cards: ICEKanbanCard[];
+    [field: string]: any;
+}
+export interface ICEKanbanDropTarget {
+    columnKey: string;
+    index: number;
+    position: 'before' | 'after';
+}
+export interface ICEKanbanOptions {
+    id?: string;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    columns: ICEKanbanColumn[];
+    columnWidth?: number;
+    cardHeight?: number;
+    gap?: number;
+    draggable?: boolean;
+    onCardMove?: (info: {
+        cardKey: string;
+        columnKey: string;
+        index: number;
+        columns: ICEKanbanColumn[];
+    }) => void;
+    [key: string]: any;
+}
+export declare class ICEKanban extends ICEWidget {
+    private columns;
+    private columnWidth;
+    private cardHeight;
+    private gap;
+    private draggable;
+    private onCardMove;
+    private cardNodes;
+    private columnNodes;
+    private dragState;
+    private __bound;
+    private running;
+    constructor(props: ICEKanbanOptions);
+    protected afterAddHandler(): void;
+    getColumns(): ICEKanbanColumn[];
+    getCardNode(key: string): ICEWidget | null;
+    getColumnNode(key: string): ICEWidget | null;
+    isDraggable(): boolean;
+    isDragging(): boolean;
+    getDropTarget(): ICEKanbanDropTarget | null;
+    /** 把卡片移到目标列的指定位置；真的动了才返回 true（判定见纯函数 `moveKanbanCard`）。 */
+    moveCard(cardKey: string, columnKey: string, index: number): boolean;
+    private __columnX;
+    private __cardY;
+    private __render;
+    private __localPoint;
+    private __columnIndexAt;
+    /** 指针 → 落点：x 定列，y 定列内插入位置（上下半格沿用列表那套）。 */
+    private __targetAt;
+    private __onMouseDown;
+    private __onMouseMove;
+    private __onMouseUp;
+    private __hideIndicators;
+    private __updateDrag;
+}

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

@@ -0,0 +1,28 @@
+import { ICEWidget } from '../core/ICEWidget';
+/**
+ * 文本标签：包装引擎 `ICEText`，支持水平（`align`）与垂直（`verticalAlign`）对齐；
+ * 未显式给尺寸时采用文字的实测尺寸，便于参与流式/盒式布局。
+ */
+export declare class ICELabel extends ICEWidget {
+    private textNode;
+    constructor(props?: any);
+    setText(text: string): this;
+    getText(): string;
+    /**
+     * 让标签自身占据文字的实测尺寸。
+     *
+     * ICEText 会把自身宽高自动调成实测值，而 ICELabel 只是它的一层包装容器：调用方不显式给尺寸时，
+     * ICELabel 会停在 ICERect 的默认 10×10 —— 布局管理器（ICEFlowLayout / ICEBoxLayout 读的都是
+     * 子项的 `state.width/height`）于是不为文字留空间，表现为「标题和后面的按钮叠在一起」
+     * （流式布局里「标题压住后面的按钮」就是这么来的）。
+     *
+     * 调用方显式传了 width/height 时不覆盖，沿用引擎里「默认值 10 视为未设置」的约定。
+     */
+    private __adoptTextSize;
+    /**
+     * @overwrite
+     * 标签的首选尺寸就是文字的实测尺寸。不覆盖的话会落到 `ICEGroup.getPreferredSize()` 的
+     * `[0, 0]`（没有 layoutManager 时），按首选尺寸排布的调用方同样拿不到正确宽度。
+     */
+    getPreferredSize(): [number, number];
+}

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

@@ -0,0 +1,59 @@
+import { ICEWidget } from '../core/ICEWidget';
+import { ICEScrollPane } from './ICEScrollPane';
+import { ICESelectionModel, ICESelectionMode } from '../model/ICESelectionModel';
+/**
+ * 列表（Swing JList / Ant List 的最小版）。
+ *
+ * - 选择逻辑在 `ICESelectionModel` 里（single 替换 / multiple 切换），组件只负责渲染与交互；
+ * - 内容高于可视高度时自动套一层 `ICEScrollPane`（复用 A2 的滚动底座与子树裁剪）；
+ * - 交互：点击行选中（disabled 行忽略）；焦点在列表上时 ↑/↓ 移动激活行（跳过 disabled）、
+ *   Enter/Space 选中激活行。
+ */
+export interface ICEListItem {
+    key: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface ICEListOptions {
+    /** 组件 id（引擎会用它做唯一标识，e2e/调试时可按 id 定位） */
+    id?: string;
+    items: ICEListItem[];
+    mode?: ICESelectionMode;
+    value?: string[];
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    itemHeight?: number;
+    onChange?: (keys: string[], item?: ICEListItem) => void;
+}
+export declare class ICEList extends ICEWidget {
+    private items;
+    private model;
+    private itemHeight;
+    private onChange;
+    private pane;
+    private content;
+    private rowNodes;
+    private activeIndex;
+    private running;
+    constructor(props: ICEListOptions);
+    protected afterAddHandler(): void;
+    getSelectedKeys(): string[];
+    setSelectedKeys(keys: string[]): this;
+    getSelectionModel(): ICESelectionModel;
+    getActiveIndex(): number;
+    getRowNode(key: string): ICEWidget | null;
+    getScrollPane(): ICEScrollPane | null;
+    getItems(): ICEListItem[];
+    setItems(items: ICEListItem[]): this;
+    /** 宽度变化时重排行宽（引擎只回调 __afterStateMerge，不调 revalidate）。 */
+    protected __afterStateMerge(sizeChanged: boolean): void;
+    /** 焦点在列表上时才处理方向键/Enter（避免抢走页面按键）。 */
+    private __onKeyDown;
+    private __moveActive;
+    private __pick;
+    private __render;
+    /** 重建行（选中态 / 激活态 / 禁用态）。 */
+    private __syncRows;
+}

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

@@ -0,0 +1,48 @@
+import { ICEContainer } from '../core/ICEContainer';
+export declare type ICEMenuItem = {
+    key: string;
+    label: string;
+    icon?: string;
+    iconPath?: string;
+    /** 子菜单：带非空 children 的项是父节点（内联展开，点它不触发 onSelect） */
+    children?: ICEMenuItem[];
+};
+/**
+ * 菜单：菜单项 +（可选）子菜单内联展开；选中态与悬停态分离，父项在子项选中时只做“当前分组”提示。
+ */
+export declare class ICEMenu extends ICEContainer {
+    private items;
+    /** 扁平化后的可见行（展开的父节点后紧跟其子项） */
+    private rows;
+    /** 鼠标悬停的项（仅视觉反馈，不影响选中） */
+    private hoverKey;
+    private expanded;
+    private itemPanels;
+    private itemNodes;
+    private itemIcons;
+    private selectedKey;
+    private itemHeight;
+    private onSelect;
+    private __bound;
+    constructor(props?: any);
+    setSelectedKey(key: string | null): this;
+    getSelectedKey(): string | null;
+    /** 可见行（展开状态下的扁平列表）。 */
+    getVisibleItems(): ICEMenuItem[];
+    getItemNode(key: string): any;
+    isExpanded(key: string): boolean;
+    toggleExpand(key: string): this;
+    setExpandedKeys(keys: string[]): this;
+    /** 激活某个可见项：父节点展开/收起，叶子项选中并回调。 */
+    activateItem(key: string): this;
+    private __hasChildren;
+    /** 按展开状态把树拍平。 */
+    private __flatten;
+    protected afterAddHandler(): void;
+    private __bindGlobalEvents;
+    private __onGlobalMouseDown;
+    private __render;
+    private __syncSelection;
+    /** 从根走到目标项，返回途中经过的父节点 key（不含自身）。 */
+    private __ancestorKeys;
+}