@trebco/treb 28.7.0 → 28.10.0

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;
@@ -849,6 +870,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trebco/treb",
-  "version": "28.7.0",
+  "version": "28.10.0",
   "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

@@ -1769,7 +1769,25 @@ export class Calculator extends Graph {
 
   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 +1851,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 +1873,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

@@ -816,6 +816,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-charts/src/chart-functions.ts

@@ -153,4 +153,15 @@ export const ChartFunctions: FunctionMap = {
     fn: Identity,
   },
 
+  'Bubble.Chart': {
+    arguments: [
+      { name: 'X', metadata: true, },
+      { name: 'Y', metadata: true, },
+      { name: 'Z', metadata: true, },
+      { name: 'Categories' },
+      { name: 'Chart Title' },
+    ],
+    fn: Identity,
+  },
+
 };

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

@@ -107,6 +107,23 @@ export interface ScatterData2 extends ChartDataBaseType {
 
 }
 
+export interface BubbleChartData extends ChartDataBaseType {
+
+  type: 'bubble';
+
+  x?: SubSeries;
+  y?: SubSeries;
+  z?: SubSeries;
+  c?: any[];
+
+  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 +207,7 @@ export type ChartData
   | AreaData
   | ColumnData
   | BarData
+  | BubbleChartData
   ;
 
 export enum LegendLayout {

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

@@ -364,6 +364,93 @@ const ApplyLabels = (series_list: SeriesType[], pattern: string, category_labels
 
 //------------------------------------------------------------------------------
 
+export const CreateBubbleChart = (args: UnionValue[]): ChartData => {
+
+  const [x, y, z] = [0,1,2].map(index => {
+    const arg = args[index];
+    if (arg.type === ValueType.array) {
+      return ArrayToSeries(arg).y;
+    }
+    return undefined;
+  });
+
+  let c: string[]|undefined = undefined;
+  if (Array.isArray(args[3])) {
+    c = Util.Flatten(args[3]).map(value => (value||'').toString());
+  }
+ 
+  const title = args[4]?.toString() || undefined;
+
+  // FIXME: need to pad out the axes by the values at the edges,
+  // so the whole circle is included in the chart area. 
+
+  const [x_scale, y_scale] = [x, y].map(subseries => {
+
+    let series_min = 0;
+    let series_max = 1;
+    let first = false;
+
+    if (subseries?.data) {
+
+      for (const [index, value] of subseries.data.entries()) {
+        if (typeof value === 'number') {
+
+          if (!first) {
+            first = true;
+            series_min = value;
+            series_max = value;
+          }
+
+          const size = (z?.data?.[index]) || 0;
+          series_min = Math.min(series_min, value - size / 2);
+          series_max = Math.max(series_max, value + size / 2);
+        }      
+      }
+    }
+
+    return Util.Scale(series_min, series_max, 7);
+
+  });
+
+  let x_labels: string[] | undefined;
+  let y_labels: string[] | undefined;
+
+  if (x?.format) {
+    x_labels = [];
+    const format = NumberFormatCache.Get(x.format);
+    for (let i = 0; i <= x_scale.count; i++) {
+      x_labels.push(format.Format(x_scale.min + i * x_scale.step));
+    }
+  }
+
+  if (y?.format) {
+    y_labels = [];
+    const format = NumberFormatCache.Get(y.format);
+    for (let i = 0; i <= y_scale.count; i++) {
+      y_labels.push(format.Format(y_scale.min + i * y_scale.step));
+    }
+  }
+
+  return {
+
+    type: 'bubble',
+
+    title,
+
+    x,
+    y,
+    z,
+    c,
+    
+    x_scale,
+    y_scale,
+
+    x_labels, 
+    y_labels,
+
+  };
+
+};
 
 /**
  * args is [data, title, options]

package/treb-charts/src/chart.ts

@@ -64,6 +64,10 @@ export class Chart {
         this.chart_data = ChartUtils.CreateScatterChart(args, 'line');
         break;
   
+      case 'bubble.chart':
+        this.chart_data = ChartUtils.CreateBubbleChart(args);
+        break;
+
       default:
         this.Clear();
         break;

package/treb-charts/src/default-chart-renderer.ts

@@ -95,6 +95,7 @@ export class DefaultChartRenderer implements ChartRendererType {
         || chart_data.type === 'histogram2'
         || chart_data.type === 'bar'
         || chart_data.type === 'scatter2'
+        || chart_data.type === 'bubble'
         ) {
 
       // we need to measure first, then lay out the other axis, then we
@@ -122,7 +123,7 @@ export class DefaultChartRenderer implements ChartRendererType {
         let max_width = 0;
         let max_height = 0;
 
-        const scale = (chart_data.type === 'scatter2') ? chart_data.y_scale : chart_data.scale;
+        const scale = (chart_data.type === 'scatter2' || chart_data.type === 'bubble') ? chart_data.y_scale : chart_data.scale;
         
         const count = (chart_data.type === 'bar') ? 
           chart_data.y_labels.length :
@@ -163,6 +164,7 @@ export class DefaultChartRenderer implements ChartRendererType {
           chart_data.type !== 'area' && 
           chart_data.type !== 'bar' && 
           chart_data.type !== 'scatter2' && 
+          chart_data.type !== 'bubble' && 
           chart_data.type !== 'histogram2' 
           );
 
@@ -199,6 +201,29 @@ export class DefaultChartRenderer implements ChartRendererType {
       this.renderer.RenderPoints(area, chart_data.x, chart_data.y, 'mc mc-correlation series-1');
       break;
 
+    case 'bubble':
+
+      this.renderer.RenderGrid(area, 
+        chart_data.y_scale.count, 
+        chart_data.x_scale.count + 1, // (sigh)
+        'chart-grid');
+
+      if (chart_data.x && chart_data.y && chart_data.z) {
+        this.renderer.RenderBubbleSeries(area,
+            chart_data.x.data,
+            chart_data.y.data,
+            chart_data.z.data,
+            chart_data.c || [],
+            chart_data.x_scale,
+            chart_data.y_scale,
+            undefined,
+            undefined,
+            'bubble-chart',
+          );
+      }
+
+      break;
+
     case 'scatter2':
 
       this.renderer.RenderGrid(area, 

package/treb-charts/src/renderer.ts

@@ -1193,6 +1193,87 @@ export class ChartRenderer {
 
   }
 
+  public RenderBubbleSeries(area: Area,
+        x: Array<number | undefined>,
+        y: Array<number | undefined>,
+        z: Array<number | undefined>,
+        c: any[] = [],
+        x_scale: RangeScale,
+        y_scale: RangeScale,
+        min = 10,
+        max = 30,
+        classes?: string | string[]): void {
+
+    const count = Math.max(x.length, y.length, z.length);
+    const xrange = (x_scale.max - x_scale.min) || 1;
+    const yrange = (y_scale.max - y_scale.min) || 1;
+
+    // const marker_elements: string[] = [];
+    const points: Array<{x: number, y: number, z: number, series: number} | undefined> = [];
+
+    const d: string[] = [];
+    const areas: string[] = [];
+
+    const group = SVGNode('g', {class: classes});
+
+    // if (title) node.setAttribute('title', title);
+    this.group.appendChild(group);
+
+    let z_min = z[0] || 0;
+    let z_max = z[0] || 0;
+
+    const map: Map<string, number> = new Map();
+
+    for (let i = 0; i < count; i++) {
+
+      const a = x[i];
+      const b = y[i];
+
+      if (typeof a === 'undefined' || typeof b === 'undefined') {
+        points.push(undefined);
+      }
+      else {
+
+        const series_key = c[i] || '';
+        let series = map.get(series_key);
+
+        if (typeof series === 'undefined') {
+
+          series = map.size + 1;
+
+          map.set(series_key, series);
+        }
+
+        let size = z[i] || 0;
+        if (size) {
+          const size_x = size / xrange * area.width;
+          const size_y = size / yrange * area.height;
+          size = Math.min(size_x, size_y);
+        }
+
+        points.push({
+          x: area.left + ((a - x_scale.min) / xrange) * area.width,
+          y: area.bottom - ((b - y_scale.min) / yrange) * area.height,
+          z: size,
+          series,
+        });
+
+      }
+
+    }
+     
+    {
+      for (const point of points) {
+        if (point) {
+          group.appendChild(SVGNode('circle', {cx: point.x, cy: point.y, r: point.z / 2, class: `point series-${point.series}`}));
+        }
+      }
+
+    }
+
+
+  }
+
   public RenderScatterSeries(area: Area,
     x: Array<number | undefined>,
     y: Array<number | undefined>,

package/treb-charts/style/charts.scss

@@ -161,6 +161,14 @@
     }
   }
 
+  .bubble-chart {
+
+    stroke-width: 3;
+    fill: color-mix(in srgb, currentColor 75%, transparent);
+    stroke: currentColor;
+    
+  }
+
   /* scatter plot line (and marker -- change that class name) */
   .scatter-plot {
 

package/treb-embed/markup/toolbar.html

@@ -65,6 +65,27 @@
     </div>
   </div>
 
+  <div composite>
+    <button data-command="border-bottom" data-target="border" title="Bottom border"></button>
+    <div class="treb-menu">
+      <button dropdown title="Border options"></button>
+      <div class="treb-icon-buttons" data-replace="border">
+        <button data-command="border-top" title="Top border"></button>        
+        <button data-command="border-left" title="Left border"></button>        
+        <button data-command="border-right" title="Right border"></button>        
+        <button data-command="border-bottom" title="Bottom border"></button>        
+        <button data-command="border-double-bottom" title="Double bottom border"></button>        
+        <button data-command="border-outside" title="Outside borders"></button>        
+        <button data-command="border-all" title="All borders"></button>        
+        <button data-command="border-none" title="Clear borders"></button>        
+        <div separator></div>
+        <div class="treb-menu treb-color-menu treb-submenu" data-color-command="border-color" data-replace-color="border" title="Border color" data-default-color-text="Default border color">
+          <button data-icon="palette" data-color-bar="border" data-color="{}"></button>
+        </div>
+      </div>
+    </div>
+  </div>
+
   <div composite>
     <button data-command="fill-color" data-color-bar="fill" data-color="{}" title="Fill color"></button>
     <div class="treb-menu treb-color-menu" data-color-command="fill-color" data-replace-color="fill" data-default-color-text="No fill">
@@ -94,28 +115,8 @@
     </div>
   </div>
 
-  <div composite>
-    <button data-command="border-bottom" data-target="border" title="Bottom border"></button>
-    <div class="treb-menu">
-      <button dropdown title="Border options"></button>
-      <div class="treb-icon-buttons" data-replace="border">
-        <button data-command="border-top" title="Top border"></button>        
-        <button data-command="border-left" title="Left border"></button>        
-        <button data-command="border-right" title="Right border"></button>        
-        <button data-command="border-bottom" title="Bottom border"></button>        
-        <button data-command="border-double-bottom" title="Double bottom border"></button>        
-        <button data-command="border-outside" title="Outside borders"></button>        
-        <button data-command="border-all" title="All borders"></button>        
-        <button data-command="border-none" title="Clear borders"></button>        
-        <div separator></div>
-        <div class="treb-menu treb-color-menu treb-submenu" data-color-command="border-color" data-replace-color="border" title="Border color" data-default-color-text="Default border color">
-          <button data-icon="palette" data-color-bar="border" data-color="{}"></button>
-        </div>
-      </div>
-    </div>
-  </div>
-
   <div composite font-scale>
+    <div class="treb-font-scale-icon"></div>
     <input class="treb-font-scale" title="Font scale">
     <div class="treb-menu">
       <button dropdown title="Font scale options"></button>
@@ -131,19 +132,6 @@
     </div>
   </div>
 
-  <div class="treb-menu">
-    <button data-icon="layout" title="Rows & columns"></button>
-    <div>
-      <button data-command="insert-row">Insert row</button>
-      <button data-command="insert-column">Insert column</button>
-      <button data-command="delete-row">Delete row</button>
-      <button data-command="delete-column">Delete column</button>
-      <div separator add-remove-sheet></div>
-      <button data-command="insert-sheet" add-remove-sheet>Add sheet</button>
-      <button data-command="delete-sheet" add-remove-sheet>Delete sheet</button>
-    </div>
-  </div>
-
   <div composite>
     <input class="treb-number-format" title="Number format">
     <div class="treb-menu">
@@ -157,6 +145,19 @@
     <button data-command="increase-precision" title="Increase precision"></button>
   </div>
 
+  <div class="treb-menu">
+    <button data-icon="layout" title="Rows & columns"></button>
+    <div>
+      <button data-command="insert-row">Insert row</button>
+      <button data-command="insert-column">Insert column</button>
+      <button data-command="delete-row">Delete row</button>
+      <button data-command="delete-column">Delete column</button>
+      <div separator add-remove-sheet></div>
+      <button data-command="insert-sheet" add-remove-sheet>Add sheet</button>
+      <button data-command="delete-sheet" add-remove-sheet>Delete sheet</button>
+    </div>
+  </div>
+
   <div composite chart-menu>
     <button data-command="insert-column-chart" data-target="annotation" title="Insert column chart"></button>
     <div class="treb-menu">