semiotic 3.2.0 → 3.2.1

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- Import: `semiotic`, `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/geo`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`, `semiotic/server`, `semiotic/themes`
+- Import: `semiotic`, `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/geo`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`, `semiotic/server`, `semiotic/themes`, `semiotic/utils`
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
 - Every HOC has a built-in error boundary and dev-mode validation warnings
@@ -13,7 +13,9 @@
 - Every HOC accepts `frameProps` to pass through. TypeScript `strict: true`.
 
 ## Common Props (all HOCs)
-`title`, `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill — overrides theme/colorScheme), `enableHover` (true), `tooltip` (boolean | `(datum) => ReactNode` | `{ fields?, title?, format?, style? }`), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array)
+`title`, `description` (overrides aria-label), `summary` (sr-only note), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill — overrides theme/colorScheme), `enableHover` (true), `tooltip` (boolean | `(datum) => ReactNode` | `{ fields?, title?, format?, style? }`), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true)
+
+`onClick` receives `(datum, { x, y })` — the original datum and pixel coordinates. Works on lines, bars, areas, pie slices, nodes, and geo features.
 
 `onObservation` receives `{ type: "hover"|"hover-end"|"click"|"brush"|"selection", datum?, x?, y?, timestamp, chartType, chartId }`. The `datum` is your original data object.
 
@@ -40,11 +42,14 @@
 **ViolinPlot** — + `bins`, `curve`, `showIQR`
 **RidgelinePlot** — + `bins`, `amplitude` (1.5, unitless multiplier of lane width)
 **DotPlot** — + `sort` (true), `dotRadius`, `showGrid` default true
-**PieChart** — `data`, `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`, `slicePadding`
+**PieChart** — `data`, `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`
 **DonutChart** — PieChart + `innerRadius` (60), `centerContent` (ReactNode)
 **FunnelChart** — `data`, `stepAccessor` ("step"), `valueAccessor` ("value"), `categoryAccessor` (optional), `colorBy`, `connectorOpacity` (0.3), `orientation` ("horizontal"|"vertical"). Horizontal: centered bars with trapezoid connectors. Vertical: bars with diagonal hatch for dropoff. Multi-category: `categoryAccessor="channel"` mirrors (horizontal) or groups (vertical).
+**SwimlaneChart** — `data`, `categoryAccessor` ("category"), `subcategoryAccessor` (required), `valueAccessor` ("value"), `colorBy` (defaults to subcategoryAccessor), `colorScheme`, `orientation` ("horizontal"|"vertical"), `barPadding` (40). Renders categorical lanes with items stacked sequentially — unlike StackedBarChart, the same subcategory can appear multiple times in the same lane. Items stack left-to-right (horizontal) or bottom-to-top (vertical) in data order. Wraps StreamOrdinalFrame with `chartType="swimlane"`. Supports push API for streaming.
+
+**LikertChart** — `data`, `categoryAccessor` ("question"), `valueAccessor` ("score", raw mode) or `levelAccessor`+`countAccessor` ("count", pre-aggregated mode), `levels` (required, ordered negative→positive), `orientation` ("horizontal"|"vertical"), `colorScheme`. Horizontal (default): diverging bar chart centered at 0% — negative levels extend left, positive right, neutral (odd count) split 50/50 across centerline. Vertical: stacked 100% bar chart. Supports any scale size (3-point to 7-point+). Raw mode aggregates integer scores automatically (1-based: score 1 → levels[0]). The `levels` array order defines polarity — first half negative, second half positive, center neutral if odd. Supports push API for streaming — accumulates raw data internally and re-aggregates percentages on each push.
 
-All ordinal HOCs support `colorBy` and `colorScheme`. `showCategoryTicks` (default true) hides per-tick labels when false — margins auto-adjust. For distribution charts with `colorBy`, set `showCategoryTicks={false}` since the legend identifies categories.
+All ordinal HOCs support `colorBy` and `colorScheme`. `categoryFormat` (`(label: string, index?: number) => string`) customizes individual tick labels (truncation, formatting). `showCategoryTicks` (default true) hides per-tick labels when false — margins auto-adjust. For distribution charts with `colorBy`, set `showCategoryTicks={false}` since the legend identifies categories.
 
 ## Network Charts (`semiotic/network`)
 
@@ -89,7 +94,7 @@ Push API: `chartRef.current.push({ time, value })`
 **IMPORTANT**: All pushed data must include a time field (default: `"time"`). Set `timeAccessor` if your field differs. Without valid time field, charts render blank.
 
 **RealtimeLineChart** — `timeAccessor` ("time"), `valueAccessor` ("value"), `windowSize` (200), `windowMode`, `stroke`, `strokeWidth`
-**RealtimeHistogram** — `binSize` (required), `timeAccessor`, `valueAccessor`, `categoryAccessor`, `colors`
+**RealtimeHistogram** — `binSize` (required), `timeAccessor`, `valueAccessor`, `categoryAccessor`, `colors`, `brush` (boolean|"x"|object, defaults to `{ dimension: "x", snap: "bin" }` when `true`), `onBrush`, `linkedBrush` (cross-chart coordination)
 **RealtimeSwarmChart** — `timeAccessor`, `valueAccessor`, `categoryAccessor`, `radius`, `opacity`
 **RealtimeWaterfallChart** — `timeAccessor`, `valueAccessor`, `positiveColor`, `negativeColor`
 **RealtimeHeatmap** — `timeAccessor`, `valueAccessor`, `heatmapXBins`, `heatmapYBins`, `aggregation`
@@ -97,6 +102,8 @@ Push API: `chartRef.current.push({ time, value })`
 
 Encoding: `decay`, `pulse`, `transition`, `staleness` — compose freely on all streaming charts.
 
+All Realtime* charts accept `data` props for static mode (no push API needed). RealtimeHistogram brush supports bin-snapping (`snap: "bin"`) and streaming tracking — the brush shrinks as selected bins scroll off and auto-clears when fully evicted. Bin snapping uses actual computed bin boundaries (data-driven), not a uniform grid — works with irregular bin widths. `snapDuring: true` enables continuous snap feedback during drag (not just on release).
+
 ### Push API on HOC charts
 Most HOC charts support push via `forwardRef`. **Omit** `data`/`nodes`/`edges` — do NOT pass `data={[]}`.
 ```jsx
@@ -129,8 +136,10 @@ Fallback chain: `pointColor` → element color → `--semiotic-primary` CSS var
 **LinkedCharts** — `selections` (resolution: "union"|"intersect"|"crossfilter"), `showLegend`, `legendPosition`, `legendInteraction`, `legendSelectionName`, `legendField`
 **CategoryColorProvider** — `colors` (map) or `categories` + `colorScheme`
 Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`, `useFilteredData`
+
+**Linked crosshair** (coordinate-based hover sync): `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}` broadcasts the hovered X data value. Other charts with the same `linkedHover` name render a synced vertical crosshair at that X position. Each chart shows its own Y values independently. Use for dashboards with multiple time-series at different scales.
 **ScatterplotMatrix** — `data`, `fields`, `colorBy`, `cellSize`, `hoverMode`, `brushMode`
-**ChartContainer** — `title`, `subtitle`, `height` (400), `width` ("100%"), `status`, `loading`, `error`, `errorBoundary`, `actions` ({ export, fullscreen, copyConfig }), `controls`
+**ChartContainer** — `title`, `subtitle`, `height` (400), `width` ("100%"), `status`, `loading`, `error`, `errorBoundary`, `actions` ({ export, fullscreen, copyConfig, dataSummary }), `controls`
 **ChartGrid** — `columns` (number|"auto"), `minCellWidth` (300), `gap` (16). `emphasis="primary"` spans two columns.
 **ContextLayout** — `context` (ReactNode), `position`, `contextSize` (250)
 
@@ -180,7 +189,8 @@ const svg = renderOrdinalToStaticSVG({ data, categoryAccessor: "cat", valueAcces
 All HOCs accept `annotations` (array). Coordinates use your data field names. Network/orbit use `nodeId`.
 
 **Positioning**: `widget` (React content at data coords — v3 replacement for v2 `htmlAnnotationRules`; props: `content`, `dx`, `dy`, `width`, `height`, `anchor`), `label` (callout with connector), `callout` (circle + label), `text` (plain text), `bracket`
-**Reference lines**: `y-threshold` (`value`, `label`, `color`), `x-threshold`, `band` (`y0`, `y1`, `label`, `fill`)
+**Reference lines**: `y-threshold` (`value`, `label`, `color`, `labelPosition`: "left"|"center"|"right", `strokeDasharray`), `x-threshold` (`labelPosition`: "top"|"center"|"bottom"), `band` (`y0`, `y1`, `label`, `fill`)
+**Ordinal**: `category-highlight` (`category`, `color`, `opacity`, `label`) — highlights a category column/row. Works on BarChart, StackedBarChart, etc. `y-threshold` also works on vertical ordinal charts.
 **Enclosures**: `enclose` (circle around `coordinates`), `rect-enclose`, `highlight` (`filter` fn or `field`+`value`)
 **Statistical** (XY): `trend` (`method`: linear/polynomial/loess), `envelope`, `anomaly-band`, `forecast`
 **Streaming anchors**: `"fixed"` (default), `"latest"` (tracks newest datum), `"sticky"` (freezes when evicted)
@@ -205,10 +215,24 @@ import { ThemeProvider } from "semiotic"
 <ThemeProvider theme={{ colors: { primary: "#ff6b6b", categorical: [...] } }}> {/* Custom */}
 ```
 
-Presets: `light`, `dark`, `high-contrast`, `pastels`, `pastels-dark`, `bi-tool`, `bi-tool-dark`, `italian`, `italian-dark`, `tufte`, `tufte-dark`, `journalist`, `journalist-dark`, `playful`, `playful-dark`.
+**Color resolution priority** (when `colorBy` is set): explicit `colorScheme` prop > ThemeProvider `colors.categorical` > `"category10"` fallback. This means ThemeProvider categorical colors automatically apply to all charts — no need to pass `colorScheme` on every component.
+
+Presets: `light`, `dark`, `high-contrast`, `pastels`, `pastels-dark`, `bi-tool`, `bi-tool-dark`, `italian`, `italian-dark`, `tufte`, `tufte-dark`, `journalist`, `journalist-dark`, `playful`, `playful-dark`, `carbon`, `carbon-dark`.
 
 Serialization (`semiotic/themes`): `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveThemePreset(name)`.
 Color-blind palette: `import { COLOR_BLIND_SAFE_CATEGORICAL } from "semiotic"` (8-color Wong 2011).
+IBM Carbon palette: `import { CARBON_CATEGORICAL_14, CARBON_ALERT } from "semiotic"` (14-color categorical + 4 alert colors).
+
+**`semiotic/utils`** (~137KB, ~10% of full bundle) — Lightweight entry point for utilities without any chart components:
+- **Theme**: `ThemeProvider`, `useTheme`, `LIGHT_THEME`, `DARK_THEME`, `HIGH_CONTRAST_THEME`, `COLOR_BLIND_SAFE_CATEGORICAL`, `CARBON_CATEGORICAL_14`, `CARBON_ALERT`, `themeToCSS`, `themeToTokens`, `resolveThemePreset`, `THEME_PRESETS`
+- **Format**: `adaptiveTimeTicks`, `smartTickFormat`
+- **Color**: `darkenColor`, `lightenColor`
+- **Patterns**: `createHatchPattern`
+- **Validation**: `validateProps`, `diagnoseConfig`
+- **Serialization**: `toConfig`, `fromConfig`, `toURL`, `fromURL`, `copyConfig`, `configToJSX`, `serializeSelections`, `deserializeSelections`, `exportChart`
+- **Vega-Lite**: `fromVegaLite` — convert Vega-Lite specs to Semiotic configs
+- **Data structures**: `RingBuffer`, `IncrementalExtent`
+- **Tooltip**: `normalizeTooltip`
 
 Key: `ThemeProvider` sets CSS vars on a wrapper div (no React context). Canvas charts read vars via `getComputedStyle`. `exportChart` inlines computed styles.
 
@@ -236,9 +260,26 @@ Key: `ThemeProvider` sets CSS vars on a wrapper div (no React context). Canvas c
 
 `createHatchPattern({ background, stroke, lineWidth, spacing, angle })` from `semiotic` — returns `CanvasPattern | null` for use as `fill` in style functions. Used by FunnelChart vertical mode for dropoff bars.
 
+## Accessibility
+
+Charts render with `role="group"` (outer interactive wrapper, keyboard/focus) and `role="img"` (inner canvas, read by assistive tech). SVG overlays include `<title>` and `<desc>`.
+
+**Keyboard navigation**: Arrow keys navigate data points. In XY/ordinal charts, ArrowRight/Left moves within a series, ArrowUp/Down switches series. In network charts, arrows move to the spatially nearest node in the pressed direction; Enter cycles edge-connected neighbors. Home/End jump to first/last. PageUp/PageDown skip 10%. Escape clears focus.
+
+**Focus ring**: Shape-adaptive dashed ring (circle for points, rect for bars, arc for wedges). Color: `--semiotic-focus` CSS var.
+
+**Data summary**: `accessibleTable` (default true) renders a sr-only summary. Activate via keyboard focus or `actions.dataSummary` in ChartContainer. JIT-computed — no render cost until activated.
+
+**Reduced motion**: `prefers-reduced-motion` auto-detected. Transitions skip to end state, orbit stops, pulse/decay disabled.
+
+**High contrast**: `forced-colors` / `prefers-contrast: more` auto-detected. ThemeProvider applies `HIGH_CONTRAST_THEME` automatically.
+
+**Hooks** (from `semiotic`): `useReducedMotion()`, `useHighContrast()` — SSR-safe, return `false` on server.
+
 ## Known Pitfalls
 
 - **Tooltip datum shape**: HOC tooltip functions get raw data. Frame `tooltipContent` gets wrapped data — use `d.data`.
+- **Tooltip positioning**: Tooltips auto-flip when near container edges (right→left, bottom→top). Custom `tooltip` content should not add its own background — the wrapper provides `--semiotic-tooltip-bg`, `--semiotic-tooltip-text`, etc. Override wrapper styles via CSS custom properties, not inline styles.
 - **Legend positioning**: "bottom" auto-expands margin ~80px. For narrow charts (<400px), prefer "bottom" or "top".
 - **MultiAxisLineChart legend**: Always use `legendPosition="bottom"` (or `"top"`) — the right-hand axis occupies the space where a right-side legend would go.
 - **Log scale**: Clamps domain min to 1e-6 (log(0) undefined).
@@ -248,6 +289,7 @@ Key: `ThemeProvider` sets CSS vars on a wrapper div (no React context). Canvas c
 - **Push API**: Omit `data` prop entirely. `data={[]}` clears pushed data every render.
 - **frameProps style functions**: Bypass HOC color resolution — use `colorBy` prop instead. Frame style functions receive `(datum, categoryName)`, not `(datum, index)`.
 - **v2 migration**: `htmlAnnotationRules` → `widget` annotations + `svgAnnotationRules`. v2 `summaryStyle` index-based coloring → v3 category-string-based.
+- **accessibleTable**: Direct prop on HOCs. Set `accessibleTable={false}` to disable the sr-only data summary.
 
 ## Performance
 

package/README.md

@@ -34,7 +34,7 @@ generate correct code without examples.
 Semiotic ships with everything an AI coding assistant needs to generate
 correct visualizations without trial and error:
 
-- **`semiotic/ai`** — a single import with all 37 chart components, optimized for LLM code generation
+- **`semiotic/ai`** — a single import with all 38 chart components, optimized for LLM code generation
 - **`ai/schema.json`** — machine-readable prop schemas for every component
 - **`npx semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
 - **`npx semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
@@ -59,8 +59,8 @@ ref-based push API. Built-in decay, pulse, and staleness encoding for
 monitoring dashboards.
 
 **Coordinated views.** `LinkedCharts` provides hover cross-highlighting,
-brush cross-filtering, and selection synchronization across any combination
-of chart types — zero wiring.
+brush cross-filtering, coordinate-based linked crosshairs, and selection
+synchronization across any combination of chart types — zero wiring.
 
 **Geographic visualization.** Choropleth maps, proportional symbol maps, flow
 maps with animated particles, and distance cartograms — all canvas-rendered
@@ -239,8 +239,8 @@ import { LineChart, BarChart } from "semiotic"
 
 | Category | Components |
 |---|---|
-| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MinimapChart` |
-| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` |
+| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` |
+| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` |
 | **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
 | **Geo** | `ChoroplethMap` `ProportionalSymbolMap` `FlowMap` `DistanceCartogram` |
 | **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
@@ -282,11 +282,11 @@ for color, size, aggregation, and binning.
 Import only what you need:
 
 ```jsx
-import { LineChart } from "semiotic/xy"                 // ~156 KB
-import { BarChart } from "semiotic/ordinal"              // ~124 KB
-import { ForceDirectedGraph } from "semiotic/network"    // ~123 KB
-import { ChoroplethMap } from "semiotic/geo"             // ~102 KB (+ d3-geo peer)
-import { LineChart } from "semiotic/ai"                  // ~397 KB (all HOCs)
+import { LineChart } from "semiotic/xy"                 // ~123 KB gzip
+import { BarChart } from "semiotic/ordinal"              // ~88 KB gzip
+import { ForceDirectedGraph } from "semiotic/network"    // ~89 KB gzip
+import { ChoroplethMap } from "semiotic/geo"             // ~82 KB gzip
+import { LineChart } from "semiotic/ai"                  // ~236 KB gzip (all HOCs)
 ```
 
 Granular entry points export only v3 Stream Frames and HOC charts — no legacy
@@ -443,7 +443,7 @@ npx semiotic-ai --compact      # compact schema (fewer tokens)
 [Interactive docs and examples](https://semiotic.nteract.io)
 
 - [Getting Started](https://semiotic.nteract.io/getting-started)
-- [Charts](https://semiotic.nteract.io/charts) — all 37 chart types with live examples
+- [Charts](https://semiotic.nteract.io/charts) — all 38 chart types with live examples
 - [Frames](https://semiotic.nteract.io/frames) — full Frame API reference
 - [Features](https://semiotic.nteract.io/features) — axes, annotations, tooltips, styling, Vega-Lite translator
 - [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes

package/ai/examples.md

@@ -995,3 +995,94 @@ import { ThemeProvider, DARK_THEME, COLOR_BLIND_SAFE_CATEGORICAL } from "semioti
   showGrid
 />
 ```
+
+---
+
+## Click Handlers
+
+### onClick on BarChart
+
+```jsx
+import { BarChart } from "semiotic/ai"
+
+<BarChart
+  data={salesData}
+  categoryAccessor="region"
+  valueAccessor="revenue"
+  onClick={(datum, { x, y }) => {
+    console.log(`Clicked ${datum.region}: $${datum.revenue}`)
+    setSelectedRegion(datum.region)
+  }}
+/>
+```
+
+Key props: `onClick` receives the original datum and pixel coordinates. Works on all chart types.
+
+---
+
+## Linked Crosshair (Multi-chart Hover Sync)
+
+### Synced crosshair across time-series charts
+
+```jsx
+import { LineChart, LinkedCharts } from "semiotic/ai"
+
+<LinkedCharts>
+  <LineChart
+    data={cpuData}
+    xAccessor="time" yAccessor="cpu"
+    linkedHover={{ name: "metrics", mode: "x-position", xField: "time" }}
+    selection={{ name: "metrics" }}
+  />
+  <LineChart
+    data={memoryData}
+    xAccessor="time" yAccessor="memory"
+    linkedHover={{ name: "metrics", mode: "x-position", xField: "time" }}
+    selection={{ name: "metrics" }}
+  />
+</LinkedCharts>
+```
+
+Key props: `linkedHover` with `mode: "x-position"` broadcasts the hovered X value. Each chart shows its own tooltip with its own Y values. Use for multi-metric dashboards.
+
+---
+
+## Category Format (Custom Tick Labels)
+
+### Truncated category labels
+
+```jsx
+import { BarChart } from "semiotic/ai"
+
+<BarChart
+  data={data}
+  categoryAccessor="department"
+  valueAccessor="headcount"
+  orientation="horizontal"
+  categoryFormat={(label) => label.length > 12 ? label.slice(0, 12) + "…" : label}
+/>
+```
+
+Key props: `categoryFormat` receives each tick label and returns a formatted string. Available on all ordinal HOCs except Pie/Donut.
+
+---
+
+## Ordinal Annotations
+
+### Threshold + category highlight on BarChart
+
+```jsx
+import { BarChart } from "semiotic/ai"
+
+<BarChart
+  data={quarterlyData}
+  categoryAccessor="quarter"
+  valueAccessor="revenue"
+  annotations={[
+    { type: "y-threshold", value: 50000, label: "Target", color: "#e45050", labelPosition: "left" },
+    { type: "category-highlight", category: "Q3 2024", color: "#4589ff", opacity: 0.15, label: "Current" },
+  ]}
+/>
+```
+
+Key props: `y-threshold` works on vertical ordinal charts. `category-highlight` highlights a category column. `labelPosition` controls label placement.

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -1578,6 +1578,100 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "LikertChart",
+        "description": "Visualize Likert scale survey responses. Horizontal (default): diverging bar chart centered at 0% — negative levels extend left, positive right, neutral (if odd count) split 50/50 across centerline. Vertical: stacked 100% bar chart. Supports raw integer scores (1-based, aggregated automatically) or pre-aggregated (question, level, count) data. The levels array defines polarity: first half = negative, second half = positive, center = neutral (if odd). Works with any scale size (3-point to 7-point+). Supports push API for streaming — accumulates raw data and re-aggregates on each push.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "array",
+              "items": {
+                "type": "object"
+              },
+              "description": "Array of raw response or pre-aggregated data objects"
+            },
+            "levels": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Ordered response labels, most negative to most positive (required). Odd count = center is neutral."
+            },
+            "categoryAccessor": {
+              "type": "string",
+              "description": "Question/item field (ordinal axis)",
+              "default": "question"
+            },
+            "valueAccessor": {
+              "type": "string",
+              "description": "Integer score field for raw response mode (1-based: score 1 → levels[0])",
+              "default": "score"
+            },
+            "levelAccessor": {
+              "type": "string",
+              "description": "Level name field for pre-aggregated mode. Each value must match an entry in levels."
+            },
+            "countAccessor": {
+              "type": "string",
+              "description": "Count/frequency field for pre-aggregated mode",
+              "default": "count"
+            },
+            "orientation": {
+              "type": "string",
+              "enum": [
+                "horizontal",
+                "vertical"
+              ],
+              "default": "horizontal"
+            },
+            "colorScheme": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "One color per level. Use a diverging palette (red → gray → blue). Defaults to Carbon-inspired diverging."
+            },
+            "barPadding": {
+              "type": "number",
+              "default": 20
+            },
+            "title": {
+              "type": "string"
+            },
+            "width": {
+              "type": "number",
+              "default": 600
+            },
+            "height": {
+              "type": "number",
+              "default": 400
+            },
+            "enableHover": {
+              "type": "boolean",
+              "default": true
+            },
+            "showLegend": {
+              "type": "boolean",
+              "default": true
+            },
+            "showGrid": {
+              "type": "boolean",
+              "default": false
+            },
+            "tooltip": {
+              "type": "boolean",
+              "default": true
+            }
+          },
+          "required": [
+            "levels"
+          ]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {
@@ -2508,10 +2602,6 @@
               "description": "Starting angle in radians",
               "default": 0
             },
-            "slicePadding": {
-              "type": "number",
-              "default": 2
-            },
             "title": {
               "type": "string"
             },
@@ -2623,10 +2713,6 @@
               "type": "number",
               "default": 0
             },
-            "slicePadding": {
-              "type": "number",
-              "default": 2
-            },
             "title": {
               "type": "string"
             },
@@ -4504,6 +4590,134 @@
           ]
         }
       }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "SwimlaneChart",
+        "description": "Categorical lanes with sequentially stacked items colored by subcategory. Unlike StackedBarChart, the same subcategory can appear multiple times in the same lane — items stack left-to-right (horizontal) or bottom-to-top (vertical) in data order. Supports brush for value-axis selection and push API for streaming.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": {
+              "type": "array",
+              "items": {
+                "type": "object"
+              },
+              "description": "Array of data objects. Omit for push API mode."
+            },
+            "categoryAccessor": {
+              "type": "string",
+              "description": "Key for lane categories (swim lanes)",
+              "default": "category"
+            },
+            "subcategoryAccessor": {
+              "type": "string",
+              "description": "Key for item subcategory (color grouping within lanes). Required. Duplicate subcategories in the same lane stack sequentially."
+            },
+            "valueAccessor": {
+              "type": "string",
+              "description": "Key for item size/duration along the value axis",
+              "default": "value"
+            },
+            "colorBy": {
+              "type": "string",
+              "description": "Key to determine color encoding. Defaults to subcategoryAccessor."
+            },
+            "colorScheme": {
+              "type": [
+                "string",
+                "array"
+              ],
+              "description": "Named d3 color scheme or array of color strings"
+            },
+            "orientation": {
+              "type": "string",
+              "enum": ["horizontal", "vertical"],
+              "description": "Horizontal renders lanes as rows; vertical as columns.",
+              "default": "horizontal"
+            },
+            "barPadding": {
+              "type": "number",
+              "description": "Padding between lanes in pixels",
+              "default": 40
+            },
+            "brush": {
+              "type": "boolean",
+              "description": "Enable value-axis brush selection"
+            },
+            "onBrush": {
+              "type": "function",
+              "description": "Callback with { r: [min, max] } or null when brush clears"
+            },
+            "linkedBrush": {
+              "type": [
+                "string",
+                "object"
+              ],
+              "description": "LinkedCharts brush integration name"
+            },
+            "showCategoryTicks": {
+              "type": "boolean",
+              "description": "Show lane labels on the category axis"
+            },
+            "annotations": {
+              "type": "array",
+              "description": "Annotation objects to render on the chart.",
+              "items": {
+                "type": "object"
+              }
+            },
+            "title": {
+              "type": "string"
+            },
+            "width": {
+              "type": "number",
+              "default": 600
+            },
+            "height": {
+              "type": "number",
+              "default": 400
+            },
+            "margin": {
+              "type": "object",
+              "description": "Chart margins: { top, right, bottom, left }"
+            },
+            "responsiveWidth": {
+              "type": "boolean",
+              "description": "Auto-resize to container width"
+            },
+            "tooltip": {
+              "type": [
+                "function",
+                "object"
+              ],
+              "description": "Tooltip content function or config."
+            },
+            "showLegend": {
+              "type": "boolean",
+              "description": "Show legend (auto-enabled with colorBy)"
+            },
+            "legendPosition": {
+              "type": "string",
+              "enum": [
+                "right",
+                "left",
+                "top",
+                "bottom"
+              ],
+              "default": "right"
+            },
+            "enableHover": {
+              "type": "boolean",
+              "default": true
+            }
+          },
+          "required": [
+            "subcategoryAccessor"
+          ]
+        }
+      }
     }
   ]
 }

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,20 +67,24 @@ 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 charts)
-- `annotations={[{ type: "y-threshold", value: 200, label: "SLA limit", color: "#e45050" }]}` — horizontal reference line
-- `annotations={[{ type: "x-threshold", value: 50, label: "Cutoff" }]}` — vertical reference line
+## 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
 
@@ -99,6 +105,8 @@ 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.
+
 `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`.

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 {};