snice 4.9.0 → 4.10.0

package/docs/components/weather.md

@@ -0,0 +1,239 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/weather.md instead)
+
+# Weather Component
+
+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.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [CSS Custom Properties](#css-custom-properties)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```html
+<snice-weather></snice-weather>
+```
+
+```typescript
+import 'snice/components/weather/snice-weather';
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `WeatherData \| null` | `null` | Weather data object with current conditions and optional forecast |
+| `unit` | `'celsius' \| 'fahrenheit'` | `'celsius'` | Temperature unit |
+| `variant` | `'compact' \| 'full'` | `'full'` | Display variant |
+
+### WeatherData
+
+```typescript
+interface WeatherData {
+  temp: number;                     // Current temperature
+  condition: string;                // Condition description (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
+}
+```
+
+### 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)
+}
+```
+
+### 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:
+
+| 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 |
+
+## CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--snice-color-background-element` | Card background color | `rgb(252 251 249)` |
+| `--snice-color-border` | Card and forecast divider border | _(theme default)_ |
+| `--snice-color-text` | Primary text color | `rgb(23 23 23)` |
+| `--snice-color-text-secondary` | Condition and detail text color | _(theme default)_ |
+| `--snice-color-text-tertiary` | Forecast low temperature color | _(theme default)_ |
+| `--snice-font-weight-bold` | Temperature font weight | `700` |
+| `--snice-font-weight-semibold` | Forecast high temperature font weight | _(theme default)_ |
+| `--snice-border-radius-lg` | Card border radius | `0.5rem` |
+| `--snice-spacing-lg` | Card padding | `1.5rem` |
+
+## Examples
+
+### Full Weather Display
+
+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>
+```
+
+### Compact Variant
+
+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>
+
+<script type="module">
+  const weather = document.getElementById('weather-compact');
+  weather.data = {
+    temp: 72,
+    condition: 'Sunny'
+  };
+</script>
+```
+
+### Fahrenheit Units
+
+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>
+```
+
+### 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>
+```
+
+### 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>
+```
+
+## Accessibility
+
+- **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
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires Custom Elements v1 and Shadow DOM support
+
+## Best Practices
+
+1. **Pass data via property**: Set `weather.data = {...}` (not via attribute) since the data is a complex object
+2. **Handle loading states**: Show a skeleton or spinner while fetching weather data from an API
+3. **Choose the right variant**: Use `full` for dedicated weather displays, `compact` for dashboard widgets or headers
+4. **Match units to locale**: Use Fahrenheit for US audiences and Celsius for most other regions
+5. **Include forecast when available**: The multi-day forecast adds context and is more useful than current conditions alone
+6. **Keep condition strings standard**: Use common weather terms (Sunny, Cloudy, Rain, Snow, etc.) for reliable auto-icon detection
+7. **Refresh data periodically**: Weather data goes stale quickly; consider refreshing every 15-30 minutes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "type": "module",
   "description": "Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.",
   "main": "dist/index.cjs",

package/docs/ai/components/popover.md

@@ -1,70 +0,0 @@
-# snice-popover
-
-Floating content positioned relative to target element.
-
-## Properties
-
-```typescript
-open: boolean = false;
-placement: 'top'|'bottom'|'left'|'right'|'top-start'|'top-end'|'bottom-start'|'bottom-end'|'left-start'|'left-end'|'right-start'|'right-end' = 'top';
-trigger: 'click'|'hover'|'focus'|'manual' = 'click';
-distance: number = 8;
-showArrow: boolean = true;
-closeOnClickOutside: boolean = true;
-closeOnEscape: boolean = true;
-hoverDelay: number = 200;
-targetSelector: string = '';
-```
-
-## Methods
-
-```typescript
-show(): void
-hide(): void
-toggle(): void
-updatePosition(): void
-```
-
-## Events
-
-- `@snice/popover-show` - Dispatched when shown
-- `@snice/popover-hide` - Dispatched when hidden
-
-## Usage
-
-```html
-<button id="btn">Click me</button>
-<snice-popover target-selector="#btn">
-  Popover content
-</snice-popover>
-
-<!-- Hover trigger -->
-<snice-popover target-selector="#btn" trigger="hover">
-  Appears on hover
-</snice-popover>
-
-<!-- Manual control -->
-<snice-popover id="pop" trigger="manual">Content</snice-popover>
-<script>
-  document.getElementById('pop').show();
-</script>
-
-<!-- Different placements -->
-<snice-popover placement="bottom">Bottom</snice-popover>
-<snice-popover placement="left-start">Left Start</snice-popover>
-
-<!-- No arrow -->
-<snice-popover show-arrow="false">No arrow</snice-popover>
-```
-
-## Features
-
-- 12 placement options with start/end alignment
-- Multiple triggers (click/hover/focus/manual)
-- Arrow indicator (optional)
-- Auto-positioning with scroll/resize
-- Close on click outside or Escape
-- Hover delay configuration
-- Target via selector or previous sibling
-- Fixed positioning overlay
-- Event dispatching

package/docs/components/popover.md

@@ -1,333 +0,0 @@
-# Popover Component
-
-Display floating content positioned relative to a target element.
-
-## Basic Usage
-
-```html
-<button id="my-button">Click me</button>
-<snice-popover target-selector="#my-button">
-  Popover content goes here
-</snice-popover>
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `open` | `boolean` | `false` | Popover visibility |
-| `placement` | `PopoverPlacement` | `'top'` | Popover position |
-| `trigger` | `'click' \| 'hover' \| 'focus' \| 'manual'` | `'click'` | Open trigger |
-| `distance` | `number` | `8` | Distance from target (px) |
-| `showArrow` | `boolean` | `true` | Show arrow indicator |
-| `closeOnClickOutside` | `boolean` | `true` | Close on outside click |
-| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
-| `hoverDelay` | `number` | `200` | Hover delay (ms) |
-| `targetSelector` | `string` | `''` | Target element selector |
-
-## Placement Options
-
-`'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end'`
-
-## Methods
-
-### `show(): void`
-Show the popover.
-
-```javascript
-popover.show();
-```
-
-### `hide(): void`
-Hide the popover.
-
-```javascript
-popover.hide();
-```
-
-### `toggle(): void`
-Toggle popover visibility.
-
-```javascript
-popover.toggle();
-```
-
-### `updatePosition(): void`
-Recalculate and update popover position.
-
-```javascript
-popover.updatePosition();
-```
-
-## Events
-
-### `@snice/popover-show`
-Dispatched when popover is shown.
-
-```javascript
-popover.addEventListener('@snice/popover-show', (e) => {
-  console.log('Popover shown');
-});
-```
-
-### `@snice/popover-hide`
-Dispatched when popover is hidden.
-
-```javascript
-popover.addEventListener('@snice/popover-hide', (e) => {
-  console.log('Popover hidden');
-});
-```
-
-## Examples
-
-### Click Trigger (Default)
-
-```html
-<button id="click-btn">Click me</button>
-<snice-popover target-selector="#click-btn">
-  Popover content
-</snice-popover>
-```
-
-### Hover Trigger
-
-```html
-<button id="hover-btn">Hover me</button>
-<snice-popover target-selector="#hover-btn" trigger="hover">
-  Appears on hover
-</snice-popover>
-```
-
-### Focus Trigger
-
-```html
-<input id="input" type="text" placeholder="Focus me">
-<snice-popover target-selector="#input" trigger="focus">
-  Help text appears on focus
-</snice-popover>
-```
-
-### Manual Control
-
-```html
-<button id="open-btn">Open</button>
-<button id="close-btn">Close</button>
-<snice-popover id="manual-popover" trigger="manual">
-  Manually controlled
-</snice-popover>
-
-<script>
-  const popover = document.getElementById('manual-popover');
-  document.getElementById('open-btn').addEventListener('click', () => {
-    popover.show();
-  });
-  document.getElementById('close-btn').addEventListener('click', () => {
-    popover.hide();
-  });
-</script>
-```
-
-### Different Placements
-
-```html
-<!-- Top -->
-<button id="top-btn">Top</button>
-<snice-popover target-selector="#top-btn" placement="top">Top</snice-popover>
-
-<!-- Bottom -->
-<button id="bottom-btn">Bottom</button>
-<snice-popover target-selector="#bottom-btn" placement="bottom">Bottom</snice-popover>
-
-<!-- Left -->
-<button id="left-btn">Left</button>
-<snice-popover target-selector="#left-btn" placement="left">Left</snice-popover>
-
-<!-- Right -->
-<button id="right-btn">Right</button>
-<snice-popover target-selector="#right-btn" placement="right">Right</snice-popover>
-```
-
-### Start/End Alignment
-
-```html
-<!-- Top Start -->
-<button id="ts-btn">Top Start</button>
-<snice-popover target-selector="#ts-btn" placement="top-start">
-  Aligned to start
-</snice-popover>
-
-<!-- Top End -->
-<button id="te-btn">Top End</button>
-<snice-popover target-selector="#te-btn" placement="top-end">
-  Aligned to end
-</snice-popover>
-```
-
-### No Arrow
-
-```html
-<button id="no-arrow-btn">No Arrow</button>
-<snice-popover target-selector="#no-arrow-btn" show-arrow="false">
-  No arrow indicator
-</snice-popover>
-```
-
-### Custom Distance
-
-```html
-<button id="distance-btn">Far away</button>
-<snice-popover target-selector="#distance-btn" distance="20">
-  20px from target
-</snice-popover>
-```
-
-### Rich Content
-
-```html
-<button id="rich-btn">User Info</button>
-<snice-popover target-selector="#rich-btn" placement="bottom">
-  <div style="max-width: 250px;">
-    <h3 style="margin: 0 0 8px;">John Doe</h3>
-    <p style="margin: 0 0 8px; color: #666;">
-      Senior Developer at Example Corp
-    </p>
-    <button>View Profile</button>
-  </div>
-</snice-popover>
-```
-
-### Custom Hover Delay
-
-```html
-<button id="delay-btn">Hover (500ms delay)</button>
-<snice-popover
-  target-selector="#delay-btn"
-  trigger="hover"
-  hover-delay="500">
-  Delayed appearance
-</snice-popover>
-```
-
-### Disable Click Outside Close
-
-```html
-<button id="no-close-btn">Click me</button>
-<snice-popover
-  target-selector="#no-close-btn"
-  close-on-click-outside="false">
-  Must click button again to close
-</snice-popover>
-```
-
-### Disable Escape Key Close
-
-```html
-<button id="no-escape-btn">Click me</button>
-<snice-popover
-  target-selector="#no-escape-btn"
-  close-on-escape="false">
-  Escape key won't close this
-</snice-popover>
-```
-
-### With Form
-
-```html
-<button id="form-btn">Edit</button>
-<snice-popover target-selector="#form-btn" placement="bottom-start">
-  <form style="padding: 8px; min-width: 200px;">
-    <label>Name:</label>
-    <input type="text" style="width: 100%; padding: 4px; margin-top: 4px;">
-    <button type="submit" style="margin-top: 8px;">Save</button>
-  </form>
-</snice-popover>
-```
-
-### With List
-
-```html
-<button id="menu-btn">Options</button>
-<snice-popover target-selector="#menu-btn" placement="bottom-start">
-  <div style="min-width: 150px;">
-    <div style="padding: 8px; cursor: pointer;">Edit</div>
-    <div style="padding: 8px; cursor: pointer;">Duplicate</div>
-    <div style="padding: 8px; cursor: pointer; color: red;">Delete</div>
-  </div>
-</snice-popover>
-```
-
-### Tooltip Style
-
-```html
-<span id="tooltip-target">Hover for info</span>
-<snice-popover
-  target-selector="#tooltip-target"
-  trigger="hover"
-  hover-delay="0"
-  placement="top">
-  This is tooltip-like popover
-</snice-popover>
-```
-
-### Help Text
-
-```html
-<label>
-  Password
-  <span id="help-icon" style="cursor: help;">ⓘ</span>
-</label>
-<input type="password">
-<snice-popover
-  target-selector="#help-icon"
-  trigger="hover"
-  placement="right">
-  Password must be at least 8 characters with uppercase, lowercase, and numbers.
-</snice-popover>
-```
-
-### Confirmation Dialog
-
-```html
-<button id="delete-btn">Delete</button>
-<snice-popover id="confirm-popover" trigger="manual" placement="top">
-  <div style="padding: 8px;">
-    <p style="margin: 0 0 8px;">Are you sure?</p>
-    <button id="confirm-yes" style="background: #f44336;">Yes</button>
-    <button id="confirm-no" style="background: #9e9e9e; margin-left: 8px;">No</button>
-  </div>
-</snice-popover>
-
-<script>
-  const deleteBtn = document.getElementById('delete-btn');
-  const confirmPopover = document.getElementById('confirm-popover');
-
-  deleteBtn.addEventListener('click', () => {
-    confirmPopover.show();
-  });
-
-  document.getElementById('confirm-yes').addEventListener('click', () => {
-    console.log('Deleted!');
-    confirmPopover.hide();
-  });
-
-  document.getElementById('confirm-no').addEventListener('click', () => {
-    confirmPopover.hide();
-  });
-</script>
-```
-
-## Accessibility
-
-- Popovers automatically update position on scroll/resize
-- Close on Escape key (configurable)
-- Focus management for keyboard navigation
-- Hover trigger includes delay to prevent accidental triggers
-- Click outside to close (configurable)
-
-## Browser Support
-
-- Modern browsers with Custom Elements v1 support
-- Uses fixed positioning for overlay
-- Automatic position updates on scroll/resize
-- Arrow indicators use CSS borders