@sybilion/uilib 1.0.20

package/src/utils/chartConnectionPoint.ts

@@ -0,0 +1,292 @@
+/**
+ * Utility functions for ensuring consistent connection points between historical and forecast data
+ * across all chart components.
+ */
+import type {
+  SeriesForecastData,
+  TimeSeriesPoint,
+} from '#uilib/components/ui/Chart/chartForecastVisualization.types';
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+
+export type EnsureChartForecastBridgeOptions = {
+  forecastSeriesIds?: number[];
+  /** When true, returns `chartData` unchanged */
+  disabled?: boolean;
+};
+
+const FORECAST_KEY_RE = /^forecast_(\d+)$/;
+
+function collectForecastSeriesIds(chartData: ChartDataPoint[]): number[] {
+  const ids = new Set<number>();
+  for (const row of chartData) {
+    for (const key of Object.keys(row)) {
+      const m = key.match(FORECAST_KEY_RE);
+      if (m) ids.add(Number(m[1]));
+    }
+  }
+  return [...ids].sort((a, b) => a - b);
+}
+
+function forecastSeriesKey(id: number): string {
+  return `forecast_${id}`;
+}
+
+function hasForecastValue(point: ChartDataPoint, id: number): boolean {
+  const v = point[forecastSeriesKey(id)];
+  return v !== null && v !== undefined && typeof v === 'number';
+}
+
+/**
+ * Injects `forecast_{id}` on the row before each series’ first forecast month (historical value)
+ * so dashed forecast lines meet the historical line. Matches sybilion-client bridge behavior.
+ * Never overwrites an existing forecast value on that row.
+ */
+export function ensureChartForecastBridge(
+  chartData: ChartDataPoint[],
+  options?: EnsureChartForecastBridgeOptions,
+): ChartDataPoint[] {
+  if (options?.disabled || chartData.length === 0) {
+    return chartData;
+  }
+
+  const sorted = [...chartData].sort(
+    (a, b) => new Date(a.date).getTime() - new Date(b.date).getTime(),
+  );
+
+  const seriesIds = options?.forecastSeriesIds?.length
+    ? [...options.forecastSeriesIds]
+    : collectForecastSeriesIds(sorted);
+
+  if (seriesIds.length === 0) {
+    return sorted;
+  }
+
+  const rows = sorted.map(p => ({ ...p }));
+
+  for (const id of seriesIds) {
+    const dataKey = forecastSeriesKey(id);
+    let firstForecastDate: string | null = null;
+    for (const row of rows) {
+      if (hasForecastValue(row, id)) {
+        firstForecastDate = row.date;
+        break;
+      }
+    }
+    if (!firstForecastDate) continue;
+
+    const prevMonthNorm = normalizeToMonthStart(
+      getPreviousMonth(firstForecastDate),
+    );
+
+    const prevMonthIdx = rows.findIndex(
+      row => normalizeToMonthStart(row.date) === prevMonthNorm,
+    );
+
+    if (prevMonthIdx >= 0) {
+      const existing = rows[prevMonthIdx][dataKey];
+      const hPrev = rows[prevMonthIdx].historical;
+      if (
+        (existing === undefined || existing === null) &&
+        hPrev !== undefined &&
+        hPrev !== null
+      ) {
+        rows[prevMonthIdx] = {
+          ...rows[prevMonthIdx],
+          [dataKey]: hPrev,
+        };
+      }
+    }
+
+    const lastHist = findLastValidHistoricalChartPoint(rows);
+    if (!lastHist) continue;
+
+    const normLast = normalizeToMonthStart(lastHist.date);
+    const normFirst = normalizeToMonthStart(firstForecastDate);
+    if (normLast >= normFirst) continue;
+
+    const idxLast = rows.findIndex(r => r.date === lastHist.date);
+    if (idxLast < 0) continue;
+
+    const existingAtLast = rows[idxLast][dataKey];
+    if (existingAtLast !== undefined && existingAtLast !== null) continue;
+
+    const hLast = rows[idxLast].historical;
+    if (hLast !== undefined && hLast !== null) {
+      rows[idxLast] = { ...rows[idxLast], [dataKey]: hLast };
+    }
+  }
+
+  return rows;
+}
+
+/**
+ * Find the last valid historical data point (filtering out null/undefined values)
+ */
+export function findLastValidHistoricalPoint(
+  historical: TimeSeriesPoint[],
+): TimeSeriesPoint | null {
+  const validPoints = historical.filter(
+    ([, value]) => value !== null && value !== undefined,
+  );
+  return validPoints.length > 0 ? validPoints[validPoints.length - 1] : null;
+}
+
+/**
+ * Find the last valid historical data point from ChartDataPoint array
+ */
+export function findLastValidHistoricalChartPoint(
+  historical: ChartDataPoint[],
+): ChartDataPoint | null {
+  const validPoints = historical.filter(
+    point => point.historical !== null && point.historical !== undefined,
+  );
+  return validPoints.length > 0 ? validPoints[validPoints.length - 1] : null;
+}
+
+/**
+ * Check if two dates are in the same month (ignoring day)
+ */
+export function isSameMonth(date1: string, date2: string): boolean {
+  const d1 = new Date(date1);
+  const d2 = new Date(date2);
+  return (
+    d1.getFullYear() === d2.getFullYear() && d1.getMonth() === d2.getMonth()
+  );
+}
+
+/**
+ * Normalize date to first day of month for comparison (YYYY-MM-01)
+ */
+export function normalizeToMonthStart(date: string): string {
+  const d = new Date(date);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-01`;
+}
+
+/**
+ * Find the earliest date from forecast_series keys
+ * This represents the first forecast date
+ */
+export function findEarliestForecastDate(
+  forecastSeries: Record<string, unknown>,
+): string | null {
+  const dates = Object.keys(forecastSeries).sort(
+    (a, b) => new Date(a).getTime() - new Date(b).getTime(),
+  );
+  return dates.length > 0 ? dates[0] : null;
+}
+
+/**
+ * Find the latest date from forecast_series keys
+ * This represents the last forecast date
+ */
+export function findLatestForecastDate(
+  forecastSeries: Record<string, unknown>,
+): string | null {
+  const dates = Object.keys(forecastSeries).sort(
+    (a, b) => new Date(a).getTime() - new Date(b).getTime(),
+  );
+  return dates.length > 0 ? dates[dates.length - 1] : null;
+}
+
+/**
+ * Get the previous month date (first day of previous month)
+ */
+export function getPreviousMonth(date: string): string {
+  const d = new Date(date);
+  d.setMonth(d.getMonth() - 1);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-01`;
+}
+
+/**
+ * Get the next month date (first day of next month)
+ */
+export function getNextMonth(date: string): string {
+  const d = new Date(date);
+  d.setMonth(d.getMonth() + 1);
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-01`;
+}
+
+/**
+ * Ensure forecast data includes a connection point at the previous month before the first forecast
+ * This ensures visual continuity without overwriting actual forecast values
+ *
+ * We don't use last_valid_data_index - we derive the connection point directly from the forecast data:
+ * 1. Find the earliest date from forecast_series (first forecast date)
+ * 2. Get the previous month (connection point date)
+ * 3. Add connection point at that date with the historical value from that month
+ */
+export function ensureForecastConnectionPoint(
+  forecast: SeriesForecastData,
+  historical: TimeSeriesPoint[],
+): SeriesForecastData {
+  const newForecast = structuredClone(forecast);
+  const forecastDates = Object.keys(newForecast.forecast_series).sort();
+
+  // Find last valid historical point
+  const lastHistorical = findLastValidHistoricalPoint(historical);
+  if (!lastHistorical) {
+    return newForecast;
+  }
+
+  const [lastHistoricalDate, lastHistoricalValue] = lastHistorical;
+
+  // Determine the connection point date
+  // Find the earliest date from forecast_series (first forecast date)
+  const earliestForecastDate = findEarliestForecastDate(
+    newForecast.forecast_series,
+  );
+
+  if (!earliestForecastDate) {
+    // No forecast dates found, nothing to connect
+    return newForecast;
+  }
+
+  // Use the month before the first forecast date as connection point
+  const connectionDate = getPreviousMonth(earliestForecastDate);
+
+  // Normalize dates for comparison
+  const normalizedConnectionDate = normalizeToMonthStart(connectionDate);
+  const normalizedLastHistorical = normalizeToMonthStart(lastHistoricalDate);
+
+  // Only add connection point if it's at the last historical month
+  // and doesn't overwrite an actual forecast value
+  if (normalizedConnectionDate === normalizedLastHistorical) {
+    // Check if this date already exists in forecast_series
+    const existingForecastDate = forecastDates.find(date =>
+      isSameMonth(date, connectionDate!),
+    );
+
+    if (existingForecastDate) {
+      // If forecast already has this date, preserve the forecast value
+      // and only add connection if dates don't match exactly
+      if (existingForecastDate !== connectionDate) {
+        // Add connection point at exact historical date
+        newForecast.forecast_series[connectionDate] = {
+          forecast: lastHistoricalValue,
+          // Preserve existing properties if any
+          ...newForecast.forecast_series[existingForecastDate],
+        };
+      }
+      // If dates match exactly, don't overwrite - the forecast value should be preserved
+    } else {
+      // No existing forecast at this date, safe to add connection point
+      newForecast.forecast_series[connectionDate] = {
+        forecast: lastHistoricalValue,
+      };
+    }
+  }
+
+  // Sort forecast series by date
+  const sortedSeries = Object.keys(newForecast.forecast_series)
+    .sort((a, b) => new Date(a).getTime() - new Date(b).getTime())
+    .reduce(
+      (acc, key) => {
+        acc[key] = newForecast.forecast_series[key];
+        return acc;
+      },
+      {} as typeof newForecast.forecast_series,
+    );
+
+  newForecast.forecast_series = sortedSeries;
+  return newForecast;
+}

package/src/utils/chartRenderQueue.ts

@@ -0,0 +1,52 @@
+const RENDER_DELAY = 200; // ms between chart renders
+
+class ChartRenderQueue {
+  private queue: Array<() => void> = [];
+  private isProcessing = false;
+  private timeoutId: NodeJS.Timeout | null = null;
+
+  registerCallback(callback: () => void): void {
+    if (this.queue.length === 0 && !this.isProcessing) {
+      // Queue is empty, call immediately
+      this.isProcessing = true;
+      callback();
+      // Process next callback after delay
+      this.timeoutId = setTimeout(() => {
+        this.isProcessing = false;
+        this.processNext();
+      }, RENDER_DELAY);
+    } else {
+      // Add to queue
+      this.queue.push(callback);
+    }
+  }
+
+  private processNext(): void {
+    if (this.queue.length === 0) {
+      this.isProcessing = false;
+      return;
+    }
+
+    this.isProcessing = true;
+    const callback = this.queue.shift();
+    if (callback) {
+      callback();
+      // Process next callback after delay
+      this.timeoutId = setTimeout(() => {
+        this.isProcessing = false;
+        this.processNext();
+      }, RENDER_DELAY);
+    }
+  }
+
+  clear(): void {
+    this.queue = [];
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+    this.isProcessing = false;
+  }
+}
+
+export const chartRenderQueue = new ChartRenderQueue();

package/src/utils/chatPresetMerge.ts

@@ -0,0 +1,36 @@
+import type { ChatPreset } from '#uilib/components/ui/Chat/Chat.types';
+import {
+  branchesFromPresetScriptGraph,
+  isPresetScriptGraph,
+} from '#uilib/components/ui/Chat/ChatMessage/presetScript';
+
+const PRESET_FREEFORM_DEFAULTS_BY_ID: Record<string, Record<string, string>> = {
+  '4': {
+    initial: 'q_company',
+    p_rev: 'complete',
+    p_mar: 'complete',
+    p_risk: 'complete',
+  },
+  '5': { initial: 'q_goal' },
+};
+
+export function mergePresetFreeformDefaults(
+  presets: ChatPreset[],
+): ChatPreset[] {
+  return presets.map(p => {
+    const fromId = PRESET_FREEFORM_DEFAULTS_BY_ID[p.id];
+    let merged = { ...(fromId ?? {}), ...(p.freeformNext ?? {}) };
+
+    if (Object.keys(merged).length === 0) {
+      const script = p.script;
+      if (isPresetScriptGraph(script)) {
+        const branchKeys = Object.keys(branchesFromPresetScriptGraph(script));
+        if (branchKeys.length === 1) {
+          merged = { initial: branchKeys[0] };
+        }
+      }
+    }
+
+    return Object.keys(merged).length > 0 ? { ...p, freeformNext: merged } : p;
+  });
+}

package/src/utils/datasetApplicationLink.ts

@@ -0,0 +1,25 @@
+import { DATASET_QUERY_PARAM } from '#uilib/constants/dataset';
+
+/** Bracket token from agent chat: `[datasetId:1234]` or `[datasetId:1;analysisId:2]` */
+export const DATASET_APP_TOKEN_REGEX =
+  /^\[datasetId:(\d+)(?:;analysisId:(\d+))?\]$/;
+
+export function parseDatasetAppToken(
+  token: string,
+): { datasetId: number; analysisId?: number } | null {
+  const m = token.match(DATASET_APP_TOKEN_REGEX);
+  if (!m) return null;
+  const datasetId = Number(m[1]);
+  const analysisId = m[2] != null ? Number(m[2]) : undefined;
+  return analysisId != null ? { datasetId, analysisId } : { datasetId };
+}
+
+export function buildDatasetApplicationPath(
+  datasetId: number,
+  analysisId?: number,
+): string {
+  const params = new URLSearchParams();
+  params.set(DATASET_QUERY_PARAM, String(datasetId));
+  if (analysisId != null) params.set('analysisId', String(analysisId));
+  return `/datasets?${params.toString()}`;
+}

package/src/utils/quantileFormat.ts

@@ -0,0 +1,46 @@
+const calculateQuantilePercentage = (quantile: string): string =>
+  (parseFloat(quantile) * 100).toFixed(0);
+
+export const findClosestQuantile = (
+  targetQuantile: string,
+  availableQuantiles: string[],
+): string => {
+  const target = parseFloat(targetQuantile);
+  let closest = availableQuantiles[0];
+  let minDiff = Math.abs(parseFloat(closest) - target);
+
+  for (const quantile of availableQuantiles) {
+    const diff = Math.abs(parseFloat(quantile) - target);
+    if (diff < minDiff) {
+      minDiff = diff;
+      closest = quantile;
+    }
+  }
+
+  return closest;
+};
+
+export const normalizeQuantileKey = (
+  quantile: string,
+  availableKeys: string[],
+): string => {
+  if (availableKeys.includes(quantile)) {
+    return quantile;
+  }
+  const normalized = parseFloat(quantile).toFixed(2);
+  if (availableKeys.includes(normalized)) {
+    return normalized;
+  }
+  return findClosestQuantile(quantile, availableKeys);
+};
+
+export const formatQuantileRangeLabel = (
+  lowerQuantile: string,
+  upperQuantile: string,
+  includeRangeSuffix: boolean = true,
+): string => {
+  const lower = calculateQuantilePercentage(lowerQuantile);
+  const upper = calculateQuantilePercentage(upperQuantile);
+  const suffix = includeRangeSuffix ? ' Range' : '';
+  return `${lower}% - ${upper}%${suffix}`;
+};