@mks2508/mks-ui 0.2.1 → 0.3.1

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"}

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

@@ -0,0 +1,99 @@
+import { EASINGS, TIMING } from "./animationConstants.js";
+import { useCallback, useEffect, useRef } from "react";
+
+//#region src/react-ui/primitives/waapi/core/useFLIPAnimation.ts
+const DEFAULT_DURATION = TIMING.FLIP_DURATION;
+const DEFAULT_EASING = EASINGS.SPRING_GENTLE;
+/**
+* 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`)
+* });
+* ```
+*/
+function useFLIPAnimation() {
+	const activeAnimationsRef = useRef(/* @__PURE__ */ new Map());
+	const animatingIdsRef = useRef(/* @__PURE__ */ new Set());
+	const animate = useCallback((element, delta, options) => {
+		const duration = options?.duration ?? DEFAULT_DURATION;
+		const easing = options?.easing ?? DEFAULT_EASING;
+		if (activeAnimationsRef.current.has(delta.id)) activeAnimationsRef.current.get(delta.id)?.cancel();
+		animatingIdsRef.current.add(delta.id);
+		options?.onStart?.(delta.id);
+		const animation = element.animate([{ transform: `translate3d(${delta.deltaX}px, ${delta.deltaY}px, 0)` }, { transform: "translate3d(0, 0, 0)" }], {
+			duration,
+			easing
+		});
+		activeAnimationsRef.current.set(delta.id, animation);
+		animation.onfinish = () => {
+			animatingIdsRef.current.delete(delta.id);
+			activeAnimationsRef.current.delete(delta.id);
+			options?.onComplete?.(delta.id);
+		};
+		animation.oncancel = () => {
+			animatingIdsRef.current.delete(delta.id);
+			activeAnimationsRef.current.delete(delta.id);
+		};
+		return animation;
+	}, []);
+	const animateAll = useCallback(async (elements, deltas, options) => {
+		const animations = [];
+		deltas.forEach((delta, id) => {
+			if (!delta.isSignificant) return;
+			const element = elements.get(id);
+			if (!element) return;
+			const anim = animate(element, delta, options);
+			animations.push(anim);
+		});
+		if (animations.length === 0) return;
+		await Promise.all(animations.map((anim) => anim.finished.catch(() => {})));
+	}, [animate]);
+	const cancel = useCallback((id) => {
+		const animation = activeAnimationsRef.current.get(id);
+		if (animation) {
+			animation.cancel();
+			activeAnimationsRef.current.delete(id);
+			animatingIdsRef.current.delete(id);
+		}
+	}, []);
+	const cancelAll = useCallback(() => {
+		activeAnimationsRef.current.forEach((animation) => animation.cancel());
+		activeAnimationsRef.current.clear();
+		animatingIdsRef.current.clear();
+	}, []);
+	const isAnimating = useCallback((id) => {
+		if (id) return animatingIdsRef.current.has(id);
+		return animatingIdsRef.current.size > 0;
+	}, []);
+	useEffect(() => {
+		return () => {
+			cancelAll();
+		};
+	}, [cancelAll]);
+	const api = useRef({
+		animate,
+		animateAll,
+		cancel,
+		cancelAll,
+		isAnimating
+	});
+	api.current.animate = animate;
+	api.current.animateAll = animateAll;
+	api.current.cancel = cancel;
+	api.current.cancelAll = cancelAll;
+	api.current.isAnimating = isAnimating;
+	return api.current;
+}
+
+//#endregion
+export { useFLIPAnimation };

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

@@ -0,0 +1,24 @@
+import type { IPositionCaptureAPI, IPositionCaptureOptions } from './types';
+/**
+ * Hook for capturing element positions and calculating FLIP deltas.
+ * Extracted from the WAAPI animation system's position capture logic.
+ *
+ * @param getElements - Function that returns the current element map
+ * @param options - Optional configuration (e.g. minimum delta threshold)
+ * @returns Position capture API with capture, delta calculation, and cache
+ *
+ * @example
+ * ```tsx
+ * const registry = useElementRegistry();
+ * const positions = usePositionCapture(registry.getAll);
+ *
+ * // Before layout change:
+ * const before = positions.capture();
+ *
+ * // After layout change:
+ * const after = positions.capture();
+ * const deltas = positions.calculateDeltas(before, after);
+ * ```
+ */
+export declare function usePositionCapture(getElements: () => Map<string, HTMLElement>, options?: IPositionCaptureOptions): IPositionCaptureAPI;
+//# sourceMappingURL=usePositionCapture.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePositionCapture.d.ts","sourceRoot":"","sources":["../../../../../src/react-ui/primitives/waapi/core/usePositionCapture.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAc,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAIxF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAChC,mBAAmB,CA0ErB"}

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

@@ -0,0 +1,75 @@
+import { TIMING } from "./animationConstants.js";
+import { useCallback, useRef } from "react";
+
+//#region src/react-ui/primitives/waapi/core/usePositionCapture.ts
+const DEFAULT_MIN_DELTA_PX = TIMING.MIN_DELTA_PX;
+/**
+* Hook for capturing element positions and calculating FLIP deltas.
+* Extracted from the WAAPI animation system's position capture logic.
+*
+* @param getElements - Function that returns the current element map
+* @param options - Optional configuration (e.g. minimum delta threshold)
+* @returns Position capture API with capture, delta calculation, and cache
+*
+* @example
+* ```tsx
+* const registry = useElementRegistry();
+* const positions = usePositionCapture(registry.getAll);
+*
+* // Before layout change:
+* const before = positions.capture();
+*
+* // After layout change:
+* const after = positions.capture();
+* const deltas = positions.calculateDeltas(before, after);
+* ```
+*/
+function usePositionCapture(getElements, options) {
+	const lastCaptureRef = useRef(/* @__PURE__ */ new Map());
+	const minDeltaPx = options?.minDeltaPx ?? DEFAULT_MIN_DELTA_PX;
+	return {
+		capture: useCallback((excludeIds) => {
+			const positions = /* @__PURE__ */ new Map();
+			getElements().forEach((el, id) => {
+				if (excludeIds?.has(id)) return;
+				const rect = el.getBoundingClientRect();
+				if (rect.width > 0 && rect.height > 0) positions.set(id, rect);
+			});
+			lastCaptureRef.current = positions;
+			return positions;
+		}, [getElements]),
+		getPosition: useCallback((id) => {
+			return lastCaptureRef.current.get(id);
+		}, []),
+		calculateDeltas: useCallback((before, after) => {
+			const deltas = /* @__PURE__ */ new Map();
+			after.forEach((newRect, id) => {
+				const prevRect = before.get(id);
+				if (!prevRect) return;
+				const deltaX = prevRect.left - newRect.left;
+				const deltaY = prevRect.top - newRect.top;
+				const deltaWidth = prevRect.width - newRect.width;
+				const deltaHeight = prevRect.height - newRect.height;
+				const isSignificant = Math.abs(deltaX) >= minDeltaPx || Math.abs(deltaY) >= minDeltaPx || Math.abs(deltaWidth) >= minDeltaPx || Math.abs(deltaHeight) >= minDeltaPx;
+				deltas.set(id, {
+					id,
+					deltaX,
+					deltaY,
+					deltaWidth,
+					deltaHeight,
+					isSignificant
+				});
+			});
+			return deltas;
+		}, [minDeltaPx]),
+		getLastCapture: useCallback(() => {
+			return new Map(lastCaptureRef.current);
+		}, []),
+		clear: useCallback(() => {
+			lastCaptureRef.current.clear();
+		}, [])
+	};
+}
+
+//#endregion
+export { usePositionCapture };

package/dist/react-ui/primitives/waapi/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WAAPI Animation Primitives
+ *
+ * Lightweight, performant React animation components built on the Web Animations API (WAAPI).
+ *
+ * @example
+ * ```tsx
+ * import { SlidingNumber, SlidingText, Reorder, Morph } from '@mks2508/mks-ui/react/primitives/waapi';
+ * ```
+ */
+export { TIMING, TRANSFORMS, EFFECTS, EASINGS, RESPONSIVE_CONFIGS, ANIMATION_CONFIGS, ANIMATION_DEFAULTS, PRESETS, getResponsiveDuration, getResponsiveStagger, } from './core';
+export { useElementRegistry } from './core';
+export { usePositionCapture } from './core';
+export { useFLIPAnimation } from './core';
+export { useAnimationOrchestrator } from './core';
+export type { IFLIPDelta, IAnimationTiming, IPositionRect, IElementRegistryAPI, IElementRegistryCallbacks, IPositionCaptureAPI, IPositionCaptureOptions, IFLIPAnimationAPI, IFLIPAnimationOptions, IExitOptions, IEnterOptions, IAnimationOrchestratorConfig, IAnimationOrchestratorAPI, IOrchestratorState, IAnimationEvent, FLIPBehavior, ExitPositionStrategy, AnimationPhase, } from './core';
+export { SlidingNumber } from './SlidingNumber';
+export type { ISlidingNumberProps, IFormatOptions, } from './SlidingNumber/SlidingNumber.types';
+export { SlidingText } from './SlidingText';
+export type { ISlidingTextProps } from './SlidingText/SlidingText.types';
+export { Reorder } from './Reorder';
+export type { IReorderProps, ReorderLayout, DurationConfig, StaggerConfig, IUseReorderReturn, IUseReorderConfig, IReorderItemState, IReorderContextValue, IUseReorderPresenceConfig, IUseReorderPresenceReturn, } from './Reorder/Reorder.types';
+export { useReorder } from './Reorder/useReorder';
+export { useReorderPresence } from './Reorder/useReorderPresence';
+export { calculateSeparatorCoordination, shouldShowSeparator } from './Reorder/utils/separatorCoordination';
+export { Morph } from './Morph';
+export type { IMorphProps, IMorphContextValue, IUseMorphConfig, IUseMorphReturn, MorphTechnique, IFLIPClipPathOptions, IFLIPClipPathAPI, ICSSGridMorphOptions, ICSSGridMorphAPI, IViewTransitionsOptions, IViewTransitionsAPI, } from './Morph/Morph.types';
+export { useMorph } from './Morph/useMorph';
+export { useMorphContext } from './Morph/MorphContext';
+export { useFLIPClipPath } from './Morph/techniques/useFLIPClipPath';
+export { useCSSGridMorph } from './Morph/techniques/useCSSGridMorph';
+export { useViewTransitions } from './Morph/techniques/useViewTransitions';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/primitives/waapi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,EACL,MAAM,EACN,UAAU,EACV,OAAO,EACP,OAAO,EACP,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,OAAO,EACP,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,wBAAwB,EAAE,MAAM,QAAQ,CAAC;AAGlD,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,4BAA4B,EAC5B,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,QAAQ,CAAC;AAKhB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EACV,mBAAmB,EACnB,cAAc,GACf,MAAM,qCAAqC,CAAC;AAK7C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAKzE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,8BAA8B,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAK5G,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC"}