# 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](10-liveview-integration.md) 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](08-utilities.md) §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. | Level | Nodes | Node kinds (§14.2) | |---|---|---| | 1 | the design | `:design` | | 2 | meta, sources, vars, theme, styles, defs, defaults, layout, interaction, frames, marks, labels | `:meta`, `:source`, `:var`, `:theme`, `:style`, `:paint`, `:defaults`, `:layout`, `:interaction`, `:frame`, `:mark`, `:label` | | 3 | size, margin, scales, axes, legend, projection, facet, viewport; a mark's data, channels, scales, offset, options, inline label, tooltip and tiles; a style's parts (§3.1); a paint's stops; a frame's, a mark's, a label's and an axis's defaults, and a container's defaults for one mark kind (§3.8) | `:size`, `:margin`, `:scale`, `:axis`, `:legend`, `:projection`, `:facet`, `:viewport`, `:data`, `:channels`, `:mark_scales`, `:mark_offset`, `:options`, `:mark_label`, `:tooltip`, `:tiles`, `:paint`, `:stroke`, `:font`, `:text_layout`, `:effect`, `:marker`, `:curve`, `:stop`, `:defaults`, `:kind_defaults` | | 4 | tick specs; an axis's measure; a projection's fit; transforms; text parts; the stops of a gradient written in a style | `:ticks`, `:measure`, `:fit`, `:transform`, `:stop`, and the `text` type of §1.4 | 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`. | Facet | Keys that | |---|---| | `:binding` | name a source, a slot, a variable, or a field of a source, or say how much of a slot to ask for: `sources`, `vars`, `budget`, `data`, `source`, `transforms`, `field`, `by` | | `:channel` | map a field onto a scale: `marks`, `channels` and every key of the channels node | | `:geometry` | fix a size, position, extent, angle, scale or tick geometry: `frames`, `box`, `kind`, `margin`, `scales`, `axes`, `side`, `ticks`, `options`, `render` | | `:style` | choose presentation: `theme`, `styles`, `style` and every key of the style grammar (§3) | | `:content` | carry text, formats and identification: `version`, `meta`, `labels`, `text`, `format`, `label` | 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 (`t:Visualize.Chart.Schema.type/0`). | Type | Accepts | |---|---| | `:integer`, `:number`, `:boolean`, `:string` | the Elixir term of that name (`:number` is an integer or a float) | | `:name` | a string naming a source, frame, scale, style, paint, variable or field; an atom given in Elixir is read as its string (§9.4, D-195) | | `{:enum, [a, b, …]}` | one of the listed atoms | | `{:list, t}` | a list whose every element is a `t` | | `{:map, t}` | a map whose keys are names and whose values are `t` | | `{:node, kind}` | a map of the node kind `kind` (§1.2), validated recursively | | `{:one_of, [t, u, …]}` | any of the listed types | | `{:ref, :scale | :style | :source | :var | :frame}` | a name declared under the frame's `scales`, or under `styles`, `sources`, `vars` or `frames` (§10.2) | | `:field` | a string 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` | | `:generator` | `{:generate, name, args}`: a call to a host's generator resolved at render (§3.13, #654), `name` an atom the registry defines for `length(args) + 1` arguments, `args` a list of `:term`s and `:field_ref`s; a style site's entry, and accepted in every `:color` position of a style | | `:extent` | `:auto`; a two-element list of numbers, `DateTime`s or `:auto`; or a list of categories (numbers, strings, atoms); a member may be a variable or a fact, typed once application replaces it (§7.4, #565) | | `:range` | a scale's range given as a list (§4.3, #710, D-185): each entry a **position** — a number, a `DateTime`, a variable or a fact — or a **color position**, a `:color` of any form that type accepts, typed colors and transforms among them. A bare atom here is canonicalized to `{:color, atom}` (§9), as in every color position: a range's entries are what the scale maps *to*, so an atom in one can only be a color. It is not the domain's `:extent`, whose atoms are categories | | `: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 | | `:budget` | a positive integer, rows; or `{:per_px, k}` with `k` a positive number, rows per pixel of plot width (§2.10, #864) | | `: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_ref`s, 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) | | `:color` | a color string, `:none`, or a **typed color** ([08-utilities](08-utilities.md) §1.9, #664, D-173): `{:color, name}` from the theme's color table — the roles `:good`, `:warning`, `:bad`, `:info` and `:neutral`, the furniture and `:series_k` among its names — `{:series, i}`, a ramp position `{:ramp, name, t}` with `name` one of the theme's four ramps and `t` a number in `0..1` (§7.5), the contrast ink `{:contrast, c}` (§3.2), or a transform of colors. A bare atom here is canonicalized to `{:color, atom}` (§9) | | `:theme_color` | a theme's color (§2.5, [08-utilities](08-utilities.md) §7.1, #667): a `:color`, or the steps a theme pins of a name, a map of integer steps in `0..1000`, 500 among them, to color strings | | `:ramp` | `{:ramp, name}` with `name` one of `:status`, `:thermal`, `:diverging`, `:sequential`: a whole ramp of the theme, which a color scale ranges over (§4.3) | | `:color_map` | a map from a category — any term — to a `:color`: an ordinal scale's range pinned category by category, the shape of a feed's `status` (§4.3, #565) | | `:size` | a number, a theme slot, or a **unit value** `{n, unit}` (§3.9; [08-utilities](08-utilities.md) §13; #651) | | `:length` | a number or a unit value, never a slot: a member of a stroke's `dash` or a text's `offset` (§3.9) | | `:font` | a string or a theme slot | | `:slot` | a slot of the design's theme: `:series_k`, `{:series, i}`, `:axis`, `:grid`, `:text`, `:background`, `:surface`, `:good`, `:warning`, `:bad`, `:info`, `:neutral`, `:font_family`, `:font_size`, `:label_size`, `:title_size` ([08-utilities](08-utilities.md) §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 license 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 name is a string in the map form** (D-195, amending D-57): a source, field, variable, frame, scale, style, paint or Use key, and every reference to one. Elixir input may spell a name as an atom — `%{frames: %{main: …}}`, `{:field, :v}`, `Visualize.Chart.var(:unit)` — and `Visualize.Chart.Migration.canonical/1` reads it as the string of the same spelling, so the map a reader returns holds `"main"`, `{:field, "v"}` and `%Var{name: "unit"}`. The library's own vocabularies stay atoms: node keys, enumerations, mark types, theme slots, units. A field's string reaches a column of either spelling: `Visualize.Data.Table.get/2` reads `"v"` from a row keyed `:v` without making an atom (D-52). ### 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: | Rule | Keys | Effect | |---|---|---| | `:concat` | every list of nodes: `marks`, `labels`, `axes`, `transforms` | the later fragment's elements follow the earlier's; the elements are never merged with each other | | `:union` | every name-keyed declaration: `sources`, `vars`, `styles`, `scales` | the union of the two maps; a name declared with equal values in both is taken once, and declared differently in both is `:conflict` at the name's path. A key either fragment gives as a struct — a whole-node variable — is not a map of names and is not united: equal in both it is taken once, different it is `:conflict` at the *key's* path (§8.1) | | `:deep` | `frames`, the only name map whose entries are assembled from fragments | the union of the two maps, and a **name both declare merges as a node** — key by key under the frame's own rules — rather than conflicting: `cartesian/1`, `axis/3`, `legend/2` and `scale/3` each declare part of one frame (§16), exactly as they did when a design had a single `frame`. A key either fragment gives as a struct is read as one value, as `:union` reads it | | `:override` | every scalar and every other node: `version`, `theme`, `kind`, `box`, `type`, `text`, … | the later fragment's value replaces the earlier's. A node given as a map by both fragments composes key by key under its own kind's rules, so a frame fragment adds its scales and axes to another's (§8); given as anything else by either — a name, a variable — it is replaced whole | ## 2. The design node ### 2.1 Keys **Implemented.** The `:design` node is the top level. `version` and `frames` are the only required keys. | Key | Type | Facet | Default | Merge | |---|---|---|---|---| | `version` | `:integer` | `:content` | required (§9) | `:override` | | `meta` | `{:node, :meta}` | `:content` | `%{}` | `:override` | | `sources` | `{:map, {:node, :source}}` | `:binding` | `%{}` | `:union` | | `vars` | `{:map, {:node, :var}}` | `:binding` | `%{}` | `:union` | | `theme` | `{:one_of, [:name, {:node, :theme}]}` | `:style` | `:default` | `:override` | | `styles` | `{:map, style entry}` — a node, a name or a list (§2.6) | `:style` | `%{}` | `:union` | | `defs` | `{:map, {:node, :paint}}` | `:style` | `%{}` | `:union` | | `defaults` | `{:node, :defaults}` | `:style` | `nil` | `:override` | | `layout` | `{:node, :layout}` | `:geometry` | `%{}` | `:override` | | `interaction` | `{:node, :interaction}` | `:binding` | `%{}` | `:override` | | `budget` | `:budget` | `:binding` | `nil` | `:override` | | `frames` | `{:map, {:node, :frame}}` | `:geometry` | required | `:deep` | | `marks` | `{:list, {:node, :mark}}` | `:channel` | `[]` | `:concat` | | `labels` | `{:list, {:node, :label}}` | `:content` | `[]` | `:concat` | ### 2.2 Meta **Implemented.** `:meta` identifies the design; nothing renders from it except through a label that quotes it. | Key | Type | Facet | Default | Merge | |---|---|---|---|---| | `name` | `:text` | `:content` | `nil` | `:override` | | `description` | `:text` | `:content` | `""` | `:override` | ### 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). | Key | Type | Facet | Default | Merge | |---|---|---|---|---| | `fields` | `{:list, :field}` | `:binding` | required | `:override` | | `types` | `{:map, {:enum, [:time, :number, :category, :text]}}` | `:binding` | `%{}` | `:override` | | `default` | `:name` | `:binding` | `nil` | `:override` | | `requires` | `{:map, {:list, {:enum, keys}}}`, `keys` the fact keys of `Visualize.Chart.Fact.keys/0`: the attributes of `Visualize.Data.Schema.attributes/0`, `:names` and `:colors` (§7.4, D-225) | `:binding` | `%{}` | `:override` | **A slot states a contract** (#552, D-136): `requires` maps a field the slot declares to the description attributes the schema of the bound feed MUST give it — `requires: %{latency: [:unit, :label]}` — and `Visualize.Chart.apply/2` checks it, with every fact the design reads of the slot, against that schema (§7.4). A name under `requires` that `fields` does not list is `{:undeclared, :field, field}` at `[:sources, name, :requires, field]`, as under `types`. **A column has a type** (#369): `types` maps a declared field to one of four — `:time` (a point in time: an instant, never a count — a signal's tick is `:number`, D-154), `: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). | Key | Type | Facet | Default | Merge | |---|---|---|---|---| | `default` | `:term` | `:binding` | `nil` (the variable MUST be supplied at application) | `:override` | ### 2.5 Theme **Implemented.** `theme` names a theme — `:default`, `:dark`, `:color_safe` or `:print` for the built-in ones of [08-utilities](08-utilities.md) §7.2, through `Visualize.Theme.builtin/1` — 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`), `ramps` (`{:map, {:list, :string}}`, a ramp name to its anchors), `colors` (`{:map, :theme_color}`, a name of the theme's color table to a color, or to a map of the steps it pins, spec/08 §1.9, §7.1, #663, #667), `styles` (a palette name to its entry — a style node, or a list of palette names and nodes, [08-utilities](08-utilities.md) §7.7 — #637, #658), `font_family` (`:string`), `font_size`, `label_size`, `title_size` (`:number`), every key `:style` and `:override`, defaults those of `Visualize.Theme.default/0`. An inline `ramps`, `colors` or `styles` names only what it changes; the rest are the default theme's (spec/08 §7.2, §7.5, §7.7). A palette entry is checked as the style node it is (§3.1, §3.2) — its slots against this theme's, a version 2 entry in the flat keys read as its parts — except that a role's `:cue` on `stroke.dash` or `marker.shape` is the role's cue (spec/08 §7.7) and `extends` is the contract's to refuse. A `roles` key, the role colors of before #663, is read as `colors` (`Visualize.Chart.Migration.canonical/1`, at every version). An inline theme whose ramps, colors or palette entries break their contracts (spec/08 §7.5, §7.7) is the fault `{:contract, message}` at `[:theme, :ramps, name]`, `[:theme, :colors, name]` or `[:theme, :styles, name]`, and application refuses it as `Visualize.Theme.new/1` does. 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), and palette names used as style references (§3.3), are checked against the theme when it is built-in or inline. A theme is also a **document of its own** (§9.3, #534, D-139): `Visualize.Chart.Theme` writes and reads a theme as this node, stamped with the schema version, so a host stores and ships one as a value. A theme kept in the builder's store is found by name (`Visualize.Chart.Builder.Store.theme/2`, §19.7), and the builder's preview resolves a design's `theme: name` that is not built-in through it, supplying the `theme:` option of application from the library. ### 2.6 Styles **Implemented** (lists: #658, D-172). `styles` declares named styles (§3). A mark, axis, legend or label references one by name through its `style` key; no other node carries a color, a font or a curve. An entry is a style node, **a name** (another style, under this one's name), or **a list** of names and nodes that stacks into one style left to right by the merge rule (§3.5), so a design names a composition once: `styles: %{bad_bold: [:bad, :bold], alert: :bad}`. The entry's type is `{:one_of, [{:node, :style}, {:ref, :style}, {:list, {:one_of, [{:ref, :style}, {:node, :style}]}}]}`; a field entry (§3.6) is a site's, since a named style has no datum of its own. ### 2.7 Defs **Implemented** (#133, D-172). `defs` declares the design's **paints**: named `:paint` nodes (§3.1) a `fill` or a `stroke` draws as `%{type: :paint, name: name}`, written short as `{:paint, name}` (§3.2). A paint under `defs` is a gradient or a hatch (§3.1), written once in the words a person uses — a type, its stops, an angle or a center; a color, a pattern and a spacing — and the SVG geometry is derived; `:union` merge, like `styles`, so a house sheet of gradients composes. A style may also write a gradient in place (§3.1), which the frame holds beside these under a hash of what it draws. | Key | Type | Facet | Default | Notes | |---|---|---|---|---| | `type` | `{:enum, [:linear, :radial, :hatch]}` | `:style` | required | a paint under `defs` is a gradient or a hatch | | `stops` | `{:list, {:node, :stop}}` | `:style` | required for a gradient | at least two, in `at` order; `color: [a, b, …]` is evenly spaced stops (§3.1) | | `angle` | `:number` | `:geometry` | `180` | linear: degrees clockwise from *up*, as CSS has it — `0` runs bottom to top, `90` left to right, `180` top to bottom; range `{0, 360, 15}` | | `center` | `{:list, :number}` | `:geometry` | `[0.5, 0.5]` | radial: `[cx, cy]` as fractions of the shape's box | | `radius` | `:number` | `:geometry` | `0.5` | radial: as a fraction of the box; range `{0, 1, 0.05}` | A `:stop` node is `at` (`:number`, required, `0` to `1`), `color` (`:color`, required — a literal, a slot or a variable, resolved as any color is), and `opacity` (`:size`, default `1`, range `{0, 1, 0.05}`); every key `:style` and `:override`. A version 2 gradient's words — `kind`, `centre`, a stop's `offset` and `colour` — are read as these (§9). A paint under `defs` with no `type`, or with a `type` that is neither a gradient nor a hatch, is `:required` or `{:enum, [:linear, :radial, :hatch]}` at its `type`, and a gradient with no `stops` is `:required` at `stops`; a hatch's keys are those of §3.1. 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 centered at `center` with `radius`, its focus at the center. `Visualize.Chart.Frame.generate/2` emits one `defs` element **first** in the frame's group, before the grid, holding every gradient of the design — declared, or written in place in a style, the latter named `p` with `` the lower-case base-36 `:erlang.phash2/1` of the gradient without its opacity, **as the style that draws it resolved it** (§3.2, #711, D-186), so every in-place gradient the tree reaches through `extends`, a stack or the defaults is declared — as a `Visualize.IR.Element.linear_gradient/2` or `radial_gradient/2` with its stops, each under the id `vis-paint--` where `` is the lower-case base-36 `:erlang.phash2/1` of the frame's paints (the design's `defs` with the gradients written in place beside them), so two charts on one page collide only when their paints are the same; a design with no paints emits no `defs`. **A hatch** is a `` under the same id scheme — `patternUnits="userSpaceOnUse"`, a tile of the hatch's `spacing` on each side rotated by its `angle` (`patternTransform="rotate(angle)"`), holding a rectangle of its `background` when it has one and, centered in the tile, a horizontal line of its `width` for `:lines`, that line and a vertical one for `:crosshatch`, or a circle of radius `width` for `:dots`, all in its `color` — so a hatch written twice in place is one pattern, keyed by what it draws, as a gradient is. `Visualize.Chart.Frame.generate/2` declares a paint written in place only when the tree it draws uses it, since the theme's palette is among the styles searched and a theme whose roles are hatched (spec/08 §7.2) would otherwise put every role's pattern in every chart; a declared paint is always declared, as before. A compiled chart's static layer (§12.4) declares, beside the declared paints, every paint and filter its first draw of every mark holds. **What a later tick first draws is declared with that tick** (#652, #721, D-190): a style a datum names by a field entry, and a stack's field entry laid over another entry's gradient — a merged gradient no table holds, on whichever row first names it (D-186) — may appear on any later row, so every SVG output of a compiled chart — `step/3`'s and `svg/2`'s group, `tick/3`'s `svg`, `render/2`'s `dynamic_svg` and a re-realized frame's static layer (§12.5) — holds, directly after the compiled `defs` where it carries them and first otherwise, a second `defs` element of every paint and every effect filter its own elements use whose id the compiled `defs` lack, in id order; an output that uses none holds none, so a tick drawing only declared paints is byte for byte what it was. A compiled chart's SVG therefore never references an undeclared paint. The same `defs` holds one **filter** per distinct effect any style in the tree uses (§3.1) — its type, radius, offset and color: `` with a `feDropShadow` of `dx`, `dy` half the radius and `stdDeviation` the radius (`flood-opacity` 0.35), or `` with a `feGaussianBlur` of `stdDeviation` the radius; a design whose styles use no effect declares none. A shadow with an `offset` or a `color` (#674) is ``, `` the lower-case base-36 `:erlang.phash2/1` of `{offset, color}` as resolved, its `feDropShadow` taking `dx` and `dy` from the offset and, with a color, `flood-color` that color and `flood-opacity` 1, so the color's own alpha is the shadow's; a shadow with neither keeps the id and the filter it always had, byte for byte. The compiled defs are static furniture (§12.2): they never change with the data; what a tick adds to them is the tick's, and goes with its layer. ### 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`. | Key | Type | Default | Meaning | |---|---|---|---| | `columns` | `{:list, :number}` | `[1]` | the column widths as **weights**, normalized over their sum | | `rows` | `{:list, :number}` | `[1]` | the row heights, likewise | | `gap` | `:number` | `0` | pixels between cells, taken out of the cells and not out of the grid's outer edges | 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, #565). `interaction` says how the chart behaves on the page, alone and beside other charts: its own **brush** (below), and 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`. | Key | Type | Default | Meaning | |---|---|---|---| | `sync` | `:string` | `nil` | the group's name; `nil` joins no group | | `frame` | `{:ref, :frame}` | `nil` | the frame whose `x` scale the group reads; `nil` is the design's first frame by name, the frame `Visualize.Chart.Applied` holds as `frame` | | `brush` | `{:enum, [:x]}` | `nil` | the design's own brush (#565, D-143): `:x` brushes a window of the frame's `x` scale; `nil` leaves the brush to the page, as it always was | **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: | Attribute | Value | |---|---| | `data-vis-sync` | the group's name | | `data-vis-sync-x` | `d0,d1,x0,x1,width`: the realized `x` scale's domain, a number for `:linear` and milliseconds since the Unix epoch for `:time`; the pixels the two ends map to in the **chart's** coordinates, which is the scale's range plus the frame's box offset and left margin; and the chart's width, the `viewBox` width those pixels are in | `Visualize.Chart.Frame.sync_attrs/1` computes them from the realized 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 realized 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. **The brush is the design's too** (#565, D-143). A brush on a time chart chooses a window, and until now a host told `BrushHook` where the plot was (`data-brush-extent`, from its own margins) and turned the pixels it pushed back into instants through a scale it rebuilt to match the one the chart drew with — every host repeating the layout and the inverse the chart already has. With `brush: :x` the chart says both. The brush frame — the one `frame` names, else the first by name, the sync frame's rule — carries three attributes on its group, beside the sync group's when it has one: | Attribute | Value | |---|---| | `data-vis-brush` | `x`, the brush's kind | | `data-vis-brush-x` | `d0,d1,x0,x1,width`, the realized `x` scale exactly as `data-vis-sync-x` gives it | | `data-vis-brush-extent` | `x0,y0,x1,y1`: the frame's plot area in the chart's coordinates — its left edge the frame's box offset plus its left margin, its top the box offset plus the top margin, and its right and bottom a plot width and a plot height further — the area the brush captures and the band spans | `Visualize.Chart.Frame.brush_attrs/1` computes them, `%{}` for a frame that is not the brush frame; `Visualize.Chart.Frame.generate/2` and `Visualize.Chart.generate/2` write them where they write the sync group's, and a page drawing a compiled chart on a canvas puts them on its container as it puts the sync group's (`Visualize.Hooks.Crosshair.attrs/3`). `BrushHook` reads them from the first descendant that carries `data-vis-brush` when its own element does not give the type or the extent (spec/10 §6.5), and it pushes the window in domain units, `"domain" => [lo, hi]`, with every `brush_select` it can map — so the host's handler reads the window and knows nothing of margins. A design without `brush` writes nothing, so its markup is the same byte for byte. The brush frame is held to what a sync frame is held to, for the same reason — the hook inverts a pixel by linear interpolation: a frame that is not `:cartesian` is `{:brush, :frame_kind, kind}` and an `x` that is not `:linear` or `:time` is `{:brush, :x_scale, kind}`, both at `[:interaction, :brush]`. ### 2.10 Budget **Implemented** (#760, #864, D-226). `budget` is the design's own say in how many rows each of its slots is asked for on a board. A board derives every bound slot's budget from what the cell draws at its size — the plot width of each mark that reads the slot, and the mark's type (spec/15 §8.2) — and a design gives `budget` only to say otherwise: a chart that wants coarser or finer data than its marks' kinds imply. | Value | The slot's budget | |---|---| | `nil` (the default) | derived (spec/15 §8.2) | | `n`, a positive integer | `n` rows, for every slot of the design, whatever its width | | `{:per_px, k}`, `k` a positive number | `ceil(k × w)` rows, at least `1`, with `w` the plot width spec/15 §8.2 derives the slot's budget from: a design that follows its plot as the derivation does, at its own rate | **An override is intent, and the board's ceiling still caps it.** A design's `budget` replaces the derivation, never the board's `budget:` option, which is the ceiling every slot's budget is held under (spec/15 §8.2). Outside a board nothing reads the key: `apply/2`, `render/2` and a compiled chart draw the rows they are given, and a host that asks its own feeds reads the key itself. A `budget` that is not a positive integer or `{:per_px, k}` with a positive number `k` is `{:type, :budget}` at `[:budget]`. Its JSON is the integer, or `{"$per_px": k}` (§11.2). ## 3. The style grammar ### 3.1 Keys: a style in compound parts **Implemented** (#649, work item #657, D-172). A `:style` node holds its look in **compound parts**, each a node of its own, beside three keys that are the whole element's. Every key is `:style` and `:override`, and every one is optional with no default: an absent key is decided by the defaults the element inherits (§3.8), the theme and the mark at compilation (§12), never by the schema. ```elixir %{ extends: :warning, fill: %{type: :solid, color: :bad, opacity: 0.8}, # %{type: :linear, color: [a, b], angle: 90} evenly spaced stops # %{type: :linear, stops: [%{at: 0, color: a}, %{at: 0.8, color: b}]} # %{type: :radial, color: [a, b], center: [0.5, 0.5], radius: 0.5} # %{type: :paint, name: :fade} a paint declared under defs # %{type: :none} no paint stroke: %{type: :solid, color: :bad, opacity: 1, width: 2, dash: [4, 2], join: :round, cap: :butt, placement: :center}, font: %{family: "Inter", size: 12, weight: :bold, style: :italic, line_height: 1.2}, text: %{anchor: :middle, baseline: :middle, offset: [4, 0], angle: 0}, effect: %{type: :shadow, radius: 3}, opacity: 1, blend: :normal, marker: %{shape: :circle, size: 64}, curve: %{type: :monotone_x, tension: 0.5, alpha: 0.5}, class: "critical" } ``` | Key | Type | Notes | |---|---|---| | `extends` | `{:one_of, [{:ref, :style}, {:list, {:ref, :style}}]}` | the style this one derives from, or a list of them stacked left to right (§3.5) | | `fill` | `{:node, :paint}` | what an area is filled with (§3.2) | | `stroke` | `{:node, :stroke}` | what a line or an outline is drawn with, and the line itself | | `font` | `{:node, :font}` | a text's face | | `text` | `{:node, :text_layout}` | where a text sits on its point (§6.3, §5.5) | | `effect` | `{:node, :effect}` | a shadow or a blur | | `opacity` | `:size` | the whole element's, `0` to `1`, after fill and stroke | | `blend` | `{:enum, [:normal, :multiply, :screen, :overlay, :darken, :lighten]}` | how the element composites with what is under it; `:normal` when absent | | `marker` | `{:node, :marker}` | the symbol a mark draws at a point | | `curve` | `{:node, :curve}` | the interpolation a mark draws a path in | | `transition` | `{:node, :style_transition}` | how a change of the fill, the stroke or the opacity reaches the element's new look: over a duration, along an easing (§3.10, #653) | | `animation` | `{:node, :style_animation}` | a motion the element runs on its own while the style holds: a pulse, a blink, a shake, a spin, or the host's keyframes (§3.11, #653) | | `enter` | `{:node, :style_enter}` | how an element arrives when its row first appears: a fade, a grow, or the host's keyframes (§3.12, #653) | | `exit` | `{:node, :style_exit}` | how an element leaves when its row is gone: a fade, a shrink, an explosion, or the host's keyframes (§3.12, #653) | | `class` | `:string` | a CSS class added to the mark's element | **A paint** (`:paint`) is what an area is filled with or a line drawn with. `fill` holds one, and `stroke` holds one with its line keys after it, so `fill: :red, stroke: :blue` is a red shape with a blue outline. A declared paint under `defs` (§2.7) is the same node. | Key | Type | Default | Notes | |---|---|---|---| | `type` | `{:enum, [:none, :solid, :linear, :radial, :hatch, :paint]}` | — | which of the keys below the paint reads: `color` for `:solid`; `stops` and the geometry for `:linear` and `:radial`; `color`, `background`, `pattern`, `angle`, `spacing` and `width` for `:hatch`; `name` for `:paint`; nothing for `:none`, which is no paint. A stroke's `type` is every one but `:hatch` (below) | | `color` | `:color` | — | a solid paint's color (§3.2) | | `stops` | `{:list, {:node, :stop}}` | — | a gradient's stops, in `at` order | | `angle` | `:number` (`:geometry`) | `180` | a linear gradient's direction (§2.7); range `{0, 360, 15}` | | `center` | `{:list, :number}` (`:geometry`) | `[0.5, 0.5]` | a radial gradient's center, as fractions of the shape's box | | `radius` | `:number` (`:geometry`) | `0.5` | a radial gradient's radius, as a fraction of the box; range `{0, 1, 0.05}` | | `name` | `{:ref, :paint}` | — | the paint under `defs` a `:paint` paint draws | | `pattern` | `{:enum, [:lines, :crosshatch, :dots]}` | `:lines` | a hatch's marks: parallel lines, lines crossed at right angles, or a dot at each crossing | | `spacing` | `:size` | `6` | a hatch's period, the distance between its lines or dots, in user units or a unit value (§3.9); range `{2, 40, 1}` | | `width` | `:size` | `1` | a hatch's line width, a dot's radius; range `{0.25, 10, 0.25}` | | `background` | `:color` | — | a hatch's ground between its marks; absent, the shape shows through | | `opacity` | `:size` | — | the paint's opacity, `0` to `1` | A `:stop` is `at` (`:number`, required, `0` to `1`), `color` (`:color`, required) and `opacity` (`:size`, default `1`). **A hatch** (#652, work item #673, D-175) paints an area with lines or dots in one color, so a category or a state reads without hue — in grayscale, on paper, to a reader who cannot tell the hues apart: ```elixir import Visualize.Color, only: [color: 1] import Visualize.Units %{fill: %{type: :hatch, color: color(:bad), background: :none, pattern: :crosshatch, angle: 45, spacing: pt(4), width: pt(1)}} ``` `angle` is the direction the lines run, in degrees clockwise from horizontal, `45` when absent (the schema's `180` is a linear gradient's); `:crosshatch` adds the lines at right angles to them, and `:dots` puts a dot of radius `width` where they would cross. `spacing` and `width` are sizes of #651's units, resolved to user units when the frame resolves the paint: an absolute unit converted, an `em` against the theme's `font_size`, and a `pct`, with no box to be a share of, `{:no_box, key}`. The hatch is laid in the user space of the element it fills, from its origin, so neighboring bars hatched alike line up. Like a gradient, a hatch is written in place or declared under `defs` (§2.7) and drawn from the frame's `defs`. It is a **fill**: a stroke's `width` is the line's, so a stroke node has no hatch keys and its `type` no `:hatch` — though a stroke may name a declared hatch, `{:paint, name}`, and is then drawn with it. **A stroke** (`:stroke`) is a paint's keys and the line it draws: | Key | Type | Notes | |---|---|---| | `width` | `:size` | user units, or a unit value (§3.9); range `{0, 20, 0.5}` | | `dash` | `{:one_of, [:string, {:list, :length}]}` | the dash pattern; a list's members may be unit values (§3.9) | | `join` | `{:enum, [:miter, :round, :bevel]}` | | | `cap` | `{:enum, [:butt, :round, :square]}` | | | `placement` | `{:enum, [:center, :inside, :outside, :double]}` | how the stroke sits on the edge (§5.6); `:center` when absent | | `non_scaling` | `:boolean` | `true`: the width stays its size on screen while the element's ancestors are scaled or zoomed (§3.9); `false` when absent | **The other parts:** | Part | Kind | Keys | |---|---|---| | `font` | `:font` | `family` (`:font`), `size` (`:size`, range `{6, 72, 1}`), `weight` (`{:one_of, [:integer, {:enum, [:light, :normal, :medium, :bold]}]}`, a word is 300, 400, 500 or 700), `style` (`{:enum, [:normal, :italic]}`), `line_height` (`:number`, the space between a text's lines as a factor of the size, `1.2` when absent, §7.1; range `{0.8, 3, 0.1}`) | | `text` | `:text_layout` | `anchor` (`{:enum, [:start, :middle, :end]}`, the horizontal alignment), `baseline` (`{:enum, [:top, :middle, :baseline, :bottom]}`, where a text sits on its point, each placement's own when absent), `offset` (`{:list, :length}`, `[x, y]`: a gap from the anchor point along the anchor's outward direction, `[0, 0]` when absent; a member may be a unit value, a `pct` of the labeled box, §3.9), `angle` (`:number`, a rotation in degrees about the anchor point, clockwise, `0` when absent; range `{-180, 180, 5}`) | | `effect` | `:effect` | `type` (`{:enum, [:none, :shadow, :blur]}`, `:none` when absent), `radius` (`:size`, `3` when absent; range `{0, 20, 0.5}`), and for a shadow `offset` (`{:list, :length}`, `[dx, dy]`) and `color` (`:color`) | | `marker` | `:marker` | `shape` (`{:enum, symbol types}`, the types of [04-shapes-and-curves](04-shapes-and-curves.md) §9.2), `size` (`:size`, area in square user units; a unit value is the side of the square of that area, a `pct` of the mark's band, §3.9) | | `curve` | `:curve` | `type` (`{:enum, curve types}`, the types of [04-shapes-and-curves](04-shapes-and-curves.md) §5.1), `tension` and `alpha` (`:number`) | A shadow also takes an `offset` and a `color` (#652, work item #674, D-175): `effect: %{type: :shadow, radius: 4, offset: [pt(2), pt(3)], color: color(:text) |> alpha(0.4)}`. `offset` is `{:list, :length}`, `[dx, dy]` in user units or unit values (§3.9), half the radius each way when absent; `color` is `:color`, black at 0.35 opacity when absent, and a color given is drawn as it is, its own alpha its opacity. A blur reads neither. Every backend draws both (§2.7, spec/09). **Shorthands, normalized on load.** A part may be written short, and the design is read in the full shape (`Visualize.Chart.Style.normalize/1`, §9): - `fill: ` is `%{type: :solid, color: }`, and `stroke` the same; `:none` is `%{type: :none}`; `{:paint, name}` is `%{type: :paint, name: name}`. A color here is any value a `:color` takes (§3.2): a literal, a slot, a meaning, a field binding, a variable. - A part written as a map with a single `color` and no `type` is `:solid`. - A gradient's `color: [a, b, …]` is its stops, evenly spaced from `0` to `1`; `stops` is the explicit form, for when the spacing matters, and wins where both are given. A `color` list in a paint with **no `type`** is a gradient's stops too — one color with no type is a solid, so a list can only be stops — whose type comes from the part it is laid over: `%{extends: :lit, fill: %{color: [color(:info), color(:info) |> darken(0.3)]}}` keeps `:lit`'s radial gradient, its center and its radius, in its own colors (§3.5, #711, D-186); laid over nothing it draws nothing, as typeless `stops` do. - `curve: :step` is `%{type: :step}`; `effect: :shadow` is `%{type: :shadow}`. - A value in a part's place that is neither a part nor a shorthand is left where it stands, for the validator to name there. The stored form is always the full shape, so a tool reads one form. **The flat keys of version 2** (`fill_opacity`, `stroke_width`, `font_size`, `margin_x`, `symbol`, …, §9) are read as the parts they mean wherever a style is read — a design, a theme's palette, a library fragment, a host's `Visualize.Chart.Build.style/3` — and are written as parts. | Version 2 keys | Part | |---|---| | `fill`, `fill_opacity` | `fill.color`, `fill.opacity` | | `stroke`, `stroke_opacity`, `stroke_width`, `stroke_dasharray`, `stroke_linejoin`, `stroke_linecap`, `stroke_style` | `stroke.color`, `opacity`, `width`, `dash`, `join`, `cap`, `placement` (`:single` is `:center`) | | `font_family`, `font_size`, `font_weight`, `font_style`, `line_height` | `font.family`, `size`, `weight`, `style`, `line_height` | | `text_anchor`, `vertical_align`, `margin_x`, `margin_y`, `text_angle` | `text.anchor`, `baseline`, `offset` (`[margin_x, margin_y]`, a missing half `0`), `angle` | | `effect`, `effect_radius` | `effect.type`, `effect.radius` | | `symbol`, `symbol_size` | `marker.shape`, `marker.size` | | `curve`, `curve_opts` | `curve.type`, and its `tension` and `alpha` | | `opacity`, `blend`, `class` | unchanged, the whole element's | **The builder's form** edits a style in these parts, one section per part (§18.7, #682, D-178), and writes nothing in the version 2 keys; a node it finds written in them is rewritten in its parts by its first edit. ### 3.2 Values **Implemented.** A value inside a part is one of nine things, and which of them a key accepts follows from its type: - a **literal** of the key's type — `"#3b6fa8"`, `2`, `:step_after`; - a **typed color** for a `:color` key ([08-utilities](08-utilities.md) §1.9, #664, D-173) — `color(:red)`, `color(:axis)`, `{:series, 3}`, `ramp(:thermal, 0.7)`, or a transform such as `color(:blue) |> intensity(0.65)` — resolved through `Visualize.Color.resolve/3`. A name resolves as a slot does: the SVG output carries `var(--vis-red, #c23238)` and a canvas the literal (D-55); a transform is the literal it computes in `:literal` mode; - a **theme slot** (`:slot`) for a `:size` or `:font` key — `:font_size`, `:font_family` — 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 **unit value** for a `:size` or `:length` key — `pt(12)`, `em(1.5)`, `pct(50)`, stored `{n, unit}` — converted to user units when the style resolves, `em` and `pct` against their context (§3.9); - a **meaning** for a `:color` key (#533, D-135): a **role** by its name in the color table — `color(:good)`, `color(:warning)`, `color(:bad)`, `color(:info)`, `color(:neutral)` — or a **ramp position** `{:ramp, name, t}` along one of the theme's four ramps, `:status`, `:thermal`, `:diverging` or `:sequential`, at `t` in `0..1` ([08-utilities](08-utilities.md) §7.5). A role is a theme slot and resolves like one; a ramp position resolves to its literal in both modes, except that `{:ramp, :status, 0 | 0.5 | 1}` resolves as `:good`, `:warning` and `:bad` do, so the two spellings of one meaning are one color (spec/08 §7.3). A design that colors by meaning writes these rather than series slots: a series slot promises a *distinct* color, a role promises the meaning, and every theme — light, dark, color-vision-safe, a host's — renders it in its own tones with the hue order fixed; - a **gradient** or a **hatch** (§3.1), as the paint of a `fill` or a `stroke` rather than a value in it — what is said here of a gradient is said of a hatch: a `:paint` paint naming a gradient the design declares under `defs` (§2.7) — `%{type: :paint, name: :fade}`, written short as `{:paint, :fade}` — or a `:linear` or `:radial` paint written in place (D-172). `Visualize.Chart.Style.resolve/3` writes a declared paint as `{:paint, name}` on the element and a gradient written in place as `{:paint, node}` — **the paint node as the element's style resolved it**, after `extends`, a stack and the defaults have merged their parts (§3.5, §3.6, §3.8; #711, D-186), without its opacity, which is the element's — both untouched, as it passes a binding; and the **frame** resolves them once its elements are drawn: `Visualize.Chart.Frame.generate/2` replaces every `{:paint, name}` and `{:paint, node}` in the tree's styles with the **paint itself**, a gradient written in place named by a hash of its resolved node (its type, stops and geometry), so the same gradient reached twice is one definition and a style that extends a gradient and changes its stops is another, a `Visualize.IR.Paint` (spec/02 §2.1, #652, D-175): its id `vis-paint--`, its kind, its geometry in the box units of §2.7 and its stops, each stop's color resolved in the mode of the render. **Every backend draws it** (spec/09): SVG writes `url(#vis-paint--)` in both modes, against the gradient the frame's `defs` holds, so a `:literal` render rasterized for a PNG draws the gradient too; a canvas — the `:json` and `:js` commands, the binary stream and the hooks that replay them — builds a `CanvasGradient` over the bounding box of each element it fills or strokes, which is what SVG's `objectBoundingBox` units mean. A gradient set on a group is built over each child's own box, as SVG's is. The one place a canvas falls back to the first stop's color is a `:text` it fills with a gradient, whose box the server cannot measure (spec/09 §3.3.3). The validator reports `{:undeclared, :paint, name}` at the paint's `name` for a name `defs` lacks. - the **contrast ink** for a `:color` key (#486, D-123): `contrast()`, stored `{:contrast, :under}` — the ink over whatever the text is drawn on, and what the bare `:contrast` of before #664 is canonicalized to — or `contrast(c)` over a color `c` of the design's choosing (spec/08 §1.9). `contrast()` is the theme's `:text` or `:background`, whichever has the higher WCAG contrast ratio (`Visualize.Color.contrast/2`) against the color the text is drawn on — `Visualize.Theme.ink/2`, spec/08 §7.3. In a mark's inline label (§5.5) that color 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 color 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 color (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 color 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 color. - a **channel binding** `{:field, f}` for any key of a part — on `marker.shape` and `stroke.dash` through the `color` scale to a role's cue (§21.7) — 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 `:color` key, passed through the scale named `color` when the frame declares one (§3.4) — a value its domain lacks is the scale's `unknown` color (§4.3), never a dropped key; **a binding is read where a datum is** (#766, D-196): of the six style sites `Visualize.Chart.Schema.style_sites/0` lists, a mark's `style`, a `:choose` case's `style` and a mark label's `style` (§5.5) read it per row, the label from the row it labels, as the mark's own elements do; a frame `:label`'s, an axis's and a legend's `style` have no datum, and a bound value there — a `{:field, f}` in an inline node of the stack, or in a design style the stack names, directly or by `extends` or a list — is `{:invalid_for, kind}` at the path that holds it, as a frame label's `{:field, f}` text is (§6.2); a stack's `{:field, f}` entry still lays nothing there and a generator's field argument still reads `nil` (§3.6, §3.13), since each has a meaning without a row; - a **color generator** `generate(:name, args)` for a `:color` key (#654, D-177), stored `{:generate, name, args}`: a call to a host's generator resolved at render, per datum where its arguments read the datum, whose result must be a typed color (§3.13). **The parts are the design's; the element keys are what they always were** (D-172). A resolved style node is **projected** onto flat keys (`Visualize.Chart.Style.project/1`, §3.4), the names the frame, the marks and the backends read: `fill.color` is `fill` and `fill.opacity` `fill_opacity`; `stroke.color`, `opacity`, `width`, `dash`, `join`, `cap` and `placement` are `stroke`, `stroke_opacity`, `stroke_width`, `stroke_dasharray`, `stroke_linejoin`, `stroke_linecap` and `stroke_style` (`:center` written `:single`); `font.family`, `size`, `weight`, `style` and `line_height` are `font_family`, `font_size`, `font_weight`, `font_style` and `line_height`; `text.anchor`, `baseline`, `offset` and `angle` are `text_anchor`, `vertical_align`, `margin_x` with `margin_y`, and `text_angle`; `effect.type`, `radius`, `offset` and `color` are `effect`, `effect_radius`, `effect_offset` and `effect_color`; `marker.shape` and `size` are `symbol` and `symbol_size`; `curve.type` is `curve` and its `tension` and `alpha` are `curve_opts`; a paint of type `:none` is the key `:none`, and a gradient `{:paint, name}`. `stroke.non_scaling` is `vector_effect: :non_scaling_stroke` (§3.9). The `transition` part (§3.10) keeps its name and reaches the element resolved, as the list of the properties it moves, and the `animation`, `enter` and `exit` parts (§3.11, §3.12) as their resolved maps; none is ever an attribute. Of the projected keys nineteen reach the element the mark draws — the fifteen of §3.4, `line_height`, and, as one, `effect` with `effect_radius`, `effect_offset` and `effect_color`, `blend` and `vector_effect`; 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). Where this document names a flat key of a resolved style — §3.4, §5.6, §6.3, spec/09 — it is this projection's key. For an enumerated key an atom is the literal; for a `:size` or `:font` key an atom is a slot. **A `:color` key never holds a bare atom in a stored design** (#664, D-173, acceptance of #650): `:none`, the literal "no paint" (in a paint's place, `%{type: :none}`), is the one bare word it keeps; `:contrast` is canonicalized to `{:contrast, :under}`; and any other atom — `fill: :bad`, which after #649 can only have meant a color — to `{:color, atom}`, by `Visualize.Chart.Migration.canonical/1` at every version (§9), silently, so it draws as it did. The validator checks every name of a typed color — a `{:color, name}` anywhere in it, operands of a transform included — against the theme's color table (`Visualize.Theme.color_names/1`) when the theme is built-in or inline (§2.5) and reports `{:undeclared, :color, name}` otherwise; a transform whose shape is not of spec/08 §1.9 (a number outside `0..1`, an empty blend), or a literal operand `Visualize.Color.parse/1` cannot read, is `{:type, :color}`. A slot of a `:size` or `:font` key is checked against `Visualize.Theme.slots/1` and reported `{:undeclared, :slot, name}`. **A scale's range given as a list is a color position too** (`:range`, §1.4, §4.3, #710, D-185): its bare atoms are canonicalized the same way, every name in it is checked against the table, and it takes every typed color and transform a style does. At render a bare atom met in a color position — a component's color, a design built in memory and never canonicalized — is still read as the name it is. ### 3.3 Built-in styles **Implemented.** Four style names are always declared — `:axis`, `:grid`, `:label` and `:title` — and a `styles` entry of the same name replaces one whole. **They are the furniture styles of the theme the chart is drawn with** (spec/08 §7.7, D-171): `Visualize.Theme.style/2` of that theme, the default theme's entry where the theme lacks one. Every built-in theme's four are the nodes these names always meant, written in slots and in parts: `:axis` (a solid `stroke` of `:axis`, a solid `fill` of `:text`, `font: %{family: :font_family, size: :font_size}`), `:grid` (a solid `stroke` of `:grid`), `:label` (a solid `fill` of `:text`, `font: %{family: :font_family, size: :label_size}`) and `:title` (as `:label` with `font: %{size: :title_size, weight: :bold}`), so a chart under a built-in theme draws as before; a host theme that gives `:title` another weight changes every title drawn under it, and a design's own `:title` still beats the theme's. The frame takes them from the theme it resolves (§4.7); the validator, the type inference and the builder, which read a style's keys and field bindings rather than its colors, take the default theme's. `Visualize.Chart.Schema.builtin_styles/0` lists the four, 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). **Every palette name is a style reference** (#637, D-171). The four are one group of the theme's style palette (spec/08 §7.7), and every name of that palette — the style series `:style_1` … `:style_n`, the roles `:good` … `:neutral`, the states `:hover` … `:breakpoint`, the furniture `:axis` … `:annotation` and the modifiers `:bold` … `:outline` — is a name a `{:ref, :style}` takes: at a site (`style: :warning`), in a stack (`style: [:node, :selected]`, `style: [:bad, :outline]`, §3.6) and under `extends` (`%{extends: :bad, stroke: %{width: 3}}`, §3.5). A name resolves against the design's `styles` first and then the palette of the theme the chart is drawn with, `Visualize.Theme.style/2` of that theme — the default theme's entry where the theme lacks one — so **a design's entry of a palette name wins for that design**, as a design's color beats the theme's (spec/08 §7.5, Precedence), and a palette name it does not declare draws as the theme says: a theme swap restyles every mark that names one. A role's entry arrives with its cue already in it (`Visualize.Theme.style/2` replaces `:cue`), and an entry is a whole look, and each mark kind draws the parts of it it has (§5.6): a line given `style: :bad` draws the bad stroke, a bar given it the bad fill with the bad outline, and a bar that wants only the outline lays `%{fill: :none}`, or the modifier `:outline`, after it. The frame reads the palette of the theme it resolves (§4.7); the validator, the type inference and the builder read the default theme's, as for the four. A name that is neither declared nor in the palette is `{:undeclared, :style, name}` (§10.1), checked against the declared names and `Visualize.Theme.style_names/1` of the theme when it is built-in or inline, as slots are; under a theme named but not built-in, whose style series only the host knows, the fixed names of the other three groups and every `:style_k` are accepted. ### 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, its parts first projected onto the flat keys (§3.2, D-172) — so a backend reads exactly the keys it read before the grammar took parts — 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 color, width and font it needs, which `Visualize.Backend.Canvas` reads as they are (spec/09 §3). `resolve/3` keeps the nineteen element keys — `line_height`, `blend`, `effect`, `effect_radius` and `vector_effect` 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 honors) and `globalCompositeOperation` on a canvas; `effect` with its radius is `filter="url(#vis-effect--)"`, 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 `:color` 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 color key whose reading is `nil` or whose scale yields `nil`. **A color is never dropped** (#487, D-122): a reading the `color` scale's domain does not hold is the scale's `unknown` color (§4.3), and a missing reading is the explicit "no paint", because the backends disagree about a color 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-color 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, D-172). A style MAY name a parent under `extends`, a `{:ref, :style}` like any other style reference: the lookup flattens the parent first and lays the child over it by **the merge rule**, so `%{extends: :axis, stroke: %{width: 2}}` is the axis style drawn heavier — the axis stroke's color kept — and the parts of §3.3 are not copied. **The merge rule** (`Visualize.Chart.Style.merge/2`), the one way a style is laid over another — by `extends`, in a stack (§3.6), and in the fragment cascade (§8.2): every top-level key of the later wins, except a **part**, which merges **key by key**, so `%{extends: :warning, stroke: %{width: 3}}` keeps the warning stroke's color and dash. When the two name **different `type`s** of one part — a solid fill over a linear one, `:none` over a color, one curve over another — the later part **replaces** the earlier, because `color` and `stops` do not mix and a curve's tension is its type's; it keeps of the earlier only what no type decides: a paint's `opacity`, and a stroke's `width`, `dash`, `join`, `cap` and `placement`. A partial part with no `type` (`%{width: 3}`) keeps the type under it, so `[:outline, %{fill: %{opacity: 0.5}}]` is still no fill. A chain of any length resolves, each link flattened over the one above it; the parent is looked up among the declared styles and then the theme's palette (§3.3), so a design derives from `:axis`, `:grid`, `:label`, `:title` — or `:warning`, `:selected`, `:style_2` — without declaring them. A palette entry is flat (spec/08 §7.7), so the palette ends every chain. A design entry of a palette name that extends the same name names itself, not the theme's entry, and is a cycle like any other: a design that wants "the theme's `:bad`, heavier" declares it under a name of its own. **`extends` may name a list** (#658): `%{extends: [:bad, :bold], fill: :none}` derives from the stack of the two — the bad look with bold text — and lays its own parts over that, as a list at a site would (§3.6). 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: ```elixir [ 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 by the merge rule of §3.5, part by part. 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 synthesizes 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 stack at a site cannot introduce a cycle, because a site is not a name: an entry may not name the stack it sits in. **A list of styles anywhere a style goes** (#658, D-172). The list a site takes is the list every other style position takes: a `styles` entry (§2.6), `extends` (§3.5), a theme's palette entry ([08-utilities](08-utilities.md) §7.7) and every site — `mark.style`, `label.style`, `mark_label.style`, `axis.style`, `legend.style` — with a site's `{:field, f}` entries among them (#644). Wherever it stands, a list stacks left to right into one style by the merge rule (§3.5), the later winning. A name, a list and an `extends` chain may reach one another, and a style that reaches itself through any of them — `a: [:b]`, `b: %{extends: :a}` — is `:cycle` at its path in `styles` (§10.1), refused before it is drawn. **A bare atom is a style.** In a style position — a site, a `styles` entry, `extends`, a list in any of them — a bare atom names a style: the design's `styles` first, then the theme's palette (§3.3). A color is never written there; it is written in a part (`fill: %{color: …}`, or the shorthand `fill: …`, §3.1), and in a paint's place the one reserved bare atom is `:none`, no paint. (Until #650 types colors, an atom in a color's place is still a slot or a meaning, §3.2.) **A field in the stack: a style named by data** (#637, #644, D-171). A stack entry MAY be a field binding `{:field, f}`: the style **named by the datum's value** of `f`. It is laid on the stack **where it stands**, the later entry winning where they overlap, so partial entries go over a base and a later entry over an earlier one. It stands alone or in a list, like any other entry: ```elixir [style: {:field, :health}, style: [:node, {:field, :health}, %{stroke: %{width: 2}}]] ``` - **The value names a style.** It resolves as any style reference does: against the design's `styles`, then the palette of the theme the chart is drawn with (§3.3), so a design's entry of the name wins. The value is an atom naming the style, or a string spelling its name — a feed's `"warning"` names `:warning` — which is matched against the names there are and never made into an atom. The mapping from data to a style name is the data's to carry: a column a host computes, or a virtual source (#643), never a scale. - **A value that names no style lays nothing.** A `nil` value, a value naming no declared style and no palette entry, and a value of any other type lay no style: the stack's other entries draw the element, and the mark keeps its own look. It is never a crash and never a fault at render. - **It is resolved per datum, by §3.2's binding rule.** A mark that draws one element per datum lays one style per element, read from that element's datum. A mark that draws one path per series — `:line`, `:area`, `:percentile_band` — takes the style of the series' first datum for the whole path. The keys that are read once per series or per placement — the `curve`, the stroke's `placement` and the `text` part — always come from the series' first datum, the whole mark's when it has no `series`; the `marker` varies per element where the mark draws symbols. A mark's inline label (§5.5) reads its `mark_label.style` entries from the datum of the element it labels. A style laid by data is a whole node and draws as one: its colors resolve through the theme in the render target's mode, a `{:field, f}` in it binds to the same datum, and it beats the series' color of §5.6 as any later layer beats an earlier one. - **Every site takes one.** The validator accepts the entry at all five sites — `mark.style`, `label.style`, `mark_label.style`, `axis.style` and `legend.style` — and checks `f` as any field binding (§3.2): a field the mark's source does not declare is `{:undeclared, :field, f}` at the entry's path. Where there is no datum — a frame label, an axis, a legend, the type inference, the color domain's field bindings — the entry lays nothing, so the rest of the stack is the site's style there. A design whose stack holds no field entry draws byte for byte as before: the per-datum path is taken only by a mark whose stack holds one. **A virtual source's field joined to an item** (#643, D-194). On a board, a row of a feed carries the fields of every per-identity virtual source over that feed for its own identity, each named `:"."` (spec/15 §14.7), so `style: {:field, :"health.state"}` names the style `:ok`, `:warning` or `:error` by the host's own health, and a list composes as any: `[:base, {:field, :"health.state"}]`. A design declares the joined field among its slot's `fields` like any column; its JSON is `{"$field": "health.state"}`. When the field declares `values`, the stack is checked to cover them (§7.4). **A generator in the stack: a style computed at render** (#654, D-177). A stack entry MAY be a generator call `generate(:name, args)`, stored `{:generate, name, args}`: the style a host's generator returns for those arguments (§3.13). It is laid **where it stands**, as a field entry is, alone or in a list: ```elixir import Visualize.Generators, only: [generate: 2] [ style: generate(:tenant_style, [{:field, :tenant}]), style: [:message, generate(:tenant_style, [{:field, :tenant}]), %{stroke: %{width: 2}}] ] ``` Its result is a style — a name, a node or a list of them — and is laid as that style would be. Its field arguments are read from the datum by the same binding rule as a field entry's; where there is no datum they read `nil`, and a generator whose arguments are all literals draws the same everywhere, a frame label, an axis and a legend included. A result that is no style lays nothing (§3.13). ### 3.7 Precedence **Implemented** (#658, #670, D-172, D-174, D-177). The look of an element is laid from these layers, each over the ones before it by the merge rule (§3.5), lowest first: | | Layer | Where it comes from | |---|---|---| | 1 | theme root defaults | the theme's `defaults` over the library's base (§3.8, [08-utilities](08-utilities.md) §7.1) | | 2 | container defaults | the part defaults of the design's, the frame's, and the element's layers' and groups' `defaults` (§3.8) | | 3 | mark-kind defaults | a container's `defaults` entry for the element's kind (§3.8) | | 4 | named and stacked styles, with `extends` | the site's stack: names, lists and inline nodes, each through its `extends` (§3.5, §3.6); the theme's palette under a name the design does not declare (§3.3) | | 5 | the field-chosen style | a `{:field, f}` entry, the style the datum's value names (§3.6) | | 6 | generator results | a `{:generate, name, args}` entry, the style a host's generator returns (§3.6, §3.13) | | 7 | view states | `:hover`, `:focused`, `:selected`, `:muted`: a board's selection (spec/15 §13.2), the hooks' markers (spec/10 §4.4) | | 8 | the site's local inline edit | the inline node a stack ends with (§3.6) | **View states sit above data styles**, so feedback stays visible over whatever the data chose, and **the local edit sits above everything**, so an edit made at a site is what that site shows. A stack an author writes is laid in the order written, a field entry where it stands (§3.6); the order above is the one the library keeps where it adds a layer itself. A board puts its selection's state entry after the stack's names, field entries and generator entries and **before** a trailing inline node (`Visualize.Chart.Style.with_state/2`), and a resolved state is laid over the element's own look and never under it. Layers 2 and 3 are laid **container by container, nearest last** (§3.8): within one container its kind entry is over its part defaults, and a nearer container's part defaults are over a farther one's kind entry. A generator entry an author writes after a field entry is laid over it, as layer 6 is over layer 5; a color generator in a part (§3.2) sits at the layer of the style that holds it. A mark's own paint — the series' color of §5.6 — is what the theme's root gives a mark when no layer above sets its paint key. ### 3.8 Defaults: inherited by container and mark kind **Implemented** (#651, work item #670, D-174). A style says what it changes. What it does not say — the width of a stroke given only a color, the family of a font given only a size — comes from **defaults**, inherited from the containers the element sits in, so a design says "every stroke here is 2 wide" in one place: ```elixir %{ version: 3, sources: %{load: %{fields: [:t, :v, :host]}}, defaults: %{ stroke: %{width: 2, cap: :round}, font: %{family: "Inter", size: 12}, line: %{stroke: %{width: 1.5}}, # every line in this design rect: %{stroke: :none} # and no outline on a rect }, frames: %{main: %{kind: :cartesian, defaults: %{font: %{size: 11}}}}, marks: [%{type: :line, data: :load, channels: %{x: :t, y: :v, series: :host}}] } ``` **A `:defaults` node** holds the parts of a style (§3.1) — `fill`, `stroke`, `font`, `text`, `effect`, `marker`, `curve`, `opacity`, `blend` and the motion parts (`transition`, `animation`, `enter` and `exit`, §3.10–§3.12) — each typed as the style's key of that name, shorthands normalized on load as a style's are — and one key per **mark type** (§5.2) but `:text`, each a `:kind_defaults` node of the same parts, which applies to the elements of that kind alone. `text` is the part — where a text sits on its point — as in a style, so the `:text` mark has no entry of its own: the parts only a text draws, `font` and `text`, already reach every text and nothing else (§5.6). A defaults node has no `extends` and no `class`: it is not a style that can be named, derived or stacked, and a class is a statement about one site. `bar` is not a mark type; a bar is a `:rect`. **Containers.** Four things hold defaults: | Container | Where its `defaults` are written | |---|---| | the design | `defaults` (§2.1) | | a frame | `frames..defaults` (§4.1) | | a layer, and a group of the builder's tree | the composite's own `defaults`, beside its `uses` and `vars` (§19.6) | | the theme | its root defaults ([08-utilities](08-utilities.md) §7.1): layer 1, under every container | A layer and a group are composites (§18.8, §19.6), and a composite is flattened into a design that has no layers. So `Visualize.Chart.Composite.flatten/2` writes a composite's defaults onto **what it places**: each mark, label and axis gets them as its own `defaults` (§5.1, §6.1, §4.4), and a frame as its frame's `defaults`, the composite's under what the node already has, by the merge rule. A group inside a layer is flattened first and the layer's laid under it, so the group's are the nearer. A flat design therefore carries the scoping as data, and a mark's, a label's or an axis's own `defaults` read as "the layers and groups this came from"; a hand-written design may set them too. **Resolution.** An element's defaults are its containers' in order, farthest first: the theme's own `defaults`, the design's, the frame the element is drawn in, and the element's own. For each container its **part defaults** are laid, then its **entry for the element's kind** over them, each by the merge rule (§3.5) over what the containers before it laid; the site's stack (§3.6) is then laid over the result. So within one container a kind entry wins over the part defaults, a nearer container wins over a farther one, and every style wins over every default: - A mark of type `t` takes the `t` entry. A `:text` mark, a mark's inline label (§5.5) and a frame label (§6) take the part defaults alone, the labels through the mark's or the label's own containers. An axis — its line, ticks, tick labels and grid — and a legend take the part defaults alone. - The mark-kind rule of §5.6 still holds: a part a kind does not draw is ignored, whether a default or a style gave it. A design default `fill` is drawn by a bar and ignored by a line. - A paint given only partly (`stroke: %{width: 2}`) leaves the paint's color to the layer below, so a mark with no stroke color from any layer keeps its series color (§5.6). A default `stroke: color(:gray)` is the color of every mark of a stroked kind that names none, its series color included: a default is the color, the series color only the theme's last word. - `:none` is no paint whether a style or a default says it, and a style's paint over it draws again. - A furniture style — `:axis`, `:label`, `:title`, … (§3.3) — is a named style, layer 4, and wins over a default: the built-in `:label` names `font: %{family: :font_family, size: :label_size}`, so a default `font` family reaches a frame label only where its style does not name one. A design that wants every text in one face sets the theme's `font_family` or restyles the furniture. **The theme's root defaults are every part, defined.** `Visualize.Theme.defaults/1` answers the root of a theme: the library's **base** — what an element that carries no value for a key already draws — under the theme's own `defaults` field: | Part | Base | |---|---| | `fill` | `%{opacity: 1}` | | `stroke` | `%{opacity: 1, width: 1, join: :miter, cap: :butt, placement: :center}` | | `font` | `%{family: :font_family, size: :font_size, weight: :normal, style: :normal, line_height: 1.2}` | | `text` | `%{offset: [0, 0], angle: 0}` | | `effect` | `%{type: :none, radius: 3}` | | `marker` | `%{shape: :circle, size: 64}` | | `curve` | `%{type: :linear}` | | `opacity`, `blend` | `1`, `:normal` | So `stroke: color(:blue)` is a blue stroke 1 wide with butt caps unless a container says otherwise, and `explain/2` (§17.3) shows that root under every part. **The base is never written onto an element.** For a fill, a stroke, an effect, a marker and a curve it is what the backends and the mark generators already draw when the key is absent — SVG's and the canvas's initial values, and the generators' `:circle`, `64` and `:linear` — so writing it would change every chart's bytes and no chart's drawing. The font is the theme's family and size: what the built-in themes' canvas draws by default (`10px sans-serif`), and what every furniture text names through its style (§3.3); an SVG text whose style names no font takes the page's, as it always has. A paint's color and a text's anchor and baseline have no base: the mark's series color (§5.6) and each placement's own (§6.3) decide them. A theme's own `defaults` are laid as layer 1, under the design's: a house theme that draws every stroke 1.5 wide says so once. **Nothing changes for a design without defaults.** No container's `defaults` and no theme `defaults` lay nothing, so every design drawn before this section draws byte for byte as it did. **Validation.** A defaults node is checked by its schema: each part as the style's key of that name is (§3.1, §3.2) — a color name against the theme's table, a slot against its slots — and a key that is neither a part nor a mark type is `:unknown_key` at its path. A `{:field, f}` at a key is accepted as in a style (§3.2): it binds per datum where the element has one. ### 3.9 Sizes in units, and strokes that do not scale **Implemented** (#651, work item #671, D-174). A size is written in any common unit — `stroke: %{width: pt(1.5)}`, `font: %{size: em(1.2)}`, `text: %{offset: [mm(2), 0]}` — and a bare number keeps its meaning: user units. A unit value is `{n, unit}`, built by `Visualize.Units` (`import Visualize.Units`, [08-utilities](08-utilities.md) §13) or written directly, and every backend gets a number: the conversion happens when the style is resolved, so SVG and a canvas draw the same width. | Where | Accepts | Absolute (`px`, `pt`, `pc`, `in`, `cm`, `mm`) | `em` | `pct` | |---|---|---|---|---| | `stroke.width`, `effect.radius` | `:size` | converted (spec/08 §13.1) | × the element's font size | `{:no_box, key}` | | an `effect.offset` member | `:length` | converted | × the element's font size | `{:no_box, :offset}` | | a hatch's `spacing`, `width` | `:size` | converted | × the theme's `font_size` | `{:no_box, key}` | | a `stroke.dash` member | `:length` | converted | × the element's font size | `{:no_box, :dash}` | | `font.size` | `:size` | converted | × the **inherited** font size | % of the inherited font size | | a `text.offset` member | `:length` | converted | × the element's font size | % of the labeled box: the element's width for `x`, its height for `y` | | `marker.size` | `:size` | the side of the square of the area: `pt(6)` is an area of 8² | the side, × the element's font size | the side, % of the mark's band | | any opacity | `:size` | `{:no_unit, :opacity}` | `{:no_unit, :opacity}` | `{:no_unit, :opacity}` | **`em` is resolved at compile time** (#651's acceptance, modification 2), never written as a CSS `em`, so a canvas, which has no cascade, and SVG agree. The **inherited font size** is the one the defaults an element inherits give (§3.8) — each container's relative size measured against the one before it, so a design at `em(1.2)` and a frame at `em(1.5)` are 1.8 times the root — and the theme's root, its `font_size`, when no container sets one. An `em` at `font.size` is measured against that inherited size; an `em` anywhere else against the element's own resolved font size, which is the inherited one unless its style sets another. That is CSS's rule for `em`, made once on the server. **`pct` only where a size has a box** (#651's acceptance, modification 1). A text's offset is a percentage of the box it labels — the element's bounds for a mark's inline label (§5.5), the plot area for a frame label (§6) and for a label on an element with no extent; a marker's size of the band of the mark's `x` scale, else its `y` scale, and `ArgumentError` naming the mark when neither is a `:band`; a font size of the inherited font size. A stroke's width, a dash and an effect's radius have no box, so a `pct` there is `{:no_box, key}` at its path (§10.1), naming the key. A unit at an opacity, which is a fraction, is `{:no_unit, key}`. **A stroke that does not scale.** `stroke: %{non_scaling: true}` keeps a stroke its width on screen while its ancestors are scaled or zoomed — a map's borders, a hairline grid under a zoom. The default is to scale. The part projects to the element key `vector_effect: :non_scaling_stroke`, and each backend draws it (spec/09): - **SVG** writes `vector-effect="non-scaling-stroke"` on every shape the style reaches. The property does not inherit, so a group's is written on its children rather than on the group. - **A canvas** (#651's acceptance, modification 3) divides the width by the scale of the transform current when the width is set, `√|det|` of the context's matrix (`a·d − b·c`): a 2-wide stroke under `scale(2)` sets a `lineWidth` of 1 and draws 2 pixels wide. The `:json` and `:js` outputs and the binary stream each carry it (spec/09 §3.3.3, §4.3.5), and the hooks compute it with `getTransform()` when they draw. **A marker or a text that does not scale is not part of this.** SVG has no attribute that keeps a glyph's size under its ancestors' scale — SVG 2's `vector-effect: non-scaling-size` is drawn by no browser — and nothing in the library zooms a chart's canvas yet, so the two backends could not agree. They come with the scenes that zoom (#620). **Validation and storage.** The validator accepts a unit value wherever a `:size` or a `:length` goes and reports a unit not of spec/08 §13 as `{:type, :size}` or `{:type, :length}`. A unit value is stored as the tuple and written in JSON as `{"$unit": [n, "unit"]}` (§11.2). Nothing changes for a design without units: a bare number is the number it was. ### 3.10 Motion: transitions **Implemented** (#653, work item #676, D-176). When a datum's style changes — from `:ok` to `:error`, or into the board's `:selected` — the element's new look is reached over time rather than at once, when its style says so. Motion is a property of the **look**, so it is a part of the style, laid and merged as every part is (§3.5–§3.8): a state's or a role's style can carry it, and a container's `defaults` can give it to every element below. ```elixir [ transition: %{duration: 200, easing: :cubic_out}, # the fill, the stroke and the opacity transition: %{fill: %{duration: 400}, stroke: %{duration: 150}} # the fill and the stroke alone ] ``` **The part** (`:style_transition`): | Key | Type | Notes | |---|---|---| | `duration` | `:number` | milliseconds, `300` when absent; range `{0, 5000, 50}` | | `easing` | `{:enum, Visualize.Ease.names()}` | the curve the change follows, a curve of `Visualize.Ease` by name — the ones a scale's and a mark's `transition` take (§4.3, #360) — `:cubic_in_out` when absent | | `fill` | `{:node, :part_transition}` | the fill's own `duration` and `easing` | | `stroke` | `{:node, :part_transition}` | the stroke's own | | `opacity` | `{:node, :part_transition}` | the whole element's opacity's own | A `:part_transition` is `duration` and `easing`, typed as above. **Which properties move:** the part's own `duration` or `easing` moves all three — `fill`, `stroke` and `opacity` — and a part entry moves that part, so `%{fill: %{duration: 400}}` moves the fill alone; each property's duration and easing are its entry's, else the part's own, else the defaults above. A `duration` of `0` moves nothing, and a node with none of the keys moves nothing. **What a property moves:** the `fill` the fill's color and its opacity; the `stroke` its color, its width and its opacity; `opacity` the element's. A gradient or a hatch is not interpolated: it is drawn at its new value at once, on every backend, as a color that changes to a paint is. Geometry is not a style's to move: a mark's own `transition` eases its readings (§5.1, §12.5). **Resolution.** `Visualize.Chart.Style.resolve/3` writes the part on the element as `transition`, resolved: the list of `{property, duration, easing}` it moves, in the order `fill`, `stroke`, `opacity`, e.g. `[{:fill, 400, :cubic_in_out}]`; an empty list is no key. It is laid as every key is, so an element whose data chose a style with a transition (§3.6) carries it on the element, and a mark whose own stack carries one carries it on its group. **Identity.** A transition is keyed by **which thing** changed, not by which element happened to draw it. Every element of a mark that **moves** writes `data-vis-id`: a mark moves when its own stack carries a motion part, or when its stack names a style by data (§3.6) and any style the frame knows — the design's `styles`, the theme's palette — carries one. That is a fact of the design, not of the rows drawn now, so a row's element names its identity before the row first chooses a moving style, and a canvas knows what it showed when it does. The attribute is `..`, the frame's name, the mark's one-based position among the design's marks, and the row's identity in the board's form (spec/15 §13.2) — the identity the slot's schema declares (D-167), else the inference a pick uses — written `field=value`, several fields joined by `&` in name order; a row with neither is its ordinal among the mark's elements, `#n`. A path-per-series mark reads it from the series' first datum. A mark whose style has no motion part writes no `data-vis-id`, so every chart drawn before this section draws byte for byte as it did. **`:css` output** (SVG). The frame writes each distinct resolved transition as one class, `vis-transition-` (`` the base-36 `:erlang.phash2/1` of the resolved list), added to the `class` of every element that carries it, and one `