From 4b984058b592f299c8629d89e7e0ce562188269b Mon Sep 17 00:00:00 2001 From: SheetJS Date: Tue, 24 Oct 2023 02:20:57 -0400 Subject: [PATCH] ssf --- docz/docs/03-demos/04-static/index.md | 1 - docz/docs/06-solutions/_category_.json | 2 +- docz/docs/07-csf/_category_.json | 2 +- docz/docs/08-api/_category_.json | 2 +- docz/docs/08-api/index.md | 2 +- docz/docs/09-constellation/01-ssf.md | 26 ++++++++ docz/docs/09-constellation/_category_.json | 4 ++ docz/docs/09-constellation/index.md | 20 +++++++ docz/docs/09-miscellany/01-formats.md | 69 ++++++++++++---------- docz/docs/09-miscellany/_category_.json | 2 +- docz/docs/09-miscellany/index.md | 16 +++++ docz/docusaurus.config.js | 1 + 12 files changed, 109 insertions(+), 38 deletions(-) create mode 100644 docz/docs/09-constellation/01-ssf.md create mode 100644 docz/docs/09-constellation/_category_.json create mode 100644 docz/docs/09-constellation/index.md create mode 100644 docz/docs/09-miscellany/index.md diff --git a/docz/docs/03-demos/04-static/index.md b/docz/docs/03-demos/04-static/index.md index 6e267bd..641e305 100644 --- a/docz/docs/03-demos/04-static/index.md +++ b/docz/docs/03-demos/04-static/index.md @@ -4,7 +4,6 @@ pagination_prev: demos/net/index pagination_next: demos/mobile/index --- -import DocCardList from '@theme/DocCardList'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; With the advent of server-side frameworks and content management systems, it is diff --git a/docz/docs/06-solutions/_category_.json b/docz/docs/06-solutions/_category_.json index 9c8c72b..6b2489f 100644 --- a/docz/docs/06-solutions/_category_.json +++ b/docz/docs/06-solutions/_category_.json @@ -1,5 +1,5 @@ { "label": "Common Use Cases", "collapsed": true, - "position": 6 + "position": 5 } diff --git a/docz/docs/07-csf/_category_.json b/docz/docs/07-csf/_category_.json index b26ba68..f11b797 100644 --- a/docz/docs/07-csf/_category_.json +++ b/docz/docs/07-csf/_category_.json @@ -1,4 +1,4 @@ { "label": "SheetJS Data Model", - "position": 7 + "position": 6 } diff --git a/docz/docs/08-api/_category_.json b/docz/docs/08-api/_category_.json index bb46120..a08a23f 100644 --- a/docz/docs/08-api/_category_.json +++ b/docz/docs/08-api/_category_.json @@ -1,4 +1,4 @@ { "label": "API Reference", - "position": 8 + "position": 7 } diff --git a/docz/docs/08-api/index.md b/docz/docs/08-api/index.md index 13caba0..bc7c832 100644 --- a/docz/docs/08-api/index.md +++ b/docz/docs/08-api/index.md @@ -154,6 +154,6 @@ ESM helper functions are described in the ["NodeJS" Installation section](/docs/ ::: -`XLSX.SSF` is an embedded version of the [format library](https://git.sheetjs.com/sheetjs/sheetjs/src/branch/master/packages/ssf). +`XLSX.SSF` is an embedded version of the [format library](/docs/constellation/ssf). `XLSX.CFB` is an embedded version of the [container library](https://git.sheetjs.com/sheetjs/js-cfb). diff --git a/docz/docs/09-constellation/01-ssf.md b/docz/docs/09-constellation/01-ssf.md new file mode 100644 index 0000000..1eb2d90 --- /dev/null +++ b/docz/docs/09-constellation/01-ssf.md @@ -0,0 +1,26 @@ +--- +title: SSF Number Formatter +--- + +As explained in ["Number Formats"](/docs/csf/features/nf), modern spreadsheet +file formats separate "content" from "presentation". Instead of storing a +formatted value like `$3.50`, applications will store the underlying value +(`3.50`) and the number format (`$0.00`). Parsers are expected to render values. + +The SheetJS `SSF` ("SpreadSheet Formatter") library formats numbers according +to the number formatting rules defined in Excel and other spreadsheet software[^1] + +A version of the library ships with the main file processing library. It is +deeply integrated in SheetJS CE API functions including `read`[^2], `write`[^3], +and `sheet_to_json`[^4]. + +The library is also available for standalone use on the SheetJS CDN[^5]. + +The source code and project documentation is hosted on the SheetJS git server at + + +[^1]: The number formatting rules are sketched in ECMA-376. A rough grammar is defined in the MS-XLS specification. +[^2]: See [`read` in "Reading Files"](/docs/api/parse-options) +[^3]: See [`write` in "Writing Files"](/docs/api/write-options) +[^4]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output) +[^5]: See for more details. \ No newline at end of file diff --git a/docz/docs/09-constellation/_category_.json b/docz/docs/09-constellation/_category_.json new file mode 100644 index 0000000..d434a61 --- /dev/null +++ b/docz/docs/09-constellation/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Constellation", + "position": 9 +} \ No newline at end of file diff --git a/docz/docs/09-constellation/index.md b/docz/docs/09-constellation/index.md new file mode 100644 index 0000000..b214d9a --- /dev/null +++ b/docz/docs/09-constellation/index.md @@ -0,0 +1,20 @@ +--- +title: SheetJS Constellation +pagination_prev: miscellany/index +--- + +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +Many related projects have been separated into dedicated libraries. + +### Contents + +
    {useCurrentSidebarCategory().items.map(globalThis.lambda = (item, index) => { + const listyle = (item.customProps?.icon) ? { + listStyleImage: `url("${item.customProps.icon}")` + } : {}; + return (
  • + {item.label}{item.customProps?.summary && (" - " + item.customProps.summary)} +
      {item.items && item.items.map(lambda)}
    +
    • ); +})}
\ No newline at end of file diff --git a/docz/docs/09-miscellany/01-formats.md b/docz/docs/09-miscellany/01-formats.md index c220eac..bf7ef50 100644 --- a/docz/docs/09-miscellany/01-formats.md +++ b/docz/docs/09-miscellany/01-formats.md @@ -1,15 +1,10 @@ --- +title: File Formats sidebar_position: 1 -hide_table_of_contents: true pagination_prev: api/utilities/index --- -# File Formats - -![graph of format support](pathname:///formats.png) - -![graph legend](pathname:///legend.png) - +SheetJS supports reading and writing a number of spreadsheet file formats. | Format | Read | Write | |:-------------------------------------------------------------|:-----:|:-----:| @@ -45,8 +40,16 @@ pagination_prev: api/utilities/index | Rich Text Format tables (RTF) | ✔ | ✔ | | Ethercalc Record Format (ETH) | ✔ | ✔ | -Features not supported by a given file format will not be written. Formats with -range limits will be silently truncated: +![graph of format support](pathname:///formats.png) + +![graph legend](pathname:///legend.png) + +Features not supported by a given file format will not be written. + +## Worksheet Range Limits + +Formats with range limits will be silently truncated. For example, the Lotus WKS +format has a limit of 2048 rows, so data after the 2048th row will not be saved. | Format | Last Cell | Max Cols | Max Rows | |:------------------------------------------|:-----------|---------:|---------:| @@ -65,7 +68,9 @@ range limits will be silently truncated: Excel 2003 SpreadsheetML range limits are governed by the version of Excel and are not enforced by the writer. -### Excel 2007+ XML (XLSX/XLSM) +## Common File Formats + +#### Excel 2007+ XML (XLSX/XLSM) XLSX and XLSM files are ZIP containers containing a series of XML files in accordance with the Open Packaging Conventions (OPC). The XLSM format, almost @@ -75,7 +80,7 @@ The format is standardized in `ECMA-376` and `ISO/IEC 29500`. Excel does not follow the specification, and there are additional documents discussing how Excel deviates from the specification. -### Excel 2.0-95 (BIFF2/BIFF3/BIFF4/BIFF5) +#### Excel 2.0-95 (BIFF2/BIFF3/BIFF4/BIFF5) BIFF 2/3 XLS are single-sheet streams of binary records. Excel 4 introduced the concept of a workbook (`XLW` files) but also had single-sheet `XLS` format. @@ -92,7 +97,7 @@ files in these formats, so record lengths and fields were determined by writing in all of the supported formats and comparing files. Excel 2016 can generate BIFF5 files, enabling a full suite of file tests starting from XLSX or BIFF2. -### Excel 97-2004 Binary (BIFF8) +#### Excel 97-2004 Binary (BIFF8) BIFF8 exclusively uses the Compound File Binary container format, splitting some content into streams within the file. At its core, it still uses an extended @@ -101,14 +106,14 @@ version of the binary record format from older versions of BIFF. The `MS-XLS` specification covers the basics of the file format, and other specifications expand on serialization of features like properties. -### Excel 2003-2004 (SpreadsheetML) +#### Excel 2003-2004 (SpreadsheetML) Predating XLSX, SpreadsheetML files are simple XML files. There is no official and comprehensive specification, although MS has released documentation on the format. Since Excel 2016 can generate SpreadsheetML files, mapping features is pretty straightforward. -### Excel 2007+ Binary (XLSB, BIFF12) +#### Excel 2007+ Binary (XLSB, BIFF12) Introduced in parallel with XLSX, the XLSB format combines the BIFF architecture with the content separation and ZIP container of XLSX. For the most part nodes @@ -117,7 +122,7 @@ in an XLSX sub-file can be mapped to XLSB records in a corresponding sub-file. The `MS-XLSB` specification covers the basics of the file format, and other specifications expand on serialization of features like properties. -### Delimiter-Separated Values (CSV/TXT) +#### Delimiter-Separated Values (CSV/TXT) Excel CSV deviates from RFC4180 in a number of important ways. The generated CSV files should generally work in Excel although they may not work in RFC4180 @@ -132,7 +137,18 @@ will be proactively reinterpreted as CSV. There are some files with semicolon delimiter that align with a valid SYLK file. For the broadest compatibility, all cells with the value of `ID` are automatically wrapped in double-quotes. -### Miscellaneous Workbook Formats +#### HTML + +Excel HTML worksheets include special metadata encoded in styles. For example, +`mso-number-format` is a localized string containing the number format. Despite +the metadata the output is valid HTML, although it does accept bare `&` symbols. + +The writer adds type metadata to the TD elements via the `t` tag. The parser +looks for those tags and overrides the default interpretation. For example, text +like `12345` will be parsed as numbers but `12345` will +be parsed as text. + +## Miscellaneous Workbook Formats Support for other formats is generally far behind XLS/XLSB/XLSX support, due in part to a lack of publicly available documentation. Test files were produced in @@ -202,16 +218,16 @@ is in the names of tags and attributes. ET is the native format for WPS Office Spreadsheet. It extends the BIFF8 XLS format with proprietary extensions. -### Miscellaneous Worksheet Formats +## Miscellaneous Worksheet Formats Many older formats supported only one worksheet: #### dBASE and Visual FoxPro (DBF) -DBF is really a typed table format: each column can only hold one data type and -each record omits type information. The parser generates a header row and -inserts records starting at the second row of the worksheet. The writer makes -files compatible with Visual FoxPro extensions. +DBF is a typed table format: each column can only hold one data type and each +record omits type information. The parser generates a header row and inserts +records starting at the second row of the worksheet. The writer makes files +compatible with Visual FoxPro extensions. Multi-file extensions like external memos and tables are currently unsupported, limited by the general ability to read arbitrary files in the web browser. The @@ -241,17 +257,6 @@ behavior from Excel. In particular, Excel extends DIF in incompatible ways: - DIF technically has no support for formulae, but Excel will automatically convert plain formulae. Array formulae are not preserved. -#### HTML - -Excel HTML worksheets include special metadata encoded in styles. For example, -`mso-number-format` is a localized string containing the number format. Despite -the metadata the output is valid HTML, although it does accept bare `&` symbols. - -The writer adds type metadata to the TD elements via the `t` tag. The parser -looks for those tags and overrides the default interpretation. For example, text -like `12345` will be parsed as numbers but `12345` will -be parsed as text. - #### Rich Text Format (RTF) Excel RTF worksheets are stored in clipboard when copying cells or ranges from a diff --git a/docz/docs/09-miscellany/_category_.json b/docz/docs/09-miscellany/_category_.json index b36045f..7474926 100644 --- a/docz/docs/09-miscellany/_category_.json +++ b/docz/docs/09-miscellany/_category_.json @@ -1,4 +1,4 @@ { "label": "Miscellany", - "position": 9 + "position": 8 } diff --git a/docz/docs/09-miscellany/index.md b/docz/docs/09-miscellany/index.md new file mode 100644 index 0000000..ec0b4ff --- /dev/null +++ b/docz/docs/09-miscellany/index.md @@ -0,0 +1,16 @@ +--- +title: Miscellany +pagination_next: constellation/index +--- + +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + +
    {useCurrentSidebarCategory().items.map(globalThis.lambda = (item, index) => { + const listyle = (item.customProps?.icon) ? { + listStyleImage: `url("${item.customProps.icon}")` + } : {}; + return (
  • + {item.label}{item.customProps?.summary && (" - " + item.customProps.summary)} +
      {item.items && item.items.map(lambda)}
    +
    • ); +})}
\ No newline at end of file diff --git a/docz/docusaurus.config.js b/docz/docusaurus.config.js index f201bf5..6b44077 100644 --- a/docz/docusaurus.config.js +++ b/docz/docusaurus.config.js @@ -181,6 +181,7 @@ const config = { { from: '/docs/demos/vue', to: '/docs/demos/frontend/vue/' }, { from: '/docs/demos/bundler', to: '/docs/demos/frontend/bundler/' }, { from: '/docs/demos/legacy', to: '/docs/demos/frontend/legacy/' }, + { from: '/docs/getting-started/demos/legacy', to: '/docs/demos/frontend/legacy/' }, /* cloud */ { from: '/docs/demos/salesforce', to: '/docs/demos/cloud/salesforce/' }, { from: '/docs/demos/aws', to: '/docs/demos/cloud/aws/' },