@rowsncolumns/utils 9.3.0 → 9.4.0

package/dist/esm/table-names.js

@@ -0,0 +1,129 @@
+/**
+ * Excel's rules for a table name (Table Design → Table Name / "Rename an Excel table"):
+ *
+ * - starts with a letter, an underscore (`_`) or a backslash (`\`);
+ * - the rest is letters, digits, periods (`.`) and underscores — no spaces;
+ * - is not a cell reference (`A1`, `R1C1`, `XFD1048576`) and not the lone `C` / `R` shortcuts;
+ * - is at most 255 characters;
+ * - is unique across the workbook, compared case-insensitively — against the other tables AND the
+ *   defined names (Excel refuses a table named like an existing defined name, and a defined name
+ *   spelled like an existing table).
+ *
+ * Both engines create and rename tables through these checks (the rnc store mirrors them in Rust and
+ * surfaces the same messages through its `rejections` channel), and the table editor's validation
+ * schema shows the same text under the name field.
+ */
+export const TABLE_NAME_MAX_LENGTH = 255;
+// Built with `RegExp` (not literals) so the `u` flag survives the CJS build's ES5 target.
+const LEADING_CHAR = new RegExp("^[\\p{L}_\\\\]", "u");
+const BODY_CHARS = new RegExp("^[\\p{L}\\p{N}._]*$", "u");
+/** `A1`-style — up to three ASCII column letters then a row number. */
+const A1_REFERENCE = /^[A-Za-z]{1,3}\d+$/;
+/** `R1C1`-style — `R`/`C` each followed by an optional index (`RC`, `R1C`, `R1C1`). */
+const R1C1_REFERENCE = /^[Rr]\d*[Cc]\d*$/;
+/** `C` and `R` alone select the active cell's column / row in the Name Box. */
+const RESERVED_SHORTCUT = /^[CcRr]$/;
+export const TABLE_NAME_REQUIRED_MESSAGE = "Enter a table name.";
+export const TABLE_NAME_TOO_LONG_MESSAGE = `Table names can't be longer than ${TABLE_NAME_MAX_LENGTH} characters.`;
+export const TABLE_NAME_SPACES_MESSAGE = "Table names can't contain spaces.";
+export const TABLE_NAME_LEADING_CHAR_MESSAGE = "Table names must start with a letter, an underscore (_) or a backslash (\\).";
+export const TABLE_NAME_INVALID_CHAR_MESSAGE = "Table names can only contain letters, numbers, periods (.) and underscores (_).";
+export const TABLE_NAME_CELL_REFERENCE_MESSAGE = "Table names can't be a cell reference such as A1 or R1C1.";
+export const tableNameDuplicateMessage = (existing) => `A table named "${existing}" already exists in this workbook. Table names must be unique.`;
+export const tableNameDefinedNameMessage = (existing) => `A defined name "${existing}" already exists in this workbook. Table names and defined names must be unique.`;
+/** `create-table` with an `id` an existing table already holds is refused on both engines (#668 T-56). */
+export const tableIdDuplicateMessage = (id) => `A table with the id "${id}" already exists in this workbook.`;
+export const definedNameTableNameMessage = (existing) => `A table named "${existing}" already exists in this workbook. Table names and defined names must be unique.`;
+/** The entry of `names` that equals `name` case-insensitively, the way Excel compares names. */
+const findNameCollision = (name, names) => {
+    if (!names) {
+        return undefined;
+    }
+    const lower = name.toLowerCase();
+    for (const existing of names) {
+        if (existing.toLowerCase() === lower) {
+            return existing;
+        }
+    }
+    return undefined;
+};
+/** True when `name` reads as a cell reference in either A1 or R1C1 notation. */
+export const isCellReferenceLikeName = (name) => A1_REFERENCE.test(name) ||
+    R1C1_REFERENCE.test(name) ||
+    RESERVED_SHORTCUT.test(name);
+/**
+ * The reason `name` is not an acceptable table name, or `undefined` when it is. `existingNames` are
+ * the OTHER tables' names in the workbook (leave the table being renamed out of it) and
+ * `existingDefinedNames` the workbook's defined names; duplicates against either are detected
+ * case-insensitively, the way Excel compares names.
+ */
+export const validateTableName = (name, existingNames, existingDefinedNames) => {
+    if (!name) {
+        return TABLE_NAME_REQUIRED_MESSAGE;
+    }
+    if (name.length > TABLE_NAME_MAX_LENGTH) {
+        return TABLE_NAME_TOO_LONG_MESSAGE;
+    }
+    if (/\s/.test(name)) {
+        return TABLE_NAME_SPACES_MESSAGE;
+    }
+    if (!LEADING_CHAR.test(name)) {
+        return TABLE_NAME_LEADING_CHAR_MESSAGE;
+    }
+    if (!BODY_CHARS.test(name.slice(1))) {
+        return TABLE_NAME_INVALID_CHAR_MESSAGE;
+    }
+    if (isCellReferenceLikeName(name)) {
+        return TABLE_NAME_CELL_REFERENCE_MESSAGE;
+    }
+    const duplicate = findNameCollision(name, existingNames);
+    if (duplicate !== undefined) {
+        return tableNameDuplicateMessage(duplicate);
+    }
+    const definedName = findNameCollision(name, existingDefinedNames);
+    if (definedName !== undefined) {
+        return tableNameDefinedNameMessage(definedName);
+    }
+    return undefined;
+};
+export const isValidTableName = (name, existingNames, existingDefinedNames) => validateTableName(name, existingNames, existingDefinedNames) === undefined;
+/**
+ * The reason a defined name `name` cannot be created or renamed to — it is spelled like one of
+ * `tableNames` (case-insensitive) — or `undefined` when no table holds it. Excel keeps tables and
+ * defined names in one namespace.
+ */
+export const validateDefinedNameAgainstTables = (name, tableNames) => {
+    const table = findNameCollision(name, tableNames);
+    return table === undefined ? undefined : definedNameTableNameMessage(table);
+};
+/**
+ * The default name for a new table: `Table1`, `Table2`, … — the LOWEST number no existing table
+ * uses (case-insensitive), so a deleted table's number is reissued and the result never collides.
+ * `format` localises the pattern (`(n) => \`Tabelle${n}\``).
+ */
+export const getNextTableName = (existingNames, format = (index) => `Table${index}`) => {
+    const taken = new Set();
+    for (const name of existingNames) {
+        taken.add(name.toLowerCase());
+    }
+    let index = 1;
+    while (taken.has(format(index).toLowerCase())) {
+        index++;
+    }
+    return format(index);
+};
+/**
+ * The name for a copy of table `base`: `Sales2`, `Sales3`, … — the LOWEST number no existing table
+ * uses (case-insensitive), the way Excel names the table on a duplicated sheet.
+ */
+export const getNextTableCopyName = (base, existingNames) => {
+    const taken = new Set();
+    for (const name of existingNames) {
+        taken.add(name.toLowerCase());
+    }
+    let index = 2;
+    while (taken.has(`${base}${index}`.toLowerCase())) {
+        index++;
+    }
+    return `${base}${index}`;
+};

package/dist/esm/table-styles.d.ts

@@ -32,6 +32,15 @@ export type BandingProperties = {
     secondBandBorder?: Maybe<Borders>;
     totalRowColor?: Maybe<Color>;
     totalRowBorder?: Maybe<Borders>;
+    /**
+     * Fill of the table's first / last column when the table shows them (`TableView.showFirstColumn`
+     * / `showLastColumn` — Excel's Table Design → First Column / Last Column). Every built-in style
+     * emphasises those columns in bold; only the Dark styles add a fill.
+     */
+    firstColumnColor?: Maybe<Color>;
+    lastColumnColor?: Maybe<Color>;
+    /** Excel's `totalRow` style element bolds the totals row. */
+    totalRowBold?: Maybe<boolean>;
 };
 export type BandedDefinition = {
     rowProperties?: Maybe<BandingProperties>;

package/dist/esm/table-styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-styles.d.ts","sourceRoot":"","sources":["../../table-styles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"table-styles.d.ts","sourceRoot":"","sources":["../../table-styles.ts"],"names":[],"mappings":"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"}

package/dist/esm/table-styles.js

@@ -11,7 +11,7 @@ export const getTableBorderStyles = (showRowStripes, showColumnStripes) => {
     let runningLightIndex = 1;
     let runningMediumIndex = 1;
     let runningDarkIndex = 1;
-    return new Map([
+    const styles = new Map([
         [
             "Light",
             [
@@ -285,6 +285,10 @@ export const getTableBorderStyles = (showRowStripes, showColumnStripes) => {
                 ...colorIndexes.map((value) => {
                     const firstTint = value - 1 === 0 ? 0.25 : -0.25;
                     const secondTint = value - 1 === 0 ? 0.5 : 0;
+                    const edgeColumnColor = {
+                        theme: value,
+                        tint: value - 1 === 0 ? 0.15 : -0.5,
+                    };
                     return [
                         ("TableStyleDark" + runningDarkIndex++),
                         firstTint,
@@ -300,6 +304,8 @@ export const getTableBorderStyles = (showRowStripes, showColumnStripes) => {
                                     theme: value,
                                     tint: secondTint,
                                 },
+                                firstColumnColor: edgeColumnColor,
+                                lastColumnColor: edgeColumnColor,
                             },
                             columnProperties: showColumnStripes
                                 ? {
@@ -315,6 +321,10 @@ export const getTableBorderStyles = (showRowStripes, showColumnStripes) => {
                 ...[1, 5, 7, 9].map((value) => {
                     const firstTint = value - 1 === 0 ? -0.35 : 0.6;
                     const secondTint = value - 1 === 0 ? -0.15 : 0.8;
+                    const edgeColumnColor = {
+                        theme: value - 1,
+                        tint: value - 1 === 0 ? -0.5 : 0.4,
+                    };
                     return [
                         ("TableStyleDark" + runningDarkIndex++),
                         firstTint,
@@ -330,6 +340,8 @@ export const getTableBorderStyles = (showRowStripes, showColumnStripes) => {
                                     theme: value - 1,
                                     tint: secondTint,
                                 },
+                                firstColumnColor: edgeColumnColor,
+                                lastColumnColor: edgeColumnColor,
                             },
                             columnProperties: showColumnStripes
                                 ? {
@@ -345,6 +357,27 @@ export const getTableBorderStyles = (showRowStripes, showColumnStripes) => {
             ],
         ],
     ]);
+    // Excel's built-in table styles bold the totals row and rule it with a double top border in
+    // the style's accent colour — the header border's colour, else the header fill's, else the
+    // stripe border's.
+    for (const entries of styles.values()) {
+        for (const [, , , bandDefinition] of entries) {
+            const rows = bandDefinition?.rowProperties;
+            if (!rows)
+                continue;
+            rows.totalRowBold = true;
+            const accent = rows.headerBorder?.top?.color ??
+                rows.headerBorder?.bottom?.color ??
+                rows.headerColor ??
+                rows.firstBandBorder?.bottom?.color;
+            if (accent && !rows.totalRowBorder) {
+                rows.totalRowBorder = {
+                    top: { width: 1, style: "double", color: accent },
+                };
+            }
+        }
+    }
+    return styles;
 };
 /**
  * Find the banded definition for a given table theme

package/dist/esm/table-totals.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Excel's table totals row: the `totalsRowFunction` values a `<tableColumn>` carries
+ * (ECMA-376 `ST_TotalsRowFunction`), the hidden-row-aware `SUBTOTAL` number each one
+ * writes into the totals cell, and the structured-reference formula for it.
+ */
+export declare const TOTALS_ROW_FUNCTIONS: readonly ["none", "average", "count", "countNums", "max", "min", "sum", "stdDev", "var", "custom"];
+export type TotalsRowFunction = (typeof TOTALS_ROW_FUNCTIONS)[number];
+/**
+ * `SUBTOTAL` function numbers of the 101–111 family (ignore rows hidden by a filter),
+ * as Excel writes them into a totals-row cell. `none` and `custom` have none.
+ */
+export declare const TOTALS_ROW_FUNCTION_SUBTOTAL: Readonly<Partial<Record<TotalsRowFunction, number>>>;
+export declare const isTotalsRowFunction: (value: unknown) => value is TotalsRowFunction;
+/**
+ * Escape a column name for use inside a structured reference: `[`, `]`, `#`
+ * and `'` are prefixed with `'`, as Excel does (`Sales[Amount '[est']]`).
+ */
+export declare const escapeStructuredColumnName: (name: string) => string;
+/**
+ * The totals-row formula for `fn` over a table column, qualified with the table
+ * name so it evaluates from any engine and matches what Excel writes:
+ * `=SUBTOTAL(109,Sales[Amount])`. `undefined` for `none` / `custom`.
+ */
+export declare const getTotalsRowFormula: (fn: TotalsRowFunction, tableName: string, columnName: string) => string | undefined;
+/**
+ * Recognise the aggregation a totals-row formula uses. Both the hidden-row-aware
+ * (1xx) and plain (1–11) `SUBTOTAL` numbers map to the same function; anything
+ * else is `none`.
+ */
+export declare const getTotalsRowFunctionFromFormula: (formula: string | null | undefined) => TotalsRowFunction;
+//# sourceMappingURL=table-totals.d.ts.map

package/dist/esm/table-totals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-totals.d.ts","sourceRoot":"","sources":["../../table-totals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,oGAWvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CACjD,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAU3C,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,OAAO,OAAO,KACb,KAAK,IAAI,iBAEiD,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,MAAM,WACnB,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,IAAI,iBAAiB,EACrB,WAAW,MAAM,EACjB,YAAY,MAAM,KACjB,MAAM,GAAG,SAQX,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,GAC1C,SAAS,MAAM,GAAG,IAAI,GAAG,SAAS,KACjC,iBAcF,CAAC"}

package/dist/esm/table-totals.js

@@ -0,0 +1,68 @@
+/**
+ * Excel's table totals row: the `totalsRowFunction` values a `<tableColumn>` carries
+ * (ECMA-376 `ST_TotalsRowFunction`), the hidden-row-aware `SUBTOTAL` number each one
+ * writes into the totals cell, and the structured-reference formula for it.
+ */
+export const TOTALS_ROW_FUNCTIONS = [
+    "none",
+    "average",
+    "count",
+    "countNums",
+    "max",
+    "min",
+    "sum",
+    "stdDev",
+    "var",
+    "custom",
+];
+/**
+ * `SUBTOTAL` function numbers of the 101–111 family (ignore rows hidden by a filter),
+ * as Excel writes them into a totals-row cell. `none` and `custom` have none.
+ */
+export const TOTALS_ROW_FUNCTION_SUBTOTAL = {
+    average: 101,
+    countNums: 102,
+    count: 103,
+    max: 104,
+    min: 105,
+    stdDev: 107,
+    sum: 109,
+    var: 110,
+};
+export const isTotalsRowFunction = (value) => typeof value === "string" &&
+    TOTALS_ROW_FUNCTIONS.includes(value);
+/**
+ * Escape a column name for use inside a structured reference: `[`, `]`, `#`
+ * and `'` are prefixed with `'`, as Excel does (`Sales[Amount '[est']]`).
+ */
+export const escapeStructuredColumnName = (name) => name.replace(/(['\[\]#])/g, "'$1");
+/**
+ * The totals-row formula for `fn` over a table column, qualified with the table
+ * name so it evaluates from any engine and matches what Excel writes:
+ * `=SUBTOTAL(109,Sales[Amount])`. `undefined` for `none` / `custom`.
+ */
+export const getTotalsRowFormula = (fn, tableName, columnName) => {
+    const subtotal = TOTALS_ROW_FUNCTION_SUBTOTAL[fn];
+    if (subtotal === undefined) {
+        return undefined;
+    }
+    return `=SUBTOTAL(${subtotal},${tableName}[${escapeStructuredColumnName(columnName)}])`;
+};
+/**
+ * Recognise the aggregation a totals-row formula uses. Both the hidden-row-aware
+ * (1xx) and plain (1–11) `SUBTOTAL` numbers map to the same function; anything
+ * else is `none`.
+ */
+export const getTotalsRowFunctionFromFormula = (formula) => {
+    if (!formula) {
+        return "none";
+    }
+    const match = /^\s*=\s*SUBTOTAL\s*\(\s*(\d{1,3})\s*,/i.exec(formula);
+    if (!match) {
+        return "none";
+    }
+    const number = Number(match[1]);
+    const normalized = number > 100 ? number - 100 : number;
+    const found = Object.entries(TOTALS_ROW_FUNCTION_SUBTOTAL).find(([, subtotal]) => subtotal - 100 === normalized);
+    return found?.[0] ?? "none";
+};

package/dist/esm/tsconfig.esm.tsbuildinfo

@@ -1 +1 @@
-{"root":["../../array.ts","../../cell-data-helpers.ts","../../color.ts","../../colors.ts","../../conditional-format.ts","../../content-hash.ts","../../data-validation.ts","../../date.ts","../../dom.ts","../../excel-number-format.ts","../../formatter.ts","../../formula-locale.ts","../../formula-refs.ts","../../formula.ts","../../index.ts","../../keyboard.ts","../../locale.ts","../../log.ts","../../memoize.ts","../../numbers.ts","../../selection.ts","../../shared-string-canonical.ts","../../sheet-span.ts","../../sort.ts","../../string.ts","../../table-styles.ts","../../typeguards.ts","../../uuid.ts","../../vitest.config.ts","../../formula-locale/formula-locale-data.generated.ts"],"version":"5.8.3"}
+{"root":["../../array.ts","../../cell-data-helpers.ts","../../color.ts","../../colors.ts","../../conditional-format.ts","../../content-hash.ts","../../data-validation.ts","../../date.ts","../../dom.ts","../../excel-number-format.ts","../../formatter.ts","../../formula-locale.ts","../../formula-refs.ts","../../formula.ts","../../index.ts","../../keyboard.ts","../../locale.ts","../../log.ts","../../memoize.ts","../../numbers.ts","../../selection.ts","../../shared-string-canonical.ts","../../sheet-span.ts","../../sort.ts","../../sparkline-groups.ts","../../string.ts","../../table-names.ts","../../table-styles.ts","../../table-totals.ts","../../typeguards.ts","../../uuid.ts","../../vitest.config.ts","../../formula-locale/formula-locale-data.generated.ts"],"version":"5.8.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowsncolumns/utils",
-  "version": "9.3.0",
+  "version": "9.4.0",
   "author": "Vinay M",
   "license": "SEE LICENSE IN LICENSE.md",
   "main": "./dist/cjs/index.js",
@@ -28,7 +28,9 @@
     "clean": "rimraf dist",
     "build:watch": "tsc -p ./tsconfig.esm.json --watch",
     "test": "vitest --run",
-    "types": "tsc -p . --noEmit"
+    "types": "tsc -p . --noEmit",
+    "types:specs": "node ../../scripts/typecheck-specs.mjs",
+    "types:specs:update": "node ../../scripts/typecheck-specs.mjs --update"
   },
   "files": [
     "dist"
@@ -42,7 +44,7 @@
   },
   "dependencies": {
     "numfmt": "^3.2.2",
-    "@rowsncolumns/common-types": ">=5.2.33"
+    "@rowsncolumns/common-types": ">=5.2.34"
   },
   "devDependencies": {},
   "peerDependencies": {}