@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/open-file.d.ts

@@ -0,0 +1,26 @@
+/**
+ * One door for a file the user picked.
+ *
+ * A spreadsheet arrives as one of four things, whatever the picker called
+ * it: an .xlsx from Excel or Google Sheets, an .ods from LibreOffice (or
+ * Google Sheets, which offers both), an .xls from any Excel since 1997, or a
+ * .csv, which every one of them exports. The kind is read from the BYTES
+ * rather than from the name: a file picked on a phone often arrives with no
+ * extension and no media type, a zip always starts PK with the package
+ * inside saying which package it is, and an .xls starts with the compound
+ * file signature.
+ */
+import { type ZipCtor } from './xlsx-document.js';
+import type { SheetState } from './document.js';
+export type OpenedFile = {
+    state: SheetState;
+    kind: 'xlsx' | 'ods' | 'xls' | 'csv';
+};
+/** What a file holds, and which kind of file it turned out to be. */
+export declare function readSpreadsheetFile(file: Blob & {
+    name?: string;
+}, JSZip?: ZipCtor): Promise<OpenedFile>;
+/** The document a file holds: .xlsx, .ods, .xls or .csv, decided by its bytes. */
+export declare function documentFromFile(file: Blob & {
+    name?: string;
+}, JSZip?: ZipCtor): Promise<SheetState>;

package/dist/sheet/open-file.js

@@ -0,0 +1,56 @@
+/**
+ * One door for a file the user picked.
+ *
+ * A spreadsheet arrives as one of four things, whatever the picker called
+ * it: an .xlsx from Excel or Google Sheets, an .ods from LibreOffice (or
+ * Google Sheets, which offers both), an .xls from any Excel since 1997, or a
+ * .csv, which every one of them exports. The kind is read from the BYTES
+ * rather than from the name: a file picked on a phone often arrives with no
+ * extension and no media type, a zip always starts PK with the package
+ * inside saying which package it is, and an .xls starts with the compound
+ * file signature.
+ */
+import { documentFromXlsxParts, loadZip } from './xlsx-document.js';
+import { sheetStateFromOds } from './ods-document.js';
+import { sheetStateFromCsv } from './csv.js';
+import { isXlsFile, sheetStateFromXls } from './xls-document.js';
+/** A picture travels as the data URL the document holds, as in the xlsx reader. */
+const MEDIA_PREFIX = 'xl/media/';
+const mediaTypeOf = (path) => {
+    const extension = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+    return extension === 'jpg' || extension === 'jpeg' ? 'image/jpeg' : `image/${extension || 'png'}`;
+};
+/** What a file holds, and which kind of file it turned out to be. */
+export async function readSpreadsheetFile(file, JSZip) {
+    const head = new Uint8Array(await file.slice(0, 8).arrayBuffer());
+    if (isXlsFile(head))
+        return { state: sheetStateFromXls(new Uint8Array(await file.arrayBuffer())), kind: 'xls' };
+    if (head[0] !== 0x50 || head[1] !== 0x4b) {
+        const name = (file.name ?? '').replace(/\.[^.]+$/, '');
+        return { state: sheetStateFromCsv(await file.text(), (name || 'Sheet1').slice(0, 31)), kind: 'csv' };
+    }
+    const Zip = await loadZip(JSZip);
+    const zip = await Zip.loadAsync(file);
+    const parts = {};
+    const pending = [];
+    zip.forEach((path, entry) => {
+        if (entry.dir)
+            return;
+        const clean = path.replace(/^\//, '');
+        if (clean.startsWith(MEDIA_PREFIX)) {
+            pending.push(entry.async('base64').then((base64) => { parts[clean] = `data:${mediaTypeOf(clean)};base64,${base64}`; }));
+            return;
+        }
+        if (!/\.(xml|rels|vml)$/i.test(clean))
+            return;
+        pending.push(entry.async('string').then((text) => { parts[clean] = text; }));
+    });
+    await Promise.all(pending);
+    if (parts['content.xml'] && !parts['xl/workbook.xml'])
+        return { state: sheetStateFromOds(parts), kind: 'ods' };
+    return { state: documentFromXlsxParts(parts), kind: 'xlsx' };
+}
+/** The document a file holds: .xlsx, .ods, .xls or .csv, decided by its bytes. */
+export async function documentFromFile(file, JSZip) {
+    return (await readSpreadsheetFile(file, JSZip)).state;
+}

package/dist/sheet/outline.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Excel's row and column outline: Data > Group, Ungroup and the little
+ * numbered bar down the side that collapses a section away.
+ *
+ * Modelled the way the FILE models it, a level per line rather than a list
+ * of ranges, because that is what `<row outlineLevel="2">` carries and
+ * because ranges have to be split, merged and renumbered on every
+ * structural edit while levels only have to be shifted. A group is then
+ * not a stored object at all: it is a maximal run of lines whose level is
+ * higher than the summary line beside it.
+ *
+ * `summaryBelow` is Excel's own default and says which side the summary
+ * line sits on. With it on, grouping rows 2 to 5 puts the collapse button
+ * on row 6, because that is where the total goes; with it off the button
+ * is on row 1. Columns have the same idea under `summaryRight`.
+ *
+ * Nothing here touches the cells. Hiding a line is the shell's business,
+ * and `hiddenByOutline` is what tells it which.
+ */
+/** Excel allows eight levels, 1 to 7 plus the ungrouped 0. */
+export declare const MAX_OUTLINE_LEVEL = 7;
+export type OutlineState = {
+    /** Level per line index, 1 to 7. A line with no entry is at level 0. */
+    levels: Record<number, number>;
+    /** Summary lines whose group is collapsed. */
+    collapsed: number[];
+};
+export type OutlineSide = {
+    /** The summary sits after the detail (Excel's default for rows). */
+    summaryBelow: boolean;
+};
+export declare const emptyOutline: () => OutlineState;
+export declare const outlineLevel: (state: OutlineState, line: number) => number;
+/** True where nothing is grouped, so the shell can skip the whole gutter. */
+export declare const isOutlined: (state: OutlineState) => boolean;
+/** The deepest level in use, which is how many buttons the level bar shows. */
+export declare function deepestLevel(state: OutlineState): number;
+/**
+ * Group `from`..`to`, deepening each line by one.
+ *
+ * Grouping an already grouped run is how a nested group is made, which is
+ * why this adds a level rather than setting one.
+ */
+export declare function groupLines(state: OutlineState, from: number, to: number): OutlineState;
+/** Ungroup `from`..`to`, taking one level off each line. */
+export declare function ungroupLines(state: OutlineState, from: number, to: number): OutlineState;
+/** Remove every group on this axis. */
+export declare const clearOutline: () => OutlineState;
+/** The lines a summary line owns, or an empty range when it owns none. */
+export declare function detailRange(state: OutlineState, summary: number, side: OutlineSide): {
+    from: number;
+    to: number;
+} | null;
+/** Collapse or expand the group `summary` owns. */
+export declare function toggleCollapsed(state: OutlineState, summary: number): OutlineState;
+/** Which lines an outline hides, detail of every collapsed group included. */
+export declare function hiddenByOutline(state: OutlineState, side: OutlineSide): Set<number>;
+/**
+ * Show levels up to `level` and collapse everything deeper: the numbered
+ * buttons at the corner of the outline bar.
+ *
+ * Level 1 is the most collapsed view, showing only the outermost
+ * summaries; the deepest level shows everything.
+ */
+export declare function showLevel(state: OutlineState, level: number, side: OutlineSide): OutlineState;
+/**
+ * The outline after lines were inserted or deleted, so a group follows the
+ * rows it was put around.
+ *
+ * An inserted line takes the level of the line it pushed down, which is
+ * what Excel does and what makes a row added inside a group part of it.
+ */
+export declare function shiftOutline(state: OutlineState, at: number, count: number): OutlineState;
+/**
+ * An outline read off a block's shape: Excel's Auto Outline.
+ *
+ * A line is detail when the line on the summary side holds a formula that
+ * reads back over it, which is what a SUBTOTAL or SUM column looks like.
+ * `isSummary` answers that for one line, so this module stays free of the
+ * workbook.
+ */
+export declare function autoOutline(from: number, to: number, isSummary: (line: number) => boolean, side: OutlineSide): OutlineState;

package/dist/sheet/outline.js

@@ -0,0 +1,228 @@
+/**
+ * Excel's row and column outline: Data > Group, Ungroup and the little
+ * numbered bar down the side that collapses a section away.
+ *
+ * Modelled the way the FILE models it, a level per line rather than a list
+ * of ranges, because that is what `<row outlineLevel="2">` carries and
+ * because ranges have to be split, merged and renumbered on every
+ * structural edit while levels only have to be shifted. A group is then
+ * not a stored object at all: it is a maximal run of lines whose level is
+ * higher than the summary line beside it.
+ *
+ * `summaryBelow` is Excel's own default and says which side the summary
+ * line sits on. With it on, grouping rows 2 to 5 puts the collapse button
+ * on row 6, because that is where the total goes; with it off the button
+ * is on row 1. Columns have the same idea under `summaryRight`.
+ *
+ * Nothing here touches the cells. Hiding a line is the shell's business,
+ * and `hiddenByOutline` is what tells it which.
+ */
+/** Excel allows eight levels, 1 to 7 plus the ungrouped 0. */
+export const MAX_OUTLINE_LEVEL = 7;
+export const emptyOutline = () => ({ levels: {}, collapsed: [] });
+export const outlineLevel = (state, line) => state.levels[line] ?? 0;
+/** True where nothing is grouped, so the shell can skip the whole gutter. */
+export const isOutlined = (state) => Object.values(state.levels).some((l) => l > 0);
+/** The deepest level in use, which is how many buttons the level bar shows. */
+export function deepestLevel(state) {
+    let max = 0;
+    for (const l of Object.values(state.levels))
+        if (l > max)
+            max = l;
+    return max;
+}
+const clone = (state) => ({
+    levels: { ...state.levels },
+    collapsed: [...state.collapsed],
+});
+/** Drop levels that fell to zero, so the record stays sparse. */
+function tidy(state) {
+    for (const [key, value] of Object.entries(state.levels)) {
+        if (value <= 0)
+            delete state.levels[Number(key)];
+    }
+    // A summary line whose group has gone is no longer collapsed.
+    state.collapsed = [...new Set(state.collapsed)].sort((a, b) => a - b);
+    return state;
+}
+/**
+ * Group `from`..`to`, deepening each line by one.
+ *
+ * Grouping an already grouped run is how a nested group is made, which is
+ * why this adds a level rather than setting one.
+ */
+export function groupLines(state, from, to) {
+    const next = clone(state);
+    const lo = Math.min(from, to);
+    const hi = Math.max(from, to);
+    for (let line = lo; line <= hi; line += 1) {
+        next.levels[line] = Math.min(outlineLevel(next, line) + 1, MAX_OUTLINE_LEVEL);
+    }
+    return tidy(next);
+}
+/** Ungroup `from`..`to`, taking one level off each line. */
+export function ungroupLines(state, from, to) {
+    const next = clone(state);
+    const lo = Math.min(from, to);
+    const hi = Math.max(from, to);
+    for (let line = lo; line <= hi; line += 1) {
+        const level = outlineLevel(next, line) - 1;
+        if (level > 0)
+            next.levels[line] = level;
+        else
+            delete next.levels[line];
+    }
+    // A line that is no longer in a group cannot be a collapsed summary of
+    // one either, or its detail would stay hidden with nothing to show it.
+    next.collapsed = next.collapsed.filter((line) => {
+        if (line < lo || line > hi)
+            return true;
+        return hasDetail({ ...next }, line, { summaryBelow: true })
+            || hasDetail({ ...next }, line, { summaryBelow: false });
+    });
+    return tidy(next);
+}
+/** Remove every group on this axis. */
+export const clearOutline = () => emptyOutline();
+/** The lines a summary line owns, or an empty range when it owns none. */
+export function detailRange(state, summary, side) {
+    const own = outlineLevel(state, summary);
+    const step = side.summaryBelow ? -1 : 1;
+    let line = summary + step;
+    if (outlineLevel(state, line) <= own)
+        return null;
+    while (outlineLevel(state, line + step) > own)
+        line += step;
+    return side.summaryBelow ? { from: line, to: summary - 1 } : { from: summary + 1, to: line };
+}
+const hasDetail = (state, summary, side) => detailRange(state, summary, side) !== null;
+/** Collapse or expand the group `summary` owns. */
+export function toggleCollapsed(state, summary) {
+    const next = clone(state);
+    const at = next.collapsed.indexOf(summary);
+    if (at >= 0)
+        next.collapsed.splice(at, 1);
+    else
+        next.collapsed.push(summary);
+    return tidy(next);
+}
+/** Which lines an outline hides, detail of every collapsed group included. */
+export function hiddenByOutline(state, side) {
+    const hidden = new Set();
+    for (const summary of state.collapsed) {
+        const range = detailRange(state, summary, side);
+        if (!range)
+            continue;
+        for (let line = range.from; line <= range.to; line += 1)
+            hidden.add(line);
+    }
+    return hidden;
+}
+/**
+ * Show levels up to `level` and collapse everything deeper: the numbered
+ * buttons at the corner of the outline bar.
+ *
+ * Level 1 is the most collapsed view, showing only the outermost
+ * summaries; the deepest level shows everything.
+ */
+export function showLevel(state, level, side) {
+    const next = clone(state);
+    next.collapsed = [];
+    const lines = Object.keys(next.levels).map(Number);
+    if (lines.length === 0)
+        return tidy(next);
+    const lo = Math.min(...lines);
+    const hi = Math.max(...lines);
+    // A summary sits just outside its detail, so the sweep runs one line
+    // wider than the outlined block on both sides.
+    for (let line = lo - 1; line <= hi + 1; line += 1) {
+        const range = detailRange(next, line, side);
+        if (!range)
+            continue;
+        // A line at level L is visible under button N when L < N, so the group
+        // whose detail starts at the summary's level plus one has to close as
+        // soon as that depth reaches N rather than only once it passes it.
+        if (outlineLevel(next, line) + 1 >= level)
+            next.collapsed.push(line);
+    }
+    return tidy(next);
+}
+/**
+ * The outline after lines were inserted or deleted, so a group follows the
+ * rows it was put around.
+ *
+ * An inserted line takes the level of the line it pushed down, which is
+ * what Excel does and what makes a row added inside a group part of it.
+ */
+export function shiftOutline(state, at, count) {
+    const next = emptyOutline();
+    const move = (line) => {
+        if (count > 0)
+            return line >= at ? line + count : line;
+        // A deleted line takes its level with it.
+        if (line >= at && line < at - count)
+            return null;
+        return line >= at ? line + count : line;
+    };
+    for (const [key, level] of Object.entries(state.levels)) {
+        const to = move(Number(key));
+        if (to !== null)
+            next.levels[to] = level;
+    }
+    if (count > 0) {
+        // An insertion inside a group inherits the level of what it displaced.
+        const inherited = state.levels[at];
+        if (inherited !== undefined) {
+            for (let i = 0; i < count; i += 1)
+                next.levels[at + i] = inherited;
+        }
+    }
+    for (const summary of state.collapsed) {
+        const to = move(summary);
+        if (to !== null)
+            next.collapsed.push(to);
+    }
+    return tidy(next);
+}
+/**
+ * An outline read off a block's shape: Excel's Auto Outline.
+ *
+ * A line is detail when the line on the summary side holds a formula that
+ * reads back over it, which is what a SUBTOTAL or SUM column looks like.
+ * `isSummary` answers that for one line, so this module stays free of the
+ * workbook.
+ */
+export function autoOutline(from, to, isSummary, side) {
+    const next = emptyOutline();
+    let runStart = null;
+    const close = (summary, start, end) => {
+        if (end < start)
+            return;
+        for (let line = start; line <= end; line += 1)
+            next.levels[line] = 1;
+        void summary;
+    };
+    if (side.summaryBelow) {
+        for (let line = from; line <= to; line += 1) {
+            if (isSummary(line)) {
+                if (runStart !== null)
+                    close(line, runStart, line - 1);
+                runStart = null;
+            }
+            else if (runStart === null)
+                runStart = line;
+        }
+    }
+    else {
+        for (let line = to; line >= from; line -= 1) {
+            if (isSummary(line)) {
+                if (runStart !== null)
+                    close(line, line + 1, runStart);
+                runStart = null;
+            }
+            else if (runStart === null)
+                runStart = line;
+        }
+    }
+    return tidy(next);
+}

package/dist/sheet/packs/array.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The array pack: Excel's dynamic array functions, the ones whose answer
+ * is a grid rather than a value. FILTER, UNIQUE, SORT, SORTBY, SEQUENCE,
+ * TRANSPOSE and TEXTSPLIT. Each takes its arguments the way every other
+ * function does (`FnArgs`, with the 2-D shape of a range in `grids`) and
+ * returns `CellValue[][]`; the evaluator spills a grid over the cells
+ * below and to the right of the formula, or reads its top-left cell where
+ * only a value fits. A grid with nothing in it is `#CALC!`, as in Excel.
+ */
+import { type CellValue } from '../ast.js';
+import type { FnArgs } from '../functions.js';
+export type Grid = CellValue[][];
+export type ArrayFunction = (a: FnArgs) => Grid | CellValue;
+/** The i-th argument as a grid: a range keeps its shape, a value is 1 x 1. */
+export declare function gridArg(a: FnArgs, i: number): Grid | null;
+export declare const ARRAY_FUNCTIONS: Record<string, ArrayFunction>;

package/dist/sheet/packs/array.js

@@ -0,0 +1,172 @@
+/**
+ * The array pack: Excel's dynamic array functions, the ones whose answer
+ * is a grid rather than a value. FILTER, UNIQUE, SORT, SORTBY, SEQUENCE,
+ * TRANSPOSE and TEXTSPLIT. Each takes its arguments the way every other
+ * function does (`FnArgs`, with the 2-D shape of a range in `grids`) and
+ * returns `CellValue[][]`; the evaluator spills a grid over the cells
+ * below and to the right of the formula, or reads its top-left cell where
+ * only a value fits. A grid with nothing in it is `#CALC!`, as in Excel.
+ */
+import { isError, err } from '../ast.js';
+import { toNumber, toBool, toText, compare, isBlank } from '../coerce.js';
+/** The i-th argument as a grid: a range keeps its shape, a value is 1 x 1. */
+export function gridArg(a, i) {
+    const grid = a.grids[i];
+    if (grid)
+        return grid.map((row) => [...row]);
+    const list = a.args[i];
+    return list === undefined ? null : [[list[0] ?? '']];
+}
+const scalar = (a, i) => a.args[i]?.[0] ?? '';
+const given = (a, i) => a.args[i] !== undefined && !(a.args[i].length === 1 && a.args[i][0] === '');
+/** The values of a 1-D array, whichever way it runs. */
+const line = (grid) => (grid.length === 1 ? [...grid[0]] : grid.map((row) => row[0] ?? ''));
+const transpose = (grid) => {
+    const cols = grid.reduce((m, row) => Math.max(m, row.length), 0);
+    return Array.from({ length: cols }, (_, c) => grid.map((row) => row[c] ?? ''));
+};
+const rowsEqual = (a, b) => a.length === b.length && a.every((v, i) => compare(v, b[i]) === 0 && typeof v === typeof b[i]);
+/** Rows of `grid` in the order `keys` says, a stable sort. */
+function sortRows(grid, keys) {
+    const index = grid.map((_, i) => i);
+    index.sort((x, y) => {
+        for (const key of keys) {
+            const a = key.values[x] ?? '';
+            const b = key.values[y] ?? '';
+            const blankA = isBlank(a);
+            const blankB = isBlank(b);
+            // Blanks sort last whichever way, as Excel's SORT puts them.
+            if (blankA !== blankB)
+                return blankA ? 1 : -1;
+            const d = compare(a, b);
+            if (d !== 0)
+                return key.descending ? -d : d;
+        }
+        return x - y;
+    });
+    return index.map((i) => grid[i]);
+}
+const empty = () => err('#CALC!');
+export const ARRAY_FUNCTIONS = {
+    /** FILTER(array, include, [if_empty]): the rows (or columns) where include is true. */
+    FILTER: (a) => {
+        const array = gridArg(a, 0);
+        const include = gridArg(a, 1);
+        if (!array || !include)
+            return err('#VALUE!');
+        const flags = line(include);
+        const byRows = include.length > 1 || (include.length === 1 && include[0].length === 1 && array.length === 1);
+        const along = byRows && include.length !== 1 ? 'rows' : include[0].length > 1 ? 'cols' : 'rows';
+        const count = along === 'rows' ? array.length : (array[0]?.length ?? 0);
+        if (flags.length !== count)
+            return err('#VALUE!');
+        for (const f of flags)
+            if (isError(f))
+                return f;
+        const keep = flags.map((f) => toBool(f));
+        const out = along === 'rows' ? array.filter((_, i) => keep[i]) : array.map((row) => row.filter((_, i) => keep[i]));
+        if (!out.length || !out[0].length)
+            return given(a, 2) ? scalar(a, 2) : empty();
+        return out;
+    },
+    /** UNIQUE(array, [by_col], [exactly_once]): the distinct rows, first seen first. */
+    UNIQUE: (a) => {
+        const array = gridArg(a, 0);
+        if (!array)
+            return err('#VALUE!');
+        const byCol = given(a, 1) && toBool(scalar(a, 1));
+        const once = given(a, 2) && toBool(scalar(a, 2));
+        const rows = byCol ? transpose(array) : array;
+        const counts = rows.map((row) => rows.filter((other) => rowsEqual(row, other)).length);
+        const out = [];
+        rows.forEach((row, i) => {
+            if (once ? counts[i] === 1 : !out.some((seen) => rowsEqual(seen, row)))
+                out.push([...row]);
+        });
+        if (!out.length)
+            return empty();
+        return byCol ? transpose(out) : out;
+    },
+    /** SORT(array, [sort_index], [sort_order], [by_col]). */
+    SORT: (a) => {
+        const array = gridArg(a, 0);
+        if (!array)
+            return err('#VALUE!');
+        const index = given(a, 1) ? Math.trunc(toNumber(scalar(a, 1))) : 1;
+        const order = given(a, 2) ? Math.trunc(toNumber(scalar(a, 2))) : 1;
+        const byCol = given(a, 3) && toBool(scalar(a, 3));
+        if (index < 1 || (order !== 1 && order !== -1))
+            return err('#VALUE!');
+        const rows = byCol ? transpose(array) : array;
+        if (index > (rows[0]?.length ?? 0))
+            return err('#VALUE!');
+        const sorted = sortRows(rows, [{ values: rows.map((row) => row[index - 1] ?? ''), descending: order === -1 }]);
+        return byCol ? transpose(sorted) : sorted;
+    },
+    /** SORTBY(array, by_array1, [order1], [by_array2, order2], ...). */
+    SORTBY: (a) => {
+        const array = gridArg(a, 0);
+        if (!array)
+            return err('#VALUE!');
+        const keys = [];
+        for (let i = 1; i < a.args.length; i += 2) {
+            const by = gridArg(a, i);
+            if (!by)
+                return err('#VALUE!');
+            const values = line(by);
+            if (values.length !== array.length)
+                return err('#VALUE!');
+            const order = given(a, i + 1) ? Math.trunc(toNumber(scalar(a, i + 1))) : 1;
+            if (order !== 1 && order !== -1)
+                return err('#VALUE!');
+            keys.push({ values, descending: order === -1 });
+        }
+        if (!keys.length)
+            return err('#VALUE!');
+        return sortRows(array, keys);
+    },
+    /** SEQUENCE(rows, [columns], [start], [step]). */
+    SEQUENCE: (a) => {
+        const rows = Math.trunc(toNumber(scalar(a, 0)));
+        const cols = given(a, 1) ? Math.trunc(toNumber(scalar(a, 1))) : 1;
+        const start = given(a, 2) ? toNumber(scalar(a, 2)) : 1;
+        const step = given(a, 3) ? toNumber(scalar(a, 3)) : 1;
+        if (rows < 1 || cols < 1)
+            return err('#VALUE!');
+        if (rows * cols > 1000000)
+            return err('#NUM!');
+        let n = start;
+        return Array.from({ length: rows }, () => Array.from({ length: cols }, () => { const v = n; n += step; return v; }));
+    },
+    /** TRANSPOSE(array). */
+    TRANSPOSE: (a) => {
+        const array = gridArg(a, 0);
+        if (!array)
+            return err('#VALUE!');
+        return transpose(array);
+    },
+    /** TEXTSPLIT(text, col_delimiter, [row_delimiter], [ignore_empty]). */
+    TEXTSPLIT: (a) => {
+        const text = scalar(a, 0);
+        if (isError(text))
+            return text;
+        const colDelim = given(a, 1) ? toText(scalar(a, 1)) : '';
+        const rowDelim = given(a, 2) ? toText(scalar(a, 2)) : '';
+        const ignoreEmpty = given(a, 3) && toBool(scalar(a, 3));
+        const split = (s, d) => (d === '' ? [s] : s.split(d));
+        const rows = split(toText(text), rowDelim).map((row) => split(row, colDelim));
+        const kept = ignoreEmpty ? rows.map((row) => row.filter((v) => v !== '')).filter((row) => row.length) : rows;
+        if (!kept.length)
+            return empty();
+        const width = kept.reduce((m, row) => Math.max(m, row.length), 0);
+        return kept.map((row) => Array.from({ length: width }, (_, i) => (i < row.length ? asValue(row[i]) : err('#N/A'))));
+    },
+};
+/** A piece of split text as the cell would read it: a number where it parses. */
+function asValue(piece) {
+    const t = piece.trim();
+    if (t === '')
+        return '';
+    const n = Number(t);
+    return Number.isFinite(n) ? n : piece;
+}

package/dist/sheet/packs/database.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Excel's Database family: the twelve aggregates that read a labelled
+ * block of records through a labelled block of criteria.
+ *
+ * All twelve share one shape, `D<agg>(database, field, criteria)`, and all
+ * the interesting behaviour is in how the criteria block is read:
+ *
+ *   - Its first row is header names, matched against the database's own
+ *     headers by text, ignoring case. A header the database does not have
+ *     matches nothing.
+ *   - Every row UNDER the header is one alternative: the conditions across
+ *     a row are ANDed, and the rows are ORed. That is Excel's advanced
+ *     filter grammar, and it is why the criteria block is two-dimensional
+ *     rather than a list.
+ *   - An empty criteria cell places no condition, so a criteria block that
+ *     is nothing but headers matches every record.
+ *
+ * `field` is either a header's text or its one-based position. Excel takes
+ * both, and a model built by hand usually holds the text while one built
+ * by a formula holds the number.
+ *
+ * These are the only aggregates that need the 2-D shape of their range
+ * rather than its flattened values, so they read `a.grids` throughout.
+ */
+import { type CellValue } from '../ast.js';
+import type { SheetFunction } from '../functions.js';
+type Grid = ReadonlyArray<ReadonlyArray<CellValue>>;
+/** The column `field` names, or -1 when it names none. */
+declare function fieldColumn(field: CellValue, header: ReadonlyArray<CellValue>): number;
+/**
+ * The records that satisfy the criteria block, as rows of the database.
+ *
+ * A criteria row with every cell blank matches everything, which is what
+ * Excel does and what makes a criteria block of headers alone a no-op.
+ */
+declare function selected(database: Grid, criteria: Grid): Array<ReadonlyArray<CellValue>>;
+export declare const DATABASE_FUNCTIONS: Record<string, SheetFunction>;
+/** Exported for the tests, which check the criteria grammar on its own. */
+export declare const __selectRecords: typeof selected;
+/** Exported for the tests: `field` resolution takes text or a position. */
+export declare const __fieldColumn: typeof fieldColumn;
+export {};