@ticatec/uniface-element 0.3.15 → 0.3.17

package/dist/lib/TreeNode_README.md

@@ -0,0 +1,577 @@
+# TreeNode - Tree Node Data Structure
+
+## Overview
+
+`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.
+
+Each node created from `TreeNodes` or `CommonTreeNodes` is an instance of the `TreeNode` class with built-in methods.
+
+## TreeNode Class
+
+```typescript
+class TreeNode<T> {
+  /** The node's data object (readonly) */
+  public readonly item: T;
+
+  /** Whether the node is expanded (showing children) */
+  public expand: boolean;
+
+  /** Whether the node is currently loading (for lazy loading) */
+  public loading: boolean;
+
+  /** Parent node (null for root nodes) */
+  public parent: TreeNode<T> | null;
+
+  /** Child nodes (readonly, use methods to modify) */
+  get children(): ReadonlyArray<TreeNode<T>>;
+
+  /** Add a child node to the current node */
+  append(childItem: T): void;
+
+  /** Remove the current node (from its parent) */
+  detach(): void;
+
+  /** Move the current node to a different parent */
+  moveTo(newParent: TreeNode<T>): void;
+
+  /** 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;
+}
+```
+
+## 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)
+
+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",
+  parentId: parentNode.item.id  // Will be set automatically
+});
+```
+
+**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
+
+---
+
+### 2. detach()
+
+Remove the current node from its parent.
+
+**Parameter**: None
+
+**Example**:
+```typescript
+// Remove the node from its parent
+node.detach();
+
+// Clear reference after removal
+activeNode.detach();
+activeNode = null;
+```
+
+**Notes**:
+- 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. 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.
+
+**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
+- Preserves children, expand state, and loading state
+
+---
+
+### 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()
+
+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
+- 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 { CommonTreeNodes, type TreeNode } from "@ticatec/uniface-element/lib/TreeNodes";
+
+  // Data type definition
+  interface MyData {
+    id: number;
+    name: string;
+    parentId: number | null;
+  }
+
+  let activeNode: TreeNode<MyData> | null = null;
+
+  // Create tree structure
+  const treeNodes = new CommonTreeNodes<MyData>({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parentId',
+    checkIsRoot: (item) => item.parentId === null,
+    checkIsDirectory: (node) => node.children.length > 0,
+    expendDepth: 2
+  });
+
+  // Initialize data
+  treeNodes.setData([
+    { id: 1, name: "Root", parentId: null },
+    { id: 2, name: "Child 1", parentId: 1 },
+    { id: 3, name: "Child 2", parentId: 1 }
+  ]);
+
+  // Add child node
+  function addChild() {
+    if (!activeNode) return;
+
+    activeNode.append({
+      id: Date.now(),
+      name: "New Child",
+      parentId: activeNode.item.id
+    });
+  }
+
+  // Delete current node
+  function deleteCurrentNode() {
+    if (!activeNode) return;
+    activeNode.detach();
+    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;
+    const newParent = treeNodes.nodeMap.get(newParentId);
+    if (newParent) {
+      activeNode.moveTo(newParent);
+    }
+  }
+</script>
+
+<div>
+  <TreeView
+    nodes={treeNodes.nodes}
+    version={treeNodes.version}
+    textField="name"
+    bind:activeNode
+    checkIsDirectory={(node) => node.children.length > 0}
+  />
+
+  {#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` instance methods and `CommonTreeNodes`/`TreeNodes` class methods have clear responsibilities:
+
+### TreeNode Instance Methods (For Operating on Specific Node Instances)
+
+```typescript
+// Operate directly on a node instance
+node.append(childItem);      // Add child 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
+```
+
+### CommonTreeNodes/TreeNodes Class Methods (For Tree-Level Operations)
+
+```typescript
+// 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 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
+
+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
+// 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);
+}
+```
+
+### Q: How to find a specific child node?
+
+```typescript
+function findChild(node: TreeNode, childId: number) {
+  return node.children.find(child => child.item.id === childId) || null;
+}
+```
+
+### 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
+
+### Q: How to recursively operate on all descendants?
+
+```typescript
+function traverse(node: TreeNode, callback: (node: TreeNode) => void) {
+  callback(node);
+  for (const child of node.children) {
+    traverse(child, callback);
+  }
+}
+
+// Usage
+traverse(rootNode, (node) => {
+  console.log(node.item.name);
+  node.expand = true;  // Expand all nodes
+});
+```
+
+### 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. **Use moveTo correctly**: The `moveTo()` method takes a TreeNode instance, not an ID:
+   ```typescript
+   // ❌ Wrong
+   node.moveTo(123);
+
+   // ✅ Correct
+   const parentNode = treeNodes.nodeMap.get(123);
+   node.moveTo(parentNode);
+   ```
+
+4. **Version management**: No need to manually manage versions, node methods update automatically
+
+5. **Type safety**: Use TypeScript generics to ensure type safety
+
+```typescript
+// ✅ Recommended: Use generics
+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
+
+- `CommonTreeNodes` - Base tree management class
+- `TreeNodes` - Extended tree management with hierarchy features
+- `TreeView` - Tree view component
+- `NodeViewOptions` - View configuration class