@trebco/treb 25.0.0-rc1 → 25.0.0-rc2

package/build/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v25.0.0-rc1. Copyright 2018-2023 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v25.0.0-rc2. Copyright 2018-2023 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -41,15 +41,20 @@ export interface EmbeddedSpreadsheetOptions {
     /** allow drag-and-drop files */
     dnd?: boolean;
 
-    /** expandable grid */
+    /**
+     * expandable grid. if this option is false, the grid will always
+     * stay the same size -- if you keep pressing down arrow, it won't
+     * grow. defaults to true.
+     */
     expand?: boolean;
 
     /**
-     * key in localStorage for persisting document. it's possible
-     * to set this to boolean `true`, in which case we will generate
-     * a storage key based on the page URI.
+     * key in localStorage for persisting document.
+     *
+     * it's possible to set this to boolean `true`, in which case we will
+     * generate a storage key based on the page URI.
      *
-     * this can be convenient for quickly setting up a document, but don't
+     * that can be convenient for quickly setting up a document, but don't
      * use it if the page URI might change (the storage will get lost)
      * or if there are multiple spreadsheets on the same page (they will
      * overwrite each other).
@@ -77,10 +82,16 @@ export interface EmbeddedSpreadsheetOptions {
     /** export to xlsx, now optional */
     export?: boolean;
 
-    /** fill container */
-    auto_size?: boolean;
+    /**
+     * fetch network document. this is a replacement for the old
+     * (deprecated) option `network_document`.
+     */
+    document?: string;
 
-    /** fetch network document (URI) */
+    /**
+     * fetch network document (URI)
+     * @deprecated - use `document`
+     */
     network_document?: string;
 
     /** freeze rows */
@@ -120,29 +131,35 @@ export interface EmbeddedSpreadsheetOptions {
     prompt_save?: boolean;
 
     /**
-     * toolbar display option
+     * toolbar display option. true or false means include/don't include
+     * the toolbar (and the toolbar button). setting to "narrow" means
+     * include the toolbar, but use a narrow version (it compresses the
+     * align/justify groups).
+     *
+     * the toolbar usually starts hidden. if you set this option to "show",
+     * it will start visible. same for "show-narrow".
      */
     toolbar?: boolean | 'show' | 'narrow' | 'show-narrow';
 
-    /** file options in the toolbar */
+    /** include the file menu in the toolbar */
     file_menu?: boolean;
 
-    /** font size in the toolbar */
+    /** include the font scale control in the toolbar */
     font_scale?: boolean;
 
-    /** show insert/remove table button in toolbar */
+    /** include the insert/remove table button in the toolbar */
     table_button?: boolean;
 
-    /** show freeze button in toolbar */
+    /** include the freeze button in the toolbar */
     freeze_button?: boolean;
 
-    /** chart menu in the toolbar */
+    /** include the chart menu in the toolbar */
     chart_menu?: boolean;
 
-    /** recalculate button in the toolbar */
+    /** include a recalculate button in the toolbar */
     toolbar_recalculate_button?: boolean;
 
-    /** new option, better support for headless operations (default false) */
+    /** better support for headless operations (default false) */
     headless?: boolean;
 
     /** max size for image, in bytes */
@@ -151,16 +168,24 @@ export interface EmbeddedSpreadsheetOptions {
     /** initial scale */
     scale?: number;
 
-    /** show scale buttons */
+    /**
+     * show scale control (slider) under the spreadsheet.
+     */
     scale_control?: boolean;
 
-    /** show stats panel */
+    /**
+     * show the stats panel under the spreadsheet.
+     */
     stats?: boolean;
 
-    /** save/load scale. this can optionally have a string key to disambiguate */
+    /**
+     * save/load scale. this can optionally have a string key to disambiguate
+     */
     persist_scale?: boolean | string;
 
-    /** target window for hyperlinks (default _blank); set false to disable hyperlinks altogether */
+    /**
+     * target window for hyperlinks (default _blank); set false to disable hyperlinks altogether
+     */
     hyperlinks?: string | false;
 
     /**
@@ -185,10 +210,16 @@ export interface EmbeddedSpreadsheetOptions {
      * for rendering the imaginary number. this is intended to support
      * switching to a different character for rendering, or adding a leading
      * space/half-space/hair-space.
+     *
+     * this _does_not_ change how you enter imaginary numbers, you still have
+     * to use `i` (lower-case ascii i).
      */
     imaginary_value?: string;
 
-    /** support MD formatting for text */
+    /**
+     * support markdown formatting for text in cells and comments. at the
+     * moment we only support bold, italic, and strike text.
+     */
     markdown?: boolean;
 
     /**
@@ -197,15 +228,19 @@ export interface EmbeddedSpreadsheetOptions {
      */
     tint_theme_colors?: boolean;
 
-    /** show a spinner for long-running operations */
+    /**
+     * show a spinner for long-running operations
+     */
     spinner?: boolean;
 
-    /** collapsed: start sidebar closed */
+    /**
+     * start with sidebar closed. defaults to false.
+     */
     collapsed?: boolean;
 
     /**
-     * show the revert button. see the Revert method. this was renamed
-     * from `revert` to avoid any ambiguity.
+     * show the revert button in the sidebar. see the `Revert` method. this
+     * was renamed from `revert` to avoid any ambiguity.
      */
     revert_button?: boolean;
 }
@@ -526,9 +561,10 @@ export declare class EmbeddedSpreadsheet {
      *
      * @remarks
      *
-     * Call this method when the container is resized. It's not necessary
-     * if the resize is triggered by our resize handle, only if the container
-     * is resized externally.
+     * This method should be called when the container is resized, to
+     * trigger an update to layout. It should be called automatically
+     * by a resize observer set in the containing tag class, but you
+     * can call it manually if necessary.
      *
      * @public
      */

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@trebco/treb",
-  "version": "25.0.0-rc1",
+  "version": "25.0.0-rc2",
+  "license": "LGPL-3.0-or-later",
+  "homepage": "https://treb.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trebco/treb.git"
+  },
   "main": "build/treb-spreadsheet.mjs",
   "types": "build/treb.d.ts",
   "type": "module",

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

@@ -163,7 +163,7 @@ export class SpreadsheetConstructor {
    */
   public ParseOptionAttributes(): Partial<EmbeddedSpreadsheetOptions> {
 
-    const attribute_options: Record<string, string|boolean|number> = {};
+    const attribute_options: Record<string, string|boolean|number|undefined> = {};
 
     if (this.root) {
 
@@ -211,7 +211,8 @@ export class SpreadsheetConstructor {
             continue; 
 
           // special case
-          case 'document':
+          case 'src':
+            attribute_options.document = this.root.getAttribute('src') || undefined;
             continue;
 
         }

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

@@ -493,7 +493,14 @@ export class EmbeddedSpreadsheet {
       NumberFormat.imaginary_character = this.options.imaginary_value;
     }
 
-    const network_document = this.options.network_document;
+    if (this.options.network_document) {
+      console.warn('the option `network_document` is deprecated. please use `document` instead.');
+      if (!this.options.document) { 
+        this.options.document = this.options.network_document;
+      }
+    }
+
+    const network_document = this.options.document;
 
     // optionally data from storage, with fallback
 
@@ -504,18 +511,10 @@ export class EmbeddedSpreadsheet {
     // unload event, as parent will already have that set
 
     if (this.options.storage_key && !this.options.toll_initial_load && !options.model) {
-
       data = localStorage.getItem(this.options.storage_key) || undefined;
       if (data) {
         source = LoadSource.LOCAL_STORAGE;
       }
-
-      /*
-      if (!data && this.options.alternate_document) {
-        network_document = this.options.alternate_document;
-      }
-      */
-
     }
 
     // this one should not be done for a split view, but we should still
@@ -687,7 +686,7 @@ export class EmbeddedSpreadsheet {
       this.key_listener = this.HandleKeyDown.bind(this);
       container.addEventListener('keydown', this.key_listener);
 
-      const toll_initial_render = !!(data || this.options.network_document);
+      const toll_initial_render = !!(data || this.options.document);
 
       // const view = container.querySelector('.treb-view') as HTMLElement;
 
@@ -883,7 +882,7 @@ export class EmbeddedSpreadsheet {
 
     // optionally scroll grid on create (async -- why?)
 
-    if (this.options.scroll && !this.options.network_document) {
+    if (this.options.scroll && !this.options.document) {
       const address = this.options.scroll;
       requestAnimationFrame(() => {
         this.ScrollTo(address);
@@ -2246,8 +2245,6 @@ export class EmbeddedSpreadsheet {
   public async ExportBlob(): Promise<Blob> {
 
     if (!this.export_worker) {
-      // const worker_name = process.env.BUILD_ENTRY_EXPORT_WORKER || '';
-      // this.export_worker = await this.LoadWorker(worker_name);
       this.export_worker = await this.LoadWorker('export');
     }
 
@@ -2297,8 +2294,7 @@ export class EmbeddedSpreadsheet {
    */
   public Revert(): void {
 
-    const canonical = // this.options.alternate_document || 
-      this.options.network_document;
+    const canonical = this.options.document;
 
     if (canonical) {
 
@@ -2419,9 +2415,10 @@ export class EmbeddedSpreadsheet {
    * 
    * @remarks 
    * 
-   * Call this method when the container is resized. It's not necessary
-   * if the resize is triggered by our resize handle, only if the container
-   * is resized externally.
+   * This method should be called when the container is resized, to 
+   * trigger an update to layout. It should be called automatically 
+   * by a resize observer set in the containing tag class, but you 
+   * can call it manually if necessary.
    * 
    * @public
    */
@@ -3907,8 +3904,7 @@ export class EmbeddedSpreadsheet {
     }
 
     if (!this.export_worker) {
-      const worker_name = process.env.BUILD_ENTRY_EXPORT_WORKER || '';
-      this.export_worker = await this.LoadWorker(worker_name);
+      this.export_worker = await this.LoadWorker('export');
     }
 
     // this originally returned a Promise<Blob> but the actual

package/treb-embed/src/options.ts

@@ -50,15 +50,20 @@ export interface EmbeddedSpreadsheetOptions {
   /** allow drag-and-drop files */
   dnd?: boolean;
 
-  /** expandable grid */
+  /** 
+   * expandable grid. if this option is false, the grid will always
+   * stay the same size -- if you keep pressing down arrow, it won't
+   * grow. defaults to true.
+   */
   expand?: boolean;
 
   /** 
-   * key in localStorage for persisting document. it's possible
-   * to set this to boolean `true`, in which case we will generate
-   * a storage key based on the page URI. 
+   * key in localStorage for persisting document. 
+   * 
+   * it's possible to set this to boolean `true`, in which case we will 
+   * generate a storage key based on the page URI. 
    * 
-   * this can be convenient for quickly setting up a document, but don't 
+   * that can be convenient for quickly setting up a document, but don't 
    * use it if the page URI might change (the storage will get lost)
    * or if there are multiple spreadsheets on the same page (they will
    * overwrite each other).
@@ -86,30 +91,17 @@ export interface EmbeddedSpreadsheetOptions {
   /** export to xlsx, now optional */
   export?: boolean;
 
-  /** fill container */
-  auto_size?: boolean;
-
-  /* * 
-   * popout icon 
-   * removed as of version 25
+  /** 
+   * fetch network document. this is a replacement for the old
+   * (deprecated) option `network_document`.
    */
-  // popout?: boolean;
-
-  /* * the old "fork and edit" button */
-  // fork?: boolean;
+  document?: string;
 
-  /** fetch network document (URI) */
-  network_document?: string;
-
-  /* * 
-   * load this document if the storage document isn't found (fallback) 
-   * 
-   * @deprecated - this is superfluous, using network_document with 
-   * storage_key is sufficient for this pattern.
-   * 
-   * removed as of version 25
+  /** 
+   * fetch network document (URI) 
+   * @deprecated - use `document`
    */
-  // alternate_document?: string;
+  network_document?: string;
 
   /** freeze rows */
   freeze_rows?: number;
@@ -148,29 +140,35 @@ export interface EmbeddedSpreadsheetOptions {
   prompt_save?: boolean;
 
   /**
-   * toolbar display option
+   * toolbar display option. true or false means include/don't include
+   * the toolbar (and the toolbar button). setting to "narrow" means
+   * include the toolbar, but use a narrow version (it compresses the 
+   * align/justify groups).
+   * 
+   * the toolbar usually starts hidden. if you set this option to "show",
+   * it will start visible. same for "show-narrow".
    */
   toolbar?: boolean | 'show' | 'narrow' | 'show-narrow';
 
-  /** file options in the toolbar */
+  /** include the file menu in the toolbar */
   file_menu?: boolean;
 
-  /** font size in the toolbar */
+  /** include the font scale control in the toolbar */
   font_scale?: boolean;
 
-  /** show insert/remove table button in toolbar */
+  /** include the insert/remove table button in the toolbar */
   table_button?: boolean;
 
-  /** show freeze button in toolbar */
+  /** include the freeze button in the toolbar */
   freeze_button?: boolean;
 
-  /** chart menu in the toolbar */
+  /** include the chart menu in the toolbar */
   chart_menu?: boolean;
 
-  /** recalculate button in the toolbar */
+  /** include a recalculate button in the toolbar */
   toolbar_recalculate_button?: boolean;
 
-  /** new option, better support for headless operations (default false) */
+  /** better support for headless operations (default false) */
   headless?: boolean;
 
   /** max size for image, in bytes */
@@ -179,16 +177,24 @@ export interface EmbeddedSpreadsheetOptions {
   /** initial scale */
   scale?: number;
 
-  /** show scale buttons */
+  /** 
+   * show scale control (slider) under the spreadsheet. 
+   */
   scale_control?: boolean;
 
-  /** show stats panel */
+  /** 
+   * show the stats panel under the spreadsheet.
+   */
   stats?: boolean;
 
-  /** save/load scale. this can optionally have a string key to disambiguate */
+  /** 
+   * save/load scale. this can optionally have a string key to disambiguate 
+   */
   persist_scale?: boolean|string;
 
-  /** target window for hyperlinks (default _blank); set false to disable hyperlinks altogether */
+  /** 
+   * target window for hyperlinks (default _blank); set false to disable hyperlinks altogether 
+   */
   hyperlinks?: string|false;
 
   /**
@@ -209,25 +215,20 @@ export interface EmbeddedSpreadsheetOptions {
    */
   complex?: 'on'|'off';
 
-  /* * 
-   * support complex numbers. the meaning of this flag is changing -- the 
-   * parser is going to always support complex numbers, but we might load 
-   * a different set of functions if they're not expected to be used.
-   * ...
-   * no, we're not doing that. atm complex support is always baked in.
-   * @deprecated
-   * @internal
-   */
-  // complex?: boolean;
-
   /** 
    * for rendering the imaginary number. this is intended to support 
    * switching to a different character for rendering, or adding a leading
    * space/half-space/hair-space.
+   * 
+   * this _does_not_ change how you enter imaginary numbers, you still have
+   * to use `i` (lower-case ascii i).
    */
   imaginary_value?: string;
 
-  /** support MD formatting for text */
+  /** 
+   * support markdown formatting for text in cells and comments. at the 
+   * moment we only support bold, italic, and strike text.
+   */
   markdown?: boolean;
 
   /** 
@@ -236,15 +237,19 @@ export interface EmbeddedSpreadsheetOptions {
    */
   tint_theme_colors?: boolean;
 
-  /** show a spinner for long-running operations */
+  /** 
+   * show a spinner for long-running operations 
+   */
   spinner?: boolean;
 
-  /** collapsed: start sidebar closed */
+  /** 
+   * start with sidebar closed. defaults to false.
+   */
   collapsed?: boolean;
   
   /**
-   * show the revert button. see the Revert method. this was renamed
-   * from `revert` to avoid any ambiguity.
+   * show the revert button in the sidebar. see the `Revert` method. this 
+   * was renamed from `revert` to avoid any ambiguity.
    */
   revert_button?: boolean;
 
@@ -291,30 +296,3 @@ export const DefaultOptions: EmbeddedSpreadsheetOptions = {
   complex: 'off',
 
 };
-
-/* *
- * actual options requires the container node
- * /
-export interface EmbeddedSpreadsheetOptions extends BaseOptions {
-  container?: string|HTMLElement;
-}
-*/
-
-/**
- * embed creation adds option for icons
- */
-export interface CreateSheetOptions extends EmbeddedSpreadsheetOptions {
-
-  /** icons */
-  decorated?: boolean;
-
-
-  /** 
-   * optional callback function on create. we're not using this anymore, but
-   * leaving it in for backwards compatibility.
-   * 
-   * @internal
-   */
-  load?: string;
-
-}