snice 4.27.0 → 4.29.0

package/docs/components/carousel.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/carousel.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/carousel.md -->
 
-# Carousel
-`<snice-carousel>`
+# Carousel Component
 
-Content carousel with autoplay, looping, navigation controls, and multi-slide views.
+Content carousel with autoplay, looping, navigation controls, slide indicators, and multi-slide views.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/carousel/snice-carousel';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-carousel.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -36,11 +32,11 @@ import 'snice/components/carousel/snice-carousel';
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `next()` | — | Advance to the next slide |
-| `prev()` | — | Go to the previous slide |
+| `next()` | -- | Advance to the next slide |
+| `prev()` | -- | Go to the previous slide |
 | `goToSlide()` | `index: number` | Navigate to a specific slide by index |
-| `play()` | — | Start autoplay |
-| `pause()` | — | Pause autoplay |
+| `play()` | -- | Start autoplay |
+| `pause()` | -- | Pause autoplay |
 
 ## Events
 
@@ -69,10 +65,6 @@ import 'snice/components/carousel/snice-carousel';
 
 ## Basic Usage
 
-```typescript
-import 'snice/components/carousel/snice-carousel';
-```
-
 ```html
 <snice-carousel>
   <div>Slide 1</div>
@@ -81,11 +73,15 @@ import 'snice/components/carousel/snice-carousel';
 </snice-carousel>
 ```
 
+```typescript
+import 'snice/components/carousel/snice-carousel';
+```
+
 ## Examples
 
 ### Autoplay
 
-Set the `autoplay` attribute to automatically advance slides. Use `autoplay-interval` to control the timing in milliseconds.
+Set the `autoplay` attribute to automatically advance slides.
 
 ```html
 <snice-carousel autoplay autoplay-interval="2000">
@@ -95,18 +91,6 @@ Set the `autoplay` attribute to automatically advance slides. Use `autoplay-inte
 </snice-carousel>
 ```
 
-### Autoplay Direction
-
-Use `autoplay-direction` to reverse the autoplay direction.
-
-```html
-<snice-carousel autoplay autoplay-direction="backward">
-  <div>First</div>
-  <div>Second</div>
-  <div>Third</div>
-</snice-carousel>
-```
-
 ### Multiple Slides Per View
 
 Use `slides-per-view` to show multiple slides at once, and `space-between` for spacing.
@@ -123,7 +107,7 @@ Use `slides-per-view` to show multiple slides at once, and `space-between` for s
 
 ### Without Loop
 
-Set `loop` to `false` to disable infinite scrolling. Navigation buttons will be disabled at the start and end.
+Set `loop` to `false` to disable infinite scrolling.
 
 ```html
 <snice-carousel loop="false">
@@ -138,17 +122,10 @@ Set `loop` to `false` to disable infinite scrolling. Navigation buttons will be
 Use `show-controls` and `show-indicators` to toggle navigation elements.
 
 ```html
-<!-- No arrow buttons -->
 <snice-carousel show-controls="false">
   <div>Slide 1</div>
   <div>Slide 2</div>
 </snice-carousel>
-
-<!-- No indicator dots -->
-<snice-carousel show-indicators="false">
-  <div>Slide 1</div>
-  <div>Slide 2</div>
-</snice-carousel>
 ```
 
 ### Programmatic Control
@@ -172,7 +149,7 @@ Use methods to control the carousel from JavaScript.
 Listen for slide changes to synchronize other UI elements.
 
 ```typescript
-carousel.addEventListener('carousel-slide-change', (e: CustomEvent) => {
+carousel.addEventListener('carousel-slide-change', (e) => {
   console.log('Active slide:', e.detail.activeIndex);
   console.log('Previous slide:', e.detail.previousIndex);
 });
@@ -180,14 +157,13 @@ carousel.addEventListener('carousel-slide-change', (e: CustomEvent) => {
 
 ### Image Gallery
 
-A common pattern using the carousel for an image gallery.
+Use the carousel for an image gallery with styled slides.
 
 ```html
-<snice-carousel id="gallery" loop>
+<snice-carousel loop>
   <img src="/gallery/sunset.jpg" alt="Sunset over mountains">
   <img src="/gallery/ocean.jpg" alt="Ocean waves">
   <img src="/gallery/forest.jpg" alt="Forest trail">
-  <img src="/gallery/city.jpg" alt="City skyline">
 </snice-carousel>
 
 <style>
@@ -200,31 +176,8 @@ A common pattern using the carousel for an image gallery.
 </style>
 ```
 
-### Product Card Carousel
-
-Display product cards in a scrollable carousel.
+## Accessibility
 
-```html
-<snice-carousel slides-per-view="3" space-between="16" loop>
-  <div class="product-card">
-    <img src="/products/headphones.jpg" alt="Headphones">
-    <h3>Wireless Headphones</h3>
-    <p>$79.99</p>
-  </div>
-  <div class="product-card">
-    <img src="/products/keyboard.jpg" alt="Keyboard">
-    <h3>Mechanical Keyboard</h3>
-    <p>$129.99</p>
-  </div>
-  <div class="product-card">
-    <img src="/products/mouse.jpg" alt="Mouse">
-    <h3>Ergonomic Mouse</h3>
-    <p>$49.99</p>
-  </div>
-  <div class="product-card">
-    <img src="/products/monitor.jpg" alt="Monitor">
-    <h3>4K Monitor</h3>
-    <p>$399.99</p>
-  </div>
-</snice-carousel>
-```
+- Keyboard navigation with arrow keys
+- ARIA roles and labels for controls and indicators
+- Focus management between slides

package/docs/components/cart.md

@@ -1,11 +1,10 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/cart.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/cart.md -->
 
 # Cart Component
 
-The cart component displays a shopping cart summary with line items, quantity controls, coupon field, tax and discount calculations, and a checkout button.
+Shopping cart summary with line items, quantity controls, coupon field, tax and discount calculations, and a checkout button.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
@@ -14,39 +13,26 @@ The cart component displays a shopping cart summary with line items, quantity co
 - [Examples](#examples)
 - [Accessibility](#accessibility)
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/cart/snice-cart';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-cart.min.js"></script>
-```
-
 ## Properties
 
-| Property | Attribute | Type | Default | Description |
-|----------|-----------|------|---------|-------------|
-| `items` | — | `CartItem[]` | `[]` | Cart line items |
-| `currency` | `currency` | `string` | `'$'` | Currency symbol |
-| `taxRate` | `tax-rate` | `number` | `0` | Tax rate percentage |
-| `discount` | `discount` | `number` | `0` | Discount amount |
-| `couponCode` | `coupon-code` | `string` | `''` | Applied coupon code |
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `items` | `CartItem[]` | `[]` | Cart line items (property only) |
+| `currency` | `string` | `'$'` | Currency symbol |
+| `taxRate` (attr: `tax-rate`) | `number` | `0` | Tax rate percentage |
+| `discount` | `number` | `0` | Discount amount |
+| `couponCode` (attr: `coupon-code`) | `string` | `''` | Applied coupon code |
 
 ### CartItem Interface
 
 ```typescript
 interface CartItem {
-  id: string;          // Unique item identifier
-  name: string;        // Item display name
-  image?: string;      // Thumbnail URL
-  price: number;       // Unit price
-  quantity: number;     // Item quantity
-  variant?: string;    // Variant description, e.g. 'Size: M, Color: Black'
+  id: string;
+  name: string;
+  image?: string;
+  price: number;
+  quantity: number;
+  variant?: string;    // e.g. 'Size: M, Color: Black'
 }
 ```
 
@@ -54,69 +40,21 @@ interface CartItem {
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `addItem(item)` | `item: CartItem` | Adds an item to the cart. If an item with the same `id` exists, increments its quantity. |
-| `removeItem(id)` | `id: string` | Removes an item by its ID |
-| `updateQuantity(id, qty)` | `id: string, qty: number` | Sets the quantity of an item. Removes the item if qty is 0 or less. |
-| `applyCoupon(code)` | `code: string` | Applies a coupon code and fires the `coupon-apply` event |
-| `clear()` | — | Removes all items from the cart |
+| `addItem()` | `item: CartItem` | Add item (increments quantity if item with same `id` exists) |
+| `removeItem()` | `id: string` | Remove item by ID |
+| `updateQuantity()` | `id: string, qty: number` | Set quantity (removes item if qty <= 0) |
+| `applyCoupon()` | `code: string` | Apply coupon code and fire `coupon-apply` event |
+| `clear()` | -- | Remove all items |
 
 ## Events
 
-#### `item-add`
-Fired when a new item is added to the cart.
-
-**Event Detail:**
-```typescript
-{
-  item: CartItem;  // The added item
-}
-```
-
-#### `item-remove`
-Fired when an item is removed from the cart.
-
-**Event Detail:**
-```typescript
-{
-  item: CartItem;  // The removed item
-}
-```
-
-#### `quantity-change`
-Fired when an item's quantity changes.
-
-**Event Detail:**
-```typescript
-{
-  item: CartItem;         // The item (with new quantity)
-  previousQuantity: number;
-  newQuantity: number;
-}
-```
-
-#### `coupon-apply`
-Fired when a coupon code is applied.
-
-**Event Detail:**
-```typescript
-{
-  code: string;  // The coupon code
-}
-```
-
-#### `checkout`
-Fired when the checkout button is clicked.
-
-**Event Detail:**
-```typescript
-{
-  items: CartItem[];     // All cart items
-  subtotal: number;      // Sum of (price * quantity)
-  discount: number;      // Discount amount
-  tax: number;           // Calculated tax
-  total: number;         // Final total
-}
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `item-add` | `{ item: CartItem }` | Item added to cart |
+| `item-remove` | `{ item: CartItem }` | Item removed from cart |
+| `quantity-change` | `{ item: CartItem, previousQuantity: number, newQuantity: number }` | Item quantity changed |
+| `coupon-apply` | `{ code: string }` | Coupon code applied |
+| `checkout` | `{ items: CartItem[], subtotal: number, discount: number, tax: number, total: number }` | Checkout button clicked |
 
 ## CSS Parts
 
@@ -151,8 +89,6 @@ Set the `items` property to populate the cart.
 <snice-cart id="my-cart" tax-rate="8.5"></snice-cart>
 
 <script type="module">
-  import 'snice/components/cart/snice-cart';
-
   const cart = document.getElementById('my-cart');
   cart.items = [
     { id: '1', name: 'Running Shoes', image: 'shoes.jpg', price: 89.99, quantity: 1, variant: 'Size: 10' },
@@ -167,62 +103,34 @@ Set the `items` property to populate the cart.
 Set `discount` and `coupon-code` to show a discount row.
 
 ```html
-<snice-cart id="discount-cart" discount="10" coupon-code="SAVE10" tax-rate="5"></snice-cart>
-
-<script type="module">
-  const cart = document.getElementById('discount-cart');
-  cart.items = [
-    { id: '1', name: 'Laptop Stand', price: 45.00, quantity: 1 },
-    { id: '2', name: 'USB-C Hub', price: 35.00, quantity: 1 }
-  ];
-</script>
+<snice-cart discount="10" coupon-code="SAVE10" tax-rate="5"></snice-cart>
 ```
 
 ### Programmatic Cart Management
 
-Use the cart methods to add, remove, and update items.
+Use methods to add, remove, and update items.
 
-```html
-<snice-cart id="cart"></snice-cart>
-
-<script type="module">
-  const cart = document.getElementById('cart');
-
-  // Add items
-  cart.addItem({ id: 'shoe', name: 'Sneakers', price: 79.99, quantity: 1 });
-  cart.addItem({ id: 'sock', name: 'Socks (3-pack)', price: 12.99, quantity: 2 });
-
-  // Update quantity
-  cart.updateQuantity('sock', 4);
-
-  // Apply coupon
-  cart.applyCoupon('SPRING20');
-</script>
+```javascript
+cart.addItem({ id: 'shoe', name: 'Sneakers', price: 79.99, quantity: 1 });
+cart.addItem({ id: 'sock', name: 'Socks (3-pack)', price: 12.99, quantity: 2 });
+cart.updateQuantity('sock', 4);
+cart.applyCoupon('SPRING20');
 ```
 
 ### Handling Checkout
 
-```html
-<snice-cart id="checkout-cart" tax-rate="8.5"></snice-cart>
-
-<script type="module">
-  const cart = document.getElementById('checkout-cart');
-  cart.items = [
-    { id: '1', name: 'Product A', price: 49.99, quantity: 2 },
-    { id: '2', name: 'Product B', price: 29.99, quantity: 1 }
-  ];
+Listen for the `checkout` event to process orders.
 
-  cart.addEventListener('checkout', (e) => {
-    const { items, subtotal, tax, total } = e.detail;
-    console.log(`Checkout: ${items.length} items, Total: $${total.toFixed(2)}`);
-    // Navigate to checkout page
-  });
-</script>
+```javascript
+cart.addEventListener('checkout', (e) => {
+  const { items, subtotal, tax, total } = e.detail;
+  console.log(`Checkout: ${items.length} items, Total: $${total.toFixed(2)}`);
+});
 ```
 
 ## Accessibility
 
-- **Quantity controls**: Increment/decrement buttons have descriptive `aria-label` attributes
-- **Remove buttons**: Include the item name in the `aria-label` for clarity
-- **Keyboard navigation**: All controls are focusable and operable via keyboard
-- **Semantic structure**: Items are rendered in an unordered list with proper heading hierarchy
+- Quantity controls have descriptive `aria-label` attributes
+- Remove buttons include the item name in the `aria-label`
+- All controls are focusable and keyboard operable
+- Semantic list structure with proper heading hierarchy