@ng-cn/core 1.0.10 → 1.0.12

package/src/app/lib/utils/animation/animation.types.ts

@@ -0,0 +1,55 @@
+/**
+ * Animation System Types - Radix-Ready Animation Layer for shadcn-angular
+ * Defines the animation lifecycle states and configuration
+ */
+
+/**
+ * Animation lifecycle states
+ * Mirrors Radix UI's internal state management
+ */
+export type AnimationState = 'closed' | 'entering' | 'open' | 'exiting';
+
+/**
+ * Positional information for directional animations
+ */
+export type AnimationSide = 'top' | 'bottom' | 'left' | 'right';
+export type AnimationAlign = 'start' | 'center' | 'end';
+
+/**
+ * Animation lifecycle configuration
+ */
+export interface AnimationConfig {
+  /** Duration in milliseconds */
+  duration?: number;
+  /** Easing function */
+  easing?: string;
+  /** CSS class to apply during animation */
+  class?: string;
+}
+
+/**
+ * State exposure API - all animated components must expose these attributes
+ */
+export interface AnimatedElementAttributes {
+  /** Current animation lifecycle state */
+  'data-state': AnimationState;
+  /** Positional side (if applicable) */
+  'data-side'?: AnimationSide;
+  /** Alignment (if applicable) */
+  'data-align'?: AnimationAlign;
+  /** Motion phase for directional animations */
+  'data-motion'?: 'from-start' | 'to-end';
+}
+
+/**
+ * Presence component token
+ * Keeps component in DOM until exit animation completes
+ */
+export interface PresenceToken {
+  /** Unique identifier for presence tracking */
+  id: string;
+  /** Current animation state */
+  state: AnimationState;
+  /** Callback when animation completes */
+  onAnimationEnd?: () => void;
+}

package/src/app/lib/utils/animation/animation.utils.ts

@@ -0,0 +1,158 @@
+/**
+ * Animation Utility Functions
+ * Helper functions for managing animation states and CSS classes
+ */
+
+import { signal, Signal } from '@angular/core';
+import type { AnimationAlign, AnimationSide, AnimationState } from './animation.types';
+
+/**
+ * Animation preset names matching shadcn/ui semantics
+ */
+export const ANIMATION_PRESETS = {
+  // Fade animations
+  fadeIn: 'animate-in fade-in-0',
+  fadeOut: 'animate-out fade-out-0',
+
+  // Scale/Zoom animations
+  scaleIn: 'animate-in zoom-in-95',
+  scaleOut: 'animate-out zoom-out-95',
+
+  // Slide animations
+  slideInFromTop: 'animate-in slide-in-from-top-2',
+  slideOutToTop: 'animate-out slide-out-to-top-2',
+  slideInFromRight: 'animate-in slide-in-from-right-2',
+  slideOutToRight: 'animate-out slide-out-to-right-2',
+  slideInFromBottom: 'animate-in slide-in-from-bottom-2',
+  slideOutToBottom: 'animate-out slide-out-to-bottom-2',
+  slideInFromLeft: 'animate-in slide-in-from-left-2',
+  slideOutToLeft: 'animate-out slide-out-to-left-2',
+
+  // Combined animations (common patterns)
+  fadeScale: 'animate-in fade-in-0 zoom-in-95',
+  fadeScaleOut: 'animate-out fade-out-0 zoom-out-95',
+} as const;
+
+/**
+ * Create animation state signal
+ * Manages the 4-state animation lifecycle
+ */
+export function createAnimationState(
+  initialState: AnimationState = 'closed'
+): Signal<AnimationState> {
+  return signal<AnimationState>(initialState);
+}
+
+/**
+ * Determine animation CSS classes based on state and direction
+ */
+export function getAnimationClasses(
+  state: AnimationState,
+  direction?: AnimationSide,
+  animate: boolean = true
+): string {
+  if (!animate) return '';
+
+  const baseClasses = ['duration-200'];
+
+  switch (state) {
+    case 'closed':
+      return [...baseClasses, 'animate-out fade-out-0'].join(' ');
+
+    case 'entering':
+      return [...baseClasses, 'animate-in fade-in-0'].join(' ');
+
+    case 'open':
+      return [...baseClasses, 'animate-in fade-in-0'].join(' ');
+
+    case 'exiting':
+      return [...baseClasses, 'animate-out fade-out-0'].join(' ');
+
+    default:
+      return '';
+  }
+}
+
+/**
+ * Get slide animation classes based on direction
+ */
+export function getSlideAnimationClasses(
+  state: AnimationState,
+  direction: AnimationSide
+): string {
+  const baseClasses = ['duration-200'];
+
+  const directionMap: Record<AnimationState, Record<AnimationSide, string>> = {
+    entering: {
+      top: 'animate-in slide-in-from-top-2',
+      bottom: 'animate-in slide-in-from-bottom-2',
+      left: 'animate-in slide-in-from-left-2',
+      right: 'animate-in slide-in-from-right-2',
+    },
+    open: {
+      top: 'animate-in slide-in-from-top-2',
+      bottom: 'animate-in slide-in-from-bottom-2',
+      left: 'animate-in slide-in-from-left-2',
+      right: 'animate-in slide-in-from-right-2',
+    },
+    exiting: {
+      top: 'animate-out slide-out-to-top-2',
+      bottom: 'animate-out slide-out-to-bottom-2',
+      left: 'animate-out slide-out-to-left-2',
+      right: 'animate-out slide-out-to-right-2',
+    },
+    closed: {
+      top: 'animate-out slide-out-to-top-2',
+      bottom: 'animate-out slide-out-to-bottom-2',
+      left: 'animate-out slide-out-to-left-2',
+      right: 'animate-out slide-out-to-right-2',
+    },
+  };
+
+  return [...baseClasses, directionMap[state]?.[direction] || ''].join(' ');
+}
+
+/**
+ * Build data attributes for animation state exposure
+ */
+export function buildAnimationAttributes(
+  state: AnimationState,
+  side?: AnimationSide,
+  align?: AnimationAlign
+): Record<string, string | undefined> {
+  return {
+    'data-state': state,
+    'data-side': side,
+    'data-align': align,
+  };
+}
+
+/**
+ * Wait for animation to complete
+ * Useful for coordinating multiple animations
+ */
+export async function waitForAnimation(element: HTMLElement): Promise<void> {
+  return new Promise((resolve) => {
+    const handleAnimationEnd = () => {
+      element.removeEventListener('animationend', handleAnimationEnd);
+      resolve();
+    };
+
+    element.addEventListener('animationend', handleAnimationEnd);
+
+    // Timeout fallback (300ms for safety)
+    setTimeout(() => {
+      element.removeEventListener('animationend', handleAnimationEnd);
+      resolve();
+    }, 300);
+  });
+}
+
+/**
+ * Check if animations are enabled (respects prefers-reduced-motion)
+ */
+export function areAnimationsEnabled(): boolean {
+  if (typeof window === 'undefined') return true;
+
+  return !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

package/src/app/lib/utils/animation/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Animation System Index
+ * Exports all animation utilities and services
+ */
+
+export type { AnimatedElementAttributes, AnimationAlign, AnimationConfig, AnimationSide, AnimationState, PresenceToken } from './animation.types';
+
+export { AnimatedDirective } from './animated.directive';
+export { AnimationTokensService } from './animation-tokens.service';
+export {
+    ANIMATION_PRESETS, areAnimationsEnabled, buildAnimationAttributes, createAnimationState,
+    getAnimationClasses,
+    getSlideAnimationClasses, waitForAnimation
+} from './animation.utils';
+export { Presence, type PresenceState } from './presence.component';
+export { PresenceIfDirective, PresenceService } from './presence.directive';
+

package/src/app/lib/utils/animation/presence.component.ts

@@ -0,0 +1,168 @@
+/**
+ * Presence Component
+ * Angular version of Radix UI's Presence primitive
+ * Keeps DOM elements present until exit animations complete
+ *
+ * This is the critical component for proper exit animations in:
+ * - Dialog
+ * - Popover
+ * - Dropdown Menu
+ * - Tooltip
+ * - Sheet
+ * - Toast
+ */
+
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  input,
+  OnDestroy,
+  signal
+} from '@angular/core';
+
+/**
+ * Presence state
+ */
+export type PresenceState = 'mounted' | 'unmountSuspended' | 'unmounted';
+
+/**
+ * Presence Component
+ * Wraps content and manages its presence in the DOM based on animation state
+ *
+ * Usage:
+ * <Presence [present]="isOpen()">
+ *   <div class="animate-in data-[state=closed]:animate-out">
+ *     Content here
+ *   </div>
+ * </Presence>
+ */
+@Component({
+  selector: 'Presence',
+  template: `
+    @if (shouldRender()) {
+      <ng-content />
+    }
+  `,
+  host: {
+    class: 'contents',
+    '[attr.data-presence-state]': 'presenceState()',
+    '(animationend)': 'handleAnimationEnd($event)',
+    '(animationcancel)': 'handleAnimationEnd($event)',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Presence implements OnDestroy {
+  /** Whether the content should be present */
+  readonly present = input.required<boolean>();
+
+  /** Force presence (bypass animation waiting) */
+  readonly forceMount = input<boolean>(false);
+
+  /** Animation duration in ms (fallback if CSS animation doesn't fire) */
+  readonly exitDuration = input<number>(200);
+
+  /** Internal presence state */
+  private readonly state = signal<PresenceState>('unmounted');
+
+  /** Previous present value for change detection */
+  private prevPresent = false;
+
+  /** Timeout for fallback animation end */
+  private exitTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /** Whether to render content */
+  readonly shouldRender = computed(() => {
+    if (this.forceMount()) return true;
+
+    const currentState = this.state();
+    return currentState === 'mounted' || currentState === 'unmountSuspended';
+  });
+
+  /** Current presence state (exposed for debugging) */
+  readonly presenceState = computed(() => this.state());
+
+  constructor() {
+    // React to present changes
+    effect(() => {
+      const isPresent = this.present();
+
+      if (isPresent !== this.prevPresent) {
+        this.handlePresenceChange(isPresent);
+        this.prevPresent = isPresent;
+      }
+    });
+  }
+
+  ngOnDestroy(): void {
+    this.clearExitTimeout();
+  }
+
+  /**
+   * Handle presence change
+   */
+  private handlePresenceChange(isPresent: boolean): void {
+    this.clearExitTimeout();
+
+    if (isPresent) {
+      // Mount immediately
+      this.state.set('mounted');
+    } else {
+      // Start exit animation
+      this.state.set('unmountSuspended');
+
+      // Set fallback timeout in case animationend doesn't fire
+      this.exitTimeout = setTimeout(() => {
+        this.state.set('unmounted');
+      }, this.exitDuration());
+    }
+  }
+
+  /**
+   * Handle animation end
+   */
+  protected handleAnimationEnd(event: AnimationEvent): void {
+    // Only handle if we're in exit state
+    if (this.state() === 'unmountSuspended') {
+      // Check if this is an exit animation (based on animation name or state)
+      const target = event.target as HTMLElement;
+      const animationName = event.animationName;
+
+      // Exit animations typically contain 'exit' or 'out' in the name
+      if (
+        animationName.includes('exit') ||
+        animationName.includes('out') ||
+        animationName.includes('leave')
+      ) {
+        this.clearExitTimeout();
+        this.state.set('unmounted');
+      }
+    }
+  }
+
+  /**
+   * Clear exit timeout
+   */
+  private clearExitTimeout(): void {
+    if (this.exitTimeout) {
+      clearTimeout(this.exitTimeout);
+      this.exitTimeout = null;
+    }
+  }
+
+  /**
+   * Force unmount (skip animation)
+   */
+  forceUnmount(): void {
+    this.clearExitTimeout();
+    this.state.set('unmounted');
+  }
+
+  /**
+   * Check if currently animating exit
+   */
+  isExiting(): boolean {
+    return this.state() === 'unmountSuspended';
+  }
+}

package/src/app/lib/utils/animation/presence.directive.ts

@@ -0,0 +1,169 @@
+/**
+ * Presence Directive & Service
+ * Keeps DOM elements in the tree until animations complete
+ * Critical for exit animations in modals, tooltips, popovers, etc.
+ */
+
+import {
+  DestroyRef,
+  Directive,
+  EmbeddedViewRef,
+  Injectable,
+  Input,
+  OnDestroy,
+  OnInit,
+  TemplateRef,
+  ViewContainerRef,
+  WritableSignal,
+  inject,
+  signal
+} from '@angular/core';
+
+/**
+ * Presence state for tracking animation lifecycle
+ */
+interface PresenceState {
+  isPresent: boolean;
+  isAnimating: boolean;
+}
+
+/**
+ * Manages presence state for animated components
+ * Ensures DOM elements stay in tree during exit animations
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class PresenceService {
+  private presenceMap = new Map<string, WritableSignal<PresenceState>>();
+
+  /**
+   * Register a presence element
+   */
+  register(id: string, initialState: boolean = false): WritableSignal<PresenceState> {
+    if (!this.presenceMap.has(id)) {
+      this.presenceMap.set(
+        id,
+        signal<PresenceState>({
+          isPresent: initialState,
+          isAnimating: false,
+        })
+      );
+    }
+    return this.presenceMap.get(id)!;
+  }
+
+  /**
+   * Unregister a presence element
+   */
+  unregister(id: string): void {
+    this.presenceMap.delete(id);
+  }
+
+  /**
+   * Update presence state
+   */
+  setState(id: string, state: Partial<PresenceState>): void {
+    const current = this.presenceMap.get(id);
+    if (current) {
+      current.update((prev) => ({ ...prev, ...state }));
+    }
+  }
+
+  /**
+   * Get current presence state
+   */
+  getState(id: string): PresenceState | undefined {
+    return this.presenceMap.get(id)?.();
+  }
+}
+
+/**
+ * Presence Directive
+ * Usage: <div *presenceIf="isVisible; duration: 300">Content</div>
+ *
+ * Keeps the element in DOM during exit animations, then removes it
+ * Properly handles animation completion before unmounting
+ */
+@Directive({
+  selector: '[presenceIf]',
+})
+export class PresenceIfDirective<T> implements OnInit, OnDestroy {
+  private readonly viewContainer = inject(ViewContainerRef);
+  private readonly presenceService = inject(PresenceService);
+  private readonly destroyRef = inject(DestroyRef);
+
+  @Input() presenceIfTemplate?: TemplateRef<T>;
+  @Input() set presenceIf(show: boolean) {
+    this.handlePresenceChange(show);
+  }
+
+  @Input() presenceDuration: number = 200;
+
+  private viewRef: EmbeddedViewRef<T> | null = null;
+  private presenceId = `presence-${Math.random().toString(36).substr(2, 9)}`;
+  private isVisible = signal(false);
+
+  ngOnInit(): void {
+    this.presenceService.register(this.presenceId, false);
+
+    // Clean up on destroy
+    this.destroyRef.onDestroy(() => {
+      this.presenceService.unregister(this.presenceId);
+    });
+  }
+
+  ngOnDestroy(): void {
+    this.presenceService.unregister(this.presenceId);
+    if (this.viewRef) {
+      this.viewRef.destroy();
+      this.viewRef = null;
+    }
+  }
+
+  private handlePresenceChange(show: boolean): void {
+    if (show) {
+      this.showElement();
+    } else {
+      this.hideElement();
+    }
+  }
+
+  private showElement(): void {
+    if (!this.viewRef && this.presenceIfTemplate) {
+      this.viewRef = this.viewContainer.createEmbeddedView(this.presenceIfTemplate);
+      this.presenceService.setState(this.presenceId, {
+        isPresent: true,
+        isAnimating: true,
+      });
+
+      // Mark animation as complete after duration
+      setTimeout(() => {
+        this.presenceService.setState(this.presenceId, {
+          isAnimating: false,
+        });
+      }, this.presenceDuration);
+    }
+
+    this.isVisible.set(true);
+  }
+
+  private hideElement(): void {
+    this.isVisible.set(false);
+    this.presenceService.setState(this.presenceId, {
+      isAnimating: true,
+    });
+
+    // Remove from DOM after animation completes
+    setTimeout(() => {
+      if (this.viewRef) {
+        this.viewRef.destroy();
+        this.viewRef = null;
+      }
+      this.presenceService.setState(this.presenceId, {
+        isPresent: false,
+        isAnimating: false,
+      });
+    }, this.presenceDuration);
+  }
+}

package/src/app/lib/utils/cn.ts

@@ -0,0 +1,15 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Utility function to merge Tailwind CSS classes with proper conflict resolution.
+ * Combines clsx for conditional classes with tailwind-merge for deduplication.
+ *
+ * @example
+ * cn('px-4 py-2', 'px-6') // => 'py-2 px-6'
+ * cn('bg-red-500', condition && 'bg-blue-500') // conditional classes
+ * cn('text-sm', ['font-bold', 'text-gray-500']) // array support
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/app/lib/utils/index.ts

@@ -0,0 +1,11 @@
+// Utility exports
+export { cn } from './cn';
+
+// Accessibility utilities
+export * from './accessibility';
+
+// Animation utilities
+export * from './animation';
+
+// Positioning utilities (collision detection)
+export * from './positioning';