snice 3.1.0 → 3.2.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/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/slider.md

@@ -0,0 +1,87 @@
+# snice-slider
+
+Range slider for numeric value selection.
+
+## Properties
+
+```typescript
+value: number = 0;
+min: number = 0;
+max: number = 100;
+step: number = 1;
+variant: 'default'|'primary'|'success'|'warning'|'danger' = 'default';
+size: 'small'|'medium'|'large' = 'medium';
+disabled: boolean = false;
+required: boolean = false;
+invalid: boolean = false;
+readonly: boolean = false;
+label: string = '';
+helperText: string = '';
+errorText: string = '';
+name: string = '';
+showValue: boolean = false;
+showTicks: boolean = false;
+vertical: boolean = false;
+```
+
+## Methods
+
+- `focus()` - Focus slider thumb
+- `blur()` - Blur slider thumb
+
+## Events
+
+- `input` - {value, slider} - During drag
+- `change` - {value, slider} - After drag complete
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-slider label="Volume" min="0" max="100"></snice-slider>
+
+<!-- With value display -->
+<snice-slider show-value value="50"></snice-slider>
+
+<!-- With ticks -->
+<snice-slider show-ticks min="0" max="10" step="1"></snice-slider>
+
+<!-- Variants -->
+<snice-slider variant="primary"></snice-slider>
+<snice-slider variant="success"></snice-slider>
+<snice-slider variant="warning"></snice-slider>
+<snice-slider variant="danger"></snice-slider>
+
+<!-- Sizes -->
+<snice-slider size="small"></snice-slider>
+<snice-slider size="medium"></snice-slider>
+<snice-slider size="large"></snice-slider>
+
+<!-- Vertical -->
+<snice-slider vertical></snice-slider>
+
+<!-- Step increments -->
+<snice-slider min="0" max="100" step="5" value="50"></snice-slider>
+
+<!-- Events -->
+<snice-slider id="slider"></snice-slider>
+<script>
+const slider = document.querySelector('#slider');
+slider.addEventListener('@snice/slider-change', (e) => {
+  console.log('Value:', e.detail.value);
+});
+</script>
+```
+
+## Features
+
+- Form-associated custom element
+- Mouse and touch support
+- Keyboard navigation (arrows, home/end, page up/down)
+- 5 color variants
+- 3 sizes
+- Vertical orientation
+- Optional value display
+- Optional tick marks
+- Step increments
+- Accessible

package/docs/ai/components/sparkline.md

@@ -0,0 +1,168 @@
+# snice-sparkline
+
+Compact inline chart for visualizing trends and patterns. For dashboards, tables, data-dense interfaces.
+
+## Properties
+
+```typescript
+data: number[] = []                     // Values to visualize
+type: SparklineType = 'line'            // 'line' | 'bar' | 'area'
+color: SparklineColor = 'primary'       // 'primary' | 'success' | 'warning' | 'danger' | 'muted'
+customColor?: string                    // Any CSS color (overrides color)
+width: number = 100                     // Chart width in pixels
+height: number = 30                     // Chart height in pixels
+strokeWidth: number = 2                 // Line/dot stroke width
+showDots: boolean = false               // Show dots on data points (line charts)
+showArea: boolean = false               // Show area fill (line charts)
+smooth: boolean = false                 // Use smooth bezier curves
+min?: number                            // Min value for scaling (auto if unset)
+max?: number                            // Max value for scaling (auto if unset)
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-sparkline id="chart"></snice-sparkline>
+<script>
+  document.getElementById('chart').data = [10, 20, 15, 25, 30];
+</script>
+
+<!-- Line chart -->
+<snice-sparkline id="line" type="line"></snice-sparkline>
+
+<!-- Bar chart -->
+<snice-sparkline id="bar" type="bar"></snice-sparkline>
+
+<!-- Area chart -->
+<snice-sparkline id="area" type="area"></snice-sparkline>
+
+<!-- Smooth curves -->
+<snice-sparkline id="smooth" smooth></snice-sparkline>
+
+<!-- With dots -->
+<snice-sparkline id="dots" show-dots></snice-sparkline>
+
+<!-- With area fill -->
+<snice-sparkline id="fill" show-area></snice-sparkline>
+
+<!-- Colors -->
+<snice-sparkline color="primary"></snice-sparkline>
+<snice-sparkline color="success"></snice-sparkline>
+<snice-sparkline color="warning"></snice-sparkline>
+<snice-sparkline color="danger"></snice-sparkline>
+<snice-sparkline color="muted"></snice-sparkline>
+
+<!-- Custom colors -->
+<snice-sparkline custom-color="#9333ea"></snice-sparkline>
+<snice-sparkline custom-color="rgb(147, 51, 234)"></snice-sparkline>
+<snice-sparkline custom-color="hsl(270, 80%, 60%)"></snice-sparkline>
+
+<!-- Sizing -->
+<snice-sparkline width="200" height="50"></snice-sparkline>
+
+<!-- Custom scale -->
+<snice-sparkline min="0" max="100"></snice-sparkline>
+
+<!-- Combined features -->
+<snice-sparkline
+  id="advanced"
+  type="line"
+  color="primary"
+  width="150"
+  height="40"
+  smooth
+  show-area
+  min="0">
+</snice-sparkline>
+```
+
+## CSS Parts
+
+```css
+::part(container)  /* Container div */
+::part(svg)        /* SVG element */
+::part(line)       /* Line/path element */
+::part(area)       /* Area polygon/path */
+::part(bar)        /* Bar rect */
+::part(dot)        /* Dot circle */
+```
+
+## Styling
+
+```css
+--snice-color-primary
+--snice-color-success
+--snice-color-warning
+--snice-color-danger
+--snice-color-text-secondary
+```
+
+## In Tables
+
+```html
+<snice-table id="table"></snice-table>
+<script>
+  document.getElementById('table').data = [
+    {
+      product: 'A',
+      trend: [10, 15, 12, 18, 22, 25]
+    }
+  ];
+
+  document.getElementById('table').columns = [
+    { key: 'product', label: 'Product' },
+    {
+      key: 'trend',
+      label: 'Trend',
+      render: (value) => {
+        const sparkline = document.createElement('snice-sparkline');
+        sparkline.data = value;
+        sparkline.width = 80;
+        sparkline.height = 25;
+        sparkline.color = 'primary';
+        return sparkline;
+      }
+    }
+  ];
+</script>
+```
+
+## Common Patterns
+
+```html
+<!-- Website traffic -->
+<snice-sparkline
+  id="traffic"
+  color="primary"
+  width="150"
+  height="40"
+  smooth
+  show-area>
+</snice-sparkline>
+
+<!-- Sales bars -->
+<snice-sparkline
+  id="sales"
+  type="bar"
+  color="success"
+  width="150"
+  height="40">
+</snice-sparkline>
+
+<!-- Response time with dots -->
+<snice-sparkline
+  id="response"
+  color="warning"
+  smooth
+  show-dots>
+</snice-sparkline>
+
+<!-- Error rate -->
+<snice-sparkline
+  id="errors"
+  type="area"
+  color="danger"
+  min="0">
+</snice-sparkline>
+```

package/docs/ai/components/spinner.md

@@ -0,0 +1,47 @@
+# snice-spinner
+
+Animated loading spinner.
+
+## Properties
+
+```typescript
+size: 'small'|'medium'|'large'|'xl' = 'medium';
+color: 'primary'|'success'|'warning'|'error'|'info' = 'primary';
+label: string = '';
+thickness: number = 4;
+```
+
+## Usage
+
+```html
+<!-- Basic -->
+<snice-spinner></snice-spinner>
+
+<!-- Sizes -->
+<snice-spinner size="small"></snice-spinner>
+<snice-spinner size="medium"></snice-spinner>
+<snice-spinner size="large"></snice-spinner>
+<snice-spinner size="xl"></snice-spinner>
+
+<!-- Colors -->
+<snice-spinner color="primary"></snice-spinner>
+<snice-spinner color="success"></snice-spinner>
+<snice-spinner color="warning"></snice-spinner>
+<snice-spinner color="error"></snice-spinner>
+<snice-spinner color="info"></snice-spinner>
+
+<!-- With label -->
+<snice-spinner label="Loading..."></snice-spinner>
+
+<!-- Custom thickness -->
+<snice-spinner thickness="6"></snice-spinner>
+```
+
+## Features
+
+- Smooth circular animation
+- 4 sizes
+- 5 color variants
+- Optional label
+- Accessible (role=status, aria-label)
+- Lightweight SVG-based