@folijs/docx 0.6.0 → 1.0.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 (123) hide show
  1. package/CHANGELOG.md +124 -0
  2. package/README.md +12 -3
  3. package/dist/custom.d.ts +2 -0
  4. package/dist/custom.d.ts.map +1 -0
  5. package/dist/custom.js +216 -0
  6. package/dist/custom.js.map +1 -0
  7. package/dist/export/balance.d.ts +1 -16
  8. package/dist/export/balance.d.ts.map +1 -1
  9. package/dist/export/balance.js +1 -0
  10. package/dist/export/balance.js.map +1 -1
  11. package/dist/export/content.d.ts +1 -19
  12. package/dist/export/content.d.ts.map +1 -1
  13. package/dist/export/content.js +2 -0
  14. package/dist/export/content.js.map +1 -1
  15. package/dist/export/controls.d.ts +1 -17
  16. package/dist/export/controls.d.ts.map +1 -1
  17. package/dist/export/controls.js +1 -0
  18. package/dist/export/controls.js.map +1 -1
  19. package/dist/export/index.d.ts +8 -2
  20. package/dist/export/index.d.ts.map +1 -1
  21. package/dist/export/index.js +6 -2
  22. package/dist/export/index.js.map +1 -1
  23. package/dist/export/parts.d.ts +1 -24
  24. package/dist/export/parts.d.ts.map +1 -1
  25. package/dist/export/parts.js +23 -9
  26. package/dist/export/parts.js.map +1 -1
  27. package/dist/export/pictures.d.ts +0 -45
  28. package/dist/export/pictures.d.ts.map +1 -1
  29. package/dist/export/pictures.js +9 -2
  30. package/dist/export/pictures.js.map +1 -1
  31. package/dist/export/properties.d.ts +1 -41
  32. package/dist/export/properties.d.ts.map +1 -1
  33. package/dist/export/properties.js +19 -14
  34. package/dist/export/properties.js.map +1 -1
  35. package/dist/export/tables.d.ts +0 -19
  36. package/dist/export/tables.d.ts.map +1 -1
  37. package/dist/export/tables.js +15 -3
  38. package/dist/export/tables.js.map +1 -1
  39. package/dist/export/xmlout.d.ts +1 -61
  40. package/dist/export/xmlout.d.ts.map +1 -1
  41. package/dist/export/xmlout.js +34 -7
  42. package/dist/export/xmlout.js.map +1 -1
  43. package/dist/import/content.d.ts +1 -43
  44. package/dist/import/content.d.ts.map +1 -1
  45. package/dist/import/content.js +4 -1
  46. package/dist/import/content.js.map +1 -1
  47. package/dist/import/controls.d.ts +1 -13
  48. package/dist/import/controls.d.ts.map +1 -1
  49. package/dist/import/controls.js +5 -7
  50. package/dist/import/controls.js.map +1 -1
  51. package/dist/import/index.d.ts +1 -9
  52. package/dist/import/index.d.ts.map +1 -1
  53. package/dist/import/index.js +12 -5
  54. package/dist/import/index.js.map +1 -1
  55. package/dist/import/ooxml.d.ts +1 -41
  56. package/dist/import/ooxml.d.ts.map +1 -1
  57. package/dist/import/ooxml.js +40 -8
  58. package/dist/import/ooxml.js.map +1 -1
  59. package/dist/import/parts.d.ts +1 -33
  60. package/dist/import/parts.d.ts.map +1 -1
  61. package/dist/import/parts.js +35 -9
  62. package/dist/import/parts.js.map +1 -1
  63. package/dist/import/pictures.d.ts +1 -33
  64. package/dist/import/pictures.d.ts.map +1 -1
  65. package/dist/import/pictures.js +7 -1
  66. package/dist/import/pictures.js.map +1 -1
  67. package/dist/import/properties.d.ts +1 -45
  68. package/dist/import/properties.d.ts.map +1 -1
  69. package/dist/import/properties.js +30 -7
  70. package/dist/import/properties.js.map +1 -1
  71. package/dist/import/report.d.ts +0 -10
  72. package/dist/import/report.d.ts.map +1 -1
  73. package/dist/import/report.js +1 -0
  74. package/dist/import/report.js.map +1 -1
  75. package/dist/import/stories.d.ts +1 -18
  76. package/dist/import/stories.d.ts.map +1 -1
  77. package/dist/import/stories.js +16 -4
  78. package/dist/import/stories.js.map +1 -1
  79. package/dist/import/tables.d.ts +0 -24
  80. package/dist/import/tables.d.ts.map +1 -1
  81. package/dist/import/tables.js +25 -6
  82. package/dist/import/tables.js.map +1 -1
  83. package/dist/package.d.ts +8 -4
  84. package/dist/package.d.ts.map +1 -1
  85. package/dist/package.js +38 -4
  86. package/dist/package.js.map +1 -1
  87. package/dist/settings.d.ts +1 -21
  88. package/dist/settings.d.ts.map +1 -1
  89. package/dist/settings.js +17 -4
  90. package/dist/settings.js.map +1 -1
  91. package/dist/xml.d.ts +8 -0
  92. package/dist/xml.d.ts.map +1 -1
  93. package/dist/xml.js +30 -2
  94. package/dist/xml.js.map +1 -1
  95. package/dist/zip.d.ts +0 -47
  96. package/dist/zip.d.ts.map +1 -1
  97. package/dist/zip.js +11 -2
  98. package/dist/zip.js.map +1 -1
  99. package/package.json +5 -4
  100. package/src/custom.ts +254 -0
  101. package/src/export/balance.ts +1 -0
  102. package/src/export/content.ts +3 -0
  103. package/src/export/controls.ts +1 -0
  104. package/src/export/index.ts +16 -5
  105. package/src/export/parts.ts +23 -8
  106. package/src/export/pictures.ts +13 -3
  107. package/src/export/properties.ts +22 -16
  108. package/src/export/tables.ts +15 -3
  109. package/src/export/xmlout.ts +36 -7
  110. package/src/import/content.ts +6 -7
  111. package/src/import/controls.ts +6 -2
  112. package/src/import/index.ts +31 -23
  113. package/src/import/ooxml.ts +40 -8
  114. package/src/import/parts.ts +43 -18
  115. package/src/import/pictures.ts +8 -1
  116. package/src/import/properties.ts +32 -7
  117. package/src/import/report.ts +1 -0
  118. package/src/import/stories.ts +16 -4
  119. package/src/import/tables.ts +25 -6
  120. package/src/package.ts +56 -6
  121. package/src/settings.ts +17 -4
  122. package/src/xml.ts +42 -2
  123. package/src/zip.ts +17 -5
@@ -6,7 +6,8 @@
6
6
  * does not model stay where Word requires them.
7
7
  */
8
8
 
9
- import { type MarkJSON, schema } from "@folijs/core";
9
+ import type { MarkJSON } from "@folijs/core";
10
+ import { schema } from "@folijs/core/internal";
10
11
  import { W } from "../import/ooxml.js";
11
12
  import {
12
13
  paragraphProperties,
@@ -20,7 +21,10 @@ import { attributesOf, el, fragment, merged, type Namespaces, onOff, val } from
20
21
  type Original = { element: XmlElement; source: string } | undefined;
21
22
  type Json = Record<string, unknown>;
22
23
 
23
- /** Structural equality of JSON values, key order aside. */
24
+ /**
25
+ * Structural equality of JSON values, key order aside.
26
+ * @internal
27
+ */
24
28
  export function same(a: unknown, b: unknown): boolean {
25
29
  if (a === b) return true;
26
30
  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
@@ -32,7 +36,8 @@ export function same(a: unknown, b: unknown): boolean {
32
36
  return ka.length === kb.length && ka.every((k) => same((a as Json)[k], (b as Json)[k]));
33
37
  }
34
38
 
35
- const reading = (original: NonNullable<Original>) => ({
39
+ /** @internal */
40
+ export const reading = (original: NonNullable<Original>) => ({
36
41
  source: original.source,
37
42
  report: new Recorder(),
38
43
  });
@@ -52,8 +57,9 @@ function canonicalMarks(marks: readonly MarkJSON[]): MarkJSON[] {
52
57
  /**
53
58
  * Children of `original` named `locals`, as written, when `unchanged`; otherwise `fresh()`.
54
59
  * One property may span several children (`w:b` and `w:bCs`).
60
+ * @internal
55
61
  */
56
- function child(
62
+ export function keptOrFresh(
57
63
  original: Original,
58
64
  unchanged: boolean,
59
65
  locals: readonly string[],
@@ -68,11 +74,6 @@ function child(
68
74
  return out;
69
75
  }
70
76
 
71
- function wrap(name: string, original: Original, children: string): string {
72
- const attributes = attributesOf(original);
73
- return children || attributes ? `<${name}${attributes}>${children}</${name}>` : "";
74
- }
75
-
76
77
  // ---- w:rPr -------------------------------------------------------------------------------
77
78
 
78
79
  /** CT_ParaRPr / CT_RPr child order (ECMA-376 Part 1, 17.3.1.29 and 17.3.2.28). */
@@ -230,6 +231,7 @@ const RUN_MODELED = new Set(Object.values(MARK_CHILDREN).flat());
230
231
  * writes `<w:rPr/>` even when empty. With `properties` (a style's, a level's, the defaults', a
231
232
  * paragraph mark's, a recorded change's previous properties) the model holds no formatting
232
233
  * change: a `w:rPrChange` stays as the original has it.
234
+ * @internal
233
235
  */
234
236
  export function runPropertiesXml(
235
237
  marks: readonly MarkJSON[],
@@ -255,7 +257,9 @@ export function runPropertiesXml(
255
257
  if (!owned(type)) continue;
256
258
  const now = current.find((m) => m.type === type);
257
259
  const before = reread.find((m) => m.type === type);
258
- const text = child(original, same(now, before), locals, () => markChildren(now, type, ns));
260
+ const text = keptOrFresh(original, same(now, before), locals, () =>
261
+ markChildren(now, type, ns),
262
+ );
259
263
  generated.set(locals[0] as string, text);
260
264
  for (const local of locals.slice(1)) generated.set(local, "");
261
265
  }
@@ -443,7 +447,7 @@ function markRunProperties(attrs: Json, original: Original, ns: Namespaces): str
443
447
  for (const local of ["ins", "del", "moveFrom", "moveTo"])
444
448
  generated.set(
445
449
  local,
446
- child(sub, true, [local], () => ""),
450
+ keptOrFresh(sub, true, [local], () => ""),
447
451
  );
448
452
  } else {
449
453
  generated.set("ins", change("ins", revision.insertion as Json | undefined));
@@ -470,6 +474,7 @@ const PARAGRAPH_ONLY = new Set(["section", "formatChange", "revision", "markForm
470
474
  * read from. With `properties` (a style's, a level's, the defaults', a recorded change's
471
475
  * previous properties) the model does not hold the mark's run properties, a section or a
472
476
  * formatting change there: those stay as the original has them.
477
+ * @internal
473
478
  */
474
479
  export function paragraphPropertiesXml(
475
480
  attrs: Json,
@@ -498,7 +503,7 @@ export function paragraphPropertiesXml(
498
503
  if (properties && PARAGRAPH_ONLY.has(prop)) continue;
499
504
  generated.set(
500
505
  local,
501
- child(original, same(current[prop], reread[prop]), [local], () =>
506
+ keptOrFresh(original, same(current[prop], reread[prop]), [local], () =>
502
507
  paragraphChild(prop, current[prop], ns),
503
508
  ),
504
509
  );
@@ -651,7 +656,10 @@ function sectionChild(name: string, value: unknown, ns: Namespaces): string {
651
656
  }
652
657
  }
653
658
 
654
- /** A section as `w:sectPr` (always written: an empty one is a section break with Word's defaults). */
659
+ /**
660
+ * A section as `w:sectPr` (always written: an empty one is a section break with Word's defaults).
661
+ * @internal
662
+ */
655
663
  export function sectionXml(section: Json, ns: Namespaces): string {
656
664
  const ext = section.ext as string | undefined;
657
665
  const original = ext ? fragment(ext, ns, "sectPr") : undefined;
@@ -662,7 +670,7 @@ export function sectionXml(section: Json, ns: Namespaces): string {
662
670
  for (const [prop, locals] of Object.entries(SECTION_CHILDREN)) {
663
671
  generated.set(
664
672
  locals[0] as string,
665
- child(original, same(section[prop], reread[prop]), locals, () =>
673
+ keptOrFresh(original, same(section[prop], reread[prop]), locals, () =>
666
674
  sectionChild(prop, section[prop], ns),
667
675
  ),
668
676
  );
@@ -670,5 +678,3 @@ export function sectionXml(section: Json, ns: Namespaces): string {
670
678
  const children = merged(SECT_ORDER, SECTION_MODELED, generated, original);
671
679
  return `<w:sectPr${attributesOf(original)}>${children}</w:sectPr>`;
672
680
  }
673
-
674
- export { child as keptOrFresh, reading, wrap };
@@ -351,20 +351,29 @@ function propertiesXml(spec: Spec, attrs: Json, ns: Namespaces, always: boolean)
351
351
  : "";
352
352
  }
353
353
 
354
- /** A table's `w:tblPr` (always written: Word requires it). */
354
+ /**
355
+ * A table's `w:tblPr` (always written: Word requires it).
356
+ * @internal
357
+ */
355
358
  export const tablePropertiesXml = (attrs: Json, ns: Namespaces) =>
356
359
  propertiesXml(TABLE, attrs, ns, true);
357
360
 
361
+ /** @internal */
358
362
  export const exceptionsXml = (exceptions: unknown, ns: Namespaces) =>
359
363
  exceptions ? propertiesXml(EXCEPTIONS, exceptions as Json, ns, false) : "";
360
364
 
365
+ /** @internal */
361
366
  export const rowPropertiesXml = (attrs: Json, ns: Namespaces) =>
362
367
  propertiesXml(ROW, attrs, ns, false);
363
368
 
369
+ /** @internal */
364
370
  export const cellPropertiesXml = (attrs: Json, ns: Namespaces) =>
365
371
  propertiesXml(CELL, attrs, ns, false);
366
372
 
367
- /** A new table style's `w:tblPr`, `w:trPr` and `w:tcPr` (empty for a part it does not set). */
373
+ /**
374
+ * A new table style's `w:tblPr`, `w:trPr` and `w:tcPr` (empty for a part it does not set).
375
+ * @internal
376
+ */
368
377
  export const stylePartsXml = (
369
378
  style: { table?: unknown; row?: unknown; cell?: unknown },
370
379
  ns: Namespaces,
@@ -374,7 +383,10 @@ export const stylePartsXml = (
374
383
  tcPr: style.cell ? propertiesXml(CELL, style.cell as Json, ns, false) : "",
375
384
  });
376
385
 
377
- /** `w:tblGrid`: as read while the widths are the same, else written from them. */
386
+ /**
387
+ * `w:tblGrid`: as read while the widths are the same, else written from them.
388
+ * @internal
389
+ */
378
390
  export function gridXml(attrs: Json, ns: Namespaces): string {
379
391
  const widths = (attrs.grid ?? []) as number[];
380
392
  const ext = attrs.gridExt as string | undefined;
@@ -7,6 +7,7 @@ import { parseXml, type XmlElement } from "../xml.js";
7
7
  /**
8
8
  * Throws when `text` has a character XML 1.0 cannot hold (control characters other than tab
9
9
  * and line ends, lone surrogates, U+FFFE, U+FFFF): no file Word opens could carry it.
10
+ * @internal
10
11
  */
11
12
  export function checkCharacters(text: string, where: string): void {
12
13
  for (let i = 0; i < text.length; i++) {
@@ -26,21 +27,31 @@ export function checkCharacters(text: string, where: string): void {
26
27
  }
27
28
  }
28
29
 
29
- /** Character data: `&`, `<`, `>` escaped (characters XML cannot hold refused). */
30
+ /**
31
+ * Character data: `&`, `<`, `>` escaped (characters XML cannot hold refused).
32
+ * @internal
33
+ */
30
34
  export function escapeText(text: string): string {
31
35
  checkCharacters(text, "text");
32
36
  return text.replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
33
37
  }
34
38
 
35
- /** An attribute value: also `"`, and tabs and line ends as references (XML normalizes them). */
39
+ /**
40
+ * An attribute value: also `"`, and tabs and line ends as references (XML normalizes them).
41
+ * @internal
42
+ */
36
43
  export function escapeAttribute(value: string): string {
37
44
  checkCharacters(value, "attribute");
38
45
  return value.replace(/[&<>"\t\n\r]/g, (c) => `&#${c.charCodeAt(0)};`);
39
46
  }
40
47
 
48
+ /** @internal */
41
49
  export type Attrs = Readonly<Record<string, string | number | boolean | undefined | null>>;
42
50
 
43
- /** `<name a="1">children</name>`, or `<name a="1"/>` without children; undefined attributes left out. */
51
+ /**
52
+ * `<name a="1">children</name>`, or `<name a="1"/>` without children; undefined attributes left out.
53
+ * @internal
54
+ */
44
55
  export function el(name: string, attrs: Attrs = {}, children = ""): string {
45
56
  let out = `<${name}`;
46
57
  for (const [key, value] of Object.entries(attrs)) {
@@ -50,12 +61,18 @@ export function el(name: string, attrs: Attrs = {}, children = ""): string {
50
61
  return children ? `${out}>${children}</${name}>` : `${out}/>`;
51
62
  }
52
63
 
53
- /** `w:` element with a `w:val`. */
64
+ /**
65
+ * `w:` element with a `w:val`.
66
+ * @internal
67
+ */
54
68
  export function val(local: string, value: string | number | undefined): string {
55
69
  return value === undefined ? "" : el(`w:${local}`, { "w:val": value });
56
70
  }
57
71
 
58
- /** An on/off property: `<w:b/>`, or `<w:b w:val="0"/>` when off. */
72
+ /**
73
+ * An on/off property: `<w:b/>`, or `<w:b w:val="0"/>` when off.
74
+ * @internal
75
+ */
59
76
  export function onOff(local: string, value: boolean | null | undefined): string {
60
77
  if (value === undefined || value === null) return "";
61
78
  return value ? el(`w:${local}`) : el(`w:${local}`, { "w:val": "0" });
@@ -64,6 +81,7 @@ export function onOff(local: string, value: boolean | null | undefined): string
64
81
  /**
65
82
  * Namespace declarations in scope for a part's verbatim fragments: its root's `xmlns`
66
83
  * attributes, written on a wrapper so a fragment such as `<w:pPr>…</w:pPr>` parses.
84
+ * @internal
67
85
  */
68
86
  export interface Namespaces {
69
87
  readonly declarations: string;
@@ -99,6 +117,7 @@ const WORD_NAMESPACES: Record<string, string> = {
99
117
  pic: "http://schemas.openxmlformats.org/drawingml/2006/picture",
100
118
  };
101
119
 
120
+ /** @internal */
102
121
  export const DEFAULT_NAMESPACES: Namespaces = {
103
122
  declarations: Object.entries(WORD_NAMESPACES)
104
123
  .map(([prefix, uri]) => `xmlns:${prefix}="${uri}"`)
@@ -106,9 +125,13 @@ export const DEFAULT_NAMESPACES: Namespaces = {
106
125
  prefixes: new Set(Object.keys(WORD_NAMESPACES)),
107
126
  };
108
127
 
109
- /** Attributes of a new part's root: Word's namespaces, its extensions ignorable. */
128
+ /**
129
+ * Attributes of a new part's root: Word's namespaces, its extensions ignorable.
130
+ * @internal
131
+ */
110
132
  export const NEW_ROOT_ATTRIBUTES = `${DEFAULT_NAMESPACES.declarations} mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh w16du wp14"`;
111
133
 
134
+ /** @internal */
112
135
  export function namespacesOf(root: XmlElement, source: string): Namespaces {
113
136
  const declared = root.attributes.filter((a) => a.name === "xmlns" || a.prefix === "xmlns");
114
137
  if (!declared.length) return DEFAULT_NAMESPACES;
@@ -122,6 +145,7 @@ export function namespacesOf(root: XmlElement, source: string): Namespaces {
122
145
  * A verbatim fragment (`ext`, `runExt`, an opaque node's XML) parsed in the part's namespaces:
123
146
  * exactly one element (named `expected` when given), with its offsets into the returned
124
147
  * source. Anything else could not be written into the part as well-formed XML: DocxError.
148
+ * @internal
125
149
  */
126
150
  export function fragment(
127
151
  xml: string,
@@ -152,6 +176,7 @@ export function fragment(
152
176
  * An element's `attributes` bag as written (` name="value"`…). A name the writer already
153
177
  * writes, or a prefix not declared in the part (nor by the bag itself), would make the element
154
178
  * ill-formed: DocxError.
179
+ * @internal
155
180
  */
156
181
  export function bagXml(
157
182
  bag: unknown,
@@ -189,6 +214,7 @@ export function bagXml(
189
214
  * not come back from the original). Every other child of `original` (unknown to Foli) is kept
190
215
  * verbatim at its place in `order`, or at the end when `order` does not name it (extensions
191
216
  * such as `w14:ligatures`, which Word writes last).
217
+ * @internal
192
218
  */
193
219
  export function merged(
194
220
  order: readonly string[],
@@ -213,7 +239,10 @@ export function merged(
213
239
  return out + tail.join("");
214
240
  }
215
241
 
216
- /** The original element's own attributes, as written (`w:rsidR`… on `w:pPr` is rare but kept). */
242
+ /**
243
+ * The original element's own attributes, as written (`w:rsidR`… on `w:pPr` is rare but kept).
244
+ * @internal
245
+ */
217
246
  export function attributesOf(
218
247
  original: { element: XmlElement; source: string } | undefined,
219
248
  ): string {
@@ -4,13 +4,8 @@
4
4
  * for markers that have nothing to show: field characters, range ends).
5
5
  */
6
6
 
7
- import {
8
- type ControlJSON,
9
- type MarkJSON,
10
- type NodeJSON,
11
- type ResourceJSON,
12
- schema,
13
- } from "@folijs/core";
7
+ import type { ControlJSON, MarkJSON, NodeJSON, ResourceJSON } from "@folijs/core";
8
+ import { schema } from "@folijs/core/internal";
14
9
  import type { DocxPackage, Relationship } from "../package.js";
15
10
  import type { XmlElement, XmlNode } from "../xml.js";
16
11
  import { controlProperties } from "./controls.js";
@@ -28,6 +23,7 @@ import {
28
23
  } from "./properties.js";
29
24
  import { cellProperties, grid, rowProperties, tableProperties } from "./tables.js";
30
25
 
26
+ /** @internal */
31
27
  export interface ContentContext extends Context {
32
28
  readonly pkg: DocxPackage;
33
29
  /** The part the content is in: relationship ids (hyperlinks) resolve against it. */
@@ -117,6 +113,7 @@ function label(table: Record<string, string | null>, element: XmlElement): strin
117
113
  /**
118
114
  * Block content: paragraphs, and every other block element as an opaque block. `section` is the
119
115
  * body's last `w:sectPr` (the envelope's): any other one stays as an opaque block.
116
+ * @internal
120
117
  */
121
118
  export function blocks(
122
119
  nodes: readonly XmlNode[],
@@ -329,6 +326,7 @@ function withLabel(attrs: Record<string, unknown>, value: string | null): Record
329
326
  return value === null ? attrs : { ...attrs, label: value.slice(0, 255) || null };
330
327
  }
331
328
 
329
+ /** @internal */
332
330
  export function paragraph(p: XmlElement, context: ContentContext): NodeJSON {
333
331
  // A story ends no section: such a paragraph stays as it is.
334
332
  const pPr = child(p, "pPr");
@@ -496,6 +494,7 @@ function valid(json: NodeJSON, el: XmlElement, context: Context): NodeJSON | und
496
494
  /**
497
495
  * The tracked moves open at a point (`w:moveFromRangeStart` … `End`, by range id): the innermost
498
496
  * open one names the moved content. Amortized constant time per operation.
497
+ * @internal
499
498
  */
500
499
  export class Moves {
501
500
  readonly #stacks = {
@@ -3,7 +3,8 @@
3
3
  * elements they were read from kept verbatim in `ext`. Export reads the same way, to tell what a
4
4
  * control says differently from its `ext`.
5
5
  */
6
- import { type ControlJSON, checkControl } from "@folijs/core";
6
+ import type { ControlJSON } from "@folijs/core";
7
+ import { checkControl } from "@folijs/core/internal";
7
8
  import type { DocxPackage } from "../package.js";
8
9
  import type { XmlElement } from "../xml.js";
9
10
  import { attr, child, deepText, elements, isW, W, W14, W15 } from "./ooxml.js";
@@ -55,7 +56,10 @@ function glossaryTexts(pkg: DocxPackage): ReadonlyMap<string, string> {
55
56
  return texts;
56
57
  }
57
58
 
58
- /** The properties of `sdt`'s `w:sdtPr` and `w:sdtEndPr`, or undefined if the model cannot hold them. */
59
+ /**
60
+ * The properties of `sdt`'s `w:sdtPr` and `w:sdtEndPr`, or undefined if the model cannot hold them.
61
+ * @internal
62
+ */
59
63
  export function controlProperties(
60
64
  sdt: XmlElement,
61
65
  context: Context & { pkg?: DocxPackage },
@@ -7,6 +7,7 @@ import {
7
7
  type StoryJSON,
8
8
  type WordSettingsJSON,
9
9
  } from "@folijs/core";
10
+ import { customFromWord } from "../custom.js";
10
11
  import {
11
12
  DocxError,
12
13
  type DocxPackage,
@@ -23,8 +24,6 @@ import { section } from "./properties.js";
23
24
  import { type ImportReport, Recorder } from "./report.js";
24
25
  import { canonicalStories, readStories } from "./stories.js";
25
26
 
26
- export { noteIds } from "./stories.js";
27
-
28
27
  export interface DocxImport {
29
28
  /** The document in the current schema (v5), validated. */
30
29
  readonly document: FoliDocument;
@@ -146,25 +145,28 @@ export function importPackage(pkg: DocxPackage): DocxImport {
146
145
 
147
146
  let document: FoliDocument;
148
147
  try {
149
- document = parseDocument({
150
- schemaVersion: SCHEMA_VERSION,
151
- section: lastSection,
152
- ...(settings ? { settings } : {}),
153
- defaults: styled.defaults,
154
- styles: styled.styles,
155
- numbering: numbered,
156
- ...(themed ? { theme: themed } : {}),
157
- comments: commented,
158
- ...(resources.size ? { resources: Object.fromEntries(resources) } : {}),
159
- ...(Object.keys(stories).length ? { stories } : {}),
160
- ...(settings ? { settings } : {}),
161
- ...(usedControls.size
162
- ? {
163
- controls: Object.fromEntries([...controls].filter(([id]) => usedControls.has(id))),
164
- }
165
- : {}),
166
- content: { type: "doc", content },
167
- });
148
+ // Controls Foli tagged for custom nodes and marks are those again (ADR-0008).
149
+ document = parseDocument(
150
+ customFromWord({
151
+ schemaVersion: SCHEMA_VERSION,
152
+ section: lastSection,
153
+ ...(settings ? { settings } : {}),
154
+ defaults: styled.defaults,
155
+ styles: styled.styles,
156
+ numbering: numbered,
157
+ ...(themed ? { theme: themed } : {}),
158
+ comments: commented,
159
+ ...(resources.size ? { resources: Object.fromEntries(resources) } : {}),
160
+ ...(Object.keys(stories).length ? { stories } : {}),
161
+ ...(settings ? { settings } : {}),
162
+ ...(usedControls.size
163
+ ? {
164
+ controls: Object.fromEntries([...controls].filter(([id]) => usedControls.has(id))),
165
+ }
166
+ : {}),
167
+ content: { type: "doc", content },
168
+ } as FoliDocument),
169
+ );
168
170
  } catch (error) {
169
171
  // Each value was checked as it was read; what is left is beyond the model's limits (an
170
172
  // element over 16 MiB kept verbatim…). A DocxError like every other import failure.
@@ -173,7 +175,10 @@ export function importPackage(pkg: DocxPackage): DocxImport {
173
175
  return { document, package: pkg, report: report.report(), trackRevisions };
174
176
  }
175
177
 
176
- /** The ids of the controls `content` holds (one read but kept verbatim after all has none). */
178
+ /**
179
+ * The ids of the controls `content` holds (one read but kept verbatim after all has none).
180
+ * @internal
181
+ */
177
182
  export function controlsUsed(content: unknown): Set<string> {
178
183
  const used = new Set<string>();
179
184
  JSON.stringify(content, (key, value) => {
@@ -186,7 +191,10 @@ export function controlsUsed(content: unknown): Set<string> {
186
191
  return used;
187
192
  }
188
193
 
189
- /** The package's stories and their controls, as a validated document holds them. */
194
+ /**
195
+ * The package's stories and their controls, as a validated document holds them.
196
+ * @internal
197
+ */
190
198
  export function packageStories(pkg: DocxPackage): {
191
199
  stories: Record<string, StoryJSON>;
192
200
  controls: Map<string, ControlJSON>;
@@ -2,14 +2,23 @@
2
2
 
3
3
  import type { XmlElement, XmlNode } from "../xml.js";
4
4
 
5
+ /** @internal */
5
6
  export const W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
6
- /** Strict Open XML's WordprocessingML namespace (not supported yet: other units and names). */
7
+ /**
8
+ * Strict Open XML's WordprocessingML namespace (not supported yet: other units and names).
9
+ * @internal
10
+ */
7
11
  export const W_STRICT = "http://purl.oclc.org/ooxml/wordprocessingml/main";
12
+ /** @internal */
8
13
  export const R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
14
+ /** @internal */
9
15
  export const W14 = "http://schemas.microsoft.com/office/word/2010/wordml";
16
+ /** @internal */
10
17
  export const W15 = "http://schemas.microsoft.com/office/word/2012/wordml";
18
+ /** @internal */
11
19
  export const A = "http://schemas.openxmlformats.org/drawingml/2006/main";
12
20
 
21
+ /** @internal */
13
22
  export const REL = {
14
23
  styles: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
15
24
  numbering: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering",
@@ -24,31 +33,47 @@ export const REL = {
24
33
  endnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes",
25
34
  };
26
35
 
27
- /** Whether `node` is the WordprocessingML element `local`. */
36
+ /**
37
+ * Whether `node` is the WordprocessingML element `local`.
38
+ * @internal
39
+ */
28
40
  export function isW(node: XmlNode, local?: string): boolean {
29
41
  return node.kind === "element" && node.ns === W && (local === undefined || node.local === local);
30
42
  }
31
43
 
44
+ /** @internal */
32
45
  export function elements(element: XmlElement): XmlElement[] {
33
46
  return element.children.filter((child): child is XmlElement => child.kind === "element");
34
47
  }
35
48
 
36
- /** The first WordprocessingML child named `local`. */
49
+ /**
50
+ * The first WordprocessingML child named `local`.
51
+ * @internal
52
+ */
37
53
  export function child(element: XmlElement, local: string): XmlElement | undefined {
38
54
  return element.children.find((c): c is XmlElement => c.kind === "element" && isW(c, local));
39
55
  }
40
56
 
41
- /** A WordprocessingML attribute (`w:val`) of `element`. */
57
+ /**
58
+ * A WordprocessingML attribute (`w:val`) of `element`.
59
+ * @internal
60
+ */
42
61
  export function attr(element: XmlElement | undefined, local: string, ns = W): string | undefined {
43
62
  return element?.attributes.find((a) => a.local === local && a.ns === ns)?.value;
44
63
  }
45
64
 
46
- /** The text of an element's character data children (`w:t`, `w:delText`, `w:instrText`). */
65
+ /**
66
+ * The text of an element's character data children (`w:t`, `w:delText`, `w:instrText`).
67
+ * @internal
68
+ */
47
69
  export function textOf(element: XmlElement): string {
48
70
  return element.children.map((c) => (c.kind === "text" ? c.text : "")).join("");
49
71
  }
50
72
 
51
- /** Every `w:t` and `w:delText` of an element's descendants, in order (the text it shows). */
73
+ /**
74
+ * Every `w:t` and `w:delText` of an element's descendants, in order (the text it shows).
75
+ * @internal
76
+ */
52
77
  export function deepText(element: XmlElement): string {
53
78
  let out = "";
54
79
  for (const c of element.children) {
@@ -58,7 +83,10 @@ export function deepText(element: XmlElement): string {
58
83
  return out;
59
84
  }
60
85
 
61
- /** An integer as Word writes it; undefined for anything else (universal measures, decimals). */
86
+ /**
87
+ * An integer as Word writes it; undefined for anything else (universal measures, decimals).
88
+ * @internal
89
+ */
62
90
  export function integer(value: string | undefined): number | undefined {
63
91
  return value !== undefined && /^-?\d+$/.test(value) ? Number.parseInt(value, 10) : undefined;
64
92
  }
@@ -66,6 +94,7 @@ export function integer(value: string | undefined): number | undefined {
66
94
  /**
67
95
  * An on/off property (ST_OnOff): absent value is on. Undefined for a value that is not one of
68
96
  * Word's spellings.
97
+ * @internal
69
98
  */
70
99
  export function toggle(element: XmlElement): boolean | undefined {
71
100
  const value = attr(element, "val");
@@ -74,7 +103,10 @@ export function toggle(element: XmlElement): boolean | undefined {
74
103
  return undefined;
75
104
  }
76
105
 
77
- /** `{ key: value }` without the undefined values; undefined when none remain. */
106
+ /**
107
+ * `{ key: value }` without the undefined values; undefined when none remain.
108
+ * @internal
109
+ */
78
110
  export function compact<T extends Record<string, unknown>>(object: T): Partial<T> | undefined {
79
111
  const out: Record<string, unknown> = {};
80
112
  for (const [key, value] of Object.entries(object)) if (value !== undefined) out[key] = value;