@trebco/treb 29.4.1 → 29.5.1

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v29.4. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v29.5. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -1042,14 +1042,22 @@ export interface GetRangeOptions {
     formula?: boolean;
 
     /**
-     * optional style for returned values (replaces old flags).
+     * by default, GetRange returns cell values. the optional type field
+     * can be used to returns data in different formats.
      *
      * @remarks
      *
      * `formatted` returns formatted values, applying number formatting and
-     * returning strings. `formula` returns cell formulas instead of values.
+     * returning strings.
+     *
+     * `A1` returns cell formulas instead of values, in A1 format.
+     *
+     * `R1C1` returns cell formauls in R1C1 format.
+     *
+     * `formula` is an alias for 'A1', for backwards compatibility.
+     *
      */
-    type?: 'formatted' | 'formula';
+    type?: 'formatted' | 'A1' | 'R1C1' | 'formula';
 }
 
 /**
@@ -1083,24 +1091,6 @@ export interface FreezePane {
     rows: number;
     columns: number;
 }
-export declare const StandardGradientsList: {
-    readonly 'red-green': {
-        readonly color_space: "RGB";
-        readonly stops: GradientStop[];
-    };
-    readonly 'red-yellow-green': {
-        readonly color_space: "RGB";
-        readonly stops: GradientStop[];
-    };
-    readonly 'green-red': {
-        readonly color_space: "RGB";
-        readonly stops: GradientStop[];
-    };
-    readonly 'green-yellow-red': {
-        readonly color_space: "RGB";
-        readonly stops: GradientStop[];
-    };
-};
 
 /**
  * options for serializing data
@@ -1244,6 +1234,7 @@ export type HorizontalAlign = '' | 'left' | 'center' | 'right';
 
 /** vertical align constants for cell style */
 export type VerticalAlign = '' | 'top' | 'bottom' | 'middle';
+export type ThemeColorType = 'Background' | 'Text' | 'Background2' | 'Text2' | 'Accent' | 'Accent2' | 'Accent3' | 'Accent4' | 'Accent5' | 'Accent6';
 
 /**
  * font size for cell style. we generally prefer relative sizes
@@ -1254,20 +1245,20 @@ export interface FontSize {
     unit: 'pt' | 'px' | 'em' | '%';
     value: number;
 }
-
-/**
- * color for cell style. color is used for foreground, background and
- * borders in the cell style. can be either a theme color (theme index
- * plus tint), or CSS text.
- */
-export interface Color {
-    theme?: number;
+export interface HTMLColor {
+    text: string;
+}
+export interface ThemeColor {
+    theme: number | ThemeColorType;
     tint?: number;
-    text?: string;
-
-    /** @deprecated */
-    none?: boolean;
 }
+export interface NullColor {
+}
+export type Color = ThemeColor | HTMLColor | NullColor;
+export declare const ThemeColorIndex: (color: ThemeColor) => number;
+export declare const IsHTMLColor: (color?: Color) => color is HTMLColor;
+export declare const IsThemeColor: (color?: Color) => color is ThemeColor;
+export declare const IsDefinedColor: (color?: Color) => color is ThemeColor | HTMLColor;
 export type CellValue = undefined | string | number | boolean | Complex | DimensionedQuantity;
 
 /**
@@ -1501,7 +1492,7 @@ export declare type LoadSource = "drag-and-drop" | "local-file" | "network-file"
  * EmbeddedSheetEvent is a discriminated union. Switch on the `type` field
  * of the event.
  */
-export type EmbeddedSheetEvent = DocumentChangeEvent | DocumentResetEvent | DocumentLoadEvent | ViewChangeEvent | DataChangeEvent | FocusViewEvent | SelectionEvent | ResizeEvent;
+export type EmbeddedSheetEvent = DocumentChangeEvent | DocumentResetEvent | DocumentLoadEvent | ThemeChangeEvent | ViewChangeEvent | DataChangeEvent | FocusViewEvent | SelectionEvent | ResizeEvent;
 
 /**
  * options when inserting a table into a sheet
@@ -1540,6 +1531,14 @@ export interface ViewChangeEvent {
     type: 'view-change';
 }
 
+/**
+ * this event is sent when the theme is updated. it's intended for any
+ * subscribers to update corresponding colors or fonts.
+ */
+export interface ThemeChangeEvent {
+    type: 'theme-change';
+}
+
 /**
  * This event is sent when a document is loaded, and also on undo. The
  * source field can help determine if it was triggered by an undo operation.

package/package.json

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

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

@@ -1,7 +1,7 @@
 
 import { Measurement } from 'treb-utils';
 import { type Color } from './style';
-import { type Theme, ThemeColor2 } from './theme';
+import { type Theme, ResolveThemeColor } from './theme';
 import { ColorFunctions } from './color';
 
 export interface GradientStop {
@@ -23,7 +23,7 @@ export class Gradient {
         throw new Error('invalid stop value');
       }
 
-      const rgb = Measurement.MeasureColor(ThemeColor2(theme, stop.color));
+      const rgb = Measurement.MeasureColor(ResolveThemeColor(theme, stop.color));
 
       let resolved: number[] = [];
 

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

@@ -27,6 +27,44 @@ export type HorizontalAlign = '' | 'left' | 'center' | 'right';
 /** vertical align constants for cell style */
 export type VerticalAlign = '' | 'top' | 'bottom' | 'middle';
 
+export type ThemeColorType =   
+  'Background'|
+  'Text'|
+  'Background2'|
+  'Text2'|
+  'Accent'|
+  'Accent2'|
+  'Accent3'|
+  'Accent4'|
+  'Accent5'|
+  'Accent6';
+
+const ThemeColorMap: Record<string, number> = {
+  'Background': 0,
+  'Text': 1,
+  'Background2': 2,
+  'Text2': 3,
+  'Accent': 4,
+  'Accent2': 5,
+  'Accent3': 6,
+  'Accent4': 7,
+  'Accent5': 8,
+  'Accent6': 9,
+};
+
+/*
+for (const [index, entry] of ThemeColorList.entries()) {
+  ThemeColorMap[entry] = index;
+}
+*/
+
+export const ThemeColorIndex = (color: ThemeColor) => {
+  if (typeof color.theme === 'number') {
+    return color.theme;
+  }
+  return ThemeColorMap[color.theme] || 0;
+};
+
 /** 
  * font size for cell style. we generally prefer relative sizes
  * (percent or em) because they are relative to the default theme
@@ -37,26 +75,67 @@ export interface FontSize {
   value: number;
 }
 
-/** 
+/* * 
  * color for cell style. color is used for foreground, background and 
  * borders in the cell style. can be either a theme color (theme index 
  * plus tint), or CSS text.
  * 
  * @privateRemarks
  * FIXME: this should be a union type. we do a lot of if switching anyway.
- */
+ * /
 export interface Color {
 
   theme?: number;
   tint?: number;
   text?: string;
 
-  /** @internal */
+  / ** @internal * /
   offset?: Color;
 
-  /** @deprecated */
+  / ** @deprecated * /
   none?: boolean;
 }
+*/
+
+export interface HTMLColor {
+  text: string;
+
+  /** @internal */
+  offset?: Color;
+
+}
+
+export interface ThemeColor {
+  theme: number|ThemeColorType;
+  tint?: number;
+
+  /** @internal */
+  offset?: Color;
+
+}
+
+export interface NullColor {
+
+  /** @internal */
+  offset?: Color;
+
+}
+
+export type Color = ThemeColor|HTMLColor|NullColor;
+
+export const IsHTMLColor = (color?: Color): color is HTMLColor => {
+  return !!color && (typeof (color as HTMLColor).text === 'string');
+};
+
+export const IsThemeColor = (color?: Color): color is ThemeColor => {
+  return !!color && (typeof (color as ThemeColor).theme !== 'undefined');
+};
+
+export const IsDefinedColor = (color?: Color): color is (ThemeColor|HTMLColor) => {
+  return !!color && (
+    (typeof (color as HTMLColor).text === 'string') ||
+    (typeof (color as ThemeColor).theme !== 'undefined'));
+}
 
 /** @internal */
 export interface CompositeBorderEdge {
@@ -258,15 +337,19 @@ export const Style = {
     return JSON.stringify(style) === empty_json;
   },
 
-  /** 
+  /* * 
    * this looks like a type guard, we should switch to a union
    * type and then add real type guards
    * 
    * @internal 
-   */
+   * /
   ValidColor: (color?: Color): boolean => {
     return !!(color && (!color.none) && (color.text || color.theme || color.theme === 0));
   },
+  */
+
+
+
 
   /** @internal */
    ParseFontSize: (text = '', default_unit = 'em'): CellStyle => {

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

@@ -19,7 +19,7 @@
  * 
  */
 
-import type { Color, CellStyle } from './style';
+import { type Color, type CellStyle, IsHTMLColor, IsThemeColor, ThemeColorIndex, type ThemeColor } from './style';
 import { ColorFunctions } from './color';
 import { DOMContext } from './dom-utilities';
 
@@ -161,14 +161,20 @@ export const DefaultTheme: Theme = {
   offset_dark: '#000',
 };
 
-/**
+/* *
  * now just a wrapper, we should remove
+ * 
+ * the only difference between this and the other function (ThemeColor2)
+ * is that this has a default for "defaultindex" => 0; calls can just 
+ * call the second method with the extra argument.
+ * 
  * @deprecated
  * @internal
- */
+ * /
 export const ThemeColor = (theme: Theme, color?: Color): string => {
   return ThemeColor2(theme, color, 0);
 };
+*/
 
 /**
  * we cache values in the theme object so that we can dump it when we 
@@ -180,7 +186,10 @@ export const ThemeColor = (theme: Theme, color?: Color): string => {
  * 
  * because this is ephemeral it won't impact export.
  */
-const TintedColor = (theme: Theme, index: number, tint: number) => {
+const TintedColor = (theme: Theme, source: ThemeColor) => {
+
+  const index = ThemeColorIndex(source);
+  let tint = (source.tint || 0);
 
   if (theme.mode === 'dark') {
     tint = -tint; // invert;
@@ -223,9 +232,9 @@ const TintedColor = (theme: Theme, index: number, tint: number) => {
  * 
  * @internal
  */
-export const ThemeColor2 = (theme: Theme, color?: Color, default_index?: number): string => {
+export const ResolveThemeColor = (theme: Theme, color?: Color, default_index?: number): string => {
 
-  if (color?.offset) {
+  if (color && color.offset) {
 
     // don't do this
     if (color.offset.offset) {
@@ -233,7 +242,7 @@ export const ThemeColor2 = (theme: Theme, color?: Color, default_index?: number)
       return ''; 
     }
 
-    const resolved = ThemeColor2(theme, color.offset);
+    const resolved = ResolveThemeColor(theme, color.offset);
 
     // check cache
     if (theme.offset_cache && theme.offset_cache[resolved]) {
@@ -271,17 +280,17 @@ export const ThemeColor2 = (theme: Theme, color?: Color, default_index?: number)
 
   // explicit color, or none
 
-  if (color?.text) {
+  if (IsHTMLColor(color)) {
     return color.text === 'none' ? '' : color.text;
   }
 
   // theme color. we need a way to cache these lookups, especially for tinting
 
-  if (color?.theme || color?.theme === 0) {
+  if (IsThemeColor(color)) {
     if (color.tint) {
-      return TintedColor(theme, color.theme, color.tint);
+      return TintedColor(theme, color);
     }
-    return theme.theme_colors ? theme.theme_colors[color.theme] : '';
+    return theme.theme_colors ? theme.theme_colors[ThemeColorIndex(color)] : '';
   }
 
   // default from argument
@@ -427,11 +436,11 @@ const DeriveColorScheme = (theme: Theme, context: CanvasRenderingContext2D): 'li
 
   // because these are rendered to a canvas, we know that A is 255
 
-  context.fillStyle = foreground_color?.text || '';
+  context.fillStyle = IsHTMLColor(foreground_color) ? foreground_color.text : '';
   context.fillRect(0, 0, 3, 3);
   const fg = ColorFunctions.RGBToHSL(...(Array.from(context.getImageData(1, 1, 1, 1).data) as [number, number, number]));
 
-  context.fillStyle = background_color?.text || '';
+  context.fillStyle = IsHTMLColor(background_color) ? background_color.text : '';
   context.fillRect(0, 0, 3, 3);
   const bg = ColorFunctions.RGBToHSL(...(Array.from(context.getImageData(1, 1, 1, 1).data) as [number, number, number]));
 
@@ -558,8 +567,8 @@ export const LoadThemeProperties = (container: HTMLElement): Theme => {
   const compare = css.color;
 
   theme.theme_colors = [
-    theme.grid_cell.fill?.text || 'rgb(255, 255, 255)',
-    theme.grid_cell.text?.text || 'rgb(51, 51, 51)',
+    IsHTMLColor(theme.grid_cell.fill) ? theme.grid_cell.fill.text : 'rgb(255, 255, 255)',
+    IsHTMLColor(theme.grid_cell.text) ? theme.grid_cell.text.text : 'rgb(51, 51, 51)',
   ];
 
   for (let i = 1; i < 32; i++) {

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

@@ -30,7 +30,7 @@
  */
 
 
-import type { Cell, CellStyle } from 'treb-base-types';
+import { IsHTMLColor, type Cell, type CellStyle } from 'treb-base-types';
 
 export interface SparklineRenderOptions {
   context: CanvasRenderingContext2D;
@@ -120,7 +120,7 @@ export class Sparkline {
     // theme default _should_ always be passed in, so we should (theoretically)
     // never need our default.
    
-    const text_color = style.text?.text || this.default_color;
+    const text_color = IsHTMLColor(style.text) ? style.text.text : this.default_color;
     const colors: string[] = [ text_color, text_color ];
 
     if (Array.isArray(cell.calculated)) {

package/treb-data-model/src/conditional_format.ts

@@ -67,7 +67,14 @@ export interface ConditionalFormatGradientOptions {
 
 }
 
-
+/**
+ * @internal
+ * 
+ * @privateRemarks
+ * 
+ * this is marked internal temporarily while I figure out why our API
+ * generator is not exporting the gradient stop type
+ */
 export const StandardGradientsList = {
   'red-green': {
     color_space: 'RGB',

package/treb-data-model/src/sheet.ts

@@ -26,7 +26,7 @@ import { ValueType, Cells, Style,
   type PropertyKeys,
   type Color,
   Area, IsFlatDataArray, 
-  IsNestedRowArray, IsCellAddress, DOMContext
+  IsNestedRowArray, IsCellAddress, DOMContext, IsHTMLColor, IsThemeColor
 } from 'treb-base-types';
 import { NumberFormatCache } from 'treb-format';
 import { Measurement, ValidateURI } from 'treb-utils';
@@ -2311,12 +2311,11 @@ export class Sheet {
         number_format_map[style.number_format] = 1;
       }
 
-      if (style.text?.text && style.text.text !== 'none') {
-        // const color = Measurement.MeasureColorARGB(style.text_color);
+      if (IsHTMLColor(style.text)) {
         color_map[style.text.text] = 1;
       }
 
-      if (style.fill?.text) {
+      if (IsHTMLColor(style.fill)) {
         color_map[style.fill.text] = 1;
       }
 
@@ -2324,16 +2323,16 @@ export class Sheet {
       //  color_map[style.background] = 1;
       //}
 
-      if (style.border_top_fill?.text) {
+      if (IsHTMLColor(style.border_top_fill)) {
         color_map[style.border_top_fill.text] = 1;
       }
-      if (style.border_left_fill?.text) {
+      if (IsHTMLColor(style.border_left_fill)) {
         color_map[style.border_left_fill.text] = 1;
       }
-      if (style.border_right_fill?.text) {
+      if (IsHTMLColor(style.border_right_fill)) {
         color_map[style.border_right_fill.text] = 1;
       }
-      if (style.border_bottom_fill?.text) {
+      if (IsHTMLColor(style.border_bottom_fill)) {
         color_map[style.border_bottom_fill.text] = 1;
       }
 
@@ -2576,13 +2575,15 @@ export class Sheet {
         ...default_color,
         ...color,
       };
-      if (result.text) {
+
+      if (IsHTMLColor(result)) {
         result.text = Measurement.MeasureColorARGB(result.text);
         return result;
       }
-      else if (typeof result.theme === 'number') {
+      else if (IsThemeColor(result)) {
         return result;
       }
+
       return undefined;
     };
 
@@ -2617,7 +2618,7 @@ export class Sheet {
         fill = translate_border_fill(style.border_bottom_fill, Style.DefaultProperties.border_bottom_fill);
         if (fill !== undefined) { style.border_bottom_fill = fill; }
 
-        if (style.fill?.text) {
+        if (IsHTMLColor(style.fill)) {
           style.fill.text = Measurement.MeasureColorARGB(style.fill.text);
         }
 
@@ -2625,10 +2626,8 @@ export class Sheet {
         //  style.background = Measurement.MeasureColorARGB(style.background);
         //}
 
-        if (style.text) {
-          if (style.text.text && style.text.text !== 'none') {
-            style.text.text = Measurement.MeasureColorARGB(style.text.text);
-          }
+        if (IsHTMLColor(style.text)) {
+          style.text.text = Measurement.MeasureColorARGB(style.text.text);
         }
 
       }

package/treb-embed/src/custom-element/spreadsheet-constructor.ts

@@ -7,7 +7,7 @@ import html from '../../markup/layout.html';
 import toolbar_html from '../../markup/toolbar.html';
 
 import { NumberFormatCache } from 'treb-format';
-import { ColorFunctions, type Color } from 'treb-base-types';
+import { ColorFunctions, type Color, IsThemeColor } from 'treb-base-types';
 import { Measurement } from 'treb-utils';
 import type { ToolbarMessage } from '../toolbar-message';
 
@@ -729,8 +729,7 @@ export class SpreadsheetConstructor<USER_DATA_TYPE = unknown> {
             const entry = sheet.document_styles.theme_colors[j][i];
             const style = `background: ${entry.resolved};`;
             let title = themes[j] || themes[4];
-            if (entry.color.tint) {
-              // title += ` (${Math.abs(entry.color.tint) * 100}% ${ entry.color.tint > 0 ? 'lighter' : 'darker'})`;
+            if (IsThemeColor(entry.color) && entry.color.tint) {
               title += ` (${(entry.color.tint > 0 ? '+' : '') + (entry.color.tint) * 100}%)`;
             }
             else {
@@ -1372,6 +1371,11 @@ export class SpreadsheetConstructor<USER_DATA_TYPE = unknown> {
             this.UpdateRevertState(sheet);
             break;
 
+          case 'theme-change':
+            this.UpdateDocumentStyles(sheet, format_menu);
+            this.UpdateSelectionStyle(sheet, toolbar, comment_box);
+            break;
+
           case 'selection':
             this.UpdateSelectionStyle(sheet, toolbar, comment_box);
             break;

package/treb-embed/src/embedded-spreadsheet.ts

@@ -73,7 +73,7 @@ import type {
 
 import {
   IsArea, ThemeColorTable, ComplexToString, Rectangle, IsComplex, type CellStyle,
-  Localization, Style, type Color, ThemeColor2, IsCellAddress, Area, IsFlatData, IsFlatDataArray, Gradient, DOMContext, 
+  Localization, Style, type Color, ResolveThemeColor, IsCellAddress, Area, IsFlatData, IsFlatDataArray, Gradient, DOMContext, 
 } from 'treb-base-types';
 
 import { EventSource, ValidateURI } from 'treb-utils';
@@ -194,14 +194,22 @@ export interface LoadDocumentOptions {
   formula?: boolean;
 
   /**
-   * optional style for returned values (replaces old flags).
+   * by default, GetRange returns cell values. the optional type field 
+   * can be used to returns data in different formats.
    * 
    * @remarks
    * 
    * `formatted` returns formatted values, applying number formatting and
-   * returning strings. `formula` returns cell formulas instead of values.
+   * returning strings.
+   * 
+   * `A1` returns cell formulas instead of values, in A1 format.
+   * 
+   * `R1C1` returns cell formauls in R1C1 format.
+   * 
+   * `formula` is an alias for 'A1', for backwards compatibility.
+   * 
    */
-  type?: 'formatted'|'formula';
+  type?: 'formatted'|'A1'|'R1C1'|'formula';
 
 }
 
@@ -2115,6 +2123,8 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     this.ApplyConditionalFormats(this.grid.active_sheet, false);
     this.grid.Update(true);
 
+    this.Publish({ type: 'theme-change' });
+
   }
 
   /**
@@ -2588,9 +2598,7 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
    * @public
    */
   public SetColumnWidth(column?: number | number[], width?: number): void {
-
-    // API v1 OK
-
+   
     this.grid.SetColumnWidth(column, width);
   }
 
@@ -4301,16 +4309,24 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
 
     // handle the old flags and the precedence rule. type takes precedence.
 
-    if (!options.type) {
+    let type = options.type;
+
+    if (!type) {
       if (options.formatted) {
-        options.type = 'formatted';
+        type = 'formatted';
       }
       if (options.formula) {
-        options.type = 'formula';
+        type = 'A1';
       }
     }
 
-    return this.grid.GetRange(this.model.ResolveAddress(range, this.grid.active_sheet), options.type);
+    // alias
+    
+    if (type === 'formula') {
+      type = 'A1';
+    }
+
+    return this.grid.GetRange(this.model.ResolveAddress(range, this.grid.active_sheet), type);
 
   }
 
@@ -5331,7 +5347,7 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
             const update_textbox = () => {
 
               if (style.fill) {
-                const color = ThemeColor2(this.grid.theme, style.fill);
+                const color = ResolveThemeColor(this.grid.theme, style.fill);
                 container.style.background = color;
               }
 
@@ -5597,7 +5613,7 @@ export class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     for (let i = 0; i < 10; i++) {
       this.document_styles.theme_colors.push(tints.map(tint => {
         const color: Color = { theme: i, tint };
-        const resolved = ThemeColor2(this.grid.theme, color);
+        const resolved = ResolveThemeColor(this.grid.theme, color);
         return { color, resolved };
       }));
     }

package/treb-embed/src/types.ts

@@ -144,6 +144,14 @@ export interface ViewChangeEvent {
   type: 'view-change';
 }
 
+/**
+ * this event is sent when the theme is updated. it's intended for any 
+ * subscribers to update corresponding colors or fonts.
+ */
+export interface ThemeChangeEvent {
+  type: 'theme-change';
+}
+
 /**
  * This event is sent when a document is loaded, and also on undo. The 
  * source field can help determine if it was triggered by an undo operation.
@@ -206,6 +214,7 @@ export type EmbeddedSheetEvent
   = DocumentChangeEvent
   | DocumentResetEvent
   | DocumentLoadEvent
+  | ThemeChangeEvent
   | ViewChangeEvent
   | DataChangeEvent
   | FocusViewEvent