@cristianmpx/react-import-sheet-ui-raw 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,750 @@
+import * as _cristianmpx_react_import_sheet_headless from '@cristianmpx/react-import-sheet-headless';
+import { SheetLayout, ImporterStatus, ConvertResult, ImporterProgressDetail, SheetError, ValidatedRow } from '@cristianmpx/react-import-sheet-headless';
+export { ConvertResult, ConvertResultData, EditCellParams, ExportOptions, IMPORTER_ABORTED_EVENT, IMPORTER_PROGRESS_EVENT, ImporterProgressDetail, ImporterProvider, ImporterProviderProps, ImporterState, ImporterStatus, PaginatedResult, ParserEngine, PipelineMetrics, PipelineMetricsPercentages, PipelineMetricsTimings, Sheet, SheetError, SheetErrorLevel, SheetLayout, SheetLayoutField, SheetLayoutRef, UseImporterOptions, UseSheetViewOptions, UseSheetViewReturn, ValidatedCell, ValidatedRow, ViewCounts, ViewFilterMode, useConvert, useImportSheet, useImporter, useImporterEventTarget, useImporterProgressSubscription, useImporterStatus, useSheetData, useSheetEditor, useSheetView } from '@cristianmpx/react-import-sheet-headless';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties, RefObject, Dispatch, SetStateAction, ErrorInfo, Component } from 'react';
+
+interface RootConfigStages {
+    mapping?: boolean;
+    process?: boolean;
+    result?: boolean;
+}
+/**
+ * When to auto-apply mapping (skip mapping UI):
+ * - `'never'`: always show mapping when convertResult exists (default).
+ * - `0`: auto-apply when 0 mismatches; show mapping when ≥1.
+ * - `1`: auto-apply when 0 or 1 mismatches; show mapping when ≥2.
+ * - `N`: auto-apply when mismatches ≤ N; show mapping when > N.
+ */
+type AutoApplyMappingWhenMismatchesAtMost = number | 'never';
+interface RootConfig {
+    fuzzyMatch: boolean;
+    editingEnabled: boolean;
+    stages: RootConfigStages;
+    /** When to skip mapping UI and auto-apply. Default 'never'. */
+    autoApplyMappingWhenMismatchesAtMost: AutoApplyMappingWhenMismatchesAtMost;
+    /** When set, show error view instead of mapping when mismatch count > this. */
+    showErrorWhenMismatchesAbove: number | undefined;
+}
+interface UseRawImporterRootOptions {
+    layout?: SheetLayout | null;
+    engine?: 'xlsx' | 'csv' | 'auto' | null;
+    persist?: boolean;
+    persistKey?: string;
+    fuzzyMatch?: boolean;
+    editingEnabled?: boolean;
+    stages?: RootConfigStages;
+    /** Auto-apply mapping when mismatches ≤ this; 'never' = always show mapping. Default 'never'. */
+    autoApplyMappingWhenMismatchesAtMost?: AutoApplyMappingWhenMismatchesAtMost;
+    /** Show error instead of mapping when mismatches > this. Optional. */
+    showErrorWhenMismatchesAbove?: number;
+    /** Headless: called by submit() with sheet rows (layout keys or submitKeyMap). Optional. */
+    onSubmit?: (rows: Record<string, unknown>[]) => void;
+    /** Headless: sheet column key → output key for submit rows. Optional. */
+    submitKeyMap?: Record<string, string>;
+}
+interface UseRawImporterRootReturn {
+    providerProps: {
+        layout?: SheetLayout | null;
+        engine?: 'xlsx' | 'csv' | 'auto' | null;
+        persist?: boolean;
+        persistKey?: string;
+        onSubmit?: (rows: Record<string, unknown>[]) => void;
+        submitKeyMap?: Record<string, string>;
+    };
+    rootConfig: RootConfig;
+}
+
+declare function useRawImporterRoot(options?: UseRawImporterRootOptions): UseRawImporterRootReturn;
+
+declare const RootConfigContext: react.Context<RootConfig>;
+/** Layout from RawImporterRoot; used by useRawMappingTable/Row for field options. */
+declare const LayoutContext: react.Context<SheetLayout | null>;
+interface RootConfigProviderProps {
+    rootConfig: RootConfig;
+    children: ReactNode;
+}
+declare function RootConfigProvider({ rootConfig, children }: RootConfigProviderProps): react_jsx_runtime.JSX.Element;
+interface LayoutProviderProps {
+    layout: SheetLayout | null;
+    children: ReactNode;
+}
+declare function LayoutProvider({ layout, children }: LayoutProviderProps): react_jsx_runtime.JSX.Element;
+
+type StatusView = 'idle' | 'mapping' | 'process' | 'result' | 'error';
+declare function getViewFromState(status: ImporterStatus, convertResult: unknown): StatusView;
+
+/** Error shown when mismatch count exceeds showErrorWhenMismatchesAbove. */
+interface MappingErrorDetail {
+    code: 'TOO_MANY_MISMATCHES';
+    mismatchCount: number;
+    maxAllowed: number;
+}
+interface UseStatusViewReturn {
+    view: StatusView;
+    status: ImporterStatus;
+    progressEventTarget: EventTarget;
+    convertResult: ConvertResult | null;
+    /** Set when view is 'error' due to too many mapping mismatches. */
+    mappingErrorDetail: MappingErrorDetail | null;
+}
+
+declare function useStatusView(): UseStatusViewReturn;
+
+interface UseRawFilePickerOptions {
+    /** Accepted file types (e.g. ".xlsx,.csv" or "application/vnd.ms-excel"). */
+    accept?: string;
+}
+interface GetRootPropsOptions {
+    className?: string;
+    style?: CSSProperties;
+}
+interface UseRawFilePickerReturn {
+    isDragging: boolean;
+    getRootProps: (options?: GetRootPropsOptions) => {
+        ref: (el: HTMLElement | null) => void;
+        onClick: (e: React.MouseEvent) => void;
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+        role: string;
+        'aria-label'?: string;
+        'data-dropzone'?: string;
+        className?: string;
+        style?: CSSProperties;
+    };
+    getInputProps: () => {
+        ref: (el: HTMLInputElement | null) => void;
+        type: 'file';
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+        accept?: string;
+        tabIndex?: number;
+        'aria-label'?: string;
+    };
+}
+
+declare function useRawFilePicker(options?: UseRawFilePickerOptions): UseRawFilePickerReturn;
+
+/**
+ * Shared types for the input phase (file picker, mapping table/row, suggest, import action).
+ * Align with @cristianmpx/react-import-sheet-headless ConvertResult, headerToFieldMap, layout fields.
+ */
+
+/** Option for the destination field selector (layout field id + label). */
+interface LayoutFieldOption {
+    id: string;
+    label: string;
+    /** True when this field is already mapped by another file column (unique mapping). */
+    disabled?: boolean;
+}
+/** Status of a single column-to-field mapping (valid when mapped and matched). */
+type MappingStatus = 'valid' | 'invalid' | 'unmapped';
+/** Context passed to useRawMappingRow for one file column. */
+interface RawMappingRowContext {
+    /** Original header from the file (column name). */
+    headerOriginal: string;
+    /** Column index in the file (0-based). */
+    columnIndex: number;
+}
+/** Context passed to useRawMappingSuggest for one file column (fuzzy suggestion). */
+interface RawMappingSuggestContext {
+    /** Original header from the file. */
+    fileHeader: string;
+    /** Column index (0-based). */
+    columnIndex: number;
+}
+/**
+ * Build layout options from SheetLayout for dropdowns/selectors.
+ * Each option has id = field key, label = field.name (or id fallback).
+ */
+declare function getLayoutFieldOptions(layout: SheetLayout | null): LayoutFieldOption[];
+
+interface UseRawMappingTableReturn {
+    /** List of row contexts (one per file column) for useRawMappingRow. */
+    rows: RawMappingRowContext[];
+    /** Whether there is convert result (mapping) data to show. */
+    hasMappingData: boolean;
+}
+
+declare function useRawMappingTable(): UseRawMappingTableReturn;
+
+interface UseRawMappingRowOptions {
+    rowContext: RawMappingRowContext;
+}
+interface UseRawMappingRowReturn {
+    headerOriginal: string;
+    columnIndex: number;
+    options: LayoutFieldOption[];
+    value: string | null;
+    onChange: (fieldId: string) => void;
+    mappingStatus: MappingStatus;
+}
+
+declare function useRawMappingRow(options: UseRawMappingRowOptions): UseRawMappingRowReturn;
+
+interface UseRawMappingSuggestOptions {
+    columnContext: RawMappingSuggestContext;
+}
+interface UseRawMappingSuggestReturn {
+    /** 0–100 when fuzzyMatch is on and a suggestion exists; 0 otherwise. */
+    matchScore: number;
+    /** Layout field id suggested when fuzzyMatch is on; null otherwise. */
+    suggestedFieldId: string | null;
+    /** Label for the suggested field; null when no suggestion. */
+    suggestedFieldLabel: string | null;
+}
+
+declare function useRawMappingSuggest(options: UseRawMappingSuggestOptions): UseRawMappingSuggestReturn;
+
+interface UseRawImportActionReturn {
+    /** True when mapping is incomplete or pipeline is already running. */
+    disabled: boolean;
+    /** Applies current mapping and runs the pipeline (Sanitizer → Validator → Transform). */
+    runImport: () => void;
+}
+
+declare function useRawImportAction(): UseRawImportActionReturn;
+
+interface UseRawProgressOptions {
+    /** Called on each importer-progress event if the consumer wants to drive state (e.g. setPercent). Optional; for high perf use progressRef only. */
+    onProgress?: (detail: ImporterProgressDetail) => void;
+}
+interface UseRawProgressReturn {
+    /** Ref updated on each importer-progress event; no re-renders. Read in requestAnimationFrame or from a display component. */
+    progressRef: RefObject<ImporterProgressDetail | null>;
+    /** Only present if passed in options; same callback. */
+    onProgress?: (detail: ImporterProgressDetail) => void;
+}
+
+declare function useRawProgress(options?: UseRawProgressOptions): UseRawProgressReturn;
+
+interface UseRawStatusReturn {
+    /** Current importer status from the Core. */
+    status: ImporterStatus;
+    /** Diagnostic object when status === 'error'. Aligned with headless SheetError (code, params, level, message). Undefined until headless exposes lastError. */
+    errorDetail?: SheetError | null;
+}
+
+declare function useRawStatus(): UseRawStatusReturn;
+
+interface UseRawAbortReturn {
+    /** Calls the Core abort(); stops Workers. Attach to a button. */
+    abort: () => void;
+}
+
+declare function useRawAbort(): UseRawAbortReturn;
+
+/**
+ * Shared types for the data phase (result grid, table head/body/row/cell, error badge).
+ * Align with headless: SheetLayout, useSheetData, useSheetEditor, ValidatedRow, ValidatedCell, SheetError.
+ */
+/** Header item for table head (from SheetLayout fields). */
+interface TableHeader {
+    id: string;
+    label: string;
+}
+/** Context passed to useRawTableRow for one row. */
+interface RawTableRowContext {
+    /** Display index (0-based) in the virtualised/list view. */
+    index: number;
+    /** Optional inline style (e.g. from virtualiser: height, transform). */
+    style?: React.CSSProperties;
+    /** Optional pre-fetched row data when consumer has it. */
+    row?: _cristianmpx_react_import_sheet_headless.ValidatedRow | null;
+}
+/** Context passed to useRawCell for one cell. */
+interface RawCellContext {
+    /** Row display index (0-based). */
+    rowIndex: number;
+    /** Field id / cell key (layout field id). */
+    fieldId: string;
+    /** Optional pre-fetched value when consumer has it. */
+    value?: unknown;
+}
+/** Props returned by getRowProps for <tr>. Key is omitted so the consumer can pass it directly to JSX (e.g. <tr key={index} {...getRowProps({ index })} />). */
+interface GetRowPropsResult {
+    'data-row-index': number;
+    'data-has-errors'?: boolean;
+    'data-placeholder'?: boolean;
+    style?: React.CSSProperties;
+    onKeyDown?: (e: React.KeyboardEvent) => void;
+    role: string;
+    'aria-rowindex'?: number;
+    [key: string]: unknown;
+}
+/** Options for getRowProps. */
+interface GetRowPropsOptions {
+    index: number;
+    style?: React.CSSProperties;
+}
+/** Options for getCellProps (merge with consumer className/style). */
+interface GetCellPropsOptions {
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+interface PendingCell {
+    rowIndex: number;
+    fieldId: string;
+}
+interface DataTableContextValue {
+    /** Whether cell editing is enabled (from RootConfig). */
+    editingEnabled: boolean;
+    /** Ordered list of column/field ids for arrow-key navigation. */
+    headerIds: string[];
+    /** Total number of rows (for arrow-key boundary). */
+    totalRowCount: number;
+    /** Currently focused row index (0-based) or null. */
+    focusedRowIndex: number | null;
+    /** Currently focused cell key (field id) or null. */
+    focusedCellKey: string | null;
+    /** Set the focused cell (for Roaming Tabindex). */
+    setFocused: (rowIndex: number | null, cellKey: string | null) => void;
+    /** Cell currently being validated (edit in flight). Cleared when edit completes. */
+    pendingCell: PendingCell | null;
+    /** Set pending cell (used by useRawCell when editCell is called). */
+    setPendingCell: (cell: PendingCell | null) => void;
+    /** Build keydown handler for a cell at (rowIndex, cellKey). Injects A11y arrow navigation. */
+    getKeyDownHandler: (rowIndex: number, cellKey: string) => (e: React.KeyboardEvent) => void;
+    /** Optional: called when focus would move to a row index outside current virtual window (for scroll). */
+    onNavigateToIndex?: (index: number) => void;
+}
+interface UseRawDataTableReturn extends DataTableContextValue {
+    /** Headers derived from layout (id, label) for convenience. */
+    headers: TableHeader[];
+}
+
+interface UseRawDataTableOptions {
+    /** Called when focus would move to a row index (e.g. for virtualiser scrollToIndex). */
+    onNavigateToIndex?: (index: number) => void;
+}
+declare function useRawDataTable(options?: UseRawDataTableOptions): UseRawDataTableReturn;
+
+declare const DataTableContext: react.Context<DataTableContextValue>;
+
+interface RawDataTableProviderProps extends UseRawDataTableOptions {
+    children: ReactNode;
+}
+/**
+ * Provides DataTableContext (Roaming Tabindex, editingEnabled) for useRawTableBody/Row/Cell.
+ * editingEnabled is overridden with headless canEdit (!submitDone) so editing is disabled after submit.
+ * Must be used inside ImporterProvider + LayoutProvider + RootConfigProvider (e.g. RawImporterRoot).
+ */
+declare function RawDataTableProvider({ children, onNavigateToIndex }: RawDataTableProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseRawTableHeadReturn {
+    /** Headers (id, label) from SheetLayout for rendering <thead> and <th>. */
+    headers: TableHeader[];
+}
+
+declare function useRawTableHead(): UseRawTableHeadReturn;
+
+interface UseRawTableBodyReturn {
+    /** Total number of data rows (for virtualisation). */
+    totalRowCount: number;
+    /** Get props for a <tr> by display index. Merges style (e.g. from virtualiser). */
+    getRowProps: (options: GetRowPropsOptions) => GetRowPropsResult;
+    /** Whether the row at index is a placeholder (e.g. beyond data or skeleton). */
+    isPlaceholder: (index: number) => boolean;
+    /** Optional: set by consumer to scroll virtualiser when focus moves (onNavigateToIndex from context). */
+    onNavigateToIndex?: (index: number) => void;
+}
+
+declare function useRawTableBody(): UseRawTableBodyReturn;
+
+type UseRawTableRowOptions = RawTableRowContext;
+interface UseRawTableRowReturn {
+    /** Props for <tr> (style, data-has-errors, data-placeholder, role, aria-rowindex). Merge with consumer className/style. */
+    getRowProps: (options?: {
+        className?: string;
+        style?: React.CSSProperties;
+    }) => GetRowPropsResult & {
+        className?: string;
+        style?: React.CSSProperties;
+    };
+    /** Row data (errors, cells). Undefined when placeholder or out of range. */
+    row: ValidatedRow | undefined | null;
+    /** Row-level errors (from ValidatedRow.errors). */
+    rowErrors: readonly _cristianmpx_react_import_sheet_headless.SheetError[];
+}
+
+declare function useRawTableRow(options: UseRawTableRowOptions): UseRawTableRowReturn;
+
+interface UseRawCellOptions {
+    /** Row display index (0-based). */
+    rowIndex: number;
+    /** Field id / cell key. */
+    fieldId: string;
+}
+interface UseRawCellReturn {
+    /** Current cell value (from sheet; optimistic after edit until validated). */
+    value: unknown;
+    /** Cell-level validation errors. */
+    errors: readonly SheetError[];
+    /** True while edit is being validated (Worker). */
+    isPending: boolean;
+    /** True when this cell is focused and editing is enabled (consumer can show input). */
+    isEditing: boolean;
+    /** Props for <td> / gridcell: role, tabIndex, data-pending, data-has-error, aria-invalid, onKeyDown; merge className/style. */
+    getCellProps: (options?: GetCellPropsOptions) => Record<string, unknown>;
+    /** Props for the edit input when isEditing: value, onChange, onBlur, ref, etc. */
+    getEditInputProps: () => Record<string, unknown>;
+    /** Props for error message slot (role="alert", aria-live, data-ris-ui="raw-cell-error-message"). */
+    getErrorProps: () => Record<string, unknown>;
+    /** Update cell value (triggers validation; isPending true until done). Respects editingEnabled. */
+    editCell: (value: unknown) => void | Promise<void>;
+}
+
+declare function useRawCell(options: UseRawCellOptions): UseRawCellReturn;
+
+interface UseRawErrorBadgeOptions {
+    /** The error to display (code, params for I18n). */
+    error: SheetError | null | undefined;
+    /** Optional: (code, params) => translated string. */
+    translateError?: (code: string, params?: Readonly<Record<string, unknown>>) => string;
+}
+interface UseRawErrorBadgeReturn {
+    /** The error (code, params). */
+    error: SheetError | null | undefined;
+    /** Translated message when translateError is provided; otherwise error.message or code. */
+    message: string;
+    /** translateError if provided (for custom slot). */
+    translateError?: (code: string, params?: Readonly<Record<string, unknown>>) => string;
+}
+
+declare function useRawErrorBadge(options: UseRawErrorBadgeOptions): UseRawErrorBadgeReturn;
+
+interface UseRawPaginationReturn {
+    page: number;
+    pageSize: number;
+    totalRows: number;
+    /** Sheet row indices for the current page (respects filterMode). Use for rendering grid rows. */
+    visibleSheetIndices: number[];
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+}
+
+declare function useRawPagination(): UseRawPaginationReturn;
+
+interface UseRawSubmitStatusReturn {
+    /** True after the user has submitted (headless submitDone). */
+    isSubmitted: boolean;
+    /** Call when user submits; headless submit() invokes Provider onSubmit(rows) and sets submitDone. */
+    markSubmitted: () => void;
+    /** Headless canSubmit: true when status success, no validation errors, and not yet submitted. */
+    canSubmit: boolean;
+}
+declare function useRawSubmitStatus(): UseRawSubmitStatusReturn;
+
+/**
+ * View phase types — pagination, filter, export, persistence.
+ * Aligned with headless ViewFilterMode and UseSheetViewReturn.
+ */
+/** Filter mode for result view: all rows or only rows with errors. Aligned with headless ViewFilterMode. */
+type FilterMode = 'all' | 'errors-only';
+
+interface ViewPhaseContextValue {
+    page: number;
+    setPage: (page: number) => void;
+    pageSize: number;
+    setPageSize: (size: number) => void;
+    totalRows: number;
+    /** Sheet row indices for the current page (filtered by filterMode). Use these to render grid rows. */
+    visibleSheetIndices: number[];
+    filterMode: FilterMode;
+    setFilterMode: Dispatch<SetStateAction<FilterMode>>;
+    downloadCSV: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    downloadJSON: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    /** Export only rows that have validation errors (CSV). Optional; may be undefined if not provided by provider. */
+    downloadCSVErrorsOnly?: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    /** Export only rows that have validation errors (JSON). Optional; may be undefined if not provided by provider. */
+    downloadJSONErrorsOnly?: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    /** True when there is at least one row with validation errors (for disabling "export errors only" when empty). */
+    hasRowsWithErrors?: boolean;
+    hasRecoverableSession: boolean;
+    recoverSession: () => Promise<void>;
+    clearSession: () => Promise<void>;
+    /** True after the user has submitted (headless submitDone). */
+    isSubmitted: boolean;
+    /** Call when user submits; headless submit() invokes Provider onSubmit(rows) and sets submitDone. */
+    markSubmitted: () => void;
+    /** Headless canSubmit: true when status success, no validation errors, and not yet submitted. */
+    canSubmit: boolean;
+}
+declare const ViewPhaseContext: react.Context<ViewPhaseContextValue | null>;
+
+interface RawViewPhaseProviderProps {
+    children: ReactNode;
+    /** Initial page (1-based). Default 1. */
+    initialPage?: number;
+    /** Initial page size. Default 25. */
+    defaultPageSize?: number;
+    /** Initial filter mode. Default 'all'. */
+    defaultFilterMode?: FilterMode;
+}
+/**
+ * Single source of truth for view phase: pagination, filter, export, persistence.
+ * Must be used inside ImporterProvider (e.g. when status is success / RESULT view).
+ * useRawPagination, useRawFilterToggle, useRawExport, useRawPersistence read from this context.
+ */
+declare function RawViewPhaseProvider({ children, initialPage, defaultPageSize, defaultFilterMode, }: RawViewPhaseProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseRawRemoveRowReturn {
+    /** Removes the row at the given index. No-op if headless does not expose removeRow. */
+    removeRow: (rowIndex: number) => void;
+    /** True if the headless exposes removeRow (removal will take effect). */
+    canRemoveRow: boolean;
+}
+
+declare function useRawRemoveRow(): UseRawRemoveRowReturn;
+
+interface UseRawEditLogReturn {
+    /** Headless changeLog: cell_edit and row_remove entries. Cleared on processFile. */
+    entries: readonly unknown[];
+    /** Human-readable log string (headless formatChangeLogAsText). */
+    changeLogAsText: string;
+    /** No-op; headless clears log on processFile only. Kept for API compatibility. */
+    clearLog: () => void;
+}
+declare function useRawEditLog(): UseRawEditLogReturn;
+
+/** Entry when a cell value was updated. */
+interface EditLogCellUpdate {
+    type: 'cell_update';
+    rowIndex: number;
+    fieldId: string;
+    oldValue: unknown;
+    newValue: unknown;
+    timestamp: number;
+}
+/** Entry when a row was removed. */
+interface EditLogRowRemoved {
+    type: 'row_removed';
+    rowIndex: number;
+    timestamp: number;
+}
+type EditLogEntry = EditLogCellUpdate | EditLogRowRemoved;
+interface EditLogContextValue {
+    entries: readonly EditLogEntry[];
+    appendCellUpdate: (params: {
+        rowIndex: number;
+        fieldId: string;
+        oldValue: unknown;
+        newValue: unknown;
+    }) => void;
+    appendRowRemoved: (params: {
+        rowIndex: number;
+    }) => void;
+    clearLog: () => void;
+}
+
+declare const EditLogContext: react.Context<EditLogContextValue | null>;
+
+interface RawEditLogProviderProps {
+    children: ReactNode;
+}
+declare function RawEditLogProvider({ children }: RawEditLogProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseRawFilterToggleReturn {
+    filterMode: FilterMode;
+    setFilterMode: (mode: FilterMode) => void;
+}
+
+declare function useRawFilterToggle(): UseRawFilterToggleReturn;
+
+interface UseRawExportReturn {
+    downloadCSV: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    downloadJSON: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    /** Export only rows that have validation errors (CSV). May be undefined. */
+    downloadCSVErrorsOnly?: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    /** Export only rows that have validation errors (JSON). May be undefined. */
+    downloadJSONErrorsOnly?: (opts?: {
+        filename?: string;
+    }) => void | Promise<void>;
+    /** True when there is at least one row with validation errors. */
+    hasRowsWithErrors?: boolean;
+}
+
+declare function useRawExport(): UseRawExportReturn;
+
+interface UseRawPersistenceReturn {
+    hasRecoverableSession: boolean;
+    recoverSession: () => Promise<void>;
+    clearSession: () => Promise<void>;
+}
+
+declare function useRawPersistence(): UseRawPersistenceReturn;
+
+/**
+ * Returns pipeline metrics from the Core (timings, totalMs, rowCount).
+ * Use in renderResult to show e.g. "10,000 rows in 1.2s".
+ */
+declare function useImporterMetrics(): _cristianmpx_react_import_sheet_headless.PipelineMetrics | null;
+
+interface RawImporterRootProps extends UseRawImporterRootOptions {
+    children: ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawImporterRoot: react.ForwardRefExoticComponent<RawImporterRootProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawStatusGuardProps {
+    renderIdle?: (data: UseStatusViewReturn) => ReactNode;
+    renderMapping?: (data: UseStatusViewReturn) => ReactNode;
+    renderProcess?: (data: UseStatusViewReturn) => ReactNode;
+    renderResult?: (data: UseStatusViewReturn) => ReactNode;
+    renderError?: (data: UseStatusViewReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawStatusGuard: react.ForwardRefExoticComponent<RawStatusGuardProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawFilePickerProps {
+    children: (state: UseRawFilePickerReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawFilePicker: react.ForwardRefExoticComponent<RawFilePickerProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawMappingTableProps {
+    children: (state: UseRawMappingTableReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawMappingTable: react.ForwardRefExoticComponent<RawMappingTableProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawMappingRowProps {
+    rowContext: RawMappingRowContext;
+    children: (state: UseRawMappingRowReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawMappingRow: react.ForwardRefExoticComponent<RawMappingRowProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawMappingSuggestProps {
+    columnContext: RawMappingSuggestContext;
+    children: (state: UseRawMappingSuggestReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawMappingSuggest: react.ForwardRefExoticComponent<RawMappingSuggestProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawImportActionProps {
+    children: (state: UseRawImportActionReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawImportAction: react.ForwardRefExoticComponent<RawImportActionProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawErrorBoundaryProps {
+    children: ReactNode;
+    /** Content shown when an error is caught. Can be a node or a function (error, errorInfo) => ReactNode. */
+    fallback: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode);
+    /** Called when an error is caught. */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+
+declare class RawErrorBoundary extends Component<RawErrorBoundaryProps, {
+    error: Error | null;
+    errorInfo: ErrorInfo | null;
+}> {
+    constructor(props: RawErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+        errorInfo: null;
+    };
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+interface RawProgressDisplayProps {
+    children: (state: UseRawProgressReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Optional callback for progress updates (same as useRawProgress onProgress). */
+    onProgress?: (detail: ImporterProgressDetail) => void;
+}
+
+declare const RawProgressDisplay: react.ForwardRefExoticComponent<RawProgressDisplayProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawStatusIndicatorProps {
+    children: (state: UseRawStatusReturn) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+
+declare const RawStatusIndicator: react.ForwardRefExoticComponent<RawStatusIndicatorProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawAbortButtonProps {
+    children?: ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    disabled?: boolean;
+    'aria-label'?: string;
+}
+
+declare const RawAbortButton: react.ForwardRefExoticComponent<RawAbortButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface RawImporterWorkflowErrorOptions {
+    mappingErrorDetail: MappingErrorDetail | null;
+}
+/** Where to show the cell validation error message in the default result grid. */
+type CellErrorPlacement = 'inline' | 'below' | 'none';
+interface RawImporterWorkflowProps {
+    className?: string;
+    style?: React.CSSProperties;
+    renderIdle?: () => ReactNode;
+    renderMapping?: () => ReactNode;
+    renderProcess?: () => ReactNode;
+    renderResult?: () => ReactNode;
+    /** Receives mappingErrorDetail when view is 'error' due to too many mismatches. */
+    renderError?: (options: RawImporterWorkflowErrorOptions) => ReactNode;
+    /** Label for the Submit button (Submit is shown when Root has onSubmit; headless canSubmit disables it until valid). Default: "Submit". */
+    submitLabel?: ReactNode;
+    /**
+     * Where to show the validation error message per cell in the default result grid.
+     * - 'inline': message after the value (current behaviour).
+     * - 'below': message as a second line inside the cell (for styling/tooltips in another lib).
+     * - 'none': do not render the message in the cell (consumer shows it elsewhere, e.g. tooltip).
+     * Default: 'inline'.
+     */
+    cellErrorPlacement?: CellErrorPlacement;
+}
+
+declare const RawImporterWorkflow: react.ForwardRefExoticComponent<RawImporterWorkflowProps & react.RefAttributes<HTMLDivElement>>;
+
+interface RawEditLogPanelProps {
+    className?: string;
+    style?: React.CSSProperties;
+    /** Optional. Renders content; receives headless changeLog entries and changeLogAsText. */
+    children?: (props: {
+        entries: readonly unknown[];
+        changeLogAsText: string;
+        clearLog: () => void;
+    }) => ReactNode;
+}
+declare const RawEditLogPanel: react.ForwardRefExoticComponent<RawEditLogPanelProps & react.RefAttributes<HTMLDivElement>>;
+
+export { type AutoApplyMappingWhenMismatchesAtMost, type CellErrorPlacement, DataTableContext, type DataTableContextValue, type EditLogCellUpdate, EditLogContext, type EditLogEntry, type EditLogRowRemoved, type FilterMode, type GetCellPropsOptions, type GetRootPropsOptions, type GetRowPropsOptions, type GetRowPropsResult, LayoutContext, type LayoutFieldOption, LayoutProvider, type LayoutProviderProps, type MappingErrorDetail, type MappingStatus, type PendingCell, RawAbortButton, type RawAbortButtonProps, type RawCellContext, RawDataTableProvider, type RawDataTableProviderProps, RawEditLogPanel, type RawEditLogPanelProps, RawEditLogProvider, type RawEditLogProviderProps, RawErrorBoundary, type RawErrorBoundaryProps, RawFilePicker, type RawFilePickerProps, RawImportAction, type RawImportActionProps, RawImporterRoot, type RawImporterRootProps, RawImporterWorkflow, type RawImporterWorkflowErrorOptions, type RawImporterWorkflowProps, RawMappingRow, type RawMappingRowContext, type RawMappingRowProps, RawMappingSuggest, type RawMappingSuggestContext, type RawMappingSuggestProps, RawMappingTable, type RawMappingTableProps, RawProgressDisplay, type RawProgressDisplayProps, RawStatusGuard, type RawStatusGuardProps, RawStatusIndicator, type RawStatusIndicatorProps, type RawTableRowContext, RawViewPhaseProvider, type RawViewPhaseProviderProps, type RootConfig, RootConfigContext, RootConfigProvider, type RootConfigProviderProps, type RootConfigStages, type StatusView, type TableHeader, type UseRawAbortReturn, type UseRawCellOptions, type UseRawCellReturn, type UseRawDataTableOptions, type UseRawDataTableReturn, type UseRawEditLogReturn, type UseRawErrorBadgeOptions, type UseRawErrorBadgeReturn, type UseRawExportReturn, type UseRawFilePickerOptions, type UseRawFilePickerReturn, type UseRawFilterToggleReturn, type UseRawImportActionReturn, type UseRawImporterRootOptions, type UseRawImporterRootReturn, type UseRawMappingRowOptions, type UseRawMappingRowReturn, type UseRawMappingSuggestOptions, type UseRawMappingSuggestReturn, type UseRawMappingTableReturn, type UseRawPaginationReturn, type UseRawPersistenceReturn, type UseRawProgressOptions, type UseRawProgressReturn, type UseRawRemoveRowReturn, type UseRawStatusReturn, type UseRawSubmitStatusReturn, type UseRawTableBodyReturn, type UseRawTableHeadReturn, type UseRawTableRowOptions, type UseRawTableRowReturn, type UseStatusViewReturn, ViewPhaseContext, type ViewPhaseContextValue, getLayoutFieldOptions, getViewFromState, useImporterMetrics, useRawAbort, useRawCell, useRawDataTable, useRawEditLog, useRawErrorBadge, useRawExport, useRawFilePicker, useRawFilterToggle, useRawImportAction, useRawImporterRoot, useRawMappingRow, useRawMappingSuggest, useRawMappingTable, useRawPagination, useRawPersistence, useRawProgress, useRawRemoveRow, useRawStatus, useRawSubmitStatus, useRawTableBody, useRawTableHead, useRawTableRow, useStatusView };