ng-hub-ui-spreadsheet 22.0.0

package/types/ng-hub-ui-spreadsheet.d.ts

@@ -0,0 +1,1958 @@
+import * as ng_hub_ui_utils from 'ng-hub-ui-utils';
+import { HubGridCoords, HubGridRange, HubGridSpan, HubGridWindow } from 'ng-hub-ui-utils';
+import * as _angular_core from '@angular/core';
+import { TemplateRef, ViewContainerRef, EnvironmentProviders, InjectionToken, OnDestroy } from '@angular/core';
+
+/**
+ * The vocabulary of a spreadsheet: what a column declares, what a cell shows, and what the sheet
+ * hands back when something changes.
+ *
+ * The sheet knows nothing about what the values mean. The owner describes the columns, keeps
+ * whatever save state it wants, and does the writing when the sheet reports a change. That split
+ * is what lets the same component serve an invoice, a price list and a timesheet.
+ */
+/**
+ * How a column shows its values and reads back what is typed into it.
+ *
+ * `select` is the one that changes behaviour rather than formatting: a column with a closed list
+ * of answers typed by hand accepts things that are not on the list, and checking afterwards is
+ * too late.
+ */
+type HubSpreadsheetValueKind = 'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select';
+/** One answer a `select` column offers. */
+interface HubSpreadsheetOption {
+    /** What is stored. */
+    readonly value: HubSpreadsheetValue;
+    /** What is shown, both in the cell and in the list. */
+    readonly label: string;
+    /** Listed but not choosable — a value being retired, say, that old rows still hold. */
+    readonly disabled?: boolean;
+}
+/**
+ * Where a cell's save stands.
+ *
+ * `pending` is a value typed into a sheet that is saved as a whole later: written, not yet sent.
+ * `conflict` is somebody else's write landing on a cell this session had already changed.
+ */
+type HubSpreadsheetCellState = 'pending' | 'saving' | 'saved' | 'error' | 'conflict';
+/** A value as the sheet carries it; null is an empty cell, not a zero. */
+type HubSpreadsheetValue = string | number | null;
+/** What a single cell shows and allows, worked out by its column from the row. */
+interface HubSpreadsheetCell {
+    /** What the cell holds. */
+    readonly value: HubSpreadsheetValue;
+    /**
+     * What to show instead of the value.
+     *
+     * For a cell whose display differs from its data — a code shown as a name, a number shown
+     * with a unit. The clipboard still carries `value`, so a copy round-trips the data and not
+     * the decoration.
+     */
+    readonly text?: string | null;
+    /** A second, quieter line under the value. */
+    readonly secondary?: string | null;
+    /** Whether the cell can be typed into. Read-only when left out. */
+    readonly editable?: boolean;
+    /** Shown in a quieter tone, for a value that comes from somewhere else. */
+    readonly muted?: boolean;
+    /** Said when the pointer rests on the cell. */
+    readonly title?: string | null;
+}
+/**
+ * One column of a sheet.
+ *
+ * Note the two identities, and that they are not interchangeable. `key` is what everything stored
+ * points at — the save state, the structured output, and later the formulas. `header` is what a
+ * reader sees and may be rewritten at any time without touching a single stored reference. Making
+ * the visible name the key is the mistake Excel made: rename a column there and every formula in
+ * the workbook has to be rewritten to match.
+ */
+interface HubSpreadsheetColumn<TRow> {
+    /** Stable identifier, unique within the sheet. Never shown to the reader. */
+    readonly key: string;
+    /** The header text, or a translation key when `translate` is set. */
+    readonly header: string;
+    /** Resolves `header` through the translation system instead of printing it literally. */
+    readonly translate?: boolean;
+    /** A second, smaller line under the header. */
+    readonly subheader?: string | null;
+    /** How values are shown and parsed. Text when left out. */
+    readonly kind?: HubSpreadsheetValueKind;
+    /** Currency code for a `currency` column; the application's own when left out. */
+    readonly currency?: string | null;
+    /**
+     * The answers a `select` column offers, in the order they are listed.
+     *
+     * A cell shows the matching option's label rather than its stored value, and falls back to
+     * the raw value when nothing matches — an old row holding a value that has since been retired
+     * has to remain readable, not blank.
+     */
+    readonly options?: readonly HubSpreadsheetOption[];
+    /** Figures go to the end, so they read down the column. */
+    readonly align?: 'start' | 'center' | 'end';
+    /** A floor for the column's width, as a CSS length. */
+    readonly minWidth?: string;
+    /**
+     * A hint shown in an empty cell of this column while the pointer rests on it.
+     *
+     * Only on hover, and never in place of a value: a column of hints reads as a column of
+     * content, and a reader scanning for what is filled in would have to look twice at every row.
+     */
+    readonly placeholder?: string;
+    /**
+     * Keeps the header readable by assistive technology but hides it from sight, for a column
+     * whose cells explain themselves and need no name repeated down every row.
+     */
+    readonly headerHidden?: boolean;
+    /**
+     * A formula every cell of this column is worked out from, fixed by whoever declared it.
+     *
+     * The other way round from a formula a reader types: that one is a value the row holds and can
+     * be changed like any other, while this one belongs to the column and is the same in every
+     * row. A total that is part of how the sheet works — a line total, a running balance — belongs
+     * here, where nobody can type over it by accident and no round trip through the data can lose
+     * it.
+     *
+     * The cells of such a column cannot be typed into; their `editable` is ignored, since there is
+     * nothing to edit. Needs `formulas` on the sheet, as any formula does.
+     */
+    readonly formula?: string;
+    /** What this column shows for a given row. */
+    readonly cell: (row: TRow) => HubSpreadsheetCell;
+}
+/** A cell as the sheet hands it to its owner. */
+interface HubSpreadsheetCellRef<TRow> {
+    /** Where it sits. */
+    readonly coords: HubGridCoords;
+    /** The row it belongs to. */
+    readonly row: TRow;
+    /** The column it belongs to. */
+    readonly column: HubSpreadsheetColumn<TRow>;
+    /** What it showed when the event happened. */
+    readonly cell: HubSpreadsheetCell;
+}
+/** A value typed or pasted into a cell, already read as a number where the column is one. */
+interface HubSpreadsheetCommit<TRow> extends HubSpreadsheetCellRef<TRow> {
+    /** The new value; null when the cell was emptied. */
+    readonly value: HubSpreadsheetValue;
+}
+/**
+ * A block pasted into the sheet, and what did not fit.
+ *
+ * The counts matter: a paste that silently drops half its values is the complaint every grid in
+ * this field collects, so the owner is told how much fell on read-only cells and how much did not
+ * read as a number, and can say so.
+ */
+interface HubSpreadsheetPaste<TRow> {
+    /** The cells that take a new value. */
+    readonly cells: readonly HubSpreadsheetCommit<TRow>[];
+    /** The rectangle the paste covered, trimmed to the sheet. */
+    readonly range: HubGridRange;
+    /** Values that landed on cells that cannot be typed into, or outside the sheet. */
+    readonly skipped: number;
+    /** Values that did not read as a number in a figure column. */
+    readonly rejected: number;
+}
+/**
+ * A row of the sheet as plain data, keyed by column alias.
+ *
+ * This is what the aliases buy: the owner gets `{ price: 12, quantity: 3 }` rather than a grid of
+ * coordinates it has to map back by position.
+ */
+type HubSpreadsheetRecord = Record<string, HubSpreadsheetValue>;
+
+/**
+ * Reading a sheet back as plain data, keyed by column alias.
+ *
+ * The point of the aliases: the owner works with `{ price: 12, units: 3 }` instead of mapping a
+ * grid of coordinates back onto its own fields by position, which breaks the moment a column
+ * moves.
+ *
+ * These read the value a column reports, never the text it decides to display, so a cell showing
+ * «120 ud.» still yields the number 120.
+ */
+/** One row as plain data. */
+declare function spreadsheetRecord<TRow>(row: TRow, columns: readonly HubSpreadsheetColumn<TRow>[]): HubSpreadsheetRecord;
+/** Every row as plain data, in the order the sheet holds them. */
+declare function spreadsheetRecords<TRow>(rows: readonly TRow[], columns: readonly HubSpreadsheetColumn<TRow>[]): HubSpreadsheetRecord[];
+/**
+ * The aliases declared more than once, each named a single time.
+ *
+ * A repeated alias is not a cosmetic problem: the later column silently overwrites the earlier
+ * one in every structured read, and once formulas arrive the reference becomes ambiguous. The
+ * sheet reports this rather than guessing which column was meant.
+ */
+declare function duplicateColumnKeys<TRow>(columns: readonly HubSpreadsheetColumn<TRow>[]): string[];
+
+/**
+ * Reading and writing the clipboard the way spreadsheets actually use it.
+ *
+ * Two flavours travel together. `text/plain` is tab-separated and carries what the source
+ * *displayed*, formatted in the source's own locale — so a figure copied from Excel in Spain
+ * arrives as `1.234,56 €`. `text/html` is where the raw number travels, in an attribute, and is
+ * the only place a value can be read back without guessing which convention wrote it.
+ *
+ * Reading only the plain text is the bug this module exists to avoid.
+ */
+/** A cell as it came off the clipboard. */
+interface HubClipboardCell {
+    /** What the source displayed. */
+    readonly text: string;
+    /** The underlying number, when the source declared one. */
+    readonly raw?: number;
+}
+/** The two flavours a paste may carry. */
+interface HubClipboardPayload {
+    readonly text?: string;
+    readonly html?: string;
+}
+/** Both flavours of a copy, ready to be put on the clipboard. */
+interface HubClipboardWrite {
+    readonly text: string;
+    readonly html: string;
+}
+/**
+ * Reads a number out of text written in the reader's convention.
+ *
+ * Deliberately three-valued: a number, `null` for an empty cell — which is an absence and not a
+ * zero — and `undefined` for text that is not a number at all, so a caller can refuse a paste
+ * instead of silently writing NaN.
+ *
+ * @param text The text as typed or as pasted.
+ * @param decimalMark Which character separates the decimals for this reader.
+ */
+declare function parseDecimal(text: string, decimalMark: ',' | '.'): number | null | undefined;
+/**
+ * Parses a pasted block into a table of cells.
+ *
+ * The plain text decides the shape, because it is the only flavour guaranteed to be there and to
+ * be complete. The HTML, when present and parseable, is read alongside it purely to recover raw
+ * numbers.
+ */
+declare function parseClipboardTable(payload: HubClipboardPayload): HubClipboardCell[][];
+/**
+ * Writes a block of values as both flavours.
+ *
+ * Numbers go into the plain text with a dot and no grouping, which every spreadsheet reads
+ * whatever its reader has configured, and into the HTML as `x:num`, which is what lets another
+ * instance of this component — or Excel — recover the exact value rather than re-parsing a
+ * formatted string.
+ */
+declare function serialiseClipboardTable(rows: readonly (readonly HubSpreadsheetValue[])[]): HubClipboardWrite;
+
+/**
+ * Adding and removing rows and columns while the sheet is running.
+ *
+ * The sheet never mutates anything itself. It reports what the reader asked for and the owner
+ * decides, because only the owner knows whether a line may be deleted, what a new row should
+ * start with, or whether any of it should reach a server. What the sheet does offer is the two
+ * pieces that are easy to get wrong: allocating an alias for a new column, and finding out what
+ * a deletion would leave pointing at nothing.
+ */
+/** Which axis a structural change acts on. */
+type HubSpreadsheetAxis = 'row' | 'column';
+/** Where a new row or column goes, relative to the one the reader pointed at. */
+type HubSpreadsheetInsertSide = 'before' | 'after';
+/**
+ * Whether a structural change is offered at all.
+ *
+ * A plain boolean covers the usual case. A predicate covers the rest: a tariff sheet that lets
+ * you add lines but never delete the first one, a column set where only the ones the reader
+ * created may be removed.
+ */
+type HubSpreadsheetPermission<TSubject> = boolean | ((subject: TSubject, index: number) => boolean);
+/** The reader asked to insert. */
+interface HubSpreadsheetInsertRequest {
+    readonly axis: HubSpreadsheetAxis;
+    /** Where the new one lands, already resolved to an index. */
+    readonly at: number;
+    /** How many to insert. */
+    readonly count: number;
+    /** For a column, an alias that is free and has never been used in this sheet. */
+    readonly key?: string;
+}
+/** The reader asked to delete. */
+interface HubSpreadsheetDeleteRequest {
+    readonly axis: HubSpreadsheetAxis;
+    /** The first index to remove. */
+    readonly at: number;
+    /** How many to remove. */
+    readonly count: number;
+    /**
+     * For a column, the aliases about to disappear.
+     *
+     * Handed over so the owner can check what still points at them before agreeing — see
+     * {@link danglingColumnKeys}.
+     */
+    readonly keys?: readonly string[];
+}
+/** How a sheet is allowed to change shape. Everything is refused unless turned on. */
+interface HubSpreadsheetStructureOptions<TRow> {
+    readonly insertRows?: HubSpreadsheetPermission<TRow | null>;
+    readonly deleteRows?: HubSpreadsheetPermission<TRow>;
+    readonly insertColumns?: HubSpreadsheetPermission<HubSpreadsheetColumn<TRow> | null>;
+    readonly deleteColumns?: HubSpreadsheetPermission<HubSpreadsheetColumn<TRow>>;
+}
+/**
+ * Whether a permission lets this particular subject through.
+ *
+ * Silence means no. A sheet that gains the ability to delete rows because an option was left out
+ * is a worse failure than one that refuses until told otherwise.
+ *
+ * A predicate that throws is treated as a refusal: the owner's guard is broken, and acting on a
+ * broken guard is how data gets deleted that should not have been.
+ */
+declare function isStructureAllowed<TSubject>(permission: HubSpreadsheetPermission<TSubject> | undefined, subject: TSubject, index: number): boolean;
+/**
+ * Where an insertion actually lands.
+ *
+ * @param reference The row or column the reader pointed at.
+ * @param side Whether the new one goes before it or after it.
+ * @param length How many there are now.
+ * @returns An index between 0 and `length`, inclusive, since appending at the end is legal.
+ */
+declare function resolveInsertIndex(reference: number, side: HubSpreadsheetInsertSide, length: number): number;
+/**
+ * An alias for a new column that has never belonged to another one.
+ *
+ * Pass every alias the sheet has ever handed out, the live ones and the retired ones together.
+ * That is the whole point: an alias is an identity, so reusing a deleted column's name makes
+ * everything that referenced the old column silently resolve to the new one, and the mistake
+ * surfaces much later as wrong numbers rather than as an error.
+ *
+ * The same rule the project already applies to task codes, for the same reason.
+ *
+ * @param taken Every alias ever used, whether the column still exists or not.
+ * @param prefix The family to number within; `col` when not given.
+ */
+declare function nextColumnKey(taken: Iterable<string>, prefix?: string): string;
+/**
+ * The references that no longer resolve to a column.
+ *
+ * Give it whatever points at columns — the keys of a saved-state map, the aliases a formula
+ * mentions — and it reports which of them have nothing behind them any more. Each one named
+ * once, in the order first seen, so a message to the reader lists them the way they were found.
+ */
+declare function danglingColumnKeys<TRow>(referenced: Iterable<string>, columns: readonly HubSpreadsheetColumn<TRow>[]): string[];
+
+/** What an editor template is handed when it opens. */
+interface HubSpreadsheetEditorContext<TRow> {
+    /** The value the cell holds, ready to be edited. */
+    readonly $implicit: HubSpreadsheetValue;
+    /** The cell as its column reported it. */
+    readonly cell: HubSpreadsheetCell;
+    /**
+     * The character that opened the cell, when it was opened by typing into it.
+     *
+     * That keystroke is the reader's first, and an editor that ignores it makes them type it
+     * again. A picker should put it in its search box; a field, in its value.
+     */
+    readonly seed: string | undefined;
+    /** The row it belongs to. */
+    readonly row: TRow;
+    /** The column it belongs to. */
+    readonly column: HubSpreadsheetColumn<TRow>;
+    /** Accepts a new value and closes the editor, moving the cursor down as Enter would. */
+    readonly commit: (value: HubSpreadsheetValue) => void;
+    /** Closes the editor and keeps what the cell held. */
+    readonly cancel: () => void;
+}
+/**
+ * Replaces the editor of one column with a template of your own.
+ *
+ * The sheet ships editors for the kinds it knows — a field for text and figures, a list for a
+ * column with options, a date field, a checkbox — and this is how a column gets something else:
+ * a `hub-select` with a search box, a picker of your own, anything that can report a value.
+ *
+ * ```html
+ * <hub-spreadsheet [rows]="rows()" [columns]="columns" [rowKey]="rowKey">
+ *   <ng-template hubSpreadsheetEditor="supplier" let-value let-ctx="commit">
+ *     <hub-select [options]="suppliers()" [ngModel]="value" (ngModelChange)="ctx($event)" />
+ *   </ng-template>
+ * </hub-spreadsheet>
+ * ```
+ *
+ * The template is responsible for calling `commit` or `cancel`. Until it does, the editor stays
+ * open — which is what lets a picker take as many clicks as it needs without the sheet deciding
+ * the reader has finished.
+ */
+declare class HubSpreadsheetEditorDirective<TRow = unknown> {
+    /** The alias of the column this editor belongs to. */
+    readonly column: _angular_core.InputSignal<string>;
+    /**
+     * The same rows the sheet is given, only so the compiler knows what a row is here.
+     *
+     * Nothing reads it. A template is compiled on its own, with no way of knowing which sheet will
+     * mount it, so `let-row` arrives as `unknown` and every use of it needs a cast. Handing the
+     * rows over is how Angular's own structural directives solve this, and it costs one binding.
+     */
+    readonly rows: _angular_core.InputSignal<readonly TRow[]>;
+    readonly template: TemplateRef<HubSpreadsheetEditorContext<TRow>>;
+    /** Lets Angular narrow `let-` bindings inside the template to the real context type. */
+    static ngTemplateContextGuard<TRow>(_directive: HubSpreadsheetEditorDirective<TRow>, _context: unknown): _context is HubSpreadsheetEditorContext<TRow>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSpreadsheetEditorDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubSpreadsheetEditorDirective<any>, "[hubSpreadsheetEditor]", never, { "column": { "alias": "hubSpreadsheetEditor"; "required": true; "isSignal": true; }; "rows": { "alias": "hubSpreadsheetEditorRows"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** What a cell template is handed while the cell is sitting still. */
+interface HubSpreadsheetCellContext<TRow> {
+    /** What the cell holds. */
+    readonly $implicit: HubSpreadsheetValue;
+    /** The cell as its column reported it. */
+    readonly cell: HubSpreadsheetCell;
+    /** The row it belongs to. */
+    readonly row: TRow;
+    /** The column it belongs to. */
+    readonly column: HubSpreadsheetColumn<TRow>;
+    /** Whether this is the cell the reader is on. */
+    readonly active: boolean;
+}
+/**
+ * Draws one column's cells yourself: a badge for a state, an avatar beside a name, a row of
+ * actions.
+ *
+ * The sibling of `hubSpreadsheetEditor`, for the other half of a cell's life. That one replaces
+ * what appears when the cell is opened; this one replaces what the cell shows while it is not.
+ *
+ * ```html
+ * <hub-spreadsheet [rows]="rows()" [columns]="columns" [rowKey]="rowKey">
+ *   <ng-template hubSpreadsheetCell="status" let-value>
+ *     <hub-badge [variant]="value === 'done' ? 'success' : 'warning'">{{ value }}</hub-badge>
+ *   </ng-template>
+ * </hub-spreadsheet>
+ * ```
+ *
+ * Two things stay the sheet's whatever the template draws. The clipboard carries the cell's value,
+ * not its decoration, so a copy round-trips as data rather than as a picture of it. And the cell
+ * is still the thing the keyboard is on: the template is drawn inside it, not instead of it.
+ *
+ * A template with something clickable in it joins the tab order of the page, which the grid's own
+ * roving tab stop does not manage — put the action behind `hubSpreadsheetEditor` instead when the
+ * cell should be entered before it can be used.
+ */
+declare class HubSpreadsheetCellDirective<TRow = unknown> {
+    /** The alias of the column these cells belong to. */
+    readonly column: _angular_core.InputSignal<string>;
+    /**
+     * The same rows the sheet is given, only so the compiler knows what a row is here.
+     *
+     * Nothing reads it. A template is compiled on its own, with no way of knowing which sheet will
+     * mount it, so `let-row` arrives as `unknown` and every use of it needs a cast. Handing the
+     * rows over is how Angular's own structural directives solve this, and it costs one binding:
+     *
+     * ```html
+     * <ng-template hubSpreadsheetCell="actions" [hubSpreadsheetCellRows]="orders()" let-row="row">
+     * ```
+     */
+    readonly rows: _angular_core.InputSignal<readonly TRow[]>;
+    readonly template: TemplateRef<HubSpreadsheetCellContext<TRow>>;
+    /** Lets Angular narrow `let-` bindings inside the template to the real context type. */
+    static ngTemplateContextGuard<TRow>(_directive: HubSpreadsheetCellDirective<TRow>, _context: unknown): _context is HubSpreadsheetCellContext<TRow>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSpreadsheetCellDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubSpreadsheetCellDirective<any>, "[hubSpreadsheetCell]", never, { "column": { "alias": "hubSpreadsheetCell"; "required": true; "isSignal": true; }; "rows": { "alias": "hubSpreadsheetCellRows"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * What to offer a reader who is in the middle of writing a formula.
+ *
+ * A formula names columns by an alias that is nowhere on screen — the header shows a title meant
+ * for people, not the key the formula needs — so writing one from memory means knowing something
+ * the sheet never showed. That is the actual problem: not that the language is hard, but that the
+ * words are hidden.
+ *
+ * Kept as arithmetic over strings, with no DOM and no component, so the awkward parts — where the
+ * word being typed starts, what counts as one — can be held still by a test.
+ */
+/** One thing the reader can put into the formula. */
+interface HubFormulaSuggestion {
+    /** What to show. */
+    readonly label: string;
+    /** What it is, so the list can say so. */
+    readonly kind: 'column' | 'function';
+    /** What goes into the draft. */
+    readonly insert: string;
+    /** A word on what it does, for a function. */
+    readonly hint?: string;
+}
+/** What the sheet knows that a formula might want. */
+interface HubFormulaVocabulary {
+    /** The column aliases, in the order the columns are in. */
+    readonly aliases: readonly string[];
+    /** What each alias is called on screen, so the list can show both. */
+    readonly titles?: Readonly<Record<string, string>>;
+}
+/** The functions the engine knows, with a word on each. */
+declare const HUB_FORMULA_FUNCTIONS: ReadonlyArray<{
+    name: string;
+    hint: string;
+}>;
+/** Where the word being typed starts, and what it says so far. */
+interface HubFormulaFragment {
+    /** Where in the draft it begins. */
+    readonly start: number;
+    /** What has been typed of it. */
+    readonly text: string;
+    /** Whether the reader is inside brackets, which is where a column belongs. */
+    readonly inBrackets: boolean;
+}
+/**
+ * The word the caret is in the middle of.
+ *
+ * Inside brackets it is a column being named — `[pri` — and everywhere else it is a function, or
+ * the beginning of one. Everything before the last operator, bracket or space is settled and is
+ * left alone.
+ */
+declare function formulaFragment(draft: string, caret?: number): HubFormulaFragment;
+/**
+ * What to offer for a draft, in the order it should be shown.
+ *
+ * Columns first while inside brackets, functions first outside them, because that is what the
+ * reader is asking for by having typed the bracket at all. An empty fragment offers everything:
+ * somebody who has just typed `=` is exactly the person who needs the list most.
+ *
+ * @param draft - The formula as it stands, `=` and all.
+ * @param vocabulary - The aliases the sheet has.
+ * @param caret - Where the caret is; the end of the draft when not given.
+ */
+declare function suggestFormula(draft: string, vocabulary: HubFormulaVocabulary, caret?: number): readonly HubFormulaSuggestion[];
+/**
+ * The draft with a suggestion put in, and where the caret should end up.
+ *
+ * The caret matters more than it looks: dropped at the end of `SUM(` it carries straight on into
+ * the brackets, and dropped after `[price]` it is ready for the operator. Leaving it where it was
+ * makes the reader move it by hand every single time.
+ */
+declare function applySuggestion(draft: string, suggestion: HubFormulaSuggestion, caret?: number): {
+    readonly draft: string;
+    readonly caret: number;
+};
+
+/**
+ * Hosting a richer editor inside a cell without depending on the library it comes from.
+ *
+ * The sheet ships a native list for a column with options, which needs nothing installed and
+ * behaves the way the platform does on a phone. A project that has a component library wires this
+ * adapter once and every list column upgrades — no template per sheet, and the sheet still imports
+ * nothing: the shape is declared here and satisfied structurally, which is the same bargain
+ * `ng-hub-ui-paginable` strikes for its table controls.
+ *
+ * `ng-hub-ui-forms` ships an implementation that fits: `hubFormControlAdapter`.
+ */
+/** How the adapter should present the control's name. Mirrors the family's label types. */
+type HubSpreadsheetControlLabelType = 'floating' | 'stacked' | 'horizontal' | 'visually-hidden';
+/** One answer a hosted list offers. */
+interface HubSpreadsheetControlOption {
+    value: unknown;
+    label: string;
+    /**
+     * Listed but not choosable, where the adapter honours it.
+     *
+     * The sheet's own list guarantees this; a hosted control is another library's, and the sheet
+     * can only pass the flag on.
+     */
+    disabled?: boolean;
+}
+/**
+ * What the sheet asks for when a cell of a list column opens.
+ *
+ * Only lists go through the adapter. A text or figure cell keeps the sheet's own editor, which
+ * holds the draft, reads the reader's decimal mark and refuses what the column cannot store —
+ * none of which a foreign control knows about, and all of which a value-per-keystroke contract
+ * would throw away.
+ */
+interface HubSpreadsheetControlConfig {
+    /** The only kind the sheet hosts today. */
+    kind: 'select';
+    /** What the cell holds. */
+    value: unknown;
+    /** The answers, in the order the column declared them. */
+    options?: ReadonlyArray<HubSpreadsheetControlOption>;
+    /** The column's header, so the control is not left anonymous inside a grid. */
+    label?: string;
+    /** How to present that name. `visually-hidden` unless the host says otherwise. */
+    labelType?: HubSpreadsheetControlLabelType;
+    /** The name to fall back on where the adapter ignores {@link label}. */
+    ariaLabel?: string;
+    /** Shown while the cell is empty. */
+    placeholder?: string;
+    /** Extra class forwarded to the control. */
+    cssClass?: string;
+    /** Whether the control offers a search box. True from a cell: a long list is why you wire one. */
+    searchable?: boolean;
+    /** Whether it offers to clear itself. False from a cell: `Delete` empties a cell. */
+    clearable?: boolean;
+    /** Whether it opens as it appears. True from a cell, where the click that opened it is spent. */
+    autoOpen?: boolean;
+    /** A term to start filtered by — the character the reader opened the cell with. */
+    searchTerm?: string;
+    /**
+     * Called when the reader chooses. The sheet commits and moves on, as the native list does.
+     *
+     * Typed `unknown` rather than the sheet's own value type, and deliberately: a callback is
+     * checked the other way round, so a narrower parameter here would refuse the very adapters
+     * this contract exists to accept. What comes back is read through the column, which is where
+     * the refusing belongs anyway.
+     */
+    onValueChange: (value: unknown) => void;
+}
+/** Live handle to a control the adapter created. */
+interface HubSpreadsheetControlHandle {
+    /** Pushes a value in from outside. */
+    setValue(value: unknown): void;
+    /** Destroys the control and releases what it holds. */
+    destroy(): void;
+}
+/**
+ * Optional, structurally typed adapter that renders a cell's list with a richer control.
+ *
+ * Declared here rather than imported, so the library keeps no dependency at all on whatever
+ * provides it. With no adapter registered the sheet draws its native list; with one, every list
+ * column upgrades at once.
+ */
+interface HubSpreadsheetControlsAdapter {
+    /**
+     * Creates a control inside `container`.
+     *
+     * @returns A handle to update or destroy it.
+     */
+    create(container: ViewContainerRef, config: HubSpreadsheetControlConfig): HubSpreadsheetControlHandle;
+}
+
+/**
+ * Working out what a reader's merge or unmerge does to a list of blocks.
+ *
+ * The sheet reports what was asked for and writes nothing, as with rows and columns — the list of
+ * blocks belongs to whoever declared it, and is usually saved with the document. These are the two
+ * lines of arithmetic that would otherwise be rewritten in every host, and the place where the
+ * awkward case lives: a merge swallows the blocks already inside it, and a host that merely
+ * appends ends up with two blocks claiming the same cell.
+ */
+/** A merge the reader asked for, and what it absorbs. */
+interface HubSpreadsheetMergeRequest {
+    /** The block to create. */
+    readonly span: HubGridSpan;
+    /** The anchors of the blocks it swallows, which have to go. */
+    readonly replaced: readonly HubGridCoords[];
+}
+/** The blocks that share a cell with a rectangle, in the order they were declared. */
+declare function spansWithin(spans: readonly HubGridSpan[], range: HubGridRange): readonly HubGridSpan[];
+/**
+ * The block a selection would become, and the blocks it swallows.
+ *
+ * `null` for a selection of one cell that is not already a block: there is nothing to merge, and
+ * an entry that does nothing should not be offered.
+ */
+declare function mergeRequestFor(spans: readonly HubGridSpan[], range: HubGridRange): HubSpreadsheetMergeRequest | null;
+/**
+ * The list of blocks after a merge.
+ *
+ * The swallowed ones are dropped rather than left behind: two blocks claiming the same cell is a
+ * sheet that draws one of them and loses the other, and which one depends on the order they happen
+ * to be declared in.
+ */
+declare function applySpanMerge(spans: readonly HubGridSpan[], request: HubSpreadsheetMergeRequest): HubGridSpan[];
+/** The list of blocks after the ones anchored at `anchors` are taken apart. */
+declare function applySpanUnmerge(spans: readonly HubGridSpan[], anchors: readonly HubGridCoords[]): HubGridSpan[];
+
+/**
+ * An editable sheet of cells: typed into, moved through with the keyboard, and pasted into from
+ * a spreadsheet.
+ *
+ * It knows nothing about what the cells mean. The owner describes each column, keeps the save
+ * state it cares about, and does the writing when the sheet reports a change. The sheet never
+ * mutates the rows it is given, which is what lets the same component serve an invoice, a price
+ * list and a timesheet without learning about any of them.
+ *
+ * Focus lives on the cells themselves, with one tab stop that travels — the arrangement screen
+ * readers expect from a grid. Pasting is the exception: a browser only dispatches `paste` to an
+ * editable element, so the paste shortcut hands focus to an off-screen field for the length of
+ * the event and takes it straight back.
+ */
+declare class HubSpreadsheetComponent<TRow> {
+    #private;
+    /** The rows, as the owner holds them. Never written to. */
+    readonly rows: _angular_core.InputSignal<readonly TRow[]>;
+    /** What each column shows and allows. */
+    readonly columns: _angular_core.InputSignal<readonly HubSpreadsheetColumn<TRow>[]>;
+    /** A stable name per row, so a save state follows its row across a reload. */
+    readonly rowKey: _angular_core.InputSignal<(row: TRow) => string>;
+    /** The save state of each cell, keyed by `rowKey` and column alias joined by a tab. */
+    readonly states: _angular_core.InputSignal<Record<string, HubSpreadsheetCellState>>;
+    /**
+     * A validation message per cell, keyed the same way as {@link states}.
+     *
+     * Owned by the host, because validation belongs to whoever knows what the data means. Keeping
+     * it a plain map rather than tying it to one forms API is what lets the same sheet be driven
+     * by Signal Forms, by reactive forms, or by nothing at all.
+     */
+    readonly errors: _angular_core.InputSignal<Record<string, string>>;
+    /** The character this reader types decimals with. */
+    readonly decimalMark: _angular_core.InputSignal<"," | ".">;
+    /** What an empty sheet says. */
+    readonly emptyText: _angular_core.InputSignal<string>;
+    /** How many rows Page Up and Page Down travel. */
+    readonly pageSize: _angular_core.InputSignal<number>;
+    /** Turns off every editor, whatever the individual cells say. */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * How many columns stay pinned against the leading edge while the sheet scrolls sideways.
+     *
+     * Counted from the start, the way a spreadsheet freezes panes, rather than marked one by one:
+     * a set of frozen columns with a gap in it cannot be laid out, so the shape of the input rules
+     * the mistake out instead of validating against it.
+     */
+    readonly frozenColumns: _angular_core.InputSignal<number>;
+    /** How many rows stay pinned below the header while the sheet scrolls down. */
+    readonly frozenRows: _angular_core.InputSignal<number>;
+    /**
+     * Cells merged into blocks, each named by its top-left corner.
+     *
+     * Owned by the host, which is why they come in as an input and why the reader's merging goes
+     * back out as a request rather than being done here — see {@link mergeable}. A declared block
+     * is treated as one cell everywhere it matters: the cursor lands on the block rather than
+     * inside it, a selection that would clip one grows to contain it, and the covered cells are
+     * not drawn at all.
+     */
+    readonly spans: _angular_core.InputSignal<readonly HubGridSpan[]>;
+    /** Which structural changes the reader may ask for. Everything is refused by default. */
+    readonly structure: _angular_core.InputSignal<HubSpreadsheetStructureOptions<TRow>>;
+    /** Editors supplied by the host, one per column alias. */
+    protected readonly customEditors: _angular_core.Signal<readonly HubSpreadsheetEditorDirective<TRow>[]>;
+    /** Cell templates supplied by the host, for what a column shows while it is not being edited. */
+    protected readonly customCells: _angular_core.Signal<readonly HubSpreadsheetCellDirective<TRow>[]>;
+    /** Aliases retired by earlier deletions, so a new column never reuses one. */
+    readonly retiredColumnKeys: _angular_core.InputSignal<readonly string[]>;
+    /** Whether the sheet offers the fill handle at the corner of the selection. */
+    readonly fillHandle: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether undo is available; the sheet only asks, the owner keeps the history. */
+    readonly canUndo: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether redo is available. */
+    readonly canRedo: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether a reader may drag a column's trailing edge to widen or narrow it. */
+    readonly resizableColumns: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether a reader may drag a header to put the column somewhere else. */
+    readonly reorderableColumns: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * The width of each column in pixels, keyed by alias.
+     *
+     * Two-way, and view state rather than data: the sheet writes it as the reader drags, and the
+     * owner may persist it so a layout survives a reload. A column with no entry keeps whatever
+     * width its content asks for.
+     */
+    readonly columnWidths: _angular_core.ModelSignal<Record<string, number>>;
+    /** The narrowest a column may be dragged. */
+    readonly minColumnWidth: _angular_core.InputSignal<number>;
+    /**
+     * Whether a right-click offers the menu of structural changes.
+     *
+     * Off unless asked for, and each entry still has to pass `structure`. A menu that lists what
+     * the reader is not allowed to do is worse than no menu.
+     */
+    readonly contextMenu: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether the reader may put cells together and take them apart again.
+     *
+     * Off unless asked for, like every other structural change: a sheet whose shape is part of the
+     * document it belongs to should not be reshaped by a stray right-click. The blocks stay the
+     * host's — the sheet reports what was asked for through {@link mergeRequested} and
+     * {@link unmergeRequested} and writes nothing itself. Offered through the context menu, so it
+     * needs {@link contextMenu} to be reachable with the pointer.
+     */
+    readonly mergeable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether a cell whose value starts with `=` is a formula.
+     *
+     * Off unless asked for, and not as caution for its own sake: a column of text may perfectly
+     * well hold `=1+1` as the thing somebody wrote, and a sheet that decides to do arithmetic on
+     * it has lost the reader's data.
+     *
+     * Formulas read columns by their alias — `=[price] * [units]`, `=SUM([total:])` — never by a
+     * coordinate, which is what the aliases were for: move a column, rename its header, and every
+     * formula still means what it said.
+     *
+     * The cell shows the answer; the editor shows the formula, so it can be corrected rather than
+     * retyped; and the clipboard carries what the cell holds, which is the formula.
+     */
+    readonly formulas: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether to draw only the rows the reader can see.
+     *
+     * Off unless asked for. A sheet of a few hundred rows is better off whole — every row is in the
+     * document, so the browser's own find works, printing works, and nothing depends on a
+     * measurement. Past a few thousand it stops being a choice: the first paint arrives late and
+     * every keystroke pays for cells nobody is looking at.
+     *
+     * What it costs: the rows out of view are not in the document, so `Ctrl+F` and printing only
+     * reach what is drawn, and the rows have to be of one height — see {@link rowHeight}.
+     */
+    readonly virtual: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * How tall a row is, in pixels, when {@link virtual} is on.
+     *
+     * Nought means "measure the first one drawn", which is right whenever the rows are alike. Say
+     * it outright for a sheet whose first row is not typical, or one that is built while hidden —
+     * a tab that is not open measures every row as nought, and a window worked out from nought is
+     * the whole sheet.
+     */
+    readonly rowHeight: _angular_core.InputSignal<number>;
+    /**
+     * What opens the editor with the pointer.
+     *
+     * `double-click` by default, the spreadsheet convention: a click picks the cell and leaves its
+     * value where it is. Selecting is the gesture a reader makes most — to copy, to look, to drag
+     * out a range — and turning every one of them into an open field puts the value at the mercy
+     * of the next keystroke. Typing is still the short way in: with the cell picked, the first
+     * character opens the editor and lands in it, so nothing is lost by not opening on the click.
+     *
+     * `click` opens on the first one, for a sheet that exists to be typed into and where the two
+     * gestures per cell are the tax.
+     *
+     * Either way the editor opens on release and only when the pointer did not travel, so
+     * dragging out a range still works — and Shift-clicking still extends rather than edits.
+     */
+    readonly editOn: _angular_core.InputSignal<"click" | "double-click">;
+    /** A cell took a new value. */
+    readonly commit: _angular_core.OutputEmitterRef<HubSpreadsheetCommit<TRow>>;
+    /** A block was pasted. */
+    readonly pasted: _angular_core.OutputEmitterRef<HubSpreadsheetPaste<TRow>>;
+    /** Delete was pressed over these cells, the editable ones of the selection. */
+    readonly cleared: _angular_core.OutputEmitterRef<HubSpreadsheetCellRef<TRow>[]>;
+    /** The selected rectangle changed; null when nothing is selected. */
+    readonly selectionChange: _angular_core.OutputEmitterRef<HubGridRange | null>;
+    /** The reader asked to add rows or columns. */
+    readonly insertRequested: _angular_core.OutputEmitterRef<HubSpreadsheetInsertRequest>;
+    /** The reader asked to remove rows or columns. */
+    readonly deleteRequested: _angular_core.OutputEmitterRef<HubSpreadsheetDeleteRequest>;
+    /**
+     * A drag of the fill handle finished.
+     *
+     * Reported as one event for the whole gesture, so an owner keeping a history can make it one
+     * undo step. Filling cell by cell and undoing cell by cell is experienced as a bug.
+     */
+    readonly filled: _angular_core.OutputEmitterRef<HubSpreadsheetPaste<TRow>>;
+    /** The reader asked to undo. The owner holds the history and decides what that means. */
+    readonly undoRequested: _angular_core.OutputEmitterRef<void>;
+    /** The reader asked to redo. */
+    readonly redoRequested: _angular_core.OutputEmitterRef<void>;
+    /**
+     * The reader dropped a column somewhere else.
+     *
+     * Reported rather than applied: the column list belongs to the owner, as the rows do. The
+     * payload carries the reordered aliases so acting on it is a single assignment.
+     */
+    readonly columnMoved: _angular_core.OutputEmitterRef<{
+        from: number;
+        to: number;
+        key: string;
+        keys: string[];
+    }>;
+    /**
+     * The reader asked to put a selection together into one block.
+     *
+     * The payload carries the block to create and the anchors of the blocks it swallows, because a
+     * host that merely appends the new one ends up with two claiming the same cell — and which of
+     * them is drawn depends on the order they were declared in. `applySpanMerge()` does the whole
+     * thing in a line.
+     */
+    readonly mergeRequested: _angular_core.OutputEmitterRef<HubSpreadsheetMergeRequest>;
+    /** The reader asked to take apart the blocks their selection touches, named by their anchors. */
+    readonly unmergeRequested: _angular_core.OutputEmitterRef<readonly HubGridCoords[]>;
+    /** The cell the cursor is on. */
+    protected readonly active: _angular_core.WritableSignal<HubGridCoords | null>;
+    /** The other corner of the selection; null when only the active cell is selected. */
+    protected readonly anchor: _angular_core.WritableSignal<HubGridCoords | null>;
+    protected readonly editing: _angular_core.WritableSignal<boolean>;
+    protected readonly draft: _angular_core.WritableSignal<string>;
+    /**
+     * The character that opened the cell, when typing opened it.
+     *
+     * Kept beside the draft rather than inside it because a supplied editor needs it as it was
+     * typed, while the draft has already been turned into whatever the column stores.
+     */
+    private readonly seed;
+    /** The editor holds text that does not read as a value, so it stays open and marked. */
+    protected readonly invalid: _angular_core.WritableSignal<boolean>;
+    private dragging;
+    /** Whether the pointer visited another cell during this press, which makes it a drag. */
+    private dragMoved;
+    /** The selection a fill drag started from; null when no fill is in progress. */
+    protected readonly fillSource: _angular_core.WritableSignal<HubGridRange | null>;
+    /** What the fill would cover if released now. */
+    protected readonly fillTarget: _angular_core.WritableSignal<HubGridRange | null>;
+    /** The column being widened, with where the pointer started and how wide it then was. */
+    private resizing;
+    /** The column being dragged to another place. */
+    protected readonly movingColumn: _angular_core.WritableSignal<number | null>;
+    /** Where it would land if dropped now. */
+    protected readonly moveTargetColumn: _angular_core.WritableSignal<number | null>;
+    /** Where the structural menu sits, in pixels from the sheet's own corner; null when closed. */
+    protected readonly menuAt: _angular_core.WritableSignal<{
+        x: number;
+        y: number;
+    } | null>;
+    /** Where each frozen column sits, in pixels from the leading edge. */
+    protected readonly columnOffsets: _angular_core.WritableSignal<readonly number[]>;
+    /** Where each frozen row sits, in pixels from the top of the scroll area. */
+    protected readonly rowOffsets: _angular_core.WritableSignal<readonly number[]>;
+    /** The merges, indexed once per change rather than scanned on every keystroke. */
+    protected readonly spanMap: _angular_core.Signal<ng_hub_ui_utils.HubGridSpanMap>;
+    protected readonly bounds: _angular_core.Signal<{
+        rows: number;
+        cols: number;
+    }>;
+    /**
+     * What the viewport has told us about itself: how far it has scrolled and how tall it is.
+     *
+     * Nought until the first measurement, which is why {@link gridWindow} draws a first screenful
+     * from nothing rather than drawing nothing: the rows it puts in are what the measurement then
+     * measures.
+     */
+    private readonly viewport;
+    private readonly scrollTop;
+    private readonly viewportHeight;
+    /** The height of a row, measured off the first one drawn unless the host declared it. */
+    private readonly measuredRowHeight;
+    /** How far the viewport has travelled sideways, and how much of it is on screen. */
+    private readonly scrollLeft;
+    private readonly viewportWidth;
+    /** The width of every column, by index, as last measured. */
+    private readonly measuredColumnWidths;
+    /** The rows to draw: the frozen ones, then the window, or all of them when not virtualising. */
+    protected readonly rowWindow: _angular_core.Signal<HubGridWindow>;
+    /**
+     * The columns to draw, the same way as the rows.
+     *
+     * Their widths are measured rather than declared, so the first render draws them all — there
+     * is nothing to measure otherwise — and every render after that windows them with what the
+     * first one learnt. A column the sheet has never drawn has no width, and one unknown width is
+     * enough to fall back to drawing the lot: a window is only as honest as the sizes it is built
+     * from.
+     */
+    protected readonly columnWindow: _angular_core.Signal<HubGridWindow>;
+    /** The column indices in the document, frozen ones first. */
+    protected readonly drawnColumns: _angular_core.Signal<number[]>;
+    /**
+     * How many cells a row of the sheet actually holds, spacers included.
+     *
+     * What a spacer row has to span. `bounds().cols` would be wrong whenever the columns are
+     * windowed — it counts the columns the sheet has, not the ones in the document — and a colspan
+     * that overshoots stretches the table wider than its own header.
+     */
+    protected readonly drawnCellCount: _angular_core.Signal<number>;
+    /** The row indices in the document, frozen ones first. */
+    protected readonly drawnRows: _angular_core.Signal<number[]>;
+    /** Every cell, worked out once per change of rows or columns rather than on every paint. */
+    protected readonly grid: _angular_core.Signal<HubSpreadsheetCell[][]>;
+    /** Which suggestion the keyboard is on, or -1 when the reader has not moved into the list. */
+    private readonly suggestionAt;
+    /**
+     * What to offer while a formula is being written, or nothing when one is not.
+     *
+     * A formula names columns by an alias the sheet never shows — the header carries a title meant
+     * for people — so without this, writing one means knowing something that is not on screen.
+     */
+    protected readonly suggestions: _angular_core.Signal<readonly HubFormulaSuggestion[]>;
+    /** Whether the sheet is showing the list of what can go into a formula. */
+    protected readonly suggesting: _angular_core.Signal<boolean>;
+    /**
+     * The one the keyboard is on, which Enter and Tab put in.
+     *
+     * The first is taken as chosen the moment there is a word being typed, so `=SU` and Tab
+     * finishes it — which is what completing means, and what a reader who has seen a spreadsheet
+     * expects. Nothing is chosen when there is no word: a bare `=`, or a formula that has just
+     * closed a bracket, is a list to look at rather than a completion to accept, and Enter there
+     * means commit.
+     */
+    protected readonly suggestionIndex: _angular_core.Signal<number>;
+    /** Whether a formula is being written, which is when the aliases are worth showing. */
+    protected readonly writingFormula: _angular_core.Signal<boolean>;
+    /** The letters a column answers to in a formula: A, B … Z, AA. */
+    protected columnLetter(index: number): string;
+    /** Puts a suggestion into the draft and leaves the caret where the next thing is typed. */
+    protected useSuggestion(suggestion: HubFormulaSuggestion): void;
+    /** Whether a cell is showing a formula that could not be worked out. */
+    protected hasFormulaError(row: number, col: number): boolean;
+    protected readonly keys: _angular_core.Signal<string[]>;
+    protected readonly range: _angular_core.Signal<HubGridRange | null>;
+    /**
+     * Keeps the cursor where it was when the rows are replaced by a reload after a save, and drops
+     * it only once it points at nothing. Typing a value and pressing Enter has to land on the cell
+     * below even when the saved figures come back as fresh objects.
+     */
+    private readonly reconcile;
+    /**
+     * Keeps the viewport's measurements up to date while virtualising.
+     *
+     * In the read phase, like the frozen offsets: reading layout while the browser is writing one
+     * forces a reflow in the middle of it, which is how a grid loses frames exactly when it is
+     * being scrolled.
+     *
+     * It settles rather than loops. Measuring feeds the window, the window changes what is drawn,
+     * and the next pass measures the same numbers — a signal set to the value it already holds
+     * tells nobody, so the third pass does not happen. It reads `drawnRows` so that a sheet whose
+     * data arrives later is measured when its first row finally exists, which is the common case
+     * and the one a single measurement at birth gets wrong.
+     */
+    private readonly measureViewport;
+    /**
+     * The width of every column, read off the headers by the index they carry.
+     *
+     * By index and not by position, because a windowed header holds the frozen columns and then
+     * the ones in view — so the third header in the document is rarely the third column. A width
+     * that is not on screen keeps whatever was measured last, which is what makes windowing the
+     * columns possible at all: they are measured once, while the sheet is still drawing them all.
+     */
+    private readColumnWidths;
+    /**
+     * Measures the frozen tracks after every render and turns the sizes into offsets.
+     *
+     * Reading layout has to happen in the read phase or it forces a synchronous reflow in the
+     * middle of writing one, which is the classic way a grid loses frames while scrolling.
+     */
+    private readonly measureFrozen;
+    /**
+     * Whether a column is pinned.
+     *
+     * Answered from the input alone, never from the measurement. A cell is taken out of the flow
+     * because the caller asked for it; the measured offset only decides where it lands. Gating
+     * the two on the same signal would leave the pane unpinned for the frame before the first
+     * measurement, and permanently unpinned anywhere the render hooks do not run.
+     */
+    protected isFrozenColumn(col: number): boolean;
+    /** Whether a row is pinned. Same reasoning as {@link isFrozenColumn}. */
+    protected isFrozenRow(row: number): boolean;
+    /** Where a frozen column sits, once measured; null until then, and the stylesheet pins it at zero. */
+    protected columnOffsetOf(col: number): number | null;
+    /** Where a frozen row sits, once measured. */
+    protected rowOffsetOf(row: number): number | null;
+    protected isColumnEdge(col: number): boolean;
+    protected isRowEdge(row: number): boolean;
+    /** Whether a cell is swallowed by a merge, and therefore not rendered. */
+    protected isHidden(row: number, col: number): boolean;
+    /** How many rows a cell occupies; null leaves the attribute off. */
+    protected rowSpanOf(row: number, col: number): number | null;
+    /** How many columns a cell occupies; null leaves the attribute off. */
+    protected colSpanOf(row: number, col: number): number | null;
+    /**
+     * Whether a cell reaches the trailing edge of the sheet, counting the columns it spans.
+     *
+     * Asked rather than guessed with `:last-child`. Once cells can be swallowed by a merge, the
+     * last one drawn in a row is not the one in the last column — in a row where the rightmost
+     * block is covered it is the cell before it, and that is the one that would lose its border.
+     */
+    protected reachesEnd(row: number, col: number): boolean;
+    protected isActive(row: number, col: number): boolean;
+    protected isSelected(row: number, col: number): boolean;
+    protected tabIndexOf(row: number, col: number): number;
+    protected stateOf(row: number, col: number): HubSpreadsheetCellState | undefined;
+    /** The validation message the host attached to a cell, if any. */
+    protected errorOf(row: number, col: number): string | undefined;
+    /** How a cell is addressed in the `states` and `errors` maps. */
+    private cellKey;
+    /**
+     * What a cell shows: its own text when it gives one, otherwise whatever its column makes of
+     * the value — an option's label, a mark for a yes, the value itself for everything else.
+     */
+    protected displayOf(cell: HubSpreadsheetCell, column: HubSpreadsheetColumn<TRow>): string;
+    /**
+     * What a hosted control should be for this cell, or null when there is nothing to host.
+     *
+     * Null covers three cases and they are all deliberate: no adapter registered, a column that is
+     * not a list, and a column whose host supplied its own editor — which is read first and wins,
+     * because a template written for one column is a more specific answer than a rule for all of
+     * them.
+     */
+    protected hostedControl(row: number, col: number): HubSpreadsheetControlConfig | null;
+    /**
+     * Which answer a list shows while it is open.
+     *
+     * Read off the draft rather than off the cell, so a list opened by typing shows the answer that
+     * keystroke reached. The draft holds the stored value until a keystroke moves it, so an
+     * ordinary open still shows what the cell holds.
+     */
+    protected isChosen(option: HubSpreadsheetOption, column: HubSpreadsheetColumn<TRow>): boolean;
+    /** Whether a boolean cell is on, which is what draws its checkbox. */
+    protected isOn(cell: HubSpreadsheetCell): boolean;
+    /**
+     * What a cell should show to say it opens onto something, or null when it opens onto a field.
+     *
+     * Only drawn on the cell the reader is on. A caret down every row of a column would read as
+     * content and make the sheet look like a form, and it is only ever the current cell that is
+     * about to be opened.
+     */
+    protected affordanceOf(column: HubSpreadsheetColumn<TRow>, col: number): 'list' | 'date' | null;
+    /** The template this column's editor should use, if the host supplied one. */
+    protected editorFor(col: number): HubSpreadsheetEditorDirective<TRow> | undefined;
+    /** The template this column draws its cells with, if the host supplied one. */
+    protected cellTemplateFor(col: number): HubSpreadsheetCellDirective<TRow> | undefined;
+    /** The context a cell template is rendered with. */
+    protected cellContext(row: number, col: number): HubSpreadsheetCellContext<TRow>;
+    /** The context a custom editor template is rendered with. */
+    protected editorContext(row: number, col: number): HubSpreadsheetEditorContext<TRow>;
+    /** Accepts a value a custom editor or a built-in list reported, and moves on as Enter would. */
+    protected commitFromEditor(value: HubSpreadsheetValue): void;
+    /**
+     * Turns a boolean cell over without opening an editor.
+     *
+     * A checkbox that needs opening, ticking and confirming is three gestures for one bit. The
+     * keyboard reaches it the same way, since a printable character on such a column toggles too.
+     */
+    protected toggleBoolean(row: number, col: number): void;
+    protected canEdit(row: number, col: number): boolean;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onMouseDown(event: MouseEvent, row: number, col: number): void;
+    /**
+     * Opens the editor on release, not on press.
+     *
+     * Pressing would settle the question too early: a press that turns into a drag is a range
+     * selection, and one that does not is a request to type. Waiting for the release is what lets
+     * both gestures start the same way.
+     */
+    protected onMouseUp(event: MouseEvent, row: number, col: number): void;
+    protected onMouseEnter(row: number, col: number): void;
+    /** The width a column has been dragged to, or null while it sizes itself to its content. */
+    protected widthOf(col: number): number | null;
+    protected onResizeStart(event: MouseEvent, col: number): void;
+    protected onHeaderMouseDown(event: MouseEvent, col: number): void;
+    protected onHeaderMouseEnter(col: number): void;
+    /** Runs for every pointer move while something is being dragged, and only then. */
+    protected onPointerMove(event: MouseEvent): void;
+    protected endDrag(): void;
+    protected onContextMenu(event: MouseEvent, row: number, col: number): void;
+    protected closeMenu(): void;
+    /**
+     * What the menu offers here, already filtered by what is allowed.
+     *
+     * Built rather than rendered-and-hidden so the menu is never opened empty, and so no entry
+     * appears that would do nothing when clicked.
+     */
+    protected readonly menuEntries: _angular_core.Signal<{
+        id: string;
+        label: string;
+        count: number;
+    }[]>;
+    protected runMenuEntry(id: string): void;
+    /** Reports the block the selection would become, with what it swallows. */
+    private requestMerge;
+    /** Reports the blocks the selection touches, so the host can take them apart. */
+    private requestUnmerge;
+    private allRows;
+    private allColumns;
+    /**
+     * Reads the viewport after it has scrolled, or been resized, or drawn its first rows.
+     *
+     * Signals rather than a stored geometry, so the window is a computed like everything else and
+     * nothing has to remember to recompute it. The row height is measured from the first row in
+     * the document, which is also the only row that is certainly there.
+     */
+    protected onViewportScroll(): void;
+    /** Reports where a dragged column was dropped, if it moved at all. */
+    private commitColumnMove;
+    /** Whether a header is the one being dragged, or the place it would land. */
+    protected isMovingColumn(col: number): boolean;
+    protected isMoveTarget(col: number): boolean;
+    /** Whether the fill handle belongs on this cell: the far corner of the selection. */
+    protected hasFillHandle(row: number, col: number): boolean;
+    /** Whether a cell is inside the area a released fill would write to. */
+    protected isFillPreview(row: number, col: number): boolean;
+    protected onFillHandleDown(event: MouseEvent): void;
+    /** Grows the preview towards wherever the pointer went, on one axis only. */
+    private trackFill;
+    /** Works out what the finished drag writes, reports it, and leaves the selection covering it. */
+    private commitFill;
+    /**
+     * Opens the cell from its own mark, on the first click.
+     *
+     * The mark exists to be pressed, so it does not wait for a second click the way the rest of the
+     * cell does — which is what a spreadsheet does with the list of a cell that has one. The press
+     * is swallowed rather than let through: the cell underneath would otherwise start a range drag,
+     * and the release would land on an editor that was not there when the press began.
+     */
+    protected onAffordanceDown(event: MouseEvent, row: number, col: number): void;
+    protected onDoubleClick(): void;
+    protected onCopy(event: ClipboardEvent, cut: boolean): void;
+    protected onPaste(event: ClipboardEvent): void;
+    /** Asks the owner to add a row beside the cursor, if it allows it. */
+    protected requestInsertRow(side: 'before' | 'after'): void;
+    /** Asks the owner to remove the rows the selection covers, if it allows it. */
+    protected requestDeleteRows(): void;
+    /** Asks the owner to add a column, handing over an alias that has never been used here. */
+    protected requestInsertColumn(side: 'before' | 'after'): void;
+    /** Asks the owner to remove the columns the selection covers, naming the aliases at stake. */
+    protected requestDeleteColumns(): void;
+    protected onDraftInput(event: Event): void;
+    protected onEditorKeydown(event: KeyboardEvent): void;
+    /**
+     * The list of suggestions takes the arrows, and takes Enter only once the reader is in it.
+     *
+     * Enter is the awkward one: it both accepts a suggestion and commits a cell, and which of the
+     * two it means depends on whether the reader has moved into the list. Moving into it is
+     * deliberate — an arrow key — so somebody who types a whole formula and presses Enter commits
+     * it, which is what they meant.
+     *
+     * @returns Whether the key was the list's, and the editor should leave it alone.
+     */
+    private onSuggestionKeydown;
+    /** Leaving the editor keeps what was typed, as clicking away does in a spreadsheet. */
+    protected onEditorBlur(): void;
+    protected trackRow: (index: number) => string;
+    protected trackColumn: (_index: number, column: HubSpreadsheetColumn<TRow>) => string;
+    /** Writes a pasted block into the sheet and reports what fitted and what did not. */
+    private applyPaste;
+    /**
+     * What a pasted cell is worth in this column.
+     *
+     * The raw number from the HTML flavour wins where there is one, because it does not depend on
+     * how the source happened to format it. Only when it is absent is the displayed text parsed,
+     * and then in this reader's own convention.
+     */
+    private read;
+    private startEdit;
+    /** Puts the keyboard in the first thing a supplied editor offers it. */
+    private focusSuppliedEditor;
+    /**
+     * Keeps the characters typed between opening a cell and the editor getting the focus.
+     *
+     * The field does not exist until the view has been drawn, so the focus can only move to it on
+     * the render after the keystroke that opened the cell. Anybody typing quickly — `8`, `0`, `0`
+     * inside one frame — has the first character open the cell and the rest arrive here, at the
+     * grid, with nowhere to go. They used to be dropped: the cell opened on `8` and committed `8`.
+     *
+     * So they are added to the draft, which is what the field shows the moment it appears.
+     */
+    private catchUp;
+    /**
+     * Reads what was typed, reports it if it changed, then moves by `step`.
+     *
+     * @returns false when the text is not a value for this column, leaving the editor open and
+     *          marked rather than throwing away what the reader wrote.
+     */
+    private finishEdit;
+    private cancelEdit;
+    /**
+     * The first answer of a list that starts with what was typed, skipping the ones a reader is
+     * not allowed to choose. Matched on the label, because that is what they were reading.
+     */
+    private optionStartingWith;
+    /** What the editor starts with, which is not always what was typed. */
+    private openingText;
+    /** A value as it goes into the editor: numbers in this reader's own convention. */
+    private editableTextOf;
+    private moveTo;
+    private selectRange;
+    private focusActive;
+    /**
+     * Brings the row the cursor is on inside the viewport, when the sheet is the thing that
+     * scrolls and the row might not be drawn.
+     *
+     * Only the arithmetic the browser cannot do for us: `scrollIntoView` needs an element, and a
+     * row that is not in the document has none. The offset is worked out from the row height,
+     * which virtualising already depends on, and the scroller is nudged by the least that brings
+     * the row in — jumping it to the middle would move the sheet under a reader who only pressed
+     * the down arrow.
+     */
+    private scrollRowIntoView;
+    /**
+     * The same for the column the cursor is on, which may be out of the document sideways.
+     *
+     * Measured widths rather than a single size: columns are rarely alike, and adding up the ones
+     * before the cursor is the only way to know where it starts. Nothing to do when a width is
+     * missing, which is also when the sheet is drawing every column anyway.
+     */
+    private scrollColumnIntoView;
+    /** Hands focus to the off-screen field so the browser will dispatch a paste at all. */
+    private focusSink;
+    private refAt;
+    private announceSelection;
+    private announceCleared;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSpreadsheetComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubSpreadsheetComponent<any>, "hub-spreadsheet", never, { "rows": { "alias": "rows"; "required": true; "isSignal": true; }; "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "rowKey": { "alias": "rowKey"; "required": true; "isSignal": true; }; "states": { "alias": "states"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "decimalMark": { "alias": "decimalMark"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "frozenColumns": { "alias": "frozenColumns"; "required": false; "isSignal": true; }; "frozenRows": { "alias": "frozenRows"; "required": false; "isSignal": true; }; "spans": { "alias": "spans"; "required": false; "isSignal": true; }; "structure": { "alias": "structure"; "required": false; "isSignal": true; }; "retiredColumnKeys": { "alias": "retiredColumnKeys"; "required": false; "isSignal": true; }; "fillHandle": { "alias": "fillHandle"; "required": false; "isSignal": true; }; "canUndo": { "alias": "canUndo"; "required": false; "isSignal": true; }; "canRedo": { "alias": "canRedo"; "required": false; "isSignal": true; }; "resizableColumns": { "alias": "resizableColumns"; "required": false; "isSignal": true; }; "reorderableColumns": { "alias": "reorderableColumns"; "required": false; "isSignal": true; }; "columnWidths": { "alias": "columnWidths"; "required": false; "isSignal": true; }; "minColumnWidth": { "alias": "minColumnWidth"; "required": false; "isSignal": true; }; "contextMenu": { "alias": "contextMenu"; "required": false; "isSignal": true; }; "mergeable": { "alias": "mergeable"; "required": false; "isSignal": true; }; "formulas": { "alias": "formulas"; "required": false; "isSignal": true; }; "virtual": { "alias": "virtual"; "required": false; "isSignal": true; }; "rowHeight": { "alias": "rowHeight"; "required": false; "isSignal": true; }; "editOn": { "alias": "editOn"; "required": false; "isSignal": true; }; }, { "columnWidths": "columnWidthsChange"; "commit": "commit"; "pasted": "pasted"; "cleared": "cleared"; "selectionChange": "selectionChange"; "insertRequested": "insertRequested"; "deleteRequested": "deleteRequested"; "filled": "filled"; "undoRequested": "undoRequested"; "redoRequested": "redoRequested"; "columnMoved": "columnMoved"; "mergeRequested": "mergeRequested"; "unmergeRequested": "unmergeRequested"; }, ["customEditors", "customCells"], never, true, never>;
+}
+
+/** The option a stored value belongs to, or undefined when it belongs to none of them. */
+declare function optionFor<TRow>(value: HubSpreadsheetValue, column: HubSpreadsheetColumn<TRow>): HubSpreadsheetOption | undefined;
+/**
+ * What the cell shows for a value.
+ *
+ * A `select` value whose option has been removed is shown as the stored value rather than as
+ * nothing: blanking it would read as data loss, and the reader would have no way to tell what the
+ * row used to say.
+ */
+declare function displayValue<TRow>(value: HubSpreadsheetValue, column: HubSpreadsheetColumn<TRow>): string;
+/**
+ * What a typed or pasted string is worth in a column.
+ *
+ * Three answers, as everywhere else here: the value, `null` for an empty cell, and `undefined`
+ * for something this column cannot hold — which lets the caller refuse rather than store rubbish.
+ */
+declare function parseForColumn<TRow>(text: string, column: HubSpreadsheetColumn<TRow>, decimalMark: ',' | '.'): HubSpreadsheetValue | undefined;
+/** Whether a stored value counts as yes. */
+declare function isTruthy(value: HubSpreadsheetValue): boolean;
+
+/**
+ * The shape of a formula, and of what comes back from running one.
+ *
+ * A formula refers to columns by the alias they were declared with — `[price] * [units]` — and
+ * never by a coordinate. That is the whole reason the aliases exist: a column can be reordered,
+ * renamed in its header, or moved to another position and every formula still means what it said.
+ * Excel made the other choice, and renaming a column there rewrites every formula in the workbook.
+ */
+/** A value a formula can work with. */
+type HubFormulaValue = number | string | boolean | null;
+/** What went wrong, in the terms a reader can be shown. */
+type HubFormulaErrorCode = 
+/** The text is not a formula: a bracket left open, an operator with nothing after it. */
+'syntax'
+/** A name nothing answers to: a column alias that does not exist, a function that is not one. */
+ | 'name'
+/** Division by nought. */
+ | 'divide-by-zero'
+/** A formula that needs its own result to work out its own result. */
+ | 'cycle'
+/** Arithmetic on something that is not a number, or a function given the wrong kind of thing. */
+ | 'type';
+/** A formula that could not be run, and why. */
+interface HubFormulaFailure {
+    readonly ok: false;
+    readonly code: HubFormulaErrorCode;
+    /** What it was that failed — an alias, a function name, the character it stopped at. */
+    readonly at?: string;
+}
+/** A formula that ran. */
+interface HubFormulaSuccess {
+    readonly ok: true;
+    readonly value: HubFormulaValue;
+}
+type HubFormulaOutcome = HubFormulaSuccess | HubFormulaFailure;
+/** What a formula is allowed to ask about the sheet around it. */
+interface HubFormulaContext {
+    /**
+     * This row's value in a column.
+     *
+     * `undefined` for an alias no column answers to, which is how `#NAME?` is told apart from an
+     * empty cell — a distinction Excel makes and every ad-hoc evaluator forgets.
+     */
+    cell(alias: string): HubFormulaValue | undefined;
+    /** Every row's value in a column, in the order the rows are in. */
+    column(alias: string): readonly HubFormulaValue[] | undefined;
+    /**
+     * The cell at a place, for a formula written with coordinates.
+     *
+     * `undefined` for a place outside the sheet, which is `#REF!` and not an empty cell: a formula
+     * pointing off the edge is a mistake, and one pointing at a blank cell is not.
+     */
+    at?(row: number, col: number): HubFormulaValue | undefined;
+    /** Every cell of a rectangle, row by row. */
+    area?(top: number, left: number, bottom: number, right: number): readonly HubFormulaValue[] | undefined;
+}
+/** A parsed formula, ready to be run as many times as the sheet is redrawn. */
+interface HubFormula {
+    /** The tree to walk. */
+    readonly node: HubFormulaNode;
+    /** Aliases it reads from its own row. */
+    readonly cells: readonly string[];
+    /** Aliases it reads whole columns of. */
+    readonly columns: readonly string[];
+    /** Whether it points at anywhere by coordinate, which is what a change of shape has to move. */
+    readonly coordinates: boolean;
+}
+/** One step of a parsed formula. */
+type HubFormulaNode = {
+    readonly kind: 'number';
+    readonly value: number;
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'boolean';
+    readonly value: boolean;
+} | {
+    readonly kind: 'cell';
+    readonly alias: string;
+} | {
+    readonly kind: 'column';
+    readonly alias: string;
+} | {
+    readonly kind: 'at';
+    readonly row: number;
+    readonly col: number;
+} | {
+    readonly kind: 'area';
+    readonly top: number;
+    readonly left: number;
+    readonly bottom: number;
+    readonly right: number;
+} | {
+    readonly kind: 'unary';
+    readonly operator: '-' | '+';
+    readonly operand: HubFormulaNode;
+} | {
+    readonly kind: 'binary';
+    readonly operator: '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '<=' | '>' | '>=';
+    readonly left: HubFormulaNode;
+    readonly right: HubFormulaNode;
+} | {
+    readonly kind: 'call';
+    readonly name: string;
+    readonly args: readonly HubFormulaNode[];
+};
+
+/**
+ * Turning the text of a formula into something that can be run.
+ *
+ * Hand-written rather than generated, and deliberately: a grammar this small is a page of code,
+ * and a parser generator would be a dependency, a build step and a licence to check for the sake
+ * of it. What it costs is that the precedence is written out by hand — which is also what makes it
+ * readable.
+ *
+ * Precedence, loosest first, as in a spreadsheet:
+ *
+ *     comparison   =  <>  <  <=  >  >=
+ *     concatenation &
+ *     additive     +  -
+ *     multiplicative *  /
+ *     power        ^
+ *     unary        -  +
+ *     primary      number, text, TRUE/FALSE, [alias], [alias:], NAME(…), ( … )
+ */
+/** Whether a stored value is a formula rather than a value. */
+declare function isFormula(value: unknown): value is string;
+/**
+ * Reads the text of a formula, with or without its leading `=`.
+ *
+ * @returns The parsed formula, or the first thing that did not make sense.
+ */
+declare function parseFormula(source: string): HubFormula | HubFormulaFailure;
+
+/**
+ * Runs a formula.
+ *
+ * @param formula - What {@link parseFormula} gave back.
+ * @param context - How to reach the sheet: this row's cells, and whole columns.
+ * @returns The value, or what went wrong.
+ */
+declare function evaluateFormula(formula: HubFormula, context: HubFormulaContext): HubFormulaOutcome;
+
+/**
+ * Working out what every cell of a sheet shows once formulas are in it.
+ *
+ * A formula reads other cells, and those may be formulas too, so the answer to one can depend on
+ * the answer to another. Two things follow, and both are here rather than in the component:
+ *
+ * - **It has to be worked out in order.** A cell is not ready until everything it reads is ready.
+ * - **It has to refuse to go round in circles.** A formula that needs its own result — directly,
+ *   or through three others — has no answer, and a sheet that tries to find one stops responding.
+ *
+ * One rule follows from the second and is worth saying out loud: a whole-column reference leaves
+ * out the cell that is asking for it. `=SUM([total:])` written in the total row is what everybody
+ * writes and what everybody means, and taken literally it is a sum that needs its own answer.
+ * Reading a *different* column is untouched — a total row that sums the prices sums every price.
+ */
+/** What a cell came to, and where it came from. */
+interface HubFormulaCellResult {
+    /** What the cell shows. */
+    readonly value: HubSpreadsheetValue;
+    /** Set when the cell holds a formula that could not be run. */
+    readonly failure?: HubFormulaFailure;
+}
+/** Every cell of the sheet, keyed by row index and column alias. */
+type HubFormulaSheet = ReadonlyArray<Readonly<Record<string, HubFormulaCellResult>>>;
+/** What a sheet of formulas is worked out from. */
+interface HubFormulaSheetInput<TRow> {
+    readonly rows: readonly TRow[];
+    readonly columns: readonly HubSpreadsheetColumn<TRow>[];
+    /**
+     * What a cell holds before any formula is run: a value, or the text of a formula.
+     *
+     * By row index rather than by row, because the caller usually has the grid already worked out
+     * and finding a row's place in a list to read it back is the kind of thing that turns a sheet
+     * of ten thousand rows into a sheet that takes a second to draw.
+     */
+    readonly raw: (rowIndex: number, column: HubSpreadsheetColumn<TRow>) => HubSpreadsheetValue;
+}
+/**
+ * Runs every formula in a sheet, in whatever order the dependencies demand.
+ *
+ * Worked out lazily and remembered: a cell is run the first time something needs it, and a column
+ * read by twenty rows is not run twenty times. The walk carries the cells it is in the middle of,
+ * which is how a circle is caught the moment it closes rather than by counting to a thousand.
+ *
+ * @returns Every cell of the sheet, ready to be shown.
+ */
+declare function evaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheet;
+
+/**
+ * Coordinates: the other way to point at a cell, and what has to happen to them afterwards.
+ *
+ * An alias says which column it means and goes on meaning it whatever happens to the sheet. A
+ * coordinate says *where* the column was when the formula was written, which is only the same
+ * thing until somebody moves it. That is not a reason to refuse coordinates — a spreadsheet
+ * without `B2` is not a spreadsheet — it is a reason to move them with the sheet, which is what
+ * every spreadsheet does and what these functions are for.
+ */
+/** The letters a column is known by: A, B … Z, AA, AB … */
+declare function columnLabel(index: number): string;
+/** Which column a run of letters means, or -1 when it means none. */
+declare function columnIndexOf(label: string): number;
+/** What a coordinate points at, counting from nought. */
+interface HubFormulaCoordinate {
+    readonly row: number;
+    readonly col: number;
+}
+/** Reads `B3` as a place, or nothing when it is not one. */
+declare function parseCoordinate(text: string): HubFormulaCoordinate | null;
+/** Writes a place back as `B3`, which is what a formula shows. */
+declare function formatCoordinate(coordinate: HubFormulaCoordinate): string;
+/** What a reference has become after the sheet changed shape. */
+type Moved = HubFormulaCoordinate | 'gone';
+/** How the sheet changed shape. */
+type HubFormulaShapeChange = {
+    readonly kind: 'move-column';
+    readonly from: number;
+    readonly to: number;
+}
+/** A positive count inserts, a negative one deletes. */
+ | {
+    readonly kind: 'columns';
+    readonly at: number;
+    readonly count: number;
+} | {
+    readonly kind: 'rows';
+    readonly at: number;
+    readonly count: number;
+};
+/** Where a coordinate ends up after a change, or that it no longer points at anything. */
+declare function moveCoordinate(coordinate: HubFormulaCoordinate, change: HubFormulaShapeChange): Moved;
+/**
+ * Rewrites the coordinates in a formula so they point at the same data as before.
+ *
+ * Text, not a parsed tree, and deliberately: what a reader typed is what is stored, so what comes
+ * back has to be something they would recognise as their own formula with a letter changed. A
+ * reference to something that has been deleted becomes `#REF!`, which is what a spreadsheet does
+ * and is honest — the alternative is a formula that quietly reads its neighbour.
+ *
+ * @param formula - The text of the formula, `=` and all.
+ * @param change - What happened to the sheet.
+ * @returns The formula with its coordinates moved.
+ */
+declare function rewriteCoordinates(formula: string, change: HubFormulaShapeChange): string;
+/**
+ * The rows again, with every formula in them moved to match the sheet's new shape.
+ *
+ * The sheet reports what the reader asked for and writes nothing, as it does with everything else,
+ * so this is the line the host writes in its own handler:
+ *
+ * ```ts
+ * protected onColumnMoved(move: { from: number; to: number; keys: string[] }): void {
+ *   this.order.set(move.keys);
+ *   this.rows.update((rows) => rewriteRowFormulas(rows, { kind: 'move-column', from: move.from, to: move.to }));
+ * }
+ * ```
+ *
+ * Every own property that holds a formula is rewritten, which covers the usual case of formulas
+ * living in the row's own fields. A host that keeps them somewhere else — a map beside the data, a
+ * column that declares its own — walks that itself with {@link rewriteCoordinates}.
+ *
+ * @param rows - The rows as they are.
+ * @param change - What happened to the sheet.
+ * @returns New rows; the ones with nothing to rewrite are the very same objects, so a sheet that
+ *          tracks by identity redraws only what moved.
+ */
+declare function rewriteRowFormulas<TRow extends object>(rows: readonly TRow[], change: HubFormulaShapeChange): TRow[];
+
+/** A file read back: its headers, if it had any, and its rows as they were written. */
+interface HubSheetTable {
+    readonly headers: readonly string[] | null;
+    readonly rows: readonly (readonly string[])[];
+}
+/**
+ * Turns a file's rows into records keyed by column alias, matching its headers to the sheet.
+ *
+ * Matched on the header first and the alias second, both ignoring case and surrounding space: a
+ * file that came from this sheet carries the headers, and one written by hand often carries the
+ * aliases. A column the file has nothing for is left out rather than filled with an empty string,
+ * so a partial file updates what it names and leaves the rest alone.
+ *
+ * Shared by every importer, because the matching is the part that has to behave the same whatever
+ * the file was: somebody who fixes a CSV by renaming a heading expects the same file to work when
+ * they save it as a workbook instead.
+ *
+ * @returns One record per row of the file, keyed by column alias.
+ */
+declare function tableToRecords<TRow>(table: HubSheetTable, columns: readonly HubSpreadsheetColumn<TRow>[]): Array<Record<string, string>>;
+
+/**
+ * A sheet as a CSV file, and back.
+ *
+ * Two things decide whether a CSV is any use, and both are here rather than left to the caller.
+ *
+ * The **separator** is not always a comma: where the comma is the decimal mark — most of Europe —
+ * a spreadsheet writes and expects semicolons, and a file written with the wrong one opens as a
+ * single column of text. So it is chosen from the decimal mark when nobody says otherwise, and
+ * sniffed when reading rather than assumed.
+ *
+ * The **values** are what the reader sees, not what the row holds: a select column exports the
+ * label somebody chose, and a formula exports the number it came to. A CSV is what gets sent to
+ * somebody who does not have the application, and a column of `pending` codes is of no use to
+ * them. `values: 'stored'` is there for the round trip that is meant to come back.
+ */
+interface HubCsvOptions {
+    /** What separates the cells. Chosen from the decimal mark when not given. */
+    readonly delimiter?: ',' | ';' | '\t';
+    /** Whether to write the column headers as the first line. On unless turned off. */
+    readonly headers?: boolean;
+    /** What to write: what the cell shows, or what the row holds. */
+    readonly values?: 'shown' | 'stored';
+    /** How this reader writes decimals, which decides the separator and the figures. */
+    readonly decimalMark?: ',' | '.';
+    /** What ends a line. CRLF, because that is what a spreadsheet on Windows expects. */
+    readonly newline?: '\n' | '\r\n';
+    /**
+     * Whether to work the formulas out before writing. On unless turned off, and never done for
+     * `values: 'stored'`, where the formula itself is the thing worth keeping.
+     */
+    readonly formulas?: boolean;
+}
+/**
+ * Writes a sheet as CSV.
+ *
+ * @param rows - The rows, as the sheet has them.
+ * @param columns - The columns, which decide the order and the headers.
+ * @param options - How to write it.
+ * @returns The file's contents.
+ */
+declare function sheetToCsv<TRow>(rows: readonly TRow[], columns: readonly HubSpreadsheetColumn<TRow>[], options?: HubCsvOptions): string;
+/**
+ * Which separator a file is written with.
+ *
+ * Counted on the first line rather than guessed from the file's name: an exporter's idea of CSV
+ * and the reader's locale often disagree, and the line that holds the headers is the one that
+ * shows it most clearly.
+ */
+declare function sniffDelimiter(text: string): ',' | ';' | '\t';
+/**
+ * Reads a CSV file.
+ *
+ * @param text - The file's contents.
+ * @param options - How to read it; the separator is sniffed when not given.
+ */
+declare function csvToTable(text: string, options?: HubCsvOptions): HubSheetTable;
+/**
+ * Reads a CSV file into rows keyed by column alias, matching its headers to the sheet's columns.
+ *
+ * @returns One record per row of the file, keyed by column alias.
+ */
+declare function csvToRecords<TRow>(text: string, columns: readonly HubSpreadsheetColumn<TRow>[], options?: HubCsvOptions): Array<Record<string, string>>;
+/**
+ * Hands the reader a CSV file to save.
+ *
+ * @param filename - What to call it.
+ * @param text - What goes in it.
+ * @param type - Its media type.
+ */
+declare function downloadText(filename: string, text: string, type?: string): void;
+
+/**
+ * A sheet as a real `.xlsx`, written by hand.
+ *
+ * CSV loses everything except the characters: a figure becomes text the moment a locale disagrees
+ * about the decimal mark, a date is whatever the reader's machine decides it is, and nothing knows
+ * a column of prices from a column of postcodes. That is why the export people actually ask for is
+ * this one.
+ *
+ * What comes out is a small, honest workbook: one sheet, a header row in bold, numbers as numbers
+ * and dates as dates. No charts, no merges, no column widths — anybody who needs those has a
+ * workbook of their own to paste into, and every one of them costs another part of a format that
+ * is already the largest thing in this library.
+ *
+ * The one thing worth knowing about the file: its parts are **stored** rather than compressed, so
+ * it is a few times larger than what Excel writes. That is the whole price of not depending on a
+ * compression library, and no reader can tell the difference.
+ */
+interface HubXlsxOptions {
+    /** The sheet's name in the workbook. `Sheet1` when not given. */
+    readonly sheetName?: string;
+    /** Whether to write the column headers as the first row. On unless turned off. */
+    readonly headers?: boolean;
+    /** What to write: what the cell shows, or what the row holds. */
+    readonly values?: 'shown' | 'stored';
+    /** Whether to work the formulas out first. On unless turned off. */
+    readonly formulas?: boolean;
+}
+/** The media type a browser and Excel both recognise. */
+declare const XLSX_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/**
+ * Writes a sheet as an xlsx workbook.
+ *
+ * @param rows - The rows, as the sheet has them.
+ * @param columns - The columns, which decide the order and the headers.
+ * @param options - How to write it.
+ * @returns The bytes of the file.
+ */
+declare function sheetToXlsx<TRow>(rows: readonly TRow[], columns: readonly HubSpreadsheetColumn<TRow>[], options?: HubXlsxOptions): Uint8Array;
+/**
+ * Hands the reader an xlsx file to save.
+ *
+ * @param filename - What to call it; `.xlsx` is added when missing.
+ * @param bytes - The workbook, from `sheetToXlsx`.
+ */
+declare function downloadXlsx(filename: string, bytes: Uint8Array): void;
+
+/**
+ * Reading an xlsx workbook.
+ *
+ * Only what a sheet of data needs: the first worksheet's cells, as text, with the headers if it has
+ * them. Not the charts, not the pictures, not the pivot tables — a file with those in it still
+ * reads, they are simply parts nobody opens here.
+ *
+ * Two things a workbook does that a CSV does not, and both have to be undone or the import is
+ * wrong. A **shared string** is written once and pointed at from every cell that holds it, so a
+ * column of the same word arrives as a column of numbers unless the table is read. And a **date**
+ * is a count of days wearing a number format, so it arrives as `45306` unless the styles are read
+ * to know which columns were dates.
+ *
+ * The XML is read with patterns rather than a parser. It is the part of this file to be suspicious
+ * of, and it is a deliberate choice: these parts are machine-written, their shape is fixed by the
+ * format, and `DOMParser` does not exist where the tests run. What it means in practice is that
+ * anything beyond these few elements is not understood — and a workbook is not a document to be
+ * edited here, only a file to be read once.
+ */
+/** How a workbook is read. */
+interface HubXlsxReadOptions {
+    /** Whether the first row holds the headers. On unless turned off. */
+    readonly headers?: boolean;
+    /** Which sheet to read, by name. The first one when not given. */
+    readonly sheetName?: string;
+}
+/**
+ * Reads a workbook's first sheet as a table of text.
+ *
+ * @param bytes - The whole file, as it was read or dropped.
+ * @param options - How to read it.
+ * @returns The headers, if it has them, and every row.
+ * @throws When the file is not a workbook at all.
+ */
+declare function xlsxToTable(bytes: Uint8Array, options?: HubXlsxReadOptions): Promise<HubSheetTable>;
+/**
+ * Reads a workbook into rows keyed by column alias, matching its headers to the sheet's columns.
+ *
+ * @returns One record per row of the file, keyed by column alias.
+ */
+declare function xlsxToRecords<TRow>(bytes: Uint8Array, columns: readonly HubSpreadsheetColumn<TRow>[], options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>>;
+
+/** How a sheet's values are read for a file. */
+interface HubSheetValuesOptions {
+    /**
+     * Whether to work the formulas out first.
+     *
+     * On for a file somebody else is going to read: a column of `=SUM([total:])` is of no use to
+     * them. Off for a round trip that is meant to come back with its formulas intact.
+     */
+    readonly formulas?: boolean;
+}
+/**
+ * What every cell of a sheet holds, with the formulas run if asked.
+ *
+ * Shared by the exporters because both need the same answer and neither should be the one deciding
+ * it: what a cell shows is the sheet's business, and a second copy of that decision inside the CSV
+ * writer would drift from the component the first time a formula grows a new case.
+ *
+ * A formula that cannot be worked out comes out as its spreadsheet spelling — `#DIV/0!` and the
+ * rest — which is what Excel writes in the same situation and what the reader of the file expects
+ * to see.
+ */
+declare function sheetValues<TRow>(rows: readonly TRow[], columns: readonly HubSpreadsheetColumn<TRow>[], options?: HubSheetValuesOptions): HubSpreadsheetValue[][];
+
+/**
+ * What a cell shows for a formula that could not be worked out.
+ *
+ * The spreadsheet spellings rather than sentences: they fit in a cell, they are the same in every
+ * language, and anybody who has used a spreadsheet already knows what `#DIV/0!` means. They also
+ * travel — a file exported with `#DIV/0!` in a cell says the same thing to whoever opens it in
+ * Excel as it did here.
+ */
+declare const FORMULA_ERROR_TEXT: Record<HubFormulaFailure['code'], string>;
+/** Every spelling, for telling an error apart from something a reader typed. */
+declare const FORMULA_ERRORS: string[];
+/** What to show for a failure. */
+declare function formulaErrorText(failure: HubFormulaFailure): string;
+
+/**
+ * Registers the control adapter a sheet opens its list cells with.
+ *
+ * ```ts
+ * import { provideHubSpreadsheetControls } from 'ng-hub-ui-spreadsheet';
+ * import { hubFormControlAdapter } from 'ng-hub-ui-forms';
+ *
+ * providers: [provideHubSpreadsheetControls(hubFormControlAdapter)];
+ * ```
+ *
+ * Every list column then opens with that control, with no template written per sheet. A single
+ * column that needs something else still overrides it with `hubSpreadsheetEditor`, which wins.
+ *
+ * @param adapter - The implementation to use, e.g. `hubFormControlAdapter` from `ng-hub-ui-forms`.
+ * @returns Providers to add to the application, or to one component.
+ */
+declare function provideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProviders;
+
+/**
+ * The optional adapter a sheet renders its list cells through.
+ *
+ * Injected with `{ optional: true }`: absent means "draw the native list", which is what the
+ * library does on its own. Register it with {@link provideHubSpreadsheetControls}.
+ */
+declare const HUB_SPREADSHEET_CONTROLS: InjectionToken<HubSpreadsheetControlsAdapter>;
+
+/**
+ * Renders a cell's editor through the optional {@link HUB_SPREADSHEET_CONTROLS} adapter.
+ *
+ * Placed on an `<ng-container>` in the branch that only runs when an adapter is registered; the
+ * native list stays in the branch beside it as the answer that needs nothing installed. The
+ * control is created as a sibling of the anchor and torn down with it.
+ *
+ * The config is read once, when the editor opens. A cell editor lives for one decision — it opens,
+ * the reader chooses, it closes — so there is nothing to keep in sync afterwards, and the value
+ * arriving from elsewhere mid-edit is the case the sheet already refuses.
+ */
+declare class HubSpreadsheetControlDirective implements OnDestroy {
+    /** What to build. */
+    readonly config: _angular_core.InputSignal<HubSpreadsheetControlConfig>;
+    private readonly vcr;
+    private readonly adapter;
+    private handle;
+    constructor();
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSpreadsheetControlDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<HubSpreadsheetControlDirective, "[hubSpreadsheetControl]", never, { "config": { "alias": "hubSpreadsheetControl"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** English dictionary for the spreadsheet's own labels. */
+declare const locale$7: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** Spanish dictionary for the spreadsheet's own labels. */
+declare const locale$6: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** French dictionary for the spreadsheet's own labels. */
+declare const locale$5: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** German dictionary for the spreadsheet's own labels. */
+declare const locale$4: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** Russian dictionary for the spreadsheet's own labels. */
+declare const locale$3: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** Japanese dictionary for the spreadsheet's own labels. */
+declare const locale$2: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** Chinese dictionary for the spreadsheet's own labels. */
+declare const locale$1: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+/** Arabic dictionary for the spreadsheet's own labels. */
+declare const locale: {
+    lang: string;
+    data: {
+        INSERT_ROW_ABOVE: string;
+        INSERT_ROW_BELOW: string;
+        DELETE_ROWS: string;
+        INSERT_COLUMN_BEFORE: string;
+        INSERT_COLUMN_AFTER: string;
+        DELETE_COLUMNS: string;
+        MERGE_CELLS: string;
+        UNMERGE_CELLS: string;
+        ROW_ACTIONS: string;
+    };
+};
+
+export { FORMULA_ERRORS, FORMULA_ERROR_TEXT, HUB_FORMULA_FUNCTIONS, HUB_SPREADSHEET_CONTROLS, HubSpreadsheetCellDirective, HubSpreadsheetComponent, HubSpreadsheetControlDirective, HubSpreadsheetEditorDirective, XLSX_MEDIA_TYPE, applySpanMerge, applySpanUnmerge, applySuggestion, locale as arSpreadsheetLocale, columnIndexOf, columnLabel, csvToRecords, csvToTable, danglingColumnKeys, locale$4 as deSpreadsheetLocale, displayValue, downloadText, downloadXlsx, duplicateColumnKeys, locale$7 as enSpreadsheetLocale, locale$6 as esSpreadsheetLocale, evaluateFormula, evaluateSheet, formatCoordinate, formulaErrorText, formulaFragment, locale$5 as frSpreadsheetLocale, isFormula, isStructureAllowed, isTruthy, locale$2 as jaSpreadsheetLocale, mergeRequestFor, moveCoordinate, nextColumnKey, optionFor, parseClipboardTable, parseCoordinate, parseDecimal, parseForColumn, parseFormula, provideHubSpreadsheetControls, resolveInsertIndex, rewriteCoordinates, rewriteRowFormulas, locale$3 as ruSpreadsheetLocale, serialiseClipboardTable, sheetToCsv, sheetToXlsx, sheetValues, sniffDelimiter, spansWithin, spreadsheetRecord, spreadsheetRecords, suggestFormula, tableToRecords, xlsxToRecords, xlsxToTable, locale$1 as zhSpreadsheetLocale };
+export type { HubClipboardCell, HubClipboardPayload, HubClipboardWrite, HubCsvOptions, HubFormula, HubFormulaCellResult, HubFormulaContext, HubFormulaCoordinate, HubFormulaErrorCode, HubFormulaFailure, HubFormulaFragment, HubFormulaNode, HubFormulaOutcome, HubFormulaShapeChange, HubFormulaSheet, HubFormulaSheetInput, HubFormulaSuccess, HubFormulaSuggestion, HubFormulaValue, HubFormulaVocabulary, HubSheetTable, HubSheetValuesOptions, HubSpreadsheetAxis, HubSpreadsheetCell, HubSpreadsheetCellContext, HubSpreadsheetCellRef, HubSpreadsheetCellState, HubSpreadsheetColumn, HubSpreadsheetCommit, HubSpreadsheetControlConfig, HubSpreadsheetControlHandle, HubSpreadsheetControlLabelType, HubSpreadsheetControlOption, HubSpreadsheetControlsAdapter, HubSpreadsheetDeleteRequest, HubSpreadsheetEditorContext, HubSpreadsheetInsertRequest, HubSpreadsheetInsertSide, HubSpreadsheetMergeRequest, HubSpreadsheetOption, HubSpreadsheetPaste, HubSpreadsheetPermission, HubSpreadsheetRecord, HubSpreadsheetStructureOptions, HubSpreadsheetValue, HubSpreadsheetValueKind, HubXlsxOptions, HubXlsxReadOptions };