@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/conditional-formatting.js

@@ -1,4 +1,6 @@
 import { tokenSet } from '../token-set.js';
+import { cloneWith } from './clone.js';
+import { cloneBorder, cloneFill, cloneFont } from './style.js';
 export const isCfValueObjectType = tokenSet({
     num: true,
     percent: true,
@@ -6,6 +8,8 @@ export const isCfValueObjectType = tokenSet({
     min: true,
     percentile: true,
     formula: true,
+    autoMin: true,
+    autoMax: true,
 });
 export const isConditionalFormattingType = tokenSet({
     expression: true,
@@ -53,6 +57,16 @@ export const isCfTimePeriod = tokenSet({
     lastWeek: true,
     nextWeek: true,
 });
+export const isDataBarDirection = tokenSet({
+    context: true,
+    leftToRight: true,
+    rightToLeft: true,
+});
+export const isDataBarAxisPosition = tokenSet({
+    automatic: true,
+    middle: true,
+    none: true,
+});
 export const isIconSetType = tokenSet({
     '3Arrows': true,
     '3ArrowsGray': true,
@@ -71,29 +85,72 @@ export const isIconSetType = tokenSet({
     '5ArrowsGray': true,
     '5Rating': true,
     '5Quarters': true,
+    '3Stars': true,
+    '3Triangles': true,
+    '5Boxes': true,
 });
+export function isExtensionIconSet(iconSet) {
+    return iconSet === '3Stars' || iconSet === '3Triangles' || iconSet === '5Boxes';
+}
+export function isCfIconSetType(value) {
+    return value === 'NoIcons' || isIconSetType(value);
+}
 export function cloneConditionalFormatting(cf) {
-    return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
+    const copy = { ref: cf.ref, rules: cf.rules.map(cloneRule) };
+    if (cf.extended !== undefined)
+        copy.extended = cf.extended;
+    return copy;
+}
+export function ruleNeedsExtension(rule) {
+    return (rule.type === 'iconSet' &&
+        ((rule.iconSet !== undefined && isExtensionIconSet(rule.iconSet)) ||
+            (rule.icons !== undefined && rule.icons.length > 0)));
 }
+const RULE_CLONE = {
+    type: 'value',
+    priority: 'value',
+    stopIfTrue: 'value',
+    operator: 'value',
+    formulae: 'values',
+    text: 'value',
+    style: cloneStyle,
+    dxfId: 'value',
+    cfvo: 'records',
+    color: 'record',
+    colors: 'records',
+    minLength: 'value',
+    maxLength: 'value',
+    gradient: 'value',
+    border: 'value',
+    borderColor: 'record',
+    direction: 'value',
+    negativeFillColor: 'record',
+    negativeBorderColor: 'record',
+    negativeBarColorSameAsPositive: 'value',
+    negativeBarBorderColorSameAsPositive: 'value',
+    axisPosition: 'value',
+    axisColor: 'record',
+    iconSet: 'value',
+    icons: 'records',
+    reverse: 'value',
+    showValue: 'value',
+    rank: 'value',
+    percent: 'value',
+    bottom: 'value',
+    aboveAverage: 'value',
+    equalAverage: 'value',
+    stdDev: 'value',
+    timePeriod: 'value',
+};
 function cloneRule(rule) {
-    return {
-        ...rule,
-        ...(rule.formulae !== undefined ? { formulae: [...rule.formulae] } : {}),
-        ...(rule.cfvo !== undefined ? { cfvo: rule.cfvo.map((v) => ({ ...v })) } : {}),
-        ...(rule.color !== undefined ? { color: { ...rule.color } } : {}),
-        ...(rule.negativeFillColor !== undefined
-            ? { negativeFillColor: { ...rule.negativeFillColor } }
-            : {}),
-        ...(rule.axisColor !== undefined ? { axisColor: { ...rule.axisColor } } : {}),
-        ...(rule.colors !== undefined ? { colors: rule.colors.map((c) => ({ ...c })) } : {}),
-        ...(rule.style !== undefined ? { style: cloneStyle(rule.style) } : {}),
-    };
+    return cloneWith(rule, RULE_CLONE);
 }
+const STYLE_CLONE = {
+    font: cloneFont,
+    fill: cloneFill,
+    border: cloneBorder,
+    numFmt: 'value',
+};
 function cloneStyle(style) {
-    return {
-        ...style,
-        ...(style.font !== undefined ? { font: { ...style.font } } : {}),
-        ...(style.fill !== undefined ? { fill: { ...style.fill } } : {}),
-        ...(style.border !== undefined ? { border: { ...style.border } } : {}),
-    };
+    return cloneWith(style, STYLE_CLONE);
 }

package/dist/core/containers.d.ts

@@ -1,2 +1,14 @@
 export declare function overwrite<T extends object>(target: T, source: T): void;
 export declare function replaceContents<T>(array: T[], next: readonly T[]): void;
+/**
+ * Copy one key from `source` onto `target`, leaving `target` untouched when `source` omits it.
+ *
+ * One key at a time is the whole point, and the reason is a limit of the checker rather than a
+ * preference: over a union key the compiler cannot correlate `source[key]`'s type with `target[key]`'s,
+ * so a version taking the union needs a cast, and that cast is the one place a facet could be written
+ * into the wrong slot with nothing to notice. Bound to a single member here, the assignment is checked.
+ *
+ * Generic over the object as well as the key because these two lines had been written out once for a
+ * cell's formatting and once for a cell's content, each under its own paragraph making this point.
+ */
+export declare function copyKeyIfPresent<T extends object, K extends keyof T>(target: T, source: Readonly<T>, key: K): void;

package/dist/core/containers.js

@@ -8,3 +8,8 @@ export function replaceContents(array, next) {
     for (const item of next)
         array.push(item);
 }
+export function copyKeyIfPresent(target, source, key) {
+    const value = source[key];
+    if (value !== undefined)
+        target[key] = value;
+}

package/dist/core/data-validation-overlay.d.ts

@@ -1,4 +1,5 @@
 import { type DataValidation, type DataValidationEntry } from './data-validation.ts';
+import type { AxisSplice } from './grid-shift.ts';
 export declare class DataValidationOverlay {
     #private;
     /**
@@ -33,7 +34,12 @@ export declare class DataValidationOverlay {
      * attached to rather than on whatever moved into their place. A rule whose every target area fell
      * inside a deleted span is dropped with them.
      */
-    shift(axis: 'row' | 'col', start: number, count: number, delta: number): void;
+    shift(splice: AxisSplice): void;
+    /**
+     * Rewrite every rule's formula operands through `rewrite`, keeping a rule whose operands did not
+     * change as the same object. A numeric operand is not a formula and passes through.
+     */
+    mapFormulas(rewrite: (formula: string) => string): void;
     /** Drop every validation, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/data-validation-overlay.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { replaceContents } from './containers.js';
 import { cloneDataValidation, } from './data-validation.js';
 import { decodeSqrefRects, shiftSqref } from './merge.js';
@@ -8,7 +8,7 @@ export class DataValidationOverlay {
     add(sqref, rule, options = {}) {
         const rects = decodeSqrefRects(sqref);
         if (rects.length === 0) {
-            throw new AuthoringError(`data validation range "${sqref}" names no cells`);
+            throw new AuthoringError(`data validation range ${quoted(sqref)} names no cells`);
         }
         const stored = cloneDataValidation(rule);
         const entry = { sqref, rule: stored };
@@ -30,11 +30,11 @@ export class DataValidationOverlay {
         }
         return undefined;
     }
-    shift(axis, start, count, delta) {
+    shift(splice) {
         const entries = [];
         const rects = [];
         for (const entry of this.#entries) {
-            const sqref = shiftSqref(entry.sqref, axis, start, count, delta);
+            const sqref = shiftSqref(entry.sqref, splice);
             if (sqref === undefined)
                 continue;
             entries.push({ ...entry, sqref });
@@ -43,6 +43,21 @@ export class DataValidationOverlay {
         replaceContents(this.#entries, entries);
         replaceContents(this.#rects, rects);
     }
+    mapFormulas(rewrite) {
+        for (const [index, entry] of this.#entries.entries()) {
+            const formulae = entry.rule.formulae;
+            if (formulae === undefined)
+                continue;
+            const next = formulae.map((operand) => typeof operand === 'string' ? rewrite(operand) : operand);
+            if (next.every((operand, i) => operand === formulae[i]))
+                continue;
+            const rule = { ...entry.rule, formulae: next };
+            this.#entries[index] = { ...entry, rule };
+            const indexed = this.#rects[index];
+            if (indexed !== undefined)
+                this.#rects[index] = { rects: indexed.rects, rule };
+        }
+    }
     clear() {
         this.#entries.length = 0;
         this.#rects.length = 0;

package/dist/core/data-validation.d.ts

@@ -1,3 +1,5 @@
+import { type ClonePlan } from './clone.ts';
+import type { AssertNever } from './internal.ts';
 /** The kind of constraint a validation enforces. `list` is a dropdown; `custom` is an arbitrary
  * boolean formula; `none` constrains nothing and exists only to carry the rule's messages; the rest
  * bound a typed value (`whole`/`decimal`/`date`/`time`/`textLength`). */
@@ -13,6 +15,14 @@ export declare const isDataValidationOperator: (value: string) => value is DataV
 export type DataValidationErrorStyle = 'stop' | 'warning' | 'information';
 /** Narrow a raw `<dataValidation errorStyle>` token to a known {@link DataValidationErrorStyle}. */
 export declare const isDataValidationErrorStyle: (value: string) => value is DataValidationErrorStyle;
+/**
+ * How the input method editor behaves while a covered cell is edited. Only an East Asian input method
+ * acts on it: `hiragana`, the katakana, alpha and hangul widths switch its mode, `on` and `off` turn it
+ * on and off, `disabled` turns it off and keeps it off, and `noControl` leaves it as the user had it.
+ */
+export type DataValidationImeMode = 'noControl' | 'off' | 'on' | 'disabled' | 'hiragana' | 'fullKatakana' | 'halfKatakana' | 'fullAlpha' | 'halfAlpha' | 'fullHangul' | 'halfHangul';
+/** Narrow a raw `<dataValidation imeMode>` token to a known {@link DataValidationImeMode}. */
+export declare const isDataValidationImeMode: (value: string) => value is DataValidationImeMode;
 /** One validation rule. `formulae` holds the operand(s), `formula1` then optional `formula2`: a
  * numeric literal is stored as a number, while a cell reference, defined name, or list source keeps
  * its verbatim string. */
@@ -21,9 +31,17 @@ export interface DataValidation {
     operator?: DataValidationOperator;
     formulae?: (string | number)[];
     allowBlank?: boolean;
+    /**
+     * Hide the in-cell dropdown arrow of a `list` rule while still enforcing the list, the usual way to
+     * validate against a list without offering a picker. Stored as `showDropDown="1"`, an attribute
+     * whose name says the opposite of what it does.
+     */
+    suppressDropDown?: boolean;
     showInputMessage?: boolean;
     showErrorMessage?: boolean;
     errorStyle?: DataValidationErrorStyle;
+    /** How the input method editor behaves in a covered cell; absent leaves it as the user had it. */
+    imeMode?: DataValidationImeMode;
     error?: string;
     errorTitle?: string;
     prompt?: string;
@@ -42,4 +60,8 @@ export interface DataValidationEntry {
 }
 /** A defensive copy of a rule, so a stored validation never aliases the caller's object (nor its
  * `formulae` array). */
+declare const RULE_CLONE: ClonePlan<DataValidation>;
+/** The proof that {@link RULE_CLONE} names every field of the rule. */
+export type EveryDataValidationFieldIsCloned = AssertNever<Exclude<keyof Required<DataValidation>, keyof typeof RULE_CLONE>>;
 export declare function cloneDataValidation(rule: DataValidation): DataValidation;
+export {};

package/dist/core/data-validation.js

@@ -1,4 +1,5 @@
 import { tokenSet } from '../token-set.js';
+import { cloneWith } from './clone.js';
 export const isDataValidationType = tokenSet({
     none: true,
     list: true,
@@ -24,9 +25,34 @@ export const isDataValidationErrorStyle = tokenSet({
     warning: true,
     information: true,
 });
+export const isDataValidationImeMode = tokenSet({
+    noControl: true,
+    off: true,
+    on: true,
+    disabled: true,
+    hiragana: true,
+    fullKatakana: true,
+    halfKatakana: true,
+    fullAlpha: true,
+    halfAlpha: true,
+    fullHangul: true,
+    halfHangul: true,
+});
+const RULE_CLONE = {
+    type: 'value',
+    operator: 'value',
+    formulae: 'values',
+    allowBlank: 'value',
+    suppressDropDown: 'value',
+    showInputMessage: 'value',
+    showErrorMessage: 'value',
+    errorStyle: 'value',
+    imeMode: 'value',
+    error: 'value',
+    errorTitle: 'value',
+    prompt: 'value',
+    promptTitle: 'value',
+};
 export function cloneDataValidation(rule) {
-    return {
-        ...rule,
-        ...(rule.formulae !== undefined ? { formulae: [...rule.formulae] } : {}),
-    };
+    return cloneWith(rule, RULE_CLONE);
 }

package/dist/core/date-format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Render a `Date` through an Excel number-format code: `yyyy-mm-dd`, `d mmm yy`, `hh:mm:ss`.
+ *
+ * The one vocabulary this library speaks for dates. `Cell.numFmt` holds a code, `DEFAULT_DATE_NUMFMT`
+ * is one, `isDateFormat` classifies one, and the CSV writer's `dateFormat` used to be a moment.js
+ * token set instead -- case-sensitive, with `mm` meaning minutes and the month spelled `MM` -- so
+ * `writeCsv(wb, {dateFormat: cell.numFmt})`, the obvious thing to write, rendered every date cell as
+ * `2024-45-dd` with no throw and no warning. A library with two public date-format properties
+ * speaking different languages has no defensible answer to "which one is this".
+ *
+ * Codes are case-insensitive, as Excel's are. What is *not* covered, deliberately: the elapsed-time
+ * forms (`[h]`, `[mm]`), which measure a duration rather than name a moment, and the locale directive
+ * (`[$-409]`), which is dropped rather than honoured -- month and weekday names render in English.
+ * Both are recorded in ADR 0041.
+ *
+ * @param utc read the date's fields in UTC rather than in the runner's local time. A serial carries
+ *   no timezone, so a `Date` that came from one is UTC wall-clock and this should be `true`; a `Date`
+ *   a caller assigned may mean either.
+ */
+export declare function formatSerialDate(date: Date, code: string, utc: boolean): string;

package/dist/core/date-format.js

@@ -0,0 +1,170 @@
+const MONTH_NAMES = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+const WEEKDAY_NAMES = [
+    'Sunday',
+    'Monday',
+    'Tuesday',
+    'Wednesday',
+    'Thursday',
+    'Friday',
+    'Saturday',
+];
+function formatRuns(code) {
+    const runs = [];
+    const literal = (text) => {
+        if (text !== '')
+            runs.push({ kind: 'literal', text, count: text.length });
+    };
+    for (let i = 0; i < code.length; i++) {
+        const ch = code[i];
+        if (ch === ';')
+            break;
+        if (ch === '[') {
+            const end = code.indexOf(']', i);
+            i = end === -1 ? code.length : end;
+            continue;
+        }
+        if (ch === '"') {
+            const end = code.indexOf('"', i + 1);
+            literal(code.slice(i + 1, end === -1 ? code.length : end));
+            i = end === -1 ? code.length : end;
+            continue;
+        }
+        if (ch === '\\') {
+            literal(code[i + 1] ?? '');
+            i += 1;
+            continue;
+        }
+        const fraction = /^\.0+/.exec(code.slice(i));
+        const previous = runs.at(-1);
+        if (fraction !== null && previous?.kind === 'placeholder' && previous.text === 's') {
+            runs.push({ kind: 'placeholder', text: '.0', count: fraction[0].length - 1 });
+            i += fraction[0].length - 1;
+            continue;
+        }
+        const lower = ch.toLowerCase();
+        if (lower === 'y' || lower === 'm' || lower === 'd' || lower === 'h' || lower === 's') {
+            let count = 1;
+            while (code[i + count]?.toLowerCase() === lower)
+                count += 1;
+            runs.push({ kind: 'placeholder', text: lower, count });
+            i += count - 1;
+            continue;
+        }
+        const meridiem = /^(AM\/PM|A\/P)/i.exec(code.slice(i));
+        if (meridiem !== null) {
+            const token = meridiem[0];
+            if (token.length === 3)
+                runs.push({ kind: 'placeholder', text: 'a/p', count: 3, written: token });
+            else
+                runs.push({ kind: 'placeholder', text: 'am/pm', count: token.length });
+            i += token.length - 1;
+            continue;
+        }
+        literal(ch);
+    }
+    return runs;
+}
+function isMinuteRun(runs, index) {
+    for (let i = index - 1; i >= 0; i--) {
+        const run = runs[i];
+        if (run.kind === 'literal')
+            continue;
+        if (run.text === 'h')
+            return true;
+        break;
+    }
+    for (let i = index + 1; i < runs.length; i++) {
+        const run = runs[i];
+        if (run.kind === 'literal')
+            continue;
+        return run.text === 's';
+    }
+    return false;
+}
+export function formatSerialDate(date, code, utc) {
+    if (Number.isNaN(date.getTime()))
+        return '';
+    const runs = formatRuns(code);
+    const year = utc ? date.getUTCFullYear() : date.getFullYear();
+    const month = (utc ? date.getUTCMonth() : date.getMonth()) + 1;
+    const day = utc ? date.getUTCDate() : date.getDate();
+    const weekday = utc ? date.getUTCDay() : date.getDay();
+    const hour24 = utc ? date.getUTCHours() : date.getHours();
+    const minute = utc ? date.getUTCMinutes() : date.getMinutes();
+    const second = utc ? date.getUTCSeconds() : date.getSeconds();
+    const twelveHour = runs.some((run) => run.kind === 'placeholder' && (run.text === 'am/pm' || run.text === 'a/p'));
+    const hour = twelveHour ? hour24 % 12 || 12 : hour24;
+    const pad = (value, width) => String(value).padStart(width, '0');
+    let out = '';
+    for (const [index, run] of runs.entries()) {
+        if (run.kind === 'literal') {
+            out += run.text;
+            continue;
+        }
+        switch (run.text) {
+            case 'y':
+                out += run.count <= 2 ? pad(year % 100, 2) : String(year);
+                break;
+            case 'm':
+                if (isMinuteRun(runs, index)) {
+                    out += run.count >= 2 ? pad(minute, 2) : String(minute);
+                }
+                else if (run.count >= 5) {
+                    out += MONTH_NAMES[month - 1][0];
+                }
+                else if (run.count === 4) {
+                    out += MONTH_NAMES[month - 1];
+                }
+                else if (run.count === 3) {
+                    out += MONTH_NAMES[month - 1].slice(0, 3);
+                }
+                else {
+                    out += run.count === 2 ? pad(month, 2) : String(month);
+                }
+                break;
+            case 'd':
+                if (run.count >= 4)
+                    out += WEEKDAY_NAMES[weekday];
+                else if (run.count === 3)
+                    out += WEEKDAY_NAMES[weekday].slice(0, 3);
+                else
+                    out += run.count === 2 ? pad(day, 2) : String(day);
+                break;
+            case 'h':
+                out += run.count >= 2 ? pad(hour, 2) : String(hour);
+                break;
+            case 's':
+                out += run.count >= 2 ? pad(second, 2) : String(second);
+                break;
+            case '.0': {
+                const digits = pad(utc ? date.getUTCMilliseconds() : date.getMilliseconds(), 3);
+                out += `.${(digits + '000').slice(0, run.count)}`;
+                break;
+            }
+            case 'am/pm':
+                out += hour24 < 12 ? 'AM' : 'PM';
+                break;
+            case 'a/p': {
+                const written = run.written ?? 'A/P';
+                out += hour24 < 12 ? written.charAt(0) : written.charAt(2);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}

package/dist/core/date.d.ts

@@ -1,20 +1,40 @@
+/**
+ * Which date system a workbook counts its serials in: the `date1904` flag of `<workbookPr>`.
+ *
+ * Carried as the epoch year rather than as a boolean because it is what every conversion here
+ * actually needs, and a boolean would mean a `? 1904 : 1900` at each of them: five chances to write
+ * the ternary backwards, on a value whose wrongness is silent by construction (a date read under the
+ * wrong system is still a perfectly good date, four years off).
+ */
+export type DateEpoch = 1900 | 1904;
 /**
  * The number format applied to a `Date` cell that carries no explicit format of its own,
  * so the value renders, and reads back, as a date rather than a bare serial number.
  */
 export declare const DEFAULT_DATE_NUMFMT = "yyyy-mm-dd";
 /**
- * Convert a JS `Date` to its 1900-system Excel serial, reproducing the phantom-leap-day
- * quirk so the value renders on the calendar date Excel would show. Fractional serials
- * carry the time of day. The caller must reject a non-finite (invalid) date before here.
+ * Convert a JS `Date` to its Excel serial under the workbook's date system, reproducing the
+ * phantom-leap-day quirk (1900 only) so the value renders on the calendar date Excel would show.
+ * Fractional serials carry the time of day. The caller must reject a non-finite (invalid) date
+ * before here.
+ */
+export declare function dateToSerial(date: Date, epoch: DateEpoch): number;
+/**
+ * Convert an Excel serial back to a UTC `Date` under the workbook's date system, accounting in the
+ * 1900 system for the phantom 1900-02-29 so serial 1 reads as 1900-01-01 (not 1899-12-31) and
+ * consecutive serials map to consecutive days.
  */
-export declare function dateToSerial(date: Date): number;
+export declare function serialToDate(serial: number, epoch: DateEpoch): Date;
 /**
- * Convert a 1900-system Excel serial back to a UTC `Date`, accounting for the phantom
- * 1900-02-29 so serial 1 reads as 1900-01-01 (not 1899-12-31) and consecutive serials
- * map to consecutive days.
+ * Parse a date-bearing text field (a Strict-mode `t="d"` cell value, a core-property timestamp) to a
+ * `Date`, or `null` when it carries nothing parseable.
+ *
+ * The `null` is the point. `new Date('not-a-date')` is a `Date` whose time is `NaN`: it satisfies
+ * `instanceof Date` and every guard downstream, survives into the model, and reaches serialisation,
+ * where it writes back as the literal string `Invalid Date` and loses the value for good. Dropping it
+ * at the boundary is the only reading that cannot lie.
  */
-export declare function serialToDate(serial: number): Date;
+export declare function parseDateText(text: string): Date | null;
 /**
  * Whether a number-format code renders its value as a date or time. A format is a date
  * format when, once its non-formatting sections are removed (bracketed color/locale/
@@ -23,3 +43,18 @@ export declare function serialToDate(serial: number): Date;
  * while `yyyy-mm-dd`, `dd/mm/yyyy`, and `[$-409]mmmm d, yyyy` are.
  */
 export declare function isDateFormat(code: string): boolean;
+/**
+ * Surface a number stored under a date format as a `Date`, and leave everything else alone.
+ *
+ * OOXML has no date type: a date is a number plus a number format that renders it as one, so this
+ * one test is what separates `45000` from `2023-03-15` across every reader. Only a plain number
+ * qualifies; a string, a boolean or a formula result of another kind under a date format keeps its
+ * own kind.
+ *
+ * One function rather than three copies of the test, because the corpus asserts the rule is identical
+ * across serialisations: the `.xlsb` reader, the `.xlsx` cell decoder and the cached formula-result
+ * decoder must all answer the same, and three spellings of one rule are three chances to disagree.
+ * The workbook's {@link DateEpoch} rides along for exactly that reason: it is the one input to this
+ * test that is not the cell's, and the three used to agree on the wrong answer for a 1904 file.
+ */
+export declare function coerceDateSerial<T>(value: T, numFmt: string | undefined, epoch: DateEpoch): T | Date;

package/dist/core/date.js

@@ -1,15 +1,26 @@
 const MS_PER_DAY = 86_400_000;
 const EPOCH_1900_UTC = Date.UTC(1899, 11, 30);
 const PHANTOM_SERIAL = 60;
+const EPOCH_1904_UTC = Date.UTC(1904, 0, 1);
 export const DEFAULT_DATE_NUMFMT = 'yyyy-mm-dd';
-export function dateToSerial(date) {
+export function dateToSerial(date, epoch) {
+    if (epoch === 1904)
+        return (date.getTime() - EPOCH_1904_UTC) / MS_PER_DAY;
     const days = (date.getTime() - EPOCH_1900_UTC) / MS_PER_DAY;
-    return days <= PHANTOM_SERIAL ? days - 1 : days;
+    return Math.floor(days) <= PHANTOM_SERIAL ? days - 1 : days;
 }
-export function serialToDate(serial) {
+export function serialToDate(serial, epoch) {
+    if (epoch === 1904)
+        return new Date(EPOCH_1904_UTC + serial * MS_PER_DAY);
     const dayOffset = serial < PHANTOM_SERIAL ? serial + 1 : serial;
     return new Date(EPOCH_1900_UTC + dayOffset * MS_PER_DAY);
 }
+export function parseDateText(text) {
+    if (text === '')
+        return null;
+    const date = new Date(text);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
 export function isDateFormat(code) {
     const stripped = code
         .replace(/\[[^\]]*\]/g, '')
@@ -17,3 +28,8 @@ export function isDateFormat(code) {
         .replace(/\\./g, '');
     return /[ymdhs]/i.test(stripped);
 }
+export function coerceDateSerial(value, numFmt, epoch) {
+    return typeof value === 'number' && numFmt !== undefined && isDateFormat(numFmt)
+        ? serialToDate(value, epoch)
+        : value;
+}

package/dist/core/formula-references.d.ts

@@ -0,0 +1,26 @@
+import type { AxisSplice } from './grid-shift.ts';
+/**
+ * Shift every relative reference in a formula by `colDelta` columns and `rowDelta` rows, leaving
+ * absolute (`$`-anchored) axes fixed. This is how a shared-formula clone recovers its own formula from
+ * the master's: a master `A1*2` shared one row down reads back as `A2*2`, `$A$1*B1` shared one row and
+ * one column across as `$A$1*C2`, and `COUNTIF(A:A,A1)` shared one column right as `COUNTIF(B:B,B1)`.
+ * Whole-column and whole-row ranges shift at each relative end, as cells do. String literals,
+ * single-quoted sheet names, and bracketed structured references are copied verbatim, and a
+ * sheet-qualified reference shifts while its sheet name is untouched. Function names and defined names
+ * are not reference-shaped, so they pass through.
+ */
+export declare function translateFormula(formula: string, colDelta: number, rowDelta: number): string;
+/** A splice as a formula sees it: which sheet's lines moved, and how. */
+export interface SheetSplice {
+    /** The spliced sheet's name, matched in any case. */
+    readonly sheet: string;
+    readonly splice: AxisSplice;
+}
+/**
+ * Rewrite a formula's references for a splice of `edit.sheet`. `home` is the sheet the formula belongs
+ * to, whose name an unqualified reference means; `undefined` for a formula that has none, such as a
+ * workbook-scoped defined name, whose references to a sheet are always qualified.
+ *
+ * Returns the formula unchanged, as the same string, when nothing in it moved.
+ */
+export declare function spliceFormula(formula: string, home: string | undefined, edit: SheetSplice): string;