nuxt-ui-tools 0.1.0

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

@@ -0,0 +1,31 @@
+import type { InferSpreadsheetOptionValue, SpreadsheetOptionItem, SpreadsheetOptionsSource } from './options.js';
+import type { SpreadsheetReferenceSourcePath, SpreadsheetReferenceValueAtPath, SpreadsheetResolutionQueryResolver, SpreadsheetResolvedSelectionValue } from './resolution.js';
+import type { SpreadsheetFieldRulesInput } from './validation.js';
+type SpreadsheetReferenceSelectBaseConfig<TOption extends SpreadsheetOptionItem> = {
+    source: string;
+    options?: SpreadsheetOptionsSource<{
+        context: Record<string, unknown>;
+    }, TOption>;
+    getOptions?: SpreadsheetResolutionQueryResolver<Record<string, unknown>, Record<string, unknown>, TOption>;
+};
+export interface SpreadsheetReferenceDefinition<TField extends string = string, TValue = unknown, TOption extends SpreadsheetOptionItem = SpreadsheetOptionItem, TSource extends string = string, TRulesInput extends SpreadsheetFieldRulesInput<TValue> | undefined = SpreadsheetFieldRulesInput<TValue> | undefined> {
+    kind: 'select';
+    field: TField;
+    source: TSource;
+    options?: SpreadsheetOptionsSource<{
+        context: Record<string, unknown>;
+    }, TOption>;
+    getOptions?: SpreadsheetResolutionQueryResolver<Record<string, unknown>, Record<string, unknown>, TOption>;
+    rules?: SpreadsheetFieldRulesInput<TValue>;
+    __rulesInput?: TRulesInput;
+}
+export type SpreadsheetReferenceSelectConfig<TRow, TSource extends SpreadsheetReferenceSourcePath<TRow>, TOption extends SpreadsheetOptionItem, TValue = SpreadsheetResolvedSelectionValue<SpreadsheetReferenceValueAtPath<TRow, TSource>, InferSpreadsheetOptionValue<TOption>>, TRulesInput extends SpreadsheetFieldRulesInput<TValue> | undefined = SpreadsheetFieldRulesInput<TValue> | undefined> = Omit<SpreadsheetReferenceSelectBaseConfig<TOption>, 'source'> & {
+    source: TSource;
+    rules?: TRulesInput;
+};
+export type SpreadsheetReferenceValue<TSourceValue, TValue> = SpreadsheetResolvedSelectionValue<TSourceValue, TValue>;
+export interface SpreadsheetReferenceBuilder<TRow = Record<string, unknown>> {
+    select: <TField extends string, TSource extends SpreadsheetReferenceSourcePath<TRow>, const TOption extends SpreadsheetOptionItem, TValue = SpreadsheetReferenceValue<SpreadsheetReferenceValueAtPath<TRow, TSource>, InferSpreadsheetOptionValue<TOption>>, TRulesInput extends SpreadsheetFieldRulesInput<TValue> | undefined = SpreadsheetFieldRulesInput<TValue> | undefined>(field: TField, config: SpreadsheetReferenceSelectConfig<TRow, TSource, TOption, TValue, TRulesInput>) => SpreadsheetReferenceDefinition<TField, TValue, TOption, TSource, TRulesInput>;
+}
+export type InferSpreadsheetReferenceValue<TReference> = TReference extends SpreadsheetReferenceDefinition<string, infer TValue, SpreadsheetOptionItem> ? TValue : never;
+export {};

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

@@ -0,0 +1,43 @@
+import type { NestedPaths } from '../../shared/types/utils.js';
+import type { SpreadsheetContextDataFromItems, SpreadsheetContextItem } from './context.js';
+import type { InferSpreadsheetOptionValue, SpreadsheetOptionItem, SpreadsheetOptionsSource } from './options.js';
+import type { SpreadsheetQueryDefinition } from './shared.js';
+import type { SpreadsheetFieldRulesInput } from './validation.js';
+export type SpreadsheetResolvedSelectionValue<TSourceValue, TValue> = NonNullable<TSourceValue> extends readonly unknown[] ? TValue[] : TValue;
+export type SpreadsheetResolutionQueryResolver<TContext, TRow, TOption extends SpreadsheetOptionItem> = {
+    bivarianceHack: (params: {
+        context: TContext;
+        row: TRow;
+        search: string;
+    }) => SpreadsheetQueryDefinition<readonly TOption[]>;
+}['bivarianceHack'];
+export interface SpreadsheetColumnResolveDefinition<TContext = unknown, TSourceValue = unknown, TOption extends SpreadsheetOptionItem = SpreadsheetOptionItem, TValue = SpreadsheetResolvedSelectionValue<TSourceValue, InferSpreadsheetOptionValue<TOption>>> {
+    options: SpreadsheetOptionsSource<{
+        context: TContext;
+    }, TOption>;
+    getOptions?: SpreadsheetResolutionQueryResolver<TContext, Record<string, unknown>, TOption>;
+    __sourceValueType?: TSourceValue;
+    __valueType?: TValue;
+}
+export type InferSpreadsheetColumnResolveValue<TResolve> = TResolve extends SpreadsheetColumnResolveDefinition<unknown, unknown, SpreadsheetOptionItem, infer TValue> ? TValue : never;
+type SpreadsheetReferencePath<TRow> = Extract<NestedPaths<TRow>, string>;
+export type SpreadsheetReferenceValueAtPath<TRow, TPath extends string> = TPath extends `${infer TKey}.${infer TRest}` ? TKey extends keyof TRow ? SpreadsheetReferenceValueAtPath<NonNullable<TRow[TKey]>, TRest> : never : TPath extends keyof TRow ? TRow[TPath] : never;
+export interface SpreadsheetResolutionDefinition<TScope extends 'column' | 'reference' = 'column' | 'reference', TTargetField extends string = string, TSourceField extends string = string, TSourceValue = unknown, TValue = unknown, TOption extends SpreadsheetOptionItem = SpreadsheetOptionItem, TContext = Record<string, unknown>, TRow = Record<string, unknown>, TRulesInput extends SpreadsheetFieldRulesInput<TValue> | undefined = SpreadsheetFieldRulesInput<TValue> | undefined> {
+    kind: 'select';
+    scope: TScope;
+    targetField: TTargetField;
+    sourceField: TSourceField;
+    options?: SpreadsheetOptionsSource<{
+        context: TContext;
+    }, TOption>;
+    getOptions?: SpreadsheetResolutionQueryResolver<TContext, TRow, TOption>;
+    rules?: SpreadsheetFieldRulesInput<TValue>;
+    __rulesInput?: TRulesInput;
+    __sourceValueType?: TSourceValue;
+    __valueType?: TValue;
+}
+export type SpreadsheetReferenceSourcePath<TRow> = SpreadsheetReferencePath<TRow>;
+export type SpreadsheetSchemaContextData<TSchema> = TSchema extends {
+    context?: infer TContextItems extends readonly SpreadsheetContextItem<string, unknown>[];
+} ? SpreadsheetContextDataFromItems<TContextItems> : Record<string, unknown>;
+export {};

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

@@ -0,0 +1,58 @@
+import type { SpreadsheetColumnDefinition, SpreadsheetColumnGroupDefinition, SpreadsheetDynamicCollectionDefinition, SpreadsheetDynamicCollectionItemDefinition, SpreadsheetDynamicOptionGroupsDefinition } from './columns.js';
+import type { SpreadsheetIssueLevel } from './shared.js';
+export interface SpreadsheetHeaderCell {
+    index: number;
+    raw: unknown;
+    text: string;
+    normalized: string;
+}
+export interface SpreadsheetColumnAssignmentOption {
+    key: string;
+    label: string;
+    assigned: boolean;
+}
+export interface SpreadsheetColumnMatch<TColumn = SpreadsheetColumnDefinition<string, unknown, boolean, unknown>> {
+    key: string;
+    columnIndex: number;
+    header: SpreadsheetHeaderCell;
+    column: TColumn;
+}
+export interface SpreadsheetUnmatchedColumn<TColumn = SpreadsheetColumnDefinition<string, unknown, boolean, unknown>> {
+    key: string;
+    column: TColumn;
+}
+export interface SpreadsheetDynamicColumnMatch<TColumn = SpreadsheetDynamicOptionGroupsDefinition<string, string, unknown> | SpreadsheetDynamicCollectionDefinition<string, 'array' | 'record'>, TItem = SpreadsheetDynamicCollectionItemDefinition> {
+    key: string;
+    targetKey: string;
+    columnIndex: number;
+    header: SpreadsheetHeaderCell;
+    column: TColumn;
+    source: unknown;
+    item?: TItem;
+}
+export interface SpreadsheetRowIssue {
+    level: SpreadsheetIssueLevel;
+    code: string;
+    message: string;
+    rowIndex: number;
+    ruleKey?: string;
+    columnKey?: string;
+    columnIndex?: number;
+    header?: string;
+}
+export interface SpreadsheetParsedRow<TRow = Record<string, unknown>> {
+    index: number;
+    source: readonly unknown[];
+    data: TRow;
+    issues: readonly SpreadsheetRowIssue[];
+    isValid: boolean;
+}
+export interface SpreadsheetRowSummary {
+    totalRows: number;
+    validRows: number;
+    invalidRows: number;
+    issueCount: number;
+}
+export type SpreadsheetStaticColumn = SpreadsheetColumnDefinition<string, unknown, boolean, unknown>;
+export type SpreadsheetStaticColumnGroup = SpreadsheetColumnGroupDefinition<string, readonly SpreadsheetRuntimeStaticColumnEntry[]>;
+export type SpreadsheetRuntimeStaticColumnEntry = SpreadsheetStaticColumn | SpreadsheetStaticColumnGroup;

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

@@ -0,0 +1,87 @@
+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 { SpreadsheetFieldRules, SpreadsheetRuleBuilder } from './validation.js';
+export interface SpreadsheetFileDefinition {
+    accept?: readonly string[];
+    maxRecords?: number;
+}
+export interface SpreadsheetStepTextDefinition {
+    title?: LazyTextValue;
+    description?: LazyTextValue;
+}
+export interface SpreadsheetSheetStepDefinition extends SpreadsheetStepTextDefinition {
+    strategy?: 'fixed' | 'selection' | 'auto';
+}
+export interface SpreadsheetHeaderStepDefinition extends SpreadsheetStepTextDefinition {
+    strategy?: 'fixed' | 'first-row' | 'selection' | 'detected';
+}
+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;
+}
+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>>;
+}
+export type SpreadsheetRelationsDefinition<TRow> = readonly {
+    [TColumn in SpreadsheetRelationPath<TRow>]: SpreadsheetRelationDefinition<TRow, TColumn>;
+}[SpreadsheetRelationPath<TRow>][];
+export type SpreadsheetBuildRowDefinition<TContext = unknown, TRow = unknown> = (params: {
+    context: TContext;
+    row: TRow;
+}) => unknown | Promise<unknown>;
+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>>;
+    }>;
+};
+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 {};

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

@@ -0,0 +1,28 @@
+import type { QueryFunction, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
+export type SpreadsheetQueryDefinition<TData = unknown> = Omit<UseQueryOptions<TData>, 'queryFn'> & {
+    queryKey: QueryKey;
+    queryFn?: QueryFunction<TData>;
+};
+export interface SpreadsheetCellValue {
+    text: string;
+    raw: unknown;
+    header: string;
+    columnIndex: number;
+    rowIndex: number;
+}
+export interface SpreadsheetHeaderMatchInput {
+    index: number;
+    text: string;
+    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';

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

@@ -0,0 +1,20 @@
+import type { ComputedRef, Ref } from 'vue';
+export interface SpreadsheetWorkbookSheet {
+    name: string;
+    rows: readonly (readonly unknown[])[];
+}
+export interface SpreadsheetWorkbookData {
+    fileName?: string;
+    sheets: readonly SpreadsheetWorkbookSheet[];
+}
+export interface SpreadsheetWorkbookSelection {
+    sheetName?: string;
+    headerRowIndex: number;
+}
+export interface SpreadsheetWorkbookStatus {
+    initialized: boolean;
+    isParsing: boolean;
+    isReady: boolean;
+}
+export type SpreadsheetBinarySource = ArrayBuffer | Uint8Array | Blob | File;
+export type SpreadsheetBinaryRef = Ref<SpreadsheetBinarySource | null> | ComputedRef<SpreadsheetBinarySource | null>;

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

@@ -0,0 +1,76 @@
+import type { SpreadsheetIssueLevel } from './shared.js';
+export type SpreadsheetLazyMessage<TValue, TParams extends unknown[] = [], TMeta extends Record<string, unknown> = {}> = string | (() => string) | ((ctx: SpreadsheetMessageContext<TValue, TParams, TMeta>) => string);
+export type SpreadsheetValidatorResult<TMeta extends Record<string, unknown> = {}> = boolean | ({
+    $valid: boolean;
+} & TMeta);
+export type SpreadsheetMessageContext<TValue, TParams extends unknown[] = [], TMeta extends Record<string, unknown> = {}> = {
+    [key: string]: unknown;
+    $valid?: boolean;
+    value: TValue;
+    params: TParams;
+} & Partial<TMeta>;
+export interface SpreadsheetRuleOverrides<TValue, TParams extends unknown[] = [], TMeta extends Record<string, unknown> = {}> {
+    message?: SpreadsheetLazyMessage<TValue, TParams, TMeta>;
+}
+export interface SpreadsheetRuleFlags {
+    required?: true;
+}
+export interface SpreadsheetRuleExecutionResult<TMeta extends Record<string, unknown> = Record<string, unknown>> {
+    $valid: boolean;
+    $message: string | null;
+    $meta: TMeta;
+}
+export interface SpreadsheetRule<TValue, TFlags extends SpreadsheetRuleFlags = SpreadsheetRuleFlags> {
+    readonly flags?: TFlags;
+    readonly $rule: true;
+    readonly name?: string;
+    readonly level: SpreadsheetIssueLevel;
+    readonly validate: {
+        bivarianceHack: (value: TValue) => SpreadsheetRuleExecutionResult;
+    }['bivarianceHack'];
+}
+export type SpreadsheetFieldRules<TValue> = readonly SpreadsheetRule<TValue, SpreadsheetRuleFlags>[];
+export interface SpreadsheetRuleBuilder {
+    validate: <TValue, TMeta extends Record<string, unknown> = {}>(options: {
+        name?: string;
+        validator: (value: TValue) => SpreadsheetValidatorResult<TMeta>;
+        message: SpreadsheetLazyMessage<TValue, [], TMeta>;
+    }) => SpreadsheetRule<TValue>;
+    required: CreateSpreadsheetRuleReturn<unknown, [], {}, {
+        required: true;
+    }>;
+    maxLength: CreateSpreadsheetRuleReturn<string, [max: number], {
+        max: number;
+    }>;
+    minLength: CreateSpreadsheetRuleReturn<string, [min: number], {
+        min: number;
+    }>;
+    number: CreateSpreadsheetRuleReturn<number, [], {}>;
+    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]>>;
+}
+export type SpreadsheetFieldRulesInput<TValue> = SpreadsheetFieldRules<TValue> | ((rules: SpreadsheetRuleBuilder) => SpreadsheetFieldRules<TValue>);
+export type CreateSpreadsheetRuleReturn<TValue, TParams extends unknown[], TMeta extends Record<string, unknown>, TFlags extends SpreadsheetRuleFlags = {}> = 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 Record<string, unknown> = {}, TFlags extends SpreadsheetRuleFlags = {}>(options: {
+    name?: string;
+    flags?: TFlags;
+    validator: (value: TValue, ...params: TParams) => SpreadsheetValidatorResult<TMeta>;
+    message: SpreadsheetLazyMessage<TValue, TParams, TMeta>;
+}) => CreateSpreadsheetRuleReturn<TValue, TParams, TMeta, TFlags>;

package/dist/runtime/spreadsheet/utils/builders/core.d.ts

@@ -0,0 +1,17 @@
+import type { SpreadsheetColumnBuilder, SpreadsheetColumnsDefinition, SpreadsheetDynamicBuilder, SpreadsheetGroupBuilder, SpreadsheetReferenceBuilder, SpreadsheetReferenceDefinition, SpreadsheetResolvedColumns, SpreadsheetBuildRowDefinition } from '../../types/index.js';
+export declare function createSpreadsheetColumnBuilder<TContext = unknown>(): SpreadsheetColumnBuilder<TContext>;
+export declare function createSpreadsheetGroupBuilder(): SpreadsheetGroupBuilder;
+export declare function createSpreadsheetDynamicBuilder<TContext>(context: TContext): SpreadsheetDynamicBuilder<TContext>;
+export declare function defineSpreadsheetColumns<TContext, const TColumns extends {
+    static?: unknown;
+    dynamic?: unknown;
+}>(columns: TColumns & SpreadsheetColumnsDefinition<TContext>): TColumns;
+export declare function createSpreadsheetReferenceBuilder<_TContext, TRow>(): SpreadsheetReferenceBuilder<TRow>;
+export declare function defineSpreadsheetReference<const TDefinition extends SpreadsheetReferenceDefinition>(definition: TDefinition): TDefinition;
+export declare function defineSpreadsheetReferences<const TReferences extends readonly unknown[]>(references: TReferences): TReferences;
+export declare function defineSpreadsheetBuildRow<TContext, TRow, const TBuildRow extends SpreadsheetBuildRowDefinition<TContext, TRow>>(buildRow: TBuildRow): TBuildRow;
+export declare function resolveSpreadsheetReferences<TReferences>(references: TReferences): TReferences;
+export declare function resolveSpreadsheetReferences<TRow, TReferences>(references: ((reference: SpreadsheetReferenceBuilder<TRow>) => TReferences) | undefined): TReferences | undefined;
+export declare function resolveCollection<TBuilderTuple extends readonly unknown[], TResult>(collection: (...builders: TBuilderTuple) => TResult, ...builders: TBuilderTuple): TResult;
+export declare function resolveCollection<TBuilderTuple extends readonly unknown[], TResult>(collection: TResult, ...builders: TBuilderTuple): TResult;
+export declare function resolveSpreadsheetColumns<TColumns>(columns: TColumns): TColumns extends SpreadsheetColumnsDefinition<any> ? SpreadsheetResolvedColumns<TColumns> : TColumns;

package/dist/runtime/spreadsheet/utils/builders/core.js

@@ -0,0 +1,250 @@
+import { resolveSpreadsheetRules } from "../validation/index.js";
+export function createSpreadsheetColumnBuilder() {
+  const textColumn = (key, options = {}) => {
+    const rules = resolveSpreadsheetRules(options.rules);
+    return {
+      kind: "text",
+      key,
+      ...options,
+      rules
+    };
+  };
+  const enumColumn = (key, options) => {
+    const rules = resolveSpreadsheetRules(options.rules);
+    return {
+      kind: "enum",
+      key,
+      label: options.label,
+      required: options.required,
+      match: options.match,
+      from: options.from,
+      multiple: options.multiple,
+      parse: options.parse,
+      options: options.options,
+      rules
+    };
+  };
+  const numberColumn = (key, options = {}) => {
+    const rules = resolveSpreadsheetRules(options.rules);
+    return {
+      kind: "number",
+      key,
+      ...options,
+      rules
+    };
+  };
+  return {
+    text: textColumn,
+    email(key, options = {}) {
+      const rules = resolveSpreadsheetRules(options.rules);
+      return {
+        kind: "email",
+        key,
+        ...options,
+        rules
+      };
+    },
+    number: numberColumn,
+    date(key, options = {}) {
+      const rules = resolveSpreadsheetRules(options.rules);
+      return {
+        kind: "date",
+        key,
+        ...options,
+        rules
+      };
+    },
+    boolean(key, options = {}) {
+      const rules = resolveSpreadsheetRules(options.rules);
+      return {
+        kind: "boolean",
+        key,
+        ...options,
+        rules
+      };
+    },
+    enum: enumColumn,
+    option(key, options) {
+      const rules = resolveSpreadsheetRules(options.rules);
+      return {
+        kind: "option",
+        key,
+        ...options,
+        rules
+      };
+    }
+  };
+}
+export function createSpreadsheetGroupBuilder() {
+  return (key, columns) => ({
+    kind: "group",
+    key,
+    columns
+  });
+}
+function createSpreadsheetDynamicValueBuilder() {
+  function options(config) {
+    if (config.mode === "multiple")
+      return {
+        kind: "options",
+        from: config.from,
+        mode: "multiple",
+        separator: config.separator,
+        matchBy: config.matchBy,
+        itemModifiers: config.itemModifiers
+      };
+    return {
+      kind: "options",
+      from: config.from,
+      mode: "single",
+      separator: config.separator,
+      matchBy: config.matchBy,
+      itemModifiers: config.itemModifiers
+    };
+  }
+  const builder = {
+    text(config = {}) {
+      return {
+        kind: "text",
+        modifiers: config.modifiers
+      };
+    },
+    number() {
+      return {
+        kind: "number"
+      };
+    },
+    date() {
+      return {
+        kind: "date"
+      };
+    },
+    boolean() {
+      return {
+        kind: "boolean"
+      };
+    },
+    options
+  };
+  return builder;
+}
+function isSpreadsheetDynamicValueResolver(definition) {
+  return typeof definition === "function";
+}
+function buildSpreadsheetCollectionItems(params) {
+  return params.from({ context: params.context }).map((source) => {
+    const item = params.each(source);
+    return {
+      ...item,
+      value: params.resolveValue(item),
+      source
+    };
+  });
+}
+export function createSpreadsheetDynamicBuilder(context) {
+  function resolveDynamicCollectionValue(definition) {
+    if (isSpreadsheetDynamicValueResolver(definition))
+      return definition(createSpreadsheetDynamicValueBuilder());
+    return definition;
+  }
+  return {
+    optionGroups(config) {
+      return {
+        kind: "option-groups",
+        key: config.key,
+        source: config.source,
+        itemKey: config.itemKey,
+        itemLabel: config.itemLabel,
+        targetKey: config.targetKey,
+        header: config.header,
+        options: config.options,
+        values: config.values,
+        output: config.output
+      };
+    },
+    arrayFromCollection(rootKey, config) {
+      const items = buildSpreadsheetCollectionItems({
+        context,
+        from: config.from,
+        each: config.each,
+        resolveValue: (item) => resolveDynamicCollectionValue(item.value)
+      });
+      return {
+        kind: "collection",
+        rootKey,
+        as: "array",
+        items
+      };
+    },
+    recordFromCollection(rootKey, config) {
+      const items = buildSpreadsheetCollectionItems({
+        context,
+        from: config.from,
+        each: config.each,
+        resolveValue: (item) => resolveDynamicCollectionValue(item.value)
+      });
+      return {
+        kind: "collection",
+        rootKey,
+        as: "record",
+        items
+      };
+    }
+  };
+}
+export function defineSpreadsheetColumns(columns) {
+  return columns;
+}
+export function createSpreadsheetReferenceBuilder() {
+  const builder = {
+    select(field, config) {
+      return {
+        kind: "select",
+        field,
+        source: config.source,
+        options: config.options,
+        getOptions: config.getOptions,
+        rules: resolveSpreadsheetRules(config.rules)
+      };
+    }
+  };
+  return builder;
+}
+export function defineSpreadsheetReference(definition) {
+  return definition;
+}
+export function defineSpreadsheetReferences(references) {
+  return references;
+}
+export function defineSpreadsheetBuildRow(buildRow) {
+  return buildRow;
+}
+function isSpreadsheetReferenceResolver(references) {
+  return typeof references === "function";
+}
+export function resolveSpreadsheetReferences(references) {
+  if (!references) return void 0;
+  if (isSpreadsheetReferenceResolver(references))
+    return references(createSpreadsheetReferenceBuilder());
+  return references;
+}
+function isCollectionResolver(collection) {
+  return typeof collection === "function";
+}
+export function resolveCollection(collection, ...builders) {
+  if (!collection) return void 0;
+  if (isCollectionResolver(collection)) return collection(...builders);
+  return collection;
+}
+export function resolveSpreadsheetColumns(columns) {
+  if (!columns || typeof columns !== "object") return columns;
+  const staticColumns = "static" in columns ? resolveCollection(
+    columns.static,
+    createSpreadsheetColumnBuilder(),
+    createSpreadsheetGroupBuilder()
+  ) : void 0;
+  return {
+    ...columns,
+    static: staticColumns
+  };
+}

package/dist/runtime/spreadsheet/utils/builders/index.d.ts

@@ -0,0 +1 @@
+export * from './core.js';

package/dist/runtime/spreadsheet/utils/builders/index.js

@@ -0,0 +1 @@
+export * from "./core.js";

package/dist/runtime/spreadsheet/utils/context.d.ts

@@ -0,0 +1,20 @@
+import type { SpreadsheetContextItem, SpreadsheetContextDataFromItems } from '../types/index.js';
+export interface SpreadsheetContextQueryResult {
+    key?: string;
+    data?: unknown;
+    error?: unknown;
+    isPending?: boolean;
+    isFetching?: boolean;
+    isSuccess?: boolean;
+    isRefetching?: boolean;
+    refetch: () => Promise<unknown>;
+}
+export declare function createSpreadsheetContextQueries<TItems extends readonly SpreadsheetContextItem<string, unknown>[]>(items: TItems): import("../types/index.js").SpreadsheetQueryDefinition<unknown>[];
+export declare function createSpreadsheetContextData<TItems extends readonly SpreadsheetContextItem<string, unknown>[]>(items: TItems, results: readonly Pick<SpreadsheetContextQueryResult, 'data'>[]): Partial<SpreadsheetContextDataFromItems<TItems>>;
+export declare function createSpreadsheetContextStatus(results: readonly Pick<SpreadsheetContextQueryResult, 'isPending' | 'isFetching' | 'isSuccess' | 'isRefetching'>[]): {
+    initialized: boolean;
+    isPending: boolean;
+    isFetching: boolean;
+    isReady: boolean;
+    isRefreshing: boolean;
+};