diff --git a/docz/docs/03-demos/02-frontend/02-react.md b/docz/docs/03-demos/02-frontend/02-react.md index 85a89fe..950f790 100644 --- a/docz/docs/03-demos/02-frontend/02-react.md +++ b/docz/docs/03-demos/02-frontend/02-react.md @@ -277,7 +277,7 @@ This complete component example fetches a test file and displays the contents in a HTML table. When the export button is clicked, a callback will export a file: ```jsx title="src/SheetJSReactAoO.js" -import { useCallback, useEffect, useState } from "react"; +import React, { useCallback, useEffect, useState } from "react"; import { read, utils, writeFileXLSX } from 'xlsx'; export default function SheetJSReactAoO() { @@ -287,14 +287,17 @@ export default function SheetJSReactAoO() { /* Fetch and update the state once */ useEffect(() => { (async() => { const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer(); + // highlight-start const wb = read(f); // parse the array buffer const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet const data = utils.sheet_to_json(ws); // generate objects setPres(data); // update state + // highlight-end })(); }, []); /* get state data and export to XLSX */ const exportFile = useCallback(() => { + // highlight-next-line const ws = utils.json_to_sheet(pres); const wb = utils.book_new(); utils.book_append_sheet(wb, ws, "Data"); @@ -303,10 +306,12 @@ export default function SheetJSReactAoO() { return ( { /* generate row for each president */ + // highlight-start pres.map((pres, index) => ()) + // highlight-end }
NameIndex
{pres.Name} {pres.Index}
@@ -358,7 +363,7 @@ and the page will attempt to download `SheetJSReactAoO.xlsx`. npm run build ``` -The generated site will be placed in the `.next` folder. +The generated site will be placed in the `dist` folder. 6) Start a local web server: @@ -382,9 +387,11 @@ This demo was tested in the following environments: ::: -:::caution +:::caution pass - CRA has known compatibility issues with React 19+[^cra]. CRA no longer receives updates and the ReactJS docs no longer recommend using CRA. For new projects, it is strongly recommended to use ViteJS with the react or react-ts templates. +CRA has known compatibility issues with React 19[^5]. CRA no longer receives +updates and the ReactJS docs no longer recommend using CRA. For new projects, it +is strongly recommended to use ViteJS with the `react` or `react-ts` templates. ::: @@ -400,7 +407,7 @@ npx -y create-react-app@5.0.1 --scripts-version=5.0.1 sheetjs-react {`\ cd sheetjs-react npm i -npm i react@18.2.0 react-dom@18.2.0 web-vitals --save --save-exact # fixes CRA dependency conflicts w/ React 19 +npm i react@18.2.0 react-dom@18.2.0 web-vitals --save --save-exact npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm start`} @@ -429,8 +436,6 @@ npx http-server build Access the displayed URL (typically `http://localhost:8080`) with a web browser and test the page. -[^cra]: See [Create React App Issue #13717](https://github.com/facebook/create-react-app/issues/13717) for details about React 19+ compatibility issues. - @@ -502,9 +507,17 @@ npm run dev`} 4) Replace `pages/index.tsx` with the `src/SheetJSReactAoO.js` example. -After replacing the code, add the following to the top of `pages/index.tsx`: +After replacing the code: -```js title="src/index.tsx (add to top)" +- uncomment the type hint in the `useState` function call: + +```js title="pages/index.tsx (uncomment the inline comment)" + const [pres, setPres] = useState([] as any[]); +``` + +- add the following to the top of `pages/index.tsx`: + +```js title="pages/index.tsx (add to top)" "use client"; ``` @@ -535,15 +548,13 @@ and the page will attempt to download `SheetJSReactAoO.xlsx`. npm run build ``` -The generated site will be placed in the `dist` folder. - 6) Start a local web server: ```bash npm run start ``` -Access the displayed URL (typically `http://localhost:8080`) with a web browser +Access the displayed URL (typically `http://localhost:3000`) with a web browser and test the page. @@ -559,11 +570,11 @@ will generate a workbook that can be opened in a spreadsheet editor. The main disadvantage of the Array of Objects approach is the specific nature of the columns. For more general use, passing around an Array of Arrays works. -However, this does not handle merge cells[^5] well! +However, this does not handle merge cells[^6] well! The [`sheet_to_html`](/docs/api/utilities/html#html-table-output) function generates HTML that is aware of merges and other worksheet features. ReactJS -`dangerouslySetInnerHTML`[^6] prop allows code to set the `innerHTML` attribute, +`dangerouslySetInnerHTML`[^7] prop allows code to set the `innerHTML` attribute, effectively inserting the code into the page. In this example, the component attaches a `ref` to the `DIV` container. During @@ -571,7 +582,7 @@ export, the first `TABLE` child element can be parsed with [`table_to_book`](/do generate a workbook object. ```jsx title="src/SheetJSReactHTML.js" -import { useCallback, useEffect, useRef, useState } from "react"; +import React, { useCallback, useEffect, useRef, useState } from "react"; import { read, utils, writeFileXLSX } from 'xlsx'; export default function SheetJSReactHTML() { @@ -676,9 +687,11 @@ This demo was tested in the following environments: ::: -:::caution +:::caution pass - CRA has known compatibility issues with React 19+[^cra]. CRA no longer receives updates and the ReactJS docs no longer recommend using CRA. For new projects, it is strongly recommended to use ViteJS with the react or react-ts templates. +CRA has known compatibility issues with React 19[^5]. CRA no longer receives +updates and the ReactJS docs no longer recommend using CRA. For new projects, it +is strongly recommended to use ViteJS with the `react` or `react-ts` templates. ::: @@ -693,7 +706,7 @@ npx -y create-react-app@5.0.1 --scripts-version=5.0.1 sheetjs-react {`\ cd sheetjs-react npm i -npm i react@18.2.0 react-dom@18.2.0 web-vitals --save --save-exact # fixes CRA dependency conflicts w/ React 19 +npm i react@18.2.0 react-dom@18.2.0 web-vitals --save --save-exact npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz npm start`} @@ -773,5 +786,6 @@ transpiled in the browser using Babel standalone library. [^2]: See [`useEffect`](https://react.dev/reference/react/useEffect) in the ReactJS documentation. [^3]: See [`useCallback`](https://react.dev/reference/react/useCallback) in the ReactJS documentation. [^4]: See [`useCallback`](https://react.dev/reference/react/useCallback) in the ReactJS documentation. -[^5]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details. -[^6]: [`dangerouslySetInnerHTML`](https://react.dev/reference/react-dom/components/common#common-props) is a ReactJS prop supported for all built-in components. +[^5]: See [Create React App Issue #13717](https://github.com/facebook/create-react-app/issues/13717) for details about React 19+ compatibility issues. +[^6]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details. +[^7]: [`dangerouslySetInnerHTML`](https://react.dev/reference/react-dom/components/common#common-props) is a ReactJS prop supported for all built-in components. diff --git a/docz/docs/03-demos/02-frontend/09-blazor.md b/docz/docs/03-demos/02-frontend/09-blazor.md index 10f9701..cfdef5e 100644 --- a/docz/docs/03-demos/02-frontend/09-blazor.md +++ b/docz/docs/03-demos/02-frontend/09-blazor.md @@ -268,7 +268,6 @@ If it has an `id`, JS code on the frontend can find the table element using the using the `table_to_book` method[^8] and exported with `writeFile`[^2]: {`\ -/* NOTE: blazor spreads the C# array, so the spread is required */ async function export_method() { const XLSX = await import("https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs"); const wb = XLSX.utils.table_to_book(document.getElementById("weather-table")); diff --git a/docz/docs/03-demos/23-data/16-postgresql.md b/docz/docs/03-demos/23-data/16-postgresql.md index 0115a05..0d209d3 100644 --- a/docz/docs/03-demos/23-data/16-postgresql.md +++ b/docz/docs/03-demos/23-data/16-postgresql.md @@ -37,7 +37,6 @@ This demo was tested in the following environments: | Postgres | Connector Library | Date | |:---------|:------------------|:-----------| | `16.6.1` | `pg` (`8.13.1`) | 2024-12-03 | -| `16.2.1` | `pg` (`8.11.4`) | 2024-03-31 | | `15.6` | `pg` (`8.11.4`) | 2024-03-31 | | `14.11` | `pg` (`8.11.4`) | 2024-03-31 | @@ -130,7 +129,8 @@ for(let row of aoo) { ### Creating a Table -The worksheet can be scanned to determine column names and types. With the names and types, a `CREATE TABLE` query can be written. +The worksheet can be scanned to determine column names and types. With the names +and types, a `CREATE TABLE` query can be written.
Implementation Details (click to show) @@ -291,6 +291,7 @@ Or, if you don't want/need a background service you can just run: ``` On Linux, install `postgresql` by running the following script: + ```bash echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list wget -qO - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - @@ -304,7 +305,7 @@ sudo -u postgres createuser -P $USER sudo -u postgres psql -c "ALTER USER $USER WITH SUPERUSER;" ``` -If running the optional user creation steps above, a PostgreSQL password will be required. [^69] +If running the optional user creation steps above, a PostgreSQL password will be required. [^8] Run the command to start a local database instance. @@ -314,12 +315,18 @@ Run the command to start a local database instance. ```bash dropdb SheetJSPG +``` -# Ubuntu/Debian +:::caution pass + +Some Linux installations do not create the `dropdb` command. The command can be +run through the `postgres` command-line tool: + +```bash title="dropdb in Ubuntu/Debian" sudo -i -u postgres dropdb SheetJSPG ``` -[^69]: PostgreSQL on Linux uses [SCRAM authentication by default, which requires a password](https://www.postgresql.org/docs/current/auth-password.html) +::: :::info pass @@ -334,15 +341,35 @@ current user, command-line flags can override the defaults. ::: +:::note pass + +If the database does not exist, the command will fail with the following error: + +``` +dropdb: error: database removal failed: ERROR: database "SheetJSPG" does not exist +``` + +This error can be safely ignored. + +::: + 2) Create an empty `SheetJSPG` database using the `createdb` command: ```bash createdb SheetJSPG +``` -# Ubuntu/Debian +:::caution pass + +Some Linux installations do not create the `createdb` command. The command can be +run through the `postgres` command-line tool: + +```bash title="createdb in Ubuntu/Debian" sudo -i -u postgres createdb SheetJSPG ``` +::: + :::note pass `createdb` supports the same `-h`, `-p`, and `-U` flags as `dropdb`. @@ -509,4 +536,5 @@ psql SheetJSPG -c 'SELECT * FROM "Presidents";' [^4]: See ["Workbook Helpers" in "Utilities"](/docs/api/utilities/wb) for details on `book_new` and `book_append_sheet`. [^5]: See [`writeFile` in "Writing Files"](/docs/api/write-options) [^6]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output) -[^7]: The [`pg-format`](https://npm.im/pg-format) package is available on the public NPM registry. Even though the project is marked as deprecated, the official [`pg` website still recommends `pg-format`](https://node-postgres.com/features/queries#parameterized-query:~:text=use%20pg%2Dformat%20package%20for%20handling%20escaping) \ No newline at end of file +[^7]: The [`pg-format`](https://npm.im/pg-format) package is available on the public NPM registry. Even though the project is marked as deprecated, the official [`pg` website still recommends `pg-format`](https://node-postgres.com/features/queries#parameterized-query:~:text=use%20pg%2Dformat%20package%20for%20handling%20escaping) +[^8]: PostgreSQL on Linux uses [SCRAM authentication by default, which requires a password](https://www.postgresql.org/docs/current/auth-password.html) \ No newline at end of file diff --git a/docz/docs/03-demos/30-cloud/02-netsuite.md b/docz/docs/03-demos/30-cloud/02-netsuite.md index d7dd1dd..96e6bc8 100644 --- a/docz/docs/03-demos/30-cloud/02-netsuite.md +++ b/docz/docs/03-demos/30-cloud/02-netsuite.md @@ -71,7 +71,7 @@ absolute or relative[^4]. :::note pass -On older versions of SuiteScript, you might need to use without `.js` extension. +In older versions of SuiteScript, references should omit the `.js` extension. ::: @@ -88,7 +88,7 @@ top-level directory, the config should use `"/SuiteScripts/xlsx.full.min.js"`: ``` Relative references are also supported. If the entire project is stored in one -folder, the config can use `"./xlsx.full.min"`: +folder, the config can use `"./xlsx.full.min.js"`: ```json title="JsLibraryConfig.json" { diff --git a/docz/docs/03-demos/32-extensions/10-stata.md b/docz/docs/03-demos/32-extensions/10-stata.md index b92e058..dd64ff4 100644 --- a/docz/docs/03-demos/32-extensions/10-stata.md +++ b/docz/docs/03-demos/32-extensions/10-stata.md @@ -49,13 +49,15 @@ This demo covers Stata extensions. For directly processing Stata DTA files, the :::note Tested Deployments -This demo was tested by SheetJS users in the following deployments: +This demo was tested in the following deployments: -| Architecture | Date | -|:-------------|:-----------| -| `darwin-x64` | 2024-04-10 | -| `win10-x64` | 2024-04-10 | -| `linux-x64` | 2024-04-25 | +| Architecture | Version | Date | +|:-------------|:------------------|:-----------| +| `darwin-x64` | `18.0` | 2024-04-10 | +| `darwin-arm` | `18.5` (StataNow) | 2024-12-15 | +| `win10-x64` | `18.0` | 2024-04-10 | +| `win11-arm` | `18.5` (StataNow) | 2024-12-15 | +| `linux-x64` | `18.0` | 2024-04-25 | ::: diff --git a/docz/docs/03-demos/42-engines/02-v8.md b/docz/docs/03-demos/42-engines/02-v8.md index ca63d1b..ca43201 100644 --- a/docz/docs/03-demos/42-engines/02-v8.md +++ b/docz/docs/03-demos/42-engines/02-v8.md @@ -146,7 +146,7 @@ This demo was tested in the following deployments: | V8 Version | Platform | OS Version | Compiler | Date | |:--------------|:-------------|:--------------|:-----------------|:-----------| -| `12.4.253` | `darwin-x64` | macOS 14.4 | `clang 15.0.0` | 2024-03-15 | +| `13.3.228` | `darwin-x64` | macOS 15.1.1 | `clang 16.0.0` | 2024-12-03 | | `12.7.130` | `darwin-arm` | macOS 14.5 | `clang 15.0.0` | 2024-05-25 | | `12.5.48` | `win10-x64` | Windows 10 | `CL 19.39.33523` | 2024-03-24 | | `12.5.48` | `linux-x64` | HoloOS 3.5.17 | `gcc 13.1.1` | 2024-03-21 | @@ -243,6 +243,7 @@ git config --global branch.autosetuprebase always ```bash +rm -rf depot_tools git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git ``` @@ -428,11 +429,11 @@ The recommended fix is to delete the referenced folder and re-run `gclient sync` -5) Checkout the desired version. The following command pulls `12.7.130`: +5) Checkout the desired version. The following command pulls `13.3.228`: ```bash -git checkout tags/12.7.130 -b sample +git checkout tags/13.3.228 -b sample ``` :::caution pass @@ -440,14 +441,14 @@ git checkout tags/12.7.130 -b sample The official documentation recommends: ```bash -git checkout refs/tags/12.7.130 -b sample -t +git checkout refs/tags/13.3.228 -b sample -t ``` This command failed in local testing: ``` -E:\v8\v8>git checkout refs/tags/12.7.130 -b sample -t -fatal: cannot set up tracking information; starting point 'refs/tags/12.7.130' is not a branch +E:\v8\v8>git checkout refs/tags/13.3.228 -b sample -t +fatal: cannot set up tracking information; starting point 'refs/tags/13.3.228' is not a branch ``` ::: @@ -464,6 +465,33 @@ tools/dev/v8gen.py x64.release.sample ninja -C out.gn/x64.release.sample v8_monolith ``` +:::danger pass + +**This does not work in newer Python releases due to a breaking change!** + +Python 3.13 removed the `pipes` module from the standard library[^9]. `v8gen.py` +will fail on newer Python releases with the following traceback: + +``` +Traceback (most recent call last): + File "/Users/sheetjs/dev/v8/v8/tools/dev/v8gen.py", line 53, in + import mb + File "/Users/sheetjs/dev/v8/v8/tools/mb/mb.py", line 21, in + import pipes +ModuleNotFoundError: No module named 'pipes' +``` + +The recommended workaround is to use Homebrew to install and use Python 3.12: + +```bash +brew install python@3.12 +export PATH="$(brew --prefix)/opt/python@3.12/libexec/bin:$PATH" +``` + +After applying the workaround, the build commands will run. + +::: + @@ -618,7 +646,7 @@ ninja -C out.gn\x64.release.sample v8_monolith ```bash g++ -I. -Iinclude samples/hello-world.cc -o hello_world -fno-rtti -lv8_monolith \ -ldl -Lout.gn/x64.release.sample/obj/ -pthread \ - -std=c++17 -DV8_COMPRESS_POINTERS=1 -DV8_ENABLE_SANDBOX + -std=c++20 -DV8_COMPRESS_POINTERS=1 -DV8_ENABLE_SANDBOX ./hello_world ``` @@ -630,7 +658,7 @@ Linking against `libv8_libbase` or `libv8_libplatform` in V8 version `12.4.253` elicited linker errors: ``` -ld: multiple errors: unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' +ld: multiple errors: unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' ``` ::: @@ -653,7 +681,7 @@ Linking against `libv8_libbase` or `libv8_libplatform` in V8 version `12.4.253` elicited linker errors: ``` -ld: multiple errors: unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' +ld: multiple errors: unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' ``` ::: @@ -780,7 +808,7 @@ copy E:\v8\v8\samples\hello-world.cc .\ ```bash g++ -I. -Iinclude hello-world.cc -o hello_world -fno-rtti -lv8_monolith \ - -lv8_libbase -lv8_libplatform -ldl -Lobj/ -pthread -std=c++17 \ + -lv8_libbase -lv8_libplatform -ldl -Lobj/ -pthread -std=c++20 \ -DV8_COMPRESS_POINTERS=1 -DV8_ENABLE_SANDBOX ./hello_world ``` @@ -790,14 +818,14 @@ g++ -I. -Iinclude hello-world.cc -o hello_world -fno-rtti -lv8_monolith \ In some V8 versions, the command failed in the linker stage: ``` -ld: multiple errors: unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' +ld: multiple errors: unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' ``` The build succeeds after removing `libv8_libbase` and `libv8_libplatform`: ```bash g++ -I. -Iinclude hello-world.cc -o hello_world -fno-rtti -lv8_monolith \ - -ldl -Lobj/ -pthread -std=c++17 \ + -ldl -Lobj/ -pthread -std=c++20 \ -DV8_COMPRESS_POINTERS=1 -DV8_ENABLE_SANDBOX ./hello_world ``` @@ -843,7 +871,7 @@ curl -LO https://docs.sheetjs.com/v8/sheetjs.v8.cc ```bash g++ -I. -Iinclude sheetjs.v8.cc -o sheetjs.v8 -fno-rtti -lv8_monolith \ - -lv8_libbase -lv8_libplatform -ldl -Lobj/ -pthread -std=c++17 \ + -lv8_libbase -lv8_libplatform -ldl -Lobj/ -pthread -std=c++20 \ -DV8_COMPRESS_POINTERS=1 -DV8_ENABLE_SANDBOX ``` @@ -852,14 +880,14 @@ g++ -I. -Iinclude sheetjs.v8.cc -o sheetjs.v8 -fno-rtti -lv8_monolith \ In some V8 versions, the command failed in the linker stage: ``` -ld: multiple errors: unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/test/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' +ld: multiple errors: unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libplatform.a'; unknown file type in '/Users/sheetjs/dev/v8/v8/out.gn/x64.release.sample/obj/libv8_libbase.a' ``` The build succeeds after removing `libv8_libbase` and `libv8_libplatform`: ```bash g++ -I. -Iinclude sheetjs.v8.cc -o sheetjs.v8 -fno-rtti -lv8_monolith \ - -ldl -Lobj/ -pthread -std=c++17 \ + -ldl -Lobj/ -pthread -std=c++20 \ -DV8_COMPRESS_POINTERS=1 -DV8_ENABLE_SANDBOX ``` @@ -1555,4 +1583,5 @@ mv target/release/sheet2csv.exe . [^5]: See ["Supported Output Formats" type in "Writing Files"](/docs/api/write-options#supported-output-formats) [^6]: The project does not have an official website. The [official Rust crate](https://crates.io/crates/v8) is hosted on `crates.io`. [^7]: The project does not have a separate website. The source repository is hosted on [GitHub](https://github.com/cloudflare/stpyv8) -[^8]: According to a maintainer, [typed arrays were not supported in the original `pyv8` project](https://github.com/cloudflare/stpyv8/issues/104#issuecomment-2059125389) \ No newline at end of file +[^8]: According to a maintainer, [typed arrays were not supported in the original `pyv8` project](https://github.com/cloudflare/stpyv8/issues/104#issuecomment-2059125389) +[^9]: `pipes` and other modules were removed from the standard library in Python 3.13 as part of ["PEP 594"](https://docs.python.org/3/whatsnew/3.13.html#whatsnew313-pep594). \ No newline at end of file