@trebco/treb 29.5.4 → 29.7.5

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v29.5. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v29.7. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -388,10 +388,8 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      * Use this function to batch multiple document changes. Essentially the
      * grid stops broadcasting events for the duration of the function call,
      * and collects them instead. After the function call we update as necessary.
-     *
-     * @public
      */
-    Batch(func: () => void, paint?: boolean): Promise<void>;
+    Batch(func: () => void, paint?: boolean): void;
 
     /** set freeze area */
     Freeze(rows?: number, columns?: number): void;
@@ -783,7 +781,7 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      *
      * @public
      */
-    Recalculate(): Promise<void>;
+    Recalculate(): void;
 
     /**
      * Save document to local storage.
@@ -964,6 +962,37 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      */
     Select(range?: RangeReference): void;
 
+    /**
+     * override for paste method omits the data parameter.
+     */
+    Paste(target?: RangeReference, options?: PasteOptions): void;
+
+    /**
+     * standard paste method accepts data argument
+     *
+     * @param target
+     * @param data
+     * @param options
+     */
+    Paste(target?: RangeReference, data?: ClipboardData, options?: PasteOptions): void;
+
+    /**
+     * 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.
+     */
+    Copy(source?: RangeReference): ClipboardData;
+
+    /**
+     * 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.
+     */
+    Cut(source?: RangeReference): ClipboardData;
+
     /**
      *
      * @param range target range. leave undefined to use current selection.
@@ -1268,6 +1297,10 @@ export interface Complex {
     real: number;
     imaginary: number;
 }
+
+/**
+ * dimensioned quantity: 3.2 m/s, 2kg, 5m, &c.
+ */
 export interface DimensionedQuantity {
     value: number;
     unit: string;
@@ -1350,6 +1383,53 @@ export interface EvaluateOptions {
      */
     r1c1?: boolean;
 }
+
+/** 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';
+}
+
+/**
+ * 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.
+ */
+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;
+}
 export declare type BorderConstants = "none" | "all" | "outside" | "top" | "bottom" | "left" | "right";
 
 /**
@@ -1589,23 +1669,6 @@ export interface SelectionEvent {
 export interface FocusViewEvent {
     type: 'focus-view';
 }
-export interface SerializedMacroFunction {
-    name: string;
-    function_def: string;
-    argument_names?: string[];
-    description?: string;
-}
-
-/**
- * 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;
-}
 
 /**
  * serialized type is a composite of expression/range. we determine
@@ -1970,6 +2033,23 @@ export interface Corner {
     address: ICellAddress;
     offset: AddressOffset;
 }
+export interface SerializedMacroFunction {
+    name: string;
+    function_def: string;
+    argument_names?: string[];
+    description?: string;
+}
+
+/**
+ * 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;
+}
 
 /**
  * options for exporting CSV/TSV

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trebco/treb",
-  "version": "29.5.4",
+  "version": "29.7.5",
   "license": "LGPL-3.0-or-later",
   "homepage": "https://treb.app",
   "repository": {

package/treb-base-types/src/cells.ts

@@ -1210,6 +1210,40 @@ export class Cells {
 
   }
 
+  /**
+   * yet another iterator, this one returns cell and address. 
+   * iterates all cells; does not create missing cells.
+   * 
+   * UPDATE: adding area parameter; not shrinking it (don't call w/ infinities)
+   */
+  public *IterateRC(area?: IArea) {
+
+    if (area) {
+      for (let row = area.start.row; row <= area.end.row; row++) {
+        const block = this.data[row];
+        if (block) {
+          for (let column = area.start.column; column <= area.end.column; column++) {
+            const cell = block[column];
+            if (cell) {
+              yield { cell, row, column };
+            }
+          }
+        }
+      }
+    }
+    else {
+      for (const [row, r] of this.data.entries()) {
+        if (r) {
+          for (const [column, cell] of r.entries()) {
+            if (cell) {
+              yield { cell, row, column };
+            }
+          }
+        }
+      }
+    }
+  }
+
   /**
    * replacement for old callback iterator. this is a composite 
    * of iterating all and iterating an area. I want to remove the

package/treb-base-types/src/evaluate-options.ts

@@ -1,4 +1,7 @@
 
+import type { ExpressionUnit } from 'treb-parser';
+import type { ICellAddress } from './area';
+
 /**
  * options for the evaluate function
  */
@@ -17,5 +20,23 @@ export interface EvaluateOptions {
    * so we optionally support that behind this flag.
    */
   r1c1?: boolean;
-  
+ 
+  /** 
+   * @internal
+   * 
+   * @privateRemarks
+   * in some cases we may call this method after parsing an expression.
+   * we don't need the evaluate method to parse it again.
+   */
+  preparsed?: ExpressionUnit;
+
+  /** 
+   * @internal
+   * 
+   * @privateRemarks
+   * we also might want to pass the address of the expression, if (or as if)
+   * it was originally in the spreadsheet.
+   */
+  address?: ICellAddress;
+
 }

package/treb-base-types/src/union.ts

@@ -105,15 +105,6 @@ export type UnionValue
     | ErrorUnion
     ;
 
-// common types
-
-/** 
- * this is a factory instead of a constant value to prevent any accidental pollution
- */
-// export const CreateUndefinedUnion = (): UnionValue => { 
-//  return { type: ValueType.undefined, value: undefined };
-//};
-
 /** 
  * shortcut, although this is wasteful 
  * 
@@ -136,8 +127,6 @@ export const Box = (value: unknown, type?: ValueType): UnionValue => {
   
 };
 
-// export type UnionOrArray = UnionValue|UnionValue[][];
-
 /**
  * box a complex value in a union, potentially switching to a real if
  * there's no imaginary component.

package/treb-base-types/src/value-type.ts

@@ -19,9 +19,6 @@
  * 
  */
 
-// split from cell for separate import, 
-// @see format-index.ts
-
 /**
  * Complex number type
  */
@@ -67,6 +64,9 @@ export const ComplexToString = (value: Complex): string => {
   }
 };
 
+/**
+ * dimensioned quantity: 3.2 m/s, 2kg, 5m, &c.
+ */
 export interface DimensionedQuantity {
   value: number;
   unit: string;

package/treb-calculator/src/calculator.ts

@@ -1589,45 +1589,54 @@ export class Calculator extends Graph {
   /** moved from embedded sheet */
   public Evaluate(expression: string, active_sheet?: Sheet, options: EvaluateOptions = {}, raw_result = false) {
     
-    // const current = this.parser.argument_separator;
-    // const r1c1_state = this.parser.flags.r1c1;
+    let parse_expression = options?.preparsed;
 
-    this.parser.Save();
+    if (!parse_expression) {
 
-    if (options.argument_separator) {
-      if (options.argument_separator === ',') {
-        this.parser.SetLocaleSettings(DecimalMarkType.Period);
+      this.parser.Save();
 
-        // this.parser.argument_separator = ArgumentSeparatorType.Comma;
-        // this.parser.decimal_mark = DecimalMarkType.Period;
+      if (options.argument_separator) {
+        if (options.argument_separator === ',') {
+          this.parser.SetLocaleSettings(DecimalMarkType.Period);
+
+          // this.parser.argument_separator = ArgumentSeparatorType.Comma;
+          // this.parser.decimal_mark = DecimalMarkType.Period;
+        }
+        else {
+          this.parser.SetLocaleSettings(DecimalMarkType.Comma);
+
+          // this.parser.argument_separator = ArgumentSeparatorType.Semicolon;
+          // this.parser.decimal_mark = DecimalMarkType.Comma;
+        }
       }
-      else {
-        this.parser.SetLocaleSettings(DecimalMarkType.Comma);
 
-        // this.parser.argument_separator = ArgumentSeparatorType.Semicolon;
-        // this.parser.decimal_mark = DecimalMarkType.Comma;
+      if (options.r1c1) {
+        this.parser.flags.r1c1 = options.r1c1;
       }
-    }
 
-    if (options.r1c1) {
-      this.parser.flags.r1c1 = options.r1c1;
-    }
+      const parse_result = this.parser.Parse(expression);
+
+      // reset
 
-    const parse_result = this.parser.Parse(expression);
+      // this.parser.argument_separator = current;
+      // this.parser.decimal_mark = (current === ArgumentSeparatorType.Comma) ? DecimalMarkType.Period : DecimalMarkType.Comma;
+      // this.parser.flags.r1c1 = r1c1_state;
 
-    // reset
+      this.parser.Restore();
 
-    // this.parser.argument_separator = current;
-    // this.parser.decimal_mark = (current === ArgumentSeparatorType.Comma) ? DecimalMarkType.Period : DecimalMarkType.Comma;
-    // this.parser.flags.r1c1 = r1c1_state;
+      parse_expression = parse_result.expression;
 
-    this.parser.Restore();
+      if (parse_result.error) {
+        throw new Error(parse_result.error);
+      }
+
+    }
 
     // OK
 
-    if (parse_result && parse_result.expression ){ 
+    if (parse_expression ){ 
 
-      this.parser.Walk(parse_result.expression, (unit) => {
+      this.parser.Walk(parse_expression, (unit) => {
         if (unit.type === 'address' || unit.type === 'range') {
 
           // don't allow offset references, even in R1C1
@@ -1648,7 +1657,7 @@ export class Calculator extends Graph {
       });
 
       // console.info({expression: parse_result.expression})
-      const result = this.CalculateExpression(parse_result.expression);
+      const result = this.CalculateExpression(parse_expression, options.address);
       if (raw_result) {
         return result;
       }
@@ -1664,10 +1673,6 @@ export class Calculator extends Graph {
 
     // or? (...)
 
-    if (parse_result.error) {
-      throw new Error(parse_result.error);
-    }
-
     throw new Error('invalid expression');
 
   }

package/treb-calculator/src/descriptors.ts

@@ -76,6 +76,8 @@ export interface ArgumentDescriptor {
    * 
    * if this flag is set in any argument descriptor in a function, we'll
    * apply arrays. that's done when the function is installed. 
+   * 
+   * FIXME: this should maybe be the default, and we have an !unroll flag
    */
   unroll?: boolean;