diff --git a/docz/docs/02-getting-started/01-installation/01-standalone.md b/docz/docs/02-getting-started/01-installation/01-standalone.md index 50a8897..4e3e55e 100644 --- a/docz/docs/02-getting-started/01-installation/01-standalone.md +++ b/docz/docs/02-getting-started/01-installation/01-standalone.md @@ -118,20 +118,20 @@ importScripts("https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.mi ### Type Checker -:::danger VSCode Telemetry and Data Exfiltration +:::danger VS Code Telemetry and Data Exfiltration -The official Microsoft builds of Visual Studio Code ("VSCode") embed telemetry -and send information to external servers. +The official builds of Visual Studio Code ("VS Code" or "VSCode") embed +telemetry and send information to Microsoft servers. -**[VSCodium](https://vscodium.com/) is a telemetry-free fork of VSCode.** +**[VSCodium](https://vscodium.com/) is a telemetry-free fork of VS Code.** When writing code that may process personally identifiable information (PII), -the SheetJS team strongly encourages building VSCode from source or using IDEs +the SheetJS team strongly encourages building VS Code from source or using IDEs that do not exfiltrate data. ::: -The type checker integrated in VSCodium and VSCode does not currently provide +The type checker integrated in VSCodium and VS Code does not currently provide type hints when using the standalone build. Using the JSDoc `@type` directive coupled with type imports, VSCodium will recognize the types: @@ -176,7 +176,7 @@ The `.d.ts` file extension must be omitted. JSDoc types using the `@import` directive are not supported in ` + +``` + +6) Refresh the browser window. This page should now display an HTML table. + 7) Stop the server (press CTRL+C in the terminal window). 8) Build the static site: ```bash -npx -y yarn run generate +npx -y pnpm run generate ``` This will create a static site in `.output/public`, which can be served with: diff --git a/docz/docs/03-demos/30-cloud/21-gsheet.md b/docz/docs/03-demos/30-cloud/21-gsheet.md index 1e0901d..17c8f5b 100644 --- a/docz/docs/03-demos/30-cloud/21-gsheet.md +++ b/docz/docs/03-demos/30-cloud/21-gsheet.md @@ -111,6 +111,7 @@ const jwt = new google.auth.JWT({ key: creds.private_key, scopes: [ 'https://www.googleapis.com/auth/spreadsheets', // Google Sheets + 'https://www.googleapis.com/auth/drive', // Google Drive 'https://www.googleapis.com/auth/drive.file', // Google Drive ] }); @@ -495,7 +496,7 @@ At this point `wb` is a SheetJS workbook object[^10]. :::note Tested Deployments -This demo was last tested on 2024-06-08 using `googleapis` version `140.0.0`. +This demo was last tested on 2025-05-14 using `googleapis` version `148.0.0`. The demo uses Sheets v4 and Drive v3 APIs. ::: @@ -551,10 +552,10 @@ be a selection box. Click the `▼` icon to show the modal. If the selection box is missing, expand the browser window. -3) Click "NEW PROJECT" in the top right corner of the modal. +3) Click "New project" in the top right corner of the modal. 4) In the New Project screen, enter "SheetJS Test" in the Project name textbox -and select "No organization" in the Location box. Click "CREATE". +and select "No organization" in the Location box. Click "Create". A notification will confirm that the project was created: @@ -569,14 +570,13 @@ The goal of this section is to enable Google Sheets API and Google Drive API. ::: -5) Open the Project Selector (`▼` icon) and select "SheetJS Test" +5) Click "Select a project" and select "SheetJS Test" from the Recent tab. -6) In the search bar, type "Enabled" and select "Enabled APIs & services". This -item will be in the "PRODUCTS & PAGES" part of the search results. +6) In the search bar, type "Enabled" and select "Enabled APIs & services". #### Enable Google Sheets API -7) Near the top of the page, click "+ ENABLE APIS AND SERVICES". +7) Near the top of the page, click "+ Enable APIs and services". 8) In the search bar near the middle of the page (not the search bar at the top), type "Sheets" and press Enter. @@ -585,11 +585,11 @@ In the results page, look for "Google Sheets API". Click the card 9) In the Product Details screen, click the blue "ENABLE" button. -10) Click the left arrow (`<-`) next to "API/Service details". +10) Click the left arrow (`<-`) next to "API/Service Details". #### Enable Google Drive API -11) Near the top of the page, click "+ ENABLE APIS AND SERVICES". +11) Near the top of the page, click "+ Enable APIs and services". 12) In the search bar near the middle of the page (not the search bar at the top), type "Drive" and press Enter. @@ -614,13 +614,13 @@ the top bar. 15) Click the Project Selector (`:·` icon) and select "SheetJS Test". 16) In the search bar, type "Credentials" and select the "Credentials" item with -subtitle "APIs & Services". This item will be in the "PRODUCTS & PAGES" group: +subtitle "APIs & Services": ![Credentials](pathname:///gsheet/creds.png) -17) Click "+ CREATE CREDENTIALS". In the dropdown, select "Service Account" +17) Click "+ Create credentials". In the dropdown, select "Service account" -18) Enter "SheetJService" for Service account name. Click "CREATE AND CONTINUE" +18) Enter "SheetJService" for Service account name. Click "Create and continue". :::note pass @@ -628,24 +628,24 @@ The Service account ID is generated automatically. ::: -19) In Step 2 "Grant this service account access to project", click CONTINUE +19) In Step 2 "Grant this service account access to project", click Continue. -20) In Step 3 click "DONE". You will be taken back to the credentials screen +20) In Step 3 click "Done". You will be taken back to the credentials screen #### Create JSON Key 21) Look for "SheetJService" in the "Service Accounts" table and click the email address in the row. -22) Click "KEYS" in the horizontal bar near the top of the page. +22) Click "Keys" in the horizontal bar near the top of the page. -23) Click "ADD KEY" and select "Create new key" in the dropdown. +23) Click "Add key" and select "Create new key" in the dropdown. -24) In the popup, select the "JSON" radio button and click "CREATE". +24) In the popup, select the "JSON" radio button and click "Create". The page will download a JSON file. If prompted, allow the download. -25) Click "CLOSE" +25) Click "Close" ### Create Document @@ -675,7 +675,7 @@ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz googlea 29) Download [`init.mjs`](pathname:///gsheet/init.mjs): ```bash -curl -LO https://docs.sheetjs.com/gsheet/init.mjs +curl -o init.mjs https://docs.sheetjs.com/gsheet/init.mjs ``` Edit the marked lines near the top of the file: @@ -713,11 +713,12 @@ Shared a-long-string-of-characters with YOUR_ACCOUNT@gmail.com The long string of characters after "Created Google Workbook" is the ID. Take note of this ID. -31) Sign into Google Sheets. A shared document "SheetJS Test" should be -displayed in the table. It will be owned by the service account. +31) Sign into Google Drive and select "Shared with me" from the left sidebar. A +shared document "SheetJS Test" should be displayed in the table. It will be +owned by the service account. -32) Open the shared document from step 31 and confirm that the document has two -worksheets named "SheetJS1" and "SheetJS2". +32) Click `⋮` next to "SheetJS Test" and select "Open with" > "Google Sheets". +Confirm that the document has two worksheets named "SheetJS1" and "SheetJS2". Confirm the worksheet data matches the following screenshots: @@ -786,13 +787,13 @@ NUMBERS file. 34) Download the [test file `pres.numbers`](https://docs.sheetjs.com/pres.numbers): ```bash -curl -LO https://docs.sheetjs.com/pres.numbers +curl -o pres.numbers https://docs.sheetjs.com/pres.numbers ``` 35) Download [`load.mjs`](pathname:///gsheet/load.mjs): ```bash -curl -LO https://docs.sheetjs.com/gsheet/load.mjs +curl -o load.mjs https://docs.sheetjs.com/gsheet/load.mjs ``` Edit the marked lines near the top of the file: @@ -830,7 +831,7 @@ The goal of this section is to export the raw data from Google Sheets to XLSB. 38) Download [`dump.mjs`](pathname:///gsheet/dump.mjs): ```bash -curl -LO https://docs.sheetjs.com/gsheet/dump.mjs +curl -o dump.mjs https://docs.sheetjs.com/gsheet/dump.mjs ``` Edit the marked lines near the top of the file: @@ -876,7 +877,7 @@ assign a grid of values 43) Download [`raw.mjs`](pathname:///gsheet/raw.mjs): ```bash -curl -LO https://docs.sheetjs.com/gsheet/raw.mjs +curl -o raw.mjs https://docs.sheetjs.com/gsheet/raw.mjs ``` Edit the marked lines near the top of the file: diff --git a/docz/docs/03-demos/30-cloud/31-dropbox.md b/docz/docs/03-demos/30-cloud/31-dropbox.md index 43f4521..e4f9d57 100644 --- a/docz/docs/03-demos/30-cloud/31-dropbox.md +++ b/docz/docs/03-demos/30-cloud/31-dropbox.md @@ -266,7 +266,7 @@ function SheetJSEnregistrez() { :::note Tested Deployments -This demo was last tested on 2024-05-27. +This demo was last tested on 2025-05-14. ::: diff --git a/docz/docs/03-demos/32-extensions/42-vs-code.md b/docz/docs/03-demos/32-extensions/05-vscode.md similarity index 62% rename from docz/docs/03-demos/32-extensions/42-vs-code.md rename to docz/docs/03-demos/32-extensions/05-vscode.md index 17b06b8..e6db976 100644 --- a/docz/docs/03-demos/32-extensions/42-vs-code.md +++ b/docz/docs/03-demos/32-extensions/05-vscode.md @@ -1,5 +1,5 @@ --- -title: Excel Viewer in Visual Studio Code +title: Visualizing Data in VS Code sidebar_label: Visual Studio Code description: View Excel files directly in VS Code. Seamlessly browse spreadsheet data without leaving your editor using SheetJS. Navigate between worksheets and pages of data with a responsive pagination_prev: demos/cloud/index @@ -16,50 +16,68 @@ import CodeBlock from '@theme/CodeBlock'; [SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing data from spreadsheets. -[Visual Studio Code](https://code.visualstudio.com) is a popular code editor that supports extensions for customizing -and enhancing functionality. +[Visual Studio Code](https://code.visualstudio.com) is a popular code editor +that supports JavaScript extensions for customizing and enhancing functionality. -This demo uses SheetJS in a VS Code extension to view Excel files directly within the editor. The extension leverages -VS Code's `Custom Editor API`[^2] and `WebView API`[^1] to display XLSX data as HTML tables. +The ["Complete Example"](#complete-example) uses SheetJS in a VS Code extension +to view Excel files directly within the editor. The extension leverages the VS +Code "Custom Editor API"[^2] and "WebView API"[^1] to display spreadsheet data +as HTML tables. -The demo includes the full source code for the extension and installation instructions. +:::tip pass + +["SheetJS Spreadsheet Viewer"](https://marketplace.visualstudio.com/items?itemName=asadbek.sheetjs-demo) +is a sample extension based on this demo. + +[The source code](https://git.sheetjs.com/asadbek064/sheetjs-vscode-extension) +is available on the SheetJS Git server. Feedback and contributions are welcome! + +::: + +![Expected output](pathname:///vscode/extension-viewing-xls-file.png) :::note Tested Deployments This demo was verified in the following deployments: -| Platform | OS Version | Architecture | Date | -|:----------------|:------------------------|:------------------|:-----------| -| VS Code 1.100.0 | macOS 15.3.1 | Darwin (arm64) | 2025-05-15 | +| Platform | Architecture | Date | +|:-----------------|:-------------|:-----------| +| VS Code 1.100.0 | `darwin-arm` | 2025-05-15 | TODO +| VSCodium 1.100.0 | `darwin-arm` | 2025-05-15 | TODO +| Cursor | `win11-arm` | 2025-05-15 | TODO +| Windsurf | `win11-arm` | 2025-05-15 | TODO +| Void | `win11-arm` | 2025-05-15 | TODO ::: ## Integration Details -The [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) can be imported from any component or script in the extension. -:::note +The [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) can be +imported from any component or script in the extension. -> Install the package as a developer dependency. -> Otherwise, `vsce`[^5] (Visual Studio Code Extension Manager) will **fail to package or publish** your extension correctly. +:::caution pass +The module must be installed as a development dependency. If the module is +installed as a normal dependency, `vsce`[^5] (Visual Studio Code Extension +Manager) will fail to package or publish your extension correctly. {`\ - npm rm --save xlsx - npm i --save-dev https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} +npm rm --save xlsx +npm i --save-dev https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ - pnpm rm xlsx - pnpm install -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} +pnpm rm xlsx +pnpm install -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} {`\ - yarn remove xlsx - yarn add -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} +yarn remove xlsx +yarn add -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} @@ -77,28 +95,25 @@ The VS Code Spreadsheet viewer extension has three main components: The extension uses VS Code's `Custom Editor API`[^2] to register as a handler for Excel files. When a file is opened, SheetJS parses it and displays the data in a WebView component. -## Building the Extension - - ### Extension Entry Point The main entry point registers the custom editor provider: - -{`import * as vscode from 'vscode'; - // highlight-start - import { ExcelEditorProvider } from './excelEditorProvider'; - // highlight-end +```ts title="src/extension.ts" +import * as vscode from 'vscode'; +// highlight-start +import { ExcelEditorProvider } from './excelEditorProvider'; +// highlight-end - export function activate(context: vscode.ExtensionContext) { - // SheetJS Spreadsheet Viewer extension activating... - // highlight-start - const provider = ExcelEditorProvider.register(context); - context.subscriptions.push(provider); - // highlight-end - } - export function deactivate() {}`} - +export function activate(context: vscode.ExtensionContext) { + // SheetJS Spreadsheet Viewer extension activating... + // highlight-start + const provider = ExcelEditorProvider.register(context); + context.subscriptions.push(provider); + // highlight-end +} +export function deactivate() {}`} +``` The `custom editor`[^3] is configured to support specific file types, giving us complete control over how each file is presented to the user. Additionally, `custom document`[^4] enables us to maintain and persist the state of each individual @@ -122,7 +137,7 @@ file that's opened. public static register(context: vscode.ExtensionContext): vscode.Disposable { return vscode.window.registerCustomEditorProvider( 'excelViewer.spreadsheet', - new ExcelEditorProvider(context), + new ExcelEditorProvider(), { webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden ); } @@ -131,6 +146,7 @@ file that's opened. ### Reading Files + The extension reads Excel files using the VS Code filesystem API and passes the data to SheetJS for parsing: @@ -189,7 +205,7 @@ sequenceDiagram ## Complete Example -1. Create a new VS Code extension +1) Create a new VS Code extension ```bash npx --package yo --package generator-code -- yo code @@ -209,78 +225,78 @@ When prompted, enter the following options: - `Do you want to open the new folder with Visual Studio Code?`: Press Enter -2. [Install the dependencies](#integration-details) and start: +2) [Install the dependencies](#integration-details) and start the dev server: {`\ +cd sheetjs-demo pnpm install -D https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz pnpm run watch `} -3. Create a new provider `excelEditorProivder.ts` and paste the following: +3) Save the following code snippet to `src/excelEditorProvider.ts`: - -{`import * as vscode from 'vscode'; - import * as XLSX from 'xlsx'; +{`\ +import * as vscode from 'vscode'; +import * as XLSX from 'xlsx'; - class ExcelDocument implements vscode.CustomDocument { - constructor(public readonly uri: vscode.Uri) { } - dispose() { } - } +class ExcelDocument implements vscode.CustomDocument { + constructor(public readonly uri: vscode.Uri) { } + dispose() { } +} export class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider { - public static register(context: vscode.ExtensionContext): vscode.Disposable { - return vscode.window.registerCustomEditorProvider( - 'excelViewer.spreadsheet', - new ExcelEditorProvider(context), - { webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden - ); - } - - private async loadWorkbook(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { - const data: Uint8Array = await vscode.workspace.fs.readFile(document.uri); - - const options: XLSX.ParsingOptions = { - type: 'array', - cellStyles: true, - cellDates: true, - }; - - return XLSX.read(new Uint8Array(data), options); // returns a XLSX.WorkBook - } - - // This is called when the first time an editor for a given resource is opened - async openCustomDocument(uri: vscode.Uri): Promise { - return new ExcelDocument(uri); - } - - // This is called whenever the user opens a new editor - async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { - const wb: XLSX.WorkBook = await this.loadWorkbook(document, webviewPanel); - const htmlTable = XLSX.utils.sheet_to_html(wb.Sheets[wb.SheetNames[0]]); - webviewPanel.webview.html = \`\${htmlTable}\`; - } - }`} - - -4. Register the custom editor provider with the main entry point `extension.ts` - - -{`import * as vscode from 'vscode'; - import { ExcelEditorProvider } from './excelEditorProvider'; - - export function activate(context: vscode.ExtensionContext) { - // SheetJS Spreadsheet Viewer extension activating... - const provider = ExcelEditorProvider.register(context); - context.subscriptions.push(provider); + public static register(context: vscode.ExtensionContext): vscode.Disposable { + return vscode.window.registerCustomEditorProvider( + 'excelViewer.spreadsheet', + new ExcelEditorProvider(), + { webviewOptions: { retainContextWhenHidden: true } } // keep webview state when hidden + ); } - export function deactivate() {}`} + + private async loadWorkbook(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { + const data: Uint8Array = await vscode.workspace.fs.readFile(document.uri); + + const options: XLSX.ParsingOptions = { + type: 'array', + cellStyles: true, + cellDates: true, + }; + + return XLSX.read(new Uint8Array(data), options); // returns a XLSX.WorkBook + } + + // This is called when the first time an editor for a given resource is opened + async openCustomDocument(uri: vscode.Uri): Promise { + return new ExcelDocument(uri); + } + + // This is called whenever the user opens a new editor + async resolveCustomEditor(document: ExcelDocument, webviewPanel: vscode.WebviewPanel): Promise { + const wb: XLSX.WorkBook = await this.loadWorkbook(document, webviewPanel); + const htmlTable = XLSX.utils.sheet_to_html(wb.Sheets[wb.SheetNames[0]]); + webviewPanel.webview.html = \`\${htmlTable}\`; + } +}`} +4) Register the custom editor provider in `src/extension.ts`: -5. Registering the custom editor in your `package.json` file. +{`\ +import * as vscode from 'vscode'; +import { ExcelEditorProvider } from './excelEditorProvider'; -{`\ +export function activate(context: vscode.ExtensionContext) { + // SheetJS Spreadsheet Viewer extension activating... + const provider = ExcelEditorProvider.register(context); + context.subscriptions.push(provider); +} +export function deactivate() {}`} + + +5) Register the custom editor in the `contributes` section of `package.json`: + +{`\ "main": "./dist/extension.js", "contributes": { // highlight-start @@ -306,18 +322,13 @@ export class ExcelEditorProvider implements vscode.CustomReadonlyEditorProvider< 6. Inside the editor, open `src/extension.ts` and press F5 or run the command **Debug: Start Debugging** -from the Command Pallet (⇧⌘P). This will compile and run the extension in a new Extension Development Host window. +from the Command Palette (⇧⌘P). This will compile and run the extension in a new Extension Development Host window. 7. Select the new VSCode Window and open a `.xlsx` or `.xls` file. -![Expected output](pathname:///vscode/extension-viewing-xls-file.png) --- -### Learn More - -You can check out [the complete SheetJS VS Code extension demo repository](https://git.sheetjs.com/asadbek064/sheetjs-vscode-extension) - your feedback and contributions are welcome! - [^1]: See [`Webview API`](https://code.visualstudio.com/api/extension-guides/webview) for more details. [^2]: See [`Custom Editor API`](https://code.visualstudio.com/api/extension-guides/custom-editors) documentation for more details. [^3]: See [`Custom Editor`](https://code.visualstudio.com/api/extension-guides/custom-editors#custom-editor) for more details. diff --git a/docz/docs/index.md b/docz/docs/index.md index cfa63c7..0b429b6 100644 --- a/docz/docs/index.md +++ b/docz/docs/index.md @@ -367,7 +367,7 @@ This,is,a,Test The test suite is regularly run against a number of modern and legacy browsers using [Sauce Labs](https://saucelabs.com/). -The following chart shows test results on 2024-10-20 for version `0.20.3`: +The following chart shows test results on 2025-05-15 for version `0.20.3`: [![Build Status](pathname:///test/sheetjs.svg)](https://saucelabs.com/u/sheetjs) diff --git a/docz/package.json b/docz/package.json index 1f0e346..a747f61 100644 --- a/docz/package.json +++ b/docz/package.json @@ -15,6 +15,10 @@ }, "overrides": { "@cmfcmf/docusaurus-search-local": { + "@algolia/autocomplete-theme-classic": "1.19.1", + "@algolia/autocomplete-js": "1.19.1", + "@algolia/client-search": "5.25.0", + "algoliasearch": "5.25.0", "@docusaurus/core": "3.7.0" } }, diff --git a/docz/static/nuxt/3/nuxt.config.ts b/docz/static/nuxt/2/nuxt.config.ts similarity index 75% rename from docz/static/nuxt/3/nuxt.config.ts rename to docz/static/nuxt/2/nuxt.config.ts index 4587637..dbac135 100644 --- a/docz/static/nuxt/3/nuxt.config.ts +++ b/docz/static/nuxt/2/nuxt.config.ts @@ -1,4 +1,4 @@ -import SheetJSModule from './sheetmodule' +import SheetJSModule from './sheetmodule'; export default defineNuxtConfig({ // @ts-ignore diff --git a/docz/static/nuxt/3/pres.vue b/docz/static/nuxt/2/pres.vue similarity index 100% rename from docz/static/nuxt/3/pres.vue rename to docz/static/nuxt/2/pres.vue diff --git a/docz/static/nuxt/3/sheetformer.ts b/docz/static/nuxt/2/sheetformer.ts similarity index 92% rename from docz/static/nuxt/3/sheetformer.ts rename to docz/static/nuxt/2/sheetformer.ts index a85d242..b641ffc 100644 --- a/docz/static/nuxt/3/sheetformer.ts +++ b/docz/static/nuxt/2/sheetformer.ts @@ -2,7 +2,7 @@ import { defineTransformer } from "@nuxt/content/transformers/utils"; import { read, utils } from "xlsx"; import { readFileSync } from "node:fs"; -import { resolve } from 'node:path'; +import { resolve } from "node:path"; export default defineTransformer({ name: 'sheetformer', diff --git a/docz/static/nuxt/3/sheetmodule.ts b/docz/static/nuxt/2/sheetmodule.ts similarity index 100% rename from docz/static/nuxt/3/sheetmodule.ts rename to docz/static/nuxt/2/sheetmodule.ts diff --git a/docz/static/test/sheetjs.svg b/docz/static/test/sheetjs.svg index 5ecb2b6..683e0de 100644 --- a/docz/static/test/sheetjs.svg +++ b/docz/static/test/sheetjs.svg @@ -1,4 +1,4 @@ - +