@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/animated-counter/README.md

@@ -0,0 +1,102 @@
+# Animated Counter
+
+A component that animates numbers smoothly between values with customizable easing, formatting, and duration.
+
+## Installation
+
+```typescript
+import { ScAnimatedCounter } from '@/ui/animated-counter';
+import type { AnimatedCounterEasing, AnimatedCounterOptions } from '@/ui/animated-counter';
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<sc-animated-counter [value]="count" class="text-4xl font-bold" />
+```
+
+```typescript
+count = signal(0);
+
+increment(): void {
+  this.count.update((v) => v + 100);
+}
+```
+
+### With Prefix and Suffix
+
+```html
+<sc-animated-counter [value]="money" prefix="$" [decimalPlaces]="2" class="text-3xl font-bold text-green-600" />
+
+<sc-animated-counter [value]="percent" suffix="%" [decimalPlaces]="1" class="text-3xl font-bold" />
+```
+
+### Custom Easing
+
+```html
+<sc-animated-counter [value]="value" easing="linear" [duration]="2000" />
+<sc-animated-counter [value]="value" easing="easeIn" [duration]="2000" />
+<sc-animated-counter [value]="value" easing="easeOut" [duration]="2000" />
+<sc-animated-counter [value]="value" easing="easeInOut" [duration]="2000" />
+```
+
+### Large Numbers with Separators
+
+```html
+<sc-animated-counter [value]="largeNumber" separator="," class="text-3xl font-bold" />
+```
+
+## API Reference
+
+### Inputs
+
+| Input           | Type                                               | Default     | Description              |
+| --------------- | -------------------------------------------------- | ----------- | ------------------------ |
+| `value`         | `number`                                           | (required)  | Target number to display |
+| `duration`      | `number`                                           | `1000`      | Animation duration in ms |
+| `easing`        | `'linear' \| 'easeIn' \| 'easeOut' \| 'easeInOut'` | `'easeOut'` | Animation easing         |
+| `decimalPlaces` | `number`                                           | `0`         | Number of decimal places |
+| `separator`     | `string`                                           | `','`       | Thousands separator      |
+| `prefix`        | `string`                                           | `''`        | Prefix text (e.g., '$')  |
+| `suffix`        | `string`                                           | `''`        | Suffix text (e.g., '%')  |
+| `class`         | `string`                                           | `''`        | Additional CSS classes   |
+
+### Outputs
+
+| Output              | Type     | Description                      |
+| ------------------- | -------- | -------------------------------- |
+| `animationComplete` | `number` | Emitted when animation completes |
+
+### Methods
+
+| Method    | Description        |
+| --------- | ------------------ |
+| `reset()` | Reset counter to 0 |
+
+## Type Definitions
+
+```typescript
+type AnimatedCounterEasing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
+
+interface AnimatedCounterOptions {
+  duration?: number;
+  easing?: AnimatedCounterEasing;
+  decimalPlaces?: number;
+  separator?: string;
+  prefix?: string;
+  suffix?: string;
+}
+```
+
+## Features
+
+- Smooth number animation with requestAnimationFrame
+- Multiple easing functions
+- Configurable decimal places
+- Thousands separator formatting
+- Prefix and suffix support
+- Accessible with aria-label
+- Automatic animation on value change
+- Tabular numbers for stable width

package/src/lib/components/animated-counter/animated-counter-types.ts

@@ -0,0 +1,23 @@
+export type AnimatedCounterEasing =
+  | 'linear'
+  | 'easeIn'
+  | 'easeOut'
+  | 'easeInOut';
+
+export interface AnimatedCounterOptions {
+  duration?: number;
+  easing?: AnimatedCounterEasing;
+  decimalPlaces?: number;
+  separator?: string;
+  prefix?: string;
+  suffix?: string;
+}
+
+export const DEFAULT_COUNTER_OPTIONS: Required<AnimatedCounterOptions> = {
+  duration: 1000,
+  easing: 'easeOut',
+  decimalPlaces: 0,
+  separator: ',',
+  prefix: '',
+  suffix: '',
+};

package/src/lib/components/animated-counter/animated-counter.ts

@@ -0,0 +1,143 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  DestroyRef,
+  effect,
+  inject,
+  input,
+  output,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import type { AnimatedCounterEasing } from './animated-counter-types';
+import { DEFAULT_COUNTER_OPTIONS } from './animated-counter-types';
+
+@Component({
+  selector: 'sc-animated-counter',
+  template: `
+    <span [class]="containerClass()" [attr.aria-label]="ariaLabel()">
+      <span aria-hidden="true">{{ displayValue() }}</span>
+    </span>
+  `,
+  styles: `
+    :host {
+      display: inline-block;
+    }
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScAnimatedCounter {
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly value = input.required<number>();
+  readonly duration = input(DEFAULT_COUNTER_OPTIONS.duration);
+  readonly easing = input<AnimatedCounterEasing>(
+    DEFAULT_COUNTER_OPTIONS.easing,
+  );
+  readonly decimalPlaces = input(DEFAULT_COUNTER_OPTIONS.decimalPlaces);
+  readonly separator = input(DEFAULT_COUNTER_OPTIONS.separator);
+  readonly prefix = input(DEFAULT_COUNTER_OPTIONS.prefix);
+  readonly suffix = input(DEFAULT_COUNTER_OPTIONS.suffix);
+  readonly class = input<string>('');
+
+  readonly animationComplete = output<number>();
+
+  private readonly currentValue = signal(0);
+  private animationId: number | null = null;
+  private previousValue = 0;
+
+  protected readonly displayValue = computed(() => {
+    const val = this.currentValue();
+    const formatted = this.formatNumber(val);
+    return `${this.prefix()}${formatted}${this.suffix()}`;
+  });
+
+  protected readonly ariaLabel = computed(() => {
+    return `${this.prefix()}${this.value()}${this.suffix()}`;
+  });
+
+  protected readonly containerClass = computed(() =>
+    cn('tabular-nums font-medium', this.class()),
+  );
+
+  constructor() {
+    effect(() => {
+      const targetValue = this.value();
+      this.animateToValue(targetValue);
+    });
+
+    this.destroyRef.onDestroy(() => {
+      this.cancelAnimation();
+    });
+  }
+
+  private animateToValue(target: number): void {
+    this.cancelAnimation();
+
+    const start = this.previousValue;
+    const startTime = performance.now();
+    const duration = this.duration();
+    const easingFn = this.getEasingFunction(this.easing());
+
+    const animate = (currentTime: number) => {
+      const elapsed = currentTime - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const easedProgress = easingFn(progress);
+
+      const current = start + (target - start) * easedProgress;
+      this.currentValue.set(current);
+
+      if (progress < 1) {
+        this.animationId = requestAnimationFrame(animate);
+      } else {
+        this.previousValue = target;
+        this.animationComplete.emit(target);
+      }
+    };
+
+    this.animationId = requestAnimationFrame(animate);
+  }
+
+  private cancelAnimation(): void {
+    if (this.animationId !== null) {
+      cancelAnimationFrame(this.animationId);
+      this.animationId = null;
+    }
+  }
+
+  private getEasingFunction(
+    easing: AnimatedCounterEasing,
+  ): (t: number) => number {
+    switch (easing) {
+      case 'linear':
+        return (t) => t;
+      case 'easeIn':
+        return (t) => t * t;
+      case 'easeOut':
+        return (t) => t * (2 - t);
+      case 'easeInOut':
+        return (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t);
+    }
+  }
+
+  private formatNumber(value: number): string {
+    const fixed = value.toFixed(this.decimalPlaces());
+    const [intPart, decPart] = fixed.split('.');
+
+    const withSeparator = intPart.replace(
+      /\B(?=(\d{3})+(?!\d))/g,
+      this.separator(),
+    );
+
+    return decPart ? `${withSeparator}.${decPart}` : withSeparator;
+  }
+
+  reset(): void {
+    this.cancelAnimation();
+    this.previousValue = 0;
+    this.currentValue.set(0);
+  }
+}

package/src/lib/components/animated-counter/index.ts

@@ -0,0 +1,6 @@
+export { ScAnimatedCounter } from './animated-counter';
+export type {
+  AnimatedCounterEasing,
+  AnimatedCounterOptions,
+} from './animated-counter-types';
+export { DEFAULT_COUNTER_OPTIONS } from './animated-counter-types';

package/src/lib/components/aspect-ratio/README.md

@@ -0,0 +1,97 @@
+# Aspect Ratio
+
+Displays content within a desired ratio.
+
+## Components
+
+- `ScAspectRatio` - Container that maintains a specific aspect ratio
+
+## Usage
+
+```html
+<div sc-aspect-ratio [ratio]="16 / 9">
+  <img src="..." alt="..." class="size-full object-cover" />
+</div>
+```
+
+## Common Ratios
+
+### 16:9 (Widescreen)
+
+```html
+<div sc-aspect-ratio [ratio]="16 / 9">
+  <img src="..." alt="..." class="size-full object-cover" />
+</div>
+```
+
+### 4:3 (Standard)
+
+```html
+<div sc-aspect-ratio [ratio]="4 / 3">
+  <img src="..." alt="..." class="size-full object-cover" />
+</div>
+```
+
+### 1:1 (Square)
+
+```html
+<div sc-aspect-ratio [ratio]="1">
+  <img src="..." alt="..." class="size-full object-cover" />
+</div>
+```
+
+### 21:9 (Ultrawide)
+
+```html
+<div sc-aspect-ratio [ratio]="21 / 9">
+  <img src="..." alt="..." class="size-full object-cover" />
+</div>
+```
+
+### 9:16 (Portrait)
+
+```html
+<div sc-aspect-ratio [ratio]="9 / 16">
+  <img src="..." alt="..." class="size-full object-cover" />
+</div>
+```
+
+## With Placeholder
+
+```html
+<div sc-aspect-ratio [ratio]="16 / 9" class="bg-muted">
+  <div class="flex size-full items-center justify-center">
+    <span class="text-muted-foreground">No image</span>
+  </div>
+</div>
+```
+
+## Video Container
+
+```html
+<div sc-aspect-ratio [ratio]="16 / 9">
+  <iframe src="..." class="size-full" allowfullscreen></iframe>
+</div>
+```
+
+## Inputs
+
+| Input   | Type     | Default | Description                 |
+| ------- | -------- | ------- | --------------------------- |
+| `ratio` | `number` | `1`     | Aspect ratio (width/height) |
+| `class` | `string` | `''`    | Additional CSS classes      |
+
+## Styling
+
+The component uses the native CSS `aspect-ratio` property:
+
+- `relative` - For absolute positioning of children
+- `w-full` - Full width of container
+- `[style.aspect-ratio]` - Dynamic aspect ratio
+
+## Usage Tips
+
+- Wrap in a container with a fixed width to control size
+- Use `overflow-hidden rounded-md` on parent for rounded images
+- Child content should use `size-full` to fill the container
+- Use `object-cover` on images to maintain aspect without distortion

package/src/lib/components/aspect-ratio/aspect-ratio.ts

@@ -0,0 +1,19 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: '[sc-aspect-ratio]',
+  host: {
+    'data-slot': 'aspect-ratio',
+    '[class]': 'class()',
+    '[style.aspect-ratio]': 'ratio()',
+  },
+})
+export class ScAspectRatio {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly ratio = input<number>(1);
+
+  protected readonly class = computed(() =>
+    cn('relative w-full', this.classInput()),
+  );
+}

package/src/lib/components/aspect-ratio/index.ts

@@ -0,0 +1 @@
+export * from './aspect-ratio';

package/src/lib/components/audio-player/README.md

@@ -0,0 +1,252 @@
+# Audio Player
+
+Feature-rich composable audio player with playlist support, shuffle, repeat, and volume controls.
+
+## Architecture
+
+The audio player follows the composable architecture pattern, allowing full customization of layout and controls.
+
+```
+ScAudioPlayer (Root - State Management)
+    ├── ScAudioPlayerAudio (Hidden audio element)
+    ├── ScAudioPlayerCover (Album artwork)
+    ├── ScAudioPlayerInfo (Track title/artist)
+    ├── ScAudioPlayerProgress (Seekable progress bar)
+    ├── ScAudioPlayerPlayButton (Play/pause)
+    ├── ScAudioPlayerPrevious (Previous track)
+    ├── ScAudioPlayerNext (Next track)
+    ├── ScAudioPlayerShuffle (Shuffle toggle)
+    ├── ScAudioPlayerRepeat (Repeat mode)
+    └── ScAudioPlayerVolume (Volume slider + mute)
+```
+
+## Components
+
+| Component                 | Selector                              | Description                    |
+| ------------------------- | ------------------------------------- | ------------------------------ |
+| `ScAudioPlayer`           | `[sc-audio-player]`                   | Root directive (state manager) |
+| `ScAudioPlayerAudio`      | `audio[sc-audio-player-audio]`        | Hidden audio element           |
+| `ScAudioPlayerCover`      | `div[sc-audio-player-cover]`          | Album artwork display          |
+| `ScAudioPlayerInfo`       | `div[sc-audio-player-info]`           | Track title and artist         |
+| `ScAudioPlayerProgress`   | `div[sc-audio-player-progress]`       | Progress bar with seek         |
+| `ScAudioPlayerPlayButton` | `button[sc-audio-player-play-button]` | Play/pause button              |
+| `ScAudioPlayerPrevious`   | `button[sc-audio-player-previous]`    | Previous track button          |
+| `ScAudioPlayerNext`       | `button[sc-audio-player-next]`        | Next track button              |
+| `ScAudioPlayerShuffle`    | `button[sc-audio-player-shuffle]`     | Shuffle toggle                 |
+| `ScAudioPlayerRepeat`     | `button[sc-audio-player-repeat]`      | Repeat cycle button            |
+| `ScAudioPlayerVolume`     | `div[sc-audio-player-volume]`         | Volume slider + mute           |
+
+## API
+
+### ScAudioTrack
+
+```typescript
+interface ScAudioTrack {
+  src: string;
+  title?: string;
+  artist?: string;
+  cover?: string;
+  duration?: number;
+}
+```
+
+### ScAudioPlayer
+
+| Input      | Type             | Default | Description           |
+| ---------- | ---------------- | ------- | --------------------- |
+| `tracks`   | `ScAudioTrack[]` | `[]`    | Array of audio tracks |
+| `autoplay` | `boolean`        | `false` | Auto-play on load     |
+
+| Model          | Type                       | Default  | Description         |
+| -------------- | -------------------------- | -------- | ------------------- |
+| `currentIndex` | `number`                   | `0`      | Current track index |
+| `volume`       | `number`                   | `1`      | Volume level (0-1)  |
+| `shuffle`      | `boolean`                  | `false`  | Shuffle mode        |
+| `repeat`       | `'none' \| 'one' \| 'all'` | `'none'` | Repeat mode         |
+
+| Output        | Type           | Description                |
+| ------------- | -------------- | -------------------------- |
+| `trackChange` | `ScAudioTrack` | Emits when track changes   |
+| `play`        | `void`         | Emits when playback starts |
+| `pause`       | `void`         | Emits when playback pauses |
+| `ended`       | `void`         | Emits when track ends      |
+
+## Usage
+
+### Basic Usage
+
+```typescript
+readonly tracks: ScAudioTrack[] = [
+  {
+    src: '/audio/song1.mp3',
+    title: 'Song Title',
+    artist: 'Artist Name',
+    cover: '/images/album.jpg',
+  },
+  // ... more tracks
+];
+```
+
+```html
+<div sc-audio-player [tracks]="tracks" class="flex flex-col gap-3 p-4 bg-card border rounded-lg">
+  <!-- Cover -->
+  <div sc-audio-player-cover class="w-full aspect-square max-w-[200px] mx-auto"></div>
+
+  <!-- Track Info -->
+  <div sc-audio-player-info class="text-center"></div>
+
+  <!-- Progress -->
+  <div sc-audio-player-progress></div>
+
+  <!-- Controls -->
+  <div class="flex items-center justify-center gap-2">
+    <button sc-audio-player-shuffle></button>
+    <button sc-audio-player-previous></button>
+    <button sc-audio-player-play-button></button>
+    <button sc-audio-player-next></button>
+    <button sc-audio-player-repeat></button>
+  </div>
+
+  <!-- Volume -->
+  <div sc-audio-player-volume class="justify-center"></div>
+
+  <!-- Hidden Audio Element -->
+  <audio sc-audio-player-audio></audio>
+</div>
+```
+
+### Compact Layout
+
+Horizontal layout for sidebars:
+
+```html
+<div sc-audio-player [tracks]="tracks" class="flex items-center gap-4 p-4 bg-card border rounded-lg">
+  <div sc-audio-player-cover class="size-16"></div>
+  <div sc-audio-player-info class="flex-1 min-w-0"></div>
+  <div class="flex items-center gap-2">
+    <button sc-audio-player-previous></button>
+    <button sc-audio-player-play-button></button>
+    <button sc-audio-player-next></button>
+  </div>
+  <audio sc-audio-player-audio></audio>
+</div>
+```
+
+### Minimal Player
+
+Simple player without extra controls:
+
+```html
+<div sc-audio-player [tracks]="tracks" class="flex items-center gap-2 p-2 bg-card border rounded-lg">
+  <div sc-audio-player-cover class="size-10"></div>
+  <div sc-audio-player-info class="flex-1 min-w-0"></div>
+  <button sc-audio-player-previous></button>
+  <button sc-audio-player-play-button></button>
+  <button sc-audio-player-next></button>
+  <audio sc-audio-player-audio></audio>
+</div>
+```
+
+### Only Essential Controls
+
+```html
+<div sc-audio-player [tracks]="tracks" class="flex flex-col gap-3 p-4 bg-card border rounded-lg">
+  <div sc-audio-player-progress></div>
+  <div class="flex items-center justify-center gap-2">
+    <button sc-audio-player-play-button></button>
+  </div>
+  <audio sc-audio-player-audio></audio>
+</div>
+```
+
+### Custom Layout
+
+Create any layout you want:
+
+```html
+<div sc-audio-player [tracks]="tracks" [(volume)]="volume">
+  <div class="grid grid-cols-2 gap-4 p-6 bg-card border rounded-lg">
+    <!-- Left Column -->
+    <div class="space-y-4">
+      <div sc-audio-player-cover class="w-full aspect-square"></div>
+      <div sc-audio-player-info></div>
+    </div>
+
+    <!-- Right Column -->
+    <div class="flex flex-col justify-between">
+      <div sc-audio-player-volume></div>
+
+      <div class="space-y-4">
+        <div sc-audio-player-progress></div>
+        <div class="flex justify-center gap-2">
+          <button sc-audio-player-shuffle></button>
+          <button sc-audio-player-previous></button>
+          <button sc-audio-player-play-button></button>
+          <button sc-audio-player-next></button>
+          <button sc-audio-player-repeat></button>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <audio sc-audio-player-audio></audio>
+</div>
+```
+
+### Custom Styling
+
+Each component accepts a `class` input:
+
+```html
+<button sc-audio-player-play-button class="size-16 bg-blue-500"></button>
+<div sc-audio-player-cover class="rounded-full size-32"></div>
+<div sc-audio-player-progress class="gap-4"></div>
+```
+
+### Controlled State
+
+```html
+<div sc-audio-player [tracks]="tracks" [(currentIndex)]="currentIndex" [(volume)]="volume" [(shuffle)]="shuffle" [(repeat)]="repeat" (trackChange)="onTrackChange($event)" (play)="onPlay()" (pause)="onPause()">
+  <!-- ... components ... -->
+</div>
+```
+
+## Features
+
+- ✅ **Composable**: Mix and match components
+- ✅ **Flexible Layout**: Full control over structure
+- ✅ **Custom Styling**: Style each component individually
+- ✅ **Play/Pause**: Visual feedback
+- ✅ **Track Navigation**: Previous/next with restart logic
+- ✅ **Progress Bar**: Click to seek
+- ✅ **Volume Control**: Slider with mute toggle
+- ✅ **Shuffle Mode**: Random track order
+- ✅ **Repeat Modes**: None, one, all
+- ✅ **Keyboard Navigation**: Seek with arrow keys
+- ✅ **Touch Friendly**: Works on all devices
+
+## Keyboard Navigation
+
+When focused on the progress bar:
+
+| Key         | Action                  |
+| ----------- | ----------------------- |
+| `←`         | Seek back 5 seconds     |
+| `→`         | Seek forward 5 seconds  |
+| `Shift + ←` | Seek back 10 seconds    |
+| `Shift + →` | Seek forward 10 seconds |
+
+## Accessibility
+
+- ARIA labels on all controls
+- Keyboard navigable progress bar
+- Screen reader announcements
+- Focus indicators on buttons
+- Proper button roles and states
+
+## Notes
+
+- The `<audio>` element must be included as a child
+- The `#audio` template reference is handled internally
+- All sub-components require the parent `[sc-audio-player]` directive
+- Components can be reordered and styled freely

package/src/lib/components/audio-player/audio-player-audio.ts

@@ -0,0 +1,32 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  inject,
+  ViewEncapsulation,
+} from '@angular/core';
+import { SC_AUDIO_PLAYER } from './audio-player';
+
+@Component({
+  selector: 'audio[sc-audio-player-audio]',
+  template: ``,
+  host: {
+    'data-slot': 'audio-player-audio',
+    '[src]': 'player.currentTrack()?.src',
+    '(timeupdate)': 'player.onTimeUpdate()',
+    '(loadedmetadata)': 'player.onLoadedMetadata()',
+    '(ended)': 'player.onEnded()',
+    '(play)': 'player.isPlaying.set(true)',
+    '(pause)': 'player.isPlaying.set(false)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScAudioPlayerAudio {
+  readonly player = inject(SC_AUDIO_PLAYER);
+  private readonly elementRef = inject(ElementRef<HTMLAudioElement>);
+
+  constructor() {
+    this.player.registerAudioElement(this.elementRef.nativeElement);
+  }
+}