nuxt-ui-tools 1.11.2 → 1.13.0

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

@@ -0,0 +1,77 @@
+import type { SpreadsheetUnknownPolicy } from './columns.js';
+import type { SpreadsheetResolvedOption } from './options.js';
+/** An answer to a value that is not an option; it applies to every row with the value. */
+export type SpreadsheetValueAnswer = {
+    action: 'map';
+    value: unknown;
+    label: string;
+} | {
+    action: 'leave-empty';
+} | {
+    action: 'skip-rows';
+} | {
+    action: 'create';
+};
+/** Answers by field path, then by answer key (see `SpreadsheetValueQuestion['key']`). */
+export type SpreadsheetValueAnswers = Readonly<Record<string, Readonly<Record<string, SpreadsheetValueAnswer>>>>;
+/** A field whose value decides the options, with its values in the rows of a question. */
+export interface SpreadsheetValueScopeField {
+    field: string;
+    label: string;
+    /** Distinct values, as displayed. */
+    values: readonly string[];
+}
+/**
+ * The set of options a value was checked against, when a column's options depend on the row
+ * (`options: ({ row }) => …`). The same value is asked once per set of options.
+ */
+export interface SpreadsheetValueScope {
+    id: string;
+    /** Fields the options read, with their values in the question's rows: `Product: English`. */
+    dependsOn: readonly SpreadsheetValueScopeField[];
+}
+/** One distinct value of a select column that matches no option. */
+export interface SpreadsheetValueQuestion<TPath extends string = string> {
+    /** `field::key` */
+    id: string;
+    field: TPath;
+    fieldLabel: string;
+    /** Value as written in the file (first occurrence). */
+    value: string;
+    /** The answer key: the normalized value, prefixed by the scope id when there is a scope. */
+    key: string;
+    /** Set of options the value was checked against, when they depend on the row. */
+    scope: SpreadsheetValueScope | null;
+    /** Options the value can map to. Empty for a remote list: search it. */
+    choices: readonly SpreadsheetResolvedOption[];
+    /** Header of the column the value comes from. */
+    header: string;
+    /** Indexes of the rows using the value. */
+    rows: readonly number[];
+    state: 'open' | 'answered';
+    answer: SpreadsheetValueAnswer | null;
+    /** `policy` when the column's `unknown` policy answered. */
+    answeredBy: 'user' | 'policy' | null;
+    policy: SpreadsheetUnknownPolicy;
+    /** The column can create new values. */
+    canCreate: boolean;
+    /** Choices come from a remote search rather than a list. */
+    remote: boolean;
+}
+/** A distinct value of a select column that matched an option. */
+export interface SpreadsheetRecognizedValue<TPath extends string = string> {
+    field: TPath;
+    value: string;
+    /** Id of the set of options, when they depend on the row. */
+    scope: string | null;
+    option: SpreadsheetResolvedOption;
+    rows: readonly number[];
+}
+/** Options of a select field, resolved and indexed for exact matching. */
+export interface SpreadsheetFieldOptions {
+    status: 'loading' | 'ready' | 'error';
+    options: readonly SpreadsheetResolvedOption[];
+    index: ReadonlyMap<string, SpreadsheetResolvedOption>;
+    remote: boolean;
+    error: unknown;
+}

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

@@ -0,0 +1,2 @@
+/** Saves a file built in the browser. */
+export declare function downloadSpreadsheetBlob(blob: Blob, name: string): void;

package/dist/runtime/spreadsheet/utils/download.js

@@ -0,0 +1,8 @@
+export function downloadSpreadsheetBlob(blob, name) {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = name;
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

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

@@ -0,0 +1,26 @@
+import type { SpreadsheetField, SpreadsheetFieldOptions, SpreadsheetRowIssue } from '../types/index.js';
+/**
+ * The rows as they are in the file, edits included, with an extra column listing their issues, so
+ * they can be fixed and imported again.
+ */
+export declare function createSpreadsheetIssuesWorkbook(params: {
+    headers: readonly string[];
+    rows: readonly {
+        cells: readonly string[];
+        issues: readonly SpreadsheetRowIssue[];
+    }[];
+    issuesHeader: string;
+    labels: ReadonlyMap<string, string>;
+}): Blob;
+/**
+ * The file to fill in: one column per field that reads its own column, named by its first declared
+ * header, and a sheet describing each column and its allowed values.
+ */
+export declare function createSpreadsheetTemplateWorkbook(params: {
+    fields: readonly SpreadsheetField[];
+    options: ReadonlyMap<string, SpreadsheetFieldOptions>;
+    sheetName: string;
+    guideName: string;
+    guideHeaders: readonly [column: string, required: string, allowed: string, description: string];
+    yes: string;
+}): Blob;

package/dist/runtime/spreadsheet/utils/export.js

@@ -0,0 +1,50 @@
+import { utils, write } from "xlsx";
+const XLSX_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+function toBlob(sheets) {
+  const workbook = utils.book_new();
+  for (const sheet of sheets)
+    utils.book_append_sheet(
+      workbook,
+      utils.aoa_to_sheet(sheet.rows.map((row) => [...row])),
+      sheet.name.slice(0, 31)
+    );
+  const binary = write(workbook, { bookType: "xlsx", type: "array" });
+  return new Blob([binary], { type: XLSX_TYPE });
+}
+export function createSpreadsheetIssuesWorkbook(params) {
+  return toBlob([
+    {
+      name: "Rows",
+      rows: [
+        [...params.headers, params.issuesHeader],
+        ...params.rows.map((row) => [
+          ...row.cells,
+          row.issues.map(
+            (issue) => issue.field ? `${params.labels.get(issue.field) ?? issue.field}: ${issue.message}` : issue.message
+          ).join("\n")
+        ])
+      ]
+    }
+  ]);
+}
+export function createSpreadsheetTemplateWorkbook(params) {
+  const fields = params.fields.filter((field) => !field.select?.from);
+  return toBlob([
+    {
+      name: params.sheetName,
+      rows: [fields.map((field) => field.name), fields.map((field) => field.example)]
+    },
+    {
+      name: params.guideName,
+      rows: [
+        [...params.guideHeaders],
+        ...fields.map((field) => [
+          field.name,
+          field.required ? params.yes : "",
+          (params.options.get(field.path)?.options ?? []).slice(0, 50).map((option) => option.label).join(", "),
+          field.description
+        ])
+      ]
+    }
+  ]);
+}

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

@@ -0,0 +1,26 @@
+import type { UiToolsTranslator } from '#ui-tools/i18n';
+import type { SpreadsheetEntry, SpreadsheetField, SpreadsheetFieldGroup, SpreadsheetRecord } from '../types/index.js';
+/** `secureCode` → `Secure code`. */
+export declare function humanizeSpreadsheetKey(key: string): string;
+/**
+ * Paths of the row a function reads, found by running it on a recording row. Reading a missing
+ * value returns a recording object too, so `row.levels.general` is seen whole; converting one to
+ * text gives `''`.
+ */
+export declare function recordSpreadsheetRowReads(read: (row: SpreadsheetRecord) => unknown): {
+    paths: Set<string>;
+    result: unknown;
+};
+/**
+ * Resolves the schema's columns for a context: groups are flattened into field paths, dynamic
+ * groups get one column per item, columns and groups whose `when` returns `false` are left out,
+ * and texts, rules, and options depending on the row are resolved.
+ */
+export declare function resolveSpreadsheetFields(params: {
+    entries: readonly SpreadsheetEntry[];
+    ctx: unknown;
+    t: UiToolsTranslator;
+}): {
+    fields: SpreadsheetField[];
+    groups: SpreadsheetFieldGroup[];
+};

package/dist/runtime/spreadsheet/utils/fields.js

@@ -0,0 +1,169 @@
+import { resolveTextValue } from "#ui-tools/shared/utils/render";
+import { createSpreadsheetColumnFactory } from "../schema/builder.js";
+import {
+  isSpreadsheetMatcherList,
+  isSpreadsheetOptionList,
+  isSpreadsheetOptionsResolver,
+  isSpreadsheetRowCallback,
+  isSpreadsheetRuleList
+} from "./guards.js";
+import { isSpreadsheetRecord } from "./paths.js";
+import { createSpreadsheetRuleBuilder } from "./rules.js";
+const DEFAULT_TRUE = ["yes", "y", "oui", "o", "true", "vrai", "x", "1"];
+const DEFAULT_FALSE = ["no", "n", "non", "false", "faux", "0"];
+export function humanizeSpreadsheetKey(key) {
+  const words = key.replaceAll(/([a-z\d])([A-Z])/gu, "$1 $2").replaceAll(/[_-]+/gu, " ").trim().toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function isOptionsConfig(input) {
+  return isSpreadsheetRecord(input) && "source" in input && !("queryKey" in input) && !("load" in input);
+}
+function toMatchers(value) {
+  if (value === void 0) return [];
+  return isSpreadsheetMatcherList(value) ? value : [value];
+}
+function resolveRules(column, t, ctx) {
+  const rules = column.config.rules;
+  if (!rules) return { rulesOf: () => [], staticRules: true };
+  if (isSpreadsheetRuleList(rules)) return { rulesOf: () => rules, staticRules: true };
+  const builder = createSpreadsheetRuleBuilder(t);
+  if (rules.length >= 2)
+    return { rulesOf: (row) => rules(builder, { ctx, row }), staticRules: false };
+  const resolved = rules(builder, { ctx, row: {} });
+  return { rulesOf: () => resolved, staticRules: true };
+}
+export function recordSpreadsheetRowReads(read) {
+  const paths = /* @__PURE__ */ new Set();
+  function record(prefix) {
+    return new Proxy(
+      {},
+      {
+        get(_, property) {
+          if (property === Symbol.toPrimitive) return () => "";
+          if (typeof property !== "string") return void 0;
+          const path = prefix ? `${prefix}.${property}` : property;
+          paths.add(path);
+          return record(path);
+        }
+      }
+    );
+  }
+  let result = void 0;
+  try {
+    result = read(record(""));
+  } catch {
+  }
+  return { paths, result };
+}
+function resolveRowOptions(params) {
+  const source = params.source;
+  if (!isSpreadsheetOptionsResolver(source)) return null;
+  const { paths, result } = recordSpreadsheetRowReads((row) => source({ ctx: params.ctx, row }));
+  if (!paths.size) return null;
+  if (result !== void 0 && !isSpreadsheetOptionList(result))
+    throw new Error(`[spreadsheet] "${params.path}" reads the row: its options must be a list.`);
+  return {
+    dependsOn: params.fieldPaths.filter((path) => paths.has(path)),
+    resolve: (row) => {
+      const resolved = source({ ctx: params.ctx, row });
+      return isSpreadsheetOptionList(resolved) ? resolved : [];
+    }
+  };
+}
+function resolveColumn(params) {
+  const { column, ctx } = params;
+  const config = column.config;
+  const path = params.parent ? `${params.parent}.${column.key}` : column.key;
+  const label = resolveTextValue(config.label, humanizeSpreadsheetKey(column.key));
+  const declared = toMatchers(config.headers);
+  const headers = [label, column.key, ...declared];
+  const name = declared.find((matcher) => typeof matcher === "string");
+  const fallback = config.default;
+  const defaultOf = fallback === void 0 ? null : isSpreadsheetRowCallback(fallback) ? (row) => fallback({ ctx, row }) : () => fallback;
+  const multiple = config.multiple;
+  const separator = multiple === true ? "," : multiple ? multiple.separator ?? "," : null;
+  let select = null;
+  if (column.kind === "select" && config.options) {
+    const options = config.options;
+    const create = isOptionsConfig(options) ? options.create ?? null : null;
+    const unknown = config.unknown ?? "ask";
+    if (unknown === "create" && !create)
+      throw new Error(`[spreadsheet] "${path}" sets unknown: 'create' without options.create.`);
+    const source = isOptionsConfig(options) ? options.source : options;
+    select = {
+      create,
+      from: config.from ?? null,
+      rowOptions: resolveRowOptions({ ctx, fieldPaths: params.fieldPaths, path, source }),
+      source,
+      unknown
+    };
+  }
+  return {
+    decimal: config.decimal ?? ".",
+    defaultOf,
+    description: resolveTextValue(config.description),
+    editable: config.editable ?? true,
+    example: resolveTextValue(config.example),
+    falseTexts: config.false ?? DEFAULT_FALSE,
+    formats: config.formats ?? [],
+    group: params.group,
+    hasDefault: fallback !== void 0,
+    headers,
+    kind: column.kind,
+    label,
+    name: typeof name === "string" ? name : label,
+    parse: config.parse ?? null,
+    path,
+    required: config.required ?? false,
+    ...resolveRules(column, params.t, ctx),
+    select,
+    separator,
+    trueTexts: config.true ?? DEFAULT_TRUE
+  };
+}
+function buildDynamicColumns(entry, ctx) {
+  const factory = createSpreadsheetColumnFactory();
+  return entry.config.items({ ctx }).map((item) => entry.config.column(item, factory));
+}
+export function resolveSpreadsheetFields(params) {
+  const fields = [];
+  const groups = [];
+  const visible = (entry) => !entry.config.when || entry.config.when({ ctx: params.ctx });
+  function add(column, parent, group) {
+    if (!visible(column)) return;
+    fields.push(
+      resolveColumn({
+        column,
+        ctx: params.ctx,
+        fieldPaths: fields.map((field) => field.path),
+        group,
+        parent,
+        t: params.t
+      })
+    );
+  }
+  for (const entry of params.entries) {
+    if (entry.entry === "column") {
+      add(entry, "", null);
+      continue;
+    }
+    if (!visible(entry)) continue;
+    const group = {
+      description: resolveTextValue(entry.config.description),
+      dynamic: entry.entry === "dynamic",
+      label: resolveTextValue(entry.config.label, humanizeSpreadsheetKey(entry.key)),
+      path: entry.key
+    };
+    groups.push(group);
+    const columns = entry.entry === "group" ? entry.children : buildDynamicColumns(entry, params.ctx);
+    for (const column of columns) add(column, entry.key, group);
+  }
+  for (const [index, field] of fields.entries()) {
+    const from = field.select?.from;
+    if (from && !fields.slice(0, index).some((other) => other.path === from))
+      throw new Error(
+        `[spreadsheet] "${field.path}" reads from "${from}", which is not a column above.`
+      );
+  }
+  return { fields, groups };
+}

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

@@ -0,0 +1,18 @@
+import type { SpreadsheetContextCallback, SpreadsheetHeaderMatcher, SpreadsheetRowCallback, SpreadsheetOptionEntry, SpreadsheetOptionItem, SpreadsheetOptionsResolver, SpreadsheetOptionsSource, SpreadsheetRule, SpreadsheetRuleBuilder, SpreadsheetRuleMessage, SpreadsheetRecord, SpreadsheetRowKey } from '../types/index.js';
+export declare function isSpreadsheetContextCallback<TResult>(value: unknown): value is SpreadsheetContextCallback<unknown, TResult>;
+export declare function isSpreadsheetRowCallback<TResult>(value: unknown): value is SpreadsheetRowCallback<unknown, SpreadsheetRecord, TResult>;
+export declare function isSpreadsheetRuleList(value: readonly SpreadsheetRule<unknown>[] | {
+    bivarianceHack(rules: SpreadsheetRuleBuilder<unknown>, params: {
+        row: unknown;
+        ctx: unknown;
+    }): readonly SpreadsheetRule<unknown>[];
+}['bivarianceHack']): value is readonly SpreadsheetRule<unknown>[];
+export declare function isSpreadsheetMatcherList(value: SpreadsheetHeaderMatcher | readonly SpreadsheetHeaderMatcher[]): value is readonly SpreadsheetHeaderMatcher[];
+export declare function isSpreadsheetOptionsResolver(value: SpreadsheetOptionsSource<unknown, SpreadsheetOptionItem, unknown>): value is SpreadsheetOptionsResolver<unknown, SpreadsheetOptionItem, unknown>;
+export declare function isSpreadsheetOptionList(value: unknown): value is readonly SpreadsheetOptionItem[];
+export declare function isSpreadsheetOptionEntry(value: SpreadsheetOptionItem): value is SpreadsheetOptionEntry;
+export declare function isSpreadsheetMessageFunction<TValue>(value: SpreadsheetRuleMessage<TValue, unknown>): value is (params: {
+    value: TValue;
+    ctx: unknown;
+}) => string;
+export declare function isSpreadsheetKeyTuple(value: SpreadsheetRowKey): value is readonly (string | number)[];

package/dist/runtime/spreadsheet/utils/guards.js

@@ -0,0 +1,27 @@
+export function isSpreadsheetContextCallback(value) {
+  return typeof value === "function";
+}
+export function isSpreadsheetRowCallback(value) {
+  return typeof value === "function";
+}
+export function isSpreadsheetRuleList(value) {
+  return Array.isArray(value);
+}
+export function isSpreadsheetMatcherList(value) {
+  return Array.isArray(value);
+}
+export function isSpreadsheetOptionsResolver(value) {
+  return typeof value === "function";
+}
+export function isSpreadsheetOptionList(value) {
+  return Array.isArray(value);
+}
+export function isSpreadsheetOptionEntry(value) {
+  return typeof value === "object" && value !== null && "value" in value;
+}
+export function isSpreadsheetMessageFunction(value) {
+  return typeof value === "function";
+}
+export function isSpreadsheetKeyTuple(value) {
+  return Array.isArray(value);
+}

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

@@ -0,0 +1,15 @@
+import type { SpreadsheetField, SpreadsheetHeaderCell } from '../types/index.js';
+export declare function createSpreadsheetHeaderCells(row: readonly string[]): SpreadsheetHeaderCell[];
+/** Whether a header is one of the field's declared names. */
+export declare function isSpreadsheetHeaderOf(field: SpreadsheetField, header: SpreadsheetHeaderCell, ctx: unknown): boolean;
+/**
+ * Assigns a column to each field that reads its own column. Choices made by the user come first
+ * (`null` leaves the field out); then each field takes the first free header that is one of its
+ * names. Nothing is guessed.
+ */
+export declare function matchSpreadsheetHeaders(params: {
+    fields: readonly SpreadsheetField[];
+    headers: readonly SpreadsheetHeaderCell[];
+    ctx: unknown;
+    manual?: Readonly<Record<string, number | null>>;
+}): Map<string, number>;

package/dist/runtime/spreadsheet/utils/headers.js

@@ -0,0 +1,36 @@
+import { isFunction, isString } from "#ui-tools/shared/utils/predicate";
+import { normalizeSpreadsheetText } from "./text.js";
+export function createSpreadsheetHeaderCells(row) {
+  return row.map((text, index) => ({ index, normalized: normalizeSpreadsheetText(text), text }));
+}
+function matchesHeader(matcher, header, ctx) {
+  if (isString(matcher)) return normalizeSpreadsheetText(matcher) === header.normalized;
+  if (matcher instanceof RegExp) {
+    matcher.lastIndex = 0;
+    return matcher.test(header.text);
+  }
+  return isFunction(matcher) ? matcher({ ctx, header }) : false;
+}
+export function isSpreadsheetHeaderOf(field, header, ctx) {
+  return Boolean(header.normalized) && field.headers.some((matcher) => matchesHeader(matcher, header, ctx));
+}
+export function matchSpreadsheetHeaders(params) {
+  const matches = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  const manual = params.manual ?? {};
+  for (const [path, index] of Object.entries(manual)) {
+    if (index === null || used.has(index)) continue;
+    matches.set(path, index);
+    used.add(index);
+  }
+  for (const field of params.fields) {
+    if (field.select?.from || field.path in manual) continue;
+    const header = params.headers.find(
+      (candidate) => !used.has(candidate.index) && isSpreadsheetHeaderOf(field, candidate, params.ctx)
+    );
+    if (!header) continue;
+    matches.set(field.path, header.index);
+    used.add(header.index);
+  }
+  return matches;
+}

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

@@ -0,0 +1,24 @@
+import type { SpreadsheetExistingAction, SpreadsheetRecord } from '../types/index.js';
+/** Text form of a row key, used to compare keys; `null` when the key is empty. */
+export declare function serializeSpreadsheetRowKey(value: unknown): string | null;
+/**
+ * Field paths a key function reads, found by running it on a recording copy of a row. Duplicate
+ * issues are attached to these cells.
+ */
+export declare function detectSpreadsheetKeyFields(key: (row: SpreadsheetRecord) => unknown, sample: SpreadsheetRecord): string[];
+/** Fields of a row whose value differs from the stored record, for the fields the record has. */
+export declare function diffSpreadsheetRow(params: {
+    paths: readonly string[];
+    data: SpreadsheetRecord;
+    existing: unknown;
+}): string[];
+export declare function resolveSpreadsheetExistingAction(params: {
+    action: SpreadsheetExistingAction | ((params: {
+        row: SpreadsheetRecord;
+        existing: unknown;
+        ctx: unknown;
+    }) => SpreadsheetExistingAction) | undefined;
+    row: SpreadsheetRecord;
+    existing: unknown;
+    ctx: unknown;
+}): SpreadsheetExistingAction;

package/dist/runtime/spreadsheet/utils/identity.js

@@ -0,0 +1,57 @@
+import { isSpreadsheetKeyTuple } from "./guards.js";
+import { getSpreadsheetPathValue, isSpreadsheetRecord } from "./paths.js";
+import { toSpreadsheetText } from "./text.js";
+function isRowKey(value) {
+  if (typeof value === "string") return value.trim() !== "";
+  if (typeof value === "number") return Number.isFinite(value);
+  return Array.isArray(value) && value.length > 0 && value.every(
+    (part) => typeof part === "string" && part.trim() !== "" || typeof part === "number"
+  );
+}
+export function serializeSpreadsheetRowKey(value) {
+  if (!isRowKey(value)) return null;
+  if (isSpreadsheetKeyTuple(value))
+    return JSON.stringify(value.map((part) => normalizeKeyPart(part)));
+  return normalizeKeyPart(value);
+}
+function normalizeKeyPart(value) {
+  return typeof value === "number" ? String(value) : value.trim().toLowerCase();
+}
+export function detectSpreadsheetKeyFields(key, sample) {
+  const paths = /* @__PURE__ */ new Set();
+  function record(target, prefix) {
+    return new Proxy(target, {
+      get(object, property) {
+        if (typeof property !== "string") return void 0;
+        const path = prefix ? `${prefix}.${property}` : property;
+        const value = object[property];
+        if (isSpreadsheetRecord(value)) return record(value, path);
+        paths.add(path);
+        return value;
+      }
+    });
+  }
+  try {
+    key(record(sample, ""));
+  } catch {
+  }
+  return [...paths];
+}
+export function diffSpreadsheetRow(params) {
+  if (!isSpreadsheetRecord(params.existing)) return [];
+  const existing = params.existing;
+  return params.paths.filter((path) => {
+    const stored = getSpreadsheetPathValue(existing, path);
+    if (stored === void 0) return false;
+    return format(stored) !== format(getSpreadsheetPathValue(params.data, path));
+  });
+}
+function format(value) {
+  if (Array.isArray(value)) return value.map(format).join(", ");
+  return toSpreadsheetText(value);
+}
+export function resolveSpreadsheetExistingAction(params) {
+  if (!params.action) return "update";
+  if (typeof params.action === "string") return params.action;
+  return params.action({ ctx: params.ctx, existing: params.existing, row: params.row });
+}

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

@@ -1,6 +1,15 @@
-export * from './builders/index.js';
-export * from './context.js';
-export * from './references/index.js';
-export * from './rows/index.js';
-export * from './source/index.js';
-export * from './validation/index.js';
+export * from './export.js';
+export * from './fields.js';
+export * from './guards.js';
+export * from './headers.js';
+export * from './identity.js';
+export * from './layout.js';
+export * from './options.js';
+export * from './parse.js';
+export * from './paths.js';
+export * from './rows.js';
+export * from './rules.js';
+export * from './suggestions.js';
+export * from './text.js';
+export * from './workbook.js';
+export * from './download.js';

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

@@ -1,6 +1,15 @@
-export * from "./builders/index.js";
-export * from "./context.js";
-export * from "./references/index.js";
-export * from "./rows/index.js";
-export * from "./source/index.js";
-export * from "./validation/index.js";
+export * from "./export.js";
+export * from "./fields.js";
+export * from "./guards.js";
+export * from "./headers.js";
+export * from "./identity.js";
+export * from "./layout.js";
+export * from "./options.js";
+export * from "./parse.js";
+export * from "./paths.js";
+export * from "./rows.js";
+export * from "./rules.js";
+export * from "./suggestions.js";
+export * from "./text.js";
+export * from "./workbook.js";
+export * from "./download.js";

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

@@ -0,0 +1,12 @@
+import type { SpreadsheetField, SpreadsheetLayoutDetection, SpreadsheetWorkbook } from '../types/index.js';
+/** Rows scanned per sheet when looking for the header row. */
+export declare const SPREADSHEET_HEADER_SCAN_ROWS = 20;
+/**
+ * Scores the first rows of every sheet by how many fields their cells name. The best row of a
+ * sheet is its header row; the best sheet wins. Title rows and empty sheets score zero.
+ */
+export declare function detectSpreadsheetLayout(params: {
+    workbook: SpreadsheetWorkbook;
+    fields: readonly SpreadsheetField[];
+    ctx: unknown;
+}): SpreadsheetLayoutDetection;

package/dist/runtime/spreadsheet/utils/layout.js

@@ -0,0 +1,37 @@
+import { createSpreadsheetHeaderCells, matchSpreadsheetHeaders } from "./headers.js";
+export const SPREADSHEET_HEADER_SCAN_ROWS = 20;
+export function detectSpreadsheetLayout(params) {
+  const sheets = params.workbook.sheets.map((sheet) => {
+    const candidates = sheet.rows.slice(0, SPREADSHEET_HEADER_SCAN_ROWS).map((row, index) => ({
+      index,
+      matchCount: matchSpreadsheetHeaders({
+        ctx: params.ctx,
+        fields: params.fields,
+        headers: createSpreadsheetHeaderCells(row)
+      }).size,
+      preview: row.filter(Boolean).slice(0, 4),
+      rowNumber: sheet.rowNumbers[index] ?? index + 1
+    }));
+    const best = candidates.reduce(
+      (winner, candidate) => candidate.matchCount > winner.matchCount ? candidate : winner,
+      candidates[0] ?? { index: 0, matchCount: 0, preview: [], rowNumber: 1 }
+    );
+    return {
+      candidates,
+      headerRow: best.index,
+      matchCount: best.matchCount,
+      name: sheet.name,
+      rowCount: Math.max(sheet.rows.length - best.index - 1, 0)
+    };
+  });
+  const top = sheets.reduce(
+    (winner, sheet) => !winner || sheet.matchCount > winner.matchCount ? sheet : winner,
+    null
+  );
+  const tied = top ? sheets.filter((sheet) => sheet.matchCount === top.matchCount) : [];
+  return {
+    ambiguous: Boolean(top && top.matchCount > 0 && tied.length > 1),
+    best: top && top.matchCount > 0 ? { headerRow: top.headerRow, matchCount: top.matchCount, sheet: top.name } : null,
+    sheets
+  };
+}