@trebco/treb 23.6.5 → 25.0.0-rc2

package/.eslintignore

@@ -0,0 +1,8 @@
+
+node_modules
+dist
+build
+declaration
+treb.d.ts
+
+

package/.eslintrc.js

@@ -0,0 +1,164 @@
+module.exports = {
+  env: {
+    'browser': true,
+    'node': true,
+  },
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: [
+    '@typescript-eslint',
+  ],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+
+  rules: {
+    'no-irregular-whitespace': [
+      'error',
+      {
+        skipComments: true,
+      }
+    ],
+    'camelcase': 'off',
+    '@typescript-eslint/camelcase': 'off',     
+    // '@typescript-eslint/explicit-function-return-type': 'off',     
+    '@typescript-eslint/quotes': [
+      'error',
+      'single',
+      { 'allowTemplateLiterals': true },
+    ],
+    'brace-style': 'off',
+    '@typescript-eslint/brace-style': [
+      'error',
+      'stroustrup',
+      { 'allowSingleLine': true },
+    ],
+    '@typescript-eslint/interface-name-prefix': 'off',
+
+    /*
+
+    FIXME: needs configuration. I'm ok with it generally but why split 
+    accessors for the same field?
+
+    UPDATE: see also https://eslint.org/docs/rules/grouped-accessor-pairs
+
+    not sure how these work together
+
+    '@typescript-eslint/member-ordering': [
+      'error',
+    ],
+    */
+
+    'grouped-accessor-pairs': ['error', 'getBeforeSet'],
+    
+  }
+
+  /*
+  "rules": {
+    "@typescript-eslint/adjacent-overload-signatures": "error",
+    "@typescript-eslint/array-type": "error",
+    "@typescript-eslint/ban-types": "error",
+    "@typescript-eslint/class-name-casing": "error",
+    "@typescript-eslint/consistent-type-assertions": "error",
+    "@typescript-eslint/indent": [
+        2
+    ],
+    "@typescript-eslint/no-empty-function": "error",
+    "@typescript-eslint/no-empty-interface": "error",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-misused-new": "error",
+    "@typescript-eslint/no-namespace": "error",
+    "@typescript-eslint/no-parameter-properties": "off",
+    "@typescript-eslint/no-use-before-define": "off",
+    "@typescript-eslint/no-var-requires": "error",
+    "@typescript-eslint/prefer-for-of": "error",
+    "@typescript-eslint/prefer-function-type": "error",
+    "@typescript-eslint/prefer-namespace-keyword": "error",
+    "@typescript-eslint/quotes": [
+        "error",
+        "single"
+    ],
+    "@typescript-eslint/triple-slash-reference": "error",
+    "@typescript-eslint/unified-signatures": "error",
+    "camelcase": "off",
+    "complexity": "off",
+    "constructor-super": "error",
+    "curly": [
+        "error",
+        "multi-line"
+    ],
+    "dot-notation": "error",
+    "eqeqeq": [
+        "error",
+        "smart"
+    ],
+    "guard-for-in": "error",
+    "id-blacklist": "error",
+    "id-match": "error",
+    "import/order": "off",
+    "max-classes-per-file": [
+        "error",
+        1
+    ],
+    "new-parens": "error",
+    "no-bitwise": "error",
+    "no-caller": "error",
+    "no-cond-assign": "error",
+    "no-console": "off",
+    "no-debugger": "error",
+    "no-empty": "error",
+    "no-eval": "error",
+    "no-fallthrough": "off",
+    "no-invalid-this": "off",
+    "no-multiple-empty-lines": "off",
+    "no-new-wrappers": "error",
+    "no-shadow": [
+        "error",
+        {
+            "hoist": "all"
+        }
+    ],
+    "no-throw-literal": "error",
+    "no-trailing-spaces": "error",
+    "no-undef-init": "error",
+    "no-underscore-dangle": "error",
+    "no-unsafe-finally": "error",
+    "no-unused-expressions": "error",
+    "no-unused-labels": "error",
+    "no-var": "error",
+    "object-shorthand": "error",
+    "one-var": [
+        "error",
+        "never"
+    ],
+    "prefer-arrow/prefer-arrow-functions": "error",
+    "prefer-const": "error",
+    "quote-props": [
+        "error",
+        "as-needed"
+    ],
+    "radix": "error",
+    "spaced-comment": "error",
+    "use-isnan": "error",
+    "valid-typeof": "off",
+
+    / *
+    "@typescript-eslint/tslint/config": [
+        "error",
+        {
+            "rules": {
+                "jsdoc-format": true,
+                "no-reference-import": true,
+                "one-line": [
+                    true,
+                    "check-open-brace"
+                ]
+            }
+        }
+    ]
+    * /
+  }
+  */
+};

package/README-shadow-DOM.md

@@ -0,0 +1,88 @@
+
+### Note on shadow DOM
+Date: March 4 2023
+
+---
+
+I spent the last couple of weeks building TREB as a custom element using 
+shadow DOM. 
+
+The benefits of shadow DOM would be tremendous, particularly style isolation.
+But ultimately there are just too many things broken for this to be practical
+as of today (March 2023). We can revisit in the future.
+
+### Selection
+
+Selection behaves differently in various browsers. Specifically the issue 
+arises when we try to get the current selection. We primarily use selections
+when typing spreadsheet formula. This happens in either the formula bar or
+the overlay editor (replacement for the old in-cell editor). 
+
+We typically check the selection in order to get the caret position. We use 
+the caret position and the entered text to highlight references in formulas
+and to insert references when mouse-selecting.
+
+#### Cross-browser selection
+
+The standard way to get the selection, in light DOM, is `Window.getSelection`.
+
+In Firefox this still works in shadow DOM. It does not work in Chrome, but 
+they add a nonstandard method to the shadow root so `ShadowRoot.getSelection` 
+works instead.
+
+Safari supports neither. We can hack our way around this in Safari using the
+`beforeinput` event, which will give you the selection on a particular 
+component. We wrote a helper class that would allow you to get the selection
+by sending an event to the component and then blocking any component update,
+but collecting the selection from the event.
+
+That Safari fix required making our `GetSelection` method asynchronous, which
+changed a lot of code paths but which was ultimately not a huge problem.
+
+#### Potential resolution
+
+We could live with our workaround. There is a proposal for a standar fix,
+
+https://github.com/WICG/webcomponents/issues/79
+
+but that proposal is already 8 years old and shows no sign of moving.
+
+### Focus/typing
+
+Focus and typing was the big blocker. For the most part this seems to work
+correctly in Chrome. Safari was not fully investigated. Firefox is completely
+broken.
+
+Among other things, Firefox doesn't support changing selection between light
+DOM and shadow DOM elements:
+
+https://bugzilla.mozilla.org/show_bug.cgi?id=1685300
+https://bugzilla.mozilla.org/show_bug.cgi?id=1496769
+
+That results in the cursor not showing up, or the text not being editable, or
+the element not being selectable at all.
+
+This bug is 5 years old, the latest comment is ~8 months old at this point 
+and there doesn't seem to be any movement on it.
+
+Additionally some elements would randomly change to RTL when editing text. I 
+couldn't find a bug tracking this and did not fully investigate, but setting
+standard properties (`dir` attribute, `direction` style property) would not 
+resolve this issue.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/README.md

@@ -1,149 +1,56 @@
-
 # TREB
 
-https://treb.app
-
-TREB is a spreadsheet component you can embed in web pages, web apps, or blogs.
+<a href='https://treb.app'><img alt="TREB logo (a leaf)" width="64" height="64" src="treb-logo.svg"></img></a>
 
-This is the ES module version. It's intended for quick integration with 
-front-end frameworks.
+http://treb.app
 
-## Installing
+TREB is a spreadsheet component designed for embedding in web pages, 
+web apps, and blogs.
 
-Install with npm/yarn/pnpm.
+## Using
 
-```sh
-> npm install --save @trebco/treb
+To add a spreadsheet to your web page, first add the script file
 ```
-
-## Stylesheet
-
-Note that the library does not automatially load the stylesheet it needs to 
-render properly (we do this for sites/apps that have strict CSP settings). So
-you need to load the stylesheet, either via `import` in your front-end 
-framework or by just including the stylesheet in your HTML.
-
-## Using 
-
-Here's how to add a spreadsheet in a couple of frameworks:
-
-### Svelte (and svelte-kit)
-
-```html
-<script lang="ts">
-
-// import the onMount handler from svelte
-import { onMount } from 'svelte';
-
-// import TREB module
-import { TREB } from 'treb';
-
-// import stylesheet
-import 'treb/treb-bundle.css';
-
-// reference to the HTML node we will use to mount the spreadsheet
-let container: HTMLElement;
-
-onMount(() => {
-
-  // create spreadsheet, passing a reference to the container node
-  TREB.CreateSpreadsheet({
-    container,
-  });
-
-});
-
-</script>
-
-<!-- this is the node where we will add the spreadsheet -->
-<div bind:this={container}></div>
-
+<script type="module" defer src="https://unpkg.com/@trebco/treb@next"></script>
 ```
-
-### React
-
-
-```tsx
-import React from 'react';
-
-// import TREB module
-import { TREB } from 'treb';
-
-// import TREB stylesheets
-import 'treb/treb-bundle.css';
-
-class SpreadsheetComponent extends React.Component {
-
-  // reference to our DOM node
-  public container: React.RefObject<HTMLDivElement>;
-
-  constructor(props) {
-    super(props);
-
-    // create ref to DOM node
-    this.container = React.createRef();
-  }
-
-  public componentDidMount() {
-    // create spreadsheet, passing reference to the container node
-    TREB.CreateSpreadsheet({ 
-      container: this.container.current,
-    });
-  }
-
-  public render() {
-    return (
-      <div ref={this.container}></div>
-    );
-  }
-}
-
-export default SpreadsheetComponent;
+then use the custom element in your page
+```
+<treb-spreadsheeet></treb-spreadsheet>
 ```
 
-### Vanilla javascript
-
-There are other ways to embed TREB spreadsheets in vanilla javascript and 
-HTML. This is an example specifically for the ES module. See the docs for 
-other options.
-
-```html
-<html>
-  <head>
-    
-    <!-- include stylesheet -->
-    <link rel='stylesheet' href='/path/to/treb-bundle.css'>
-    <script type='module'>
-
-// import from esm
-import { TREB } from '/path/to/treb-bundle.mjs';
-
-// run this when the DOM is complete
-document.addEventListener("DOMContentLoaded", () => {
-
-  // get the node
-  const container = document.querySelector('.embedded-spreadsheet');
-
-  // call CreateSpreadsheet with the container node
-  TREB.CreateSpreadsheet({ container });
-
-});
-      
-      </script>
-  </head>
-  <body>
+For more information on options, configuration, and using the API, 
+go to [docs.treb.app][1].
 
-    <!-- we will use script to insert the spreadsheet in this div -->
-    <div class="embedded-spreadsheet"></div>
+## Download
 
-  </body>
-</html>
+Download from npm using npm, yarn, pnpm or your favorite module tool
 ```
+npm install @trebco/treb
+```
+
+## License
 
-## More
+TREB is provided under the GNU Lesser General Public License (LGPL). 
+See the file [LICENSE.txt][3] for details. TREB is also available under a 
+commercial license with different terms. For more information contact
+us at [info@treb.app][4].
 
-For documentation on using TREB and the API see our website at https://treb.app.
+## Note on icons
 
+TREB includes icons from [font awesome][6], used under the terms of the
+[font awesome free license][7]; and [bootstrap icons][8], used under the terms
+of the [MIT license][9]. 
 
+The TREB icon (a leaf) is a trademark of trebco, llc. Other icons are property 
+of their respective owners. 
 
+[1]: https://docs.treb.app
+[2]: treb-embed/style/treb-icons.scss
+[3]: LICENSE.txt
+[4]: mailto:info@treb.app
+[5]: https://treb.app/download
+[6]: https://fontawesome.com/
+[7]: https://github.com/FortAwesome/Font-Awesome/blob/master/LICENSE.txt
+[8]: https://icons.getbootstrap.com/
+[9]: https://github.com/twbs/icons/blob/main/LICENSE.md
 

package/api-config.json

@@ -0,0 +1,29 @@
+{
+
+  "package": "./package.json",
+
+  "output": "./build/treb.d.ts",
+
+  "root": "./declaration",
+
+  "index": "treb-embed/src/index.d.ts",
+
+  "include": [
+    "treb-embed/src/custom-element/global.d.ts"
+  ],
+
+  "drop_types": [
+    "GridEvent"
+  ],
+
+  "convert_to_any": [
+    "TREBDocument"
+  ],
+
+  "exclude_tags": [
+    "internal"
+  ],
+
+  "flatten_enums": true
+
+}

package/api-generator/api-generator-types.ts

@@ -0,0 +1,82 @@
+
+export interface Config {
+
+  /** root of declaration dir, relative to config file */
+  root: string;
+
+  /** starting point for docs, relative to root */
+  index: string;
+
+  /** output file relative to config file (or stdout) */
+  output?: string;
+
+  /** package.json for version information */
+  package: string;
+
+  /** drop these types, even if they're exported */
+  drop_types: string[];
+
+  /** keep variables of this type but change to any */
+  convert_to_any: string[];
+
+  /** exclude via jsdoc tags. typically "internal" */
+  exclude_tags: string[];
+
+  /** drop generics */
+  drop_generics: string[];
+
+  /** rename types */
+  rename_types: Record<string, string>;
+
+  /** additional files to include. these will be concatenated to the generated output. */
+  include: string[];
+
+  /** map declaration files directly (by prefix) */
+  map: Record<string, string>;
+
+  /** turn enums into union types. this helps import. */
+  flatten_enums: boolean;
+
+}
+
+
+export interface ReadTypeArgs {
+  /** 
+  * types we are looking for. if this is missing, we will colllect
+  * all types that are exported and public (TODO: also not @internal) 
+  */
+  types?: string[],
+
+  /** dependencies, with target types */
+  recursive_targets: Record<string, string[]>,
+
+  /** ... */
+  imported_types: Record<string, string>,
+
+  /** 
+   * this has to change, because we may collect reference types
+   * from types which we don't actually want (the owner/parent).
+   * however, we don't know ahead of time because the (owner/parent)
+   * type may be referenced later...
+   * 
+   * so this is a map of who references it -> the reference. we 
+   * can collapse this list later once we decide what we actually want
+   * to keep.
+   * 
+   * actually let's keep both records...
+   */
+  referenced_type_map: Record<string, string[]>,
+
+  /** types we will need, from the imports (probably) */
+  referenced_types: Record<string, number>,
+
+  /** types we have resolved (we can stop looking for them) */
+  found_types: Record<string, string>,
+
+  /** ... */
+  extra_types: Record<string, string>,
+
+  /** exported variables */
+  exported_variables: string[],
+
+}