@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/sheet-kinds.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What kind of thing a sheet tab is.
+ *
+ * A workbook's tabs have always been cell grids. A `grid` tab is the other
+ * thing a business workbook wants: a data-bound table, backed by records
+ * rather than by cells, sorted and filtered and edited as a grid rather
+ * than as a sheet.
+ *
+ * The trick that makes this cheap rather than a second engine: **a grid
+ * sheet PROJECTS its records into the workbook's cells.** The records are
+ * the truth, and after every change they are written into the same
+ * `string[][]` a cell sheet keeps, header row included. So
+ * `=SUM(Orders!D2:D99)` on a cell sheet reads a grid sheet with no new
+ * machinery at all: the formula engine, the dependency graph, the file
+ * writers and the printer never learn that this tab is different.
+ *
+ * The projection runs through `setRaw`, which ignores a write that changes
+ * nothing, so editing one field of one record rewrites one cell and
+ * recalculates what depended on it, not the sheet.
+ *
+ * What a grid sheet deliberately does NOT do: hold a formula of its own.
+ * Its cells are a rendering of its records, so anything typed into them
+ * would be overwritten by the next projection. A sheet that needs formulas
+ * beside the data is a cell sheet reading the grid one across.
+ */
+import { type SheetField } from './from-rows.js';
+export type SheetKind = 'cells' | 'grid';
+/** One column of a grid sheet, as the sheet describes it. */
+export type GridSheetField = SheetField & {
+    /** Narrow the editor and the alignment, as the grid's own columns do. */
+    type?: 'text' | 'number' | 'date' | 'boolean';
+    width?: number;
+    editable?: boolean;
+};
+export type GridSheetSpec = {
+    fields: GridSheetField[];
+    /** The records. A grid sheet's truth; the cells are made from these. */
+    rows: Array<Record<string, unknown>>;
+    /** Rows may be edited in place. Off by default, as a report would want. */
+    editable?: boolean;
+    /** A totals row under the records, summing every numeric column. */
+    totals?: boolean;
+};
+export declare const emptyGridSheet: () => GridSheetSpec;
+/** The cells a grid sheet stands for: the header, the records, the totals. */
+export declare function projectGridSheet(spec: GridSheetSpec): string[][];
+/**
+ * Where a record sits in the projection.
+ *
+ * Row 0 is the header, so record `i` is at row `i + 1`. Kept as a function
+ * rather than inlined so the offset is named in one place: getting it
+ * wrong reads the header as a record and is silent.
+ */
+export declare const rowOfRecord: (index: number) => number;
+export declare const recordOfRow: (row: number) => number;
+/** Is this row of the projection a record, rather than a header or total? */
+export declare const isRecordRow: (spec: GridSheetSpec, row: number) => boolean;
+/**
+ * A field's column in the projection, or -1.
+ *
+ * Matched on the field name rather than the label, since two columns may
+ * share a label and the name is what the record is keyed by.
+ */
+export declare const columnOfField: (spec: GridSheetSpec, field: string) => number;
+/** A deep-enough copy for a document snapshot. */
+export declare const copyGridSheet: (spec: GridSheetSpec) => GridSheetSpec;
+/**
+ * A value typed into a grid sheet, coerced to the field's type.
+ *
+ * The grid hands back whatever its editor produced, which for a number
+ * column typed into by hand is a string. Storing that would make the
+ * record's shape depend on how it was edited, so it is narrowed here once.
+ */
+export declare function coerceFieldValue(field: GridSheetField, value: unknown): unknown;

package/dist/sheet/sheet-kinds.js

@@ -0,0 +1,91 @@
+/**
+ * What kind of thing a sheet tab is.
+ *
+ * A workbook's tabs have always been cell grids. A `grid` tab is the other
+ * thing a business workbook wants: a data-bound table, backed by records
+ * rather than by cells, sorted and filtered and edited as a grid rather
+ * than as a sheet.
+ *
+ * The trick that makes this cheap rather than a second engine: **a grid
+ * sheet PROJECTS its records into the workbook's cells.** The records are
+ * the truth, and after every change they are written into the same
+ * `string[][]` a cell sheet keeps, header row included. So
+ * `=SUM(Orders!D2:D99)` on a cell sheet reads a grid sheet with no new
+ * machinery at all: the formula engine, the dependency graph, the file
+ * writers and the printer never learn that this tab is different.
+ *
+ * The projection runs through `setRaw`, which ignores a write that changes
+ * nothing, so editing one field of one record rewrites one cell and
+ * recalculates what depended on it, not the sheet.
+ *
+ * What a grid sheet deliberately does NOT do: hold a formula of its own.
+ * Its cells are a rendering of its records, so anything typed into them
+ * would be overwritten by the next projection. A sheet that needs formulas
+ * beside the data is a cell sheet reading the grid one across.
+ */
+import { sheetCellsFromRows } from './from-rows.js';
+export const emptyGridSheet = () => ({ fields: [], rows: [] });
+/** The cells a grid sheet stands for: the header, the records, the totals. */
+export function projectGridSheet(spec) {
+    return sheetCellsFromRows(spec.rows, spec.fields, spec.totals ? { totals: true } : {});
+}
+/**
+ * Where a record sits in the projection.
+ *
+ * Row 0 is the header, so record `i` is at row `i + 1`. Kept as a function
+ * rather than inlined so the offset is named in one place: getting it
+ * wrong reads the header as a record and is silent.
+ */
+export const rowOfRecord = (index) => index + 1;
+export const recordOfRow = (row) => row - 1;
+/** Is this row of the projection a record, rather than a header or total? */
+export const isRecordRow = (spec, row) => row >= 1 && row <= spec.rows.length;
+/**
+ * A field's column in the projection, or -1.
+ *
+ * Matched on the field name rather than the label, since two columns may
+ * share a label and the name is what the record is keyed by.
+ */
+export const columnOfField = (spec, field) => spec.fields.findIndex((f) => f.field === field);
+/** A deep-enough copy for a document snapshot. */
+export const copyGridSheet = (spec) => ({
+    fields: spec.fields.map((f) => ({ ...f })),
+    rows: spec.rows.map((r) => ({ ...r })),
+    ...(spec.editable !== undefined ? { editable: spec.editable } : {}),
+    ...(spec.totals !== undefined ? { totals: spec.totals } : {}),
+});
+/**
+ * A value typed into a grid sheet, coerced to the field's type.
+ *
+ * The grid hands back whatever its editor produced, which for a number
+ * column typed into by hand is a string. Storing that would make the
+ * record's shape depend on how it was edited, so it is narrowed here once.
+ */
+export function coerceFieldValue(field, value) {
+    if (value === null || value === undefined || value === '')
+        return value === '' ? '' : null;
+    switch (field.type) {
+        case 'number': {
+            const n = typeof value === 'number' ? value : Number(String(value).trim());
+            return Number.isFinite(n) ? n : value;
+        }
+        case 'boolean': {
+            if (typeof value === 'boolean')
+                return value;
+            const text = String(value).trim().toLowerCase();
+            if (text === 'true' || text === 'yes' || text === '1')
+                return true;
+            if (text === 'false' || text === 'no' || text === '0')
+                return false;
+            return value;
+        }
+        case 'date': {
+            if (value instanceof Date)
+                return value;
+            const text = String(value).trim();
+            return text === '' ? null : text;
+        }
+        default:
+            return typeof value === 'string' ? value : String(value);
+    }
+}

package/dist/sheet/shortcuts.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The Excel keymap, as a table rather than an if-chain, so the bindings can be
+ * read in one screen and tested as data.
+ *
+ * Matching is exact on modifiers: a binding that does not ask for shift will
+ * not fire when shift is held. Without that, Ctrl+Shift+Arrow would match the
+ * Ctrl+Arrow binding and the extend-selection variant would be unreachable.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+import { type Direction, type Grid, type Rect } from './navigate.js';
+import { type FormatPresetName } from './number-format.js';
+import type { SheetFormatStore, CellAddressLookup, CellFormatEntry } from './format-store.js';
+import type { Workbook } from './workbook.js';
+export type SheetCommand = (cmd: GridCommandContext, event: KeyboardEvent) => boolean;
+/**
+ * What the formatting commands write to, and how they turn a display position
+ * into the stable ids the store keys on.
+ *
+ * Optional because the shortcuts are useful without it: a grid that only wants
+ * navigation and fill never sets one up, and the format bindings decline
+ * rather than half-working.
+ */
+export type SheetFormatTarget = {
+    store: SheetFormatStore;
+    lookup: CellAddressLookup;
+    /** Called after a change so the consumer can re-render. */
+    onChange?(): void;
+    /**
+     * Whether the rectangles may be formatted. A protected sheet says no for
+     * a selection with a locked cell in it; the ribbon greys its buttons on
+     * the same answer, so it must be cheap and must not talk to the user.
+     */
+    guard?(rects: ReadonlyArray<Rect>): boolean;
+    /** Called when a change was refused by `guard`: the place to say why. */
+    refused?(): void;
+};
+/** The guard's answer, with the refusal reported when it is no. */
+export declare function formatAllowed(target: SheetFormatTarget, rects: ReadonlyArray<Rect>): boolean;
+/** Attach the store the formatting shortcuts write to. */
+export declare function setFormatTarget(target: SheetFormatTarget | null): void;
+export declare function getFormatTarget(): SheetFormatTarget | null;
+export declare function setWorkbook(next: Workbook | null, onChange?: () => void, isHidden?: (name: string) => boolean): void;
+export declare function getWorkbook(): Workbook | null;
+/** Move `delta` sheets from the active one. Excel does NOT wrap at the ends,
+ *  so neither does this: hitting the last sheet and pressing again should
+ *  leave you there rather than teleport you to the first. */
+export declare function switchSheet(delta: number): boolean;
+export declare function setPasteSpecialHandler(fn: ((cmd: GridCommandContext) => void) | null): void;
+export declare function setFindReplaceHandler(fn: ((cmd: GridCommandContext) => void) | null): void;
+/** Called when Ctrl+1 fires, so a consumer can open its own dialog. The
+ *  shortcut layer does not ship one: what a Format Cells dialog should look
+ *  like is a design decision, not a keyboard one. */
+/**
+ * Ribbon actions a key raises: F9 recalculates, Ctrl+` shows formulas,
+ * Ctrl+Shift+L toggles the filter, Shift+F3 and Ctrl+F3 open Insert
+ * Function and the Name Manager, Ctrl+T formats as a table. The shell
+ * answers them the way it answers the ribbon button; returning false means
+ * nothing is behind the action and the key falls through.
+ */
+export type RibbonKeyAction = 'file-open' | 'file-save-xlsx' | 'file-print' | 'recalculate' | 'toggle-formulas' | 'toggle-filter' | 'insert-function' | 'name-manager' | 'insert-table' | 'hide-rows' | 'hide-columns' | 'unhide-rows' | 'unhide-columns' | 'edit-comment' | 'open-list' | 'toggle-ribbon' | 'insert-link' | 'merge-center' | 'merge-across' | 'merge-cells' | 'unmerge-cells' | 'cut';
+export declare function setRibbonActionHandler(fn: ((action: RibbonKeyAction, cmd: GridCommandContext) => boolean) | null): void;
+/** Raise a ribbon action from a button whose face is not an entry of its own. */
+export declare function raiseRibbonAction(action: RibbonKeyAction, cmd: GridCommandContext): boolean;
+/** Excel's size ladder. Pixels here, since that is what the cell renders. */
+export declare const FONT_SIZES: number[];
+/** A cell with no size of its own renders at the grid's 13px. */
+export declare const DEFAULT_FONT_SIZE = 13;
+/** The format entry under the active cell, or undefined. */
+export declare function activeEntry(cmd: GridCommandContext): CellFormatEntry | undefined;
+/** Excel's Increase / Decrease Font Size: the next rung of the ladder. */
+export declare function nudgeFontSize(direction: 1 | -1): SheetCommand;
+export declare function setFormatDialogHandler(fn: ((cmd: GridCommandContext) => void) | null): void;
+export declare function setShortcutOwner(token: object | null): void;
+export declare function getShortcutOwner(): object | null;
+export type SheetBinding = {
+    /** Matched case-insensitively against `event.key`. */
+    key: string;
+    /**
+     * Matched against `event.code` INSTEAD of `key`, for bindings where shift
+     * changes the character. Pressing Ctrl+Shift+1 reports `event.key` as '!'
+     * on a US layout, ':' for Ctrl+Shift+; and '~' for Ctrl+Shift+`, so a
+     * binding spelling the unshifted character can never fire in a browser.
+     * `code` is the physical key and does not move.
+     */
+    code?: string;
+    /** Ctrl on Windows/Linux, Cmd on macOS. Both are accepted for either. */
+    mod?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    /**
+     * Runs while a cell is being edited, and only then. The other bindings
+     * act on the selection and stay out of the editor, where Ctrl+D is a
+     * keystroke the user meant for the text.
+     */
+    editing?: boolean;
+    run: SheetCommand;
+    /** For docs and the demo's cheat sheet. */
+    label: string;
+};
+/** Read the grid through the command context as a blank-aware matrix. */
+export declare function gridOf(cmd: GridCommandContext): Grid;
+/**
+ * Ctrl+End: the bottom-right corner of what has been typed, as in Excel,
+ * rather than the grid's last cell. A sheet has thousands of empty rows
+ * below the data, and the last of them is never where the user wanted to
+ * go. Ctrl+Home is the grid's own and already lands on A1.
+ */
+export declare function lastUsedCell(cmd: GridCommandContext): {
+    row: number;
+    col: number;
+};
+export declare const goToLastUsed: SheetCommand;
+/** F4 while editing: turn the reference at the caret through its anchorings. */
+export declare const pinReference: SheetCommand;
+export declare function move(dir: Direction, extend: boolean): SheetCommand;
+/** Ctrl+A: the current region, then the whole sheet on a second press. */
+export declare const selectRegion: SheetCommand;
+/**
+ * Ctrl+Space / Shift+Space: the whole columns or rows the selection
+ * touches (B2:C3 gives rows 2:3), as in Excel; the active cell stays.
+ */
+export declare function selectLine(axis: 'column' | 'row'): SheetCommand;
+/** Ctrl+Shift+8 (Ctrl+*): the current region, and only that. */
+export declare const selectCurrentRegion: SheetCommand;
+/**
+ * Run a format change over `rects` as ONE undo step.
+ *
+ * The format store is not the grid's data, so a write to it is invisible
+ * to Ctrl+Z on its own: Bold would land and the Undo button would stay
+ * grey, which is not how a spreadsheet behaves. This snapshots every cell
+ * the change touches before and after, and hands the grid a step that puts
+ * either snapshot back. A cell's whole entry is restored rather than the
+ * one field, so undoing "bold" on a cell that was also made red does not
+ * have to know which of the two the press was about.
+ */
+export declare function withFormatUndo(cmd: GridCommandContext, target: SheetFormatTarget, rects: ReadonlyArray<Rect>, mutate: () => void): void;
+/** Apply a patch to the selection through the attached store. */
+export declare function applyFormat(cmd: GridCommandContext, patch: CellFormatEntry): boolean;
+export declare function toggleFormat(cmd: GridCommandContext, field: 'bold' | 'italic' | 'underline' | 'strike'): boolean;
+export type BorderPreset = 'none' | 'bottom' | 'top' | 'left' | 'right' | 'all' | 'outside' | 'thick-bottom';
+/**
+ * Excel's Borders menu, applied the way Excel applies it: "Bottom Border"
+ * puts a line under the bottom edge of the SELECTION, not under every
+ * cell; "All Borders" lines every cell; "Outside" frames the block. Sides
+ * merge with what a cell already has, so a top border does not erase a
+ * bottom one, and "No Border" clears all four.
+ */
+export declare function applyBorders(cmd: GridCommandContext, preset: BorderPreset): boolean;
+/** Excel's Clear Formats: drop every format on the selection, keep the values. */
+export declare function clearFormats(cmd: GridCommandContext): boolean;
+export declare function preset(name: FormatPresetName): SheetCommand;
+/**
+ * Alt+=. Proposes =SUM(range) over the run Excel would guess. With one cell
+ * selected the formula is opened in the cell's editor rather than written,
+ * as Excel's AutoSum does: the guess is often a row short, and the editor is
+ * where it gets corrected before Enter takes it. A wider selection has the
+ * sum written into the active cell outright.
+ */
+export declare const autoSum: SheetCommand;
+export declare const SHEET_BINDINGS: ReadonlyArray<SheetBinding>;
+/** Shift+F11 and the ribbon's Insert Sheet: a new sheet after the last, made active. */
+export declare function newSheet(): boolean;
+export declare function structural(cmd: GridCommandContext, kind: 'insert' | 'delete'): boolean;
+/**
+ * The handler registered with the grid. Returns true when a binding ran, which
+ * is what tells the grid to stop and not interpret the key itself.
+ *
+ * A binding marked `editing` runs only inside the editor and the others
+ * only outside it: Ctrl+D while someone is typing in a cell is a keystroke
+ * they meant for the text, and F4 on the grid root has nothing to pin.
+ * Alt+Enter needs no binding: the grid's multiline text editor takes it as
+ * a line break itself.
+ */
+export declare function handleSheetKey(event: KeyboardEvent, cmd: GridCommandContext): boolean;