ice-web-components 1.0.0

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

@@ -0,0 +1,71 @@
+/**
+ * UI 过渡：极简补间 + 常用动效助手（淡入淡出 / 滑入 / 缩放进入）。
+ *
+ * 为什么不用引擎的 AnimationManager：那套是「按 props.animations 声明、每帧写 state 的点路径补间」，
+ * 适合常驻动画（蚂蚁线等），但没有**完成回调**与「一次性过渡」的语义。浮层/抽屉/消息这类
+ * 「进入-结束-回调」的过渡用它更别扭，所以这里做一层薄薄的 rAF 补间：
+ *
+ * - 纯函数式：只依赖注入的 frame driver（测试里可手动 step）；
+ * - 每个 tween 返回句柄，可 cancel（cancel 不触发 onFinish）；
+ * - duration ≤ 0 时同步落到终点并回调。
+ *
+ * 渐变类动效改的是组件 `state.opacity`（引擎按子树相乘，整棵子树一起透明，见 ice-render 的
+ * 子树不透明度支持）；滑块类是直接改 left/top；缩放改 `transform.scale`。
+ */
+export declare type ICEEasingName = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+export declare type ICEEasing = ICEEasingName | ((t: number) => number);
+export interface ICEFrameDriver {
+    request(callback: (time: number) => void): any;
+    cancel(handle: any): void;
+}
+export interface ICETweenOptions {
+    from?: number;
+    to: number;
+    /** 毫秒；≤ 0 或非法时同步落到终点 */
+    duration?: number;
+    delay?: number;
+    easing?: ICEEasing;
+    onUpdate: (value: number) => void;
+    onFinish?: () => void;
+    driver?: ICEFrameDriver;
+}
+export interface ICETweenHandle {
+    cancel(): void;
+}
+export declare function easeInQuad(t: number): number;
+export declare function easeOutCubic(t: number): number;
+export declare function easeInOutCubic(t: number): number;
+export declare function resolveICEEasing(easing?: ICEEasing): (t: number) => number;
+/** 单值补间（frame driver 可注入，测试里手动 step）。 */
+export declare function tween(options: ICETweenOptions): ICETweenHandle;
+/** 过渡公共参数（不含 from/to）。 */
+export interface ICETransitionOptions {
+    duration?: number;
+    delay?: number;
+    easing?: ICEEasing;
+    onFinish?: () => void;
+    driver?: ICEFrameDriver;
+}
+/** 把不透明度过渡到指定值。 */
+export declare function fadeTo(component: any, to: number, options?: ICETransitionOptions): ICETweenHandle;
+/** 淡入：从 0 到 1。 */
+export declare function fadeIn(component: any, options?: ICETransitionOptions): ICETweenHandle;
+/** 淡出：从当前值到 0（完成后通常再移除组件）。 */
+export declare function fadeOut(component: any, options?: ICETransitionOptions): ICETweenHandle;
+export interface ICESlideOptions extends ICETransitionOptions {
+    /** 从哪一侧滑入（目标位置保持不变） */
+    from: 'top' | 'bottom' | 'left' | 'right';
+    distance?: number;
+    /** 是否同时淡入，默认 true */
+    fade?: boolean;
+}
+/** 滑入：从指定方向的偏移位置移到当前位置（可选同时淡入）。 */
+export declare function slideIn(component: any, options: ICESlideOptions): ICETweenHandle;
+export interface ICEScaleInOptions extends ICETransitionOptions {
+    /** 起始缩放（默认 0.96） */
+    from?: number;
+    /** 是否同时淡入，默认 true */
+    fade?: boolean;
+}
+/** 缩放进入：scale 从 from 到 1（可选同时淡入）。 */
+export declare function scaleIn(component: any, options?: ICEScaleInOptions): ICETweenHandle;

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

@@ -0,0 +1,102 @@
+/**
+ * 拖拽排序的纯逻辑（表格行 / 树节点 / 看板卡共用）。
+ *
+ * 交互里最容易错的两件事——「指针落在第几行的上/下半格」和「移动之后数组长什么样」——
+ * 都在这里用纯函数解决，交互层只负责读指针、画指示线、松手时调用 `moveItem`。
+ */
+/** 落点：插到第 `index` 行的之前 / 之后。 */
+export interface ICEDropTarget {
+    index: number;
+    position: 'before' | 'after';
+}
+export interface ICEDropTargetOptions {
+    /** 指针相对列表内容顶部的纵坐标（已减去滚动偏移） */
+    pointerY: number;
+    itemHeight: number;
+    itemCount: number;
+}
+/**
+ * 指针坐标 → 落点。
+ *
+ * - 上半格 = `before`，下半格 = `after`（正好压在分界线算 after，边界行为稳定）；
+ * - 拖到列表上下方会夹到首尾，不会给出越界下标；
+ * - 空列表或非法行高返回 `null`（调用方据此不画指示线）。
+ */
+export declare function computeDropTarget(options: ICEDropTargetOptions): ICEDropTarget | null;
+export interface ICEMoveResult<T> {
+    items: T[];
+    /** 移动后的新下标 */
+    to: number;
+    /** 是否真的移动了（拖回原位 / 相邻等价位置都算没动） */
+    moved: boolean;
+}
+/**
+ * 把第 `from` 项移到落点处，返回新数组。
+ *
+ * - 不改原数组（返回的是浅拷贝）；
+ * - 落点换算成「移除后数组里的插入下标」，所以往回拖不会错一位；
+ * - 拖到自己身上、或拖到与自己相邻的等价位置，一律 `moved: false`；
+ * - 任一下标越界也当作没动。
+ */
+export declare function moveItem<T>(items: T[], from: number, target: ICEDropTarget): ICEMoveResult<T>;
+/** 树拖拽的落点：`inside` = 放进节点里当子节点。 */
+export interface ICETreeDropTarget {
+    index: number;
+    position: 'before' | 'inside' | 'after';
+}
+export interface ICETreeDropTargetOptions {
+    /** 指针相对**内容顶部**的纵坐标（已减去滚动偏移） */
+    pointerY: number;
+    itemHeight: number;
+    itemCount: number;
+}
+/**
+ * 树的行内三分法：上 1/3 插到前面、中 1/3 放进去当子节点、下 1/3 插到后面。
+ *
+ * 为什么是三分而不是列表的两分：树拖拽必须能表达「成为它的子节点」这件事，
+ * 只用上下两半就只能同级移动了。三分法也是各家树控件的通行做法（手感最好）。
+ */
+export declare function computeTreeDropTarget(options: ICETreeDropTargetOptions): ICETreeDropTarget | null;
+export interface ICETreeNodeLike {
+    key: string;
+    children?: ICETreeNodeLike[];
+    [key: string]: any;
+}
+export interface ICETreeMoveResult<T> {
+    nodes: T[];
+    moved: boolean;
+    /** 移动后的父节点 key（根级为 null） */
+    parentKey: string | null;
+}
+/**
+ * 把 `dragKey` 节点移到 `targetKey` 的 before / inside / after。
+ *
+ * - 返回**新树**（不改原数组/原节点）；
+ * - **不能拖进自己的后代**（那样整棵子树会凭空消失）—— 直接 `moved: false`；
+ * - 位置没变（例如同级 before 到紧邻的下一项）也算没动；
+ * - `before/after` 是插到目标的**同级**，`inside` 则成为目标的最后一个子节点。
+ */
+export declare function moveTreeNode<T extends ICETreeNodeLike>(nodes: T[], dragKey: string, targetKey: string, position: ICETreeDropTarget['position'], childrenKey?: string): ICETreeMoveResult<T>;
+/** 看板列（结构最小化：只要 key + cards）。 */
+export interface ICEKanbanColumnLike<T = any> {
+    key: string;
+    cards: T[];
+    [field: string]: any;
+}
+export interface ICEKanbanMoveResult<C> {
+    columns: C[];
+    moved: boolean;
+    /** 移动后所在的列 */
+    columnKey: string | null;
+    /** 移动后在列内的下标 */
+    index: number;
+}
+/**
+ * 看板卡片移动：从原列取出，插到目标列的 `index` 位置。
+ *
+ * - 卡片对象**引用不变**地搬过去（业务字段不丢）；
+ * - `index` 超界收到末尾（插到列尾 / 空列都是合法落点）；
+ * - 未知卡片 / 未知列 / 同列原位（移动前后下标相同）都返回 `moved: false` 且结构不变；
+ * - 返回新结构（浅拷贝列数组 + 新卡片数组），原结构不动。
+ */
+export declare function moveKanbanCard<C extends ICEKanbanColumnLike>(columns: C[], cardKey: string, targetColumnKey: string, index: number): ICEKanbanMoveResult<C>;

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

@@ -0,0 +1,65 @@
+/**
+ * 原生输入替身（canvas 里支持中文 IME 的关键一步）。
+ *
+ * 问题：canvas 组件自己处理 `keydown` 只能吃单字符键 —— **中文输入法在组字阶段根本没有
+ * keydown**，所以「打中文」一直打不进去（只能 `setValue`）。
+ *
+ * 做法（和引擎 `ICEText.startEditing()` 同一套路）：聚焦时在组件上方挂一个**完全透明**的
+ * 原生 `<input>` / `<textarea>`，让浏览器和输入法去做它们擅长的事，再把结果回写：
+ * - `input`：普通输入（打字、粘贴、删除）
+ * - `compositionend`：输入法组字结束（中文/日文/韩文走这条）
+ * - `Enter` / `Escape` / `blur`：交给组件决定（提交、取消、收尾）
+ *
+ * 元素是透明的（文字透明、背景透明、无边框），**画面仍然由 canvas 画**，元素只提供光标与输入法。
+ *
+ * 没有 `document` 的运行时（Node / 小程序）里 `mount()` 是空操作，组件据此降级回 keydown 输入。
+ */
+export interface ICENativeInputBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface ICENativeInputOptions {
+    /** 注入 document（测试用假对象）；不传则取全局 document */
+    doc?: any;
+    /** 组件的世界坐标盒（CSS 像素，相对画布左上角） */
+    box: ICENativeInputBox;
+    value?: string;
+    /** 与 canvas 完全一致的字体串（`400 14px Tahoma`），否则光标与文本对不齐 */
+    font?: string;
+    caretColor?: string;
+    /** 0 / 不传 = 不限制 */
+    maxLength?: number;
+    /** 多行模式：创建 textarea（Enter 换行，不触发 onEnter） */
+    multiline?: boolean;
+    onInput?: (value: string) => void;
+    onEnter?: () => void;
+    onEscape?: () => void;
+    onBlur?: () => void;
+}
+export declare class ICENativeInput {
+    private options;
+    private element;
+    private doc;
+    private value;
+    private maxLength;
+    private multiline;
+    constructor(options: ICENativeInputOptions);
+    isMounted(): boolean;
+    getElement(): any;
+    getValue(): string;
+    /** 挂载：创建元素、定位、聚焦、把光标放到末尾。重复调用是幂等的。 */
+    mount(): this;
+    /** 卸载并解绑；重复调用安全。 */
+    unmount(): void;
+    /** 外部改值（例如 setValue）：同步到元素并把光标移到末尾。 */
+    setValue(value: string): this;
+    focus(): this;
+    private __normalize;
+    private __moveCaretToEnd;
+    /** `input` 与 `compositionend` 共用：截断 → 回写元素 → 通知组件。 */
+    private __handleInput;
+    private __handleKeyDown;
+    private __handleBlur;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * 浮层定位：纯函数，不依赖 canvas / ICE，便于单测。
+ *
+ * 语义参照 Ant Design：placement 由「边」+「对齐」组成（如 bottomLeft = 锚点下方、左对齐），
+ * 空间不够时自动翻到对侧（flip），最后再夹到容器可见范围内（clamp）。
+ */
+export declare type ICEOverlayPlacement = 'top' | 'topLeft' | 'topRight' | 'bottom' | 'bottomLeft' | 'bottomRight' | 'left' | 'leftTop' | 'leftBottom' | 'right' | 'rightTop' | 'rightBottom';
+export interface ICEOverlayBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface ICEOverlayPositionInput {
+    /** 锚点盒（世界坐标） */
+    anchor: ICEOverlayBox;
+    /** 浮层内容尺寸 */
+    content: {
+        width: number;
+        height: number;
+    };
+    /**
+     * 可见容器（世界坐标）。默认左上角在原点；带视口平移时传 left/top，
+     * 内部会在「容器局部坐标」里计算再换回世界坐标。
+     */
+    container: {
+        width: number;
+        height: number;
+        left?: number;
+        top?: number;
+    };
+    placement?: ICEOverlayPlacement;
+    /** 浮层与锚点的间距（默认 8） */
+    offset?: number;
+    /** 浮层与容器边缘的最小留白（默认 4） */
+    padding?: number;
+    /** 空间不足时是否翻到对侧（默认 true） */
+    flip?: boolean;
+}
+export interface ICEOverlayPosition {
+    left: number;
+    top: number;
+    /** 实际使用的 placement（可能因 flip 与请求值不同） */
+    placement: ICEOverlayPlacement;
+    /** 是否发生了翻转 */
+    flipped: boolean;
+}
+/**
+ * 计算浮层位置：优先用请求的 placement；放不下且 flip 打开时翻到对侧；
+ * 最后把结果夹进容器（内容比容器还大时夹到起始边，保证左上角可见）。
+ */
+export declare function resolveICEOverlayPosition(input: ICEOverlayPositionInput): ICEOverlayPosition;

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

@@ -0,0 +1,60 @@
+import { ICEText } from 'ice-render';
+import type { ICEThemeTokens } from '../theme/ICETheme';
+export declare type ICEStatusColor = 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+/**
+ * 极简文本宽度估算（给「按最长文字定容器宽度」用的）。
+ *
+ * 画布文本**没有裁剪**：容器（tooltip / dropdown 面板）算窄了，中文会直接压出色块外面。
+ * 中日韩与全角字符按 1em、其余按 0.6em 估算——够用且不依赖 ctx（构造期就能算）。
+ */
+export declare function estimateTextWidth(text: string, fontSize: number): number;
+/**
+ * 从 `hoverchange` 事件里读取 hovered。
+ *
+ * 引擎的 `trigger(name, evt, param)` 把第三个参数放进 `event.param`（不是平铺在事件上），
+ * 而手写的 `trigger('hoverchange', { hovered })` 又是平铺的 —— 两种都要兼容。
+ * 只读 `evt.hovered` 会永远拿到 undefined，表现为「悬停反馈静默失效」。
+ */
+export declare function readHovered(evt: any): boolean;
+export declare type ICEStatusColors = {
+    background: string;
+    border: string;
+    /** 状态实色（白底上的文字 / 进度条等填充） */
+    text: string;
+    /** subtle 浅底上的强调文字色（Bootstrap `*-text-emphasis`） */
+    strong: string;
+    /** 实底填充（Bootstrap `.text-bg-*` 的 background） */
+    solid: string;
+    /** 实底上的文字色（亮色底为黑字） */
+    onSolid: string;
+};
+export declare function getStatusColors(theme: ICEThemeTokens, status?: ICEStatusColor): {
+    background: string;
+    border: string;
+    text: string;
+    strong: string;
+    solid: string;
+    onSolid: string;
+};
+/**
+ * 创建一段按照 ICE 约定居中显示的文本。
+ * width/height 不传时交给 ICEText 自动测量，并保持左上角文本语义。
+ */
+export declare function createTextNode(props: {
+    text?: string;
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    fillStyle?: string;
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    align?: 'left' | 'center' | 'right';
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+}): ICEText;
+export declare function centerTextNode(text: string, theme: ICEThemeTokens, width: number, height: number, options?: {
+    fontSize?: number;
+    fontWeight?: string;
+    fillStyle?: string;
+}): ICEText;

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

@@ -0,0 +1,14 @@
+/**
+ * UI 组件的世界盒（`left/top/width/height`）。
+ *
+ * UI 组件不旋转，父子关系就是简单的偏移叠加：沿父链累加 left/top 即可，
+ * 不依赖引擎的 composedMatrix 是否新鲜（浮层定位、焦点环、命中范围判断都要用）。
+ */
+export interface ICEWorldBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export declare function getICEWorldBox(component: any): ICEWorldBox;
+export declare function isPointInsideICEBox(box: ICEWorldBox, x: number, y: number): boolean;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "ice-web-components",
+  "version": "1.0.0",
+  "description": "Swing-style Canvas UI components built on ice-render.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "browser": "dist/index.umd.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run build:types && npm run build:js",
+    "build:js": "rollup -c --environment NODE_ENV:production",
+    "build:types": "tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "clean": "rimraf dist",
+    "dev": "rollup -c -w --environment NODE_ENV:development",
+    "test": "jest --runInBand",
+    "types:check": "tsc --noEmit",
+    "qa:admin": "node scripts/qa-admin.mjs",
+    "qa:gallery": "node scripts/qa-gallery.mjs",
+    "qa:workbench": "node scripts/qa-workbench.mjs",
+    "qa:xp": "node scripts/qa-xp.mjs",
+    "qa:arcade": "node scripts/qa-arcade.mjs",
+    "docs:api": "node scripts/gen-docs.mjs",
+    "docs:check": "node scripts/check-docs.mjs",
+    "docs": "npm run docs:api && npm run docs:check",
+    "verify": "npm run types:check && npm test && npm run build && npm run docs"
+  },
+  "dependencies": {
+    "ice-render": "^1.3.0"
+  },
+  "devDependencies": {
+    "@babel/core": "7.17.8",
+    "@babel/preset-env": "7.16.11",
+    "@babel/preset-typescript": "7.9.0",
+    "@rollup/plugin-commonjs": "21.0.2",
+    "@rollup/plugin-json": "4.1.0",
+    "@rollup/plugin-node-resolve": "13.1.3",
+    "@types/jest": "^27.5.2",
+    "@types/node": "^14.18.63",
+    "jest": "25.4.0",
+    "rimraf": "3.0.2",
+    "rollup": "2.70.1",
+    "rollup-plugin-babel": "4.4.0",
+    "rollup-plugin-terser": "5.3.0",
+    "typescript": "4.6.2"
+  },
+  "keywords": [
+    "canvas",
+    "ui",
+    "ice-render",
+    "swing"
+  ],
+  "license": "MIT"
+}