@mks2508/mks-ui 0.2.0 → 0.3.1

package/src/react-ui/primitives/waapi/core/usePositionCapture.ts

@@ -0,0 +1,105 @@
+import { useRef, useCallback } from 'react';
+import { TIMING } from './animationConstants';
+import type { IPositionCaptureAPI, IFLIPDelta, IPositionCaptureOptions } from './types';
+
+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);
+ * ```
+ */
+export function usePositionCapture(
+  getElements: () => Map<string, HTMLElement>,
+  options?: IPositionCaptureOptions
+): IPositionCaptureAPI {
+  const lastCaptureRef = useRef<Map<string, DOMRect>>(new Map());
+  const minDeltaPx = options?.minDeltaPx ?? DEFAULT_MIN_DELTA_PX;
+
+  const capture = useCallback((excludeIds?: Set<string>): Map<string, DOMRect> => {
+    const positions = new Map<string, DOMRect>();
+    const elements = getElements();
+
+    elements.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]);
+
+  const getPosition = useCallback((id: string): DOMRect | undefined => {
+    return lastCaptureRef.current.get(id);
+  }, []);
+
+  const calculateDeltas = useCallback((
+    before: Map<string, DOMRect>,
+    after: Map<string, DOMRect>
+  ): Map<string, IFLIPDelta> => {
+    const deltas = new Map<string, IFLIPDelta>();
+
+    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]);
+
+  const getLastCapture = useCallback((): Map<string, DOMRect> => {
+    return new Map(lastCaptureRef.current);
+  }, []);
+
+  const clear = useCallback(() => {
+    lastCaptureRef.current.clear();
+  }, []);
+
+  return {
+    capture,
+    getPosition,
+    calculateDeltas,
+    getLastCapture,
+    clear
+  };
+}

package/src/react-ui/primitives/waapi/index.ts

@@ -0,0 +1,116 @@
+/**
+ * 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';
+ * ```
+ */
+
+// ============================================================
+// Core — FLIP animation infrastructure
+// ============================================================
+
+// Constants (SSOT)
+export {
+  TIMING,
+  TRANSFORMS,
+  EFFECTS,
+  EASINGS,
+  RESPONSIVE_CONFIGS,
+  ANIMATION_CONFIGS,
+  ANIMATION_DEFAULTS,
+  PRESETS,
+  getResponsiveDuration,
+  getResponsiveStagger,
+} from './core';
+
+// Core hooks
+export { useElementRegistry } from './core';
+export { usePositionCapture } from './core';
+export { useFLIPAnimation } from './core';
+export { useAnimationOrchestrator } from './core';
+
+// Core types
+export type {
+  IFLIPDelta,
+  IAnimationTiming,
+  IPositionRect,
+  IElementRegistryAPI,
+  IElementRegistryCallbacks,
+  IPositionCaptureAPI,
+  IPositionCaptureOptions,
+  IFLIPAnimationAPI,
+  IFLIPAnimationOptions,
+  IExitOptions,
+  IEnterOptions,
+  IAnimationOrchestratorConfig,
+  IAnimationOrchestratorAPI,
+  IOrchestratorState,
+  IAnimationEvent,
+  FLIPBehavior,
+  ExitPositionStrategy,
+  AnimationPhase,
+} from './core';
+
+// ============================================================
+// SlidingNumber - Animated number transitions
+// ============================================================
+export { SlidingNumber } from './SlidingNumber';
+export type {
+  ISlidingNumberProps,
+  IFormatOptions,
+} from './SlidingNumber/SlidingNumber.types';
+
+// ============================================================
+// SlidingText - Character/word text animations
+// ============================================================
+export { SlidingText } from './SlidingText';
+export type { ISlidingTextProps } from './SlidingText/SlidingText.types';
+
+// ============================================================
+// Reorder - FLIP list reordering
+// ============================================================
+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';
+
+// ============================================================
+// Morph - Morphing animations
+// ============================================================
+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';
+
+// Morph techniques (individual)
+export { useFLIPClipPath } from './Morph/techniques/useFLIPClipPath';
+export { useCSSGridMorph } from './Morph/techniques/useCSSGridMorph';
+export { useViewTransitions } from './Morph/techniques/useViewTransitions';

package/src/react-ui/styles/animations.css

@@ -0,0 +1,369 @@
+/* ============================================
+   WAAPI Animation Primitives - CSS-First Architecture
+
+   RESPONSIBILITIES:
+   - CSS: Structure, final states, accessibility
+   - WAAPI: Dynamic animations, FLIP, timing
+
+   GOLDEN RULE: CSS does NOT animate what WAAPI controls
+   ============================================ */
+
+/* ============================================
+   CSS Variables for WAAPI Animations
+   These can be overridden by consumers
+   ============================================ */
+:root {
+  /* Timing */
+  --waapi-duration-enter: 200ms;
+  --waapi-duration-exit: 180ms;
+  --waapi-duration-collapse: 200ms;
+  --waapi-duration-flip: 300ms;
+  --waapi-stagger-enter: 15ms;
+  --waapi-stagger-exit: 0ms;
+
+  /* Transforms */
+  --waapi-offset-y-enter: 8px;
+  --waapi-offset-y-exit: -8px;
+  --waapi-offset-x: 16px;
+  --waapi-scale-exit: 0.85;
+
+  /* Effects */
+  --waapi-blur-enter: 4px;
+  --waapi-blur-exit: 2px;
+
+  /* Easings */
+  --waapi-ease-enter: cubic-bezier(0.33, 1, 0.68, 1);
+  --waapi-ease-exit: cubic-bezier(0.32, 0, 0.67, 0);
+  --waapi-ease-collapse: cubic-bezier(0.42, 0, 0.58, 1);
+  --waapi-ease-flip: cubic-bezier(0.2, 0, 0.2, 1);
+}
+
+/* ===========================================
+   REORDER CONTAINER
+   =========================================== */
+.waapi-reorder-container {
+  position: relative;
+}
+
+/* ===========================================
+   REORDER ITEM - Base State
+   [data-reorder-state] marks elements controlled by the orchestrator
+   =========================================== */
+[data-reorder-state] {
+  position: relative;
+  will-change: transform, opacity;
+}
+
+/* ===========================================
+   STATE: IDLE (Default)
+   Normal state after animation completes
+   =========================================== */
+[data-reorder-state="idle"] {
+  opacity: 1;
+  transform: none;
+  will-change: auto;
+}
+
+/* ===========================================
+   STATE: ENTERING
+   CSS: Starts HIDDEN - WAAPI animates to visible
+   Prevents flicker - element is hidden BEFORE JS runs
+   =========================================== */
+[data-reorder-state="entering"] {
+  opacity: 0;
+  transform: translateY(-8px) scale(0.95);
+}
+
+/* ===========================================
+   STATE: EXITING
+   WAAPI controls opacity and transform
+   =========================================== */
+[data-reorder-state="exiting"] {
+  pointer-events: none;
+}
+
+/* Exit position variant: absolute-fixed */
+[data-reorder-state="exiting"][data-exit-position="absolute"] {
+  position: absolute;
+}
+
+/* Exit position variant: in-place */
+[data-reorder-state="exiting"][data-exit-position="in-place"] {
+  position: relative;
+}
+
+/* ===========================================
+   STATE: FLIPPING
+   WAAPI controls the translate3d FLIP
+   =========================================== */
+[data-reorder-state="flipping"] {
+  /* WAAPI manages the FLIP transform */
+}
+
+/* ===========================================
+   STATE: COMPLETED (Post-Animation)
+   CSS handles final state, no animation needed
+   =========================================== */
+[data-reorder-state="completed"] {
+  position: absolute !important;
+  opacity: 0 !important;
+  pointer-events: none !important;
+  visibility: hidden;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
+/* ===========================================
+   SEPARATOR STATES
+   =========================================== */
+[data-separator-state] {
+  display: inline;
+  white-space: pre;
+  will-change: transform, opacity;
+}
+
+[data-separator-state="idle"] {
+  /* Normal */
+}
+
+[data-separator-state="exiting"] {
+  pointer-events: none;
+}
+
+[data-separator-state="completed"] {
+  opacity: 0;
+  position: absolute;
+  pointer-events: none;
+  width: 0;
+  overflow: hidden;
+}
+
+/* ===========================================
+   FLIP BEHAVIOR VARIANTS
+   Controls which elements participate in FLIP
+   =========================================== */
+[data-flip-behavior="all"] {
+  /* Default: all siblings do FLIP */
+}
+
+[data-flip-behavior="siblings-after"] {
+  /* Only siblings after the exiting item */
+}
+
+[data-flip-behavior="none"] {
+  /* This item does not participate in FLIP */
+}
+
+/* ===========================================
+   STAGGER INDEX (Progressive Enhancement)
+   Chrome 138+, Safari TP 226+ support sibling-index()
+   =========================================== */
+@supports (animation-delay: calc(sibling-index() * 1ms)) {
+  [data-reorder-state="entering"] {
+    --waapi-stagger-index: sibling-index();
+  }
+}
+
+/* Fallback: use data-reorder-index set by JS */
+[data-reorder-index] {
+  /* JS sets this for stagger calculation fallback */
+}
+
+/* ===========================================
+   LEGACY CLASS SUPPORT
+   Compatibility with existing components
+   =========================================== */
+
+/* Token wrapper - FLIP-ready container */
+.waapi-token-wrapper {
+  display: inline-flex;
+  align-items: center;
+}
+
+.waapi-token-wrapper.exit-completed,
+.waapi-token-wrapper[data-reorder-state="completed"] {
+  position: absolute !important;
+  opacity: 0 !important;
+  pointer-events: none !important;
+}
+
+/* Token separator - WAAPI handles animations */
+.waapi-token-separator {
+  display: inline !important;
+  white-space: pre;
+  margin-left: 0.25em;
+  will-change: transform, opacity;
+}
+
+.waapi-token-separator.exit-coordinated {
+  /* Intentionally empty - WAAPI handles animation */
+}
+
+.waapi-token-separator.flip-active {
+  will-change: transform;
+}
+
+.waapi-token-separator.exit-completed {
+  opacity: 0;
+  position: absolute;
+  pointer-events: none;
+  width: 0;
+  overflow: hidden;
+}
+
+/* Token overflow indicator */
+.waapi-token-overflow {
+  display: inline-flex;
+  align-items: center;
+  white-space: nowrap;
+}
+
+/* SlidingText container */
+.waapi-sliding-text-container {
+  display: inline-flex;
+  overflow: visible;
+  vertical-align: bottom;
+  will-change: width;
+}
+
+.waapi-sliding-text-content {
+  display: inline-flex;
+  white-space: pre;
+}
+
+/* SlidingText token */
+.waapi-sliding-text-token {
+  display: inline-block;
+  will-change: transform, opacity, filter;
+  backface-visibility: hidden;
+  font-weight: 500;
+}
+
+.waapi-sliding-text-token.enter-from {
+  opacity: 0;
+  filter: blur(var(--blur-amount, 4px));
+}
+
+.waapi-sliding-text-token.enter-to {
+  opacity: 1;
+  transform: translate(0, 0);
+  filter: blur(0);
+}
+
+.waapi-sliding-text-token.exit-active {
+  opacity: 0;
+  filter: blur(var(--blur-amount, 4px));
+}
+
+/* Direction variants */
+.waapi-direction-vertical .waapi-sliding-text-token.enter-from {
+  transform: translateY(var(--offset, 8px));
+}
+
+.waapi-direction-vertical .waapi-sliding-text-token.exit-active {
+  transform: translateY(calc(var(--offset, 8px) * -1));
+}
+
+.waapi-direction-horizontal .waapi-sliding-text-token.enter-from {
+  transform: translateX(var(--offset, 16px));
+}
+
+.waapi-direction-horizontal .waapi-sliding-text-token.exit-active {
+  transform: translateX(calc(var(--offset, 16px) * -1));
+}
+
+/* AnimatedTokens container */
+.waapi-animated-tokens-container {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0;
+}
+
+.waapi-animated-tokens-container.waapi-animated-tokens-container--inline {
+  display: inline-flex;
+  flex-wrap: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Placeholder styling */
+.waapi-token-placeholder {
+  color: var(--muted-foreground, #888) !important;
+  font-style: italic;
+}
+
+/* Sliding Number Styles */
+.waapi-sliding-number {
+  display: inline-flex;
+  align-items: center;
+  font-variant-numeric: tabular-nums;
+}
+
+/* ===========================================
+   ACCESSIBILITY - Reduced Motion
+   =========================================== */
+@media (prefers-reduced-motion: reduce) {
+  [data-reorder-state],
+  [data-separator-state],
+  .waapi-token-separator,
+  .waapi-sliding-text-token,
+  .waapi-token-wrapper {
+    will-change: auto;
+    transition: none !important;
+    animation: none !important;
+  }
+}
+
+/* ===========================================
+   ACCESSIBILITY - High Contrast
+   =========================================== */
+@media (prefers-contrast: high) {
+  .waapi-sliding-text-token.enter-from,
+  .waapi-sliding-text-token.exit-active {
+    filter: none;
+  }
+}
+
+/* ===========================================
+   MOBILE - Performance Optimization
+   =========================================== */
+@media (max-width: 768px) {
+  .waapi-token-wrapper,
+  [data-reorder-state] {
+    transform: translateZ(0);
+    backface-visibility: hidden;
+    perspective: 1000px;
+  }
+}
+
+/* ===========================================
+   PRINT - Disable animations, show content
+   =========================================== */
+@media print {
+  .waapi-animated-tokens-container,
+  .waapi-sliding-text-container,
+  .waapi-token-separator,
+  .waapi-token-wrapper,
+  [data-reorder-state],
+  [data-separator-state] {
+    transition: none !important;
+    animation: none !important;
+    transform: none !important;
+    opacity: 1 !important;
+  }
+
+  .waapi-token-separator.exit-completed,
+  .waapi-token-wrapper.exit-completed,
+  [data-reorder-state="completed"],
+  [data-separator-state="completed"] {
+    position: static !important;
+    opacity: 1 !important;
+    pointer-events: auto !important;
+    visibility: visible !important;
+    width: auto !important;
+    height: auto !important;
+  }
+}