@tetrascience-npm/tetrascience-react-ui 0.6.0-beta.83.1 → 0.6.0-beta.84.1

package/dist/index.d.ts

@@ -48,6 +48,7 @@ import * as React_2 from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { ReactPortal } from 'react';
+import { Ref } from 'react';
 import { RefObject } from 'react';
 import * as ResizablePrimitive from 'react-resizable-panels';
 import { ScrollArea as ScrollArea_2 } from 'radix-ui';
@@ -578,6 +579,94 @@ export declare const CHART_SEQUENTIAL: {
     readonly purple: string[];
 };
 
+/**
+ * The design-system tooltip anchored at a chart position; drive it with
+ * `useChartTooltip`.
+ *
+ * Renders the same visual as the ui `TooltipContent` (bubble + arrow) but
+ * positions it directly from the anchor coordinates — Radix's popper
+ * repositions asynchronously and mis-measures animated content, which made
+ * tooltips drift on charts. Placement supports all four sides with
+ * Radix-style collision flipping.
+ */
+export declare function ChartTooltip({ anchor, bubbleRef }: ChartTooltipProps): ReactPortal | null;
+
+export declare interface ChartTooltipAnchor {
+    left: number;
+    top: number;
+    lines: string[];
+    /** Preferred placement side; auto-flips to the opposite when it won't fit */
+    side?: ChartTooltipSide;
+    /** Plays the exit animation before the tooltip unmounts */
+    closing?: boolean;
+}
+
+/**
+ * Minimal structural view of a Plotly hover point — covers cartesian, pie,
+ * and heatmap traces without depending on Plotly's loose event typings.
+ */
+export declare interface ChartTooltipHoverPoint {
+    x?: number | string;
+    y?: number | string;
+    z?: number;
+    /** Pie slice label */
+    label?: string;
+    /** Pie slice value */
+    value?: number;
+    /** Pie slice raw value (Plotly's `v` alias) */
+    v?: number;
+    /** Pie slice percentage (0–100) */
+    percent?: number;
+    /** Per-point hover text (e.g. PlateMap wells), lines separated by `<br>` */
+    text?: string;
+    pointIndex?: number;
+    data?: {
+        name?: string;
+    };
+    /** Per-point custom data attached to the trace */
+    customdata?: unknown;
+    /** Hovered point bounds in plot-div pixels (provided by Plotly) */
+    bbox?: {
+        x0: number;
+        x1: number;
+        y0: number;
+        y1: number;
+    };
+    /**
+     * Plotly axis objects (internal) used to project a data value to a plot-div
+     * pixel. Bars report a `bbox` that sits below their visual top, so we anchor
+     * to `_offset + l2p(value)` instead.
+     */
+    yaxis?: {
+        _offset?: number;
+        l2p?: (value: number) => number;
+    };
+    xaxis?: {
+        _offset?: number;
+        l2p?: (value: number) => number;
+    };
+}
+
+/**
+ * Build default tooltip lines from Plotly hover points. Handles pie slices,
+ * text-carrying traces (e.g. PlateMap wells), single cartesian points, and
+ * unified multi-trace hovers.
+ */
+export declare function chartTooltipLines(points: ChartTooltipHoverPoint[], labels?: {
+    xLabel?: string;
+    yLabel?: string;
+}): string[];
+
+export declare interface ChartTooltipProps {
+    /** Anchor position (viewport coordinates) and content lines */
+    anchor: ChartTooltipAnchor | null;
+    /** Ref to the bubble node, used by cursor-following charts to clamp it on-screen */
+    bubbleRef?: Ref<HTMLDivElement>;
+}
+
+/** Which edge of the point the tooltip is placed against (matches Radix). */
+export declare type ChartTooltipSide = "top" | "bottom" | "left" | "right";
+
 export declare const Chat: ({ initialMessages, models, defaultModel, suggestions, onSend, className, }: ChatProps) => JSX.Element;
 
 export declare interface ChatMessage {
@@ -3863,6 +3952,47 @@ export declare function useCarousel(): CarouselContextProps;
 
 declare type UseCarouselParameters = Parameters<typeof default_3>;
 
+/**
+ * Drives the design-system tooltip from Plotly hover events.
+ *
+ * ```tsx
+ * const { bindTooltip, tooltipElement } = useChartTooltip({ xLabel, yLabel });
+ * // after Plotly.newPlot(...): set trace hoverinfo to "none", then
+ * bindTooltip(plotRef.current);
+ * // anywhere in the chart markup:
+ * {tooltipElement}
+ * ```
+ */
+export declare function useChartTooltip(options?: UseChartTooltipOptions): {
+    bindTooltip: (plotDiv: HTMLElement | null) => void;
+    tooltipElement: JSX.Element;
+};
+
+export declare interface UseChartTooltipOptions {
+    /** Axis label used for the default x line (falls back to "X") */
+    xLabel?: string;
+    /** Axis label used for the default y line (falls back to "Y") */
+    yLabel?: string;
+    /** Override the default line builder entirely */
+    getLines?: (points: ChartTooltipHoverPoint[]) => string[];
+    /**
+     * Track the cursor instead of anchoring to the hovered point's bounds, and
+     * keep the tooltip clamped inside the viewport. Use for traces with large
+     * hover targets (e.g. pie slices) where a fixed anchor feels disconnected.
+     */
+    followCursor?: boolean;
+    /**
+     * Override Plotly's hover hit radius (px). A larger radius makes big markers
+     * (e.g. heatmap circles) hoverable across their whole face.
+     */
+    hoverDistance?: number;
+    /**
+     * Preferred side to place the tooltip on relative to the point. Auto-flips to
+     * the opposite side when there isn't room (Radix-style). Defaults to "top".
+     */
+    side?: ChartTooltipSide;
+}
+
 export declare function useComboboxAnchor(): React_2.RefObject<HTMLDivElement | null>;
 
 export declare function useDataTable<TData = unknown>(): TableContextValue<TData>;