@tetrascience-npm/tetrascience-react-ui 0.6.0 → 0.7.0-beta.103.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";
 }
 
@@ -134,7 +136,15 @@ export declare const AreaGraph: default_2.FC<AreaGraphProps>;
 
 export declare interface AreaGraphProps {
     dataSeries: AreaDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     xRange?: [number, number];
     yRange?: [number, number];
@@ -142,6 +152,13 @@ export declare interface AreaGraphProps {
     xTitle?: string;
     yTitle?: string;
     title?: string;
+    /**
+     * Categorical labels for the x-axis ticks. When provided, the x data values
+     * still drive area positioning but the displayed tick labels match these
+     * strings in order (e.g. ["Mon", "Tue", …]). Should align 1:1 with the
+     * unique, ordered x values across all series.
+     */
+    xTickText?: string[];
 }
 
 export declare type AreaGraphVariant = "normal" | "stacked";
@@ -292,7 +309,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[];
@@ -304,7 +322,15 @@ export declare const BarGraph: default_2.FC<BarGraphProps>;
 
 export declare interface BarGraphProps {
     dataSeries: BarDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     xRange?: [number, number];
     yRange?: [number, number];
@@ -313,6 +339,13 @@ export declare interface BarGraphProps {
     yTitle?: string;
     title?: string;
     barWidth?: number;
+    /**
+     * Categorical labels for the x-axis ticks. When provided, the x data values
+     * still drive bar positioning but the displayed tick labels match these
+     * strings in order (e.g. ["Mon", "Tue", …]). Should align 1:1 with the
+     * unique, ordered x values across all series.
+     */
+    xTickText?: string[];
 }
 
 export declare type BarGraphVariant = "group" | "stack" | "overlay";
@@ -337,7 +370,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;
@@ -348,7 +382,15 @@ export declare const Boxplot: default_2.FC<BoxplotProps>;
 
 export declare interface BoxplotProps {
     dataSeries: BoxDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     xRange?: [number, number];
     yRange?: [number, number];
@@ -575,6 +617,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 +916,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 +937,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 & {
@@ -1160,7 +1219,7 @@ export declare interface CostBreakdown {
     cache?: number;
 }
 
-export declare function DataAppShell({ appName, appFullName, appIcon, version, navGroups, onAppNameClick, backToPlatformPath, onBackToPlatform, userMenu, breadcrumbs, onHelpClick, headerActions, sidebarPanel, children, className, }: DataAppShellProps): JSX.Element;
+export declare function DataAppShell({ appName, appFullName, appIcon, version, navGroups, onAppNameClick, backToPlatformPath, onBackToPlatform, userMenu, breadcrumbs, onHelpClick, headerActions, sidebarPanel, showNavRail, children, className, }: DataAppShellProps): JSX.Element;
 
 export declare interface DataAppShellProps {
     /** Application name/abbreviation shown in the logo button */
@@ -1189,6 +1248,8 @@ export declare interface DataAppShellProps {
     headerActions?: React_2.ReactNode;
     /** Slot rendered between the icon rail and the content (e.g. WorkflowPanel) */
     sidebarPanel?: React_2.ReactNode;
+    /** Show the desktop icon nav rail. Set false to reclaim width when the panel is collapsed. */
+    showNavRail?: boolean;
     /** Main content area */
     children: React_2.ReactNode;
     /** Additional className for the root container */
@@ -1316,7 +1377,15 @@ export declare interface DotPlotDataSeries {
 
 export declare type DotPlotProps = {
     dataSeries: DotPlotDataSeries | DotPlotDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     title?: string;
     xTitle?: string;
@@ -1554,7 +1623,15 @@ export declare interface HistogramDataSeries {
 
 export declare type HistogramProps = {
     dataSeries: HistogramDataSeries | HistogramDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     title?: string;
     xTitle?: string;
@@ -1798,7 +1875,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";
@@ -1811,7 +1889,15 @@ export declare const LineGraph: default_2.FC<LineGraphProps>;
 
 export declare type LineGraphProps = {
     dataSeries: LineDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     xRange?: [number, number];
     yRange?: [number, number];
@@ -1819,6 +1905,13 @@ export declare type LineGraphProps = {
     xTitle?: string;
     yTitle?: string;
     title?: string;
+    /**
+     * Categorical labels for the x-axis ticks. When provided, the x data values
+     * still drive line positioning but the displayed tick labels match these
+     * strings in order (e.g. ["Mon", "Tue", …]). Should align 1:1 with the
+     * unique, ordered x values across all series.
+     */
+    xTickText?: string[];
 };
 
 export declare type LineGraphVariant = "lines" | "lines+markers" | "lines+markers+error_bars";
@@ -3160,6 +3253,24 @@ export declare interface ReferencedSourcesContext {
     clear: () => void;
 }
 
+/**
+ * Resize handle between two panels.
+ *
+ * The handle's layout footprint is a **1px divider that sits exactly on the
+ * panel boundary**, so the divider, the grip, and the seam between the panels
+ * all line up — regardless of the panels' backgrounds. A wide, transparent
+ * **grab area** is layered on top via `::after` (it overlaps both panels by 6px
+ * without taking layout space) so the handle can be grabbed anywhere in the gap,
+ * not just on the hairline.
+ *
+ * The 1px divider — and the optional grip (`withHandle`) — stay hidden at rest
+ * and **reveal on hover, keyboard focus, or while dragging** (the handle tracks
+ * the pointer, so it stays hovered). Keyboard focus reveals them in the `ring`
+ * color for a clear focus indicator. Works in both orientations.
+ *
+ * Has a default `aria-label` so the separator always has an accessible name;
+ * pass `aria-label` to override it with something context-specific.
+ */
 export declare function ResizableHandle({ withHandle, className, ...props }: ResizablePrimitive.SeparatorProps & {
     withHandle?: boolean;
 }): JSX.Element;
@@ -3205,14 +3316,23 @@ 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>;
 
 export declare interface ScatterGraphProps {
     dataSeries: ScatterDataSeries[];
+    /**
+     * Fixed width in pixels. When omitted, the chart fills its container and
+     * tracks the container's width via a `ResizeObserver`.
+     */
     width?: number;
+    /**
+     * Fixed height in pixels. When omitted, the chart fills its container and
+     * tracks the container's height via a `ResizeObserver`.
+     */
     height?: number;
     xRange?: [number, number];
     yRange?: [number, number];
@@ -3256,6 +3376,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 +4028,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 +4049,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>;