|
1 | | -import type * as docx from "docx"; |
2 | | - |
3 | | -export type ImageErrorMode = "warn" | "silent" | "throw" | "placeholder"; |
4 | | -export type MermaidFallbackMode = "code" | "warn" | "silent"; |
5 | | -export type SvgFallbackMode = "warn" | "code" | "silent"; |
6 | | - |
7 | | -export interface INodeImageErrorOptions { |
8 | | - /** |
9 | | - * General image error behavior. |
10 | | - * - "warn": Emits a styled, muted text run with alt text. |
11 | | - * - "silent": Drops the node completely (0 relationships, 0 XML overhead). |
12 | | - * - "throw": Rejects the toDocx conversion promise with the underlying Error. |
13 | | - * - "placeholder": Uses custom options.placeholder image. If placeholder is omitted, emits a warning badge. |
14 | | - * @default "warn" |
15 | | - */ |
16 | | - errorMode?: ImageErrorMode; |
17 | | - /** |
18 | | - * Fallback strategy specifically for failed Mermaid diagrams (when data.mermaid is present). |
19 | | - * - "code": Renders the raw Mermaid diagram definition as a formatted monospace code block. |
20 | | - * - "warn": Emits a warning badge [Mermaid Diagram Error: ...]. |
21 | | - * - "silent": Drops the node completely. |
22 | | - * @default "code" (or inherits "silent" if errorMode is "silent") |
23 | | - */ |
24 | | - mermaidFallback?: MermaidFallbackMode; |
25 | | - /** |
26 | | - * Fallback strategy for failed non-Mermaid SVGs. |
27 | | - * - "warn": Emits styled muted text badge `[Image: <alt or 'SVG unavailable'>]`. |
28 | | - * - "code": Renders the raw SVG XML markup in a standard DOCX code block (`lang: "xml"`). |
29 | | - * - "silent": Drops the node completely. |
30 | | - * @default "warn" |
31 | | - */ |
32 | | - svgFallback?: SvgFallbackMode; |
33 | | - /** |
34 | | - * Optional heading added above fallback code blocks (H6 level, maps to Heading 5 in Word). |
35 | | - * - `false`: No heading is inserted (only the code block). |
36 | | - * - `true`: Inserts an H6 heading (`###### ⚠️ Diagram Source (Render Fallback)`). |
37 | | - * - `string`: Inserts custom heading text at H6 level. |
38 | | - * @default true |
39 | | - */ |
40 | | - collapsibleHeading?: boolean | string; |
41 | | - /** Custom placeholder image source (path, URL, or data URL) */ |
42 | | - placeholder?: string; |
43 | | -} |
44 | | - |
45 | | -/** |
46 | | - * Generates fallback docx runs for failed image or diagram resolution in Node.js. |
47 | | - */ |
48 | | -export const createFallbackRuns = ( |
49 | | - docxModule: typeof docx, |
50 | | - data: Record<string, unknown>, |
51 | | - options?: INodeImageErrorOptions, |
52 | | - runProps?: Record<string, unknown>, |
53 | | -): docx.TextRun[] => { |
54 | | - const errorMode = options?.errorMode ?? "warn"; |
55 | | - const mermaidFallback = |
56 | | - options?.mermaidFallback ?? (errorMode === "silent" ? "silent" : "code"); |
57 | | - |
58 | | - if (data?.mermaid) { |
59 | | - if (mermaidFallback === "silent") { |
60 | | - return []; |
61 | | - } |
62 | | - if (mermaidFallback === "code") { |
63 | | - const lines = String(data.mermaid).split("\n"); |
64 | | - const runs: docx.TextRun[] = []; |
65 | | - lines.forEach((line: string, index: number) => { |
66 | | - runs.push( |
67 | | - new docxModule.TextRun({ |
68 | | - text: line, |
69 | | - font: "Consolas", |
70 | | - size: 19, |
71 | | - color: "24292F", |
72 | | - ...runProps, |
73 | | - break: index > 0 ? 1 : 0, |
74 | | - }), |
75 | | - ); |
76 | | - }); |
77 | | - return runs; |
78 | | - } |
79 | | - const errorObj = data.error as Error | undefined; |
80 | | - const msg = errorObj?.message ?? "render failed"; |
81 | | - return [ |
82 | | - new docxModule.TextRun({ |
83 | | - text: `⚠️ [Mermaid Diagram Error: ${msg}]`, |
84 | | - italics: true, |
85 | | - color: "C00000", |
86 | | - ...runProps, |
87 | | - }), |
88 | | - ]; |
89 | | - } |
90 | | - |
91 | | - if (errorMode === "silent") { |
92 | | - return []; |
93 | | - } |
94 | | - |
95 | | - if (data?.errorReason === "placeholder-not-configured") { |
96 | | - const altText = data.altText as { name?: string } | undefined; |
97 | | - const label = altText?.name || "Image"; |
98 | | - return [ |
99 | | - new docxModule.TextRun({ |
100 | | - text: `⚠️ [${label} Error: placeholder not configured]`, |
101 | | - italics: true, |
102 | | - color: "C00000", |
103 | | - ...runProps, |
104 | | - }), |
105 | | - ]; |
106 | | - } |
107 | | - |
108 | | - const altText = data.altText as { name?: string } | undefined; |
109 | | - const alt = altText?.name; |
110 | | - return [ |
111 | | - new docxModule.TextRun({ |
112 | | - text: alt ? `[Image: ${alt}]` : "[Image unavailable]", |
113 | | - italics: true, |
114 | | - color: "71717A", |
115 | | - ...runProps, |
116 | | - }), |
117 | | - ]; |
118 | | -}; |
| 1 | +export * from "@m2d/image/fallback"; |
0 commit comments