npm - @cj-tech-master/excelts - Versions diffs - 9.4.2 → 9.5.0 - Mend

@cj-tech-master/excelts 9.4.2 → 9.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (618) hide show

package/dist/browser/modules/xml/encode.d.ts CHANGED Viewed

@@ -9,8 +9,12 @@
  * Handles named entities (`&lt;`, `&gt;`, `&amp;`, `&quot;`, `&apos;`)
  * and numeric character references (`&#123;`, `&#x7B;`).
  *
- * Security: validates numeric code points are in range [1, 0x10FFFF]
- * and rejects surrogate halves (0xD800-0xDFFF).
+ * Security: validates numeric code points against the XML 1.0 `Char`
+ * production (rejects NUL, forbidden C0 controls, surrogates,
+ * noncharacters, and out-of-range code points). Malformed numeric
+ * refs are left untouched in the output so downstream layers (e.g. a
+ * re-encoder that strips them) can distinguish "author meant this" from
+ * "we couldn't decode this".
  *
  * Fast-path: returns the original string if no `&` is found.
  */
@@ -27,11 +31,23 @@ export declare function xmlDecode(text: string): string;
  */
 export declare function xmlEncode(text: string): string;
 /**
- * Encode a value for use in an XML attribute.
+ * Encode a value for use in a double-quoted XML attribute.
  *
- * Same as {@link xmlEncode} — provided as a semantic alias.
- * In the future this could apply attribute-specific normalisation
- * (e.g. collapsing whitespace per XML 1.0 §3.3.3).
+ * Does everything {@link xmlEncode} does (escape `<>&"'`, strip invalid
+ * control chars and lone surrogates) PLUS encodes `\t`, `\n`, `\r` as
+ * numeric character references (`&#x9;`, `&#xA;`, `&#xD;`).
+ *
+ * The extra whitespace handling is required by XML 1.0 §3.3.3
+ * (attribute-value normalisation), which replaces every literal
+ * whitespace character inside an attribute value with a single space
+ * at parse time. Without the numeric-ref encoding, `"foo\nbar"` written
+ * into an attribute round-trips as `"foo bar"` — the newline is gone.
+ * Parsers / validators never collapse numeric character references, so
+ * `&#xA;` survives verbatim.
+ *
+ * Use this for every attribute value in XML output that needs to
+ * round-trip exactly (OOXML chart / sidecar / pivot content, relationship
+ * targets, anything later re-parsed by another tool).
  */
 export declare function xmlEncodeAttr(value: string): string;
 /**
@@ -47,12 +63,45 @@ export declare function xmlEncodeAttr(value: string): string;
  */
 export declare function validateXmlName(name: string): void;
 /**
- * Encode text for a CDATA section, splitting on `]]>` to produce valid output.
+ * Encode text for a CDATA section, stripping XML 1.0-illegal
+ * characters first and then splitting on `]]>` to produce valid
+ * output.
+ *
+ * CDATA is not a magic passthrough: only the five structural entities
+ * are skipped, but every other XML Char production rule still applies.
+ * A user string that carries `\x08` or a lone surrogate half wraps
+ * into a CDATA section that every conformant parser rejects. Strip
+ * them first (same sanitisation as {@link xmlEncode} / the chart
+ * module's `escapeXml`) so CDATA output stays well-formed.
  *
  * The sequence `]]>` cannot appear inside CDATA, so each occurrence is split
  * into adjacent CDATA sections: `<![CDATA[...]]]]><![CDATA[>...]]>`.
  */
 export declare function encodeCData(text: string): string;
+/**
+ * Strip characters that XML 1.0 forbids from text / attribute /
+ * CDATA content, plus DEL (0x7F) as a project-policy extension.
+ *
+ * The XML 1.0 Char production allows: `#x9 | #xA | #xD |
+ * [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]`. So the
+ * disallowed ranges are:
+ *   - C0 controls other than `\t` `\n` `\r` (`0x00-0x08`, `0x0B`,
+ *     `0x0C`, `0x0E-0x1F`),
+ *   - lone UTF-16 surrogate halves (`0xD800-0xDFFF` not in a valid
+ *     pair),
+ *   - the noncharacters `0xFFFE` / `0xFFFF`.
+ *
+ * `0x7F` (DEL) is TECHNICALLY legal per the XML spec — it falls
+ * within the `[#x20-#xD7FF]` range — but some downstream consumers
+ * (older Excel versions, strict SAX libraries) choke on it. We strip
+ * it as a defence-in-depth measure; the comment that previously
+ * claimed "XML 1.0 forbids DEL" was incorrect.
+ *
+ * Exported so `chart-utils.ts` and any other module that needs the
+ * same sanitisation can share a single implementation instead of
+ * carrying a local copy that drifts on edge cases.
+ */
+export declare function stripXmlIllegalChars(text: string): string;
 /**
  * Validate that text is legal for an XML comment.
  *

package/dist/browser/modules/xml/encode.js CHANGED Viewed

@@ -51,14 +51,51 @@ const ENCODE_ENTITIES = {
 // =============================================================================
 // Decode
 // =============================================================================
+/**
+ * Is `code` a legal XML 1.0 character per §2.2?
+ *
+ *   Char ::= #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD]
+ *          | [#x10000-#x10FFFF]
+ *
+ * Rejects NULs, the forbidden C0 controls (`0x01`-`0x08`, `0x0B`,
+ * `0x0C`, `0x0E`-`0x1F`), lone surrogate halves (`0xD800`-`0xDFFF`),
+ * the noncharacters `0xFFFE` / `0xFFFF`, and anything above the
+ * Unicode ceiling.
+ *
+ * Used by both {@link xmlDecode} (to refuse malformed numeric
+ * character references) and {@link encodeCData} (to strip illegal
+ * bytes before wrapping user content in a CDATA section).
+ */
+function isLegalXmlChar(code) {
+    if (!Number.isFinite(code) || code < 0 || code > 0x10ffff) {
+        return false;
+    }
+    if (code === 0x9 || code === 0xa || code === 0xd) {
+        return true;
+    }
+    if (code < 0x20) {
+        return false;
+    }
+    if (code >= 0xd800 && code <= 0xdfff) {
+        return false;
+    }
+    if (code === 0xfffe || code === 0xffff) {
+        return false;
+    }
+    return true;
+}
 /**
  * Decode XML entities in a string.
  *
  * Handles named entities (`&lt;`, `&gt;`, `&amp;`, `&quot;`, `&apos;`)
  * and numeric character references (`&#123;`, `&#x7B;`).
  *
- * Security: validates numeric code points are in range [1, 0x10FFFF]
- * and rejects surrogate halves (0xD800-0xDFFF).
+ * Security: validates numeric code points against the XML 1.0 `Char`
+ * production (rejects NUL, forbidden C0 controls, surrogates,
+ * noncharacters, and out-of-range code points). Malformed numeric
+ * refs are left untouched in the output so downstream layers (e.g. a
+ * re-encoder that strips them) can distinguish "author meant this" from
+ * "we couldn't decode this".
  *
  * Fast-path: returns the original string if no `&` is found.
  */
@@ -71,8 +108,11 @@ export function xmlDecode(text) {
             const code = entity[1] === "x" || entity[1] === "X"
                 ? parseInt(entity.slice(2), 16)
                 : parseInt(entity.slice(1), 10);
-            // Reject NaN, null char, surrogates, and out-of-range code points
-            if (Number.isNaN(code) || code < 1 || (code >= 0xd800 && code <= 0xdfff) || code > 0x10ffff) {
+            // Refuse everything outside the XML 1.0 Char range — NUL,
+            // forbidden controls, surrogates, noncharacters, and values
+            // above `0x10FFFF`. Leaving the ref untouched is safer than
+            // materialising an invalid character into the decoded string.
+            if (!isLegalXmlChar(code)) {
                 return match;
             }
             return String.fromCodePoint(code);
@@ -182,14 +222,35 @@ export function xmlEncode(text) {
 // Attribute Encoding
 // =============================================================================
 /**
- * Encode a value for use in an XML attribute.
+ * Encode a value for use in a double-quoted XML attribute.
+ *
+ * Does everything {@link xmlEncode} does (escape `<>&"'`, strip invalid
+ * control chars and lone surrogates) PLUS encodes `\t`, `\n`, `\r` as
+ * numeric character references (`&#x9;`, `&#xA;`, `&#xD;`).
+ *
+ * The extra whitespace handling is required by XML 1.0 §3.3.3
+ * (attribute-value normalisation), which replaces every literal
+ * whitespace character inside an attribute value with a single space
+ * at parse time. Without the numeric-ref encoding, `"foo\nbar"` written
+ * into an attribute round-trips as `"foo bar"` — the newline is gone.
+ * Parsers / validators never collapse numeric character references, so
+ * `&#xA;` survives verbatim.
  *
- * Same as {@link xmlEncode} — provided as a semantic alias.
- * In the future this could apply attribute-specific normalisation
- * (e.g. collapsing whitespace per XML 1.0 §3.3.3).
+ * Use this for every attribute value in XML output that needs to
+ * round-trip exactly (OOXML chart / sidecar / pivot content, relationship
+ * targets, anything later re-parsed by another tool).
  */
 export function xmlEncodeAttr(value) {
-    return xmlEncode(value);
+    // Fast path: common case has none of `\t \n \r` so the expensive
+    // replace chain doesn't run. `xmlEncode` handles `<>&"'` and invalid
+    // control chars; whitespace characters fall through it unchanged.
+    const encoded = xmlEncode(value);
+    if (encoded.indexOf("\t") === -1 &&
+        encoded.indexOf("\n") === -1 &&
+        encoded.indexOf("\r") === -1) {
+        return encoded;
+    }
+    return encoded.replace(/\r/g, "&#xD;").replace(/\n/g, "&#xA;").replace(/\t/g, "&#x9;");
 }
 // =============================================================================
 // Name Validation
@@ -228,13 +289,98 @@ export function validateXmlName(name) {
 // Writer Helpers
 // =============================================================================
 /**
- * Encode text for a CDATA section, splitting on `]]>` to produce valid output.
+ * Encode text for a CDATA section, stripping XML 1.0-illegal
+ * characters first and then splitting on `]]>` to produce valid
+ * output.
+ *
+ * CDATA is not a magic passthrough: only the five structural entities
+ * are skipped, but every other XML Char production rule still applies.
+ * A user string that carries `\x08` or a lone surrogate half wraps
+ * into a CDATA section that every conformant parser rejects. Strip
+ * them first (same sanitisation as {@link xmlEncode} / the chart
+ * module's `escapeXml`) so CDATA output stays well-formed.
  *
  * The sequence `]]>` cannot appear inside CDATA, so each occurrence is split
  * into adjacent CDATA sections: `<![CDATA[...]]]]><![CDATA[>...]]>`.
  */
 export function encodeCData(text) {
-    return "<![CDATA[" + text.split("]]>").join("]]]]><![CDATA[>") + "]]>";
+    return "<![CDATA[" + stripIllegalXmlChars(text).split("]]>").join("]]]]><![CDATA[>") + "]]>";
+}
+/**
+ * Strip characters that XML 1.0 forbids from text / attribute /
+ * CDATA content, plus DEL (0x7F) as a project-policy extension.
+ *
+ * The XML 1.0 Char production allows: `#x9 | #xA | #xD |
+ * [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]`. So the
+ * disallowed ranges are:
+ *   - C0 controls other than `\t` `\n` `\r` (`0x00-0x08`, `0x0B`,
+ *     `0x0C`, `0x0E-0x1F`),
+ *   - lone UTF-16 surrogate halves (`0xD800-0xDFFF` not in a valid
+ *     pair),
+ *   - the noncharacters `0xFFFE` / `0xFFFF`.
+ *
+ * `0x7F` (DEL) is TECHNICALLY legal per the XML spec — it falls
+ * within the `[#x20-#xD7FF]` range — but some downstream consumers
+ * (older Excel versions, strict SAX libraries) choke on it. We strip
+ * it as a defence-in-depth measure; the comment that previously
+ * claimed "XML 1.0 forbids DEL" was incorrect.
+ *
+ * Exported so `chart-utils.ts` and any other module that needs the
+ * same sanitisation can share a single implementation instead of
+ * carrying a local copy that drifts on edge cases.
+ */
+export function stripXmlIllegalChars(text) {
+    // Fast path: scan for any char that would fail the Char production.
+    // Most user input is plain ASCII in the legal range, so this
+    // returns the original string without allocation.
+    let needsStrip = false;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if ((code < 0x20 && code !== 9 && code !== 10 && code !== 13) ||
+            code === 0x7f ||
+            (code >= 0xd800 && code <= 0xdfff) ||
+            code === 0xfffe ||
+            code === 0xffff) {
+            needsStrip = true;
+            break;
+        }
+    }
+    if (!needsStrip) {
+        return text;
+    }
+    const out = [];
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 0x20) {
+            if (code === 9 || code === 10 || code === 13) {
+                out.push(text[i]);
+            }
+            continue;
+        }
+        if (code === 0x7f) {
+            continue;
+        }
+        if (code === 0xfffe || code === 0xffff) {
+            continue;
+        }
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = text.charCodeAt(i + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                out.push(text[i], text[i + 1]);
+                i += 1;
+            }
+            // else: lone high surrogate — strip
+            continue;
+        }
+        if (code >= 0xdc00 && code <= 0xdfff) {
+            continue;
+        }
+        out.push(text[i]);
+    }
+    return out.join("");
+}
+function stripIllegalXmlChars(text) {
+    return stripXmlIllegalChars(text);
 }
 /**
  * Validate that text is legal for an XML comment.

package/dist/cjs/index.js CHANGED Viewed

@@ -17,8 +17,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uint8ArrayToString = exports.stringToUint8Array = exports.toUint8Array = exports.concatUint8Arrays = exports.getRootCause = exports.getErrorChain = exports.errorToJSON = exports.toError = exports.BaseError = exports.getSupportedFormats = exports.DateFormatter = exports.DateParser = exports.xmlDecode = exports.xmlEncode = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = exports.excelToDate = exports.dateToExcel = exports.isDateDisplayFormat = exports.formatCellValue = exports.getCellDisplayText = exports.encodeRange = exports.decodeRange = exports.encodeCell = exports.decodeCell = exports.encodeRow = exports.decodeRow = exports.encodeCol = exports.decodeCol = exports.DefinedNames = exports.createCsvFormatterStream = exports.createCsvParserStream = exports.CsvFormatterStream = exports.CsvParserStream = exports.createTextWatermarkImage = exports.WorksheetReader = exports.WorksheetWriter = exports.WorkbookReader = exports.WorkbookWriter = exports.FormCheckbox = exports.DataValidations = exports.Note = exports.Table = exports.Image = exports.Range = exports.Cell = exports.Column = exports.Row = exports.Worksheet = exports.Workbook = void 0;
-exports.MarkdownParseError = exports.MarkdownError = exports.MaxItemsExceededError = exports.ImageError = exports.TableError = exports.PivotTableError = exports.WorksheetNameError = exports.XmlParseError = exports.InvalidValueTypeError = exports.MergeConflictError = exports.RowOutOfBoundsError = exports.ColumnOutOfBoundsError = exports.InvalidAddressError = exports.ExcelStreamStateError = exports.ExcelNotSupportedError = exports.ExcelDownloadError = exports.ExcelFileError = exports.isExcelError = exports.ExcelError = exports.isPdfError = exports.PdfStructureError = exports.PdfFontError = exports.PdfRenderError = exports.PdfError = exports.PageSizes = exports.excelToPdf = exports.pdf = void 0;
+exports.concatUint8Arrays = exports.getRootCause = exports.getErrorChain = exports.errorToJSON = exports.toError = exports.BaseError = exports.getSupportedFormats = exports.DateFormatter = exports.DateParser = exports.validateXmlName = exports.xmlEncodeAttr = exports.xmlDecode = exports.xmlEncode = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = exports.excelToDate = exports.dateToExcel = exports.isDateDisplayFormat = exports.formatCellValue = exports.getCellDisplayText = exports.encodeRange = exports.decodeRange = exports.encodeCell = exports.decodeCell = exports.encodeRow = exports.decodeRow = exports.encodeCol = exports.decodeCol = exports.Chartsheet = exports.DefinedNames = exports.createCsvFormatterStream = exports.createCsvParserStream = exports.CsvFormatterStream = exports.CsvParserStream = exports.createTextWatermarkImage = exports.WorksheetReader = exports.WorksheetWriter = exports.WorkbookReader = exports.WorkbookWriter = exports.FormCheckbox = exports.DataValidations = exports.Note = exports.Table = exports.Image = exports.Range = exports.Cell = exports.Column = exports.Row = exports.Worksheet = exports.Workbook = void 0;
+exports.MarkdownParseError = exports.MarkdownError = exports.MaxItemsExceededError = exports.ImageError = exports.TableError = exports.PivotTableError = exports.WorksheetNameError = exports.XmlParseError = exports.InvalidValueTypeError = exports.MergeConflictError = exports.RowOutOfBoundsError = exports.ColumnOutOfBoundsError = exports.InvalidAddressError = exports.ExcelStreamStateError = exports.ExcelNotSupportedError = exports.ExcelDownloadError = exports.ExcelFileError = exports.isExcelError = exports.ExcelError = exports.isPdfError = exports.PdfStructureError = exports.PdfFontError = exports.PdfRenderError = exports.PdfError = exports.PageSizes = exports.excelToPdf = exports.pdf = exports.uint8ArrayToString = exports.stringToUint8Array = exports.toUint8Array = void 0;
 var workbook_1 = require("./modules/excel/workbook.js");
 Object.defineProperty(exports, "Workbook", { enumerable: true, get: function () { return workbook_1.Workbook; } });
 var worksheet_1 = require("./modules/excel/worksheet.js");
@@ -80,6 +80,8 @@ Object.defineProperty(exports, "createCsvFormatterStream", { enumerable: true, g
 // =============================================================================
 var defined_names_1 = require("./modules/excel/defined-names.js");
 Object.defineProperty(exports, "DefinedNames", { enumerable: true, get: function () { return defined_names_1.DefinedNames; } });
+var chartsheet_1 = require("./modules/excel/chartsheet.js");
+Object.defineProperty(exports, "Chartsheet", { enumerable: true, get: function () { return chartsheet_1.Chartsheet; } });
 // =============================================================================
 // Utilities
 // =============================================================================
@@ -93,6 +95,13 @@ Object.defineProperty(exports, "decodeCell", { enumerable: true, get: function (
 Object.defineProperty(exports, "encodeCell", { enumerable: true, get: function () { return address_1.encodeCell; } });
 Object.defineProperty(exports, "decodeRange", { enumerable: true, get: function () { return address_1.decodeRange; } });
 Object.defineProperty(exports, "encodeRange", { enumerable: true, get: function () { return address_1.encodeRange; } });
+// Chart programmatic surface (builders, renderers, presets, parsers,
+// install function) lives at the `./chart` subpath so it stays out of
+// bundles that only need to read / write XLSX files. Import
+// `@cj-tech-master/excelts/chart` to use chart APIs — and call
+// `installChartSupport()` once at startup to enable
+// `worksheet.addChart()`, chart-cache population during write, and
+// chart reconstruction during XLSX load.
 // Cell display-text helpers (apply numFmt to produce an Excel-style string)
 var cell_format_1 = require("./modules/excel/utils/cell-format.js");
 Object.defineProperty(exports, "getCellDisplayText", { enumerable: true, get: function () { return cell_format_1.getCellDisplayText; } });
@@ -110,6 +119,8 @@ Object.defineProperty(exports, "uint8ArrayToBase64", { enumerable: true, get: fu
 var encode_1 = require("./modules/xml/encode.js");
 Object.defineProperty(exports, "xmlEncode", { enumerable: true, get: function () { return encode_1.xmlEncode; } });
 Object.defineProperty(exports, "xmlDecode", { enumerable: true, get: function () { return encode_1.xmlDecode; } });
+Object.defineProperty(exports, "xmlEncodeAttr", { enumerable: true, get: function () { return encode_1.xmlEncodeAttr; } });
+Object.defineProperty(exports, "validateXmlName", { enumerable: true, get: function () { return encode_1.validateXmlName; } });
 // Date parsing/formatting (high-performance, zero-dep)
 var datetime_1 = require("./utils/datetime.js");
 Object.defineProperty(exports, "DateParser", { enumerable: true, get: function () { return datetime_1.DateParser; } });