snice 4.27.0 → 4.29.0

package/docs/ai/components/drawer.md

@@ -5,13 +5,13 @@ Slide-out panel from any viewport side with focus trap and dismissal options. Su
 ## Properties
 
 ```typescript
-open: boolean = false;                         // Visibility state
+open: boolean = false;
 position: 'left'|'right'|'top'|'bottom' = 'left';
 size: 'small'|'medium'|'large'|'xl'|'xxl'|'xxxl'|'full' = 'medium';
 inline: boolean = false;                       // Sit in document flow (no overlay/backdrop/focus-trap)
 breakpoint: number = 0;                        // Viewport px width: above → inline, below → overlay
-noHeader: boolean = false;                      // attribute: no-header — hide header entirely
-noFooter: boolean = false;                      // attribute: no-footer — hide footer entirely
+noHeader: boolean = false;                     // attribute: no-header
+noFooter: boolean = false;                     // attribute: no-footer
 noBackdrop: boolean = false;                   // attribute: no-backdrop
 noBackdropDismiss: boolean = false;            // attribute: no-backdrop-dismiss
 noEscapeDismiss: boolean = false;              // attribute: no-escape-dismiss
@@ -23,30 +23,42 @@ contained: boolean = false;                    // Position relative to parent
 
 ## Methods
 
-```typescript
-show()    // Open drawer
-hide()    // Close drawer
-toggle()  // Toggle drawer
-```
+- `show()` - Open drawer
+- `hide()` - Close drawer
+- `toggle()` - Toggle drawer
 
 ## Events
 
-```typescript
-'drawer-open'   // { drawer }
-'drawer-close'  // { drawer }
-```
+- `drawer-open` → `{ drawer }` - Drawer opened
+- `drawer-close` → `{ drawer }` - Drawer closed
 
 ## Slots
 
-```html
-<snice-drawer>
-  <h2 slot="title">Title</h2>
-  <div>Body content</div>
-  <div slot="footer">Actions</div>
-</snice-drawer>
-```
+- `(default)` - Body content
+- `title` - Header title text
+- `footer` - Footer actions
+
+## CSS Custom Properties
+
+- `--drawer-width-small` through `--drawer-width-xxxl` - Width per size
+- `--drawer-height-small` through `--drawer-height-xxxl` - Height per size (top/bottom)
+- `--drawer-bg` - Background (default: `var(--snice-color-background, white)`)
+- `--drawer-shadow` - Shadow (default: `var(--snice-shadow-lg)`)
+- `--drawer-backdrop` - Backdrop color (default: `rgba(0, 0, 0, 0.5)`)
+- `--drawer-transition` - Transition timing
+- `--drawer-z-index` - Z-index (default: `1050`)
+
+## CSS Parts
+
+- `backdrop` - Backdrop overlay
+- `base` - Drawer panel container
+- `header` - Header section
+- `title` - Title wrapper (h2)
+- `close` - Close button
+- `body` - Body content section
+- `footer` - Footer section
 
-## Usage
+## Basic Usage
 
 ```html
 <snice-drawer id="menu" position="left">
@@ -66,10 +78,9 @@ drawer.toggle();
 
 ## Inline Mode
 
-Renders in document flow — no overlay, backdrop, focus trap, or escape handler. Drawer panel is always visible.
+Renders in document flow — no overlay, backdrop, focus trap, or escape handler.
 
 ```html
-<!-- Always-visible sidebar -->
 <div style="display:flex; height:100vh">
   <snice-drawer inline position="left" size="small">
     <span slot="title">Sidebar</span>
@@ -79,73 +90,33 @@ Renders in document flow — no overlay, backdrop, focus trap, or escape handler
 </div>
 ```
 
-- CSS uses border separator instead of box-shadow
-- `open` property is ignored (always visible)
-- Border direction matches `position` (left→border-right, right→border-left, etc.)
-
 ## Breakpoint Mode
 
-Responsive switching: inline above the breakpoint, overlay below. Uses `window.matchMedia`.
+Responsive: inline above breakpoint, overlay below. Uses `window.matchMedia`.
 
 ```html
-<!-- Inline on desktop (≥768px), overlay on mobile (<768px) -->
-<snice-drawer breakpoint="768" position="left" size="small">
-  <span slot="title">Navigation</span>
-  ...
-</snice-drawer>
+<snice-drawer breakpoint="768" position="left" size="small">...</snice-drawer>
 ```
 
-- Sets/removes the `inline` attribute dynamically via matchMedia listener
-- Crossing the breakpoint while open: overlay behaviors torn down/set up automatically
-- Listener cleaned up on `@dispose()`
-- `@watch('breakpoint')` tears down old listener and sets up new one when value changes
-
 ## Push Content with `<snice-drawer-target>`
 
-Use `<snice-drawer-target>` to wrap content that should be pushed when a drawer opens. The target watches the drawer's `[open]` attribute via MutationObserver and applies a `translateX()` or `translateY()` transform.
-
-```typescript
-// snice-drawer-target properties
-for: string = '';   // ID of the linked drawer
-push: string = '';  // Current push amount (e.g. '240px'), set automatically
-```
-
 ```html
-<snice-drawer id="nav" position="left" size="small" contained push-content>
-  <span slot="title">Nav</span>
-</snice-drawer>
+<snice-drawer id="nav" position="left" size="small" contained push-content>...</snice-drawer>
 <snice-drawer-target for="nav">
-  <main>This content slides when drawer opens</main>
+  <main>Content slides when drawer opens</main>
 </snice-drawer-target>
 ```
 
-- Target measures drawer panel width/height directly via `shadowRoot.querySelector('.drawer').offsetWidth`
-- Left/right drawers → `translateX`, top/bottom → `translateY`
-- Transition: `transform 0.3s cubic-bezier(0.4, 0, 0.2, 1)`
-- Resets parent `scrollLeft`/`scrollTop` after transform change (prevents `overflow:hidden` scroll bug)
-- Cleanup on disconnect via `@dispose()`
-
-## Features
-
-- Slides from any edge (left, right, top, bottom)
-- Multiple size options
-- Focus trap with Tab navigation
-- Focus restoration on close
-- Backdrop click to close
-- Escape key to close
-- Push content mode via `<snice-drawer-target>`
-- Persistent mode (no close button)
-- Inline mode (persistent sidebar in document flow)
-- Breakpoint mode (responsive inline ↔ overlay switching)
-- Contained mode uses `overflow: clip` to prevent scroll bugs during transform animations
-- ARIA attributes (role, aria-modal, aria-hidden)
+Target properties: `for: string` (drawer ID), `push: string` (auto-set amount).
 
-## CSS Parts
+## Keyboard Navigation
 
-- `backdrop` - Backdrop overlay
-- `base` - The drawer panel container
-- `header` - Header section
-- `title` - Title wrapper (h2)
-- `close` - Close button
-- `body` - Body content section
-- `footer` - Footer section
+- Escape closes drawer (unless no-escape-dismiss/persistent)
+- Tab/Shift+Tab cycles focusable elements (focus trapped)
+
+## Accessibility
+
+- role=dialog, aria-modal=true on drawer
+- aria-hidden reflects visibility
+- Focus trap + focus restoration
+- Contained mode skips focus trap and body scroll lock

package/docs/ai/components/empty-state.md

@@ -13,15 +13,15 @@ actionText: string = '';       // attribute: action-text
 actionHref: string = '';       // attribute: action-href
 ```
 
+## Events
+
+- `empty-state-action` → `{ emptyState: SniceEmptyStateElement }`
+
 ## Slots
 
 - `icon` - Custom icon content (overrides `icon` property)
 - (default) - Custom content below the action button
 
-## Events
-
-- `empty-state-action` → `{ emptyState }`
-
 ## CSS Parts
 
 - `container` - Outer empty state wrapper
@@ -30,39 +30,25 @@ actionHref: string = '';       // attribute: action-href
 - `description` - Description paragraph
 - `action` - Action button or link
 
-## Usage
+## Basic Usage
 
-```html
-<!-- Basic -->
-<snice-empty-state></snice-empty-state>
+```typescript
+import 'snice/components/empty-state/snice-empty-state';
+```
 
-<!-- Custom (icon supports: URL, image files, emoji, text) -->
+```html
 <snice-empty-state
   icon="🔍"
   title="No results found"
   description="Try adjusting your search"
+  action-text="Clear Search"
 ></snice-empty-state>
 
-<!-- ⚠️ icon="search_off" renders as PLAIN TEXT. Use the icon slot for icon fonts. -->
-
 <!-- Icon SLOT — for Material Symbols, Font Awesome, SVGs -->
 <snice-empty-state title="No results">
   <span slot="icon" class="material-symbols-outlined" style="font-size: 4rem;">search_off</span>
 </snice-empty-state>
 
-<!-- Icon PROPERTY — for emoji, URLs, image files only -->
-<snice-empty-state
-  icon="/icons/empty.svg"
-  title="No items"
-></snice-empty-state>
-
-<!-- With action -->
-<snice-empty-state
-  title="No items yet"
-  description="Get started by creating your first item"
-  action-text="Create Item"
-></snice-empty-state>
-
 <!-- With link -->
 <snice-empty-state
   title="Page not found"
@@ -72,11 +58,7 @@ actionHref: string = '';       // attribute: action-href
 
 <!-- Sizes -->
 <snice-empty-state size="small"></snice-empty-state>
-<snice-empty-state size="medium"></snice-empty-state>
 <snice-empty-state size="large"></snice-empty-state>
-
-<!-- Events -->
-<snice-empty-state id="empty" action-text="Click"></snice-empty-state>
 ```
 
 ```typescript
@@ -84,19 +66,3 @@ empty.addEventListener('empty-state-action', () => {
   console.log('Action clicked');
 });
 ```
-
-```html
-
-<!-- Custom content -->
-<snice-empty-state title="No data">
-  <div>Custom HTML content here</div>
-</snice-empty-state>
-```
-
-## Features
-
-- Customizable icon (URL, image files, emoji), title, description. Use slot for icon fonts.
-- Optional action button or link
-- 3 sizes
-- Slot for custom content
-- Accessible

package/docs/ai/components/estimate.md

@@ -5,42 +5,34 @@ Professional estimate/quote document with from/to parties, line items, optional
 ## Properties
 
 ```typescript
-estimateNumber: string = ''              // attribute: estimate-number
-date: string = ''                        // Estimate date
-expiryDate: string = ''                  // attribute: expiry-date
-status: EstimateStatus = 'draft'         // 'draft' | 'sent' | 'accepted' | 'declined' | 'expired'
-currency: string = '$'                   // Currency symbol
-taxRate: number = 0                      // attribute: tax-rate — percentage
-discount: number = 0                     // Discount percentage
-notes: string = ''                       // Footer notes
-terms: string = ''                       // Terms & conditions
-variant: EstimateVariant = 'standard'    // 'standard' | 'comparison' | 'professional' | 'creative' | 'minimal'
-showQr: boolean = false                  // attribute: show-qr
-qrData: string = ''                      // attribute: qr-data
-qrPosition: QrPosition = 'top-right'     // attribute: qr-position — 'top-right' | 'bottom-right' | 'footer'
-from: EstimateParty | null = null        // Sender party data (JS only)
-to: EstimateParty | null = null          // Recipient party data (JS only)
-items: EstimateItem[] = []               // Line items (JS only)
+estimateNumber: string = '';              // attribute: estimate-number
+date: string = '';
+expiryDate: string = '';                  // attribute: expiry-date
+status: EstimateStatus = 'draft';         // 'draft'|'sent'|'accepted'|'declined'|'expired'
+currency: string = '$';
+taxRate: number = 0;                      // attribute: tax-rate
+discount: number = 0;
+notes: string = '';
+terms: string = '';
+variant: EstimateVariant = 'standard';    // 'standard'|'comparison'|'professional'|'creative'|'minimal'
+showQr: boolean = false;                  // attribute: show-qr
+qrData: string = '';                      // attribute: qr-data
+qrPosition: QrPosition = 'top-right';    // attribute: qr-position — 'top-right'|'bottom-right'|'footer'
+from: EstimateParty | null = null;        // JS only
+to: EstimateParty | null = null;          // JS only
+items: EstimateItem[] = [];               // JS only
 ```
 
-## Types
+## Methods
 
-```typescript
-interface EstimateParty {
-  name: string;
-  address?: string;
-  email?: string;
-  phone?: string;
-}
-
-interface EstimateItem {
-  description: string;
-  quantity: number;
-  unitPrice: number;
-  optional?: boolean;     // Item can be toggled on/off
-  included?: boolean;     // Whether optional item is included
-}
-```
+- `print()` - Trigger browser print
+- `toJSON(): EstimateJSON` - Returns full estimate data with computed totals
+
+## Events
+
+- `estimate-accept` → `{ estimateNumber: string; items: EstimateItem[]; total: number }`
+- `estimate-decline` → `{ estimateNumber: string }`
+- `item-toggle` → `{ index: number; item: EstimateItem; included: boolean }`
 
 ## Slots
 
@@ -48,26 +40,19 @@ interface EstimateItem {
 - `qr` - Custom QR code content
 - `footer` - Footer content
 
-## Events
-
-- `estimate-accept` → `{ estimateNumber: string; items: EstimateItem[]; total: number }`
-- `estimate-decline` → `{ estimateNumber: string }`
-- `item-toggle` → `{ index: number; item: EstimateItem; included: boolean }`
+## CSS Parts
 
-## Methods
+`base`, `header`, `logo`, `title`, `status`, `expiry`, `expiry-date`, `meta`, `parties`, `party`, `party-label`, `party-name`, `party-detail`, `table`, `table-header`, `table-row`, `table-cell`, `item-toggle`, `summary`, `subtotal`, `discount-row`, `tax-row`, `total`, `notes`, `notes-label`, `notes-content`, `terms`, `actions`, `accept-button`, `decline-button`, `footer`, `qr-container`, `qr`, `comparison`, `option`, `option-button`
 
-- `print()` - Trigger browser print
-- `toJSON()` - Returns full estimate data with computed totals
+## CSS Custom Properties
 
-## Variants
+`--estimate-max-width`, `--estimate-bg`, `--estimate-border`, `--estimate-text`, `--estimate-accent`, `--estimate-header-padding`, `--estimate-section-padding`, `--estimate-radius`, `--estimate-title-size`, `--estimate-accept-bg`, `--estimate-decline-text`, `--estimate-total-bg`, `--estimate-qr-size`
 
-- `standard` - Clean professional layout
-- `comparison` - Card-based option selector (one card per item)
-- `professional` - Dark header gradient, shadow, accent labels
-- `creative` - Gradient header, rounded pill buttons, vibrant colors
-- `minimal` - No borders/shadows, flat typography, reduced spacing
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/estimate/snice-estimate';
+```
 
 ```html
 <snice-estimate estimate-number="EST-001" date="2026-01-15" status="sent" tax-rate="10">
@@ -82,16 +67,6 @@ est.items = [
   { description: 'Brand Identity', quantity: 1, unitPrice: 5000 },
   { description: 'SEO Audit', quantity: 1, unitPrice: 1500, optional: true, included: false }
 ];
-est.terms = 'Payment due within 30 days';
-
 est.addEventListener('estimate-accept', e => console.log('Accepted:', e.detail));
 est.addEventListener('item-toggle', e => console.log('Item toggled:', e.detail));
 ```
-
-<!-- Comparison variant -->
-<snice-estimate variant="comparison"></snice-estimate>
-```
-
-## CSS Parts
-
-`base`, `header`, `logo`, `title`, `status`, `expiry`, `expiry-date`, `meta`, `parties`, `party`, `party-label`, `party-name`, `party-detail`, `table`, `table-header`, `table-row`, `table-cell`, `item-toggle`, `summary`, `subtotal`, `discount-row`, `tax-row`, `total`, `notes`, `notes-label`, `notes-content`, `terms`, `actions`, `accept-button`, `decline-button`, `footer`, `qr-container`, `qr`, `comparison`, `option`, `option-button`

package/docs/ai/components/file-gallery.md

@@ -18,128 +18,76 @@ autoUpload: boolean = true;    // attribute: auto-upload
 showDropzone: boolean = true;  // attribute: show-dropzone
 showAddButton: boolean = false; // attribute: show-add-button
 showHeader: boolean = true;     // attribute: show-header
-files: GalleryFile[];           // read-only
+files: GalleryFile[];           // read-only getter
 ```
 
-## Getters
+## Methods
 
+Getters:
 - `files: GalleryFile[]` - Get all files
 - `customActions: CustomAction[]` - Get all custom actions
-- `getFile(fileId): GalleryFile | undefined` - Get specific file
-- `getCustomAction(actionId): CustomAction | undefined` - Get specific action
-- `isPending(fileId): boolean` - Check if pending
-- `isUploading(fileId): boolean` - Check if uploading
-- `isPaused(fileId): boolean` - Check if paused
-- `isCompleted(fileId): boolean` - Check if completed
-- `hasError(fileId): boolean` - Check if has error
-- `canAddFiles(): boolean` - Check if can add more files
-
-## File Management
-
-- `addFiles(files: FileList | File[])` - Add files to gallery
-- `addFileWithPreview(file: File, previewDataUrl: string)` - Add file with preview
-- `removeFile(fileId: string)` - Remove file
-- `clear()` - Remove all files
-- `clearCompleted()` - Remove completed files
-- `clearErrors()` - Remove files with errors
-
-## Upload Control
-
-- `pauseUpload(fileId: string)` - Pause upload
-- `resumeUpload(fileId: string)` - Resume upload
-- `retryUpload(fileId: string)` - Retry failed upload
-- `cancelUpload(fileId: string)` - Cancel and remove upload
-- `pauseAll()` - Pause all uploading files
-- `resumeAll()` - Resume all paused files
-- `retryAll()` - Retry all errored files
-- `cancelAll()` - Cancel all active uploads
-
-## Custom Actions
-
-- `addCustomAction(icon: string, text: string): string` - Add custom action, returns actionId
-- `removeCustomAction(actionId: string)` - Remove action
-- `clearCustomActions()` - Remove all actions
-
-## Utility
-
-- `openFilePicker()` - Open file picker dialog
-- `setFileBadge(fileId: string, badge: string, position?: 'top-left'|'top-right'|'bottom-left'|'bottom-right')` - Add badge overlay to file preview (supports HTML)
-- `removeFileBadge(fileId: string)` - Remove badge from file
+- `getFile(fileId): GalleryFile | undefined`
+- `getCustomAction(actionId): CustomAction | undefined`
+- `isPending(fileId): boolean`
+- `isUploading(fileId): boolean`
+- `isPaused(fileId): boolean`
+- `isCompleted(fileId): boolean`
+- `hasError(fileId): boolean`
+- `canAddFiles(): boolean`
+
+File management:
+- `addFiles(files: FileList | File[])`
+- `addFileWithPreview(file: File, previewDataUrl: string)`
+- `removeFile(fileId: string)`
+- `clear()` / `clearCompleted()` / `clearErrors()`
+
+Upload control:
+- `pauseUpload(fileId)` / `resumeUpload(fileId)` / `retryUpload(fileId)` / `cancelUpload(fileId)`
+- `pauseAll()` / `resumeAll()` / `retryAll()` / `cancelAll()`
+
+Custom actions:
+- `addCustomAction(icon: string, text: string): string`
+- `removeCustomAction(actionId)` / `clearCustomActions()`
+
+Utility:
+- `openFilePicker()`
+- `setFileBadge(fileId, badge, position?)` / `removeFileBadge(fileId)`
 
 ## Events
 
-- `files-change` - {files, component}
-- `upload-progress` - {file, progress, component}
-- `upload-complete` - {file, response: UploadResponse, component}
-- `upload-error` - {file, error, component}
-- `upload-pause` - {file, component}
-- `file-remove` - {file, component}
-- `custom-action-click` - {actionId, component}
-- `gallery-error` - {message, component}
+- `files-change` → `{ files, component }`
+- `upload-progress` → `{ file, progress, component }`
+- `upload-complete` → `{ file, response: UploadResponse, component }`
+- `upload-error` → `{ file, error, component }`
+- `upload-pause` → `{ file, component }`
+- `file-remove` → `{ file, component }`
+- `custom-action-click` → `{ actionId, component }`
+- `gallery-error` → `{ message, component }`
 
-## Types
+## CSS Parts
 
-```typescript
-interface GalleryFile {
-  id: string;
-  file: File;
-  preview?: string;
-  uploadProgress: number;
-  uploadStatus: 'pending'|'uploading'|'paused'|'completed'|'error';
-  error?: string;
-  badge?: string; // HTML content for badge overlay
-  badgePosition?: 'top-left'|'top-right'|'bottom-left'|'bottom-right';
-}
-
-interface UploadRequest {
-  file: File;
-  fileId: string;
-  onProgress?: (progress: number) => void;
-  signal?: AbortSignal;
-}
-
-interface UploadResponse {
-  success: boolean;
-  fileId: string;
-  url?: string;
-  error?: string;
-}
-```
-
-**CSS Parts:**
-- `base` - Outer gallery container div
+- `base` - Outer gallery container
 - `dropzone` - Drag-and-drop upload zone
 - `gallery` - File thumbnails grid/list area
 
-## Upload Handler
-
-Uses `@request/@respond` pattern (`file-gallery-upload`). Handler receives `UploadRequest`, returns `UploadResponse`.
+## Basic Usage
 
-## Usage
+```typescript
+import 'snice/components/file-gallery/snice-file-gallery';
+```
 
 ```html
-<!-- Basic -->
 <snice-file-gallery></snice-file-gallery>
-
-<!-- Images only -->
 <snice-file-gallery accept="image/*"></snice-file-gallery>
-
-<!-- Manual upload -->
 <snice-file-gallery auto-upload="false"></snice-file-gallery>
-
-<!-- Limits -->
 <snice-file-gallery max-files="3" max-size="2097152"></snice-file-gallery>
-
-<!-- List view -->
 <snice-file-gallery view="list"></snice-file-gallery>
-
-<!-- Add button mode -->
-<snice-file-gallery show-dropzone="false" show-add-button="true" max-files="6"></snice-file-gallery>
-
-<!-- Events -->
+<snice-file-gallery show-dropzone="false" show-add-button="true"></snice-file-gallery>
 ```
 
 ```typescript
-gallery.addEventListener('files-change', (e) => console.log(e.detail.files));
-gallery.addEventListener('upload-complete', (e) => console.log(e.detail.response));
+gallery.addEventListener('files-change', e => console.log(e.detail.files));
+gallery.addEventListener('upload-complete', e => console.log(e.detail.response));
 ```
+
+Uses `@request/@respond` pattern (`file-gallery-upload`). Handler receives `UploadRequest { file, fileId, onProgress?, signal? }`, returns `UploadResponse { success, fileId, url?, error? }`.