Merge branch 'release/2.7.0'

Author: sequba

.typedoc.md.ts

@@ -2,8 +2,8 @@ module.exports = {
   ...require('./.typedoc.ts'),
   "theme": "./docs/.vuepress/subtheme",
   "out": "docs/api",
-  "name": "HyperFormula API reference",
+  "name": "API Reference Overview",
   "categorizeByGroup": true,
-  "readme": "./docs/api-template.md",
+  "readme": "./docs/api-ref-readme.md",
   "plugin": ["typedoc-plugin-markdown"],
 }

.typedoc.ts

@@ -1,7 +1,7 @@
 module.exports = {
   "inputFiles": [
     "./src/HyperFormula.ts",
-    "./src/Config.ts",
+    "./src/ConfigParams.ts",
     "./src/Emitter.ts",
   ],
   "exclude": [
@@ -47,7 +47,7 @@ module.exports = {
   ],
   "toc": [
     "HyperFormula",
-    "Config",
+    "ConfigParams",
     "Emitter"
   ]
 }

CHANGELOG.md

@@ -7,6 +7,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+## [2.7.0] - 2024-04-10
+
+### Added
+
+- Added method `getNamedExpressionsFromFormula` to extract named expressions from formulas. [#1365](https://github.com/handsontable/hyperformula/issues/1365)
+- Added `context` config option for passing data to custom functions. [#1396](https://github.com/handsontable/hyperformula/issues/1396)
+
 ## [2.6.2] - 2024-02-15
 
 ### Changed

README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  <strong>A headless spreadsheet • A parser and evaluator of Excel formulas</strong>
+  <strong>An open-source headless spreadsheet for business web apps</strong>
 </p>
 
 <p align="center">
@@ -22,90 +22,89 @@
 
 ---
 
-HyperFormula is a headless spreadsheet built on top of TypeScript. It is a parser and evaluator of Excel formulas for web applications. You can use it in a browser or as a service, with Node.js as your back-end technology.
-- High-speed Excel formula parsing and evaluating
-- A library of nearly [400 built-in functions](https://hyperformula.handsontable.com/guide/built-in-functions.html)
-- Support for [internationalization](https://hyperformula.handsontable.com/guide/i18n-features.html) with 17 built-in languages
-- Support for [custom functions](https://hyperformula.handsontable.com/guide/custom-functions.html)
-- Function syntax compatible with [Microsoft Excel](https://hyperformula.handsontable.com/guide/compatibility-with-microsoft-excel.html) and [Google Sheets](https://hyperformula.handsontable.com/guide/compatibility-with-google-sheets.html)
+HyperFormula is a headless spreadsheet built in TypeScript, serving as both a parser and evaluator of spreadsheet formulas. It can be integrated into your browser or utilized as a service with Node.js as your back-end technology.
+
+## What HyperFormula can be used for?
+HyperFormula doesn't assume any existing user interface, making it a general-purpose library that can be used in various business applications. Here are some examples:
+
+- Custom spreadsheet-like app
+- Business logic builder
+- Forms and form builder
+- Educational app
+- Online calculator
+
+## Features
+
+- [Function syntax compatible with Microsoft Excel](https://hyperformula.handsontable.com/guide/compatibility-with-microsoft-excel.html) and [Google Sheets](https://hyperformula.handsontable.com/guide/compatibility-with-google-sheets.html)
+- High-speed parsing and evaluation of spreadsheet formulas
+- [A library of ~400 built-in functions](https://hyperformula.handsontable.com/guide/built-in-functions.html)
+- [Support for custom functions](https://hyperformula.handsontable.com/guide/custom-functions.html)
 - [Support for Node.js](https://hyperformula.handsontable.com/guide/server-side-installation.html#install-with-npm-or-yarn)
-- Support for [undo/redo](https://hyperformula.handsontable.com/guide/undo-redo.html)
-- Support for [CRUD operations](https://hyperformula.handsontable.com/guide/basic-operations.html)
-- Support for [clipboard](https://hyperformula.handsontable.com/guide/clipboard-operations.html)
-- Support for [named expressions](https://hyperformula.handsontable.com/guide/named-expressions.html)
-- Support for [data sorting](https://hyperformula.handsontable.com/guide/sorting-data.html)
-- Support for [React](https://hyperformula.handsontable.com/guide/integration-with-react.html), [Angular](https://hyperformula.handsontable.com/guide/integration-with-angular.html), and [Vue.js](https://hyperformula.handsontable.com/guide/integration-with-vue.html)
-- Open-source license
-- Actively maintained by the team that stands behind [Handsontable - JavaScript Data Grid](https://handsontable.com/)
+- [Support for undo/redo](https://hyperformula.handsontable.com/guide/undo-redo.html)
+- [Support for CRUD operations](https://hyperformula.handsontable.com/guide/basic-operations.html)
+- [Support for clipboard](https://hyperformula.handsontable.com/guide/clipboard-operations.html)
+- [Support for named expressions](https://hyperformula.handsontable.com/guide/named-expressions.html)
+- [Support for data sorting](https://hyperformula.handsontable.com/guide/sorting-data.html)
+- [Support for formula localization with 17 built-in languages](https://hyperformula.handsontable.com/guide/i18n-features.html)
+- GPLv3 license
+- Maintained by the team that stands behind the [Handsontable](https://handsontable.com/) data grid
 
 ## Documentation
 
-- [Explainer video](https://www.youtube.com/watch?v=JJXUmACTDdk)
-- [Installation](https://hyperformula.handsontable.com/guide/client-side-installation.html)
+- [Client-side installation](https://hyperformula.handsontable.com/guide/client-side-installation.html)
+- [Server-side installation](https://hyperformula.handsontable.com/guide/server-side-installation.html)
 - [Basic usage](https://hyperformula.handsontable.com/guide/basic-usage.html)
-  - [Demo with React](https://hyperformula.handsontable.com/guide/integration-with-react.html)
-  - [Demo with Angular](https://hyperformula.handsontable.com/guide/integration-with-angular.html)
-  - [Demo with Vue.js](https://hyperformula.handsontable.com/guide/integration-with-vue.html)
-- [API Reference](https://hyperformula.handsontable.com/api/)
 - [Configuration options](https://hyperformula.handsontable.com/guide/configuration-options.html)
 - [List of built-in functions](https://hyperformula.handsontable.com/guide/built-in-functions.html)
-- [Key concepts](https://hyperformula.handsontable.com/guide/key-concepts.html)
+- [API Reference](https://hyperformula.handsontable.com/api/)
+
+## Integrations
+
+- [Integration with React](https://hyperformula.handsontable.com/guide/integration-with-react.html#demo)
+- [Integration with Angular](https://hyperformula.handsontable.com/guide/integration-with-angular.html#demo)
+- [Integration with Vue](https://hyperformula.handsontable.com/guide/integration-with-vue.html#demo)
+- [Integration with Svelte](https://hyperformula.handsontable.com/guide/integration-with-svelte.html#demo)
 
 ## Installation and usage
 
-Install the library from [npm](https://www.npmjs.com/package/hyperformula):
+Install the library from [npm](https://www.npmjs.com/package/hyperformula) like so:
 
 ```bash
 npm install hyperformula
 ```
 
-Once installed, you can use it like this:
+Once installed, you can use it to develop applications tailored to your specific business needs. Here, we've used it to craft a form that calculates mortgage payments using the `PMT` formula.
 
 ```js
 import { HyperFormula } from 'hyperformula';
 
-// define the options
-const options = {
-  licenseKey: 'gpl-v3',
-};
+// Create a HyperFormula instance
+const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
 
-// define the data
-const data = [['10', '20', '30', '=SUM(A1:C1)']];
+// Add an empty sheet
+const sheetName = hf.addSheet('Mortgage Calculator');
+const sheetId = hf.getSheetId(sheetName);
 
-// build an instance with defined options and data
-const hfInstance = HyperFormula.buildFromArray(data, options);
+// Enter the mortgage parameters
+hf.addNamedExpression('AnnualInterestRate', '8%');
+hf.addNamedExpression('NumberOfMonths', 360);
+hf.addNamedExpression('LoanAmount', 800000);
 
-// call getCellValue to get the calculation results
-const mySum = hfInstance.getCellValue({ col: 3, row: 0, sheet: 0 });
+// Use the PMT function to calculate the monthly payment
+hf.setCellContents({ sheet: sheetId, row: 0, col: 0 }, [['Monthly Payment', '=PMT(AnnualInterestRate/12, NumberOfMonths, -LoanAmount)']]);
 
-// print the result in the browser's console
-console.log(mySum);
+// Display the result
+console.log(`${hf.getCellValue({ sheet: sheetId, row: 0, col: 0 })}: ${hf.getCellValue({ sheet: sheetId, row: 0, col: 1 })}`);
 ```
 
-[Run this code in CodeSandbox](https://codesandbox.io/s/github/handsontable/hyperformula-demos/tree/develop/basic-usage)
-
-## What can it be used for?
-
-HyperFormula doesn't assume any existing user interface, making it a great general-purpose library that can be used in various business applications. Here are some examples:
-
-- Spreadsheets
-- Business logic builders
-- Forms and form builders
-- Computation notebooks
-- Smart documents
-- Educational apps
-- Online calculators
+[Run this code in CodeSandbox](https://codesandbox.io/p/sandbox/github/handsontable/hyperformula-demos/tree/2.7.x/mortgage-calculator)
 
 ## Contributing
 
-Help us build the fastest and most flexible calculation engine for
-business web apps. Please read the [Contributing Guide](https://hyperformula.handsontable.com/guide/contributing.html) before making a pull request.
+Contributions are welcome, but before you make them, please read the [Contributing Guide](https://hyperformula.handsontable.com/guide/contributing.html) and accept the [Contributor License Agreement](https://goo.gl/forms/yuutGuN0RjsikVpM2).
 
 ## License
 
-HyperFormula is available under the open source license ([GPLv3](https://github.com/handsontable/hyperformula/blob/master/LICENSE.txt)).
-
-To buy a commercial license, please write to us at sales@handsontable.com
+HyperFormula is available under two different licenses: GPLv3 and commercial. The commercial license can be purchased by [contacting our team](https://handsontable.com/get-a-quote) at Handsontable.
 
-## Copyrights
-© 2023 [Handsoncode](https://handsontable.com)
+Copyright (c) Handsoncode

docs/.vuepress/config.js

@@ -71,6 +71,8 @@ module.exports = {
         $page.version = HyperFormula.version
         // inject current HF buildDate as {{ $page.buildDate }} variable
         $page.buildDate = HyperFormula.buildDate
+        // inject current HF buildDate URI encoded as {{ $page.buildDateURIEncoded }} variable
+        $page.buildDateURIEncoded = encodeURIComponent(HyperFormula.buildDate)
         // inject current HF releaseDate as {{ $page.releaseDate }} variable
         $page.releaseDate = HyperFormula.releaseDate
         // inject current HF function count as {{ $page.functionsCount }} variable
@@ -138,21 +140,21 @@ module.exports = {
     sidebar: {
       '/api/': [
         {
-          title: 'Introduction',
+          title: 'API Reference Overview',
           path: '/api/',
         },
         {
-          title: 'HyperFormula Class',
+          title: 'HyperFormula',
           path: '/api/classes/hyperformula',
           collapsable: true,
         },
         {
-          title: 'Configuration Options',
+          title: 'ConfigParams ',
           path: '/api/interfaces/configparams',
           collapsable: true,
         },
         {
-          title: 'Event Types',
+          title: 'Listeners',
           path: '/api/interfaces/listeners',
           alias: '/api/events',
           collapsable: true,

docs/README.md

@@ -52,7 +52,7 @@ docs                            # All documentation files
 │   └── highlight.js            # Code highlight configuration
 ├── api                         # The API reference files, generated automatically from JsDoc. Do not edit!
 ├── guide                       # The docs source files: Markdown content
-├── api-template.md             # The API reference welcome page
+├── api-ref-readme.md           # The API reference welcome page
 ├── index.md                    # The main docs portal welcome page
 └── README.md                   # The file you're looking at right now!
 ```

docs/api-template.md renamed to docs/api-ref-readme.md

@@ -22,7 +22,7 @@ const sheetData = [
 const hfInstance = HyperFormula.buildFromArray(sheetData, options);
 ```
 
-#### Configuration Options
+#### ConfigParams
 This section contains information about options that allow you to configure the instance of HyperFormula.
 
 An example set of options:
@@ -34,7 +34,7 @@ const options = {
 };
 ```
 
-#### Event Types
+#### Listeners
 In this section, you can find information about all events you can subscribe to.
 
 For example, subscribing to `sheetAdded` event:

docs/guide/advanced-usage.md

@@ -122,8 +122,8 @@ console.log(winningTeam)
 ## Demo
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.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;"
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">

docs/guide/basic-operations.md

@@ -407,8 +407,8 @@ This demo presents several basic operations integrated with a
 sample UI.
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.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;"
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/basic-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">

docs/guide/basic-usage.md

@@ -65,9 +65,9 @@ works. It's time to move on to a more
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.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"
-     sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-   ></iframe>
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/basic-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
+</iframe>

docs/guide/batch-operations.md

@@ -124,8 +124,8 @@ The [paste](../api/classes/hyperformula.md#paste) method also can't be called wh
 ## Demo
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.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;"
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/batch-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">

docs/guide/clipboard-operations.md

@@ -113,8 +113,8 @@ Depending on what was cut, the data is stored as:
 ## Demo
 
 <iframe
-  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.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;"
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/clipboard-operations?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">

docs/guide/contact.md

@@ -10,7 +10,7 @@ We typically reply within a few hours during our working hours:
 
 Write to us at [sales@handsontable.com](mailto:sales@handsontable.com)
 or submit your inquiry through the
-[contact form](https://handsontable.com/contact?category=request_for_quotation).
+[contact form](https://handsontable.com/get-a-quote).
 
 ## Billing address
 

docs/guide/custom-functions.md

@@ -363,8 +363,8 @@ 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.6.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;"
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/custom-functions?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">

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

@@ -99,8 +99,8 @@ 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.6.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;"
+  :src="`https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.7.x/date-time?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview&v=${$page.buildDateURIEncoded}`"
+  style="width:100%; height:1070px; 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"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">