@ticatec/uniface-element 0.3.18 → 0.3.19

package/dist/form-field/README_CN.md

@@ -0,0 +1,193 @@
+# FormField 表单字段
+
+一个表单字段包装组件，为表单输入提供一致的布局，包括标签、错误消息和必填指示器。
+
+## 特性
+
+- **标签支持**: 显示带可选后缀的标签
+- **必填指示器**: 必填字段的视觉指示器
+- **错误显示**: 显示验证错误消息
+- **灵活布局**: 中心或顶部标签对齐
+- **自定义样式**: 标签和容器的自定义样式
+- **响应式高度**: 可调整的字段高度
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import FormField from '@ticatec/uniface-element/FormField';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<FormField label="用户名" required>
+  <TextEditor placeholder="请输入用户名" />
+</FormField>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|---------|-------------|
+| `label` | `string` | `'Label:'` | 字段标签文本 |
+| `labelSuffix` | `string` | `':'` | 标签后的后缀文本 |
+| `required` | `boolean` | `false` | 显示必填指示器 (*) |
+| `error` | `string \| null` | `null` | 要显示的错误消息 |
+| `labelAlignment` | `'center' \| 'top'` | `'center'` | 标签垂直对齐方式 |
+| `labelStyle` | `string \| null` | `null` | 标签的自定义CSS |
+| `style` | `string` | `''` | 容器的自定义CSS |
+| `height` | `string` | `'auto'` | 字段区域的高度 |
+| `class` | `string` | `''` | CSS类名 |
+
+## 示例
+
+### 基本表单字段
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<FormField label="邮箱">
+  <TextEditor type="email" placeholder="user@example.com" />
+</FormField>
+```
+
+### 必填字段
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<FormField label="密码" required>
+  <TextEditor type="password" placeholder="请输入密码" />
+</FormField>
+```
+
+### 带错误消息
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let error = '此字段为必填项';
+</script>
+
+<FormField label="用户名" {error} required>
+  <TextEditor placeholder="请输入用户名" />
+</FormField>
+```
+
+### 顶部标签对齐
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<FormField label="描述" labelAlignment="top">
+  <TextEditor placeholder="请输入描述" />
+</FormField>
+```
+
+### 自定义标签样式
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<FormField
+  label="重要字段"
+  labelStyle="color: #007acc; font-weight: bold;"
+>
+  <TextEditor placeholder="请输入值" />
+</FormField>
+```
+
+### 完整表单示例
+
+```svelte
+<script>
+  import FormField from '@ticatec/uniface-element/FormField';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+  import Button from '@ticatec/uniface-element/Button';
+
+  let formData = {
+    username: '',
+    email: '',
+    password: ''
+  };
+
+  let errors = {
+    username: '',
+    email: '',
+    password: ''
+  };
+
+  function validate() {
+    if (!formData.username) {
+      errors.username = '用户名为必填项';
+    }
+    if (!formData.email) {
+      errors.email = '邮箱为必填项';
+    }
+    if (!formData.password) {
+      errors.password = '密码为必填项';
+    }
+  }
+
+  function handleSubmit() {
+    validate();
+    if (Object.values(errors).every(e => !e)) {
+      console.log('表单提交:', formData);
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <FormField label="用户名" required error={errors.username}>
+    <TextEditor bind:value={formData.username} placeholder="请输入用户名" />
+  </FormField>
+
+  <FormField label="邮箱" required error={errors.email}>
+    <TextEditor bind:value={formData.email} type="email" placeholder="user@example.com" />
+  </FormField>
+
+  <FormField label="密码" required error={errors.password}>
+    <TextEditor bind:value={formData.password} type="password" placeholder="请输入密码" />
+  </FormField>
+
+  <Button type="primary" onclick={handleSubmit}>提交</Button>
+</form>
+```
+
+## 最佳实践
+
+1. **始终使用标签**: 为可访问性提供清晰、描述性的标签
+2. **标记必填字段**: 对必填字段使用 `required` 属性
+3. **显示错误**: 在字段下方显示验证错误
+4. **一致对齐**: 在整个表单中使用相同的标签对齐方式
+5. **自定义样式**: 需要特殊强调时使用 labelStyle
+
+## 无障碍访问
+
+- 表单字段的正确标签关联
+- 屏幕阅读器的必填指示器
+- 验证反馈的错误消息显示
+- 语义化HTML结构

package/dist/form-panel/flex-form/FlexForm.svelte

@@ -3,7 +3,7 @@
     export let fieldLayout: 'vertical' | 'horizontal' = 'vertical';
 
 </script>
-<div class="flex-form" class:field-layout-horizontal={fieldLayout=='horizontal'}  {style}>
+<div class="flex-form" class:field-layout-horizontal={fieldLayout=='horizontal'} {style}>
     <div>
         <slot/>
     </div>

package/dist/inline-cell-editor/README.md

@@ -0,0 +1,116 @@
+# InlineCellEditor
+
+A lightweight wrapper component for inline editing in table cells or other constrained spaces.
+
+## Features
+
+- **Minimal Wrapper**: Simple slot-based component for maximum flexibility
+- **Inline Editing**: Designed for inline editing scenarios
+- **Custom Styling**: Accepts custom styles
+- **Focus Handling**: Built-in focus event handling
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<InlineCellEditor>
+  <TextEditor placeholder="Edit inline..." />
+</InlineCellEditor>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | Custom CSS styles |
+
+## Examples
+
+### Basic Inline Editor
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let value = '';
+</script>
+
+<InlineCellEditor>
+  <TextEditor bind:value={value} placeholder="Click to edit" />
+</InlineCellEditor>
+```
+
+### In Table Cells
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let data = [
+    { name: 'Item 1', price: 100 },
+    { name: 'Item 2', price: 200 }
+  ];
+</script>
+
+<table>
+  {#each data as item}
+    <tr>
+      <td>
+        <InlineCellEditor>
+          <TextEditor bind:value={item.name} />
+        </InlineCellEditor>
+      </td>
+      <td>
+        <InlineCellEditor>
+          <TextEditor bind:value={item.price} type="number" />
+        </InlineCellEditor>
+      </td>
+    </tr>
+  {/each}
+</table>
+```
+
+### With Custom Styling
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let value = '';
+</script>
+
+<InlineCellEditor style="padding: 4px; background: #f5f5f5;">
+  <TextEditor bind:value={value} compact />
+</InlineCellEditor>
+```
+
+## Use Cases
+
+- **Table Cell Editing**: Edit data directly in table cells
+- **Form Grids**: Compact editing in form layouts
+- **List Items**: Inline editing in list views
+- **Data Grids**: Spreadsheet-like editing experience
+
+## Best Practices
+
+1. **Use with Compact Editors**: Pair with compact form components
+2. **Minimal Styling**: Keep inline editors simple and unobtrusive
+3. **Focus Management**: Ensure proper focus handling for accessibility
+4. **Validation**: Implement validation on blur or change events

package/dist/inline-cell-editor/README_CN.md

@@ -0,0 +1,116 @@
+# InlineCellEditor 内联单元格编辑器
+
+一个轻量级的包装组件，用于表格单元格或其他受限空间中的内联编辑。
+
+## 特性
+
+- **最小化包装**: 基于插槽的简单组件，最大化灵活性
+- **内联编辑**: 专为内联编辑场景设计
+- **自定义样式**: 接受自定义样式
+- **焦点处理**: 内置焦点事件处理
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+```typescript
+import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+</script>
+
+<InlineCellEditor>
+  <TextEditor placeholder="点击编辑..." />
+</InlineCellEditor>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | 自定义CSS样式 |
+
+## 示例
+
+### 基本内联编辑器
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let value = '';
+</script>
+
+<InlineCellEditor>
+  <TextEditor bind:value={value} placeholder="点击编辑" />
+</InlineCellEditor>
+```
+
+### 在表格单元格中
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let data = [
+    { name: '项目1', price: 100 },
+    { name: '项目2', price: 200 }
+  ];
+</script>
+
+<table>
+  {#each data as item}
+    <tr>
+      <td>
+        <InlineCellEditor>
+          <TextEditor bind:value={item.name} />
+        </InlineCellEditor>
+      </td>
+      <td>
+        <InlineCellEditor>
+          <TextEditor bind:value={item.price} type="number" />
+        </InlineCellEditor>
+      </td>
+    </tr>
+  {/each}
+</table>
+```
+
+### 自定义样式
+
+```svelte
+<script>
+  import InlineCellEditor from '@ticatec/uniface-element/InlineCellEditor';
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+
+  let value = '';
+</script>
+
+<InlineCellEditor style="padding: 4px; background: #f5f5f5;">
+  <TextEditor bind:value={value} compact />
+</InlineCellEditor>
+```
+
+## 使用场景
+
+- **表格单元格编辑**: 直接在表格单元格中编辑数据
+- **表单网格**: 表单布局中的紧凑编辑
+- **列表项**: 列表视图中的内联编辑
+- **数据网格**: 类似电子表格的编辑体验
+
+## 最佳实践
+
+1. **使用紧凑编辑器**: 与紧凑的表单组件配对使用
+2. **最小化样式**: 保持内联编辑器简单且不突兀
+3. **焦点管理**: 确保正确的焦点处理以实现无障碍访问
+4. **验证**: 在模糊或更改事件上实现验证

package/dist/lib/TreeNode_README.md

@@ -9,7 +9,7 @@ Each node created from `TreeNodes` or `CommonTreeNodes` is an instance of the `T
 ## TreeNode Class
 
 ```typescript
-class TreeNode<T> {
+class TreeNode<T> implements ITreeNode<T> {
   /** The node's data object (readonly) */
   public readonly item: T;
 
@@ -20,26 +20,26 @@ class TreeNode<T> {
   public loading: boolean;
 
   /** Parent node (null for root nodes) */
-  public parent: TreeNode<T> | null;
+  public readonly parent: TreeNode<T> | null;
 
-  /** Child nodes (readonly, use methods to modify) */
-  get children(): ReadonlyArray<TreeNode<T>>;
+  /** Node level (root = 0) */
+  get level(): number;
 
-  /** Add a child node to the current node */
-  append(childItem: T): void;
+  /** Child nodes (shallow copy, use methods to modify) */
+  get children(): Array<TreeNode<T>> | null;
+
+  /** Add child(ren) to the current node */
+  append(childItem: T | Array<T>): ITreeNode<T> | Array<ITreeNode<T>>;
 
   /** Remove the current node (from its parent) */
   detach(): void;
 
-  /** Move the current node to a different parent */
-  moveTo(newParent: TreeNode<T>): void;
+  /** Move the current node to a different parent (returns new node) */
+  moveTo(newParent: TreeNode<T>): TreeNode<T>;
 
   /** Replace the current node's data */
   replace(newItem: T): void;
 
-  /** Remove a specific child node by ID */
-  removeChild(childId: any): void;
-
   /** Remove all child nodes */
   removeChildren(): void;
 }
@@ -87,25 +87,33 @@ class NodeViewOptions<T> {
 
 ### 1. append(childItem)
 
-Add a child node to the current node.
+Add child(ren) to the current node.
 
-**Parameter**:
-- `childItem: T` - The child node's data object
+**Parameters**:
+- `childItem: T | Array<T>` - The child node's data object or array of child objects
 
 **Example**:
 ```typescript
-// Pass data object directly
+// Add a single child
 parentNode.append({
   id: 123,
   name: "New Child",
   parentId: parentNode.item.id  // Will be set automatically
 });
+
+// Add multiple children at once
+parentNode.append([
+  { id: 124, name: "Child 1", parentId: parentNode.item.id },
+  { id: 125, name: "Child 2", parentId: parentNode.item.id }
+]);
 ```
 
+**Returns**:
+- `ITreeNode<T> | Array<ITreeNode<T>>` - The added child node(s)
+
 **Notes**:
 - Automatically initializes children array if needed
 - If a sort function is configured, nodes will be automatically sorted
-- The parent's `expand` is automatically set to `true`
 - Triggers version update for reactive updates
 
 ---
@@ -195,32 +203,7 @@ node.replace({
 
 ---
 
-### 5. removeChild(childId)
-
-Remove a specific child node.
-
-**Parameter**:
-- `childId: any` - ID of the child node to remove
-
-**Example**:
-```typescript
-// Remove child with specific ID
-parentNode.removeChild(123);
-
-// Use variable
-const childId = childNode.item.id;
-parentNode.removeChild(childId);
-```
-
-**Notes**:
-- Only removes direct children, not grandchildren recursively
-- Silently ignores if child doesn't exist
-- All descendants of the child node are also removed
-- Triggers version update for reactive updates
-
----
-
-### 6. removeChildren()
+### 5. removeChildren()
 
 Remove all child nodes.
 
@@ -322,12 +305,6 @@ interface TreeNodeOptions<T> {
     activeNode = null;
   }
 
-  // Delete specific child
-  function deleteChild(childId: number) {
-    if (!activeNode) return;
-    activeNode.removeChild(childId);
-  }
-
   // Clear all children
   function clearChildren() {
     if (!activeNode) return;
@@ -383,11 +360,10 @@ interface TreeNodeOptions<T> {
 
 ```typescript
 // Operate directly on a node instance
-node.append(childItem);      // Add child to this node
+node.append(childItem);      // Add child(ren) to this node
 node.detach();               // Remove this node from its parent
 node.replace(newItem);       // Replace this node's data
 node.moveTo(newParentNode);  // Move this node to another parent
-node.removeChild(childId);   // Remove specific child
 node.removeChildren();       // Remove all children
 ```
 
@@ -409,9 +385,8 @@ treeNodes.extractDirectories(item); // Extract directory structure (TreeNodes on
 The data object stored in the node. Cannot be modified directly. Use `replace()` to update data.
 
 ### children (readonly)
-Returns a read-only array of child nodes. To modify children, use the methods:
-- `append()` - add a child
-- `removeChild()` - remove a specific child
+Returns a shallow copy of the child nodes array. To modify children, use the methods:
+- `append()` - add child(ren)
 - `removeChildren()` - remove all children
 
 ### expand
@@ -488,10 +463,10 @@ function findChild(node: TreeNode, childId: number) {
 
 ### Q: Can I modify the children array directly?
 
-No. The `children` property is read-only. Use the provided methods instead:
-- `append()` to add
-- `removeChild()` to remove specific child
-- `removeChildren()` to remove all
+No. The `children` property returns a shallow copy. Use the provided methods instead:
+- `append()` to add child(ren)
+- `removeChildren()` to remove all children
+- To remove a specific child, iterate through children and call `detach()` on the child node
 
 ### Q: How to recursively operate on all descendants?