snice 4.9.0 → 4.10.0

package/docs/components/testimonial.md

@@ -0,0 +1,185 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/testimonial.md instead)
+
+# Testimonial Component
+
+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.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-testimonial
+  quote="This product changed my workflow completely."
+  author="Jane Doe"
+></snice-testimonial>
+```
+
+```typescript
+import 'snice/components/testimonial/snice-testimonial';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `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") |
+| `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 |
+|----------|-------------|---------|
+| `--snice-color-background-element` | Card background color | `rgb(252 251 249)` |
+| `--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-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-spacing-lg` | Card padding | `1.5rem` |
+| `--snice-border-radius-lg` | Card border radius | `0.5rem` |
+
+## Examples
+
+### Card Variant (Default)
+
+Use the default `card` variant for a testimonial with background, border, and shadow.
+
+```html
+<snice-testimonial
+  quote="This product changed my workflow completely. I can't imagine going back."
+  author="Jane Doe"
+  role="CTO"
+  company="Acme Corp"
+  avatar="https://example.com/avatars/jane.jpg"
+  rating="5"
+></snice-testimonial>
+```
+
+### Minimal Variant
+
+Use the `minimal` variant for a subtle left-border accent style without a background fill.
+
+```html
+<snice-testimonial
+  variant="minimal"
+  quote="Simple, elegant, and powerful. Exactly what we needed."
+  author="Alex Rivera"
+  role="Lead Designer"
+  company="DesignStudio"
+  rating="4"
+></snice-testimonial>
+```
+
+### Featured Variant
+
+Use the `featured` variant for a bold, primary-colored background with inverse text, suitable for hero sections.
+
+```html
+<snice-testimonial
+  variant="featured"
+  quote="Outstanding experience from start to finish. The team was incredibly responsive."
+  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.
+
+```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">
+  <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
+
+## Best Practices
+
+1. **Use real quotes**: Authentic testimonials build trust; avoid generic placeholder text
+2. **Include author details**: Name and role/company add credibility
+3. **Add avatars when available**: Photos make testimonials more personal and trustworthy
+4. **Use the featured variant sparingly**: Reserve it for one or two standout quotes
+5. **Keep quotes concise**: Shorter quotes are more impactful and easier to scan
+6. **Use the rating when relevant**: Star ratings work well for product reviews but may not suit all testimonial contexts
+7. **Group testimonials together**: Display 3 or more testimonials in a grid for social proof

package/docs/components/textarea.md

@@ -1,208 +1,75 @@
-# Textarea Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/textarea.md instead)
 
-The `<snice-textarea>` component provides a multi-line text input with validation, character counting, and optional auto-grow functionality.
+# Textarea
+`<snice-textarea>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Methods](#methods)
-- [Events](#events)
-- [Features](#features)
-- [Examples](#examples)
+A multi-line text input with validation, character counting, and optional auto-grow.
 
 ## Basic Usage
 
-```html
-<snice-textarea
-  label="Comments"
-  placeholder="Enter your comments here"
-  rows="5"
-></snice-textarea>
-```
-
 ```typescript
 import 'snice/components/textarea/snice-textarea';
-
-const textarea = document.querySelector('snice-textarea');
-textarea.addEventListener('textarea-change', (e) => {
-  console.log('Value:', e.detail.value);
-});
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `value` | `string` | `''` | The textarea value |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
-| `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Visual style variant |
-| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Resize behavior |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `label` | `string` | `''` | Label text |
-| `helperText` | `string` | `''` | Helper text below textarea |
-| `errorText` | `string` | `''` | Error message (shown when invalid) |
-| `disabled` | `boolean` | `false` | Whether textarea is disabled |
-| `readonly` | `boolean` | `false` | Whether textarea is readonly |
-| `required` | `boolean` | `false` | Whether textarea is required |
-| `invalid` | `boolean` | `false` | Whether to show invalid state |
-| `rows` | `number` | `3` | Number of visible rows |
-| `cols` | `number` | `-1` | Number of visible columns |
-| `maxlength` | `number` | `-1` | Maximum character count |
-| `minlength` | `number` | `-1` | Minimum character count |
-| `autocomplete` | `string` | `''` | Autocomplete attribute value |
-| `name` | `string` | `''` | Form field name |
-| `autoGrow` | `boolean` | `false` | Whether to auto-grow height |
-
-## Methods
-
-### `focus(): void`
-Give focus to the textarea.
-
-```typescript
-textarea.focus();
-```
-
-### `blur(): void`
-Remove focus from the textarea.
-
-```typescript
-textarea.blur();
 ```
 
-### `select(): void`
-Select all text in the textarea.
-
-```typescript
-textarea.select();
-```
-
-### `checkValidity(): boolean`
-Check if the textarea passes validation.
-
-```typescript
-const isValid = textarea.checkValidity();
+```html
+<snice-textarea label="Comments" placeholder="Enter your comments here" rows="5"></snice-textarea>
 ```
 
-### `reportValidity(): boolean`
-Report validation status to the user.
+## Importing
 
+**ESM (bundler)**
 ```typescript
-textarea.reportValidity();
+import 'snice/components/textarea/snice-textarea';
 ```
 
-### `setCustomValidity(message: string): void`
-Set a custom validation message.
-
-```typescript
-textarea.setCustomValidity('This field is required');
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-textarea.min.js"></script>
 ```
 
-## Events
-
-### `textarea-input`
-Fired when the textarea value changes during input.
-
-**Detail**: `{ value: string, textarea: SniceTextareaElement }`
-
-```typescript
-textarea.addEventListener('textarea-input', (e) => {
-  console.log('Input value:', e.detail.value);
-});
-```
+## Examples
 
-### `textarea-change`
-Fired when the textarea value is committed (blur or enter).
+### Variants
 
-**Detail**: `{ value: string, textarea: SniceTextareaElement }`
+Use the `variant` attribute to change the visual style.
 
-```typescript
-textarea.addEventListener('textarea-change', (e) => {
-  console.log('Changed to:', e.detail.value);
-});
+```html
+<snice-textarea variant="outlined" label="Outlined"></snice-textarea>
+<snice-textarea variant="filled" label="Filled"></snice-textarea>
+<snice-textarea variant="underlined" label="Underlined"></snice-textarea>
 ```
 
-### `textarea-focus`
-Fired when the textarea receives focus.
-
-**Detail**: `{ textarea: SniceTextareaElement }`
-
-### `textarea-blur`
-Fired when the textarea loses focus.
-
-**Detail**: `{ textarea: SniceTextareaElement }`
+### Sizes
 
-## Features
-
-- **Form Integration**: Fully form-associated custom element with validation support
-- **Visual Variants**: Three style options (outlined, filled, underlined)
-- **Auto-grow**: Automatically expand height to fit content
-- **Character Counter**: Shows count when maxlength is set
-- **Resize Control**: Four resize modes (none, vertical, horizontal, both)
-- **Validation**: Built-in HTML5 validation with custom messages
-- **Accessibility**: Full keyboard support and ARIA attributes
-
-## Examples
-
-### Basic Textarea
+Use the `size` attribute to change the textarea size.
 
 ```html
-<snice-textarea
-  label="Description"
-  placeholder="Enter description..."
-  rows="4"
-></snice-textarea>
+<snice-textarea size="small" label="Small"></snice-textarea>
+<snice-textarea size="medium" label="Medium"></snice-textarea>
+<snice-textarea size="large" label="Large"></snice-textarea>
 ```
 
 ### With Character Counter
 
-```html
-<snice-textarea
-  label="Bio"
-  maxlength="500"
-  helper-text="Share a brief bio"
-></snice-textarea>
-```
-
-### Auto-grow Textarea
+Set the `maxlength` attribute to show a character counter.
 
 ```html
-<snice-textarea
-  label="Notes"
-  auto-grow
-  rows="3"
-  placeholder="Type to expand..."
-></snice-textarea>
+<snice-textarea label="Bio" maxlength="500" helper-text="Share a brief bio"></snice-textarea>
 ```
 
-### Error State
-
-```html
-<snice-textarea
-  label="Message"
-  invalid
-  error-text="This field is required"
-  required
-></snice-textarea>
-```
+### Auto-grow
 
-### Different Variants
+Set the `auto-grow` attribute to expand height automatically as content grows.
 
 ```html
-<snice-textarea variant="outlined" label="Outlined"></snice-textarea>
-<snice-textarea variant="filled" label="Filled"></snice-textarea>
-<snice-textarea variant="underlined" label="Underlined"></snice-textarea>
-```
-
-### Different Sizes
-
-```html
-<snice-textarea size="small" label="Small"></snice-textarea>
-<snice-textarea size="medium" label="Medium"></snice-textarea>
-<snice-textarea size="large" label="Large"></snice-textarea>
+<snice-textarea label="Notes" auto-grow rows="3" placeholder="Type to expand..."></snice-textarea>
 ```
 
 ### Resize Control
 
+Use the `resize` attribute to control user resize behavior.
+
 ```html
 <snice-textarea resize="none" label="No resize"></snice-textarea>
 <snice-textarea resize="vertical" label="Vertical only"></snice-textarea>
@@ -210,26 +77,74 @@ Fired when the textarea loses focus.
 <snice-textarea resize="both" label="Both directions"></snice-textarea>
 ```
 
+### Error State
+
+Set the `invalid` attribute with `error-text` to show validation errors.
+
+```html
+<snice-textarea label="Message" invalid error-text="This field is required" required></snice-textarea>
+```
+
 ### In a Form
 
+The textarea is form-associated and participates in form submission.
+
 ```html
 <form id="feedback-form">
-  <snice-textarea
-    name="feedback"
-    label="Your Feedback"
-    required
-    minlength="10"
-    maxlength="1000"
-    helper-text="Please provide at least 10 characters"
-  ></snice-textarea>
+  <snice-textarea name="feedback" label="Your Feedback" required minlength="10" maxlength="1000" helper-text="At least 10 characters"></snice-textarea>
   <button type="submit">Submit</button>
 </form>
-
-<script>
-document.getElementById('feedback-form').addEventListener('submit', (e) => {
-  e.preventDefault();
-  const formData = new FormData(e.target);
-  console.log('Feedback:', formData.get('feedback'));
-});
-</script>
 ```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `''` | Textarea value |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size variant |
+| `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Visual style |
+| `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Resize behavior |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `label` | `string` | `''` | Label text |
+| `helperText` (attr: `helper-text`) | `string` | `''` | Helper text below textarea |
+| `errorText` (attr: `error-text`) | `string` | `''` | Error message (shown when invalid) |
+| `disabled` | `boolean` | `false` | Disables the textarea |
+| `readonly` | `boolean` | `false` | Makes the textarea read-only |
+| `required` | `boolean` | `false` | Makes the textarea required |
+| `invalid` | `boolean` | `false` | Shows invalid state |
+| `rows` | `number` | `3` | Number of visible rows |
+| `cols` | `number` | `-1` | Number of visible columns |
+| `maxlength` | `number` | `-1` | Maximum character count |
+| `minlength` | `number` | `-1` | Minimum character count |
+| `autocomplete` | `string` | `''` | Autocomplete attribute |
+| `name` | `string` | `''` | Form field name |
+| `autoGrow` (attr: `auto-grow`) | `boolean` | `false` | Auto-expand height |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `textarea-input` | `{ value: string, textarea: SniceTextareaElement }` | Value changed during input |
+| `textarea-change` | `{ value: string, textarea: SniceTextareaElement }` | Value committed (blur) |
+| `textarea-focus` | `{ textarea: SniceTextareaElement }` | Textarea received focus |
+| `textarea-blur` | `{ textarea: SniceTextareaElement }` | Textarea lost focus |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `focus()` | `options?: FocusOptions` | Focus the textarea |
+| `blur()` | -- | Remove focus |
+| `select()` | -- | Select all text |
+| `checkValidity()` | -- | Check validation, returns `boolean` |
+| `reportValidity()` | -- | Report validation to user, returns `boolean` |
+| `setCustomValidity()` | `message: string` | Set custom validation message |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `textarea` | The native textarea element |
+| `spinner` | Loading spinner |
+| `error-text` | Error message container |
+| `helper-text` | Helper text container |