@mks2508/mks-ui 0.2.0 → 0.3.1

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

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

@@ -0,0 +1,260 @@
+"use client";
+
+import React, { useMemo, useState, useEffect, useRef, useCallback, useImperativeHandle, Children, isValidElement, cloneElement, forwardRef, type CSSProperties, type ReactNode, type ReactElement } from 'react';
+import { useReorder } from './useReorder';
+import type { IReorderProps, ReorderLayout, DurationConfig } from './Reorder.types';
+import { cn } from '@/react-ui/lib/utils';
+
+function getDuration(config: DurationConfig | undefined, type: 'enter' | 'exit'): number | undefined {
+  if (config === undefined) return undefined;
+  if (typeof config === 'number') return config;
+  return config[type];
+}
+
+const layoutStyles: Record<ReorderLayout, CSSProperties> = {
+  auto: { position: 'relative' },
+  horizontal: { display: 'flex', flexDirection: 'row', flexWrap: 'wrap', alignItems: 'center', position: 'relative' },
+  'inline-horizontal': { display: 'inline-flex', flexDirection: 'row', flexWrap: 'nowrap', alignItems: 'center', position: 'relative' },
+  vertical: { display: 'flex', flexDirection: 'column', position: 'relative' },
+  grid: { display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(100px, 1fr))', gap: '8px', position: 'relative' }
+};
+
+interface IChildRecord {
+  key: string;
+  element: ReactElement;
+}
+
+/**
+ * Reorder - Agnostic container for reorderable items with FLIP animations
+ *
+ * @example
+ * ```tsx
+ * <Reorder
+ *   layout="horizontal"
+ *   onItemExit={(id) => handleRemove(id)}
+ * >
+ *   {items.map(item => (
+ *     <div key={item.id}>{item.name}</div>
+ *   ))}
+ * </Reorder>
+ * ```
+ */
+const ReorderRoot = forwardRef<{
+  startItemExit: (id: string) => Promise<void>;
+  startItemEnter: (id: string) => Promise<void>;
+  isAnimating: (id?: string) => boolean;
+}, IReorderProps>(({
+  children,
+  stagger,
+  duration,
+  layout = 'auto',
+  className = '',
+  flipBehavior,
+  exitPositionStrategy,
+  onItemExit,
+  onItemEnter
+}, ref) => {
+  // Completion handler - removes from displayChildren
+  const handleAnimationComplete = useCallback((id: string) => {
+    setDisplayChildren(prev => prev.filter(child => child.key !== id));
+  }, []);
+
+  // Reorder hook — delegates to full FLIP orchestrator
+  const reorder = useReorder({
+    enterDuration: getDuration(duration, 'enter'),
+    exitDuration: getDuration(duration, 'exit'),
+    flipBehavior,
+    exitPositionStrategy,
+    onComplete: handleAnimationComplete
+  });
+
+  // Expose reorder methods via ref
+  useImperativeHandle(ref, () => ({
+    startItemExit: reorder.startItemExit,
+    startItemEnter: reorder.startItemEnter,
+    isAnimating: reorder.isAnimating
+  }), [reorder.startItemExit, reorder.startItemEnter, reorder.isAnimating]);
+
+  // Store reorder functions in refs for stable callbacks
+  const startExitRef = useRef(reorder.startItemExit);
+  const startEnterRef = useRef(reorder.startItemEnter);
+  useEffect(() => {
+    startExitRef.current = reorder.startItemExit;
+    startEnterRef.current = reorder.startItemEnter;
+  }, [reorder.startItemExit, reorder.startItemEnter]);
+
+  // Extract current children as records
+  const currentChildren = useMemo<IChildRecord[]>(() => {
+    const records: IChildRecord[] = [];
+    Children.forEach(children, child => {
+      if (isValidElement(child) && child.key != null) {
+        records.push({
+          key: String(child.key),
+          element: child as ReactElement
+        });
+      }
+    });
+    return records;
+  }, [children]);
+
+  // Internal display state
+  const [displayChildren, setDisplayChildren] = useState<IChildRecord[]>(currentChildren);
+
+  // Track which keys are currently exiting
+  const exitingKeysRef = useRef<Set<string>>(new Set());
+
+  // Calculate stagger delay
+  const getStaggerDelay = useCallback((index: number, type: 'enter' | 'exit'): number => {
+    if (!stagger) return 0;
+    if (typeof stagger === 'number') return stagger * index;
+    return (stagger[type] ?? 0) * index;
+  }, [stagger]);
+
+  // Detect changes and sync displayChildren
+  useEffect(() => {
+    const currentKeys = new Set(currentChildren.map(c => c.key));
+    const displayKeys = new Set(displayChildren.map(c => c.key));
+
+    // Removals: in display but not in current, and not already exiting
+    const removed = displayChildren.filter(c =>
+      !currentKeys.has(c.key) && !exitingKeysRef.current.has(c.key)
+    );
+
+    // Additions: in current but not in display
+    const added = currentChildren.filter(c => !displayKeys.has(c.key));
+
+    // No structural changes
+    if (removed.length === 0 && added.length === 0) {
+      const hasUpdates = currentChildren.some((c) => {
+        const displayChild = displayChildren.find(dc => dc.key === c.key);
+        return displayChild && displayChild.element !== c.element;
+      });
+
+      if (hasUpdates) {
+        setDisplayChildren(prev => prev.map(dc => {
+          if (exitingKeysRef.current.has(dc.key)) return dc;
+          const currentChild = currentChildren.find(c => c.key === dc.key);
+          return currentChild ?? dc;
+        }));
+      }
+      return;
+    }
+
+    // Handle removals - start exit animations
+    removed.forEach((child, index) => {
+      const delay = getStaggerDelay(index, 'exit');
+      exitingKeysRef.current.add(child.key);
+
+      const processExit = () => {
+        onItemExit?.(child.key);
+
+        // Start exit animation
+        startExitRef.current(child.key).finally(() => {
+          exitingKeysRef.current.delete(child.key);
+        });
+      };
+
+      if (delay > 0) {
+        setTimeout(processExit, delay);
+      } else {
+        processExit();
+      }
+    });
+
+    // Handle additions - merge into display
+    if (added.length > 0) {
+      const exitingChildren = displayChildren.filter(c => !currentKeys.has(c.key));
+      let result = [...currentChildren];
+
+      exitingChildren.forEach(ec => {
+        const oldIdx = displayChildren.findIndex(c => c.key === ec.key);
+        if (oldIdx !== -1 && oldIdx <= result.length) {
+          result.splice(oldIdx, 0, ec);
+        }
+      });
+
+      setDisplayChildren(result);
+
+      added.forEach((child, index) => {
+        const delay = getStaggerDelay(index, 'enter');
+
+        const processEnter = () => {
+          onItemEnter?.(child.key);
+        };
+
+        if (delay > 0) {
+          setTimeout(processEnter, delay);
+        } else {
+          processEnter();
+        }
+      });
+    }
+  }, [currentChildren, displayChildren, getStaggerDelay, onItemExit, onItemEnter]);
+
+  // Build present children with data attributes and ref registration
+  const presentChildren = useMemo<ReactNode[]>(() => {
+    const currentKeys = new Set(currentChildren.map(c => c.key));
+
+    return displayChildren.map(({ key, element }) => {
+      const isNewElement = currentKeys.has(key);
+      const isExiting = exitingKeysRef.current.has(key);
+
+      const elementWithRef = cloneElement(element as ReactElement<any>, {
+        ref: (el: HTMLElement | null) => {
+          if (el) {
+            reorder.registerElement(key, el);
+
+            const currentState = el.dataset.reorderState;
+
+            if (!currentState && isNewElement && !isExiting) {
+              el.dataset.reorderState = 'entering';
+              startEnterRef.current(key);
+            }
+          } else {
+            reorder.registerElement(key, null);
+          }
+
+          // Preserve original ref
+          const originalRef = (element as any).ref;
+          if (typeof originalRef === 'function') {
+            originalRef(el);
+          } else if (originalRef && typeof originalRef === 'object') {
+            (originalRef as React.MutableRefObject<HTMLElement | null>).current = el;
+          }
+        },
+        'data-reorder-id': key
+      });
+
+      return elementWithRef;
+    });
+  }, [displayChildren, currentChildren, reorder.registerElement]);
+
+  const layoutClass = layout !== 'auto' ? `reorder--${layout}` : '';
+
+  return (
+    <div
+      className={cn('waapi-reorder-container', 'reorder', layoutClass, className)}
+      style={layoutStyles[layout]}
+    >
+      {presentChildren}
+    </div>
+  );
+});
+
+ReorderRoot.displayName = 'Reorder';
+
+export { ReorderRoot as Reorder };
+export type {
+  IReorderProps,
+  ReorderLayout,
+  DurationConfig,
+  StaggerConfig,
+  IUseReorderReturn,
+  IUseReorderConfig,
+  IReorderItemState,
+  IReorderContextValue,
+  IUseReorderPresenceConfig,
+  IUseReorderPresenceReturn,
+  FLIPBehavior,
+  ExitPositionStrategy,
+} from './Reorder.types';

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

@@ -0,0 +1,46 @@
+import { useAnimationOrchestrator } from '../core/useAnimationOrchestrator';
+import type { IUseReorderReturn, IUseReorderConfig } from './Reorder.types';
+
+/**
+ * Hook for managing reorderable lists with FLIP animations.
+ *
+ * Architecture: Thin wrapper around useAnimationOrchestrator.
+ * Delegates all animation logic to the orchestrator and provides
+ * a stable API surface for the Reorder component.
+ *
+ * @param config - Optional reorder configuration (timing, easing, callbacks)
+ * @returns Reorder API with register, exit, enter, and query methods
+ *
+ * @example
+ * ```tsx
+ * const reorder = useReorder({
+ *   onComplete: (id) => removeFromList(id)
+ * });
+ *
+ * <div ref={el => reorder.registerElement('item-1', el)}>
+ *   Item 1
+ * </div>
+ *
+ * await reorder.startItemExit('item-1');
+ * ```
+ */
+export function useReorder(config?: IUseReorderConfig): IUseReorderReturn {
+  const orchestrator = useAnimationOrchestrator({
+    enterDuration: config?.enterDuration,
+    exitDuration: config?.exitDuration,
+    flipDuration: config?.flipDuration,
+    enterEasing: config?.enterEasing,
+    exitEasing: config?.exitEasing,
+    flipEasing: config?.flipEasing,
+    flipBehavior: config?.flipBehavior,
+    exitPositionStrategy: config?.exitPositionStrategy,
+    onExitComplete: config?.onComplete
+  });
+
+  return {
+    ...orchestrator,
+    registerElement: orchestrator.registerElement,
+    startItemExit: orchestrator.startExit,
+    startItemEnter: orchestrator.startEnter
+  };
+}

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

@@ -0,0 +1,208 @@
+import {
+  useRef,
+  useCallback,
+  useMemo,
+  useLayoutEffect,
+  useEffect,
+  Children,
+  isValidElement,
+  cloneElement,
+  type ReactNode,
+  type ReactElement
+} from 'react';
+import { useReorder } from './useReorder';
+import type {
+  IUseReorderPresenceConfig,
+  IUseReorderPresenceReturn
+} from './Reorder.types';
+
+/**
+ * Hook for managing presence animations in reorderable lists.
+ *
+ * Follows the pattern where elements stay in DOM until animation completes.
+ * Consumer must keep items in their state until onAnimationComplete fires.
+ * No "ghost" cloning — animations run on actual DOM elements.
+ *
+ * @param children - React children with unique keys
+ * @param config - Presence animation configuration
+ * @returns Presence API with presentChildren, triggerExit, and state queries
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = useState(INITIAL_ITEMS);
+ *
+ * const { presentChildren, triggerExit } = useReorderPresence(
+ *   items.map(item => <div key={item.id}>{item.name}</div>),
+ *   {
+ *     onAnimationComplete: (id) => {
+ *       setItems(prev => prev.filter(item => item.id !== id));
+ *     }
+ *   }
+ * );
+ *
+ * const handleDelete = (id: string) => {
+ *   triggerExit(id);
+ * };
+ * ```
+ */
+export function useReorderPresence(
+  children: ReactNode,
+  config: IUseReorderPresenceConfig = {}
+): IUseReorderPresenceReturn {
+  const {
+    autoAnimate = true,
+    stagger,
+    enterDuration,
+    exitDuration,
+    flipDuration,
+    enterEasing,
+    exitEasing,
+    flipEasing
+  } = config;
+
+  const configRef = useRef(config);
+  useEffect(() => {
+    configRef.current = config;
+  }, [config]);
+
+  // Track animating IDs via REF (not state) — like AnimatedTokens
+  const exitingIdsRef = useRef<Set<string>>(new Set());
+  const enteringIdsRef = useRef<Set<string>>(new Set());
+
+  // Track previous children keys for change detection
+  const prevKeysRef = useRef<Set<string>>(new Set());
+
+  const getStaggerDelay = useCallback((index: number, type: 'enter' | 'exit'): number => {
+    if (!stagger) return 0;
+    if (typeof stagger === 'number') return stagger * index;
+    return (stagger[type] ?? 0) * index;
+  }, [stagger]);
+
+  const handleAnimationComplete = useCallback((id: string) => {
+    exitingIdsRef.current.delete(id);
+    configRef.current.onAnimationComplete?.(id);
+  }, []);
+
+  const reorder = useReorder({
+    enterDuration,
+    exitDuration,
+    flipDuration,
+    enterEasing,
+    exitEasing,
+    flipEasing,
+    onComplete: handleAnimationComplete
+  });
+
+  const currentKeys = useMemo(() => {
+    const keys = new Set<string>();
+    Children.forEach(children, child => {
+      if (isValidElement(child) && child.key != null) {
+        keys.add(String(child.key));
+      }
+    });
+    return keys;
+  }, [children]);
+
+  // Detect and process changes
+  useLayoutEffect(() => {
+    const prevKeys = prevKeysRef.current;
+
+    // Detect additions (in current but not in prev)
+    const added: string[] = [];
+    currentKeys.forEach(key => {
+      if (!prevKeys.has(key) && !enteringIdsRef.current.has(key)) {
+        added.push(key);
+      }
+    });
+
+    // Process additions
+    if (added.length > 0) {
+      added.forEach((key, index) => {
+        const delay = getStaggerDelay(index, 'enter');
+
+        const processEnter = () => {
+          enteringIdsRef.current.add(key);
+          configRef.current.onItemEnter?.(key);
+
+          requestAnimationFrame(() => {
+            reorder.startItemEnter(key).then(() => {
+              enteringIdsRef.current.delete(key);
+            });
+          });
+        };
+
+        if (delay > 0) {
+          setTimeout(processEnter, delay);
+        } else {
+          processEnter();
+        }
+      });
+    }
+
+    prevKeysRef.current = new Set(currentKeys);
+  }, [currentKeys, autoAnimate, reorder, getStaggerDelay]);
+
+  // Manual exit trigger
+  const triggerExit = useCallback((id: string) => {
+    if (exitingIdsRef.current.has(id)) return;
+    if (!reorder.registry.has(id)) return;
+
+    exitingIdsRef.current.add(id);
+    configRef.current.onItemExit?.(id);
+
+    reorder.startItemExit(id);
+  }, [reorder]);
+
+  const isExiting = useCallback((id: string): boolean => {
+    return exitingIdsRef.current.has(id);
+  }, []);
+
+  const isEntering = useCallback((id: string): boolean => {
+    return enteringIdsRef.current.has(id);
+  }, []);
+
+  const getExitingIds = useCallback((): string[] => {
+    return Array.from(exitingIdsRef.current);
+  }, []);
+
+  const getEnteringIds = useCallback((): string[] => {
+    return Array.from(enteringIdsRef.current);
+  }, []);
+
+  // presentChildren — children as-is with data attribute for exiting
+  const presentChildren = useMemo(() => {
+    const result: ReactNode[] = [];
+
+    Children.forEach(children, child => {
+      if (!isValidElement(child)) {
+        result.push(child);
+        return;
+      }
+
+      const key = child.key != null ? String(child.key) : null;
+      const isCurrentlyExiting = key != null && exitingIdsRef.current.has(key);
+
+      if (isCurrentlyExiting) {
+        result.push(
+          cloneElement(child as ReactElement<{ 'data-reorder-state'?: string }>, {
+            'data-reorder-state': 'exiting'
+          })
+        );
+      } else {
+        result.push(child);
+      }
+    });
+
+    return result;
+  }, [children]);
+
+  return {
+    presentChildren,
+    triggerExit,
+    isExiting,
+    isEntering,
+    exitingIds: getExitingIds(),
+    enteringIds: getEnteringIds(),
+    reorder
+  };
+}