@idealyst/theme 1.2.29 → 1.2.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/theme",
-  "version": "1.2.29",
+  "version": "1.2.31",
   "description": "Theming system for Idealyst Framework",
   "readme": "README.md",
   "main": "src/index.ts",
@@ -50,6 +50,12 @@
       "import": "./src/darkTheme.ts",
       "require": "./src/darkTheme.ts",
       "types": "./src/darkTheme.ts"
+    },
+    "./animation": {
+      "native": "./src/animation/index.native.ts",
+      "import": "./src/animation/index.ts",
+      "require": "./src/animation/index.ts",
+      "types": "./src/animation/index.ts"
     }
   },
   "scripts": {
@@ -57,7 +63,7 @@
     "publish:npm": "npm publish"
   },
   "dependencies": {
-    "@idealyst/tooling": "^1.2.3"
+    "@idealyst/tooling": "^1.2.30"
   },
   "peerDependencies": {
     "react-native-unistyles": ">=3.0.0"

package/src/animation/index.native.ts

@@ -0,0 +1,62 @@
+/**
+ * Animation module for @idealyst/theme (Native)
+ *
+ * This module provides animation tokens and utilities for creating
+ * consistent animations across web and native platforms.
+ *
+ * Native-specific exports include Reanimated-compatible utilities.
+ *
+ * @example
+ * // Import tokens
+ * import { durations, easings, presets } from '@idealyst/theme/animation';
+ *
+ * // Import native utilities
+ * import { timingConfig, springConfig, animationConfig } from '@idealyst/theme/animation';
+ *
+ * // Use with Reanimated
+ * import { withTiming, withSpring, Easing } from 'react-native-reanimated';
+ *
+ * const config = timingConfig('normal', 'easeOut');
+ * value.value = withTiming(target, {
+ *   duration: config.duration,
+ *   easing: Easing.bezier(...config.easing),
+ * });
+ */
+
+// Export tokens
+export { durations, easings, presets } from './tokens';
+export type { DurationKey, EasingKey, PresetKey } from './tokens';
+
+// Export types
+export type {
+  Duration,
+  Easing,
+  BezierEasing,
+  SpringConfig,
+  CSSEasing,
+  AnimationConfig,
+  TransitionConfig,
+  Keyframes,
+  KeyframeAnimationConfig,
+  AnimationIterations,
+  AnimationDirection,
+  AnimationFillMode,
+  SpringType,
+  TimingAnimationConfig,
+  PlatformAnimationOptions,
+  GradientAnimation,
+  GradientBorderConfig,
+} from './types';
+
+// Export native utilities
+export {
+  resolveDuration,
+  resolveEasingBezier,
+  isSpringEasing,
+  timingConfig,
+  springConfig,
+  animationConfig,
+  presetConfig,
+  delayMs,
+  sequenceSteps,
+} from './transitions.native';

package/src/animation/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Animation module for @idealyst/theme
+ *
+ * This module provides animation tokens and utilities for creating
+ * consistent animations across web and native platforms.
+ *
+ * @example
+ * // Import tokens
+ * import { durations, easings, presets } from '@idealyst/theme/animation';
+ *
+ * // Import web utilities
+ * import { cssTransition, cssPreset, cssKeyframes } from '@idealyst/theme/animation';
+ *
+ * // Import native utilities (in .native.ts files)
+ * import { timingConfig, springConfig } from '@idealyst/theme/animation';
+ */
+
+// Export tokens
+export { durations, easings, presets } from './tokens';
+export type { DurationKey, EasingKey, PresetKey } from './tokens';
+
+// Export types
+export type {
+  Duration,
+  Easing,
+  BezierEasing,
+  SpringConfig,
+  CSSEasing,
+  AnimationConfig,
+  TransitionConfig,
+  Keyframes,
+  KeyframeAnimationConfig,
+  AnimationIterations,
+  AnimationDirection,
+  AnimationFillMode,
+  SpringType,
+  TimingAnimationConfig,
+  PlatformAnimationOptions,
+  GradientAnimation,
+  GradientBorderConfig,
+} from './types';
+
+// Export web utilities
+export {
+  resolveDuration,
+  resolveEasing,
+  cssTransition,
+  cssPreset,
+  cssKeyframes,
+  cssAnimation,
+  gradientPropertyCSS,
+  injectGradientCSS,
+  conicSpinnerStyle,
+  pulseGradientStyle,
+} from './transitions';
+
+// Export native utilities (these are also exported from index.native.ts)
+// Including here allows type-checking in monorepo without platform resolution
+export {
+  resolveEasingBezier,
+  isSpringEasing,
+  timingConfig,
+  springConfig,
+  animationConfig,
+  presetConfig,
+  delayMs,
+  sequenceSteps,
+} from './transitions.native';

package/src/animation/tokens.ts

@@ -0,0 +1,145 @@
+/**
+ * Animation tokens for @idealyst/theme
+ *
+ * These tokens provide consistent animation timing across the framework.
+ * Use these instead of hardcoded values for consistency and maintainability.
+ */
+
+/**
+ * Duration tokens in milliseconds
+ *
+ * @example
+ * import { durations } from '@idealyst/theme/animation';
+ *
+ * // Use in CSS transition
+ * transition: `opacity ${durations.normal}ms ease`
+ *
+ * // Use with Reanimated
+ * withTiming(value, { duration: durations.fast })
+ */
+export const durations = {
+  /** 0ms - No animation, instant change */
+  instant: 0,
+  /** 100ms - Micro-interactions: hover, focus, press feedback */
+  fast: 100,
+  /** 200ms - Standard state transitions: toggle, selection changes */
+  normal: 200,
+  /** 300ms - Complex transitions: expand/collapse, progress bars */
+  slow: 300,
+  /** 500ms - Entrance animations: modals, toasts appearing */
+  slower: 500,
+  /** 750ms - Extended animations: skeleton pulse, loading states */
+  slowest: 750,
+  /** 1000ms - Loop animations: spinners, continuous indicators */
+  loop: 1000,
+} as const;
+
+/**
+ * Easing tokens with both CSS string and bezier values
+ *
+ * CSS easings include both a CSS string for web transitions
+ * and bezier curve values for Reanimated's Easing.bezier()
+ *
+ * Spring easings are native-only and include damping/stiffness/mass
+ *
+ * @example
+ * import { easings } from '@idealyst/theme/animation';
+ *
+ * // Web: use CSS string
+ * transition: `opacity 200ms ${easings.easeOut.css}`
+ *
+ * // Native: use bezier values
+ * Easing.bezier(...easings.easeOut.bezier)
+ *
+ * // Native spring
+ * withSpring(value, easings.spring)
+ */
+export const easings = {
+  // Standard CSS easings
+  /** Linear - constant speed, no acceleration */
+  linear: { css: 'linear', bezier: [0, 0, 1, 1] as const },
+  /** Ease - slight acceleration at start, deceleration at end */
+  ease: { css: 'ease', bezier: [0.25, 0.1, 0.25, 1] as const },
+  /** Ease-in - starts slow, accelerates */
+  easeIn: { css: 'ease-in', bezier: [0.42, 0, 1, 1] as const },
+  /** Ease-out - starts fast, decelerates (most common for UI) */
+  easeOut: { css: 'ease-out', bezier: [0, 0, 0.58, 1] as const },
+  /** Ease-in-out - symmetric acceleration and deceleration */
+  easeInOut: { css: 'ease-in-out', bezier: [0.42, 0, 0.58, 1] as const },
+
+  // Material Design easings
+  /** Standard - Material Design standard easing, balanced feel */
+  standard: { css: 'cubic-bezier(0.4, 0, 0.2, 1)', bezier: [0.4, 0, 0.2, 1] as const },
+  /** Decelerate - Material Design deceleration, for entering elements */
+  decelerate: { css: 'cubic-bezier(0, 0, 0.2, 1)', bezier: [0, 0, 0.2, 1] as const },
+  /** Accelerate - Material Design acceleration, for exiting elements */
+  accelerate: { css: 'cubic-bezier(0.4, 0, 1, 1)', bezier: [0.4, 0, 1, 1] as const },
+
+  // Spring configurations (native only - used with withSpring)
+  /** Spring - balanced spring, good for toggles and state changes */
+  spring: { damping: 15, stiffness: 200, mass: 1 } as const,
+  /** Spring stiff - less bounce, snappier feel, good for switches */
+  springStiff: { damping: 40, stiffness: 200, mass: 1 } as const,
+  /** Spring bouncy - more bounce, playful feel, good for buttons */
+  springBouncy: { damping: 10, stiffness: 180, mass: 1 } as const,
+} as const;
+
+/**
+ * Animation presets for common use cases
+ *
+ * These combine duration and easing for specific interaction patterns.
+ *
+ * @example
+ * import { presets } from '@idealyst/theme/animation';
+ *
+ * // Use for hover effects
+ * _web: { transition: cssPreset(presets.hover) }
+ */
+export const presets = {
+  // Micro-interactions
+  /** Hover effect - fast, subtle */
+  hover: { duration: 'fast' as const, easing: 'ease' as const },
+  /** Press/active feedback - fast, ease-out */
+  press: { duration: 'fast' as const, easing: 'easeOut' as const },
+  /** Focus ring - normal speed */
+  focus: { duration: 'normal' as const, easing: 'ease' as const },
+
+  // State changes
+  /** Toggle/switch - normal with spring on native */
+  toggle: { duration: 'normal' as const, easing: 'spring' as const },
+  /** Selection change - normal, standard easing */
+  select: { duration: 'normal' as const, easing: 'standard' as const },
+
+  // Expand/collapse
+  /** Expand content - slow, standard easing */
+  expand: { duration: 'slow' as const, easing: 'standard' as const },
+  /** Collapse content - slightly faster than expand */
+  collapse: { duration: 'normal' as const, easing: 'accelerate' as const },
+
+  // Entrance/exit
+  /** Fade in - normal, decelerate */
+  fadeIn: { duration: 'normal' as const, easing: 'decelerate' as const },
+  /** Fade out - fast, accelerate */
+  fadeOut: { duration: 'fast' as const, easing: 'accelerate' as const },
+  /** Scale in (modal, dialog) - slower, decelerate */
+  scaleIn: { duration: 'slower' as const, easing: 'decelerate' as const },
+  /** Scale out - normal, accelerate */
+  scaleOut: { duration: 'normal' as const, easing: 'accelerate' as const },
+  /** Slide in - slow, standard */
+  slideIn: { duration: 'slow' as const, easing: 'standard' as const },
+  /** Slide out - normal, accelerate */
+  slideOut: { duration: 'normal' as const, easing: 'accelerate' as const },
+
+  // Loading/continuous
+  /** Spinner rotation - 1s linear loop */
+  spin: { duration: 'loop' as const, easing: 'linear' as const, iterations: 'infinite' as const },
+  /** Pulse effect - slowest, ease-in-out loop */
+  pulse: { duration: 'slowest' as const, easing: 'easeInOut' as const, iterations: 'infinite' as const },
+  /** Skeleton wave - slower than pulse */
+  wave: { duration: 1500 as const, easing: 'easeInOut' as const, iterations: 'infinite' as const },
+} as const;
+
+// Type exports for convenience
+export type DurationKey = keyof typeof durations;
+export type EasingKey = keyof typeof easings;
+export type PresetKey = keyof typeof presets;

package/src/animation/transitions.native.ts

@@ -0,0 +1,219 @@
+/**
+ * Native-specific animation utilities
+ *
+ * These utilities generate Reanimated-compatible configurations
+ * from animation tokens for use in React Native animations.
+ */
+
+import { durations, easings } from './tokens';
+import type { DurationKey, EasingKey, PresetKey } from './tokens';
+import type { Duration, SpringType, BezierEasing } from './types';
+
+/**
+ * Resolve a duration value to milliseconds
+ */
+export function resolveDuration(duration: Duration): number {
+  if (typeof duration === 'number') {
+    return duration;
+  }
+  return durations[duration];
+}
+
+/**
+ * Resolve an easing key to bezier curve values
+ * Returns bezier array for use with Easing.bezier()
+ *
+ * Note: Spring easings return a fallback bezier curve.
+ * For actual spring behavior, use springConfig() instead.
+ */
+export function resolveEasingBezier(easing: EasingKey): BezierEasing {
+  const easingConfig = easings[easing];
+  // Spring configs don't have bezier equivalent, fall back to ease-out
+  if ('damping' in easingConfig) {
+    return easings.easeOut.bezier;
+  }
+  return easingConfig.bezier;
+}
+
+/**
+ * Check if an easing is a spring configuration
+ */
+export function isSpringEasing(easing: EasingKey): easing is SpringType {
+  return easing === 'spring' || easing === 'springStiff' || easing === 'springBouncy';
+}
+
+/**
+ * Get Reanimated withTiming configuration from tokens
+ *
+ * Use with Reanimated's withTiming() function.
+ * The returned config includes duration and a bezier easing function creator.
+ *
+ * @param duration - Duration token key or milliseconds
+ * @param easing - Easing token key (spring easings fall back to easeOut)
+ * @returns Configuration object with duration and easing bezier values
+ *
+ * @example
+ * import { timingConfig } from '@idealyst/theme/animation';
+ * import { withTiming, Easing } from 'react-native-reanimated';
+ *
+ * const config = timingConfig('normal', 'easeOut');
+ * // => { duration: 200, easing: [0, 0, 0.58, 1] }
+ *
+ * // Use with Reanimated
+ * animatedValue.value = withTiming(targetValue, {
+ *   duration: config.duration,
+ *   easing: Easing.bezier(...config.easing),
+ * });
+ */
+export function timingConfig(
+  duration: Duration = 'normal',
+  easing: EasingKey = 'easeOut'
+): { duration: number; easing: BezierEasing } {
+  return {
+    duration: resolveDuration(duration),
+    easing: resolveEasingBezier(easing),
+  };
+}
+
+/**
+ * Get Reanimated withSpring configuration from tokens
+ *
+ * Use with Reanimated's withSpring() function.
+ *
+ * @param type - Spring type: 'spring', 'springStiff', or 'springBouncy'
+ * @returns Spring configuration object
+ *
+ * @example
+ * import { springConfig } from '@idealyst/theme/animation';
+ * import { withSpring } from 'react-native-reanimated';
+ *
+ * const config = springConfig('springStiff');
+ * // => { damping: 40, stiffness: 200, mass: 1 }
+ *
+ * // Use with Reanimated
+ * animatedValue.value = withSpring(targetValue, config);
+ */
+export function springConfig(
+  type: SpringType = 'spring'
+): { damping: number; stiffness: number; mass: number } {
+  const config = easings[type];
+  return {
+    damping: config.damping,
+    stiffness: config.stiffness,
+    mass: config.mass,
+  };
+}
+
+/**
+ * Get animation configuration based on easing type
+ *
+ * Automatically returns spring config for spring easings,
+ * or timing config for bezier easings.
+ *
+ * @param duration - Duration token key or milliseconds
+ * @param easing - Easing token key
+ * @returns Either spring config or timing config
+ *
+ * @example
+ * import { animationConfig } from '@idealyst/theme/animation';
+ *
+ * // Returns spring config
+ * animationConfig('normal', 'spring')
+ * // => { type: 'spring', config: { damping: 15, stiffness: 200, mass: 1 } }
+ *
+ * // Returns timing config
+ * animationConfig('normal', 'easeOut')
+ * // => { type: 'timing', config: { duration: 200, easing: [0, 0, 0.58, 1] } }
+ */
+export function animationConfig(
+  duration: Duration = 'normal',
+  easing: EasingKey = 'easeOut'
+):
+  | { type: 'spring'; config: ReturnType<typeof springConfig> }
+  | { type: 'timing'; config: ReturnType<typeof timingConfig> } {
+  if (isSpringEasing(easing)) {
+    return {
+      type: 'spring',
+      config: springConfig(easing),
+    };
+  }
+  return {
+    type: 'timing',
+    config: timingConfig(duration, easing),
+  };
+}
+
+/**
+ * Get preset animation configuration for native
+ *
+ * @param presetName - Preset key
+ * @returns Animation configuration for the preset
+ */
+export function presetConfig(presetName: keyof typeof import('./tokens').presets) {
+  const { presets } = require('./tokens');
+  const preset = presets[presetName];
+  return animationConfig(preset.duration, preset.easing);
+}
+
+/**
+ * Helper to create a delay configuration
+ *
+ * Use with Reanimated's withDelay() function.
+ *
+ * @param delay - Delay in milliseconds or duration token
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * import { delayMs } from '@idealyst/theme/animation';
+ * import { withDelay, withTiming } from 'react-native-reanimated';
+ *
+ * // Using duration token
+ * animatedValue.value = withDelay(
+ *   delayMs('normal'),
+ *   withTiming(targetValue, timingConfig('fast', 'easeOut'))
+ * );
+ */
+export function delayMs(delay: Duration): number {
+  return resolveDuration(delay);
+}
+
+/**
+ * Create a sequence of timing animations
+ *
+ * Helper for creating withSequence() compatible values.
+ *
+ * @param steps - Array of { value, duration?, easing? } objects
+ * @returns Array of animation configurations
+ *
+ * @example
+ * import { sequenceSteps } from '@idealyst/theme/animation';
+ *
+ * const steps = sequenceSteps([
+ *   { value: 0 },
+ *   { value: 1, duration: 'normal', easing: 'easeOut' },
+ *   { value: 0.5, duration: 'fast' },
+ * ]);
+ *
+ * // Use with Reanimated
+ * animatedValue.value = withSequence(
+ *   ...steps.map(s => withTiming(s.value, {
+ *     duration: s.config.duration,
+ *     easing: Easing.bezier(...s.config.easing)
+ *   }))
+ * );
+ */
+export function sequenceSteps(
+  steps: Array<{
+    value: number;
+    duration?: Duration;
+    easing?: EasingKey;
+  }>
+): Array<{
+  value: number;
+  config: ReturnType<typeof timingConfig>;
+}> {
+  return steps.map((step) => ({
+    value: step.value,
+    config: timingConfig(step.duration ?? 'normal', step.easing ?? 'easeOut'),
+  }));
+}