snice 2.5.4 → 3.1.0

package/docs/ai/components/skeleton.md

@@ -0,0 +1,57 @@
+# snice-skeleton
+
+Loading placeholder with animated shimmer effect.
+
+## Properties
+
+```typescript
+variant: 'text'|'circular'|'rectangular'|'rounded' = 'text';
+width: string = '';
+height: string = '';
+animation: 'pulse'|'wave'|'none' = 'pulse';
+count: number = 1;
+spacing: string = '8px';
+```
+
+## Usage
+
+```html
+<!-- Text placeholder -->
+<snice-skeleton variant="text"></snice-skeleton>
+<snice-skeleton variant="text" width="200px"></snice-skeleton>
+
+<!-- Circular (avatar) -->
+<snice-skeleton variant="circular" width="40px" height="40px"></snice-skeleton>
+
+<!-- Rectangular -->
+<snice-skeleton variant="rectangular" width="100%" height="200px"></snice-skeleton>
+
+<!-- Rounded (card) -->
+<snice-skeleton variant="rounded" width="300px" height="150px"></snice-skeleton>
+
+<!-- Multiple lines -->
+<snice-skeleton variant="text" count="3"></snice-skeleton>
+<snice-skeleton variant="text" count="5" spacing="12px"></snice-skeleton>
+
+<!-- Animation types -->
+<snice-skeleton animation="pulse"></snice-skeleton>
+<snice-skeleton animation="wave"></snice-skeleton>
+<snice-skeleton animation="none"></snice-skeleton>
+
+<!-- Complex layout -->
+<div style="display: flex; gap: 16px;">
+  <snice-skeleton variant="circular" width="48px" height="48px"></snice-skeleton>
+  <div style="flex: 1;">
+    <snice-skeleton variant="text" width="40%"></snice-skeleton>
+    <snice-skeleton variant="text" width="60%"></snice-skeleton>
+  </div>
+</div>
+```
+
+## Features
+
+- 4 shape variants (text/circular/rectangular/rounded)
+- 3 animation styles (pulse/wave/none)
+- Custom dimensions
+- Multiple skeleton elements with spacing
+- Mimics loading content shapes

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/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 });
+```

package/docs/ai/components/tooltip.md

@@ -0,0 +1,146 @@
+# snice-tooltip
+
+Contextual information on hover, click, or focus with smart positioning.
+
+## Properties
+
+```typescript
+content: string = '';
+position: TooltipPosition = 'top';
+trigger: 'hover'|'click'|'focus'|'manual' = 'hover';
+delay: number = 0;                    // Show delay (ms)
+hideDelay: number = 0;                // Hide delay (ms)
+offset: number = 12;                  // Distance from trigger (px)
+arrow: boolean = true;
+open: boolean = false;                // For manual trigger
+maxWidth: number = 250;               // px
+zIndex: number = 10000;
+strictPositioning: boolean = false;   // Disable auto-repositioning
+```
+
+## Positions
+
+**Main (13 total):**
+- `top`, `bottom`, `left`, `right`
+- `top-start`, `top-end`
+- `bottom-start`, `bottom-end`
+- `left-start`, `left-end`
+- `right-start`, `right-end`
+
+## Methods
+
+```typescript
+show()            // Show tooltip
+hide()            // Hide tooltip
+toggle()          // Toggle visibility
+updatePosition()  // Recalculate position
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-tooltip content="Tooltip text">
+  <button>Hover me</button>
+</snice-tooltip>
+
+<!-- Position -->
+<snice-tooltip content="Below" position="bottom">
+  <button>Button</button>
+</snice-tooltip>
+
+<!-- Click trigger -->
+<snice-tooltip content="Click to toggle" trigger="click">
+  <button>Click me</button>
+</snice-tooltip>
+
+<!-- Focus trigger -->
+<snice-tooltip content="Focus input" trigger="focus">
+  <input type="text">
+</snice-tooltip>
+
+<!-- Manual control -->
+<snice-tooltip id="tip" content="Manual" trigger="manual">
+  <span>Element</span>
+</snice-tooltip>
+<button onclick="document.querySelector('#tip').open = true">Show</button>
+
+<!-- With delay -->
+<snice-tooltip content="Delayed" delay="500" hide-delay="200">
+  <button>Wait</button>
+</snice-tooltip>
+
+<!-- Custom styling -->
+<snice-tooltip
+  content="Custom"
+  max-width="400"
+  offset="20"
+  arrow="false">
+  <button>Custom</button>
+</snice-tooltip>
+```
+
+## Features
+
+- Portal rendering (appends to body)
+- Smart viewport detection & auto-repositioning
+- 13 position options with alignment
+- 4 trigger modes
+- Show/hide delays
+- Arrow indicator
+- Click-outside detection (click trigger)
+- Custom max-width, offset, z-index
+- Accessibility: role="tooltip"
+- Focus restoration
+
+## Patterns
+
+**Help icon:**
+```html
+<snice-tooltip content="Help text">
+  <span>?</span>
+</snice-tooltip>
+```
+
+**Disabled button:**
+```html
+<snice-tooltip content="Fill form first">
+  <span>
+    <button disabled>Submit</button>
+  </span>
+</snice-tooltip>
+```
+
+**Truncated text:**
+```html
+<snice-tooltip content="Full text here">
+  <div class="truncated">Full text...</div>
+</snice-tooltip>
+```
+
+**Programmatic:**
+```typescript
+const tip = document.querySelector('snice-tooltip');
+tip.show();
+tip.hide();
+tip.toggle();
+tip.updatePosition(); // After layout change
+```
+
+## Smart Positioning
+
+Auto-repositions if tooltip would overflow viewport. Tries alternative positions in order:
+- Top → Bottom → Left → Right
+- Bottom → Top → Left → Right
+- Left → Right → Top → Bottom
+- Right → Left → Top → Bottom
+
+Disable with `strict-positioning` attribute.
+
+## Notes
+
+- Disabled elements need wrapper span (no events)
+- Portal created in document.body
+- Hover doesn't work on touch devices
+- Content should be brief (not interactive)
+- Use `trigger="manual"` with `open` for programmatic control