@sybilion/uilib 1.3.21 → 1.3.23

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);
+}