Architecture

Status: Implemented

Visualize is a pipeline of pure values: data is mapped by scales, turned into geometry by shapes, assembled into a backend-agnostic scene graph (the IR), and finally serialised by a backend. This document settles the pipeline, the three IR modules, the backend behaviour and its resolution, the Visualize.Render entry point, and the SVG element layer that faces HEEx templates.

1. The pipeline

data ──► Visualize.Scale ──► Visualize.Shape ──► Visualize.IR.Element ──► Visualize.Backend ──► Visualize.Render
          domain → range     path strings or      scene graph of          SVG | Canvas          iolist | String
                             IR.Path               elements + transforms   (+ encoders)

1. Scales (Visualize.Scale, 03-scales) map domain values to range values. They are structs; apply/2 performs the mapping.
2. Shapes (Visualize.Shape, 04-shapes-and-curves) turn scaled data into geometry. generate/2 returns an SVG path-data string; generate_path/2 returns a Visualize.IR.Path.
3. The IR (Visualize.IR.*, §2) is the scene graph: Element nodes carrying attributes, style, an optional Transform, children, text content or a Path. Visualize.Axis.generate/1 and the layouts emit IR.
4. Backends (Visualize.Backend, §3) serialise the IR. Visualize.Backend.SVG and Visualize.Backend.Canvas implement the behaviour. Visualize.Backend.CanvasBinary, Visualize.Backend.Hybrid and Visualize.Backend.CanvasIncremental are encoders with their own entry points, not behaviour implementations; they are specified in 09-rendering-backends.
5. Render (Visualize.Render, §4) chooses a backend and dispatches on the IR's shape.

Every stage is a pure function of its inputs. No stage holds process state; the only process in the library is the force simulation (06-layouts).

2. The intermediate representation

2.1 Visualize.IR.Element

An element is %Visualize.IR.Element{type, attrs, style, transform, children, content, path, clip}. clip is nil or %{shape: element, keep: :inside | :outside}: the element is drawn only where the shape is (:inside) or only where it is not (:outside), the shape being a :path, :rect, :circle, :ellipse or :polygon element whose style is ignored — how a stroke is kept inside or outside an edge (spec/14 §5.6). A backend that can clip MUST honour it (spec/09 §2.3, §3.3); one that cannot draws the element unclipped and says so. type MUST be one of :path, :rect, :circle, :ellipse, :line, :polyline, :polygon, :text, :group, :image, :defs, :clip_path, :linear_gradient, :radial_gradient, :stop, :filter, :fe_drop_shadow, :fe_gaussian_blur, :tspan, :root, :title, :desc. attrs is a map of geometric attributes; style is a map whose recognised keys are :fill, :stroke, :stroke_width, :stroke_linecap (:butt | :round | :square), :stroke_linejoin (:miter | :round | :bevel), :stroke_dasharray, :opacity, :fill_opacity, :stroke_opacity, :font_size, :font_family, :font_weight, :font_style, :text_anchor (:start | :middle | :end), :dominant_baseline, :class, :blend (a mix-blend-mode word), :effect (:none | :shadow | :blur) with :effect_radius; :fill and :stroke accept a string, :none or :current_color. Gradient stops additionally use :stop_color and :stop_opacity. Backends MUST pass unrecognised style keys through unchanged. Constructors with a default style argument default it to %{}.

Visualize.IR.Element implements String.Chars (renders through Visualize.Backend.SVG) and, when Phoenix.HTML.Safe is loaded, Phoenix.HTML.Safe (D-7).

2.2 Visualize.IR.Path

A path is %Visualize.IR.Path{commands, metadata}; metadata is a free map for producers and is not serialised. Commands are tuples tagged with the SVG command letter — absolute upper-case, relative lower-case: {:M|:m, x, y}, {:L|:l, x, y}, {:H|:h, x}, {:V|:v, y}, {:C|:c, x1, y1, x2, y2, x, y}, {:S|:s, x2, y2, x, y}, {:Q|:q, x1, y1, x, y}, {:T|:t, x, y}, {:A|:a, rx, ry, rotation, large_arc, sweep, x, y} and the bare atom :Z. large_arc and sweep MUST be 0 or 1. Builders append in call order. A path is built in time proportional to its commands (#414): the appenders above put one command at the end of a list, which is the cost of the list, so a builder that draws one command per datum makes its commands in order and hands them to from_commands/1 at the end — a path of 50,000 commands took six seconds to append one at a time and the drawing of a large chart was quadratic in its points.

to_string/1 is the only d serialisation: Visualize.Backend.SVG.path_data/1, Visualize.SVG.Path.to_string/1 and the String.Chars implementation for Visualize.IR.Path (defined alongside Visualize.SVG.Path) delegate to it (D-12, D-34).

2.3 Visualize.IR.Transform

A transform is %Visualize.IR.Transform{operations}, an ordered list applied left to right as SVG does: {:translate, x, y}, {:rotate, angle}, {:rotate, angle, cx, cy}, {:scale, sx, sy}, {:skew_x, angle}, {:skew_y, angle}, {:matrix, a, b, c, d, e, f}. Angles are degrees.

3. The backend behaviour

3.1 Callbacks

Visualize.Backend is a behaviour. An implementation MUST define:

• path_data(Visualize.IR.Path.t()) :: String.t() | [tuple()] — the backend's native path data (the d string for SVG; a list of drawing commands for Canvas).

• render_path(Visualize.IR.Path.t(), keyword()) :: output — a rendered path; options MAY include :style.
• render_element(Visualize.IR.Element.t(), keyword()) :: output — a rendered element tree.
• render_scene([Visualize.IR.Element.t()], keyword()) :: output — a rendered list of elements; the built-in backends wrap the result with wrap_root/2 unless wrap: false.

and MAY define wrap_root(output, keyword()) :: output, which wraps content in a root container (<svg> for SVG; canvas setup for Canvas) using options :width (default 800), :height (default 600) and :view_box. output is an iolist, string, map or command list as the backend chooses. The callback implementations on Visualize.Backend.SVG and Visualize.Backend.Canvas are specified in 09-rendering-backends.

3.2 Resolution and configuration

config :visualize, default_backend: value accepts the same values as resolve/1. There is deliberately no per-process override (D-2): the backend is either the :backend option at the call site or the application configuration.

4. Visualize.Render

Visualize.Render dispatches a renderable — a Visualize.IR.Path, a Visualize.IR.Element, or a list of elements — to render_path/2, render_element/2 or render_scene/2 respectively. Every function takes an options keyword list; :backend (:svg, :canvas, or a module) selects the backend and all other options pass through to it.

to_png/2 is the one function of the module that produces no backend output: it renders an IR root with to_svg_string/2 and hands the SVG to the rasteriser of 09-rendering-backends §9 (D-121). Its input is narrower than a renderable, because a PNG is a whole document: a :root element (Visualize.IR.Element.root/3, or Visualize.Chart.generate/2 with root: true), or the SVG string such an element renders to (Visualize.Chart.render/2 with root: true).

5. The SVG element layer

Visualize.SVG.Element predates the IR and remains the HEEx-facing struct: %Visualize.SVG.Element{tag, attrs, children, content} mirrors an SVG element one-to-one, with tag an SVG tag atom and attrs a map rendered as attributes. It implements String.Chars and, when Phoenix is loaded, Phoenix.HTML.Safe via Visualize.SVG.Renderer.render/1, so it interpolates into a template as an iolist without escaping. from_ir/1 is the bridge from the IR: the scene graph is built with Visualize.IR.Element, converted once, and embedded.

5.1 Visualize.SVG.Element

from_ir/1 maps element types to tags (:group → :g, :root → :svg, :clip_path → :clipPath, :linear_gradient → :linearGradient, :radial_gradient → :radialGradient, others unchanged), copies attrs, adds d from the path via Visualize.IR.Path.to_string/1, adds transform via Visualize.IR.Transform.to_string/1, converts every style key to its hyphenated SVG attribute name (:stroke_width → :"stroke-width" and so on) and every style atom value to its SVG keyword (:none → "none", :current_color → "currentColor", :start, :middle, :end, :butt, :round, :square, :miter, :bevel, :bold). Style attributes overwrite geometric attrs of the same name. A :root element gains xmlns="http://www.w3.org/2000/svg" and its view_box attr becomes the viewBox key (D-11, D-34); a :polyline/:polygon whose points is a list of {x, y} tuples has it formatted as Visualize.Backend.SVG formats points (spec/09 §2.6). Conversion is recursive over children. The result renders, through Visualize.SVG.Renderer, to exactly the markup Visualize.Backend.SVG.render_element/1 emits for the same IR (D-34); test/visualize/svg/bridge_test.exs holds both to it.

Every constructor accepts attrs as a map or keyword list. The camel-case names (clipPath, linearGradient, radialGradient) are deliberate: they are the SVG tag names.

5.2 Visualize.SVG

The fluent builder over Visualize.SVG.Element. Attrs are accepted as keyword lists or maps.

5.3 Visualize.SVG.Path

A compatibility façade: every builder delegates to Visualize.IR.Path and operates on Visualize.IR.Path structs (there is no separate SVG.Path struct). New code SHOULD use Visualize.IR.Path directly.

5.4 Visualize.SVG.Renderer

Serialises an SVG.Element tree. Attributes with a nil value are omitted; the rest are emitted sorted by their SVG name from attribute_name/1, values escaped (&, ", <, >); text content is escaped (&, <, >); child-less, content-less circle, ellipse, line, path, polygon, polyline, rect, image, use, stop, feDropShadow and feGaussianBlur elements are self-closing. The iolist form is what Phoenix.HTML.Safe returns. Visualize.Backend.SVG renders its tags, attributes and text through the same functions, so the two serialisers cannot drift (D-34).