@rowsncolumns/spreadsheet 10.2.73 → 10.2.75

package/dist/esm/api/evaluate-formula.js

@@ -0,0 +1,109 @@
+/** `ERROR.TYPE` result → Excel error literal. */
+export const ERROR_TYPE_CODES = {
+    1: "#NULL!",
+    2: "#DIV/0!",
+    3: "#VALUE!",
+    4: "#REF!",
+    5: "#NAME?",
+    6: "#NUM!",
+    7: "#N/A",
+    8: "#GETTING_DATA",
+};
+/**
+ * The error code of a `FormulaError`-shaped result (the unwrapped reference
+ * `useCalculation().onRequestCalculate` returns the error instance rather
+ * than throwing; the wrapped calculators return `undefined`). Duck-typed like
+ * the wrapper's `isFormulaErrorLike` so no parser import is needed here.
+ */
+const formulaErrorCode = (value) => {
+    if (!(value instanceof Error))
+        return undefined;
+    const code = value.error;
+    return typeof code === "string" && code.startsWith("#") ? code : undefined;
+};
+const toEvaluationValue = (result) => {
+    const error = formulaErrorCode(result);
+    if (error)
+        return { error };
+    if (Array.isArray(result)) {
+        return result.map((row) => Array.isArray(row)
+            ? row.map((cell) => toEvaluationValue(cell))
+            : [toEvaluationValue(row)]);
+    }
+    if (result === null ||
+        result === undefined ||
+        typeof result === "string" ||
+        typeof result === "number" ||
+        typeof result === "boolean" ||
+        result instanceof Date) {
+        return result;
+    }
+    return String(result);
+};
+/**
+ * `onRequestCalculate` is the cell editor's live preview, so it reports
+ * DISPLAY text: the rnc engine stringifies numbers and booleans, the
+ * reference wrapper returns the formatted value (`1,234.50`, `$5.00`,
+ * `TRUE`). Substituting that text verbatim would turn `=A1=15` into
+ * `"15"=15` (FALSE) or `"1,234.50"*2` (#VALUE!), so the text is re-typed
+ * through the engine itself: `TYPE(expression)` says number / text /
+ * boolean, and a number is re-read as General text (`&""` keeps both probes
+ * clear of the cell's number format) so it parses back to a number.
+ */
+const retypeDisplayText = async (text, expression, calculate) => {
+    const typeCode = await calculate(`=TYPE(${expression})&""`);
+    switch (typeof typeCode === "string" ? typeCode.trim() : typeCode) {
+        case "1":
+        case 1: {
+            const direct = Number(text);
+            if (Number.isFinite(direct) && text.trim() !== "")
+                return direct;
+            const general = await calculate(`=(${expression})&""`);
+            const parsed = Number(typeof general === "string" ? general : NaN);
+            return Number.isFinite(parsed) ? parsed : text;
+        }
+        case "4":
+        case 4: {
+            const upper = text.trim().toUpperCase();
+            if (upper === "TRUE")
+                return true;
+            if (upper === "FALSE")
+                return false;
+            const numeric = await calculate(`=--(${expression})&""`);
+            return typeof numeric === "string" ? numeric.trim() === "1" : text;
+        }
+        default:
+            return text;
+    }
+};
+/**
+ * Build the Evaluate Formula stepper's `evaluate` from the grid's
+ * `onRequestCalculate` (the cell editor's live-preview calculator — a
+ * read-only scratch evaluation in both engines). A string result is
+ * re-typed through the engine (see `retypeDisplayText`); a `FormulaError`
+ * instance (unwrapped reference calculator) becomes the error literal; the
+ * wrapped calculators report a formula error as an empty result, so a blank
+ * answer is re-asked as `ERROR.TYPE(expression)` to recover the error
+ * literal and a genuine blank stays `null`.
+ */
+export const createExpressionEvaluator = (onRequestCalculate, sheetId, cell) => {
+    const calculate = (formula) => onRequestCalculate(formula, sheetId, cell.rowIndex, cell.columnIndex);
+    return async (expression) => {
+        const value = toEvaluationValue(await calculate(`=${expression}`));
+        if (typeof value === "string") {
+            return retypeDisplayText(value, expression, calculate);
+        }
+        if (value !== null && value !== undefined)
+            return value;
+        const errorType = await calculate(`=ERROR.TYPE(${expression})&""`);
+        const code = typeof errorType === "number"
+            ? errorType
+            : typeof errorType === "string"
+                ? Number(errorType)
+                : NaN;
+        if (ERROR_TYPE_CODES[code]) {
+            return { error: ERROR_TYPE_CODES[code] };
+        }
+        return null;
+    };
+};

package/dist/esm/api/excel-validation-kinds.d.ts

@@ -0,0 +1,71 @@
+import type { DataValidationRule, SheetRange } from "../types";
+/**
+ * Excel's data-validation "Allow" kinds that have no `ConditionType` of
+ * their own. Each is authored as Excel's `type` + `operator` + up to two
+ * formulas and stored two ways at once:
+ *
+ * - `condition` — what both engines evaluate for the red Invalid marker:
+ *   `whole` and `textLength` compose a `CUSTOM_FORMULA` over the range
+ *   anchor (the same shape both importers synthesize), `time` is a plain
+ *   `NUMBER_*` comparison over day-fraction serials;
+ * - `xlsxSource` — the Excel-native description both xlsx exporters replay
+ *   verbatim (`type="whole"` …), so the rule round-trips as what the user
+ *   picked instead of a decimal / custom rule.
+ *
+ * Imported rules already carry `xlsxSource`, so the editor reads them back
+ * as "Whole number between 1 and 10" rather than a custom formula.
+ */
+export type ExcelValidationKind = "whole" | "time" | "textLength";
+export type ExcelValidationOperator = "between" | "notBetween" | "equal" | "notEqual" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual";
+export type ExcelValidationSpec = {
+    kind: ExcelValidationKind;
+    operator: ExcelValidationOperator;
+    /** Bound(s) as the user typed them: a literal (`10`, `9:30 AM`) or `=ref`. */
+    formula1?: string;
+    formula2?: string;
+};
+export declare const EXCEL_VALIDATION_KIND_LABELS: ReadonlyArray<{
+    kind: ExcelValidationKind;
+    label: string;
+}>;
+export declare const EXCEL_VALIDATION_OPERATOR_LABELS: ReadonlyArray<{
+    operator: ExcelValidationOperator;
+    label: string;
+}>;
+/** Two-sided operators need both bounds. */
+export declare const isTwoSidedOperator: (operator: ExcelValidationOperator) => operator is "between" | "notBetween";
+/**
+ * Parse a typed time (`9:30`, `9:30 AM`, `21:05:10`, `24:00`, `0.5`) to
+ * Excel's serial. A bare non-negative number is taken as a serial already and
+ * kept whole (Excel's Time validation compares the full serial, so a
+ * date-time is out of a same-day range). `undefined` when unparsable.
+ */
+export declare const parseTimeToSerial: (text: string | undefined) => number | undefined;
+/** Render a day-fraction serial as `h:mm AM/PM` (seconds when non-zero). */
+export declare const formatTimeSerial: (serial: number) => string;
+/** The A1 anchor (range top-left) a relative custom formula is written against. */
+export declare const getValidationAnchor: (range: SheetRange | undefined) => string;
+/**
+ * Build the `condition` + `xlsxSource` pair for an Excel kind. Returns
+ * `undefined` when a required bound is missing (the editor keeps the form
+ * open in that case).
+ */
+export declare const buildExcelValidationRule: (spec: ExcelValidationSpec, anchor: string) => Pick<DataValidationRule, "condition" | "xlsxSource"> | undefined;
+/**
+ * Read an Excel kind back from a rule's `xlsxSource` (imported or authored
+ * here); `undefined` for every other rule. Time bounds come back as
+ * `h:mm AM/PM` text so the editor shows what the user would type.
+ */
+export declare const readExcelValidationSpec: (rule: Pick<DataValidationRule, "xlsxSource"> | undefined | null) => ExcelValidationSpec | undefined;
+/** A typed value that is a formula (`=…`) — validated on its result, not its text. */
+export declare const isFormulaEntry: (value: unknown) => value is string;
+/**
+ * Decide an Excel-kind rule for a freshly typed value without the
+ * calculator — the commit-time enforcement Excel applies (`stop` blocks a
+ * decimal in a whole-number cell). `undefined` when the bounds are
+ * formulas / references, or when the typed value is itself a formula
+ * (Excel validates the formula's RESULT after the recalc, so `=5` is a
+ * valid whole number), so the caller falls back to the flag-only marker.
+ */
+export declare const checkExcelValidationValue: (rule: Pick<DataValidationRule, "xlsxSource"> | undefined | null, value: string | boolean) => boolean | undefined;
+//# sourceMappingURL=excel-validation-kinds.d.ts.map

package/dist/esm/api/excel-validation-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-validation-kinds.d.ts","sourceRoot":"","sources":["../../../api/excel-validation-kinds.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,kBAAkB,EAClB,UAAU,EACX,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;AAElE,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,YAAY,GACZ,OAAO,GACP,UAAU,GACV,aAAa,GACb,UAAU,GACV,oBAAoB,GACpB,iBAAiB,CAAC;AAEtB,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,aAAa,CAAC;IACvD,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf,CAIA,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,aAAa,CAAC;IAC3D,QAAQ,EAAE,uBAAuB,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf,CASA,CAAC;AAOF,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,GAAI,UAAU,uBAAuB,yCACf,CAAC;AAwBtD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,GAAG,SAAS,KACvB,MAAM,GAAG,SAuBX,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,MAUjD,CAAC;AAoBF,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,GAAI,OAAO,UAAU,GAAG,SAAS,KAAG,MAKzD,CAAC;AAgCZ;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,MAAM,mBAAmB,EACzB,QAAQ,MAAM,KACb,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,YAAY,CAAC,GAAG,SAiDzD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,IAAI,CAAC,kBAAkB,EAAE,YAAY,CAAC,GAAG,SAAS,GAAG,IAAI,KAC9D,mBAAmB,GAAG,SAuBxB,CAAC;AAmCF,sFAAsF;AACtF,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACE,CAAC;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACpC,MAAM,IAAI,CAAC,kBAAkB,EAAE,YAAY,CAAC,GAAG,SAAS,GAAG,IAAI,EAC/D,OAAO,MAAM,GAAG,OAAO,KACtB,OAAO,GAAG,SAmCZ,CAAC"}

package/dist/esm/api/excel-validation-kinds.js

@@ -0,0 +1,287 @@
+import { cellToAddress } from "@rowsncolumns/utils";
+export const EXCEL_VALIDATION_KIND_LABELS = [
+    { kind: "whole", label: "Whole number" },
+    { kind: "time", label: "Time" },
+    { kind: "textLength", label: "Text length" },
+];
+export const EXCEL_VALIDATION_OPERATOR_LABELS = [
+    { operator: "between", label: "between" },
+    { operator: "notBetween", label: "not between" },
+    { operator: "equal", label: "equal to" },
+    { operator: "notEqual", label: "not equal to" },
+    { operator: "greaterThan", label: "greater than" },
+    { operator: "lessThan", label: "less than" },
+    { operator: "greaterThanOrEqual", label: "greater than or equal to" },
+    { operator: "lessThanOrEqual", label: "less than or equal to" },
+];
+const EXCEL_KINDS = new Set(["whole", "time", "textLength"]);
+const EXCEL_OPERATORS = new Set(EXCEL_VALIDATION_OPERATOR_LABELS.map((entry) => entry.operator));
+/** Two-sided operators need both bounds. */
+export const isTwoSidedOperator = (operator) => operator === "between" || operator === "notBetween";
+const NUMBER_CONDITION_BY_OPERATOR = {
+    between: "NUMBER_BETWEEN",
+    notBetween: "NUMBER_NOT_BETWEEN",
+    equal: "NUMBER_EQ",
+    notEqual: "NUMBER_NOT_EQ",
+    greaterThan: "NUMBER_GREATER",
+    lessThan: "NUMBER_LESS",
+    greaterThanOrEqual: "NUMBER_GREATER_THAN_EQ",
+    lessThanOrEqual: "NUMBER_LESS_THAN_EQ",
+};
+const stripEquals = (text) => {
+    const trimmed = text?.trim() ?? "";
+    return trimmed.startsWith("=") ? trimmed.slice(1).trim() : trimmed;
+};
+const TIME_PATTERN = /^(\d{1,2})(?::(\d{1,2}))?(?::(\d{1,2}))?\s*([AaPp][Mm]?)?$/;
+/**
+ * Parse a typed time (`9:30`, `9:30 AM`, `21:05:10`, `24:00`, `0.5`) to
+ * Excel's serial. A bare non-negative number is taken as a serial already and
+ * kept whole (Excel's Time validation compares the full serial, so a
+ * date-time is out of a same-day range). `undefined` when unparsable.
+ */
+export const parseTimeToSerial = (text) => {
+    const trimmed = text?.trim() ?? "";
+    if (!trimmed)
+        return undefined;
+    const asNumber = Number(trimmed);
+    if (Number.isFinite(asNumber)) {
+        return asNumber >= 0 ? asNumber : undefined;
+    }
+    const match = TIME_PATTERN.exec(trimmed);
+    if (!match)
+        return undefined;
+    let hours = Number(match[1]);
+    const minutes = Number(match[2] ?? 0);
+    const seconds = Number(match[3] ?? 0);
+    const meridiem = match[4]?.toLowerCase();
+    if (minutes > 59 || seconds > 59)
+        return undefined;
+    if (meridiem) {
+        if (hours < 1 || hours > 12)
+            return undefined;
+        if (meridiem.startsWith("p") && hours !== 12)
+            hours += 12;
+        if (meridiem.startsWith("a") && hours === 12)
+            hours = 0;
+    }
+    else if (hours > 24 || (hours === 24 && (minutes > 0 || seconds > 0))) {
+        // Excel accepts `24:00` as exactly 1.0 (midnight at the end of the day).
+        return undefined;
+    }
+    return (hours * 3600 + minutes * 60 + seconds) / 86400;
+};
+/** Render a day-fraction serial as `h:mm AM/PM` (seconds when non-zero). */
+export const formatTimeSerial = (serial) => {
+    const total = Math.round((serial - Math.floor(serial)) * 86400) % 86400;
+    const hours24 = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    const meridiem = hours24 >= 12 ? "PM" : "AM";
+    const hours12 = hours24 % 12 === 0 ? 12 : hours24 % 12;
+    const mm = String(minutes).padStart(2, "0");
+    const ss = seconds ? `:${String(seconds).padStart(2, "0")}` : "";
+    return `${hours12}:${mm}${ss} ${meridiem}`;
+};
+/**
+ * A bound as it goes into a formula / `xlsxSource`: references and formulas
+ * verbatim (no `=`), times as serials, numbers as typed.
+ */
+const toBoundFormula = (kind, text) => {
+    const raw = text?.trim() ?? "";
+    if (!raw)
+        return undefined;
+    if (raw.startsWith("="))
+        return stripEquals(raw);
+    if (kind === "time") {
+        const serial = parseTimeToSerial(raw);
+        return serial === undefined ? raw : String(serial);
+    }
+    return raw;
+};
+/** The A1 anchor (range top-left) a relative custom formula is written against. */
+export const getValidationAnchor = (range) => cellToAddress(range
+    ? { rowIndex: range.startRowIndex, columnIndex: range.startColumnIndex }
+    : { rowIndex: 1, columnIndex: 1 }) ?? "A1";
+const comparison = (subject, operator, a, b) => {
+    switch (operator) {
+        case "between":
+            return b === undefined
+                ? undefined
+                : `AND(${subject}>=${a},${subject}<=${b})`;
+        case "notBetween":
+            return b === undefined
+                ? undefined
+                : `OR(${subject}<${a},${subject}>${b})`;
+        case "equal":
+            return `${subject}=${a}`;
+        case "notEqual":
+            return `${subject}<>${a}`;
+        case "greaterThan":
+            return `${subject}>${a}`;
+        case "lessThan":
+            return `${subject}<${a}`;
+        case "greaterThanOrEqual":
+            return `${subject}>=${a}`;
+        case "lessThanOrEqual":
+            return `${subject}<=${a}`;
+    }
+};
+/**
+ * Build the `condition` + `xlsxSource` pair for an Excel kind. Returns
+ * `undefined` when a required bound is missing (the editor keeps the form
+ * open in that case).
+ */
+export const buildExcelValidationRule = (spec, anchor) => {
+    const formula1 = toBoundFormula(spec.kind, spec.formula1);
+    const formula2 = toBoundFormula(spec.kind, spec.formula2);
+    if (!formula1)
+        return undefined;
+    if (isTwoSidedOperator(spec.operator) && !formula2)
+        return undefined;
+    const xlsxSource = {
+        type: spec.kind,
+        operator: spec.operator,
+        formula1,
+        ...(isTwoSidedOperator(spec.operator) ? { formula2 } : {}),
+    };
+    if (spec.kind === "time") {
+        const condition = {
+            type: NUMBER_CONDITION_BY_OPERATOR[spec.operator],
+            values: [
+                {
+                    userEnteredValue: /^[A-Za-z$'!]/.test(formula1)
+                        ? `=${formula1}`
+                        : formula1,
+                },
+                ...(isTwoSidedOperator(spec.operator) && formula2
+                    ? [
+                        {
+                            userEnteredValue: /^[A-Za-z$'!]/.test(formula2)
+                                ? `=${formula2}`
+                                : formula2,
+                        },
+                    ]
+                    : []),
+            ],
+        };
+        return { condition, xlsxSource };
+    }
+    const subject = spec.kind === "textLength" ? `LEN(${anchor})` : anchor;
+    const body = comparison(subject, spec.operator, formula1, formula2);
+    if (!body)
+        return undefined;
+    const formula = spec.kind === "whole"
+        ? `=AND(ISNUMBER(${anchor}),${anchor}=INT(${anchor}),${body})`
+        : `=${body}`;
+    return {
+        condition: {
+            type: "CUSTOM_FORMULA",
+            values: [{ userEnteredValue: formula }],
+        },
+        xlsxSource,
+    };
+};
+/**
+ * Read an Excel kind back from a rule's `xlsxSource` (imported or authored
+ * here); `undefined` for every other rule. Time bounds come back as
+ * `h:mm AM/PM` text so the editor shows what the user would type.
+ */
+export const readExcelValidationSpec = (rule) => {
+    const source = rule?.xlsxSource;
+    if (!source || !EXCEL_KINDS.has(source.type))
+        return undefined;
+    const operator = (source.operator && EXCEL_OPERATORS.has(source.operator)
+        ? source.operator
+        : "between");
+    const kind = source.type;
+    const display = (formula) => {
+        if (formula === undefined || formula === "")
+            return undefined;
+        const asNumber = Number(formula);
+        if (Number.isFinite(asNumber)) {
+            return kind === "time" ? formatTimeSerial(asNumber) : formula;
+        }
+        return `=${formula}`;
+    };
+    return {
+        kind,
+        operator,
+        formula1: display(source.formula1),
+        formula2: display(source.formula2),
+    };
+};
+const compare = (subject, operator, a, b) => {
+    switch (operator) {
+        case "between":
+            return (b !== undefined &&
+                subject >= Math.min(a, b) &&
+                subject <= Math.max(a, b));
+        case "notBetween":
+            return (b !== undefined &&
+                (subject < Math.min(a, b) || subject > Math.max(a, b)));
+        case "equal":
+            return subject === a;
+        case "notEqual":
+            return subject !== a;
+        case "greaterThan":
+            return subject > a;
+        case "lessThan":
+            return subject < a;
+        case "greaterThanOrEqual":
+            return subject >= a;
+        case "lessThanOrEqual":
+            return subject <= a;
+    }
+};
+/** A typed value that is a formula (`=…`) — validated on its result, not its text. */
+export const isFormulaEntry = (value) => typeof value === "string" && value.trim().startsWith("=");
+/**
+ * Decide an Excel-kind rule for a freshly typed value without the
+ * calculator — the commit-time enforcement Excel applies (`stop` blocks a
+ * decimal in a whole-number cell). `undefined` when the bounds are
+ * formulas / references, or when the typed value is itself a formula
+ * (Excel validates the formula's RESULT after the recalc, so `=5` is a
+ * valid whole number), so the caller falls back to the flag-only marker.
+ */
+export const checkExcelValidationValue = (rule, value) => {
+    const source = rule?.xlsxSource;
+    if (!source || !EXCEL_KINDS.has(source.type))
+        return undefined;
+    if (isFormulaEntry(value))
+        return undefined;
+    const operator = (source.operator ?? "between");
+    if (!EXCEL_OPERATORS.has(operator))
+        return undefined;
+    const a = Number(source.formula1);
+    const b = source.formula2 === undefined ? undefined : Number(source.formula2);
+    if (!Number.isFinite(a))
+        return undefined;
+    if (isTwoSidedOperator(operator) &&
+        !(b !== undefined && Number.isFinite(b))) {
+        return undefined;
+    }
+    const text = typeof value === "boolean" ? (value ? "TRUE" : "FALSE") : value;
+    switch (source.type) {
+        case "textLength":
+            return compare(Array.from(text).length, operator, a, b);
+        case "whole": {
+            if (typeof value === "boolean")
+                return false;
+            const num = Number(text.trim());
+            if (!Number.isFinite(num) || !Number.isInteger(num))
+                return false;
+            return compare(num, operator, a, b);
+        }
+        case "time": {
+            if (typeof value === "boolean")
+                return false;
+            // Excel compares the cell's full serial against the bounds (a
+            // date-time such as 45292.5 is NOT between 9:00 and 12:00) — the same
+            // comparison the composed `NUMBER_*` condition makes for the marker.
+            const serial = parseTimeToSerial(text);
+            if (serial === undefined)
+                return false;
+            return compare(serial, operator, a, b);
+        }
+    }
+};

package/dist/esm/api/go-to-special.d.ts

@@ -0,0 +1,32 @@
+import type { GridRange } from "@rowsncolumns/grid";
+import type { CellData } from "../types";
+/**
+ * Excel's Go To Special categories that can be decided from cell data alone.
+ * (Row / column differences, precedents / dependents and objects are served
+ * by the trace arrows and the drawing layer, not by this dialog.)
+ */
+export type GoToSpecialKind = "blanks" | "constants" | "formulas" | "errors" | "notes" | "visible";
+export declare const GO_TO_SPECIAL_OPTIONS: ReadonlyArray<{
+    kind: GoToSpecialKind;
+    label: string;
+}>;
+export type GoToSpecialContext<T extends CellData = CellData> = {
+    sheetId: number;
+    /** The area to scan — the current selection, or the used range for a single cell. */
+    range: GridRange;
+    getCellData(sheetId: number, rowIndex: number, columnIndex: number): T | null | undefined;
+    isRowHidden?(rowIndex: number): boolean;
+    isColumnHidden?(columnIndex: number): boolean;
+    /** Scan guard — Excel refuses huge Go To Special selections as well. */
+    maxCells?: number;
+};
+/** Cells scanned before the search gives up (returns what it found so far). */
+export declare const GO_TO_SPECIAL_MAX_CELLS = 250000;
+/**
+ * Resolve a Go To Special category to the matching cells of `range`, packed
+ * into per-row runs of adjacent columns (what the selection layer paints).
+ * Hidden rows / columns are skipped for every kind — Excel never selects
+ * into a hidden cell from Go To Special. Returns `[]` when nothing matches.
+ */
+export declare const resolveGoToSpecial: <T extends CellData>(kind: GoToSpecialKind, context: GoToSpecialContext<T>) => GridRange[];
+//# sourceMappingURL=go-to-special.d.ts.map

package/dist/esm/api/go-to-special.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"go-to-special.d.ts","sourceRoot":"","sources":["../../../api/go-to-special.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,QAAQ,GACR,OAAO,GACP,SAAS,CAAC;AAEd,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC;IAChD,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,CAOA,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,CACT,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACxB,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,cAAc,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAmD/C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,QAAQ,EACnD,MAAM,eAAe,EACrB,SAAS,kBAAkB,CAAC,CAAC,CAAC,KAC7B,SAAS,EAoCX,CAAC"}

package/dist/esm/api/go-to-special.js

@@ -0,0 +1,96 @@
+export const GO_TO_SPECIAL_OPTIONS = [
+    { kind: "notes", label: "Notes" },
+    { kind: "constants", label: "Constants" },
+    { kind: "formulas", label: "Formulas" },
+    { kind: "errors", label: "Errors" },
+    { kind: "blanks", label: "Blanks" },
+    { kind: "visible", label: "Visible cells only" },
+];
+/** Cells scanned before the search gives up (returns what it found so far). */
+export const GO_TO_SPECIAL_MAX_CELLS = 250_000;
+const hasContent = (cell) => {
+    const ue = cell?.ue ?? cell?.userEnteredValue;
+    if (!ue)
+        return false;
+    return (ue.fv != null ||
+        ue.formulaValue != null ||
+        ue.sv != null ||
+        ue.stringValue != null ||
+        ue.nv != null ||
+        ue.numberValue != null ||
+        ue.bv != null ||
+        ue.boolValue != null);
+};
+const isFormula = (cell) => {
+    const ue = cell?.ue ?? cell?.userEnteredValue;
+    return typeof (ue?.fv ?? ue?.formulaValue) === "string";
+};
+const isError = (cell) => {
+    const ev = cell?.ev ?? cell?.effectiveValue;
+    const error = ev?.ev ?? ev?.errorValue;
+    return !!error && error.type === "Error";
+};
+const hasNote = (cell) => typeof cell?.note === "string" && cell.note.trim().length > 0;
+const matches = (kind, cell) => {
+    switch (kind) {
+        case "blanks":
+            return !hasContent(cell);
+        case "constants":
+            return hasContent(cell) && !isFormula(cell);
+        case "formulas":
+            return isFormula(cell);
+        case "errors":
+            return isError(cell);
+        case "notes":
+            return hasNote(cell);
+        case "visible":
+            return true;
+    }
+};
+/**
+ * Resolve a Go To Special category to the matching cells of `range`, packed
+ * into per-row runs of adjacent columns (what the selection layer paints).
+ * Hidden rows / columns are skipped for every kind — Excel never selects
+ * into a hidden cell from Go To Special. Returns `[]` when nothing matches.
+ */
+export const resolveGoToSpecial = (kind, context) => {
+    const { sheetId, range, getCellData, isRowHidden, isColumnHidden } = context;
+    const maxCells = context.maxCells ?? GO_TO_SPECIAL_MAX_CELLS;
+    const runs = [];
+    let scanned = 0;
+    for (let row = range.startRowIndex; row <= range.endRowIndex; row++) {
+        if (isRowHidden?.(row))
+            continue;
+        let runStart;
+        const flush = (endColumn) => {
+            if (runStart === undefined)
+                return;
+            runs.push({
+                startRowIndex: row,
+                endRowIndex: row,
+                startColumnIndex: runStart,
+                endColumnIndex: endColumn,
+            });
+            runStart = undefined;
+        };
+        for (let col = range.startColumnIndex; col <= range.endColumnIndex; col++) {
+            if (++scanned > maxCells) {
+                flush(col - 1);
+                return runs;
+            }
+            if (isColumnHidden?.(col)) {
+                flush(col - 1);
+                continue;
+            }
+            if (matches(kind, getCellData(sheetId, row, col))) {
+                if (runStart === undefined)
+                    runStart = col;
+            }
+            else {
+                flush(col - 1);
+            }
+        }
+        flush(range.endColumnIndex);
+    }
+    return runs;
+};

package/dist/esm/api/go-to.d.ts

@@ -0,0 +1,19 @@
+import type { NamedRange, SheetRange } from "../types";
+export type GoToResolverContext = {
+    /** The sheet an unqualified reference (`A1`, `B2:C4`) is resolved against. */
+    sheetId: number;
+    namedRanges?: NamedRange[] | null;
+    /** Resolves `Sheet2!A1` / `'My Sheet'!A1`. Sheet-qualified input fails without it. */
+    getSheetId?: (sheetName: string) => number | undefined;
+    rowCount?: number;
+    columnCount?: number;
+};
+/**
+ * Resolve what the user typed into Excel's Go To box: a defined name (case
+ * insensitive), an A1 reference (`A1`, `$B$2:C4`, `A:A`, `3:3`) or a
+ * sheet-qualified reference (`Sheet2!A1`, `'My Sheet'!B2:C3`). A leading `=`
+ * is tolerated. Returns `undefined` when nothing matches — the dialog shows
+ * Excel's "Reference is not valid." then.
+ */
+export declare const resolveGoToReference: (input: string, context: GoToResolverContext) => SheetRange | undefined;
+//# sourceMappingURL=go-to.d.ts.map

package/dist/esm/api/go-to.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"go-to.d.ts","sourceRoot":"","sources":["../../../api/go-to.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEvD,MAAM,MAAM,mBAAmB,GAAG;IAChC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAClC,sFAAsF;IACtF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAiBF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,MAAM,EACb,SAAS,mBAAmB,KAC3B,UAAU,GAAG,SA6Bf,CAAC"}

package/dist/esm/api/go-to.js

@@ -0,0 +1,41 @@
+import { addressToSheetRange } from "@rowsncolumns/utils";
+// Rows are 1-based: `A0` / `0:0` are "Reference is not valid." in Excel (on
+// this grid row 0 is the column header).
+const CELL = "\\$?[A-Za-z]{1,3}\\$?[1-9]\\d*";
+const COLUMN = "\\$?[A-Za-z]{1,3}";
+const ROW = "\\$?[1-9]\\d*";
+const A1_REFERENCE = new RegExp(`^(?:${CELL}(?::${CELL})?|${COLUMN}:${COLUMN}|${ROW}:${ROW})$`);
+/** `'My Sheet'` → `My Sheet` (doubled quotes unescaped); bare names pass through. */
+const unquoteSheetName = (name) => name.startsWith("'") && name.endsWith("'") && name.length >= 2
+    ? name.slice(1, -1).replace(/''/g, "'")
+    : name;
+/**
+ * Resolve what the user typed into Excel's Go To box: a defined name (case
+ * insensitive), an A1 reference (`A1`, `$B$2:C4`, `A:A`, `3:3`) or a
+ * sheet-qualified reference (`Sheet2!A1`, `'My Sheet'!B2:C3`). A leading `=`
+ * is tolerated. Returns `undefined` when nothing matches — the dialog shows
+ * Excel's "Reference is not valid." then.
+ */
+export const resolveGoToReference = (input, context) => {
+    const text = input.trim().replace(/^=/, "").trim();
+    if (!text)
+        return undefined;
+    const named = context.namedRanges?.find((range) => range.name.toLowerCase() === text.toLowerCase());
+    if (named?.range) {
+        return { ...named.range };
+    }
+    let sheetId = context.sheetId;
+    let reference = text;
+    const bang = text.lastIndexOf("!");
+    if (bang !== -1) {
+        const sheetName = unquoteSheetName(text.slice(0, bang).trim());
+        reference = text.slice(bang + 1).trim();
+        const resolved = context.getSheetId?.(sheetName);
+        if (resolved === undefined)
+            return undefined;
+        sheetId = resolved;
+    }
+    if (!A1_REFERENCE.test(reference))
+        return undefined;
+    return addressToSheetRange(reference.toUpperCase(), sheetId, context.rowCount, context.columnCount);
+};