okengine 0.11.2 → 0.13.0

package/src/console/ui-next/src/components/charts/projection-utils.ts

@@ -0,0 +1,378 @@
+export type ProjectionMode = "auto" | "target" | "manual";
+export type ProjectionAutoMethod = "linearRegression" | "lastSegment";
+/** How the projection segment is drawn between anchor and horizon. */
+export type ProjectionCurveKind = "linear" | "bezier";
+/** @deprecated Stepped density removed — projections always anchor → horizon. */
+export type ProjectionPathDensity = "stepped" | "endpoints";
+
+export interface ProjectionPoint {
+  date: Date;
+  value: number;
+}
+
+export interface BuildProjectionPathOptions {
+  sourceData: Record<string, unknown>[];
+  seriesKey: string;
+  xDataKey?: string;
+  mode: ProjectionMode;
+  autoMethod?: ProjectionAutoMethod;
+  /** Auto mode: stepped points per interval, or anchor + end only. Default: stepped */
+  pathDensity?: ProjectionPathDensity;
+  /** Index in sourceData where projection anchors (default: last point). */
+  startIndex?: number;
+  /** How many future points to generate (matches source cadence). */
+  horizonPoints?: number;
+  /** Target Y at the final projected date (target mode). */
+  endValue?: number;
+  /** Full manual path — anchor + future points (manual mode). */
+  points?: ProjectionPoint[];
+}
+
+function readDate(row: Record<string, unknown>, xDataKey: string): Date | null {
+  const raw = row[xDataKey];
+  if (raw instanceof Date && !Number.isNaN(raw.getTime())) {
+    return raw;
+  }
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    const date = new Date(raw);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  if (typeof raw === "string") {
+    const date = new Date(raw);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+  return null;
+}
+
+function readValue(row: Record<string, unknown>, seriesKey: string): number | null {
+  const raw = row[seriesKey];
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+}
+
+function resolveStartIndex(
+  sourceData: Record<string, unknown>[],
+  startIndex: number | undefined,
+): number {
+  if (startIndex == null || !Number.isFinite(startIndex)) {
+    return Math.max(0, sourceData.length - 1);
+  }
+  return Math.min(Math.max(0, Math.floor(startIndex)), sourceData.length - 1);
+}
+
+function intervalFromAdjacentRows(
+  sourceData: Record<string, unknown>[],
+  xDataKey: string,
+  startIndex: number,
+): number | null {
+  if (startIndex < 1) {
+    return null;
+  }
+  const prevRow = sourceData[startIndex - 1];
+  const currentRow = sourceData[startIndex];
+  const prev = prevRow ? readDate(prevRow, xDataKey) : null;
+  const current = currentRow ? readDate(currentRow, xDataKey) : null;
+  if (!(prev && current)) {
+    return null;
+  }
+  const delta = current.getTime() - prev.getTime();
+  return delta > 0 ? delta : null;
+}
+
+function intervalFromSeriesSpan(
+  sourceData: Record<string, unknown>[],
+  xDataKey: string,
+): number | null {
+  if (sourceData.length < 2) {
+    return null;
+  }
+  const firstRow = sourceData[0];
+  const lastRow = sourceData.at(-1);
+  const first = firstRow ? readDate(firstRow, xDataKey) : null;
+  const last = lastRow ? readDate(lastRow, xDataKey) : null;
+  if (!(first && last)) {
+    return null;
+  }
+  const span = last.getTime() - first.getTime();
+  return span > 0 ? span / (sourceData.length - 1) : null;
+}
+
+function resolveIntervalMs(
+  sourceData: Record<string, unknown>[],
+  xDataKey: string,
+  startIndex: number,
+): number {
+  return (
+    intervalFromAdjacentRows(sourceData, xDataKey, startIndex) ??
+    intervalFromSeriesSpan(sourceData, xDataKey) ??
+    86_400_000
+  );
+}
+
+function linearRegressionSlope(points: { t: number; y: number }[]): number {
+  if (points.length < 2) {
+    return 0;
+  }
+  const n = points.length;
+  let sumT = 0;
+  let sumY = 0;
+  let sumTY = 0;
+  let sumTT = 0;
+  for (const { t, y } of points) {
+    sumT += t;
+    sumY += y;
+    sumTY += t * y;
+    sumTT += t * t;
+  }
+  const denom = n * sumTT - sumT * sumT;
+  if (Math.abs(denom) < 1e-12) {
+    return 0;
+  }
+  return (n * sumTY - sumT * sumY) / denom;
+}
+
+function buildAutoFutureValues(options: {
+  anchorTime: number;
+  anchorValue: number;
+  autoMethod: ProjectionAutoMethod;
+  historyPoints: { t: number; y: number }[];
+  horizonPoints: number;
+  intervalMs: number;
+  pathDensity: ProjectionPathDensity;
+}): ProjectionPoint[] {
+  const {
+    anchorTime,
+    anchorValue,
+    autoMethod,
+    historyPoints,
+    horizonPoints,
+    intervalMs,
+    pathDensity,
+  } = options;
+
+  const slope =
+    autoMethod === "lastSegment" && historyPoints.length >= 2
+      ? (() => {
+          const prev = historyPoints.at(-2);
+          const last = historyPoints.at(-1);
+          if (!(prev && last)) {
+            return 0;
+          }
+          const dt = last.t - prev.t;
+          return dt === 0 ? 0 : (last.y - prev.y) / dt;
+        })()
+      : linearRegressionSlope(historyPoints);
+
+  if (pathDensity === "endpoints") {
+    const endTime = anchorTime + intervalMs * horizonPoints;
+    const endValue = anchorValue + slope * intervalMs * horizonPoints;
+    return [
+      { date: new Date(anchorTime), value: anchorValue },
+      { date: new Date(endTime), value: endValue },
+    ];
+  }
+
+  const result: ProjectionPoint[] = [{ date: new Date(anchorTime), value: anchorValue }];
+
+  for (let i = 1; i <= horizonPoints; i++) {
+    const t = anchorTime + intervalMs * i;
+    const value = anchorValue + slope * intervalMs * i;
+    result.push({ date: new Date(t), value });
+  }
+
+  return result;
+}
+
+/** Slope (value change per ms) at the projection anchor from the last data segment. */
+export function computeProjectionAnchorTangentSlope(
+  sourceData: Record<string, unknown>[],
+  seriesKey: string,
+  xDataKey = "date",
+  startIndexProp?: number,
+): number {
+  if (sourceData.length < 2) {
+    return 0;
+  }
+  const startIndex = resolveStartIndex(sourceData, startIndexProp);
+  const historyPoints: { t: number; y: number }[] = [];
+  for (let i = 0; i <= startIndex; i++) {
+    const row = sourceData[i];
+    if (!row) {
+      continue;
+    }
+    const date = readDate(row, xDataKey);
+    const value = readValue(row, seriesKey);
+    if (date && value != null) {
+      historyPoints.push({ t: date.getTime(), y: value });
+    }
+  }
+  if (historyPoints.length < 2) {
+    return 0;
+  }
+  const prev = historyPoints.at(-2);
+  const last = historyPoints.at(-1);
+  if (!(prev && last)) {
+    return 0;
+  }
+  const dt = last.t - prev.t;
+  return dt === 0 ? 0 : (last.y - prev.y) / dt;
+}
+
+/** Cubic bezier with horizontal tangents at start and end (price-target S-curve). */
+export function buildHorizontalTangentBezierPath(
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+  /** How far control points sit along the x span (0–0.5). Default: 0.45 */
+  tension = 0.45,
+): string {
+  const dx = x1 - x0;
+  if (Math.abs(dx) < 1e-6) {
+    return `M ${x0},${y0} L ${x1},${y1}`;
+  }
+  const t = Math.min(0.5, Math.max(0.05, tension));
+  const c1x = x0 + dx * t;
+  const c2x = x1 - dx * t;
+  return `M ${x0},${y0} C ${c1x},${y0} ${c2x},${y1} ${x1},${y1}`;
+}
+
+function buildTargetPath(options: {
+  anchorTime: number;
+  anchorValue: number;
+  endValue: number;
+  horizonPoints: number;
+  intervalMs: number;
+}): ProjectionPoint[] {
+  const { anchorTime, anchorValue, endValue, horizonPoints, intervalMs } = options;
+  const endTime = anchorTime + intervalMs * horizonPoints;
+  return [
+    { date: new Date(anchorTime), value: anchorValue },
+    { date: new Date(endTime), value: endValue },
+  ];
+}
+
+/** Build a projection path from historical chart data or explicit points. */
+export function buildProjectionPath(options: BuildProjectionPathOptions): ProjectionPoint[] {
+  const {
+    sourceData,
+    seriesKey,
+    xDataKey = "date",
+    mode,
+    autoMethod = "linearRegression",
+    pathDensity = "endpoints",
+    startIndex: startIndexProp,
+    horizonPoints = 6,
+    endValue,
+    points,
+  } = options;
+
+  if (mode === "manual" && points && points.length >= 2) {
+    return points.map((point) => ({
+      date: new Date(point.date),
+      value: point.value,
+    }));
+  }
+
+  if (sourceData.length === 0) {
+    return [];
+  }
+
+  const startIndex = resolveStartIndex(sourceData, startIndexProp);
+  const anchorRow = sourceData[startIndex];
+  if (!anchorRow) {
+    return [];
+  }
+
+  const anchorDate = readDate(anchorRow, xDataKey);
+  const anchorValue = readValue(anchorRow, seriesKey);
+  if (!anchorDate || anchorValue == null) {
+    return [];
+  }
+
+  const intervalMs = resolveIntervalMs(sourceData, xDataKey, startIndex);
+  const anchorTime = anchorDate.getTime();
+
+  const historyPoints: { t: number; y: number }[] = [];
+  for (let i = 0; i <= startIndex; i++) {
+    const row = sourceData[i];
+    if (!row) {
+      continue;
+    }
+    const date = readDate(row, xDataKey);
+    const value = readValue(row, seriesKey);
+    if (date && value != null) {
+      historyPoints.push({ t: date.getTime(), y: value });
+    }
+  }
+
+  if (mode === "target" && endValue != null && Number.isFinite(endValue)) {
+    return buildTargetPath({
+      anchorTime,
+      anchorValue,
+      endValue,
+      horizonPoints,
+      intervalMs,
+    });
+  }
+
+  return buildAutoFutureValues({
+    anchorTime,
+    anchorValue,
+    autoMethod,
+    historyPoints,
+    horizonPoints,
+    intervalMs,
+    pathDensity,
+  });
+}
+
+/** Collect numeric Y extents from projection point arrays. */
+export function projectionValueExtents(
+  paths: ProjectionPoint[][],
+): { minValue: number; maxValue: number } | null {
+  let minValue = Number.POSITIVE_INFINITY;
+  let maxValue = Number.NEGATIVE_INFINITY;
+
+  for (const path of paths) {
+    for (const point of path) {
+      if (point.value < minValue) {
+        minValue = point.value;
+      }
+      if (point.value > maxValue) {
+        maxValue = point.value;
+      }
+    }
+  }
+
+  if (minValue === Number.POSITIVE_INFINITY) {
+    return null;
+  }
+
+  return { minValue, maxValue };
+}
+
+/** Collect date extents from projection point arrays. */
+export function projectionDateExtents(
+  paths: ProjectionPoint[][],
+): { minTime: number; maxTime: number } | null {
+  let minTime = Number.POSITIVE_INFINITY;
+  let maxTime = Number.NEGATIVE_INFINITY;
+
+  for (const path of paths) {
+    for (const point of path) {
+      const time = point.date.getTime();
+      if (time < minTime) {
+        minTime = time;
+      }
+      if (time > maxTime) {
+        maxTime = time;
+      }
+    }
+  }
+
+  if (minTime === Number.POSITIVE_INFINITY) {
+    return null;
+  }
+
+  return { minTime, maxTime };
+}

package/src/console/ui-next/src/components/charts/reference-area-config.ts

@@ -0,0 +1,59 @@
+import { Children, isValidElement, type ReactElement, type ReactNode } from "react";
+import { normalizeYAxisId } from "./y-axis-scales";
+
+export interface ReferenceAreaConfig {
+  yAxisId: string;
+  y1?: number;
+  y2?: number;
+  axisLabelColor?: string;
+}
+
+interface ReferenceAreaConfigProps {
+  yAxisId?: string | number;
+  y1?: number;
+  y2?: number;
+  axisLabelColor?: string;
+}
+
+function getChildComponentName(child: ReactElement) {
+  const childType = child.type as { displayName?: string; name?: string };
+  return typeof child.type === "function" ? childType.displayName || childType.name || "" : "";
+}
+
+function isReferenceAreaElement(child: ReactElement): boolean {
+  return getChildComponentName(child) === "ReferenceArea";
+}
+
+/** Collect {@link ReferenceArea} props from chart children for axis label styling. */
+export function extractReferenceAreaConfigs(children: ReactNode): ReferenceAreaConfig[] {
+  const configs: ReferenceAreaConfig[] = [];
+
+  const visit = (node: ReactNode) => {
+    Children.forEach(node, (child) => {
+      if (!isValidElement(child)) {
+        return;
+      }
+
+      if (isReferenceAreaElement(child)) {
+        const props = child.props as ReferenceAreaConfigProps | undefined;
+        if (props) {
+          configs.push({
+            yAxisId: normalizeYAxisId(props.yAxisId),
+            y1: props.y1,
+            y2: props.y2,
+            axisLabelColor: props.axisLabelColor,
+          });
+        }
+        return;
+      }
+
+      const childProps = child.props as { children?: ReactNode } | undefined;
+      if (childProps?.children) {
+        visit(childProps.children);
+      }
+    });
+  };
+
+  visit(children);
+  return configs;
+}

package/src/console/ui-next/src/components/charts/reference-area-geometry.ts

@@ -0,0 +1,136 @@
+export type ReferenceAreaIfOverflow = "hidden" | "visible" | "discard";
+
+export interface ReferenceAreaRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ComputeReferenceAreaRectOptions {
+  innerWidth: number;
+  innerHeight: number;
+  x1?: Date | number;
+  x2?: Date | number;
+  y1?: number;
+  y2?: number;
+  ifOverflow?: ReferenceAreaIfOverflow;
+  xScale: (value: Date) => number;
+  yScale: (value: number) => number;
+}
+
+function toDate(value: Date | number): Date {
+  return value instanceof Date ? value : new Date(value);
+}
+
+function resolveXPixel(
+  xScale: (value: Date) => number,
+  value: Date | number | undefined,
+  fallback: number,
+): number {
+  if (value == null) {
+    return fallback;
+  }
+  return xScale(toDate(value));
+}
+
+function resolveYPixel(
+  yScale: (value: number) => number,
+  value: number | undefined,
+  fallback: number,
+): number {
+  if (value == null) {
+    return fallback;
+  }
+  return yScale(value);
+}
+
+function clampRectToPlot(
+  rect: ReferenceAreaRect,
+  innerWidth: number,
+  innerHeight: number,
+): ReferenceAreaRect | null {
+  const x1 = Math.max(0, rect.x);
+  const y1 = Math.max(0, rect.y);
+  const x2 = Math.min(innerWidth, rect.x + rect.width);
+  const y2 = Math.min(innerHeight, rect.y + rect.height);
+  const width = x2 - x1;
+  const height = y2 - y1;
+  if (width <= 0 || height <= 0) {
+    return null;
+  }
+  return { x: x1, y: y1, width, height };
+}
+
+function isFullyInsidePlot(
+  rect: ReferenceAreaRect,
+  innerWidth: number,
+  innerHeight: number,
+): boolean {
+  return (
+    rect.x >= 0 &&
+    rect.y >= 0 &&
+    rect.x + rect.width <= innerWidth &&
+    rect.y + rect.height <= innerHeight
+  );
+}
+
+/** Map data bounds to plot pixels for a reference rectangle. */
+export function computeReferenceAreaRect(
+  options: ComputeReferenceAreaRectOptions,
+): ReferenceAreaRect | null {
+  const {
+    innerWidth,
+    innerHeight,
+    x1,
+    x2,
+    y1,
+    y2,
+    ifOverflow = "hidden",
+    xScale,
+    yScale,
+  } = options;
+
+  if (innerWidth <= 0 || innerHeight <= 0) {
+    return null;
+  }
+
+  const left = resolveXPixel(xScale, x1, 0);
+  const right = resolveXPixel(xScale, x2, innerWidth);
+  const top = resolveYPixel(yScale, y1, 0);
+  const bottom = resolveYPixel(yScale, y2, innerHeight);
+
+  const x = Math.min(left, right);
+  const y = Math.min(top, bottom);
+  const width = Math.abs(right - left);
+  const height = Math.abs(bottom - top);
+
+  if (width <= 0 || height <= 0) {
+    return null;
+  }
+
+  const rect: ReferenceAreaRect = { x, y, width, height };
+
+  if (ifOverflow === "visible") {
+    return rect;
+  }
+
+  if (ifOverflow === "discard") {
+    return isFullyInsidePlot(rect, innerWidth, innerHeight) ? rect : null;
+  }
+
+  return clampRectToPlot(rect, innerWidth, innerHeight);
+}
+
+/** Inclusive data range for axis label highlighting. */
+export function resolveReferenceDataRange(
+  y1: number | undefined,
+  y2: number | undefined,
+  domain: [number, number],
+): [number, number] {
+  const dMin = Math.min(domain[0], domain[1]);
+  const dMax = Math.max(domain[0], domain[1]);
+  const low = y1 ?? dMin;
+  const high = y2 ?? dMax;
+  return [Math.min(low, high), Math.max(low, high)];
+}

package/src/console/ui-next/src/components/charts/reference-area-registration-context.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { ReferenceAreaConfig } from "./reference-area-config";
+
+export interface ReferenceAreaRegistrationContextValue {
+  registerReferenceArea: (id: string, config: ReferenceAreaConfig) => void;
+  unregisterReferenceArea: (id: string) => void;
+}
+
+export const ReferenceAreaRegistrationContext =
+  createContext<ReferenceAreaRegistrationContextValue | null>(null);
+
+export function useReferenceAreaRegistration(): ReferenceAreaRegistrationContextValue | null {
+  return useContext(ReferenceAreaRegistrationContext);
+}

package/src/console/ui-next/src/components/charts/series-bar-layout.ts

@@ -0,0 +1,60 @@
+export function computeSeriesBarWidth(input: {
+  innerWidth: number;
+  dataLength: number;
+  columnWidth: number;
+  seriesCount: number;
+  composedBarSize?: number;
+  composedMaxBarSize?: number;
+  composedBarGap?: number;
+  stacked?: boolean;
+}): number {
+  const {
+    innerWidth,
+    dataLength,
+    columnWidth,
+    seriesCount,
+    composedBarSize,
+    composedMaxBarSize,
+    composedBarGap = 4,
+    stacked = false,
+  } = input;
+
+  const gap = composedBarGap;
+  const groupCount = stacked ? 1 : Math.max(1, seriesCount);
+  let slot = columnWidth;
+  if (slot <= 0) {
+    slot = dataLength < 2 ? innerWidth : innerWidth / (dataLength - 1);
+  }
+
+  let width =
+    composedBarSize ?? Math.min(slot * 0.88, composedMaxBarSize ?? Number.POSITIVE_INFINITY);
+  if (composedMaxBarSize != null) {
+    width = Math.min(width, composedMaxBarSize);
+  }
+  if (groupCount > 1) {
+    const maxGroup = slot * 0.92;
+    const needed = groupCount * width + (groupCount - 1) * gap;
+    if (needed > maxGroup && maxGroup > 0) {
+      width = Math.max(4, (maxGroup - (groupCount - 1) * gap) / groupCount);
+    }
+  }
+
+  return Math.max(2, width);
+}
+
+/** Half-width of the bar group at each x — used to pad reveal clips. */
+export function computeSeriesBarRevealClipPadding(input: {
+  barWidth: number;
+  seriesCount: number;
+  gap?: number;
+  stacked?: boolean;
+}): number {
+  const { barWidth, seriesCount, gap = 4, stacked = false } = input;
+
+  if (stacked || seriesCount <= 1) {
+    return Math.ceil(barWidth / 2);
+  }
+
+  const groupWidth = seriesCount * barWidth + (seriesCount - 1) * gap;
+  return Math.ceil(groupWidth / 2);
+}