@enact-ui/animate 0.1.0 → 0.2.0

package/dist/utils/select-preset.js

@@ -0,0 +1,320 @@
+// Copyright (c) 2026 Amsterdam Data Labs
+/**
+ * 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 { componentPresets, getPresetsByContext, } from "../presets/component-presets";
+// =============================================================================
+// Selection Logic
+// =============================================================================
+/**
+ * Calculates a match score between criteria and a preset.
+ */
+function calculateMatchScore(preset, criteria) {
+    let score = 0;
+    let factors = 0;
+    // Use case match
+    if (criteria.useCase) {
+        factors++;
+        if (preset.metadata.useCase.includes(criteria.useCase)) {
+            score += 1;
+        }
+    }
+    // Context match
+    if (criteria.context) {
+        factors++;
+        if (preset.metadata.context.includes(criteria.context)) {
+            score += 1;
+        }
+    }
+    // Intensity range
+    if (criteria.maxIntensity !== undefined) {
+        factors++;
+        if (preset.metadata.intensity <= criteria.maxIntensity) {
+            score += 1;
+        }
+    }
+    if (criteria.minIntensity !== undefined) {
+        factors++;
+        if (preset.metadata.intensity >= criteria.minIntensity) {
+            score += 1;
+        }
+    }
+    // Movement preference
+    if (criteria.preferMovement !== undefined) {
+        factors++;
+        if (preset.metadata.hasMovement === criteria.preferMovement) {
+            score += 1;
+        }
+    }
+    // Direction match
+    if (criteria.direction && preset.metadata.direction) {
+        factors++;
+        if (preset.metadata.direction === criteria.direction) {
+            score += 1;
+        }
+    }
+    // Accessibility preference (lower intensity = more accessible)
+    if (criteria.prioritizeAccessibility) {
+        factors++;
+        // Favor lower intensity presets
+        score += (5 - preset.metadata.intensity) / 5;
+    }
+    return factors > 0 ? score / factors : 0;
+}
+/**
+ * Determines the best motion style based on criteria.
+ */
+function determineStyle(criteria) {
+    if (criteria.style) {
+        return criteria.style;
+    }
+    if (criteria.prioritizeAccessibility) {
+        return "subtle";
+    }
+    if (criteria.context === "hero" || criteria.context === "page") {
+        return "bold";
+    }
+    if (criteria.context === "tooltip" || criteria.context === "dropdown") {
+        return "subtle";
+    }
+    return "standard";
+}
+/**
+ * Generates reasoning for a selection.
+ */
+function generateReasoning(preset, criteria, score) {
+    const reasons = [];
+    if (criteria.useCase && preset.metadata.useCase.includes(criteria.useCase)) {
+        reasons.push(`matches use case "${criteria.useCase}"`);
+    }
+    if (criteria.context && preset.metadata.context.includes(criteria.context)) {
+        reasons.push(`suitable for "${criteria.context}" context`);
+    }
+    if (criteria.direction && preset.metadata.direction === criteria.direction) {
+        reasons.push(`provides "${criteria.direction}" movement`);
+    }
+    if (criteria.prioritizeAccessibility && preset.metadata.intensity <= 2) {
+        reasons.push("has low intensity for accessibility");
+    }
+    if (reasons.length === 0) {
+        reasons.push("general-purpose animation");
+    }
+    return `Selected "${preset.metadata.name}" (${Math.round(score * 100)}% match): ${reasons.join(", ")}.`;
+}
+// =============================================================================
+// Main Selection Functions
+// =============================================================================
+/**
+ * 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 function selectPreset(criteria) {
+    const allPresets = Object.entries(componentPresets);
+    // Calculate scores for all presets
+    const scoredPresets = allPresets.map(([name, preset]) => ({
+        name,
+        preset,
+        score: calculateMatchScore(preset, criteria),
+    }));
+    // Sort by score descending
+    scoredPresets.sort((a, b) => b.score - a.score);
+    const best = scoredPresets[0];
+    const style = determineStyle(criteria);
+    if (!best) {
+        throw new Error("selectPreset: no presets available; cannot select a preset.");
+    }
+    const alternatives = scoredPresets
+        .slice(1, 4)
+        .filter((p) => p.score > 0.3)
+        .map((p) => p.name);
+    return {
+        preset: best.preset,
+        presetName: best.name,
+        style,
+        confidence: best.score,
+        reasoning: generateReasoning(best.preset, criteria, best.score),
+        alternatives,
+    };
+}
+/**
+ * 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 function getRecommendations(context, options = {}) {
+    const { maxResults = 5, minScore = 0.3 } = options;
+    const contextPresets = getPresetsByContext(context);
+    const recommendations = contextPresets.map((preset) => {
+        const name = Object.entries(componentPresets).find(([_, p]) => p === preset)?.[0];
+        // Score based on how well the preset fits the context
+        const contextFit = preset.metadata.context.indexOf(context) === 0 ? 1 : 0.7;
+        const intensityFit = 1 - Math.abs(preset.metadata.intensity - 3) / 4;
+        const score = (contextFit + intensityFit) / 2;
+        return {
+            preset,
+            name,
+            reason: `${preset.metadata.description}. Ideal for ${preset.metadata.context.slice(0, 2).join(", ")}.`,
+            score,
+        };
+    });
+    return recommendations
+        .filter((r) => r.score >= minScore)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}
+/**
+ * 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 function getDefaultPreset(context) {
+    // Define sensible defaults for each context
+    const defaults = {
+        modal: "scale",
+        dropdown: "slideDown",
+        tooltip: "fadeIn",
+        drawer: "slideRight",
+        card: "fadeIn",
+        "list-item": "slideUp",
+        notification: "slideRight",
+        page: "fadeIn",
+        section: "slideUp",
+        hero: "slideUpScale",
+    };
+    return componentPresets[defaults[context]];
+}
+/**
+ * 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 function suggestAnimations(context, style = "standard") {
+    // Get the best entrance animation
+    const entranceResult = selectPreset({
+        useCase: "entrance",
+        context,
+        style,
+    });
+    // Get a matching exit animation
+    const exitResult = selectPreset({
+        useCase: "exit",
+        context,
+        style,
+    });
+    return {
+        entrance: entranceResult.preset,
+        entranceName: entranceResult.presetName,
+        exit: exitResult.preset,
+        exitName: exitResult.presetName,
+        style,
+    };
+}
+// =============================================================================
+// Preset Metadata Utilities
+// =============================================================================
+/**
+ * Gets all available preset names.
+ */
+export function getAllPresetNames() {
+    return Object.keys(componentPresets);
+}
+/**
+ * Gets all available contexts.
+ */
+export function getAllContexts() {
+    return ["modal", "dropdown", "tooltip", "drawer", "card", "list-item", "notification", "page", "section", "hero"];
+}
+/**
+ * Gets all available use cases.
+ */
+export function getAllUseCases() {
+    return ["entrance", "exit", "transition", "emphasis", "reveal"];
+}
+/**
+ * Gets preset metadata by name.
+ */
+export function getPresetMetadata(name) {
+    return componentPresets[name].metadata;
+}
+//# sourceMappingURL=select-preset.js.map

package/dist/utils/select-preset.js.map

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

package/dist/utils/spring-configs.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Spring configuration presets for Motion library animations.
+ *
+ * @ai-hint This module provides pre-configured spring physics parameters for
+ * smooth, natural-feeling animations. Springs are preferred over duration-based
+ * animations for interactive UI elements as they respond naturally to interruption.
+ *
+ * @example
+ * ```tsx
+ * import { springGentle, springSnappy, createSpring } from './spring-configs';
+ *
+ * // Use a preset
+ * <motion.div animate={{ x: 100 }} transition={springGentle} />
+ *
+ * // Create custom spring
+ * const customSpring = createSpring(300, 25, 0.8);
+ * ```
+ */
+/**
+ * Configuration object for spring-based animations.
+ *
+ * @ai-hint SpringTransition defines physics-based animation parameters.
+ * Higher stiffness = faster movement, higher damping = less oscillation,
+ * higher mass = more inertia and slower response.
+ */
+export interface SpringTransition {
+    /** Animation type identifier */
+    readonly type: "spring";
+    /**
+     * Spring stiffness coefficient.
+     * Higher values create faster, more aggressive animations.
+     * @default 100
+     */
+    readonly stiffness: number;
+    /**
+     * Damping coefficient to reduce oscillation.
+     * Higher values reduce bounciness.
+     * @default 10
+     */
+    readonly damping: number;
+    /**
+     * Mass of the animated object.
+     * Higher values create more inertia.
+     * @default 1
+     */
+    readonly mass: number;
+}
+/**
+ * Parameters for creating a custom spring configuration.
+ */
+export interface SpringParams {
+    /** Spring stiffness (tension) */
+    stiffness: number;
+    /** Damping (friction) */
+    damping: number;
+    /** Mass of the object */
+    mass: number;
+}
+/**
+ * Gentle spring with smooth, relaxed motion.
+ *
+ * @ai-hint Use for subtle transitions, fades, and non-interactive elements.
+ * Creates a calm, professional feel without drawing attention.
+ *
+ * @example
+ * ```tsx
+ * <motion.div
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ *   transition={springGentle}
+ * />
+ * ```
+ */
+export declare const springGentle: SpringTransition;
+/**
+ * Snappy spring with quick, responsive motion.
+ *
+ * @ai-hint Use for buttons, toggles, and interactive elements that need
+ * immediate feedback. Feels responsive without being jarring.
+ *
+ * @example
+ * ```tsx
+ * <motion.button
+ *   whileHover={{ scale: 1.05 }}
+ *   whileTap={{ scale: 0.95 }}
+ *   transition={springSnappy}
+ * />
+ * ```
+ */
+export declare const springSnappy: SpringTransition;
+/**
+ * Bouncy spring with playful oscillation.
+ *
+ * @ai-hint Use sparingly for celebratory moments, notifications, or
+ * elements that should draw attention. Too much bounce can feel unpolished.
+ *
+ * @example
+ * ```tsx
+ * <motion.div
+ *   initial={{ scale: 0 }}
+ *   animate={{ scale: 1 }}
+ *   transition={springBouncy}
+ * />
+ * ```
+ */
+export declare const springBouncy: SpringTransition;
+/**
+ * Stiff spring with minimal oscillation and fast settling.
+ *
+ * @ai-hint Use for UI elements that need to feel solid and immediate,
+ * like modals, dropdowns, or navigation. Minimal overshoot.
+ *
+ * @example
+ * ```tsx
+ * <motion.nav
+ *   initial={{ x: -300 }}
+ *   animate={{ x: 0 }}
+ *   transition={springStiff}
+ * />
+ * ```
+ */
+export declare const springStiff: SpringTransition;
+/**
+ * Creates a custom spring configuration with specified physics parameters.
+ *
+ * @ai-hint Use this factory when presets don't match your needs. Start with
+ * a preset and adjust from there. Common adjustments:
+ * - Increase stiffness for faster animations
+ * - Increase damping to reduce bounce
+ * - Decrease mass for quicker response
+ *
+ * @param stiffness - Spring stiffness (tension). Range: 100-1000. Higher = faster.
+ * @param damping - Damping coefficient (friction). Range: 10-50. Higher = less bounce.
+ * @param mass - Mass of the object. Range: 0.5-2. Higher = more inertia.
+ * @returns A SpringTransition configuration object.
+ *
+ * @example
+ * ```tsx
+ * // Create a very snappy spring for micro-interactions
+ * const microSpring = createSpring(600, 40, 0.5);
+ *
+ * // Create a heavy, slow spring for large elements
+ * const heavySpring = createSpring(150, 25, 1.5);
+ *
+ * <motion.div transition={createSpring(350, 28, 0.9)} />
+ * ```
+ */
+export declare function createSpring(stiffness: number, damping: number, mass: number): SpringTransition;
+/**
+ * Creates a spring configuration from a params object.
+ *
+ * @ai-hint Alternative factory that accepts an object, useful when
+ * spring parameters come from configuration or theme.
+ *
+ * @param params - Spring parameters object
+ * @returns A SpringTransition configuration object.
+ *
+ * @example
+ * ```tsx
+ * const themeSpring = { stiffness: 250, damping: 22, mass: 1 };
+ * const spring = createSpringFromParams(themeSpring);
+ * ```
+ */
+export declare function createSpringFromParams(params: SpringParams): SpringTransition;
+/**
+ * Collection of all spring presets for iteration or dynamic selection.
+ *
+ * @ai-hint Use this map when you need to select springs dynamically
+ * based on user preference or theme configuration.
+ *
+ * @example
+ * ```tsx
+ * const springName = userPreference.animationStyle; // 'gentle' | 'snappy' | etc.
+ * const spring = springPresets[springName];
+ * ```
+ */
+export declare const springPresets: {
+    readonly gentle: SpringTransition;
+    readonly snappy: SpringTransition;
+    readonly bouncy: SpringTransition;
+    readonly stiff: SpringTransition;
+};
+/**
+ * Type representing valid spring preset names.
+ */
+export type SpringPresetName = keyof typeof springPresets;
+//# sourceMappingURL=spring-configs.d.ts.map

package/dist/utils/spring-configs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring-configs.d.ts","sourceRoot":"","sources":["../../src/utils/spring-configs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,gBAKjB,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,gBAKjB,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,gBAKjB,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,EAAE,gBAKhB,CAAC;AAMX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAO/F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAO7E;AAMD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,aAAa,CAAC"}

package/dist/utils/spring-configs.js

@@ -0,0 +1,169 @@
+// Copyright (c) 2026 Amsterdam Data Labs
+// =============================================================================
+// SPRING PRESETS
+// =============================================================================
+/**
+ * Gentle spring with smooth, relaxed motion.
+ *
+ * @ai-hint Use for subtle transitions, fades, and non-interactive elements.
+ * Creates a calm, professional feel without drawing attention.
+ *
+ * @example
+ * ```tsx
+ * <motion.div
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ *   transition={springGentle}
+ * />
+ * ```
+ */
+export const springGentle = {
+    type: "spring",
+    stiffness: 200,
+    damping: 30,
+    mass: 1,
+};
+/**
+ * Snappy spring with quick, responsive motion.
+ *
+ * @ai-hint Use for buttons, toggles, and interactive elements that need
+ * immediate feedback. Feels responsive without being jarring.
+ *
+ * @example
+ * ```tsx
+ * <motion.button
+ *   whileHover={{ scale: 1.05 }}
+ *   whileTap={{ scale: 0.95 }}
+ *   transition={springSnappy}
+ * />
+ * ```
+ */
+export const springSnappy = {
+    type: "spring",
+    stiffness: 400,
+    damping: 30,
+    mass: 0.8,
+};
+/**
+ * Bouncy spring with playful oscillation.
+ *
+ * @ai-hint Use sparingly for celebratory moments, notifications, or
+ * elements that should draw attention. Too much bounce can feel unpolished.
+ *
+ * @example
+ * ```tsx
+ * <motion.div
+ *   initial={{ scale: 0 }}
+ *   animate={{ scale: 1 }}
+ *   transition={springBouncy}
+ * />
+ * ```
+ */
+export const springBouncy = {
+    type: "spring",
+    stiffness: 300,
+    damping: 15,
+    mass: 1,
+};
+/**
+ * Stiff spring with minimal oscillation and fast settling.
+ *
+ * @ai-hint Use for UI elements that need to feel solid and immediate,
+ * like modals, dropdowns, or navigation. Minimal overshoot.
+ *
+ * @example
+ * ```tsx
+ * <motion.nav
+ *   initial={{ x: -300 }}
+ *   animate={{ x: 0 }}
+ *   transition={springStiff}
+ * />
+ * ```
+ */
+export const springStiff = {
+    type: "spring",
+    stiffness: 500,
+    damping: 35,
+    mass: 0.6,
+};
+// =============================================================================
+// SPRING FACTORY
+// =============================================================================
+/**
+ * Creates a custom spring configuration with specified physics parameters.
+ *
+ * @ai-hint Use this factory when presets don't match your needs. Start with
+ * a preset and adjust from there. Common adjustments:
+ * - Increase stiffness for faster animations
+ * - Increase damping to reduce bounce
+ * - Decrease mass for quicker response
+ *
+ * @param stiffness - Spring stiffness (tension). Range: 100-1000. Higher = faster.
+ * @param damping - Damping coefficient (friction). Range: 10-50. Higher = less bounce.
+ * @param mass - Mass of the object. Range: 0.5-2. Higher = more inertia.
+ * @returns A SpringTransition configuration object.
+ *
+ * @example
+ * ```tsx
+ * // Create a very snappy spring for micro-interactions
+ * const microSpring = createSpring(600, 40, 0.5);
+ *
+ * // Create a heavy, slow spring for large elements
+ * const heavySpring = createSpring(150, 25, 1.5);
+ *
+ * <motion.div transition={createSpring(350, 28, 0.9)} />
+ * ```
+ */
+export function createSpring(stiffness, damping, mass) {
+    return {
+        type: "spring",
+        stiffness,
+        damping,
+        mass,
+    };
+}
+/**
+ * Creates a spring configuration from a params object.
+ *
+ * @ai-hint Alternative factory that accepts an object, useful when
+ * spring parameters come from configuration or theme.
+ *
+ * @param params - Spring parameters object
+ * @returns A SpringTransition configuration object.
+ *
+ * @example
+ * ```tsx
+ * const themeSpring = { stiffness: 250, damping: 22, mass: 1 };
+ * const spring = createSpringFromParams(themeSpring);
+ * ```
+ */
+export function createSpringFromParams(params) {
+    return {
+        type: "spring",
+        stiffness: params.stiffness,
+        damping: params.damping,
+        mass: params.mass,
+    };
+}
+// =============================================================================
+// PRESET COLLECTIONS
+// =============================================================================
+/**
+ * Collection of all spring presets for iteration or dynamic selection.
+ *
+ * @ai-hint Use this map when you need to select springs dynamically
+ * based on user preference or theme configuration.
+ *
+ * @example
+ * ```tsx
+ * const springName = userPreference.animationStyle; // 'gentle' | 'snappy' | etc.
+ * const spring = springPresets[springName];
+ * ```
+ */
+export const springPresets = {
+    gentle: springGentle,
+    snappy: springSnappy,
+    bouncy: springBouncy,
+    stiff: springStiff,
+};
+//# sourceMappingURL=spring-configs.js.map

package/dist/utils/spring-configs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring-configs.js","sourceRoot":"","sources":["../../src/utils/spring-configs.ts"],"names":[],"mappings":"AAAA,yCAAyC;AA+DzC,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC1C,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,CAAC;CACD,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC1C,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,GAAG;CACH,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAqB;IAC1C,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,CAAC;CACD,CAAC;AAEX;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,WAAW,GAAqB;IACzC,IAAI,EAAE,QAAQ;IACd,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,GAAG;CACH,CAAC;AAEX,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,OAAe,EAAE,IAAY;IACzE,OAAO;QACH,IAAI,EAAE,QAAQ;QACd,SAAS;QACT,OAAO;QACP,IAAI;KACE,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAoB;IACvD,OAAO;QACH,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI;KACX,CAAC;AACf,CAAC;AAED,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,WAAW;CACZ,CAAC"}