@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/tooltip/tooltip-manager.ts

@@ -0,0 +1,194 @@
+import { ConnectedPosition, Overlay, OverlayRef } from '@angular/cdk/overlay';
+import { ComponentPortal } from '@angular/cdk/portal';
+import { DOCUMENT } from '@angular/common';
+import {
+  ComponentRef,
+  DestroyRef,
+  ElementRef,
+  inject,
+  Injectable,
+  Injector,
+  OutputRefSubscription,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { fromEvent } from 'rxjs';
+import { filter } from 'rxjs/operators';
+import { ScTooltip, SC_TOOLTIP_DATA } from './tooltip';
+
+export type ScTooltipPosition = 'top' | 'right' | 'bottom' | 'left';
+
+const positionMap: Record<ScTooltipPosition, ConnectedPosition[]> = {
+  top: [
+    {
+      originX: 'center',
+      originY: 'top',
+      overlayX: 'center',
+      overlayY: 'bottom',
+      offsetY: -8,
+    },
+    {
+      originX: 'center',
+      originY: 'bottom',
+      overlayX: 'center',
+      overlayY: 'top',
+      offsetY: 8,
+    },
+  ],
+  bottom: [
+    {
+      originX: 'center',
+      originY: 'bottom',
+      overlayX: 'center',
+      overlayY: 'top',
+      offsetY: 8,
+    },
+    {
+      originX: 'center',
+      originY: 'top',
+      overlayX: 'center',
+      overlayY: 'bottom',
+      offsetY: -8,
+    },
+  ],
+  left: [
+    {
+      originX: 'start',
+      originY: 'center',
+      overlayX: 'end',
+      overlayY: 'center',
+      offsetX: -8,
+    },
+    {
+      originX: 'end',
+      originY: 'center',
+      overlayX: 'start',
+      overlayY: 'center',
+      offsetX: 8,
+    },
+  ],
+  right: [
+    {
+      originX: 'end',
+      originY: 'center',
+      overlayX: 'start',
+      overlayY: 'center',
+      offsetX: 8,
+    },
+    {
+      originX: 'start',
+      originY: 'center',
+      overlayX: 'end',
+      overlayY: 'center',
+      offsetX: -8,
+    },
+  ],
+};
+
+export interface ScTooltipConfig {
+  content: string;
+  position: ScTooltipPosition;
+  tooltipClass: string;
+}
+
+@Injectable({ providedIn: 'root' })
+export class ScTooltipManager {
+  private readonly overlay = inject(Overlay);
+  private readonly injector = inject(Injector);
+  private readonly document = inject(DOCUMENT);
+  private readonly destroyRef = inject(DestroyRef);
+
+  private overlayRef: OverlayRef | null = null;
+  private tooltipRef: ComponentRef<ScTooltip> | null = null;
+  private currentTooltipId: string | null = null;
+  private animationSubscription: OutputRefSubscription | null = null;
+
+  constructor() {
+    this.setupEscapeListener();
+  }
+
+  private setupEscapeListener(): void {
+    fromEvent<KeyboardEvent>(this.document, 'keydown')
+      .pipe(
+        filter((event) => event.key === 'Escape'),
+        takeUntilDestroyed(this.destroyRef),
+      )
+      .subscribe(() => this.hide());
+  }
+
+  show(
+    elementRef: ElementRef,
+    config: ScTooltipConfig,
+    tooltipId: string,
+  ): void {
+    // Close any existing tooltip first (singleton behavior)
+    if (this.overlayRef) {
+      this.hide();
+    }
+
+    this.currentTooltipId = tooltipId;
+
+    const positionStrategy = this.overlay
+      .position()
+      .flexibleConnectedTo(elementRef)
+      .withPositions(positionMap[config.position])
+      .withPush(true);
+
+    this.overlayRef = this.overlay.create({
+      positionStrategy,
+      scrollStrategy: this.overlay.scrollStrategies.reposition(),
+      hasBackdrop: false,
+    });
+
+    const tooltipInjector = Injector.create({
+      providers: [
+        {
+          provide: SC_TOOLTIP_DATA,
+          useValue: {
+            content: config.content,
+            tooltipClass: config.tooltipClass,
+            tooltipId,
+          },
+        },
+      ],
+      parent: this.injector,
+    });
+
+    const portal = new ComponentPortal(ScTooltip, null, tooltipInjector);
+
+    this.tooltipRef = this.overlayRef.attach(portal);
+
+    // Subscribe to animation completion
+    this.animationSubscription =
+      this.tooltipRef.instance.animationComplete.subscribe(() => {
+        this.disposeTooltip();
+      });
+  }
+
+  hide(): void {
+    if (!this.tooltipRef) {
+      return;
+    }
+
+    // Trigger close animation (will dispose via animationComplete)
+    this.tooltipRef.instance.close();
+  }
+
+  private disposeTooltip(): void {
+    if (this.animationSubscription) {
+      this.animationSubscription.unsubscribe();
+      this.animationSubscription = null;
+    }
+
+    if (this.overlayRef) {
+      this.overlayRef.dispose();
+      this.overlayRef = null;
+    }
+
+    this.tooltipRef = null;
+    this.currentTooltipId = null;
+  }
+
+  isTooltipVisible(tooltipId: string): boolean {
+    return this.currentTooltipId === tooltipId;
+  }
+}

package/src/lib/components/tooltip/tooltip-trigger.ts

@@ -0,0 +1,148 @@
+import {
+  DestroyRef,
+  Directive,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import { _IdGenerator } from '@angular/cdk/a11y';
+import { ScTooltipManager, ScTooltipPosition } from './tooltip-manager';
+
+@Directive({
+  selector: '[scTooltipTrigger]',
+  host: {
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+    '[attr.aria-describedby]': 'ariaDescribedBy()',
+  },
+})
+export class ScTooltipTrigger {
+  private readonly tooltipManager = inject(ScTooltipManager);
+  private readonly elementRef = inject(ElementRef);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly idGenerator = inject(_IdGenerator);
+
+  /** The tooltip text content */
+  readonly content = input.required<string>({ alias: 'scTooltipTrigger' });
+
+  /** Position of the tooltip relative to the trigger element */
+  readonly position = input<ScTooltipPosition>('top', {
+    alias: 'tooltipPosition',
+  });
+
+  /** Delay before showing the tooltip in milliseconds */
+  readonly showDelay = input<number>(200, { alias: 'tooltipDelay' });
+
+  /** Delay before hiding the tooltip in milliseconds */
+  readonly hideDelay = input<number>(0, { alias: 'tooltipHideDelay' });
+
+  /** Whether the tooltip is disabled */
+  readonly disabled = input<boolean>(false, { alias: 'tooltipDisabled' });
+
+  /** Custom CSS class for the tooltip */
+  readonly tooltipClass = input<string>('', { alias: 'tooltipClass' });
+
+  private readonly tooltipId = this.idGenerator.getId('sc-tooltip-');
+  private showTimeout: ReturnType<typeof setTimeout> | null = null;
+  private hideTimeout: ReturnType<typeof setTimeout> | null = null;
+  private readonly isVisible = signal(false);
+
+  protected readonly ariaDescribedBy = () =>
+    this.isVisible() ? this.tooltipId : null;
+
+  constructor() {
+    // Effect to hide tooltip when content becomes empty
+    effect(() => {
+      if (!this.content() && this.isVisible()) {
+        this.hide();
+      }
+    });
+
+    // Cleanup on destroy
+    this.destroyRef.onDestroy(() => {
+      this.cancelTimers();
+      this.hide();
+    });
+  }
+
+  protected onMouseEnter(): void {
+    this.scheduleShow();
+  }
+
+  protected onMouseLeave(): void {
+    this.scheduleHide();
+  }
+
+  protected onFocus(): void {
+    this.scheduleShow();
+  }
+
+  protected onBlur(): void {
+    this.scheduleHide();
+  }
+
+  private scheduleShow(): void {
+    if (this.disabled() || !this.content()) {
+      return;
+    }
+
+    this.cancelTimers();
+
+    const delay = this.showDelay();
+    if (delay > 0) {
+      this.showTimeout = setTimeout(() => this.show(), delay);
+    } else {
+      this.show();
+    }
+  }
+
+  private scheduleHide(): void {
+    this.cancelTimers();
+
+    const delay = this.hideDelay();
+    if (delay > 0) {
+      this.hideTimeout = setTimeout(() => this.hide(), delay);
+    } else {
+      this.hide();
+    }
+  }
+
+  private show(): void {
+    if (this.disabled() || !this.content()) {
+      return;
+    }
+
+    this.tooltipManager.show(
+      this.elementRef,
+      {
+        content: this.content(),
+        position: this.position(),
+        tooltipClass: this.tooltipClass(),
+      },
+      this.tooltipId,
+    );
+    this.isVisible.set(true);
+  }
+
+  private hide(): void {
+    if (this.tooltipManager.isTooltipVisible(this.tooltipId)) {
+      this.tooltipManager.hide();
+    }
+    this.isVisible.set(false);
+  }
+
+  private cancelTimers(): void {
+    if (this.showTimeout) {
+      clearTimeout(this.showTimeout);
+      this.showTimeout = null;
+    }
+    if (this.hideTimeout) {
+      clearTimeout(this.hideTimeout);
+      this.hideTimeout = null;
+    }
+  }
+}

package/src/lib/components/tooltip/tooltip.ts

@@ -0,0 +1,72 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  InjectionToken,
+  output,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+export interface ScTooltipData {
+  content: string;
+  tooltipClass: string;
+  tooltipId: string;
+}
+
+export const SC_TOOLTIP_DATA = new InjectionToken<ScTooltipData>(
+  'SC_TOOLTIP_DATA',
+);
+
+type ScTooltipState = 'open' | 'closed';
+
+@Component({
+  selector: 'sc-tooltip',
+  template: `
+    {{ data.content }}
+  `,
+  host: {
+    'data-slot': 'tooltip',
+    role: 'tooltip',
+    'aria-live': 'polite',
+    'aria-atomic': 'true',
+    '[id]': 'data.tooltipId',
+    '[class]': 'hostClass()',
+    '[attr.data-state]': 'state()',
+    '(animationend)': 'onAnimationEnd($event)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScTooltip {
+  private readonly elementRef = inject(ElementRef);
+
+  readonly data = inject(SC_TOOLTIP_DATA);
+  readonly state = signal<ScTooltipState>('open');
+  readonly animationComplete = output<void>();
+
+  protected readonly hostClass = computed(() =>
+    cn(
+      'bg-primary text-primary-foreground z-50 rounded-md px-3 py-1.5 text-xs max-w-xs',
+      'animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+      this.data.tooltipClass,
+    ),
+  );
+
+  protected onAnimationEnd(event: AnimationEvent): void {
+    // Only emit when close animation completes
+    if (
+      this.state() === 'closed' &&
+      event.target === this.elementRef.nativeElement
+    ) {
+      this.animationComplete.emit();
+    }
+  }
+
+  close(): void {
+    this.state.set('closed');
+  }
+}

package/src/lib/components/tour-guide/README.md

@@ -0,0 +1,158 @@
+# Tour Guide
+
+Step-by-step UI tour component for user onboarding and feature discovery.
+
+## Usage
+
+```typescript
+import { TourService, TourOptions, ScTourGuide } from './ui/tour-guide';
+
+// Inject the service
+const tourService = inject(TourService);
+
+// Start a tour
+const options: TourOptions = {
+  steps: [
+    {
+      target: '#element-1',
+      title: 'Welcome',
+      content: 'This is the first step of the tour.',
+      placement: 'bottom',
+    },
+    {
+      target: '#element-2',
+      title: 'Settings',
+      content: 'Configure your preferences here.',
+    },
+  ],
+  showProgress: true,
+  showStepNumbers: true,
+};
+
+tourService.start(options);
+```
+
+```html
+<!-- Add the component to your template -->
+<sc-tour-guide (stepChange)="onStepChange($event)" (tourComplete)="onTourComplete()" (tourClosed)="onTourClosed()" />
+```
+
+## API
+
+### TourStep
+
+```typescript
+interface TourStep {
+  target: string; // CSS selector for the target element
+  title: string;
+  content: string;
+  placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+  highlightPadding?: number;
+  disableInteraction?: boolean;
+  beforeShow?: () => void | Promise<void>;
+  afterHide?: () => void | Promise<void>;
+}
+```
+
+### TourOptions
+
+```typescript
+interface TourOptions {
+  steps: TourStep[];
+  overlayOpacity?: number; // Default: 0.5
+  animationDuration?: number; // Default: 300
+  showProgress?: boolean; // Default: true
+  showStepNumbers?: boolean; // Default: true
+  allowClose?: boolean; // Default: true
+  allowKeyboardNavigation?: boolean; // Default: true
+  scrollBehavior?: ScrollBehavior; // Default: 'smooth'
+  scrollPadding?: number; // Default: 100
+}
+```
+
+### TourService
+
+| Method        | Type                      | Description            |
+| ------------- | ------------------------- | ---------------------- |
+| `start`       | `(options: TourOptions)`  | Start a new tour       |
+| `stop`        | `() => void`              | Stop the current tour  |
+| `next`        | `() => void`              | Go to next step        |
+| `previous`    | `() => void`              | Go to previous step    |
+| `goTo`        | `(index: number) => void` | Jump to specific step  |
+| `isActive`    | `Signal<boolean>`         | Whether tour is active |
+| `currentStep` | `Signal<number>`          | Current step index     |
+| `steps`       | `Signal<TourStep[]>`      | All tour steps         |
+| `progress`    | `Signal<number>`          | Progress percentage    |
+
+### ScTourGuide
+
+| Output         | Type     | Description                     |
+| -------------- | -------- | ------------------------------- |
+| `stepChange`   | `number` | Emits when step changes         |
+| `tourComplete` | `void`   | Emits when tour finishes        |
+| `tourClosed`   | `void`   | Emits when tour is closed early |
+
+## Examples
+
+### Basic Tour
+
+```typescript
+tourService.start({
+  steps: [
+    { target: '#dashboard', title: 'Dashboard', content: 'Your main overview.' },
+    { target: '#settings', title: 'Settings', content: 'Configure options.' },
+    { target: '#help', title: 'Help', content: 'Get support.' },
+  ],
+});
+```
+
+### Minimal Tour (No Progress/Numbers)
+
+```typescript
+tourService.start({
+  steps: [...],
+  showProgress: false,
+  showStepNumbers: false,
+  overlayOpacity: 0.7
+});
+```
+
+### Custom Placement
+
+```typescript
+{
+  target: '#sidebar',
+  title: 'Navigation',
+  content: 'Access all sections here.',
+  placement: 'right',
+  highlightPadding: 16
+}
+```
+
+## Keyboard Shortcuts
+
+| Key     | Action             |
+| ------- | ------------------ |
+| `→`     | Next step          |
+| `←`     | Previous step      |
+| `Enter` | Next step / Finish |
+| `Esc`   | Close tour         |
+
+## Features
+
+- SVG mask-based overlay with spotlight cutout
+- Auto-positioning tooltips with smart placement
+- Progress bar and step number indicators
+- Keyboard navigation support
+- Scroll target elements into view
+- Customizable highlight padding
+- Lifecycle hooks for before/after step actions
+- Injectable service for programmatic control
+- Responsive overlay that tracks window resize/scroll
+
+## Accessibility
+
+- ARIA dialog role with modal attribute
+- Keyboard navigable
+- Focus management
+- Screen reader friendly labels

package/src/lib/components/tour-guide/index.ts

@@ -0,0 +1,2 @@
+export { ScTourGuide, TourService } from './tour-guide';
+export type { TourStep, TourOptions } from './tour-guide';