snice 4.9.0 → 4.10.0

package/docs/components/virtual-scroller.md

@@ -1,298 +1,158 @@
-# Virtual Scroller Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/virtual-scroller.md instead)
 
-Efficiently render large lists by only displaying visible items.
+# Virtual Scroller
+`<snice-virtual-scroller>`
 
-## Basic Usage
-
-```javascript
-const scroller = document.querySelector('snice-virtual-scroller');
-
-scroller.items = Array.from({ length: 10000 }, (_, i) => ({
-  id: i,
-  data: `Item ${i}`
-}));
-
-scroller.renderItem = (item, index) => {
-  return `<div>${item.data}</div>`;
-};
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `items` | `VirtualScrollerItem[]` | `[]` | Array of items to render |
-| `itemHeight` | `number` | `50` | Height of each item (px) |
-| `bufferSize` | `number` | `5` | Extra items to render outside viewport |
-| `estimatedItemHeight` | `number` | `50` | Estimated height for variable items |
-| `renderItem` | `Function` | - | Function to render each item |
+Efficiently renders large lists by only displaying visible items.
 
-## VirtualScrollerItem Interface
+## Basic Usage
 
 ```typescript
-interface VirtualScrollerItem {
-  id: string | number;  // Unique identifier
-  data: any;           // Item data
-  height?: number;     // Optional custom height
-}
+import 'snice/components/virtual-scroller/snice-virtual-scroller';
 ```
 
-## Methods
-
-### `scrollToIndex(index: number): void`
-Scroll to specific item index.
+```html
+<snice-virtual-scroller id="list" style="height: 400px;"></snice-virtual-scroller>
 
-```javascript
-scroller.scrollToIndex(500);
-```
+<script>
+  const scroller = document.getElementById('list');
 
-### `scrollToItem(id: string | number): void`
-Scroll to item by ID.
+  scroller.items = Array.from({ length: 10000 }, (_, i) => ({
+    id: i,
+    data: `Item ${i + 1}`
+  }));
 
-```javascript
-scroller.scrollToItem('item-123');
+  scroller.renderItem = (item) => {
+    return `<div style="padding: 15px; border-bottom: 1px solid #eee;">${item.data}</div>`;
+  };
+</script>
 ```
 
-### `refresh(): void`
-Recalculate visible range and re-render.
+## Importing
 
-```javascript
-scroller.refresh();
+**ESM (bundler)**
+```typescript
+import 'snice/components/virtual-scroller/snice-virtual-scroller';
 ```
 
-### `getVisibleRange(): { start: number; end: number }`
-Get currently visible item indices.
-
-```javascript
-const range = scroller.getVisibleRange();
-console.log(`Showing items ${range.start} to ${range.end}`);
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-virtual-scroller.min.js"></script>
 ```
 
 ## Examples
 
-### Simple List
-
-```javascript
-const scroller = document.querySelector('snice-virtual-scroller');
-
-scroller.items = Array.from({ length: 10000 }, (_, i) => ({
-  id: i,
-  data: `Item ${i + 1}`
-}));
-
-scroller.renderItem = (item) => {
-  return `<div style="padding: 15px; border-bottom: 1px solid #eee;">
-    ${item.data}
-  </div>`;
-};
-```
-
-### User List
+### Custom Item Height
 
-```javascript
-scroller.items = Array.from({ length: 5000 }, (_, i) => ({
-  id: i,
-  data: {
-    name: `User ${i + 1}`,
-    email: `user${i + 1}@example.com`
-  }
-}));
+Use the `item-height` attribute to set the height of each item in pixels.
 
-scroller.renderItem = (item) => {
-  return `<div class="user-item">
-    <div class="user-name">${item.data.name}</div>
-    <div class="user-email">${item.data.email}</div>
-  </div>`;
-};
+```html
+<snice-virtual-scroller item-height="80" style="height: 600px;"></snice-virtual-scroller>
 ```
 
 ### Variable Height Items
 
+Set individual `height` values on items for variable row heights.
+
 ```javascript
 scroller.items = Array.from({ length: 1000 }, (_, i) => ({
   id: i,
-  data: {
-    title: `Post ${i + 1}`,
-    content: i % 2 === 0 ? 'Short content' : 'Longer content with more text...'
-  },
+  data: { title: `Post ${i + 1}` },
   height: i % 2 === 0 ? 60 : 100
 }));
-
-scroller.renderItem = (item) => {
-  return `<div style="padding: 15px;">
-    <h3>${item.data.title}</h3>
-    <p>${item.data.content}</p>
-  </div>`;
-};
-```
-
-### Custom Item Height
-
-```html
-<snice-virtual-scroller
-  style="height: 600px;"
-  item-height="80">
-</snice-virtual-scroller>
 ```
 
 ### Custom Buffer Size
 
+Use the `buffer-size` attribute to control how many extra items are rendered outside the viewport.
+
 ```html
-<snice-virtual-scroller
-  buffer-size="10"
-  style="height: 400px;">
-</snice-virtual-scroller>
+<snice-virtual-scroller buffer-size="10" style="height: 400px;"></snice-virtual-scroller>
 ```
 
 ### Programmatic Scrolling
 
 ```javascript
-// Scroll to top
-scroller.scrollToIndex(0);
+scroller.scrollToIndex(500);          // Scroll to index
+scroller.scrollToItem('item-123');    // Scroll to item by ID
+scroller.refresh();                   // Recalculate layout
 
-// Scroll to middle
-scroller.scrollToIndex(Math.floor(scroller.items.length / 2));
-
-// Scroll to specific item
-scroller.scrollToItem('item-500');
+const range = scroller.getVisibleRange();
+console.log(`Showing items ${range.start} to ${range.end}`);
 ```
 
-### With Search
+### User List
 
 ```javascript
-const allItems = Array.from({ length: 10000 }, (_, i) => ({
+scroller.items = Array.from({ length: 5000 }, (_, i) => ({
   id: i,
-  data: { name: `Item ${i + 1}`, value: i }
+  data: { name: `User ${i + 1}`, email: `user${i + 1}@example.com` }
 }));
 
-scroller.items = allItems;
-
-// Filter items
-function filterItems(query) {
-  if (!query) {
-    scroller.items = allItems;
-  } else {
-    scroller.items = allItems.filter(item =>
-      item.data.name.toLowerCase().includes(query.toLowerCase())
-    );
-  }
-  scroller.refresh();
-}
-```
-
-### With Sorting
-
-```javascript
-function sortItems(field, order = 'asc') {
-  scroller.items = [...scroller.items].sort((a, b) => {
-    const aVal = a.data[field];
-    const bVal = b.data[field];
-    return order === 'asc' ? aVal - bVal : bVal - aVal;
-  });
-  scroller.refresh();
-}
-```
-
-### Complex Item Rendering
-
-```javascript
-scroller.renderItem = (item, index) => {
-  return `
-    <div class="complex-item" data-id="${item.id}">
-      <div class="item-header">
-        <img src="${item.data.avatar}" alt="${item.data.name}">
-        <span>${item.data.name}</span>
-        <span class="badge">${item.data.status}</span>
-      </div>
-      <div class="item-content">
-        ${item.data.description}
-      </div>
-      <div class="item-footer">
-        <button onclick="handleEdit(${item.id})">Edit</button>
-        <button onclick="handleDelete(${item.id})">Delete</button>
-      </div>
-    </div>
-  `;
+scroller.renderItem = (item) => {
+  return `<div style="padding: 12px;">
+    <div style="font-weight: 600;">${item.data.name}</div>
+    <div style="color: #666;">${item.data.email}</div>
+  </div>`;
 };
 ```
 
-### Infinite Scroll
+### Filtering
 
 ```javascript
-let currentPage = 1;
-const itemsPerPage = 100;
-
-async function loadMore() {
-  const newItems = await fetchItems(currentPage);
+const allItems = Array.from({ length: 10000 }, (_, i) => ({
+  id: i,
+  data: { name: `Item ${i + 1}` }
+}));
 
-  scroller.items = [
-    ...scroller.items,
-    ...newItems
-  ];
+scroller.items = allItems;
 
+function filterItems(query) {
+  scroller.items = query
+    ? allItems.filter(item => item.data.name.toLowerCase().includes(query.toLowerCase()))
+    : allItems;
   scroller.refresh();
-  currentPage++;
 }
-
-scroller.addEventListener('scroll', (e) => {
-  const { scrollTop, scrollHeight, clientHeight } = e.target;
-
-  // Load more when near bottom
-  if (scrollHeight - scrollTop - clientHeight < 200) {
-    loadMore();
-  }
-});
 ```
 
 ### Dynamic Updates
 
 ```javascript
 // Add item
-function addItem(data) {
-  scroller.items = [
-    ...scroller.items,
-    { id: Date.now(), data }
-  ];
-  scroller.refresh();
-}
+scroller.items = [...scroller.items, { id: Date.now(), data: newData }];
+scroller.refresh();
 
 // Remove item
-function removeItem(id) {
-  scroller.items = scroller.items.filter(item => item.id !== id);
-  scroller.refresh();
-}
-
-// Update item
-function updateItem(id, newData) {
-  scroller.items = scroller.items.map(item =>
-    item.id === id ? { ...item, data: { ...item.data, ...newData } } : item
-  );
-  scroller.refresh();
-}
+scroller.items = scroller.items.filter(item => item.id !== targetId);
+scroller.refresh();
 ```
 
-## Performance
-
-Virtual scrolling provides significant performance benefits for large lists:
-
-- **Without virtual scrolling:** 10,000 items = 10,000 DOM elements
-- **With virtual scrolling:** 10,000 items = ~20-30 DOM elements (only visible items)
+## Properties
 
-This results in:
-- Faster initial render
-- Smooth 60fps scrolling
-- Lower memory usage
-- Better overall UX
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `items` | `VirtualScrollerItem[]` | `[]` | Array of items to render |
+| `itemHeight` (attr: `item-height`) | `number` | `50` | Default item height (px) |
+| `bufferSize` (attr: `buffer-size`) | `number` | `5` | Extra items rendered outside viewport |
+| `estimatedItemHeight` (attr: `estimated-item-height`) | `number` | `50` | Estimated height for variable items |
+| `renderItem` | `(item: VirtualScrollerItem, index: number) => string` | -- | Function to render each item |
 
-## Accessibility
+### VirtualScrollerItem Interface
 
-- Maintains scroll position
-- Keyboard navigation supported
-- Screen readers can navigate items
-- Supports ARIA attributes in rendered items
+```typescript
+interface VirtualScrollerItem {
+  id: string | number;
+  data: any;
+  height?: number;
+}
+```
 
-## Browser Support
+## Methods
 
-- Modern browsers with Custom Elements v1 support
-- Uses CSS transforms for smooth scrolling
-- Efficient rendering with minimal reflows
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `scrollToIndex()` | `index: number` | Scroll to item at index |
+| `scrollToItem()` | `id: string \| number` | Scroll to item by ID |
+| `refresh()` | -- | Recalculate visible range and re-render |
+| `getVisibleRange()` | -- | Returns `{ start: number, end: number }` |

package/docs/components/waterfall.md

@@ -0,0 +1,217 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/waterfall.md instead)
+
+# Waterfall Component
+
+The waterfall component renders a waterfall chart (also known as a bridge chart) that visualizes the cumulative effect of sequential positive and negative values. Bars are color-coded by type: green for increases, red for decreases, and blue for totals, with optional connector lines and value labels.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-waterfall></snice-waterfall>
+```
+
+```typescript
+import 'snice/components/waterfall/snice-waterfall';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `WaterfallDataPoint[]` | `[]` | Array of data points to render |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chart orientation |
+| `showValues` (attr: `show-values`) | `boolean` | `true` | Display value labels on bars |
+| `showConnectors` (attr: `show-connectors`) | `boolean` | `true` | Show connector lines between bars |
+| `animated` | `boolean` | `false` | Animate bars on render |
+
+### WaterfallDataPoint
+
+```typescript
+interface WaterfallDataPoint {
+  label: string;                                      // Bar label text
+  value: number;                                      // Numeric value
+  type?: 'increase' | 'decrease' | 'total';           // Bar type (auto-detected from value sign if omitted)
+}
+```
+
+When `type` is omitted, it is automatically determined: positive values render as `increase` (green) and negative values render as `decrease` (red). Use `type: 'total'` explicitly for summary bars.
+
+## Events
+
+### `bar-click`
+Fired when a bar is clicked.
+
+**Event Detail:**
+```typescript
+{
+  item: WaterfallDataPoint;
+  index: number;
+}
+```
+
+### `bar-hover`
+Fired when the mouse enters a bar.
+
+**Event Detail:**
+```typescript
+{
+  item: WaterfallDataPoint;
+  index: number;
+}
+```
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--snice-color-success` | Increase bar fill color | `rgb(22 163 74)` |
+| `--snice-color-danger` | Decrease bar fill color | `rgb(220 38 38)` |
+| `--snice-color-primary` | Total bar fill color | `rgb(37 99 235)` |
+| `--snice-color-text-secondary` | Label text color | _(theme default)_ |
+| `--snice-color-text-tertiary` | Connector line color | _(theme default)_ |
+| `--snice-color-border` | Zero-line axis color | `rgb(226 226 226)` |
+| `--snice-transition-fast` | Bar hover transition speed | `150ms` |
+| `--snice-font-weight-medium` | Value text font weight | _(theme default)_ |
+
+## Examples
+
+### Profit & Loss Waterfall
+
+Show how revenue, costs, and taxes contribute to a final balance.
+
+```html
+<snice-waterfall id="pnl-chart" show-values show-connectors></snice-waterfall>
+
+<script type="module">
+  import 'snice/components/waterfall/snice-waterfall';
+
+  const chart = document.getElementById('pnl-chart');
+  chart.data = [
+    { label: 'Starting Balance', value: 1000, type: 'total' },
+    { label: 'Revenue', value: 500 },
+    { label: 'Services', value: 300 },
+    { label: 'Costs', value: -200 },
+    { label: 'Wages', value: -350 },
+    { label: 'Tax', value: -100 },
+    { label: 'Net Income', value: 1150, type: 'total' }
+  ];
+</script>
+```
+
+### Horizontal Orientation
+
+Render the waterfall chart horizontally instead of vertically.
+
+```html
+<snice-waterfall id="horizontal-chart" orientation="horizontal" show-values></snice-waterfall>
+
+<script type="module">
+  const chart = document.getElementById('horizontal-chart');
+  chart.data = [
+    { label: 'Q1 Start', value: 5000, type: 'total' },
+    { label: 'Sales', value: 2000 },
+    { label: 'Returns', value: -300 },
+    { label: 'Marketing', value: -800 },
+    { label: 'Q1 End', value: 5900, type: 'total' }
+  ];
+</script>
+```
+
+### Animated Chart
+
+Use the `animated` property to animate bars when the chart renders.
+
+```html
+<snice-waterfall id="animated-chart" animated show-values show-connectors></snice-waterfall>
+
+<script type="module">
+  const chart = document.getElementById('animated-chart');
+  chart.data = [
+    { label: 'January', value: 10000, type: 'total' },
+    { label: 'New Subscriptions', value: 3500 },
+    { label: 'Upgrades', value: 1200 },
+    { label: 'Churn', value: -2100 },
+    { label: 'Refunds', value: -400 },
+    { label: 'February', value: 12200, type: 'total' }
+  ];
+</script>
+```
+
+### Bar Click Handling
+
+Listen for bar clicks to display details or navigate to related views.
+
+```html
+<snice-waterfall id="clickable-chart" show-values></snice-waterfall>
+<p id="click-info">Click a bar to see details.</p>
+
+<script type="module">
+  const chart = document.getElementById('clickable-chart');
+  const info = document.getElementById('click-info');
+
+  chart.data = [
+    { label: 'Budget', value: 50000, type: 'total' },
+    { label: 'Hiring', value: -15000 },
+    { label: 'Equipment', value: -8000 },
+    { label: 'Revenue', value: 20000 },
+    { label: 'Remaining', value: 47000, type: 'total' }
+  ];
+
+  chart.addEventListener('bar-click', (e) => {
+    const { item, index } = e.detail;
+    info.textContent = `Clicked: ${item.label} = ${item.value > 0 ? '+' : ''}${item.value}`;
+  });
+</script>
+```
+
+### Without Connectors or Values
+
+Hide connector lines and value labels for a cleaner visual.
+
+```html
+<snice-waterfall id="clean-chart"></snice-waterfall>
+
+<script type="module">
+  const chart = document.getElementById('clean-chart');
+  chart.showValues = false;
+  chart.showConnectors = false;
+  chart.data = [
+    { label: 'Start', value: 100, type: 'total' },
+    { label: 'Add', value: 40 },
+    { label: 'Remove', value: -25 },
+    { label: 'Add', value: 15 },
+    { label: 'End', value: 130, type: 'total' }
+  ];
+</script>
+```
+
+## Accessibility
+
+- **ARIA roles**: Bars use appropriate roles for data visualization
+- **Value labels**: When `showValues` is enabled, values are displayed as text for screen readers
+- **Color and text**: Bar types are distinguishable not only by color but also by their value labels (positive/negative numbers)
+- **Keyboard support**: Bars are focusable and clickable via keyboard
+- **Reduced motion**: When `animated` is set, animations respect `prefers-reduced-motion`
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Always include total bars**: Start and end with `type: 'total'` bars so viewers can see the full picture
+2. **Use meaningful labels**: Labels should clearly describe what each bar represents
+3. **Keep data sets manageable**: 5-10 bars work well; more than 15 can become hard to read
+4. **Show connectors for clarity**: Connector lines help viewers trace the cumulative flow between bars
+5. **Let type auto-detect when possible**: Omit `type` for regular increase/decrease bars; only specify `type: 'total'` explicitly
+6. **Use animation for presentations**: The `animated` option works well for slide decks and dashboards where data loads dynamically
+7. **Choose orientation based on labels**: Use `horizontal` when labels are long; `vertical` when labels are short