/**
 * @fileoverview CLI spinner utilities for long-running operations.
 * Provides animated progress indicators with CI environment detection.
 */
import type { Writable } from 'node:stream';
import type { ShimmerColorGradient, ShimmerConfig, ShimmerDirection, ShimmerState } from './effects/text-shimmer';
/**
 * Named color values supported by the spinner.
 * Maps to standard terminal colors with bright variants.
 */
export type ColorName = 'black' | 'blue' | 'blueBright' | 'cyan' | 'cyanBright' | 'gray' | 'green' | 'greenBright' | 'magenta' | 'magentaBright' | 'red' | 'redBright' | 'white' | 'whiteBright' | 'yellow' | 'yellowBright';
/**
 * Special 'inherit' color value that uses the spinner's current color.
 * Used with shimmer effects to dynamically inherit the spinner color.
 */
export type ColorInherit = 'inherit';
/**
 * RGB color tuple with values 0-255 for red, green, and blue channels.
 * @example [140, 82, 255] // Socket purple
 * @example [255, 0, 0]    // Red
 */
export type ColorRgb = readonly [number, number, number];
/**
 * Union of all supported color types: named colors or RGB tuples.
 */
export type ColorValue = ColorName | ColorRgb;
/**
 * Symbol types for status messages.
 * Maps to log symbols: success (✓), fail (✗), info (ℹ), warn (⚠).
 */
export type SymbolType = 'fail' | 'info' | 'success' | 'warn';
/**
 * Progress tracking information for display in spinner.
 * Used by `progress()` and `progressStep()` methods to show animated progress bars.
 */
export type ProgressInfo = {
    /** Current progress value */
    current: number;
    /** Total/maximum progress value */
    total: number;
    /** Optional unit label displayed after the progress count (e.g., 'files', 'items') */
    unit?: string | undefined;
};
/**
 * Internal shimmer state with color configuration.
 * Extends `ShimmerState` with additional color property that can be inherited from spinner.
 */
export type ShimmerInfo = ShimmerState & {
    /** Color for shimmer effect - can inherit from spinner, use explicit color, or gradient */
    color: ColorInherit | ColorValue | ShimmerColorGradient;
};
/**
 * Spinner instance for displaying animated loading indicators.
 * Provides methods for status updates, progress tracking, and text shimmer effects.
 *
 * KEY BEHAVIORS:
 * - Methods WITHOUT "AndStop" keep the spinner running (e.g., `success()`, `fail()`)
 * - Methods WITH "AndStop" auto-clear the spinner line (e.g., `successAndStop()`, `failAndStop()`)
 * - Status messages (done, success, fail, info, warn, step, substep) go to stderr
 * - Data messages (`log()`) go to stdout
 *
 * @example
 * ```ts
 * import { Spinner } from '@socketsecurity/lib/spinner'
 *
 * const spinner = Spinner({ text: 'Loading…' })
 * spinner.start()
 *
 * // Show success while continuing to spin
 * spinner.success('Step 1 complete')
 *
 * // Stop the spinner with success message
 * spinner.successAndStop('All done!')
 * ```
 */
export type Spinner = {
    /** Current spinner color as RGB tuple */
    color: ColorRgb;
    /** Current spinner animation style */
    spinner: SpinnerStyle;
    /** Whether spinner is currently animating */
    get isSpinning(): boolean;
    /** Clear the current line without stopping the spinner */
    clear(): Spinner;
    /** Show debug message without stopping (only if debug mode enabled) */
    debug(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show debug message and stop the spinner (only if debug mode enabled) */
    debugAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Alias for `fail()` - show error without stopping */
    error(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Alias for `failAndStop()` - show error and stop */
    errorAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show failure (✗) without stopping the spinner */
    fail(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show failure (✗) and stop the spinner, auto-clearing the line */
    failAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Get current spinner text (getter) or set new text (setter) */
    text(value: string): Spinner;
    text(): string;
    /** Increase indentation by specified spaces (default: 2) */
    indent(spaces?: number | undefined): Spinner;
    /** Decrease indentation by specified spaces (default: 2) */
    dedent(spaces?: number | undefined): Spinner;
    /** Show info (ℹ) message without stopping the spinner */
    info(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show info (ℹ) message and stop the spinner, auto-clearing the line */
    infoAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Log to stdout without stopping the spinner */
    log(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Log and stop the spinner, auto-clearing the line */
    logAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Start spinning with optional text */
    start(text?: string | undefined): Spinner;
    /** Stop spinning and clear internal state, auto-clearing the line */
    stop(text?: string | undefined): Spinner;
    /** Stop and show final text without clearing the line */
    stopAndPersist(text?: string | undefined): Spinner;
    /** Show main step message to stderr without stopping */
    step(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show indented substep message to stderr without stopping */
    substep(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show success (✓) without stopping the spinner */
    success(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show success (✓) and stop the spinner, auto-clearing the line */
    successAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Alias for `success()` - show success without stopping */
    done(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Alias for `successAndStop()` - show success and stop */
    doneAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Update progress bar with current/total values and optional unit */
    progress(current: number, total: number, unit?: string | undefined): Spinner;
    /** Increment progress by specified amount (default: 1) */
    progressStep(amount?: number): Spinner;
    /** Toggle shimmer effect on/off */
    shimmer(enabled: boolean): Spinner;
    /** Update shimmer configuration or set direction */
    shimmer(config: Partial<ShimmerConfig> | ShimmerDirection): Spinner;
    /** Show warning (⚠) without stopping the spinner */
    warn(text?: string | undefined, ...extras: unknown[]): Spinner;
    /** Show warning (⚠) and stop the spinner, auto-clearing the line */
    warnAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
};
/**
 * Configuration options for creating a spinner instance.
 */
export type SpinnerOptions = {
    /**
     * Spinner color as RGB tuple or color name.
     * @default [140, 82, 255] Socket purple
     */
    readonly color?: ColorValue | undefined;
    /**
     * Shimmer effect configuration or direction string.
     * When enabled, text will have an animated shimmer effect.
     * @default undefined No shimmer effect
     */
    readonly shimmer?: ShimmerConfig | ShimmerDirection | undefined;
    /**
     * Animation style with frames and timing.
     * @default 'socket' Custom Socket animation in CLI, minimal in CI
     */
    readonly spinner?: SpinnerStyle | undefined;
    /**
     * Abort signal for cancelling the spinner.
     * @default getAbortSignal() from process constants
     */
    readonly signal?: AbortSignal | undefined;
    /**
     * Output stream for spinner rendering.
     * @default process.stderr
     */
    readonly stream?: Writable | undefined;
    /**
     * Initial text to display with the spinner.
     * @default undefined No initial text
     */
    readonly text?: string | undefined;
};
/**
 * Animation style definition for spinner frames.
 * Defines the visual appearance and timing of the spinner animation.
 */
export type SpinnerStyle = {
    /** Array of animation frames (strings to display sequentially) */
    readonly frames: string[];
    /**
     * Milliseconds between frame changes.
     * @default 80 Standard frame rate
     */
    readonly interval?: number | undefined;
};
/**
 * Minimal spinner style for CI environments.
 * Uses empty frame and max interval to effectively disable animation in CI.
 */
export declare const ciSpinner: SpinnerStyle;
/**
 * Get available CLI spinner styles or a specific style by name.
 * Extends the standard cli-spinners collection with Socket custom spinners.
 *
 * Custom spinners:
 * - `socket` (default): Socket pulse animation with sparkles and lightning
 *
 * @param styleName - Optional name of specific spinner style to retrieve
 * @returns Specific spinner style if name provided, all styles if omitted, `undefined` if style not found
 * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
 *
 * @example
 * ```ts
 * // Get all available spinner styles
 * const allSpinners = getCliSpinners()
 *
 * // Get specific style
 * const socketStyle = getCliSpinners('socket')
 * const dotsStyle = getCliSpinners('dots')
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function getCliSpinners(styleName?: string | undefined): SpinnerStyle | Record<string, SpinnerStyle> | undefined;
/**
 * Create a spinner instance for displaying loading indicators.
 * Provides an animated CLI spinner with status messages, progress tracking, and shimmer effects.
 *
 * AUTO-CLEAR BEHAVIOR:
 * - All *AndStop() methods AUTO-CLEAR the spinner line via yocto-spinner.stop()
 *   Examples: `doneAndStop()`, `successAndStop()`, `failAndStop()`, etc.
 *
 * - Methods WITHOUT "AndStop" do NOT clear (spinner keeps spinning)
 *   Examples: `done()`, `success()`, `fail()`, etc.
 *
 * STREAM USAGE:
 * - Spinner animation: stderr (yocto-spinner default)
 * - Status methods (done, success, fail, info, warn, step, substep): stderr
 * - Data methods (`log()`): stdout
 *
 * COMPARISON WITH LOGGER:
 * - `logger.done()` does NOT auto-clear (requires manual `logger.clearLine()`)
 * - `spinner.doneAndStop()` DOES auto-clear (built into yocto-spinner.stop())
 * - Pattern: `logger.clearLine().done()` vs `spinner.doneAndStop()`
 *
 * @param options - Configuration options for the spinner
 * @returns New spinner instance
 *
 * @example
 * ```ts
 * import { Spinner } from '@socketsecurity/lib/spinner'
 *
 * // Basic usage
 * const spinner = Spinner({ text: 'Loading data…' })
 * spinner.start()
 * await fetchData()
 * spinner.successAndStop('Data loaded!')
 *
 * // With custom color
 * const spinner = Spinner({
 *   text: 'Processing…',
 *   color: [255, 0, 0] // Red
 * })
 *
 * // With shimmer effect
 * const spinner = Spinner({
 *   text: 'Building…',
 *   shimmer: { dir: 'ltr', speed: 0.5 }
 * })
 *
 * // Show progress
 * spinner.progress(5, 10, 'files')
 * spinner.progressStep() // Increment by 1
 * ```
 */
/*@__NO_SIDE_EFFECTS__*/
export declare function Spinner(options?: SpinnerOptions | undefined): Spinner;
/**
 * Get the default spinner instance.
 * Lazily creates the spinner to avoid circular dependencies during module initialization.
 * Reuses the same instance across calls.
 *
 * @returns Shared default spinner instance
 *
 * @example
 * ```ts
 * import { getDefaultSpinner } from '@socketsecurity/lib/spinner'
 *
 * const spinner = getDefaultSpinner()
 * spinner.start('Loading…')
 * ```
 */
export declare function getDefaultSpinner(): ReturnType<typeof Spinner>;
/**
 * Default shared spinner instance (lazily initialized).
 *
 * @deprecated Use `getDefaultSpinner()` function instead for better tree-shaking and to avoid circular dependencies.
 *
 * @example
 * ```ts
 * // Old (deprecated):
 * import { spinner } from '@socketsecurity/lib/spinner'
 * spinner.start('Loading…')
 *
 * // New (recommended):
 * import { getDefaultSpinner } from '@socketsecurity/lib/spinner'
 * const spinner = getDefaultSpinner()
 * spinner.start('Loading…')
 * ```
 */
export declare const spinner: Spinner;
/**
 * Configuration options for `withSpinner()` helper.
 * @template T - Return type of the async operation
 */
export type WithSpinnerOptions<T> = {
    /** Message to display while the spinner is running */
    message: string;
    /** Async function to execute while spinner is active */
    operation: () => Promise<T>;
    /**
     * Optional spinner instance to use.
     * If not provided, operation runs without spinner.
     */
    spinner?: Spinner | undefined;
};
/**
 * Execute an async operation with spinner lifecycle management.
 * Ensures `spinner.stop()` is always called via try/finally, even if the operation throws.
 * Provides safe cleanup and consistent spinner behavior.
 *
 * @template T - Return type of the operation
 * @param options - Configuration object
 * @param options.message - Message to display while spinner is running
 * @param options.operation - Async function to execute
 * @param options.spinner - Optional spinner instance (if not provided, no spinner is used)
 * @returns Result of the operation
 * @throws Re-throws any error from operation after stopping spinner
 *
 * @example
 * ```ts
 * import { Spinner, withSpinner } from '@socketsecurity/lib/spinner'
 *
 * const spinner = Spinner()
 *
 * // With spinner instance
 * const result = await withSpinner({
 *   message: 'Processing…',
 *   operation: async () => {
 *     return await processData()
 *   },
 *   spinner
 * })
 *
 * // Without spinner instance (no-op, just runs operation)
 * const result = await withSpinner({
 *   message: 'Processing…',
 *   operation: async () => {
 *     return await processData()
 *   }
 * })
 * ```
 */
export declare function withSpinner<T>(options: WithSpinnerOptions<T>): Promise<T>;
/**
 * Configuration options for `withSpinnerRestore()` helper.
 * @template T - Return type of the async operation
 */
export type WithSpinnerRestoreOptions<T> = {
    /** Async function to execute while spinner is stopped */
    operation: () => Promise<T>;
    /** Optional spinner instance to restore after operation */
    spinner?: Spinner | undefined;
    /** Whether spinner was spinning before the operation (used to conditionally restart) */
    wasSpinning: boolean;
};
/**
 * Execute an async operation with conditional spinner restart.
 * Useful when you need to temporarily stop a spinner for an operation,
 * then restore it to its previous state (if it was spinning).
 *
 * @template T - Return type of the operation
 * @param options - Configuration object
 * @param options.operation - Async function to execute
 * @param options.spinner - Optional spinner instance to manage
 * @param options.wasSpinning - Whether spinner was spinning before the operation
 * @returns Result of the operation
 * @throws Re-throws any error from operation after restoring spinner state
 *
 * @example
 * ```ts
 * import { getDefaultSpinner, withSpinnerRestore } from '@socketsecurity/lib/spinner'
 *
 * const spinner = getDefaultSpinner()
 * const wasSpinning = spinner.isSpinning
 * spinner.stop()
 *
 * const result = await withSpinnerRestore({
 *   operation: async () => {
 *     // Do work without spinner
 *     return await someOperation()
 *   },
 *   spinner,
 *   wasSpinning
 * })
 * // Spinner is automatically restarted if wasSpinning was true
 * ```
 */
export declare function withSpinnerRestore<T>(options: WithSpinnerRestoreOptions<T>): Promise<T>;
/**
 * Configuration options for `withSpinnerSync()` helper.
 * @template T - Return type of the sync operation
 */
export type WithSpinnerSyncOptions<T> = {
    /** Message to display while the spinner is running */
    message: string;
    /** Synchronous function to execute while spinner is active */
    operation: () => T;
    /**
     * Optional spinner instance to use.
     * If not provided, operation runs without spinner.
     */
    spinner?: Spinner | undefined;
};
/**
 * Execute a synchronous operation with spinner lifecycle management.
 * Ensures `spinner.stop()` is always called via try/finally, even if the operation throws.
 * Provides safe cleanup and consistent spinner behavior for sync operations.
 *
 * @template T - Return type of the operation
 * @param options - Configuration object
 * @param options.message - Message to display while spinner is running
 * @param options.operation - Synchronous function to execute
 * @param options.spinner - Optional spinner instance (if not provided, no spinner is used)
 * @returns Result of the operation
 * @throws Re-throws any error from operation after stopping spinner
 *
 * @example
 * ```ts
 * import { Spinner, withSpinnerSync } from '@socketsecurity/lib/spinner'
 *
 * const spinner = Spinner()
 *
 * const result = withSpinnerSync({
 *   message: 'Processing…',
 *   operation: () => {
 *     return processDataSync()
 *   },
 *   spinner
 * })
 * ```
 */
export declare function withSpinnerSync<T>(options: WithSpinnerSyncOptions<T>): T;
