@tetrascience-npm/tetrascience-react-ui 0.7.0-beta.129.1 → 0.7.0-beta.131.1

package/dist/components/charts/PlateMap/types.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Plate format string constants for standard microplate configurations.
+ */
+export declare const PLATE_FORMAT_96: "96";
+export declare const PLATE_FORMAT_384: "384";
+export declare const PLATE_FORMAT_1536: "1536";
+export declare const PLATE_FORMAT_CUSTOM: "custom";
+/**
+ * Plate format presets for standard microplate configurations.
+ * - `"96"`: 8 rows × 12 columns (wells A1-H12)
+ * - `"384"`: 16 rows × 24 columns (wells A1-P24)
+ * - `"1536"`: 32 rows × 48 columns (wells A1-AF48)
+ * - `"custom"`: User-defined dimensions via `rows` and `columns` props
+ */
+export type PlateFormat = typeof PLATE_FORMAT_96 | typeof PLATE_FORMAT_384 | typeof PLATE_FORMAT_1536 | typeof PLATE_FORMAT_CUSTOM;
+/**
+ * Visualization mode for the plate map.
+ * - `"heatmap"`: Displays quantitative values as a continuous color gradient.
+ *   Use for OD readings, fluorescence intensity, or other numeric measurements.
+ * - `"categorical"`: Displays well types with discrete colors.
+ *   Use for showing sample types, control positions, or experimental conditions.
+ */
+export type VisualizationMode = "heatmap" | "categorical";
+/**
+ * Well type for categorical visualization.
+ * Common types include:
+ * - `"sample"`: Test samples (blue by default)
+ * - `"control"`: Positive/negative controls (red by default)
+ * - `"empty"`: Unused wells (light gray by default)
+ *
+ * Custom types can be added and colored via the `categoryColors` prop.
+ */
+export type WellType = "sample" | "control" | "empty" | string;
+/**
+ * Color scale definition for the heatmap visualization mode.
+ *
+ * Can be:
+ * - A named Plotly colorscale (e.g., "Viridis", "Blues", "Hot")
+ * - An array of [position, color] tuples where position is 0-1
+ *
+ * @example
+ * // Named colorscale
+ * colorScale="Viridis"
+ *
+ * @example
+ * // Custom gradient
+ * colorScale={[
+ *   [0, "#313695"],   // Dark blue at min
+ *   [0.5, "#ffffbf"], // Yellow at midpoint
+ *   [1, "#a50026"],   // Dark red at max
+ * ]}
+ */
+export type ColorScale = string | Array<[number, string]>;
+/**
+ * Position for the legend display.
+ * - `"right"`: Legend appears to the right of the plate (default)
+ * - `"bottom"`: Legend appears below the plate
+ * - `"left"`: Legend appears to the left of the plate
+ * - `"top"`: Legend appears above the plate
+ */
+export type LegendPosition = "right" | "bottom" | "left" | "top";
+/**
+ * Well data for individual wells.
+ *
+ * @example
+ * // Well with a single numeric value
+ * { wellId: "A1", values: { "Fluorescence": 1500 } }
+ *
+ * @example
+ * // Well with multiple values (creates multiple layers)
+ * { wellId: "A1", values: { "Raw": 1500, "Normalized": 0.85, "Status": "positive" } }
+ *
+ * @example
+ * // Well with tooltip-only data
+ * { wellId: "A1", values: { "Value": 500 }, tooltipData: { compound: "Drug A", concentration: "10µM" } }
+ */
+export interface WellData {
+    /**
+     * Well identifier in standard microplate notation.
+     * - Single letter + number for 96/384-well: "A1", "H12", "P24"
+     * - Double letter + number for 1536-well: "A1", "AA1", "AF48"
+     * Case-insensitive ("a1" and "A1" are equivalent).
+     */
+    wellId: string;
+    /**
+     * Named values for the well. Each key can become a visualization layer.
+     *
+     * - Numeric values: Displayed using heatmap visualization
+     * - String values: Displayed using categorical visualization
+     * - null: Empty/no data for that property
+     *
+     * All values are shown in the tooltip regardless of which layer is active.
+     *
+     * @example
+     * // Well with multiple measurement values (numeric)
+     * { wellId: "A1", values: { "Raw": 1500, "Normalized": 0.85, "Z-Score": 1.2 } }
+     *
+     * @example
+     * // Well with categorical values (string)
+     * { wellId: "A1", values: { "Status": "positive", "QC": "pass" } }
+     *
+     * @example
+     * // Mixed numeric and categorical
+     * { wellId: "A1", values: { "Fluorescence": 1500, "Status": "positive" } }
+     */
+    values?: Record<string, string | number | null>;
+    /**
+     * Optional data for tooltip display only (not visualized as layers).
+     * Keys become labels, values are displayed.
+     *
+     * @example
+     * { tooltipData: { sampleId: "S001", compound: "Drug A", concentration: "10µM" } }
+     */
+    tooltipData?: Record<string, unknown>;
+}
+/**
+ * Configuration for auto-generated layers when using WellData with `values`.
+ *
+ * When wells have multiple values (via the `values` property), layers are
+ * auto-generated from the unique keys. Use LayerConfig to customize the
+ * display name, visualization mode, and color scale for each layer.
+ *
+ * @example
+ * // Configure layers for wells with { values: { "Raw": 100, "Normalized": 0.5 } }
+ * const layerConfigs: LayerConfig[] = [
+ *   { id: "Raw", name: "Raw Data", colorScale: "Blues" },
+ *   { id: "Normalized", name: "Normalized Values", valueMin: 0, valueMax: 1 },
+ * ];
+ */
+export interface LayerConfig {
+    /** Layer ID (must match a key in WellData.values) */
+    id: string;
+    /** Display name for the layer (defaults to id if not provided) */
+    name?: string;
+    /** Visualization mode for this layer */
+    visualizationMode?: VisualizationMode;
+    /** Color scale for this layer (for heatmap mode) */
+    colorScale?: ColorScale;
+    /** Minimum value for color scaling */
+    valueMin?: number;
+    /** Maximum value for color scaling */
+    valueMax?: number;
+    /** Value unit suffix for tooltips and colorbar (e.g., "RFU", "%"). A space is automatically added before the unit. */
+    valueUnit?: string;
+    /**
+     * Custom colors for categorical visualization mode.
+     * Keys are category values (strings from `values`), values are hex colors.
+     * Merged with DEFAULT_CATEGORY_COLORS.
+     */
+    categoryColors?: Record<string, string>;
+}
+/**
+ * Configuration for legend styling and positioning.
+ *
+ * @example
+ * // Legend on the bottom with custom styling
+ * legendConfig={{
+ *   position: "bottom",
+ *   fontSize: 14,
+ *   itemSpacing: 12,
+ *   swatchSize: 20,
+ * }}
+ */
+export interface LegendConfig {
+    /**
+     * Position of the legend relative to the plate.
+     * @default "right"
+     */
+    position?: LegendPosition;
+    /**
+     * Font size for legend labels in pixels.
+     * @default 12
+     */
+    fontSize?: number;
+    /**
+     * Spacing between legend items in pixels.
+     * @default 4
+     */
+    itemSpacing?: number;
+    /**
+     * Size of the color swatch in pixels.
+     * @default 16
+     */
+    swatchSize?: number;
+    /**
+     * Title to display above the legend.
+     */
+    title?: string;
+}
+/**
+ * A region to highlight on the plate (e.g., controls, sample areas, empty wells)
+ */
+export interface PlateRegion {
+    /** Unique identifier for the region */
+    id: string;
+    /** Display name for the region (shown in legend) */
+    name: string;
+    /**
+     * Wells included in this region using range notation.
+     * Format: "StartWell:EndWell" (e.g., "A1:B6" for a rectangular block from A1 to B6)
+     */
+    wells: string;
+    /** Border color for the region highlight */
+    borderColor?: string;
+    /** Border width in pixels (default: 2) */
+    borderWidth?: number;
+    /** Optional fill color with transparency (e.g., "rgba(255, 0, 0, 0.1)") */
+    fillColor?: string;
+}
+/**
+ * Props for PlateMap component
+ */
+export interface PlateMapProps {
+    /**
+     * Well data array as WellData objects with wellId and values.
+     *
+     * If wells have multiple values (via `values` property), layers are
+     * auto-generated for each unique key, enabling layer toggling.
+     */
+    data?: WellData[];
+    /**
+     * Configuration for auto-generated layers when using WellData with `values`.
+     * Use this to customize display names, colors, and ranges for each layer.
+     * Only used when `data` contains wells with `values` property.
+     */
+    layerConfigs?: LayerConfig[];
+    /**
+     * Initial layer ID to display when the component mounts.
+     * If not provided, defaults to the first layer.
+     */
+    initialLayerId?: string;
+    /**
+     * Optional callback notified when the active layer changes.
+     * This is purely informational - the component manages layer state internally.
+     * Use this for logging, analytics, or syncing with external state.
+     */
+    onLayerChange?: (layerId: string) => void;
+    /** Plate format preset (default: "96") */
+    plateFormat?: PlateFormat;
+    /** Number of rows for custom format (default: 8 for 96-well, 16 for 384-well) */
+    rows?: number;
+    /** Number of columns for custom format (default: 12 for 96-well, 24 for 384-well) */
+    columns?: number;
+    /**
+     * Visualization mode (default: "heatmap")
+     * - "heatmap": Display quantitative values with color gradient
+     * - "categorical": Display well types with discrete colors
+     */
+    visualizationMode?: VisualizationMode;
+    /**
+     * Custom colors for categorical visualization mode.
+     * Keys are well types, values are hex colors.
+     * Merged with DEFAULT_CATEGORY_COLORS.
+     */
+    categoryColors?: Record<string, string>;
+    /**
+     * Regions to highlight on the plate (e.g., controls, sample areas, empty wells).
+     * Each region can specify wells and styling for visual distinction.
+     */
+    regions?: PlateRegion[];
+    /** Chart title */
+    title?: string;
+    /** X-axis title (e.g., "Columns") */
+    xTitle?: string;
+    /** Y-axis title (e.g., "Rows") */
+    yTitle?: string;
+    /** Custom x-axis labels (overrides auto-generated column numbers) */
+    xLabels?: string[] | number[];
+    /** Custom y-axis labels (overrides auto-generated row letters) */
+    yLabels?: string[] | number[];
+    /** Color scale for the heatmap (only used in heatmap mode) */
+    colorScale?: ColorScale;
+    /** Minimum value for color scale (auto-calculated if not provided) */
+    valueMin?: number;
+    /** Maximum value for color scale (auto-calculated if not provided) */
+    valueMax?: number;
+    /** Color for empty/null wells (default: "#f0f0f0") */
+    emptyWellColor?: string;
+    /** Show color bar legend for heatmap mode (default: true) */
+    showColorBar?: boolean;
+    /** Show categorical legend for categorical mode (default: true) */
+    showLegend?: boolean;
+    /**
+     * Configuration for legend positioning and styling.
+     * Applies to both heatmap colorbar and categorical legend.
+     *
+     * @example
+     * // Position legend at bottom with larger text
+     * legendConfig={{ position: "bottom", fontSize: 14 }}
+     */
+    legendConfig?: LegendConfig;
+    /** Chart width in pixels (default: 800) */
+    width?: number;
+    /** Chart height in pixels (default: 500) */
+    height?: number;
+    /** Number of decimal places for values (default: 0) */
+    precision?: number;
+    /**
+     * Marker shape for wells (default: "circle")
+     * - "circle": Round markers, ideal for plate-based data
+     * - "square": Square markers, ideal for generic heatmaps
+     */
+    markerShape?: "circle" | "square";
+    /**
+     * Callback when a well/cell is clicked.
+     * @param wellData - The full well data object including wellId, values, and tooltipData
+     */
+    onWellClick?: (wellData: WellData) => void;
+}
+/**
+ * Result of converting WellData array to grids
+ */
+export interface WellDataGridResult {
+    /** 2D grid of numeric values for the active layer */
+    grid: (number | null)[][];
+    /** 2D grid of string values for categorical visualization */
+    categories: (string | null)[][];
+    /** Map of wellId -> all values (for tooltip display) */
+    allValues: Map<string, Record<string, string | number | null>>;
+    /** Map of wellId -> tooltipData */
+    tooltipData: Map<string, Record<string, unknown>>;
+}

package/dist/components/charts/PlateMap/utils.d.ts

@@ -0,0 +1,133 @@
+import { WellData, WellDataGridResult, LayerConfig, LegendPosition } from './types';
+/**
+ * Generate row labels (A, B, C, ... for 96-well; A-P for 384-well; A-AF for 1536-well)
+ * For rows beyond Z (26), uses AA, AB, AC, etc.
+ */
+export declare function generateRowLabels(count: number): string[];
+/**
+ * Generate column labels (1, 2, 3, ...)
+ */
+export declare function generateColumnLabels(count: number): number[];
+/**
+ * Parse well ID to row and column indices
+ * @param wellId - Well identifier (e.g., "A1", "H12", "P24", "AA1", "AF48")
+ * @returns { row, col } zero-indexed
+ */
+export declare function parseWellId(wellId: string): {
+    row: number;
+    col: number;
+} | null;
+/**
+ * Convert WellData array to 2D grids for a specific layer
+ */
+export declare function wellDataToGrid(wells: WellData[], rows: number, columns: number, layerId?: string): WellDataGridResult;
+/**
+ * Calculate min/max values from grid, ignoring nulls
+ */
+export declare function calculateValueRange(grid: (number | null)[][]): {
+    min: number;
+    max: number;
+};
+/**
+ * Check if WellData array contains multi-value wells (has `values` property)
+ */
+export declare function hasMultiValueWells(data: WellData[]): boolean;
+/**
+ * Extract unique layer IDs from WellData array with `values`
+ */
+export declare function extractLayerIds(data: WellData[]): string[];
+/**
+ * Check if a layer contains string values (categorical) or numeric values (heatmap)
+ */
+export declare function isStringValueLayer(data: WellData[], layerId: string): boolean;
+/**
+ * Extract layer configs from multi-value WellData array.
+ * Creates a layer entry for each unique key found in the `values` objects.
+ * Merges with user-provided layerConfigs to apply custom settings.
+ */
+export declare function extractLayers(data: WellData[], layerConfigs?: LayerConfig[]): LayerConfig[];
+/**
+ * Parse region wells from range notation like "A1:B6"
+ * Returns the bounding box coordinates for overlay rendering
+ */
+export declare function parseRegionWells(wells: string, rowLabels: readonly (string | number)[], colLabels: readonly (string | number)[]): {
+    minRow: number;
+    maxRow: number;
+    minCol: number;
+    maxCol: number;
+} | null;
+/** Options for building hover text for a well */
+export interface BuildHoverTextOptions {
+    wellId: string;
+    value: number | null;
+    allValues: Record<string, number | string | null> | undefined;
+    tooltipExtra: Record<string, unknown> | undefined;
+    activeLayerId: string | undefined;
+    layerConfigMap: Map<string, LayerConfig>;
+    precision: number;
+    valueUnit: string;
+}
+/**
+ * Builds the hover text HTML for a single well.
+ * Shows all layer values with the active layer marked.
+ */
+export declare function buildWellHoverText({ wellId, value, allValues, tooltipExtra, activeLayerId, layerConfigMap, precision, valueUnit, }: BuildHoverTextOptions): string;
+/** Colorbar configuration for a specific position */
+export interface ColorbarConfig {
+    orientation?: "h" | "v";
+    thickness: number;
+    len: number;
+    outlinewidth: number;
+    ticksuffix: string;
+    x: number;
+    xanchor: "left" | "center" | "right";
+    y: number;
+    yanchor: "top" | "middle" | "bottom";
+    title?: {
+        text: string;
+        side: "top" | "bottom" | "right";
+    };
+}
+/**
+ * Builds the colorbar configuration based on legend position.
+ */
+export declare function buildColorbarConfig(position: LegendPosition, valueUnit: string, legendTitle?: string): ColorbarConfig;
+/** Margin configuration for the plot */
+export interface PlotMargins {
+    l: number;
+    r: number;
+    b: number;
+    t: number;
+    pad: number;
+}
+/**
+ * Builds the margin configuration based on legend position and title presence.
+ */
+export declare function buildPlotMargins(position: LegendPosition, hasTitle: boolean, hasYTitle: boolean): PlotMargins;
+/**
+ * Calculates the title X position based on legend position.
+ */
+export declare function calculateTitleX(position: LegendPosition): number;
+/**
+ * Calculates the X-axis domain based on legend position.
+ */
+export declare function calculateAxisDomain(position: LegendPosition): [number, number];
+/** Data arrays for scatter plot */
+export interface ScatterPlotData {
+    xData: number[];
+    yData: string[];
+    colorData: number[];
+    textData: string[];
+}
+/**
+ * Flattens 2D grid data into arrays for scatter plot rendering.
+ */
+export declare function flattenGridData(plotZ: (number | null)[][], rowLabels: (string | number)[], hoverText: string[][], rows: number, columns: number, plotZMin: number): ScatterPlotData;
+/** Marker size calculation result */
+export interface MarkerSizeResult {
+    markerSize: number;
+}
+/**
+ * Calculates the marker size based on plot dimensions and marker shape.
+ */
+export declare function calculateMarkerSize(width: number, height: number, rows: number, columns: number, markerShape: "circle" | "square", hasTitle: boolean, hasYTitle: boolean): number;

package/dist/components/charts/ScatterPlot/ScatterPlot.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const X=require("react/jsx-runtime"),n=require("react"),Q=require("../ChartTooltip/ChartTooltip.cjs"),b=require("../plotly-loader.cjs"),V=require("../../../hooks/use-element-size.cjs"),f=require("../../../hooks/use-plotly-theme.cjs"),Z=require("../../../lib/utils.cjs"),$=require("../../../utils/colors.cjs"),D=["circle","square","diamond","triangle-up","triangle-down","star"],ee=({dataSeries:x,width:F,height:z,xRange:p,yRange:g,xTitle:C,yTitle:T,title:P="Scatter Plot",variant:E="default",markerSize:I=10})=>{const h=n.useRef(null),o=f.usePlotlyTheme(),{bindTooltip:R,tooltipElement:W}=Q.useChartTooltip({xLabel:C,yLabel:T}),[U,S]=V.useElementSize(),s=F??S.width,a=z??S.height,Y=s>0&&a>0,G=F===void 0,J=z===void 0,w=n.useRef({width:s,height:a});w.current={width:s,height:a};const _=n.useRef(!1),v=n.useRef({width:0,height:0}),k=n.useMemo(()=>Array.isArray(x)?x:[x],[x]),{xMin:q,xMax:O,yMin:H,yMax:N}=n.useMemo(()=>{let t=1/0,e=-1/0,l=1/0,r=-1/0;k.forEach(c=>{c.x.forEach(u=>{t=Math.min(t,u),e=Math.max(e,u)}),c.y.forEach(u=>{l=Math.min(l,u),r=Math.max(r,u)})});const m=(e-t)*.1,i=(r-l)*.1;return{xMin:t-m,xMax:e+m,yMin:l-i,yMax:r+i}},[k]),d=n.useMemo(()=>p||[q,O],[p,q,O]),y=n.useMemo(()=>g||[H,N],[g,H,N]),A=n.useMemo(()=>{const t=d[1]-d[0];let e=Math.pow(10,Math.floor(Math.log10(t)));t/e>10&&(e=e*2),t/e<4&&(e=e/2);const l=[];let r=Math.ceil(d[0]/e)*e;for(;r<=d[1];)l.push(r),r+=e;return l},[d]),B=n.useMemo(()=>{const t=y[1]-y[0];let e=Math.pow(10,Math.floor(Math.log10(t)));t/e>10&&(e=e*2),t/e<4&&(e=e/2);const l=[];let r=Math.ceil(y[0]/e)*e;for(;r<=y[1];)l.push(r),r+=e;return l},[y]),L=n.useMemo(()=>({tickcolor:o.tickColor,ticklen:12,tickwidth:1,ticks:"outside",tickfont:{size:16,color:o.textColor,family:f.CHART_FONT_FAMILY,weight:400},linecolor:o.lineColor,linewidth:1,position:0,zeroline:!1}),[o]);return n.useEffect(()=>{if(!h.current||!Y)return;const t=k.map((i,c)=>({x:i.x,y:i.y,type:"scatter",mode:"markers",name:i.name,marker:{color:$.seriesColor(c,i.color),size:i.size??I,symbol:i.symbol??(E==="stacked"?D[c%D.length]:"circle"),line:{color:o.paperBg,width:1}},hoverinfo:"none"})),e={title:{text:P,font:{size:32,family:f.CHART_FONT_FAMILY,color:o.textColor}},width:w.current.width,height:w.current.height,margin:{l:80,r:30,b:96,t:60,pad:10},paper_bgcolor:o.paperBg,plot_bgcolor:o.plotBg,font:{family:f.CHART_FONT_FAMILY},dragmode:!1,xaxis:{title:{text:C,font:{size:16,color:o.textSecondary,family:f.CHART_FONT_FAMILY,weight:400},standoff:32},gridcolor:o.gridColor,range:p,autorange:!p,tickmode:"array",tickvals:A,ticktext:A.map(String),showgrid:!0,automargin:!0,...L},yaxis:{title:{text:T,font:{size:16,color:o.textSecondary,family:f.CHART_FONT_FAMILY,weight:400},standoff:30},gridcolor:o.gridColor,range:g,autorange:!g,tickmode:"array",tickvals:B,showgrid:!0,automargin:!0,...L},legend:{x:.5,y:0,xanchor:"center",yanchor:"bottom",yref:"container",orientation:"h",font:{size:16,color:o.legendColor,family:f.CHART_FONT_FAMILY,weight:500}},showlegend:!0,hovermode:"closest"},l={responsive:!1,displayModeBar:!1,displaylogo:!1};let r=!1,m=null;return b.loadPlotly().then(i=>{if(r||!h.current)return;i.newPlot(h.current,t,e,l),R(h.current);const c=h.current;m=c,_.current=!0,v.current={...w.current};const u=c,j={color:o.spikeColor,width:2};u.on("plotly_hover",K=>{const M=K.points[0];M&&i.relayout(c,{shapes:[{type:"line",xref:"x",yref:"paper",x0:M.x,x1:M.x,y0:0,y1:1,line:j,layer:"below"},{type:"line",xref:"paper",yref:"y",x0:0,x1:1,y0:M.y,y1:M.y,line:j,layer:"below"}]})}),u.on("plotly_unhover",()=>{i.relayout(c,{shapes:[]})})}),()=>{r=!0,m&&(b.getLoadedPlotly().purge(m),_.current=!1)}},[k,Y,p,g,C,T,P,E,I,d,y,A,B,L,o,R]),n.useEffect(()=>{const t=h.current;!t||!_.current||s<=0||a<=0||v.current.width===s&&v.current.height===a||(v.current={width:s,height:a},b.getLoadedPlotly().relayout(t,{width:s,height:a}).catch(()=>{}))},[s,a]),X.jsxs("div",{ref:U,className:Z.cn("relative",G&&"w-full",J&&"h-full"),children:[X.jsx("div",{ref:h,style:{width:"100%",height:"100%"}}),W]})};exports.ScatterPlot=ee;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const X=require("react/jsx-runtime"),n=require("react"),Q=require("../ChartTooltip/ChartTooltip.cjs"),b=require("../plotly-loader.cjs"),V=require("../../../hooks/use-element-size.cjs"),f=require("../../../hooks/use-plotly-theme.cjs"),Z=require("../../../lib/utils.cjs"),$=require("../../../utils/colors.cjs"),D=["circle","square","diamond","triangle-up","triangle-down","star"],ee=({dataSeries:x,width:F,height:z,xRange:p,yRange:g,xTitle:_,yTitle:C,title:P="Scatter Plot",variant:E="default",markerSize:I=10})=>{const h=n.useRef(null),o=f.usePlotlyTheme(),{bindTooltip:R,tooltipElement:W}=Q.useChartTooltip({xLabel:_,yLabel:C}),[U,S]=V.useElementSize(),s=F??S.width,a=z??S.height,Y=s>0&&a>0,G=F===void 0,J=z===void 0,w=n.useRef({width:s,height:a});w.current={width:s,height:a};const T=n.useRef(!1),v=n.useRef({width:0,height:0}),k=n.useMemo(()=>Array.isArray(x)?x:[x],[x]),{xMin:q,xMax:O,yMin:H,yMax:N}=n.useMemo(()=>{let t=1/0,e=-1/0,l=1/0,r=-1/0;k.forEach(c=>{c.x.forEach(u=>{t=Math.min(t,u),e=Math.max(e,u)}),c.y.forEach(u=>{l=Math.min(l,u),r=Math.max(r,u)})});const m=(e-t)*.1,i=(r-l)*.1;return{xMin:t-m,xMax:e+m,yMin:l-i,yMax:r+i}},[k]),d=n.useMemo(()=>p||[q,O],[p,q,O]),y=n.useMemo(()=>g||[H,N],[g,H,N]),A=n.useMemo(()=>{const t=d[1]-d[0];let e=Math.pow(10,Math.floor(Math.log10(t)));t/e>10&&(e=e*2),t/e<4&&(e=e/2);const l=[];let r=Math.ceil(d[0]/e)*e;for(;r<=d[1];)l.push(r),r+=e;return l},[d]),B=n.useMemo(()=>{const t=y[1]-y[0];let e=Math.pow(10,Math.floor(Math.log10(t)));t/e>10&&(e=e*2),t/e<4&&(e=e/2);const l=[];let r=Math.ceil(y[0]/e)*e;for(;r<=y[1];)l.push(r),r+=e;return l},[y]),L=n.useMemo(()=>({tickcolor:o.tickColor,ticklen:12,tickwidth:1,ticks:"outside",tickfont:{size:16,color:o.textColor,family:f.CHART_FONT_FAMILY,weight:400},linecolor:o.lineColor,linewidth:1,position:0,zeroline:!1}),[o]);return n.useEffect(()=>{if(!h.current||!Y)return;const t=k.map((i,c)=>({x:i.x,y:i.y,type:"scatter",mode:"markers",name:i.name,marker:{color:$.seriesColor(c,i.color),size:i.size??I,symbol:i.symbol??(E==="stacked"?D[c%D.length]:"circle"),line:{color:o.paperBg,width:1}},hoverinfo:"none"})),e={title:{text:P,font:{size:32,family:f.CHART_FONT_FAMILY,color:o.textColor}},width:w.current.width,height:w.current.height,margin:{l:80,r:30,b:96,t:60,pad:10},paper_bgcolor:o.paperBg,plot_bgcolor:o.plotBg,font:{family:f.CHART_FONT_FAMILY},dragmode:!1,xaxis:{title:{text:_,font:{size:16,color:o.textSecondary,family:f.CHART_FONT_FAMILY,weight:400},standoff:32},gridcolor:o.gridColor,range:p,autorange:!p,tickmode:"array",tickvals:A,ticktext:A.map(String),showgrid:!0,automargin:!0,...L},yaxis:{title:{text:C,font:{size:16,color:o.textSecondary,family:f.CHART_FONT_FAMILY,weight:400},standoff:30},gridcolor:o.gridColor,range:g,autorange:!g,tickmode:"array",tickvals:B,showgrid:!0,automargin:!0,...L},legend:{x:.5,y:0,xanchor:"center",yanchor:"bottom",yref:"container",orientation:"h",font:{size:16,color:o.legendColor,family:f.CHART_FONT_FAMILY,weight:500}},showlegend:!0,hovermode:"closest"},l={responsive:!1,displayModeBar:!1,displaylogo:!1};let r=!1,m=null;return b.loadPlotly().then(i=>{if(r||!h.current)return;i.newPlot(h.current,t,e,l),R(h.current);const c=h.current;m=c,T.current=!0,v.current={...w.current};const u=c,j={color:o.spikeColor,width:2};u.on("plotly_hover",K=>{const M=K.points[0];M&&i.relayout(c,{shapes:[{type:"line",xref:"x",yref:"paper",x0:M.x,x1:M.x,y0:0,y1:1,line:j,layer:"below"},{type:"line",xref:"paper",yref:"y",x0:0,x1:1,y0:M.y,y1:M.y,line:j,layer:"below"}]})}),u.on("plotly_unhover",()=>{i.relayout(c,{shapes:[]})})}),()=>{r=!0,m&&(b.getLoadedPlotly().purge(m),T.current=!1)}},[k,Y,p,g,_,C,P,E,I,d,y,A,B,L,o,R]),n.useEffect(()=>{const t=h.current;!t||!T.current||s<=0||a<=0||v.current.width===s&&v.current.height===a||(v.current={width:s,height:a},b.getLoadedPlotly().relayout(t,{width:s,height:a}).catch(()=>{}))},[s,a]),X.jsxs("div",{ref:U,className:Z.cn("relative",G&&"w-full",J&&"h-full"),children:[X.jsx("div",{ref:h,style:{width:"100%",height:"100%"}}),W]})};exports.ScatterPlot=ee;
 //# sourceMappingURL=ScatterPlot.cjs.map

package/dist/components/charts/ScatterPlot/ScatterPlot.d.ts

@@ -0,0 +1,43 @@
+import { default as React } from 'react';
+type MarkerSymbol = "circle" | "square" | "diamond" | "triangle-up" | "triangle-down" | "star";
+interface ScatterPlotDataSeries {
+    x: number[];
+    y: number[];
+    name: string;
+    /** Optional color override (auto-assigned from CHART_COLORS if not provided) */
+    color?: string;
+    /** Optional marker symbol override (auto-assigned in the `stacked` variant) */
+    symbol?: MarkerSymbol;
+    /** Optional per-series marker size override (falls back to `markerSize`) */
+    size?: number;
+}
+type ScatterPlotVariant = "default" | "stacked";
+interface ScatterPlotProps {
+    /** One or more data series to plot */
+    dataSeries: ScatterPlotDataSeries | ScatterPlotDataSeries[];
+    /**
+     * 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];
+    xTitle?: string;
+    yTitle?: string;
+    title?: string;
+    /**
+     * `default` renders every series as circles; `stacked` cycles through
+     * distinct marker symbols per series so overlapping series stay legible.
+     */
+    variant?: ScatterPlotVariant;
+    /** Default marker size in pixels (per-series `size` takes precedence) */
+    markerSize?: number;
+}
+declare const ScatterPlot: React.FC<ScatterPlotProps>;
+export { ScatterPlot };
+export type { MarkerSymbol, ScatterPlotDataSeries, ScatterPlotProps, ScatterPlotVariant, };

package/dist/components/charts/ScatterPlot/index.d.ts

@@ -0,0 +1,2 @@
+export { ScatterPlot } from './ScatterPlot';
+export type { ScatterPlotDataSeries, ScatterPlotProps, ScatterPlotVariant, } from './ScatterPlot';

package/dist/components/charts/ScatterPlotInteractive/ScatterPlotInteractive.d.ts

@@ -0,0 +1,25 @@
+import { default as React } from 'react';
+import { ScatterPlotInteractiveProps } from './types';
+/**
+ * ScatterPlotInteractive component for visualizing scatter plot data with advanced interactions.
+ *
+ * **Features:**
+ * - Data-driven and static styling (color, shape, size)
+ * - Interactive selection (click, box, lasso)
+ * - Keyboard modifiers for click-selection modes (Shift/Ctrl)
+ * - Customizable tooltips with rich content support
+ * - Axis customization (ranges, log/linear scales)
+ * - Performance optimizations for large datasets
+ * - Selection propagation via callbacks
+ *
+ * **Selection Modes (click selection only):**
+ * - Default click: Replace selection
+ * - Shift + click: Add to selection
+ * - Ctrl/Cmd + click: Remove from selection
+ * - Shift + Ctrl + click: Toggle selection
+ *
+ * Box/lasso selection always replaces the current selection because
+ * Plotly does not expose the original keyboard event for drag operations.
+ */
+declare const ScatterPlotInteractive: React.FC<ScatterPlotInteractiveProps>;
+export { ScatterPlotInteractive };

package/dist/components/charts/ScatterPlotInteractive/constants.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Default colors for the scatter plot. Background, grid, and axis colors
+ * come from the active theme via `usePlotlyTheme`.
+ */
+export declare const COLORS: {
+    primary: string;
+    selected: string;
+};
+/**
+ * Default color scale for continuous color mapping (CVD-friendly diverging ramp)
+ */
+export declare const DEFAULT_COLOR_SCALE: Array<[number, string]>;
+/**
+ * Default category colors (cycle through these)
+ */
+export declare const DEFAULT_CATEGORY_COLORS: readonly [string, string, string, string, string, string, string, string, string, string, string, string];
+/**
+ * Default sizes
+ */
+export declare const DEFAULT_MARKER_SIZE = 8;
+export declare const DEFAULT_SIZE_RANGE: [number, number];
+/**
+ * Default downsampling configuration
+ */
+export declare const DEFAULT_MAX_POINTS = 5000;
+/**
+ * Constants for plot layout
+ */
+export declare const PLOT_CONSTANTS: {
+    MARGIN_LEFT: number;
+    MARGIN_RIGHT: number;
+    MARGIN_TOP: number;
+    MARGIN_BOTTOM: number;
+    TITLE_FONT_SIZE: number;
+    AXIS_TITLE_FONT_SIZE: number;
+    AXIS_TICK_FONT_SIZE: number;
+    LEGEND_FONT_SIZE: number;
+    FONT_FAMILY: string;
+    GRID_WIDTH: number;
+    AXIS_LINE_WIDTH: number;
+    AUTO_RANGE_PADDING: number;
+};
+/**
+ * Selection mode keyboard modifiers
+ */
+export declare const SELECTION_MODIFIERS: {
+    readonly ADD: "shiftKey";
+    readonly REMOVE: "ctrlKey";
+    readonly TOGGLE: "both";
+};

package/dist/components/charts/ScatterPlotInteractive/index.d.ts

@@ -0,0 +1,3 @@
+export { ScatterPlotInteractive } from './ScatterPlotInteractive';
+export * from './types';
+export * from './constants';