@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/hover-card/README.md

@@ -0,0 +1,118 @@
+# Hover Card Components
+
+For sighted users to preview content available behind a link.
+
+## Architecture
+
+```
+ScHoverCardProvider (Root)
+    ├── open: signal<boolean>
+    ├── side: input ('top' | 'right' | 'bottom' | 'left')
+    ├── align: input ('start' | 'center' | 'end')
+    ├── openDelay: input (default: 700ms)
+    └── closeDelay: input (default: 300ms)
+         │
+         ├── ScHoverCardTrigger
+         │     ├── Injects ScHoverCardProvider
+         │     ├── Uses CdkOverlayOrigin
+         │     └── Handles hover/focus with delay
+         │
+         └── ScHoverCardPortal
+               ├── Injects ScHoverCardProvider
+               ├── Uses cdkConnectedOverlay
+               └── Positions based on side/align
+                    │
+                    └── ScHoverCard
+                          ├── Injects ScHoverCardProvider
+                          ├── Content panel with styling
+                          └── Handles hover to keep card open
+```
+
+## Components
+
+| Component             | Selector                      | Description                                     |
+| --------------------- | ----------------------------- | ----------------------------------------------- |
+| `ScHoverCardProvider` | `div[sc-hover-card-provider]` | Root wrapper with state and configuration       |
+| `ScHoverCardTrigger`  | `[sc-hover-card-trigger]`     | Element that triggers hover card on hover/focus |
+| `ScHoverCardPortal`   | `div[sc-hover-card-portal]`   | CDK overlay positioning layer                   |
+| `ScHoverCard`         | `div[sc-hover-card]`          | The card content displayed on hover             |
+
+## Inputs
+
+### ScHoverCardProvider
+
+| Input        | Type                                     | Default    | Description                 |
+| ------------ | ---------------------------------------- | ---------- | --------------------------- |
+| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Which side to show the card |
+| `align`      | `'start' \| 'center' \| 'end'`           | `'center'` | Alignment along the side    |
+| `openDelay`  | `number`                                 | `700`      | Delay before showing (ms)   |
+| `closeDelay` | `number`                                 | `300`      | Delay before hiding (ms)    |
+
+## Usage
+
+```html
+<div sc-hover-card-provider>
+  <a sc-hover-card-trigger href="/profile">@username</a>
+  <div sc-hover-card-portal>
+    <div sc-hover-card>
+      <div class="flex gap-4">
+        <img src="avatar.jpg" class="size-12 rounded-full" />
+        <div>
+          <h4 class="font-semibold">@username</h4>
+          <p class="text-sm text-muted-foreground">Software developer at Example Corp.</p>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### With Custom Position
+
+```html
+<div sc-hover-card-provider side="right" align="start">
+  <button sc-hover-card-trigger>Hover me</button>
+  <div sc-hover-card-portal>
+    <div sc-hover-card>Content appears to the right, aligned to the top</div>
+  </div>
+</div>
+```
+
+### With Custom Delays
+
+```html
+<div sc-hover-card-provider [openDelay]="500" [closeDelay]="200">
+  <span sc-hover-card-trigger>Quick hover</span>
+  <div sc-hover-card-portal>
+    <div sc-hover-card>Shows faster, hides faster</div>
+  </div>
+</div>
+```
+
+## Position Combinations
+
+The component supports 12 position combinations:
+
+| Side     | Align Options            |
+| -------- | ------------------------ |
+| `top`    | `start`, `center`, `end` |
+| `bottom` | `start`, `center`, `end` |
+| `left`   | `start`, `center`, `end` |
+| `right`  | `start`, `center`, `end` |
+
+## Differences from Tooltip
+
+| Feature     | Hover Card                   | Tooltip          |
+| ----------- | ---------------------------- | ---------------- |
+| Content     | Rich content (cards, images) | Simple text      |
+| Styling     | Card with border/shadow      | Solid background |
+| Open delay  | 700ms (longer)               | 200ms (shorter)  |
+| Close delay | 300ms (has delay)            | 0ms (instant)    |
+| Width       | 256px default                | Auto             |
+
+## Accessibility
+
+- Content remains visible when hovering over the card itself
+- Supports focus trigger for keyboard users
+- Uses connected overlay for proper positioning
+- Close delay allows mouse movement to the card

package/src/lib/components/hover-card/hover-card-portal.ts

@@ -0,0 +1,142 @@
+import { ConnectedPosition, OverlayModule } from '@angular/cdk/overlay';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import {
+  HoverCardAlign,
+  HoverCardSide,
+  ScHoverCardProvider,
+} from './hover-card-provider';
+
+type PositionKey = `${HoverCardSide}-${HoverCardAlign}`;
+
+const positionMap: Record<PositionKey, ConnectedPosition> = {
+  'top-start': {
+    originX: 'start',
+    originY: 'top',
+    overlayX: 'start',
+    overlayY: 'bottom',
+    offsetY: -4,
+  },
+  'top-center': {
+    originX: 'center',
+    originY: 'top',
+    overlayX: 'center',
+    overlayY: 'bottom',
+    offsetY: -4,
+  },
+  'top-end': {
+    originX: 'end',
+    originY: 'top',
+    overlayX: 'end',
+    overlayY: 'bottom',
+    offsetY: -4,
+  },
+  'bottom-start': {
+    originX: 'start',
+    originY: 'bottom',
+    overlayX: 'start',
+    overlayY: 'top',
+    offsetY: 4,
+  },
+  'bottom-center': {
+    originX: 'center',
+    originY: 'bottom',
+    overlayX: 'center',
+    overlayY: 'top',
+    offsetY: 4,
+  },
+  'bottom-end': {
+    originX: 'end',
+    originY: 'bottom',
+    overlayX: 'end',
+    overlayY: 'top',
+    offsetY: 4,
+  },
+  'left-start': {
+    originX: 'start',
+    originY: 'top',
+    overlayX: 'end',
+    overlayY: 'top',
+    offsetX: -4,
+  },
+  'left-center': {
+    originX: 'start',
+    originY: 'center',
+    overlayX: 'end',
+    overlayY: 'center',
+    offsetX: -4,
+  },
+  'left-end': {
+    originX: 'start',
+    originY: 'bottom',
+    overlayX: 'end',
+    overlayY: 'bottom',
+    offsetX: -4,
+  },
+  'right-start': {
+    originX: 'end',
+    originY: 'top',
+    overlayX: 'start',
+    overlayY: 'top',
+    offsetX: 4,
+  },
+  'right-center': {
+    originX: 'end',
+    originY: 'center',
+    overlayX: 'start',
+    overlayY: 'center',
+    offsetX: 4,
+  },
+  'right-end': {
+    originX: 'end',
+    originY: 'bottom',
+    overlayX: 'start',
+    overlayY: 'bottom',
+    offsetX: 4,
+  },
+};
+
+@Component({
+  selector: 'div[sc-hover-card-portal]',
+  imports: [OverlayModule],
+  template: `
+    @if (origin(); as origin) {
+      <ng-template
+        cdkConnectedOverlay
+        [cdkConnectedOverlayOrigin]="origin"
+        [cdkConnectedOverlayOpen]="hoverCardProvider.overlayOpen()"
+        [cdkConnectedOverlayPositions]="[position()]"
+      >
+        <ng-content />
+      </ng-template>
+    }
+  `,
+  host: {
+    'data-slot': 'hover-card-portal',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScHoverCardPortal {
+  readonly hoverCardProvider = inject(ScHoverCardProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly origin = computed(() => this.hoverCardProvider.origin());
+
+  protected readonly position = computed(() => {
+    const side = this.hoverCardProvider.side();
+    const align = this.hoverCardProvider.align();
+    const key: PositionKey = `${side}-${align}`;
+    return positionMap[key];
+  });
+
+  protected readonly class = computed(() => cn('', this.classInput()));
+}

package/src/lib/components/hover-card/hover-card-provider.ts

@@ -0,0 +1,85 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  contentChild,
+  effect,
+  input,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScHoverCardTrigger } from './hover-card-trigger';
+
+export type HoverCardSide = 'top' | 'right' | 'bottom' | 'left';
+export type HoverCardAlign = 'start' | 'center' | 'end';
+
+@Component({
+  selector: 'div[sc-hover-card-provider]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'hover-card-provider',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScHoverCardProvider {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  /** Which side the hover card appears on */
+  readonly side = input<HoverCardSide>('bottom');
+
+  /** Alignment along the side */
+  readonly align = input<HoverCardAlign>('center');
+
+  /** Delay before showing hover card (ms) */
+  readonly openDelay = input<number>(700);
+
+  /** Delay before hiding hover card (ms) */
+  readonly closeDelay = input<number>(300);
+
+  /** Whether the hover card is logically open (controls animation state) */
+  readonly open = signal<boolean>(false);
+
+  /** Whether the overlay should be physically open (stays true during close animation) */
+  readonly overlayOpen = signal<boolean>(false);
+
+  private readonly triggerChild = contentChild(ScHoverCardTrigger);
+
+  readonly origin = computed(() => this.triggerChild()?.overlayOrigin);
+
+  protected readonly class = computed(() =>
+    cn('relative inline-block', this.classInput()),
+  );
+
+  constructor() {
+    // When opening, open overlay immediately
+    effect(() => {
+      if (this.open()) {
+        this.overlayOpen.set(true);
+      }
+    });
+  }
+
+  show(): void {
+    this.open.set(true);
+  }
+
+  hide(): void {
+    this.open.set(false);
+    // overlayOpen will be set to false by onAnimationComplete
+  }
+
+  /** Called by hover-card when close animation completes */
+  onAnimationComplete(): void {
+    this.overlayOpen.set(false);
+  }
+
+  /** Cancel pending hide timeout on the trigger */
+  cancelTriggerHide(): void {
+    this.triggerChild()?.cancelHide();
+  }
+}

package/src/lib/components/hover-card/hover-card-trigger.ts

@@ -0,0 +1,75 @@
+import { CdkOverlayOrigin } from '@angular/cdk/overlay';
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScHoverCardProvider } from './hover-card-provider';
+
+@Directive({
+  selector: '[sc-hover-card-trigger]',
+  hostDirectives: [CdkOverlayOrigin],
+  host: {
+    'data-slot': 'hover-card-trigger',
+    '[class]': 'class()',
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+  },
+})
+export class ScHoverCardTrigger {
+  readonly hoverCardProvider = inject(ScHoverCardProvider);
+  readonly overlayOrigin = inject(CdkOverlayOrigin);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  private showTimeout: ReturnType<typeof setTimeout> | null = null;
+  private hideTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  protected readonly class = computed(() => cn('', this.classInput()));
+
+  onMouseEnter(): void {
+    this.cancelHide();
+    this.scheduleShow();
+  }
+
+  onMouseLeave(): void {
+    this.cancelShow();
+    this.scheduleHide();
+  }
+
+  onFocus(): void {
+    this.cancelHide();
+    this.scheduleShow();
+  }
+
+  onBlur(): void {
+    this.cancelShow();
+    this.scheduleHide();
+  }
+
+  private scheduleShow(): void {
+    this.cancelShow();
+    this.showTimeout = setTimeout(() => {
+      this.hoverCardProvider.show();
+    }, this.hoverCardProvider.openDelay());
+  }
+
+  private cancelShow(): void {
+    if (this.showTimeout) {
+      clearTimeout(this.showTimeout);
+      this.showTimeout = null;
+    }
+  }
+
+  private scheduleHide(): void {
+    this.cancelHide();
+    this.hideTimeout = setTimeout(() => {
+      this.hoverCardProvider.hide();
+    }, this.hoverCardProvider.closeDelay());
+  }
+
+  cancelHide(): void {
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+      this.hideTimeout = null;
+    }
+  }
+}

package/src/lib/components/hover-card/hover-card.ts

@@ -0,0 +1,97 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  output,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScHoverCardProvider } from './hover-card-provider';
+
+type ScHoverCardState = 'open' | 'closed';
+
+@Component({
+  selector: 'div[sc-hover-card]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'hover-card',
+    '[class]': 'class()',
+    '[attr.data-state]': 'state()',
+    '[attr.data-side]': 'hoverCardProvider.side()',
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()',
+    '(animationend)': 'onAnimationEnd($event)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScHoverCard {
+  private readonly elementRef = inject(ElementRef);
+
+  readonly hoverCardProvider = inject(ScHoverCardProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly state = signal<ScHoverCardState>('closed');
+  readonly animationComplete = output<void>();
+
+  protected readonly class = computed(() =>
+    cn(
+      'z-50 w-64 rounded-lg border bg-popover p-2.5 text-sm text-popover-foreground shadow-md outline-none',
+      'animate-in fade-in-0 zoom-in-95 duration-100',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+      'data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+      this.classInput(),
+    ),
+  );
+
+  private hideTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  constructor() {
+    // Sync state with provider's open signal
+    effect(() => {
+      const isOpen = this.hoverCardProvider.open();
+      this.state.set(isOpen ? 'open' : 'closed');
+    });
+  }
+
+  onMouseEnter(): void {
+    this.hoverCardProvider.cancelTriggerHide();
+    this.cancelHide();
+    this.hoverCardProvider.show();
+  }
+
+  onMouseLeave(): void {
+    this.scheduleHide();
+  }
+
+  private scheduleHide(): void {
+    this.cancelHide();
+    this.hideTimeout = setTimeout(() => {
+      this.hoverCardProvider.hide();
+    }, this.hoverCardProvider.closeDelay());
+  }
+
+  private cancelHide(): void {
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+      this.hideTimeout = null;
+    }
+  }
+
+  protected onAnimationEnd(event: AnimationEvent): void {
+    // Only emit when close animation completes
+    if (
+      this.state() === 'closed' &&
+      event.target === this.elementRef.nativeElement
+    ) {
+      this.animationComplete.emit();
+      this.hoverCardProvider.onAnimationComplete();
+    }
+  }
+}

package/src/lib/components/hover-card/index.ts

@@ -0,0 +1,5 @@
+export { ScHoverCardProvider } from './hover-card-provider';
+export type { HoverCardAlign, HoverCardSide } from './hover-card-provider';
+export { ScHoverCardPortal } from './hover-card-portal';
+export { ScHoverCard } from './hover-card';
+export { ScHoverCardTrigger } from './hover-card-trigger';

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

@@ -0,0 +1,132 @@
+# Image Annotator
+
+A canvas-based image annotation component with drawing tools for adding annotations on top of images.
+
+## Installation
+
+```typescript
+import { ScImageAnnotator } from '@/ui/image-annotator';
+import type { Annotation, AnnotationPoint, AnnotationTool } from '@/ui/image-annotator';
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<sc-image-annotator src="https://example.com/image.jpg" [width]="800" [height]="600" (annotationsChange)="onAnnotationsChange($event)" (save)="onSave($event)" />
+```
+
+```typescript
+onAnnotationsChange(annotations: Annotation[]) {
+  console.log('Annotations updated:', annotations);
+}
+
+onSave(dataUrl: string) {
+  console.log('Image saved as data URL');
+}
+```
+
+### With Custom Dimensions
+
+```html
+<sc-image-annotator src="/assets/photo.png" [width]="1200" [height]="800" />
+```
+
+### Programmatic Control
+
+```html
+<sc-image-annotator #annotator [src]="imageSrc" />
+
+<button (click)="loadAnnotations()">Load</button>
+<button (click)="clearAnnotations()">Clear</button>
+```
+
+```typescript
+@ViewChild('annotator') annotator!: ScImageAnnotator;
+
+loadAnnotations() {
+  this.annotator.setAnnotations(savedAnnotations);
+}
+
+clearAnnotations() {
+  this.annotator.clearAll();
+}
+
+getAnnotations() {
+  return this.annotator.getAnnotations();
+}
+```
+
+## API Reference
+
+### Inputs
+
+| Input    | Type     | Default    | Description             |
+| -------- | -------- | ---------- | ----------------------- |
+| `src`    | `string` | (required) | Image source URL        |
+| `width`  | `number` | `600`      | Canvas width in pixels  |
+| `height` | `number` | `400`      | Canvas height in pixels |
+| `class`  | `string` | `''`       | Additional CSS classes  |
+
+### Outputs
+
+| Output              | Type           | Description                               |
+| ------------------- | -------------- | ----------------------------------------- |
+| `annotationsChange` | `Annotation[]` | Emitted when annotations are modified     |
+| `save`              | `string`       | Emitted with data URL when image is saved |
+
+### Methods
+
+| Method                           | Description                      |
+| -------------------------------- | -------------------------------- |
+| `getAnnotations(): Annotation[]` | Get current annotations          |
+| `setAnnotations(annotations)`    | Set annotations programmatically |
+| `undo()`                         | Remove last annotation           |
+| `clearAll()`                     | Clear all annotations            |
+| `download()`                     | Download annotated image as PNG  |
+
+## Type Definitions
+
+```typescript
+type AnnotationTool = 'pen' | 'line' | 'rectangle' | 'circle' | 'arrow' | 'text' | 'eraser';
+
+interface AnnotationPoint {
+  x: number;
+  y: number;
+}
+
+interface Annotation {
+  id: string;
+  tool: AnnotationTool;
+  points: AnnotationPoint[];
+  color: string;
+  lineWidth: number;
+  text?: string;
+}
+```
+
+## Available Tools
+
+| Tool      | Description                      |
+| --------- | -------------------------------- |
+| Pen       | Freehand drawing                 |
+| Line      | Straight line between two points |
+| Rectangle | Rectangle shape                  |
+| Circle    | Circle/ellipse from center point |
+| Arrow     | Line with arrowhead              |
+| Eraser    | Remove annotations by proximity  |
+
+## Features
+
+- Multiple drawing tools (pen, line, rectangle, circle, arrow)
+- Eraser tool for removing annotations
+- Color picker with preset colors
+- Adjustable line width
+- Undo functionality
+- Clear all annotations
+- Download annotated image as PNG
+- Cross-origin image support
+- Real-time annotation preview
+- Toolbar with tool selection
+- Programmatic annotation control

package/src/lib/components/image-annotator/image-annotator-types.ts

@@ -0,0 +1,29 @@
+export type AnnotationTool =
+  | 'pen'
+  | 'line'
+  | 'rectangle'
+  | 'circle'
+  | 'arrow'
+  | 'text'
+  | 'eraser';
+
+export interface AnnotationPoint {
+  x: number;
+  y: number;
+}
+
+export interface Annotation {
+  id: string;
+  tool: AnnotationTool;
+  points: AnnotationPoint[];
+  color: string;
+  lineWidth: number;
+  text?: string;
+}
+
+export interface ImageAnnotatorState {
+  annotations: Annotation[];
+  currentTool: AnnotationTool;
+  currentColor: string;
+  lineWidth: number;
+}