LivePanels.Canvas.Placement (livepanels v0.1.0)

Public placement frame companion for the canvas API.

A placement frame is the canonical {space, x, y, w, h, anchor} shape used by the canvas model. :world frames are transformed by the camera; :viewport frames are fixed to the browser viewport layer and interpret x/y as offsets from their placement anchor.

Application-facing APIs such as LivePanels.Canvas.Item.place/3 and LivePanels.Canvas.Item.copy_to/3 accept app_frame/0: :x, :y, :w, and :h are required, while :space and :anchor default to :world and :top_left when omitted. Browser and persistence codecs use the full frame/0 at their boundaries.

Summary

Types

anchor()

app_frame()

frame()

space()

Functions

anchors()

Returns the supported viewport anchoring positions.

default_anchor()

Returns the placement anchor used when callers omit one.

default_space()

Returns the placement space used when callers omit one.

from_item(item)

Projects an item into a placement frame.

normalize_anchor(anchor)

Normalizes a placement anchor from atom or string input.

normalize_anchor(anchor, fallback)

Normalizes a placement anchor or returns the supplied fallback.

normalize_app_frame(raw)

Normalizes an app-facing placement frame.

normalize_space(arg1)

Normalizes a placement space from atom or string input.

normalize_space(space, fallback)

Normalizes a placement space or returns the supplied fallback.

serialize_anchor(anchor)

Serializes a placement anchor for browser and persistence payloads.

serialize_space(space)

Serializes a placement space for browser and persistence payloads.

spaces()

Returns the placement spaces supported by canvas items.

Types

anchor()

@type anchor() ::
  :top_left
  | :top
  | :top_right
  | :right
  | :bottom_right
  | :bottom
  | :bottom_left
  | :left
  | :center

app_frame()

@type app_frame() :: %{
  optional(:space) => space(),
  optional(:anchor) => anchor(),
  x: integer(),
  y: integer(),
  w: pos_integer(),
  h: pos_integer()
}

frame()

@type frame() :: %{
  space: space(),
  x: integer(),
  y: integer(),
  w: pos_integer(),
  h: pos_integer(),
  anchor: anchor()
}

space()

@type space() :: :world | :viewport

Functions

anchors()

@spec anchors() :: [anchor()]

Returns the supported viewport anchoring positions.

default_anchor()

@spec default_anchor() :: anchor()

Returns the placement anchor used when callers omit one.

default_space()

@spec default_space() :: space()

Returns the placement space used when callers omit one.

from_item(item)

@spec from_item(map()) :: frame()

Projects an item into a placement frame.

normalize_anchor(anchor)

@spec normalize_anchor(term()) :: anchor() | nil

Normalizes a placement anchor from atom or string input.

normalize_anchor(anchor, fallback)

@spec normalize_anchor(term(), anchor()) :: anchor()

Normalizes a placement anchor or returns the supplied fallback.

normalize_app_frame(raw)

@spec normalize_app_frame(map()) :: {:ok, frame()} | {:error, atom()}

Normalizes an app-facing placement frame.

Applications may omit :space and :anchor; they default to :world and :top_left. Explicit malformed values still fail clearly.

normalize_space(arg1)

@spec normalize_space(term()) :: space() | nil

Normalizes a placement space from atom or string input.

normalize_space(space, fallback)

@spec normalize_space(term(), space()) :: space()

Normalizes a placement space or returns the supplied fallback.

serialize_anchor(anchor)

@spec serialize_anchor(term()) :: String.t()

Serializes a placement anchor for browser and persistence payloads.

serialize_space(space)

@spec serialize_space(term()) :: String.t()

Serializes a placement space for browser and persistence payloads.

spaces()

@spec spaces() :: [space()]

Returns the placement spaces supported by canvas items.