@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/ast.d.ts

@@ -4,7 +4,10 @@
  * shapes without importing each other.
  */
 import type { CellRef } from './address.js';
-export type SheetError = '#REF!' | '#CYCLE!' | '#DIV/0!' | '#VALUE!' | '#NAME?' | '#NUM!' | '#N/A' | '#PARSE!';
+export type SheetError = '#REF!' | '#CYCLE!' | '#DIV/0!' | '#VALUE!' | '#NAME?' | '#NUM!' | '#N/A' | '#PARSE!' | '#SPILL!' | '#CALC!'
+/** Excel's empty intersection. Nothing here produces it; a file can
+ *  carry it, and a formula can name it, so it is one of the values. */
+ | '#NULL!';
 /** A computed cell value. Errors are values, not exceptions, once evaluation
  *  finishes - that is what lets `=IFERROR(A1, 0)` see one. */
 export type CellValue = string | number | boolean | {
@@ -16,6 +19,10 @@ export declare function isError(v: CellValue): v is {
 export declare function err(code: SheetError): {
     error: SheetError;
 };
+/** The error a typed text stands for, or null when it is ordinary text. */
+export declare function typedError(text: string): {
+    error: SheetError;
+} | null;
 /** Thrown during evaluation and caught at the boundary, where it becomes a
  *  value. Carrying the code on a real Error keeps stack traces useful in dev
  *  without the evaluator having to thread a result type through every branch. */
@@ -33,12 +40,30 @@ export type Node = {
     k: 'bool';
     v: boolean;
 }
+/** An error written INTO a formula: `=#N/A`, `=IFERROR(A1, #N/A)`. Excel
+ *  takes one as a value, and a file from Excel, Google Sheets or
+ *  LibreOffice can carry an error cell as a formula that is only this. */
+ | {
+    k: 'err';
+    v: SheetError;
+}
 /** A single cell. `ref.row` is never null here; a column-only reference
  *  parses as a range instead. */
  | {
     k: 'ref';
     ref: CellRef;
 }
+/**
+ * The spilled-range operator, `A1#`: the rectangle a dynamic array
+ * anchored at `ref` currently spills into. Like a table reference, it is
+ * NOT resolved to a range here - the rectangle depends on how far the
+ * array spills right now, which changes as the array grows, so it is
+ * resolved against the workbook at evaluation. `ref.row` is never null.
+ */
+ | {
+    k: 'spill';
+    ref: CellRef;
+}
 /** A rectangle. Either end's row may be null, meaning a whole-column ref
  *  that runs to the last used row of the sheet. */
  | {
@@ -46,6 +71,19 @@ export type Node = {
     from: CellRef;
     to: CellRef;
 }
+/**
+ * A 3D reference: `Sheet1:Sheet3!A1` or `Jan:Dec!B5:B10`. The same cell or
+ * rectangle on every sheet from `sheetFrom` to `sheetTo` in tab order,
+ * inclusive. `from`/`to` carry no sheet of their own (the sheets are the
+ * range); resolved against the workbook's sheet order at evaluation, so a
+ * tab inserted between the two joins the sum, as Excel's does. */
+ | {
+    k: 'ref3d';
+    sheetFrom: string;
+    sheetTo: string;
+    from: CellRef;
+    to: CellRef;
+}
 /** A defined name (`=Tax`), resolved against the workbook at evaluation. */
  | {
     k: 'name';
@@ -83,6 +121,12 @@ export type Node = {
     k: 'fn';
     name: string;
     args: Node[];
+}
+/** An omitted argument: the gap in `PMT(rate, nper, pv, , 1)`. Reads as a
+ *  blank, so a function sees its default the way it does when the
+ *  argument is simply left off the end. */
+ | {
+    k: 'empty';
 };
 export type BinaryOp = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '>' | '<=' | '>=';
 /** Binding power. Comparison loosest, then concat, then arithmetic. */

package/dist/sheet/ast.js

@@ -4,6 +4,20 @@ export function isError(v) {
 export function err(code) {
     return { error: code };
 }
+/** The error codes a user can type into a cell. Excel stores what is typed
+ *  as the error itself, so =ISNA(A1) over a cell holding #N/A is TRUE.
+ *  #PARSE! is ours, not Excel's, and no one types it. */
+const TYPED_ERRORS = [
+    '#REF!', '#DIV/0!', '#VALUE!', '#NAME?', '#NUM!', '#N/A', '#SPILL!', '#CALC!', '#CYCLE!', '#NULL!',
+];
+/** The error a typed text stands for, or null when it is ordinary text. */
+export function typedError(text) {
+    if (!text.startsWith('#'))
+        return null;
+    const upper = text.toUpperCase();
+    const found = TYPED_ERRORS.find((code) => code === upper);
+    return found ? { error: found } : null;
+}
 /** Thrown during evaluation and caught at the boundary, where it becomes a
  *  value. Carrying the code on a real Error keeps stack traces useful in dev
  *  without the evaluator having to thread a result type through every branch. */

package/dist/sheet/auto-filter.d.ts

@@ -20,14 +20,47 @@ export type FilterCondition = {
     value?: string;
     valueTo?: string;
 };
+/** Excel's Date Filters: a period around today, or a bound typed as a date. */
+export type DatePeriod = 'equals' | 'before' | 'after' | 'between' | 'tomorrow' | 'today' | 'yesterday' | 'nextWeek' | 'thisWeek' | 'lastWeek' | 'nextMonth' | 'thisMonth' | 'lastMonth' | 'nextQuarter' | 'thisQuarter' | 'lastQuarter' | 'nextYear' | 'thisYear' | 'lastYear' | 'yearToDate';
 export type ColumnFilter = {
-    kind: 'values'; /** Display texts left unticked; '' stands for the blanks. */
+    kind: 'values';
+    /** Display texts left unticked; '' stands for the blanks. */
     excluded: string[];
+    /** The texts ticked, from a file that lists what is IN (Excel and ODF
+     *  both do): wins over `excluded` while set. The menu writes the
+     *  exclusion form back the next time the filter is applied. */
+    included?: string[];
 } | {
     kind: 'condition';
     first: FilterCondition;
     join?: 'and' | 'or';
     second?: FilterCondition;
+}
+/** A date period; `value` and `valueTo` are `yyyy-mm-dd` for the typed bounds. */
+ | {
+    kind: 'date';
+    period: DatePeriod;
+    value?: string;
+    valueTo?: string;
+}
+/** Excel's Filter by Color: the cell's fill, or null for the cells with none. */
+ | {
+    kind: 'color';
+    fill: string | null;
+}
+/** Excel's Top 10: the `count` largest (or smallest) values, or that percent of the rows. */
+ | {
+    kind: 'top';
+    top: boolean;
+    count: number;
+    percent?: boolean;
+};
+/** What a filter reads beside the cell's value and text. */
+export type FilterContext = {
+    /** The cell's fill, its own or a conditional format's; null when none. */
+    fillAt?: (r: number, c: number) => string | null;
+    /** The day the date periods count from. */
+    today?: Date;
 };
 export type AutoFilterState = {
     /** The region, header row first. */
@@ -46,14 +79,35 @@ export type FilterValue = {
  * rows other columns' filters hide, as Excel's list does.
  */
 export declare function distinctValues(state: AutoFilterState, col: number, valueAt: (r: number, c: number) => CellValue, displayAt: (r: number, c: number) => string, rowVisible?: (r: number) => boolean): FilterValue[];
-/** Whether a row passes one column's filter. */
-export declare function passesFilter(filter: ColumnFilter, value: CellValue, display: string): boolean;
+/**
+ * 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 declare function datePeriodBounds(filter: Extract<ColumnFilter, {
+    kind: 'date';
+}>, today?: Date): [from: number, to: number] | null;
+/**
+ * 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 declare function passesFilter(filter: ColumnFilter, value: CellValue, display: string, extra?: {
+    fill?: string | null;
+    today?: Date;
+    topPasses?: (value: CellValue) => boolean;
+}): boolean;
 /**
  * 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 declare function hiddenRowsFor(state: AutoFilterState | null, valueAt: (r: number, c: number) => CellValue, displayAt: (r: number, c: number) => string): Set<number>;
+export declare function hiddenRowsFor(state: AutoFilterState | null, valueAt: (r: number, c: number) => CellValue, displayAt: (r: number, c: number) => string, ctx?: FilterContext): Set<number>;
+/** 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 declare function distinctFills(state: AutoFilterState, col: number, fillAt: (r: number, c: number) => string | null): Array<string | null>;
+/** Whether a column reads as dates: every cell with something in it holds one. */
+export declare function isDateColumn(values: ReadonlyArray<FilterValue>): boolean;
 /** Whether any column is filtered. */
 export declare function isFiltering(state: AutoFilterState | null): boolean;
 /** The state with one column's filter set, or cleared with null. */

package/dist/sheet/auto-filter.js

@@ -14,6 +14,7 @@
 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']);
 /**
@@ -60,31 +61,139 @@ function passesCondition(cond, value, display) {
         return test(display === '' ? null : display);
     return test(isError(value) ? value.error : display);
 }
-/** Whether a row passes one column's filter. */
-export function passesFilter(filter, value, display) {
-    if (filter.kind === 'values')
-        return !filter.excluded.includes(display);
-    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;
+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) {
+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) {
-            if (!passesFilter(filter, valueAt(r, c), displayAt(r, c))) {
+            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;
             }
@@ -92,6 +201,23 @@ export function hiddenRowsFor(state, valueAt, displayAt) {
     }
     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;
@@ -133,10 +259,32 @@ const OP_WORDS = {
     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')

package/dist/sheet/autocomplete.d.ts

@@ -5,6 +5,15 @@ export type FunctionSuggestion = {
     /** 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>;
 /**

package/dist/sheet/autocomplete.js

@@ -8,16 +8,40 @@
  * with an index, which the component owns.
  */
 import { FUNCTIONS } from './functions.js';
-const NAMES = Object.keys(FUNCTIONS).sort();
+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 = {
-    VLOOKUP: 'VLOOKUP(lookup, table, colIndex)',
-    HLOOKUP: 'HLOOKUP(lookup, table, rowIndex)',
-    XLOOKUP: 'XLOOKUP(lookup, haystack, results, [ifMissing])',
+    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])',
@@ -32,6 +56,68 @@ export const SIGNATURES = {
     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

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;

package/dist/sheet/cell-images.js

@@ -0,0 +1,90 @@
+/**
+ * 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 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 function imageCall(text) {
+    const trimmed = text.trim();
+    const head = /^=\s*IMAGE\s*\(/i.exec(trimmed);
+    if (!head)
+        return null;
+    const inside = trimmed.slice(head[0].length);
+    const args = [];
+    let depth = 0;
+    let quoted = false;
+    let start = 0;
+    let closed = -1;
+    for (let i = 0; i < inside.length; i += 1) {
+        const ch = inside[i];
+        if (quoted) {
+            if (ch === '"') {
+                if (inside[i + 1] === '"')
+                    i += 1;
+                else
+                    quoted = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            quoted = true;
+            continue;
+        }
+        if (ch === '(') {
+            depth += 1;
+            continue;
+        }
+        if (ch === ')') {
+            if (depth === 0) {
+                args.push(inside.slice(start, i));
+                closed = i;
+                break;
+            }
+            depth -= 1;
+            continue;
+        }
+        if (ch === ',' && depth === 0) {
+            args.push(inside.slice(start, i));
+            start = i + 1;
+        }
+    }
+    // Anything after the closing bracket means the call is part of a larger
+    // formula, so the cell is not simply a picture.
+    if (closed < 0 || inside.slice(closed + 1).trim() !== '')
+        return null;
+    const source = (args[0] ?? '').trim();
+    if (!source)
+        return null;
+    const alt = (args[1] ?? '').trim();
+    return { source, ...(alt ? { alt } : {}) };
+}
+/**
+ * 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 function isDrawableImageSource(source) {
+    const value = source.trim();
+    if (/^data:image\//i.test(value))
+        return true;
+    return /^https?:\/\/\S+$/i.test(value);
+}