snice 2.5.4 → 3.1.0

package/docs/ai/api.md

@@ -0,0 +1,175 @@
+# API Reference
+
+## Class Decorators
+
+```typescript
+@element('tag-name') // Define custom element
+@page({ tag, routes, guards?, placard? }) // Define routable page
+@controller('name') // Define behavior module
+@layout('name') // Define page wrapper
+```
+
+## Rendering
+
+```typescript
+@render(options?: { debounce?, throttle?, once?, sync?, differential? })
+// Returns: TemplateResult from html`...` (or string if differential: false)
+// Auto re-renders on property changes
+// Supports differential updates by default
+// differential: false - disables differential rendering, expects string return
+//   Clears shadow root and re-renders from scratch each time
+//   Still honors <if> and <switch>/<case> meta elements
+
+@styles()
+// Returns: CSSResult from css`...`
+// Scoped to shadow DOM
+```
+
+## Properties
+
+```typescript
+@property(options?: { type?, attribute?, reflect? })
+// Syncs with attributes, triggers re-render
+// Types: String (default), Number, Boolean, Object, Array
+
+@watch(...propertyNames: string[])
+// Called on property change: (oldVal, newVal) => void
+```
+
+## Lifecycle
+
+```typescript
+@ready() // After initial render
+@dispose() // On disconnectedCallback
+@moved() // On adoptedCallback
+@adopted() // On adoptedCallback
+```
+
+## DOM Queries
+
+```typescript
+@query(selector: string) // Single element
+@queryAll(selector: string) // NodeListOf<Element>
+```
+
+## Events
+
+**Template syntax:**
+```typescript
+html`
+  <button @click=${handler}>...</button>
+  <input @keydown:Enter=${handler} />
+  <input @keydown.ctrl+s=${handler} />
+  <input .value=${val} ?disabled=${bool} />
+`
+```
+
+**Decorator:**
+```typescript
+@on(event: string | string[], selector?: string, options?: OnOptions)
+// Works in elements + controllers
+// Options: { debounce?, throttle?, preventDefault?, stopPropagation?, once?, capture?, passive?, target? }
+// target: CSS selector for shadow DOM event delegation
+// Keyboard: 'keydown:Enter', 'keydown.escape', 'keydown:ctrl+s', 'keydown:~Space'
+// Supports both ':' and '.' notation
+
+@dispatch(eventName: string)
+// Fires CustomEvent after method, detail = return value
+```
+
+## Communication
+
+```typescript
+@request(channel: string)
+// Send: this.methodName(data) → Promise<response>
+
+@respond(channel: string)
+// Receive: methodName(request, respond) → respond(data)
+```
+
+## Observers
+
+```typescript
+@observe(target: () => Node, options?: MutationObserverInit)
+// Auto-cleanup on disconnect
+// Method called with: (mutations: MutationRecord[])
+```
+
+## Context & Router
+
+```typescript
+@context(options?: { debounce?, throttle?, once? })
+// Method decorator: receives Context object on router navigation
+// Method signature: (ctx: Context) => void
+// Context: { application, navigation: { placards, route, params }, update() }
+// Call ctx.update() after modifying ctx.application to notify all subscribers
+// Options:
+//   debounce (ms) - wait for quiet period before calling
+//   throttle (ms) - limit to at most once per period
+//   once - call only once then unregister
+// Example:
+//   @context() handleContext(ctx) {
+//     this.ctx = ctx;
+//     ctx.application.user = user;
+//     ctx.update(); // notify all subscribers
+//   }
+
+Router({ target, context?, layout? })
+// Returns: { page, navigate, initialize }
+// page() - decorator factory
+// navigate(path) - programmatic navigation
+// initialize() - start router
+```
+
+## Templates
+
+```typescript
+html`...` // TemplateResult
+css`...` // CSSResult
+
+// Conditionals
+<if ${condition}>...</if>
+<case ${value}>
+  <when value="x">...</when>
+  <default>...</default>
+</case>
+
+// Lists
+${items.map(i => html`<li>${i}</li>`)}
+
+// Bindings
+attr="${val}" // Attribute
+.prop="${val}" // Property
+?attr="${bool}" // Boolean attribute
+@event="${handler}" // Event listener
+@event:modifier="${handler}" // With keyboard modifier
+```
+
+## Types
+
+```typescript
+interface TemplateResult { readonly _$litType$: number; }
+interface CSSResult { cssText: string; }
+interface OnOptions { debounce?, throttle?, preventDefault?, stopPropagation?, once?, capture?, passive?, target? }
+interface RenderOptions { debounce?, throttle?, once?, sync? }
+interface Layout { update(context, placards, route, params) }
+interface Placard { name, title, icon?, description?, order?, show?, visibleOn?, parent?, group?, searchTerms?, hotkeys?, breadcrumbs?, tooltip? }
+type Guard<T> = (context: T) => boolean | Promise<boolean>
+```
+
+## Exports
+
+```typescript
+import {
+  element, page, controller, layout,
+  property, watch, context,
+  render, styles, html, css,
+  query, queryAll,
+  on, dispatch,
+  request, respond,
+  observe,
+  ready, dispose, moved, adopted,
+  Router,
+  debounce, throttle, once, memoize
+} from 'snice';
+```

package/docs/ai/architecture.md

@@ -0,0 +1,160 @@
+# Architecture
+
+## Core Principles
+
+**Separation of concerns:**
+- **Cross-cutting:** Router + global context
+- **Pages:** Orchestrate elements, handle URLs
+- **Elements:** Pure presentation, no business logic
+- **Controllers:** Behavior, data fetching, swappable
+
+**Data flow:**
+- Down: Properties
+- Up: Events
+- Sideways: Request/Response channels
+
+## Rendering System
+
+**Template compilation:**
+1. `html\`...\`` → TemplateResult
+2. Parse template, identify dynamic parts
+3. Create Template with Part instances
+4. TemplateInstance tracks values
+
+**Part types:**
+- NodePart: Text content
+- AttributePart: `attr="${val}"`
+- PropertyPart: `.prop="${val}"`
+- BooleanAttributePart: `?attr="${bool}"`
+- EventPart: `@event="${handler}"`
+- IfPart: `<if>` conditional
+- CasePart: `<case>/<when>` branching
+
+**Differential updates:**
+- Only changed Parts re-render
+- DOM nodes reused, not recreated
+- Event listeners preserved
+- Batched via microtask queue
+
+**Auto-rendering:**
+- Property setters trigger queueRender()
+- Batches multiple changes
+- Calls @render() method
+- Updates TemplateInstance
+
+## Decorator System
+
+**Metadata storage:**
+- Symbols prevent collisions
+- Stored on prototype/class
+- Retrieved during lifecycle
+
+**Element lifecycle:**
+1. Constructor
+2. connectedCallback → setupEventHandlers, initial render
+3. attributeChangedCallback → property sync
+4. @ready() → after first render
+5. Property changes → auto re-render
+6. disconnectedCallback → cleanup
+
+**Controller lifecycle:**
+1. Element sets controller="name"
+2. attributeChangedCallback detects change
+3. Detach old controller (if any)
+4. Attach new controller
+5. setupEventHandlers for controller
+6. On detach: cleanupEventHandlers
+
+## Router System
+
+**Registration:**
+- @page() stores { tag, routes, guards, placard }
+- Router.initialize() registers pages
+- Path-to-RegExp for route matching
+
+**Navigation:**
+1. navigate(path) or URL change
+2. Match route → page config
+3. Run guards (abort if fail)
+4. Update layout (if present)
+5. Create/reuse page element
+6. Extract params → page properties
+7. Slot into layout or target
+
+**Layouts:**
+- Persistent wrapper around pages
+- Receives placard metadata
+- update() called on navigation
+- `<slot name="page">` for content
+
+## Event System
+
+**Template events:**
+- EventPart handles `@event="${handler}"`
+- Supports keyboard modifiers via parseKeyboardFilter()
+- Both `:` and `.` notation
+- Listeners on actual elements
+
+**@on decorator:**
+- Stores handler metadata
+- setupEventHandlers creates listeners
+- Supports delegation with selectors
+- Uses same parseKeyboardFilter() as templates
+- Auto cleanup on disconnect
+
+**Keyboard syntax:**
+```
+@keydown:Enter → { key: "Enter" }
+@keydown:ctrl+s → { key: "s", ctrl: true }
+@keydown:~Space → { key: " ", anyModifiers: true }
+@keydown.escape → { key: "Escape" }
+```
+
+## Communication Patterns
+
+**Parent → Child:** Properties
+```typescript
+html`<child-el .data=${this.data}></child-el>`
+```
+
+**Child → Parent:** Events
+```typescript
+@dispatch('changed')
+onChange() { return { value: this.value }; }
+```
+
+**Element ↔ Controller:** Request/Response
+```typescript
+// Element requests, controller responds
+@request('channel') method!: (data) => Promise<result>
+@respond('channel') handler(req, respond) { respond(data); }
+```
+
+**Global State:** Context
+```typescript
+@context() handleContext(ctx: Context) {
+  this.app = ctx.application;
+  this.route = ctx.navigation.route;
+}
+```
+
+## Shadow DOM
+
+- All elements use shadow DOM (mode: 'open')
+- Styles scoped automatically
+- Events cross boundary with composed: true
+- Query selectors work within shadowRoot
+
+## Performance
+
+**Optimizations:**
+- Template caching (Map<TemplateStringsArray, Template>)
+- Part reuse (no DOM recreation)
+- Microtask batching (queueMicrotask)
+- Debounce/throttle built-in
+- Conditional rendering (IfPart, CasePart)
+
+**Trade-offs:**
+- Initial template parsing overhead
+- Memory for TemplateInstance per element
+- Benefit: Much faster updates

package/docs/ai/components/accordion.md

@@ -0,0 +1,174 @@
+# snice-accordion & snice-accordion-item
+
+Collapsible sections with single or multiple open mode and keyboard navigation.
+
+## Components
+
+### snice-accordion
+
+Container managing accordion items.
+
+```typescript
+multiple: boolean = false;  // Allow multiple items open
+```
+
+**Methods:**
+- `openItem(id)` - Open specific item
+- `closeItem(id)` - Close specific item
+- `toggleItem(id)` - Toggle specific item
+- `openAll()` - Open all (multiple mode only)
+- `closeAll()` - Close all
+
+**Events:**
+- `@snice/accordion-open` - {itemId, item}
+- `@snice/accordion-close` - {itemId, item}
+
+### snice-accordion-item
+
+Individual collapsible section.
+
+```typescript
+itemId: string;              // Auto-generated if not provided
+open: boolean = false;
+disabled: boolean = false;
+```
+
+**Methods:**
+- `toggle()` - Toggle open/closed
+- `expand(animate = true)` - Open
+- `collapse(animate = true)` - Close
+
+**Events:**
+- `accordion-item-toggle` - {itemId, open}
+
+**Slots:**
+- `header` - Clickable trigger content
+- default - Collapsible content
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-accordion>
+  <snice-accordion-item item-id="item-1">
+    <span slot="header">Section 1</span>
+    <div>Content 1</div>
+  </snice-accordion-item>
+
+  <snice-accordion-item item-id="item-2">
+    <span slot="header">Section 2</span>
+    <div>Content 2</div>
+  </snice-accordion-item>
+</snice-accordion>
+
+<!-- Multiple open -->
+<snice-accordion multiple>
+  <snice-accordion-item item-id="a" open>
+    <span slot="header">A</span>
+    <p>Content A</p>
+  </snice-accordion-item>
+
+  <snice-accordion-item item-id="b" open>
+    <span slot="header">B</span>
+    <p>Content B</p>
+  </snice-accordion-item>
+</snice-accordion>
+
+<!-- Disabled item -->
+<snice-accordion>
+  <snice-accordion-item item-id="active">
+    <span slot="header">Active</span>
+    <p>Can open</p>
+  </snice-accordion-item>
+
+  <snice-accordion-item item-id="disabled" disabled>
+    <span slot="header">Disabled</span>
+    <p>Cannot open</p>
+  </snice-accordion-item>
+</snice-accordion>
+```
+
+## Programmatic Control
+
+```typescript
+const accordion = document.querySelector('snice-accordion');
+
+// Control items
+accordion.openItem('item-1');
+accordion.closeItem('item-2');
+accordion.toggleItem('item-3');
+accordion.openAll();  // Multiple mode only
+accordion.closeAll();
+
+// Listen for events
+accordion.addEventListener('@snice/accordion-open', (e) => {
+  console.log('Opened:', e.detail.itemId);
+});
+
+// Control individual item
+const item = document.querySelector('snice-accordion-item');
+item.toggle();
+item.expand();
+item.collapse();
+```
+
+## Keyboard Navigation
+
+- **↓** - Next item
+- **↑** - Previous item
+- **Home** - First item
+- **End** - Last item
+- **Enter/Space** - Toggle focused item
+
+## Features
+
+- Single or multiple open mode
+- Keyboard navigation
+- Click or keyboard to toggle
+- Auto-generated item IDs
+- Disabled state
+- Open/close events
+- Accessibility: aria-expanded, button roles
+- Smooth animations
+
+## Common Patterns
+
+**FAQ:**
+```html
+<snice-accordion>
+  <snice-accordion-item item-id="q1">
+    <span slot="header">Question?</span>
+    <p>Answer.</p>
+  </snice-accordion-item>
+</snice-accordion>
+```
+
+**Settings:**
+```html
+<snice-accordion multiple>
+  <snice-accordion-item item-id="general">
+    <span slot="header">General</span>
+    <!-- Settings form -->
+  </snice-accordion-item>
+</snice-accordion>
+```
+
+**Lazy loading:**
+```typescript
+accordion.addEventListener('@snice/accordion-open', async (e) => {
+  if (!loaded[e.detail.itemId]) {
+    const data = await fetch(`/api/${e.detail.itemId}`);
+    // Update content
+    loaded[e.detail.itemId] = true;
+  }
+});
+```
+
+## Notes
+
+- Items are light DOM children (not slotted)
+- Without `multiple`, opening one closes others
+- Item IDs auto-generated if not provided
+- Disabled items cannot be toggled
+- Header slot required for trigger content
+- Full ARIA support for screen readers

package/docs/ai/components/alert.md

@@ -0,0 +1,77 @@
+# snice-alert
+
+Notification messages for user feedback.
+
+## Properties
+
+```typescript
+variant: 'info'|'success'|'warning'|'error' = 'info';
+size: 'small'|'medium'|'large' = 'medium';
+title: string = '';
+dismissible: boolean = false;
+icon: string = '';
+```
+
+## Methods
+
+- `show()` - Show alert
+- `hide()` - Hide alert
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-alert>Alert message</snice-alert>
+
+<!-- Success -->
+<snice-alert variant="success">
+  Operation completed successfully!
+</snice-alert>
+
+<!-- Error -->
+<snice-alert variant="error">
+  An error occurred
+</snice-alert>
+
+<!-- Warning -->
+<snice-alert variant="warning">
+  Please review your input
+</snice-alert>
+
+<!-- With title -->
+<snice-alert variant="info" title="Information">
+  Additional details about the information.
+</snice-alert>
+
+<!-- Dismissible -->
+<snice-alert variant="success" dismissible>
+  Can be closed by user
+</snice-alert>
+
+<!-- Custom icon -->
+<snice-alert icon="🎉">
+  Custom icon alert
+</snice-alert>
+
+<!-- Sizes -->
+<snice-alert size="small">Small</snice-alert>
+<snice-alert size="medium">Medium</snice-alert>
+<snice-alert size="large">Large</snice-alert>
+```
+
+## Features
+
+- 4 variants with semantic colors
+- 3 size options
+- Optional title
+- Optional dismiss button
+- Custom icon support
+- Show/hide methods
+- Accessibility: role="alert"
+
+## Variants
+
+- `info` - Blue, informational
+- `success` - Green, positive feedback
+- `warning` - Orange, caution
+- `error` - Red, errors/problems

package/docs/ai/components/avatar.md

@@ -0,0 +1,61 @@
+# snice-avatar
+
+User profile images with fallback initials.
+
+## Properties
+
+```typescript
+src: string = '';
+alt: string = '';
+name: string = '';
+size: 'xs'|'small'|'medium'|'large'|'xl'|'xxl' = 'medium';
+shape: 'circle'|'square'|'rounded' = 'circle';
+fallbackColor: string = '';
+fallbackBackground: string = '';
+```
+
+## Methods
+
+- `getInitials(name)` - Extract initials from name
+
+## Usage
+
+```html
+<!-- With image -->
+<snice-avatar
+  src="/user.jpg"
+  alt="John Doe"
+  name="John Doe">
+</snice-avatar>
+
+<!-- Fallback to initials -->
+<snice-avatar name="John Doe"></snice-avatar>
+
+<!-- Sizes -->
+<snice-avatar name="JD" size="xs"></snice-avatar>
+<snice-avatar name="JD" size="small"></snice-avatar>
+<snice-avatar name="JD" size="medium"></snice-avatar>
+<snice-avatar name="JD" size="large"></snice-avatar>
+<snice-avatar name="JD" size="xl"></snice-avatar>
+<snice-avatar name="JD" size="xxl"></snice-avatar>
+
+<!-- Shapes -->
+<snice-avatar name="JD" shape="circle"></snice-avatar>
+<snice-avatar name="JD" shape="square"></snice-avatar>
+<snice-avatar name="JD" shape="rounded"></snice-avatar>
+
+<!-- Custom colors -->
+<snice-avatar
+  name="JD"
+  fallback-color="#fff"
+  fallback-background="#3b82f6">
+</snice-avatar>
+```
+
+## Features
+
+- 6 size options (xs to xxl)
+- 3 shape options
+- Image with fallback to initials
+- Custom fallback colors
+- Auto-extracts initials from name