@enact-ui/animate 0.1.0 → 0.2.0

package/dist/utils/reduced-motion.js

@@ -0,0 +1,362 @@
+// Copyright (c) 2026 Amsterdam Data Labs
+"use client";
+/**
+ * Reduced Motion Utilities
+ *
+ * @ai-hint This module provides utilities for handling the `prefers-reduced-motion`
+ * media query. Use these utilities to ensure animations are accessible and respect
+ * user preferences for reduced motion.
+ *
+ * @packageDocumentation
+ */
+import { useEffect, useState } from "react";
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Media query string for detecting reduced motion preference.
+ *
+ * @ai-hint Use this constant when you need to directly query the media feature
+ * outside of the provided hooks.
+ */
+export const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/**
+ * Default transition for reduced motion mode.
+ * Provides instant transitions without animation.
+ *
+ * @ai-hint This transition effectively disables animation while still
+ * allowing the final state to be applied immediately.
+ */
+export const INSTANT_TRANSITION = {
+    duration: 0,
+    delay: 0,
+};
+// =============================================================================
+// Hooks
+// =============================================================================
+/**
+ * Hook that returns whether the user prefers reduced motion.
+ *
+ * @ai-hint This hook reactively tracks the `prefers-reduced-motion` media query.
+ * It updates automatically when the user changes their system preference.
+ * Use this hook to conditionally apply or skip animations.
+ *
+ * @returns `true` if the user prefers reduced motion, `false` otherwise
+ *
+ * @example
+ * ```tsx
+ * function AnimatedComponent() {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     return (
+ *         <motion.div
+ *             animate={{ x: 100 }}
+ *             transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.5 }}
+ *         >
+ *             Content
+ *         </motion.div>
+ *     );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Skip animation entirely when reduced motion is preferred
+ * function FadeInComponent({ children }: { children: React.ReactNode }) {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     if (prefersReducedMotion) {
+ *         return <div>{children}</div>;
+ *     }
+ *
+ *     return (
+ *         <motion.div
+ *             initial={{ opacity: 0 }}
+ *             animate={{ opacity: 1 }}
+ *             transition={{ duration: 0.3 }}
+ *         >
+ *             {children}
+ *         </motion.div>
+ *     );
+ * }
+ * ```
+ */
+export function useReducedMotion() {
+    const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
+        // Return false during SSR
+        if (typeof window === "undefined") {
+            return false;
+        }
+        return window.matchMedia(REDUCED_MOTION_QUERY).matches;
+    });
+    useEffect(() => {
+        const mediaQuery = window.matchMedia(REDUCED_MOTION_QUERY);
+        // Set initial value (handles hydration mismatch)
+        setPrefersReducedMotion(mediaQuery.matches);
+        // Listen for changes to the preference
+        const handleChange = (event) => {
+            setPrefersReducedMotion(event.matches);
+        };
+        mediaQuery.addEventListener("change", handleChange);
+        return () => {
+            mediaQuery.removeEventListener("change", handleChange);
+        };
+    }, []);
+    return prefersReducedMotion;
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Returns the appropriate variant based on reduced motion preference.
+ *
+ * @ai-hint Use this function to provide alternative animation variants for users
+ * who prefer reduced motion. The reduced variant should avoid or minimize
+ * movement-based animations while potentially preserving opacity/color changes.
+ *
+ * @param normalVariant - The variant to use when motion is allowed
+ * @param reducedVariant - The variant to use when reduced motion is preferred
+ * @returns The appropriate variant based on the current reduced motion preference
+ *
+ * @example
+ * ```tsx
+ * function SlideInCard() {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     const normalVariant = {
+ *         hidden: { x: -100, opacity: 0 },
+ *         visible: { x: 0, opacity: 1 },
+ *     };
+ *
+ *     const reducedVariant = {
+ *         hidden: { opacity: 0 },
+ *         visible: { opacity: 1 },
+ *     };
+ *
+ *     const variants = getReducedMotionVariant(
+ *         normalVariant,
+ *         reducedVariant,
+ *         prefersReducedMotion
+ *     );
+ *
+ *     return (
+ *         <motion.div
+ *             variants={variants}
+ *             initial="hidden"
+ *             animate="visible"
+ *         >
+ *             Card Content
+ *         </motion.div>
+ *     );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with a hook for reactive updates
+ * function AnimatedList({ items }: { items: string[] }) {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     const itemVariant = getReducedMotionVariant(
+ *         { hidden: { y: 20, opacity: 0 }, visible: { y: 0, opacity: 1 } },
+ *         { hidden: { opacity: 0 }, visible: { opacity: 1 } },
+ *         prefersReducedMotion
+ *     );
+ *
+ *     return (
+ *         <motion.ul>
+ *             {items.map((item, i) => (
+ *                 <motion.li
+ *                     key={item}
+ *                     variants={itemVariant}
+ *                     initial="hidden"
+ *                     animate="visible"
+ *                     transition={{ delay: i * 0.1 }}
+ *                 >
+ *                     {item}
+ *                 </motion.li>
+ *             ))}
+ *         </motion.ul>
+ *     );
+ * }
+ * ```
+ */
+export function getReducedMotionVariant(normalVariant, reducedVariant, prefersReducedMotion) {
+    return prefersReducedMotion ? reducedVariant : normalVariant;
+}
+/**
+ * Properties that are considered safe for reduced motion mode.
+ * These typically don't involve movement and are accessibility-friendly.
+ *
+ * @ai-hint Opacity and color changes are generally acceptable even for users
+ * who prefer reduced motion, as they don't cause vestibular issues.
+ */
+const _SAFE_ANIMATION_PROPERTIES = new Set(["opacity", "color", "backgroundColor", "borderColor", "fill", "stroke"]);
+/**
+ * Filters a variant to only include safe properties for reduced motion.
+ *
+ * @param variant - The variant to filter
+ * @param options - Options for filtering
+ * @returns Filtered variant with only safe properties
+ */
+function filterVariantForReducedMotion(variant, options) {
+    const { preserveOpacity = true, preserveColors = true } = options;
+    const filtered = {};
+    for (const [key, value] of Object.entries(variant)) {
+        const isOpacityProperty = key === "opacity";
+        const isColorProperty = key === "color" || key === "backgroundColor" || key === "borderColor" || key === "fill" || key === "stroke";
+        if ((preserveOpacity && isOpacityProperty) || (preserveColors && isColorProperty)) {
+            filtered[key] = value;
+        }
+    }
+    return filtered;
+}
+/**
+ * Wraps Motion props to respect the user's reduced motion preference.
+ *
+ * @ai-hint This function transforms Motion component props to be accessibility-friendly.
+ * When reduced motion is preferred, it either disables animations or preserves
+ * only safe properties (like opacity) based on the options provided.
+ *
+ * @param props - The original Motion props
+ * @param prefersReducedMotion - Whether reduced motion is preferred
+ * @param options - Options for customizing reduced motion behavior
+ * @returns Transformed props that respect reduced motion preference
+ *
+ * @example
+ * ```tsx
+ * function AccessibleMotionDiv({ children }: { children: React.ReactNode }) {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     const baseProps: MotionProps = {
+ *         initial: { x: -50, opacity: 0 },
+ *         animate: { x: 0, opacity: 1 },
+ *         transition: { duration: 0.5 },
+ *     };
+ *
+ *     const accessibleProps = createReducedMotionProps(
+ *         baseProps,
+ *         prefersReducedMotion
+ *     );
+ *
+ *     return <motion.div {...accessibleProps}>{children}</motion.div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Preserve opacity transitions in reduced motion mode
+ * function FadeSlideComponent() {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     const props = createReducedMotionProps(
+ *         {
+ *             initial: { y: 20, opacity: 0 },
+ *             animate: { y: 0, opacity: 1 },
+ *             transition: { duration: 0.3 },
+ *         },
+ *         prefersReducedMotion,
+ *         { preserveOpacity: true }
+ *     );
+ *
+ *     // In reduced motion: only opacity animates, y is instant
+ *     return <motion.div {...props}>Content</motion.div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom reduced transition
+ * function CustomReducedMotion() {
+ *     const prefersReducedMotion = useReducedMotion();
+ *
+ *     const props = createReducedMotionProps(
+ *         {
+ *             animate: { scale: 1.1 },
+ *             transition: { duration: 0.5 },
+ *         },
+ *         prefersReducedMotion,
+ *         {
+ *             reducedTransition: { duration: 0.1, ease: "linear" },
+ *         }
+ *     );
+ *
+ *     return <motion.button {...props}>Hover me</motion.button>;
+ * }
+ * ```
+ */
+export function createReducedMotionProps(props, prefersReducedMotion, options = {}) {
+    // If reduced motion is not preferred, return props as-is
+    if (!prefersReducedMotion) {
+        return props;
+    }
+    const { preserveOpacity = true, preserveColors = true, reducedTransition } = options;
+    // Use provided reduced transition or default to instant
+    const transition = reducedTransition ?? INSTANT_TRANSITION;
+    // Helper to process variant-like objects
+    const processVariant = (variant) => {
+        if (variant === undefined || typeof variant === "string" || typeof variant === "boolean") {
+            return variant;
+        }
+        return filterVariantForReducedMotion(variant, { preserveOpacity, preserveColors });
+    };
+    // Helper to process variants object
+    const processVariants = (variants) => {
+        if (!variants) {
+            return undefined;
+        }
+        const processed = {};
+        for (const [key, variant] of Object.entries(variants)) {
+            processed[key] = filterVariantForReducedMotion(variant, { preserveOpacity, preserveColors });
+        }
+        return processed;
+    };
+    // Process animate/exit/whileInView - these don't accept boolean
+    const processNonBooleanVariant = (variant) => {
+        if (variant === undefined || typeof variant === "string") {
+            return variant;
+        }
+        return filterVariantForReducedMotion(variant, { preserveOpacity, preserveColors });
+    };
+    return {
+        ...props,
+        initial: processVariant(props.initial),
+        animate: processNonBooleanVariant(props.animate),
+        exit: processNonBooleanVariant(props.exit),
+        variants: processVariants(props.variants),
+        transition,
+        // Disable hover/tap/focus animations in reduced motion mode
+        // as they often involve movement
+        whileHover: undefined,
+        whileTap: undefined,
+        whileFocus: undefined,
+        whileDrag: undefined,
+        whileInView: processNonBooleanVariant(props.whileInView),
+    };
+}
+/**
+ * Checks if reduced motion is preferred (non-reactive, for one-time checks).
+ *
+ * @ai-hint Use this function for one-time checks outside of React components.
+ * For reactive behavior within components, prefer the `useReducedMotion` hook.
+ *
+ * @returns `true` if reduced motion is preferred, `false` otherwise (including SSR)
+ *
+ * @example
+ * ```ts
+ * // In a utility function
+ * function getAnimationDuration(baseDuration: number): number {
+ *     if (checkReducedMotion()) {
+ *         return 0;
+ *     }
+ *     return baseDuration;
+ * }
+ * ```
+ */
+export function checkReducedMotion() {
+    if (typeof window === "undefined") {
+        return false;
+    }
+    return window.matchMedia(REDUCED_MOTION_QUERY).matches;
+}
+//# sourceMappingURL=reduced-motion.js.map

package/dist/utils/reduced-motion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reduced-motion.js","sourceRoot":"","sources":["../../src/utils/reduced-motion.ts"],"names":[],"mappings":"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"}

package/dist/utils/select-preset.d.ts

@@ -0,0 +1,186 @@
+/**
+ * AI-Driven Preset Selection
+ *
+ * Utilities for intelligently selecting animation presets based on
+ * context, use case, and preferences. Designed to be used by AI tools
+ * for automatic animation selection.
+ *
+ * @packageDocumentation
+ */
+import { type ComponentPreset, type ComponentPresetName, type PresetContext, type PresetUseCase } from "../presets/component-presets";
+import type { MotionStyle } from "../presets/motion-styles";
+/**
+ * Criteria for selecting a preset.
+ */
+export interface SelectionCriteria {
+    /** Primary use case for the animation */
+    useCase?: PresetUseCase;
+    /** Context where the animation will be used */
+    context?: PresetContext;
+    /** Preferred motion style */
+    style?: MotionStyle;
+    /** Maximum intensity level (1-5) */
+    maxIntensity?: number;
+    /** Minimum intensity level (1-5) */
+    minIntensity?: number;
+    /** Whether movement is desired */
+    preferMovement?: boolean;
+    /** Preferred direction of movement */
+    direction?: "up" | "down" | "left" | "right" | "in" | "out";
+    /** Whether to prioritize accessibility */
+    prioritizeAccessibility?: boolean;
+}
+/**
+ * Result of preset selection with reasoning.
+ */
+export interface SelectionResult {
+    /** The selected preset */
+    preset: ComponentPreset;
+    /** Name of the selected preset */
+    presetName: ComponentPresetName;
+    /** Recommended motion style */
+    style: MotionStyle;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Reasoning for the selection */
+    reasoning: string;
+    /** Alternative presets that could work */
+    alternatives: ComponentPresetName[];
+}
+/**
+ * Preset recommendation for a specific context.
+ */
+export interface PresetRecommendation {
+    /** Recommended preset */
+    preset: ComponentPreset;
+    /** Preset name */
+    name: ComponentPresetName;
+    /** Why this preset is recommended */
+    reason: string;
+    /** Score (0-1) */
+    score: number;
+}
+/**
+ * Selects the best preset based on criteria.
+ *
+ * This function analyzes the given criteria and returns the most
+ * appropriate animation preset along with reasoning.
+ *
+ * @ai-hint Use this function to automatically select animations based on
+ * the component's context and requirements. Pass as much information as
+ * possible for better selection.
+ *
+ * @param criteria - Selection criteria
+ * @returns Selection result with preset and reasoning
+ *
+ * @example
+ * ```ts
+ * const result = selectPreset({
+ *   useCase: "entrance",
+ *   context: "modal",
+ *   prioritizeAccessibility: true,
+ * });
+ *
+ * console.log(result.presetName); // "fadeIn"
+ * console.log(result.reasoning); // "Selected 'Fade In' (95% match): ..."
+ * ```
+ *
+ * @example
+ * ```ts
+ * // For a hero section with bold animation
+ * const result = selectPreset({
+ *   useCase: "entrance",
+ *   context: "hero",
+ *   preferMovement: true,
+ *   direction: "up",
+ * });
+ *
+ * console.log(result.presetName); // "slideUpScale"
+ * console.log(result.style); // "bold"
+ * ```
+ */
+export declare function selectPreset(criteria: SelectionCriteria): SelectionResult;
+/**
+ * Gets recommendations for a specific context.
+ *
+ * Returns multiple preset options ranked by suitability.
+ *
+ * @param context - The UI context
+ * @param options - Additional filtering options
+ * @returns Array of recommendations
+ *
+ * @example
+ * ```ts
+ * const recommendations = getRecommendations("modal");
+ * // Returns: [
+ * //   { preset: scale, name: "scale", reason: "...", score: 0.9 },
+ * //   { preset: fadeIn, name: "fadeIn", reason: "...", score: 0.8 },
+ * //   ...
+ * // ]
+ * ```
+ */
+export declare function getRecommendations(context: PresetContext, options?: {
+    maxResults?: number;
+    minScore?: number;
+}): PresetRecommendation[];
+/**
+ * Gets the default preset for a context.
+ *
+ * Quick helper for getting a sensible default animation.
+ *
+ * @param context - The UI context
+ * @returns The default preset for that context
+ *
+ * @example
+ * ```ts
+ * const modalPreset = getDefaultPreset("modal");
+ * // Returns: scale preset
+ *
+ * const tooltipPreset = getDefaultPreset("tooltip");
+ * // Returns: fadeIn preset
+ * ```
+ */
+export declare function getDefaultPreset(context: PresetContext): ComponentPreset;
+/**
+ * Suggests animation combinations for a component.
+ *
+ * Returns entrance, exit, and interaction animations that work together.
+ *
+ * @param context - The UI context
+ * @param style - Preferred motion style
+ * @returns Object with suggested animations
+ *
+ * @example
+ * ```ts
+ * const suggestions = suggestAnimations("card", "standard");
+ * // Returns: {
+ * //   entrance: slideUp,
+ * //   exit: fadeOut,
+ * //   interaction: cardHover (from micro-interactions)
+ * // }
+ * ```
+ */
+export declare function suggestAnimations(context: PresetContext, style?: MotionStyle): {
+    entrance: ComponentPreset;
+    entranceName: ComponentPresetName;
+    exit: ComponentPreset;
+    exitName: ComponentPresetName;
+    style: MotionStyle;
+};
+/**
+ * Gets all available preset names.
+ */
+export declare function getAllPresetNames(): ComponentPresetName[];
+/**
+ * Gets all available contexts.
+ */
+export declare function getAllContexts(): PresetContext[];
+/**
+ * Gets all available use cases.
+ */
+export declare function getAllUseCases(): PresetUseCase[];
+/**
+ * Gets preset metadata by name.
+ */
+export declare function getPresetMetadata(name: ComponentPresetName): import("..").PresetMetadata;
+//# sourceMappingURL=select-preset.d.ts.map

package/dist/utils/select-preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-preset.d.ts","sourceRoot":"","sources":["../../src/utils/select-preset.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EACH,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAGxB,KAAK,aAAa,EAClB,KAAK,aAAa,EACrB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAM5D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,yCAAyC;IACzC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,CAAC;IAC5D,0CAA0C;IAC1C,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,0BAA0B;IAC1B,MAAM,EAAE,eAAe,CAAC;IACxB,kCAAkC;IAClC,UAAU,EAAE,mBAAmB,CAAC;IAChC,+BAA+B;IAC/B,KAAK,EAAE,WAAW,CAAC;IACnB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,YAAY,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,yBAAyB;IACzB,MAAM,EAAE,eAAe,CAAC;IACxB,kBAAkB;IAClB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;CACjB;AA8HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,eAAe,CAiCzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE;IACL,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAChB,GACP,oBAAoB,EAAE,CAyBxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAgBxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,aAAa,EACtB,KAAK,GAAE,WAAwB,GAChC;IACC,QAAQ,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,mBAAmB,CAAC;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,WAAW,CAAC;CACtB,CAsBA;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,EAAE,CAEzD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,aAAa,EAAE,CAEhD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,aAAa,EAAE,CAEhD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,+BAE1D"}