@twinfinity/printing 6.0.1-ci.28952-beta → 6.0.2-beta

package/src/layout/templateVariables.ts

@@ -1,317 +1,317 @@
-/**
- * Template variable extraction, validation, and resolution.
- *
- * This module provides utilities for working with parameterized templates:
- * - Extract variable definitions for UI generation
- * - Get default values (fail-safe fallback)
- * - Resolve user-provided values with validation
- * - Apply variables to template (substitute {{vars.*}} references)
- *
- * @module templateVariables
- */
-
-import type { LayoutTemplate, TemplateVariableDef, TemplateVariableInfo } from './types';
-
-/**
- * Extract all variable definitions from a template.
- *
- * Returns an array of variable info objects suitable for UI generation.
- * Returns empty array if template has no variables.
- *
- * @param template - Layout template (may or may not have variables)
- * @returns Array of variable definitions with metadata
- *
- * @example
- * ```typescript
- * const vars = getTemplateVariables(template);
- * // [
- * //   { name: 'hyresobjektsnummer', type: 'string', default: '2022-F2008', label: 'Hyresobjekt', ... },
- * //   { name: 'showLegend', type: 'boolean', default: true, label: 'Show Legend', ... }
- * // ]
- *
- * // Use for UI generation
- * vars.forEach(v => {
- *   if (v.type === 'string') {
- *     renderTextField(v.label, v.default);
- *   } else if (v.type === 'boolean') {
- *     renderCheckbox(v.label, v.default);
- *   }
- * });
- * ```
- */
-export function getTemplateVariables(template: LayoutTemplate): TemplateVariableInfo[] {
-    if (!template.variables) return [];
-
-    return Object.entries(template.variables).map(([name, def]) => ({
-        name,
-        type: def.type,
-        default: def.default,
-        label: def.label ?? name,
-        description: def.description,
-        format: def.format,
-        min: def.min,
-        max: def.max,
-        step: def.step,
-        minLength: def.minLength,
-        maxLength: def.maxLength,
-        pattern: def.pattern,
-        enum: def.enum,
-        items: def.items
-    }));
-}
-
-/**
- * Extract all default values from a template.
- *
- * Returns an object with all variable names mapped to their default values.
- * These defaults are guaranteed to work - template can always render with them.
- *
- * Returns empty object if template has no variables.
- *
- * @param template - Layout template
- * @returns Object mapping variable names to default values
- *
- * @example
- * ```typescript
- * const defaults = getTemplateDefaults(template);
- * // { hyresobjektsnummer: '2022-F2008', showLegend: true, scaleDenom: 100 }
- *
- * // Can always render with defaults (fail-safe)
- * const { svg } = await renderDrawing({
- *   template,
- *   models,
- *   variables: defaults  // Guaranteed to work
- * });
- * ```
- */
-export function getTemplateDefaults(template: LayoutTemplate): Record<string, any> {
-    if (!template.variables) return {};
-
-    const defaults: Record<string, any> = {};
-    for (const [name, def] of Object.entries(template.variables)) {
-        defaults[name] = def.default;
-    }
-    return defaults;
-}
-
-/**
- * Validate a value against a variable definition.
- *
- * Checks type and constraint validation (min/max, pattern, enum, etc.).
- *
- * @param value - Value to validate
- * @param varDef - Variable definition with constraints
- * @returns Validation result with ok flag and optional error message
- */
-function validateVariable(value: any, varDef: TemplateVariableDef): { ok: boolean; error?: string } {
-    // Type check
-    const actualType = Array.isArray(value) ? 'array' : typeof value;
-    if (varDef.type === 'number' && actualType !== 'number') {
-        return { ok: false, error: `Expected number, got ${actualType}` };
-    }
-    if (varDef.type === 'string' && actualType !== 'string') {
-        return { ok: false, error: `Expected string, got ${actualType}` };
-    }
-    if (varDef.type === 'boolean' && actualType !== 'boolean') {
-        return { ok: false, error: `Expected boolean, got ${actualType}` };
-    }
-    if (varDef.type === 'array' && actualType !== 'array') {
-        return { ok: false, error: `Expected array, got ${actualType}` };
-    }
-
-    // String validation
-    if (varDef.type === 'string' && typeof value === 'string') {
-        if (varDef.minLength !== undefined && value.length < varDef.minLength) {
-            return { ok: false, error: `String too short (min ${varDef.minLength})` };
-        }
-        if (varDef.maxLength !== undefined && value.length > varDef.maxLength) {
-            return { ok: false, error: `String too long (max ${varDef.maxLength})` };
-        }
-        if (varDef.pattern) {
-            try {
-                const regex = new RegExp(varDef.pattern);
-                if (!regex.test(value)) {
-                    return { ok: false, error: `Does not match pattern ${varDef.pattern}` };
-                }
-            } catch {
-                return { ok: false, error: `Invalid pattern: ${varDef.pattern}` };
-            }
-        }
-        if (varDef.enum && !varDef.enum.includes(value)) {
-            return { ok: false, error: `Not in allowed values: ${varDef.enum.join(', ')}` };
-        }
-    }
-
-    // Number validation
-    if (varDef.type === 'number' && typeof value === 'number') {
-        if (!Number.isFinite(value)) {
-            return { ok: false, error: 'Must be a finite number' };
-        }
-        if (varDef.min !== undefined && value < varDef.min) {
-            return { ok: false, error: `Too small (min ${varDef.min})` };
-        }
-        if (varDef.max !== undefined && value > varDef.max) {
-            return { ok: false, error: `Too large (max ${varDef.max})` };
-        }
-    }
-
-    return { ok: true };
-}
-
-/**
- * Resolve template variables by merging user values with defaults.
- *
- * This is a **fail-safe** function:
- * - Missing values → use default
- * - Invalid values → use default + warn
- * - Unknown variables → warn + ignore
- *
- * The result is ALWAYS valid and complete (safe to use for rendering).
- *
- * @param template - Layout template with variable definitions
- * @param userValues - Optional user-provided values (can be partial or undefined)
- * @returns Object with resolved values and any validation warnings
- *
- * @example
- * ```typescript
- * // User provides partial values
- * const { values, warnings } = resolveTemplateValues(template, {
- *   hyresobjektsnummer: '2022-F2009'  // Valid
- *   // Other vars use defaults
- * });
- * // values = { hyresobjektsnummer: '2022-F2009', showLegend: true, scaleDenom: 100 }
- * // warnings = []
- *
- * // User provides invalid value
- * const { values, warnings } = resolveTemplateValues(template, {
- *   scaleDenom: 9999  // Out of range (max: 500)
- * });
- * // values = { scaleDenom: 100, ... }  ← Fell back to default
- * // warnings = ["Invalid 'scaleDenom': Too large (max 500) - using default '100'"]
- *
- * // Always safe to render
- * const resolvedTemplate = applyTemplateVariables(template, values);
- * ```
- */
-export function resolveTemplateValues(
-    template: LayoutTemplate,
-    userValues?: Record<string, any>
-): { values: Record<string, any>; warnings: string[] } {
-    const defaults = getTemplateDefaults(template);
-    const warnings: string[] = [];
-
-    // Start with all defaults (fail-safe!)
-    const values = { ...defaults };
-
-    // No user values or no variables → return defaults
-    if (!userValues || !template.variables) {
-        return { values, warnings };
-    }
-
-    // Merge and validate user values
-    for (const [name, value] of Object.entries(userValues)) {
-        const varDef = template.variables[name];
-
-        // Unknown variable
-        if (!varDef) {
-            warnings.push(`Unknown variable '${name}' - ignoring`);
-            continue;
-        }
-
-        // Validate value
-        const validation = validateVariable(value, varDef);
-        if (!validation.ok) {
-            warnings.push(`Invalid '${name}': ${validation.error} - using default '${defaults[name]}'`);
-            continue;
-        }
-
-        // Valid → use it
-        values[name] = value;
-    }
-
-    return { values, warnings };
-}
-
-/**
- * Apply variables to a template by substituting {{vars.*}} references.
- *
- * Recursively scans the template and replaces all {{vars.variableName}} references
- * with the corresponding values from the provided values object.
- *
- * Returns a new template with all variables resolved (does not mutate input).
- *
- * @param template - Original template with {{vars.*}} references
- * @param values - Resolved variable values (from resolveTemplateValues)
- * @returns New template with all {{vars.*}} replaced by actual values
- *
- * @example
- * ```typescript
- * const template = {
- *   elements: [
- *     { kind: 'text', text: 'Hyresobjekt: {{vars.hyresobjektsnummer}}' },
- *     { kind: 'viewport', clip: { where: { 'BIP.id': '{{vars.hyresobjektsnummer}}' } } }
- *   ]
- * };
- *
- * const values = { hyresobjektsnummer: '2022-F2009' };
- * const resolved = applyTemplateVariables(template, values);
- * // {
- * //   elements: [
- * //     { kind: 'text', text: 'Hyresobjekt: 2022-F2009' },
- * //     { kind: 'viewport', clip: { where: { 'BIP.id': '2022-F2009' } } }
- * //   ]
- * // }
- * ```
- */
-export function applyTemplateVariables(template: LayoutTemplate, values: Record<string, any>): LayoutTemplate {
-    // Deep clone to avoid mutation
-    const resolved: LayoutTemplate = JSON.parse(JSON.stringify(template));
-
-    // Recursively replace {{vars.*}} in all string values
-    function replaceInValue(obj: any): any {
-        if (typeof obj === 'string') {
-            return interpolateVariables(obj, values);
-        }
-        if (Array.isArray(obj)) {
-            return obj.map(replaceInValue);
-        }
-        if (obj && typeof obj === 'object') {
-            const result: any = {};
-            for (const [key, val] of Object.entries(obj)) {
-                result[key] = replaceInValue(val);
-            }
-            return result;
-        }
-        return obj;
-    }
-
-    // Apply to all template properties that might contain variable references
-    resolved.elements = replaceInValue(resolved.elements);
-    if (resolved.assets) {
-        resolved.assets = replaceInValue(resolved.assets);
-    }
-
-    return resolved;
-}
-
-/**
- * Interpolate {{vars.*}} references in a string.
- *
- * Replaces all occurrences of {{vars.variableName}} with the corresponding value.
- * If variable is not found, keeps the placeholder and logs a warning.
- *
- * @param str - String potentially containing {{vars.*}} references
- * @param values - Variable values
- * @returns String with all {{vars.*}} replaced
- */
-function interpolateVariables(str: string, values: Record<string, any>): string {
-    return str.replace(/\{\{vars\.(\w+)\}\}/g, (match, varName) => {
-        if (varName in values) {
-            const value = values[varName];
-            // Convert to string (handles numbers, booleans, etc.)
-            return String(value);
-        }
-        console.warn(`[templateVariables] Variable '${varName}' not found - keeping placeholder`);
-        return match; // Keep {{vars.varName}} as-is
-    });
-}
+/**
+ * Template variable extraction, validation, and resolution.
+ *
+ * This module provides utilities for working with parameterized templates:
+ * - Extract variable definitions for UI generation
+ * - Get default values (fail-safe fallback)
+ * - Resolve user-provided values with validation
+ * - Apply variables to template (substitute {{vars.*}} references)
+ *
+ * @module templateVariables
+ */
+
+import type { LayoutTemplate, TemplateVariableDef, TemplateVariableInfo } from './types';
+
+/**
+ * Extract all variable definitions from a template.
+ *
+ * Returns an array of variable info objects suitable for UI generation.
+ * Returns empty array if template has no variables.
+ *
+ * @param template - Layout template (may or may not have variables)
+ * @returns Array of variable definitions with metadata
+ *
+ * @example
+ * ```typescript
+ * const vars = getTemplateVariables(template);
+ * // [
+ * //   { name: 'hyresobjektsnummer', type: 'string', default: '2022-F2008', label: 'Hyresobjekt', ... },
+ * //   { name: 'showLegend', type: 'boolean', default: true, label: 'Show Legend', ... }
+ * // ]
+ *
+ * // Use for UI generation
+ * vars.forEach(v => {
+ *   if (v.type === 'string') {
+ *     renderTextField(v.label, v.default);
+ *   } else if (v.type === 'boolean') {
+ *     renderCheckbox(v.label, v.default);
+ *   }
+ * });
+ * ```
+ */
+export function getTemplateVariables(template: LayoutTemplate): TemplateVariableInfo[] {
+    if (!template.variables) return [];
+
+    return Object.entries(template.variables).map(([name, def]) => ({
+        name,
+        type: def.type,
+        default: def.default,
+        label: def.label ?? name,
+        description: def.description,
+        format: def.format,
+        min: def.min,
+        max: def.max,
+        step: def.step,
+        minLength: def.minLength,
+        maxLength: def.maxLength,
+        pattern: def.pattern,
+        enum: def.enum,
+        items: def.items
+    }));
+}
+
+/**
+ * Extract all default values from a template.
+ *
+ * Returns an object with all variable names mapped to their default values.
+ * These defaults are guaranteed to work - template can always render with them.
+ *
+ * Returns empty object if template has no variables.
+ *
+ * @param template - Layout template
+ * @returns Object mapping variable names to default values
+ *
+ * @example
+ * ```typescript
+ * const defaults = getTemplateDefaults(template);
+ * // { hyresobjektsnummer: '2022-F2008', showLegend: true, scaleDenom: 100 }
+ *
+ * // Can always render with defaults (fail-safe)
+ * const { svg } = await renderDrawing({
+ *   template,
+ *   models,
+ *   variables: defaults  // Guaranteed to work
+ * });
+ * ```
+ */
+export function getTemplateDefaults(template: LayoutTemplate): Record<string, any> {
+    if (!template.variables) return {};
+
+    const defaults: Record<string, any> = {};
+    for (const [name, def] of Object.entries(template.variables)) {
+        defaults[name] = def.default;
+    }
+    return defaults;
+}
+
+/**
+ * Validate a value against a variable definition.
+ *
+ * Checks type and constraint validation (min/max, pattern, enum, etc.).
+ *
+ * @param value - Value to validate
+ * @param varDef - Variable definition with constraints
+ * @returns Validation result with ok flag and optional error message
+ */
+function validateVariable(value: any, varDef: TemplateVariableDef): { ok: boolean; error?: string } {
+    // Type check
+    const actualType = Array.isArray(value) ? 'array' : typeof value;
+    if (varDef.type === 'number' && actualType !== 'number') {
+        return { ok: false, error: `Expected number, got ${actualType}` };
+    }
+    if (varDef.type === 'string' && actualType !== 'string') {
+        return { ok: false, error: `Expected string, got ${actualType}` };
+    }
+    if (varDef.type === 'boolean' && actualType !== 'boolean') {
+        return { ok: false, error: `Expected boolean, got ${actualType}` };
+    }
+    if (varDef.type === 'array' && actualType !== 'array') {
+        return { ok: false, error: `Expected array, got ${actualType}` };
+    }
+
+    // String validation
+    if (varDef.type === 'string' && typeof value === 'string') {
+        if (varDef.minLength !== undefined && value.length < varDef.minLength) {
+            return { ok: false, error: `String too short (min ${varDef.minLength})` };
+        }
+        if (varDef.maxLength !== undefined && value.length > varDef.maxLength) {
+            return { ok: false, error: `String too long (max ${varDef.maxLength})` };
+        }
+        if (varDef.pattern) {
+            try {
+                const regex = new RegExp(varDef.pattern);
+                if (!regex.test(value)) {
+                    return { ok: false, error: `Does not match pattern ${varDef.pattern}` };
+                }
+            } catch {
+                return { ok: false, error: `Invalid pattern: ${varDef.pattern}` };
+            }
+        }
+        if (varDef.enum && !varDef.enum.includes(value)) {
+            return { ok: false, error: `Not in allowed values: ${varDef.enum.join(', ')}` };
+        }
+    }
+
+    // Number validation
+    if (varDef.type === 'number' && typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            return { ok: false, error: 'Must be a finite number' };
+        }
+        if (varDef.min !== undefined && value < varDef.min) {
+            return { ok: false, error: `Too small (min ${varDef.min})` };
+        }
+        if (varDef.max !== undefined && value > varDef.max) {
+            return { ok: false, error: `Too large (max ${varDef.max})` };
+        }
+    }
+
+    return { ok: true };
+}
+
+/**
+ * Resolve template variables by merging user values with defaults.
+ *
+ * This is a **fail-safe** function:
+ * - Missing values → use default
+ * - Invalid values → use default + warn
+ * - Unknown variables → warn + ignore
+ *
+ * The result is ALWAYS valid and complete (safe to use for rendering).
+ *
+ * @param template - Layout template with variable definitions
+ * @param userValues - Optional user-provided values (can be partial or undefined)
+ * @returns Object with resolved values and any validation warnings
+ *
+ * @example
+ * ```typescript
+ * // User provides partial values
+ * const { values, warnings } = resolveTemplateValues(template, {
+ *   hyresobjektsnummer: '2022-F2009'  // Valid
+ *   // Other vars use defaults
+ * });
+ * // values = { hyresobjektsnummer: '2022-F2009', showLegend: true, scaleDenom: 100 }
+ * // warnings = []
+ *
+ * // User provides invalid value
+ * const { values, warnings } = resolveTemplateValues(template, {
+ *   scaleDenom: 9999  // Out of range (max: 500)
+ * });
+ * // values = { scaleDenom: 100, ... }  ← Fell back to default
+ * // warnings = ["Invalid 'scaleDenom': Too large (max 500) - using default '100'"]
+ *
+ * // Always safe to render
+ * const resolvedTemplate = applyTemplateVariables(template, values);
+ * ```
+ */
+export function resolveTemplateValues(
+    template: LayoutTemplate,
+    userValues?: Record<string, any>
+): { values: Record<string, any>; warnings: string[] } {
+    const defaults = getTemplateDefaults(template);
+    const warnings: string[] = [];
+
+    // Start with all defaults (fail-safe!)
+    const values = { ...defaults };
+
+    // No user values or no variables → return defaults
+    if (!userValues || !template.variables) {
+        return { values, warnings };
+    }
+
+    // Merge and validate user values
+    for (const [name, value] of Object.entries(userValues)) {
+        const varDef = template.variables[name];
+
+        // Unknown variable
+        if (!varDef) {
+            warnings.push(`Unknown variable '${name}' - ignoring`);
+            continue;
+        }
+
+        // Validate value
+        const validation = validateVariable(value, varDef);
+        if (!validation.ok) {
+            warnings.push(`Invalid '${name}': ${validation.error} - using default '${defaults[name]}'`);
+            continue;
+        }
+
+        // Valid → use it
+        values[name] = value;
+    }
+
+    return { values, warnings };
+}
+
+/**
+ * Apply variables to a template by substituting {{vars.*}} references.
+ *
+ * Recursively scans the template and replaces all {{vars.variableName}} references
+ * with the corresponding values from the provided values object.
+ *
+ * Returns a new template with all variables resolved (does not mutate input).
+ *
+ * @param template - Original template with {{vars.*}} references
+ * @param values - Resolved variable values (from resolveTemplateValues)
+ * @returns New template with all {{vars.*}} replaced by actual values
+ *
+ * @example
+ * ```typescript
+ * const template = {
+ *   elements: [
+ *     { kind: 'text', text: 'Hyresobjekt: {{vars.hyresobjektsnummer}}' },
+ *     { kind: 'viewport', clip: { where: { 'BIP.id': '{{vars.hyresobjektsnummer}}' } } }
+ *   ]
+ * };
+ *
+ * const values = { hyresobjektsnummer: '2022-F2009' };
+ * const resolved = applyTemplateVariables(template, values);
+ * // {
+ * //   elements: [
+ * //     { kind: 'text', text: 'Hyresobjekt: 2022-F2009' },
+ * //     { kind: 'viewport', clip: { where: { 'BIP.id': '2022-F2009' } } }
+ * //   ]
+ * // }
+ * ```
+ */
+export function applyTemplateVariables(template: LayoutTemplate, values: Record<string, any>): LayoutTemplate {
+    // Deep clone to avoid mutation
+    const resolved: LayoutTemplate = JSON.parse(JSON.stringify(template));
+
+    // Recursively replace {{vars.*}} in all string values
+    function replaceInValue(obj: any): any {
+        if (typeof obj === 'string') {
+            return interpolateVariables(obj, values);
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(replaceInValue);
+        }
+        if (obj && typeof obj === 'object') {
+            const result: any = {};
+            for (const [key, val] of Object.entries(obj)) {
+                result[key] = replaceInValue(val);
+            }
+            return result;
+        }
+        return obj;
+    }
+
+    // Apply to all template properties that might contain variable references
+    resolved.elements = replaceInValue(resolved.elements);
+    if (resolved.assets) {
+        resolved.assets = replaceInValue(resolved.assets);
+    }
+
+    return resolved;
+}
+
+/**
+ * Interpolate {{vars.*}} references in a string.
+ *
+ * Replaces all occurrences of {{vars.variableName}} with the corresponding value.
+ * If variable is not found, keeps the placeholder and logs a warning.
+ *
+ * @param str - String potentially containing {{vars.*}} references
+ * @param values - Variable values
+ * @returns String with all {{vars.*}} replaced
+ */
+function interpolateVariables(str: string, values: Record<string, any>): string {
+    return str.replace(/\{\{vars\.(\w+)\}\}/g, (match, varName) => {
+        if (varName in values) {
+            const value = values[varName];
+            // Convert to string (handles numbers, booleans, etc.)
+            return String(value);
+        }
+        console.warn(`[templateVariables] Variable '${varName}' not found - keeping placeholder`);
+        return match; // Keep {{vars.varName}} as-is
+    });
+}

package/src/layout/typeGuards.ts

@@ -1,9 +1,9 @@
-/** Type guard: true for plain objects, false for arrays, null, and primitives. */
-export const isRecord = (value: unknown): value is Record<string, unknown> => {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-};
-
-/** Safely read a property from an unknown value. Returns undefined for non-objects. */
-export const getProp = (obj: unknown, key: string): unknown => {
-    return isRecord(obj) ? obj[key] : undefined;
-};
+/** Type guard: true for plain objects, false for arrays, null, and primitives. */
+export const isRecord = (value: unknown): value is Record<string, unknown> => {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+};
+
+/** Safely read a property from an unknown value. Returns undefined for non-objects. */
+export const getProp = (obj: unknown, key: string): unknown => {
+    return isRecord(obj) ? obj[key] : undefined;
+};