@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/tree-view/README.md

@@ -0,0 +1,761 @@
+# TreeView
+
+A hierarchical tree view component for displaying nested data structures. Features expandable/collapsible nodes, lazy loading, context menus, and customizable node display. Perfect for file explorers, organizational charts, and hierarchical data navigation.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import TreeView, { type LazyLoader, type NodeVisibleFun, type OnNodeSelectionChange } from "@ticatec/uniface-element/TreeView";
+import TreeNodes, { type TreeNode } from "@ticatec/uniface-element/TreeNodes";
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let activeNode = null;
+  
+  // Sample data
+  const data = [
+    { id: 1, name: "Documents", parent: null },
+    { id: 2, name: "Projects", parent: null },
+    { id: 3, name: "Project A", parent: 2 },
+    { id: 4, name: "Project B", parent: 2 },
+    { id: 5, name: "file1.txt", parent: 3 },
+    { id: 6, name: "file2.txt", parent: 3 }
+  ];
+  
+  // Create tree structure
+  const treeNodes = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.children != null
+  });
+  
+  treeNodes.setData(data);
+  
+  function handleSelectionChange(node) {
+    console.log('Selected node:', node);
+    return true; // Allow selection
+  }
+</script>
+
+<TreeView 
+  nodes={treeNodes.nodes}
+  textField="name"
+  bind:activeNode
+  onchange={handleSelectionChange}
+  checkIsDirectory={node => node.children != null}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `nodes` | `Array<TreeNode<any>>` | Required | Array of tree nodes to display |
+| `textField` | `string \| GetText<any>` | Required | Field name or function to get node text |
+| `activeNode` | `any` | `null` | Currently selected/active node |
+| `style` | `string` | `""` | Additional CSS styles |
+| `lazyLoader` | `LazyLoader \| null` | `null` | Lazy loading configuration |
+| `isVisible` | `NodeVisibleFun` | `null` | Function to determine node visibility |
+| `onchange` | `OnNodeSelectionChange` | `null` | Callback when node selection changes |
+| `onfocus` | `((event: FocusEvent) => void) \| null` | `null` | Callback when tree gains focus |
+| `onblur` | `((event: FocusEvent) => void) \| null` | `null` | Callback when tree loses focus |
+| `onContextMenu` | `OnContextMenu` | `null` | Right-click context menu handler |
+| `checkIsDirectory` | `CheckIsDirectory<any>` | Required | Function to check if node is a directory |
+| `class` | `string` | `""` | CSS class name |
+
+## Type Definitions
+
+### TreeNode<T>
+```typescript
+interface TreeNode<T> {
+  item: T;              // The actual data item
+  children?: Array<TreeNode<T>>;  // Child nodes
+  expand?: boolean;     // Whether node is expanded
+  parent?: TreeNode<T>; // Parent node reference
+}
+```
+
+### LazyLoader
+```typescript
+interface LazyLoader {
+  isBranch: (node: TreeNode<any>) => boolean;  // Check if node can have children
+  load: (node: TreeNode<any>) => Promise<Array<TreeNode<any>>>;  // Load children
+}
+```
+
+### OnNodeSelectionChange
+```typescript
+type OnNodeSelectionChange = (node: TreeNode<any>) => Promise<boolean>;
+```
+
+### NodeVisibleFun
+```typescript
+type NodeVisibleFun = (node: TreeNode<any>) => boolean;
+```
+
+## Examples
+
+### File System Tree
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let activeNode = null;
+  
+  const fileSystemData = [
+    { id: 1, name: "=� Documents", type: "folder", parent: null },
+    { id: 2, name: "=� Pictures", type: "folder", parent: null },
+    { id: 3, name: "=� Work", type: "folder", parent: 1 },
+    { id: 4, name: "=� Personal", type: "folder", parent: 1 },
+    { id: 5, name: "=� resume.pdf", type: "file", parent: 3 },
+    { id: 6, name: "=� cover-letter.doc", type: "file", parent: 3 },
+    { id: 7, name: "=� vacation.jpg", type: "file", parent: 2 },
+    { id: 8, name: "=� family.png", type: "file", parent: 2 }
+  ];
+  
+  const fileTree = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.item.type === 'folder',
+    expendDepth: 1 // Expand first level by default
+  });
+  
+  fileTree.setData(fileSystemData);
+  
+  function handleFileSelection(node) {
+    console.log('Selected file:', node.item.name);
+    return true;
+  }
+  
+  function isDirectory(node) {
+    return node.item.type === 'folder';
+  }
+</script>
+
+<div class="file-explorer">
+  <h3>File Explorer</h3>
+  <TreeView 
+    nodes={fileTree.nodes}
+    textField="name"
+    bind:activeNode
+    onchange={handleFileSelection}
+    checkIsDirectory={isDirectory}
+  />
+</div>
+
+<style>
+  .file-explorer {
+    width: 300px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+  
+  h3 {
+    margin: 0 0 12px 0;
+    font-size: 16px;
+  }
+</style>
+```
+
+### Organization Chart
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let selectedEmployee = null;
+  
+  const orgData = [
+    { id: 1, name: "CEO - John Smith", position: "Chief Executive Officer", manager: null },
+    { id: 2, name: "CTO - Jane Doe", position: "Chief Technology Officer", manager: 1 },
+    { id: 3, name: "CFO - Bob Wilson", position: "Chief Financial Officer", manager: 1 },
+    { id: 4, name: "Dev Manager - Alice Brown", position: "Development Manager", manager: 2 },
+    { id: 5, name: "QA Manager - Charlie Davis", position: "QA Manager", manager: 2 },
+    { id: 6, name: "Developer - Eve Johnson", position: "Senior Developer", manager: 4 },
+    { id: 7, name: "Developer - Frank Miller", position: "Junior Developer", manager: 4 },
+    { id: 8, name: "QA Engineer - Grace Lee", position: "QA Engineer", manager: 5 }
+  ];
+  
+  const orgChart = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'manager',
+    checkIsRoot: (item) => item.manager === null,
+    checkIsDirectory: (node) => node.children && node.children.length > 0,
+    expendDepth: 2
+  });
+  
+  orgChart.setData(orgData);
+  
+  function handleEmployeeSelection(node) {
+    selectedEmployee = node.item;
+    return true;
+  }
+  
+  function isManager(node) {
+    return node.children && node.children.length > 0;
+  }
+</script>
+
+<div class="org-chart">
+  <h3>Organization Chart</h3>
+  <TreeView 
+    nodes={orgChart.nodes}
+    textField="name"
+    onchange={handleEmployeeSelection}
+    checkIsDirectory={isManager}
+  />
+  
+  {#if selectedEmployee}
+    <div class="employee-details">
+      <h4>Employee Details</h4>
+      <p><strong>Name:</strong> {selectedEmployee.name}</p>
+      <p><strong>Position:</strong> {selectedEmployee.position}</p>
+    </div>
+  {/if}
+</div>
+
+<style>
+  .org-chart {
+    width: 400px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+  
+  .employee-details {
+    margin-top: 16px;
+    padding: 12px;
+    background: #f8f9fa;
+    border-radius: 4px;
+  }
+  
+  .employee-details h4 {
+    margin: 0 0 8px 0;
+  }
+  
+  .employee-details p {
+    margin: 4px 0;
+  }
+</style>
+```
+
+### With Lazy Loading
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let activeNode = null;
+  
+  // Initial root nodes
+  const initialData = [
+    { id: 1, name: "Folder A", hasChildren: true },
+    { id: 2, name: "Folder B", hasChildren: true },
+    { id: 3, name: "File 1.txt", hasChildren: false }
+  ];
+  
+  const treeNodes = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => !item.parent,
+    checkIsDirectory: (node) => node.item.hasChildren
+  });
+  
+  treeNodes.setData(initialData);
+  
+  // Lazy loader configuration
+  const lazyLoader = {
+    isBranch: (node) => node.item.hasChildren,
+    
+    load: async (node) => {
+      // Simulate API call
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      
+      // Generate child nodes
+      const children = [];
+      for (let i = 1; i <= 3; i++) {
+        children.push({
+          id: `${node.item.id}-${i}`,
+          name: `${node.item.name} - Child ${i}`,
+          parent: node.item.id,
+          hasChildren: Math.random() > 0.7 // 30% chance of having children
+        });
+      }
+      
+      return children.map(child => ({ item: child, children: null }));
+    }
+  };
+  
+  function handleSelection(node) {
+    console.log('Selected:', node.item.name);
+    return true;
+  }
+  
+  function isDirectory(node) {
+    return node.item.hasChildren;
+  }
+</script>
+
+<div class="lazy-tree">
+  <h3>Lazy Loading Tree</h3>
+  <TreeView 
+    nodes={treeNodes.nodes}
+    textField="name"
+    bind:activeNode
+    {lazyLoader}
+    onchange={handleSelection}
+    checkIsDirectory={isDirectory}
+  />
+</div>
+
+<style>
+  .lazy-tree {
+    width: 300px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+</style>
+```
+
+### With Context Menu
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  import ContextMenu from "@ticatec/uniface-element/ContextMenu";
+  
+  let activeNode = null;
+  let contextMenu;
+  
+  const menuData = [
+    { id: 1, name: "Root Folder", type: "folder", parent: null },
+    { id: 2, name: "Subfolder", type: "folder", parent: 1 },
+    { id: 3, name: "document.txt", type: "file", parent: 2 }
+  ];
+  
+  const menuTree = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.item.type === 'folder'
+  });
+  
+  menuTree.setData(menuData);
+  
+  function handleContextMenu(event, node) {
+    const isFolder = node.item.type === 'folder';
+    
+    const menuItems = [
+      {
+        text: "Open",
+        action: () => console.log('Open:', node.item.name)
+      },
+      {
+        text: "Rename",
+        action: () => console.log('Rename:', node.item.name)
+      },
+      ...(isFolder ? [{
+        text: "Add File",
+        action: () => console.log('Add file to:', node.item.name)
+      }] : []),
+      {
+        text: "Delete",
+        action: () => console.log('Delete:', node.item.name)
+      }
+    ];
+    
+    contextMenu.show(event, menuItems);
+  }
+  
+  function isDirectory(node) {
+    return node.item.type === 'folder';
+  }
+</script>
+
+<div class="context-tree">
+  <h3>Right-click for Context Menu</h3>
+  <TreeView 
+    nodes={menuTree.nodes}
+    textField="name"
+    bind:activeNode
+    onContextMenu={handleContextMenu}
+    checkIsDirectory={isDirectory}
+  />
+</div>
+
+<ContextMenu bind:this={contextMenu} />
+
+<style>
+  .context-tree {
+    width: 300px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+</style>
+```
+
+### With Custom Visibility Filter
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let activeNode = null;
+  let showHidden = false;
+  
+  const fileData = [
+    { id: 1, name: "public", hidden: false, parent: null },
+    { id: 2, name: ".env", hidden: true, parent: null },
+    { id: 3, name: "index.js", hidden: false, parent: 1 },
+    { id: 4, name: ".gitignore", hidden: true, parent: 1 },
+    { id: 5, name: "config.json", hidden: false, parent: 1 }
+  ];
+  
+  const fileTree = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.children && node.children.length > 0
+  });
+  
+  fileTree.setData(fileData);
+  
+  function isVisible(node) {
+    return showHidden || !node.item.hidden;
+  }
+  
+  function isDirectory(node) {
+    return node.children && node.children.length > 0;
+  }
+</script>
+
+<div class="filtered-tree">
+  <div class="controls">
+    <label>
+      <input type="checkbox" bind:checked={showHidden} />
+      Show hidden files
+    </label>
+  </div>
+  
+  <TreeView 
+    nodes={fileTree.nodes}
+    textField="name"
+    bind:activeNode
+    {isVisible}
+    checkIsDirectory={isDirectory}
+  />
+</div>
+
+<style>
+  .filtered-tree {
+    width: 300px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+  
+  .controls {
+    margin-bottom: 12px;
+  }
+  
+  label {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 14px;
+  }
+</style>
+```
+
+### With Event Handlers
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let activeNode = null;
+  let isFocused = false;
+  let selectionLog = [];
+  
+  const eventData = [
+    { id: 1, name: "Node 1", parent: null },
+    { id: 2, name: "Node 2", parent: null },
+    { id: 3, name: "Child 1", parent: 1 },
+    { id: 4, name: "Child 2", parent: 1 }
+  ];
+  
+  const eventTree = new TreeNodes({
+    keyField: 'id',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => node.children && node.children.length > 0
+  });
+  
+  eventTree.setData(eventData);
+  
+  function handleSelectionChange(node) {
+    selectionLog = [...selectionLog, `Selected: ${node.item.name} at ${new Date().toLocaleTimeString()}`];
+    return true;
+  }
+  
+  function handleFocus(event) {
+    console.log('Tree focused');
+    isFocused = true;
+  }
+  
+  function handleBlur(event) {
+    console.log('Tree blurred');
+    isFocused = false;
+  }
+  
+  function isDirectory(node) {
+    return node.children && node.children.length > 0;
+  }
+</script>
+
+<div class="event-tree">
+  <h3>Event Handling Demo</h3>
+  <p>Tree is {isFocused ? 'focused' : 'not focused'}</p>
+  
+  <TreeView 
+    nodes={eventTree.nodes}
+    textField="name"
+    bind:activeNode
+    onchange={handleSelectionChange}
+    onfocus={handleFocus}
+    onblur={handleBlur}
+    checkIsDirectory={isDirectory}
+  />
+  
+  <div class="log">
+    <h4>Selection Log:</h4>
+    {#each selectionLog.slice(-5) as entry}
+      <p>{entry}</p>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .event-tree {
+    width: 400px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+  
+  .log {
+    margin-top: 16px;
+    padding: 12px;
+    background: #f8f9fa;
+    border-radius: 4px;
+    max-height: 150px;
+    overflow-y: auto;
+  }
+  
+  .log h4 {
+    margin: 0 0 8px 0;
+    font-size: 14px;
+  }
+  
+  .log p {
+    margin: 2px 0;
+    font-size: 12px;
+    font-family: monospace;
+  }
+</style>
+```
+
+### Geographic Hierarchy
+
+```svelte
+<script>
+  import TreeView from "@ticatec/uniface-element/TreeView";
+  import TreeNodes from "@ticatec/uniface-element/TreeNodes";
+  
+  let activeLocation = null;
+  
+  const locationData = [
+    { code: "CN", name: "China", type: "country", parent: null },
+    { code: "US", name: "United States", type: "country", parent: null },
+    { code: "CN-BJ", name: "Beijing", type: "province", parent: "CN" },
+    { code: "CN-SH", name: "Shanghai", type: "province", parent: "CN" },
+    { code: "US-CA", name: "California", type: "state", parent: "US" },
+    { code: "US-NY", name: "New York", type: "state", parent: "US" },
+    { code: "CN-BJ-HD", name: "Haidian District", type: "district", parent: "CN-BJ" },
+    { code: "CN-BJ-CY", name: "Chaoyang District", type: "district", parent: "CN-BJ" },
+    { code: "US-CA-SF", name: "San Francisco", type: "city", parent: "US-CA" },
+    { code: "US-CA-LA", name: "Los Angeles", type: "city", parent: "US-CA" }
+  ];
+  
+  const locationTree = new TreeNodes({
+    keyField: 'code',
+    textField: 'name',
+    parentKeyField: 'parent',
+    checkIsRoot: (item) => item.parent === null,
+    checkIsDirectory: (node) => {
+      const hasChildren = locationData.some(loc => loc.parent === node.item.code);
+      return hasChildren;
+    },
+    expendDepth: 1
+  });
+  
+  locationTree.setData(locationData);
+  
+  function handleLocationSelection(node) {
+    activeLocation = node.item;
+    return true;
+  }
+  
+  function isDirectory(node) {
+    return locationData.some(loc => loc.parent === node.item.code);
+  }
+  
+  function getLocationIcon(type) {
+    switch (type) {
+      case 'country': return '<
+      case 'province':
+      case 'state': return '<�';
+      case 'district':
+      case 'city': return '<�';
+      default: return '=�';
+    }
+  }
+  
+  function displayLocationName(item) {
+    return `${getLocationIcon(item.type)} ${item.name}`;
+  }
+</script>
+
+<div class="location-tree">
+  <h3>Geographic Hierarchy</h3>
+  <TreeView 
+    nodes={locationTree.nodes}
+    textField={displayLocationName}
+    onchange={handleLocationSelection}
+    checkIsDirectory={isDirectory}
+  />
+  
+  {#if activeLocation}
+    <div class="location-details">
+      <h4>Selected Location</h4>
+      <p><strong>Name:</strong> {activeLocation.name}</p>
+      <p><strong>Code:</strong> {activeLocation.code}</p>
+      <p><strong>Type:</strong> {activeLocation.type}</p>
+    </div>
+  {/if}
+</div>
+
+<style>
+  .location-tree {
+    width: 350px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 16px;
+  }
+  
+  .location-details {
+    margin-top: 16px;
+    padding: 12px;
+    background: #f8f9fa;
+    border-radius: 4px;
+  }
+  
+  .location-details h4 {
+    margin: 0 0 8px 0;
+  }
+  
+  .location-details p {
+    margin: 4px 0;
+  }
+</style>
+```
+
+## Features
+
+- **Hierarchical Display**: Clean tree structure with expandable/collapsible nodes
+- **Lazy Loading**: Load child nodes on demand for large datasets
+- **Context Menus**: Right-click support for custom actions
+- **Keyboard Navigation**: Full keyboard accessibility support
+- **Custom Visibility**: Filter nodes based on custom criteria
+- **Selection Management**: Track and control node selection
+- **Event Handling**: Comprehensive event system for interactions
+- **Flexible Data**: Support for any data structure with configurable mapping
+
+## Node Management
+
+The TreeView component works with the `TreeNodes` utility class to manage hierarchical data:
+
+```typescript
+const treeNodes = new TreeNodes({
+  keyField: 'id',           // Unique identifier field
+  textField: 'name',        // Display text field
+  parentKeyField: 'parent', // Parent reference field
+  checkIsRoot: (item) => item.parent === null,
+  checkIsDirectory: (node) => node.children != null,
+  expendDepth: 1           // Initial expansion depth
+});
+
+treeNodes.setData(flatData); // Convert flat data to tree structure
+```
+
+## Accessibility
+
+- Keyboard navigation with arrow keys and Enter
+- Proper ARIA attributes for screen readers
+- Focus management and visual indicators
+- Semantic HTML structure
+- Tab navigation support
+
+## Best Practices
+
+1. **Data Structure**: Use consistent field names across your data
+2. **Performance**: Implement lazy loading for large datasets
+3. **Visibility**: Use the `isVisible` prop to filter nodes efficiently
+4. **Selection**: Always return a boolean from selection change handlers
+5. **Context Menus**: Provide contextually relevant menu items
+6. **Accessibility**: Ensure proper keyboard navigation support
+
+## Browser Support
+
+- Modern browsers with full event support
+- Compatible with Svelte 5+
+- Keyboard navigation support
+- Touch-friendly interface
+- Full TypeScript support
+
+## Related Components
+
+- `TreeNodes` - Tree data structure utility
+- `ContextMenu` - Right-click context menu component
+- `LazyLoader` - Async data loading interface