@ticatec/uniface-element 0.3.18 → 0.3.20

package/dist/split/README.md

@@ -0,0 +1,240 @@
+# Split
+
+A resizable splitter component that allows users to adjust the size of adjacent panels by dragging the divider. Perfect for creating resizable layouts with flexible panel sizing.
+
+## Features
+
+- **Resizable Panels**: Drag to resize adjacent panels
+- **Direction Support**: Horizontal and vertical orientations
+- **Custom Width**: Set the divider width
+- **Reverse Mode**: Optional reverse dragging direction
+- **Fixed Mode**: Can be fixed (non-resizable)
+- **Visual Feedback**: Cursor changes during drag operation
+- **Minimum Size**: Enforces minimum panel size (5px)
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import Split from '@ticatec/uniface-element/Split';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let leftPanel;
+  let rightPanel;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div bind:this={leftPanel} style="flex: 0 0 200px; background: #f0f0f0;">
+    Left Panel
+  </div>
+  <Split bindingPanel={leftPanel} direction="horizontal" />
+  <div bind:this={rightPanel} style="flex: 1; background: #e0e0e0;">
+    Right Panel
+  </div>
+</div>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `direction` | `'horizontal' \| 'vertical'` | `'vertical'` | Splitter orientation |
+| `width` | `number` | `2` | Width/thickness of the divider (px) |
+| `bindingPanel` | `HTMLElement \| null` | `null` | Reference to the panel to resize |
+| `reverse` | `boolean` | `false` | Reverse the drag direction |
+
+## Examples
+
+### Horizontal Split
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let panel1;
+  let panel2;
+</script>
+
+<div style="display: flex; height: 400px;">
+  <div bind:this={panel1} style="flex: 0 0 250px; padding: 16px; background: #f5f5f5;">
+    <h3>Left Panel</h3>
+    <p>Resize me by dragging the divider!</p>
+  </div>
+
+  <Split bindingPanel={panel1} direction="horizontal" width="4" />
+
+  <div style="flex: 1; padding: 16px; background: #e8e8e8;">
+    <h3>Right Panel</h3>
+    <p>This panel fills remaining space</p>
+  </div>
+</div>
+```
+
+### Vertical Split
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let topPanel;
+  let bottomPanel;
+</script>
+
+<div style="display: flex; flex-direction: column; height: 400px;">
+  <div bind:this={topPanel} style="flex: 0 0 150px; padding: 16px; background: #f5f5f5;">
+    <h3>Top Panel</h3>
+  </div>
+
+  <Split bindingPanel={topPanel} direction="vertical" width="4" />
+
+  <div style="flex: 1; padding: 16px; background: #e8e8e8;">
+    <h3>Bottom Panel</h3>
+  </div>
+</div>
+```
+
+### Custom Width
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let panel1;
+  let panel2;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div bind:this={panel1} style="flex: 0 0 200px; background: #f0f0f0;">
+    Panel 1
+  </div>
+
+  <!-- Thick divider -->
+  <Split bindingPanel={panel1} width="8" />
+
+  <div style="flex: 1; background: #e0e0e0;">
+    Panel 2
+  </div>
+</div>
+```
+
+### Reverse Direction
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let panel1;
+  let panel2;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1; background: #e0e0e0;">
+    Panel 1 (expands when panel 2 shrinks)
+  </div>
+
+  <!-- Reverse mode: drags in opposite direction -->
+  <Split bindingPanel={panel1} reverse />
+
+  <div bind:this={panel2} style="flex: 0 0 200px; background: #f0f0f0;">
+    Panel 2
+  </div>
+</div>
+```
+
+### Fixed Divider
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+</script>
+
+<!-- Without bindingPanel, the divider is fixed (non-resizable) -->
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1; background: #f0f0f0;">
+    Panel 1
+  </div>
+
+  <Split /> <!-- Fixed divider -->
+
+  <div style="flex: 1; background: #e0e0e0;">
+    Panel 2
+  </div>
+</div>
+```
+
+### Complete Resizable Layout
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let sidebar;
+  let mainContent;
+  let detailPanel;
+</script>
+
+<div style="display: flex; height: 100vh;">
+  <!-- Sidebar -->
+  <div bind:this={sidebar} style="flex: 0 0 250px; background: #2d3748; color: white; padding: 16px;">
+    <h3>Sidebar</h3>
+    <ul>
+      <li>Menu Item 1</li>
+      <li>Menu Item 2</li>
+      <li>Menu Item 3</li>
+    </ul>
+  </div>
+
+  <!-- Vertical split for sidebar -->
+  <Split bindingPanel={sidebar} direction="horizontal" width="4" />
+
+  <!-- Main content area with vertical split -->
+  <div style="flex: 1; display: flex; flex-direction: column;">
+    <!-- Top panel -->
+    <div bind:this={mainContent} style="flex: 0 0 60%; background: #f7fafc; padding: 16px;">
+      <h2>Main Content</h2>
+      <p>This is the main content area. Drag the divider below to resize.</p>
+    </div>
+
+    <!-- Horizontal split -->
+    <Split bindingPanel={mainContent} direction="vertical" width="4" />
+
+    <!-- Bottom panel -->
+    <div style="flex: 1; background: #edf2f7; padding: 16px;">
+      <h3>Details Panel</h3>
+      <p>Additional details and information</p>
+    </div>
+  </div>
+</div>
+```
+
+## Best Practices
+
+1. **Panel References**: Always bind the panel you want to resize using `bindingPanel`
+2. **Flex Layout**: Use flexbox for predictable resizing behavior
+3. **Initial Sizes**: Set reasonable initial sizes for resizable panels
+4. **Minimum Size**: The component enforces a 5px minimum panel size
+5. **User Feedback**: Cursor changes provide visual feedback during dragging
+6. **Fixed Dividers**: Don't provide `bindingPanel` for non-resizable dividers
+
+## Browser Support
+
+- Modern browsers with full flexbox support
+- Mouse events for drag functionality
+- Touch devices (with touch event handling)
+
+## Notes
+
+- The `bindingPanel` must be a valid HTML element reference
+- Minimum panel size is enforced at 5px to prevent collapse
+- Drag operation updates the panel's style directly
+- Cursor automatically changes during drag operation
+- The component uses `mousedown`, `mousemove`, and `mouseup` events

package/dist/split/README_CN.md

@@ -0,0 +1,240 @@
+# Split 分割器
+
+一个可调整大小的分割器组件，允许用户通过拖动分割线来调整相邻面板的大小。非常适合创建具有灵活面板大小的可调整布局。
+
+## 特性
+
+- **可调整面板**: 拖动以调整相邻面板的大小
+- **方向支持**: 水平和垂直方向
+- **自定义宽度**: 设置分割线的宽度
+- **反向模式**: 可选的反向拖动方向
+- **固定模式**: 可以是固定的（不可调整大小）
+- **视觉反馈**: 拖动操作期间光标变化
+- **最小尺寸**: 强制执行最小面板尺寸（5px）
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import Split from '@ticatec/uniface-element/Split';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let leftPanel;
+  let rightPanel;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div bind:this={leftPanel} style="flex: 0 0 200px; background: #f0f0f0;">
+    左侧面板
+  </div>
+  <Split bindingPanel={leftPanel} direction="horizontal" />
+  <div bind:this={rightPanel} style="flex: 1; background: #e0e0e0;">
+    右侧面板
+  </div>
+</div>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|---------|-------------|
+| `direction` | `'horizontal' \| 'vertical'` | `'vertical'` | 分割器方向 |
+| `width` | `number` | `2` | 分割线的宽度/厚度（px） |
+| `bindingPanel` | `HTMLElement \| null` | `null` | 要调整大小的面板的引用 |
+| `reverse` | `boolean` | `false` | 反向拖动方向 |
+
+## 示例
+
+### 水平分割
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let panel1;
+  let panel2;
+</script>
+
+<div style="display: flex; height: 400px;">
+  <div bind:this={panel1} style="flex: 0 0 250px; padding: 16px; background: #f5f5f5;">
+    <h3>左侧面板</h3>
+    <p>通过拖动分割线调整我的大小！</p>
+  </div>
+
+  <Split bindingPanel={panel1} direction="horizontal" width="4" />
+
+  <div style="flex: 1; padding: 16px; background: #e8e8e8;">
+    <h3>右侧面板</h3>
+    <p>此面板填充剩余空间</p>
+  </div>
+</div>
+```
+
+### 垂直分割
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let topPanel;
+  let bottomPanel;
+</script>
+
+<div style="display: flex; flex-direction: column; height: 400px;">
+  <div bind:this={topPanel} style="flex: 0 0 150px; padding: 16px; background: #f5f5f5;">
+    <h3>顶部面板</h3>
+  </div>
+
+  <Split bindingPanel={topPanel} direction="vertical" width="4" />
+
+  <div style="flex: 1; padding: 16px; background: #e8e8e8;">
+    <h3>底部面板</h3>
+  </div>
+</div>
+```
+
+### 自定义宽度
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let panel1;
+  let panel2;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div bind:this={panel1} style="flex: 0 0 200px; background: #f0f0f0;">
+    面板 1
+  </div>
+
+  <!-- 粗分割线 -->
+  <Split bindingPanel={panel1} width="8" />
+
+  <div style="flex: 1; background: #e0e0e0;">
+    面板 2
+  </div>
+</div>
+```
+
+### 反向方向
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let panel1;
+  let panel2;
+</script>
+
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1; background: #e0e0e0;">
+    面板 1（面板2缩小时展开）
+  </div>
+
+  <!-- 反向模式：向相反方向拖动 -->
+  <Split bindingPanel={panel1} reverse />
+
+  <div bind:this={panel2} style="flex: 0 0 200px; background: #f0f0f0;">
+    面板 2
+  </div>
+</div>
+```
+
+### 固定分割线
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+</script>
+
+<!-- 没有 bindingPanel 时，分割线是固定的（不可调整大小） -->
+<div style="display: flex; height: 300px;">
+  <div style="flex: 1; background: #f0f0f0;">
+    面板 1
+  </div>
+
+  <Split /> <!-- 固定分割线 -->
+
+  <div style="flex: 1; background: #e0e0e0;">
+    面板 2
+  </div>
+</div>
+```
+
+### 完整的可调整布局
+
+```svelte
+<script>
+  import Split from '@ticatec/uniface-element/Split';
+
+  let sidebar;
+  let mainContent;
+  let detailPanel;
+</script>
+
+<div style="display: flex; height: 100vh;">
+  <!-- 侧边栏 -->
+  <div bind:this={sidebar} style="flex: 0 0 250px; background: #2d3748; color: white; padding: 16px;">
+    <h3>侧边栏</h3>
+    <ul>
+      <li>菜单项 1</li>
+      <li>菜单项 2</li>
+      <li>菜单项 3</li>
+    </ul>
+  </div>
+
+  <!-- 侧边栏的垂直分割 -->
+  <Split bindingPanel={sidebar} direction="horizontal" width="4" />
+
+  <!-- 主内容区域，带有垂直分割 -->
+  <div style="flex: 1; display: flex; flex-direction: column;">
+    <!-- 顶部面板 -->
+    <div bind:this={mainContent} style="flex: 0 0 60%; background: #f7fafc; padding: 16px;">
+      <h2>主要内容</h2>
+      <p>这是主内容区域。拖动下方的分割线来调整大小。</p>
+    </div>
+
+    <!-- 水平分割 -->
+    <Split bindingPanel={mainContent} direction="vertical" width="4" />
+
+    <!-- 底部面板 -->
+    <div style="flex: 1; background: #edf2f7; padding: 16px;">
+      <h3>详情面板</h3>
+      <p>额外的详细信息和数据</p>
+    </div>
+  </div>
+</div>
+```
+
+## 最佳实践
+
+1. **面板引用**: 始终使用 `bindingPanel` 绑定要调整大小的面板
+2. **Flex 布局**: 使用 flexbox 以获得可预测的调整大小行为
+3. **初始大小**: 为可调整大小的面板设置合理的初始大小
+4. **最小尺寸**: 组件强制执行 5px 的最小面板尺寸
+5. **用户反馈**: 光标变化在拖动期间提供视觉反馈
+6. **固定分割线**: 对于不可调整大小的分割线，不提供 `bindingPanel`
+
+## 浏览器支持
+
+- 支持完整 flexbox 的现代浏览器
+- 用于拖动功能的鼠标事件
+- 触摸设备（带有触摸事件处理）
+
+## 注意事项
+
+- `bindingPanel` 必须是有效的 HTML 元素引用
+- 强制执行最小面板尺寸为 5px 以防止折叠
+- 拖动操作直接更新面板的样式
+- 光标在拖动操作期间自动变化
+- 组件使用 `mousedown`、`mousemove` 和 `mouseup` 事件

package/dist/tree-view/README.md

@@ -83,49 +83,57 @@ import TreeNodes, { TreeNode, NodeViewOptions } from "@ticatec/uniface-element/T
 
 ### TreeNode<T>
 ```typescript
-class TreeNode<T> {
-  readonly item: T;              // The actual data item
-  readonly children: ReadonlyArray<TreeNode<T>>;  // Child nodes (read-only)
-  expand: boolean;               // Whether node is expanded
-  loading: boolean;              // Whether node is loading (for lazy loading)
-  parent: TreeNode<T> | null;    // Parent node reference
+class TreeNode<T> implements ITreeNode<T> {
+  readonly item: T;                           // The actual data item
+  get children(): Array<TreeNode<T>> | null;  // Child nodes (shallow copy)
+  get level(): number;                        // Node level (root = 0)
+  expand: boolean;                            // Whether node is expanded
+  loading: boolean;                           // Whether node is loading (for lazy loading)
+  readonly parent: TreeNode<T> | null;        // Parent node reference
 
   // Methods
-  append(childItem: T): void;           // Add a child node
-  detach(): void;                       // Remove this node from parent
-  moveTo(newParent: TreeNode<T>): void; // Move to different parent
-  replace(newItem: T): void;            // Replace node data
-  removeChild(childId: any): void;      // Remove specific child
-  removeChildren(): void;               // Remove all children
+  append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;  // Add child(ren)
+  detach(): void;                                                              // Remove this node from parent
+  moveTo(newParent: TreeNode<T>): TreeNode<T>;                                 // Move to different parent
+  replace(newItem: T): void;                                                   // Replace node data
+  removeChildren(): void;                                                      // Remove all children
 }
 ```
 
-### NodeViewOptions<T>
+### ITreeNode<T>
 ```typescript
-class NodeViewOptions<T> {
-  keyField: keyof T;
-  textField: keyof T | ((data: T) => string);
-  iconField?: keyof T | ((data: T) => string);
-  cssClassField?: keyof T | ((data: T) => string);
-  styleField?: keyof T | ((data: T) => Record<string, string>);
+interface ITreeNode<T> {
+  expand: boolean;                              // Whether node is expanded
+  loading: boolean;                             // Whether node is loading
+  get level(): number;                          // Node level (root = 0)
+  get children(): Array<ITreeNode<T>> | null;   // Child nodes (read-only)
+  get item(): T;                                // Node data
 
   // Methods
-  getText(data: T): string;
-  getIcon(data: T): string | undefined;
-  getCssClass(data: T): string | undefined;
-  getStyle(data: T): Record<string, string> | undefined;
-  getKey(data: T): any;
+  append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;
+  detach(): void;
+  moveTo(newParent: ITreeNode<T>): ITreeNode<T>;
+  replace(newItem: T): void;
+  removeChildren(): void;
 }
 ```
 
-### LazyLoader
+### TreeLazyLoader
 ```typescript
-interface LazyLoader {
-  isBranch: (node: TreeNode<any>) => boolean;  // Check if node can have children
-  load: (node: TreeNode<any>) => Promise<Array<TreeNode<any>>>;  // Load children
+interface TreeLazyLoader {
+  isBranch: (node: ITreeNode<any>) => boolean;              // Check if node can have children
+  load: (node: ITreeNode<any>) => Promise<Array<any>>;      // Load children data
 }
 ```
 
+### LazyLoader (Deprecated)
+```typescript
+/**
+ * @deprecated Use TreeLazyLoader instead. Will be removed in future versions.
+ */
+type LazyLoader = TreeLazyLoader;
+```
+
 ### OnNodeSelectionChange
 ```typescript
 type OnNodeSelectionChange = (node: TreeNode<any>) => Promise<boolean>;
@@ -766,19 +774,25 @@ TreeNode is now a class with built-in methods for data manipulation:
 // Get a node and manipulate it directly
 const node = treeNodes.nodes[0];
 
-// Add a child node
+// Add a child node (or array of children)
 node.append({
   id: 'new-child',
   name: 'New Child',
   parent: node.item.id
 });
 
+// Or add multiple children at once
+node.append([
+  { id: 'child1', name: 'Child 1', parent: node.item.id },
+  { id: 'child2', name: 'Child 2', parent: node.item.id }
+]);
+
 // Remove the node from tree
 node.detach();
 
-// Move node to different parent
+// Move node to different parent (returns new node instance)
 const newParent = treeNodes.nodes[1];
-node.moveTo(newParent);
+const movedNode = node.moveTo(newParent);
 
 // Replace node data
 node.replace({
@@ -787,15 +801,13 @@ node.replace({
   parent: node.item.parent
 });
 
-// Remove specific child
-node.removeChild('child-id');
-
 // Remove all children
 node.removeChildren();
 
-// Access properties (read-only)
+// Access properties
 console.log(node.item);      // Node data
-console.log(node.children);  // Read-only child array
+console.log(node.children);  // Shallow copy of children array
+console.log(node.level);     // Node level (root = 0)
 console.log(node.expand);    // Expanded state
 console.log(node.parent);    // Parent node
 ```

package/dist/tree-view/README_CN.md

@@ -69,6 +69,7 @@ import TreeNodes, { type TreeNode } from "@ticatec/uniface-element/TreeNodes";
 | `textField` | `string \| GetText<any>` | 必需 | 节点文本的字段名称或获取文本的函数 |
 | `activeNode` | `any` | `null` | 当前选中的/活动节点 |
 | `style` | `string` | `""` | 附加 CSS 样式 |
+| `title` | `string` | `undefined` | 可选的标题，显示在树视图顶部（固定位置，不滚动） |
 | `lazyLoader` | `LazyLoader \| null` | `null` | 延迟加载配置 |
 | `isVisible` | `NodeVisibleFun` | `null` | 判断节点可见性的函数 |
 | `onchange` | `OnNodeSelectionChange` | `null` | 节点选择更改时的回调函数 |
@@ -83,22 +84,57 @@ import TreeNodes, { type TreeNode } from "@ticatec/uniface-element/TreeNodes";
 
 ### TreeNode<T>
 ```typescript
-interface TreeNode<T> {
-  item: T;              // 实际数据项
-  children?: Array<TreeNode<T>>;  // 子节点
-  expand?: boolean;     // 节点是否展开
-  parent?: TreeNode<T>; // 父节点引用
+class TreeNode<T> implements ITreeNode<T> {
+  readonly item: T;                           // 节点的数据对象
+  get children(): Array<TreeNode<T>> | null;  // 子节点（浅拷贝）
+  get level(): number;                        // 节点层级（根节点为 0）
+  expand: boolean;                            // 是否展开（显示子节点）
+  loading: boolean;                           // 是否正在加载（用于懒加载）
+  readonly parent: TreeNode<T> | null;        // 父节点引用
+
+  // 方法
+  append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;  // 添加子节点
+  detach(): void;                                                              // 从父节点中分离
+  moveTo(newParent: TreeNode<T>): TreeNode<T>;                                 // 移动到其他父节点
+  replace(newItem: T): void;                                                   // 替换节点数据
+  removeChildren(): void;                                                      // 删除所有子节点
 }
 ```
 
-### LazyLoader
+### ITreeNode<T>
 ```typescript
-interface LazyLoader {
-  isBranch: (node: TreeNode<any>) => boolean;  // 判断节点是否可有子节点
-  load: (node: TreeNode<any>) => Promise<Array<TreeNode<any>>>;  // 加载子节点
+interface ITreeNode<T> {
+  expand: boolean;                              // 是否展开
+  loading: boolean;                             // 是否正在加载
+  get level(): number;                          // 节点层级（根节点为 0）
+  get children(): Array<ITreeNode<T>> | null;   // 子节点（只读）
+  get item(): T;                                // 节点数据
+
+  // 方法
+  append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;
+  detach(): void;
+  moveTo(newParent: ITreeNode<T>): ITreeNode<T>;
+  replace(newItem: T): void;
+  removeChildren(): void;
 }
 ```
 
+### TreeLazyLoader
+```typescript
+interface TreeLazyLoader {
+  isBranch: (node: ITreeNode<any>) => boolean;              // 判断节点是否可为分支
+  load: (node: ITreeNode<any>) => Promise<Array<any>>;      // 加载子节点数据
+}
+```
+
+### LazyLoader (已弃用)
+```typescript
+/**
+ * @deprecated 使用 TreeLazyLoader 代替。LazyLoader 已弃用，将在未来版本中移除。
+ */
+type LazyLoader = TreeLazyLoader;
+```
+
 ### OnNodeSelectionChange
 ```typescript
 type OnNodeSelectionChange = (node: TreeNode<any>) => Promise<boolean>;