Custom Charts — Recipe Kit — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/custom-charts/recipe-kit

Recipe Chrome Kit

A custom layout returns scene primitives and an overlays ReactNode painted on top (for the chrome the canvas doesn’t draw: labels, enclosures, callouts). Surveying the recipes, the same overlay chores recurred — so the building blocks live in one small, composable kit, exported from semiotic/recipes. They return plain SVG with pointer-events: none, so they decorate without intercepting canvas hit-testing, and they’re pure / SSR-safe.

Above: a roundedEnclosure sized by boundsOf, a leftbandLabel, and a markCallout with an elbow connector — the same pieces the Satellites in Space recipe uses for its orbit-band borders and named-satellite callouts.

The kit

Helper	Returns	Use
`roundedEnclosure(props)`	a rounded `<rect>`	a border around a group of marks (a cell, a row/column band, a cluster)
`boundsOf(points, pad)`	`{ x, y, width, height }`	the padded bounding box of a point set — the usual precursor to an enclosure
`bandLabel(props)`	a `<text>` (or null)	an axis/band label, suppressed when it would overflow `maxWidth`
`markCallout(props)`	a `<g>`: ring + connector + label	an editorial leader-line callout to a specific mark a layout emitted
`linearAxis(props)`	a `<g>` of ticks	a tick axis + gridlines from any scale — the bespoke-scale escape hatch when `showAxes` can’t apply
`legendSwatches(props)`	a `<g>` of swatch rows	a portable SVG legend in `overlays` — fill / line / shape / hatch swatches (sibling to `legendGroupsFrom`, which feeds the frame legend)
`hatchFill(opts)`	`{ def, fill }`	an SVG `<pattern>` for percentile / uncertainty bands, shared by the chart band and its legend swatch (SVG analogue of`createHatchPattern`)
`readField(node, key, fallback)`	the value	read `node.data.<key>` (the network ingest wrapper) or the node itself
`dimFor(datum, opts)`	an opacity	the highlight/dim rule: lit marks (matching `highlight` AND`predicate`) stay bright, the rest fall to `dimOpacity`
`signatureKey` / `LayoutCache`	a key / a cache	content-signature geometry cache — re-style on interaction without re-running an expensive layout
`legendGroupsFrom(input)`	`LegendGroup[]`	build the legend a custom layout passes through `frameProps.legend`(color / symbol / size channels)
`shade` / `makeShade`	a color	perceptual (CIELAB) lightness ramp on a hue — a continuous channel
`symbolPathString` / `symbolExtent`	a path string / radius	glyph path + true extent (seeGlyph Marks)

Scene nodes, geometry & data helpers

Beyond overlay chrome, the kit ships the pure pieces a hand-built custom chart kept re-deriving — so a layout assembles geometry from named, tested functions instead of inlining trigonometry and bezier control points.

Helper	Family	Use
`hitTargetPoint` / `hitTargetRect`	xy / ordinal	a transparent, hit-tested scene node so a layout that draws its marks in`overlays` still earns keyboard nav + focus ring (a11y),`onObservation` + selection, and transition identity; point-like helpers also provide `pointId` annotation anchoring
`geoHitTarget` / `geoAreaHitTarget`	geo	transparent point or polygon scene nodes for custom GeoFrame overlays, preserving hover, keyboard focus, tooltips, accessible rows, and observation callbacks
`networkHitTarget`	network	transparent circle or rect scene nodes for network custom overlays, with stable node identity for annotation anchoring and linked interaction
`polarToXY` / `xyToAngle` / `angleScale` /`radiusScale` / `ringArcPath`	radial	angle ⟂ radius for a two-continuous-channel radial chart (0 = up, clockwise);`ringArcPath` draws annular sectors, wedges, and full rings
`curvedEdgePath` / `orthogonalEdgePath` /`boxEdgeAnchors` / `fanOutBend`	network	edge SVG paths: S-curve (with side-bow) or elbow, box exit/entry points by direction, and a fan-out bend so parallel edges don’t overlap
`cubicPoint` / `cubicTangent` / `cubicPath`	network	evaluate a cubic Bézier — sample a point or tangent along a `CubicCurve`to seat a mark on the curve (a node mid-edge, an arrowhead), or serialize it to an SVG path
`addPoints` / `subtractPoints` / `scalePoint` /`pointMagnitude` / `normalizePoint`	any	2D point/vector math — an edge offset normal to its tangent, a radial spoke, a leader line; composes with the radial + edge kits
`allocateCells`	any	largest-remainder grid allocation: `{key, weight}[]` + a cell count → integer cells with no rounding drift (`minPerCategory` keeps small categories visible) — the math behind a feature-mix waffle
`unitize` / `unitizeRange`	any	the pictogram/tally allocator — one value → repeated unit signs with a fractional final sign (ISOTYPE: symbols repeat, they never grow). `maxUnits` caps with an `overflow` flag, `minFraction` drops slivers honestly (`total` vs `shown`), and `unitizeRange` extends the tally to a projected/scenario endpoint, sharing a mid-sign boundary via`startFraction`. The counting sibling of `allocateCells`; feeds `glyph` node `fraction`s directly
`tokenLayer` / `generateTokens`	any	the tokenized-reasoning layer above `unitize`: declare`tokenSemantics` (`unitized-measure`, `risk-case`,`possible-outcome`, etc.) and a `countStrategy` (`unitized`, `fixed-denominator`, `quantile`,`posterior-sample`), then get positioned dot, icon, or`glyph` scene nodes for rows, grids, waffles, dotplots, strips, or hybrid bar segments. Pass `{ value, rangeValue }` plus`includeRange` when a unitized tally needs projected/scenario tokens. Use`generateTokens` directly when a bespoke layout needs the records without default scene nodes; pair with `diagnoseTokenEncoding` and`suggestTokenEncoding` when a chart or IDID flow needs to explain why tokens are appropriate
`Glyph` / `glyphPlacement` / `glyphExtent`	any	the React face + geometry of the composite-pictogram `glyph` scene node: render a `GlyphDef` in overlays/legends/chrome with`<Glyph>`, and measure a definition’s drawn box/anchor offsets for layout math — seeGlyph Marks
`clamp` / `mean` / `withAlpha`	any	the numeric/color one-liners every layout re-declares; `withAlpha` turns a hex into `rgba()` so a hover-dim can ride a recipe’s`resolveColor` callback
`packIntervals` / `activeCountOverDomain`	any	greedy Gantt sub-track packing + the concurrency step series that pairs with it
`runs` / `runLengthEncode`	any	collapse a per-step categorical/boolean series into drawable runs (condition strips, status timelines)
`wrapValue` / `shortestArcDelta` /`cyclicRangeContains` / `selectCyclicRange`	any	cyclical (wrap-around) math for periodic axes — day-of-year, hour, compass bearing
`axisFixedForcePositions` / `rectCollide`	network	pin one axis from a field, relax the other with attraction + rectangular (label-box) collision
`unwrapDatum`	any	the raw user datum from an `onObservation` handler — collapses the wrapped-vs-raw split

JSX

import { hitTargetPoint, polarToXY, angleScale, radiusScale } from "semiotic/recipes" // A radial layout: draw the art-directed glyphs in overlays, emit a transparent // hit target per datum so the chart is keyboard-navigable + annotation-anchorable. function radialLayout(ctx) { const angle = angleScale([0, 365]) // day-of-year → radians const radius = radiusScale([-10, 110], [0, 180]) // temperature → px return { nodes: ctx.data.map((d) => { const { x, y } = polarToXY(angle(d.day), radius(d.temp)) return hitTargetPoint({ x, y, datum: d, id: `day-${d.day}` }) }), overlays: <RadialGlyphs data={ctx.data} angle={angle} radius={radius} />, } }

Composing overlays

JSX

import { roundedEnclosure, boundsOf, bandLabel, markCallout, readField } from "semiotic/recipes" function myLayout(ctx) { const sceneNodes = ctx.nodes.map((n) => ({ type: "circle", cx: read(n), cy: ..., r: 4, style: { fill: ctx.resolveColor(readField(n, "group", "")) }, datum: n.data, id: n.id, })) const box = boundsOf(sceneNodes.map((s) => ({ x: s.cx, y: s.cy, r: s.r })), 6) const overlays = ( <g style={{ pointerEvents: "none" }}> {box && roundedEnclosure({ ...box, stroke: "var(--semiotic-text)", radius: 10 })} {bandLabel({ text: "Group A", x: box.x, y: box.y - 6, anchor: "start" })} {markCallout({ markX, markY, labelX, labelY, label: "peak", markRadius: 8 })} </g> ) return { sceneNodes, overlays } }

Restyling on hover/selection without a relayout

By default, a selection or hover change re-runs the layout — rebuilding scene nodes, repainting the canvas, and rebuilding the hit-test quadtree. For a big graph that’s an O(nodes+edges) cost on every hover. Two opt-ins keep selection styling cheap (the layout runs only on data/size changes):

Canvas marks — return a restyle(node, selection) from the layout result (network also takes restyleEdge). Compute geometry once in the layout body; express dimming/highlighting in restyle. A selection change then re-applies styles to the existing marksoff each mark’s base style and just repaints — no relayout, no quadtree rebuild.
Overlays — call useCustomLayoutSelection() inside an overlay component for { isActive, predicate }. The frame swaps only the context value on selection change, so subscribing overlays re-render while the canvas and quadtree stay untouched.

JSX

import { useCustomLayoutSelection } from "semiotic/recipes" function myLayout(ctx) { const sceneNodes = ctx.nodes.map((n) => ({ type: "circle", cx, cy, r: 5, style: { fill, opacity: 1 }, datum: n.data, id: n.id })) return { sceneNodes, // Re-applied on selection WITHOUT a relayout; patch merges onto the base style. restyle: (node, selection) => selection?.isActive && !selection.predicate(node.datum) ? { opacity: 0.12 } : { opacity: 1 }, overlays: <Labels />, // <Labels> calls useCustomLayoutSelection() to dim its text } }

Drive selection through the selection store (selection /linkedHoveron the chart, or useSelectionActions) rather than layoutConfig, so changes ride this path instead of forcing a rebuild.

Reading the computed layout back out

A page often needs what the layout computed — placement stats for a readout, the set of marks actually drawn for an inspector — and re-running the layout function host-side just to summarize it duplicates work (and can drift). Every custom chart’s ref exposesgetCustomLayout(): the most recent layout result exactly as yourlayout(ctx) returned it (nodes/sceneNodes, overlays, plus any extra fields you attached). It is null before the first layout runs, and sits beside getData()/getScales() on the same handle.

JSX

const ref = useRef() // after mount / layout: const layout = ref.current?.getCustomLayout() const placed = layout?.nodes ?? [] // summarize what was actually drawn <XYCustomChart ref={ref} layout={myLayout} data={rows} />

Why a kit, not props on the frame

The frame deliberately owns interaction, accessibility, transitions, and SSR; recipes own chrome; the host owns the editorial aesthetic. Keeping these as small composable functions (rather than a giant options bag on the frame, or one render-everything recipe) means a new layout — or an AI generating one — assembles exactly the chrome it needs from named pieces with obvious signatures.

Annotations can now anchor to a mark a custom layout emits: give the scene node anid and pass an annotation { pointId: "<id>" } to the chart’s annotations prop (all four custom HOCs accept it).markCallout remains for fully bespoke, recipe-drawn leader lines.