markdown-pdf-export 0.0.0-stage → 2.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.
@@ -0,0 +1,725 @@
1
+ /**
2
+ * @fileoverview Schema validator for structured header/footer configuration.
3
+ *
4
+ * Validates the declarative header/footer configuration and provides
5
+ * helpful error messages for invalid configurations.
6
+ *
7
+ * @module schema-validator
8
+ */
9
+
10
+ import {
11
+ ELEMENT_TYPES,
12
+ IMAGE_FORMATS,
13
+ SHORTHAND_MAPPINGS,
14
+ } from "./types.mjs";
15
+
16
+ // ─────────────────────────────────────────────────────────────────────────────
17
+ // Validation Helpers
18
+ // ─────────────────────────────────────────────────────────────────────────────
19
+
20
+ /**
21
+ * Create a validation error object.
22
+ *
23
+ * @param {string} path - JSON path to the invalid property
24
+ * @param {string} message - Human-readable error message
25
+ * @param {any} [value] - The invalid value
26
+ * @returns {import('./types.mjs').ValidationError}
27
+ */
28
+ function createError(path, message, value = undefined) {
29
+ const error = { path, message };
30
+ if (value !== undefined) {
31
+ error.value = value;
32
+ }
33
+ return error;
34
+ }
35
+
36
+ /**
37
+ * Create a validation warning object.
38
+ *
39
+ * @param {string} path - JSON path to the property
40
+ * @param {string} message - Human-readable warning message
41
+ * @param {any} [value] - The value that triggered the warning
42
+ * @returns {import('./types.mjs').ValidationError}
43
+ */
44
+ function createWarning(path, message, value = undefined) {
45
+ return createError(path, message, value);
46
+ }
47
+
48
+ /**
49
+ * Check if a value is a non-empty string.
50
+ *
51
+ * @param {any} value - Value to check
52
+ * @returns {boolean}
53
+ */
54
+ function isNonEmptyString(value) {
55
+ return typeof value === "string" && value.trim().length > 0;
56
+ }
57
+
58
+ /**
59
+ * Check if a value is a valid CSS length (e.g., "10px", "15mm", "1in").
60
+ *
61
+ * @param {any} value - Value to check
62
+ * @returns {boolean}
63
+ */
64
+ function isCssLength(value) {
65
+ if (typeof value !== "string") return false;
66
+ // Match number followed by unit, or just "0"
67
+ return /^-?\d*\.?\d+(px|pt|em|rem|mm|cm|in|%|vh|vw)?$/.test(value.trim()) || value.trim() === "0";
68
+ }
69
+
70
+ /**
71
+ * Check if a value is a valid CSS color.
72
+ * This is a permissive check - accepts hex, rgb, rgba, hsl, hsla, and named colors.
73
+ *
74
+ * @param {any} value - Value to check
75
+ * @returns {boolean}
76
+ */
77
+ function isCssColor(value) {
78
+ if (typeof value !== "string") return false;
79
+ const v = value.trim().toLowerCase();
80
+ // Hex colors
81
+ if (/^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/.test(v)) return true;
82
+ // rgb/rgba/hsl/hsla
83
+ if (/^(rgb|rgba|hsl|hsla)\([^)]+\)$/.test(v)) return true;
84
+ // Named colors (permissive - just check it's alphabetic)
85
+ if (/^[a-z]+$/.test(v)) return true;
86
+ return false;
87
+ }
88
+
89
+ /**
90
+ * Check if a value is a valid font-weight.
91
+ *
92
+ * @param {any} value - Value to check
93
+ * @returns {boolean}
94
+ */
95
+ function isFontWeight(value) {
96
+ if (typeof value === "number") {
97
+ return value >= 1 && value <= 1000;
98
+ }
99
+ if (typeof value === "string") {
100
+ const v = value.trim().toLowerCase();
101
+ return ["normal", "bold", "bolder", "lighter"].includes(v) ||
102
+ /^\d{1,4}$/.test(v);
103
+ }
104
+ return false;
105
+ }
106
+
107
+ /**
108
+ * Check if a value is a valid font-style.
109
+ *
110
+ * @param {any} value - Value to check
111
+ * @returns {boolean}
112
+ */
113
+ function isFontStyle(value) {
114
+ if (typeof value !== "string") return false;
115
+ return ["normal", "italic", "oblique"].includes(value.trim().toLowerCase());
116
+ }
117
+
118
+ /**
119
+ * Check if a file extension is a supported image format.
120
+ *
121
+ * @param {string} path - File path
122
+ * @returns {boolean}
123
+ */
124
+ function isSupportedImageFormat(path) {
125
+ if (typeof path !== "string") return false;
126
+ const ext = path.toLowerCase().match(/\.[^.]+$/)?.[0];
127
+ return ext ? ext in IMAGE_FORMATS : false;
128
+ }
129
+
130
+ // ─────────────────────────────────────────────────────────────────────────────
131
+ // Element Validators
132
+ // ─────────────────────────────────────────────────────────────────────────────
133
+
134
+ /**
135
+ * Validate a text element.
136
+ *
137
+ * @param {any} element - Element to validate
138
+ * @param {string} path - JSON path for error reporting
139
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
140
+ */
141
+ function validateTextElement(element, path) {
142
+ const errors = [];
143
+ const warnings = [];
144
+
145
+ if (!isNonEmptyString(element.content)) {
146
+ errors.push(createError(`${path}.content`, "Text element requires a non-empty 'content' string", element.content));
147
+ }
148
+
149
+ if (element.font_size !== undefined && !isCssLength(element.font_size)) {
150
+ warnings.push(createWarning(`${path}.font_size`, `Invalid CSS length: "${element.font_size}". Expected format like "10px", "9pt", "1em"`, element.font_size));
151
+ }
152
+
153
+ if (element.font_weight !== undefined && !isFontWeight(element.font_weight)) {
154
+ warnings.push(createWarning(`${path}.font_weight`, `Invalid font-weight: "${element.font_weight}". Expected "normal", "bold", or a number 1-1000`, element.font_weight));
155
+ }
156
+
157
+ if (element.font_style !== undefined && !isFontStyle(element.font_style)) {
158
+ warnings.push(createWarning(`${path}.font_style`, `Invalid font-style: "${element.font_style}". Expected "normal", "italic", or "oblique"`, element.font_style));
159
+ }
160
+
161
+ if (element.color !== undefined && !isCssColor(element.color)) {
162
+ warnings.push(createWarning(`${path}.color`, `Possibly invalid CSS color: "${element.color}"`, element.color));
163
+ }
164
+
165
+ return { errors, warnings };
166
+ }
167
+
168
+ /**
169
+ * Validate an image element.
170
+ *
171
+ * @param {any} element - Element to validate
172
+ * @param {string} path - JSON path for error reporting
173
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
174
+ */
175
+ function validateImageElement(element, path) {
176
+ const errors = [];
177
+ const warnings = [];
178
+
179
+ if (!isNonEmptyString(element.src)) {
180
+ errors.push(createError(`${path}.src`, "Image element requires a non-empty 'src' path", element.src));
181
+ } else if (!isSupportedImageFormat(element.src)) {
182
+ const ext = element.src.match(/\.[^.]+$/)?.[0] || "(no extension)";
183
+ warnings.push(createWarning(`${path}.src`, `Unsupported image format: "${ext}". Supported formats: SVG, PNG, JPG`, element.src));
184
+ }
185
+
186
+ if (element.height !== undefined && !isCssLength(element.height)) {
187
+ warnings.push(createWarning(`${path}.height`, `Invalid CSS length for height: "${element.height}"`, element.height));
188
+ }
189
+
190
+ if (element.width !== undefined && !isCssLength(element.width)) {
191
+ warnings.push(createWarning(`${path}.width`, `Invalid CSS length for width: "${element.width}"`, element.width));
192
+ }
193
+
194
+ return { errors, warnings };
195
+ }
196
+
197
+ /**
198
+ * Validate a page_number element.
199
+ *
200
+ * @param {any} element - Element to validate
201
+ * @param {string} path - JSON path for error reporting
202
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
203
+ */
204
+ function validatePageNumberElement(element, path) {
205
+ const errors = [];
206
+ const warnings = [];
207
+
208
+ if (element.format !== undefined && typeof element.format !== "string") {
209
+ errors.push(createError(`${path}.format`, "Format must be a string", element.format));
210
+ }
211
+
212
+ if (element.font_size !== undefined && !isCssLength(element.font_size)) {
213
+ warnings.push(createWarning(`${path}.font_size`, `Invalid CSS length: "${element.font_size}"`, element.font_size));
214
+ }
215
+
216
+ if (element.color !== undefined && !isCssColor(element.color)) {
217
+ warnings.push(createWarning(`${path}.color`, `Possibly invalid CSS color: "${element.color}"`, element.color));
218
+ }
219
+
220
+ return { errors, warnings };
221
+ }
222
+
223
+ /**
224
+ * Validate a total_pages element.
225
+ *
226
+ * @param {any} element - Element to validate
227
+ * @param {string} path - JSON path for error reporting
228
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
229
+ */
230
+ function validateTotalPagesElement(element, path) {
231
+ // Same validation as page_number
232
+ return validatePageNumberElement(element, path);
233
+ }
234
+
235
+ /**
236
+ * Validate a date element.
237
+ *
238
+ * @param {any} element - Element to validate
239
+ * @param {string} path - JSON path for error reporting
240
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
241
+ */
242
+ function validateDateElement(element, path) {
243
+ const errors = [];
244
+ const warnings = [];
245
+
246
+ if (element.format !== undefined && typeof element.format !== "string") {
247
+ errors.push(createError(`${path}.format`, "Date format must be a string (date-fns format)", element.format));
248
+ }
249
+
250
+ if (element.font_size !== undefined && !isCssLength(element.font_size)) {
251
+ warnings.push(createWarning(`${path}.font_size`, `Invalid CSS length: "${element.font_size}"`, element.font_size));
252
+ }
253
+
254
+ if (element.color !== undefined && !isCssColor(element.color)) {
255
+ warnings.push(createWarning(`${path}.color`, `Possibly invalid CSS color: "${element.color}"`, element.color));
256
+ }
257
+
258
+ return { errors, warnings };
259
+ }
260
+
261
+ /**
262
+ * Validate a title element.
263
+ *
264
+ * @param {any} element - Element to validate
265
+ * @param {string} path - JSON path for error reporting
266
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
267
+ */
268
+ function validateTitleElement(element, path) {
269
+ const errors = [];
270
+ const warnings = [];
271
+
272
+ if (element.font_size !== undefined && !isCssLength(element.font_size)) {
273
+ warnings.push(createWarning(`${path}.font_size`, `Invalid CSS length: "${element.font_size}"`, element.font_size));
274
+ }
275
+
276
+ if (element.font_weight !== undefined && !isFontWeight(element.font_weight)) {
277
+ warnings.push(createWarning(`${path}.font_weight`, `Invalid font-weight: "${element.font_weight}"`, element.font_weight));
278
+ }
279
+
280
+ if (element.color !== undefined && !isCssColor(element.color)) {
281
+ warnings.push(createWarning(`${path}.color`, `Possibly invalid CSS color: "${element.color}"`, element.color));
282
+ }
283
+
284
+ if (element.fallback !== undefined && typeof element.fallback !== "string") {
285
+ errors.push(createError(`${path}.fallback`, "Fallback must be a string", element.fallback));
286
+ }
287
+
288
+ return { errors, warnings };
289
+ }
290
+
291
+ /**
292
+ * Validate a spacer element.
293
+ *
294
+ * @param {any} element - Element to validate
295
+ * @param {string} path - JSON path for error reporting
296
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
297
+ */
298
+ function validateSpacerElement(element, path) {
299
+ const errors = [];
300
+ const warnings = [];
301
+
302
+ if (element.width !== undefined && !isCssLength(element.width)) {
303
+ warnings.push(createWarning(`${path}.width`, `Invalid CSS length for width: "${element.width}"`, element.width));
304
+ }
305
+
306
+ return { errors, warnings };
307
+ }
308
+
309
+ /**
310
+ * Validate a single element.
311
+ *
312
+ * @param {any} element - Element to validate
313
+ * @param {string} path - JSON path for error reporting
314
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
315
+ */
316
+ function validateElement(element, path) {
317
+ const errors = [];
318
+ const warnings = [];
319
+
320
+ if (element === null || element === undefined) {
321
+ errors.push(createError(path, "Element cannot be null or undefined"));
322
+ return { errors, warnings };
323
+ }
324
+
325
+ if (typeof element !== "object" || Array.isArray(element)) {
326
+ errors.push(createError(path, "Element must be an object", element));
327
+ return { errors, warnings };
328
+ }
329
+
330
+ if (!element.type) {
331
+ errors.push(createError(`${path}.type`, "Element requires a 'type' property"));
332
+ return { errors, warnings };
333
+ }
334
+
335
+ if (!ELEMENT_TYPES.includes(element.type)) {
336
+ errors.push(createError(
337
+ `${path}.type`,
338
+ `Invalid element type: "${element.type}". Valid types: ${ELEMENT_TYPES.join(", ")}`,
339
+ element.type
340
+ ));
341
+ return { errors, warnings };
342
+ }
343
+
344
+ // Validate based on element type
345
+ let result;
346
+ switch (element.type) {
347
+ case "text":
348
+ result = validateTextElement(element, path);
349
+ break;
350
+ case "image":
351
+ result = validateImageElement(element, path);
352
+ break;
353
+ case "page_number":
354
+ result = validatePageNumberElement(element, path);
355
+ break;
356
+ case "total_pages":
357
+ result = validateTotalPagesElement(element, path);
358
+ break;
359
+ case "date":
360
+ result = validateDateElement(element, path);
361
+ break;
362
+ case "title":
363
+ result = validateTitleElement(element, path);
364
+ break;
365
+ case "spacer":
366
+ result = validateSpacerElement(element, path);
367
+ break;
368
+ default:
369
+ // Already validated type above, shouldn't reach here
370
+ break;
371
+ }
372
+
373
+ if (result) {
374
+ errors.push(...result.errors);
375
+ warnings.push(...result.warnings);
376
+ }
377
+
378
+ return { errors, warnings };
379
+ }
380
+
381
+ // ─────────────────────────────────────────────────────────────────────────────
382
+ // Zone Validators
383
+ // ─────────────────────────────────────────────────────────────────────────────
384
+
385
+ /**
386
+ * Validate a zone (left, center, or right).
387
+ *
388
+ * @param {any} zone - Zone content (element or array of elements)
389
+ * @param {string} path - JSON path for error reporting
390
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
391
+ */
392
+ function validateZone(zone, path) {
393
+ const errors = [];
394
+ const warnings = [];
395
+
396
+ // null means explicitly remove this zone - valid
397
+ if (zone === null) {
398
+ return { errors, warnings };
399
+ }
400
+
401
+ // Array of elements
402
+ if (Array.isArray(zone)) {
403
+ if (zone.length === 0) {
404
+ warnings.push(createWarning(path, "Empty zone array - zone will be empty"));
405
+ }
406
+ zone.forEach((element, index) => {
407
+ const result = validateElement(element, `${path}[${index}]`);
408
+ errors.push(...result.errors);
409
+ warnings.push(...result.warnings);
410
+ });
411
+ return { errors, warnings };
412
+ }
413
+
414
+ // Single element (object)
415
+ if (typeof zone === "object") {
416
+ const result = validateElement(zone, path);
417
+ errors.push(...result.errors);
418
+ warnings.push(...result.warnings);
419
+ return { errors, warnings };
420
+ }
421
+
422
+ errors.push(createError(path, "Zone must be an element object, array of elements, or null", zone));
423
+ return { errors, warnings };
424
+ }
425
+
426
+ // ─────────────────────────────────────────────────────────────────────────────
427
+ // Header/Footer Validator
428
+ // ─────────────────────────────────────────────────────────────────────────────
429
+
430
+ /**
431
+ * Validate a header or footer configuration.
432
+ *
433
+ * @param {any} config - Header or footer configuration
434
+ * @param {string} path - JSON path for error reporting (e.g., "header" or "footer")
435
+ * @returns {{errors: import('./types.mjs').ValidationError[], warnings: import('./types.mjs').ValidationError[]}}
436
+ */
437
+ function validateHeaderFooter(config, path) {
438
+ const errors = [];
439
+ const warnings = [];
440
+
441
+ // null means no header/footer - valid
442
+ if (config === null || config === undefined) {
443
+ return { errors, warnings };
444
+ }
445
+
446
+ if (typeof config !== "object" || Array.isArray(config)) {
447
+ errors.push(createError(path, "Header/footer configuration must be an object", config));
448
+ return { errors, warnings };
449
+ }
450
+
451
+ // Validate container properties
452
+ if (config.height !== undefined && !isCssLength(config.height)) {
453
+ warnings.push(createWarning(`${path}.height`, `Invalid CSS length: "${config.height}"`, config.height));
454
+ }
455
+
456
+ if (config.font_size !== undefined && !isCssLength(config.font_size)) {
457
+ warnings.push(createWarning(`${path}.font_size`, `Invalid CSS length: "${config.font_size}"`, config.font_size));
458
+ }
459
+
460
+ if (config.color !== undefined && !isCssColor(config.color)) {
461
+ warnings.push(createWarning(`${path}.color`, `Possibly invalid CSS color: "${config.color}"`, config.color));
462
+ }
463
+
464
+ if (config.background !== undefined && typeof config.background !== "string") {
465
+ warnings.push(createWarning(`${path}.background`, "Background should be a CSS value string", config.background));
466
+ }
467
+
468
+ // Validate zones
469
+ const zones = ["left", "center", "right"];
470
+ for (const zone of zones) {
471
+ if (config[zone] !== undefined) {
472
+ const result = validateZone(config[zone], `${path}.${zone}`);
473
+ errors.push(...result.errors);
474
+ warnings.push(...result.warnings);
475
+ }
476
+ }
477
+
478
+ // Check for shorthand properties
479
+ const shorthandKeys = Object.keys(SHORTHAND_MAPPINGS);
480
+ const usedShorthands = shorthandKeys.filter((key) => config[key] !== undefined);
481
+ const usedZones = zones.filter((zone) => config[zone] !== undefined);
482
+
483
+ // Warn if mixing shorthand and full zone definitions for the same zone
484
+ for (const shorthand of usedShorthands) {
485
+ const mapping = SHORTHAND_MAPPINGS[shorthand];
486
+ if (usedZones.includes(mapping.zone)) {
487
+ warnings.push(createWarning(
488
+ `${path}.${shorthand}`,
489
+ `Shorthand "${shorthand}" is ignored because "${mapping.zone}" zone is also defined`,
490
+ config[shorthand]
491
+ ));
492
+ }
493
+ }
494
+
495
+ // Validate shorthand values
496
+ for (const shorthand of usedShorthands) {
497
+ const value = config[shorthand];
498
+
499
+ if (shorthand.endsWith("_text")) {
500
+ if (typeof value !== "string") {
501
+ errors.push(createError(`${path}.${shorthand}`, "Text shorthand must be a string", value));
502
+ }
503
+ } else if (shorthand.endsWith("_image") && !shorthand.endsWith("_image_height")) {
504
+ if (typeof value !== "string") {
505
+ errors.push(createError(`${path}.${shorthand}`, "Image shorthand must be a file path string", value));
506
+ } else if (!isSupportedImageFormat(value)) {
507
+ warnings.push(createWarning(`${path}.${shorthand}`, "Unsupported image format. Supported: SVG, PNG, JPG", value));
508
+ }
509
+ } else if (shorthand.endsWith("_image_height")) {
510
+ if (!isCssLength(value)) {
511
+ warnings.push(createWarning(`${path}.${shorthand}`, `Invalid CSS length: "${value}"`, value));
512
+ }
513
+ }
514
+ }
515
+
516
+ return { errors, warnings };
517
+ }
518
+
519
+ // ─────────────────────────────────────────────────────────────────────────────
520
+ // Main Validation Functions
521
+ // ─────────────────────────────────────────────────────────────────────────────
522
+
523
+ /**
524
+ * Validate a structured PDF configuration (header and footer).
525
+ *
526
+ * @param {any} config - Configuration object with optional header and footer
527
+ * @returns {import('./types.mjs').ValidationResult}
528
+ */
529
+ export function validateStructuredConfig(config) {
530
+ const errors = [];
531
+ const warnings = [];
532
+
533
+ if (config === null || config === undefined) {
534
+ return { valid: true, errors: [], warnings: [] };
535
+ }
536
+
537
+ if (typeof config !== "object" || Array.isArray(config)) {
538
+ return {
539
+ valid: false,
540
+ errors: [createError("", "Configuration must be an object", config)],
541
+ warnings: [],
542
+ };
543
+ }
544
+
545
+ // Validate header
546
+ if (config.header !== undefined) {
547
+ const result = validateHeaderFooter(config.header, "header");
548
+ errors.push(...result.errors);
549
+ warnings.push(...result.warnings);
550
+ }
551
+
552
+ // Validate footer
553
+ if (config.footer !== undefined) {
554
+ const result = validateHeaderFooter(config.footer, "footer");
555
+ errors.push(...result.errors);
556
+ warnings.push(...result.warnings);
557
+ }
558
+
559
+ return {
560
+ valid: errors.length === 0,
561
+ errors,
562
+ warnings,
563
+ };
564
+ }
565
+
566
+ /**
567
+ * Validate front matter PDF configuration.
568
+ *
569
+ * @param {any} frontMatterConfig - The pdf block from front matter
570
+ * @returns {import('./types.mjs').ValidationResult}
571
+ */
572
+ export function validateFrontMatterConfig(frontMatterConfig) {
573
+ const errors = [];
574
+ const warnings = [];
575
+
576
+ if (frontMatterConfig === null || frontMatterConfig === undefined) {
577
+ return { valid: true, errors: [], warnings: [] };
578
+ }
579
+
580
+ if (typeof frontMatterConfig !== "object" || Array.isArray(frontMatterConfig)) {
581
+ return {
582
+ valid: false,
583
+ errors: [createError("pdf", "Front matter pdf must be an object", frontMatterConfig)],
584
+ warnings: [],
585
+ };
586
+ }
587
+
588
+ // Validate header and footer
589
+ const structuredResult = validateStructuredConfig(frontMatterConfig);
590
+ errors.push(...structuredResult.errors);
591
+ warnings.push(...structuredResult.warnings);
592
+
593
+ // Validate other settings that can appear in front matter
594
+ if (frontMatterConfig.display_header_footer !== undefined) {
595
+ if (typeof frontMatterConfig.display_header_footer !== "boolean") {
596
+ errors.push(createError(
597
+ "pdf.display_header_footer",
598
+ "display_header_footer must be a boolean",
599
+ frontMatterConfig.display_header_footer
600
+ ));
601
+ }
602
+ }
603
+
604
+ if (frontMatterConfig.page_format !== undefined) {
605
+ const validFormats = ["A4", "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A5", "A6"];
606
+ if (!validFormats.includes(frontMatterConfig.page_format)) {
607
+ errors.push(createError(
608
+ "pdf.page_format",
609
+ `Invalid page format: "${frontMatterConfig.page_format}". Valid: ${validFormats.join(", ")}`,
610
+ frontMatterConfig.page_format
611
+ ));
612
+ }
613
+ }
614
+
615
+ if (frontMatterConfig.orientation !== undefined) {
616
+ if (!["portrait", "landscape"].includes(frontMatterConfig.orientation)) {
617
+ errors.push(createError(
618
+ "pdf.orientation",
619
+ `Invalid orientation: "${frontMatterConfig.orientation}". Must be "portrait" or "landscape"`,
620
+ frontMatterConfig.orientation
621
+ ));
622
+ }
623
+ }
624
+
625
+ if (frontMatterConfig.scale !== undefined) {
626
+ if (typeof frontMatterConfig.scale !== "number" || frontMatterConfig.scale < 0.1 || frontMatterConfig.scale > 2) {
627
+ errors.push(createError(
628
+ "pdf.scale",
629
+ "Scale must be a number between 0.1 and 2",
630
+ frontMatterConfig.scale
631
+ ));
632
+ }
633
+ }
634
+
635
+ if (frontMatterConfig.margin !== undefined) {
636
+ if (typeof frontMatterConfig.margin !== "object" || Array.isArray(frontMatterConfig.margin)) {
637
+ errors.push(createError("pdf.margin", "Margin must be an object", frontMatterConfig.margin));
638
+ } else {
639
+ for (const side of ["top", "right", "bottom", "left"]) {
640
+ if (frontMatterConfig.margin[side] !== undefined && !isCssLength(frontMatterConfig.margin[side])) {
641
+ warnings.push(createWarning(
642
+ `pdf.margin.${side}`,
643
+ `Invalid CSS length: "${frontMatterConfig.margin[side]}"`,
644
+ frontMatterConfig.margin[side]
645
+ ));
646
+ }
647
+ }
648
+ }
649
+ }
650
+
651
+ return {
652
+ valid: errors.length === 0,
653
+ errors,
654
+ warnings,
655
+ };
656
+ }
657
+
658
+ /**
659
+ * Format validation errors and warnings as a human-readable string.
660
+ *
661
+ * @param {import('./types.mjs').ValidationResult} result - Validation result
662
+ * @returns {string} Formatted message
663
+ */
664
+ export function formatValidationResult(result) {
665
+ const lines = [];
666
+
667
+ if (result.errors.length > 0) {
668
+ lines.push("❌ Validation Errors:");
669
+ for (const error of result.errors) {
670
+ const path = error.path ? `[${error.path}] ` : "";
671
+ lines.push(` ${path}${error.message}`);
672
+ }
673
+ }
674
+
675
+ if (result.warnings.length > 0) {
676
+ if (lines.length > 0) lines.push("");
677
+ lines.push("⚠️ Validation Warnings:");
678
+ for (const warning of result.warnings) {
679
+ const path = warning.path ? `[${warning.path}] ` : "";
680
+ lines.push(` ${path}${warning.message}`);
681
+ }
682
+ }
683
+
684
+ if (result.valid && result.warnings.length === 0) {
685
+ lines.push("✅ Configuration is valid");
686
+ }
687
+
688
+ return lines.join("\n");
689
+ }
690
+
691
+ /**
692
+ * Check if a configuration object uses structured header/footer format
693
+ * (vs. raw HTML template strings).
694
+ *
695
+ * @param {any} config - Configuration object
696
+ * @returns {boolean} True if using structured format
697
+ */
698
+ export function isStructuredConfig(config) {
699
+ if (!config || typeof config !== "object") {
700
+ return false;
701
+ }
702
+
703
+ // Check if header or footer is an object (structured) vs string (raw HTML)
704
+ if (config.header !== undefined && config.header !== null) {
705
+ if (typeof config.header === "object") {
706
+ return true;
707
+ }
708
+ }
709
+
710
+ if (config.footer !== undefined && config.footer !== null) {
711
+ if (typeof config.footer === "object") {
712
+ return true;
713
+ }
714
+ }
715
+
716
+ // Check for shorthand properties
717
+ const shorthandKeys = Object.keys(SHORTHAND_MAPPINGS);
718
+ for (const key of shorthandKeys) {
719
+ if (config[key] !== undefined) {
720
+ return true;
721
+ }
722
+ }
723
+
724
+ return false;
725
+ }