@trebco/treb 23.6.2 → 25.0.0-rc1

package/{treb.d.ts → build/treb.d.ts}

@@ -1,100 +1,229 @@
-/*! API v23.6. Copyright 2018-2023 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v25.0.0-rc1. Copyright 2018-2023 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
-/** 
- * Global instance. In the base script, this object will be created as an
- * ambient global object (bound to the window object). If you instead use the
- * ES module, import the TREB object from the module.
+/**
+ * add our tag to the map
  */
- declare const TREB: TREBGlobal;
-
+declare global {
+  interface HTMLElementTagNameMap {
+    'treb-spreadsheet': HTMLElement & {
+      sheet: EmbeddedSpreadsheet|undefined;
+    };
+  }
+}
 /**
- * global object used to create spreadsheets
+ * API class for creating spreadsheets. this is intended as a singleton,
+ * we will export an instance of the class.
  */
 export declare class TREBGlobal {
 
-  /** TREB version */
-  version: string;
-
-  /** create a spreadsheet */
-  CreateSpreadsheet(options: EmbeddedSpreadsheetOptions): EmbeddedSpreadsheet;
+    /**
+     * build version
+     */
+    version: string;
 
+    /**
+     * create a spreadsheet instance
+     */
+    CreateSpreadsheet(options: EmbeddedSpreadsheetOptions): EmbeddedSpreadsheet;
 }
-/**
- * options for saving files. we add the option for JSON formatting.
- */
-export interface SaveOptions extends SerializeOptions {
 
-    /** pretty json formatting */
-    pretty?: boolean;
-}
+/** single instance of factory class */
+export declare const TREB: TREBGlobal;
 
 /**
- * options for the LoadDocument method
+ * options for creating spreadsheet
  */
-export interface LoadDocumentOptions {
+export interface EmbeddedSpreadsheetOptions {
+
+    /** containing HTML element */
+    container?: string | HTMLElement;
+
+    /** allow drag-and-drop files */
+    dnd?: boolean;
+
+    /** expandable grid */
+    expand?: boolean;
+
+    /**
+     * key in localStorage for persisting document. it's possible
+     * to set this to boolean `true`, in which case we will generate
+     * a storage key based on the page URI.
+     *
+     * this can be convenient for quickly setting up a document, but don't
+     * use it if the page URI might change (the storage will get lost)
+     * or if there are multiple spreadsheets on the same page (they will
+     * overwrite each other).
+     */
+    storage_key?: string | boolean;
+
+    /** don't load immediately (?) */
+    toll_initial_load?: boolean;
+
+    /** show formula bar. default true. */
+    formula_bar?: boolean;
+
+    /** expand formula bar */
+    expand_formula_button?: boolean;
+
+    /** scroll to cell on load */
     scroll?: string | ICellAddress;
-    flush?: boolean;
+
+    /** sheet to show on load, overrides anything in the model */
+    sheet?: string;
+
+    /** add resizable wrapper */
+    resizable?: boolean;
+
+    /** export to xlsx, now optional */
+    export?: boolean;
+
+    /** fill container */
+    auto_size?: boolean;
+
+    /** fetch network document (URI) */
+    network_document?: string;
+
+    /** freeze rows */
+    freeze_rows?: number;
+
+    /** freeze columns */
+    freeze_columns?: number;
+
+    /** row/column headers */
+    headers?: boolean;
+
+    /** recalculate on load */
     recalculate?: boolean;
-    override_sheet?: string;
-}
 
-/**
- * options for the GetRange method
- */
-export interface GetRangeOptions {
+    /** show scrollbars */
+    scrollbars?: boolean;
+
+    /** show tab bar (multi sheet) */
+    tab_bar?: boolean | 'auto';
+
+    /** allow add tab */
+    add_tab?: boolean;
+
+    /** show delete tab */
+    delete_tab?: boolean;
+
+    /** set a reference in global (self) */
+    global_name?: string;
+
+    /** support undo */
+    undo?: boolean;
+
+    /** support in-cell editor */
+    in_cell_editor?: boolean;
+
+    /** prompt "you have unsaved changes" */
+    prompt_save?: boolean;
 
     /**
-     * return formatted values (apply number formats and return strings)
-     * @deprecated
+     * toolbar display option
      */
-    formatted?: boolean;
+    toolbar?: boolean | 'show' | 'narrow' | 'show-narrow';
 
-    /**
-     * return formulas instead of values. formula takes precedence over
-     * "formatted"; if you pass both, returned values will *not* be formatted.
-     * @deprecated
-     *
-     **/
-    formula?: boolean;
+    /** file options in the toolbar */
+    file_menu?: boolean;
+
+    /** font size in the toolbar */
+    font_scale?: boolean;
+
+    /** show insert/remove table button in toolbar */
+    table_button?: boolean;
+
+    /** show freeze button in toolbar */
+    freeze_button?: boolean;
+
+    /** chart menu in the toolbar */
+    chart_menu?: boolean;
+
+    /** recalculate button in the toolbar */
+    toolbar_recalculate_button?: boolean;
+
+    /** new option, better support for headless operations (default false) */
+    headless?: boolean;
+
+    /** max size for image, in bytes */
+    max_file_size?: number;
+
+    /** initial scale */
+    scale?: number;
+
+    /** show scale buttons */
+    scale_control?: boolean;
+
+    /** show stats panel */
+    stats?: boolean;
+
+    /** save/load scale. this can optionally have a string key to disambiguate */
+    persist_scale?: boolean | string;
+
+    /** target window for hyperlinks (default _blank); set false to disable hyperlinks altogether */
+    hyperlinks?: string | false;
 
     /**
-     * optional style for returned values (replaces old flags).
+     * enable handling complex numbers in function calculation. turning this
+     * off doesn't actually disable complex numbers. it means that functions
+     * will not return complex numbers unless one of the arguments is complex.
      *
-     * @remarks
+     * for example, if complex numbers are off, `=SQRT(-1)` will return `#VALUE`.
+     * if complex numbers are on, `=SQRT(-1)` will return `i`.
      *
-     * `formatted` returns formatted values, applying number formatting and
-     * returning strings. `formula` returns cell formulas instead of values.
+     * even if complex numbers are off, however, `=SQRT(-1 + 0i)` will return
+     * `i` because the argument is complex.
+     *
+     * currently this behavior applies to `SQRT`, `POWER` and the exponentiation
+     * operator `^`.
+     *
+     * in version 22, this defaults to `off`.
      */
-    type?: 'formatted' | 'formula';
-}
+    complex?: 'on' | 'off';
 
-/**
- * options for the ScrollTo method.
- *
- * @remarks
- *
- * this method was renamed because of a conflict with a DOM type,
- * which was causing problems with the documentation generator.
- */
-export interface SheetScrollOptions {
+    /**
+     * for rendering the imaginary number. this is intended to support
+     * switching to a different character for rendering, or adding a leading
+     * space/half-space/hair-space.
+     */
+    imaginary_value?: string;
 
-    /** scroll in x-direction. defaults to true. */
-    x?: boolean;
+    /** support MD formatting for text */
+    markdown?: boolean;
 
-    /** scroll in y-direction. defaults to true. */
-    y?: boolean;
+    /**
+     * show tinted colors in toolbar color dropdowns. as of version 25
+     * this defaults to true (used to be false).
+     */
+    tint_theme_colors?: boolean;
+
+    /** show a spinner for long-running operations */
+    spinner?: boolean;
+
+    /** collapsed: start sidebar closed */
+    collapsed?: boolean;
 
     /**
-     * smooth scrolling, if supported. we use scrollTo so support is as here:
-     * https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo
+     * show the revert button. see the Revert method. this was renamed
+     * from `revert` to avoid any ambiguity.
      */
-    smooth?: boolean;
+    revert_button?: boolean;
 }
 
 /**
- * function type used for filtering tables
+ * Structure represents a cell address. Note that row and column are 0-based.
  */
-export type TableFilterFunction = (value: CellValue, calculated_value: CellValue, style: Style.Properties) => boolean;
+export interface ICellAddress {
+
+    /** 0-based row */
+    row: number;
+
+    /** 0-based column */
+    column: number;
+    absolute_row?: boolean;
+    absolute_column?: boolean;
+    sheet_id?: number;
+}
 
 /**
  * embedded spreadsheet
@@ -472,8 +601,7 @@ export declare class EmbeddedSpreadsheet {
 
     /**
      * unserialize document from data.
-     *
-     **/
+     */
     LoadDocument(data: any, options?: LoadDocumentOptions): void;
 
     /**
@@ -716,16 +844,91 @@ export declare class EmbeddedSpreadsheet {
      */
     Cancel(token: number): void;
 }
+
+/**
+ * options for saving files. we add the option for JSON formatting.
+ */
+export interface SaveOptions extends SerializeOptions {
+
+    /** pretty json formatting */
+    pretty?: boolean;
+}
+
+/**
+ * options for the LoadDocument method
+ */
+export interface LoadDocumentOptions {
+    scroll?: string | ICellAddress;
+    flush?: boolean;
+    recalculate?: boolean;
+    override_sheet?: string;
+}
+
+/**
+ * options for the GetRange method
+ */
+export interface GetRangeOptions {
+
+    /**
+     * return formatted values (apply number formats and return strings)
+     * @deprecated
+     */
+    formatted?: boolean;
+
+    /**
+     * return formulas instead of values. formula takes precedence over
+     * "formatted"; if you pass both, returned values will *not* be formatted.
+     * @deprecated
+     */
+    formula?: boolean;
+
+    /**
+     * optional style for returned values (replaces old flags).
+     *
+     * @remarks
+     *
+     * `formatted` returns formatted values, applying number formatting and
+     * returning strings. `formula` returns cell formulas instead of values.
+     */
+    type?: 'formatted' | 'formula';
+}
+
+/**
+ * options for the ScrollTo method.
+ *
+ * @remarks
+ *
+ * this method was renamed because of a conflict with a DOM type,
+ * which was causing problems with the documentation generator.
+ */
+export interface SheetScrollOptions {
+
+    /** scroll in x-direction. defaults to true. */
+    x?: boolean;
+
+    /** scroll in y-direction. defaults to true. */
+    y?: boolean;
+
+    /**
+     * smooth scrolling, if supported. we use scrollTo so support is as here:
+     * https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo
+     */
+    smooth?: boolean;
+}
+
+/**
+ * function type used for filtering tables
+ */
+export type TableFilterFunction = (value: CellValue, calculated_value: CellValue, style: Style.Properties) => boolean;
 export interface FreezePane {
     rows: number;
     columns: number;
 }
-export declare type BorderConstants = "none" | "all" | "outside" | "top" | "bottom" | "left" | "right" | "double-top" | "double-bottom";
+export declare type BorderConstants = "none" | "all" | "outside" | "top" | "bottom" | "left" | "right";
 
 /**
  * options for serializing data
- *
- **/
+ */
 export interface SerializeOptions {
 
     /** optimize for size */
@@ -771,46 +974,22 @@ export interface SetRangeOptions {
     spill?: boolean;
 
     /**
-     * argument separator to use when parsing the input formula. by default,
-     * parsing uses the current locale. that is not optimal, because you
-     * do not necessarily know ahead of time where a spreadsheet may be viewed.
-     *
-     * set this option to call SetRange with a consistent argument separator.
-     * the decimal separator is implied; if the argument separator is set to
-     * comma (',') the decimal mark will be a dot ('.'); and if the argument
-     * separator is set to semicolon (';') the decimal mark will be set to
-     * comma (','). you cannot mix and match these values.
-     *
-     * @see EvaluateOptions for more discussion of this option.
+     * argument separator to use when parsing the input formula. set this
+     * option to call SetRange with a consistent argument separator,
+     * independent of current locale.
      */
     argument_separator?: ',' | ';';
 
     /**
-     * allow R1C1-style references; these can be either
-     * direct (e.g. R2C4) or offset (e.g. R[-3]C[0]).
+     * allow R1C1-style references; these can be either absolute
+     * addresses (e.g. R2C4) or relative to the cell (e.g. R[-3]C[0]).
      */
     r1c1?: boolean;
 }
 
-/**
- * Structure represents a cell address. Note that row and column are 0-based.
- */
-export interface ICellAddress {
-
-    /** 0-based row */
-    row: number;
-
-    /** 0-based column */
-    column: number;
-    absolute_row?: boolean;
-    absolute_column?: boolean;
-    sheet_id?: number;
-}
-
 /**
  * Structure represents a 2d range of cells.
- *
- **/
+ */
 export interface IArea {
     start: ICellAddress;
     end: ICellAddress;
@@ -835,8 +1014,7 @@ export declare namespace Style {
 
     /**
          * vertical align constants
-         *
-         **/ type VerticalAlign = "" | "top" | "bottom" | "middle";
+         */ type VerticalAlign = "" | "top" | "bottom" | "middle";
 
     /** composite font size */
     interface FontSize {
@@ -846,8 +1024,7 @@ export declare namespace Style {
 
     /**
      * color is either a theme color (theme index plus tint), or CSS text
-     *
-     **/
+     */
     interface Color {
         theme?: number;
         tint?: number;
@@ -950,8 +1127,7 @@ export interface DimensionedQuantity {
 
 /**
  * composite styling for tables.
- *
- **/
+ */
 export interface TableTheme {
 
     /** the first row in a table, showing column titles. */
@@ -1012,7 +1188,7 @@ export declare type LoadSource = "drag-and-drop" | "local-file" | "network-file"
  * EmbeddedSheetEvent is a discriminated union. Switch on the `type` field
  * of the event.
  */
-export type EmbeddedSheetEvent = DocumentChangeEvent | DocumentResetEvent | DocumentLoadEvent | DataChangeEvent | SelectionEvent | ResizeEvent;
+export type EmbeddedSheetEvent = DocumentChangeEvent | DocumentResetEvent | DocumentLoadEvent | DataChangeEvent | FocusViewEvent | SelectionEvent | ResizeEvent;
 
 /**
  * options when inserting a table into a sheet
@@ -1054,8 +1230,7 @@ export interface DocumentLoadEvent {
 
 /**
  * This event is sent when the document is reset.
- *
- **/
+ */
 export interface DocumentResetEvent {
     type: 'reset';
 }
@@ -1086,6 +1261,14 @@ export interface SelectionEvent {
     type: 'selection';
 }
 
+/**
+ * This event is sent when the focused view changes, if you have more
+ * than one view.
+ */
+export interface FocusViewEvent {
+    type: 'focus-view';
+}
+
 /**
  * options for exporting CSV/TSV
  */
@@ -1104,209 +1287,20 @@ export interface ExportOptions {
     formatted?: boolean;
 }
 
-/**
- * options for creating spreadsheet
- */
-export interface EmbeddedSpreadsheetOptions {
-
-    /** containing HTML element */
-    container?: string | HTMLElement;
-
-    /** allow drag-and-drop files */
-    dnd?: boolean;
-
-    /** expandable grid */
-    expand?: boolean;
-
-    /** key in localStorage for persisting document */
-    storage_key?: string;
-
-    /** don't load immediately (?) */
-    toll_initial_load?: boolean;
-
-    /** show formula bar */
-    formula_bar?: boolean;
-
-    /** expand formula bar */
-    expand_formula_button?: boolean;
-
-    /** scroll to cell on load */
-    scroll?: string | ICellAddress;
-
-    /** sheet to show on load, overrides anything in the model */
-    sheet?: string;
-
-    /** add resizable wrapper */
-    resizable?: boolean;
-
-    /** export to xlsx, now optional */
-    export?: boolean;
-
-    /** fill container */
-    auto_size?: boolean;
-
-    /** popout icon */
-    popout?: boolean;
-
-    /** fetch network document (URI) */
-    network_document?: string;
-
-    /**
-     * load this document if the storage document isn't found (fallback)
-     *
-     * @deprecated - this is superfluous, using network_document with
-     * storage_key is sufficient for this pattern.
-     */
-    alternate_document?: string;
-
-    /** freeze rows */
-    freeze_rows?: number;
-
-    /** freeze columns */
-    freeze_columns?: number;
-
-    /** row/column headers */
-    headers?: boolean;
-
-    /** recalculate on load */
-    recalculate?: boolean;
-
-    /** show scrollbars */
-    scrollbars?: boolean;
-
-    /** show tab bar (multi sheet) */
-    tab_bar?: boolean | 'auto';
-
-    /** allow add tab */
-    add_tab?: boolean;
-
-    /** show delete tab */
-    delete_tab?: boolean;
-
-    /** set a reference in global (self) */
-    global_name?: string;
-
-    /** support undo */
-    undo?: boolean;
-
-    /** support in-cell editor */
-    in_cell_editor?: boolean;
-
-    /** prompt "you have unsaved changes" */
-    prompt_save?: boolean;
-
-    /**
-     * toolbar display option
-     */
-    toolbar?: boolean | 'show' | 'narrow' | 'show-narrow';
-
-    /** file options in the toolbar */
-    file_menu?: boolean;
-
-    /** font size in the toolbar */
-    font_scale?: boolean;
-
-    /** show insert/remove table button in toolbar */
-    table_button?: boolean;
-
-    /** chart menu in the toolbar */
-    chart_menu?: boolean;
-
-    /** recalculate button in the toolbar */
-    toolbar_recalculate_button?: boolean;
-
-    /** new option, better support for headless operations (default false) */
-    headless?: boolean;
-
-    /** max size for image, in bytes */
-    max_file_size?: number;
-
-    /** initial scale */
-    scale?: number;
-
-    /** show scale buttons */
-    scale_control?: boolean;
-
-    /** show stats panel */
-    stats?: boolean;
-
-    /** save/load scale. this can optionally have a string key to disambiguate */
-    persist_scale?: boolean | string;
-
-    /** target window for hyperlinks (default _blank); set false to disable hyperlinks altogether */
-    hyperlinks?: string | false;
-
-    /**
-     * enable handling complex numbers in function calculation. turning this
-     * off doesn't actually disable complex numbers. it means that functions
-     * will not return complex numbers unless one of the arguments is complex.
-     *
-     * for example, if complex numbers are off, `=SQRT(-1)` will return `#VALUE`.
-     * if complex numbers are on, `=SQRT(-1)` will return `i`.
-     *
-     * even if complex numbers are off, however, `=SQRT(-1 + 0i)` will return
-     * `i` because the argument is complex.
-     *
-     * currently this behavior applies to `SQRT`, `POWER` and the exponentiation
-     * operator `^`.
-     *
-     * in version 22, this defaults to `off`.
-     */
-    complex?: 'on' | 'off';
-
-    /**
-     * for rendering the imaginary number. this is intended to support
-     * switching to a different character for rendering, or adding a leading
-     * space/half-space/hair-space.
-     */
-    imaginary_value?: string;
-
-    /** support MD formatting for text */
-    markdown?: boolean;
-
-    /** show tinted colors in toolbar color dropdowns */
-    tint_theme_colors?: boolean;
-
-    /** show a spinner for long-running operations */
-    spinner?: boolean;
-
-    /** collapsed: start sidebar closed */
-    collapsed?: boolean;
-
-    /**
-     * show the revert button. see the Revert method.
-     */
-    revert?: boolean;
-}
-
 /**
  * options for the evaluate function
  */
 export interface EvaluateOptions {
 
     /**
-     * By default, the Evaluate function will evaluate the expression in the
-     * current locale, meaning it will use the current locale's decimal separator
-     * and argument separator.
-     *
-     * If you do not want that behavior, set the argument separator explicitly.
-     * That will force evaluation using either comma (,) or semicolon (;) as the
-     * argument separator.
-     *
-     * Decimal separator is implied by the argument separator. If you set the
-     * argument separator to comma, the decimal separator will be dot (.). If you
-     * set the argument separator to semicolon, the decimal separator will be
-     * comma (,). You cannot mix-and-match these characters.
-     *
-     * Since you may not know where the code is being executed at run-time,
-     * using consistent argument and decimal separators makes sense. However we
-     * are leaving the original behavior as default for backwards compatibility.
+     * argument separator to use when parsing input. set this option to
+     * use a consistent argument separator independent of current locale.
      */
     argument_separator?: ',' | ';';
 
     /**
      * allow R1C1-style references. the Evaluate function cannot use
-     * offset references (e.g. R[-1]C[0]), so those will always fail.
+     * relative references (e.g. R[-1]C[0]), so those will always fail.
      * however it may be useful to use direct R1C1 references (e.g. R3C4),
      * so we optionally support that behind this flag.
      */