snice 4.27.0 → 4.29.0

package/docs/components/order-tracker.md

@@ -1,174 +1,129 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/order-tracker.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/order-tracker.md -->
 
-# Order Tracker Component
+# Order Tracker
+`<snice-order-tracker>`
 
-The order tracker component displays an order status timeline with step indicators, tracking information, timestamps, and descriptions. Supports horizontal and vertical layouts.
+An order status timeline with step indicators, tracking info, timestamps, and descriptions.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/order-tracker/snice-order-tracker';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-order-tracker.min.js"></script>
-```
+- [Data Types](#data-types)
 
 ## Properties
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `steps` | — | `OrderStep[]` | `[]` | Timeline steps |
-| `trackingNumber` | `tracking-number` | `string` | `''` | Tracking number |
-| `carrier` | `carrier` | `string` | `''` | Carrier name (e.g. UPS, FedEx) |
-| `variant` | `variant` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation |
-
-### OrderStep Interface
-
-```typescript
-interface OrderStep {
-  label: string;                                     // Step label
-  status: 'pending' | 'active' | 'completed';       // Step status
-  timestamp?: string;                                // When the step occurred
-  description?: string;                              // Additional details
-  icon?: string;                                     // Custom icon (reserved for future use)
-}
-```
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `steps` | `OrderStep[]` | `[]` | Timeline steps (set via JS) |
+| `trackingNumber` (attr: `tracking-number`) | `string` | `''` | Tracking number |
+| `carrier` | `string` | `''` | Carrier name (e.g. UPS, FedEx) |
+| `variant` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout orientation |
 
 ## Events
 
-#### `step-click`
-Fired when a step is clicked.
-
-**Event Detail:**
-```typescript
-{
-  step: OrderStep;   // The clicked step
-  index: number;     // Step index (0-based)
-}
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `step-click` | `{ step: OrderStep, index: number }` | Fired when a step is clicked |
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `base` | The outer tracker container |
-| `info` | Tracking info section |
-| `steps` | Steps container |
-| `step` | Individual step |
-| `step-indicator` | Step circle indicator |
-| `step-content` | Step label and details |
+Style internal elements from outside the shadow DOM using `::part()`.
 
-## Basic Usage
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | The outer tracker container |
+| `info` | `<div>` | Tracking info section (carrier, tracking number) |
+| `steps` | `<div>` | The steps container |
+| `step` | `<div>` | An individual step |
+| `step-indicator` | `<div>` | Step number or check icon |
+| `step-content` | `<div>` | Step label, timestamp, and description |
 
-```html
-<snice-order-tracker></snice-order-tracker>
-```
+## Basic Usage
 
 ```typescript
 import 'snice/components/order-tracker/snice-order-tracker';
 ```
 
-## Examples
-
-### Order In Transit
-
-A typical order tracking timeline with the shipment in transit.
-
 ```html
-<snice-order-tracker
-  id="tracker"
-  tracking-number="1Z999AA10123456784"
-  carrier="UPS">
-</snice-order-tracker>
+<snice-order-tracker id="tracker" tracking-number="1Z999AA10123456784" carrier="UPS"></snice-order-tracker>
 
 <script type="module">
-  import 'snice/components/order-tracker/snice-order-tracker';
-
   const tracker = document.getElementById('tracker');
   tracker.steps = [
-    { label: 'Ordered', status: 'completed', timestamp: 'Feb 20, 2026 9:15 AM', description: 'Order placed successfully' },
-    { label: 'Confirmed', status: 'completed', timestamp: 'Feb 20, 2026 9:30 AM' },
-    { label: 'Shipped', status: 'active', timestamp: 'Feb 22, 2026 2:00 PM', description: 'Package left the warehouse' },
+    { label: 'Ordered', status: 'completed', timestamp: 'Feb 20, 2026' },
+    { label: 'Confirmed', status: 'completed', timestamp: 'Feb 20, 2026' },
+    { label: 'Shipped', status: 'active', timestamp: 'Feb 22, 2026', description: 'Package left the warehouse' },
     { label: 'Out for Delivery', status: 'pending' },
     { label: 'Delivered', status: 'pending' }
   ];
 </script>
 ```
 
-### Delivered Order
+## Examples
 
-All steps completed indicates the order has been delivered.
+### Vertical Layout
+
+Use `variant="vertical"` for a top-to-bottom timeline.
 
 ```html
-<snice-order-tracker id="delivered-tracker"></snice-order-tracker>
+<snice-order-tracker id="tracker" variant="vertical"></snice-order-tracker>
 
 <script type="module">
-  const tracker = document.getElementById('delivered-tracker');
+  const tracker = document.getElementById('tracker');
   tracker.steps = [
-    { label: 'Ordered', status: 'completed', timestamp: 'Feb 15, 2026' },
-    { label: 'Confirmed', status: 'completed', timestamp: 'Feb 15, 2026' },
-    { label: 'Shipped', status: 'completed', timestamp: 'Feb 17, 2026' },
-    { label: 'Out for Delivery', status: 'completed', timestamp: 'Feb 19, 2026' },
-    { label: 'Delivered', status: 'completed', timestamp: 'Feb 19, 2026', description: 'Left at front door' }
+    { label: 'Order Placed', status: 'completed', timestamp: 'Feb 24, 2026', description: 'Your order has been received' },
+    { label: 'Payment Confirmed', status: 'completed', timestamp: 'Feb 24, 2026' },
+    { label: 'Preparing Order', status: 'active', timestamp: 'Feb 24, 2026', description: 'Your items are being packed' },
+    { label: 'Ready for Pickup', status: 'pending' }
   ];
 </script>
 ```
 
-### Vertical Layout
-
-Use `variant="vertical"` for a top-to-bottom timeline, ideal for sidebars or detailed tracking.
+### Delivered Order
 
-```html
-<snice-order-tracker id="vertical-tracker" variant="vertical"></snice-order-tracker>
+All steps completed indicates the order has been delivered.
 
-<script type="module">
-  const tracker = document.getElementById('vertical-tracker');
-  tracker.steps = [
-    { label: 'Order Placed', status: 'completed', timestamp: 'Feb 24, 2026 10:00 AM', description: 'Your order has been received' },
-    { label: 'Payment Confirmed', status: 'completed', timestamp: 'Feb 24, 2026 10:05 AM', description: 'Payment processed successfully' },
-    { label: 'Preparing Order', status: 'active', timestamp: 'Feb 24, 2026 11:30 AM', description: 'Your items are being packed' },
-    { label: 'Ready for Pickup', status: 'pending' },
-    { label: 'Picked Up', status: 'pending' }
-  ];
-</script>
+```typescript
+tracker.steps = [
+  { label: 'Ordered', status: 'completed', timestamp: 'Feb 15, 2026' },
+  { label: 'Shipped', status: 'completed', timestamp: 'Feb 17, 2026' },
+  { label: 'Delivered', status: 'completed', timestamp: 'Feb 19, 2026', description: 'Left at front door' }
+];
 ```
 
-### Step Click Handling
-
-```html
-<snice-order-tracker id="clickable-tracker"></snice-order-tracker>
+### Event Handling
 
-<script type="module">
-  const tracker = document.getElementById('clickable-tracker');
-  tracker.steps = [
-    { label: 'Ordered', status: 'completed', timestamp: 'Feb 20, 2026' },
-    { label: 'Shipped', status: 'active', timestamp: 'Feb 22, 2026' },
-    { label: 'Delivered', status: 'pending' }
-  ];
+Listen for `step-click` to handle step interactions.
 
-  tracker.addEventListener('step-click', (e) => {
-    const { step, index } = e.detail;
-    console.log(`Clicked step ${index}: ${step.label} (${step.status})`);
-  });
-</script>
+```typescript
+tracker.addEventListener('step-click', (e) => {
+  const { step, index } = e.detail;
+  console.log(`Clicked step ${index}: ${step.label} (${step.status})`);
+});
 ```
 
 ## Accessibility
 
-- **Semantic structure**: Steps are rendered as a list with `role="list"` and `role="listitem"`
-- **Keyboard navigation**: Each step is focusable and activatable with Enter or Space
-- **Visual indicators**: Completed steps show a checkmark, active steps are highlighted with a ring, pending steps show their number
-- **Status communication**: Step status is conveyed through color and iconography, not color alone
+- Steps are rendered as a list with `role="list"` and `role="listitem"`
+- Each step is focusable with `tabindex="0"` and activatable with Enter or Space
+- Completed steps show a checkmark icon
+- Active steps are highlighted with a ring indicator
+- Status is conveyed through color and iconography
+
+## Data Types
+
+```typescript
+type OrderStepStatus = 'pending' | 'active' | 'completed';
+
+interface OrderStep {
+  label: string;                    // Step label text
+  status: OrderStepStatus;         // Current step status
+  timestamp?: string;              // Display timestamp
+  description?: string;            // Additional description text
+  icon?: string;                   // Custom icon
+}
+```

package/docs/components/org-chart.md

@@ -1,57 +1,42 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/org-chart.md instead -->
-
-# Org Chart Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/org-chart.md -->
 
+# Org Chart
 `<snice-org-chart>`
 
-A hierarchical organizational chart that renders tree-structured data with node cards, connecting lines, avatars, and expand/collapse functionality. Supports both top-down and left-right layout directions.
+A hierarchical organizational chart with expand/collapse functionality, avatars, and two layout directions.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Types](#types)
 - [Accessibility](#accessibility)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/org-chart/snice-org-chart';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-org-chart.min.js"></script>
-```
+- [Data Types](#data-types)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `data` | `OrgChartNode \| null` | `null` | Root node of the organizational tree (set via JavaScript) |
-| `direction` | `'top-down' \| 'left-right'` | `'top-down'` | Layout direction for the chart |
-| `compact` | `boolean` | `false` | Use compact node display with smaller cards |
+| `data` | `OrgChartNode \| null` | `null` | Root node of the tree (set via JS) |
+| `direction` | `'top-down' \| 'left-right'` | `'top-down'` | Layout direction |
+| `compact` | `boolean` | `false` | Compact node display |
 
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `collapseNode()` | `id: string` | Collapse a specific node, hiding its children |
-| `expandNode()` | `id: string` | Expand a specific node, showing its children |
-| `expandAll()` | -- | Expand all nodes in the chart |
-| `collapseAll()` | -- | Collapse all nodes in the chart |
+| `collapseNode()` | `id: string` | Collapse a specific node by ID |
+| `expandNode()` | `id: string` | Expand a specific node by ID |
+| `expandAll()` | -- | Expand all nodes in the tree |
+| `collapseAll()` | -- | Collapse all nodes in the tree |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `node-click` | `{ node: OrgChartNode }` | Fired when a node card is clicked |
+| `node-click` | `{ node: OrgChartNode }` | Fired when a node is clicked |
 | `node-expand` | `{ node: OrgChartNode }` | Fired when a node is expanded |
 | `node-collapse` | `{ node: OrgChartNode }` | Fired when a node is collapsed |
 
@@ -62,15 +47,10 @@ Style internal elements from outside the shadow DOM using `::part()`.
 | Part | Element | Description |
 |------|---------|-------------|
 | `base` | `<div>` | The outer chart container |
-| `tree` | `<div>` | The tree layout wrapper with connecting lines |
-| `node` | `<div>` | Individual node cards (repeated for each node) |
+| `tree` | `<div>` | The tree layout wrapper |
+| `node` | `<div>` | Individual node cards |
 
 ```css
-snice-org-chart::part(base) {
-  padding: 2rem;
-  overflow: auto;
-}
-
 snice-org-chart::part(node) {
   border-radius: 12px;
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
@@ -84,216 +64,87 @@ import 'snice/components/org-chart/snice-org-chart';
 ```
 
 ```html
-<snice-org-chart direction="top-down"></snice-org-chart>
-```
-
-## Examples
-
-### Basic Org Chart
-
-Provide a tree data structure to render a top-down organizational chart.
-
-```html
-<snice-org-chart id="org" direction="top-down"></snice-org-chart>
+<snice-org-chart id="chart" direction="top-down"></snice-org-chart>
 
 <script type="module">
-  import 'snice/components/org-chart/snice-org-chart';
-
-  const chart = document.getElementById('org');
+  const chart = document.getElementById('chart');
   chart.data = {
     id: 'ceo',
     name: 'Jane Smith',
     title: 'CEO',
     avatar: '/avatars/jane.jpg',
     children: [
-      {
-        id: 'cto',
-        name: 'Bob Jones',
-        title: 'CTO',
-        children: [
-          { id: 'dev1', name: 'Alice Chen', title: 'Senior Engineer' },
-          { id: 'dev2', name: 'David Park', title: 'Engineer' }
-        ]
-      },
-      {
-        id: 'cfo',
-        name: 'Carol White',
-        title: 'CFO',
-        children: [
-          { id: 'acc1', name: 'Eve Brown', title: 'Accountant' }
-        ]
-      }
+      { id: 'cto', name: 'Bob Jones', title: 'CTO', children: [
+        { id: 'dev1', name: 'Alice Chen', title: 'Senior Engineer' },
+        { id: 'dev2', name: 'David Park', title: 'Engineer' }
+      ]},
+      { id: 'cfo', name: 'Carol White', title: 'CFO' }
     ]
   };
 </script>
 ```
 
-### Left-to-Right Layout
-
-Use `direction="left-right"` for a horizontal chart layout.
-
-```html
-<snice-org-chart id="horizontal-org" direction="left-right"></snice-org-chart>
-
-<script type="module">
-  import 'snice/components/org-chart/snice-org-chart';
-
-  const chart = document.getElementById('horizontal-org');
-  chart.data = {
-    id: 'root',
-    name: 'Engineering',
-    title: 'Department',
-    children: [
-      {
-        id: 'frontend',
-        name: 'Frontend Team',
-        title: 'Team Lead: Maria',
-        children: [
-          { id: 'fe1', name: 'Tom', title: 'React Developer' },
-          { id: 'fe2', name: 'Lisa', title: 'UI Engineer' }
-        ]
-      },
-      {
-        id: 'backend',
-        name: 'Backend Team',
-        title: 'Team Lead: James',
-        children: [
-          { id: 'be1', name: 'Sam', title: 'API Engineer' },
-          { id: 'be2', name: 'Nina', title: 'Database Admin' }
-        ]
-      }
-    ]
-  };
-</script>
-```
+## Examples
 
-### Compact Mode
+### Left-Right Layout
 
-Set the `compact` attribute for smaller node cards, useful for large organizations.
+Use `direction="left-right"` for a horizontal tree layout.
 
 ```html
-<snice-org-chart id="compact-org" compact></snice-org-chart>
-
-<script type="module">
-  import 'snice/components/org-chart/snice-org-chart';
-
-  const chart = document.getElementById('compact-org');
-  chart.data = {
-    id: 'ceo',
-    name: 'Jane Smith',
-    title: 'CEO',
-    children: [
-      { id: 'vp1', name: 'VP Engineering', title: 'VP' },
-      { id: 'vp2', name: 'VP Sales', title: 'VP' },
-      { id: 'vp3', name: 'VP Marketing', title: 'VP' },
-      { id: 'vp4', name: 'VP Operations', title: 'VP' }
-    ]
-  };
-</script>
+<snice-org-chart direction="left-right"></snice-org-chart>
 ```
 
-### Interactive Node Selection
+### Compact Mode
 
-Listen for `node-click` events to display details or navigate when a node is selected.
+Use the `compact` attribute for smaller node cards.
 
 ```html
-<snice-org-chart id="interactive-org"></snice-org-chart>
-<div id="selected-info" style="margin-top: 1rem;"></div>
-
-<script type="module">
-  import 'snice/components/org-chart/snice-org-chart';
-
-  const chart = document.getElementById('interactive-org');
-  const info = document.getElementById('selected-info');
-
-  chart.data = {
-    id: 'ceo',
-    name: 'Jane Smith',
-    title: 'CEO',
-    avatar: '/avatars/jane.jpg',
-    children: [
-      { id: 'cto', name: 'Bob Jones', title: 'CTO', avatar: '/avatars/bob.jpg' },
-      { id: 'cfo', name: 'Carol White', title: 'CFO', avatar: '/avatars/carol.jpg' }
-    ]
-  };
-
-  chart.addEventListener('node-click', (e) => {
-    const node = e.detail.node;
-    info.textContent = `Selected: ${node.name} (${node.title || 'No title'})`;
-  });
-</script>
+<snice-org-chart compact></snice-org-chart>
 ```
 
 ### Programmatic Expand/Collapse
 
-Use methods to control which branches of the tree are visible.
+Use methods to control the tree programmatically.
 
-```html
-<snice-org-chart id="controlled-org"></snice-org-chart>
-<button id="expand-all">Expand All</button>
-<button id="collapse-all">Collapse All</button>
-
-<script type="module">
-  import 'snice/components/org-chart/snice-org-chart';
-
-  const chart = document.getElementById('controlled-org');
-  chart.data = {
-    id: 'root',
-    name: 'Company',
-    title: 'Organization',
-    children: [
-      {
-        id: 'dept1',
-        name: 'Engineering',
-        title: 'Department',
-        children: [
-          { id: 'team1', name: 'Frontend', title: 'Team' },
-          { id: 'team2', name: 'Backend', title: 'Team' }
-        ]
-      },
-      {
-        id: 'dept2',
-        name: 'Marketing',
-        title: 'Department',
-        children: [
-          { id: 'team3', name: 'Content', title: 'Team' },
-          { id: 'team4', name: 'Growth', title: 'Team' }
-        ]
-      }
-    ]
-  };
-
-  document.getElementById('expand-all').addEventListener('click', () => chart.expandAll());
-  document.getElementById('collapse-all').addEventListener('click', () => chart.collapseAll());
+```typescript
+chart.collapseAll();
+chart.expandNode('cto');
 
-  chart.addEventListener('node-expand', (e) => {
-    console.log('Expanded:', e.detail.node.name);
-  });
+chart.addEventListener('node-expand', (e) => {
+  console.log('Expanded:', e.detail.node.name);
+});
 
-  chart.addEventListener('node-collapse', (e) => {
-    console.log('Collapsed:', e.detail.node.name);
-  });
-</script>
+chart.addEventListener('node-collapse', (e) => {
+  console.log('Collapsed:', e.detail.node.name);
+});
 ```
 
-## Types
+### Interactive Node Selection
 
-### OrgChartNode
+Listen for `node-click` events to display details or navigate.
 
 ```typescript
-interface OrgChartNode {
-  id: string;                    // Unique identifier for the node
-  name: string;                  // Person's name displayed on the card
-  title?: string;                // Job title or role
-  avatar?: string;               // Avatar image URL
-  children?: OrgChartNode[];     // Child nodes in the hierarchy
-}
+chart.addEventListener('node-click', (e) => {
+  const node = e.detail.node;
+  console.log(`Selected: ${node.name} (${node.title || 'No title'})`);
+});
 ```
 
 ## Accessibility
 
 - Node cards are interactive and clickable
-- Expand/collapse controls are accessible for toggling subtree visibility
-- The chart uses connecting lines to visually represent the hierarchy
+- Expand/collapse toggle buttons are accessible
+- Avatar placeholders display name initials when no image is provided
 - Nodes display name, title, and optional avatar for clear identification
-- Keyboard users can interact with node cards to trigger click events
+
+## Data Types
+
+```typescript
+interface OrgChartNode {
+  id: string;                      // Unique identifier
+  name: string;                    // Person's name
+  title?: string;                  // Job title or role
+  avatar?: string;                 // Avatar image URL
+  children?: OrgChartNode[];       // Child nodes
+}
+```