@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
@@ -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",
@@ -18,33 +27,53 @@ export const REL = {
18
27
  commentsExtended: "http://schemas.microsoft.com/office/2011/relationships/commentsExtended",
19
28
  hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
20
29
  settings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings",
30
+ header: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header",
31
+ footer: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer",
32
+ footnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes",
33
+ endnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes",
21
34
  };
22
35
 
23
- /** Whether `node` is the WordprocessingML element `local`. */
36
+ /**
37
+ * Whether `node` is the WordprocessingML element `local`.
38
+ * @internal
39
+ */
24
40
  export function isW(node: XmlNode, local?: string): boolean {
25
41
  return node.kind === "element" && node.ns === W && (local === undefined || node.local === local);
26
42
  }
27
43
 
44
+ /** @internal */
28
45
  export function elements(element: XmlElement): XmlElement[] {
29
46
  return element.children.filter((child): child is XmlElement => child.kind === "element");
30
47
  }
31
48
 
32
- /** The first WordprocessingML child named `local`. */
49
+ /**
50
+ * The first WordprocessingML child named `local`.
51
+ * @internal
52
+ */
33
53
  export function child(element: XmlElement, local: string): XmlElement | undefined {
34
54
  return element.children.find((c): c is XmlElement => c.kind === "element" && isW(c, local));
35
55
  }
36
56
 
37
- /** A WordprocessingML attribute (`w:val`) of `element`. */
57
+ /**
58
+ * A WordprocessingML attribute (`w:val`) of `element`.
59
+ * @internal
60
+ */
38
61
  export function attr(element: XmlElement | undefined, local: string, ns = W): string | undefined {
39
62
  return element?.attributes.find((a) => a.local === local && a.ns === ns)?.value;
40
63
  }
41
64
 
42
- /** 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
+ */
43
69
  export function textOf(element: XmlElement): string {
44
70
  return element.children.map((c) => (c.kind === "text" ? c.text : "")).join("");
45
71
  }
46
72
 
47
- /** 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
+ */
48
77
  export function deepText(element: XmlElement): string {
49
78
  let out = "";
50
79
  for (const c of element.children) {
@@ -54,7 +83,10 @@ export function deepText(element: XmlElement): string {
54
83
  return out;
55
84
  }
56
85
 
57
- /** 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
+ */
58
90
  export function integer(value: string | undefined): number | undefined {
59
91
  return value !== undefined && /^-?\d+$/.test(value) ? Number.parseInt(value, 10) : undefined;
60
92
  }
@@ -62,6 +94,7 @@ export function integer(value: string | undefined): number | undefined {
62
94
  /**
63
95
  * An on/off property (ST_OnOff): absent value is on. Undefined for a value that is not one of
64
96
  * Word's spellings.
97
+ * @internal
65
98
  */
66
99
  export function toggle(element: XmlElement): boolean | undefined {
67
100
  const value = attr(element, "val");
@@ -70,7 +103,10 @@ export function toggle(element: XmlElement): boolean | undefined {
70
103
  return undefined;
71
104
  }
72
105
 
73
- /** `{ 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
+ */
74
110
  export function compact<T extends Record<string, unknown>>(object: T): Partial<T> | undefined {
75
111
  const out: Record<string, unknown> = {};
76
112
  for (const [key, value] of Object.entries(object)) if (value !== undefined) out[key] = value;
@@ -1,16 +1,15 @@
1
1
  /** The parts beside the document: styles, numbering, theme, comments. */
2
2
 
3
- import {
4
- type AbstractNumberingJSON,
5
- type CommentJSON,
6
- type MarkJSON,
7
- type NumberingInstanceJSON,
8
- type NumberingLevelJSON,
9
- RUN_PROPERTY_MARKS,
10
- type StyleJSON,
11
- schema,
12
- type ThemeJSON,
3
+ import type {
4
+ AbstractNumberingJSON,
5
+ CommentJSON,
6
+ MarkJSON,
7
+ NumberingInstanceJSON,
8
+ NumberingLevelJSON,
9
+ StyleJSON,
10
+ ThemeJSON,
13
11
  } from "@folijs/core";
12
+ import { RUN_PROPERTY_MARKS, schema } from "@folijs/core/internal";
14
13
  import type { XmlElement } from "../xml.js";
15
14
  import { blocks, type ContentContext } from "./content.js";
16
15
  import { A, attr, child, compact, elements, integer, isW, toggle, W14, W15 } from "./ooxml.js";
@@ -46,7 +45,10 @@ function id(
46
45
  return n;
47
46
  }
48
47
 
49
- /** `w:styles`: the document defaults and the styles (each with its element verbatim). */
48
+ /**
49
+ * `w:styles`: the document defaults and the styles (each with its element verbatim).
50
+ * @internal
51
+ */
50
52
  export function styles(
51
53
  root: XmlElement,
52
54
  context: Context,
@@ -71,7 +73,10 @@ export function styles(
71
73
  return { defaults, styles: list };
72
74
  }
73
75
 
74
- /** `w:docDefaults` as the envelope's defaults (with the element verbatim). */
76
+ /**
77
+ * `w:docDefaults` as the envelope's defaults (with the element verbatim).
78
+ * @internal
79
+ */
75
80
  export function defaultsOf(docDefaults: XmlElement, context: Context): Record<string, unknown> {
76
81
  const pPr = child(child(docDefaults, "pPrDefault") ?? docDefaults, "pPr");
77
82
  const rPr = child(child(docDefaults, "rPrDefault") ?? docDefaults, "rPr");
@@ -84,7 +89,10 @@ export function defaultsOf(docDefaults: XmlElement, context: Context): Record<st
84
89
  };
85
90
  }
86
91
 
87
- /** Whether import keeps a `w:style` (it has a usable id and type); others stay in the part only. */
92
+ /**
93
+ * Whether import keeps a `w:style` (it has a usable id and type); others stay in the part only.
94
+ * @internal
95
+ */
88
96
  export function usableStyle(el: XmlElement): boolean {
89
97
  const styleId = attr(el, "styleId");
90
98
  return (
@@ -92,7 +100,10 @@ export function usableStyle(el: XmlElement): boolean {
92
100
  );
93
101
  }
94
102
 
95
- /** A `w:style` as a style (with the element verbatim); undefined (reported) when unusable. */
103
+ /**
104
+ * A `w:style` as a style (with the element verbatim); undefined (reported) when unusable.
105
+ * @internal
106
+ */
96
107
  export function styleOf(el: XmlElement, context: Context): StyleJSON | undefined {
97
108
  const styleId = attr(el, "styleId");
98
109
  const type = attr(el, "type") ?? "paragraph";
@@ -170,6 +181,7 @@ function breakCycles<T>(
170
181
  });
171
182
  }
172
183
 
184
+ /** @internal */
173
185
  export function level(lvl: XmlElement, context: Context): NumberingLevelJSON | undefined {
174
186
  const index = integer(attr(lvl, "ilvl"));
175
187
  if (index === undefined || index < 0 || index > 8) {
@@ -226,7 +238,10 @@ function checked(
226
238
  return out;
227
239
  }
228
240
 
229
- /** `w:numbering`: abstract definitions and instances (each with its element verbatim). */
241
+ /**
242
+ * `w:numbering`: abstract definitions and instances (each with its element verbatim).
243
+ * @internal
244
+ */
230
245
  export function numbering(
231
246
  root: XmlElement,
232
247
  context: Context,
@@ -245,7 +260,10 @@ export function numbering(
245
260
  return { abstracts, instances };
246
261
  }
247
262
 
248
- /** A `w:abstractNum` as a definition (with the element verbatim); undefined (reported) when unusable. */
263
+ /**
264
+ * A `w:abstractNum` as a definition (with the element verbatim); undefined (reported) when unusable.
265
+ * @internal
266
+ */
249
267
  export function abstractOf(el: XmlElement, context: Context): AbstractNumberingJSON | undefined {
250
268
  const abstractId = id(attr(el, "abstractNumId"), 0, "w:abstractNum", context);
251
269
  if (abstractId === undefined) return undefined;
@@ -278,7 +296,10 @@ export function abstractOf(el: XmlElement, context: Context): AbstractNumberingJ
278
296
  }) as AbstractNumberingJSON;
279
297
  }
280
298
 
281
- /** A `w:num` as an instance (with the element verbatim); undefined (reported) when unusable. */
299
+ /**
300
+ * A `w:num` as an instance (with the element verbatim); undefined (reported) when unusable.
301
+ * @internal
302
+ */
282
303
  export function instanceOf(el: XmlElement, context: Context): NumberingInstanceJSON | undefined {
283
304
  const numId = id(attr(el, "numId"), 1, "w:num", context);
284
305
  const abstract = id(attr(child(el, "abstractNumId"), "val"), 0, "w:num/w:abstractNumId", context);
@@ -332,7 +353,10 @@ const THEME_COLORS = [
332
353
  "folHlink",
333
354
  ];
334
355
 
335
- /** `a:theme`'s fonts and colors; undefined (reported) when its fonts are missing or unusable. */
356
+ /**
357
+ * `a:theme`'s fonts and colors; undefined (reported) when its fonts are missing or unusable.
358
+ * @internal
359
+ */
336
360
  export function theme(root: XmlElement, context: Context): ThemeJSON | undefined {
337
361
  const a = (el: XmlElement | undefined, local: string) =>
338
362
  el?.children.find(
@@ -374,6 +398,7 @@ export function theme(root: XmlElement, context: Context): ThemeJSON | undefined
374
398
  * `w:comments`, with replies and resolved state from `commentsExtended` (keyed by the
375
399
  * `w14:paraId` of each comment's last paragraph). Each comment keeps its start tag verbatim
376
400
  * (`ext`): values the model cannot hold (a long author, a date without a time) stay there.
401
+ * @internal
377
402
  */
378
403
  export function comments(
379
404
  root: XmlElement,
@@ -394,7 +419,7 @@ export function comments(
394
419
  if (initials !== undefined && initials.length > 9) {
395
420
  context.report.unmodeled("w:comment@w:initials", "longer than 9");
396
421
  }
397
- const content = blocks(el.children, context);
422
+ const content = blocks(el.children, { ...context, story: "comment" });
398
423
  const comment = compact({
399
424
  id: commentId,
400
425
  author: author.length <= 255 ? author : author.slice(0, 255),
@@ -9,7 +9,9 @@ import type { XmlElement } from "../xml.js";
9
9
  import { A, attr, integer, R, textOf } from "./ooxml.js";
10
10
  import { type Context, sourceOf } from "./properties.js";
11
11
 
12
+ /** @internal */
12
13
  export const WP = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
14
+ /** @internal */
13
15
  export const PIC = "http://schemas.openxmlformats.org/drawingml/2006/picture";
14
16
  const ADEC = "http://schemas.microsoft.com/office/drawing/2017/decorative";
15
17
  const IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
@@ -24,6 +26,7 @@ const WRAPS: Record<string, string> = {
24
26
  };
25
27
  const SIDES = new Set(["bothSides", "left", "right", "largest"]);
26
28
 
29
+ /** @internal */
27
30
  export interface PictureContext extends Context {
28
31
  /** The part's relationship with this id. */
29
32
  readonly relationship: (
@@ -74,7 +77,10 @@ function position(el: XmlElement | undefined) {
74
77
  return undefined;
75
78
  }
76
79
 
77
- /** The `float` of a `wp:anchor`: undefined for one the model cannot hold (kept opaque). */
80
+ /**
81
+ * The `float` of a `wp:anchor`: undefined for one the model cannot hold (kept opaque).
82
+ * @internal
83
+ */
78
84
  export function floatOf(anchor: XmlElement): Record<string, unknown> | undefined {
79
85
  const horizontal = position(kid(anchor, WP, "positionH"));
80
86
  const vertical = position(kid(anchor, WP, "positionV"));
@@ -130,6 +136,7 @@ export function floatOf(anchor: XmlElement): Record<string, unknown> | undefined
130
136
  /**
131
137
  * The picture node's attributes for `drawing`, its image added to `resources`; undefined for
132
138
  * a drawing Foli keeps opaque (not one inline picture, no embedded image part).
139
+ * @internal
133
140
  */
134
141
  export function pictureAttrs(
135
142
  drawing: XmlElement,
@@ -5,25 +5,39 @@
5
5
  * element's verbatim `ext`, so nothing is lost.
6
6
  */
7
7
 
8
- import { checkSection, type MarkJSON, RUN_PROPERTY_MARKS, schema } from "@folijs/core";
8
+ import type { MarkJSON } from "@folijs/core";
9
+ import { checkSection, RUN_PROPERTY_MARKS, schema } from "@folijs/core/internal";
9
10
  import type { XmlElement } from "../xml.js";
10
11
  import { attr, child, compact, elements, integer, isW, R, toggle, W } from "./ooxml.js";
11
12
  import type { Recorder } from "./report.js";
12
13
 
14
+ /** @internal */
13
15
  export interface Context {
14
16
  readonly source: string;
15
17
  readonly report: Recorder;
16
18
  }
17
19
 
20
+ /** @internal */
18
21
  export function sourceOf(context: Context, element: XmlElement): string {
19
22
  return context.source.slice(element.start, element.end);
20
23
  }
21
24
 
25
+ /**
26
+ * `object` without its undefined values.
27
+ * @internal
28
+ */
29
+ export function compactDefined<T extends Record<string, unknown>>(object: T): Partial<T> {
30
+ return Object.fromEntries(
31
+ Object.entries(object).filter(([, value]) => value !== undefined),
32
+ ) as Partial<T>;
33
+ }
34
+
22
35
  const ATTRIBUTE_NAME = /^[A-Za-z_][\w.-]*(:[A-Za-z_][\w.-]*)?$/;
23
36
 
24
37
  /**
25
38
  * An element's attributes not in `modeled`, as an `attributes` bag (undefined when none). One
26
39
  * the bag cannot hold (a name outside its pattern, a value over 64 KiB, past 64) is reported.
40
+ * @internal
27
41
  */
28
42
  export function attributeBag(
29
43
  element: XmlElement,
@@ -51,7 +65,10 @@ export function attributeBag(
51
65
 
52
66
  const PARAGRAPH_ATTRS = schema.nodes.paragraph?.spec.attrs ?? {};
53
67
 
54
- /** Keeps `value` as paragraph attribute `name` if the schema accepts it; reports it otherwise. */
68
+ /**
69
+ * Keeps `value` as paragraph attribute `name` if the schema accepts it; reports it otherwise.
70
+ * @internal
71
+ */
55
72
  export function setParagraph(
56
73
  out: Record<string, unknown>,
57
74
  name: string,
@@ -65,7 +82,10 @@ export function setParagraph(
65
82
  else out[name] = value;
66
83
  }
67
84
 
68
- /** The mark if the schema accepts it; reported and left out otherwise. */
85
+ /**
86
+ * The mark if the schema accepts it; reported and left out otherwise.
87
+ * @internal
88
+ */
69
89
  export function mark(json: MarkJSON, element: string, context: Context): MarkJSON | undefined {
70
90
  try {
71
91
  schema.markFromJSON(json);
@@ -76,7 +96,10 @@ export function mark(json: MarkJSON, element: string, context: Context): MarkJSO
76
96
  }
77
97
  }
78
98
 
79
- /** Who and when, for tracked changes (`w:ins`, `w:del`, `w:rPrChange`…). */
99
+ /**
100
+ * Who and when, for tracked changes (`w:ins`, `w:del`, `w:rPrChange`…).
101
+ * @internal
102
+ */
80
103
  export function revisionOf(element: XmlElement): {
81
104
  id: number | undefined;
82
105
  author: string;
@@ -92,6 +115,7 @@ export function revisionOf(element: XmlElement): {
92
115
  /**
93
116
  * A tracked change's mark (`insertion`, `deletion`, with `move` for `w:moveFrom`/`w:moveTo`).
94
117
  * An invalid date is left out rather than losing the change.
118
+ * @internal
95
119
  */
96
120
  export function revisionMark(
97
121
  type: "insertion" | "deletion",
@@ -124,6 +148,7 @@ const TOGGLES: Record<string, string> = {
124
148
  * `w:rPr`'s run properties as marks (without `runExt`, the caller's). Tracked changes of the
125
149
  * paragraph mark (`w:ins`/`w:del` in a paragraph's `w:rPr`) are not run properties: see
126
150
  * `paragraphRevision`.
151
+ * @internal
127
152
  */
128
153
  export function runProperties(rPr: XmlElement | undefined, context: Context): MarkJSON[] {
129
154
  if (!rPr) return [];
@@ -305,7 +330,10 @@ function whole(
305
330
  return n;
306
331
  }
307
332
 
308
- /** An ST_OnOff attribute (`w:beforeAutospacing="1"`); another value is reported, read as missing. */
333
+ /**
334
+ * An ST_OnOff attribute (`w:beforeAutospacing="1"`); another value is reported, read as missing.
335
+ * @internal
336
+ */
309
337
  export function onOff(
310
338
  element: XmlElement | undefined,
311
339
  local: string,
@@ -325,6 +353,7 @@ const toggleProperty = (el: XmlElement | undefined) => (el ? toggle(el) : undefi
325
353
  /**
326
354
  * `w:pPr` as paragraph attributes. With `paragraph`, also what only a paragraph has (its
327
355
  * section, the paragraph mark's revisions, a formatting change, the verbatim `ext`).
356
+ * @internal
328
357
  */
329
358
  export function paragraphProperties(
330
359
  pPr: XmlElement | undefined,
@@ -458,9 +487,57 @@ export function paragraphProperties(
458
487
  return out;
459
488
  }
460
489
 
461
- /** `w:sectPr` as a section; every part checked on its own. */
490
+ /** `w:footnotePr` or `w:endnotePr` of a section: how its notes are placed and numbered. */
491
+ function noteProperties(element: XmlElement | undefined, context: Context) {
492
+ if (!element) return undefined;
493
+ const value = (local: string) => attr(child(element, local), "val");
494
+ return compact({
495
+ position: value("pos"),
496
+ format: value("numFmt"),
497
+ start: whole(child(element, "numStart"), "val", context),
498
+ restart: value("numRestart"),
499
+ });
500
+ }
501
+
502
+ /** `w:cols`: `widths` from its `w:col` children, when it has them. */
503
+ function sectionColumns(cols: XmlElement | undefined, context: Context) {
504
+ if (!cols) return undefined;
505
+ const on = (local: string) => {
506
+ const value = attr(cols, local);
507
+ return value === undefined ? undefined : !["0", "false", "off"].includes(value);
508
+ };
509
+ const widths = elements(cols)
510
+ .filter((el) => isW(el, "col"))
511
+ .map((el) => compact({ width: whole(el, "w", context), space: whole(el, "space", context) }));
512
+ return compact({
513
+ count: whole(cols, "num", context),
514
+ space: whole(cols, "space", context),
515
+ equalWidth: on("equalWidth"),
516
+ separator: on("sep"),
517
+ widths: widths.length ? widths : undefined,
518
+ });
519
+ }
520
+
521
+ /** `w:sectPrChange`: who changed the section's setup, and the setup before (`w:sectPr`). */
522
+ function sectionChange(element: XmlElement | undefined, context: Context) {
523
+ if (!element) return undefined;
524
+ const { id, author, date } = revisionOf(element);
525
+ const before = child(element, "sectPr");
526
+ return compact({
527
+ id,
528
+ author,
529
+ date: date ?? undefined,
530
+ previous: before ? section(before, context) : {},
531
+ });
532
+ }
533
+
534
+ /**
535
+ * `w:sectPr` as a section; every part checked on its own.
536
+ * @internal
537
+ */
462
538
  export function section(sectPr: XmlElement, context: Context): Record<string, unknown> {
463
539
  const pgSz = child(sectPr, "pgSz");
540
+ const pgNumType = child(sectPr, "pgNumType");
464
541
  const pgMar = child(sectPr, "pgMar");
465
542
  const references = (local: string) =>
466
543
  compact(
@@ -494,6 +571,13 @@ export function section(sectPr: XmlElement, context: Context): Record<string, un
494
571
  titlePage: titlePg ? toggle(titlePg) : undefined,
495
572
  headers: references("headerReference"),
496
573
  footers: references("footerReference"),
574
+ columns: sectionColumns(child(sectPr, "cols"), context),
575
+ pageNumbers:
576
+ pgNumType &&
577
+ compact({ start: whole(pgNumType, "start", context), format: attr(pgNumType, "fmt") }),
578
+ footnotes: noteProperties(child(sectPr, "footnotePr"), context),
579
+ endnotes: noteProperties(child(sectPr, "endnotePr"), context),
580
+ change: sectionChange(child(sectPr, "sectPrChange"), context),
497
581
  };
498
582
  const out: Record<string, unknown> = {};
499
583
  for (const [key, value] of Object.entries(parts)) {
@@ -22,6 +22,7 @@ export interface ImportReport {
22
22
  readonly picturesWithoutAlt: number;
23
23
  }
24
24
 
25
+ /** @internal */
25
26
  export class Recorder {
26
27
  // Maps, not objects: element names such as `constructor` are only names.
27
28
  readonly #opaque = new Map<string, number>();
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Headers, footers, footnotes and endnotes as stories (ADR-0007): content trees of their own,
3
+ * read from their parts with the same reader as the body. A header's or footer's id is its
4
+ * relationship id; a note's is `footnote:<w:id>` or `endnote:<w:id>`. A note the model cannot
5
+ * name stays in its part, untouched.
6
+ */
7
+ import { parseContent, type StoryJSON } from "@folijs/core";
8
+ import type { DocxPackage } from "../package.js";
9
+ import type { XmlElement } from "../xml.js";
10
+ import { blocks, type ContentContext } from "./content.js";
11
+ import { attr, elements, integer, isW, REL } from "./ooxml.js";
12
+
13
+ const NOTE_TYPES = new Set(["normal", "separator", "continuationSeparator", "continuationNotice"]);
14
+
15
+ /**
16
+ * The notes of a footnotes or endnotes part that the model holds, by story id.
17
+ * @internal
18
+ */
19
+ export function notesOf(root: XmlElement, kind: "footnote" | "endnote"): Map<string, XmlElement> {
20
+ const out = new Map<string, XmlElement>();
21
+ for (const el of elements(root)) {
22
+ if (!isW(el, kind)) continue;
23
+ const id = integer(attr(el, "id"));
24
+ const type = attr(el, "type");
25
+ const key = `${kind}:${id}`;
26
+ if (id === undefined || (type !== undefined && !NOTE_TYPES.has(type)) || out.has(key)) continue;
27
+ out.set(key, el);
28
+ }
29
+ return out;
30
+ }
31
+
32
+ const docOf = (content: StoryJSON["content"]["content"]): StoryJSON["content"] => ({
33
+ type: "doc",
34
+ content: content?.length ? content : [{ type: "paragraph" }],
35
+ });
36
+
37
+ /**
38
+ * Every story of the package, by id. `contextFor` gives the reading context of a part.
39
+ * @internal
40
+ */
41
+ export function readStories(
42
+ pkg: DocxPackage,
43
+ contextFor: (part: string, source: string) => ContentContext,
44
+ ): Record<string, StoryJSON> {
45
+ const stories: Record<string, StoryJSON> = {};
46
+ const notesRead = new Set<string>();
47
+ for (const relationship of pkg.relationships(pkg.mainDocument)) {
48
+ const part = relationship.partName ? pkg.part(relationship.partName) : undefined;
49
+ if (relationship.external || !part) continue;
50
+ const headerOrFooter =
51
+ relationship.type === REL.header
52
+ ? ["header", "hdr"]
53
+ : relationship.type === REL.footer
54
+ ? ["footer", "ftr"]
55
+ : undefined;
56
+ const note =
57
+ relationship.type === REL.footnotes
58
+ ? "footnote"
59
+ : relationship.type === REL.endnotes
60
+ ? "endnote"
61
+ : undefined;
62
+ if (!headerOrFooter && !note) continue;
63
+ // A part that is not XML (a relationship can point anywhere) stays as it is.
64
+ let xml: ReturnType<DocxPackage["xml"]>;
65
+ try {
66
+ xml = pkg.xml(part.name);
67
+ } catch {
68
+ continue;
69
+ }
70
+ const context = contextFor(part.name, xml.source);
71
+ if (headerOrFooter) {
72
+ const [kind, root] = headerOrFooter as ["header" | "footer", string];
73
+ // An id the envelope cannot hold as a key: the part stays as it is.
74
+ if (!isW(xml.root, root) || relationship.id === "__proto__") continue;
75
+ stories[relationship.id] = {
76
+ kind,
77
+ content: docOf(blocks(xml.root.children, { ...context, story: kind })),
78
+ };
79
+ } else if (note) {
80
+ // One part per kind, of the right kind: any other stays as it is.
81
+ if (notesRead.has(note) || !isW(xml.root, `${note}s`)) continue;
82
+ notesRead.add(note);
83
+ for (const [key, el] of notesOf(xml.root, note)) {
84
+ const type = attr(el, "type");
85
+ stories[key] = {
86
+ kind: note,
87
+ ...(type ? { noteType: type as StoryJSON["noteType"] & string } : {}),
88
+ content: docOf(blocks(el.children, { ...context, story: note })),
89
+ ext: xml.source.slice(el.start, el.openEnd),
90
+ };
91
+ }
92
+ }
93
+ }
94
+ return stories;
95
+ }
96
+
97
+ /**
98
+ * The ids of every note in the package's notes parts, those the model does not hold too.
99
+ * @internal
100
+ */
101
+ export function noteIds(pkg: DocxPackage): Set<string> {
102
+ const ids = new Set<string>();
103
+ for (const [type, kind] of [
104
+ [REL.footnotes, "footnote"],
105
+ [REL.endnotes, "endnote"],
106
+ ] as const) {
107
+ const name = pkg.relationships(pkg.mainDocument).find((r) => r.type === type)?.partName;
108
+ if (!name || !pkg.part(name)) continue;
109
+ let root: XmlElement;
110
+ try {
111
+ root = pkg.xml(name).root;
112
+ } catch {
113
+ continue;
114
+ }
115
+ for (const el of elements(root)) {
116
+ const id = integer(attr(el, "id"));
117
+ if (isW(el, kind) && id !== undefined) ids.add(`${kind}:${id}`);
118
+ }
119
+ }
120
+ return ids;
121
+ }
122
+
123
+ /**
124
+ * The stories in the form a validated document holds them, to compare with one.
125
+ * @internal
126
+ */
127
+ export function canonicalStories(
128
+ pkg: DocxPackage,
129
+ contextFor: (part: string, source: string) => ContentContext,
130
+ ): Record<string, StoryJSON> {
131
+ const stories = readStories(pkg, contextFor);
132
+ for (const story of Object.values(stories)) story.content = parseContent(story.content).toJSON();
133
+ return stories;
134
+ }