snice 4.28.0 → 4.30.0

package/docs/components/testimonial.md

@@ -1,8 +1,9 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/testimonial.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/testimonial.md -->
 
-# Testimonial Component
+# Testimonial
+`<snice-testimonial>`
 
-The testimonial component displays a quote or review card with author information, avatar, role/company attribution, optional star rating, and multiple visual variants. It is ideal for customer testimonials, reviews, and social proof sections.
+Displays a quote or review card with author information, avatar, role/company attribution, optional star rating, and multiple visual variants.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -11,7 +12,6 @@ The testimonial component displays a quote or review card with author informatio
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
@@ -20,19 +20,11 @@ The testimonial component displays a quote or review card with author informatio
 | `quote` | `string` | `''` | The testimonial quote text |
 | `author` | `string` | `''` | Author name |
 | `avatar` | `string` | `''` | URL for the author's avatar image |
-| `role` | `string` | `''` | Author's role or job title (e.g., "CEO") |
+| `role` | `string` | `''` | Author's role or job title |
 | `company` | `string` | `''` | Author's company name (renders as "role at company") |
 | `rating` | `number` | `0` | Star rating from 0-5 (0 hides the rating display) |
 | `variant` | `'card' \| 'minimal' \| 'featured'` | `'card'` | Visual style variant |
 
-### Variants
-
-| Variant | Description |
-|---------|-------------|
-| `card` | Default style with background, border, and shadow |
-| `minimal` | Left border accent, no background fill |
-| `featured` | Primary-colored background with inverse (light) text |
-
 ## CSS Custom Properties
 
 | Property | Description | Default |
@@ -41,41 +33,28 @@ The testimonial component displays a quote or review card with author informatio
 | `--snice-color-border` | Card border color | `rgb(226 226 226)` |
 | `--snice-color-primary` | Quote icon color, minimal border accent, featured background | `rgb(37 99 235)` |
 | `--snice-color-text` | Primary text color | `rgb(23 23 23)` |
-| `--snice-color-text-secondary` | Author role/company text color | _(theme default)_ |
+| `--snice-color-text-secondary` | Author role/company text color | -- |
 | `--snice-color-text-inverse` | Text color for the featured variant | `rgb(250 250 250)` |
 | `--snice-color-warning` | Star rating color | `rgb(234 179 8)` |
-| `--snice-shadow-sm` | Card shadow | _(theme default)_ |
+| `--snice-shadow-sm` | Card shadow | -- |
 | `--snice-spacing-lg` | Card padding | `1.5rem` |
 | `--snice-border-radius-lg` | Card border radius | `0.5rem` |
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer testimonial container |
-| `quote` | `<div>` | The quote text element |
-| `author` | `<div>` | The author info container (avatar, name, role) |
-| `stars` | `<div>` | The star rating element |
+| Part | Description |
+|------|-------------|
+| `base` | The outer testimonial container |
+| `quote` | The quote text element |
+| `author` | The author info container (avatar, name, role) |
+| `stars` | The star rating element |
 
-```css
-snice-testimonial::part(base) {
-  border: 2px solid #e2e8f0;
-}
-
-snice-testimonial::part(quote) {
-  font-style: italic;
-  font-size: 1.125rem;
-}
+## Basic Usage
 
-snice-testimonial::part(stars) {
-  color: #f59e0b;
-}
+```typescript
+import 'snice/components/testimonial/snice-testimonial';
 ```
 
-## Basic Usage
-
 ```html
 <snice-testimonial
   quote="This product changed my workflow completely."
@@ -83,10 +62,6 @@ snice-testimonial::part(stars) {
 ></snice-testimonial>
 ```
 
-```typescript
-import 'snice/components/testimonial/snice-testimonial';
-```
-
 ## Examples
 
 ### Card Variant (Default)
@@ -121,83 +96,51 @@ Use the `minimal` variant for a subtle left-border accent style without a backgr
 
 ### Featured Variant
 
-Use the `featured` variant for a bold, primary-colored background with inverse text, suitable for hero sections.
+Use the `featured` variant for a bold, primary-colored background with inverse text.
 
 ```html
 <snice-testimonial
   variant="featured"
-  quote="Outstanding experience from start to finish. The team was incredibly responsive."
+  quote="Outstanding experience from start to finish."
   author="John Smith"
   role="VP of Engineering"
   company="TechCorp"
-  avatar="https://example.com/avatars/john.jpg"
   rating="5"
 ></snice-testimonial>
 ```
 
 ### Without Rating
 
-Set `rating` to `0` (or omit it) to hide the star rating display entirely.
+Set `rating` to `0` (or omit it) to hide the star rating display.
 
 ```html
 <snice-testimonial
   quote="A game-changer for our team's productivity."
   author="Sarah Kim"
   role="Product Manager"
-  company="StartupXYZ"
 ></snice-testimonial>
 ```
 
 ### Testimonial Grid
 
-Arrange multiple testimonials in a responsive grid layout.
-
 ```html
-<style>
-  .testimonial-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-    gap: 1.5rem;
-  }
-</style>
-
-<div class="testimonial-grid">
+<div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 1.5rem;">
   <snice-testimonial
     quote="Incredible tool. Saved us hours every week."
     author="Maria Lopez"
-    role="Engineering Manager"
-    company="DataFlow"
     rating="5"
   ></snice-testimonial>
-
   <snice-testimonial
     quote="The best UI components library I've used."
     author="Chris Park"
-    role="Frontend Developer"
-    company="WebScale"
-    avatar="https://example.com/avatars/chris.jpg"
     rating="4"
   ></snice-testimonial>
-
-  <snice-testimonial
-    quote="Clean design, great documentation, easy integration."
-    author="Emma Wilson"
-    role="Tech Lead"
-    company="BuildRight"
-    rating="5"
-  ></snice-testimonial>
 </div>
 ```
 
 ## Accessibility
 
-- **Semantic markup**: The quote is rendered with appropriate quotation semantics
-- **Image alt text**: Avatar images use the author name as alt text for screen readers
-- **Star rating**: The star rating is conveyed with an ARIA label (e.g., "4 out of 5 stars")
-- **Color contrast**: All text meets WCAG AA contrast requirements across all variants, including the featured variant with inverse text
-- **No interactive elements**: Testimonials are display-only, so no keyboard interaction is needed
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+- Avatar images use the author name as alt text for screen readers
+- Star rating is conveyed with visible star characters
+- Color contrast meets WCAG AA across all variants
+- No interactive elements; testimonials are display-only

package/docs/components/textarea.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/textarea.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/textarea.md -->
 
 # Textarea
 `<snice-textarea>`
 
-A multi-line text input with validation, character counting, and optional auto-grow.
+A multi-line text input with validation, character counting, and optional auto-grow. Form-associated.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/textarea/snice-textarea';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-textarea.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 

package/docs/components/theme.md

@@ -1,21 +1,14 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/theme.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/theme.md -->
 
 # Theme
 `theme.css`
 
-Provides all design tokens for Snice components via CSS custom properties. Includes light and dark themes with automatic system preference detection.
+Provides all design tokens for Snice components via CSS custom properties. Includes light and dark themes with automatic system preference detection. This is a CSS-only module with no web component.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/theme/theme.css';
-```
-
-**CDN**
-```html
-<link rel="stylesheet" href="theme.min.css">
-```
+## Table of Contents
+- [CSS Custom Properties](#css-custom-properties)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## CSS Custom Properties
 
@@ -137,6 +130,10 @@ color: hsl(var(--snice-color-blue-500));
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/theme/theme.css';
+```
+
 ```html
 <link rel="stylesheet" href="snice/components/theme/theme.css">
 ```
@@ -168,16 +165,6 @@ Set `data-theme="dark"` on any element to apply dark theme tokens.
 </html>
 ```
 
-### Force Light Theme
-
-Set `data-theme="light"` to override system preference and force light theme.
-
-```html
-<html data-theme="light">
-  <!-- Always light, regardless of system preference -->
-</html>
-```
-
 ### Automatic Theme (System Preference)
 
 Without a `data-theme` attribute, the theme follows the user's system preference via `prefers-color-scheme`.

package/docs/components/time-picker.md

@@ -1,46 +1,41 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/time-picker.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/time-picker.md -->
 
 # Time Picker
 `<snice-time-picker>`
 
-Single time selection with hour/minute/second selectors and AM/PM toggle.
+Single time selection with hour/minute/second selectors and AM/PM toggle. Form-associated.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/time-picker/snice-time-picker';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-time-picker.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `value` | `value` | `string` | `''` | Time value (HH:MM or HH:MM:SS) |
-| `format` | `format` | `'12h' \| '24h'` | `'24h'` | Display format |
-| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Component size |
-| `step` | `step` | `1 \| 5 \| 10 \| 15 \| 30` | `15` | Minute step interval |
-| `minTime` | `min-time` | `string` | `''` | Minimum selectable time |
-| `maxTime` | `max-time` | `string` | `''` | Maximum selectable time |
-| `showSeconds` | `show-seconds` | `boolean` | `false` | Show seconds selector |
-| `disabled` | `disabled` | `boolean` | `false` | Disables the picker |
-| `readonly` | `readonly` | `boolean` | `false` | Makes input read-only |
-| `loading` | `loading` | `boolean` | `false` | Shows loading spinner |
-| `clearable` | `clearable` | `boolean` | `false` | Shows clear button when value is set |
-| `placeholder` | `placeholder` | `string` | `''` | Input placeholder text |
-| `label` | `label` | `string` | `''` | Label text |
-| `helperText` | `helper-text` | `string` | `''` | Helper text below input |
-| `errorText` | `error-text` | `string` | `''` | Error text below input |
-| `required` | `required` | `boolean` | `false` | Marks as required |
-| `invalid` | `invalid` | `boolean` | `false` | Shows invalid styling |
-| `name` | `name` | `string` | `''` | Form field name |
-| `variant` | `variant` | `'dropdown' \| 'inline'` | `'dropdown'` | Display variant |
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Time value (HH:MM or HH:MM:SS) |
+| `format` | `'12h' \| '24h'` | `'24h'` | Display format |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Component size |
+| `step` | `1 \| 5 \| 10 \| 15 \| 30` | `15` | Minute step interval |
+| `minTime` (attr: `min-time`) | `string` | `''` | Minimum selectable time |
+| `maxTime` (attr: `max-time`) | `string` | `''` | Maximum selectable time |
+| `showSeconds` (attr: `show-seconds`) | `boolean` | `false` | Show seconds selector |
+| `disabled` | `boolean` | `false` | Disables the picker |
+| `readonly` | `boolean` | `false` | Makes input read-only |
+| `loading` | `boolean` | `false` | Shows loading spinner |
+| `clearable` | `boolean` | `false` | Shows clear button when value is set |
+| `placeholder` | `string` | `''` | Input placeholder text |
+| `label` | `string` | `''` | Label text |
+| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text below input |
+| `errorText` (attr: `error-text`) | `string` | `''` | Error text below input |
+| `required` | `boolean` | `false` | Marks as required |
+| `invalid` | `boolean` | `false` | Shows invalid styling |
+| `name` | `string` | `''` | Form field name |
+| `variant` | `'dropdown' \| 'inline'` | `'dropdown'` | Display variant |
 
 ## Methods
 
@@ -51,8 +46,8 @@ import 'snice/components/time-picker/snice-time-picker';
 | `clear()` | -- | Clears the selected time |
 | `focus()` | -- | Focuses the input |
 | `blur()` | -- | Removes focus |
-| `checkValidity()` | -- | Returns input validity |
-| `reportValidity()` | -- | Reports input validity |
+| `checkValidity()` | -- | Returns input validity (`boolean`) |
+| `reportValidity()` | -- | Reports input validity to user (`boolean`) |
 | `setCustomValidity()` | `message: string` | Sets custom validation message |
 
 ## Events
@@ -123,22 +118,6 @@ Use the `size` attribute to change the picker size.
 <snice-time-picker size="large" label="Large"></snice-time-picker>
 ```
 
-### Loading
-
-Set the `loading` attribute to show a spinner and disable interaction.
-
-```html
-<snice-time-picker loading label="Loading"></snice-time-picker>
-```
-
-### Clearable
-
-Set the `clearable` attribute to show a clear button when a value is selected.
-
-```html
-<snice-time-picker value="14:30" clearable label="Clearable"></snice-time-picker>
-```
-
 ### Step Intervals
 
 Use the `step` attribute to control the minute increment in the selector.
@@ -171,6 +150,22 @@ Use `variant="inline"` to always show the time selectors without a dropdown.
 <snice-time-picker variant="inline" value="10:00" label="Inline Picker"></snice-time-picker>
 ```
 
+### Clearable
+
+Set the `clearable` attribute to show a clear button when a value is selected.
+
+```html
+<snice-time-picker value="14:30" clearable label="Clearable"></snice-time-picker>
+```
+
+### Loading
+
+Set the `loading` attribute to show a spinner and disable interaction.
+
+```html
+<snice-time-picker loading label="Loading"></snice-time-picker>
+```
+
 ### Helper and Error Text
 
 Use `helper-text` and `error-text` for guidance or validation messages.
@@ -191,16 +186,6 @@ Use `helper-text` and `error-text` for guidance or validation messages.
 
 Use `name` and `required` for native form participation.
 
-```html
-<form>
-  <snice-time-picker name="startTime" required label="Start Time"></snice-time-picker>
-</form>
-```
-
-### Form Validation
-
-The component supports the Constraint Validation API. Use `checkValidity()`, `reportValidity()`, and `setCustomValidity()` for custom form validation.
-
 ```html
 <form>
   <snice-time-picker name="startTime" required label="Start Time"></snice-time-picker>
@@ -208,19 +193,10 @@ The component supports the Constraint Validation API. Use `checkValidity()`, `re
 </form>
 ```
 
-```typescript
-picker.setCustomValidity('Please select a time during business hours');
-picker.reportValidity();
-```
-
 ### Event Handling
 
 Listen for time changes using the `time-change` event.
 
-```html
-<snice-time-picker label="Pick a time"></snice-time-picker>
-```
-
 ```typescript
 picker.addEventListener('time-change', (e) => {
   console.log('Value:', e.detail.value);

package/docs/components/time-range-picker.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/time-range-picker.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/time-range-picker.md -->
 
 # Time Range Picker
 `<snice-time-range-picker>`
 
 A vertically stacked time slot picker for selecting time ranges within a single day via click and drag.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/time-range-picker/snice-time-range-picker';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-time-range-picker.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -32,15 +27,6 @@ import 'snice/components/time-range-picker/snice-time-range-picker';
 | `readonly` | `boolean` | `false` | Show selections but prevent interaction |
 | `disabled` | `boolean` | `false` | Disable all interaction |
 
-## Methods
-
-| Method | Arguments | Description |
-|--------|-----------|-------------|
-| `getSelectedRanges()` | -- | Returns `TimeRange[]` |
-| `setSelectedRanges()` | `ranges: TimeRange[]` | Set selected ranges |
-| `clearSelection()` | -- | Clear all selections |
-| `isSlotDisabled()` | `time: string` | Check if slot is disabled, returns `boolean` |
-
 ### TimeRange Interface
 
 ```typescript
@@ -50,6 +36,15 @@ interface TimeRange {
 }
 ```
 
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `getSelectedRanges()` | -- | Returns `TimeRange[]` |
+| `setSelectedRanges()` | `ranges: TimeRange[]` | Set selected ranges |
+| `clearSelection()` | -- | Clear all selections |
+| `isSlotDisabled()` | `time: string` | Check if slot is disabled, returns `boolean` |
+
 ## Events
 
 | Event | Detail | Description |
@@ -60,25 +55,11 @@ interface TimeRange {
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer wrapper container |
-| `header` | `<div>` | The header with label and selected value display |
-| `slots` | `<div>` | The time slots container |
-
-```css
-snice-time-range-picker::part(header) {
-  font-weight: 600;
-  padding: 0.75rem;
-}
-
-snice-time-range-picker::part(slots) {
-  max-height: 400px;
-  overflow-y: auto;
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | The outer wrapper container |
+| `header` | The header with label and selected value display |
+| `slots` | The time slots container |
 
 ## Basic Usage
 

package/docs/components/timeline.md

@@ -1,22 +1,15 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/timeline.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/timeline.md -->
 
 # Timeline
 `<snice-timeline>`
 
-Displays events in chronological order with markers, timestamps, and descriptions.
+Displays events in chronological order with markers, timestamps, and descriptions. Supports vertical and horizontal orientations with configurable item positioning.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/timeline/snice-timeline';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-timeline.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 

package/docs/components/timer.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/timer.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/timer.md -->
 
 # Timer
 `<snice-timer>`
 
-A stopwatch and countdown timer component.
+A stopwatch and countdown timer component with start/stop/reset controls.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/timer/snice-timer';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-timer.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 
@@ -46,24 +41,11 @@ import 'snice/components/timer/snice-timer';
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The outer timer container |
-| `display` | `<div>` | The time display element |
-| `controls` | `<div>` | The start/stop/reset button container |
-
-```css
-snice-timer::part(display) {
-  font-size: 3rem;
-  font-family: monospace;
-}
-
-snice-timer::part(controls) {
-  gap: 1rem;
-}
-```
+| Part | Description |
+|------|-------------|
+| `base` | The outer timer container |
+| `display` | The time display element |
+| `controls` | The start/stop/reset button container |
 
 ## Basic Usage
 
@@ -83,6 +65,8 @@ import 'snice/components/timer/snice-timer';
 
 ### Stopwatch
 
+Use the default `stopwatch` mode to count up from zero.
+
 ```html
 <snice-timer id="stopwatch" mode="stopwatch"></snice-timer>