@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/conditional-formats.d.ts

@@ -16,7 +16,7 @@
  * Stop If True stops the rules below it for the cells it matches.
  */
 import { type CellValue } from './ast.js';
-import type { StructuralEdit } from './refs.js';
+import { type StructuralEdit } from './refs.js';
 import { type Rect } from './rects.js';
 import type { CellFormatEntry } from './format-store.js';
 export type CfStyle = Pick<CellFormatEntry, 'fill' | 'color' | 'bold' | 'italic' | 'underline' | 'strike' | 'numFmt'>;
@@ -53,9 +53,20 @@ export type CfRule = {
     kind: 'average';
     above: boolean;
     style: CfStyle;
-} | {
+}
+/** Excel's "Use a formula to determine which cells to format": written
+ *  for the rule's top-left cell and moved to each cell, TRUE formats. */
+ | {
+    kind: 'formula';
+    formula: string;
+    style: CfStyle;
+}
+/** `negativeColor` paints the bars left of the axis; without it a range
+ *  with negatives still draws them, in Excel's red. */
+ | {
     kind: 'dataBar';
     color: string;
+    negativeColor?: string;
 } | {
     kind: 'colorScale';
     colors: CfScaleColors;
@@ -75,7 +86,7 @@ export type CfRuleBody = DistributiveOmit<CfRule, 'id' | 'rects'>;
 /** A styled rule without its id and rectangles: what the dialog hands back. */
 export type CfBody = DistributiveOmit<CfStyledRule, 'id' | 'rects'>;
 /** The small dialogs, one per ribbon entry. */
-export type CfPreset = 'greater' | 'less' | 'between' | 'equal' | 'text' | 'duplicates' | 'top10' | 'bottom10' | 'aboveAverage' | 'belowAverage';
+export type CfPreset = 'greater' | 'less' | 'between' | 'equal' | 'text' | 'duplicates' | 'top10' | 'bottom10' | 'aboveAverage' | 'belowAverage' | 'formula';
 /** What one rule knows about the numbers in its rectangles. */
 export type CfStats = {
     /** Numbers, sorted ascending. */
@@ -89,10 +100,16 @@ export type CfStats = {
 /** What the rules say about one cell. */
 export type CfResult = {
     style?: CfStyle;
-    /** A bar across the cell, 0..1 of its width. */
+    /**
+     * A bar across the cell: `ratio` of its width, starting `axis` of the
+     * way across (0 when the range has no negatives) and running right for a
+     * positive value, left for a negative one, which `negative` says.
+     */
     dataBar?: {
         ratio: number;
         color: string;
+        axis: number;
+        negative: boolean;
     };
     /** The icon set and which of its three icons: 0 = the top one. */
     icon?: {
@@ -102,8 +119,12 @@ export type CfResult = {
 };
 /** How a rule reads the sheet: the shell wires the workbook in. */
 export type CfContext = {
-    /** A formula or a literal, evaluated in the sheet. */
-    evaluate(text: string): CellValue;
+    /** A formula or a literal, evaluated in the sheet; `at` is the cell a
+     *  formula rule is being read for, so ROW() and COLUMN() work in it. */
+    evaluate(text: string, at?: {
+        row: number;
+        col: number;
+    }): CellValue;
 };
 /** The six "with" styles of Excel's Highlight Cells dialogs. */
 export declare const CF_PRESET_STYLES: ReadonlyArray<{
@@ -112,6 +133,8 @@ export declare const CF_PRESET_STYLES: ReadonlyArray<{
     style: CfStyle;
 }>;
 export declare const DATA_BAR_COLOR = "#638EC6";
+/** Excel's colour for the bars left of the axis. */
+export declare const DATA_BAR_NEGATIVE_COLOR = "#FF0000";
 export declare const COLOR_SCALES: Record<'green-yellow-red' | 'red-yellow-green' | 'green-white' | 'white-red', CfScaleColors>;
 export declare function cfId(): string;
 /**

package/dist/sheet/conditional-formats.js

@@ -17,6 +17,7 @@
  */
 import { isError } from './ast.js';
 import { toText } from './coerce.js';
+import { translateFormula } from './refs.js';
 import { rectContains, shiftRects, subtractRect, rectsIntersect } from './rects.js';
 // ---------------------------------------------------------------------------
 // Excel's palettes
@@ -30,6 +31,8 @@ export const CF_PRESET_STYLES = [
     { id: 'red-text', label: 'Red Text', style: { color: '#9C0006' } },
 ];
 export const DATA_BAR_COLOR = '#638EC6';
+/** Excel's colour for the bars left of the axis. */
+export const DATA_BAR_NEGATIVE_COLOR = '#FF0000';
 export const COLOR_SCALES = {
     'green-yellow-red': ['#63BE7B', '#FFEB84', '#F8696B'],
     'red-yellow-green': ['#F8696B', '#FFEB84', '#63BE7B'],
@@ -109,7 +112,7 @@ function cellIs(value, operator, a, b) {
     }
 }
 /** Whether a styling rule matches the cell. */
-function matches(rule, value, display, stats, ctx) {
+function matches(rule, value, display, stats, ctx, at) {
     switch (rule.kind) {
         case 'cellIs': {
             const isEquality = rule.operator === 'equal' || rule.operator === 'notEqual';
@@ -166,22 +169,43 @@ function matches(rule, value, display, stats, ctx) {
                 return false;
             return rule.above ? value > stats.mean : value < stats.mean;
         }
+        case 'formula': {
+            // Written for the rule's top-left cell and moved to the cell being
+            // painted, as a copied formula would be: =$B2>100 on A2:A9 reads
+            // each row's B. TRUE, or a number other than 0, formats.
+            const text = rule.formula.trim();
+            if (!text)
+                return false;
+            const origin = rule.rects[0];
+            const source = text.startsWith('=') ? text : `=${text}`;
+            const moved = origin && at ? String(translateFormula(source, at.row - origin[0], at.col - origin[1])) : source;
+            const v = ctx.evaluate(moved, at);
+            if (isError(v))
+                return false;
+            return typeof v === 'boolean' ? v : typeof v === 'number' ? v !== 0 : false;
+        }
         default:
             return false;
     }
 }
 /**
- * A data bar's share of the cell, 0..1. Excel measures from zero when the
- * range is non-negative (10, 20, 40 draw a quarter, a half and the whole
- * width), so the smallest value keeps a bar; a range with negatives runs
- * from its minimum instead, since there is no negative axis here.
+ * A data bar's geometry. Excel measures from zero: over a non-negative
+ * range 10, 20, 40 draw a quarter, a half and the whole width, so the
+ * smallest value keeps a bar. A range with negatives puts an axis where
+ * zero falls between the minimum and the maximum, and a bar grows away
+ * from it, right for a positive value and left for a negative one, each
+ * as its share of the whole span, as Excel's automatic axis draws them.
  */
-function barRatio(value, stats) {
+function dataBarFor(value, stats) {
     const lo = Math.min(0, stats.min);
     const hi = Math.max(0, stats.max);
-    if (hi === lo)
-        return 0;
-    return Math.min(1, Math.max(0, (value - lo) / (hi - lo)));
+    const span = hi - lo;
+    const negative = value < 0;
+    if (span === 0)
+        return { ratio: 0, axis: 0, negative };
+    const axis = lo < 0 ? -lo / span : 0;
+    const ratio = Math.min(1, Math.abs(value) / span);
+    return { ratio, axis, negative };
 }
 /** Where a number sits in a range, 0..1; 0.5 for a flat range. */
 function ratioOf(value, stats) {
@@ -229,8 +253,8 @@ export function evaluateCf(rules, r, c, value, display, statsFor, ctx) {
         let hit = false;
         if (rule.kind === 'dataBar') {
             if (typeof value === 'number' && !(out?.dataBar)) {
-                const stats = statsFor(rule);
-                out = { ...(out ?? {}), dataBar: { ratio: barRatio(value, stats), color: rule.color } };
+                const bar = dataBarFor(value, statsFor(rule));
+                out = { ...(out ?? {}), dataBar: { ...bar, color: bar.negative ? rule.negativeColor ?? DATA_BAR_NEGATIVE_COLOR : rule.color } };
                 hit = true;
             }
         }
@@ -249,7 +273,7 @@ export function evaluateCf(rules, r, c, value, display, statsFor, ctx) {
                 hit = true;
             }
         }
-        else if (hasStyle(rule) && matches(rule, value, display, statsFor(rule), ctx)) {
+        else if (hasStyle(rule) && matches(rule, value, display, statsFor(rule), ctx, { row: r, col: c })) {
             const style = { ...(out?.style ?? {}) };
             const own = rule.style;
             for (const key of Object.keys(own)) {
@@ -305,6 +329,7 @@ export function describeCf(rule) {
         case 'duplicates': return rule.unique ? 'Unique Values' : 'Duplicate Values';
         case 'topBottom': return `${rule.top ? 'Top' : 'Bottom'} ${rule.rank}${rule.percent ? '%' : ''}`;
         case 'average': return rule.above ? 'Above Average' : 'Below Average';
+        case 'formula': return `Formula: ${rule.formula}`;
         case 'dataBar': return 'Data Bar';
         case 'colorScale': return rule.colors.length === 3 ? 'Graded Color Scale' : 'Two-Color Scale';
         case 'iconSet': return 'Icon Set';

package/dist/sheet/csv.d.ts

@@ -0,0 +1,32 @@
+import type { SheetState } from './document.js';
+/**
+ * A sheet as CSV, the way Excel's Save As CSV writes one: what the cells
+ * SHOW, so a formula goes out as its value and a formatted number as its
+ * text; a field with a comma, a quote or a line break in quotes, a quote
+ * doubled; CRLF between rows; trailing empty cells kept so every row has
+ * the sheet's width.
+ */
+export declare function csvText(rows: ReadonlyArray<ReadonlyArray<string>>, separator?: string): string;
+/**
+ * CSV text back into rows.
+ *
+ * A scan, not a split: a quoted field may hold the separator, a line break
+ * or a doubled quote, and every real export uses all three. CRLF and LF both
+ * end a row, a BOM at the start is dropped (Excel writes one), and the
+ * separator is guessed when it is not given, so a semicolon file from a
+ * European Excel and a tab file pasted from anywhere read as themselves.
+ */
+export declare function csvRows(text: string, separator?: string): string[][];
+/** The separator a file uses: the one that divides its first lines evenly. */
+export declare function guessCsvSeparator(text: string): string;
+/**
+ * A CSV (or TSV) file as a one-sheet document.
+ *
+ * Every spreadsheet exports CSV and every one of them reads it back the same
+ * way: a field that looks like a number IS a number, and one that looks like
+ * a percentage, a currency amount or a grouped number keeps the format it
+ * implies, which is what `parseEntry` decides for typing. A field is never
+ * read as a formula - a CSV holding `=1+1` is text in Excel too, since the
+ * file came from somewhere else.
+ */
+export declare function sheetStateFromCsv(text: string, sheetName?: string, separator?: string): SheetState;

package/dist/sheet/csv.js

@@ -0,0 +1,158 @@
+import { parseEntry } from './entry.js';
+import { formatKeyAt } from './format-store.js';
+/**
+ * A sheet as CSV, the way Excel's Save As CSV writes one: what the cells
+ * SHOW, so a formula goes out as its value and a formatted number as its
+ * text; a field with a comma, a quote or a line break in quotes, a quote
+ * doubled; CRLF between rows; trailing empty cells kept so every row has
+ * the sheet's width.
+ */
+export function csvText(rows, separator = ',') {
+    const width = rows.reduce((max, row) => Math.max(max, row.length), 0);
+    const field = (text) => /[",\r\n]/.test(text) || text.includes(separator) ? `"${text.replace(/"/g, '""')}"` : text;
+    return rows
+        .map((row) => Array.from({ length: width }, (_, i) => field(row[i] ?? '')).join(separator))
+        .join('\r\n');
+}
+/**
+ * CSV text back into rows.
+ *
+ * A scan, not a split: a quoted field may hold the separator, a line break
+ * or a doubled quote, and every real export uses all three. CRLF and LF both
+ * end a row, a BOM at the start is dropped (Excel writes one), and the
+ * separator is guessed when it is not given, so a semicolon file from a
+ * European Excel and a tab file pasted from anywhere read as themselves.
+ */
+export function csvRows(text, separator) {
+    const body = text.replace(/^/, '');
+    if (body === '')
+        return [];
+    const sep = separator ?? guessCsvSeparator(body);
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    let i = 0;
+    const endField = () => { row.push(field); field = ''; };
+    const endRow = () => { endField(); rows.push(row); row = []; };
+    while (i < body.length) {
+        const ch = body[i];
+        if (quoted) {
+            if (ch === '"') {
+                if (body[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                quoted = false;
+                i += 1;
+                continue;
+            }
+            field += ch;
+            i += 1;
+            continue;
+        }
+        if (ch === '"' && field === '') {
+            quoted = true;
+            i += 1;
+            continue;
+        }
+        if (body.startsWith(sep, i)) {
+            endField();
+            i += sep.length;
+            continue;
+        }
+        if (ch === '\r') {
+            if (body[i + 1] === '\n')
+                i += 1;
+            endRow();
+            i += 1;
+            continue;
+        }
+        if (ch === '\n') {
+            endRow();
+            i += 1;
+            continue;
+        }
+        field += ch;
+        i += 1;
+    }
+    if (field !== '' || row.length)
+        endRow();
+    return rows;
+}
+/** The separator a file uses: the one that divides its first lines evenly. */
+export function guessCsvSeparator(text) {
+    const lines = text.split(/\r?\n/).filter((line) => line !== '').slice(0, 20);
+    if (!lines.length)
+        return ',';
+    let best = null;
+    for (const sep of [',', ';', '\t', '|']) {
+        // Count outside quotes: a comma inside "Smith, John" divides nothing.
+        const counts = lines.map((line) => {
+            let n = 0;
+            let quoted = false;
+            for (let i = 0; i < line.length; i += 1) {
+                const ch = line[i];
+                if (ch === '"') {
+                    quoted = !quoted;
+                    continue;
+                }
+                if (!quoted && line.startsWith(sep, i))
+                    n += 1;
+            }
+            return n;
+        });
+        const present = counts.filter((n) => n > 0).length;
+        if (!present)
+            continue;
+        const first = counts.find((n) => n > 0) ?? 0;
+        const even = counts.every((n) => n === 0 || n === first);
+        const score = present * (even ? 3 : 1) + first;
+        if (!best || score > best.score)
+            best = { sep, score };
+    }
+    return best?.sep ?? ',';
+}
+/**
+ * A CSV (or TSV) file as a one-sheet document.
+ *
+ * Every spreadsheet exports CSV and every one of them reads it back the same
+ * way: a field that looks like a number IS a number, and one that looks like
+ * a percentage, a currency amount or a grouped number keeps the format it
+ * implies, which is what `parseEntry` decides for typing. A field is never
+ * read as a formula - a CSV holding `=1+1` is text in Excel too, since the
+ * file came from somewhere else.
+ */
+export function sheetStateFromCsv(text, sheetName = 'Sheet1', separator) {
+    const rows = csvRows(text, separator);
+    const cells = [];
+    const formats = {};
+    rows.forEach((row, r) => {
+        const line = [];
+        row.forEach((field, c) => {
+            const parsed = field === '' ? null : parseEntry(field);
+            if (parsed) {
+                line.push(parsed.value);
+                if (parsed.numFmt)
+                    formats[formatKeyAt(r, c)] = { numFmt: parsed.numFmt };
+                return;
+            }
+            // A leading = would be read as a formula by the workbook, and this
+            // text was never one: Excel's own CSV import keeps it as it reads.
+            line.push(field.startsWith('=') ? `'${field}` : field);
+        });
+        cells.push(line);
+    });
+    return {
+        version: 1,
+        workbook: { sheets: [{ name: sheetName, cells }], active: sheetName, names: {} },
+        sheets: {
+            [sheetName]: {
+                formats, columnWidths: {}, rowHeights: [], hidden: { rows: [], cols: [] },
+                freeze: { rows: 0, cols: 0 }, comments: {}, protected: false,
+                merges: [], validation: [], conditionalFormats: [], autoFilter: null,
+            },
+        },
+    };
+}

package/dist/sheet/culture.d.ts

@@ -0,0 +1,87 @@
+/**
+ * How a locale spells a number, a date and a formula.
+ *
+ * The rule this module exists to enforce: **the workbook stores the
+ * invariant spelling, always.** A formula in the document is
+ * `=SUM(1.5, A1)` whatever the user's locale, and a number is `1234.5`.
+ * The culture is a layer over the top, applied when a formula is shown for
+ * editing and un-applied when one is typed.
+ *
+ * That is what Excel does, and it is the only arrangement where a file
+ * written in Berlin opens in Boston. Storing `=SUMME(1,5;A1)` would make
+ * the document's meaning depend on who saved it, and every reader, writer
+ * and test would have to carry the locale to make sense of a cell.
+ *
+ * What a culture changes:
+ *   - the decimal mark and the group mark, `1.234,5` against `1,234.5`
+ *   - the argument separator, which Excel makes `;` wherever the decimal
+ *     mark is `,`, since `,` is then busy
+ *   - the order of a slash date, `31/12` against `12/31`
+ *
+ * What it does NOT change: function names, which stay English here, and
+ * the spelling in the file, which stays invariant.
+ */
+export type SheetCulture = {
+    /** The locale this was derived from, for the number formatter. */
+    locale: string;
+    /** The decimal mark, `.` or `,`. */
+    decimal: string;
+    /** The group mark, which may be a non-breaking space. */
+    group: string;
+    /** What separates a function's arguments: `,`, or `;` where `,` is the
+     *  decimal mark. */
+    argSeparator: string;
+    /** How a slash date reads: day first, month first, or year first. */
+    dateOrder: 'dmy' | 'mdy' | 'ymd';
+};
+export declare const SPACE_GROUP_MARKS: ReadonlyArray<string>;
+/** The spelling the document itself uses, and the default. */
+export declare const INVARIANT_CULTURE: SheetCulture;
+/**
+ * The culture a locale implies, read off `Intl` rather than a table, so a
+ * locale nobody thought of still comes out right.
+ *
+ * Falls back to the invariant culture where `Intl` is missing or the
+ * locale is not one it knows, since a sheet that renders in the wrong
+ * separators is better than one that does not render.
+ */
+export declare function cultureFromLocale(locale: string): SheetCulture;
+/** True where the culture spells everything the way the document does. */
+export declare const isInvariant: (c: SheetCulture) => boolean;
+/**
+ * A stored formula as the user's locale spells it, for the formula bar.
+ *
+ * `=SUM(1.5, A1)` becomes `=SUM(1,5; A1)` in a German sheet.
+ */
+export declare function formulaToCulture(formula: string, culture: SheetCulture): string;
+/**
+ * A typed formula back to the spelling the document stores.
+ *
+ * The inverse of `formulaToCulture`, with one deliberate kindness: where
+ * the culture's separator is `;`, a `,` between arguments is taken as a
+ * separator too, so a user with an English keyboard habit is not stopped.
+ * A `,` that sits between digits is still the decimal mark, so nothing
+ * ambiguous is guessed at.
+ */
+export declare function formulaFromCulture(formula: string, culture: SheetCulture): string;
+/**
+ * A number as the culture writes it, back to a plain number.
+ *
+ * Returns null when the text is not a number in this culture, so the
+ * caller can fall through to treating it as text. The group mark is
+ * dropped wherever it appears rather than checked for position, as Excel
+ * does: `1.2.3,4` is not worth refusing on a technicality.
+ */
+export declare function parseNumberInCulture(text: string, culture: SheetCulture): number | null;
+/** A number as the culture writes it, for display. */
+export declare function formatNumberInCulture(value: number, culture: SheetCulture): string;
+/**
+ * The day, month and year a slash date names, in this culture's order.
+ *
+ * Returns null when the pieces cannot be a date, which is what tells a
+ * slash date apart from a fraction typed without a whole part.
+ */
+export declare function slashDateParts(a: number, b: number, culture: SheetCulture): {
+    month: number;
+    day: number;
+} | null;