snice 4.8.0 → 4.10.0

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 |

package/docs/components/location.md

@@ -1,9 +1,16 @@
-# Location Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/location.md instead)
 
-Display location information with addresses, coordinates, maps, and custom icons.
+# Location
+`<snice-location>`
+
+Displays location information with addresses, coordinates, maps, and custom icons.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/location/snice-location';
+```
+
 ```html
 <snice-location
   name="Central Park"
@@ -15,100 +22,27 @@ Display location information with addresses, coordinates, maps, and custom icons
 </snice-location>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `mode` | `'full' \| 'compact' \| 'coordinates' \| 'address'` | `'full'` | Display mode |
-| `name` | `string` | `''` | Location name |
-| `address` | `string` | `''` | Street address |
-| `city` | `string` | `''` | City name |
-| `state` | `string` | `''` | State/province |
-| `country` | `string` | `''` | Country name |
-| `zipCode` | `string` | `''` | ZIP/postal code |
-| `latitude` | `number \| string` | `''` | Latitude coordinate |
-| `longitude` | `number \| string` | `''` | Longitude coordinate |
-| `showMap` | `boolean` | `false` | Show embedded map |
-| `showIcon` | `boolean` | `true` | Show location icon |
-| `icon` | `string` | `'📍'` | Icon (URL, image file, emoji, or font ligature) |
-| `iconImage` | `string` | `''` | Icon image URL (deprecated, use `icon`) |
-| `mapUrl` | `string` | `''` | Custom map URL |
-| `clickable` | `boolean` | `false` | Make location clickable |
-
-## Slots
-
-| Slot Name | Description |
-|-----------|-------------|
-| `icon` | Custom icon content. Overrides `icon` and `iconImage` properties. |
-
-### Icon Slot Usage
-
-Use the `icon` slot for external CSS-based icon fonts:
-
-```html
-<snice-location name="Office" address="123 Main St">
-  <span slot="icon" class="material-symbols-outlined">business</span>
-</snice-location>
+## Importing
 
-<snice-location name="Restaurant" city="New York" clickable>
-  <i slot="icon" class="fa-solid fa-utensils"></i>
-</snice-location>
-```
-
-## Methods
-
-### `getData(): LocationData`
-Get complete location data object.
-
-```javascript
-const data = location.getData();
-console.log(data.name, data.latitude, data.longitude);
-```
-
-### `getCoordinates(): { latitude: number; longitude: number } | null`
-Get coordinate pair or null if invalid.
-
-```javascript
-const coords = location.getCoordinates();
-if (coords) {
-  console.log(`${coords.latitude}, ${coords.longitude}`);
-}
+**ESM (bundler)**
+```typescript
+import 'snice/components/location/snice-location';
 ```
 
-### `getFullAddress(): string`
-Get formatted full address string.
-
-```javascript
-const address = location.getFullAddress();
-// "123 Main St, New York, NY, 10001, USA"
-```
-
-### `openMap(): void`
-Open location in maps application (new tab).
-
-```javascript
-location.openMap();
-```
-
-## Events
-
-### `location-click`
-Dispatched when clickable location is clicked.
-
-```javascript
-location.addEventListener('location-click', (e) => {
-  console.log('Location clicked:', e.detail);
-});
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-location.min.js"></script>
 ```
 
-**Detail:** `LocationData` object
-
 ## Examples
 
 ### Display Modes
 
+Use the `mode` attribute to control what information is shown.
+
 ```html
-<!-- Full mode (default) -->
+<!-- Full mode (default) - shows name, address, and coordinates -->
 <snice-location
   name="Empire State Building"
   address="350 5th Ave"
@@ -120,93 +54,77 @@ location.addEventListener('location-click', (e) => {
 </snice-location>
 
 <!-- Compact mode -->
-<snice-location
-  name="Times Square"
-  address="Times Square"
-  city="New York"
-  latitude="40.7580"
-  longitude="-73.9855"
-  mode="compact">
-</snice-location>
+<snice-location name="Times Square" city="New York" mode="compact"></snice-location>
 
 <!-- Coordinates only -->
-<snice-location
-  latitude="40.7580"
-  longitude="-73.9855"
-  mode="coordinates">
-</snice-location>
+<snice-location latitude="40.7580" longitude="-73.9855" mode="coordinates"></snice-location>
 
 <!-- Address only -->
-<snice-location
-  name="Brooklyn Bridge"
-  address="Brooklyn Bridge"
-  city="New York"
-  state="NY"
-  mode="address">
-</snice-location>
+<snice-location name="Brooklyn Bridge" city="New York" state="NY" mode="address"></snice-location>
 ```
 
 ### Custom Icons
 
+Use the `icon` attribute for emoji or the `icon` slot for external icon fonts.
+
 ```html
 <!-- Emoji icon -->
-<snice-location
-  name="Office"
-  address="123 Business Blvd"
-  icon="🏢">
-</snice-location>
+<snice-location name="Office" address="123 Business Blvd" icon="🏢"></snice-location>
 
 <!-- Image icon -->
-<snice-location
-  name="Store"
-  address="456 Shopping Ave"
-  icon-image="/icons/store.svg">
+<snice-location name="Store" address="456 Shopping Ave" icon-image="/icons/store.svg"></snice-location>
+
+<!-- Icon slot (for CSS icon fonts) -->
+<snice-location name="Restaurant" city="New York">
+  <span slot="icon" class="material-symbols-outlined">restaurant</span>
 </snice-location>
 
 <!-- No icon -->
-<snice-location
-  name="Home"
-  address="789 Residential St"
-  show-icon="false">
-</snice-location>
+<snice-location name="Home" address="789 Elm St" show-icon="false"></snice-location>
 ```
 
-### Interactive Locations
+### Clickable Locations
+
+Set the `clickable` attribute to make the location interactive.
 
 ```html
-<!-- Clickable location -->
 <snice-location
   name="Golden Gate Bridge"
   latitude="37.8199"
   longitude="-122.4783"
   clickable>
 </snice-location>
-
-<!-- Custom map URL -->
-<snice-location
-  name="Custom Location"
-  latitude="34.0522"
-  longitude="-118.2437"
-  clickable
-  map-url="https://www.openstreetmap.org/?mlat=34.0522&mlon=-118.2437">
-</snice-location>
 ```
 
 ### Embedded Maps
 
+Set the `show-map` attribute to display an embedded Google Maps iframe.
+
 ```html
-<!-- Show embedded map -->
 <snice-location
   name="Statue of Liberty"
   address="Liberty Island"
   city="New York"
-  state="NY"
   latitude="40.6892"
   longitude="-74.0445"
   show-map>
 </snice-location>
 ```
 
+### Custom Map URL
+
+Use `map-url` to link to an alternative maps provider.
+
+```html
+<snice-location
+  name="Custom Location"
+  latitude="34.0522"
+  longitude="-118.2437"
+  clickable
+  map-url="https://www.openstreetmap.org/?mlat=34.0522&mlon=-118.2437">
+</snice-location>
+```
+
 ### Complete Address
 
 ```html
@@ -223,147 +141,10 @@ location.addEventListener('location-click', (e) => {
 </snice-location>
 ```
 
-### Restaurant Location
+### Programmatic Usage
 
-```html
-<snice-location
-  name="Blue Hill"
-  address="75 Washington Pl"
-  city="New York"
-  state="NY"
-  zip-code="10011"
-  latitude="40.7308"
-  longitude="-73.9973"
-  icon="🍽️"
-  clickable>
-</snice-location>
-```
-
-### Park Location
-
-```html
-<snice-location
-  name="Millennium Park"
-  address="201 E Randolph St"
-  city="Chicago"
-  state="IL"
-  latitude="41.8826"
-  longitude="-87.6226"
-  icon="🌳"
-  mode="full"
-  clickable>
-</snice-location>
-```
-
-### Airport Location
-
-```html
-<snice-location
-  name="LAX"
-  address="1 World Way"
-  city="Los Angeles"
-  state="CA"
-  zip-code="90045"
-  latitude="33.9416"
-  longitude="-118.4085"
-  icon="✈️"
-  clickable>
-</snice-location>
-```
-
-### Hospital Location
-
-```html
-<snice-location
-  name="Mayo Clinic"
-  address="200 First St SW"
-  city="Rochester"
-  state="MN"
-  zip-code="55905"
-  latitude="44.0225"
-  longitude="-92.4666"
-  icon="🏥"
-  show-map>
-</snice-location>
-```
-
-### University Location
-
-```html
-<snice-location
-  name="MIT"
-  address="77 Massachusetts Ave"
-  city="Cambridge"
-  state="MA"
-  zip-code="02139"
-  latitude="42.3601"
-  longitude="-71.0942"
-  icon="🎓"
-  mode="compact"
-  clickable>
-</snice-location>
-```
-
-### Hotel Location
-
-```html
-<snice-location
-  name="The Plaza Hotel"
-  address="768 5th Ave"
-  city="New York"
-  state="NY"
-  zip-code="10019"
-  latitude="40.7643"
-  longitude="-73.9747"
-  icon="🏨"
-  clickable>
-</snice-location>
-```
-
-### Museum Location
-
-```html
-<snice-location
-  name="The Met"
-  address="1000 5th Ave"
-  city="New York"
-  state="NY"
-  zip-code="10028"
-  latitude="40.7794"
-  longitude="-73.9632"
-  icon="🏛️"
-  show-map>
-</snice-location>
-```
-
-### Stadium Location
-
-```html
-<snice-location
-  name="Yankee Stadium"
-  address="1 E 161st St"
-  city="Bronx"
-  state="NY"
-  zip-code="10451"
-  latitude="40.8296"
-  longitude="-73.9262"
-  icon="⚾"
-  clickable>
-</snice-location>
-```
-
-## Programmatic Usage
-
-```javascript
-const location = document.createElement('snice-location');
-location.name = 'Central Park';
-location.latitude = 40.7829;
-location.longitude = -73.9654;
-location.clickable = true;
-
-location.addEventListener('location-click', (e) => {
-  console.log('Clicked:', e.detail);
-});
+```typescript
+const location = document.querySelector('snice-location');
 
 // Get data
 const data = location.getData();
@@ -372,18 +153,50 @@ const address = location.getFullAddress();
 
 // Open in maps
 location.openMap();
+
+// Listen for clicks
+location.addEventListener('location-click', (e) => {
+  console.log('Clicked:', e.detail);
+});
 ```
 
-## Accessibility
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `icon` | Custom icon content (overrides `icon` and `iconImage` properties) |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'full' \| 'compact' \| 'coordinates' \| 'address'` | `'full'` | Display mode |
+| `name` | `string` | `''` | Location name |
+| `address` | `string` | `''` | Street address |
+| `city` | `string` | `''` | City name |
+| `state` | `string` | `''` | State or province |
+| `country` | `string` | `''` | Country name |
+| `zipCode` (attr: `zip-code`) | `string` | `''` | ZIP/postal code |
+| `latitude` | `number \| string` | `''` | Latitude coordinate |
+| `longitude` | `number \| string` | `''` | Longitude coordinate |
+| `showMap` (attr: `show-map`) | `boolean` | `false` | Show embedded map |
+| `showIcon` (attr: `show-icon`) | `boolean` | `true` | Show location icon |
+| `icon` | `string` | `'📍'` | Icon (emoji, URL, or font ligature) |
+| `iconImage` (attr: `icon-image`) | `string` | `''` | Icon image URL |
+| `mapUrl` (attr: `map-url`) | `string` | `''` | Custom map URL |
+| `clickable` | `boolean` | `false` | Make location clickable |
+
+## Events
 
-- Use descriptive `name` attributes for screen readers
-- Clickable locations are keyboard accessible
-- Icons should be decorative; location name provides context
-- Map iframes include proper loading attributes
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `location-click` | `LocationData` | Fired when a clickable location is clicked |
 
-## Browser Support
+## Methods
 
-- Modern browsers with Custom Elements v1 support
-- Embedded maps require internet connection
-- Default map provider is Google Maps
-- Custom map URLs can use alternative providers
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `getData()` | -- | Returns complete LocationData object |
+| `getCoordinates()` | -- | Returns `{ latitude, longitude }` or null |
+| `getFullAddress()` | -- | Returns formatted address string |
+| `openMap()` | -- | Opens location in maps (new tab) |