/**
 * @file Public type surface for `spinner/*` modules — the `Spinner` instance
 *   shape, configuration option records, progress and shimmer state types, plus
 *   the `withSpinner*` option records. Pure types only; no runtime side effects
 *   so this module stays cheap to import everywhere.
 */
import type { Writable } from 'node:stream';
import type { ColorInherit, ColorRgb, ColorValue } from '../colors/types';
import type { Palette, ShimmerConfig, ShimmerDirection } from '../effects/shimmer';
/**
 * 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 runtime state. Holds the user-facing config plus a monotonic
 * frame counter; the spinner advances `frame` on each animation tick and feeds
 * the current frame to the shimmer engine.
 */
export type ShimmerInfo = {
    /**
     * User-facing color reference (inherit, explicit value, or palette).
     */
    color: ColorInherit | ColorValue | Palette;
    /**
     * Current direction (driven by config, snapshotted here for getters).
     */
    direction: ShimmerDirection;
    /**
     * Steps per frame.
     */
    speed: number;
    /**
     * Monotonic frame counter — advanced on each animation tick.
     */
    frame: number;
};
/**
 * 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, reason, step, substep) go to stderr - Data messages
 * (`log()`) go to stdout.
 *
 * @example
 *   ;```ts
 *   import { Spinner } from '@socketsecurity/lib/spinner/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 SpinnerInstance = {
    /**
     * Current spinner color as RGB tuple.
     */
    color: ColorRgb;
    /**
     * Current spinner animation style.
     */
    spinner: SpinnerStyle;
    /**
     * Whether spinner is currently animating.
     */
    get isSpinning(): boolean;
    /**
     * Get current shimmer state (enabled/disabled and configuration)
     */
    get shimmerState(): ShimmerInfo | undefined;
    /**
     * Clear the current line without stopping the spinner.
     */
    clear(): SpinnerInstance;
    /**
     * Show debug message without stopping (only if debug mode enabled)
     */
    debug(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show debug message and stop the spinner (only if debug mode enabled)
     */
    debugAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Decrease indentation by specified spaces (default: 2)
     */
    dedent(spaces?: number | undefined): SpinnerInstance;
    /**
     * Disable shimmer effect (preserves config for later re-enable)
     */
    disableShimmer(): SpinnerInstance;
    /**
     * Alias for `success()` - show success without stopping.
     */
    done(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Alias for `successAndStop()` - show success and stop.
     */
    doneAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Enable shimmer effect (restores saved config or uses defaults)
     */
    enableShimmer(): SpinnerInstance;
    /**
     * Alias for `fail()` - show error without stopping.
     */
    error(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Alias for `failAndStop()` - show error and stop.
     */
    errorAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show failure (✗) without stopping the spinner.
     */
    fail(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show failure (✗) and stop the spinner, auto-clearing the line.
     */
    failAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Increase indentation by specified spaces (default: 2)
     */
    indent(spaces?: number | undefined): SpinnerInstance;
    /**
     * Show info (ℹ) message without stopping the spinner.
     */
    info(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show info (ℹ) message and stop the spinner, auto-clearing the line.
     */
    infoAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Log to stdout without stopping the spinner.
     */
    log(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Log and stop the spinner, auto-clearing the line.
     */
    logAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Update progress bar with current/total values and optional unit.
     */
    progress(current: number, total: number, unit?: string | undefined): SpinnerInstance;
    /**
     * Increment progress by specified amount (default: 1)
     */
    progressStep(amount?: number): SpinnerInstance;
    /**
     * Set complete shimmer configuration.
     */
    setShimmer(config: ShimmerConfig): SpinnerInstance;
    /**
     * Show skip (↻) message without stopping the spinner.
     */
    skip(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show skip (↻) message and stop the spinner, auto-clearing the line.
     */
    skipAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Start spinning with optional text.
     */
    start(text?: string | undefined): SpinnerInstance;
    /**
     * Show main step message to stderr without stopping.
     */
    step(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Stop spinning and clear internal state, auto-clearing the line.
     */
    stop(text?: string | undefined): SpinnerInstance;
    /**
     * Stop and show final text without clearing the line.
     */
    stopAndPersist(text?: string | undefined): SpinnerInstance;
    /**
     * Show indented substep message to stderr without stopping.
     */
    substep(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show success (✓) without stopping the spinner.
     */
    success(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show success (✓) and stop the spinner, auto-clearing the line.
     */
    successAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Get current spinner text (getter) or set new text (setter)
     */
    text(value: string): SpinnerInstance;
    text(): string;
    /**
     * Update partial shimmer configuration.
     */
    updateShimmer(config: Partial<ShimmerConfig>): SpinnerInstance;
    /**
     * Show warning (⚠) without stopping the spinner.
     */
    warn(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
    /**
     * Show warning (⚠) and stop the spinner, auto-clearing the line.
     */
    warnAndStop(text?: string | undefined, ...extras: unknown[]): SpinnerInstance;
};
/**
 * 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;
    /**
     * Theme to use for spinner colors. Accepts theme name ('socket', 'sunset',
     * etc.) or Theme object.
     *
     * @default Current theme from getTheme()
     */
    readonly theme?: import('../themes/types').Theme | import('../themes/themes').ThemeName | 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;
};
/**
 * Symbol types for status messages. Maps to log symbols: fail (✗), info (ℹ),
 * skip (↻), success (✓), warn (⚠).
 */
export type SymbolType = 'fail' | 'info' | 'skip' | 'success' | 'warn';
/**
 * 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?: SpinnerInstance | undefined;
    /**
     * Optional spinner options to apply during the operation. These options will
     * be pushed when the operation starts and popped when it completes. Supports
     * color and shimmer configuration.
     */
    withOptions?: Partial<Pick<SpinnerOptions, 'color' | 'shimmer'>> | undefined;
};
/**
 * 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?: SpinnerInstance | undefined;
    /**
     * Whether spinner was spinning before the operation (used to conditionally
     * restart)
     */
    wasSpinning: boolean;
};
/**
 * 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?: SpinnerInstance | undefined;
    /**
     * Optional spinner options to apply during the operation. These options will
     * be pushed when the operation starts and popped when it completes. Supports
     * color and shimmer configuration.
     */
    withOptions?: Partial<Pick<SpinnerOptions, 'color' | 'shimmer'>> | undefined;
};
