@sybilion/uilib 1.3.22 → 1.3.23

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

@@ -0,0 +1,139 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import cn from 'classnames';
+import { useState, useCallback, useMemo, useRef, useEffect } from 'react';
+import { ChartEmptyState } from '../../ui/Chart/components/ChartEmptyState/ChartEmptyState.js';
+import { ChartAreaInteractive } from '../../ui/ChartAreaInteractive/ChartAreaInteractive.js';
+import { getForecastColor } from '../../ui/ChartAreaInteractive/ChartLines.js';
+import '../../ui/Page/AppShell/AppShell.js';
+import 'react-router-dom';
+import '../../ui/Sidebar/Sidebar.js';
+import 'lucide-react';
+import '../../ui/Page/Breadcrumbs/Breadcrumbs.styl.js';
+import '../../ui/Page/pageContext.js';
+import '@radix-ui/react-tooltip';
+import '../../ui/Tooltip/Tooltip.styl.js';
+import '../../ui/Page/PageHeader/PageHeader.styl.js';
+import '../../ui/Page/PageEmptyCanvas/PageEmptyCanvas.styl.js';
+import '../../ui/Page/PageContent/PageContent.styl.js';
+import '@homecode/ui';
+import '../../ui/Page/PageScroll/PageScroll.styl.js';
+import { PageXScroll } from '../../ui/Page/PageXScroll/PageXScroll.js';
+import '../../ui/Page/PageFooter/PageFooter.styl.js';
+import '@radix-ui/react-tabs';
+import '../../ui/Tabs/Tabs.styl.js';
+import '../../ui/Page/PageTabs/PageTabs.styl.js';
+import '../../ui/Page/PageColumns/PageColumns.styl.js';
+import '../../ui/Page/SectionHeader/SectionHeader.styl.js';
+import { Table, TableHeader, TableRow, TableHead, TableBody, TableCell } from '../../ui/Table/Table.js';
+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';
+
+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, }) {
+    const [internalTimeRange, setInternalTimeRange] = useState(ALL_TIME_RANGE);
+    const [hiddenSeries, setHiddenSeries] = useState(new Set());
+    const timeRange = timeRangeProp ?? internalTimeRange;
+    const handleTimeRangeChange = useCallback((val) => {
+        if (!val)
+            return;
+        onTimeRangeChange?.(val);
+        if (timeRangeProp === undefined) {
+            setInternalTimeRange(val);
+        }
+    }, [onTimeRangeChange, timeRangeProp]);
+    const toggleSeries = useCallback((id) => {
+        const key = toForecastDataKey(id);
+        setHiddenSeries(prev => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else
+                next.add(key);
+            return next;
+        });
+    }, []);
+    const showSeries = useCallback((id) => {
+        const key = toForecastDataKey(id);
+        setHiddenSeries(prev => {
+            if (!prev.has(key))
+                return prev;
+            const next = new Set(prev);
+            next.delete(key);
+            return next;
+        });
+    }, []);
+    const sortedDriversWithData = useMemo(() => {
+        const driversList = payload?.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]);
+    const mergedWithHistorical = useMemo(() => mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical, mergedChartData), [datasetHistorical, mergedChartData]);
+    const chartForecastData = useMemo(() => {
+        if (!payload?.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]);
+    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;
+            return {
+                id: DRIVER_FORECAST_ID_BASE + idx,
+                name: driver.name || String(driver.id),
+                color: getForecastColor(idx + 1),
+                importance,
+                lag: driver.lag,
+            };
+        });
+    }, [sortedDriversWithData]);
+    const seriesInitKeyResolved = seriesInitKey ?? `${tableSeriesRows.map(r => r.id).join(',') || 'none'}`;
+    const backtestsSeriesInitKeyRef = useRef('');
+    useEffect(() => {
+        if (tableSeriesRows.length === 0)
+            return;
+        const initKey = seriesInitKeyResolved;
+        if (backtestsSeriesInitKeyRef.current === initKey)
+            return;
+        backtestsSeriesInitKeyRef.current = initKey;
+        setHiddenSeries(() => {
+            const next = new Set();
+            tableSeriesRows.forEach((row, idx) => {
+                const key = toForecastDataKey(row.id);
+                if (idx >= INITIAL_VISIBLE_SERIES_COUNT) {
+                    next.add(key);
+                }
+            });
+            return next;
+        });
+    }, [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
+                                                ? '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: "Importance" }), jsx(TableHead, { children: "Lag" })] }) }), 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));
+                                    }) })] }) }) })) })] }));
+}
+
+export { DriversComparisonChart };

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

@@ -0,0 +1,7 @@
+import styleInject from 'style-inject';
+
+var css_248z = "@media (max-width:768px){:root{--page-x-padding:var(--p-6);--page-y-padding:var(--p-6)}}.DriversComparisonChart_root__GLnlF{display:flex;flex-direction:column;gap:var(--p-4);width:100%}.DriversComparisonChart_chartShell__0AzAz{position:relative;width:100%}.DriversComparisonChart_chartShellLoading__wTLod .DriversComparisonChart_chartSlot__WKe6N{opacity:.3;pointer-events:none}.DriversComparisonChart_chartShellLoading__wTLod .recharts-line-dots{display:none}.DriversComparisonChart_chartSlot__WKe6N{width:100%}.DriversComparisonChart_loadingLayer__HlEmA{inset:0;pointer-events:none;position:absolute;z-index:10}.DriversComparisonChart_loadingMessage__Li3S7{color:var(--foreground);display:block;left:0;position:absolute;text-align:center;top:calc(50% - 4em);width:100%;z-index:1}.DriversComparisonChart_loadingText__0y3Ms{backdrop-filter:blur(10px);border-radius:var(--p-4);box-shadow:0 0 0 2px var(--page-color);color:var(--foreground);font-size:16px;font-weight:500;padding:0 var(--p-3)}.DriversComparisonChart_chartWithOverlay__SMToK{position:relative;width:100%}.DriversComparisonChart_chartInteractiveLayer__0aquh{transition:opacity .2s ease-out;width:100%}.DriversComparisonChart_chartInteractiveDimmed__us1dv{opacity:.3;pointer-events:none}.DriversComparisonChart_chartInteractiveDimmed__us1dv .recharts-line-dots{display:none}.DriversComparisonChart_chartEmptyOverlay__eXqzk{align-items:center;display:flex;inset:0;justify-content:center;padding:var(--p-4);pointer-events:none;position:absolute;z-index:6}.DriversComparisonChart_chartEmptyBlurb__Tjy9E{max-width:42rem;padding:0 var(--p-3)}.DriversComparisonChart_seriesEmptyWrap__RyRs5{display:flex;justify-content:center;padding:var(--p-8) var(--p-4)}.DriversComparisonChart_seriesSection__yrf4I{width:100%}.DriversComparisonChart_seriesTableWrapper__oredC{margin:0 calc(var(--page-x-padding)*-1);position:relative}.DriversComparisonChart_seriesTableContainer__dhfXK{overflow-x:auto;position:relative;width:100%}.DriversComparisonChart_seriesScrollbar__2jgk6{bottom:calc(var(--p-7)*-1 + 2px)!important}.DriversComparisonChart_seriesTable__NybPR{max-width:100%;table-layout:auto;width:100%}.DriversComparisonChart_seriesTable__NybPR tr{cursor:pointer;position:relative}.DriversComparisonChart_seriesTable__NybPR td:not(:first-child),.DriversComparisonChart_seriesTable__NybPR th:not(:first-child){text-align:right}.DriversComparisonChart_seriesColSeries__--0mj{text-align:left;vertical-align:middle}.DriversComparisonChart_rowHidden__Fwhna{opacity:.4}.DriversComparisonChart_colorSwatch__o3ZVr{border-radius:2px;display:inline-flex;flex-shrink:0;height:10px;margin-right:var(--p-2);width:10px}.DriversComparisonChart_seriesLabel__Aidof{display:-webkit-box;-webkit-line-clamp:3;max-width:60vw;min-width:0;padding:var(--p-2) 0;-webkit-box-orient:vertical;white-space:break-spaces}.DriversComparisonChart_chartContainer__1eM-O{margin-left:calc(var(--page-x-padding)*-1 + 26px);max-width:calc(100% + 60px);transition:opacity .3s ease-out;width:calc(100% + 60px)}.DriversComparisonChart_chartContainer__1eM-O .recharts-yAxis-tick-labels{display:none}@media (max-width:768px){.DriversComparisonChart_chartContainer__1eM-O{margin-left:calc(var(--page-x-padding)*-1 + 10px);width:calc(100% + 30px)}}";
+var S = {"root":"DriversComparisonChart_root__GLnlF","chartShell":"DriversComparisonChart_chartShell__0AzAz","chartShellLoading":"DriversComparisonChart_chartShellLoading__wTLod","chartSlot":"DriversComparisonChart_chartSlot__WKe6N","loadingLayer":"DriversComparisonChart_loadingLayer__HlEmA","loadingMessage":"DriversComparisonChart_loadingMessage__Li3S7","loadingText":"DriversComparisonChart_loadingText__0y3Ms","chartWithOverlay":"DriversComparisonChart_chartWithOverlay__SMToK","chartInteractiveLayer":"DriversComparisonChart_chartInteractiveLayer__0aquh","chartInteractiveDimmed":"DriversComparisonChart_chartInteractiveDimmed__us1dv","chartEmptyOverlay":"DriversComparisonChart_chartEmptyOverlay__eXqzk","chartEmptyBlurb":"DriversComparisonChart_chartEmptyBlurb__Tjy9E","seriesEmptyWrap":"DriversComparisonChart_seriesEmptyWrap__RyRs5","seriesSection":"DriversComparisonChart_seriesSection__yrf4I","seriesTableWrapper":"DriversComparisonChart_seriesTableWrapper__oredC","seriesTableContainer":"DriversComparisonChart_seriesTableContainer__dhfXK","seriesScrollbar":"DriversComparisonChart_seriesScrollbar__2jgk6","seriesTable":"DriversComparisonChart_seriesTable__NybPR","seriesColSeries":"DriversComparisonChart_seriesColSeries__--0mj","rowHidden":"DriversComparisonChart_rowHidden__Fwhna","colorSwatch":"DriversComparisonChart_colorSwatch__o3ZVr","seriesLabel":"DriversComparisonChart_seriesLabel__Aidof","chartContainer":"DriversComparisonChart_chartContainer__1eM-O"};
+styleInject(css_248z);
+
+export { S as default };

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

@@ -0,0 +1,159 @@
+import { normalizeToMonthStart, getPreviousMonth, getNextMonth } from '../../../utils/chartConnectionPoint.js';
+
+const DRIVER_FORECAST_ID_BASE = 8_000_000;
+const INITIAL_VISIBLE_SERIES_COUNT = 3;
+/** Months of historical context before the earliest forecast month (inclusive). */
+const DRIVER_COMPARISON_CHART_LEAD_MONTHS = 6;
+/** 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;
+function formatSeriesImportance(value) {
+    if (value === null)
+        return '—';
+    return `${value.toFixed(1)}%`;
+}
+function mergeBacktestsChartData(payload) {
+    if (!payload?.target?.normalized_series)
+        return [];
+    const norm = (d) => normalizeToMonthStart(d);
+    const map = new Map();
+    const targetSeries = payload.target.normalized_series;
+    Object.entries(targetSeries).forEach(([dateStr, val]) => {
+        if (val === null || val === undefined)
+            return;
+        const k = norm(dateStr);
+        const existing = map.get(k) ?? { date: k };
+        existing.historical = val;
+        map.set(k, existing);
+    });
+    if (payload.drivers?.length) {
+        const sorted = [...payload.drivers]
+            .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)));
+        sorted.forEach((driver, idx) => {
+            const fid = DRIVER_FORECAST_ID_BASE + idx;
+            const series = driver.normalized_series;
+            Object.entries(series).forEach(([dateStr, val]) => {
+                if (val === null || val === undefined)
+                    return;
+                const k = norm(dateStr);
+                const existing = map.get(k) ?? { date: k };
+                existing[`forecast_${fid}`] = val;
+                map.set(k, existing);
+            });
+        });
+    }
+    return Array.from(map.values()).sort((a, b) => a.date.localeCompare(b.date));
+}
+/** While drivers comparison is not loaded: dataset historical only. After load: normalized historical from target.normalized_series (see mergeBacktestsChartData) replaces it. */
+function mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical, backtestsMerged) {
+    if (backtestsMerged.length === 0) {
+        if (datasetHistorical.length === 0)
+            return [];
+        return datasetHistorical
+            .map(p => {
+            const k = normalizeToMonthStart(p.date);
+            const histVal = p.historical;
+            return {
+                date: k,
+                ...(typeof histVal === 'number' ? { historical: histVal } : {}),
+            };
+        })
+            .sort((a, b) => a.date.localeCompare(b.date));
+    }
+    return backtestsMerged;
+}
+/** Lower-median of ISO month strings (YYYY-MM-01 sorts lexicographically). */
+function medianSortedIsoMonth(months) {
+    const s = [...months].sort((a, b) => a.localeCompare(b));
+    return s[Math.floor((s.length - 1) / 2)];
+}
+/**
+ * For each driver, first month with materially non-zero value; anchor = median of those months.
+ * (Min is too early with outliers; max matched logs where one driver started 2017-12 while most started 2015-01.)
+ */
+function getZoomAnchorMonthFromDriverMaterialStarts(points, forecastIds) {
+    const perDriverFirstMaterial = [];
+    for (const id of forecastIds) {
+        let minForId = null;
+        for (const p of points) {
+            const v = p[`forecast_${id}`];
+            if (typeof v !== 'number' ||
+                !Number.isFinite(v) ||
+                Math.abs(v) <= DRIVER_FORECAST_NONZERO_EPS) {
+                continue;
+            }
+            const d = normalizeToMonthStart(p.date);
+            if (minForId === null || d.localeCompare(minForId) < 0)
+                minForId = d;
+        }
+        if (minForId === null) {
+            return { anchor: null, perDriverFirstMaterial };
+        }
+        perDriverFirstMaterial.push(minForId);
+    }
+    const anchor = medianSortedIsoMonth(perDriverFirstMaterial);
+    return { anchor, perDriverFirstMaterial };
+}
+function subtractMonthsFromMonthStart(date, count) {
+    let result = date;
+    for (let i = 0; i < count; i++) {
+        result = getPreviousMonth(result);
+    }
+    return result;
+}
+/**
+ * Backtests payload often starts at the same month for target + drivers, so xMin falls
+ * in a range with no rows. Prepend historical-only months from raw dataset series
+ * (scaled to the first normalized point) so the lead-in shows the target line alone.
+ */
+function prependHistoricalLeadFromDataset(points, datasetHistorical, xMin) {
+    if (points.length === 0)
+        return points;
+    const firstMonth = normalizeToMonthStart(points[0].date);
+    if (xMin.localeCompare(firstMonth) >= 0)
+        return points;
+    const rawByMonth = new Map();
+    for (const p of datasetHistorical) {
+        const k = normalizeToMonthStart(p.date);
+        const v = p.historical;
+        if (typeof v === 'number' && Number.isFinite(v))
+            rawByMonth.set(k, v);
+    }
+    const histFirst = points[0].historical;
+    const rawFirst = rawByMonth.get(firstMonth);
+    if (typeof histFirst !== 'number' ||
+        !Number.isFinite(histFirst) ||
+        typeof rawFirst !== 'number' ||
+        !Number.isFinite(rawFirst) ||
+        Math.abs(rawFirst) <= 1e-15) {
+        return points;
+    }
+    const lead = [];
+    let m = xMin;
+    while (m.localeCompare(firstMonth) < 0) {
+        const rawM = rawByMonth.get(m);
+        if (typeof rawM === 'number' && Number.isFinite(rawM)) {
+            lead.push({
+                date: m,
+                historical: histFirst * (rawM / rawFirst),
+            });
+        }
+        m = getNextMonth(m);
+    }
+    return [...lead, ...points];
+}
+function buildDriversComparisonChartData(mergedWithHistorical, datasetHistorical, forecastIds) {
+    if (mergedWithHistorical.length === 0)
+        return mergedWithHistorical;
+    if (forecastIds.length === 0)
+        return mergedWithHistorical;
+    const { anchor: anchorMonth } = getZoomAnchorMonthFromDriverMaterialStarts(mergedWithHistorical, forecastIds);
+    if (anchorMonth === null)
+        return mergedWithHistorical;
+    const xMin = subtractMonthsFromMonthStart(anchorMonth, DRIVER_COMPARISON_CHART_LEAD_MONTHS);
+    const withLead = prependHistoricalLeadFromDataset(mergedWithHistorical, datasetHistorical, xMin);
+    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 };

package/dist/esm/index.js

@@ -104,6 +104,8 @@ export { DriverMap } from './components/widgets/DriverMap/DriverMap.js';
 export { getCategoryIcon } from './components/widgets/DriverMap/driverCategoryIcon.js';
 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 { SybilionAppHeader } from './components/widgets/SybilionAppHeader/SybilionAppHeader.js';
 export { SybilionAuthLayout } from './components/widgets/SybilionAuthLayout/SybilionAuthLayout.js';
 export { SybilionAuthHeadline } from './components/widgets/SybilionAuthLayout/SybilionAuthHeadline.js';

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

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

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

@@ -0,0 +1,26 @@
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+import type { BacktestsComponentPayload } from '@sybilion/platform-sdk';
+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 declare function formatSeriesImportance(value: number | null): string;
+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[];
+/**
+ * For each driver, first month with materially non-zero value; anchor = median of those months.
+ * (Min is too early with outliers; max matched logs where one driver started 2017-12 while most started 2015-01.)
+ */
+export declare function getZoomAnchorMonthFromDriverMaterialStarts(points: ChartDataPoint[], forecastIds: number[]): {
+    anchor: string | null;
+    perDriverFirstMaterial: string[];
+};
+export declare function subtractMonthsFromMonthStart(date: string, count: number): string;
+/**
+ * Backtests payload often starts at the same month for target + drivers, so xMin falls
+ * in a range with no rows. Prepend historical-only months from raw dataset series
+ * (scaled to the first normalized point) so the lead-in shows the target line alone.
+ */
+export declare function prependHistoricalLeadFromDataset(points: ChartDataPoint[], datasetHistorical: ChartDataPoint[], xMin: string): ChartDataPoint[];
+export declare function buildDriversComparisonChartData(mergedWithHistorical: ChartDataPoint[], datasetHistorical: ChartDataPoint[], forecastIds: number[]): ChartDataPoint[];

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

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

package/dist/esm/types/src/docs/pages/DriversComparisonChartPage.d.ts

@@ -0,0 +1 @@
+export default function DriversComparisonChartPage(): import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/src/index.d.ts

@@ -68,6 +68,7 @@ export * from './components/ui/WorkspaceAppSwitcher';
 export * from './components/widgets/SidebarDatasetsItemsGrouped';
 export * from './components/widgets/DriverCard';
 export * from './components/widgets/DriverMap';
+export * from './components/widgets/DriversComparisonChart';
 export * from './components/widgets/SybilionAppHeader';
 export * from './components/widgets/SybilionAuthLayout';
 export * from './components/widgets/SybilionSignInPanel';

package/dist/esm/utils/chartConnectionPoint.js

@@ -101,5 +101,13 @@ function getPreviousMonth(date) {
     d.setMonth(d.getMonth() - 1);
     return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-01`;
 }
+/**
+ * Get the next month date (first day of next month)
+ */
+function getNextMonth(date) {
+    const d = new Date(date);
+    d.setMonth(d.getMonth() + 1);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-01`;
+}
 
-export { ensureChartForecastBridge, findLastValidHistoricalChartPoint, getPreviousMonth, normalizeToMonthStart };
+export { ensureChartForecastBridge, findLastValidHistoricalChartPoint, getNextMonth, getPreviousMonth, normalizeToMonthStart };

package/package.json

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

package/src/components/widgets/DriversComparisonChart/DriversComparisonChart.styl

@@ -0,0 +1,145 @@
+@import '../../../lib/theme.styl';
+
+.root
+  display flex
+  flex-direction column
+  gap var(--p-4)
+  width 100%
+
+.chartShell
+  position relative
+  width 100%
+
+.chartShellLoading
+  .chartSlot
+    opacity 0.3
+    pointer-events none
+
+  :global(.recharts-line-dots)
+    display none
+
+.chartSlot
+  width 100%
+
+.loadingLayer
+  position absolute
+  inset 0
+  z-index 10
+  pointer-events none
+
+.loadingMessage
+  position absolute
+  z-index 1
+  top calc(50% - 4em)
+  left 0
+  width 100%
+  display block
+  text-align center
+  color var(--foreground)
+
+.loadingText
+  font-size 16px
+  font-weight 500
+  color var(--foreground)
+  border-radius var(--p-4)
+  padding 0 var(--p-3)
+  backdrop-filter blur(10px)
+  box-shadow 0 0 0 2px var(--page-color)
+
+.chartWithOverlay
+  position relative
+  width 100%
+
+.chartInteractiveLayer
+  width 100%
+  transition opacity 0.2s ease-out
+
+.chartInteractiveDimmed
+  opacity 0.3
+  pointer-events none
+
+  :global(.recharts-line-dots)
+    display none
+
+.chartEmptyOverlay
+  position absolute
+  inset 0
+  z-index 6
+  display flex
+  align-items center
+  justify-content center
+  padding var(--p-4)
+  pointer-events none
+
+.chartEmptyBlurb
+  max-width 42rem
+  padding 0 var(--p-3)
+
+.seriesEmptyWrap
+  display flex
+  justify-content center
+  padding var(--p-8) var(--p-4)
+
+.seriesSection
+  width 100%
+
+.seriesTableWrapper
+  position relative
+  margin 0 calc(var(--page-x-padding) * -1)
+
+.seriesTableContainer
+  position relative
+  width 100%
+  overflow-x auto
+
+.seriesScrollbar
+  bottom calc(var(--p-7) * -1 + 2px) !important
+
+.seriesTable
+  table-layout auto
+  width 100%
+  max-width 100%
+
+  tr
+    position relative
+    cursor pointer
+
+  td
+  th
+    &:not(:first-child)
+      text-align right
+
+.seriesColSeries
+  text-align left
+  vertical-align middle
+
+.rowHidden
+  opacity .4
+
+.colorSwatch
+  display inline-flex
+  flex-shrink 0
+  width 10px
+  height 10px
+  margin-right var(--p-2)
+  border-radius 2px
+
+.seriesLabel
+  min-width 0
+  max-width 60vw
+  padding var(--p-2) 0
+  line-clamp(3)
+  white-space break-spaces
+
+.chartContainer
+  margin-left calc(-1 * var(--page-x-padding) + 26px)
+  width calc(100% + 60px)
+  max-width @width
+  transition opacity 300ms ease-out
+
+  :global(.recharts-yAxis-tick-labels)
+    display none
+
+  @media (max-width: unit(MOBILE, 'px'))
+    margin-left calc(-1 * var(--page-x-padding) + 10px)
+    width calc(100% + 30px)

package/src/components/widgets/DriversComparisonChart/DriversComparisonChart.styl.d.ts

@@ -0,0 +1,29 @@
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'chartContainer': string;
+  'chartEmptyBlurb': string;
+  'chartEmptyOverlay': string;
+  'chartInteractiveDimmed': string;
+  'chartInteractiveLayer': string;
+  'chartShell': string;
+  'chartShellLoading': string;
+  'chartSlot': string;
+  'chartWithOverlay': string;
+  'colorSwatch': string;
+  'loadingLayer': string;
+  'loadingMessage': string;
+  'loadingText': string;
+  'root': string;
+  'rowHidden': string;
+  'seriesColSeries': string;
+  'seriesEmptyWrap': string;
+  'seriesLabel': string;
+  'seriesScrollbar': string;
+  'seriesSection': string;
+  'seriesTable': string;
+  'seriesTableContainer': string;
+  'seriesTableWrapper': string;
+}
+export const cssExports: CssExports;
+export default cssExports;

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

@@ -0,0 +1,325 @@
+import cn from 'classnames';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { ChartEmptyState } from '#uilib/components/ui/Chart/components/ChartEmptyState/ChartEmptyState';
+import { ChartAreaInteractive } from '#uilib/components/ui/ChartAreaInteractive';
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+import {
+  type ForecastItemData,
+  getForecastColor,
+} from '#uilib/components/ui/ChartAreaInteractive/ChartLines';
+import { PageXScroll } from '#uilib/components/ui/Page';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '#uilib/components/ui/Table';
+import { TextShimmer } from '#uilib/components/ui/TextShimmer/TextShimmer';
+import { TIME_RANGES } from '#uilib/components/ui/TimeRangeControls/TimeRangeControls.constants';
+import type { BacktestsComponentPayload } from '@sybilion/platform-sdk';
+
+import S from './DriversComparisonChart.styl';
+import {
+  DRIVER_FORECAST_ID_BASE,
+  INITIAL_VISIBLE_SERIES_COUNT,
+  buildDriversComparisonChartData,
+  formatSeriesImportance,
+  mergeBacktestsChartData,
+  mergeDatasetHistoricalWithBacktestsChartData,
+} from './driversComparisonChart.helpers';
+
+const ALL_TIME_RANGE = TIME_RANGES[TIME_RANGES.length - 1];
+
+function toForecastDataKey(id: number | string): string {
+  const s = String(id);
+  return s.startsWith('forecast_') ? s : `forecast_${id}`;
+}
+
+export type DriversComparisonChartProps = {
+  payload: BacktestsComponentPayload | null;
+  datasetHistorical?: ChartDataPoint[];
+  loading?: boolean;
+  chartLoading?: boolean;
+  statusHint?: string | null;
+  statusTone?: 'destructive' | 'muted';
+  runAnalysisHint?: boolean;
+  timeRange?: string;
+  onTimeRangeChange?: (range: string) => void;
+  isDarkTheme?: boolean;
+  className?: string;
+  /** Resets visible series when this key changes (e.g. selected analysis id). */
+  seriesInitKey?: string;
+};
+
+export function DriversComparisonChart({
+  payload,
+  datasetHistorical = [],
+  loading = false,
+  chartLoading = false,
+  statusHint = null,
+  statusTone = 'muted',
+  runAnalysisHint = false,
+  timeRange: timeRangeProp,
+  onTimeRangeChange,
+  isDarkTheme = false,
+  className,
+  seriesInitKey,
+}: DriversComparisonChartProps) {
+  const [internalTimeRange, setInternalTimeRange] =
+    useState<string>(ALL_TIME_RANGE);
+  const [hiddenSeries, setHiddenSeries] = useState<Set<string>>(new Set());
+
+  const timeRange = timeRangeProp ?? internalTimeRange;
+  const handleTimeRangeChange = useCallback(
+    (val: string) => {
+      if (!val) return;
+      onTimeRangeChange?.(val);
+      if (timeRangeProp === undefined) {
+        setInternalTimeRange(val);
+      }
+    },
+    [onTimeRangeChange, timeRangeProp],
+  );
+
+  const toggleSeries = useCallback((id: number | string) => {
+    const key = toForecastDataKey(id);
+    setHiddenSeries(prev => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }, []);
+
+  const showSeries = useCallback((id: number | string) => {
+    const key = toForecastDataKey(id);
+    setHiddenSeries(prev => {
+      if (!prev.has(key)) return prev;
+      const next = new Set(prev);
+      next.delete(key);
+      return next;
+    });
+  }, []);
+
+  const sortedDriversWithData = useMemo(() => {
+    const driversList = payload?.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],
+  );
+
+  const mergedWithHistorical = useMemo(
+    () =>
+      mergeDatasetHistoricalWithBacktestsChartData(
+        datasetHistorical,
+        mergedChartData,
+      ),
+    [datasetHistorical, mergedChartData],
+  );
+
+  const chartForecastData = useMemo((): ForecastItemData[] => {
+    if (!payload?.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]);
+
+  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;
+      return {
+        id: DRIVER_FORECAST_ID_BASE + idx,
+        name: driver.name || String(driver.id),
+        color: getForecastColor(idx + 1),
+        importance,
+        lag: driver.lag,
+      };
+    });
+  }, [sortedDriversWithData]);
+
+  const seriesInitKeyResolved =
+    seriesInitKey ?? `${tableSeriesRows.map(r => r.id).join(',') || 'none'}`;
+
+  const backtestsSeriesInitKeyRef = useRef<string>('');
+
+  useEffect(() => {
+    if (tableSeriesRows.length === 0) return;
+    const initKey = seriesInitKeyResolved;
+    if (backtestsSeriesInitKeyRef.current === initKey) return;
+    backtestsSeriesInitKeyRef.current = initKey;
+
+    setHiddenSeries(() => {
+      const next = new Set<string>();
+      tableSeriesRows.forEach((row, idx) => {
+        const key = toForecastDataKey(row.id);
+        if (idx >= INITIAL_VISIBLE_SERIES_COUNT) {
+          next.add(key);
+        }
+      });
+      return next;
+    });
+  }, [seriesInitKeyResolved, tableSeriesRows]);
+
+  const driversComparisonChartData = useMemo(
+    () =>
+      buildDriversComparisonChartData(
+        mergedWithHistorical,
+        datasetHistorical,
+        chartForecastData.map(f => f.id),
+      ),
+    [chartForecastData, datasetHistorical, mergedWithHistorical],
+  );
+
+  const showEmptyOverlay = (runAnalysisHint || Boolean(statusHint)) && !loading;
+
+  return (
+    <div className={cn(S.root, className)}>
+      <div className={cn(S.chartShell, loading && S.chartShellLoading)}>
+        <div className={S.chartSlot}>
+          <div className={S.chartWithOverlay}>
+            <div
+              className={cn(
+                S.chartInteractiveLayer,
+                showEmptyOverlay && S.chartInteractiveDimmed,
+              )}
+            >
+              <ChartAreaInteractive
+                disableHistoricalAnimation
+                disableTimeRangeSelector
+                enableTimeRangeBrush
+                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}
+              />
+            </div>
+            {showEmptyOverlay && (
+              <div
+                className={S.chartEmptyOverlay}
+                role="status"
+                aria-live="polite"
+              >
+                <div className={S.chartEmptyBlurb}>
+                  <ChartEmptyState
+                    variant="inline"
+                    hint={
+                      runAnalysisHint
+                        ? 'Run a completed analysis to load the drivers comparison chart for an analysis.'
+                        : undefined
+                    }
+                    status={statusHint ?? undefined}
+                    statusTone={statusTone}
+                  />
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+        {loading && (
+          <div className={S.loadingLayer} aria-busy="true" aria-live="polite">
+            <div className={S.loadingMessage}>
+              <TextShimmer as="span" className={S.loadingText}>
+                Loading drivers comparison…
+              </TextShimmer>
+            </div>
+          </div>
+        )}
+      </div>
+
+      <div className={S.seriesSection}>
+        {tableSeriesRows.length === 0 ? (
+          <div className={S.seriesEmptyWrap}>
+            <div className={S.chartEmptyBlurb}>
+              <ChartEmptyState
+                variant="inline"
+                align="center"
+                status="No series"
+              />
+            </div>
+          </div>
+        ) : (
+          <div className={S.seriesTableWrapper}>
+            <PageXScroll
+              size="md"
+              fullWidth
+              innerClassName={S.seriesTableContainer}
+              scrollbarClassName={S.seriesScrollbar}
+            >
+              <Table withBackground withPaddings className={S.seriesTable}>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead className={S.seriesColSeries}>
+                      Driver name
+                    </TableHead>
+                    <TableHead>Importance</TableHead>
+                    <TableHead>Lag</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {tableSeriesRows.map(row => {
+                    const dataKey = toForecastDataKey(row.id);
+                    const hidden = hiddenSeries.has(dataKey);
+                    return (
+                      <TableRow
+                        key={row.id}
+                        className={cn(hidden && S.rowHidden)}
+                        onClick={() => toggleSeries(row.id)}
+                      >
+                        <TableCell>
+                          <span className={S.seriesLabel}>
+                            <span
+                              className={S.colorSwatch}
+                              style={{
+                                backgroundColor: row.color,
+                              }}
+                            />
+                            {row.name ?? String(row.id)}
+                          </span>
+                        </TableCell>
+                        <TableCell>
+                          {formatSeriesImportance(row.importance)}
+                        </TableCell>
+                        <TableCell>{row.lag ?? '—'}</TableCell>
+                      </TableRow>
+                    );
+                  })}
+                </TableBody>
+              </Table>
+            </PageXScroll>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,206 @@
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+import {
+  getNextMonth,
+  getPreviousMonth,
+  normalizeToMonthStart,
+} from '#uilib/utils/chartConnectionPoint';
+import type { BacktestsComponentPayload } from '@sybilion/platform-sdk';
+
+export const DRIVER_FORECAST_ID_BASE = 8_000_000;
+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;
+
+/** 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;
+
+export function formatSeriesImportance(value: number | null): string {
+  if (value === null) return '—';
+  return `${value.toFixed(1)}%`;
+}
+
+export function mergeBacktestsChartData(
+  payload: BacktestsComponentPayload | null,
+): ChartDataPoint[] {
+  if (!payload?.target?.normalized_series) return [];
+
+  const norm = (d: string) => normalizeToMonthStart(d);
+  const map = new Map<string, ChartDataPoint>();
+
+  const targetSeries = payload.target.normalized_series;
+  Object.entries(targetSeries).forEach(([dateStr, val]) => {
+    if (val === null || val === undefined) return;
+    const k = norm(dateStr);
+    const existing = map.get(k) ?? { date: k };
+    existing.historical = val;
+    map.set(k, existing);
+  });
+
+  if (payload.drivers?.length) {
+    const sorted = [...payload.drivers]
+      .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)));
+
+    sorted.forEach((driver, idx) => {
+      const fid = DRIVER_FORECAST_ID_BASE + idx;
+      const series = driver.normalized_series!;
+      Object.entries(series).forEach(([dateStr, val]) => {
+        if (val === null || val === undefined) return;
+        const k = norm(dateStr);
+        const existing = map.get(k) ?? { date: k };
+        existing[`forecast_${fid}`] = val;
+        map.set(k, existing);
+      });
+    });
+  }
+
+  return Array.from(map.values()).sort((a, b) => a.date.localeCompare(b.date));
+}
+
+/** While drivers comparison is not loaded: dataset historical only. After load: normalized historical from target.normalized_series (see mergeBacktestsChartData) replaces it. */
+export function mergeDatasetHistoricalWithBacktestsChartData(
+  datasetHistorical: ChartDataPoint[],
+  backtestsMerged: ChartDataPoint[],
+): ChartDataPoint[] {
+  if (backtestsMerged.length === 0) {
+    if (datasetHistorical.length === 0) return [];
+    return datasetHistorical
+      .map(p => {
+        const k = normalizeToMonthStart(p.date);
+        const histVal = p.historical;
+        return {
+          date: k,
+          ...(typeof histVal === 'number' ? { historical: histVal } : {}),
+        };
+      })
+      .sort((a, b) => a.date.localeCompare(b.date));
+  }
+  return backtestsMerged;
+}
+
+/** Lower-median of ISO month strings (YYYY-MM-01 sorts lexicographically). */
+function medianSortedIsoMonth(months: string[]): string {
+  const s = [...months].sort((a, b) => a.localeCompare(b));
+  return s[Math.floor((s.length - 1) / 2)];
+}
+
+/**
+ * For each driver, first month with materially non-zero value; anchor = median of those months.
+ * (Min is too early with outliers; max matched logs where one driver started 2017-12 while most started 2015-01.)
+ */
+export function getZoomAnchorMonthFromDriverMaterialStarts(
+  points: ChartDataPoint[],
+  forecastIds: number[],
+): { anchor: string | null; perDriverFirstMaterial: string[] } {
+  const perDriverFirstMaterial: string[] = [];
+  for (const id of forecastIds) {
+    let minForId: string | null = null;
+    for (const p of points) {
+      const v = p[`forecast_${id}`];
+      if (
+        typeof v !== 'number' ||
+        !Number.isFinite(v) ||
+        Math.abs(v) <= DRIVER_FORECAST_NONZERO_EPS
+      ) {
+        continue;
+      }
+      const d = normalizeToMonthStart(p.date);
+      if (minForId === null || d.localeCompare(minForId) < 0) minForId = d;
+    }
+    if (minForId === null) {
+      return { anchor: null, perDriverFirstMaterial };
+    }
+    perDriverFirstMaterial.push(minForId);
+  }
+  const anchor = medianSortedIsoMonth(perDriverFirstMaterial);
+  return { anchor, perDriverFirstMaterial };
+}
+
+export function subtractMonthsFromMonthStart(
+  date: string,
+  count: number,
+): string {
+  let result = date;
+  for (let i = 0; i < count; i++) {
+    result = getPreviousMonth(result);
+  }
+  return result;
+}
+
+/**
+ * Backtests payload often starts at the same month for target + drivers, so xMin falls
+ * in a range with no rows. Prepend historical-only months from raw dataset series
+ * (scaled to the first normalized point) so the lead-in shows the target line alone.
+ */
+export function prependHistoricalLeadFromDataset(
+  points: ChartDataPoint[],
+  datasetHistorical: ChartDataPoint[],
+  xMin: string,
+): ChartDataPoint[] {
+  if (points.length === 0) return points;
+  const firstMonth = normalizeToMonthStart(points[0].date);
+  if (xMin.localeCompare(firstMonth) >= 0) return points;
+
+  const rawByMonth = new Map<string, number>();
+  for (const p of datasetHistorical) {
+    const k = normalizeToMonthStart(p.date);
+    const v = p.historical;
+    if (typeof v === 'number' && Number.isFinite(v)) rawByMonth.set(k, v);
+  }
+
+  const histFirst = points[0].historical;
+  const rawFirst = rawByMonth.get(firstMonth);
+  if (
+    typeof histFirst !== 'number' ||
+    !Number.isFinite(histFirst) ||
+    typeof rawFirst !== 'number' ||
+    !Number.isFinite(rawFirst) ||
+    Math.abs(rawFirst) <= 1e-15
+  ) {
+    return points;
+  }
+
+  const lead: ChartDataPoint[] = [];
+  let m = xMin;
+  while (m.localeCompare(firstMonth) < 0) {
+    const rawM = rawByMonth.get(m);
+    if (typeof rawM === 'number' && Number.isFinite(rawM)) {
+      lead.push({
+        date: m,
+        historical: histFirst * (rawM / rawFirst),
+      });
+    }
+    m = getNextMonth(m);
+  }
+  return [...lead, ...points];
+}
+
+export function buildDriversComparisonChartData(
+  mergedWithHistorical: ChartDataPoint[],
+  datasetHistorical: ChartDataPoint[],
+  forecastIds: number[],
+): ChartDataPoint[] {
+  if (mergedWithHistorical.length === 0) return mergedWithHistorical;
+  if (forecastIds.length === 0) return mergedWithHistorical;
+  const { anchor: anchorMonth } = getZoomAnchorMonthFromDriverMaterialStarts(
+    mergedWithHistorical,
+    forecastIds,
+  );
+  if (anchorMonth === null) return mergedWithHistorical;
+  const xMin = subtractMonthsFromMonthStart(
+    anchorMonth,
+    DRIVER_COMPARISON_CHART_LEAD_MONTHS,
+  );
+  const withLead = prependHistoricalLeadFromDataset(
+    mergedWithHistorical,
+    datasetHistorical,
+    xMin,
+  );
+  return withLead.filter(p => normalizeToMonthStart(p.date) >= xMin);
+}

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

@@ -0,0 +1,13 @@
+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';

package/src/docs/pages/DriversComparisonChartPage.tsx

@@ -0,0 +1,174 @@
+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 { TIME_RANGES } from '#uilib/components/ui/TimeRangeControls/TimeRangeControls.constants';
+import { DriversComparisonChart } from '#uilib/components/widgets/DriversComparisonChart';
+import { useTheme } from '#uilib/contexts/theme-context';
+import type { BacktestsComponentPayload } from '@sybilion/platform-sdk';
+
+import { AppPageHeader } from '../components/AppPageHeader/AppPageHeader';
+import { DocsHeaderActions } from '../docsHeaderActions';
+
+const ALL_TIME_RANGE = TIME_RANGES[TIME_RANGES.length - 1];
+
+function monthKey(year: number, month: number): string {
+  return `${year}-${String(month).padStart(2, '0')}-01`;
+}
+
+function buildMonthlySeries(
+  startYear: number,
+  startMonth: number,
+  count: number,
+  base: number,
+  drift = 0.08,
+  phase = 0,
+): Record<string, number> {
+  const out: Record<string, number> = {};
+  let y = startYear;
+  let m = startMonth;
+  for (let i = 0; i < count; i++) {
+    out[monthKey(y, m)] = base + Math.sin(i * 0.4 + phase) * 0.35 + i * drift;
+    m += 1;
+    if (m > 12) {
+      m = 1;
+      y += 1;
+    }
+  }
+  return out;
+}
+
+function buildTargetSeries(): Record<string, number> {
+  return buildMonthlySeries(2018, 1, 48, 1.0, 0.012, 0.2);
+}
+
+const MOCK_PAYLOAD: BacktestsComponentPayload = {
+  target: {
+    id: 'target',
+    name: 'Normalized target',
+    normalized_series: buildTargetSeries(),
+  },
+  drivers: [
+    {
+      id: 'driver-us-pmi',
+      name: 'U.S. manufacturing PMI composite',
+      importance: 84.2,
+      lag: '1 quarter(s)',
+      normalized_series: buildMonthlySeries(2019, 4, 42, 0.45, 0.015, 0),
+    },
+    {
+      id: 'driver-eu-orders',
+      name: 'German industrial orders (domestic + foreign)',
+      importance: 81.6,
+      lag: '2 month(s)',
+      normalized_series: buildMonthlySeries(2019, 1, 42, 0.52, -0.006, 1.1),
+    },
+    {
+      id: 'driver-jp-machinery',
+      name: 'Japan machinery orders (core private-sector)',
+      importance: 77,
+      lag: '~1 month(s)',
+      normalized_series: buildMonthlySeries(2019, 7, 42, 0.38, 0.01, 2.4),
+    },
+    {
+      id: 'driver-global-risk',
+      name: 'Global equity risk appetite composite',
+      importance: 66.5,
+      lag: 'Unknown',
+      normalized_series: buildMonthlySeries(2018, 10, 42, 0.41, 0.004, 3.8),
+    },
+    {
+      id: 'driver-china-credit',
+      name: 'China aggregate financing impulse',
+      importance: 58.3,
+      lag: '3 month(s)',
+      normalized_series: buildMonthlySeries(2020, 1, 36, 0.29, 0.018, 4.2),
+    },
+  ],
+};
+
+function buildDatasetHistorical(): ChartDataPoint[] {
+  const raw = buildMonthlySeries(2017, 7, 54, 112, 0.9, 0.5);
+  return Object.entries(raw).map(([date, historical]) => ({
+    date,
+    historical,
+  }));
+}
+
+export default function DriversComparisonChartPage() {
+  const { isDarkMode } = useTheme();
+  const [loading, setLoading] = useState(false);
+  const [runAnalysisHint, setRunAnalysisHint] = useState(false);
+  const [emptyPayload, setEmptyPayload] = useState(false);
+  const [timeRange, setTimeRange] = useState<string>(ALL_TIME_RANGE);
+
+  const payload = useMemo(
+    () => (emptyPayload ? null : MOCK_PAYLOAD),
+    [emptyPayload],
+  );
+  const datasetHistorical = useMemo(() => buildDatasetHistorical(), []);
+
+  return (
+    <>
+      <AppPageHeader
+        breadcrumbs={[{ label: 'Drivers comparison chart' }]}
+        title="DriversComparisonChart"
+        subheader="Normalized target line with driver series; table rows toggle chart visibility."
+        actions={<DocsHeaderActions />}
+      />
+      <PageContentSection>
+        <div
+          style={{
+            display: 'flex',
+            flexWrap: 'wrap',
+            alignItems: 'center',
+            gap: 16,
+            marginBottom: 16,
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+            <Switch
+              id="loading-overlay"
+              checked={loading}
+              onCheckedChange={setLoading}
+            />
+            <label htmlFor="loading-overlay">Loading overlay</label>
+          </div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+            <Switch
+              id="run-analysis-hint"
+              checked={runAnalysisHint}
+              onCheckedChange={setRunAnalysisHint}
+            />
+            <label htmlFor="run-analysis-hint">Run analysis hint</label>
+          </div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+            <Switch
+              id="empty-payload"
+              checked={emptyPayload}
+              onCheckedChange={setEmptyPayload}
+            />
+            <label htmlFor="empty-payload">Empty payload</label>
+          </div>
+        </div>
+        <DriversComparisonChart
+          payload={payload}
+          datasetHistorical={datasetHistorical}
+          loading={loading}
+          chartLoading={false}
+          runAnalysisHint={runAnalysisHint}
+          statusHint={
+            emptyPayload
+              ? 'No normalized driver series in the response yet.'
+              : null
+          }
+          timeRange={timeRange}
+          onTimeRangeChange={setTimeRange}
+          isDarkTheme={isDarkMode}
+          seriesInitKey={emptyPayload ? 'empty' : 'mock'}
+        />
+      </PageContentSection>
+    </>
+  );
+}

package/src/docs/registry.ts

@@ -145,6 +145,12 @@ export const DOC_REGISTRY: DocEntry[] = [
     section: 'Widgets',
     load: () => import('./pages/DriverMapPage'),
   },
+  {
+    slug: 'drivers-comparison-chart',
+    title: 'DriversComparisonChart',
+    section: 'Widgets',
+    load: () => import('./pages/DriversComparisonChartPage'),
+  },
   {
     slug: 'dropdown-menu',
     title: 'DropdownMenu',

package/src/index.ts

@@ -73,6 +73,7 @@ export * from './components/ui/WorkspaceAppSwitcher';
 export * from './components/widgets/SidebarDatasetsItemsGrouped';
 export * from './components/widgets/DriverCard';
 export * from './components/widgets/DriverMap';
+export * from './components/widgets/DriversComparisonChart';
 export * from './components/widgets/SybilionAppHeader';
 export * from './components/widgets/SybilionAuthLayout';
 export * from './components/widgets/SybilionSignInPanel';