snice 4.28.0 → 4.30.0

package/docs/components/waterfall.md

@@ -1,8 +1,9 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/waterfall.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/waterfall.md -->
 
-# Waterfall Component
+# Waterfall
+`<snice-waterfall>`
 
-The waterfall component renders a waterfall chart (also known as a bridge chart) that visualizes the cumulative effect of sequential positive and negative values. Bars are color-coded by type: green for increases, red for decreases, and blue for totals, with optional connector lines and value labels.
+Renders a waterfall chart (bridge chart) that visualizes the cumulative effect of sequential positive and negative values. Bars are color-coded by type: green for increases, red for decreases, and blue for totals.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -12,7 +13,6 @@ The waterfall component renders a waterfall chart (also known as a bridge chart)
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
@@ -24,13 +24,13 @@ The waterfall component renders a waterfall chart (also known as a bridge chart)
 | `showConnectors` (attr: `show-connectors`) | `boolean` | `true` | Show connector lines between bars |
 | `animated` | `boolean` | `false` | Animate bars on render |
 
-### WaterfallDataPoint
+### WaterfallDataPoint Interface
 
 ```typescript
 interface WaterfallDataPoint {
-  label: string;                                      // Bar label text
-  value: number;                                      // Numeric value
-  type?: 'increase' | 'decrease' | 'total';           // Bar type (auto-detected from value sign if omitted)
+  label: string;
+  value: number;
+  type?: 'increase' | 'decrease' | 'total';  // auto-detected from value sign if omitted
 }
 ```
 
@@ -38,27 +38,10 @@ When `type` is omitted, it is automatically determined: positive values render a
 
 ## Events
 
-### `bar-click`
-Fired when a bar is clicked.
-
-**Event Detail:**
-```typescript
-{
-  item: WaterfallDataPoint;
-  index: number;
-}
-```
-
-### `bar-hover`
-Fired when the mouse enters a bar.
-
-**Event Detail:**
-```typescript
-{
-  item: WaterfallDataPoint;
-  index: number;
-}
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `bar-click` | `{ item: WaterfallDataPoint, index: number }` | Bar clicked |
+| `bar-hover` | `{ item: WaterfallDataPoint, index: number }` | Mouse entered a bar |
 
 ## CSS Custom Properties
 
@@ -75,123 +58,74 @@ Fired when the mouse enters a bar.
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | The main waterfall container |
-| `chart` | `<div>` | The chart rendering area |
+| Part | Description |
+|------|-------------|
+| `base` | The main waterfall container |
+| `chart` | The chart rendering area |
 
-```css
-snice-waterfall::part(base) {
-  border-radius: 8px;
-  overflow: hidden;
-}
+## Basic Usage
 
-snice-waterfall::part(chart) {
-  padding: 1rem;
-}
+```typescript
+import 'snice/components/waterfall/snice-waterfall';
 ```
 
-## Basic Usage
-
 ```html
-<snice-waterfall></snice-waterfall>
+<snice-waterfall show-values show-connectors></snice-waterfall>
 ```
 
 ```typescript
-import 'snice/components/waterfall/snice-waterfall';
+chart.data = [
+  { label: 'Starting Balance', value: 1000, type: 'total' },
+  { label: 'Revenue', value: 500 },
+  { label: 'Costs', value: -200 },
+  { label: 'Tax', value: -100 },
+  { label: 'Net Income', value: 1200, type: 'total' }
+];
 ```
 
 ## Examples
 
-### Profit & Loss Waterfall
+### Profit and Loss
 
 Show how revenue, costs, and taxes contribute to a final balance.
 
-```html
-<snice-waterfall id="pnl-chart" show-values show-connectors></snice-waterfall>
-
-<script type="module">
-  import 'snice/components/waterfall/snice-waterfall';
-
-  const chart = document.getElementById('pnl-chart');
-  chart.data = [
-    { label: 'Starting Balance', value: 1000, type: 'total' },
-    { label: 'Revenue', value: 500 },
-    { label: 'Services', value: 300 },
-    { label: 'Costs', value: -200 },
-    { label: 'Wages', value: -350 },
-    { label: 'Tax', value: -100 },
-    { label: 'Net Income', value: 1150, type: 'total' }
-  ];
-</script>
+```typescript
+chart.data = [
+  { label: 'Starting Balance', value: 1000, type: 'total' },
+  { label: 'Revenue', value: 500 },
+  { label: 'Services', value: 300 },
+  { label: 'Costs', value: -200 },
+  { label: 'Wages', value: -350 },
+  { label: 'Tax', value: -100 },
+  { label: 'Net Income', value: 1150, type: 'total' }
+];
 ```
 
 ### Horizontal Orientation
 
-Render the waterfall chart horizontally instead of vertically.
+Use the `orientation` attribute to render the chart horizontally.
 
 ```html
-<snice-waterfall id="horizontal-chart" orientation="horizontal" show-values></snice-waterfall>
-
-<script type="module">
-  const chart = document.getElementById('horizontal-chart');
-  chart.data = [
-    { label: 'Q1 Start', value: 5000, type: 'total' },
-    { label: 'Sales', value: 2000 },
-    { label: 'Returns', value: -300 },
-    { label: 'Marketing', value: -800 },
-    { label: 'Q1 End', value: 5900, type: 'total' }
-  ];
-</script>
+<snice-waterfall orientation="horizontal" show-values></snice-waterfall>
 ```
 
 ### Animated Chart
 
-Use the `animated` property to animate bars when the chart renders.
+Use the `animated` attribute to animate bars when the chart renders.
 
 ```html
-<snice-waterfall id="animated-chart" animated show-values show-connectors></snice-waterfall>
-
-<script type="module">
-  const chart = document.getElementById('animated-chart');
-  chart.data = [
-    { label: 'January', value: 10000, type: 'total' },
-    { label: 'New Subscriptions', value: 3500 },
-    { label: 'Upgrades', value: 1200 },
-    { label: 'Churn', value: -2100 },
-    { label: 'Refunds', value: -400 },
-    { label: 'February', value: 12200, type: 'total' }
-  ];
-</script>
+<snice-waterfall animated show-values show-connectors></snice-waterfall>
 ```
 
 ### Bar Click Handling
 
 Listen for bar clicks to display details or navigate to related views.
 
-```html
-<snice-waterfall id="clickable-chart" show-values></snice-waterfall>
-<p id="click-info">Click a bar to see details.</p>
-
-<script type="module">
-  const chart = document.getElementById('clickable-chart');
-  const info = document.getElementById('click-info');
-
-  chart.data = [
-    { label: 'Budget', value: 50000, type: 'total' },
-    { label: 'Hiring', value: -15000 },
-    { label: 'Equipment', value: -8000 },
-    { label: 'Revenue', value: 20000 },
-    { label: 'Remaining', value: 47000, type: 'total' }
-  ];
-
-  chart.addEventListener('bar-click', (e) => {
-    const { item, index } = e.detail;
-    info.textContent = `Clicked: ${item.label} = ${item.value > 0 ? '+' : ''}${item.value}`;
-  });
-</script>
+```typescript
+chart.addEventListener('bar-click', (e) => {
+  const { item, index } = e.detail;
+  console.log(`Clicked: ${item.label} = ${item.value}`);
+});
 ```
 
 ### Without Connectors or Values
@@ -199,31 +133,18 @@ Listen for bar clicks to display details or navigate to related views.
 Hide connector lines and value labels for a cleaner visual.
 
 ```html
-<snice-waterfall id="clean-chart"></snice-waterfall>
-
-<script type="module">
-  const chart = document.getElementById('clean-chart');
-  chart.showValues = false;
-  chart.showConnectors = false;
-  chart.data = [
-    { label: 'Start', value: 100, type: 'total' },
-    { label: 'Add', value: 40 },
-    { label: 'Remove', value: -25 },
-    { label: 'Add', value: 15 },
-    { label: 'End', value: 130, type: 'total' }
-  ];
-</script>
+<snice-waterfall></snice-waterfall>
 ```
 
-## Accessibility
-
-- **ARIA roles**: Bars use appropriate roles for data visualization
-- **Value labels**: When `showValues` is enabled, values are displayed as text for screen readers
-- **Color and text**: Bar types are distinguishable not only by color but also by their value labels (positive/negative numbers)
-- **Keyboard support**: Bars are focusable and clickable via keyboard
-- **Reduced motion**: When `animated` is set, animations respect `prefers-reduced-motion`
+```typescript
+chart.showValues = false;
+chart.showConnectors = false;
+```
 
-## Browser Support
+## Accessibility
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+- Bars use appropriate roles for data visualization
+- Value labels provide screen reader text when `showValues` is enabled
+- Bar types are distinguishable by color and value labels
+- Bars are focusable and clickable via keyboard
+- Animations respect `prefers-reduced-motion`

package/docs/components/weather.md

@@ -1,8 +1,9 @@
-<!-- AI: For a low-token version of this doc, use docs/ai/components/weather.md instead -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/components/weather.md -->
 
-# Weather Component
+# Weather
+`<snice-weather>`
 
-The weather component displays current weather conditions with temperature, condition description, humidity, wind speed, and an optional multi-day forecast. It supports Celsius and Fahrenheit units, auto-detected weather icons, and compact or full display variants. The component does not make API calls; it receives all data via properties.
+Displays current weather conditions with temperature, condition description, humidity, wind speed, and an optional multi-day forecast. The component does not make API calls; it receives all data via properties.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -11,7 +12,6 @@ The weather component displays current weather conditions with temperature, cond
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
-- [Browser Support](#browser-support)
 
 ## Properties
 
@@ -21,52 +21,41 @@ The weather component displays current weather conditions with temperature, cond
 | `unit` | `'celsius' \| 'fahrenheit'` | `'celsius'` | Temperature unit |
 | `variant` | `'compact' \| 'full'` | `'full'` | Display variant |
 
-### WeatherData
+### WeatherData Interface
 
 ```typescript
 interface WeatherData {
-  temp: number;                     // Current temperature
-  condition: string;                // Condition description (e.g., "Sunny", "Partly Cloudy", "Rain")
+  temp: number;
+  condition: string;                // e.g., "Sunny", "Partly Cloudy", "Rain"
   icon?: string;                    // Emoji or custom icon (auto-detected from condition if omitted)
   humidity?: number;                // Humidity percentage
   wind?: number;                    // Wind speed in km/h
-  forecast?: WeatherForecastDay[];  // Multi-day forecast array
+  forecast?: WeatherForecastDay[];
 }
-```
-
-### WeatherForecastDay
 
-```typescript
 interface WeatherForecastDay {
-  day: string;        // Day label (e.g., "Mon", "Tue")
-  high: number;       // High temperature
-  low: number;        // Low temperature
-  condition: string;  // Condition description
-  icon?: string;      // Emoji or custom icon (auto-detected if omitted)
+  day: string;        // e.g., "Mon", "Tue"
+  high: number;
+  low: number;
+  condition: string;
+  icon?: string;      // Auto-detected if omitted
 }
 ```
 
-### Variants
-
-| Variant | Description |
-|---------|-------------|
-| `full` | Shows current weather, detail row (humidity and wind), and multi-day forecast |
-| `compact` | Shows only the current temperature and weather icon; hides details and forecast |
-
 ### Auto-Detected Icons
 
-When the `icon` property is omitted on either the main data or forecast days, the component maps the `condition` string to an appropriate emoji:
+When the `icon` property is omitted, the component maps the `condition` string to an appropriate emoji:
 
 | Condition (contains) | Icon |
 |----------------------|------|
-| sun / clear | Sun emoji |
-| partly cloud | Partly cloudy emoji |
-| cloud | Cloud emoji |
-| rain | Rain emoji |
-| snow | Snow emoji |
-| thunder / storm | Thunderstorm emoji |
-| fog / mist | Fog emoji |
-| wind | Wind emoji |
+| sun / clear | Sun |
+| partly cloud | Partly cloudy |
+| cloud | Cloud |
+| rain | Rain |
+| snow | Snow |
+| thunder / storm | Thunderstorm |
+| fog / mist | Fog |
+| wind | Wind |
 
 ## CSS Custom Properties
 
@@ -84,35 +73,30 @@ When the `icon` property is omitted on either the main data or forecast days, th
 
 ## CSS Parts
 
-Style internal elements from outside the shadow DOM using `::part()`.
-
-| Part | Element | Description |
-|------|---------|-------------|
-| `base` | `<div>` | Outer weather card container |
-| `current` | `<div>` | Current conditions section with icon, temperature, and condition text |
-| `details` | `<div>` | Details row showing humidity and wind speed |
-| `forecast` | `<div>` | Multi-day forecast section with day columns |
+| Part | Description |
+|------|-------------|
+| `base` | Outer weather card container |
+| `current` | Current conditions section with icon, temperature, and condition text |
+| `details` | Details row showing humidity and wind speed |
+| `forecast` | Multi-day forecast section with day columns |
 
-```css
-snice-weather::part(base) {
-  border-radius: 12px;
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
-}
+## Basic Usage
 
-snice-weather::part(forecast) {
-  border-top: 1px solid #e2e8f0;
-  padding-top: 1rem;
-}
+```typescript
+import 'snice/components/weather/snice-weather';
 ```
 
-## Basic Usage
-
 ```html
 <snice-weather></snice-weather>
 ```
 
 ```typescript
-import 'snice/components/weather/snice-weather';
+weather.data = {
+  temp: 22,
+  condition: 'Partly Cloudy',
+  humidity: 65,
+  wind: 12
+};
 ```
 
 ## Examples
@@ -121,27 +105,20 @@ import 'snice/components/weather/snice-weather';
 
 Show current conditions with humidity, wind, and a multi-day forecast.
 
-```html
-<snice-weather id="weather-full" unit="celsius" variant="full"></snice-weather>
-
-<script type="module">
-  import 'snice/components/weather/snice-weather';
-
-  const weather = document.getElementById('weather-full');
-  weather.data = {
-    temp: 22,
-    condition: 'Partly Cloudy',
-    humidity: 65,
-    wind: 12,
-    forecast: [
-      { day: 'Mon', high: 24, low: 18, condition: 'Sunny' },
-      { day: 'Tue', high: 20, low: 15, condition: 'Rain' },
-      { day: 'Wed', high: 22, low: 16, condition: 'Cloudy' },
-      { day: 'Thu', high: 25, low: 19, condition: 'Sunny' },
-      { day: 'Fri', high: 21, low: 14, condition: 'Thunderstorm' }
-    ]
-  };
-</script>
+```typescript
+weather.data = {
+  temp: 22,
+  condition: 'Partly Cloudy',
+  humidity: 65,
+  wind: 12,
+  forecast: [
+    { day: 'Mon', high: 24, low: 18, condition: 'Sunny' },
+    { day: 'Tue', high: 20, low: 15, condition: 'Rain' },
+    { day: 'Wed', high: 22, low: 16, condition: 'Cloudy' },
+    { day: 'Thu', high: 25, low: 19, condition: 'Sunny' },
+    { day: 'Fri', high: 21, low: 14, condition: 'Thunderstorm' }
+  ]
+};
 ```
 
 ### Compact Variant
@@ -149,15 +126,14 @@ Show current conditions with humidity, wind, and a multi-day forecast.
 Use the `compact` variant for a small weather badge showing just the temperature and icon.
 
 ```html
-<snice-weather id="weather-compact" unit="fahrenheit" variant="compact"></snice-weather>
+<snice-weather unit="fahrenheit" variant="compact"></snice-weather>
+```
 
-<script type="module">
-  const weather = document.getElementById('weather-compact');
-  weather.data = {
-    temp: 72,
-    condition: 'Sunny'
-  };
-</script>
+```typescript
+weather.data = {
+  temp: 72,
+  condition: 'Sunny'
+};
 ```
 
 ### Fahrenheit Units
@@ -165,90 +141,55 @@ Use the `compact` variant for a small weather badge showing just the temperature
 Set `unit="fahrenheit"` for Fahrenheit temperature display.
 
 ```html
-<snice-weather id="weather-f" unit="fahrenheit"></snice-weather>
-
-<script type="module">
-  const weather = document.getElementById('weather-f');
-  weather.data = {
-    temp: 85,
-    condition: 'Clear',
-    humidity: 45,
-    wind: 8,
-    forecast: [
-      { day: 'Sat', high: 87, low: 72, condition: 'Sunny' },
-      { day: 'Sun', high: 82, low: 68, condition: 'Partly Cloudy' },
-      { day: 'Mon', high: 79, low: 65, condition: 'Rain' }
-    ]
-  };
-</script>
+<snice-weather unit="fahrenheit"></snice-weather>
 ```
 
 ### Custom Icons
 
 Override the auto-detected icons by providing explicit `icon` values.
 
-```html
-<snice-weather id="weather-custom"></snice-weather>
-
-<script type="module">
-  const weather = document.getElementById('weather-custom');
-  weather.data = {
-    temp: 18,
-    condition: 'Overcast',
-    icon: '/icons/weather/overcast.svg',
-    humidity: 80,
-    wind: 20,
-    forecast: [
-      { day: 'Mon', high: 20, low: 14, condition: 'Rain', icon: '/icons/weather/rain.svg' },
-      { day: 'Tue', high: 22, low: 15, condition: 'Snow', icon: '/icons/weather/snow.svg' }
-    ]
-  };
-</script>
+```typescript
+weather.data = {
+  temp: 18,
+  condition: 'Overcast',
+  icon: '/icons/weather/overcast.svg',
+  humidity: 80,
+  wind: 20,
+  forecast: [
+    { day: 'Mon', high: 20, low: 14, condition: 'Rain', icon: '/icons/weather/rain.svg' }
+  ]
+};
 ```
 
 ### Fetching Data from an API
 
 The weather component does not call any APIs itself. Fetch data externally and pass it in.
 
-```html
-<snice-weather id="live-weather" variant="full"></snice-weather>
-
-<script type="module">
-  import type { SniceWeatherElement } from 'snice/components/weather/snice-weather.types';
-
-  const weather = document.getElementById('live-weather') as SniceWeatherElement;
-
-  async function loadWeather() {
-    const response = await fetch('/api/weather?city=london');
-    const apiData = await response.json();
-
-    weather.data = {
-      temp: apiData.current.temp,
-      condition: apiData.current.condition,
-      humidity: apiData.current.humidity,
-      wind: apiData.current.wind_speed,
-      forecast: apiData.daily.map(day => ({
-        day: day.day_name.slice(0, 3),
-        high: day.high,
-        low: day.low,
-        condition: day.condition
-      }))
-    };
-  }
-
-  loadWeather();
-</script>
-```
+```typescript
+async function loadWeather() {
+  const response = await fetch('/api/weather?city=london');
+  const apiData = await response.json();
 
-## Accessibility
+  weather.data = {
+    temp: apiData.current.temp,
+    condition: apiData.current.condition,
+    humidity: apiData.current.humidity,
+    wind: apiData.current.wind_speed,
+    forecast: apiData.daily.map(day => ({
+      day: day.day_name.slice(0, 3),
+      high: day.high,
+      low: day.low,
+      condition: day.condition
+    }))
+  };
+}
 
-- **ARIA attributes**: The component uses appropriate ARIA roles and labels for the weather display
-- **Temperature units**: The unit (C or F) is included in screen reader text alongside the temperature value
-- **Weather icons**: Icons have alt text derived from the condition string for screen readers
-- **Forecast readability**: Each forecast day includes high and low temperatures with labels
-- **Color contrast**: All text meets WCAG AA contrast standards
+loadWeather();
+```
 
-## Browser Support
+## Accessibility
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+- The unit (C or F) is included in screen reader text alongside the temperature value
+- Weather icons have alt text derived from the condition string
+- Each forecast day includes high and low temperatures with labels
+- All text meets WCAG AA contrast standards