@trebco/treb 23.6.5 → 25.0.0-rc2

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

@@ -1,100 +1,264 @@
-/*! API v23.6. Copyright 2018-2023 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v25.0.0-rc2. 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. if this option is false, the grid will always
+     * stay the same size -- if you keep pressing down arrow, it won't
+     * grow. defaults to true.
+     */
+    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.
+     *
+     * that 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;
-    recalculate?: boolean;
-    override_sheet?: string;
-}
 
-/**
- * options for the GetRange method
- */
-export interface GetRangeOptions {
+    /** sheet to show on load, overrides anything in the model */
+    sheet?: string;
+
+    /** add resizable wrapper */
+    resizable?: boolean;
+
+    /** export to xlsx, now optional */
+    export?: boolean;
 
     /**
-     * return formatted values (apply number formats and return strings)
-     * @deprecated
+     * fetch network document. this is a replacement for the old
+     * (deprecated) option `network_document`.
      */
-    formatted?: boolean;
+    document?: string;
 
     /**
-     * return formulas instead of values. formula takes precedence over
-     * "formatted"; if you pass both, returned values will *not* be formatted.
-     * @deprecated
+     * fetch network document (URI)
+     * @deprecated - use `document`
+     */
+    network_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. true or false means include/don't include
+     * the toolbar (and the toolbar button). setting to "narrow" means
+     * include the toolbar, but use a narrow version (it compresses the
+     * align/justify groups).
      *
-     **/
-    formula?: boolean;
+     * the toolbar usually starts hidden. if you set this option to "show",
+     * it will start visible. same for "show-narrow".
+     */
+    toolbar?: boolean | 'show' | 'narrow' | 'show-narrow';
+
+    /** include the file menu in the toolbar */
+    file_menu?: boolean;
+
+    /** include the font scale control in the toolbar */
+    font_scale?: boolean;
+
+    /** include the insert/remove table button in the toolbar */
+    table_button?: boolean;
+
+    /** include the freeze button in the toolbar */
+    freeze_button?: boolean;
+
+    /** include the chart menu in the toolbar */
+    chart_menu?: boolean;
+
+    /** include a recalculate button in the toolbar */
+    toolbar_recalculate_button?: boolean;
+
+    /** better support for headless operations (default false) */
+    headless?: boolean;
+
+    /** max size for image, in bytes */
+    max_file_size?: number;
+
+    /** initial scale */
+    scale?: number;
 
     /**
-     * optional style for returned values (replaces old flags).
+     * show scale control (slider) under the spreadsheet.
+     */
+    scale_control?: boolean;
+
+    /**
+     * show the stats panel under the spreadsheet.
+     */
+    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.
      *
-     * @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.
+     *
+     * this _does_not_ change how you enter imaginary numbers, you still have
+     * to use `i` (lower-case ascii i).
+     */
+    imaginary_value?: string;
 
-    /** scroll in x-direction. defaults to true. */
-    x?: boolean;
+    /**
+     * support markdown formatting for text in cells and comments. at the
+     * moment we only support bold, italic, and strike 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;
 
     /**
-     * smooth scrolling, if supported. we use scrollTo so support is as here:
-     * https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo
+     * show a spinner for long-running operations
      */
-    smooth?: boolean;
+    spinner?: boolean;
+
+    /**
+     * start with sidebar closed. defaults to false.
+     */
+    collapsed?: boolean;
+
+    /**
+     * show the revert button in the sidebar. see the `Revert` method. this
+     * was renamed from `revert` to avoid any ambiguity.
+     */
+    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
@@ -397,9 +561,10 @@ export declare class EmbeddedSpreadsheet {
      *
      * @remarks
      *
-     * Call this method when the container is resized. It's not necessary
-     * if the resize is triggered by our resize handle, only if the container
-     * is resized externally.
+     * This method should be called when the container is resized, to
+     * trigger an update to layout. It should be called automatically
+     * by a resize observer set in the containing tag class, but you
+     * can call it manually if necessary.
      *
      * @public
      */
@@ -472,8 +637,7 @@ export declare class EmbeddedSpreadsheet {
 
     /**
      * unserialize document from data.
-     *
-     **/
+     */
     LoadDocument(data: any, options?: LoadDocumentOptions): void;
 
     /**
@@ -716,16 +880,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 */
@@ -784,25 +1023,9 @@ export interface SetRangeOptions {
     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;
@@ -827,8 +1050,7 @@ export declare namespace Style {
 
     /**
          * vertical align constants
-         *
-         **/ type VerticalAlign = "" | "top" | "bottom" | "middle";
+         */ type VerticalAlign = "" | "top" | "bottom" | "middle";
 
     /** composite font size */
     interface FontSize {
@@ -838,8 +1060,7 @@ export declare namespace Style {
 
     /**
      * color is either a theme color (theme index plus tint), or CSS text
-     *
-     **/
+     */
     interface Color {
         theme?: number;
         tint?: number;
@@ -942,8 +1163,7 @@ export interface DimensionedQuantity {
 
 /**
  * composite styling for tables.
- *
- **/
+ */
 export interface TableTheme {
 
     /** the first row in a table, showing column titles. */
@@ -1004,7 +1224,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
@@ -1046,8 +1266,7 @@ export interface DocumentLoadEvent {
 
 /**
  * This event is sent when the document is reset.
- *
- **/
+ */
 export interface DocumentResetEvent {
     type: 'reset';
 }
@@ -1078,6 +1297,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
  */
@@ -1096,181 +1323,6 @@ 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
  */