nuxt-ui-tools 1.11.2 → 1.13.0

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

@@ -1,10 +1,31 @@
-import type { SpreadsheetValue } from '../types/index.js';
-export interface SpreadsheetOptionEntry {
-    label: string;
-    value: SpreadsheetValue;
-}
-export declare function isSpreadsheetPrimitiveOption<T>(value: T): value is T & (string | number | boolean);
-export declare function isSpreadsheetOptionEntry<T>(value: T): value is T & SpreadsheetOptionEntry;
-export declare function resolveSpreadsheetOptionEntries<TParams>(source: SpreadsheetValue, params: TParams): readonly SpreadsheetValue[];
-export declare function getSpreadsheetOptionLabel<T>(option: T): string;
-export declare function getSpreadsheetOptionValue<T>(option: T): SpreadsheetValue | undefined;
+import type { QueryFnDefinition } from '#ui-tools/shared/types/query';
+import type { RemoteOptionsLoader } from '#ui-tools/shared/types/remote-options';
+import type { SpreadsheetFieldOptions, SpreadsheetOptionItem, SpreadsheetOptionsSource, SpreadsheetResolvedOption } from '../types/index.js';
+export declare function isSpreadsheetQueryDefinition<TData>(value: unknown): value is QueryFnDefinition<TData>;
+export declare function isSpreadsheetRemoteLoader(value: unknown): value is RemoteOptionsLoader<SpreadsheetOptionItem>;
+/**
+ * What a source gives once resolved against the context: a list, a query, or a remote loader.
+ * Sources reading the row are resolved per row instead (see `SpreadsheetField['select']`).
+ */
+export declare function resolveSpreadsheetOptionsSource(source: SpreadsheetOptionsSource<unknown, SpreadsheetOptionItem>, ctx: unknown): {
+    kind: 'list';
+    items: readonly SpreadsheetOptionItem[];
+} | {
+    kind: 'query';
+    query: QueryFnDefinition<readonly SpreadsheetOptionItem[]>;
+} | {
+    kind: 'remote';
+    loader: RemoteOptionsLoader<SpreadsheetOptionItem>;
+};
+export declare function toSpreadsheetOption(item: SpreadsheetOptionItem): SpreadsheetResolvedOption;
+/** Options indexed by every exact key they match: label, value, and aliases, normalized. */
+export declare function indexSpreadsheetOptions(options: readonly SpreadsheetResolvedOption[]): Map<string, SpreadsheetResolvedOption>;
+/** Options of a list, ready to match. */
+export declare function createSpreadsheetFieldOptions(items: readonly SpreadsheetOptionItem[]): SpreadsheetFieldOptions;
+/** Short stable id of a text (FNV-1a), for scope ids. */
+export declare function hashSpreadsheetText(text: string): string;
+/**
+ * Key of an answer: the normalized value, prefixed by the scope when the options depend on the
+ * row, since the same value may map to different options in each scope.
+ */
+export declare function spreadsheetAnswerKey(key: string, scope: string | null | undefined): string;

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

@@ -1,38 +1,66 @@
-import { isBoolean, isFunction, isNumber, isString } from "#ui-tools/shared/utils/predicate";
-import { isSpreadsheetRecord } from "./object.js";
-function isSpreadsheetOptionResolver(value) {
-  return isFunction(value);
+import { isFunction } from "#ui-tools/shared/utils/predicate";
+import { resolveTextValue } from "#ui-tools/shared/utils/render";
+import {
+  isSpreadsheetOptionEntry,
+  isSpreadsheetOptionList,
+  isSpreadsheetOptionsResolver
+} from "./guards.js";
+import { isSpreadsheetRecord } from "./paths.js";
+import { normalizeSpreadsheetText } from "./text.js";
+export function isSpreadsheetQueryDefinition(value) {
+  return isSpreadsheetRecord(value) && Array.isArray(value.queryKey) && isFunction(value.queryFn);
 }
-export function isSpreadsheetPrimitiveOption(value) {
-  return isString(value) || isNumber(value) || isBoolean(value);
+export function isSpreadsheetRemoteLoader(value) {
+  return isSpreadsheetRecord(value) && isFunction(value.load) && isFunction(value.resolveSelected);
 }
-export function isSpreadsheetOptionEntry(value) {
-  return isSpreadsheetRecord(value) && "label" in value && isString(value.label) && "value" in value;
-}
-export function resolveSpreadsheetOptionEntries(source, params) {
-  if (Array.isArray(source)) {
-    return source;
-  }
-  if (isSpreadsheetOptionResolver(source)) {
-    return source(params);
+export function resolveSpreadsheetOptionsSource(source, ctx) {
+  if (isSpreadsheetOptionList(source)) return { items: source, kind: "list" };
+  if (isSpreadsheetRemoteLoader(source)) return { kind: "remote", loader: source };
+  if (isSpreadsheetOptionsResolver(source)) {
+    const resolved = source({ ctx, row: {} });
+    return isSpreadsheetOptionList(resolved) ? { items: resolved, kind: "list" } : { kind: "query", query: resolved };
   }
-  return [];
+  if (isSpreadsheetQueryDefinition(source))
+    return { kind: "query", query: source };
+  return { items: [], kind: "list" };
 }
-export function getSpreadsheetOptionLabel(option) {
-  if (isSpreadsheetPrimitiveOption(option)) {
-    return String(option);
-  }
-  if (isSpreadsheetOptionEntry(option)) {
-    return option.label;
-  }
-  return "";
+export function toSpreadsheetOption(item) {
+  if (isSpreadsheetOptionEntry(item))
+    return {
+      aliases: item.aliases ?? [],
+      label: resolveTextValue(item.label, String(item.value)),
+      value: item.value
+    };
+  return { aliases: [], label: String(item), value: item };
 }
-export function getSpreadsheetOptionValue(option) {
-  if (isSpreadsheetPrimitiveOption(option)) {
-    return option;
+export function indexSpreadsheetOptions(options) {
+  const index = /* @__PURE__ */ new Map();
+  for (const option of options) {
+    for (const key of [option.label, String(option.value), ...option.aliases]) {
+      const normalized = normalizeSpreadsheetText(key);
+      if (normalized && !index.has(normalized)) index.set(normalized, option);
+    }
   }
-  if (isSpreadsheetOptionEntry(option)) {
-    return option.value;
+  return index;
+}
+export function createSpreadsheetFieldOptions(items) {
+  const options = items.map(toSpreadsheetOption);
+  return {
+    error: null,
+    index: indexSpreadsheetOptions(options),
+    options,
+    remote: false,
+    status: "ready"
+  };
+}
+export function hashSpreadsheetText(text) {
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index++) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
   }
-  return void 0;
+  return (hash >>> 0).toString(36);
+}
+export function spreadsheetAnswerKey(key, scope) {
+  return scope ? `${scope}:${key}` : key;
 }

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

@@ -0,0 +1,6 @@
+/** Reads a date: an Excel date, an Excel serial number, or text in one of `formats`. Returns ISO or `null`. */
+export declare function parseSpreadsheetDate(text: string, raw: unknown, formats: readonly string[]): string | null;
+/** Reads a number, with `,` or `.` as decimal separator; spaces and the other separator are ignored. */
+export declare function parseSpreadsheetNumber(text: string, raw: unknown, decimal: '.' | ','): number | null;
+/** Reads a boolean from the texts accepted as true and false. Returns `null` for anything else. */
+export declare function parseSpreadsheetBoolean(text: string, raw: unknown, trueTexts: readonly string[], falseTexts: readonly string[]): boolean | null;

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

@@ -0,0 +1,147 @@
+import { SSF } from "xlsx";
+import { normalizeSpreadsheetText } from "./text.js";
+const MONTHS = [
+  ["january", "jan", "janvier", "janv"],
+  ["february", "feb", "fevrier", "fevr", "fev"],
+  ["march", "mar", "mars"],
+  ["april", "apr", "avril", "avr"],
+  ["may", "mai"],
+  ["june", "jun", "juin"],
+  ["july", "jul", "juillet", "juil"],
+  ["august", "aug", "aout"],
+  ["september", "sep", "sept", "septembre"],
+  ["october", "oct", "octobre"],
+  ["november", "nov", "novembre"],
+  ["december", "dec", "decembre"]
+];
+const DEFAULT_DATE_FORMATS = [
+  "yyyy-MM-dd",
+  "yyyy-MM-dd HH:mm",
+  "yyyy-MM-dd HH:mm:ss",
+  "dd/MM/yyyy",
+  "dd/MM/yyyy HH:mm"
+];
+const TOKENS = /yyyy|yy|MMMM|MMM|MM|M|dd|d|HH|H|hh|h|mm|ss|a/gu;
+const pad = (value, length = 2) => String(value).padStart(length, "0");
+function toIso(parts) {
+  const date = `${pad(parts.year, 4)}-${pad(parts.month)}-${pad(parts.day)}`;
+  if (!parts.hasTime) return date;
+  const time = `${pad(parts.hours)}:${pad(parts.minutes)}`;
+  return parts.seconds ? `${date}T${time}:${pad(parts.seconds)}` : `${date}T${time}`;
+}
+function isValidDate(parts) {
+  const date = new Date(parts.year, parts.month - 1, parts.day);
+  return date.getFullYear() === parts.year && date.getMonth() === parts.month - 1 && date.getDate() === parts.day && parts.hours < 24 && parts.minutes < 60 && parts.seconds < 60;
+}
+function monthFromName(name) {
+  const normalized = normalizeSpreadsheetText(name).replace(/\.$/u, "");
+  const index = MONTHS.findIndex((names) => names.includes(normalized));
+  return index < 0 ? 0 : index + 1;
+}
+const formatCache = /* @__PURE__ */ new Map();
+function compileFormat(format) {
+  const cached = formatCache.get(format);
+  if (cached) return cached;
+  const tokens = [];
+  let source = "";
+  let last = 0;
+  for (const match of format.matchAll(TOKENS)) {
+    source += format.slice(last, match.index).replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&").replaceAll(/\s+/gu, "\\s+");
+    tokens.push(match[0]);
+    source += match[0] === "MMMM" || match[0] === "MMM" ? "([\\p{L}]+\\.?)" : match[0] === "a" ? "([AaPp]\\.?[Mm]\\.?)" : match[0] === "yyyy" ? "(\\d{4})" : "(\\d{1,2})";
+    last = (match.index ?? 0) + match[0].length;
+  }
+  source += format.slice(last).replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&").replaceAll(/\s+/gu, "\\s+");
+  const compiled = { pattern: new RegExp(`^${source}$`, "u"), tokens };
+  formatCache.set(format, compiled);
+  return compiled;
+}
+function parseWithFormat(text, format) {
+  const { pattern, tokens } = compileFormat(format);
+  const match = pattern.exec(text.trim());
+  if (!match) return null;
+  const parts = {
+    day: 1,
+    hasTime: false,
+    hours: 0,
+    minutes: 0,
+    month: 1,
+    seconds: 0,
+    year: 1970
+  };
+  let pm = null;
+  for (const [index, token] of tokens.entries()) {
+    const value = match[index + 1] ?? "";
+    const number = Number(value);
+    if (token === "yyyy") parts.year = number;
+    else if (token === "yy") parts.year = 2e3 + number;
+    else if (token === "MMMM" || token === "MMM") parts.month = monthFromName(value);
+    else if (token === "MM" || token === "M") parts.month = number;
+    else if (token === "dd" || token === "d") parts.day = number;
+    else if (token === "HH" || token === "H" || token === "hh" || token === "h") {
+      parts.hours = number;
+      parts.hasTime = true;
+    } else if (token === "mm") {
+      parts.minutes = number;
+      parts.hasTime = true;
+    } else if (token === "ss") parts.seconds = number;
+    else if (token === "a") pm = value.toLowerCase().startsWith("p");
+  }
+  if (pm !== null) {
+    if (parts.hours > 12 || parts.hours === 0) return null;
+    parts.hours = parts.hours % 12 + (pm ? 12 : 0);
+  }
+  return parts.month && isValidDate(parts) ? parts : null;
+}
+function partsFromDate(date) {
+  const hours = date.getHours();
+  const minutes = date.getMinutes();
+  const seconds = date.getSeconds();
+  return {
+    day: date.getDate(),
+    hasTime: Boolean(hours || minutes || seconds),
+    hours,
+    minutes,
+    month: date.getMonth() + 1,
+    seconds,
+    year: date.getFullYear()
+  };
+}
+export function parseSpreadsheetDate(text, raw, formats) {
+  if (raw instanceof Date && !Number.isNaN(raw.getTime())) return toIso(partsFromDate(raw));
+  if (typeof raw === "number") {
+    const code = SSF.parse_date_code(raw);
+    if (code && code.y > 1900) {
+      const parts = {
+        day: code.d,
+        hasTime: Boolean(code.H || code.M || code.S),
+        hours: code.H,
+        minutes: code.M,
+        month: code.m,
+        seconds: Math.round(code.S),
+        year: code.y
+      };
+      return toIso(parts);
+    }
+  }
+  for (const format of formats.length ? formats : DEFAULT_DATE_FORMATS) {
+    const parts = parseWithFormat(text, format);
+    if (parts) return toIso(parts);
+  }
+  return null;
+}
+export function parseSpreadsheetNumber(text, raw, decimal) {
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+  const compact = text.replaceAll(/[\s  ']/gu, "");
+  const normalized = decimal === "," ? compact.replaceAll(".", "").replace(",", ".") : compact.replaceAll(",", "");
+  if (!/^[+-]?(\d+\.?\d*|\.\d+)$/u.test(normalized)) return null;
+  const value = Number(normalized);
+  return Number.isFinite(value) ? value : null;
+}
+export function parseSpreadsheetBoolean(text, raw, trueTexts, falseTexts) {
+  if (typeof raw === "boolean") return raw;
+  const normalized = normalizeSpreadsheetText(text);
+  if (trueTexts.some((value) => normalizeSpreadsheetText(value) === normalized)) return true;
+  if (falseTexts.some((value) => normalizeSpreadsheetText(value) === normalized)) return false;
+  return null;
+}

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

@@ -0,0 +1,4 @@
+import type { SpreadsheetRecord, SpreadsheetValue } from '../types/index.js';
+export declare function isSpreadsheetRecord<T>(value: T): value is T & SpreadsheetRecord;
+export declare function getSpreadsheetPathValue(data: SpreadsheetRecord, path: string): SpreadsheetValue;
+export declare function setSpreadsheetPathValue(target: SpreadsheetRecord, path: string, value: SpreadsheetValue): void;

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

@@ -0,0 +1,29 @@
+import { isPlainObject } from "#ui-tools/shared/utils/predicate";
+export function isSpreadsheetRecord(value) {
+  return isPlainObject(value);
+}
+export function getSpreadsheetPathValue(data, path) {
+  let current = data;
+  for (const part of path.split(".")) {
+    if (!isSpreadsheetRecord(current)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+export function setSpreadsheetPathValue(target, path, value) {
+  const parts = path.split(".");
+  let current = target;
+  for (const [index, part] of parts.entries()) {
+    if (index === parts.length - 1) {
+      current[part] = value;
+      return;
+    }
+    const next = current[part];
+    if (isSpreadsheetRecord(next)) current = next;
+    else {
+      const created = {};
+      current[part] = created;
+      current = created;
+    }
+  }
+}

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

@@ -0,0 +1,69 @@
+import type { UiToolsTranslator } from '#ui-tools/i18n';
+import type { SpreadsheetField, SpreadsheetFieldOptions, SpreadsheetRecord, SpreadsheetResolvedOption, SpreadsheetRowIssue, SpreadsheetValueAnswers } from '../types/index.js';
+/** Options a select field checks a row against, and their scope when they depend on the row. */
+export interface SpreadsheetRowOptions {
+    options: SpreadsheetFieldOptions | undefined;
+    /** Id of the set of options, when they depend on the row; `null` otherwise. */
+    scope: string | null;
+}
+/** What parsing needs besides the row: fields, their columns, options, answers, and the context. */
+export interface SpreadsheetParseContext {
+    /** In declared order: a field reads the fields above it. */
+    fields: readonly SpreadsheetField[];
+    /** Column index of each field reading its own column. */
+    columns: ReadonlyMap<string, number>;
+    headers: readonly string[];
+    /** Options of a select field for a row, the fields above it parsed. */
+    optionsOf: (field: SpreadsheetField, row: SpreadsheetRecord) => SpreadsheetRowOptions;
+    answers: SpreadsheetValueAnswers;
+    ctx: unknown;
+    t: UiToolsTranslator;
+}
+/** A select item that matched no option, recorded to build the questions. */
+export interface SpreadsheetUnmatchedToken {
+    field: string;
+    /** Normalized value. */
+    key: string;
+    value: string;
+    header: string;
+    scope: string | null;
+}
+export interface SpreadsheetMatchedToken {
+    field: string;
+    key: string;
+    value: string;
+    option: SpreadsheetResolvedOption;
+    scope: string | null;
+}
+export interface SpreadsheetCellResult {
+    text: string;
+    original: string;
+    display: string;
+    defaulted: boolean;
+    created: boolean;
+    /** Options of a select cell, for this row. */
+    choices: readonly SpreadsheetResolvedOption[];
+}
+export interface SpreadsheetParsedRow {
+    data: SpreadsheetRecord;
+    issues: SpreadsheetRowIssue[];
+    cells: Map<string, SpreadsheetCellResult>;
+    unmatched: SpreadsheetUnmatchedToken[];
+    matched: SpreadsheetMatchedToken[];
+    /** A value answered “skip these rows”, by the user or the policy. */
+    skipped: boolean;
+}
+/**
+ * Parses one data row, field by field in declared order: each field reads its cell (or the cell
+ * of its `from` column), applies its default, parser, options, and value answers, then its rules.
+ * Defaults, parsers, options, and rules receive the fields above as `row`. Nothing is guessed: a
+ * select value matches an option exactly, or it is answered, or it follows the column's `unknown`
+ * policy.
+ */
+export declare function parseSpreadsheetRow(params: {
+    index: number;
+    cells: readonly string[];
+    raws: readonly unknown[] | undefined;
+    edits: Readonly<Record<string, string>> | undefined;
+    context: SpreadsheetParseContext;
+}): SpreadsheetParsedRow;

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

@@ -0,0 +1,168 @@
+import { spreadsheetAnswerKey } from "./options.js";
+import { parseSpreadsheetBoolean, parseSpreadsheetDate, parseSpreadsheetNumber } from "./parse.js";
+import { setSpreadsheetPathValue } from "./paths.js";
+import { normalizeSpreadsheetText, splitSpreadsheetItems, toSpreadsheetText } from "./text.js";
+function displayValue(field, value, options) {
+  const items = Array.isArray(value) ? value : [value];
+  return items.filter((item) => item !== null && item !== void 0).map((item) => {
+    if (field.kind !== "select") return toSpreadsheetText(item);
+    return options?.options.find((option) => option.value === item)?.label ?? toSpreadsheetText(item);
+  }).join(", ");
+}
+function parseScalar(params) {
+  const { field, text, raw } = params;
+  if (field.parse) {
+    try {
+      return {
+        value: field.parse({
+          cell: { header: params.header, raw: raw ?? text, rowIndex: params.rowIndex, text },
+          ctx: params.ctx,
+          row: params.row
+        })
+      };
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  if (field.kind === "number") {
+    const value = parseSpreadsheetNumber(text, raw, field.decimal);
+    return value === null ? { error: "number" } : { value };
+  }
+  if (field.kind === "date") {
+    const value = parseSpreadsheetDate(text, raw, field.formats);
+    return value === null ? { error: "date" } : { value };
+  }
+  if (field.kind === "boolean") {
+    const value = parseSpreadsheetBoolean(text, raw, field.trueTexts, field.falseTexts);
+    return value === null ? { error: "boolean" } : { value };
+  }
+  return { value: text };
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export function parseSpreadsheetRow(params) {
+  const { context, edits } = params;
+  const { t } = context;
+  const data = {};
+  const issues = [];
+  const cells = /* @__PURE__ */ new Map();
+  const unmatched = [];
+  const matched = [];
+  let skipped = false;
+  for (const field of context.fields) {
+    const from = field.select?.from ?? null;
+    const column = from ? context.columns.get(from) : context.columns.get(field.path);
+    const header = column === void 0 ? "" : context.headers[column] ?? "";
+    const original = from ? cells.get(from)?.text ?? "" : column === void 0 ? "" : toSpreadsheetText(params.cells[column]);
+    const edited = edits?.[field.path];
+    const text = edited ?? original;
+    const raw = edited === void 0 && !from && column !== void 0 ? params.raws?.[column] : void 0;
+    const issue = (code, message, level = "error") => issues.push({ code, field: field.path, level, message });
+    let resolved = { options: void 0, scope: null };
+    if (field.select) {
+      try {
+        resolved = context.optionsOf(field, data);
+      } catch (error) {
+        issue("options", errorMessage(error));
+      }
+    }
+    const { options, scope } = resolved;
+    const choices = options?.options ?? [];
+    if (!text) {
+      let value2 = field.separator ? [] : null;
+      if (field.defaultOf) {
+        try {
+          value2 = field.defaultOf(data) ?? value2;
+        } catch (error) {
+          issue("default", errorMessage(error));
+        }
+      }
+      setSpreadsheetPathValue(data, field.path, value2);
+      cells.set(field.path, {
+        choices,
+        created: false,
+        defaulted: field.hasDefault,
+        display: field.hasDefault ? displayValue(field, value2, options) : "",
+        original,
+        text
+      });
+      if (field.required && !field.hasDefault) issue("required", t("spreadsheet.issues.required"));
+      continue;
+    }
+    const items = field.separator ? splitSpreadsheetItems(text, field.separator) : [text];
+    const values = [];
+    let created = false;
+    if (field.kind === "select" && field.select) {
+      for (const item of items) {
+        const key = normalizeSpreadsheetText(item);
+        const option = options?.index.get(key);
+        if (option) {
+          values.push(option.value);
+          matched.push({ field: field.path, key, option, scope, value: item });
+          continue;
+        }
+        if (!options || options.status !== "ready") continue;
+        unmatched.push({ field: field.path, header, key, scope, value: item });
+        const answer = context.answers[field.path]?.[spreadsheetAnswerKey(key, scope)] ?? (field.select.unknown === "ask" || field.select.unknown === "error" ? void 0 : { action: field.select.unknown });
+        if (answer?.action === "map") values.push(answer.value);
+        else if (answer?.action === "create") {
+          values.push(item);
+          created = true;
+        } else if (answer?.action === "skip-rows") {
+          skipped = true;
+          issue("value.skipped", t("spreadsheet.issues.skipped", { value: item }), "info");
+        } else if (answer?.action === "leave-empty") continue;
+        else if (field.select.unknown === "error")
+          issue("value.not-found", t("spreadsheet.issues.notFound", { value: item }));
+        else issue("value.unknown", t("spreadsheet.issues.unknownValue", { value: item }));
+      }
+    } else {
+      for (const item of items) {
+        const result = parseScalar({
+          ctx: context.ctx,
+          field,
+          header,
+          raw: items.length > 1 ? void 0 : raw,
+          row: data,
+          rowIndex: params.index,
+          text: item
+        });
+        if ("value" in result) values.push(result.value);
+        else if (result.error === "number" || result.error === "date" || result.error === "boolean")
+          issue(result.error, t(`spreadsheet.issues.${result.error}`, { value: item }));
+        else issue("parse", result.error);
+      }
+    }
+    const value = field.separator ? values : values[0] ?? null;
+    setSpreadsheetPathValue(data, field.path, value);
+    cells.set(field.path, {
+      choices,
+      created,
+      defaulted: false,
+      display: displayValue(field, value, options) || text,
+      original,
+      text
+    });
+    if (field.required && (value === null || Array.isArray(value) && !value.length) && !issues.some((entry) => entry.field === field.path))
+      issue("required", t("spreadsheet.issues.required"));
+    let rules = [];
+    try {
+      rules = field.rulesOf(data);
+    } catch (error) {
+      issue("rules", errorMessage(error));
+    }
+    for (const rule of rules) {
+      const targets = field.separator ? values : [value];
+      for (const target of targets) {
+        if (target === null && !rule.required) continue;
+        const message = rule.check(target, { ctx: context.ctx });
+        if (message) {
+          issue(rule.name, message, rule.level);
+          break;
+        }
+      }
+    }
+  }
+  return { cells, data, issues, matched, skipped, unmatched };
+}

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

@@ -0,0 +1,4 @@
+import type { UiToolsTranslator } from '#ui-tools/i18n';
+import type { SpreadsheetRuleBuilder } from '../types/index.js';
+/** The `v` of `rules: (v) => [...]`, with messages from the locale. */
+export declare function createSpreadsheetRuleBuilder(t: UiToolsTranslator): SpreadsheetRuleBuilder<unknown>;

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

@@ -0,0 +1,95 @@
+import { isSpreadsheetMessageFunction } from "./guards.js";
+const EMAIL = /^[^@\s]+@[^@\s]+\.[^@\s]{2,}$/u;
+function resolveMessage(message, value, ctx) {
+  if (isSpreadsheetMessageFunction(message)) return String(message({ ctx, value }));
+  return typeof message === "string" || typeof message === "number" ? String(message) : String(message());
+}
+function createRule(params) {
+  return {
+    check(value, context) {
+      return params.test(value, context.ctx) ? null : resolveMessage(params.message, value, context.ctx);
+    },
+    level: params.level ?? "error",
+    name: params.name,
+    required: params.required ?? false
+  };
+}
+function withOptions(options, fallback) {
+  return { level: options?.level, message: options?.message ?? fallback };
+}
+function isEmpty(value) {
+  return value === null || value === void 0 || value === "" || Array.isArray(value) && value.length === 0;
+}
+const pad = (part) => String(part).padStart(2, "0");
+function todayIso() {
+  const now = /* @__PURE__ */ new Date();
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+export function createSpreadsheetRuleBuilder(t) {
+  return {
+    between: (min, max, options) => createRule({
+      name: "between",
+      ...withOptions(
+        options,
+        ({ value }) => t("spreadsheet.issues.between", { max, min, value: String(value) })
+      ),
+      test: (value) => value >= min && value <= max
+    }),
+    email: (options) => createRule({
+      name: "email",
+      ...withOptions(options, () => t("spreadsheet.issues.email")),
+      test: (value) => EMAIL.test(value)
+    }),
+    max: (max, options) => createRule({
+      name: "max",
+      ...withOptions(
+        options,
+        ({ value }) => t("spreadsheet.issues.max", { max, value: String(value) })
+      ),
+      test: (value) => value <= max
+    }),
+    maxLength: (max, options) => createRule({
+      name: "maxLength",
+      ...withOptions(options, () => t("spreadsheet.issues.maxLength", { max })),
+      test: (value) => value.length <= max
+    }),
+    min: (min, options) => createRule({
+      name: "min",
+      ...withOptions(
+        options,
+        ({ value }) => t("spreadsheet.issues.min", { min, value: String(value) })
+      ),
+      test: (value) => value >= min
+    }),
+    minLength: (min, options) => createRule({
+      name: "minLength",
+      ...withOptions(options, () => t("spreadsheet.issues.minLength", { min })),
+      test: (value) => value.length >= min
+    }),
+    notFuture: (options) => createRule({
+      name: "notFuture",
+      ...withOptions(options, () => t("spreadsheet.issues.notFuture")),
+      test: (value) => value.slice(0, 10) <= todayIso()
+    }),
+    pattern: (pattern, options) => createRule({
+      name: "pattern",
+      ...withOptions(options, () => t("spreadsheet.issues.pattern")),
+      test: (value) => {
+        pattern.lastIndex = 0;
+        return pattern.test(value);
+      }
+    }),
+    required: (options) => createRule({
+      name: "required",
+      required: true,
+      ...withOptions(options, () => t("spreadsheet.issues.required")),
+      test: (value) => !isEmpty(value)
+    }),
+    validate: (options) => createRule({
+      level: options.level,
+      message: options.message,
+      name: options.name ?? "validate",
+      test: (value, ctx) => options.validator(value, { ctx })
+    })
+  };
+}