@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/sheet/_SheetEvents.d.ts

@@ -0,0 +1,43 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * The kinds of change a sheet announces from its commits, and the scope they are announced
+ * under.
+ *
+ * @remarks
+ * Every mutation appends the ranges it wrote under one of these, so a commit carries what to
+ * announce rather than what its last operation changed. The categories are recorded as the
+ * `sheet.events` intent (`_SheetIntents`), so they are unioned across the operations of a batch
+ * and travel on the commit, which is what lets an undo announce the same categories the forward
+ * commit did.
+ *
+ * The scope is {@link ISheet.getId}, so a commit that spans sheets announces each of them
+ * separately.
+ *
+ * @internal
+ */
+/**
+ * A category of change to announce, named after the mutation kind that produces it.
+ *
+ * @remarks
+ * * `data` - cell values written, cleared or pasted.
+ * * `style` - styles and number formats.
+ * * `comments` - comments and notes.
+ * * `hyperlinks` - hyperlinks.
+ * * `merges` - merge and unmerge.
+ * * `spills` - spill regions written or cleared.
+ * * `address` - a structural shift: an insert, a delete or a move of cells.
+ * * `layout` - sizes and hidden runs.
+ * * `anchored` - a model anchored over a range: a table, a conditional format, a validation, a
+ *   protected range.
+ * * `sheets` - the sheet itself, over the cells a reader of it may now read differently. A rename
+ *   is one: every cross-sheet formula naming it resolves again.
+ *
+ * `data`, `style`, `merges`, `spills`, `address` and `layout` each have an event of their own;
+ * the rest reach a consumer only through the union. A consumer that wants "did anything happen in
+ * my box" takes the union rather than naming categories, so a category added later cannot
+ * silently stop reaching it.
+ */
+export type EventCategory = 'data' | 'style' | 'comments' | 'hyperlinks' | 'merges' | 'spills' | 'address' | 'layout' | 'anchored' | 'sheets';
+/** What one sheet has to announce from a commit, by category. */
+export type SheetEvents = Readonly<Partial<Record<EventCategory, readonly IRange.Coords[]>>>;
+//# sourceMappingURL=_SheetEvents.d.ts.map

package/types/src/sheet/_SheetFilterUtils.d.ts

@@ -1,9 +1,57 @@
 import { IRange } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { ICondition } from '../condition';
+import { NumberFormatRef } from '../numFmt/BuiltInFormats';
+import { ISheet } from './ISheet';
 import { Sheet } from './Sheet';
+/** A run of one column's rows that show their values under the same number format. */
+export interface TextFormatRun {
+    rowStart: number;
+    rowEnd: number;
+    format: NumberFormatRef;
+}
 /**
- * Sheet specific filter utils. Mirrors `_SheetSortUtils.doSort`.
+ * The rows of a column by the number format they show their values under, ascending and
+ * covering `coords`; adjacent rows of one format are one run.
+ *
+ * @remarks
+ * What a cell shows follows from its value and its number format. The formats lie in few runs
+ * whatever the number of rows, so a reader of the column's text formats values and builds no cell.
+ */
+export declare function getTextFormatRuns(sheet: ISheet, coords: Readonly<IRange.Coords>): TextFormatRun[];
+/**
+ * What a filter evaluation settles: on one axis, the runs that stay visible and the runs that hide.
+ *
+ * @remarks
+ * The two halves of a filter are split so a caller with its own transaction (a table, which also
+ * writes its levels) can evaluate first and write inside: {@link evalFilter} may await a calc, and
+ * a transaction never stays open across an await.
+ */
+export interface FilterRuns {
+    /** The axis the runs index. */
+    axis: IRange.Axis;
+    /** The runs that match every condition, ascending. */
+    visibleRuns: readonly RunCoords[];
+    /** The runs that fail one, ascending. */
+    hiddenRuns: readonly RunCoords[];
+}
+/**
+ * Read-only: resolves every condition and settles the final visible and hidden runs.
+ */
+export declare function evalFilter(sheet: Sheet, coords: Readonly<IRange.Coords>, condition: ICondition.Input | ICondition.RangeOptions | null | undefined): Promise<FilterRuns>;
+/**
+ * Writes the hidden bits {@link evalFilter} settled. Inside the caller's open transaction.
+ *
+ * @remarks
+ * Full recompute, every apply (DESIGN-FILTER.md §2): unhide every row/column that now matches,
+ * then hide every row/column that doesn't — including one the user hid manually, matching real
+ * Excel AutoFilter (there's no persisted "hidden by filter" vs. "hidden by user" bit to preserve).
+ */
+export declare function applyFilterRuns(sheet: Sheet, runs: FilterRuns, options?: ITransaction.OperationOptions): void;
+/**
+ * Sheet specific filter utils. Mirrors `_SheetSortUtils.doSort`: {@link evalFilter}, then one
+ * transaction around {@link applyFilterRuns}.
  */
 export declare function doFilter(sheet: Sheet, coords: Readonly<IRange.Coords>, condition: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): Promise<IRange.Coords>;
 //# sourceMappingURL=_SheetFilterUtils.d.ts.map

package/types/src/sheet/_SheetIntents.d.ts

@@ -0,0 +1,296 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICellRange } from '../cellRange';
+import { IMovable } from '../movable';
+import { IMovableSelection, IRangeSelection } from '../selection';
+import { ITransaction } from '../transaction';
+import { ISheet } from './ISheet';
+import { SheetEvents } from './_SheetEvents';
+/**
+ * Directives a sheet operation records on its transaction: something to do once the operation
+ * completes, rather than a change the operation makes.
+ *
+ * @remarks
+ * All coords, ids and options - no sheet, view or range instances. An intent is recorded on the
+ * root transaction, so a batch of operations resolves one set of them, and it travels on the
+ * commit, so undo and redo read it back.
+ *
+ * @internal
+ */
+/** Key for the {@link EventsIntent}. */
+export declare const IntentEvents = "sheet.events";
+/** Key for the {@link FormulasEnteredIntent}. */
+export declare const IntentFormulasEntered = "sheet.formulasEntered";
+/** Key for the {@link SelectionIntent}`[]` the operations of a commit declared. */
+export declare const IntentSelection = "sheet.selection";
+/** Key for the {@link BatchSelectIntent}. */
+export declare const IntentBatchSelect = "sheet.batchSelect";
+/** Key for {@link AutoFitIntent}`[]`. */
+export declare const IntentAutoFit = "sheet.autoFit";
+/**
+ * Key for the sheet ids ({@link ISheet.getId}) whose commit-time protection check stands down.
+ *
+ * @remarks
+ * The catch-all at `onBeforeCommitStart` refuses any write to a locked sheet. An operation that
+ * has already ruled on its own allowance (`Sheet._protectionCheck`) records itself here so the
+ * catch-all does not veto what the allowance permitted; so does a load, which is not a user's
+ * write. Read on the way in, so it has to be on the record before the root commits.
+ */
+export declare const IntentSkipProtectionCheck = "sheet.skipProtectionCheck";
+/** Key for the {@link FreezePanesIntent}. */
+export declare const IntentFreezePanes = "sheet.freezePanes";
+/** Key for the {@link MovableSelectionIntent}`[]` the operations of a commit declared. */
+export declare const IntentMovableSelection = "sheet.movableSelection";
+/**
+ * Key for the sheet ids ({@link ISheet.getId}) a load is populating in this commit.
+ *
+ * @remarks
+ * A load is not an edit: nothing it writes is announced, and the calculation it would otherwise
+ * trigger is the calc-on-load decision's to make, not the commit's. The writes inside a load go
+ * through the same mutation paths as an edit and record the same changes (an added table records
+ * `anchored`), so the announce has to be told to stand down for the commit as a whole. Implies
+ * {@link IntentSkipProtectionCheck}.
+ */
+export declare const IntentInitial = "sheet.initial";
+/**
+ * Key for the sheet ids ({@link ISheet.getId}) whose entered formulas should take the number
+ * format of the first cell they read that has one, or failing that the format their results
+ * carry, once the compile and the calculation have them.
+ *
+ * @remarks
+ * The one directive that cannot be resolved when the operation completes: the result it formats,
+ * and the engine's word on which cells the formula reads, do not exist yet. It is resolved by the
+ * calculation's amend into this commit (`Sheet._promoteCalcResults`), and only once - see
+ * {@link IntentCalcResolved}.
+ */
+export declare const IntentAutoFormat = "sheet.autoFormat";
+/**
+ * Key for the sheet ids whose entry directives the calculation has resolved for this commit.
+ *
+ * @remarks
+ * Recorded by the calculation's amend once it has formatted and fitted the results of the
+ * formulas the commit entered on that sheet. A later pass for the same commit - a dependent on
+ * another sheet, an explicit recalculation, the pass a redo triggers - finds the sheet here and
+ * leaves the promoted format and the sizes as they are, which is also why an undo and a redo see
+ * them: they are in the snapshot, not re-derived.
+ */
+export declare const IntentCalcResolved = "sheet.calcResolved";
+/**
+ * What to announce once the operation lands, by sheet ({@link ISheet.getId}) and by category.
+ *
+ * @remarks
+ * The one intent every mutation writes. A union: each write appends the ranges it wrote, so a
+ * batch describes all of its operations rather than its last, and an amend unions into the commit
+ * it folds into. Written copy-on-write ({@link Sheet._recordChange}), because an amend's
+ * accumulator is handed the TARGET commit's value as its `prev` and must not mutate it.
+ *
+ * What it holds is not "what was touched" - a registration amend writes state and deliberately
+ * records nothing - but what a consumer has to hear about. Six of the categories have an event of
+ * their own; the rest reach a consumer through the union ({@link Sheet._changedRanges}), which is
+ * also what an undo selects over and what gates the calculation.
+ */
+export type EventsIntent = Readonly<Record<string, SheetEvents>>;
+/**
+ * The ranges a formula was entered over, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * A subset of the `data` category, found from what the write produced rather than named by the
+ * caller - a cleared formula is a data change and nothing more. No event fires for it: it is read
+ * by the calculation's amend (`Sheet._promoteCalcResults`) to decide what to format and what to
+ * fit, which is Excel's rule that entering a formula formats and fits it while recalculating it
+ * does not.
+ */
+export type FormulasEnteredIntent = Readonly<Record<string, readonly IRange.Coords[]>>;
+/**
+ * `list` with `ranges` appended, for an intent accumulator that unions range lists.
+ *
+ * @param list The list on the record so far, or none.
+ * @param ranges What this write adds.
+ * @param owner The id of the operation recording it ({@link ITransaction.getId}).
+ *
+ * @remarks
+ * An accumulator must not change the value it is handed: on a fold that value is the TARGET
+ * commit's, and a list the target announces would grow by what the amend recorded. A list this
+ * operation built is a different matter - nothing else holds it until the operation lands - so it
+ * is appended to, and only a list from elsewhere is copied first. Without that, a batch of one
+ * write per cell copies every range recorded so far on each write, and so does the replay of those
+ * writes when the batch folds.
+ */
+export declare const _appendOwnedRanges: (list: readonly IRange.Coords[] | undefined, ranges: readonly IRange.Coords[], owner: string) => readonly IRange.Coords[];
+/**
+ * What one operation declared about the selection: where it leaves the user, and where an undo of
+ * it lands when that is somewhere else.
+ *
+ * @remarks
+ * Every operation declares, whatever it was asked, and never applies: whether the view moves, and
+ * which declaration it moves to, is decided once the commit closes ({@link resolveSelection}). So
+ * an operation neither reads the transaction stack nor decides whether it is the one that counts,
+ * and a replay can apply a different policy to the same record.
+ *
+ * Entries are kept in the order they were declared, one per operation, so a batch holds all of
+ * its operations'.
+ */
+export interface SelectionIntent {
+    /** {@link ISheet.getId} of the sheet the selection is on. */
+    sheetId: string;
+    /**
+     * {@link ISheetView.getId} of the view the operation was made against.
+     *
+     * @remarks
+     * A sheet can be shown through more than one view - each user in a shared workbook has their
+     * own - and only the view that made the change is moved by undoing it.
+     */
+    viewId: string;
+    /** Where the operation leaves the user, and where a redo of it lands. */
+    selection: Partial<IRangeSelection.Coords>;
+    /**
+     * Where an undo of the operation lands, when it is not {@link selection}: an auto-fill undoes
+     * to the template it was dragged from, a cut-drag to the source.
+     */
+    undo?: Partial<IRangeSelection.Coords>;
+    /**
+     * The operation's `autoSelect`, resolved against its axis (see `Sheet._resolveSelectOptions`),
+     * or `false` when it was not asked to select.
+     */
+    options: boolean | ICellRange.SelectOptions;
+    /** The operation's `autoSelectRestore`, resolved like {@link options}: whether an undo or a redo selects. */
+    restoreOptions: boolean | ICellRange.SelectOptions;
+    /**
+     * The operation ran inside another one ({@link _isInsideOperation}): the writes a table makes
+     * when it expands are the expansion's, and where they would put the user is not the
+     * expansion's to say.
+     */
+    nested: boolean;
+}
+/**
+ * The `autoSelect` a batch was opened with, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * A batch asks to select for the operations inside it that did not ask for themselves: a command
+ * groups a per-range loop and selects the result, and the operations in the loop were never told.
+ */
+export type BatchSelectIntent = Readonly<Record<string, boolean | ICellRange.SelectOptions>>;
+/**
+ * Whether `trans` is begun inside a transaction that names an operation
+ * ({@link ITransaction.getOperation}).
+ *
+ * @remarks
+ * An enclosing transaction that names no operation - a batch - is not one.
+ */
+export declare const _isInsideOperation: (trans: ITransaction) => boolean;
+/**
+ * Where a commit moves a view's selection, or `null` when it does not move it.
+ *
+ * @param intents The commit's intents.
+ * @param sheetId The sheet whose view is asking.
+ * @param viewId The view that is asking.
+ * @param direction Whether the operation has just run, or is being undone or redone.
+ *
+ * @remarks
+ * The local policy. Only an operation that is not part of another one counts, and only one that
+ * was asked to select - itself, or by the batch it ran in: by `autoSelect` as it runs, by
+ * `autoSelectRestore` when it is undone or redone. A script that did not ask never moves the user,
+ * and neither does anything that reacts to the user's edit. Forward and redo land where the LAST
+ * such operation left the user; an undo lands where the FIRST one says, since a batch is undone
+ * as a whole.
+ */
+export declare const resolveSelection: (intents: Readonly<Record<string, any>> | undefined, sheetId: string, viewId: string, direction: "forward" | "undo" | "redo") => {
+    selection: Partial<IRangeSelection.Coords>;
+    options: boolean | ICellRange.SelectOptions;
+} | null;
+/**
+ * Where the freeze panes sit before and after the operation, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * The one view fact an insert or delete changes: a frozen row above the insertion point moves
+ * with the cells. Recorded only by an operation that moved them, and merged the way the
+ * selection pair is - `before` first-writer-wins, `after` last-writer-wins - so a batch undoes to
+ * where it started and redoes to where it ended. The forward operation moves the panes itself;
+ * this is what undo and redo read.
+ */
+export type FreezePanesIntent = Readonly<Record<string, {
+    before: IRange.CellCoords;
+    after: IRange.CellCoords;
+}>>;
+/**
+ * What one operation declared about the movable selection: what it leaves selected, and what was
+ * selected when it began.
+ *
+ * @remarks
+ * The movable counterpart of {@link SelectionIntent}, kept the same way: every operation that
+ * changes which movables exist or which of them the user is working on declares, whether or not
+ * it was asked to select, and whether the view moves - now, on undo or on redo - is decided once,
+ * when the commit closes ({@link resolveMovableSelection}). Entries are kept in the order they
+ * were declared, one per operation, so a batch holds all of its operations'.
+ *
+ * Movables are named by their id ({@link ITransaction.ITransactional.getId}). A snapshot restores
+ * the same instances, so holding them would work - but an intent is data, and an id is what
+ * survives a reload and a collaborator.
+ */
+export interface MovableSelectionIntent {
+    /** {@link ISheet.getId} of the sheet the movables are on. */
+    sheetId: string;
+    /**
+     * {@link ISheetView.getId} of the view the operation was made against.
+     *
+     * @remarks
+     * Only the view that made the change is moved by it - see {@link SelectionIntent}.
+     */
+    viewId: string;
+    /** What the operation leaves selected, the active one last; where a redo lands. */
+    selection: readonly string[];
+    /** {@link selection} extends what the operations before it left selected, rather than replacing it. */
+    add: boolean;
+    /** What was selected when the operation began, the active one last; where an undo lands. */
+    undo: readonly string[];
+    /** Whether the operation selects as it runs: its `autoSelect`. */
+    options: boolean;
+    /** Whether an undo or a redo of the operation selects: its `autoSelectRestore`. */
+    restoreOptions: boolean;
+}
+/**
+ * What `selection` holds, the active one last: the order {@link IMovableSelection.select} takes to
+ * select it again.
+ */
+export declare const pickOrder: (selection: IMovableSelection) => readonly IMovable[];
+/**
+ * Declare what an operation leaves selected on `sheet`'s view. See {@link MovableSelectionIntent}.
+ *
+ * @param trans The operation's transaction.
+ * @param sheet The sheet the movables are on.
+ * @param selection What the operation leaves selected, the active one last.
+ * @param options The operation's own options, passed through as they were given.
+ * @param undo What was selected when the operation began, the active one last, when the view no
+ * longer says: the operation has deleted what was selected.
+ */
+export declare const recordMovableSelection: (trans: ITransaction, sheet: ISheet, selection: readonly IMovable[], options?: Pick<IMovable.OperationOptions, "autoSelect" | "autoSelectRestore"> | null, undo?: readonly IMovable[]) => void;
+/**
+ * The movables a commit selects on a view, by id with the active one last, or `null` when it
+ * leaves the selection alone.
+ *
+ * @param intents The commit's intents.
+ * @param sheetId The sheet whose view is asking.
+ * @param viewId The view that is asking.
+ * @param direction Whether the operation has just run, or is being undone or redone.
+ *
+ * @remarks
+ * Only an operation that was asked to select counts: by `autoSelect` as it runs, by
+ * `autoSelectRestore` when it is undone or redone. An undo lands where the FIRST such operation
+ * began, since a batch is undone as a whole. Forward and redo land where the operations left the
+ * user, taken in order: one that adds extends what the ones before it left, any other replaces it.
+ */
+export declare const resolveMovableSelection: (intents: Readonly<Record<string, any>> | undefined, sheetId: string, viewId: string, direction: "forward" | "undo" | "redo") => readonly string[] | null;
+/**
+ * Fit these ranges when the operation completes.
+ *
+ * @remarks
+ * A union: every operation in a batch adds the ranges it wrote, and one fit covers them all.
+ * Entries are kept per sheet and per option set - two operations that fit differently cannot
+ * be measured as one.
+ */
+export interface AutoFitIntent {
+    /** {@link ISheet.getId} of the sheet to fit on. */
+    sheetId: string;
+    ranges: IRange.Coords[];
+    options?: ICellRange.AutoFitOptions;
+}
+//# sourceMappingURL=_SheetIntents.d.ts.map