@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/paste-special.js

@@ -20,7 +20,7 @@
  * `x:num`, and Sheets' `data-sheets-*` attributes all come through, so a
  * block copied from either arrives with its values, formulas and formats.
  */
-import { translateFormula } from './refs.js';
+import { translateFormula, transposeFormula } from './refs.js';
 import { parseFormula } from './parse.js';
 import { visit } from './ast.js';
 import { entryToStyle } from './format-store.js';
@@ -466,7 +466,10 @@ function arithmetic(existing, incoming, op) {
  * them so) needs to become A1; it then needs no offset, being relative to
  * wherever it lands.
  */
-export function resolvePasteCell(source, existing, opts, offset = { rows: 0, cols: 0 }, at) {
+export function resolvePasteCell(source, existing, opts, offset = { rows: 0, cols: 0 }, at, 
+/** Where the cell came from and lands, for a transposed paste: its
+ *  relative references are turned rather than shifted. */
+turn) {
     if (!source)
         return { kind: 'skip' };
     const what = opts.what ?? 'all';
@@ -484,7 +487,9 @@ export function resolvePasteCell(source, existing, opts, offset = { rows: 0, col
     const value = wantsFormula && source.formula
         ? at && isR1C1(source.formula)
             ? r1c1ToA1(source.formula, at.row, at.col)
-            : String(translateFormula(source.formula, offset.rows, offset.cols))
+            : turn
+                ? String(transposeFormula(source.formula, turn.source, turn.dest))
+                : String(translateFormula(source.formula, offset.rows, offset.cols))
         : source.text;
     if (what === 'values' || what === 'formulas')
         return { kind: 'value', value };
@@ -573,7 +578,8 @@ export function planPaste(grid, destination, opts = {}, origin, fill) {
     for (let tr = 0; tr < repeats.rows; tr += 1) {
         for (let tc = 0; tc < repeats.cols; tc += 1) {
             const corner = { row: destination.row + tr * height, col: destination.col + tc * width };
-            // A transposed paste changes the shape, so Excel does not translate either.
+            // A transposed paste turns each formula's references instead of
+            // shifting them (see `transposeFormula`); the offset is for the rest.
             const offset = origin && !opts.transpose
                 ? { rows: corner.row - origin.row, cols: corner.col - origin.col }
                 : { rows: 0, cols: 0 };
@@ -583,7 +589,10 @@ export function planPaste(grid, destination, opts = {}, origin, fill) {
                     const source = row[c];
                     if (!source)
                         continue;
-                    out.push({ row: corner.row + r, col: corner.col + c, source, offset });
+                    const dest = { row: corner.row + r, col: corner.col + c };
+                    // In the turned grid, (r, c) came from (c, r) of the block.
+                    const turn = opts.transpose && origin ? { source: { row: origin.row + c, col: origin.col + r }, dest } : undefined;
+                    out.push({ ...dest, source, offset, ...(turn ? { turn } : {}) });
                 }
             }
         }

package/dist/sheet/pivot-range.d.ts

@@ -0,0 +1,160 @@
+/**
+ * A PivotTable over a range of cells: Excel's Insert > PivotTable, on the
+ * pivot engine the grid already has (`pivot.ts`).
+ *
+ * The definition is what the sheet keeps: the source range (its first row
+ * is the field names), where the result is written, and the row fields,
+ * column fields and measures. The RESULT is plain cells, written into the
+ * sheet like any other block, so every other part of the shell works on it
+ * without knowing it came from a pivot: it can be formatted, filtered,
+ * charted, printed and saved to an .xlsx. Refresh rebuilds the block from
+ * the source, which is what a pivot over live cells owes the user.
+ *
+ * Everything here is pure: it reads cells through the callbacks it is
+ * given, and returns the block of text to write.
+ */
+import type { Rect } from './format-store.js';
+import type { StructuralEdit } from './refs.js';
+import type { CellValue } from './ast.js';
+/** The aggregations Excel's Summarize Values By offers, as this sheet has them. */
+export declare const SHEET_PIVOT_AGGS: readonly ["sum", "avg", "count", "countDistinct", "min", "max"];
+export type SheetPivotAgg = (typeof SHEET_PIVOT_AGGS)[number];
+export type SheetPivotValue = {
+    /** A field name: one of the source's header cells. */
+    field: string;
+    agg: SheetPivotAgg;
+    label?: string;
+};
+export type SheetPivot = {
+    id: string;
+    /** The source block, its first row the field names. */
+    source: Rect;
+    /** The top-left cell of the written block, on the same sheet. */
+    target: {
+        row: number;
+        col: number;
+    };
+    /** Row fields, outermost first. */
+    rows: string[];
+    /** Column fields, outermost first. */
+    cols: string[];
+    values: SheetPivotValue[];
+    /**
+     * Excel's Filters area: a field, and the one value the whole pivot is
+     * narrowed to. An empty value is "(All)", which narrows nothing.
+     *
+     * It is written above the block, a line per filter, so the reader can
+     * see what the numbers are of; typing another value there and refreshing
+     * is the fast way to change it.
+     */
+    filters?: SheetPivotFilter[];
+    grandTotalRow?: boolean;
+    grandTotalCol?: boolean;
+    rowSubtotals?: boolean;
+    /** The block the last refresh wrote, so the next one can clear it. */
+    written?: Rect;
+};
+export type SheetPivotFilter = {
+    field: string;
+    /** The value to keep, as text. Empty means every value. */
+    value: string;
+};
+/** An id no other pivot of this session carries. */
+export declare const pivotId: () => string;
+/** A copy safe to hand out or save. */
+export declare function copyPivot(pivot: SheetPivot): SheetPivot;
+/**
+ * The pivot after an insert or delete: the source moves with its cells and
+ * the target with its own. Null when the source is gone, or the cell the
+ * result is written at is.
+ */
+export declare function shiftPivot(pivot: SheetPivot, edit: StructuralEdit): SheetPivot | null;
+/** The pivots of a sheet after an insert or delete, the gone ones dropped. */
+export declare function shiftPivots(pivots: ReadonlyArray<SheetPivot>, edit: StructuralEdit): SheetPivot[];
+/**
+ * The field names of a source range: its first row, with a blank header
+ * named after its column the way Excel names an unnamed one.
+ */
+export declare function pivotFields(source: Rect, textAt: (row: number, col: number) => string): string[];
+/** The source's body as records keyed by field name, ready for the engine. */
+export declare function pivotRecords(source: Rect, valueAt: (row: number, col: number) => CellValue, textAt: (row: number, col: number) => string): Array<Record<string, unknown>>;
+/**
+ * The column tree flattened for a sheet: one header row per level of the
+ * tree, and the leaf ids in the order they are written. A header sits over
+ * the leaves it covers, and its own cell is the leftmost of them, the way
+ * Excel writes a merged group header without the merge.
+ */
+export declare function flattenPivotColumns(columns: ReadonlyArray<unknown>): {
+    headerRows: string[][];
+    leaves: Array<{
+        id: string;
+        header: string;
+    }>;
+};
+/**
+ * The records a pivot's filters leave.
+ *
+ * Excel's report filter narrows the whole pivot, not one part of it, so it
+ * applies before anything is grouped: the totals, the subtotals and the
+ * drill-down all see the same rows, which is the only way the numbers on
+ * the page add up.
+ */
+export declare function filteredRecords(pivot: SheetPivot, records: ReadonlyArray<Record<string, unknown>>): Array<Record<string, unknown>>;
+/** The values a field carries, each once, in the order they appear. */
+export declare function pivotFieldValues(field: string, source: Rect, valueAt: (row: number, col: number) => CellValue, textAt: (row: number, col: number) => string): string[];
+/**
+ * The block of text a pivot writes: the column headers, then one line per
+ * pivot row, the row label indented by its depth the way Excel indents a
+ * group under its parent.
+ */
+export declare function pivotBlock(pivot: SheetPivot, valueAt: (row: number, col: number) => CellValue, textAt: (row: number, col: number) => string): string[][];
+/**
+ * The block, and what each of its lines and columns stands for.
+ *
+ * `pivotBlock` writes the cells; drilling into one needs to know which
+ * field values pin it, which is the same walk. Both come from here so they
+ * cannot drift: a cell drawn from one layout and read from another would
+ * open the wrong rows.
+ */
+export type PivotLayout = {
+    cells: string[][];
+    /** How many lines of `cells` are column headers. */
+    headerCount: number;
+    /**
+     * The row field values that pin each line, outermost first, aligned to
+     * `cells`. Null for a header line; shorter than the pivot's row fields
+     * for a group, a subtotal or the grand total, which pin fewer of them.
+     */
+    rowPaths: Array<string[] | null>;
+    /** The same for each column of `cells`. Null for the label column. */
+    colPaths: Array<string[] | null>;
+};
+export declare function pivotLayout(pivot: SheetPivot, valueAt: (row: number, col: number) => CellValue, textAt: (row: number, col: number) => string): PivotLayout;
+/** What a filter with no value chosen shows, and what clears one. */
+export declare const ALL_VALUES = "(All)";
+/** The source rows behind one cell of a written pivot. */
+export type PivotDrill = {
+    /** The row and column field values that pin the cell, outermost first. */
+    rowPath: string[];
+    colPath: string[];
+    /** The records behind it, in the source's own order. */
+    records: Array<Record<string, unknown>>;
+    /** The source's fields, in its own order. */
+    fields: string[];
+};
+/**
+ * Excel's "show details": the rows behind the number in a pivot cell.
+ *
+ * `row` and `col` are a cell on the sheet, not a place in the block. Null
+ * when the cell is outside the pivot, or is a header, or is the row label
+ * column, none of which stand for a number.
+ */
+export declare function pivotDrill(pivot: SheetPivot, row: number, col: number, valueAt: (row: number, col: number) => CellValue, textAt: (row: number, col: number) => string): PivotDrill | null;
+/** The rectangle a block written at the target covers. */
+export declare function pivotWrittenRect(pivot: SheetPivot, block: ReadonlyArray<ReadonlyArray<string>>): Rect;
+/**
+ * Where Excel's Create PivotTable dialog opens: the source is the selected
+ * block, and the result lands two columns past it, which keeps it clear of
+ * the data it reads.
+ */
+export declare function pivotFromRange(source: Rect, fields: ReadonlyArray<string>): SheetPivot;

package/dist/sheet/pivot-range.js

@@ -0,0 +1,333 @@
+import { shiftRect, lineShift } from './rects.js';
+import { colToLetters } from './address.js';
+import { createPivotModel } from '../pivot.js';
+/** The aggregations Excel's Summarize Values By offers, as this sheet has them. */
+export const SHEET_PIVOT_AGGS = ['sum', 'avg', 'count', 'countDistinct', 'min', 'max'];
+let nextPivotId = 1;
+/** An id no other pivot of this session carries. */
+export const pivotId = () => `pivot-${Date.now().toString(36)}-${(nextPivotId += 1).toString(36)}`;
+/** A copy safe to hand out or save. */
+export function copyPivot(pivot) {
+    return {
+        ...pivot,
+        source: [...pivot.source],
+        target: { ...pivot.target },
+        rows: [...pivot.rows],
+        cols: [...pivot.cols],
+        values: pivot.values.map((v) => ({ ...v })),
+        ...(pivot.filters?.length ? { filters: pivot.filters.map((f) => ({ ...f })) } : {}),
+        ...(pivot.written ? { written: [...pivot.written] } : {}),
+    };
+}
+/**
+ * The pivot after an insert or delete: the source moves with its cells and
+ * the target with its own. Null when the source is gone, or the cell the
+ * result is written at is.
+ */
+export function shiftPivot(pivot, edit) {
+    const source = shiftRect(pivot.source, edit);
+    if (!source)
+        return null;
+    const shift = lineShift(edit);
+    const rows = edit.kind === 'insertRows' || edit.kind === 'deleteRows';
+    const at = rows ? shift(pivot.target.row) : shift(pivot.target.col);
+    if (at === null)
+        return null;
+    const out = copyPivot(pivot);
+    out.source = source;
+    out.target = rows ? { ...out.target, row: at } : { ...out.target, col: at };
+    if (out.written) {
+        const written = shiftRect(out.written, edit);
+        if (written)
+            out.written = written;
+        else
+            delete out.written;
+    }
+    return out;
+}
+/** The pivots of a sheet after an insert or delete, the gone ones dropped. */
+export function shiftPivots(pivots, edit) {
+    return pivots.map((p) => shiftPivot(p, edit)).filter((p) => p !== null);
+}
+/**
+ * The field names of a source range: its first row, with a blank header
+ * named after its column the way Excel names an unnamed one.
+ */
+export function pivotFields(source, textAt) {
+    const [r1, c1, , c2] = source;
+    const out = [];
+    const seen = new Set();
+    for (let c = c1; c <= c2; c += 1) {
+        let name = textAt(r1, c).trim() || `Column ${colToLetters(c)}`;
+        // Two columns with one name would collapse into one field.
+        while (seen.has(name))
+            name = `${name} (${colToLetters(c)})`;
+        seen.add(name);
+        out.push(name);
+    }
+    return out;
+}
+/** The source's body as records keyed by field name, ready for the engine. */
+export function pivotRecords(source, valueAt, textAt) {
+    const [r1, c1, r2, c2] = source;
+    const fields = pivotFields(source, textAt);
+    const out = [];
+    for (let r = r1 + 1; r <= r2; r += 1) {
+        const record = {};
+        let any = false;
+        for (let c = c1; c <= c2; c += 1) {
+            const value = valueAt(r, c);
+            record[fields[c - c1]] = value === '' ? null : value;
+            if (value !== '')
+                any = true;
+        }
+        // A wholly empty row is a gap in the block, not a record.
+        if (any)
+            out.push(record);
+    }
+    return out;
+}
+/**
+ * The column tree flattened for a sheet: one header row per level of the
+ * tree, and the leaf ids in the order they are written. A header sits over
+ * the leaves it covers, and its own cell is the leftmost of them, the way
+ * Excel writes a merged group header without the merge.
+ */
+export function flattenPivotColumns(columns) {
+    const nodes = columns;
+    const depthOf = (list) => list.reduce((deep, node) => Math.max(deep, node.columns?.length ? 1 + depthOf(node.columns) : 1), 0);
+    const depth = depthOf(nodes);
+    const headerRows = Array.from({ length: depth }, () => []);
+    const leaves = [];
+    const walk = (list, level) => {
+        for (const node of list) {
+            const label = node.header === undefined || node.header === null ? '' : String(node.header);
+            if (node.columns?.length) {
+                const start = leaves.length;
+                walk(node.columns, level + 1);
+                for (let i = start; i < leaves.length; i += 1)
+                    headerRows[level][i] = i === start ? label : '';
+            }
+            else {
+                leaves.push({ id: String(node.id ?? ''), header: label });
+                const at = leaves.length - 1;
+                for (let l = level; l < depth - 1; l += 1)
+                    headerRows[l][at] = '';
+                headerRows[depth - 1][at] = label;
+            }
+        }
+    };
+    walk(nodes, 0);
+    for (const row of headerRows) {
+        for (let i = 0; i < leaves.length; i += 1)
+            row[i] = row[i] ?? '';
+    }
+    return { headerRows, leaves };
+}
+/**
+ * The records a pivot's filters leave.
+ *
+ * Excel's report filter narrows the whole pivot, not one part of it, so it
+ * applies before anything is grouped: the totals, the subtotals and the
+ * drill-down all see the same rows, which is the only way the numbers on
+ * the page add up.
+ */
+export function filteredRecords(pivot, records) {
+    const active = (pivot.filters ?? []).filter((f) => f.field && f.value !== '');
+    if (!active.length)
+        return [...records];
+    return records.filter((record) => active.every((f) => String(record[f.field] ?? '') === f.value));
+}
+/** The values a field carries, each once, in the order they appear. */
+export function pivotFieldValues(field, source, valueAt, textAt) {
+    const seen = [];
+    for (const record of pivotRecords(source, valueAt, textAt)) {
+        const value = String(record[field] ?? '');
+        if (value !== '' && !seen.includes(value))
+            seen.push(value);
+    }
+    return seen;
+}
+/** A number without the float noise a sum of decimals leaves behind. */
+function cellText(value) {
+    if (value === null || value === undefined || value === '')
+        return '';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            return '';
+        return String(Number(value.toPrecision(12)));
+    }
+    if (typeof value === 'boolean')
+        return value ? 'TRUE' : 'FALSE';
+    return String(value);
+}
+/**
+ * The block of text a pivot writes: the column headers, then one line per
+ * pivot row, the row label indented by its depth the way Excel indents a
+ * group under its parent.
+ */
+export function pivotBlock(pivot, valueAt, textAt) {
+    return pivotLayout(pivot, valueAt, textAt).cells;
+}
+export function pivotLayout(pivot, valueAt, textAt) {
+    const empty = { cells: [], headerCount: 0, rowPaths: [], colPaths: [] };
+    if (!pivot.values.length)
+        return empty;
+    const records = filteredRecords(pivot, pivotRecords(pivot.source, valueAt, textAt));
+    const result = createPivotModel(records, {
+        rows: pivot.rows,
+        cols: pivot.cols,
+        values: pivot.values.map((v) => ({
+            field: v.field,
+            agg: v.agg,
+            ...(v.label ? { label: v.label } : {}),
+        })),
+        grandTotalRow: pivot.grandTotalRow !== false,
+        // With no column field the grand total column would repeat the only
+        // measure column, which is not what Excel shows.
+        grandTotalCol: pivot.cols.length ? pivot.grandTotalCol !== false : false,
+        rowSubtotals: pivot.rowSubtotals !== false,
+    });
+    const { headerRows, leaves } = flattenPivotColumns(result.columns);
+    // The engine's first column is the row-axis label; it is the block's own
+    // first column here rather than one of the leaves.
+    const label = leaves[0]?.id === '__pivotRowHeader' ? leaves.shift() : undefined;
+    const headerLabel = label?.header ?? '';
+    const dropped = label ? 1 : 0;
+    const out = headerRows.map((row, i) => [
+        i === headerRows.length - 1 ? headerLabel : '',
+        ...row.slice(dropped),
+    ]);
+    // With one measure, the bottom header row is that measure's name under
+    // every column, which says nothing the dialog has not. Drop it and let
+    // the column values carry the corner label, as Excel's compact form does.
+    if (pivot.values.length === 1 && out.length > 1) {
+        const measures = out.pop();
+        out[out.length - 1][0] = measures[0] ?? '';
+    }
+    // Excel writes the Filters area above the block, one line per filter and
+    // a blank line under them, so the reader sees what the numbers are of
+    // before reading a number.
+    const filters = (pivot.filters ?? []).filter((f) => f.field);
+    if (filters.length) {
+        const width = out[0]?.length ?? 2;
+        const pad = (line) => {
+            while (line.length < Math.max(width, 2))
+                line.push('');
+            return line;
+        };
+        out.unshift(...filters.map((f) => pad([f.field, f.value === '' ? ALL_VALUES : f.value])), pad([]));
+    }
+    const headerCount = out.length;
+    const rowPaths = Array.from({ length: headerCount }, () => null);
+    // The row axis is a walk down a tree, and the model hands its rows out in
+    // that order: a group before what is under it. Keeping the labels seen at
+    // each depth is enough to know the path of the line being written, and
+    // the label IS the value as the model grouped it, since it groups on the
+    // text too.
+    const stack = [];
+    for (const row of result.rows) {
+        const indent = '    '.repeat(Math.max(0, row.__pivotDepth - 1));
+        out.push([`${indent}${row.__pivotLabel}`, ...leaves.map((leaf) => cellText(row[leaf.id]))]);
+        const depth = Math.max(0, row.__pivotDepth);
+        if (row.__pivotKind === 'grandTotal') {
+            rowPaths.push([]);
+            continue;
+        }
+        stack.length = depth;
+        if (depth > 0)
+            stack[depth - 1] = row.__pivotLabel;
+        rowPaths.push([...stack]);
+    }
+    // A column's path is the headers above it, with a group's label repeated
+    // under it: `flattenPivotColumns` writes a group once, over its leftmost
+    // leaf, the way Excel writes one.
+    const levels = Math.min(pivot.cols.length, headerRows.length);
+    const colPaths = [null];
+    leaves.forEach((leaf, i) => {
+        // The grand total column reads every record, and a sheet with no column
+        // field has one column per measure, which is the same.
+        if (leaf.id.includes('__total__m') || leaf.id.startsWith('pv__all__m')) {
+            colPaths.push([]);
+            return;
+        }
+        const path = [];
+        for (let level = 0; level < levels; level += 1) {
+            let value = '';
+            for (let j = 0; j <= i + dropped; j += 1) {
+                const cell = headerRows[level]?.[j];
+                if (cell)
+                    value = cell;
+            }
+            path.push(value);
+        }
+        colPaths.push(path);
+    });
+    return { cells: out, headerCount, rowPaths, colPaths };
+}
+/** What a filter with no value chosen shows, and what clears one. */
+export const ALL_VALUES = '(All)';
+/**
+ * Excel's "show details": the rows behind the number in a pivot cell.
+ *
+ * `row` and `col` are a cell on the sheet, not a place in the block. Null
+ * when the cell is outside the pivot, or is a header, or is the row label
+ * column, none of which stand for a number.
+ */
+export function pivotDrill(pivot, row, col, valueAt, textAt) {
+    const layout = pivotLayout(pivot, valueAt, textAt);
+    if (!layout.cells.length)
+        return null;
+    const line = row - pivot.target.row;
+    const column = col - pivot.target.col;
+    if (line < 0 || line >= layout.cells.length)
+        return null;
+    if (column < 0 || column >= (layout.cells[line]?.length ?? 0))
+        return null;
+    const rowPath = layout.rowPaths[line];
+    const colPath = layout.colPaths[column];
+    if (!rowPath || !colPath)
+        return null;
+    const records = filteredRecords(pivot, pivotRecords(pivot.source, valueAt, textAt));
+    const matches = records.filter((record) => {
+        for (let i = 0; i < rowPath.length; i += 1) {
+            const field = pivot.rows[i];
+            if (field === undefined)
+                return false;
+            if (String(record[field] ?? '') !== rowPath[i])
+                return false;
+        }
+        for (let i = 0; i < colPath.length; i += 1) {
+            const field = pivot.cols[i];
+            if (field === undefined)
+                return false;
+            if (String(record[field] ?? '') !== colPath[i])
+                return false;
+        }
+        return true;
+    });
+    return { rowPath: [...rowPath], colPath: [...colPath], records: matches, fields: pivotFields(pivot.source, textAt) };
+}
+/** The rectangle a block written at the target covers. */
+export function pivotWrittenRect(pivot, block) {
+    const height = Math.max(1, block.length);
+    const width = Math.max(1, block.reduce((w, row) => Math.max(w, row.length), 0));
+    const { row, col } = pivot.target;
+    return [row, col, row + height - 1, col + width - 1];
+}
+/**
+ * Where Excel's Create PivotTable dialog opens: the source is the selected
+ * block, and the result lands two columns past it, which keeps it clear of
+ * the data it reads.
+ */
+export function pivotFromRange(source, fields) {
+    const [r1, , , c2] = source;
+    return {
+        id: pivotId(),
+        source: [...source],
+        target: { row: r1, col: c2 + 2 },
+        rows: fields.length ? [fields[0]] : [],
+        cols: [],
+        values: fields.length > 1 ? [{ field: fields[fields.length - 1], agg: 'sum' }] : [],
+    };
+}

package/dist/sheet/presence.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Presence: where the other people are.
+ *
+ * The delta stream carries what everyone TYPES; this carries where everyone
+ * IS, which is the other half of two people on one sheet. Seeing a
+ * colleague's box move is what stops two people typing into the same cell,
+ * and it is what makes a shared sheet feel shared rather than merely
+ * synchronised.
+ *
+ * Presence is not part of the document. It is never saved, never in
+ * `getState()` and never in the .xlsx: a cursor belongs to a session, and a
+ * file that remembered where someone's cursor was a week ago would be
+ * remembering nothing worth keeping. It is passed to the shell as a prop and
+ * drawn over the cells.
+ */
+import type { Rect } from './rects.js';
+export type SheetPresence = {
+    /** Whoever this is, stable for as long as they are here. */
+    id: string;
+    /** What to put on the tag. */
+    name: string;
+    /** Their colour, which the box and the tag are drawn in. Left out means
+     *  one picked from the id, so a set of peers is never all one colour. */
+    colour?: string;
+    /** The sheet they are looking at. */
+    sheet: string;
+    /** Their selection, `[minRow, minCol, maxRow, maxCol]`. */
+    rect: Rect;
+    /** The cell the cursor is in, which is where the tag goes. Defaults to
+     *  the top-left of the selection. */
+    active?: {
+        row: number;
+        col: number;
+    };
+    /** When they were last heard from, in ms. Absent counts as now. */
+    at?: number;
+};
+/**
+ * Eight colours that read as different people rather than as a heat map,
+ * stay legible as a thin box over a white sheet and over a dark one, and
+ * each carry a white name at 11px at 4.5:1 or better, so every tag wears
+ * the same white ink. The first set had five a shade too light for that.
+ */
+export declare const PRESENCE_COLOURS: ReadonlyArray<string>;
+/** A colour for an id: the same person gets the same one every session. */
+export declare function presenceColour(id: string): string;
+/**
+ * The ink for a name tag on a person's colour: black or white, whichever
+ * contrasts more. White on every colour was the first version, and white
+ * on the first set's green, orange or yellow was a little over 3:1, under
+ * the 4.5:1 an 11px name needs. The built-in set is dark enough now, but a
+ * collaborator's own colour can be anything, so the tag still asks.
+ * A colour that is not a hex triplet gets white, the way it always did.
+ */
+export declare function presenceInk(colour: string): '#000' | '#fff';
+/** Two initials for the tag when the box is too small for a name. */
+export declare function presenceInitials(name: string): string;
+/**
+ * The peers still here: the newest entry per person, anyone quiet for
+ * longer than `timeoutMs` dropped.
+ *
+ * A network gives no "goodbye" when a tab is closed, so the only honest
+ * answer to "is this person still here" is how long ago they last said
+ * anything. Fifteen seconds is the grid's own answer, and this keeps to it.
+ */
+export declare function livePresence(list: ReadonlyArray<SheetPresence>, now?: number, timeoutMs?: number): SheetPresence[];
+/** The peers on one sheet, in a stable order so the boxes do not swap. */
+export declare function presenceOnSheet(list: ReadonlyArray<SheetPresence>, sheet: string): SheetPresence[];
+/** Where the tag goes: the cell named, or the top-left of the selection. */
+export declare function presenceAnchor(person: SheetPresence): {
+    row: number;
+    col: number;
+};