snice 3.1.0 → 3.3.0

package/docs/ai/components/kpi.md

@@ -0,0 +1,158 @@
+# snice-kpi
+
+Key performance indicator display with value, label, trend, sparkline, and sentiment.
+
+## Properties
+
+```typescript
+label: string = ''                      // Metric label/name
+value: string | number = ''             // Main metric value
+trendValue?: string | number            // Trend value (e.g., "+12.5%")
+trendData?: number[]                    // Sparkline data array
+sentiment?: KpiSentiment                // 'up' | 'down' | 'neutral'
+size: KpiSize = 'medium'                // 'small' | 'medium' | 'large'
+showSparkline: boolean = true           // Show sparkline when data provided
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-kpi label="Revenue" value="$45,231"></snice-kpi>
+
+<!-- With trend -->
+<snice-kpi
+  label="Monthly Revenue"
+  value="$54,239"
+  trend-value="+12.5%"
+  sentiment="up">
+</snice-kpi>
+
+<!-- With sparkline -->
+<snice-kpi
+  id="sales"
+  label="Weekly Sales"
+  value="$28,450"
+  trend-value="+15.3%"
+  sentiment="up">
+</snice-kpi>
+<script>
+  document.getElementById('sales').trendData = [20, 25, 22, 30, 28, 35, 32];
+</script>
+
+<!-- Sentiments -->
+<snice-kpi sentiment="up"></snice-kpi>     <!-- Green, ↑ -->
+<snice-kpi sentiment="down"></snice-kpi>   <!-- Red, ↓ -->
+<snice-kpi sentiment="neutral"></snice-kpi> <!-- Gray, → -->
+
+<!-- Sizes -->
+<snice-kpi size="small"></snice-kpi>
+<snice-kpi size="medium"></snice-kpi>
+<snice-kpi size="large"></snice-kpi>
+
+<!-- Without sparkline -->
+<snice-kpi show-sparkline="false"></snice-kpi>
+
+<!-- Dashboard grid -->
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px;">
+  <snice-kpi
+    id="mrr"
+    label="MRR"
+    value="$127K"
+    trend-value="+22%"
+    sentiment="up">
+  </snice-kpi>
+
+  <snice-kpi
+    id="users"
+    label="Active Users"
+    value="2,345"
+    trend-value="+8.7%"
+    sentiment="up">
+  </snice-kpi>
+
+  <snice-kpi
+    id="churn"
+    label="Churn"
+    value="2.3%"
+    trend-value="+0.8%"
+    sentiment="down">
+  </snice-kpi>
+</div>
+<script>
+  document.getElementById('mrr').trendData = [100, 110, 105, 120, 115, 130, 127];
+  document.getElementById('users').trendData = [2000, 2100, 2200, 2250, 2300, 2345];
+  document.getElementById('churn').trendData = [1.5, 1.8, 2.0, 2.2, 2.1, 2.3];
+</script>
+```
+
+## CSS Parts
+
+```css
+::part(container)   /* Main container */
+::part(header)      /* Header section */
+::part(main)        /* Main content (label + value) */
+::part(label)       /* Label text */
+::part(value)       /* Value text */
+::part(trend)       /* Trend container */
+::part(trend-icon)  /* Trend icon (↑↓→) */
+::part(trend-value) /* Trend value text */
+::part(sparkline)   /* Sparkline container */
+```
+
+## Styling
+
+```css
+--snice-color-background
+--snice-color-border
+--snice-color-text
+--snice-color-text-secondary
+--snice-color-success        /* Up sentiment */
+--snice-color-danger         /* Down sentiment */
+--snice-spacing-xs
+--snice-spacing-sm
+--snice-spacing-md
+--snice-spacing-lg
+--snice-font-size-xs
+--snice-font-size-sm
+--snice-font-size-md
+--snice-font-size-2xl
+--snice-font-size-3xl
+--snice-font-size-4xl
+--snice-font-weight-medium
+--snice-font-weight-semibold
+--snice-font-weight-bold
+--snice-border-radius-md
+```
+
+## Common Patterns
+
+```html
+<!-- Financial metrics -->
+<snice-kpi label="Revenue" value="$127K" trend-value="+22%" sentiment="up"></snice-kpi>
+<snice-kpi label="Costs" value="$45K" trend-value="-5%" sentiment="down"></snice-kpi>
+<snice-kpi label="Profit" value="$82K" trend-value="+35%" sentiment="up"></snice-kpi>
+
+<!-- User metrics -->
+<snice-kpi label="Total Users" value="12,345" trend-value="+234" sentiment="up"></snice-kpi>
+<snice-kpi label="Active Users" value="8,901" trend-value="+156" sentiment="up"></snice-kpi>
+<snice-kpi label="Churn Rate" value="2.3%" trend-value="+0.2%" sentiment="down"></snice-kpi>
+
+<!-- Performance metrics -->
+<snice-kpi label="Response Time" value="245ms" trend-value="-23ms" sentiment="down"></snice-kpi>
+<snice-kpi label="Uptime" value="99.9%" trend-value="±0%" sentiment="neutral"></snice-kpi>
+<snice-kpi label="Error Rate" value="0.12%" trend-value="-0.03%" sentiment="down"></snice-kpi>
+
+<!-- Marketing metrics -->
+<snice-kpi label="Conversion Rate" value="3.24%" trend-value="+0.5%" sentiment="up"></snice-kpi>
+<snice-kpi label="CAC" value="$156" trend-value="-$12" sentiment="down"></snice-kpi>
+<snice-kpi label="LTV" value="$1,245" trend-value="+$87" sentiment="up"></snice-kpi>
+```
+
+## Notes
+
+- Sparkline automatically uses sentiment color (success/danger/muted)
+- Sentiment icons: up=↑, down=↓, neutral=→
+- trendData array automatically renders sparkline
+- Value can be string or number for formatting flexibility
+- showSparkline=false hides sparkline even if data provided

package/docs/ai/components/layout.md

@@ -0,0 +1,261 @@
+# snice-layout
+
+Collection of pre-built page layouts for common application patterns.
+
+## snice-layout
+
+Base layout with header navigation, main content area, and footer.
+
+### Slots
+
+- `brand` - Logo/brand in header
+- `page` - Main page content
+- `footer` - Footer content
+
+### Methods
+
+- `update(appContext, placards, currentRoute, routeParams)` - Update layout navigation
+
+### Usage
+
+```html
+<snice-layout>
+  <div slot="brand">
+    <h1>My App</h1>
+  </div>
+  <div slot="page">
+    <!-- Page content -->
+  </div>
+  <div slot="footer">
+    <p>© 2025 My Company</p>
+  </div>
+</snice-layout>
+```
+
+## snice-layout-centered
+
+Centered single-column layout with configurable width.
+
+### Properties
+
+```typescript
+width: 'sm'|'md'|'lg'|'xl' = 'md';
+```
+
+### Slots
+
+- `page` - Main content (centered)
+
+### Usage
+
+```html
+<snice-layout-centered width="lg">
+  <div slot="page">
+    <!-- Centered content -->
+  </div>
+</snice-layout-centered>
+```
+
+## snice-layout-split
+
+Two-column split layout.
+
+### Slots
+
+- `left` - Left column content
+- `right` - Right column content
+
+### Usage
+
+```html
+<snice-layout-split>
+  <div slot="left">
+    <!-- Left sidebar -->
+  </div>
+  <div slot="right">
+    <!-- Main content -->
+  </div>
+</snice-layout-split>
+```
+
+## snice-layout-sidebar
+
+Layout with collapsible sidebar and main content area.
+
+### Slots
+
+- `brand` - Logo/brand in sidebar header
+- `sidebar` - Sidebar navigation content
+- `page` - Main page content
+- `footer` - Footer content
+
+### Usage
+
+```html
+<snice-layout-sidebar>
+  <div slot="brand">
+    <h1>My App</h1>
+  </div>
+  <nav slot="sidebar">
+    <!-- Sidebar navigation -->
+  </nav>
+  <div slot="page">
+    <!-- Main content -->
+  </div>
+</snice-layout-sidebar>
+```
+
+## snice-layout-dashboard
+
+Dashboard layout with header, sidebar, and content grid.
+
+### Slots
+
+- `brand` - Logo/brand
+- `header` - Top header content
+- `sidebar` - Left sidebar navigation
+- `page` - Main dashboard content
+
+### Usage
+
+```html
+<snice-layout-dashboard>
+  <div slot="brand">
+    <h1>Dashboard</h1>
+  </div>
+  <div slot="header">
+    <!-- User menu, notifications -->
+  </div>
+  <nav slot="sidebar">
+    <!-- Nav items -->
+  </nav>
+  <div slot="page">
+    <!-- Dashboard widgets -->
+  </div>
+</snice-layout-dashboard>
+```
+
+## snice-layout-landing
+
+Landing page layout with hero section.
+
+### Slots
+
+- `header` - Top navigation
+- `hero` - Hero section
+- `page` - Main content
+- `footer` - Footer
+
+### Usage
+
+```html
+<snice-layout-landing>
+  <nav slot="header">
+    <!-- Top nav -->
+  </nav>
+  <div slot="hero">
+    <h1>Welcome</h1>
+  </div>
+  <div slot="page">
+    <!-- Features, content -->
+  </div>
+  <footer slot="footer">
+    <!-- Links, copyright -->
+  </footer>
+</snice-layout-landing>
+```
+
+## snice-layout-blog
+
+Blog-style layout with header, content, and sidebar.
+
+### Slots
+
+- `header` - Header navigation
+- `page` - Main blog content
+- `sidebar` - Blog sidebar (recent posts, categories)
+- `footer` - Footer
+
+### Usage
+
+```html
+<snice-layout-blog>
+  <nav slot="header">
+    <!-- Blog nav -->
+  </nav>
+  <article slot="page">
+    <!-- Blog post -->
+  </article>
+  <aside slot="sidebar">
+    <!-- Recent posts, categories -->
+  </aside>
+</snice-layout-blog>
+```
+
+## snice-layout-fullscreen
+
+Full viewport layout with no margins.
+
+### Slots
+
+- `page` - Fullscreen content
+
+### Usage
+
+```html
+<snice-layout-fullscreen>
+  <div slot="page">
+    <!-- Fullscreen app -->
+  </div>
+</snice-layout-fullscreen>
+```
+
+## snice-layout-minimal
+
+Minimal layout with just header and content.
+
+### Slots
+
+- `header` - Minimal header
+- `page` - Main content
+
+### Usage
+
+```html
+<snice-layout-minimal>
+  <div slot="header">
+    <h1>Simple App</h1>
+  </div>
+  <div slot="page">
+    <!-- Content -->
+  </div>
+</snice-layout-minimal>
+```
+
+## snice-layout-card
+
+Card-based centered layout for login/signup pages.
+
+### Slots
+
+- `page` - Card content
+
+### Usage
+
+```html
+<snice-layout-card>
+  <div slot="page">
+    <h2>Sign In</h2>
+    <!-- Login form -->
+  </div>
+</snice-layout-card>
+```
+
+## Features
+
+- 10 pre-built layout patterns
+- Responsive design
+- Slotted content areas
+- Navigation integration (where applicable)
+- Router integration support
+- Common UI patterns (dashboard, blog, landing, etc.)

package/docs/ai/components/link.md

@@ -0,0 +1,77 @@
+# snice-link
+
+Link component with variants and external link handling.
+
+## Properties
+
+```typescript
+href: string = ''                      // Link URL
+target: LinkTarget = '_self'           // '_self' | '_blank' | '_parent' | '_top'
+variant: LinkVariant = 'default'       // 'default' | 'primary' | 'secondary' | 'muted'
+disabled: boolean = false              // Disable link
+external: boolean = false              // Auto _blank + noopener
+underline: boolean = false             // Show underline
+hash: boolean = false                  // Auto prepend # to href (for hash routing)
+```
+
+## Events
+
+```typescript
+@dispatch('click')     // Emitted on click (prevented if disabled)
+@dispatch('navigate')  // Emitted on hash link click (for router integration)
+                       // detail: { href: string }
+                       // cancelable: true
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-link href="/page">Link text</snice-link>
+
+<!-- External -->
+<snice-link href="https://example.com" external>External</snice-link>
+
+<!-- Variants -->
+<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>
+
+<!-- Underlined -->
+<snice-link href="/page" underline>Underlined link</snice-link>
+
+<!-- Disabled -->
+<snice-link href="/page" disabled>Disabled</snice-link>
+
+<!-- Hash links (for routing) -->
+<snice-link href="home" hash>Home</snice-link>
+<snice-link href="about" hash>About</snice-link>
+<!-- Renders as: <a href="#home">Home</a> -->
+
+<!-- Router integration -->
+<snice-link href="profile" hash @navigate="${handleNavigate}">Profile</snice-link>
+<script>
+  function handleNavigate(e) {
+    console.log('Navigate to:', e.detail.href);
+    // e.preventDefault() in the handler will cancel navigation
+  }
+</script>
+```
+
+## CSS Parts
+
+```css
+::part(link)          /* Anchor element */
+::part(external-icon) /* External icon */
+```
+
+## Styling
+
+```css
+--snice-color-primary
+--snice-color-primary-dark
+--snice-color-text-secondary
+--snice-color-text
+--snice-color-text-muted
+--snice-color-text-disabled
+```

package/docs/ai/components/list.md

@@ -0,0 +1,50 @@
+# snice-list
+
+List of items with optional selection, icons, descriptions.
+
+## Properties
+
+```typescript
+items: ListItem[] = [];
+selectionMode: 'single'|'multiple'|'none' = 'none';
+selectedItems: string[] = [];
+hoverable: boolean = true;
+dividers: boolean = false;
+dense: boolean = false;
+```
+
+## ListItem
+
+```typescript
+interface ListItem {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  iconImage?: string;
+  disabled?: boolean;
+  selected?: boolean;
+  data?: any;
+}
+```
+
+## Methods
+
+- `selectItem(id)`, `deselectItem(id)`, `toggleSelection(id)`
+- `getSelectedItems(): ListItem[]`
+
+## Events
+
+- `@snice/list-item-select` (detail: { item, selected, list })
+
+## Usage
+
+```html
+<snice-list id="list" selection-mode="single" dividers></snice-list>
+<script>
+  list.items = [
+    { id: '1', label: 'Item 1', description: 'First', icon: '📄' },
+    { id: '2', label: 'Item 2', description: 'Second', icon: '📄' }
+  ];
+</script>
+```

package/docs/ai/components/location.md

@@ -0,0 +1,75 @@
+# snice-location
+
+Display location information with addresses, coordinates, and maps.
+
+## Properties
+
+```typescript
+mode: 'full'|'compact'|'coordinates'|'address' = 'full';
+name: string = '';
+address: string = '';
+city: string = '';
+state: string = '';
+country: string = '';
+zipCode: string = '';
+latitude: number | string = '';
+longitude: number | string = '';
+showMap: boolean = false;
+showIcon: boolean = true;
+icon: string = '📍';
+iconImage: string = '';
+mapUrl: string = '';
+clickable: boolean = false;
+```
+
+## Methods
+
+```typescript
+getData(): LocationData
+getCoordinates(): { latitude: number; longitude: number } | null
+getFullAddress(): string
+openMap(): void
+```
+
+## Events
+
+- `location-click` - Dispatched when clicked (detail: LocationData)
+
+## Usage
+
+```html
+<snice-location
+  name="Central Park"
+  address="Central Park"
+  city="New York"
+  state="NY"
+  latitude="40.7829"
+  longitude="-73.9654"
+  clickable>
+</snice-location>
+
+<!-- With embedded map -->
+<snice-location
+  name="Times Square"
+  latitude="40.7580"
+  longitude="-73.9855"
+  show-map>
+</snice-location>
+
+<!-- Coordinates only -->
+<snice-location
+  latitude="40.7580"
+  longitude="-73.9855"
+  mode="coordinates">
+</snice-location>
+```
+
+## Features
+
+- Multiple display modes (full/compact/coordinates/address)
+- Embedded Google Maps support
+- Custom icons (emoji or image)
+- Clickable to open in maps app
+- Custom map URL support
+- Complete address formatting
+- Coordinate validation