snice 4.9.0 → 4.11.0

package/docs/components/timeline.md

@@ -1,75 +1,51 @@
-# Timeline Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/timeline.md instead)
 
-The `<snice-timeline>` component displays events in chronological order with markers, timestamps, and descriptions.
+# Timeline
+`<snice-timeline>`
+
+Displays events in chronological order with markers, timestamps, and descriptions.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/timeline/snice-timeline';
+```
+
 ```html
 <snice-timeline id="timeline"></snice-timeline>
 
 <script>
-  const timeline = document.getElementById('timeline');
-  timeline.items = [
-    {
-      timestamp: '2024-01-15',
-      title: 'Event Title',
-      description: 'Event description'
-    }
+  document.getElementById('timeline').items = [
+    { timestamp: '2024-01-15', title: 'Project Started', description: 'Initial planning phase' },
+    { timestamp: '2024-01-20', title: 'Design Complete', description: 'Mockups approved' }
   ];
 </script>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Timeline orientation |
-| `position` | `'left' \| 'right' \| 'alternate'` | `'left'` | Item position (vertical only) |
-| `items` | `TimelineItem[]` | `[]` | Timeline items |
-| `reverse` | `boolean` | `false` | Reverse item order |
-
-## TimelineItem Interface
+## Importing
 
+**ESM (bundler)**
 ```typescript
-interface TimelineItem {
-  timestamp?: string;
-  title: string;
-  description?: string;
-  icon?: string;
-  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
-}
+import 'snice/components/timeline/snice-timeline';
 ```
 
-## Examples
-
-### Vertical Timeline
-
+**CDN**
 ```html
-<snice-timeline id="timeline"></snice-timeline>
-
-<script>
-  document.getElementById('timeline').items = [
-    {
-      timestamp: '2024-01-15 09:00',
-      title: 'Project Started',
-      description: 'Initial planning phase'
-    },
-    {
-      timestamp: '2024-01-20 14:30',
-      title: 'Design Complete',
-      description: 'Mockups approved'
-    }
-  ];
-</script>
+<script src="snice-runtime.min.js"></script>
+<script src="snice-timeline.min.js"></script>
 ```
 
-### Horizontal Timeline
+## Examples
+
+### Horizontal
+
+Use the `orientation` attribute for a horizontal layout.
 
 ```html
-<snice-timeline orientation="horizontal" id="horizontal-timeline"></snice-timeline>
+<snice-timeline orientation="horizontal" id="h-timeline"></snice-timeline>
 
 <script>
-  document.getElementById('horizontal-timeline').items = [
+  document.getElementById('h-timeline').items = [
     { title: 'Step 1', description: 'First step' },
     { title: 'Step 2', description: 'Second step' },
     { title: 'Step 3', description: 'Third step' }
@@ -79,6 +55,8 @@ interface TimelineItem {
 
 ### Alternate Position
 
+Use `position="alternate"` for a zigzag layout.
+
 ```html
 <snice-timeline position="alternate" id="alt-timeline"></snice-timeline>
 
@@ -93,100 +71,74 @@ interface TimelineItem {
 
 ### With Variants
 
+Use the `variant` property on items to set marker colors.
+
 ```html
 <snice-timeline id="variant-timeline"></snice-timeline>
 
 <script>
   document.getElementById('variant-timeline').items = [
-    {
-      title: 'Completed',
-      variant: 'success',
-      description: 'Task finished successfully'
-    },
-    {
-      title: 'Warning',
-      variant: 'warning',
-      description: 'Attention needed'
-    },
-    {
-      title: 'Error',
-      variant: 'error',
-      description: 'Action failed'
-    }
+    { title: 'Completed', variant: 'success', description: 'Task finished' },
+    { title: 'Warning', variant: 'warning', description: 'Attention needed' },
+    { title: 'Error', variant: 'error', description: 'Action failed' }
   ];
 </script>
 ```
 
 ### Custom Icons
 
+Use the `icon` property on items for custom marker icons.
+
 ```html
 <snice-timeline id="icon-timeline"></snice-timeline>
 
 <script>
   document.getElementById('icon-timeline').items = [
-    { title: 'Planning', icon: '📋' },
-    { title: 'Development', icon: '💻' },
-    { title: 'Launch', icon: '🚀' }
+    { title: 'Planning', icon: '1' },
+    { title: 'Development', icon: '2' },
+    { title: 'Launch', icon: '3' }
   ];
 </script>
 ```
 
 ### Reversed Order
 
-```html
-<snice-timeline reverse id="reversed-timeline"></snice-timeline>
+Set the `reverse` attribute to reverse item display order.
 
-<script>
-  document.getElementById('reversed-timeline').items = [
-    { title: 'Latest Event', timestamp: '2024-03-01' },
-    { title: 'Earlier Event', timestamp: '2024-02-01' },
-    { title: 'First Event', timestamp: '2024-01-01' }
-  ];
-</script>
+```html
+<snice-timeline reverse id="reversed"></snice-timeline>
 ```
 
-## Styling
-
-The component exposes several CSS parts for styling:
-
-```css
-snice-timeline::part(container) {
-  /* Timeline container */
-}
-
-snice-timeline::part(item) {
-  /* Timeline item */
-}
-
-snice-timeline::part(marker) {
-  /* Item marker/circle */
-}
-
-snice-timeline::part(icon) {
-  /* Marker icon */
-}
-
-snice-timeline::part(content) {
-  /* Item content area */
-}
+## Properties
 
-snice-timeline::part(timestamp) {
-  /* Timestamp text */
-}
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Timeline orientation |
+| `position` | `'left' \| 'right' \| 'alternate'` | `'left'` | Item position (vertical only) |
+| `items` | `TimelineItem[]` | `[]` | Timeline items |
+| `reverse` | `boolean` | `false` | Reverse item order |
 
-snice-timeline::part(title) {
-  /* Title text */
-}
+### TimelineItem Interface
 
-snice-timeline::part(description) {
-  /* Description text */
+```typescript
+interface TimelineItem {
+  timestamp?: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
 }
 ```
 
-## Notes
-
-- Items without timestamps will still render but won't display a timestamp
-- Items without descriptions will only show the title
-- Default icons are provided for each variant
-- Horizontal timelines work best with 3-5 items
-- Alternate positioning creates a zigzag layout
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Timeline container |
+| `item` | Individual timeline item |
+| `marker` | Item marker circle |
+| `icon` | Marker icon |
+| `content` | Item content area |
+| `timestamp` | Timestamp text |
+| `title` | Title text |
+| `description` | Description text |

package/docs/components/timer.md

@@ -1,42 +1,36 @@
-# Timer Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/timer.md instead)
 
-The `<snice-timer>` component provides a stopwatch and countdown timer.
+# Timer
+`<snice-timer>`
+
+A stopwatch and countdown timer component.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/timer/snice-timer';
+```
+
 ```html
 <!-- Stopwatch -->
 <snice-timer mode="stopwatch"></snice-timer>
 
-<!-- Countdown Timer -->
+<!-- Countdown -->
 <snice-timer mode="timer" initial-time="60"></snice-timer>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `mode` | `'stopwatch' \| 'timer'` | `'stopwatch'` | Timer mode |
-| `initial-time` | `number` | `0` | Starting time in seconds (for timer mode) |
-| `running` | `boolean` | `false` | Timer running state (read-only) |
-
-## Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `start()` | `void` | Start the timer |
-| `stop()` | `void` | Stop/pause the timer |
-| `reset()` | `void` | Reset to initial state |
-| `getTime()` | `number` | Get current time in seconds |
+## Importing
 
-## Events
+**ESM (bundler)**
+```typescript
+import 'snice/components/timer/snice-timer';
+```
 
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `timer-start` | `{ timer, time }` | Timer started |
-| `timer-stop` | `{ timer, time }` | Timer stopped |
-| `timer-reset` | `{ timer, time }` | Timer reset |
-| `timer-complete` | `{ timer }` | Countdown completed (timer mode only) |
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-timer.min.js"></script>
+```
 
 ## Examples
 
@@ -48,7 +42,6 @@ The `<snice-timer>` component provides a stopwatch and countdown timer.
 <script>
   const stopwatch = document.getElementById('stopwatch');
   stopwatch.start();
-
   // Later...
   stopwatch.stop();
   console.log('Elapsed:', stopwatch.getTime(), 'seconds');
@@ -57,16 +50,16 @@ The `<snice-timer>` component provides a stopwatch and countdown timer.
 
 ### Countdown Timer
 
+Set the `initial-time` attribute in seconds for a countdown.
+
 ```html
-<snice-timer id="timer" mode="timer" initial-time="300"></snice-timer>
+<snice-timer id="countdown" mode="timer" initial-time="300"></snice-timer>
 
 <script>
-  const timer = document.getElementById('timer');
-
+  const timer = document.getElementById('countdown');
   timer.addEventListener('timer-complete', () => {
     console.log('Time is up!');
   });
-
   timer.start();
 </script>
 ```
@@ -79,65 +72,30 @@ The `<snice-timer>` component provides a stopwatch and countdown timer.
 <button onclick="document.getElementById('my-timer').start()">Start</button>
 <button onclick="document.getElementById('my-timer').stop()">Stop</button>
 <button onclick="document.getElementById('my-timer').reset()">Reset</button>
-
-<script>
-  const timer = document.getElementById('my-timer');
-
-  timer.addEventListener('timer-start', (e) => {
-    console.log('Timer started at', e.detail.time);
-  });
-
-  timer.addEventListener('timer-stop', (e) => {
-    console.log('Timer stopped at', e.detail.time);
-  });
-</script>
-```
-
-### Workout Timer
-
-```html
-<snice-timer id="workout" mode="timer" initial-time="45"></snice-timer>
-
-<script>
-  const workout = document.getElementById('workout');
-
-  workout.addEventListener('timer-complete', () => {
-    alert('Rest time!');
-    // Start rest period
-    workout.initialTime = 15;
-    workout.reset();
-    workout.start();
-  });
-
-  workout.start();
-</script>
 ```
 
-## Styling
-
-The timer uses CSS custom properties from the theme system:
+## Properties
 
-```css
-snice-timer {
-  --snice-color-background-element: rgb(252 251 249);
-  --snice-color-border: rgb(226 226 226);
-  --snice-color-text: rgb(23 23 23);
-  --snice-color-success: rgb(22 163 74);
-  --snice-color-warning: rgb(202 138 4);
-  --snice-color-neutral: rgb(82 82 82);
-}
-```
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'stopwatch' \| 'timer'` | `'stopwatch'` | Timer mode |
+| `initialTime` (attr: `initial-time`) | `number` | `0` | Starting time in seconds (timer mode) |
+| `running` | `boolean` | `false` | Whether the timer is running (read-only) |
 
-## Accessibility
+## Events
 
-- Large, readable time display
-- Clear button labels and icons
-- Keyboard accessible controls
-- High contrast buttons
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `timer-start` | `{ timer, time }` | Timer started |
+| `timer-stop` | `{ timer, time }` | Timer stopped |
+| `timer-reset` | `{ timer, time }` | Timer reset |
+| `timer-complete` | `{ timer }` | Countdown completed (timer mode only) |
 
-## Best Practices
+## Methods
 
-1. **Choose the right mode**: Use stopwatch for tracking elapsed time, timer for countdowns
-2. **Handle timer-complete**: Listen for completion events in timer mode
-3. **Provide context**: Add labels or descriptions near the timer
-4. **Reset appropriately**: Call `reset()` to return to initial state
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `start()` | -- | Start the timer |
+| `stop()` | -- | Stop/pause the timer |
+| `reset()` | -- | Reset to initial state |
+| `getTime()` | -- | Get current time in seconds, returns `number` |