@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/sort.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Excel's sort order over a block of rows, by one key or several.
+ *
+ * The rules that make a sheet's sort read as Excel's: numbers before text
+ * before booleans and errors, blanks last whichever way the sort runs,
+ * text without regard to case, a stable order so a tie keeps the rows as
+ * they were, and each key only consulted when the ones before it tie.
+ */
+import { type CellValue } from './ast.js';
+export type SortDirection = 'asc' | 'desc';
+/**
+ * What a key sorts on. Excel's "Sort On" list: the cell's value, or one of
+ * its colours.
+ */
+export type SortOn = 'value' | 'fill' | 'color';
+export type SortKey = {
+    /** The column the key reads, as a sheet column index. */
+    col: number;
+    direction: SortDirection;
+    /** What the key reads in that column. Absent means the value. */
+    on?: SortOn;
+    /**
+     * The colour this key puts first, for a colour key: Excel sorts ONE
+     * colour to the top (ascending) or the bottom (descending) and leaves
+     * every other row where it was. Absent leaves the key doing nothing.
+     */
+    colour?: string;
+};
+/**
+ * The rows in sorted order. `rows` are the row indexes of the block's data
+ * rows (the header left out), `valueAt` reads a computed cell.
+ */
+export declare function sortOrder(rows: ReadonlyArray<number>, keys: ReadonlyArray<SortKey>, valueAt: (row: number, col: number) => CellValue, 
+/**
+ * The colours a cell carries, for a key that sorts on one: its fill and
+ * its font colour, each as it is written, or null. Only a colour key
+ * calls it.
+ */
+colourAt?: (row: number, col: number, on: 'fill' | 'color') => string | null): number[];
+/**
+ * Excel's guess at "my data has headers": the first row of the key column
+ * holds text and the row under it holds something that is not text. Given
+ * the block's columns it looks across them, as Excel does: a Name column
+ * over names says nothing, and the Pay column beside it, text over a
+ * number, is what says the first row is a header, so a sort by name does
+ * not carry "Name" down into the names.
+ */
+export declare function guessHeaderRow(valueAt: (row: number, col: number) => CellValue, top: number, col: number, columns?: {
+    left: number;
+    right: number;
+}): boolean;

package/dist/sheet/sort.js

@@ -0,0 +1,107 @@
+/**
+ * Excel's sort order over a block of rows, by one key or several.
+ *
+ * The rules that make a sheet's sort read as Excel's: numbers before text
+ * before booleans and errors, blanks last whichever way the sort runs,
+ * text without regard to case, a stable order so a tie keeps the rows as
+ * they were, and each key only consulted when the ones before it tie.
+ */
+import { isError } from './ast.js';
+import { isBlankValue } from './navigate.js';
+/** Excel's type order: numbers, then text, then booleans and errors. */
+function rank(v) {
+    if (isBlankValue(v))
+        return [3, ''];
+    if (typeof v === 'number')
+        return [0, v];
+    if (typeof v === 'boolean')
+        return [2, v ? 1 : 0];
+    if (isError(v))
+        return [2, 0];
+    return [1, String(v).toLowerCase()];
+}
+function compareValues(a, b, direction) {
+    const [ka, va] = rank(a);
+    const [kb, vb] = rank(b);
+    // A blank sorts last both ways, as in Excel.
+    if (ka === 3 || kb === 3)
+        return ka === kb ? 0 : ka === 3 ? 1 : -1;
+    if (ka !== kb)
+        return direction === 'asc' ? ka - kb : kb - ka;
+    const cmp = typeof va === 'number' && typeof vb === 'number' ? va - vb : String(va).localeCompare(String(vb));
+    return direction === 'asc' ? cmp : -cmp;
+}
+/**
+ * The rows in sorted order. `rows` are the row indexes of the block's data
+ * rows (the header left out), `valueAt` reads a computed cell.
+ */
+export function sortOrder(rows, keys, valueAt, 
+/**
+ * The colours a cell carries, for a key that sorts on one: its fill and
+ * its font colour, each as it is written, or null. Only a colour key
+ * calls it.
+ */
+colourAt) {
+    if (!keys.length)
+        return [...rows];
+    return rows
+        .map((row, index) => ({ row, index }))
+        .sort((a, b) => {
+        for (const key of keys) {
+            const cmp = key.on === 'fill' || key.on === 'color'
+                ? compareColours(a.row, b.row, key, colourAt)
+                : compareValues(valueAt(a.row, key.col), valueAt(b.row, key.col), key.direction);
+            if (cmp !== 0)
+                return cmp;
+        }
+        return a.index - b.index;
+    })
+        .map((entry) => entry.row);
+}
+/**
+ * A colour key: the rows wearing the chosen colour move to the top, or to
+ * the bottom when the key runs the other way, and everything else keeps the
+ * order it had.
+ *
+ * That is Excel's model and it is worth stating, because the obvious
+ * alternative, ordering colours among themselves, has no order to use: two
+ * colours are not greater or lesser than one another.
+ */
+function compareColours(rowA, rowB, key, colourAt) {
+    if (!key.colour || !colourAt || (key.on !== 'fill' && key.on !== 'color'))
+        return 0;
+    const wanted = key.colour.trim().toLowerCase();
+    const has = (row) => (colourAt(row, key.col, key.on) ?? '').trim().toLowerCase() === wanted;
+    const a = has(rowA);
+    const b = has(rowB);
+    if (a === b)
+        return 0;
+    return key.direction === 'asc' ? (a ? -1 : 1) : (a ? 1 : -1);
+}
+/**
+ * Excel's guess at "my data has headers": the first row of the key column
+ * holds text and the row under it holds something that is not text. Given
+ * the block's columns it looks across them, as Excel does: a Name column
+ * over names says nothing, and the Pay column beside it, text over a
+ * number, is what says the first row is a header, so a sort by name does
+ * not carry "Name" down into the names.
+ */
+export function guessHeaderRow(valueAt, top, col, columns) {
+    const isText = (v) => typeof v === 'string' && v !== '';
+    const headerOver = (c) => {
+        const below = valueAt(top + 1, c);
+        return isText(valueAt(top, c)) && !isText(below) && !isBlankValue(below);
+    };
+    if (!columns)
+        return headerOver(col);
+    let someHeader = false;
+    for (let c = columns.left; c <= columns.right; c += 1) {
+        const head = valueAt(top, c);
+        // A number or a blank in the first row is data, whatever is beside it.
+        if (!isBlankValue(head) && !isText(head))
+            return false;
+        if (headerOver(c))
+            someHeader = true;
+    }
+    return someHeader;
+}

package/dist/sheet/sparklines.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Sparklines: Excel's tiny chart drawn INSIDE a cell, one per row (or per
+ * column) of a block of numbers.
+ *
+ * Excel keeps them as a group rather than as one chart per cell: a data
+ * range, a location range of the same shape, and the settings the whole
+ * group shares (the kind, the colours, whether every line is drawn on one
+ * scale). That is what this keeps, because it is also what the user edits:
+ * changing the kind changes the group, and clearing one clears the group.
+ *
+ * A sparkline is not an object (`objects.ts`): it has no anchor and no size
+ * of its own, it IS the cell, so it moves and dies with the cells the way a
+ * conditional format does. Its data is read live from the range, so editing
+ * a number redraws it.
+ */
+import type { Rect } from './format-store.js';
+import type { StructuralEdit } from './refs.js';
+import type { CellValue } from './ast.js';
+/** The three Excel offers: Line, Column and Win/Loss. */
+export declare const SPARKLINE_TYPES: readonly ["line", "column", "winloss"];
+export type SheetSparklineType = (typeof SPARKLINE_TYPES)[number];
+export type SparklineGroup = {
+    id: string;
+    /** The cells the sparklines are drawn in: one row, or one column. */
+    location: Rect;
+    /** The numbers they read, one line of it per location cell. */
+    data: Rect;
+    type: SheetSparklineType;
+    /** The line or the positive bars. Defaults to the theme's accent. */
+    color?: string;
+    /** The negative bars of a Column or Win/Loss group. */
+    negativeColor?: string;
+    /** One value scale across the whole group, as Excel's "Same for All". */
+    sameScale?: boolean;
+    /** A dot on the last point of a Line group. */
+    markers?: boolean;
+};
+/** An id no other group of this session carries. */
+export declare const sparklineId: () => string;
+/** A copy safe to hand out or save. */
+export declare function copySparkline(group: SparklineGroup): SparklineGroup;
+/**
+ * The group after an insert or delete: both rectangles move with their
+ * cells. Null when the edit took every cell the group was drawn in, or
+ * every cell it read.
+ */
+export declare function shiftSparkline(group: SparklineGroup, edit: StructuralEdit): SparklineGroup | null;
+/** The groups of a sheet after an insert or delete, the gone ones dropped. */
+export declare function shiftSparklines(groups: ReadonlyArray<SparklineGroup>, edit: StructuralEdit): SparklineGroup[];
+/** True when the group draws down a column of cells rather than along a row. */
+export declare function isColumnLocation(group: SparklineGroup): boolean;
+/**
+ * The numbers one location cell draws, read through `valueAt`. The nth cell
+ * of the location reads the nth line of the data: the nth row when the
+ * sparklines run down a column, the nth column when they run along a row.
+ * A blank or a text cell inside the line is a gap, which Excel draws as a
+ * zero rather than breaking the line.
+ */
+export declare function sparklineSeries(group: SparklineGroup, row: number, col: number, valueAt: (row: number, col: number) => CellValue): number[] | null;
+/** The group drawn in a cell, or null: the last one wins, as Excel's does. */
+/**
+ * One line per cell of the group: the cell the sparkline is drawn in and
+ * the block of numbers it reads.
+ *
+ * The drawing works this out cell by cell as it paints; a writer needs the
+ * whole list, because Excel stores a sparkline group as one entry per cell
+ * with its own reference.
+ */
+/**
+ * A sparkline as standalone SVG markup, for a page the component cannot
+ * draw on: the printed sheet.
+ *
+ * The geometry is the grid's own `buildSparkline`, so the printed line is
+ * the line on screen rather than a second drawing that can disagree with
+ * it. The markup carries its colours inline, since the print document has
+ * no stylesheet of ours.
+ */
+export declare function sparklineSvg(values: ReadonlyArray<number>, options: {
+    type?: SheetSparklineType;
+    width: number;
+    height: number;
+    color?: string;
+    negativeColor?: string;
+    min?: number;
+    max?: number;
+    markers?: boolean;
+}): string;
+export declare function sparklineLines(group: SparklineGroup): Array<{
+    row: number;
+    col: number;
+    data: Rect;
+}>;
+export declare function sparklineAt(groups: ReadonlyArray<SparklineGroup>, row: number, col: number): SparklineGroup | null;
+/**
+ * The scale a group is drawn on when every sparkline in it shares one, which
+ * is Excel's "Same for All": the smallest and largest number anywhere in the
+ * data range. Null when the group scales each sparkline on its own.
+ */
+export declare function sparklineScale(group: SparklineGroup, valueAt: (row: number, col: number) => CellValue): {
+    min: number;
+    max: number;
+} | null;
+/**
+ * Where Excel's Create Sparklines dialog opens: the data is the selected
+ * block, and the location the column just past it (or the row just under it
+ * when the block is a single row). A block one cell tall gets a location of
+ * one cell, which is the common "a row of months, a sparkline beside it".
+ */
+export declare function sparklinesFromRange(data: Rect, type?: SheetSparklineType): SparklineGroup;
+/** The groups left after clearing every one the rectangles touch. */
+export declare function clearSparklines(groups: ReadonlyArray<SparklineGroup>, rects: ReadonlyArray<Rect>): SparklineGroup[];

package/dist/sheet/sparklines.js

@@ -0,0 +1,204 @@
+import { shiftRect, rectContains } from './rects.js';
+// The geometry only, through the grid's own subpath: this module is read by
+// the xlsx writer and by tests that run without a DOM, and the package root
+// would drag every component in with it.
+import { buildSparkline } from '@svgrid/grid/sparkline';
+/** The three Excel offers: Line, Column and Win/Loss. */
+export const SPARKLINE_TYPES = ['line', 'column', 'winloss'];
+let nextSparklineId = 1;
+/** An id no other group of this session carries. */
+export const sparklineId = () => `spark-${Date.now().toString(36)}-${(nextSparklineId += 1).toString(36)}`;
+/** A copy safe to hand out or save. */
+export function copySparkline(group) {
+    return { ...group, location: [...group.location], data: [...group.data] };
+}
+/**
+ * The group after an insert or delete: both rectangles move with their
+ * cells. Null when the edit took every cell the group was drawn in, or
+ * every cell it read.
+ */
+export function shiftSparkline(group, edit) {
+    const location = shiftRect(group.location, edit);
+    if (!location)
+        return null;
+    const data = shiftRect(group.data, edit);
+    if (!data)
+        return null;
+    return { ...copySparkline(group), location: location, data: data };
+}
+/** The groups of a sheet after an insert or delete, the gone ones dropped. */
+export function shiftSparklines(groups, edit) {
+    return groups.map((g) => shiftSparkline(g, edit)).filter((g) => g !== null);
+}
+/** True when the group draws down a column of cells rather than along a row. */
+export function isColumnLocation(group) {
+    const [r1, c1, r2, c2] = group.location;
+    // A single cell counts as a column: its data is read as one line either way.
+    return r2 - r1 >= c2 - c1;
+}
+/** A cell's value as a number, or null when it is not one. */
+function numberOf(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+/**
+ * The numbers one location cell draws, read through `valueAt`. The nth cell
+ * of the location reads the nth line of the data: the nth row when the
+ * sparklines run down a column, the nth column when they run along a row.
+ * A blank or a text cell inside the line is a gap, which Excel draws as a
+ * zero rather than breaking the line.
+ */
+export function sparklineSeries(group, row, col, valueAt) {
+    if (!rectContains(group.location, row, col))
+        return null;
+    const [lr1, lc1] = group.location;
+    const [dr1, dc1, dr2, dc2] = group.data;
+    const down = isColumnLocation(group);
+    const index = down ? row - lr1 : col - lc1;
+    const values = [];
+    if (down) {
+        const r = dr1 + index;
+        if (r > dr2)
+            return null;
+        for (let c = dc1; c <= dc2; c += 1)
+            values.push(numberOf(valueAt(r, c)) ?? 0);
+    }
+    else {
+        const c = dc1 + index;
+        if (c > dc2)
+            return null;
+        for (let r = dr1; r <= dr2; r += 1)
+            values.push(numberOf(valueAt(r, c)) ?? 0);
+    }
+    return values.length ? values : null;
+}
+/** The group drawn in a cell, or null: the last one wins, as Excel's does. */
+/**
+ * One line per cell of the group: the cell the sparkline is drawn in and
+ * the block of numbers it reads.
+ *
+ * The drawing works this out cell by cell as it paints; a writer needs the
+ * whole list, because Excel stores a sparkline group as one entry per cell
+ * with its own reference.
+ */
+/**
+ * A sparkline as standalone SVG markup, for a page the component cannot
+ * draw on: the printed sheet.
+ *
+ * The geometry is the grid's own `buildSparkline`, so the printed line is
+ * the line on screen rather than a second drawing that can disagree with
+ * it. The markup carries its colours inline, since the print document has
+ * no stylesheet of ours.
+ */
+export function sparklineSvg(values, options) {
+    const geo = buildSparkline([...values], {
+        type: options.type === 'column' ? 'bar' : options.type === 'winloss' ? 'winloss' : 'line',
+        width: options.width,
+        height: options.height,
+        ...(options.color ? { color: options.color } : {}),
+        ...(options.negativeColor ? { negativeColor: options.negativeColor } : {}),
+        ...(options.min !== undefined ? { min: options.min } : {}),
+        ...(options.max !== undefined ? { max: options.max } : {}),
+        lastPoint: Boolean(options.markers),
+    });
+    if (!geo)
+        return '';
+    const parts = [];
+    if (geo.bars.length) {
+        for (const bar of geo.bars) {
+            const fill = bar.negative ? geo.negativeColor : geo.color;
+            parts.push(`<rect x="${round(bar.x)}" y="${round(bar.y)}" width="${round(bar.w)}" height="${round(bar.h)}" fill="${fill}"/>`);
+        }
+    }
+    if (geo.linePath) {
+        parts.push(`<path d="${geo.linePath}" fill="none" stroke="${geo.color}" stroke-width="${geo.lineWidth}" stroke-linejoin="round" stroke-linecap="round"/>`);
+    }
+    if (geo.lastPoint && options.markers) {
+        parts.push(`<circle cx="${round(geo.lastPoint.x)}" cy="${round(geo.lastPoint.y)}" r="${geo.lineWidth + 0.5}" fill="${geo.color}"/>`);
+    }
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${geo.width}" height="${geo.height}" viewBox="0 0 ${geo.width} ${geo.height}" role="img" aria-hidden="true">${parts.join('')}</svg>`;
+}
+const round = (n) => Math.round(n * 100) / 100;
+export function sparklineLines(group) {
+    const [lr1, lc1, lr2, lc2] = group.location;
+    const [dr1, dc1, dr2, dc2] = group.data;
+    const down = isColumnLocation(group);
+    const out = [];
+    const count = down ? lr2 - lr1 + 1 : lc2 - lc1 + 1;
+    for (let i = 0; i < count; i += 1) {
+        if (down) {
+            const r = dr1 + i;
+            if (r > dr2)
+                break;
+            out.push({ row: lr1 + i, col: lc1, data: [r, dc1, r, dc2] });
+        }
+        else {
+            const c = dc1 + i;
+            if (c > dc2)
+                break;
+            out.push({ row: lr1, col: lc1 + i, data: [dr1, c, dr2, c] });
+        }
+    }
+    return out;
+}
+export function sparklineAt(groups, row, col) {
+    for (let i = groups.length - 1; i >= 0; i -= 1) {
+        if (rectContains(groups[i].location, row, col))
+            return groups[i];
+    }
+    return null;
+}
+/**
+ * The scale a group is drawn on when every sparkline in it shares one, which
+ * is Excel's "Same for All": the smallest and largest number anywhere in the
+ * data range. Null when the group scales each sparkline on its own.
+ */
+export function sparklineScale(group, valueAt) {
+    if (!group.sameScale)
+        return null;
+    const [r1, c1, r2, c2] = group.data;
+    let min = Infinity;
+    let max = -Infinity;
+    for (let r = r1; r <= r2; r += 1) {
+        for (let c = c1; c <= c2; c += 1) {
+            const n = numberOf(valueAt(r, c));
+            if (n === null)
+                continue;
+            if (n < min)
+                min = n;
+            if (n > max)
+                max = n;
+        }
+    }
+    if (min === Infinity)
+        return null;
+    return min === max ? { min: min - 1, max: max + 1 } : { min, max };
+}
+/**
+ * Where Excel's Create Sparklines dialog opens: the data is the selected
+ * block, and the location the column just past it (or the row just under it
+ * when the block is a single row). A block one cell tall gets a location of
+ * one cell, which is the common "a row of months, a sparkline beside it".
+ */
+export function sparklinesFromRange(data, type = 'line') {
+    const [r1, c1, r2, c2] = data;
+    const alongARow = r2 === r1 && c2 > c1;
+    const location = alongARow
+        ? [r1, c2 + 1, r1, c2 + 1]
+        : [r1, c2 + 1, r2, c2 + 1];
+    return { id: sparklineId(), location, data: [r1, c1, r2, c2], type, markers: type === 'line' };
+}
+/** The groups left after clearing every one the rectangles touch. */
+export function clearSparklines(groups, rects) {
+    return groups.filter((g) => !rects.some((rect) => overlaps(g.location, rect)));
+}
+function overlaps(a, b) {
+    return !(a[2] < b[0] || b[2] < a[0] || a[3] < b[1] || b[3] < a[1]);
+}

package/dist/sheet/structure.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Insert and delete rows and columns, with every formula on the sheet
+ * rewritten to follow.
+ *
+ * The api half already existed (`addRow`, `removeRow`, `addColumn`,
+ * `removeColumn`). What was missing is the fixup pass: inserting a row above
+ * `=SUM(D2:D11)` without widening the range silently produces the wrong total,
+ * and deleting a referenced row leaves a formula pointing at whatever moved
+ * into its place. Neither shows an error. That is why this waited for the
+ * engine rather than shipping with the other shortcuts.
+ *
+ * A structural edit is three things in order:
+ *   1. rewrite every formula in the sheet, and every defined name
+ *   2. drop format entries for whatever the edit deletes
+ *   3. apply the structural change itself
+ *
+ * Order matters: the first two read the OLD geometry.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+import { type StructuralEdit } from './refs.js';
+import type { SheetNames } from './names.js';
+import type { SheetFormatStore, CellAddressLookup } from './format-store.js';
+/** What a structural command needs beyond the command context. */
+export type StructureTarget = {
+    /** Rewrite one cell's raw text. Called only for cells that changed. */
+    setRaw(rowIndex: number, colIndex: number, text: string): void;
+    /** Read one cell's raw text, formula included. */
+    getRaw(rowIndex: number, colIndex: number): string;
+    /** Apply the structural change to the data itself. */
+    apply(edit: StructuralEdit): void;
+    /**
+     * Set when `apply` rewrites the references itself. A Workbook does, across
+     * every sheet, which is the whole reason a shell routes the edit through
+     * it; rewriting here as well then moved every reference twice, so one
+     * inserted row turned =SUM(A1:A3) into =SUM(A1:A5) and a cycle.
+     */
+    rewritesReferences?: boolean;
+    names?: SheetNames;
+    format?: {
+        store: SheetFormatStore;
+        lookup: CellAddressLookup;
+    };
+    onChange?(): void;
+    /**
+     * Everything a structural edit can touch, as one value, and the way to
+     * put it back. Supplying both makes insert and delete ONE Ctrl+Z: the
+     * command records the state before and after and hands the grid a step
+     * that restores either. Without them the formula rewrites inside the
+     * edit would sit in the history on their own, and undoing those while
+     * the rows stayed inserted would leave the sheet inconsistent.
+     */
+    snapshot?(): unknown;
+    restore?(state: unknown): void;
+    /**
+     * Whether the edit may happen at all. A protected sheet says no to every
+     * insert and delete, as Excel's does; the ribbon greys Insert and Delete
+     * on the same answer, so it must be cheap and must not talk to the user.
+     */
+    canApply?(edit: StructuralEdit): boolean;
+    /** Called when `canApply` refused an edit: the place to say why. */
+    refused?(): void;
+};
+/** Attach what the insert / delete commands operate on. */
+export declare function setStructureTarget(next: StructureTarget | null): void;
+export declare function getStructureTarget(): StructureTarget | null;
+/**
+ * Rewrite every formula on the sheet for one structural edit.
+ *
+ * Walks the whole grid rather than consulting the dependency graph, because
+ * the graph indexes what a formula READS and this needs every formula that
+ * MENTIONS a moved coordinate, including ones whose precedents were never
+ * resolved (a `#REF!` today may become valid after an insert).
+ */
+export declare function rewriteFormulas(cmd: GridCommandContext, t: StructureTarget, edit: StructuralEdit): number;
+export declare function insertRows(cmd: GridCommandContext, at?: number, count?: number): boolean;
+export declare function deleteRows(cmd: GridCommandContext, at?: number, count?: number): boolean;
+export declare function insertColumns(cmd: GridCommandContext, at?: number, count?: number): boolean;
+export declare function deleteColumns(cmd: GridCommandContext, at?: number, count?: number): boolean;
+/**
+ * Which axis a bare Ctrl+Plus / Ctrl+Minus acts on.
+ *
+ * Excel opens a dialog when the selection is not a whole row or column. That
+ * dialog is a design decision, so this reports what it would ask about and
+ * lets the consumer decide: a selection spanning every column is a row
+ * operation, every row is a column operation, anything else is ambiguous.
+ */
+export declare function axisForSelection(cmd: GridCommandContext): 'rows' | 'cols' | 'ambiguous';