semiotic 3.4.2 → 3.5.0

package/ai/system-prompt.md

@@ -1,6 +1,6 @@
 # Semiotic — React Data Visualization
 
-Use sub-path imports: `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB). Or `semiotic/ai` for all 38 HOCs in one import (269KB).
+Use sub-path imports: `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB). Or `semiotic/ai` for all 39 non-geo HOCs in one import (269KB).
 
 ## Flat Array Data (`data: object[]`)
 - **LineChart** — `xAccessor`, `yAccessor`, `lineBy` (multi-line), `curve`
@@ -105,7 +105,7 @@ All charts respond to CSS custom properties on any ancestor:
 ```
 Or use ThemeProvider with 15 named presets: `<ThemeProvider theme="tufte">`, `"tufte-dark"`, `"pastels"`, `"bi-tool"`, `"italian"`, `"journalist"`, `"playful"` (each with `-dark` variant), `"dark"`, `"high-contrast"`.
 
-**Color resolution**: When `colorBy` is set, charts use: explicit `colorScheme` prop > ThemeProvider `colors.categorical` > `"category10"`. No need to pass `colorScheme` on every chart when using ThemeProvider.
+**Color resolution**: When `colorBy` is set, charts use: CategoryColorProvider/LinkedCharts category map > explicit `colorScheme` fallback > ThemeProvider `colors.categorical` > `"category10"`. No need to pass `colorScheme` on every chart when using ThemeProvider.
 
 `semiotic/themes` entry point: `themeToCSS(theme, selector)` generates CSS string, `themeToTokens(theme)` generates DTCG design tokens, `resolveThemePreset("tufte")` returns theme object by name. Theme objects: `TUFTE_LIGHT`, `TUFTE_DARK`, `PASTELS_LIGHT`, `BI_TOOL_LIGHT`, `ITALIAN_LIGHT`, `JOURNALIST_LIGHT`, `PLAYFUL_LIGHT`, etc.
 
@@ -113,9 +113,28 @@ Or use ThemeProvider with 15 named presets: `<ThemeProvider theme="tufte">`, `"t
 
 **Scoped CSS cascade override** (per-subtree, no ThemeProvider needed): wrap in `<div style={{ "--semiotic-danger": "#c00" }}>` — every chart beneath inherits the override via canvas CSS-var lookup (`getComputedStyle` on the canvas's DOM ancestor). Use CSS vars for **single-role** overrides, nested `ThemeProvider` for **array/scale** overrides.
 
-`COLOR_BLIND_SAFE_CATEGORICAL` — 8-color accessible palette (Wong 2011). Import from `semiotic`.
+`COLOR_BLIND_SAFE_CATEGORICAL` — 8-color accessible palette (Wong 2011). Import from `semiotic/themes`.
+
+
+## Behavior Contracts
+
+<!-- semiotic-behavior-contracts:start -->
+
+These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.
+
+- **Data required by usage mode** (`props.data-required-by-usage-mode`): Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.
+- **Categorical color precedence** (`color.category-precedence`): When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.
+- **Required prop combinations** (`props.required-combinations`): Some chart families need semantic props beyond data. These combinations are enforced by validation/schema for static configs and remain required in push mode unless explicitly noted.
+  Required combinations: StackedAreaChart: static data + areaBy; push areaBy. Stacked areas need a flat data array plus areaBy to identify the stacked series. BubbleChart: static data + sizeBy; push sizeBy. Bubbles need sizeBy in addition to x/y accessors so radius encodes data rather than a constant point size. StackedBarChart: static data + stackBy; push stackBy. Stacked bars need stackBy to split each category into stack segments. GroupedBarChart: static data + groupBy; push groupBy. Grouped bars need groupBy to split each category into side-by-side bars. SwimlaneChart: static data + subcategoryAccessor; push subcategoryAccessor. Swimlanes need subcategoryAccessor; colorBy defaults to the same field when not provided. GaugeChart: static value; push not supported. GaugeChart is value-only. thresholds, min, max, sweep, and arcWidth are optional. ForceDirectedGraph: static nodes + edges; push nodes + edges. ForceDirectedGraph schema/rendering requires nodes and edges. If an agent infers nodes from edge endpoints, it must materialize a nodes array before returning code.
+- **Push mode omits data** (`streaming.push-mode-data`): HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.
+- **Ref mutations need stable IDs** (`streaming.ref-mutations-require-id-accessors`): push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.
+- **renderChart uses static props only** (`rendering.renderchart-static-props`): MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot. Browser-only realtime components and future ref pushes are not renderable through that path.
+
+<!-- semiotic-behavior-contracts:end -->
 
 ## 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**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `thresholds`.
+- **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
+- **CLI**: `npx semiotic-ai --list` shows components/import paths/renderability; `npx semiotic-ai --schema GaugeChart` prints one component schema with metadata; `--doctor` validates props JSON and behavior contracts.
+- **MCP**: `npx semiotic-mcp` exposes tools (`getSchema`, `suggestChart`, `diagnoseConfig`, `renderChart`, `applyTheme`, `reportIssue`), resources (`semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`), and prompts (`build-semiotic-chart`, `debug-semiotic-chart`).
 - **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

package/dist/components/LinkedCharts.d.ts

@@ -7,6 +7,10 @@ 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;
+/** Register a chart's current color categories with the nearest LinkedCharts. */
+export declare function useLinkedChartCategories(categories: string[]): void;
+/** True when a chart can register live categories with a parent LinkedCharts. */
+export declare function useLinkedChartCategoryRegistryActive(): boolean;
 export interface LinkedChartsProps {
     children: React.ReactNode;
     /** Pre-configure selections with resolution modes */
@@ -16,7 +20,7 @@ export interface LinkedChartsProps {
     /**
      * 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)
+     * @default true
      */
     showLegend?: boolean;
     /**

package/dist/components/Tooltip/Tooltip.d.ts

@@ -151,4 +151,4 @@ export declare function MultiPointTooltip(): TooltipContentFn;
  * Returns `false` to disable, or a `TooltipContentFn` compatible with
  * all Stream Frame `tooltipContent` signatures.
  */
-export declare function normalizeTooltip(tooltip: TooltipProp | undefined): false | TooltipContentFn;
+export declare function normalizeTooltip(tooltip: TooltipProp | undefined): false | TooltipContentFn | undefined;

package/dist/components/charts/custom/NetworkCustomChart.d.ts

@@ -0,0 +1,64 @@
+import * as React from "react";
+import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { NetworkCustomLayout } from "../../stream/networkCustomLayout";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps } from "../shared/types";
+export interface NetworkCustomChartProps<TNode extends Datum = Datum, TEdge extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps {
+    /** Node objects with at least an `id` field. Positions are typically pre-computed by the user (e.g. from dagre / d3-flextree) and read by the layout. */
+    nodes?: TNode[];
+    /** Edge objects referencing node ids via `source`/`target`. */
+    edges?: TEdge[];
+    /** The layout function. Receives NetworkLayoutContext, returns scene primitives. */
+    layout: NetworkCustomLayout<TConfig>;
+    /** Config blob threaded through to NetworkLayoutContext.config. */
+    layoutConfig?: TConfig;
+    /** Field name (or function) for the node id. @default "id" */
+    nodeIDAccessor?: StreamNetworkFrameProps["nodeIDAccessor"];
+    /** Field name for the edge source id. @default "source" */
+    sourceAccessor?: StreamNetworkFrameProps["sourceAccessor"];
+    /** Field name for the edge target id. @default "target" */
+    targetAccessor?: StreamNetworkFrameProps["targetAccessor"];
+    /** Color scheme threaded into the layout's `resolveColor` helper. */
+    colorScheme?: string | string[];
+    enableHover?: boolean;
+    /**
+     * Custom layouts own their own color resolution (the layout function
+     * decides what each node looks like), so the auto-legend infrastructure
+     * the built-in network HOCs use can't run. To render a legend, build a
+     * `legendGroups` array yourself and pass it through `frameProps.legend`.
+     */
+    /** Additional StreamNetworkFrame props for advanced customization. */
+    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig">>;
+}
+/**
+ * NetworkCustomChart — escape hatch for bespoke network geometry.
+ *
+ * Wraps StreamNetworkFrame and threads a user-supplied layout function
+ * into the scene-building pipeline. The layout receives raw nodes/edges,
+ * dimensions, theme, and a `resolveColor` helper, and returns positioned
+ * scene primitives + optional overlays.
+ *
+ * Pair with `flextreeLayout`, `dagreLayout`, or your own. Built-in chart
+ * types (force, sankey, chord, tree, ...) should still be preferred when
+ * they fit; reach for this HOC when none does.
+ *
+ * @example
+ * ```tsx
+ * import { NetworkCustomChart } from "semiotic/network"
+ * import { dagreLayout } from "semiotic/recipes"
+ *
+ * <NetworkCustomChart
+ *   nodes={positionedNodes}
+ *   edges={positionedEdges}
+ *   layout={dagreLayout}
+ *   layoutConfig={{ edgeStyle: "smooth" }}
+ *   width={800}
+ *   height={500}
+ * />
+ * ```
+ */
+export declare const NetworkCustomChart: {
+    <TNode extends Datum = Datum, TEdge extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: NetworkCustomChartProps<TNode, TEdge, TConfig> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/custom/OrdinalCustomChart.d.ts

@@ -0,0 +1,71 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { OrdinalCustomLayout } from "../../stream/ordinalCustomLayout";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps } from "../shared/types";
+export interface OrdinalCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps {
+    /** Data passed through to OrdinalLayoutContext.data. */
+    data?: TDatum[];
+    /** The layout function. Receives OrdinalLayoutContext, returns scene nodes + overlays. */
+    layout: OrdinalCustomLayout<TConfig>;
+    /** Config blob threaded through to OrdinalLayoutContext.config. */
+    layoutConfig?: TConfig;
+    /** Field name (or function) for the category. The frame builds the o-scale from these. */
+    categoryAccessor?: StreamOrdinalFrameProps["categoryAccessor"];
+    /** Field name (or function) for the value. The frame builds the r-scale from these. */
+    valueAccessor?: StreamOrdinalFrameProps["valueAccessor"];
+    /**
+     * Optional category order — overrides the data's insertion order. Most
+     * recipes can ignore this and read `ctx.scales.o.domain()` instead.
+     */
+    oExtent?: StreamOrdinalFrameProps["oExtent"];
+    /** Optional fixed value extent. */
+    rExtent?: StreamOrdinalFrameProps["rExtent"];
+    /** Vertical / horizontal / radial. Default vertical. */
+    projection?: StreamOrdinalFrameProps["projection"];
+    /** Color scheme threaded into the layout's `resolveColor` helper. */
+    colorScheme?: string | string[];
+    enableHover?: boolean;
+    showAxes?: boolean;
+    showGrid?: boolean;
+    annotations?: Datum[];
+    /** Additional StreamOrdinalFrame props for advanced customization. */
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "chartType" | "size" | "customLayout" | "layoutConfig">>;
+}
+/**
+ * OrdinalCustomChart — escape hatch for bespoke ordinal geometry.
+ *
+ * Wraps StreamOrdinalFrame and threads a user-supplied layout function
+ * into the scene-building pipeline. The layout receives the o-scale
+ * (band scale over categories) and r-scale (linear over values), plus
+ * dimensions, theme, and a `resolveColor` helper, and returns scene
+ * primitives plus optional overlays.
+ *
+ * Built-in chart types (BarChart, SwarmPlot, BoxPlot, PieChart, ...)
+ * should still be preferred when they fit. Reach for this HOC when none
+ * does — marimekko, parallel coordinates, bullet, fan chart, slope graph,
+ * etc.
+ *
+ * @example
+ * ```tsx
+ * import { OrdinalCustomChart } from "semiotic/ordinal"
+ * import { marimekkoLayout } from "semiotic/recipes"
+ *
+ * <OrdinalCustomChart
+ *   data={cohorts}
+ *   layout={marimekkoLayout}
+ *   layoutConfig={{
+ *     categoryAccessor: "segment",
+ *     valueAccessor: "revenue",
+ *     stackBy: "product",
+ *   }}
+ *   width={700}
+ *   height={300}
+ * />
+ * ```
+ */
+export declare const OrdinalCustomChart: {
+    <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: OrdinalCustomChartProps<TDatum, TConfig> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/custom/XYCustomChart.d.ts

@@ -0,0 +1,59 @@
+import * as React from "react";
+import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { CustomLayout } from "../../stream/customLayout";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, AxisConfig } from "../shared/types";
+import type { TooltipProp } from "../../Tooltip/Tooltip";
+export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps, AxisConfig {
+    /** Data passed through to LayoutContext.data. */
+    data?: TDatum[];
+    /** The layout function. Receives LayoutContext, returns SceneNode[] + overlays. */
+    layout: CustomLayout<TConfig>;
+    /** Config blob threaded through to LayoutContext.config. */
+    layoutConfig?: TConfig;
+    /**
+     * Optional fixed extents — flow into scale construction *before* the layout
+     * runs, so scales reflect the layout's intended domain. Layouts that don't
+     * use scales (waffle, calendar, treemap) can ignore this.
+     */
+    xExtent?: [number | undefined, number | undefined];
+    yExtent?: [number | undefined, number | undefined];
+    /** Show axes — default false; most custom layouts draw their own axes. */
+    showAxes?: boolean;
+    showGrid?: boolean;
+    enableHover?: boolean;
+    showLegend?: boolean;
+    annotations?: Datum[];
+    colorScheme?: string | string[];
+    tooltip?: TooltipProp;
+    /** Additional StreamXYFrame props for advanced customization, excluding XYCustomChart-controlled fields. */
+    frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size" | "customLayout" | "layoutConfig">>;
+}
+/**
+ * XYCustomChart — escape hatch for bespoke chart geometry.
+ *
+ * Wraps StreamXYFrame and threads a user-supplied layout function into the
+ * scene-building pipeline. The layout receives scales, dimensions, theme,
+ * and a resolveColor helper, and returns scene nodes + optional overlays.
+ *
+ * Built-in chart types should always be preferred. Reach for XYCustomChart
+ * when no HOC fits — waffle grids, calendar heatmaps, horizon bands,
+ * bespoke composites. See `semiotic/recipes` for reference layouts.
+ *
+ * @example
+ * ```tsx
+ * import { XYCustomChart } from "semiotic/xy"
+ * import { waffleLayout } from "semiotic/recipes"
+ *
+ * <XYCustomChart
+ *   data={cells}
+ *   layout={waffleLayout}
+ *   layoutConfig={{ rows: 10, columns: 10, gutter: 2, valueAccessor: "value" }}
+ * />
+ * ```
+ */
+export declare const XYCustomChart: {
+    <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: XYCustomChartProps<TDatum, TConfig> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -4,10 +4,31 @@ 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";
+/**
+ * ChoroplethMap component props
+ */
 export interface ChoroplethMapProps<TDatum extends Datum = Datum> extends BaseChartProps {
-    /** GeoJSON features or a reference string ("world-110m", "world-50m", "land-110m", "land-50m") */
+    /**
+     * Either a `GeoJSON.Feature[]` array (one feature per region) or a
+     * reference string the library resolves into bundled topology:
+     * `"world-110m"`, `"world-50m"`, `"land-110m"`, `"land-50m"`. To pass a
+     * custom geography stored as a `FeatureCollection`, hand its `.features`
+     * array in. Each feature's `properties` should carry the value
+     * `valueAccessor` reads.
+     * @example
+     * ```ts
+     * areas="world-110m"                  // bundled world borders
+     * areas={features}                     // GeoJSON.Feature[]
+     * areas={featureCollection.features}   // FeatureCollection → unwrap to .features
+     * areas={mergeData(world, rows, { featureKey: "iso", dataKey: "iso" })}
+     * ```
+     */
     areas: AreasProp;
-    /** Accessor for the numeric value to encode as color */
+    /**
+     * Field name or function returning the numeric value for each feature.
+     * Read from `feature.properties` after merging or directly off the
+     * feature when values are baked in.
+     */
     valueAccessor: ChartAccessor<TDatum, number>;
     /** Sequential color scheme @default "blues" */
     colorScheme?: string;
@@ -47,6 +68,76 @@ export interface ChoroplethMapProps<TDatum extends Datum = Datum> extends BaseCh
     /** Passthrough to StreamGeoFrame */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "projection">>;
 }
+/**
+ * ChoroplethMap - Encode a numeric value per region with a sequential color scale.
+ *
+ * Each feature in `areas` is filled with a color derived from its
+ * `valueAccessor` value, scaled across the data extent. For point-based
+ * geographic data use {@link ProportionalSymbolMap}; for flow data use
+ * {@link FlowMap}.
+ *
+ * @example
+ * ```tsx
+ * // World choropleth from a bundled topology, values merged in.
+ * // `resolveReferenceGeography` is async, so resolve it in an effect
+ * // before merging — or pass the reference string directly to `areas`
+ * // if your topology already carries the values you need.
+ * import * as React from "react"
+ * import { ChoroplethMap, mergeData, resolveReferenceGeography } from "semiotic/geo"
+ *
+ * function WorldGDPMap({ gdpRows }) {
+ *   const [areas, setAreas] = React.useState([])
+ *   React.useEffect(() => {
+ *     let cancelled = false
+ *     resolveReferenceGeography("world-110m").then(world => {
+ *       if (cancelled) return
+ *       setAreas(mergeData(world, gdpRows, { featureKey: "iso_a3", dataKey: "iso" }))
+ *     })
+ *     return () => { cancelled = true }
+ *   }, [gdpRows])
+ *
+ *   return (
+ *     <ChoroplethMap
+ *       areas={areas}
+ *       valueAccessor={(f) => f.properties.gdp}
+ *       colorScheme="viridis"
+ *       projection="equalEarth"
+ *     />
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom GeoJSON + graticule + zoom/pan
+ * <ChoroplethMap
+ *   areas={statesGeoJson}
+ *   valueAccessor="population_density"
+ *   colorScheme="oranges"
+ *   projection="albersUsa"
+ *   graticule
+ *   zoomable
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Tile basemap underlay (Mercator only) with semi-transparent areas
+ * <ChoroplethMap
+ *   areas={countiesGeoJson}
+ *   valueAccessor="rate"
+ *   projection="mercator"
+ *   tileURL="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+ *   tileAttribution="© OpenStreetMap contributors"
+ *   areaOpacity={0.7}
+ * />
+ * ```
+ *
+ * @remarks
+ * The legend defaults to a sequential gradient legend matching the chosen
+ * `colorScheme`. For diverging data (positive/negative around zero), use
+ * a diverging scheme name and pass `frameProps={{ colorDomain: [-max, max] }}`.
+ */
 export declare function ChoroplethMap<TDatum extends Datum = Datum>(props: ChoroplethMapProps<TDatum>): import("react/jsx-runtime").JSX.Element;
 export declare namespace ChoroplethMap {
     var displayName: string;

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

@@ -9,12 +9,11 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     /** Point data with geographic coordinates */
     points?: TDatum[];
     /** Route/edge data with source/target fields */
-    lines?: {
+    lines?: Array<{
         source: string;
         target: string;
-        coordinates?: any[];
-        [key: string]: any;
-    }[];
+        coordinates?: Datum[];
+    } & Record<string, unknown>>;
     /** Longitude accessor @default "lon" */
     xAccessor?: ChartAccessor<TDatum, number>;
     /** Latitude accessor @default "lat" */
@@ -85,6 +84,54 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     /** Passthrough */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "projection">>;
 }
+/**
+ * DistanceCartogram - Distort a map so distances reflect cost/time, not geography.
+ *
+ * Points are repositioned so their pixel distance from `center` is
+ * proportional to `costAccessor` (commute time, fare, hops, etc.) rather
+ * than great-circle distance. `strength` interpolates between the
+ * geographic positions (0) and the fully-distorted cartogram (1).
+ * Concentric rings show iso-cost contours by default.
+ *
+ * @example
+ * ```tsx
+ * // Cities by travel-time from NYC
+ * <DistanceCartogram
+ *   points={cities}
+ *   xAccessor="lon"
+ *   yAccessor="lat"
+ *   nodeIdAccessor="iata"
+ *   center="JFK"
+ *   costAccessor="hours_from_jfk"
+ *   costLabel="hrs"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Half-distorted view + colored points + custom ring intervals
+ * <DistanceCartogram
+ *   points={cities}
+ *   center="JFK"
+ *   costAccessor="hours_from_jfk"
+ *   strength={0.5}
+ *   colorBy="region"
+ *   showRings={[1, 3, 6, 12]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With route lines connecting source→target by cost
+ * <DistanceCartogram
+ *   points={airports}
+ *   lines={routes}
+ *   center="JFK"
+ *   costAccessor="cost"
+ *   lineMode="fractional"
+ * />
+ * ```
+ */
 export declare const DistanceCartogram: {
     <TDatum extends Datum = Datum>(props: DistanceCartogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

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

@@ -2,6 +2,7 @@ import type { Datum } from "../shared/datumTypes";
 import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { Style } from "../../stream/types";
 import type { GeoParticleStyle } from "../../stream/GeoParticlePool";
 import { type AreasProp } from "../../geo/useReferenceAreas";
@@ -53,6 +54,10 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     tooltip?: TooltipProp;
     /** Show legend */
     showLegend?: boolean;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** 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. */
@@ -77,6 +82,56 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     /** Passthrough */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "projection">>;
 }
+/**
+ * FlowMap - Visualize directed flows between geographic locations.
+ *
+ * Each `flow` connects two `nodes` by id; line width encodes
+ * `valueAccessor` and (optionally) color encodes `edgeColorBy`. Use
+ * `flowStyle="arc"` for curved lines or `"offset"` for bidirectional pairs
+ * that don't overlap. Toggle `showParticles` for animated traffic along
+ * each line.
+ *
+ * For static value-per-region maps use {@link ChoroplethMap}; for
+ * point-size encodings use {@link ProportionalSymbolMap}.
+ *
+ * @example
+ * ```tsx
+ * // Migration flows between cities
+ * <FlowMap
+ *   nodes={cities}                 // [{ id, lon, lat, name }]
+ *   flows={migrations}             // [{ source, target, value }]
+ *   nodeIdAccessor="id"
+ *   valueAccessor="value"
+ *   projection="albersUsa"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Curved arcs colored by source country, particles for live feel
+ * <FlowMap
+ *   nodes={airports}
+ *   flows={routes}
+ *   valueAccessor="passengers"
+ *   flowStyle="arc"
+ *   edgeColorBy="origin_country"
+ *   showParticles
+ *   areas="world-110m"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Bidirectional offset so A→B and B→A are visible separately
+ * <FlowMap
+ *   nodes={hubs}
+ *   flows={trades}
+ *   flowStyle="offset"
+ *   lineType="line"
+ *   edgeOpacity={0.8}
+ * />
+ * ```
+ */
 export declare function FlowMap<TDatum extends Datum = Datum>(props: FlowMapProps<TDatum>): import("react/jsx-runtime").JSX.Element;
 export declare namespace FlowMap {
     var displayName: string;

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

@@ -62,6 +62,59 @@ export interface ProportionalSymbolMapProps<TDatum extends Datum = Datum> extend
     /** Passthrough */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "points" | "projection">>;
 }
+/**
+ * ProportionalSymbolMap - Plot points on a map sized by a numeric value.
+ *
+ * Each row in `points` becomes a circle whose pixel radius is scaled from
+ * `sizeBy`. Optional `colorBy` adds a categorical encoding; an optional
+ * `areas` background gives geographic context.
+ *
+ * For value-per-region encodings use {@link ChoroplethMap}; for
+ * directed-flow encodings use {@link FlowMap}.
+ *
+ * @example
+ * ```tsx
+ * // Cities sized by population
+ * <ProportionalSymbolMap
+ *   points={cities}                // [{ lon, lat, population, country }]
+ *   xAccessor="lon"
+ *   yAccessor="lat"
+ *   sizeBy="population"
+ *   sizeRange={[3, 30]}
+ *   areas="world-110m"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Color by region + tile basemap (Mercator)
+ * <ProportionalSymbolMap
+ *   points={cities}
+ *   sizeBy="population"
+ *   colorBy="region"
+ *   projection="mercator"
+ *   tileURL="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
+ *   tileAttribution="© OpenStreetMap contributors"
+ *   showLegend
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push API — stream new observations onto the map.
+ * // Include the id field in pushed data so remove()/update() can target it.
+ * const ref = useRef<RealtimeFrameHandle>(null)
+ * useEffect(() => {
+ *   ref.current?.push({ id: "evt-1", lon: -73.9, lat: 40.7, magnitude: 5.2 })
+ * }, [])
+ *
+ * <ProportionalSymbolMap
+ *   ref={ref}
+ *   sizeBy="magnitude"
+ *   pointIdAccessor="id"
+ * />
+ * ```
+ */
 export declare const ProportionalSymbolMap: {
     <TDatum extends Datum = Datum>(props: ProportionalSymbolMapProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

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

@@ -30,6 +30,12 @@ export { MultiAxisLineChart } from "./xy/MultiAxisLineChart";
 export type { MultiAxisLineChartProps, MultiAxisSeriesConfig } from "./xy/MultiAxisLineChart";
 export { CandlestickChart } from "./xy/CandlestickChart";
 export type { CandlestickChartProps } from "./xy/CandlestickChart";
+export { XYCustomChart } from "./custom/XYCustomChart";
+export type { XYCustomChartProps } from "./custom/XYCustomChart";
+export { NetworkCustomChart } from "./custom/NetworkCustomChart";
+export type { NetworkCustomChartProps } from "./custom/NetworkCustomChart";
+export { OrdinalCustomChart } from "./custom/OrdinalCustomChart";
+export type { OrdinalCustomChartProps } from "./custom/OrdinalCustomChart";
 export { BarChart } from "./ordinal/BarChart";
 export type { BarChartProps } from "./ordinal/BarChart";
 export { StackedBarChart } from "./ordinal/StackedBarChart";

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

@@ -30,9 +30,41 @@ export interface ChordDiagramProps<TNode extends Datum = Datum, TEdge extends Da
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;
 }
 /**
- * ChordDiagram - Visualize directed relationships with circular chord layout
+ * ChordDiagram - Visualize bidirectional flows between a small set of categories.
  *
- * Wraps StreamNetworkFrame (canvas-first) for chord relationship visualization.
+ * Each node is a wedge around a circle; ribbons inside connect nodes whose
+ * `valueAccessor` describes the flow magnitude. Best for ≤30 categories
+ * with a square many-to-many relationship matrix.
+ *
+ * For directed many-step flows prefer {@link SankeyDiagram}; for
+ * unbounded networks prefer {@link ForceDirectedGraph}.
+ *
+ * @example
+ * ```tsx
+ * // Trade flows between regions
+ * <ChordDiagram
+ *   nodes={[{ id: "EMEA" }, { id: "Americas" }, { id: "APAC" }]}
+ *   edges={[
+ *     { source: "EMEA", target: "Americas", value: 32 },
+ *     { source: "Americas", target: "APAC", value: 18 },
+ *     { source: "APAC", target: "EMEA", value: 24 },
+ *   ]}
+ *   valueAccessor="value"
+ *   showLabels
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Color ribbons by source, custom padAngle
+ * <ChordDiagram
+ *   nodes={nodes}
+ *   edges={edges}
+ *   valueAccessor="value"
+ *   edgeColorBy="source"
+ *   padAngle={0.04}
+ * />
+ * ```
  */
 export declare const ChordDiagram: {
     <TNode extends Datum = Datum, TEdge extends Datum = Datum>(props: ChordDiagramProps<TNode, TEdge> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;