@trebco/treb 37.0.0 → 37.0.1

package/build/treb-grid/src/types/grid_base.d.ts

@@ -0,0 +1,442 @@
+/**
+ * grid base is a superclass for grid that takes over all (most) of the
+ * data operations, leaving UI operations (painting and interacting, plus
+ * layout) in the grid subclass.
+ *
+ * this is part of an effort to support running outside of the browser,
+ * but still using the command log to handle deltas.
+ *
+ * this turns out to be a little like the (old) layout where we had modern
+ * and legacy layouts -- a lot of stuff can be reused, but a lot can't.
+ *
+ * calling this "grid" doesn't really make sense anymore, but we're not in
+ * a hurry to change it either.
+ *
+ */
+import { EventSource } from 'treb-utils';
+import type { DataModel, ConditionalFormat, // MacroFunction, SerializedModel, SerializedNamedExpression, 
+ViewModel } from 'treb-data-model';
+import type { Parser } from 'treb-parser';
+import { Area } from 'treb-base-types';
+import type { ICellAddress, IArea, Cell, CellValue, Table, TableSortOptions, TableTheme, PatchOptions as PatchAreaOptions, Color } from 'treb-base-types';
+import { Sheet, type Annotation } from 'treb-data-model';
+import type { FunctionDescriptor } from '../editors/autocomplete_matcher';
+import { AutocompleteMatcher } from '../editors/autocomplete_matcher';
+import type { GridEvent } from './grid_events';
+import { ErrorCode } from './grid_events';
+import type { CommandRecord, CreateAnnotationCommand, DataValidationCommand, FreezeCommand, InsertColumnsCommand, InsertRowsCommand, RemoveAnnotationCommand, ResizeColumnsCommand, ResizeRowsCommand, SelectCommand, SetRangeCommand, ShowSheetCommand, SortTableCommand } from './grid_command';
+import { type GridOptions } from './grid_options';
+import type { Command, ActivateSheetCommand, DeleteSheetCommand, UpdateBordersCommand, SheetSelection } from './grid_command';
+import type { UpdateFlags } from './update_flags';
+import type { FreezePane, LegacySerializedSheet } from 'treb-data-model';
+interface PatchOptions extends PatchAreaOptions {
+    sheet: Sheet;
+}
+export declare class GridBase {
+    /** events */
+    grid_events: EventSource<GridEvent>;
+    /** for recording */
+    command_log: EventSource<CommandRecord>;
+    readonly model: DataModel;
+    readonly view: ViewModel;
+    get active_sheet(): Sheet;
+    set active_sheet(sheet: Sheet);
+    /** access the view index, if needed */
+    get view_index(): number;
+    /**
+     * switching to a stack, in case batching is nested. we don't need
+     * actual data so (atm) just count the depth.
+     */
+    protected batch: number;
+    /**
+     * if any batch method along the way requests a paint update, we
+     * want to toll it until the last batch call is complete, but we don't
+     * want to lose it. just remember to reset. [FIXME: isn't tolling this
+     * paint implicit, since it's async? ...]
+     */
+    protected batch_paint: boolean;
+    protected batch_events: GridEvent[];
+    /**
+     * single instance of AC. editors (function bar, ICE) have references.
+     * this is in base, instead of subclass, because we use it to check
+     * for valid names.
+     */
+    protected autocomplete_matcher: AutocompleteMatcher;
+    /**
+     * flags/state (used for some recordkeeping -- not super important)
+     */
+    protected flags: Record<string, boolean>;
+    /** */
+    protected options: GridOptions;
+    /**
+     * spreadsheet language parser. used to pull out address
+     * references from functions, for highlighting
+     *
+     * ...
+     *
+     * it's used for lots of stuff now, in addition to highlighting.
+     * copy/paste with translation; csv; defines; and some other stuff.
+     * still would like to share w/ parent though, if possible.
+     *
+     *
+     * FIXME: need a way to share/pass parser flags
+     * UPDATE: sharing parser w/ owner (embedded sheet)
+     */
+    protected parser: Parser;
+    constructor(options: GridOptions | undefined, model: DataModel);
+    RemoveConditionalFormat(options: {
+        format?: ConditionalFormat;
+        area?: IArea;
+    }): void;
+    AddConditionalFormat(format: ConditionalFormat): void;
+    /** remove a table. doesn't remove any data, just removes the overlay. */
+    RemoveTable(table: Table): void;
+    /**
+     * create a table in the given area. the area cannot contain any
+     * merge cells, arrays, or be part of another table. if you add a table
+     * with a totals row, we don't insert a new row -- allocate enough space
+     * when you create it.
+     *
+     * @param area - the total area for the table, including headers and totals
+     * @param totals - set true to include a totals row. tables have different
+     * formatting and slightly different behavior when there's a totals row.
+     */
+    InsertTable(area: IArea, totals?: boolean, sortable?: boolean | undefined, theme?: TableTheme): void;
+    /**
+     * activate sheet, by name or index number
+     * @param sheet number (index into the array) or string (name)
+     */
+    ActivateSheet(sheet: number | string, user?: boolean): void;
+    /**
+     * activate sheet, by ID
+     */
+    ActivateSheetID(id: number): void;
+    /**
+     * duplicate sheet by index or (omitting index) the current active sheet
+     */
+    DuplicateSheet(index?: number, name?: string, insert_before?: number | string): void;
+    AddSheet(name?: string): void;
+    /**
+     * delete sheet, by index or (omitting index) the current active sheet
+     */
+    DeleteSheet(index?: number): void;
+    /** insert sheet at the given index (or current index) */
+    InsertSheet(index?: number, name?: string): void;
+    DeleteSheetID(id: number): void;
+    /**
+     * clear sheet, reset all data
+     */
+    Reset(): void;
+    /**
+     * set hyperlink, like set note
+     */
+    SetLink(address: ICellAddress, reference?: string): void;
+    ShowAll(): void;
+    ShowSheet(index?: number | string, show?: boolean): void;
+    /**
+     * sort table. column is absolute.
+     */
+    SortTable(table: Table, options?: Partial<TableSortOptions>): void;
+    /** return freeze area */
+    GetFreeze(): FreezePane;
+    /**
+     * insert rows(s) at some specific point
+     */
+    InsertRows(before_row?: number, count?: number): void;
+    /**
+     * return the table (if any) at the given address
+     */
+    GetTableReference(address: ICellAddress): Table | undefined;
+    /**
+     * reset sheet, set data from CSV
+     *
+     * FIXME: this is problematic, because it runs around the exec command
+     * system. however it doesn't seem like a good candidate for a separate
+     * command. it should maybe move to the import class? (...)
+     *
+     * one problem with that is that import is really, really heavy (jszip).
+     * it seems wasteful to require all that just to import csv.
+     */
+    FromCSV(text: string): void;
+    /**
+     * insert column(s) at some specific point
+     */
+    InsertColumns(before_column?: number, count?: number): void;
+    /** move sheet (X) before sheet (Y) */
+    ReorderSheet(index: number, move_before: number): void;
+    /**
+     * rename active sheet
+     */
+    RenameSheet(sheet: Sheet, name: string): void;
+    /**
+     * freeze rows or columns. set to 0 (or call with no arguments) to un-freeze.
+     *
+     * highglight is shown by default, but we can hide it(mostly for document load)
+     */
+    Freeze(rows?: number, columns?: number, highlight_transition?: boolean): void;
+    /**
+     * API method
+     */
+    SetRowHeight(row?: number | number[], height?: number, shrink?: boolean): void;
+    /**
+     * API method
+     *
+     * @param column - column, columns, or undefined means all columns
+     * @param width - target width, or undefined means auto-size
+     * @param allow_shrinking - for auto-size, allow shrinking. defaults to true.
+     * set false to disallow shrinking.
+     */
+    SetColumnWidth(column?: number | number[], width?: number, allow_shrinking?: boolean): void;
+    /**
+     * filter table. what this means is "show the rows that match the filter
+     * and hide the other rows". it doesn't actually change data, but it does
+     * show/hide rows which (now) has some data effects.
+     *
+     * note that we don't pass the filter command through the command queue.
+     * it uses a callback, so that would not work. rather we filter first,
+     * then send hide/show row commands through the command queue. that will
+     * propagate updates.
+     */
+    FilterTable(table: Table, column: number, filter: (cell: Cell) => boolean): void;
+    /**
+     * UpdateSheets means "set these as the sheets, drop any old stuff". there's
+     * an implicit reset (in fact we may do that twice in some cases).
+     *
+     * this is non-UI; specialization should handle the UI part
+     */
+    UpdateSheets(data: LegacySerializedSheet[], render?: boolean, activate_sheet?: number | string): void;
+    /**
+     * set functions for AC matcher. should be called by calculator on init,
+     * or when any functions are added/removed.
+     *
+     * FIXME: we should use this to normalize function names, on insert and
+     * on paste (if we're doing that).
+     *
+     * FIXME: are named expressions included here? (this function predates
+     * named expressions).
+     *
+     *
+     * this moved to grid base because we use the list to check for conflicts
+     * when setting names.
+     *
+     */
+    SetAutocompleteFunctions(functions: FunctionDescriptor[]): void;
+    ResetMetadata(): void;
+    /**
+     * see ResizeRowsInternal
+     */
+    protected ResizeColumnsInternal(command: ResizeColumnsCommand): void;
+    protected RemoveAnnotationInternal(command: RemoveAnnotationCommand): void;
+    /** placeholder */
+    protected CreateAnnotationInternal(command: CreateAnnotationCommand): void;
+    /**
+     * resize rows. this supports auto size, but that will fail in !ui grid,
+     * because it uses HTML. also non-ui doesn't really need to worry about
+     * scale... we should split.
+     */
+    protected ResizeRowsInternal(command: ResizeRowsCommand): IArea | undefined;
+    protected ResetInternal(): void;
+    /**
+     * check if we can paste into the target area(s). this will
+     * return false if the areas contain locked cells, or part of
+     * an array or merge but not the whole array or merge.
+     *
+     * @param areas
+     * @returns
+     */
+    protected ValidatePasteAreas(areas: Area[]): boolean;
+    protected SetValidationInternal(command: DataValidationCommand): void;
+    /**
+     * get values from a range of data
+     * @param area
+     */
+    protected GetValidationRange(area: IArea): CellValue[] | undefined;
+    /**
+     * @returns true if we need a recalc, because references have broken.
+     */
+    protected DeleteSheetInternal(command: DeleteSheetCommand): boolean;
+    /**
+     * rename a sheet. this requires changing any formulae that refer to the
+     * old name to refer to the new name. if there are any references by ID
+     * those don't have to change.
+     *
+     * FIXME: can we do this using the dependency graph? (...)
+     */
+    protected RenameSheetInternal(target: Sheet, name: string): void;
+    /**
+     *
+     */
+    protected SortTableInternal(command: SortTableCommand): Area | undefined;
+    /**
+     * update all columns of a table (collect column names). this
+     * method rebuilds all columns; that's probably unecessary in
+     * many cases, but we'll start here and we can drill down later.
+     *
+     * we do two things here: we normalize column header values, and
+     * we collect them for table headers.
+     *
+     * @param table
+     */
+    protected UpdateTableColumns(table: Table): IArea;
+    /**
+     * set range, via command. returns affected area.
+     *
+     * Adding a flags parameter (in/out) to support indicating
+     * that we need to update layout.
+     */
+    protected SetRangeInternal(command: SetRangeCommand, flags?: UpdateFlags): Area | undefined;
+    /**
+     * basic implementation does not handle any UI, painting, or layout.
+     */
+    protected ActivateSheetInternal(command: ActivateSheetCommand): void;
+    protected ShowSheetInternal(command: ShowSheetCommand): void;
+    /**
+     * normalize commands. for co-editing support we need to ensure that
+     * commands properly have sheet IDs in areas/addresses (and explicit
+     * fields in some cases).
+     *
+     * at the same time we're editing the commands a little bit to make
+     * them a little more consistent (within reason).
+     *
+     * @param commands
+     */
+    protected NormalizeCommands(commands: Command | Command[]): Command[];
+    TabColor(sheet: Sheet, color?: Color): void;
+    /**
+     * add sheet. data only.
+     */
+    protected AddSheetInternal(name?: string, insert_index?: number): number | undefined;
+    /**
+     * resolve sheet in a command that uses the SheetSelection interface;
+     * that allows sheet selection by name, id or index.
+     */
+    protected ResolveSheet(command: SheetSelection): Sheet | undefined;
+    /**
+     * find sheet matching sheet_id in area.start, or active sheet
+     *
+     * FIXME: should return undefined on !match
+     * FIXME: should be in model, which should be a class
+     */
+    protected FindSheet(identifier: number | IArea | ICellAddress | undefined): Sheet;
+    /**
+     * this function now works for both rows and columns, and can handle
+     * sheets other than the active sheet. it does assume that you only ever
+     * add rows/columns on the active sheet, but since that's all parameterized
+     * you could get it to work either way.
+     *
+     * in fact we should change the names of those parameters so it's a little
+     * more generic.
+     */
+    protected PatchFormulasInternal(source: string, before_row: number, row_count: number, before_column: number, column_count: number, target_sheet_name: string, is_target: boolean): string | undefined;
+    protected PatchExpressionSheetName(expression: string, old_name: string, name: string): string | undefined;
+    /**
+     * splitting this logic into a new function so we can reuse it
+     * for invalidating broken references. generally we'll call this
+     * on all sheets, but I wanted to leave the option open.
+     *
+     * @returns count of changes made. it's useful for the delete routine,
+     * so we can force a recalc.
+     */
+    protected RenameSheetReferences(sheets: Sheet[], old_name: string, name: string): number;
+    /**
+     * these are all addative except for "none", which removes all borders.
+     *
+     * we no longer put borders into two cells at once (hurrah!). however
+     * we still need to do some maintenance on the mirror cells -- because
+     * if you apply a border to cell A1, then that should take precedence
+     * over any border previously applied to cell A2.
+     *
+     * FIXME: is that right? perhaps we should just leave whatever the user
+     * did -- with the exception of clearing, which should always mirror.
+     *
+     *
+     * UPDATE: modifying function for use with ExecCommand. runs the style
+     * updates and returns the affected area.
+     *
+     */
+    protected ApplyBordersInternal(command: UpdateBordersCommand): Area;
+    protected TranslateR1C1(address: ICellAddress, value: CellValue): CellValue;
+    protected ClearAreaInternal(area: Area): void;
+    /**
+     * send an error message. subscriber can figure out how to communicate it
+     * to users.
+     *
+     * dropping strings, now we only allow error constants (via enum)
+     *
+     * @param message
+     */
+    protected Error(message: ErrorCode): void;
+    /**
+     * this breaks (or doesn't work) if the add_tab option is false; that's
+     * fine, although we might want to make a distinction between UI add-tab
+     * and API add-tab. And allow it from the API.
+     *
+     * @param command
+     * @returns
+     */
+    private DuplicateSheetInternal;
+    /**
+     * this is the callback method for the command-log select command
+     * (which is not widely used). it does nothing. the specialization
+     * should do something.
+     *
+     * @param command
+     */
+    protected SelectInternal(command: SelectCommand): void;
+    protected FreezeInternal(command: FreezeCommand): void;
+    /**
+     * patch an expression for insert/delete row/column operations.
+     * FIXME: should move, maybe to parser? (...)
+     *
+     * NOTE: did I write this twice? we only need one. check which one is better.
+     * @see PatchFormulasInternal
+     *
+     * @returns the updated expression, or `undefined` if no changes were made.
+     */
+    protected PatchExpression(expression: string, options: PatchOptions): string | undefined;
+    /**
+     * patch sheet conditionals for insert/delete row/column operations.
+     * some of them may be deleted.
+     *
+     * UPDATE: using this routine to also patch data validations
+     */
+    protected PatchConditionalsAndValidations(options: PatchOptions): void;
+    /**
+     * FIXME: should be API method
+     * FIXME: need to handle annotations that are address-based
+     *
+     * @see InsertColumns for inline comments
+     */
+    protected InsertRowsInternal(command: InsertRowsCommand): {
+        error?: boolean;
+        update_annotations_list?: Annotation[];
+        resize_annotations_list?: Annotation[];
+        delete_annotations_list?: Annotation[];
+    };
+    /**
+     *
+     */
+    protected InsertColumnsInternal(command: InsertColumnsCommand): {
+        error?: boolean;
+        update_annotations_list?: Annotation[];
+        resize_annotations_list?: Annotation[];
+        delete_annotations_list?: Annotation[];
+    };
+    /**
+     * pass all data/style/structure operations through a command mechanism.
+     * this method should optimally act as a dispatcher, so try to minimize
+     * inline code in favor of method calls.
+     *
+     * [NOTE: don't go crazy with that, some simple operations can be inlined]
+     *
+     * NOTE: working on coediting. we will need to handle different sheets.
+     * going to work one command at a time...
+     *
+     * @param queue -- push on the command log. this is default true so it
+     * doesn't change existing behavior, but you can turn it off if the message
+     * comes from a remote queue.
+     *
+     */
+    ExecCommand(commands: Command | Command[], queue?: boolean): UpdateFlags;
+}
+export {};