semiotic 3.4.1 → 3.5.0

package/dist/components/charts/ordinal/FunnelChart.d.ts

@@ -51,6 +51,46 @@ export interface FunnelChartProps<TDatum extends Datum = Datum> extends BaseChar
  * **Vertical** (`orientation="vertical"`): vertical bars with hatched
  * dropoff stacking. Each bar shows retained (solid) + dropoff from
  * previous step (hatched). Multi-category renders grouped bars.
+ *
+ * For multi-step many-source flows prefer {@link SankeyDiagram}.
+ *
+ * @example
+ * ```tsx
+ * // Classic conversion funnel
+ * <FunnelChart
+ *   data={[
+ *     { step: "Visit",    users: 5000 },
+ *     { step: "Signup",   users: 3200 },
+ *     { step: "Activate", users: 1800 },
+ *     { step: "Upgrade",  users: 240 },
+ *   ]}
+ *   stepAccessor="step"
+ *   valueAccessor="users"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical orientation showing absolute drop-off
+ * <FunnelChart
+ *   data={steps}
+ *   stepAccessor="step"
+ *   valueAccessor="users"
+ *   orientation="vertical"
+ *   connectorOpacity={0.3}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-category funnel — one funnel per cohort
+ * <FunnelChart
+ *   data={cohortSteps}
+ *   stepAccessor="step"
+ *   valueAccessor="users"
+ *   categoryAccessor="cohort"
+ * />
+ * ```
  */
 export declare const FunnelChart: {
     <TDatum extends Datum = Datum>(props: FunnelChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

package/dist/components/charts/ordinal/GaugeChart.d.ts

@@ -50,6 +50,51 @@ export interface GaugeChartProps extends BaseChartProps {
     /** frameProps escape hatch */
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * GaugeChart - A single-value indicator with an optional needle and threshold zones.
+ *
+ * Pass a `value` between `min` and `max`; threshold zones color the arc
+ * by status. Useful for KPI tiles, health-check displays, and scorecards.
+ *
+ * @example
+ * ```tsx
+ * // Simple gauge with threshold zones
+ * <GaugeChart
+ *   value={72}
+ *   min={0}
+ *   max={100}
+ *   thresholds={[
+ *     { value: 60, color: "#22c55e", label: "ok" },
+ *     { value: 80, color: "#f59e0b", label: "warn" },
+ *     { value: 100, color: "#ef4444", label: "crit" },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Half-sweep gauge with center value text
+ * <GaugeChart
+ *   value={42}
+ *   min={0}
+ *   max={100}
+ *   sweep={Math.PI}
+ *   arcWidth={20}
+ *   centerContent={<text fontSize={32}>42%</text>}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Hide needle, fill the zone-of-current-value instead
+ * <GaugeChart
+ *   value={87}
+ *   thresholds={[{ value: 50, color: "#22c55e" }, { value: 90, color: "#f59e0b" }, { value: 100, color: "#ef4444" }]}
+ *   showNeedle={false}
+ *   fillZones
+ * />
+ * ```
+ */
 export declare const GaugeChart: {
     (props: GaugeChartProps & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/GroupedBarChart.d.ts

@@ -34,6 +34,44 @@ export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends Base
     categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * GroupedBarChart - Multiple bars per category, side by side.
+ *
+ * Each row contributes to one bar inside the group named by
+ * `categoryAccessor`; `groupBy` splits each category into the
+ * side-by-side series. Use {@link StackedBarChart} when group totals
+ * matter more than individual values.
+ *
+ * @example
+ * ```tsx
+ * // Quarterly revenue by region
+ * <GroupedBarChart
+ *   data={[
+ *     { quarter: "Q1", region: "EMEA",     revenue: 120 },
+ *     { quarter: "Q1", region: "Americas", revenue: 95 },
+ *     { quarter: "Q2", region: "EMEA",     revenue: 140 },
+ *     { quarter: "Q2", region: "Americas", revenue: 110 },
+ *   ]}
+ *   categoryAccessor="quarter"
+ *   valueAccessor="revenue"
+ *   groupBy="region"
+ *   showLegend
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom palette + sorted categories
+ * <GroupedBarChart
+ *   data={data}
+ *   categoryAccessor="quarter"
+ *   valueAccessor="revenue"
+ *   groupBy="region"
+ *   colorScheme={["#3b82f6", "#22c55e", "#ef4444"]}
+ *   sort="asc"
+ * />
+ * ```
+ */
 export declare const GroupedBarChart: {
     <TDatum extends Datum = Datum>(props: GroupedBarChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/Histogram.d.ts

@@ -5,11 +5,45 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * Histogram component props
+ */
 export interface HistogramProps<TDatum extends Datum = Datum> extends BaseChartProps {
+    /**
+     * Array of rows. Either pre-binned (one row per bar with a category +
+     * count) or raw observations the chart will bin via `valueAccessor`.
+     * @example
+     * ```ts
+     * // Raw observations — chart bins them
+     * [{ value: 12 }, { value: 18 }, { value: 22 }, ...]
+     * // Or pre-binned
+     * [{ bucket: "0–10", count: 3 }, { bucket: "10–20", count: 7 }]
+     * ```
+     */
     data?: TDatum[];
+    /**
+     * Field name or function returning the bin label (used when data is
+     * already binned). Ignored when binning raw values.
+     * @default "category"
+     */
     categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function returning the numeric value to bin (raw mode)
+     * or the count for each bin (pre-binned mode).
+     * @default "value"
+     */
     valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Number of equal-width bins for raw-data mode. Ignored when data is
+     * already binned.
+     * @default 25
+     */
     bins?: number;
+    /**
+     * Render bin heights as fraction of total instead of absolute counts.
+     * Y-axis becomes [0, 1].
+     * @default false
+     */
     relative?: boolean;
     categoryLabel?: string;
     valueLabel?: string;
@@ -40,6 +74,67 @@ export interface HistogramProps<TDatum extends Datum = Datum> extends BaseChartP
     categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * Histogram - Visualize the distribution of a continuous variable as bars.
+ *
+ * Always horizontal-bars-by-value-axis style. Either bin raw observations
+ * via `bins` and `valueAccessor`, or pass pre-binned rows directly. Use
+ * `relative` to convert counts to a fraction of total.
+ *
+ * For comparison across multiple distributions overlaid, prefer
+ * {@link RidgelinePlot} (one row per group, stacked) or
+ * {@link ViolinPlot} (mirrored density per group).
+ *
+ * @example
+ * ```tsx
+ * // Bin raw observations
+ * <Histogram
+ *   data={observations}        // [{ value: 12 }, { value: 18 }, ...]
+ *   valueAccessor="value"
+ *   bins={20}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pre-binned data
+ * <Histogram
+ *   data={[
+ *     { bucket: "0–10", count: 3 },
+ *     { bucket: "10–20", count: 7 },
+ *     { bucket: "20–30", count: 5 },
+ *   ]}
+ *   categoryAccessor="bucket"
+ *   valueAccessor="count"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Brush to select a value range; receives the brushed extent
+ * <Histogram
+ *   data={observations}
+ *   valueAccessor="value"
+ *   brush
+ *   onBrush={(extent) => console.log(extent?.r)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Relative frequencies (fractions of total)
+ * <Histogram
+ *   data={observations}
+ *   valueAccessor="value"
+ *   bins={30}
+ *   relative
+ * />
+ * ```
+ *
+ * @remarks
+ * For streaming distributions (window-based binning over a live data
+ * stream), use {@link RealtimeHistogram} from `semiotic/realtime` instead.
+ */
 export declare const Histogram: {
     <TDatum extends Datum = Datum>(props: HistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/LikertChart.d.ts

@@ -92,6 +92,48 @@ export interface LikertChartProps<TDatum extends Datum = Datum> extends BaseChar
 export interface LikertChartHandle extends RealtimeFrameHandle {
     getScales(): ReturnType<NonNullable<StreamOrdinalFrameHandle["getScales"]>>;
 }
+/**
+ * LikertChart - Diverging stacked bars for ordered survey responses.
+ *
+ * Each category (question) gets a horizontal bar where positive responses
+ * extend right and negative responses extend left, centered on the
+ * midpoint of the `levels` ordering. Best for 5-point or 7-point Likert
+ * scales where you want to see net sentiment at a glance.
+ *
+ * Two data shapes are supported: pre-aggregated (one row per
+ * category × level via `levelAccessor` + `countAccessor`) or raw
+ * observations (one row per response via `valueAccessor`).
+ *
+ * @example
+ * ```tsx
+ * // Pre-aggregated: question × level × count
+ * <LikertChart
+ *   data={[
+ *     { question: "Easy to use", level: "Strongly Agree", count: 12 },
+ *     { question: "Easy to use", level: "Agree",          count: 30 },
+ *     { question: "Easy to use", level: "Neutral",        count: 8 },
+ *     { question: "Easy to use", level: "Disagree",       count: 4 },
+ *     { question: "Easy to use", level: "Strongly Disagree", count: 1 },
+ *   ]}
+ *   categoryAccessor="question"
+ *   levelAccessor="level"
+ *   countAccessor="count"
+ *   levels={["Strongly Disagree", "Disagree", "Neutral", "Agree", "Strongly Agree"]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Raw observations: one row per response
+ * <LikertChart
+ *   data={surveyResponses}
+ *   categoryAccessor="question"
+ *   valueAccessor="response"
+ *   levels={["Never", "Rarely", "Sometimes", "Often", "Always"]}
+ *   colorScheme="RdYlGn"
+ * />
+ * ```
+ */
 export declare const LikertChart: {
     <TDatum extends Datum = Datum>(props: LikertChartProps<TDatum> & React.RefAttributes<LikertChartHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/PieChart.d.ts

@@ -5,14 +5,51 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * PieChart component props
+ */
 export interface PieChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
+    /**
+     * Array of category rows. Each row should have a category and a numeric
+     * value; values determine relative wedge size. Omit when using the push API.
+     * @example
+     * ```ts
+     * [{ region: "EMEA", revenue: 120 }, { region: "Americas", revenue: 85 }]
+     * ```
+     */
     data?: TDatum[];
+    /**
+     * Field name or function returning the wedge label.
+     * @default "category"
+     */
     categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function returning the wedge value (slice size). Values
+     * are aggregated by absolute magnitude (`Math.abs`), so negative inputs
+     * render as positive-sized wedges. If your data has signed values you
+     * need to differentiate, sign-encode via `colorBy` or pre-process.
+     * @default "value"
+     */
     valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field or function that determines wedge color. Defaults to coloring by
+     * `categoryAccessor` since pies are inherently categorical.
+     */
     colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for `colorBy`. Either a d3 scheme name (`"category10"`,
+     * `"set2"`, etc.) or an explicit array of colors. Falls back to the
+     * theme's categorical palette when omitted.
+     */
     colorScheme?: string | string[];
+    /**
+     * Rotation in **degrees** applied to the first wedge. `0` starts at 12
+     * o'clock and proceeds clockwise; `90` starts at 3 o'clock, `180` at 6
+     * o'clock, `270` at 9 o'clock.
+     * @default 0
+     */
     startAngle?: number;
-    /** Rounded corner radius on wedge arcs */
+    /** Rounded corner radius on wedge arcs (pixels). */
     cornerRadius?: number;
     enableHover?: boolean;
     showCategoryTicks?: boolean;
@@ -23,6 +60,58 @@ export interface PieChartProps<TDatum extends Datum = Datum> extends BaseChartPr
     annotations?: Datum[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * PieChart - Visualize a single categorical distribution as wedges of a circle.
+ *
+ * Each row becomes one wedge sized by `valueAccessor`. Best for ≤7 categories;
+ * with more, prefer {@link BarChart} or {@link DonutChart} for legibility.
+ *
+ * For a pie with a hole and center content, use {@link DonutChart}.
+ *
+ * @example
+ * ```tsx
+ * // Simple pie
+ * <PieChart
+ *   data={[
+ *     { region: "EMEA", revenue: 120 },
+ *     { region: "Americas", revenue: 85 },
+ *     { region: "APAC", revenue: 60 },
+ *   ]}
+ *   categoryAccessor="region"
+ *   valueAccessor="revenue"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom palette + rounded wedges + start angle
+ * <PieChart
+ *   data={data}
+ *   categoryAccessor="region"
+ *   valueAccessor="revenue"
+ *   colorScheme={["#1f77b4", "#ff7f0e", "#2ca02c"]}
+ *   cornerRadius={4}
+ *   startAngle={90}
+ *   showLegend
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Hover highlight + click handler
+ * <PieChart
+ *   data={data}
+ *   categoryAccessor="region"
+ *   valueAccessor="revenue"
+ *   hoverHighlight
+ *   onClick={(d) => console.log("clicked region:", d)}
+ * />
+ * ```
+ *
+ * @remarks
+ * Wraps {@link StreamOrdinalFrame} with pie-specific defaults. See
+ * {@link https://semiotic.nteract.io/charts/pie-chart} for live demos.
+ */
 export declare const PieChart: {
     <TDatum extends Datum = Datum>(props: PieChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/RidgelinePlot.d.ts

@@ -36,6 +36,33 @@ export interface RidgelinePlotProps<TDatum extends Datum = Datum> extends BaseCh
  *
  * Each category shows its value distribution as a filled area extending from a
  * baseline. The amplitude prop controls overlap between rows.
+ *
+ * Compare with {@link ViolinPlot} (mirrored, side-by-side) and
+ * {@link BoxPlot} (five-number summaries only). Best for ≤30 categories
+ * with enough observations per category to estimate density.
+ *
+ * @example
+ * ```tsx
+ * // Test scores per class — distributions stacked vertically
+ * <RidgelinePlot
+ *   data={observations}
+ *   categoryAccessor="class"
+ *   valueAccessor="score"
+ *   bins={30}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // More overlap (denser packing) + smooth curve
+ * <RidgelinePlot
+ *   data={observations}
+ *   categoryAccessor="month"
+ *   valueAccessor="temperature"
+ *   amplitude={2.5}
+ *   curve="monotoneX"
+ * />
+ * ```
  */
 export declare const RidgelinePlot: {
     <TDatum extends Datum = Datum>(props: RidgelinePlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

package/dist/components/charts/ordinal/StackedBarChart.d.ts

@@ -35,6 +35,44 @@ export interface StackedBarChartProps<TDatum extends Datum = Datum> extends Base
     categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * StackedBarChart - Categorical bars split into stacked segments.
+ *
+ * Each row contributes one segment of the bar named by `categoryAccessor`;
+ * `stackBy` chooses which series the segment belongs to. Use
+ * {@link GroupedBarChart} when individual segment values matter more than
+ * the total; pass `normalize` to compare composition rather than absolute
+ * size.
+ *
+ * @example
+ * ```tsx
+ * // Quarterly revenue split by region
+ * <StackedBarChart
+ *   data={[
+ *     { quarter: "Q1", region: "EMEA",     revenue: 120 },
+ *     { quarter: "Q1", region: "Americas", revenue: 95 },
+ *     { quarter: "Q2", region: "EMEA",     revenue: 140 },
+ *     { quarter: "Q2", region: "Americas", revenue: 110 },
+ *   ]}
+ *   categoryAccessor="quarter"
+ *   valueAccessor="revenue"
+ *   stackBy="region"
+ *   showLegend
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Normalized to 100% — focus on composition
+ * <StackedBarChart
+ *   data={data}
+ *   categoryAccessor="quarter"
+ *   valueAccessor="revenue"
+ *   stackBy="region"
+ *   normalize
+ * />
+ * ```
+ */
 export declare const StackedBarChart: {
     <TDatum extends Datum = Datum>(props: StackedBarChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/SwarmPlot.d.ts

@@ -43,6 +43,42 @@ export interface SwarmPlotProps<TDatum extends Datum = Datum> extends BaseChartP
     categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * SwarmPlot - Show every individual observation per category as a beeswarm.
+ *
+ * Points are placed along the value axis and offset perpendicular to it
+ * to avoid overlap, producing a packed cluster per category. Best for
+ * datasets where you want both the distribution shape AND the individual
+ * observations visible — typically dozens to a few thousand points.
+ *
+ * For aggregate distribution shape only, prefer {@link ViolinPlot},
+ * {@link BoxPlot}, or {@link RidgelinePlot}.
+ *
+ * @example
+ * ```tsx
+ * // Reaction-time observations per cohort
+ * <SwarmPlot
+ *   data={observations}
+ *   categoryAccessor="cohort"
+ *   valueAccessor="reactionTime"
+ *   pointRadius={3}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Color by group within each category, sized by weight
+ * <SwarmPlot
+ *   data={observations}
+ *   categoryAccessor="condition"
+ *   valueAccessor="score"
+ *   colorBy="group"
+ *   sizeBy="weight"
+ *   sizeRange={[2, 10]}
+ *   showLegend
+ * />
+ * ```
+ */
 export declare const SwarmPlot: {
     <TDatum extends Datum = Datum>(props: SwarmPlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -61,9 +61,69 @@ export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseCh
     rTickValues?: number[];
     /** Align first value tick label to start, last to end. Prevents clipping at chart edges. */
     tickLabelEdgeAlign?: boolean;
+    /** Gradient fill for swimlane segments. `true` uses tip→base opacity ramp;
+     *  pass `{ topOpacity, bottomOpacity }` for a uniform alpha gradient or
+     *  `{ colorStops }` for a multi-stop color ramp. Same shape as
+     *  BarChart.gradientFill / AreaChart.gradientFill. The gradient runs along
+     *  the lane's growth direction (left→right horizontal, bottom→top vertical). */
+    gradientFill?: boolean | {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
+    /** Lane "track" fill — a rect drawn behind each lane spanning the full
+     *  value-axis range, sized to the lane's bandwidth. Lets budget/progress
+     *  lanes read as filled vs. empty. Pass a color string (CSS vars
+     *  supported, e.g. `"var(--semiotic-grid)"`) or `{ color, opacity }`. */
+    trackFill?: string | {
+        color: string;
+        opacity?: number;
+    };
     /** Pass-through props to StreamOrdinalFrame */
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * SwimlaneChart - Range bars per category (swim lane), one segment per row.
+ *
+ * Each row becomes a horizontal segment in the lane named by
+ * `categoryAccessor`; `subcategoryAccessor` chooses the segment label
+ * within the lane. Useful for project timelines, status histories,
+ * Gantt-like views, and per-resource workloads.
+ *
+ * @example
+ * ```tsx
+ * // Project task ranges per assignee
+ * <SwimlaneChart
+ *   data={[
+ *     { team: "Design", task: "Spec",   value: 8 },
+ *     { team: "Design", task: "Mocks",  value: 12 },
+ *     { team: "Eng",    task: "API",    value: 16 },
+ *     { team: "Eng",    task: "Client", value: 10 },
+ *     { team: "QA",     task: "Plan",   value: 4 },
+ *   ]}
+ *   categoryAccessor="team"
+ *   subcategoryAccessor="task"
+ *   valueAccessor="value"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Color by subcategory + custom label rotation
+ * <SwimlaneChart
+ *   data={data}
+ *   categoryAccessor="team"
+ *   subcategoryAccessor="task"
+ *   valueAccessor="hours"
+ *   colorBy="task"
+ *   showLegend
+ * />
+ * ```
+ */
 export declare const SwimlaneChart: {
     <TDatum extends Datum = Datum>(props: SwimlaneChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/ordinal/ViolinPlot.d.ts

@@ -42,6 +42,38 @@ export interface ViolinPlotProps<TDatum extends Datum = Datum> extends BaseChart
     categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+/**
+ * ViolinPlot - Mirrored density curves per category for distribution shape.
+ *
+ * Each category gets a symmetric kernel density estimate, optionally with
+ * a {@link BoxPlot}-style IQR overlay (`showIQR`). Compare with
+ * {@link RidgelinePlot} (stacked, single-sided), {@link BoxPlot} (summary
+ * only), or {@link SwarmPlot} (every observation visible).
+ *
+ * @example
+ * ```tsx
+ * // Reaction-time distribution per cohort
+ * <ViolinPlot
+ *   data={observations}
+ *   categoryAccessor="cohort"
+ *   valueAccessor="reactionTime"
+ *   bins={40}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Smoother curve + IQR overlay
+ * <ViolinPlot
+ *   data={observations}
+ *   categoryAccessor="condition"
+ *   valueAccessor="score"
+ *   curve="monotoneX"
+ *   showIQR
+ *   colorBy="condition"
+ * />
+ * ```
+ */
 export declare const ViolinPlot: {
     <TDatum extends Datum = Datum>(props: ViolinPlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -108,16 +108,34 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
  *
  * @example
  * ```tsx
+ * // Count-aggregated heatmap — each push lands in a (time-bin × value-bin) cell
  * const ref = useRef<RealtimeFrameHandle>(null)
- * ref.current.push({ time: Date.now(), x: 42, y: 7 })
+ * useEffect(() => {
+ *   const id = setInterval(() => ref.current?.push({ time: Date.now(), y: Math.random() * 10 }), 50)
+ *   return () => clearInterval(id)
+ * }, [])
+ * return (
+ *   <RealtimeHeatmap
+ *     ref={ref}
+ *     timeAccessor="time"
+ *     valueAccessor="y"
+ *     heatmapXBins={30}
+ *     heatmapYBins={20}
+ *     aggregation="count"
+ *   />
+ * )
+ * ```
  *
+ * @example
+ * ```tsx
+ * // Mean aggregation with a sequential color scheme; useful for sensor density maps
  * <RealtimeHeatmap
  *   ref={ref}
  *   timeAccessor="time"
  *   valueAccessor="y"
- *   heatmapXBins={30}
- *   heatmapYBins={20}
- *   aggregation="count"
+ *   aggregation="mean"
+ *   colorScheme="viridis"
+ *   windowSize={500}
  * />
  * ```
  */