@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/number-format.js

@@ -0,0 +1,508 @@
+/**
+ * Excel number-format strings, compiled once and applied many times.
+ *
+ * The grammar is small but full of traps, so this file is explicit about the
+ * ones that bite:
+ *
+ *   - A pattern has up to four sections separated by `;`:
+ *     positive;negative;zero;text. With two, the second covers negatives AND
+ *     zero. With one, it covers everything. A negative rendered by section two
+ *     uses its ABSOLUTE value, which is why `0.00;(0.00)` shows `(1.50)` and
+ *     not `(-1.50)`.
+ *   - `,` means two different things. Between placeholders it is a thousands
+ *     separator; immediately before the decimal point (or at the end) it scales
+ *     the number down by a thousand per comma.
+ *   - `%` scales UP by 100 and prints a literal percent.
+ *   - `0` prints a digit or a zero, `#` prints a digit or nothing, `?` prints a
+ *     digit or a space. They can be mixed: `#,##0.0#` keeps one decimal always
+ *     and a second only when it is there.
+ *   - Anything in quotes, after a backslash, or in the set of always-literal
+ *     characters is emitted as-is.
+ *   - `[Red]` and friends set a colour rather than printing.
+ *   - `@` is the text placeholder and only appears in the fourth section.
+ *
+ * Dates are detected rather than configured: a pattern containing date tokens
+ * outside quotes is a date pattern. `m` is minutes when it follows an hour
+ * token and months otherwise, which is the one piece of context the token
+ * scanner has to carry.
+ */
+const COLORS = {
+    BLACK: '#000000', BLUE: '#0000ff', CYAN: '#00ffff', GREEN: '#008000',
+    MAGENTA: '#ff00ff', RED: '#ff0000', WHITE: '#ffffff', YELLOW: '#ffff00',
+};
+/** Split on `;` at the top level, ignoring separators inside quotes, brackets
+ *  or escapes. A naive `pattern.split(';')` breaks `"a;b"` and `[<100]`. */
+function splitSections(pattern) {
+    const out = [];
+    let current = '';
+    let inQuote = false;
+    let inBracket = false;
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === '\\') {
+            current += ch + (pattern[i + 1] ?? '');
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inQuote = !inQuote;
+            current += ch;
+            continue;
+        }
+        if (!inQuote && ch === '[') {
+            inBracket = true;
+            current += ch;
+            continue;
+        }
+        if (!inQuote && ch === ']') {
+            inBracket = false;
+            current += ch;
+            continue;
+        }
+        if (ch === ';' && !inQuote && !inBracket) {
+            out.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    out.push(current);
+    return out;
+}
+function parseSection(raw) {
+    let color;
+    let body = '';
+    // Walk rather than regex-replace: a pattern like `"[" @ "]"` has brackets
+    // INSIDE quoted literals, and a global /\[[^\]]*\]/ happily eats the text
+    // between them.
+    for (let i = 0; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (ch === '\\') {
+            body += ch + (raw[i + 1] ?? '');
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            const end = raw.indexOf('"', i + 1);
+            const stop = end < 0 ? raw.length : end;
+            body += raw.slice(i, stop + 1);
+            i = stop;
+            continue;
+        }
+        if (ch === '[') {
+            const end = raw.indexOf(']', i + 1);
+            if (end < 0) {
+                body += ch;
+                continue;
+            }
+            const inner = raw.slice(i + 1, end).trim().toUpperCase();
+            const named = COLORS[inner];
+            if (named)
+                color = named;
+            // Anything else (a condition like [<100]) is unsupported: drop it rather
+            // than print it.
+            i = end;
+            continue;
+        }
+        body += ch;
+    }
+    return { raw, color, body };
+}
+const DATE_TOKEN = /^(yyyy|yy|mmmm|mmm|mm|m|dddd|ddd|dd|d|hh|h|ss|s|AM\/PM|am\/pm|A\/P)/;
+/** Does this section describe a date? Scans outside quotes and escapes. */
+function looksLikeDate(body) {
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (ch === '\\') {
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            const end = body.indexOf('"', i + 1);
+            i = end < 0 ? body.length : end;
+            continue;
+        }
+        if (DATE_TOKEN.test(body.slice(i))) {
+            // `m` alone is ambiguous with the thousands/number grammar only in
+            // theory: a numeric pattern never contains a bare letter outside quotes.
+            return true;
+        }
+    }
+    return false;
+}
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December'];
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const pad2 = (n) => String(n).padStart(2, '0');
+function toDate(value) {
+    if (value instanceof Date)
+        return value;
+    if (typeof value === 'number') {
+        // Excel serial day, with the usual 1899-12-30 epoch. That is correct for
+        // every date from 1900-03-01 on, which is every date anyone stores. Excel
+        // itself is a day out below serial 61 because it counts a 1900-02-29 that
+        // never existed; matching that bug exactly would break real dates.
+        return new Date(Date.UTC(1899, 11, 30) + value * 86400000);
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+function renderDate(body, date) {
+    let out = '';
+    let sawHour = false;
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (ch === '\\') {
+            out += body[i + 1] ?? '';
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            const end = body.indexOf('"', i + 1);
+            out += body.slice(i + 1, end < 0 ? body.length : end);
+            i = end < 0 ? body.length : end;
+            continue;
+        }
+        const m = DATE_TOKEN.exec(body.slice(i));
+        if (!m) {
+            out += ch;
+            continue;
+        }
+        const token = m[1];
+        i += token.length - 1;
+        switch (token) {
+            case 'yyyy':
+                out += date.getUTCFullYear();
+                break;
+            case 'yy':
+                out += pad2(date.getUTCFullYear() % 100);
+                break;
+            case 'mmmm':
+                out += MONTHS[date.getUTCMonth()];
+                break;
+            case 'mmm':
+                out += MONTHS[date.getUTCMonth()].slice(0, 3);
+                break;
+            case 'dddd':
+                out += DAYS[date.getUTCDay()];
+                break;
+            case 'ddd':
+                out += DAYS[date.getUTCDay()].slice(0, 3);
+                break;
+            case 'dd':
+                out += pad2(date.getUTCDate());
+                break;
+            case 'd':
+                out += date.getUTCDate();
+                break;
+            case 'hh':
+                out += pad2(date.getUTCHours());
+                sawHour = true;
+                break;
+            case 'h':
+                out += date.getUTCHours();
+                sawHour = true;
+                break;
+            case 'ss':
+                out += pad2(date.getUTCSeconds());
+                break;
+            case 's':
+                out += date.getUTCSeconds();
+                break;
+            case 'AM/PM':
+            case 'am/pm':
+            case 'A/P':
+                out += date.getUTCHours() < 12 ? 'AM' : 'PM';
+                break;
+            // `m` and `mm` are MINUTES after an hour token, MONTHS otherwise. This
+            // is the one piece of context the scanner carries, and getting it wrong
+            // turns 09:05 into 09:09.
+            case 'mm':
+                out += sawHour ? pad2(date.getUTCMinutes()) : pad2(date.getUTCMonth() + 1);
+                break;
+            case 'm':
+                out += sawHour ? date.getUTCMinutes() : date.getUTCMonth() + 1;
+                break;
+            default: out += token;
+        }
+    }
+    return out;
+}
+/** Pull a numeric section apart into literal text and digit placeholders. */
+function planNumeric(body) {
+    let prefix = '';
+    let suffix = '';
+    let intPlaceholders = '';
+    let fracPlaceholders = '';
+    let useGrouping = false;
+    let percent = false;
+    let scientific = false;
+    let expPlaceholders = '';
+    let scale = 1;
+    let seenPlaceholder = false;
+    let afterDecimal = false;
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (ch === '\\') {
+            const next = body[i + 1] ?? '';
+            if (seenPlaceholder)
+                suffix += next;
+            else
+                prefix += next;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            const end = body.indexOf('"', i + 1);
+            const text = body.slice(i + 1, end < 0 ? body.length : end);
+            if (seenPlaceholder)
+                suffix += text;
+            else
+                prefix += text;
+            i = end < 0 ? body.length : end;
+            continue;
+        }
+        if (ch === '0' || ch === '#' || ch === '?') {
+            seenPlaceholder = true;
+            // After an E+ the placeholders size the EXPONENT, not the mantissa.
+            // Counting them as decimals turns 0.00E+00 into four decimal places.
+            if (scientific)
+                expPlaceholders += ch;
+            else if (afterDecimal)
+                fracPlaceholders += ch;
+            else
+                intPlaceholders += ch;
+            continue;
+        }
+        if (ch === '.') {
+            afterDecimal = true;
+            seenPlaceholder = true;
+            continue;
+        }
+        if (ch === ',') {
+            // A comma between placeholders groups; one trailing (before the decimal
+            // point or at the end of the pattern) scales by a thousand.
+            const rest = body.slice(i + 1);
+            if (/^[0#?]/.test(rest))
+                useGrouping = true;
+            else
+                scale *= 1000;
+            continue;
+        }
+        if (ch === '%') {
+            percent = true;
+            if (seenPlaceholder)
+                suffix += '%';
+            else
+                prefix += '%';
+            continue;
+        }
+        if ((ch === 'E' || ch === 'e') && /^[+-]/.test(body.slice(i + 1))) {
+            scientific = true;
+            i += 1;
+            continue;
+        }
+        if (seenPlaceholder)
+            suffix += ch;
+        else
+            prefix += ch;
+    }
+    return {
+        prefix, suffix, intPlaceholders, fracPlaceholders, expPlaceholders,
+        useGrouping, scale, percent, scientific,
+    };
+}
+function group(intText) {
+    return intText.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+function renderNumeric(plan, value) {
+    let n = value;
+    if (plan.percent)
+        n *= 100;
+    if (plan.scale !== 1)
+        n /= plan.scale;
+    if (plan.scientific) {
+        const text = n.toExponential(plan.fracPlaceholders.length);
+        // toExponential gives "1.23e+4"; Excel writes the exponent with at least
+        // as many digits as the pattern asked for.
+        const [mantissa = '', exponent = ''] = text.split('e');
+        const sign = exponent.startsWith('-') ? '-' : '+';
+        const digits = exponent.replace(/^[+-]/, '').padStart(plan.expPlaceholders.length || 1, '0');
+        return `${plan.prefix}${mantissa}E${sign}${digits}${plan.suffix}`;
+    }
+    const decimals = plan.fracPlaceholders.length;
+    const fixed = Math.abs(n).toFixed(decimals);
+    const [rawInt = '0', rawFrac = ''] = fixed.split('.');
+    // Pad the integer side out to the number of `0` placeholders, and drop a
+    // leading zero entirely when the pattern is all `#`.
+    const minInt = plan.intPlaceholders.split('').filter((c) => c === '0').length;
+    let intText = rawInt;
+    if (intText.length < minInt)
+        intText = intText.padStart(minInt, '0');
+    if (minInt === 0 && intText === '0' && plan.intPlaceholders.length > 0)
+        intText = '';
+    if (plan.useGrouping && intText !== '')
+        intText = group(intText);
+    // Trim optional decimals from the right: `0.0#` on 1.5 gives "1.5", not
+    // "1.50". A `0` placeholder is never trimmed, a `#` always may be, and a
+    // `?` becomes a space so columns line up.
+    let fracText = rawFrac;
+    for (let i = plan.fracPlaceholders.length - 1; i >= 0; i -= 1) {
+        const kind = plan.fracPlaceholders[i];
+        if (kind === '0')
+            break;
+        if (fracText[i] !== '0')
+            break;
+        fracText = kind === '?' ? `${fracText.slice(0, i)} ` : fracText.slice(0, i);
+    }
+    const body = fracText === '' ? intText : `${intText}.${fracText}`;
+    // `#` on zero prints nothing, which is how "hide zeros" patterns work. The
+    // fallback below is only for a pattern with no digit placeholders at all.
+    return plan.prefix + body + plan.suffix;
+}
+/** A section with no digit placeholders is pure literal text: `"-"` as the
+ *  zero section must print `-`, not `-0`. */
+function hasPlaceholders(plan) {
+    return plan.intPlaceholders !== '' || plan.fracPlaceholders !== '';
+}
+/** Excel's General: up to 11 significant digits, no trailing zeros. */
+function general(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            return String(value);
+        if (Number.isInteger(value))
+            return String(value);
+        return String(Number(value.toPrecision(11)));
+    }
+    if (typeof value === 'boolean')
+        return value ? 'TRUE' : 'FALSE';
+    return value === null || value === undefined ? '' : String(value);
+}
+/**
+ * Compile a format string. Compilation is cached per pattern, so a column of
+ * ten thousand cells sharing one format parses it once.
+ */
+const cache = new Map();
+export function compileNumberFormat(pattern) {
+    const hit = cache.get(pattern);
+    if (hit)
+        return hit;
+    const sections = splitSections(pattern).map(parseSection);
+    const positive = sections[0];
+    const negative = sections[1];
+    const zero = sections[2];
+    const text = sections[3];
+    // Plans are built once here, not per value.
+    const plans = new Map();
+    const dateFlags = new Map();
+    for (const s of sections) {
+        if (!s)
+            continue;
+        const isDate = looksLikeDate(s.body);
+        dateFlags.set(s, isDate);
+        if (!isDate)
+            plans.set(s, planNumeric(s.body));
+    }
+    const compiled = {
+        pattern,
+        format(value) {
+            if (pattern.trim() === '' || pattern.toUpperCase() === 'GENERAL') {
+                return { text: general(value) };
+            }
+            if (typeof value === 'string' && value !== '') {
+                const section = text ?? positive;
+                if (!section)
+                    return { text: value };
+                // The text section substitutes @ for the value; without an @ the
+                // section's literal text is all you get.
+                const body = section.body.includes('@')
+                    ? section.body.replace(/@/g, value).replace(/"/g, '')
+                    : value;
+                return { text: body, color: section.color };
+            }
+            if (value === null || value === undefined || value === '')
+                return { text: '' };
+            if (typeof value === 'boolean')
+                return { text: value ? 'TRUE' : 'FALSE' };
+            const n = typeof value === 'number' ? value : Number(value);
+            if (!Number.isFinite(n)) {
+                const d = toDate(value);
+                if (d && positive && dateFlags.get(positive)) {
+                    return { text: renderDate(positive.body, d), color: positive.color };
+                }
+                return { text: String(value) };
+            }
+            // Pick the section. Two sections means the second covers zero too.
+            let section = positive;
+            if (n < 0 && negative)
+                section = negative;
+            else if (n === 0 && zero)
+                section = zero;
+            if (!section)
+                return { text: general(value) };
+            if (dateFlags.get(section)) {
+                const d = toDate(value);
+                return d
+                    ? { text: renderDate(section.body, d), color: section.color }
+                    : { text: general(value) };
+            }
+            const plan = plans.get(section);
+            if (!hasPlaceholders(plan)) {
+                return { text: plan.prefix + plan.suffix, color: section.color };
+            }
+            // A negative shown by its own section renders its ABSOLUTE value: the
+            // section supplies the sign, usually as parentheses or a literal minus.
+            const usingNegativeSection = n < 0 && section === negative;
+            const magnitude = usingNegativeSection ? Math.abs(n) : n;
+            let out = renderNumeric(plan, magnitude);
+            // With no negative section, put the sign back on.
+            if (n < 0 && !usingNegativeSection && !out.startsWith('-'))
+                out = `-${out}`;
+            return { text: out, color: section.color };
+        },
+    };
+    cache.set(pattern, compiled);
+    return compiled;
+}
+/** Format one value against a pattern. Convenience over compile-then-call. */
+export function formatWithPattern(value, pattern) {
+    return compileNumberFormat(pattern).format(value).text;
+}
+/** The presets behind Ctrl+Shift+1 through 6. */
+export const FORMAT_PRESETS = {
+    general: 'General',
+    number: '#,##0.00',
+    time: 'h:mm AM/PM',
+    date: 'yyyy-mm-dd',
+    currency: '$#,##0.00;($#,##0.00)',
+    percent: '0.00%',
+    scientific: '0.00E+00',
+};
+/**
+ * Which of Excel's categories a pattern belongs to, with the decimals and
+ * separator it carries, so the ribbon's combo can say "Percentage" for a
+ * cell holding `0%` (a typed 12%) as well as for the preset's `0.00%`, and
+ * Format Cells can open on the right category. A pattern that is none of
+ * them is 'custom'.
+ */
+export function formatCategory(fmt) {
+    if (!fmt || fmt === 'General')
+        return { category: 'general', decimals: 2, thousands: true };
+    const decimals = fmt.match(/\.(0+)/)?.[1]?.length ?? 0;
+    if (/E\+/i.test(fmt))
+        return { category: 'scientific', decimals, thousands: false };
+    if (/%$/.test(fmt))
+        return { category: 'percent', decimals, thousands: false };
+    if (/^\$/.test(fmt))
+        return { category: 'currency', decimals, thousands: true };
+    if (/[hs]:|AM\/PM/i.test(fmt))
+        return { category: 'time', decimals: 0, thousands: false };
+    if (/y|d/i.test(fmt) && !/[#0]/.test(fmt))
+        return { category: 'date', decimals: 0, thousands: false };
+    if (/^#?,?#*0(\.0+)?$/.test(fmt))
+        return { category: 'number', decimals, thousands: fmt.includes(',') };
+    return { category: 'custom', decimals, thousands: false };
+}

package/dist/sheet/palette.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Excel's colour picker, as data: the ten theme colours with five tints and
+ * shades each, then the ten standard colours. These are the values a
+ * spreadsheet user expects to find under Fill Colour and Font Colour, and
+ * they are cell DATA (a fill the document carries) rather than chrome, which
+ * is why they are literal hex here and not theme tokens.
+ */
+export type PaletteColour = {
+    value: string;
+    label: string;
+};
+export declare const STANDARD_COLOURS: ReadonlyArray<PaletteColour>;
+/** Mix `hex` toward white (`amount` > 0) or black (`amount` < 0). */
+export declare function tint(hex: string, amount: number): string;
+export type PaletteRow = ReadonlyArray<PaletteColour>;
+/** Ten columns by six rows: the base row, then five variations per column. */
+export declare const THEME_COLOURS: ReadonlyArray<PaletteRow>;
+/** The whole picker flattened, for a `select` fallback and for tests. */
+export declare const ALL_COLOURS: ReadonlyArray<PaletteColour>;

package/dist/sheet/palette.js

@@ -0,0 +1,84 @@
+/**
+ * Excel's colour picker, as data: the ten theme colours with five tints and
+ * shades each, then the ten standard colours. These are the values a
+ * spreadsheet user expects to find under Fill Colour and Font Colour, and
+ * they are cell DATA (a fill the document carries) rather than chrome, which
+ * is why they are literal hex here and not theme tokens.
+ */
+/** The Office theme's base row: white, black, two greys, then six accents. */
+const THEME_BASE = [
+    { value: '#FFFFFF', label: 'White, Background 1' },
+    { value: '#000000', label: 'Black, Text 1' },
+    { value: '#E7E6E6', label: 'Light Gray, Background 2' },
+    { value: '#44546A', label: 'Blue-Gray, Text 2' },
+    { value: '#4472C4', label: 'Blue, Accent 1' },
+    { value: '#ED7D31', label: 'Orange, Accent 2' },
+    { value: '#A5A5A5', label: 'Gray, Accent 3' },
+    { value: '#FFC000', label: 'Gold, Accent 4' },
+    { value: '#5B9BD5', label: 'Blue, Accent 5' },
+    { value: '#70AD47', label: 'Green, Accent 6' },
+];
+export const STANDARD_COLOURS = [
+    { value: '#C00000', label: 'Dark Red' },
+    { value: '#FF0000', label: 'Red' },
+    { value: '#FFC000', label: 'Orange' },
+    { value: '#FFFF00', label: 'Yellow' },
+    { value: '#92D050', label: 'Light Green' },
+    { value: '#00B050', label: 'Green' },
+    { value: '#00B0F0', label: 'Light Blue' },
+    { value: '#0070C0', label: 'Blue' },
+    { value: '#002060', label: 'Dark Blue' },
+    { value: '#7030A0', label: 'Purple' },
+];
+function hexToRgb(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+function rgbToHex([r, g, b]) {
+    const part = (v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0').toUpperCase();
+    return `#${part(r)}${part(g)}${part(b)}`;
+}
+/** Mix `hex` toward white (`amount` > 0) or black (`amount` < 0). */
+export function tint(hex, amount) {
+    const [r, g, b] = hexToRgb(hex);
+    const target = amount > 0 ? 255 : 0;
+    const t = Math.abs(amount);
+    return rgbToHex([r + (target - r) * t, g + (target - g) * t, b + (target - b) * t]);
+}
+/**
+ * Excel's five variations under each theme colour. Lighter 80/60/40 % for
+ * the accents; the white and black columns run the other way, as they do in
+ * Excel, so white gets greys and black gets lighter greys rather than five
+ * identical swatches.
+ */
+const STEPS = [
+    { amount: 0.8, label: 'Lighter 80%' },
+    { amount: 0.6, label: 'Lighter 60%' },
+    { amount: 0.4, label: 'Lighter 40%' },
+    { amount: -0.25, label: 'Darker 25%' },
+    { amount: -0.5, label: 'Darker 50%' },
+];
+const WHITE_STEPS = [-0.05, -0.15, -0.25, -0.35, -0.5];
+const BLACK_STEPS = [0.5, 0.35, 0.25, 0.15, 0.05];
+/** Ten columns by six rows: the base row, then five variations per column. */
+export const THEME_COLOURS = (() => {
+    const rows = [THEME_BASE.map((c) => ({ ...c }))];
+    for (let step = 0; step < 5; step += 1) {
+        rows.push(THEME_BASE.map((base, col) => {
+            const amount = col === 0 ? WHITE_STEPS[step] : col === 1 ? BLACK_STEPS[step] : STEPS[step].amount;
+            const name = base.label.split(',')[0];
+            const how = col === 0
+                ? `Darker ${Math.round(Math.abs(amount) * 100)}%`
+                : col === 1
+                    ? `Lighter ${Math.round(amount * 100)}%`
+                    : STEPS[step].label;
+            return { value: tint(base.value, amount), label: `${name}, ${how}` };
+        }));
+    }
+    return rows;
+})();
+/** The whole picker flattened, for a `select` fallback and for tests. */
+export const ALL_COLOURS = [
+    ...THEME_COLOURS.flat(),
+    ...STANDARD_COLOURS,
+];

package/dist/sheet/parse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Precedence-climbing parser over the token stream.
+ *
+ * One structural choice worth naming: a whole-column reference like `A:A`
+ * lexes as a range whose `to.row` is null, and the evaluator fills that in
+ * from the sheet's last used row. Resolving it here instead would bake the
+ * row count into the AST, and the AST is cached across edits that change it.
+ */
+import { type Node } from './ast.js';
+import { type Token } from './tokenize.js';
+export declare function parse(tokens: ReadonlyArray<Token>): Node;
+/** Tokenize and parse one formula. Accepts the leading `=` or not. */
+export declare function parseFormula(src: string): Node;