@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/file-upload/file-upload-item.ts

@@ -0,0 +1,35 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { FileUploadFile } from './file-upload';
+
+@Component({
+  selector: '[sc-file-upload-item]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'file-upload-item',
+    '[class]': 'class()',
+    '[attr.data-status]': 'file().status',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScFileUploadItem {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly file = input.required<FileUploadFile>();
+
+  protected readonly class = computed(() =>
+    cn(
+      'flex items-center gap-3 rounded-lg border bg-background p-3',
+      'data-[status=error]:border-destructive data-[status=error]:bg-destructive/10',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/file-upload/file-upload-list.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: '[sc-file-upload-list]',
+  host: {
+    'data-slot': 'file-upload-list',
+    '[class]': 'class()',
+  },
+})
+export class ScFileUploadList {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('mt-4 space-y-2', this.classInput()),
+  );
+}

package/src/lib/components/file-upload/file-upload-trigger.ts

@@ -0,0 +1,70 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { SC_FILE_UPLOAD } from './file-upload';
+
+@Component({
+  selector: 'button[sc-file-upload-trigger]',
+  template: `
+    <input
+      #fileInput
+      type="file"
+      class="sr-only"
+      [multiple]="fileUpload.multiple()"
+      [accept]="fileUpload.accept()"
+      [disabled]="fileUpload.disabled()"
+      (change)="onFileSelect($event)"
+    />
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'file-upload-trigger',
+    type: 'button',
+    '[class]': 'class()',
+    '[disabled]': 'fileUpload.disabled()',
+    '(click)': 'openFilePicker($event)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScFileUploadTrigger {
+  readonly fileUpload = inject(SC_FILE_UPLOAD);
+  private readonly elementRef = inject(ElementRef);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex h-10 items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground',
+      'ring-offset-background transition-colors',
+      'hover:bg-primary/90',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      'disabled:pointer-events-none disabled:opacity-50',
+      this.classInput(),
+    ),
+  );
+
+  openFilePicker(event: Event): void {
+    event.preventDefault();
+    if (this.fileUpload.disabled()) return;
+    const input = this.elementRef.nativeElement.querySelector(
+      'input[type="file"]',
+    ) as HTMLInputElement;
+    input?.click();
+  }
+
+  onFileSelect(event: Event): void {
+    const input = event.target as HTMLInputElement;
+    if (input.files && input.files.length > 0) {
+      this.fileUpload.addFiles(input.files);
+      input.value = '';
+    }
+  }
+}

package/src/lib/components/file-upload/file-upload.ts

@@ -0,0 +1,156 @@
+import {
+  computed,
+  Directive,
+  InjectionToken,
+  input,
+  model,
+  output,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+// Token for file upload context
+export const SC_FILE_UPLOAD = new InjectionToken<ScFileUpload>(
+  'SC_FILE_UPLOAD',
+);
+
+export interface FileUploadFile {
+  file: File;
+  id: string;
+  progress?: number;
+  status: 'pending' | 'uploading' | 'complete' | 'error';
+  error?: string;
+}
+
+@Directive({
+  selector: '[sc-file-upload]',
+  providers: [{ provide: SC_FILE_UPLOAD, useExisting: ScFileUpload }],
+  host: {
+    'data-slot': 'file-upload',
+    '[class]': 'class()',
+  },
+})
+export class ScFileUpload {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly multiple = input<boolean>(false);
+  readonly accept = input<string>('');
+  readonly maxSize = input<number>(0); // in bytes, 0 = no limit
+  readonly maxFiles = input<number>(0); // 0 = no limit
+  readonly disabled = input<boolean>(false);
+
+  readonly files = model<FileUploadFile[]>([]);
+  readonly filesSelected = output<File[]>();
+  readonly fileRemoved = output<FileUploadFile>();
+  readonly error = output<string>();
+
+  protected readonly class = computed(() => cn('block', this.classInput()));
+
+  private generateId(): string {
+    return Math.random().toString(36).substring(2, 11);
+  }
+
+  addFiles(fileList: FileList | File[]): void {
+    if (this.disabled()) return;
+
+    const newFiles = Array.from(fileList);
+    const currentFiles = this.files();
+    const maxFiles = this.maxFiles();
+    const maxSize = this.maxSize();
+    const accept = this.accept();
+
+    const validFiles: File[] = [];
+
+    for (const file of newFiles) {
+      // Check max files limit
+      if (maxFiles > 0 && currentFiles.length + validFiles.length >= maxFiles) {
+        this.error.emit(`Maximum ${maxFiles} files allowed`);
+        break;
+      }
+
+      // Check file size
+      if (maxSize > 0 && file.size > maxSize) {
+        this.error.emit(`File "${file.name}" exceeds maximum size`);
+        continue;
+      }
+
+      // Check file type
+      if (accept && !this.isAcceptedType(file, accept)) {
+        this.error.emit(`File "${file.name}" is not an accepted type`);
+        continue;
+      }
+
+      validFiles.push(file);
+    }
+
+    if (validFiles.length > 0) {
+      const uploadFiles: FileUploadFile[] = validFiles.map((file) => ({
+        file,
+        id: this.generateId(),
+        status: 'pending' as const,
+      }));
+
+      if (this.multiple()) {
+        this.files.update((files) => [...files, ...uploadFiles]);
+      } else {
+        this.files.set(uploadFiles.slice(0, 1));
+      }
+
+      this.filesSelected.emit(validFiles);
+    }
+  }
+
+  removeFile(fileId: string): void {
+    const file = this.files().find((f) => f.id === fileId);
+    if (file) {
+      this.files.update((files) => files.filter((f) => f.id !== fileId));
+      this.fileRemoved.emit(file);
+    }
+  }
+
+  updateFileProgress(fileId: string, progress: number): void {
+    this.files.update((files) =>
+      files.map((f) =>
+        f.id === fileId ? { ...f, progress, status: 'uploading' as const } : f,
+      ),
+    );
+  }
+
+  updateFileStatus(
+    fileId: string,
+    status: FileUploadFile['status'],
+    error?: string,
+  ): void {
+    this.files.update((files) =>
+      files.map((f) => (f.id === fileId ? { ...f, status, error } : f)),
+    );
+  }
+
+  clearFiles(): void {
+    this.files.set([]);
+  }
+
+  private isAcceptedType(file: File, accept: string): boolean {
+    const acceptTypes = accept.split(',').map((t) => t.trim().toLowerCase());
+
+    for (const acceptType of acceptTypes) {
+      if (acceptType.startsWith('.')) {
+        // Extension check
+        if (file.name.toLowerCase().endsWith(acceptType)) {
+          return true;
+        }
+      } else if (acceptType.endsWith('/*')) {
+        // MIME type wildcard (e.g., image/*)
+        const mimePrefix = acceptType.slice(0, -2);
+        if (file.type.toLowerCase().startsWith(mimePrefix)) {
+          return true;
+        }
+      } else {
+        // Exact MIME type match
+        if (file.type.toLowerCase() === acceptType) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+}

package/src/lib/components/file-upload/index.ts

@@ -0,0 +1,11 @@
+export { SC_FILE_UPLOAD, ScFileUpload } from './file-upload';
+export type { FileUploadFile } from './file-upload';
+export { ScFileUploadDropzone } from './file-upload-dropzone';
+export { ScFileUploadTrigger } from './file-upload-trigger';
+export { ScFileUploadList } from './file-upload-list';
+export { ScFileUploadItem } from './file-upload-item';
+export { ScFileUploadItemPreview } from './file-upload-item-preview';
+export { ScFileUploadItemName } from './file-upload-item-name';
+export { ScFileUploadItemSize } from './file-upload-item-size';
+export { ScFileUploadItemDelete } from './file-upload-item-delete';
+export { ScFileUploadItemProgress } from './file-upload-item-progress';

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

@@ -0,0 +1,341 @@
+# Hover Card Architecture
+
+## Overview
+
+The hover card component uses a composable architecture pattern with four main components working together to provide smooth animations and flexible positioning.
+
+## Component Structure
+
+```
+ScHoverCardProvider (Root Container)
+├── ScHoverCardTrigger (Directive)
+└── ScHoverCardPortal
+    └── ScHoverCard (Content)
+```
+
+### 1. ScHoverCardProvider (`hover-card-provider.ts`)
+
+**Role:** Root component that manages state and coordinates child components.
+
+**Key Responsibilities:**
+
+- Manages hover card visibility state
+- Provides configuration (side, align, delays)
+- Coordinates animation timing with overlay lifecycle
+- Exposes trigger origin for positioning
+
+**Important Signals:**
+
+```typescript
+open: Signal<boolean>; // Logical state - "should this show?"
+overlayOpen: Signal<boolean>; // Physical state - "is DOM mounted?"
+```
+
+### 2. ScHoverCardTrigger (`hover-card-trigger.ts`)
+
+**Role:** Directive that marks the trigger element and handles user interactions.
+
+**Key Responsibilities:**
+
+- Provides `CdkOverlayOrigin` for positioning
+- Handles mouse/keyboard events (hover, focus)
+- Manages open/close delays
+- Exposes trigger element reference to provider
+
+### 3. ScHoverCardPortal (`hover-card-portal.ts`)
+
+**Role:** Manages the CDK overlay and positioning.
+
+**Key Responsibilities:**
+
+- Uses CDK `ConnectedOverlay` for positioning
+- Maps `side` + `align` to 12 positioning configurations
+- Binds overlay visibility to `provider.overlayOpen()`
+- Handles positioning offsets (±4px)
+
+### 4. ScHoverCard (`hover-card.ts`)
+
+**Role:** The actual content component with animations.
+
+**Key Responsibilities:**
+
+- Renders hover card content
+- Manages animation state (`'open'` | `'closed'`)
+- Applies animation classes based on state and side
+- Notifies provider when animation completes
+
+## State Management: The Two-Signal Pattern
+
+### Why Two Signals?
+
+The hover card uses **two separate signals** to handle animation timing correctly:
+
+#### `open` - Logical State
+
+- Represents the **intended** visibility
+- Controls the animation state
+- When `false`, triggers the close animation
+
+#### `overlayOpen` - Physical State
+
+- Controls whether content **exists in the DOM**
+- Stays `true` during close animation
+- Only becomes `false` after animation completes
+
+### The Problem This Solves
+
+CDK overlay's `cdkConnectedOverlayOpen` binding works like this:
+
+- `true` → Content is mounted in DOM
+- `false` → Content is **immediately removed** from DOM
+
+If we used only one signal:
+
+```typescript
+// ❌ This doesn't work:
+<cdkConnectedOverlay [cdkConnectedOverlayOpen]="open()">
+  <!-- When open() becomes false, content vanishes instantly -->
+  <!-- No animation plays because DOM is removed -->
+</cdkConnectedOverlay>
+```
+
+With two signals:
+
+```typescript
+// ✅ This works:
+<cdkConnectedOverlay [cdkConnectedOverlayOpen]="overlayOpen()">
+  <!-- overlayOpen stays true during animation -->
+  <!-- Animation plays while content is still in DOM -->
+  <!-- After animation completes, overlayOpen becomes false -->
+</cdkConnectedOverlay>
+```
+
+## Animation Flow
+
+### Opening Sequence
+
+1. **User hovers over trigger**
+
+   ```
+   ScHoverCardTrigger detects mouseenter
+   → Schedules show after openDelay (700ms)
+   → Calls provider.show()
+   ```
+
+2. **Provider opens**
+
+   ```typescript
+   show() {
+     this.open.set(true);  // Effect also sets overlayOpen to true
+   }
+   ```
+
+3. **Overlay renders**
+
+   ```
+   overlayOpen = true → CDK mounts content in DOM
+   ```
+
+4. **Animation plays**
+
+   ```typescript
+   // In ScHoverCard:
+   effect(() => {
+     const isOpen = this.hoverCardProvider.open();
+     this.state.set(isOpen ? 'open' : 'closed');
+   });
+
+   // state = 'open' → Triggers entry animation:
+   // - animate-in fade-in-0 zoom-in-95
+   // - slide-in-from-{direction}
+   ```
+
+### Closing Sequence
+
+1. **User moves away from trigger**
+
+   ```
+   ScHoverCardTrigger detects mouseleave
+   → Schedules hide after closeDelay (300ms)
+   → Calls provider.hide()
+   ```
+
+2. **Provider hides (but overlay stays)**
+
+   ```typescript
+   hide() {
+     this.open.set(false);
+     // overlayOpen stays true! (critical for animation)
+   }
+   ```
+
+3. **Close animation plays**
+
+   ```typescript
+   // In ScHoverCard:
+   effect(() => {
+     const isOpen = this.hoverCardProvider.open();
+     this.state.set(isOpen ? 'open' : 'closed'); // Sets to 'closed'
+   });
+
+   // state = 'closed' → Triggers exit animation:
+   // - data-[state=closed]:animate-out
+   // - data-[state=closed]:fade-out-0
+   // - data-[state=closed]:zoom-out-95
+   ```
+
+4. **Animation completes → DOM cleanup**
+
+   ```typescript
+   onAnimationEnd(event: AnimationEvent) {
+     if (this.state() === 'closed' &&
+         event.target === this.elementRef.nativeElement) {
+       this.animationComplete.emit();
+       this.hoverCardProvider.onAnimationComplete(); // ← Cleanup
+     }
+   }
+
+   // In provider:
+   onAnimationComplete() {
+     this.overlayOpen.set(false); // NOW remove from DOM
+   }
+   ```
+
+5. **Overlay removes content**
+   ```
+   overlayOpen = false → CDK removes content from DOM
+   ```
+
+## Timeline Diagram
+
+```
+User action: hover away
+│
+├─ t=0ms:    provider.hide()
+│            ├─ open = false
+│            └─ overlayOpen = true (stays mounted)
+│
+├─ t=0ms:    state = 'closed' (triggers animation)
+│
+├─ t=0-100ms: Animation plays
+│             ├─ fade-out-0
+│             ├─ zoom-out-95
+│             └─ Content still visible!
+│
+├─ t=100ms:  onAnimationEnd fires
+│            └─ provider.onAnimationComplete()
+│               └─ overlayOpen = false
+│
+└─ t=100ms:  CDK removes content from DOM
+```
+
+## Animation Classes
+
+Entry animations (applied when `state = 'open'`):
+
+```css
+animate-in fade-in-0 zoom-in-95 duration-100
+```
+
+Exit animations (applied when `state = 'closed'` via data attributes):
+
+```css
+data-[state=closed]:animate-out
+data-[state=closed]:fade-out-0
+data-[state=closed]:zoom-out-95
+```
+
+Directional slides (based on `data-side` attribute):
+
+```css
+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
+```
+
+## Positioning System
+
+The portal supports 12 position combinations:
+
+**Sides:** `top` | `right` | `bottom` | `left`
+**Alignments:** `start` | `center` | `end`
+
+Each combination maps to a `ConnectedPosition` with:
+
+- Origin anchor points (where to attach to trigger)
+- Overlay anchor points (where to attach overlay)
+- Offsets (4px spacing)
+
+Example:
+
+```typescript
+'bottom-center': {
+  originX: 'center',    // Center of trigger
+  originY: 'bottom',    // Bottom edge of trigger
+  overlayX: 'center',   // Center of overlay
+  overlayY: 'top',      // Top edge of overlay
+  offsetY: 4,           // 4px gap
+}
+```
+
+## Key Design Patterns
+
+### 1. Provider Pattern
+
+The provider component manages shared state and configuration that child components can inject.
+
+### 2. Signal-based Reactivity
+
+All state is managed through Angular signals for fine-grained reactivity.
+
+### 3. Effect-based Synchronization
+
+Effects automatically sync derived state (like animation state from open state).
+
+### 4. Delayed Cleanup Pattern
+
+Separating logical state from physical DOM state enables animations to complete before cleanup.
+
+### 5. Composable Architecture
+
+Each component has a single responsibility and can be composed together for flexible usage.
+
+## Comparison to Tooltip
+
+Both components share the same animation architecture:
+
+| Aspect               | Tooltip                      | Hover Card                         |
+| -------------------- | ---------------------------- | ---------------------------------- |
+| **Manager**          | `TooltipManager` service     | `ScHoverCardProvider` component    |
+| **Logical State**    | Internal to manager          | `provider.open` signal             |
+| **Physical State**   | `overlayRef` lifecycle       | `provider.overlayOpen` signal      |
+| **Animation Timing** | `animationComplete` output   | `animationComplete` output         |
+| **Cleanup Trigger**  | Manager subscribes to output | Provider's `onAnimationComplete()` |
+| **Architecture**     | Service + Component          | Composable components              |
+
+The hover card uses a more modular component-based approach, while the tooltip uses a centralized service pattern.
+
+## Usage Example
+
+```typescript
+<div sc-hover-card-provider side="bottom" align="center">
+  <button sc-hover-card-trigger>
+    Hover me
+  </button>
+
+  <div sc-hover-card-portal>
+    <div sc-hover-card>
+      This is the hover card content!
+    </div>
+  </div>
+</div>
+```
+
+## Future Considerations
+
+- Add arrow/pointer support
+- Support collision detection and auto-repositioning
+- Add focus trap for accessibility
+- Support controlled mode (external state management)
+- Add animation duration configuration