semiotic 3.3.0 → 3.4.0

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- **Use sub-path imports** — `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB), `semiotic/server` (100KB), `semiotic/utils` (31KB), `semiotic/themes` (5KB), `semiotic/data` (5KB). Full `semiotic` is 278KB gz.
+- **Use sub-path imports** — `semiotic/xy` (78KB gz), `semiotic/ordinal` (65KB), `semiotic/network` (54KB), `semiotic/geo` (53KB), `semiotic/realtime` (77KB), `semiotic/server` (58KB), `semiotic/utils` (19KB), `semiotic/themes` (3KB), `semiotic/data` (3KB). Full `semiotic` is 158KB gz.
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
 
@@ -12,7 +12,7 @@
 - Every HOC accepts `frameProps` for pass-through. TypeScript `strict: true`. Every HOC has error boundary + dev-mode validation.
 
 ## Common Props (all HOCs)
-`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `enableHover` (true), `tooltip` (boolean | "multi" | function | config object), `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), `hoverHighlight` (boolean — dims non-hovered series, requires `colorBy`), `hoverRadius` (30)
+`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `enableHover` (true), `tooltip` (boolean | "multi" | function | config object), `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), `hoverHighlight` (boolean — dims non-hovered series, requires `colorBy`), `hoverRadius` (30), `animate` (boolean | { duration?, easing?, intro? } — animated intro on first render + smooth transitions on data change; intro defaults to true when animate is enabled)
 
 `onClick` receives `(datum, { x, y })`. `onObservation` receives `{ type, datum?, x?, y?, timestamp, chartType, chartId }`.
 
@@ -27,18 +27,20 @@
 **QuadrantChart** — Scatterplot + `quadrants` (required), `xCenter`, `yCenter`
 **MultiAxisLineChart** — Dual Y-axis. `series` (required: `[{ yAccessor, label?, color?, format?, extent? }]`). Falls back to multi-line if not 2 series.
 **Heatmap** — `data`, `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `showValues`, `cellBorderColor`
+**ScatterplotMatrix** — `data`, `fields` (array of numeric field names for grid)
+**MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart.
 
 ## Ordinal Charts (`semiotic/ordinal`)
 
 **BarChart** — `data`, `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40)
-**StackedBarChart** — + `stackBy` (required), `normalize`
-**GroupedBarChart** — + `groupBy` (required), `barPadding` (60)
+**StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (default false — insertion order)
+**GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (default false — insertion order)
 **SwarmPlot** — `colorBy`, `sizeBy`, `pointRadius`, `pointOpacity`
 **BoxPlot** — + `showOutliers`, `outlierRadius`
 **Histogram** — + `bins` (25), `relative`. Always horizontal.
 **ViolinPlot** — + `bins`, `curve`, `showIQR`
 **RidgelinePlot** — + `bins`, `amplitude` (1.5)
-**DotPlot** — + `sort` (true), `dotRadius`, `showGrid` default true
+**DotPlot** — + `sort` ("auto" — insertion order when streaming, value-desc on static), `dotRadius`, `showGrid` default true
 **PieChart** — `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`
 **DonutChart** — PieChart + `innerRadius` (60), `centerContent`
 **FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor` (optional), `connectorOpacity`, `orientation`
@@ -84,20 +86,23 @@ Most HOCs support push via `forwardRef`. **Omit** `data` — do NOT pass `data={
 const ref = useRef()
 ref.current.push({ id: "p1", x: 1, y: 2 })
 ref.current.pushMany([...points])
+ref.current.replace([...points])                   // ordinal only — full dataset replacement, preserves category order + transitions (progressively chunks large datasets)
 ref.current.remove("p1")                          // by ID — requires pointIdAccessor
 ref.current.remove(["p1", "p2"])                   // batch remove
 ref.current.update("p1", d => ({ ...d, y: 99 }))  // in-place update — requires pointIdAccessor
 ref.current.clear()
 ref.current.getData()
+ref.current.getScales()                            // returns {o, r, projection} (ordinal) / {x, y} (XY) — null if not yet computed
 <Scatterplot ref={ref} xAccessor="x" yAccessor="y" pointIdAccessor="id" />
 ```
-`remove()` and `update()` require an ID accessor: `pointIdAccessor` on XY/realtime charts, `dataIdAccessor` on ordinal charts. Network HOC refs also use `remove(id)`/`update(id, updater)` (operates on nodes). For edge-level operations, use `StreamNetworkFrameHandle` directly: `removeNode(id)`, `removeEdge(sourceId, targetId)`, `updateNode(id, updater)`, `updateEdge(sourceId, targetId, updater)`.
+`remove()` and `update()` require an ID accessor: `pointIdAccessor` on XY/realtime charts, `dataIdAccessor` on ordinal charts. `replace()` is ordinal-only and routes through a bounded-ingest path that preserves category insertion-order memory and the transition position snapshot — what aggregator HOCs like LikertChart use under the hood to re-aggregate streaming input without shuffling categories or losing animations. Network HOC refs also use `remove(id)`/`update(id, updater)` (operates on nodes). For edge-level operations, use `StreamNetworkFrameHandle` directly: `removeNode(id)`, `removeEdge(sourceId, targetId)` or `removeEdge(edgeId)` (requires `edgeIdAccessor`), `updateNode(id, updater)`, `updateEdge(sourceId, targetId, updater)`.
 Not supported: Tree, Treemap, CirclePack, Orbit, ChoroplethMap, FlowMap, ScatterplotMatrix.
 
 ## Coordinated Views
 
 **LinkedCharts** — `selections`, **CategoryColorProvider** — `colors`|`categories` + `colorScheme`
 Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`
+**Shared categories inside LinkedCharts → wrap in `CategoryColorProvider`.** When two or more charts encode the same categorical field (e.g. both `colorBy="region"`), wrapping in `CategoryColorProvider` gives every chart identical colors per category AND makes `LinkedCharts` render one unified legend (and suppress individual chart legends). Without it, each chart renders its own legend independently — often with mismatched colors.
 **Linked crosshair**: `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}`. Click-to-lock: click locks crosshair (dashed white), click/Escape unlocks.
 **ScatterplotMatrix**, **ChartContainer** (`title`, `subtitle`, `actions`), **ChartGrid** (`columns`, `gap`), **ContextLayout**
 
@@ -150,7 +155,7 @@ All HOCs accept `annotations` (array). Coordinates use data field names.
 
 ## Theming
 
-CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-secondary`, `--semiotic-border`, `--semiotic-grid`, `--semiotic-primary`, `--semiotic-focus`, `--semiotic-font-family`, `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
+CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-secondary`, `--semiotic-border`, `--semiotic-grid`, `--semiotic-primary`, `--semiotic-focus`, `--semiotic-font-family`, `--semiotic-annotation-color`, `--semiotic-legend-font-size`, `--semiotic-title-font-size`, `--semiotic-tick-font-family`, `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
 
 ```jsx
 <ThemeProvider theme="tufte">       {/* Named preset */}
@@ -174,6 +179,9 @@ Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveTh
 - **Legend**: "bottom" expands margin ~80px. MultiAxisLineChart: use `legendPosition="bottom"`.
 - **Log scale**: Domain min clamped to 1e-6.
 - **barPadding**: Pixel value (40/60 default). Reduce for small charts.
+- **sort on StackedBarChart/GroupedBarChart**: Default `false` preserves insertion order. The underlying frame defaults to value-descending if `oSort` is undefined, so always pass `sort` explicitly if order matters.
+- **sort `"auto"`** (BarChart/StackedBarChart/GroupedBarChart/DotPlot): insertion order while streaming, value-desc on static data. The right choice when using the push API — avoids categories shuffling as values fluctuate. DotPlot's default; opt-in on others.
+- **Tooltip format cascade**: `valueFormat` (ordinal) / `xFormat` / `yFormat` (XY) / `valueFormat` on Heatmap flow to the default tooltip automatically, so axis and tooltip read identically. Only applies to the default tooltip — a custom `tooltip` prop fully overrides; re-pass the formatter inside `Tooltip({format})` / `MultiLineTooltip({fields:[{format}]})` if you want it there. Bespoke-tooltip charts (Histogram, FunnelChart, LikertChart, GaugeChart) don't participate; customize via `tooltip`.
 - **Horizontal bars**: Need wider left margin: `margin={{ left: 120 }}`.
 - **Push API**: Omit `data` entirely. `data={[]}` clears on every render.
 - **frameProps style functions**: Bypass HOC color resolution — use `colorBy` prop instead.
@@ -186,6 +194,7 @@ Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveTh
 - **scalePadding**: Pixel inset on scale ranges. Pass via `frameProps={{ scalePadding: 12 }}`.
 - **categoryFormat/xFormat/yFormat**: Can return ReactNode (renders in `<foreignObject>`).
 - **Tick deduplication**: Adjacent identical labels auto-removed.
+- **Composing overlays**: XY/Ordinal charts paint `--semiotic-bg` across the full canvas by default, hiding anything beneath. When stacking charts (e.g. `position: absolute` overlay on top of a base), pass `frameProps={{ background: "transparent" }}` on the overlay to skip the fill. Network/Geo frames don't paint bg by default, so this only matters for XY/Ordinal.
 
 ## 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 38 chart components, optimized for LLM code generation
+- **`semiotic/ai`** — a single import with 35 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
 - **`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

package/ai/dist/mcp-server.js

@@ -24642,10 +24642,9 @@ var ProgressTokenSchema = union([string2(), number2().int()]);
 var CursorSchema = string2();
 var TaskCreationParamsSchema = looseObject({
   /**
-   * Time in milliseconds to keep task results available after completion.
-   * If null, the task has unlimited lifetime until manually cleaned up.
+   * Requested duration in milliseconds to retain task from creation.
    */
-  ttl: union([number2(), _null3()]).optional(),
+  ttl: number2().optional(),
   /**
    * Time in milliseconds to wait between task status requests.
    */
@@ -24945,7 +24944,11 @@ var ClientCapabilitiesSchema = object2({
   /**
    * Present if the client supports task creation.
    */
-  tasks: ClientTasksCapabilitySchema.optional()
+  tasks: ClientTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the client supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeRequestParamsSchema = BaseRequestParamsSchema.extend({
   /**
@@ -25007,7 +25010,11 @@ var ServerCapabilitiesSchema = object2({
   /**
    * Present if the server supports task creation.
    */
-  tasks: ServerTasksCapabilitySchema.optional()
+  tasks: ServerTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeResultSchema = ResultSchema.extend({
   /**
@@ -25199,6 +25206,12 @@ var ResourceSchema = object2({
    * The MIME type of this resource, if known.
    */
   mimeType: optional(string2()),
+  /**
+   * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+   *
+   * This can be used by Hosts to display file sizes and estimate context window usage.
+   */
+  size: optional(number2()),
   /**
    * Optional annotations for the client.
    */
@@ -27694,6 +27707,10 @@ var Protocol = class {
     this._progressHandlers.clear();
     this._taskProgressTokens.clear();
     this._pendingDebouncedNotifications.clear();
+    for (const info of this._timeoutInfo.values()) {
+      clearTimeout(info.timeoutId);
+    }
+    this._timeoutInfo.clear();
     for (const controller of this._requestHandlerAbortControllers.values()) {
       controller.abort();
     }
@@ -27824,7 +27841,9 @@ var Protocol = class {
         await capturedTransport?.send(errorResponse);
       }
     }).catch((error48) => this._onerror(new Error(`Failed to send response: ${error48}`))).finally(() => {
-      this._requestHandlerAbortControllers.delete(request.id);
+      if (this._requestHandlerAbortControllers.get(request.id) === abortController) {
+        this._requestHandlerAbortControllers.delete(request.id);
+      }
     });
   }
   _onprogress(notification) {
@@ -29837,6 +29856,9 @@ var McpServer = class {
           annotations = rest.shift();
         }
       } else if (typeof firstArg === "object" && firstArg !== null) {
+        if (Object.values(firstArg).some((v) => typeof v === "object" && v !== null)) {
+          throw new Error(`Tool ${name} expected a Zod schema or ToolAnnotations, but received an unrecognized object`);
+        }
         annotations = rest.shift();
       }
     }
@@ -29955,6 +29977,9 @@ function getZodSchemaObject(schema2) {
   if (isZodRawShapeCompat(schema2)) {
     return objectFromShape(schema2);
   }
+  if (!isZodSchemaInstance(schema2)) {
+    throw new Error("inputSchema must be a Zod schema or raw shape, received an unrecognized object");
+  }
   return schema2;
 }
 function promptArgumentsFromSchema(schema2) {
@@ -30240,6 +30265,17 @@ var requestPrototype = {
     }
   });
 });
+Object.defineProperty(requestPrototype, /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom"), {
+  value: function(depth, options, inspectFn) {
+    const props = {
+      method: this.method,
+      url: this.url,
+      headers: this.headers,
+      nativeRequest: this[requestCache]
+    };
+    return `Request (lightweight) ${inspectFn(props, { ...options, depth: depth == null ? null : depth - 1 })}`;
+  }
+});
 Object.setPrototypeOf(requestPrototype, Request.prototype);
 var newRequest = (incoming, defaultHostname) => {
   const req = Object.create(requestPrototype);
@@ -30344,6 +30380,17 @@ var Response2 = class _Response {
     }
   });
 });
+Object.defineProperty(Response2.prototype, /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom"), {
+  value: function(depth, options, inspectFn) {
+    const props = {
+      status: this.status,
+      headers: this.headers,
+      ok: this.ok,
+      nativeResponse: this[responseCache]
+    };
+    return `Response (lightweight) ${inspectFn(props, { ...options, depth: depth == null ? null : depth - 1 })}`;
+  }
+});
 Object.setPrototypeOf(Response2, GlobalResponse);
 Object.setPrototypeOf(Response2.prototype, GlobalResponse.prototype);
 async function readWithoutBlocking(readPromise) {
@@ -30415,6 +30462,50 @@ if (typeof global.crypto === "undefined") {
   global.crypto = import_crypto.default;
 }
 var outgoingEnded = /* @__PURE__ */ Symbol("outgoingEnded");
+var incomingDraining = /* @__PURE__ */ Symbol("incomingDraining");
+var DRAIN_TIMEOUT_MS = 500;
+var MAX_DRAIN_BYTES = 64 * 1024 * 1024;
+var drainIncoming = (incoming) => {
+  const incomingWithDrainState = incoming;
+  if (incoming.destroyed || incomingWithDrainState[incomingDraining]) {
+    return;
+  }
+  incomingWithDrainState[incomingDraining] = true;
+  if (incoming instanceof import_http2.Http2ServerRequest) {
+    try {
+      ;
+      incoming.stream?.close?.(import_http2.constants.NGHTTP2_NO_ERROR);
+    } catch {
+    }
+    return;
+  }
+  let bytesRead = 0;
+  const cleanup = () => {
+    clearTimeout(timer);
+    incoming.off("data", onData);
+    incoming.off("end", cleanup);
+    incoming.off("error", cleanup);
+  };
+  const forceClose = () => {
+    cleanup();
+    const socket = incoming.socket;
+    if (socket && !socket.destroyed) {
+      socket.destroySoon();
+    }
+  };
+  const timer = setTimeout(forceClose, DRAIN_TIMEOUT_MS);
+  timer.unref?.();
+  const onData = (chunk) => {
+    bytesRead += chunk.length;
+    if (bytesRead > MAX_DRAIN_BYTES) {
+      forceClose();
+    }
+  };
+  incoming.on("data", onData);
+  incoming.on("end", cleanup);
+  incoming.on("error", cleanup);
+  incoming.resume();
+};
 var handleRequestError = () => new Response(null, {
   status: 400
 });
@@ -30586,14 +30677,18 @@ var getRequestListener = (fetchCallback, options = {}) => {
               setTimeout(() => {
                 if (!incomingEnded) {
                   setTimeout(() => {
-                    incoming.destroy();
-                    outgoing.destroy();
+                    drainIncoming(incoming);
                   });
                 }
               });
             }
           };
         }
+        outgoing.on("finish", () => {
+          if (!incomingEnded) {
+            drainIncoming(incoming);
+          }
+        });
       }
       outgoing.on("close", () => {
         const abortController = req[abortControllerKey];
@@ -30608,7 +30703,7 @@ var getRequestListener = (fetchCallback, options = {}) => {
           setTimeout(() => {
             if (!incomingEnded) {
               setTimeout(() => {
-                incoming.destroy();
+                drainIncoming(incoming);
               });
             }
           });

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -4793,6 +4793,102 @@
           ]
         }
       }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "ScatterplotMatrix",
+        "description": "Multi-panel scatterplot grid with crossfilter brushing. Requires data array with numeric fields.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": { "type": "array" },
+            "fields": { "type": "array", "items": { "type": "string" } }
+          },
+          "required": ["data", "fields"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "MinimapChart",
+        "description": "Overview + detail chart with linked zoom. Wraps an XY chart with a minimap navigation pane.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": { "type": "array" }
+          },
+          "required": ["data"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "ChoroplethMap",
+        "description": "Geographic choropleth map with colored regions based on data values.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "areas": { "type": ["array", "string"], "description": "GeoJSON features or reference geography name" },
+            "valueAccessor": { "type": "string" },
+            "colorScheme": { "type": "string" },
+            "projection": { "type": "string", "default": "equalEarth" }
+          },
+          "required": ["areas"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "ProportionalSymbolMap",
+        "description": "Geographic map with sized symbols at point locations.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "points": { "type": "array" },
+            "xAccessor": { "type": "string", "default": "lon" },
+            "yAccessor": { "type": "string", "default": "lat" },
+            "sizeBy": { "type": "string" },
+            "areas": { "type": ["array", "string"] }
+          },
+          "required": ["points"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "FlowMap",
+        "description": "Geographic flow map showing movement between locations with animated particles.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "flows": { "type": "array" },
+            "nodes": { "type": "array" },
+            "valueAccessor": { "type": "string" }
+          },
+          "required": ["flows"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "DistanceCartogram",
+        "description": "Cartogram distorting geographic positions based on travel time or cost from a center point.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "points": { "type": "array" },
+            "center": { "type": "array" },
+            "costAccessor": { "type": "string" }
+          },
+          "required": ["points"]
+        }
+      }
     }
   ]
 }

package/dist/components/LinkedCharts.d.ts

@@ -44,6 +44,14 @@ export interface LinkedChartsProps {
      */
     legendField?: string;
 }
+/**
+ * Mirror of the wrap logic in Legend's renderLegendGroupHorizontal:
+ * itemWidth = SWATCH(16) + 10 + label.length * 7, wrap when the cursor
+ * would exceed maxWidth. Used only to size the container SVG — the
+ * authoritative layout still happens inside <Legend>. When width is
+ * unknown (e.g. first paint, SSR), return 1 so we don't pre-grow.
+ */
+export declare function estimateLegendRowCount(labels: string[], width: number): number;
 /**
  * LinkedCharts — context provider for coordinated chart views.
  *

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

@@ -33,7 +33,7 @@ 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 type { LikertChartProps, LikertChartHandle } from "./ordinal/LikertChart";
 export { SwarmPlot } from "./ordinal/SwarmPlot";
 export type { SwarmPlotProps } from "./ordinal/SwarmPlot";
 export { BoxPlot } from "./ordinal/BoxPlot";

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

@@ -17,8 +17,16 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
-    sort?: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number);
+    /** Category ordering. `false` (default) = insertion order. `"asc"` /
+     *  `"desc"` sorts by total value. `"auto"` preserves insertion order
+     *  while streaming and falls through to value-desc on static data.
+     *  `true` = value-desc regardless of source. Function comparators
+     *  receive category name strings (not row objects) and run against
+     *  the category list on the axis. */
+    sort?: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number);
     barPadding?: number;
+    /** Rounded top corner radius in pixels. Only the end away from the baseline is rounded. */
+    roundedTop?: number;
     /** When true, adds padding below the 0 baseline. Default false (bars flush with axis). */
     baselinePadding?: boolean;
     enableHover?: boolean;

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

@@ -13,6 +13,8 @@ export interface DonutChartProps<TDatum extends Record<string, any> = Record<str
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     startAngle?: number;
+    /** Rounded corner radius on wedge arcs */
+    cornerRadius?: number;
     enableHover?: boolean;
     showCategoryTicks?: boolean;
     showLegend?: boolean;

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

@@ -14,7 +14,15 @@ export interface DotPlotProps<TDatum extends Record<string, any> = Record<string
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
-    sort?: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number);
+    /** Category ordering. Default (`undefined`) resolves to `"auto"`, which
+     *  preserves insertion order while streaming and falls through to
+     *  value-desc on static data — the recommended choice when using the
+     *  push API so categories don't jump around as values fluctuate.
+     *  `true` forces value-desc regardless of source. `"asc"` / `"desc"`
+     *  sorts by total value. `false` for insertion order regardless of
+     *  source. Function comparators receive category name strings (not
+     *  row objects) and run against the category list on the axis. */
+    sort?: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number);
     dotRadius?: number;
     categoryPadding?: number;
     enableHover?: boolean;

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

@@ -15,7 +15,11 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
+    /** Category sort order. Default: `false` (data insertion order). `"asc"`/`"desc"` sorts by total grouped value. `"auto"` preserves insertion order while streaming and falls through to value-desc on static data. Custom comparators receive category keys. */
+    sort?: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number);
     barPadding?: number;
+    /** Rounded corner radius on bar ends (away from baseline). */
+    roundedTop?: number;
     baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;

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

@@ -1,5 +1,5 @@
 import * as React from "react";
-import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -88,7 +88,10 @@ export interface LikertChartProps<TDatum extends Record<string, any> = Record<st
     categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
+export interface LikertChartHandle extends RealtimeFrameHandle {
+    getScales(): ReturnType<NonNullable<StreamOrdinalFrameHandle["getScales"]>>;
+}
 export declare const LikertChart: {
-    <TDatum extends Record<string, any> = Record<string, any>>(props: LikertChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    <TDatum extends Record<string, any> = Record<string, any>>(props: LikertChartProps<TDatum> & React.RefAttributes<LikertChartHandle>): React.ReactElement | null;
     displayName?: string;
 };

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

@@ -11,6 +11,8 @@ export interface PieChartProps<TDatum extends Record<string, any> = Record<strin
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     startAngle?: number;
+    /** Rounded corner radius on wedge arcs */
+    cornerRadius?: number;
     enableHover?: boolean;
     showCategoryTicks?: boolean;
     showLegend?: boolean;

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

@@ -16,7 +16,11 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     normalize?: boolean;
+    /** Category sort order. Default: `false` (data insertion order). `"asc"`/`"desc"` sorts by total stacked value. `"auto"` preserves insertion order while streaming and falls through to value-desc on static data. Custom comparators receive category keys. */
+    sort?: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number);
     barPadding?: number;
+    /** Rounded top corner radius. Only the topmost stacked segment gets rounded. */
+    roundedTop?: number;
     baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;

package/dist/components/charts/shared/hooks.d.ts

@@ -33,8 +33,17 @@ export declare function useColorScale(data: Array<Record<string, any>>, colorBy:
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
+ *
+ * `"auto"` and function comparators are pass-through here. The frame-
+ * level `resolveCategories` decides the visual category order:
+ *   • `"auto"` → insertion order when streaming, value-desc when static.
+ *   • function → runs as a category-key comparator on the axis list.
+ * The HOC's row-level `data` order only seeds insertion order via the
+ * store's category Set; rearranging rows with a category comparator
+ * makes no sense (it would call the comparator with row objects instead
+ * of strings), so we decline to sort in both cases.
  */
-export declare function useSortedData(data: Array<Record<string, any>>, sort: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number), valueAccessor: Accessor<number>): Array<Record<string, any>>;
+export declare function useSortedData(data: Array<Record<string, any>>, sort: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number), valueAccessor: Accessor<number>): Array<Record<string, any>>;
 /**
  * Hook to set up selection and linked hover for a chart component.
  * Consolidates normalizeLinkedHover, useSelection, useLinkedHover,
@@ -121,7 +130,11 @@ export interface LegendInteractionState {
 }
 /**
  * Hook managing legend highlight/isolate interaction.
- * - "highlight": hover over legend item dims everything else to 30% opacity
+ * - "highlight": hover over a legend item produces a selection hook that
+ *   `wrapStyleWithSelection` uses to dim non-matching data. The actual
+ *   dim opacity resolves in this order: per-chart
+ *   `selection.unselectedOpacity` → `theme.colors.selectionOpacity` →
+ *   `DEFAULT_SELECTION_OPACITY` fallback.
  * - "isolate": click toggles category visibility; click all to reset
  */
 export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: any) => string) | undefined, allCategories: string[]): LegendInteractionState;

package/dist/components/charts/shared/selectionUtils.d.ts

@@ -48,19 +48,21 @@ export interface SelectionStyleConfig {
     unselectedStyle?: Record<string, any>;
     selectedStyle?: Record<string, any>;
 }
-/** Default opacity for unselected (dimmed) elements */
-export declare const DEFAULT_SELECTION_OPACITY = 0.2;
 /**
- * Read the --semiotic-selection-opacity CSS variable from a container element.
- * Returns the numeric value or the default if not set or not parseable.
+ * Library fallback opacity for unselected (dimmed) elements.
+ *
+ * This is the last-resort value when nothing else supplies one. Clients
+ * control the effective default declaratively through `ThemeProvider`'s
+ * `colors.selectionOpacity` (built-in presets set this). Per-chart
+ * `selection.unselectedOpacity` still overrides the theme value.
  */
-export declare function readSelectionOpacityFromCSS(container: Element | null): number;
+export declare const DEFAULT_SELECTION_OPACITY = 0.5;
 /**
  * Wrap a base style function with selection awareness.
  * When a selection is active, non-matching datums get dimmed.
  *
  * Dimming opacity is resolved in this order:
- * 1. `config.unselectedOpacity` (explicit prop)
- * 2. `DEFAULT_SELECTION_OPACITY` (0.2)
+ * 1. `config.unselectedOpacity` (explicit, usually per-chart or theme-merged)
+ * 2. `DEFAULT_SELECTION_OPACITY`
  */
 export declare function wrapStyleWithSelection(baseStyleFn: (d: Record<string, any>) => Record<string, any>, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Record<string, any>) => Record<string, any>;

package/dist/components/charts/shared/tooltipUtils.d.ts

@@ -4,6 +4,14 @@ export interface TooltipFieldConfig {
     label: string;
     accessor: string | ((d: any) => any);
     role?: "title" | "x" | "y" | "color" | "size" | "group" | "value";
+    /** Per-field formatter. HOCs pass `xFormat`/`yFormat`/`valueFormat` here so
+     *  the default tooltip renders values consistently with the axis. Typed
+     *  permissively (`any` → `ReactNode`) to match the mixed formatter
+     *  signatures across ordinal (`(d: string | number) => string`) and XY
+     *  (`(d, index?, allTicks?) => ReactNode`). A ReactNode return renders
+     *  as-is in the tooltip span. If the formatter throws, the tooltip
+     *  falls back to the built-in `formatVal`. */
+    format?: (v: any, ...rest: any[]) => React.ReactNode;
 }
 /**
  * Extract a display name from an accessor.
@@ -25,10 +33,14 @@ export declare function buildDefaultTooltip(fields: TooltipFieldConfig[]): (hove
  * @param pieData - If true, extracts datum via `d.data?.[0] || d.data || d`
  *   (PieChart/DonutChart wrap data in arrays). Default: `d.data || d`.
  */
-export declare function buildOrdinalTooltip({ categoryAccessor, valueAccessor, groupAccessor, groupLabel, pieData, }: {
+export declare function buildOrdinalTooltip({ categoryAccessor, valueAccessor, groupAccessor, groupLabel, pieData, valueFormat, }: {
     categoryAccessor: string | ((d: any) => any);
     valueAccessor: string | ((d: any) => any);
     groupAccessor?: string | ((d: any) => any);
     groupLabel?: string;
     pieData?: boolean;
+    /** Same formatter the HOC passes to the value axis. Threaded here so the
+     *  default tooltip shows values consistently with the axis ("$450k", not
+     *  "450000"). Override by passing a custom `tooltip` prop. */
+    valueFormat?: (v: any, ...rest: any[]) => React.ReactNode;
 }): (d: Record<string, any>) => React.ReactNode;