@twinfinity/printing 5.0.3-ci.28538-beta

package/src/layout/renderUtils.ts

@@ -0,0 +1,138 @@
+import { isRecord } from './typeGuards';
+
+export const escapeAttr = (value: unknown): string =>
+    String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+export const escapeText = (value: unknown): string =>
+    String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+export const getPathValue = (source: unknown, path: string): unknown => {
+    const parts = path
+        .split('.')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    let current: unknown = source;
+    for (const part of parts) {
+        if (!isRecord(current)) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+};
+
+export const interpolate = (template: string, data: any, warnings?: string[]): string =>
+    template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (match, path) => {
+        const value = getPathValue(data, path);
+        if (value === undefined || value === null) {
+            if (warnings) {
+                warnings.push(`Unresolved template variable '${path}' in "${template}".`);
+            }
+            return '';
+        }
+        if (typeof value === 'object') {
+            if (warnings) {
+                warnings.push(
+                    `Template variable '${path}' resolved to an object instead of a string in "${template}".`
+                );
+            }
+            return '';
+        }
+        return String(value);
+    });
+
+export const interpolateWithSources = (template: string, sources: any[]): string =>
+    template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, path) => {
+        for (const source of sources) {
+            const value = getPathValue(source, path);
+            if (value !== undefined && value !== null && typeof value !== 'object') {
+                return String(value);
+            }
+        }
+        return '';
+    });
+
+// colorFromString moved to utils.ts to avoid duplication
+// Import from utils.ts if needed: import { colorFromString } from './utils';
+
+/**
+ * Resolve a short property path from an item's propertySets.
+ *
+ * Template paths use the format: SetName.propertyName
+ * Example: "SetName.propName" resolves to item.propertySets.SetName.propName.value
+ *
+ * @param item - An object with propertySets structure
+ * @param shortPath - Short path like "SetName.propName"
+ * @returns The property value, or undefined if not found
+ */
+export const resolveProperty = (item: unknown, shortPath: string): unknown => {
+    if (!shortPath || !isRecord(item)) return undefined;
+
+    const propertySets = (item as Record<string, unknown>).propertySets;
+    if (!isRecord(propertySets)) return undefined;
+
+    const parts = shortPath.split('.');
+    if (parts.length < 2) return undefined;
+
+    const [setName, ...propParts] = parts;
+    const propName = propParts.join('.');
+
+    const propSet = propertySets[setName];
+    if (!isRecord(propSet)) return undefined;
+
+    // New T8 API: T8PropertySet has .properties sub-record
+    const innerProps = propSet['properties'];
+    const prop = (isRecord(innerProps) ? innerProps[propName] : undefined) ?? propSet[propName];
+
+    // Handle both wrapped {value} and raw values
+    if (isRecord(prop) && 'value' in prop) {
+        return prop.value;
+    }
+    return prop;
+};
+
+/**
+ * Resolve a property value using either short or full path.
+ * Short path: "SetName.propName" → resolves via propertySets
+ * Full path: "propertySets.SetName.propName.value" → resolves via direct traversal
+ * Also handles top-level properties like "color".
+ */
+export const resolvePath = (obj: unknown, path: string): unknown => {
+    if (path.startsWith('propertySets.')) {
+        return getPathValue(obj, path);
+    }
+    const direct = getPathValue(obj, path);
+    if (direct !== undefined) return direct;
+    return resolveProperty(obj, path);
+};
+
+/**
+ * Check if an item matches a filter condition using short property paths.
+ *
+ * @param item - An object with propertySets structure
+ * @param filter - Filter with path (short format), equals, or in conditions
+ * @returns true if item matches the filter
+ */
+export const matchesPropertyFilter = (
+    item: unknown,
+    filter: { path?: string; equals?: unknown; in?: unknown[] } | undefined
+): boolean => {
+    if (!filter || !filter.path) return true;
+
+    const value = resolveProperty(item, filter.path);
+    const normalizedValue = typeof value === 'string' ? value.toLowerCase().trim() : value;
+
+    if (filter.equals !== undefined) {
+        const normalizedEquals = typeof filter.equals === 'string' ? filter.equals.toLowerCase().trim() : filter.equals;
+        return normalizedValue === normalizedEquals;
+    }
+
+    if (Array.isArray(filter.in)) {
+        return filter.in.some((v) => {
+            const normalizedV = typeof v === 'string' ? v.toLowerCase().trim() : v;
+            return normalizedValue === normalizedV;
+        });
+    }
+
+    return true;
+};

package/src/layout/sectionValidation.ts

@@ -0,0 +1,2 @@
+export { validateSectionState } from '@twinfinity/geometry';
+export type { SectionStateValidationResult } from '@twinfinity/geometry';

package/src/layout/templateVariables.ts

@@ -0,0 +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
+    });
+}

package/src/layout/typeGuards.ts

@@ -0,0 +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;
+};