@rowsncolumns/toolkit 24.4.2 → 24.4.4

package/dist/esm/helpers/implicit-intersection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@operand` → `SINGLE(operand)`, for every implicit-intersection `@` in
+ * `formula`. A parenthesised operand contributes its content (`@(A1:A3*2)`
+ * → `SINGLE(A1:A3*2)`); a signed operand keeps its sign inside the call
+ * (`@-A1:A10` → `SINGLE(-A1:A10)`). An `@` with nothing it can bind to is
+ * left as is.
+ */
+export declare function encodeImplicitIntersection(formula: string): string;
+/**
+ * `_xlfn.SINGLE(x)` / `SINGLE(x)` → `@x` (or `@(x)` when `x` is more than a
+ * single, optionally signed, operand, e.g. `_xlfn.SINGLE(A1:A3*2)` →
+ * `@(A1:A3*2)` but `_xlfn.SINGLE(-A1:A3)` → `@-A1:A3`), for every such call
+ * in `formula`.
+ */
+export declare function decodeImplicitIntersection(formula: string): string;
+//# sourceMappingURL=implicit-intersection.d.ts.map

package/dist/esm/helpers/implicit-intersection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implicit-intersection.d.ts","sourceRoot":"","sources":["../../../helpers/implicit-intersection.ts"],"names":[],"mappings":"AA4GA;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA6BlE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA+BlE"}

package/dist/esm/helpers/implicit-intersection.js

@@ -0,0 +1,184 @@
+/**
+ * Excel's implicit-intersection operator `@` (`=@A1:A10`, `=SUM(@rng)`,
+ * `=@INDEX(...)`) is a UI-only spelling: in sheet XML Excel 365 persists it
+ * as the `_xlfn.SINGLE(...)` function (a bare `@` in `<f>` is not valid file
+ * content), and re-renders `_xlfn.SINGLE(x)` as `@x` when it opens the file.
+ * These two transforms mirror that so a formula round-trips unchanged: the
+ * exporter encodes `@x` → `SINGLE(x)` (future-function qualification then
+ * adds the `_xlfn.` prefix) and the importer decodes `_xlfn.SINGLE(x)` → `@x`.
+ *
+ * Both work on the formula lexer's tokens, so `@` inside string literals and
+ * the this-row structured references `Table[@]` / `[@Column]` are left alone.
+ */
+import { lexify, tokenVocabulary } from "@rowsncolumns/calculator";
+const T = tokenVocabulary;
+const SINGLE_CALL = /^(?:_xlfn\.)?SINGLE\($/i;
+const PREFIX_TOKENS = new Set([T.PlusOp.name, T.MinOp.name, T.At.name]);
+const tokenName = (token) => token?.tokenType?.name;
+const tokenEnd = (token) => (token.endOffset ?? token.startOffset) + 1;
+const bracketDelta = (image) => {
+    let depth = 0;
+    for (const ch of image) {
+        if (ch === "[")
+            depth++;
+        else if (ch === "]")
+            depth--;
+    }
+    return depth;
+};
+/**
+ * Index of the last token of the primary operand that starts at `start`
+ * (a reference, name, constant, balanced call / paren group / array
+ * constant / structured reference, optionally behind a sheet prefix), or -1
+ * when no operand starts there.
+ */
+const primaryEnd = (tokens, start) => {
+    const token = tokens[start];
+    if (!token)
+        return -1;
+    switch (tokenName(token)) {
+        case T.Sheet.name:
+        case T.SheetQuoted.name:
+        case T.SheetRange.name:
+            return primaryEnd(tokens, start + 1);
+        case T.Function.name:
+        case T.OpenParen.name: {
+            let depth = 0;
+            for (let i = start; i < tokens.length; i++) {
+                const name = tokenName(tokens[i]);
+                if (name === T.Function.name || name === T.OpenParen.name)
+                    depth++;
+                else if (name === T.CloseParen.name)
+                    depth--;
+                if (depth === 0)
+                    return i;
+            }
+            return -1;
+        }
+        case T.OpenCurlyParen.name: {
+            for (let i = start + 1; i < tokens.length; i++) {
+                if (tokenName(tokens[i]) === T.CloseCurlyParen.name)
+                    return i;
+            }
+            return -1;
+        }
+        case T.TableName.name:
+        case T.TableColumnName.name:
+        case T.SpecialItem.name: {
+            let depth = 0;
+            for (let i = start; i < tokens.length; i++) {
+                depth += bracketDelta(tokens[i].image);
+                if (depth <= 0)
+                    return i;
+            }
+            return -1;
+        }
+        case T.Cell.name:
+        case T.Name.name:
+        case T.Column.name:
+        case T.RowAbsolute.name:
+        case T.Number.name:
+        case T.String.name:
+        case T.Boolean.name:
+        case T.FormulaErrorT.name:
+        case T.RefError.name:
+            return start;
+        default:
+            return -1;
+    }
+};
+/**
+ * Like `primaryEnd`, but also swallows leading sign / `@` prefixes (`-A1:A10`,
+ * `+A1`, `@A1`) and `:` range continuations (`A1:A10`, `A:A`). The prefixes
+ * belong to the operand because `@`, like unary `-`, is applied after the
+ * prefixes to its right (`@-A1:A10` is `@(-A1:A10)`), so its persisted form
+ * is `SINGLE(-A1:A10)` — a `@` left in front of a sign would be invalid
+ * sheet-XML content.
+ */
+const operandEnd = (tokens, start) => {
+    while (PREFIX_TOKENS.has(tokenName(tokens[start]) ?? ""))
+        start++;
+    let end = primaryEnd(tokens, start);
+    if (end === -1)
+        return -1;
+    while (tokenName(tokens[end + 1]) === T.Colon.name) {
+        const next = primaryEnd(tokens, end + 2);
+        if (next === -1)
+            break;
+        end = next;
+    }
+    return end;
+};
+/**
+ * `@operand` → `SINGLE(operand)`, for every implicit-intersection `@` in
+ * `formula`. A parenthesised operand contributes its content (`@(A1:A3*2)`
+ * → `SINGLE(A1:A3*2)`); a signed operand keeps its sign inside the call
+ * (`@-A1:A10` → `SINGLE(-A1:A10)`). An `@` with nothing it can bind to is
+ * left as is.
+ */
+export function encodeImplicitIntersection(formula) {
+    let current = formula;
+    for (;;) {
+        const tokens = lexify(current).tokens;
+        let replaced = false;
+        // Right-to-left so a nested `@` inside an operand is encoded first.
+        for (let i = tokens.length - 1; i >= 0; i--) {
+            if (tokenName(tokens[i]) !== T.At.name)
+                continue;
+            // `Table[@]` is the this-row item of a structured reference.
+            if (tokenName(tokens[i - 1]) === T.TableName.name)
+                continue;
+            const end = operandEnd(tokens, i + 1);
+            if (end === -1)
+                continue;
+            const first = tokens[i + 1];
+            const last = tokens[end];
+            const isParenGroup = tokenName(first) === T.OpenParen.name &&
+                primaryEnd(tokens, i + 1) === end;
+            const operand = isParenGroup
+                ? current.slice(tokenEnd(first), last.startOffset)
+                : current.slice(first.startOffset, tokenEnd(last));
+            current = `${current.slice(0, tokens[i].startOffset)}SINGLE(${operand})${current.slice(tokenEnd(last))}`;
+            replaced = true;
+            break;
+        }
+        if (!replaced)
+            return current;
+    }
+}
+/**
+ * `_xlfn.SINGLE(x)` / `SINGLE(x)` → `@x` (or `@(x)` when `x` is more than a
+ * single, optionally signed, operand, e.g. `_xlfn.SINGLE(A1:A3*2)` →
+ * `@(A1:A3*2)` but `_xlfn.SINGLE(-A1:A3)` → `@-A1:A3`), for every such call
+ * in `formula`.
+ */
+export function decodeImplicitIntersection(formula) {
+    let current = formula;
+    for (;;) {
+        const tokens = lexify(current).tokens;
+        let replaced = false;
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (tokenName(token) !== T.Function.name ||
+                !SINGLE_CALL.test(token.image)) {
+                continue;
+            }
+            const end = primaryEnd(tokens, i);
+            if (end === -1)
+                continue;
+            const close = tokens[end];
+            const inner = current.slice(tokenEnd(token), close.startOffset).trim();
+            if (!inner)
+                continue;
+            const innerTokens = lexify(inner).tokens;
+            const isSingleOperand = innerTokens.length > 0 &&
+                operandEnd(innerTokens, 0) === innerTokens.length - 1;
+            const body = isSingleOperand ? inner : `(${inner})`;
+            current = `${current.slice(0, token.startOffset)}@${body}${current.slice(tokenEnd(close))}`;
+            replaced = true;
+            break;
+        }
+        if (!replaced)
+            return current;
+    }
+}

package/dist/esm/print-settings.d.ts

@@ -0,0 +1,105 @@
+import type { GridRange } from "@rowsncolumns/common-types";
+import type { PrintHeaderFooter, PageMargins, PageSetup, PrintOptions, SheetPrintSettings, PrintTitles } from "@rowsncolumns/spreadsheet";
+/**
+ * Shared helpers for the sheet `printSettings` facet: the builtin
+ * `_xlnm.Print_Area` / `_xlnm.Print_Titles` defined-name formulas (XLSX), the
+ * Excel header/footer code language (`&L&P of &N`), and the ODS page-layout
+ * equivalents (paper sizes, `style:print` tokens, `<text:*>` fields).
+ */
+export declare const PRINT_AREA_NAME = "_xlnm.Print_Area";
+export declare const PRINT_TITLES_NAME = "_xlnm.Print_Titles";
+export declare const isBuiltinPrintName: (name: string | undefined | null) => name is "_xlnm.Print_Area" | "_xlnm.Print_Titles";
+/** Wrap a sheet name in single quotes when a formula reference requires it. */
+export declare const quoteSheetNameForRef: (name: string) => string;
+/** Split a defined-name formula on top-level commas (quote aware). */
+export declare const splitDefinedNameAreas: (formula: string) => string[];
+/** `'My Sheet'!$A$1:$B$2` → `{ sheetName: "My Sheet", ref: "$A$1:$B$2" }`. */
+export declare const splitSheetQualifiedRef: (part: string) => {
+    sheetName?: string;
+    ref: string;
+};
+/**
+ * Parse a `_xlnm.Print_Area` formula into 1-based inclusive rectangles.
+ * Bands (`$1:$2`, `$A:$B`) and non-rectangular parts are rejected; the sheet
+ * name is taken from the first qualified part.
+ */
+export declare const parsePrintAreaFormula: (formula: string) => {
+    sheetName?: string;
+    ranges: GridRange[];
+} | undefined;
+/**
+ * Parse a `_xlnm.Print_Titles` formula (`'Sheet'!$A:$B,'Sheet'!$1:$2` — any
+ * order, either band alone) into the repeated row / column bands.
+ */
+export declare const parsePrintTitlesFormula: (formula: string) => {
+    sheetName?: string;
+    titles: PrintTitles;
+} | undefined;
+/** `'Sheet'!$A$1:$D$10,'Sheet'!$F$2:$G$5` (Excel's own multi-area shape). */
+export declare const buildPrintAreaFormula: (sheetName: string, ranges: GridRange[]) => string | undefined;
+/** Columns first, then rows — the order Excel writes. */
+export declare const buildPrintTitlesFormula: (sheetName: string, titles: PrintTitles) => string | undefined;
+export declare const isValidPrintRange: (range: GridRange) => boolean;
+/**
+ * Drop empty sub-objects / empty arrays; returns `undefined` when nothing
+ * is left so callers can omit the facet entirely.
+ */
+export declare const compactPrintSettings: (settings: SheetPrintSettings | null | undefined) => SheetPrintSettings | undefined;
+export type HeaderFooterZones = {
+    left?: string;
+    center?: string;
+    right?: string;
+};
+/**
+ * Split an Excel header/footer code into its `&L` / `&C` / `&R` zones. Text
+ * before any zone marker belongs to the centre zone (Excel's rule). `&&`
+ * escapes are left untouched inside each zone.
+ */
+export declare const splitHeaderFooterZones: (code: string) => HeaderFooterZones;
+export declare const joinHeaderFooterZones: (zones: HeaderFooterZones) => string;
+export type HeaderFooterField = "page" | "pages" | "date" | "time" | "sheet" | "file" | "path";
+export type HeaderFooterToken = {
+    type: "text";
+    text: string;
+} | {
+    type: "field";
+    field: HeaderFooterField;
+};
+/**
+ * Tokenize one zone of header/footer code into literal text and field
+ * macros. Formatting codes (`&"Font,Style"`, `&12`, `&B`, `&Kff0000`, `&G`…)
+ * have no ODS counterpart and are dropped.
+ */
+export declare const tokenizeHeaderFooterZone: (zone: string) => HeaderFooterToken[];
+export declare const headerFooterZoneFromTokens: (tokens: HeaderFooterToken[]) => string;
+/** Every header/footer text on the facet is empty / absent. */
+export declare const isHeaderFooterEmpty: (hf: PrintHeaderFooter | null | undefined) => boolean;
+export declare const INCH_TO_CM = 2.54;
+/** Portrait page size in centimetres for a paper-size code. */
+export declare const paperSizeToCm: (code: number | null | undefined) => {
+    width: number;
+    height: number;
+} | undefined;
+/** Nearest paper-size code for a page (either orientation), or undefined. */
+export declare const paperSizeFromCm: (widthCm: number, heightCm: number) => number | undefined;
+/** Parse an ODF length (`2.54cm`, `1in`, `72pt`, `25.4mm`) to inches. */
+export declare const odsLengthToInches: (value: string | undefined | null) => number | undefined;
+export declare const inchesToOdsCm: (inches: number) => string;
+/**
+ * `style:print` token list. LibreOffice's default (attribute absent) is
+ * `objects charts drawings zero-values`; `grid` / `headers` map to
+ * `<printOptions gridLines headings>`.
+ */
+export declare const buildOdsPrintTokens: (options: PrintOptions | null | undefined) => string;
+export declare const parseOdsPrintTokens: (value: string | undefined | null) => PrintOptions | undefined;
+export declare const odsTableCentering: (options: PrintOptions | null | undefined) => "both" | "horizontal" | "vertical" | undefined;
+export declare const parseOdsTableCentering: (value: string | undefined | null) => Pick<PrintOptions, "horizontalCentered" | "verticalCentered">;
+export declare const isPageSetupEmpty: (setup: PageSetup | null | undefined) => boolean;
+export declare const isPageMarginsEmpty: (margins: PageMargins | null | undefined) => boolean;
+/** Excel's "Normal" margins — what every untouched worksheet carries. */
+export declare const DEFAULT_PAGE_MARGINS_IN: Required<{
+    [K in keyof PageMargins]: number;
+}>;
+/** `true` when the margins are exactly Excel's defaults (nothing to keep). */
+export declare const isDefaultPageMargins: (margins: PageMargins | null | undefined) => boolean;
+//# sourceMappingURL=print-settings.d.ts.map

package/dist/esm/print-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"print-settings.d.ts","sourceRoot":"","sources":["../../print-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAOnC;;;;;GAKG;AAEH,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAClD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,GAAG,SAAS,GAAG,IAAI,sDACV,CAAC;AAEzD,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,WAGZ,CAAC;AAEtC,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,KAAG,MAAM,EAe7D,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,GACjC,MAAM,MAAM,KACX;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAQnC,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,SAAS,MAAM,KACd;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,GAAG,SAehD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,KACd;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG,SA0BhD,CAAC;AAUF,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,GAChC,WAAW,MAAM,EACjB,QAAQ,SAAS,EAAE,KAClB,MAAM,GAAG,SAKX,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,GAClC,WAAW,MAAM,EACjB,QAAQ,WAAW,KAClB,MAAM,GAAG,SAuBX,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,YAIF,CAAC;AAKjD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,UAAU,kBAAkB,GAAG,IAAI,GAAG,SAAS,KAC9C,kBAAkB,GAAG,SAcvB,CAAC;AAIF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,KAAG,iBA4BrD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,OAAO,iBAAiB,KAAG,MAMhE,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,CAAC;AAEX,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAsBhD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,iBAAiB,EA+CxE,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,QAAQ,iBAAiB,EAAE,KAC1B,MAOU,CAAC;AAEd,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,GAAI,IAAI,iBAAiB,GAAG,IAAI,GAAG,SAAS,YAW5C,CAAC;AAIjC,eAAO,MAAM,UAAU,OAAO,CAAC;AAiB/B,+DAA+D;AAC/D,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,KAC9B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAItC,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,EACf,UAAU,MAAM,KACf,MAAM,GAAG,SASX,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,KAC/B,MAAM,GAAG,SAsBX,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,WACmB,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,SAAS,YAAY,GAAG,IAAI,GAAG,SAAS,WAMzC,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,KAC/B,YAAY,GAAG,SAOjB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,SAAS,YAAY,GAAG,IAAI,GAAG,SAAS,mDAKzE,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,KAC/B,IAAI,CAAC,YAAY,EAAE,oBAAoB,GAAG,kBAAkB,CAW9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,OAAO,SAAS,GAAG,IAAI,GAAG,SAAS,YAC/C,CAAC;AAEtB,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,GAAG,IAAI,GAAG,SAAS,YACnD,CAAC;AAExB,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC;KAC5C,CAAC,IAAI,MAAM,WAAW,GAAG,MAAM;CACjC,CAOA,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,GAAI,SAAS,WAAW,GAAG,IAAI,GAAG,SAAS,YASzE,CAAC"}