nuxt-ui-tools 1.11.2 → 1.13.0

package/dist/runtime/spreadsheet/types/schema.d.ts

@@ -1,88 +1,174 @@
-import type { LazyTextValue, NestedPaths } from '#ui-tools/shared/types/utils';
-import type { SpreadsheetColumnsDefinition, SpreadsheetResolvedColumns } from './columns.js';
-import type { SpreadsheetContextDataFromItems, SpreadsheetContextItem } from './context.js';
-import type { ExtractSpreadsheetValidationRow, SpreadsheetRowData } from './inference.js';
-import type { SpreadsheetValue } from './shared.js';
-import type { SpreadsheetFieldRules, SpreadsheetRuleBuilder } from './validation.js';
+import type { QueryKey } from '@tanstack/vue-query';
+import type { QueryFunctionResult } from '#ui-tools/shared/types/query';
+import type { MaybePromise } from '#ui-tools/shared/types/utils';
+import type { SpreadsheetColumnsBuilder, SpreadsheetEntry, SpreadsheetFieldPath } from './columns.js';
+import type { SpreadsheetIssueLevel, SpreadsheetPrettify, SpreadsheetRecord } from './shared.js';
 export interface SpreadsheetFileDefinition {
+    /** Accepted extensions. Defaults to `.xlsx`, `.xls`, and `.csv`. */
     accept?: readonly string[];
-    maxRecords?: number;
+    /** Rows past this number are left out with the reason `limit`. */
+    maxRows?: number;
+    /** `'auto'` (default): the sheet whose rows match the most columns. Otherwise a sheet name. */
+    sheet?: string;
+    /** `'auto'` (default): the row, among the first 20, matching the most columns. Or a 1-based row. */
+    headerRow?: 'auto' | number;
 }
-export interface SpreadsheetStepTextDefinition {
-    title?: LazyTextValue;
-    description?: LazyTextValue;
+/** What happens to a row: created, updated from the file, or left as it is. */
+export type SpreadsheetRowMode = 'create' | 'update' | 'skip';
+/** What to do with a row whose key matches a stored record. */
+export type SpreadsheetExistingAction = 'update' | 'skip' | 'error';
+/** Value identifying a row: text, a number, or several of them for a key of several fields. */
+export type SpreadsheetRowKey = string | number | readonly (string | number)[];
+/** A query definition (with `queryKey` and `queryFn`) or a promise of the stored records. */
+export type SpreadsheetLookupResult = {
+    queryKey: QueryKey;
+} | MaybePromise<readonly unknown[]>;
+/** Record type returned by a lookup, from a query definition or a promise. */
+export type SpreadsheetLookupRecord<TResult> = unknown extends TResult ? unknown : TResult extends {
+    queryKey: QueryKey;
+} ? QueryFunctionResult<TResult> extends readonly (infer TRecord)[] ? TRecord : never : Awaited<TResult> extends readonly (infer TRecord)[] ? TRecord : never;
+export interface SpreadsheetExistingDefinition<TContext, TRow, TKeyValue, TLookup> {
+    /**
+     * Returns the stored records whose keys are in `keys`, in one query. Called again when the keys
+     * of the file change.
+     */
+    lookup(params: {
+        keys: readonly TKeyValue[];
+        ctx: TContext;
+    }): TLookup;
+    /** Key of a stored record. Defaults to `rows.key` applied to the record. */
+    keyOf?(record: SpreadsheetLookupRecord<TLookup>): TKeyValue;
+    /**
+     * `update` (default) re-syncs the stored record, `skip` leaves it as it is, `error` blocks the
+     * row. A function decides per row, with the stored record at hand.
+     */
+    action?: SpreadsheetExistingAction | {
+        bivarianceHack(params: {
+            row: TRow;
+            existing: SpreadsheetLookupRecord<TLookup>;
+            ctx: TContext;
+        }): SpreadsheetExistingAction;
+    }['bivarianceHack'];
 }
-export interface SpreadsheetSheetStepDefinition extends SpreadsheetStepTextDefinition {
-    strategy?: 'fixed' | 'selection' | 'auto';
+export interface SpreadsheetRowsDefinition<TContext, TRow, TKeyValue, TLookup> {
+    /**
+     * Identifies a row, in the file and among stored records: `(row) => row.secureCode`, or a tuple
+     * for several fields. A row whose key is empty is not identified.
+     */
+    key?(row: TRow): TKeyValue | null | undefined;
+    /** Two rows of the file with the same key. Defaults to `error`: both rows are blocked. */
+    duplicates?: 'error' | 'keep-first' | 'keep-last';
+    /** Rows whose key matches a stored record. */
+    existing?: SpreadsheetExistingDefinition<TContext, TRow, TKeyValue, TLookup>;
 }
-export interface SpreadsheetHeaderStepDefinition extends SpreadsheetStepTextDefinition {
-    strategy?: 'fixed' | 'first-row' | 'selection' | 'detected';
+/** An issue raised by `validate`. */
+export interface SpreadsheetIssueInput {
+    field: string;
+    message: string;
+    level: SpreadsheetIssueLevel;
+    code: string;
 }
-export interface SpreadsheetMatchingStepDefinition extends SpreadsheetStepTextDefinition {
-    strategy?: 'template' | 'smart' | 'manual';
-}
-export interface SpreadsheetReviewStepDefinition extends SpreadsheetStepTextDefinition {
-    allowInvalidSubmit?: boolean;
-}
-export interface SpreadsheetStructureStepDefinition extends SpreadsheetStepTextDefinition {
-    sheet?: SpreadsheetSheetStepDefinition;
-    header?: SpreadsheetHeaderStepDefinition;
-}
-export interface SpreadsheetStepsDefinition {
-    upload?: SpreadsheetStepTextDefinition;
-    structure?: SpreadsheetStructureStepDefinition;
-    matching?: SpreadsheetMatchingStepDefinition;
-    references?: SpreadsheetStepTextDefinition;
-    review?: SpreadsheetReviewStepDefinition;
+export type SpreadsheetIssueFactory<TRow> = (field: SpreadsheetFieldPath<TRow>, message: string, options?: {
+    level?: SpreadsheetIssueLevel;
+    code?: string;
+}) => SpreadsheetIssueInput;
+type SpreadsheetFalsy = false | null | undefined | 0 | '';
+/**
+ * What `defineSpreadsheetSchema` receives. Declare `columns` before the callbacks that read rows:
+ * they are typed from it.
+ */
+export interface SpreadsheetSchemaDefinition<TContext, TRow, TKeyValue, TLookup, TOutput> {
+    /** Names the import: query keys and the memory of past answers. */
+    key: string;
+    file?: SpreadsheetFileDefinition;
+    /** The columns, chained: `(c) => c.text(…).select(…)`. */
+    columns(c: SpreadsheetColumnsBuilder<TContext, NonNullable<unknown>>): SpreadsheetColumnsBuilder<TContext, TRow>;
+    rows?: SpreadsheetRowsDefinition<TContext, SpreadsheetPrettify<TRow>, TKeyValue, TLookup>;
+    /** Rules across fields. Return issues, or falsy values to skip. */
+    validate?(params: {
+        row: SpreadsheetPrettify<TRow>;
+        ctx: TContext;
+        issue: SpreadsheetIssueFactory<SpreadsheetPrettify<TRow>>;
+    }): readonly (SpreadsheetIssueInput | SpreadsheetFalsy)[];
+    /** What `onSubmit` receives for each imported row. Defaults to the row. */
+    output?(params: {
+        row: SpreadsheetPrettify<TRow>;
+        mode: Exclude<SpreadsheetRowMode, 'skip'>;
+        existing: SpreadsheetLookupRecord<TLookup> | undefined;
+        ctx: TContext;
+    }): MaybePromise<TOutput>;
 }
-type SpreadsheetValueAtPath<TRow, TPath extends string> = TPath extends `${infer TKey}.${infer TRest}` ? TKey extends keyof TRow ? SpreadsheetValueAtPath<NonNullable<TRow[TKey]>, TRest> : never : TPath extends keyof TRow ? TRow[TPath] : never;
-type SpreadsheetRelationPath<TRow> = Extract<NestedPaths<TRow>, string>;
-export interface SpreadsheetRelationDefinition<TRow, TColumn extends SpreadsheetRelationPath<TRow> = SpreadsheetRelationPath<TRow>> {
-    column: TColumn;
-    condition?: (row: TRow) => boolean;
-    rules: (rules: SpreadsheetRuleBuilder, row: TRow) => SpreadsheetFieldRules<SpreadsheetValueAtPath<TRow, TColumn>>;
+/** A schema, as `defineSpreadsheetSchema` returns it. */
+export interface SpreadsheetSchema<TContext = unknown, TRow = unknown, TKeyValue = unknown, TLookup = unknown, TOutput = unknown> extends SpreadsheetSchemaDefinition<TContext, TRow, TKeyValue, TLookup, TOutput> {
+    /** Type only. */
+    readonly '~context'?: TContext;
 }
-export type SpreadsheetRelationsDefinition<TRow> = readonly {
-    [TColumn in SpreadsheetRelationPath<TRow>]: SpreadsheetRelationDefinition<TRow, TColumn>;
-}[SpreadsheetRelationPath<TRow>][];
-export type SpreadsheetBuildRowDefinition<TContext = unknown, TRow = unknown> = (params: {
+type SpreadsheetSchemaParts<TSchema> = TSchema extends SpreadsheetSchema<infer TContext, infer TRow, infer TKey, infer TLookup, infer TOutput> ? {
     context: TContext;
     row: TRow;
-}) => SpreadsheetValue | Promise<SpreadsheetValue>;
-export interface SpreadsheetSchema<TContextItems extends readonly SpreadsheetContextItem<string, unknown>[] = readonly [], TColumns extends SpreadsheetColumnsDefinition<SpreadsheetContextDataFromItems<TContextItems>> = SpreadsheetColumnsDefinition<SpreadsheetContextDataFromItems<TContextItems>>, TReferences = readonly unknown[], TRelations = SpreadsheetRelationsDefinition<SpreadsheetRowData<SpreadsheetResolvedColumns<TColumns>, TReferences>>, TBuildRow = SpreadsheetBuildRowDefinition<SpreadsheetContextDataFromItems<TContextItems>, SpreadsheetRowData<SpreadsheetResolvedColumns<TColumns>, TReferences>>> {
-    importKey: string;
-    file?: SpreadsheetFileDefinition;
-    sheet?: SpreadsheetSheetStepDefinition;
-    header?: SpreadsheetHeaderStepDefinition;
-    matching?: SpreadsheetMatchingStepDefinition;
-    steps?: SpreadsheetStepsDefinition;
-    context?: TContextItems;
-    columns?: TColumns;
-    references?: TReferences;
-    relations?: TRelations;
-    buildRow?: TBuildRow;
-    review?: SpreadsheetReviewStepDefinition;
-}
-export interface SpreadsheetSchemaRefinement<TRow> {
-    relations?: SpreadsheetRelationsDefinition<TRow>;
-}
-export type SpreadsheetSchemaWithRefine<TSchema extends {
-    importKey: string;
-}> = TSchema & {
-    refine<const TRelations extends SpreadsheetRelationsDefinition<ExtractSpreadsheetValidationRow<TSchema>>>(refinement: {
-        relations: TRelations;
-    }): SpreadsheetSchemaWithRefine<TSchema & {
-        relations: SpreadsheetRelationsDefinition<ExtractSpreadsheetValidationRow<TSchema>>;
-    }>;
+    key: TKey;
+    lookup: TLookup;
+    output: TOutput;
+} : {
+    context: unknown;
+    row: SpreadsheetRecord;
+    key: unknown;
+    lookup: unknown;
+    output: unknown;
 };
-export type BuildSpreadsheetSchema<TContextItems extends readonly SpreadsheetContextItem<string, unknown>[] = readonly [], TColumns extends SpreadsheetColumnsDefinition<SpreadsheetContextDataFromItems<TContextItems>> = SpreadsheetColumnsDefinition<SpreadsheetContextDataFromItems<TContextItems>>, TReferences = readonly unknown[], TRelations = SpreadsheetRelationsDefinition<SpreadsheetRowData<SpreadsheetResolvedColumns<TColumns>, TReferences>>, TBuildRow = SpreadsheetBuildRowDefinition<SpreadsheetContextDataFromItems<TContextItems>, SpreadsheetRowData<SpreadsheetResolvedColumns<TColumns>, TReferences>>, TExtra extends {
-    importKey: string;
-} = {
-    importKey: string;
-}> = TExtra & SpreadsheetSchema<TContextItems, TColumns, TReferences, TRelations, TBuildRow>;
-export type ResolvedSpreadsheetSchema<TSchema> = TSchema extends {
-    columns?: infer TColumns;
-} ? TSchema & {
-    columns?: SpreadsheetResolvedColumns<TColumns>;
-} : TSchema;
+export type ExtractSpreadsheetContext<TSchema> = SpreadsheetSchemaParts<TSchema>['context'];
+export type ExtractSpreadsheetRow<TSchema> = SpreadsheetPrettify<SpreadsheetSchemaParts<TSchema>['row']>;
+export type ExtractSpreadsheetOutput<TSchema> = SpreadsheetSchemaParts<TSchema>['output'];
+export type ExtractSpreadsheetExisting<TSchema> = SpreadsheetLookupRecord<SpreadsheetSchemaParts<TSchema>['lookup']>;
+export type ExtractSpreadsheetKeyValue<TSchema> = SpreadsheetSchemaParts<TSchema>['key'];
+export type ExtractSpreadsheetFieldPath<TSchema> = SpreadsheetFieldPath<ExtractSpreadsheetRow<TSchema>>;
+/**
+ * A schema as the runtime reads it: every type parameter erased. Any schema made by
+ * `defineSpreadsheetSchema` fits it, because its callbacks are declared as methods and the
+ * functions the runtime passes to them accept anything.
+ */
+export interface SpreadsheetRuntimeSchema {
+    readonly key: string;
+    readonly file?: SpreadsheetFileDefinition;
+    /** Receives the builder; typed loosely so that the builder of any context fits. */
+    columns(c: {
+        readonly '~entries': readonly SpreadsheetEntry[];
+    }): {
+        readonly '~entries': readonly SpreadsheetEntry[];
+    };
+    readonly rows?: {
+        key?(row: SpreadsheetRecord): unknown;
+        readonly duplicates?: 'error' | 'keep-first' | 'keep-last';
+        readonly existing?: {
+            lookup(params: {
+                keys: readonly unknown[];
+                ctx: unknown;
+            }): unknown;
+            keyOf?(record: unknown): unknown;
+            readonly action?: SpreadsheetExistingAction | {
+                bivarianceHack(params: {
+                    row: SpreadsheetRecord;
+                    existing: unknown;
+                    ctx: unknown;
+                }): SpreadsheetExistingAction;
+            }['bivarianceHack'];
+        };
+    };
+    validate?(params: {
+        row: SpreadsheetRecord;
+        ctx: unknown;
+        issue: (field: never, message: string, options?: {
+            level?: SpreadsheetIssueLevel;
+            code?: string;
+        }) => SpreadsheetIssueInput;
+    }): readonly (SpreadsheetIssueInput | SpreadsheetFalsy)[];
+    output?(params: {
+        row: SpreadsheetRecord;
+        mode: Exclude<SpreadsheetRowMode, 'skip'>;
+        existing: unknown;
+        ctx: unknown;
+    }): unknown;
+    /** Type only. */
+    readonly '~context'?: unknown;
+}
 export {};

package/dist/runtime/spreadsheet/types/shared.d.ts

@@ -1,35 +1,33 @@
-import type { QueryFunction, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
 import type { GenericObject } from '#ui-tools/shared/types/utils';
-/** Runtime values decoded from spreadsheet cells, rows, and external references. */
+/** Runtime value read from a cell, a row, or the context. */
 export type SpreadsheetValue = GenericObject[string];
-/** Named row/context contract for spreadsheet data that is decoded at runtime. */
+/** Row or context data decoded at runtime. */
 export type SpreadsheetRecord = {
     [key: string]: SpreadsheetValue;
 };
-export type SpreadsheetQueryDefinition<TData = unknown> = Omit<UseQueryOptions<TData>, 'queryFn'> & {
-    queryKey: QueryKey;
-    queryFn?: QueryFunction<TData>;
-};
-export interface SpreadsheetCellValue {
+/** Severity of an issue: only `error` keeps a row out of the import. */
+export type SpreadsheetIssueLevel = 'info' | 'warning' | 'error';
+/** One cell as a column parser receives it. */
+export interface SpreadsheetCell {
+    /** Text as displayed in the file, trimmed. Edits made in review replace it. */
     text: string;
+    /** Typed value when the file stores one (number, boolean, date), otherwise the text. */
     raw: unknown;
+    /** Header of the column the cell comes from, or an empty string without a column. */
     header: string;
-    columnIndex: number;
+    /** 0-based index of the data row. */
     rowIndex: number;
 }
-export interface SpreadsheetHeaderMatchInput {
+/** A header cell of the selected sheet. */
+export interface SpreadsheetHeaderCell {
+    /** 0-based column index in the sheet. */
     index: number;
     text: string;
+    /** Text used for exact matching: no case, accents, or repeated spaces. */
     normalized: string;
 }
-export type SpreadsheetModifier = 'trim' | 'lowercase' | 'uppercase' | 'normalizeSpaces' | 'accent-insensitive' | 'case-insensitive';
-export type SpreadsheetHeaderMatcher = string | RegExp | ((params: {
-    header: SpreadsheetHeaderMatchInput;
-}) => number | null);
-export interface SpreadsheetMatchDefinition {
-    headers: readonly SpreadsheetHeaderMatcher[];
-    prefer?: 'first' | 'best-score';
-    minScore?: number;
-    required?: boolean;
-}
-export type SpreadsheetIssueLevel = 'info' | 'warning' | 'error';
+/** Removes `readonly` from arrays and flattens intersections, for readable inferred types. */
+export type SpreadsheetPrettify<T> = {
+    [K in keyof T]: T[K];
+} & NonNullable<unknown>;
+export type SpreadsheetUnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;

package/dist/runtime/spreadsheet/types/source.d.ts

@@ -1,20 +1,44 @@
-import type { ComputedRef, Ref } from 'vue';
-export interface SpreadsheetWorkbookSheet {
+/** One sheet of a file: displayed text of each non-empty row, typed cell values, row numbers. */
+export interface SpreadsheetSheet {
     name: string;
-    rows: readonly (readonly unknown[])[];
+    /** Text of each cell as displayed in the file, trimmed. Empty rows are left out. */
+    rows: readonly (readonly string[])[];
+    /** Typed values (number, boolean, `Date`) of each row, where the file stores one. */
+    raws: readonly (readonly unknown[] | undefined)[];
+    /** Row number in the file (1-based) of each row. */
+    rowNumbers: readonly number[];
 }
-export interface SpreadsheetWorkbookData {
-    fileName?: string;
-    sheets: readonly SpreadsheetWorkbookSheet[];
+export interface SpreadsheetWorkbook {
+    name: string;
+    sheets: readonly SpreadsheetSheet[];
+}
+/** What `importer.file.load` accepts. */
+export type SpreadsheetFileSource = File | Blob | ArrayBuffer | Uint8Array;
+/** A row of a sheet scored as a header row: how many columns of the schema its cells match. */
+export interface SpreadsheetHeaderRowCandidate {
+    /** 0-based index among the sheet's rows. */
+    index: number;
+    rowNumber: number;
+    matchCount: number;
+    /** First non-empty cells of the row. */
+    preview: readonly string[];
 }
-export interface SpreadsheetWorkbookSelection {
-    sheetName?: string;
-    headerRowIndex: number;
+export interface SpreadsheetSheetLayout {
+    name: string;
+    /** Best header row of the sheet. */
+    headerRow: number;
+    matchCount: number;
+    /** Data rows under the best header row. */
+    rowCount: number;
+    candidates: readonly SpreadsheetHeaderRowCandidate[];
 }
-export interface SpreadsheetWorkbookStatus {
-    initialized: boolean;
-    isParsing: boolean;
-    isReady: boolean;
+export interface SpreadsheetLayoutDetection {
+    sheets: readonly SpreadsheetSheetLayout[];
+    best: {
+        sheet: string;
+        headerRow: number;
+        matchCount: number;
+    } | null;
+    /** Several sheets match equally well. */
+    ambiguous: boolean;
 }
-export type SpreadsheetBinarySource = ArrayBuffer | Uint8Array | Blob | File;
-export type SpreadsheetBinaryRef = Ref<SpreadsheetBinarySource | null> | ComputedRef<SpreadsheetBinarySource | null>;

package/dist/runtime/spreadsheet/types/steps.d.ts

@@ -0,0 +1,76 @@
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { SpreadsheetFieldStatus, SpreadsheetFileModel, SpreadsheetReadiness, SpreadsheetSubmitModel } from './importer.js';
+/** What step checks read: the importer of any schema fits it. */
+export interface SpreadsheetStepContext {
+    readonly file: Pick<SpreadsheetFileModel, 'loaded' | 'reading'>;
+    readonly columns: {
+        readonly missing: readonly unknown[];
+        readonly fields: readonly {
+            readonly status: SpreadsheetFieldStatus;
+        }[];
+    };
+    readonly values: {
+        readonly open: readonly unknown[];
+        readonly questions: readonly unknown[];
+    };
+    readonly rows: {
+        readonly all: readonly unknown[];
+        readonly invalid: readonly unknown[];
+    };
+    readonly readiness: SpreadsheetReadiness;
+    readonly submit: Pick<SpreadsheetSubmitModel, 'status'>;
+}
+/** Keys of the built-in steps. */
+export type SpreadsheetBuiltInStep = 'file' | 'columns' | 'values' | 'review' | 'submit';
+/**
+ * A step of a wizard. Built-in steps come from `spreadsheetSteps.*`; a step of your own is the same
+ * object with its own `key`, label, and checks.
+ */
+export interface SpreadsheetStep {
+    key: string;
+    /** The built-in step this one is, for its default content. */
+    builtIn?: SpreadsheetBuiltInStep;
+    label?: LazyTextValue;
+    hint?: LazyTextValue;
+    /**
+     * `always` (default) shows the step; `when-needed` skips it when it has nothing to do, shown as
+     * done in the stepper.
+     */
+    show?: 'always' | 'when-needed';
+    /** Whether the user can move on. Defaults to `true`. */
+    ready?: (importer: SpreadsheetStepContext) => boolean;
+    /** With `show: 'when-needed'`: whether the step has something to do. Defaults to `true`. */
+    needed?: (importer: SpreadsheetStepContext) => boolean;
+    /** What still blocks the step, shown next to the navigation. */
+    blockers?: (importer: SpreadsheetStepContext) => number;
+}
+export type SpreadsheetStepState = 'done' | 'current' | 'upcoming' | 'skipped';
+/** A step with its state in the wizard. */
+export interface SpreadsheetStepStatus {
+    key: string;
+    builtIn: SpreadsheetBuiltInStep | null;
+    label: LazyTextValue | undefined;
+    hint: LazyTextValue | undefined;
+    state: SpreadsheetStepState;
+    /** 1-based position among the steps. */
+    position: number;
+    ready: boolean;
+    skipped: boolean;
+    blockers: number;
+}
+export interface SpreadsheetSteps {
+    readonly list: readonly SpreadsheetStepStatus[];
+    /** Key of the current step. */
+    readonly current: string;
+    readonly step: SpreadsheetStepStatus | null;
+    readonly canNext: boolean;
+    readonly canBack: boolean;
+    readonly isLast: boolean;
+    /** Moves to the next step that is not skipped, when the current one is ready. */
+    next(): void;
+    back(): void;
+    /** Moves to a step before the current one, or to the current one. */
+    goTo(key: string): void;
+    /** Back to the first step. */
+    reset(): void;
+}

package/dist/runtime/spreadsheet/types/validation.d.ts

@@ -1,76 +1,56 @@
-import type { SpreadsheetIssueLevel, SpreadsheetRecord } from './shared.js';
-export type SpreadsheetLazyMessage<TValue, TParams extends unknown[] = [], TMeta extends SpreadsheetRecord = NonNullable<unknown>> = string | (() => string) | ((ctx: SpreadsheetMessageContext<TValue, TParams, TMeta>) => string);
-export type SpreadsheetValidatorResult<TMeta extends SpreadsheetRecord = NonNullable<unknown>> = boolean | ({
-    $valid: boolean;
-} & TMeta);
-export type SpreadsheetMessageContext<TValue, TParams extends unknown[] = [], TMeta extends SpreadsheetRecord = NonNullable<unknown>> = {
-    [key: string]: SpreadsheetRecord[string];
-    $valid?: boolean;
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { SpreadsheetIssueLevel } from './shared.js';
+/** Message of a failed rule: text, lazy text, or a function of the value and the context. */
+export type SpreadsheetRuleMessage<TValue, TContext = unknown> = LazyTextValue | ((params: {
     value: TValue;
-    params: TParams;
-} & Partial<TMeta>;
-export interface SpreadsheetRuleOverrides<TValue, TParams extends unknown[] = [], TMeta extends SpreadsheetRecord = NonNullable<unknown>> {
-    message?: SpreadsheetLazyMessage<TValue, TParams, TMeta>;
+    ctx: TContext;
+}) => string);
+export interface SpreadsheetRuleOptions<TValue, TContext = unknown> {
+    message?: SpreadsheetRuleMessage<TValue, TContext>;
+    /** `error` (default) keeps the row out of the import; `warning` and `info` only inform. */
+    level?: SpreadsheetIssueLevel;
 }
-export interface SpreadsheetRuleFlags {
-    required?: true;
-}
-export interface SpreadsheetRuleExecutionResult<TMeta extends SpreadsheetRecord = SpreadsheetRecord> {
-    $valid: boolean;
-    $message: string | null;
-    $meta: TMeta;
-}
-export interface SpreadsheetRule<TValue, TFlags extends SpreadsheetRuleFlags = SpreadsheetRuleFlags> {
-    readonly flags?: TFlags;
-    readonly $rule: true;
-    readonly name?: string;
+/**
+ * A rule checks one value. Rules run on non-empty values only, except `required`; on a column
+ * with `multiple`, they run on each item.
+ */
+export interface SpreadsheetRule<TValue> {
+    readonly name: string;
     readonly level: SpreadsheetIssueLevel;
-    readonly validate: {
-        bivarianceHack: (value: TValue) => SpreadsheetRuleExecutionResult;
-    }['bivarianceHack'];
+    /** The rule also runs on empty values. */
+    readonly required: boolean;
+    /** Returns the message when the value fails, `null` when it passes. */
+    check(value: TValue, context: {
+        ctx: unknown;
+    }): string | null;
 }
-export type SpreadsheetFieldRules<TValue> = readonly SpreadsheetRule<TValue, SpreadsheetRuleFlags>[];
-export interface SpreadsheetRuleBuilder {
-    validate: <TValue, TMeta extends SpreadsheetRecord = NonNullable<unknown>>(options: {
+export interface SpreadsheetRuleBuilder<TContext> {
+    /** The value must not be empty. Prefer the column's `required` flag unless you need a level. */
+    required: (options?: SpreadsheetRuleOptions<unknown, TContext>) => SpreadsheetRule<unknown>;
+    /** A rule of your own. */
+    validate: <TValue>(options: {
         name?: string;
-        validator: (value: TValue) => SpreadsheetValidatorResult<TMeta>;
-        message: SpreadsheetLazyMessage<TValue, [], TMeta>;
+        validator: (value: TValue, context: {
+            ctx: TContext;
+        }) => boolean;
+        message: SpreadsheetRuleMessage<TValue, TContext>;
+        level?: SpreadsheetIssueLevel;
     }) => SpreadsheetRule<TValue>;
-    required: CreateSpreadsheetRuleReturn<unknown, [], NonNullable<unknown>, {
-        required: true;
-    }>;
-    maxLength: CreateSpreadsheetRuleReturn<string, [max: number], {
-        max: number;
-    }>;
-    minLength: CreateSpreadsheetRuleReturn<string, [min: number], {
-        min: number;
-    }>;
-    number: CreateSpreadsheetRuleReturn<number, [], NonNullable<unknown>>;
-    min: CreateSpreadsheetRuleReturn<number, [min: number], {
-        min: number;
-    }>;
-    max: CreateSpreadsheetRuleReturn<number, [max: number], {
-        max: number;
-    }>;
-    between: CreateSpreadsheetRuleReturn<number, [
-        min: number,
-        max: number
-    ], {
-        min: number;
-        max: number;
-    }>;
-    oneOf: <const TValues extends readonly unknown[]>(values: TValues, overrides?: SpreadsheetRuleOverrides<SpreadsheetWidenLiteral<TValues[number]>, [
-        TValues
-    ], {
-        values: TValues;
-    }>) => SpreadsheetRule<SpreadsheetWidenLiteral<TValues[number]>>;
+    email: (options?: SpreadsheetRuleOptions<string, TContext>) => SpreadsheetRule<string>;
+    pattern: (pattern: RegExp, options?: SpreadsheetRuleOptions<string, TContext>) => SpreadsheetRule<string>;
+    minLength: (min: number, options?: SpreadsheetRuleOptions<string, TContext>) => SpreadsheetRule<string>;
+    maxLength: (max: number, options?: SpreadsheetRuleOptions<string, TContext>) => SpreadsheetRule<string>;
+    min: (min: number, options?: SpreadsheetRuleOptions<number, TContext>) => SpreadsheetRule<number>;
+    max: (max: number, options?: SpreadsheetRuleOptions<number, TContext>) => SpreadsheetRule<number>;
+    between: (min: number, max: number, options?: SpreadsheetRuleOptions<number, TContext>) => SpreadsheetRule<number>;
+    /** ISO dates only: the date must not be after today. */
+    notFuture: (options?: SpreadsheetRuleOptions<string, TContext>) => SpreadsheetRule<string>;
 }
-export type SpreadsheetFieldRulesInput<TValue> = SpreadsheetFieldRules<TValue> | ((rules: SpreadsheetRuleBuilder) => SpreadsheetFieldRules<TValue>);
-export type CreateSpreadsheetRuleReturn<TValue, TParams extends unknown[], TMeta extends SpreadsheetRecord, TFlags extends SpreadsheetRuleFlags = NonNullable<unknown>> = TParams extends [] ? (overrides?: SpreadsheetRuleOverrides<TValue, TParams, TMeta>) => SpreadsheetRule<TValue, TFlags> : (...args: [...TParams, overrides?: SpreadsheetRuleOverrides<TValue, TParams, TMeta>]) => SpreadsheetRule<TValue, TFlags>;
-export type SpreadsheetWidenLiteral<TValue> = TValue extends string ? string : TValue extends number ? number : TValue extends boolean ? boolean : TValue;
-export type CreateSpreadsheetRule = <TValue, TParams extends unknown[], TMeta extends SpreadsheetRecord = NonNullable<unknown>, TFlags extends SpreadsheetRuleFlags = NonNullable<unknown>>(options: {
-    name?: string;
-    flags?: TFlags;
-    validator: (value: TValue, ...params: TParams) => SpreadsheetValidatorResult<TMeta>;
-    message: SpreadsheetLazyMessage<TValue, TParams, TMeta>;
-}) => CreateSpreadsheetRuleReturn<TValue, TParams, TMeta, TFlags>;
+/**
+ * Rules of a column. The function form also receives the row so far (the columns declared before
+ * this one) and the context, for rules that depend on another column.
+ */
+export type SpreadsheetRulesInput<TValue, TContext, TRow = unknown> = readonly SpreadsheetRule<TValue>[] | ((rules: SpreadsheetRuleBuilder<TContext>, params: {
+    row: TRow;
+    ctx: TContext;
+}) => readonly SpreadsheetRule<TValue>[]);