snice 4.9.0 → 4.11.0

package/docs/components/link.md

@@ -1,100 +1,84 @@
-# Link Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/link.md instead)
 
-A customizable link component with multiple variants, external link handling, and accessibility features.
+# Link
+`<snice-link>`
 
-## Features
-
-- **Multiple Variants**: default, primary, secondary, muted
-- **External Link Handling**: Automatic `target="_blank"` and security attributes
-- **Hash Routing**: Built-in support for hash-based navigation
-- **Router Integration**: Emits events for custom router integration
-- **Accessibility**: Proper ARIA attributes and keyboard navigation
-- **Disabled State**: Visual and functional disabled state
-- **Customizable**: Full theme integration
+A customizable hyperlink component with variants, external link handling, and hash routing support.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/link/snice-link';
+```
+
 ```html
 <snice-link href="/about">About Us</snice-link>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `href` | `string` | `''` | Link URL |
-| `target` | `LinkTarget` | `'_self'` | Target attribute ('_self', '_blank', '_parent', '_top') |
-| `variant` | `LinkVariant` | `'default'` | Visual style variant |
-| `disabled` | `boolean` | `false` | Disable the link |
-| `external` | `boolean` | `false` | Treat as external link (auto _blank + security) |
-| `underline` | `boolean` | `false` | Show text underline |
-| `hash` | `boolean` | `false` | Automatically prepend # to href (for hash routing) |
-
-## Variants
+## Importing
 
-### Default
-```html
-<snice-link href="/page">Default link</snice-link>
+**ESM (bundler)**
+```typescript
+import 'snice/components/link/snice-link';
 ```
 
-### Primary
+**CDN**
 ```html
-<snice-link href="/page" variant="primary">Primary link</snice-link>
+<script src="snice-runtime.min.js"></script>
+<script src="snice-link.min.js"></script>
 ```
 
-### Secondary
-```html
-<snice-link href="/page" variant="secondary">Secondary link</snice-link>
-```
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the link's visual style.
 
-### Muted
 ```html
-<snice-link href="/page" variant="muted">Muted link</snice-link>
+<snice-link href="/page" variant="default">Default</snice-link>
+<snice-link href="/page" variant="primary">Primary</snice-link>
+<snice-link href="/page" variant="secondary">Secondary</snice-link>
+<snice-link href="/page" variant="muted">Muted</snice-link>
 ```
 
-## External Links
+### External Links
 
-External links automatically open in a new tab with security attributes:
+Set the `external` attribute to open in a new tab with security attributes and an arrow icon.
 
 ```html
-<snice-link href="https://example.com" external>
-  External Link
-</snice-link>
+<snice-link href="https://example.com" external>Visit Example</snice-link>
 ```
 
-This automatically adds:
-- `target="_blank"`
-- `rel="noopener noreferrer"`
-- External link icon (↗)
+### Underline
 
-## Underline
+Use the `underline` attribute to show text decoration.
 
 ```html
-<snice-link href="/page" underline>Underlined link</snice-link>
+<snice-link href="/docs" underline>Documentation</snice-link>
 ```
 
-## Disabled State
+### Disabled State
+
+Set the `disabled` attribute to prevent interaction.
 
 ```html
-<snice-link href="/page" disabled>Disabled link</snice-link>
+<snice-link href="/page" disabled>Unavailable</snice-link>
 ```
 
-## Hash Routing
+### Hash Routing
 
-For hash-based navigation (Single Page Applications):
+Set the `hash` attribute to auto-prepend `#` to href for single-page app routing.
 
 ```html
-<!-- Automatically prepends # to href -->
 <snice-link href="home" hash>Home</snice-link>
 <snice-link href="about" hash>About</snice-link>
 <snice-link href="contact" hash>Contact</snice-link>
-
 <!-- Renders as: <a href="#home">Home</a> -->
 ```
 
 ### Router Integration
 
-The `navigate` event allows decoupled router integration:
+Listen for the `navigate` event on hash links for custom routing.
 
 ```html
 <snice-link href="profile" hash id="profile-link">Profile</snice-link>
@@ -102,128 +86,60 @@ The `navigate` event allows decoupled router integration:
 <script>
   document.getElementById('profile-link').addEventListener('navigate', (e) => {
     console.log('Navigating to:', e.detail.href);
-
-    // Custom routing logic
-    myRouter.navigate(e.detail.href);
-
-    // Optionally prevent default navigation
-    // e.preventDefault();
-  });
-</script>
-```
-
-### Example Router Setup
-
-```html
-<nav>
-  <snice-link href="home" hash>Home</snice-link>
-  <snice-link href="products" hash>Products</snice-link>
-  <snice-link href="about" hash>About</snice-link>
-</nav>
-
-<script>
-  // Listen to all navigate events
-  document.addEventListener('navigate', (e) => {
-    const route = e.detail.href;
-
-    // Update view based on route
-    switch(route) {
-      case 'home':
-        showHomeView();
-        break;
-      case 'products':
-        showProductsView();
-        break;
-      case 'about':
-        showAboutView();
-        break;
-    }
+    // e.preventDefault() cancels default navigation
   });
 </script>
 ```
 
-## In Context
+### Inline Usage
 
-Links work naturally within text:
+Links display inline and work naturally within text.
 
 ```html
 <p>
-  This is a paragraph with an <snice-link href="/page">inline link</snice-link>
-  in the middle of the text.
+  Read our <snice-link href="/privacy" underline>privacy policy</snice-link>
+  for more details.
 </p>
 ```
 
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `click` | `MouseEvent` | Emitted when link is clicked (prevented if disabled) |
-| `navigate` | `{ href: string }` | Emitted on hash link click (bubbles, composed, cancelable) |
-
-## CSS Parts
-
-Use `::part()` to style internal elements:
-
-```css
-snice-link::part(link) {
-  font-weight: bold;
-}
+### Footer Links
 
-snice-link::part(external-icon) {
-  color: blue;
-}
+```html
+<footer>
+  <snice-link href="/privacy" variant="muted">Privacy</snice-link>
+  <snice-link href="/terms" variant="muted">Terms</snice-link>
+  <snice-link href="https://github.com" external variant="muted">GitHub</snice-link>
+</footer>
 ```
 
-## Theming
-
-The component uses these CSS custom properties:
+## Slots
 
-```css
---snice-color-primary
---snice-color-primary-dark
---snice-color-primary-darker
---snice-color-text
---snice-color-text-secondary
---snice-color-text-muted
---snice-color-text-disabled
---snice-transition-fast
-```
+| Name | Description |
+|------|-------------|
+| (default) | Link text content |
 
-## Accessibility
+## Properties
 
-- Proper `href` attribute for keyboard navigation
-- Correct `rel` attributes for external links
-- Disabled state prevents interaction
-- Screen reader friendly
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `href` | `string` | `''` | Link URL |
+| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | `'_self'` | Link target |
+| `variant` | `'default' \| 'primary' \| 'secondary' \| 'muted'` | `'default'` | Visual style |
+| `disabled` | `boolean` | `false` | Disables the link |
+| `external` | `boolean` | `false` | Opens in new tab with `noopener noreferrer` |
+| `underline` | `boolean` | `false` | Shows text underline |
+| `hash` | `boolean` | `false` | Auto-prepends `#` to href |
 
-## Examples
+## Events
 
-### Navigation Menu
-```html
-<nav>
-  <snice-link href="/">Home</snice-link>
-  <snice-link href="/about">About</snice-link>
-  <snice-link href="/contact">Contact</snice-link>
-</nav>
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `click` | `MouseEvent` | Fired on click (prevented when disabled) |
+| `navigate` | `{ href: string }` | Fired on hash link click, cancelable |
 
-### Footer Links
-```html
-<footer>
-  <snice-link href="/privacy" variant="muted">Privacy</snice-link>
-  <snice-link href="/terms" variant="muted">Terms</snice-link>
-  <snice-link href="https://twitter.com" external variant="muted">
-    Twitter
-  </snice-link>
-</footer>
-```
+## CSS Parts
 
-### Action Links
-```html
-<snice-link href="/download" variant="primary">
-  Download Now
-</snice-link>
-<snice-link href="/learn-more" variant="secondary">
-  Learn More
-</snice-link>
-```
+| Part | Description |
+|------|-------------|
+| `link` | The anchor element |
+| `external-icon` | The external link arrow icon |

package/docs/components/list.md

@@ -1,65 +1,161 @@
-# List Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/list.md instead)
 
-Display a list of items with optional selection, icons, and descriptions.
+# List
+`<snice-list>`
+
+A list container with search, infinite scroll, loading states, and composable list items.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/list/snice-list';
+```
+
 ```html
-<snice-list id="list"></snice-list>
-<script>
-  document.getElementById('list').items = [
-    { id: '1', label: 'Item 1', icon: '📄' },
-    { id: '2', label: 'Item 2', icon: '📄' }
-  ];
-</script>
+<snice-list>
+  <snice-list-item heading="Inbox" description="3 unread messages"></snice-list-item>
+  <snice-list-item heading="Drafts" description="2 drafts"></snice-list-item>
+  <snice-list-item heading="Sent" description="Last sent 2 hours ago"></snice-list-item>
+</snice-list>
 ```
 
-## Properties
+## Importing
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `items` | `ListItem[]` | `[]` | Array of items |
-| `selectionMode` | `'single' \| 'multiple' \| 'none'` | `'none'` | Selection mode |
-| `selectedItems` | `string[]` | `[]` | Selected item IDs |
-| `hoverable` | `boolean` | `true` | Hover effects |
-| `dividers` | `boolean` | `false` | Show dividers |
-| `dense` | `boolean` | `false` | Compact spacing |
+**ESM (bundler)**
+```typescript
+import 'snice/components/list/snice-list';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-list.min.js"></script>
+```
 
-## ListItem Interface
+## Examples
 
-```typescript
-interface ListItem {
-  id: string;
-  label: string;
-  description?: string;
-  icon?: string;
-  iconImage?: string;
-  disabled?: boolean;
-  selected?: boolean;
-  data?: any;
-}
+### Dividers
+
+Use the `dividers` attribute to show separator lines between items.
+
+```html
+<snice-list dividers>
+  <snice-list-item heading="General" description="General settings"></snice-list-item>
+  <snice-list-item heading="Security" description="Password and 2FA"></snice-list-item>
+  <snice-list-item heading="Notifications" description="Email preferences"></snice-list-item>
+</snice-list>
 ```
 
-## Methods
+### Items with Icons
 
-- `selectItem(id: string)` - Select item
-- `deselectItem(id: string)` - Deselect item
-- `toggleSelection(id: string)` - Toggle selection
-- `getSelectedItems(): ListItem[]` - Get selected items
+Use the `before` and `after` slots on list items for icons and metadata.
 
-## Events
+```html
+<snice-list dividers>
+  <snice-list-item heading="Downloads" description="Manage your files">
+    <span slot="before">📥</span>
+    <span slot="after">12</span>
+  </snice-list-item>
+  <snice-list-item heading="Uploads" description="View upload history">
+    <span slot="before">📤</span>
+    <span slot="after">5</span>
+  </snice-list-item>
+</snice-list>
+```
 
-- `@snice/list-item-select` - Item selected (detail: { item, selected, list })
+### Searchable List
 
-## Examples
+Set the `searchable` attribute to show a search input. Handle queries with the `@snice/list/search` request.
+
+```html
+<snice-list searchable dividers>
+  <snice-list-item heading="Alice Johnson"></snice-list-item>
+  <snice-list-item heading="Bob Smith"></snice-list-item>
+  <snice-list-item heading="Carol Williams"></snice-list-item>
+</snice-list>
+```
+
+### Infinite Scroll
+
+Set the `infinite` attribute inside a scrollable container to auto-load more items.
+
+```html
+<div style="height: 300px; overflow-y: auto;">
+  <snice-list infinite>
+    <snice-list-item heading="Item 1"></snice-list-item>
+    <snice-list-item heading="Item 2"></snice-list-item>
+  </snice-list>
+</div>
+```
+
+### Loading State
+
+Set the `loading` attribute to show skeleton placeholders.
 
 ```html
-<!-- With dividers -->
-<snice-list dividers></snice-list>
+<snice-list loading skeleton-count="3"></snice-list>
+```
+
+### No Results
 
-<!-- Single selection -->
-<snice-list selection-mode="single"></snice-list>
+Set the `no-results` attribute to show an empty state message.
 
-<!-- Dense -->
-<snice-list dense></snice-list>
+```html
+<snice-list no-results></snice-list>
 ```
+
+### Selected and Disabled Items
+
+```html
+<snice-list dividers>
+  <snice-list-item heading="Active Plan" selected></snice-list-item>
+  <snice-list-item heading="Enterprise" disabled></snice-list-item>
+</snice-list>
+```
+
+## List Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | List item elements |
+| `before` | Content before the list items |
+| `after` | Content after the list items |
+| `no-results` | Custom empty state (overrides default) |
+| `loading` | Custom loading content (overrides skeleton) |
+
+## List Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `dividers` | `boolean` | `false` | Shows separator lines between items |
+| `searchable` | `boolean` | `false` | Shows a search input |
+| `search` | `string` | `''` | Current search query value |
+| `infinite` | `boolean` | `false` | Enables infinite scroll loading |
+| `loading` | `boolean` | `false` | Shows loading skeletons |
+| `noResults` (attr: `no-results`) | `boolean` | `false` | Shows empty state |
+| `threshold` | `number` | `0.5` | Intersection threshold for infinite scroll |
+| `skeletonCount` (attr: `skeleton-count`) | `number` | `5` | Number of skeleton placeholders |
+
+## List Item Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `heading` | `string` | `''` | Item heading text |
+| `description` | `string` | `''` | Item description text |
+| `selected` | `boolean` | `false` | Highlights the item |
+| `disabled` | `boolean` | `false` | Disables interaction |
+
+## List Item Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Custom item content |
+| `before` | Content before the item (e.g., icon) |
+| `after` | Content after the item (e.g., badge) |
+
+## Requests
+
+| Request | Params | Description |
+|---------|--------|-------------|
+| `@snice/list/search` | `{ query: string, list }` | Handle search queries |
+| `@snice/list/load-more` | `{ page: number, list }` | Load next page for infinite scroll |