@ticatec/topside-elements 1.0.0

package/docs/components/transfer/README.md

@@ -0,0 +1,116 @@
+# Transfer
+
+复合组件组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+在左右两个列表之间移动数据项的穿梭框。
+
+## 适用场景
+
+- 成员授权、角色分配和字段选择
+- 需要清晰区分待选与已选集合
+
+## 导入
+
+```ts
+import Transfer from '@ticatec/topside-elements/Transfer';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `style` | 否 | `string` | 否 | `''` | 否 | 附加到组件根元素的内联样式。 |
+| `sourceList` | 是 | `Array<any>` | 否 | `$bindable([])` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `sourceTitle` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `targetList` | 是 | `Array<any>` | 否 | `$bindable([])` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `targetTitle` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `itemRender` | 否 | `any` | 否 | `null` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `filter` | 是 | `FilterFn \| null` | 否 | `null` | 否 | 本地过滤函数。接收当前数据项和搜索文字，返回 true 时保留该项。仅用于已经加载到内存中的 list。 |
+| `beforeTransfer` | 否 | `BeforeTransfer` | 否 | `undefined` | 否 | 移动前的否决钩子：返回 false 阻止移动。 |
+| `onchange` | 是 | `OnTransfer` | 否 | `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。
+
+- 类型：`FilterFn | null`
+- 默认值：`null`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onchange`
+
+移动完成后的通知。
+
+- 类型：`OnTransfer`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `FilterFn`
+
+```ts
+export type FilterFn = (item: any, text: string) => boolean;
+```
+
+### `BeforeTransfer`
+
+```ts
+export type BeforeTransfer = (list: Array<any>, direction: "left" | "right") => boolean | void | Promise<boolean | void>;
+```
+
+### `OnTransfer`
+
+```ts
+export type OnTransfer = (list: Array<any>, direction: "left" | "right") => void;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import Transfer from '@ticatec/topside-elements/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/topside-elements/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,179 @@
+# TreeView
+
+数据展示组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+以可展开的层级节点展示树形数据，支持选择、懒加载和自定义图标。
+
+## 适用场景
+
+- 组织架构、文件目录和分类树
+- 数据具有父子关系且需要展开、选择或右键操作
+
+## 导入
+
+```ts
+import TreeView from '@ticatec/topside-elements/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` | 否 | `IsNodeVisible` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `beforeChange` | 是 | `BeforeNodeChange` | 否 | `undefined` | 否 | 切换选中节点前的否决钩子：返回 false 阻止切换；node 为 null 表示取消选中。 |
+| `onchange` | 是 | `OnNodeChange` | 否 | `undefined` | 否 | 选中节点变化后的通知。 |
+| `onfocus` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件失去焦点时调用。 |
+| `oncontextmenu` | 否 | `OnContextMenu` | 否 | `undefined` | 否 | 节点右键菜单回调 (event, node) |
+| `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`
+
+### `beforeChange`
+
+切换选中节点前的否决钩子：返回 false 阻止切换；node 为 null 表示取消选中。
+
+- 类型：`BeforeNodeChange`
+- 默认值：`undefined`
+- 示例写法：参见下方完整示例中的类型化实现。
+
+### `onchange`
+
+选中节点变化后的通知。
+
+- 类型：`OnNodeChange`
+- 默认值：`undefined`
+- 示例写法：`onchange={async (...args: any[]) => { console.log('onchange', ...args); return true; }}`
+
+## 相关类型定义
+
+以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。
+
+### `TreeLazyLoader`
+
+```ts
+export interface TreeLazyLoader {
+    /**
+     * 检查是否是枝节点（可能包含子节点）
+     */
+    isBranch: (node: IHierarchyData<any>) => boolean;
+
+    /**
+     * 加载子节点数据
+     */
+    load: LoadChildren;
+}
+```
+
+### `IsNodeVisible`
+
+```ts
+export type IsNodeVisible = (node: IHierarchyData<any>) => boolean;
+```
+
+### `BeforeNodeChange`
+
+```ts
+export type BeforeNodeChange = (node: IHierarchyData<any> | null) => boolean | void | Promise<boolean | void>;
+```
+
+### `OnNodeChange`
+
+```ts
+export type OnNodeChange = (node: IHierarchyData<any> | null) => void;
+```
+
+### `OnContextMenu`
+
+```ts
+export type OnContextMenu = (event: MouseEvent, data: any) => void;
+```
+
+### `LoadChildren`
+
+```ts
+export type LoadChildren = (item: IHierarchyData<any>) => Promise<Array<any>>;
+```
+
+## 示例
+
+完整示例见 [example.svelte](./example.svelte)。
+```svelte
+<script lang="ts">
+  import TreeView from '@ticatec/topside-elements/TreeView';
+  import {HierarchyTree} from '@ticatec/topside-elements/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
+  beforeChange={async (node: any) => true}
+  onchange={(node: any) => console.log('选择节点', node?.data)}
+/>
+```
+
+## 源码
+
+- `src/lib/data_display/tree_view/TreeView.svelte`

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

@@ -0,0 +1,27 @@
+<script lang="ts">
+  import TreeView from '@ticatec/topside-elements/TreeView';
+  import {HierarchyTree} from '@ticatec/topside-elements/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
+  beforeChange={async (node: any) => true}
+  onchange={(node: any) => console.log('选择节点', node?.data)}
+/>

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

@@ -0,0 +1,195 @@
+# UnitNumberEditor
+
+表单组件。本文档由源码自动生成，类型以当前版本为准。
+
+## 简介
+
+带单位显示的数值编辑器。
+
+## 适用场景
+
+- 长度、重量、百分比和货币数值
+- 数值含义依赖固定单位的输入
+
+## 导入
+
+```ts
+import UnitNumberEditor from '@ticatec/topside-elements/UnitNumberEditor';
+```
+
+## 属性
+
+| 属性 | 重要 | 类型 | 必填 | 默认值 | 可绑定/响应式 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `variant` | 是 | `EditorVariant` | 否 | `undefined` | 否 | 视觉样式变体，可选值：`""`(默认)、`plain`、`outlined`、`filled`；具体含义见组件说明。 |
+| `theme` | 否 | `string` | 否 | `undefined` | 否 | 组件主题标识，通常通过 `data-theme` 选择对应 CSS 变量。 |
+| `compact` | 否 | `boolean` | 否 | `false` | 否 | 启用紧凑尺寸，减少组件高度和内边距。 |
+| `style` | 否 | `string` | 否 | `undefined` | 否 | 附加到组件根元素的内联样式。 |
+| `tooltip` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `error` | 否 | `string` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `value` | 是 | `number` | 否 | `$bindable<number \| undefined>()` | 是 | 组件的核心值。支持绑定时建议使用 `bind:value`，外部修改会同步到组件。 |
+| `unitCode` | 是 | `string` | 否 | `$bindable<string \| undefined>()` | 是 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `options` | 是 | `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` | 否 | `(event: FocusEvent) => void` | 否 | `undefined` | 否 | 组件获得焦点时调用。 |
+| `onblur` | 否 | `(event: 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`
+
+### `options`
+
+可选单位列表
+
+- 类型：`Array<UnitOption>`
+- 默认值：`[]`
+- 示例写法：`options={[
+    {code: 'dev', text: '研发部'},
+    {code: 'product', text: '产品部'}
+  ]}`
+
+### `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/topside-elements/UnitNumberEditor';
+  let value = $state<any>(42);
+  let unitCode = $state<any>();
+</script>
+
+<UnitNumberEditor
+  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,17 @@
+<script lang="ts">
+  import UnitNumberEditor from '@ticatec/topside-elements/UnitNumberEditor';
+  let value = $state<any>(42);
+  let unitCode = $state<any>();
+</script>
+
+<UnitNumberEditor
+  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>