snice 4.28.0 → 4.29.0

package/docs/components/split-pane.md

@@ -1,22 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/split-pane.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/split-pane.md -->
 
 # Split Pane
-`<snice-split-pane>`
 
-A resizable split pane layout with horizontal or vertical orientation.
+A resizable split layout with a draggable divider. Supports horizontal (left/right) and vertical (top/bottom) orientations with configurable size constraints.
 
-## Importing
+## Table of Contents
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/split-pane/snice-split-pane';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-split-pane.min.js"></script>
-```
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -24,25 +21,25 @@ import 'snice/components/split-pane/snice-split-pane';
 |----------|------|---------|-------------|
 | `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) |
+| `minPrimarySize` (attr: `min-primary-size`) | `number` | `10` | Minimum primary pane size (%) |
+| `minSecondarySize` (attr: `min-secondary-size`) | `number` | `10` | Minimum secondary pane size (%) |
+| `snapSize` (attr: `snap-size`) | `number` | `0` | Snap interval (%, 0 = no snapping) |
 | `disabled` | `boolean` | `false` | Disable resizing |
 
 ## Methods
 
-| 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 |
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `getPrimarySize()` | -- | `number` | Get current primary pane size (%) |
+| `getSecondarySize()` | -- | `number` | Get current secondary pane size (%) |
+| `setPrimarySize()` | `size: number` | `void` | Set primary pane size (respects min sizes) |
+| `reset()` | -- | `void` | Reset to 50/50 split |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `pane-resize` | `{ primarySize: number, secondarySize: number, splitPane: SniceResizeElement }` | Fired when pane is resized |
+| `pane-resize` | `{ primarySize: number, secondarySize: number, splitPane: SniceSplitPaneElement }` | Fired when the pane is resized |
 
 ## Slots
 
@@ -53,25 +50,12 @@ import 'snice/components/split-pane/snice-split-pane';
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `primary` | `<div>` | The primary pane container |
-| `divider` | `<div>` | The draggable divider bar |
-| `handle` | `<div>` | The visual handle inside the divider |
-| `secondary` | `<div>` | The secondary pane container |
-
-```css
-snice-split-pane::part(divider) {
-  background: #e2e8f0;
-}
-
-snice-split-pane::part(handle) {
-  background: #94a3b8;
-  border-radius: 4px;
-}
-```
+| Part | Description |
+|------|-------------|
+| `primary` | The primary pane container |
+| `divider` | The draggable divider bar |
+| `handle` | The visual handle inside the divider |
+| `secondary` | The secondary pane container |
 
 ## Basic Usage
 
@@ -90,7 +74,7 @@ import 'snice/components/split-pane/snice-split-pane';
 
 ### Vertical Split
 
-Use the `direction` attribute to split vertically (top/bottom).
+Use `direction="vertical"` for a top/bottom layout.
 
 ```html
 <snice-split-pane direction="vertical" style="height: 400px;">
@@ -101,7 +85,7 @@ Use the `direction` attribute to split vertically (top/bottom).
 
 ### Custom Initial Size
 
-Use the `primary-size` attribute to set the initial split ratio.
+Use `primary-size` to set the initial split ratio.
 
 ```html
 <snice-split-pane primary-size="30" style="height: 400px;">
@@ -123,7 +107,7 @@ Use `min-primary-size` and `min-secondary-size` to constrain pane sizing.
 
 ### Snap
 
-Use the `snap-size` attribute to snap the divider to fixed increments.
+Use `snap-size` to snap the divider to fixed percentage increments.
 
 ```html
 <snice-split-pane snap-size="10" style="height: 400px;">
@@ -134,7 +118,7 @@ Use the `snap-size` attribute to snap the divider to fixed increments.
 
 ### Disabled
 
-Set the `disabled` attribute to prevent resizing.
+Set `disabled` to prevent resizing.
 
 ```html
 <snice-split-pane disabled primary-size="40" style="height: 400px;">
@@ -159,15 +143,14 @@ Set the `disabled` attribute to prevent resizing.
 
 ### Programmatic Control
 
-```html
-<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');
-  split.setPrimarySize(30);   // Set to 30%
-  split.reset();              // Reset to 50/50
-</script>
+```typescript
+const split = document.querySelector('snice-split-pane');
+split.setPrimarySize(30);   // Set to 30%
+console.log(split.getPrimarySize());  // 30
+split.reset();              // Reset to 50/50
 ```
+
+## Accessibility
+
+- Divider is keyboard-accessible with arrow keys for resizing
+- Mouse, touch, and keyboard input supported

package/docs/components/spotlight.md

@@ -1,10 +1,11 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/spotlight.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/spotlight.md -->
 
-# Spotlight Component
+# Spotlight
 
-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.
+A guided tour and onboarding component that highlights elements on the page with a cutout overlay and step-by-step popover instructions. Supports customizable positioning and smooth transitions between steps.
 
 ## Table of Contents
+
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
@@ -12,7 +13,6 @@ The spotlight component provides a guided tour and onboarding experience by high
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
@@ -27,79 +27,28 @@ 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
+  position?: 'top' | 'bottom' | 'left' | 'right' | 'auto';  // Popover position
 }
 ```
 
 ## 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();
-```
+| Method | Arguments | Returns | Description |
+|--------|-----------|---------|-------------|
+| `start()` | -- | `void` | Begin the tour from step 0 |
+| `next()` | -- | `void` | Advance to the next step (ends tour if on last step) |
+| `prev()` | -- | `void` | Go back to the previous step |
+| `goToStep()` | `index: number` | `void` | Jump to a specific step by index |
+| `end()` | -- | `void` | End the tour immediately |
 
 ## 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
-}
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `spotlight-start` | `void` | Tour has begun |
+| `spotlight-step` | `{ index: number, step: SpotlightStep }` | Navigated to a new step |
+| `spotlight-end` | `void` | Tour ended (completed or ended programmatically) |
+| `spotlight-skip` | `{ index: number }` | User skipped the tour at the given step |
 
 ## CSS Custom Properties
 
@@ -115,99 +64,63 @@ Fired when the user skips the tour.
 
 ## Basic Usage
 
-```html
-<snice-spotlight></snice-spotlight>
-```
-
 ```typescript
 import 'snice/components/spotlight/snice-spotlight';
 ```
 
-## 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';
-
+<script>
   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' }
+    { target: '#search-bar', title: 'Search', description: 'Find content here.', position: 'bottom' },
+    { target: '#nav-menu', title: 'Navigation', description: 'Browse sections.', position: 'right' },
+    { target: '#profile', title: 'Profile', description: 'Your settings.', 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;
+## Examples
 
-  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.' }
-  ];
+### Auto-Positioned Steps
 
-  spotlight.addEventListener('spotlight-step', (e) => {
-    console.log(`Now on step ${e.detail.index}: ${e.detail.step.title}`);
-  });
+Omit `position` or set it to `'auto'` for automatic popover placement.
 
-  spotlight.addEventListener('spotlight-end', () => {
-    console.log('Tour completed');
-    localStorage.setItem('onboarding-done', 'true');
-  });
+```typescript
+spotlight.steps = [
+  { target: '.sidebar', title: 'Sidebar', description: 'Access tools here.' },
+  { target: '.main', title: 'Content', description: 'Your workspace.', position: 'auto' },
+];
+spotlight.start();
+```
 
-  spotlight.addEventListener('spotlight-skip', (e) => {
-    console.log(`Tour skipped at step ${e.detail.index}`);
-  });
+### Event Handling
 
-  // Only show tour for new users
-  if (!localStorage.getItem('onboarding-done')) {
-    spotlight.start();
-  }
-</script>
-```
+Track tour lifecycle events for analytics or conditional behavior.
 
-### Auto-Positioned Steps
+```typescript
+spotlight.addEventListener('spotlight-step', (e) => {
+  console.log(`Step ${e.detail.index}: ${e.detail.step.title}`);
+});
 
-Use `position: 'auto'` or omit the position to let the component automatically determine the best popover placement.
+spotlight.addEventListener('spotlight-end', () => {
+  localStorage.setItem('onboarding-done', 'true');
+});
 
-```html
-<snice-spotlight id="auto-tour"></snice-spotlight>
+spotlight.addEventListener('spotlight-skip', (e) => {
+  console.log(`Skipped at step ${e.detail.index}`);
+});
 
-<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' }
-  ];
+if (!localStorage.getItem('onboarding-done')) {
   spotlight.start();
-</script>
+}
 ```
 
-### Programmatic Step Navigation
+### Programmatic Navigation
 
-Control the tour programmatically using methods, useful for custom navigation UI.
+Control the tour with methods for custom navigation UI.
 
 ```html
 <snice-spotlight id="controlled-tour"></snice-spotlight>
@@ -220,13 +133,8 @@ Control the tour programmatically using methods, useful for custom navigation UI
 
 ## 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
+- Navigation buttons (Next, Previous, Skip) are keyboard accessible
+- Focus moves to the popover when each step is shown
+- Overlay and popover use appropriate ARIA roles
+- Escape key ends the tour
+- Transitions respect `prefers-reduced-motion`