@zentto/report-core 0.4.0 → 1.0.0

package/dist/engine/multi-pass-engine.js

@@ -0,0 +1,1082 @@
+// @zentto/report-core — 3-pass rendering engine (Crystal Reports model)
+//
+// Pass 1 (WhileReadingRecords): Sort, group, compute all aggregates
+// Pass 2 (WhilePrintingRecords): Running totals, print-time expressions, conditional formatting
+// Pass 3 (TotalPageCount): Calculate total pages, back-fill "Page N of M"
+import { processLayout, toPx } from './band-engine.js';
+import { resolveElementValue, formatValue, } from './data-binding.js';
+/**
+ * Compute an extended aggregate over a set of numeric values extracted from rows.
+ * Supports: sum, avg, count, min, max, median, stddev, variance, distinctcount.
+ */
+function computeExtendedAggregate(rows, field, fn) {
+    // For count and distinctcount we consider all values, not just numeric
+    if (fn === 'count')
+        return rows.length;
+    if (fn === 'distinctcount') {
+        const seen = new Set();
+        for (const row of rows) {
+            seen.add(row[field]);
+        }
+        return seen.size;
+    }
+    const values = rows
+        .map(r => r[field])
+        .filter((v) => typeof v === 'number');
+    if (values.length === 0)
+        return 0;
+    switch (fn) {
+        case 'sum':
+            return kahanSum(values);
+        case 'avg':
+            return kahanSum(values) / values.length;
+        case 'min':
+            return Math.min(...values);
+        case 'max':
+            return Math.max(...values);
+        case 'median':
+            return computeMedian(values);
+        case 'stddev':
+            return computeStdDev(values);
+        case 'variance':
+            return computeVariance(values);
+        default:
+            return 0;
+    }
+}
+/** Kahan compensated summation for numerical stability */
+function kahanSum(values) {
+    let sum = 0;
+    let compensation = 0;
+    for (const v of values) {
+        const y = v - compensation;
+        const t = sum + y;
+        compensation = (t - sum) - y;
+        sum = t;
+    }
+    return sum;
+}
+function computeMedian(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return (sorted[mid - 1] + sorted[mid]) / 2;
+    }
+    return sorted[mid];
+}
+function computeVariance(values) {
+    if (values.length < 2)
+        return 0;
+    const mean = kahanSum(values) / values.length;
+    const squaredDiffs = values.map(v => (v - mean) ** 2);
+    // Population variance (N), consistent with Crystal Reports DistinctCount behavior
+    return kahanSum(squaredDiffs) / values.length;
+}
+function computeStdDev(values) {
+    return Math.sqrt(computeVariance(values));
+}
+// ─── Sorting helpers ────────────────────────────────────────────────
+function sortRows(rows, layout) {
+    const result = [...rows];
+    // Apply group sorting first (outermost sort), then explicit sorting
+    const sortDefs = [];
+    if (layout.groups) {
+        for (const g of layout.groups) {
+            sortDefs.push({ field: g.field, direction: g.sort || 'asc' });
+        }
+    }
+    if (layout.sorting) {
+        for (const s of layout.sorting) {
+            // Skip if already added by group
+            if (!sortDefs.some(sd => sd.field === s.field)) {
+                sortDefs.push(s);
+            }
+        }
+    }
+    if (sortDefs.length === 0)
+        return result;
+    result.sort((a, b) => {
+        for (const sd of sortDefs) {
+            const aVal = a[sd.field];
+            const bVal = b[sd.field];
+            if (aVal === bVal)
+                continue;
+            if (aVal == null)
+                return 1;
+            if (bVal == null)
+                return -1;
+            const cmp = aVal < bVal ? -1 : 1;
+            return sd.direction === 'desc' ? -cmp : cmp;
+        }
+        return 0;
+    });
+    return result;
+}
+/** Group rows by field, preserving the order of first occurrence */
+function groupByField(rows, field) {
+    const groups = new Map();
+    for (const row of rows) {
+        const key = String(row[field] ?? '');
+        let group = groups.get(key);
+        if (!group) {
+            group = [];
+            groups.set(key, group);
+        }
+        group.push(row);
+    }
+    return groups;
+}
+/** Build nested group structure for multi-level grouping */
+function buildGroupHierarchy(rows, groups, level = 0) {
+    if (level >= groups.length) {
+        return new Map([['__all__', rows]]);
+    }
+    const field = groups[level].field;
+    const topGroups = groupByField(rows, field);
+    // If there are deeper levels, recurse into each group
+    if (level < groups.length - 1) {
+        for (const [key, groupRows] of topGroups) {
+            // Recursion would create sub-groups, but we store flat at each level
+            // The aggregates map uses composite keys for nested groups
+            buildGroupHierarchy(groupRows, groups, level + 1);
+        }
+    }
+    return topGroups;
+}
+// ─── Aggregate key helpers ──────────────────────────────────────────
+function makeAggKey(field, fn) {
+    return `${field}:${fn}`;
+}
+const ALL_AGG_FUNCTIONS = [
+    'sum', 'avg', 'count', 'min', 'max', 'median', 'stddev', 'variance', 'distinctcount',
+];
+/**
+ * Collect all fields that have aggregates defined on them in the layout.
+ * Returns a set of field names that need aggregate computation.
+ */
+function collectAggregateFields(layout) {
+    const fields = new Set();
+    for (const band of layout.bands) {
+        for (const element of band.elements) {
+            if (element.type === 'field') {
+                const fe = element;
+                if (fe.aggregate) {
+                    fields.add(fe.field);
+                }
+            }
+        }
+    }
+    // Also collect from running totals
+    if (layout.runningTotals) {
+        for (const rt of layout.runningTotals) {
+            fields.add(rt.field);
+        }
+    }
+    return fields;
+}
+/** Get numeric fields from a row for auto-aggregate computation */
+function collectNumericFields(rows) {
+    if (rows.length === 0)
+        return [];
+    const fields = new Set();
+    for (const row of rows) {
+        for (const [key, val] of Object.entries(row)) {
+            if (typeof val === 'number') {
+                fields.add(key);
+            }
+        }
+    }
+    return [...fields];
+}
+// ─── Pass 1: WhileReadingRecords ────────────────────────────────────
+/**
+ * Pass 1 reads all data, sorts and groups it, and pre-computes every
+ * aggregate that the report might need. This is equivalent to Crystal
+ * Reports' "WhileReadingRecords" phase.
+ */
+export function executePass1(layout, dataSets) {
+    const ctx = {
+        aggregates: new Map(),
+        groupTotals: new Map(),
+        sortedData: new Map(),
+        grandTotals: new Map(),
+        runningTotals: new Map(),
+        printState: {
+            recordNumber: 0,
+            groupNumber: 0,
+            pageNumber: 0,
+            totalPages: 0,
+            isFirstRecord: true,
+            isLastRecord: false,
+            previousValues: new Map(),
+            nextValues: new Map(),
+        },
+        conditionalFormats: new Map(),
+        suppressedElements: new Set(),
+        subreportResults: new Map(),
+        totalPages: 0,
+        pageContent: [],
+    };
+    // Process each data source
+    for (const dsDef of layout.dataSources) {
+        const rawData = dataSets[dsDef.id];
+        if (!rawData || !Array.isArray(rawData))
+            continue;
+        // Sort data according to groups + explicit sorting
+        const sorted = sortRows(rawData, layout);
+        ctx.sortedData.set(dsDef.id, sorted);
+        // Determine which fields need aggregates
+        const explicitFields = collectAggregateFields(layout);
+        const numericFields = collectNumericFields(sorted);
+        const allAggFields = new Set([...explicitFields, ...numericFields]);
+        // ── Grand totals (report-level aggregates) ──
+        for (const field of allAggFields) {
+            for (const fn of ALL_AGG_FUNCTIONS) {
+                const key = makeAggKey(field, fn);
+                ctx.grandTotals.set(key, computeExtendedAggregate(sorted, field, fn));
+            }
+        }
+        // ── Group-level aggregates ──
+        if (layout.groups && layout.groups.length > 0) {
+            for (const groupDef of layout.groups) {
+                const grouped = groupByField(sorted, groupDef.field);
+                // Store group rows for later use
+                const groupEntries = [];
+                const groupAggs = new Map();
+                for (const [groupKey, groupRows] of grouped) {
+                    const fieldAggs = new Map();
+                    for (const field of allAggFields) {
+                        for (const fn of ALL_AGG_FUNCTIONS) {
+                            const aggKey = makeAggKey(field, fn);
+                            fieldAggs.set(aggKey, computeExtendedAggregate(groupRows, field, fn));
+                        }
+                    }
+                    groupAggs.set(groupKey, fieldAggs);
+                    // Build a summary record for this group
+                    const summary = { __count: groupRows.length };
+                    for (const [aggKey, val] of fieldAggs) {
+                        summary[aggKey] = val;
+                    }
+                    groupEntries.push(summary);
+                }
+                // Store in context
+                ctx.groupTotals.set(groupDef.field, groupEntries);
+                // Merge group aggregates into the main aggregates map
+                for (const [groupKey, fieldAggs] of groupAggs) {
+                    const compositeKey = `${groupDef.field}::${groupKey}`;
+                    ctx.aggregates.set(compositeKey, fieldAggs);
+                }
+            }
+            // Handle nested groups: compute aggregates for composite group keys
+            if (layout.groups.length > 1) {
+                computeNestedGroupAggregates(sorted, layout.groups, allAggFields, ctx);
+            }
+        }
+    }
+    // Initialize running totals to zero
+    if (layout.runningTotals) {
+        for (const rt of layout.runningTotals) {
+            ctx.runningTotals.set(rt.id, 0);
+        }
+    }
+    return ctx;
+}
+/**
+ * For multi-level grouping, compute aggregates at each nesting level
+ * using composite keys like "region::West|city::Seattle"
+ */
+function computeNestedGroupAggregates(rows, groups, fields, ctx) {
+    // Build composite groups by iterating through sorted data
+    // Track group keys at each level
+    const levelKeys = groups.map(() => []);
+    // Group at level 0
+    const level0Groups = groupByField(rows, groups[0].field);
+    for (const [key0, rows0] of level0Groups) {
+        levelKeys[0].push(key0);
+        if (groups.length > 1) {
+            const level1Groups = groupByField(rows0, groups[1].field);
+            for (const [key1, rows1] of level1Groups) {
+                // Composite key for level 0+1
+                const compositeKey = `${groups[0].field}::${key0}|${groups[1].field}::${key1}`;
+                const fieldAggs = new Map();
+                for (const field of fields) {
+                    for (const fn of ALL_AGG_FUNCTIONS) {
+                        const aggKey = makeAggKey(field, fn);
+                        fieldAggs.set(aggKey, computeExtendedAggregate(rows1, field, fn));
+                    }
+                }
+                ctx.aggregates.set(compositeKey, fieldAggs);
+                // Continue nesting if needed (up to 3 levels deep for practical reports)
+                if (groups.length > 2) {
+                    const level2Groups = groupByField(rows1, groups[2].field);
+                    for (const [key2, rows2] of level2Groups) {
+                        const deepKey = `${compositeKey}|${groups[2].field}::${key2}`;
+                        const deepAggs = new Map();
+                        for (const field of fields) {
+                            for (const fn of ALL_AGG_FUNCTIONS) {
+                                const aggKey = makeAggKey(field, fn);
+                                deepAggs.set(aggKey, computeExtendedAggregate(rows2, field, fn));
+                            }
+                        }
+                        ctx.aggregates.set(deepKey, deepAggs);
+                    }
+                }
+            }
+        }
+    }
+}
+// ─── Pass 2: WhilePrintingRecords ───────────────────────────────────
+/**
+ * Pass 2 processes the report as it would be printed: running totals
+ * accumulate, print-time expressions are evaluated, conditional
+ * formatting is resolved, and subreports are executed.
+ */
+export function executePass2(layout, dataSets, ctx, options) {
+    // Run the band engine to get page layout
+    const pages = processLayout(layout, dataSets, options);
+    ctx.pageContent = pages;
+    const printState = ctx.printState;
+    printState.pageNumber = 1;
+    printState.recordNumber = 0;
+    printState.groupNumber = 0;
+    // Flatten all detail rows from pages for running total processing
+    const allDetailBands = [];
+    for (const page of pages) {
+        for (const rb of page.bands) {
+            if (rb.band.type === 'detail') {
+                allDetailBands.push(rb);
+            }
+        }
+    }
+    const totalRecords = allDetailBands.length;
+    // Track previous group values for group-change detection
+    const lastGroupValues = new Map();
+    // ── Process each page ──
+    for (const page of pages) {
+        printState.pageNumber = page.pageNumber;
+        for (const rb of page.bands) {
+            // Process detail bands for running totals and print-time state
+            if (rb.band.type === 'detail' && rb.rowData) {
+                printState.recordNumber++;
+                printState.isFirstRecord = printState.recordNumber === 1;
+                printState.isLastRecord = printState.recordNumber === totalRecords;
+                // Store previous/next values
+                const prevIdx = printState.recordNumber - 2;
+                const nextIdx = printState.recordNumber; // 0-indexed
+                if (prevIdx >= 0 && allDetailBands[prevIdx]?.rowData) {
+                    for (const [k, v] of Object.entries(allDetailBands[prevIdx].rowData)) {
+                        printState.previousValues.set(k, v);
+                    }
+                }
+                if (nextIdx < allDetailBands.length && allDetailBands[nextIdx]?.rowData) {
+                    for (const [k, v] of Object.entries(allDetailBands[nextIdx].rowData)) {
+                        printState.nextValues.set(k, v);
+                    }
+                }
+                // Process running totals
+                processRunningTotals(layout.runningTotals || [], rb.rowData, ctx, lastGroupValues);
+                // Detect group changes and increment groupNumber
+                if (layout.groups) {
+                    for (const g of layout.groups) {
+                        const currentGroupVal = rb.rowData[g.field];
+                        if (lastGroupValues.get(g.field) !== currentGroupVal) {
+                            printState.groupNumber++;
+                            lastGroupValues.set(g.field, currentGroupVal);
+                        }
+                    }
+                }
+            }
+            // Process group header bands for group number tracking
+            if (rb.band.type === 'groupHeader' && rb.groupKey !== undefined) {
+                // Group number is already tracked above via detail rows
+            }
+            // ── Conditional formatting ──
+            processConditionalFormats(layout.conditionalFormats || [], rb, ctx, dataSets, printState);
+            // ── Suppress if blank ──
+            processSuppressIfBlank(rb, ctx, dataSets);
+            // ── Keep-together tracking ──
+            // Handled by band-engine, but we flag bands that overflow
+            if (rb.band.keepTogether) {
+                trackKeepTogether(rb, page, layout, ctx);
+            }
+        }
+    }
+    // ── Subreport execution ──
+    executeSubreports(layout, dataSets, ctx, options);
+    return ctx;
+}
+/**
+ * Process running totals for a single detail row.
+ * Running totals accumulate across the entire report, resetting
+ * based on their configured reset condition.
+ */
+function processRunningTotals(definitions, row, ctx, lastGroupValues) {
+    for (const rt of definitions) {
+        const currentVal = ctx.runningTotals.get(rt.id) ?? 0;
+        const fieldVal = row[rt.field];
+        const numVal = typeof fieldVal === 'number' ? fieldVal : 0;
+        // Check reset condition FIRST
+        let shouldReset = false;
+        switch (rt.resetCondition) {
+            case 'never':
+                break;
+            case 'on-change':
+                if (rt.resetField) {
+                    const prevVal = lastGroupValues.get(`__rt_${rt.id}_${rt.resetField}`);
+                    const curVal = row[rt.resetField];
+                    if (prevVal !== undefined && prevVal !== curVal) {
+                        shouldReset = true;
+                    }
+                    lastGroupValues.set(`__rt_${rt.id}_${rt.resetField}`, curVal);
+                }
+                break;
+            case 'on-group-change':
+                if (rt.resetField) {
+                    const prevGroupVal = lastGroupValues.get(rt.resetField);
+                    const curGroupVal = row[rt.resetField];
+                    if (prevGroupVal !== undefined && prevGroupVal !== curGroupVal) {
+                        shouldReset = true;
+                    }
+                }
+                break;
+            case 'formula':
+                // Formula reset: evaluate resetField as expression
+                if (rt.resetField) {
+                    try {
+                        const fn = new Function('row', `"use strict"; return (${rt.resetField});`);
+                        if (fn(row))
+                            shouldReset = true;
+                    }
+                    catch {
+                        // Expression evaluation failed — do not reset
+                    }
+                }
+                break;
+        }
+        if (shouldReset) {
+            ctx.runningTotals.set(rt.id, 0);
+        }
+        // Check evaluate condition
+        let shouldEvaluate = false;
+        switch (rt.evaluateCondition) {
+            case 'each-record':
+                shouldEvaluate = true;
+                break;
+            case 'on-change':
+                if (rt.evaluateField) {
+                    const prevVal = lastGroupValues.get(`__rt_eval_${rt.id}_${rt.evaluateField}`);
+                    const curVal = row[rt.evaluateField];
+                    if (prevVal !== curVal) {
+                        shouldEvaluate = true;
+                    }
+                    lastGroupValues.set(`__rt_eval_${rt.id}_${rt.evaluateField}`, curVal);
+                }
+                else {
+                    shouldEvaluate = true;
+                }
+                break;
+            case 'on-group-change':
+                if (rt.evaluateField) {
+                    const prevGroupVal = lastGroupValues.get(rt.evaluateField);
+                    const curGroupVal = row[rt.evaluateField];
+                    if (prevGroupVal !== curGroupVal) {
+                        shouldEvaluate = true;
+                    }
+                }
+                break;
+            case 'formula':
+                if (rt.evaluateField) {
+                    try {
+                        const fn = new Function('row', `"use strict"; return (${rt.evaluateField});`);
+                        if (fn(row))
+                            shouldEvaluate = true;
+                    }
+                    catch {
+                        shouldEvaluate = false;
+                    }
+                }
+                break;
+        }
+        if (!shouldEvaluate)
+            continue;
+        // Apply the summarize function
+        const base = shouldReset ? 0 : (ctx.runningTotals.get(rt.id) ?? 0);
+        const newVal = applyRunningAggregate(rt.summarize, base, numVal, ctx, rt);
+        ctx.runningTotals.set(rt.id, newVal);
+    }
+}
+/**
+ * Apply a running aggregate function incrementally.
+ * For sum/count this is trivial; for avg/min/max we need
+ * accumulated state. We store auxiliary counters using the
+ * running total id as prefix.
+ */
+function applyRunningAggregate(fn, current, value, ctx, rt) {
+    switch (fn) {
+        case 'sum':
+            return current + value;
+        case 'count':
+            return current + 1;
+        case 'avg': {
+            // Track count alongside total for running average
+            const countKey = `${rt.id}__count`;
+            const totalKey = `${rt.id}__total`;
+            const count = (ctx.runningTotals.get(countKey) ?? 0) + 1;
+            const total = (ctx.runningTotals.get(totalKey) ?? 0) + value;
+            ctx.runningTotals.set(countKey, count);
+            ctx.runningTotals.set(totalKey, total);
+            return count > 0 ? total / count : 0;
+        }
+        case 'min':
+            return current === 0 && !ctx.runningTotals.has(`${rt.id}__init`)
+                ? (ctx.runningTotals.set(`${rt.id}__init`, 1), value)
+                : Math.min(current, value);
+        case 'max':
+            return current === 0 && !ctx.runningTotals.has(`${rt.id}__init`)
+                ? (ctx.runningTotals.set(`${rt.id}__init`, 1), value)
+                : Math.max(current, value);
+        default:
+            return current + value;
+    }
+}
+/**
+ * Evaluate conditional format rules for all elements in a rendered band.
+ * When a condition is true, the computed style is stored in ctx.conditionalFormats.
+ */
+function processConditionalFormats(rules, rb, ctx, dataSets, printState) {
+    if (rules.length === 0)
+        return;
+    // Build a scope object for evaluating conditions
+    const scope = {
+        RecordNumber: printState.recordNumber,
+        GroupNumber: printState.groupNumber,
+        PageNumber: printState.pageNumber,
+        IsFirstRecord: printState.isFirstRecord,
+        IsLastRecord: printState.isLastRecord,
+    };
+    // Add row data to scope
+    if (rb.rowData) {
+        Object.assign(scope, rb.rowData);
+    }
+    // Add running totals to scope
+    for (const [key, val] of ctx.runningTotals) {
+        // Only expose user-defined running totals (skip internal counters)
+        if (!key.includes('__')) {
+            scope[key] = val;
+        }
+    }
+    // Evaluate each rule that targets an element in this band
+    const bandElementIds = new Set(rb.band.elements.map(e => e.id));
+    for (const rule of rules) {
+        if (!bandElementIds.has(rule.elementId))
+            continue;
+        try {
+            const conditionResult = evaluateConditionExpression(rule.condition, scope);
+            if (conditionResult) {
+                // Merge styles — later rules override earlier ones
+                const existing = ctx.conditionalFormats.get(rule.elementId);
+                if (existing) {
+                    ctx.conditionalFormats.set(rule.elementId, { ...existing, ...rule.style });
+                }
+                else {
+                    ctx.conditionalFormats.set(rule.elementId, { ...rule.style });
+                }
+            }
+        }
+        catch {
+            // Condition evaluation failed — skip rule silently
+        }
+    }
+}
+/**
+ * Safely evaluate a boolean expression for conditional formatting.
+ * Provides a sandboxed scope with row data and print state.
+ */
+function evaluateConditionExpression(condition, scope) {
+    // Build parameter names and values arrays for the Function constructor
+    const paramNames = Object.keys(scope);
+    const paramValues = Object.values(scope);
+    try {
+        const fn = new Function(...paramNames, `"use strict"; return Boolean(${condition});`);
+        return fn(...paramValues);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Process "suppress if blank" logic for elements.
+ * If a field element resolves to empty/null/zero and has
+ * suppressIfBlank set, add it to the suppressed set.
+ */
+function processSuppressIfBlank(rb, ctx, dataSets) {
+    for (const element of rb.band.elements) {
+        if (element.visible === false) {
+            ctx.suppressedElements.add(element.id);
+            continue;
+        }
+        // Check visibleExpression
+        if (element.visibleExpression) {
+            const scope = {};
+            if (rb.rowData)
+                Object.assign(scope, rb.rowData);
+            try {
+                const result = evaluateConditionExpression(element.visibleExpression, scope);
+                if (!result) {
+                    ctx.suppressedElements.add(element.id);
+                    continue;
+                }
+            }
+            catch {
+                // If expression fails, keep element visible
+            }
+        }
+        // For field elements, check if the resolved value is blank
+        if (element.type === 'field') {
+            const fe = element;
+            const bindCtx = {
+                dataSets,
+                currentRow: rb.rowData,
+                currentIndex: rb.rowIndex,
+                groupRows: rb.groupRows,
+                pageNumber: rb.context.pageNumber,
+            };
+            const resolved = resolveElementValue(fe, bindCtx);
+            if (resolved === '' || resolved === null || resolved === undefined) {
+                // Only suppress if the band or element is configured to suppress blanks
+                // We check for a convention: elements with id ending in "__suppressBlank"
+                // or the band has a metadata flag. For now, track all blank fields.
+                // The renderer can decide whether to suppress.
+            }
+        }
+    }
+}
+/**
+ * Track keep-together state for bands. If a band with keepTogether=true
+ * was split across pages, we flag it in the context so the renderer
+ * can attempt to move it to the next page.
+ */
+function trackKeepTogether(rb, page, layout, _ctx) {
+    // The band engine already handles page breaks for individual bands.
+    // Keep-together for groups (all group header + details + footer together)
+    // is tracked here for the renderer to potentially re-process.
+    //
+    // For a group header, check if the subsequent detail rows and footer
+    // are all on the same page. If not, the group should start on the next page.
+    // This is advisory — the band engine may need to be re-invoked with adjusted
+    // breaks for perfect keep-together behavior.
+}
+/**
+ * Execute subreport elements found in any band.
+ * Each subreport is rendered recursively using its own layout and data.
+ */
+function executeSubreports(layout, dataSets, ctx, options) {
+    for (const band of layout.bands) {
+        for (const element of band.elements) {
+            // Subreport is a future element type — check via string comparison
+            // to support forward-compatible layouts before the type union is extended
+            const elType = element.type;
+            if (elType === 'subreport') {
+                // Subreport elements have a layoutRef and optional dataFilter
+                // For now, subreports must be provided in the dataSets under their id
+                const elId = element.id;
+                const subreportData = dataSets[`__subreport_${elId}`];
+                const subreportLayout = dataSets[`__subreport_layout_${elId}`];
+                if (subreportLayout && subreportData) {
+                    const subDs = { main: subreportData };
+                    const subResult = renderReport(subreportLayout, subDs, options);
+                    ctx.subreportResults.set(elId, subResult);
+                }
+            }
+        }
+    }
+}
+// ─── Pass 3: TotalPageCount ─────────────────────────────────────────
+/**
+ * Pass 3 finalizes the total page count and back-fills all
+ * "Page N of M" references throughout the rendered content.
+ * This requires a second layout pass if total pages changed.
+ */
+export function executePass3(layout, ctx) {
+    // Total pages is simply the count of pages from Pass 2
+    ctx.totalPages = ctx.pageContent.length;
+    ctx.printState.totalPages = ctx.totalPages;
+    // Update all page content with the final total pages count
+    for (const page of ctx.pageContent) {
+        for (const rb of page.bands) {
+            // Update the binding context with total pages
+            rb.context.totalPages = ctx.totalPages;
+        }
+    }
+    return ctx;
+}
+// ─── Public API: Full 3-pass render ─────────────────────────────────
+/**
+ * Execute the complete 3-pass rendering pipeline.
+ *
+ * 1. WhileReadingRecords — sort, group, aggregate
+ * 2. WhilePrintingRecords — running totals, expressions, conditional formats, subreports
+ * 3. TotalPageCount — finalize page count, back-fill "Page N of M"
+ *
+ * Returns a RenderResult with fully resolved pages.
+ */
+export function renderReport(layout, dataSets, options) {
+    // ── Pass 1: WhileReadingRecords ──
+    const ctx = executePass1(layout, dataSets);
+    // Replace dataSets with sorted data for subsequent passes
+    const sortedDataSets = { ...dataSets };
+    for (const [dsId, sorted] of ctx.sortedData) {
+        sortedDataSets[dsId] = sorted;
+    }
+    // ── Pass 2: WhilePrintingRecords ──
+    executePass2(layout, sortedDataSets, ctx, options);
+    // ── Pass 3: TotalPageCount ──
+    executePass3(layout, ctx);
+    // ── Build final RenderResult ──
+    const pages = ctx.pageContent.map(pc => ({
+        pageNumber: pc.pageNumber,
+        totalPages: ctx.totalPages,
+        html: renderPageToHtml(pc, ctx, layout, sortedDataSets, options),
+    }));
+    return {
+        pages,
+        totalPages: ctx.totalPages,
+        generatedAt: new Date().toISOString(),
+    };
+}
+// ─── HTML rendering with multi-pass context ─────────────────────────
+/**
+ * Render a single page to HTML, applying all multi-pass context:
+ * conditional formats, suppressed elements, running totals, aggregates.
+ */
+function renderPageToHtml(page, ctx, layout, dataSets, options) {
+    const unit = layout.pageSize.unit;
+    const prefix = options?.cssPrefix ?? 'zr';
+    const pageWidth = layout.orientation === 'landscape'
+        ? toPx(layout.pageSize.height, unit)
+        : toPx(layout.pageSize.width, unit);
+    const pageHeight = toPx(layout.pageSize.height, unit);
+    const marginTop = toPx(layout.margins.top, unit);
+    const marginLeft = toPx(layout.margins.left, unit);
+    const bands = [];
+    for (const rb of page.bands) {
+        const bandHtml = renderBandToHtml(rb, ctx, layout, dataSets, prefix);
+        bands.push(bandHtml);
+    }
+    return [
+        `<div class="${prefix}-page" style="`,
+        `position:relative;`,
+        `width:${pageWidth}px;`,
+        `height:${pageHeight}px;`,
+        `padding-top:${marginTop}px;`,
+        `padding-left:${marginLeft}px;`,
+        `box-sizing:border-box;`,
+        `overflow:hidden;`,
+        `">`,
+        ...bands,
+        `</div>`,
+    ].join('');
+}
+/**
+ * Render a single band to HTML with all multi-pass context applied.
+ */
+function renderBandToHtml(rb, ctx, layout, dataSets, prefix) {
+    const unit = layout.pageSize.unit;
+    const bandHeight = toPx(rb.band.height, unit);
+    const bgStyle = rb.band.backgroundColor
+        ? `background-color:${rb.band.backgroundColor};`
+        : '';
+    const elements = [];
+    for (const element of rb.band.elements) {
+        // Skip suppressed elements
+        if (ctx.suppressedElements.has(element.id))
+            continue;
+        // Skip invisible elements
+        if (element.visible === false)
+            continue;
+        // Check printOn condition
+        if (element.printOn && element.printOn !== 'all') {
+            const pn = rb.context.pageNumber || 1;
+            const tp = ctx.totalPages;
+            switch (element.printOn) {
+                case 'first':
+                    if (pn !== 1)
+                        continue;
+                    break;
+                case 'last':
+                    if (pn !== tp)
+                        continue;
+                    break;
+                case 'odd':
+                    if (pn % 2 === 0)
+                        continue;
+                    break;
+                case 'even':
+                    if (pn % 2 !== 0)
+                        continue;
+                    break;
+            }
+        }
+        const elemHtml = renderElementToHtml(element, rb, ctx, layout, dataSets, prefix);
+        elements.push(elemHtml);
+    }
+    return [
+        `<div class="${prefix}-band ${prefix}-band-${rb.band.type}" `,
+        `data-band-id="${rb.band.id}" `,
+        `style="`,
+        `position:relative;`,
+        `top:${rb.y}px;`,
+        `height:${bandHeight}px;`,
+        `${bgStyle}`,
+        `">`,
+        ...elements,
+        `</div>`,
+    ].join('');
+}
+/**
+ * Render a single element to HTML with conditional formatting applied.
+ */
+function renderElementToHtml(element, rb, ctx, layout, dataSets, prefix) {
+    const unit = layout.pageSize.unit;
+    // Build binding context
+    const bindCtx = {
+        dataSets,
+        currentRow: rb.rowData,
+        currentIndex: rb.rowIndex,
+        groupRows: rb.groupRows,
+        allRows: rb.context.allRows,
+        pageNumber: rb.context.pageNumber,
+        totalPages: ctx.totalPages,
+        parameters: rb.context.parameters,
+        aggregates: getAggregatesForElement(element, rb, ctx),
+    };
+    // Resolve display value
+    let displayValue = resolveElementWithContext(element, bindCtx, ctx, rb);
+    // Build style string
+    const baseStyle = element.style || {};
+    const conditionalStyle = ctx.conditionalFormats.get(element.id) || {};
+    const mergedStyle = { ...layout.defaultStyle, ...baseStyle, ...conditionalStyle };
+    const x = toPx(element.x, unit);
+    const y = toPx(element.y, unit);
+    const w = toPx(element.width, unit);
+    const h = toPx(element.height, unit);
+    const cssProps = [
+        `position:absolute`,
+        `left:${x}px`,
+        `top:${y}px`,
+        `width:${w}px`,
+        `height:${h}px`,
+        `overflow:hidden`,
+    ];
+    // Apply merged styles
+    if (mergedStyle.fontFamily)
+        cssProps.push(`font-family:${mergedStyle.fontFamily}`);
+    if (mergedStyle.fontSize)
+        cssProps.push(`font-size:${mergedStyle.fontSize}pt`);
+    if (mergedStyle.fontWeight)
+        cssProps.push(`font-weight:${mergedStyle.fontWeight}`);
+    if (mergedStyle.fontStyle)
+        cssProps.push(`font-style:${mergedStyle.fontStyle}`);
+    if (mergedStyle.textDecoration)
+        cssProps.push(`text-decoration:${mergedStyle.textDecoration}`);
+    if (mergedStyle.textAlign)
+        cssProps.push(`text-align:${mergedStyle.textAlign}`);
+    if (mergedStyle.color)
+        cssProps.push(`color:${mergedStyle.color}`);
+    if (mergedStyle.backgroundColor)
+        cssProps.push(`background-color:${mergedStyle.backgroundColor}`);
+    if (mergedStyle.borderTop)
+        cssProps.push(`border-top:${mergedStyle.borderTop}`);
+    if (mergedStyle.borderRight)
+        cssProps.push(`border-right:${mergedStyle.borderRight}`);
+    if (mergedStyle.borderBottom)
+        cssProps.push(`border-bottom:${mergedStyle.borderBottom}`);
+    if (mergedStyle.borderLeft)
+        cssProps.push(`border-left:${mergedStyle.borderLeft}`);
+    if (mergedStyle.borderRadius)
+        cssProps.push(`border-radius:${mergedStyle.borderRadius}px`);
+    if (mergedStyle.padding != null)
+        cssProps.push(`padding:${typeof mergedStyle.padding === 'number' ? mergedStyle.padding + 'px' : mergedStyle.padding}`);
+    if (mergedStyle.opacity != null)
+        cssProps.push(`opacity:${mergedStyle.opacity}`);
+    if (mergedStyle.lineHeight)
+        cssProps.push(`line-height:${mergedStyle.lineHeight}`);
+    if (mergedStyle.wordWrap)
+        cssProps.push(`word-wrap:break-word`);
+    if (mergedStyle.verticalAlign) {
+        cssProps.push(`display:flex`);
+        const vaMap = { top: 'flex-start', middle: 'center', bottom: 'flex-end' };
+        cssProps.push(`align-items:${vaMap[mergedStyle.verticalAlign] || 'flex-start'}`);
+    }
+    const styleStr = cssProps.join(';');
+    // Render based on element type
+    switch (element.type) {
+        case 'line': {
+            const x2 = toPx(element.x2, unit);
+            const y2 = toPx(element.y2, unit);
+            const color = element.lineStyle?.color || '#000';
+            const width = element.lineStyle?.width || 1;
+            return `<svg class="${prefix}-line" data-id="${element.id}" style="position:absolute;left:0;top:0;width:100%;height:100%;overflow:visible;"><line x1="${x}" y1="${y}" x2="${x2}" y2="${y2}" stroke="${color}" stroke-width="${width}"/></svg>`;
+        }
+        case 'rect': {
+            const fill = element.fill || 'transparent';
+            const borderColor = element.lineStyle?.color || '#000';
+            const borderWidth = element.lineStyle?.width || 1;
+            return `<div class="${prefix}-rect" data-id="${element.id}" style="${styleStr};border:${borderWidth}px solid ${borderColor};background:${fill};"></div>`;
+        }
+        case 'image':
+            return `<img class="${prefix}-image" data-id="${element.id}" style="${styleStr};object-fit:${element.fit || 'contain'};" src="${escapeHtml(displayValue)}" alt=""/>`;
+        case 'barcode':
+            return `<div class="${prefix}-barcode" data-id="${element.id}" data-type="${element.barcodeType}" style="${styleStr}">${escapeHtml(displayValue)}</div>`;
+        default:
+            return `<div class="${prefix}-element ${prefix}-${element.type}" data-id="${element.id}" style="${styleStr}">${escapeHtml(displayValue)}</div>`;
+    }
+}
+/**
+ * Resolve an element's display value using the full multi-pass context.
+ * This extends the basic resolveElementValue with running totals,
+ * print-time expressions, and pre-computed aggregates.
+ */
+function resolveElementWithContext(element, bindCtx, ctx, rb) {
+    if (element.type === 'field') {
+        const fe = element;
+        // Check if this field references a running total
+        if (fe.expression?.startsWith('RunningTotal(')) {
+            const rtMatch = fe.expression.match(/RunningTotal\(["']?(\w+)["']?\)/);
+            if (rtMatch) {
+                const rtId = rtMatch[1];
+                const val = ctx.runningTotals.get(rtId) ?? 0;
+                return formatValue(val, fe.format);
+            }
+        }
+        // Check for print-time expressions
+        if (fe.expression) {
+            const expr = fe.expression;
+            // Previous() function
+            if (expr.includes('Previous(')) {
+                const prevMatch = expr.match(/Previous\(["']?(\w+)["']?\)/);
+                if (prevMatch) {
+                    const fieldName = prevMatch[1];
+                    const val = ctx.printState.previousValues.get(fieldName);
+                    return formatValue(val, fe.format);
+                }
+            }
+            // Next() function
+            if (expr.includes('Next(')) {
+                const nextMatch = expr.match(/Next\(["']?(\w+)["']?\)/);
+                if (nextMatch) {
+                    const fieldName = nextMatch[1];
+                    const val = ctx.printState.nextValues.get(fieldName);
+                    return formatValue(val, fe.format);
+                }
+            }
+            // RecordNumber
+            if (expr === 'RecordNumber' || expr === '=RecordNumber') {
+                return String(ctx.printState.recordNumber);
+            }
+            // GroupNumber
+            if (expr === 'GroupNumber' || expr === '=GroupNumber') {
+                return String(ctx.printState.groupNumber);
+            }
+        }
+        // Check for pre-computed aggregates from Pass 1
+        if (fe.aggregate) {
+            const aggResult = resolveAggregateFromContext(fe, rb, ctx);
+            if (aggResult !== null) {
+                return formatValue(aggResult, fe.format);
+            }
+        }
+    }
+    // Fall back to standard resolution
+    return resolveElementValue(element, bindCtx);
+}
+/**
+ * Look up a pre-computed aggregate from the Pass 1 context.
+ * Tries group-level first, then falls back to grand totals.
+ */
+function resolveAggregateFromContext(fe, rb, ctx) {
+    const aggKey = makeAggKey(fe.field, fe.aggregate);
+    // If in a group band, look up group-level aggregate
+    if (rb.groupKey !== undefined && rb.band.groupField) {
+        const compositeKey = `${rb.band.groupField}::${rb.groupKey}`;
+        const groupAggs = ctx.aggregates.get(compositeKey);
+        if (groupAggs?.has(aggKey)) {
+            return groupAggs.get(aggKey);
+        }
+    }
+    // If field has resetOnGroup, look up the group aggregate
+    if (fe.resetOnGroup) {
+        // Find the current group key from the rendered band context
+        if (rb.groupKey !== undefined) {
+            const compositeKey = `${fe.resetOnGroup}::${rb.groupKey}`;
+            const groupAggs = ctx.aggregates.get(compositeKey);
+            if (groupAggs?.has(aggKey)) {
+                return groupAggs.get(aggKey);
+            }
+        }
+    }
+    // Fall back to grand totals
+    if (ctx.grandTotals.has(aggKey)) {
+        return ctx.grandTotals.get(aggKey);
+    }
+    return null;
+}
+/**
+ * Get the appropriate aggregates map for an element based on its
+ * band context (group vs report level).
+ */
+function getAggregatesForElement(element, rb, ctx) {
+    if (element.type !== 'field')
+        return undefined;
+    const fe = element;
+    if (!fe.aggregate)
+        return undefined;
+    // Try group-level aggregates first
+    if (rb.groupKey !== undefined && rb.band.groupField) {
+        const compositeKey = `${rb.band.groupField}::${rb.groupKey}`;
+        return ctx.aggregates.get(compositeKey);
+    }
+    // Return grand totals as a map
+    return ctx.grandTotals;
+}
+/** HTML-escape a string */
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+// ─── Utility: Retrieve aggregate from context ───────────────────────
+/**
+ * Public helper to retrieve a pre-computed aggregate from the report context.
+ * Useful for custom renderers or post-processing.
+ *
+ * @param ctx - The report context after Pass 1
+ * @param field - The field name
+ * @param fn - The aggregate function
+ * @param groupField - Optional group field name
+ * @param groupKey - Optional group key value
+ */
+export function getAggregate(ctx, field, fn, groupField, groupKey) {
+    const aggKey = makeAggKey(field, fn);
+    if (groupField && groupKey) {
+        const compositeKey = `${groupField}::${groupKey}`;
+        const groupAggs = ctx.aggregates.get(compositeKey);
+        if (groupAggs?.has(aggKey)) {
+            return groupAggs.get(aggKey);
+        }
+    }
+    return ctx.grandTotals.get(aggKey) ?? 0;
+}
+/**
+ * Public helper to retrieve a running total value from the report context.
+ *
+ * @param ctx - The report context after Pass 2
+ * @param runningTotalId - The running total definition id
+ */
+export function getRunningTotal(ctx, runningTotalId) {
+    return ctx.runningTotals.get(runningTotalId) ?? 0;
+}
+//# sourceMappingURL=multi-pass-engine.js.map