@enact-ui/animate 0.1.0 → 0.2.0

package/dist/presets/stagger-presets.d.ts

@@ -0,0 +1,378 @@
+/**
+ * Stagger Animation Presets
+ *
+ * Defines stagger animation presets for animating lists and grids of items.
+ * These presets control the timing and order in which child elements animate,
+ * creating visually appealing sequential or patterned animations.
+ *
+ * Each preset includes:
+ * - A delay calculation function based on item index
+ * - Container variants for orchestrating child animations
+ * - Item variants for individual element animations
+ * - Metadata for documentation and AI tool selection
+ *
+ * @packageDocumentation
+ *
+ * @example Basic list animation with sequential stagger
+ * ```tsx
+ * import { motion } from "motion/react";
+ * import { staggerSequential } from "@enact-ui/animate";
+ *
+ * function AnimatedList({ items }) {
+ *   const { getContainerVariants, getItemVariants } = staggerSequential;
+ *
+ *   return (
+ *     <motion.ul
+ *       variants={getContainerVariants("standard")}
+ *       initial="hidden"
+ *       animate="visible"
+ *     >
+ *       {items.map((item, index) => (
+ *         <motion.li key={item.id} variants={getItemVariants("standard")}>
+ *           {item.content}
+ *         </motion.li>
+ *       ))}
+ *     </motion.ul>
+ *   );
+ * }
+ * ```
+ *
+ * @example Grid animation with diagonal wave
+ * ```tsx
+ * import { staggerGrid } from "@enact-ui/animate";
+ *
+ * function AnimatedGrid({ items, columns = 4 }) {
+ *   return (
+ *     <motion.div
+ *       className="grid grid-cols-4"
+ *       variants={staggerGrid.getContainerVariants("bold")}
+ *       initial="hidden"
+ *       animate="visible"
+ *     >
+ *       {items.map((item, index) => (
+ *         <motion.div
+ *           key={item.id}
+ *           variants={staggerGrid.getItemVariants("bold")}
+ *           custom={{ index, columns }}
+ *         >
+ *           {item.content}
+ *         </motion.div>
+ *       ))}
+ *     </motion.div>
+ *   );
+ * }
+ * ```
+ */
+import type { MotionStyle } from "./motion-styles";
+/**
+ * Container animation variants for stagger orchestration.
+ * The container coordinates when children should animate.
+ */
+export interface ContainerVariants {
+    /** Hidden state before animation starts */
+    hidden: Record<string, unknown>;
+    /** Visible state with stagger children configuration */
+    visible: Record<string, unknown>;
+}
+/**
+ * Item animation variants for individual elements.
+ * Applied to each child element in the staggered animation.
+ */
+export interface ItemVariants {
+    /** Hidden state (typically opacity: 0, transform offset) */
+    hidden: Record<string, unknown>;
+    /** Visible state (typically opacity: 1, transform reset) */
+    visible: Record<string, unknown>;
+}
+/**
+ * Complete stagger preset configuration.
+ *
+ * @ai-hint Stagger presets control how lists and grids of items animate.
+ * Choose based on the visual effect needed: sequential for simple lists,
+ * center for focus effects, grid for 2D layouts, wave for organic feels.
+ */
+export interface StaggerPreset {
+    /** Display name of the stagger preset */
+    name: string;
+    /** Description of the animation effect */
+    description: string;
+    /** Recommended use cases for this preset */
+    useCase: string[];
+    /**
+     * Calculates the delay for a specific item.
+     *
+     * @param index - The item's index in the list (0-based)
+     * @param total - Total number of items in the list
+     * @param style - The motion style to use for timing
+     * @returns Delay in seconds before this item animates
+     */
+    getDelay: (index: number, total: number, style: MotionStyle) => number;
+    /**
+     * Gets container variants for Motion library.
+     *
+     * @param style - The motion style for timing configuration
+     * @returns Container variants with stagger configuration
+     */
+    getContainerVariants: (style: MotionStyle) => ContainerVariants;
+    /**
+     * Gets item variants for Motion library.
+     *
+     * @param style - The motion style for animation configuration
+     * @returns Item variants for individual elements
+     */
+    getItemVariants: (style: MotionStyle) => ItemVariants;
+}
+/**
+ * Sequential Stagger - Items animate one after another from top to bottom.
+ *
+ * The most common stagger pattern where items appear in their natural order.
+ * Creates a clean, predictable animation flow that guides the eye downward.
+ *
+ * @ai-hint Use staggerSequential for standard lists, menus, and vertical
+ * content where you want items to appear in reading order (top to bottom).
+ *
+ * @example
+ * ```tsx
+ * import { staggerSequential } from "@enact-ui/animate";
+ *
+ * // Navigation menu items
+ * <motion.nav variants={staggerSequential.getContainerVariants("standard")}>
+ *   {menuItems.map((item) => (
+ *     <motion.a variants={staggerSequential.getItemVariants("standard")}>
+ *       {item.label}
+ *     </motion.a>
+ *   ))}
+ * </motion.nav>
+ * ```
+ */
+export declare const staggerSequential: StaggerPreset;
+/**
+ * Reverse Stagger - Items animate from bottom to top.
+ *
+ * Creates an upward flow effect, useful for content that should draw
+ * attention upward or create a "rising" visual metaphor.
+ *
+ * @ai-hint Use staggerReverse for toast notifications, chat messages
+ * (newest first), or any content where bottom-to-top flow makes sense.
+ *
+ * @example
+ * ```tsx
+ * import { staggerReverse } from "@enact-ui/animate";
+ *
+ * // Toast notification stack
+ * <motion.div variants={staggerReverse.getContainerVariants("standard")}>
+ *   {toasts.map((toast) => (
+ *     <motion.div variants={staggerReverse.getItemVariants("standard")}>
+ *       {toast.message}
+ *     </motion.div>
+ *   ))}
+ * </motion.div>
+ * ```
+ */
+export declare const staggerReverse: StaggerPreset;
+/**
+ * Center Stagger - Items animate from center outward.
+ *
+ * Creates a radial expansion effect where the middle item(s) appear first,
+ * then items progressively reveal outward. Great for focus-based UIs.
+ *
+ * @ai-hint Use staggerCenter for hero sections, featured content, or any
+ * UI where you want to draw attention to the center element first.
+ *
+ * @example
+ * ```tsx
+ * import { staggerCenter } from "@enact-ui/animate";
+ *
+ * // Feature cards with center focus
+ * <motion.div
+ *   className="flex gap-4"
+ *   variants={staggerCenter.getContainerVariants("bold")}
+ * >
+ *   {features.map((feature, i) => (
+ *     <motion.div
+ *       variants={staggerCenter.getItemVariants("bold")}
+ *       custom={{ index: i, total: features.length }}
+ *     >
+ *       {feature.title}
+ *     </motion.div>
+ *   ))}
+ * </motion.div>
+ * ```
+ */
+export declare const staggerCenter: StaggerPreset;
+/**
+ * Random Stagger - Items animate in random order.
+ *
+ * Creates an organic, unpredictable animation pattern. Each render
+ * produces the same "random" order using a seeded approach based on index.
+ *
+ * @ai-hint Use staggerRandom for photo galleries, tag clouds, or creative
+ * UIs where a playful, organic feel is desired. Avoid for data-heavy UIs.
+ *
+ * @example
+ * ```tsx
+ * import { staggerRandom } from "@enact-ui/animate";
+ *
+ * // Photo gallery with organic reveal
+ * <motion.div
+ *   className="grid grid-cols-3"
+ *   variants={staggerRandom.getContainerVariants("playful")}
+ * >
+ *   {photos.map((photo) => (
+ *     <motion.img
+ *       src={photo.url}
+ *       variants={staggerRandom.getItemVariants("playful")}
+ *     />
+ *   ))}
+ * </motion.div>
+ * ```
+ */
+export declare const staggerRandom: StaggerPreset;
+/**
+ * Grid Stagger - 2D diagonal wave pattern for grid layouts.
+ *
+ * Creates a diagonal wave effect where items animate based on their
+ * row + column position. Perfect for image grids and card layouts.
+ *
+ * @ai-hint Use staggerGrid for 2D layouts like image galleries, card grids,
+ * or dashboards. Pass columns count for accurate diagonal calculation.
+ *
+ * @example
+ * ```tsx
+ * import { staggerGrid } from "@enact-ui/animate";
+ *
+ * const COLUMNS = 4;
+ *
+ * // Image grid with diagonal wave
+ * <motion.div
+ *   className="grid grid-cols-4"
+ *   variants={staggerGrid.getContainerVariants("standard")}
+ * >
+ *   {images.map((image, index) => (
+ *     <motion.div
+ *       key={image.id}
+ *       variants={staggerGrid.getItemVariants("standard")}
+ *       style={{
+ *         // Custom delay based on grid position
+ *         transitionDelay: `${staggerGrid.getDelay(
+ *           index,
+ *           images.length,
+ *           "standard"
+ *         )}s`,
+ *       }}
+ *     >
+ *       <img src={image.url} alt={image.alt} />
+ *     </motion.div>
+ *   ))}
+ * </motion.div>
+ * ```
+ */
+export declare const staggerGrid: StaggerPreset;
+/**
+ * Wave Stagger - Sine-wave based stagger pattern.
+ *
+ * Creates an organic wave effect using sinusoidal timing. Items
+ * animate in a flowing pattern that feels natural and rhythmic.
+ *
+ * @ai-hint Use staggerWave for music/audio UIs, timeline visualizations,
+ * or any interface that benefits from organic, flowing motion.
+ *
+ * @example
+ * ```tsx
+ * import { staggerWave } from "@enact-ui/animate";
+ *
+ * // Audio equalizer bars
+ * <motion.div
+ *   className="flex items-end gap-1"
+ *   variants={staggerWave.getContainerVariants("playful")}
+ * >
+ *   {bars.map((bar, index) => (
+ *     <motion.div
+ *       key={index}
+ *       className="bg-primary"
+ *       style={{ height: bar.height }}
+ *       variants={staggerWave.getItemVariants("playful")}
+ *     />
+ *   ))}
+ * </motion.div>
+ * ```
+ */
+export declare const staggerWave: StaggerPreset;
+/**
+ * Cascade Stagger - Fast initial items, progressively slower.
+ *
+ * Creates an accelerating cascade effect where early items appear quickly
+ * and later items take longer. Great for emphasizing quantity.
+ *
+ * @ai-hint Use staggerCascade for long lists, data tables, or anywhere
+ * you want to convey "there's more" by slowing down the reveal.
+ *
+ * @example
+ * ```tsx
+ * import { staggerCascade } from "@enact-ui/animate";
+ *
+ * // Long data table rows
+ * <motion.tbody variants={staggerCascade.getContainerVariants("subtle")}>
+ *   {rows.map((row) => (
+ *     <motion.tr
+ *       key={row.id}
+ *       variants={staggerCascade.getItemVariants("subtle")}
+ *     >
+ *       {row.cells.map((cell) => (
+ *         <td key={cell.id}>{cell.value}</td>
+ *       ))}
+ *     </motion.tr>
+ *   ))}
+ * </motion.tbody>
+ * ```
+ */
+export declare const staggerCascade: StaggerPreset;
+/**
+ * All stagger presets indexed by name.
+ *
+ * @ai-hint Use this map to dynamically select stagger presets based on
+ * user preferences or component configuration.
+ */
+export declare const staggerPresets: Record<string, StaggerPreset>;
+/**
+ * Stagger preset type identifier.
+ */
+export type StaggerPresetType = keyof typeof staggerPresets;
+/**
+ * Gets a stagger preset by name.
+ *
+ * @param name - The preset name to retrieve
+ * @returns The stagger preset configuration
+ * @throws Error if preset name is not found
+ *
+ * @example
+ * ```ts
+ * const preset = getStaggerPreset("center");
+ * const containerVariants = preset.getContainerVariants("standard");
+ * ```
+ */
+export declare function getStaggerPreset(name: StaggerPresetType): StaggerPreset;
+/**
+ * Creates custom delay values for a list of items using a specific preset.
+ *
+ * Useful when you need to calculate delays outside of Motion's variants
+ * system, such as for CSS animations or manual timing control.
+ *
+ * @param preset - The stagger preset to use
+ * @param total - Total number of items
+ * @param style - The motion style for timing
+ * @returns Array of delay values in seconds for each item
+ *
+ * @example
+ * ```ts
+ * const delays = calculateStaggerDelays("cascade", 10, "standard");
+ * // Returns: [0, 0.05, 0.071, 0.087, 0.1, ...]
+ *
+ * // Use with CSS custom properties
+ * items.forEach((item, index) => {
+ *   item.style.setProperty("--delay", `${delays[index]}s`);
+ * });
+ * ```
+ */
+export declare function calculateStaggerDelays(preset: StaggerPresetType, total: number, style: MotionStyle): number[];
+//# sourceMappingURL=stagger-presets.d.ts.map

package/dist/presets/stagger-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagger-presets.d.ts","sourceRoot":"","sources":["../../src/presets/stagger-presets.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGnD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC9B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;OAOG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC;IACvE;;;;;OAKG;IACH,oBAAoB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,iBAAiB,CAAC;IAChE;;;;;OAKG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,YAAY,CAAC;CACzD;AA6BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,iBAAiB,EAAE,aA0B/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,cAAc,EAAE,aA+C5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,aAAa,EAAE,aA+C3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,aAAa,EAAE,aAkD3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,WAAW,EAAE,aAmDzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,WAAW,EAAE,aAoDzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,cAAc,EAAE,aAiD5B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAQxD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAMvE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAG7G"}