Skip to content

Commit 3c13b5c

Browse files
committed
refactor(@m2d/image-node): ♻️ share fallback logic with image
1 parent 730ee36 commit 3c13b5c

7 files changed

Lines changed: 34 additions & 119 deletions

File tree

‎.changeset/share-image-fallback.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"@m2d/image": minor
3+
"@m2d/image-node": patch
4+
---
5+
6+
Export `@m2d/image/fallback` subpath and share fallback run generation across `@m2d/image` and `@m2d/image-node`.

‎packages/image-node/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
},
4444
"dependencies": {
4545
"@m2d/core": "workspace:*",
46+
"@m2d/image": "workspace:*",
4647
"sharp": "^0.35.5"
4748
},
4849
"peerDependencies": {
Lines changed: 1 addition & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1 @@
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";

‎packages/image/package.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,26 @@
2323
"default": "./dist/index.js"
2424
}
2525
},
26+
"./fallback": {
27+
"import": {
28+
"types": "./dist/fallback.d.mts",
29+
"default": "./dist/fallback.mjs"
30+
},
31+
"require": {
32+
"types": "./dist/fallback.d.ts",
33+
"default": "./dist/fallback.js"
34+
}
35+
},
36+
"./dist/fallback": {
37+
"import": {
38+
"types": "./dist/fallback.d.mts",
39+
"default": "./dist/fallback.mjs"
40+
},
41+
"require": {
42+
"types": "./dist/fallback.d.ts",
43+
"default": "./dist/fallback.js"
44+
}
45+
},
2646
"./package.json": "./package.json"
2747
},
2848
"repository": {

‎packages/image/src/fallback.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ export interface IImageErrorOptions {
4242
placeholder?: string;
4343
}
4444

45+
export type INodeImageErrorOptions = IImageErrorOptions;
46+
4547
/**
4648
* Generates fallback docx runs for failed image or diagram resolution.
4749
*/

‎packages/image/tsup.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ export default defineConfig(
77
target: "es2022",
88
tsconfig: "../../tsconfig.build.json",
99
dts: true,
10-
entry: ["./src/index.ts"],
10+
entry: ["./src/index.ts", "./src/fallback.ts"],
1111
sourcemap: false,
1212
clean: !options.watch,
1313
bundle: true,

‎pnpm-lock.yaml‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)