@ticatec/uniface-element 5.0.1 → 5.0.2

package/docs/components/transfer/README.md

@@ -0,0 +1,109 @@
+# Transfer
+
+复合组件组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+在左右两个列表之间移动数据项的穿梭框。
+
+## 适用场景
+
+- 成员授权、角色分配和字段选择
+- 需要清晰区分待选与已选集合
+
+## 导入
+
+```ts
+import Transfer from '@ticatec/uniface-element/Transfer';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `sourceList` | 是 | `Array<any>` | 否 | `$bindable([])` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `sourceTitle` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `targetList` | 是 | `Array<any>` | 否 | `$bindable([])` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `targetTitle` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `itemRender` | 否 | `any` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `filter` | 是 | `FunFilter \| null` | 否 | `null` | 否 | 本地过滤函数。接收当前数据项和搜索文字，返回 true 时保留该项。仅用于已经加载到内存中的 list。 |
+| `onchange` | 是 | `TransferData` | 否 | `undefined` | 否 | 用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+| `footer$style` | 否 | `string` | 否 | `'width: 100%; background-color: #f0f0f0; padding: 2px 6px; text-align: right; box-sizing: border-box'` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `sourceList`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`Array<any>`
+- 默认值：`$bindable([])`
+- 推荐写法：`bind:sourceList`
+
+### `targetList`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`Array<any>`
+- 默认值：`$bindable([])`
+- 推荐写法：`bind:targetList`
+
+### `filter`
+
+本地过滤函数。接收当前数据项和搜索文字，返回 true 时保留该项。仅用于已经加载到内存中的 list。
+
+- 类型：`FunFilter | null`
+- 默认值：`null`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onchange`
+
+用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。
+
+- 类型：`TransferData`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `FunFilter`
+
+```ts
+export type FunFilter = (item: any, text: string) => boolean;
+```
+
+### `TransferData`
+
+```ts
+export type TransferData = (list: Array<any>, direction: "left" | "right") => Promise<boolean>;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Transfer from '@ticatec/uniface-element/Transfer';
+  let sourceList = $state<any>([]);
+  let targetList = $state<any>([]);
+</script>
+
+<Transfer
+  bind:sourceList
+  bind:targetList
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+/>
+<p>当前状态：{JSON.stringify({sourceList, targetList})}</p>
+```
+
+## 源码
+
+- `src/lib/composite/transfer/Transfer.svelte`

package/docs/components/transfer/example.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  import Transfer from '@ticatec/uniface-element/Transfer';
+  let sourceList = $state<any>([]);
+  let targetList = $state<any>([]);
+</script>
+
+<Transfer
+  bind:sourceList
+  bind:targetList
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+/>
+<p>当前状态：{JSON.stringify({sourceList, targetList})}</p>

package/docs/components/tree-view/README.md

@@ -0,0 +1,163 @@
+# TreeView
+
+数据展示组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以可展开的层级节点展示树形数据，支持选择、懒加载和自定义图标。
+
+## 适用场景
+
+- 组织架构、文件目录和分类树
+- 数据具有父子关系且需要展开、选择或右键操作
+
+## 导入
+
+```ts
+import TreeView from '@ticatec/uniface-element/TreeView';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `tree` | 是 | `HierarchyTree<any>` | 是 | `—` | 否 | HierarchyTree 实例，负责节点层级、键值与父子关系。 |
+| `textField` | 是 | `string \| GetText<any>` | 是 | `—` | 否 | 数据项中用于界面显示的文本字段名。 |
+| `iconField` | 否 | `string \| GetIcon<any>` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `nodeIcon` | 否 | `Snippet<[NodeIconContext]>` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `chevronIcon` | 否 | `Snippet<[ChevronIconContext]>` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `lazyLoader` | 是 | `TreeLazyLoader \| null` | 否 | `null` | 否 | 异步分页加载器，签名为 `(filterText, pageNo) => Promise<{list, hasMore}>`。ListBox 当前从第 1 页开始请求，滚动到底部且 `hasMore=true` 时继续加载。 |
+| `activeNode` | 是 | `any` | 否 | `$bindable<any>(null)` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `class` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的 CSS class。 |
+| `isVisible` | 否 | `NodeVisibleFun` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `onchange` | 是 | `OnNodeSelectionChange` | 否 | `undefined` | 否 | 用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+| `onContextMenu` | 否 | `OnContextMenu` | 否 | `undefined` | 否 | 事件或行为回调；参数与返回值以类型签名为准。 |
+| `title` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `defaultExpandDepth` | 否 | `number` | 否 | `0` | 否 | 初始展开多少层（0 = 全部折叠，1 = 展开根节点，依此类推）。默认 0。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `tree`
+
+HierarchyTree 实例，负责节点层级、键值与父子关系。
+
+- 类型：`HierarchyTree<any>`
+- 默认值：`—`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `textField`
+
+数据项中用于界面显示的文本字段名。
+
+- 类型：`string | GetText<any>`
+- 默认值：`—`
+- 示例写法：`textField="text"`
+
+### `lazyLoader`
+
+异步分页加载器，签名为 `(filterText, pageNo) => Promise<{list, hasMore}>`。ListBox 当前从第 1 页开始请求，滚动到底部且 `hasMore=true` 时继续加载。
+
+- 类型：`TreeLazyLoader | null`
+- 默认值：`null`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `activeNode`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`any`
+- 默认值：`$bindable<any>(null)`
+- 推荐写法：`bind:activeNode`
+
+### `onchange`
+
+用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。
+
+- 类型：`OnNodeSelectionChange`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `TreeLazyLoader`
+
+```ts
+export interface TreeLazyLoader {
+    /**
+     * 检查是否是枝节点（可能包含子节点）
+     */
+    isBranch: (node: IHierarchyData<any>) => boolean;
+
+    /**
+     * 加载子节点数据
+     */
+    load: LoadChildrenFun;
+}
+```
+
+### `NodeVisibleFun`
+
+```ts
+export type NodeVisibleFun = (node: IHierarchyData<any>) => boolean;
+```
+
+### `OnNodeSelectionChange`
+
+```ts
+export type OnNodeSelectionChange = (node: IHierarchyData<any>) => Promise<boolean>;
+```
+
+### `OnContextMenu`
+
+```ts
+export type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+### `LoadChildrenFun`
+
+```ts
+export type LoadChildrenFun = (item: IHierarchyData<any>) => Promise<Array<any>>;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import TreeView from '@ticatec/uniface-element/TreeView';
+  import {HierarchyTree} from '@ticatec/uniface-element/TreeNodes';
+
+  type Department = {id: string; parentId: string | null; name: string};
+  const departments: Department[] = [
+    {id: 'company', parentId: null, name: '公司'},
+    {id: 'dev', parentId: 'company', name: '研发部'},
+    {id: 'product', parentId: 'company', name: '产品部'}
+  ];
+  const tree = new HierarchyTree<Department>({
+    getKey: (item: Department) => item.id,
+    getParentKey: (item: Department) => item.parentId
+  });
+  tree.setData(departments);
+  let activeNode = $state<any>(null);
+</script>
+
+<TreeView
+  {tree}
+  textField="name"
+  title="组织架构"
+  defaultExpandDepth={1}
+  bind:activeNode
+  onchange={async (node) => { console.log('选择节点', node?.data); return true; }}
+/>
+```
+
+## 源码
+
+- `src/lib/data_display/tree_view/TreeView.svelte`

package/docs/components/tree-view/example.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+  import TreeView from '@ticatec/uniface-element/TreeView';
+  import {HierarchyTree} from '@ticatec/uniface-element/TreeNodes';
+
+  type Department = {id: string; parentId: string | null; name: string};
+  const departments: Department[] = [
+    {id: 'company', parentId: null, name: '公司'},
+    {id: 'dev', parentId: 'company', name: '研发部'},
+    {id: 'product', parentId: 'company', name: '产品部'}
+  ];
+  const tree = new HierarchyTree<Department>({
+    getKey: (item: Department) => item.id,
+    getParentKey: (item: Department) => item.parentId
+  });
+  tree.setData(departments);
+  let activeNode = $state<any>(null);
+</script>
+
+<TreeView
+  {tree}
+  textField="name"
+  title="组织架构"
+  defaultExpandDepth={1}
+  bind:activeNode
+  onchange={async (node) => { console.log('选择节点', node?.data); return true; }}
+/>

package/docs/components/unit-number-editor/README.md

@@ -0,0 +1,192 @@
+# UnitNumberEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+带单位显示的数值编辑器。
+
+## 适用场景
+
+- 长度、重量、百分比和货币数值
+- 数值含义依赖固定单位的输入
+
+## 导入
+
+```ts
+import UnitNumberEditor from '@ticatec/uniface-element/UnitNumberEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `variant` | 是 | `EditorVariant` | 否 | `undefined` | 否 | 视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。 |
+| `compact` | 否 | `boolean` | 否 | `false` | 否 | 启用紧凑尺寸，减少组件高度和内边距。 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `error` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `value` | 是 | `number` | 否 | `$bindable<number \| undefined>()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `unitCode` | 是 | `string` | 否 | `$bindable<string \| undefined>()` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `units` | 是 | `Array<UnitOption>` | 是 | `—` | 否 | 可选单位列表；用户可在输入框旁切换单位，数值随单位换算显示。 |
+| `disabled` | 是 | `boolean` | 否 | `false` | 否 | 禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。 |
+| `readonly` | 是 | `boolean` | 否 | `false` | 否 | 只读状态。保留内容展示，但阻止用户修改。 |
+| `prefix` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `allowNegative` | 否 | `boolean` | 否 | `false` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `menu$height` | 否 | `number` | 否 | `0` | 否 | 高度配置，数值单位为像素。 |
+| `placeholder` | 是 | `string` | 否 | `undefined` | 否 | 值为空时显示的提示文本。 |
+| `onchange` | 是 | `(value: number \| undefined) => void` | 否 | `undefined` | 否 | 用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。 |
+| `onfocus` | 否 | `(e: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(e: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+| `leadingIcon` | 否 | `Snippet` | 否 | `undefined` | 否 | Svelte Snippet 渲染入口，用于替换或补充默认内容。 |
+
+> 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
+
+## 重要属性说明
+
+### `variant`
+
+视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。
+
+- 类型：`EditorVariant`
+- 默认值：`undefined`
+- 示例写法：`variant="plain"`
+
+### `value`
+
+组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。
+
+- 类型：`number`
+- 默认值：`$bindable<number | undefined>()`
+- 推荐写法：`bind:value`
+
+### `unitCode`
+
+可选配置，具体取值范围和数据结构见类型列。
+
+- 类型：`string`
+- 默认值：`$bindable<string | undefined>()`
+- 推荐写法：`bind:unitCode`
+
+### `units`
+
+可选单位列表；用户可在输入框旁切换单位，数值随单位换算显示。
+
+- 类型：`Array<UnitOption>`
+- 默认值：`—`
+- 示例写法：`units={[]}`
+
+### `disabled`
+
+禁用交互。禁用后通常不可聚焦、不可修改，也不会触发变更操作。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`disabled={false}`
+
+### `readonly`
+
+只读状态。保留内容展示，但阻止用户修改。
+
+- 类型：`boolean`
+- 默认值：`false`
+- 示例写法：`readonly={false}`
+
+### `placeholder`
+
+值为空时显示的提示文本。
+
+- 类型：`string`
+- 默认值：`undefined`
+- 示例写法：`placeholder="请输入或选择"`
+
+### `onchange`
+
+用户完成值变更时调用；编程式赋值是否触发请以组件行为说明为准。
+
+- 类型：`(value: number | undefined) => void`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+## 组件实例方法
+
+通过 `bind:this` 获取组件实例后调用。
+
+| 方法 | 类型 | 说明 |
+| --- | --- | --- |
+| `focus()` | `() => void` | 组件实例方法。 |
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `EditorVariant`
+
+```ts
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+```
+
+### `UnitOption`
+
+```ts
+export default interface UnitOption {
+
+    /**
+     * 单位编码
+     */
+    code: string;
+
+    /**
+     * 单位文字
+     */
+    text?: string;
+
+    /**
+     * 标准比例
+     */
+    ratio?: number;
+
+    /**
+     * 小数位
+     */
+    precision?: number;
+
+    /**
+     * 最大值
+     */
+    max?: number;
+
+    /**
+     * 最小值
+     */
+    min?: number;
+}
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import UnitNumberEditor from '@ticatec/uniface-element/UnitNumberEditor';
+  let value = $state<any>(42);
+  let unitCode = $state<any>();
+</script>
+
+<UnitNumberEditor
+  units={[]}
+  bind:value
+  bind:unitCode
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  variant="plain"
+  placeholder="请输入或选择"
+  compact={true}
+  disabled={false}
+/>
+<p>当前状态：{JSON.stringify({value, unitCode})}</p>
+```
+
+## 源码
+
+- `src/lib/form/unit-number-editor/UnitNumberEditor.svelte`

package/docs/components/unit-number-editor/example.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  import UnitNumberEditor from '@ticatec/uniface-element/UnitNumberEditor';
+  let value = $state<any>(42);
+  let unitCode = $state<any>();
+</script>
+
+<UnitNumberEditor
+  units={[]}
+  bind:value
+  bind:unitCode
+  onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}
+  onfocus={async (...args: any[]) => { console.log('onfocus', ...args); return true; }}
+  variant="plain"
+  placeholder="请输入或选择"
+  compact={true}
+  disabled={false}
+/>
+<p>当前状态：{JSON.stringify({value, unitCode})}</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticatec/uniface-element",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "description": "A comprehensive UI component library for Svelte applications with rich form controls, data tables, layouts and interactive elements",
   "keywords": [
     "svelte",
@@ -24,7 +24,7 @@
   },
   "files": [
     "dist",
-    "docs/**/*.md",
+    "docs/**/*",
     "*.md",
     "!dist/**/*.scss",
     "!dist/**/*.test.*",
@@ -365,6 +365,11 @@
       "svelte": "./dist/navigation/tabs/index.js",
       "import": "./dist/navigation/tabs/index.js"
     },
+    "./PageStack": {
+      "types": "./dist/navigation/page-stack/index.d.ts",
+      "svelte": "./dist/navigation/page-stack/index.js",
+      "import": "./dist/navigation/page-stack/index.js"
+    },
     "./FullScreenOverlay": {
       "types": "./dist/overlay/common/FullscreenOverlay.svelte.d.ts",
       "svelte": "./dist/overlay/common/FullscreenOverlay.svelte",
@@ -429,9 +434,9 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.60.1",
+    "@sveltejs/kit": "^2.70.2",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@sveltejs/vite-plugin-svelte": "^7.2.0",
     "@tailwindcss/postcss": "^4.3.1",
     "@testing-library/svelte": "^5.4.2",
     "@ticatec/i18n": "^0.5.0",
@@ -445,15 +450,15 @@
     "prettier-plugin-svelte": "^4.0.0",
     "publint": "^0.3.21",
     "sass": "^1.99.0",
-    "svelte": "^5.55.9",
-    "svelte-check": "^4.4.8",
+    "svelte": "^5.56.5",
+    "svelte-check": "^4.7.4",
     "svelte-preprocess": "^6.0.3",
     "tailwindcss": "^4.3.1",
     "tslib": "^2.8.1",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.59.4",
     "vite": "^8.0.13",
-    "vitest": "^3.2.7"
+    "vitest": "^4.1.10"
   },
   "author": "Henry Feng",
   "license": "MIT",
@@ -485,12 +490,15 @@
     "build:css": "sass ./src/lib/ticatec-uniface-web.scss:./src/lib/ticatec-uniface-web.css --no-source-map",
     "build": "pnpm run build:css && svelte-kit sync && svelte-package",
     "package": "svelte-kit sync && svelte-package && publint",
+    "test:consumer": "pnpm --filter uniface-element-consumer-test test",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "lint": "eslint src/lib",
     "lint:fix": "eslint src/lib --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "docs:components": "node ./scripts/generate-component-docs.mjs",
+    "docs:check": "pnpm run build && node ./scripts/check-docs-examples.mjs",
     "typecheck": "pnpm run check",
     "test": "vitest run",
     "audit": "pnpm audit",