semiotic-react-dataviz-cursorrules-prompt-file

Semiotic — AI Assistant Guide

Quick Start

• Install: npm install semiotic
• Import: semiotic, semiotic/xy, semiotic/ordinal, semiotic/network, semiotic/geo, semiotic/realtime, semiotic/ai, semiotic/data, semiotic/server
• CLI: npx semiotic-ai [--schema|--compact|--examples|--doctor]
• MCP: npx semiotic-mcp
• Every HOC has a built-in error boundary (never blanks the page) and dev-mode validation warnings

Architecture

• HOC Charts: Simple props, sensible defaults. Stream Frames: Full control.
• Always use HOC charts (ForceDirectedGraph, SankeyDiagram, LineChart, RealtimeLineChart, ChoroplethMap, etc.) unless you need sophisticated control they don't expose. Stream Frames (StreamNetworkFrame, StreamXYFrame, StreamOrdinalFrame, StreamGeoFrame) are low-level escape hatches — they accept raw RealtimeNode/RealtimeEdge wrappers in callbacks, not your data objects directly.
• Every HOC accepts frameProps to pass through. TypeScript strict: true.

Common Props (all HOCs)

title, width (600), height (400), responsiveWidth, responsiveHeight, margin, className, enableHover (true), tooltip (boolean | (datum) => ReactNode | config object), showLegend, showGrid (false), frameProps, onObservation (callback, see below), chartId, loading (false), emptyContent, legendInteraction ("none"|"highlight"|"isolate"), legendPosition ("right"|"left"|"top"|"bottom", default "right"), emphasis ("primary"|"secondary")

tooltip

tooltip accepts: true (default tooltip), false (disabled), a function (datum: Record<string, any>) => ReactNode, or a config { fields?: string[], title?: accessor, format?: fn, style?: CSSProperties }. The function form receives your raw data object directly.

onObservation

onObservation receives a ChartObservation with type and event-specific fields:

• hover: { type: "hover", datum: <your data>, x, y, timestamp, chartType, chartId }
• hover-end: { type: "hover-end", timestamp, chartType, chartId }
• click: { type: "click", datum: <your data>, x, y, timestamp, chartType, chartId }
• brush: { type: "brush", extent: { x: [min, max], y: [min, max] }, timestamp, chartType }
• selection: { type: "selection", selection: { name, fields }, timestamp, chartType }