@xlcalc/vue 0.0.0-stage → 0.21.2

package/dist/contract/source.d.ts

@@ -0,0 +1,433 @@
+/**
+ * The sheet source contract: everything the component knows about its data. Rows and columns are 1-based, cells
+ * are A1 addresses. The source displays formulas in its own locale and parses what the user typed; the component knows
+ * nothing about the engine, the formula locale or HTTP. Optional methods enable features: without `edit` the sheet
+ * is read-only, without `find` there is no search, and so on.
+ */
+import type { CellStyle, CellValue, ConditionalAppearance, FunctionSignature, NumberFormat, StructureOp, StylePatch } from 'xlcalc/contract';
+/** The sheet's data source; the component accesses its data only through this interface. */
+export interface SheetSource {
+    /** The workbook's sheets in order; read again after a structure change and on a `reload` event. */
+    sheets(signal?: AbortSignal): Promise<SheetInfo[]>;
+    /** A rectangular block of a sheet's cells (a window), at most `maxCells` cells. */
+    window(req: WindowRequest, signal?: AbortSignal): Promise<SheetWindow | SheetPending>;
+    /** An edit as typed (`=SUM(A1:A3)`, `1.5`, `'007`); `null` clears. Without it the sheet is read-only. `opts.accept`: see `EditOptions`. */
+    edit?(entries: CellEntry[], opts?: EditOptions): Promise<EditOutcome>;
+    /** Clipboard text pasted at a cell as Excel pastes it, as a single undo step; `select` is the filled range. Without it the fields go to `edit`. */
+    paste?(sheet: string, cell: string, text: string): Promise<EditOutcome>;
+    /** Ctrl+Enter: the text typed into the active cell, entered into every cell of `range`. Without it only the active cell gets it. */
+    fill?(sheet: string, range: string, text: string, active: string, opts?: EditOptions): Promise<EditOutcome>;
+    /** Undoes the workbook's last change as a whole (`ok` with no changes when there is none); `select` is where it was. Without it there is no undo. */
+    undo?(): Promise<EditOutcome>;
+    /** Redoes the last undone change. */
+    redo?(): Promise<EditOutcome>;
+    /** A structure operation; without it there is no structure menu. */
+    structure?(op: SheetOp): Promise<EditOutcome>;
+    /** Column widths and row heights set with the mouse; without it a changed width lasts until the page reloads. */
+    layout?(edit: LayoutChange): Promise<EditOutcome>;
+    /**
+     * A range's plain text as Excel puts it on the clipboard: values formatted by their number formats and not clipped to
+     * the column width (a date in a narrow column is the date, not `##`), hidden rows and columns omitted, rows ending with
+     * CRLF, the last one included unless `trailingNewline` is false (Excel for Mac). A range too large to copy is rejected
+     * with an error. Without it the sheet copies the displayed text of its windows.
+     */
+    copyText?(sheet: string, range: string, opts?: {
+        trailingNewline?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * Formats ranges (`B2:D9`, entire columns `B:D`, rows `2:5`) as a single undo step, as Excel formats a selection:
+     * style fields apply on top of each cell's displayed style (null removes a field), `style: null` removes the cells' own
+     * style, and a number format or null sets the format; several patches carry what differs by position (outside borders).
+     * Without it there is no toolbar.
+     */
+    format?(sheet: string, patches: FormatPatch[]): Promise<EditOutcome>;
+    /** Changes made elsewhere: another tab, an agent, the clock. Returns the unsubscribe function. */
+    subscribe?(listener: (event: SourceEvent) => void): () => void;
+    /** A cell's data validation as Excel displays it on the cell: its dropdown list and its input message; null when no rule applies to the cell. */
+    validation?(sheet: string, cell: string, signal?: AbortSignal): Promise<SheetValidation | null>;
+    /**
+     * An item chosen from a list rule's dropdown: item number `item` of `validation`'s `list` (with its `text`, to detect a
+     * changed list), written as Excel writes a chosen item (its value, not parsed as typed text; the cell's number format
+     * kept), without checking the rule, as a single undo step. Without it the item goes to `edit` as typed, with `accept`.
+     */
+    pick?(sheet: string, cell: string, item: number, text: string): Promise<EditOutcome>;
+    /** Excel's Freeze Panes: the rows above and the columns to the left of a cell kept in view (`{ rows: 2, cols: 1 }`), null unfreezes; a single undo step. Without it only the sheet's lock button hides the workbook's frozen panes. */
+    freeze?(sheet: string, panes: {
+        rows: number;
+        cols: number;
+    } | null): Promise<EditOutcome>;
+    /** The functions a formula can call, by their names as typed in the source's locale (`СУММ` in ru-RU), for Excel's Formula AutoComplete. */
+    functionNames?(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * A function's arguments for Excel's argument tooltip while a formula is typed (`SUM(number1, [number2], ...)`, in ru-RU
+     * `СУММ(число1;[число2];...)`): the name as typed, in English or in the source's locale, in any letter case; null for a
+     * function the source does not know. Without it there is no tooltip.
+     */
+    functionSignature?(name: string, signal?: AbortSignal): Promise<SheetFunctionSignature | null>;
+    /** A cell's precedent tree as text. */
+    explain?(sheet: string, cell: string): Promise<string>;
+    /**
+     * Excel's Ctrl+arrow from a cell (`Range.End`): the cell it goes to (`B12`), which is the end of the block of non-empty
+     * cells, the next non-empty cell, or the edge of the sheet, skipping hidden rows or columns. Without it the sheet goes to
+     * the edge of the data known to it.
+     */
+    end?(sheet: string, cell: string, direction: 'up' | 'down' | 'left' | 'right', signal?: AbortSignal): Promise<string>;
+    /** Totals of a range; without it the component counts over the loaded windows. */
+    stats?(sheet: string, range: string, filter?: SheetFilter, signal?: AbortSignal): Promise<RangeStats>;
+    /** Excel's Find on a sheet: matches in Excel's order, by rows or by columns (under a display filter, only its visible rows). Without it there is no search. */
+    find?(req: FindRequest, signal?: AbortSignal): Promise<FindResult>;
+    /** Excel's Replace All: every cell `find` finds for `req`, searched in formulas whatever `lookIn` says, as Excel replaces, with the matched text replaced by `by`, as a single undo step. */
+    replace?(req: FindRequest, by: string): Promise<ReplaceOutcome>;
+    /** Excel's outline commands: Group, Ungroup, a group's button and a level button. Without it the outline is drawn but cannot be changed. */
+    outline?(change: OutlineChange): Promise<EditOutcome>;
+    /** The sheet's rows in display order under the filter and sort; `rows: null` when there are no conditions. */
+    visibleRows?(sheet: string, filter: SheetFilter, signal?: AbortSignal): Promise<{
+        rows: number[] | null;
+    }>;
+    /** A column's values for the filter funnel, over the rows visible under the other columns' conditions. */
+    columnValues?(sheet: string, col: number, filter: SheetFilter, signal?: AbortSignal): Promise<{
+        values: {
+            text: string;
+            count: number;
+        }[];
+        more: number;
+    }>;
+    /** The maximum number of cells in one window, 20,000 by default. */
+    readonly maxCells?: number;
+    /** The number of steps `undo` and `redo` can take, as of the last completed call: a toolbar enables its buttons by them. */
+    readonly history?: {
+        readonly undo: number;
+        readonly redo: number;
+    };
+}
+/** A function's signature as returned by a source, with what Excel's Insert Function displays under the syntax: a one-line description of the function, in the source's locale. */
+export type SheetFunctionSignature = FunctionSignature & {
+    description?: string;
+};
+/** A range's formatting in `SheetSource.format`. */
+export interface FormatPatch {
+    range: string;
+    style?: StylePatch | null;
+    numberFormat?: NumberFormat | null;
+}
+/** A display filter and sort: the data do not change. */
+export interface SheetFilter {
+    /** Header rows at the top, which are never filtered. */
+    head: number;
+    cols?: Record<number, {
+        values?: string[];
+        text?: string;
+    }>;
+    sort?: {
+        col: number;
+        dir: 'asc' | 'desc';
+    };
+}
+export interface RangeStats {
+    cells: number;
+    numbers: number;
+    sum: number;
+    min: number | null;
+    max: number | null;
+}
+export interface SheetInfo {
+    name: string;
+    maxRow: number;
+    maxCol: number;
+    freeze?: {
+        rows: number;
+        cols: number;
+    };
+    /** Not shown on the tabs; `very` (xlsx's veryHidden) is also not offered for Unhide, since Excel never offers it. */
+    hidden?: boolean | 'very';
+    /** Ranges that cannot be edited, with the reason for a tooltip (for example, ranges managed by a script). */
+    locked?: {
+        range: string;
+        reason: string;
+    }[];
+    /** List mode: column titles in the header instead of letters; `sortable` makes a header click sort. */
+    columns?: {
+        title: string;
+        align?: 'left' | 'center' | 'right';
+        sortable?: boolean;
+    }[];
+    /** Row numbers on the left, shown by default; a list has none. */
+    rowNumbers?: boolean;
+    /** A totals row pinned to the bottom: the displayed text for each of the sheet's columns (null: empty). */
+    totals?: (string | null)[];
+    /** Excel's outline (Data > Group): the sheet's groups of rows and columns; a sheet without groups has none. */
+    outline?: SheetOutline;
+}
+/** A sheet's groups as Excel draws them in the bars next to the row numbers and above the column letters. */
+export interface SheetOutline {
+    /** Groups of rows by their first row, the outer group before the inner one when both start on the same row. */
+    rows: OutlineGroup[];
+    columns: OutlineGroup[];
+    /** A group's summary row, which holds its button, is below it (Excel's default) or above it. */
+    summaryBelow: boolean;
+    /** A group's summary column is to the right of it (Excel's default) or to the left of it. */
+    summaryRight: boolean;
+}
+/**
+ * A group: the rows or columns `from`..`to` (columns by number) at outline level `level` or deeper, with no such row
+ * or column adjacent to them; `level` is 1 to 7, so every row or column inside a level-2 group is also inside a level-1
+ * group. `collapsed`: its rows or columns are hidden and its button shows +.
+ */
+export interface OutlineGroup {
+    from: number;
+    to: number;
+    level: number;
+    collapsed: boolean;
+}
+/**
+ * Excel's outline commands on a sheet, each a single undo step: Group and Ungroup move entire rows or columns one level
+ * deeper or shallower (`rows: '3:6'`, `columns: 'B:D'`); collapse and expand are a group's button (Excel's Hide Detail
+ * and Show Detail), with the group identified by its rows or columns and level as `SheetOutline` returns it; `showLevel`
+ * is a level button: groups at `level` and deeper are collapsed, shallower ones expanded, and one past the deepest level
+ * expands all.
+ */
+export type OutlineChange = {
+    op: 'group' | 'ungroup';
+    sheet: string;
+    rows: string;
+} | {
+    op: 'group' | 'ungroup';
+    sheet: string;
+    columns: string;
+} | {
+    op: 'collapse' | 'expand';
+    sheet: string;
+    rows: string;
+    level: number;
+} | {
+    op: 'collapse' | 'expand';
+    sheet: string;
+    columns: string;
+    level: number;
+} | {
+    op: 'showLevel';
+    sheet: string;
+    axis: 'rows' | 'columns';
+    level: number;
+};
+/** What Excel's Find searches for and where, as set by the options of its dialog. */
+export interface FindRequest {
+    sheet: string;
+    /** The text to find; `*` matches any characters, `?` one character, and `~` before either of them or before itself matches that character, as in Excel. */
+    query: string;
+    /** Only within this range, as Excel searches within a selection of more than one cell; the entire sheet without it. */
+    range?: string;
+    /** Match case; without it the case is ignored. */
+    matchCase?: boolean;
+    /** Match entire cell contents: the entire text matches the query, not a part of it. */
+    wholeCell?: boolean;
+    /** Look in: the text a cell opens with for editing (formulas as typed in the workbook's locale, Excel's default) or its displayed text. */
+    lookIn?: 'formulas' | 'values';
+    /** Search by columns: matches column by column; row by row without it. */
+    byColumns?: boolean;
+    /**
+     * Find Next from this cell (`B12`), as Excel's Find continues from the active cell (`Range.Find`'s After): the matches in
+     * Find's order starting from the first one after it, wrapping around at the end, with the cell itself last. Without it they
+     * start from the range's first cell. A source that does not support it returns them from the first cell, and Find Next
+     * moves through the matches it returned.
+     */
+    after?: string;
+    /** The display filter in effect: only its visible rows are searched. */
+    filter?: SheetFilter;
+}
+/** The matches of a search, at most as many as the source returns in one response; `total` counts them all. */
+export interface FindResult {
+    hits: {
+        row: number;
+        col: number;
+    }[];
+    total: number;
+}
+/**
+ * The outcome of Replace All and how many cells it changed (Excel's "We made N replacements"); `refused`: the cells whose
+ * new text Excel would not accept (a formula that no longer parses), left unchanged while the others are written, with the
+ * reason.
+ */
+export type ReplaceOutcome = EditOutcome & {
+    replaced: number;
+    refused?: {
+        sheet: string;
+        cell: string;
+        message: string;
+    }[];
+};
+/** With a filter, `row` is a display index (a position among the visible rows). */
+export interface WindowRequest {
+    sheet: string;
+    row: number;
+    rows: number;
+    col: number;
+    cols: number;
+    filter?: SheetFilter;
+}
+export interface SheetWindow {
+    row: number;
+    col: number;
+    /** Displayed text, the window's rows × columns; an empty cell is ''. */
+    text: string[][];
+    /** Values of the same cells, used for selection totals and alignment. */
+    values: CellValue[][];
+    /** Formulas by address as they are displayed and edited (in the source's locale), without `=`. */
+    formulas: Record<string, string>;
+    /** The text each cell opens with for editing, as Excel's formula bar displays it; a cell missing from it opens empty. Without it the component produces the text from the value and the formula. */
+    editText?: Record<string, string>;
+    /** The color from the number format's section (`#RRGGBB`). */
+    colors: Record<string, string>;
+    styleIds: Record<string, number>;
+    styles: CellStyle[];
+    /** The number format code each cell is displayed with (its own, otherwise its row's or column's); a cell missing from it is General. For a toolbar. */
+    numberFormats?: Record<string, string>;
+    /** The window's column widths (in the units of xlcalc's `ColumnInput.width`, null for the default), row heights in points. */
+    widths: (number | null)[];
+    rowHeights: Record<number, number>;
+    merges: string[];
+    /** The default row height in points. */
+    defaultRowHeight?: number;
+    /** The sheet's tables, from which their header and border are drawn. */
+    tables?: {
+        name: string;
+        range: string;
+        headerRow: number;
+    }[];
+    /** The cells' conditional formatting as xlcalc calculates it: a style on top of the cell's own, a data bar, an icon, a hidden value. */
+    appearance?: Record<string, ConditionalAppearance>;
+    /** Hyperlinks: an external address, a location in the workbook (`Sheet!B12`), a tooltip, a host-specific target (such as a file of the host). */
+    links?: Record<string, {
+        href?: string;
+        location?: string;
+        tooltip?: string;
+        target?: string;
+    }>;
+    notes?: Record<string, {
+        author?: string;
+        text: string;
+    }>;
+    /** A notice above the grid (for example, "values calculated on the server"). */
+    notice?: string;
+    /** Drill-down cells (list mode): underlined, and a click or Enter emits `cellDrill`. */
+    drill?: Record<string, true>;
+}
+/** The window is not ready yet (the host's workbook is recalculating): the component waits and requests it again. */
+export interface SheetPending {
+    pending: {
+        elapsedMs: number;
+    };
+}
+export interface CellEntry {
+    sheet: string;
+    cell: string;
+    text: string | null;
+}
+/** Options of an edit. */
+export interface EditOptions {
+    /** The user kept a value the cell's rule rejects, with Yes on a warning or OK on an information alert: write it without checking the rule again. */
+    accept?: true;
+    /** The text was edited starting from the cell's own text (F2, a double click, the formula bar), not typed over the cell: Excel's automatic percentage entry then adds no `%` (`6%` in a `0%` cell is 0.06). */
+    inPlace?: true;
+}
+/** A cell's data validation as the user sees it: Excel's dropdown of a list rule and the message displayed while the cell is selected. */
+export interface SheetValidation {
+    /** A list rule that shows its dropdown: the items as text, in order; empty when its formula returns none. */
+    list?: string[];
+    /** The input message (in Excel, a title of up to 32 characters and text of up to 255). */
+    prompt?: {
+        title?: string;
+        text: string;
+    };
+}
+/** A data validation rule's alert for a value that violates it, as Excel displays it: stop (Retry, Cancel), warning (Continue? Yes, No, Cancel), information (OK, Cancel). */
+export interface SheetValidationAlert {
+    severity: 'stop' | 'warning' | 'information';
+    /** The rule's title, otherwise the component's default ("Microsoft Excel"). */
+    title?: string;
+    /** The rule's message, otherwise the source's description of the rule. */
+    message: string;
+    /** The cell where the value was rejected. */
+    sheet: string;
+    cell: string;
+}
+export type SheetOp = Exclude<StructureOp, {
+    op: 'addTable' | 'renameTable' | 'deleteTable' | 'convertTable';
+}>;
+/** Columns or rows changed: a width or height set with the mouse, rows or columns hidden or unhidden, columns or rows fitted to their contents (Excel's double click on an edge). */
+export type LayoutChange = {
+    sheet: string;
+    columns: string;
+    width?: number;
+    hidden?: boolean;
+    fit?: true;
+} | {
+    sheet: string;
+    rows: string;
+    height?: number;
+    hidden?: boolean;
+    fit?: true;
+};
+export type EditOutcome = {
+    ok: true;
+    changes: CellUpdate[];
+    /** Where the selection goes after `paste`, `fill`, `undo` or `redo`: the range they filled or restored; `edit` returns none (the active cell has already moved). */
+    select?: {
+        sheet: string;
+        range: string;
+    };
+} | {
+    ok: false;
+    /**
+     * conflict: the workbook changed elsewhere; refused: the cell is locked or the operation is not allowed;
+     * invalid: the formula does not parse (`at` is the position in the typed text); failed: anything else.
+     */
+    reason: 'conflict' | 'refused' | 'invalid' | 'failed';
+    message: string;
+    /**
+     * The source's code for the reason, for a host that reacts to it rather than to the text. `memorySource` and
+     * `@xlcalc/vue/local` give xlcalc's codes: an outline command's `outline_deep`, `not_grouped` or `detail`, and in
+     * `./local` the code of any structure operation xlcalc refuses.
+     */
+    code?: string;
+    at?: number;
+    /**
+     * For `invalid`: the formula Excel suggests instead in its "We found a typo in your formula" dialog, in the source's
+     * locale (unclosed parentheses closed, `=(1+2` → `=(1+2)`); the component offers to accept it and sends the edit again with it.
+     */
+    correction?: string;
+    /** A value that violates a data validation rule (`refused`): the component displays Excel's alert, and sends the edit again with `accept` after Yes on a warning or OK on an information alert. */
+    alert?: SheetValidationAlert;
+};
+/** A cell's new state after an edit or a recalculation. */
+export interface CellUpdate {
+    sheet: string;
+    cell: string;
+    text: string;
+    value: CellValue;
+    color?: string;
+    /** Only for edited cells: the formula as displayed, or null when the cell no longer has one. */
+    formula?: string | null;
+    /** Only for edited cells, from a source whose windows have `editText`: the text the cell now opens with for editing. */
+    editText?: string;
+    /** Only for edited cells, from a source whose windows have `numberFormats`: the format code the cell is now displayed with (null: General), as when a typed date sets one. */
+    numberFormat?: string | null;
+}
+export type SourceEvent = {
+    kind: 'changed';
+    changes: CellUpdate[];
+}
+/** Many or unknown things changed: read the sheets and windows again. */
+ | {
+    kind: 'reload';
+    message?: string;
+}
+/** Cells in these ranges may look different (conditional formats): windows that overlap them are re-read in place, keeping the sheets, sizes and display filter as they are. */
+ | {
+    kind: 'repaint';
+    ranges: {
+        sheet: string;
+        range: string;
+    }[];
+};

package/dist/contract/view.d.ts

@@ -0,0 +1,108 @@
+import type { CellStyle } from 'xlcalc/contract';
+import type { SheetMessages } from './messages.js';
+import type { EditOutcome, FormatPatch, OutlineChange, SheetOp, SheetSource, SheetWindow } from './source.js';
+/** Properties of `SheetView`. */
+export interface SheetViewProps {
+    source: SheetSource;
+    /** Interface texts; a partial set overrides the English defaults. */
+    messages?: Partial<SheetMessages>;
+    /** Key in the browser's storage for the frozen panes display choice and column widths; without it they last as long as the component. */
+    storageKey?: string;
+    /** A location to show: `Sheet!B12:D15`, `B7`, `Sheet`; each new object is a new jump. */
+    focus?: {
+        ref: string;
+    } | null;
+    /** The host page's address for a location; without it there is no "Link to the cell" button. */
+    cellUrl?: (ref: string) => string;
+    readOnly?: boolean;
+    /** Shows the formula bar above the grid; on by default. */
+    formulaBar?: boolean;
+    /** The workbook's locale for texts the component produces itself: a cell's edit text without `editText`, and selection totals. */
+    locale?: string;
+    /** Hides the tabs of a workbook with a single sheet, for hosts that want it; Excel always shows them, which is the default. */
+    hideLoneTab?: boolean;
+    /** Double-clicking a column edge restores the workbook's width, for hosts that want it; by default it fits the columns to their contents, as Excel does. */
+    edgeRestoresWidth?: boolean;
+    /** List mode: the order the host sorted the list in, shown as an arrow on the column's title; null for none. */
+    sort?: ListSort | null;
+    /** List mode: the first column opens its row (`rowOpen`), and so does Enter on a cell that is not a drill-down. */
+    openRows?: boolean;
+    /** The host opens links itself through `openLink`: for a host whose listener the component cannot see, such as a custom element's. */
+    hostLinks?: boolean;
+}
+/** Why the workbook cannot be displayed: the source's error and its text. */
+export interface SheetFailure {
+    error: unknown;
+    text: string;
+}
+/** What `state` reports: the sheet, the selection, and the active cell's formula and displayed value. */
+export interface SheetViewState {
+    sheet: string;
+    ref: string;
+    formula?: string;
+    value?: string;
+    /** The active cell's style, for a toolbar; absent while its window is not loaded or when it has none. */
+    style?: CellStyle;
+    /** The active cell's number format code, from a source whose windows include them; absent for General. */
+    numberFormat?: string;
+    /** The merged range containing the active cell (`A1:B2`), from the loaded windows: Excel's Merge & Center shows as pressed on it. */
+    merged?: string;
+    /** The merge commands are available (`SheetViewApi.merge`): the source has `structure`, the sheet is editable, and no display filter is on. */
+    canMerge?: true;
+}
+/** A hyperlink the component does not open itself, with the cell it belongs to. */
+export type SheetLinkEvent = NonNullable<SheetWindow['links']>[string] & {
+    sheet: string;
+    cell: string;
+};
+/**
+ * What `SheetView` exposes to its host (through a template `ref`): changes made as the sheet's own keyboard commands make
+ * them, with the outcome's selection set without a flash or a Back history entry. Each method resolves to the source's
+ * outcome, or to null when nothing was sent (the source lacks the method, the sheet is read-only, or an undo is pending).
+ */
+export interface SheetViewApi {
+    undo(): Promise<EditOutcome | null>;
+    redo(): Promise<EditOutcome | null>;
+    /** Formats the active sheet in one call to the source's `format`. */
+    format(patches: SheetFormatPatch[]): Promise<EditOutcome | null>;
+    /** A structure operation through the source; the sheet displayed afterwards is the one Excel displays. */
+    structure(op: SheetOp): Promise<EditOutcome | null>;
+    /** An outline command through the source (Group, Ungroup, a group's button, a level button); the sheet reloads afterwards. */
+    outline(change: OutlineChange): Promise<EditOutcome | null>;
+    /** Opens Excel's Format Cells dialog (Ctrl+1) for the selection, with the active cell's formatting; false when the sheet cannot be formatted. */
+    formatCells(): boolean;
+    /**
+     * Excel's Freeze Panes through the source's `freeze`, as a single undo step, after which the sheet reloads: `panes` (the
+     * default) keeps the rows above and the columns to the left of the active cell in view (with A1 active, the middle of the
+     * viewport, where Excel splits it), `unfreeze` removes the workbook's panes, `topRow` and `firstColumn` freeze one row or
+     * column. Frozen panes are displayed whatever the lock button's earlier state; null when nothing was sent (no `freeze`,
+     * a read-only sheet, nothing to freeze or unfreeze).
+     */
+    freezePanes(mode?: FreezeMode): Promise<EditOutcome | null>;
+    /** Excel's Reapply (Ctrl+Alt+L): applies the display filter's conditions and sort again to the current data; false when no filter is on. */
+    reapplyFilter(): Promise<boolean>;
+    /** Excel's Trace Precedents as a panel next to the grid: the source's tree of the active cell's precedents, following the active cell; false if the source has no `explain`. */
+    explain(): boolean;
+    /**
+     * Excel's Merge & Center (`mergeCenter`), Merge Across, Merge Cells and Unmerge Cells over the selection through the
+     * source's `structure`, as a single undo step, with Excel's warning first when more than one cell would lose its value. null
+     * when nothing was sent: no `structure`, a read-only sheet, a display filter, a single cell outside a merged range, or Cancel
+     * in the warning.
+     */
+    merge(command: MergeCommand): Promise<EditOutcome | null>;
+}
+/** A patch for `SheetView.format`: applied to its own range, or to the selection without one. */
+export type SheetFormatPatch = Omit<FormatPatch, 'range'> & {
+    range?: string;
+};
+/** Excel's Freeze Panes commands: the panes of the active cell, Unfreeze Panes, Freeze Top Row, Freeze First Column. */
+export type FreezeMode = 'panes' | 'unfreeze' | 'topRow' | 'firstColumn';
+/** Excel's merge commands: Merge & Center on the button, and Merge Across, Merge Cells and Unmerge Cells in its dropdown. */
+export type MergeCommand = 'mergeCenter' | 'mergeAcross' | 'mergeCells' | 'unmergeCells';
+/** The order a list is sorted in, by a column of the sheet (1-based): the host sorts, and the sheet shows the arrow. */
+export interface ListSort {
+    col: number;
+    dir: 'asc' | 'desc';
+}
+/** The source the toolbar formats through: a `SheetSource`, whose `history` tells whether Undo and Redo have a step. */
+export type ToolbarSource = SheetSource;

package/dist/contract.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The package's contract: every public type, in modules by area, with no code. `source` is the sheet source contract a
+ * host implements, `view` the sheet's props, state, events and methods, `memory` memorySource's types, `messages` the
+ * interface texts' keys. The `@xlcalc/vue/local` entry's types are in src/local/types.ts.
+ */
+export type * from './contract/source.js';
+export type * from './contract/view.js';
+export type * from './contract/memory.js';
+export type * from './contract/messages.js';

package/dist/core/ask.d.ts

@@ -0,0 +1,2 @@
+/** Calls `call` with a new controller's signal; `take` or `fail` run only while `live()` holds. Returns the controller, to abort it. */
+export declare function askSource<T>(call: (signal: AbortSignal) => Promise<T>, live: () => boolean, take: (value: T) => void, fail: () => void): AbortController;

package/dist/core/autocomplete.d.ts

@@ -0,0 +1,28 @@
+import { type Ref } from 'vue';
+import type { ScanOptions } from 'xlcalc/contract';
+import type { SheetSource } from '../contract/source.js';
+import type { EditorState } from './editing.js';
+/** Items the list displays at once; Page Up and Page Down move by them. */
+export declare const FUNCTION_ROWS = 8;
+export interface AutocompleteDeps {
+    source: () => SheetSource;
+    editor: Ref<EditorState | null>;
+    /** The open editor's element, for its caret. */
+    input: () => HTMLTextAreaElement | null;
+    /** Shows the draft's new text with its caret in the editor. */
+    show: () => void;
+    /** How the workbook's formula text is parsed (its list separator); null while its locale loads. */
+    scan: () => ScanOptions | null;
+}
+/** The list's state over the editor's draft: what it displays, the highlighted item, the keys it handles, the name it inserts. */
+export declare function useAutocomplete(deps: AutocompleteDeps): {
+    items: import("vue").ShallowRef<readonly string[], readonly string[]>;
+    index: Ref<number, number>;
+    open: import("vue").ComputedRef<boolean>;
+    update: (text: string, caret: number | null) => void;
+    follow: () => void;
+    accept: (i?: number) => boolean;
+    close: () => void;
+    onKey: (e: KeyboardEvent) => boolean;
+};
+export type Autocomplete = ReturnType<typeof useAutocomplete>;

package/dist/core/cell-style.d.ts

@@ -0,0 +1,33 @@
+import type { BorderLine, CellStyle, CellValue } from 'xlcalc/contract';
+export type Horizontal = 'left' | 'center' | 'right' | 'fill' | 'justify' | 'distributed' | 'centerContinuous';
+export type Vertical = 'top' | 'center' | 'bottom';
+/** Excel's General alignment by value: numbers right, text left, booleans and errors centered. */
+export declare function generalAlign(value: CellValue | undefined): 'left' | 'center' | 'right';
+/** A cell's displayed horizontal alignment. */
+export declare function horizontalOf(style: CellStyle | undefined, value: CellValue | undefined): Horizontal;
+/** A cell's displayed vertical alignment; Excel's default is bottom. */
+export declare function verticalOf(style: CellStyle | undefined): Vertical;
+/** Whether the text wraps: by the style, and always for justify and distributed, as Excel does. */
+export declare function wrapsOf(style: CellStyle | undefined): boolean;
+/** The line width in pixels of an xlsx border style. */
+export declare function borderWidth(line: BorderLine | undefined): number;
+/** A CSS line: width, style and color, set as longhands (a shorthand with var() is not parsed everywhere). */
+export interface CssLine {
+    width: string;
+    style: string;
+    color: string;
+}
+/** An xlsx border line as a CSS line; CSS has no dash-dot, so those are dashed. Without a color: Excel's automatic. */
+export declare function borderCss(line: BorderLine | undefined): CssLine | undefined;
+/** Puts a line on one side of a cell's CSS. */
+export declare function setSide(css: Record<string, string>, side: 'Top' | 'Right' | 'Bottom' | 'Left', line: CssLine): void;
+/** A cell's font, color and fill; `section` is the color from the number format's section, which takes precedence over the font's. */
+export declare function fontCss(style: CellStyle | undefined, section: string | undefined): Record<string, string>;
+/** Underline and strikethrough, for the element that holds the text: decorations do not reach an absolutely positioned overflow run. A link is underlined anyway. */
+export declare function decorationCss(style: CellStyle | undefined, link: boolean): Record<string, string>;
+/** Content box alignment: CSS for the box that holds the text, by horizontal and vertical alignment and indent. */
+export declare function alignCss(h: Horizontal, indent: number): Record<string, string>;
+/** Excel's Fill alignment repeats the text across the cell: enough copies to cover its width, with the rest clipped. */
+export declare function fillText(text: string, widthPx: number): string;
+/** Whether a value's text may overflow into empty neighbors: only text does, as in Excel. */
+export declare const overflows: (value: CellValue | undefined) => boolean;