@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/value.js

@@ -1,120 +1,120 @@
-// The fill engine's value policy (FR2, ADR-0037 Karar 5; ADR-0039). Pure.
-//
-// A value is a string, or null (empty). It may not hold a tab, a line break —
-// except LF in a tag the caller names multi-line (ADR-0039) — nor any
-// character XML 1.0 forbids or the engine refuses anyway. CR, U+2028 and
-// U+2029 stay refused even in a multi-line tag: the engine never changes a
-// value silently, so a CRLF the caller did not normalize is an error, not a
-// rewrite. Re-scanning the output would NOT catch these: U+FFFE is valid
-// UTF-8, and TextEncoder silently turns a lone surrogate into U+FFFD, so the
-// check has to happen here.
-//
-// An issue names the code, the first offending index, its code point and how
-// many such characters there are — never the value itself (KVKK: a report or
-// an error message must not carry personal data into a log).
-
-const encoder = new TextEncoder();
-
-/**
- * @typedef {object} ValueIssue
- * @property {string} code
- * @property {number} [index]  UTF-16 index of the first offending character
- * @property {number} [codePoint]
- * @property {number} [count]  how many characters of this kind the value holds
- * @property {string} [type]  for VALUE_NOT_STRING: the value's type
- */
-
-/**
- * @typedef {object} ValueCheck
- * @property {ValueIssue[]} errors
- * @property {ValueIssue[]} warnings
- * @property {boolean} empty  null, "" or whitespace only — allowed, and reported
- */
-
-/**
- * Not an XML 1.0 Char, or one the engine refuses anyway: C0 controls (tab,
- * LF and CR are classified before this), DEL and the C1 controls, a lone
- * surrogate (a valid pair is combined before this), and the noncharacters —
- * U+FDD0–U+FDEF and the last two code points of every plane (U+FFFE, U+FFFF,
- * U+1FFFE …).
- * @param {number} cp
- * @returns {boolean}
- */
-function isIllegalCodePoint(cp) {
-  return (
-    cp < 0x20 ||
-    (cp >= 0x7f && cp <= 0x9f) ||
-    (cp >= 0xd800 && cp <= 0xdfff) ||
-    (cp >= 0xfdd0 && cp <= 0xfdef) ||
-    (cp & 0xfffe) === 0xfffe
-  );
-}
-
-/**
- * @param {number} cp
- * @param {boolean} multiline  the tag is named in the fill's `multiline` option
- * @returns {string | null}
- */
-function classify(cp, multiline) {
-  if (cp === 0x0a) return multiline ? null : "VALUE_LINE_BREAK";
-  if (cp === 0x0d || cp === 0x2028 || cp === 0x2029) return "VALUE_LINE_BREAK";
-  if (cp === 0x09) return "VALUE_TAB";
-  if (isIllegalCodePoint(cp)) return "VALUE_ILLEGAL_CHAR";
-  return null;
-}
-
-/**
- * @param {unknown} value
- * @returns {string}
- */
-function typeName(value) {
-  if (Array.isArray(value)) return "array";
-  return typeof value;
-}
-
-/**
- * Checks one value the data supplied for a tag. The caller has already
- * decided presence: an absent key or `undefined` is MISSING_VALUE there.
- * A value of line breaks only is empty, like whitespace (`trim`).
- * @param {unknown} value
- * @param {{multiline?: boolean}} [options]  `multiline`: LF is a line break, not an error (ADR-0039)
- * @returns {ValueCheck}
- */
-export function checkValue(value, { multiline = false } = {}) {
-  if (value === null) return { errors: [], warnings: [], empty: true };
-  if (typeof value !== "string") {
-    return { errors: [{ code: "VALUE_NOT_STRING", type: typeName(value) }], warnings: [], empty: false };
-  }
-  /** @type {Map<string, ValueIssue>} */
-  const found = new Map();
-  for (let i = 0; i < value.length; i += 1) {
-    const unit = value.charCodeAt(i);
-    let cp = unit;
-    if (unit >= 0xd800 && unit <= 0xdbff && i + 1 < value.length) {
-      const next = value.charCodeAt(i + 1);
-      if (next >= 0xdc00 && next <= 0xdfff) cp = (unit - 0xd800) * 0x400 + (next - 0xdc00) + 0x10000;
-    }
-    const code = classify(cp, multiline);
-    if (code !== null) {
-      const issue = found.get(code);
-      if (issue === undefined) found.set(code, { code, index: i, codePoint: cp, count: 1 });
-      else issue.count = /** @type {number} */ (issue.count) + 1;
-    }
-    if (cp > 0xffff) i += 1;
-  }
-  /** @type {ValueIssue[]} */
-  const warnings = [];
-  if (value.normalize("NFC") !== value) warnings.push({ code: "VALUE_NOT_NFC" });
-  return { errors: [...found.values()], warnings, empty: value.trim() === "" };
-}
-
-/**
- * The bytes that replace a tag's text: `&`, `<` and `>` escaped (escaping
- * `>` also makes `]]>` impossible), UTF-8 encoded. Call only on a value
- * `checkValue` accepted.
- * @param {string} value
- * @returns {Uint8Array}
- */
-export function encodeTextValue(value) {
-  return encoder.encode(value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"));
-}
+// The fill engine's value policy (FR2, ADR-0037 Karar 5; ADR-0039). Pure.
+//
+// A value is a string, or null (empty). It may not hold a tab, a line break —
+// except LF in a tag the caller names multi-line (ADR-0039) — nor any
+// character XML 1.0 forbids or the engine refuses anyway. CR, U+2028 and
+// U+2029 stay refused even in a multi-line tag: the engine never changes a
+// value silently, so a CRLF the caller did not normalize is an error, not a
+// rewrite. Re-scanning the output would NOT catch these: U+FFFE is valid
+// UTF-8, and TextEncoder silently turns a lone surrogate into U+FFFD, so the
+// check has to happen here.
+//
+// An issue names the code, the first offending index, its code point and how
+// many such characters there are — never the value itself (KVKK: a report or
+// an error message must not carry personal data into a log).
+
+const encoder = new TextEncoder();
+
+/**
+ * @typedef {object} ValueIssue
+ * @property {string} code
+ * @property {number} [index]  UTF-16 index of the first offending character
+ * @property {number} [codePoint]
+ * @property {number} [count]  how many characters of this kind the value holds
+ * @property {string} [type]  for VALUE_NOT_STRING: the value's type
+ */
+
+/**
+ * @typedef {object} ValueCheck
+ * @property {ValueIssue[]} errors
+ * @property {ValueIssue[]} warnings
+ * @property {boolean} empty  null, "" or whitespace only — allowed, and reported
+ */
+
+/**
+ * Not an XML 1.0 Char, or one the engine refuses anyway: C0 controls (tab,
+ * LF and CR are classified before this), DEL and the C1 controls, a lone
+ * surrogate (a valid pair is combined before this), and the noncharacters —
+ * U+FDD0–U+FDEF and the last two code points of every plane (U+FFFE, U+FFFF,
+ * U+1FFFE …).
+ * @param {number} cp
+ * @returns {boolean}
+ */
+function isIllegalCodePoint(cp) {
+  return (
+    cp < 0x20 ||
+    (cp >= 0x7f && cp <= 0x9f) ||
+    (cp >= 0xd800 && cp <= 0xdfff) ||
+    (cp >= 0xfdd0 && cp <= 0xfdef) ||
+    (cp & 0xfffe) === 0xfffe
+  );
+}
+
+/**
+ * @param {number} cp
+ * @param {boolean} multiline  the tag is named in the fill's `multiline` option
+ * @returns {string | null}
+ */
+function classify(cp, multiline) {
+  if (cp === 0x0a) return multiline ? null : "VALUE_LINE_BREAK";
+  if (cp === 0x0d || cp === 0x2028 || cp === 0x2029) return "VALUE_LINE_BREAK";
+  if (cp === 0x09) return "VALUE_TAB";
+  if (isIllegalCodePoint(cp)) return "VALUE_ILLEGAL_CHAR";
+  return null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function typeName(value) {
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+/**
+ * Checks one value the data supplied for a tag. The caller has already
+ * decided presence: an absent key or `undefined` is MISSING_VALUE there.
+ * A value of line breaks only is empty, like whitespace (`trim`).
+ * @param {unknown} value
+ * @param {{multiline?: boolean}} [options]  `multiline`: LF is a line break, not an error (ADR-0039)
+ * @returns {ValueCheck}
+ */
+export function checkValue(value, { multiline = false } = {}) {
+  if (value === null) return { errors: [], warnings: [], empty: true };
+  if (typeof value !== "string") {
+    return { errors: [{ code: "VALUE_NOT_STRING", type: typeName(value) }], warnings: [], empty: false };
+  }
+  /** @type {Map<string, ValueIssue>} */
+  const found = new Map();
+  for (let i = 0; i < value.length; i += 1) {
+    const unit = value.charCodeAt(i);
+    let cp = unit;
+    if (unit >= 0xd800 && unit <= 0xdbff && i + 1 < value.length) {
+      const next = value.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) cp = (unit - 0xd800) * 0x400 + (next - 0xdc00) + 0x10000;
+    }
+    const code = classify(cp, multiline);
+    if (code !== null) {
+      const issue = found.get(code);
+      if (issue === undefined) found.set(code, { code, index: i, codePoint: cp, count: 1 });
+      else issue.count = /** @type {number} */ (issue.count) + 1;
+    }
+    if (cp > 0xffff) i += 1;
+  }
+  /** @type {ValueIssue[]} */
+  const warnings = [];
+  if (value.normalize("NFC") !== value) warnings.push({ code: "VALUE_NOT_NFC" });
+  return { errors: [...found.values()], warnings, empty: value.trim() === "" };
+}
+
+/**
+ * The bytes that replace a tag's text: `&`, `<` and `>` escaped (escaping
+ * `>` also makes `]]>` impossible), UTF-8 encoded. Call only on a value
+ * `checkValue` accepted.
+ * @param {string} value
+ * @returns {Uint8Array}
+ */
+export function encodeTextValue(value) {
+  return encoder.encode(value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"));
+}