@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/image-compare/README.md

@@ -0,0 +1,239 @@
+# Image Compare
+
+Before/after image comparison slider with keyboard and touch support. Built using the composable architecture pattern for maximum flexibility.
+
+## Components
+
+- `ScImageCompare` (directive) - Root state management
+- `ScImageCompareContainer` - Interactive container with event handling
+- `ScImageCompareBefore` - Before image positioning
+- `ScImageCompareAfter` - After image with clip-path reveal
+- `ScImageCompareSlider` - Draggable slider line and handle
+- `ScImageCompareLabel` - Customizable labels
+
+## Basic Usage
+
+```html
+<div sc-image-compare class="w-full max-w-2xl aspect-[2/1]">
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="before.jpg" alt="Before" />
+    <img sc-image-compare-after src="after.jpg" alt="After" />
+    <div sc-image-compare-slider></div>
+    <div sc-image-compare-label class="top-2 left-2">Before</div>
+    <div sc-image-compare-label class="top-2 right-2">After</div>
+  </div>
+</div>
+```
+
+## API
+
+### ScImageCompare (Directive)
+
+The root directive that manages state.
+
+| Input         | Type                         | Default        | Description        |
+| ------------- | ---------------------------- | -------------- | ------------------ |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Slider orientation |
+
+| Model      | Type     | Default | Description             |
+| ---------- | -------- | ------- | ----------------------- |
+| `position` | `number` | `50`    | Slider position (0-100) |
+
+### ScImageCompareContainer
+
+The interactive container that handles user input.
+
+| Input       | Type     | Default                     | Description          |
+| ----------- | -------- | --------------------------- | -------------------- |
+| `ariaLabel` | `string` | `'Image comparison slider'` | Accessibility label  |
+| `class`     | `string` | -                           | Additional CSS class |
+
+### ScImageCompareBefore / ScImageCompareAfter
+
+Image components for before/after images. Use as attribute directives on `<img>` tags.
+
+| Input   | Type     | Default | Description          |
+| ------- | -------- | ------- | -------------------- |
+| `class` | `string` | -       | Additional CSS class |
+
+### ScImageCompareSlider
+
+The draggable slider line and handle.
+
+| Input   | Type     | Default | Description          |
+| ------- | -------- | ------- | -------------------- |
+| `class` | `string` | -       | Additional CSS class |
+
+**Content Projection:** Place custom handle icons inside the slider component.
+
+### ScImageCompareLabel
+
+Label component with full positioning control.
+
+| Input   | Type     | Default | Description          |
+| ------- | -------- | ------- | -------------------- |
+| `class` | `string` | -       | Additional CSS class |
+
+## Examples
+
+### Basic Usage
+
+```html
+<div sc-image-compare class="w-full max-w-2xl aspect-[2/1]">
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="/images/before.jpg" alt="Before" />
+    <img sc-image-compare-after src="/images/after.jpg" alt="After" />
+    <div sc-image-compare-slider></div>
+    <div sc-image-compare-label class="top-2 left-2">Before</div>
+    <div sc-image-compare-label class="top-2 right-2">After</div>
+  </div>
+</div>
+```
+
+### Without Labels
+
+Simply omit the label components:
+
+```html
+<div sc-image-compare class="w-full max-w-2xl aspect-[2/1]">
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="before.jpg" alt="Before" />
+    <img sc-image-compare-after src="after.jpg" alt="After" />
+    <div sc-image-compare-slider></div>
+  </div>
+</div>
+```
+
+### Vertical Orientation
+
+```html
+<div sc-image-compare [orientation]="'vertical'" class="w-full max-w-sm aspect-[2/3]">
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="before.jpg" alt="Top" />
+    <img sc-image-compare-after src="after.jpg" alt="Bottom" />
+    <div sc-image-compare-slider></div>
+    <div sc-image-compare-label class="top-2 left-2">Top</div>
+    <div sc-image-compare-label class="bottom-2 left-2">Bottom</div>
+  </div>
+</div>
+```
+
+### Custom Labels
+
+Labels have full positioning control:
+
+```html
+<div sc-image-compare class="w-full max-w-2xl aspect-[2/1]">
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="before.jpg" alt="Before" />
+    <img sc-image-compare-after src="after.jpg" alt="After" />
+    <div sc-image-compare-slider></div>
+    <div sc-image-compare-label class="bottom-4 left-4 bg-blue-500 text-white px-3 py-1 rounded-full">Original</div>
+    <div sc-image-compare-label class="bottom-4 right-4 bg-green-500 text-white px-3 py-1 rounded-full">Enhanced</div>
+  </div>
+</div>
+```
+
+### Custom Slider Handle
+
+Use content projection to customize the slider handle:
+
+```html
+<div sc-image-compare>
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="before.jpg" alt="Before" />
+    <img sc-image-compare-after src="after.jpg" alt="After" />
+    <div sc-image-compare-slider>
+      <!-- Custom handle content -->
+      <svg><!-- Your custom icon --></svg>
+    </div>
+  </div>
+</div>
+```
+
+### Controlled Position
+
+```typescript
+@Component({
+  template: `
+    <div sc-image-compare [(position)]="position" class="w-full max-w-2xl aspect-[2/1]">
+      <div sc-image-compare-container>
+        <img sc-image-compare-before src="before.jpg" alt="Before" />
+        <img sc-image-compare-after src="after.jpg" alt="After" />
+        <div sc-image-compare-slider></div>
+      </div>
+    </div>
+
+    <input type="range" min="0" max="100" [value]="position()" (input)="position.set(+$any($event.target).value)" />
+  `,
+})
+export class MyComponent {
+  readonly position = signal(50);
+}
+```
+
+### Custom Initial Position
+
+```typescript
+readonly position = signal(25); // Start at 25%
+```
+
+```html
+<div sc-image-compare [(position)]="position">
+  <div sc-image-compare-container>
+    <img sc-image-compare-before src="before.jpg" alt="Before" />
+    <img sc-image-compare-after src="after.jpg" alt="After" />
+    <div sc-image-compare-slider></div>
+  </div>
+</div>
+```
+
+## Keyboard Navigation
+
+| Key             | Action                   |
+| --------------- | ------------------------ |
+| `←` / `→`       | Move slider (horizontal) |
+| `↑` / `↓`       | Move slider (vertical)   |
+| `Shift` + Arrow | Move by 10%              |
+| `Home`          | Go to 0%                 |
+| `End`           | Go to 100%               |
+
+## Styling
+
+The component uses CSS `clip-path` for the reveal effect. Set dimensions on the root:
+
+```html
+<!-- Fixed aspect ratio -->
+<div sc-image-compare class="w-full max-w-2xl aspect-[16/9]">...</div>
+
+<!-- Square -->
+<div sc-image-compare class="w-full max-w-md aspect-square">...</div>
+
+<!-- Custom dimensions -->
+<div sc-image-compare class="w-[600px] h-[400px]">...</div>
+```
+
+## Composable Architecture
+
+This component follows the composable architecture pattern:
+
+- **Root Directive** (`sc-image-compare`): Manages state (position, orientation)
+- **Container** (`sc-image-compare-container`): Handles user interactions (mouse, touch, keyboard)
+- **Image Components**: Positioned with appropriate clip-path
+- **Slider**: Customizable via content projection
+- **Labels**: Optional, fully customizable positioning and styling
+
+Benefits:
+
+- Full control over structure and layout
+- Easy customization of all visual elements
+- Content projection for icons and labels
+- Can add additional elements between components
+
+## Accessibility
+
+- Full keyboard support with arrow keys
+- ARIA slider role with value announcements
+- Screen reader accessible labels
+- Focus ring for keyboard navigation
+- Touch support for mobile devices

package/src/lib/components/image-compare/image-compare-after.ts

@@ -0,0 +1,39 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_IMAGE_COMPARE } from './image-compare';
+
+@Component({
+  selector: 'img[sc-image-compare-after]',
+  template: '',
+  host: {
+    'data-slot': 'image-compare-after',
+    '[class]': 'class()',
+    '[style.clip-path]': 'clipPath()',
+    draggable: 'false',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScImageCompareAfter {
+  readonly imageCompare = inject(SC_IMAGE_COMPARE);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('absolute inset-0 size-full object-cover', this.classInput()),
+  );
+
+  protected readonly clipPath = computed(() => {
+    const pos = this.imageCompare.position();
+    if (this.imageCompare.orientation() === 'horizontal') {
+      return `inset(0 0 0 ${pos}%)`;
+    }
+    return `inset(${pos}% 0 0 0)`;
+  });
+}

package/src/lib/components/image-compare/image-compare-before.ts

@@ -0,0 +1,30 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_IMAGE_COMPARE } from './image-compare';
+
+@Component({
+  selector: 'img[sc-image-compare-before]',
+  template: '',
+  host: {
+    'data-slot': 'image-compare-before',
+    '[class]': 'class()',
+    draggable: 'false',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScImageCompareBefore {
+  readonly imageCompare = inject(SC_IMAGE_COMPARE);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('absolute inset-0 size-full object-cover', this.classInput()),
+  );
+}

package/src/lib/components/image-compare/image-compare-container.ts

@@ -0,0 +1,119 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+  ViewEncapsulation,
+  viewChild,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_IMAGE_COMPARE } from './image-compare';
+
+@Component({
+  selector: '[sc-image-compare-container]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'image-compare-container',
+    '[class]': 'class()',
+    tabindex: '0',
+    role: 'slider',
+    '[attr.aria-label]': 'ariaLabel()',
+    '[attr.aria-valuenow]': 'imageCompare.position()',
+    'aria-valuemin': '0',
+    'aria-valuemax': '100',
+    '(mousedown)': 'onPointerDown($event)',
+    '(mousemove)': 'onPointerMove($event)',
+    '(mouseup)': 'onPointerUp()',
+    '(mouseleave)': 'onPointerUp()',
+    '(touchstart)': 'onTouchStart($event)',
+    '(touchmove)': 'onTouchMove($event)',
+    '(touchend)': 'onPointerUp()',
+    '(keydown)': 'onKeydown($event)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScImageCompareContainer {
+  readonly imageCompare = inject(SC_IMAGE_COMPARE);
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly ariaLabel = input<string>('Image comparison slider');
+
+  protected readonly class = computed(() =>
+    cn(
+      'relative select-none cursor-ew-resize overflow-hidden rounded-lg',
+      'focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+      this.imageCompare.orientation() === 'vertical' && 'cursor-ns-resize',
+      this.classInput(),
+    ),
+  );
+
+  protected onPointerDown(event: MouseEvent): void {
+    this.imageCompare.startDragging();
+    this.updatePosition(event.clientX, event.clientY);
+  }
+
+  protected onPointerMove(event: MouseEvent): void {
+    if (!this.imageCompare.isDragging()) return;
+    this.updatePosition(event.clientX, event.clientY);
+  }
+
+  protected onPointerUp(): void {
+    this.imageCompare.stopDragging();
+  }
+
+  protected onTouchStart(event: TouchEvent): void {
+    event.preventDefault();
+    this.imageCompare.startDragging();
+    const touch = event.touches[0];
+    this.updatePosition(touch.clientX, touch.clientY);
+  }
+
+  protected onTouchMove(event: TouchEvent): void {
+    if (!this.imageCompare.isDragging()) return;
+    event.preventDefault();
+    const touch = event.touches[0];
+    this.updatePosition(touch.clientX, touch.clientY);
+  }
+
+  protected onKeydown(event: KeyboardEvent): void {
+    const step = event.shiftKey ? 10 : 1;
+    const orientation = this.imageCompare.orientation();
+
+    if (orientation === 'horizontal') {
+      if (event.key === 'ArrowLeft') {
+        this.imageCompare.moveSlider('backward', step);
+        event.preventDefault();
+      } else if (event.key === 'ArrowRight') {
+        this.imageCompare.moveSlider('forward', step);
+        event.preventDefault();
+      }
+    } else {
+      if (event.key === 'ArrowUp') {
+        this.imageCompare.moveSlider('backward', step);
+        event.preventDefault();
+      } else if (event.key === 'ArrowDown') {
+        this.imageCompare.moveSlider('forward', step);
+        event.preventDefault();
+      }
+    }
+
+    if (event.key === 'Home') {
+      this.imageCompare.setPositionToStart();
+      event.preventDefault();
+    } else if (event.key === 'End') {
+      this.imageCompare.setPositionToEnd();
+      event.preventDefault();
+    }
+  }
+
+  private updatePosition(clientX: number, clientY: number): void {
+    const rect = this.elementRef.nativeElement.getBoundingClientRect();
+    this.imageCompare.updatePosition(clientX, clientY, rect);
+  }
+}

package/src/lib/components/image-compare/image-compare-label.ts

@@ -0,0 +1,34 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_IMAGE_COMPARE } from './image-compare';
+
+@Component({
+  selector: '[sc-image-compare-label]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'image-compare-label',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScImageCompareLabel {
+  readonly imageCompare = inject(SC_IMAGE_COMPARE);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'absolute px-2 py-1 bg-black/60 text-white text-xs rounded',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/image-compare/image-compare-slider.ts

@@ -0,0 +1,103 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_IMAGE_COMPARE } from './image-compare';
+
+@Component({
+  selector: '[sc-image-compare-slider]',
+  template: `
+    <div [class]="handleClass()">
+      <ng-content>
+        <!-- Default handle icons -->
+        @if (imageCompare.orientation() === 'horizontal') {
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            class="size-5"
+          >
+            <path d="m9 18 6-6-6-6" />
+          </svg>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            class="size-5 rotate-180"
+          >
+            <path d="m9 18 6-6-6-6" />
+          </svg>
+        } @else {
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            class="size-5 -rotate-90"
+          >
+            <path d="m9 18 6-6-6-6" />
+          </svg>
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            class="size-5 rotate-90"
+          >
+            <path d="m9 18 6-6-6-6" />
+          </svg>
+        }
+      </ng-content>
+    </div>
+  `,
+  host: {
+    'data-slot': 'image-compare-slider',
+    '[class]': 'lineClass()',
+    '[style]': 'lineStyle()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScImageCompareSlider {
+  readonly imageCompare = inject(SC_IMAGE_COMPARE);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly lineClass = computed(() =>
+    cn(
+      'absolute bg-white shadow-lg',
+      this.imageCompare.orientation() === 'horizontal'
+        ? 'top-0 bottom-0 w-0.5 -translate-x-1/2'
+        : 'left-0 right-0 h-0.5 -translate-y-1/2',
+      this.classInput(),
+    ),
+  );
+
+  protected readonly lineStyle = computed(() => {
+    const pos = this.imageCompare.position();
+    if (this.imageCompare.orientation() === 'horizontal') {
+      return `left: ${pos}%`;
+    }
+    return `top: ${pos}%`;
+  });
+
+  protected readonly handleClass = computed(() =>
+    cn(
+      'absolute bg-white rounded-full shadow-lg border-2 border-white',
+      'flex items-center justify-center',
+      this.imageCompare.orientation() === 'horizontal'
+        ? 'top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-10 h-10'
+        : 'top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-10 h-10 flex-col',
+    ),
+  );
+}

package/src/lib/components/image-compare/image-compare.ts

@@ -0,0 +1,79 @@
+import { Directive, InjectionToken, input, model, signal } from '@angular/core';
+
+/**
+ * Injection token for ScImageCompare
+ */
+export interface ScImageCompare {
+  orientation: () => 'horizontal' | 'vertical';
+  position: ReturnType<typeof model<number>>;
+  isDragging: ReturnType<typeof signal<boolean>>;
+  startDragging: () => void;
+  stopDragging: () => void;
+  updatePosition: (clientX: number, clientY: number, rect: DOMRect) => void;
+  moveSlider: (direction: 'forward' | 'backward', step?: number) => void;
+  setPositionToStart: () => void;
+  setPositionToEnd: () => void;
+}
+
+export const SC_IMAGE_COMPARE = new InjectionToken<ScImageCompare>(
+  'SC_IMAGE_COMPARE',
+);
+
+@Directive({
+  selector: '[sc-image-compare]',
+  exportAs: 'scImageCompare',
+  providers: [
+    { provide: SC_IMAGE_COMPARE, useExisting: ScImageCompareDirective },
+  ],
+  host: {
+    'data-slot': 'image-compare',
+    '[attr.data-orientation]': 'orientation()',
+  },
+})
+export class ScImageCompareDirective implements ScImageCompare {
+  // Configuration inputs
+  readonly orientation = input<'horizontal' | 'vertical'>('horizontal');
+
+  // Model for two-way binding of slider position
+  readonly position = model<number>(50);
+
+  // Internal state
+  readonly isDragging = signal(false);
+
+  // Methods for child components
+  startDragging(): void {
+    this.isDragging.set(true);
+  }
+
+  stopDragging(): void {
+    this.isDragging.set(false);
+  }
+
+  updatePosition(clientX: number, clientY: number, rect: DOMRect): void {
+    let position: number;
+    if (this.orientation() === 'horizontal') {
+      position = ((clientX - rect.left) / rect.width) * 100;
+    } else {
+      position = ((clientY - rect.top) / rect.height) * 100;
+    }
+
+    this.position.set(Math.max(0, Math.min(100, position)));
+  }
+
+  moveSlider(direction: 'forward' | 'backward', step = 1): void {
+    const current = this.position();
+    const newPosition =
+      direction === 'forward'
+        ? Math.min(100, current + step)
+        : Math.max(0, current - step);
+    this.position.set(newPosition);
+  }
+
+  setPositionToStart(): void {
+    this.position.set(0);
+  }
+
+  setPositionToEnd(): void {
+    this.position.set(100);
+  }
+}

package/src/lib/components/image-compare/index.ts

@@ -0,0 +1,10 @@
+export {
+  ScImageCompareDirective,
+  ScImageCompareDirective as ScImageCompare,
+  SC_IMAGE_COMPARE,
+} from './image-compare';
+export { ScImageCompareContainer } from './image-compare-container';
+export { ScImageCompareBefore } from './image-compare-before';
+export { ScImageCompareAfter } from './image-compare-after';
+export { ScImageCompareSlider } from './image-compare-slider';
+export { ScImageCompareLabel } from './image-compare-label';