snice 4.27.0 → 4.29.0

package/docs/components/list.md

@@ -1,24 +1,27 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/list.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/list.md -->
 
 # List
 `<snice-list>`
 
 A list container with search, infinite scroll, loading states, and composable list items.
 
-## Importing
+## Table of Contents
+- [Components](#components)
+- [Properties](#properties)
+- [Requests](#requests)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
-**ESM (bundler)**
-```typescript
-import 'snice/components/list/snice-list';
-```
+## Components
 
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-list.min.js"></script>
-```
+- `<snice-list>` - The list container with search, infinite scroll, and loading support
+- `<snice-list-item>` - Individual list item with heading, description, and slot areas
+
+## Properties
 
-## List Properties
+### snice-list
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -31,7 +34,7 @@ import 'snice/components/list/snice-list';
 | `threshold` | `number` | `0.5` | Intersection threshold for infinite scroll |
 | `skeletonCount` (attr: `skeleton-count`) | `number` | `5` | Number of skeleton placeholders |
 
-## List Item Properties
+### snice-list-item
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
@@ -40,7 +43,18 @@ import 'snice/components/list/snice-list';
 | `selected` | `boolean` | `false` | Highlights the item |
 | `disabled` | `boolean` | `false` | Disables interaction |
 
-## List Slots
+## Requests
+
+The list uses `@request`/`@respond` for controller-driven data flow.
+
+| Request | Params | Description |
+|---------|--------|-------------|
+| `list/search` | `{ query: string, list }` | Handle search queries (debounced 300ms) |
+| `list/load-more` | `{ page: number, list }` | Load next page for infinite scroll |
+
+## Slots
+
+### snice-list
 
 | Name | Description |
 |------|-------------|
@@ -48,15 +62,26 @@ import 'snice/components/list/snice-list';
 | `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) |
+| `loading` | Custom loading content (overrides skeletons) |
 
-## List Item Slots
+### snice-list-item
 
 | Name | Description |
 |------|-------------|
 | (default) | Custom item content |
-| `before` | Content before the item (e.g., icon) |
-| `after` | Content after the item (e.g., badge) |
+| `before` | Content before the item (e.g., icon, avatar) |
+| `after` | Content after the item (e.g., badge, metadata) |
+
+## CSS Parts
+
+### snice-list
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `container` | `<div>` | The outer list container |
+| `search` | `<div>` | The search input wrapper |
+| `loading` | `<div>` | The loading skeletons wrapper |
+| `sentinel` | `<div>` | The infinite scroll sentinel element |
 
 ## Basic Usage
 
@@ -105,7 +130,7 @@ Use the `before` and `after` slots on list items for icons and metadata.
 
 ### Searchable List
 
-Set the `searchable` attribute to show a search input. Handle queries with the `list/search` request.
+Set the `searchable` attribute to show a search input. Handle queries with a `list/search` responder.
 
 ```html
 <snice-list searchable dividers>
@@ -152,10 +177,3 @@ Set the `no-results` attribute to show an empty state message.
   <snice-list-item heading="Enterprise" disabled></snice-list-item>
 </snice-list>
 ```
-
-## Requests
-
-| Request | Params | Description |
-|---------|--------|-------------|
-| `list/search` | `{ query: string, list }` | Handle search queries |
-| `list/load-more` | `{ page: number, list }` | Load next page for infinite scroll |

package/docs/components/location.md

@@ -1,22 +1,18 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/location.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/location.md -->
 
 # Location
 `<snice-location>`
 
 Displays location information with addresses, coordinates, maps, and custom icons.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/location/snice-location';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-location.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
 
 ## Properties
 

package/docs/components/login.md

@@ -1,22 +1,20 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/login.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/login.md -->
 
 # Login
 `<snice-login>`
 
 A complete authentication form with username/password fields, using Snice's @request/@respond pattern for controller communication.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/login/snice-login';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-login.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Requests](#requests)
+- [Events](#events)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -35,12 +33,36 @@ import 'snice/components/login/snice-login';
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `login()` | `credentials?: LoginCredentials` | Trigger login (uses form values if no args) |
+| `login()` | `credentials?: LoginCredentials` | Trigger login via @request (uses form values if no args) |
 | `reset()` | -- | Clear form, error, and loading state |
 | `setError()` | `message: string` | Display an error message |
 | `clearError()` | -- | Remove error message |
 | `setCredentials()` | `credentials: Partial<LoginCredentials>` | Set form field values |
 
+## Requests
+
+The login component uses `@request('login-user')` to communicate with an authentication controller.
+
+| Request | Params | Description |
+|---------|--------|-------------|
+| `login-user` | `LoginCredentials` | Sent to controller on login attempt |
+
+### Types
+
+```typescript
+interface LoginCredentials {
+  username: string;
+  password: string;
+  remember?: boolean;
+}
+
+interface LoginResult {
+  success: boolean;
+  error?: string;
+  data?: any;
+}
+```
+
 ## Events
 
 | Event | Detail | Description |
@@ -154,8 +176,6 @@ Use `title` and `action-text` to customize the form text.
 
 ### Request/Respond Pattern
 
-The login component uses `@request('login-user')` to communicate with an authentication controller.
-
 ```typescript
 import { controller, respond, IController } from 'snice';
 import type { LoginCredentials, LoginResult } from 'snice/components/login/snice-login.types';
@@ -216,24 +236,10 @@ login.clearError();
 login.reset();
 ```
 
-## Request/Respond Types
-
-```typescript
-interface LoginCredentials {
-  username: string;
-  password: string;
-  remember?: boolean;
-}
+## Accessibility
 
-interface LoginResult {
-  success: boolean;
-  error?: string;
-  data?: any;
-}
-```
-
-## Requests
-
-| Request | Params | Description |
-|---------|--------|-------------|
-| `login-user` | `LoginCredentials` | Sent to controller on login attempt |
+- Form inputs use proper `<label>` elements with `for` attributes
+- Inputs have `autocomplete` attributes (`username`, `current-password`)
+- Enter key on password field triggers form submission
+- Loading and disabled states propagate to all form inputs and the submit button
+- Required fields are marked with the `required` attribute

package/docs/components/map.md

@@ -1,35 +1,19 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/map.md instead -->
-
-# Map Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/map.md -->
 
+# Map
 `<snice-map>`
 
 An interactive slippy map component using OpenStreetMap tiles. Supports markers with popups, drag panning, scroll zoom, and programmatic control over the viewport.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
-- [Types](#types)
 - [Accessibility](#accessibility)
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/map/snice-map';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-map.min.js"></script>
-```
-
 ## Properties
 
 | Property | Type | Default | Description |
@@ -41,6 +25,24 @@ import 'snice/components/map/snice-map';
 | `markers` | `MapMarker[]` | `[]` | Array of marker data (set via JavaScript) |
 | `tileUrl` (attr: `tile-url`) | `string` | `'https://tile.openstreetmap.org/{z}/{x}/{y}.png'` | Tile server URL template with `{x}`, `{y}`, `{z}` placeholders |
 
+### Types
+
+```typescript
+interface MapCenter {
+  lat: number;
+  lng: number;
+}
+
+interface MapMarker {
+  id: string;       // Unique identifier
+  lat: number;      // Latitude
+  lng: number;      // Longitude
+  label?: string;   // Marker label text
+  icon?: string;    // Custom icon URL
+  popup?: string;   // Popup text shown on marker click
+}
+```
+
 ## Methods
 
 | Method | Arguments | Description |
@@ -55,9 +57,9 @@ import 'snice/components/map/snice-map';
 
 | Event | Detail | Description |
 |-------|--------|-------------|
-| `map-click` | `{ lat: number; lng: number }` | Fired when the map is clicked (not on a marker) |
+| `map-click` | `{ lat: number, lng: number }` | Fired when the map is clicked (not on a marker) |
 | `marker-click` | `{ marker: MapMarker }` | Fired when a marker is clicked. Also toggles the marker's popup |
-| `map-move` | `{ center: MapCenter; zoom: number }` | Fired after a drag pan operation completes |
+| `map-move` | `{ center: MapCenter, zoom: number }` | Fired after a drag pan operation completes |
 | `map-zoom` | `{ zoom: number }` | Fired when the zoom level changes |
 
 ## CSS Parts
@@ -194,34 +196,10 @@ Use the `tile-url` attribute to load tiles from a different provider.
 ></snice-map>
 ```
 
-## Types
-
-### MapCenter
-
-```typescript
-interface MapCenter {
-  lat: number;
-  lng: number;
-}
-```
-
-### MapMarker
-
-```typescript
-interface MapMarker {
-  id: string;       // Unique identifier
-  lat: number;      // Latitude
-  lng: number;      // Longitude
-  label?: string;   // Marker label text
-  icon?: string;    // Custom icon URL
-  popup?: string;   // Popup text shown on marker click
-}
-```
-
 ## Accessibility
 
-- The map supports mouse drag to pan and scroll wheel to zoom
-- Zoom in/out buttons are provided in the top-right corner for keyboard and pointer access
+- Mouse drag to pan, scroll wheel to zoom
+- Zoom in/out buttons in the top-right corner for keyboard and pointer access
 - Markers are interactive and toggle popup display on click
 - OpenStreetMap attribution is included automatically
 - For keyboard-only users, the zoom buttons provide an accessible alternative to scroll-wheel zoom

package/docs/components/markdown.md

@@ -1,16 +1,15 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/markdown.md instead -->
-
-# Markdown Component
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/markdown.md -->
 
+# Markdown
 `<snice-markdown>`
 
 A lightweight GFM-compatible markdown renderer that converts markdown text to styled HTML inside shadow DOM. Includes built-in sanitization to prevent XSS attacks.
 
 ## Table of Contents
-- [Importing](#importing)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
+- [Slots](#slots)
 - [CSS Custom Properties](#css-custom-properties)
 - [CSS Parts](#css-parts)
 - [Basic Usage](#basic-usage)
@@ -18,19 +17,6 @@ A lightweight GFM-compatible markdown renderer that converts markdown text to st
 - [Supported Syntax](#supported-syntax)
 - [Accessibility](#accessibility)
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/markdown/snice-markdown';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-markdown.min.js"></script>
-```
-
 ## Properties
 
 | Property | Type | Default | Description |
@@ -38,18 +24,26 @@ import 'snice/components/markdown/snice-markdown';
 | `sanitize` | `boolean` | `true` | Whether to sanitize the HTML output to prevent XSS |
 | `theme` | `'default' \| 'github'` | `'default'` | Visual theme for the rendered output |
 
+> **Note:** The `content` field is a plain class property, not a reactive `@property`. Use `setContent()` to update content programmatically, or provide text as slotted content.
+
 ## Methods
 
 | Method | Arguments | Description |
 |--------|-----------|-------------|
-| `setContent()` | `markdown: string` | Set the markdown source programmatically |
+| `setContent()` | `markdown: string` | Set the markdown source programmatically and re-render |
 
 ## Events
 
 | Event | Detail | Description |
 |-------|--------|-------------|
 | `markdown-render` | `{ html: string }` | Fired after the markdown has been rendered to HTML |
-| `link-click` | `{ href: string; text: string }` | Fired when a link in the rendered content is clicked. Default navigation is prevented |
+| `link-click` | `{ href: string, text: string }` | Fired when a link in the rendered content is clicked. Default navigation is prevented |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| (default) | Markdown source text (read on connect and slotchange) |
 
 ## CSS Custom Properties
 
@@ -155,7 +149,7 @@ Use the `theme="github"` attribute for GitHub-style markdown rendering.
 
 ### Intercepting Link Clicks
 
-Listen for the `link-click` event to handle navigation within your application instead of following the default link behavior.
+Listen for the `link-click` event to handle navigation within your application.
 
 ```html
 <snice-markdown id="docs">Check out [the documentation](/docs) or visit [our website](https://example.com).</snice-markdown>
@@ -169,7 +163,6 @@ Listen for the `link-click` event to handle navigation within your application i
     const { href, text } = e.detail;
     console.log(`Link clicked: "${text}" -> ${href}`);
 
-    // Handle internal navigation
     if (href.startsWith('/')) {
       window.history.pushState({}, '', href);
     } else {
@@ -181,13 +174,9 @@ Listen for the `link-click` event to handle navigation within your application i
 
 ### Code Blocks and Tables
 
-Render markdown that includes fenced code blocks and GFM tables.
-
 ```html
 <snice-markdown>## API Response
 
-The endpoint returns the following JSON:
-
 | Code | Meaning |
 |------|---------|
 | 200  | Success |

package/docs/components/masonry.md

@@ -1,22 +1,17 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/masonry.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/masonry.md -->
 
 # Masonry
 `<snice-masonry>`
 
 A Pinterest-style layout that arranges items in columns with variable heights using CSS columns.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/masonry/snice-masonry';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-masonry.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Slots](#slots)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
 
 ## Properties
 
@@ -135,3 +130,10 @@ Use the `gap` attribute with any CSS length value.
   });
 </script>
 ```
+
+## Accessibility
+
+- The masonry container has `role="list"` for screen readers
+- Items flow top-to-bottom, left-to-right within CSS columns
+- `break-inside: avoid` prevents items from splitting across columns
+- CSS columns-based layout requires no JavaScript measurement

package/docs/components/mentions.md

@@ -1,34 +1,31 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/mentions.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/mentions.md -->
 
 # Mentions
 `<snice-mentions>`
 
 A text input with inline @mention autocomplete. Typing the trigger character shows a filtered user list dropdown, and selected mentions are stored as structured markers in the value.
 
-## Importing
-
-**ESM (bundler)**
-```typescript
-import 'snice/components/mentions/snice-mentions';
-```
-
-**CDN**
-```html
-<script src="snice-runtime.min.js"></script>
-<script src="snice-mentions.min.js"></script>
-```
+## Table of Contents
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [CSS Parts](#css-parts)
+- [Basic Usage](#basic-usage)
+- [Examples](#examples)
+- [Keyboard Navigation](#keyboard-navigation)
+- [Accessibility](#accessibility)
 
 ## Properties
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `value` | `string` | `''` | Raw text with `@[Name](id)` mention markers |
-| `users` | `MentionUser[]` | `[]` | Users available for autocomplete |
+| `users` | `MentionUser[]` | `[]` | Users available for autocomplete (set via JavaScript) |
 | `placeholder` | `string` | `'Type @ to mention someone...'` | Input placeholder text |
 | `readonly` | `boolean` | `false` | Prevents editing |
 | `trigger` | `string` | `'@'` | Character that triggers the autocomplete dropdown |
 
-### MentionUser Interface
+### Types
 
 ```typescript
 interface MentionUser {
@@ -36,11 +33,7 @@ interface MentionUser {
   name: string;
   avatar?: string;
 }
-```
 
-### Mention Interface
-
-```typescript
 interface Mention {
   id: string;
   name: string;
@@ -67,12 +60,14 @@ interface Mention {
 
 ## CSS Parts
 
-| Part | Description |
-|------|-------------|
-| `base` | Wrapper container |
-| `editor` | Editor container with border |
-| `textarea` | The textarea element |
-| `dropdown` | Autocomplete dropdown |
+Style internal elements from outside the shadow DOM using `::part()`.
+
+| Part | Element | Description |
+|------|---------|-------------|
+| `base` | `<div>` | Wrapper container |
+| `editor` | `<div>` | Editor container with border |
+| `textarea` | `<textarea>` | The textarea element |
+| `dropdown` | `<div>` | Autocomplete dropdown |
 
 ## Basic Usage
 
@@ -171,3 +166,19 @@ editor.addEventListener('value-change', e => {
   console.log('Mentions:', e.detail.mentions);
 });
 ```
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Arrow Down | Move to next item in dropdown |
+| Arrow Up | Move to previous item in dropdown |
+| Enter / Tab | Select highlighted item |
+| Escape | Close dropdown |
+
+## Accessibility
+
+- The textarea has `aria-autocomplete="list"` and `aria-haspopup="listbox"`
+- Dropdown items have `role="option"` with `aria-selected` for the highlighted item
+- The dropdown has `role="listbox"`
+- Avatar placeholders show user initials when no image is provided