@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/slider/README.md

@@ -0,0 +1,106 @@
+# Slider
+
+An input where the user selects a value from within a given range.
+
+## Components
+
+- `ScSlider` - Range slider with track, range, and draggable thumb
+
+## Usage
+
+```html
+<div sc-slider [(value)]="volume"></div>
+```
+
+## With Min/Max
+
+```html
+<div sc-slider [(value)]="price" [min]="0" [max]="1000"></div>
+```
+
+## With Step
+
+```html
+<div sc-slider [(value)]="quantity" [step]="10"></div>
+```
+
+## With Signal Forms
+
+ScSlider implements `FormValueControl<number>` and works seamlessly with Angular Signal Forms:
+
+```typescript
+import { signal } from '@angular/core';
+import { form, FormField } from '@angular/forms/signals';
+import { required, min, max } from '@angular/forms/signals';
+
+readonly formModel = signal({ volume: 50 });
+readonly myForm = form(this.formModel, (schemaPath) => {
+  required(schemaPath.volume);
+  min(schemaPath.volume, 0);
+  max(schemaPath.volume, 100);
+});
+```
+
+```html
+<div sc-slider [formField]="myForm.volume"></div>
+```
+
+Note: Add `FormField` to your component's `imports` array to use the `[formField]` directive. When using `[formField]`, you cannot use other property bindings like `[min]` or `[max]` on the same element. Instead, use validators in the form schema.
+
+## Disabled
+
+```html
+<div sc-slider [value]="50" [disabled]="true"></div>
+```
+
+## With Labels
+
+```html
+<div class="space-y-2">
+  <div class="flex justify-between text-sm">
+    <span>Volume</span>
+    <span>{{ volume() }}%</span>
+  </div>
+  <div sc-slider [(value)]="volume"></div>
+</div>
+```
+
+## Inputs
+
+| Input             | Type                  | Default     | Description                          |
+| ----------------- | --------------------- | ----------- | ------------------------------------ |
+| `value`           | `number`              | `0`         | Current value (model)                |
+| `min`             | `number \| undefined` | `0`         | Minimum value                        |
+| `max`             | `number \| undefined` | `100`       | Maximum value                        |
+| `step`            | `number`              | `1`         | Step increment                       |
+| `disabled`        | `boolean`             | `false`     | Whether slider is disabled           |
+| `label`           | `string \| undefined` | `undefined` | ARIA label for accessibility         |
+| `aria-labelledby` | `string \| undefined` | `undefined` | ID of element that labels the slider |
+| `class`           | `string`              | `''`        | Additional CSS classes               |
+
+## Outputs
+
+| Output        | Type     | Description              |
+| ------------- | -------- | ------------------------ |
+| `valueChange` | `number` | Emits when value changes |
+
+## Keyboard Navigation
+
+| Key        | Action                |
+| ---------- | --------------------- |
+| ArrowRight | Increase by step      |
+| ArrowUp    | Increase by step      |
+| ArrowLeft  | Decrease by step      |
+| ArrowDown  | Decrease by step      |
+| Home       | Set to minimum        |
+| End        | Set to maximum        |
+| PageUp     | Increase by step × 10 |
+| PageDown   | Decrease by step × 10 |
+
+## Accessibility
+
+- Uses `role="slider"` on thumb
+- `aria-valuemin`, `aria-valuemax`, `aria-valuenow` attributes
+- `aria-disabled` when disabled
+- Full keyboard navigation support
+- Focus ring for keyboard users

package/src/lib/components/slider/index.ts

@@ -0,0 +1,4 @@
+export * from './slider';
+export * from './slider-track';
+export * from './slider-range';
+export * from './slider-thumb';

package/src/lib/components/slider/slider-range.ts

@@ -0,0 +1,28 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-slider-range]',
+  host: {
+    'data-slot': 'slider-range',
+    '[class]': 'class()',
+    '[style.width.%]': 'percentage()',
+  },
+  template: '',
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSliderRange {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly percentage = input.required<number>();
+
+  protected readonly class = computed(() =>
+    cn('absolute h-full bg-primary', this.classInput()),
+  );
+}

package/src/lib/components/slider/slider-thumb.ts

@@ -0,0 +1,73 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  output,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-slider-thumb]',
+  host: {
+    'data-slot': 'slider-thumb',
+    '[class]': 'class()',
+    '[style.left.%]': 'percentage()',
+    '[attr.tabindex]': 'disabled() ? -1 : 0',
+    '[attr.role]': '"slider"',
+    '[attr.aria-valuemin]': 'min()',
+    '[attr.aria-valuemax]': 'max()',
+    '[attr.aria-valuenow]': 'value()',
+    '[attr.aria-disabled]': 'disabled() || null',
+    '[attr.aria-label]': 'ariaLabel() ?? null',
+    '[attr.aria-labelledby]': 'ariaLabelledby() ?? null',
+    '(keydown)': 'onKeydown($event)',
+    '(mousedown)': 'onMouseDown($event)',
+    '(touchstart)': 'onTouchStart($event)',
+  },
+  template: '',
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSliderThumb {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly percentage = input.required<number>();
+  readonly value = input.required<number>();
+  readonly min = input<number | undefined>(0);
+  readonly max = input<number | undefined>(100);
+  readonly step = input<number>(1);
+  readonly disabled = input<boolean>(false);
+  readonly ariaLabel = input<string | undefined>(undefined, {
+    alias: 'aria-label',
+  });
+  readonly ariaLabelledby = input<string | undefined>(undefined, {
+    alias: 'aria-labelledby',
+  });
+
+  readonly keydown = output<KeyboardEvent>();
+  readonly mouseDown = output<MouseEvent>();
+  readonly touchStart = output<TouchEvent>();
+
+  protected readonly class = computed(() =>
+    cn(
+      'absolute block size-5 -translate-x-1/2 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      this.disabled()
+        ? 'cursor-not-allowed'
+        : 'cursor-grab active:cursor-grabbing',
+      this.classInput(),
+    ),
+  );
+
+  protected onKeydown(event: KeyboardEvent): void {
+    this.keydown.emit(event);
+  }
+
+  protected onMouseDown(event: MouseEvent): void {
+    this.mouseDown.emit(event);
+  }
+
+  protected onTouchStart(event: TouchEvent): void {
+    this.touchStart.emit(event);
+  }
+}

package/src/lib/components/slider/slider-track.ts

@@ -0,0 +1,31 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-slider-track]',
+  host: {
+    'data-slot': 'slider-track',
+    '[class]': 'class()',
+  },
+  template: `
+    <ng-content />
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSliderTrack {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'relative h-2 w-full grow overflow-hidden rounded-full bg-secondary',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/slider/slider.ts

@@ -0,0 +1,185 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  DestroyRef,
+  ElementRef,
+  inject,
+  input,
+  model,
+  OnInit,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import type { FormValueControl } from '@angular/forms/signals';
+import { fromEvent, merge } from 'rxjs';
+import { cn } from '@semantic-components/ui';
+import { ScSliderTrack } from './slider-track';
+import { ScSliderRange } from './slider-range';
+import { ScSliderThumb } from './slider-thumb';
+
+@Component({
+  selector: 'div[sc-slider]',
+  imports: [ScSliderTrack, ScSliderRange, ScSliderThumb],
+  host: {
+    'data-slot': 'slider',
+    '[class]': 'class()',
+    '[attr.data-disabled]': 'disabled() || null',
+  },
+  template: `
+    <div sc-slider-track>
+      <div sc-slider-range [percentage]="percentage()"></div>
+    </div>
+    <div
+      sc-slider-thumb
+      [percentage]="percentage()"
+      [value]="value()"
+      [min]="min()"
+      [max]="max()"
+      [step]="step()"
+      [disabled]="disabled()"
+      [aria-label]="ariaLabel()"
+      [aria-labelledby]="ariaLabelledby()"
+      (keydown)="onKeydown($event)"
+      (mouseDown)="onThumbMouseDown($event)"
+      (touchStart)="onThumbTouchStart($event)"
+    ></div>
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSlider implements OnInit, FormValueControl<number> {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly value = model<number>(0);
+  readonly min = input<number | undefined>(0);
+  readonly max = input<number | undefined>(100);
+  readonly step = input<number>(1);
+  readonly disabled = input<boolean>(false);
+  readonly ariaLabel = input<string | undefined>(undefined, {
+    alias: 'aria-label',
+  });
+  readonly ariaLabelledby = input<string | undefined>(undefined, {
+    alias: 'aria-labelledby',
+  });
+
+  private readonly isDragging = signal(false);
+
+  protected readonly percentage = computed(() => {
+    const minVal = this.min() ?? 0;
+    const maxVal = this.max() ?? 100;
+    const val = this.value();
+    if (maxVal === minVal) return 0;
+    return ((val - minVal) / (maxVal - minVal)) * 100;
+  });
+
+  protected readonly class = computed(() =>
+    cn(
+      'relative flex w-full touch-none select-none items-center',
+      this.disabled() && 'opacity-50 cursor-not-allowed',
+      this.classInput(),
+    ),
+  );
+
+  ngOnInit(): void {
+    merge(
+      fromEvent<MouseEvent>(document, 'mousemove'),
+      fromEvent<MouseEvent>(document, 'mouseup'),
+      fromEvent<TouchEvent>(document, 'touchmove'),
+      fromEvent<TouchEvent>(document, 'touchend'),
+    )
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe((event) => {
+        if (!this.isDragging()) return;
+
+        if (event.type === 'mouseup' || event.type === 'touchend') {
+          this.isDragging.set(false);
+          return;
+        }
+
+        if (event.type === 'mousemove') {
+          this.updateValueFromPosition((event as MouseEvent).clientX);
+        } else if (event.type === 'touchmove') {
+          const touch = (event as TouchEvent).touches[0];
+          if (touch) {
+            this.updateValueFromPosition(touch.clientX);
+          }
+        }
+      });
+  }
+
+  protected onThumbMouseDown(event: MouseEvent): void {
+    if (this.disabled()) return;
+    event.preventDefault();
+    this.isDragging.set(true);
+  }
+
+  protected onThumbTouchStart(event: TouchEvent): void {
+    if (this.disabled()) return;
+    event.preventDefault();
+    this.isDragging.set(true);
+  }
+
+  protected onKeydown(event: KeyboardEvent): void {
+    if (this.disabled()) return;
+
+    const stepVal = this.step();
+    const minVal = this.min() ?? 0;
+    const maxVal = this.max() ?? 100;
+    let newValue = this.value();
+
+    switch (event.key) {
+      case 'ArrowRight':
+      case 'ArrowUp':
+        event.preventDefault();
+        newValue = Math.min(newValue + stepVal, maxVal);
+        break;
+      case 'ArrowLeft':
+      case 'ArrowDown':
+        event.preventDefault();
+        newValue = Math.max(newValue - stepVal, minVal);
+        break;
+      case 'Home':
+        event.preventDefault();
+        newValue = minVal;
+        break;
+      case 'End':
+        event.preventDefault();
+        newValue = maxVal;
+        break;
+      case 'PageUp':
+        event.preventDefault();
+        newValue = Math.min(newValue + stepVal * 10, maxVal);
+        break;
+      case 'PageDown':
+        event.preventDefault();
+        newValue = Math.max(newValue - stepVal * 10, minVal);
+        break;
+      default:
+        return;
+    }
+
+    this.value.set(newValue);
+  }
+
+  private updateValueFromPosition(clientX: number): void {
+    const rect = this.elementRef.nativeElement.getBoundingClientRect();
+    const percentage = Math.max(
+      0,
+      Math.min(1, (clientX - rect.left) / rect.width),
+    );
+
+    const minVal = this.min() ?? 0;
+    const maxVal = this.max() ?? 100;
+    const stepVal = this.step();
+
+    let newValue = minVal + percentage * (maxVal - minVal);
+    newValue = Math.round(newValue / stepVal) * stepVal;
+    newValue = Math.max(minVal, Math.min(maxVal, newValue));
+
+    this.value.set(newValue);
+  }
+}

package/src/lib/components/sortable-list/README.md

@@ -0,0 +1,229 @@
+# Sortable List
+
+A drag and drop list component for reordering items.
+
+## Usage
+
+```html
+<div sc-sortable-list [(items)]="items" class="gap-2">
+  @for (item of items(); track item; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="item" class="p-3 border rounded-md">{{ item }}</div>
+  }
+</div>
+```
+
+## Components
+
+### ScSortableList
+
+Root container that manages sortable state.
+
+**Selector:** `[sc-sortable-list]`
+
+**Inputs:**
+
+| Input         | Type                         | Default      | Description          |
+| ------------- | ---------------------------- | ------------ | -------------------- |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | List direction       |
+| `disabled`    | `boolean`                    | `false`      | Disable reordering   |
+| `handleOnly`  | `boolean`                    | `false`      | Only drag via handle |
+| `class`       | `string`                     | `''`         | Additional CSS       |
+
+**Two-way Bindings:**
+
+| Binding | Type  | Default | Description    |
+| ------- | ----- | ------- | -------------- |
+| `items` | `T[]` | `[]`    | Array of items |
+
+**Outputs:**
+
+| Output       | Type               | Description        |
+| ------------ | ------------------ | ------------------ |
+| `sortChange` | `SortableEvent<T>` | Item was reordered |
+| `sortStart`  | `{ item, index }`  | Drag started       |
+| `sortEnd`    | `SortableEvent<T>` | Drag ended         |
+
+**Methods:**
+
+| Method               | Description                 |
+| -------------------- | --------------------------- |
+| `moveItem(from, to)` | Move item programmatically  |
+| `moveUp(index)`      | Move item up one position   |
+| `moveDown(index)`    | Move item down one position |
+
+### ScSortableItem
+
+Individual draggable item.
+
+**Selector:** `[sc-sortable-item]`
+
+**Inputs:**
+
+| Input   | Type     | Required | Description    |
+| ------- | -------- | -------- | -------------- |
+| `index` | `number` | Yes      | Item index     |
+| `item`  | `T`      | Yes      | Item data      |
+| `class` | `string` | No       | Additional CSS |
+
+**Data Attributes:**
+
+| Attribute        | Description                |
+| ---------------- | -------------------------- |
+| `data-dragging`  | Present when being dragged |
+| `data-drag-over` | Present when drag target   |
+
+### ScSortableHandle
+
+Optional drag handle (use with `handleOnly`).
+
+**Selector:** `[sc-sortable-handle]`
+
+**Inputs:**
+
+| Input   | Type     | Default | Description    |
+| ------- | -------- | ------- | -------------- |
+| `class` | `string` | `''`    | Additional CSS |
+
+### ScSortableOverlay
+
+Optional overlay during drag (prevents interaction with other elements).
+
+**Selector:** `[sc-sortable-overlay]`
+
+## Types
+
+### SortableEvent<T>
+
+```typescript
+interface SortableEvent<T> {
+  item: T;
+  previousIndex: number;
+  currentIndex: number;
+}
+```
+
+## Examples
+
+### Basic
+
+```html
+<div sc-sortable-list [(items)]="items" class="gap-2">
+  @for (item of items(); track item; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="item" class="p-3 border rounded-md">{{ item }}</div>
+  }
+</div>
+```
+
+### With Drag Handle
+
+```html
+<div sc-sortable-list [(items)]="items" [handleOnly]="true" class="gap-2">
+  @for (item of items(); track item; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="item" class="flex items-center gap-3 p-3 border">
+    <span sc-sortable-handle></span>
+    <span>{{ item }}</span>
+  </div>
+  }
+</div>
+```
+
+### Horizontal Layout
+
+```html
+<div sc-sortable-list [(items)]="items" orientation="horizontal" class="gap-3">
+  @for (item of items(); track item; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="item" class="p-4 border rounded-md">{{ item }}</div>
+  }
+</div>
+```
+
+### Task List
+
+```html
+<div sc-sortable-list [(items)]="tasks" [handleOnly]="true" class="gap-1">
+  <div sc-sortable-overlay></div>
+  @for (task of tasks(); track task.id; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="task" class="flex items-center gap-3 p-3 border">
+    <span sc-sortable-handle></span>
+    <input type="checkbox" [checked]="task.completed" />
+    <span>{{ task.title }}</span>
+  </div>
+  }
+</div>
+```
+
+### With Sort Events
+
+```html
+<div sc-sortable-list [(items)]="items" (sortStart)="onSortStart($event)" (sortChange)="onSortChange($event)" (sortEnd)="onSortEnd($event)">...</div>
+```
+
+```typescript
+onSortChange(event: SortableEvent<Item>) {
+  console.log(`Moved "${event.item}" from ${event.previousIndex} to ${event.currentIndex}`);
+}
+```
+
+### Disabled
+
+```html
+<div sc-sortable-list [items]="items" [disabled]="true">
+  @for (item of items; track item; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="item" class="p-3 border opacity-60">{{ item }}</div>
+  }
+</div>
+```
+
+### Custom Handle Icon
+
+```html
+<span sc-sortable-handle>
+  <svg class="size-5"><!-- custom icon --></svg>
+</span>
+```
+
+### Playlist Example
+
+```html
+<div sc-sortable-list [(items)]="songs" [handleOnly]="true" class="divide-y">
+  @for (song of songs(); track song.id; let i = $index) {
+  <div sc-sortable-item [index]="i" [item]="song" class="flex items-center gap-4 p-3">
+    <span sc-sortable-handle></span>
+    <span class="text-muted-foreground">{{ i + 1 }}</span>
+    <div class="flex-1">
+      <p class="font-medium">{{ song.title }}</p>
+      <p class="text-sm text-muted-foreground">{{ song.artist }}</p>
+    </div>
+    <span>{{ song.duration }}</span>
+  </div>
+  }
+</div>
+```
+
+## Keyboard Navigation
+
+| Key                        | Action                                |
+| -------------------------- | ------------------------------------- |
+| `ArrowUp` / `ArrowLeft`    | Move item up (based on orientation)   |
+| `ArrowDown` / `ArrowRight` | Move item down (based on orientation) |
+| `Tab`                      | Move focus between items              |
+
+## Features
+
+- **Drag and Drop**: Native HTML5 drag and drop
+- **Keyboard Support**: Arrow keys to reorder when focused
+- **Handle Mode**: Restrict dragging to handle element
+- **Orientations**: Vertical or horizontal layouts
+- **Visual Feedback**: Opacity and ring indicators during drag
+- **Events**: Callbacks for sort start, change, and end
+- **Overlay**: Optional overlay to prevent interaction during drag
+- **Two-way Binding**: Sync with `[(items)]`
+- **Generic Types**: Full TypeScript support
+
+## Accessibility
+
+- Focusable items with `tabindex`
+- Keyboard reordering with arrow keys
+- ARIA label on drag handle
+- Visual focus indicators
+- Disabled state support

package/src/lib/components/sortable-list/index.ts

@@ -0,0 +1,4 @@
+export * from './sortable-list';
+export * from './sortable-item';
+export * from './sortable-handle';
+export * from './sortable-overlay';