@mks2508/mks-ui 0.5.4 → 0.5.8

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

@@ -1,177 +0,0 @@
-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

@@ -1,260 +0,0 @@
-"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

@@ -1,47 +0,0 @@
-'use client';
-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

@@ -1,209 +0,0 @@
-'use client';
-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
-  };
-}