@caffeinebounce/ui 0.62.2

package/dist/hooks-8ORd7T1A.d.cts

@@ -0,0 +1,751 @@
+import { l as PeriodGranularity, C as ComparisonMode, T as TimeUnit, c as FinancialStatementEntry, F as FinancialStatementConfig, q as SubtotalRulesConfig } from './FinancialStatementTable-BNUrdTU4.cjs';
+import * as React from 'react';
+import { StepStatus } from './forms.cjs';
+
+/**
+ * Represents an error captured during the session
+ */
+interface SessionError {
+    message: string;
+    stack?: string;
+    timestamp: string;
+    type: "error" | "unhandledrejection";
+}
+/**
+ * Options for configuring the useSessionErrors hook
+ */
+interface UseSessionErrorsOptions {
+    /** Maximum number of errors to store (default: 20) */
+    maxErrors?: number;
+    /** Session storage key for storing errors (default: "session_errors") */
+    storageKey?: string;
+}
+/**
+ * Hook that captures console errors and unhandled promise rejections
+ * during the session. Stores the last N errors in sessionStorage.
+ *
+ * Uses a singleton pattern to ensure only one set of global listeners
+ * is active, regardless of how many components use this hook.
+ *
+ * @param options Configuration options for error tracking
+ * @returns Object with methods to get and clear session errors
+ *
+ * @example
+ * ```tsx
+ * function FeedbackDialog() {
+ *   const { getErrors, clearErrors } = useSessionErrors({
+ *     maxErrors: 10,
+ *     storageKey: "my_app_errors",
+ *   });
+ *
+ *   const handleSubmit = async () => {
+ *     const errors = getErrors();
+ *     await submitFeedback({ sessionErrors: errors });
+ *     clearErrors();
+ *   };
+ * }
+ * ```
+ */
+declare function useSessionErrors(options?: UseSessionErrorsOptions): {
+    getErrors: () => SessionError[];
+    clearErrors: () => void;
+};
+
+interface DateRange {
+    start: string;
+    end: string;
+}
+declare function getDefaultLtmRange(): DateRange;
+interface UseFinancialStatementStateOptions {
+    initialGranularity?: PeriodGranularity;
+    initialComparisonMode?: ComparisonMode;
+    initialComparisonPeriods?: number;
+}
+declare function useFinancialStatementState({ initialGranularity, initialComparisonMode, initialComparisonPeriods, }?: UseFinancialStatementStateOptions): {
+    granularity: PeriodGranularity;
+    periodStart: string;
+    periodEnd: string;
+    timeUnit: TimeUnit;
+    selectedClass: string;
+    selectedDepartment: string;
+    comparisonMode: ComparisonMode;
+    comparisonPeriods: number;
+    comparisonCustomStart: string | undefined;
+    comparisonCustomEnd: string | undefined;
+    mobileFiltersOpen: boolean;
+    hideZeroRows: boolean;
+    showRowTotals: boolean;
+    priorRange: {
+        start: string;
+        end: string;
+    };
+    comparisonRanges: DateRange[];
+    periodChipLabel: string;
+    comparisonChipLabel: string;
+    activeFilterCount: number;
+    formatPeriodLabel: (periodKey?: string) => string;
+    setSelectedClass: React.Dispatch<React.SetStateAction<string>>;
+    setSelectedDepartment: React.Dispatch<React.SetStateAction<string>>;
+    setMobileFiltersOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    setHideZeroRows: React.Dispatch<React.SetStateAction<boolean>>;
+    setShowRowTotals: React.Dispatch<React.SetStateAction<boolean>>;
+    handlePeriodChange: (params: {
+        granularity: PeriodGranularity;
+        periodStart: string;
+        periodEnd: string;
+        timeUnit: "month" | "quarter" | "year";
+    }) => void;
+    handleComparisonChange: (params: {
+        mode: ComparisonMode;
+        periods: number;
+        customStart?: string;
+        customEnd?: string;
+    }) => void;
+    resetFilters: () => void;
+};
+
+interface ComparisonHookParams {
+    periodStart: string;
+    periodEnd: string;
+    classId?: string;
+    departmentId?: string;
+    enabled?: boolean;
+    keepPrevious?: boolean;
+}
+interface ComparisonHookResult<TRow, TClass = {
+    id: string;
+    name: string;
+}, TDepartment = {
+    id: string;
+    name: string;
+}> {
+    data?: {
+        data: TRow[];
+        classes?: TClass[];
+        departments?: TDepartment[];
+    };
+    isLoading: boolean;
+}
+interface UseComparisonDataParams<TRow, TClass = {
+    id: string;
+    name: string;
+}, TDepartment = {
+    id: string;
+    name: string;
+}> {
+    useDataHook: (params: ComparisonHookParams) => ComparisonHookResult<TRow, TClass, TDepartment>;
+    currentParams: {
+        periodStart: string;
+        periodEnd: string;
+        classId?: string;
+        departmentId?: string;
+    };
+    comparisonRanges: DateRange[];
+    comparisonMode: ComparisonMode;
+    comparisonPeriods: number;
+    toEntries: (rows: TRow[]) => FinancialStatementEntry[];
+    getPeriodKey: (row: TRow) => string;
+}
+declare function useComparisonData<TRow, TClass = {
+    id: string;
+    name: string;
+}, TDepartment = {
+    id: string;
+    name: string;
+}>({ useDataHook, currentParams, comparisonRanges, comparisonMode, comparisonPeriods, toEntries, getPeriodKey, }: UseComparisonDataParams<TRow, TClass, TDepartment>): {
+    response: {
+        data: TRow[];
+        classes?: TClass[] | undefined;
+        departments?: TDepartment[] | undefined;
+    } | undefined;
+    isLoading: boolean;
+    rawData: TRow[];
+    entries: FinancialStatementEntry[];
+    currentPeriodCount: number;
+    currentPeriodKeys: string[];
+    totalVisiblePeriodCount: number;
+    showVariance: boolean;
+    classes: TClass[];
+    departments: TDepartment[];
+};
+
+interface UseCopyToClipboardProps {
+    timeout?: number;
+}
+declare function useCopyToClipboard({ timeout, }?: UseCopyToClipboardProps): {
+    isCopied: boolean;
+    copiedId: string | null;
+    copyToClipboard: (value: string, id?: string) => void;
+};
+
+/**
+ * Hook that debounces a value by the specified delay.
+ * Useful for search inputs, API calls, etc.
+ *
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds (default: 500ms)
+ * @returns The debounced value
+ *
+ * @example
+ * ```tsx
+ * const [search, setSearch] = useState("");
+ * const debouncedSearch = useDebounce(search, 300);
+ *
+ * useEffect(() => {
+ *   // API call with debouncedSearch
+ * }, [debouncedSearch]);
+ * ```
+ */
+declare function useDebounce<T>(value: T, delay?: number): T;
+
+/**
+ * Keyboard shortcut definition
+ */
+interface KeyboardShortcutDefinition {
+    /** Key to press (case-sensitive for letters) */
+    key: string;
+    /** Require Ctrl/Cmd key */
+    ctrl?: boolean;
+    /** Require Shift key */
+    shift?: boolean;
+    /** Require Alt/Option key */
+    alt?: boolean;
+    /** Require Meta/Cmd key (Mac) */
+    meta?: boolean;
+    /** Whether the shortcut is currently enabled */
+    enabled?: boolean;
+}
+/**
+ * Options for the useKeyboardShortcut hook
+ */
+interface UseKeyboardShortcutOptions {
+    /** Whether the shortcut is enabled (default: true) */
+    enabled?: boolean;
+    /** Target element to attach listener to (default: document) */
+    target?: HTMLElement | Document | null;
+    /** Event phase to use (default: false for bubble phase) */
+    capture?: boolean;
+    /** Prevent default browser behavior when shortcut is triggered */
+    preventDefault?: boolean;
+    /** Stop event propagation when shortcut is triggered */
+    stopPropagation?: boolean;
+}
+/**
+ * Check if a keyboard event matches a shortcut definition.
+ * Uses boolean logic: `shortcut.ctrl ? event.ctrlKey : !event.ctrlKey`
+ *
+ * @param event - The keyboard event
+ * @param shortcut - The shortcut definition to match against
+ * @returns Whether the event matches the shortcut
+ */
+declare function matchesShortcut(event: KeyboardEvent, shortcut: KeyboardShortcutDefinition): boolean;
+/**
+ * Hook for handling keyboard shortcuts with SSR safety.
+ * Automatically manages event listeners and cleanup.
+ *
+ * @param shortcut - The keyboard shortcut definition
+ * @param callback - Function to call when shortcut is triggered
+ * @param options - Additional options for the shortcut
+ *
+ * @example
+ * ```tsx
+ * // Simple shortcut
+ * useKeyboardShortcut(
+ *   { key: "k", ctrl: true },
+ *   () => setSearchOpen(true)
+ * );
+ *
+ * // With options
+ * useKeyboardShortcut(
+ *   { key: "Escape" },
+ *   () => setModalOpen(false),
+ *   { preventDefault: true, enabled: modalOpen }
+ * );
+ *
+ * // Multiple modifier keys
+ * useKeyboardShortcut(
+ *   { key: "L", ctrl: true, shift: true },
+ *   () => toggleTheme()
+ * );
+ * ```
+ */
+declare function useKeyboardShortcut(shortcut: KeyboardShortcutDefinition, callback: (event: KeyboardEvent) => void, options?: UseKeyboardShortcutOptions): void;
+/**
+ * Format a shortcut for display (e.g., "Ctrl+Shift+L" or "⌘K").
+ * Uses platform-specific symbols when available.
+ *
+ * @param shortcut - The shortcut to format
+ * @param usePlatformSymbols - Whether to use platform symbols (⌘, ⌥, ⇧, ⌃) on Mac
+ * @returns Formatted shortcut string
+ *
+ * @example
+ * ```tsx
+ * formatShortcut({ key: "K", ctrl: true }) // "Ctrl+K"
+ * formatShortcut({ key: "K", meta: true }, true) // "⌘K" on Mac
+ * formatShortcut({ key: "L", ctrl: true, shift: true }) // "Ctrl+Shift+L"
+ * ```
+ */
+declare function formatShortcut(shortcut: KeyboardShortcutDefinition, usePlatformSymbols?: boolean): string;
+
+/**
+ * Hook for reading and writing to localStorage with SSR safety.
+ * Automatically syncs across tabs via the storage event.
+ *
+ * @param key - The localStorage key (pass null to disable)
+ * @param initialValue - The initial value if nothing is stored
+ * @returns A tuple of [storedValue, setValue, removeValue, isLoaded]
+ *
+ * **Breaking Change (v0.16+):** Return type changed from 3-tuple to 4-tuple.
+ * The `isLoaded` boolean is now the 4th element, indicating when localStorage
+ * has been read and state is hydrated. This is important for SSR compatibility.
+ *
+ * @example
+ * ```tsx
+ * // Destructure the 4-tuple
+ * const [theme, setTheme, removeTheme, isLoaded] = useLocalStorage("theme", "light");
+ *
+ * // Only render when loaded (SSR safe)
+ * if (!isLoaded) return <Skeleton />;
+ * ```
+ */
+declare function useLocalStorage<T>(key: string | null | undefined, initialValue: T): [T, (value: T | ((val: T) => T)) => void, () => void, boolean];
+
+/**
+ * Hook that tracks whether a media query matches.
+ * Useful for responsive designs and conditional rendering.
+ *
+ * @param query - The media query string (e.g., "(min-width: 768px)")
+ * @returns Whether the media query matches
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery("(max-width: 767px)");
+ * const isTablet = useMediaQuery("(min-width: 768px) and (max-width: 1023px)");
+ * const isDesktop = useMediaQuery("(min-width: 1024px)");
+ * const prefersDark = useMediaQuery("(prefers-color-scheme: dark)");
+ * ```
+ */
+declare function useMediaQuery(query: string): boolean;
+/**
+ * Preset breakpoints matching common Tailwind CSS defaults.
+ */
+declare const breakpoints: {
+    readonly sm: "(min-width: 640px)";
+    readonly md: "(min-width: 768px)";
+    readonly lg: "(min-width: 1024px)";
+    readonly xl: "(min-width: 1280px)";
+    readonly "2xl": "(min-width: 1536px)";
+};
+/**
+ * Hook that returns boolean flags for common responsive breakpoints.
+ *
+ * @example
+ * ```tsx
+ * const { isMobile, isTablet, isDesktop } = useBreakpoints();
+ * ```
+ */
+declare function useBreakpoints(): {
+    /** Below 640px */
+    isMobile: boolean;
+    /** 640px - 767px */
+    isSm: boolean;
+    /** 768px - 1023px */
+    isTablet: boolean;
+    /** 768px+ */
+    isMd: boolean;
+    /** 1024px+ */
+    isDesktop: boolean;
+    /** 1024px - 1279px */
+    isLg: boolean;
+    /** 1280px+ */
+    isXl: boolean;
+    /** 1536px+ */
+    is2xl: boolean;
+};
+
+type ScrollDirection = "up" | "down" | null;
+interface UseScrollDirectionOptions {
+    /** Minimum scroll delta before direction changes (prevents jitter) */
+    threshold?: number;
+    /** Scroll position below which navbar is always visible */
+    topThreshold?: number;
+}
+/**
+ * Hook that tracks scroll direction for implementing hide-on-scroll-down patterns.
+ *
+ * @example
+ * ```tsx
+ * const { direction, isAtTop } = useScrollDirection({ threshold: 10 });
+ * const visible = direction === "up" || isAtTop;
+ * ```
+ */
+declare function useScrollDirection({ threshold, topThreshold, }?: UseScrollDirectionOptions): {
+    direction: ScrollDirection;
+    isAtTop: boolean;
+};
+
+interface UseStatementExportParams {
+    entries: FinancialStatementEntry[];
+    config: FinancialStatementConfig;
+    timeUnit: TimeUnit;
+    subtotalRules?: SubtotalRulesConfig;
+    hideZeroRows: boolean;
+    periodStart: string;
+    periodEnd: string;
+    filenamePrefix: string;
+    worksheetName: string;
+}
+declare function useStatementExport({ entries, config, timeUnit, subtotalRules, hideZeroRows, periodStart, periodEnd, filenamePrefix, worksheetName, }: UseStatementExportParams): (format: "csv" | "excel") => void;
+
+interface UseStatementMobileModeParams<TEntry extends {
+    period_first_day: string;
+}> {
+    isMobile: boolean;
+    entries: TEntry[];
+    currentPeriodKeys: string[];
+    comparisonMode: string;
+}
+interface UseStatementMobileModeReturn<TEntry> {
+    activePeriodIndex: number;
+    setActivePeriodIndex: (updater: number | ((prev: number) => number)) => void;
+    compareEnabled: boolean;
+    setCompareEnabled: (enabled: boolean) => void;
+    mobileEntries: TEntry[];
+    periodLabel: string;
+    compareLabel?: string;
+    hasPrev: boolean;
+    hasNext: boolean;
+    hasComparisonCandidate: boolean;
+    activePeriod?: string;
+}
+declare function useStatementMobileMode<TEntry extends {
+    period_first_day: string;
+}>({ isMobile, entries, currentPeriodKeys, comparisonMode, }: UseStatementMobileModeParams<TEntry>): UseStatementMobileModeReturn<TEntry>;
+
+/**
+ * Toast options compatible with shadcn/ui toast pattern
+ */
+interface ToastOptions {
+    title?: string;
+    description?: string;
+    variant?: "default" | "destructive";
+    duration?: number;
+}
+/**
+ * Toast function that wraps sonner's API with shadcn/ui-compatible interface
+ */
+declare function toast(options: ToastOptions): string | number;
+/**
+ * Hook providing shadcn/ui-compatible toast interface using sonner.
+ *
+ * @example
+ * ```tsx
+ * const { toast } = useToast();
+ *
+ * toast({
+ *   title: "Success",
+ *   description: "Your changes have been saved.",
+ * });
+ *
+ * toast({
+ *   title: "Error",
+ *   description: "Something went wrong.",
+ *   variant: "destructive",
+ * });
+ * ```
+ */
+declare function useToast(): {
+    toast: typeof toast;
+};
+
+type FormFieldKey<TValues extends Record<string, unknown>> = Extract<keyof TValues, string>;
+/**
+ * Generic form interface for data restoration helper.
+ * Compatible with TanStack Form's useForm return type.
+ * Uses generic function signatures to accept TanStack Form's complex type structure.
+ */
+interface FormWithSetFieldValue<TValues extends Record<string, unknown>> {
+    setFieldValue: <TField extends FormFieldKey<TValues>>(field: TField, value: TValues[TField]) => void;
+    validateField: (field: FormFieldKey<TValues>, trigger: "change" | "blur") => void;
+}
+/**
+ * Creates a data restoration handler for multi-step wizard forms.
+ *
+ * This utility handles the complex pattern of restoring persisted data
+ * to a TanStack Form, which requires special timing due to unmounted fields.
+ *
+ * @param form - The form instance with setFieldValue and validateField methods
+ * @param onComplete - Optional callback after restoration is complete
+ * @returns A handler function to pass to FormWizard's onDataRestored prop
+ *
+ * @example
+ * ```tsx
+ * const form = useForm({ ... });
+ * const handleDataRestored = createDataRestorationHandler(form, () => {
+ *   console.log("Data restored!");
+ * });
+ *
+ * <FormWizard onDataRestored={handleDataRestored}>
+ *   ...
+ * </FormWizard>
+ * ```
+ */
+declare function createDataRestorationHandler<TValues extends Record<string, unknown>>(form: FormWithSetFieldValue<TValues>, defaultValues: TValues, onComplete?: () => void): (data: Partial<TValues>) => void;
+/**
+ * Extracts human-readable error messages from a Zod validation result.
+ *
+ * @param zodResult - The result from calling `zodSchema.safeParse(values)`
+ * @param fieldFilter - Optional array of field names to filter errors by
+ * @returns Array of formatted error messages
+ *
+ * @example
+ * ```tsx
+ * const result = stepSchema.safeParse(values);
+ * const errors = extractZodErrors(result);
+ * // ["Company Name is required", "Email must be valid"]
+ *
+ * // Or filter by specific fields:
+ * const errors = extractZodErrors(result, ["name", "email"]);
+ * ```
+ */
+declare function extractZodErrors(zodResult: {
+    success: boolean;
+    error?: {
+        issues: Array<{
+            path: (string | number)[];
+            message: string;
+        }>;
+    };
+}, fieldFilter?: string[]): string[];
+/**
+ * Configuration for a wizard form step
+ */
+interface WizardStep {
+    /** Unique identifier for the step */
+    id: string;
+    /** Display label for the step */
+    label: string;
+    /** Fields that belong to this step (for validation) */
+    fields: string[];
+    /** Whether this step is optional (affects validation display) */
+    optional?: boolean;
+}
+/**
+ * Generic interface for form field metadata (compatible with TanStack Form)
+ */
+interface FieldMeta {
+    errors?: string[];
+}
+/**
+ * Generic form interface for wizard utilities.
+ * Compatible with TanStack Form's useForm return type.
+ * Uses generic function signatures to accept TanStack Form's complex type structure.
+ */
+interface WizardFormInstance<_TValues extends Record<string, unknown>> {
+    setFieldValue: (field: FormFieldKey<_TValues>, value: _TValues[FormFieldKey<_TValues>]) => void;
+    validateField: (field: FormFieldKey<_TValues>, trigger: "change" | "blur") => void;
+    validateAllFields: (trigger: "change" | "blur") => void;
+    reset: () => void;
+    handleSubmit: () => void | Promise<void>;
+}
+/**
+ * Creates a stepHasFieldErrors checker function from form field metadata.
+ *
+ * This utility checks if any fields in a step have validation errors
+ * based on the form's fieldMeta state.
+ *
+ * @param steps - Array of step configurations with field mappings
+ * @param formFieldMeta - Form's field metadata (from useStore)
+ * @returns A function that checks if a step has field errors
+ *
+ * @example
+ * ```tsx
+ * const formFieldMeta = useStore(form.store, (state) => state.fieldMeta);
+ * const stepHasFieldErrors = createStepHasFieldErrors(steps, formFieldMeta);
+ *
+ * // Use in useWizardForm
+ * const wizard = useWizardForm({ steps, stepHasFieldErrors, ... }, values);
+ * ```
+ */
+declare function createStepHasFieldErrors<TFieldMeta extends Record<string, FieldMeta | undefined>>(steps: WizardStep[], formFieldMeta: TFieldMeta): (stepIndex: number) => boolean;
+/**
+ * Creates a form reset handler that resets both form state and wizard state.
+ *
+ * This utility provides a consistent pattern for resetting multi-step forms:
+ * 1. Resets TanStack Form state (clears errors and dirty state)
+ * 2. Resets all fields to default values
+ * 3. Resets wizard navigation state
+ *
+ * @param form - The form instance
+ * @param defaultValues - Default values to reset fields to
+ * @param resetWizardState - Function to reset wizard state
+ * @param clearSubmitError - Optional function to clear submit error state
+ * @returns A handler function to reset the entire form
+ *
+ * @example
+ * ```tsx
+ * const handleReset = createFormResetHandler(
+ *   form,
+ *   defaultValues,
+ *   wizard.resetWizardState,
+ *   () => setSubmitError(null)
+ * );
+ * ```
+ */
+declare function createFormResetHandler<TValues extends Record<string, unknown>>(form: WizardFormInstance<TValues>, defaultValues: TValues, resetWizardState: () => void, clearSubmitError?: () => void): () => void;
+/**
+ * Options for the form submit handler
+ */
+interface FormSubmitHandlerOptions {
+    /** Function to validate a specific step */
+    validateStep: (stepIndex: number) => boolean;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Error logger instance (from @caffeinebounce/logger) */
+    errorLogger?: {
+        logError: (error: Error, context: Record<string, unknown>) => void;
+    };
+    /** Component name for error logging */
+    componentName: string;
+    /** Current step statuses for logging */
+    getStepStatuses?: () => unknown[];
+    /** Function to show a toast notification for validation errors */
+    showValidationToast?: (message: string) => void;
+}
+/**
+ * Creates a form submission handler with validation and error handling.
+ *
+ * This utility provides a consistent pattern for form submission:
+ * 1. Marks the wizard as submitted (triggers error display)
+ * 2. Validates all form fields
+ * 3. Checks if all steps are valid
+ * 4. If invalid, shows toast error and logs
+ * 5. If valid, submits the form
+ *
+ * @param form - The form instance
+ * @param markAsSubmitted - Function to mark wizard as submitted
+ * @param options - Configuration options (including showValidationToast for error display)
+ * @returns A handler function for form submission
+ *
+ * @example
+ * ```tsx
+ * const handleSubmit = createFormSubmitHandler(
+ *   form,
+ *   wizard.markAsSubmitted,
+ *   {
+ *     validateStep,
+ *     totalSteps: sections.length,
+ *     errorLogger,
+ *     componentName: "CompanyForm",
+ *     getStepStatuses: () => wizard.stepStatuses,
+ *     showValidationToast: (msg) => toast.error(msg),
+ *   }
+ * );
+ * ```
+ */
+declare function createFormSubmitHandler<TValues extends Record<string, unknown>>(form: WizardFormInstance<TValues>, markAsSubmitted: () => void, options: FormSubmitHandlerOptions): () => void | Promise<void>;
+/**
+ * Options for the useWizardForm hook
+ */
+interface UseWizardFormOptions<TValues> {
+    /** Array of step definitions */
+    steps: WizardStep[];
+    /** Function to validate a step by index, returns true if valid */
+    validateStep: (stepIndex: number, values: TValues) => boolean;
+    /** Function to get validation errors with actual error messages for a step */
+    getStepErrors?: (stepIndex: number, values: TValues) => string[];
+    /** Function to check if a step has field-level errors (from form library) */
+    stepHasFieldErrors?: (stepIndex: number) => boolean;
+    /** Initial step index (default: 0) */
+    initialStep?: number;
+}
+/**
+ * Return type for useWizardForm hook
+ */
+interface UseWizardFormReturn {
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Whether the current step is the first */
+    isFirstStep: boolean;
+    /** Whether the current step is the last */
+    isLastStep: boolean;
+    /** The highest step index the user has navigated to */
+    highestStepReached: number;
+    /** Set of step indices where errors should be shown */
+    stepsWithErrorsShown: Set<number>;
+    /** Whether the user has attempted final form submission */
+    hasAttemptedFinalSubmit: boolean;
+    /** Array of step statuses for progress indicator */
+    stepStatuses: StepStatus[];
+    /** Whether any steps have incomplete or error status */
+    hasIncompleteOrErrorSteps: boolean;
+    /** Whether the current step is valid (passes validation) */
+    isCurrentStepValid: boolean;
+    /** Go to the next step (marks current step as having errors shown) */
+    handleNext: () => void;
+    /** Go to the previous step */
+    handleBack: () => void;
+    /** Go to a specific step by index */
+    handleStepClick: (stepIndex: number) => void;
+    /** Mark form as submitted (shows all errors, validates all steps) */
+    markAsSubmitted: () => void;
+    /** Reset all navigation and validation state */
+    resetWizardState: () => void;
+    /** Check if errors should be shown for a specific step */
+    shouldShowErrorsForStep: (stepIndex: number) => boolean;
+    /** Get step status for a specific step */
+    getStepStatus: (stepIndex: number) => StepStatus;
+    /** Get tooltip content for a step (error messages) */
+    getStepTooltip: (stepIndex: number, status: StepStatus) => string | null;
+    /** Get field names for a specific step */
+    getStepFields: (stepIndex: number) => string[];
+}
+/**
+ * Hook for managing multi-step wizard form state and navigation.
+ *
+ * This hook provides:
+ * - Step navigation with tracking of visited steps
+ * - Step validation status calculation
+ * - Error display management (only show errors for visited steps)
+ * - Submit state tracking
+ *
+ * @example
+ * ```tsx
+ * const wizard = useWizardForm({
+ *   steps: [
+ *     { id: "basic", label: "Basic Info", fields: ["name", "email"] },
+ *     { id: "details", label: "Details", fields: ["description"] },
+ *   ],
+ *   validateStep: (stepIndex, values) => {
+ *     if (stepIndex === 0) return !!values.name && !!values.email;
+ *     return true;
+ *   },
+ *   getStepErrors: (stepIndex, values) => {
+ *     const errors = [];
+ *     if (stepIndex === 0) {
+ *       if (!values.name) errors.push("Name is required");
+ *       if (!values.email) errors.push("Email is required");
+ *     }
+ *     return errors;
+ *   },
+ * }, formValues);
+ *
+ * // Use in FormWizard
+ * <FormWizard
+ *   steps={steps}
+ *   currentStep={wizard.currentStep}
+ *   onStepChange={wizard.handleStepClick}
+ *   getStepStatus={wizard.getStepStatus}
+ *   getStepTooltip={wizard.getStepTooltip}
+ * >
+ *   {children}
+ * </FormWizard>
+ * ```
+ */
+declare function useWizardForm<TValues>(options: UseWizardFormOptions<TValues>, 
+/** Current form values - pass this to trigger re-renders on value changes */
+currentValues: TValues): UseWizardFormReturn;
+
+export { useSessionErrors as A, useStatementExport as B, useStatementMobileMode as C, useToast as D, useWizardForm as E, type FieldMeta as F, type KeyboardShortcutDefinition as K, type ScrollDirection as S, type ToastOptions as T, type UseKeyboardShortcutOptions as U, type WizardFormInstance as W, type FormSubmitHandlerOptions as a, type FormWithSetFieldValue as b, type SessionError as c, type UseScrollDirectionOptions as d, type UseSessionErrorsOptions as e, type UseWizardFormOptions as f, type UseWizardFormReturn as g, type WizardStep as h, breakpoints as i, createDataRestorationHandler as j, createFormResetHandler as k, createFormSubmitHandler as l, createStepHasFieldErrors as m, extractZodErrors as n, formatShortcut as o, getDefaultLtmRange as p, matchesShortcut as q, useComparisonData as r, useCopyToClipboard as s, useDebounce as t, useBreakpoints as u, useFinancialStatementState as v, useKeyboardShortcut as w, useLocalStorage as x, useMediaQuery as y, useScrollDirection as z };