@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/shortcuts.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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): 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 = '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' | 'merge-center' | 'merge-across' | 'merge-cells' | 'unmerge-cells';
+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 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+=. Inserts =SUM(range) over the run Excel would guess. */
+export declare const autoSum: SheetCommand;
+export declare const SHEET_BINDINGS: ReadonlyArray<SheetBinding>;
+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;