mviz 1.6.6 → 1.6.7

package/dist/charts/area.js

@@ -1,10 +1,11 @@
 /**
  * Area chart generator
  */
-import { FONT_SIZE_XXS, LEGEND_ITEM_WIDTH, LEGEND_ITEM_HEIGHT, LEGEND_ITEM_GAP, DEFAULT_CHART_HEIGHT, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
+import { DEFAULT_CHART_HEIGHT, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
 import { wrapHtml } from '../core/serializer.js';
 import { registerChart, registerOptions } from './registry.js';
-import { inferFormat, getAxisFormatterJs, inferAxisType, resolveCurrency, shouldPctMultiply, collectNumericFieldValues, } from '../core/formatting.js';
+import { inferAxisType } from '../core/formatting.js';
+import { buildValueAxisFormatContext, buildXAxisLabelConfig, applyValueAxisRange, buildMultiSeriesLegend, } from '../core/chart-helpers.js';
 /**
  * Build ECharts options for an area chart
  */
@@ -19,30 +20,12 @@ export function buildAreaOptions(spec) {
     const yKeys = Array.isArray(y) ? y : [y];
     const categories = data.map((d) => d[x]);
     const palette = getPaletteWithCustom(theme, spec.customTheme);
-    // Infer format for value axis based on first y field name
-    const firstYKey = yKeys[0] ?? 'value';
-    const sampleValue = data.length > 0 && data[0] ? data[0][firstYKey] ?? 0 : 0;
-    const valueFormat = spec.format ?? inferFormat(firstYKey, sampleValue);
-    const currency = resolveCurrency(spec.currency);
-    const pctMultiply = shouldPctMultiply(valueFormat, collectNumericFieldValues(data, yKeys));
-    const axisFormatter = getAxisFormatterJs(valueFormat, currency.symbol, currency.locale, pctMultiply);
+    // Resolve value-axis format/currency/formatters
+    const { axisFormatter } = buildValueAxisFormatContext(spec, data, yKeys);
     // Detect x-axis type: time, value, or category
     const xAxisType = spec.xAxisType ?? inferAxisType(categories);
     // Get axis label config based on axis type
-    const xAxisLabelConfig = xAxisType === 'category'
-        ? { interval: 0, rotate: 45, overflow: 'truncate', ellipsis: '...', width: 100 }
-        : xAxisType === 'time'
-            ? {
-                hideOverlap: true,
-                formatter: {
-                    _js_: `function(value) {
-            var d = new Date(value);
-            var months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
-            return months[d.getMonth()] + ' ' + d.getDate();
-          }`,
-                },
-            }
-            : { hideOverlap: true };
+    const xAxisLabelConfig = buildXAxisLabelConfig(xAxisType);
     const option = {
         backgroundColor: 'transparent',
         animation: false,
@@ -84,22 +67,10 @@ export function buildAreaOptions(spec) {
         series: [],
     };
     // Apply yMin/yMax
-    if (spec.yMin !== undefined) {
-        option.yAxis.min = spec.yMin;
-    }
-    if (spec.yMax !== undefined) {
-        option.yAxis.max = spec.yMax;
-    }
+    applyValueAxisRange(option.yAxis, spec);
     // Add legend for multi-series
     if (yKeys.length > 1) {
-        option.legend = {
-            data: yKeys,
-            top: 0,
-            textStyle: { color: colors.textSecondary, fontSize: FONT_SIZE_XXS },
-            itemWidth: LEGEND_ITEM_WIDTH,
-            itemHeight: LEGEND_ITEM_HEIGHT,
-            itemGap: LEGEND_ITEM_GAP,
-        };
+        option.legend = buildMultiSeriesLegend(yKeys, colors);
     }
     // Build series
     for (let i = 0; i < yKeys.length; i++) {

package/dist/charts/bar.js

@@ -1,10 +1,11 @@
 /**
  * Bar chart generator
  */
-import { BAR_MAX_WIDTH, LEGEND_ITEM_WIDTH, LEGEND_ITEM_HEIGHT, LEGEND_ITEM_GAP, FONT_SIZE_TINY, FONT_SIZE_XXS, DEFAULT_CHART_HEIGHT, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
+import { BAR_MAX_WIDTH, FONT_SIZE_TINY, FONT_SIZE_XXS, DEFAULT_CHART_HEIGHT, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
 import { wrapHtml } from '../core/serializer.js';
 import { registerChart, registerOptions } from './registry.js';
-import { inferFormat, getLabelFormatterJs, getAxisFormatterJs, inferAxisType, resolveCurrency, shouldPctMultiply, collectNumericFieldValues, } from '../core/formatting.js';
+import { inferAxisType } from '../core/formatting.js';
+import { buildValueAxisFormatContext, buildXAxisLabelConfig, applyValueAxisRange, buildMultiSeriesLegend, } from '../core/chart-helpers.js';
 /**
  * Build ECharts options for a bar chart
  */
@@ -19,14 +20,8 @@ export function buildBarOptions(spec) {
     const yKeys = Array.isArray(y) ? y : [y];
     const categories = data.map((d) => d[x]);
     const palette = getPaletteWithCustom(theme, spec.customTheme);
-    // Infer format for value axis based on first y field name
-    const firstYKey = yKeys[0] ?? 'value';
-    const sampleValue = data.length > 0 && data[0] ? data[0][firstYKey] ?? 0 : 0;
-    const valueFormat = spec.format ?? inferFormat(firstYKey, sampleValue);
-    const currency = resolveCurrency(spec.currency);
-    const pctMultiply = shouldPctMultiply(valueFormat, collectNumericFieldValues(data, yKeys));
-    const labelFormatter = getLabelFormatterJs(valueFormat, currency.symbol, currency.locale, pctMultiply);
-    const axisFormatter = getAxisFormatterJs(valueFormat, currency.symbol, currency.locale, pctMultiply);
+    // Resolve value-axis format/currency/formatters
+    const { axisFormatter, labelFormatter } = buildValueAxisFormatContext(spec, data, yKeys, { withLabelFormatter: true });
     // Detect category axis type (this is x-axis for vertical, y-axis for horizontal)
     const categoryAxisType = spec.xAxisType ?? inferAxisType(categories);
     // For horizontal bars, x-axis is always 'value'; for vertical it's the category axis type
@@ -34,9 +29,7 @@ export function buildBarOptions(spec) {
     // Determine if labels should be shown (based on category axis type, not x-axis for horizontal)
     const showLabels = yKeys.length === 1 && !stacked && data.length <= 12 && categoryAxisType === 'category';
     // Get axis label config based on axis type
-    const xAxisLabelConfig = xAxisType === 'category'
-        ? { interval: 0, rotate: 45, overflow: 'truncate', ellipsis: '...', width: 100 }
-        : { hideOverlap: true };
+    const xAxisLabelConfig = buildXAxisLabelConfig(xAxisType);
     const option = {
         backgroundColor: 'transparent',
         animation: false,
@@ -111,12 +104,7 @@ export function buildBarOptions(spec) {
     };
     // Apply yMin/yMax to value axis
     const valueAxis = horizontal ? 'xAxis' : 'yAxis';
-    if (spec.yMin !== undefined) {
-        option[valueAxis].min = spec.yMin;
-    }
-    if (spec.yMax !== undefined) {
-        option[valueAxis].max = spec.yMax;
-    }
+    applyValueAxisRange(option[valueAxis], spec);
     // Adjust y-axis gridlines based on x-axis category label length
     // Long category labels (rotated 45°) take up vertical space at bottom
     const chartHeight = typeof spec.height === 'number' ? spec.height : DEFAULT_CHART_HEIGHT;
@@ -137,14 +125,7 @@ export function buildBarOptions(spec) {
     }
     // Add legend for multi-series
     if (yKeys.length > 1) {
-        option.legend = {
-            data: yKeys,
-            top: 0,
-            textStyle: { color: colors.textSecondary, fontSize: FONT_SIZE_XXS },
-            itemWidth: LEGEND_ITEM_WIDTH,
-            itemHeight: LEGEND_ITEM_HEIGHT,
-            itemGap: LEGEND_ITEM_GAP,
-        };
+        option.legend = buildMultiSeriesLegend(yKeys, colors);
     }
     // Use lighter label color for dark theme for better visibility
     const labelColor = theme === 'dark' ? colors.text : colors.textSecondary;

package/dist/charts/combo.js

@@ -1,9 +1,10 @@
 /**
  * Combo chart generator (bar + line with optional dual axis)
  */
-import { FONT_SIZE_XXS, BAR_MAX_WIDTH, LEGEND_ITEM_WIDTH, LEGEND_ITEM_HEIGHT, LEGEND_ITEM_GAP, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
+import { BAR_MAX_WIDTH, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
 import { wrapHtml } from '../core/serializer.js';
-import { inferAxisType, inferFormat, getAxisFormatterJs, resolveCurrency, shouldPctMultiply, collectNumericFieldValues, } from '../core/formatting.js';
+import { inferAxisType, inferFormat } from '../core/formatting.js';
+import { buildValueAxisFormatContext, buildXAxisLabelConfig, applyValueAxisRange, buildMultiSeriesLegend, } from '../core/chart-helpers.js';
 import { registerChart, registerOptions } from './registry.js';
 /**
  * Build ECharts options for a combo chart (bar + line with optional dual axis)
@@ -20,34 +21,21 @@ export function buildComboOptions(spec) {
     const barKeys = Array.isArray(barFields) ? barFields : barFields ? [barFields] : [];
     const lineKeys = Array.isArray(lineFields) ? lineFields : lineFields ? [lineFields] : [];
     const categories = data.map((d) => d[x]);
-    // Infer format for primary y-axis (bars)
-    const barSample = data.length > 0 && data[0] && barKeys[0] ? data[0][barKeys[0]] ?? 0 : 0;
-    const primaryFormat = spec.format ?? inferFormat(barKeys[0] ?? 'value', barSample);
-    const currency = resolveCurrency(spec.currency);
-    const primaryPctMultiply = shouldPctMultiply(primaryFormat, collectNumericFieldValues(data, barKeys));
-    const primaryAxisFormatter = getAxisFormatterJs(primaryFormat, currency.symbol, currency.locale, primaryPctMultiply);
-    // Infer format for secondary y-axis (line if dual axis)
-    const lineSample = data.length > 0 && data[0] && lineKeys[0] ? data[0][lineKeys[0]] ?? 0 : 0;
-    const secondaryFormat = spec.secondaryFormat ?? inferFormat(lineKeys[0] ?? 'value', lineSample);
-    const secondaryPctMultiply = shouldPctMultiply(secondaryFormat, collectNumericFieldValues(data, lineKeys));
-    const secondaryAxisFormatter = getAxisFormatterJs(secondaryFormat, currency.symbol, currency.locale, secondaryPctMultiply);
+    // Resolve format/currency/formatters for primary y-axis (bars) and secondary (line).
+    //
+    // The secondary axis must NOT inherit spec.format (which is the primary/bar
+    // format), so we resolve it explicitly here from spec.secondaryFormat or by
+    // inferring from the line field, then pass it as an explicit override.
+    const { axisFormatter: primaryAxisFormatter } = buildValueAxisFormatContext(spec, data, barKeys);
+    const lineSample = data.length > 0 && data[0] && lineKeys[0]
+        ? data[0][lineKeys[0]] ?? 0
+        : 0;
+    const resolvedSecondaryFormat = spec.secondaryFormat ?? inferFormat(lineKeys[0] ?? 'value', lineSample);
+    const { axisFormatter: secondaryAxisFormatter } = buildValueAxisFormatContext(spec, data, lineKeys, { formatOverride: resolvedSecondaryFormat });
     // Detect x-axis type
     const xAxisType = inferAxisType(categories);
     // Get axis label config based on axis type
-    const xAxisLabelConfig = xAxisType === 'category'
-        ? { interval: 0, rotate: 45, overflow: 'truncate', ellipsis: '...', width: 100 }
-        : xAxisType === 'time'
-            ? {
-                hideOverlap: true,
-                formatter: {
-                    _js_: `function(value) {
-            var d = new Date(value);
-            var months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
-            return months[d.getMonth()] + ' ' + d.getDate();
-          }`,
-                },
-            }
-            : { hideOverlap: true };
+    const xAxisLabelConfig = buildXAxisLabelConfig(xAxisType);
     const series = [];
     // Add bar series
     barKeys.forEach((key, i) => {
@@ -96,12 +84,7 @@ export function buildComboOptions(spec) {
         },
     ];
     // Apply yMin/yMax to primary y-axis
-    if (spec.yMin !== undefined) {
-        yAxis[0].min = spec.yMin;
-    }
-    if (spec.yMax !== undefined) {
-        yAxis[0].max = spec.yMax;
-    }
+    applyValueAxisRange(yAxis[0], spec);
     if (dualAxis) {
         yAxis.push({
             type: 'value',
@@ -130,14 +113,7 @@ export function buildComboOptions(spec) {
             bottom: '8%',
             containLabel: true,
         },
-        legend: {
-            data: [...barKeys, ...lineKeys],
-            top: 0,
-            textStyle: { color: colors.textSecondary, fontSize: FONT_SIZE_XXS },
-            itemWidth: LEGEND_ITEM_WIDTH,
-            itemHeight: LEGEND_ITEM_HEIGHT,
-            itemGap: LEGEND_ITEM_GAP,
-        },
+        legend: buildMultiSeriesLegend([...barKeys, ...lineKeys], colors),
         xAxis: {
             type: xAxisType,
             data: xAxisType === 'category' ? categories.map(String) : undefined,

package/dist/charts/line.js

@@ -4,7 +4,8 @@
 import { FONT_SIZE_TINY, DEFAULT_CHART_HEIGHT, getThemeColors, getPaletteWithCustom, } from '../core/themes.js';
 import { wrapHtml } from '../core/serializer.js';
 import { registerChart, registerOptions } from './registry.js';
-import { inferFormat, getAxisFormatterJs, inferAxisType, resolveCurrency, shouldPctMultiply, collectNumericFieldValues, } from '../core/formatting.js';
+import { inferAxisType } from '../core/formatting.js';
+import { buildValueAxisFormatContext, buildXAxisLabelConfig, applyValueAxisRange, } from '../core/chart-helpers.js';
 /**
  * Build ECharts options for a line chart
  */
@@ -18,33 +19,15 @@ export function buildLineOptions(spec) {
     const yKeys = Array.isArray(y) ? y : [y];
     const categories = data.map((d) => d[x]);
     const palette = getPaletteWithCustom(theme, spec.customTheme);
-    // Infer format for value axis based on first y field name
-    const firstYKey = yKeys[0] ?? 'value';
-    const sampleValue = data.length > 0 && data[0] ? data[0][firstYKey] ?? 0 : 0;
-    const valueFormat = spec.format ?? inferFormat(firstYKey, sampleValue);
-    const currency = resolveCurrency(spec.currency);
-    const pctMultiply = shouldPctMultiply(valueFormat, collectNumericFieldValues(data, yKeys));
-    const axisFormatter = getAxisFormatterJs(valueFormat, currency.symbol, currency.locale, pctMultiply);
+    // Resolve value-axis format/currency/formatters
+    const { axisFormatter } = buildValueAxisFormatContext(spec, data, yKeys);
     // Detect x-axis type: time, value, or category
     // User can override with xAxisType in spec
     const xAxisType = spec.xAxisType ?? inferAxisType(categories);
     // More right margin needed for end labels on multi-series
     const hasEndLabels = yKeys.length > 1;
     // Get axis label config based on axis type
-    const xAxisLabelConfig = xAxisType === 'category'
-        ? { interval: 0, rotate: 45, overflow: 'truncate', ellipsis: '...', width: 100 }
-        : xAxisType === 'time'
-            ? {
-                hideOverlap: true,
-                formatter: {
-                    _js_: `function(value) {
-            var d = new Date(value);
-            var months = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
-            return months[d.getMonth()] + ' ' + d.getDate();
-          }`,
-                },
-            }
-            : { hideOverlap: true };
+    const xAxisLabelConfig = buildXAxisLabelConfig(xAxisType);
     const option = {
         backgroundColor: 'transparent',
         animation: false,
@@ -87,12 +70,7 @@ export function buildLineOptions(spec) {
         series: [],
     };
     // Apply yMin/yMax
-    if (spec.yMin !== undefined) {
-        option.yAxis.min = spec.yMin;
-    }
-    if (spec.yMax !== undefined) {
-        option.yAxis.max = spec.yMax;
-    }
+    applyValueAxisRange(option.yAxis, spec);
     // Build series
     for (let i = 0; i < yKeys.length; i++) {
         const key = yKeys[i];

package/dist/components/big_value.d.ts

@@ -1,9 +1,31 @@
 /**
  * Big value display component
+ *
+ * Provides two rendering paths that share the same business rules:
+ *   - generateBigValue(spec)  – standalone HTML document
+ *   - renderBigValue(spec, ctx) – dashboard grid-item fragment
+ *
+ * Validation (value must be numeric) and format inference live in the shared
+ * resolveBigValueState() helper so the two paths cannot drift.
  */
 import type { ComponentSpec } from '../types.js';
 /**
- * Generate a big value display for key metrics
+ * Optional dashboard rendering context.
+ */
+export interface BigValueRenderContext {
+    colSpan?: number | undefined;
+    anchorId?: string | undefined;
+    /** Currency code from frontmatter; falls back to spec.currency */
+    currencyCode?: string | undefined;
+}
+/**
+ * Render a big_value as a dashboard grid-item fragment.
+ *
+ * Throws ValidationError on non-numeric `value` (matches generateBigValue).
+ */
+export declare function renderBigValue(spec: Record<string, unknown>, ctx?: BigValueRenderContext): string;
+/**
+ * Generate a standalone big_value HTML document.
  */
 declare function generateBigValue(spec: ComponentSpec): string;
 export { generateBigValue };

package/dist/components/big_value.js

@@ -1,54 +1,113 @@
 /**
  * Big value display component
+ *
+ * Provides two rendering paths that share the same business rules:
+ *   - generateBigValue(spec)  – standalone HTML document
+ *   - renderBigValue(spec, ctx) – dashboard grid-item fragment
+ *
+ * Validation (value must be numeric) and format inference live in the shared
+ * resolveBigValueState() helper so the two paths cannot drift.
  */
 import { COLORS, FONT_STACK, getThemeColors } from '../core/themes.js';
 import { formatNumber, inferFormat, resolveCurrency } from '../core/formatting.js';
 import { registerComponent } from './registry.js';
 import { ValidationError } from '../core/exceptions.js';
 /**
- * Generate a big value display for key metrics
+ * Resolve the display state for a big_value spec.
+ *
+ * Throws ValidationError if `value` is not a number — this is intentional and
+ * matches the strict standalone behavior (the linter's `big-value-string` rule
+ * catches string values for spec authors; this throw is defensive for
+ * programmatic callers).
  */
-function generateBigValue(spec) {
+function resolveBigValueState(spec, currencyCode) {
     if (typeof spec.value !== 'number') {
         throw new ValidationError('value', 'big_value', 'number', spec.value);
     }
     const value = spec.value;
     const specLabel = spec.label;
     const specTitle = spec.title;
-    const theme = (spec.theme ?? 'light');
-    const comparison = spec.comparison;
-    // If only title is provided (no label), use title as the label below the number
-    // This matches user expectations that "title" describes what the number represents
+    // If only title is provided (no label), use title as the label below the number.
+    // If both provided, title becomes header and label goes below.
     const label = specLabel ?? specTitle ?? '';
-    // Only show H2 header if BOTH title and label are explicitly provided
-    const showTitleHeader = specTitle && specLabel;
+    const showTitleHeader = Boolean(specTitle && specLabel);
     const title = showTitleHeader ? specTitle : '';
-    // Auto-infer format from label if not specified
     const fmt = spec.format ?? inferFormat(label, value);
-    const currency = resolveCurrency(spec.currency);
-    const colors = getThemeColors(theme);
+    const currency = resolveCurrency(currencyCode ?? spec.currency);
     const displayValue = formatNumber(value, fmt, false, currency);
-    let comparisonHtml = '';
-    if (comparison) {
-        const compVal = comparison.value ?? 0;
-        const compLabel = comparison.label ?? '';
+    const comparisonSpec = spec.comparison;
+    let comparison;
+    if (comparisonSpec) {
+        const compVal = comparisonSpec.value ?? 0;
         const isPositive = compVal >= 0;
-        const arrow = isPositive ? '↑' : '↓';
-        const compColor = isPositive ? COLORS.POSITIVE_GREEN : COLORS.ERROR_RED;
-        const compDisplay = formatNumber(compVal, comparison.format, true, currency);
+        comparison = {
+            arrow: isPositive ? '↑' : '↓',
+            color: isPositive ? COLORS.POSITIVE_GREEN : COLORS.ERROR_RED,
+            display: formatNumber(compVal, comparisonSpec.format, true, currency),
+            label: comparisonSpec.label ?? '',
+        };
+    }
+    return { value, label, title, showTitleHeader, displayValue, comparison };
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Render a big_value as a dashboard grid-item fragment.
+ *
+ * Throws ValidationError on non-numeric `value` (matches generateBigValue).
+ */
+export function renderBigValue(spec, ctx = {}) {
+    const state = resolveBigValueState(spec, ctx.currencyCode);
+    const colSpan = ctx.colSpan ?? 4;
+    const anchorAttr = ctx.anchorId ? ` id="${ctx.anchorId}"` : '';
+    let comparisonHtml = '';
+    if (state.comparison) {
+        const c = state.comparison;
+        comparisonHtml = `
+      <div style="display: flex; align-items: center; gap: 4px; margin-top: 4px;">
+        <span style="color: ${c.color}; font-size: 12px;">${c.arrow} ${c.display}</span>
+        <span style="color: var(--text-muted); font-size: 10px;">${escapeHtml(c.label)}</span>
+      </div>`;
+    }
+    const titleHtml = state.showTitleHeader
+        ? `<h3 class="chart-title">${escapeHtml(state.title.toUpperCase())}</h3>`
+        : '';
+    return `
+    <div class="grid-item"${anchorAttr} style="--col-span: ${colSpan}; grid-column: span ${colSpan};">
+      ${titleHtml}<div class="big-value">${escapeHtml(state.displayValue)}</div>
+      <div class="label">${escapeHtml(state.label)}</div>${comparisonHtml}
+    </div>`;
+}
+/**
+ * Generate a standalone big_value HTML document.
+ */
+function generateBigValue(spec) {
+    const theme = (spec.theme ?? 'light');
+    const state = resolveBigValueState(spec);
+    const colors = getThemeColors(theme);
+    let comparisonHtml = '';
+    if (state.comparison) {
+        const c = state.comparison;
         comparisonHtml = `
       <div style="display: flex; align-items: center; gap: 4px; margin-top: 8px;">
-        <span style="color: ${compColor}; font-size: 14px;">${arrow} ${compDisplay}</span>
-        <span style="color: ${colors.textSecondary}; font-size: 12px;">${compLabel}</span>
+        <span style="color: ${c.color}; font-size: 14px;">${c.arrow} ${c.display}</span>
+        <span style="color: ${colors.textSecondary}; font-size: 12px;">${c.label}</span>
       </div>`;
     }
-    const titleUpper = title.toUpperCase();
-    const titleHtml = title ? `<h2>${titleUpper}</h2>` : '';
+    const titleHtml = state.showTitleHeader
+        ? `<h2>${state.title.toUpperCase()}</h2>`
+        : '';
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
-  <title>${title}</title>
+  <title>${state.title}</title>
   <style>
     * { box-sizing: border-box; }
     html, body {
@@ -70,8 +129,8 @@ function generateBigValue(spec) {
 <body>
   <div class="container">
     ${titleHtml}
-    <div class="big-value">${displayValue}</div>
-    <div class="label">${label}</div>
+    <div class="big-value">${state.displayValue}</div>
+    <div class="label">${state.label}</div>
     ${comparisonHtml}
   </div>
 </body>

package/dist/components/delta.d.ts

@@ -1,9 +1,32 @@
 /**
  * Delta/change indicator component
+ *
+ * Provides two rendering paths that share the same business rules:
+ *   - generateDelta(spec)      – standalone HTML document
+ *   - renderDelta(spec, ctx)   – dashboard grid-item fragment
+ *
+ * Direction/color resolution (including the neutral case) lives in the shared
+ * resolveDeltaState() helper so the two paths cannot drift.
  */
 import type { ComponentSpec } from '../types.js';
 /**
- * Generate a delta/change indicator
+ * Optional dashboard rendering context.
+ */
+export interface DeltaRenderContext {
+    colSpan?: number | undefined;
+    anchorId?: string | undefined;
+    /** Currency code from frontmatter; falls back to spec.currency */
+    currencyCode?: string | undefined;
+}
+/**
+ * Render a delta as a dashboard grid-item fragment.
+ *
+ * Uses the dashboard's CSS `--text-muted` token for the neutral color so the
+ * value blends with theme-aware muted text.
+ */
+export declare function renderDelta(spec: Record<string, unknown>, ctx?: DeltaRenderContext): string;
+/**
+ * Generate a standalone delta HTML document.
  */
 declare function generateDelta(spec: ComponentSpec): string;
 export { generateDelta };

package/dist/components/delta.js

@@ -1,36 +1,41 @@
 /**
  * Delta/change indicator component
+ *
+ * Provides two rendering paths that share the same business rules:
+ *   - generateDelta(spec)      – standalone HTML document
+ *   - renderDelta(spec, ctx)   – dashboard grid-item fragment
+ *
+ * Direction/color resolution (including the neutral case) lives in the shared
+ * resolveDeltaState() helper so the two paths cannot drift.
  */
 import { COLORS, FONT_STACK, getThemeColors } from '../core/themes.js';
 import { formatNumber, inferFormat, resolveCurrency } from '../core/formatting.js';
 import { registerComponent } from './registry.js';
 /**
- * Generate a delta/change indicator
+ * Resolve the display state for a delta spec.
+ *
+ * Neutral handling: when `value === neutralIs` (default 0), the indicator
+ * uses a right-arrow and a muted color — never green/red. This matches user
+ * expectations that "no change" is not a positive or negative signal.
  */
-function generateDelta(spec) {
+function resolveDeltaState(spec, neutralColor, currencyCode) {
     const value = typeof spec.value === 'number' ? spec.value : 0;
     const specLabel = spec.label;
     const specTitle = spec.title;
-    const theme = (spec.theme ?? 'light');
     const neutralIs = spec.neutralIs ?? 0;
     const positiveIsGood = spec.positiveIsGood !== false; // Default true
-    // If only title is provided (no label), use title as the label below
-    // If both provided, title becomes H2 header and label goes below
     const label = specLabel ?? specTitle ?? '';
-    const showTitleHeader = specTitle && specLabel;
+    const showTitleHeader = Boolean(specTitle && specLabel);
     const title = showTitleHeader ? specTitle : '';
-    // Auto-infer format from label if not specified
     const fmt = spec.format ?? inferFormat(label, value);
-    const currency = resolveCurrency(spec.currency);
-    const colors = getThemeColors(theme);
-    // Determine direction and color
+    const currency = resolveCurrency(currencyCode ?? spec.currency);
     const isPositive = value > neutralIs;
     const isNegative = value < neutralIs;
     const isNeutral = value === neutralIs;
     let color;
     let arrow;
     if (isNeutral) {
-        color = colors.textSecondary;
+        color = neutralColor;
         arrow = '→';
     }
     else if ((isPositive && positiveIsGood) || (isNegative && !positiveIsGood)) {
@@ -42,13 +47,54 @@ function generateDelta(spec) {
         arrow = isPositive ? '↑' : '↓';
     }
     const displayValue = formatNumber(value, fmt, true, currency);
-    const titleUpper = title.toUpperCase();
-    const titleHtml = title ? `<h2>${titleUpper}</h2>` : '';
+    return { label, title, showTitleHeader, arrow, color, isNeutral, displayValue };
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * Render a delta as a dashboard grid-item fragment.
+ *
+ * Uses the dashboard's CSS `--text-muted` token for the neutral color so the
+ * value blends with theme-aware muted text.
+ */
+export function renderDelta(spec, ctx = {}) {
+    // Dashboard uses a CSS variable for the muted color so theme switching works.
+    const state = resolveDeltaState(spec, 'var(--text-muted)', ctx.currencyCode);
+    const colSpan = ctx.colSpan ?? 4;
+    const anchorAttr = ctx.anchorId ? ` id="${ctx.anchorId}"` : '';
+    const titleHtml = state.showTitleHeader
+        ? `<h3 class="chart-title">${escapeHtml(state.title.toUpperCase())}</h3>`
+        : '';
+    return `
+    <div class="grid-item"${anchorAttr} style="--col-span: ${colSpan}; grid-column: span ${colSpan};">
+      ${titleHtml}<div class="delta">
+        <span class="arrow" style="color: ${state.color};">${state.arrow}</span>
+        <span class="value" style="color: ${state.color};">${escapeHtml(state.displayValue)}</span>
+      </div>
+      <div class="label">${escapeHtml(state.label)}</div>
+    </div>`;
+}
+/**
+ * Generate a standalone delta HTML document.
+ */
+function generateDelta(spec) {
+    const theme = (spec.theme ?? 'light');
+    const colors = getThemeColors(theme);
+    const state = resolveDeltaState(spec, colors.textSecondary);
+    const titleHtml = state.showTitleHeader
+        ? `<h2>${state.title.toUpperCase()}</h2>`
+        : '';
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
-  <title>${title}</title>
+  <title>${state.title}</title>
   <style>
     * { box-sizing: border-box; }
     html, body {
@@ -70,10 +116,10 @@ function generateDelta(spec) {
   <div class="container">
     ${titleHtml}
     <div class="delta">
-      <span class="arrow" style="color: ${color};">${arrow}</span>
-      <span class="value" style="color: ${color};">${displayValue}</span>
+      <span class="arrow" style="color: ${state.color};">${state.arrow}</span>
+      <span class="value" style="color: ${state.color};">${state.displayValue}</span>
     </div>
-    <div class="label">${label}</div>
+    <div class="label">${state.label}</div>
   </div>
 </body>
 </html>`;