@semantic-components/ui-lab 0.62.0 → 0.63.0

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

@@ -0,0 +1,304 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  DestroyRef,
+  ElementRef,
+  inject,
+  input,
+  model,
+  OnInit,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { fromEvent, merge } from 'rxjs';
+import { cn } from '@semantic-components/ui';
+import { ScSliderTrack, ScSliderRange, ScSliderThumb } from '../slider';
+
+@Component({
+  selector: 'div[sc-range-slider]',
+  imports: [ScSliderTrack, ScSliderRange, ScSliderThumb],
+  host: {
+    'data-slot': 'range-slider',
+    '[class]': 'class()',
+    '[attr.data-disabled]': 'disabled() || null',
+  },
+  template: `
+    <div sc-slider-track>
+      <div
+        sc-slider-range
+        [percentage]="rangeWidth()"
+        [style.left.%]="rangeStart()"
+      ></div>
+    </div>
+    <div
+      sc-slider-thumb
+      [percentage]="minPercentage()"
+      [value]="minValue()"
+      [min]="min()"
+      [max]="max()"
+      [step]="step()"
+      [disabled]="disabled()"
+      [aria-label]="minAriaLabel()"
+      [aria-labelledby]="minAriaLabelledby()"
+      (keydown)="onMinKeydown($event)"
+      (mouseDown)="onMinThumbMouseDown($event)"
+      (touchStart)="onMinThumbTouchStart($event)"
+    ></div>
+    <div
+      sc-slider-thumb
+      [percentage]="maxPercentage()"
+      [value]="maxValue()"
+      [min]="min()"
+      [max]="max()"
+      [step]="step()"
+      [disabled]="disabled()"
+      [aria-label]="maxAriaLabel()"
+      [aria-labelledby]="maxAriaLabelledby()"
+      (keydown)="onMaxKeydown($event)"
+      (mouseDown)="onMaxThumbMouseDown($event)"
+      (touchStart)="onMaxThumbTouchStart($event)"
+    ></div>
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScRangeSlider implements OnInit {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly destroyRef = inject(DestroyRef);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly minValue = model<number>(0);
+  readonly maxValue = model<number>(100);
+  readonly min = input<number>(0);
+  readonly max = input<number>(100);
+  readonly step = input<number>(1);
+  readonly disabled = input<boolean>(false);
+  readonly minAriaLabel = input<string | undefined>(undefined, {
+    alias: 'min-aria-label',
+  });
+  readonly maxAriaLabel = input<string | undefined>(undefined, {
+    alias: 'max-aria-label',
+  });
+  readonly minAriaLabelledby = input<string | undefined>(undefined, {
+    alias: 'min-aria-labelledby',
+  });
+  readonly maxAriaLabelledby = input<string | undefined>(undefined, {
+    alias: 'max-aria-labelledby',
+  });
+
+  private readonly isDraggingMin = signal(false);
+  private readonly isDraggingMax = signal(false);
+
+  protected readonly minPercentage = computed(() => {
+    const minVal = this.min();
+    const maxVal = this.max();
+    const val = this.minValue();
+    if (maxVal === minVal) return 0;
+    return ((val - minVal) / (maxVal - minVal)) * 100;
+  });
+
+  protected readonly maxPercentage = computed(() => {
+    const minVal = this.min();
+    const maxVal = this.max();
+    const val = this.maxValue();
+    if (maxVal === minVal) return 0;
+    return ((val - minVal) / (maxVal - minVal)) * 100;
+  });
+
+  protected readonly rangeStart = computed(() => this.minPercentage());
+
+  protected readonly rangeWidth = computed(() => {
+    return this.maxPercentage() - this.minPercentage();
+  });
+
+  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.isDraggingMin() && !this.isDraggingMax()) return;
+
+        if (event.type === 'mouseup' || event.type === 'touchend') {
+          this.isDraggingMin.set(false);
+          this.isDraggingMax.set(false);
+          return;
+        }
+
+        if (event.type === 'mousemove') {
+          const clientX = (event as MouseEvent).clientX;
+          if (this.isDraggingMin()) {
+            this.updateMinValueFromPosition(clientX);
+          } else if (this.isDraggingMax()) {
+            this.updateMaxValueFromPosition(clientX);
+          }
+        } else if (event.type === 'touchmove') {
+          const touch = (event as TouchEvent).touches[0];
+          if (touch) {
+            if (this.isDraggingMin()) {
+              this.updateMinValueFromPosition(touch.clientX);
+            } else if (this.isDraggingMax()) {
+              this.updateMaxValueFromPosition(touch.clientX);
+            }
+          }
+        }
+      });
+  }
+
+  protected onMinThumbMouseDown(event: MouseEvent): void {
+    if (this.disabled()) return;
+    event.preventDefault();
+    this.isDraggingMin.set(true);
+  }
+
+  protected onMinThumbTouchStart(event: TouchEvent): void {
+    if (this.disabled()) return;
+    event.preventDefault();
+    this.isDraggingMin.set(true);
+  }
+
+  protected onMaxThumbMouseDown(event: MouseEvent): void {
+    if (this.disabled()) return;
+    event.preventDefault();
+    this.isDraggingMax.set(true);
+  }
+
+  protected onMaxThumbTouchStart(event: TouchEvent): void {
+    if (this.disabled()) return;
+    event.preventDefault();
+    this.isDraggingMax.set(true);
+  }
+
+  protected onMinKeydown(event: KeyboardEvent): void {
+    if (this.disabled()) return;
+
+    const stepVal = this.step();
+    const minVal = this.min();
+    const maxVal = this.maxValue(); // Min thumb can't go beyond max thumb
+    let newValue = this.minValue();
+
+    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.minValue.set(newValue);
+  }
+
+  protected onMaxKeydown(event: KeyboardEvent): void {
+    if (this.disabled()) return;
+
+    const stepVal = this.step();
+    const minVal = this.minValue(); // Max thumb can't go below min thumb
+    const maxVal = this.max();
+    let newValue = this.maxValue();
+
+    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.maxValue.set(newValue);
+  }
+
+  private updateMinValueFromPosition(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();
+    const maxVal = this.maxValue(); // Min thumb can't go beyond max thumb
+    const stepVal = this.step();
+
+    let newValue = minVal + percentage * (this.max() - minVal);
+    newValue = Math.round(newValue / stepVal) * stepVal;
+    newValue = Math.max(minVal, Math.min(maxVal, newValue));
+
+    this.minValue.set(newValue);
+  }
+
+  private updateMaxValueFromPosition(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.minValue(); // Max thumb can't go below min thumb
+    const maxVal = this.max();
+    const stepVal = this.step();
+
+    let newValue = this.min() + percentage * (maxVal - this.min());
+    newValue = Math.round(newValue / stepVal) * stepVal;
+    newValue = Math.max(minVal, Math.min(maxVal, newValue));
+
+    this.maxValue.set(newValue);
+  }
+}

package/src/lib/components/rating-field/README.md

@@ -0,0 +1,150 @@
+# Rating Field Component
+
+A composable rating field component for Angular applications, built with a three-tier directive architecture for maximum flexibility and accessibility.
+
+## Architecture
+
+The component consists of three directives:
+
+1. **ScRatingField** - Parent directive managing value state and configuration
+2. **ScRatingItemGroup** - Container directive managing hover state and keyboard navigation
+3. **ScRatingItem** - Individual rating item directive
+
+## Basic Usage
+
+```html
+<div sc-rating-field [(value)]="rating">
+  <div sc-rating-item-group>
+    @for (i of [1, 2, 3, 4, 5]; track i) {
+    <span sc-rating-item [value]="i">
+      <svg si-star-icon class="size-5"></svg>
+    </span>
+    }
+  </div>
+</div>
+```
+
+## Features
+
+- **Two-way binding** - Use `[(value)]` for reactive value updates
+- **Hover preview** - Visual feedback shows rating before selection
+- **Half-star support** - Enable `[allowHalf]="true"` for 0.5 increments
+- **Custom icons** - Use any icon (stars, hearts, etc.)
+- **Keyboard navigation** - Full arrow key, Home, End support
+- **Accessibility** - WCAG AA compliant with proper ARIA attributes
+- **Readonly/Disabled states** - Control interactivity
+- **Clear capability** - Click same value to reset (configurable)
+
+## API
+
+### ScRatingField
+
+| Input            | Type      | Default | Description                                 |
+| ---------------- | --------- | ------- | ------------------------------------------- |
+| `value`          | `number`  | `0`     | Current rating value (use with `[(value)]`) |
+| `allowHalf`      | `boolean` | `false` | Enable half-star ratings                    |
+| `allowClear`     | `boolean` | `true`  | Allow clearing by clicking same value       |
+| `readonly`       | `boolean` | `false` | Make the rating read-only                   |
+| `disabled`       | `boolean` | `false` | Disable the rating                          |
+| `label`          | `string`  | `''`    | Accessible label for the rating             |
+| `ariaLabelledby` | `string`  | `''`    | ID of element labeling the rating           |
+
+**Note:** The `max` value is automatically calculated from the highest `value` among all rating items.
+
+### ScRatingItemGroup
+
+Container directive that manages hover state and keyboard navigation. No inputs required.
+
+### ScRatingItem
+
+| Input   | Type     | Required | Description                           |
+| ------- | -------- | -------- | ------------------------------------- |
+| `value` | `number` | Yes      | The rating value this item represents |
+
+## Examples
+
+### Half-Star Rating
+
+```html
+<div sc-rating-field [(value)]="rating" [allowHalf]="true">
+  <div sc-rating-item-group>
+    @for (i of [1, 2, 3, 4, 5]; track i) {
+    <span sc-rating-item [value]="i">
+      <svg si-star-icon class="size-6"></svg>
+    </span>
+    }
+  </div>
+</div>
+```
+
+### Custom Icons (Hearts)
+
+```html
+<div sc-rating-field [(value)]="rating">
+  <div sc-rating-item-group>
+    @for (i of [1, 2, 3, 4, 5]; track i) {
+    <span sc-rating-item [value]="i">
+      <svg si-heart-icon class="size-5"></svg>
+    </span>
+    }
+  </div>
+</div>
+```
+
+### Readonly Display
+
+```html
+<div sc-rating-field [value]="4.5" [readonly]="true">
+  <div sc-rating-item-group>
+    @for (i of [1, 2, 3, 4, 5]; track i) {
+    <span sc-rating-item [value]="i">
+      <svg si-star-icon class="size-5"></svg>
+    </span>
+    }
+  </div>
+</div>
+```
+
+## Accessibility
+
+The component implements WCAG AA accessibility standards:
+
+- **ARIA roles**: `group` for container, `radiogroup` for items container, `radio` for items
+- **ARIA attributes**: `aria-label`, `aria-labelledby`, `aria-checked`, `aria-valuenow/min/max`
+- **Keyboard navigation**: Arrow keys, Home, End, Space, Enter
+- **Focus management**: Roving tabindex pattern for optimal keyboard navigation
+- **Screen reader support**: Announces current value and changes
+
+## Keyboard Shortcuts
+
+- **Arrow Right/Up**: Increase rating by step (1 or 0.5)
+- **Arrow Left/Down**: Decrease rating by step
+- **Home**: Set to minimum (0)
+- **End**: Set to maximum
+- **Space/Enter**: Select focused item
+
+## Styling
+
+Items expose a `data-state` attribute with values:
+
+- `full` - Item is fully selected
+- `half` - Item is half selected (when `allowHalf` is enabled)
+- `empty` - Item is not selected
+
+Use CSS to style based on state:
+
+```css
+[sc-rating-item][data-state='full'] svg {
+  fill: gold;
+  color: gold;
+}
+
+[sc-rating-item][data-state='half'] svg {
+  fill: url(#half-gradient);
+}
+
+[sc-rating-item][data-state='empty'] svg {
+  fill: none;
+  color: gray;
+}
+```

package/src/lib/components/rating-field/index.ts

@@ -0,0 +1,3 @@
+export { SC_RATING_FIELD, ScRatingField } from './rating-field';
+export { SC_RATING_ITEM_GROUP, ScRatingItemGroup } from './rating-item-group';
+export { ScRatingFieldItem } from './rating-item';

package/src/lib/components/rating-field/rating-field.ts

@@ -0,0 +1,87 @@
+import { _IdGenerator } from '@angular/cdk/a11y';
+import {
+  computed,
+  contentChildren,
+  Directive,
+  ElementRef,
+  inject,
+  InjectionToken,
+  input,
+  model,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_FIELD } from '../field';
+import { ScRatingFieldItem } from './rating-item';
+
+// Token for rating field context
+export const SC_RATING_FIELD = new InjectionToken<ScRatingField>(
+  'SC_RATING_FIELD',
+);
+
+@Directive({
+  selector: 'div[sc-rating-field], label[sc-rating-field]',
+  providers: [
+    { provide: SC_RATING_FIELD, useExisting: ScRatingField },
+    { provide: SC_FIELD, useExisting: ScRatingField },
+  ],
+  host: {
+    '[attr.role]': 'role()',
+    'data-slot': 'rating-field',
+    '[class]': 'class()',
+    '[attr.aria-label]': 'ariaLabel() || null',
+    '[attr.aria-labelledby]': 'ariaLabelledby() || null',
+    '[attr.data-disabled]': 'disabled() || null',
+    '[attr.data-readonly]': 'readonly() || null',
+  },
+})
+export class ScRatingField {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  readonly id = input(inject(_IdGenerator).getId('sc-rating-field-'));
+
+  protected readonly role = computed(() => {
+    const tagName = this.elementRef.nativeElement.tagName;
+    return tagName === 'LABEL' ? null : 'group';
+  });
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly value = model<number>(0);
+  readonly readonly = input<boolean>(false);
+  readonly disabled = input<boolean>(false);
+  readonly allowHalf = input<boolean>(false);
+  readonly allowClear = input<boolean>(true);
+  readonly ariaLabel = input<string>('', { alias: 'aria-label' });
+  readonly ariaLabelledby = input<string>('', { alias: 'aria-labelledby' });
+
+  private readonly items = contentChildren(ScRatingFieldItem, {
+    descendants: true,
+  });
+
+  readonly max = computed(() => {
+    const allItems = this.items();
+    if (allItems.length === 0) {
+      throw new Error(
+        'ScRatingField: No rating items found. Add at least one [sc-rating-item] element.',
+      );
+    }
+    return Math.max(...allItems.map((item) => item.value()));
+  });
+
+  protected readonly class = computed(() =>
+    cn('inline-flex items-center', this.classInput()),
+  );
+
+  setValue(value: number): void {
+    if (this.readonly() || this.disabled()) return;
+
+    // Validate value is within range
+    const maxValue = this.max();
+    const clampedValue = Math.max(0, Math.min(maxValue, value));
+
+    // Allow clearing by clicking the same value
+    if (this.allowClear() && clampedValue === this.value()) {
+      this.value.set(0);
+    } else {
+      this.value.set(clampedValue);
+    }
+  }
+}

package/src/lib/components/rating-field/rating-item-group.ts

@@ -0,0 +1,73 @@
+import {
+  computed,
+  Directive,
+  inject,
+  InjectionToken,
+  signal,
+} from '@angular/core';
+import { SC_RATING_FIELD } from './rating-field';
+
+// Token for rating item group context
+export const SC_RATING_ITEM_GROUP = new InjectionToken<ScRatingItemGroup>(
+  'SC_RATING_ITEM_GROUP',
+);
+
+@Directive({
+  selector: '[sc-rating-item-group]',
+  providers: [
+    { provide: SC_RATING_ITEM_GROUP, useExisting: ScRatingItemGroup },
+  ],
+  host: {
+    'data-slot': 'rating-item-group',
+    role: 'radiogroup',
+    '[attr.aria-valuenow]': 'field.value()',
+    '[attr.aria-valuemin]': '0',
+    '[attr.aria-valuemax]': 'field.max()',
+    '(mouseleave)': 'onMouseLeave()',
+    '(keydown)': 'onKeydown($event)',
+  },
+})
+export class ScRatingItemGroup {
+  protected readonly field = inject(SC_RATING_FIELD);
+
+  readonly hoveredValue = signal<number | null>(null);
+
+  readonly displayValue = computed(() => {
+    const hovered = this.hoveredValue();
+    return hovered !== null ? hovered : this.field.value();
+  });
+
+  setHoveredValue(value: number | null): void {
+    if (!this.field.readonly() && !this.field.disabled()) {
+      this.hoveredValue.set(value);
+    }
+  }
+
+  onMouseLeave(): void {
+    this.hoveredValue.set(null);
+  }
+
+  onKeydown(event: KeyboardEvent): void {
+    if (this.field.readonly() || this.field.disabled()) return;
+
+    const step = this.field.allowHalf() ? 0.5 : 1;
+    const max = this.field.max();
+    const current = this.field.value();
+
+    if (event.key === 'ArrowRight' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      const newValue = Math.min(max, current + step);
+      this.field.value.set(newValue);
+    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowDown') {
+      event.preventDefault();
+      const newValue = Math.max(0, current - step);
+      this.field.value.set(newValue);
+    } else if (event.key === 'Home') {
+      event.preventDefault();
+      this.field.value.set(0);
+    } else if (event.key === 'End') {
+      event.preventDefault();
+      this.field.value.set(max);
+    }
+  }
+}

package/src/lib/components/rating-field/rating-item.ts

@@ -0,0 +1,89 @@
+import { computed, Directive, ElementRef, inject, input } from '@angular/core';
+import { SC_RATING_FIELD } from './rating-field';
+import { SC_RATING_ITEM_GROUP } from './rating-item-group';
+
+@Directive({
+  selector: '[sc-rating-item]',
+  host: {
+    'data-slot': 'rating-item',
+    role: 'radio',
+    '[attr.aria-checked]': 'isSelected()',
+    '[attr.aria-label]': '"Rate " + value()',
+    '[attr.data-state]': 'state()',
+    '[tabindex]': 'tabIndex()',
+    '(click)': 'onClick($event)',
+    '(mouseenter)': 'onMouseEnter()',
+    '(keydown.space)': 'onSpace($event)',
+    '(keydown.enter)': 'onEnter($event)',
+  },
+})
+export class ScRatingFieldItem {
+  protected readonly field = inject(SC_RATING_FIELD);
+  protected readonly group = inject(SC_RATING_ITEM_GROUP);
+  private readonly elementRef = inject(ElementRef);
+
+  readonly value = input.required<number>();
+
+  readonly state = computed(() => {
+    const displayValue = this.group.displayValue();
+    const itemValue = this.value();
+
+    if (displayValue >= itemValue) {
+      return 'full';
+    } else if (this.field.allowHalf() && displayValue >= itemValue - 0.5) {
+      return 'half';
+    }
+    return 'empty';
+  });
+
+  readonly isSelected = computed(() => {
+    return this.field.value() >= this.value();
+  });
+
+  readonly tabIndex = computed(() => {
+    if (this.field.disabled() || this.field.readonly()) return -1;
+
+    // If this item is selected or partially selected, it should be focusable
+    if (this.isSelected()) return 0;
+
+    // If no item is selected, the first item (value 1) should be focusable
+    if (this.field.value() === 0 && this.value() === 1) return 0;
+
+    return -1;
+  });
+
+  protected onClick(event: MouseEvent): void {
+    if (this.field.readonly() || this.field.disabled()) return;
+
+    if (this.field.allowHalf()) {
+      const rect = (event.currentTarget as HTMLElement).getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const isLeftHalf = x < rect.width / 2;
+      this.field.setValue(isLeftHalf ? this.value() - 0.5 : this.value());
+    } else {
+      this.field.setValue(this.value());
+    }
+  }
+
+  protected onMouseEnter(): void {
+    this.group.setHoveredValue(this.value());
+  }
+
+  protected onSpace(event: Event): void {
+    event.preventDefault();
+    if (!this.field.readonly() && !this.field.disabled()) {
+      this.field.setValue(this.value());
+    }
+  }
+
+  protected onEnter(event: Event): void {
+    event.preventDefault();
+    if (!this.field.readonly() && !this.field.disabled()) {
+      this.field.setValue(this.value());
+    }
+  }
+
+  focus(): void {
+    this.elementRef.nativeElement.focus();
+  }
+}