@folijs/view 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 (82) hide show
  1. package/CHANGELOG.md +161 -0
  2. package/README.md +1 -1
  3. package/dist/clipboard.d.ts +1 -51
  4. package/dist/clipboard.d.ts.map +1 -1
  5. package/dist/clipboard.js +65 -13
  6. package/dist/clipboard.js.map +1 -1
  7. package/dist/extension.d.ts +90 -0
  8. package/dist/extension.d.ts.map +1 -0
  9. package/dist/extension.js +152 -0
  10. package/dist/extension.js.map +1 -0
  11. package/dist/index.d.ts +2 -1
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js.map +1 -1
  14. package/dist/layout/flow.d.ts +1 -282
  15. package/dist/layout/flow.d.ts.map +1 -1
  16. package/dist/layout/flow.js +21 -4
  17. package/dist/layout/flow.js.map +1 -1
  18. package/dist/print.d.ts +1 -17
  19. package/dist/print.d.ts.map +1 -1
  20. package/dist/print.js +5 -1
  21. package/dist/print.js.map +1 -1
  22. package/dist/render.d.ts +1 -24
  23. package/dist/render.d.ts.map +1 -1
  24. package/dist/render.js +4 -1
  25. package/dist/render.js.map +1 -1
  26. package/dist/view.d.ts +34 -67
  27. package/dist/view.d.ts.map +1 -1
  28. package/dist/view.js +209 -24
  29. package/dist/view.js.map +1 -1
  30. package/dist/word/blocks.d.ts +0 -175
  31. package/dist/word/blocks.d.ts.map +1 -1
  32. package/dist/word/blocks.js +106 -24
  33. package/dist/word/blocks.js.map +1 -1
  34. package/dist/word/columns.d.ts +1 -22
  35. package/dist/word/columns.d.ts.map +1 -1
  36. package/dist/word/columns.js +15 -3
  37. package/dist/word/columns.js.map +1 -1
  38. package/dist/word/controls.d.ts +1 -62
  39. package/dist/word/controls.d.ts.map +1 -1
  40. package/dist/word/controls.js +6 -1
  41. package/dist/word/controls.js.map +1 -1
  42. package/dist/word/edit.d.ts +1 -83
  43. package/dist/word/edit.d.ts.map +1 -1
  44. package/dist/word/edit.js +183 -5
  45. package/dist/word/edit.js.map +1 -1
  46. package/dist/word/matches.d.ts +1 -22
  47. package/dist/word/matches.d.ts.map +1 -1
  48. package/dist/word/matches.js +6 -1
  49. package/dist/word/matches.js.map +1 -1
  50. package/dist/word/notes.d.ts +0 -103
  51. package/dist/word/notes.d.ts.map +1 -1
  52. package/dist/word/notes.js +15 -4
  53. package/dist/word/notes.js.map +1 -1
  54. package/dist/word/pages.d.ts +15 -10
  55. package/dist/word/pages.d.ts.map +1 -1
  56. package/dist/word/pages.js +3 -2
  57. package/dist/word/pages.js.map +1 -1
  58. package/dist/word/regions.d.ts +0 -111
  59. package/dist/word/regions.d.ts.map +1 -1
  60. package/dist/word/regions.js +19 -5
  61. package/dist/word/regions.js.map +1 -1
  62. package/dist/word/table.d.ts +1 -78
  63. package/dist/word/table.d.ts.map +1 -1
  64. package/dist/word/table.js +13 -3
  65. package/dist/word/table.js.map +1 -1
  66. package/package.json +6 -3
  67. package/src/clipboard.ts +91 -21
  68. package/src/extension.ts +267 -0
  69. package/src/index.ts +10 -0
  70. package/src/layout/flow.ts +59 -13
  71. package/src/print.ts +9 -2
  72. package/src/render.ts +6 -1
  73. package/src/view.ts +245 -40
  74. package/src/word/blocks.ts +124 -30
  75. package/src/word/columns.ts +19 -4
  76. package/src/word/controls.ts +13 -3
  77. package/src/word/edit.ts +207 -9
  78. package/src/word/matches.ts +6 -1
  79. package/src/word/notes.ts +19 -6
  80. package/src/word/pages.ts +19 -3
  81. package/src/word/regions.ts +27 -8
  82. package/src/word/table.ts +33 -8
@@ -1,181 +1,6 @@
1
- /**
2
- * Schema v3 blocks as DOM, formatted as Word formats them (8.6b): every paragraph's and run's
3
- * effective formatting from `Resolver` as inline CSS, list markers, tracked changes, comment
4
- * anchors, and content the model keeps opaque shown as text. Read-only: built with
5
- * createElement/textContent only (never innerHTML); the page layout is in `pages.ts`.
6
- */
7
- import { type FoliDocument, type ListMarker, type NodeJSON, type ParagraphFormat, Resolver, type ResourceJSON, type RunFormat, type SectionJSON } from "@folijs/core";
8
- /** Marks the <br> of an explicit page break (the page flow ends the page after its line). */
9
- export declare const WORD_PAGE_BREAK_ATTR = "data-page-break";
10
- /** Marks the <br> of an explicit column break (the flow ends the column after its line). */
11
- export declare const WORD_COLUMN_BREAK_ATTR = "data-column-break";
12
- /** CSS px per twip (1/1440 inch; CSS: 96 px per inch). */
13
- export declare const PX_PER_TWIP: number;
14
1
  /** EMU (DrawingML's unit: 914 400 per inch) per CSS px. */
15
2
  export declare const EMU_PER_PX: number;
16
- /** The URL to show a picture's image from (its resource key), if one is known. */
17
- export type ImageSource = (key: string) => string | undefined;
18
- /** Marks a picture's element (its resource key). */
19
- export declare const PICTURE_ATTR = "data-foli-picture";
20
- /** The accessible name of a picture with no alt text that is not decorative. */
21
- export declare const NO_ALT_LABEL = "Picture without alt text";
22
- /**
23
- * The URL a resource gives on its own: an image `data:` URL, or a web or `blob:` URL; none for
24
- * an image in a package part (the app's resolver gives one) or anything else.
25
- */
26
- export declare function ownImageUrl(resource: ResourceJSON | undefined): string | undefined;
27
- /**
28
- * A picture as shown: its image at its size, or, when no URL is known for it, a box of that size
29
- * with its alt text. A picture with no alt text that is not decorative is marked (`data-foli-
30
- * no-alt`); a decorative one has an empty alt.
31
- */
32
- export declare function pictureElement(attrs: Record<string, unknown>, doc: Document, image?: ImageSource): HTMLElement;
33
- /** Marks the element holding a floating picture (its wrapping), drawn at its paragraph's start. */
34
- export declare const FLOAT_ATTR = "data-foli-float";
35
- /** A section's page, in CSS px: what a floating picture is positioned against. */
36
- export interface FloatGeometry {
37
- readonly pageWidth: number;
38
- readonly pageHeight: number;
39
- readonly marginLeft: number;
40
- readonly marginTop: number;
41
- readonly textWidth: number;
42
- readonly textHeight: number;
43
- }
44
- /** The page geometry of `section` (Word's Letter page and margins where it does not say). */
45
- export declare function floatGeometry(section: SectionJSON | undefined): FloatGeometry;
46
- /**
47
- * A floating picture (10.9, ADR-0006) as CSS floats lay it out, put first in its anchor
48
- * paragraph: `holder` holds the picture (`FLOAT_ATTR`), `nodes` go in the paragraph (a
49
- * zero-width spacer float before it gives its offset from the paragraph's top).
50
- * - Square (tight and through shown as square): a float on the side the picture is on, its
51
- * distance from the text as its margin; text goes on the other side only.
52
- * - Top and bottom: a float as wide as the paragraph, the picture in it at its position.
53
- * - Behind and in front of text: absolutely positioned on the page (z-index -1 or 1; the page is
54
- * the containing block and its own stacking context).
55
- * shortcut: a wrapping picture placed against the page or its margins vertically is drawn at
56
- * its paragraph's top; horizontal positions are against the paragraph's box (its indents in);
57
- * all against `geometry` (one section's page), not each page's. A float's top is never above an
58
- * earlier float's (CSS), and `clear` stacks it below earlier floats on its side: several floats
59
- * in a paragraph, or one above a float of an earlier paragraph, add their offsets down and do
60
- * not sit side by side.
61
- */
62
- export declare function floatElements(attrs: Record<string, unknown>, doc: Document, image: ImageSource | undefined, geometry: FloatGeometry): {
63
- nodes: HTMLElement[];
64
- holder: HTMLElement;
65
- };
66
3
  /** Which version of tracked changes to show. */
67
4
  /** How tracked changes show (`@folijs/core`'s, for `renderDocument` too). */
68
5
  export type { ReviewView } from "@folijs/core";
69
- import type { ReviewView } from "@folijs/core";
70
- /** The color of `author`'s changes: always the same for a name. */
71
- export declare function authorColor(author: string): string;
72
- /** The bar beside a paragraph with changes (`markup` and `simple`), drawn in the margin. */
73
- export declare const CHANGE_BAR = "-4px 0 0 0 #6B6B6B";
74
- /**
75
- * The element around an inserted or deleted run: `ins` or `del` (named for screen readers by
76
- * its title), styled for `review`. Deleted text not shown is hidden, not left out: the editable
77
- * view maps positions through it.
78
- */
79
- export declare function changeElement(doc: Document, inserted: boolean, author: string, date: string | null, review: ReviewView): HTMLElement;
80
- export interface BlockOptions {
81
- /** `markup` (the default): insertions underlined, deletions struck through; `simple`, `final`: as if accepted. */
82
- review?: ReviewView;
83
- /** Fields show their codes instead of their results (Word's Alt+F9). */
84
- fieldCodes?: boolean;
85
- /**
86
- * The ratio of a font's normal line height to its size (`fontFamily`: a CSS font-family
87
- * list). Word's single line spacing is the font's own line height; multiples scale it.
88
- * Measured by the page layout; 1.2 when nothing measures (no layout engine).
89
- */
90
- lineRatio?: (fontFamily: string) => number;
91
- /**
92
- * The URL to show a picture's image from (`key` in `resources`): the app's (a package part's
93
- * object URL…); `null` (or "") shows the picture's box. Left out, or undefined for a key: the
94
- * resource's own image `data:` URL or web URL (fetched as it is shown).
95
- */
96
- resource?: (key: string, resource: ResourceJSON) => string | null | undefined;
97
- /** The document's resolver, when the caller has one (a story of it, drawn per page). */
98
- resolver?: Resolver;
99
- /** What note references show, by story, and what a note's own mark shows (never stored). */
100
- notes?: {
101
- references?: ReadonlyMap<string, string>;
102
- mark?: string;
103
- };
104
- }
105
- /** On the element showing a note reference's number: the note's story. */
106
- export declare const NOTE_REF_ATTR = "data-foli-note-ref";
107
- /** On a number drawn for a note, at its reference or its mark: not text of the document. */
108
- export declare const NOTE_NUMBER_ATTR = "data-foli-note-number";
109
- /** The line a separator run draws, when `xml` is one (`w:separator`, `w:continuationSeparator`). */
110
- export declare function separatorElement(xml: Element | null, doc: Document): HTMLElement | null;
111
- /** The source for a document's pictures: the app's URL, else the resource's own. */
112
- export declare function imageSource(resources: Readonly<Record<string, ResourceJSON>> | undefined, resolve?: (key: string, resource: ResourceJSON) => string | null | undefined): ImageSource;
113
- /** A rendered block and what the page flow needs to know about it. */
114
- export interface WordBlock {
115
- element: HTMLElement;
116
- /** Indices in the document's content of the nodes it shows (several when paragraphs merged). */
117
- nodes: number[];
118
- /** Space before and after, in CSS px (Word adds them: the flow places them). */
119
- before: number;
120
- after: number;
121
- keepNext: boolean;
122
- keepLines: boolean;
123
- pageBreakBefore: boolean;
124
- /** The page setup of the section this block ends (null: the section goes on). */
125
- section: SectionJSON | null;
126
- }
127
- /** A CSS font-family list for a Word font name: the font, its substitutes, a generic family. */
128
- export declare function fontStack(name: string | null): string;
129
- /** The one font name a run shows for Latin text. */
130
- export declare const latin: (run: RunFormat) => string | null;
131
- /** A line height in CSS for text in `run` (`ratio`: its font's normal line height ratio). */
132
- export declare function lineHeight(paragraph: ParagraphFormat, run: RunFormat, ratio: number): string;
133
- /** Run formatting as inline CSS on `element`. */
134
- export declare function styleRun(element: HTMLElement, run: RunFormat, line: string): void;
135
- /** Paragraph properties as inline CSS on `element` (spacing is the flow's). */
136
- export declare function styleParagraph(element: HTMLElement, paragraph: ParagraphFormat): void;
137
- /** Text a run of opaque XML shows: its `w:t` elements (field results, content controls). */
138
- export declare function opaqueText(element: Element): string;
139
- /** Opaque XML's text, a line per paragraph (`w:p`), or its runs' text when it has none. */
140
- export declare function opaqueParagraphsText(element: Element): string;
141
- /**
142
- * Parses verbatim WordprocessingML (opaque content) into an inert XML document, declaring the
143
- * prefixes it uses; null when it is not well-formed.
144
- */
145
- export declare function parseOpaque(xml: string, doc: Document): Element | null;
146
- /**
147
- * Renders a document's blocks. `final` review merges a paragraph whose mark was deleted into
148
- * the next one, as accepting the deletion does.
149
- */
150
- export declare function renderBlocks(document: FoliDocument, doc: Document, options?: BlockOptions): WordBlock[];
151
- /**
152
- * Whether a paragraph's line holds nothing but inline pictures: Word's line then ends at the
153
- * picture's foot (its PDFs of the corpus: no room below it for the text it does not have).
154
- */
155
- export declare function onlyPictures<T>(inline: Iterable<T>, type: (node: T) => string, floats: (node: T) => boolean): boolean;
156
- /**
157
- * The top margin of a paragraph after another (whose space after is `above`) in a box the page
158
- * flow does not lay out (a table cell). Adjacent margins collapse to the larger: Word's rule. In
159
- * a document where the two spaces add up this margin holds both, so the collapse gives the sum
160
- * and no paragraph's shading or border grows.
161
- */
162
- export declare function marginAbove(before: number, above: number, resolver: Resolver): number;
163
- /** A paragraph's element: a heading of its outline level (1-6), else a paragraph. */
164
- export declare function tagOf(paragraph: ParagraphFormat): string;
165
- /** A list marker: its text, then what follows it (a tab to the text's indent, a space). */
166
- export declare function markerElement(marker: ListMarker, paragraph: ParagraphFormat, doc: Document, ratio: (family: string) => number): HTMLElement;
167
- /**
168
- * A block the model keeps opaque (tables until Phase 10, block content controls), shown from
169
- * its XML: a table as a table of its cells' paragraphs, anything else as its paragraphs. Only
170
- * text is read: no formatting beyond the paragraph styles.
171
- */
172
- export declare function opaqueBlock(node: NodeJSON, index: number, resolver: Resolver, doc: Document, ratio: (family: string) => number, image?: ImageSource,
173
- /** The page floating pictures in its cells are placed against. */
174
- geometry?: FloatGeometry, codes?: boolean, notes?: BlockOptions["notes"]): WordBlock;
175
- /** A border of the model (`BorderJSON`) as CSS; undefined when it says none. */
176
- export declare function borderJsonCss(border: {
177
- style?: string;
178
- size?: number;
179
- color?: string;
180
- } | undefined): string | undefined;
181
6
  //# sourceMappingURL=blocks.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/word/blocks.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/word/blocks.ts"],"names":[],"mappings":"AAwCA,2DAA2D;AAC3D,eAAO,MAAM,UAAU,QAAe,CAAC;AA+QvC,gDAAgD;AAChD,6EAA6E;AAC7E,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
@@ -4,22 +4,39 @@
4
4
  * anchors, and content the model keeps opaque shown as text. Read-only: built with
5
5
  * createElement/textContent only (never innerHTML); the page layout is in `pages.ts`.
6
6
  */
7
- import { fieldDisplay, Resolver, } from "@folijs/core";
8
- /** Marks the <br> of an explicit page break (the page flow ends the page after its line). */
7
+ import { fieldDisplay, } from "@folijs/core";
8
+ import { CUSTOM_TYPE, foreignTextOf, Resolver, } from "@folijs/core/internal";
9
+ /**
10
+ * Marks the <br> of an explicit page break (the page flow ends the page after its line).
11
+ * @internal
12
+ */
9
13
  export const WORD_PAGE_BREAK_ATTR = "data-page-break";
10
- /** Marks the <br> of an explicit column break (the flow ends the column after its line). */
14
+ /**
15
+ * Marks the <br> of an explicit column break (the flow ends the column after its line).
16
+ * @internal
17
+ */
11
18
  export const WORD_COLUMN_BREAK_ATTR = "data-column-break";
12
- /** CSS px per twip (1/1440 inch; CSS: 96 px per inch). */
19
+ /**
20
+ * CSS px per twip (1/1440 inch; CSS: 96 px per inch).
21
+ * @internal
22
+ */
13
23
  export const PX_PER_TWIP = 96 / 1440;
14
24
  /** EMU (DrawingML's unit: 914 400 per inch) per CSS px. */
15
25
  export const EMU_PER_PX = 914_400 / 96;
16
- /** Marks a picture's element (its resource key). */
26
+ /**
27
+ * Marks a picture's element (its resource key).
28
+ * @internal
29
+ */
17
30
  export const PICTURE_ATTR = "data-foli-picture";
18
- /** The accessible name of a picture with no alt text that is not decorative. */
31
+ /**
32
+ * The accessible name of a picture with no alt text that is not decorative.
33
+ * @internal
34
+ */
19
35
  export const NO_ALT_LABEL = "Picture without alt text";
20
36
  /**
21
37
  * The URL a resource gives on its own: an image `data:` URL, or a web or `blob:` URL; none for
22
38
  * an image in a package part (the app's resolver gives one) or anything else.
39
+ * @internal
23
40
  */
24
41
  export function ownImageUrl(resource) {
25
42
  const data = resource?.data;
@@ -32,6 +49,7 @@ export function ownImageUrl(resource) {
32
49
  * A picture as shown: its image at its size, or, when no URL is known for it, a box of that size
33
50
  * with its alt text. A picture with no alt text that is not decorative is marked (`data-foli-
34
51
  * no-alt`); a decorative one has an empty alt.
52
+ * @internal
35
53
  */
36
54
  export function pictureElement(attrs, doc, image) {
37
55
  const key = String(attrs.resource ?? "");
@@ -77,9 +95,15 @@ export function pictureElement(attrs, doc, image) {
77
95
  style.height = height;
78
96
  return element;
79
97
  }
80
- /** Marks the element holding a floating picture (its wrapping), drawn at its paragraph's start. */
98
+ /**
99
+ * Marks the element holding a floating picture (its wrapping), drawn at its paragraph's start.
100
+ * @internal
101
+ */
81
102
  export const FLOAT_ATTR = "data-foli-float";
82
- /** The page geometry of `section` (Word's Letter page and margins where it does not say). */
103
+ /**
104
+ * The page geometry of `section` (Word's Letter page and margins where it does not say).
105
+ * @internal
106
+ */
83
107
  export function floatGeometry(section) {
84
108
  const m = section?.margins ?? {};
85
109
  const width = section?.pageSize?.width ?? 12_240;
@@ -166,6 +190,7 @@ function floatTop(v, height, g) {
166
190
  * earlier float's (CSS), and `clear` stacks it below earlier floats on its side: several floats
167
191
  * in a paragraph, or one above a float of an earlier paragraph, add their offsets down and do
168
192
  * not sit side by side.
193
+ * @internal
169
194
  */
170
195
  export function floatElements(attrs, doc, image, geometry) {
171
196
  const float = attrs.float;
@@ -236,19 +261,26 @@ const AUTHOR_COLORS = [
236
261
  "#AD1457",
237
262
  "#5D4037",
238
263
  ];
239
- /** The color of `author`'s changes: always the same for a name. */
264
+ /**
265
+ * The color of `author`'s changes: always the same for a name.
266
+ * @internal
267
+ */
240
268
  export function authorColor(author) {
241
269
  let hash = 0;
242
270
  for (const c of author)
243
271
  hash = (hash * 31 + (c.codePointAt(0) ?? 0)) >>> 0;
244
272
  return AUTHOR_COLORS[hash % AUTHOR_COLORS.length];
245
273
  }
246
- /** The bar beside a paragraph with changes (`markup` and `simple`), drawn in the margin. */
274
+ /**
275
+ * The bar beside a paragraph with changes (`markup` and `simple`), drawn in the margin.
276
+ * @internal
277
+ */
247
278
  export const CHANGE_BAR = "-4px 0 0 0 #6B6B6B";
248
279
  /**
249
280
  * The element around an inserted or deleted run: `ins` or `del` (named for screen readers by
250
281
  * its title), styled for `review`. Deleted text not shown is hidden, not left out: the editable
251
282
  * view maps positions through it.
283
+ * @internal
252
284
  */
253
285
  export function changeElement(doc, inserted, author, date, review) {
254
286
  const element = doc.createElement(inserted ? "ins" : "del");
@@ -265,13 +297,22 @@ export function changeElement(doc, inserted, author, date, review) {
265
297
  }
266
298
  return element;
267
299
  }
268
- /** On the element showing a note reference's number: the note's story. */
300
+ /**
301
+ * On the element showing a note reference's number: the note's story.
302
+ * @internal
303
+ */
269
304
  export const NOTE_REF_ATTR = "data-foli-note-ref";
270
- /** On a number drawn for a note, at its reference or its mark: not text of the document. */
305
+ /**
306
+ * On a number drawn for a note, at its reference or its mark: not text of the document.
307
+ * @internal
308
+ */
271
309
  export const NOTE_NUMBER_ATTR = "data-foli-note-number";
272
310
  /** Word's footnote separator is two inches long; its continuation line here is the same. */
273
311
  const SEPARATOR_WIDTH = 192;
274
- /** The line a separator run draws, when `xml` is one (`w:separator`, `w:continuationSeparator`). */
312
+ /**
313
+ * The line a separator run draws, when `xml` is one (`w:separator`, `w:continuationSeparator`).
314
+ * @internal
315
+ */
275
316
  export function separatorElement(xml, doc) {
276
317
  if (!xml)
277
318
  return null;
@@ -289,7 +330,10 @@ export function separatorElement(xml, doc) {
289
330
  style.verticalAlign = "middle";
290
331
  return line;
291
332
  }
292
- /** The source for a document's pictures: the app's URL, else the resource's own. */
333
+ /**
334
+ * The source for a document's pictures: the app's URL, else the resource's own.
335
+ * @internal
336
+ */
293
337
  export function imageSource(resources, resolve) {
294
338
  return (key) => {
295
339
  const resource = resources && Object.hasOwn(resources, key) ? resources[key] : undefined;
@@ -314,7 +358,10 @@ const SUBSTITUTES = {
314
358
  };
315
359
  const SERIF = new Set(["cambria", "times new roman", "georgia", "garamond", "book antiqua"]);
316
360
  const MONOSPACE = new Set(["courier new", "consolas", "courier"]);
317
- /** A CSS font-family list for a Word font name: the font, its substitutes, a generic family. */
361
+ /**
362
+ * A CSS font-family list for a Word font name: the font, its substitutes, a generic family.
363
+ * @internal
364
+ */
318
365
  export function fontStack(name) {
319
366
  const font = name ?? "Times New Roman";
320
367
  const key = font.toLowerCase();
@@ -370,9 +417,15 @@ const BORDER_STYLES = {
370
417
  none: "none",
371
418
  nil: "none",
372
419
  };
373
- /** The one font name a run shows for Latin text. */
420
+ /**
421
+ * The one font name a run shows for Latin text.
422
+ * @internal
423
+ */
374
424
  export const latin = (run) => run.font.ascii ?? run.font.hAnsi;
375
- /** A line height in CSS for text in `run` (`ratio`: its font's normal line height ratio). */
425
+ /**
426
+ * A line height in CSS for text in `run` (`ratio`: its font's normal line height ratio).
427
+ * @internal
428
+ */
376
429
  export function lineHeight(paragraph, run, ratio) {
377
430
  const sizePx = (run.size / 2) * (96 / 72);
378
431
  const { line, lineRule } = paragraph.spacing;
@@ -384,7 +437,10 @@ export function lineHeight(paragraph, run, ratio) {
384
437
  return `${Math.max(line * PX_PER_TWIP, ratio * sizePx)}px`;
385
438
  return String((ratio * line) / 240);
386
439
  }
387
- /** Run formatting as inline CSS on `element`. */
440
+ /**
441
+ * Run formatting as inline CSS on `element`.
442
+ * @internal
443
+ */
388
444
  export function styleRun(element, run, line) {
389
445
  const { style } = element;
390
446
  style.fontFamily = fontStack(latin(run));
@@ -426,7 +482,10 @@ export function styleRun(element, run, line) {
426
482
  if (run.hidden)
427
483
  style.display = "none";
428
484
  }
429
- /** Paragraph properties as inline CSS on `element` (spacing is the flow's). */
485
+ /**
486
+ * Paragraph properties as inline CSS on `element` (spacing is the flow's).
487
+ * @internal
488
+ */
430
489
  export function styleParagraph(element, paragraph) {
431
490
  const { style } = element;
432
491
  style.margin = "0";
@@ -460,7 +519,10 @@ export function styleParagraph(element, paragraph) {
460
519
  * same drawing again for older readers).
461
520
  */
462
521
  const NOT_INLINE = new Set(["txbxContent", "Fallback"]);
463
- /** Text a run of opaque XML shows: its `w:t` elements (field results, content controls). */
522
+ /**
523
+ * Text a run of opaque XML shows: its `w:t` elements (field results, content controls).
524
+ * @internal
525
+ */
464
526
  export function opaqueText(element) {
465
527
  let text = "";
466
528
  for (const node of element.children) {
@@ -475,7 +537,10 @@ export function opaqueText(element) {
475
537
  }
476
538
  return text;
477
539
  }
478
- /** Opaque XML's text, a line per paragraph (`w:p`), or its runs' text when it has none. */
540
+ /**
541
+ * Opaque XML's text, a line per paragraph (`w:p`), or its runs' text when it has none.
542
+ * @internal
543
+ */
479
544
  export function opaqueParagraphsText(element) {
480
545
  const paragraphs = [...element.getElementsByTagName("*")].filter((e) => e.localName === "p");
481
546
  if (element.localName === "p")
@@ -504,6 +569,7 @@ const CELL_CONTENT = new Set(["p", "tbl"]);
504
569
  /**
505
570
  * Parses verbatim WordprocessingML (opaque content) into an inert XML document, declaring the
506
571
  * prefixes it uses; null when it is not well-formed.
572
+ * @internal
507
573
  */
508
574
  export function parseOpaque(xml, doc) {
509
575
  const view = doc.defaultView;
@@ -525,6 +591,7 @@ export function parseOpaque(xml, doc) {
525
591
  /**
526
592
  * Renders a document's blocks. `final` review merges a paragraph whose mark was deleted into
527
593
  * the next one, as accepting the deletion does.
594
+ * @internal
528
595
  */
529
596
  export function renderBlocks(document, doc, options = {}) {
530
597
  const review = options.review ?? "markup";
@@ -656,6 +723,7 @@ function joinDisplays(before, length, after) {
656
723
  /**
657
724
  * Whether a paragraph's line holds nothing but inline pictures: Word's line then ends at the
658
725
  * picture's foot (its PDFs of the corpus: no room below it for the text it does not have).
726
+ * @internal
659
727
  */
660
728
  export function onlyPictures(inline, type, floats) {
661
729
  let found = false;
@@ -686,11 +754,15 @@ const INVISIBLE = new Set([
686
754
  * flow does not lay out (a table cell). Adjacent margins collapse to the larger: Word's rule. In
687
755
  * a document where the two spaces add up this margin holds both, so the collapse gives the sum
688
756
  * and no paragraph's shading or border grows.
757
+ * @internal
689
758
  */
690
759
  export function marginAbove(before, above, resolver) {
691
760
  return resolver.addsParagraphSpacing ? before + above : before;
692
761
  }
693
- /** A paragraph's element: a heading of its outline level (1-6), else a paragraph. */
762
+ /**
763
+ * A paragraph's element: a heading of its outline level (1-6), else a paragraph.
764
+ * @internal
765
+ */
694
766
  export function tagOf(paragraph) {
695
767
  const level = paragraph.outlineLevel;
696
768
  return level !== null && level >= 0 && level < 6 ? `h${level + 1}` : "p";
@@ -730,7 +802,10 @@ const SYMBOLS = {
730
802
  "\uF0D8": "\u27A2", // Wingdings: arrowhead
731
803
  "\uF0FC": "\u2713", // Wingdings: check mark
732
804
  };
733
- /** A list marker: its text, then what follows it (a tab to the text's indent, a space). */
805
+ /**
806
+ * A list marker: its text, then what follows it (a tab to the text's indent, a space).
807
+ * @internal
808
+ */
734
809
  export function markerElement(marker, paragraph, doc, ratio) {
735
810
  const span = doc.createElement("span");
736
811
  span.dataset.foliMarker = "";
@@ -832,6 +907,9 @@ function renderInline(parent, inline, paragraphRun, paragraph, context) {
832
907
  text = context.notes?.references?.get(String(attrs.story)) ?? "";
833
908
  else if (node.type === "noteMark")
834
909
  text = context.notes?.mark ?? "";
910
+ // A custom node without its extension here (ADR-0008): its `.docx` text, else its type.
911
+ else if (CUSTOM_TYPE.test(node.type))
912
+ text = foreignTextOf(node) ?? `[${node.type}]`;
835
913
  else if (node.type === "opaqueInline") {
836
914
  const xml = parseOpaque(String(attrs.xml ?? ""), doc);
837
915
  const separator = separatorElement(xml, doc);
@@ -885,6 +963,7 @@ function renderInline(parent, inline, paragraphRun, paragraph, context) {
885
963
  * A block the model keeps opaque (tables until Phase 10, block content controls), shown from
886
964
  * its XML: a table as a table of its cells' paragraphs, anything else as its paragraphs. Only
887
965
  * text is read: no formatting beyond the paragraph styles.
966
+ * @internal
888
967
  */
889
968
  export function opaqueBlock(node, index, resolver, doc, ratio, image,
890
969
  /** The page floating pictures in its cells are placed against. */
@@ -1127,7 +1206,10 @@ function opaqueTable(tbl, resolver, doc, ratio) {
1127
1206
  table.append(body);
1128
1207
  return table;
1129
1208
  }
1130
- /** A border of the model (`BorderJSON`) as CSS; undefined when it says none. */
1209
+ /**
1210
+ * A border of the model (`BorderJSON`) as CSS; undefined when it says none.
1211
+ * @internal
1212
+ */
1131
1213
  export function borderJsonCss(border) {
1132
1214
  if (!border)
1133
1215
  return undefined;