@trebco/treb 22.14.2 → 23.1.2

package/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v22.14. Copyright 2018-2022 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v23.1. Copyright 2018-2022 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /** 
  * Global instance. In the base script, this object will be created as an
@@ -91,6 +91,11 @@ export interface SheetScrollOptions {
     smooth?: boolean;
 }
 
+/**
+ * function type used for filtering tables
+ */
+export declare type TableFilterFunction = (value: CellValue, calculated_value: CellValue, style: Style.Properties) => boolean;
+
 /**
  * embedded spreadsheet
  */
@@ -309,6 +314,32 @@ export declare class EmbeddedSpreadsheet {
      */
     DeleteColumns(start_column?: number, count?: number): void;
 
+    /**
+     * sort a table. the reference can be the table name, or a cell in the table.
+     * if the reference is an area (range), we're going to look at the top-left
+     * cell.
+     *
+     * this method uses a function to filter rows based on cell values. leave the
+     * function undefined to show all rows. this is a shortcut for "unfilter".
+     *
+     * @param column - the column to sort on. values from this column will be
+     * passed to the filter function.
+     *
+     * @param filter - a callback function to filter based on cell values. this
+     * will be called with the cell value (formula), the calculated value (if any),
+     * and the cell style. return false to hide the row, and true to show the row.
+     * if the filter parameter is omitted, all values will be shown.
+     *
+     */
+    FilterTable(reference: RangeReference, column?: number, filter?: TableFilterFunction): void;
+
+    /**
+     * sort a table. the reference can be the table name, or a cell in the table.
+     * if the reference is an area (range), we're going to look at the top-left
+     * cell.
+     */
+    SortTable(reference: RangeReference, options?: Partial<TableSortOptions>): void;
+
     /**
      * Merge cells in range.
      *
@@ -700,6 +731,12 @@ export interface SerializeOptions {
 
     /** prune unused rows/columns */
     shrink?: boolean;
+
+    /**
+     * include tables. tables will be serialized in the model, so we can
+     * drop them from cells. but you can leave them in if that's useful.
+     */
+    tables?: boolean;
 }
 
 /**
@@ -908,6 +945,22 @@ export declare type AddressReference = string | ICellAddress;
  * address object, an area (range) object, or a string.
  */
 export declare type RangeReference = string | ICellAddress | IArea;
+export interface TableSortOptions {
+
+    /**
+     * when sorting, column is relative to the table (and 0-based). so the
+     * first column in the table is 0, regardless of where the table is in
+     * the spreadsheet. defaults to 0, if not specified.
+     */
+    column: number;
+
+    /** sort type. defaults to 'text'. */
+    type: TableSortType;
+
+    /** ascending sort. defaults to true. */
+    asc: boolean;
+}
+export declare type TableSortType = 'text' | 'numeric';
 
 /**
  * options for exporting CSV/TSV
@@ -1056,6 +1109,24 @@ export interface EmbeddedSpreadsheetOptions {
     /** 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