Macaw.Surface (macaw v0.1.2)

Copy Markdown View Source

A surface: a reusable composed unit of cells in a 12-column grid (spec/06 §3.1).

{:ok, surface} =
  Macaw.Surface.new(
    name: "service_overview",
    title: "Service overview",
    cells: %{
      "latency" => %{component: "macaw.table", place: %{x: 0, y: 0, w: 6, h: 4},
                     slots: %{"rows" => %{source: "latency"}}}
    }
  )

A surface is a document, read through the kernel's gates and stacked as a fragment:

  • the map form is %{version: v, surface: node} (to_map/1), the JSON form {"$version": v, "surface": {…}} (to_json/1); from_map/2 and from_json/2 read them back through every gate (the version, the limits, the migration), then new/1;
  • as a fragment type, cells is a :union by name and every other key an :override, so a layer adds or replaces cells by name and overrides the title.

Names are strings, an atom read as its spelling; no atom is made from a document.

Summary

Types

t()

Functions

fetch(validated, env)

Each cell's deliveries and drawn state (spec/06 §3.5): %{cell => %{deliveries:, drawn:}}. env: sources: (as given to validate/3), now: and ceiling: (required), viewer: (nil), width: (1200), row_height: (64), timeout: (5_000 ms). Each fetch runs bounded in a process of its own, so it never blocks or crashes the caller.

fragment(surface)

%{surface: node}: the surface as a fragment.

from_json(json, opts \\ [])

The surface a JSON document holds, read as from_map/2 reads a map, every gate first.

from_map(document, opts \\ [])

The surface a map document holds, or every fault: the version gate first, then the limits (limits: as Macaw.Layers.Document.read/3 takes them) and the migration, then new/1.

new(attrs)

A surface from a keyword list or a map with atom keys: {:ok, surface} or every fault at once, by path from the surface, in the kernel's order.

node(surface)

The surface as its node: its keys, each cell as its map, names that spell one of the document's keys written as that key.

render(validated, env)

Fetches and renders in one call: render(validated, fetch(validated, env), env).

render(validated, fetched, env)

The surface's markup (spec/06 §3.6), a safe value: its title at heading_level: (2), then its cells in reading order, in mode: (:socketless), with theme:, now:, width: and row_height: as for fetching.

to_json(surface)

The JSON document, {:ok, json}, stamped "$version".

to_map(surface)

%{version: current, surface: node}.

validate(surface, registry, sources)

The static pass over a surface (spec/06 §3.4), with the host's registry and its sources by name, each {source, context}: {:ok, %Macaw.Surface.Validated{}} or every fault at once, by path from the surface. No I/O but each source's describe, and no viewer.

Types

t()

@type t() :: %Macaw.Surface{
  cells: %{required(String.t()) => Macaw.Surface.Cell.t()},
  layout: :grid,
  name: String.t(),
  title: String.t() | nil
}

Functions

fetch(validated, env)

@spec fetch(Macaw.Surface.Validated.t(), keyword()) :: %{
  required(String.t()) => map()
}

Each cell's deliveries and drawn state (spec/06 §3.5): %{cell => %{deliveries:, drawn:}}. env: sources: (as given to validate/3), now: and ceiling: (required), viewer: (nil), width: (1200), row_height: (64), timeout: (5_000 ms). Each fetch runs bounded in a process of its own, so it never blocks or crashes the caller.

fragment(surface)

@spec fragment(t()) :: %{surface: map()}

%{surface: node}: the surface as a fragment.

from_json(json, opts \\ [])

@spec from_json(String.t(), keyword()) ::
  {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

The surface a JSON document holds, read as from_map/2 reads a map, every gate first.

from_map(document, opts \\ [])

@spec from_map(term(), keyword()) ::
  {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

The surface a map document holds, or every fault: the version gate first, then the limits (limits: as Macaw.Layers.Document.read/3 takes them) and the migration, then new/1.

new(attrs)

@spec new(keyword() | map()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

A surface from a keyword list or a map with atom keys: {:ok, surface} or every fault at once, by path from the surface, in the kernel's order.

node(surface)

@spec node(t()) :: map()

The surface as its node: its keys, each cell as its map, names that spell one of the document's keys written as that key.

render(validated, env)

@spec render(Macaw.Surface.Validated.t(), keyword()) :: Phoenix.HTML.safe()

Fetches and renders in one call: render(validated, fetch(validated, env), env).

render(validated, fetched, env)

@spec render(Macaw.Surface.Validated.t(), map(), keyword()) :: Phoenix.HTML.safe()

The surface's markup (spec/06 §3.6), a safe value: its title at heading_level: (2), then its cells in reading order, in mode: (:socketless), with theme:, now:, width: and row_height: as for fetching.

to_json(surface)

@spec to_json(t()) :: {:ok, String.t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

The JSON document, {:ok, json}, stamped "$version".

to_map(surface)

@spec to_map(t()) :: %{version: pos_integer(), surface: map()}

%{version: current, surface: node}.

validate(surface, registry, sources)

@spec validate(t(), Macaw.Registry.t(), %{
  required(String.t()) => {Macaw.Data.Source.t(), term()}
}) ::
  {:ok, Macaw.Surface.Validated.t()} | {:error, [Macaw.Layers.Fault.t(), ...]}

The static pass over a surface (spec/06 §3.4), with the host's registry and its sources by name, each {source, context}: {:ok, %Macaw.Surface.Validated{}} or every fault at once, by path from the surface. No I/O but each source's describe, and no viewer.