@trebco/treb 29.5.4 → 29.7.5

package/treb-data-model/src/types.ts

@@ -0,0 +1,71 @@
+
+import type { SerializedSheet } from './sheet_types';
+import type { Sheet } from './sheet';
+import type { IArea } from 'treb-base-types';
+import type { SerializedNamed } from './named';
+import type { Table } from 'treb-base-types';
+import type { ExpressionUnit } from 'treb-parser';
+
+export interface ConnectedElementType {
+  formula: string;
+  update?: (instance: ConnectedElementType) => void;
+  internal?: unknown; // opaque type to prevent circular dependencies
+}
+
+export interface SerializedMacroFunction {
+  name: string;
+  function_def: string;
+  argument_names?: string[];
+  description?: string;
+}
+
+/**
+ * we define this as extending the serialized version, rather
+ * than taking out the parameter, so we can make that def public
+ * in the API types.
+ */
+export interface MacroFunction extends SerializedMacroFunction {
+  expression?: ExpressionUnit;
+}
+
+/**
+ * @internal
+ */
+export interface ViewModel {
+  active_sheet: Sheet;
+  view_index: number;
+}
+
+/** 
+ * this type is no longer in use, but we retain it to parse old documents
+ * that use it. 
+ * 
+ * @deprecated
+ */
+export interface SerializedNamedExpression {
+  name: string;
+  expression: string;
+}
+
+export interface SerializedModel {
+  sheet_data: SerializedSheet[];
+  active_sheet: number;
+
+  /** @deprecated */
+  named_ranges?: Record<string, IArea>;
+
+  /** @deprecated */
+  named_expressions?: SerializedNamedExpression[];
+
+  /** 
+   * new type for consolidated named ranges & expressions. the old
+   * types are retained for backwards compatibility on import but we won't 
+   * export them anymore.
+   */
+  named?: SerializedNamed[];
+
+  macro_functions?: MacroFunction[];
+  tables?: Table[];
+  decimal_mark?: ','|'.';
+}
+

package/treb-embed/src/embedded-spreadsheet.ts

@@ -73,7 +73,7 @@ import type {
 
 import {
   IsArea, ThemeColorTable, ComplexToString, Rectangle, IsComplex, type CellStyle,
-  Localization, Style, type Color, ResolveThemeColor, IsCellAddress, Area, IsFlatData, IsFlatDataArray, Gradient, DOMContext, 
+  Localization, Style, type Color, ResolveThemeColor, IsCellAddress, Area, IsFlatData, IsFlatDataArray, Gradient, DOMContext 
 } from 'treb-base-types';
 
 import { EventSource, ValidateURI } from 'treb-utils';
@@ -93,7 +93,7 @@ import type { SelectionState } from './selection-state';
 import type { BorderToolbarMessage, ToolbarMessage } from './toolbar-message';
 
 import { Chart, ChartFunctions } from 'treb-charts';
-import type { SetRangeOptions } from 'treb-grid';
+import type { SetRangeOptions, ClipboardData, PasteOptions } from 'treb-grid';
 
 import type { StateLeafVertex } from 'treb-calculator';
 
@@ -264,6 +264,9 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
   /** @internal */
   public static one_time_warnings: Record<string, boolean> = {};
 
+  /** @internal */
+  protected static clipboard?: ClipboardData;
+
   protected DOM = DOMContext.GetInstance(); // default
 
   /**
@@ -943,10 +946,20 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
               const cached_selection = this.last_selection;
 
+              /*
               ((this.calculation === CalculationOptions.automatic) ?
                 this.Recalculate(event) : Promise.resolve()).then(() => {
                   this.DocumentChange(cached_selection);
                 });
+              */
+
+              // recalc is no longer async
+
+              if (this.calculation === CalculationOptions.automatic) {
+                this.Recalculate(event);
+              }
+
+              this.DocumentChange(cached_selection);
 
               /*
               if (this.calculation === CalculationOptions.automatic) {
@@ -1027,10 +1040,19 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
               if (event.rebuild_required) {
                 this.calculator.Reset();
 
+                /*
                 ((this.calculation === CalculationOptions.automatic) ?
                   this.Recalculate(event) : Promise.resolve()).then(() => {
                     this.DocumentChange(cached_selection);
                   });
+                */
+
+                // recalculate is no longer async
+
+                if (this.calculation === CalculationOptions.automatic) {
+                  this.Recalculate(event);
+                }
+                this.DocumentChange(cached_selection);
 
               }
               else {
@@ -1387,18 +1409,10 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
   /** @internal */
   public ConditionalFormatDuplicateValues(range: RangeReference|undefined, options: ConditionalFormatDuplicateValuesOptions): ConditionalFormat {
-       
-    if (range === undefined) {
-      const ref = this.GetSelectionReference();
-      if (ref.empty) {
-        throw new Error('invalid range (no selection)');
-      }
-      range = ref.area;
-    }
-    
+      
     return this.AddConditionalFormat({
         type: 'duplicate-values',
-        area: this.model.ResolveArea(range, this.grid.active_sheet),
+        area: this.RangeOrSelection(range, 'invalid range (no selection)'),
         ...options,
       });
 
@@ -1409,15 +1423,7 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
    */
   public ConditionalFormatGradient(range: RangeReference|undefined, options: ConditionalFormatGradientOptions|StandardGradient): ConditionalFormat {
 
-    if (range === undefined) {
-      const ref = this.GetSelectionReference();
-      if (ref.empty) {
-        throw new Error('invalid range (no selection)');
-      }
-      range = ref.area;
-    }
-    
-    const area = this.model.ResolveArea(range, this.grid.active_sheet);
+    const area = this.RangeOrSelection(range, 'invalid range (no selection)');
 
     const format: ConditionalFormatGradient = (typeof options === 'object') ?
       {
@@ -1435,19 +1441,9 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
   /** @internal */
   public ConditionalFormatCellMatch(range: RangeReference|undefined, options: ConditionalFormatCellMatchOptions): ConditionalFormat {
 
-    if (range === undefined) {
-      const ref = this.GetSelectionReference();
-      if (ref.empty) {
-        throw new Error('invalid range (no selection)');
-      }
-      range = ref.area;
-    }
-    
-    const area = this.model.ResolveArea(range, this.grid.active_sheet);
-
     const format: ConditionalFormatCellMatch = {
       type: 'cell-match',
-      area,
+      area: this.RangeOrSelection(range, 'invalid range (no selection)'),
       ...options,
     };
 
@@ -1462,19 +1458,9 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
    */
   public ConditionalFormatExpression(range: RangeReference|undefined, options: CondifionalFormatExpressionOptions): ConditionalFormat {
 
-    if (range === undefined) {
-      const ref = this.GetSelectionReference();
-      if (ref.empty) {
-        throw new Error('invalid range (no selection)');
-      }
-      range = ref.area;
-    }
-    
-    const area = this.model.ResolveArea(range, this.grid.active_sheet);
-
     const format: ConditionalFormatExpression = {
       type: 'expression',
-      area,
+      area: this.RangeOrSelection(range, 'invalid range (no selection)'),
       ...options,
     };
 
@@ -1515,18 +1501,10 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
    * @internal
    */
   public RemoveConditionalFormats(range?: RangeReference) {
-
-    if (range === undefined) {
-      const ref = this.GetSelectionReference();
-      if (ref.empty) {
-        throw new Error('invalid range (no selection)');
-      }
-      range = ref.area;
+    const area = this.RangeOrSelection(range);
+    if (area) {
+      this.grid.RemoveConditionalFormat({ area });
     }
-
-    const area = this.model.ResolveArea(range, this.grid.active_sheet);
-    this.grid.RemoveConditionalFormat({ area });
-
   }
 
   //////////////////////////////////////////////////////////////////////////////
@@ -2009,9 +1987,27 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
    * grid stops broadcasting events for the duration of the function call, 
    * and collects them instead. After the function call we update as necessary.
    * 
-   * @public
+   * @privateRemarks
+   * 
+   * FIXME: we need to consider the case where this is nested, since we now
+   * call it from the Paste method. that might be batched by a caller. we
+   * need a batch stack, and we need to consolidate any options (paint is the
+   * only option) and keep the top-of-stack last selection.
+   * 
+   * Q: why does this work the way it does, anyway? why not just rely
+   * on the actual events? if grid published them after a batch, wouldn't 
+   * everything just work? or is the problem that we normally handle events
+   * serially? maybe we need to rethink how we handle events coming from
+   * the grid.
+   * 
+   * ---
+   * 
+   * OK so now, grid will handle nested batching. it won't return anything
+   * until the last batch is complete. so this should work in the case of 
+   * nested calls, because nothing will happen until the last one is complete.
+   * 
    */
-  public async Batch(func: () => void, paint = false): Promise<void> {
+  public Batch(func: () => void, paint = false): void {
 
     // API v1 OK
 
@@ -2021,6 +2017,8 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     let recalc = false;
     let reset = false;
 
+    // FIXME (2024): are these FIXMEs below still a thing? (...)
+
     // FIXME: annotation events
     // TODO: annotation events
 
@@ -2041,7 +2039,7 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     }
 
     if (recalc || reset) {
-      await this.Recalculate();
+      this.Recalculate();
       this.DocumentChange(cached_selection);
     }
 
@@ -3739,10 +3737,12 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
    * 
    * the event parameter should not be used if this is called
    * as an API function, remove it from typings
-   * 
+   *
+   * why is this async? it doesn't do anything async.
+   *  
    * @public
    */
-  public async Recalculate(event?: GridEvent): Promise<void> {
+  public Recalculate(event?: GridEvent) {
 
     // API v1 OK
 
@@ -4289,6 +4289,114 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
   }
 
+  /** 
+   * override for paste method omits the data parameter. 
+   */
+  public Paste(target?: RangeReference, options?: PasteOptions): void;
+
+  /**
+   * standard paste method accepts data argument
+   * 
+   * @param target 
+   * @param data 
+   * @param options 
+   */
+  public Paste(target?: RangeReference, data?: ClipboardData, options?: PasteOptions): void;
+
+  /**
+   * paste clipboard data into a target range. this method does not use
+   * the system clipboard; pass in clipboard data returned from the Cut or
+   * Copy method.
+   * 
+   * @param target - the target to paste data into. this can be larger 
+   * than the clipboard data, in which case values will be recycled in 
+   * blocks. if the target is smaller than the source data, we will expand
+   * it to fit the data.
+   * 
+   * @param data - clipboard data to paste.
+   * 
+   * @privateRemarks LLM API
+   * 
+   * @privateRemarks this was async when we were thinking of using the 
+   * system clipboard, but that's pretty broken so we're not going to
+   * bother atm.
+   */
+  public Paste(target?: RangeReference, ...args: unknown[]): void {
+
+    // support for the dynamic overload (not sure that's actually a good idea)
+
+    let data = EmbeddedSpreadsheet.clipboard; // default to "global" clipboard
+    let options: PasteOptions = {}; // default
+
+    switch (args.length) {
+      case 1:
+
+        // could be either
+
+        if (Array.isArray(args[0])) {
+          data = args[0] as ClipboardData;
+        }
+        else if (typeof args[0] === 'object') {
+          options = args[0] as PasteOptions;
+        }
+        break;
+
+      case 2:
+
+        // check if it exists, could be undef/null
+        if (args[0] && Array.isArray(args[0])) {
+          data = args[0] as ClipboardData;
+        }
+
+        // 1 should exist if len is 2
+        if (args[1] && typeof args[1] === 'object') {
+          options = args[1] as PasteOptions;
+        }
+        break;
+    }
+    
+    if (!data) {
+      throw new Error('no clipboad data');
+    }
+
+    this.grid.PasteArea(
+      this.RangeOrSelection(target, 'no range and no selection'), 
+      data, 
+      options);
+
+  }
+
+  /**
+   * copy data. this method returns the copied data. it does not put it on
+   * the system clipboard. this is for API access when the system clipboard 
+   * might not be available.
+   * 
+   * @privateRemarks LLM API
+   */
+  public Copy(source?: RangeReference): ClipboardData {
+    const area = this.RangeOrSelection(source);
+    const data: ClipboardData = area ? this.grid.CopyArea(area, 'copy') : [];
+    EmbeddedSpreadsheet.clipboard = structuredClone(data);
+    return data;
+  }
+
+  /**
+   * cut data. this method returns the cut data. it does not put it on the 
+   * system clipboard. this method is similar to the Copy method, with 
+   * two differences: (1) we remove the source data, effectively clearing
+   * the source range; and (2) the clipboard data retains references, meaning
+   * if you paste the data in a different location it will refer to the same
+   * cells.
+   * 
+   * @privateRemarks LLM API
+   */
+  public Cut(source?: RangeReference): ClipboardData {
+    const area = this.RangeOrSelection(source);
+    const data: ClipboardData = area ? this.grid.CopyArea(area, 'cut') : [];
+    EmbeddedSpreadsheet.clipboard = structuredClone(data);
+    return data;
+  }
+ 
   /** 
    * 
    * @param range target range. leave undefined to use current selection.
@@ -4299,14 +4407,11 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
     // API v1 OK
 
-    if (!range) {
-      const selection = this.GetSelectionReference();
-      if (!selection.empty) {
-        range = selection.area;
-      }
-    }
+    const resolved = this.RangeOrSelection(range);
 
-    if (!range) { return undefined; }
+    if (!resolved) {
+      return undefined;
+    }
 
     // handle the old flags and the precedence rule. type takes precedence.
 
@@ -4327,7 +4432,7 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
       type = 'A1';
     }
 
-    return this.grid.GetRange(this.model.ResolveAddress(range, this.grid.active_sheet), type);
+    return this.grid.GetRange(resolved, type);
 
   }
 
@@ -4347,16 +4452,12 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
     // API v1 OK
 
-    if (!range) {
-      const selection = this.GetSelectionReference();
-      if (!selection.empty) {
-        range = selection.area;
-      }
+    const resolved = this.RangeOrSelection(range);
+    if (!resolved) {
+      return undefined;
     }
 
-    if (!range) { return undefined; }
-
-    return this.grid.GetRangeStyle(this.model.ResolveAddress(range, this.grid.active_sheet), apply_theme);
+    return this.grid.GetRangeStyle(resolved, apply_theme);
     
   }
 
@@ -4377,15 +4478,10 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
     // API v1 OK
 
-    if (!range) {
-      const selection = this.GetSelectionReference();
-      if (!selection.empty) {
-        range = selection.area;
-      }
-    }
+    const area = this.RangeOrSelection(range);
 
-    if (range) {
-      const area = this.model.ResolveArea(range, this.grid.active_sheet);
+    if (area) {
+      // const area = this.model.ResolveArea(range, this.grid.active_sheet);
 
       if (options.spill && Array.isArray(data)) {
         const rows = data.length;
@@ -4441,6 +4537,42 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
   // --- internal (protected) methods ------------------------------------------
 
+  /**
+   * overload returns undefined if no range and no selection
+   */
+  protected RangeOrSelection(source: RangeReference|undefined): Area|undefined;
+
+  /**
+   * overload throws if no range and no selection (pass the error to throw)
+   */
+  protected RangeOrSelection(source: RangeReference|undefined, error: string): Area;
+
+  /**
+   * this is a common pattern, start with a range reference; if it's 
+   * undefined, check selection; then resolve. if there's no selection 
+   * and no range passed in, returns undefined or if the error parameter
+   * is set, throws.
+   */
+  protected RangeOrSelection(source: RangeReference|undefined, error?: string): Area|undefined {
+
+    if (!source) {
+      const selection = this.GetSelectionReference();
+      if (!selection.empty) {
+        return selection.area.Clone(); // Area
+      }
+      else {
+        if (error) {
+          throw error;
+        }
+        // throw new Error('no range and no selection');
+        return undefined;
+      }
+    }
+
+    return this.model.ResolveArea(source, this.grid.active_sheet);
+
+  } 
+
   // --- moved from grid/grid base ---------------------------------------------
 
   

package/treb-export/src/xml-utils.ts

@@ -158,7 +158,7 @@ export class XMLUtils {
    * 
    * in either case we want both "c" elements.
    */
-  public static FindAll(root: any = {}, path: string): any[] {
+  public static FindAll(root: DOMContent = {}, path: string): any[] {
 
     const components = path.split('/');
 
@@ -190,12 +190,12 @@ export class XMLUtils {
    * basically if you see a wildcard, just treat every element as a 
    * match -- right?
    */
-  public static FindAllTail(root: any, elements: string[]): any[] {
+  public static FindAllTail(root: DOMContent|DOMContent[], elements: string[]): DOMContent[] {
 
     if (Array.isArray(root)) {
       return root.reduce((composite, element) => {
         return composite.concat(this.FindAllTail(element, elements));
-      }, []);
+      }, [] as DOMContent[]);
     }
 
     for (let i = 0; i < elements.length; i++) {
@@ -209,15 +209,27 @@ export class XMLUtils {
       // maps attributes and text differently... hopefully they won't use 
       // wildcards
 
+      if (element === '*') {
+
+        const pairs = Object.entries(root) as Array<[string, DOMContent]>;
+        root = pairs.reduce((result, [key, value]) => {
+          if (key !== 'a$' && key !== 't$')  {
+            result.push(value);
+          }
+          return result;
+        }, [] as DOMContent[]);
+
+        /*
       // two loops, really? come on
 
-      if (element === '*') {
-        root = Object.keys(root).
+        root = Object.keys(flat).
             filter(key => (key !== 'a$' && key !== 't$')).
-            map(key => root[key]);
+            map(key => flat[key]) as DOMContent[];
+        */
+
       }
       else {
-        root = root[element];
+        root = root[element] as DOMContent;
       }
 
       if (!root) {
@@ -237,7 +249,7 @@ export class XMLUtils {
         const step = elements.slice(1);
         return root.reduce((composite, element) => {
           return composite.concat(this.FindAllTail(element, step));
-        }, []);
+        }, [] as DOMContent[]);
 
       }
 

package/treb-grid/src/index.ts

@@ -22,6 +22,7 @@
 export { Grid } from './types/grid';
 export { GridBase } from './types/grid_base';
 export * from './types/grid_events';
+export * from './types/clipboard_data2';
 export type { GridOptions } from './types/grid_options';
 export { CommandKey } from './types/grid_command';
 export type { Command } from './types/grid_command';

package/treb-grid/src/types/clipboard_data2.ts

@@ -0,0 +1,85 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the 
+ * terms of the GNU General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your option) any 
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY 
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along 
+ * with TREB. If not, see <https://www.gnu.org/licenses/>. 
+ *
+ * Copyright 2022-2024 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { CellValue, IArea, CellStyle } from 'treb-base-types';
+
+
+/**
+ * this is a structure for copy/paste data. clipboard data may include 
+ * relative formauls and resolved styles, so it's suitable for pasting into 
+ * other areas of the spreadsheet.
+ * 
+ * @privateRemarks
+ * work in progress. atm we're not using the system clipboard, although it 
+ * might be useful to merge this with grid copy/paste routines in the future.
+ * 
+ * if it hits the clipboard this should use mime type `application/x-treb-data`
+ * 
+ */
+export interface ClipboardDataElement {
+
+  /** calculated cell value */
+  calculated: CellValue,
+
+  /** the actual cell value or formula */
+  value: CellValue,
+
+  /** cell style. this may include row/column styles from the copy source */
+  style?: CellStyle,
+
+  /** area. if this cell is part of an array, this is the array range */
+  area?: IArea,
+
+  /* TODO: merge, like area */
+
+  /* TODO: table */
+
+}
+
+/** clipboard data is a 2d array */
+export type ClipboardData = ClipboardDataElement[][];
+
+/** 
+ * optional paste options. we can paste formulas or values, and we 
+ * can use the source style, target style, or just use the source
+ * number formats.
+ */
+export interface PasteOptions {
+
+  /**
+   * when clipboard data includes formulas, optionally paste calculated
+   * values instead of the original formulas. defaults to false.
+   */
+  values?: boolean;
+
+  /** 
+   * when pasting data from the clipboard, we can copy formatting/style 
+   * from the original data, or we can retain the target range formatting
+   * and just paste data. a third option allows pasting source number 
+   * formats but dropping other style information.
+   * 
+   * defaults to "source", meaning paste source styles.
+   */
+
+  formatting?: 'source'|'target'|'number-formats'
+
+}
+