@sheetpane/validation 0.3.0 → 0.4.0

package/README.md

@@ -5,11 +5,22 @@
 A plugin for `@sheetpane/grid`. It reads the `<dataValidations>` the file's
 author saved, including the x14 form Excel uses for lists on another sheet,
 and runs them through the `validate` hook. `<sheetpane-excel>` and
-`<sheetpane-errors>` on the same pane both see the result. No runtime
-dependencies; `@sheetpane/grid` is a peer. Versioned in lockstep with it.
+`<sheetpane-errors>` on the same pane both see the result. On export it can
+also write the host's rules file into the `.xlsx` as Excel's own dropdowns
+and checks. No third-party runtime dependencies (`@sheetpane/export` writes
+the rules and gives `shiftFormula`); `@sheetpane/grid` is a peer. Versioned in lockstep with it.
 
-- `@sheetpane/validation`: the headless plugin (`validate` only).
+- `@sheetpane/validation`: the headless plugin (`validate`, and `exportPatch` for the rules file).
 - `@sheetpane/validation/ui`: opt-in. Adds the list arrow and the status-line count.
+- `@sheetpane/validation/check`: the same plugin with no registration, no
+  element and no Download switch (checking only — `exportPatch` is the page
+  entry's), and `check(bytes, options)` — `@sheetpane/grid/check`'s check with
+  this plugin on: the workbook's own validation from Node or a worker.
+
+  ```js
+  import { check } from '@sheetpane/validation/check';
+  const errors = await check(await readFile('budget.xlsx'), { name: 'budget.xlsx', severity: 'error' });
+  ```
 
 ## Use
 
@@ -80,6 +91,7 @@ What an operand can be:
 - a quoted string
 - a cell: `$G$1`, `Sheet2!B1`, or a relative `D1`, which shifts with each cell the same way it does in Excel
 - a defined name that resolves to one of these
+- `INDIRECT(<cell>)`: the cell named by that cell's text (see dependent lists below)
 
 A cell operand is read live, so changing the limit re-checks the rule. An
 empty operand cell reads as 0.
@@ -89,10 +101,34 @@ A `list` source can be:
 - a literal list: `"a,b,c"`
 - a range: `$H$1:$H$9`, `Lists!$A$1:$A$9`, `$A:$A`
 - a defined name that resolves to a range
+- an Excel table's column: `Units[Unit]` or `Units[[#Data],[Unit]]`, directly or
+  through a defined name — the column's data rows, as the file stores the table
+
+- `INDIRECT($A2)` — a **dependent list** (W-60): each row reads its parent
+  cell's text and lists what it names — a defined name (any case; the sheet's
+  own name before a global one), a table or table column (`Units[Unit]`), or
+  an A1 range (`Lists!$B$2:$B$5`). `INDIRECT("Turbidity")` (quoted text) and
+  `INDIRECT($A2, TRUE)` work too.
 
 A range source is read live from the store, and the arrow's menu re-reads it
 each time it opens.
 
+### Dependent lists
+
+Excel's pattern for *Unit depends on Parameter*: one defined name per
+parameter (`Turbidity` → `Lists!$B$2:$B$3`) and `=INDIRECT($A2)` as the Unit
+column's list source. The parent's text is read per row, live: change the
+Parameter and the Unit is checked again in the same edit — a unit the new
+parameter does not allow (an orphan) is a warning, and the arrow offers the
+new parameter's units.
+
+A parent that names nothing (blank, or text that is no name, such as
+`Flow Rate`) gives no list. As in Excel, the child then passes under
+`allowBlank` ("Ignore blank") and fails without it (`expected`:
+`list — (A7 "Flow Rate" names no list)`). Names cannot hold spaces, so
+workbooks wrap the parent in `SUBSTITUTE`; that, `&` and R1C1
+(`INDIRECT($A2, FALSE)`) are not emulated — the rule is skipped (`source`).
+
 Blank cells pass when the rule has `allowBlank`. Without it, they fail.
 Cells are checked only inside the sheet's used range: its data plus any cell
 the user changed. A rule on `B:B` therefore does not produce a million rows.
@@ -102,10 +138,10 @@ the user changed. A rule on `B:B` therefore does not produce a million rows.
 | reason | what |
 |---|---|
 | `custom` | a `custom` rule when no formula plugin offers `evaluate()` (see below) |
-| `operand` | an operand the subset above does not cover, e.g. `SUM(...)` or `INDIRECT(...)` |
+| `operand` | an operand the subset above does not cover, e.g. `SUM(...)` or `INDIRECT(SUBSTITUTE(...))` |
 | `operator` | an operator outside the eight above |
 | `type` | an unknown rule type |
-| `source` | a list source that is neither a list, a range nor a name, or that names a missing sheet |
+| `source` | a list source that is neither a list, a range, a name nor `INDIRECT` of one cell or quoted text (`OFFSET(...)`, `INDIRECT(SUBSTITUTE(...))`), or that names a missing sheet |
 
 `skippedRules(store)` counts `custom` as checked when the pane has a formula
 evaluator. `skippedRules(book)` has only the workbook to go on, so it counts
@@ -124,13 +160,52 @@ The plugin passes the formula with its relative references already shifted to
 the cell. `true` or a non-zero number passes. `false` or `0` fails. Anything
 else counts as unknown, and the cell is not flagged.
 
+## The rules file as Excel dropdowns (`rulesAsValidation`)
+
+A host that checks its sheets with a rules file (`rules-src`, or
+`excel.rules`) can hand the same rules to people who work in Excel. The
+Download menu shows **Write rules as Excel dropdowns** while the pane has a
+rules file or column rules; turned on, the `.xlsx` carries them as the
+workbook's own data validation.
+
+```ts
+validation({ rulesAsValidation: true });          // the switch on at first (default: off)
+await excel.export({ rulesAsValidation: true });  // or for one export
+lastRulesWrite(excel.workbook?.book);             // { written, merged, skipped, conflicts }
+rulesAsValidations(store);                        // the plan, without writing
+```
+
+| the rule says | Excel gets | skipped (code) |
+|---|---|---|
+| `oneOf`, `equals` | a dropdown list | a value with a comma, an empty list, over 255 characters (SP-5403) |
+| `integer` / `number`, `min` / `max` | whole number / decimal | a bound that is not a number (SP-5404) |
+| `date`, `min` / `max` | date | a bound not written `2026-01-31` or as a serial (SP-5404) |
+| `minLength` / `maxLength` | text length | (SP-5404) |
+| `boolean` | the list TRUE, FALSE | |
+| `required` | "ignore blank" off (alone: text length ≥ 1) | |
+| `pattern`, `noneOf`, `unique` | — | always (SP-5401) |
+| two checks in one rule | — | always (SP-5402) |
+
+A column rule covers its column from the row under the titles to the last
+row; a cell rule its range. The rule's `message` is Excel's error text, the
+rule in words its input prompt; `onInvalid: 'block'` is Excel's Stop, a
+`note` its Information, anything else its Warning.
+
+**The workbook's own rule wins.** Where the file already has a rule, the
+written one leaves those cells and the conflict is listed (SP-5406); a rule
+that checks the same thing joins the file's own instead of repeating it.
+Excel 2010 `x14` rules stay where they are. A rules-file title the workbook
+lacks is SP-5405. Every rule not written is a console warning with its code,
+and the status line adds `· k rules not written to Excel`. `.xlsx` only.
+
 ## The controls (`/ui`)
 
 - **List arrow** (`cell` slot, Edit only): appears in every cell a `list` rule
   covers. It opens the rule's current choices, and picking one sets the cell
   with `store.setCell`, which can be undone.
 - **Status** (`status` slot, View and Edit): `3 validation warnings`, plus
-  `· 1 rule not checked` when rules were skipped.
+  `· 1 rule not checked` when rules were skipped, plus `· 2 rules not written
+  to Excel` after an export that wrote the rules file.
 
 `<sheetpane-errors>` lists the rule rows with the reviewer's own errors. Its
 author filter (Anyone · People · Workbook rules · File comments) shows only

package/dist/check.d.ts

@@ -0,0 +1,26 @@
+import { type CheckOptions, type SheetpaneError } from '@sheetpane/grid/check';
+import { type ValidationOptions } from './plugin.js';
+export type { Book, Rule, RuleKind, Operator, SkipReason, Evaluate } from './rules.js';
+export { rulesOf, listOptions, ruleWords, shiftFormula, parseOperand } from './rules.js';
+export { PLUGIN_ID, ERROR_TYPE, AUTHOR, skippedRules, lastReport, validateSheet, validation, listRuleAt, type ValidationOptions, type SkippedRule, type SkipReport } from './plugin.js';
+/**
+ * The errors a pane running this plugin holds once a file has loaded — the workbook's own
+ * validation rules, plus whatever else `options` names (a rules file, column rules, other plugins) —
+ * computed with no page (SR-VALIDATION decision 11). `@sheetpane/grid/check`'s `check()` with
+ * `validation({ severity })` added (an id `"validation"` in `plugins` means the same plugin). Give a
+ * formula engine (`formulas()`) in `plugins` for `custom` rules, as in a pane.
+ * @param file - The `.xlsx` or `.csv` bytes.
+ * @param options - `@sheetpane/grid/check`'s options, and `severity` — what a broken rule gets (default `warning`).
+ * @returns The errors, SheetpaneError v1, in the grid check's order.
+ * @example
+ * ```ts
+ * import { check } from '@sheetpane/validation/check';
+ *
+ * // `bytes`: the file as your runtime reads it — `await readFile(path)` in Node
+ * const found = await check(bytes, { name: 'budget.xlsx', severity: 'error' });
+ * for (const e of found) console.log(`${e.sheet}!${e.range}: ${e.message}`);
+ * ```
+ * @see https://github.com/arpitarya/sheetpane/blob/main/records/0108_VALIDATION.md
+ */
+export declare function check(file: Uint8Array | ArrayBuffer | Blob, options?: CheckOptions & ValidationOptions): Promise<SheetpaneError[]>;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,YAAY,EAAe,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAChH,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE5E,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAExL;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,EAAE,OAAO,GAAE,YAAY,GAAG,iBAAsB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAMtI"}

package/dist/check.js

@@ -0,0 +1,36 @@
+// @sheetpane/validation/check — the workbook's own `<dataValidations>`, checked with no page (W-54):
+// the plugin and its evaluator, registering nothing and importing no element, and `check()` — the
+// grid's `@sheetpane/grid/check` with this plugin on. Runs in Node, a worker or a page. The
+// one-rule `check(rule, …)` of the main entry is not re-exported here: `check` names the workbook check.
+import { check as checkPane } from '@sheetpane/grid/check';
+import { PLUGIN_ID, validation } from './plugin.js';
+export { rulesOf, listOptions, ruleWords, shiftFormula, parseOperand } from './rules.js';
+export { PLUGIN_ID, ERROR_TYPE, AUTHOR, skippedRules, lastReport, validateSheet, validation, listRuleAt } from './plugin.js';
+/**
+ * The errors a pane running this plugin holds once a file has loaded — the workbook's own
+ * validation rules, plus whatever else `options` names (a rules file, column rules, other plugins) —
+ * computed with no page (SR-VALIDATION decision 11). `@sheetpane/grid/check`'s `check()` with
+ * `validation({ severity })` added (an id `"validation"` in `plugins` means the same plugin). Give a
+ * formula engine (`formulas()`) in `plugins` for `custom` rules, as in a pane.
+ * @param file - The `.xlsx` or `.csv` bytes.
+ * @param options - `@sheetpane/grid/check`'s options, and `severity` — what a broken rule gets (default `warning`).
+ * @returns The errors, SheetpaneError v1, in the grid check's order.
+ * @example
+ * ```ts
+ * import { check } from '@sheetpane/validation/check';
+ *
+ * // `bytes`: the file as your runtime reads it — `await readFile(path)` in Node
+ * const found = await check(bytes, { name: 'budget.xlsx', severity: 'error' });
+ * for (const e of found) console.log(`${e.sheet}!${e.range}: ${e.message}`);
+ * ```
+ * @see https://github.com/arpitarya/sheetpane/blob/main/records/0108_VALIDATION.md
+ */
+export function check(file, options = {}) {
+    const { severity, ...rest } = options;
+    const own = () => validation(severity ? { severity } : {});
+    const plugins = (rest.plugins ?? []).map((p) => (p === PLUGIN_ID ? own() : p));
+    if (!plugins.some((p) => typeof p !== 'string' && p.id === PLUGIN_ID))
+        plugins.unshift(own());
+    return checkPane(file, { ...rest, plugins });
+}
+//# sourceMappingURL=check.js.map

package/dist/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,kGAAkG;AAClG,4FAA4F;AAC5F,yGAAyG;AACzG,OAAO,EAAE,KAAK,IAAI,SAAS,EAAuD,MAAM,uBAAuB,CAAC;AAChH,OAAO,EAAE,SAAS,EAAE,UAAU,EAA0B,MAAM,aAAa,CAAC;AAG5E,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAA6D,MAAM,aAAa,CAAC;AAExL;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,KAAK,CAAC,IAAqC,EAAE,OAAO,GAAqC,EAAE;IACzG,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAwB,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC;QAAE,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9F,OAAO,SAAS,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/index.d.ts

@@ -1,60 +1,19 @@
-import { type ErrorDraft, type Plugin, type Severity, type WorkbookStore } from '@sheetpane/grid';
-import { type Book, type Rule, type SkipReason } from './rules.js';
+import { type Plugin, type Severity } from '@sheetpane/grid';
 export type { Book, Rule, RuleKind, Operator, SkipReason, Evaluate } from './rules.js';
 export { rulesOf, listOptions, ruleWords, check, shiftFormula, parseOperand } from './rules.js';
-/** The plugin's id, and the name `plugins="…"` takes. */
-export declare const PLUGIN_ID = "validation";
-/** The `type` of every error this plugin raises. */
-export declare const ERROR_TYPE = "validation";
-/** The `author` of every error this plugin raises: the workbook's own rules, not a person. */
-export declare const AUTHOR = "workbook";
+export { PLUGIN_ID, ERROR_TYPE, AUTHOR, skippedRules, lastReport, validateSheet, listRuleAt, type SkippedRule, type SkipReport } from './plugin.js';
+export { RULES_OPTION, RULES_OPTION_LABEL, validationOf, rulesAsValidations, writeRules, lastRulesWrite, mainBlockCount, type MappedRule, type RuleConflict, type RulesWritePlan, type RulesWriteReport, type UnwrittenReason, type UnwrittenRule } from './write.js';
 /** Options for {@link validation}. */
 export interface ValidationOptions {
     /** The severity a broken rule gets; `warning` by default. */
     severity?: Severity;
+    /**
+     * The Download menu's *Write rules as Excel dropdowns* switch, on or off at first (W-58): the host's rules file (and
+     * the element's `columns`) written into the `.xlsx` as the workbook's own data validation. Off by default;
+     * `export({ rulesAsValidation: true })` turns it on for one export.
+     */
+    rulesAsValidation?: boolean;
 }
-/** A rule that is not checked: where it is, its type, and why (`custom`, `operand`, `operator`, `type`, `source`). */
-export interface SkippedRule {
-    sheet: string;
-    sqref: string;
-    type: string;
-    reason: SkipReason;
-    detail: string;
-}
-/** How many of a workbook's rules are checked, and the ones that are not. */
-export interface SkipReport {
-    /** Rules the workbook holds (`type="none"` excluded). */
-    rules: number;
-    /** Rules this pane checks. */
-    checked: number;
-    /** Rules it cannot check, and why. `skipped.length` is the count `sheetpane-load` would carry. */
-    skipped: SkippedRule[];
-}
-/**
- * The rules a workbook holds that are not checked, and why. Given a store, a
- * `custom` rule counts as checked when its `derive` plugin offers `evaluate()`;
- * given a bare workbook, every `custom` rule is skipped.
- *
- * @param from - The workbook, or the store holding it.
- * @returns The report; all zero when no workbook is loaded.
- */
-export declare function skippedRules(from: Book | WorkbookStore): SkipReport;
-/**
- * The last report `validate` made for a workbook (the status line reads it).
- *
- * @param book - The workbook, or `undefined`.
- * @returns The report, or `undefined` before the first `validate`.
- */
-export declare function lastReport(book: Book | undefined): SkipReport | undefined;
-/**
- * Every failing cell on one sheet: one error draft per cell (the first rule it breaks), within the used range.
- *
- * @param sheet - The sheet's name.
- * @param store - The workbook store.
- * @param severity - The drafts' severity; default `warning`.
- * @returns The drafts — `type: 'validation'`, `author: 'workbook'`, `found`, `expected` and `message` filled.
- */
-export declare function validateSheet(sheet: string, store: WorkbookStore, severity?: Severity): ErrorDraft[];
 /**
  * The data-validation plugin: checks the workbook's own `<dataValidations>` rules on load and after every change,
  * through the `validate` hook. A cell that breaks a rule is one error (`type: 'validation'`, `author: 'workbook'`)
@@ -62,7 +21,11 @@ export declare function validateSheet(sheet: string, store: WorkbookStore, sever
  * (`@sheetpane/formulas`); rules it cannot check are listed by {@link skippedRules}. Importing this module
  * registers it as `validation`; the list arrow and status count are in `@sheetpane/validation/ui`.
  *
- * @param o - The severity a broken rule gets; default `warning`.
+ * On export (`exportPatch`, W-58) it can also write the host's rules file, and the element's `columns`, into the
+ * `.xlsx` as the workbook's own data validation — the Download menu's *Write rules as Excel dropdowns*, or
+ * `export({ rulesAsValidation: true })`. What Excel cannot hold is listed on the console and the status line.
+ *
+ * @param o - The severity a broken rule gets (default `warning`); whether the rules are written by default (no).
  * @returns The plugin (`id: 'validation'`).
  * @see https://github.com/arpitarya/sheetpane/blob/main/records/0108_VALIDATION.md
  * @example
@@ -80,16 +43,15 @@ export declare function validateSheet(sheet: string, store: WorkbookStore, sever
  * import '@sheetpane/validation'; // registers `validation`
  * excel.setAttribute('plugins', 'validation formulas');
  * ```
- */
-export declare function validation(o?: ValidationOptions): Plugin;
-/**
- * The checkable `list` rule covering a cell, if any — the list arrow's `appliesTo`.
+ * @example
+ * ```ts
+ * import { lastRulesWrite } from '@sheetpane/validation';
  *
- * @param store - The workbook store.
- * @param sheet - The sheet's name.
- * @param row - The cell's row, 0-based.
- * @param col - The cell's column, 0-based.
- * @returns The rule, or `undefined`.
+ * // the rules file written into the download as Excel's own dropdowns and checks
+ * excel.rules = { version: 1, sheets: { '*': { columns: { Status: { oneOf: ['Active', 'Inactive'] } } } } };
+ * const blob = await excel.export({ rulesAsValidation: true });
+ * console.log(lastRulesWrite(excel.workbook?.book)); // { written, merged, skipped, conflicts }
+ * ```
  */
-export declare function listRuleAt(store: WorkbookStore, sheet: string, row: number, col: number): Rule | undefined;
+export declare function validation(o?: ValidationOptions): Plugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkB,KAAK,UAAU,EAAE,KAAK,MAAM,EAAsB,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACtI,OAAO,EAAiF,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAElJ,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhG,yDAAyD;AACzD,eAAO,MAAM,SAAS,eAAe,CAAC;AACtC,oDAAoD;AACpD,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,8FAA8F;AAC9F,eAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC/G,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,GAAG,UAAU,CAcnE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAEzE;AAQD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,GAAE,QAAoB,GAAG,UAAU,EAAE,CAwB/G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAE,iBAAsB,GAAG,MAAM,CAU5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAI1G"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkB,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAsB,MAAM,iBAAiB,CAAC;AAIjG,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACpJ,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtQ,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAE,iBAAsB,GAAG,MAAM,CAY5D"}

package/dist/index.js

@@ -2,93 +2,15 @@
 // load and on every edit through the `validate` hook (W-18). A cell that breaks a
 // rule is one error: type `validation`, author `workbook`; the store resolves it
 // when the cell passes and reopens it when it fails again.
-// Headless: this entry never imports ./ui.js. Importing it in Node is safe.
+// Headless: this entry never imports ./ui.js. Importing it in Node is safe; the
+// same plugin with no registration, and without the Download switch, is
+// `@sheetpane/validation/check` (W-54).
 import { registerPlugin } from '@sheetpane/grid';
-import { a1, check, covers, evaluatorOf, ruleWords, rulesOf, skipOf, textAt, usedRange } from './rules.js';
+import { PLUGIN_ID, validation as checking } from './plugin.js';
+import { RULES_OPTION, RULES_OPTION_LABEL, writeRules } from './write.js';
 export { rulesOf, listOptions, ruleWords, check, shiftFormula, parseOperand } from './rules.js';
-/** The plugin's id, and the name `plugins="…"` takes. */
-export const PLUGIN_ID = 'validation';
-/** The `type` of every error this plugin raises. */
-export const ERROR_TYPE = 'validation';
-/** The `author` of every error this plugin raises: the workbook's own rules, not a person. */
-export const AUTHOR = 'workbook';
-const reports = new WeakMap();
-/**
- * The rules a workbook holds that are not checked, and why. Given a store, a
- * `custom` rule counts as checked when its `derive` plugin offers `evaluate()`;
- * given a bare workbook, every `custom` rule is skipped.
- *
- * @param from - The workbook, or the store holding it.
- * @returns The report; all zero when no workbook is loaded.
- */
-export function skippedRules(from) {
-    const store = 'getSnapshot' in from ? from : undefined;
-    const book = store ? store.book : from;
-    const out = { rules: 0, checked: 0, skipped: [] };
-    if (!book)
-        return out;
-    for (const s of book.sheets) {
-        for (const r of rulesOf(book, s.name)) {
-            out.rules++;
-            const skip = skipOf(r, store);
-            if (skip)
-                out.skipped.push({ sheet: s.name, sqref: r.dv.sqref.join(' '), type: r.dv.type, reason: skip.reason, detail: skip.detail });
-            else
-                out.checked++;
-        }
-    }
-    return out;
-}
-/**
- * The last report `validate` made for a workbook (the status line reads it).
- *
- * @param book - The workbook, or `undefined`.
- * @returns The report, or `undefined` before the first `validate`.
- */
-export function lastReport(book) {
-    return book ? reports.get(book) : undefined;
-}
-/** The rule's own error text — `errorTitle: error`, either alone — else the rule in words. */
-function messageOf(rule, words) {
-    const t = rule.dv.errorTitle?.trim(), e = rule.dv.error?.trim();
-    return t && e ? `${t}: ${e}` : t || e || words;
-}
-/**
- * Every failing cell on one sheet: one error draft per cell (the first rule it breaks), within the used range.
- *
- * @param sheet - The sheet's name.
- * @param store - The workbook store.
- * @param severity - The drafts' severity; default `warning`.
- * @returns The drafts — `type: 'validation'`, `author: 'workbook'`, `found`, `expected` and `message` filled.
- */
-export function validateSheet(sheet, store, severity = 'warning') {
-    const book = store.book, s = store.sheet(sheet);
-    if (!book || !s)
-        return [];
-    const rules = rulesOf(book, sheet).filter((r) => !skipOf(r, store));
-    if (!rules.length)
-        return [];
-    const evaluate = evaluatorOf(store);
-    const used = usedRange(store, s);
-    const out = [];
-    const flagged = new Set();
-    const memo = new Map(); // a fixed list source is read once per run
-    for (const rule of rules) {
-        for (const b of rule.boxes) {
-            for (let r = b.top; r <= Math.min(b.bottom, used.rows - 1); r++) {
-                for (let c = b.left; c <= Math.min(b.right, used.cols - 1); c++) {
-                    const ref = a1(r, c);
-                    if (flagged.has(ref) || check(rule, store, r, c, evaluate, memo) !== 'fail')
-                        continue;
-                    flagged.add(ref);
-                    const expected = ruleWords(rule, store, r, c);
-                    out.push({ sheet, range: ref, type: ERROR_TYPE, severity, found: textAt(store, sheet, ref) || '(blank)', expected, message: messageOf(rule, expected), author: AUTHOR });
-                }
-            }
-        }
-    }
-    return out;
-}
+export { PLUGIN_ID, ERROR_TYPE, AUTHOR, skippedRules, lastReport, validateSheet, listRuleAt } from './plugin.js';
+export { RULES_OPTION, RULES_OPTION_LABEL, validationOf, rulesAsValidations, writeRules, lastRulesWrite, mainBlockCount } from './write.js';
 /**
  * The data-validation plugin: checks the workbook's own `<dataValidations>` rules on load and after every change,
  * through the `validate` hook. A cell that breaks a rule is one error (`type: 'validation'`, `author: 'workbook'`)
@@ -96,7 +18,11 @@ export function validateSheet(sheet, store, severity = 'warning') {
  * (`@sheetpane/formulas`); rules it cannot check are listed by {@link skippedRules}. Importing this module
  * registers it as `validation`; the list arrow and status count are in `@sheetpane/validation/ui`.
  *
- * @param o - The severity a broken rule gets; default `warning`.
+ * On export (`exportPatch`, W-58) it can also write the host's rules file, and the element's `columns`, into the
+ * `.xlsx` as the workbook's own data validation — the Download menu's *Write rules as Excel dropdowns*, or
+ * `export({ rulesAsValidation: true })`. What Excel cannot hold is listed on the console and the status line.
+ *
+ * @param o - The severity a broken rule gets (default `warning`); whether the rules are written by default (no).
  * @returns The plugin (`id: 'validation'`).
  * @see https://github.com/arpitarya/sheetpane/blob/main/records/0108_VALIDATION.md
  * @example
@@ -114,33 +40,34 @@ export function validateSheet(sheet, store, severity = 'warning') {
  * import '@sheetpane/validation'; // registers `validation`
  * excel.setAttribute('plugins', 'validation formulas');
  * ```
+ * @example
+ * ```ts
+ * import { lastRulesWrite } from '@sheetpane/validation';
+ *
+ * // the rules file written into the download as Excel's own dropdowns and checks
+ * excel.rules = { version: 1, sheets: { '*': { columns: { Status: { oneOf: ['Active', 'Inactive'] } } } } };
+ * const blob = await excel.export({ rulesAsValidation: true });
+ * console.log(lastRulesWrite(excel.workbook?.book)); // { written, merged, skipped, conflicts }
+ * ```
  */
 export function validation(o = {}) {
-    const severity = o.severity ?? 'warning';
+    const writeByDefault = o.rulesAsValidation ?? false;
     return {
-        id: PLUGIN_ID,
-        provides: ['validate'],
-        validate(sheet, ctx) {
-            if (ctx.book && !reports.has(ctx.book))
-                reports.set(ctx.book, skippedRules(ctx.store));
-            return validateSheet(sheet, ctx.store, severity);
+        ...checking(o),
+        provides: ['validate', 'exportPatch'],
+        // W-58: the host's rules into the download as Excel's own dropdowns and checks, when the switch is on
+        async exportPatch(patch, ctx) {
+            if ((ctx.exportOptions?.[RULES_OPTION] ?? writeByDefault) !== true || !hostRules(ctx.store))
+                return;
+            await writeRules(patch, ctx.store);
         },
+        exportOptions: [{ key: RULES_OPTION, label: RULES_OPTION_LABEL, default: writeByDefault, applies: hostRules }],
     };
 }
-/**
- * The checkable `list` rule covering a cell, if any — the list arrow's `appliesTo`.
- *
- * @param store - The workbook store.
- * @param sheet - The sheet's name.
- * @param row - The cell's row, 0-based.
- * @param col - The cell's column, 0-based.
- * @returns The rule, or `undefined`.
- */
-export function listRuleAt(store, sheet, row, col) {
-    const book = store.book;
-    if (!book)
-        return undefined;
-    return rulesOf(book, sheet).find((r) => r.kind === 'list' && !r.skip && covers(r, row, col));
+/** Does the pane hold rules to write — a rules file, or column rules on the element? */
+function hostRules(store) {
+    const c = store.columnRules;
+    return c.document !== undefined || Object.keys(c.columns ?? {}).length > 0;
 }
 registerPlugin(PLUGIN_ID, () => validation());
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,kFAAkF;AAClF,iFAAiF;AACjF,2DAA2D;AAC3D,gFAAgF;AAChF,wEAAwE;AACxE,wCAAwC;AACxC,OAAO,EAAE,cAAc,EAAkD,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAAE,SAAS,EAAE,UAAU,IAAI,QAAQ,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG1E,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAqC,MAAM,aAAa,CAAC;AACpJ,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAA4H,MAAM,YAAY,CAAC;AActQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,UAAU,CAAC,CAAC,GAAsB,EAAE;IAClD,MAAM,cAAc,GAAG,CAAC,CAAC,iBAAiB,IAAI,KAAK,CAAC;IACpD,OAAO;QACL,GAAG,QAAQ,CAAC,CAAC,CAAC;QACd,QAAQ,EAAE,CAAC,UAAU,EAAE,aAAa,CAAC;QACrC,sGAAsG;QACtG,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG;YAC1B,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,YAAY,CAAC,IAAI,cAAc,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO;YACpG,MAAM,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QACD,aAAa,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;KAC/G,CAAC;AACJ,CAAC;AAED,wFAAwF;AACxF,SAAS,SAAS,CAAC,KAAoB;IACrC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;IAC5B,OAAO,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC7E,CAAC;AAED,cAAc,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,94 @@
+import type { ErrorDraft, Plugin, Severity, WorkbookStore } from '@sheetpane/grid/check';
+import { type Book, type Rule, type SkipReason } from './rules.js';
+/** The plugin's id, and the name `plugins="…"` takes. */
+export declare const PLUGIN_ID = "validation";
+/** The `type` of every error this plugin raises. */
+export declare const ERROR_TYPE = "validation";
+/** The `author` of every error this plugin raises: the workbook's own rules, not a person. */
+export declare const AUTHOR = "workbook";
+/** Options for {@link validation}. */
+export interface ValidationOptions {
+    /** The severity a broken rule gets; `warning` by default. */
+    severity?: Severity;
+}
+/** A rule that is not checked: where it is, its type, and why (`custom`, `operand`, `operator`, `type`, `source`). */
+export interface SkippedRule {
+    sheet: string;
+    sqref: string;
+    type: string;
+    reason: SkipReason;
+    detail: string;
+}
+/** How many of a workbook's rules are checked, and the ones that are not. */
+export interface SkipReport {
+    /** Rules the workbook holds (`type="none"` excluded). */
+    rules: number;
+    /** Rules this pane checks. */
+    checked: number;
+    /** Rules it cannot check, and why. `skipped.length` is the count `sheetpane-load` would carry. */
+    skipped: SkippedRule[];
+}
+/**
+ * The rules a workbook holds that are not checked, and why. Given a store, a
+ * `custom` rule counts as checked when its `derive` plugin offers `evaluate()`;
+ * given a bare workbook, every `custom` rule is skipped.
+ *
+ * @param from - The workbook, or the store holding it.
+ * @returns The report; all zero when no workbook is loaded.
+ */
+export declare function skippedRules(from: Book | WorkbookStore): SkipReport;
+/**
+ * The last report `validate` made for a workbook (the status line reads it).
+ *
+ * @param book - The workbook, or `undefined`.
+ * @returns The report, or `undefined` before the first `validate`.
+ */
+export declare function lastReport(book: Book | undefined): SkipReport | undefined;
+/**
+ * Every failing cell on one sheet: one error draft per cell (the first rule it breaks), within the used range.
+ *
+ * @param sheet - The sheet's name.
+ * @param store - The workbook store.
+ * @param severity - The drafts' severity; default `warning`.
+ * @returns The drafts — `type: 'validation'`, `author: 'workbook'`, `found`, `expected` and `message` filled.
+ */
+export declare function validateSheet(sheet: string, store: WorkbookStore, severity?: Severity): ErrorDraft[];
+/**
+ * The data-validation plugin: checks the workbook's own `<dataValidations>` rules on load and after every change,
+ * through the `validate` hook. A cell that breaks a rule is one error (`type: 'validation'`, `author: 'workbook'`)
+ * that resolves when the cell passes and reopens when it fails again. `custom` rules need a formula engine
+ * (`@sheetpane/formulas`); rules it cannot check are listed by {@link skippedRules}. `@sheetpane/validation`
+ * registers it as `validation`, with the Download menu's *Write rules as Excel dropdowns* added (W-58); the list arrow
+ * and status count are in `@sheetpane/validation/ui`.
+ *
+ * @param o - The severity a broken rule gets; default `warning`.
+ * @returns The plugin (`id: 'validation'`).
+ * @see https://github.com/arpitarya/sheetpane/blob/main/records/0108_VALIDATION.md
+ * @example
+ * ```ts
+ * import { createWorkbook } from '@sheetpane/grid';
+ * import { formulas } from '@sheetpane/formulas';
+ * import { skippedRules, validation } from '@sheetpane/validation';
+ *
+ * const book = createWorkbook({ plugins: [validation({ severity: 'error' }), formulas()] });
+ * await book.load(bytes, 'budget.xlsx');
+ * console.log(skippedRules(book).skipped);
+ * ```
+ * @example
+ * ```ts
+ * import '@sheetpane/validation'; // registers `validation`
+ * excel.setAttribute('plugins', 'validation formulas');
+ * ```
+ */
+export declare function validation(o?: ValidationOptions): Plugin;
+/**
+ * The checkable `list` rule covering a cell, if any — the list arrow's `appliesTo`.
+ *
+ * @param store - The workbook store.
+ * @param sheet - The sheet's name.
+ * @param row - The cell's row, 0-based.
+ * @param col - The cell's column, 0-based.
+ * @returns The rule, or `undefined`.
+ */
+export declare function listRuleAt(store: WorkbookStore, sheet: string, row: number, col: number): Rule | undefined;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAiB,QAAQ,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACxG,OAAO,EAAiF,KAAK,IAAI,EAAE,KAAK,IAAI,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAElJ,yDAAyD;AACzD,eAAO,MAAM,SAAS,eAAe,CAAC;AACtC,oDAAoD;AACpD,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,8FAA8F;AAC9F,eAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC/G,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,GAAG,UAAU,CAcnE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAEzE;AAQD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,GAAE,QAAoB,GAAG,UAAU,EAAE,CAwB/G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAE,iBAAsB,GAAG,MAAM,CAU5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAI1G"}