semiotic 3.0.0 → 3.1.0

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -294,6 +294,57 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "QuadrantChart",
+        "description": "Scatterplot divided into four labeled, colored quadrants by center lines. Use for BCG matrices, priority matrices, and any 2x2 strategic framework.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Array of data objects"
+            },
+            "xAccessor": { "type": "string", "default": "x" },
+            "yAccessor": { "type": "string", "default": "y" },
+            "xCenter": { "type": "number", "description": "X-coordinate of the vertical center line. Defaults to midpoint of x domain." },
+            "yCenter": { "type": "number", "description": "Y-coordinate of the horizontal center line. Defaults to midpoint of y domain." },
+            "quadrants": {
+              "type": "object",
+              "description": "Configuration for the four quadrants: { topRight, topLeft, bottomRight, bottomLeft }, each with { label, color, opacity? }",
+              "properties": {
+                "topRight": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] },
+                "topLeft": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] },
+                "bottomRight": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] },
+                "bottomLeft": { "type": "object", "properties": { "label": { "type": "string" }, "color": { "type": "string" }, "opacity": { "type": "number" } }, "required": ["label", "color"] }
+              },
+              "required": ["topRight", "topLeft", "bottomRight", "bottomLeft"]
+            },
+            "showQuadrantLabels": { "type": "boolean", "default": true },
+            "quadrantLabelSize": { "type": "number", "default": 12 },
+            "colorBy": { "type": "string", "description": "Key to determine point color" },
+            "colorScheme": { "type": ["string", "array"], "default": "category10" },
+            "sizeBy": { "type": "string", "description": "Key for variable point sizing" },
+            "sizeRange": { "type": "array", "items": { "type": "number" }, "default": [3, 15] },
+            "pointRadius": { "type": "number", "default": 5 },
+            "pointOpacity": { "type": "number", "default": 0.8 },
+            "xLabel": { "type": "string" },
+            "yLabel": { "type": "string" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 400 },
+            "enableHover": { "type": "boolean", "default": true },
+            "showLegend": { "type": "boolean" },
+            "showGrid": { "type": "boolean", "default": false },
+            "margin": { "type": "object" },
+            "className": { "type": "string" }
+          },
+          "required": ["quadrants"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {
@@ -377,6 +428,51 @@
             "height": { "type": "number", "default": 400 },
             "enableHover": { "type": "boolean", "default": true },
             "margin": { "type": "object" },
+            "className": { "type": "string" },
+            "showLegend": {
+              "type": "boolean",
+              "description": "Show a gradient color legend",
+              "default": false
+            },
+            "legendPosition": {
+              "type": "string",
+              "enum": ["right", "left", "top", "bottom"],
+              "description": "Position of the gradient legend",
+              "default": "right"
+            }
+          },
+          "required": ["data"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "ConnectedScatterplot",
+        "description": "Scatterplot where points are connected in order, showing trajectories through 2D space. Viridis-colored start→end, white halo under lines.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Array of data objects"
+            },
+            "xAccessor": { "type": "string", "description": "Key for x-axis values", "default": "x" },
+            "yAccessor": { "type": "string", "description": "Key for y-axis values", "default": "y" },
+            "orderAccessor": { "type": "string", "description": "Key for point ordering (number or Date field)" },
+            "orderLabel": { "type": "string", "description": "Label for the ordering metric in tooltips" },
+            "pointRadius": { "type": "number", "description": "Point radius", "default": 4 },
+            "pointIdAccessor": { "type": "string", "description": "Accessor for unique point IDs, used by point-anchored annotations" },
+            "annotations": { "type": "array", "description": "Annotation objects to render on the chart" },
+            "colorBy": { "type": "string", "description": "Key to determine color encoding" },
+            "colorScheme": { "type": ["string", "array"], "description": "Named d3 color scheme or array of color strings" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 400 },
+            "enableHover": { "type": "boolean", "default": true },
+            "showGrid": { "type": "boolean", "default": false },
+            "margin": { "type": "object" },
             "className": { "type": "string" }
           },
           "required": ["data"]
@@ -1126,6 +1222,43 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "OrbitDiagram",
+        "description": "Animated orbital diagram showing hierarchical data as nodes orbiting a center. Supports flat, solar, atomic, and custom ring arrangements.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "object",
+              "description": "Hierarchical root object with children: { name: 'root', children: [...] }"
+            },
+            "childrenAccessor": { "type": "string", "description": "Key to access children from each datum", "default": "children" },
+            "nodeIdAccessor": { "type": "string", "description": "Key to identify each node", "default": "name" },
+            "colorBy": { "type": "string", "description": "Field or function for node color" },
+            "colorScheme": { "type": ["string", "array"], "description": "Color scheme", "default": "category10" },
+            "colorByDepth": { "type": "boolean", "description": "Color by hierarchy depth", "default": false },
+            "orbitMode": { "type": ["string", "array"], "description": "Ring arrangement: 'flat', 'solar', 'atomic', or number[]", "default": "flat" },
+            "orbitSize": { "type": "number", "description": "Ring size divisor per depth", "default": 2.95 },
+            "speed": { "type": "number", "description": "Orbit speed in degrees per frame", "default": 0.25 },
+            "eccentricity": { "type": "number", "description": "Vertical squash for elliptical orbits (1 = circle)", "default": 1 },
+            "showRings": { "type": "boolean", "description": "Show orbital ring paths", "default": true },
+            "nodeRadius": { "type": "number", "description": "Node radius", "default": 6 },
+            "showLabels": { "type": "boolean", "description": "Show node labels", "default": false },
+            "animated": { "type": "boolean", "description": "Enable animation", "default": true },
+            "annotations": { "type": "array", "description": "Annotations anchored by nodeId" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 600 },
+            "enableHover": { "type": "boolean", "default": true },
+            "margin": { "type": "object" },
+            "className": { "type": "string" }
+          },
+          "required": ["data"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {

package/ai/system-prompt.md

@@ -5,37 +5,78 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 ## Flat Array Data (`data: object[]`)
 - **LineChart** — `xAccessor`, `yAccessor`, `lineBy` (multi-line), `curve`
 - **AreaChart** — `xAccessor`, `yAccessor`, `areaBy`, `areaOpacity`
-- **StackedAreaChart** — `xAccessor`, `yAccessor`, `areaBy` (required), `normalize`
+- **StackedAreaChart** — `xAccessor`, `yAccessor`, **`areaBy`** (required, groups flat data into stacked areas), `colorBy`, `normalize`. Data must be a flat array. Do NOT use `lineBy` or `lineDataAccessor`.
 - **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`
 - **GroupedBarChart** — `categoryAccessor`, `valueAccessor`, **`groupBy`** (required)
 - **SwarmPlot** — `categoryAccessor`, `valueAccessor`, `pointRadius`
 - **BoxPlot** — `categoryAccessor`, `valueAccessor`, `showOutliers`
-- **Histogram** — `categoryAccessor`, `valueAccessor`, `bins` (default 25), `relative`
+- **Histogram** — `categoryAccessor` (optional, defaults to `"category"` — omit for single-group), `valueAccessor`, `bins` (default 25), `relative`
 - **ViolinPlot** — `categoryAccessor`, `valueAccessor`, `bins`, `curve`, `showIQR`
 - **DotPlot** — `categoryAccessor`, `valueAccessor`, `sort`, `dotRadius`
 - **PieChart** — `categoryAccessor`, `valueAccessor`
-- **DonutChart** — `categoryAccessor`, `valueAccessor`, `innerRadius`, `centerContent`
+- **DonutChart** — `categoryAccessor`, `valueAccessor`, `innerRadius`, `centerContent` (ReactNode, e.g. `<div>50%</div>`)
 
 ## Hierarchical Data (`data: { children: [...] }`)
 - **TreeDiagram** — `childrenAccessor`, `nodeIdAccessor`, `layout` ("tree"|"cluster"|"partition"), `orientation`
 - **Treemap** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
 - **CirclePack** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
+- **OrbitDiagram** — animated radial/orbital hierarchy (use this, not TreeDiagram, for animated orbiting nodes). `childrenAccessor`, `nodeIdAccessor`, `orbitMode` ("flat"|"solar"|"atomic"|number[]), `speed`, `animated`. For static radial trees use `TreeDiagram layout="radial"`.
 
 ## Network Data (`nodes: object[]`, `edges: object[]`)
-- **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`
+- **ForceDirectedGraph** — **`nodes`**, **`edges`** (both required), `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize` (number|string|fn), `nodeSizeRange`, `edgeWidth`, `edgeOpacity`, `iterations`, `forceStrength`, `showLabels`, `nodeLabel`, `tooltip`, `showLegend`
 - **SankeyDiagram** — **`edges`** (required), `sourceAccessor`, `targetAccessor`, `valueAccessor`
 - **ChordDiagram** — **`edges`** (required), `sourceAccessor`, `targetAccessor`, `valueAccessor`
 
+**Important**: Always use these HOC components for network charts unless you need sophisticated control they don't expose. `StreamNetworkFrame` is a low-level escape hatch — its callbacks receive internal wrapper objects (`RealtimeNode`), not your raw data.
+
 ## Realtime (ref-based push API, canvas)
-- **RealtimeLineChart** — `ref.current.push(datum)`, `timeAccessor`, `valueAccessor`, `windowSize`
-- **RealtimeHistogram** — **`binSize`** (required), `timeAccessor`, `valueAccessor`
-- **RealtimeSwarmChart** — `timeAccessor`, `valueAccessor`, `categoryAccessor`
-- **RealtimeWaterfallChart** — `timeAccessor`, `valueAccessor`, `positiveColor`, `negativeColor`
-- **StreamNetworkFrame** (`chartType="sankey"`) — `ref.current.push({ source, target, value })`, `sourceAccessor`, `targetAccessor`, `valueAccessor` (import from `semiotic`)
+
+**IMPORTANT**: All pushed data must include a time field (default: `"time"`). Set `timeAccessor` if your field is named differently. Without a valid time field, charts silently render blank.
+
+Sizing: all Realtime HOCs accept both `size={[600, 400]}` (tuple) and `width={600} height={400}`.
+
+- **RealtimeLineChart** — `ref.current.push(datum)`, **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `windowSize`
+- **RealtimeHistogram** — **`binSize`** (required), **`timeAccessor`** ("time"), **`valueAccessor`** ("value"). Time field required even though this is a distribution — it's used for windowing.
+- **RealtimeSwarmChart** — **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `categoryAccessor`
+- **RealtimeWaterfallChart** — **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `positiveColor`, `negativeColor`
+- **RealtimeHeatmap** — **`timeAccessor`** ("time"), **`valueAccessor`** ("value"), `heatmapXBins`, `heatmapYBins`, `aggregation`. Both must match your data fields.
+- **StreamNetworkFrame** (`chartType="sankey"`) — push **individual edges**: `ref.current.push({ source, target, value })`. Use `ref.current.pushMany([...edges])` for batches. Do NOT push full edge snapshots. Props: `sourceAccessor`, `targetAccessor`, `valueAccessor`, `showParticles` (boolean), `particleStyle` (`{ radius, opacity, speedMultiplier, maxPerEdge, colorBy }`) (import from `semiotic`)
+
+Pushed data shape: `{ time: Date.now(), value: 42 }` for line/waterfall/heatmap, add `category` for histogram/swarm.
+
+### Push API on HOC charts
+Many HOC charts support the push API via `forwardRef`. **Omit the `data` prop** (do NOT pass `data={[]}`) and push imperatively:
+```jsx
+const chartRef = useRef()
+chartRef.current.push({ x: 1, y: 2 })
+<Scatterplot ref={chartRef} xAccessor="x" yAccessor="y" />
+```
+Methods: `push(datum)`, `pushMany(data)`, `clear()`, `getData()`. Streaming-specific props (`windowSize`, `decay`, `pulse`) go in `frameProps`. Supported: XY charts, ordinal charts, network charts (ForceDirectedGraph, SankeyDiagram, ChordDiagram), ProportionalSymbolMap, DistanceCartogram. Not supported: hierarchy charts (TreeDiagram, Treemap, CirclePack, OrbitDiagram), ChoroplethMap, FlowMap, ScatterplotMatrix.
+
+For advanced streaming control, use Stream Frames (`StreamXYFrame`, `StreamOrdinalFrame`, `StreamNetworkFrame`) with `runtimeMode="streaming"` and ref-based push.
+
+## ChartContainer
+- **ChartContainer** — wrapper with title, subtitle, status indicator, toolbar. `title`, `subtitle`, `height` (default **400** — always set this to match your chart height), `width` ("100%"), `status` ("live"|"stale"|"error"), `loading`, `error`, `actions`, `style`
+- When using with `size={[w, h]}`, set `height={h}` on the container or you'll get extra whitespace.
 
 ## Common Props (all components)
-`width`, `height`, `margin`, `title`, `colorBy`, `colorScheme`, `enableHover`, `tooltip`, `showLegend`, `className`, `frameProps`
+`width`, `height`, `margin`, `title`, `colorBy`, `colorScheme`, `enableHover`, `tooltip`, `showLegend`, `className`, `frameProps`, `onObservation`, `emphasis` ("primary"|"secondary")
+
+### tooltip
+`true` (default) | `false` | `(datum) => ReactNode` (function receives your raw data) | config `{ fields?, title?, format?, style? }`
+
+### onObservation
+Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selection", datum: <your data>, x, y, timestamp, chartType, chartId }`. The `datum` field is your original data object. Hover-end/click-end events omit `datum`.
+
+### emphasis
+`emphasis="primary"` makes a chart span two columns inside a `ChartGrid`.
+
+## Key Patterns
+- **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
+- **SSR**: `renderToStaticSVG("ordinal", props)` or `renderOrdinalToStaticSVG(props)` from `semiotic/server`. Frame type is `"xy"` | `"ordinal"` | `"network"` (NOT component name).
+- **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

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/components/Legend.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import { LegendProps, GradientLegendConfig } from "./types/legendTypes";
+/** Gradient legend for continuous/sequential color scales */
+export declare function GradientLegend({ config, orientation, width, }: {
+    config: GradientLegendConfig;
+    orientation?: "vertical" | "horizontal";
+    width?: number;
+}): React.JSX.Element;
+export default function Legend(props: LegendProps): 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/components/charts/geo/ChoroplethMap.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
+import { type AreasProp } from "../../geo/useReferenceAreas";
+export interface ChoroplethMapProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /** GeoJSON features or a reference string ("world-110m", "world-50m", "land-110m", "land-50m") */
+    areas: AreasProp;
+    /** Accessor for the numeric value to encode as color */
+    valueAccessor: ChartAccessor<TDatum, number>;
+    /** Sequential color scheme @default "blues" */
+    colorScheme?: string;
+    /** Geographic projection @default "equalEarth" */
+    projection?: ProjectionProp;
+    /** Show graticule grid lines */
+    graticule?: boolean | import("../../stream/geoTypes").GraticuleConfig;
+    /** Tooltip config */
+    tooltip?: TooltipProp;
+    /** Show legend @default true */
+    showLegend?: boolean;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    fitPadding?: number;
+    /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
+    zoomable?: boolean;
+    /** [minZoom, maxZoom] @default [1, 8] */
+    zoomExtent?: [number, number];
+    /** Zoom change callback */
+    onZoom?: StreamGeoFrameProps["onZoom"];
+    /**
+     * When true, drag gestures rotate the projection (globe spinning)
+     * instead of panning. Defaults to true for orthographic projection.
+     */
+    dragRotate?: boolean;
+    /** Raster tile URL template or function. Enables tile basemap (Mercator only). */
+    tileURL?: string | ((z: number, x: number, y: number, dpr: number) => string);
+    /** Attribution text for tile provider */
+    tileAttribution?: string;
+    /** Max cached tiles @default 256 */
+    tileCacheSize?: number;
+    /** Fill opacity for area polygons. Useful for layering over tile basemaps. @default 1 */
+    areaOpacity?: number;
+    /** Annotations */
+    annotations?: Record<string, any>[];
+    /** Passthrough to StreamGeoFrame */
+    frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "projection">>;
+}
+export declare function ChoroplethMap<TDatum extends Record<string, any> = Record<string, any>>(props: ChoroplethMapProps<TDatum>): React.JSX.Element | null;
+export declare namespace ChoroplethMap {
+    var displayName: string;
+}

package/dist/components/charts/geo/DistanceCartogram.d.ts

@@ -0,0 +1,90 @@
+import * as React from "react";
+import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendPosition } from "../shared/hooks";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+export interface DistanceCartogramProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /** Point data with geographic coordinates */
+    points?: TDatum[];
+    /** Route/edge data with source/target fields */
+    lines?: {
+        source: string;
+        target: string;
+        coordinates?: any[];
+        [key: string]: any;
+    }[];
+    /** Longitude accessor @default "lon" */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /** Latitude accessor @default "lat" */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /** Node ID accessor @default "id" */
+    nodeIdAccessor?: string;
+    /** ID of the center point */
+    center: string;
+    /** Cost/distance accessor — numeric field or function */
+    costAccessor: string | ((d: any) => number);
+    /** Interpolation between geographic (0) and cartogram (1) @default 1 */
+    strength?: number;
+    /** Line rendering mode @default "straight" */
+    lineMode?: "straight" | "fractional";
+    /** Base geographic projection @default "mercator" */
+    projection?: ProjectionProp;
+    /** Show graticule grid lines */
+    graticule?: boolean | import("../../stream/geoTypes").GraticuleConfig;
+    /** Transition duration in ms when center/strength changes */
+    transition?: number;
+    /** Field to determine point color */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /** Color scheme @default "category10" */
+    colorScheme?: string | string[];
+    /** Point radius @default 5 */
+    pointRadius?: number;
+    /** Tooltip */
+    tooltip?: TooltipProp;
+    /** Show legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    fitPadding?: number;
+    /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
+    zoomable?: boolean;
+    /** [minZoom, maxZoom] @default [1, 8] */
+    zoomExtent?: [number, number];
+    /** Zoom change callback */
+    onZoom?: StreamGeoFrameProps["onZoom"];
+    /**
+     * When true, drag gestures rotate the projection (globe spinning)
+     * instead of panning. Defaults to true for orthographic projection.
+     */
+    dragRotate?: boolean;
+    /** Raster tile URL template or function. Enables tile basemap (Mercator only). */
+    tileURL?: string | ((z: number, x: number, y: number, dpr: number) => string);
+    /** Attribution text for tile provider */
+    tileAttribution?: string;
+    /** Max cached tiles @default 256 */
+    tileCacheSize?: number;
+    /** Show concentric distance rings around center. true for auto intervals, number for ring count, or number[] for explicit cost values. @default true */
+    showRings?: boolean | number | number[];
+    /** Ring style overrides */
+    ringStyle?: {
+        stroke?: string;
+        strokeWidth?: number;
+        strokeDasharray?: string;
+        labelColor?: string;
+        labelSize?: number;
+    };
+    /** Show north indicator arrow @default true */
+    showNorth?: boolean;
+    /** Label for cost units shown on rings (e.g. "hrs", "km") */
+    costLabel?: string;
+    /** Annotations */
+    annotations?: Record<string, any>[];
+    /** Passthrough */
+    frameProps?: Partial<Omit<StreamGeoFrameProps, "projection">>;
+}
+export declare const DistanceCartogram: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: DistanceCartogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/geo/FlowMap.d.ts

@@ -0,0 +1,83 @@
+import * as React from "react";
+import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { Style } from "../../stream/types";
+import type { GeoParticleStyle } from "../../stream/GeoParticlePool";
+import { type AreasProp } from "../../geo/useReferenceAreas";
+export interface FlowMapProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /** Flow edges with source/target/value */
+    flows?: {
+        source: string;
+        target: string;
+        value?: number;
+        [key: string]: any;
+    }[];
+    /** Geographic nodes with coordinates */
+    nodes?: TDatum[];
+    /** Node ID accessor @default "id" */
+    nodeIdAccessor?: string;
+    /** Longitude accessor @default "lon" */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /** Latitude accessor @default "lat" */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /** Value accessor for edge width @default "value" */
+    valueAccessor?: string;
+    /** Projection @default "equalEarth" */
+    projection?: ProjectionProp;
+    /** Show graticule grid lines */
+    graticule?: boolean | import("../../stream/geoTypes").GraticuleConfig;
+    /** Line type: "geo" for great circles, "line" for straight @default "geo" */
+    lineType?: "geo" | "line";
+    /** Flow rendering style: "basic" (straight/great-circle), "offset" (bidirectional offset), "arc" (curved arcs) @default "basic" */
+    flowStyle?: "basic" | "offset" | "arc";
+    /** Optional background areas */
+    areas?: AreasProp;
+    /** Background area style */
+    areaStyle?: Style;
+    /** Edge color accessor */
+    edgeColorBy?: ChartAccessor<any, string>;
+    /** Edge opacity @default 0.6 */
+    edgeOpacity?: number;
+    /** Min/max pixel width for proportional edge width @default [1, 8] */
+    edgeWidthRange?: [number, number];
+    /** Line cap style for flow edges @default "round" */
+    edgeLinecap?: "butt" | "round" | "square";
+    /** Color scheme for edges @default "category10" */
+    colorScheme?: string | string[];
+    /** Show animated particles along flow lines */
+    showParticles?: boolean;
+    /** Particle appearance and behavior */
+    particleStyle?: GeoParticleStyle;
+    /** Tooltip */
+    tooltip?: TooltipProp;
+    /** Show legend */
+    showLegend?: boolean;
+    /** Padding fraction for auto-fit projection. 0.1 = 10% inset from edges. @default 0 */
+    fitPadding?: number;
+    /** Enable zoom/pan. Defaults to true when tileURL is set, false otherwise. */
+    zoomable?: boolean;
+    /** [minZoom, maxZoom] @default [1, 8] */
+    zoomExtent?: [number, number];
+    /** Zoom change callback */
+    onZoom?: StreamGeoFrameProps["onZoom"];
+    /**
+     * When true, drag gestures rotate the projection (globe spinning)
+     * instead of panning. Defaults to true for orthographic projection.
+     */
+    dragRotate?: boolean;
+    /** Raster tile URL template or function. Enables tile basemap (Mercator only). */
+    tileURL?: string | ((z: number, x: number, y: number, dpr: number) => string);
+    /** Attribution text for tile provider */
+    tileAttribution?: string;
+    /** Max cached tiles @default 256 */
+    tileCacheSize?: number;
+    /** Annotations */
+    annotations?: Record<string, any>[];
+    /** Passthrough */
+    frameProps?: Partial<Omit<StreamGeoFrameProps, "projection">>;
+}
+export declare function FlowMap<TDatum extends Record<string, any> = Record<string, any>>(props: FlowMapProps<TDatum>): React.JSX.Element;
+export declare namespace FlowMap {
+    var displayName: string;
+}