Declarative chart layer

Status: Agreed

A chart is a nested map — a design — that names its data, its coordinate frame, its marks and its labels without a function anywhere in it, so that a design can be stored, diffed, shared, built by a tool and rendered against different data. This document is the contract for the whole layer: the map at every level with every key's type, facet, default and merge rule; the style grammar; sources as typed slots and variables as terms; version and migration; the validator and its error shape; the JSON form; and, as agreed prose, application, composition and compilation. Vega-Lite is the precedent for a stored design and its flat several-hundred-key specification is the warning: the map keeps the three-noun nesting of theme, style and frame (D-57).

Each section states what is implemented. The schema, the validator, the Visualize.Chart struct with its map and JSON round-trips, variables and version handling, the frame — its scales, inference, axes, grid, legend and labels, rendered as the static furniture — and the marks — every mark type drawn from the frame's scales by the existing generators, the transforms as steps of a mark's data pipeline, and the style grammar resolved to an SVG and a canvas output — and the presets — the ten LiveView components of 10-liveview-integration as stored designs plus an assign mapping (§15) — and application and composition — variables resolved and slots bound by Visualize.Chart.apply/2 into an applied chart, fragments merged by Visualize.Chart.compose/2 and layered by Visualize.Chart.stack/1 under the schema's merge rules (§7.3, §8) — and compilation — the static/dynamic split computed from the design, a render target per mark from the bound data, the hybrid chart map per tick, the streaming window over the incremental path, and the payload measured (§12) — are Implemented. The builder — Visualize.Chart.Build, whose every function returns a fragment the composition of §8 folds into a design (§16) — is Implemented. The inspectors of a stack — Visualize.Chart.explain/1, the provenance of every leaf over the layers, and Visualize.Chart.free_vars/1, the variables a stack still demands (§17) — are Implemented.

1. The map

1.1 The design is the primary representation

Implemented. The nested map is the chart; every other form — the Visualize.Chart struct, a JSON document, the builder's forms, the pipeline API of the earlier documents — is a view of it or sugar that builds one. Four requirements make the map an asset rather than a liability, and every section below is held to them:

1. No functions. Fields, transforms, formats, curves, styles and scales are named; where the pipeline API takes a closure the map takes a name or a literal. An escape hatch that needs code is applied to the struct after Visualize.Chart.from_map/1, never stored.
2. Design separate from data. A design names its sources (data: :primary); rows arrive at application (§7.3). The same design binds to any source with the fields it declares.
3. A schema with a validator. Every key is declared once, as data (§14.2), and Visualize.Chart.Validator.validate/1 reports each fault by path and reason (§10).
4. A version key from the first design, with a migration path per version (§9).

The three nouns of the design are the theme (visual constants as named slots, 08-utilities §7), the style (per-mark presentation, declared once under styles and referenced by name, §3) and the frame (the coordinate system and its furniture: size, margins, scales, axes, legend, §4). The frame owns the scales and injects them into the marks it holds, so a mark declares channels and never applies a scale itself.

1.2 Four levels

Implemented. The map has four levels and nothing deeper; every builder struct in the library decomposes into one of these nodes.

Collections are lists (marks, axes, labels, transforms); named declarations are maps keyed by name (sources, vars, styles, scales). A name is an atom. Marks reference scales, styles and sources by name, never by nesting: that is what makes fragments composable (§8) and the map diffable.

1.3 Facets

Implemented. Every key carries a facet, one of five, and nothing in the library keeps a hand-written list of "which keys are style": the builder's style panel (#54), the theme's overridable slots (#57) and the compiler (§12) all read Visualize.Chart.Schema.keys/1.

A container's facet is the facet of what it holds: marks is :channel because a mark exists to bind fields to scales, frames is :geometry, labels is :content.

1.4 Types

Implemented. The schema types every key with one of these terms; Visualize.Chart.Schema.describe/1 returns them as data (Visualize.Chart.Schema.type/0).

| {:ref, :scale | :style | :source | :var | :frame} | a name declared under the frame's scales, or under styles, sources, vars or frames (§10.2) | | :field | an atom naming a field of the mark's source (§5.4) | | :field_ref | {:field, f} with f a :field; how a per-datum value reaches a style or a text | | :channel | a :field, a number (a constant channel) or a :field_ref | | :extent | :auto; a two-element list of numbers, DateTimes or :auto; or a list of categories (numbers, strings, atoms) | | :key_order | {:keys, [n, …]} with every n a :name: a stacking order fixed by the series keys, bottom first (§5.4.1, #492) | | :adopted | {:frame, f, s}, the scale s of the frame f (§4.3): what a frame writes under a scale name in place of a node of its own | | :text | a string with interpolation: #{var(:name)} stands for a variable and #{field(:name)} for a datum's field, a literal #{ is \#{ (§7.1); a list of parts — strings, variables and :field_refs, the form an earlier draft wrote — is read and written back as the string (§9) | | :anchor | :title, :subtitle, :caption; {:axis, s} with s a {:ref, :scale}; {:frame, c} with c one of :top_left, :top_right, :bottom_left, :bottom_right, :center; or {:data, [x, y]} with x and y values in the domains of the frame's position scales (§6.3) | | :colour | a colour string, :none, :contrast (the contrast ink, §3.2), or a theme slot | | :size | a number or a theme slot | | :font | a string or a theme slot | | :slot | a slot of the design's theme: :series_k, {:series, i}, :axis, :grid, :text, :background, :surface, :font_family, :font_size, :label_size, :title_size (08-utilities §7.1) | | :term | any JSON-representable term: a number, string, boolean, nil, atom or DateTime, or a list or name-keyed map of those |

A %Visualize.Chart.Var{} (§7.1) is accepted wherever a value of any type is expected, including in place of a whole node; its value is typed at application.

A struct is a leaf of every walk (D-92). A variable stands for a value rather than being one, so no walk over the design map — composition and the cascade (§8), resolution (§7.3), validation (§10), the JSON codec (§11), the provenance and free-variable walks (§17) and the builder's node list (§18.5) — descends into a struct or merges one as a map, whatever type the schema gives the key it sits at. That a struct is also a map in Elixir is an implementation fact and never a licence to treat it as one: a walk MUST exclude it explicitly. Exactly two structs may appear in a design map — a %Visualize.Chart.Var{} and a DateTime — and both are values.

A field name is an atom in the map form even for a source whose columns are strings: Visualize.Data.Table.get/2 reads either spelling (D-52), so :v reaches a column named "v" and the map never carries a string where a name belongs (D-57).

1.5 Merge rules

Implemented as data, applied by Visualize.Chart.compose/2 and Visualize.Chart.stack/2 (§8). Every key declares how two fragments combine under it; the Effect column is the union's, and the cascade's difference where two fragments collide is §8.2:

2. The design node

2.1 Keys

Implemented. The :design node is the top level. version and frames are the only required keys.

2.2 Meta

Implemented. :meta identifies the design; nothing renders from it except through a label that quotes it.

2.3 Sources

Implemented. A :source is a typed slot (§7.2): the fields the design reads from it, what each field's column is, and the name of the pool entry that fills it when application supplies none under the slot's own name (§7.3).

A column has a type (#369): types maps a declared field to one of four — :time (a point in time), :number, :category (one of a set of names) or :text (free text). It is a separate key rather than a pair in fields because the JSON form (§11) has no tuples and a keyword list would not survive it; the validator holds the two together — a name under types that fields does not list is {[:sources, name, :types, field], {:undeclared, :field, field}} — so they cannot drift silently. A field with no type is as it always was. Rendering reads no type: a scale still says how a column maps to the plot, and a channel bound to a field with no scale is still the identity (§4.3); the type says what the column is, which is what lets a tool derive the scale a person did not write (§18.16, #370). Visualize.Chart.column_type/3 answers column_type(design, source, field) with the type or nil; Visualize.Chart.Schema.column_types/0 is the four. Rows can suggest a type: Visualize.Data.Table.column_types/1 (spec/08 §6.3) reads a table's columns whole — every value temporal (temporal?/1) is :time, every value a number :number, every value a string :text, every value an atom or boolean :category, anything mixed no type — for a tool to pre-fill what a design does not declare; the design's word, once written, is never overridden by rows.

2.4 Vars

Implemented. A :var declaration gives a variable its default. The default is declared here and only here; the %Visualize.Chart.Var{} term that uses it carries the name alone (§7.1, D-59).

2.5 Theme

Implemented. theme names a theme — :default or :dark for the built-in ones of 08-utilities §7.2 — or gives one inline as a :theme node whose keys are the fields of Visualize.Theme: name (:name), series ({:list, :string}, non-empty), axis, grid, text, background, surface (:string), font_family (:string), font_size, label_size, title_size (:number), every key :style and :override, defaults those of Visualize.Theme.default/0. A name that is neither built-in nor known to the consumer is resolved at application, which takes a theme: option; the validator accepts any name. Slots referenced from styles (§3.2) are checked against the theme when it is built-in or inline.

2.6 Styles

Implemented. styles declares named style nodes (§3). A mark, axis, legend or label references one by name through its style key; no other node carries a colour, a font or a curve.

2.7 Defs

Implemented (#133). defs declares the design's paints: named :gradient nodes a :colour key refers to as {:paint, name} (§3.2). A gradient is written once in the words a person uses — a kind, its stops, an angle or a centre — and the SVG geometry is derived; :union merge, like styles, so a house sheet of gradients composes.

A :stop node is offset (:number, required, 0 to 1), colour (:colour, required — a literal, a slot or a variable, resolved as any colour is), and opacity (:size, default 1, range {0, 1, 0.05}); every key :style and :override.

A gradient's units are the shape's bounding box (objectBoundingBox), so one gradient fits any mark. From the angle θ a linear gradient's line runs from (½ − ½ sin θ, ½ + ½ cos θ) to (½ + ½ sin θ, ½ − ½ cos θ); a radial one is centred at centre with radius, its focus at the centre. Visualize.Chart.Frame.generate/2 emits one defs element first in the frame's group, before the grid, holding every gradient of the design as a Visualize.IR.Element.linear_gradient/2 or radial_gradient/2 with its stops, each under the id vis-paint-<h>-<name> where <h> is the lower-case base-36 :erlang.phash2/1 of the design's defs, so two charts on one page collide only when their paints are the same; a design with no paints emits no defs. The same defs holds one filter per {effect, radius} pair any style in the tree uses (§3.1): <filter id="vis-effect-shadow-3"> with a feDropShadow of dx, dy and stdDeviation the radius (flood-opacity 0.35), or <filter id="vis-effect-blur-3"> with a feGaussianBlur of stdDeviation the radius; a design whose styles use no effect declares none. The defs are static furniture (§12.2): they never change with the data.

2.8 Layout

Implemented (#384). layout is the grid a design's frames are placed on, so "attached to the right of that one" is a layout rather than arithmetic (§4.2). Every key is :geometry and :override.

A design with no layout places its frames by their boxes alone. A weight that is not positive is a fault ({:weight, :columns} or {:weight, :rows} at the design's path), since a cell of no width is not a cell. The grid fills the box the render is given: a frame in cell [c, r] spanning [dc, dr] takes the columns c … c + dc − 1 and the rows r … r + dr − 1, and its box is their share of the whole less the gap.

2.9 Interaction

Implemented (#466, #467). interaction says how the chart behaves on the page beside other charts. Its one behaviour is the sync group: charts that name the same group share hover, so pointing at one moves the crosshair and the tooltip of every other (spec/10 §4.3), and share the brush, so a window brushed on one shows as a band on every other while only the chart brushed tells its server (spec/10 §6.4). What travels between them is the x value, or the brushed x extent, in domain units, never a pixel, so members of different widths and margins line up on the same instant. Every key is :binding and :override.

The group is rendered as data (D-77, D-116). The sync frame's group in the markup carries two attributes, which do nothing without the hooks:

Visualize.Chart.Frame.sync_attrs/1 computes them from the realised frame: %{} for a frame that is not the sync frame of a group. Visualize.Chart.Frame.generate/2 writes them on the frame's group, Visualize.Chart.generate/2 keeps them on that frame's group in a design of several frames, and Visualize.Hooks.Crosshair.attrs/3 adds them to the container's attributes (spec/10 §13.2). Every number prints through Visualize.IR.Path.format_number/1. The realised frame carries the group as sync (§4.7). A design without sync writes nothing, so its markup is the same byte for byte.

Only a linear or a time x joins a group. The hooks map a value through d0,d1,x0,x1 by linear interpolation, and that interpolation is the scale only for :linear and :time. A :band or :ordinal x has no value between its categories, and a :log or :power x is not linear in its pixels. With sync given, the validator therefore holds the sync frame (the one frame names, else the first by name) to two things, both reported at [:interaction, :sync]:

• The frame is :cartesian. Any other kind is {:sync, :frame_kind, kind}.
• Its x scale is :linear or :time, read through any adoption to the node that declares it (§4.3). Any other kind is {:sync, :x_scale, kind}, and a frame that declares no x is {:sync, :x_scale, nil}.

A frame that names no frame of the design is {:undeclared, :frame, name}, as any frame reference is.

3. The style grammar

3.1 Keys

Implemented. A :style node has twenty-nine keys, every one :style and :override, every one optional with no default: an absent key is decided by the theme and the mark at compilation (§12), never by the schema. The keys are read as a drawing tool shows a style — in groups: what a style derives from first, then its fill, its stroke, its font, the position of its text, its effects, and last the keys that belong to no group. A key's group is data on its spec (group, §14.2), and the table below is in group order, which is the order the form shows them in (§18.7).

3.2 Values

Implemented. A style value is one of six things, and which of them a key accepts follows from its type:

• a literal of the key's type — "#3b6fa8", 2, :step_after;
• a theme slot (:slot) for the :colour, :size and :font keys — :series_1, {:series, 3}, :axis, :font_size — resolved through Visualize.Theme.resolve/3 in the mode of the render target, so the SVG output carries var(--vis-axis, #666666) and a canvas the literal (D-55);
• a variable (§7.1) for any key;
• a paint {:paint, name} for a :colour key: a gradient the design declares under defs (§2.7). Visualize.Chart.Style.resolve/3 passes it through untouched, as it does a binding, and the frame resolves it once its elements are drawn — Visualize.Chart.Frame.generate/2 replaces every {:paint, name} in the tree's styles with url(#vis-paint-<h>-<name>) in :css and with the gradient's first stop's colour, resolved as a colour, in :literal, since a canvas gradient is a different object and the first stop keeps a canvas chart drawable and honest. The validator reports {:undeclared, :paint, name} for a name defs lacks.
• the contrast ink :contrast for a :colour key (#486, D-123): the theme's :text or :background, whichever has the higher WCAG contrast ratio (Visualize.Color.contrast/2) against the colour the text is drawn on — Visualize.Theme.ink/2, spec/08 §7.3. In a mark's inline label (§5.5) that colour is the fill of the element the label sits on, so the ink is chosen per element: dark on a pale slice, light on a dark one, in one style. Anywhere else — a frame label, an axis, a :text mark, a mark's own paint — there is no element under the text, and the colour is the theme's background, so :contrast there is the ink that reads on the page (on every theme that holds spec/08 §7.4, its text). When neither slot reaches 4.5:1 against the colour (WCAG AA for text), the ink is black or white instead, whichever contrasts more, and one of the two always reaches 4.58:1. The ink is a literal colour in both modes: Visualize.Chart.Style.resolve/3 writes the chosen slot's literal, never a var(--vis-text, …), because the choice was made against the literals — a stylesheet that overrode --vis-text under it would undo the choice it was made for — so under resolve: :css the ink is chosen against the slots' fallback literals and the element's fill's, exactly as under :literal, and the SVG and the canvas carry the same colour.
• a channel binding {:field, f} for any key, which is how Visualize.Shape.Band's per-datum fill is expressed: the value is read from the datum at render — per element for a mark that draws one element per datum, from the series' first datum for a mark that draws one path per series (§5.6) — and, for a :colour key, passed through the scale named color when the frame declares one (§3.4) — a value its domain lacks is the scale's unknown colour (§4.3), never a dropped key.

Eighteen keys reach the element the mark draws — the fifteen of §3.4, line_height, and, as one, effect with effect_radius, and blend; four more — curve, curve_opts, symbol and symbol_size — reach the mark's generator (§5.6) and never an element; five — stroke_style (§5.6), vertical_align, margin_x, margin_y and text_angle (§6.3) — are read by the placements from the style node and never reach an element as themselves; and extends reaches neither, being consumed by the lookup that flattens it (§3.5).

For an enumerated key an atom is the literal; for a :colour, :size or :font key an atom is a slot, :none is the literal "no paint", and :contrast on a :colour key is the contrast ink (it is not a slot, and the validator accepts it on every theme). The validator checks a slot against the theme's Visualize.Theme.slots/1 when the theme is built-in or inline (§2.5) and reports {:undeclared, :slot, name} otherwise.

3.3 Built-in styles

Implemented. Four style names are always declared, derived from the theme's slots, and a styles entry of the same name replaces one whole: :axis (stroke: :axis, fill: :text, font_family: :font_family, font_size: :font_size), :grid (stroke: :grid), :label (fill: :text, font_family: :font_family, font_size: :label_size) and :title (as :label with font_size: :title_size, font_weight: :bold). Visualize.Chart.Schema.builtin_styles/0 lists them, a {:ref, :style} resolves against the union of the built-in and the declared names, and the frame resolves a style to an element's style map by Visualize.Theme.resolve/3 for every slot in it (§4.7). A mark whose style gives no value for its paint key — stroke for a stroked type, fill for a filled one — takes the theme's {:series, i} for its one-based position among the marks as its paint (§5.6).

3.4 Resolution: one node, two outputs

Implemented. A style node resolves to the style map of a Visualize.IR.Element through Visualize.Chart.Style.resolve/3 in the mode of the render target, and the mode is what makes one node serve two backends (D-63): in :css the SVG output carries classes and CSS custom-property references — class="mark mark-line series", stroke="var(--vis-series-1, #3b6fa8)" — that a stylesheet overrides; in :literal a canvas gets the plain colour, width and font it needs, which Visualize.Backend.Canvas reads as they are (spec/09 §3). resolve/3 keeps the eighteen element keys — line_height, blend, effect and effect_radius among them, which the backends read as spec/09 §2.5 and §3.3.3 say: blend is mix-blend-mode in an inline style attribute (it is a CSS property, not a presentation attribute every browser honours) and globalCompositeOperation on a canvas; effect with its radius is filter="url(#vis-effect-<effect>-<radius>)", the filter itself declared once per chart per pair in the frame's defs (§2.7) as a feDropShadow or a feGaussianBlur, and on a canvas the context's shadow properties or its filter — resolves every slot through Visualize.Theme.resolve/3, joins a dash-array list with spaces, writes a font_weight of :light as 300 and :medium as 500 (:normal and :bold are CSS's own words and pass as they are) and passes a literal through; a canvas reads font_style and font_weight into its font shorthand — italic 300 12px sans-serif — beside the size and the family (spec/09 §3); a {:field, f} survives it unchanged, and Visualize.Chart.Style.bind/4 then reads it from a datum through Visualize.Data.Table.get/2 — a :colour key's reading through the frame's color scale when the frame declares one, the scale's output resolved as a slot when it is one — and writes :none for a colour key whose reading is nil or whose scale yields nil. A colour is never dropped (#487, D-122): a reading the color scale's domain does not hold is the scale's unknown colour (§4.3), and a missing reading is the explicit "no paint", because the backends disagree about a colour key that is absent — SVG paints an element with no fill anywhere in its chain black, its initial value, and a canvas fills nothing (spec/09 §3.3) — while they agree about :none: SVG writes fill="none" and a canvas issues no fill(). A non-colour key whose reading is nil is still dropped, and the element then takes the mark's own value or the backend's default. A variable in either raises ArgumentError naming it: variables resolve at application (§7.3).

3.5 Derivation: extends

Implemented (work item 3 of #91, D-80). A style MAY name a parent under extends, a {:ref, :style} like any other style reference: the lookup flattens the parent's keys first and the child's over them, key by key, so %{extends: :axis, stroke_width: 2} is the axis style drawn heavier and the four keys of §3.3 are not copied. A chain of any length resolves, each link flattened over the one above it; the parent is looked up among the declared styles and the built-in four, so a design derives from :axis, :grid, :label or :title without declaring them.

Derivation is within a style; composition (§8) is between fragments, and the two never meet. Visualize.Chart.compose/2 unions two styles maps and reports :conflict where they declare one name differently, and extends is a value of a style node like any other key while it does so. What derivation buys is that a dashboard wanting "the series style, but heavier" writes one key instead of copying four that then drift.

A cycle — a style that reaches itself through extends, directly or through a chain — is :cycle at the style's path ([:styles, :series]), reported by the validator for every style that reaches itself, and a design with one does not validate. extends reaches neither the element nor the mark's generator: the lookup consumes it, so a flattened style node never carries it and Visualize.Chart.Style.resolve/3 never sees it.

3.6 Composition at a site: the style stack

Derivation (§3.5) is a chain within a style. A stack is composition at the site that uses one. Five keys refer to a style — mark.style, label.style, mark_label.style, axis.style and legend.style — and each takes either a reference, a style node written inline, or a list of those:

[
  style: :series,
  # one reference, as it always was
  style: [:series, :emphasis],
  # two, the later winning
  style: [:series, %{stroke_width: 5}]
  # a shared style and a local one
]

A list cascades left to right, the later winning, which is Visualize.Chart.stack/1's rule (§8.2) applied at a point rather than across a document. Each entry is resolved through its own extends chain first, and the resolved nodes then merge key by key. The two mechanisms are orthogonal and both remain: extends is a statement about a style, a stack is a statement about this mark.

A bare reference is a stack of one. That is not a compatibility shim but the definition — :series and [:series] resolve to the same node by the same path — so every design written before this section means exactly what it meant.

The private node/2 of Visualize.Chart.Style is where this happens, and it is the only place a reference becomes a node; its eight callers are unchanged.

The local style. The last entry of a stack MAY be an inline style node, and that is where an edit made at the site lands. Editing the stroke width of a mark that references :series must not restyle every other mark that references the same name, so an edit writes to the site's own node and never to the shared one. A local style is created on first edit — a site with no local edit carries references and nothing else, because a document should not carry structure nobody asked for.

It is anonymous in the document: an inline node is not a key of design.styles, so nothing can refer to it. Visualize.Chart.explain/1 needs a name for attribution and synthesises one from where it sits — marks[0].style.local, axes[1].style.local — which is unique by construction, one local per site and one site per position. That name is a display name and not a reference: writing style: :"marks[0].style.local" names a style nothing declares, exactly as any other undeclared name does. Sharing a local style means promoting it to a declared one.

What does not change. A reference to a style nothing declares is the error it already is, at the entry's own path. A cycle through extends is :cycle as before, and a stack cannot introduce one, because a stack is not a chain: an entry may not name the stack it sits in.

4. The frame

4.1 Keys

Implemented. A frame is a coordinate system and its furniture, and a design holds several, by name (#383): frames is a map, so frames.history and frames.now are two plots of the same design over the same sources, placed by their boxes. Visualize.Chart.Frame.new/2 realises one of them into a %Visualize.Chart.Frame{} (§4.7) — every scale built once, the theme resolved, over the marks and labels that say that frame — and Visualize.Chart.Frame.generate/2 renders its furniture: grid, axes, legend and labels, the static part of a chart that a data change never touches (§12).

A design with one frame names it whatever it likes; the migration of an older design names it main (§9).

4.2 Size and margin

Implemented. A design records no size (#383, #427). How big a chart is is a property of where it is shown, not of what it says, so the size comes in at render: Visualize.Chart.apply/2 takes size: as {width, height} — the host's container — and Visualize.Chart.Frame.new/2 takes the same option, {600, 400} by default so a static render still works and a design never carries one. The frame node therefore has no size key, and a design that still has one is the validator's unknown-key fault, which is what makes an unmigrated design fail loudly instead of drawing at a stale size.

A frame's box is its share of the design's (#383): [x, y, w, h] as fractions of the box the render is given (§4.2's size:), so side by side is [0, 0, 0.5, 1] and [0.5, 0, 0.5, 1], a gauge in the corner of a plot is [0.72, 0.04, 0.24, 0.24] over [0, 0, 1, 1], and two boxes that overlap draw over one another. Fractions rather than pixels because the design records no size at all: the same design fills whatever container it is given, and the frames keep their proportions. A frame's own pixel box is [x·W, y·H, w·W, h·H] and its margins come out of that, so each frame has its own plot area and its own margins. z orders the drawing, ties broken by name, so an overlay says so rather than depending on declaration order; background is a colour painted under that frame's contents and nothing else, nil by default — a frame is transparent, so an overlay hides only what it paints.

A grid of weights says where a frame goes, in place of arithmetic (#384). The design's layout is a :layout node — columns and rows, each {:list, :number} of weights and [1] by default, and gap, a :number of pixels between cells, 0 by default — and a frame writes cell: [column, row] in place of box, with span: [columns, rows] ([1, 1] by default) for one that covers more than one cell. columns: [4, 3, 2, 1] is four columns in those proportions, so Context's four windows are cells 0..3 of one row and no fraction is computed by hand.

A weight is not a fraction: the weights are normalised over their sum, so [4, 3, 2, 1] and [8, 6, 4, 2] are the same layout. A weight that is not positive is a fault — a frame with no width is not a frame — as is a cell outside the grid, a span that runs past its edge, and a frame that gives both box and cell, which are two ways of saying one thing.

A cell resolves to a box in one place: Visualize.Chart.Frame.new/2, where a frame's box is read (§4.7). The design keeps what its author wrote — from_map/1 and to_map/1 are inverses and a stored design says cell, not the arithmetic — and everything downstream reads the realised frame's box, so nothing else learns about cells. The gap comes out of the cells' own boxes and not out of the grid's outer edges: a row of cells with a gap still spans the whole box, and each frame's plot is that much narrower. A design with no layout and a frame with no cell are what they were.

The gallery draws what the boxes are for (#429): Load is one load source read twice — a history line over [0, 0, 1, 1] and a gauge of its newest reading (:take, §5.4.1) over [0.72, 0.04, 0.24, 0.24], an overlay with its own background — and Context is one source at four time scales, four :window steps in four frames attached left to right, so a year and the last fifteen minutes are legible in one picture. Load age + gauge (#498) is the overlapping inset from two charts' pieces: Load age's log-age view over the whole box and Load gauge's dial in a box over the age plot's upper-left corner, inside its plot area, at z: 1 on its own background, both read at one now (§12.6).

Margins are pixels and do not scale. :margin has top, right, bottom and left, each :number, :geometry, default 0; the plot area is the given size less the margins, so it is the plot that flexes with the container while the tick text, the axis gutters and the fonts stay the size they were designed to be read at. The same design at two sizes therefore draws byte-identical furniture text and two different plot boxes. Visualize.Chart.Schema.default/2 gives the frame's defaults so a consumer never repeats them, and the frame struct carries the plot area as plot (§4.7).

The :size node kind goes with it: nothing in a design declares a pair of pixels any more. A transform step's size key (§5.4.2) is a {:list, :number} and the compiled chart's own size (§12.1) is the render's, neither of them a node.

4.3 Scales

Implemented. A :scale node is one of the fourteen kinds Visualize.Scale constructs (03-scales §2) with the kind's parameters; every key is :geometry and :override.

A scale name belongs to its frame (#383). scales is a key of the frame, so frames.history.scales.x and frames.now.scales.x are two scales; a frame's own axes and legend read the scales that frame declares, and a mark's or a label's are its own frame's (§5.1, §6.1). A name no frame in scope declares is {:undeclared, :scale, name} as it always was.

A frame may adopt another frame's scale (#384). In place of a node of its own, a frame writes {:frame, f, s} under a scale name — frames.day.scales.y: {:frame, :year, :y} — and that name is then the same scale as frames.year.scales.y: the node is the owner's, so its kind, its nice, its ticks and its declared domain are said once, and its domain is shared — inferred over the channels of every frame taking part, the owner's and every adopter's, so four frames over four windows of one column read against one axis. The range stays the adopting frame's own, since a range is pixels and each frame has its own plot: the same domain drawn at each frame's own size. An axis or a legend on the name draws the shared domain in whichever frame it stands.

A chain resolves to the first declared scale — an adopter of an adopter reads the node at the end of the chain — and a cycle is {:cycle, :scale, name} at the path of the scale that closes it. A frame the design does not declare is {:undeclared, :frame, f} and a scale that frame does not declare is {:undeclared, :scale, s}, both at the adopting scale's own path. An adopted name is a scale of the adopting frame like any other: its marks read it by name and know nothing of where the node came from.

The domain is resolved when the design is applied (§7.3), in two passes: every frame is realised over its own marks, then each adoption group's domains are united — by extent for a continuous scale, by the categories in order of first appearance for a discrete one — and the frames taking part are realised again with that extent given, which is the domains: option Visualize.Chart.Frame.new/2 already takes for a window (§12.5). The realised frame carries what it was given as domains (§4.7), and a compiled chart carries it on (§12.1), so a tick draws the shared domain the chart was compiled with: a compiled chart is one frame (§12.1) and the other frames' rows are not in it to be re-read. A design whose shared domain must follow moving rows on the canvas backends fixes the domain or is compiled again, which is the rule a design whose marks move already follows (§12.5, #424).

A :transition node has duration (:number, :geometry, 300, milliseconds), easing ({:enum, …}, :geometry, :cubic_in_out — a curve of Visualize.Ease by name) and shrink_after (:number, :geometry, 0, milliseconds), every key :override. It says nothing to Visualize.Chart.Frame.new/2, which draws the inferred domain as it always has: a transition is a property of a run, and lives in the thing that runs (§12.5). The same node sits on a mark (§5.1, #417), where it eases the mark's own values instead of a domain and shrink_after says nothing.

Realisation. Visualize.Chart.Frame.new/2 builds one scale struct per entry through the constructors of Visualize.Scale — :linear by Visualize.Scale.linear/0; :log by Visualize.Scale.log/1 with base; :power by Visualize.Scale.power/0 with exponent; :sqrt; :symlog with constant; :time with zone by Visualize.Scale.Time.zone/2 when it is given; :radial; :ordinal with unknown, which on the color scale is the theme's :axis slot when the node gives none (D-122); :band with padding or, when either is given, padding_inner and padding_outer, then align and round; :quantize, :quantile and :threshold; :sequential and :diverging by Visualize.Scale.Color over the range — then the domain, the range, and Visualize.Scale.nice/1 and Visualize.Scale.clamp/2 when the flags are true. The realised scales are cached on the frame and read through Visualize.Chart.Frame.scales/1, the escape hatch for annotations, brush conversion and custom marks; Visualize.Chart.Frame.put_scale/3 replaces one after construction, which is the code-level override of §1.1 — an axis drawn for that name follows the replacement (D-60).

Inference. domain: :auto, or an extent with :auto at one end, is inferred at construction from every mark channel that names the scale, over the sources given to new/2, whole column (Tucan's first-row rule is the documented limit, D-52). A scale whose domain is fixed reads no column (#409): the columns are gathered for the scales that infer one and no others, so a chart whose scales are all fixed — what a streaming design's copy-shift requires of every scale but its viewport's (§12.5) — never walks its rows to build the frame. Visualize.Chart.Frame.new/2 takes domains:, a map from scale name to an extent, which stands in for what would have been inferred: the compiled chart passes the viewport scale's window through it ([hi − span, hi], which the window would have set afterwards anyway), so a tick of a viewport design infers nothing at all:

• A channel names a scale by the frame's kind. In a :cartesian (and a :facet) frame x, x0 and x1 name x; y, y0, y1, median, inner_lo, inner_hi, outer_lo and outer_hi name y; series names color, and so does value on a :rect. In a :polar frame angle, x, x0, x1 and an :arc's start and end name angle; y, y0, y1, median, the four percentile channels, value on a :rose, inner and outer name r; series names color, and so does value on a :rect (#391: the cartesian channels are the polar ones, so every mark is laid out in (angle, r) and bent, §5.2). In a :geo frame series names color. The value of a :symbol, a :circle and an :arc is a size or a share (§5.2) and names nothing. A mark's scales node (§5.1) renames what its channels name: scales: %{x: :count} sends that mark's x, x0 and x1 through the frame's count scale instead of x, so a scale of any other name — a marginal histogram's counts, a second y — is inferred from, and drawn by, the marks that name it (D-67). A {:field, f} on a :colour key of a mark's style names color in every kind (§3.2), whatever the mark's scales say.
• The values are the channel's column of the mark's source through Visualize.Data.Table.get/2 — the field itself, or the f of a {:field, f} — with nils dropped; a number channel contributes the number, once the mark has a row to draw it on, and a {:scale, :min} or {:scale, :max} (§5.2) contributes nothing, since it is read from the domain. A constant is data to inference: a rule at y: 0 holds 0 in an inferred y domain, which is a baseline meant to be seen, but a :text mark at x: 0 holds 0 in an inferred x domain as well, which a caption never means — a series whose readings scroll away from zero is then drawn over the right part of its plot, and a step bound to the plot's columns (§5.4.1's :m4) no longer lands on them. The validator reports the second as {:feeds_domain, scale, n} (§10.1, #490, D-124); a text that should stand at an edge whatever the data reads {:scale, :min} or {:scale, :max}, and one that needs no datum is a frame label (§6.3). A mark whose source is not among the bound sources contributes nothing; a mark that reads its source through transforms contributes the column of the transformed rows — the pipeline of §5.4 runs at construction over the bound source, so a :bin's count or a :stack's y1 infers the domain it is drawn on (D-62). A row a :projection clips is among those rows, with nil positions (§5.4.4, D-130), so inference reads every row, drawn or not, and a domain over its other columns is the same whatever the view.
• The domain follows the kind. Continuous scales (:linear, :log, :power, :sqrt, :symlog, :radial, :quantize, :threshold, :sequential) take the extent [lo, hi] of Visualize.Data.extent/2; :diverging takes [lo, (lo + hi) / 2, hi]. :time takes the extent under the values' own ordering (DateTime, Date or NaiveDateTime compare by their module, never by term order), an ISO 8601 string read as Visualize.Data.Table.temporal?/1 reads it, and a value that is not temporal raises ArgumentError naming the scale. :quantile takes every value as its samples. :ordinal and :band take the distinct values in order of first appearance.
• [0, :auto] fixes the lower end and infers the upper; [:auto, hi] the reverse.
• A collapsed extent — one distinct value — stays [v, v]: every continuous scale maps it to the range midpoint and its axis draws one tick (D-49). The frame never widens a domain; an author who wants a readable axis fixes an end.
• Nothing bound gives the unit domain: [0, 1] for a continuous scale ([1, 10] for :log, whose domain excludes zero), [0, 0.5, 1] diverging, one day from the Unix epoch for :time, [] for the discrete and quantile scales. A frame therefore renders without any source, over its unit domains, which is what the static split needs (§12).

Range. range: :auto follows the scale's name. x is [0, width] of the plot area and y is [height, 0]; angle is the sweep from its start — [start, start + sweep] in radians, clockwise from 12 o'clock (04-shapes-and-curves §6.2), the full turn [0, 2π] by default, so a 90° gauge at the top-left is start: -90, sweep: 90 and a speedometer start: -120, sweep: 240 (#390; a range given as a list still wins, and start/sweep on any other scale say nothing). A categorical angle (#393) is a :band scale on angle: its categories are spaced evenly over the sweep and the range is widened by half a step at each end so the band centres — where a position channel lands — span the sweep: on a full turn the step is sweep / n and the range [start − step/2, start + sweep − step/2], so the first category stands at the start, the last one step before it, and the ring closes with nothing overlapping; on a partial sweep the step is sweep / (n − 1) and the range [start − step/2, start + sweep + step/2], the categories ends-inclusive. The angle axis on it ticks every category at its band centre; r is [0, min(width, height) / 2]; color on a discrete scale is the theme's series as slot atoms, [:series_1, …, :series_n], which the legend and the marks resolve through Visualize.Theme.resolve/3 in the mode of their render target, so a theme swap recolours the scale's output. A :sequential scale, whatever its name, runs from the theme's background to its first series colour and a :diverging one from the second series colour through the background to the first: a colour scale's output is a colour, and the plot area has nothing to offer it. Any other name follows the first axis that names it — :top or :bottom as x, :left or :right as y — and is [0, 1] when no axis does. A range given as a list is used as it is — which is how one frame held two panels (#376): a second pair of position scales whose ranges are the lower half of the plot, y ranging over the upper half, the second panel's marks reading the pair through their scales renames (§5.1), an axis per scale each spanning its own range. Two panels are now two frames (#383): the gallery's Spectrum drew its signal above its spectrum that way and is now a signal frame over the upper half of the box and a spectrum frame over the lower, each with its own x and y, which is what the trick was standing in for — an explicit range stays what it always was, the way to say where one scale draws. An empty list raises ArgumentError naming the scale — a scale with no value to map to is an authoring error, not a scale; a scheme name is Visualize.Scale.Color.scheme/1's stops, the colours of a discrete scale or the interpolator of a colour scale. A scale name is any atom; the names x, y, angle, r and color carry the meanings above, so an axis or a legend on any other name MUST say where it draws through side and position. An offset scale (#132): the names x_offset and y_offset are a band within a band — a :band scale whose :auto range is [0, bandwidth] of the scale its family maps to (x or y, or whatever the mark's scales node renames it to), realised after that scale; its domain is inferred from the fields the marks' offset nodes read (§5.1). A range given as a list is used as it is.

4.4 Axes and tick specs

Implemented. An :axis node draws a scale on one side of the plot area; tick geometry is a :ticks node, the fourth level.

ticks as an integer is the count hint, as a list the explicit values, as a :ticks node both with the sizes: count (:integer, :geometry), values ({:list, :term}, :content), size_inner and size_outer (:number, :geometry, 6) and padding (:number, :geometry, 3) — the setters of 05-axes-and-formatting §1.2 by name. Explicit values beat the count, and the count beats the scale's default of ten.

Each axis is a Visualize.Axis on the realised scale, oriented by side, with the tick spec, offset and the frame's theme applied, generated in the :resolve mode of the render (spec/05 §1.4) and placed at its side of the plot area: :bottom at translate(0, height), :right at translate(width, 0), :top and :left at the origin. A frame's axis is therefore byte for byte the axis a caller builds by hand from the same scale, and test/visualize/chart/frame_test.exs holds it to that. format is a Visualize.Format specifier applied to every tick value: Visualize.Format.time/2 on a :time scale — of the tick shifted into the scale's zone by Visualize.Scale.Time.local/2, so an explicit tick value prints in local time like a computed one (spec/05 §2.8, #447) — Visualize.Format.formatter/1 on any other, a tick value that is not a number passing through to_string/1 — or the name of a format no specifier can express: :duration, Visualize.Format.duration/1 over a value in seconds, the unit chosen by magnitude (45s, 2m30s, 1.5h; spec/05 §2.9, #191). Bytes by magnitude are the specifier's own s type with a unit (format: ".1~s", unit: "B" prints 2.3GB). A tick carries a unit (#135): prefix and unit are literals put before and after every tick's label — the formatted value, or the default label when there is no format — so unit: "M" prints 1412M, prefix: "$", unit: "T" prints $5T, and unit: "%" prints 45% of a value already in percent, where the specifier's own % would multiply by a hundred. The specifier stays d3's; a unit is what every caller was concatenating by hand, and the two keys live on the axis beside format, the key they complete, rather than on the :ticks node, which holds geometry.

grid: true draws a line at each tick position across the plot area — the height for a :top or :bottom axis, the width for a :left or :right one — in the :grid style, behind every axis, in one group class="grid" that is aria-hidden like the axes (D-56). The axis's line, ticks and labels draw in its style; tick sizes stay geometry. A style other than :axis restyles the generated axis: stroke, stroke_width, stroke_dasharray, stroke_linecap, stroke_linejoin and stroke_opacity reach the domain line and the tick lines, fill and the font keys reach the tick labels, opacity and class the axis group.

An axis has no id: its identity in a stack is {scale, side} (§8.2), so a layer that wants the shared frame's bottom x-axis with six ticks writes an axis for that scale and side and replaces it, and two axes drawing one scale on one side can never both be drawn. Nothing in the axis node is required to make that identity — scale and side are both required keys already.

4.5 Legend

Implemented. A :legend node explains one scale, normally the colour scale.

The frame builds the legend from the realised scale: one entry per value of Visualize.Scale.ticks/2 — the domain of a discrete scale, five ticks of a continuous one — each a 12 × 12 swatch and, 16 user units to its right, the value's label as an axis would print it (spec/05 §1.5), with the legend's own prefix and unit before and after it (#135), so a legend explaining a scale with units agrees with the axis drawing it. The swatch is filled with the scale's value for the entry when that is a colour — a string, or a theme slot resolved through Visualize.Theme.resolve/3 (§4.3) — and with the theme's {:series, i} for the i-th entry of a scale that yields anything else. The labels and the title take the legend's style.

group  style: %{class: "legend", font_family: <font_family>, font_size: <font_size>}, transform: translate(x, y)
├── text   style: %{fill: <fill>, font_weight: :bold}, content: title            — when the title is given
└── group  style: %{class: "legend-item"}, attrs: %{"data-series" => value}, transform: translate(…)  — one per entry
    ├── rect  0 0 12 12, style: %{fill: <swatch>}
    └── text  x: 16 (or −4, anchored end), y: 6, dy: "0.32em", style: %{fill: <fill>}, content: label

Entries are 16 apart and the title, when given, is the first row. position places the legend inside the plot area, 8 user units from its edges: the four corner positions stack the entries downward from the corner, the right-hand ones laid out right to left — the swatch at the edge and the label anchored end to its left — so no text width is needed; :left and :right stack them likewise, centred on the plot's height; :top and :bottom lay them in one row centred on the plot's width, each entry's width taken as 16 plus 0.6 × the font size per character of its label — the one place the layout estimates text.

A legend in a margin (#136). With inside: false the legend sits in the margin its position names, 8 user units out from the plot's edge, laid out in the same direction as inside: :right, :top_right and :bottom_right stack in the right margin, at the plot's top, centred on its height, or at its bottom; :left, :top_left and :bottom_left likewise in the left margin; :top and :bottom run in one row in the top and bottom margins, centred on the plot's width, the row's swatches 8 above the plot's top edge or 8 below its bottom one. Outside there is room, so every position reads swatch-then-label — the right-to-left order is the inside layout's alone — and a left-margin legend is placed by its estimated width so its labels end 8 from the plot: the swatch, the gap and 0.6 × the font size per character of the longest label (the title counted as a label). A legend that does not fit its margin is not clipped silently: Visualize.Chart.Frame.new/2 raises ArgumentError naming the margin and the size the legend needs — its estimated width for a side margin, its rows × 16 (the swatch's 12 for a row) plus the 8 for a top or bottom one — as it raises for an empty range, since a legend the author cannot see is worse than a fault. The converted gallery charts that reserved a margin for their legend draw it there.

Every entry's group carries data-series, to_string/1 of the entry's value — the string every element of that series carries (§5.6) — so LegendHook (spec/10 §14) can hide what the entry explains; it is written whatever the scale and is inert without the hook (D-77).

4.6 Kind-specific nodes

Implemented.

• :cartesian reads scales, axes and legend as §4.3–4.5 give them.
• :polar places its furniture with translate(width / 2, height / 2), the plot centre, and uses angle and r as its position scales with R = min(width, height) / 2 the outer radius (§4.3). The polar axes follow their scales' ranges (#390): the angle scale's range is a sweep from a start (§4.3) and the r scale's a band [inner, outer], and the furniture draws those and no more. An axis on angle draws an arc: the domain line is the arc of the scale's range at the axis's radius (R when absent) — one A command from the start to the end, the large-arc flag set past a half turn, and a circle when the sweep is a full turn, so the full-turn output is byte for byte what it was; at each tick a line from the arc's radius outward by size_inner along the tick's spoke and its label size_inner + padding beyond that, anchored middle with dy: "0.32em"; grid: true adds a spoke from the r range's inner radius to its outer per tick. An axis on r draws a spoke: the domain line from the inner radius to the outer in the direction its side names (:top upward, :right, :bottom, :left) or its at gives (degrees clockwise from 12 o'clock, winning over side), at each tick a line of size_inner across the spoke with its label padding beyond it, and grid: true adds an arc over the sweep at each tick's radius (a circle on a full turn). An axis on any other scale draws as in a cartesian frame. Every ordinary mark is laid out in (angle, r) and bent (§5.2, #391). Its groups are class="axis axis-angle" and class="axis axis-r"; every polar coordinate is rounded to six decimals with negative zero folded (D-6), so a right angle lands on the axis, and a grid ring of zero radius is not drawn.
• :geo takes a :projection node in place of position scales: type (:name, required, a type of Visualize.Geo.Projection), scale (:number), translate, center, rotate, parallels ({:list, :number}) and clip_angle (:number), every key :geometry and :override, defaults those of Visualize.Geo.Projection.new/1 except translate, which defaults to the plot centre. The frame realises it through that module's setters and Visualize.Chart.Frame.projection/1 returns it; an axis or a legend on a declared scale draws as in a cartesian frame. Delaunay, Voronoi and contours are transforms (§5.4). The view can fit a source (#475): fit ({:node, :fit}, :binding, :override) holds data ({:ref, :source}, :binding, required), the points as fields ({:list, :field}, :binding, [longitude, latitude]) or the geometries as field (:field, :binding, a GeoJSON geometry or feature per row, as the :projection transform reads them, §5.4.4), and padding (:number, :geometry, 0, pixels). One of fields and field is required, and the validator reports a fit with neither as fields :required and one with both as field {:invalid_for, :fit}. The frame reads the bound source's rows — before any mark's transforms — for every point they hold (every position of a geometry, at any depth of its coordinates, its geometries or its features; a nil or non-numeric coordinate is skipped) and sets the projection's scale and translate by Visualize.Geo.Projection.fit/3 (spec/07 §1.6) to the plot area inset by padding on every side, after the other keys are applied, so a scale or a translate given beside a fit is overwritten by it; center and rotate are kept, so a Mercator projection fitted to a track is still tile-aligned and a :tiles mark follows the fit (§5.2). A source not bound, or one with no point, leaves the projection as its other keys give it. The fit is read wherever the frame is realised, so a compiled chart fits every tick's rows (§12.2).
• :facet repeats the frame over a grouping: a :facet node with by (:field, :binding, required) and columns (:integer, :geometry, nil for one row). The panels are the distinct values of by, in order of first appearance, over the bound source of every mark (a source without the column contributes nothing), so a frame with no bound source has one panel; Visualize.Chart.Frame.new/2 records them as panels. The panels tile the plot area in columns columns and as many rows as they need, each width / columns by height / rows; the scales' :auto ranges run over one panel and their domains are shared, so every panel is drawn to the same axes; each panel is a group class="panel" translated to its cell holding the grid, the marks drawn from the rows whose by is the panel's value (§5.6), and the axes, with its value written at the panel's top-left in the :label style. The legend and the labels are drawn once, over the whole plot area.
• viewport makes a streaming window: scale ({:ref, :scale}, required) and span (:number, required), both :geometry. The frame itself draws the scale over its inferred or given domain; a compiled chart over a design with a viewport windows the scale to [hi − span, hi] on every tick and is stateful (§12.5).

4.7 The frame struct and its rendering

Implemented. %Visualize.Chart.Frame{} is the realised frame: kind; size, the {width, height} the caller gave as size: or the {600, 400} default (§4.2) — the design has none — and margin with the schema's defaults filled; plot, %{width, height} of the plot area; scales, the realised structs by name (§4.3); projection, a %Visualize.Geo.Projection{} in a :geo frame and nil otherwise; panels, the facet values of §4.6, [] in any other kind, and facet, %{by, columns} with the effective column count in a :facet frame and nil otherwise; domains, the extents the frame was realised with rather than inferring — a shared scale's (§4.3) or a window's (§12.5) — %{} when it inferred everything; axes, legend, labels and marks as the design gives them; theme, the %Visualize.Theme{} the design names — a built-in name or an inline :theme node — or the theme: option of new/2, which is taken for any name and required for one that is neither built-in nor inline; and styles, the declared styles over the built-in four (§3.3); and sync, the design's sync group when this frame is the one the group reads (§2.9), nil otherwise.

A design renders its frames in z order (#383): one group per frame, <g class="frame frame-<name>" transform="translate(x, y)" data-node="frames.<name>"> at the frame's own pixel box (§4.2), holding that frame's furniture, its marks and its labels; a background is a rect at the frame's box under them. Ties in z are broken by name, so the drawing order of a design is a property of the design and not of the order a map happens to enumerate in. Visualize.Chart.Applied holds frames, the realised frames by name, beside the chart and its sources.

Visualize.Chart.Frame.generate/2 is one frame's static furniture as one Visualize.IR.Element group with the margins applied, every theme slot resolved through Visualize.Theme.resolve/3 in its :resolve mode (:css by default), and every text a string:

group  style: %{class: "frame"}, transform: translate(margin.left, margin.top)
├── group  style: %{class: "grid"}, attrs: %{aria_hidden: "true"}   — when any axis has grid: true (§4.4)
├── group  style: %{class: "mark mark-<type>"}                        — one per mark, when sources are given (§5.6); `:tiles` marks first (§5.2)
├── group  style: %{class: "axis axis-<side>"}, transform            — one per axis, holding the Visualize.Axis group
├── group  style: %{class: "legend"}                                 — when a legend is given (§4.5)
└── text   style: %{class: "label", …}                               — one per label (§6.3)

With paths: true the frame's group, each mark's and axis's group, the legend's group and each label's text carry data-node with the node's path (below).

A :facet frame holds one class="panel" group per panel in place of the grid, marks and axes; a :polar frame's grid, marks and axes sit inside a group translated to the plot centre. generate/2 draws the marks only when given sources: — a map from source name to anything Visualize.Data.Table.rows/1 reads, as new/2 takes — each through Visualize.Chart.Mark.generate/3 at its one-based position; without sources it is the furniture alone, which is what the static split needs (§12). A %Visualize.Chart.Var{} reached while building — in a text, a style or a node — raises ArgumentError naming it: variables resolve at application (§7.3), and a frame is built from an applied design or from one that uses none. Visualize.Chart.Frame.render/2 is generate/2 followed by Visualize.Render.to_string/2, with :resolve defaulting to Visualize.Theme.mode/1 of the :backend, as Visualize.Axis.render/2 does.

Every node the frame draws carries its path when asked (#259, D-105). generate/2 and render/2 take paths:, false by default; with paths: true the element each design node renders carries data-node spelling the node's path as Visualize.Chart.Validator.format_path/1 spells one — frames.<name> on the frame's own group, marks[i] on a mark's group (its zero-based position among the design's marks, not among the frame's), frames.<name>.axes[i] on an axis's group, frames.<name>.legend on the legend's, labels[i] on a label's text. The frame stamps what it places: a mark's group is Visualize.Chart.Mark.generate/3's as it is, tagged by the frame at the design position it came from, so a facet frame's copies of one mark carry one path, a polar frame's ring and spoke axes keep their positions among axes, and the second mark of a design drawn in the second frame is marks[1] there. A mark's inline label (§5.5) sits inside its mark's group — in the labels group beside the mark's elements (§5.6) — and has no path of its own; the grid is furniture, not a node. Without the option the markup is byte for byte what it was, so a chart drawn for a page is unchanged, and the builder — which draws with it so a click on the graph can name what it hit (§18.4, §18.16) — is the caller that asks. Visualize.Chart.render/2 passes it through.

A design renders as a document when asked (#131). Visualize.Chart.generate/2 is the applied chart as a Visualize.IR.Element — the frame's group, as generate/2 above builds it over the bound sources — and Visualize.Chart.render/2 is that element serialised. Both take root:, false by default: with root: true the group is the one child of Visualize.IR.Element.root/3 at the frame's own size, the accessible root of spec/02 §2.1 — role="img", the viewBox, a <title> and a <desc> first with aria-labelledby naming them — its title and description the design's meta.name and meta.description (§2.1), each a text with no hole left in it after application, an absent or empty one leaving its element out; title: and description: override them and responsive: reaches the root as its own option. A design carries everything the root needs, so nothing new is written to say it: a caller that put a chart in a page built this <svg> by hand, and three of them did it three ways. The default stays the bare group, so nothing that renders a chart today changes. The components of spec/10 keep their own <svg>: their markup is what spec/10 §1.2 specifies, class and font included, not a shell around a rendered design.

5. Marks

5.1 Keys

Implemented. A mark binds fields of its data to the frame's scales and draws them with one of the existing generators. Visualize.Chart.Mark.generate/3 draws one mark of a frame (§5.6); Visualize.Chart.Frame.generate/2 draws every mark of the design when it is given the sources (§4.7). render is the compiler's override (§12.3) and changes nothing generate/3 draws.

frame is the frame the mark is drawn in (#383), required when the design has more than one and the single frame's when it has one — the validator reports a mark without one in a multi-frame design as :required and a name the design does not declare as {:undeclared, :frame, name}. A scale name resolves inside the mark's frame, so history and now may both declare x or r and each mark reads its own; that is what makes two plots over one source two frames rather than two designs.

scales is the mark's word on which scale a channel family reads through (§4.3). A :mark_scales node's keys are the scale names of the frame kinds' tables — x, y, angle, r and color — each {:ref, :scale}, :channel, nil by default, :override; a key the frame's kind does not use names nothing. scales: %{x: :count} sends the mark's x, x0 and x1 through the declared scale count, and every channel not renamed reads the scale of the kind's table as before. The name must be one the frame declares ({:undeclared, :scale, name} otherwise), so a mark still references scales by name and never by nesting (§1.2).

offset is a band within a band (#132, D-109): a :mark_offset node's keys are x and y, each a :field, :channel, nil by default, :override — the field whose value places the datum within its band on that family. With offset: %{x: :series} a :rect's x0 and x1 read the category's band from x as before, then the series' band from the x_offset scale (§4.3) inside it: x0 at the outer band's start plus the inner band's start, x1 a bandwidth of the inner further, a position channel at the inner band's centre; the reading adds, which is d3's own model and the one the layer's grain allows, since the frame owns both scales and an offset scale is a scale. A grouped bar chart is therefore one :rect mark over one row per bar, its x_offset a :band over the series; an offset on y is a grouped horizontal bar; an offset scale with one member is the ungrouped chart. A family whose outer scale is not a :band, or a datum the inner scale cannot place, places nothing (§5.2's per-datum drop). The mark's scales renames apply to both: scales: %{x: :cat, x_offset: :inner}.

transition is the same :transition node a scale takes (§4.3), saying that the mark's values move to their readings rather than appearing at them (§12.5, #417): a needle on a dial sweeps over duration milliseconds along easing, and shrink_after, which is a domain's hysteresis, says nothing here. Like a scale's, it says nothing to Visualize.Chart.Frame.new/2 and nothing to Visualize.Chart.render/2 — one frame has nowhere to move from — and lives in the thing that runs.

id is the mark's identity in a stack (§8.2): a higher layer's mark with the same id replaces this one in place rather than drawing a second mark beside it. It is optional, is not required to be unique, and nothing renders from it — a mark without one appends, as every mark did before identity existed.

5.2 Types and channels

Implemented. The mark types are the data-shaped generators of 04-shapes-and-curves and four generic marks. A :channels node's keys are the channels; every key is :channel, :override, of type :channel. Which channels a mark takes is a function of its type, and the validator reports a channel the type does not read as {:invalid_for, type}:

series names what a row belongs to, on every type that draws rows (#508, D-126). Every type but :percentile_band and :tiles takes an optional series channel. It is read raw and is never mapped as a position. On a :line or an :area it also splits the rows, one path per series value in order of first appearance. On every other type each datum is still its own element, and the channel says which series that element belongs to. On every type it does the same two things (§5.6). Each element the mark draws for a series carries that series' data-series, and so does every inline label drawn for it, so a legend toggle hides everything the series draws (spec/10 §14). Each element is painted the series' colour unless something more specific paints it. The points of a series drawn as a :circle or a :symbol mark beside its :line therefore name the same series as the line, are painted the same colour, and are hidden with it. A :percentile_band draws one band from all its rows, so it has no element per series to name. A :tiles mark draws no rows.

In a :polar frame every ordinary mark bends around the arc (#391). The mark is laid out exactly as in a cartesian frame — its channels through the frame's scales, x through angle (radians, the sweep of §4.3) and y through r (user units from the centre) — and its geometry is then bent by Visualize.Chart.Mark.Bend.bend/1, a pure function of the mark's element group, so every backend draws the same elements: a point (a, r) goes to (r · sin a, −r · cos a) (spec/04 §6.2's convention, the centre at the origin); a line element and every straight segment of a path (L, H, V) is sampled at no more than 2° of angle and bent point by point, so a :line wraps around the arc and a :rule at x is a spoke; a C or Q command is sampled along its parameter, so a curve is interpolated in (angle, r) before it bends; an A command likewise; Z is kept; a rect becomes an annular sector — its x extent the angles, its y extent the radii — so a :band is a sector band, an x_band a wedge, and a :rect with a band on y a bar that arcs around the chart (with a band on x, the rose); a circle keeps its radius at the bent centre, so a :symbol and a :circle stay dots; a text moves to the bent point; a group's children bend and a translate in a transform bends as a point. The marks that are polar already — :rose and :arc — and a :path, whose rows carry geometry in plot pixels, are drawn as they are. A :rule and an :x_band in a polar frame span the r range — the band from the inner radius to the outer — where a cartesian one spans the plot height, and a :rule may give y in place of x (#391) to stand at a radius instead of an angle: an arc over the sweep at r(y). :area's baseline is r's zero, clamped to the r range — the inner radius. An :arc's start and end read through the angle scale when the frame declares one, raw radians otherwise, so a layout's angles (the sunburst's) still land where they were computed. A mark's inline label anchors at the bent point, its radii the sector's, so :outward and :inward work on a bent mark as on a rose. A :needle (#392) is the gauge's indicator, drawn by Visualize.Shape.Needle (spec/04 §16) in the plane already — a filled tapered path from the hub to the tip at angle(x) and r(y) (the outer radius when y is absent), with inner_radius, width, tail, hub and cap as §5.3 says — plus the hub circle, both in the mark's style (fill both, stroke outlines); its inline label anchors at the tip, :outward by default, its radii {inner_radius, length}; one needle per row, so three rows are three needles. It is drawn as it is, like the rose, and is refused outside a polar frame. Over a categorical angle a straight segment is a chord (#393): when the frame's angle scale is a :band the bend does not sample a straight segment but joins the two bent points with one L, so a :line over (category, value) is the polygon of a radar and an :area its volume; :step_after there steps along an arc at each point's radius to the next spoke, since a horizontal run (H) in (angle, r) is a run at one radius and is sampled into an arc even where straight segments are chords; over a continuous angle straight segments follow the arc as above. closed (:boolean, :geometry, an option of :line and :area): the loop closes back to its first point — the first row is appended after the last at its angle plus the sweep, so the closing segment runs forward round the ring — true by default on a full turn over a categorical angle, false otherwise; a closed curve (:cardinal_closed, :basis_closed, spec/04 §5) closes itself and is not appended to. Several series through series are each their own loop and volume, drawn in series order on top of one another — a translucent fill_opacity shows every volume through the others, the scope view — and a :stack step ahead of the mark sums them where that is wanted.

An area's default baseline never leaves the plot (#420). With no y0 an :area fills to the y scale's zero — d3's convention, and what a diverging area wants — and so does the area under a filled :line (§5.6). Where the domain excludes zero that pixel lies outside the scale's range: an area over [50, 150] filled 205 px below a 410-high plot, across the axis and into the margin, marks being unclipped. The default is therefore clamped to the scale's range — the zero line where zero is in view, the nearer edge of the plot where it is not. A baseline the author gives is placed as given, whether it is a field, a constant or {:scale, …}: a ridgeline's y0: :base is one baseline per ridge stepping up the plot, and a partial fill is exactly what an explicit baseline is for.

A :tiles mark is a Web-Mercator basemap (#475): the slippy-map tiles under a :geo frame's projection, so a GPS track or a set of sensor locations drawn through that projection sits on its streets. It takes no channels and draws no rows: data is not required of it, and one given is checked as any mark's and read by nothing. Its tiles node ({:node, :tiles}, :content, :override, required of a :tiles mark and {:invalid_for, type} on any other) holds url (:string, :content, required) — the provider's template with {z}, {x} and {y} and optionally {s} —, attribution (:string, :content, required), subdomains ({:list, :string}, :content, ["a", "b", "c"]) and max_zoom (:integer, :geometry, 19). From the frame's projection the mark takes the zoom of spec/07 §8.2, the tiles covering the plot area of §8.3 and each one's URL by §8.4 — {s} is subdomains[rem(x + y, n)] over the wrapped column — and draws, in the plot area's coordinates:

group  style: %{class: "mark mark-tiles[ <class>]"}
├── image  attrs: %{href: url, x: left, y: top, width: size, height: size}   — one per tile, row then column (spec/07 §8.3)
└── text   attrs: %{x: width − 4, y: height − 4}, style: %{class: "mark-attribution", text_anchor: :end, …}, content: attribution

The attribution is drawn, always, in the plot area's bottom-right corner, 4 px in from both edges with its baseline on the inner line, anchored at its end — where every slippy map puts it, so a reader looks for it there. Its style is the mark's style over the built-in :label style (§3.3), resolved as §3.4 says, so a design sets its size, colour or font as for any text; text_anchor is :end whatever the style says, since the corner is the right edge. The images carry no style: a tile is the provider's picture. A fit padding (§4.6) keeps data out of the corner where a design needs both.

Tiles go beneath every other mark, whatever the marks' order (D-119). A frame draws its :tiles marks first among its marks, in design order among themselves, and every other mark after them in design order (§4.7, §12.2): a basemap is the ground the marks stand on, and a design composed from fragments (§8) does not control which fragment's mark comes first, so "beneath" is the mark type's property and not an ordering the author must remember. A mark's paint index (§5.6) and its data-node path (§4.7) are still its position in the design.

The library never fetches a tile. It writes <image href> elements, and the browser loads them as it loads any image; a wrong URL shows as broken tiles, not as an error here. The provider, its terms and its usage policy are the host's — public servers such as OpenStreetMap's have policies a polling dashboard must respect — which is why url and attribution are both required intent in the design rather than defaults in the library.

The frame must be a :geo frame whose projection is tile-aligned (spec/07 §8.1): :mercator, its center latitude 0, its rotate tilt and roll 0. Otherwise the validator reports {:tiles, :projection, what} on the mark's type (§10.1). A :tiles mark's render target is :svg whatever render says (§12.3). On a hybrid page the tiles are the backdrop (#476, D-120). A compiled chart draws a :tiles mark's images in its backdrop layer, a document the page stacks beneath the canvas, and its attribution in the SVG layer over the canvas (§12.3, §12.4): a dense track on the canvas then sits on the roads, and the attribution stays readable over it. On the whole-chart canvas backends a tile is an :image element: Visualize.Backend.Canvas draws it when it loads, after the commands drawn synchronously and so over them (spec/09 §3.4), and the binary stream drops it (spec/09 §4.4), which has no image record and gains none. A design with a basemap is drawn on SVG, or by a compiled chart on a page that stacks the backdrop; a whole-chart canvas is not a basemap's backend (D-120).

Visualize.Chart.Schema.channels/1 returns the two lists for a type. A channel reads its field from each row through Visualize.Data.Table.get/2 — a number is a constant, a {:field, f} reads f — and the frame maps the reading through the scale the channel names (§4.3) when the frame declares that scale. A channel may name its scale's own end (#420): {:scale, :min} and {:scale, :max} read the low and the high end of the domain of the scale that channel maps through — by value where the domain is numeric, by position where it is not (the first and the last member) — mapped like any other reading, so y0: {:scale, :min} fills an area down to the bottom of its axis whatever the domain turns out to be, which an inferred domain could not be told to do and which a number could only say for a fixed one. It is a tuple because an atom is a field name and always will be. It reads through the channel's own scale, so a mark's scales rename is honoured and a polar :area reaches the inner radius the same way; a channel whose scale the frame does not declare places nothing, as any unplaceable reading does. A datum the scale cannot place (a nil reading, or a category a :band or an :ordinal scale does not hold) is dropped from a per-datum mark and breaks a path mark's path there, as defined/2 of spec/04 §1.2 would. A :line or an :area path — one per series — none of whose data is placed draws no element at all, never an empty <path d="">, so a series a projection clips whole leaves nothing behind (D-130); a :path mark's row whose path is nil likewise draws nothing. Through a :band scale x0 (and y0) is the band's start, x1 (y1) its end — the start plus Visualize.Scale.bandwidth/1 — and x (y) its centre, so a bar over categories is x0: :cat, x1: :cat and a point over them sits mid-band. A channel that names no scale, or names one the frame does not declare, is read as pixels: path, the value of a :symbol and of a :circle, the value, start and end of an :arc (a share and two angles in radians, never scaled in any kind), and the position channels of a :geo frame, whose pixels come from the :projection transform (§5.4.4). An :arc's value is required unless both start and end are given, and either of those two requires the other: the validator reports the missing one as :required (D-69). series splits a :line or an :area into one path per distinct value, in order of first appearance, and colours each as §5.6 says.

5.3 Options

Implemented. An :options node holds a mark's geometry scalars, every key :number (cap an enum, #392; closed a boolean, #393), :geometry, :override; the validator reports a key the type does not read as {:invalid_for, type}. Visualize.Chart.Schema.options/1 returns a type's keys; the defaults are the generators' own, with R the outer radius min(width, height) / 2 of the plot area.

An :arc's inner and outer channels replace inner_radius and outer_radius per datum; its start and end channels, given together, replace the pie — start_angle and end_angle are not read then, and pad_angle is the arc's own (Visualize.Shape.Arc.pad_angle/2) rather than the pie's. Angles are radians and sizes user units, as in 11-public-api §3.3.

5.4 Data and transforms

Implemented. data is a source name, or a :data node with source ({:ref, :source}, :binding, required) and transforms ({:list, {:node, :transform}}, :binding, [], :concat). Layouts, binning, stacking, aggregation and the geo algorithms are transforms — steps in a mark's data pipeline that yield rows — never marks: a treemap is a :treemap transform producing rows with x0 y0 x1 y1 that a :rect draws, and a chord diagram is a :chord transform whose rows carry a path that a :path mark draws.

Visualize.Chart.Transform.apply/3 runs the steps in order over the source's rows (Visualize.Data.Table.rows/1), each step a pure function of the rows before it and its node, yielding the rows the next step or the mark reads. Its only context is the plot area, as size:, the point a centred mark is about, as centre: ([x, y]: the plot's middle, or the origin of a :polar frame's centred group, which already sits there — the point an :arc or a :rose mark is about, §5.6, and the middle of size: when not given), in a :geo frame the projection, as projection:, the bound sources, as sources:, for the one step that reads a second table (a graph's nodes, §5.4.3), and the instant a relative window is measured from, as now: (§5.4.1's :window) — never a scale, so the frame runs the pipeline before its scales exist and infers their domains from the transformed columns (§4.3, D-62). A step that reads a column the rows lack reads nil and treats it as the op says; a step that lacks a key its op requires raises ArgumentError naming both.

A :transform node has op ({:enum, ops}, :binding, required) and the keys its op reads; every key is :override. Visualize.Chart.Schema.transform_keys/1 returns the required and optional keys of an op, and the validator reports a missing required key as :required and a key the op does not read as {:invalid_for, op}:

The ops are :filter, :bin, :stack, :fold, :sum, :sort, :take, :window, :spectrum, :lttb, :m4, :tree, :cluster, :pack, :partition, :treemap, :chord, :sankey, :force, :contour, :density, :delaunay, :voronoi and :hexbin (Visualize.Chart.Schema.transform_ops/0) and :projection. Every row a step yields is a map; a row the step derives from a datum keeps the datum's columns and adds its own, so a :treemap node still carries its name. A field named in a mark's channels, in its inline label's text or in its transforms is checked against the source's declared fields when the mark reads the source directly. After a transform the columns are the transform's, and a {:field, f} in a style is shared by every mark that references the style; those references are read at render, when the rows exist.

5.4.1 Data steps

• :filter — field required; test (:present) and value (nil). The rows, in order, whose reading of field through Visualize.Data.Table.get/2 passes the test: :present keeps a reading that is not nil and :absent one that is; :eq keeps a reading equal to value (==) and :ne one that is not; :lt, :lte, :gt and :gte keep a reading that is not nil and stands so to value under Elixir's term ordering, as :sort orders — a nil reading never passes an ordering. The step reads a column the rows lack as nil, so %{op: :filter, field: :height, test: :eq, value: 0} after a hierarchy keeps its leaves and %{op: :filter, field: :depth, test: :gt, value: 0} drops its root (D-68). The transform node's op names the step, which is why the test is not under op.

• :take — n required (:integer, :geometry); side ({:enum, [:end, :start]}, :geometry, :end). The last, or the first, n rows in order (#383). n at or above the row count is every row and n of zero is none; a negative n raises ArgumentError as the step's fault. The gauge of a design that shows the newest reading beside its history reads take(1).

• :window — field required (:field, :binding, a time column); from and to ({:list, :term}, :geometry, nil), each a duration ago as [n, unit] with unit one of :second, :minute, :hour, :day, :week, :year and a unit the seconds it names (a :day is 86,400 seconds and a :year 365 of those — a window is an extent of time, not a calendar walk). The rows whose reading of field lies in [now − from, now − to), in order. A given to is exclusive, which is what stops two adjacent windows sharing a row — window(:t, from: [1, :year], to: [24, :hour]) and window(:t, from: [24, :hour], to: [1, :hour]) are disjoint and contiguous. An absent to closes the window at now itself, inclusively, so window(:t, from: [15, :minute]) is the last fifteen minutes up to now and holds the newest reading — there is a natural newest instant and a window with no neighbour above it has no reason to exclude it. An absent from is genuinely open at the old end, there being no natural oldest instant. Four windows of decreasing span therefore partition a column exactly, which is what a design showing one signal at four scales needs. now is Visualize.Chart.apply/2's :now option when it is given, else the newest reading of field over the rows entering the step — a live dashboard means the wall clock and a test means the data's own end, and only the caller knows which, so it is an option rather than something derived. A reading that is not temporal, or a unit that is not one of the six, raises ArgumentError naming the step, as :bin's faults do. Readings compare as §4.3 compares a :time domain: DateTime, Date and NaiveDateTime by their module, an ISO 8601 string as Visualize.Data.Table.temporal?/1 reads it, a number as seconds.

  A :window step and a frame's viewport node (§12.5) are different things and the names are close enough to be worth separating: this selects rows by their reading before a mark draws them, and a viewport is a streaming window over pixels that decides what a tick redraws. A design may use either, or both, and neither reads the other.

• :lttb — fields required ([x, y], the two columns a line reads); n required (:integer, or :plot; :geometry). Shape-preserving downsampling (#448) by Largest-Triangle-Three-Buckets, Visualize.Data.lttb/3 over the rows with the accessor reading {x, y} from the two columns: the first row, the last, and n − 2 rows between that keep the line's visual area — the right default for a line beyond the thousand points SVG draws well (spec/01 §2). n: :plot binds to the frame's geometry: the plot area's width in pixels, ceil of it, read from the pipeline's size: (§5.4's context, the same plot area a layout defaults to), so lttb(from(:hr), [:t, :bpm], :plot) says "one point per pixel of this plot" without a number and follows the plot when the container is resized. Input of n or fewer rows is returned unchanged; an n below 3 — a line needs its two ends and one point between to have a shape — raises ArgumentError as the step's fault, as :take's negative n does. Gaps pass through: a row whose x or y reads nil is a gap, the rows reduce run by run between the gaps, and each run of gap rows keeps its first row in place, so the line's defined/2 still breaks the path where the input broke (spec/08 §5.2 gives the per-run budget). An x reads as a number or as a time — a DateTime, NaiveDateTime, Date or ISO 8601 string, in seconds, as :window reads one — and a y as a number; any other reading raises ArgumentError naming the step. Whole rows are kept, every column of each, so a tooltip over a kept point reads the datum itself. O(n) in the rows, pure Elixir (spec/08 §5.2 says why there is no Nx path).

• :m4 — fields required ([x, y]); width required (:integer, or :plot; :geometry). Per pixel column the first, last, minimum and maximum rows (#448), Visualize.Data.m4/3 over the rows as :lttb reads them, deduplicated and in input order. width: :plot binds to the plot area's width as n: :plot does, and is what a design means nearly always; an integer is for a design reduced for a size it knows. A width below 1 raises ArgumentError as the step's fault. The columns split the extent of the defined x readings, which is the x scale's when its domain is inferred and not nice (§4.3) and nothing but the readings of the reduced series feeds it — a constant channel of another mark in the frame widens it past them (§10.1, #490) — then the reduced line draws the same pixels as the unreduced one: every column it crosses, with the same top, bottom, entry and exit, so a peak is never lost; it is the right choice where one must not be, an alert threshold or a heart-rate maximum. Under a nice or explicit x domain the columns are the data's, not the plot's, and a column may straddle two pixels — still at most four rows per column and every column's extreme kept. Gaps, readings, faults, whole rows and the cost are :lttb's.

• :bin — field required; thresholds (10) and as (:count). Visualize.Data.bin/2 over the column with nils dropped, one row per bin: x0, x1, y0 (0, so a histogram's channels read the rows alone), as (the bin's count) and values.

• :stack — fields required (the series keys); order (:none), offset (:none). Visualize.Shape.Stack with the keys, the order and the offset (:inside_out is its :insideout; :appearance orders the keys by the index of each series' greatest value, d3's stackOrderAppearance, before a :none stack; {:keys, [k, …]} is the stack's own fixed order, the listed keys bottom first and the keys it does not list above them in fields order, a listed key that is not in fields ignored — spec/04 §8.4, #492). Every order but {:keys, …} is computed from the rows the step is given, so over an animated or streaming source it is computed afresh each tick and a layer can change places between frames; a design whose layers must hold their places — a streamgraph a reader follows over time — fixes them with {:keys, …}, computing the order once from whatever data it chooses. One row per series in key order, per datum in data order: the datum's columns plus key, series (the series' stacking position), value, y0 and y1.

• :fold — fields required; as ([:key, :value]). Wide columns to long rows (#237): one output row per input row per listed column the row has — a listed column the rows lack is skipped, never a fault, which is how a design says "these, if they exist", and a row's nil in a folded column yields no row for it — the row's other columns carried unchanged, the folded column's name under the first name of as and its value under the second. Input rows in order, and within a row the columns in the order fields lists them, so the series order is the author's. A fields that is a variable resolves at application like any list (§7.1), so a host or the variables panel chooses the set. The validator holds fields to names alone — not to the source's fields, since a missing one is not a fault; the source declares the columns every row has ([:hour], checked at binding, §7.3) and the fold lists the ones a row may — and, as after any step, does not check a channel against the folded rows (a step's columns are known at run time); a channel that reads a folded column after the fold reads nil, as §5.4 says of any column the rows lack.

• :sum — field required; by and as (:sum). One row per distinct by value in order of first appearance, %{by => value, as => sum} with nils ignored; without by, one row %{as => sum}.

• :sort — field required; order (:ascending, or :descending). The rows stably sorted by the column under Enum.sort_by/3's ordering.

• :spectrum — field required (the sample column); time (the time column, nil), every (the seconds between samples, nil), samples (the window, a power of two, nil), window (:hann), detrend (false), as ([:frequency, :magnitude]). A time series to its frequency spectrum by FFT (#375, spec/08 §9): the sample interval is every when given, else the median gap of the time column — DateTimes in seconds, numbers as they are — and 1 when neither is given; the newest samples rows (the largest power of two not above the row count when not given) with a numeric reading of field — their mean subtracted first when detrend is true, so an offset does not leak from the DC line into the bins beside it (#376) — are tapered, transformed and read as samples / 2 rows, each the two names of as for the line's frequency and magnitude, and a third name when as gives one for its phase. Fewer than two numeric samples yield no rows. A samples that is not a power of two, or a window not one of Visualize.Data.FFT.windows/0, raises ArgumentError as the step's fault, as :bin's do.

5.4.2 Hierarchies

:tree, :cluster, :pack, :partition and :treemap read the rows as a flat node list: id (:id) names each node and by (:parent) its parent, nil or "" for the root, through Visualize.Layout.Hierarchy.stratify/2; field names the value Visualize.Layout.Hierarchy.sum/2 adds up (nil as 0), and without it Visualize.Layout.Hierarchy.count/1 counts leaves. size ([width, height], default the plot area) and padding (0) reach the layout's own setters, tile (:squarify) the treemap's. The hierarchies of 06-layouts §2–5 lay out the tree exactly as a direct call would.

• output: :nodes (the default) — one row per node in pre-order (Visualize.Layout.Hierarchy.descendants/1): the datum's columns plus depth, height, value and the layout's own fields — x, y for :tree and :cluster; x, y, r for :pack; x0, y0, x1, y1 for :partition and :treemap.
• output: :links (:tree, :cluster and :pack) — one row per parent–child pair in the order of Visualize.Layout.Hierarchy.links/1: source and target (the ids), x0, y0 (the parent's position), x1, y1 (the child's) and path, a Visualize.IR.Path — for :tree and :cluster the link of orientation (:vertical): vertical is M x0,y0 C x0,ym x1,ym x1,y1 with ym the mid-height, horizontal the same curve with the axes swapped, M y0,x0 C ym,x0 ym,x1 y1,x1, so size: [height, width] with orientation: :horizontal is the tree spec/10 §3.2 draws; the rows' x, y, x0, y0, x1 and y1 stay the layout's own in either orientation (D-70). link (:curve) is the path's shape (#127): :curve the cubic above; :elbow the dendrogram's step, across at the parent's depth and then down to the child — vertical M x0,y0 H x1 V y1, horizontal M y0,x0 V x1 H y1 — so the branches of one parent leave it as one line; :line the straight segment. For :pack the path is the straight line between the centres.

5.4.3 Graphs

:chord, :sankey and :force read the rows as flows: fields: [source, target] required, field the flow's value (1 when absent for :force, required by the other two). The nodes are the distinct ids over every source and then every target, in order of first appearance — or, with nodes (#346, D-110), the rows of the source it names: a graph is two tables, and the second is the nodes. The node source's id column (the step's id key, :id by default) keys them; a node row the layout yields is that row's columns with the layout's own — id, its position, index, depth — over them, so a mark's style reads fill: {:field, :group} and its label {:field, :name} from the node table; the node order is the source's; a flow whose source or target the table lacks raises ArgumentError naming the id; a node the flows never mention is laid out as an isolated node. The validator holds nodes to a declared source as it holds a mark's data, and Visualize.Chart.Frame.new/2 reads the source from the same binding a mark's data is bound from (§7.3), so an unbound node source is the unbound-source fault. size ([width, height]) defaults to the plot area; every position and path is in its pixels.

• :chord — padding (0) is the pad angle in radians. The flows fill the square matrix of Visualize.Layout.Chord.generate/2 (a repeated pair adds up); with R = min(width, height) / 2 of size (default the plot area) and the centre the pipeline's centre: — the point an :arc mark is about (§5.6), the plot's middle, or the origin of a :polar frame's centred group. size sets the radius, never the centre (#488): the ring and the ribbons of one design are about the same point however each step is sized, so a ribbon's ends at 0.9 R lie on an :arc mark's ring of inner radius 0.9 R at the group's own angles, and a design cannot misalign them by passing a size. output: :groups (the default) yields one row per group in index order — index, id, start_angle, end_angle, value and path, the annulus sector between 0.9 R and R as Visualize.Shape.Arc draws it, translated to the centre — and output: :chords one row per chord in row-major order: source, target (the ids), source_value, target_value and path, the ribbon at 0.9 R of Visualize.Layout.Chord.ribbon_path/2 as a Visualize.IR.Path (the source arc, a quadratic curve through the centre to the target arc's start, the target arc, a quadratic curve back, Z), translated to the centre.

• :sankey — padding (8) is the node gap; the node width is 24. Visualize.Layout.Sankey.compute/3 over the nodes and the flows; output: :nodes (the default) yields one row per node in input order with id, index, depth, height, layer, value, x0, x1, y0, y1; output: :links one row per flow in input order with source, target, value, width, x0 (the source node's right edge), y0, x1 (the target node's left edge), y1 and path, the ribbon of Visualize.Layout.Sankey.generate_link_path/1 as a Visualize.IR.Path.

• :force — Visualize.Layout.Force.run/1 over the nodes and the flows with the forces [{:center, x: width / 2, y: height / 2}, {:many_body, strength: strength}, {:link, distance: distance}] — strength (-30) and distance (30) the step's own keys (#346) — and its default 300 iterations from alpha 1: a pure function of the input, so a design renders the same graph twice. A node whose row in the node source has a numeric x and y starts there, as d3 honours a node's given position (#527); every other node starts at Force.run/1's own initial position (spec/06 §8.1). output: :nodes (the default) yields one row per node with id, x, y; output: :links one row per flow with source, target, x0, y0, x1, y1 and path, the straight line.

  A realised frame runs each :force step once (#527, D-132). Visualize.Chart.Frame.new/2 lays out every distinct :force step of its marks before it infers a domain, and every pipeline that reaches such a step during that realisation — domain inference, the render target's count (§12.3), each mark that draws it — reads that one layout. Two steps are the same run when their nodes are equal apart from output and their input is equal: the same size, the same nodes in the same order with the same seeded positions, and the same flows. So a graph drawn as a :path mark over output: :links and a :circle mark over the nodes is one simulation, and a link's endpoints are its nodes' positions in every frame. A step whose input differs — a mark whose rows a transition has moved (§12.5), a facet's panel — runs on its own, cold, as before.

  In a compiled chart the layout is warm (#527, D-132). Visualize.Chart.render/2, Visualize.Chart.Frame.render/2 and every realisation without carried state are cold, as above. A compiled chart (§12.5) keeps, per :force step, the last layout it drew — each node's x, y, vx and vy by its id — and each tick's realisation starts from it: the known nodes at their carried positions and velocities, the simulation reheated to the step's alpha (0.3) and run for at most its ticks (3) iterations at d3's own decay, alpha_decay = 1 - 0.001^(1 / 300). Three iterations a tick at the gallery's 20 ticks a second is 60 a second, d3's own pace of one per animation frame; thirty a tick moved a node of the gallery's graph by up to 78 px between ticks while the graph first swelled from its cold layout, which no reheat can avoid — a cold layout is frozen as alpha decays, not settled. A change to the step's forces — the gallery's breathing distance — therefore moves the graph from where it stood toward the new equilibrium rather than relaxing a fresh graph to whichever equilibrium it falls into, which is what d3's alphaTarget/restart idiom does. A node new to the graph starts at the mean of its laid-out linked neighbours, or of every laid-out node when it has none, offset by its spiral position of spec/06 §8.1, so it neither lands on a neighbour nor pulls the centre force across the whole graph; a seeded position, when its row has one, wins over both. A node that has gone is forgotten. alpha and ticks are how lively the motion is, the designer's intent with defaults: set wrong the graph is visibly sluggish or jumpy, never wrong.

5.4.4 Geo algorithms

:delaunay, :voronoi, :density and :hexbin read pixel coordinates from fields: [x, y] (required); a nil coordinate drops the datum. They run after a :projection step, or a :force, or over columns already in pixels, and never through a scale.

• :projection — the projection is the frame's (projection: of Visualize.Chart.Transform.apply/3), and a pipeline without one raises ArgumentError. With fields: [longitude, latitude] each row is a point: it gains x and y from Visualize.Geo.Projection.project/3, and a point the projection clips keeps its row with x and y both nil. With field (#349) each row holds a GeoJSON geometry or feature under that column — a map as Visualize.Geo.Path reads it (spec/07 §2.1), %{"type" => "Sphere"} included — and gains path, the projected outline as a Visualize.IR.Path from Visualize.Geo.Path.path/2, and x, y, its centroid from Visualize.Geo.Path.centroid/2; a row whose geometry projects to nothing keeps its row with path, x and y all nil. A clip hides a row; it does not drop it (#522, D-130). Clipping is the view's, not the data's, so every row the step is given reaches domain inference (§4.3) whatever the viewpoint: a turning globe whose land is coloured through an inferred :ordinal domain keeps each land mass's colour, and a bubble map's size domain does not depend on what is in view. The marks draw nothing for a clipped row, since a nil reading places nothing (§5.2): a per-datum mark drops the datum, a :path mark draws no element for a nil path, a :line or an :area breaks its path there, and :delaunay, :voronoi, :density and :hexbin drop the point. Only bad data is dropped: a row whose longitude or latitude is missing or not a number, or whose geometry is not a map. One of the two keys is required and the validator reports a step with neither as fields :required; a step with both is reported as field {:invalid_for, :projection}. Clipping is the projection's own (spec/07 §1.5, §2.2.1): the orthographic drops the far hemisphere, its paths cut at the horizon and closed along it, so a globe's land never closes by a chord across the disc; and a path under a projection without a clip angle is cut at the antimeridian of the rotated frame and closed along the map's edge, so a rotated pseudo-cylindrical map draws no ring the long way round; a design draws no clipPath.
• :delaunay — Visualize.Geo.Delaunay.new/1 over the points. output: :triangles (the default) yields one row per triangle in construction order: index, vertices (the three point indices, counter-clockwise) and path, the closed triangle; output: :hull one row, path, the closed hull (an empty path for fewer than three points).
• :voronoi — Visualize.Geo.Voronoi.new/1 over the points, bounded by [0, 0, width, height]. output: :cells (the default) yields one row per point in input order: the datum's columns plus index and path, the closed clipped cell (Visualize.Geo.Voronoi.cell/2; an empty path for a site without a cell); output: :edges one row per finite edge: x0, y0, x1, y1 and path.
• :contour — field required, read from every row in row-major order over the grid size: [columns, rows] (required); thresholds (10). Visualize.Contour.compute/2 with smoothing on; one row per ring — a polygon of a threshold's MultiPolygon — in threshold order: value and path, the ring closed with Z, its grid coordinates scaled so that the grid's columns − 1 by rows − 1 cells span the plot area.
• :density — field (the weight, 1 when absent), size (default the plot area), bandwidth (20), thresholds (20); the cell size is 4. Visualize.Contour.Density.compute/2; one row per ring in threshold order, value and path, the ring closed, in pixels.
• :hexbin (#348) — radius (20), the hexagon's circumradius in pixels. Visualize.Layout.Hexbin.bin/2 over the points (spec/06 §9); output: :cells (the default) yields one row per non-empty cell in lattice order — x, y (the centre), count and path, the closed hexagon of Visualize.Layout.Hexbin.hexagon/3 — so a :path mark with fill: {:field, :count} through a :sequential color scale is the density; output: :points yields the input rows in order, each with its cell's x, y and count under cx, cy and count.

5.5 Inline label

Implemented. A :mark_label node labels the mark from its own data: text (:text, :content, required), anchor ({:enum, [:top, :bottom, :left, :right, :start, :middle, :end, :x0, :x1, :y0, :y1, :outward, :inward]}, :geometry, :top), style ({:ref, :style}, :style, :label), dx, dy and dr (:number, :geometry, 0), rotate ({:one_of, [:number, {:enum, [:tangent, :radial]}]}, :geometry, nil), fit ({:enum, [:none, :truncate, :hide]}, :geometry, :none); every key :override. A {:field, f} in its text reads the datum through Visualize.Data.Table.get/2 — to_string/1 of the value, nothing for nil — which is how a rule labels itself with the deploy's sha.

Visualize.Chart.Mark.generate/3 draws the label as one text element per datum — per series for a :line or an :area, at its last point — in the label's style with class="mark-label", dx and dy added. Each mark type has an anchor point (px, py): the datum's position for a :symbol, a :circle and the end of a :line or an :area; the centre of the rectangle for a :rect and a :band; Visualize.Shape.Arc.centroid/2 about the plot centre for an :arc — over the pie's angles, or the datum's own start and end — and a :rose; the first point of the path for a :path. The anchor names where the text sits:

The two polar anchors (#137) place the label along the ray from the plot's centre through the anchor point — a sector's from its rim, the outer radius outward or the inner inward, any other mark's from its own point — 4 plus dr beyond it, rather than along an axis, so a label leaves the sector it belongs to on the sector's own spoke: :outward on a :rose at dr: 15 sits at R + 19 on the sector's ray, R its outer radius. The centre is the group's origin for a centred mark (a :rose, an :arc, §5.6) or in a :polar frame, and the plot's middle otherwise. The text_anchor follows the side: :start right of the centre, :end left of it, :middle on the vertical. rotate turns the text about its own position: a number is degrees, rotate(deg, x, y); :tangent and :radial are computed per datum from the anchor point's angle about the centre — :radial along the ray, :tangent across it — with the half-turn flip that keeps the text upright on the left (radial) or the lower (tangent) half, the flip every hand-written ring label does and the reason it is written once here; a radial label anchors :start on the right and, flipped, :end on the left, so it runs toward the centre and ends at the point; a tangent label anchors :middle. A text_anchor in the label's style replaces both. The same rotate on a frame :label (§6.1) turns it about its own position, :tangent and :radial about the plot's middle.

A ring's outer labels stay inside the plot (#489). An :outward label leaves its ring along the spoke and, :radial, runs on away from the centre — from its point on the right, flipped on the left to end at it — so its far end is R + 4 + dr + t from the centre, R the ring's outer radius and t the text's width. Nothing in the mark knows where the plot ends, and it cannot move a label inward without laying it over the ring it names: the ring's radius is the design's. A design that labels a ring outside it therefore sizes the ring from the plot and its longest label: R = min(w, h) / 2 − (4 + dr + t + 4), w and h the plot area, t the estimated width Visualize.Chart.Text.width/2 gives the longest label at the label's font size, and the last 4 the inset every corner label keeps from the plot's edge (§6.3). The bound holds on every spoke, the worst being one along an axis, where the text's far end is R + 4 + dr + t out and its height lies across the edge. The estimate is the one fit and the legend use, and the inset is what absorbs a wide glyph the estimate misses — a capital W or O in a proportional face. The gallery's Radial bar and Chord diagram size their rings this way (Examples.Charts.Design.ring_radius/4), and the suite holds them to it by measurement: every ring label's drawn bounding box, as resvg lays it out in DejaVu Sans, lies inside the plot.

The four edge anchors are for the rectangular types, a :rect and a :band, whose elements carry their bounds: a bar labels itself past its own end, whatever its length, with no second mark. On any other type they fall back to the cartesian anchor of the same side — :x0 to :left, :x1 to :right, :y1 to :top, :y0 to :bottom — so the anchor list stays total.

A label fitted to its element (#138). fit is what happens when the text is wider than the element it labels: :none (the default) draws it as it is; :truncate cuts it to the characters that fit and ends a cut label with …, drawing nothing when not even one character fits; :hide draws nothing for an element the whole text does not fit and the text as it is otherwise. The width is the element's own, per type — the width of a :rect's or a :band's bounds, a :circle's diameter, and for an :arc or a :rose the arc's length at the label's own radius, the sector's angle times the distance from the label's point to the centre — and a type with no extent (a :symbol, a :line's end, a :text) fits everything. The text's width is estimated as the legend's is (§4.5): 0.6 × the label's font size per character, the font size the label's style resolves to — Visualize.Chart.Text.width/2, width(text, font_size), the one estimate the library makes of a text's width, public so a design can size itself by it (below). It is an estimate — a design cannot measure a glyph — and is stated as one; a label the estimate keeps may still overrun a narrow glyph's neighbour by a pixel. A rectangle's height must hold its label too (#497): a label on a :rect or a :band at any anchor but the four edge anchors sits on the element, so a fit other than :none draws nothing for an element shorter than the label's font size — a thin or zero-area cell has no room for a line of text, which would otherwise spill over its neighbours in an ink chosen for a fill it is not on. A label at an edge anchor sits outside its element and is fitted by width alone, as is every other type's. The pie, the sunburst and the treemap components print their mark's labels as the layer fits them (§15.3, §15.4, #494, #497); until #497 the treemap component drew its labels itself, by its own rule of seven pixels a character and its own thresholds.

A :rule and an :x_band label themselves through their generator's own label/2 — to the right of the upper end, spec/04 §12.2 — so the annotation is byte for byte the text the generator draws; anchor, dx and dy are not read by those two types, and the label's style reaches the generator's text. A text_anchor in the label's style replaces the anchor's own. The mark lifts that text out of the generator's per-datum group into its labels group (below), where every other type's labels are.

A label is not drawn in its mark's style (#485). A mark's style is its elements' — the paint, the stroke and its width, the opacities, the effects — and a label reads only its own style. So the labels are not inside the group that carries the mark's style but beside it (§5.6): a slice's white separator, a cell's outline or a node's series stroke no longer outlines every glyph of the label over it, which smeared or erased light text on dark fills and thickened dark text on light ones; a fill_opacity or an opacity on the mark no longer fades its labels. A deliberate halo is the label's style's: a label style that sets stroke (and stroke_width) draws its text outlined in it, exactly as it says. What a label style leaves unset is inherited from the frame, never from the mark. A :text mark is its label and is drawn in its own style (§5.2).

A label's ink can follow its element (#486, D-123). A :colour key of the label's style — its fill, and a halo's stroke alike — that is :contrast (§3.2) is resolved per label against the colour under it, the fill of the element the label belongs to, as that element is drawn: the element's own fill once its bindings are read (a {:field, f} through the frame's color scale, §3.4), else the mark's group's — the style's fill, or the series paint of a filled type (§5.6). That colour is taken as a literal: a CSS reference by its fallback (var(--vis-series-2, #d9730d) is #d9730d), a paint {:paint, name} by its first stop's colour, as a canvas draws it (§3.2), a slot through Visualize.Theme.resolve/3 in :literal. A translucent fill is composited over the theme's background first — its fill_opacity times its opacity, the element's own else the mark style's, each 1 when absent, mixed channel by channel in sRGB — since that is the colour the text is read against. An element with no fill (:none, a stroked type's path, a :rule), a colour Visualize.Color.parse/1 does not read, and a label with no element — a :text mark's, a :rule's or an :x_band's generator text — have nothing under them, and their :contrast is the theme background's ink, as everywhere else. The ink is then Visualize.Theme.ink(theme, colour) (spec/08 §7.3) and replaces :contrast in the label's resolved style as a literal, in both modes. A label that overhangs its element is still inked against its element: fit (above) is what keeps a label inside the element it is inked for, which is why a design that writes :contrast on a filled mark's label normally sets a fit too.

5.6 Rendering

Implemented. Visualize.Chart.Mark.generate/3 is one mark as one Visualize.IR.Element group in the plot area's coordinates, its rows those of Visualize.Chart.Mark.rows/3 (the bound source through the pipeline of §5.4; [] when the source is not bound, so a mark renders empty rather than raising), its channels mapped as §5.2 says through Visualize.Chart.Frame.scales/1, its style resolved as §3.4 says in the :resolve mode:

group  style: %{class: "mark mark-<type>[ <class>]", …the resolved style}   — attrs: %{"data-node" => "marks[i]"} when the frame draws with paths: true (§4.7)
└── <element>   one per datum, or one per series for a :line and an :area (§5.2)

A mark with an inline label (§5.5) — any type but :text, which is its label — is drawn as a wrapper holding two sibling groups, so its labels are not inside the group that carries its style (#485):

group  style: %{class: "mark mark-<type>[ <class>]"}        — data-node, the tooltip's attributes and the centring transform, as above
├── group  style: %{class: "mark-elements", …the resolved style}
│   └── <element>   one per datum, or one per series, as above
└── group  style: %{class: "mark-labels"}                    — no style of its own: nothing to inherit from
    └── text  style: %{class: "mark-label", …the label's style}   — the inline label (§5.5)

The wrapper is the mark: it carries the class, data-node (§4.7), data-tooltip-template and data-tooltip-event (§5.7) and the translation of a centred mark, so every attribute the hooks read is where it was (spec/10 §12, D-75) — a datum's element is still a descendant of .mark, a click on a label still finds the mark's data-node as its nearest, and the tooltip's template is still an ancestor of every element. The elements' group carries the resolved style and the paint, which reach the elements as they did; the labels' group carries no style, so a label is drawn in its own style alone. A mark whose design has no label is the one group, byte for byte as before. Whether a mark is wrapped is the design's to say, not the data's: a labelled mark with no rows is still the wrapper, with two empty groups.

With a tooltip node (§5.7) the mark's group — the wrapper, for a labelled mark — also carries data-tooltip-template and data-tooltip-event when the node gives them, and every element the mark draws carries the datum attributes of spec/10 §12.2 through Visualize.IR.Element.datum/2 — a per-datum element its own datum's fields, a per-series path (:line, :area) and the paths of a :percentile_band the first row's of their series, so {series} names the line under the pointer.

Every element a series draws carries data-series (D-77, D-126). The value is to_string/1 of its series value, the string the legend's entries carry (§4.5). A mark with a series channel (§5.2) stamps it on:

• every element it draws. For a :line or an :area that is the series' path, and the line-fill area under a filled line. For every other type it is the datum's own element, with the series read from that datum. For a :rule, an :x_band or a :needle that element is the per-datum group, so the attribute covers the line, rectangle or pointer inside it;
• the second element of an :outside or a :double stroke style, which copies the first;
• every inline label (§5.5) drawn for that element. This includes the label a :rule or an :x_band generator drew and the mark lifted into its labels group, and the text a :text mark draws.

A row whose series reading is nil names no series, and its elements carry no data-series. A mark without the channel carries none. This is the whole contract LegendHook reads: it hides .mark [data-series="<value>"], so an element of the series that lacked the attribute would stay drawn when its legend entry is toggled off (#508).

The elements are the generators' own, so a mark is byte for byte the direct call with the same numbers (D-61):

| :rect | one rect per datum: x = min(x0, x1), width = |x1 − x0|, likewise y and height; rx and ry when corner_radius is positive | | :circle | one circle per datum at (x, y) with r the value or radius |

A mark's paint is the colour its elements are drawn in: the style's fill for a filled type (area, band, x_band, rose, symbol, arc, path, rect, circle, the bands of a percentile_band) and its stroke for a stroked one (line, rule, the median of a percentile_band). When the style gives no value for that key, the paint is the theme's {:series, i} for the mark's one-based position among the design's marks (§3.3), set on the group as that key, and a :line also takes fill: :none. A filled line is the area under it: a :line whose style gives a fill other than :none draws, beneath each series' path, one more path — the area from the line down to the baseline, the y scale's zero clamped to its range, exactly as an :area's y0 defaults (§5.2), in the same curve, class="line-fill", stroke: :none, its fill the group's — and the line's own path takes fill: :none, so the fill is the volume under the plot and never the polygon SVG would close between the curve's ends. A fill_opacity reaches the area as it reaches any fill. The generators of a :rule and an :x_band draw in current_color and the brush's fill, which a group's style does not reach, so the stroke keys of the resolved style and the paint are set on the rule's line and the fill keys and the paint on the x-band's rectangle. With a series channel, on any type, each element a series draws takes the series' colour as its paint key. That colour is the frame's color scale's value for the series value when the frame declares the scale. It is resolved exactly as the legend resolves it, a slot atom through Visualize.Theme.resolve/3, and a series value the domain lacks takes the scale's unknown (§4.3). Without the scale it is {:series, j}, where j is the series' one-based position among the mark's series values in order of first appearance (#508, D-126). The series' colour is the element's own value, so it is drawn over the group's paint. Anything more specific than the series wins over it: a paint key the element already sets, such as a line-fill's stroke: :none, a :rect's value fill or a :text mark's label fill, and a {:field, f} binding of that key. On a :rule or an :x_band the series' colour replaces the paint that is set on the rule's line or the band's rectangle. A :rect's value reaches the colour scale the same way, as the element's fill. A {:field, f} on any style key is bound per element (§3.4): a colour key whose reading is missing is :none on the element, so a mark element with no paint draws no paint on every backend — fill="none" in the SVG, no fill() on a canvas (D-122). Every slot resolves in the :resolve mode, so the SVG carries var(--vis-series-1, #3b6fa8) and a canvas the literal; on a canvas the same tree renders through Visualize.Backend.Canvas with literal paints, an inline label as fillText, and nothing for a text on the binary stream (spec/09 §4).

The stroke style (stroke_style, §3.1) says how a mark's stroke sits on its edge, and the mark draws it — it is not an element key, so Visualize.Chart.Style.resolve/3 drops it and Visualize.Chart.Mark.generate/3 reads it from the style node once its elements are bound:

Inside and outside belong to a closed mark — area, band, x_band, rose, symbol, arc, path, rect, circle — where "in" and "out" of the edge mean something; on an open mark (line, rule, percentile_band) they draw as :single, and the validator says nothing, since a style stacks onto marks of any type through a name. :double draws on every type. The width is the style's stroke_width, 1 when it gives none; the second element of an outside or a double stroke carries the same datum attributes as the first, so a tooltip reads either. How a clip reaches each backend is spec/02 §2.1 and spec/09 §2.3, §3.3.

The group is returned untranslated. Visualize.Chart.Frame.generate/2 places every mark of the design after the grid, inside the group the margins translate — inside the centred group of a :polar frame, inside each panel of a :facet frame from the rows whose by is the panel's value — when it is given sources:, and draws the furniture alone without them (§4.7). A :rose and an :arc mark are about the plot centre in every kind, so generate/3 translates their group there in a frame that is not polar; a :chord step's paths are about the same point, the pipeline's centre: (§5.4.3), so they need no translation of their own. A %Visualize.Chart.Var{} reached while drawing raises ArgumentError naming it, as the frame does.

5.7 Tooltip

Implemented. A :tooltip node asks the mark to carry each datum's fields on its elements, for TooltipHook of spec/10 §12 to show under the pointer with no round trip (D-75):

fields names the columns written, in that order, each read from the datum through Visualize.Data.Table.get/2; [] writes every column of the datum in Enum.sort/1 order of its keys. The datum is the row the element was drawn from — after the mark's transforms, so a :stack row's key, y0 and y1 are fields a tooltip can name (§5.4). A field named in fields is checked against the source's declared fields when the mark reads the source directly, as a channel is (§5.4). template is the data-tooltip-template of the group — {field} placeholders, spec/10 §12.2 — and event its data-tooltip-event, the name a click pushes. The node changes nothing the mark draws: only attributes are added (§5.6), so a design without one renders byte for byte as before.

6. Labels

6.1 Keys

Implemented as schema. A :label node is a text of the frame — a title, a caption, an axis title — rather than of a datum.

frame is the frame the label belongs to (#383), on the same rule as a mark's (§5.1): required when the design has more than one, the single frame's when it has one. A label's {:axis, s} and {:data, [x, y]} anchors read its own frame's scales.

rotate turns the text about its own position — degrees, or :tangent/:radial about the plot's middle with the upright flip — as a mark label's does (§5.5, #137); it composes with an axis title's own rotation.

{:axis, s} anchors the label as the title of the axis drawn for scale s; s is a scale reference and is checked as one. {:frame, c} anchors it at a corner of the plot area, or at its centre for :center, and {:data, [x, y]} at a point of the data (§6.3).

id is the label's identity in a stack (§8.2), read exactly as a mark's is: a higher layer's label with the same id replaces this one in place. A label without one appends. Nothing renders from it.

6.2 Text

Implemented. A text is a list, never a parsed string: ["Uptime — ", var(:unit)], ["deploy ", {:field, :sha}]. Strings are literal, a variable resolves at application, a field reference reads the datum (inline labels) or is an error (frame labels, which have no datum: {:invalid_for, :label}). A "{{unit}}" string form MAY be added later as sugar that compiles to the list.

6.3 Placement

Implemented. The frame draws each label as one text element in its style, class="label", at the anchor's position; dx and dy are added to it. With w and h the plot area and m the margin:

The centre is a frame anchor (#489). {:frame, :center} is the middle of the plot area in every kind of frame, which in a :polar frame is the origin its centred group is translated to (§4.6) — [0, 0] inside that group, the point a centred mark is drawn about (§5.6), and the point a centred mark's polar anchors and rotations are about (§5.5) — so a text in a donut's hole or under a radial bar's average sits at the centre whatever the r scale's range. {:data, [0, 0]} is not that point: it maps radius zero through r, which is the centre only when r's range starts at zero; a radial bar whose r range is [50, R], to keep a hole, put its "centre" text 50 up the first spoke. Like a data anchor it has no baseline of its own — the point is the text's baseline, so two lines stack by their dy — and no outward direction; its text_anchor is :middle, since a centred text is centred.

Position (§3.1). Each placement above has a baseline — the dy in its row, or none — and an outward direction: away from the plot for a title, a subtitle (up), a caption and a bottom axis title (down), a top axis title (up), a left or a right axis title (further from the plot, which in the rotated frame is −y); into the plot for a corner, so {:frame, :top_left} runs (+x, +y) and {:frame, :bottom_right} (−x, −y); none for a data anchor or the centre. The label's style says how the text sits on that point: vertical_align replaces the baseline — :baseline no dy, :middle "0.32em", :top "0.71em" (the text hangs below its point), :bottom "-0.25em" — and leaves the placement's own when absent; margin_x and margin_y move the point along the outward direction, each by its sign, so a caption with margin_y: 6 sits 6 further down and a corner label 6 further in; text_angle rotates the text about the point it sits on, a rotate(angle, x, y) added after any transform the placement has, so a left axis title turns about its own point in its rotated frame. A label's dx and dy are added as before, the signed one-off nudge; the margins are what a named style sets for every label it reaches. The same four keys reach a mark's inline label (§5.5) — outward is the label's anchor: :top up, :bottom down, :left left, :right right, :start right, :end left, :middle nowhere — and text_angle alone reaches an axis's tick labels through the axis's style (§4.4), each turned about its own anchor, which is how a category axis with long names angles them; a legend's entries take none of the four.

An axis title follows the side of the first axis that names its scale; with no axis on the scale, x is taken as :bottom, y as :left, and any other name as :bottom. A data anchor maps [x, y] through the scales named x and y in a :cartesian or :facet frame (the first panel), through angle and r in a :polar frame — (R sin a, −R cos a) from the centre — and through the projection in a :geo frame, where the pair is [longitude, latitude] and a point the projection clips is not drawn. A text_anchor in the label's style replaces the anchor's own.

7. Variables and slots

7.1 Variables

Implemented. Visualize.Chart.var/1 builds %Visualize.Chart.Var{name: name}, a term allowed wherever a value can appear — a style value, a channel, a whole node (style: var(:style), margin: var(:margin)) — and, inside a text, as #{var(:name)}. The term carries only the name; the default is declared once under vars (§2.4), so two fragments cannot disagree about it (D-59). The validator requires every variable used to be declared ({:undeclared, :var, name}) and does not type the value, which is unknown until application: the value is typed by the validator at the path where the variable stood, once Visualize.Chart.apply/2 has put it there (§7.3). Resolution is single level: the value a variable takes at application MUST NOT itself be a variable, and one that is is {:var_binding, name} at every path where the variable stood (§7.3, §10.1). A variable nested inside a value another variable is bound to is not resolved either, and needs no rule of its own — the vars declarations are dropped before validation, so the validator finds it as {:undeclared, :var, name} at its path; only the direct case was silent.

A text interpolates. A :text is one string — "Uptime for #{var(:host)} over 24h" — in which #{var(:name)} stands for a variable and #{field(:name)} for the datum's field a mark's label reads (§5.5); \#{ is a literal #{. Visualize.Chart.Text.parse/1 reads it into parts and Visualize.Chart.Text.unparse/1 writes parts back, the two inverse, so a text is one value whichever form holds it: its variables stand at the key (labels[0].text, never labels[0].text[1]), each named once however many holes name it, and application writes the bound value into the string as to_string/1 gives it. A hole that names neither var nor field, or a #{ never closed, is {:template, reason} at the key. The list-of-parts form an earlier draft wrote is read wherever a text is read and is written back as the string (§9), so no document goes stale and no second form survives a round trip.

A text has lines. A newline in a text breaks it: "Uptime\n24 h" is two lines, and so is a text whose variable resolves to a string with a newline in it, since the split is of the resolved parts. Every text the frame draws — a frame label (§6.3), a mark's inline label (§5.5), an axis title, a legend title — draws its lines as one text element holding one tspan per line, each at the text's x and the first at its y, the rest each line_height em below the last (§3.1); a text of one line is drawn as it was, a text with its content and no tspan, so nothing changes for a text that has no newline. Visualize.Chart.Frame.generate/2 does it in one pass over its tree once the labels are placed, so no placement has to know about lines; a canvas draws one fillText per line, stepping by line_height × font_size (spec/09 §3.3). The lines are left-, centre- or right-aligned together by the text's text_anchor, since each tspan restarts at x.

7.2 Sources as slots

Implemented. A source declaration is a slot: the fields the design reads are the contract, and binding maps slot to source at application — "made for {a, b, c} but showing {d, e, f}" is one rebinding, Visualize.Chart.apply/2 with another sources: map. Application takes a pool of named sources; a slot binds to the pool's entry under its own name, else under its default, and a slot with neither is unbound (§7.3). A dashboard picker validates a candidate source against fields before offering it, by the rule application applies: every declared field is a key of some row of the source, in either spelling (D-52).

7.3 Application

Implemented (work item 5 of #53, D-65). Visualize.Chart.apply/2 takes a design — a %Visualize.Chart{}, or a design map that goes through Visualize.Chart.from_map/1 first, so an invalid map is its errors — and the options sources: (the pool, a map from name to source, %{}), vars: (a map from variable name to value, %{}), theme: (a %Visualize.Theme{}, as Visualize.Chart.Frame.new/2 takes it), size: (the host's container as {width, height}, {600, 400} by default, §4.2) and now: (the instant a :window step measures its durations back from, §5.4.1; absent, each such step takes the newest reading of its own column), and returns {:ok, applied} or {:error, errors} — the errors of §10.1 by path, ordered by path — in three steps. Each step reports every fault it finds and a step with faults stops before the next, so resolution faults are never mixed with binding faults, nor either with the validator's.

1. Variables resolve. Every %Visualize.Chart.Var{} in the design — a value, a text part, a whole node — is replaced by the value vars: gives its name, else by the declared default (§2.4); a variable with neither is {:unresolved, :var, name} at the path of its use, and every use is reported; a variable whose value — from vars: or from its own declared default — is itself a %Visualize.Chart.Var{} is {:var_binding, name} at every path where it stood, since resolution is single level (§7.1) and a second pass would let a stored design bind a variable to a variable and never settle. A name in vars: that no declaration carries is {:undeclared, :var, name} at [:vars, name]. In a text a resolved part that is a number or an atom is written with to_string/1, so ["n = ", var(:n)] with n: 3 reads ["n = ", "3"]; every other value stands as it is, where the validator types it. The vars declarations are dropped: the concrete chart has none and no variable anywhere in it, which is what Visualize.Chart.Frame.new/2 requires (§4.7).
2. Slots bind. Each slot of sources (§2.3) binds to the pool's entry under its own name, else under its default; a slot with neither is {:unbound, :source, name} at [:sources, name]. Pool entries that no slot names are ignored, so one pool serves many designs. A bound source is anything Visualize.Data.Table.rows/1 reads and is kept as given — the frame reads it through rows/1 as it does any source, and a rank-1 Nx tensor stays a tensor for the dense path (D-52). Every field the slot declares MUST be a key of some row of the bound source, in either spelling; a field no row carries is {:missing_field, field} at [:sources, name], one error per field, which is the "made for {a, b, c}" contract failing loudly (§7.2). A source with no rows binds without a check. A field a channel, a text or a transform reads is checked against the slot's declaration by the validator (§5.4), so a field the design reads and the source lacks is caught at one or the other.
3. The result validates and its frame is realised. Visualize.Chart.Validator.validate/1 runs over the resolved, bound design — the value a variable took is typed here, at the path where it stood — and Visualize.Chart.Frame.new/2 builds the frame over the bound sources, inferring every :auto domain from the bound columns (§4.3). A value a scale cannot take, or a theme name theme: does not resolve, raises ArgumentError from the frame as it does for any chart: those are faults of the data or the consumer, not of the binding.

The result is a %Visualize.Chart.Applied{} (§14.10): chart, the concrete %Visualize.Chart{} — no variable anywhere in it, vars empty, the slot declarations kept as the data contract, everything else as the design wrote it; sources, the bound sources by slot name; and frame, the realised frame, whose Visualize.Chart.Frame.scales/1 is the escape hatch. Visualize.Chart.render/2 draws it: Visualize.Chart.Frame.render/2 of the frame over the bound sources, with the same options. The design, its fragments and a binding are storable; the applied chart holds data and is not — it has no map form and no JSON form.

8. Composition and the stack

Implemented. Two operations close over fragments, and both are total in the sense that matters: their result is a fragment, so a stored composition is a part of another composition and a stored stack is a layer of another stack. Visualize.Chart.compose/2 is the union — it assembles one design from disjoint parts and reports a name two fragments declare differently as a fault. Visualize.Chart.stack/2 is the cascade — it layers a house theme, a shared frame and a panel's own overrides, and a name two layers declare differently is the higher layer's word. Neither validates nor defaults: the result becomes a chart through Visualize.Chart.from_map/1 or Visualize.Chart.apply/2, which is where it MUST validate.

8.1 compose/2: the union

Implemented (work item 5 of #53, D-65). Visualize.Chart.compose/2 merges two fragments — design maps, or %Visualize.Chart{}s taken as their maps — into one map by the merge rule of every key (§1.5), the second over the first, and returns {:ok, map} or {:error, errors}; Visualize.Chart.compose/1 folds a list left to right, so compose([a, b, c]) is compose(b, c) over compose(a, b), and compose([]) is {:ok, %{}}. A fragment is any map with the design's keys: it need not carry version or frames, and nothing is validated or defaulted — the result is a fragment too, and becomes a chart through Visualize.Chart.from_map/1 or Visualize.Chart.apply/2, which is where it MUST validate.

For each key present in either fragment, by the key's spec in the node kind being merged:

• :concat — the later fragment's elements after the earlier's: marks, labels, axes, transforms. Elements are never merged with each other. A key either fragment gives as a struct is not a list, so there is nothing to append and the later fragment's value is taken whole (§1.4); a variable at a :concat key is not a disagreement, because a collection has no names for two fragments to claim.
• :union — the union of the two name-keyed maps: sources, vars, styles, scales. A name in both with equal values is taken once; with different values it is :conflict at the name's path ([:styles, :series], [:frames, :main, :scales, :x]), every conflict reported. A house style sheet composes with a chart's own styles and disagrees loudly, never silently. A key either fragment gives as a struct — styles: var(:sheet), the documented way to leave a whole node to application (§1.4, §7.1) — carries no names to unite, so it is read as one value: equal in both fragments it is taken once, and different it is :conflict at the key's own path ([:styles], [:frames, :main, :scales]) with the later fragment's value in the result. A variable at a :union key says this whole declaration is somebody else's, and a fragment that also declares part of it is the disagreement compose/2 exists to report (D-92).
• :deep — frames (§1.5): the union of the two maps, and a frame both fragments declare merges as a node, key by key under the frame's rules. A frame is assembled from fragments — cartesian/1 says its kind, scale/3 a scale, axis/3 an axis (§16) — so two fragments naming the same frame are parts of one frame and not a disagreement; a frame each names alone is taken as it is.
• :override — the later fragment's value, except that a key whose type is a node — {:node, kind}, or a {:one_of, …} that admits one, such as theme — given as a map by both fragments composes key by key under that kind's rules: a frame merges, its scales union, its axes concatenate, its kind is the later's; meta merges likewise. A key the schema does not know is :override.

A key present in one fragment alone is taken as it is. Over a list, :concat and :union keys compose associatively and :override keys last-wins, so the order of the fragments is the order of their marks and labels and the precedence of their scalars: a standard label set, a house style sheet and a chart-specific fragment compose in that order into one design.

8.2 stack/1: the cascade

Implemented (#97, D-81). Visualize.Chart.stack/2 merges two fragments as a cascade: for every key the higher layer wins. Visualize.Chart.stack/1 folds a list left to right, the later layer the higher, so stack([a, b, c]) is stack(stack(a, b), c); stack([]) is %{} and stack([a]) is a itself. A layer is a design map or a %Visualize.Chart{} taken as its map, exactly as a fragment of compose/2 is, or a {name, layer} pair whose name stack/1 ignores and Visualize.Chart.explain/1 reports (§17.1), so the two functions take the same list.

The cascade cannot fail — there is no disagreement for it to report, since a disagreement is what it exists to resolve — so stack/1 and stack/2 return the fragment itself and not an {:ok, fragment} tuple. That is the second difference from compose/2 (§8.3) and it is what makes stack([a]) == a an equality rather than a comparison of wrappers.

For each key present in either layer, by the key's spec in the node kind being merged:

• :concat — a higher element whose identity equals a lower element's replaces it in place, keeping the lower's position; every other higher element follows the lower's, as compose/2 appends them. Identity is what lets a layer restyle the shared frame's x-axis rather than draw a second one, and it is defined below.
• :union — the union of the two name-keyed maps; a name both layers declare is the higher layer's entry, where compose/2 reports :conflict. The entry is taken whole: a style the higher layer redeclares replaces the lower's rather than merging into it, so the result is a style some layer actually wrote. Derivation within a style is extends (§3.5), which is the key-by-key operation on styles and is unrelated to the cascade. A key either layer gives as a struct carries no names to unite (§1.4), so it is the higher layer's value whole, exactly as the :override rule below reads it — the cascade resolves the disagreement compose/2 reports (D-92).
• :override — the higher layer's value, except that a key whose type is a node — {:node, kind}, or a {:one_of, …} that admits one — given as a map by both layers cascades key by key under that kind's rules, exactly as compose/2 recurses: a panel fragment's frame adds its own scales and axes to the shared frame's and takes precedence on the frame's scalars. A node either layer gives as anything else — a name, a variable — is the higher layer's value whole. A key the schema does not know is :override.

Element identity (#98, D-82) is what a :concat key's elements are matched by:

An element with no identity appends, so a stack of layers that name nothing behaves exactly as the append of §8.1 and the identity rule costs a design that does not use it nothing. Identity matches only within one key — a mark and a label with the same id are different elements — and nothing renders from an id or from an axis's identity: they are the algebra's names for elements, and the SVG carries neither (D-77 is what names a series in the document).

The schema does not require an id to be unique — a fragment is not a whole design, and uniqueness is only meaningful once the layers are known — so where the cascade merges two lists it reads the lower's elements and the higher's as one sequence and collapses duplicates in both: each identity keeps its first position and its last value. A key only one layer carries is passed through untouched, as every rule of the cascade passes such a key through, so a fragment that is never stacked is never rewritten.

A matched element is replaced whole, not merged key by key, for the reason the :union rule is: a mark's meaning is its whole node, and a higher %{id: :series, type: :area} merged over a lower :line would keep the line's channels under the area's type and draw something no layer wrote. A layer that wants to change one key of a mark writes the mark.

The result of that is that the stacked list is ordered by each identity's first appearance across the layers and carries its last value, whichever way the layers are grouped, which is why the cascade stays associative over :concat keys.

A key present in one layer alone is taken as it is. :concat, :union and :override keys all cascade associatively where every layer gives a mergeable key as a map — a :union key as a name map, a node key as a node — which is every layer that declares anything at them. So a stack is a list of layers in precedence order and the fold over it may be built in parts: a house sheet stacked with a frame is a layer of the panel's stack.

The exception is a layer that gives a mergeable key as a struct — a whole-node variable (§1.4). That layer is replacing the declaration rather than merging into it, and a replacement in the middle of a stack is not recoverable by regrouping: stack([a, b, c]) is the left fold, which is what Visualize.Chart.stack/1 computes and what Visualize.Chart.explain/1 reports, while stack(a, stack(b, c)) may differ where b replaces a key a declares and c declares it again. Carrying the erasure through the regrouping would mean an intermediate result that is not a fragment, which §8.2 exists to rule out. This is the price of admitting a whole-node value at a key whose rule is to merge, and it is the second reason compose/2 reports the same pair as a :conflict (§8.1) instead of resolving it (D-92).

8.3 Why there are two operations

Implemented. The two are not one operation with a flag, and neither is the other's default.

compose/2 assembles one design from parts that are meant to be disjoint — a standard label set, a source list, the fragments a builder function returns (§16) — and a name declared twice there is a mistake: two authors believing they own :series produce a design neither of them wrote, silently, and the :conflict is the whole value of the operation. stack/1 layers designs that are meant to overlap — a house theme, a shared frame, a panel's overrides, a dashboard's per-panel edits — and a name declared twice there is the point: the higher layer is saying what it is for.

They agree exactly where the fragments are disjoint. Over two fragments that declare no :union or :deep name and no :override key in common, stack(a, b) is the map of compose(a, b), which is the property that holds the two definitions together as the schema's merge rules grow.

9. Version and migration

Implemented. version is required and is the integer Visualize.Chart.Migration.current/0, which is 2. Visualize.Chart.from_map/1 calls Visualize.Chart.Migration.migrate/1 before validation: a design at the current version passes through unchanged; one at an older version is stepped forward one version at a time through the migration registered for each step, so a stored design never goes stale; a version above the current one, or that is not an integer, is {:error, [{[:version], reason}]} with {:unsupported_version, v} or :required. Version 2 is the first step (#383): a design holds its frames by name, so a version 1 design's singular frame becomes frames: %{main: …} and the size such a frame may still carry is dropped, the render giving one now (§2.1, §4.1, §4.2, #427). A stored version 1 design therefore keeps working — it is migrated where it is read, which is why this is a migration and not a breaking change. That holds for a design read from JSON too (§11): the codec types a key by the current schema, so a key only an earlier version had is typed by the shape it had there (Visualize.Chart.Migration.legacy_type/2) and the migration then moves it; otherwise a v1 frame's values would stay strings and the migrated design would not validate (#479). The name main is the migration's word: a design that says nothing about names has one frame, and every path the builder and the validator print is frames.main.… for it. Within a version, migrate/1 also returns the design in the shape this library writes (Visualize.Chart.Migration.canonical/1): a :text given as a list of parts becomes its string form (§7.1), which is a canonicalisation and not a version step, since the two forms are one value and both read. Every migration MUST be pure and MUST produce a map that validates at its target version.

10. Validation

10.1 Error shape

Implemented. Visualize.Chart.Validator.validate/1 takes a map and returns :ok or {:error, errors} with every fault found, not the first: each error is {path, reason} (Visualize.Chart.Validator.error/0). The path is the list of keys and list indexes from the design to the faulty value — [:marks, 1, :channels, :y], [:styles, :series, :stroke], [:frames, :main, :axes, 0, :scale], [:version] — and [] is the design itself. Errors are ordered by path, as a reader would walk the map.

The last four are reported by Visualize.Chart.apply/2 and Visualize.Chart.compose/2 in the same shape, so one reader serves every error of the layer. Visualize.Chart.Validator.format/1 renders one error as a line a person reads, marks[1].channels.y: field :temp is not declared by the mark's source, sources.primary: has no field :v.

10.2 Checks

Implemented. For every node, in this order: unknown keys; required keys; the type of every present value, recursing into nodes, lists and maps; enumerations; then references. A reference is resolved against the design being validated — the node's own frame's scales for :scale (a mark's or a label's is the frame it names, §5.1; a frame's own parts are its own, §4.3), frames for :frame, styles and the built-in names for :style, sources for :source, vars for :var, the mark's source's fields for :field, the theme's slots for :slot — so a design is self-contained or it does not validate. A %Visualize.Chart.Var{} in any position is accepted after its declaration is checked, and nothing under it is examined.

11. JSON

11.1 Encoding

Implemented. Visualize.Chart.to_json/1 and Visualize.Chart.from_json/1 are the map round-trip over a JSON document, behind the optional Jason dependency: mix.exs declares {:jason, "~> 1.4", optional: true}, Visualize.Chart declares @compile {:no_warn_undefined, Jason} (D-50), and without Jason both return {:error, {:missing_dependency, :jason}} while everything else works. scripts/consumer_check.exs asserts that Jason is absent from a bare consumer. The encoding is schema-driven: keys are strings, a :name, :field, :slot or enumerated atom is its string, and from_json/1 reads each string back as the atom the schema says it is. A design is authored, not data — its names are the author's vocabulary — so decoding creates the atoms a design names; a consumer that loads designs from an untrusted source bounds them itself.

11.2 Tagged terms

Implemented. Terms JSON has no form for are objects with one $-prefixed key, and nothing else in a design starts a key with $:

Everything else — numbers, strings, booleans, lists, maps — is its JSON self. from_json(to_json(chart)) is chart for every valid chart.

12. Compilation

12.1 The compiled chart

Implemented (work item 6 of #53, D-66). Visualize.Chart.compile/2 compiles a design the way HEEx compiles a template: the design is validated once, the theme and the styles are resolved, everything data-independent is drawn once, and the result is a %Visualize.Chart.Compiled{} per frame, each with one closure per dynamic region taking the realised frame and the bound sources. Rendering a compiled chart per tick pays no validation and no static drawing.

compile/2 takes a %Visualize.Chart.Applied{} (§7.3), or a %Visualize.Chart{} or a design map, which go through Visualize.Chart.apply/2 first with the same sources:, vars: and theme: options — so a compiled chart is always compiled over a binding, the one the render targets are chosen from (§12.3) — and returns {:ok, %{name => compiled}}, one compiled chart per frame (#385), or the {:error, errors} of application. A design of one frame is a map of one, so a caller has one shape to read whatever the design holds. Its one option of its own is ceiling:, the point-count ceiling of §12.3, a positive integer, 1000 by default. The struct holds chart, the concrete %Visualize.Chart{} restricted to this frame — its frames the one frame, its marks and labels the ones that say it (§5.1) — so everything below this point reads one frame and never asks which; theme, its %Visualize.Theme{}; regions, every region of §12.2 in the frame's drawing order, each static with its element drawn once or dynamic with its closure and its reason; targets, the target and the bound point count of every mark in that frame's order (§12.3); ceiling; static, the static SVG string of §12.4, rendered once; plot, margin and size as the frame gives them — size the render's, which is the design's box; box, this frame's own pixel box %{x, y, width, height} within it (§4.2), which is where a page puts this plot's canvas; domains, the extents this frame was realised with rather than inferring — a scale adopted from another frame (§4.3), whose rows are not in this compiled chart to be re-read — which every tick's realisation is given; viewport, nil or the window state of §12.5; and forces, the warm force layouts of §12.5 (#527, D-132), %{} for a design with no :force step. A compiled chart is a value: recompile on a design change, not on a data change; one compiled chart serves every tick of one binding, and a slot rebound to another source is another compilation. It holds closures and data, so it has no map or JSON form, as the applied chart has none (§14.10); a macro or sigil that runs the compiler on a literal design at compile time is not built here and would need a data form of the regions.

A compiled chart is one plot, and a design has one per frame (#385). The regions, the render targets and the incremental window are per plot (spec/09 §5.3, D-106, D-107) and stay so: what a frame adds is that a design holds several of them. Each frame compiles over its own realised frame (Applied.frames) and the marks and labels that say it, so nothing inside the compiler asks how many frames there are: the region, transition and window modules read the one frame their restricted chart holds. A frame's static (§12.4) is a page-ready document at the design's size with that frame's group translated by its box and its margins, so the documents of a design's frames stack — each is transparent where it draws nothing — and a design of one frame at the box [0, 0, 1, 1] renders byte for byte what it always did.

A tick is per frame too: tick/3, step/3, svg/2, static/1 and render/2 each take one compiled chart and answer for one plot. A caller with several frames maps over them and is given one payload per frame, which is what lets a page put one <canvas> per plot at its own box with its own ack and scroll contract (spec/09 §5.3) rather than one canvas for a design.

12.2 Regions: the static/dynamic split

Implemented. The split is computed from the design, never assumed. The frame's drawing order (§4.7) is a list of regions, and each region is static — drawn once at compilation, byte for byte the same on every tick — or dynamic, drawn per tick by its closure:

A scale is fixed when its domain is an extent with no :auto in it and it is not the frame's viewport scale (§12.5); it moves when its domain is inferred (:auto, or :auto at one end, §4.3) or windowed. The order of the regions is the order the frame draws in: :grid, the marks — the :tiles marks first (§5.2) — the axes, :legend, :labels in a :cartesian or a :geo frame; in a :polar frame the grid, the marks and the axes on angle and r sit in the centred group and the outer grid and an axis on another scale follow it (§4.6); a :facet frame is :panels, :legend, :labels. A region that would hold nothing — a grid no axis asks for, a legend or labels the design has none of — is not listed. Visualize.Chart.Compiled.regions/1 reports every region as {region, :static} or {region, {:dynamic, reason}}, and Visualize.Chart.Compiled.dynamic_regions/1 the dynamic ones alone as {region, reason}. The reason is :data for a mark (a fitted :tiles mark's included), :facet for the panels, and {:inferred, names} for a region that reads moving scales — the names of those scales, sorted — so an author reading {:grid, {:inferred, [:y]}} and {{:axis, 1}, {:inferred, [:y]}} sees exactly which domain to fix to make the diff smaller.

A static region is drawn at compilation in the :css mode from the frame the chart was compiled over; since it reads no moving scale, the frame of any tick draws it the same. A dynamic region's closure takes the frame realised over the tick's sources — Visualize.Chart.Frame.new/2 runs per tick, which is where the moving domains are inferred — and draws the region as §4 and §5 do: a mark through Visualize.Chart.Mark.generate/3 at its position, an axis and the grid through the frame's furniture, the legend and the labels likewise. The static elements are cached on the struct as Visualize.IR.Elements, and test/visualize/chart/compiled_test.exs holds the static bytes identical across data changes and the assembled output of §12.4 equal to Visualize.Chart.Frame.render/2 for every design under test/support/designs/.

12.3 The render target

Implemented. The render target is a compiler decision per mark, never a design property beyond the render override (§5.1). For each mark, in design order: render: :svg, :canvas or :binary is taken as given; :auto (the default) counts the rows the mark draws over the bound sources — a :text mark is :svg whatever render says, since it draws text alone and the binary stream carries none (spec/09 §4.4, #134), and a :tiles mark is {:svg, 0}, since it draws images and text and no rows (§5.2) — — Visualize.Chart.Mark.rows/3, the points of a path mark, the elements of a per-datum one, a row a :projection clips counted with the rest (D-130), so a turning map keeps its target — and picks :svg when the count is at most the ceiling, else :binary when Visualize.Backend.CanvasBinary.available?/0 (Nx is loaded) and :canvas otherwise. The ceiling is the ceiling: option of compile/2, 1000 by default: the ~1,000 DOM-node ceiling of 00-prior-art §3.2. Rebinding a slot to a denser source and recompiling moves a mark from SVG to canvas without touching the design. Visualize.Chart.Compiled.targets/1 reports {target, points} per mark, the target chosen and the count it was chosen from, so [{:svg, 120}, {:binary, 5000}] is a chart whose second mark went to the binary path.

Static furniture is always SVG. Layering is fixed — the backdrop layer under the canvas layer under the SVG layer, and mark order within each layer — and text stays in the SVG layer: a canvas-layer mark's inline label (§5.5) is drawn as SVG text in the mark's group — the wrapper and its labels group, without the elements' group, so the label is in its own style on the SVG layer as on SVG (§5.6), while the canvas layer draws the wrapper and its elements' group and drops the labels group with its text — since the canvas has no text a stylesheet or a DOM hit can reach (spec/09 §4.4). The backdrop layer (#476, D-120) holds what must sit beneath the data whatever its target: a :tiles mark's images, which are SVG <image> elements in a document of their own. A :tiles mark's region is therefore drawn in two layers: its images in the backdrop, its attribution — text, which must be read over the data — in the SVG layer, in the mark's group with its images removed. Each part is static or dynamic with the region (§12.2): drawn once at compilation, unless the frame's projection is fitted. Nothing else is in the backdrop: every other mark is the data and goes to the canvas or the SVG layer by its target, and the maps' ocean, a :path mark under the projection, is data the design orders as it likes. The marks of a :facet frame are drawn per panel inside the :panels region and stay in the SVG layer whatever their count: their target is reported as :svg. One node of style resolves for both layers (§3.4): the SVG layer in :css, the canvas layer in :literal.

12.4 Rendering per tick: the hybrid chart map

Implemented. Visualize.Chart.Compiled.render/2 takes the compiled chart and the sources by slot name — the map Visualize.Chart.Applied holds, anything Visualize.Data.Table.rows/1 reads under each name; a slot the map omits draws nothing, and nothing is re-validated — realises the frame over them, runs every dynamic closure, and returns the chart map of Visualize.Backend.Hybrid (spec/09 §6) with one key added for the SVG layer's moving part:

The static and dynamic_svg lists hold a :tiles mark's group with its attribution alone; its images are in backdrop. Visualize.Backend.Hybrid.render/1 reads none of the three added keys: a consumer of the compiled chart stacks them itself, as below.

Visualize.Chart.Compiled.static/1 is the static SVG string, Visualize.Backend.Hybrid.render_static/1 of the static list, rendered once at compilation and cached. Visualize.Chart.Compiled.backdrop/1 is the static backdrop (#476): the static regions' backdrop elements as one SVG root of the same shape, rendered once at compilation and cached, "" when there are none. Visualize.Chart.Compiled.tick/3 is the per-tick payload: {payload, compiled} where payload is a map with svg, the dynamic_svg list rendered as one SVG root of the same shape as static/1; backdrop, the dynamic regions' backdrop elements — a fitted :tiles mark's images — as one SVG root of that shape, "" when there are none; canvas, Visualize.Backend.Hybrid.render_dynamic/1 of the map, "" when there is no canvas layer; canvas_format; incremental, the payload of §12.5 or nil; and bytes, the byte size of what a tick transmits — svg and backdrop plus canvas, or plus the incremental payload's binary — which is what the measurement of §12.6 reads.

The page stacks five documents (#476, D-120), each positioned at the container's origin, each transparent where it draws nothing, bottom to top: the static backdrop (backdrop/1), the tick's backdrop (payload.backdrop), the canvas, the static SVG (static/1) and the tick's SVG (payload.svg). The canvas clears to transparent (spec/10 §8.2), so the backdrop shows through wherever the data does not draw; the SVG layers take no pointer events where a hook on the canvas needs them, as before. A page that omits the backdrop draws no tiles and nothing else is lost, since the backdrop holds nothing but a basemap's images. For a design of several frames (§12.1) the order holds layer by layer: every frame's backdrop beneath every canvas, as every static document is over them. The returned compiled chart holds the tick's sources and the window state; a design without a viewport returns it otherwise unchanged.

Visualize.Chart.Compiled.svg/2 is the one-string form: the frame's group of §4.7 assembled from the cached static elements — the defs first — and the tick's dynamic ones in the frame's own order — the grid, the marks, the axes, the legend, the labels — rendered through Visualize.Render.to_string/2 as SVG. A region's elements are built as the frame builds them: a mark's group through Visualize.Chart.Mark.generate/3 with its paints resolved for the mode and its texts' lines split (§4.7), so a compiled mark is the frame's mark (#356). When every mark targets :svg it is byte for byte Visualize.Chart.Frame.render/2 over the same sources, which is how the split is held to the frame; a canvas-layer mark is absent from it, since it is the SVG layer.

12.5 The viewport: a streaming window

Implemented. A frame viewport (§4.6) — scale, a {:ref, :scale}, and span, a number in the scale's domain units, seconds for a :time scale — makes the compiled chart stateful: the named scale is windowed to [hi − span, hi] on every tick, where hi is the newest value the marks bind to it over the tick's sources — the greatest value of every channel naming the scale, as inference reads them (§4.3) — or the now: option of tick/3, which is how a clock, or a test's fake clock, drives the window. The windowed scale moves (§12.2): its axis and grid are dynamic regions. A mark that reads the windowed scale draws the rows whose reading lies within the window, so nothing is drawn beyond the plot area; the reading is the channel's field before the mark's transforms, and a mark whose channel is a transform's output draws every row its pipeline yields.

When the chart has a binary canvas layer (canvas_format :binary_base64, §12.4 — the incremental record of spec/09 §5.5 carries binary streams and nothing else; a :json layer is sent whole per tick), the window slides it through Visualize.Incremental (spec/09 §7), whose state the compiled chart holds between ticks: the first tick is the full-redraw payload of Visualize.Incremental.initial_render/1; each later tick scrolls by dx = (hi − hi₀) × width / span pixels, with width the plot's, through Visualize.Incremental.scroll/2, so the payload is the canvas_incremental event of spec/09 §7.3 — "scroll_x" with the exposed strip filled, "full" when the window jumped by half the plot or more, "none" when it did not move. The incremental canvas is the plot area: its size is plot, it sits at (margin.left, margin.top) of the container, and the marks are drawn in plot coordinates — the exposed strip is at the canvas's edge (spec/09 §5.3), and only a canvas whose right edge is the plot's right edge exposes the newest points there. Into each exposed region the compiled chart draws the rows under the strip and three neighbours each side (#332, D-108): the region's x and x + width in plot pixels are mapped back through the windowed scale to a range of the scale's units, each canvas mark's source is restricted to the rows whose reading lies within it, widened by the three rows before and the three after (the compiled chart's window module, strip/6, a private helper), and the mark is built over those — a path enters and leaves the strip on its own line, since a :monotone_x curve reads one neighbour each side and a :basis curve two, and the client's clip to the region's bounds (spec/10 §9.2) removes the overhang. The full redraw draws the whole window. A scroll payload is therefore the strip's — a few kilobytes against a full redraw's hundred — which is the saving the incremental path exists for; the compiled chart once drew the whole window into every strip, so a scroll cost what a full redraw cost and saved the client's redraw alone. What the window keeps between ticks is the scroll's position and the canvas's, never a tick's own rendering (#406): the state the compiled chart stores carries no build_element and no data — both are the tick's, given afresh each time — so its size is constant however long a run lasts. It had kept the tick's closure, which captured the compiled chart, whose window held the tick before's closure: a chain a link longer every frame, invisible in one process and fatal across two, since the state is copied into the render task per frame. A strip's render time doubled — 13 ms, 32, 75, 186, 385, 812, 1,388, 2,850 — until the run skipped every tick and read 1 FPS. A scroll tick never builds the whole window (#404). The canvas layer of a viewport design with a binary layer is built only where it is used: Visualize.Chart.Compiled.tick/3 draws the canvas-layer marks' SVG part alone — their inline labels — and hands the compiled chart's window module a function for the whole window's geometry, which the scroll calls in the one branch that needs it, the full-redraw payload (the first tick, or a jump the incremental machinery turns into one). A scroll tick therefore builds the strip and nothing else. The tick had built every mark over the whole window in literal style and passed it along to be discarded on every scroll, so a scroll cost a redraw and saved only its bytes — 25 ms a frame at 2,961 rows against 0.8 ms for the same tick over 40. The strip's rows are selected in one pass besides, and that pass keeps only what it returns (#410): the source is folded once, holding the three rows before the strip, the rows within it and the three after — nothing is built for the rest of the window — while noting whether the readings arrived ordered, as a streaming source's do; a source that did not arrive ordered is collected and sorted as before, and answers the same rows. Selecting a strip out of a 22,201-row window cost 6.0 ms when every row of the window became a tuple to be indexed and sliced. The state's data is empty and its accessors are never consulted: the builder receives the region as clip_region and reads the rows itself. The copy-and-shift holds only while the windowed scale is a translation of its units and every other scale the canvas marks read is fixed (#416), since the scroll moves every pixel already drawn by one dx, which is right only when sliding the window moves every reading by the same number of pixels. With an inferred scale beside the window the old pixels are wrong once its domain moves; with a windowed scale that is not a translation no single dx is right — a :log window over [100, 1000] slid to [120, 1020] on 740 px moves a reading at 200 by 46.1 px, one at 500 by 23.8 and one at 900 by 9.4, where a linear window moves each by 16.4 — and a strip stitched onto them joins a stretched picture. Either way every tick is a full-redraw payload, dynamic_regions/1 names the scale (the inferred one to fix, or the windowed one), and the window module is never asked for a strip. The condition is derived, never declared: a viewport has no option to say it scrolls, since an author who had to set it would get it wrong in exactly the cases that matter. Its current consequence is an allowlist of the kinds that are translations, [:linear, :time] — a :time scale in its own units, seconds over a plain extent — named rather than reached by exclusion, so a kind added later redraws in full until it is shown to be one; :log, :power, :sqrt, :symlog and every other kind redraw in full. Since #414 a full redraw of 50,000 points is 155 ms, so a log viewport is a working chart, not a refusal. The SVG layer of a viewport design is per-tick SVG as §12.4 says, its :svg marks windowed alike.

An inferred domain eases (#360). A scale with a transition (§4.3) and a domain that moves — :auto, or :auto at one end — keeps a shown domain in the compiled chart between ticks, beside the viewport's state: on the first tick the shown domain is the inferred one; on a later tick whose inferred extent differs, the shown domain is retargeted — it eases from where it is toward the new extent over duration milliseconds along easing, each tick's frame drawn at the shown domain through the escape hatch (§4.3), so the marks, the axis and its grid agree at every intermediate frame; a domain that has not changed costs nothing and a scale with no transition jumps as before, byte for byte. The clock is tick/3's at: option, milliseconds, System.monotonic_time(:millisecond) when absent, so a test drives the easing as it drives the window. shrink_after is hysteresis: an inferred extent that lies inside the shown target is a shrink, and a shrink is taken only once every inferred extent for shrink_after milliseconds has stayed inside — a passing spike does not pump the axis — while a grow is taken at once and clears a pending shrink. Only a numeric domain eases (:linear, :log, :power, :sqrt, :symlog, :radial); a :time scale, or a fixed domain, draws its target as it is. Visualize.Chart.render/2 of an applied chart — one frame, no state — is unchanged.