Drawing subsystem for persistent vector items.
Drawing commands still flow through the canonical canvas reducer. This module is the app-facing command/query front door for vector item creation, mutation, removal, and inspection.
Summary
Types
First argument accepted by drawing command helpers.
Functions
Creates a persistent vector item and returns the command result.
Creates a persistent vector item through the canvas command path.
Creates a persistent arrow vector item and returns the command result.
Creates a persistent arrow vector item.
Returns vector kinds backed by a placement box.
Creates a persistent diamond vector item and returns the command result.
Creates a persistent diamond vector item.
Edits a committed vector item and returns the command result.
Edits committed vector item style, text, label, route, arrowheads, or bends.
Creates a persistent ellipse vector item and returns the command result.
Creates a persistent ellipse vector item.
Converts an external drawing document into canonical LivePanels commands.
Flattens committed vector items and returns the command result.
Flattens committed vector items into one persistent drawing item.
Automatically flattens vector items over a threshold and returns the command result.
Automatically flattens vector items when a count threshold is exceeded.
Creates a persistent freehand vector item and returns the command result.
Creates a persistent freehand vector item.
Converts an external drawing document map into normalized drawing payloads.
Imports an external drawing document and returns the command result.
Imports an external drawing document through the normal canvas command path.
Creates a persistent line vector item and returns the command result.
Creates a persistent line vector item.
Returns vector kinds backed by editable points.
Returns true when the item id or item value is a committed point-backed vector item.
Creates a persistent polyline vector item and returns the command result.
Creates a persistent polyline vector item.
Creates a persistent rectangle vector item and returns the command result.
Creates a persistent rectangle vector item.
Removes a committed vector item and returns the command result.
Removes a committed vector item through drawing authorization.
Creates a persistent text vector item and returns the command result.
Creates a persistent text vector item.
Exports committed vector items as an external drawing document map.
Creates a persistent triangle vector item and returns the command result.
Creates a persistent triangle vector item.
Restores a flattened vector item and returns the command result.
Restores a flattened vector item back into its source vector items.
Creates a persistent vector item and returns the command result.
Creates a persistent vector item through the canvas command path.
Returns true when the item id or item value is a committed vector item.
Returns committed vector items from assigned items or a canvas state.
Returns every supported vector kind.
Returns canonical vector state for a committed vector item.
Types
@type command_result() :: LivePanels.Canvas.Command.result()
@type item_ref() :: LivePanels.Item.ref()
@type socket() :: Phoenix.LiveView.Socket.t()
@type target() :: LivePanels.Canvas.command_target()
First argument accepted by drawing command helpers.
Pass a LiveView socket for a standalone command, or a
LivePanels.Canvas.Transaction context inside LivePanels.Canvas.transaction/2.
@type vector_kind() ::
:freehand
| :polyline
| :arrow
| :line
| :rectangle
| :ellipse
| :diamond
| :triangle
| :text
@type vector_source() :: LivePanels.Canvas.State.t() | %{items: %{optional(String.t()) => LivePanels.Item.t()}} | %{optional(String.t()) => LivePanels.Item.t()}
Functions
@spec add(target(), vector_kind(), map(), keyword()) :: command_result()
Creates a persistent vector item and returns the command result.
@spec add!(target(), vector_kind(), map(), keyword()) :: target()
Creates a persistent vector item through the canvas command path.
@spec arrow(target(), map(), keyword()) :: command_result()
Creates a persistent arrow vector item and returns the command result.
Creates a persistent arrow vector item.
@spec box_kinds() :: [vector_kind()]
Returns vector kinds backed by a placement box.
@spec diamond(target(), map(), keyword()) :: command_result()
Creates a persistent diamond vector item and returns the command result.
Creates a persistent diamond vector item.
@spec edit(target(), item_ref(), map() | keyword()) :: command_result()
Edits a committed vector item and returns the command result.
Edits committed vector item style, text, label, route, arrowheads, or bends.
@spec ellipse(target(), map(), keyword()) :: command_result()
Creates a persistent ellipse vector item and returns the command result.
Creates a persistent ellipse vector item.
Converts an external drawing document into canonical LivePanels commands.
Drawn shapes become vector item commands, and arrows with both endpoints bound become graph connector commands with ports on the bound items.
Flattens committed vector items and returns the command result.
Flattens committed vector items into one persistent drawing item.
The flattened item renders as one unit and stores the source vector items as serialized source item records in the flattened item's local coordinate space.
Options:
:id- explicit id for the flattened item.:owner_client_id- only flatten vector items owned by that client.
@spec flatten_over_limit(target(), pos_integer(), keyword() | map()) :: command_result()
Automatically flattens vector items over a threshold and returns the command result.
@spec flatten_over_limit!(target(), pos_integer(), keyword() | map()) :: target()
Automatically flattens vector items when a count threshold is exceeded.
Applications can call this after drawing commits, on a timer, or from their own
workflow hooks. scope may be :all, :owner, :viewport, or :selection.
:viewport uses the current actor viewport when available; :owner uses the
current actor unless :owner_client_id is supplied.
@spec freehand(target(), map(), keyword()) :: command_result()
Creates a persistent freehand vector item and returns the command result.
Creates a persistent freehand vector item.
Converts an external drawing document map into normalized drawing payloads.
Unsupported or malformed elements are ignored. Applications should create the
returned payloads through vector_item/4 so authorization, broadcasts, history, and
persistence stay on the normal canvas command path.
@spec import_excalidraw(target(), map(), keyword()) :: command_result()
Imports an external drawing document and returns the command result.
Imports an external drawing document through the normal canvas command path.
@spec line(target(), map(), keyword()) :: command_result()
Creates a persistent line vector item and returns the command result.
Creates a persistent line vector item.
@spec point_kinds() :: [vector_kind()]
Returns vector kinds backed by editable points.
@spec point_vector_item?( LivePanels.Canvas.State.t(), String.t() | LivePanels.Item.t() ) :: boolean()
Returns true when the item id or item value is a committed point-backed vector item.
@spec polyline(target(), map(), keyword()) :: command_result()
Creates a persistent polyline vector item and returns the command result.
Creates a persistent polyline vector item.
@spec rectangle(target(), map(), keyword()) :: command_result()
Creates a persistent rectangle vector item and returns the command result.
Creates a persistent rectangle vector item.
@spec remove(target(), item_ref()) :: command_result()
Removes a committed vector item and returns the command result.
Removes a committed vector item through drawing authorization.
@spec text(target(), map(), String.t(), keyword()) :: command_result()
Creates a persistent text vector item and returns the command result.
Creates a persistent text vector item.
@spec to_excalidraw( vector_source(), keyword() ) :: map()
Exports committed vector items as an external drawing document map.
The returned map is intentionally not JSON-encoded here; applications can choose how they want to persist or download it without making the drawing subsystem depend on a JSON library.
@spec triangle(target(), map(), keyword()) :: command_result()
Creates a persistent triangle vector item and returns the command result.
Creates a persistent triangle vector item.
@spec unflatten(target(), item_ref()) :: command_result()
Restores a flattened vector item and returns the command result.
Restores a flattened vector item back into its source vector items.
Flattened vector items retain their source item records and can be restored later.
@spec vector_item(target(), vector_kind(), map(), keyword()) :: command_result()
Creates a persistent vector item and returns the command result.
@spec vector_item!(target(), vector_kind(), map(), keyword()) :: target()
Creates a persistent vector item through the canvas command path.
kind is one of vector_kinds/0. placement accepts the app-facing
placement frame shape:
%{
x: 120,
y: 80,
w: 320,
h: 180
}:space and :anchor may be included and default to :world and
:top_left:
%{
space: :world,
anchor: :top_left,
x: 120,
y: 80,
w: 320,
h: 180
}opts accepts :style, :points, optional :id, text state (:text,
:font, :align, :vertical_align), bound :label, and linear vector
presentation (:arrowheads, :route).
@spec vector_item?(LivePanels.Canvas.State.t(), String.t() | LivePanels.Item.t()) :: boolean()
Returns true when the item id or item value is a committed vector item.
@spec vector_items(vector_source()) :: [LivePanels.Item.t()]
Returns committed vector items from assigned items or a canvas state.
@spec vector_kinds() :: [vector_kind()]
Returns every supported vector kind.
@spec vector_state(LivePanels.Item.t() | map()) :: {:ok, map()} | :error
Returns canonical vector state for a committed vector item.
Application-owned drawing renderers use this to add hit areas, point handles, and editing controls while keeping geometry normalization in LivePanels.