snice 2.5.4 → 3.2.0

package/docs/ai/components/switch.md

@@ -0,0 +1,53 @@
+# snice-switch
+
+Toggle switch input for boolean selections.
+
+## Properties
+
+```typescript
+checked: boolean = false;        // Switch state
+disabled: boolean = false;       // Disabled state
+required: boolean = false;       // Form required
+invalid: boolean = false;        // Invalid state styling
+size: 'small'|'medium'|'large' = 'medium';
+name: string = '';              // Form field name
+value: string = 'on';           // Form field value when checked
+label: string = '';             // Label text
+labelOn: string = '';           // Label shown when on
+labelOff: string = '';          // Label shown when off
+```
+
+## Methods
+
+```typescript
+toggle()      // Toggle switch state
+focus()       // Focus the switch
+blur()        // Remove focus
+click()       // Programmatic click
+```
+
+## Events
+
+```typescript
+'@snice/switch-change' // { checked, switch }
+```
+
+## Usage
+
+```html
+<snice-switch label="Enable notifications"></snice-switch>
+```
+
+```typescript
+switchEl.addEventListener('@snice/switch-change', (e) => {
+  console.log(e.detail.checked);
+});
+```
+
+## CSS Parts
+
+```css
+::part(track)   // Switch track
+::part(thumb)   // Switch thumb
+::part(label)   // Label text
+```

package/docs/ai/components/table.md

@@ -0,0 +1,227 @@
+# snice-table, snice-row, snice-column, snice-cell, snice-header
+
+Data table with Excel-like formatting, sorting, pagination, and 15 column types.
+
+## snice-table
+
+```typescript
+size: 'small'|'medium'|'large' = 'medium';
+variant: 'default'|'striped'|'bordered' = 'default';
+striped: boolean = false;
+hoverable: boolean = false;
+bordered: boolean = false;
+stickyHeader: boolean = false;
+sortable: boolean = false;
+selectable: boolean = false;
+clickable: boolean = false;
+loading: boolean = false;
+data: any[] = [];
+columns: ColumnDefinition[] = [];
+showSearch: boolean = false;
+showPagination: boolean = false;
+pageSize: number = 10;
+currentPage: number = 1;
+totalItems: number = 0;
+```
+
+**Methods:**
+- `setData(data)` - Set table data
+- `sort(column)` - Sort by column
+- `getSelectedRows()` - Get selected rows
+- `search(query)` - Filter data
+- `goToPage(page)` - Navigate pagination
+
+**Events:**
+- `row-click` - {row, index}
+- `row-select` - {row, selected}
+- `sort` - {column, direction}
+- `page-change` - {page, pageSize}
+
+## Column Types
+
+15 specialized column types with formatting options:
+
+1. **text** - Plain text
+2. **number** - Formatted numbers (decimals, thousands separators, prefix/suffix)
+3. **date** - Date formatting (short/medium/long/full/custom)
+4. **boolean** - True/false with symbols or text
+5. **currency** - Currency formatting with locale and display options
+6. **percent** - Percentages with trends and colorization
+7. **rating** - Star ratings with custom symbols
+8. **progress** - Progress bars with percentage
+9. **sparkline** - Inline charts (line/bar/area)
+10. **accounting** - Accounting number format
+11. **scientific** - Scientific notation
+12. **fraction** - Fraction display
+13. **duration** - Time durations
+14. **filesize** - File size formatting
+15. **custom** - Custom formatter function
+
+## Column Definition
+
+```typescript
+interface ColumnDefinition {
+  key: string;
+  label: string;
+  type?: ColumnType;
+  align?: 'left'|'center'|'right';
+  width?: string;
+  sortable?: boolean;
+  filterable?: boolean;
+  formatter?: (value, row) => string;
+
+  // Excel-like formatting
+  numberFormat?: NumberFormat;
+  dateFormat?: DateFormat;
+  booleanFormat?: BooleanFormat;
+  ratingFormat?: RatingFormat;
+  progressFormat?: ProgressFormat;
+  sparklineFormat?: SparklineFormat;
+  percentageFormat?: PercentageFormat;
+  currencyFormat?: CurrencyFormat;
+
+  // Additional formats
+  phoneFormat?: PhoneFormat;
+  statusFormat?: StatusFormat;
+  tagFormat?: TagFormat;
+  actionsFormat?: ActionsFormat;
+  linkFormat?: LinkFormat;
+  colorFormat?: ColorFormat;
+  emailFormat?: EmailFormat;
+  imageFormat?: ImageFormat;
+  jsonFormat?: JsonFormat;
+  locationFormat?: LocationFormat;
+
+  // Cell styling
+  style?: CellStyle;
+  conditionalFormats?: ConditionalFormat[];
+
+  // Display options
+  wrap?: boolean;
+  ellipsis?: boolean;
+  tooltip?: boolean | ((value, row) => string);
+}
+```
+
+## Usage
+
+```html
+<!-- Basic table -->
+<snice-table id="table"></snice-table>
+
+<script>
+const table = document.querySelector('#table');
+
+table.columns = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'age', label: 'Age', type: 'number', align: 'right' },
+  { key: 'email', label: 'Email' }
+];
+
+table.data = [
+  { name: 'John', age: 30, email: 'john@example.com' },
+  { name: 'Jane', age: 25, email: 'jane@example.com' }
+];
+</script>
+
+<!-- Striped and hoverable -->
+<snice-table striped hoverable></snice-table>
+
+<!-- With sorting and selection -->
+<snice-table sortable selectable></snice-table>
+
+<!-- With pagination and search -->
+<snice-table show-pagination show-search page-size="20"></snice-table>
+
+<!-- Sticky header -->
+<snice-table sticky-header></snice-table>
+
+<!-- Advanced formatting -->
+<script>
+table.columns = [
+  {
+    key: 'price',
+    label: 'Price',
+    type: 'currency',
+    currencyFormat: { currency: 'USD', decimals: 2 }
+  },
+  {
+    key: 'progress',
+    label: 'Progress',
+    type: 'progress',
+    progressFormat: { max: 100, showPercentage: true }
+  },
+  {
+    key: 'rating',
+    label: 'Rating',
+    type: 'rating',
+    ratingFormat: { max: 5, symbol: '★' }
+  },
+  {
+    key: 'trend',
+    label: 'Trend',
+    type: 'sparkline',
+    sparklineFormat: { type: 'line', color: '#3b82f6' }
+  },
+  {
+    key: 'status',
+    label: 'Status',
+    type: 'boolean',
+    booleanFormat: { trueValue: 'Active', falseValue: 'Inactive', useSymbols: true }
+  }
+];
+</script>
+
+<!-- Conditional formatting -->
+<script>
+table.columns = [
+  {
+    key: 'score',
+    label: 'Score',
+    type: 'number',
+    conditionalFormats: [
+      {
+        condition: (val) => val >= 90,
+        style: { backgroundColor: '#dcfce7', color: '#166534' }
+      },
+      {
+        condition: (val) => val < 60,
+        style: { backgroundColor: '#fee2e2', color: '#991b1b' }
+      }
+    ]
+  }
+];
+</script>
+
+<!-- Event handling -->
+<script>
+table.addEventListener('row-click', (e) => {
+  console.log('Clicked row:', e.detail.row);
+});
+
+table.addEventListener('row-select', (e) => {
+  console.log('Selected:', e.detail.selected);
+});
+
+table.addEventListener('sort', (e) => {
+  console.log('Sort by:', e.detail.column, e.detail.direction);
+});
+</script>
+```
+
+## Features
+
+- 15 specialized column types
+- Excel-like formatting for numbers, dates, currencies
+- Visual formatters (progress bars, ratings, sparklines)
+- Conditional formatting with styles
+- Sorting and filtering
+- Row selection
+- Pagination and search
+- Sticky header
+- Custom cell formatters
+- Tooltips and ellipsis
+- Action buttons in cells
+- 3 sizes and variants
+- Loading state
+- Responsive and accessible

package/docs/ai/components/tabs.md

@@ -0,0 +1,83 @@
+# snice-tabs
+
+Tabbed interface with container, tab buttons, and content panels.
+
+## Components
+
+### snice-tabs (Container)
+
+```typescript
+selected: number = 0;                              // Active tab index
+placement: 'top'|'bottom'|'start'|'end' = 'top';  // Tab navigation position
+noScrollControls: boolean = false;                 // Hide scroll buttons
+transition: string = 'none';                       // Panel transition effect
+```
+
+**Methods:**
+```typescript
+selectTab(index: number)           // Select tab by index
+show(index: number)                 // Alias for selectTab
+getTab(index: number)               // Get tab element
+getPanel(index: number)             // Get panel element
+```
+
+**Events:**
+```typescript
+'@snice/tab-change' // { index, oldIndex, tab, panel }
+```
+
+### snice-tab (Tab Button)
+
+```typescript
+disabled: boolean = false;   // Disabled state
+closable: boolean = false;   // Show close button
+```
+
+**Methods:**
+```typescript
+focus()   // Focus the tab
+blur()    // Remove focus
+```
+
+**Events:**
+```typescript
+'@snice/tab-select' // { tab }
+'@snice/close'      // { tab }
+```
+
+### snice-tab-panel (Content Panel)
+
+```typescript
+name: string = '';                         // Panel identifier
+transitionIn: string = '';                 // Transition when showing
+transitionOut: string = '';                // Transition when hiding
+transitioning: 'in'|'out'|'' = '';        // Transition state
+transitionDuration: number = 300;          // Transition duration (ms)
+```
+
+## Usage
+
+```html
+<snice-tabs>
+  <snice-tab slot="nav">Tab 1</snice-tab>
+  <snice-tab slot="nav">Tab 2</snice-tab>
+
+  <snice-tab-panel>Content 1</snice-tab-panel>
+  <snice-tab-panel>Content 2</snice-tab-panel>
+</snice-tabs>
+```
+
+```typescript
+tabs.addEventListener('@snice/tab-change', (e) => {
+  console.log(e.detail.index);
+});
+
+tabs.selectTab(1);
+```
+
+## Notes
+
+- Tabs use `slot="nav"` attribute
+- Panels in default slot
+- Automatically manages ARIA attributes
+- Supports keyboard navigation

package/docs/ai/components/textarea.md

@@ -0,0 +1,87 @@
+# snice-textarea
+
+Multi-line text input field with auto-grow and character count.
+
+## Properties
+
+```typescript
+value: string = '';
+variant: 'outlined'|'filled'|'underlined' = 'outlined';
+size: 'small'|'medium'|'large' = 'medium';
+resize: 'none'|'vertical'|'horizontal'|'both' = 'vertical';
+placeholder: string = '';
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+label: string = '';
+helperText: string = '';
+errorText: string = '';
+rows: number = 3;
+cols: number = -1;
+minlength: number = -1;
+maxlength: number = -1;
+autocomplete: string = '';
+name: string = '';
+autoGrow: boolean = false;
+```
+
+## Methods
+
+- `focus()` - Focus textarea
+- `blur()` - Blur textarea
+- `select()` - Select text
+
+## Events
+
+- `input` - {value, textarea}
+- `change` - {value, textarea}
+- `focus` - {textarea}
+- `blur` - {textarea}
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-textarea label="Comments" placeholder="Enter comments"></snice-textarea>
+
+<!-- Variants -->
+<snice-textarea variant="outlined"></snice-textarea>
+<snice-textarea variant="filled"></snice-textarea>
+<snice-textarea variant="underlined"></snice-textarea>
+
+<!-- Rows -->
+<snice-textarea rows="5"></snice-textarea>
+
+<!-- Auto-grow -->
+<snice-textarea auto-grow></snice-textarea>
+
+<!-- Character count -->
+<snice-textarea maxlength="500"></snice-textarea>
+
+<!-- Resize options -->
+<snice-textarea resize="none"></snice-textarea>
+<snice-textarea resize="both"></snice-textarea>
+
+<!-- Sizes -->
+<snice-textarea size="small"></snice-textarea>
+<snice-textarea size="medium"></snice-textarea>
+<snice-textarea size="large"></snice-textarea>
+
+<!-- Helper text -->
+<snice-textarea helper-text="Max 500 characters"></snice-textarea>
+
+<!-- Error state -->
+<snice-textarea invalid error-text="Required field"></snice-textarea>
+```
+
+## Features
+
+- Form-associated custom element
+- 3 visual variants
+- Auto-grow height option
+- Character counter
+- Resizable (4 modes)
+- Helper and error text
+- 3 sizes
+- Keyboard accessible

package/docs/ai/components/timeline.md

@@ -0,0 +1,77 @@
+# snice-timeline
+
+Displays chronological events with markers.
+
+## Properties
+
+```typescript
+orientation: 'vertical'|'horizontal' = 'vertical';
+position: 'left'|'right'|'alternate' = 'left';
+items: TimelineItem[] = [];
+reverse: boolean = false;
+```
+
+## TimelineItem
+
+```typescript
+interface TimelineItem {
+  timestamp?: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  variant?: 'default'|'success'|'warning'|'error'|'info';
+}
+```
+
+## Usage
+
+```html
+<!-- Basic --><snice-timeline id="timeline"></snice-timeline>
+<script>
+timeline.items = [{
+  timestamp: '2024-01-15',
+  title: 'Event',
+  description: 'Details'
+}];
+</script>
+
+<!-- Vertical positions -->
+<snice-timeline position="left"></snice-timeline>
+<snice-timeline position="right"></snice-timeline>
+<snice-timeline position="alternate"></snice-timeline>
+
+<!-- Horizontal -->
+<snice-timeline orientation="horizontal"></snice-timeline>
+
+<!-- Variants -->
+<script>
+timeline.items = [
+  { title: 'Success', variant: 'success' },
+  { title: 'Warning', variant: 'warning' },
+  { title: 'Error', variant: 'error' },
+  { title: 'Info', variant: 'info' }
+];
+</script>
+
+<!-- Custom icons -->
+<script>
+timeline.items = [
+  { title: 'Planning', icon: '📋' },
+  { title: 'Development', icon: '💻' },
+  { title: 'Launch', icon: '🚀' }
+];
+</script>
+
+<!-- Reversed -->
+<snice-timeline reverse></snice-timeline>
+```
+
+## Features
+
+- Vertical and horizontal orientations
+- Left/right/alternate positioning (vertical)
+- 5 item variants with default icons
+- Custom icons supported
+- Timestamps and descriptions optional
+- Connecting lines between items
+- Reversible order

package/docs/ai/components/toast.md

@@ -0,0 +1,140 @@
+# snice-toast & snice-toast-container
+
+Temporary notification system with static API.
+
+## Components
+
+### snice-toast
+
+Individual toast notification element.
+
+```typescript
+type: 'success'|'error'|'warning'|'info' = 'info';
+message: string = '';
+closable: boolean = true;
+icon: boolean = true;
+```
+
+**Methods:**
+- `hide()` - Start hide animation
+
+### snice-toast-container
+
+Manages and positions multiple toasts.
+
+```typescript
+position: 'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right' = 'bottom-center';
+```
+
+**Methods:**
+- `show(message, options?)` - Show toast, returns ID
+- `hide(id)` - Hide specific toast
+- `clear()` - Remove all toasts
+
+## Static API (Recommended)
+
+```typescript
+import Toast from 'snice/components/toast/snice-toast-container';
+
+// Convenience methods
+Toast.success(message, options?): Promise<string>
+Toast.error(message, options?): Promise<string>
+Toast.warning(message, options?): Promise<string>
+Toast.info(message, options?): Promise<string>
+
+// Generic
+Toast.show(message, options?): Promise<string>
+
+// Control
+Toast.hide(id): void
+Toast.clear(): void
+```
+
+## Toast Options
+
+```typescript
+interface ToastOptions {
+  type?: 'success'|'error'|'warning'|'info';  // Default: 'info'
+  duration?: number;      // ms, 0 = no auto-dismiss, default: 4000
+  position?: ToastPosition;  // Only for static API
+  closable?: boolean;     // Default: true
+  icon?: boolean;         // Default: true
+  id?: string;            // Custom ID, auto-generated if omitted
+}
+```
+
+## Usage
+
+```typescript
+// Basic
+Toast.success('Saved successfully');
+Toast.error('Failed to load');
+Toast.warning('Low disk space');
+Toast.info('5 new messages');
+
+// With options
+Toast.show('Custom', {
+  type: 'success',
+  duration: 5000,
+  position: 'top-right',
+  closable: true,
+  icon: false
+});
+
+// Manual control
+const id = Toast.info('Loading...', { duration: 0 });
+await operation();
+Toast.hide(id);
+Toast.success('Complete');
+
+// Clear all
+Toast.clear();
+```
+
+## Container Usage
+
+```html
+<snice-toast-container position="bottom-center"></snice-toast-container>
+```
+
+```typescript
+const container = document.querySelector('snice-toast-container');
+const id = container.show('Message', { type: 'success' });
+container.hide(id);
+container.clear();
+```
+
+## Features
+
+- Auto-dismiss after duration (default 4s)
+- 4 types with icons and colors
+- 6 position options
+- Slide in/out animations (300ms)
+- Global container auto-creation
+- Top positions prepend, bottom append
+- Accessibility: role="alert", aria-live="polite"
+- Close button keyboard accessible
+
+## Patterns
+
+**Success/Error:**
+```typescript
+try {
+  await action();
+  Toast.success('Done');
+} catch (e) {
+  Toast.error(e.message);
+}
+```
+
+**Loading:**
+```typescript
+const id = Toast.info('Loading...', { duration: 0 });
+await fetch();
+Toast.hide(id);
+```
+
+**Persistent:**
+```typescript
+Toast.show('Manual close only', { duration: 0 });
+```