@usejunior/docx-core 0.18.0 → 0.20.1

package/dist/primitives/symbol_run_content.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Text projection of `<w:sym>` run content.
+ *
+ * A symbol glyph has two legal spellings in WordprocessingML and Word renders
+ * them identically:
+ *
+ * 1. `<w:sym w:font="Wingdings" w:char="F0A8"/>`, and
+ * 2. the same codepoint written literally inside a `<w:t>`, with the symbol
+ *    font carried on the run's `<w:rFonts>`.
+ *
+ * Any text projection that walks `w:t`/`w:delText` alone therefore sees a
+ * document that *lost* a symbol and a document that *kept* it as the same
+ * string, and sees the two spellings of one glyph as different strings. This
+ * module is the single place the projection resolves spelling (1) into the
+ * characters spelling (2) would have contributed.
+ *
+ * The font is deliberately **not** part of the projected value. The projections
+ * that consume this are text projections: they already exclude `w:rFonts`, so
+ * folding `w:sym/@w:font` in would make the same font signal visible for one
+ * spelling of a glyph and invisible for the other, and would make the two
+ * spellings compare unequal by construction — the exact false difference this
+ * resolution exists to remove. A font-only change is a formatting change and
+ * belongs to the formatting-fidelity surface, not the round-trip text gate;
+ * that residual is tracked separately.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.3.3.30
+ * @see https://github.com/UseJunior/safe-docx/issues/793
+ * @see https://github.com/UseJunior/safe-docx/issues/799
+ */
+/** Local name of the symbol-character run-content element. */
+export declare const SYM_LOCAL_NAME = "sym";
+/**
+ * Project a `<w:sym>` element to the text it contributes, or `undefined` when
+ * `element` is not a `w:sym`.
+ *
+ * For a resolvable `@w:char` the result is exactly the character the glyph
+ * stands for — what it would have contributed had it been spelled as literal
+ * `w:t` content. Otherwise it is a framed, projection-only identity that keeps
+ * the element's presence visible without colliding with authored text.
+ */
+export declare function projectSymbolRun(element: Element): string | undefined;
+//# sourceMappingURL=symbol_run_content.d.ts.map

package/dist/primitives/symbol_run_content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol_run_content.d.ts","sourceRoot":"","sources":["../../src/primitives/symbol_run_content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,8DAA8D;AAC9D,eAAO,MAAM,cAAc,QAAQ,CAAC;AAkCpC;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMrE"}

package/dist/primitives/symbol_run_content.js

@@ -0,0 +1,79 @@
+/**
+ * Text projection of `<w:sym>` run content.
+ *
+ * A symbol glyph has two legal spellings in WordprocessingML and Word renders
+ * them identically:
+ *
+ * 1. `<w:sym w:font="Wingdings" w:char="F0A8"/>`, and
+ * 2. the same codepoint written literally inside a `<w:t>`, with the symbol
+ *    font carried on the run's `<w:rFonts>`.
+ *
+ * Any text projection that walks `w:t`/`w:delText` alone therefore sees a
+ * document that *lost* a symbol and a document that *kept* it as the same
+ * string, and sees the two spellings of one glyph as different strings. This
+ * module is the single place the projection resolves spelling (1) into the
+ * characters spelling (2) would have contributed.
+ *
+ * The font is deliberately **not** part of the projected value. The projections
+ * that consume this are text projections: they already exclude `w:rFonts`, so
+ * folding `w:sym/@w:font` in would make the same font signal visible for one
+ * spelling of a glyph and invisible for the other, and would make the two
+ * spellings compare unequal by construction — the exact false difference this
+ * resolution exists to remove. A font-only change is a formatting change and
+ * belongs to the formatting-fidelity surface, not the round-trip text gate;
+ * that residual is tracked separately.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.3.3.30
+ * @see https://github.com/UseJunior/safe-docx/issues/793
+ * @see https://github.com/UseJunior/safe-docx/issues/799
+ */
+import { OOXML } from './namespaces.js';
+/** Local name of the symbol-character run-content element. */
+export const SYM_LOCAL_NAME = 'sym';
+/**
+ * `w:sym/@w:char` is `ST_ShortHexNumber` — `xsd:hexBinary` restricted to
+ * `length="2"`, i.e. exactly two bytes, four hexadecimal digits. Every legal
+ * value is therefore a BMP codepoint and `String.fromCharCode` is total over
+ * the domain. Four digits exactly: `A` and `ABC` are outside the lexical space
+ * and must not be read as characters.
+ */
+const SHORT_HEX_NUMBER = /^[0-9A-Fa-f]{4}$/u;
+/**
+ * Projection identity for a `w:sym` whose `@w:char` is absent or outside
+ * `ST_ShortHexNumber`. Both `CT_Sym` attributes are optional in the vendored
+ * schema, so such an element is not schema-invalid — it is semantically
+ * unresolvable, and it is still *content*. Projecting nothing would reopen the
+ * blindness this module closes.
+ *
+ * It is a framed token rather than a character (U+FFFD was the obvious choice
+ * and is wrong: a document may author U+FFFD literally, and an unresolvable
+ * symbol would then compare equal to that text). The framing follows the
+ * `__safe_docx_pageref__|` convention already used for stable comparison
+ * identities in `docx-compare`.
+ */
+const UNRESOLVED_SYMBOL_IDENTITY = '__safe_docx_sym__|unresolved';
+function isSymElement(element) {
+    // The namespace check alone is sufficient, and a qualified-name fallback
+    // would be dead code: `parseXml` rejects an undeclared prefix outright
+    // (`NamespaceError: prefix is non-null and namespace is null`), so nothing
+    // reaching this function can be named `w:sym` with a null namespace.
+    return element.namespaceURI === OOXML.W_NS && element.localName === SYM_LOCAL_NAME;
+}
+/**
+ * Project a `<w:sym>` element to the text it contributes, or `undefined` when
+ * `element` is not a `w:sym`.
+ *
+ * For a resolvable `@w:char` the result is exactly the character the glyph
+ * stands for — what it would have contributed had it been spelled as literal
+ * `w:t` content. Otherwise it is a framed, projection-only identity that keeps
+ * the element's presence visible without colliding with authored text.
+ */
+export function projectSymbolRun(element) {
+    if (!isSymElement(element))
+        return undefined;
+    const raw = element.getAttributeNS(OOXML.W_NS, 'char') ?? element.getAttribute('w:char');
+    if (raw === null || !SHORT_HEX_NUMBER.test(raw))
+        return UNRESOLVED_SYMBOL_IDENTITY;
+    return String.fromCharCode(Number.parseInt(raw, 16));
+}
+//# sourceMappingURL=symbol_run_content.js.map

package/dist/primitives/symbol_run_content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol_run_content.js","sourceRoot":"","sources":["../../src/primitives/symbol_run_content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAExC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,MAAM,0BAA0B,GAAG,8BAA8B,CAAC;AAElE,SAAS,YAAY,CAAC,OAAgB;IACpC,yEAAyE;IACzE,uEAAuE;IACvE,2EAA2E;IAC3E,qEAAqE;IACrE,OAAO,OAAO,CAAC,YAAY,KAAK,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC,SAAS,KAAK,cAAc,CAAC;AACrF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,GAAG,GACP,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/E,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,0BAA0B,CAAC;IACnF,OAAO,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/primitives/text.d.ts

@@ -3,7 +3,17 @@ export type TextRun = {
     r: Element;
     text: string;
     isFieldResult: boolean;
+    fieldResultId?: number | null;
+    fieldInstruction?: string | null;
 };
+/**
+ * Return the paragraph's visible runs while retaining enough complex-field
+ * provenance to distinguish a safe cached-result edit from a field-boundary
+ * rewrite.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.16.18
+ * @see #651
+ */
 export declare function getParagraphRuns(p: Element): TextRun[];
 export declare function getParagraphText(p: Element): string;
 export declare function visibleLengthForEl(el: Element): number;
@@ -27,5 +37,24 @@ export type ReplacementPart = {
     addRunProps?: AddRunProps;
     clearHighlight?: boolean;
 };
+/**
+ * Replace a visible paragraph range while keeping tracked runs inside their
+ * existing run container. In particular, edits wholly inside `w:hyperlink`
+ * remain nested there, while cross-container ranges are refused before the
+ * DOM is changed.
+ *
+ * Embedded content (`w:drawing`, `w:pict`, `w:object`, `w:contentPart`)
+ * inside the replaced range is preserved as live runs: it contributes no
+ * visible text, so no text match ever covers it and no text edit may delete
+ * it. Tracked deletions around preserved content are emitted as in-place
+ * segments so rejectChanges() restores the original content order exactly.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.5.14
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.5.15
+ * @conformance ECMA-376 edition 5, Part 1 § 17.16.22
+ * @see #652
+ * @see #741
+ * @see #739
+ */
 export declare function replaceParagraphTextRange(p: Element, start: number, end: number, replacement: string | ReplacementPart[], ctx?: RevisionContext): void;
 //# sourceMappingURL=text.d.ts.map

package/dist/primitives/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/primitives/text.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,MAAM,OAAO,GAAG;IACpB,CAAC,EAAE,OAAO,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAsDtD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAInD;AAoGD,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAMtD;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,EAAE,CAWhE;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAgEvG;AA0BD,MAAM,MAAM,WAAW,GAAG;IAGxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AA2KF,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,OAAO,EACV,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAAG,eAAe,EAAE,EACvC,GAAG,CAAC,EAAE,eAAe,GACpB,IAAI,CAsJN"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/primitives/text.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,MAAM,OAAO,GAAG;IACpB,CAAC,EAAE,OAAO,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,CAqGtD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAInD;AA6GD,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAMtD;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,EAAE,CAWhE;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAgEvG;AAkDD,MAAM,MAAM,WAAW,GAAG;IAGxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAyRF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,OAAO,EACV,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAAG,eAAe,EAAE,EACvC,GAAG,CAAC,EAAE,eAAe,GACpB,IAAI,CAkSN"}