Interoperability — Gofish — 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/interoperability/gofish

Experimental GoFish DisplayList Adapter

GoFish’s toDisplayList({ w, h }) is therender IR: the output of GoFish’s layout solve, captured one step before backend emission, as a flat, ordered list of positioned primitives in absolute pixels. The operators, constraints, channels, and coordinate transforms are all already consumed — a polar petal arrives as a baked path, a treemap cell as a baked rect. GoFish’s developer shipped this stage specifically for this adapter, and it makes the integration small and faithful: GoFish owns the geometry, andunstable_fromGofishIR maps each item onto a Semioticcustom layout by its role — exactly as GoFish’s own reference displayListToSVG backend emits SVG tags, but emitting scene-nodes and overlays instead.

role: "overlay" → overlay.Chrome (axis ticks, labels, glyph detail) renders verbatim into one ordered SVG overlay layer — a JSX port of GoFish’s reference renderer — so painter order and everykind (warped paths, images, Porter-Duffcomposite/mask graphs) stay pixel-faithful.
role: "node" → scene node.Each data-bearing mark renders into that same SVG layer and gets a transparent hit-rect scene node carrying its datum, so Semiotic stays authoritative for hover, tooltips, onObservation, cross-chart selection, keyboard a11y, and SSR mark-count evidence. Chrome without a datum (legend swatches, axis ticks) stays overlay-only.

Because a display list is viewport-baked — solved at one{ w, h }, not cacheable — the result always mounts onNetworkCustomChart, the scale-free family (plot-relative pixels, no data scales to fight the baked geometry). The adapter surfaces the document’sviewport as width/height; on resize or data change a host re-calls toDisplayList and re-runs the adapter rather than rescaling an old document.

This adapter is named unstable-gofish-displaylist-adapter, exposed as anunstable_ preview from semiotic/experimental. It is not a runtime dependency on GoFish — it consumes GoFish’s published render IR, not its renderer. The examples below are real baked documents, generated byscripts/gen-gofish-fixtures.ts from gofish-graphics and checked in so the gallery never depends on the nightly at runtime.

This baked frame

GoFish's real flower chart, verbatim: a meadow where each lake is a green stem (a bar whose height is the lake's total catch) topped by a polar fan of petals, one per species, sized by count. It is layer([stems, flowers]) — the flowers selectAll the stems and stack a polar petal fan on each. The composition's root is a combinator (no ChartBuilder.toDisplayList), so it is baked through GoFish's mark-resolution contract; see gofish-displaylist-findings.md.

Viewport 725 × 608 · 46 items ·6 data nodes

Primitive kinds:rect×11, path×30, text×5

Selected mark

Hover a bar, flower stem, passenger circle, or bottle — the transparent hit-rect over each role: "node" item carries its source datum.

The DisplayList driving this chart

This is not hand-wired. The JSON below is a GoFish DisplayList document — the post-layout render IR. Every item is absolute pixels with its coordinate transform already folded in; role is the mapping switch and datum is the provenance Semiotic hit-tests against. (Items are abridged for display.)

JSON

{ "irVersion": 0, "ir": "gofish-display-list", "viewport": { "w": 725, "h": 608 }, "items": [ { "kind": "rect", "x": 46, "y": 177.05109489051097, "w": 4, "h": 390.94890510948903, "rx": 0, "ry": 0, "style": { "fill": "rgb(0, 142, 91)", "stroke": "rgb(0, 142, 91)", "strokeWidth": 0, "opacity": 1 }, "datum": [ { "lake": "A", "species": "Bass", "count": 23, "x": 5.26 }, { "lake": "A", "species": "Trout", "count": 31, "x": 5.26 }, { "lake": "A", "species": "Catfish", "count": 29, "x": 5.26 }, { "lake": "A", "species": "Perch", "count": 12, "x": 5.26 }, { "lake": "A", "species": "Salmon", "count": 8, "x": 5.26 } ], "role": "node" }, { "kind": "rect", "x": 150.21159715157677, "y": 48, "w": 4, "h": 520, "rx": 0, "ry": 0, "style": { "fill": "rgb(0, 142, 91)", "stroke": "rgb(0, 142, 91)", "strokeWidth": 0, "opacity": 1 }, "datum": [ { "lake": "B", "species": "Bass", "count": 25, "x": 30.87 }, { "lake": "B", "species": "Trout", "count": 34, "x": 30.87 }, { "lake": "B", "species": "Catfish", "count": 41, "x": 30.87 }, { "lake": "B", "species": "Perch", "count": 21, "x": 30.87 }, { "lake": "B", "species": "Salmon", "count": 16, "x": 30.87 } ], "role": "node" }, { "kind": "rect", "x": 228.09562563580872, "y": 97.34306569343067, "w": 4, "h": 470.6569343065693, "rx": 0, "ry": 0, "style": { "fill": "rgb(0, 142, 91)", "stroke": "rgb(0, 142, 91)", "strokeWidth": 0, "opacity": 1 }, "datum": [ { "lake": "C", "species": "Bass", "count": 15, "x": 50.01 }, { "lake": "C", "species": "Trout", "count": 25, "x": 50.01 }, { "lake": "C", "species": "Catfish", "count": 31, "x": 50.01 }, { "lake": "C", "species": "Perch", "count": 22, "x": 50.01 }, { "lake": "C", "species": "Salmon", "count": 31, "x": 50.01 } ], "role": "node" }, { "kind": "rect", "x": 493.08036622583916, "y": 127.7080291970803, "w": 4, "h": 440.2919708029197, "rx": 0, "ry": 0, "style": { "fill": "rgb(0, 142, 91)", "stroke": "rgb(0, 142, 91)", "strokeWidth": 0, "opacity": 1 }, "datum": [ { "lake": "D", "species": "Bass", "count": 12, "x": 115.13 }, { "lake": "D", "species": "Trout", "count": 17, "x": 115.13 }, { "lake": "D", "species": "Catfish", "count": 23, "x": 115.13 }, { "lake": "D", "species": "Perch", "count": 23, "x": 115.13 }, { "lake": "D", "species": "Salmon", "count": 41, "x": 115.13 } ], "role": "node" }, { "kind": "rect", "x": 566, "y": 230.18978102189783, "w": 4, "h": 337.81021897810217, "rx": 0, "ry": 0, "style": { "fill": "rgb(0, 142, 91)", "stroke": "rgb(0, 142, 91)", "strokeWidth": 0, "opacity": 1 }, "datum": [ { "lake": "E", "species": "Bass", "count": 7, "x": 133.05 }, { "lake": "E", "species": "Trout", "count": 9, "x": 133.05 }, { "lake": "E", "species": "Catfish", "count": 13, "x": 133.05 }, { "lake": "E", "species": "Perch", "count": 20, "x": 133.05 }, { "lake": "E", "species": "Salmon", "count": 40, "x": 133.05 } ], "role": "node" }, { "kind": "rect", "x": 374.50457782299077, "y": 233.98540145985402, "w": 4, "h": 334.014598540146, "rx": 0, "ry": 0, "style": { "fill": "rgb(0, 142, 91)", "stroke": "rgb(0, 142, 91)", "strokeWidth": 0, "opacity": 1 }, "datum": [ { "lake": "F", "species": "Bass", "count": 4, "x": 85.99 }, { "lake": "F", "species": "Trout", "count": 7, "x": 85.99 }, { "lake": "F", "species": "Catfish", "count": 9, "x": 85.99 }, { "lake": "F", "species": "Perch", "count": 21, "x": 85.99 }, { "lake": "F", "species": "Salmon", "count": 47, "x": 85.99 } ], "role": "node" }, "…and 40 more items" ] }

Why this is not ad hoc

GoFish owns layout; Semiotic owns interaction. The adapter does no geometry — it forwards baked primitives and attaches hit targets, accessibility, and SSR evidence to the data-bearing ones.
Role is the contract.node vs overlay is the single switch; nothing is recognized or special-cased per chart type. A bar chart, a polar flower, and a packed circle treemap all flow through the same mapping.
Provenance survives the solve. Data-bearing primitives carry the source row(s) they were elaborated from, so a hovered flower stem still answers “which lake, and what was the catch?” — even though the petals atop it are baked geometry.

Targets

GoFish example	Baked primitives	Node contract
Flower meadow	`rect (stems) + path (polar petals) + rect/text (legend)`	layer([stems, flowers]): each green stem is a data node carrying its lake's catch rows; the polar petals atop it are baked paths (chrome) with no per-row datum.
Polar ribbon chart	`path (clock-projected radial bars + bumped species ribbons) + rect/text (legend)`	layer({ coord: clock() }, [bars, ribbons]): each radial bar is a data node; the per-species area ribbons that selectAll the bars are baked paths (chrome). Wrap, gap, and bumps are all in absolute-pixel paths.
Fare circle treemap	`ellipse (one circle per passenger, faceted by class) + rect/text (facet + legend chrome)`	facet by pclass (dir x) → squarify-circle treemap per class, fare-sized, sorted desc. Every circle is a data node coloured by survival; the three class blocks and legend are chrome.
Bottle fill pictorial	`composite (paint blendMode: silhouette image + fill rect) + text (label)`	A paint composite per stage tints the fill inside the silhouette; the adapter harvests the composite's child datum so each bottle is one hit node.
Boba cups (hand-written)	`path (cup, tea/ice slabs, straw) + ellipse (pearls) + rect (ice cubes, lid) + text (labels)`	Hand-emitted DisplayList — no gofish-graphics, no GoFish solve; all the cup geometry is plain arithmetic. Proof the render IR is an open, host-emittable format. The three volume bands per drink are data nodes carrying drink + volume; cup, straw, pearls, and labels are chrome.
Python memory diagram	`rect + text (frame + tuple cells) + path/ellipse (pointer arrows)`	Best-effort reconstruction from primitives (the real example needs unpublished GoFish helpers). Built from literal values, so no mark carries a datum — every item is chrome, zero hit targets. Bakes vertically flipped vs the live render (toDisplayList y-orientation, GoFish #143/#16).

Using the adapter

In a host, the document comes from GoFish’s layout pass. Build a spec exactly as you would to render it, but stop at toDisplayList instead of painting to SVG, then feed the result to unstable_fromGofishIR:

JSX

import { useEffect, useState } from "react" import { chart, spread, stack, rect, field } from "gofish-graphics" import { NetworkCustomChart } from "semiotic/network" import { unstable_fromGofishIR } from "semiotic/experimental" function LiveGoFish({ data, width, height }) { const [cfg, setCfg] = useState(null) // The display list is viewport-baked and async — re-bake on size/data change // rather than rescaling an old document. useEffect(() => { let live = true chart(data) .flow(spread({ by: "lake", dir: "x" }), stack({ dir: "y", by: "species" })) .mark(rect({ w: 34, h: field("count"), fill: field("species") })) .toDisplayList({ w: width, h: height }) .then((doc) => { if (live) setCfg(unstable_fromGofishIR(doc)) }) return () => { live = false } }, [data, width, height]) if (!cfg) return null return ( <NetworkCustomChart nodes={cfg.nodes} layout={cfg.networkLayout} layoutConfig={cfg.layoutConfig} width={cfg.width} height={cfg.height} margin={{ top: 0, right: 0, bottom: 0, left: 0 }} enableHover emptyContent={false} /> ) }