semiotic 3.1.2 → 3.2.1

package/ai/system-prompt.md

@@ -21,6 +21,8 @@ Use `import { ComponentName } from "semiotic/ai"` for all components below.
 - **PieChart** — `categoryAccessor`, `valueAccessor`
 - **DonutChart** — `categoryAccessor`, `valueAccessor`, `innerRadius`, `centerContent` (ReactNode, e.g. `<div>50%</div>`)
 
+All ordinal HOCs (except Pie/Donut) support `categoryFormat` — a function `(label, index?) => string` for custom tick label formatting (truncation, abbreviation).
+
 ## Hierarchical Data (`data: { children: [...] }`)
 - **TreeDiagram** — `childrenAccessor`, `nodeIdAccessor`, `layout` ("tree"|"cluster"|"partition"), `orientation`
 - **Treemap** — `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorByDepth`
@@ -65,17 +67,50 @@ For advanced streaming control, use Stream Frames (`StreamXYFrame`, `StreamOrdin
 - 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`, `onObservation`, `emphasis` ("primary"|"secondary")
+`width`, `height`, `margin`, `title`, `colorBy`, `colorScheme`, `enableHover`, `tooltip`, `showLegend`, `className`, `frameProps`, `onObservation`, `onClick`, `emphasis` ("primary"|"secondary")
 
 ### tooltip
 `true` (default) | `false` | `(datum) => ReactNode` (function receives your raw data) | config `{ fields?, title?, format?, style? }`
 
+### onClick
+`onClick={(datum, { x, y }) => ...}` — called when a data element is clicked. Receives the original datum and pixel coordinates. Works on lines, bars, areas, pie slices, nodes, and geo features.
+
 ### 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`.
 
+## Annotations (XY and ordinal charts)
+- `annotations={[{ type: "y-threshold", value: 200, label: "SLA limit", color: "#e45050", labelPosition: "right" }]}` — horizontal reference line (works on XY and vertical ordinal charts). `labelPosition`: "left"|"center"|"right"
+- `annotations={[{ type: "x-threshold", value: 50, label: "Cutoff", labelPosition: "top" }]}` — vertical reference line. `labelPosition`: "top"|"center"|"bottom"
+- `annotations={[{ type: "category-highlight", category: "Q3 2024", color: "#4589ff", opacity: 0.15 }]}` — highlight a category column/row in ordinal charts
+- `annotations={[{ type: "widget", time: 42, latency: 850, dy: -10, content: <span>Alert</span> }]}` — place React element at data coordinates
+- `annotations={[{ type: "enclose", coordinates: [datum1, datum2], label: "Cluster" }]}` — circle enclosing data points
+
+## Theming & Brand Styling
+All charts respond to CSS custom properties on any ancestor:
+```css
+.my-theme {
+  --semiotic-bg: #1a1a2e;        /* chart background */
+  --semiotic-text: #ededed;       /* primary text */
+  --semiotic-text-secondary: #aaa; /* tick labels */
+  --semiotic-grid: #333;          /* grid lines */
+  --semiotic-border: #555;        /* axis lines */
+  --semiotic-font-family: Georgia, serif;
+  --semiotic-tooltip-bg: #1a1a2e;
+  --semiotic-tooltip-text: #ededed;
+  --semiotic-tooltip-radius: 8px;
+}
+```
+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.
+
+`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.
+
+`COLOR_BLIND_SAFE_CATEGORICAL` — 8-color accessible palette (Wong 2011). Import from `semiotic`.
+
 ## 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).

package/dist/components/ChartContainer.d.ts

@@ -23,6 +23,8 @@ export interface ChartContainerProps {
         copyConfig?: boolean | {
             format?: CopyFormat;
         };
+        /** Enable "Data Summary" action button — shows statistical summary + sample rows */
+        dataSummary?: boolean;
     };
     /** Chart configuration for serialization. Enables the "Copy Config" toolbar action. */
     chartConfig?: ChartConfig;

package/dist/components/DataSummaryContext.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+interface DataSummaryState {
+    /** When true, AccessibleDataTable renders visibly instead of sr-only */
+    visible: boolean;
+    setVisible: React.Dispatch<React.SetStateAction<boolean>>;
+}
+export declare function DataSummaryProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function useDataSummary(): DataSummaryState | null;
+export declare function useDataSummaryToggle(): (() => void) | null;
+export {};

package/dist/components/ThemeProvider.d.ts

@@ -1,12 +1,14 @@
 import * as React from "react";
-import { LIGHT_THEME, DARK_THEME } from "./store/ThemeStore";
+import { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME } from "./store/ThemeStore";
 import type { SemioticTheme } from "./store/ThemeStore";
+import type { ThemePresetName } from "./semiotic-themes";
 interface ThemeProviderProps {
-    theme?: "light" | "dark" | Partial<SemioticTheme>;
+    /** Theme preset name (e.g. "tufte", "pastels-dark", "bi-tool") or a partial SemioticTheme object. */
+    theme?: ThemePresetName | Partial<SemioticTheme>;
     children: React.ReactNode;
 }
 declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): React.JSX.Element;
 declare function useTheme(): SemioticTheme;
 export { ThemeProviderWrapper as ThemeProvider, useTheme };
-export { LIGHT_THEME, DARK_THEME };
+export { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME };
 export type { SemioticTheme };

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

@@ -0,0 +1,34 @@
+import * as React from "react";
+interface FlippingTooltipProps {
+    /** X position within the chart area (relative to margin.left) */
+    x: number;
+    /** Y position within the chart area (relative to margin.top) */
+    y: number;
+    /** Chart area width (excluding margins) */
+    containerWidth: number;
+    /** Chart area height (excluding margins) */
+    containerHeight: number;
+    /** Chart margins */
+    margin: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** Tooltip content */
+    children: React.ReactNode;
+    /** CSS class name for the wrapper */
+    className?: string;
+    /** z-index (default 1) */
+    zIndex?: number;
+}
+/**
+ * Viewport-aware tooltip wrapper that flips horizontally and vertically
+ * when the tooltip would overflow the chart container.
+ *
+ * On first render, uses a heuristic (similar to the old 70%/30% thresholds).
+ * After measuring the actual tooltip size via ref, repositions precisely to
+ * prevent clipping against container edges.
+ */
+export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): React.JSX.Element;
+export {};

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

@@ -47,7 +47,7 @@ export interface ChoroplethMapProps<TDatum extends Record<string, any> = Record<
     /** 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 function ChoroplethMap<TDatum extends Record<string, any> = Record<string, any>>(props: ChoroplethMapProps<TDatum>): React.JSX.Element;
 export declare namespace ChoroplethMap {
     var displayName: string;
 }

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

@@ -26,10 +26,14 @@ export { MinimapChart } from "./xy/MinimapChart";
 export type { MinimapChartProps, MinimapConfig } from "./xy/MinimapChart";
 export { QuadrantChart } from "./xy/QuadrantChart";
 export type { QuadrantChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle } from "./xy/QuadrantChart";
+export { MultiAxisLineChart } from "./xy/MultiAxisLineChart";
+export type { MultiAxisLineChartProps, MultiAxisSeriesConfig } from "./xy/MultiAxisLineChart";
 export { BarChart } from "./ordinal/BarChart";
 export type { BarChartProps } from "./ordinal/BarChart";
 export { StackedBarChart } from "./ordinal/StackedBarChart";
 export type { StackedBarChartProps } from "./ordinal/StackedBarChart";
+export { LikertChart } from "./ordinal/LikertChart";
+export type { LikertChartProps } from "./ordinal/LikertChart";
 export { SwarmPlot } from "./ordinal/SwarmPlot";
 export type { SwarmPlotProps } from "./ordinal/SwarmPlot";
 export { BoxPlot } from "./ordinal/BoxPlot";
@@ -40,6 +44,8 @@ export { ViolinPlot } from "./ordinal/ViolinPlot";
 export type { ViolinPlotProps } from "./ordinal/ViolinPlot";
 export { RidgelinePlot } from "./ordinal/RidgelinePlot";
 export type { RidgelinePlotProps } from "./ordinal/RidgelinePlot";
+export { FunnelChart } from "./ordinal/FunnelChart";
+export type { FunnelChartProps } from "./ordinal/FunnelChart";
 export { DotPlot } from "./ordinal/DotPlot";
 export type { DotPlotProps } from "./ordinal/DotPlot";
 export { PieChart } from "./ordinal/PieChart";
@@ -48,6 +54,8 @@ export { DonutChart } from "./ordinal/DonutChart";
 export type { DonutChartProps } from "./ordinal/DonutChart";
 export { GroupedBarChart } from "./ordinal/GroupedBarChart";
 export type { GroupedBarChartProps } from "./ordinal/GroupedBarChart";
+export { SwimlaneChart } from "./ordinal/SwimlaneChart";
+export type { SwimlaneChartProps } from "./ordinal/SwimlaneChart";
 export { ForceDirectedGraph } from "./network/ForceDirectedGraph";
 export type { ForceDirectedGraphProps } from "./network/ForceDirectedGraph";
 export { ChordDiagram } from "./network/ChordDiagram";
@@ -75,6 +83,9 @@ export type { RealtimeHeatmapProps } from "./realtime/RealtimeHeatmap";
 export type { BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./shared/types";
 export { useColorScale, useSortedData, DEFAULT_COLOR } from "./shared/hooks";
 export { COLOR_SCHEMES, DEFAULT_COLORS, getColor, createColorScale, getSize } from "./shared/colorUtils";
-export { formatNumber, formatDate, formatAxis, createTooltip, formatLargeNumber, truncateText } from "./shared/formatUtils";
+export { formatNumber, formatDate, formatAxis, createTooltip, formatLargeNumber, truncateText, adaptiveTimeTicks } from "./shared/formatUtils";
+export { darkenColor, lightenColor } from "./shared/colorManipulation";
 export { Tooltip, MultiLineTooltip, normalizeTooltip } from "../Tooltip/Tooltip";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "../Tooltip/Tooltip";
+export { createHatchPattern } from "./shared/hatchPattern";
+export type { HatchPatternOptions } from "./shared/hatchPattern";

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

@@ -1,7 +1,7 @@
 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 { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 /**
@@ -21,11 +21,14 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     barPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface BoxPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -19,11 +19,14 @@ export interface BoxPlotProps<TDatum extends Record<string, any> = Record<string
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const BoxPlot: {

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

@@ -13,8 +13,8 @@ export interface DonutChartProps<TDatum extends Record<string, any> = Record<str
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     startAngle?: number;
-    slicePadding?: number;
     enableHover?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface DotPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -19,11 +19,14 @@ export interface DotPlotProps<TDatum extends Record<string, any> = Record<string
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const DotPlot: {

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

@@ -0,0 +1,57 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * FunnelChart component props
+ */
+export interface FunnelChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    data?: TDatum[];
+    /** Accessor for funnel step names (e.g., "Awareness", "Interest", "Purchase") */
+    stepAccessor?: ChartAccessor<TDatum, string>;
+    /** Accessor for the numeric value at each step */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /** Accessor for splitting into mirrored categories (e.g., "control" vs "treatment") */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    colorBy?: ChartAccessor<TDatum, string>;
+    colorScheme?: string | string[];
+    /**
+     * Funnel orientation.
+     *
+     * - `"horizontal"` (default): steps run top-to-bottom with centered bars and
+     *   trapezoid connectors between steps.
+     * - `"vertical"`: steps on the x-axis as vertical bars. Each bar is stacked:
+     *   solid = retained value, hatched = dropoff from the previous step.
+     *   Multi-category data renders grouped bars within each step.
+     */
+    orientation?: "horizontal" | "vertical";
+    /** Opacity of the trapezoid connectors between steps (0–1, default 0.3). Horizontal only. */
+    connectorOpacity?: number;
+    /** Show step name + value labels on bars (default true) */
+    showLabels?: boolean;
+    enableHover?: boolean;
+    showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+/**
+ * FunnelChart — Visualize sequential conversion steps.
+ *
+ * **Horizontal** (default): centered bars narrowing top-to-bottom with
+ * trapezoid connectors. Multi-category mirrors around center axis.
+ *
+ * **Vertical** (`orientation="vertical"`): vertical bars with hatched
+ * dropoff stacking. Each bar shows retained (solid) + dropoff from
+ * previous step (hatched). Multi-category renders grouped bars.
+ */
+export declare const FunnelChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: FunnelChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -1,7 +1,7 @@
 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 { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface GroupedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -18,11 +18,14 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     barPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const GroupedBarChart: {

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
-import type { LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+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";
 export interface HistogramProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -18,10 +18,25 @@ export interface HistogramProps<TDatum extends Record<string, any> = Record<stri
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Enable brush on the value axis */
+    brush?: boolean;
+    /** Callback when brush selection changes */
+    onBrush?: (extent: {
+        r: [number, number];
+    } | null) => void;
+    /** LinkedCharts brush integration */
+    linkedBrush?: string | {
+        name: string;
+        rField?: string;
+    };
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const Histogram: {

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

@@ -0,0 +1,94 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * LikertChart — visualize Likert scale survey responses.
+ *
+ * Supports two data formats:
+ *
+ * **Raw responses** — each row is one respondent's answer:
+ * ```
+ * [{ question: "Q1", score: 4 }, { question: "Q1", score: 2 }, ...]
+ * ```
+ * Set `valueAccessor` to the integer score field. Scores are mapped to
+ * `levels` by index (score 1 → levels[0], score 2 → levels[1], …).
+ *
+ * **Pre-aggregated** — each row is a (question, level, count) triple:
+ * ```
+ * [{ question: "Q1", level: "Agree", count: 45 }, ...]
+ * ```
+ * Set `levelAccessor` and `countAccessor`.
+ *
+ * **Orientation:**
+ * - `"horizontal"` (default) — diverging bar chart centered at 0%.
+ *   Negative levels extend left, positive right. If `levels` has an odd
+ *   count, the center level is split 50/50 across the centerline and drawn
+ *   in a neutral color. Even counts split cleanly at the midpoint.
+ * - `"vertical"` — stacked 100% bar chart, levels stacked bottom-to-top.
+ *
+ * **Important:** The diverging layout assigns meaning by position in the
+ * `levels` array. The first half is treated as "negative", the second half
+ * as "positive", and (if odd) the middle entry as "neutral". If your data
+ * doesn't follow this low-to-high convention, the chart will misrepresent
+ * the polarity.
+ */
+export interface LikertChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    data?: TDatum[];
+    /** Question / item accessor — the ordinal axis. */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Integer score accessor (raw response mode).
+     * Scores are 1-based: score 1 maps to levels[0], score 2 to levels[1], etc.
+     * Mutually exclusive with levelAccessor/countAccessor.
+     */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Level name accessor (pre-aggregated mode).
+     * Each value must match an entry in `levels`.
+     */
+    levelAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Count/frequency accessor (pre-aggregated mode). Defaults to "count".
+     */
+    countAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Ordered response labels from most negative to most positive.
+     * Example (5-point): ["Strongly Disagree", "Disagree", "Neutral", "Agree", "Strongly Agree"]
+     * Example (4-point): ["Strongly Disagree", "Disagree", "Agree", "Strongly Agree"]
+     *
+     * Odd count → center level is neutral. Even count → clean negative/positive split.
+     */
+    levels: string[];
+    /**
+     * "horizontal" (default): diverging bar chart centered at 0%.
+     * "vertical": stacked 100% bar chart.
+     */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * One color per level. Should match the length of `levels`.
+     * For diverging orientation, use a diverging palette (red→neutral→blue).
+     */
+    colorScheme?: string[];
+    categoryLabel?: string;
+    valueLabel?: string;
+    valueFormat?: (d: number | string) => string;
+    barPadding?: number;
+    enableHover?: boolean;
+    showGrid?: boolean;
+    showCategoryTicks?: boolean;
+    showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+export declare const LikertChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: LikertChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -11,8 +11,8 @@ export interface PieChartProps<TDatum extends Record<string, any> = Record<strin
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     startAngle?: number;
-    slicePadding?: number;
     enableHover?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -1,10 +1,11 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
-import type { LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+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";
 export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
-    data: TDatum[];
+    data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
     valueAccessor?: ChartAccessor<TDatum, number>;
     orientation?: "vertical" | "horizontal";
@@ -19,10 +20,14 @@ export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**
@@ -31,7 +36,7 @@ export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<
  * Each category shows its value distribution as a filled area extending from a
  * baseline. The amplitude prop controls overlap between rows.
  */
-export declare function RidgelinePlot<TDatum extends Record<string, any> = Record<string, any>>(props: RidgelinePlotProps<TDatum>): React.JSX.Element;
-export declare namespace RidgelinePlot {
-    var displayName: string;
-}
+export declare const RidgelinePlot: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RidgelinePlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -1,7 +1,7 @@
 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 { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface StackedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -19,11 +19,14 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     barPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const StackedBarChart: {

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -21,11 +21,25 @@ export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<stri
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Enable brush on the value axis */
+    brush?: boolean;
+    /** Callback when brush selection changes */
+    onBrush?: (extent: {
+        r: [number, number];
+    } | null) => void;
+    /** LinkedCharts brush integration */
+    linkedBrush?: string | {
+        name: string;
+        rField?: string;
+    };
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const SwarmPlot: {