@svgrid/enterprise 3.0.2 → 3.1.0

package/dist/sheet/objects.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Objects on a sheet: the things that float over the cells rather than
+ * living in them. A chart drawn from a range, and a picture.
+ *
+ * Excel anchors an object to a cell and an offset inside it, and that is
+ * what this keeps: the object moves when rows or columns are inserted
+ * above or to the left of it, and goes when the cell it hangs from is
+ * deleted. Its size is in pixels rather than a second anchor cell, so
+ * resizing a column under a chart moves it without reshaping it, which is
+ * Excel's "move but don't size with cells".
+ *
+ * A chart holds the range it reads rather than a copy of the numbers, so
+ * editing a cell redraws it. `chartSpecOf` turns the range into the spec
+ * `<SvChart>` takes, reading through whatever the caller supplies, which
+ * is how the same function serves the shell and a test.
+ */
+import type { ChartSpec } from '@svgrid/grid';
+import type { Rect } from './format-store.js';
+import type { StructuralEdit } from './refs.js';
+import type { CellValue } from './ast.js';
+/** Where an object hangs: a cell, an offset inside it, and a size in pixels. */
+export type ObjectAnchor = {
+    row: number;
+    col: number;
+    /** Offset from the cell's top-left corner, in pixels. */
+    dx: number;
+    dy: number;
+    width: number;
+    height: number;
+};
+/** The chart kinds the sheet offers, a subset of what `<SvChart>` draws. */
+export declare const SHEET_CHART_TYPES: readonly ["bar", "line", "area", "pie", "scatter"];
+export type SheetChartType = (typeof SHEET_CHART_TYPES)[number];
+export type SheetChartObject = {
+    id: string;
+    kind: 'chart';
+    anchor: ObjectAnchor;
+    /** The cells the chart reads, on the sheet it sits on. */
+    range: Rect;
+    type: SheetChartType;
+    /** The range's first row holds the series labels, its first column the categories. */
+    headers: boolean;
+    /** Each column of the range is a series (Excel's default), or each row. */
+    series: 'columns' | 'rows';
+    title?: string;
+    stacked?: boolean;
+    /**
+     * A trend line over every series: Excel's Add Trendline, in the two
+     * shapes people actually pick. Drawn by the chart's own overlay, so it
+     * follows the data rather than being a second set of numbers.
+     */
+    trend?: SheetChartTrend;
+    /**
+     * The series plotted against a second value axis on the right, by its
+     * label. Excel's "Plot series on secondary axis", which is what makes a
+     * revenue-and-margin chart readable when the two are orders of magnitude
+     * apart. Unknown labels are ignored.
+     */
+    secondary?: string;
+};
+/** The trend lines the sheet offers: a straight fit, or a moving average. */
+export declare const SHEET_CHART_TRENDS: readonly ["linear", "sma3"];
+export type SheetChartTrend = (typeof SHEET_CHART_TRENDS)[number];
+export type SheetImageObject = {
+    id: string;
+    kind: 'image';
+    anchor: ObjectAnchor;
+    /** A `data:` or `http(s):` URL. The document carries it as it is. */
+    src: string;
+    alt?: string;
+};
+export type SheetObject = SheetChartObject | SheetImageObject;
+/** An id no other object of this session carries. */
+export declare const objectId: () => string;
+/** A copy safe to hand out or save. */
+export declare function copyObject(object: SheetObject): SheetObject;
+/**
+ * The object after an insert or delete: its anchor cell moves with its
+ * line and a chart's range moves with its cells. Null when the edit
+ * deleted the cell it hangs from, or every cell a chart read.
+ */
+export declare function shiftObject(object: SheetObject, edit: StructuralEdit): SheetObject | null;
+/** The objects of a sheet after an insert or delete, the gone ones dropped. */
+export declare function shiftObjects(objects: ReadonlyArray<SheetObject>, edit: StructuralEdit): SheetObject[];
+/** The object at a point, topmost first: what a click on the layer hits. */
+export declare function objectAt(objects: ReadonlyArray<SheetObject>, point: {
+    x: number;
+    y: number;
+}, boxOf: (object: SheetObject) => {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | null): SheetObject | null;
+/**
+ * The chart's spec, read from its range through `valueAt` (the computed
+ * value) and `textAt` (what the cell shows, for the labels). A chart of a
+ * range with no numbers in it draws nothing rather than throwing.
+ */
+export declare function chartSpecOf(object: SheetChartObject, valueAt: (row: number, col: number) => CellValue, textAt: (row: number, col: number) => string): ChartSpec;
+/**
+ * A chart over a selected block, the way Insert > Chart guesses it: a
+ * header row when the first row is text over numbers, series down the
+ * columns, anchored just below the block.
+ */
+export declare function chartFromRange(range: Rect, valueAt: (row: number, col: number) => CellValue, anchor?: Partial<ObjectAnchor>): SheetChartObject;

package/dist/sheet/objects.js

@@ -0,0 +1,149 @@
+import { shiftRect, lineShift } from './rects.js';
+import { colToLetters } from './address.js';
+/** The chart kinds the sheet offers, a subset of what `<SvChart>` draws. */
+export const SHEET_CHART_TYPES = ['bar', 'line', 'area', 'pie', 'scatter'];
+/** The trend lines the sheet offers: a straight fit, or a moving average. */
+export const SHEET_CHART_TRENDS = ['linear', 'sma3'];
+let nextObjectId = 1;
+/** An id no other object of this session carries. */
+export const objectId = () => `obj-${Date.now().toString(36)}-${(nextObjectId += 1).toString(36)}`;
+/** A copy safe to hand out or save. */
+export function copyObject(object) {
+    return object.kind === 'chart'
+        ? { ...object, anchor: { ...object.anchor }, range: [...object.range] }
+        : { ...object, anchor: { ...object.anchor } };
+}
+/**
+ * The object after an insert or delete: its anchor cell moves with its
+ * line and a chart's range moves with its cells. Null when the edit
+ * deleted the cell it hangs from, or every cell a chart read.
+ */
+export function shiftObject(object, edit) {
+    const shift = lineShift(edit);
+    const rows = edit.kind === 'insertRows' || edit.kind === 'deleteRows';
+    const at = rows ? shift(object.anchor.row) : shift(object.anchor.col);
+    if (at === null)
+        return null;
+    const out = copyObject(object);
+    out.anchor = { ...out.anchor, ...(rows ? { row: at } : { col: at }) };
+    if (out.kind === 'chart') {
+        const range = shiftRect(out.range, edit);
+        if (!range)
+            return null;
+        out.range = range;
+    }
+    return out;
+}
+/** The objects of a sheet after an insert or delete, the gone ones dropped. */
+export function shiftObjects(objects, edit) {
+    return objects.map((o) => shiftObject(o, edit)).filter((o) => o !== null);
+}
+/** The object at a point, topmost first: what a click on the layer hits. */
+export function objectAt(objects, point, boxOf) {
+    for (let i = objects.length - 1; i >= 0; i -= 1) {
+        const box = boxOf(objects[i]);
+        if (!box)
+            continue;
+        if (point.x >= box.left && point.x <= box.left + box.width && point.y >= box.top && point.y <= box.top + box.height)
+            return objects[i];
+    }
+    return null;
+}
+/** 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 chart's spec, read from its range through `valueAt` (the computed
+ * value) and `textAt` (what the cell shows, for the labels). A chart of a
+ * range with no numbers in it draws nothing rather than throwing.
+ */
+export function chartSpecOf(object, valueAt, textAt) {
+    const [r1, c1, r2, c2] = object.range;
+    const byColumns = object.series === 'columns';
+    // Along the series, and across each one.
+    const seriesFrom = byColumns ? c1 : r1;
+    const seriesTo = byColumns ? c2 : r2;
+    const pointFrom = byColumns ? r1 : c1;
+    const pointTo = byColumns ? r2 : c2;
+    // With headers, the first line across is the labels and the first line
+    // along is the categories.
+    const firstSeries = object.headers ? seriesFrom + 1 : seriesFrom;
+    const firstPoint = object.headers ? pointFrom + 1 : pointFrom;
+    const cellAt = (s, p) => (byColumns ? { row: p, col: s } : { row: s, col: p });
+    const categories = [];
+    for (let p = firstPoint; p <= pointTo; p += 1) {
+        const at = cellAt(seriesFrom, p);
+        const label = object.headers ? textAt(at.row, at.col) : '';
+        categories.push(label.trim() === '' ? (byColumns ? String(p + 1) : colToLetters(p)) : label);
+    }
+    const series = [];
+    for (let s = firstSeries; s <= seriesTo; s += 1) {
+        const head = cellAt(s, pointFrom);
+        const label = object.headers ? textAt(head.row, head.col) : '';
+        const values = [];
+        let numeric = false;
+        for (let p = firstPoint; p <= pointTo; p += 1) {
+            const at = cellAt(s, p);
+            const n = numberOf(valueAt(at.row, at.col));
+            if (n !== null)
+                numeric = true;
+            values.push(n ?? 0);
+        }
+        if (!numeric)
+            continue;
+        const name = label.trim() === '' ? (byColumns ? colToLetters(s) : String(s + 1)) : label;
+        series.push({
+            label: name,
+            values,
+            // The trend line and the second axis are per series in the chart, and
+            // a sheet says them once: over everything, and for one series.
+            ...(object.trend ? { overlay: object.trend === 'sma3' ? 'sma:3' : 'linear' } : {}),
+            ...(object.secondary && object.secondary === name ? { axis: 'right' } : {}),
+        });
+    }
+    return {
+        type: object.type,
+        categories,
+        series,
+        ...(object.stacked ? { stacked: true } : {}),
+    };
+}
+/**
+ * A chart over a selected block, the way Insert > Chart guesses it: a
+ * header row when the first row is text over numbers, series down the
+ * columns, anchored just below the block.
+ */
+export function chartFromRange(range, valueAt, anchor) {
+    const [r1, c1, r2, c2] = range;
+    // A header row: the first row is text and the second has a number under it.
+    let headers = false;
+    if (r2 > r1) {
+        let text = 0;
+        let numbers = 0;
+        for (let c = c1; c <= c2; c += 1) {
+            if (typeof valueAt(r1, c) === 'string' && String(valueAt(r1, c)).trim() !== '')
+                text += 1;
+            if (numberOf(valueAt(r1 + 1, c)) !== null)
+                numbers += 1;
+        }
+        headers = text > 0 && numbers > 0;
+    }
+    return {
+        id: objectId(),
+        kind: 'chart',
+        anchor: { row: r2 + 1, col: c1, dx: 8, dy: 8, width: 420, height: 260, ...anchor },
+        range: [r1, c1, r2, c2],
+        type: 'bar',
+        headers,
+        series: 'columns',
+    };
+}

package/dist/sheet/ods-document.d.ts

@@ -0,0 +1,44 @@
+import { type TableRefToken } from './tokenize.js';
+import type { SheetDocument, SheetState } from './document.js';
+import { type ZipCtor } from './xlsx-document.js';
+/** A length as CSS writes it (`1.9445in`, `2.54cm`, `12pt`) in pixels. */
+export declare function odfLength(text: string | null): number | null;
+/**
+ * An ODF formula as A1.
+ *
+ * `of:=SUM([.A1:.A3])` is `=SUM(A1:A3)`; a reference into another sheet is
+ * `[$Sheet2.A1]` or `[$'Price list'.A1]`; arguments are separated by `;`.
+ * The newer functions carry a vendor prefix, which is the same function
+ * under a longer name.
+ */
+export declare function formulaFromOdf(text: string): string;
+/**
+ * What a structured reference points at, for a writer that has a workbook:
+ * ODF has no `Orders[Amount]`, so one has to become the rectangle it names
+ * or the formula cannot be written at all.
+ */
+export type TableResolver = (token: TableRefToken) => {
+    sheet: string | null;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+} | null;
+/**
+ * An A1 formula as ODF writes one: every reference in brackets, `;` between
+ * arguments. Rebuilt from the tokens rather than by substitution, so a comma
+ * inside a string stays a comma and `A1` inside one is not a reference.
+ *
+ * Returns null when the formula cannot be spelled in ODF - a structured
+ * reference with no workbook to resolve it - so the caller can write the
+ * cell's value on its own rather than a formula the reader would refuse.
+ */
+export declare function formulaToOdf(text: string, resolve?: TableResolver): string | null;
+/** The document an .ods holds, from its unzipped parts. */
+export declare function sheetStateFromOds(parts: Record<string, string>): SheetState;
+/** The document an .ods file holds, as a saved state. */
+export declare function documentFromOds(file: Blob | ArrayBuffer | Uint8Array, JSZip?: ZipCtor): Promise<SheetState>;
+/** The parts of an .ods package, as text. */
+export declare function documentToOdsParts(doc: SheetDocument): Record<string, string>;
+/** The document as an .ods Blob: what File > Save As writes for LibreOffice. */
+export declare function documentToOds(doc: SheetDocument, JSZip?: ZipCtor): Promise<Blob>;