@sybilion/uilib 1.3.0 → 1.3.1

package/src/components/ui/Chart/lightweight/chartTime.ts

@@ -0,0 +1,18 @@
+import type { UTCTimestamp } from 'lightweight-charts';
+
+/**
+ * Parse `YYYY-MM-DD` dates as UTC midnight → Lightweight Charts unix seconds.
+ */
+export function chartDateToUtcTimestamp(dateStr: string): UTCTimestamp {
+  const trimmed = dateStr.slice(0, 10);
+  const [y, m, d] = trimmed.split('-').map(Number);
+  if (
+    !Number.isFinite(y) ||
+    !Number.isFinite(m) ||
+    !Number.isFinite(d) ||
+    trimmed.length !== 10
+  ) {
+    return Math.floor(new Date(dateStr).getTime() / 1000) as UTCTimestamp;
+  }
+  return Math.floor(Date.UTC(y, m - 1, d, 0, 0, 0, 0) / 1000) as UTCTimestamp;
+}

package/src/components/ui/Chart/lightweight/lightweightForecastChart.helpers.ts

@@ -0,0 +1,141 @@
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+import type {
+  ChartOptions,
+  DeepPartial,
+  LineData,
+  UTCTimestamp,
+} from 'lightweight-charts';
+import { ColorType } from 'lightweight-charts';
+
+import { applyQuantileBandConeToChartData } from '../quantileBandConeChartData';
+import { chartDateToUtcTimestamp } from './chartTime';
+import type { QuantileBandCustomData } from './quantileBandCustomSeries';
+
+export function buildLightweightChartOptions(args: {
+  isDarkTheme: boolean;
+  width: number;
+  height: number;
+  autoSize?: boolean;
+}): DeepPartial<ChartOptions> {
+  const { isDarkTheme, width, height, autoSize = false } = args;
+  return {
+    autoSize,
+    width: Math.max(1, Math.floor(width)),
+    height: Math.max(1, Math.floor(height)),
+    layout: {
+      background: {
+        type: ColorType.Solid,
+        color: 'transparent',
+      },
+      textColor: isDarkTheme ? '#d8dee9' : '#191919',
+    },
+    grid: {
+      vertLines: {
+        color: isDarkTheme ? '#2f3440' : '#e6edf3',
+      },
+      horzLines: {
+        color: isDarkTheme ? '#2f3440' : '#e6edf3',
+      },
+    },
+    rightPriceScale: {
+      borderVisible: false,
+      scaleMargins: {
+        top: 0.08,
+        bottom: 0.08,
+      },
+    },
+    timeScale: {
+      borderVisible: false,
+      timeVisible: true,
+      secondsVisible: false,
+      fixLeftEdge: true,
+      fixRightEdge: true,
+    },
+    localization: {
+      locale:
+        typeof navigator !== 'undefined' && navigator.language
+          ? navigator.language
+          : 'en-US',
+    },
+  };
+}
+
+export function buildHistoricalLineData(
+  rows: ChartDataPoint[],
+): LineData<UTCTimestamp>[] {
+  const out: LineData<UTCTimestamp>[] = [];
+  for (const row of rows) {
+    const v = row.historical;
+    if (typeof v !== 'number' || !Number.isFinite(v)) continue;
+    out.push({
+      time: chartDateToUtcTimestamp(row.date),
+      value: v,
+    });
+  }
+  out.sort((a, b) => Number(a.time) - Number(b.time));
+  return out;
+}
+
+export function buildForecastLineData(
+  rows: ChartDataPoint[],
+  forecastKey: string,
+): LineData<UTCTimestamp>[] {
+  const out: LineData<UTCTimestamp>[] = [];
+  for (const row of rows) {
+    const v = row[forecastKey];
+    if (typeof v !== 'number' || !Number.isFinite(v)) continue;
+    out.push({
+      time: chartDateToUtcTimestamp(row.date),
+      value: v,
+    });
+  }
+  out.sort((a, b) => Number(a.time) - Number(b.time));
+  return out;
+}
+
+export function buildQuantileBandCustomData(
+  rows: ChartDataPoint[],
+  bandKey: string,
+): QuantileBandCustomData[] {
+  const coned = applyQuantileBandConeToChartData(rows, bandKey);
+  const out: QuantileBandCustomData[] = [];
+  for (const row of coned) {
+    const v = row[bandKey];
+    if (
+      !Array.isArray(v) ||
+      v.length !== 2 ||
+      typeof v[0] !== 'number' ||
+      typeof v[1] !== 'number' ||
+      !Number.isFinite(v[0]) ||
+      !Number.isFinite(v[1])
+    ) {
+      continue;
+    }
+    out.push({
+      time: chartDateToUtcTimestamp(row.date),
+      lower: v[0],
+      upper: v[1],
+    });
+  }
+  out.sort((a, b) => Number(a.time) - Number(b.time));
+  return out;
+}
+
+export function findNearestChartRow(
+  rows: ChartDataPoint[],
+  time: UTCTimestamp,
+): ChartDataPoint | null {
+  if (!rows.length) return null;
+  const target = Number(time) * 1000;
+  let best: ChartDataPoint | null = null;
+  let bestDist = Infinity;
+  for (const row of rows) {
+    const t = Number(chartDateToUtcTimestamp(row.date)) * 1000;
+    const dist = Math.abs(t - target);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = row;
+    }
+  }
+  return best;
+}

package/src/components/ui/Chart/lightweight/quantileBandCustomSeries.ts

@@ -0,0 +1,215 @@
+import type { CanvasRenderingTarget2D } from 'fancy-canvas';
+import type {
+  CustomData,
+  CustomSeriesOptions,
+  CustomSeriesWhitespaceData,
+  ICustomSeriesPaneRenderer,
+  ICustomSeriesPaneView,
+  PaneRendererCustomData,
+  PriceToCoordinateConverter,
+  UTCTimestamp,
+} from 'lightweight-charts';
+import { customSeriesDefaultOptions } from 'lightweight-charts';
+
+export interface QuantileBandCustomData extends CustomData<UTCTimestamp> {
+  lower: number;
+  upper: number;
+}
+
+export type QuantileBandStyle = {
+  fill: string;
+  stroke?: string;
+  strokeWidth: number;
+  strokeDasharray?: string;
+  strokeOpacity?: number;
+};
+
+type MediaXY = { x: number; y: number };
+
+/** Catmull–Rom segment chain → cubic Béziers (matches curved line feel). */
+function appendCatmullRomBezierChain(
+  ctx: CanvasRenderingContext2D,
+  pts: MediaXY[],
+  startWithMoveTo: boolean,
+): void {
+  if (pts.length < 2) return;
+
+  if (pts.length === 2) {
+    if (startWithMoveTo) ctx.moveTo(pts[0].x, pts[0].y);
+    ctx.lineTo(pts[1].x, pts[1].y);
+    return;
+  }
+
+  if (startWithMoveTo) {
+    ctx.moveTo(pts[0].x, pts[0].y);
+  }
+
+  for (let i = 0; i < pts.length - 1; i += 1) {
+    const p0 = pts[Math.max(0, i - 1)];
+    const p1 = pts[i];
+    const p2 = pts[i + 1];
+    const p3 = pts[Math.min(pts.length - 1, i + 2)];
+    const cp1x = p1.x + (p2.x - p0.x) / 6;
+    const cp1y = p1.y + (p2.y - p0.y) / 6;
+    const cp2x = p2.x - (p3.x - p1.x) / 6;
+    const cp2y = p2.y - (p3.y - p1.y) / 6;
+    ctx.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, p2.x, p2.y);
+  }
+}
+
+class QuantileBandPaneRenderer implements ICustomSeriesPaneRenderer {
+  public constructor(
+    private readonly getData: () =>
+      | PaneRendererCustomData<UTCTimestamp, QuantileBandCustomData>
+      | undefined,
+    private readonly getStyle: () => QuantileBandStyle,
+    private readonly isWhitespaceFn: (
+      data: QuantileBandCustomData | CustomSeriesWhitespaceData<UTCTimestamp>,
+    ) => data is CustomSeriesWhitespaceData<UTCTimestamp>,
+  ) {}
+
+  public draw(
+    target: CanvasRenderingTarget2D,
+    priceConverter: PriceToCoordinateConverter,
+  ): void {
+    const pane = this.getData() as
+      | PaneRendererCustomData<UTCTimestamp, QuantileBandCustomData>
+      | undefined;
+    if (!pane?.bars?.length) {
+      return;
+    }
+
+    const style = this.getStyle();
+    const segments: Array<{ x: number; yU: number; yL: number }> = [];
+
+    for (const bar of pane.bars) {
+      const d = bar.originalData;
+      if (this.isWhitespaceFn(d)) {
+        continue;
+      }
+      const p = d as QuantileBandCustomData;
+      const yU = priceConverter(p.upper);
+      const yL = priceConverter(p.lower);
+      if (yU === null || yL === null) {
+        continue;
+      }
+      segments.push({ x: bar.x, yU, yL });
+    }
+
+    if (segments.length < 2) {
+      return;
+    }
+
+    target.useMediaCoordinateSpace(({ context }) => {
+      const opacity =
+        typeof style.strokeOpacity === 'number'
+          ? style.strokeOpacity
+          : undefined;
+      const prevAlpha = context.globalAlpha;
+      const upper: MediaXY[] = segments.map(s => ({ x: s.x, y: s.yU }));
+      const lowerRev: MediaXY[] = segments
+        .map(s => ({ x: s.x, y: s.yL }))
+        .reverse();
+
+      context.beginPath();
+      appendCatmullRomBezierChain(context, upper, true);
+      const last = segments[segments.length - 1]!;
+      context.lineTo(last.x, last.yL);
+      appendCatmullRomBezierChain(context, lowerRev, false);
+      context.closePath();
+      context.fillStyle = style.fill;
+      context.fill();
+
+      const sw = style.strokeWidth;
+      if (sw > 0) {
+        if (opacity !== undefined) context.globalAlpha = opacity;
+        context.lineWidth = sw;
+        context.strokeStyle = style.stroke ?? style.fill;
+        if (style.strokeDasharray) {
+          const parts = style.strokeDasharray
+            .split(/[\s,]+/)
+            .map(Number)
+            .filter(n => Number.isFinite(n));
+          if (parts.length) context.setLineDash(parts);
+          else context.setLineDash([]);
+        } else {
+          context.setLineDash([]);
+        }
+        context.stroke();
+        context.setLineDash([]);
+      }
+      context.globalAlpha = prevAlpha;
+    });
+  }
+}
+
+export class QuantileBandPaneView implements ICustomSeriesPaneView<
+  UTCTimestamp,
+  QuantileBandCustomData,
+  CustomSeriesOptions
+> {
+  private _paneData:
+    | PaneRendererCustomData<UTCTimestamp, QuantileBandCustomData>
+    | undefined;
+
+  private _style!: QuantileBandStyle;
+
+  public constructor(initialStyle: QuantileBandStyle) {
+    this._style = initialStyle;
+  }
+
+  public updateStyle(style: QuantileBandStyle): void {
+    this._style = style;
+  }
+
+  public renderer(): ICustomSeriesPaneRenderer {
+    return new QuantileBandPaneRenderer(
+      () => this._paneData,
+      () => this._style,
+      (d): d is CustomSeriesWhitespaceData<UTCTimestamp> =>
+        this.isWhitespace(d),
+    );
+  }
+
+  public update(
+    paneData: PaneRendererCustomData<UTCTimestamp, QuantileBandCustomData>,
+    seriesOptions: CustomSeriesOptions,
+  ): void {
+    this._paneData = paneData;
+    const c = seriesOptions.color;
+    if (typeof c === 'string') {
+      this._style = { ...this._style, fill: c };
+    }
+  }
+
+  public priceValueBuilder(plotRow: QuantileBandCustomData): number[] {
+    if (this.isWhitespace(plotRow)) {
+      return [];
+    }
+    const p = plotRow as QuantileBandCustomData;
+    return [p.lower, p.upper, (p.lower + p.upper) / 2];
+  }
+
+  public isWhitespace(
+    data: QuantileBandCustomData | CustomSeriesWhitespaceData<UTCTimestamp>,
+  ): data is CustomSeriesWhitespaceData<UTCTimestamp> {
+    const row = data as QuantileBandCustomData;
+    if (
+      typeof row.lower !== 'number' ||
+      typeof row.upper !== 'number' ||
+      !Number.isFinite(row.lower) ||
+      !Number.isFinite(row.upper)
+    ) {
+      return true;
+    }
+    return false;
+  }
+
+  public defaultOptions(): CustomSeriesOptions {
+    return customSeriesDefaultOptions;
+  }
+
+  public destroy(): void {
+    this._paneData = undefined;
+  }
+}

package/src/components/ui/Chart/quantileBandConeChartData.ts

@@ -0,0 +1,171 @@
+import type { ChartDataPoint } from '#uilib/components/ui/ChartAreaInteractive/ChartAreaInteractive.types';
+
+function isFiniteBandTuple(v: unknown): v is [number, number] {
+  return (
+    Array.isArray(v) &&
+    v.length === 2 &&
+    typeof v[0] === 'number' &&
+    typeof v[1] === 'number' &&
+    Number.isFinite(v[0]) &&
+    Number.isFinite(v[1])
+  );
+}
+
+/**
+ * Matches ChartAreaInteractive `mode="intervals"`: cone / fan chart hand-off — collapse the
+ * interval to a point at the historical→forecast boundary, then expand along forecast anchors.
+ * (Same rules as `useQuantileBands`, without requiring `ForecastData` — reads tuples from each row.)
+ */
+export function applyQuantileBandConeToChartData(
+  chartData: ChartDataPoint[],
+  bandKey: string,
+): ChartDataPoint[] {
+  if (!chartData.length) return chartData;
+
+  const originalBandByDate = new Map<string, [number, number]>();
+  for (const p of chartData) {
+    const t = p[bandKey];
+    if (isFiniteBandTuple(t)) originalBandByDate.set(p.date, [t[0], t[1]]);
+  }
+
+  const forecastDateList = [...originalBandByDate.keys()].sort(
+    (a, b) => new Date(a).getTime() - new Date(b).getTime(),
+  );
+  if (forecastDateList.length === 0) return chartData;
+
+  const forecastDatesSet = new Set(forecastDateList);
+  const dateToQuantileIndex = new Map<string, number>();
+  forecastDateList.forEach((d, i) => dateToQuantileIndex.set(d, i));
+
+  const clonedData = [...chartData];
+
+  const historicalPoints = clonedData.filter(
+    p =>
+      p.historical !== undefined &&
+      p.historical !== null &&
+      typeof p.historical === 'number' &&
+      Number.isFinite(p.historical),
+  );
+  const lastHistoricalPoint =
+    historicalPoints.length > 0
+      ? historicalPoints[historicalPoints.length - 1]
+      : null;
+  const lastHistoricalDate = lastHistoricalPoint?.date;
+  const lastHistoricalValue = lastHistoricalPoint?.historical as
+    | number
+    | undefined;
+
+  const firstForecastDate = forecastDateList[0];
+  const firstForecastDateObj = firstForecastDate
+    ? new Date(firstForecastDate)
+    : null;
+  const lastHistoricalDateObj = lastHistoricalDate
+    ? new Date(lastHistoricalDate)
+    : null;
+
+  const hasGap =
+    !!lastHistoricalDate &&
+    !!firstForecastDate &&
+    lastHistoricalValue !== undefined &&
+    firstForecastDateObj &&
+    lastHistoricalDateObj &&
+    firstForecastDateObj.getTime() > lastHistoricalDateObj.getTime();
+
+  const needsBridgePoint =
+    !!lastHistoricalDate &&
+    !!firstForecastDate &&
+    lastHistoricalValue !== undefined &&
+    firstForecastDateObj &&
+    lastHistoricalDateObj &&
+    firstForecastDateObj.getTime() <= lastHistoricalDateObj.getTime();
+
+  let bridgePoint: (typeof historicalPoints)[number] | null = null;
+  let pointBeforeForecast: (typeof historicalPoints)[number] | null = null;
+  if (needsBridgePoint && historicalPoints.length > 0) {
+    bridgePoint =
+      firstForecastDateObj &&
+      lastHistoricalDateObj &&
+      firstForecastDateObj.getTime() === lastHistoricalDateObj.getTime()
+        ? lastHistoricalPoint
+        : [...historicalPoints]
+            .reverse()
+            .find(
+              p =>
+                firstForecastDateObj &&
+                new Date(p.date).getTime() < firstForecastDateObj.getTime(),
+            ) || lastHistoricalPoint;
+
+    if (firstForecastDateObj) {
+      pointBeforeForecast =
+        historicalPoints.findLast(
+          p => new Date(p.date).getTime() < firstForecastDateObj.getTime(),
+        ) ?? null;
+    }
+  }
+
+  return clonedData.map(point => {
+    const newPoint: ChartDataPoint = { ...point };
+
+    if (
+      hasGap &&
+      point.date === lastHistoricalDate &&
+      lastHistoricalValue !== undefined
+    ) {
+      newPoint[bandKey] = [lastHistoricalValue, lastHistoricalValue] as [
+        number,
+        number,
+      ];
+    }
+
+    const isBridgePointDate =
+      needsBridgePoint &&
+      bridgePoint &&
+      bridgePoint.historical !== undefined &&
+      point.date === bridgePoint.date;
+    const isPointBeforeForecast =
+      needsBridgePoint &&
+      pointBeforeForecast &&
+      pointBeforeForecast.historical !== undefined &&
+      point.date === pointBeforeForecast.date;
+    const isAlsoForecastDate = forecastDatesSet.has(point.date);
+
+    if (isPointBeforeForecast && !isAlsoForecastDate) {
+      newPoint[bandKey] = [
+        pointBeforeForecast.historical as number,
+        pointBeforeForecast.historical as number,
+      ];
+    } else if (isBridgePointDate && !isAlsoForecastDate) {
+      newPoint[bandKey] = [
+        bridgePoint.historical as number,
+        bridgePoint.historical as number,
+      ];
+    }
+
+    if (forecastDatesSet.has(point.date)) {
+      const quantileIndex = dateToQuantileIndex.get(point.date);
+      if (quantileIndex !== undefined) {
+        const bandValues = originalBandByDate.get(point.date);
+        if (bandValues) {
+          const isBridgePointDateForecast =
+            needsBridgePoint &&
+            bridgePoint &&
+            point.date === bridgePoint.date &&
+            bridgePoint.historical !== undefined;
+
+          if (isBridgePointDateForecast && quantileIndex === 0) {
+            newPoint[bandKey] = [
+              bridgePoint.historical as number,
+              bandValues[1],
+            ];
+          } else {
+            newPoint[bandKey] = bandValues;
+          }
+        } else {
+          delete newPoint[bandKey];
+        }
+      }
+    }
+
+    return newPoint;
+  });
+}