@mks2508/mks-ui 0.2.1 → 0.3.1

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

package/src/react-ui/primitives/waapi/Reorder/utils/separatorCoordination.ts

@@ -0,0 +1,104 @@
+/**
+ * Utility functions for separator animation coordination.
+ *
+ * When a token exits, determines which separators should animate:
+ * 1. The exiting token's own separator (if it has one)
+ * 2. If the exiting token is the last visible, the previous token's separator
+ *
+ * @module primitives/waapi/Reorder/utils/separatorCoordination
+ */
+
+/**
+ * Calculate which separator IDs should animate along with an exiting item.
+ *
+ * Logic:
+ * - If the exiting item is NOT the last in the list, animate its own separator
+ * - If the exiting item IS the last in the list, animate the previous item's separator
+ *   (because the previous item will become the new last and shouldn't have a separator)
+ *
+ * @param exitingId - The ID of the item being removed
+ * @param currentKeys - Set of all current (non-exiting) item keys
+ * @param exitingIds - Set of all currently exiting item IDs
+ * @param orderedKeys - Array of keys in render order
+ * @returns Array of separator IDs to animate
+ *
+ * @example
+ * ```ts
+ * // Items: [A, B, C, D] with separators after A, B, C
+ * // Removing C (not last):
+ * calculateSeparatorCoordination('C', {'A','B','D'}, {'C'}, ['A','B','C','D'])
+ * // Returns: ['C'] - animate C's separator
+ *
+ * // Removing D (last item):
+ * calculateSeparatorCoordination('D', {'A','B','C'}, {'D'}, ['A','B','C','D'])
+ * // Returns: ['C'] - animate C's separator (C becomes new last)
+ * ```
+ */
+export function calculateSeparatorCoordination(
+  exitingId: string,
+  currentKeys: Set<string>,
+  exitingIds: Set<string>,
+  orderedKeys: string[]
+): string[] {
+  const additionalSeparators: string[] = [];
+
+  const visibleKeys = orderedKeys.filter(
+    key => currentKeys.has(key) || exitingIds.has(key)
+  );
+
+  const indexInVisible = visibleKeys.indexOf(exitingId);
+  if (indexInVisible === -1) {
+    return additionalSeparators;
+  }
+
+  const isLastVisible = indexInVisible === visibleKeys.length - 1;
+  const isNotLastVisible = indexInVisible < visibleKeys.length - 1;
+
+  if (isNotLastVisible) {
+    additionalSeparators.push(exitingId);
+  }
+
+  if (isLastVisible && indexInVisible > 0) {
+    const previousKey = visibleKeys[indexInVisible - 1];
+    if (previousKey && !exitingIds.has(previousKey)) {
+      additionalSeparators.push(previousKey);
+    }
+  }
+
+  return additionalSeparators;
+}
+
+/**
+ * Determine if a separator should be visible based on position and animation state.
+ *
+ * @param _tokenId - The token ID to check (unused, kept for API compatibility)
+ * @param tokenIndex - Index of the token in the visible list
+ * @param totalVisible - Total number of visible tokens
+ * @param separatorPhase - Current animation phase of the separator
+ * @returns Whether the separator should be rendered
+ */
+export function shouldShowSeparator(
+  _tokenId: string,
+  tokenIndex: number,
+  totalVisible: number,
+  separatorPhase?: 'idle' | 'exit-coordinated' | 'flip-coordinated' | 'completed'
+): boolean {
+  if (tokenIndex >= totalVisible - 1) {
+    return false;
+  }
+
+  if (!separatorPhase) {
+    return true;
+  }
+
+  switch (separatorPhase) {
+    case 'idle':
+    case 'exit-coordinated':
+    case 'flip-coordinated':
+      return true;
+    case 'completed':
+      return false;
+    default:
+      return true;
+  }
+}

package/src/react-ui/primitives/waapi/SlidingNumber/SlidingNumber.styles.ts

@@ -0,0 +1,14 @@
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { StyleSlots } from '@/core/types';
+
+/**
+ * Style slots for SlidingNumber component
+ */
+export type SlidingNumberSlot = 'root';
+
+/**
+ * Base styles for SlidingNumber component
+ */
+export const slidingNumberBaseStyles: StyleSlots<SlidingNumberSlot> = {
+  root: 'waapi-sliding-number',
+};