@sybilion/uilib 1.3.62 → 1.3.64

package/dist/esm/components/ui/Chart/components/BaseChartWrapper.js

@@ -48,7 +48,7 @@ BaseChartWrapperLoading.displayName = 'BaseChartWrapperLoading';
  * Separated to maintain hook order consistency
  */
 const BaseChartWrapperContent = forwardRef((props, ref) => {
-    const { chartConfig = {}, chartData, historicalLineColor, forecastData = [], loading, hasCombinedData, renderId, isDarkTheme, height, className, loadingComponentClassName, footerClassName, chartClassName, xAxisClassName, yAxisClassName, legendClassName, footerActions, quantileBands, quantileBandKey, xMin, xMax, yMin, yMax, autoScaleYAxis = true, formatNumber, formatDate: formatDateFn = formatDate, labelFormatter, onLegendClick, margin, chartType = 'composed', disableAnimation = false, disableLineDrawAnimation = false, showGrid = true, showAxes = true, showTooltip = true, showLegend = true, showChartAxesLegend = true, xAxisLabel, yAxisLabel, showActiveDots = true, overlayElements, hiddenSeries, excludeLegendIds, onAnalysisSelect, onFailedAnalysisClick, containerProps, error, loadingMessage, noDataMessage = 'No data available', onGridHeightChange, forecastLineStyle = 'dashed', disableHistoricalAnimation = false, onShowAll: _onShowAll, onShowOnly: _onShowOnly, maxVisibleItems, preventDeselection, legendVariant = 'default', legendWidth = 1000, legendMarginLeft = 0, } = props;
+    const { chartConfig = {}, chartData, historicalLineColor, forecastData = [], loading, hasCombinedData, renderId, isDarkTheme, height, className, loadingComponentClassName, footerClassName, chartClassName, xAxisClassName, yAxisClassName, legendClassName, footerActions, quantileBands, quantileBandKey, xMin, xMax, yMin, yMax, autoScaleYAxis = true, formatNumber, formatDate: formatDateFn = formatDate, labelFormatter, onLegendClick, margin, chartType = 'composed', disableAnimation = false, disableLineDrawAnimation = false, showGrid = true, showAxes = true, showTooltip = true, showLegend = true, showChartAxesLegend = true, xAxisLabel, yAxisLabel, showActiveDots = true, overlayElements, hiddenSeries, includeHiddenInYScale = false, excludeLegendIds, onAnalysisSelect, onFailedAnalysisClick, containerProps, error, loadingMessage, noDataMessage = 'No data available', onGridHeightChange, forecastLineStyle = 'dashed', disableHistoricalAnimation = false, onShowAll: _onShowAll, onShowOnly: _onShowOnly, maxVisibleItems, preventDeselection, legendVariant = 'default', legendWidth = 1000, legendMarginLeft = 0, } = props;
     const [shouldAnimate, setShouldAnimate] = useState(false);
     const lineDataInitializedRef = useRef(false);
     const rootRef = useRef(null);
@@ -291,12 +291,17 @@ const BaseChartWrapperContent = forwardRef((props, ref) => {
     let effectiveAutoScale = autoScaleYAxis;
     if (autoScaleYAxis !== false && yMin !== undefined && yMax !== undefined) {
         const dataKeys = chartData.length > 0 ? Object.keys(chartData[0]) : [];
-        const historicalValues = chartData
-            .map(p => p.historical)
-            .filter(v => v !== null && v !== undefined);
+        const historicalValues = !includeHiddenInYScale && hiddenSeries?.has('historical')
+            ? []
+            : chartData
+                .map(p => p.historical)
+                .filter(v => v !== null && v !== undefined);
         const forecastKeys = dataKeys.filter(k => k.startsWith('forecast_'));
+        const visibleForecastKeys = !includeHiddenInYScale && hiddenSeries
+            ? forecastKeys.filter(k => !hiddenSeries.has(k))
+            : forecastKeys;
         const forecastValues = chartData
-            .flatMap(p => forecastKeys.map(k => p[k]))
+            .flatMap(p => visibleForecastKeys.map(k => p[k]))
             .filter(v => v !== null && v !== undefined);
         const allLineValues = [...historicalValues, ...forecastValues];
         if (allLineValues.length > 0) {

package/dist/esm/components/ui/ChartAreaInteractive/overlays/useChartYRange.js

@@ -1,75 +1,116 @@
 import { useRef, useMemo } from 'react';
 
+/** Serialize hidden series keys for stable cache comparison. */
+function serializeHiddenSeries(hiddenSeries) {
+    if (!hiddenSeries || hiddenSeries.size === 0)
+        return '';
+    return [...hiddenSeries].sort().join(',');
+}
 /**
- * Hook to calculate yMin and yMax from chart data
- * Optionally includes quantile values from forecast data
+ * Returns true when a chart data key should be skipped for Y-scale (series hidden).
  */
-function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileChanges, excludeQuantileBands = false, selectedForecastId, }) {
-    // Store initial Y-range when disableRescaleWhenQuantileChanges is true
-    const stableYRangeRef = useRef(null);
-    const prevBaseChartDataRef = useRef(baseChartProps.chartData);
-    // Helper function to calculate Y-range from data
-    const calculateYRange = (dataToUse, excludeQuantileBands, forecastId) => {
-        const allValues = [];
-        dataToUse.forEach(point => {
-            Object.entries(point).forEach(([key, value]) => {
-                if (key === 'date')
+function isKeyExcludedFromYScale(key, hiddenSeries) {
+    if (!hiddenSeries || hiddenSeries.size === 0)
+        return false;
+    if (key === 'historical') {
+        return hiddenSeries.has('historical');
+    }
+    if (key.startsWith('forecast_')) {
+        return hiddenSeries.has(key);
+    }
+    if (key.startsWith('q') && key.includes('_')) {
+        const forecastId = key.slice(key.lastIndexOf('_') + 1);
+        return hiddenSeries.has(`forecast_${forecastId}`);
+    }
+    if (key.startsWith('band_')) {
+        const forecastId = key.slice(key.lastIndexOf('_') + 1);
+        return hiddenSeries.has(`forecast_${forecastId}`);
+    }
+    return false;
+}
+/** Pure Y-range calculation from chart data points. */
+function calculateChartYRange(dataToUse, { excludeQuantileBands, forecastId, hiddenSeries, includeHiddenInYScale = false, }) {
+    const allValues = [];
+    dataToUse.forEach(point => {
+        Object.entries(point).forEach(([key, value]) => {
+            if (key === 'date')
+                return;
+            if (!includeHiddenInYScale &&
+                isKeyExcludedFromYScale(key, hiddenSeries)) {
+                return;
+            }
+            // When selectedForecastId is provided, scale from historical + selected forecast + its
+            // quantile band (exclude other forecasts and their quantile values only).
+            if (forecastId !== undefined) {
+                if (key.startsWith('forecast_') && key !== `forecast_${forecastId}`)
+                    return;
+                // Exclude q{quantile}_{otherAnalysisId} - only include selected forecast's quantiles
+                if (key.startsWith('q') && !key.endsWith(`_${forecastId}`))
+                    return;
+            }
+            // When excludeQuantileBands is true, exclude:
+            // 1. Quantile band arrays ([number, number])
+            // 2. Individual quantile values (q{quantile}_{analysisId} properties)
+            // Only include historical and forecast line values
+            if (excludeQuantileBands) {
+                // Skip quantile band arrays
+                if (Array.isArray(value) &&
+                    value.length === 2 &&
+                    typeof value[0] === 'number' &&
+                    typeof value[1] === 'number') {
                     return;
-                // When selectedForecastId is provided, scale from historical + selected forecast + its
-                // quantile band (exclude other forecasts and their quantile values only).
-                if (forecastId !== undefined) {
-                    if (key.startsWith('forecast_') && key !== `forecast_${forecastId}`)
-                        return;
-                    // Exclude q{quantile}_{otherAnalysisId} - only include selected forecast's quantiles
-                    if (key.startsWith('q') && !key.endsWith(`_${forecastId}`))
-                        return;
                 }
-                // When excludeQuantileBands is true, exclude:
-                // 1. Quantile band arrays ([number, number])
-                // 2. Individual quantile values (q{quantile}_{analysisId} properties)
-                // Only include historical and forecast line values
-                if (excludeQuantileBands) {
-                    // Skip quantile band arrays
-                    if (Array.isArray(value) &&
-                        value.length === 2 &&
-                        typeof value[0] === 'number' &&
-                        typeof value[1] === 'number') {
-                        return;
-                    }
-                    // Skip individual quantile values (properties starting with 'q' followed by number/underscore)
-                    // Format: q{quantile}_{analysisId} (e.g., q0.05_123, q0.95_123)
-                    if (key.startsWith('q') && typeof value === 'number') {
-                        return;
-                    }
-                    // Include only historical and forecast line values
-                    if (typeof value === 'number') {
-                        allValues.push(value);
-                    }
+                // Skip individual quantile values (properties starting with 'q' followed by number/underscore)
+                // Format: q{quantile}_{analysisId} (e.g., q0.05_123, q0.95_123)
+                if (key.startsWith('q') && typeof value === 'number') {
                     return;
                 }
-                // When not excluding, include both numbers and quantile band arrays
+                // Include only historical and forecast line values
                 if (typeof value === 'number') {
                     allValues.push(value);
                 }
-                else if (Array.isArray(value) &&
-                    value.length === 2 &&
-                    typeof value[0] === 'number' &&
-                    typeof value[1] === 'number') {
-                    allValues.push(value[0], value[1]);
-                }
-            });
+                return;
+            }
+            // When not excluding, include both numbers and quantile band arrays
+            if (typeof value === 'number') {
+                allValues.push(value);
+            }
+            else if (Array.isArray(value) &&
+                value.length === 2 &&
+                typeof value[0] === 'number' &&
+                typeof value[1] === 'number') {
+                allValues.push(value[0], value[1]);
+            }
         });
-        if (allValues.length === 0) {
-            return { yMin: 0, yMax: 100 };
-        }
-        const min = Math.min(...allValues);
-        const max = Math.max(...allValues);
-        const diff = max - min;
-        return {
-            yMin: min - diff * 0.1,
-            yMax: max + diff * 0.1,
-        };
+    });
+    if (allValues.length === 0) {
+        return { yMin: 0, yMax: 100 };
+    }
+    const min = Math.min(...allValues);
+    const max = Math.max(...allValues);
+    const diff = max - min;
+    return {
+        yMin: min - diff * 0.1,
+        yMax: max + diff * 0.1,
     };
+}
+/**
+ * Hook to calculate yMin and yMax from chart data
+ * Optionally includes quantile values from forecast data
+ */
+function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileChanges, excludeQuantileBands = false, selectedForecastId, }) {
+    const includeHiddenInYScale = baseChartProps.includeHiddenInYScale ?? false;
+    const hiddenSeries = baseChartProps.hiddenSeries;
+    // Store initial Y-range when disableRescaleWhenQuantileChanges is true
+    const stableYRangeRef = useRef(null);
+    const prevBaseChartDataRef = useRef(baseChartProps.chartData);
+    const prevHiddenSeriesKeyRef = useRef(serializeHiddenSeries(hiddenSeries));
+    const calculateYRange = (dataToUse, excludeBands, forecastId) => calculateChartYRange(dataToUse, {
+        excludeQuantileBands: excludeBands,
+        forecastId,
+        hiddenSeries,
+        includeHiddenInYScale,
+    });
     // When disableRescaleWhenQuantileChanges is true, calculate initial stable range
     // If chartData (transformedChartData) is provided, use it WITH quantile bands for initial calculation
     // Then keep it stable when dragging quantiles
@@ -84,7 +125,7 @@ function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileC
         if (!disableRescaleWhenQuantileChanges) {
             return null;
         }
-        // Reset stable range when dataset or selected forecast changes
+        // Reset stable range when dataset, selected forecast, or hidden series changes
         if (prevBaseChartDataRef.current !== baseChartProps.chartData) {
             prevBaseChartDataRef.current = baseChartProps.chartData;
             stableYRangeRef.current = null;
@@ -92,6 +133,11 @@ function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileC
         if (stableYRangeRef.current?.forecastId !== selectedForecastId) {
             stableYRangeRef.current = null;
         }
+        const hiddenSeriesKey = serializeHiddenSeries(hiddenSeries);
+        if (prevHiddenSeriesKeyRef.current !== hiddenSeriesKey) {
+            prevHiddenSeriesKeyRef.current = hiddenSeriesKey;
+            stableYRangeRef.current = null;
+        }
         // If chartData (transformedChartData) is provided, use it WITH quantile bands for initial calculation
         // This ensures IntervalsOverlay includes quantile bands in Y-scale
         const dataToUse = chartData ?? baseChartProps.chartData;
@@ -115,6 +161,8 @@ function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileC
         disableRescaleWhenQuantileChanges,
         excludeQuantileBands,
         selectedForecastId,
+        hiddenSeries,
+        includeHiddenInYScale,
     ]);
     // When disableRescaleWhenQuantileChanges is false, calculate from transformed data
     const dynamicRange = useMemo(() => {
@@ -138,6 +186,8 @@ function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileC
         disableRescaleWhenQuantileChanges,
         excludeQuantileBands,
         selectedForecastId,
+        hiddenSeries,
+        includeHiddenInYScale,
     ]);
     // Return appropriate range
     if (disableRescaleWhenQuantileChanges) {
@@ -150,4 +200,4 @@ function useChartYRange({ baseChartProps, chartData, disableRescaleWhenQuantileC
     return dynamicRange;
 }
 
-export { useChartYRange };
+export { calculateChartYRange, isKeyExcludedFromYScale, useChartYRange };

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

@@ -83,8 +83,8 @@ function DriversComparisonChart({ payload, datasetHistorical = [], loading = fal
     const mergedChartData = useMemo(() => mergeBacktestsChartData(payloadForView), [payloadForView]);
     const mergedWithHistorical = useMemo(() => mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical, mergedChartData), [datasetHistorical, mergedChartData]);
     const historicalWindowFloor = useMemo(() => {
-        const overlappedMerged = mergeBacktestsChartData(payload);
-        const merged = mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical, overlappedMerged);
+        const laggedMerged = mergeBacktestsChartData(payload);
+        const merged = mergeDatasetHistoricalWithBacktestsChartData(datasetHistorical, laggedMerged);
         const sortedDrivers = [...(payload?.drivers ?? [])]
             .filter(d => d.normalized_series &&
             Object.keys(d.normalized_series).some(key => d.normalized_series[key] != null))

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

@@ -57,7 +57,7 @@ function formatLagMonthsLabel(months) {
     return `${months} month(s)`;
 }
 function getLagDisplayForView(lag, tab) {
-    if (tab === 'overlapped') {
+    if (tab === 'lagged') {
         return lag?.trim() ? lag : '—';
     }
     const months = parseLagMonthsFromLabel(lag);
@@ -78,8 +78,24 @@ function shiftNormalizedSeriesForward(series, lagMonths) {
     }
     return out;
 }
+/** Shift driver points left (earlier months) by lag — overlapped alignment vs target. */
+function shiftNormalizedSeriesBackward(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 = getPreviousMonth(shifted);
+        }
+        out[shifted] = val;
+    }
+    return out;
+}
 function applyDriversComparisonViewToPayload(payload, tab) {
-    if (!payload || tab === 'overlapped')
+    if (!payload || tab === 'lagged')
         return payload;
     return {
         target: {
@@ -90,7 +106,7 @@ function applyDriversComparisonViewToPayload(payload, tab) {
             const lagMonths = parseLagMonthsFromLabel(resolveDriverLagLabel(driver));
             const series = driver.normalized_series ?? {};
             const normalized_series = lagMonths != null && lagMonths > 0
-                ? shiftNormalizedSeriesForward(series, lagMonths)
+                ? shiftNormalizedSeriesBackward(series, lagMonths)
                 : { ...series };
             return {
                 ...driver,
@@ -231,7 +247,7 @@ function prependHistoricalLeadFromDataset(points, datasetHistorical, xMin) {
     }
     return [...lead, ...points];
 }
-/** Overlapped (unshifted) anchor minus lead months — stable xMin across lagged/overlapped tabs. */
+/** Lagged (unshifted) anchor minus lead months — stable xMin across lagged/overlapped tabs. */
 function computeDriversComparisonHistoricalWindowFloor(mergedWithHistorical, forecastIds) {
     if (mergedWithHistorical.length === 0 || forecastIds.length === 0)
         return null;
@@ -253,4 +269,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, applyDriversComparisonViewToPayload, buildDriversComparisonChartData, computeDriversComparisonHistoricalWindowFloor, formatLagMonthsLabel, formatSeriesImportance, getLagDisplayForView, getZoomAnchorMonthFromDriverMaterialStarts, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, parseLagMonthsFromLabel, prependHistoricalLeadFromDataset, resolveDriverLagLabel, shiftNormalizedSeriesForward, subtractMonthsFromMonthStart };
+export { DRIVER_COMPARISON_CHART_LEAD_MONTHS, DRIVER_FORECAST_ID_BASE, INITIAL_VISIBLE_SERIES_COUNT, applyDriversComparisonViewToPayload, buildDriversComparisonChartData, computeDriversComparisonHistoricalWindowFloor, formatLagMonthsLabel, formatSeriesImportance, getLagDisplayForView, getZoomAnchorMonthFromDriverMaterialStarts, mergeBacktestsChartData, mergeDatasetHistoricalWithBacktestsChartData, parseLagMonthsFromLabel, prependHistoricalLeadFromDataset, resolveDriverLagLabel, shiftNormalizedSeriesBackward, shiftNormalizedSeriesForward, subtractMonthsFromMonthStart };

package/dist/esm/types/src/components/ui/Chart/components/BaseChartWrapper.d.ts

@@ -58,6 +58,8 @@ export interface BaseChartWrapperProps {
     showActiveDots?: boolean;
     overlayElements?: ReactNode;
     hiddenSeries?: Set<string>;
+    /** When false (default), hidden series values are excluded from Y-axis domain calculation. */
+    includeHiddenInYScale?: boolean;
     excludeLegendIds?: number[];
     onAnalysisSelect?: (analysisId: number | string) => void;
     onFailedAnalysisClick?: (analysisId?: number | string) => void;

package/dist/esm/types/src/components/ui/ChartAreaInteractive/overlays/useChartYRange.d.ts

@@ -7,6 +7,21 @@ interface UseChartYRangeOptions {
     excludeQuantileBands?: boolean;
     selectedForecastId?: number;
 }
+export interface CalculateChartYRangeOptions {
+    excludeQuantileBands: boolean;
+    forecastId?: number;
+    hiddenSeries?: Set<string>;
+    includeHiddenInYScale?: boolean;
+}
+/**
+ * Returns true when a chart data key should be skipped for Y-scale (series hidden).
+ */
+export declare function isKeyExcludedFromYScale(key: string, hiddenSeries?: Set<string>): boolean;
+/** Pure Y-range calculation from chart data points. */
+export declare function calculateChartYRange(dataToUse: ChartDataPoint[], { excludeQuantileBands, forecastId, hiddenSeries, includeHiddenInYScale, }: CalculateChartYRangeOptions): {
+    yMin: number;
+    yMax: number;
+};
 /**
  * Hook to calculate yMin and yMax from chart data
  * Optionally includes quantile values from forecast data

package/dist/esm/types/src/components/ui/ChartAreaInteractive/overlays/useChartYRange.test.d.ts

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

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

@@ -16,6 +16,8 @@ export declare function parseLagMonthsFromLabel(lag: string | null | undefined):
 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>;
+/** Shift driver points left (earlier months) by lag — overlapped alignment vs target. */
+export declare function shiftNormalizedSeriesBackward(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. */
@@ -35,6 +37,6 @@ export declare function subtractMonthsFromMonthStart(date: string, count: number
  * (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[];
-/** Overlapped (unshifted) anchor minus lead months — stable xMin across lagged/overlapped tabs. */
+/** Lagged (unshifted) anchor minus lead months — stable xMin across lagged/overlapped tabs. */
 export declare function computeDriversComparisonHistoricalWindowFloor(mergedWithHistorical: ChartDataPoint[], forecastIds: number[]): string | null;
 export declare function buildDriversComparisonChartData(mergedWithHistorical: ChartDataPoint[], datasetHistorical: ChartDataPoint[], forecastIds: number[], historicalWindowFloor?: string | null): ChartDataPoint[];

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

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

package/package.json

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

package/src/components/ui/Chart/components/BaseChartWrapper.tsx

@@ -121,6 +121,8 @@ export interface BaseChartWrapperProps {
   showActiveDots?: boolean;
   overlayElements?: ReactNode;
   hiddenSeries?: Set<string>;
+  /** When false (default), hidden series values are excluded from Y-axis domain calculation. */
+  includeHiddenInYScale?: boolean;
   excludeLegendIds?: number[];
   onAnalysisSelect?: (analysisId: number | string) => void;
   onFailedAnalysisClick?: (analysisId?: number | string) => void;
@@ -225,6 +227,7 @@ const BaseChartWrapperContent = forwardRef<
     showActiveDots = true,
     overlayElements,
     hiddenSeries,
+    includeHiddenInYScale = false,
     excludeLegendIds,
     onAnalysisSelect,
     onFailedAnalysisClick,
@@ -567,12 +570,19 @@ const BaseChartWrapperContent = forwardRef<
   let effectiveAutoScale = autoScaleYAxis;
   if (autoScaleYAxis !== false && yMin !== undefined && yMax !== undefined) {
     const dataKeys = chartData.length > 0 ? Object.keys(chartData[0]) : [];
-    const historicalValues = chartData
-      .map(p => p.historical)
-      .filter(v => v !== null && v !== undefined);
+    const historicalValues =
+      !includeHiddenInYScale && hiddenSeries?.has('historical')
+        ? []
+        : chartData
+            .map(p => p.historical)
+            .filter(v => v !== null && v !== undefined);
     const forecastKeys = dataKeys.filter(k => k.startsWith('forecast_'));
+    const visibleForecastKeys =
+      !includeHiddenInYScale && hiddenSeries
+        ? forecastKeys.filter(k => !hiddenSeries.has(k))
+        : forecastKeys;
     const forecastValues = chartData
-      .flatMap(p => forecastKeys.map(k => p[k]))
+      .flatMap(p => visibleForecastKeys.map(k => p[k]))
       .filter(v => v !== null && v !== undefined);
     const allLineValues = [...historicalValues, ...forecastValues];
 

package/src/components/ui/ChartAreaInteractive/overlays/useChartYRange.test.ts

@@ -0,0 +1,87 @@
+import { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+
+import {
+  calculateChartYRange,
+  isKeyExcludedFromYScale,
+} from './useChartYRange';
+
+const makePoint = (values: Record<string, number>): ChartDataPoint => ({
+  date: '2024-01-01',
+  ...values,
+});
+
+describe('isKeyExcludedFromYScale', () => {
+  it('excludes historical when hidden', () => {
+    expect(isKeyExcludedFromYScale('historical', new Set(['historical']))).toBe(
+      true,
+    );
+  });
+
+  it('excludes quantile keys when parent forecast is hidden', () => {
+    expect(
+      isKeyExcludedFromYScale('q0.05_123', new Set(['forecast_123'])),
+    ).toBe(true);
+  });
+
+  it('excludes band keys when parent forecast is hidden', () => {
+    expect(
+      isKeyExcludedFromYScale('band_10_90_123', new Set(['forecast_123'])),
+    ).toBe(true);
+  });
+});
+
+describe('calculateChartYRange hidden series exclusion', () => {
+  const chartData: ChartDataPoint[] = [
+    makePoint({ historical: 10, forecast_1: 100, forecast_2: 50 }),
+  ];
+
+  it('pin mode: two forecasts, one hidden - Y range from visible only', () => {
+    const hiddenSeries = new Set(['forecast_1']);
+    const range = calculateChartYRange(chartData, {
+      excludeQuantileBands: true,
+      hiddenSeries,
+      includeHiddenInYScale: false,
+    });
+
+    expect(range).toEqual({ yMin: 6, yMax: 54 });
+  });
+
+  it('hidden historical excluded from Y range', () => {
+    const dataWithOutlierHistorical: ChartDataPoint[] = [
+      makePoint({ historical: 1000, forecast_1: 50, forecast_2: 60 }),
+    ];
+    const hiddenSeries = new Set(['historical']);
+    const range = calculateChartYRange(dataWithOutlierHistorical, {
+      excludeQuantileBands: true,
+      hiddenSeries,
+      includeHiddenInYScale: false,
+    });
+
+    expect(range).toEqual({ yMin: 49, yMax: 61 });
+  });
+
+  it('includeHiddenInYScale=true preserves old behavior', () => {
+    const hiddenSeries = new Set(['forecast_1']);
+    const range = calculateChartYRange(chartData, {
+      excludeQuantileBands: true,
+      hiddenSeries,
+      includeHiddenInYScale: true,
+    });
+
+    expect(range).toEqual({ yMin: 1, yMax: 109 });
+  });
+
+  it('quantile keys excluded when forecast hidden', () => {
+    const dataWithQuantile: ChartDataPoint[] = [
+      makePoint({ forecast_456: 50, forecast_789: 70, 'q0.05_123': 500 }),
+    ];
+    const hiddenSeries = new Set(['forecast_123']);
+    const range = calculateChartYRange(dataWithQuantile, {
+      excludeQuantileBands: false,
+      hiddenSeries,
+      includeHiddenInYScale: false,
+    });
+
+    expect(range).toEqual({ yMin: 48, yMax: 72 });
+  });
+});

package/src/components/ui/ChartAreaInteractive/overlays/useChartYRange.ts

@@ -11,6 +11,137 @@ interface UseChartYRangeOptions {
   selectedForecastId?: number;
 }
 
+export interface CalculateChartYRangeOptions {
+  excludeQuantileBands: boolean;
+  forecastId?: number;
+  hiddenSeries?: Set<string>;
+  includeHiddenInYScale?: boolean;
+}
+
+/** Serialize hidden series keys for stable cache comparison. */
+function serializeHiddenSeries(hiddenSeries?: Set<string>): string {
+  if (!hiddenSeries || hiddenSeries.size === 0) return '';
+  return [...hiddenSeries].sort().join(',');
+}
+
+/**
+ * Returns true when a chart data key should be skipped for Y-scale (series hidden).
+ */
+export function isKeyExcludedFromYScale(
+  key: string,
+  hiddenSeries?: Set<string>,
+): boolean {
+  if (!hiddenSeries || hiddenSeries.size === 0) return false;
+
+  if (key === 'historical') {
+    return hiddenSeries.has('historical');
+  }
+
+  if (key.startsWith('forecast_')) {
+    return hiddenSeries.has(key);
+  }
+
+  if (key.startsWith('q') && key.includes('_')) {
+    const forecastId = key.slice(key.lastIndexOf('_') + 1);
+    return hiddenSeries.has(`forecast_${forecastId}`);
+  }
+
+  if (key.startsWith('band_')) {
+    const forecastId = key.slice(key.lastIndexOf('_') + 1);
+    return hiddenSeries.has(`forecast_${forecastId}`);
+  }
+
+  return false;
+}
+
+/** Pure Y-range calculation from chart data points. */
+export function calculateChartYRange(
+  dataToUse: ChartDataPoint[],
+  {
+    excludeQuantileBands,
+    forecastId,
+    hiddenSeries,
+    includeHiddenInYScale = false,
+  }: CalculateChartYRangeOptions,
+) {
+  const allValues: number[] = [];
+
+  dataToUse.forEach(point => {
+    Object.entries(point).forEach(([key, value]) => {
+      if (key === 'date') return;
+
+      if (
+        !includeHiddenInYScale &&
+        isKeyExcludedFromYScale(key, hiddenSeries)
+      ) {
+        return;
+      }
+
+      // When selectedForecastId is provided, scale from historical + selected forecast + its
+      // quantile band (exclude other forecasts and their quantile values only).
+      if (forecastId !== undefined) {
+        if (key.startsWith('forecast_') && key !== `forecast_${forecastId}`)
+          return;
+        // Exclude q{quantile}_{otherAnalysisId} - only include selected forecast's quantiles
+        if (key.startsWith('q') && !key.endsWith(`_${forecastId}`)) return;
+      }
+
+      // When excludeQuantileBands is true, exclude:
+      // 1. Quantile band arrays ([number, number])
+      // 2. Individual quantile values (q{quantile}_{analysisId} properties)
+      // Only include historical and forecast line values
+      if (excludeQuantileBands) {
+        // Skip quantile band arrays
+        if (
+          Array.isArray(value) &&
+          value.length === 2 &&
+          typeof value[0] === 'number' &&
+          typeof value[1] === 'number'
+        ) {
+          return;
+        }
+
+        // Skip individual quantile values (properties starting with 'q' followed by number/underscore)
+        // Format: q{quantile}_{analysisId} (e.g., q0.05_123, q0.95_123)
+        if (key.startsWith('q') && typeof value === 'number') {
+          return;
+        }
+
+        // Include only historical and forecast line values
+        if (typeof value === 'number') {
+          allValues.push(value);
+        }
+        return;
+      }
+
+      // When not excluding, include both numbers and quantile band arrays
+      if (typeof value === 'number') {
+        allValues.push(value);
+      } else if (
+        Array.isArray(value) &&
+        value.length === 2 &&
+        typeof value[0] === 'number' &&
+        typeof value[1] === 'number'
+      ) {
+        allValues.push(value[0], value[1]);
+      }
+    });
+  });
+
+  if (allValues.length === 0) {
+    return { yMin: 0, yMax: 100 };
+  }
+
+  const min = Math.min(...allValues);
+  const max = Math.max(...allValues);
+  const diff = max - min;
+
+  return {
+    yMin: min - diff * 0.1,
+    yMax: max + diff * 0.1,
+  };
+}
+
 /**
  * Hook to calculate yMin and yMax from chart data
  * Optionally includes quantile values from forecast data
@@ -22,6 +153,9 @@ export function useChartYRange({
   excludeQuantileBands = false,
   selectedForecastId,
 }: UseChartYRangeOptions) {
+  const includeHiddenInYScale = baseChartProps.includeHiddenInYScale ?? false;
+  const hiddenSeries = baseChartProps.hiddenSeries;
+
   // Store initial Y-range when disableRescaleWhenQuantileChanges is true
   const stableYRangeRef = useRef<{
     yMin: number;
@@ -29,84 +163,20 @@ export function useChartYRange({
     forecastId?: number;
   } | null>(null);
   const prevBaseChartDataRef = useRef(baseChartProps.chartData);
+  const prevHiddenSeriesKeyRef = useRef(serializeHiddenSeries(hiddenSeries));
 
-  // Helper function to calculate Y-range from data
   const calculateYRange = (
     dataToUse: ChartDataPoint[],
-    excludeQuantileBands: boolean,
+    excludeBands: boolean,
     forecastId?: number,
-  ) => {
-    const allValues: number[] = [];
-
-    dataToUse.forEach(point => {
-      Object.entries(point).forEach(([key, value]) => {
-        if (key === 'date') return;
-
-        // When selectedForecastId is provided, scale from historical + selected forecast + its
-        // quantile band (exclude other forecasts and their quantile values only).
-        if (forecastId !== undefined) {
-          if (key.startsWith('forecast_') && key !== `forecast_${forecastId}`)
-            return;
-          // Exclude q{quantile}_{otherAnalysisId} - only include selected forecast's quantiles
-          if (key.startsWith('q') && !key.endsWith(`_${forecastId}`)) return;
-        }
-
-        // When excludeQuantileBands is true, exclude:
-        // 1. Quantile band arrays ([number, number])
-        // 2. Individual quantile values (q{quantile}_{analysisId} properties)
-        // Only include historical and forecast line values
-        if (excludeQuantileBands) {
-          // Skip quantile band arrays
-          if (
-            Array.isArray(value) &&
-            value.length === 2 &&
-            typeof value[0] === 'number' &&
-            typeof value[1] === 'number'
-          ) {
-            return;
-          }
-
-          // Skip individual quantile values (properties starting with 'q' followed by number/underscore)
-          // Format: q{quantile}_{analysisId} (e.g., q0.05_123, q0.95_123)
-          if (key.startsWith('q') && typeof value === 'number') {
-            return;
-          }
-
-          // Include only historical and forecast line values
-          if (typeof value === 'number') {
-            allValues.push(value);
-          }
-          return;
-        }
-
-        // When not excluding, include both numbers and quantile band arrays
-        if (typeof value === 'number') {
-          allValues.push(value);
-        } else if (
-          Array.isArray(value) &&
-          value.length === 2 &&
-          typeof value[0] === 'number' &&
-          typeof value[1] === 'number'
-        ) {
-          allValues.push(value[0], value[1]);
-        }
-      });
+  ) =>
+    calculateChartYRange(dataToUse, {
+      excludeQuantileBands: excludeBands,
+      forecastId,
+      hiddenSeries,
+      includeHiddenInYScale,
     });
 
-    if (allValues.length === 0) {
-      return { yMin: 0, yMax: 100 };
-    }
-
-    const min = Math.min(...allValues);
-    const max = Math.max(...allValues);
-    const diff = max - min;
-
-    return {
-      yMin: min - diff * 0.1,
-      yMax: max + diff * 0.1,
-    };
-  };
-
   // When disableRescaleWhenQuantileChanges is true, calculate initial stable range
   // If chartData (transformedChartData) is provided, use it WITH quantile bands for initial calculation
   // Then keep it stable when dragging quantiles
@@ -125,7 +195,7 @@ export function useChartYRange({
       return null;
     }
 
-    // Reset stable range when dataset or selected forecast changes
+    // Reset stable range when dataset, selected forecast, or hidden series changes
     if (prevBaseChartDataRef.current !== baseChartProps.chartData) {
       prevBaseChartDataRef.current = baseChartProps.chartData;
       stableYRangeRef.current = null;
@@ -133,6 +203,11 @@ export function useChartYRange({
     if (stableYRangeRef.current?.forecastId !== selectedForecastId) {
       stableYRangeRef.current = null;
     }
+    const hiddenSeriesKey = serializeHiddenSeries(hiddenSeries);
+    if (prevHiddenSeriesKeyRef.current !== hiddenSeriesKey) {
+      prevHiddenSeriesKeyRef.current = hiddenSeriesKey;
+      stableYRangeRef.current = null;
+    }
 
     // If chartData (transformedChartData) is provided, use it WITH quantile bands for initial calculation
     // This ensures IntervalsOverlay includes quantile bands in Y-scale
@@ -164,6 +239,8 @@ export function useChartYRange({
     disableRescaleWhenQuantileChanges,
     excludeQuantileBands,
     selectedForecastId,
+    hiddenSeries,
+    includeHiddenInYScale,
   ]);
 
   // When disableRescaleWhenQuantileChanges is false, calculate from transformed data
@@ -192,6 +269,8 @@ export function useChartYRange({
     disableRescaleWhenQuantileChanges,
     excludeQuantileBands,
     selectedForecastId,
+    hiddenSeries,
+    includeHiddenInYScale,
   ]);
 
   // Return appropriate range

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

@@ -10,7 +10,7 @@ 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)
+- `viewTab` / `onViewTabChange`: `lagged` (calendar-aligned, raw dates) or `overlapped` (driver series shifted backward 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.
 
@@ -18,8 +18,8 @@ Report tile: `drivers_comparison_chart` — host loads normalized backtests payl
 
 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).
+Lag column: **Lagged** shows API `lag` string (may be a range). **Overlapped** shows single `N month(s)` from `parseLagMonthsFromLabel` (range uses max month).
 
-Historical window: lead-in is anchored to the **overlapped** view (`computeDriversComparisonHistoricalWindowFloor`); lagged tab shifts driver lines only — switching tabs does not change historical extent.
+Historical window: lead-in is anchored to the **lagged** (unshifted) view (`computeDriversComparisonHistoricalWindowFloor`); overlapped tab shifts driver lines backward only — switching tabs does not change historical extent when floor is pinned.
 
 Empty/loading: loading props shimmer chart; null `payload` with `runAnalysisHint` prompts to run analysis.

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

@@ -160,10 +160,10 @@ export function DriversComparisonChart({
   );
 
   const historicalWindowFloor = useMemo(() => {
-    const overlappedMerged = mergeBacktestsChartData(payload);
+    const laggedMerged = mergeBacktestsChartData(payload);
     const merged = mergeDatasetHistoricalWithBacktestsChartData(
       datasetHistorical,
-      overlappedMerged,
+      laggedMerged,
     );
     const sortedDrivers = [...(payload?.drivers ?? [])]
       .filter(

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

@@ -12,6 +12,7 @@ import {
   mergeDatasetHistoricalWithBacktestsChartData,
   parseLagMonthsFromLabel,
   resolveDriverLagLabel,
+  shiftNormalizedSeriesBackward,
   shiftNormalizedSeriesForward,
   subtractMonthsFromMonthStart,
 } from './driversComparisonChart.helpers';
@@ -58,17 +59,17 @@ describe('formatLagMonthsLabel', () => {
 });
 
 describe('getLagDisplayForView', () => {
-  it('shows API lag on overlapped tab', () => {
-    expect(getLagDisplayForView('9 to 12 month(s)', 'overlapped')).toBe(
+  it('shows API lag on lagged tab', () => {
+    expect(getLagDisplayForView('9 to 12 month(s)', 'lagged')).toBe(
       '9 to 12 month(s)',
     );
   });
 
-  it('shows parsed month on lagged tab', () => {
-    expect(getLagDisplayForView('9 to 12 month(s)', 'lagged')).toBe(
+  it('shows parsed month on overlapped tab', () => {
+    expect(getLagDisplayForView('9 to 12 month(s)', 'overlapped')).toBe(
       '12 month(s)',
     );
-    expect(getLagDisplayForView('Unknown', 'lagged')).toBe('—');
+    expect(getLagDisplayForView('Unknown', 'overlapped')).toBe('—');
   });
 });
 
@@ -90,6 +91,24 @@ describe('shiftNormalizedSeriesForward', () => {
   });
 });
 
+describe('shiftNormalizedSeriesBackward', () => {
+  it('moves points backward by lag months', () => {
+    const shifted = shiftNormalizedSeriesBackward(
+      { '2015-03-01': 1.2, '2015-04-01': 1.4 },
+      2,
+    );
+    expect(shifted['2015-01-01']).toBe(1.2);
+    expect(shifted['2015-02-01']).toBe(1.4);
+  });
+
+  it('returns a shallow copy when lag is zero', () => {
+    const series = { '2015-01-01': 1 };
+    const shifted = shiftNormalizedSeriesBackward(series, 0);
+    expect(shifted).toEqual(series);
+    expect(shifted).not.toBe(series);
+  });
+});
+
 describe('applyDriversComparisonViewToPayload', () => {
   const payload = {
     target: {
@@ -107,18 +126,19 @@ describe('applyDriversComparisonViewToPayload', () => {
     ],
   };
 
-  it('returns original payload for overlapped tab', () => {
-    expect(applyDriversComparisonViewToPayload(payload, 'overlapped')).toBe(
-      payload,
-    );
+  it('returns original payload for lagged tab', () => {
+    expect(applyDriversComparisonViewToPayload(payload, 'lagged')).toBe(payload);
   });
 
-  it('shifts driver series for lagged tab without mutating source', () => {
-    const lagged = applyDriversComparisonViewToPayload(payload, 'lagged');
-    expect(lagged).not.toBe(payload);
+  it('shifts driver series backward for overlapped tab without mutating source', () => {
+    const overlapped = applyDriversComparisonViewToPayload(
+      payload,
+      'overlapped',
+    );
+    expect(overlapped).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(
+    expect(overlapped?.drivers[0].normalized_series['2014-11-01']).toBe(0.5);
+    expect(overlapped?.target.normalized_series).toEqual(
       payload.target.normalized_series,
     );
   });
@@ -135,11 +155,11 @@ describe('applyDriversComparisonViewToPayload', () => {
         },
       ],
     };
-    const lagged = applyDriversComparisonViewToPayload(
+    const overlapped = applyDriversComparisonViewToPayload(
       withOverallLag,
-      'lagged',
+      'overlapped',
     );
-    expect(lagged?.drivers[0].normalized_series['2015-07-01']).toBe(0.8);
+    expect(overlapped?.drivers[0].normalized_series['2015-05-01']).toBe(0.8);
   });
 });
 
@@ -184,7 +204,7 @@ describe('computeDriversComparisonHistoricalWindowFloor', () => {
 
   const forecastIds = [DRIVER_FORECAST_ID_BASE];
 
-  it('returns anchor minus lead months from overlapped merged data', () => {
+  it('returns anchor minus lead months from lagged (unshifted) merged data', () => {
     const merged = mergeDatasetHistoricalWithBacktestsChartData(
       datasetHistorical,
       mergeBacktestsChartData(laggedDriverPayload),
@@ -245,70 +265,70 @@ describe('buildDriversComparisonChartData historical window floor', () => {
   const forecastIds = [DRIVER_FORECAST_ID_BASE];
 
   it('keeps same xMin for lagged and overlapped when floor is pinned', () => {
-    const overlappedMerged = mergeDatasetHistoricalWithBacktestsChartData(
+    const laggedMerged = mergeDatasetHistoricalWithBacktestsChartData(
       datasetHistorical,
       mergeBacktestsChartData(laggedDriverPayload),
     );
-    const laggedPayload = applyDriversComparisonViewToPayload(
+    const overlappedPayload = applyDriversComparisonViewToPayload(
       laggedDriverPayload,
-      'lagged',
+      'overlapped',
     );
-    const laggedMerged = mergeDatasetHistoricalWithBacktestsChartData(
+    const overlappedMerged = mergeDatasetHistoricalWithBacktestsChartData(
       datasetHistorical,
-      mergeBacktestsChartData(laggedPayload),
+      mergeBacktestsChartData(overlappedPayload),
     );
     const floor = computeDriversComparisonHistoricalWindowFloor(
-      overlappedMerged,
+      laggedMerged,
       forecastIds,
     )!;
 
-    const overlappedChart = buildDriversComparisonChartData(
-      overlappedMerged,
+    const laggedChart = buildDriversComparisonChartData(
+      laggedMerged,
       datasetHistorical,
       forecastIds,
       floor,
     );
-    const laggedChart = buildDriversComparisonChartData(
-      laggedMerged,
+    const overlappedChart = buildDriversComparisonChartData(
+      overlappedMerged,
       datasetHistorical,
       forecastIds,
       floor,
     );
 
-    expect(overlappedChart[0]?.date).toBe('2014-10-01');
     expect(laggedChart[0]?.date).toBe('2014-10-01');
-    expect(laggedChart[0]?.date).toBe(overlappedChart[0]?.date);
+    expect(overlappedChart[0]?.date).toBe('2014-10-01');
+    expect(overlappedChart[0]?.date).toBe(laggedChart[0]?.date);
   });
 
-  it('without floor override lagged chart starts later than overlapped', () => {
-    const overlappedMerged = mergeDatasetHistoricalWithBacktestsChartData(
+  it('without floor override overlapped chart starts earlier than lagged', () => {
+    const laggedMerged = mergeDatasetHistoricalWithBacktestsChartData(
       datasetHistorical,
       mergeBacktestsChartData(laggedDriverPayload),
     );
-    const laggedPayload = applyDriversComparisonViewToPayload(
+    const overlappedPayload = applyDriversComparisonViewToPayload(
       laggedDriverPayload,
-      'lagged',
+      'overlapped',
     );
-    const laggedMerged = mergeDatasetHistoricalWithBacktestsChartData(
+    const overlappedMerged = mergeDatasetHistoricalWithBacktestsChartData(
       datasetHistorical,
-      mergeBacktestsChartData(laggedPayload),
+      mergeBacktestsChartData(overlappedPayload),
     );
 
-    const overlappedChart = buildDriversComparisonChartData(
-      overlappedMerged,
+    const laggedChart = buildDriversComparisonChartData(
+      laggedMerged,
       datasetHistorical,
       forecastIds,
     );
-    const laggedChart = buildDriversComparisonChartData(
-      laggedMerged,
+    const overlappedChart = buildDriversComparisonChartData(
+      overlappedMerged,
       datasetHistorical,
       forecastIds,
     );
 
-    expect(overlappedChart[0]?.date).toBe('2014-10-01');
-    expect(laggedChart[0]?.date).toBe('2015-01-01');
-    expect(laggedChart[0]?.date!.localeCompare(overlappedChart[0]?.date!)).toBe(
-      1,
-    );
+    expect(laggedChart[0]?.date).toBe('2014-10-01');
+    expect(overlappedChart[0]?.date).toBe('2014-07-01');
+    expect(
+      overlappedChart[0]?.date!.localeCompare(laggedChart[0]?.date!),
+    ).toBe(-1);
   });
 });

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

@@ -78,7 +78,7 @@ export function getLagDisplayForView(
   lag: string | null | undefined,
   tab: DriversComparisonViewTab,
 ): string {
-  if (tab === 'overlapped') {
+  if (tab === 'lagged') {
     return lag?.trim() ? lag : '—';
   }
   const months = parseLagMonthsFromLabel(lag);
@@ -102,11 +102,29 @@ export function shiftNormalizedSeriesForward(
   return out;
 }
 
+/** Shift driver points left (earlier months) by lag — overlapped alignment vs target. */
+export function shiftNormalizedSeriesBackward(
+  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 = getPreviousMonth(shifted);
+    }
+    out[shifted] = val;
+  }
+  return out;
+}
+
 export function applyDriversComparisonViewToPayload(
   payload: BacktestsComponentPayload | null,
   tab: DriversComparisonViewTab,
 ): BacktestsComponentPayload | null {
-  if (!payload || tab === 'overlapped') return payload;
+  if (!payload || tab === 'lagged') return payload;
 
   return {
     target: {
@@ -118,7 +136,7 @@ export function applyDriversComparisonViewToPayload(
       const series = driver.normalized_series ?? {};
       const normalized_series =
         lagMonths != null && lagMonths > 0
-          ? shiftNormalizedSeriesForward(series, lagMonths)
+          ? shiftNormalizedSeriesBackward(series, lagMonths)
           : { ...series };
       return {
         ...driver,
@@ -290,7 +308,7 @@ export function prependHistoricalLeadFromDataset(
   return [...lead, ...points];
 }
 
-/** Overlapped (unshifted) anchor minus lead months — stable xMin across lagged/overlapped tabs. */
+/** Lagged (unshifted) anchor minus lead months — stable xMin across lagged/overlapped tabs. */
 export function computeDriversComparisonHistoricalWindowFloor(
   mergedWithHistorical: ChartDataPoint[],
   forecastIds: number[],

package/src/docs/pages/IncludeHiddenInYScalePage.tsx

@@ -0,0 +1,152 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import { ChartAreaInteractive } from '#uilib/components/ui/ChartAreaInteractive';
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+import type { ForecastItemData } from '#uilib/components/ui/ChartAreaInteractive/ChartLines';
+import { calculateChartYRange } from '#uilib/components/ui/ChartAreaInteractive/overlays/useChartYRange';
+import { Label } from '#uilib/components/ui/Label';
+import { PageContentSection } from '#uilib/components/ui/Page';
+import { Switch } from '#uilib/components/ui/Switch';
+import { useTheme } from '#uilib/contexts/theme-context';
+
+import { AppPageHeader } from '../components/AppPageHeader/AppPageHeader';
+import { DocsHeaderActions } from '../docsHeaderActions';
+
+const FORECAST_BASELINE_ID = 1;
+const FORECAST_HIGH_ID = 2;
+
+const DEMO_FORECAST_ITEMS: ForecastItemData[] = [
+  { id: FORECAST_BASELINE_ID, name: 'Baseline forecast' },
+  { id: FORECAST_HIGH_ID, name: 'High scenario (hidden)' },
+];
+
+const INITIAL_CHART: ChartDataPoint[] = [
+  { date: '2022-01-01', historical: 8 },
+  { date: '2022-02-01', historical: 10 },
+  { date: '2022-03-01', historical: 9 },
+  { date: '2022-04-01', historical: 12 },
+  { date: '2022-05-01', historical: 11 },
+  { date: '2022-06-01', historical: 12 },
+  { date: '2022-07-01', historical: 13 },
+  { date: '2022-08-01', historical: 12 },
+  { date: '2022-09-01', historical: 14 },
+  { date: '2022-10-01', historical: 13 },
+  { date: '2022-11-01', historical: 15 },
+  { date: '2022-12-01', historical: 14 },
+  { date: '2023-01-01', historical: 10 },
+  { date: '2023-02-01', historical: 12 },
+  { date: '2023-03-01', historical: 11 },
+  { date: '2023-04-01', historical: 14 },
+  { date: '2023-05-01', historical: 13 },
+  {
+    date: '2023-06-01',
+    [`forecast_${FORECAST_BASELINE_ID}`]: 13.5,
+    [`forecast_${FORECAST_HIGH_ID}`]: 88,
+  },
+  {
+    date: '2023-07-01',
+    [`forecast_${FORECAST_BASELINE_ID}`]: 14,
+    [`forecast_${FORECAST_HIGH_ID}`]: 92,
+  },
+  {
+    date: '2023-08-01',
+    [`forecast_${FORECAST_BASELINE_ID}`]: 15,
+    [`forecast_${FORECAST_HIGH_ID}`]: 95,
+  },
+];
+
+export default function IncludeHiddenInYScalePage() {
+  const { isDarkMode } = useTheme();
+  const [timeRange, setTimeRange] = useState<string>('All');
+  const [chartData] = useState<ChartDataPoint[]>(INITIAL_CHART);
+  const [hidden, setHidden] = useState<Set<string>>(
+    () => new Set([`forecast_${FORECAST_HIGH_ID}`]),
+  );
+  const [includeHiddenInYScale, setIncludeHiddenInYScale] = useState(false);
+
+  const toggleLegendSeries = useCallback((key: string) => {
+    setHidden(prev => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }, []);
+
+  const ensureAnalysisSeriesVisible = useCallback(() => {}, []);
+
+  const yRange = useMemo(
+    () =>
+      calculateChartYRange(chartData, {
+        excludeQuantileBands: true,
+        hiddenSeries: hidden,
+        includeHiddenInYScale,
+      }),
+    [chartData, hidden, includeHiddenInYScale],
+  );
+
+  return (
+    <>
+      <AppPageHeader
+        breadcrumbs={[{ label: 'includeHiddenInYScale' }]}
+        title="includeHiddenInYScale"
+        subheader={
+          <>
+            <code>BaseChartWrapper</code> / <code>ChartAreaInteractive</code>{' '}
+            prop. When <code>false</code> (default), hidden legend series are
+            excluded from Y-axis domain; when <code>true</code>, hidden values
+            still expand the scale (legacy behavior). Toggle the high scenario
+            in the legend, then flip the switch to compare.
+          </>
+        }
+        actions={<DocsHeaderActions />}
+      />
+      <PageContentSection>
+        <div
+          style={{
+            display: 'flex',
+            flexWrap: 'wrap',
+            alignItems: 'center',
+            gap: 16,
+            marginBottom: 16,
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            <Switch
+              id="include-hidden-y-scale"
+              checked={includeHiddenInYScale}
+              onCheckedChange={setIncludeHiddenInYScale}
+            />
+            <Label htmlFor="include-hidden-y-scale">
+              includeHiddenInYScale
+            </Label>
+          </div>
+          <span style={{ color: 'var(--muted-foreground)', fontSize: 13 }}>
+            Y domain: {yRange.yMin} – {yRange.yMax}
+            {hidden.has(`forecast_${FORECAST_HIGH_ID}`)
+              ? ' (high scenario hidden)'
+              : ' (all series visible)'}
+          </span>
+        </div>
+        <ChartAreaInteractive
+          timeRange={timeRange}
+          onTimeRangeChange={setTimeRange}
+          pinMonth={undefined}
+          onPinMonthChange={() => {}}
+          chartData={chartData}
+          forecastData={DEMO_FORECAST_ITEMS}
+          loading={false}
+          isDarkTheme={isDarkMode}
+          toggleLegendSeries={toggleLegendSeries}
+          ensureAnalysisSeriesVisible={ensureAnalysisSeriesVisible}
+          hiddenSeries={hidden}
+          includeHiddenInYScale={includeHiddenInYScale}
+          yMin={yRange.yMin}
+          yMax={yRange.yMax}
+          autoScaleYAxis={false}
+          disableTimeRangeSelector
+        />
+      </PageContentSection>
+    </>
+  );
+}

package/src/docs/registry.ts

@@ -97,6 +97,12 @@ export const DOC_REGISTRY: DocEntry[] = [
     section: 'Charts',
     load: () => import('./pages/ChartAreaInteractivePage'),
   },
+  {
+    slug: 'include-hidden-in-y-scale',
+    title: 'includeHiddenInYScale',
+    section: 'Charts',
+    load: () => import('./pages/IncludeHiddenInYScalePage'),
+  },
   {
     slug: 'lightweight-forecast-chart',
     title: 'LightweightForecastChart',