TS code examples (#10990)

* SPIKE - add script that compiles an example TS file to JS

* Adjust the start script to make it work in Windows env

* Extend the base eslintrc in the eslintrc for example files

* Add a bash script that generates the JS files for all the TS example files

* Add generate-js-examples step to the npm scripts

* Make the generate-js-examples script apply only for the vanilla js examples

* Renamed all js examples to *.ts without changing the content

* Add typings for data array in the examples (array of arrays)

* Add typings for HOT instance in all TS examples

* Add typings for data array in the examples (array of objects)

* Improve reporting in the generate-js-examples script

* Add typings for the HOT instance in the examples

* Improve typings in docs/content/guides/accessories-and-menus/context-menu/javascript/example3.ts

* Improve typings in docs/content/guides/accessories-and-menus/export-to-csv/javascript/example1.ts

* Add typing for .getPlugin statements

* Change typing for HOT instance from Handsontable to Core

* Add typings for custom renderers in the ts examples

* Add missing import statements

* Improve typings for arrays

* replace Core type

* add lint rules

* update lint

* update ts examples

* Newline at the end of file gitignore

* Remove unused vars in docs/content/guides/getting-started

* Remove unused 'const hot' variables

* Fix type error for html containers for the HOT instance

* Fix typings in docs/content/guides/rows/row-prepopulating/javascript/example1.ts

* Make all HOT instances variables names consistently 'hot'

* Improve typings in docs/content/guides/getting-started/binding-to-data

* add ts fixes and cleanup

* Improve typings for cells() function in HOT configuration

* Fix docs/content/guides/columns/column-filter/javascript/exampleFilterDifferentTypes.ts

* Fix typings for docs/content/guides/getting-started/demo/javascript/example.ts

* Fix type-null-checking in HTML elements

* fix example

* Fix typing for HTMLInputElement vars

* Fix docs/content/guides/optimization/batch-operations/javascript/example1.ts

* Fix typings in dir  docs/content/guides/cell-functions

* Fix typings in dir docs/content/guides/columns

* Fix typings in dir docs/content/guides/cell-features

* Fix typings in dir docs/content/guides/cell-types

* Fix typings in dir docs/content/guides/formulas

* Fix typings in dir docs/content/guides/navigation

* Fix typings in dir docs/content/guides/accessories-and-menus

* Improve typings for docs/content/guides/getting-started/binding-to-data/javascript/example4.ts

* Revert unnecessary changes

* Revert unnecessary changes

* Make generate-js-examples script re-generate files even when exist

* Make sure generate-js-examples.sh is run in bash shell

* Remove generate-js-examples script from the docs:start pipeline

* Make generate-js-examples script run jobs in parallel to speed things up

* Improve the dev experience with the generate-js-examples script

* Fix merge errors

* Fix merge errors

* Make generat-js-examples script work in zsh env (MacOS)

* Fix/docs visual cache logic (#11014)

* make sure we evaluate the cache restore properly

* build and serve for visual tests

* increase timeout

* fix lock

* resolve docs lock

* update locks

---------

Co-authored-by: adrianspdev <adrian.dusinkiewicz@soppo.team>
Co-authored-by: Maciej Giergiczny <maciej.giergiczny@handsontable.com>
Co-authored-by: Evan Seaward <seaward.evan@gmail.com>

.github/workflows/docs-visual-tests.yml

@@ -25,7 +25,7 @@ defaults:
 jobs:
   run-tests:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     env: # Or as an environment variable
       PASS_COOKIE: ${{ secrets.PassCookie }}
     steps:
@@ -55,6 +55,11 @@ jobs:
         if: ${{inputs.test_env == 'http://localhost:8080/docs'}} 
         run: |
           npm run docs:api
+      
+      - name: Build documentation
+        if: ${{inputs.test_env == 'http://localhost:8080/docs'}} 
+        run: |
+          npm run docs:build       
 
       - name: Set up cache
         id: cache
@@ -63,13 +68,22 @@ jobs:
           key: plawyright-cache/${{github.repository}}/${{github.ref}}
           restore-keys: plawyright-cache/${{github.repository}}/refs/heads/develop
           path: '**/test-artifacts/**'
-
+
+      - name: Check if cache was restored
+        id: check-cache
+        run: |
+          if [[ -n "$(find . -name 'test-artifacts' -type d -not -path '*/node_modules/*' -print0 | xargs -0 -I {} find {} -type f -print -quit)" ]]; then
+            echo "cache-restored=true" >> $GITHUB_ENV
+          else
+            echo "cache-restored=false" >> $GITHUB_ENV
+          fi
+
       - name: Initialize snapshots
-        if: ${{steps.cache.outputs.cache-hit != 'true' || inputs.update-snapshots == 'true'}}
+        if: ${{env.cache-restored != 'true' || github.event.inputs.update-snapshots == 'true'}}
         run: BASE_URL=${{ inputs.test_env }} npx playwright test --update-snapshots
 
       - name: Test
-        if: ${{steps.cache.outputs.cache-hit == 'true' || inputs.update-snapshots != 'true'}}
+        if: ${{env.cache-restored == 'true' || github.event.inputs.update-snapshots != 'true'}}
         run: BASE_URL=${{ inputs.test_env }} npx playwright test
 
       - name: Upload test report

docs/.eslintrc.js

@@ -5,7 +5,10 @@ module.exports = {
     parser: 'babel-eslint',
     sourceType: 'module'
   },
-  ignorePatterns: ['**/guides/**/*.js'],
+  ignorePatterns: [
+    '**/guides/**/*.js',
+    '**/guides/**/*.ts'
+  ],
   rules: {
     'no-restricted-globals': 'off',
     'import/no-unresolved': 'off'

docs/.gitignore

@@ -31,3 +31,4 @@ report-check-links.xlsx
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+/content/guides/**/javascript/**/*.js

docs/.vuepress/tools/generate-js-examples.sh

@@ -0,0 +1,34 @@
+ #!/usr/bin/bash
+
+# This script generates the JS files for all the TS code examples. It skips the examples that already have a JS file.
+
+jobs_limit=16
+
+generate_single_file() {
+  ts_filename="$1"
+  js_filename="${ts_filename%.*}.js"
+
+  tsc --target esnext --skipLibCheck $ts_filename > /dev/null
+
+  if [ -f "$js_filename" ]; then
+    eslint --fix --no-ignore -c eslintrc.examples.js $js_filename > /dev/null
+    echo "Generated $js_filename"
+  else
+    echo "Failed to generate $js_filename"
+  fi
+}
+
+echo "Running $jobs_limit jobs in parallel..."
+
+find content/guides -wholename "*/javascript/*.ts" -print0 | while read -d $'\0' ts_filename; do
+  while test "$(jobs | wc -l)" -ge "$jobs_limit"; do
+    sleep 1
+  done
+
+  generate_single_file "$ts_filename" &
+done
+
+wait
+echo "Waiting for the result of all jobs..."
+sleep 20
+echo "All jobs finished"

docs/content/guides/accessibility/accessibility/javascript/example1.js → docs/content/guides/accessibility/accessibility/javascript/example1.ts

@@ -1,7 +1,19 @@
 import Handsontable from 'handsontable';
 import 'handsontable/dist/handsontable.full.min.css';
+
+/* start:skip-in-preview */
+interface Product {
+  companyName: string;
+  productName: string;
+  sellDate: string;
+  inStock: boolean;
+  qty: number;
+  orderId: string;
+  country: string;
+}
+
 /* start:skip-in-preview */
-const data = [
+const data: Product[] = [
   {
     companyName: 'Hodkiewicz - Hintz',
     productName: 'Rustic Soft Ball',
@@ -463,7 +475,7 @@ const data = [
   },
 ];
 
-const countries = data.reduce((acc, curr) => {
+const countries = data.reduce<string[]>((acc, curr) => {
   if (acc.includes(curr.country)) {
     return acc;
   }
@@ -474,10 +486,10 @@ const countries = data.reduce((acc, curr) => {
 /* end:skip-in-preview */
 
 // Get the DOM element with the ID 'example1' where the Handsontable will be rendered
-const app = document.getElementById('example1');
+const app = document.getElementById('example1')!;
 
 // Define configuration options for the Handsontable
-const hotOptions = {
+const hotOptions: Handsontable.GridSettings = {
   data,
   height: 464,
   colWidths: [140, 165, 100, 100, 100, 110, 178],
@@ -533,116 +545,116 @@ const hotOptions = {
 };
 
 // Initialize the Handsontable instance with the specified configuration options
-let hotInstance = new Handsontable(app, hotOptions);
+let hot = new Handsontable(app, hotOptions);
 
 // Helper function to set up checkbox event handling
-const setupCheckbox = (element, callback) =>
-  element.addEventListener('click', clickEvent => callback(element.checked));
+const setupCheckbox = (element: HTMLInputElement, callback: (val: boolean) => void) =>
+  element.addEventListener('click', () => callback(element.checked));
 
 // Set up event listeners for various checkboxes to update Handsontable settings.
 // This allows us to change the Handsontable settings from the UI, showcasing
 // the flexibility of Handsontable in configuring according to your needs.
 
 // Checkbox: Enable/Disable Tab Navigation
-setupCheckbox(document.querySelector('#enable-tab-navigation'), (checked) => {
+setupCheckbox(document.querySelector('#enable-tab-navigation') as HTMLInputElement, (checked) => {
   hotOptions.tabNavigation = checked;
-  hotInstance.updateSettings({
+  hot.updateSettings({
     tabNavigation: hotOptions.tabNavigation,
   });
   console.log(
     'Updated setting: tabNavigation to',
-    hotInstance.getSettings().tabNavigation
+    hot.getSettings().tabNavigation
   );
 });
 
 // Checkbox: Enable/Disable Header Navigation
 setupCheckbox(
-  document.querySelector('#enable-header-navigation'),
+  document.querySelector('#enable-header-navigation') as HTMLInputElement,
   (checked) => {
     hotOptions.navigableHeaders = checked;
-    hotInstance.updateSettings({
+    hot.updateSettings({
       navigableHeaders: hotOptions.navigableHeaders,
     });
     console.log(
       'Updated setting: navigableHeaders to',
-      hotInstance.getSettings().navigableHeaders
+      hot.getSettings().navigableHeaders
     );
   }
 );
 
 // Checkbox: Enable/Disable Cell Virtualization
 setupCheckbox(
-  document.querySelector('#enable-cell-virtualization'),
+  document.querySelector('#enable-cell-virtualization') as HTMLInputElement,
   (checked) => {
-    hotInstance.destroy();
-    hotInstance = new Handsontable(document.getElementById('example1'), {
+    hot.destroy();
+    hot = new Handsontable(document.getElementById('example1')!, {
       ...hotOptions,
       renderAllRows: !checked,
       renderAllColumns: !checked,
     });
     console.log('Updated virtualization settings:', {
-      renderAllRows: hotInstance.getSettings().renderAllRows,
-      renderAllColumns: hotInstance.getSettings().renderAllColumns,
+      renderAllRows: hot.getSettings().renderAllRows,
+      renderAllColumns: hot.getSettings().renderAllColumns,
     });
   }
 );
 
 // Checkbox: Enable/Disable Cell Enter Editing
 setupCheckbox(
-  document.querySelector('#enable-cell-enter-editing'),
+  document.querySelector('#enable-cell-enter-editing') as HTMLInputElement,
   (checked) => {
     hotOptions.enterBeginsEditing = checked;
-    hotInstance.updateSettings({
+    hot.updateSettings({
       enterBeginsEditing: hotOptions.enterBeginsEditing,
     });
     console.log(
       'Updated setting: enable-cell-enter-editing to',
-      hotInstance.getSettings().enterBeginsEditing
+      hot.getSettings().enterBeginsEditing
     );
   }
 );
 
 // Checkbox: Enable/Disable Arrow Navigation for First/Last Row
 setupCheckbox(
-  document.querySelector('#enable-arrow-rl-first-last-column'),
+  document.querySelector('#enable-arrow-rl-first-last-column') as HTMLInputElement,
   (checked) => {
     hotOptions.autoWrapRow = checked;
-    hotInstance.updateSettings({
+    hot.updateSettings({
       autoWrapRow: hotOptions.autoWrapRow,
     });
     console.log(
       'Updated setting: autoWrapRow to',
-      hotInstance.getSettings().autoWrapRow
+      hot.getSettings().autoWrapRow
     );
   }
 );
 
 // Checkbox: Enable/Disable Arrow Navigation for First/Last Column
 setupCheckbox(
-  document.querySelector('#enable-arrow-td-first-last-column'),
+  document.querySelector('#enable-arrow-td-first-last-column') as HTMLInputElement,
   (checked) => {
     hotOptions.autoWrapCol = checked;
-    hotInstance.updateSettings({
+    hot.updateSettings({
       autoWrapCol: hotOptions.autoWrapCol,
     });
     console.log(
       'Updated setting: autoWrapCol to',
-      hotInstance.getSettings().autoWrapCol
+      hot.getSettings().autoWrapCol
     );
   }
 );
 
 // Checkbox: Enable/Disable Enter Key Focus for Editing
 setupCheckbox(
-  document.querySelector('#enable-enter-focus-editing'),
+  document.querySelector('#enable-enter-focus-editing') as HTMLInputElement,
   (checked) => {
     hotOptions.enterMoves = checked ? { col: 0, row: 1 } : { col: 0, row: 0 };
-    hotInstance.updateSettings({
+    hot.updateSettings({
       enterMoves: hotOptions.enterMoves,
     });
     console.log(
       'Updated setting: enterMoves to',
-      hotInstance.getSettings().enterMoves
+      hot.getSettings().enterMoves
     );
   }
 );

docs/content/guides/accessories-and-menus/context-menu/javascript/example1.js → docs/content/guides/accessories-and-menus/context-menu/javascript/example1.ts

@@ -1,8 +1,9 @@
 import Handsontable from 'handsontable';
 import 'handsontable/dist/handsontable.full.min.css';
 
-const container = document.querySelector('#example1');
-const hot = new Handsontable(container, {
+const container = document.querySelector('#example1')!;
+
+new Handsontable(container, {
   data: [
     ['', 'Tesla', 'Nissan', 'Toyota', 'Honda', 'Mazda', 'Ford'],
     ['2017', 10, 11, 12, 13, 15, 16],

docs/content/guides/accessories-and-menus/context-menu/javascript/example2.js → docs/content/guides/accessories-and-menus/context-menu/javascript/example2.ts

@@ -1,8 +1,9 @@
 import Handsontable from 'handsontable';
 import 'handsontable/dist/handsontable.full.min.css';
 
-const container = document.querySelector('#example2');
-const hot = new Handsontable(container, {
+const container = document.querySelector('#example2')!;
+
+new Handsontable(container, {
   data: [
     ['', 'Tesla', 'Nissan', 'Toyota', 'Honda', 'Mazda', 'Ford'],
     ['2017', 10, 11, 12, 13, 15, 16],