snice 4.9.0 → 4.11.0

package/docs/components/input.md

@@ -0,0 +1,242 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/input.md instead)
+
+# Input
+`<snice-input>`
+
+Text input field with validation, icons, and form association.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/input/snice-input';
+```
+
+```html
+<snice-input label="Name" placeholder="Enter your name"></snice-input>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/input/snice-input';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-input.min.js"></script>
+```
+
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the input style.
+
+```html
+<snice-input variant="outlined" label="Outlined"></snice-input>
+<snice-input variant="filled" label="Filled"></snice-input>
+<snice-input variant="underlined" label="Underlined"></snice-input>
+```
+
+### Sizes
+
+Use the `size` attribute to change the input size.
+
+```html
+<snice-input size="small" placeholder="Small"></snice-input>
+<snice-input size="medium" placeholder="Medium"></snice-input>
+<snice-input size="large" placeholder="Large"></snice-input>
+```
+
+### Input Types
+
+Use the `type` attribute to set the input type.
+
+```html
+<snice-input type="text" label="Text"></snice-input>
+<snice-input type="email" label="Email"></snice-input>
+<snice-input type="number" label="Age" min="0" max="120"></snice-input>
+<snice-input type="tel" label="Phone"></snice-input>
+<snice-input type="url" label="Website"></snice-input>
+<snice-input type="search" label="Search"></snice-input>
+```
+
+### Password Toggle
+
+Set the `password` attribute along with `type="password"` to show a visibility toggle button.
+
+```html
+<snice-input type="password" password label="Password"></snice-input>
+```
+
+### Icons
+
+Use the `prefix-icon` and `suffix-icon` attributes to add icons. Supports emoji, URLs, image files, and Material Symbols ligatures.
+
+```html
+<snice-input prefix-icon="🔍" placeholder="Search"></snice-input>
+<snice-input suffix-icon="✉️" type="email" label="Email"></snice-input>
+<snice-input prefix-icon="/icons/search.svg" placeholder="Search"></snice-input>
+<snice-input prefix-icon="search" placeholder="Search"></snice-input>
+```
+
+### Icon Slots
+
+Use the `prefix-icon` and `suffix-icon` slots for custom icon content like external icon fonts.
+
+```html
+<snice-input placeholder="Search">
+  <span slot="prefix-icon" class="material-symbols-outlined">search</span>
+</snice-input>
+<snice-input placeholder="Email">
+  <span slot="suffix-icon" class="material-symbols-outlined">mail</span>
+</snice-input>
+```
+
+### Clearable
+
+Set the `clearable` attribute to show a clear button when the input has a value.
+
+```html
+<snice-input value="Hello" clearable label="Clearable"></snice-input>
+```
+
+### Helper and Error Text
+
+Use `helper-text` and `error-text` to display guidance or validation messages.
+
+```html
+<snice-input label="Username" helper-text="Must be unique"></snice-input>
+<snice-input label="Email" invalid error-text="Invalid email address"></snice-input>
+```
+
+### Loading
+
+Set the `loading` attribute to show a spinner and disable the input.
+
+```html
+<snice-input loading label="Validating" value="user@example.com"></snice-input>
+```
+
+### Disabled and Readonly
+
+```html
+<snice-input disabled value="Cannot edit" label="Disabled"></snice-input>
+<snice-input readonly value="Read only" label="Readonly"></snice-input>
+```
+
+### Validation
+
+Use `required`, `pattern`, `minlength`, and `maxlength` for built-in validation.
+
+```html
+<snice-input type="email" required label="Email"></snice-input>
+<snice-input pattern="[A-Za-z]+" label="Letters only"></snice-input>
+<snice-input minlength="3" maxlength="20" label="Username"></snice-input>
+```
+
+### Number Input
+
+Use `min`, `max`, and `step` for number inputs.
+
+```html
+<snice-input type="number" min="0" max="100" step="5" label="Quantity"></snice-input>
+```
+
+### Form Integration
+
+Use `name` and `required` for native form participation.
+
+```html
+<form>
+  <snice-input name="username" required label="Username"></snice-input>
+  <snice-input name="email" type="email" required label="Email"></snice-input>
+</form>
+```
+
+### Event Handling
+
+Listen for input events using `input-input` and `input-change`.
+
+```html
+<snice-input id="inp" label="Type something"></snice-input>
+<script>
+const inp = document.querySelector('#inp');
+inp.addEventListener('input-input', (e) => console.log('Input:', e.detail.value));
+inp.addEventListener('input-change', (e) => console.log('Change:', e.detail.value));
+</script>
+```
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix-icon` | Custom prefix icon content (overrides `prefixIcon` property) |
+| `suffix-icon` | Custom suffix icon content (overrides `suffixIcon` property) |
+
+## Properties
+
+| Property | Attribute | Type | Default | Description |
+|----------|-----------|------|---------|-------------|
+| `type` | `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'tel' \| 'url' \| 'search' \| 'date' \| 'time' \| 'datetime-local'` | `'text'` | Input type |
+| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Input size |
+| `variant` | `variant` | `'outlined' \| 'filled' \| 'underlined'` | `'outlined'` | Visual style |
+| `value` | `value` | `string` | `''` | Input value |
+| `placeholder` | `placeholder` | `string` | `''` | Placeholder text |
+| `label` | `label` | `string` | `''` | Label text |
+| `helperText` | `helper-text` | `string` | `''` | Helper text below input |
+| `errorText` | `error-text` | `string` | `''` | Error text below input |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the input |
+| `readonly` | `readonly` | `boolean` | `false` | Makes the input read-only |
+| `loading` | `loading` | `boolean` | `false` | Shows loading spinner |
+| `required` | `required` | `boolean` | `false` | Marks as required |
+| `invalid` | `invalid` | `boolean` | `false` | Shows invalid styling |
+| `clearable` | `clearable` | `boolean` | `false` | Shows clear button |
+| `password` | `password` | `boolean` | `false` | Shows password visibility toggle |
+| `min` | `min` | `string` | `''` | Minimum value (number inputs) |
+| `max` | `max` | `string` | `''` | Maximum value (number inputs) |
+| `step` | `step` | `string` | `''` | Step value (number inputs) |
+| `pattern` | `pattern` | `string` | `''` | Validation pattern |
+| `maxlength` | `maxlength` | `number` | `-1` | Maximum character length |
+| `minlength` | `minlength` | `number` | `-1` | Minimum character length |
+| `autocomplete` | `autocomplete` | `string` | `''` | Autocomplete hint |
+| `name` | `name` | `string` | `''` | Form field name |
+| `prefixIcon` | `prefix-icon` | `string` | `''` | Prefix icon (emoji, URL, or ligature) |
+| `suffixIcon` | `suffix-icon` | `string` | `''` | Suffix icon (emoji, URL, or ligature) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `input-input` | `{ value, input }` | Fired on each keystroke |
+| `input-change` | `{ value, input }` | Fired on value commit |
+| `input-focus` | `{ input }` | Fired on focus |
+| `input-blur` | `{ input }` | Fired on blur |
+| `input-clear` | `{ input }` | Fired when cleared |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `focus()` | — | Focuses the input |
+| `blur()` | — | Removes focus |
+| `select()` | — | Selects all text |
+| `clear()` | — | Clears the value |
+| `checkValidity()` | — | Returns input validity |
+| `reportValidity()` | — | Reports input validity |
+| `setCustomValidity()` | `message: string` | Sets custom validation message |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | The native input element |
+| `prefix-icon` | The prefix icon container |
+| `suffix-icon` | The suffix icon container |
+| `clear` | The clear button |
+| `spinner` | The loading spinner |
+| `password-toggle` | The password visibility toggle |
+| `helper-text` | The helper text element |
+| `error-text` | The error text element |

package/docs/components/kanban.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/kanban.md instead)
+
 # Kanban Component
 
 Drag-and-drop kanban board with columns and cards.

package/docs/components/kpi.md

@@ -1,3 +1,5 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/kpi.md instead)
+
 # KPI Component
 
 A key performance indicator display component for showing metrics with optional trend visualization and sentiment indicators. Perfect for dashboards and analytics interfaces.

package/docs/components/layout.md

@@ -0,0 +1,84 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/layout.md instead)
+
+# Layout
+`<snice-layout>`
+
+Application layout with header navigation, main content area, and footer.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/layout/snice-layout';
+```
+
+```html
+<snice-layout>
+  <div slot="brand"><h1>My App</h1></div>
+  <div slot="page">Page content</div>
+  <div slot="footer"><p>&copy; 2025 My Company</p></div>
+</snice-layout>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/layout/snice-layout';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-layout.min.js"></script>
+```
+
+## Examples
+
+### Basic Layout
+
+Use slots to fill the brand, page, and footer areas.
+
+```html
+<snice-layout>
+  <div slot="brand">
+    <h1>Dashboard</h1>
+  </div>
+  <div slot="page">
+    <h2>Welcome</h2>
+    <p>Main content goes here.</p>
+  </div>
+  <div slot="footer">
+    <p>&copy; 2025 Acme Corp</p>
+  </div>
+</snice-layout>
+```
+
+### With Router Integration
+
+Use the `update()` method to sync navigation with the router.
+
+```html
+<snice-layout id="app-layout">
+  <img slot="brand" src="/logo.svg" alt="Logo" />
+  <div slot="page" id="page-content"></div>
+</snice-layout>
+```
+
+```javascript
+const layout = document.querySelector('#app-layout');
+layout.update(appContext, placards, currentRoute, routeParams);
+```
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `brand` | Logo or brand content in the header |
+| `page` | Main page content area |
+| `footer` | Footer content |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `update()` | `appContext: AppContext, placards: Placard[], currentRoute: string, routeParams: RouteParams` | Updates navigation from router state |

package/docs/components/link-preview.md

@@ -1,161 +1,135 @@
-# Link Preview Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/link-preview.md instead)
 
-The link preview component displays social media-style link preview cards, similar to Open Graph or Twitter Card previews. It is purely visual -- all data is passed via properties (no fetching).
+# Link Preview
+`<snice-link-preview>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Events](#events)
-- [Examples](#examples)
+Displays a rich preview card for a URL with image, title, description, and site info.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/link-preview/snice-link-preview';
+```
+
 ```html
 <snice-link-preview
-  title="My Article"
-  description="A brief description of the article content."
-  image="https://example.com/og-image.jpg"
-  site-name="example.com"
-  url="https://example.com/article"
-></snice-link-preview>
+  url="https://example.com"
+  title="Example Website"
+  description="An example website for demonstration."
+  image="https://example.com/og-image.jpg">
+</snice-link-preview>
 ```
 
+## Importing
+
+**ESM (bundler)**
 ```typescript
 import 'snice/components/link-preview/snice-link-preview';
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `url` | `string` | `''` | Target URL. Clicking the card opens this in a new tab. |
-| `title` | `string` | `''` | Title text. Truncated to 2 lines. |
-| `description` | `string` | `''` | Description text. Truncated to 3 lines. |
-| `image` | `string` | `''` | Image URL. Shows a placeholder icon when empty. |
-| `site-name` | `string` | `''` | Name of the source site. |
-| `favicon` | `string` | `''` | URL of the site favicon icon. |
-| `variant` | `'horizontal' \| 'vertical'` | `'vertical'` | Layout direction. Vertical shows image on top; horizontal shows image on left. |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Controls padding, font sizes, and image dimensions. |
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `@snice/link-click` | `{ url: string }` | Fired when the card is clicked, before opening the URL. |
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-link-preview.min.js"></script>
+```
 
 ## Examples
 
-### Vertical Card (Default)
+### Vertical Card
+
+The default layout stacks the image above the content.
 
 ```html
 <snice-link-preview
+  url="https://snice.dev"
   title="Snice - Beautiful Decorators for Custom Elements"
-  description="Write clean, reactive web components with TypeScript decorators. No framework. No virtual DOM."
+  description="Write clean, reactive web components with TypeScript decorators."
   image="https://picsum.photos/600/300"
-  site-name="snice.dev"
-  url="https://snice.dev"
-></snice-link-preview>
+  site-name="snice.dev">
+</snice-link-preview>
 ```
 
 ### Horizontal Card
 
+Use `variant="horizontal"` to display the image beside the content.
+
 ```html
 <snice-link-preview
   variant="horizontal"
-  title="Getting Started Guide"
-  description="Learn to build elements step by step"
-  site-name="snice.dev"
   url="https://snice.dev/guide"
-></snice-link-preview>
+  title="Getting Started Guide"
+  description="Learn to build elements step by step."
+  site-name="snice.dev">
+</snice-link-preview>
 ```
 
-### Small Horizontal Cards
-
-```html
-<snice-link-preview
-  variant="horizontal"
-  size="small"
-  title="Quick Link"
-  description="A short description"
-  site-name="example.com"
-  url="https://example.com"
-></snice-link-preview>
-```
+### Sizes
 
-### Large Card
+Use the `size` attribute to adjust padding, font sizes, and image dimensions.
 
 ```html
-<snice-link-preview
-  size="large"
-  title="In-Depth Article Title"
-  description="A longer description that can span up to four lines in the large size variant, giving more room for content summaries."
-  image="https://picsum.photos/800/400"
-  site-name="blog.example.com"
-  favicon="https://example.com/favicon.ico"
-  url="https://blog.example.com/article"
-></snice-link-preview>
+<snice-link-preview size="small" url="https://example.com" title="Compact Card" description="A short summary."></snice-link-preview>
+<snice-link-preview size="large" url="https://example.com" title="Expanded Card" description="A longer description with more room for content." image="https://picsum.photos/800/400"></snice-link-preview>
 ```
 
 ### Without Image
 
+When no image is provided, a placeholder link icon is shown.
+
 ```html
 <snice-link-preview
+  url="https://example.com"
   title="Text-Only Preview"
   description="When no image is provided, a placeholder icon is shown."
-  site-name="example.com"
-  url="https://example.com"
-></snice-link-preview>
+  site-name="example.com">
+</snice-link-preview>
 ```
 
 ### With Favicon
 
 ```html
 <snice-link-preview
+  url="https://example.com/article"
   title="Article with Favicon"
   description="Shows the site favicon next to the site name."
   image="https://picsum.photos/600/300"
   site-name="example.com"
-  favicon="https://example.com/favicon.ico"
-  url="https://example.com/article"
-></snice-link-preview>
+  favicon="https://example.com/favicon.ico">
+</snice-link-preview>
 ```
 
-### Listening for Click Events
+### Click Event
 
 ```html
 <snice-link-preview
   id="preview"
   title="Clickable Preview"
-  description="Listen for link-click events."
-  url="https://example.com"
-></snice-link-preview>
+  description="Listen for click events."
+  url="https://example.com">
+</snice-link-preview>
 
 <script type="module">
-  const preview = document.getElementById('preview');
-  preview.addEventListener('@snice/link-click', (e) => {
+  document.getElementById('preview').addEventListener('@snice/link-click', (e) => {
     console.log('Link clicked:', e.detail.url);
   });
 </script>
 ```
 
-## Accessibility
-
-- **ARIA role**: Card has `role="article"` for screen reader context
-- **ARIA label**: Uses the title as the accessible label
-- **Keyboard navigation**: Card is focusable and activates with Enter or Space
-- **Focus ring**: Visible focus indicator for keyboard users
-- **Image alt**: Images use empty alt text (decorative) since the title provides context
-
-## Browser Support
+## Properties
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `url` | `string` | `''` | Target URL (opens on click) |
+| `title` | `string` | `''` | Preview title (clamped to 2 lines) |
+| `description` | `string` | `''` | Preview description (clamped to 3 lines) |
+| `image` | `string` | `''` | Preview image URL |
+| `siteName` (attr: `site-name`) | `string` | `''` | Site name in footer |
+| `favicon` | `string` | `''` | Favicon URL in footer |
+| `variant` | `'vertical' \| 'horizontal'` | `'vertical'` | Card layout direction |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Card size |
 
-## Best Practices
+## Events
 
-1. **Always set a title**: The title is the primary content of the preview card
-2. **Provide meaningful descriptions**: Keep descriptions concise but informative
-3. **Use appropriate images**: Wide aspect ratio images (1.91:1) work best for vertical cards
-4. **Set the URL**: Without a URL, clicking the card does nothing
-5. **Use horizontal for compact layouts**: The horizontal variant works well in sidebars or lists
-6. **Use small size for dense UIs**: Small cards work well when showing multiple previews
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/link-click` | `{ url: string }` | Fired when the card is clicked |