@trebco/treb 23.6.5 → 25.0.0-rc1

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

@@ -0,0 +1,124 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+/**
+ * utility functions, primarily for adjusting lightness. since we generally
+ * traffic in RGB (or symbolic colors) that requires translating to/from HSL.
+ */
+class ColorFunctions {
+
+  /** darken rgb color by amount (%), optionally relative */
+  public Darken(r: number, g: number, b: number, amount: number, relative = false) {
+
+    // eslint-disable-next-line prefer-const
+    let { h, s, l } = this.RGBToHSL(r, g, b);
+    if (relative) l -= l * amount / 100;
+    else l -= amount / 100;
+    l = Math.max(0, Math.min(1, l));
+    return this.HSLToRGB(h, s, l);
+  }
+
+  /** lighten rgb color by amount (%), optionally relative */
+  public Lighten(r: number, g: number, b: number, amount: number, relative = false) {
+
+    // eslint-disable-next-line prefer-const
+    let { h, s, l } = this.RGBToHSL(r, g, b);
+    if (relative) l += l * amount / 100;
+    else l += amount / 100;
+    l = Math.max(0, Math.min(1, l));
+    return this.HSLToRGB(h, s, l);
+  }
+
+  public RGBToHSL(r: number, g: number, b: number) {
+
+    r /= 255;
+    g /= 255;
+    b /= 255;
+
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+
+    let h = 0;
+    let s = 0;
+
+    const l = (max + min) / 2;
+
+    if (max === min) {
+      h = s = 0;
+    }
+    else {
+      const d = max - min;
+      s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+      switch (max) {
+        case r:
+          h = (g - b) / d + (g < b ? 6 : 0);
+          break;
+        case g:
+          h = (b - r) / d + 2;
+          break;
+        case b:
+          h = (r - g) / d + 4;
+          break;
+      }
+      h /= 6;
+    }
+
+    return { h: h * 360, s, l };
+  }
+
+  public HSLToRGB(h: number, s: number, l: number) {
+
+    let r: number;
+    let g: number;
+    let b: number;
+
+    if (s === 0) {
+      r = g = b = l;
+    }
+    else {
+      h = h / 360;
+      const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+      const p = 2 * l - q;
+      r = this.HueToRGB(p, q, h + 1 / 3);
+      g = this.HueToRGB(p, q, h);
+      b = this.HueToRGB(p, q, h - 1 / 3);
+    }
+
+    return { 
+      r: Math.round(r * 255), 
+      g: Math.round(g * 255), 
+      b: Math.round(b * 255), 
+    };
+  }
+
+  private HueToRGB(p: number, q: number, t: number) {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  }
+
+}
+
+/** @internal */
+export const Color = new ColorFunctions();

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

@@ -0,0 +1,71 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { Style } from './style';
+import type { ValueType } from './value-type';
+import type { IArea } from './area';
+import type { AnnotationLayout } from './layout';
+import type { DataValidation } from './cell';
+import type { Table } from './table';
+
+export interface CellParseResult {
+  row: number,
+  column: number,
+  type: ValueType,
+  value: number|string|undefined|boolean,
+  calculated?: number|string|undefined|boolean,
+  calculated_type?: ValueType,
+  style_ref?: number,
+  hyperlink?: string,
+  validation?: DataValidation,
+  merge_area?: IArea,
+  area?: IArea,
+  table?: Table,
+}
+
+export interface AnchoredAnnotation {
+  layout: AnnotationLayout;
+  type?: string;
+  formula?: string;
+}
+
+/**
+ * this is moved from export to avoid a circular reference
+ */
+export interface ImportedSheetData {
+  name: string|undefined;
+  cells: CellParseResult[];
+  default_column_width: number;
+  column_widths: number[];
+  row_heights: number[];
+  styles: Style.Properties[];
+
+  // optional, for backcompat
+  sheet_style?: number;
+  column_styles?: number[];
+
+  // new
+  annotations?: AnchoredAnnotation[];
+
+  hidden?: boolean;
+
+}
+

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

@@ -0,0 +1,29 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+/**
+ * this is a special index for inclusion in the standalone format lib
+ */
+
+export * from './localization';
+export * from './text_part';
+export * from './value-type';
+

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

@@ -0,0 +1,42 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+export * from './area';
+export * from './cell';
+export * from './cells';
+export * from './localization';
+export * from './basic_types';
+export * from './rectangle';
+export * from './style';
+export * from './text_part';
+export * from './import';
+export * from './union';
+export * from './value-type';
+export * from './theme';
+export * from './color';
+export * from './layout';
+export * from './render_text';
+export * from './api_types';
+export * from './table';
+
+// import * as Style from './style';
+// export { Style };
+

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

@@ -0,0 +1,47 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { ICellAddress } from './area';
+
+/**
+ * offset from corner, as % of cell
+ */
+export interface AddressOffset {
+  x: number, 
+  y: number,
+}
+
+/** 
+ * represents one corner of a layout rectangle
+ */
+export interface Corner {
+  address: ICellAddress;
+  offset: AddressOffset;
+}  
+
+/**
+ * represents the layout of an annotation, reference to the sheet
+ */
+export interface AnnotationLayout {
+  tl: Corner;
+  br: Corner;
+}
+

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

@@ -0,0 +1,187 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+/**
+ * the point of localization is to have a central, single source of truth
+ * for the current locale. this can come from the browser, via a GET
+ * parameter (mostly for testing), or explicitly from a method call.
+ *
+ * based on locale we report settings for decimal separator, digit grouping,
+ * and argument separator.
+ */
+export class Localization {
+
+  public static locale = 'en-us'; // default, for node
+
+  public static decimal_separator: ('.' | ',') = '.';
+  public static argument_separator: ','|';' = ',';
+  public static grouping_separator: ','|' ' = ',';
+
+  public static date_components = {
+    short_days: [
+      'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat',
+    ],
+
+    long_days: [
+      'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday',
+    ],
+
+    short_months: [
+      'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+    ],
+
+    long_months: [
+      'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August',
+      'September', 'October', 'November', 'December',
+    ],
+  };
+
+  /**
+   * update the locale. this will be called on module load (should
+   * be just once), but can be called subsequently to update.
+   *
+   * priority:
+   * (1) function argument
+   * (2) get parameter
+   * (3) navigator.languages[0]
+   * (4) navigator.language
+   *
+   * regarding languages[0] vs language, see
+   * https://stackoverflow.com/a/33204290
+   *
+   * @param locale explicitly set locale
+   */
+  public static UpdateLocale(locale?: string): void {
+
+    if (locale) {
+      this.locale = locale; // 1
+    }
+    else if (typeof self !== 'undefined') {
+
+      // const location = ((typeof self === 'undefined' || typeof self.document === 'undefined') ?
+      //  undefined : self.document.location);
+
+      const location = self?.document?.location;
+
+      if (location && location.search &&
+          /locale=([^?&]+?)(?:\?|$|&)/.test(location.search)) {
+        const match = location.search.match(/locale=(.*?)(?:\?|$|&)/);
+        if (match) this.locale = match[1];
+        console.info('override locale', this.locale);
+      }
+      else if (typeof navigator !== 'undefined') {
+        if (navigator.languages && navigator.languages[0]) {
+          this.locale = navigator.languages[0];
+        }
+        else {
+          this.locale = navigator.language;
+        }
+      }
+
+    }
+
+    const decimal_separator = new Intl.NumberFormat(this.locale,
+      {minimumFractionDigits: 1}).format(3.3).replace(/\d/g, '');
+
+    this.decimal_separator = (decimal_separator === ',') ? ',' : '.';
+
+    if (this.decimal_separator === ',') {
+      this.argument_separator = ';';
+
+      // FIXME: should be half-space (char?)
+      //
+      // the appropriate character (I think) is \u2009, "thin space", but
+      // it seems to be rendered as full-width space in monospace fonts --
+      // which makes sense -- and since we mostly use those it's probably 
+      // immaterial.
+      //
+      // it might be useful for fonts with variable-width characters but
+      // tabular numbers, in which case we would want to use it.
+      //
+      // FIXME: does format use this field, or does it have its own? (...)
+      
+      this.grouping_separator = ' '; 
+    }
+    else {
+      this.argument_separator = ',';
+      this.grouping_separator = ',';
+    }
+
+    // moved from number format lib
+
+
+      let date = new Date(2000, 0, 2, 12, 0, 0, 0); // Sun Jan 2
+      this.UpdateDateComponent(0, 0, date);
+
+      date = new Date(2000, 1, 7, 12, 0, 0, 0); // Mon Feb 7
+      this.UpdateDateComponent(1, 1, date);
+
+      date = new Date(2000, 2, 7, 12, 0, 0, 0); // Tue Mar 7
+      this.UpdateDateComponent(2, 2, date);
+
+      date = new Date(2000, 3, 5, 12, 0, 0, 0); // Wed Apr 5
+      this.UpdateDateComponent(3, 3, date);
+
+      date = new Date(2000, 4, 4, 12, 0, 0, 0); // Thur May 4
+      this.UpdateDateComponent(4, 4, date);
+
+      date = new Date(2000, 5, 2, 12, 0, 0, 0); // Fri Jun 2
+      this.UpdateDateComponent(5, 5, date);
+
+      date = new Date(2000, 6, 1, 12, 0, 0, 0); // Sat Jul 1
+      this.UpdateDateComponent(6, 6, date);
+
+      date = new Date(2000, 7, 1, 12, 0, 0, 0); // Aug
+      this.UpdateDateComponent(7, -1, date);
+
+      date = new Date(2000, 8, 1, 12, 0, 0, 0); // Sep
+      this.UpdateDateComponent(8, -1, date);
+
+      date = new Date(2000, 9, 1, 12, 0, 0, 0); // Oct
+      this.UpdateDateComponent(9, -1, date);
+
+      date = new Date(2000, 10, 1, 12, 0, 0, 0); // Nov
+      this.UpdateDateComponent(10, -1, date);
+
+      date = new Date(2000, 11, 1, 12, 0, 0, 0); // Dec
+      this.UpdateDateComponent(11, -1, date);
+
+      /*
+      console.info('LX', this.locale, this.date_components.short_days,
+        this.date_components.long_days, this.date_components.short_months,
+        this.date_components.long_months);
+      */
+    }
+
+    private static UpdateDateComponent(month_index: number, day_index: number, date: Date){
+      if (day_index >= 0) {
+        this.date_components.short_days[day_index] = date.toLocaleString(this.locale, {weekday: 'short'});
+        this.date_components.long_days[day_index] = date.toLocaleString(this.locale, {weekday: 'long'});
+      }
+      if (month_index >= 0) {
+        this.date_components.short_months[month_index] = date.toLocaleString(this.locale, {month: 'short'});
+        this.date_components.long_months[month_index] = date.toLocaleString(this.locale, {month: 'long'});
+      }
+    }
+
+}
+
+Localization.UpdateLocale(); // always call

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

@@ -0,0 +1,145 @@
+/*
+ * 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-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+/** structure represents rectangle coordinates */
+export interface IRectangle {
+  top: number;
+  left: number;
+  width: number;
+  height: number;  
+}
+
+export class Rectangle implements IRectangle {
+
+  public get right(): number { return this.left + this.width; }
+  public get bottom(): number { return this.top + this.height; }
+
+  /**
+   * create a rectangle from an object that looks 
+   * like a rectangle, probably a serialized object
+   */
+  public static Create(obj: Partial<Rectangle>): Rectangle {
+    return new Rectangle(
+      obj.left || 0,
+      obj.top || 0,
+      obj.width || 0,
+      obj.height || 0);
+  }
+
+  public static IsRectangle(obj: unknown): obj is IRectangle {
+    return (typeof obj === 'object') &&
+      (typeof (obj as any)?.left === 'number') && 
+      (typeof (obj as any)?.top === 'number') && 
+      (typeof (obj as any)?.width === 'number') && 
+      (typeof (obj as any)?.height === 'number');
+  }
+
+  constructor(  public left = 0,
+                public top = 0,
+                public width = 0,
+                public height = 0 ){}
+
+  /** returns a new rect shifted from this one by (x,y) */
+  public Shift(x = 0, y = 0): Rectangle {
+    return new Rectangle(this.left + x, this.top + y, this.width, this.height );
+  }
+
+  public Scale(scale_x = 1, scale_y = scale_x): Rectangle {
+    return new Rectangle(this.left * scale_x, this.top * scale_y, this.width * scale_x, this.height * scale_y);
+  }
+
+  /** returns a new rect expanded from this one by (x,y) */
+  public Expand(x = 0, y = 0): Rectangle {
+    return new Rectangle(this.left, this.top, this.width + x, this.height + y );
+  }
+
+  /** returns a new rectangle that combines this rectangle with the argument */
+  public Combine(rect: Rectangle): Rectangle {
+    return new Rectangle(
+      Math.min(this.left, rect.left),
+      Math.min(this.top, rect.top),
+      Math.max(this.right, rect.right) - Math.min(this.left, rect.left),
+      Math.max(this.bottom, rect.bottom) - Math.min(this.top, rect.top),
+    );
+  }
+
+  public CheckEdges(x: number, y: number, border = 16): number{
+
+    let edge = 0;
+
+    // tslint:disable-next-line:no-bitwise
+    if (x - this.left < border) edge |= 1;
+
+    // tslint:disable-next-line:no-bitwise
+    if (this.right - x < border) edge |= 2;
+
+    // tslint:disable-next-line:no-bitwise
+    if (y - this.top < border) edge |= 4;
+
+    // tslint:disable-next-line:no-bitwise
+    if (this.bottom - y < border) edge |= 8;
+
+    return edge;
+  }
+
+  /**
+   * check if rectangle contains the given coordinates, optionally with
+   * some added padding
+   */
+  public Contains(x: number, y: number, padding = 0): boolean {
+    return (x >= this.left - padding)
+      && (x <= (this.left + this.width + padding))
+      && (y >= this.top - padding)
+      && (y <= (this.top + this.height + padding));
+  }
+
+  /** convenience method for canvas */
+  public ContextFill(context: CanvasRenderingContext2D){
+    context.fillRect(this.left, this.top, this.width, this.height);
+  }
+
+  /** convenience method for canvas */
+  public ContextStroke(context: CanvasRenderingContext2D){
+    context.strokeRect(this.left, this.top, this.width, this.height);
+  }
+
+  /** clamp coordinate to rectangle */
+  public Clamp(x: number, y: number){
+    x = Math.min(Math.max(x, this.left), this.right);
+    y = Math.min(Math.max(y, this.top), this.bottom);
+    return { x, y };
+  }
+
+  /** convenience method for html element style */
+  public ApplyStyle(element: HTMLElement){
+    element.style.top = this.top + 'px';
+    element.style.left = this.left + 'px';
+    element.style.width = this.width + 'px';
+    element.style.height = this.height + 'px';
+  }
+
+  public toJSON(){
+    return {
+      top: this.top, left: this.left, width: this.width, height: this.height,
+    };
+  }
+
+}