@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/spotlight/spotlight.ts

@@ -0,0 +1,367 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  DestroyRef,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  output,
+  signal,
+  viewChild,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+export interface SpotlightOptions {
+  target: string | Element;
+  padding?: number;
+  borderRadius?: number;
+  overlayOpacity?: number;
+  animationDuration?: number;
+  showClose?: boolean;
+  closeOnOverlayClick?: boolean;
+  closeOnEscape?: boolean;
+  scrollIntoView?: boolean;
+  scrollBehavior?: ScrollBehavior;
+}
+
+interface TargetRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+@Component({
+  selector: 'sc-spotlight',
+  template: `
+    @if (isActive()) {
+      <div
+        [class]="containerClass()"
+        (click)="onOverlayClick($event)"
+        (keydown)="onKeydown($event)"
+        tabindex="-1"
+        role="dialog"
+        aria-modal="true"
+        #container
+      >
+        <!-- SVG Overlay with spotlight cutout -->
+        <svg class="absolute inset-0 w-full h-full pointer-events-none">
+          <defs>
+            <mask id="spotlight-mask">
+              <rect x="0" y="0" width="100%" height="100%" fill="white" />
+              @if (targetRect()) {
+                <rect
+                  [attr.x]="targetRect()!.left - padding()"
+                  [attr.y]="targetRect()!.top - padding()"
+                  [attr.width]="targetRect()!.width + padding() * 2"
+                  [attr.height]="targetRect()!.height + padding() * 2"
+                  [attr.rx]="borderRadius()"
+                  fill="black"
+                />
+              }
+            </mask>
+          </defs>
+          <rect
+            x="0"
+            y="0"
+            width="100%"
+            height="100%"
+            [attr.fill]="'rgba(0,0,0,' + overlayOpacity() + ')'"
+            mask="url(#spotlight-mask)"
+            class="transition-opacity"
+            [style.transition-duration.ms]="animationDuration()"
+          />
+        </svg>
+
+        <!-- Spotlight border/glow effect -->
+        @if (targetRect()) {
+          <div
+            class="absolute pointer-events-none transition-all"
+            [class]="highlightClass()"
+            [style.top.px]="targetRect()!.top - padding()"
+            [style.left.px]="targetRect()!.left - padding()"
+            [style.width.px]="targetRect()!.width + padding() * 2"
+            [style.height.px]="targetRect()!.height + padding() * 2"
+            [style.border-radius.px]="borderRadius()"
+            [style.transition-duration.ms]="animationDuration()"
+          >
+            <!-- Pulse animation ring -->
+            <div
+              class="absolute inset-0 rounded-[inherit] animate-ping bg-primary/20"
+              [style.animation-duration]="'1.5s'"
+            ></div>
+            <!-- Solid border -->
+            <div
+              class="absolute inset-0 rounded-[inherit] border-2 border-primary"
+            ></div>
+          </div>
+        }
+
+        <!-- Close button -->
+        @if (showClose()) {
+          <button
+            type="button"
+            (click)="close()"
+            class="absolute top-4 right-4 p-2 rounded-full bg-background/90 hover:bg-background text-foreground shadow-lg z-10"
+            aria-label="Close spotlight"
+          >
+            <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="M18 6 6 18" />
+              <path d="m6 6 12 12" />
+            </svg>
+          </button>
+        }
+
+        <!-- Content slot for tooltip/info -->
+        @if (targetRect()) {
+          <div
+            [class]="contentClass()"
+            [style]="contentStyle()"
+            (click)="$event.stopPropagation()"
+          >
+            <ng-content></ng-content>
+          </div>
+        }
+      </div>
+    }
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    '(window:resize)': 'updateTargetRect()',
+    '(window:scroll)': 'updateTargetRect()',
+  },
+})
+export class ScSpotlight {
+  private readonly destroyRef = inject(DestroyRef);
+
+  // Inputs
+  readonly target = input<string | Element | null>(null);
+  readonly padding = input(8);
+  readonly borderRadius = input(8);
+  readonly overlayOpacity = input(0.75);
+  readonly animationDuration = input(300);
+  readonly showClose = input(true);
+  readonly closeOnOverlayClick = input(true);
+  readonly closeOnEscape = input(true);
+  readonly scrollIntoView = input(true);
+  readonly scrollBehavior = input<ScrollBehavior>('smooth');
+  readonly contentPlacement = input<
+    'top' | 'bottom' | 'left' | 'right' | 'auto'
+  >('auto');
+  readonly class = input<string>('');
+
+  // Outputs
+  readonly opened = output<void>();
+  readonly closed = output<void>();
+
+  // Internal state
+  readonly isActive = signal(false);
+  readonly targetRect = signal<TargetRect | null>(null);
+  private targetElement: Element | null = null;
+  private resizeObserver: ResizeObserver | null = null;
+
+  private readonly container =
+    viewChild<ElementRef<HTMLDivElement>>('container');
+
+  protected readonly containerClass = computed(() =>
+    cn(
+      'fixed inset-0 z-[9999]',
+      'animate-in fade-in-0 duration-200',
+      this.class(),
+    ),
+  );
+
+  protected readonly highlightClass = computed(() =>
+    cn('shadow-[0_0_0_4px_rgba(var(--primary),0.2)]'),
+  );
+
+  protected readonly contentClass = computed(() =>
+    cn(
+      'absolute z-10 max-w-sm p-4 bg-popover text-popover-foreground',
+      'border rounded-lg shadow-lg',
+      'animate-in fade-in-0 zoom-in-95 duration-200',
+    ),
+  );
+
+  protected readonly contentStyle = computed(() => {
+    const rect = this.targetRect();
+    if (!rect) return {};
+
+    const pad = this.padding();
+    const contentWidth = 320;
+    const contentHeight = 150;
+    const margin = 16;
+
+    let placement = this.contentPlacement();
+
+    if (placement === 'auto') {
+      const spaceBelow = window.innerHeight - (rect.top + rect.height + pad);
+      const spaceAbove = rect.top - pad;
+      const spaceRight = window.innerWidth - (rect.left + rect.width + pad);
+      const spaceLeft = rect.left - pad;
+
+      if (spaceBelow >= contentHeight + margin) {
+        placement = 'bottom';
+      } else if (spaceAbove >= contentHeight + margin) {
+        placement = 'top';
+      } else if (spaceRight >= contentWidth + margin) {
+        placement = 'right';
+      } else if (spaceLeft >= contentWidth + margin) {
+        placement = 'left';
+      } else {
+        placement = 'bottom';
+      }
+    }
+
+    let top: number;
+    let left: number;
+
+    switch (placement) {
+      case 'top':
+        top = rect.top - pad - contentHeight - margin;
+        left = rect.left + rect.width / 2 - contentWidth / 2;
+        break;
+      case 'bottom':
+        top = rect.top + rect.height + pad + margin;
+        left = rect.left + rect.width / 2 - contentWidth / 2;
+        break;
+      case 'left':
+        top = rect.top + rect.height / 2 - contentHeight / 2;
+        left = rect.left - pad - contentWidth - margin;
+        break;
+      case 'right':
+        top = rect.top + rect.height / 2 - contentHeight / 2;
+        left = rect.left + rect.width + pad + margin;
+        break;
+      default:
+        top = rect.top + rect.height + pad + margin;
+        left = rect.left + rect.width / 2 - contentWidth / 2;
+    }
+
+    left = Math.max(
+      margin,
+      Math.min(left, window.innerWidth - contentWidth - margin),
+    );
+    top = Math.max(margin, top);
+
+    return {
+      top: `${top}px`,
+      left: `${left}px`,
+      maxWidth: `${contentWidth}px`,
+    };
+  });
+
+  constructor() {
+    effect(() => {
+      const targetInput = this.target();
+      if (targetInput) {
+        this.show(targetInput);
+      } else if (this.isActive()) {
+        this.hide();
+      }
+    });
+
+    this.destroyRef.onDestroy(() => {
+      this.resizeObserver?.disconnect();
+    });
+  }
+
+  show(target: string | Element): void {
+    const element =
+      typeof target === 'string' ? document.querySelector(target) : target;
+
+    if (!element) {
+      console.warn('Spotlight: Target element not found');
+      return;
+    }
+
+    this.targetElement = element;
+    this.isActive.set(true);
+    this.updateTargetRect();
+    this.setupResizeObserver();
+
+    if (this.scrollIntoView()) {
+      element.scrollIntoView({
+        behavior: this.scrollBehavior(),
+        block: 'center',
+      });
+    }
+
+    this.opened.emit();
+
+    // Focus the container for keyboard navigation
+    setTimeout(() => {
+      this.container()?.nativeElement?.focus();
+    });
+  }
+
+  hide(): void {
+    this.isActive.set(false);
+    this.targetElement = null;
+    this.targetRect.set(null);
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+    this.closed.emit();
+  }
+
+  toggle(target: string | Element): void {
+    if (this.isActive()) {
+      this.hide();
+    } else {
+      this.show(target);
+    }
+  }
+
+  updateTargetRect(): void {
+    if (!this.targetElement) {
+      this.targetRect.set(null);
+      return;
+    }
+
+    const rect = this.targetElement.getBoundingClientRect();
+    this.targetRect.set({
+      top: rect.top + window.scrollY,
+      left: rect.left + window.scrollX,
+      width: rect.width,
+      height: rect.height,
+    });
+  }
+
+  private setupResizeObserver(): void {
+    if (!this.targetElement || this.resizeObserver) return;
+
+    this.resizeObserver = new ResizeObserver(() => {
+      this.updateTargetRect();
+    });
+
+    this.resizeObserver.observe(this.targetElement);
+  }
+
+  protected onOverlayClick(event: MouseEvent): void {
+    if (event.target === event.currentTarget && this.closeOnOverlayClick()) {
+      this.close();
+    }
+  }
+
+  protected onKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Escape' && this.closeOnEscape()) {
+      this.close();
+      event.preventDefault();
+    }
+  }
+
+  close(): void {
+    this.hide();
+  }
+}

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

@@ -0,0 +1,319 @@
+# Stat Card
+
+A composable set of directives for displaying statistics and metrics with optional trends, icons, and descriptions.
+
+## Components
+
+- `ScStatCard` - Main container with border, background, and padding
+- `ScStatCardLabel` - Label/title text styling
+- `ScStatCardValue` - Large value/metric display styling
+- `ScStatCardIcon` - Icon container styling
+- `ScStatCardChange` - Trend/change indicator styling with color variants
+- `ScStatCardDescription` - Additional description text styling
+
+## Installation
+
+```typescript
+import { ScStatCard, ScStatCardLabel, ScStatCardValue, ScStatCardIcon, ScStatCardChange, ScStatCardDescription } from '@semantic-components/ui-lab';
+```
+
+## Usage
+
+### Basic Stat Card
+
+```html
+<div sc-stat-card>
+  <div class="space-y-1">
+    <p sc-stat-card-label>Total Revenue</p>
+    <p sc-stat-card-value>$45,231.89</p>
+  </div>
+  <p sc-stat-card-description>Revenue for the current period</p>
+</div>
+```
+
+### With Icon
+
+```html
+<div sc-stat-card>
+  <div class="flex items-start justify-between">
+    <div class="space-y-1">
+      <p sc-stat-card-label>Active Users</p>
+      <p sc-stat-card-value>2,350</p>
+    </div>
+    <div sc-stat-card-icon>
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" />
+        <circle cx="9" cy="7" r="4" />
+        <path d="M22 21v-2a4 4 0 0 0-3-3.87" />
+        <path d="M16 3.13a4 4 0 0 1 0 7.75" />
+      </svg>
+    </div>
+  </div>
+</div>
+```
+
+### With Trend Indicator
+
+```html
+<div sc-stat-card>
+  <div class="space-y-1">
+    <p sc-stat-card-label>Sales</p>
+    <p sc-stat-card-value>12,234</p>
+  </div>
+
+  <div class="mt-3 flex items-center gap-2">
+    <span sc-stat-card-change trend="up">
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="m18 15-6-6-6 6" />
+      </svg>
+      <span>+20.1%</span>
+    </span>
+    <span class="text-xs text-muted-foreground">from last month</span>
+  </div>
+</div>
+```
+
+### Complete Example
+
+```html
+<div sc-stat-card variant="default" size="md">
+  <div class="flex items-start justify-between">
+    <div class="space-y-1">
+      <p sc-stat-card-label size="md">Total Revenue</p>
+      <p sc-stat-card-value size="md">$45,231.89</p>
+    </div>
+    <div sc-stat-card-icon size="md">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M12 2v20M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6" />
+      </svg>
+    </div>
+  </div>
+
+  <div class="mt-3 flex items-center gap-2">
+    <span sc-stat-card-change trend="up">
+      <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="m18 15-6-6-6 6" />
+      </svg>
+      <span>+20.1%</span>
+    </span>
+    <span class="text-xs text-muted-foreground">from last month</span>
+  </div>
+
+  <p sc-stat-card-description class="mt-2">Your revenue increased significantly this month</p>
+</div>
+```
+
+## Variants
+
+### Default (with border)
+
+```html
+<div sc-stat-card variant="default">
+  <!-- content -->
+</div>
+```
+
+### Outline (thick border)
+
+```html
+<div sc-stat-card variant="outline">
+  <!-- content -->
+</div>
+```
+
+### Filled (colored background)
+
+```html
+<div sc-stat-card variant="filled">
+  <!-- content -->
+</div>
+```
+
+## Sizes
+
+### Small
+
+```html
+<div sc-stat-card size="sm">
+  <p sc-stat-card-label size="sm">Label</p>
+  <p sc-stat-card-value size="sm">1,234</p>
+</div>
+```
+
+### Medium (default)
+
+```html
+<div sc-stat-card size="md">
+  <p sc-stat-card-label size="md">Label</p>
+  <p sc-stat-card-value size="md">5,678</p>
+</div>
+```
+
+### Large
+
+```html
+<div sc-stat-card size="lg">
+  <p sc-stat-card-label size="lg">Label</p>
+  <p sc-stat-card-value size="lg">9,012</p>
+</div>
+```
+
+## Trend Colors
+
+The `sc-stat-card-change` directive automatically applies colors based on the `trend` input:
+
+- `trend="up"` - Green text (positive)
+- `trend="down"` - Red text (negative)
+- `trend="neutral"` - Muted text (neutral)
+
+```html
+<span sc-stat-card-change trend="up">
+  <svg><!-- up arrow --></svg>
+  <span>+12.5%</span>
+</span>
+
+<span sc-stat-card-change trend="down">
+  <svg><!-- down arrow --></svg>
+  <span>-5.2%</span>
+</span>
+
+<span sc-stat-card-change trend="neutral">
+  <span>No change</span>
+</span>
+```
+
+## API Reference
+
+### ScStatCard Inputs
+
+| Input     | Type                                 | Default     | Description            |
+| --------- | ------------------------------------ | ----------- | ---------------------- |
+| `variant` | `'default' \| 'outline' \| 'filled'` | `'default'` | Card style variant     |
+| `size`    | `'sm' \| 'md' \| 'lg'`               | `'md'`      | Card padding size      |
+| `class`   | `string`                             | `''`        | Additional CSS classes |
+
+### ScStatCardLabel Inputs
+
+| Input   | Type                   | Default | Description            |
+| ------- | ---------------------- | ------- | ---------------------- |
+| `size`  | `'sm' \| 'md' \| 'lg'` | `'md'`  | Label text size        |
+| `class` | `string`               | `''`    | Additional CSS classes |
+
+### ScStatCardValue Inputs
+
+| Input   | Type                   | Default | Description            |
+| ------- | ---------------------- | ------- | ---------------------- |
+| `size`  | `'sm' \| 'md' \| 'lg'` | `'md'`  | Value text size        |
+| `class` | `string`               | `''`    | Additional CSS classes |
+
+### ScStatCardIcon Inputs
+
+| Input   | Type                   | Default | Description            |
+| ------- | ---------------------- | ------- | ---------------------- |
+| `size`  | `'sm' \| 'md' \| 'lg'` | `'md'`  | Icon container size    |
+| `class` | `string`               | `''`    | Additional CSS classes |
+
+### ScStatCardChange Inputs
+
+| Input   | Type                          | Default     | Description            |
+| ------- | ----------------------------- | ----------- | ---------------------- |
+| `trend` | `'up' \| 'down' \| 'neutral'` | `'neutral'` | Trend direction/color  |
+| `class` | `string`                      | `''`        | Additional CSS classes |
+
+### ScStatCardDescription Inputs
+
+| Input   | Type     | Default | Description            |
+| ------- | -------- | ------- | ---------------------- |
+| `class` | `string` | `''`    | Additional CSS classes |
+
+## Type Definitions
+
+```typescript
+type StatCardTrend = 'up' | 'down' | 'neutral';
+type StatCardVariant = 'default' | 'outline' | 'filled';
+type StatCardSize = 'sm' | 'md' | 'lg';
+```
+
+## Styling Reference
+
+| Component               | Default Styling                                                              |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `ScStatCard`            | `rounded-lg transition-colors` + variant/size classes                        |
+| `ScStatCardLabel`       | `font-medium text-muted-foreground` + size-specific font size                |
+| `ScStatCardValue`       | `font-bold tracking-tight` + size-specific font size                         |
+| `ScStatCardIcon`        | `rounded-md bg-muted p-2 inline-flex items-center justify-center` + SVG size |
+| `ScStatCardChange`      | `inline-flex items-center gap-1 text-xs font-medium` + trend color           |
+| `ScStatCardDescription` | `text-xs text-muted-foreground`                                              |
+
+## Features
+
+- Fully composable - use only what you need
+- Content projection for maximum flexibility
+- Multiple style variants (default, outline, filled)
+- Multiple size options (sm, md, lg)
+- Automatic trend-based coloring
+- Support for custom icons from any library
+- Responsive design
+- Custom class support on all directives
+
+## Accessibility
+
+- Uses semantic HTML structure
+- All directives accept standard HTML attributes
+- Ensure proper heading hierarchy for labels
+- Use appropriate ARIA labels for trend indicators
+- Icons should have descriptive text for screen readers
+
+## Example Layouts
+
+### Grid of Stats
+
+```html
+<div class="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
+  <div sc-stat-card>
+    <p sc-stat-card-label>Total Revenue</p>
+    <p sc-stat-card-value>$45,231.89</p>
+  </div>
+
+  <div sc-stat-card>
+    <p sc-stat-card-label>Active Users</p>
+    <p sc-stat-card-value>2,350</p>
+  </div>
+
+  <div sc-stat-card>
+    <p sc-stat-card-label>Sales</p>
+    <p sc-stat-card-value>12,234</p>
+  </div>
+
+  <div sc-stat-card>
+    <p sc-stat-card-label>Conversions</p>
+    <p sc-stat-card-value>573</p>
+  </div>
+</div>
+```
+
+### Custom Layout
+
+Since all components use content projection, you can create any layout you need:
+
+```html
+<div sc-stat-card>
+  <!-- Custom header with icon on left -->
+  <div class="flex items-center gap-3 mb-4">
+    <div sc-stat-card-icon>
+      <svg><!-- icon --></svg>
+    </div>
+    <p sc-stat-card-label>Revenue</p>
+  </div>
+
+  <!-- Centered value -->
+  <p sc-stat-card-value class="text-center">$45,231.89</p>
+
+  <!-- Bottom trend -->
+  <div class="mt-4 flex justify-center">
+    <span sc-stat-card-change trend="up">
+      <span>↑ 20.1%</span>
+    </span>
+  </div>
+</div>
+```