snice 4.27.0 → 4.29.0

package/docs/components/product-card.md

@@ -1,152 +1,90 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/product-card.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/product-card.md -->
 
-# Product Card Component
+# Product Card
+`<snice-product-card>`
 
-The product card component displays a product with image gallery, pricing, star ratings, variant selectors, and an add-to-cart button. Supports vertical, horizontal, and compact layouts.
+A product display card with image gallery, pricing, star ratings, variant selectors, and an add-to-cart button. Supports multiple layout variants.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/product-card/snice-product-card';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-product-card.min.js"></script>
-```
+- [Data Types](#data-types)
 
 ## Properties
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `name` | `name` | `string` | `''` | Product name |
-| `price` | `price` | `number` | `0` | Regular price |
-| `salePrice` | `sale-price` | `number \| null` | `null` | Sale price (shows strikethrough on original) |
-| `currency` | `currency` | `string` | `'$'` | Currency symbol |
-| `images` | — | `string[]` | `[]` | Image URLs (gallery navigation for multiple) |
-| `rating` | `rating` | `number` | `0` | Star rating (0-5, supports half stars) |
-| `reviewCount` | `review-count` | `number` | `0` | Number of reviews |
-| `variants` | — | `ProductVariant[]` | `[]` | Variant selector groups |
-| `inStock` | `in-stock` | `boolean` | `true` | Whether product is in stock |
-| `variant` | `variant` | `'vertical' \| 'horizontal' \| 'compact' \| 'featured' \| 'minimal' \| 'grid'` | `'vertical'` | Card layout variant |
-| `badge` | `badge` | `string` | `''` | Badge text (e.g. "SALE", "NEW") |
-| `badgeVariant` | `badge-variant` | `'sale' \| 'new' \| 'featured'` | `'sale'` | Badge visual style |
-| `loading` | `loading` | `boolean` | `false` | Shows skeleton loading state |
-| `favorite` | `favorite` | `boolean` | `false` | Favorite/heart toggle state |
-| `stockCount` | `stock-count` | `number` | `-1` | Stock count (-1 hides, <5 shows urgency) |
-
-### ProductVariant Interface
-
-```typescript
-interface ProductVariant {
-  type: string;       // Variant group name, e.g. 'Size', 'Color'
-  options: string[];  // Available options, e.g. ['S', 'M', 'L'] or ['#000', '#fff']
-}
-```
-
-When the `type` is `'Color'` (case-insensitive), options are rendered as color swatches instead of text chips.
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `name` | `string` | `''` | Product name |
+| `price` | `number` | `0` | Regular price |
+| `salePrice` (attr: `sale-price`) | `number \| null` | `null` | Sale price (shows strikethrough on original) |
+| `currency` | `string` | `'$'` | Currency symbol |
+| `images` | `string[]` | `[]` | Image URLs (gallery navigation for multiple). Set via JS. |
+| `rating` | `number` | `0` | Star rating (0-5, supports half stars) |
+| `reviewCount` (attr: `review-count`) | `number` | `0` | Number of reviews |
+| `variants` | `ProductVariant[]` | `[]` | Variant selector groups. Set via JS. |
+| `inStock` (attr: `in-stock`) | `boolean` | `true` | Whether product is in stock |
+| `variant` | `'vertical' \| 'horizontal' \| 'compact' \| 'featured' \| 'minimal' \| 'grid'` | `'vertical'` | Card layout variant |
+| `badge` | `string` | `''` | Badge text (e.g. "SALE", "NEW") |
+| `badgeVariant` (attr: `badge-variant`) | `'sale' \| 'new' \| 'featured'` | `'sale'` | Badge visual style |
+| `loading` | `boolean` | `false` | Shows skeleton loading state |
+| `favorite` | `boolean` | `false` | Favorite/heart toggle state |
+| `stockCount` (attr: `stock-count`) | `number` | `-1` | Stock count (-1 hides, <5 shows urgency) |
 
 ## Events
 
-#### `add-to-cart`
-Fired when the add-to-cart button is clicked.
-
-**Event Detail:**
-```typescript
-{
-  name: string;                           // Product name
-  price: number;                          // Effective price (sale price if available)
-  salePrice: number | null;               // Sale price
-  selectedVariants: Record<string, string>; // e.g. { Size: 'M', Color: '#000' }
-}
-```
-
-#### `variant-select`
-Fired when a variant option is selected.
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `add-to-cart` | `{ name, price, salePrice, selectedVariants }` | Fired when the add-to-cart button is clicked |
+| `variant-select` | `{ type: string, value: string }` | Fired when a variant option is selected |
+| `image-click` | `{ index: number, src: string }` | Fired when the gallery image is clicked |
+| `favorite` | `{ favorited: boolean }` | Fired when the favorite button is toggled |
+| `quick-view` | `void` | Fired when the quick view overlay is clicked |
 
-**Event Detail:**
-```typescript
-{
-  type: string;   // Variant group name
-  value: string;  // Selected option value
-}
-```
+## CSS Parts
 
-#### `image-click`
-Fired when the gallery image is clicked.
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | The outer card container |
+| `gallery` | `<div>` | Image gallery area |
+| `body` | `<div>` | Card body content |
+| `title` | `<h3>` | Product name heading |
+| `rating` | `<div>` | Star rating area |
+| `stars` | `<div>` | Star rating container |
+| `price` | `<div>` | Price display area |
+| `price-current` | `<span>` | Current price display |
+| `price-original` | `<span>` | Original price (strikethrough on sale) |
+| `discount` | `<span>` | Discount percentage badge |
+| `stock` | `<div>` | Stock status indicator |
+| `variants` | `<div>` | Variant selectors area |
+| `variant-group` | `<div>` | Variant selector group |
+| `variant-option` | `<button>` | Individual variant option button |
+| `cta` | `<button>` | Add-to-cart button |
+| `badge` | `<span>` | Product badge |
+| `favorite-btn` | `<button>` | Favorite/heart button |
+| `image` | `<img>` | Gallery image element |
 
-**Event Detail:**
-```typescript
-{
-  index: number;  // Current image index
-  src: string;    // Image URL
-}
-```
-
-#### `favorite`
-Fired when the favorite/heart button is toggled.
+## Basic Usage
 
-**Event Detail:**
 ```typescript
-{
-  favorited: boolean;  // Whether the product is now favorited
-}
+import 'snice/components/product-card/snice-product-card';
 ```
 
-#### `quick-view`
-Fired when the quick view overlay is clicked.
-
-**Event Detail:** `void`
-
-## CSS Parts
-
-| Part | Description |
-|------|-------------|
-| `base` | The outer card container |
-| `gallery` | Image gallery area |
-| `body` | Card body content |
-| `title` | Product name heading |
-| `rating` | Star rating area |
-| `price` | Price display area |
-| `variants` | Variant selectors area |
-| `cta` | Add-to-cart button |
-| `stock` | Stock status indicator |
-| `badge` | Product badge (SALE, NEW, etc.) |
-| `favorite-btn` | Favorite/heart button |
-| `image` | Gallery image element |
-| `stars` | Star rating container |
-| `price-current` | Current price display |
-| `price-original` | Original price (strikethrough on sale) |
-| `discount` | Discount percentage badge |
-| `variant-group` | Variant selector group |
-| `variant-option` | Individual variant option button |
-
-## Basic Usage
-
 ```html
 <snice-product-card
   name="Running Shoes"
   price="129.99"
   rating="4.5"
-  review-count="342">
+  review-count="342"
+  in-stock>
 </snice-product-card>
 ```
 
-```typescript
-import 'snice/components/product-card/snice-product-card';
-```
-
 ## Examples
 
 ### Sale Price
@@ -154,77 +92,40 @@ import 'snice/components/product-card/snice-product-card';
 Use the `sale-price` attribute to display a sale with the original price crossed out and a discount badge.
 
 ```html
-<snice-product-card
-  name="Premium Sneakers"
-  price="149.99"
-  sale-price="99.99"
-  rating="4.5"
-  review-count="128">
-</snice-product-card>
+<snice-product-card name="Premium Sneakers" price="149.99" sale-price="99.99" rating="4.5" review-count="128"></snice-product-card>
 ```
 
 ### Multiple Images
 
 Set the `images` property to enable gallery navigation with prev/next buttons and dots.
 
-```html
-<snice-product-card id="shoe" name="Athletic Shoes" price="89.99"></snice-product-card>
-
-<script type="module">
-  const card = document.getElementById('shoe');
-  card.images = ['front.jpg', 'side.jpg', 'back.jpg', 'detail.jpg'];
-</script>
+```typescript
+card.images = ['front.jpg', 'side.jpg', 'back.jpg', 'detail.jpg'];
 ```
 
 ### Variant Selectors
 
-Set the `variants` property to add size chips and color swatches.
-
-```html
-<snice-product-card id="tshirt" name="Classic T-Shirt" price="29.99"></snice-product-card>
-
-<script type="module">
-  const card = document.getElementById('tshirt');
-  card.images = ['tshirt.jpg'];
-  card.variants = [
-    { type: 'Size', options: ['XS', 'S', 'M', 'L', 'XL'] },
-    { type: 'Color', options: ['#1a1a2e', '#e94560', '#0f3460', '#ffffff'] }
-  ];
-
-  card.addEventListener('variant-select', (e) => {
-    console.log(`Selected ${e.detail.type}: ${e.detail.value}`);
-  });
-</script>
-```
-
-### Horizontal Layout
+Set the `variants` property to add size chips and color swatches. Color variants (type "Color") render as swatches.
 
-Use `variant="horizontal"` for a side-by-side layout suited to wider containers.
+```typescript
+card.variants = [
+  { type: 'Size', options: ['XS', 'S', 'M', 'L', 'XL'] },
+  { type: 'Color', options: ['#1a1a2e', '#e94560', '#0f3460', '#ffffff'] }
+];
 
-```html
-<snice-product-card
-  variant="horizontal"
-  name="MacBook Pro"
-  price="2499.00"
-  sale-price="2199.00"
-  rating="4.9"
-  review-count="1024">
-</snice-product-card>
+card.addEventListener('variant-select', (e) => {
+  console.log(`Selected ${e.detail.type}: ${e.detail.value}`);
+});
 ```
 
-### Compact Layout
+### Layout Variants
 
-Use `variant="compact"` for a minimal row layout suited to lists and sidebars.
+Use the `variant` attribute to change the card layout.
 
 ```html
-<snice-product-card
-  variant="compact"
-  name="Wireless Earbuds"
-  price="59.99"
-  sale-price="39.99"
-  rating="4.2"
-  review-count="89">
-</snice-product-card>
+<snice-product-card variant="vertical" name="Product" price="29.99"></snice-product-card>
+<snice-product-card variant="horizontal" name="Product" price="29.99"></snice-product-card>
+<snice-product-card variant="compact" name="Product" price="29.99"></snice-product-card>
 ```
 
 ### Out of Stock
@@ -232,36 +133,32 @@ Use `variant="compact"` for a minimal row layout suited to lists and sidebars.
 Set `in-stock="false"` to disable the add-to-cart button and show an out-of-stock indicator.
 
 ```html
-<snice-product-card
-  name="Limited Edition Watch"
-  price="599.00"
-  in-stock="false"
-  rating="4.8"
-  review-count="56">
-</snice-product-card>
+<snice-product-card name="Limited Edition Watch" price="599.00" in-stock="false"></snice-product-card>
 ```
 
 ### Handling Add to Cart
 
-```html
-<snice-product-card id="product" name="Headphones" price="199.99"></snice-product-card>
-
-<script type="module">
-  const card = document.getElementById('product');
-  card.images = ['headphones.jpg'];
-  card.variants = [{ type: 'Color', options: ['#000000', '#ffffff', '#c0c0c0'] }];
-
-  card.addEventListener('add-to-cart', (e) => {
-    const { name, price, selectedVariants } = e.detail;
-    console.log(`Adding ${name} at $${price}`, selectedVariants);
-  });
-</script>
+```typescript
+card.addEventListener('add-to-cart', (e) => {
+  const { name, price, selectedVariants } = e.detail;
+  console.log(`Adding ${name} at $${price}`, selectedVariants);
+});
 ```
 
 ## Accessibility
 
-- **Star rating**: Includes `aria-label` with numeric rating
-- **Variant selectors**: Use `role="radiogroup"` and `role="radio"` with `aria-checked`
-- **Gallery navigation**: Previous/next buttons have `aria-label` attributes
-- **Out of stock**: CTA button is disabled with appropriate state
-- **Keyboard navigation**: All interactive elements are focusable and keyboard-accessible
+- Star rating includes `aria-label` with numeric rating value
+- Variant selectors use `role="radiogroup"` and `role="radio"` with `aria-checked`
+- Gallery navigation buttons have `aria-label` attributes
+- Favorite button has a descriptive `aria-label`
+- Out-of-stock state disables the CTA button
+- All interactive elements are keyboard-focusable
+
+## Data Types
+
+```typescript
+interface ProductVariant {
+  type: string;                    // Variant group name, e.g. 'Size', 'Color'
+  options: string[];               // Available options, e.g. ['S', 'M', 'L']
+}
+```

package/docs/components/progress-ring.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/progress-ring.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/progress-ring.md -->
 
 # Progress Ring
 `<snice-progress-ring>`
 
 A determinate circular progress indicator that displays progress as an animated SVG ring fill with optional center text.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/progress-ring/snice-progress-ring';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-progress-ring.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -34,18 +29,20 @@ import 'snice/components/progress-ring/snice-progress-ring';
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `progress-complete` | `{ value: number, max: number, component: SniceProgressRingElement }` | Fired when value reaches max |
+| `progress-complete` | `{ value: number, max: number, component }` | Fired when value reaches max |
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `base` | Outer container with `role="progressbar"` |
-| `track` | Background circle |
-| `fill` | Progress circle |
-| `center` | Center text container |
-| `value` | Percentage text |
-| `label` | Label text |
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | Outer container with `role="progressbar"` |
+| `track` | `<circle>` | Background circle |
+| `fill` | `<circle>` | Progress circle |
+| `center` | `<div>` | Center text container |
+| `value` | `<span>` | Percentage text |
+| `label` | `<span>` | Label text |
 
 ## Basic Usage
 
@@ -69,7 +66,7 @@ Set the `show-value` attribute to display the percentage in the center of the ri
 
 ### Custom Label
 
-Use the `label` attribute to display custom text in the center instead of (or alongside) the percentage.
+Use the `label` attribute to display custom text in the center.
 
 ```html
 <snice-progress-ring value="60" label="CPU" show-value></snice-progress-ring>
@@ -115,13 +112,13 @@ Use the `max` attribute to set a maximum value other than 100.
 
 Listen to the `progress-complete` event to react when progress reaches the maximum.
 
-```html
-<snice-progress-ring id="upload" value="0" max="100" show-value></snice-progress-ring>
-
-<script>
-  const ring = document.getElementById('upload');
-  ring.addEventListener('progress-complete', () => {
-    console.log('Upload complete!');
-  });
-</script>
+```typescript
+ring.addEventListener('progress-complete', () => {
+  console.log('Upload complete!');
+});
 ```
+
+## Accessibility
+
+- Uses `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- Label or percentage text is used as `aria-label` for screen readers

package/docs/components/progress.md

@@ -1,22 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/progress.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/progress.md -->
 
 # Progress
 `<snice-progress>`
 
-A progress indicator with linear and circular display variants.
+A progress indicator with linear and circular display variants, indeterminate mode, striped/animated styles, and optional labels.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/progress/snice-progress';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-progress.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [CSS Custom Properties](#css-custom-properties)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -30,7 +27,7 @@ import 'snice/components/progress/snice-progress';
 | `indeterminate` | `boolean` | `false` | Unknown progress mode |
 | `showLabel` (attr: `show-label`) | `boolean` | `false` | Show percentage label |
 | `label` | `string` | `''` | Custom label text (overrides percentage) |
-| `striped` | `boolean` | `false` | Striped bar pattern |
+| `striped` | `boolean` | `false` | Striped bar pattern (linear only) |
 | `animated` | `boolean` | `false` | Animate striped pattern |
 | `thickness` | `number` | `4` | Stroke width for circular variant |
 
@@ -45,13 +42,13 @@ import 'snice/components/progress/snice-progress';
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `progress-change` | `{ value: number, max: number, percentage: number, indeterminate: boolean }` | Fired when value, max, or indeterminate changes |
+| `progress-change` | `{ value, max, percentage, indeterminate }` | Fired when value, max, or indeterminate changes |
 
 ## CSS Parts
 
 Style internal elements from outside the shadow DOM using `::part()`.
 
-### Linear variant
+### Linear Variant
 
 | Part | Element | Description |
 |------|---------|-------------|
@@ -59,7 +56,7 @@ Style internal elements from outside the shadow DOM using `::part()`.
 | `bar` | `<div>` | The progress bar fill |
 | `label` | `<span>` | Percentage or custom label text |
 
-### Circular variant
+### Circular Variant
 
 | Part | Element | Description |
 |------|---------|-------------|
@@ -69,19 +66,15 @@ Style internal elements from outside the shadow DOM using `::part()`.
 | `circle-bar` | `<circle>` | Foreground progress arc |
 | `label` | `<div>` | Percentage or custom label text |
 
-```css
-snice-progress::part(bar) {
-  border-radius: 0;
-}
+## CSS Custom Properties
 
-snice-progress::part(label) {
-  font-weight: 700;
-}
-
-snice-progress::part(circle-bar) {
-  filter: drop-shadow(0 0 4px currentColor);
-}
-```
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--progress-height` | Bar height (linear) | `0.5rem` |
+| `--progress-radius` | Bar border radius | `4px` |
+| `--progress-bg` | Background track color | `var(--snice-color-border)` |
+| `--progress-color` | Progress fill color | `var(--snice-color-primary)` |
+| `--progress-animation-duration` | Animation speed | `1.5s` |
 
 ## Basic Usage
 
@@ -113,8 +106,6 @@ Use the `size` attribute to change the progress indicator size.
 <snice-progress value="50" size="medium"></snice-progress>
 <snice-progress value="50" size="large"></snice-progress>
 <snice-progress value="50" size="xl" variant="circular"></snice-progress>
-<snice-progress value="50" size="xxl" variant="circular"></snice-progress>
-<snice-progress value="50" size="xxxl" variant="circular"></snice-progress>
 ```
 
 ### Colors
@@ -126,7 +117,6 @@ Use the `color` attribute with semantic names or any CSS color value.
 <snice-progress value="80" color="success"></snice-progress>
 <snice-progress value="80" color="warning"></snice-progress>
 <snice-progress value="80" color="error"></snice-progress>
-<snice-progress value="80" color="info"></snice-progress>
 <snice-progress value="80" color="#3b82f6"></snice-progress>
 ```
 
@@ -141,7 +131,7 @@ Set the `indeterminate` attribute for unknown progress (loading state).
 
 ### With Label
 
-Use the `show-label` attribute to display the percentage, or `label` for custom text.
+Use `show-label` to display the percentage, or `label` for custom text.
 
 ```html
 <snice-progress value="60" show-label></snice-progress>
@@ -157,14 +147,6 @@ Use `striped` for a striped pattern and `animated` for animated stripes.
 <snice-progress value="70" striped animated></snice-progress>
 ```
 
-### Custom Max
-
-Use the `max` attribute to set a custom maximum value.
-
-```html
-<snice-progress value="3" max="10"></snice-progress>
-```
-
 ### Circular Thickness
 
 Use the `thickness` attribute to control the circular variant's stroke width.
@@ -173,28 +155,15 @@ Use the `thickness` attribute to control the circular variant's stroke width.
 <snice-progress variant="circular" value="75" thickness="8" size="xl"></snice-progress>
 ```
 
-### Dynamic Updates
-
-```html
-<snice-progress value="0"></snice-progress>
-```
-
-```typescript
-let value = 0;
-
-setInterval(() => {
-  value = (value + 10) % 100;
-  progress.value = value;
-}, 500);
-```
-
 ### Programmatic Control
 
 ```typescript
-// Set progress
 progress.setProgress(75);
 progress.setProgress(3, 10); // value 3, max 10
-
-// Get percentage
-console.log(progress.getPercentage()); // 75
+console.log(progress.getPercentage()); // 30
 ```
+
+## Accessibility
+
+- Uses `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+- Label text is used as `aria-label` for screen readers