snice 4.8.0 → 4.10.0

package/docs/components/spinner.md

@@ -1,26 +1,39 @@
-# Spinner Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/spinner.md instead)
 
-The `<snice-spinner>` component provides an animated loading indicator.
+# Spinner
+`<snice-spinner>`
+
+An animated loading indicator.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/spinner/snice-spinner';
+```
+
 ```html
 <snice-spinner></snice-spinner>
 ```
 
-## Properties
+## Importing
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `size` | `'small' \| 'medium' \| 'large' \| 'xl'` | `'medium'` | Spinner size |
-| `color` | `'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Color variant |
-| `label` | `string` | `''` | Accessible label |
-| `thickness` | `number` | `4` | Stroke thickness |
+**ESM (bundler)**
+```typescript
+import 'snice/components/spinner/snice-spinner';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-spinner.min.js"></script>
+```
 
 ## Examples
 
 ### Sizes
 
+Use the `size` attribute to change the spinner's size.
+
 ```html
 <snice-spinner size="small"></snice-spinner>
 <snice-spinner size="medium"></snice-spinner>
@@ -30,6 +43,8 @@ The `<snice-spinner>` component provides an animated loading indicator.
 
 ### Colors
 
+Use the `color` attribute to change the spinner's color.
+
 ```html
 <snice-spinner color="primary"></snice-spinner>
 <snice-spinner color="success"></snice-spinner>
@@ -40,20 +55,15 @@ The `<snice-spinner>` component provides an animated loading indicator.
 
 ### With Label
 
+Set the `label` attribute for an accessible description.
+
 ```html
 <snice-spinner label="Loading data..."></snice-spinner>
 ```
 
-### Loading State
+### Inline
 
-```html
-<div style="text-align: center; padding: 2rem;">
-  <snice-spinner size="large" color="primary"></snice-spinner>
-  <p>Loading content...</p>
-</div>
-```
-
-### Inline Spinner
+Use a small spinner inline with text.
 
 ```html
 <button disabled>
@@ -61,3 +71,12 @@ The `<snice-spinner>` component provides an animated loading indicator.
   Processing...
 </button>
 ```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'medium' \| 'large' \| 'xl'` | `'medium'` | Spinner size |
+| `color` | `'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'primary'` | Color variant |
+| `label` | `string` | `''` | Accessible label |
+| `thickness` | `number` | `4` | Stroke thickness |

package/docs/components/split-pane.md

@@ -1,9 +1,16 @@
-# Split Pane Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/split-pane.md instead)
 
-Resizable split pane layout with horizontal or vertical orientation.
+# Split Pane
+`<snice-split-pane>`
+
+A resizable split pane layout with horizontal or vertical orientation.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/split-pane/snice-split-pane';
+```
+
 ```html
 <snice-split-pane style="height: 400px;">
   <div slot="primary">Left pane content</div>
@@ -11,74 +18,25 @@ Resizable split pane layout with horizontal or vertical orientation.
 </snice-split-pane>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Split direction |
-| `primarySize` | `number` | `50` | Primary pane size (%) |
-| `minPrimarySize` | `number` | `10` | Min primary size (%) |
-| `minSecondarySize` | `number` | `10` | Min secondary size (%) |
-| `snapSize` | `number` | `0` | Snap interval (%, 0 = none) |
-| `disabled` | `boolean` | `false` | Disable resizing |
-
-## Methods
-
-### `getPrimarySize(): number`
-Get current primary pane size percentage.
-
-```javascript
-const size = splitPane.getPrimarySize(); // 50
-```
-
-### `getSecondarySize(): number`
-Get current secondary pane size percentage.
+## Importing
 
-```javascript
-const size = splitPane.getSecondarySize(); // 50
+**ESM (bundler)**
+```typescript
+import 'snice/components/split-pane/snice-split-pane';
 ```
 
-### `setPrimarySize(size: number): void`
-Set primary pane size (respects min sizes).
-
-```javascript
-splitPane.setPrimarySize(30); // Set to 30%
-```
-
-### `reset(): void`
-Reset to 50/50 split.
-
-```javascript
-splitPane.reset();
-```
-
-## Events
-
-### `pane-resize`
-Dispatched when pane is resized.
-
-```javascript
-splitPane.addEventListener('pane-resize', (e) => {
-  console.log('Primary:', e.detail.primarySize);
-  console.log('Secondary:', e.detail.secondarySize);
-});
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-split-pane.min.js"></script>
 ```
 
-**Detail:** `{ primarySize: number, secondarySize: number, splitPane: SniceResizeElement }`
-
 ## Examples
 
-### Horizontal Split
-
-```html
-<snice-split-pane style="height: 400px;">
-  <div slot="primary">Left pane</div>
-  <div slot="secondary">Right pane</div>
-</snice-split-pane>
-```
-
 ### Vertical Split
 
+Use the `direction` attribute to split vertically (top/bottom).
+
 ```html
 <snice-split-pane direction="vertical" style="height: 400px;">
   <div slot="primary">Top pane</div>
@@ -88,6 +46,8 @@ splitPane.addEventListener('pane-resize', (e) => {
 
 ### Custom Initial Size
 
+Use the `primary-size` attribute to set the initial split ratio.
+
 ```html
 <snice-split-pane primary-size="30" style="height: 400px;">
   <div slot="primary">30% width</div>
@@ -95,30 +55,32 @@ splitPane.addEventListener('pane-resize', (e) => {
 </snice-split-pane>
 ```
 
-### With Minimum Sizes
+### Minimum Sizes
+
+Use `min-primary-size` and `min-secondary-size` to constrain pane sizing.
 
 ```html
-<snice-split-pane
-  min-primary-size="20"
-  min-secondary-size="30"
-  style="height: 400px;">
+<snice-split-pane min-primary-size="20" min-secondary-size="30" style="height: 400px;">
   <div slot="primary">Min 20%</div>
   <div slot="secondary">Min 30%</div>
 </snice-split-pane>
 ```
 
-### With Snap
+### Snap
+
+Use the `snap-size` attribute to snap the divider to fixed increments.
 
 ```html
-<!-- Snaps to 10% increments -->
 <snice-split-pane snap-size="10" style="height: 400px;">
-  <div slot="primary">Snaps to 10, 20, 30...</div>
+  <div slot="primary">Snaps to 10% increments</div>
   <div slot="secondary">Right pane</div>
 </snice-split-pane>
 ```
 
 ### Disabled
 
+Set the `disabled` attribute to prevent resizing.
+
 ```html
 <snice-split-pane disabled primary-size="40" style="height: 400px;">
   <div slot="primary">Fixed 40%</div>
@@ -126,35 +88,6 @@ splitPane.addEventListener('pane-resize', (e) => {
 </snice-split-pane>
 ```
 
-### Programmatic Control
-
-```html
-<button id="set-30">30%</button>
-<button id="set-70">70%</button>
-<button id="reset">Reset</button>
-
-<snice-split-pane id="my-split" style="height: 400px;">
-  <div slot="primary">Primary</div>
-  <div slot="secondary">Secondary</div>
-</snice-split-pane>
-
-<script>
-  const split = document.getElementById('my-split');
-
-  document.getElementById('set-30').addEventListener('click', () => {
-    split.setPrimarySize(30);
-  });
-
-  document.getElementById('set-70').addEventListener('click', () => {
-    split.setPrimarySize(70);
-  });
-
-  document.getElementById('reset').addEventListener('click', () => {
-    split.reset();
-  });
-</script>
-```
-
 ### Nested Split Panes
 
 ```html
@@ -169,147 +102,50 @@ splitPane.addEventListener('pane-resize', (e) => {
 </snice-split-pane>
 ```
 
-### File Explorer Layout
-
-```html
-<snice-split-pane primary-size="25" style="height: 600px;">
-  <!-- Sidebar -->
-  <div slot="primary" style="padding: 10px; background: #f5f5f5;">
-    <h3>Files</h3>
-    <ul>
-      <li>index.html</li>
-      <li>styles.css</li>
-      <li>script.js</li>
-    </ul>
-  </div>
-
-  <!-- Main content -->
-  <div slot="secondary" style="padding: 20px;">
-    <h2>Content Area</h2>
-    <p>Main content goes here...</p>
-  </div>
-</snice-split-pane>
-```
-
-### Code Editor Layout
-
-```html
-<snice-split-pane primary-size="20" style="height: 600px;">
-  <!-- File tree -->
-  <div slot="primary" style="background: #1e1e1e; color: #d4d4d4; padding: 10px;">
-    <div>📁 src</div>
-    <div style="margin-left: 15px;">📄 main.ts</div>
-  </div>
-
-  <!-- Editor + Console -->
-  <div slot="secondary" style="height: 100%;">
-    <snice-split-pane direction="vertical" primary-size="70">
-      <!-- Editor -->
-      <div slot="primary" style="background: #1e1e1e; color: #d4d4d4; padding: 10px; font-family: monospace;">
-        <code>console.log('Hello');</code>
-      </div>
-
-      <!-- Console -->
-      <div slot="secondary" style="background: #252526; color: #d4d4d4; padding: 10px; font-family: monospace;">
-        $ npm start
-      </div>
-    </snice-split-pane>
-  </div>
-</snice-split-pane>
-```
-
-### Dashboard Layout
-
-```html
-<snice-split-pane direction="vertical" primary-size="60" style="height: 600px;">
-  <!-- Charts -->
-  <div slot="primary">
-    <snice-split-pane>
-      <div slot="primary">Chart 1</div>
-      <div slot="secondary">Chart 2</div>
-    </snice-split-pane>
-  </div>
-
-  <!-- Table -->
-  <div slot="secondary" style="padding: 20px;">
-    <table style="width: 100%;">
-      <tr><th>Name</th><th>Value</th></tr>
-      <tr><td>Item 1</td><td>100</td></tr>
-    </table>
-  </div>
-</snice-split-pane>
-```
-
-### Email Client Layout
-
-```html
-<snice-split-pane primary-size="30" style="height: 600px;">
-  <!-- Email list -->
-  <div slot="primary" style="background: #f5f5f5; padding: 10px; overflow: auto;">
-    <div style="padding: 10px; background: white; margin-bottom: 5px; border-radius: 4px;">
-      <strong>Meeting Today</strong>
-      <div style="font-size: 12px; color: #666;">John Doe</div>
-    </div>
-    <div style="padding: 10px; background: white; margin-bottom: 5px; border-radius: 4px;">
-      <strong>Project Update</strong>
-      <div style="font-size: 12px; color: #666;">Jane Smith</div>
-    </div>
-  </div>
-
-  <!-- Email content -->
-  <div slot="secondary" style="padding: 20px; overflow: auto;">
-    <h2>Meeting Today</h2>
-    <div style="color: #666; margin-bottom: 10px;">From: John Doe</div>
-    <p>Let's meet at 2pm to discuss the project...</p>
-  </div>
-</snice-split-pane>
-```
-
-### Responsive Sizes
+### Programmatic Control
 
 ```html
-<snice-split-pane id="responsive-split" style="height: 400px;">
+<snice-split-pane id="my-split" style="height: 400px;">
   <div slot="primary">Primary</div>
   <div slot="secondary">Secondary</div>
 </snice-split-pane>
 
 <script>
-  const split = document.getElementById('responsive-split');
-
-  function updateSize() {
-    if (window.innerWidth < 768) {
-      split.setPrimarySize(100); // Stack on mobile
-    } else {
-      split.setPrimarySize(50); // Side by side on desktop
-    }
-  }
-
-  window.addEventListener('resize', updateSize);
-  updateSize();
+  const split = document.getElementById('my-split');
+  split.setPrimarySize(30);   // Set to 30%
+  split.reset();              // Reset to 50/50
 </script>
 ```
 
-## Styling
+## Slots
 
-The component exposes CSS custom properties for theming:
+| Name | Description |
+|------|-------------|
+| `primary` | Primary pane content (left or top) |
+| `secondary` | Secondary pane content (right or bottom) |
 
-```css
-snice-split-pane {
-  --snice-border-color: #e0e0e0;
-  --snice-color-primary: #2196f3;
-  --snice-bg-secondary: #f5f5f5;
-}
-```
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Split direction |
+| `primarySize` (attr: `primary-size`) | `number` | `50` | Primary pane size (%) |
+| `minPrimarySize` (attr: `min-primary-size`) | `number` | `10` | Min primary size (%) |
+| `minSecondarySize` (attr: `min-secondary-size`) | `number` | `10` | Min secondary size (%) |
+| `snapSize` (attr: `snap-size`) | `number` | `0` | Snap interval (%, 0 = none) |
+| `disabled` | `boolean` | `false` | Disable resizing |
 
-## Accessibility
+## Events
 
-- Drag handle is keyboard accessible
-- Mouse and touch support for resizing
-- Respects minimum sizes for usability
-- Visual feedback on hover and drag
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `pane-resize` | `{ primarySize: number, secondarySize: number, splitPane: SniceResizeElement }` | Fired when pane is resized |
 
-## Browser Support
+## Methods
 
-- Modern browsers with Custom Elements v1 support
-- Mouse event handling for drag
-- Percentage-based sizing for responsiveness
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `getPrimarySize()` | -- | Get primary pane size (%), returns `number` |
+| `getSecondarySize()` | -- | Get secondary pane size (%), returns `number` |
+| `setPrimarySize()` | `size: number` | Set primary pane size (respects min sizes) |
+| `reset()` | -- | Reset to 50/50 split |

package/docs/components/spotlight.md

@@ -0,0 +1,240 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/spotlight.md instead)
+
+# Spotlight Component
+
+The spotlight component provides a guided tour and onboarding experience by highlighting elements on the page with a cutout overlay and step-by-step popover instructions. It supports step navigation, customizable positioning, and smooth transitions between steps.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-spotlight></snice-spotlight>
+```
+
+```typescript
+import 'snice/components/spotlight/snice-spotlight';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `steps` | `SpotlightStep[]` | `[]` | Array of step definitions for the tour |
+
+### SpotlightStep
+
+```typescript
+interface SpotlightStep {
+  target: string;              // CSS selector for the element to highlight
+  title: string;               // Step title displayed in the popover
+  description: string;         // Step description text
+  position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';  // Popover position relative to target
+}
+```
+
+## Methods
+
+#### `start(): void`
+Begin the spotlight tour from step 0.
+
+```typescript
+spotlight.start();
+```
+
+#### `next(): void`
+Advance to the next step. Ends the tour if on the last step.
+
+```typescript
+spotlight.next();
+```
+
+#### `prev(): void`
+Go back to the previous step.
+
+```typescript
+spotlight.prev();
+```
+
+#### `goToStep(index: number): void`
+Jump to a specific step by index.
+
+```typescript
+spotlight.goToStep(2);
+```
+
+#### `end(): void`
+End the tour immediately.
+
+```typescript
+spotlight.end();
+```
+
+## Events
+
+### `spotlight-start`
+Fired when the tour begins.
+
+**Event Detail:** `void`
+
+### `spotlight-step`
+Fired when navigating to a new step.
+
+**Event Detail:**
+```typescript
+{
+  index: number;
+  step: SpotlightStep;
+}
+```
+
+### `spotlight-end`
+Fired when the tour ends (either completed or ended programmatically).
+
+**Event Detail:** `void`
+
+### `spotlight-skip`
+Fired when the user skips the tour.
+
+**Event Detail:**
+```typescript
+{
+  index: number;  // The step index where the tour was skipped
+}
+```
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--snice-transition-medium` | Cutout transition speed | `250ms` |
+| `--snice-color-background` | Popover background color | `rgb(255 255 255)` |
+| `--snice-color-border` | Popover border color | `rgb(226 226 226)` |
+| `--snice-color-text` | Popover text color | `rgb(23 23 23)` |
+| `--snice-color-primary` | Primary button color | `rgb(37 99 235)` |
+| `--snice-shadow-lg` | Popover box shadow | _(theme default)_ |
+| `--snice-border-radius-lg` | Popover border radius | `0.5rem` |
+
+## Examples
+
+### Basic Tour
+
+Set up a simple guided tour with three steps targeting elements on the page.
+
+```html
+<div id="search-bar">Search...</div>
+<div id="nav-menu">Navigation</div>
+<div id="profile-icon">Profile</div>
+
+<snice-spotlight id="tour"></snice-spotlight>
+
+<script type="module">
+  import 'snice/components/spotlight/snice-spotlight';
+
+  const spotlight = document.getElementById('tour');
+  spotlight.steps = [
+    { target: '#search-bar', title: 'Search', description: 'Use the search bar to find content.', position: 'bottom' },
+    { target: '#nav-menu', title: 'Navigation', description: 'Browse sections from the navigation menu.', position: 'right' },
+    { target: '#profile-icon', title: 'Profile', description: 'View and edit your profile settings here.', position: 'left' }
+  ];
+  spotlight.start();
+</script>
+```
+
+### Listening for Tour Events
+
+React to tour lifecycle events to track progress or trigger side effects.
+
+```html
+<snice-spotlight id="onboarding"></snice-spotlight>
+
+<script type="module">
+  import type { SniceSpotlightElement } from 'snice/components/spotlight/snice-spotlight.types';
+
+  const spotlight = document.getElementById('onboarding') as SniceSpotlightElement;
+
+  spotlight.steps = [
+    { target: '#feature-a', title: 'Feature A', description: 'This is feature A.' },
+    { target: '#feature-b', title: 'Feature B', description: 'This is feature B.' },
+    { target: '#feature-c', title: 'Feature C', description: 'This is feature C.' }
+  ];
+
+  spotlight.addEventListener('spotlight-step', (e) => {
+    console.log(`Now on step ${e.detail.index}: ${e.detail.step.title}`);
+  });
+
+  spotlight.addEventListener('spotlight-end', () => {
+    console.log('Tour completed');
+    localStorage.setItem('onboarding-done', 'true');
+  });
+
+  spotlight.addEventListener('spotlight-skip', (e) => {
+    console.log(`Tour skipped at step ${e.detail.index}`);
+  });
+
+  // Only show tour for new users
+  if (!localStorage.getItem('onboarding-done')) {
+    spotlight.start();
+  }
+</script>
+```
+
+### Auto-Positioned Steps
+
+Use `position: 'auto'` or omit the position to let the component automatically determine the best popover placement.
+
+```html
+<snice-spotlight id="auto-tour"></snice-spotlight>
+
+<script type="module">
+  const spotlight = document.getElementById('auto-tour');
+  spotlight.steps = [
+    { target: '.sidebar', title: 'Sidebar', description: 'Access tools and settings here.' },
+    { target: '.main-content', title: 'Content Area', description: 'Your main workspace.', position: 'auto' },
+    { target: '.footer-help', title: 'Help', description: 'Need assistance? Click here.', position: 'top' }
+  ];
+  spotlight.start();
+</script>
+```
+
+### Programmatic Step Navigation
+
+Control the tour programmatically using methods, useful for custom navigation UI.
+
+```html
+<snice-spotlight id="controlled-tour"></snice-spotlight>
+
+<button onclick="document.getElementById('controlled-tour').prev()">Previous</button>
+<button onclick="document.getElementById('controlled-tour').next()">Next</button>
+<button onclick="document.getElementById('controlled-tour').goToStep(0)">Restart</button>
+<button onclick="document.getElementById('controlled-tour').end()">End Tour</button>
+```
+
+## Accessibility
+
+- **Keyboard support**: The popover navigation buttons (Next, Previous, Skip) are fully keyboard accessible
+- **Focus management**: Focus is moved to the popover when each step is shown
+- **ARIA attributes**: The overlay and popover use appropriate ARIA roles for screen reader support
+- **Escape key**: Pressing Escape ends the tour
+- **Reduced motion**: Transitions respect `prefers-reduced-motion` for users sensitive to animations
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Keep tours short**: Limit to 3-5 steps to avoid user fatigue
+2. **Write clear descriptions**: Each step should explain what the user can do, not just what the element is
+3. **Target visible elements**: Ensure target elements are visible and in the viewport before starting the tour
+4. **Persist completion state**: Use `localStorage` or a backend flag to avoid showing the tour to returning users
+5. **Provide a skip option**: Always let users skip the tour if they prefer
+6. **Use appropriate positions**: Choose positions that don't obscure important UI elements