Merge branch 'release/2.4.0'

.eslintrc.js

@@ -32,6 +32,7 @@ module.exports = {
     '@typescript-eslint/brace-style': 'error', // wtf
     '@typescript-eslint/no-unnecessary-boolean-literal-compare': ['error'],
     '@typescript-eslint/no-extra-non-null-assertion': ['error'],
+    '@typescript-eslint/no-throw-literal': ['error'],
     '@typescript-eslint/array-type': ['error'],
     '@typescript-eslint/space-before-function-paren': ["error", {
       "anonymous": "never",

.github/pull_request_template.md

@@ -20,10 +20,11 @@
 ### Checklist:
 <!--- Go through the points below, and put an `x` in each box that applies. -->
 <!--- If you're unsure about any of these, contact us. We're always glad to help! -->
+- [ ] I have reviewed the guidelines about [Contributing to HyperFormula](https://hyperformula.handsontable.com/guide/contributing.html) and I confirm that my code follows the code style of this project.
+- [ ] I have signed the [Contributor License Agreement](https://goo.gl/forms/yuutGuN0RjsikVpM2).
 - [ ] My change is compliant with the [OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html) standard.
 - [ ] My change is compatible with Microsoft Excel.
 - [ ] My change is compatible with Google Sheets.
-- [ ] My code follows the code style of this project.
 - [ ] I described my changes in the [CHANGELOG.md](https://github.com/handsontable/hyperformula/blob/master/CHANGELOG.md) file.
 - [ ] My changes require a documentation update.
 - [ ] My changes require a migration guide.

CHANGELOG.md

@@ -8,6 +8,24 @@ and this project adheres to
 
 ## [Unreleased]
 
+## [2.4.0] - 2023-04-24
+
+### Added
+
+- Exported the `CellError` class as a public API.
+  [#1232](https://github.com/handsontable/hyperformula/issues/1232)
+- Exported the `SimpleRangeValue` class as a public API.
+  [#1178](https://github.com/handsontable/hyperformula/issues/1178)
+
+### Fixed
+
+- Fixed an `EmptyCellVertex` data integrity issue between the `AddressMapping` and `DependencyGraph` objects.
+  [#1188](https://github.com/handsontable/hyperformula/issues/1188)
+- Fixed a build issue with M1- and M2-chip MacBooks.
+  [#1166](https://github.com/handsontable/hyperformula/issues/1166)
+- Fixed an issue where the order of items returned by `removeColumns()` depended on the address mapping policy.
+  [#1205](https://github.com/handsontable/hyperformula/issues/1205)
+
 ## [2.3.1] - 2023-03-03
 
 ### Fixed

docs/.vuepress/config.js

@@ -21,7 +21,13 @@ module.exports = {
       })(window,document,'script','dataLayer','GTM-N59TZXR');
     `],
     // Google Console
-    ['meta', { name: 'google-site-verification', content: 'MZpSOa8SNvFLRRGwUQpYVZ78kIHQoPVdVbafHhJ_d4Q' }]
+    ['meta', { name: 'google-site-verification', content: 'MZpSOa8SNvFLRRGwUQpYVZ78kIHQoPVdVbafHhJ_d4Q' }],
+    // Favicon
+    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/favicon/apple-touch-icon.png' }],
+    ['link', { rel: 'icon', sizes: '32x32', type: 'image/png', href: '/favicon/favicon-32x32.png' }],
+    ['link', { rel: 'icon', sizes: '16x16', type: 'image/png', href: '/favicon/favicon-16x16.png' }],
+    ['link', { rel: 'manifest', href: '/favicon/site.webmanifest' }],
+    ['link', { rel: 'mask-icon', color: '#ffffff', href: '/favicon/safari-pinned-tab.svg' }],
   ],
   base: '/',
   plugins: [

docs/.vuepress/public/favicon/browserconfig.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/mstile-150x150.png"/>
+            <TileColor>#ffffff</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>

docs/.vuepress/public/favicon/site.webmanifest

@@ -0,0 +1,19 @@
+{
+    "name": "HyperFormula",
+    "short_name": "HyperFormula",
+    "icons": [
+        {
+            "src": "/android-chrome-192x192.png",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "/android-chrome-512x512.png",
+            "sizes": "512x512",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "display": "standalone"
+}

docs/guide/advanced-usage.md

@@ -96,7 +96,7 @@ After setting everything up, you can add formulas:
 // add a sheet named 'Formulas'
 const sheetNameC = hfInstance.addSheet('Formulas');
 // get the new sheet ID for further API calls
-const sheetIdC = hfInstance.getSheetId(sheetNameA);
+const sheetIdC = hfInstance.getSheetId(sheetNameC);
 // add formulas to that sheet
 hfInstance.setSheetContent(sheetIdC, formulas);
 ```
@@ -122,7 +122,7 @@ console.log(winningTeam)
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: advanced-usage"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/basic-operations.md

@@ -389,7 +389,7 @@ This demo presents several basic operations integrated with a
 sample UI.
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/basic-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/basic-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
   style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
   title="handsontable/hyperformula-demos: basic-operations"
   allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/basic-usage.md

@@ -65,7 +65,7 @@ works. It's time to move on to a more
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/basic-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/basic-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: basic-usage"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/batch-operations.md

@@ -118,7 +118,7 @@ can be sent as a single one.
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/batch-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/batch-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: batch-operations"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/built-in-functions.md

@@ -1,5 +1,18 @@
 # Built-in functions
 
+<!--
+The below dummy div uses a CSS class to alter the .page layout for the current page without any additional customization of VuePress.
+It makes the page wider to accommodate large tables
+-->
+<div class="widePage"></div>
+<style>
+.page:has(.widePage) .theme-default-content:not(.custom), /* markdown content */
+.page:has(.widePage) .page-edit, /* footer containing the "Help us improve the page" link */
+.page:has(.widePage) .page-nav /* footer links to the next and prev page */ {
+  max-width: 1200px !important; /* override default max-width of 740px for this page */
+}
+</style>
+
 ## Overview
 
 HyperFormula comes with an extensive library of pre-built functions. You can use
@@ -9,6 +22,8 @@ spreadsheet software. That is because a spreadsheet is probably the most
 universal software ever created. We wanted the same flexibility for HyperFormula
 but without the constraints of the spreadsheet UI.
 
+Each of HyperFormula's built-in function names is available in [17 languages](localizing-functions.md#list-of-supported-languages) and [custom language packs](localizing-functions) can be added.
+
 The latest version of HyperFormula has an extensive collection of
 **{{ $page.functionsCount }}** functions grouped into categories:
 
@@ -28,34 +43,9 @@ The latest version of HyperFormula has an extensive collection of
 _Some categories such as compatibility, cube, and database are yet to be
 supported._
 
-## Internationalization
-
-Each of HyperFormula's built-in function names (and
-[errors](types-of-errors.md)) is available in
-[17 language versions](localizing-functions.md#list-of-supported-languages).
-
-To support more languages or properties, create a
-[custom language pack](localizing-functions).
-
-## Custom functions
-
-One of the most valuable features of HyperFormula is its extensibility. All
-functions are implemented within the plugin architecture which means it is easy
-to remove or replace them. This means you are not limited by the current
-functionality of the engine. HyperFormula lets you design your own
-[custom functions](custom-functions).
-
-## Demo
-
-<iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/built-in-functions?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
-  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
-  title="handsontable/hyperformula-demos: built-in-functions"
-  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
-  sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
-</iframe>
-
-<br><br>
+::: tip
+You can modify the built-in functions or create your own, by adding a [custom function](custom-functions).
+:::
 
 ## List of available functions
 

docs/guide/clipboard-operations.md

@@ -112,4 +112,4 @@ Depending on what was cut, the data is stored as:
 
 ## Demo
 
-<iframe src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/clipboard-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" title="handsontable/hyperformula-demos: clipboard-operations" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"></iframe>
+<iframe src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/clipboard-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview" style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" title="handsontable/hyperformula-demos: clipboard-operations" allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"></iframe>

docs/guide/custom-functions.md

@@ -69,8 +69,12 @@ MyCustomPlugin.implementedFunctions = {
 
 ### 3. Add your function's names
 
-In a separate object,
-[define your function's names in every language you want to support](#function-name-translations).
+In a separate object, define your function's names in every
+[language](#function-name-translations) that you want to support.
+
+::: tip
+Even if you support just a single language, you still need to define a translation for it.
+:::
 
 ```js
 export const MyCustomPluginTranslations = {
@@ -127,8 +131,8 @@ export class MyCustomPlugin extends FunctionPlugin {
 
 ### 5. Register your function plugin
 
-Register your function plugin (and its translations) so that HyperFormula can
-recognize it.
+Register your function plugin and its translations so that HyperFormula can
+recognize it. You need to do this **before** you create your HyperFormula instance.
 
 Use the
 [`registerFunctionPlugin()`](../api/classes/hyperformula.md#registerfunctionplugin)
@@ -138,21 +142,18 @@ method:
 HyperFormula.registerFunctionPlugin(MyCustomPlugin, MyCustomPluginTranslations);
 ```
 
-### 6. Use your custom function inside a formula
+### 6. Use your custom function in a formula
 
-Now, you can use your GREET function inside a formula:
+Now, you're ready to use your GREET function in a formula.
 
 ```js
-// prepare spreadsheet data
-const data = [['Anthony', '=GREET(A1)']];
-
 // build a HyperFormula instance where you can use your function directly
-const hfInstance = HyperFormula.buildFromArray(data);
+const hfInstance = HyperFormula.buildFromArray([['Anthony', '=GREET(A1)']]);
 
-// read the value of cell A1
+// read the value of cell B1
 const result = hfInstance.getCellValue({ sheet: 0, col: 1, row: 0 });
 
-// open the browser's console to see the results
+// cell B1 should evaluate to 'Anthony'
 console.log(result);
 ```
 
@@ -357,7 +358,7 @@ This demo contains the implementation of both the
 [`DOUBLE_RANGE`](#advanced-custom-function-example) custom functions.
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/custom-functions?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/custom-functions?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
   style="width:100%; height:300px; border:0; border-radius: 4px; overflow:hidden;"
   title="handsontable/hyperformula-demos: custom-functions"
   allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
@@ -478,15 +479,14 @@ function's behavior depends on the number of valid arguments passed), use the
 You can add translations of your function's name in multiple languages. Your end
 users use the translated names to call your function inside formulas.
 
-::: tip
-If you support just one language, you still need to define the name of
-your function in that language.
-:::
-
 In a separate object, define the translations of your custom functions' names in
 every language you want to support. Function names are case-insensitive, as they
 are all normalized to uppercase.
 
+::: tip
+Even if you support just a single language, you still need to define a translation for it.
+:::
+
 ```js
 export const MyCustomPluginTranslations = {
   enGB: {

docs/guide/date-and-time-handling.md

@@ -99,7 +99,7 @@ And now, HyperFormula recognizes these values as valid dates and can operate on
 ## Demo
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/date-time?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/date-time?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
   style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
   title="handsontable/hyperformula-demos: date-time"
   allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/demo.md

@@ -1,7 +1,7 @@
 # Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/vanillajs-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/vanillajs-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; margin-bottom: 50px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: vanillajs-demo"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/file-import.md

@@ -18,7 +18,7 @@ To import XLSX files, use a third-party [XLSX parser](https://www.npmjs.com/sear
 
 This example uses [ExcelJS](https://www.npmjs.com/package/exceljs) to import XLSX files into HyperFormula. 
 
-See full example on [GitHub](https://github.com/handsontable/hyperformula-demos/tree/2.3.x/read-excel-file).
+See full example on [GitHub](https://github.com/handsontable/hyperformula-demos/tree/2.4.x/read-excel-file).
 
 ```js
 const ExcelJS = require('exceljs');

docs/guide/i18n-features.md

@@ -106,7 +106,7 @@ localeLang: 'en-US',
 This demo shows HyperFormula configured for the `en-US` locale.
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/i18n?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/i18n?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
   style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
   title="handsontable/hyperformula-demos: basic-operations"
   allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/integration-with-angular.md

@@ -8,7 +8,7 @@ more details.
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/angular-demo?autoresize=1
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/angular-demo?autoresize=1
      &fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: angular-demo"

docs/guide/integration-with-react.md

@@ -8,7 +8,7 @@ more details.
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/react-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/react-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: react-demo"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"

docs/guide/integration-with-vue.md

@@ -8,7 +8,7 @@ more details.
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.3.x/vue-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.4.x/vue-demo?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
      style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
      title="handsontable/hyperformula-demos: vue-demo"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"