Legends
GoFish draws a color legend automatically from the color scale it infers — a column of swatches and labels for a categorical scale, or a colorbar (a sampled gradient bar with tick labels) for a continuous (gradient) one. Like axes, a legend is not a privileged node type. It is elaborated into ordinary GoFish shapes (rect, text) and operators (spread, layer) wired together with constraints (align, distribute, position). The render pass has no legend-specific code at all.
Why elaborate
The legend was the second-to-last bespoke piece of chrome. Axis titles followed it, and both are now elaborated. It used to render as a <For> over scaleContext.unit.color in gofish.tsx's render(), hand-placing swatches at translate(width + pad*3, …) behind a fixed 120px LEGEND_MARGIN reserved on the right of the SVG. Because it was a render-time fixture rather than a node, it could not participate in space allocation (#493) — its width was a guessed constant, not a measured extent — nor in size inference (#494): a chart with w/h omitted had no way to fold the legend into its computed extent. Elaborating it into the laid-out tree fixes both, and opens the same customization seam axes got in #490: the legend is now built by pure, exported functions a future public API can override.
The elaboration pass
A legend is the outermost ring of the chrome of the node that owns the color encoding (see Axes for how elaborateChrome builds the rings). The color scale is resolved once for the whole render, by a walk from the chart root (resolveColorScale), so the root owns it. layout() builds legendRing(scale, root) when the scale has something to show (a non-empty categorical color map, or a continuous color scale) and stamps it on the root's chrome request, before chrome elaboration wraps any node of the tree; elaborateChrome seats it as the root's outermost ring. The axes option plays no part, so a legend appears whenever a color encoding resolved.
The chart option legend: false is the one veto. With it, the root gets no legend ring, and nothing reserves the column's width. The scale still colors the marks. A chart with 72 categories can keep its colors and drop a swatch column that would be taller than the chart.
legendRing reads the resolved scaleContext.unit (the color map for a categorical scale, or the scaleFn and domain for a continuous one) and builds legendColumn or legendColorbar from it. The color scale is resolved before chrome is elaborated and is not resolved again afterward. Chrome adds no data colors: legend fills are literal color strings (each colorbar band is scaleFn(value), baked at elaboration time), never isValue data references.
The ring holds the box inside it (the root with its axes and titles) plus the legend:
root = Layer([ titled, legend ])legendColumn is a Spread({ dir: "y" }) of one row per color-map entry. Each legendRow is a Spread({ dir: "x" }) of a 10×10 Rect swatch and a 10px gray Text label. The column's y is ordinal, so the spread reads top-down (see Axis direction): the entries are listed top to bottom in the order they are given.
The order is the one the plot lays its color series out in down the screen, when it lays them out along y, and the color scale's own otherwise. The legend does not work that out from the shape of the plot. Each operator that chains its parts along y (a stack or a spread, a distribute on y) reports the keys of its parts in the order they read down the screen (keysDownTheScreen in constraints/distribute.ts): its placement order, reversed when its y grows upward, because such a chain lays its first part at the bottom. A stack reports its chain whatever the signs of its parts. Inside a coordinate space the chain's y is a coordinate of that space (a polar radius), not the screen's, so it reports no order. The legend links to its series structurally, by field: the color scale records the fields it encodes, and an operator that splits its data by a field records that field on each of its parts (__splitBy). The legend takes the chain of the outermost operator (breadth first, seriesDownTheScreen) that splits by a field the color scale encodes and lays its parts out along y. So a stacked bar chart lists its last series first, the one at the top of each bar. The legend follows the plot; the plot's stacking rule never reads the legend.
A continuous (gradient) colorbar is a continuous value axis, so it grows upward: the domain max is at the top. Its bands are listed from the top, each showing the value at its center, and each tick sits valueToPx(v) above the bar's base.
The three constraints
The ring is wired with three constraints, and the order matters because the first one places the box the other two read:
position({ x: 0, y: 0, anchor: "baseline" })on the box inside, a literal-pixel pin at the origin that means "stay exactly where you were laid out". Every ring starts with this pin (wrapRing). The box is referenced by thedistributebelow, and a constraint-referenced child skips the layer's phase-1 baseline placement (placement is first-write-wins), so the pin states that placement explicitly. It pins the baseline (the local 0 point), not the bounding-box corner, so the box never moves however far its axis labels reach.distribute({ dir: "x", spacing: 20 }, [box, column])seats the column just right of the box, which includes the axis labels and titles.align({ y: top }, [box, column])top-aligns the column with the box. The constraint runs in the ring's axis order, so "top" is theendof a y that grows upward and thestartof one that reads top-down (a heatmap):orientSide("start", wrapperDirection(root)).
The outermost ring inherits the root's key, so faceting keeps resolving to it. The root keeps its _name, and every ring is transparent to a name lookup, so refs and selectAll still resolve to the root.
Why the ring preserves the content's spaces
Inserting a Layer around the content could in principle change the chart's inferred underlying space. It does not, because of unionChildSpaces' rule that an UNDEFINED sibling contributes "no opinion" and is ignored in the all-SIZE gate (the same way ORDINAL siblings are filtered). The swatch column resolves to UNDEFINED on both axes (fixed-pixel shapes, no data-driven extent), so the ring's space is the content's space. See Underlying Space.
Sizing: the legend takes room
The fixed 120px LEGEND_MARGIN is gone, and so is the measured right overhang that replaced it. The legend is a ring of the root's chrome, so it takes room like the axes do (#1032): its swatches and labels claim their sizes, its ring claims the hull of the box inside and the legend where it is seated, and the content gets what the chrome leaves of the canvas. The render's w/h is the whole graphic, legend included, and when they are omitted the canvas is the root's whole box. See Layout & Render Passes.
Interplay with axis titles
The title ring is inside the legend ring (see Axes). So the legend is seated off the box with the titles, and the title centering never sees the legend column.
This relies on the content node reporting a complete, correctly-positioned bounding box. Most nodes do, but the polar coord node historically emitted an { x, y, w, h } intrinsic-dims form that set only min/size and left max/center undefined — and was positionally offset from the rendered content. That poisoned the distribute constraint (it seats the column at content.dims[0].max, which was NaN), so the fix lives in coord itself (reporting a placed-consistent [0, size] box), not in special-casing the legend.
The customization seam
legendRow / legendColumn (categorical) and legendColorbar (continuous) are pure, exported builders (no mutation, no context) — the seam a future public legend API would override, exactly as elaborateAxis is for axes. The visual constants (swatch/bar size, gaps, label font and color) live as module constants chosen to match the previous bespoke styling.
legendColorbar builds the bar as a layer of fixed-pixel shapes — BAND_COUNT thin band Rects (each filled scaleFn(value)) plus a tick mark + label per d3 tick — each placed by a literal-pixel Constraint.position in the colorbar's y-down layer (value v sits t·BAR_HEIGHT above the bar's base, so the domain max is at the top). The layer's bbox is the union of those shapes, so the colorbar is measured by normal layout exactly like the swatch column.
Limitations
- A tall legend (more entries than the content is tall) can extend below the content bottom. This is a pre-existing failure mode carried over from the bespoke layout and is out of scope here.
