@tetrascience-npm/tetrascience-react-ui 0.6.0-beta.82.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';
@@ -126,7 +127,8 @@ export declare interface AreaDataSeries {
     x: number[];
     y: number[];
     name: string;
-    color: string;
+    /** Optional color override (auto-assigned from CHART_COLORS if not provided) */
+    color?: string;
     fill?: "tozeroy" | "tonexty" | "toself";
 }
 
@@ -292,7 +294,8 @@ export declare interface BarDataSeries {
     x: number[];
     y: number[];
     name: string;
-    color: string;
+    /** Optional color override (auto-assigned from CHART_COLORS if not provided) */
+    color?: string;
     error_y?: {
         type: "data";
         array: number[];
@@ -337,7 +340,8 @@ declare type BoundaryMarkerType = "none" | "triangle" | "diamond";
 export declare interface BoxDataSeries {
     y: number[];
     name: string;
-    color: string;
+    /** Optional color override (auto-assigned from CHART_COLORS if not provided) */
+    color?: string;
     x?: string[] | number[];
     boxpoints?: "all" | "outliers" | "suspectedoutliers" | false;
     jitter?: number;
@@ -575,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 {
@@ -786,75 +878,6 @@ export declare function CollapsibleContent({ ...props }: React.ComponentProps<ty
 
 export declare function CollapsibleTrigger({ ...props }: React.ComponentProps<typeof Collapsible_2.CollapsibleTrigger>): JSX.Element;
 
-/**
- * Centralized color tokens that map to CSS variables
- * This provides TypeScript support while leveraging CSS custom properties
- */
-export declare const COLORS: {
-    readonly BLACK_50: string;
-    readonly BLACK_100: string;
-    readonly BLACK_200: string;
-    readonly BLACK_300: string;
-    readonly BLACK_400: string;
-    readonly BLACK_500: string;
-    readonly BLACK_600: string;
-    readonly BLACK_700: string;
-    readonly BLACK_800: string;
-    readonly BLACK_900: string;
-    readonly BLACK: string;
-    readonly BLACK_OPACITY_20: "rgba(26, 26, 26, 0.2)";
-    readonly WHITE_50: string;
-    readonly WHITE_100: string;
-    readonly WHITE_200: string;
-    readonly WHITE_300: string;
-    readonly WHITE_400: string;
-    readonly WHITE_500: string;
-    readonly WHITE_600: string;
-    readonly WHITE_700: string;
-    readonly WHITE_800: string;
-    readonly WHITE_900: string;
-    readonly WHITE: string;
-    readonly BLUE_50: string;
-    readonly BLUE_100: string;
-    readonly BLUE_200: string;
-    readonly BLUE_300: string;
-    readonly BLUE_400: string;
-    readonly BLUE_500: string;
-    readonly BLUE_600: string;
-    readonly BLUE_700: string;
-    readonly BLUE_800: string;
-    readonly BLUE_900: string;
-    readonly BLUE: string;
-    readonly GREY_50: string;
-    readonly GREY_100: string;
-    readonly GREY_200: string;
-    readonly GREY_300: string;
-    readonly GREY_400: string;
-    readonly GREY_500: string;
-    readonly GREY_600: string;
-    readonly GREY_700: string;
-    readonly GREY_800: string;
-    readonly GREY_900: string;
-    readonly GREY: string;
-    readonly ORANGE: string;
-    readonly RED: string;
-    readonly GREEN: string;
-    readonly YELLOW: string;
-    readonly PURPLE: string;
-    readonly GREEN_BG: string;
-    readonly GREEN_SUCCESS: string;
-    readonly ORANGE_BG: string;
-    readonly ORANGE_CAUTION: string;
-    readonly RED_BG: string;
-    readonly RED_ERROR: string;
-    readonly GRAPH_SECONDARY_BROWN: string;
-    readonly GRAPH_SECONDARY_PINK: string;
-    readonly GRAPH_SECONDARY_TEAL: string;
-    readonly GRAPH_SECONDARY_DARK_BLUE: string;
-    readonly GRAPH_SECONDARY_BLACK: string;
-    readonly GRAPH_SECONDARY_GREY: string;
-};
-
 /**
  * Color scale definition for the heatmap visualization mode.
  *
@@ -876,8 +899,6 @@ export declare const COLORS: {
  */
 export declare type ColorScale = string | Array<[number, string]>;
 
-export declare type ColorToken = keyof typeof COLORS;
-
 export declare const Combobox: typeof Combobox_2.Root;
 
 export declare function ComboboxChip({ className, children, showRemove, ...props }: Combobox_2.Chip.Props & {
@@ -1798,7 +1819,8 @@ export declare interface LineDataSeries {
     x: number[];
     y: number[];
     name: string;
-    color: string;
+    /** Optional color override (auto-assigned from CHART_COLORS if not provided) */
+    color?: string;
     symbol?: MarkerSymbol;
     error_y?: {
         type: "data";
@@ -3205,7 +3227,8 @@ export declare interface ScatterDataSeries {
     x: number[];
     y: number[];
     name: string;
-    color: string;
+    /** Optional color override (auto-assigned from CHART_COLORS if not provided) */
+    color?: string;
 }
 
 export declare const ScatterGraph: default_2.FC<ScatterGraphProps>;
@@ -3256,6 +3279,16 @@ export declare function SelectValue({ ...props }: React_2.ComponentProps<typeof
 
 export declare function Separator({ className, orientation, decorative, ...props }: React_2.ComponentProps<typeof Separator_2.Root>): JSX.Element;
 
+/**
+ * Resolve the color for a data series: use the explicit color when one is
+ * provided, otherwise cycle through the {@link CHART_COLORS} palette by series
+ * index (wrapping around when there are more series than palette slots).
+ *
+ * @param index - Zero-based series index
+ * @param explicit - Caller-provided color override, if any
+ */
+export declare const seriesColor: (index: number, explicit?: string | null) => string;
+
 export declare function Sheet({ ...props }: React_2.ComponentProps<typeof Dialog_2.Root>): JSX.Element;
 
 export declare function SheetClose({ ...props }: React_2.ComponentProps<typeof Dialog_2.Close>): JSX.Element;
@@ -3898,6 +3931,12 @@ declare type ToolUIPartApproval = {
     reason?: string;
 } | undefined;
 
+/**
+ * Convert a color ramp (e.g. `CHART_SEQUENTIAL.blue`, `CHART_DIVERGING.blueOrange`)
+ * into Plotly's colorscale format: evenly spaced [position, color] stops.
+ */
+export declare const toPlotlyColorscale: (ramp: readonly string[]) => Array<[number, string]>;
+
 export declare function triagePlateMapCsvByBarcode(text: string, options?: PlateMapCsvTriageOptions): PlateMapCsvTriage;
 
 export declare function triagePlateMapCsvFile(file: File, options?: PlateMapCsvTriageOptions): Promise<PlateMapCsvTriage | undefined>;
@@ -3913,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>;