@folijs/docx 0.3.0 → 0.5.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 (85) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/README.md +72 -10
  3. package/dist/export/content.d.ts +2 -0
  4. package/dist/export/content.d.ts.map +1 -1
  5. package/dist/export/content.js +41 -3
  6. package/dist/export/content.js.map +1 -1
  7. package/dist/export/index.d.ts +14 -2
  8. package/dist/export/index.d.ts.map +1 -1
  9. package/dist/export/index.js +76 -15
  10. package/dist/export/index.js.map +1 -1
  11. package/dist/export/parts.d.ts.map +1 -1
  12. package/dist/export/parts.js +13 -0
  13. package/dist/export/parts.js.map +1 -1
  14. package/dist/export/pictures.d.ts +51 -0
  15. package/dist/export/pictures.d.ts.map +1 -0
  16. package/dist/export/pictures.js +346 -0
  17. package/dist/export/pictures.js.map +1 -0
  18. package/dist/export/properties.d.ts +11 -1
  19. package/dist/export/properties.d.ts.map +1 -1
  20. package/dist/export/properties.js +1 -1
  21. package/dist/export/properties.js.map +1 -1
  22. package/dist/export/tables.d.ts +27 -0
  23. package/dist/export/tables.d.ts.map +1 -0
  24. package/dist/export/tables.js +344 -0
  25. package/dist/export/tables.js.map +1 -0
  26. package/dist/images.d.ts +21 -0
  27. package/dist/images.d.ts.map +1 -0
  28. package/dist/images.js +53 -0
  29. package/dist/images.js.map +1 -0
  30. package/dist/import/content.d.ts +5 -1
  31. package/dist/import/content.d.ts.map +1 -1
  32. package/dist/import/content.js +161 -7
  33. package/dist/import/content.js.map +1 -1
  34. package/dist/import/index.d.ts +6 -1
  35. package/dist/import/index.d.ts.map +1 -1
  36. package/dist/import/index.js +16 -4
  37. package/dist/import/index.js.map +1 -1
  38. package/dist/import/ooxml.d.ts +1 -0
  39. package/dist/import/ooxml.d.ts.map +1 -1
  40. package/dist/import/ooxml.js +1 -0
  41. package/dist/import/ooxml.js.map +1 -1
  42. package/dist/import/parts.d.ts.map +1 -1
  43. package/dist/import/parts.js +7 -0
  44. package/dist/import/parts.js.map +1 -1
  45. package/dist/import/pictures.d.ts +34 -0
  46. package/dist/import/pictures.d.ts.map +1 -0
  47. package/dist/import/pictures.js +147 -0
  48. package/dist/import/pictures.js.map +1 -0
  49. package/dist/import/properties.d.ts.map +1 -1
  50. package/dist/import/properties.js +2 -1
  51. package/dist/import/properties.js.map +1 -1
  52. package/dist/import/report.d.ts +6 -0
  53. package/dist/import/report.d.ts.map +1 -1
  54. package/dist/import/report.js +5 -0
  55. package/dist/import/report.js.map +1 -1
  56. package/dist/import/tables.d.ts +31 -0
  57. package/dist/import/tables.d.ts.map +1 -0
  58. package/dist/import/tables.js +236 -0
  59. package/dist/import/tables.js.map +1 -0
  60. package/dist/index.d.ts +2 -1
  61. package/dist/index.d.ts.map +1 -1
  62. package/dist/index.js +1 -0
  63. package/dist/index.js.map +1 -1
  64. package/dist/settings.d.ts +8 -0
  65. package/dist/settings.d.ts.map +1 -0
  66. package/dist/settings.js +72 -0
  67. package/dist/settings.js.map +1 -0
  68. package/package.json +2 -2
  69. package/src/export/content.ts +49 -5
  70. package/src/export/index.ts +135 -19
  71. package/src/export/parts.ts +15 -0
  72. package/src/export/pictures.ts +405 -0
  73. package/src/export/properties.ts +1 -1
  74. package/src/export/tables.ts +386 -0
  75. package/src/images.ts +60 -0
  76. package/src/import/content.ts +154 -9
  77. package/src/import/index.ts +20 -5
  78. package/src/import/ooxml.ts +1 -0
  79. package/src/import/parts.ts +13 -0
  80. package/src/import/pictures.ts +176 -0
  81. package/src/import/properties.ts +4 -1
  82. package/src/import/report.ts +11 -0
  83. package/src/import/tables.ts +267 -0
  84. package/src/index.ts +2 -1
  85. package/src/settings.ts +75 -0
@@ -5,9 +5,10 @@
5
5
  * byte for byte. Without a package, a new one is made.
6
6
  */
7
7
 
8
- import { type FoliDocument, parseDocument } from "@folijs/core";
8
+ import { type FoliDocument, parseDocument, type ResourceJSON } from "@folijs/core";
9
9
  import { child, REL } from "../import/ooxml.js";
10
10
  import { DocxError, type DocxPackage, type NewPart } from "../package.js";
11
+ import { newSettingsXml, withTrackRevisions } from "../settings.js";
11
12
  import { deflateEntry, writeZip } from "../zip.js";
12
13
  import { blocksXml, type WriteContext } from "./content.js";
13
14
  import {
@@ -17,6 +18,7 @@ import {
17
18
  type OriginalPart,
18
19
  stylesXml,
19
20
  } from "./parts.js";
21
+ import { drawingXml, Media, pictureBytes } from "./pictures.js";
20
22
  import { sectionXml } from "./properties.js";
21
23
  import {
22
24
  DEFAULT_NAMESPACES,
@@ -33,6 +35,7 @@ const CT = {
33
35
  comments: "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml",
34
36
  commentsExtended:
35
37
  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml",
38
+ settings: "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml",
36
39
  rels: "application/vnd.openxmlformats-package.relationships+xml",
37
40
  };
38
41
 
@@ -43,17 +46,51 @@ class Relationships {
43
46
  readonly added: { id: string; type: string; target: string; external: boolean }[] = [];
44
47
  readonly #ids: Set<string>;
45
48
  readonly #byTarget = new Map<string, string>();
46
- readonly #existing: ReadonlyMap<string, { type: string; target: string; external: boolean }>;
49
+ readonly #existing: ReadonlyMap<
50
+ string,
51
+ { type: string; target: string; external: boolean; partName?: string }
52
+ >;
53
+ /** The part each internal relationship points to (resolved, as the package resolves it). */
54
+ readonly #parts = new Map<string, string>();
47
55
 
48
56
  constructor(
49
- existing: readonly { id: string; type: string; target: string; external: boolean }[],
57
+ existing: readonly {
58
+ id: string;
59
+ type: string;
60
+ target: string;
61
+ external: boolean;
62
+ partName?: string;
63
+ }[],
50
64
  ) {
51
65
  this.#existing = new Map(existing.map((r) => [r.id, r]));
66
+ for (const r of existing) if (!r.external && r.partName) this.#parts.set(r.id, r.partName);
52
67
  this.#ids = new Set(existing.map((r) => r.id));
53
68
  for (const r of existing)
54
69
  if (r.type === REL.hyperlink && r.external) this.#byTarget.set(r.target, r.id);
55
70
  }
56
71
 
72
+ /** The part relationship `id` points to (one it had, or one added), if internal. */
73
+ target(id: string): string | undefined {
74
+ return this.#parts.get(id);
75
+ }
76
+
77
+ /**
78
+ * The relationship to image part `part` (absolute; `target` as this part refers to it):
79
+ * `current` when it is one, else a known or new one. Compared by part, not by the target's
80
+ * text (`/word/media/x.png`, `./media/x.png` and `media/x.png` are one part).
81
+ */
82
+ image(part: string, target: string, current: string | undefined): string {
83
+ const isImage = (id: string) => {
84
+ const r = this.#existing.get(id) ?? this.added.find((a) => a.id === id);
85
+ return r?.type === REL_IMAGE && this.#parts.get(id)?.toLowerCase() === part.toLowerCase();
86
+ };
87
+ if (current !== undefined && isImage(current)) return current;
88
+ for (const id of this.#parts.keys()) if (isImage(id)) return id;
89
+ const id = this.add(REL_IMAGE, target, false);
90
+ this.#parts.set(id, part);
91
+ return id;
92
+ }
93
+
57
94
  hyperlink(href: string, id: string | undefined): string {
58
95
  const own = id === undefined ? undefined : this.#existing.get(id);
59
96
  if (own && own.type === REL.hyperlink && own.target === href) return id as string;
@@ -89,8 +126,28 @@ class Relationships {
89
126
  }
90
127
  }
91
128
 
92
- function contextFor(namespaces: Namespaces, relationships: Relationships): WriteContext {
93
- return { namespaces, hyperlink: (href, id) => relationships.hyperlink(href, id) };
129
+ const REL_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
130
+
131
+ function contextFor(
132
+ namespaces: Namespaces,
133
+ relationships: Relationships,
134
+ media: Media,
135
+ source: string,
136
+ ): WriteContext {
137
+ return {
138
+ namespaces,
139
+ hyperlink: (href, id) => relationships.hyperlink(href, id),
140
+ picture: (attrs) =>
141
+ drawingXml(
142
+ attrs,
143
+ {
144
+ image: (part, current) => relationships.image(part, relative(source, part), current),
145
+ target: (id) => relationships.target(id),
146
+ },
147
+ namespaces,
148
+ media,
149
+ ),
150
+ };
94
151
  }
95
152
 
96
153
  /** `/word/_rels/document.xml.rels` for `/word/document.xml`. */
@@ -105,6 +162,22 @@ function relative(from: string, to: string): string {
105
162
  return to.startsWith(folder) ? to.slice(folder.length) : to;
106
163
  }
107
164
 
165
+ export interface ExportOptions {
166
+ /**
167
+ * Whether Word records edits as tracked changes (`w:trackRevisions`). Left out: as the
168
+ * original package has it (off in a new one).
169
+ */
170
+ trackRevisions?: boolean;
171
+ /**
172
+ * The bytes of a picture's image the package does not hold and its resource gives no `data:`
173
+ * URL for (an app's upload, by its URL). Undefined: the export fails, never drops it.
174
+ */
175
+ resource?: (
176
+ key: string,
177
+ resource: ResourceJSON,
178
+ ) => Promise<Uint8Array | undefined> | Uint8Array | undefined;
179
+ }
180
+
108
181
  /**
109
182
  * The document as a `.docx`. With `original` (the package it was imported from), the parts
110
183
  * Foli does not edit come back byte for byte and unchanged elements verbatim.
@@ -112,9 +185,29 @@ function relative(from: string, to: string): string {
112
185
  export async function exportDocx(
113
186
  document: FoliDocument,
114
187
  original?: DocxPackage,
188
+ options: ExportOptions = {},
115
189
  ): Promise<Uint8Array> {
116
190
  const doc = withThreadIds(parseDocument(document), original);
117
- return original ? intoPackage(doc, original) : newPackage(doc);
191
+ // Before the app is asked for any picture's bytes.
192
+ const reference = original ? undefined : packageReference(doc);
193
+ if (reference) {
194
+ throw new DocxError(
195
+ `The document refers to a part of its original package (${reference}): export it with that package`,
196
+ );
197
+ }
198
+ // The parts written from the model: their drawings are the document's own.
199
+ const rewritten = original
200
+ ? [
201
+ original.mainDocument,
202
+ ...original
203
+ .relationships(original.mainDocument)
204
+ .filter((r) => r.type === REL.comments && r.partName)
205
+ .map((r) => r.partName as string),
206
+ ]
207
+ : [];
208
+ const bytes = await pictureBytes(doc, original, options.resource);
209
+ const media = new Media(doc, original, bytes, rewritten);
210
+ return original ? intoPackage(doc, original, options, media) : newPackage(doc, options, media);
118
211
  }
119
212
 
120
213
  const PARA_ID = "w14:paraId";
@@ -177,14 +270,19 @@ function withThreadIds(doc: FoliDocument, pkg: DocxPackage | undefined): FoliDoc
177
270
  return copy;
178
271
  }
179
272
 
180
- async function intoPackage(doc: FoliDocument, pkg: DocxPackage): Promise<Uint8Array> {
273
+ async function intoPackage(
274
+ doc: FoliDocument,
275
+ pkg: DocxPackage,
276
+ options: ExportOptions,
277
+ media: Media,
278
+ ): Promise<Uint8Array> {
181
279
  const mainName = pkg.mainDocument;
182
280
  const main = pkg.xml(mainName);
183
281
  const body = child(main.root, "body");
184
282
  if (!body) throw new DocxError(`${mainName}: no w:body`);
185
283
  const namespaces = namespacesOf(main.root, main.source);
186
284
  const rels = new Relationships(pkg.relationships(mainName));
187
- const context = contextFor(namespaces, rels);
285
+ const context = contextFor(namespaces, rels, media, mainName);
188
286
 
189
287
  const content = blocksXml(doc.content.content ?? [], context) + bodySection(doc, namespaces);
190
288
  const documentXml =
@@ -262,7 +360,8 @@ async function intoPackage(doc: FoliDocument, pkg: DocxPackage): Promise<Uint8Ar
262
360
  REL.comments,
263
361
  "/word/comments.xml",
264
362
  CT.comments,
265
- (o, ns) => commentsXml(doc, o, contextFor(ns, commentRels)),
363
+ (o, ns) =>
364
+ commentsXml(doc, o, contextFor(ns, commentRels, media, commentsName ?? "/word/comments.xml")),
266
365
  doc.comments.length > 0,
267
366
  );
268
367
  if (comments && commentRels.added.length) writeRelationships(comments, commentRels);
@@ -277,7 +376,19 @@ async function intoPackage(doc: FoliDocument, pkg: DocxPackage): Promise<Uint8Ar
277
376
  );
278
377
  }
279
378
 
379
+ const { trackRevisions } = options;
380
+ if (trackRevisions !== undefined) {
381
+ part(
382
+ REL.settings,
383
+ "/word/settings.xml",
384
+ CT.settings,
385
+ (o) => (o ? withTrackRevisions(o.source, o.root, trackRevisions) : newSettingsXml()),
386
+ trackRevisions,
387
+ );
388
+ }
389
+
280
390
  if (rels.added.length) writeRelationships(mainName, rels);
391
+ add.push(...media.added);
281
392
  return pkg.write(replace, add);
282
393
 
283
394
  function writeRelationships(source: string, relationships: Relationships): void {
@@ -326,15 +437,13 @@ function changedThreads(doc: FoliDocument, pkg: DocxPackage): boolean {
326
437
  }
327
438
 
328
439
  /** A new package: content types, relationships, the document and the parts it needs. */
329
- async function newPackage(doc: FoliDocument): Promise<Uint8Array> {
330
- const reference = packageReference(doc);
331
- if (reference) {
332
- throw new DocxError(
333
- `The document refers to a part of its original package (${reference}): export it with that package`,
334
- );
335
- }
440
+ async function newPackage(
441
+ doc: FoliDocument,
442
+ options: ExportOptions,
443
+ media: Media,
444
+ ): Promise<Uint8Array> {
336
445
  const rels = new Relationships([]);
337
- const context = contextFor(DEFAULT_NAMESPACES, rels);
446
+ const context = contextFor(DEFAULT_NAMESPACES, rels, media, "/word/document.xml");
338
447
  const main = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n<w:document ${NEW_ROOT_ATTRIBUTES}><w:body>${blocksXml(doc.content.content ?? [], context)}${bodySection(doc, DEFAULT_NAMESPACES)}</w:body></w:document>`;
339
448
  const parts: { name: string; text: string; contentType: string }[] = [
340
449
  { name: "/word/document.xml", text: main, contentType: CT.main },
@@ -358,7 +467,11 @@ async function newPackage(doc: FoliDocument): Promise<Uint8Array> {
358
467
  "/word/comments.xml",
359
468
  REL.comments,
360
469
  CT.comments,
361
- commentsXml(doc, undefined, contextFor(DEFAULT_NAMESPACES, commentRels)),
470
+ commentsXml(
471
+ doc,
472
+ undefined,
473
+ contextFor(DEFAULT_NAMESPACES, commentRels, media, "/word/comments.xml"),
474
+ ),
362
475
  );
363
476
  if (commentRels.added.length)
364
477
  parts.push({
@@ -375,12 +488,14 @@ async function newPackage(doc: FoliDocument): Promise<Uint8Array> {
375
488
  );
376
489
  }
377
490
  }
491
+ if (options.trackRevisions)
492
+ add("/word/settings.xml", REL.settings, CT.settings, newSettingsXml());
378
493
  parts.push({
379
494
  name: "/word/_rels/document.xml.rels",
380
495
  text: rels.xml(undefined),
381
496
  contentType: CT.rels,
382
497
  });
383
- const overrides = parts
498
+ const overrides = [...parts, ...media.added]
384
499
  .filter((p) => p.contentType !== CT.rels)
385
500
  .map((p) => `<Override PartName="${p.name}" ContentType="${p.contentType}"/>`)
386
501
  .join("");
@@ -397,6 +512,7 @@ async function newPackage(doc: FoliDocument): Promise<Uint8Array> {
397
512
  ];
398
513
  const entries = [];
399
514
  for (const [name, text] of files) entries.push(await deflateEntry(name, encoder.encode(text)));
515
+ for (const part of media.added) entries.push(await deflateEntry(part.name.slice(1), part.data));
400
516
  return writeZip(entries);
401
517
  }
402
518
 
@@ -24,9 +24,11 @@ import {
24
24
  usableStyle,
25
25
  } from "../import/parts.js";
26
26
  import { Recorder } from "../import/report.js";
27
+ import { DocxError } from "../package.js";
27
28
  import type { XmlElement, XmlNode } from "../xml.js";
28
29
  import { blocksXml, type WriteContext } from "./content.js";
29
30
  import { paragraphPropertiesXml, runPropertiesXml, same } from "./properties.js";
31
+ import { stylePartsXml } from "./tables.js";
30
32
  import {
31
33
  attributesOf,
32
34
  el,
@@ -187,6 +189,18 @@ function styleXml(style: StyleJSON, ns: Namespaces): string {
187
189
  if (reread && same(normalizeStyle(style), normalizeStyle(reread))) return style.ext as string;
188
190
  }
189
191
  const reread = o ? styleOf(o.element, reading(o.source)) : undefined;
192
+ // A table style read from the file has its parts written as read (`w:tblPr`… kept): a change
193
+ // would be lost. A new one (Word's Table Grid, added by a command) is written from the model,
194
+ // without conditional formats.
195
+ for (const key of o
196
+ ? (["table", "row", "cell", "conditions"] as const)
197
+ : (["conditions"] as const)) {
198
+ if (!same(style[key], reread?.[key])) {
199
+ throw new DocxError(
200
+ `Style ${style.id}: a changed table style (${key}) cannot be exported yet`,
201
+ );
202
+ }
203
+ }
190
204
  const generated = new Map<string, string>([
191
205
  ["name", val("name", style.name)],
192
206
  ["basedOn", val("basedOn", style.basedOn)],
@@ -208,6 +222,7 @@ function styleXml(style: StyleJSON, ns: Namespaces): string {
208
222
  "rPr",
209
223
  runPropertiesXml(style.run ?? [], childSource(o, "rPr"), ns, "w:rPr", false, undefined, true),
210
224
  ],
225
+ ...(o ? [] : Object.entries(stylePartsXml(style, ns))),
211
226
  ]);
212
227
  const children = merged(STYLE_ORDER, new Set(generated.keys()), generated, o);
213
228
  const open =