@mks2508/mks-ui 0.2.0 → 0.3.1

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

@@ -0,0 +1,106 @@
+import type { ReactNode, RefObject } from 'react';
+
+/**
+ * Available morphing techniques.
+ */
+export type MorphTechnique = 'flip-clip-path' | 'css-grid' | 'view-transitions';
+
+// =============================================================================
+// FLIP + clip-path
+// =============================================================================
+
+/** Options for the FLIP + clip-path morphing technique */
+export interface IFLIPClipPathOptions {
+  duration?: number;
+  easing?: string;
+  clipPathStart?: string;
+  clipPathEnd?: string;
+}
+
+/** API returned by useFLIPClipPath */
+export interface IFLIPClipPathAPI {
+  isMorphing: boolean;
+  morph: (fromElement: HTMLElement, toElement: HTMLElement) => Promise<void>;
+  cancel: () => void;
+}
+
+// =============================================================================
+// CSS Grid
+// =============================================================================
+
+/** Options for the CSS Grid expand/collapse technique */
+export interface ICSSGridMorphOptions {
+  duration?: number;
+  easing?: string;
+}
+
+/** API returned by useCSSGridMorph */
+export interface ICSSGridMorphAPI {
+  isExpanded: boolean;
+  expand: () => void;
+  collapse: () => void;
+  toggle: () => void;
+  containerRef: RefObject<HTMLElement | null>;
+}
+
+// =============================================================================
+// View Transitions
+// =============================================================================
+
+/** Options for the View Transitions API wrapper */
+export interface IViewTransitionsOptions {
+  name?: string;
+  types?: string[];
+}
+
+/** API returned by useViewTransitions */
+export interface IViewTransitionsAPI {
+  isSupported: boolean;
+  startTransition: (callback: () => void | Promise<void>) => Promise<void>;
+  setTypes: (types: string[]) => void;
+}
+
+// =============================================================================
+// Unified Morph
+// =============================================================================
+
+/** Configuration for useMorph hook */
+export interface IUseMorphConfig {
+  technique?: MorphTechnique;
+  duration?: number;
+  easing?: string;
+  onMorphStart?: () => void;
+  onMorphEnd?: () => void;
+}
+
+/** Return type for useMorph hook */
+export interface IUseMorphReturn {
+  isMorphing: boolean;
+  technique: MorphTechnique;
+  isViewTransitionsSupported: boolean;
+  morph: (fromElement: HTMLElement, toElement: HTMLElement) => Promise<void>;
+  cancel: () => void;
+  flipClipPath: IFLIPClipPathAPI;
+  cssGrid: ICSSGridMorphAPI;
+  viewTransitions: IViewTransitionsAPI;
+}
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+/** Props for Morph container component */
+export interface IMorphProps {
+  children: ReactNode;
+  technique?: MorphTechnique;
+  duration?: number;
+  easing?: string;
+  className?: string;
+  onMorphStart?: () => void;
+  onMorphEnd?: () => void;
+}
+
+/** Context value for Morph components */
+export interface IMorphContextValue {
+  morph: IUseMorphReturn;
+}

package/src/react-ui/primitives/waapi/Morph/MorphContext.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import React, { createContext, useContext } from 'react';
+import type { IMorphContextValue } from './Morph.types';
+
+const MorphContext = createContext<IMorphContextValue | null>(null);
+
+/**
+ * Hook to access morph context
+ *
+ * @throws Error if used outside of Morph provider
+ */
+export function useMorphContext(): IMorphContextValue {
+  const context = useContext(MorphContext);
+  if (!context) {
+    throw new Error('useMorphContext must be used within a Morph component');
+  }
+  return context;
+}
+
+export { MorphContext };

package/src/react-ui/primitives/waapi/Morph/index.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import React, { useMemo, type ReactNode } from 'react';
+import { MorphContext } from './MorphContext';
+import { useMorph } from './useMorph';
+import type { IMorphProps, IMorphContextValue } from './Morph.types';
+import { cn } from '@/react-ui/lib/utils';
+
+/**
+ * Morph - Container component for morphable elements.
+ *
+ * Provides morphing capabilities to child components through context.
+ * Supports FLIP + clip-path, CSS Grid, and View Transitions techniques.
+ *
+ * @example
+ * ```tsx
+ * <Morph technique="flip-clip-path" duration={300}>
+ *   <button onClick={() => morph(fromRef.current, toRef.current)}>
+ *     Morph
+ *   </button>
+ * </Morph>
+ * ```
+ */
+export function Morph({
+  children,
+  technique = 'flip-clip-path',
+  duration,
+  easing,
+  className = '',
+  onMorphStart,
+  onMorphEnd
+}: IMorphProps): ReactNode {
+  const morph = useMorph({
+    technique,
+    duration,
+    easing,
+    onMorphStart,
+    onMorphEnd
+  });
+
+  const contextValue = useMemo<IMorphContextValue>(() => ({
+    morph
+  }), [morph]);
+
+  return (
+    <MorphContext.Provider value={contextValue}>
+      <div className={cn('morph-container', className)}>
+        {children}
+      </div>
+    </MorphContext.Provider>
+  );
+}
+
+Morph.displayName = 'Morph';
+
+export type { IMorphProps, IMorphContextValue };

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

@@ -0,0 +1,12 @@
+/**
+ * Morph techniques.
+ *
+ * Individual morphing implementations that can be used
+ * standalone or composed through useMorph.
+ *
+ * @module primitives/waapi/Morph/techniques
+ */
+
+export { useFLIPClipPath } from './useFLIPClipPath';
+export { useCSSGridMorph } from './useCSSGridMorph';
+export { useViewTransitions } from './useViewTransitions';

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

@@ -0,0 +1,88 @@
+import { useRef, useCallback, useState } from 'react';
+import { TIMING, EASINGS } from '../../core/animationConstants';
+import type { ICSSGridMorphOptions, ICSSGridMorphAPI } from '../Morph.types';
+
+const DEFAULT_DURATION = TIMING.FLIP_DURATION;
+const DEFAULT_EASING = EASINGS.MATERIAL_STANDARD;
+
+/**
+ * Hook for CSS Grid-based expand/collapse animations.
+ *
+ * Uses the `grid-template-rows: 0fr/1fr` technique for smooth height
+ * animations without needing to know the content height in advance.
+ *
+ * CSS required on container:
+ * ```css
+ * .morph-container {
+ *   display: grid;
+ *   grid-template-rows: 0fr;
+ *   transition: grid-template-rows 300ms ease;
+ * }
+ * .morph-container.expanded {
+ *   grid-template-rows: 1fr;
+ * }
+ * .morph-content {
+ *   overflow: hidden;
+ * }
+ * ```
+ *
+ * @param options - Duration and easing overrides
+ * @returns Grid morph API with expand, collapse, toggle, and container ref
+ *
+ * @example
+ * ```tsx
+ * const { isExpanded, toggle, containerRef } = useCSSGridMorph();
+ *
+ * return (
+ *   <div ref={containerRef} className={isExpanded ? 'expanded' : ''}>
+ *     <div className="morph-content">Collapsible content</div>
+ *   </div>
+ * );
+ * ```
+ */
+export function useCSSGridMorph(options?: ICSSGridMorphOptions): ICSSGridMorphAPI {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const containerRef = useRef<HTMLElement | null>(null);
+  const optionsRef = useRef(options);
+
+  const duration = optionsRef.current?.duration ?? DEFAULT_DURATION;
+  const easing = optionsRef.current?.easing ?? DEFAULT_EASING;
+
+  const applyTransition = useCallback(() => {
+    if (containerRef.current) {
+      containerRef.current.style.transition = `grid-template-rows ${duration}ms ${easing}`;
+    }
+  }, [duration, easing]);
+
+  const expand = useCallback(() => {
+    applyTransition();
+    if (containerRef.current) {
+      containerRef.current.style.gridTemplateRows = '1fr';
+    }
+    setIsExpanded(true);
+  }, [applyTransition]);
+
+  const collapse = useCallback(() => {
+    applyTransition();
+    if (containerRef.current) {
+      containerRef.current.style.gridTemplateRows = '0fr';
+    }
+    setIsExpanded(false);
+  }, [applyTransition]);
+
+  const toggle = useCallback(() => {
+    if (isExpanded) {
+      collapse();
+    } else {
+      expand();
+    }
+  }, [isExpanded, expand, collapse]);
+
+  return {
+    isExpanded,
+    expand,
+    collapse,
+    toggle,
+    containerRef
+  };
+}

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
+  };
+}