semiotic 2.0.3 → 3.0.0-beta.2

package/README.md

@@ -1,70 +1,248 @@
 [![Semiotic](semiotic_logo_horizontal.png "semiotic")](https://semiotic.nteract.io)
 
-[![Semiotic](https://github.com/nteract/semiotic/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/nteract/semiotic/actions/workflows/node.js.yml)
+[![CI](https://github.com/nteract/semiotic/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/nteract/semiotic/actions/workflows/node.js.yml)
+[![npm version](https://img.shields.io/npm/v/semiotic.svg)](https://www.npmjs.com/package/semiotic)
+[![TypeScript](https://img.shields.io/badge/TypeScript-built--in-blue.svg)](https://www.typescriptlang.org/)
 
-Semiotic is a data visualization framework combining React & D3.
+A React data visualization library for charts, networks, and beyond.
 
-## Documentation
+Simple charts in 5 lines. Force-directed graphs, Sankey diagrams, treemaps,
+and chord diagrams when you need them. Full D3-level control when you want it.
+
+```jsx
+import { LineChart } from "semiotic"
+
+<LineChart
+  data={salesData}
+  xAccessor="month"
+  yAccessor="revenue"
+/>
+```
+
+## Why Semiotic
+
+Most React charting libraries give you bar charts, line charts, and pie charts.
+Semiotic gives you those too — but it's built for the projects where those
+aren't enough.
+
+### When you need more than standard charts
+
+**Network visualization.** Show how things connect — org charts,
+dependency graphs, budget flows, taxonomies. Semiotic has force-directed
+graphs, Sankey diagrams, chord diagrams, tree layouts, treemaps, and circle
+packing as React components with the same prop API as LineChart.
+
+**Streaming data.** Monitor live systems — server metrics, sensor feeds,
+financial tickers. Semiotic's realtime charts render on canvas at 60fps with
+a ref-based push API. Old data fades out (decay), new data flashes in
+(pulse), and stale feeds are flagged automatically.
+
+**Coordinated dashboards.** Hover one chart, highlight matching data in
+others. Brush a scatterplot, filter a bar chart. Semiotic's `LinkedCharts`
+and `ScatterplotMatrix` provide crossfilter coordination that other libraries
+leave you to build from scratch.
+
+**Statistical summaries.** Box plots, violin plots, swarm plots, ridgeline
+plots, histograms — the distribution charts that data scientists need and
+most charting libraries skip. Add marginal distribution graphics (histogram,
+violin, ridgeline, boxplot) to scatterplot margins with a single prop.
+
+### Start simple, go deep
+
+| Layer | For | Example |
+|---|---|---|
+| **Charts** | Common visualizations with sensible defaults | `<LineChart data={d} xAccessor="x" yAccessor="y" />` |
+| **Frames** | Full control over rendering, interaction, and layout | `<StreamXYFrame chartType="line" lineStyle={...} />` |
 
-[Interactive Documentation v1.x](https://semioticv1.nteract.io/)
+Every Chart component accepts a `frameProps` prop to access the underlying
+Frame API without leaving the simpler interface.
 
-[API Docs v1.x](https://semioticv1.nteract.io/api)
+### When to use something else
 
-[Interactive Examples v1.x](https://semioticv1.nteract.io/examples)
+Need a standard bar or line chart for a dashboard you'll never need to
+customize beyond colors and labels? [Recharts](https://recharts.org) has a
+larger ecosystem and more community examples. Need GPU-accelerated rendering
+for millions of data points? [Apache ECharts](https://echarts.apache.org)
+handles that scale.
 
-[Preview of Interactive Documentation for v2.x](https://semiotic.nteract.io)
+Semiotic is for projects that outgrow those libraries — when you need
+network graphs alongside time series, streaming data alongside static
+snapshots, or coordinated views across chart types.
 
-## Installation
+**AI-ready.** Semiotic ships with structured schemas (`ai/schema.json`), an
+`import from "semiotic/ai"` entry point, and an MCP server — all designed for
+LLM code generation. AI coding assistants can generate correct Semiotic code on
+the first try. Run `npx semiotic-ai --help` for CLI options or add `semiotic-mcp`
+to your MCP client config for tool-based chart rendering.
+
+## Install
 
 ```bash
-yarn install semiotic
+npm install semiotic
 ```
 
-## Usage Example
+Requires React 18.1 or later.
 
-As a library:
-```js
-import { XYFrame } from "semiotic"
+## Quick Examples
+
+### Coordinated Dashboard
+
+Hover one chart, highlight the same data in another — zero wiring:
+
+```jsx
+import { LinkedCharts, Scatterplot, BarChart } from "semiotic"
+
+<LinkedCharts>
+  <Scatterplot
+    data={data} xAccessor="age" yAccessor="income" colorBy="region"
+    linkedHover={{ name: "hl", fields: ["region"] }}
+    selection={{ name: "hl" }}
+  />
+  <BarChart
+    data={summary} categoryAccessor="region" valueAccessor="total"
+    selection={{ name: "hl" }}
+  />
+</LinkedCharts>
 ```
 
-You can also use the static distribution (via https://unpkg.com or https://esm.sh):
+### Streaming Metrics with Decay
+
+Live data fades old points, flashes new ones, flags stale feeds:
 
-```html
-<script type="module">
-	import { XYFrame } from "https://unpkg.com/semiotic?module"
-</script>
+```jsx
+import { RealtimeLineChart } from "semiotic"
+
+const chartRef = useRef()
+chartRef.current.push({ time: Date.now(), value: cpuLoad })
+
+<RealtimeLineChart
+  ref={chartRef}
+  timeAccessor="time"
+  valueAccessor="value"
+  decay={{ type: "exponential", halfLife: 100 }}
+  staleness={{ threshold: 5000, showBadge: true }}
+/>
 ```
 
-[These Codepen examples](https://codepen.io/emeeks/) use the static distribution.
+### Network Graphs
+
+Force-directed graphs and Sankey diagrams — same API as LineChart:
 
-## Project recognition
+```jsx
+import { ForceDirectedGraph, SankeyDiagram } from "semiotic"
 
-_Semiotic icon based on an icon by André Schauer_
+<ForceDirectedGraph
+  nodes={people} edges={friendships}
+  colorBy="team" nodeSize={8} showLabels
+/>
 
-It may not be apparent in the commit logs but development of this library owes a lot to:
+<SankeyDiagram
+  edges={budgetFlows}
+  sourceAccessor="from" targetAccessor="to" valueAccessor="amount"
+/>
+```
 
-* Susie Lu
-* Jason Reid
-* James Womack
-* Matt Herman
-* Shelby Sturgis
-* Tristan Reid
+### Standard Charts
 
-## Testing
+Line, bar, scatter, area — all the basics, with sensible defaults:
 
-Using BrowserStack for browser compatibility testing
-[![BrowserStack](browserstack_logo.png "browserstack")](http://browserstack.com/)
+```jsx
+import { LineChart, BarChart } from "semiotic"
 
-## Changelog
+<LineChart
+  data={salesData}
+  xAccessor="month" yAccessor="revenue"
+  curve="monotoneX" showPoints
+/>
 
-[Changelog](./CHANGELOG.md)
+<BarChart
+  data={categoryData}
+  categoryAccessor="department" valueAccessor="sales"
+  orientation="horizontal" colorBy="region"
+/>
+```
 
-## License
+## All Chart Components
 
-[License](./LICENSE)
+| Category | Components |
+|---|---|
+| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `BubbleChart` `Heatmap` |
+| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `DotPlot` `PieChart` `DonutChart` |
+| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` |
+| **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
+| **Coordination** | `LinkedCharts` `ScatterplotMatrix` |
+| **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` |
+
+## Smaller Bundles
+
+Import only what you need:
+
+```jsx
+import { LineChart } from "semiotic/xy"        // 125 KB (vs 218 KB full)
+import { BarChart } from "semiotic/ordinal"     // 140 KB
+import { ForceDirectedGraph } from "semiotic/network"  // 133 KB
+import { LineChart } from "semiotic/ai"           // HOC-only surface for AI generation
+```
+
+## TypeScript
+
+Full type definitions ship with the package. Generics for type-safe accessors:
+
+```tsx
+interface Sale { month: number; revenue: number }
+
+<LineChart<Sale>
+  data={sales}
+  xAccessor="month"    // TS validates this is keyof Sale
+  yAccessor="revenue"
+/>
+```
+
+## Server-Side Rendering
+
+Static SVG generation for Node.js (email, OG images, PDF):
+
+```js
+import { renderToStaticSVG } from "semiotic/server"
+
+const svg = renderToStaticSVG("xy", {
+  lines: [{ coordinates: data }],
+  xAccessor: "date",
+  yAccessor: "value",
+  size: [600, 400],
+})
+```
+
+Works with Next.js App Router, Remix, and Astro via `"use client"` directives.
+
+## Documentation
+
+[Interactive docs and examples](https://semiotic.nteract.io)
+
+- [Getting Started](https://semiotic.nteract.io/getting-started)
+- [Charts](https://semiotic.nteract.io/charts) — all 27 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
+- [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes
+- [Playground](https://semiotic.nteract.io/playground) — interactive prop exploration
+
+## Upgrading
+
+- [Migration Guide](./MIGRATION.md) — upgrading from v1.x or v2.x
+- [Changelog](./CHANGELOG.md) — full release history
 
 ## Contributing
 
-Our community follows the nteract [Contributor Code of Conduct](https://github.com/nteract/nteract/blob/main/CODE_OF_CONDUCT.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md). Our community follows the nteract
+[Code of Conduct](https://github.com/nteract/nteract/blob/main/CODE_OF_CONDUCT.md).
+
+## Acknowledgments
+
+Development of this library owes a lot to Susie Lu, Jason Reid, James Womack,
+Matt Herman, Shelby Sturgis, and Tristan Reid.
+
+_Semiotic icon based on an icon by Andre Schauer._
+
+## License
 
-If you are interested in contributing to the project, please read our [CONTRIBUTING.md](CONTRIBUTING.md) file.
+[Apache 2.0](./LICENSE)

package/ai/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const pkgRoot = path.resolve(__dirname, "..")
+
+const FILES = {
+  default: path.join(pkgRoot, "CLAUDE.md"),
+  "--schema": path.join(__dirname, "schema.json"),
+  "--compact": path.join(__dirname, "system-prompt.md"),
+  "--examples": path.join(__dirname, "examples.md"),
+}
+
+const HELP = `
+semiotic-ai — Dump Semiotic AI context to stdout
+
+Usage:
+  npx semiotic-ai              Print CLAUDE.md (full reference)
+  npx semiotic-ai --schema     Print ai/schema.json (tool definitions)
+  npx semiotic-ai --compact    Print ai/system-prompt.md (compact prompt)
+  npx semiotic-ai --examples   Print ai/examples.md (copy-paste examples)
+  npx semiotic-ai --help       Show this help message
+`.trim()
+
+const flag = process.argv[2]
+
+if (flag === "--help" || flag === "-h") {
+  console.log(HELP)
+  process.exit(0)
+}
+
+const filePath = flag ? FILES[flag] : FILES.default
+
+if (!filePath) {
+  console.error(`Unknown flag: ${flag}\n`)
+  console.error(HELP)
+  process.exit(1)
+}
+
+try {
+  const content = fs.readFileSync(filePath, "utf-8")
+  process.stdout.write(content)
+} catch (err) {
+  console.error(`Error reading ${filePath}: ${err.message}`)
+  process.exit(1)
+}

package/ai/dist/ai/componentRegistry.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPONENT_REGISTRY = void 0;
+const LineChart_1 = require("../src/components/charts/xy/LineChart");
+const AreaChart_1 = require("../src/components/charts/xy/AreaChart");
+const StackedAreaChart_1 = require("../src/components/charts/xy/StackedAreaChart");
+const Scatterplot_1 = require("../src/components/charts/xy/Scatterplot");
+const BubbleChart_1 = require("../src/components/charts/xy/BubbleChart");
+const Heatmap_1 = require("../src/components/charts/xy/Heatmap");
+const BarChart_1 = require("../src/components/charts/ordinal/BarChart");
+const StackedBarChart_1 = require("../src/components/charts/ordinal/StackedBarChart");
+const GroupedBarChart_1 = require("../src/components/charts/ordinal/GroupedBarChart");
+const SwarmPlot_1 = require("../src/components/charts/ordinal/SwarmPlot");
+const BoxPlot_1 = require("../src/components/charts/ordinal/BoxPlot");
+const DotPlot_1 = require("../src/components/charts/ordinal/DotPlot");
+const PieChart_1 = require("../src/components/charts/ordinal/PieChart");
+const DonutChart_1 = require("../src/components/charts/ordinal/DonutChart");
+const ForceDirectedGraph_1 = require("../src/components/charts/network/ForceDirectedGraph");
+const ChordDiagram_1 = require("../src/components/charts/network/ChordDiagram");
+const SankeyDiagram_1 = require("../src/components/charts/network/SankeyDiagram");
+const TreeDiagram_1 = require("../src/components/charts/network/TreeDiagram");
+const Treemap_1 = require("../src/components/charts/network/Treemap");
+const CirclePack_1 = require("../src/components/charts/network/CirclePack");
+exports.COMPONENT_REGISTRY = {
+    LineChart: { component: LineChart_1.LineChart, category: "xy" },
+    AreaChart: { component: AreaChart_1.AreaChart, category: "xy" },
+    StackedAreaChart: { component: StackedAreaChart_1.StackedAreaChart, category: "xy" },
+    Scatterplot: { component: Scatterplot_1.Scatterplot, category: "xy" },
+    BubbleChart: { component: BubbleChart_1.BubbleChart, category: "xy" },
+    Heatmap: { component: Heatmap_1.Heatmap, category: "xy" },
+    BarChart: { component: BarChart_1.BarChart, category: "ordinal" },
+    StackedBarChart: { component: StackedBarChart_1.StackedBarChart, category: "ordinal" },
+    GroupedBarChart: { component: GroupedBarChart_1.GroupedBarChart, category: "ordinal" },
+    SwarmPlot: { component: SwarmPlot_1.SwarmPlot, category: "ordinal" },
+    BoxPlot: { component: BoxPlot_1.BoxPlot, category: "ordinal" },
+    DotPlot: { component: DotPlot_1.DotPlot, category: "ordinal" },
+    PieChart: { component: PieChart_1.PieChart, category: "ordinal" },
+    DonutChart: { component: DonutChart_1.DonutChart, category: "ordinal" },
+    ForceDirectedGraph: { component: ForceDirectedGraph_1.ForceDirectedGraph, category: "network" },
+    ChordDiagram: { component: ChordDiagram_1.ChordDiagram, category: "network" },
+    SankeyDiagram: { component: SankeyDiagram_1.SankeyDiagram, category: "network" },
+    TreeDiagram: { component: TreeDiagram_1.TreeDiagram, category: "network" },
+    Treemap: { component: Treemap_1.Treemap, category: "network" },
+    CirclePack: { component: CirclePack_1.CirclePack, category: "network" },
+};

package/ai/dist/ai/mcp-server.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Semiotic MCP Server
+ *
+ * Exposes every HOC chart component as an MCP tool.
+ * Accepts component props as tool arguments, renders to static SVG,
+ * and returns the SVG string.
+ *
+ * Usage (Claude Desktop / claude_desktop_config.json):
+ * {
+ *   "mcpServers": {
+ *     "semiotic": {
+ *       "command": "npx",
+ *       "args": ["semiotic-mcp"]
+ *     }
+ *   }
+ * }
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const renderHOCToSVG_1 = require("./renderHOCToSVG");
+const componentRegistry_1 = require("./componentRegistry");
+// Load schema.json for tool definitions
+const schemaPath = path.resolve(__dirname, "schema.json");
+const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
+// Build MCP server
+const server = new mcp_js_1.McpServer({
+    name: "semiotic",
+    version: schema.version || "3.0.0",
+});
+// Register each chart component as a tool
+for (const toolDef of schema.tools) {
+    const { name, description, parameters } = toolDef.function;
+    // Skip realtime charts (ref-based, can't render to static SVG)
+    if (name.startsWith("Realtime"))
+        continue;
+    // Skip components not in registry
+    if (!componentRegistry_1.COMPONENT_REGISTRY[name])
+        continue;
+    // Register the tool — use raw z.any() style since we have our own validation
+    server.tool(name, description, {}, async (args) => {
+        const result = (0, renderHOCToSVG_1.renderHOCToSVG)(name, args);
+        if (result.error) {
+            return {
+                content: [{ type: "text", text: result.error }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: result.svg }],
+        };
+    });
+}
+// Start the server
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+});

package/ai/dist/ai/renderHOCToSVG.js

@@ -0,0 +1,77 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderHOCToSVG = renderHOCToSVG;
+/**
+ * Render a Semiotic HOC chart component to static SVG markup.
+ *
+ * Uses ReactDOMServer.renderToStaticMarkup which supports hooks
+ * (useMemo, custom hooks) used by the HOC components.
+ */
+const React = __importStar(require("react"));
+const ReactDOMServer = __importStar(require("react-dom/server"));
+const componentRegistry_1 = require("./componentRegistry");
+const validateProps_1 = require("../src/components/charts/shared/validateProps");
+function renderHOCToSVG(componentName, props) {
+    // Look up component
+    const entry = componentRegistry_1.COMPONENT_REGISTRY[componentName];
+    if (!entry) {
+        return {
+            svg: null,
+            error: `Unknown component "${componentName}". Available: ${Object.keys(componentRegistry_1.COMPONENT_REGISTRY).join(", ")}`,
+        };
+    }
+    // Validate props
+    const validation = (0, validateProps_1.validateProps)(componentName, props);
+    if (!validation.valid) {
+        return {
+            svg: null,
+            error: `Validation errors:\n${validation.errors.join("\n")}`,
+        };
+    }
+    // Disable hover (not useful in static SVG)
+    const renderProps = { ...props, enableHover: false };
+    try {
+        const element = React.createElement(entry.component, renderProps);
+        const svg = ReactDOMServer.renderToStaticMarkup(element);
+        return { svg, error: null };
+    }
+    catch (err) {
+        return {
+            svg: null,
+            error: `Render error: ${err.message || String(err)}`,
+        };
+    }
+}