@enact-ui/animate 0.1.0 → 0.2.0

package/dist/presets/micro-interactions.d.ts

@@ -0,0 +1,451 @@
+/**
+ * Micro-Interaction Animation Presets
+ *
+ * Provides a collection of reusable micro-interaction animations for common UI patterns.
+ * Each preset adapts to the chosen MotionStyle, respecting user preferences including
+ * reduced motion settings.
+ *
+ * @packageDocumentation
+ */
+import type { MotionStyle } from "./motion-styles";
+/**
+ * Props returned by micro-interaction preset functions.
+ * Compatible with Motion library's component props.
+ */
+export interface MicroInteractionProps {
+    /** Animation values applied on hover */
+    whileHover?: Record<string, unknown>;
+    /** Animation values applied while pressed/tapped */
+    whileTap?: Record<string, unknown>;
+    /** Animation values applied while focused */
+    whileFocus?: Record<string, unknown>;
+    /** Transition configuration for the animation */
+    transition?: Record<string, unknown>;
+    /** Initial animation state */
+    initial?: Record<string, unknown>;
+    /** Target animation state */
+    animate?: Record<string, unknown>;
+}
+/**
+ * Definition for a micro-interaction preset.
+ * Includes metadata for documentation and AI-assisted selection.
+ */
+export interface MicroInteractionPreset {
+    /** Unique identifier for the preset */
+    name: string;
+    /** Human-readable description of the animation effect */
+    description: string;
+    /** Suggested use cases for this animation */
+    useCase: string[];
+    /** Function that generates Motion props based on the motion style */
+    getProps: (style: MotionStyle) => MicroInteractionProps;
+}
+/**
+ * Button Press Micro-Interaction
+ *
+ * Creates a subtle press effect where the element scales down slightly when clicked
+ * and springs back to its original size on release. Provides tactile feedback for
+ * interactive elements.
+ *
+ * @ai-hint Use buttonPress for clickable elements like buttons, cards, or list items
+ * that need tactile feedback. Best for primary actions and interactive controls.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { buttonPress } from "@enact-ui/animate";
+ *
+ * function Button({ children }) {
+ *   const props = buttonPress.getProps("standard");
+ *   return <motion.button {...props}>{children}</motion.button>;
+ * }
+ * ```
+ */
+export declare const buttonPress: MicroInteractionPreset;
+/**
+ * Card Hover Micro-Interaction
+ *
+ * Creates a subtle lift effect with shadow enhancement when hovering over card-like
+ * elements. Provides visual depth and indicates interactivity.
+ *
+ * @ai-hint Use cardHover for cards, tiles, or panels that are clickable or expandable.
+ * Creates a "lifting" effect that suggests the element can be interacted with.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { cardHover } from "@enact-ui/animate";
+ *
+ * function Card({ children }) {
+ *   const props = cardHover.getProps("standard");
+ *   return <motion.article {...props}>{children}</motion.article>;
+ * }
+ * ```
+ */
+export declare const cardHover: MicroInteractionPreset;
+/**
+ * Icon Spin Micro-Interaction
+ *
+ * Performs a full 360-degree rotation, ideal for refresh icons, loading indicators,
+ * or interactive feedback on icon clicks.
+ *
+ * @ai-hint Use iconSpin for refresh buttons, sync icons, or loading states.
+ * Good for indicating an action is in progress or for playful icon interactions.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { iconSpin } from "@enact-ui/animate";
+ *
+ * function RefreshButton() {
+ *   const props = iconSpin.getProps("standard");
+ *   return (
+ *     <motion.button {...props}>
+ *       <RefreshIcon />
+ *     </motion.button>
+ *   );
+ * }
+ * ```
+ */
+export declare const iconSpin: MicroInteractionPreset;
+/**
+ * Pulse Micro-Interaction
+ *
+ * Creates a breathing/pulsing scale animation. Can be used for attention-grabbing
+ * elements, loading states, or to indicate something is active/live.
+ *
+ * @ai-hint Use pulse for notifications, live indicators, or elements needing attention.
+ * The breathing effect draws the eye without being too distracting.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { pulse } from "@enact-ui/animate";
+ *
+ * function LiveIndicator() {
+ *   const props = pulse.getProps("standard");
+ *   return <motion.span {...props} className="live-dot" />;
+ * }
+ * ```
+ */
+export declare const pulse: MicroInteractionPreset;
+/**
+ * Shake Micro-Interaction
+ *
+ * Horizontal shake animation commonly used for error states, invalid input,
+ * or to indicate that an action cannot be completed.
+ *
+ * @ai-hint Use shake for error states, invalid form inputs, or denied actions.
+ * The horizontal movement mimics the "no" head shake gesture.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { shake } from "@enact-ui/animate";
+ *
+ * function FormInput({ error }) {
+ *   const props = error ? shake.getProps("standard") : {};
+ *   return <motion.input {...props} />;
+ * }
+ * ```
+ */
+export declare const shake: MicroInteractionPreset;
+/**
+ * Wiggle Micro-Interaction
+ *
+ * Playful rotation wiggle animation. Great for drawing attention to elements
+ * in a fun, non-intrusive way. Often used in gamified interfaces or
+ * celebratory moments.
+ *
+ * @ai-hint Use wiggle for playful interfaces, gamification, or to draw attention
+ * to elements in a fun way. Works well for icons, badges, or decorative elements.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { wiggle } from "@enact-ui/animate";
+ *
+ * function AchievementBadge() {
+ *   const props = wiggle.getProps("playful");
+ *   return <motion.div {...props}><BadgeIcon /></motion.div>;
+ * }
+ * ```
+ */
+export declare const wiggle: MicroInteractionPreset;
+/**
+ * Heartbeat Micro-Interaction
+ *
+ * Double-pulse heartbeat pattern that creates a realistic heartbeat effect.
+ * Perfect for health apps, like buttons, or emphasizing something "alive".
+ *
+ * @ai-hint Use heartbeat for health/fitness apps, like/love buttons, or to indicate
+ * something is active/alive. The double-pulse mimics a real heartbeat rhythm.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { heartbeat } from "@enact-ui/animate";
+ *
+ * function LikeButton({ isLiked }) {
+ *   const props = isLiked ? heartbeat.getProps("playful") : {};
+ *   return <motion.button {...props}><HeartIcon /></motion.button>;
+ * }
+ * ```
+ */
+export declare const heartbeat: MicroInteractionPreset;
+/**
+ * Rubber Band Micro-Interaction
+ *
+ * Elastic stretch and snap back animation inspired by the classic rubber band effect.
+ * Creates a bouncy, playful feel that's perfect for attention-grabbing elements.
+ *
+ * @ai-hint Use rubberBand for emphasis animations, attention grabbers, or playful
+ * interfaces. The elastic effect creates a memorable, tactile impression.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { rubberBand } from "@enact-ui/animate";
+ *
+ * function BouncyButton({ children }) {
+ *   const props = rubberBand.getProps("playful");
+ *   return <motion.button {...props}>{children}</motion.button>;
+ * }
+ * ```
+ */
+export declare const rubberBand: MicroInteractionPreset;
+/**
+ * Scale Micro-Interaction
+ *
+ * Creates a scale animation effect for selection feedback. The element scales up
+ * briefly when activated, providing satisfying tactile feedback for toggles,
+ * checkboxes, and selection states.
+ *
+ * @ai-hint Use scale for checkboxes, toggles, radio buttons, or any selection
+ * feedback. The scale effect provides clear visual confirmation of state change.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { scale } from "@enact-ui/animate";
+ *
+ * function Checkbox({ isSelected }) {
+ *   const props = isSelected ? scale.getProps("standard") : {};
+ *   return <motion.div {...props}>{isSelected && <Check />}</motion.div>;
+ * }
+ * ```
+ */
+export declare const scale: MicroInteractionPreset;
+/**
+ * Shimmer Micro-Interaction
+ *
+ * Creates a gradient shimmer effect that slides across the element.
+ * Perfect for loading skeletons, progress indicators, or placeholder content.
+ *
+ * @ai-hint Use shimmer for skeleton loading states, progress bars, or placeholder
+ * content. Creates a polished "loading" appearance that indicates content is coming.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { shimmer } from "@enact-ui/animate";
+ *
+ * function SkeletonCard() {
+ *   const props = shimmer.getProps("standard");
+ *   return (
+ *     <motion.div
+ *       {...props}
+ *       className="h-20 bg-gray-200 rounded overflow-hidden relative"
+ *       style={{
+ *         background: "linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)",
+ *         backgroundSize: "200% 100%",
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare const shimmer: MicroInteractionPreset;
+/**
+ * Glow Pulse Micro-Interaction
+ *
+ * Creates a glowing pulse effect using box-shadow. Perfect for AI-generated
+ * content indicators, special items, or elements that need extra emphasis.
+ *
+ * @ai-hint Use glowPulse for AI content indicators, featured items, or elements
+ * needing premium emphasis. The glow effect creates a "magical" or "special" feel.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { glowPulse } from "@enact-ui/animate";
+ *
+ * function AIGeneratedBadge() {
+ *   const props = glowPulse.getProps("standard");
+ *   return <motion.span {...props} className="ai-badge">AI</motion.span>;
+ * }
+ * ```
+ */
+export declare const glowPulse: MicroInteractionPreset;
+/**
+ * Progress Fill Micro-Interaction
+ *
+ * Animates width from 0% to the target value. Perfect for progress bars,
+ * completion indicators, and skill bars.
+ *
+ * Note: This preset returns a function that takes the target percentage
+ * and returns animation props. Use with scaleX transform for best performance.
+ *
+ * @ai-hint Use progressFill for progress bars, skill meters, or completion
+ * indicators. Animates smoothly from 0 to the target percentage.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { progressFill } from "@enact-ui/animate";
+ *
+ * function ProgressBar({ value }: { value: number }) {
+ *   const props = progressFill.getProps("standard");
+ *   return (
+ *     <div className="h-2 bg-gray-200 rounded overflow-hidden">
+ *       <motion.div
+ *         {...props}
+ *         className="h-full bg-blue-500 origin-left"
+ *         style={{ width: `${value}%` }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const progressFill: MicroInteractionPreset;
+/**
+ * All available micro-interaction presets indexed by name.
+ *
+ * @ai-hint Use this collection to iterate over all presets or to access
+ * presets by name dynamically. Each preset adapts to the motion style.
+ *
+ * @example
+ * ```tsx
+ * import { microInteractions } from "@enact-ui/animate";
+ *
+ * // Get a specific preset by name
+ * const pressProps = microInteractions.buttonPress.getProps("standard");
+ *
+ * // List all available presets
+ * Object.keys(microInteractions).forEach(name => {
+ *   console.log(microInteractions[name].description);
+ * });
+ * ```
+ */
+/**
+ * Checkmark Draw Micro-Interaction
+ *
+ * Animated checkmark draw effect, commonly used for success states,
+ * completed tasks, or confirmation feedback.
+ *
+ * @ai-hint Use checkmarkDraw for success confirmations, completed checkboxes,
+ * or any "done" state indication. The drawing animation provides satisfying feedback.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { checkmarkDraw } from "@enact-ui/animate";
+ *
+ * function SuccessIcon() {
+ *   const props = checkmarkDraw.getProps("standard");
+ *   return <motion.svg {...props}><path d="M5 13l4 4L19 7" /></motion.svg>;
+ * }
+ * ```
+ */
+export declare const checkmarkDraw: MicroInteractionPreset;
+/**
+ * Success Flash Micro-Interaction
+ *
+ * Brief highlight flash animation for success feedback. Creates a quick
+ * visual confirmation without being distracting.
+ *
+ * @ai-hint Use successFlash for brief success highlights, toast notifications,
+ * or inline success messages. The flash draws attention without lingering.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { successFlash } from "@enact-ui/animate";
+ *
+ * function SuccessMessage() {
+ *   const props = successFlash.getProps("standard");
+ *   return <motion.div {...props}>Saved!</motion.div>;
+ * }
+ * ```
+ */
+export declare const successFlash: MicroInteractionPreset;
+/**
+ * Badge Pop Micro-Interaction
+ *
+ * Pop animation for badge count changes. Provides satisfying feedback
+ * when numbers update, drawing attention to the change.
+ *
+ * @ai-hint Use badgePop for notification badges, count indicators, or any
+ * numeric value that changes. The pop effect highlights the update.
+ *
+ * @example
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { badgePop } from "@enact-ui/animate";
+ *
+ * function NotificationBadge({ count }) {
+ *   const props = badgePop.getProps("standard");
+ *   return <motion.span {...props} key={count}>{count}</motion.span>;
+ * }
+ * ```
+ */
+export declare const badgePop: MicroInteractionPreset;
+export declare const microInteractions: Record<string, MicroInteractionPreset>;
+/**
+ * Gets a micro-interaction preset by name.
+ *
+ * @param name - The name of the preset to retrieve
+ * @returns The micro-interaction preset, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const preset = getMicroInteraction("buttonPress");
+ * if (preset) {
+ *   const props = preset.getProps("standard");
+ * }
+ * ```
+ */
+export declare function getMicroInteraction(name: string): MicroInteractionPreset | undefined;
+/**
+ * Gets all micro-interaction preset names.
+ *
+ * @returns Array of all preset names
+ *
+ * @example
+ * ```ts
+ * const names = getMicroInteractionNames();
+ * // ["buttonPress", "cardHover", "iconSpin", ...]
+ * ```
+ */
+export declare function getMicroInteractionNames(): string[];
+/**
+ * Finds micro-interaction presets suitable for a given use case.
+ *
+ * @param useCase - The use case to search for (case-insensitive)
+ * @returns Array of presets that match the use case
+ *
+ * @ai-hint Use this function to find appropriate presets based on your component's
+ * purpose. It searches the useCase arrays of all presets for matches.
+ *
+ * @example
+ * ```ts
+ * const errorPresets = findPresetsForUseCase("error");
+ * // Returns [shake] preset since it includes "error states" in its use cases
+ *
+ * const buttonPresets = findPresetsForUseCase("button");
+ * // Returns [buttonPress, rubberBand] presets
+ * ```
+ */
+export declare function findPresetsForUseCase(useCase: string): MicroInteractionPreset[];
+//# sourceMappingURL=micro-interactions.d.ts.map

package/dist/presets/micro-interactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"micro-interactions.d.ts","sourceRoot":"","sources":["../../src/presets/micro-interactions.ts"],"names":[],"mappings":"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"}