@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
package/src/word/edit.ts CHANGED
@@ -10,18 +10,30 @@
10
10
  * opaque inline node a leaf element.
11
11
  */
12
12
  import {
13
- type CellFormat,
14
13
  type FieldDisplay,
15
14
  fieldDisplay,
16
15
  isSafeHref,
17
- type ListMarker,
18
16
  type Mark,
19
17
  type MarkJSON,
20
18
  type Node as ModelNode,
19
+ } from "@folijs/core";
20
+ import {
21
+ type CellFormat,
22
+ type ListMarker,
21
23
  type RunFormat,
22
24
  referencesIn,
23
25
  type WordContext,
24
- } from "@folijs/core";
26
+ } from "@folijs/core/internal";
27
+ import {
28
+ applyAttrs,
29
+ type Decoration,
30
+ type Drawn,
31
+ type NodeView,
32
+ type NodeViewDOM,
33
+ nodeViewDOM,
34
+ reportError,
35
+ type Views,
36
+ } from "../extension.js";
25
37
  import type { BlockDesc, LeafDesc } from "../render.js";
26
38
  import {
27
39
  CHANGE_BAR,
@@ -79,7 +91,10 @@ function hasChanges(node: ModelNode): boolean {
79
91
  return found;
80
92
  }
81
93
 
82
- /** What the page flow needs to know about a v3 block. */
94
+ /**
95
+ * What the page flow needs to know about a v3 block.
96
+ * @internal
97
+ */
83
98
  export interface WordInfo {
84
99
  /** Space before and after in CSS px (Word adds them: the flow places them). */
85
100
  before: number;
@@ -104,22 +119,33 @@ function childTypes(node: ModelNode): string[] {
104
119
  return types;
105
120
  }
106
121
 
107
- /** A rendered v3 block: a view block plus its flow information and what it was rendered for. */
122
+ /**
123
+ * A rendered v3 block: a view block plus its flow information and what it was rendered for.
124
+ * @internal
125
+ */
108
126
  export interface WordBlockDesc extends BlockDesc {
109
127
  readonly word: WordInfo;
110
128
  /** What the rendering depends on besides the node (its marker, open comments). */
111
129
  readonly key: string;
130
+ /**
131
+ * A custom block's node view that may split: where it may break, as the bottoms of its root's
132
+ * children from its top (client px; the last is its height). Its `splits` are then the layout
133
+ * px from its top where each fragment after the first starts, not content offsets.
134
+ */
135
+ readonly parts?: () => number[];
112
136
  }
113
137
 
114
138
  /**
115
139
  * A floating picture's holder (drawn first in its paragraph, the view's own DOM) to its anchor:
116
140
  * the empty, non-editable span at the picture's place in the text, which positions map to.
141
+ * @internal
117
142
  */
118
143
  export const FLOAT_ANCHORS = new WeakMap<Element, HTMLElement>();
119
144
 
120
145
  /**
121
146
  * Renders the blocks of one v3 document for the editable view. `prepare` runs before each
122
147
  * render: list numbers and comment ranges depend on the blocks before.
148
+ * @internal
123
149
  */
124
150
  export class WordRenderer {
125
151
  #context: WordContext;
@@ -145,6 +171,14 @@ export class WordRenderer {
145
171
  #noteMark = "";
146
172
  /** The numbers each block shows. */
147
173
  #noteKeys: string[] = [];
174
+ /** Node and mark views (`ViewExtension`), none on the clipboard. */
175
+ views: Views | null = null;
176
+ /** Where node views' drawings are recorded, for their `destroy` (the view's list). */
177
+ drawn: Drawn[] | null = null;
178
+ readonly #dom: NodeViewDOM;
179
+ /** Each block's decorations, relative to its content (`decorationsByBlock`), and as keys. */
180
+ #decorations: readonly (readonly Decoration[] | undefined)[] = [];
181
+ #decorationKeys: string[] = [];
148
182
 
149
183
  constructor(
150
184
  context: WordContext,
@@ -158,6 +192,7 @@ export class WordRenderer {
158
192
  this.#codes = codes;
159
193
  this.#context = context;
160
194
  this.#doc = doc;
195
+ this.#dom = nodeViewDOM(doc);
161
196
  this.#ratio = ratio;
162
197
  this.#clipboard = clipboard;
163
198
  this.#review = review;
@@ -173,6 +208,12 @@ export class WordRenderer {
173
208
  this.#context = context;
174
209
  }
175
210
 
211
+ /** Decorations by block index (of those prepared): set before `key` and `render`. */
212
+ set decorations(list: readonly (readonly Decoration[] | undefined)[]) {
213
+ this.#decorations = list;
214
+ this.#decorationKeys = list.map((own) => (own ? JSON.stringify(own) : ""));
215
+ }
216
+
176
217
  /** What notes show: set before `prepare`. */
177
218
  setNotes(references: ReadonlyMap<string, string>, mark = ""): void {
178
219
  this.#notes = references;
@@ -235,7 +276,8 @@ export class WordRenderer {
235
276
  const field = this.#fields[index];
236
277
  const fields = field?.hidden.size || field?.gone ? `|${[...field.hidden]}${field.gone}` : "";
237
278
  const notes = this.#noteKeys[index] ? `|${this.#noteKeys[index]}` : "";
238
- return `${this.#markers[index]?.text ?? ""}|${(this.#comments[index] ?? []).join(" ")}${inCell}${above}${fields}${notes}|${this.#noteMark}`;
279
+ const decorations = this.#decorationKeys[index] ? `|${this.#decorationKeys[index]}` : "";
280
+ return `${this.#markers[index]?.text ?? ""}|${(this.#comments[index] ?? []).join(" ")}${inCell}${above}${fields}${notes}|${this.#noteMark}${decorations}`;
239
281
  }
240
282
 
241
283
  /** A block; `cell` is the format of the table cell it is in, if any. */
@@ -245,7 +287,8 @@ export class WordRenderer {
245
287
  splits: readonly number[] = [],
246
288
  cell?: CellFormat | null,
247
289
  ): WordBlockDesc {
248
- if (node.type.name !== "paragraph") return this.#opaque(node, index);
290
+ const decorations = this.#decorations[index] ?? [];
291
+ if (node.type.name !== "paragraph") return this.#opaque(node, index, splits, !!cell);
249
292
  const { resolver } = this.#context;
250
293
  const { paragraph, run } = resolver.paragraph(node.attrs, cell ?? undefined);
251
294
  const line = (r: RunFormat) => lineHeight(paragraph, r, this.#ratio(fontStack(latin(r))));
@@ -273,6 +316,7 @@ export class WordRenderer {
273
316
  }
274
317
  if (changed && !this.#clipboard) fragment.style.boxShadow = CHANGE_BAR;
275
318
  if (display.gone) fragment.style.display = "none";
319
+ for (const d of decorations) if (d.node && d.from < 0) applyAttrs(fragment, d.attrs);
276
320
  return fragment;
277
321
  });
278
322
  const dom = fragments[0] as HTMLElement;
@@ -295,6 +339,12 @@ export class WordRenderer {
295
339
  const floats = new Map<HTMLElement, HTMLElement[]>();
296
340
  let geometry: FloatGeometry | undefined;
297
341
  const comments = new Set(this.#comments[index] ?? []);
342
+ /** Inline decorations over content `from`..`to`, and node ones on a leaf there. */
343
+ const decorate = (element: HTMLElement, from: number, to: number, leaf: boolean) => {
344
+ for (const d of decorations)
345
+ if (d.node ? leaf && d.from === from : d.from <= from && d.to >= to)
346
+ applyAttrs(element, d.attrs);
347
+ };
298
348
  node.forEach((child, offset, childIndex) => {
299
349
  const name = child.type.name;
300
350
  if (name === "commentStart") comments.add(child.attrs.id as number);
@@ -310,6 +360,7 @@ export class WordRenderer {
310
360
  return span;
311
361
  };
312
362
  const leafElement = (element: HTMLElement) => {
363
+ decorate(element, offset, offset + child.nodeSize, true);
313
364
  leaves.push({ dom: element, offset, size: child.nodeSize });
314
365
  holder(offset).append(this.#wrap(element, child.marks, comments));
315
366
  };
@@ -329,6 +380,7 @@ export class WordRenderer {
329
380
  case "tab": {
330
381
  // A tab is text to the line layout (tab stops) and to the read-back.
331
382
  const span = this.#run(run, child.marks, line);
383
+ decorate(span, offset, offset + 1, true);
332
384
  const tab = doc.createTextNode("\t");
333
385
  span.append(tab);
334
386
  leaves.push({ dom: tab, offset, size: 1 });
@@ -374,6 +426,20 @@ export class WordRenderer {
374
426
  return;
375
427
  }
376
428
  default: {
429
+ const stands = child.type.spec.text;
430
+ if (stands) {
431
+ // A custom or foreign node (ADR-0008): its node view or its text, one position, as
432
+ // opaque content.
433
+ const span = this.#run(run, child.marks, line);
434
+ const view = this.#clipboard ? undefined : this.views?.nodes.get(name);
435
+ const drawn = view && this.#draw(view, child, span);
436
+ if (drawn) span.append(drawn);
437
+ else span.textContent = stands(child.attrs);
438
+ span.dataset.foliCustom = String(child.attrs.type ?? name);
439
+ span.setAttribute("contenteditable", "false");
440
+ leafElement(span);
441
+ return;
442
+ }
377
443
  // A field's code and braces, when codes show: drawn, not document text.
378
444
  const shown =
379
445
  display.braces.get(childIndex) ??
@@ -397,12 +463,19 @@ export class WordRenderer {
397
463
  }
398
464
  }
399
465
  const text = child.text ?? "";
400
- const cuts = splits.filter((split) => split > offset && split < offset + text.length);
466
+ const inside = (at: number) => at > offset && at < offset + text.length;
467
+ const cuts = splits.filter(inside);
468
+ // Inline decorations start and end runs of their own.
469
+ for (const d of decorations)
470
+ if (!d.node)
471
+ for (const at of [d.from, d.to]) if (inside(at) && !cuts.includes(at)) cuts.push(at);
472
+ cuts.sort((a, b) => a - b);
401
473
  let from = offset;
402
474
  for (const to of [...cuts, offset + text.length]) {
403
475
  const leaf = doc.createTextNode(text.slice(from - offset, to - offset));
404
476
  leaves.push({ dom: leaf, offset: from, size: to - from });
405
477
  const span = this.#run(run, child.marks, line);
478
+ decorate(span, from, to, false);
406
479
  span.append(leaf);
407
480
  holder(from).append(this.#wrap(span, child.marks, comments));
408
481
  from = to;
@@ -482,6 +555,20 @@ export class WordRenderer {
482
555
  const run = this.#context.resolver.run(paragraphRun, json);
483
556
  const span = this.#doc.createElement("span");
484
557
  styleRun(span, run, line(run));
558
+ // Custom marks (ADR-0008): named for CSS, styled by their mark views.
559
+ const custom: string[] = [];
560
+ for (const mark of marks) {
561
+ const type = mark.type.name === "foreign" ? String(mark.attrs.type) : mark.type.name;
562
+ if (!type.includes(":")) continue;
563
+ custom.push(type);
564
+ const view = this.views?.marks.get(mark.type.name);
565
+ try {
566
+ if (view) applyAttrs(span, view(mark));
567
+ } catch (error) {
568
+ reportError(error);
569
+ }
570
+ }
571
+ if (custom.length) span.dataset.foliMark = custom.join(" ");
485
572
  return span;
486
573
  }
487
574
 
@@ -516,8 +603,95 @@ export class WordRenderer {
516
603
  return a;
517
604
  }
518
605
 
606
+ /** A node view's drawing of `node` in `box`, recorded; null (reported) when `render` throws. */
607
+ #draw(view: NodeView, node: ModelNode, box: HTMLElement): Node | null {
608
+ try {
609
+ const root = view.render(node, this.#dom);
610
+ this.drawn?.push({ view, root, box });
611
+ return root;
612
+ } catch (error) {
613
+ reportError(error);
614
+ return null;
615
+ }
616
+ }
617
+
618
+ /**
619
+ * A custom block drawn by its node view (ADR-0008): one fragment, or one per page it is split
620
+ * across, each drawing the node again and showing its part (`splits`, layout px) through a clip.
621
+ */
622
+ #nodeView(
623
+ node: ModelNode,
624
+ index: number,
625
+ view: NodeView,
626
+ splits: readonly number[],
627
+ inCell: boolean,
628
+ ): WordBlockDesc {
629
+ const doc = this.#doc;
630
+ const tops = [0, ...splits];
631
+ let root: Node | undefined;
632
+ const fragments = tops.map((top, i) => {
633
+ const box = doc.createElement("div");
634
+ box.dataset.foliCustom = node.type.name;
635
+ box.setAttribute("contenteditable", "false");
636
+ // Its root's margins stay inside it: measured as the flow places it.
637
+ box.style.display = "flow-root";
638
+ const drawn =
639
+ this.#draw(view, node, box) ?? doc.createTextNode(node.type.spec.text?.(node.attrs) ?? "");
640
+ root ??= drawn;
641
+ if (tops.length > 1) {
642
+ box.dataset.fragment = String(i);
643
+ box.style.overflow = "hidden";
644
+ const next = tops[i + 1];
645
+ if (next !== undefined) box.style.height = `${next - top}px`;
646
+ // The parts after the first are drawn again: read once.
647
+ if (i > 0) {
648
+ box.setAttribute("aria-hidden", "true");
649
+ box.setAttribute("inert", "");
650
+ }
651
+ const inner = doc.createElement("div");
652
+ inner.style.marginTop = `${-top}px`;
653
+ inner.append(drawn);
654
+ box.append(inner);
655
+ } else box.append(drawn);
656
+ for (const d of this.#decorations[index] ?? [])
657
+ if (d.node && d.from < 0) applyAttrs(box, d.attrs);
658
+ return box;
659
+ });
660
+ const dom = fragments[0] as HTMLElement;
661
+ // shortcut: a custom block in a table cell is kept whole (cells split at their lines); split it there when a node view needs it.
662
+ const split = view.split !== false && !inCell;
663
+ const parts = () => {
664
+ const { top, height } = dom.getBoundingClientRect();
665
+ const bottoms: number[] = [];
666
+ const children = root?.nodeType === Node.ELEMENT_NODE ? (root as Element).children : [];
667
+ for (const child of children) {
668
+ const bottom = child.getBoundingClientRect().bottom - top;
669
+ if (bottom > (bottoms[bottoms.length - 1] ?? 0) && bottom < height) bottoms.push(bottom);
670
+ }
671
+ bottoms.push(height);
672
+ return bottoms;
673
+ };
674
+ return {
675
+ node,
676
+ dom,
677
+ fragments,
678
+ splits,
679
+ leaves: [],
680
+ key: this.key(index),
681
+ word: leafInfo(!split),
682
+ ...(split ? { parts } : {}),
683
+ };
684
+ }
685
+
519
686
  /** An opaque block, shown from its XML: a block leaf, not editable inside. */
520
- #opaque(node: ModelNode, index: number): WordBlockDesc {
687
+ #opaque(
688
+ node: ModelNode,
689
+ index: number,
690
+ splits: readonly number[],
691
+ inCell: boolean,
692
+ ): WordBlockDesc {
693
+ const view = this.#clipboard ? undefined : this.views?.nodes.get(node.type.name);
694
+ if (view) return this.#nodeView(node, index, view, splits, inCell);
521
695
  const shown = opaqueBlock(
522
696
  node.toJSON(),
523
697
  index,
@@ -529,6 +703,14 @@ export class WordRenderer {
529
703
  );
530
704
  const dom = shown.element;
531
705
  dom.setAttribute("contenteditable", "false");
706
+ const stands = node.type.spec.text;
707
+ if (stands) {
708
+ // A custom or foreign block (ADR-0008): its text in a box.
709
+ dom.textContent = stands(node.attrs);
710
+ dom.dataset.foliCustom = String(node.attrs.type ?? node.type.name);
711
+ }
712
+ for (const d of this.#decorations[index] ?? [])
713
+ if (d.node && d.from < 0) applyAttrs(dom, d.attrs);
532
714
  return {
533
715
  node,
534
716
  dom,
@@ -550,6 +732,20 @@ export class WordRenderer {
550
732
  }
551
733
  }
552
734
 
735
+ /** What the flow needs of a block that is not a paragraph: no spacing, keep rules or breaks. */
736
+ function leafInfo(keepLines: boolean): WordInfo {
737
+ return {
738
+ before: 0,
739
+ after: 0,
740
+ keepNext: false,
741
+ keepLines,
742
+ pageBreakBefore: false,
743
+ style: null,
744
+ contextual: false,
745
+ empty: false,
746
+ };
747
+ }
748
+
553
749
  /** An element's style attribute, ready for one more declaration. */
554
750
  function styleOf(element: Element): string {
555
751
  const style = element.getAttribute("style")?.trim() ?? "";
@@ -560,6 +756,7 @@ function styleOf(element: Element): string {
560
756
  * The HTML of copied v3 blocks `nodes`: drawn as the editor draws them, with their list numbers
561
757
  * in `doc` (from top-level block `first`; -1 for text from inside one paragraph, which takes no
562
758
  * number), without what only the editor needs (comment shading, `contenteditable`).
759
+ * @internal
563
760
  */
564
761
  export function clipboardBlocks(
565
762
  context: WordContext,
@@ -593,6 +790,7 @@ export function clipboardBlocks(
593
790
  * paragraphs of the same style that ask for it (contextual spacing). When only the first asks,
594
791
  * its space after still eats into the second's space before, unless the document adds the two
595
792
  * (`adds`).
793
+ * @internal
596
794
  */
597
795
  export function spacing(
598
796
  above: WordInfo | undefined,
@@ -10,6 +10,7 @@ import { PAGE_FIELD_ATTR } from "./regions.js";
10
10
  const ALL = "foli-find";
11
11
  const CURRENT = "foli-find-current";
12
12
 
13
+ /** @internal */
13
14
  export const MATCH_STYLES =
14
15
  `::highlight(${ALL}){background-color:#ffe17a}` +
15
16
  `::highlight(${CURRENT}){background-color:#f5a04a}` +
@@ -22,7 +23,10 @@ interface HighlightWindow {
22
23
  Highlight?: new () => Set<Range> & { priority: number };
23
24
  }
24
25
 
25
- /** One view's marks; views share the document's two highlights. */
26
+ /**
27
+ * One view's marks; views share the document's two highlights.
28
+ * @internal
29
+ */
26
30
  export class MatchMarks {
27
31
  private all: Range[] = [];
28
32
  private current: Range[] = [];
@@ -58,6 +62,7 @@ export class MatchMarks {
58
62
  /**
59
63
  * Where `query` is in drawn copies of a story (read-only, with their pages' numbers filled in):
60
64
  * looked for in each paragraph's text, as the text shown there has no positions.
65
+ * @internal
61
66
  */
62
67
  export function rangesInText(root: Element, query: string, options: FindOptions): Range[] {
63
68
  const doc = root.ownerDocument;
package/src/word/notes.ts CHANGED
@@ -6,20 +6,25 @@
6
6
  import {
7
7
  type FoliDocument,
8
8
  type NoteNumber,
9
- noteKindOf,
10
9
  noteProperties,
11
- type Resolver,
12
10
  type SectionJSON,
13
11
  type StoryJSON,
14
12
  } from "@folijs/core";
13
+ import { noteKindOf, type Resolver } from "@folijs/core/internal";
15
14
  import { arrangeNotes, type FlowNote, type FlowRules, type NotePiece } from "../layout/flow.js";
16
15
  import { type BlockOptions, renderBlocks } from "./blocks.js";
17
16
  import { columnsPx } from "./columns.js";
18
17
  import { REGION_CLASS, REGION_CONTENT_CLASS, type RegionOptions, stack } from "./regions.js";
19
18
 
20
- /** On a piece of a note drawn on a page: the story. */
19
+ /**
20
+ * On a piece of a note drawn on a page: the story.
21
+ * @internal
22
+ */
21
23
  export const NOTE_ATTR = "data-foli-note";
22
- /** The class of what holds a column's notes. */
24
+ /**
25
+ * The class of what holds a column's notes.
26
+ * @internal
27
+ */
23
28
  export const NOTES_CLASS = "foli-notes";
24
29
 
25
30
  /**
@@ -29,6 +34,7 @@ export const NOTES_CLASS = "foli-notes";
29
34
  *
30
35
  * shortcut: line boxes are inferred from content rects (exact for even line heights); a
31
36
  * superscript or a much larger run on a line moves that line's boundaries slightly.
37
+ * @internal
32
38
  */
33
39
  export function lineBottoms(element: HTMLElement): number[] {
34
40
  const box = element.getBoundingClientRect();
@@ -115,11 +121,15 @@ interface Drawn {
115
121
  lines: number[];
116
122
  }
117
123
 
124
+ /** @internal */
118
125
  export type NoteCache = WeakMap<StoryJSON, Map<string, Drawn>>;
119
126
 
120
127
  let serial = 0;
121
128
 
122
- /** The notes at a band's foot, or after the text of one of its columns. */
129
+ /**
130
+ * The notes at a band's foot, or after the text of one of its columns.
131
+ * @internal
132
+ */
123
133
  export interface NoteGroup {
124
134
  page: number;
125
135
  band: number;
@@ -132,7 +142,10 @@ export interface NoteGroup {
132
142
  section: number;
133
143
  }
134
144
 
135
- /** What a document's pages need to know of its notes. */
145
+ /**
146
+ * What a document's pages need to know of its notes.
147
+ * @internal
148
+ */
136
149
  export class PageNotes {
137
150
  private document: Omit<FoliDocument, "content"> | null = null;
138
151
  private sections: readonly SectionJSON[] = [];
package/src/word/pages.ts CHANGED
@@ -11,9 +11,11 @@ import {
11
11
  noteProperties,
12
12
  noteTexts,
13
13
  parseContent,
14
- Resolver,
14
+ type ResourceJSON,
15
+ type ReviewView,
15
16
  type SectionJSON,
16
17
  } from "@folijs/core";
18
+ import { Resolver } from "@folijs/core/internal";
17
19
  import {
18
20
  type BlockBox,
19
21
  type FlowNote,
@@ -40,7 +42,6 @@ import { lineBottoms, type NoteGroup, PageNotes } from "./notes.js";
40
42
  import { PageRegions } from "./regions.js";
41
43
 
42
44
  export type { ReviewView } from "./blocks.js";
43
- export { lineBottoms };
44
45
 
45
46
  /** The class of each page element. */
46
47
  export const WORD_PAGE_CLASS = "foli-word-page";
@@ -135,6 +136,7 @@ function createPage(doc: Document, g: Geometry): { page: HTMLElement; body: HTML
135
136
  /**
136
137
  * The ratio of a font's normal line height to its size, measured: a line of 100 px text with
137
138
  * `line-height: normal` (the font's own ascent, descent and gap, as Word's single spacing).
139
+ * @internal
138
140
  */
139
141
  export function measureLineRatio(container: HTMLElement): (family: string) => number {
140
142
  return (family) => {
@@ -204,6 +206,20 @@ interface Section {
204
206
  column: HTMLElement;
205
207
  }
206
208
 
209
+ /** `renderDocument`'s options. */
210
+ export interface RenderDocumentOptions {
211
+ /** `markup` (the default): insertions underlined, deletions struck through; `simple`, `final`: as if accepted. */
212
+ review?: ReviewView;
213
+ /** Fields show their codes instead of their results (Word's Alt+F9). */
214
+ fieldCodes?: boolean;
215
+ /**
216
+ * The URL to show a picture's image from (`key` in `resources`): the app's (a package part's
217
+ * object URL…); `null` (or "") shows the picture's box. Left out, or undefined for a key: the
218
+ * resource's own image `data:` URL or web URL (fetched as it is shown).
219
+ */
220
+ resource?: (key: string, resource: ResourceJSON) => string | null | undefined;
221
+ }
222
+
207
223
  /**
208
224
  * Lays a v3 document out on pages inside `container`: every section's page setup, its columns
209
225
  * (a band per section on a page), continuous sections, Word's blank pages, headers and footers
@@ -212,7 +228,7 @@ interface Section {
212
228
  export function renderDocument(
213
229
  document: FoliDocument,
214
230
  container: HTMLElement,
215
- options: Omit<BlockOptions, "lineRatio"> = {},
231
+ options: RenderDocumentOptions = {},
216
232
  ): DocumentPages {
217
233
  const doc = container.ownerDocument;
218
234
  // What notes show: numbers depend on the pages only where they restart on each.
@@ -6,29 +6,38 @@
6
6
  */
7
7
  import {
8
8
  type FoliDocument,
9
- formatNumber,
10
9
  type NodeJSON,
11
10
  pageVariant,
12
- type Resolver,
13
11
  type SectionJSON,
14
12
  type StoryJSON,
15
13
  type StorySide,
16
14
  storyOfSection,
17
15
  } from "@folijs/core";
16
+ import { formatNumber, type Resolver } from "@folijs/core/internal";
18
17
  import type { FlowPage, PageFacts } from "../layout/flow.js";
19
18
  import { type BlockOptions, PX_PER_TWIP, renderBlocks, type WordBlock } from "./blocks.js";
20
19
 
21
- /** On what shows a page field's number in a drawn copy of a story. */
20
+ /**
21
+ * On what shows a page field's number in a drawn copy of a story.
22
+ * @internal
23
+ */
22
24
  export const PAGE_FIELD_ATTR = "data-foli-page-field";
23
25
 
24
- /** The class of a page's header or footer element. */
26
+ /**
27
+ * The class of a page's header or footer element.
28
+ * @internal
29
+ */
25
30
  export const REGION_CLASS = "foli-region";
31
+ /** @internal */
26
32
  export const REGION_CONTENT_CLASS = "foli-region-content";
27
33
 
28
34
  /** Word's distance from the page's edge when a section does not give one: half an inch. */
29
35
  const EDGE = 720;
30
36
 
31
- /** What the page fields of a page show. */
37
+ /**
38
+ * What the page fields of a page show.
39
+ * @internal
40
+ */
32
41
  export interface FieldValues {
33
42
  page: string;
34
43
  pages: string;
@@ -160,7 +169,10 @@ interface StoryDrawing {
160
169
  heights: Map<string, number>;
161
170
  }
162
171
 
163
- /** Per story (an object replaced when the story changes), what was measured and drawn of it. */
172
+ /**
173
+ * Per story (an object replaced when the story changes), what was measured and drawn of it.
174
+ * @internal
175
+ */
164
176
  export type RegionCache = WeakMap<StoryJSON, StoryDrawing>;
165
177
 
166
178
  /** A section's page as the regions need it, in CSS px. */
@@ -199,7 +211,10 @@ function edgesOf(section: SectionJSON): Edges {
199
211
  };
200
212
  }
201
213
 
202
- /** Lays `blocks` out as a story: spacing as between the paragraphs of a page. */
214
+ /**
215
+ * Lays `blocks` out as a story: spacing as between the paragraphs of a page.
216
+ * @internal
217
+ */
203
218
  export function stack(blocks: readonly WordBlock[], parent: HTMLElement, adds: boolean): number {
204
219
  let previous = 0;
205
220
  blocks.forEach((block, i) => {
@@ -216,6 +231,7 @@ export function stack(blocks: readonly WordBlock[], parent: HTMLElement, adds: b
216
231
  return previous;
217
232
  }
218
233
 
234
+ /** @internal */
219
235
  export interface RegionOptions extends Omit<BlockOptions, "resolver"> {
220
236
  /** Where stories are measured (hidden, for a moment). */
221
237
  measureIn(): HTMLElement;
@@ -223,7 +239,10 @@ export interface RegionOptions extends Omit<BlockOptions, "resolver"> {
223
239
  scale?(): number;
224
240
  }
225
241
 
226
- /** What the layout of a document's pages needs to know of their headers and footers. */
242
+ /**
243
+ * What the layout of a document's pages needs to know of their headers and footers.
244
+ * @internal
245
+ */
227
246
  export class PageRegions {
228
247
  /** The page count and each section's, as of the last flow (the fields' values). */
229
248
  private pages = 1;