snice 4.8.0 → 4.10.0

package/docs/components/tree.md

@@ -1,294 +1,64 @@
-# Tree Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/tree.md instead)
 
-The tree component displays hierarchical data with expandable/collapsible nodes, support for selection (single/multiple), checkboxes, icons, and lazy loading.
+# Tree
+`<snice-tree>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Data Structure](#data-structure)
-- [Examples](#examples)
+Displays hierarchical data with expandable/collapsible nodes, selection, checkboxes, icons, and lazy loading.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/tree/snice-tree';
+```
+
 ```html
-<snice-tree id="myTree"></snice-tree>
+<snice-tree id="file-tree"></snice-tree>
 
 <script>
-  const tree = document.getElementById('myTree');
-  tree.nodes = [
+  document.getElementById('file-tree').nodes = [
     {
-      id: 'root',
-      label: 'Root Folder',
+      id: 'src',
+      label: 'src',
       icon: '📁',
       expanded: true,
       children: [
-        { id: 'file1', label: 'file1.txt', icon: '📄' },
-        { id: 'file2', label: 'file2.txt', icon: '📄' }
+        { id: 'index.ts', label: 'index.ts', icon: '📄' },
+        { id: 'main.ts', label: 'main.ts', icon: '📄' }
       ]
     }
   ];
 </script>
 ```
 
-```typescript
-import 'snice/components/tree/snice-tree';
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `nodes` | `TreeNode[]` | `[]` | Array of tree nodes to display |
-| `selectionMode` | `'single' \| 'multiple' \| 'none'` | `'single'` | Selection behavior |
-| `showCheckboxes` | `boolean` | `false` | Display checkboxes for multi-select |
-| `showIcons` | `boolean` | `true` | Display node icons |
-| `expandOnClick` | `boolean` | `false` | Expand/collapse on node click |
-| `selectedNodes` | `string[]` | `[]` | Array of selected node IDs |
-| `checkedNodes` | `string[]` | `[]` | Array of checked node IDs |
-
-## Methods
-
-### Expand/Collapse
-
-#### `expandNode(id: string): void`
-Expand a specific node by ID.
-
-```typescript
-tree.expandNode('folder1');
-```
-
-#### `collapseNode(id: string): void`
-Collapse a specific node by ID.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-tree.collapseNode('folder1');
-```
-
-#### `toggleNode(id: string): void`
-Toggle a node's expanded state.
-
-```typescript
-tree.toggleNode('folder1');
-```
-
-#### `expandAll(): void`
-Expand all nodes in the tree.
-
-```typescript
-tree.expandAll();
-```
-
-#### `collapseAll(): void`
-Collapse all nodes in the tree.
-
-```typescript
-tree.collapseAll();
-```
-
-### Selection
-
-#### `selectNode(id: string): void`
-Select a node by ID.
-
-```typescript
-tree.selectNode('file1');
-```
-
-#### `deselectNode(id: string): void`
-Deselect a node by ID.
-
-```typescript
-tree.deselectNode('file1');
-```
-
-#### `toggleSelection(id: string): void`
-Toggle a node's selection state.
-
-```typescript
-tree.toggleSelection('file1');
-```
-
-### Checkboxes
-
-#### `checkNode(id: string): void`
-Check a node by ID.
-
-```typescript
-tree.checkNode('file1');
-```
-
-#### `uncheckNode(id: string): void`
-Uncheck a node by ID.
-
-```typescript
-tree.uncheckNode('file1');
-```
-
-#### `toggleCheck(id: string): void`
-Toggle a node's checked state.
-
-```typescript
-tree.toggleCheck('file1');
-```
-
-### Getters
-
-#### `getNode(id: string): TreeNode | undefined`
-Get a node object by ID.
-
-```typescript
-const node = tree.getNode('file1');
-console.log(node.label);
-```
-
-#### `getSelectedNodes(): TreeNode[]`
-Get all selected nodes.
-
-```typescript
-const selected = tree.getSelectedNodes();
-console.log(selected.map(n => n.label));
-```
-
-#### `getCheckedNodes(): TreeNode[]`
-Get all checked nodes.
-
-```typescript
-const checked = tree.getCheckedNodes();
-console.log(checked.map(n => n.label));
-```
-
-## Events
-
-### `tree-node-expand`
-Fired when a node is expanded.
-
-**Event Detail:**
-```typescript
-{
-  nodeId: string;
-  node: TreeNode;
-  tree: SniceTreeElement;
-}
-```
-
-### `tree-node-collapse`
-Fired when a node is collapsed.
-
-**Event Detail:**
-```typescript
-{
-  nodeId: string;
-  node: TreeNode;
-  tree: SniceTreeElement;
-}
-```
-
-### `tree-node-select`
-Fired when a node is selected.
-
-**Event Detail:**
-```typescript
-{
-  nodeId: string;
-  node: TreeNode;
-  selectedNodes: TreeNode[];
-  tree: SniceTreeElement;
-}
-```
-
-### `tree-node-check`
-Fired when a node checkbox is toggled.
-
-**Event Detail:**
-```typescript
-{
-  nodeId: string;
-  node: TreeNode;
-  checked: boolean;
-  checkedNodes: TreeNode[];
-  tree: SniceTreeElement;
-}
-```
-
-### `tree-node-lazy-load`
-Fired when a lazy-loading node is expanded.
-
-**Event Detail:**
-```typescript
-{
-  nodeId: string;
-  node: TreeNode;
-  tree: SniceTreeElement;
-}
+import 'snice/components/tree/snice-tree';
 ```
 
-## Data Structure
-
-### TreeNode Interface
-
-```typescript
-interface TreeNode {
-  id: string;              // Unique identifier
-  label: string;           // Display text
-  icon?: string;           // Text/emoji icon
-  iconImage?: string;      // Icon image URL
-  children?: TreeNode[];   // Child nodes
-  disabled?: boolean;      // Disable interaction
-  selected?: boolean;      // Selection state
-  checked?: boolean;       // Checkbox state
-  expanded?: boolean;      // Expansion state
-  lazy?: boolean;          // Enable lazy loading
-  data?: any;             // Custom data
-}
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-tree.min.js"></script>
 ```
 
 ## Examples
 
-### File System Tree
-
-```html
-<snice-tree id="fileTree"></snice-tree>
-
-<script>
-  const fileTree = document.getElementById('fileTree');
-  fileTree.nodes = [
-    {
-      id: 'src',
-      label: 'src',
-      icon: '📁',
-      expanded: true,
-      children: [
-        {
-          id: 'components',
-          label: 'components',
-          icon: '📁',
-          children: [
-            { id: 'header.ts', label: 'header.ts', icon: '📄' },
-            { id: 'footer.ts', label: 'footer.ts', icon: '📄' }
-          ]
-        },
-        { id: 'index.ts', label: 'index.ts', icon: '📄' }
-      ]
-    }
-  ];
-</script>
-```
-
 ### Single Selection
 
+Use `selection-mode="single"` to allow selecting one node at a time.
+
 ```html
-<snice-tree id="singleTree" selection-mode="single"></snice-tree>
+<snice-tree id="single-tree" selection-mode="single"></snice-tree>
 
 <script>
-  const tree = document.getElementById('singleTree');
+  const tree = document.getElementById('single-tree');
   tree.nodes = [
     { id: '1', label: 'Item 1' },
     { id: '2', label: 'Item 2' },
     { id: '3', label: 'Item 3' }
   ];
-
   tree.addEventListener('tree-node-select', (e) => {
     console.log('Selected:', e.detail.node.label);
   });
@@ -297,240 +67,144 @@ interface TreeNode {
 
 ### Multiple Selection
 
-```html
-<snice-tree id="multiTree" selection-mode="multiple"></snice-tree>
+Use `selection-mode="multiple"` to allow selecting multiple nodes.
 
-<script>
-  const tree = document.getElementById('multiTree');
-  tree.nodes = [
-    { id: '1', label: 'Item 1' },
-    { id: '2', label: 'Item 2' },
-    { id: '3', label: 'Item 3' }
-  ];
-
-  tree.addEventListener('tree-node-select', (e) => {
-    console.log('Selected nodes:', e.detail.selectedNodes.map(n => n.label));
-  });
-</script>
+```html
+<snice-tree selection-mode="multiple"></snice-tree>
 ```
 
-### Checkbox Selection
+### Checkboxes
+
+Set the `show-checkboxes` attribute to display checkboxes for multi-select.
 
 ```html
-<snice-tree id="checkboxTree" show-checkboxes></snice-tree>
+<snice-tree id="checkbox-tree" show-checkboxes></snice-tree>
 
 <script>
-  const tree = document.getElementById('checkboxTree');
-  tree.nodes = [
+  document.getElementById('checkbox-tree').nodes = [
     {
       id: 'features',
       label: 'Features',
       children: [
-        { id: 'feature1', label: 'Dark Mode' },
-        { id: 'feature2', label: 'Notifications' },
-        { id: 'feature3', label: 'Auto-save' }
+        { id: 'dark-mode', label: 'Dark Mode' },
+        { id: 'notifications', label: 'Notifications' },
+        { id: 'auto-save', label: 'Auto-save' }
       ]
     }
   ];
-
-  tree.addEventListener('tree-node-check', (e) => {
-    console.log('Checked nodes:', e.detail.checkedNodes.map(n => n.label));
-  });
 </script>
 ```
 
 ### Lazy Loading
 
+Set `lazy: true` on nodes to load children on demand.
+
 ```html
-<snice-tree id="lazyTree"></snice-tree>
+<snice-tree id="lazy-tree"></snice-tree>
 
 <script>
-  const tree = document.getElementById('lazyTree');
+  const tree = document.getElementById('lazy-tree');
   tree.nodes = [
-    {
-      id: 'folder1',
-      label: 'Click to load...',
-      icon: '📁',
-      lazy: true,
-      children: []
-    }
+    { id: 'folder', label: 'Click to load...', icon: '📁', lazy: true, children: [] }
   ];
 
   tree.addEventListener('tree-node-lazy-load', async (e) => {
     const node = e.detail.node;
-
-    // Simulate async data loading
     const data = await fetch(`/api/nodes/${node.id}`).then(r => r.json());
-
-    node.children = data.map(item => ({
-      id: item.id,
-      label: item.name,
-      icon: '📄'
-    }));
+    node.children = data.map(item => ({ id: item.id, label: item.name, icon: '📄' }));
     node.lazy = false;
     node.expanded = true;
-
-    // Trigger re-render
     tree.nodes = [...tree.nodes];
   });
 </script>
 ```
 
-### Programmatic Control
-
-```html
-<div>
-  <button onclick="tree.expandAll()">Expand All</button>
-  <button onclick="tree.collapseAll()">Collapse All</button>
-</div>
+### Expand on Click
 
-<snice-tree id="tree"></snice-tree>
-
-<script>
-  const tree = document.getElementById('tree');
-  tree.nodes = [
-    {
-      id: 'root',
-      label: 'Root',
-      children: [
-        {
-          id: 'branch1',
-          label: 'Branch 1',
-          children: [
-            { id: 'leaf1', label: 'Leaf 1' }
-          ]
-        }
-      ]
-    }
-  ];
-</script>
-```
-
-### Organization Chart
+Set the `expand-on-click` attribute so clicking a node toggles its expansion.
 
 ```html
-<snice-tree id="orgTree"></snice-tree>
-
-<script>
-  const orgTree = document.getElementById('orgTree');
-  orgTree.nodes = [
-    {
-      id: 'ceo',
-      label: 'CEO - John Smith',
-      icon: '👤',
-      expanded: true,
-      children: [
-        {
-          id: 'cto',
-          label: 'CTO - Jane Doe',
-          icon: '👤',
-          children: [
-            { id: 'dev1', label: 'Developer - Alice', icon: '👤' },
-            { id: 'dev2', label: 'Developer - Bob', icon: '👤' }
-          ]
-        },
-        {
-          id: 'cfo',
-          label: 'CFO - Mike Johnson',
-          icon: '👤',
-          children: [
-            { id: 'acc1', label: 'Accountant - Carol', icon: '👤' }
-          ]
-        }
-      ]
-    }
-  ];
-</script>
+<snice-tree expand-on-click></snice-tree>
 ```
 
 ### Without Icons
 
-```html
-<snice-tree id="noIconTree" show-icons="false"></snice-tree>
+Set `show-icons="false"` to hide node icons.
 
-<script>
-  const tree = document.getElementById('noIconTree');
-  tree.nodes = [
-    {
-      id: '1',
-      label: 'Chapter 1',
-      children: [
-        { id: '1.1', label: 'Section 1.1' },
-        { id: '1.2', label: 'Section 1.2' }
-      ]
-    },
-    {
-      id: '2',
-      label: 'Chapter 2',
-      children: [
-        { id: '2.1', label: 'Section 2.1' }
-      ]
-    }
-  ];
-</script>
+```html
+<snice-tree show-icons="false"></snice-tree>
 ```
 
-### Custom Icons with Images
+### Programmatic Control
 
-```html
-<snice-tree id="customIconTree"></snice-tree>
+```javascript
+const tree = document.querySelector('snice-tree');
+tree.expandAll();
+tree.collapseAll();
+tree.expandNode('folder1');
+tree.selectNode('file1');
+tree.checkNode('feature1');
 
-<script>
-  const tree = document.getElementById('customIconTree');
-  tree.nodes = [
-    {
-      id: 'images',
-      label: 'Images',
-      iconImage: '/icons/folder.png',
-      children: [
-        { id: 'pic1.jpg', label: 'pic1.jpg', iconImage: '/icons/image.png' },
-        { id: 'pic2.png', label: 'pic2.png', iconImage: '/icons/image.png' }
-      ]
-    },
-    {
-      id: 'documents',
-      label: 'Documents',
-      iconImage: '/icons/folder.png',
-      children: [
-        { id: 'doc1.pdf', label: 'doc1.pdf', iconImage: '/icons/pdf.png' }
-      ]
-    }
-  ];
-</script>
+const selected = tree.getSelectedNodes();
+const checked = tree.getCheckedNodes();
+const node = tree.getNode('file1');
 ```
 
-### Disabled Nodes
+## Properties
 
-```html
-<snice-tree id="disabledTree"></snice-tree>
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `nodes` | `TreeNode[]` | `[]` | Array of tree nodes |
+| `selectionMode` (attr: `selection-mode`) | `'single' \| 'multiple' \| 'none'` | `'single'` | Selection behavior |
+| `showCheckboxes` (attr: `show-checkboxes`) | `boolean` | `false` | Display checkboxes |
+| `showIcons` (attr: `show-icons`) | `boolean` | `true` | Display node icons |
+| `expandOnClick` (attr: `expand-on-click`) | `boolean` | `false` | Expand/collapse on node click |
+| `selectedNodes` (attr: `selected-nodes`) | `string[]` | `[]` | Selected node IDs |
+| `checkedNodes` (attr: `checked-nodes`) | `string[]` | `[]` | Checked node IDs |
 
-<script>
-  const tree = document.getElementById('disabledTree');
-  tree.nodes = [
-    { id: '1', label: 'Active Node' },
-    { id: '2', label: 'Disabled Node', disabled: true },
-    {
-      id: '3',
-      label: 'Parent',
-      children: [
-        { id: '3.1', label: 'Active Child' },
-        { id: '3.2', label: 'Disabled Child', disabled: true }
-      ]
-    }
-  ];
-</script>
+### TreeNode Interface
+
+```typescript
+interface TreeNode {
+  id: string;
+  label: string;
+  icon?: string;
+  iconImage?: string;
+  children?: TreeNode[];
+  disabled?: boolean;
+  selected?: boolean;
+  checked?: boolean;
+  expanded?: boolean;
+  lazy?: boolean;
+  data?: any;
+}
 ```
 
-## Accessibility
+## Events
 
-- Supports keyboard navigation (Arrow keys, Home, End)
-- Proper ARIA attributes (`role="tree"`, `role="treeitem"`, `aria-expanded`, `aria-selected`)
-- Focus management for keyboard users
-- Screen reader announcements for state changes
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `tree-node-expand` | `{ nodeId: string, node: TreeNode, tree }` | Node expanded |
+| `tree-node-collapse` | `{ nodeId: string, node: TreeNode, tree }` | Node collapsed |
+| `tree-node-select` | `{ nodeId: string, node: TreeNode, selectedNodes: TreeNode[], tree }` | Node selected |
+| `tree-node-check` | `{ nodeId: string, node: TreeNode, checked: boolean, checkedNodes: TreeNode[], tree }` | Checkbox toggled |
+| `tree-node-lazy-load` | `{ nodeId: string, node: TreeNode, tree }` | Lazy node expanded |
 
-## Browser Support
+## Methods
 
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Modern browsers with Custom Elements v1 support
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `expandNode()` | `id: string` | Expand a node |
+| `collapseNode()` | `id: string` | Collapse a node |
+| `toggleNode()` | `id: string` | Toggle expand/collapse |
+| `expandAll()` | -- | Expand all nodes |
+| `collapseAll()` | -- | Collapse all nodes |
+| `selectNode()` | `id: string` | Select a node |
+| `deselectNode()` | `id: string` | Deselect a node |
+| `toggleSelection()` | `id: string` | Toggle selection |
+| `checkNode()` | `id: string` | Check a node |
+| `uncheckNode()` | `id: string` | Uncheck a node |
+| `toggleCheck()` | `id: string` | Toggle checked state |
+| `getNode()` | `id: string` | Get node object |
+| `getSelectedNodes()` | -- | Get all selected nodes |
+| `getCheckedNodes()` | -- | Get all checked nodes |