snice 2.5.4 → 3.1.0

package/docs/ai/components/input.md

@@ -0,0 +1,111 @@
+# snice-input
+
+Text input field with validation and icons.
+
+## Properties
+
+```typescript
+value: string = '';
+type: 'text'|'password'|'email'|'number'|'tel'|'url'|'search'|'date'|'time'|'datetime-local' = 'text';
+variant: 'outlined'|'filled'|'underlined' = 'outlined';
+size: 'small'|'medium'|'large' = 'medium';
+placeholder: string = '';
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+clearable: boolean = false;
+label: string = '';
+helperText: string = '';
+errorText: string = '';
+prefix: string = '';
+suffix: string = '';
+prefixIcon: string = '';
+suffixIcon: string = '';
+min: string = '';
+max: string = '';
+minlength: number = 0;
+maxlength: number = 0;
+pattern: string = '';
+autocomplete: string = '';
+name: string = '';
+```
+
+## Methods
+
+- `focus()` - Focus input
+- `blur()` - Blur input
+- `select()` - Select text
+- `clear()` - Clear value
+
+## Events
+
+- `input` - {value, input}
+- `change` - {value, input}
+- `focus` - {input}
+- `blur` - {input}
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-input label="Name" placeholder="Enter name"></snice-input>
+
+<!-- Variants -->
+<snice-input variant="outlined"></snice-input>
+<snice-input variant="filled"></snice-input>
+<snice-input variant="underlined"></snice-input>
+
+<!-- Input types -->
+<snice-input type="email" label="Email"></snice-input>
+<snice-input type="password" label="Password"></snice-input>
+<snice-input type="number" label="Age"></snice-input>
+
+<!-- With icons -->
+<snice-input prefix-icon="🔍" placeholder="Search"></snice-input>
+<snice-input suffix-icon="✉️" type="email"></snice-input>
+
+<!-- With prefix/suffix text -->
+<snice-input prefix="$" type="number"></snice-input>
+<snice-input suffix=".com" type="url"></snice-input>
+
+<!-- Clearable -->
+<snice-input value="Text" clearable></snice-input>
+
+<!-- Helper text -->
+<snice-input label="Username" helper-text="Must be unique"></snice-input>
+
+<!-- Error state -->
+<snice-input label="Email" invalid error-text="Invalid email"></snice-input>
+
+<!-- Validation -->
+<snice-input type="email" required minlength="5" maxlength="50"></snice-input>
+
+<!-- Sizes -->
+<snice-input size="small"></snice-input>
+<snice-input size="medium"></snice-input>
+<snice-input size="large"></snice-input>
+
+<!-- Form integration -->
+<snice-input name="username" required></snice-input>
+
+<!-- Events -->
+<snice-input id="inp"></snice-input>
+<script>
+const inp = document.querySelector('#inp');
+inp.addEventListener('input', (e) => console.log('Input:', e.detail.value));
+inp.addEventListener('change', (e) => console.log('Change:', e.detail.value));
+</script>
+```
+
+## Features
+
+- Form-associated custom element
+- 10 input types
+- 3 visual variants
+- Prefix/suffix icons or text
+- Clearable with X button
+- Helper and error text
+- Validation (min/max/pattern/length)
+- 3 sizes
+- Keyboard accessible

package/docs/ai/components/login.md

@@ -0,0 +1,109 @@
+# snice-login
+
+Login form component with username, password, and optional features.
+
+## Properties
+
+```typescript
+variant: 'default'|'card'|'minimal' = 'default';
+size: 'small'|'medium'|'large' = 'medium';
+title: string = '';
+disabled: boolean = false;
+loading: boolean = false;
+showRememberMe: boolean = false;
+showForgotPassword: boolean = false;
+actionText: string = 'Login';
+```
+
+## Methods
+
+- `login(credentials)` - Programmatic login, returns {success, error?, data?}
+- `reset()` - Clear form
+- `setError(message)` - Display error message
+- `clearError()` - Clear error message
+
+## Events
+
+- `submit` - {username, password, remember}
+- `forgot-password` - User clicked forgot password link
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-login title="Sign In"></snice-login>
+
+<!-- Variants -->
+<snice-login variant="card"></snice-login>
+<snice-login variant="minimal"></snice-login>
+
+<!-- With remember me and forgot password -->
+<snice-login show-remember-me show-forgot-password></snice-login>
+
+<!-- Custom action text -->
+<snice-login action-text="Sign In"></snice-login>
+
+<!-- Loading state -->
+<snice-login loading></snice-login>
+
+<!-- Disabled -->
+<snice-login disabled></snice-login>
+
+<!-- Sizes -->
+<snice-login size="small"></snice-login>
+<snice-login size="medium"></snice-login>
+<snice-login size="large"></snice-login>
+
+<!-- Event handling -->
+<snice-login id="login"></snice-login>
+<script>
+const login = document.querySelector('#login');
+
+login.addEventListener('submit', async (e) => {
+  const {username, password, remember} = e.detail;
+
+  login.loading = true;
+  const result = await fetch('/api/login', {
+    method: 'POST',
+    body: JSON.stringify({username, password})
+  });
+
+  if (!result.ok) {
+    login.setError('Invalid credentials');
+    login.loading = false;
+  } else {
+    window.location = '/dashboard';
+  }
+});
+
+login.addEventListener('forgot-password', () => {
+  window.location = '/forgot-password';
+});
+</script>
+
+<!-- Programmatic login -->
+<script>
+const result = await login.login({
+  username: 'user@example.com',
+  password: 'password123',
+  remember: true
+});
+
+if (result.success) {
+  console.log('Logged in:', result.data);
+} else {
+  console.error('Login failed:', result.error);
+}
+</script>
+```
+
+## Features
+
+- 3 visual variants (default/card/minimal)
+- 3 sizes
+- Optional remember me checkbox
+- Optional forgot password link
+- Loading and disabled states
+- Error message display
+- Programmatic and event-based submission
+- Keyboard accessible (Enter to submit)

package/docs/ai/components/modal.md

@@ -0,0 +1,67 @@
+# snice-modal
+
+Dialog overlay with focus trap, backdrop dismiss, and accessibility.
+
+## Properties
+
+```typescript
+open: boolean = false;                        // Visibility state
+size: 'small'|'medium'|'large'|'fullscreen' = 'medium';
+noBackdropDismiss: boolean = false;           // Prevent backdrop click close
+noEscapeDismiss: boolean = false;             // Prevent Escape key close
+noFocusTrap: boolean = false;                 // Disable focus trapping
+noCloseButton: boolean = false;               // Hide close button
+label: string = '';                           // Accessible label
+```
+
+## Methods
+
+```typescript
+show()   // Open modal
+close()  // Close modal
+```
+
+## Events
+
+```typescript
+'@snice/modal-open'   // { modal }
+'@snice/modal-close'  // { modal }
+```
+
+## Slots
+
+```html
+<snice-modal>
+  <div slot="header">Title</div>
+  <div>Body content</div>
+  <div slot="footer">Actions</div>
+</snice-modal>
+```
+
+## Usage
+
+```html
+<snice-modal id="myModal" label="Confirm">
+  <div slot="header"><h2>Confirm</h2></div>
+  <p>Are you sure?</p>
+  <div slot="footer">
+    <button onclick="this.closest('snice-modal').close()">Cancel</button>
+    <button onclick="this.closest('snice-modal').close()">OK</button>
+  </div>
+</snice-modal>
+```
+
+```typescript
+const modal = document.querySelector('snice-modal');
+modal.show();
+modal.close();
+```
+
+## Features
+
+- Body scroll lock when open
+- Focus trap with Tab navigation
+- Focus restoration on close
+- Backdrop click to close
+- Escape key to close
+- ARIA attributes (role, aria-modal, aria-label, aria-hidden)

package/docs/ai/components/nav.md

@@ -0,0 +1,76 @@
+# snice-nav
+
+Navigation menu from placard configurations, integrates with Snice routing.
+
+## Properties
+
+```typescript
+variant: 'flat'|'hierarchical'|'grouped' = 'flat';
+orientation: 'horizontal'|'vertical' = 'horizontal';
+isTopLevel: boolean = false;              // Receive context updates
+```
+
+## Methods
+
+```typescript
+update(placards, appContext?, currentRoute?, routeParams?)  // Update nav with placard data
+```
+
+## Placard Structure
+
+```typescript
+interface Placard {
+  name: string;                    // Route identifier
+  title: string;                   // Display text
+  icon?: string;                   // Icon character
+  order?: number;                  // Sort order
+  parent?: string;                 // Parent name (hierarchical)
+  group?: string;                  // Group name (grouped)
+  show?: boolean;                  // Visibility
+  description?: string;            // Accessible label/tooltip
+  tooltip?: string;                // Hover tooltip
+  hotkeys?: string[];              // Keyboard shortcuts
+  helpUrl?: string;                // Help URL
+  searchTerms?: string[];          // Search keywords
+  attributes?: Record<string, any>; // Custom data attributes
+  visibleOn?: Function | Function[]; // Visibility guards
+}
+```
+
+## Usage
+
+```html
+<snice-nav id="nav" variant="flat" orientation="horizontal"></snice-nav>
+```
+
+```typescript
+const nav = document.querySelector('snice-nav');
+const placards = [
+  { name: 'home', title: 'Home', icon: '🏠', order: 0 },
+  { name: 'products', title: 'Products', icon: '📦', order: 1 },
+];
+nav.update(placards, undefined, 'home');
+```
+
+## Variants
+
+- **flat**: Simple list (default)
+- **hierarchical**: Nested with parent-child relationships
+- **grouped**: Organized into labeled groups
+
+## Context Integration
+
+```html
+<snice-nav is-top-level></snice-nav>
+```
+
+Auto-receives placards, routes, and app context from Snice context system.
+
+## Features
+
+- Active route tracking with `.nav__link--active` class
+- `aria-current="page"` on active links
+- `role="navigation"` on container
+- Hotkeys via `data-hotkeys` attribute
+- Custom attributes via placard `attributes` property
+- Conditional visibility via `visibleOn` guards

package/docs/ai/components/pagination.md

@@ -0,0 +1,55 @@
+# snice-pagination
+
+Pagination navigation component.
+
+## Properties
+
+```typescript
+current: number = 1;         // Active page
+total: number = 1;           // Total pages
+siblings: number = 1;        // Pages shown each side of current
+showFirst: boolean = true;   // Show first button
+showLast: boolean = true;    // Show last button
+showPrev: boolean = true;    // Show previous button
+showNext: boolean = true;    // Show next button
+size: 'small'|'medium'|'large' = 'medium';
+variant: 'default'|'rounded'|'text' = 'default';
+```
+
+## Methods
+
+```typescript
+goToPage(page: number)   // Navigate to page
+nextPage()               // Next page
+previousPage()           // Previous page
+firstPage()              // First page
+lastPage()               // Last page
+```
+
+## Events
+
+```typescript
+'@snice/pagination-change' // { page, previousPage }
+```
+
+## Usage
+
+```html
+<snice-pagination current="1" total="10"></snice-pagination>
+```
+
+```typescript
+pagination.addEventListener('@snice/pagination-change', (e) => {
+  console.log(e.detail.page);
+});
+```
+
+## CSS Variables
+
+```css
+--pagination-gap: 4px;
+--pagination-button-size: 32px;
+--pagination-button-padding: 8px;
+--pagination-font-size: 14px;
+--pagination-border-radius: 4px;
+```

package/docs/ai/components/progress.md

@@ -0,0 +1,72 @@
+# snice-progress
+
+Progress indicator with linear or circular display.
+
+## Properties
+
+```typescript
+value: number = 0;
+max: number = 100;
+variant: 'linear'|'circular' = 'linear';
+indeterminate: boolean = false;
+size: 'small'|'medium'|'large' = 'medium';
+color: string = '';
+showLabel: boolean = false;
+label: string = '';
+striped: boolean = false;
+animated: boolean = false;
+```
+
+## Usage
+
+```html
+<!-- Basic linear -->
+<snice-progress value="50"></snice-progress>
+
+<!-- Circular -->
+<snice-progress variant="circular" value="75"></snice-progress>
+
+<!-- Indeterminate (loading) -->
+<snice-progress indeterminate></snice-progress>
+<snice-progress variant="circular" indeterminate></snice-progress>
+
+<!-- With label -->
+<snice-progress value="60" show-label></snice-progress>
+<snice-progress value="60" label="Uploading..."></snice-progress>
+
+<!-- Custom max -->
+<snice-progress value="3" max="10"></snice-progress>
+
+<!-- Striped and animated -->
+<snice-progress value="70" striped></snice-progress>
+<snice-progress value="70" striped animated></snice-progress>
+
+<!-- Custom color -->
+<snice-progress value="80" color="#3b82f6"></snice-progress>
+
+<!-- Sizes -->
+<snice-progress value="50" size="small"></snice-progress>
+<snice-progress value="50" size="medium"></snice-progress>
+<snice-progress value="50" size="large"></snice-progress>
+
+<!-- Dynamic updates -->
+<snice-progress id="prog" value="0"></snice-progress>
+<script>
+const prog = document.querySelector('#prog');
+let val = 0;
+setInterval(() => {
+  val = (val + 10) % 100;
+  prog.value = val;
+}, 500);
+</script>
+```
+
+## Features
+
+- Linear or circular variant
+- Indeterminate mode for unknown progress
+- Optional percentage label or custom text
+- Striped and animated styles
+- Custom color
+- 3 sizes
+- Reactive value updates

package/docs/ai/components/radio.md

@@ -0,0 +1,79 @@
+# snice-radio
+
+Form radio button input with grouping.
+
+## Properties
+
+```typescript
+checked: boolean = false;
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+size: 'small'|'medium'|'large' = 'medium';
+name: string = '';
+value: string = '';
+label: string = '';
+```
+
+## Methods
+
+- `focus()` - Focus radio
+- `blur()` - Blur radio
+- `click()` - Programmatic click
+
+## Events
+
+- `change` - {checked, value, radio}
+
+## Usage
+
+```html
+<!-- Basic radio group -->
+<snice-radio name="color" value="red" label="Red"></snice-radio>
+<snice-radio name="color" value="green" label="Green"></snice-radio>
+<snice-radio name="color" value="blue" label="Blue"></snice-radio>
+
+<!-- Pre-selected -->
+<snice-radio name="size" value="s" label="Small"></snice-radio>
+<snice-radio name="size" value="m" label="Medium" checked></snice-radio>
+<snice-radio name="size" value="l" label="Large"></snice-radio>
+
+<!-- Disabled -->
+<snice-radio label="Unavailable" disabled></snice-radio>
+<snice-radio label="Selected but disabled" checked disabled></snice-radio>
+
+<!-- Required -->
+<snice-radio name="accept" value="yes" label="Accept" required></snice-radio>
+
+<!-- Invalid -->
+<snice-radio label="Invalid option" invalid></snice-radio>
+
+<!-- Sizes -->
+<snice-radio label="Small" size="small"></snice-radio>
+<snice-radio label="Medium" size="medium"></snice-radio>
+<snice-radio label="Large" size="large"></snice-radio>
+
+<!-- Form integration -->
+<form>
+  <snice-radio name="plan" value="free" label="Free"></snice-radio>
+  <snice-radio name="plan" value="pro" label="Pro"></snice-radio>
+  <snice-radio name="plan" value="enterprise" label="Enterprise"></snice-radio>
+</form>
+
+<!-- Event handling -->
+<snice-radio id="rb" name="opt" value="a"></snice-radio>
+<script>
+document.querySelector('#rb').addEventListener('change', (e) => {
+  console.log('Selected:', e.detail.value);
+});
+</script>
+```
+
+## Features
+
+- Form-associated custom element
+- Automatic radio group management by name
+- 3 sizes
+- Keyboard accessible (arrow keys navigate group)
+- Change events
+- Invalid state styling

package/docs/ai/components/select.md

@@ -0,0 +1,92 @@
+# snice-select
+
+Customizable dropdown selection with single/multiple selection, search, and icons.
+
+## Components
+
+### snice-select (Container)
+
+```typescript
+value: string = '';                 // Selected value (comma-separated for multiple)
+disabled: boolean = false;          // Disabled state
+required: boolean = false;          // Required for form validation
+invalid: boolean = false;           // Invalid state styling
+readonly: boolean = false;          // Readonly state
+multiple: boolean = false;          // Allow multiple selection
+searchable: boolean = false;        // Show search input
+clearable: boolean = false;         // Show clear button
+open: boolean = false;              // Dropdown open state
+size: 'small'|'medium'|'large' = 'medium';
+name: string = '';                  // Form field name
+label: string = '';                 // Label text
+placeholder: string = 'Select an option';
+maxHeight: string = '200px';        // Max dropdown height
+```
+
+**Methods:**
+```typescript
+selectOption(value: string)  // Select option by value
+clear()                      // Clear selection
+openDropdown()               // Open dropdown
+closeDropdown()              // Close dropdown
+toggleDropdown()             // Toggle dropdown
+focus()                      // Focus trigger
+blur()                       // Blur and close
+```
+
+**Events:**
+```typescript
+'@snice/select-change'  // { value, option, select }
+'@snice/select-open'    // { select }
+'@snice/select-close'   // { select }
+```
+
+### snice-option (Option Item)
+
+```typescript
+value: string = '';           // Option value (defaults to label)
+label: string = '';           // Option label (defaults to textContent)
+disabled: boolean = false;    // Disabled state
+selected: boolean = false;    // Initially selected
+icon: string = '';            // Icon URL
+```
+
+**Getter:**
+```typescript
+optionData  // { value, label, disabled, selected, icon }
+```
+
+## Usage
+
+```html
+<snice-select label="Choose" name="choice">
+  <snice-option value="1">Option 1</snice-option>
+  <snice-option value="2">Option 2</snice-option>
+</snice-select>
+```
+
+```typescript
+select.addEventListener('@snice/select-change', (e) => {
+  console.log(e.detail.value);
+});
+
+select.selectOption('1');
+```
+
+## Features
+
+- Single and multiple selection
+- Search filtering
+- Keyboard navigation
+- Form integration
+- Icons in options
+- Clearable selection
+- Disabled options
+
+## Notes
+
+- Options must be direct children of select
+- Multiple selection values are comma-separated
+- Hidden native select for form submission
+- Dropdown closes outside click
+- Search shows in dropdown when open