@trebco/treb 28.7.0 → 28.10.5

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v28.7. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v28.10. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -19,12 +19,20 @@ declare global {
 export declare class TREBGlobal {
 
     /**
-     * build version
+     * Package version
      */
     version: string;
 
     /**
-     * create a spreadsheet instance
+     * Create a spreadsheet. The `USER_DATA_TYPE` template parameter is the type
+     * assigned to the `user_data` field of the spreadsheet instance -- it can
+     * help simplify typing if you are storing extra data in spreadsheet
+     * files.
+     *
+     * Just ignore this parameter if you don't need it.
+     *
+     * @typeParam USER_DATA_TYPE - type for the `user_data` field in the
+     * spreadsheet instance
      */
     CreateSpreadsheet<USER_DATA_TYPE = unknown>(options: EmbeddedSpreadsheetOptions): EmbeddedSpreadsheet<USER_DATA_TYPE>;
 }
@@ -256,6 +264,13 @@ export interface EmbeddedSpreadsheetOptions {
      * top-left of the spreadsheet when a network document has local changes.
      */
     revert_indicator?: boolean;
+
+    /**
+     * handle the F9 key and recalculate the spreadsheet. for compatibility.
+     * we're leaving this option to default `false` for now, but that may
+     * change in the future. key modifiers have no effect.
+     */
+    recalculate_on_f9?: boolean;
 }
 
 /**
@@ -291,11 +306,17 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     /** document name (metadata) */
     set document_name(name: string | undefined);
 
-    /** opaque user data (metadata) */
+    /**
+     * opaque user data (metadata). `USER_DATA_TYPE` is a template
+     * parameter you can set when creating the spreadsheet.
+     */
     get user_data(): USER_DATA_TYPE | undefined;
 
-    /** opaque user data (metadata) */
-    set user_data(data: USER_DATA_TYPE);
+    /**
+     * opaque user data (metadata). `USER_DATA_TYPE` is a template
+     * parameter you can set when creating the spreadsheet.
+     */
+    set user_data(data: USER_DATA_TYPE | undefined);
 
     /** current grid scale */
     get scale(): number;
@@ -417,6 +438,8 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      * Add a sheet, optionally named.
      */
     AddSheet(name?: string): number;
+    RemoveConnectedChart(id: number): void;
+    UpdateConnectedChart(id: number, formula: string): void;
 
     /**
      * Insert an annotation node. Usually this means inserting a chart. Regarding
@@ -849,6 +872,16 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      */
     FormatNumber(value: number, format?: string): string;
 
+    /**
+     * convert a javascript date (or timestamp) to a spreadsheet date
+     */
+    SpreadsheetDate(javascript_date: number | Date): number;
+
+    /**
+     * convert a spreadsheet date to a javascript date
+     */
+    JavascriptDate(spreadsheet_date: number): number;
+
     /**
      * Apply borders to range.
      *

package/notes/connected-elements.md

@@ -0,0 +1,37 @@
+
+
+"Connected elements" refers to a new API that's intended to link things 
+outside of the spreadsheet to the spreadsheet's graph and calculation events.
+
+The canonical example is a chart that lives outside of the spreadsheet.
+It should be updated any time the spreadsheet data changes. It should 
+also gracefully handle layout modifications (change sheet name, insert/delete
+rows/columns) as if it were inside the spreadsheet.
+
+One thing about these is that they're ephemeral; they have no persistent 
+representation in the data model. So you create them when you lay out your 
+web page, and they only exist for the lifetime of that page.
+
+Still TODO:
+
+ - clean up junk (when?)
+    As long as we remove the leaf nodes from the graph, it should be
+    clean. 
+
+ - deal with model rebuild (elements are getting orphaned here)
+    I think this is handled? still maybe an issue on Reset()
+
+ - API to update elements (e.g. change formula w/o removing)
+    that last one could be implemented as remove/add, possibly 
+    reusing the generated ID. at least as a first cut.
+
+Done:
+
+ - API to remove elements
+
+ - rewrite formula on layout changes
+
+Open Qs:
+
+ - what happens if you completely flush the data model (reset, load new file?)
+

package/package.json

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

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

@@ -15,7 +15,7 @@ export class Gradient {
 
   public mapped: Array<GradientStop & { resolved: number[] }>;
 
-  constructor(stops: GradientStop[], theme: Theme, public color_space: ColorSpace = 'HSL') {
+  constructor(stops: GradientStop[], theme: Theme, public color_space: ColorSpace = 'RGB') {
 
     this.mapped = stops.map(stop => {
 

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

@@ -98,6 +98,12 @@ export class Localization {
 
     }
 
+    // don't allow the "C" locale
+    if (this.locale === 'C') {
+      console.warn('Locale not set, defaulting to en-us');
+      this.locale = 'en-us';
+    }
+   
     const decimal_separator = new Intl.NumberFormat(this.locale,
       {minimumFractionDigits: 1}).format(3.3).replace(/\d/g, '');
 

package/treb-calculator/src/calculator.ts

@@ -55,6 +55,7 @@ import type { LeafVertex } from './dag/graph';
 import { ArgumentError, ReferenceError, UnknownError, ValueError, ExpressionError, NAError, DivideByZeroError } from './function-error';
 import { StateLeafVertex } from './dag/state_leaf_vertex';
 import { CalculationLeafVertex } from './dag/calculation_leaf_vertex';
+import type { ConnectedElementType } from 'treb-grid';
 
 /**
  * breaking this out so we can use it for export (TODO)
@@ -1291,6 +1292,7 @@ export class Calculator extends Graph {
       subset = undefined;
       this.UpdateAnnotations();
       this.UpdateConditionals();
+      this.UpdateConnectedElements();
       // this.UpdateNotifiers();
       this.full_rebuild_required = false; // unset
     }
@@ -1488,6 +1490,7 @@ export class Calculator extends Graph {
 
     this.UpdateAnnotations(); // all
     this.UpdateConditionals();
+    this.UpdateConnectedElements();
 
     // and notifiers
 
@@ -1767,9 +1770,73 @@ export class Calculator extends Graph {
     }
   }
 
+  public RemoveConnectedELement(element: ConnectedElementType) {
+    let internal = element.internal as { vertex: StateLeafVertex };
+    if (internal?.vertex) {
+      this.RemoveLeafVertex(internal.vertex);
+      return true;
+    }
+    return false;
+  }
+
+  public UpdateConnectedElements(context?: Sheet, element?: ConnectedElementType) {
+
+    // we have a problem here in that these elements are not bound
+    // to sheets, so we might have no context. for now we'll 
+    // just grab the first sheet, although that's not necessarily
+    // what you want. we should enforce that these have hard sheet 
+    // references when created.
+    
+    if (!context) {
+      context = this.model.sheets.list[0];
+    }
+
+    if (element) {
+      let internal = element.internal as { vertex: StateLeafVertex };
+      if (internal?.vertex) {
+        this.RemoveLeafVertex(internal.vertex);
+      }
+    }
+
+    const elements = element ? [element] : this.model.connected_elements.values();
+
+    for (const element of elements) {
+      let internal = element.internal as { vertex: StateLeafVertex };
+      if (!internal) {
+        internal = {
+          vertex: new StateLeafVertex(),
+        };
+        element.internal = internal;
+      }
+
+      const vertex = internal.vertex as LeafVertex;
+      this.AddLeafVertex(vertex);
+      this.UpdateLeafVertex(vertex, element.formula, context);
+
+    }
+  }
+
   public UpdateConditionals(list?: ConditionalFormat|ConditionalFormat[], context?: Sheet): void {
 
+    // this method is (1) relying on the leaf vertex Set to avoid duplication,
+    // and (2) leaving orphansed conditionals in place. we should look to 
+    // cleaning things up. 
+
+    // is it also (3) adding unecessary calculations (building the expression,
+    // below)?
+
     if (!list) {
+
+      // we could in theory remove all of the leaves (the ones we know to
+      // be used for conditionals), because they will be added back below.
+      // how wasteful is that?
+      
+      // or maybe we could change the mark, and then use invalid marks 
+      // to check?
+
+      // the alternative is just to leave them as orphans until the graph
+      // is rebuilt. which is lazy, but probably not that bad... 
+
       for (const sheet of this.model.sheets.list) {
         if (sheet.conditional_formats?.length) {
           this.UpdateConditionals(sheet.conditional_formats, sheet);
@@ -1833,7 +1900,11 @@ export class Calculator extends Graph {
         entry.internal = {};
       }
       if (!entry.internal.vertex) {
-        entry.internal.vertex = new CalculationLeafVertex();
+
+        const vertex = new CalculationLeafVertex();
+        vertex.use = 'conditional';
+
+        entry.internal.vertex = vertex;
 
         let options: EvaluateOptions|undefined;
         if (entry.type !== 'gradient' && entry.type !== 'duplicate-values') {
@@ -1851,35 +1922,6 @@ export class Calculator extends Graph {
       this.AddLeafVertex(vertex);
       this.UpdateLeafVertex(vertex, expression, context);
 
-      /*
-      if (entry.type === 'cell-match') {
-        if (!entry.internal) {
-          entry.internal = {};
-        }
-        if (!entry.internal.vertex) {
-          entry.internal.vertex = new CalculationLeafVertex();
-        }
-        const vertex = entry.internal.vertex as LeafVertex;
-        this.AddLeafVertex(vertex);
-        this.UpdateLeafVertex(vertex, entry.expression, context);
-      }
-      else if (entry.type === 'expression') {
-        if (!entry.internal) {
-          entry.internal = {};
-        }
-        if (!entry.internal.vertex) {
-          entry.internal.vertex = new CalculationLeafVertex();
-
-          // set initial state based on current state
-          entry.internal.vertex.result = { type: ValueType.boolean, value: !!entry.applied };
-
-        }
-        const vertex = entry.internal.vertex as LeafVertex;
-        this.AddLeafVertex(vertex);
-        this.UpdateLeafVertex(vertex, entry.expression, context);
-      }
-      */
-
     }
 
   }

package/treb-calculator/src/dag/calculation_leaf_vertex.ts

@@ -42,6 +42,13 @@ export class CalculationLeafVertex extends SpreadsheetVertex {
   
   public address = { row: -1, column: -1 }; // fake address
 
+  /**
+   * this type is currently only used for conditional formatting.
+   * but that might change in the future. I want to identify what
+   * it's used for so we can selectively prune them when necessary.
+   */
+  public use?: string;
+
   /** 
    * flag, to reduce unecessary application. work in progress. this
    * indicates that we reached the calculation step. that means either

package/treb-calculator/src/dag/graph.ts

@@ -31,6 +31,7 @@ import type { DataModel } from 'treb-grid';
 import { CalculationLeafVertex } from './calculation_leaf_vertex';
 
 export type LeafVertex = StateLeafVertex|CalculationLeafVertex;
+export type { StateLeafVertex };
 
 // FIXME: this is a bad habit if you're testing on falsy for OK.
 
@@ -816,6 +817,13 @@ export abstract class Graph implements GraphCallbacks {
    * managing and maintaining these vertices: we only need references.
    */
   public AddLeafVertex(vertex: LeafVertex): void {
+
+    /*
+    if (this.leaf_vertices.has(vertex)) {
+      console.info("TLV already has", vertex);
+    }
+    */
+
     this.leaf_vertices.add(vertex); 
   }
 

package/treb-calculator/src/functions/base-functions.ts

@@ -848,6 +848,17 @@ export const BaseFunctionLibrary: FunctionMap = {
       }),
     },
 
+    RoundUp: {
+      fn: Utils.ApplyAsArray2((a, digits = 0) => {
+        const m = Math.pow(10, digits);
+        const positive = a >= 0;
+        return { 
+          type: ValueType.number, 
+          value: positive ? Math.ceil(m * a) / m : Math.floor(m * a) / m,
+        };
+      }),
+    },
+
     /*
 
     Round: {
@@ -1259,13 +1270,31 @@ export const BaseFunctionLibrary: FunctionMap = {
           columns = area.value[0]?.length || 0;
 
           const result: UnionValue[][] = [];
+
           for (let r = 0; r < rows; r++) {
             const row: UnionValue[] = [];
             for (let c = 0; c < columns; c++) {
               const src = area.value[r][c];
               if (src.type === ValueType.number) {
                 let calc = 0;
-                if (range > 0) {
+
+                // special case: max === min. this can be used to do binary 
+                // coloring over a set of data (ignoring the pivot).
+
+                // FIXME: use a separate loop?
+
+                if (max === min) {
+                  if (src.value > max) {
+                    calc = 1;
+                  }
+                  else if (src.value < max) {
+                    calc = 0;
+                  }
+                  else {
+                    calc = 0.5
+                  }
+                }
+                else if (range > 0) {
                   calc = (src.value - min) / range;
                 }
                 row.push({ type: ValueType.number, value: calc });

package/treb-calculator/src/index.ts

@@ -24,4 +24,4 @@ export * from './calculator';
 
 // for annotations that have dependencies
 
-export type { LeafVertex } from './dag/graph';
+export type { LeafVertex, StateLeafVertex } from './dag/graph';

package/treb-charts/src/chart-functions.ts

@@ -60,14 +60,20 @@ export const ChartFunctions: FunctionMap = {
    * more general "group" if you just want to group things.
    * 
    * boxing properly as "extended" type
+   * 
+   * this is getting too specific to bubble charts, which have a lot
+   * of requirements that other charts don't have. can we split? 
+   * 
    */
   Series: {
     arguments: [
       { name: 'Label' }, // , metadata: true, },
       { name: 'X', metadata: true, },
       { name: 'Y', metadata: true, },
+      { name: 'Z', metadata: true, },
       { name: 'index', },
       { name: 'subtype', },
+      { name: 'Labels', description: 'Labels for bubble charts only (atm)' },
     ],
     fn: (...args: any) => {
       return {
@@ -153,4 +159,12 @@ export const ChartFunctions: FunctionMap = {
     fn: Identity,
   },
 
+  'Bubble.Chart': {
+    arguments: [
+      { name: 'Data', metadata: true, },
+      { name: 'Chart Title' },
+    ],
+    fn: Identity,
+  },
+
 };

package/treb-charts/src/chart-types.ts

@@ -107,6 +107,27 @@ export interface ScatterData2 extends ChartDataBaseType {
 
 }
 
+export interface BubbleChartData extends ChartDataBaseType {
+
+  type: 'bubble';
+
+  /*
+  x?: SubSeries;
+  y?: SubSeries;
+  z?: SubSeries;
+  c?: any[];
+  */
+  series: SeriesType[];
+
+
+  x_scale: RangeScale;
+  y_scale: RangeScale;
+
+  x_labels?: string[];
+  y_labels?: string[];
+
+}
+
 /** base for column types (FIXME: probably common to scatter/line/area also) */
 export interface ColumnDataBaseType extends ChartDataBaseType {
   column_width: number;
@@ -190,6 +211,7 @@ export type ChartData
   | AreaData
   | ColumnData
   | BarData
+  | BubbleChartData
   ;
 
 export enum LegendLayout {
@@ -201,7 +223,7 @@ export enum LegendPosition {
 }
 
 export enum LegendStyle {
-  line, marker
+  line, marker, bubble
 }
 
 export interface LegendOptions {
@@ -225,6 +247,8 @@ export interface SeriesType {
   subtype?: string;
   x: SubSeries;
   y: SubSeries;
+  z?: SubSeries;
   index?: number;
+  labels?: string[];
 }