semiotic 3.0.0-beta.7 → 3.0.1

package/ai/system-prompt.md

@@ -8,6 +8,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **StackedAreaChart** — `xAccessor`, `yAccessor`, `areaBy` (required), `normalize`
 - **Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`
 - **BubbleChart** — `xAccessor`, `yAccessor`, **`sizeBy`** (required), `sizeRange`
+- **ConnectedScatterplot** — `xAccessor`, `yAccessor`, `orderAccessor` (sequencing field), `pointRadius`
 - **Heatmap** — `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme` ("blues"|"reds"|"greens"|"viridis")
 - **BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `sort`
 - **StackedBarChart** — `categoryAccessor`, `valueAccessor`, **`stackBy`** (required), `normalize`
@@ -24,6 +25,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **TreeDiagram** — `childrenAccessor`, `nodeIdAccessor`, `layout` ("tree"|"cluster"|"partition"), `orientation`
 - **Treemap** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
 - **CirclePack** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
+- **OrbitDiagram** — `childrenAccessor`, `nodeIdAccessor`, `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`
 
 ## Network Data (`nodes: object[]`, `edges: object[]`)
 - **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`
@@ -35,6 +37,7 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **RealtimeHistogram** — **`binSize`** (required), `timeAccessor`, `valueAccessor`
 - **RealtimeSwarmChart** — `timeAccessor`, `valueAccessor`, `categoryAccessor`
 - **RealtimeWaterfallChart** — `timeAccessor`, `valueAccessor`, `positiveColor`, `negativeColor`
+- **RealtimeHeatmap** — `timeAccessor`, `valueAccessor`, `heatmapXBins`, `heatmapYBins`, `aggregation`
 - **StreamNetworkFrame** (`chartType="sankey"`) — `ref.current.push({ source, target, value })`, `sourceAccessor`, `targetAccessor`, `valueAccessor` (import from `semiotic`)
 
 ## Common Props (all components)

package/dist/{ChartGrid.d.ts → components/ChartGrid.d.ts}

@@ -1,4 +1,5 @@
 import * as React from "react";
+export type ChartEmphasis = "primary" | "secondary";
 export interface ChartGridProps {
     /** Chart components to arrange in the grid */
     children: React.ReactNode;
@@ -20,15 +21,16 @@ export interface ChartGridProps {
  * Each cell automatically gets `responsiveWidth` behavior since the grid
  * manages the cell dimensions.
  *
- * Works naturally with `LinkedCharts` for coordinated views:
+ * Children can set `emphasis="primary"` to span two columns and receive
+ * higher visual weight, following the F-pattern reading layout recommended
+ * by Carbon Design guidelines.
  *
  * ```tsx
- * <LinkedCharts>
- *   <ChartGrid columns={2}>
- *     <LineChart data={d} xAccessor="x" yAccessor="y" responsiveWidth />
- *     <BarChart data={d} categoryAccessor="cat" valueAccessor="val" responsiveWidth />
- *   </ChartGrid>
- * </LinkedCharts>
+ * <ChartGrid columns={2}>
+ *   <LineChart data={d} emphasis="primary" responsiveWidth />
+ *   <BarChart data={d} responsiveWidth />
+ *   <ScatterChart data={d} responsiveWidth />
+ * </ChartGrid>
  * ```
  */
 export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;

package/dist/{LinkedCharts.d.ts → components/LinkedCharts.d.ts}

@@ -1,15 +1,48 @@
 import * as React from "react";
 import type { ResolutionMode } from "./store/SelectionStore";
+type LegendInteractionMode = "highlight" | "isolate" | "none";
 export { useSelection, useLinkedHover, useBrushSelection, useFilteredData } from "./store/useSelection";
 export type { UseSelectionOptions, UseSelectionResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./store/useSelection";
 export { useChartObserver } from "./store/useObservation";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./store/useObservation";
+/** Hook: returns true when a parent LinkedCharts is handling the legend. */
+export declare function useLinkedLegendSuppression(): boolean;
 export interface LinkedChartsProps {
     children: React.ReactNode;
     /** Pre-configure selections with resolution modes */
     selections?: Record<string, {
         resolution?: ResolutionMode;
     }>;
+    /**
+     * Show a unified legend for all linked charts.
+     * When true, child chart legends are automatically suppressed unless explicitly set.
+     * @default true (when a CategoryColorProvider is present)
+     */
+    showLegend?: boolean;
+    /**
+     * Position of the unified legend.
+     * @default "top"
+     */
+    legendPosition?: "top" | "bottom";
+    /**
+     * Legend interaction mode for the unified legend.
+     * - "highlight": hover dims non-hovered categories across all linked charts
+     * - "isolate": click toggles category visibility across all linked charts
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
+    /**
+     * Selection name that the unified legend produces on.
+     * Child charts must use the same name in their `selection` prop to respond.
+     * @default "legend"
+     */
+    legendSelectionName?: string;
+    /**
+     * Field name that the unified legend uses for cross-chart highlighting.
+     * This must match the field used in child charts' `linkedHover.fields` / `colorBy`.
+     * @default first field from the first child's linkedHover config, or "category"
+     */
+    legendField?: string;
 }
 /**
  * LinkedCharts — context provider for coordinated chart views.
@@ -41,4 +74,4 @@ export interface LinkedChartsProps {
  * </LinkedCharts>
  * ```
  */
-export declare function LinkedCharts({ children, selections }: LinkedChartsProps): React.JSX.Element;
+export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): React.JSX.Element;

package/dist/{Tooltip → components/Tooltip}/Tooltip.d.ts

@@ -136,6 +136,13 @@ export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data
  */
 export type TooltipProp = boolean | ((data: Record<string, unknown>) => React.ReactNode) | ReturnType<typeof Tooltip> | ReturnType<typeof MultiLineTooltip> | TooltipConfig;
 /**
- * Convert a tooltip prop to the format Semiotic expects
+ * The function signature that Stream Frames expect for tooltipContent.
+ * Compatible with HoverData and any Record-based hover object.
  */
-export declare function normalizeTooltip(tooltip: TooltipProp): boolean | Function;
+export type TooltipContentFn = (d: Record<string, any>) => React.ReactNode;
+/**
+ * Convert a tooltip prop to the format Semiotic expects.
+ * Returns `false` to disable, or a `TooltipContentFn` compatible with
+ * all Stream Frame `tooltipContent` signatures.
+ */
+export declare function normalizeTooltip(tooltip: TooltipProp | undefined): false | TooltipContentFn;

package/dist/{charts → components/charts}/index.d.ts

@@ -58,6 +58,8 @@ export { Treemap } from "./network/Treemap";
 export type { TreemapProps } from "./network/Treemap";
 export { CirclePack } from "./network/CirclePack";
 export type { CirclePackProps } from "./network/CirclePack";
+export { OrbitDiagram } from "./network/OrbitDiagram";
+export type { OrbitDiagramProps, OrbitNode } from "./network/OrbitDiagram";
 export { RealtimeLineChart } from "./realtime/RealtimeLineChart";
 export type { RealtimeLineChartProps } from "./realtime/RealtimeLineChart";
 export { RealtimeTemporalHistogram, RealtimeHistogram } from "./realtime/RealtimeHistogram";

package/dist/{charts → components/charts}/network/ChordDiagram.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * ChordDiagram component props
  */
@@ -21,6 +22,7 @@ export interface ChordDiagramProps<TNode extends Record<string, any> = Record<st
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;
+    legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;

package/dist/{charts → components/charts}/network/CirclePack.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor, Accessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * CirclePack component props
  */
@@ -18,6 +19,7 @@ export interface CirclePackProps<TNode extends Record<string, any> = Record<stri
     circleOpacity?: number;
     padding?: number;
     enableHover?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;
 }

package/dist/{charts → components/charts}/network/ForceDirectedGraph.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * ForceDirectedGraph component props
  */
@@ -24,6 +25,7 @@ export interface ForceDirectedGraphProps<TNode extends Record<string, any> = Rec
     showLabels?: boolean;
     enableHover?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "size">>;
 }

package/dist/components/charts/network/OrbitDiagram.d.ts

@@ -0,0 +1,78 @@
+import * as React from "react";
+import type { BaseChartProps } from "../shared/types";
+export interface OrbitNode {
+    datum: any;
+    x: number;
+    y: number;
+    ring: number;
+    angle: number;
+    depth: number;
+    parent?: OrbitNode;
+    children?: OrbitNode[];
+    id?: string;
+}
+type OrbitMode = "flat" | "solar" | "atomic" | number[];
+export interface OrbitDiagramProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /** Hierarchical data — single root object with children */
+    data: TDatum;
+    /** How to access children from each datum @default "children" */
+    childrenAccessor?: string | ((d: TDatum) => TDatum[] | null | undefined);
+    /** How to identify each node @default "name" */
+    nodeIdAccessor?: string | ((d: any) => string);
+    /** Field or function for node color */
+    colorBy?: string | ((d: any) => string);
+    /** Color scheme @default "category10" */
+    colorScheme?: string | string[];
+    /** Color by hierarchy depth instead of field @default false */
+    colorByDepth?: boolean;
+    /**
+     * Ring arrangement mode:
+     * - "flat": all children in one ring
+     * - "solar": one child per ring
+     * - "atomic": [2, 8] electron shell pattern
+     * - number[]: custom ring capacities (last value repeats)
+     * @default "flat"
+     */
+    orbitMode?: OrbitMode;
+    /** Ring size divisor per depth. Larger = tighter orbits. @default 2.95 */
+    orbitSize?: number | ((node: OrbitNode) => number);
+    /** Orbit speed in degrees per frame @default 0.25 */
+    speed?: number;
+    /** Per-node speed modifier @default (node) => 1 / (node.depth + 1) */
+    revolution?: (node: OrbitNode) => number;
+    /** Vertical squash for elliptical orbits. 1 = circle, 0.5 = ellipse @default 1 */
+    eccentricity?: number | ((node: OrbitNode) => number);
+    /** Show orbital ring paths @default true */
+    showRings?: boolean;
+    /** Node radius. Number or function of node. @default 6 */
+    nodeRadius?: number | ((node: OrbitNode) => number);
+    /** Show node labels @default false */
+    showLabels?: boolean;
+    /** Enable animation @default true */
+    animated?: boolean;
+    /** Tooltip configuration */
+    tooltip?: (node: OrbitNode) => React.ReactNode;
+    /** Enable hover @default true */
+    enableHover?: boolean;
+    /** Annotation objects. Supports type: "widget" with content (ReactNode) anchored to a node by nodeId. */
+    annotations?: Array<{
+        type: string;
+        nodeId?: string;
+        dx?: number;
+        dy?: number;
+        width?: number;
+        height?: number;
+        content?: React.ReactNode;
+        label?: string;
+        [key: string]: any;
+    }>;
+    /** Additional SVG content */
+    foregroundGraphics?: React.ReactNode;
+    /** Frame props passthrough (unused, for API consistency) */
+    frameProps?: Record<string, any>;
+}
+export declare function OrbitDiagram<TDatum extends Record<string, any> = Record<string, any>>(props: OrbitDiagramProps<TDatum>): React.JSX.Element;
+export declare namespace OrbitDiagram {
+    var displayName: string;
+}
+export {};

package/dist/{charts → components/charts}/network/SankeyDiagram.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * SankeyDiagram component props
  */
@@ -22,6 +23,7 @@ export interface SankeyDiagramProps<TNode extends Record<string, any> = Record<s
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;
+    legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
     edgeSort?: (a: any, b: any) => number;
     tooltip?: TooltipProp;

package/dist/{charts → components/charts}/network/TreeDiagram.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor, Accessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * TreeDiagram component props
  */
@@ -20,6 +21,7 @@ export interface TreeDiagramProps<TNode extends Record<string, any> = Record<str
     showLabels?: boolean;
     nodeSize?: number;
     enableHover?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;
 }

package/dist/{charts → components/charts}/network/Treemap.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps, ChartAccessor, Accessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * Treemap component props
  */
@@ -19,6 +20,7 @@ export interface TreemapProps<TNode extends Record<string, any> = Record<string,
     padding?: number;
     paddingTop?: number;
     enableHover?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;
 }

package/dist/{charts → components/charts}/ordinal/BarChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -20,6 +21,7 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/BoxPlot.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface BoxPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -18,6 +19,7 @@ export interface BoxPlotProps<TDatum extends Record<string, any> = Record<string
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/DonutChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface DonutChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -14,6 +15,7 @@ export interface DonutChartProps<TDatum extends Record<string, any> = Record<str
     slicePadding?: number;
     enableHover?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/DotPlot.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface DotPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -18,6 +19,7 @@ export interface DotPlotProps<TDatum extends Record<string, any> = Record<string
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/GroupedBarChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface GroupedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -17,6 +18,7 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/PieChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface PieChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -12,6 +13,7 @@ export interface PieChartProps<TDatum extends Record<string, any> = Record<strin
     slicePadding?: number;
     enableHover?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/StackedBarChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface StackedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -18,6 +19,7 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/{charts → components/charts}/ordinal/SwarmPlot.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -20,6 +21,7 @@ export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<stri
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;

package/dist/components/charts/shared/diagnoseConfig.d.ts

@@ -0,0 +1,23 @@
+/**
+ * diagnoseConfig — anti-pattern detector for Semiotic chart configurations.
+ *
+ * Catches common failure modes that produce blank charts or runtime errors,
+ * returning actionable fix instructions for each issue found.
+ */
+export interface Diagnosis {
+    severity: "error" | "warning";
+    code: string;
+    message: string;
+    fix: string;
+}
+export interface DiagnosisResult {
+    ok: boolean;
+    diagnoses: Diagnosis[];
+}
+/**
+ * Run anti-pattern diagnostics on a Semiotic chart configuration.
+ *
+ * Returns actionable diagnoses with severity, code, message, and fix instruction.
+ * Runs validateProps internally — validation errors are included as diagnoses.
+ */
+export declare function diagnoseConfig(componentName: string, props: Record<string, any>): DiagnosisResult;

package/dist/{charts → components/charts}/shared/hooks.d.ts

@@ -16,7 +16,7 @@ export declare function resolveAccessor<T = any>(accessor: string | ((d: Record<
  * Hook to create a color scale from data and colorBy configuration.
  * Returns undefined when colorBy is absent or is a function accessor.
  */
-export declare function useColorScale(data: Array<Record<string, any>>, colorBy: Accessor<string> | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Record<string, any>>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
@@ -69,6 +69,28 @@ export declare function useChartLegendAndMargin({ data, colorBy, colorScale, sho
         right: number;
     };
 };
+export type LegendInteractionMode = "highlight" | "isolate" | "none";
+export interface LegendInteractionState {
+    highlightedCategory: string | null;
+    isolatedCategories: Set<string>;
+    onLegendHover: (item: {
+        label: string;
+    } | null) => void;
+    onLegendClick: (item: {
+        label: string;
+    }) => void;
+    /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
+    legendSelectionHook: {
+        isActive: boolean;
+        predicate: (d: Record<string, any>) => boolean;
+    } | null;
+}
+/**
+ * Hook managing legend highlight/isolate interaction.
+ * - "highlight": hover over legend item dims everything else to 30% opacity
+ * - "isolate": click toggles category visibility; click all to reset
+ */
+export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: any) => string) | undefined, allCategories: string[]): LegendInteractionState;
 interface ChartModeInput {
     width?: number;
     height?: number;

package/dist/components/charts/shared/stringDistance.d.ts

@@ -0,0 +1,11 @@
+/**
+ * String distance utilities for typo detection and field suggestions.
+ * Shared by validateProps and validateChartData.
+ */
+/** Levenshtein edit distance between two strings. */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Find the closest match from candidates by Levenshtein distance.
+ * Returns the match if distance <= maxDist, otherwise null/undefined.
+ */
+export declare function closestMatch(input: string, candidates: string[], maxDist?: number): string | undefined;

package/dist/{charts → components/charts}/shared/tooltipUtils.d.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 import type { HoverData } from "../../realtime/types";
 export interface TooltipFieldConfig {
     label: string;
-    accessor: string | ((d: Record<string, any>) => any);
+    accessor: string | ((d: any) => any);
     role?: "x" | "y" | "color" | "size" | "group" | "value";
 }
 /**

package/dist/{charts → components/charts}/shared/types.d.ts

@@ -69,6 +69,12 @@ export interface BaseChartProps {
     onObservation?: OnObservationCallback;
     /** Identifier for this chart instance, included in observation events */
     chartId?: string;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: React.ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
 }
 /**
  * Axis configuration props

package/dist/{charts → components/charts}/shared/withChartWrapper.d.ts

@@ -11,6 +11,16 @@ interface SafeRenderProps {
  * with the component name and error message instead of crashing the page.
  */
 export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): React.JSX.Element;
+/**
+ * Renders a "No data available" placeholder when data is empty.
+ * Returns null when data is present or emptyContent is `false`.
+ */
+export declare function renderEmptyState(data: any[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
+/**
+ * Renders a shimmer/skeleton loading placeholder.
+ * Returns null when loading is false.
+ */
+export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number): React.ReactElement | null;
 /** Warn if a string accessor isn't found in the first data element */
 export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
 /** Warn if data looks like the wrong shape for this chart type */

package/dist/{charts → components/charts}/xy/AreaChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -110,6 +111,13 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      * @default true (when multiple areas)
      */
     showLegend?: boolean;
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
     /**
      * Tooltip configuration
      */

package/dist/{charts → components/charts}/xy/BubbleChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamXYFrameProps, MarginalGraphicsConfig } from "../../stream/types";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -92,6 +93,13 @@ export interface BubbleChartProps<TDatum extends Record<string, any> = Record<st
     marginalGraphics?: MarginalGraphicsConfig;
     /** Accessor for unique point IDs, used by point-anchored annotations */
     pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
     /**
      * Annotation objects to render on the chart
      */

package/dist/{charts → components/charts}/xy/ConnectedScatterplot.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * ConnectedScatterplot component props
  */
@@ -30,6 +31,8 @@ export interface ConnectedScatterplotProps<TDatum extends Record<string, any> =
     tooltip?: TooltipProp;
     /** Accessor for unique point IDs, used by point-anchored annotations */
     pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
     /** Annotation objects to render on the chart */
     annotations?: Record<string, any>[];
     /** Additional StreamXYFrame props for advanced customization */

package/dist/{charts → components/charts}/xy/Heatmap.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -86,6 +87,13 @@ export interface HeatmapProps<TDatum extends Record<string, any> = Record<string
      * Tooltip configuration
      */
     tooltip?: TooltipProp;
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
     /**
      * Annotation objects to render on the chart
      */