/**
 * Type surface for the OperationCard compound.
 *
 * The card represents the lifecycle of a long-running operation (git
 * push/pull, deploy, upload, migration, anything that ticks through
 * discrete phases). It is **generic over the transfer payload** — the
 * consumer defines what `transfer` looks like and wires it through
 * `IOperationCardState<TTransfer>`.
 *
 * mks-ui owns this interface and knows nothing about domain types.
 *
 * @module @mks2508/mks-ui/react/ui/OperationCard
 */
import type { ReactNode } from 'react';
import type { IBaseConfig, SlotOverrides } from '../../../core/types';
import type { DotMatrixAccentRow, DotMatrixColor, DotMatrixPattern } from '../../../react-ui/primitives/DotMatrix';
/** Lifecycle status of the underlying operation. */
export type OperationCardStatus = 'idle' | 'pending' | 'success' | 'failed' | 'cancelled';
/**
 * Error shape. Kept minimal on purpose — consumers surface what they
 * want via `details`.
 */
export interface IOperationCardError {
    /** One-liner shown in the header + error section. */
    message: string;
    /** Optional verbose body, shown inside the collapsible "Show details". */
    details?: string;
}
/**
 * One inline action surfaced in `OperationCardActions`. Used for the
 * follow-up buttons that replace a generic Retry in specific failure /
 * success scenarios (e.g. "Pull & push" after a non-fast-forward push,
 * "Pull now" after a fetch detects new commits upstream).
 */
export interface IOperationCardAction {
    /** Button label. */
    label: string;
    /** Handler fired when the button is pressed. */
    onClick: () => void;
    /**
     * Recommended next step — painted as the primary action. Only one
     * recommended action should exist per state; the rest fall back to
     * the secondary treatment.
     */
    recommended?: boolean;
    /** Visual variant. `primary` is equivalent to `recommended`. */
    variant?: 'primary' | 'secondary' | 'ghost';
    /** Optional icon rendered before the label. */
    icon?: ReactNode;
    /** Disable the button (keeps it rendered to preserve layout). */
    disabled?: boolean;
}
/**
 * Known meta fields read by the compound. Consumer can attach anything
 * else — unknown keys are preserved and ignored by the card itself.
 */
export interface IOperationCardMeta extends Record<string, unknown> {
    /** Drives the `Cancel (3s)` grace-period countdown when `pending`. */
    remainingSeconds?: number;
    /** DotMatrix animation pattern. Drives the visual flow per op. */
    pattern?: DotMatrixPattern;
    /** DotMatrix palette colour. */
    color?: DotMatrixColor;
    /** Bloom intensity for the DotMatrix. */
    bloom?: boolean | number;
    /** Number of accent cells (e.g. new commits detected). Default: 0. */
    accentCount?: number;
    /** Accent cells row. Default: `top`. */
    accentRow?: DotMatrixAccentRow;
    /** Inline actions — rendered alongside / instead of the default Retry. */
    actions?: IOperationCardAction[];
}
/**
 * View-model the compound reads from context. Derive it upstream (hook
 * or adapter) and pass to `<OperationCardRoot state={...} />`.
 */
export interface IOperationCardState<TTransfer = unknown> {
    /** Status of the operation. */
    status: OperationCardStatus;
    /** Progress value 0..1. Consumer derives from transfer. */
    progress: number;
    /** Title line (e.g. "Pull origin · main"). */
    title: string;
    /**
     * Phase label (e.g. "Enumerating objects"). Swapped with SlidingText
     * when it changes to give a continuous "work is happening" feel.
     */
    phaseLabel?: string;
    /** Opaque domain payload. Passed to the Stats render-prop children. */
    transfer?: TTransfer;
    /** Populated when `status === 'failed'`. */
    error?: IOperationCardError;
    /** Narrative + behavioural metadata. See `IOperationCardMeta`. */
    meta?: IOperationCardMeta;
}
export type OperationCardSlot = 'root' | 'header' | 'title' | 'phase' | 'percent' | 'visualizer' | 'stats' | 'progress' | 'actions';
export interface IOperationCardConfig extends IBaseConfig {
    /**
     * Auto-close after success. If omitted, the card stays open until
     * the consumer dismisses it.
     */
    autoCloseMs?: number;
    /** Close when Escape is pressed. Default: true. */
    closeOnEscape?: boolean;
}
export interface IOperationCardContext<TTransfer = unknown> {
    state: IOperationCardState<TTransfer>;
    onCancel?: () => void;
    onRetry?: () => void;
    onClose?: () => void;
}
export interface IOperationCardRootProps<TTransfer = unknown> {
    /** View-model describing the operation. */
    state: IOperationCardState<TTransfer>;
    /** Called when the user cancels a pending operation. */
    onCancel?: () => void;
    /** Called when the user retries a failed operation. */
    onRetry?: () => void;
    /**
     * Called when the card wants to close itself — Esc keydown,
     * auto-close timer on success, or consumer-triggered dismissal.
     */
    onClose?: () => void;
    /** Auto-close after success (ms). 0 / undefined = stay open. */
    autoCloseMs?: number;
    /** Close when Escape is pressed. Default: true. */
    closeOnEscape?: boolean;
    /** Per-slot className overrides. */
    slots?: SlotOverrides<OperationCardSlot>;
    /** Advanced config. */
    config?: IOperationCardConfig;
    /** Extra className for the root. */
    className?: string;
    /** Subcomponents (OperationCardHeader, OperationCardVisualizer, ...). */
    children: ReactNode;
}
export interface IOperationCardHeaderProps {
    /** Extra className appended after slot override. */
    className?: string;
}
export interface IOperationCardVisualizerProps {
    /** Rows of the DotMatrix grid. Default 6. */
    rows?: number;
    /** Cols of the DotMatrix grid. Default 18. */
    cols?: number;
    /**
     * Pattern override. When omitted, falls back to `state.meta?.pattern`
     * then to `wave-lr`.
     */
    pattern?: DotMatrixPattern;
    /** Palette override. Falls back to `state.meta?.color`. */
    color?: DotMatrixColor;
    /** Bloom override. Falls back to `state.meta?.bloom`. */
    bloom?: boolean | number;
    /** Accent cells row placement. Falls back to `state.meta?.accentRow`. */
    accentRow?: DotMatrixAccentRow;
    /** Replace the default DotMatrix with custom children. */
    children?: ReactNode;
    /** Extra className appended after slot override. */
    className?: string;
}
export interface IOperationCardStatsProps<TTransfer = unknown> {
    /**
     * Render-prop receiving the `transfer` payload from context state.
     * When `transfer` is undefined, children still renders with `undefined`
     * so the consumer can decide whether to hide zero-state or show
     * skeletons.
     */
    children: (transfer: TTransfer | undefined) => ReactNode;
    /** Extra className appended after slot override. */
    className?: string;
}
export interface IOperationCardProgressProps {
    /** Extra className appended after slot override. */
    className?: string;
}
export interface IOperationCardActionsProps {
    /**
     * Show the "Esc to close" hint. Default: true. Consumers who implement
     * their own keyboard hint surface can disable this.
     */
    showEscHint?: boolean;
    /** Extra className appended after slot override. */
    className?: string;
    /** Extra children appended after the built-in buttons. */
    children?: ReactNode;
}
//# sourceMappingURL=OperationCard.types.d.ts.map