@ticatec/uniface-element 0.3.15 → 0.3.16

package/dist/lib/TreeNode_README.md

@@ -0,0 +1,449 @@
+# TreeNode - Tree Node Data Structure
+
+## 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.
+
+Every node obtained from `TreeNodes` automatically has bound operation methods that can be called directly.
+
+## Type Definition
+
+```typescript
+interface TreeNode<T> {
+  /** The node's data object */
+  item: T;
+
+  /** Whether the node is expanded (showing children) */
+  expand?: boolean;
+
+  /** Array of child nodes */
+  children?: TreeNode<T>[];
+}
+```
+
+### TreeNodeWithMethods<T>
+
+This is the actual node type in use, extending `TreeNode<T>` with operation methods:
+
+```typescript
+interface TreeNodeWithMethods<T> extends TreeNode<T> {
+  /** Add a child node to the current node */
+  append: (childItem: T) => void;
+
+  /** Remove the current node (from its parent) */
+  remove: () => void;
+
+  /** Replace the current node's data */
+  replace: (newItem: T) => void;
+
+  /** Move the current node to a different parent */
+  moveTo: (newParentId: string) => void;
+
+  /** Remove a specific child node */
+  removeChild: (childId: any) => void;
+
+  /** Remove all child nodes */
+  removeChildren: () => void;
+}
+```
+
+## Node Methods
+
+### 1. append(childItem)
+
+Add a child node to the current node.
+
+**Parameter**:
+- `childItem: T` - The child node's data object
+
+**Example**:
+```typescript
+// Pass data object directly
+parentNode.append({
+  id: 123,
+  name: "New Child",
+  parent: parentNode.item.id  // Optional, 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
+- If a sort function is configured, nodes will be automatically sorted
+- The parent's `expand` is automatically set to `true`
+
+---
+
+### 2. remove()
+
+Remove the current node (from its parent).
+
+**Parameter**: None
+
+**Example**:
+```typescript
+// Remove the node
+node.remove();
+
+// Clear reference after removal
+activeNode.remove();
+activeNode = null;
+```
+
+**Notes**:
+- Removes from parent's `children` array
+- Deletes from internal map
+- If it's a root node, removes from root node list
+
+---
+
+### 3. replace(newItem)
+
+Replace the current node's data.
+
+**Parameter**:
+- `newItem: T` - New data object
+
+**Example**:
+```typescript
+// Update some fields
+node.replace({
+  ...node.item,        // Keep other fields
+  name: "New Name",    // Update name
+  status: "active"     // Update status
+});
+
+// Or complete replacement
+node.replace({
+  id: node.item.id,    // Must keep ID
+  name: "Completely New Data",
+  newField: "value"
+});
+```
+
+**Notes**:
+- 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
+
+---
+
+### 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
+
+---
+
+### 6. removeChildren()
+
+Remove all child nodes.
+
+**Parameter**: None
+
+**Example**:
+```typescript
+// Clear all children
+parentNode.removeChildren();
+
+// Remove and then add new children
+parentNode.removeChildren();
+parentNode.append(newChildData);
+```
+
+**Notes**:
+- Removes all children and their descendants
+- Node's `expand` state remains unchanged
+- Internal map is updated accordingly
+
+## Complete Usage Example
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes, { type TreeNode } from "@ticatec/uniface-element/TreeNodes";
+
+  // Data type definition
+  interface MyData {
+    id: number;
+    name: string;
+    parent: number | null;
+  }
+
+  let activeNode: TreeNodeWithMethods<MyData> | null = null;
+
+  // Create tree structure
+  const treeNodes = new TreeNodes<MyData>({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.children != null
+  });
+
+  // Initialize data
+  treeNodes.setData([
+    { id: 1, name: "Root", parent: null },
+    { id: 2, name: "Child 1", parent: 1 },
+    { id: 3, name: "Child 2", parent: 1 }
+  ]);
+
+  // Add child node
+  function addChild() {
+    if (!activeNode) return;
+
+    activeNode.append({
+      id: Date.now(),
+      name: "New Child",
+      parent: activeNode.item.id
+    });
+  }
+
+  // Delete current node
+  function deleteCurrentNode() {
+    if (!activeNode) return;
+    activeNode.remove();
+    activeNode = null;
+  }
+
+  // Delete specific child
+  function deleteChild(childId: number) {
+    if (!activeNode) return;
+    activeNode.removeChild(childId);
+  }
+
+  // Clear all children
+  function clearChildren() {
+    if (!activeNode) return;
+    activeNode.removeChildren();
+  }
+
+  // Rename node
+  function renameNode(newName: string) {
+    if (!activeNode) return;
+    activeNode.replace({
+      ...activeNode.item,
+      name: newName
+    });
+  }
+
+  // Move node
+  function moveNodeTo(newParentId: number) {
+    if (!activeNode) return;
+    activeNode.moveTo(newParentId);
+  }
+</script>
+
+<div>
+  <TreeView
+    nodes={treeNodes.nodes}
+    version={treeNodes.version}
+    textField="name"
+    bind:activeNode
+    checkIsDirectory={(node) => node.children != null}
+  />
+
+  {#if activeNode}
+    <div class="node-actions">
+      <h3>Selected: {activeNode.item.name}</h3>
+      <button on:click={addChild}>Add Child</button>
+      <button on:click={deleteCurrentNode}>Delete Node</button>
+      <button on:click={() => renameNode("New Name")}>Rename</button>
+      <button on:click={() => moveNodeTo(1)}>Move to Root</button>
+      <button on:click={clearChildren}>Clear Children</button>
+    </div>
+  {/if}
+</div>
+```
+
+## Difference from TreeNodes Class Methods
+
+`TreeNode` methods and `TreeNodes` class methods have clear responsibilities:
+
+### TreeNode Node Methods (Recommended for Operating on Specific Nodes)
+
+```typescript
+// Operate directly on node - Recommended when you have a node instance
+node.append(childItem);      // Add child to this node
+node.remove();               // Remove this node
+node.replace(newItem);       // Replace this node's data
+node.moveTo(newParentId);    // Move this node
+node.removeChild(childId);   // Remove specific child
+node.removeChildren();       // Remove all children
+```
+
+### TreeNodes Class Methods (For Batch Operations or Initialization)
+
+```typescript
+// Class-level operations - Suitable when you only have data
+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
+```
+
+## Reactive Updates
+
+All node method operations automatically trigger `version` updates, ensuring Svelte components can respond to data changes:
+
+```svelte
+<TreeView
+  nodes={treeNodes.nodes}
+  version={treeNodes.version}  ← Auto-updated
+  ...
+/>
+```
+
+You don't need to manually trigger updates; node methods handle it automatically.
+
+## FAQ
+
+### Q: How to get a node instance?
+
+```typescript
+// Method 1: Through activeNode (selected node)
+let activeNode: TreeNode | null = null;
+<TreeView bind:activeNode />
+
+// Method 2: Through nodeMap (need to keep TreeNodes reference)
+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);
+  });
+}
+```
+
+### Q: How to find a specific child node?
+
+```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
+
+// 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
+```
+
+### 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));
+  }
+}
+
+// Usage
+traverse(rootNode, (node) => {
+  console.log(node.item.name);
+  node.expand = true;  // Expand all nodes
+});
+```
+
+## 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
+
+4. **Handle lazy nodes**: For lazy-loaded nodes, wait for loading to complete before operations
+
+5. **Version management**: No need to manually manage versions, node methods update automatically
+
+6. **Type safety**: Use TypeScript generics to ensure type safety
+
+```typescript
+// ✅ Recommended: Use generics
+const treeNodes = new TreeNodes<MyData>({ ... });
+
+// Node type is automatically inferred
+node.append({ id: 1, name: "..." });  // Type checking
+```
+
+## 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
+
+## Related Components
+
+- `TreeNodes` - Tree management class
+- `TreeView` - Tree view component
+- `LazyLoader` - Lazy loading interface