@sybilion/uilib 1.3.54 → 1.3.55

package/dist/esm/components/widgets/DriversComparisonChart/DriversComparisonChart.js

@@ -28,16 +28,18 @@ import { Table, TableHeader, TableRow, TableHead, TableCellValue, TableBody, Tab
 import { TextShimmer } from '../../ui/TextShimmer/TextShimmer.js';
 import { TIME_RANGES } from '../../ui/TimeRangeControls/TimeRangeControls.constants.js';
 import S from './DriversComparisonChart.styl.js';
-import { mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, DRIVER_FORECAST_ID_BASE, INITIAL_VISIBLE_SERIES_COUNT, buildDriversComparisonChartData, formatSeriesImportance } from './driversComparisonChart.helpers.js';
+import { applyDriversComparisonViewToPayload, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, DRIVER_FORECAST_ID_BASE, getLagDisplayForView, resolveDriverLagLabel, INITIAL_VISIBLE_SERIES_COUNT, buildDriversComparisonChartData, formatSeriesImportance } from './driversComparisonChart.helpers.js';
 
 const ALL_TIME_RANGE = TIME_RANGES[TIME_RANGES.length - 1];
 function toForecastDataKey(id) {
     const s = String(id);
     return s.startsWith('forecast_') ? s : `forecast_${id}`;
 }
-function DriversComparisonChart({ payload, datasetHistorical = [], loading = false, chartLoading = false, statusHint = null, statusTone = 'muted', runAnalysisHint = false, timeRange: timeRangeProp, onTimeRangeChange, isDarkTheme = false, className, seriesInitKey, }) {
+function DriversComparisonChart({ payload, datasetHistorical = [], loading = false, chartLoading = false, statusHint = null, statusTone = 'muted', runAnalysisHint = false, timeRange: timeRangeProp, onTimeRangeChange, isDarkTheme = false, className, seriesInitKey, viewTab: viewTabProp, onViewTabChange, }) {
     const [internalTimeRange, setInternalTimeRange] = useState(ALL_TIME_RANGE);
+    const [internalViewTab, setInternalViewTab] = useState('overlapped');
     const [hiddenSeries, setHiddenSeries] = useState(new Set());
+    const viewTab = viewTabProp ?? internalViewTab;
     const timeRange = timeRangeProp ?? internalTimeRange;
     const handleTimeRangeChange = useCallback((val) => {
         if (!val)
@@ -68,42 +70,51 @@ function DriversComparisonChart({ payload, datasetHistorical = [], loading = fal
             return next;
         });
     }, []);
+    const payloadForView = useMemo(() => applyDriversComparisonViewToPayload(payload, viewTab), [payload, viewTab]);
     const sortedDriversWithData = useMemo(() => {
-        const driversList = payload?.drivers ?? [];
+        const driversList = payloadForView?.drivers ?? [];
         if (!driversList.length)
             return [];
         return [...driversList]
             .filter(d => d.normalized_series &&
             Object.keys(d.normalized_series).some(key => d.normalized_series[key] != null))
             .sort((a, b) => String(a.id).localeCompare(String(b.id)));
-    }, [payload?.drivers]);
-    const mergedChartData = useMemo(() => mergeBacktestsChartData(payload), [payload]);
+    }, [payloadForView?.drivers]);
+    const mergedChartData = useMemo(() => mergeBacktestsChartData(payloadForView), [payloadForView]);
     const mergedWithHistorical = useMemo(() => mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical, mergedChartData), [datasetHistorical, mergedChartData]);
     const chartForecastData = useMemo(() => {
-        if (!payload?.target?.normalized_series)
+        if (!payloadForView?.target?.normalized_series)
             return [];
         return sortedDriversWithData.map((driver, idx) => ({
             id: DRIVER_FORECAST_ID_BASE + idx,
             name: driver.name || String(driver.id),
             color: getForecastColor(idx + 1),
         }));
-    }, [payload?.target?.normalized_series, sortedDriversWithData]);
+    }, [payloadForView?.target?.normalized_series, sortedDriversWithData]);
+    const originalDriversById = useMemo(() => {
+        const map = new Map();
+        for (const driver of payload?.drivers ?? []) {
+            map.set(String(driver.id), driver);
+        }
+        return map;
+    }, [payload?.drivers]);
     const tableSeriesRows = useMemo(() => {
         if (sortedDriversWithData.length === 0)
             return [];
         return sortedDriversWithData.map((driver, idx) => {
             const raw = driver.importance;
             const importance = typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+            const lagSource = originalDriversById.get(String(driver.id)) ?? driver;
             return {
                 id: DRIVER_FORECAST_ID_BASE + idx,
                 name: driver.name || String(driver.id),
                 color: getForecastColor(idx + 1),
                 importance,
-                lag: driver.lag,
+                lag: getLagDisplayForView(resolveDriverLagLabel(lagSource), viewTab),
             };
         });
-    }, [sortedDriversWithData]);
-    const seriesInitKeyResolved = seriesInitKey ?? `${tableSeriesRows.map(r => r.id).join(',') || 'none'}`;
+    }, [originalDriversById, sortedDriversWithData, viewTab]);
+    const seriesInitKeyResolved = `${seriesInitKey ?? `${tableSeriesRows.map(r => r.id).join(',') || 'none'}`}:${viewTab}`;
     const backtestsSeriesInitKeyRef = useRef('');
     useEffect(() => {
         if (tableSeriesRows.length === 0)
@@ -125,14 +136,14 @@ function DriversComparisonChart({ payload, datasetHistorical = [], loading = fal
     }, [seriesInitKeyResolved, tableSeriesRows]);
     const driversComparisonChartData = useMemo(() => buildDriversComparisonChartData(mergedWithHistorical, datasetHistorical, chartForecastData.map(f => f.id)), [chartForecastData, datasetHistorical, mergedWithHistorical]);
     const showEmptyOverlay = (runAnalysisHint || Boolean(statusHint)) && !loading;
-    return (jsxs("div", { className: cn(S.root, className), children: [jsxs("div", { className: cn(S.chartShell, loading && S.chartShellLoading), children: [jsx("div", { className: S.chartSlot, children: jsxs("div", { className: S.chartWithOverlay, children: [jsx("div", { className: cn(S.chartInteractiveLayer, showEmptyOverlay && S.chartInteractiveDimmed), children: jsx(ChartAreaInteractive, { disableHistoricalAnimation: true, disableTimeRangeSelector: true, enableTimeRangeBrush: true, chartContainerClassName: S.chartContainer, chartData: driversComparisonChartData, forecastData: chartForecastData, timeRange: timeRange, onTimeRangeChange: handleTimeRangeChange, pinMonth: undefined, onPinMonthChange: () => { }, isDarkTheme: isDarkTheme, loading: chartLoading, hasCombinedData: mergedWithHistorical.length > 0, forecastLineStyle: "solid", showLegend: false, hiddenSeries: hiddenSeries, toggleLegendSeries: toggleSeries, ensureAnalysisSeriesVisible: showSeries }) }), showEmptyOverlay && (jsx("div", { className: S.chartEmptyOverlay, role: "status", "aria-live": "polite", children: jsx("div", { className: S.chartEmptyBlurb, children: jsx(ChartEmptyState, { variant: "inline", hint: runAnalysisHint
+    return (jsxs("div", { className: cn(S.root, className), children: [jsxs("div", { className: cn(S.chartShell, loading && S.chartShellLoading), children: [jsx("div", { className: S.chartSlot, children: jsxs("div", { className: S.chartWithOverlay, children: [jsx("div", { className: cn(S.chartInteractiveLayer, showEmptyOverlay && S.chartInteractiveDimmed), children: jsx(ChartAreaInteractive, { chartRenderId: `drivers-comparison-${viewTab}`, disableHistoricalAnimation: true, disableTimeRangeSelector: true, enableTimeRangeBrush: true, chartContainerClassName: S.chartContainer, chartData: driversComparisonChartData, forecastData: chartForecastData, timeRange: timeRange, onTimeRangeChange: handleTimeRangeChange, pinMonth: undefined, onPinMonthChange: () => { }, isDarkTheme: isDarkTheme, loading: chartLoading, hasCombinedData: mergedWithHistorical.length > 0, forecastLineStyle: "solid", showLegend: false, hiddenSeries: hiddenSeries, toggleLegendSeries: toggleSeries, ensureAnalysisSeriesVisible: showSeries }, viewTab) }), showEmptyOverlay && (jsx("div", { className: S.chartEmptyOverlay, role: "status", "aria-live": "polite", children: jsx("div", { className: S.chartEmptyBlurb, children: jsx(ChartEmptyState, { variant: "inline", hint: runAnalysisHint
                                                 ? 'Run a completed analysis to load the drivers comparison chart for an analysis.'
                                                 : undefined, status: statusHint ?? undefined, statusTone: statusTone }) }) }))] }) }), loading && (jsx("div", { className: S.loadingLayer, "aria-busy": "true", "aria-live": "polite", children: jsx("div", { className: S.loadingMessage, children: jsx(TextShimmer, { as: "span", className: S.loadingText, children: "Loading drivers comparison\u2026" }) }) }))] }), jsx("div", { className: S.seriesSection, children: tableSeriesRows.length === 0 ? (jsx("div", { className: S.seriesEmptyWrap, children: jsx("div", { className: S.chartEmptyBlurb, children: jsx(ChartEmptyState, { variant: "inline", align: "center", status: "No series" }) }) })) : (jsx("div", { className: S.seriesTableWrapper, children: jsx(PageXScroll, { size: "md", fullWidth: true, innerClassName: S.seriesTableContainer, scrollbarClassName: S.seriesScrollbar, children: jsxs(Table, { withBackground: true, withPaddings: true, className: S.seriesTable, children: [jsx(TableHeader, { children: jsxs(TableRow, { children: [jsx(TableHead, { className: S.seriesColSeries, children: "Driver name" }), jsx(TableHead, { children: jsxs(TableCellValue, { children: ["Importance", jsxs(Tooltip, { children: [jsx(TooltipTrigger, { asChild: true, children: jsx("span", { children: jsx(InfoIcon, { size: 16, style: { cursor: 'help' } }) }) }), jsx(TooltipContent, { side: "top", maxWidth: 300, children: "How much this driver contributes to price movements in the forecast model. Higher = stronger influence. Reflects relative weight of each driver, scored from 0% to 100%." })] })] }) }), jsx(TableHead, { children: jsxs(TableCellValue, { children: ["Lag", jsxs(Tooltip, { children: [jsx(TooltipTrigger, { asChild: true, children: jsx("span", { children: jsx(InfoIcon, { size: 16, style: { cursor: 'help' } }) }) }), jsx(TooltipContent, { side: "top", maxWidth: 300, children: "Lag shows how far ahead this driver predicts price movement. A range (e.g. 9\u201312 months) means the predictive signal is strongest somewhere in that window \u2014 not at a single fixed point." })] })] }) })] }) }), jsx(TableBody, { children: tableSeriesRows.map(row => {
                                         const dataKey = toForecastDataKey(row.id);
                                         const hidden = hiddenSeries.has(dataKey);
                                         return (jsxs(TableRow, { className: cn(hidden && S.rowHidden), onClick: () => toggleSeries(row.id), children: [jsx(TableCell, { children: jsxs("span", { className: S.seriesLabel, children: [jsx("span", { className: S.colorSwatch, style: {
                                                                     backgroundColor: row.color,
-                                                                } }), row.name ?? String(row.id)] }) }), jsx(TableCell, { children: formatSeriesImportance(row.importance) }), jsx(TableCell, { children: row.lag ?? '—' })] }, row.id));
+                                                                } }), row.name ?? String(row.id)] }) }), jsx(TableCell, { children: formatSeriesImportance(row.importance) }), jsx(TableCell, { children: row.lag })] }, row.id));
                                     }) })] }) }) })) })] }));
 }
 

package/dist/esm/components/widgets/DriversComparisonChart/driversComparisonChart.helpers.js

@@ -1,4 +1,4 @@
-import { normalizeToMonthStart, getPreviousMonth, getNextMonth } from '../../../utils/chartConnectionPoint.js';
+import { normalizeToMonthStart, getNextMonth, getPreviousMonth } from '../../../utils/chartConnectionPoint.js';
 
 const DRIVER_FORECAST_ID_BASE = 8_000_000;
 const INITIAL_VISIBLE_SERIES_COUNT = 3;
@@ -11,6 +11,95 @@ function formatSeriesImportance(value) {
         return '—';
     return `${value.toFixed(1)}%`;
 }
+function resolveDriverLagLabel(driver) {
+    if (typeof driver.lag === 'string' && driver.lag.trim()) {
+        return driver.lag;
+    }
+    const raw = driver;
+    const overallLag = raw.overall_lag ?? raw.overallLag;
+    if (typeof overallLag === 'string' && overallLag.trim()) {
+        return overallLag;
+    }
+    return null;
+}
+/** Parse lag label to month count; ranges use the upper bound. */
+function parseLagMonthsFromLabel(lag) {
+    if (lag == null)
+        return null;
+    const trimmed = lag.trim();
+    if (!trimmed)
+        return null;
+    const lower = trimmed.toLowerCase().replace(/\u2013|\u2014/g, '-');
+    if (lower === 'unknown' || lower === 'no lag' || lower.includes('no lag')) {
+        return null;
+    }
+    const rangeMatch = lower.match(/(\d+)\s*(?:to|-)\s*(\d+)\s*months?/);
+    if (rangeMatch) {
+        const a = parseInt(rangeMatch[1], 10);
+        const b = parseInt(rangeMatch[2], 10);
+        if (Number.isFinite(a) && Number.isFinite(b))
+            return Math.max(a, b);
+    }
+    const quarterMatch = lower.match(/~?\s*(\d+)\s*quarter/);
+    if (quarterMatch) {
+        const q = parseInt(quarterMatch[1], 10);
+        if (Number.isFinite(q) && q > 0)
+            return q * 3;
+    }
+    const monthMatch = lower.match(/~?\s*(\d+)\s*months?/);
+    if (monthMatch) {
+        const m = parseInt(monthMatch[1], 10);
+        if (Number.isFinite(m) && m > 0)
+            return m;
+    }
+    return null;
+}
+function formatLagMonthsLabel(months) {
+    return `${months} month(s)`;
+}
+function getLagDisplayForView(lag, tab) {
+    if (tab === 'overlapped') {
+        return lag?.trim() ? lag : '—';
+    }
+    const months = parseLagMonthsFromLabel(lag);
+    return months != null ? formatLagMonthsLabel(months) : '—';
+}
+function shiftNormalizedSeriesForward(series, lagMonths) {
+    if (lagMonths <= 0)
+        return { ...series };
+    const out = {};
+    for (const [dateStr, val] of Object.entries(series)) {
+        if (val === null || val === undefined)
+            continue;
+        let shifted = normalizeToMonthStart(dateStr);
+        for (let i = 0; i < lagMonths; i++) {
+            shifted = getNextMonth(shifted);
+        }
+        out[shifted] = val;
+    }
+    return out;
+}
+function applyDriversComparisonViewToPayload(payload, tab) {
+    if (!payload || tab === 'overlapped')
+        return payload;
+    return {
+        target: {
+            ...payload.target,
+            normalized_series: { ...payload.target.normalized_series },
+        },
+        drivers: payload.drivers.map(driver => {
+            const lagMonths = parseLagMonthsFromLabel(resolveDriverLagLabel(driver));
+            const series = driver.normalized_series ?? {};
+            const normalized_series = lagMonths != null && lagMonths > 0
+                ? shiftNormalizedSeriesForward(series, lagMonths)
+                : { ...series };
+            return {
+                ...driver,
+                normalized_series,
+            };
+        }),
+    };
+}
 function mergeBacktestsChartData(payload) {
     if (!payload?.target?.normalized_series)
         return [];
@@ -156,4 +245,4 @@ function buildDriversComparisonChartData(mergedWithHistorical, datasetHistorical
     return withLead.filter(p => normalizeToMonthStart(p.date) >= xMin);
 }
 
-export { DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, INITIAL_VISIBLE_SERIES_COUNT, buildDriversComparisonChartData, formatSeriesImportance, getZoomAnchorMonthFromDriverMaterialStarts, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, prependHistoricalLeadFromDataset, subtractMonthsFromMonthStart };
+export { DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, INITIAL_VISIBLE_SERIES_COUNT, applyDriversComparisonViewToPayload, buildDriversComparisonChartData, formatLagMonthsLabel, formatSeriesImportance, getLagDisplayForView, getZoomAnchorMonthFromDriverMaterialStarts, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, parseLagMonthsFromLabel, prependHistoricalLeadFromDataset, resolveDriverLagLabel, shiftNormalizedSeriesForward, subtractMonthsFromMonthStart };

package/dist/esm/index.js

@@ -108,7 +108,7 @@ export { getCategoryIcon } from './components/widgets/DriverMap/driverCategoryIc
 export { getDriverImportance, getHighestImportanceDriver } from './components/widgets/DriverMap/driverMapSelection.js';
 export { geographicCoordinates, geographicToSVG, getContinentFromRegion, getPreciseCoordinates, getResponsiveCoordinates, svgToPercentage } from './components/widgets/DriverMap/driverMapGeography.js';
 export { DriversComparisonChart } from './components/widgets/DriversComparisonChart/DriversComparisonChart.js';
-export { DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, INITIAL_VISIBLE_SERIES_COUNT, buildDriversComparisonChartData, formatSeriesImportance, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData } from './components/widgets/DriversComparisonChart/driversComparisonChart.helpers.js';
+export { DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, INITIAL_VISIBLE_SERIES_COUNT, applyDriversComparisonViewToPayload, buildDriversComparisonChartData, formatLagMonthsLabel, formatSeriesImportance, getLagDisplayForView, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, parseLagMonthsFromLabel, resolveDriverLagLabel, shiftNormalizedSeriesForward } from './components/widgets/DriversComparisonChart/driversComparisonChart.helpers.js';
 export { PerformanceChart } from './components/widgets/PerformanceChart/PerformanceChart.js';
 export { PerformanceTable } from './components/widgets/PerformanceChart/PerformanceTable.js';
 export { SPAGHETTI_DRIFT_PER_HORIZON_ID_BASE, SPAGHETTI_MODEL_PER_HORIZON_ID_BASE, averageForecastErrorsVsHistoricalForMatrixColumn, buildDriftSpaghettiMatrixForCustomDialog, buildPerHorizonSpaghettiEntries, buildSpaghettiMergedChartData, calculateYRangeFromChartData, getForecastModelDisplayName, spaghettiGridFromHistoricalPreviousMonth } from './components/widgets/PerformanceChart/performanceChart.helpers.js';

package/dist/esm/types/src/components/widgets/DriversComparisonChart/DriversComparisonChart.d.ts

@@ -1,5 +1,6 @@
 import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
 import type { BacktestsComponentPayload } from '@sybilion/platform-sdk';
+import { type DriversComparisonViewTab } from './driversComparisonChart.helpers';
 export type DriversComparisonChartProps = {
     payload: BacktestsComponentPayload | null;
     datasetHistorical?: ChartDataPoint[];
@@ -14,5 +15,8 @@ export type DriversComparisonChartProps = {
     className?: string;
     /** Resets visible series when this key changes (e.g. selected analysis id). */
     seriesInitKey?: string;
+    viewTab?: DriversComparisonViewTab;
+    onViewTabChange?: (tab: DriversComparisonViewTab) => void;
 };
-export declare function DriversComparisonChart({ payload, datasetHistorical, loading, chartLoading, statusHint, statusTone, runAnalysisHint, timeRange: timeRangeProp, onTimeRangeChange, isDarkTheme, className, seriesInitKey, }: DriversComparisonChartProps): import("react/jsx-runtime").JSX.Element;
+export type { DriversComparisonViewTab } from './driversComparisonChart.helpers';
+export declare function DriversComparisonChart({ payload, datasetHistorical, loading, chartLoading, statusHint, statusTone, runAnalysisHint, timeRange: timeRangeProp, onTimeRangeChange, isDarkTheme, className, seriesInitKey, viewTab: viewTabProp, onViewTabChange, }: DriversComparisonChartProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/src/components/widgets/DriversComparisonChart/driversComparisonChart.helpers.d.ts

@@ -4,7 +4,17 @@ export declare const DRIVER_FORECAST_ID_BASE = 8000000;
 export declare const INITIAL_VISIBLE_SERIES_COUNT = 3;
 /** Months of historical context before the earliest forecast month (inclusive). */
 export declare const DRIVER_COMPARISON_CHART_LEAD_MONTHS = 6;
+export type DriversComparisonViewTab = 'overlapped' | 'lagged';
 export declare function formatSeriesImportance(value: number | null): string;
+export declare function resolveDriverLagLabel(driver: {
+    lag?: string | null;
+}): string | null;
+/** Parse lag label to month count; ranges use the upper bound. */
+export declare function parseLagMonthsFromLabel(lag: string | null | undefined): number | null;
+export declare function formatLagMonthsLabel(months: number): string;
+export declare function getLagDisplayForView(lag: string | null | undefined, tab: DriversComparisonViewTab): string;
+export declare function shiftNormalizedSeriesForward(series: Record<string, number | null>, lagMonths: number): Record<string, number | null>;
+export declare function applyDriversComparisonViewToPayload(payload: BacktestsComponentPayload | null, tab: DriversComparisonViewTab): BacktestsComponentPayload | null;
 export declare function mergeBacktestsChartData(payload: BacktestsComponentPayload | null): ChartDataPoint[];
 /** While drivers comparison is not loaded: dataset historical only. After load: normalized historical from target.normalized_series (see mergeBacktestsChartData) replaces it. */
 export declare function mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical: ChartDataPoint[], backtestsMerged: ChartDataPoint[]): ChartDataPoint[];

package/dist/esm/types/src/components/widgets/DriversComparisonChart/driversComparisonChart.helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/src/components/widgets/DriversComparisonChart/index.d.ts

@@ -1,2 +1,2 @@
-export { DriversComparisonChart, type DriversComparisonChartProps, } from './DriversComparisonChart';
-export { buildDriversComparisonChartData, DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, formatSeriesImportance, INITIAL_VISIBLE_SERIES_COUNT, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, } from './driversComparisonChart.helpers';
+export { DriversComparisonChart, type DriversComparisonChartProps, type DriversComparisonViewTab, } from './DriversComparisonChart';
+export { applyDriversComparisonViewToPayload, buildDriversComparisonChartData, DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, formatLagMonthsLabel, formatSeriesImportance, getLagDisplayForView, resolveDriverLagLabel, INITIAL_VISIBLE_SERIES_COUNT, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, parseLagMonthsFromLabel, shiftNormalizedSeriesForward, } from './driversComparisonChart.helpers';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.3.54",
+  "version": "1.3.55",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",

package/src/components/widgets/DriversComparisonChart/AGENT.md

@@ -10,9 +10,14 @@ Host provides:
 - `payload`: BacktestsComponentPayload from platform SDK (host fetch per analysis)
 - Optional `datasetHistorical` overlay
 - `seriesInitKey` when selected analysis changes
+- `viewTab` / `onViewTabChange`: `overlapped` (calendar-aligned) or `lagged` (driver series shifted forward by parsed lag months)
+
+View tabs: host should render uilib `Tabs variant="button"` with **Lagged** / **Overlapped** in the toolbar (analysis selector left, tabs right). Chart applies `applyDriversComparisonViewToPayload` internally.
 
 Report tile: `drivers_comparison_chart` — host loads normalized backtests payload + dataset historical; built-in analysis selector.
 
-Requires: `payload` — target + driver normalized_series; `loading` / `chartLoading` — spinners; `seriesInitKey` — reset visible series on analysis change; `runAnalysisHint` / `statusHint` — empty/error text.
+Requires: `payload` — target + driver normalized_series; `loading` / `chartLoading` — spinners; `seriesInitKey` — reset visible series on analysis or view tab change; `runAnalysisHint` / `statusHint` — empty/error text.
+
+Lag column: **Overlapped** shows API `lag` string (may be a range). **Lagged** shows single `N month(s)` from `parseLagMonthsFromLabel` (range uses max month).
 
 Empty/loading: loading props shimmer chart; null `payload` with `runAnalysisHint` prompts to run analysis.

package/src/components/widgets/DriversComparisonChart/DriversComparisonChart.tsx

@@ -31,11 +31,15 @@ import { InfoIcon } from 'lucide-react';
 import S from './DriversComparisonChart.styl';
 import {
   DRIVER_FORECAST_ID_BASE,
+  type DriversComparisonViewTab,
   INITIAL_VISIBLE_SERIES_COUNT,
+  applyDriversComparisonViewToPayload,
   buildDriversComparisonChartData,
   formatSeriesImportance,
+  getLagDisplayForView,
   mergeBacktestsChartData,
   mergeDatasetHistoricalWithBacktestsChartData,
+  resolveDriverLagLabel,
 } from './driversComparisonChart.helpers';
 
 const ALL_TIME_RANGE = TIME_RANGES[TIME_RANGES.length - 1];
@@ -59,8 +63,12 @@ export type DriversComparisonChartProps = {
   className?: string;
   /** Resets visible series when this key changes (e.g. selected analysis id). */
   seriesInitKey?: string;
+  viewTab?: DriversComparisonViewTab;
+  onViewTabChange?: (tab: DriversComparisonViewTab) => void;
 };
 
+export type { DriversComparisonViewTab } from './driversComparisonChart.helpers';
+
 export function DriversComparisonChart({
   payload,
   datasetHistorical = [],
@@ -74,11 +82,17 @@ export function DriversComparisonChart({
   isDarkTheme = false,
   className,
   seriesInitKey,
+  viewTab: viewTabProp,
+  onViewTabChange,
 }: DriversComparisonChartProps) {
   const [internalTimeRange, setInternalTimeRange] =
     useState<string>(ALL_TIME_RANGE);
+  const [internalViewTab, setInternalViewTab] =
+    useState<DriversComparisonViewTab>('overlapped');
   const [hiddenSeries, setHiddenSeries] = useState<Set<string>>(new Set());
 
+  const viewTab = viewTabProp ?? internalViewTab;
+
   const timeRange = timeRangeProp ?? internalTimeRange;
   const handleTimeRangeChange = useCallback(
     (val: string) => {
@@ -111,8 +125,13 @@ export function DriversComparisonChart({
     });
   }, []);
 
+  const payloadForView = useMemo(
+    () => applyDriversComparisonViewToPayload(payload, viewTab),
+    [payload, viewTab],
+  );
+
   const sortedDriversWithData = useMemo(() => {
-    const driversList = payload?.drivers ?? [];
+    const driversList = payloadForView?.drivers ?? [];
     if (!driversList.length) return [];
     return [...driversList]
       .filter(
@@ -123,11 +142,11 @@ export function DriversComparisonChart({
           ),
       )
       .sort((a, b) => String(a.id).localeCompare(String(b.id)));
-  }, [payload?.drivers]);
+  }, [payloadForView?.drivers]);
 
   const mergedChartData = useMemo(
-    () => mergeBacktestsChartData(payload),
-    [payload],
+    () => mergeBacktestsChartData(payloadForView),
+    [payloadForView],
   );
 
   const mergedWithHistorical = useMemo(
@@ -140,13 +159,21 @@ export function DriversComparisonChart({
   );
 
   const chartForecastData = useMemo((): ForecastItemData[] => {
-    if (!payload?.target?.normalized_series) return [];
+    if (!payloadForView?.target?.normalized_series) return [];
     return sortedDriversWithData.map((driver, idx) => ({
       id: DRIVER_FORECAST_ID_BASE + idx,
       name: driver.name || String(driver.id),
       color: getForecastColor(idx + 1),
     }));
-  }, [payload?.target?.normalized_series, sortedDriversWithData]);
+  }, [payloadForView?.target?.normalized_series, sortedDriversWithData]);
+
+  const originalDriversById = useMemo(() => {
+    const map = new Map<string, (typeof sortedDriversWithData)[number]>();
+    for (const driver of payload?.drivers ?? []) {
+      map.set(String(driver.id), driver);
+    }
+    return map;
+  }, [payload?.drivers]);
 
   const tableSeriesRows = useMemo(() => {
     if (sortedDriversWithData.length === 0) return [];
@@ -154,18 +181,18 @@ export function DriversComparisonChart({
       const raw = driver.importance;
       const importance =
         typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+      const lagSource = originalDriversById.get(String(driver.id)) ?? driver;
       return {
         id: DRIVER_FORECAST_ID_BASE + idx,
         name: driver.name || String(driver.id),
         color: getForecastColor(idx + 1),
         importance,
-        lag: driver.lag,
+        lag: getLagDisplayForView(resolveDriverLagLabel(lagSource), viewTab),
       };
     });
-  }, [sortedDriversWithData]);
+  }, [originalDriversById, sortedDriversWithData, viewTab]);
 
-  const seriesInitKeyResolved =
-    seriesInitKey ?? `${tableSeriesRows.map(r => r.id).join(',') || 'none'}`;
+  const seriesInitKeyResolved = `${seriesInitKey ?? `${tableSeriesRows.map(r => r.id).join(',') || 'none'}`}:${viewTab}`;
 
   const backtestsSeriesInitKeyRef = useRef<string>('');
 
@@ -211,6 +238,8 @@ export function DriversComparisonChart({
               )}
             >
               <ChartAreaInteractive
+                key={viewTab}
+                chartRenderId={`drivers-comparison-${viewTab}`}
                 disableHistoricalAnimation
                 disableTimeRangeSelector
                 enableTimeRangeBrush
@@ -351,7 +380,7 @@ export function DriversComparisonChart({
                         <TableCell>
                           {formatSeriesImportance(row.importance)}
                         </TableCell>
-                        <TableCell>{row.lag ?? '—'}</TableCell>
+                        <TableCell>{row.lag}</TableCell>
                       </TableRow>
                     );
                   })}

package/src/components/widgets/DriversComparisonChart/driversComparisonChart.helpers.test.ts

@@ -0,0 +1,135 @@
+import {
+  applyDriversComparisonViewToPayload,
+  formatLagMonthsLabel,
+  getLagDisplayForView,
+  parseLagMonthsFromLabel,
+  resolveDriverLagLabel,
+  shiftNormalizedSeriesForward,
+} from './driversComparisonChart.helpers';
+
+describe('parseLagMonthsFromLabel', () => {
+  it('uses max month for ranges', () => {
+    expect(parseLagMonthsFromLabel('9 to 12 month(s)')).toBe(12);
+  });
+
+  it('parses single month labels', () => {
+    expect(parseLagMonthsFromLabel('2 month(s)')).toBe(2);
+    expect(parseLagMonthsFromLabel('~1 month(s)')).toBe(1);
+  });
+
+  it('converts quarters to months', () => {
+    expect(parseLagMonthsFromLabel('1 quarter(s)')).toBe(3);
+  });
+
+  it('returns null for unknown or empty labels', () => {
+    expect(parseLagMonthsFromLabel('Unknown')).toBeNull();
+    expect(parseLagMonthsFromLabel('no lag')).toBeNull();
+    expect(parseLagMonthsFromLabel('')).toBeNull();
+    expect(parseLagMonthsFromLabel(null)).toBeNull();
+  });
+
+  it('parses en-dash month ranges', () => {
+    expect(parseLagMonthsFromLabel('9–12 month(s)')).toBe(12);
+  });
+});
+
+describe('resolveDriverLagLabel', () => {
+  it('reads lag or overall_lag', () => {
+    expect(resolveDriverLagLabel({ lag: '2 month(s)' })).toBe('2 month(s)');
+    expect(resolveDriverLagLabel({ overall_lag: '3 month(s)' })).toBe(
+      '3 month(s)',
+    );
+  });
+});
+
+describe('formatLagMonthsLabel', () => {
+  it('formats month count', () => {
+    expect(formatLagMonthsLabel(12)).toBe('12 month(s)');
+  });
+});
+
+describe('getLagDisplayForView', () => {
+  it('shows API lag on overlapped tab', () => {
+    expect(getLagDisplayForView('9 to 12 month(s)', 'overlapped')).toBe(
+      '9 to 12 month(s)',
+    );
+  });
+
+  it('shows parsed month on lagged tab', () => {
+    expect(getLagDisplayForView('9 to 12 month(s)', 'lagged')).toBe(
+      '12 month(s)',
+    );
+    expect(getLagDisplayForView('Unknown', 'lagged')).toBe('—');
+  });
+});
+
+describe('shiftNormalizedSeriesForward', () => {
+  it('moves points forward by lag months', () => {
+    const shifted = shiftNormalizedSeriesForward(
+      { '2015-01-01': 1.2, '2015-02-01': 1.4 },
+      2,
+    );
+    expect(shifted['2015-03-01']).toBe(1.2);
+    expect(shifted['2015-04-01']).toBe(1.4);
+  });
+
+  it('returns a shallow copy when lag is zero', () => {
+    const series = { '2015-01-01': 1 };
+    const shifted = shiftNormalizedSeriesForward(series, 0);
+    expect(shifted).toEqual(series);
+    expect(shifted).not.toBe(series);
+  });
+});
+
+describe('applyDriversComparisonViewToPayload', () => {
+  const payload = {
+    target: {
+      id: 'target',
+      name: 'Target',
+      normalized_series: { '2015-01-01': 1 },
+    },
+    drivers: [
+      {
+        id: 'd1',
+        name: 'Driver',
+        lag: '2 month(s)',
+        normalized_series: { '2015-01-01': 0.5 },
+      },
+    ],
+  };
+
+  it('returns original payload for overlapped tab', () => {
+    expect(applyDriversComparisonViewToPayload(payload, 'overlapped')).toBe(
+      payload,
+    );
+  });
+
+  it('shifts driver series for lagged tab without mutating source', () => {
+    const lagged = applyDriversComparisonViewToPayload(payload, 'lagged');
+    expect(lagged).not.toBe(payload);
+    expect(payload.drivers[0].normalized_series['2015-01-01']).toBe(0.5);
+    expect(lagged?.drivers[0].normalized_series['2015-03-01']).toBe(0.5);
+    expect(lagged?.target.normalized_series).toEqual(
+      payload.target.normalized_series,
+    );
+  });
+
+  it('shifts using overall_lag when lag is absent', () => {
+    const withOverallLag = {
+      ...payload,
+      drivers: [
+        {
+          id: 'd2',
+          name: 'Driver 2',
+          overall_lag: '1 month(s)',
+          normalized_series: { '2015-06-01': 0.8 },
+        },
+      ],
+    };
+    const lagged = applyDriversComparisonViewToPayload(
+      withOverallLag,
+      'lagged',
+    );
+    expect(lagged?.drivers[0].normalized_series['2015-07-01']).toBe(0.8);
+  });
+});

package/src/components/widgets/DriversComparisonChart/driversComparisonChart.helpers.ts

@@ -11,6 +11,8 @@ export const INITIAL_VISIBLE_SERIES_COUNT = 3;
 /** Months of historical context before the earliest forecast month (inclusive). */
 export const DRIVER_COMPARISON_CHART_LEAD_MONTHS = 6;
 
+export type DriversComparisonViewTab = 'overlapped' | 'lagged';
+
 /** Ignore leading months where drivers are numerically zero (API often fills 0; lines look empty until real signal). */
 const DRIVER_FORECAST_NONZERO_EPS = 1e-9;
 
@@ -19,6 +21,112 @@ export function formatSeriesImportance(value: number | null): string {
   return `${value.toFixed(1)}%`;
 }
 
+export function resolveDriverLagLabel(driver: {
+  lag?: string | null;
+}): string | null {
+  if (typeof driver.lag === 'string' && driver.lag.trim()) {
+    return driver.lag;
+  }
+  const raw = driver as Record<string, unknown>;
+  const overallLag = raw.overall_lag ?? raw.overallLag;
+  if (typeof overallLag === 'string' && overallLag.trim()) {
+    return overallLag;
+  }
+  return null;
+}
+
+/** Parse lag label to month count; ranges use the upper bound. */
+export function parseLagMonthsFromLabel(
+  lag: string | null | undefined,
+): number | null {
+  if (lag == null) return null;
+  const trimmed = lag.trim();
+  if (!trimmed) return null;
+  const lower = trimmed.toLowerCase().replace(/\u2013|\u2014/g, '-');
+  if (lower === 'unknown' || lower === 'no lag' || lower.includes('no lag')) {
+    return null;
+  }
+
+  const rangeMatch = lower.match(/(\d+)\s*(?:to|-)\s*(\d+)\s*months?/);
+  if (rangeMatch) {
+    const a = parseInt(rangeMatch[1], 10);
+    const b = parseInt(rangeMatch[2], 10);
+    if (Number.isFinite(a) && Number.isFinite(b)) return Math.max(a, b);
+  }
+
+  const quarterMatch = lower.match(/~?\s*(\d+)\s*quarter/);
+  if (quarterMatch) {
+    const q = parseInt(quarterMatch[1], 10);
+    if (Number.isFinite(q) && q > 0) return q * 3;
+  }
+
+  const monthMatch = lower.match(/~?\s*(\d+)\s*months?/);
+  if (monthMatch) {
+    const m = parseInt(monthMatch[1], 10);
+    if (Number.isFinite(m) && m > 0) return m;
+  }
+
+  return null;
+}
+
+export function formatLagMonthsLabel(months: number): string {
+  return `${months} month(s)`;
+}
+
+export function getLagDisplayForView(
+  lag: string | null | undefined,
+  tab: DriversComparisonViewTab,
+): string {
+  if (tab === 'overlapped') {
+    return lag?.trim() ? lag : '—';
+  }
+  const months = parseLagMonthsFromLabel(lag);
+  return months != null ? formatLagMonthsLabel(months) : '—';
+}
+
+export function shiftNormalizedSeriesForward(
+  series: Record<string, number | null>,
+  lagMonths: number,
+): Record<string, number | null> {
+  if (lagMonths <= 0) return { ...series };
+  const out: Record<string, number | null> = {};
+  for (const [dateStr, val] of Object.entries(series)) {
+    if (val === null || val === undefined) continue;
+    let shifted = normalizeToMonthStart(dateStr);
+    for (let i = 0; i < lagMonths; i++) {
+      shifted = getNextMonth(shifted);
+    }
+    out[shifted] = val;
+  }
+  return out;
+}
+
+export function applyDriversComparisonViewToPayload(
+  payload: BacktestsComponentPayload | null,
+  tab: DriversComparisonViewTab,
+): BacktestsComponentPayload | null {
+  if (!payload || tab === 'overlapped') return payload;
+
+  return {
+    target: {
+      ...payload.target,
+      normalized_series: { ...payload.target.normalized_series },
+    },
+    drivers: payload.drivers.map(driver => {
+      const lagMonths = parseLagMonthsFromLabel(resolveDriverLagLabel(driver));
+      const series = driver.normalized_series ?? {};
+      const normalized_series =
+        lagMonths != null && lagMonths > 0
+          ? shiftNormalizedSeriesForward(series, lagMonths)
+          : { ...series };
+      return {
+        ...driver,
+        normalized_series,
+      };
+    }),
+  };
+}
+
 export function mergeBacktestsChartData(
   payload: BacktestsComponentPayload | null,
 ): ChartDataPoint[] {

package/src/components/widgets/DriversComparisonChart/index.ts

@@ -1,13 +1,20 @@
 export {
   DriversComparisonChart,
   type DriversComparisonChartProps,
+  type DriversComparisonViewTab,
 } from './DriversComparisonChart';
 export {
+  applyDriversComparisonViewToPayload,
   buildDriversComparisonChartData,
   DRIVER_COMPARISON_CHART_LEAD_MONTHS,
   DRIVER_FORECAST_ID_BASE,
+  formatLagMonthsLabel,
   formatSeriesImportance,
+  getLagDisplayForView,
+  resolveDriverLagLabel,
   INITIAL_VISIBLE_SERIES_COUNT,
   mergeBacktestsChartData,
   mergeDatasetHistoricalWithBacktestsChartData,
+  parseLagMonthsFromLabel,
+  shiftNormalizedSeriesForward,
 } from './driversComparisonChart.helpers';

package/src/docs/pages/DriversComparisonChartPage.tsx

@@ -3,8 +3,12 @@ import { useMemo, useState } from 'react';
 import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
 import { PageContentSection } from '#uilib/components/ui/Page';
 import { Switch } from '#uilib/components/ui/Switch';
+import { Tabs, TabsList, TabsTrigger } from '#uilib/components/ui/Tabs';
 import { TIME_RANGES } from '#uilib/components/ui/TimeRangeControls/TimeRangeControls.constants';
-import { DriversComparisonChart } from '#uilib/components/widgets/DriversComparisonChart';
+import {
+  DriversComparisonChart,
+  type DriversComparisonViewTab,
+} from '#uilib/components/widgets/DriversComparisonChart';
 import { useTheme } from '#uilib/contexts/theme-context';
 import type { BacktestsComponentPayload } from '@sybilion/platform-sdk';
 
@@ -82,7 +86,7 @@ const MOCK_PAYLOAD: BacktestsComponentPayload = {
       id: 'driver-china-credit',
       name: 'China aggregate financing impulse',
       importance: 58.3,
-      lag: '3 month(s)',
+      lag: '9 to 12 month(s)',
       normalized_series: buildMonthlySeries(2020, 1, 36, 0.29, 0.018, 4.2),
     },
   ],
@@ -102,6 +106,8 @@ export default function DriversComparisonChartPage() {
   const [runAnalysisHint, setRunAnalysisHint] = useState(false);
   const [emptyPayload, setEmptyPayload] = useState(false);
   const [timeRange, setTimeRange] = useState<string>(ALL_TIME_RANGE);
+  const [viewTab, setViewTab] =
+    useState<DriversComparisonViewTab>('overlapped');
 
   const payload = useMemo(
     () => (emptyPayload ? null : MOCK_PAYLOAD),
@@ -114,7 +120,7 @@ export default function DriversComparisonChartPage() {
       <AppPageHeader
         breadcrumbs={[{ label: 'Drivers comparison chart' }]}
         title="DriversComparisonChart"
-        subheader="Normalized target line with driver series; table rows toggle chart visibility."
+        subheader="Normalized target line with driver series; Lagged/Overlapped tabs shift driver alignment; table rows toggle chart visibility."
         actions={<DocsHeaderActions />}
       />
       <PageContentSection>
@@ -152,6 +158,28 @@ export default function DriversComparisonChartPage() {
             <label htmlFor="empty-payload">Empty payload</label>
           </div>
         </div>
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'flex-end',
+            marginBottom: 16,
+          }}
+        >
+          <Tabs
+            variant="button"
+            value={viewTab}
+            onValueChange={v => {
+              if (v === 'lagged' || v === 'overlapped') {
+                setViewTab(v);
+              }
+            }}
+          >
+            <TabsList>
+              <TabsTrigger value="lagged">Lagged</TabsTrigger>
+              <TabsTrigger value="overlapped">Overlapped</TabsTrigger>
+            </TabsList>
+          </Tabs>
+        </div>
         <DriversComparisonChart
           payload={payload}
           datasetHistorical={datasetHistorical}
@@ -167,6 +195,8 @@ export default function DriversComparisonChartPage() {
           onTimeRangeChange={setTimeRange}
           isDarkTheme={isDarkMode}
           seriesInitKey={emptyPayload ? 'empty' : 'mock'}
+          viewTab={viewTab}
+          onViewTabChange={setViewTab}
         />
       </PageContentSection>
     </>