@folijs/docx 0.5.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 +157 -0
  2. package/README.md +54 -17
  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 +2 -0
  8. package/dist/export/balance.d.ts.map +1 -0
  9. package/dist/export/balance.js +112 -0
  10. package/dist/export/balance.js.map +1 -0
  11. package/dist/export/content.d.ts +1 -14
  12. package/dist/export/content.d.ts.map +1 -1
  13. package/dist/export/content.js +157 -22
  14. package/dist/export/content.js.map +1 -1
  15. package/dist/export/controls.d.ts +2 -0
  16. package/dist/export/controls.d.ts.map +1 -0
  17. package/dist/export/controls.js +233 -0
  18. package/dist/export/controls.js.map +1 -0
  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 +218 -18
  22. package/dist/export/index.js.map +1 -1
  23. package/dist/export/parts.d.ts +1 -16
  24. package/dist/export/parts.d.ts.map +1 -1
  25. package/dist/export/parts.js +79 -11
  26. package/dist/export/parts.js.map +1 -1
  27. package/dist/export/pictures.d.ts +0 -42
  28. package/dist/export/pictures.d.ts.map +1 -1
  29. package/dist/export/pictures.js +24 -4
  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 +74 -15
  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 -33
  44. package/dist/import/content.d.ts.map +1 -1
  45. package/dist/import/content.js +208 -17
  46. package/dist/import/content.js.map +1 -1
  47. package/dist/import/controls.d.ts +2 -0
  48. package/dist/import/controls.d.ts.map +1 -0
  49. package/dist/import/controls.js +121 -0
  50. package/dist/import/controls.js.map +1 -0
  51. package/dist/import/index.d.ts +1 -1
  52. package/dist/import/index.d.ts.map +1 -1
  53. package/dist/import/index.js +82 -14
  54. package/dist/import/index.js.map +1 -1
  55. package/dist/import/ooxml.d.ts +1 -37
  56. package/dist/import/ooxml.d.ts.map +1 -1
  57. package/dist/import/ooxml.js +44 -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 +36 -10
  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 -43
  68. package/dist/import/properties.d.ts.map +1 -1
  69. package/dist/import/properties.js +84 -6
  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 +2 -0
  76. package/dist/import/stories.d.ts.map +1 -0
  77. package/dist/import/stories.js +131 -0
  78. package/dist/import/stories.js.map +1 -0
  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 -7
  88. package/dist/settings.d.ts.map +1 -1
  89. package/dist/settings.js +186 -26
  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 +6 -5
  100. package/src/custom.ts +254 -0
  101. package/src/export/balance.ts +114 -0
  102. package/src/export/content.ts +203 -19
  103. package/src/export/controls.ts +260 -0
  104. package/src/export/index.ts +268 -20
  105. package/src/export/parts.ts +102 -10
  106. package/src/export/pictures.ts +21 -5
  107. package/src/export/properties.ts +90 -18
  108. package/src/export/tables.ts +15 -3
  109. package/src/export/xmlout.ts +36 -7
  110. package/src/import/content.ts +219 -17
  111. package/src/import/controls.ts +141 -0
  112. package/src/import/index.ts +103 -22
  113. package/src/import/ooxml.ts +44 -8
  114. package/src/import/parts.ts +44 -19
  115. package/src/import/pictures.ts +8 -1
  116. package/src/import/properties.ts +90 -6
  117. package/src/import/report.ts +1 -0
  118. package/src/import/stories.ts +134 -0
  119. package/src/import/tables.ts +25 -6
  120. package/src/package.ts +56 -6
  121. package/src/settings.ts +204 -27
  122. package/src/xml.ts +42 -2
  123. package/src/zip.ts +17 -5
@@ -5,12 +5,14 @@
5
5
  * Its image is the package's part when the resource names one there, else a new media part
6
6
  * whose bytes come from the resource's `data:` URL or the app (`ExportOptions.resource`).
7
7
  */
8
+
8
9
  import type { FoliDocument, NodeJSON, ResourceJSON } from "@folijs/core";
9
10
  import { A, R } from "../import/ooxml.js";
10
11
  import { floatOf, PIC, WP } from "../import/pictures.js";
11
12
  import type { DocxPackage } from "../package.js";
12
13
  import { DocxError } from "../package.js";
13
14
  import type { XmlElement } from "../xml.js";
15
+ import { ControlWriter } from "./controls.js";
14
16
  import { same } from "./properties.js";
15
17
  import { escapeAttribute, fragment, type Namespaces } from "./xmlout.js";
16
18
 
@@ -27,7 +29,7 @@ const EXTENSIONS: Record<string, string> = {
27
29
  "image/x-wmf": "wmf",
28
30
  };
29
31
 
30
- /** Every picture node of the document (body and comments). */
32
+ /** Every picture node of the document (body, comments and stories). */
31
33
  function picturesOf(doc: FoliDocument): Json[] {
32
34
  const out: Json[] = [];
33
35
  const visit = (nodes: readonly NodeJSON[] | undefined) => {
@@ -38,6 +40,7 @@ function picturesOf(doc: FoliDocument): Json[] {
38
40
  };
39
41
  visit(doc.content.content);
40
42
  for (const comment of doc.comments) visit(comment.content);
43
+ for (const story of Object.values(doc.stories ?? {})) visit(story.content.content);
41
44
  return out;
42
45
  }
43
46
 
@@ -65,7 +68,10 @@ function ownPart(resource: ResourceJSON, pkg: DocxPackage | undefined): boolean
65
68
  return !!part && part.contentType.startsWith("image/") && part.data.length === resource.size;
66
69
  }
67
70
 
68
- /** The bytes of each picture's image the package does not hold, before anything is written. */
71
+ /**
72
+ * The bytes of each picture's image the package does not hold, before anything is written.
73
+ * @internal
74
+ */
69
75
  export async function pictureBytes(
70
76
  doc: FoliDocument,
71
77
  pkg: DocxPackage | undefined,
@@ -102,9 +108,14 @@ export async function pictureBytes(
102
108
  const docPrIds = (xml: string) =>
103
109
  [...xml.matchAll(/<(?:[\w.-]+:)?docPr\b[^>]*?\bid="(\d+)"/g)].map((m) => Number(m[1]));
104
110
 
105
- /** The media parts pictures need, allocated as they are written, and the drawings' ids. */
111
+ /**
112
+ * The media parts pictures need, allocated as they are written, and the drawings' ids.
113
+ * @internal
114
+ */
106
115
  export class Media {
107
116
  readonly added: { name: string; data: Uint8Array; contentType: string }[] = [];
117
+ /** The document's content controls, written once across its parts. */
118
+ readonly controls: ControlWriter;
108
119
  readonly #parts = new Map<string, string>();
109
120
  /** Ids drawings Foli does not write hold (opaque content, headers and footers). */
110
121
  readonly #reserved = new Set<number>();
@@ -119,6 +130,7 @@ export class Media {
119
130
  /** The parts rewritten from the model (their drawings are the document's). */
120
131
  rewritten: readonly string[] = [],
121
132
  ) {
133
+ this.controls = new ControlWriter(doc.controls ?? {});
122
134
  // `wp:docPr` ids are unique in a document, across its parts: new ones above all of them.
123
135
  let max = 0;
124
136
  for (const attrs of picturesOf(doc))
@@ -129,7 +141,7 @@ export class Media {
129
141
  max = Math.max(max, id);
130
142
  }
131
143
  };
132
- JSON.stringify([doc.content, doc.comments], (key, value) => {
144
+ JSON.stringify([doc.content, doc.comments, doc.stories], (key, value) => {
133
145
  if (key === "xml" && typeof value === "string") reserve(value);
134
146
  return value;
135
147
  });
@@ -222,7 +234,10 @@ function setAttr(
222
234
  }
223
235
  }
224
236
 
225
- /** A part's relationships as a picture's drawing needs them. */
237
+ /**
238
+ * A part's relationships as a picture's drawing needs them.
239
+ * @internal
240
+ */
226
241
  export interface PictureRelations {
227
242
  /** The id relating image part `part` (`current` when it already does). */
228
243
  image(part: string, current: string | undefined): string;
@@ -304,6 +319,7 @@ function wrapXml(float: Json): string {
304
319
  * has none, when its position or wrapping changed, or when it was read in another part or
305
320
  * package and refers to other relationships (an SVG's PNG fallback, a click link) that mean
306
321
  * something else here.
322
+ * @internal
307
323
  */
308
324
  export function drawingXml(
309
325
  attrs: Json,
@@ -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
  );
@@ -547,10 +552,47 @@ const SECTION_CHILDREN: Record<string, readonly string[]> = {
547
552
  pageSize: ["pgSz"],
548
553
  margins: ["pgMar"],
549
554
  titlePage: ["titlePg"],
555
+ columns: ["cols"],
556
+ pageNumbers: ["pgNumType"],
557
+ footnotes: ["footnotePr"],
558
+ endnotes: ["endnotePr"],
559
+ change: ["sectPrChange"],
550
560
  };
551
561
  const SECTION_MODELED = new Set(Object.values(SECTION_CHILDREN).flat());
552
562
 
553
- function sectionChild(name: string, value: unknown): string {
563
+ /** `w:footnotePr` or `w:endnotePr`: its children in CT_FtnProps order. */
564
+ function noteProperties(local: string, v: Json): string {
565
+ const s = (x: unknown) => (x === undefined ? undefined : String(x));
566
+ const children =
567
+ val("pos", s(v.position)) +
568
+ val("numFmt", s(v.format)) +
569
+ val("numStart", s(v.start)) +
570
+ val("numRestart", s(v.restart));
571
+ return children ? el(`w:${local}`, {}, children) : "";
572
+ }
573
+
574
+ /**
575
+ * The setup a tracked change records, every value it could have changed spelled out: Word finds
576
+ * no change in what the recorded `w:sectPr` leaves out (a `w:cols` without `w:num`, checked with
577
+ * Word 16). One read from a file stays as it was.
578
+ */
579
+ function previousSetup(previous: Json): Json {
580
+ if (previous.ext) return previous;
581
+ const size = (previous.pageSize ?? {}) as Json;
582
+ const columns = (previous.columns ?? {}) as Json;
583
+ return {
584
+ ...previous,
585
+ type: previous.type ?? "nextPage",
586
+ pageSize: { ...size, width: size.width ?? 12240, height: size.height ?? 15840 },
587
+ margins: previous.margins ?? {},
588
+ columns: {
589
+ ...columns,
590
+ count: columns.count ?? (columns.widths as unknown[] | undefined)?.length ?? 1,
591
+ },
592
+ };
593
+ }
594
+
595
+ function sectionChild(name: string, value: unknown, ns: Namespaces): string {
554
596
  if (value === undefined || value === null) return "";
555
597
  const v = value as Json;
556
598
  const s = (x: unknown) => (x === undefined || x === null ? undefined : String(x));
@@ -580,12 +622,44 @@ function sectionChild(name: string, value: unknown): string {
580
622
  });
581
623
  case "titlePage":
582
624
  return onOff("titlePg", value as boolean);
625
+ case "columns":
626
+ return el(
627
+ "w:cols",
628
+ {
629
+ "w:num": s(v.count),
630
+ "w:sep": v.separator as boolean | undefined,
631
+ "w:space": s(v.space),
632
+ "w:equalWidth": v.equalWidth as boolean | undefined,
633
+ },
634
+ ((v.widths ?? []) as Json[])
635
+ .map((col) => el("w:col", { "w:w": s(col.width), "w:space": s(col.space) }))
636
+ .join(""),
637
+ );
638
+ case "pageNumbers":
639
+ return el("w:pgNumType", { "w:fmt": s(v.format), "w:start": s(v.start) });
640
+ case "footnotes":
641
+ return noteProperties("footnotePr", v);
642
+ case "endnotes":
643
+ return noteProperties("endnotePr", v);
644
+ case "change":
645
+ return el(
646
+ "w:sectPrChange",
647
+ { "w:id": s(v.id), "w:author": s(v.author) ?? "", "w:date": s(v.date) },
648
+ // What the section was: never its header references (CT_SectPrBase has none).
649
+ sectionXml(
650
+ { ...previousSetup(v.previous as Json), headers: undefined, footers: undefined },
651
+ ns,
652
+ ),
653
+ );
583
654
  default:
584
655
  return "";
585
656
  }
586
657
  }
587
658
 
588
- /** 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
+ */
589
663
  export function sectionXml(section: Json, ns: Namespaces): string {
590
664
  const ext = section.ext as string | undefined;
591
665
  const original = ext ? fragment(ext, ns, "sectPr") : undefined;
@@ -596,13 +670,11 @@ export function sectionXml(section: Json, ns: Namespaces): string {
596
670
  for (const [prop, locals] of Object.entries(SECTION_CHILDREN)) {
597
671
  generated.set(
598
672
  locals[0] as string,
599
- child(original, same(section[prop], reread[prop]), locals, () =>
600
- sectionChild(prop, section[prop]),
673
+ keptOrFresh(original, same(section[prop], reread[prop]), locals, () =>
674
+ sectionChild(prop, section[prop], ns),
601
675
  ),
602
676
  );
603
677
  }
604
678
  const children = merged(SECT_ORDER, SECTION_MODELED, generated, original);
605
679
  return `<w:sectPr${attributesOf(original)}>${children}</w:sectPr>`;
606
680
  }
607
-
608
- 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 {