@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/conditional-formatting.js

@@ -0,0 +1,464 @@
+// Serialising conditional formatting to the classic `<conditionalFormatting>` worksheet element.
+//
+// Each block names its target range(s) in a `sqref` attribute and holds one or more `<cfRule>`
+// children. A rule's shape depends on its type: a `dataBar`/`colorScale`/`iconSet` carries a scale
+// element (its `<cfvo>` anchors and colours), while a `cellIs`/`expression`/`top10`/… carries its
+// operands as `<formula>` children and points at a differential style by `dxfId`. A rule the library
+// does not model in depth still round-trips its attributes, so nothing is silently dropped on save.
+//
+// A data bar's richer facets — its gradient fill, its negative-value fill colour, its axis colour —
+// have no home in the classic `<dataBar>` element; Excel stores them only in the 2009 x14 extension.
+// So a data-bar rule carrying any of them is written twice: the classic element (its anchors and bar
+// colour, understood by every consumer) plus an `<x14:dataBar>` in the worksheet `<extLst>` carrying
+// the extras, the two linked by a shared id. The reader folds the extension back onto the classic
+// rule, so the gradient flag and the two extra colours survive a round-trip rather than being dropped.
+import { boolAttr, escapeAttr, escapeText, stripFormulaEquals } from "../../xml/xml.js";
+import { boolStrict, coerceNumericLiteral, localName, parseXml } from "../../xml/xml-read.js";
+// The x14/xm extension namespaces and ext-URI GUIDs are declared inline on the `<ext>` elements
+// exactly as Excel writes them, so no worksheet-root xmlns is needed. `CF_EXT_URI` scopes the
+// worksheet's x14 conditional formattings; `DATABAR_LINK_EXT_URI` scopes the `<x14:id>` link a
+// classic cfRule carries to name its extension.
+import { CF_EXT_URI, DATABAR_LINK_EXT_URI, XM_NS } from "./namespaces.js";
+import { colorAttrs, parseColor } from "./styles.js";
+import { x14Ext } from "./x14-ext.js";
+// Excel's default data bar when the author supplies none: a min/max anchor pair and its standard blue.
+const DEFAULT_DATABAR_CFVO = [{ type: 'min' }, { type: 'max' }];
+const DEFAULT_DATABAR_COLOR = { argb: 'FF638EC6' };
+// A data bar needs the x14 extension only when it carries a facet the classic element cannot express.
+// A plain data bar (anchors and bar colour alone) stays classic-only, so an unadorned rule never
+// fabricates an empty extension block.
+function needsDataBarExt(rule) {
+    return (rule.gradient !== undefined ||
+        rule.negativeFillColor !== undefined ||
+        rule.axisColor !== undefined);
+}
+// The synthetic id linking a classic cfRule to its x14 extension. Excel uses a random GUID; any unique
+// token that matches on both ends works, so a deterministic per-sheet index keeps the output stable
+// and testable.
+function dataBarExtGuid(index) {
+    return `{00000000-0000-0000-0000-${String(index + 1).padStart(12, '0')}}`;
+}
+// Assign every extended data bar its link id once, keyed by rule identity. The classic pass (which
+// emits the `<extLst>` link on the cfRule) and the extension pass (which emits the `<x14:cfRule id>`)
+// both read the id from this map, so the two ends of a link agree by construction — not by the two
+// passes happening to walk the rules in the same order. A rule absent from the map needs no extension.
+function dataBarExtLinks(formattings) {
+    const links = new Map();
+    let index = 0;
+    for (const cf of formattings) {
+        for (const rule of cf.rules) {
+            if (rule.type === 'dataBar' && needsDataBarExt(rule))
+                links.set(rule, dataBarExtGuid(index++));
+        }
+    }
+    return links;
+}
+// The three built-in visual rules. Each renders a built-in visual and carries no differential
+// style (so the write side skips the dxf), and each nests its `<color>` children differently (so
+// the read side, {@link ScaleKind}, tracks which one it is inside). This tuple drives both.
+const SCALE_KINDS = ['dataBar', 'colorScale', 'iconSet'];
+const SCALE_TYPES = new Set(SCALE_KINDS);
+/**
+ * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
+ * insertion order. Returns '' when the sheet has none. A rule missing a `priority` is assigned the
+ * next free one, so the output always satisfies Excel's requirement that every cfRule carry one.
+ */
+export function conditionalFormattingsXml(formattings, styles) {
+    if (formattings.length === 0)
+        return '';
+    const priority = { next: 1 };
+    const extLinks = dataBarExtLinks(formattings);
+    return formattings.map((cf) => blockXml(cf, styles, priority, extLinks)).join('');
+}
+/**
+ * The worksheet `<extLst>` `<ext>` carrying the x14 data-bar extensions, or '' when no data bar needs
+ * one. Each extension's `<x14:cfRule id>` is read from the same {@link dataBarExtLinks} map the classic
+ * pass uses for the `<x14:id>` its cfRule carries, so the two ends of a link always match. Emitted bare
+ * (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single `<extLst>` beside the
+ * data-validation extension.
+ */
+export function conditionalFormattingsExtXml(formattings) {
+    const extLinks = dataBarExtLinks(formattings);
+    const items = [];
+    for (const cf of formattings) {
+        for (const rule of cf.rules) {
+            const guid = extLinks.get(rule);
+            if (guid !== undefined)
+                items.push(x14DataBarXml(cf.ref, rule, guid));
+        }
+    }
+    if (items.length === 0)
+        return '';
+    return x14Ext(CF_EXT_URI, `<x14:conditionalFormattings>${items.join('')}</x14:conditionalFormattings>`);
+}
+// One `<x14:conditionalFormatting>`: an `<x14:cfRule type="dataBar" id>` mirroring the classic anchors
+// as `<x14:cfvo>` and adding the facets the classic element cannot carry (gradient, negative-fill and
+// axis colours), with the target range in an `<xm:sqref>` child — the shape Excel writes.
+function x14DataBarXml(ref, rule, guid) {
+    const cfvo = rule.cfvo && rule.cfvo.length > 0 ? rule.cfvo : DEFAULT_DATABAR_CFVO;
+    const anchors = cfvo.map(x14CfvoXml).join('');
+    const gradient = boolAttr('gradient', rule.gradient);
+    const negative = rule.negativeFillColor !== undefined
+        ? `<x14:negativeFillColor ${colorAttrs(rule.negativeFillColor)}/>`
+        : '';
+    const axis = rule.axisColor !== undefined ? `<x14:axisColor ${colorAttrs(rule.axisColor)}/>` : '';
+    return (`<x14:conditionalFormatting xmlns:xm="${XM_NS}">` +
+        `<x14:cfRule type="dataBar" id="${guid}">` +
+        `<x14:dataBar${gradient}>${anchors}${negative}${axis}</x14:dataBar>` +
+        `</x14:cfRule><xm:sqref>${escapeText(ref)}</xm:sqref></x14:conditionalFormatting>`);
+}
+// An x14 scale anchor. A `min`/`max` carries no value and self-closes; the rest wrap their value in an
+// `<xm:f>` (the extension form stores every anchor value as a formula).
+function x14CfvoXml(cfvo) {
+    const type = escapeAttr(cfvo.type);
+    if (cfvo.value === undefined)
+        return `<x14:cfvo type="${type}"/>`;
+    return `<x14:cfvo type="${type}"><xm:f>${escapeText(String(cfvo.value))}</xm:f></x14:cfvo>`;
+}
+// The `<extLst>` a classic data-bar cfRule carries to name its x14 extension by shared id.
+function cfRuleExtLinkXml(guid) {
+    return `<extLst>${x14Ext(DATABAR_LINK_EXT_URI, `<x14:id>${guid}</x14:id>`)}</extLst>`;
+}
+function blockXml(cf, styles, priority, extLinks) {
+    const rules = cf.rules.map((rule) => ruleXml(rule, styles, priority, extLinks)).join('');
+    return `<conditionalFormatting sqref="${escapeAttr(cf.ref)}">${rules}</conditionalFormatting>`;
+}
+function ruleXml(rule, styles, priority, extLinks) {
+    const p = rule.priority ?? priority.next;
+    // Keep the running counter ahead of any explicit priority so later auto-assigned ones stay unique.
+    priority.next = Math.max(priority.next, p) + 1;
+    const attrs = [`type="${escapeAttr(rule.type)}"`];
+    const dxfId = resolveDxfId(rule, styles);
+    if (dxfId !== undefined)
+        attrs.push(`dxfId="${dxfId}"`);
+    attrs.push(`priority="${p}"`);
+    if (rule.stopIfTrue)
+        attrs.push('stopIfTrue="1"');
+    if (rule.aboveAverage === false)
+        attrs.push('aboveAverage="0"');
+    if (rule.equalAverage)
+        attrs.push('equalAverage="1"');
+    if (rule.bottom)
+        attrs.push('bottom="1"');
+    if (rule.percent)
+        attrs.push('percent="1"');
+    if (rule.operator !== undefined)
+        attrs.push(`operator="${escapeAttr(rule.operator)}"`);
+    if (rule.text !== undefined)
+        attrs.push(`text="${escapeAttr(rule.text)}"`);
+    if (rule.timePeriod !== undefined)
+        attrs.push(`timePeriod="${escapeAttr(rule.timePeriod)}"`);
+    if (rule.rank !== undefined)
+        attrs.push(`rank="${rule.rank}"`);
+    if (rule.stdDev !== undefined)
+        attrs.push(`stdDev="${rule.stdDev}"`);
+    let body = SCALE_TYPES.has(rule.type) ? scaleXml(rule) : formulaeXml(rule.formulae);
+    // A data bar with x14-only facets links to its extension by the id assigned in dataBarExtLinks; the
+    // extension itself rides in the worksheet <extLst>. The link is the cfRule's last child, after the
+    // dataBar. A rule absent from the map carries no extension.
+    const extGuid = extLinks.get(rule);
+    if (extGuid !== undefined)
+        body += cfRuleExtLinkXml(extGuid);
+    return body === ''
+        ? `<cfRule ${attrs.join(' ')}/>`
+        : `<cfRule ${attrs.join(' ')}>${body}</cfRule>`;
+}
+// A rule points at a differential style either by a preserved index read from a file (`dxfId`) or by
+// a style authored on the rule (interned here). The preserved index wins — it references the original
+// file's dxf table, which the writer re-emits verbatim. Scale rules never carry one.
+function resolveDxfId(rule, styles) {
+    if (SCALE_TYPES.has(rule.type))
+        return undefined;
+    if (rule.dxfId !== undefined)
+        return Number(rule.dxfId);
+    if (rule.style !== undefined)
+        return styles.differentialStyleId(rule.style);
+    return undefined;
+}
+function formulaeXml(formulae) {
+    if (formulae === undefined)
+        return '';
+    return formulae.map((f) => `<formula>${escapeText(stripFormulaEquals(f))}</formula>`).join('');
+}
+function scaleXml(rule) {
+    if (rule.type === 'dataBar')
+        return dataBarXml(rule);
+    if (rule.type === 'colorScale')
+        return colorScaleXml(rule);
+    return iconSetXml(rule);
+}
+// A data bar states its low and high anchors and its bar colour. The minimal call (no cfvo, no colour)
+// gains Excel's own defaults — a min/max anchor pair and the standard blue — rather than an invalid
+// empty element. The gradient flag and the negative-fill/axis colours have no home in this classic
+// element; they ride in the x14 extension (see {@link conditionalFormattingsExtXml}), linked from the
+// cfRule that wraps this by a shared id.
+function dataBarXml(rule) {
+    const cfvo = rule.cfvo && rule.cfvo.length > 0 ? rule.cfvo : DEFAULT_DATABAR_CFVO;
+    const color = rule.color ?? DEFAULT_DATABAR_COLOR;
+    const anchors = cfvo.map(cfvoXml).join('');
+    return `<dataBar>${anchors}<color ${colorAttrs(color)}/></dataBar>`;
+}
+// A colour scale pairs each anchor with a colour; a missing colour list falls back to none, still a
+// well-formed (if plain) element.
+function colorScaleXml(rule) {
+    const anchors = (rule.cfvo ?? []).map(cfvoXml).join('');
+    const colors = (rule.colors ?? []).map((c) => `<color ${colorAttrs(c)}/>`).join('');
+    return `<colorScale>${anchors}${colors}</colorScale>`;
+}
+function iconSetXml(rule) {
+    const name = rule.iconSet !== undefined ? ` iconSet="${escapeAttr(rule.iconSet)}"` : '';
+    const anchors = (rule.cfvo ?? []).map(cfvoXml).join('');
+    return `<iconSet${name}>${anchors}</iconSet>`;
+}
+// One scale anchor. `min`/`max` carry no value; the rest state theirs in `val` (a formula anchor's
+// value is its formula text, escaped like any attribute).
+function cfvoXml(cfvo) {
+    const val = cfvo.value !== undefined ? ` val="${escapeAttr(String(cfvo.value))}"` : '';
+    return `<cfvo type="${escapeAttr(cfvo.type)}"${val}/>`;
+}
+/**
+ * Parse a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
+ * blocks supply every rule; the x14 extension (`<x14:conditionalFormatting>` inside `<extLst>`) is
+ * read only to enrich a classic data bar with the facets the classic element cannot carry — the
+ * gradient flag and the negative-fill and axis colours — matched by the shared id the two ends link
+ * on. An extension rule with no classic counterpart (a rule that lives only in x14) is ignored, so it
+ * is never half-read into a broken classic rule.
+ */
+export function parseConditionalFormattings(xml) {
+    const blocks = [];
+    let block;
+    let draft;
+    let scale;
+    let capturingFormula = false;
+    let formulaText = '';
+    // Classic data-bar rules that named an extension, paired with the id they linked on, plus the
+    // extensions gathered from the worksheet <extLst>. The two are married after the pass — the
+    // extension always follows the classic blocks in document order, so it is known by then.
+    const linked = [];
+    const extById = new Map();
+    let x14Ext;
+    let x14ExtId;
+    let capturingX14Id = false;
+    let x14IdText = '';
+    parseXml(xml, {
+        onOpen(name, attrs, selfClosing) {
+            const ln = localName(name);
+            if (name.includes(':')) {
+                // The `<x14:id>` a classic data bar carries to name its extension: capture its text into the
+                // open draft. The rest are the worksheet extension's own elements.
+                if (ln === 'id' && draft !== undefined) {
+                    capturingX14Id = true;
+                    x14IdText = '';
+                }
+                else if (ln === 'cfRule') {
+                    x14Ext = attrs.type === 'dataBar' && attrs.id !== undefined ? emptyExt() : undefined;
+                    x14ExtId = attrs.id;
+                }
+                else if (x14Ext !== undefined && ln === 'dataBar') {
+                    // gradient defaults to true in the x14 schema, so an absent attribute reads as a gradient.
+                    x14Ext.gradient = attrs.gradient !== '0';
+                }
+                else if (x14Ext !== undefined && ln === 'negativeFillColor') {
+                    x14Ext.negativeFillColor = parseColor(attrs);
+                }
+                else if (x14Ext !== undefined && ln === 'axisColor') {
+                    x14Ext.axisColor = parseColor(attrs);
+                }
+                return;
+            }
+            if (ln === 'conditionalFormatting') {
+                block = { ref: attrs.sqref ?? '', rules: [] };
+            }
+            else if (ln === 'cfRule' && block !== undefined) {
+                // A rule with no operands (e.g. duplicateValues) is a self-closing element that fires no
+                // close event, so it must be finalised here; one with children waits for its </cfRule>.
+                if (selfClosing) {
+                    block.rules.push(finalizeRule(newDraft(attrs)));
+                }
+                else {
+                    draft = newDraft(attrs);
+                    scale = undefined;
+                }
+            }
+            else if (draft !== undefined &&
+                (ln === 'dataBar' || ln === 'colorScale' || ln === 'iconSet')) {
+                scale = ln;
+                if (ln === 'iconSet' && attrs.iconSet !== undefined)
+                    draft.iconSet = attrs.iconSet;
+            }
+            else if (draft !== undefined && ln === 'cfvo') {
+                draft.cfvo.push(parseCfvo(attrs));
+            }
+            else if (draft !== undefined && ln === 'color') {
+                const color = parseColor(attrs);
+                if (scale === 'dataBar')
+                    draft.color = color;
+                else
+                    draft.colors.push(color);
+            }
+            else if (draft !== undefined && ln === 'formula') {
+                capturingFormula = true;
+                formulaText = '';
+            }
+        },
+        onText(chunk) {
+            if (capturingFormula)
+                formulaText += chunk;
+            if (capturingX14Id)
+                x14IdText += chunk;
+        },
+        onClose(name) {
+            const ln = localName(name);
+            if (name.includes(':')) {
+                if (ln === 'id' && capturingX14Id) {
+                    if (draft !== undefined)
+                        draft.x14Id = x14IdText;
+                    capturingX14Id = false;
+                }
+                else if (ln === 'cfRule' && x14Ext !== undefined && x14ExtId !== undefined) {
+                    extById.set(x14ExtId, x14Ext);
+                    x14Ext = undefined;
+                    x14ExtId = undefined;
+                }
+                return;
+            }
+            if (ln === 'formula' && capturingFormula) {
+                if (draft !== undefined)
+                    draft.formulae.push(coerceNumericLiteral(formulaText));
+                capturingFormula = false;
+            }
+            else if (ln === 'dataBar' || ln === 'colorScale' || ln === 'iconSet') {
+                scale = undefined;
+            }
+            else if (ln === 'cfRule' && draft !== undefined) {
+                const rule = finalizeRule(draft);
+                if (block !== undefined)
+                    block.rules.push(rule);
+                if (draft.x14Id !== undefined)
+                    linked.push({ rule, id: draft.x14Id });
+                draft = undefined;
+            }
+            else if (ln === 'conditionalFormatting' && block !== undefined) {
+                blocks.push(block);
+                block = undefined;
+            }
+        },
+    });
+    for (const { rule, id } of linked) {
+        const ext = extById.get(id);
+        if (ext === undefined)
+            continue;
+        if (ext.gradient !== undefined)
+            rule.gradient = ext.gradient;
+        if (ext.negativeFillColor !== undefined)
+            rule.negativeFillColor = ext.negativeFillColor;
+        if (ext.axisColor !== undefined)
+            rule.axisColor = ext.axisColor;
+    }
+    return blocks;
+}
+function emptyExt() {
+    return { gradient: undefined, negativeFillColor: undefined, axisColor: undefined };
+}
+/**
+ * Extract the differential-style (`<dxf>`) fragments from styles.xml, each verbatim. Preserving the
+ * raw XML — rather than reparsing and re-serialising — is what keeps a foreign dxf's number format a
+ * real format code on re-write instead of a coerced `"[object Object]"`, and keeps every conditional
+ * formatting's `dxfId` index pointing at the same style it did in the source file.
+ */
+export function parseDxfs(stylesXml) {
+    const block = /<dxfs\b[^>]*>([\s\S]*?)<\/dxfs>/.exec(stylesXml);
+    if (block === null)
+        return [];
+    const inner = block[1] ?? '';
+    return [...inner.matchAll(/<dxf\b[^>]*>[\s\S]*?<\/dxf>|<dxf\b[^>]*\/>/g)].map((m) => m[0] ?? '');
+}
+function newDraft(attrs) {
+    return {
+        type: attrs.type ?? '',
+        priority: parseFiniteAttr(attrs.priority),
+        stopIfTrue: boolStrict(attrs.stopIfTrue),
+        operator: attrs.operator,
+        text: attrs.text,
+        timePeriod: attrs.timePeriod,
+        rank: parseFiniteAttr(attrs.rank),
+        stdDev: parseFiniteAttr(attrs.stdDev),
+        percent: boolStrict(attrs.percent),
+        bottom: boolStrict(attrs.bottom),
+        // aboveAverage defaults to true in OOXML; only an explicit "0" means below-average.
+        aboveAverage: attrs.aboveAverage === undefined ? undefined : attrs.aboveAverage !== '0',
+        equalAverage: boolStrict(attrs.equalAverage),
+        dxfId: parseIndexAttr(attrs.dxfId),
+        iconSet: undefined,
+        formulae: [],
+        cfvo: [],
+        colors: [],
+        color: undefined,
+        x14Id: undefined,
+    };
+}
+// priority/rank/stdDev must be finite; a malformed value is dropped rather than propagated as NaN —
+// `priority` in particular feeds the writer's running priority counter (see `ruleXml`), so one bad
+// value would otherwise poison every later rule's auto-assigned priority on the same sheet.
+function parseFiniteAttr(value) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+// dxfId is preserved as the raw string (not renumbered) so it keeps pointing at the same slot in the
+// dxf table on re-write; it must still be a non-negative integer, so a malformed value is dropped
+// rather than later coercing to `dxfId="NaN"` in {@link resolveDxfId}.
+function parseIndexAttr(value) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    return Number.isInteger(n) && n >= 0 ? value : undefined;
+}
+function finalizeRule(draft) {
+    const rule = { type: draft.type };
+    if (draft.priority !== undefined)
+        rule.priority = draft.priority;
+    if (draft.stopIfTrue)
+        rule.stopIfTrue = true;
+    if (draft.operator !== undefined)
+        rule.operator = draft.operator;
+    if (draft.text !== undefined)
+        rule.text = draft.text;
+    if (draft.timePeriod !== undefined)
+        rule.timePeriod = draft.timePeriod;
+    if (draft.rank !== undefined)
+        rule.rank = draft.rank;
+    if (draft.stdDev !== undefined)
+        rule.stdDev = draft.stdDev;
+    if (draft.percent)
+        rule.percent = true;
+    if (draft.bottom)
+        rule.bottom = true;
+    if (draft.aboveAverage !== undefined)
+        rule.aboveAverage = draft.aboveAverage;
+    if (draft.equalAverage)
+        rule.equalAverage = true;
+    if (draft.dxfId !== undefined)
+        rule.dxfId = draft.dxfId;
+    if (draft.iconSet !== undefined)
+        rule.iconSet = draft.iconSet;
+    if (draft.formulae.length > 0)
+        rule.formulae = draft.formulae;
+    if (draft.cfvo.length > 0)
+        rule.cfvo = draft.cfvo;
+    if (draft.colors.length > 0)
+        rule.colors = draft.colors;
+    if (draft.color !== undefined)
+        rule.color = draft.color;
+    return rule;
+}
+function parseCfvo(attrs) {
+    const type = (attrs.type ?? 'num');
+    const cfvo = { type };
+    if (attrs.val !== undefined) {
+        // A `formula` anchor's value is an expression and stays a string; the rest are numeric.
+        cfvo.value = type === 'formula' ? attrs.val : coerceNumericLiteral(attrs.val);
+    }
+    return cfvo;
+}

package/dist/io/xlsx/data-validation.d.ts

@@ -0,0 +1,20 @@
+import type { DataValidationEntry } from '../../core/data-validation.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+/** The standard `<dataValidations>` element for the rules stored in the legacy form, or '' when the
+ * sheet has none of them — so a sheet with only extended (or no) validations stays byte-clean here.
+ * The extended rules are emitted separately by {@link dataValidationsExtXml}. */
+export declare function dataValidationsXml(entries: readonly DataValidationEntry[]): string;
+/** The `<ext>` carrying the extended (`<x14:dataValidation>`) rules, or '' when the sheet declares
+ * none. Emitted bare (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single
+ * `<extLst>` beside the conditional-formatting extension — a worksheet may carry at most one. */
+export declare function dataValidationsExtXml(entries: readonly DataValidationEntry[]): string;
+/** Parse every standard `<dataValidation>` out of a worksheet part into range-bound rules. */
+export declare function parseDataValidations(xml: string): DataValidationEntry[];
+/** Parse every extended `<x14:dataValidation>` out of a worksheet's `<extLst>` into range-bound
+ * rules tagged `extended`, so a cross-sheet or whole-column list validation Excel stored only in the
+ * 2009 extension form is read back rather than dropped. The standard parser ignores these (they are
+ * prefixed); this one, symmetrically, handles only the prefixed elements. */
+export declare function parseExtendedDataValidations(xml: string): DataValidationEntry[];
+/** Fold parsed validations onto a sheet, each bound to its original range and carrying its form: an
+ * `extended` entry is re-attached as extended so a round-trip writes it back to the x14 block. */
+export declare function applyDataValidations(sheet: Worksheet, entries: readonly DataValidationEntry[]): void;