@ticatec/uniface-element 0.3.16 → 0.3.18

package/dist/lib/TreeNode_README.md

@@ -2,52 +2,88 @@
 
 ## Overview
 
-`TreeNode` is the core data type used to represent nodes in a tree structure. It contains the node's data, child nodes, expansion state, and provides convenient methods to manipulate the node itself and its children.
+`TreeNode` is a class that represents nodes in a tree structure. It encapsulates the node's data, child nodes, expansion state, and provides convenient methods to manipulate the node itself and its children.
 
-Every node obtained from `TreeNodes` automatically has bound operation methods that can be called directly.
+Each node created from `TreeNodes` or `CommonTreeNodes` is an instance of the `TreeNode` class with built-in methods.
 
-## Type Definition
+## TreeNode Class
 
 ```typescript
-interface TreeNode<T> {
-  /** The node's data object */
-  item: T;
+class TreeNode<T> {
+  /** The node's data object (readonly) */
+  public readonly item: T;
 
   /** Whether the node is expanded (showing children) */
-  expand?: boolean;
+  public expand: boolean;
 
-  /** Array of child nodes */
-  children?: TreeNode<T>[];
-}
-```
+  /** Whether the node is currently loading (for lazy loading) */
+  public loading: boolean;
 
-### TreeNodeWithMethods<T>
+  /** Parent node (null for root nodes) */
+  public parent: TreeNode<T> | null;
 
-This is the actual node type in use, extending `TreeNode<T>` with operation methods:
+  /** Child nodes (readonly, use methods to modify) */
+  get children(): ReadonlyArray<TreeNode<T>>;
 
-```typescript
-interface TreeNodeWithMethods<T> extends TreeNode<T> {
   /** Add a child node to the current node */
-  append: (childItem: T) => void;
+  append(childItem: T): void;
 
   /** Remove the current node (from its parent) */
-  remove: () => void;
-
-  /** Replace the current node's data */
-  replace: (newItem: T) => void;
+  detach(): void;
 
   /** Move the current node to a different parent */
-  moveTo: (newParentId: string) => void;
+  moveTo(newParent: TreeNode<T>): void;
+
+  /** Replace the current node's data */
+  replace(newItem: T): void;
 
-  /** Remove a specific child node */
-  removeChild: (childId: any) => void;
+  /** Remove a specific child node by ID */
+  removeChild(childId: any): void;
 
   /** Remove all child nodes */
-  removeChildren: () => void;
+  removeChildren(): void;
 }
 ```
 
-## Node Methods
+## NodeViewOptions Class
+
+The `NodeViewOptions` class handles view configuration for tree nodes, separating display concerns from data:
+
+```typescript
+class NodeViewOptions<T> {
+  /** Field name for unique identifier */
+  keyField: keyof T;
+
+  /** Field name or function for display text */
+  textField: keyof T | ((data: T) => string);
+
+  /** Optional: Field name or function for icon */
+  iconField?: keyof T | ((data: T) => string);
+
+  /** Optional: Field name or function for CSS class */
+  cssClassField?: keyof T | ((data: T) => string);
+
+  /** Optional: Field name or function for inline styles */
+  styleField?: keyof T | ((data: T) => Record<string, string>);
+
+  /** Get display text from data */
+  getText(data: T): string;
+
+  /** Get icon from data */
+  getIcon(data: T): string | undefined;
+
+  /** Get CSS class from data */
+  getCssClass(data: T): string | undefined;
+
+  /** Get styles from data */
+  getStyle(data: T): Record<string, string> | undefined;
+
+  /** Get unique key from data */
+  getKey(data: T): any;
+}
+```
+
+## TreeNode Methods
 
 ### 1. append(childItem)
 
@@ -62,33 +98,31 @@ Add a child node to the current node.
 parentNode.append({
   id: 123,
   name: "New Child",
-  parent: parentNode.item.id  // Optional, will be set automatically
+  parentId: parentNode.item.id  // Will be set automatically
 });
 ```
 
 **Notes**:
-- **Auto-load lazy nodes**: When a node is selected (clicked or when `activeNode` is set externally), if it's a lazy node and not loaded (`children === null`), TreeView will automatically trigger `lazyLoader.load()` to load child nodes
-- **Manually add child nodes**: You can manually call `append()` to add child nodes
-  - If the node is not yet loaded, it will automatically initialize the `children` array
-  - The node will transition from leaf to branch, UI will display the branch icon
+- 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
 
 ---
 
-### 2. remove()
+### 2. detach()
 
-Remove the current node (from its parent).
+Remove the current node from its parent.
 
 **Parameter**: None
 
 **Example**:
 ```typescript
-// Remove the node
-node.remove();
+// Remove the node from its parent
+node.detach();
 
 // Clear reference after removal
-activeNode.remove();
+activeNode.detach();
 activeNode = null;
 ```
 
@@ -96,10 +130,40 @@ activeNode = null;
 - Removes from parent's `children` array
 - Deletes from internal map
 - If it's a root node, removes from root node list
+- Triggers version update for reactive updates
 
 ---
 
-### 3. replace(newItem)
+### 3. moveTo(newParent)
+
+Move the current node to a different parent node.
+
+**Parameter**:
+- `newParent: TreeNode<T>` - The new parent node (not an ID)
+
+**Example**:
+```typescript
+// Move to a different parent node
+node.moveTo(newParentNode);
+
+// Get parent node first
+const parentNode = treeNodes.nodeMap.get(parentId);
+if (parentNode) {
+  node.moveTo(parentNode);
+}
+```
+
+**Notes**:
+- Takes a TreeNode instance, not an ID
+- Automatically updates the node's `parentKeyField` in data
+- Removes from current parent's `children`
+- Adds to new parent's `children`
+- If a sort function is configured, will automatically re-sort
+- Triggers version update for reactive updates
+
+---
+
+### 4. replace(newItem)
 
 Replace the current node's data.
 
@@ -127,32 +191,7 @@ node.replace({
 - Usually need to keep the `id` field unchanged
 - If a sort function is configured and sort field changes, will automatically re-sort
 - Automatically triggers view update
-
----
-
-### 4. moveTo(newParentId)
-
-Move the current node to a different parent.
-
-**Parameter**:
-- `newParentId: string | number` - New parent node's ID
-
-**Example**:
-```typescript
-// Move to specified parent
-node.moveTo("parent-123");
-
-// Use another node's ID
-node.moveTo(anotherNode.item.id);
-```
-
-**Notes**:
-- Automatically updates the node's `parent` field
-- Removes from current parent's `children`
-- Adds to new parent's `children`
-- **Lazy node handling**: If the new parent is lazy-loaded and not loaded (`children === null`), it will automatically initialize the `children` array
-  - The new parent will transition from leaf to branch, UI will display the branch icon
-  - When the user expands the node later, the lazyLoader will load child nodes that merge with manually added nodes
+- Preserves children, expand state, and loading state
 
 ---
 
@@ -177,6 +216,7 @@ parentNode.removeChild(childId);
 - 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
 
 ---
 
@@ -200,37 +240,68 @@ parentNode.append(newChildData);
 - Removes all children and their descendants
 - Node's `expand` state remains unchanged
 - Internal map is updated accordingly
+- Triggers version update for reactive updates
+
+## CommonTreeNodes Options
+
+When creating a tree, you can configure it with these options:
+
+```typescript
+interface TreeNodeOptions<T> {
+  /** Field name for unique identifier (default: 'id') */
+  keyField?: keyof T;
+
+  /** Field name or function for display text (default: 'text') */
+  textField?: keyof T | ((data: T) => string);
+
+  /** Field name for parent reference (default: 'parentId') */
+  parentKeyField?: keyof T;
+
+  /** Function to check if data is a root node */
+  checkIsRoot: (data: T) => boolean;
+
+  /** Optional: Function to check if node is a branch (has children) */
+  checkIsDirectory?: (node: TreeNode<T>) => boolean;
+
+  /** Optional: Comparison function for sorting */
+  compareFun?: (o1: T, o2: T) => number | undefined;
+
+  /** Optional: Expand depth (default: 1) */
+  expendDepth?: number;
+}
+```
 
 ## Complete Usage Example
 
 ```svelte
 <script>
   import TreeView from "@ticatec/uniface-element/TreeView";
-  import TreeNodes, { type TreeNode } from "@ticatec/uniface-element/TreeNodes";
+  import { CommonTreeNodes, type TreeNode } from "@ticatec/uniface-element/lib/TreeNodes";
 
   // Data type definition
   interface MyData {
     id: number;
     name: string;
-    parent: number | null;
+    parentId: number | null;
   }
 
-  let activeNode: TreeNodeWithMethods<MyData> | null = null;
+  let activeNode: TreeNode<MyData> | null = null;
 
   // Create tree structure
-  const treeNodes = new TreeNodes<MyData>({
+  const treeNodes = new CommonTreeNodes<MyData>({
     keyField: 'id',
     textField: 'name',
-    parentKeyField: 'parent',
-    checkIsRoot: (item) => item.parent === null,
-    checkIsDirectory: (node) => node.children != null
+    parentKeyField: 'parentId',
+    checkIsRoot: (item) => item.parentId === null,
+    checkIsDirectory: (node) => node.children.length > 0,
+    expendDepth: 2
   });
 
   // Initialize data
   treeNodes.setData([
-    { id: 1, name: "Root", parent: null },
-    { id: 2, name: "Child 1", parent: 1 },
-    { id: 3, name: "Child 2", parent: 1 }
+    { id: 1, name: "Root", parentId: null },
+    { id: 2, name: "Child 1", parentId: 1 },
+    { id: 3, name: "Child 2", parentId: 1 }
   ]);
 
   // Add child node
@@ -240,14 +311,14 @@ parentNode.append(newChildData);
     activeNode.append({
       id: Date.now(),
       name: "New Child",
-      parent: activeNode.item.id
+      parentId: activeNode.item.id
     });
   }
 
   // Delete current node
   function deleteCurrentNode() {
     if (!activeNode) return;
-    activeNode.remove();
+    activeNode.detach();
     activeNode = null;
   }
 
@@ -275,7 +346,10 @@ parentNode.append(newChildData);
   // Move node
   function moveNodeTo(newParentId: number) {
     if (!activeNode) return;
-    activeNode.moveTo(newParentId);
+    const newParent = treeNodes.nodeMap.get(newParentId);
+    if (newParent) {
+      activeNode.moveTo(newParent);
+    }
   }
 </script>
 
@@ -285,7 +359,7 @@ parentNode.append(newChildData);
     version={treeNodes.version}
     textField="name"
     bind:activeNode
-    checkIsDirectory={(node) => node.children != null}
+    checkIsDirectory={(node) => node.children.length > 0}
   />
 
   {#if activeNode}
@@ -303,30 +377,64 @@ parentNode.append(newChildData);
 
 ## Difference from TreeNodes Class Methods
 
-`TreeNode` methods and `TreeNodes` class methods have clear responsibilities:
+`TreeNode` instance methods and `CommonTreeNodes`/`TreeNodes` class methods have clear responsibilities:
 
-### TreeNode Node Methods (Recommended for Operating on Specific Nodes)
+### TreeNode Instance Methods (For Operating on Specific Node Instances)
 
 ```typescript
-// Operate directly on node - Recommended when you have a node instance
+// Operate directly on a node instance
 node.append(childItem);      // Add child to this node
-node.remove();               // Remove this node
+node.detach();               // Remove this node from its parent
 node.replace(newItem);       // Replace this node's data
-node.moveTo(newParentId);    // Move this node
+node.moveTo(newParentNode);  // Move this node to another parent
 node.removeChild(childId);   // Remove specific child
 node.removeChildren();       // Remove all children
 ```
 
-### TreeNodes Class Methods (For Batch Operations or Initialization)
+### CommonTreeNodes/TreeNodes Class Methods (For Tree-Level Operations)
 
 ```typescript
-// Class-level operations - Suitable when you only have data
+// Tree-level operations
 treeNodes.setData(data);           // Initialize tree structure
 treeNodes.append(item);            // Add new node (auto-find parent)
 treeNodes.nodes;                   // Get root node list
 treeNodes.version;                 // Get version number
-treeNodes.getHierarchyList();      // Get expanded node list
-treeNodes.extractDirectories(item); // Extract directory structure
+treeNodes.getHierarchyList();      // Get expanded node list (TreeNodes only)
+treeNodes.extractDirectories(item); // Extract directory structure (TreeNodes only)
+```
+
+## Key Properties
+
+### item (readonly)
+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
+- `removeChildren()` - remove all children
+
+### expand
+Controls whether the node is expanded (showing its children). Can be set directly:
+```typescript
+node.expand = true;   // Expand the node
+node.expand = false;  // Collapse the node
+```
+
+### loading
+Indicates if the node is currently loading data (used for lazy loading). Can be set directly:
+```typescript
+node.loading = true;  // Show loading state
+node.loading = false; // Hide loading state
+```
+
+### parent
+Reference to the parent node. Is `null` for root nodes.
+
+```typescript
+if (node.parent) {
+  console.log("Parent name:", node.parent.item.name);
+}
 ```
 
 ## Reactive Updates
@@ -359,10 +467,14 @@ const node = treeNodes.nodeMap.get(nodeId);
 ### Q: How to iterate over child nodes?
 
 ```typescript
-if (node.children) {
-  node.children.forEach(child => {
-    console.log(child.item.name);
-  });
+// children is readonly, but you can iterate over it
+node.children.forEach(child => {
+  console.log(child.item.name);
+});
+
+// Or use for...of
+for (const child of node.children) {
+  console.log(child.item.name);
 }
 ```
 
@@ -370,40 +482,24 @@ if (node.children) {
 
 ```typescript
 function findChild(node: TreeNode, childId: number) {
-  if (!node.children) return null;
   return node.children.find(child => child.item.id === childId) || null;
 }
 ```
 
-### Q: How do lazy-loaded nodes work?
-
-For nodes using lazyLoader (`children === null`):
-
-```typescript
-// ✅ When a node is selected, TreeView automatically triggers loading
-// When you click a node or set activeNode:
-// - If it's a lazy node and not loaded
-// - Automatically calls lazyLoader.load()
-// - children is set, node transitions to branch
-
-// Manually add child nodes
-lazyNode.append(childItem);     // Initialize children array and add child node
-                                // Node transitions to branch, shows branch icon
-
-lazyNode.moveTo(parentId);      // Moving to this node will initialize children
+### Q: Can I modify the children array directly?
 
-// removeChild() and removeChildren() have no effect before loading
-lazyNode.removeChild(id);       // No effect when children is null
-lazyNode.removeChildren();      // No effect when children is null
-```
+No. The `children` property is read-only. Use the provided methods instead:
+- `append()` to add
+- `removeChild()` to remove specific child
+- `removeChildren()` to remove all
 
 ### Q: How to recursively operate on all descendants?
 
 ```typescript
 function traverse(node: TreeNode, callback: (node: TreeNode) => void) {
   callback(node);
-  if (node.children) {
-    node.children.forEach(child => traverse(child, callback));
+  for (const child of node.children) {
+    traverse(child, callback);
   }
 }
 
@@ -414,36 +510,68 @@ traverse(rootNode, (node) => {
 });
 ```
 
+### Q: What's the difference between TreeNode and NodeViewOptions?
+
+- **TreeNode**: Represents the data structure. Each node is an instance with methods for manipulation.
+- **NodeViewOptions**: Configuration class for how nodes should be displayed (text field, icon, CSS, etc.)
+
+This separation allows TreeNode to be used in different contexts (TreeView, TreeDataGrid, etc.) without coupling to view-specific concerns.
+
 ## Best Practices
 
 1. **Prefer node methods**: When you have a node instance, calling node methods directly is more intuitive
 
 2. **Keep ID unchanged**: When using `replace()`, ensure the `id` field remains unchanged
 
-3. **Check children existence**: Before operating on child nodes, check if `node.children` exists first
+3. **Use moveTo correctly**: The `moveTo()` method takes a TreeNode instance, not an ID:
+   ```typescript
+   // ❌ Wrong
+   node.moveTo(123);
 
-4. **Handle lazy nodes**: For lazy-loaded nodes, wait for loading to complete before operations
+   // ✅ Correct
+   const parentNode = treeNodes.nodeMap.get(123);
+   node.moveTo(parentNode);
+   ```
 
-5. **Version management**: No need to manually manage versions, node methods update automatically
+4. **Version management**: No need to manually manage versions, node methods update automatically
 
-6. **Type safety**: Use TypeScript generics to ensure type safety
+5. **Type safety**: Use TypeScript generics to ensure type safety
 
 ```typescript
 // ✅ Recommended: Use generics
-const treeNodes = new TreeNodes<MyData>({ ... });
+const treeNodes = new CommonTreeNodes<MyData>({ ... });
 
 // Node type is automatically inferred
 node.append({ id: 1, name: "..." });  // Type checking
 ```
 
+6. **Children is readonly**: Don't try to modify the children array directly. Always use the provided methods.
+
 ## Performance Considerations
 
 - All node methods have O(1) or O(n) time complexity, where n is the number of child nodes
 - Delete operations also remove from internal map to maintain consistency
 - For large batch operations, consider using `setData()` to rebuild the tree structure
 
+## Architecture
+
+### Decoupling from View
+
+TreeNode is designed to be independent of any specific view component:
+- No view-specific logic in TreeNode
+- NodeViewOptions handles view configuration separately
+- Can be used in TreeView, TreeDataGrid, or any other tree-based component
+
+### Data Immutability
+
+The `item` property is readonly to ensure data integrity:
+- Prevents accidental mutations
+- Makes state changes explicit through `replace()` method
+- Helps with debugging and state tracking
+
 ## Related Components
 
-- `TreeNodes` - Tree management class
+- `CommonTreeNodes` - Base tree management class
+- `TreeNodes` - Extended tree management with hierarchy features
 - `TreeView` - Tree view component
-- `LazyLoader` - Lazy loading interface
+- `NodeViewOptions` - View configuration class