@mks2508/mks-ui 0.2.1 → 0.3.1

package/src/react-ui/primitives/waapi/Morph/techniques/useFLIPClipPath.ts

@@ -0,0 +1,175 @@
+import { useRef, useCallback, useEffect, useState } from 'react';
+import { TIMING, EASINGS } from '../../core/animationConstants';
+import type { IFLIPClipPathOptions, IFLIPClipPathAPI } from '../Morph.types';
+
+const DEFAULT_DURATION = TIMING.FLIP_DURATION;
+const DEFAULT_EASING = EASINGS.EASE_OUT_CUBIC;
+
+/**
+ * Hook for FLIP + clip-path morphing technique.
+ *
+ * Combines:
+ * 1. FLIP for position/size transitions
+ * 2. clip-path for shape morphing
+ * 3. Opacity crossfade for smooth visual transition
+ *
+ * @param options - Duration, easing, and clip-path overrides
+ * @returns API with morph trigger, cancel, and morphing state
+ *
+ * @example
+ * ```tsx
+ * const { isMorphing, morph, cancel } = useFLIPClipPath({ duration: 300 });
+ *
+ * const handleMorph = async () => {
+ *   await morph(fromRef.current, toRef.current);
+ * };
+ * ```
+ */
+export function useFLIPClipPath(options?: IFLIPClipPathOptions): IFLIPClipPathAPI {
+  const [isMorphing, setIsMorphing] = useState(false);
+  const activeAnimationsRef = useRef<Animation[]>([]);
+  const optionsRef = useRef(options);
+
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  const cancel = useCallback(() => {
+    activeAnimationsRef.current.forEach(anim => anim.cancel());
+    activeAnimationsRef.current = [];
+    setIsMorphing(false);
+  }, []);
+
+  const morph = useCallback(async (
+    fromElement: HTMLElement,
+    toElement: HTMLElement
+  ): Promise<void> => {
+    if (isMorphing) {
+      cancel();
+    }
+
+    setIsMorphing(true);
+
+    const duration = optionsRef.current?.duration ?? DEFAULT_DURATION;
+    const easing = optionsRef.current?.easing ?? DEFAULT_EASING;
+
+    const fromRect = fromElement.getBoundingClientRect();
+    const toRect = toElement.getBoundingClientRect();
+
+    const deltaX = fromRect.left - toRect.left;
+    const deltaY = fromRect.top - toRect.top;
+    const scaleX = fromRect.width / toRect.width;
+    const scaleY = fromRect.height / toRect.height;
+
+    const fromBorderRadius = getComputedStyle(fromElement).borderRadius;
+    const toBorderRadius = getComputedStyle(toElement).borderRadius;
+
+    const fromClipPath = optionsRef.current?.clipPathStart ||
+      borderRadiusToInset(fromBorderRadius, fromRect);
+    const toClipPath = optionsRef.current?.clipPathEnd ||
+      borderRadiusToInset(toBorderRadius, toRect);
+
+    const originalFromStyles = {
+      position: fromElement.style.position,
+      opacity: fromElement.style.opacity,
+      pointerEvents: fromElement.style.pointerEvents
+    };
+
+    const originalToStyles = {
+      position: toElement.style.position,
+      opacity: toElement.style.opacity,
+      transform: toElement.style.transform,
+      clipPath: toElement.style.clipPath
+    };
+
+    fromElement.style.position = 'absolute';
+    fromElement.style.pointerEvents = 'none';
+
+    toElement.style.position = 'relative';
+    toElement.style.transform = `translate(${deltaX}px, ${deltaY}px) scale(${scaleX}, ${scaleY})`;
+    toElement.style.clipPath = fromClipPath;
+    toElement.style.opacity = '0';
+
+    const fromFadeOut = fromElement.animate([
+      { opacity: 1 },
+      { opacity: 0 }
+    ], {
+      duration: duration * 0.5,
+      easing,
+      fill: 'forwards'
+    });
+
+    const toFadeIn = toElement.animate([
+      { opacity: 0 },
+      { opacity: 1 }
+    ], {
+      duration: duration * 0.5,
+      delay: duration * 0.25,
+      easing,
+      fill: 'forwards'
+    });
+
+    const toTransform = toElement.animate([
+      {
+        transform: `translate(${deltaX}px, ${deltaY}px) scale(${scaleX}, ${scaleY})`,
+        clipPath: fromClipPath
+      },
+      {
+        transform: 'translate(0, 0) scale(1, 1)',
+        clipPath: toClipPath
+      }
+    ], {
+      duration,
+      easing,
+      fill: 'forwards'
+    });
+
+    activeAnimationsRef.current = [fromFadeOut, toFadeIn, toTransform];
+
+    try {
+      await Promise.all([
+        fromFadeOut.finished,
+        toFadeIn.finished,
+        toTransform.finished
+      ]);
+    } catch {
+      Object.assign(fromElement.style, originalFromStyles);
+      Object.assign(toElement.style, originalToStyles);
+      setIsMorphing(false);
+      return;
+    }
+
+    Object.assign(fromElement.style, originalFromStyles);
+    toElement.style.transform = '';
+    toElement.style.clipPath = '';
+    toElement.style.opacity = '1';
+
+    activeAnimationsRef.current = [];
+    setIsMorphing(false);
+  }, [isMorphing, cancel]);
+
+  useEffect(() => {
+    return () => {
+      cancel();
+    };
+  }, [cancel]);
+
+  return {
+    isMorphing,
+    morph,
+    cancel
+  };
+}
+
+/**
+ * Convert a CSS border-radius value to an inset() clip-path with rounded corners.
+ * @param borderRadius - CSS border-radius string
+ * @param rect - Bounding rect of the element
+ * @returns inset() clip-path string
+ */
+function borderRadiusToInset(borderRadius: string, rect: DOMRect): string {
+  const radius = parseFloat(borderRadius) || 0;
+  const percentX = (radius / rect.width) * 100;
+  const percentY = (radius / rect.height) * 100;
+  return `inset(0 round ${percentX}% ${percentY}%)`;
+}

package/src/react-ui/primitives/waapi/Morph/techniques/useViewTransitions.ts

@@ -0,0 +1,86 @@
+import { useRef, useCallback, useMemo } from 'react';
+import type { IViewTransitionsOptions, IViewTransitionsAPI } from '../Morph.types';
+
+/**
+ * Hook for the View Transitions API.
+ *
+ * Provides a wrapper around the native View Transitions API
+ * with automatic feature detection and fallback handling.
+ *
+ * Browser support:
+ * - Chrome 111+
+ * - Firefox 144+
+ * - Safari latest
+ *
+ * @param options - Optional view transition name and types
+ * @returns View Transitions API with support detection and transition trigger
+ *
+ * @example
+ * ```tsx
+ * const { isSupported, startTransition } = useViewTransitions({ name: 'hero' });
+ *
+ * const handleTransition = async () => {
+ *   await startTransition(() => {
+ *     setActiveImage(nextImage);
+ *   });
+ * };
+ * ```
+ */
+export function useViewTransitions(options?: IViewTransitionsOptions): IViewTransitionsAPI {
+  const optionsRef = useRef(options);
+  const typesRef = useRef<string[]>(options?.types || []);
+
+  const isSupported = useMemo(() => {
+    if (typeof document === 'undefined') return false;
+    return 'startViewTransition' in document;
+  }, []);
+
+  const setTypes = useCallback((types: string[]) => {
+    typesRef.current = types;
+  }, []);
+
+  const startTransition = useCallback(async (
+    callback: () => void | Promise<void>
+  ): Promise<void> => {
+    if (!document.startViewTransition) {
+      await callback();
+      return;
+    }
+
+    const viewTransitionName = optionsRef.current?.name;
+
+    const setupStyles = () => {
+      if (viewTransitionName) {
+        const styleEl = document.createElement('style');
+        styleEl.id = `view-transition-${viewTransitionName}`;
+        styleEl.textContent = `
+          ::view-transition-old(${viewTransitionName}),
+          ::view-transition-new(${viewTransitionName}) {
+            animation-duration: 300ms;
+            animation-timing-function: ease-out;
+          }
+        `;
+        document.head.appendChild(styleEl);
+        return () => {
+          styleEl.remove();
+        };
+      }
+      return () => {};
+    };
+
+    const cleanup = setupStyles();
+
+    try {
+      const transition = document.startViewTransition(callback);
+      await transition.finished;
+    } finally {
+      cleanup();
+    }
+  }, []);
+
+  return {
+    isSupported,
+    startTransition,
+    setTypes
+  };
+}

package/src/react-ui/primitives/waapi/Morph/useMorph.ts

@@ -0,0 +1,100 @@
+import { useCallback, useRef, useEffect } from 'react';
+import { useFLIPClipPath } from './techniques/useFLIPClipPath';
+import { useCSSGridMorph } from './techniques/useCSSGridMorph';
+import { useViewTransitions } from './techniques/useViewTransitions';
+import type { IUseMorphReturn, IUseMorphConfig, MorphTechnique } from './Morph.types';
+
+/**
+ * Unified hook for morphing animations.
+ *
+ * Provides access to multiple morphing techniques:
+ * - FLIP + clip-path (default): Best for element-to-element transitions
+ * - CSS Grid: Best for expand/collapse animations
+ * - View Transitions: Best for page/route transitions (requires browser support)
+ *
+ * Falls back to FLIP + clip-path when View Transitions API is unsupported.
+ *
+ * @param options - Technique selection, timing, and callbacks
+ * @returns Unified morph API with access to individual techniques
+ *
+ * @example
+ * ```tsx
+ * const morph = useMorph({ technique: 'flip-clip-path' });
+ *
+ * // Unified API:
+ * await morph.morph(fromElement, toElement);
+ *
+ * // Or individual techniques:
+ * morph.cssGrid.toggle();
+ * ```
+ */
+export function useMorph(options?: IUseMorphConfig): IUseMorphReturn {
+  const technique: MorphTechnique = options?.technique ?? 'flip-clip-path';
+
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  }, [options]);
+
+  const flipClipPath = useFLIPClipPath({
+    duration: options?.duration,
+    easing: options?.easing
+  });
+
+  const cssGrid = useCSSGridMorph({
+    duration: options?.duration,
+    easing: options?.easing
+  });
+
+  const viewTransitions = useViewTransitions();
+
+  const isMorphing = flipClipPath.isMorphing;
+
+  const morph = useCallback(async (
+    fromElement: HTMLElement,
+    toElement: HTMLElement
+  ): Promise<void> => {
+    optionsRef.current?.onMorphStart?.();
+
+    const currentTechnique = optionsRef.current?.technique ?? 'flip-clip-path';
+
+    switch (currentTechnique) {
+      case 'flip-clip-path':
+        await flipClipPath.morph(fromElement, toElement);
+        break;
+
+      case 'view-transitions':
+        if (viewTransitions.isSupported) {
+          await viewTransitions.startTransition(() => {
+            fromElement.style.opacity = '0';
+            toElement.style.opacity = '1';
+          });
+        } else {
+          // Fallback to FLIP when View Transitions unsupported
+          await flipClipPath.morph(fromElement, toElement);
+        }
+        break;
+
+      case 'css-grid':
+        cssGrid.toggle();
+        break;
+    }
+
+    optionsRef.current?.onMorphEnd?.();
+  }, [flipClipPath, viewTransitions, cssGrid]);
+
+  const cancel = useCallback(() => {
+    flipClipPath.cancel();
+  }, [flipClipPath]);
+
+  return {
+    isMorphing,
+    technique,
+    isViewTransitionsSupported: viewTransitions.isSupported,
+    morph,
+    cancel,
+    flipClipPath,
+    cssGrid,
+    viewTransitions
+  };
+}

package/src/react-ui/primitives/waapi/Reorder/Reorder.types.ts

@@ -0,0 +1,177 @@
+import type { ReactNode, ElementType } from 'react';
+import type {
+  IAnimationOrchestratorAPI,
+  FLIPBehavior,
+  ExitPositionStrategy
+} from '../core/types';
+
+// Re-export core types used by consumers
+export type { FLIPBehavior, ExitPositionStrategy } from '../core/types';
+
+/**
+ * Layout direction for reorder items.
+ *
+ * - `auto`: No layout applied (consumer handles positioning)
+ * - `horizontal`: Flexbox row layout with wrapping
+ * - `inline-horizontal`: Inline-flexbox row layout without wrapping
+ * - `vertical`: Flexbox column layout
+ * - `grid`: CSS Grid with auto-fill columns
+ */
+export type ReorderLayout = 'auto' | 'horizontal' | 'inline-horizontal' | 'vertical' | 'grid';
+
+/**
+ * Stagger configuration for animations.
+ * A single number applies to both enter/exit; an object allows separate values.
+ */
+export type StaggerConfig = number | { enter: number; exit: number };
+
+/**
+ * Duration configuration for animations.
+ * A single number applies to both enter/exit; an object allows separate values.
+ */
+export type DurationConfig = number | { enter: number; exit: number };
+
+/**
+ * Animation state for individual reorder items.
+ */
+export interface IReorderItemState {
+  /** True when the item is currently animating out */
+  isExiting: boolean;
+  /** True when the item is currently animating in */
+  isEntering: boolean;
+}
+
+/**
+ * Props for Reorder container component.
+ * Agnostic primitive for animated list reordering using FLIP technique.
+ */
+export interface IReorderProps {
+  /** Child elements to be animated. Each child should have a unique `key` prop */
+  children: ReactNode;
+  /** Layout arrangement for child elements */
+  layout?: ReorderLayout;
+  /** Stagger delay between item animations */
+  stagger?: StaggerConfig;
+  /** Animation duration in milliseconds */
+  duration?: DurationConfig;
+  /** Additional CSS class name for the container */
+  className?: string;
+  /** FLIP animation behavior strategy */
+  flipBehavior?: FLIPBehavior;
+  /** Strategy for positioning elements during exit animation */
+  exitPositionStrategy?: ExitPositionStrategy;
+  /** Callback fired when an item starts its exit animation */
+  onItemExit?: (id: string) => void;
+  /** Callback fired when an item completes its enter animation */
+  onItemEnter?: (id: string) => void;
+}
+
+/**
+ * Configuration options for useReorder hook.
+ * All timing values are in milliseconds.
+ */
+export interface IUseReorderConfig {
+  /** Duration of enter animation in milliseconds. @default 200 */
+  enterDuration?: number;
+  /** Duration of exit animation in milliseconds. @default 180 */
+  exitDuration?: number;
+  /** Duration of FLIP animation in milliseconds. @default 300 */
+  flipDuration?: number;
+  /** Easing function for enter animation */
+  enterEasing?: string;
+  /** Easing function for exit animation */
+  exitEasing?: string;
+  /** Easing function for FLIP animation */
+  flipEasing?: string;
+  /** FLIP animation behavior strategy. @default 'all' */
+  flipBehavior?: FLIPBehavior;
+  /** Strategy for positioning elements during exit animation. @default 'absolute-fixed' */
+  exitPositionStrategy?: ExitPositionStrategy;
+  /** Callback called when an item's exit animation completes */
+  onComplete?: (id: string) => void;
+}
+
+/**
+ * Return type for useReorder hook.
+ * Extends the full AnimationOrchestratorAPI with semantic aliases.
+ */
+export interface IUseReorderReturn extends IAnimationOrchestratorAPI {
+  /** Start exit animation for an item (alias for startExit) */
+  startItemExit: (id: string) => Promise<void>;
+  /** Start enter animation for an item (alias for startEnter) */
+  startItemEnter: (id: string) => Promise<void>;
+}
+
+/**
+ * Context value passed to Reorder children.
+ * @internal Consumed by ReorderItem component.
+ */
+export interface IReorderContextValue {
+  /** Reorder instance with animation methods */
+  reorder: IUseReorderReturn;
+  /** Current layout setting */
+  layout: ReorderLayout;
+  /** Check if an item is currently exiting */
+  isExiting: (id: string) => boolean;
+  /** Check if an item is currently entering */
+  isEntering: (id: string) => boolean;
+  /** Array of item IDs currently exiting */
+  exitingIds: string[];
+  /** Array of item IDs currently entering */
+  enteringIds: string[];
+}
+
+/**
+ * Configuration for useReorderPresence hook.
+ * An alternative to the Reorder component giving full control
+ * over rendering while handling animation orchestration.
+ */
+export interface IUseReorderPresenceConfig {
+  /** Enable automatic enter animations for new children. @default true */
+  autoAnimate?: boolean;
+  /** Stagger delay between item animations */
+  stagger?: StaggerConfig;
+  /** Duration of enter animation in milliseconds */
+  enterDuration?: number;
+  /** Duration of exit animation in milliseconds */
+  exitDuration?: number;
+  /** Duration of FLIP animation in milliseconds */
+  flipDuration?: number;
+  /** Easing function for enter animation */
+  enterEasing?: string;
+  /** Easing function for exit animation */
+  exitEasing?: string;
+  /** Easing function for FLIP animation */
+  flipEasing?: string;
+  /** FLIP animation behavior strategy */
+  flipBehavior?: FLIPBehavior;
+  /** Strategy for positioning elements during exit animation */
+  exitPositionStrategy?: ExitPositionStrategy;
+  /** Callback fired when an item starts its exit animation */
+  onItemExit?: (id: string) => void;
+  /** Callback fired when an item completes its enter animation */
+  onItemEnter?: (id: string) => void;
+  /** Callback fired when an item's exit animation completes */
+  onAnimationComplete?: (id: string) => void;
+}
+
+/**
+ * Return type for useReorderPresence hook.
+ * Provides rendered children and methods for triggering animations.
+ */
+export interface IUseReorderPresenceReturn {
+  /** Rendered children with animation data attributes applied */
+  presentChildren: ReactNode;
+  /** Trigger exit animation for an item */
+  triggerExit: (id: string) => void;
+  /** Check if an item is currently exiting */
+  isExiting: (id: string) => boolean;
+  /** Check if an item is currently entering */
+  isEntering: (id: string) => boolean;
+  /** Array of item IDs currently exiting */
+  exitingIds: string[];
+  /** Array of item IDs currently entering */
+  enteringIds: string[];
+  /** Underlying reorder instance */
+  reorder: IUseReorderReturn;
+}