@trebco/treb 29.8.3 → 30.1.0

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v29.8. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v30.1. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -276,6 +276,12 @@ export interface EmbeddedSpreadsheetOptions {
      * indent/outdent buttons; default false
      */
     indent_buttons?: boolean;
+
+    /**
+     * enable spill arrays and spill references. this is on by default
+     * starting in 30.1.0. set to false to disable.
+     */
+    spill?: boolean;
 }
 
 /**
@@ -291,6 +297,9 @@ export interface ICellAddress {
     absolute_row?: boolean;
     absolute_column?: boolean;
     sheet_id?: number;
+
+    /** spill reference */
+    spill?: boolean;
 }
 
 /**
@@ -1794,6 +1803,7 @@ export interface BaseCellData {
     hyperlink?: string;
     type?: SerializedValueType;
     sheet_id?: number;
+    spill?: IArea;
 }
 
 /**

package/eslint.config.js

@@ -9,6 +9,15 @@ export default tseslint.config(
   {
     rules: {
 
+      // allow destructuring to use let if some vars are changed
+
+      "prefer-const": [
+        "error", { 
+          "destructuring": "all",
+        },
+      ],
+
+
       // allow destructuring to use garbage variables. prefix name with 
       // underscore (or just use underscore).
 

package/package.json

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

package/treb-base-types/src/area-utils.ts

@@ -0,0 +1,60 @@
+/*
+ * 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 { IArea } from './area';
+import type { ICellAddress } from './area';
+
+/**
+ * area being a class is a mistake, but it will take a while
+ * to undo that (if we do it at all). for now we'll start creating
+ * utilities that can operate on the interface type, and maybe over
+ * time the class will wither.
+ */
+
+export function* Iterate(area: IArea): Generator<ICellAddress> {
+
+  /**
+   * this doesn't serialize. perhaps we should switch to -1, 
+   * which is obviously invalid. although I think we may from
+   * time to time use that as a flag. which is bad, obviously.
+   * if we do that we'll need to define a new interface. which
+   * might be good.
+   */
+  if (area.start.row === Infinity || area.end.row === Infinity) {
+    throw new Error(`don't iterate infinite area`);
+  }
+
+  /*
+  if (area.entire_row || area.entire_column) {
+    throw new Error(`don't iterate infinite area`);
+  }
+  */
+
+  const sheet_id = area.start.sheet_id;
+
+  for (let row = area.start.row; row <= area.end.row; row++) {
+    for (let column = area.start.column; column <= area.end.column; column++) {
+      yield { row, column, sheet_id };
+    }
+  }
+
+}
+

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

@@ -33,6 +33,10 @@ export interface ICellAddress {
   absolute_row?: boolean;
   absolute_column?: boolean;
   sheet_id?: number;
+
+  /** spill reference */
+  spill?: boolean;
+
 }
 
 /**
@@ -659,6 +663,13 @@ export class Area implements IArea {
     }
   }
 
+  /** Resizes range in place to be the requested shape */
+  public Reshape(rows: number, columns: number): Area {
+    this.end_.row = this.start_.row + rows - 1;
+    this.end_.column = this.start_.column + columns - 1;
+    return this; // fluent
+  }
+
   /** Resizes range in place so that it includes the given area (merge) */
   public ConsumeArea(area: IArea): void {
     this.ConsumeAddress(area.start);

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

@@ -236,6 +236,9 @@ export class Cell {
   /** if this cell is part of an array, pointer to the area. */
   public area?: Area;
 
+  /** testing spill */
+  public spill?: Area;
+
   /**
    * if this cell is merged, pointer to the area
    */
@@ -354,6 +357,7 @@ export class Cell {
   public Reset(): void{
     this.type = ValueType.undefined;
     this.value
+      = this.spill
       = this.note
       = this.hyperlink
       = this.formatted
@@ -372,7 +376,8 @@ export class Cell {
   public Set(value: CellValue, type = GetValueType(value)): void {
     this.value = value;
     this.type = type;
-    this.formatted =
+    this.spill = // added
+      this.formatted =
       this.rendered_type =
       this.style =
       this.calculated =

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

@@ -87,6 +87,7 @@ export interface BaseCellData {
   hyperlink?: string;
   type?: SerializedValueType; // ValueType;
   sheet_id?: number;
+  spill?: IArea;
   // locked?: boolean;
 }
 
@@ -507,6 +508,9 @@ export class Cells {
         // cell.calculated = obj.calculated;
         // cell.calculated_type = obj.calculated_type;
         cell.SetCalculatedValue(obj.calculated, this.SerializedTypeToValueType(obj.calculated_type));
+        if (obj.spill) {
+          cell.spill = new Area(obj.spill.start, obj.spill.end);
+        }
       }
 
       if (style_refs) {
@@ -704,6 +708,9 @@ export class Cells {
             if (options.calculated_value &&
                 typeof cell.calculated !== 'undefined') { // && cell.calculated_type !== ValueType.error) {
               obj.calculated = cell.calculated;
+              if (cell.spill) {
+                obj.spill = cell.spill;
+              }
 
               // always preserve error type, because we can't infer
               if (options.preserve_type || cell.calculated_type === ValueType.error) {
@@ -1216,16 +1223,40 @@ export class Cells {
    * 
    * UPDATE: adding area parameter; not shrinking it (don't call w/ infinities)
    */
-  public *IterateRC(area?: IArea) {
+  public *IterateRC(area?: IArea, create_missing_cells = false) {
+
+    if (!area && create_missing_cells) {
+      area = new Area({
+        row: 0,
+        column: 0,
+      }, {
+        row: this.rows_ - 1,
+        column: this.columns - 1,
+      });
+    }
 
     if (area) {
-      for (let row = area.start.row; row <= area.end.row; row++) {
-        const block = this.data[row];
-        if (block) {
+      if (create_missing_cells) {
+        for (let row = area.start.row; row <= area.end.row; row++) {
+          if (!this.data[row]) this.data[row] = [];
+          const block = this.data[row];
           for (let column = area.start.column; column <= area.end.column; column++) {
-            const cell = block[column];
-            if (cell) {
-              yield { cell, row, column };
+            if (!block[column]) {
+              block[column] = new Cell();
+            }
+            yield { cell: block[column], row, column };
+          }
+        }
+      }
+      else {
+        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 };
+              }
             }
           }
         }

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

@@ -40,6 +40,8 @@ export * from './gradient';
 export * from './evaluate-options';
 export * from './dom-utilities';
 
+export * as AreaUtils from './area-utils';
+
 // import * as Style from './style';
 // export { Style };
 

package/treb-calculator/src/calculator.ts

@@ -20,7 +20,8 @@
  */
 
 import type { Cell, ICellAddress, ICellAddress2, UnionValue, EvaluateOptions,
-         ArrayUnion, IArea, CellDataWithAddress, CellValue} from 'treb-base-types';
+         ArrayUnion, IArea, CellDataWithAddress, CellValue,
+         Cells} from 'treb-base-types';
 import { Localization, Area, ValueType, IsCellAddress} from 'treb-base-types';
          
 import type { ExpressionUnit, DependencyList, UnitRange, UnitAddress, UnitIdentifier, ParseResult } from 'treb-parser';
@@ -140,10 +141,14 @@ export interface CalculatorOptions {
    */
   complex_numbers: 'on'|'off';
 
+  /** enable spill arrays */
+  spill?: boolean;
+
 }
 
 const default_calculator_options: CalculatorOptions = {
   complex_numbers: 'off',
+  spill: false, 
 };
 
 /**
@@ -181,6 +186,15 @@ export class Calculator extends Graph {
   /** the next calculation must do a full rebuild -- set on reset */
   protected full_rebuild_required = false;
 
+  protected options: CalculatorOptions;
+
+  /**
+   * this is a flag we're using to communicate back to the embedded
+   * sheet, when the grid has expanded as a result of a calculation 
+   * (because of a spill).
+   */
+  public grid_expanded = false;
+
   constructor(protected readonly model: DataModel, calculator_options: Partial<CalculatorOptions> = {}) {
 
     super();
@@ -191,12 +205,12 @@ export class Calculator extends Graph {
     // at the moment options are only used here; in the future
     // we may need to extend handling.
 
-    const options: CalculatorOptions = {
+    this.options = {
       ...default_calculator_options, 
       ...calculator_options,
     };
 
-    if (options.complex_numbers === 'on') {
+    if (this.options.complex_numbers === 'on') {
 
       // complex number handling: we need to change SQRT, POWER and ^
 
@@ -1065,6 +1079,244 @@ export class Calculator extends Graph {
     }
   }
 
+  public AttachSpillData(area: Area, cells?: Cells) {
+
+    if (!cells) {
+      const sheet = area.start.sheet_id ? this.model.sheets.Find(area.start.sheet_id) : undefined;
+      cells = sheet?.cells;
+    }
+
+    if (!cells) {
+      throw new Error('invalid sheet ID in attach spill data');
+    }
+
+    const vertex = new StateLeafVertex();
+    let counter = 0;
+    let error = false;
+
+    for (const {cell, row, column} of cells.IterateRC(area, true)) {
+      if (counter++ && (cell.type !== ValueType.undefined || cell.area || cell.merge_area || cell.table)) {
+        error = true; // spill error.
+      }
+      this.AddLeafVertexEdge({row, column, sheet_id: area.start.sheet_id}, vertex);
+    }
+
+    // console.info("storing spill data");
+    this.spill_data.push({area, vertex});
+
+    return { vertex, area, error };
+
+  }
+
+  public SpillCallback(vertex: SpreadsheetVertex, result: ArrayUnion): SpreadsheetVertex[] {
+
+    const { reference, address } = vertex;
+    const { value } = result;
+
+    const recalculate_list: SpreadsheetVertex[] = [];
+
+    if (!reference) {
+      // should throw but this is new and I don't want to break stuff rn
+      console.error("invalid reference in spill callback");
+      return recalculate_list;
+    }
+
+    if (!address || !address.sheet_id) {
+      // should throw but this is new and I don't want to break stuff rn
+      console.error("invalid address in spill callback");
+      return recalculate_list;
+    }
+
+    // I guess we could do the one-cell version here
+
+    if (value.length === 1 && value[0].length === 1) {
+      reference.SetCalculatedValue(value[0][0].value as CellValue);
+      return recalculate_list;
+    }
+
+    if (!this.options.spill) {
+      reference.SetCalculatedValue(value[0][0].value as CellValue);
+      return recalculate_list;
+    }
+
+    // console.info("SPILLING");
+
+    const sheet = this.model.sheets.Find(address.sheet_id);
+    const cells = sheet?.cells;
+
+    if (cells) {
+
+      // first thing we do is check for empty. if !empty, that's a 
+      // spill error and we can stop. also check for area, spill and 
+      // merge (and table).
+
+      const columns = result.value.length;
+      const rows = result.value[0].length;
+      const area = new Area(address).Reshape(rows, columns);
+
+
+      /*
+      let counter = 0;
+      let error = false;
+      const leaf = new StateLeafVertex();
+
+      for (const {cell, row, column} of cells.IterateRC(area, true)) {
+        if (counter++ && (cell.type !== ValueType.undefined || cell.area || cell.merge_area || cell.table)) {
+          error = true; // spill error.
+        }
+        this.AddLeafVertexEdge({row, column, sheet_id: area.start.sheet_id}, leaf);
+      }
+
+      console.info("storing spill data");
+
+      // this.spills.push(new Area(area.start, area.end));
+      this.spill_data.push({area, vertex: leaf});
+      */
+
+      const { error } = this.AttachSpillData(area, cells);
+
+      if (error) {
+        // console.info("returning error");
+        reference.SetCalculationError('SPILL');
+        return recalculate_list;
+      }
+
+      // expand the sheet, if necessary (+1)
+
+      if (sheet.rows < area.end.row + 1) {
+        sheet.cells.EnsureRow(area.end.row + 1);
+        this.grid_expanded = true;
+      }
+      if (sheet.columns < area.end.column + 1) {
+        sheet.cells.EnsureColumn(area.end.column + 1);
+        this.grid_expanded = true;
+      }
+
+      // hmmm... we need the grid to update... how can we ensure that?
+      // we could use a flag that the embedded sheet checks after 
+      // calculation... which is kind of sloppy but I don't have a better
+      // idea
+
+
+
+      const sheet_id = address.sheet_id;
+      // let dirty = false;
+
+      for (const {row, column} of cells.IterateRC(area)) {
+        if (row === address.row && column === address.column) { continue; }
+
+        const vertex = this.GetVertex({sheet_id, row, column}, false) as SpreadsheetVertex;
+
+        if (vertex) {
+          // onsole.info("Have vertex @", row, column, "dirty?", vertex.dirty);
+
+          if (!(vertex as SpreadsheetVertex).dirty) {
+            recalculate_list.push(vertex);
+          }
+        }
+
+        // do we need these edges? if so, what for? (...)
+        // I guess to propagate dirty if there's a dependent?
+        // apparently not, although I'm not sure why...
+
+
+        // this.AddEdge(address, {sheet_id, row, column});
+
+      }
+
+      /*
+      // ok, now we can go on: copying a little from dynamic dependencies, 
+      // we're going to add vertices and check for dirty:
+      
+      const sheet_id = address.sheet_id;
+      let dirty = false;
+
+      for (const {row, column} of cells.IterateRC(area)) {
+
+        if (row === address.row && column === address.column) { continue; }
+
+        const vertex = this.GetVertex({sheet_id, row, column}, true);
+        if (vertex && vertex.dirty) {
+
+          console.info(`Adding edge from ${{row: address.row, column: address.column}} -> ${{row, column}}`)
+
+          // see comments in DynamicDependencies()
+          
+          this.AddEdge(address, {row, column, sheet_id});
+          dirty = true;
+
+        }
+
+      }
+
+      console.info("DIRTY?", dirty);
+
+      if (dirty) {
+        const current_vertex = this.GetVertex(address, true) as SpreadsheetVertex;
+        current_vertex.short_circuit = true;
+        return;
+      }
+      */
+
+      //
+
+
+      // maybe we could use a vertex here?
+      // actually we also need to do a loop check
+     
+      // so I think the approach is 
+      //
+      // 1 - create a vertex (spill -- array vertex?)
+      // 2 - check for loops
+      // 3 - if no loop, check for empty
+      // 4 - if empty, fill in values
+      //
+
+      // and then we need to flush spill vertices at
+      // some point, either always on recalc, or on 
+      // recalc if something is dirty. flushing spill
+      // vertices implies removing all spilled values 
+      // so they will be empty if something changes
+
+      // PLAN: start by flushing all spill vertices on
+      // every recalc, and then we can trim it back
+      
+      // spill ok, set values
+
+
+      for (let {cell, row, column} of cells.IterateRC(area)) {
+
+        cell.spill = area;
+
+        row -= address.row;
+        column -= address.column;
+
+        const v = result.value[column][row];
+
+        switch (v.type) {
+          case ValueType.object:
+          case ValueType.array:
+            break;
+          default:
+            cell.SetCalculatedValue(v.value, v.type);
+            break;
+        }
+
+      }
+
+      return recalculate_list;
+
+    }
+
+    // 
+
+    console.error("invalid cell reference in spill callback");
+    reference.SetCalculationError('SPILL');
+
+    return [];
+    
+  }
+
   /**
    * this is a mess [not as bad as it used to be]
    */
@@ -1507,6 +1759,8 @@ export class Calculator extends Graph {
 
     this.RebuildGraph(subset);
 
+    this.grid_expanded = false; // unset
+
     try {
       this.Recalculate();
     }
@@ -2567,7 +2821,23 @@ export class Calculator extends Graph {
    */
   protected RebuildGraphCell(cell: Cell, address: ICellAddress2): void {
 
-    // console.info("RGC", cell, address);
+    // FIXME/TODO: if spill is not enabled, we'll need to clean up
+    // rendered values from the spill here
+
+    if (cell.spill) {
+      if (this.options.spill) {
+        if (cell.spill.start.row === address.row && cell.spill.start.column === address.column) {
+
+          // this.spills.push(new Area(cell.spill.start, cell.spill.end));
+          this.AttachSpillData(new Area(cell.spill.start, cell.spill.end));
+
+        }
+        else {
+          // ... 
+          this.AddEdge(cell.spill.start, address);
+        }
+      }
+    }
 
     // array head
     if (cell.area && cell.area.start.column === address.column && cell.area.start.row === address.row) {

package/treb-calculator/src/dag/array-vertex.ts

@@ -66,16 +66,6 @@ export class ArrayVertex extends SpreadsheetVertexBase {
   /** the target area */
   public area: Area;
 
-  /* * temporary method, we should clean up explicitly * /
-  public static CheckOutbound(): void {
-    for (const vertex of this.list) {
-      if (vertex.edges_out.length === 0) {
-        console.info('no outbound edges', vertex);
-      }
-    }
-  }
-  */
-
   /** 
    * factory/lookup method: creates a vertex if it does not exist, or 
    * returns existing vertex. returns the vertex and a flag indicating