markdown-pdf-export 0.0.0-stage → 2.0.1

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.
@@ -0,0 +1,837 @@
1
+ /**
2
+ * @fileoverview HTML generator for structured header/footer configuration.
3
+ *
4
+ * This module converts declarative header/footer configurations into
5
+ * HTML templates suitable for Playwright's PDF generation.
6
+ *
7
+ * Key responsibilities:
8
+ * - Convert element definitions to HTML
9
+ * - Handle shorthand property expansion
10
+ * - Generate flexbox-based layout for zones (left, center, right)
11
+ * - Integrate with asset resolver for images
12
+ * - Integrate with placeholder resolver for dynamic content
13
+ *
14
+ * @module html-generator
15
+ */
16
+
17
+ import { SHORTHAND_MAPPINGS } from "./types.mjs";
18
+
19
+ // ─────────────────────────────────────────────────────────────────────────────
20
+ // Constants
21
+ // ─────────────────────────────────────────────────────────────────────────────
22
+
23
+ /**
24
+ * Default styles for header/footer container.
25
+ * @type {Readonly<Object.<string, string>>}
26
+ */
27
+ const DEFAULT_CONTAINER_STYLES = Object.freeze({
28
+ display: "flex",
29
+ "justify-content": "space-between",
30
+ "align-items": "center",
31
+ width: "100%",
32
+ "box-sizing": "border-box",
33
+ padding: "0 10mm",
34
+ "font-size": "10px",
35
+ "font-family": "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
36
+ });
37
+
38
+ /**
39
+ * Default styles for zone containers.
40
+ * @type {Readonly<Object.<string, string>>}
41
+ */
42
+ const DEFAULT_ZONE_STYLES = Object.freeze({
43
+ display: "flex",
44
+ "align-items": "center",
45
+ "flex-shrink": "0",
46
+ gap: "4px",
47
+ });
48
+
49
+ /**
50
+ * Zone alignment mapping.
51
+ * @type {Readonly<Object.<string, string>>}
52
+ */
53
+ const ZONE_ALIGNMENT = Object.freeze({
54
+ left: "flex-start",
55
+ center: "center",
56
+ right: "flex-end",
57
+ });
58
+
59
+ // ─────────────────────────────────────────────────────────────────────────────
60
+ // Style Utilities
61
+ // ─────────────────────────────────────────────────────────────────────────────
62
+
63
+ /**
64
+ * Convert a style object to inline CSS string.
65
+ *
66
+ * @param {Object.<string, string|number>} styles - Style object
67
+ * @returns {string} Inline CSS string
68
+ */
69
+ function stylesToString(styles) {
70
+ return Object.entries(styles)
71
+ .filter(([, value]) => value !== undefined && value !== null && value !== "")
72
+ .map(([key, value]) => `${key}:${value}`)
73
+ .join(";");
74
+ }
75
+
76
+ /**
77
+ * Parse a custom style string into a style object.
78
+ *
79
+ * @param {string} styleStr - CSS style string, e.g., "color: red; font-size: 12px"
80
+ * @returns {Object.<string, string>} Style object
81
+ */
82
+ function parseStyleString(styleStr) {
83
+ if (!styleStr || typeof styleStr !== "string") {
84
+ return {};
85
+ }
86
+
87
+ const result = {};
88
+ const declarations = styleStr.split(";").map((s) => s.trim()).filter(Boolean);
89
+
90
+ for (const declaration of declarations) {
91
+ const colonIndex = declaration.indexOf(":");
92
+ if (colonIndex > 0) {
93
+ const property = declaration.slice(0, colonIndex).trim();
94
+ const value = declaration.slice(colonIndex + 1).trim();
95
+ if (property && value) {
96
+ result[property] = value;
97
+ }
98
+ }
99
+ }
100
+
101
+ return result;
102
+ }
103
+
104
+ /**
105
+ * Build element styles from element properties.
106
+ *
107
+ * @param {Object} element - Element with style properties
108
+ * @returns {Object.<string, string>} Style object
109
+ */
110
+ function buildElementStyles(element) {
111
+ const styles = {};
112
+
113
+ if (element.font_size) {
114
+ styles["font-size"] = element.font_size;
115
+ }
116
+
117
+ if (element.font_weight) {
118
+ styles["font-weight"] = String(element.font_weight);
119
+ }
120
+
121
+ if (element.font_style) {
122
+ styles["font-style"] = element.font_style;
123
+ }
124
+
125
+ if (element.color) {
126
+ styles.color = element.color;
127
+ }
128
+
129
+ // Parse and merge custom style string
130
+ if (element.style) {
131
+ Object.assign(styles, parseStyleString(element.style));
132
+ }
133
+
134
+ return styles;
135
+ }
136
+
137
+ // ─────────────────────────────────────────────────────────────────────────────
138
+ // HTML Escaping
139
+ // ─────────────────────────────────────────────────────────────────────────────
140
+
141
+ /**
142
+ * Escape HTML special characters.
143
+ *
144
+ * @param {string} text - Text to escape
145
+ * @returns {string} Escaped text
146
+ */
147
+ function escapeHtml(text) {
148
+ if (typeof text !== "string") {
149
+ return "";
150
+ }
151
+
152
+ return text
153
+ .replace(/&/g, "&amp;")
154
+ .replace(/</g, "&lt;")
155
+ .replace(/>/g, "&gt;")
156
+ .replace(/"/g, "&quot;")
157
+ .replace(/'/g, "&#39;");
158
+ }
159
+
160
+ // ─────────────────────────────────────────────────────────────────────────────
161
+ // Element Generators
162
+ // ─────────────────────────────────────────────────────────────────────────────
163
+
164
+ /**
165
+ * @typedef {Object} GeneratorContext
166
+ * @property {(imagePath: string) => Promise<string>} resolveAsset - Resolve image to data URI
167
+ * @property {(text: string) => string} resolvePlaceholders - Resolve placeholders in text
168
+ * @property {string} [fontFamily] - Default font family
169
+ */
170
+
171
+ /**
172
+ * Generate HTML for a text element.
173
+ *
174
+ * @param {import('./types.mjs').TextElement} element - Text element
175
+ * @param {GeneratorContext} context - Generator context
176
+ * @returns {string} HTML string
177
+ */
178
+ function generateTextElement(element, context) {
179
+ const styles = buildElementStyles(element);
180
+ const styleStr = stylesToString(styles);
181
+
182
+ // Resolve placeholders in content
183
+ let content = context.resolvePlaceholders(element.content || "");
184
+
185
+ const styleAttr = styleStr ? ` style="${escapeHtml(styleStr)}"` : "";
186
+ return `<span${styleAttr}>${content}</span>`;
187
+ }
188
+
189
+ /**
190
+ * Generate HTML for an image element.
191
+ *
192
+ * @param {import('./types.mjs').ImageElement} element - Image element
193
+ * @param {GeneratorContext} context - Generator context
194
+ * @param {string} dataUri - Resolved data URI for the image
195
+ * @returns {string} HTML string
196
+ */
197
+ function generateImageElement(element, context, dataUri) {
198
+ const styles = {};
199
+
200
+ if (element.height) {
201
+ styles.height = element.height;
202
+ }
203
+
204
+ if (element.width) {
205
+ styles.width = element.width;
206
+ }
207
+
208
+ // Parse and merge custom style string
209
+ if (element.style) {
210
+ Object.assign(styles, parseStyleString(element.style));
211
+ }
212
+
213
+ const styleStr = stylesToString(styles);
214
+ const alt = element.alt ? ` alt="${escapeHtml(element.alt)}"` : ' alt=""';
215
+ const styleAttr = styleStr ? ` style="${escapeHtml(styleStr)}"` : "";
216
+
217
+ // Use height attribute for legacy compatibility, style for CSS
218
+ const heightAttr = element.height ? ` height="${escapeHtml(element.height.replace(/[^0-9]/g, ''))}"` : "";
219
+
220
+ return `<img src="${dataUri}"${alt}${heightAttr}${styleAttr}>`;
221
+ }
222
+
223
+ /**
224
+ * Generate HTML for a page_number element.
225
+ *
226
+ * @param {import('./types.mjs').PageNumberElement} element - Page number element
227
+ * @param {GeneratorContext} context - Generator context
228
+ * @returns {string} HTML string
229
+ */
230
+ function generatePageNumberElement(element, context) {
231
+ const styles = buildElementStyles(element);
232
+ const styleStr = stylesToString(styles);
233
+ const styleAttr = styleStr ? ` style="${escapeHtml(styleStr)}"` : "";
234
+
235
+ if (element.format) {
236
+ // Format string with {page} placeholder
237
+ const content = context.resolvePlaceholders(element.format);
238
+ return `<span${styleAttr}>${content}</span>`;
239
+ }
240
+
241
+ // Just the page number
242
+ return `<span class="pageNumber"${styleAttr}></span>`;
243
+ }
244
+
245
+ /**
246
+ * Generate HTML for a total_pages element.
247
+ *
248
+ * @param {import('./types.mjs').TotalPagesElement} element - Total pages element
249
+ * @param {GeneratorContext} context - Generator context
250
+ * @returns {string} HTML string
251
+ */
252
+ function generateTotalPagesElement(element, context) {
253
+ const styles = buildElementStyles(element);
254
+ const styleStr = stylesToString(styles);
255
+ const styleAttr = styleStr ? ` style="${escapeHtml(styleStr)}"` : "";
256
+
257
+ if (element.format) {
258
+ // Format string with {pages} placeholder
259
+ const content = context.resolvePlaceholders(element.format);
260
+ return `<span${styleAttr}>${content}</span>`;
261
+ }
262
+
263
+ // Just the total pages
264
+ return `<span class="totalPages"${styleAttr}></span>`;
265
+ }
266
+
267
+ /**
268
+ * Generate HTML for a date element.
269
+ *
270
+ * @param {import('./types.mjs').DateElement} element - Date element
271
+ * @param {GeneratorContext} context - Generator context
272
+ * @returns {string} HTML string
273
+ */
274
+ function generateDateElement(element, context) {
275
+ const styles = buildElementStyles(element);
276
+ const styleStr = stylesToString(styles);
277
+ const styleAttr = styleStr ? ` style="${escapeHtml(styleStr)}"` : "";
278
+
279
+ // Build placeholder with format if specified
280
+ const placeholder = element.format ? `{date:${element.format}}` : "{date}";
281
+ const content = context.resolvePlaceholders(placeholder);
282
+
283
+ return `<span${styleAttr}>${escapeHtml(content)}</span>`;
284
+ }
285
+
286
+ /**
287
+ * Generate HTML for a title element.
288
+ *
289
+ * @param {import('./types.mjs').TitleElement} element - Title element
290
+ * @param {GeneratorContext} context - Generator context
291
+ * @returns {string} HTML string
292
+ */
293
+ function generateTitleElement(element, context) {
294
+ const styles = buildElementStyles(element);
295
+ const styleStr = stylesToString(styles);
296
+ const styleAttr = styleStr ? ` style="${escapeHtml(styleStr)}"` : "";
297
+
298
+ // Resolve {title} placeholder
299
+ let content = context.resolvePlaceholders("{title}");
300
+
301
+ // Use fallback if title is empty
302
+ if (!content && element.fallback) {
303
+ content = escapeHtml(element.fallback);
304
+ }
305
+
306
+ return `<span${styleAttr}>${content}</span>`;
307
+ }
308
+
309
+ /**
310
+ * Generate HTML for a spacer element.
311
+ *
312
+ * @param {import('./types.mjs').SpacerElement} element - Spacer element
313
+ * @returns {string} HTML string
314
+ */
315
+ function generateSpacerElement(element) {
316
+ const styles = {};
317
+
318
+ if (element.width) {
319
+ styles.width = element.width;
320
+ styles["flex-shrink"] = "0";
321
+ } else {
322
+ // Flexible spacer
323
+ styles.flex = "1";
324
+ }
325
+
326
+ const styleStr = stylesToString(styles);
327
+ return `<span style="${escapeHtml(styleStr)}"></span>`;
328
+ }
329
+
330
+ /**
331
+ * Generate HTML for a single element.
332
+ *
333
+ * @param {import('./types.mjs').Element} element - Element definition
334
+ * @param {GeneratorContext} context - Generator context
335
+ * @param {Map<string, string>} resolvedAssets - Pre-resolved asset map
336
+ * @returns {string} HTML string
337
+ */
338
+ function generateElement(element, context, resolvedAssets) {
339
+ switch (element.type) {
340
+ case "text":
341
+ return generateTextElement(element, context);
342
+
343
+ case "image": {
344
+ const dataUri = resolvedAssets.get(element.src) || element.src;
345
+ return generateImageElement(element, context, dataUri);
346
+ }
347
+
348
+ case "page_number":
349
+ return generatePageNumberElement(element, context);
350
+
351
+ case "total_pages":
352
+ return generateTotalPagesElement(element, context);
353
+
354
+ case "date":
355
+ return generateDateElement(element, context);
356
+
357
+ case "title":
358
+ return generateTitleElement(element, context);
359
+
360
+ case "spacer":
361
+ return generateSpacerElement(element);
362
+
363
+ default:
364
+ // Unknown element type - return empty
365
+ console.warn(`Unknown element type: ${element.type}`);
366
+ return "";
367
+ }
368
+ }
369
+
370
+ // ─────────────────────────────────────────────────────────────────────────────
371
+ // Shorthand Expansion
372
+ // ─────────────────────────────────────────────────────────────────────────────
373
+
374
+ /**
375
+ * Expand shorthand properties into full element definitions.
376
+ *
377
+ * @param {import('./types.mjs').HeaderFooterConfig} config - Config with possible shorthands
378
+ * @returns {import('./types.mjs').HeaderFooterConfig} Config with shorthands expanded
379
+ */
380
+ export function expandShorthands(config) {
381
+ if (!config || typeof config !== "object") {
382
+ return config;
383
+ }
384
+
385
+ const result = { ...config };
386
+
387
+ // Group shorthands by zone
388
+ const zoneElements = {
389
+ left: null,
390
+ center: null,
391
+ right: null,
392
+ };
393
+
394
+ // Process each shorthand
395
+ for (const [shorthand, mapping] of Object.entries(SHORTHAND_MAPPINGS)) {
396
+ if (config[shorthand] !== undefined) {
397
+ const { zone, type, property } = mapping;
398
+
399
+ // Skip if zone is already explicitly defined
400
+ if (config[zone] !== undefined) {
401
+ continue;
402
+ }
403
+
404
+ // Initialize or get existing element for this zone
405
+ if (!zoneElements[zone]) {
406
+ zoneElements[zone] = { type };
407
+ }
408
+
409
+ // Set the property
410
+ if (property === "content") {
411
+ zoneElements[zone].content = config[shorthand];
412
+ } else if (property === "src") {
413
+ zoneElements[zone].src = config[shorthand];
414
+ } else if (property === "height") {
415
+ zoneElements[zone].height = config[shorthand];
416
+ }
417
+
418
+ // Remove shorthand from result
419
+ delete result[shorthand];
420
+ }
421
+ }
422
+
423
+ // Apply expanded zones
424
+ for (const [zone, element] of Object.entries(zoneElements)) {
425
+ if (element && !result[zone]) {
426
+ result[zone] = element;
427
+ }
428
+ }
429
+
430
+ return result;
431
+ }
432
+
433
+ // ─────────────────────────────────────────────────────────────────────────────
434
+ // Zone Generation
435
+ // ─────────────────────────────────────────────────────────────────────────────
436
+
437
+ /**
438
+ * Normalize zone content to an array of elements.
439
+ *
440
+ * @param {import('./types.mjs').Zone} zone - Zone content
441
+ * @returns {import('./types.mjs').Element[]} Array of elements
442
+ */
443
+ function normalizeZone(zone) {
444
+ if (!zone) {
445
+ return [];
446
+ }
447
+
448
+ if (Array.isArray(zone)) {
449
+ return zone;
450
+ }
451
+
452
+ // Single element
453
+ return [zone];
454
+ }
455
+
456
+ /**
457
+ * Generate HTML for a zone (left, center, or right).
458
+ *
459
+ * @param {import('./types.mjs').Zone} zone - Zone content
460
+ * @param {string} zoneName - Zone name ('left', 'center', 'right')
461
+ * @param {GeneratorContext} context - Generator context
462
+ * @param {Map<string, string>} resolvedAssets - Pre-resolved assets
463
+ * @returns {string} HTML string
464
+ */
465
+ function generateZone(zone, zoneName, context, resolvedAssets) {
466
+ const elements = normalizeZone(zone);
467
+
468
+ if (elements.length === 0) {
469
+ // Empty zone - still render container for layout
470
+ return "";
471
+ }
472
+
473
+ const styles = {
474
+ ...DEFAULT_ZONE_STYLES,
475
+ "justify-content": ZONE_ALIGNMENT[zoneName] || "flex-start",
476
+ };
477
+
478
+ // Center zone should be centered in available space
479
+ if (zoneName === "center") {
480
+ styles.flex = "1";
481
+ styles["justify-content"] = "center";
482
+ }
483
+
484
+ const styleStr = stylesToString(styles);
485
+ const elementsHtml = elements
486
+ .map((el) => generateElement(el, context, resolvedAssets))
487
+ .join("");
488
+
489
+ return `<div style="${escapeHtml(styleStr)}">${elementsHtml}</div>`;
490
+ }
491
+
492
+ // ─────────────────────────────────────────────────────────────────────────────
493
+ // Asset Collection
494
+ // ─────────────────────────────────────────────────────────────────────────────
495
+
496
+ /**
497
+ * Collect all image paths from a configuration.
498
+ *
499
+ * @param {import('./types.mjs').HeaderFooterConfig} config - Header/footer config
500
+ * @returns {string[]} Array of image paths
501
+ */
502
+ export function collectImagePaths(config) {
503
+ if (!config || typeof config !== "object") {
504
+ return [];
505
+ }
506
+
507
+ const expanded = expandShorthands(config);
508
+ const paths = [];
509
+
510
+ for (const zoneName of ["left", "center", "right"]) {
511
+ const zone = expanded[zoneName];
512
+ if (!zone) continue;
513
+
514
+ const elements = normalizeZone(zone);
515
+ for (const element of elements) {
516
+ if (element.type === "image" && element.src) {
517
+ paths.push(element.src);
518
+ }
519
+ }
520
+ }
521
+
522
+ return paths;
523
+ }
524
+
525
+ // ─────────────────────────────────────────────────────────────────────────────
526
+ // Main HTML Generator
527
+ // ─────────────────────────────────────────────────────────────────────────────
528
+
529
+ /**
530
+ * @typedef {Object} GenerateHtmlOptions
531
+ * @property {import('./types.mjs').HeaderFooterConfig} config - Header/footer configuration
532
+ * @property {'header'|'footer'} type - Whether this is header or footer
533
+ * @property {(text: string) => string} resolvePlaceholders - Placeholder resolver function
534
+ * @property {Map<string, string>} [resolvedAssets] - Pre-resolved image assets (path -> dataUri)
535
+ * @property {string} [fontFamily] - Global font family override
536
+ */
537
+
538
+ /**
539
+ * Generate HTML template from structured configuration.
540
+ *
541
+ * @param {GenerateHtmlOptions} options - Generation options
542
+ * @returns {string} HTML template string
543
+ */
544
+ export function generateHtml(options) {
545
+ const {
546
+ config,
547
+ type = "header",
548
+ resolvePlaceholders,
549
+ resolvedAssets = new Map(),
550
+ fontFamily,
551
+ } = options;
552
+
553
+ if (!config || typeof config !== "object") {
554
+ return "";
555
+ }
556
+
557
+ // Expand shorthands
558
+ const expanded = expandShorthands(config);
559
+
560
+ // Build context
561
+ const context = {
562
+ resolvePlaceholders: resolvePlaceholders || ((text) => text),
563
+ fontFamily,
564
+ };
565
+
566
+ // Build container styles
567
+ const containerStyles = { ...DEFAULT_CONTAINER_STYLES };
568
+
569
+ // Apply config-level styles
570
+ if (expanded.height) {
571
+ containerStyles.height = expanded.height;
572
+ }
573
+
574
+ if (expanded.padding) {
575
+ containerStyles.padding = expanded.padding;
576
+ }
577
+
578
+ if (expanded.font_family || fontFamily) {
579
+ containerStyles["font-family"] = expanded.font_family || fontFamily;
580
+ }
581
+
582
+ if (expanded.font_size) {
583
+ containerStyles["font-size"] = expanded.font_size;
584
+ }
585
+
586
+ if (expanded.font_style) {
587
+ containerStyles["font-style"] = expanded.font_style;
588
+ }
589
+
590
+ if (expanded.font_weight) {
591
+ containerStyles["font-weight"] = String(expanded.font_weight);
592
+ }
593
+
594
+ if (expanded.color) {
595
+ containerStyles.color = expanded.color;
596
+ }
597
+
598
+ if (expanded.background) {
599
+ containerStyles.background = expanded.background;
600
+ }
601
+
602
+ // Type-specific borders
603
+ if (type === "header" && expanded.border_bottom) {
604
+ containerStyles["border-bottom"] = expanded.border_bottom;
605
+ }
606
+
607
+ if (type === "footer" && expanded.border_top) {
608
+ containerStyles["border-top"] = expanded.border_top;
609
+ }
610
+
611
+ // Parse and merge custom style string
612
+ if (expanded.style) {
613
+ Object.assign(containerStyles, parseStyleString(expanded.style));
614
+ }
615
+
616
+ // Generate zones
617
+ const leftHtml = generateZone(expanded.left, "left", context, resolvedAssets);
618
+ const centerHtml = generateZone(expanded.center, "center", context, resolvedAssets);
619
+ const rightHtml = generateZone(expanded.right, "right", context, resolvedAssets);
620
+
621
+ // A rule under the header / above the footer should stop at the side
622
+ // padding, like the text does, instead of running to the paper edge. Move
623
+ // padding (and any background, which stays full-width) to an outer box.
624
+ const hasRule =
625
+ (type === "header" && expanded.border_bottom) ||
626
+ (type === "footer" && expanded.border_top);
627
+ let open = "";
628
+ let close = "";
629
+ if (hasRule) {
630
+ const outer = {
631
+ width: "100%",
632
+ "box-sizing": "border-box",
633
+ padding: containerStyles.padding,
634
+ };
635
+ if (containerStyles.background) {
636
+ outer.background = containerStyles.background;
637
+ delete containerStyles.background;
638
+ }
639
+ containerStyles.padding = "0";
640
+ open = `<div style="${escapeHtml(stylesToString(outer))}">`;
641
+ close = "</div>";
642
+ }
643
+
644
+ // Build the final HTML
645
+ const containerStyleStr = stylesToString(containerStyles);
646
+
647
+ // If center exists, anchor it to the true page midpoint via absolute
648
+ // positioning so left/right content width never shifts the center.
649
+ if (centerHtml) {
650
+ const containerStyleStrAbs = stylesToString({
651
+ ...containerStyles,
652
+ position: "relative",
653
+ });
654
+ const leftWrapperStyle = "flex-shrink:0;min-width:0;";
655
+ const rightWrapperStyle = "flex-shrink:0;min-width:0;margin-left:auto;";
656
+ const centerWrapperStyle =
657
+ "position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);" +
658
+ "display:flex;align-items:center;justify-content:center;";
659
+
660
+ let html = `${open}<div style="${escapeHtml(containerStyleStrAbs)}">`;
661
+ html += `<div style="${leftWrapperStyle}">${leftHtml || ""}</div>`;
662
+ html += `<div style="${centerWrapperStyle}">${centerHtml}</div>`;
663
+ html += `<div style="${rightWrapperStyle}">${rightHtml || ""}</div>`;
664
+ html += `</div>${close}`;
665
+ return html;
666
+ }
667
+
668
+ // Simple two-column layout (left and right only)
669
+ let html = `${open}<div style="${escapeHtml(containerStyleStr)}">`;
670
+
671
+ if (leftHtml) {
672
+ html += leftHtml;
673
+ }
674
+
675
+ // Add spacer if both left and right exist
676
+ if (leftHtml && rightHtml) {
677
+ html += '<div style="flex:1;"></div>';
678
+ }
679
+
680
+ if (rightHtml) {
681
+ html += rightHtml;
682
+ }
683
+
684
+ html += `</div>${close}`;
685
+ return html;
686
+ }
687
+
688
+ // ─────────────────────────────────────────────────────────────────────────────
689
+ // Full Generation with Asset Resolution
690
+ // ─────────────────────────────────────────────────────────────────────────────
691
+
692
+ /**
693
+ * @typedef {Object} GenerateWithAssetsOptions
694
+ * @property {import('./types.mjs').HeaderFooterConfig} config - Header/footer configuration
695
+ * @property {'header'|'footer'} type - Whether this is header or footer
696
+ * @property {(text: string) => string} resolvePlaceholders - Placeholder resolver function
697
+ * @property {(imagePath: string) => Promise<string>} resolveAsset - Asset resolver function
698
+ * @property {string} [fontFamily] - Global font family override
699
+ */
700
+
701
+ /**
702
+ * Generate HTML template with automatic asset resolution.
703
+ *
704
+ * @param {GenerateWithAssetsOptions} options - Generation options
705
+ * @returns {Promise<string>} HTML template string
706
+ */
707
+ export async function generateHtmlWithAssets(options) {
708
+ const {
709
+ config,
710
+ type = "header",
711
+ resolvePlaceholders,
712
+ resolveAsset,
713
+ fontFamily,
714
+ } = options;
715
+
716
+ if (!config || typeof config !== "object") {
717
+ return "";
718
+ }
719
+
720
+ // Collect all image paths
721
+ const imagePaths = collectImagePaths(config);
722
+
723
+ // Resolve all assets in parallel
724
+ const resolvedAssets = new Map();
725
+
726
+ if (resolveAsset && imagePaths.length > 0) {
727
+ const resolutions = await Promise.all(
728
+ imagePaths.map(async (path) => {
729
+ try {
730
+ const dataUri = await resolveAsset(path);
731
+ return { path, dataUri };
732
+ } catch (error) {
733
+ console.warn(`Failed to resolve asset "${path}": ${error.message}`);
734
+ return { path, dataUri: path }; // Keep original path on failure
735
+ }
736
+ })
737
+ );
738
+
739
+ for (const { path, dataUri } of resolutions) {
740
+ resolvedAssets.set(path, dataUri);
741
+ }
742
+ }
743
+
744
+ // Generate HTML with resolved assets
745
+ return generateHtml({
746
+ config,
747
+ type,
748
+ resolvePlaceholders,
749
+ resolvedAssets,
750
+ fontFamily,
751
+ });
752
+ }
753
+
754
+ // ─────────────────────────────────────────────────────────────────────────────
755
+ // Generator Factory
756
+ // ─────────────────────────────────────────────────────────────────────────────
757
+
758
+ /**
759
+ * @typedef {Object} HtmlGeneratorOptions
760
+ * @property {import('./lib/placeholder-resolver.mjs').PlaceholderResolver} placeholderResolver - Placeholder resolver
761
+ * @property {import('./lib/asset-resolver.mjs').AssetResolver} [assetResolver] - Asset resolver (optional)
762
+ * @property {string} [fontFamily] - Default font family
763
+ */
764
+
765
+ /**
766
+ * @typedef {Object} HtmlGenerator
767
+ * @property {(config: import('./types.mjs').HeaderFooterConfig) => Promise<string>} generateHeader - Generate header HTML
768
+ * @property {(config: import('./types.mjs').HeaderFooterConfig) => Promise<string>} generateFooter - Generate footer HTML
769
+ * @property {(config: import('./types.mjs').HeaderFooterConfig) => string[]} getImagePaths - Get image paths from config
770
+ */
771
+
772
+ /**
773
+ * Create an HTML generator with bound resolvers.
774
+ *
775
+ * @param {HtmlGeneratorOptions} options - Generator options
776
+ * @returns {HtmlGenerator}
777
+ *
778
+ * @example
779
+ * const generator = createHtmlGenerator({
780
+ * placeholderResolver: createPlaceholderResolver(context),
781
+ * assetResolver: createAssetResolver({ basePath: '/path/to/doc.md' }),
782
+ * fontFamily: 'Arial, sans-serif',
783
+ * });
784
+ *
785
+ * const headerHtml = await generator.generateHeader(headerConfig);
786
+ * const footerHtml = await generator.generateFooter(footerConfig);
787
+ */
788
+ export function createHtmlGenerator(options) {
789
+ const { placeholderResolver, assetResolver, fontFamily } = options;
790
+
791
+ const resolvePlaceholders = placeholderResolver?.resolve || ((text) => text);
792
+ const resolveAsset = assetResolver?.resolve;
793
+
794
+ return {
795
+ /**
796
+ * Generate header HTML from configuration.
797
+ *
798
+ * @param {import('./types.mjs').HeaderFooterConfig} config - Header configuration
799
+ * @returns {Promise<string>} Header HTML
800
+ */
801
+ async generateHeader(config) {
802
+ return generateHtmlWithAssets({
803
+ config,
804
+ type: "header",
805
+ resolvePlaceholders,
806
+ resolveAsset,
807
+ fontFamily,
808
+ });
809
+ },
810
+
811
+ /**
812
+ * Generate footer HTML from configuration.
813
+ *
814
+ * @param {import('./types.mjs').HeaderFooterConfig} config - Footer configuration
815
+ * @returns {Promise<string>} Footer HTML
816
+ */
817
+ async generateFooter(config) {
818
+ return generateHtmlWithAssets({
819
+ config,
820
+ type: "footer",
821
+ resolvePlaceholders,
822
+ resolveAsset,
823
+ fontFamily,
824
+ });
825
+ },
826
+
827
+ /**
828
+ * Get all image paths from a configuration (useful for pre-warming cache).
829
+ *
830
+ * @param {import('./types.mjs').HeaderFooterConfig} config - Configuration
831
+ * @returns {string[]} Array of image paths
832
+ */
833
+ getImagePaths(config) {
834
+ return collectImagePaths(config);
835
+ },
836
+ };
837
+ }