@sybilion/uilib 1.3.62 → 1.3.63

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/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/package.json

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

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[],