@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/auto-filter.js

@@ -0,0 +1,295 @@
+/**
+ * Excel's AutoFilter: arrows on the header row of a region, each opening a
+ * menu of the column's values to tick and untick, or a condition (equals,
+ * greater than, contains, between...), and the rows that fail fold away.
+ * The rows are hidden through the grid's collapsed rows, kept apart from
+ * the rows the user hid by hand so Unhide and the saved document see
+ * only those.
+ *
+ * This module is the pure part: the state, the values a column offers,
+ * which rows a state hides, and how the state moves with an insert or
+ * delete. Conditions run through the grid's own Excel-filter compiler, so
+ * the operator semantics are the ones the grid's filter row has.
+ */
+import { compileExcelFilter } from '@svgrid/grid/filtering';
+import { isError } from './ast.js';
+import { shiftRect, lineShift } from './rects.js';
+import { dateValue } from './validation.js';
+/** The operators that compare as numbers; the rest compare the display text. */
+const NUMERIC_OPS = new Set(['greaterThan', 'lessThan', 'between']);
+/**
+ * The values a column offers, each once with its count: numbers first
+ * in order, then text A to Z, the blanks last. `rowVisible` leaves out the
+ * rows other columns' filters hide, as Excel's list does.
+ */
+export function distinctValues(state, col, valueAt, displayAt, rowVisible = () => true) {
+    const seen = new Map();
+    for (let r = state.range[0] + 1; r <= state.range[2]; r += 1) {
+        if (!rowVisible(r))
+            continue;
+        const text = displayAt(r, col);
+        const v = valueAt(r, col);
+        const entry = seen.get(text);
+        if (entry) {
+            entry.count += 1;
+            continue;
+        }
+        seen.set(text, { text, count: 1, numeric: typeof v === 'number' && Number.isFinite(v) ? v : null });
+    }
+    return [...seen.values()].sort((a, b) => {
+        if (a.text === '')
+            return 1;
+        if (b.text === '')
+            return -1;
+        if (a.numeric !== null && b.numeric !== null)
+            return a.numeric - b.numeric;
+        if (a.numeric !== null)
+            return -1;
+        if (b.numeric !== null)
+            return 1;
+        return a.text.localeCompare(b.text, undefined, { sensitivity: 'base' });
+    });
+}
+function passesCondition(cond, value, display) {
+    const test = compileExcelFilter({ id: 'f', operator: cond.op, value: cond.value, valueTo: cond.valueTo });
+    if (NUMERIC_OPS.has(cond.op)) {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            return false;
+        return test(value);
+    }
+    if (cond.op === 'isBlank' || cond.op === 'isNotBlank')
+        return test(display === '' ? null : display);
+    return test(isError(value) ? value.error : display);
+}
+const DAY_MS = 86400000;
+const dayStart = (d) => Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+/**
+ * The first and last day of a period, as UTC day-start milliseconds,
+ * counted from `today`. Weeks run Sunday to Saturday; quarters are the
+ * calendar's. The typed periods read `value` and `valueTo`.
+ */
+export function datePeriodBounds(filter, today = new Date()) {
+    const t = dayStart(today);
+    const y = today.getUTCFullYear();
+    const m = today.getUTCMonth();
+    const q = Math.floor(m / 3);
+    const sunday = t - today.getUTCDay() * DAY_MS;
+    const month = (yy, mm) => [Date.UTC(yy, mm, 1), Date.UTC(yy, mm + 1, 0)];
+    const quarter = (yy, qq) => [Date.UTC(yy, qq * 3, 1), Date.UTC(yy, qq * 3 + 3, 0)];
+    const typed = (text) => {
+        if (!text)
+            return null;
+        const ms = dateValue(text.trim());
+        return ms === null ? null : dayStart(new Date(ms));
+    };
+    switch (filter.period) {
+        case 'today': return [t, t];
+        case 'yesterday': return [t - DAY_MS, t - DAY_MS];
+        case 'tomorrow': return [t + DAY_MS, t + DAY_MS];
+        case 'thisWeek': return [sunday, sunday + 6 * DAY_MS];
+        case 'lastWeek': return [sunday - 7 * DAY_MS, sunday - DAY_MS];
+        case 'nextWeek': return [sunday + 7 * DAY_MS, sunday + 13 * DAY_MS];
+        case 'thisMonth': return month(y, m);
+        case 'lastMonth': return month(y, m - 1);
+        case 'nextMonth': return month(y, m + 1);
+        case 'thisQuarter': return quarter(y, q);
+        case 'lastQuarter': return q === 0 ? quarter(y - 1, 3) : quarter(y, q - 1);
+        case 'nextQuarter': return q === 3 ? quarter(y + 1, 0) : quarter(y, q + 1);
+        case 'thisYear': return [Date.UTC(y, 0, 1), Date.UTC(y, 11, 31)];
+        case 'lastYear': return [Date.UTC(y - 1, 0, 1), Date.UTC(y - 1, 11, 31)];
+        case 'nextYear': return [Date.UTC(y + 1, 0, 1), Date.UTC(y + 1, 11, 31)];
+        case 'yearToDate': return [Date.UTC(y, 0, 1), t];
+        case 'equals': {
+            const d = typed(filter.value);
+            return d === null ? null : [d, d];
+        }
+        case 'before': {
+            const d = typed(filter.value);
+            return d === null ? null : [-Infinity, d - DAY_MS];
+        }
+        case 'after': {
+            const d = typed(filter.value);
+            return d === null ? null : [d + DAY_MS, Infinity];
+        }
+        case 'between': {
+            const a = typed(filter.value);
+            const b = typed(filter.valueTo);
+            return a === null || b === null ? null : [Math.min(a, b), Math.max(a, b)];
+        }
+    }
+}
+const sameFill = (a, b) => (a ?? '').trim().toLowerCase() === (b ?? '').trim().toLowerCase();
+/**
+ * Whether a row passes one column's filter. A Top 10 filter needs the
+ * whole column to know its threshold, which `hiddenRowsFor` works out and
+ * passes as `topPasses`; on its own the filter passes everything.
+ */
+export function passesFilter(filter, value, display, extra = {}) {
+    switch (filter.kind) {
+        case 'values': return filter.included ? filter.included.includes(display) : !filter.excluded.includes(display);
+        case 'date': {
+            const bounds = datePeriodBounds(filter, extra.today);
+            if (!bounds)
+                return true;
+            const ms = dateValue(value);
+            if (ms === null)
+                return false;
+            const day = dayStart(new Date(ms));
+            return day >= bounds[0] && day <= bounds[1];
+        }
+        case 'color': return sameFill(extra.fill ?? null, filter.fill);
+        case 'top': return extra.topPasses ? extra.topPasses(value) : true;
+        default: {
+            const first = passesCondition(filter.first, value, display);
+            if (!filter.second)
+                return first;
+            const second = passesCondition(filter.second, value, display);
+            return filter.join === 'or' ? first || second : first && second;
+        }
+    }
+}
+/** The test a Top 10 filter applies once the column's numbers are known:
+ *  the values at or past the threshold, counted over the whole region as
+ *  Excel counts them, whatever the other columns hide. */
+function topPassesFor(filter, numbers) {
+    if (!numbers.length)
+        return () => false;
+    const sorted = numbers.slice().sort((a, b) => (filter.top ? b - a : a - b));
+    const count = filter.percent ? Math.round((filter.count / 100) * sorted.length) : filter.count;
+    const keep = Math.max(0, Math.min(sorted.length, Math.trunc(count)));
+    if (keep === 0)
+        return () => false;
+    const threshold = sorted[keep - 1];
+    return (value) => typeof value === 'number' && Number.isFinite(value) && (filter.top ? value >= threshold : value <= threshold);
+}
+/**
+ * The rows the state hides: every row of the region under the header
+ * that fails a column's filter. Blanks past the region's edge are not in
+ * it, as Excel's region is what was filtered.
+ */
+export function hiddenRowsFor(state, valueAt, displayAt, ctx = {}) {
+    const out = new Set();
+    if (!state)
+        return out;
+    const columns = Object.entries(state.filters).map(([c, f]) => [Number(c), f]);
+    if (!columns.length)
+        return out;
+    const tops = new Map();
+    for (const [c, filter] of columns) {
+        if (filter.kind !== 'top')
+            continue;
+        const numbers = [];
+        for (let r = state.range[0] + 1; r <= state.range[2]; r += 1) {
+            const v = valueAt(r, c);
+            if (typeof v === 'number' && Number.isFinite(v))
+                numbers.push(v);
+        }
+        tops.set(c, topPassesFor(filter, numbers));
+    }
+    for (let r = state.range[0] + 1; r <= state.range[2]; r += 1) {
+        for (const [c, filter] of columns) {
+            const extra = {
+                today: ctx.today,
+                fill: filter.kind === 'color' ? ctx.fillAt?.(r, c) ?? null : undefined,
+                topPasses: tops.get(c),
+            };
+            if (!passesFilter(filter, valueAt(r, c), displayAt(r, c), extra)) {
+                out.add(r);
+                break;
+            }
+        }
+    }
+    return out;
+}
+/** The fills a column's cells carry, each once, first seen first; null
+ *  stands for the cells with none. Excel's Filter by Color list. */
+export function distinctFills(state, col, fillAt) {
+    const seen = [];
+    for (let r = state.range[0] + 1; r <= state.range[2]; r += 1) {
+        const fill = fillAt(r, col);
+        const key = fill ? fill.trim().toLowerCase() : null;
+        if (!seen.some((f) => sameFill(f, key)))
+            seen.push(key);
+    }
+    return seen;
+}
+/** Whether a column reads as dates: every cell with something in it holds one. */
+export function isDateColumn(values) {
+    const filled = values.filter((v) => v.text !== '');
+    return filled.length > 0 && filled.every((v) => v.numeric === null && dateValue(v.text) !== null);
+}
+/** Whether any column is filtered. */
+export function isFiltering(state) {
+    return !!state && Object.keys(state.filters).length > 0;
+}
+/** The state with one column's filter set, or cleared with null. */
+export function withColumnFilter(state, col, filter) {
+    const filters = { ...state.filters };
+    if (filter === null)
+        delete filters[col];
+    else
+        filters[col] = filter;
+    return { range: state.range, filters };
+}
+/** A values filter from the ticked list, or null when everything is ticked. */
+export function valuesFilter(all, ticked) {
+    const excluded = all.filter((text) => !ticked.has(text));
+    return excluded.length ? { kind: 'values', excluded } : null;
+}
+/** The state after an insert or delete: the region moves, the filters follow their columns. */
+export function shiftAutoFilter(state, edit) {
+    if (!state)
+        return null;
+    const range = shiftRect(state.range, edit);
+    if (!range)
+        return null;
+    if (edit.kind === 'insertRows' || edit.kind === 'deleteRows')
+        return { range, filters: { ...state.filters } };
+    const shift = lineShift(edit);
+    const filters = {};
+    for (const [c, f] of Object.entries(state.filters)) {
+        const next = shift(Number(c));
+        if (next !== null)
+            filters[next] = f;
+    }
+    return { range, filters };
+}
+const OP_WORDS = {
+    equals: 'equals', notEquals: 'does not equal', greaterThan: 'is greater than', lessThan: 'is less than',
+    between: 'is between', contains: 'contains', notContains: 'does not contain', startsWith: 'begins with',
+    endsWith: 'ends with', isBlank: 'is blank', isNotBlank: 'is not blank',
+};
+const PERIOD_WORDS = {
+    equals: 'equals', before: 'is before', after: 'is after', between: 'is between',
+    tomorrow: 'tomorrow', today: 'today', yesterday: 'yesterday',
+    nextWeek: 'next week', thisWeek: 'this week', lastWeek: 'last week',
+    nextMonth: 'next month', thisMonth: 'this month', lastMonth: 'last month',
+    nextQuarter: 'next quarter', thisQuarter: 'this quarter', lastQuarter: 'last quarter',
+    nextYear: 'next year', thisYear: 'this year', lastYear: 'last year', yearToDate: 'year to date',
+};
+/** A filter in words, for the menu's heading. */
+export function describeFilter(filter) {
+    if (filter.kind === 'values' && filter.included)
+        return filter.included.length === 1 ? '1 value shown' : `${filter.included.length} values shown`;
+    if (filter.kind === 'values')
+        return filter.excluded.length === 1 ? '1 value hidden' : `${filter.excluded.length} values hidden`;
+    if (filter.kind === 'date') {
+        const word = PERIOD_WORDS[filter.period];
+        if (filter.period === 'between')
+            return `${word} ${filter.value ?? ''} and ${filter.valueTo ?? ''}`;
+        if (filter.period === 'equals' || filter.period === 'before' || filter.period === 'after')
+            return `${word} ${filter.value ?? ''}`;
+        return word;
+    }
+    if (filter.kind === 'color')
+        return filter.fill ? `filled ${filter.fill}` : 'no fill';
+    if (filter.kind === 'top')
+        return `${filter.top ? 'top' : 'bottom'} ${filter.count}${filter.percent ? ' percent' : ''}`;
+    const one = (c) => {
+        const word = OP_WORDS[c.op] ?? c.op;
+        if (c.op === 'isBlank' || c.op === 'isNotBlank')
+            return word;
+        return c.op === 'between' ? `${word} ${c.value ?? ''} and ${c.valueTo ?? ''}` : `${word} ${c.value ?? ''}`;
+    };
+    return filter.second ? `${one(filter.first)} ${filter.join ?? 'and'} ${one(filter.second)}` : one(filter.first);
+}

package/dist/sheet/autocomplete.d.ts

@@ -0,0 +1,51 @@
+export type FunctionSuggestion = {
+    name: string;
+    /** Where the partial name starts, so accepting can splice it out. */
+    start: number;
+    /** Where the caret is, i.e. where the partial name ends. */
+    end: number;
+};
+/**
+ * The evaluator dispatches these itself, so they are not in the table.
+ *
+ * Exported because `function-catalog.ts` needs the same list: it kept a
+ * copy of its own, the copy fell behind this one, and Insert Function
+ * quietly stopped listing LET, LAMBDA, the lambda helpers and SUBTOTAL
+ * even though it carried written descriptions for them. One list now.
+ */
+export declare const EVALUATOR_NAMES: string[];
+/** Signature hints, for the ones whose argument order is not obvious. */
+export declare const SIGNATURES: Record<string, string>;
+/**
+ * The word being typed immediately before the caret, if it could be a function
+ * name. Returns null when the caret is not in a formula, or sits somewhere a
+ * function name cannot start (inside a string, or right after a reference).
+ */
+export declare function partialAt(text: string, caret: number): {
+    word: string;
+    start: number;
+} | null;
+/**
+ * Function names matching what is being typed.
+ *
+ * Prefix matches first, then anything merely containing the text, so typing
+ * "look" still finds VLOOKUP. Within each group, SHORTER names rank first:
+ * alphabetical order puts SUBSTITUTE above SUM for "SU", which is exactly
+ * backwards from what someone typing two letters wants.
+ */
+export declare function suggestFunctions(text: string, caret: number, limit?: number): FunctionSuggestion[];
+/** Splice an accepted suggestion in, leaving the caret inside the parens. */
+export declare function applySuggestion(text: string, suggestion: FunctionSuggestion): {
+    text: string;
+    caret: number;
+};
+/**
+ * Close the parentheses a formula left open, the way Excel corrects
+ * "=SUM(A1:A3" to "=SUM(A1:A3)" when it is entered. Quoted text is skipped,
+ * so a ")" inside a string neither closes nor needs closing. Text that is
+ * not a formula, or has more closers than openers, is returned as it is:
+ * that one is an error the engine should report, not paper over.
+ */
+export declare function balanceParens(text: string): string;
+/** The signature hint for whatever call the caret is inside, if any. */
+export declare function signatureAt(text: string, caret: number): string | null;

package/dist/sheet/autocomplete.js

@@ -0,0 +1,248 @@
+/**
+ * Formula-bar autocomplete, kept out of the component so the interesting part
+ * is testable without mounting anything.
+ *
+ * The job is narrow: given the text in the bar and where the caret is, work out
+ * whether the user is partway through typing a function name, and if so which
+ * ones match. Everything else (arrow keys, accepting a suggestion) is a list
+ * with an index, which the component owns.
+ */
+import { FUNCTIONS } from './functions.js';
+import { ARRAY_FUNCTIONS } from './packs/array.js';
+/**
+ * The evaluator dispatches these itself, so they are not in the table.
+ *
+ * Exported because `function-catalog.ts` needs the same list: it kept a
+ * copy of its own, the copy fell behind this one, and Insert Function
+ * quietly stopped listing LET, LAMBDA, the lambda helpers and SUBTOTAL
+ * even though it carried written descriptions for them. One list now.
+ */
+export const EVALUATOR_NAMES = ['IF', 'IFS', 'IFERROR', 'IFNA', 'SWITCH', 'ISERROR', 'ISERR', 'ISNA', 'ROW', 'COLUMN', 'ADDRESS', 'OFFSET', 'INDIRECT', 'SUBTOTAL',
+    // LET, LAMBDA and the helpers that take one: the evaluator answers these
+    // itself, since a lambda is an AST rather than a value.
+    'LET', 'LAMBDA', 'MAP', 'BYROW', 'BYCOL', 'REDUCE', 'SCAN', 'MAKEARRAY'];
+const NAMES = [...new Set([...Object.keys(FUNCTIONS), ...Object.keys(ARRAY_FUNCTIONS), ...EVALUATOR_NAMES])].sort();
+/** Signature hints, for the ones whose argument order is not obvious. */
+export const SIGNATURES = {
+    LET: 'LET(name, value, ..., calculation)',
+    LAMBDA: 'LAMBDA(parameter, ..., calculation)',
+    MAP: 'MAP(array, ..., lambda)',
+    BYROW: 'BYROW(array, lambda)',
+    BYCOL: 'BYCOL(array, lambda)',
+    REDUCE: 'REDUCE(initial, array, lambda)',
+    SCAN: 'SCAN(initial, array, lambda)',
+    MAKEARRAY: 'MAKEARRAY(rows, columns, lambda)',
+    VLOOKUP: 'VLOOKUP(lookup, table, colIndex, [rangeLookup])',
+    HLOOKUP: 'HLOOKUP(lookup, table, rowIndex, [rangeLookup])',
+    XLOOKUP: 'XLOOKUP(lookup, haystack, results, [ifMissing], [matchMode], [searchMode])',
+    INDEX: 'INDEX(range, row, [col])',
+    MATCH: 'MATCH(lookup, range, [mode])',
+    SUMIF: 'SUMIF(range, criterion, [sumRange])',
+    SUMIFS: 'SUMIFS(sumRange, range, criterion, ...)',
+    SUBTOTAL: 'SUBTOTAL(code, range, ...)',
+    TRUE: 'TRUE()',
+    FALSE: 'FALSE()',
+    COUNTIF: 'COUNTIF(range, criterion)',
+    COUNTIFS: 'COUNTIFS(range, criterion, ...)',
+    AVERAGEIF: 'AVERAGEIF(range, criterion, [avgRange])',
+    IF: 'IF(condition, then, else)',
+    IFS: 'IFS(condition, value, ...)',
+    IFERROR: 'IFERROR(value, fallback)',
+    SWITCH: 'SWITCH(subject, case, value, ..., [default])',
+    ROUND: 'ROUND(number, digits)',
+    TEXT: 'TEXT(number, pattern)',
+    TEXTJOIN: 'TEXTJOIN(separator, skipEmpty, ...)',
+    SUBSTITUTE: 'SUBSTITUTE(text, find, replace)',
+    MID: 'MID(text, start, length)',
+    DATE: 'DATE(year, month, day)',
+    EOMONTH: 'EOMONTH(date, months)',
+    PMT: 'PMT(rate, nper, pv, [fv], [type])',
+    IPMT: 'IPMT(rate, per, nper, pv, [fv], [type])',
+    PPMT: 'PPMT(rate, per, nper, pv, [fv], [type])',
+    PV: 'PV(rate, nper, pmt, [fv], [type])',
+    FV: 'FV(rate, nper, pmt, [pv], [type])',
+    NPER: 'NPER(rate, pmt, pv, [fv], [type])',
+    RATE: 'RATE(nper, pmt, pv, [fv], [type], [guess])',
+    NPV: 'NPV(rate, value1, ...)',
+    IRR: 'IRR(values, [guess])',
+    SLN: 'SLN(cost, salvage, life)',
+    SUMPRODUCT: 'SUMPRODUCT(array1, [array2], ...)',
+    CEILING: 'CEILING(number, significance)',
+    'CEILING.MATH': 'CEILING.MATH(number, [significance], [mode])',
+    FLOOR: 'FLOOR(number, significance)',
+    'FLOOR.MATH': 'FLOOR.MATH(number, [significance], [mode])',
+    MROUND: 'MROUND(number, multiple)',
+    TRUNC: 'TRUNC(number, [digits])',
+    LOG: 'LOG(number, [base])',
+    RANDBETWEEN: 'RANDBETWEEN(bottom, top)',
+    QUOTIENT: 'QUOTIENT(numerator, denominator)',
+    LARGE: 'LARGE(range, k)',
+    SMALL: 'SMALL(range, k)',
+    PERCENTILE: 'PERCENTILE(range, k)',
+    'PERCENTILE.INC': 'PERCENTILE.INC(range, k)',
+    'PERCENTILE.EXC': 'PERCENTILE.EXC(range, k)',
+    QUARTILE: 'QUARTILE(range, quart)',
+    'QUARTILE.INC': 'QUARTILE.INC(range, quart)',
+    'QUARTILE.EXC': 'QUARTILE.EXC(range, quart)',
+    AVERAGEIFS: 'AVERAGEIFS(avgRange, range, criterion, ...)',
+    MAXIFS: 'MAXIFS(maxRange, range, criterion, ...)',
+    MINIFS: 'MINIFS(minRange, range, criterion, ...)',
+    CORREL: 'CORREL(range1, range2)',
+    SLOPE: 'SLOPE(known_ys, known_xs)',
+    INTERCEPT: 'INTERCEPT(known_ys, known_xs)',
+    FORECAST: 'FORECAST(x, known_ys, known_xs)',
+    'FORECAST.LINEAR': 'FORECAST.LINEAR(x, known_ys, known_xs)',
+    REPT: 'REPT(text, count)',
+    IMAGE: 'IMAGE(source, [alt_text])',
+    NUMBERVALUE: 'NUMBERVALUE(text, [decimal_separator], [group_separator])',
+    REPLACE: 'REPLACE(old_text, start, count, new_text)',
+    EXACT: 'EXACT(text1, text2)',
+    WEEKDAY: 'WEEKDAY(date, [type])',
+    EDATE: 'EDATE(date, months)',
+    NETWORKDAYS: 'NETWORKDAYS(start_date, end_date, [holidays])',
+    WORKDAY: 'WORKDAY(start_date, days, [holidays])',
+    WEEKNUM: 'WEEKNUM(date, [type])',
+    TIME: 'TIME(hour, minute, second)',
+    YEARFRAC: 'YEARFRAC(start_date, end_date, [basis])',
+    NA: 'NA()',
+    CHOOSE: 'CHOOSE(index, value1, ...)',
+    ROW: 'ROW([reference])',
+    COLUMN: 'COLUMN([reference])',
+    ADDRESS: 'ADDRESS(row, column, [abs], [a1], [sheet])',
+    OFFSET: 'OFFSET(reference, rows, cols, [height], [width])',
+    INDIRECT: 'INDIRECT(text, [a1])',
+    FILTER: 'FILTER(array, include, [if_empty])',
+    UNIQUE: 'UNIQUE(array, [by_col], [exactly_once])',
+    SORT: 'SORT(array, [sort_index], [sort_order], [by_col])',
+    SORTBY: 'SORTBY(array, by_array1, [sort_order1], ...)',
+    SEQUENCE: 'SEQUENCE(rows, [columns], [start], [step])',
+    TRANSPOSE: 'TRANSPOSE(array)',
+    TEXTSPLIT: 'TEXTSPLIT(text, col_delimiter, [row_delimiter], [ignore_empty])',
+};
+/**
+ * The word being typed immediately before the caret, if it could be a function
+ * name. Returns null when the caret is not in a formula, or sits somewhere a
+ * function name cannot start (inside a string, or right after a reference).
+ */
+export function partialAt(text, caret) {
+    if (!text.startsWith('='))
+        return null;
+    const upto = text.slice(0, caret);
+    // Inside a string literal there is nothing to suggest. Count unescaped
+    // quotes: an odd number means the caret is inside one.
+    let quotes = 0;
+    for (let i = 0; i < upto.length; i += 1) {
+        if (upto[i] === '"') {
+            if (upto[i + 1] === '"') {
+                i += 1;
+                continue;
+            }
+            quotes += 1;
+        }
+    }
+    if (quotes % 2 === 1)
+        return null;
+    const m = /([A-Za-z][A-Za-z0-9.]*)$/.exec(upto);
+    if (!m)
+        return null;
+    const word = m[1];
+    const start = caret - word.length;
+    // A word followed by digits is a cell reference being typed, not a function.
+    if (/\d$/.test(word))
+        return null;
+    return { word, start };
+}
+/**
+ * Function names matching what is being typed.
+ *
+ * Prefix matches first, then anything merely containing the text, so typing
+ * "look" still finds VLOOKUP. Within each group, SHORTER names rank first:
+ * alphabetical order puts SUBSTITUTE above SUM for "SU", which is exactly
+ * backwards from what someone typing two letters wants.
+ */
+export function suggestFunctions(text, caret, limit = 8) {
+    const partial = partialAt(text, caret);
+    if (!partial || partial.word.length < 1)
+        return [];
+    const upper = partial.word.toUpperCase();
+    const prefix = [];
+    const contains = [];
+    for (const name of NAMES) {
+        if (name === upper)
+            continue;
+        if (name.startsWith(upper))
+            prefix.push(name);
+        else if (name.includes(upper))
+            contains.push(name);
+    }
+    const byCloseness = (a, b) => a.length - b.length || a.localeCompare(b);
+    return [...prefix.sort(byCloseness), ...contains.sort(byCloseness)]
+        .slice(0, limit)
+        .map((name) => ({ name, start: partial.start, end: caret }));
+}
+/** Splice an accepted suggestion in, leaving the caret inside the parens. */
+export function applySuggestion(text, suggestion) {
+    const before = text.slice(0, suggestion.start);
+    const after = text.slice(suggestion.end);
+    // Do not double up a parenthesis the user already typed.
+    const needsParen = !after.startsWith('(');
+    // Only the OPENING parenthesis, as Excel inserts it. Inserting the pair
+    // put the caret between them, and everyone who then typed the arguments
+    // finished with a ")" of their own and got =SUM(A1:A3)) and #PARSE!.
+    // The closing one is supplied at commit by `balanceParens` when it is
+    // still missing, which is what Excel does too.
+    const inserted = needsParen ? `${suggestion.name}(` : suggestion.name;
+    return {
+        text: before + inserted + after,
+        caret: before.length + inserted.length,
+    };
+}
+/**
+ * Close the parentheses a formula left open, the way Excel corrects
+ * "=SUM(A1:A3" to "=SUM(A1:A3)" when it is entered. Quoted text is skipped,
+ * so a ")" inside a string neither closes nor needs closing. Text that is
+ * not a formula, or has more closers than openers, is returned as it is:
+ * that one is an error the engine should report, not paper over.
+ */
+export function balanceParens(text) {
+    if (!text.startsWith('='))
+        return text;
+    let depth = 0;
+    let inString = false;
+    for (const ch of text) {
+        if (ch === '"')
+            inString = !inString;
+        else if (!inString && ch === '(')
+            depth += 1;
+        else if (!inString && ch === ')')
+            depth -= 1;
+    }
+    return depth > 0 ? text + ')'.repeat(depth) : text;
+}
+/** The signature hint for whatever call the caret is inside, if any. */
+export function signatureAt(text, caret) {
+    if (!text.startsWith('='))
+        return null;
+    const upto = text.slice(0, caret);
+    // Walk back looking for an unclosed '(' and read the name before it.
+    let depth = 0;
+    for (let i = upto.length - 1; i >= 0; i -= 1) {
+        const ch = upto[i];
+        if (ch === ')') {
+            depth += 1;
+            continue;
+        }
+        if (ch === '(') {
+            if (depth > 0) {
+                depth -= 1;
+                continue;
+            }
+            const name = /([A-Za-z][A-Za-z0-9.]*)$/.exec(upto.slice(0, i))?.[1];
+            if (!name)
+                return null;
+            const upper = name.toUpperCase();
+            return SIGNATURES[upper] ?? (upper in FUNCTIONS ? `${upper}(...)` : null);
+        }
+    }
+    return null;
+}

package/dist/sheet/cell-images.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Excel's `IMAGE` function: a picture IN a cell rather than floating over
+ * it.
+ *
+ * The difference is the whole point. A picture object hangs from a cell and
+ * covers whatever is under it; an `IMAGE` cell IS the picture, so it sorts
+ * with its row, filters with it, copies as a formula and moves when the
+ * cells move, with nothing to keep in step. A catalogue with a thumbnail
+ * column wants this one.
+ *
+ * The function answers with the source, which is what makes `=IMAGE(A2)`
+ * read like any other formula: the value is text, `ISTEXT` says so, and a
+ * cell that reads it gets the address rather than a picture it cannot use.
+ * Drawing it is the shell's part, and this is what the shell reads to know
+ * a cell is one.
+ */
+/** The arguments of a top-level `=IMAGE(...)`, as written. */
+export type ImageCall = {
+    /** The source expression: a quoted URL, a reference, a formula. */
+    source: string;
+    /** The alt text expression, when the call gives one. */
+    alt?: string;
+};
+/**
+ * The call's arguments when a formula IS one `IMAGE(...)` call, or null.
+ *
+ * Read off the text rather than the parsed tree on purpose: this runs for
+ * every cell that paints, and a scan is cheaper than a parse. A formula
+ * that merely CONTAINS an IMAGE call (`=IF(A1, IMAGE(B1), "")`) is not one,
+ * because its value is not a picture in every case.
+ */
+export declare function imageCall(text: string): ImageCall | null;
+/**
+ * Whether a source is one a browser will load. A `data:` URL and an
+ * ordinary web address are; anything else (a file path, a `javascript:`
+ * scheme) is not, and a cell showing it as text says more than a broken
+ * image would.
+ */
+export declare function isDrawableImageSource(source: string): boolean;