okengine 0.11.2 → 0.12.0

package/src/console/ui-next/src/components/charts/use-chart-phase-orchestrator.ts

@@ -0,0 +1,173 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { type ChartPhase, type ChartStatus, resolveRestingChartPhase } from "./chart-phase";
+
+export interface UseChartPhaseOrchestratorOptions {
+  chartStatus: ChartStatus;
+  targetData: Record<string, unknown>[];
+  skeletonData: Record<string, unknown>[];
+  animationDuration: number;
+  yDomainTweenDuration: number;
+  /** Signature of motion URL state — replays clip reveal in Studio. */
+  revealSignature?: string;
+  /** Skip mount/signature enter reveal (static docs previews). */
+  skipEnterReveal?: boolean;
+}
+
+export function useChartPhaseOrchestrator({
+  chartStatus,
+  targetData,
+  skeletonData,
+  animationDuration,
+  yDomainTweenDuration,
+  revealSignature = "",
+  skipEnterReveal = false,
+}: UseChartPhaseOrchestratorOptions) {
+  const [chartPhase, setChartPhase] = useState<ChartPhase>(() =>
+    resolveRestingChartPhase(chartStatus),
+  );
+  const [plotData, setPlotData] = useState<Record<string, unknown>[]>(() =>
+    chartStatus === "loading" ? skeletonData : targetData,
+  );
+  const [revealEpoch, setRevealEpoch] = useState(0);
+  const [concealEpoch, setConcealEpoch] = useState(0);
+  const [isLoaded, setIsLoaded] = useState(() => chartStatus === "ready");
+  const prevStatusRef = useRef(chartStatus);
+  const phaseRef = useRef(chartPhase);
+  phaseRef.current = chartPhase;
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: status transition branches for animation durations
+  useEffect(() => {
+    const prevStatus = prevStatusRef.current;
+    if (prevStatus === chartStatus) {
+      return;
+    }
+    prevStatusRef.current = chartStatus;
+
+    if (chartStatus === "ready" && prevStatus === "loading") {
+      setIsLoaded(false);
+      if (animationDuration <= 0) {
+        if (yDomainTweenDuration <= 0) {
+          setPlotData(targetData);
+          setChartPhase("revealing");
+        } else {
+          setChartPhase("gridTweenReady");
+        }
+      } else {
+        setChartPhase("exiting");
+      }
+      return;
+    }
+
+    if (chartStatus === "loading" && prevStatus === "ready") {
+      setIsLoaded(false);
+      if (animationDuration <= 0) {
+        if (yDomainTweenDuration <= 0) {
+          setPlotData(skeletonData);
+          setChartPhase("loading");
+        } else {
+          setChartPhase("gridTweenLoading");
+        }
+      } else {
+        setConcealEpoch((epoch) => epoch + 1);
+        setChartPhase("exitingReady");
+      }
+    }
+  }, [animationDuration, chartStatus, skeletonData, targetData, yDomainTweenDuration]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: revealSignature replays enter
+  useEffect(() => {
+    if (skipEnterReveal) {
+      return;
+    }
+    if (chartStatus !== "ready") {
+      return;
+    }
+    if (phaseRef.current !== "ready") {
+      return;
+    }
+
+    setChartPhase("revealing");
+    setIsLoaded(false);
+  }, [animationDuration, chartStatus, revealSignature, skipEnterReveal]);
+
+  useEffect(() => {
+    switch (chartPhase) {
+      case "loading":
+        if (chartStatus === "loading") {
+          setPlotData(skeletonData);
+        }
+        break;
+      case "exiting":
+        setPlotData(skeletonData);
+        break;
+      case "exitingReady":
+      case "gridTweenLoading":
+      case "gridTweenReady":
+      case "revealing":
+      case "ready":
+        setPlotData(targetData);
+        break;
+      default:
+        break;
+    }
+  }, [chartPhase, chartStatus, skeletonData, targetData]);
+
+  /** Loading pulse exit finished — tween grid to ready spacing next. */
+  const notifyLoadingPulseComplete = useCallback(() => {
+    if (phaseRef.current !== "exiting") {
+      return;
+    }
+    setChartPhase("gridTweenReady");
+  }, []);
+
+  /** Ready series conceal finished — tween grid to loading spacing next. */
+  const notifyRevealConcealComplete = useCallback(() => {
+    if (phaseRef.current !== "exitingReady") {
+      return;
+    }
+    setChartPhase("gridTweenLoading");
+  }, []);
+
+  /** Grid tween finished — enter the next resting phase. */
+  const notifyYDomainTweenComplete = useCallback(() => {
+    if (phaseRef.current === "gridTweenLoading") {
+      setChartPhase("loading");
+      return;
+    }
+    if (phaseRef.current === "gridTweenReady") {
+      setChartPhase("revealing");
+    }
+  }, []);
+
+  useEffect(() => {
+    if (chartPhase !== "revealing") {
+      return;
+    }
+
+    setRevealEpoch((epoch) => epoch + 1);
+    if (animationDuration <= 0) {
+      setChartPhase("ready");
+      setIsLoaded(true);
+      return;
+    }
+
+    const timer = window.setTimeout(() => {
+      setChartPhase("ready");
+      setIsLoaded(true);
+    }, animationDuration);
+    return () => window.clearTimeout(timer);
+  }, [animationDuration, chartPhase]);
+
+  return {
+    chartPhase,
+    plotData,
+    revealEpoch,
+    concealEpoch,
+    isLoaded,
+    notifyLoadingPulseComplete,
+    notifyRevealConcealComplete,
+    notifyYDomainTweenComplete,
+  };
+}

package/src/console/ui-next/src/components/charts/use-enter-complete.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import type { MotionValue } from "motion/react";
+import { useEffect, useState } from "react";
+
+/**
+ * Returns true once a mount-progress MotionValue reaches 1.
+ * Use to swap animated MotionValue-driven props for static values after
+ * enter completes — drops per-frame subscriptions during pan/hover.
+ */
+export function useEnterComplete(mountProgress: MotionValue<number>): boolean {
+  const [complete, setComplete] = useState(() => mountProgress.get() >= 1);
+
+  useEffect(() => {
+    if (mountProgress.get() >= 1) {
+      setComplete(true);
+      return;
+    }
+
+    return mountProgress.on("change", (value) => {
+      if (value >= 1) {
+        setComplete(true);
+      }
+    });
+  }, [mountProgress]);
+
+  return complete;
+}

package/src/console/ui-next/src/components/charts/use-grid-shimmer.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { animate, useMotionValue, useReducedMotion, useTransform } from "motion/react";
+import { useEffect } from "react";
+import {
+  LINE_LOADING_LOOP_PAUSE_MS,
+  LINE_LOADING_PULSE_CYCLE_S,
+  LINE_LOADING_PULSE_EASE,
+} from "./line-loading-timing";
+
+export interface UseGridShimmerOptions {
+  innerWidth: number;
+  shimmer: boolean;
+  shimmerLength: number;
+  shimmerSpeed: number;
+  shimmerSync: boolean;
+  /** When false, shimmer animation is paused (e.g. during exit transition). */
+  active: boolean;
+  /** Run a single synced sweep (loading → ready handoff). */
+  oneShot?: boolean;
+}
+
+export function useGridShimmer({
+  innerWidth,
+  shimmer,
+  shimmerLength,
+  shimmerSpeed,
+  shimmerSync,
+  active,
+  oneShot = false,
+}: UseGridShimmerOptions) {
+  const progress = useMotionValue(0);
+  const reducedMotion = useReducedMotion();
+  const shimmerCycleS = LINE_LOADING_PULSE_CYCLE_S / Math.max(shimmerSpeed, 0.1);
+  const shimmerEnabled = active && shimmer && reducedMotion !== true && innerWidth > 0;
+
+  useEffect(() => {
+    if (!shimmerEnabled) {
+      return;
+    }
+
+    let cancelled = false;
+    let timeoutId: number | undefined;
+    let controls: ReturnType<typeof animate> | undefined;
+
+    const runSyncedCycle = () => {
+      if (cancelled) {
+        return;
+      }
+
+      progress.set(0);
+      controls = animate(progress, 1, {
+        duration: shimmerCycleS,
+        ease: [...LINE_LOADING_PULSE_EASE],
+        onComplete: () => {
+          if (cancelled) {
+            return;
+          }
+          timeoutId = window.setTimeout(runSyncedCycle, LINE_LOADING_LOOP_PAUSE_MS);
+        },
+      });
+    };
+
+    if (shimmerSync && oneShot) {
+      progress.set(0);
+      controls = animate(progress, 1, {
+        duration: shimmerCycleS / 2,
+        ease: [...LINE_LOADING_PULSE_EASE],
+      });
+      return () => controls?.stop();
+    }
+
+    if (shimmerSync) {
+      runSyncedCycle();
+      return () => {
+        cancelled = true;
+        controls?.stop();
+        if (timeoutId !== undefined) {
+          window.clearTimeout(timeoutId);
+        }
+      };
+    }
+
+    progress.set(0);
+    controls = animate(progress, 1, {
+      duration: shimmerCycleS,
+      repeat: Number.POSITIVE_INFINITY,
+      ease: [...LINE_LOADING_PULSE_EASE],
+    });
+
+    return () => controls?.stop();
+  }, [oneShot, progress, shimmerCycleS, shimmerEnabled, shimmerSync]);
+
+  const shimmerX = useTransform(
+    progress,
+    (value) => -shimmerLength + value * (innerWidth + shimmerLength * 2),
+  );
+  const shimmerTransform = useTransform(shimmerX, (x) => `translate(${x}, 0)`);
+
+  return { shimmerEnabled, shimmerTransform };
+}

package/src/console/ui-next/src/components/charts/use-highlight-segment.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import { useSpring } from "motion/react";
+import { useMemo, useRef } from "react";
+import { useChartConfig } from "./chart-config-context";
+import { useChartHover, useChartStable } from "./chart-context";
+import { computeSegmentBounds, INACTIVE_SEGMENT } from "./highlight-segment-bounds";
+
+// Hover-highlight band for `line.tsx` and `area.tsx`. Computes the segment
+// bounds and springs its x/width; `<HighlightSegment>` renders the clipped
+// re-stroke. Spring tuning comes from `ChartConfigProvider.highlightSpring`.
+// Stable + hover slices are read separately so callers can see the exact
+// subscription surface (anything calling this hook will re-render on hover).
+
+export interface HighlightSegmentResult {
+  xSpring: ReturnType<typeof useSpring>;
+  widthSpring: ReturnType<typeof useSpring>;
+  isActive: boolean;
+}
+
+/**
+ * @param enabled set false when there is no stroke to highlight (e.g. an area
+ *   with `showLine={false}`); defaults true.
+ */
+export function useHighlightSegment({
+  enabled = true,
+}: {
+  enabled?: boolean;
+} = {}): HighlightSegmentResult {
+  const { data, xScale, xAccessor } = useChartStable();
+  const { tooltipData, selection } = useChartHover();
+  const { highlightSpring } = useChartConfig();
+
+  const bounds = useMemo(
+    () =>
+      enabled
+        ? computeSegmentBounds(data, xScale, xAccessor, tooltipData, selection)
+        : INACTIVE_SEGMENT,
+    [enabled, data, xScale, xAccessor, tooltipData, selection],
+  );
+
+  const xSpring = useSpring(0, highlightSpring);
+  const widthSpring = useSpring(0, highlightSpring);
+
+  // Jump on inactive→active so the band appears at the hovered point instead
+  // of sliding in from x=0; ease on subsequent moves.
+  const wasActive = useRef(false);
+  if (bounds.isActive && !wasActive.current) {
+    xSpring.jump(bounds.x);
+    widthSpring.jump(bounds.width);
+  } else {
+    xSpring.set(bounds.x);
+    widthSpring.set(bounds.width);
+  }
+  wasActive.current = bounds.isActive;
+
+  return { xSpring, widthSpring, isActive: bounds.isActive };
+}

package/src/console/ui-next/src/components/charts/use-mount-progress.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import { animate, type Transition, useMotionValue } from "motion/react";
+import { useEffect, useRef } from "react";
+import { DEFAULT_CHART_ENTER_TRANSITION } from "./animation";
+
+/** Drives 0→1 enter progress using the studio motion transition (spring or tween). */
+export function useMountProgress(
+  enterTransition: Transition | undefined,
+  delaySeconds: number,
+  replayKey: number | string,
+) {
+  const progress = useMotionValue(0);
+  const transitionRef = useRef(enterTransition);
+  transitionRef.current = enterTransition;
+
+  // replayKey intentionally retriggers enter when motion settings change
+  // biome-ignore lint/correctness/useExhaustiveDependencies: replayKey
+  useEffect(() => {
+    progress.set(0);
+    const controls = animate(progress, 1, {
+      ...(transitionRef.current ?? DEFAULT_CHART_ENTER_TRANSITION),
+      delay: delaySeconds,
+    });
+    return () => controls.stop();
+  }, [delaySeconds, replayKey, progress]);
+
+  return progress;
+}

package/src/console/ui-next/src/components/charts/use-scheduled-tooltip.ts

@@ -0,0 +1,97 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface ScheduledTooltipControls<T> {
+  tooltipData: T | null;
+  setTooltipData: React.Dispatch<React.SetStateAction<T | null>>;
+  scheduleTooltip: (tooltip: T, dedupeKey?: string) => void;
+  clearTooltip: () => void;
+  resetTooltipDedupe: () => void;
+}
+
+function defaultDedupeKey<T>(tooltip: T): string {
+  if (
+    typeof tooltip === "object" &&
+    tooltip !== null &&
+    "index" in tooltip &&
+    typeof (tooltip as { index: unknown }).index === "number"
+  ) {
+    const { index, x } = tooltip as { index: number; x?: number };
+    if (typeof x === "number") {
+      return `${index}:${Math.round(x)}`;
+    }
+    return String(index);
+  }
+  return JSON.stringify(tooltip);
+}
+
+export function useScheduledTooltip<T>(): ScheduledTooltipControls<T> {
+  const [tooltipData, setTooltipData] = useState<T | null>(null);
+  const lastKeyRef = useRef<string | null>(null);
+  const pendingRef = useRef<T | null>(null);
+  const rafRef = useRef<number | null>(null);
+  const pendingKeyRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current);
+      }
+    };
+  }, []);
+
+  const commitTooltip = useCallback((tooltip: T, dedupeKey: string) => {
+    if (dedupeKey === lastKeyRef.current) {
+      return;
+    }
+    lastKeyRef.current = dedupeKey;
+    setTooltipData(tooltip);
+  }, []);
+
+  const scheduleTooltip = useCallback(
+    (tooltip: T, dedupeKey?: string) => {
+      const key = dedupeKey ?? defaultDedupeKey(tooltip);
+      pendingRef.current = tooltip;
+      pendingKeyRef.current = key;
+      if (key === lastKeyRef.current) {
+        return;
+      }
+      if (rafRef.current !== null) {
+        return;
+      }
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = null;
+        const next = pendingRef.current;
+        const nextKey = pendingKeyRef.current;
+        if (next && nextKey) {
+          commitTooltip(next, nextKey);
+        }
+      });
+    },
+    [commitTooltip],
+  );
+
+  const clearTooltip = useCallback(() => {
+    if (rafRef.current !== null) {
+      cancelAnimationFrame(rafRef.current);
+      rafRef.current = null;
+    }
+    pendingRef.current = null;
+    pendingKeyRef.current = null;
+    lastKeyRef.current = null;
+    setTooltipData(null);
+  }, []);
+
+  const resetTooltipDedupe = useCallback(() => {
+    lastKeyRef.current = null;
+  }, []);
+
+  return {
+    tooltipData,
+    setTooltipData,
+    scheduleTooltip,
+    clearTooltip,
+    resetTooltipDedupe,
+  };
+}