ink-motion 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,262 @@
+import React from 'react';
+
+/**
+ * Colour value as hex (#ff0000), rgb (rgb(255,0,0)), or named (red, blue, etc.)
+ * Note: Props use 'color' (US spelling) for React convention, but type uses UK spelling
+ */
+type Colour = string;
+/**
+ * @deprecated Use Colour instead
+ */
+type Color = Colour;
+/**
+ * Easing function that takes normalised time (0-1) and returns eased value (0-1)
+ */
+type EasingFunction = (time: number) => number;
+/**
+ * Named easing functions
+ */
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+/**
+ * Base props shared by all effect components
+ */
+interface BaseEffectProps {
+    /**
+     * Text to animate (required)
+     */
+    children: string;
+    /**
+     * Animation speed multiplier
+     * @default 1
+     * @example 0.5 // half speed
+     * @example 2 // double speed
+     */
+    speed?: number;
+    /**
+     * Enable/disable animation
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Callback when animation completes
+     */
+    onComplete?: () => void;
+}
+
+type ShimmerDirection = 'left' | 'right';
+interface ShimmerProps extends BaseEffectProps {
+    /**
+     * Gradient colours for the shimmer effect [start, peak, end]
+     * @default ['#666666', '#ffffff', '#666666']
+     * @example ['#60a5fa', '#3b82f6', '#60a5fa']
+     */
+    colors?: [Colour, Colour, Colour];
+    /**
+     * Width of the shimmer band in characters
+     * @default 4
+     */
+    width?: number;
+    /**
+     * Brightness multiplier (0-1)
+     * @default 1
+     */
+    intensity?: number;
+    /**
+     * Direction of shimmer movement
+     * @default 'right'
+     */
+    direction?: ShimmerDirection;
+}
+/**
+ * Shimmer effect component that creates a moving highlight across text
+ *
+ * Creates a shimmering animation by interpolating through a gradient of colours
+ * that sweeps across the text from left to right or right to left.
+ *
+ * @example
+ * ```tsx
+ * <Shimmer colors={['#60a5fa', '#3b82f6', '#60a5fa']} intensity={0.8}>
+ *   Loading...
+ * </Shimmer>
+ * ```
+ */
+declare function Shimmer({ children, colors, width, intensity, direction, speed, enabled, onComplete, }: ShimmerProps): React.JSX.Element;
+
+interface TypewriterProps extends BaseEffectProps {
+    /**
+     * Text colour
+     * @default undefined (inherits)
+     * @example 'green'
+     */
+    color?: Colour;
+    /**
+     * Cursor character or false to disable
+     * @default '▋'
+     * @example '█'
+     */
+    cursor?: string | boolean;
+    /**
+     * Cursor colour (defaults to text colour)
+     * @default undefined
+     * @example 'cyan'
+     */
+    cursorColor?: Colour;
+    /**
+     * Typing speed randomness (0-1) for more human-like typing
+     * @default 0.3
+     */
+    variance?: number;
+    /**
+     * Initial delay before typing starts (ms)
+     * @default 0
+     */
+    delay?: number;
+}
+/**
+ * Typewriter effect component that reveals text character by character
+ *
+ * Simulates typing text with configurable speed, variance for realistic timing,
+ * and an optional cursor. The cursor blinks while typing is in progress.
+ *
+ * @example
+ * ```tsx
+ * <Typewriter color="green" cursor="█" variance={0.5} speed={2}>
+ *   npm install ink-motion
+ * </Typewriter>
+ * ```
+ */
+declare function Typewriter({ children, color, cursor, cursorColor, variance, delay, speed, enabled, onComplete, }: TypewriterProps): React.JSX.Element;
+
+interface FadeProps extends BaseEffectProps {
+    /**
+     * Text colour
+     * @default '#ffffff'
+     * @example 'yellow'
+     */
+    color?: Colour;
+    /**
+     * Starting opacity (0-1)
+     * @default 0
+     */
+    from?: number;
+    /**
+     * Ending opacity (0-1)
+     * @default 1
+     */
+    to?: number;
+    /**
+     * Duration in milliseconds
+     * @default 1000
+     */
+    duration?: number;
+    /**
+     * Easing function
+     * @default 'ease-out'
+     */
+    easing?: EasingName;
+    /**
+     * Loop animation continuously
+     * @default false
+     */
+    loop?: boolean;
+}
+/**
+ * Fade effect component that smoothly transitions text opacity
+ *
+ * Animates text from one opacity to another using configurable easing functions.
+ * Can loop continuously or run once.
+ *
+ * @example
+ * ```tsx
+ * <Fade color="yellow" from={0} to={1} duration={500} easing="ease-in">
+ *   Success!
+ * </Fade>
+ * ```
+ */
+declare function Fade({ children, color, from, to, duration, easing, loop, speed, enabled, onComplete, }: FadeProps): React.JSX.Element;
+
+type WaveType = 'brightness' | 'vertical';
+interface WaveProps extends BaseEffectProps {
+    /**
+     * Gradient colours for the wave [dark, bright]
+     * @default ['#888888', '#ffffff']
+     * @example ['#ec4899', '#8b5cf6']
+     */
+    colors?: [Colour, Colour];
+    /**
+     * Wave height (0-1)
+     * @default 0.5
+     */
+    amplitude?: number;
+    /**
+     * Number of wave cycles across text
+     * @default 2
+     */
+    frequency?: number;
+    /**
+     * Wave effect type
+     * @default 'brightness'
+     */
+    type?: WaveType;
+}
+/**
+ * Wave effect component that creates a wave motion through text
+ *
+ * Animates text with a sine wave pattern that can affect brightness or vertical position.
+ * The wave continuously flows through the text.
+ *
+ * @example
+ * ```tsx
+ * <Wave colors={['#ec4899', '#8b5cf6']} amplitude={0.7} frequency={3}>
+ *   ~~ wavy text ~~
+ * </Wave>
+ * ```
+ */
+declare function Wave({ children, colors, amplitude, frequency, type, speed, enabled, }: WaveProps): React.JSX.Element;
+
+/**
+ * Runs a callback on every animation frame using setInterval
+ *
+ * @param callback - Function called each frame with delta time in ms
+ * @param enabled - Whether animation is active
+ */
+declare function useAnimationFrame(callback: (deltaTime: number) => void, enabled?: boolean): void;
+
+/**
+ * Hook that tracks elapsed time since mount or last reset
+ *
+ * @param enabled - Whether to track time
+ * @param speed - Speed multiplier (default: 1)
+ * @returns Elapsed time in milliseconds
+ */
+declare function useElapsedTime(enabled?: boolean, speed?: number): number;
+
+interface UseCursorBlinkOptions {
+    enabled: boolean;
+    isComplete: boolean;
+}
+/**
+ * Hook that manages cursor blinking state
+ *
+ * @param options - Configuration for cursor blink
+ * @returns Whether cursor should be visible
+ */
+declare function useCursorBlink({ enabled, isComplete, }: UseCursorBlinkOptions): boolean;
+
+interface UseTypewriterProgressOptions {
+    totalCharacters: number;
+    speed: number;
+    variance: number;
+    initialDelay: number;
+    enabled: boolean;
+    onComplete?: () => void;
+}
+/**
+ * Hook that manages typewriter character reveal timing
+ *
+ * @param options - Configuration for typewriter progress
+ * @returns Number of characters to display
+ */
+declare function useTypewriterProgress({ totalCharacters, speed, variance, initialDelay, enabled, onComplete, }: UseTypewriterProgressOptions): number;
+
+export { type BaseEffectProps, type Color, type Colour, type EasingFunction, type EasingName, Fade, Shimmer, Typewriter, Wave, useAnimationFrame, useCursorBlink, useElapsedTime, useTypewriterProgress };

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+import React from 'react';
+
+/**
+ * Colour value as hex (#ff0000), rgb (rgb(255,0,0)), or named (red, blue, etc.)
+ * Note: Props use 'color' (US spelling) for React convention, but type uses UK spelling
+ */
+type Colour = string;
+/**
+ * @deprecated Use Colour instead
+ */
+type Color = Colour;
+/**
+ * Easing function that takes normalised time (0-1) and returns eased value (0-1)
+ */
+type EasingFunction = (time: number) => number;
+/**
+ * Named easing functions
+ */
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+/**
+ * Base props shared by all effect components
+ */
+interface BaseEffectProps {
+    /**
+     * Text to animate (required)
+     */
+    children: string;
+    /**
+     * Animation speed multiplier
+     * @default 1
+     * @example 0.5 // half speed
+     * @example 2 // double speed
+     */
+    speed?: number;
+    /**
+     * Enable/disable animation
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Callback when animation completes
+     */
+    onComplete?: () => void;
+}
+
+type ShimmerDirection = 'left' | 'right';
+interface ShimmerProps extends BaseEffectProps {
+    /**
+     * Gradient colours for the shimmer effect [start, peak, end]
+     * @default ['#666666', '#ffffff', '#666666']
+     * @example ['#60a5fa', '#3b82f6', '#60a5fa']
+     */
+    colors?: [Colour, Colour, Colour];
+    /**
+     * Width of the shimmer band in characters
+     * @default 4
+     */
+    width?: number;
+    /**
+     * Brightness multiplier (0-1)
+     * @default 1
+     */
+    intensity?: number;
+    /**
+     * Direction of shimmer movement
+     * @default 'right'
+     */
+    direction?: ShimmerDirection;
+}
+/**
+ * Shimmer effect component that creates a moving highlight across text
+ *
+ * Creates a shimmering animation by interpolating through a gradient of colours
+ * that sweeps across the text from left to right or right to left.
+ *
+ * @example
+ * ```tsx
+ * <Shimmer colors={['#60a5fa', '#3b82f6', '#60a5fa']} intensity={0.8}>
+ *   Loading...
+ * </Shimmer>
+ * ```
+ */
+declare function Shimmer({ children, colors, width, intensity, direction, speed, enabled, onComplete, }: ShimmerProps): React.JSX.Element;
+
+interface TypewriterProps extends BaseEffectProps {
+    /**
+     * Text colour
+     * @default undefined (inherits)
+     * @example 'green'
+     */
+    color?: Colour;
+    /**
+     * Cursor character or false to disable
+     * @default '▋'
+     * @example '█'
+     */
+    cursor?: string | boolean;
+    /**
+     * Cursor colour (defaults to text colour)
+     * @default undefined
+     * @example 'cyan'
+     */
+    cursorColor?: Colour;
+    /**
+     * Typing speed randomness (0-1) for more human-like typing
+     * @default 0.3
+     */
+    variance?: number;
+    /**
+     * Initial delay before typing starts (ms)
+     * @default 0
+     */
+    delay?: number;
+}
+/**
+ * Typewriter effect component that reveals text character by character
+ *
+ * Simulates typing text with configurable speed, variance for realistic timing,
+ * and an optional cursor. The cursor blinks while typing is in progress.
+ *
+ * @example
+ * ```tsx
+ * <Typewriter color="green" cursor="█" variance={0.5} speed={2}>
+ *   npm install ink-motion
+ * </Typewriter>
+ * ```
+ */
+declare function Typewriter({ children, color, cursor, cursorColor, variance, delay, speed, enabled, onComplete, }: TypewriterProps): React.JSX.Element;
+
+interface FadeProps extends BaseEffectProps {
+    /**
+     * Text colour
+     * @default '#ffffff'
+     * @example 'yellow'
+     */
+    color?: Colour;
+    /**
+     * Starting opacity (0-1)
+     * @default 0
+     */
+    from?: number;
+    /**
+     * Ending opacity (0-1)
+     * @default 1
+     */
+    to?: number;
+    /**
+     * Duration in milliseconds
+     * @default 1000
+     */
+    duration?: number;
+    /**
+     * Easing function
+     * @default 'ease-out'
+     */
+    easing?: EasingName;
+    /**
+     * Loop animation continuously
+     * @default false
+     */
+    loop?: boolean;
+}
+/**
+ * Fade effect component that smoothly transitions text opacity
+ *
+ * Animates text from one opacity to another using configurable easing functions.
+ * Can loop continuously or run once.
+ *
+ * @example
+ * ```tsx
+ * <Fade color="yellow" from={0} to={1} duration={500} easing="ease-in">
+ *   Success!
+ * </Fade>
+ * ```
+ */
+declare function Fade({ children, color, from, to, duration, easing, loop, speed, enabled, onComplete, }: FadeProps): React.JSX.Element;
+
+type WaveType = 'brightness' | 'vertical';
+interface WaveProps extends BaseEffectProps {
+    /**
+     * Gradient colours for the wave [dark, bright]
+     * @default ['#888888', '#ffffff']
+     * @example ['#ec4899', '#8b5cf6']
+     */
+    colors?: [Colour, Colour];
+    /**
+     * Wave height (0-1)
+     * @default 0.5
+     */
+    amplitude?: number;
+    /**
+     * Number of wave cycles across text
+     * @default 2
+     */
+    frequency?: number;
+    /**
+     * Wave effect type
+     * @default 'brightness'
+     */
+    type?: WaveType;
+}
+/**
+ * Wave effect component that creates a wave motion through text
+ *
+ * Animates text with a sine wave pattern that can affect brightness or vertical position.
+ * The wave continuously flows through the text.
+ *
+ * @example
+ * ```tsx
+ * <Wave colors={['#ec4899', '#8b5cf6']} amplitude={0.7} frequency={3}>
+ *   ~~ wavy text ~~
+ * </Wave>
+ * ```
+ */
+declare function Wave({ children, colors, amplitude, frequency, type, speed, enabled, }: WaveProps): React.JSX.Element;
+
+/**
+ * Runs a callback on every animation frame using setInterval
+ *
+ * @param callback - Function called each frame with delta time in ms
+ * @param enabled - Whether animation is active
+ */
+declare function useAnimationFrame(callback: (deltaTime: number) => void, enabled?: boolean): void;
+
+/**
+ * Hook that tracks elapsed time since mount or last reset
+ *
+ * @param enabled - Whether to track time
+ * @param speed - Speed multiplier (default: 1)
+ * @returns Elapsed time in milliseconds
+ */
+declare function useElapsedTime(enabled?: boolean, speed?: number): number;
+
+interface UseCursorBlinkOptions {
+    enabled: boolean;
+    isComplete: boolean;
+}
+/**
+ * Hook that manages cursor blinking state
+ *
+ * @param options - Configuration for cursor blink
+ * @returns Whether cursor should be visible
+ */
+declare function useCursorBlink({ enabled, isComplete, }: UseCursorBlinkOptions): boolean;
+
+interface UseTypewriterProgressOptions {
+    totalCharacters: number;
+    speed: number;
+    variance: number;
+    initialDelay: number;
+    enabled: boolean;
+    onComplete?: () => void;
+}
+/**
+ * Hook that manages typewriter character reveal timing
+ *
+ * @param options - Configuration for typewriter progress
+ * @returns Number of characters to display
+ */
+declare function useTypewriterProgress({ totalCharacters, speed, variance, initialDelay, enabled, onComplete, }: UseTypewriterProgressOptions): number;
+
+export { type BaseEffectProps, type Color, type Colour, type EasingFunction, type EasingName, Fade, Shimmer, Typewriter, Wave, useAnimationFrame, useCursorBlink, useElapsedTime, useTypewriterProgress };