snice 3.2.0 → 3.3.1

package/docs/ai/components/menu.md

@@ -0,0 +1,114 @@
+# snice-menu
+
+Dropdown menu with items, dividers, and configurable trigger behavior.
+
+## Properties
+
+```typescript
+open: boolean = false;
+placement: 'bottom-start'|'bottom-end'|'top-start'|'top-end'|'right-start'|'right-end'|'left-start'|'left-end' = 'bottom-start';
+trigger: 'click'|'hover'|'manual' = 'click';
+closeOnSelect: boolean = true;
+distance: number = 4;
+```
+
+## Methods
+
+- `openMenu()` - Open the menu
+- `closeMenu()` - Close the menu
+- `toggleMenu()` - Toggle menu open/closed state
+
+## Slots
+
+- `trigger` - Element that triggers the menu (required)
+- Default slot - Menu items and dividers
+
+## Events
+
+- `@snice/menu-open` - Fired when menu opens (detail: { menu: SniceMenuElement })
+- `@snice/menu-close` - Fired when menu closes (detail: { menu: SniceMenuElement })
+
+## Usage
+
+```html
+<!-- Basic menu -->
+<snice-menu>
+  <button slot="trigger">Open Menu</button>
+  <snice-menu-item value="new">New File</snice-menu-item>
+  <snice-menu-item value="open">Open</snice-menu-item>
+  <snice-menu-divider></snice-menu-divider>
+  <snice-menu-item value="save">Save</snice-menu-item>
+</snice-menu>
+
+<!-- With icons and shortcuts -->
+<snice-menu>
+  <button slot="trigger">Edit</button>
+  <snice-menu-item value="cut">
+    <span slot="icon">✂️</span>
+    Cut
+    <span slot="shortcut">⌘X</span>
+  </snice-menu-item>
+  <snice-menu-item value="copy">
+    <span slot="icon">📋</span>
+    Copy
+    <span slot="shortcut">⌘C</span>
+  </snice-menu-item>
+  <snice-menu-item value="paste">
+    <span slot="icon">📄</span>
+    Paste
+    <span slot="shortcut">⌘V</span>
+  </snice-menu-item>
+</snice-menu>
+
+<!-- Different placements -->
+<snice-menu placement="top-start">...</snice-menu>
+<snice-menu placement="right-start">...</snice-menu>
+
+<!-- Hover trigger -->
+<snice-menu trigger="hover">...</snice-menu>
+
+<!-- Manual control -->
+<snice-menu trigger="manual" id="my-menu">...</snice-menu>
+<script>
+  document.getElementById('my-menu').openMenu();
+</script>
+
+<!-- Keep open on select -->
+<snice-menu close-on-select="false">...</snice-menu>
+```
+
+## snice-menu-item
+
+### Properties
+
+```typescript
+value: string = '';
+disabled: boolean = false;
+selected: boolean = false;
+```
+
+### Slots
+
+- `icon` - Icon before label
+- Default slot - Item label
+- `shortcut` - Keyboard shortcut text
+
+### Events
+
+- `@snice/menu-item-select` - Fired when item is clicked (detail: { item: SniceMenuItemElement, value: string })
+
+## snice-menu-divider
+
+Visual separator between menu items.
+
+## Features
+
+- 8 placement options
+- Click, hover, or manual trigger modes
+- Auto-close on item selection (configurable)
+- Auto-close on outside click
+- Icon and shortcut support
+- Disabled state for items
+- Selected state for items
+- Keyboard accessible (aria roles)
+- Configurable distance from trigger

package/docs/ai/components/popover.md

@@ -0,0 +1,70 @@
+# snice-popover
+
+Floating content positioned relative to target element.
+
+## Properties
+
+```typescript
+open: boolean = false;
+placement: 'top'|'bottom'|'left'|'right'|'top-start'|'top-end'|'bottom-start'|'bottom-end'|'left-start'|'left-end'|'right-start'|'right-end' = 'top';
+trigger: 'click'|'hover'|'focus'|'manual' = 'click';
+distance: number = 8;
+showArrow: boolean = true;
+closeOnClickOutside: boolean = true;
+closeOnEscape: boolean = true;
+hoverDelay: number = 200;
+targetSelector: string = '';
+```
+
+## Methods
+
+```typescript
+show(): void
+hide(): void
+toggle(): void
+updatePosition(): void
+```
+
+## Events
+
+- `@snice/popover-show` - Dispatched when shown
+- `@snice/popover-hide` - Dispatched when hidden
+
+## Usage
+
+```html
+<button id="btn">Click me</button>
+<snice-popover target-selector="#btn">
+  Popover content
+</snice-popover>
+
+<!-- Hover trigger -->
+<snice-popover target-selector="#btn" trigger="hover">
+  Appears on hover
+</snice-popover>
+
+<!-- Manual control -->
+<snice-popover id="pop" trigger="manual">Content</snice-popover>
+<script>
+  document.getElementById('pop').show();
+</script>
+
+<!-- Different placements -->
+<snice-popover placement="bottom">Bottom</snice-popover>
+<snice-popover placement="left-start">Left Start</snice-popover>
+
+<!-- No arrow -->
+<snice-popover show-arrow="false">No arrow</snice-popover>
+```
+
+## Features
+
+- 12 placement options with start/end alignment
+- Multiple triggers (click/hover/focus/manual)
+- Arrow indicator (optional)
+- Auto-positioning with scroll/resize
+- Close on click outside or Escape
+- Hover delay configuration
+- Target via selector or previous sibling
+- Fixed positioning overlay
+- Event dispatching

package/docs/ai/components/qr-code.md

@@ -0,0 +1,106 @@
+# snice-qr-code
+
+QR code generator with customizable styling and export.
+
+## Properties
+
+```typescript
+value: string = '';
+size: number = 200;
+errorCorrectionLevel: 'L'|'M'|'Q'|'H' = 'M';
+renderMode: 'canvas'|'svg' = 'svg';
+margin: number = 4;
+fgColor: string = '#000000';
+bgColor: string = '#ffffff';
+includeImage: boolean = false;
+imageUrl: string = '';
+imageSize: number = 40;
+```
+
+## Methods
+
+```typescript
+toDataURL(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): Promise<string>
+toBlob(type?: 'image/png'|'image/jpeg'|'image/webp', quality?: number): Promise<Blob>
+download(filename?: string): void
+```
+
+## Usage
+
+```javascript
+// Basic
+qr.value = 'https://example.com';
+qr.size = 200;
+
+// Custom colors
+qr.fgColor = '#2196f3';
+qr.bgColor = '#e3f2fd';
+
+// Error correction
+qr.errorCorrectionLevel = 'H'; // L|M|Q|H
+
+// Canvas mode
+qr.renderMode = 'canvas';
+
+// With image overlay
+qr.includeImage = true;
+qr.imageUrl = 'logo.png';
+qr.imageSize = 50;
+
+// Export
+const dataURL = await qr.toDataURL('image/png', 0.92);
+const blob = await qr.toBlob('image/png');
+qr.download('qr-code.png');
+```
+
+```html
+<snice-qr-code
+  value="https://example.com"
+  size="250"
+  fg-color="#000000"
+  bg-color="#ffffff"
+  error-correction-level="M"
+  render-mode="svg">
+</snice-qr-code>
+```
+
+## Common Formats
+
+```javascript
+// URL
+qr.value = 'https://example.com';
+
+// Email
+qr.value = 'mailto:name@example.com';
+
+// Phone
+qr.value = 'tel:+1234567890';
+
+// SMS
+qr.value = 'sms:+1234567890?body=Hello';
+
+// WiFi
+qr.value = 'WIFI:T:WPA;S:NetworkName;P:password;;';
+
+// vCard
+qr.value = `BEGIN:VCARD
+VERSION:3.0
+FN:John Doe
+TEL:+1234567890
+EMAIL:john@example.com
+END:VCARD`;
+
+// Location
+qr.value = 'geo:37.7749,-122.4194';
+```
+
+## Features
+
+- SVG/Canvas rendering
+- Custom colors
+- Error correction levels
+- Image overlay
+- Export (PNG/JPEG/WebP)
+- Download
+- Adjustable margin
+- Multiple data formats

package/docs/ai/components/split-pane.md

@@ -0,0 +1,71 @@
+# snice-split-pane
+
+Resizable split pane layout.
+
+## Properties
+
+```typescript
+direction: 'horizontal'|'vertical' = 'horizontal';
+primarySize: number = 50; // percentage
+minPrimarySize: number = 10; // percentage
+minSecondarySize: number = 10; // percentage
+snapSize: number = 0; // percentage, 0 = no snap
+disabled: boolean = false;
+```
+
+## Methods
+
+```typescript
+getPrimarySize(): number
+getSecondarySize(): number
+setPrimarySize(size: number): void
+reset(): void
+```
+
+## Events
+
+- `@snice/resize` - Dispatched on resize (detail: { primarySize, secondarySize, splitPane })
+
+## Usage
+
+```html
+<snice-split-pane style="height: 400px;">
+  <div slot="primary">Left pane</div>
+  <div slot="secondary">Right pane</div>
+</snice-split-pane>
+
+<!-- Vertical -->
+<snice-split-pane direction="vertical">
+  <div slot="primary">Top</div>
+  <div slot="secondary">Bottom</div>
+</snice-split-pane>
+
+<!-- Custom size -->
+<snice-split-pane primary-size="30">
+  <div slot="primary">30%</div>
+  <div slot="secondary">70%</div>
+</snice-split-pane>
+
+<!-- With snap -->
+<snice-split-pane snap-size="10">
+  <div slot="primary">Snaps to 10%</div>
+  <div slot="secondary">Right</div>
+</snice-split-pane>
+
+<!-- Programmatic -->
+<script>
+  splitPane.setPrimarySize(40);
+  splitPane.reset(); // 50/50
+</script>
+```
+
+## Features
+
+- Horizontal and vertical orientation
+- Drag to resize
+- Minimum sizes for both panes
+- Snap to grid
+- Programmatic control
+- Nested layouts supported
+- Disabled state
+- Event dispatching

package/docs/ai/components/stat.md

@@ -0,0 +1,29 @@
+# snice-stat
+
+Statistics display with trends and icons.
+
+## Properties
+
+```typescript
+label: string = '';
+value: string | number = '';
+change: string | number = '';
+trend: 'up'|'down'|'neutral' = 'neutral';
+size: 'small'|'medium'|'large' = 'medium';
+icon: string = '';
+iconImage: string = '';
+colorValue: boolean = false;
+```
+
+## Usage
+
+```html
+<snice-stat
+  label="Revenue"
+  value="$45,231"
+  change="+12%"
+  trend="up"
+  icon="💰"
+  color-value>
+</snice-stat>
+```

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