snice 3.6.0 → 3.8.0

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v3.5.0
+ * snice v3.7.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v3.5.0
+ * snice v3.7.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v3.5.0
+ * snice v3.7.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v3.5.0
+ * snice v3.7.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/types/context.d.ts

@@ -3,6 +3,7 @@ import { NavContext } from './nav-context';
 import { Placard } from './placard';
 import { RouteParams } from './route-params';
 import { REGISTERED_ELEMENTS, IS_UPDATING, CONTEXT_REGISTER, CONTEXT_UNREGISTER, CONTEXT_NOTIFY_ELEMENT } from '../symbols';
+import type { Fetcher } from '../fetcher';
 declare const REGISTERED_ELEMENTS_SET: unique symbol;
 /**
  * Represents the bundled router state that can notify registered elements of changes
@@ -38,7 +39,12 @@ export declare class Context {
      * Navigation state
      */
     navigation: NavContext;
-    constructor(context?: AppContext, placards?: Placard[], currentRoute?: string, routeParams?: RouteParams);
+    /**
+     * Fetch function with optional middleware support
+     * Bound to this Context instance, allowing middleware to access application and navigation state
+     */
+    fetch: typeof globalThis.fetch;
+    constructor(context?: AppContext, placards?: Placard[], currentRoute?: string, routeParams?: RouteParams, fetcher?: Fetcher);
     /**
      * Update the context and notify all registered elements
      * Prevents infinite loops by tracking update state

package/dist/types/router-options.d.ts

@@ -1,4 +1,5 @@
 import { Transition } from './transition';
+import type { Fetcher } from '../fetcher';
 export interface RouterOptions {
     /**
      * The target element selector where the page element will be instantiated.
@@ -29,4 +30,9 @@ export interface RouterOptions {
      * Default layout element tag name for all pages
      */
     layout?: string;
+    /**
+     * Optional fetcher for context-aware HTTP requests with middleware support
+     * If not provided, Context.fetch will default to native fetch
+     */
+    fetcher?: Fetcher;
 }

package/docs/ai/api.md

@@ -147,13 +147,45 @@ html`
 //     ctx.update(); // notify all subscribers
 //   }
 
-Router({ target, context?, layout? })
+Router({ target, context?, layout?, fetcher? })
 // Returns: { page, navigate, initialize }
 // page() - decorator factory
 // navigate(path) - programmatic navigation
 // initialize() - start router
 ```
 
+## Fetcher
+
+```typescript
+class ContextAwareFetcher implements Fetcher {
+  use(type: 'request', middleware: RequestMiddleware): void
+  use(type: 'response', middleware: ResponseMiddleware): void
+  create(ctx: Context): typeof globalThis.fetch
+}
+
+type RequestMiddleware = (
+  this: Context,
+  request: Request,
+  next: () => Promise<Response>
+) => Promise<Response>
+
+type ResponseMiddleware = (
+  this: Context,
+  response: Response,
+  next: () => Promise<Response>
+) => Promise<Response>
+```
+
+**Usage:**
+- Create fetcher, add middleware via `.use('request', fn)` and `.use('response', fn)`
+- Request middleware runs before fetch, response middleware after
+- Middleware `this` bound to Context instance
+- Access `this.application` and `this.navigation` in middleware
+- Pass to Router via `fetcher` option
+- Use via `ctx.fetch()` in pages/components
+- Optional - defaults to native fetch if not provided
+```
+
 ## Templates
 
 ```typescript

package/docs/ai/components/music-player.md

@@ -0,0 +1,134 @@
+# snice-music-player
+
+Full-featured audio player with playlist, shuffle, repeat, and volume control.
+
+## Properties
+
+```typescript
+tracks: Track[] = [];
+currentTrackIndex: number = 0;
+currentTrack: string = ''; // reflected attribute
+currentTime: number = 0; // read-only, use seek()
+duration: number = 0;
+volume: number = 1;
+muted: boolean = false;
+shuffle: boolean = false;
+repeat: 'off'|'all'|'one' = 'off';
+state: 'playing'|'paused'|'stopped'|'loading'|'error' = 'stopped';
+autoplay: boolean = false;
+showPlaylist: boolean = true;
+showControls: boolean = true;
+showVolume: boolean = true;
+showArtwork: boolean = true;
+showTrackInfo: boolean = true;
+compact: boolean = false;
+```
+
+## Methods
+
+```typescript
+play(): Promise<void>
+pause(): void
+stop(): void
+next(): void
+previous(): void
+seek(time: number): void
+setVolume(volume: number): void
+toggleShuffle(): void
+setRepeat(mode: 'off'|'all'|'one'): void
+loadTrack(index: number): Promise<void>
+getCurrentTrack(): Track | null
+```
+
+## Track Interface
+
+```typescript
+interface Track {
+  id: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  artwork?: string;
+  src: string;
+  duration?: number;
+}
+```
+
+## Events
+
+- `@snice/player-play` - Playback started
+- `@snice/player-pause` - Playback paused
+- `@snice/player-stop` - Playback stopped
+- `@snice/player-track-change` - Track changed
+- `@snice/player-track-ended` - Track ended
+- `@snice/player-shuffle-change` - Shuffle changed
+- `@snice/player-repeat-change` - Repeat mode changed
+- `@snice/player-volume-change` - Volume changed
+- `@snice/player-time-update` - Time updated
+- `@snice/player-error` - Error occurred
+
+## Usage
+
+```javascript
+// Set tracks
+player.tracks = [
+  {
+    id: '1',
+    title: 'Song Title',
+    artist: 'Artist Name',
+    album: 'Album Name',
+    artwork: 'https://example.com/art.jpg',
+    src: 'https://example.com/audio.mp3',
+    duration: 180
+  }
+];
+
+// Controls
+await player.play();
+player.pause();
+player.stop();
+player.next();
+player.previous();
+player.seek(30);
+
+// Volume
+player.setVolume(0.5);
+
+// Shuffle & repeat
+player.toggleShuffle();
+player.setRepeat('all');
+
+// Load track
+await player.loadTrack(2);
+
+// Get current
+const track = player.getCurrentTrack();
+
+// Get/set via currentTrack attribute
+console.log(player.currentTrack); // track ID
+player.currentTrack = 'track-2'; // loads track by ID
+```
+
+```html
+<snice-music-player
+  autoplay
+  shuffle
+  compact
+  show-playlist="false">
+</snice-music-player>
+```
+
+## Features
+
+- HTML5 Audio API
+- Playlist support
+- Play/pause/stop/next/previous
+- Shuffle with randomization
+- Repeat modes: off, all, one
+- Volume control (vertical slider)
+- Progress bar with seek
+- Real-time updates
+- Track artwork & metadata
+- Compact mode
+- Event-driven
+- Clickable playlist

package/docs/ai/components/timer.md

@@ -0,0 +1,43 @@
+# Timer
+
+```html
+<snice-timer mode="stopwatch"></snice-timer>
+<snice-timer mode="timer" initial-time="60"></snice-timer>
+```
+
+## Properties
+- `mode`: 'stopwatch' | 'timer' (default: 'stopwatch')
+- `initial-time`: number (default: 0) - Starting time in seconds for timer mode
+- `running`: boolean (read-only)
+
+## Methods
+- `start()`: Start timer
+- `stop()`: Stop/pause timer
+- `reset()`: Reset to initial state
+- `getTime()`: Get current time in seconds
+
+## Events
+- `@snice/timer-start`: { timer, time }
+- `@snice/timer-stop`: { timer, time }
+- `@snice/timer-reset`: { timer, time }
+- `@snice/timer-complete`: { timer } - Countdown reached 0
+
+## Implementation
+- Uses requestAnimationFrame for smooth updates
+- Direct DOM manipulation for display to avoid re-renders
+- Stopwatch: counts up from 0
+- Timer: counts down from initial-time
+- Auto-stops at 0 in timer mode
+
+## Display Format
+- Under 1 hour: `M:SS.D` (e.g., "2:05.3")
+- Over 1 hour: `H:MM:SS` (e.g., "1:05:30")
+
+## Theme Integration
+Uses standard theme tokens:
+- Background: `--snice-color-background-element`
+- Borders: `--snice-color-border`
+- Text: `--snice-color-text`
+- Start button: `--snice-color-success`
+- Pause button: `--snice-color-warning`
+- Reset button: `--snice-color-neutral`

package/docs/ai/patterns.md

@@ -56,7 +56,7 @@ class UserPage extends HTMLElement {
   private appContext?: AppContext;
 
   @context()
-  handleContext(ctx: Context<AppContext>) {
+  handleContext(ctx: Context) {
     this.appContext = ctx.application;
     this.requestRender();
   }
@@ -115,6 +115,53 @@ class UserProfile extends HTMLElement {
 }
 ```
 
+## Fetch with Middleware
+
+```typescript
+import { Router, ContextAwareFetcher } from 'snice';
+
+const fetcher = new ContextAwareFetcher();
+
+// Request middleware - modify request before fetch
+fetcher.use('request', function(request, next) {
+  const token = this.application.user?.token;
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+  return next();
+});
+
+// Response middleware - handle response after fetch
+fetcher.use('response', async function(response, next) {
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return next();
+});
+
+const router = Router({
+  target: '#app',
+  context: { user: null },
+  fetcher
+});
+
+// In pages
+@page({ tag: 'user-page', routes: ['/users/:id'] })
+class UserPage extends HTMLElement {
+  private ctx: Context;
+
+  @context()
+  handleContext(ctx: Context) {
+    this.ctx = ctx;
+  }
+
+  @ready()
+  async load() {
+    const user = await this.ctx.fetch('/api/users/123').then(r => r.json());
+  }
+}
+```
+
 ## Conditional Rendering
 ```typescript
 html`

package/docs/components/music-player.md

@@ -0,0 +1,314 @@
+# Music Player Component
+
+A full-featured audio player with playlist support, shuffle, repeat modes, and volume control.
+
+## Basic Usage
+
+```html
+<snice-music-player id="player"></snice-music-player>
+
+<script>
+  const player = document.getElementById('player');
+
+  // Set tracks
+  player.tracks = [
+    {
+      id: 'track-1',
+      title: 'Song Title',
+      artist: 'Artist Name',
+      album: 'Album Name',
+      artwork: 'https://example.com/artwork.jpg',
+      src: 'https://example.com/audio.mp3',
+      duration: 180
+    }
+  ];
+
+  // Listen for events
+  player.addEventListener('@snice/player-play', (e) => {
+    console.log('Playing:', e.detail.track.title);
+  });
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `tracks` | `Track[]` | `[]` | Array of tracks |
+| `currentTrackIndex` | `number` | `0` | Current track index |
+| `currentTrack` | `string` | `''` | Current track ID (reflected attribute) |
+| `currentTime` | `number` | `0` | Current playback time (read-only, use seek() to set) |
+| `duration` | `number` | `0` | Track duration (seconds) |
+| `volume` | `number` | `1` | Volume (0-1) |
+| `muted` | `boolean` | `false` | Mute state |
+| `shuffle` | `boolean` | `false` | Shuffle mode |
+| `repeat` | `RepeatMode` | `'off'` | Repeat mode |
+| `state` | `PlayerState` | `'stopped'` | Playback state |
+| `autoplay` | `boolean` | `false` | Auto-play on load |
+| `showPlaylist` | `boolean` | `true` | Show playlist |
+| `showControls` | `boolean` | `true` | Show control buttons |
+| `showVolume` | `boolean` | `true` | Show volume control |
+| `showArtwork` | `boolean` | `true` | Show artwork |
+| `showTrackInfo` | `boolean` | `true` | Show track info |
+| `compact` | `boolean` | `false` | Compact mode |
+
+## Track Interface
+
+```typescript
+interface Track {
+  id: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  artwork?: string;
+  src: string;
+  duration?: number;
+}
+```
+
+## Repeat Modes
+
+- `'off'` - No repeat
+- `'all'` - Repeat all tracks
+- `'one'` - Repeat current track
+
+## Player States
+
+- `'playing'` - Currently playing
+- `'paused'` - Paused
+- `'stopped'` - Stopped
+- `'loading'` - Loading track
+- `'error'` - Error occurred
+
+## Methods
+
+### `play(): Promise<void>`
+Start or resume playback.
+
+### `pause(): void`
+Pause playback.
+
+### `stop(): void`
+Stop playback and reset position.
+
+### `next(): void`
+Skip to next track.
+
+### `previous(): void`
+Skip to previous track.
+
+### `seek(time: number): void`
+Seek to specific time (seconds).
+
+### `setVolume(volume: number): void`
+Set volume (0-1).
+
+### `toggleShuffle(): void`
+Toggle shuffle mode.
+
+### `setRepeat(mode: RepeatMode): void`
+Set repeat mode.
+
+### `loadTrack(index: number): Promise<void>`
+Load track by index.
+
+### `getCurrentTrack(): Track | null`
+Get current track.
+
+## Events
+
+- `@snice/player-play` - Playback started
+- `@snice/player-pause` - Playback paused
+- `@snice/player-stop` - Playback stopped
+- `@snice/player-track-change` - Track changed
+- `@snice/player-track-ended` - Track ended
+- `@snice/player-shuffle-change` - Shuffle changed
+- `@snice/player-repeat-change` - Repeat mode changed
+- `@snice/player-volume-change` - Volume changed
+- `@snice/player-time-update` - Playback time updated
+- `@snice/player-error` - Error occurred
+
+## Examples
+
+### Full Player with Playlist
+
+```html
+<snice-music-player id="player"></snice-music-player>
+
+<script>
+  const player = document.getElementById('player');
+
+  player.tracks = [
+    {
+      id: '1',
+      title: 'Summer Breeze',
+      artist: 'The Acoustic Collective',
+      album: 'Peaceful Moments',
+      artwork: 'https://example.com/art1.jpg',
+      src: 'https://example.com/track1.mp3',
+      duration: 360
+    },
+    {
+      id: '2',
+      title: 'Midnight Jazz',
+      artist: 'Smooth Notes Ensemble',
+      album: 'Late Night Sessions',
+      artwork: 'https://example.com/art2.jpg',
+      src: 'https://example.com/track2.mp3',
+      duration: 420
+    }
+  ];
+</script>
+```
+
+### Compact Player (No Playlist)
+
+```html
+<snice-music-player
+  show-playlist="false"
+  compact>
+</snice-music-player>
+```
+
+### Minimal Player
+
+```html
+<snice-music-player
+  show-playlist="false"
+  show-artwork="false"
+  show-track-info="false">
+</snice-music-player>
+```
+
+### Programmatic Control
+
+```javascript
+const player = document.querySelector('snice-music-player');
+
+// Play/Pause
+await player.play();
+player.pause();
+player.stop();
+
+// Navigation
+player.next();
+player.previous();
+
+// Seek
+player.seek(30); // Jump to 30 seconds
+
+// Volume
+player.setVolume(0.5); // 50% volume
+
+// Shuffle
+player.toggleShuffle();
+
+// Repeat
+player.setRepeat('all');
+player.setRepeat('one');
+player.setRepeat('off');
+
+// Load track
+await player.loadTrack(2); // Load third track
+
+// Get current track
+const track = player.getCurrentTrack();
+console.log(track.title, track.artist);
+
+// Get/set via currentTrack attribute
+console.log(player.currentTrack); // Returns track ID
+player.currentTrack = 'track-2'; // Loads track with this ID
+
+// Change time via seek (currentTime is read-only)
+player.seek(30); // Jump to 30 seconds
+```
+
+### Event Handling
+
+```javascript
+const player = document.querySelector('snice-music-player');
+
+player.addEventListener('@snice/player-play', (e) => {
+  console.log('Playing:', e.detail.track);
+});
+
+player.addEventListener('@snice/player-pause', (e) => {
+  console.log('Paused:', e.detail.track);
+});
+
+player.addEventListener('@snice/player-track-change', (e) => {
+  console.log('Track changed:', e.detail.track);
+});
+
+player.addEventListener('@snice/player-track-ended', (e) => {
+  console.log('Track ended:', e.detail.track);
+});
+
+player.addEventListener('@snice/player-time-update', (e) => {
+  console.log('Time:', e.detail.currentTime, '/', e.detail.duration);
+});
+
+player.addEventListener('@snice/player-error', (e) => {
+  console.error('Error:', e.detail.error);
+});
+```
+
+### Auto-play
+
+```html
+<snice-music-player autoplay></snice-music-player>
+```
+
+**Note:** Autoplay may be blocked by browser policies. User interaction is usually required.
+
+### Dynamic Track Loading
+
+```javascript
+const player = document.querySelector('snice-music-player');
+
+// Load tracks from API
+const response = await fetch('/api/tracks');
+const tracks = await response.json();
+
+player.tracks = tracks;
+await player.loadTrack(0);
+await player.play();
+```
+
+### Playlist Click Handler
+
+```javascript
+// Tracks in playlist are clickable by default
+// Listen for track changes
+player.addEventListener('@snice/player-track-change', (e) => {
+  console.log('User selected:', e.detail.track.title);
+});
+```
+
+## Features
+
+- Full-featured audio player with HTML5 Audio API
+- Playlist support with clickable tracks
+- Play, pause, stop, next, previous controls
+- Shuffle mode with randomization
+- Repeat modes: off, all, one
+- Volume control with vertical slider
+- Progress bar with seek support
+- Real-time progress updates
+- Track artwork and metadata display
+- Compact mode for smaller layouts
+- Fully customizable with show/hide options
+- Event-driven architecture
+- TypeScript support
+
+## Browser Support
+
+- Modern browsers with HTML5 Audio support
+- Requires JavaScript enabled
+
+## Accessibility
+
+- Keyboard navigation support
+- ARIA labels on controls
+- Semantic HTML structure
+- Focus indicators