@trebco/treb 25.9.1 → 26.0.3

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

@@ -100,7 +100,7 @@ export interface ClickFunctionResult {
 export type ClickFunction = (options: ClickFunctionOptions) => ClickFunctionResult;
 
 
-/**
+/*
  * restructuring from the old system, which had lots of separate arrays for
  * things. for the most part I think having a single array (or object) with
  * objects will be more useful (if not necessarily more efficient). the
@@ -121,11 +121,11 @@ export type ClickFunction = (options: ClickFunctionOptions) => ClickFunctionResu
  * validation TODO: date, number, boolean, &c
  */
 export enum ValidationType {
-  List,
-  Date,
-  Range,
-  Number,
-  Boolean,
+  List = 'list',
+  Date = 'date',
+  Range = 'range',
+  Number = 'number',
+  Boolean = 'boolean',
 }
 
 export interface DataValidationBase {
@@ -133,25 +133,25 @@ export interface DataValidationBase {
 }
 
 export interface DataValidationRange extends DataValidationBase {
-  type: ValidationType.Range;
+  type: 'range'; // ValidationType.Range;
   area: IArea;
 }
 
 export interface DataValidationList extends DataValidationBase {
-  type: ValidationType.List;
+  type: 'list'; // ValidationType.List;
   list: CellValue[];
 }
 
 export interface DataValidationDate extends DataValidationBase {
-  type: ValidationType.Date;
+  type: 'date'; // ValidationType.Date;
 }
 
 export interface DataValidationNumber extends DataValidationBase {
-  type: ValidationType.Number;
+  type: 'number'; // ValidationType.Number;
 }
 
 export interface DataValidationBoolean extends DataValidationBase {
-  type: ValidationType.Boolean;
+  type: 'boolean'; // ValidationType.Boolean;
 }
 
 export type DataValidation 

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

@@ -29,7 +29,7 @@ import { Area, IsCellAddress } from './area';
 import type { DataValidation } from './cell';
 import { Cell } from './cell';
 import type { Table } from './table';
-import { ValueType, GetValueType } from './value-type';
+import { type SerializedValueType, ValueType, GetValueType, ValueTypeList } from './value-type';
 import type { CellValue, UnionValue } from './union';
 import type { Style } from './style';
 
@@ -80,10 +80,10 @@ export interface BaseCellData {
   area?: IArea;
   merge_area?: IArea;
   validation?: DataValidation;
-  calculated_type?: ValueType;
+  calculated_type?: SerializedValueType; //  ValueType;
   note?: string;
   hyperlink?: string;
-  type?: ValueType;
+  type?: SerializedValueType; // ValueType;
   sheet_id?: number;
   // locked?: boolean;
 }
@@ -132,6 +132,17 @@ export const IsNestedRowArray = (test: NestedRowData[]|NestedColumnData[]): test
 
 // ...
 
+
+/** 
+ * this is the reverse map, i.e. type => number 
+ * FIXME: why is this getting exported by the API generator?
+ * FIXME: I get why it's dynamic, but for practical purposes why not just 
+ * create a static map?
+ */
+const ValueTypeMap = 
+  ValueTypeList.map((key, index) => ({ [key]: index })).reduce((set, value) => ({...set, ...value}), {}) as Record<SerializedValueType, ValueType>;
+
+
 /**
  * collection of cells, basically a wrapper around an
  * array, with some accessor and control methods.
@@ -357,6 +368,53 @@ export class Cells {
     this.columns_ = columns;
   }
 
+  public SerializedTypeToValueType(type?: SerializedValueType|ValueType): ValueType|undefined {
+
+    if (!type) {
+      return undefined;
+    }
+
+    if (typeof type === 'number') {
+      return type as ValueType;
+    }
+
+    return ValueTypeMap[type] || undefined;
+
+  }
+
+  public ValueTypeToSerializedType(type?: ValueType): SerializedValueType|undefined {
+    return type ? ValueTypeList[type] : undefined;
+  }
+
+  /**
+   * this method is used for importing legacy data validation types. in those
+   * those we used a numeric enum. we're just dropping that altogether (c.f.
+   * ValueType, which we're keeping) so we need to translate for backcompat. 
+   * it's ugly, but it gets us to a better place. we can probably drop at some
+   * point in the future.
+   * 
+   * export enum ValidationType {
+   *   List = 'list',
+   *   Date = 'date',
+   *   Range = 'range',
+   *   Number = 'number',
+   *   Boolean = 'boolean',
+   * }
+   * 
+   */
+  public ImportDataValidation(value: DataValidation): DataValidation|undefined {
+
+    if (typeof (value as any).type === 'number') {
+      const types = ['list', 'date', 'range', 'number', 'boolean'];
+      (value as any).type = types[(value as any).type];
+      if (!value.type) {
+        return undefined;
+      }
+    }
+
+    return value;
+  }
+
   /**
    * UPDATE: adding optional style refs, for export
    */
@@ -423,7 +481,7 @@ export class Cells {
       if (typeof obj.calculated !== 'undefined') {
         // cell.calculated = obj.calculated;
         // cell.calculated_type = obj.calculated_type;
-        cell.SetCalculatedValue(obj.calculated, obj.calculated_type);
+        cell.SetCalculatedValue(obj.calculated, this.SerializedTypeToValueType(obj.calculated_type));
       }
 
       if (style_refs) {
@@ -494,7 +552,13 @@ export class Cells {
       }
 
       if (obj.validation) {
-        cell.validation = obj.validation;
+
+        // the old type used a numeric enum. we just dropped that in favor
+        // of a string enum, so we can export it as a type. but for backwards
+        // compatibility we still need to think about the numeric enum.
+
+        cell.validation = this.ImportDataValidation(obj.validation);
+
       }
 
     }
@@ -606,7 +670,9 @@ export class Cells {
               obj.hyperlink = cell.hyperlink;
             }
 
-            if (options.preserve_type) obj.type = cell.type;
+            if (options.preserve_type) {
+              obj.type = this.ValueTypeToSerializedType(cell.type);
+            }
             if (options.sheet_id) obj.sheet_id = options.sheet_id;
             if (options.calculated_value &&
                 typeof cell.calculated !== 'undefined') { // && cell.calculated_type !== ValueType.error) {
@@ -614,7 +680,7 @@ export class Cells {
 
               // always preserve error type, because we can't infer
               if (options.preserve_type || cell.calculated_type === ValueType.error) {
-                obj.calculated_type = cell.calculated_type;
+                obj.calculated_type = this.ValueTypeToSerializedType(cell.calculated_type);
               }
             }
             if (cell.table && table_head) {

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

@@ -20,7 +20,7 @@
  */
 
 import type { Style } from './style';
-import type { ValueType } from './value-type';
+import type { SerializedValueType, ValueType } from './value-type';
 import type { IArea } from './area';
 import type { AnnotationLayout } from './layout';
 import type { DataValidation } from './cell';
@@ -30,10 +30,10 @@ import type { AnnotationType } from 'treb-grid';
 export interface CellParseResult {
   row: number,
   column: number,
-  type: ValueType,
+  type: SerializedValueType; // ValueType,
   value: number|string|undefined|boolean,
   calculated?: number|string|undefined|boolean,
-  calculated_type?: ValueType,
+  calculated_type?: SerializedValueType; // ValueType,
   style_ref?: number,
   hyperlink?: string,
   validation?: DataValidation,

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

@@ -84,12 +84,44 @@ export const IsDimensionedQuantity = (value: unknown): value is DimensionedQuant
           && (typeof (value as DimensionedQuantity).unit === 'string');
 };
 
+/** 
+ * this is the list of value types. internally, we use an enum. I don't 
+ * want to change that, at least not at the moment, but that presents a
+ * problem for exporting types.
+ * 
+ * we'll switch to string types for import/export, although we still support
+ * importing the old numeric enum types for backwards compatibility.
+ */
+export const ValueTypeList = [
+  'undefined',
+  'formula',
+  'string',
+  'number',
+  'boolean',
+  'object',
+  'error',
+  'complex',
+  'array',
+  'dimensioned_quantity',
+] as const;
+
 /**
- * I _think_ using enums is faster. I'm not actually sure about that, though.
- * it stands to reason that a single int compare is faster than a string
- * compare, but you never know with javascript. undefined preferred over null.
- * formula implies a string.
- *
+ * string types for import/export
+ */
+export type SerializedValueType = typeof ValueTypeList[number];
+
+/**
+ * this enum goes back a long way and is pretty ingrained, so I don't 
+ * want to change it (at least not right now). but if we're exporting types, 
+ * using enums is a problem.
+ * 
+ * what we will do is keep the enum internally but switch the exported type
+ * to a string. the problem then becomes keeping the types matched up 
+ * properly. I can't arrive at a good way of doing that automatically. 
+ * 
+ * old comments:
+ * ---
+ * 
  * undefined is 0 so we can test it as falsy.
  *
  * we're passing this type information out to calculators, so it needs

package/treb-embed/src/types.ts

@@ -46,23 +46,61 @@ export enum SaveFileType {
  * I would like to do it, though, that `any` looks bad in the  public API.
  */
 export interface TREBDocument {
+
+  /** app name, as identifier */
   app: string;
+
+  /** app version. we'll warn if you use a file from a newer version */
   version: string;
+
+  /** 
+   * revision number. this is a value that increments on any document change,
+   * useful for checking if a document is "dirty".
+   */
   revision?: number;
+
+  /** document name */
   name?: string;
+
+  /** 
+   * opaque user data. we don't read or parse this, but applications can
+   * use it to store arbitrary data.
+   */
   user_data?: any;
-  sheet_data?: SerializedSheet|SerializedSheet[]; // NOTE: support old version, but it would be nice to drop
+
+  /**
+   * per-sheet data. this should be an array, but for historical reasons
+   * we still support a single sheet outside of an array.
+   */
+  sheet_data?: SerializedSheet|SerializedSheet[];
+
+  /** document decimal mark */
   decimal_mark?: '.' | ',';
+
+  /** active sheet. if unset we'll show the first un-hidden sheet */
   active_sheet?: number;
+  
+  /** 
+   * this document includes rendered calculated values. using this lets the
+   * app show a document faster, without requiring an initial calculation.
+   */
   rendered_values?: boolean;
   
-  // named_ranges?: {[index: string]: IArea};
+  /** document named ranges */
   named_ranges?: Record<string, IArea>;
 
-  macro_functions?: SerializedMacroFunction[];
+  /** document named expressions */
   named_expressions?: SerializedNamedExpression[];
+
+  /** document macro functions */
+  macro_functions?: SerializedMacroFunction[];
+
+  /** document tables */
   tables?: Table[];
+
+  /** document shared resources (usually images) */
   shared_resources?: Record<string, string>;
+
 }
 
 export interface ResizeEvent {

package/treb-export/src/import2.ts

@@ -29,7 +29,7 @@ import { Parser } from 'treb-parser';
 import type { RangeType, AddressType, HyperlinkType } from './address-type';
 import { is_range, ShiftRange, InRange, is_address } from './address-type';
 import type { ImportedSheetData, AnchoredAnnotation, CellParseResult, AnnotationLayout, Corner as LayoutCorner, ICellAddress, DataValidation, IArea } from 'treb-base-types/src';
-import { ValueType, ValidationType } from 'treb-base-types/src';
+import { type ValueType, ValidationType, type SerializedValueType } from 'treb-base-types/src';
 import type { Sheet} from './workbook-sheet2';
 import { VisibleState } from './workbook-sheet2';
 import type { CellAnchor } from './drawing2/drawing2';
@@ -119,11 +119,13 @@ export class Importer {
     // console.info(element);
 
     let value: undefined | number | boolean | string;
-    let type: ValueType = ValueType.undefined;
+    // let type: ValueType = ValueType.undefined;
+    let type: SerializedValueType = 'undefined';
 
     let calculated_value: undefined | number | boolean | string;
-    let calculated_type: ValueType = ValueType.undefined;
-
+    // let calculated_type: ValueType = ValueType.undefined;
+    let calculated_type: SerializedValueType = 'undefined';
+    
     // QUESTIONS:
     //
     // 1. is v always a value, or can it be an object?
@@ -147,7 +149,7 @@ export class Importer {
     // console.info(address, 'e', element, 'm', mapped);
 
     if (element.a$?.t && element.a$.t === 's') {
-      type = ValueType.string;
+      type = 'string'; // ValueType.string;
       if (typeof element.v !== undefined) {
         const index = Number(element.v);
         if (!isNaN(index) && sheet.shared_strings) {
@@ -158,7 +160,7 @@ export class Importer {
     }
     else {
       if (typeof element.f !== 'undefined') {
-        type = ValueType.formula;
+        type = 'formula'; // ValueType.formula;
 
         const formula = (typeof element.f === 'string' ? element.f : element.f.t$) || '';
 
@@ -219,11 +221,11 @@ export class Importer {
         if (typeof element.v !== 'undefined') {
           const num = Number(element.v.toString());
           if (!isNaN(num)) {
-            calculated_type = ValueType.number;
+            calculated_type = 'number'; // ValueType.number;
             calculated_value = num;
           }
           else {
-            calculated_type = ValueType.string;
+            calculated_type = 'string'; // ValueType.string;
             calculated_value = element.v.toString();
           }
         }
@@ -232,11 +234,11 @@ export class Importer {
       else if (typeof element.v !== 'undefined') {
         const num = Number(element.v.toString());
         if (!isNaN(num)) {
-          type = ValueType.number;
+          type = 'number'; // ValueType.number;
           value = num;
         }
         else {
-          type = ValueType.string;
+          type = 'string'; // ValueType.string;
           value = element.v.toString();
         }
       }
@@ -254,7 +256,7 @@ export class Importer {
         calculated_type = type;
         calculated_value = value;
         value = undefined;
-        type = ValueType.undefined;
+        type = 'undefined'; // ValueType.undefined;
       }
     }
 
@@ -833,11 +835,16 @@ export class Importer {
 
           if (is_address(translated)) {
 
-            const result = {
+            const result: {
+              row: number;
+              column: number;
+              value: string;
+              type: SerializedValueType;
+            } = {
               row: translated.row - 1, 
               column: translated.col - 1,
               value: constructed_function, 
-              type: ValueType.formula,
+              type: 'formula', // ValueType.formula,
             };
 
             let matched = false;
@@ -845,7 +852,7 @@ export class Importer {
             for (const element of data) {
               if (element.row === result.row && element.column === result.column) {
                 matched = true;
-                element.type = ValueType.formula;
+                element.type = 'formula'; // ValueType.formula;
                 element.value = constructed_function;
                 break;
               }

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

@@ -30,7 +30,6 @@ export interface SerializedMacroFunction {
   name: string;
   function_def: string;
   argument_names?: string[];
-  // argument_default_values?: any[]; // <- new
   description?: string;
 }
 

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

@@ -805,7 +805,9 @@ export class Grid extends GridBase {
    * be wiped from the model.
    */
   public RemoveAnnotationNodes(): void {
-    this.layout.RemoveAnnotationNodes();
+    if (!this.headless) {
+      this.layout.RemoveAnnotationNodes();
+    }
   }
 
   /**

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

@@ -44,47 +44,83 @@ export interface ScrollOffset {
 
 export interface SerializedSheet {
 
-  // version: string;
-  // data: any; // FIXME
+  /** cell data */
   data: SerializedCellData;
 
+  /** top-level sheet style, if any */
   sheet_style: Style.Properties;
+
+  /** row count */
   rows: number;
+
+  /** column count */
   columns: number;
+
+  /**
+   * cell styles is for empty cells that have styling
+   */
   cell_styles: Array<{row: number; column: number; ref: number, rows?: number}>;
 
-  /** @deprecated */
+  /** 
+   * @deprecated use `styles` instead
+   */
   cell_style_refs?: Style.Properties[]; // old 
-  styles?: Style.Properties[];          // new
 
+  /** 
+   * new implementation 
+   */
+  styles?: Style.Properties[];
+
+  /**
+   * per-row styles
+   */
   row_style: Record<number, Style.Properties|number>;
+
+  /**
+   * per-column styles
+   */
   column_style: Record<number, Style.Properties|number>;
 
   /** 
-   * @deprecated - no one uses this anymore and it's weird 
+   * @deprecated no one uses this anymore and it's weird 
    */
   row_pattern?: Style.Properties[];
 
+  /** default for new rows */
   default_row_height?: number;
+
+  /** default for new columns */
   default_column_width?: number;
 
+  /** list of row heights. we use a Record instead of an array because it's sparse */
   row_height?: Record<number, number>;
+
+  /** list of column widths. we use a Record instead of an array because it's sparse */
   column_width?: Record<number, number>;
-  named_ranges?: Record<string, IArea>;
 
-  // row_height?: {[index: number]: number};
-  // column_width?: {[index: number]: number};
-  // named_ranges?: {[index: string]: IArea};
+  /** 
+   * @deprecated these were moved to the containing document
+   */
+  named_ranges?: Record<string, IArea>;
 
   freeze?: FreezePane;
 
+  /** sheet ID, for serializing references */
   id?: number;
+
+  /** sheet name */
   name?: string;
 
+  /** current active selection */
   selection: GridSelection;
+
+  /**  */
   annotations?: Partial<AnnotationData>[]; // Partial<Annotation>[];
+
+  /** current scroll position */
   scroll?: ScrollOffset;
 
+  /** visible flag. we only support visible/hidden */
   visible?: boolean;
 
   /** testing */