Visualize.Chart.Builder (Visualize v0.2.35)

Copy Markdown View Source

An embeddable editor of typed fragments (spec/14 §18, §19).

A Phoenix.LiveComponent, not a Phoenix.LiveView: a LiveView owns a route and a session, and this embeds in whatever page a host already has.

<.live_component module={Visualize.Chart.Builder} id="builder"
                 layers={@layers} sources={@sources} on_save={:design_saved} />

The host owns the route, the layers the builder starts with, the pool of sample sources the preview binds to, the library of saved fragments (Visualize.Chart.Builder.Store) and what saving means. The builder owns the editing state alone: a stack of use sites (§19.3) — each a fragment used at a position, with what is masked, bound and added there — and, when a library entry is opened, that entry's fragment. The one thing that leaves it is a message: saving sends {on_save, id, structure} to the host LiveView process, where structure is the stack as a composite (§19.6); a host that wants a flat design flattens it with Visualize.Chart.flatten/2. It pushes no event and patches no URL (D-85).

Assigns

  • id - the component id (required)
  • layers - the fragments the stack starts with, in precedence order, the higher later: a design map, a Visualize.Chart or a {name, layer} pair (default []). Each is seeded as an inline-only use site (§19.9).
  • sources - the pool of sample sources the preview binds the design's slots to, as Visualize.Chart.apply/2 takes it (default %{})
  • vars - the values the preview applies the design's variables with (default %{})
  • theme - a Visualize.Theme for the preview, nil for the design's own
  • store - a module implementing Visualize.Chart.Builder.Store, or {module, context} with what the host wants every callback told (spec/14 §19.7), or nil for no library (default nil)
  • on_save - the tag of the message saving sends (default :visualize_chart_saved)
  • styles - render the stylesheet in a <style> element (default true); false when the host ships Visualize.Chart.Builder.css/0 through its own asset pipeline
  • class - appended to the builder's root class

Handling the message

def handle_info({:design_saved, "builder", structure}, socket) do
  {:ok, design, _missing} = Visualize.Chart.flatten(structure, &MyStore.fetch/1)
  {:noreply, assign(socket, design: design)}
end

This module compiles only when Phoenix.Component is loaded: phoenix_live_view is an optional dependency, so an application that only renders predefined charts never compiles a line of the builder, which scripts/consumer_check.exs proves on every pipeline (spec/10 §1.1, D-45, D-85).

Summary

Functions

css()

Returns the builder's stylesheet as a binary (spec/14 §18.13).

mount(socket)
styles(assigns)

Renders the stylesheet in a <style> element (spec/14 §18.13).

tick(id, socket)

The host's one line for the signals' tick (spec/14 §18.2): forwards the message the builder scheduled to itself, {:visualize_chart_tick, id}, as an update.

Functions

css()

@spec css() :: binary()

Returns the builder's stylesheet as a binary (spec/14 §18.13).

The builder renders this itself unless the host passes styles={false}; Visualize.Chart.Builder.Styles.install!/0 writes it beside the hooks for a host that would rather own the file.

mount(socket)

Attributes

  • id (:string) (required) - the component id.
  • layers (:list) - the fragments the stack starts with, the higher later. Defaults to [].
  • sources (:map) - the pool the preview binds the design's slots to. Defaults to %{}.
  • vars (:map) - the values the preview applies the variables with. Defaults to %{}.
  • theme (:any) - a Visualize.Theme for the preview. Defaults to nil.
  • source_defaults (:boolean) - whether a source's default is offered in the form (spec/14 §18.1, §19.10). Defaults to true.
  • tick_ms (:integer) - the period of the signals' tick while playing (spec/14 §19.10). Defaults to 500.
  • store (:any) - a Visualize.Chart.Builder.Store, or {module, context}. Defaults to nil.
  • on_save (:any) - the tag of the save message. Defaults to :visualize_chart_saved.
  • on_deploy (:any) - the tag of the deploy message: the flat design, where save's carries structure. Defaults to :visualize_chart_deployed.
  • styles (:boolean) - render the stylesheet, false if the host ships it. Defaults to true.
  • class (:string) - appended to the builder's root class. Defaults to nil.
  • library_folded (:any) - the library's top-level headers folded at the start, a set of names; a person's folds are the builder's own after that (spec/14 §18.16, #355).

styles(assigns)

Renders the stylesheet in a <style> element (spec/14 §18.13).

tick(id, socket)

@spec tick(String.t(), Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()

The host's one line for the signals' tick (spec/14 §18.2): forwards the message the builder scheduled to itself, {:visualize_chart_tick, id}, as an update.

def handle_info({:visualize_chart_tick, id}, socket),
  do: {:noreply, Visualize.Chart.Builder.tick(id, socket)}