@semantic-components/ui-lab 0.63.0 → 0.65.0

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

@@ -1,322 +0,0 @@
-# Image Cropper
-
-An interactive image cropping component with drag, resize, zoom, and aspect ratio controls. Built using the composable architecture pattern for maximum flexibility.
-
-## Components
-
-- `ScImageCropper` (directive) - Root state management
-- `ScImageCropperContainer` - Interactive UI with crop area, grid, handles, and canvas
-- `ScImageCropperControls` - Zoom slider with buttons
-- `ScImageCropperPreview` - Live preview of the cropped area
-- `ScImageCropperAspectRatio` - Aspect ratio selector buttons
-
-## Basic Usage
-
-```html
-<div sc-image-cropper [src]="imageUrl" [(cropArea)]="cropArea" [containerHeight]="400">
-  <div sc-image-cropper-container #container class="rounded-lg overflow-hidden border"></div>
-
-  <div sc-image-cropper-controls></div>
-
-  <button (click)="cropImage(container)">Crop</button>
-</div>
-```
-
-```typescript
-async cropImage(container: InstanceType<typeof ScImageCropperContainer>) {
-  const result = await container.crop();
-  console.log(result.dataUrl); // Base64 image
-  console.log(result.blob); // Blob for upload
-}
-```
-
-## API
-
-### ScImageCropper (Directive)
-
-The root directive that manages state.
-
-**Selector:** `[sc-image-cropper]`
-
-**Inputs:**
-
-| Input             | Type                                          | Default       | Description            |
-| ----------------- | --------------------------------------------- | ------------- | ---------------------- |
-| `src`             | `string`                                      | Required      | Image source URL       |
-| `aspectRatio`     | `number \| null`                              | `null`        | Lock aspect ratio      |
-| `minWidth`        | `number`                                      | `50`          | Minimum crop width     |
-| `minHeight`       | `number`                                      | `50`          | Minimum crop height    |
-| `containerHeight` | `number`                                      | `400`         | Container height in px |
-| `showGrid`        | `boolean`                                     | `true`        | Show rule of thirds    |
-| `disabled`        | `boolean`                                     | `false`       | Disable interactions   |
-| `outputType`      | `'image/png' \| 'image/jpeg' \| 'image/webp'` | `'image/png'` | Output format          |
-| `outputQuality`   | `number`                                      | `0.92`        | JPEG/WebP quality      |
-
-**Two-way Bindings:**
-
-| Binding    | Type       | Description              |
-| ---------- | ---------- | ------------------------ |
-| `cropArea` | `CropArea` | Current crop coordinates |
-| `zoom`     | `number`   | Current zoom level       |
-
-**Outputs:**
-
-| Output        | Type                                | Description       |
-| ------------- | ----------------------------------- | ----------------- |
-| `cropChange`  | `CropArea`                          | Crop area changed |
-| `imageLoaded` | `{ width: number; height: number }` | Image loaded      |
-
-### ScImageCropperContainer
-
-The interactive UI component that renders the image, crop area, grid, handles, and hidden canvas.
-
-**Selector:** `[sc-image-cropper-container]`
-
-**Inputs:**
-
-| Input   | Type     | Default | Description          |
-| ------- | -------- | ------- | -------------------- |
-| `class` | `string` | `''`    | Additional CSS class |
-
-**Methods (via template reference):**
-
-| Method            | Returns               | Description           |
-| ----------------- | --------------------- | --------------------- |
-| `crop()`          | `Promise<CropResult>` | Get cropped image     |
-| `resetCropArea()` | `void`                | Reset to initial crop |
-
-### ScImageCropperControls
-
-Zoom slider with zoom in/out buttons.
-
-**Selector:** `[sc-image-cropper-controls]`
-
-**Inputs:**
-
-| Input   | Type     | Default | Description          |
-| ------- | -------- | ------- | -------------------- |
-| `class` | `string` | `''`    | Additional CSS class |
-
-### ScImageCropperPreview
-
-Live preview of the cropped area.
-
-**Selector:** `[sc-image-cropper-preview]`
-
-**Inputs:**
-
-| Input    | Type     | Default | Description          |
-| -------- | -------- | ------- | -------------------- |
-| `width`  | `number` | `200`   | Preview width        |
-| `height` | `number` | `200`   | Preview height       |
-| `class`  | `string` | `''`    | Additional CSS class |
-
-### ScImageCropperAspectRatio
-
-Aspect ratio selector with predefined options.
-
-**Selector:** `[sc-image-cropper-aspect-ratio]`
-
-**Inputs:**
-
-| Input     | Type                                          | Default                  | Description          |
-| --------- | --------------------------------------------- | ------------------------ | -------------------- |
-| `options` | `Array<{label: string, value: number\|null}>` | `[Free, 1:1, 4:3, 16:9]` | Aspect ratio options |
-| `class`   | `string`                                      | `''`                     | Additional CSS class |
-
-**Outputs:**
-
-| Output              | Type             | Description                     |
-| ------------------- | ---------------- | ------------------------------- |
-| `aspectRatioChange` | `number \| null` | Emits when aspect ratio changes |
-
-## Examples
-
-### Basic Cropping
-
-```html
-<div sc-image-cropper [src]="imageSrc()" [(cropArea)]="cropArea" [containerHeight]="400">
-  <div sc-image-cropper-container #container class="rounded-lg border"></div>
-
-  <div sc-image-cropper-controls></div>
-
-  <button (click)="cropImage(container)">Crop Image</button>
-</div>
-```
-
-```typescript
-@Component({...})
-export class MyComponent {
-  readonly imageSrc = signal('https://example.com/image.jpg');
-  readonly cropArea = signal<CropArea>({ x: 50, y: 50, width: 200, height: 200 });
-  readonly croppedImage = signal<string | null>(null);
-
-  async cropImage(container: InstanceType<typeof ScImageCropperContainer>) {
-    const result = await container.crop();
-    this.croppedImage.set(result.dataUrl);
-  }
-}
-```
-
-### With Aspect Ratio Selector
-
-```html
-<div sc-image-cropper [src]="imageSrc()" [aspectRatio]="selectedAspectRatio()" [containerHeight]="400">
-  <div sc-image-cropper-container class="rounded-lg border"></div>
-
-  <div sc-image-cropper-aspect-ratio [options]="aspectRatioOptions" (aspectRatioChange)="selectedAspectRatio.set($event)"></div>
-
-  <div sc-image-cropper-controls></div>
-</div>
-```
-
-```typescript
-readonly selectedAspectRatio = signal<number | null>(null);
-readonly aspectRatioOptions = [
-  { label: 'Free', value: null },
-  { label: '1:1', value: 1 },
-  { label: '4:3', value: 4 / 3 },
-  { label: '16:9', value: 16 / 9 },
-];
-```
-
-### Avatar Cropper with Preview
-
-```html
-<div sc-image-cropper [src]="imageSrc()" [aspectRatio]="1" [containerHeight]="300">
-  <div sc-image-cropper-container class="rounded-lg border"></div>
-
-  <div class="flex gap-8">
-    <div class="flex-1">
-      <div sc-image-cropper-controls></div>
-    </div>
-
-    <div class="space-y-4">
-      <p class="text-sm font-medium">Preview:</p>
-      <div sc-image-cropper-preview [width]="100" [height]="100" class="rounded-full overflow-hidden"></div>
-    </div>
-  </div>
-</div>
-```
-
-### Custom Output Format
-
-```html
-<div sc-image-cropper [src]="imageSrc()" [outputType]="'image/jpeg'" [outputQuality]="0.9">
-  <div sc-image-cropper-container #container></div>
-  <button (click)="container.crop()">Crop as JPEG</button>
-</div>
-```
-
-### File Upload + Cropping
-
-```html
-<div class="space-y-4">
-  <input type="file" accept="image/*" (change)="onFileChange($event)" />
-
-  @if (uploadedImage()) {
-  <div sc-image-cropper [src]="uploadedImage()!" [containerHeight]="400">
-    <div sc-image-cropper-container #container class="rounded-lg border"></div>
-
-    <div sc-image-cropper-controls></div>
-
-    <button (click)="cropAndDownload(container)">Crop & Download</button>
-  </div>
-  }
-</div>
-```
-
-```typescript
-readonly uploadedImage = signal<string | null>(null);
-
-onFileChange(event: Event) {
-  const file = (event.target as HTMLInputElement).files?.[0];
-  if (file) {
-    const reader = new FileReader();
-    reader.onload = () => {
-      this.uploadedImage.set(reader.result as string);
-    };
-    reader.readAsDataURL(file);
-  }
-}
-
-async cropAndDownload(container: InstanceType<typeof ScImageCropperContainer>) {
-  const result = await container.crop();
-  const link = document.createElement('a');
-  link.href = result.dataUrl;
-  link.download = 'cropped-image.png';
-  link.click();
-}
-```
-
-### Real-time Crop Info
-
-```html
-<div sc-image-cropper [src]="imageSrc()" [(cropArea)]="cropArea">
-  <div sc-image-cropper-container class="rounded-lg border"></div>
-
-  <div class="grid grid-cols-2 gap-4 text-sm">
-    <div>X: {{ cropArea().x.toFixed(0) }}px</div>
-    <div>Y: {{ cropArea().y.toFixed(0) }}px</div>
-    <div>Width: {{ cropArea().width.toFixed(0) }}px</div>
-    <div>Height: {{ cropArea().height.toFixed(0) }}px</div>
-  </div>
-</div>
-```
-
-## Types
-
-### CropArea
-
-```typescript
-interface CropArea {
-  x: number; // Left position
-  y: number; // Top position
-  width: number; // Crop width
-  height: number; // Crop height
-}
-```
-
-### CropResult
-
-```typescript
-interface CropResult {
-  dataUrl: string; // Base64 data URL
-  blob: Blob | null; // Blob for uploading
-  width: number; // Output image width
-  height: number; // Output image height
-}
-```
-
-## Composable Architecture
-
-This component follows the composable architecture pattern:
-
-- **Root Directive** (`sc-image-cropper`): Manages all state (crop area, zoom, aspect ratio, drag/resize)
-- **Container** (`sc-image-cropper-container`): Renders UI (image, overlay, crop area, grid, handles, canvas) and handles interactions
-- **Controls**: Optional zoom controls
-- **Preview**: Optional live preview
-- **Aspect Ratio**: Optional aspect ratio selector
-
-Benefits:
-
-- Separation of concerns: state vs UI
-- Container handles all interactions (mouse, touch, drag, resize)
-- Can add custom UI elements between components
-- Methods like `crop()` and `resetCropArea()` are called on the container via template reference
-
-## Accessibility
-
-- Keyboard support for fine adjustments
-- Screen reader announcements for crop area changes
-- Focus indicators for interactive elements
-- Touch-friendly resize handles
-- ARIA labels for all controls
-
-## Notes
-
-- Images are loaded via `<img>` and rendered on a hidden `<canvas>` for cropping
-- The crop operation preserves the original image quality
-- Supports zoom from 0.1x to 3x
-- Aspect ratios are maintained during resize when specified
-- All calculations are done in natural image coordinates for accuracy

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

@@ -1,65 +0,0 @@
-import {
-  ChangeDetectionStrategy,
-  Component,
-  computed,
-  inject,
-  input,
-  output,
-  ViewEncapsulation,
-} from '@angular/core';
-import { cn } from '@semantic-components/ui';
-import { SC_IMAGE_CROPPER } from './image-cropper';
-
-@Component({
-  selector: '[sc-image-cropper-aspect-ratio]',
-  template: `
-    <div class="flex items-center gap-1">
-      @for (option of options(); track option.value) {
-        <button
-          type="button"
-          class="px-3 py-1 text-sm rounded-md border transition-colors"
-          [class]="
-            isSelected(option.value)
-              ? 'bg-primary text-primary-foreground'
-              : 'bg-background hover:bg-accent'
-          "
-          (click)="selectAspectRatio(option.value)"
-        >
-          {{ option.label }}
-        </button>
-      }
-    </div>
-  `,
-  host: {
-    'data-slot': 'image-cropper-aspect-ratio',
-    '[class]': 'class()',
-  },
-  encapsulation: ViewEncapsulation.None,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class ScImageCropperAspectRatio {
-  readonly cropper = inject(SC_IMAGE_CROPPER);
-
-  readonly classInput = input<string>('', { alias: 'class' });
-  readonly options = input<{ label: string; value: number | null }[]>([
-    { label: 'Free', value: null },
-    { label: '1:1', value: 1 },
-    { label: '4:3', value: 4 / 3 },
-    { label: '16:9', value: 16 / 9 },
-  ]);
-
-  readonly aspectRatioChange = output<number | null>();
-
-  protected readonly class = computed(() => cn('', this.classInput()));
-
-  isSelected(value: number | null): boolean {
-    const current = this.cropper.aspectRatio();
-    if (value === null && current === null) return true;
-    if (value === null || current === null) return false;
-    return Math.abs(current - value) < 0.001;
-  }
-
-  selectAspectRatio(value: number | null): void {
-    this.aspectRatioChange.emit(value);
-  }
-}

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

@@ -1,294 +0,0 @@
-import {
-  afterNextRender,
-  ChangeDetectionStrategy,
-  Component,
-  computed,
-  ElementRef,
-  inject,
-  input,
-  ViewEncapsulation,
-  viewChild,
-} from '@angular/core';
-import { cn } from '@semantic-components/ui';
-import { SC_IMAGE_CROPPER } from './image-cropper';
-
-@Component({
-  selector: '[sc-image-cropper-container]',
-  template: `
-    <div
-      class="relative overflow-hidden bg-black/90 select-none"
-      [style.height.px]="cropper.containerHeight()"
-    >
-      <!-- Image container -->
-      <div
-        class="absolute inset-0 flex items-center justify-center"
-        [style.transform]="imageTransform()"
-      >
-        <img
-          #imageEl
-          [src]="cropper.src()"
-          class="max-w-none"
-          [style.width.px]="scaledImageWidth()"
-          [style.height.px]="scaledImageHeight()"
-          (load)="onImageLoad()"
-          draggable="false"
-          alt="Image to crop"
-        />
-      </div>
-
-      <!-- Overlay mask -->
-      <div class="absolute inset-0 pointer-events-none">
-        <svg class="w-full h-full">
-          <defs>
-            <mask id="cropMask">
-              <rect width="100%" height="100%" fill="white" />
-              <rect
-                [attr.x]="cropper.cropArea().x"
-                [attr.y]="cropper.cropArea().y"
-                [attr.width]="cropper.cropArea().width"
-                [attr.height]="cropper.cropArea().height"
-                fill="black"
-              />
-            </mask>
-          </defs>
-          <rect
-            width="100%"
-            height="100%"
-            fill="rgba(0,0,0,0.5)"
-            mask="url(#cropMask)"
-          />
-        </svg>
-      </div>
-
-      <!-- Crop area -->
-      <div
-        class="absolute border-2 border-white cursor-move"
-        [style.left.px]="cropper.cropArea().x"
-        [style.top.px]="cropper.cropArea().y"
-        [style.width.px]="cropper.cropArea().width"
-        [style.height.px]="cropper.cropArea().height"
-        (mousedown)="onCropAreaMouseDown($event)"
-        (touchstart)="onCropAreaTouchStart($event)"
-        (mousemove)="onMouseMove($event)"
-        (touchmove)="onTouchMove($event)"
-      >
-        <!-- Grid lines -->
-        @if (cropper.showGrid()) {
-          <div class="absolute inset-0 pointer-events-none">
-            <div
-              class="absolute left-1/3 top-0 bottom-0 w-px bg-white/30"
-            ></div>
-            <div
-              class="absolute left-2/3 top-0 bottom-0 w-px bg-white/30"
-            ></div>
-            <div class="absolute top-1/3 left-0 right-0 h-px bg-white/30"></div>
-            <div class="absolute top-2/3 left-0 right-0 h-px bg-white/30"></div>
-          </div>
-        }
-
-        <!-- Resize handles -->
-        @if (!cropper.disabled()) {
-          <!-- Corners -->
-          <div
-            class="absolute -left-1.5 -top-1.5 size-3 bg-white border border-gray-400 cursor-nw-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'nw')"
-            (touchstart)="onHandleTouchStart($event, 'nw')"
-          ></div>
-          <div
-            class="absolute -right-1.5 -top-1.5 size-3 bg-white border border-gray-400 cursor-ne-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'ne')"
-            (touchstart)="onHandleTouchStart($event, 'ne')"
-          ></div>
-          <div
-            class="absolute -left-1.5 -bottom-1.5 size-3 bg-white border border-gray-400 cursor-sw-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'sw')"
-            (touchstart)="onHandleTouchStart($event, 'sw')"
-          ></div>
-          <div
-            class="absolute -right-1.5 -bottom-1.5 size-3 bg-white border border-gray-400 cursor-se-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'se')"
-            (touchstart)="onHandleTouchStart($event, 'se')"
-          ></div>
-
-          <!-- Edges -->
-          <div
-            class="absolute left-1/2 -translate-x-1/2 -top-1.5 w-6 h-3 bg-white border border-gray-400 cursor-n-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'n')"
-            (touchstart)="onHandleTouchStart($event, 'n')"
-          ></div>
-          <div
-            class="absolute left-1/2 -translate-x-1/2 -bottom-1.5 w-6 h-3 bg-white border border-gray-400 cursor-s-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 's')"
-            (touchstart)="onHandleTouchStart($event, 's')"
-          ></div>
-          <div
-            class="absolute top-1/2 -translate-y-1/2 -left-1.5 w-3 h-6 bg-white border border-gray-400 cursor-w-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'w')"
-            (touchstart)="onHandleTouchStart($event, 'w')"
-          ></div>
-          <div
-            class="absolute top-1/2 -translate-y-1/2 -right-1.5 w-3 h-6 bg-white border border-gray-400 cursor-e-resize z-10"
-            (mousedown)="onHandleMouseDown($event, 'e')"
-            (touchstart)="onHandleTouchStart($event, 'e')"
-          ></div>
-        }
-      </div>
-    </div>
-
-    <!-- Hidden canvas for cropping -->
-    <canvas #canvasEl class="hidden"></canvas>
-
-    <!-- Content projection -->
-    <ng-content />
-  `,
-  host: {
-    'data-slot': 'image-cropper-container',
-    '[class]': 'class()',
-  },
-  encapsulation: ViewEncapsulation.None,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class ScImageCropperContainer {
-  readonly cropper = inject(SC_IMAGE_CROPPER);
-  private readonly elementRef = inject(ElementRef<HTMLElement>);
-
-  readonly classInput = input<string>('', { alias: 'class' });
-
-  protected readonly class = computed(() => cn('block', this.classInput()));
-
-  private readonly imageEl = viewChild<ElementRef<HTMLImageElement>>('imageEl');
-  readonly canvasEl = viewChild<ElementRef<HTMLCanvasElement>>('canvasEl');
-
-  protected readonly scaledImageWidth = computed(() =>
-    this.cropper.getScaledImageWidth(),
-  );
-  protected readonly scaledImageHeight = computed(() =>
-    this.cropper.getScaledImageHeight(),
-  );
-
-  protected readonly imageTransform = computed(() => {
-    return `scale(1)`;
-  });
-
-  constructor() {
-    afterNextRender(() => {
-      document.addEventListener(
-        'mousemove',
-        this.onDocumentMouseMove.bind(this),
-      );
-    });
-  }
-
-  private getContainerWidth(): number {
-    return this.elementRef.nativeElement.clientWidth || 400;
-  }
-
-  protected onImageLoad(): void {
-    const img = this.imageEl()?.nativeElement;
-    if (!img) return;
-
-    this.cropper.onImageLoad(img.naturalWidth, img.naturalHeight);
-
-    // Initialize crop area after image loads
-    afterNextRender(() => {
-      this.cropper.initializeCropArea(this.getContainerWidth());
-    });
-  }
-
-  protected onCropAreaMouseDown(event: MouseEvent): void {
-    if (this.cropper.disabled()) return;
-    event.preventDefault();
-    this.cropper.startDragging(event.clientX, event.clientY);
-  }
-
-  protected onCropAreaTouchStart(event: TouchEvent): void {
-    if (this.cropper.disabled()) return;
-    event.preventDefault();
-    const touch = event.touches[0];
-    this.cropper.startDragging(touch.clientX, touch.clientY);
-  }
-
-  protected onHandleMouseDown(event: MouseEvent, handle: string): void {
-    if (this.cropper.disabled()) return;
-    event.preventDefault();
-    event.stopPropagation();
-    this.cropper.startResizing(event.clientX, event.clientY, handle);
-  }
-
-  protected onHandleTouchStart(event: TouchEvent, handle: string): void {
-    if (this.cropper.disabled()) return;
-    event.preventDefault();
-    event.stopPropagation();
-    const touch = event.touches[0];
-    this.cropper.startResizing(touch.clientX, touch.clientY, handle);
-  }
-
-  private onDocumentMouseMove(event: MouseEvent): void {
-    if (this.cropper.isDragging) {
-      this.cropper.handleDrag(
-        event.clientX,
-        event.clientY,
-        this.getContainerWidth(),
-      );
-    } else if (this.cropper.isResizing) {
-      this.cropper.handleResize(
-        event.clientX,
-        event.clientY,
-        this.getContainerWidth(),
-      );
-    }
-  }
-
-  protected onMouseMove(event: MouseEvent): void {
-    if (this.cropper.isDragging) {
-      this.cropper.handleDrag(
-        event.clientX,
-        event.clientY,
-        this.getContainerWidth(),
-      );
-    } else if (this.cropper.isResizing) {
-      this.cropper.handleResize(
-        event.clientX,
-        event.clientY,
-        this.getContainerWidth(),
-      );
-    }
-  }
-
-  protected onTouchMove(event: TouchEvent): void {
-    if (this.cropper.isDragging || this.cropper.isResizing) {
-      event.preventDefault();
-      const touch = event.touches[0];
-      if (this.cropper.isDragging) {
-        this.cropper.handleDrag(
-          touch.clientX,
-          touch.clientY,
-          this.getContainerWidth(),
-        );
-      } else if (this.cropper.isResizing) {
-        this.cropper.handleResize(
-          touch.clientX,
-          touch.clientY,
-          this.getContainerWidth(),
-        );
-      }
-    }
-  }
-
-  // Public method for cropping - can be called via template reference
-  async crop(): Promise<ReturnType<typeof this.cropper.crop>> {
-    const img = this.imageEl()?.nativeElement;
-    const canvas = this.canvasEl()?.nativeElement;
-
-    if (!img || !canvas) {
-      throw new Error('Image or canvas not found');
-    }
-
-    return this.cropper.crop(img, canvas, this.getContainerWidth());
-  }
-
-  // Public method for resetting crop area
-  resetCropArea(): void {
-    this.cropper.resetCropArea(this.getContainerWidth());
-  }
-}