snice 3.1.0 → 3.3.0

package/docs/ai/components/stepper.md

@@ -0,0 +1,216 @@
+# snice-stepper
+
+Step indicator for multi-step processes, wizards, workflows. Shows progress with pending/active/completed/error states.
+
+## Properties
+
+```typescript
+steps: Step[] = []                          // Array of step objects
+currentStep: number = 0                     // Current active step index
+orientation: StepperOrientation = 'horizontal' // 'horizontal' | 'vertical'
+clickable: boolean = false                  // Enable click navigation
+
+// Step object:
+{
+  label: string;           // Step label (required)
+  description?: string;    // Optional description
+  status?: StepStatus;     // Override auto status: 'pending' | 'active' | 'completed' | 'error'
+}
+```
+
+## Usage
+
+```html
+<!-- Basic horizontal -->
+<snice-stepper id="basic"></snice-stepper>
+<script>
+  document.getElementById('basic').steps = [
+    { label: 'Step 1' },
+    { label: 'Step 2' },
+    { label: 'Step 3' }
+  ];
+  document.getElementById('basic').currentStep = 1;
+</script>
+
+<!-- With panels (auto show/hide) -->
+<snice-stepper id="wizard" clickable></snice-stepper>
+<snice-stepper-panel>Step 1 content</snice-stepper-panel>
+<snice-stepper-panel>Step 2 content</snice-stepper-panel>
+<snice-stepper-panel>Step 3 content</snice-stepper-panel>
+<script>
+  document.getElementById('wizard').steps = [
+    { label: 'Account' },
+    { label: 'Profile' },
+    { label: 'Complete' }
+  ];
+</script>
+
+<!-- Vertical with descriptions -->
+<snice-stepper id="vertical" orientation="vertical"></snice-stepper>
+<script>
+  document.getElementById('vertical').steps = [
+    { label: 'Account', description: 'Create your account' },
+    { label: 'Profile', description: 'Personal info' },
+    { label: 'Complete', description: 'Finish setup' }
+  ];
+</script>
+
+<!-- Clickable navigation -->
+<snice-stepper id="wizard" clickable></snice-stepper>
+<script>
+  const wizard = document.getElementById('wizard');
+  wizard.steps = [
+    { label: 'Cart' },
+    { label: 'Delivery' },
+    { label: 'Payment' },
+    { label: 'Confirm' }
+  ];
+
+  wizard.addEventListener('step-change', (e) => {
+    console.log(e.detail.previousStep); // Previous step index
+    console.log(e.detail.currentStep);  // New step index
+    console.log(e.detail.step);         // Step object
+    // e.preventDefault(); to cancel navigation
+  });
+</script>
+
+<!-- Error state -->
+<snice-stepper id="validation"></snice-stepper>
+<script>
+  document.getElementById('validation').steps = [
+    { label: 'Upload', status: 'completed' },
+    { label: 'Validate', status: 'error' },
+    { label: 'Process', status: 'pending' }
+  ];
+</script>
+
+<!-- Programmatic navigation -->
+<script>
+  const stepper = document.getElementById('my-stepper');
+  stepper.currentStep++; // Next
+  stepper.currentStep--; // Previous
+  stepper.currentStep = 2; // Go to step 3
+</script>
+```
+
+## Events
+
+```javascript
+// step-change (only in clickable mode)
+stepper.addEventListener('step-change', (e) => {
+  const { previousStep, currentStep, step } = e.detail;
+  e.preventDefault(); // Cancel navigation if needed
+});
+```
+
+## CSS Parts
+
+```css
+::part(container)       /* Main container */
+::part(step)            /* Individual step */
+::part(step-indicator)  /* Circular indicator */
+::part(step-content)    /* Label + description wrapper */
+::part(step-label)      /* Step label text */
+::part(step-description) /* Description text */
+::part(step-connector)  /* Line between steps */
+```
+
+## Styling
+
+```css
+--snice-color-primary       /* Active state */
+--snice-color-success       /* Completed state */
+--snice-color-danger        /* Error state */
+--snice-color-text
+--snice-color-text-secondary /* Pending state */
+--snice-color-text-inverse  /* Indicator text */
+--snice-color-background
+--snice-color-border
+--snice-spacing-xs
+--snice-spacing-sm
+--snice-spacing-md
+--snice-spacing-lg
+--snice-font-size-xs
+--snice-font-size-sm
+--snice-font-weight-medium
+--snice-font-weight-semibold
+--snice-transition-fast
+```
+
+## Common Patterns
+
+```html
+<!-- Checkout flow -->
+<snice-stepper id="checkout" clickable></snice-stepper>
+<button onclick="document.getElementById('checkout').currentStep--">Back</button>
+<button onclick="document.getElementById('checkout').currentStep++">Next</button>
+<script>
+  document.getElementById('checkout').steps = [
+    { label: 'Cart', description: 'Review items' },
+    { label: 'Delivery', description: 'Shipping address' },
+    { label: 'Payment', description: 'Billing info' },
+    { label: 'Confirm', description: 'Place order' }
+  ];
+</script>
+
+<!-- Onboarding wizard (vertical) -->
+<snice-stepper id="onboarding" orientation="vertical" clickable></snice-stepper>
+<script>
+  document.getElementById('onboarding').steps = [
+    { label: 'Welcome' },
+    { label: 'Profile Setup' },
+    { label: 'Preferences' },
+    { label: 'Get Started' }
+  ];
+</script>
+
+<!-- Form validation -->
+<snice-stepper id="form"></snice-stepper>
+<script>
+  document.getElementById('form').steps = [
+    { label: 'Personal Info', status: 'completed' },
+    { label: 'Address', status: 'error' },  // Has validation error
+    { label: 'Review', status: 'pending' }
+  ];
+</script>
+
+<!-- Progress tracker -->
+<snice-stepper id="upload"></snice-stepper>
+<script>
+  const upload = document.getElementById('upload');
+  upload.steps = [
+    { label: 'Upload', status: 'completed' },
+    { label: 'Process', status: 'active' },
+    { label: 'Complete', status: 'pending' }
+  ];
+  upload.currentStep = 1;
+</script>
+```
+
+## Stepper Panels
+
+```html
+<!-- Panels auto show/hide based on currentStep -->
+<snice-stepper id="wizard"></snice-stepper>
+<snice-stepper-panel>Content for step 0</snice-stepper-panel>
+<snice-stepper-panel>Content for step 1</snice-stepper-panel>
+<snice-stepper-panel>Content for step 2</snice-stepper-panel>
+```
+
+- Panels must be direct children of stepper
+- Panel index matches order (first panel = step 0, etc.)
+- Automatically activated when stepper.currentStep changes
+- Only active panel is visible (display: block), others hidden
+
+## Notes
+
+- Status auto-computed from currentStep if not explicitly set:
+  - Steps before currentStep: 'completed' (shows ✓)
+  - Step at currentStep: 'active'
+  - Steps after currentStep: 'pending'
+- Completed steps show checkmark (✓) instead of number
+- Connector lines auto-hidden on last step
+- Click events only work when clickable=true
+- step-change event is cancelable via preventDefault()
+- Orientation affects layout but not behavior
+- Panels sync automatically via @watch decorator on currentStep

package/docs/ai/components/textarea.md

@@ -0,0 +1,87 @@
+# snice-textarea
+
+Multi-line text input field with auto-grow and character count.
+
+## Properties
+
+```typescript
+value: string = '';
+variant: 'outlined'|'filled'|'underlined' = 'outlined';
+size: 'small'|'medium'|'large' = 'medium';
+resize: 'none'|'vertical'|'horizontal'|'both' = 'vertical';
+placeholder: string = '';
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+label: string = '';
+helperText: string = '';
+errorText: string = '';
+rows: number = 3;
+cols: number = -1;
+minlength: number = -1;
+maxlength: number = -1;
+autocomplete: string = '';
+name: string = '';
+autoGrow: boolean = false;
+```
+
+## Methods
+
+- `focus()` - Focus textarea
+- `blur()` - Blur textarea
+- `select()` - Select text
+
+## Events
+
+- `input` - {value, textarea}
+- `change` - {value, textarea}
+- `focus` - {textarea}
+- `blur` - {textarea}
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-textarea label="Comments" placeholder="Enter comments"></snice-textarea>
+
+<!-- Variants -->
+<snice-textarea variant="outlined"></snice-textarea>
+<snice-textarea variant="filled"></snice-textarea>
+<snice-textarea variant="underlined"></snice-textarea>
+
+<!-- Rows -->
+<snice-textarea rows="5"></snice-textarea>
+
+<!-- Auto-grow -->
+<snice-textarea auto-grow></snice-textarea>
+
+<!-- Character count -->
+<snice-textarea maxlength="500"></snice-textarea>
+
+<!-- Resize options -->
+<snice-textarea resize="none"></snice-textarea>
+<snice-textarea resize="both"></snice-textarea>
+
+<!-- Sizes -->
+<snice-textarea size="small"></snice-textarea>
+<snice-textarea size="medium"></snice-textarea>
+<snice-textarea size="large"></snice-textarea>
+
+<!-- Helper text -->
+<snice-textarea helper-text="Max 500 characters"></snice-textarea>
+
+<!-- Error state -->
+<snice-textarea invalid error-text="Required field"></snice-textarea>
+```
+
+## Features
+
+- Form-associated custom element
+- 3 visual variants
+- Auto-grow height option
+- Character counter
+- Resizable (4 modes)
+- Helper and error text
+- 3 sizes
+- Keyboard accessible

package/docs/ai/components/timeline.md

@@ -0,0 +1,77 @@
+# snice-timeline
+
+Displays chronological events with markers.
+
+## Properties
+
+```typescript
+orientation: 'vertical'|'horizontal' = 'vertical';
+position: 'left'|'right'|'alternate' = 'left';
+items: TimelineItem[] = [];
+reverse: boolean = false;
+```
+
+## TimelineItem
+
+```typescript
+interface TimelineItem {
+  timestamp?: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  variant?: 'default'|'success'|'warning'|'error'|'info';
+}
+```
+
+## Usage
+
+```html
+<!-- Basic --><snice-timeline id="timeline"></snice-timeline>
+<script>
+timeline.items = [{
+  timestamp: '2024-01-15',
+  title: 'Event',
+  description: 'Details'
+}];
+</script>
+
+<!-- Vertical positions -->
+<snice-timeline position="left"></snice-timeline>
+<snice-timeline position="right"></snice-timeline>
+<snice-timeline position="alternate"></snice-timeline>
+
+<!-- Horizontal -->
+<snice-timeline orientation="horizontal"></snice-timeline>
+
+<!-- Variants -->
+<script>
+timeline.items = [
+  { title: 'Success', variant: 'success' },
+  { title: 'Warning', variant: 'warning' },
+  { title: 'Error', variant: 'error' },
+  { title: 'Info', variant: 'info' }
+];
+</script>
+
+<!-- Custom icons -->
+<script>
+timeline.items = [
+  { title: 'Planning', icon: '📋' },
+  { title: 'Development', icon: '💻' },
+  { title: 'Launch', icon: '🚀' }
+];
+</script>
+
+<!-- Reversed -->
+<snice-timeline reverse></snice-timeline>
+```
+
+## Features
+
+- Vertical and horizontal orientations
+- Left/right/alternate positioning (vertical)
+- 5 item variants with default icons
+- Custom icons supported
+- Timestamps and descriptions optional
+- Connecting lines between items
+- Reversible order

package/docs/ai/components/tree.md

@@ -0,0 +1,191 @@
+# snice-tree
+
+Hierarchical tree view with expandable nodes, selection, checkboxes, icons, and lazy loading.
+
+## Properties
+
+```typescript
+nodes: TreeNode[] = [];
+selectionMode: 'single'|'multiple'|'none' = 'single';
+showCheckboxes: boolean = false;
+showIcons: boolean = true;
+expandOnClick: boolean = false;
+selectedNodes: string[] = [];
+checkedNodes: string[] = [];
+```
+
+## 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
+}
+```
+
+## Methods
+
+### Expand/Collapse
+- `expandNode(id: string)` - Expand a node
+- `collapseNode(id: string)` - Collapse a node
+- `toggleNode(id: string)` - Toggle node expansion
+- `expandAll()` - Expand all nodes
+- `collapseAll()` - Collapse all nodes
+
+### Selection
+- `selectNode(id: string)` - Select a node
+- `deselectNode(id: string)` - Deselect a node
+- `toggleSelection(id: string)` - Toggle selection
+
+### Checkboxes
+- `checkNode(id: string)` - Check a node
+- `uncheckNode(id: string)` - Uncheck a node
+- `toggleCheck(id: string)` - Toggle check state
+
+### Getters
+- `getNode(id: string): TreeNode | undefined` - Get node by ID
+- `getSelectedNodes(): TreeNode[]` - Get all selected nodes
+- `getCheckedNodes(): TreeNode[]` - Get all checked nodes
+
+## Events
+
+- `@snice/tree-node-expand` - Node expanded (detail: { nodeId, node, tree })
+- `@snice/tree-node-collapse` - Node collapsed (detail: { nodeId, node, tree })
+- `@snice/tree-node-select` - Node selected (detail: { nodeId, node, selectedNodes, tree })
+- `@snice/tree-node-check` - Node checked/unchecked (detail: { nodeId, node, checked, checkedNodes, tree })
+- `@snice/tree-node-lazy-load` - Lazy node expanded (detail: { nodeId, node, tree })
+
+## Usage
+
+```html
+<!-- Basic file tree -->
+<snice-tree id="fileTree"></snice-tree>
+<script>
+  document.getElementById('fileTree').nodes = [
+    {
+      id: 'src',
+      label: 'src',
+      icon: '📁',
+      expanded: true,
+      children: [
+        { id: 'index.ts', label: 'index.ts', icon: '📄' },
+        {
+          id: 'components',
+          label: 'components',
+          icon: '📁',
+          children: [
+            { id: 'header.ts', label: 'header.ts', icon: '📄' }
+          ]
+        }
+      ]
+    }
+  ];
+</script>
+
+<!-- Single selection -->
+<snice-tree selection-mode="single"></snice-tree>
+
+<!-- Multiple selection -->
+<snice-tree selection-mode="multiple"></snice-tree>
+
+<!-- No selection -->
+<snice-tree selection-mode="none"></snice-tree>
+
+<!-- Checkbox selection -->
+<snice-tree show-checkboxes></snice-tree>
+
+<!-- Without icons -->
+<snice-tree show-icons="false"></snice-tree>
+
+<!-- Expand/collapse programmatically -->
+<button onclick="tree.expandAll()">Expand All</button>
+<button onclick="tree.collapseAll()">Collapse All</button>
+
+<!-- Selection events -->
+<snice-tree id="tree"></snice-tree>
+<script>
+  const tree = document.getElementById('tree');
+  tree.addEventListener('@snice/tree-node-select', (e) => {
+    console.log('Selected:', e.detail.node.label);
+    console.log('All selected:', e.detail.selectedNodes.map(n => n.label));
+  });
+</script>
+
+<!-- Lazy loading -->
+<snice-tree id="lazyTree"></snice-tree>
+<script>
+  const lazyTree = document.getElementById('lazyTree');
+  lazyTree.nodes = [
+    {
+      id: 'folder1',
+      label: 'Click to load...',
+      icon: '📁',
+      lazy: true,
+      children: []
+    }
+  ];
+
+  lazyTree.addEventListener('@snice/tree-node-lazy-load', async (e) => {
+    const node = e.detail.node;
+    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.lazy = false;
+    node.expanded = true;
+
+    // Trigger re-render
+    lazyTree.nodes = [...lazyTree.nodes];
+  });
+</script>
+
+<!-- Custom icons with images -->
+<snice-tree id="imgTree"></snice-tree>
+<script>
+  document.getElementById('imgTree').nodes = [
+    {
+      id: '1',
+      label: 'Images',
+      iconImage: '/icons/folder.png',
+      children: [
+        { id: '2', label: 'photo.jpg', iconImage: '/icons/image.png' }
+      ]
+    }
+  ];
+</script>
+
+<!-- Disabled nodes -->
+<snice-tree id="disabledTree"></snice-tree>
+<script>
+  document.getElementById('disabledTree').nodes = [
+    { id: '1', label: 'Active Node' },
+    { id: '2', label: 'Disabled Node', disabled: true }
+  ];
+</script>
+```
+
+## Features
+
+- Hierarchical data display
+- Expand/collapse nodes
+- Single/multiple/no selection modes
+- Checkbox support for multi-select
+- Text and image icons
+- Lazy loading for large trees
+- Disabled nodes
+- Keyboard navigation (Arrow keys, Enter, Space, Home, End)
+- Full ARIA accessibility
+- Programmatic control
+- Custom data storage per node

package/docs/ai/components/virtual-scroller.md

@@ -0,0 +1,71 @@
+# snice-virtual-scroller
+
+Efficiently render large lists by only displaying visible items.
+
+## Properties
+
+```typescript
+items: VirtualScrollerItem[] = [];
+itemHeight: number = 50; // px
+bufferSize: number = 5; // extra items outside viewport
+estimatedItemHeight: number = 50;
+renderItem: (item: VirtualScrollerItem, index: number) => string | HTMLElement;
+```
+
+## VirtualScrollerItem
+
+```typescript
+interface VirtualScrollerItem {
+  id: string | number;
+  data: any;
+  height?: number; // optional custom height
+}
+```
+
+## Methods
+
+```typescript
+scrollToIndex(index: number): void
+scrollToItem(id: string | number): void
+refresh(): void
+getVisibleRange(): { start: number; end: number }
+```
+
+## Usage
+
+```javascript
+scroller.items = Array.from({ length: 10000 }, (_, i) => ({
+  id: i,
+  data: `Item ${i}`
+}));
+
+scroller.renderItem = (item, index) => {
+  return `<div>${item.data}</div>`;
+};
+
+// Scroll to item
+scroller.scrollToIndex(500);
+
+// Get visible range
+const range = scroller.getVisibleRange();
+```
+
+```html
+<snice-virtual-scroller
+  style="height: 400px;"
+  item-height="60"
+  buffer-size="10">
+</snice-virtual-scroller>
+```
+
+## Features
+
+- Only renders visible items + buffer
+- Handles thousands of items efficiently
+- Variable item heights supported
+- Programmatic scrolling
+- Dynamic updates (add/remove/update)
+- Smooth 60fps scrolling
+- Low memory footprint
+- Search and filter support
+- Infinite scroll patterns