@mks2508/mks-ui 0.2.0 → 0.3.1

package/dist/react-ui/primitives/waapi/core/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Core types for headless animation primitives.
+ * Based on WAAPI (Web Animations API) patterns.
+ *
+ * @module primitives/waapi/core/types
+ */
+/** Calculated delta between two captured positions of an element */
+export interface IFLIPDelta {
+    id: string;
+    deltaX: number;
+    deltaY: number;
+    deltaWidth: number;
+    deltaHeight: number;
+    isSignificant: boolean;
+}
+/** Timing configuration for a single animation */
+export interface IAnimationTiming {
+    duration: number;
+    delay?: number;
+    easing: string;
+    fill?: FillMode;
+}
+/** Captured position rectangle */
+export interface IPositionRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** API for tracking DOM elements by ID */
+export interface IElementRegistryAPI {
+    register: (id: string, el: HTMLElement | null) => void;
+    unregister: (id: string) => void;
+    get: (id: string) => HTMLElement | undefined;
+    getAll: () => Map<string, HTMLElement>;
+    has: (id: string) => boolean;
+    clear: () => void;
+    size: number;
+}
+/** Callbacks for element registry lifecycle events */
+export interface IElementRegistryCallbacks {
+    onRegister?: (id: string, el: HTMLElement) => void;
+    onUnregister?: (id: string) => void;
+}
+/** API for capturing element positions and calculating FLIP deltas */
+export interface IPositionCaptureAPI {
+    capture: (excludeIds?: Set<string>) => Map<string, DOMRect>;
+    getPosition: (id: string) => DOMRect | undefined;
+    calculateDeltas: (before: Map<string, DOMRect>, after: Map<string, DOMRect>) => Map<string, IFLIPDelta>;
+    getLastCapture: () => Map<string, DOMRect>;
+    clear: () => void;
+}
+/** Options for position capture behavior */
+export interface IPositionCaptureOptions {
+    minDeltaPx?: number;
+}
+/** Options for individual FLIP animations */
+export interface IFLIPAnimationOptions {
+    duration?: number;
+    easing?: string;
+    onStart?: (id: string) => void;
+    onComplete?: (id: string) => void;
+}
+/** API for executing FLIP animations */
+export interface IFLIPAnimationAPI {
+    animate: (element: HTMLElement, delta: IFLIPDelta, options?: IFLIPAnimationOptions) => Animation;
+    animateAll: (elements: Map<string, HTMLElement>, deltas: Map<string, IFLIPDelta>, options?: IFLIPAnimationOptions) => Promise<void>;
+    cancel: (id: string) => void;
+    cancelAll: () => void;
+    isAnimating: (id?: string) => boolean;
+}
+/** Options for exit animations */
+export interface IExitOptions {
+    duration?: number;
+    easing?: string;
+    collapseWidth?: boolean;
+    additionalIds?: string[];
+    onComplete?: () => void;
+}
+/** Options for enter animations */
+export interface IEnterOptions {
+    duration?: number;
+    easing?: string;
+    stagger?: number;
+    onComplete?: () => void;
+}
+/**
+ * Controls which elements animate when an item exits.
+ * - `'all'`: All remaining elements animate to fill the gap (default)
+ * - `'siblings-after'`: Only elements after the exiting one animate
+ * - `'none'`: No FLIP animation, item exits in-place
+ */
+export type FLIPBehavior = 'all' | 'siblings-after' | 'none';
+/**
+ * Controls how the exiting element is positioned during exit animation.
+ * - `'absolute-fixed'`: Position absolute with fixed coordinates (default)
+ * - `'in-place'`: Stay in flow, no position change
+ * - `'custom'`: Consumer handles positioning via CSS/callbacks
+ */
+export type ExitPositionStrategy = 'absolute-fixed' | 'in-place' | 'custom';
+/** Configuration for the animation orchestrator */
+export interface IAnimationOrchestratorConfig {
+    exitDuration?: number;
+    flipDuration?: number;
+    enterDuration?: number;
+    exitEasing?: string;
+    flipEasing?: string;
+    enterEasing?: string;
+    flipBehavior?: FLIPBehavior;
+    exitPositionStrategy?: ExitPositionStrategy;
+    minDeltaPx?: number;
+    onExitComplete?: (id: string) => void;
+    onEnterComplete?: (id: string) => void;
+}
+/** Full API surface of the animation orchestrator */
+export interface IAnimationOrchestratorAPI {
+    registry: IElementRegistryAPI;
+    positions: IPositionCaptureAPI;
+    flip: IFLIPAnimationAPI;
+    registerElement: (id: string, el: HTMLElement | null) => void;
+    startExit: (id: string, options?: IExitOptions) => Promise<void>;
+    startEnter: (id: string, options?: IEnterOptions) => Promise<void>;
+    isAnimating: (id?: string) => boolean;
+    cancelAnimation: (id: string) => void;
+    cancelAllAnimations: () => void;
+    capturePositions: (excludeIds?: Set<string>) => Map<string, DOMRect>;
+}
+/** Internal state tracked by the orchestrator */
+export interface IOrchestratorState {
+    animatingIds: Set<string>;
+    positions: Map<string, DOMRect>;
+    activeAnimations: Map<string, Animation[]>;
+}
+/** Phase of an animation lifecycle */
+export type AnimationPhase = 'idle' | 'exit' | 'flip' | 'enter' | 'completed';
+/** Animation event emitted during orchestration */
+export interface IAnimationEvent {
+    id: string;
+    phase: AnimationPhase;
+    timestamp: number;
+    duration?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/react-ui/primitives/waapi/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/primitives/waapi/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACvD,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAC7C,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sDAAsD;AACtD,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IACnD,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAMD,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5D,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,SAAS,CAAC;IACjD,eAAe,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxG,cAAc,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,SAAS,CAAC;IACjG,UAAU,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpI,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,WAAW,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AAMD,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAMD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAM5E,mDAAmD;AACnD,MAAM,WAAW,4BAA4B;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAE5C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,qDAAqD;AACrD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,IAAI,EAAE,iBAAiB,CAAC;IAExB,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9D,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,WAAW,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,mBAAmB,EAAE,MAAM,IAAI,CAAC;IAChC,gBAAgB,EAAE,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtE;AAMD,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;CAC5C;AAMD,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;AAE9E,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/react-ui/primitives/waapi/core/useAnimationOrchestrator.d.ts

@@ -0,0 +1,32 @@
+import type { IAnimationOrchestratorAPI, IAnimationOrchestratorConfig } from './types';
+/**
+ * Main animation orchestrator hook.
+ * Composes useElementRegistry, usePositionCapture, and useFLIPAnimation
+ * into a full FLIP exit/enter pipeline.
+ *
+ * Handles the full exit animation sequence:
+ * 1. Capture positions of remaining elements (FIRST)
+ * 2. Apply position:absolute to exiting element
+ * 3. Force synchronous reflow
+ * 4. Capture AFTER positions (LAST)
+ * 5. Calculate INVERT deltas and PLAY FLIP animations
+ * 6. Run exit animation (per-token stagger or whole-element)
+ * 7. Wait for all animations to complete
+ * 8. Cleanup and notify completion
+ *
+ * @param config - Optional orchestrator configuration
+ * @returns Full orchestrator API
+ *
+ * @example
+ * ```tsx
+ * const orchestrator = useAnimationOrchestrator({
+ *   onExitComplete: (id) => removeFromList(id)
+ * });
+ *
+ * <div ref={el => orchestrator.registerElement('item-1', el)} />
+ *
+ * await orchestrator.startExit('item-1');
+ * ```
+ */
+export declare function useAnimationOrchestrator(config?: IAnimationOrchestratorConfig): IAnimationOrchestratorAPI;
+//# sourceMappingURL=useAnimationOrchestrator.d.ts.map

package/dist/react-ui/primitives/waapi/core/useAnimationOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnimationOrchestrator.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/primitives/waapi/core/useAnimationOrchestrator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAI7B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,CAAC,EAAE,4BAA4B,GACpC,yBAAyB,CAgY3B"}

package/dist/react-ui/primitives/waapi/core/useAnimationOrchestrator.js

@@ -0,0 +1,322 @@
+import { EASINGS, EFFECTS, TIMING, TRANSFORMS } from "./animationConstants.js";
+import { useElementRegistry } from "./useElementRegistry.js";
+import { usePositionCapture } from "./usePositionCapture.js";
+import { useFLIPAnimation } from "./useFLIPAnimation.js";
+import { useCallback, useEffect, useRef } from "react";
+
+//#region src/react-ui/primitives/waapi/core/useAnimationOrchestrator.ts
+/**
+* Main animation orchestrator hook.
+* Composes useElementRegistry, usePositionCapture, and useFLIPAnimation
+* into a full FLIP exit/enter pipeline.
+*
+* Handles the full exit animation sequence:
+* 1. Capture positions of remaining elements (FIRST)
+* 2. Apply position:absolute to exiting element
+* 3. Force synchronous reflow
+* 4. Capture AFTER positions (LAST)
+* 5. Calculate INVERT deltas and PLAY FLIP animations
+* 6. Run exit animation (per-token stagger or whole-element)
+* 7. Wait for all animations to complete
+* 8. Cleanup and notify completion
+*
+* @param config - Optional orchestrator configuration
+* @returns Full orchestrator API
+*
+* @example
+* ```tsx
+* const orchestrator = useAnimationOrchestrator({
+*   onExitComplete: (id) => removeFromList(id)
+* });
+*
+* <div ref={el => orchestrator.registerElement('item-1', el)} />
+*
+* await orchestrator.startExit('item-1');
+* ```
+*/
+function useAnimationOrchestrator(config) {
+	const configRef = useRef(config);
+	useEffect(() => {
+		configRef.current = config;
+	}, [config]);
+	const stateRef = useRef({
+		animatingIds: /* @__PURE__ */ new Set(),
+		positions: /* @__PURE__ */ new Map(),
+		activeAnimations: /* @__PURE__ */ new Map()
+	});
+	const registry = useElementRegistry();
+	const positions = usePositionCapture(registry.getAll, { minDeltaPx: config?.minDeltaPx ?? TIMING.MIN_DELTA_PX });
+	const flip = useFLIPAnimation();
+	const exitDuration = config?.exitDuration ?? TIMING.EXIT_DURATION;
+	const flipDuration = config?.flipDuration ?? TIMING.FLIP_DURATION;
+	const exitEasing = config?.exitEasing ?? EASINGS.EASE_IN_CUBIC;
+	const cancelAnimation = useCallback((id) => {
+		const animations = stateRef.current.activeAnimations.get(id);
+		if (animations) {
+			animations.forEach((anim) => anim.cancel());
+			stateRef.current.activeAnimations.delete(id);
+		}
+		stateRef.current.animatingIds.delete(id);
+		flip.cancel(id);
+	}, [flip]);
+	const cancelAllAnimations = useCallback(() => {
+		stateRef.current.activeAnimations.forEach((animations) => {
+			animations.forEach((anim) => anim.cancel());
+		});
+		stateRef.current.activeAnimations.clear();
+		stateRef.current.animatingIds.clear();
+		flip.cancelAll();
+	}, [flip]);
+	const flipBehavior = config?.flipBehavior ?? "all";
+	const exitPositionStrategy = config?.exitPositionStrategy ?? "absolute-fixed";
+	/**
+	* Full FLIP exit implementation.
+	* Based on research from Paul Lewis (aerotwist.com), react-flip-move,
+	* and Framer Motion popLayout mode.
+	*/
+	const startExit = useCallback(async (id, options) => {
+		const el = registry.get(id);
+		if (!el || stateRef.current.animatingIds.has(id)) return;
+		stateRef.current.animatingIds.add(id);
+		const duration = options?.duration ?? exitDuration;
+		const easing = options?.easing ?? exitEasing;
+		const allElements = registry.getAll();
+		const beforePositions = /* @__PURE__ */ new Map();
+		const exitingRect = el.getBoundingClientRect();
+		beforePositions.set(id, exitingRect);
+		allElements.forEach((element, elemId) => {
+			if (elemId !== id) {
+				const rect = element.getBoundingClientRect();
+				if (rect.width > 0 && rect.height > 0) beforePositions.set(elemId, rect);
+			}
+		});
+		const parent = el.parentElement;
+		el.dataset.reorderState = "exiting";
+		if (exitPositionStrategy === "absolute-fixed") el.dataset.exitPosition = "absolute";
+		const parentRectBefore = parent?.getBoundingClientRect() || {
+			left: 0,
+			top: 0
+		};
+		const absoluteLeft = exitingRect.left - parentRectBefore.left;
+		const absoluteTop = exitingRect.top - parentRectBefore.top;
+		if (exitPositionStrategy === "absolute-fixed") {
+			el.style.position = "absolute";
+			el.style.left = `${absoluteLeft}px`;
+			el.style.top = `${absoluteTop}px`;
+			el.style.width = `${exitingRect.width}px`;
+			el.style.height = `${exitingRect.height}px`;
+			el.style.margin = "0";
+		}
+		const parentRectAfter = parent?.getBoundingClientRect() || {
+			left: 0,
+			top: 0
+		};
+		const parentDeltaX = parentRectAfter.left - parentRectBefore.left;
+		const parentDeltaY = parentRectAfter.top - parentRectBefore.top;
+		if (Math.abs(parentDeltaX) > .5 || Math.abs(parentDeltaY) > .5) el.style.transform = `translate(${-parentDeltaX}px, ${-parentDeltaY}px)`;
+		const afterPositions = /* @__PURE__ */ new Map();
+		allElements.forEach((element, elemId) => {
+			if (elemId !== id) {
+				const rect = element.getBoundingClientRect();
+				if (rect.width > 0 && rect.height > 0) afterPositions.set(elemId, rect);
+			}
+		});
+		const flipAnimations = [];
+		if (flipBehavior !== "none") {
+			let siblingsToAnimate = [];
+			if (flipBehavior === "all") siblingsToAnimate = [...afterPositions.keys()];
+			else if (flipBehavior === "siblings-after") {
+				const elementsWithIds = Array.from(allElements.entries());
+				elementsWithIds.sort((a, b) => {
+					const posA = a[1];
+					const posB = b[1];
+					return posA.compareDocumentPosition(posB) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+				});
+				const sortedKeys = elementsWithIds.map(([k]) => k);
+				const exitingIndex = sortedKeys.indexOf(id);
+				if (exitingIndex !== -1) siblingsToAnimate = sortedKeys.slice(exitingIndex + 1).filter((k) => afterPositions.has(k));
+			}
+			siblingsToAnimate.forEach((siblingId) => {
+				const before = beforePositions.get(siblingId);
+				const after = afterPositions.get(siblingId);
+				if (!before || !after) return;
+				const deltaX = before.left - after.left;
+				const deltaY = before.top - after.top;
+				if (Math.abs(deltaX) > 1 || Math.abs(deltaY) > 1) {
+					const siblingEl = allElements.get(siblingId);
+					if (siblingEl) {
+						siblingEl.dataset.reorderState = "flipping";
+						siblingEl.style.transform = `translate(${deltaX}px, ${deltaY}px)`;
+						const anim = siblingEl.animate([{ transform: `translate(${deltaX}px, ${deltaY}px)` }, { transform: "none" }], {
+							duration: flipDuration,
+							easing: EASINGS.MATERIAL_DECELERATE,
+							fill: "forwards"
+						});
+						flipAnimations.push(anim);
+						anim.finished.then(() => {
+							siblingEl.style.transform = "";
+							siblingEl.dataset.reorderState = "idle";
+						}).catch(() => {
+							siblingEl.style.transform = "";
+							siblingEl.dataset.reorderState = "idle";
+						});
+					}
+				}
+			});
+		}
+		const exitAnimations = [];
+		const tokens = el.querySelectorAll(".waapi-sliding-text-token");
+		if (tokens.length > 0) tokens.forEach((token, index) => {
+			const delay = index * TIMING.EXIT_STAGGER;
+			const anim = token.animate([{
+				opacity: 1,
+				transform: "translateY(0) scale(1)",
+				filter: "blur(0px)"
+			}, {
+				opacity: 0,
+				transform: `translateY(${TRANSFORMS.OFFSET_Y_EXIT}px) scale(${TRANSFORMS.SCALE_EXIT})`,
+				filter: `blur(${EFFECTS.BLUR_EXIT}px)`
+			}], {
+				duration,
+				easing,
+				delay,
+				fill: "forwards"
+			});
+			exitAnimations.push(anim);
+		});
+		else {
+			const anim = el.animate([{
+				opacity: 1,
+				transform: "scale(1)"
+			}, {
+				opacity: 0,
+				transform: `scale(${TRANSFORMS.SCALE_EXIT})`
+			}], {
+				duration,
+				easing,
+				fill: "forwards"
+			});
+			exitAnimations.push(anim);
+		}
+		stateRef.current.activeAnimations.set(id, [...exitAnimations, ...flipAnimations]);
+		try {
+			await Promise.all([...exitAnimations.map((a) => a.finished), ...flipAnimations.map((a) => a.finished)]);
+		} catch {
+			stateRef.current.animatingIds.delete(id);
+			stateRef.current.activeAnimations.delete(id);
+			return;
+		}
+		stateRef.current.animatingIds.delete(id);
+		stateRef.current.activeAnimations.delete(id);
+		el.dataset.reorderState = "completed";
+		if (exitPositionStrategy === "absolute-fixed") {
+			el.style.removeProperty("position");
+			el.style.removeProperty("left");
+			el.style.removeProperty("top");
+			el.style.removeProperty("width");
+			el.style.removeProperty("height");
+			el.style.removeProperty("margin");
+		}
+		delete el.dataset.exitPosition;
+		registry.unregister(id);
+		options?.onComplete?.();
+		configRef.current?.onExitComplete?.(id);
+	}, [
+		registry,
+		exitDuration,
+		exitEasing,
+		flipDuration,
+		flipBehavior,
+		exitPositionStrategy
+	]);
+	/**
+	* Start enter animation for an element.
+	*
+	* Architecture: CSS + WAAPI
+	* - Assumes element already has data-reorder-state="entering" (set by Reorder.tsx)
+	* - CSS [data-reorder-state="entering"] { opacity: 0; transform: translateY(-8px) scale(0.95); }
+	* - WAAPI animates FROM that state TO visible
+	* - Sets data-reorder-state="idle" on completion
+	*/
+	const startEnter = useCallback(async (id, options) => {
+		const el = registry.get(id);
+		if (!el) return;
+		if (!el.dataset.reorderState) el.dataset.reorderState = "entering";
+		const enterDuration = configRef.current?.enterDuration ?? TIMING.ENTER_DURATION;
+		const enterEasing = configRef.current?.enterEasing ?? EASINGS.MATERIAL_DECELERATE;
+		const duration = options?.duration ?? enterDuration;
+		const easing = options?.easing ?? enterEasing;
+		const stagger = options?.stagger ?? TIMING.ENTER_STAGGER;
+		const tokens = el.querySelectorAll(".waapi-sliding-text-token");
+		const animations = [];
+		const fromKeyframe = {
+			opacity: 0,
+			transform: "translateY(-8px) scale(0.95)"
+		};
+		const toKeyframe = {
+			opacity: 1,
+			transform: "none"
+		};
+		if (tokens.length > 0) tokens.forEach((token, index) => {
+			const delay = index * stagger;
+			token.dataset.reorderIndex = String(index);
+			const anim = token.animate([{
+				...fromKeyframe,
+				filter: `blur(${EFFECTS.BLUR_ENTER}px)`
+			}, {
+				...toKeyframe,
+				filter: "blur(0px)"
+			}], {
+				duration,
+				easing,
+				delay,
+				fill: "forwards"
+			});
+			animations.push(anim);
+		});
+		else {
+			const anim = el.animate([fromKeyframe, toKeyframe], {
+				duration,
+				easing,
+				fill: "forwards"
+			});
+			animations.push(anim);
+		}
+		try {
+			await Promise.all(animations.map((a) => a.finished));
+		} catch {
+			el.dataset.reorderState = "idle";
+			return;
+		}
+		el.dataset.reorderState = "idle";
+		options?.onComplete?.();
+		configRef.current?.onEnterComplete?.(id);
+	}, [registry]);
+	const isAnimating = useCallback((id) => {
+		if (id) return stateRef.current.animatingIds.has(id);
+		return stateRef.current.animatingIds.size > 0;
+	}, []);
+	const capturePositions = useCallback((excludeIds) => {
+		return positions.capture(excludeIds);
+	}, [positions]);
+	useEffect(() => {
+		return () => {
+			cancelAllAnimations();
+		};
+	}, [cancelAllAnimations]);
+	return {
+		registry,
+		positions,
+		flip,
+		registerElement: registry.register,
+		startExit,
+		startEnter,
+		isAnimating,
+		cancelAnimation,
+		cancelAllAnimations,
+		capturePositions
+	};
+}
+
+//#endregion
+export { useAnimationOrchestrator };

package/dist/react-ui/primitives/waapi/core/useElementRegistry.d.ts

@@ -0,0 +1,21 @@
+import type { IElementRegistryAPI, IElementRegistryCallbacks } from './types';
+/**
+ * Hook for tracking DOM elements by ID.
+ * Extracted from the WAAPI animation system's element registration logic.
+ *
+ * @param callbacks - Optional lifecycle callbacks for register/unregister events
+ * @returns Registry API for managing elements by ID
+ *
+ * @example
+ * ```tsx
+ * const registry = useElementRegistry({
+ *   onRegister: (id) => console.log(`Registered: ${id}`),
+ *   onUnregister: (id) => console.log(`Unregistered: ${id}`)
+ * });
+ *
+ * // In render:
+ * <div ref={el => registry.register('item-1', el)} />
+ * ```
+ */
+export declare function useElementRegistry(callbacks?: IElementRegistryCallbacks): IElementRegistryAPI;
+//# sourceMappingURL=useElementRegistry.d.ts.map

package/dist/react-ui/primitives/waapi/core/useElementRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useElementRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/primitives/waapi/core/useElementRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,CAAC,EAAE,yBAAyB,GACpC,mBAAmB,CAwDrB"}

package/dist/react-ui/primitives/waapi/core/useElementRegistry.js

@@ -0,0 +1,65 @@
+import { useCallback, useEffect, useRef } from "react";
+
+//#region src/react-ui/primitives/waapi/core/useElementRegistry.ts
+/**
+* Hook for tracking DOM elements by ID.
+* Extracted from the WAAPI animation system's element registration logic.
+*
+* @param callbacks - Optional lifecycle callbacks for register/unregister events
+* @returns Registry API for managing elements by ID
+*
+* @example
+* ```tsx
+* const registry = useElementRegistry({
+*   onRegister: (id) => console.log(`Registered: ${id}`),
+*   onUnregister: (id) => console.log(`Unregistered: ${id}`)
+* });
+*
+* // In render:
+* <div ref={el => registry.register('item-1', el)} />
+* ```
+*/
+function useElementRegistry(callbacks) {
+	const elementsRef = useRef(/* @__PURE__ */ new Map());
+	const callbacksRef = useRef(callbacks);
+	useEffect(() => {
+		callbacksRef.current = callbacks;
+	}, [callbacks]);
+	return {
+		register: useCallback((id, el) => {
+			if (el) {
+				elementsRef.current.set(id, el);
+				callbacksRef.current?.onRegister?.(id, el);
+			} else if (elementsRef.current.has(id)) {
+				elementsRef.current.delete(id);
+				callbacksRef.current?.onUnregister?.(id);
+			}
+		}, []),
+		unregister: useCallback((id) => {
+			if (elementsRef.current.has(id)) {
+				elementsRef.current.delete(id);
+				callbacksRef.current?.onUnregister?.(id);
+			}
+		}, []),
+		get: useCallback((id) => {
+			return elementsRef.current.get(id);
+		}, []),
+		getAll: useCallback(() => {
+			return new Map(elementsRef.current);
+		}, []),
+		has: useCallback((id) => {
+			return elementsRef.current.has(id);
+		}, []),
+		clear: useCallback(() => {
+			const ids = Array.from(elementsRef.current.keys());
+			elementsRef.current.clear();
+			ids.forEach((id) => callbacksRef.current?.onUnregister?.(id));
+		}, []),
+		get size() {
+			return elementsRef.current.size;
+		}
+	};
+}
+
+//#endregion
+export { useElementRegistry };

package/dist/react-ui/primitives/waapi/core/useFLIPAnimation.d.ts

@@ -0,0 +1,20 @@
+import type { IFLIPAnimationAPI } from './types';
+/**
+ * Hook for executing FLIP (First-Last-Invert-Play) animations.
+ * Uses spring easing for natural motion with slight overshoot.
+ *
+ * @returns FLIP animation API with animate, cancel, and status methods
+ *
+ * @example
+ * ```tsx
+ * const flip = useFLIPAnimation();
+ *
+ * // After calculating deltas:
+ * await flip.animateAll(elements, deltas, {
+ *   duration: 300,
+ *   onComplete: (id) => console.log(`${id} completed`)
+ * });
+ * ```
+ */
+export declare function useFLIPAnimation(): IFLIPAnimationAPI;
+//# sourceMappingURL=useFLIPAnimation.d.ts.map

package/dist/react-ui/primitives/waapi/core/useFLIPAnimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFLIPAnimation.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/primitives/waapi/core/useFLIPAnimation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,SAAS,CAAC;AAKpF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAgHpD"}