@twinfinity/printing 6.1.0-beta → 6.1.2-ci.30738-beta

package/src/layout/renderLayout.ts

@@ -0,0 +1,483 @@
+import { renderViewportElement } from './viewportRender';
+import { prepareViewports } from './viewportPrep';
+import { renderLabels, ViewportRenderInfo } from './labelsRender';
+import { renderQrElements } from './qrRender';
+import { applyLegendFilter, buildLegendGroup, type LegendColorAssignment, type LegendResult } from './legendRender';
+import { RenderLayoutOptions } from './options';
+import { resolvePresets } from './presets';
+import { resolveIncludeClasses } from './metadata';
+import { pushWarning } from './warnings';
+import { escapeAttr, escapeText, interpolate, getPathValue, formatNumber } from './renderUtils';
+import { uniquePositiveDenoms } from './utils';
+import { validateLayoutTemplate } from './validation';
+import { validateLayoutData } from './preflight';
+import {
+    ELEMENT_KIND_VIEWPORT,
+    ELEMENT_KIND_TEXT,
+    ELEMENT_KIND_IMAGE,
+    ELEMENT_KIND_LINE,
+    ELEMENT_KIND_RECT,
+    ELEMENT_KIND_CIRCLE,
+    ELEMENT_KIND_POLYLINE,
+    ELEMENT_KIND_POLYGON,
+    ELEMENT_KIND_SCALE_BAR,
+    ELEMENT_KIND_QR,
+    ELEMENT_KIND_LABELS,
+    ELEMENT_KIND_LEGEND,
+    ELEMENT_KIND_GROUP
+} from './elementKinds';
+import {
+    ResourceSpec,
+    LayoutElement,
+    ViewportElement,
+    TextElement,
+    ImageElement,
+    LineElement,
+    RectElement,
+    CircleElement,
+    PolylineElement,
+    PolygonElement,
+    ScaleBarElement,
+    QrElement,
+    LabelsElement,
+    LegendElement,
+    GroupElement,
+    LayoutTemplate,
+    ModelContext,
+    LayoutData,
+    ValidationIssue,
+    ComputedViewportScale
+} from './types';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** Result of {@link renderLayout}: the final SVG markup, per-viewport scale info, and any warnings. */
+export interface RenderLayoutResult {
+    /** Complete SVG markup string ready for embedding or PDF conversion. */
+    svg: string;
+    /** Per-viewport computed scale information (denominator, mm-per-model-unit, fit status). */
+    viewportScales: Record<string, ComputedViewportScale>;
+    /** Non-fatal issues encountered during rendering (missing resources, unresolved styles, etc.). */
+    warnings: string[];
+}
+
+const dashArray = (dash?: string): string => (dash ? ` stroke-dasharray="${escapeAttr(dash)}"` : '');
+
+/**
+ * Render a layout template to SVG.
+ *
+ * This is the low-level rendering function. For most use cases, prefer {@link renderDrawing}
+ * which handles all data wiring automatically.
+ *
+ * @param template - Validated layout template (page, elements, styles, presets).
+ * @param data - Layout data with viewport items, template variables, and legend rows.
+ * @param models - Per-viewport SVG model views (geometry + transforms).
+ * @param options - Optional rendering settings (remote resources, scale overrides, metadata).
+ * @returns SVG markup string, computed viewport scales, and any warnings.
+ */
+export async function renderLayout(
+    template: LayoutTemplate,
+    data: LayoutData,
+    models: ModelContext,
+    options?: RenderLayoutOptions
+): Promise<RenderLayoutResult> {
+    const presets = resolvePresets(template?.presets);
+
+    const validation = validateLayoutTemplate(template, {
+        allowRemoteResources: options?.allowRemoteResources,
+        allowDataUrls: options?.allowDataUrls,
+        maxViewports: options?.maxViewports
+    });
+    if (!validation.ok) {
+        throw new Error(
+            `Template validation failed: ${validation.errors.map((e: ValidationIssue) => `${e.path}: ${e.message}`).join('; ')}`
+        );
+    }
+
+    const preferredScales = uniquePositiveDenoms(options?.scaleDenominators);
+    const page = template.page;
+    const warnings: string[] = [];
+
+    // Flatten all elements to collect viewports, qrs, labels, legends regardless of grouping
+    const allElements: LayoutElement[] = [];
+    const collectElements = (elements: LayoutElement[]): void => {
+        elements.forEach((el) => {
+            allElements.push(el);
+            if (el.kind === ELEMENT_KIND_GROUP) {
+                collectElements((el as GroupElement).children);
+            }
+        });
+    };
+    collectElements(template.elements);
+
+    const viewports = allElements.filter((el) => el.kind === ELEMENT_KIND_VIEWPORT) as ViewportElement[];
+
+    const dataValidation = validateLayoutData(
+        data,
+        viewports.map((v) => v.id)
+    );
+    if (!dataValidation.ok) {
+        throw new Error(`Layout data validation failed: ${dataValidation.errors.join('; ')}`);
+    }
+
+    const {
+        viewportScales,
+        viewportClipPolygonsLocal,
+        viewportClipPolygonsWorld,
+        viewportClipBounds,
+        viewportClipLabels,
+        viewportClipStyles,
+        // viewportClipWhere intentionally omitted — not needed for rendering
+        viewportHighlight,
+        filteredModelsByViewport
+    } = prepareViewports(viewports, models, data, preferredScales, presets, {
+        metadataById: options?.metadataById,
+        warnings
+    });
+
+    const viewportData: Record<
+        string,
+        {
+            scaleDenom: number;
+            scaleText: string;
+            mmPerModelUnit: number;
+            fits: boolean;
+        }
+    > = {};
+
+    Object.entries(viewportScales).forEach(([id, scale]) => {
+        viewportData[id] = {
+            scaleDenom: scale.denom,
+            scaleText: `1:${scale.denom}`,
+            mmPerModelUnit: scale.mmPerModelUnit,
+            fits: scale.fits
+        };
+    });
+
+    const dataWithViewport = { ...data, viewport: viewportData };
+
+    const sorted = [...template.elements].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
+
+    const parts: string[] = [];
+    parts.push(
+        `<svg xmlns="${SVG_NS}" width="${page.widthMm}mm" height="${page.heightMm}mm" viewBox="0 0 ${page.widthMm} ${page.heightMm}">`
+    );
+
+    if (page.backgroundColor) {
+        parts.push(
+            `<rect x="0" y="0" width="${page.widthMm}" height="${page.heightMm}" fill="${escapeAttr(page.backgroundColor)}"/>`
+        );
+    }
+
+    const resourceMap = new Map<string, ResourceSpec>();
+    (template.resources ?? []).forEach((resource) => resourceMap.set(resource.id, resource));
+
+    const qrElements = allElements.filter((el) => el.kind === ELEMENT_KIND_QR) as QrElement[];
+    const labelElements = allElements.filter((el) => el.kind === ELEMENT_KIND_LABELS) as LabelsElement[];
+    const viewportRenderInfo: Record<string, ViewportRenderInfo> = {};
+
+    // Compute every legend ONCE, before viewport rendering: fill: "legend"
+    // needs the color assignments first, and the drawn legend must be built
+    // from the exact same rows — computing twice is how fill colors drift
+    // from the legend swatches. applyLegendFilter works in world space, so no
+    // render-time state is needed here. Results are keyed by element
+    // reference (immune to duplicate ids) and reused by the render pass.
+    const legendColorMaps = new Map<string, LegendColorAssignment>(); // viewport ID -> color assignment
+    const legendResults = new Map<LegendElement, LegendResult | null>();
+    const legendElements = allElements.filter((el) => el.kind === ELEMENT_KIND_LEGEND) as LegendElement[];
+    legendElements.forEach((legend) => {
+        const legendItems = getPathValue(data, `viewports.${legend.viewport}.items`);
+        const rawLegendItems = Array.isArray(legendItems) ? legendItems : [];
+        const legendDataFiltered = applyLegendFilter(rawLegendItems, legend, viewportClipPolygonsWorld);
+        if (!legendDataFiltered.length) {
+            if (!rawLegendItems.length) {
+                pushWarning(warnings, `Legend '${legend.id}' has no items from viewport '${legend.viewport}'.`);
+            } else {
+                pushWarning(
+                    warnings,
+                    `Legend '${legend.id}' filter matched 0 of ${rawLegendItems.length} items (class=${JSON.stringify(legend.class)}, where=${JSON.stringify(legend.where)}).`
+                );
+            }
+        }
+        const vpEl = viewports.find((v) => v.id === legend.viewport);
+        // Swatch opacity mirrors the fill rule the legend actually drives
+        // (fill: "legend"), falling back to the first fill rule.
+        const fillRule = vpEl?.fills?.find((f) => f.fill === 'legend') ?? vpEl?.fills?.[0];
+        const fillOpacity = fillRule ? (fillRule.fillOpacity ?? 0.35) : undefined;
+        const result = buildLegendGroup(legend, template.styles, page, page.marginMm, legendDataFiltered, fillOpacity);
+        legendResults.set(legend, result);
+        if (result?.colors) {
+            if (legendColorMaps.has(legend.viewport)) {
+                pushWarning(
+                    warnings,
+                    `Multiple legends with assignColors target viewport '${legend.viewport}' — fill: "legend" uses the last one.`
+                );
+            }
+            legendColorMaps.set(legend.viewport, result.colors);
+        }
+    });
+
+    const renderElement = (el: LayoutElement): void => {
+        if (el.kind === ELEMENT_KIND_RECT) {
+            const r = el as RectElement;
+            parts.push(
+                `<rect x="${r.xMm}" y="${r.yMm}" width="${r.widthMm}" height="${r.heightMm}"` +
+                    (r.stroke ? ` stroke="${escapeAttr(r.stroke)}"` : '') +
+                    (r.strokeWidthMm ? ` stroke-width="${r.strokeWidthMm}"` : '') +
+                    (r.fill ? ` fill="${escapeAttr(r.fill)}"` : ' fill="none"') +
+                    dashArray(r.dash) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_LINE) {
+            const l = el as LineElement;
+            parts.push(
+                `<line x1="${l.x1Mm}" y1="${l.y1Mm}" x2="${l.x2Mm}" y2="${l.y2Mm}"` +
+                    (l.stroke ? ` stroke="${escapeAttr(l.stroke)}"` : '') +
+                    (l.strokeWidthMm ? ` stroke-width="${l.strokeWidthMm}"` : '') +
+                    dashArray(l.dash) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_CIRCLE) {
+            const c = el as CircleElement;
+            parts.push(
+                `<circle cx="${c.cxMm}" cy="${c.cyMm}" r="${c.rMm}"` +
+                    (c.stroke ? ` stroke="${escapeAttr(c.stroke)}"` : '') +
+                    (c.strokeWidthMm ? ` stroke-width="${c.strokeWidthMm}"` : '') +
+                    (c.fill ? ` fill="${escapeAttr(c.fill)}"` : ' fill="none"') +
+                    dashArray(c.dash) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_POLYLINE) {
+            const pl = el as PolylineElement;
+            const pointsStr = pl.points.map((p) => `${formatNumber(p.xMm)},${formatNumber(p.yMm)}`).join(' ');
+            parts.push(
+                `<polyline points="${pointsStr}" stroke="${escapeAttr(pl.stroke)}" stroke-width="${pl.strokeWidthMm}" fill="none"${dashArray(pl.dash)} />`
+            );
+        } else if (el.kind === ELEMENT_KIND_POLYGON) {
+            const pg = el as PolygonElement;
+            const pointsStr = pg.points.map((p) => `${formatNumber(p.xMm)},${formatNumber(p.yMm)}`).join(' ');
+            parts.push(
+                `<polygon points="${pointsStr}"` +
+                    (pg.stroke ? ` stroke="${escapeAttr(pg.stroke)}"` : '') +
+                    (pg.strokeWidthMm ? ` stroke-width="${pg.strokeWidthMm}"` : '') +
+                    (pg.fill ? ` fill="${escapeAttr(pg.fill)}"` : ' fill="none"') +
+                    dashArray(pg.dash) +
+                    ` />`
+            );
+        } else if (el.kind === ELEMENT_KIND_TEXT) {
+            const tEl = el as TextElement;
+            const styleName = tEl.textStyle;
+            const style = styleName ? template.styles?.[styleName] : undefined;
+            if (!style) {
+                pushWarning(warnings, `Missing text style '${styleName ?? '(none)'}' for element '${tEl.id}'.`);
+                return;
+            }
+            const text = interpolate(tEl.text, dataWithViewport, warnings);
+            const anchor = tEl.align === 'center' ? 'middle' : tEl.align === 'right' ? 'end' : 'start';
+            parts.push(
+                `<text x="${tEl.xMm}" y="${tEl.yMm}" font-family="${escapeAttr(style.fontFamily)}" font-size="${style.fontSizeMm}"` +
+                    (style.fontWeight ? ` font-weight="${escapeAttr(style.fontWeight)}"` : '') +
+                    (style.color ? ` fill="${escapeAttr(style.color)}"` : '') +
+                    // Escaped, not type-narrowed: validation only checks fontFamily and fontSizeMm,
+                    // and these attributes legitimately accept a length with units ("0.5mm"), so
+                    // forcing them to numbers would reject valid templates. Unescaped, a value of
+                    // `0" onload="…` closed the attribute and injected a handler.
+                    (style.letterSpacingMm !== undefined
+                        ? ` letter-spacing="${escapeAttr(style.letterSpacingMm)}"`
+                        : '') +
+                    (style.lineHeightMm !== undefined ? ` line-height="${escapeAttr(style.lineHeightMm)}"` : '') +
+                    ` text-anchor="${anchor}">${escapeText(text)}</text>`
+            );
+        } else if (el.kind === ELEMENT_KIND_IMAGE) {
+            const img = el as ImageElement;
+            const resource = resourceMap.get(img.resourceId);
+            if (!resource) {
+                pushWarning(warnings, `Missing resource '${img.resourceId}' for image '${img.id}'.`);
+                return;
+            }
+            if (resource.src) {
+                parts.push(
+                    `<image href="${escapeAttr(resource.src)}" x="${img.xMm}" y="${img.yMm}" width="${img.widthMm}" height="${img.heightMm}"` +
+                        (img.fit === 'cover'
+                            ? ' preserveAspectRatio="xMidYMid slice"'
+                            : img.fit === 'stretch'
+                              ? ' preserveAspectRatio="none"'
+                              : ' preserveAspectRatio="xMidYMid meet"') +
+                        ` />`
+                );
+            } else if (resource.content) {
+                parts.push(
+                    `<g transform="translate(${img.xMm} ${img.yMm}) scale(${img.widthMm} ${img.heightMm})">${resource.content}</g>`
+                );
+            }
+        } else if (el.kind === ELEMENT_KIND_SCALE_BAR) {
+            const sb = el as ScaleBarElement;
+            // Scale bar declares which viewport it binds to via `viewport`
+            const boundViewport = sb.viewport ?? viewports[0]?.id ?? null;
+            if (!boundViewport) {
+                pushWarning(warnings, `Scale bar '${sb.id}' is not bound to a viewport.`);
+                return;
+            }
+            const scaleInfo = viewportScales[boundViewport];
+            if (!scaleInfo) {
+                pushWarning(warnings, `Viewport '${boundViewport}' missing scale info for scale bar '${sb.id}'.`);
+                return;
+            }
+            const lengthMm = sb.maxLengthMm;
+            const segments = sb.segments ?? 10;
+            const segmentMm = lengthMm / segments;
+            const metersPerMm = 1 / scaleInfo.mmPerModelUnit;
+            const segmentMeters = segmentMm * metersPerMm;
+            const labelsEvery = Math.max(1, sb.labelEvery ?? 2);
+            const unitSuffix = sb.unit ? ` ${sb.unit}` : ' m';
+            const barParts: string[] = [];
+            const sbStroke = sb.stroke ?? '#000';
+            const sbStrokeWidth = sb.strokeWidthMm ?? 0.25;
+
+            for (let i = 0; i <= segments; i++) {
+                const x = sb.xMm + segmentMm * i;
+                const isLabel = i % labelsEvery === 0;
+                const height = isLabel ? 4 : 3;
+                barParts.push(
+                    `<line x1="${x}" y1="${sb.yMm}" x2="${x}" y2="${sb.yMm - height}" stroke="${escapeAttr(
+                        sbStroke
+                    )}" stroke-width="${sbStrokeWidth}" />`
+                );
+                if (isLabel && sb.textStyle) {
+                    const style = template.styles?.[sb.textStyle];
+                    if (style) {
+                        const labelValue = (segmentMeters * i).toFixed(2).replace(/\.?0+$/, '');
+                        barParts.push(
+                            `<text x="${x}" y="${sb.yMm + style.fontSizeMm + 1}" font-family="${escapeAttr(
+                                style.fontFamily
+                            )}" font-size="${style.fontSizeMm}" text-anchor="middle">${escapeText(labelValue + unitSuffix)}</text>`
+                        );
+                    }
+                }
+            }
+
+            barParts.push(
+                `<line x1="${sb.xMm}" y1="${sb.yMm}" x2="${sb.xMm + lengthMm}" y2="${sb.yMm}" stroke="${escapeAttr(
+                    sbStroke
+                )}" stroke-width="${sbStrokeWidth}" />`
+            );
+
+            parts.push(barParts.join(''));
+        } else if (el.kind === ELEMENT_KIND_VIEWPORT) {
+            const vp = el as ViewportElement;
+            const model = filteredModelsByViewport[vp.id] ?? models[vp.id] ?? null;
+            if (!model) {
+                pushWarning(warnings, `Viewport '${vp.id}' missing model.`);
+            }
+            // Resolved once per viewport: the same includeClasses (incl. presets) that
+            // filters the line paths also gates generic fill rules in the renderer.
+            const vpIncludeFilters = resolveIncludeClasses(vp.includeClasses as unknown, presets.includeClasses ?? {});
+            const vpParts = renderViewportElement(
+                vp,
+                model,
+                dataWithViewport,
+                preferredScales,
+                presets.scales,
+                resourceMap,
+                viewportScales,
+                viewportClipPolygonsLocal,
+                viewportClipBounds,
+                viewportClipLabels,
+                viewportClipStyles,
+                viewportHighlight,
+                viewportRenderInfo,
+                warnings,
+                legendColorMaps,
+                undefined,
+                vpIncludeFilters
+            );
+            parts.push(...vpParts);
+        } else if (el.kind === ELEMENT_KIND_LEGEND) {
+            // Computed once in the pre-pass (same rows as the color maps).
+            const legendResult = legendResults.get(el as LegendElement);
+            if (legendResult) {
+                parts.push(legendResult.svg);
+            }
+        } else if (el.kind === ELEMENT_KIND_GROUP) {
+            const grp = el as GroupElement;
+            const children = Array.isArray(grp.children) ? grp.children : [];
+            if (!children.length) return;
+
+            const t = grp.transform;
+            const transforms: string[] = [];
+            if (t?.translateXMm || t?.translateYMm) {
+                transforms.push(`translate(${t.translateXMm ?? 0} ${t.translateYMm ?? 0})`);
+            }
+            if (t?.rotateDeg) transforms.push(`rotate(${t.rotateDeg})`);
+            if (t?.scaleX !== undefined || t?.scaleY !== undefined) {
+                transforms.push(`scale(${t.scaleX ?? 1} ${t.scaleY ?? 1})`);
+            }
+
+            let clipRef = '';
+            if (grp.clip && grp.clip.type === 'rect') {
+                // grp.id is template-authored and lands in both id="..." and url(#...); a quote in it
+                // would close the attribute and let the rest inject arbitrary ones. Every other
+                // template value in this function is escaped the same way.
+                const clipId = escapeAttr(`group-clip-${grp.id}-${parts.length}`);
+                parts.push(
+                    `<defs><clipPath id="${clipId}"><rect x="${grp.clip.xMm}" y="${grp.clip.yMm}" width="${grp.clip.widthMm}" height="${grp.clip.heightMm}" /></clipPath></defs>`
+                );
+                clipRef = ` clip-path="url(#${clipId})"`;
+            }
+
+            parts.push(
+                `<g${transforms.length ? ` transform="${transforms.join(' ')}"` : ''}` +
+                    (grp.opacity !== undefined ? ` opacity="${grp.opacity}"` : '') +
+                    clipRef +
+                    `>`
+            );
+            // Labels and QR are data-driven overlays rendered globally after
+            // the element pass (they need viewport render info / async QR
+            // encoding) — group transform/opacity/clip do not apply to them.
+            if (children.some((c) => c.kind === ELEMENT_KIND_LABELS || c.kind === ELEMENT_KIND_QR)) {
+                pushWarning(
+                    warnings,
+                    `Group '${grp.id}' contains labels/qr children — these render as page-level overlays; the group's transform/opacity/clip do not apply to them.`
+                );
+            }
+            [...children]
+                .filter((c) => c.kind !== ELEMENT_KIND_LABELS && c.kind !== ELEMENT_KIND_QR)
+                .sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0))
+                .forEach(renderElement);
+            parts.push('</g>');
+        }
+    };
+    sorted.forEach(renderElement);
+
+    if (labelElements.length) {
+        const labelParts = renderLabels(
+            labelElements,
+            data,
+            viewportRenderInfo,
+            viewportClipLabels,
+            viewportClipPolygonsLocal,
+            viewportClipPolygonsWorld,
+            template.styles ?? {},
+            dataWithViewport,
+            warnings
+        );
+        parts.push(...labelParts);
+    }
+
+    if (qrElements.length) {
+        const qrParts = await renderQrElements(
+            qrElements,
+            viewports,
+            viewportScales,
+            models,
+            { qrContext: options?.qrContext },
+            dataWithViewport,
+            warnings
+        );
+        parts.push(...qrParts);
+    }
+
+    parts.push('</svg>');
+
+    return { svg: parts.join(''), viewportScales, warnings };
+}