TermUI.Component behaviour (TermUI v1.0.0)

Base behaviour for all TermUI components.

Components are the building blocks of TermUI applications. This behaviour defines the minimal interface that all components must implement.

This is the low-level stateless widget behaviour. The default application runtime expects a root module implementing TermUI.Elm; it does not mount TermUI.Component modules as independent runtime children. Applications normally call a stateless widget's render/2 from the root view/1.

Basic Usage

The simplest component only needs to implement render/2:

defmodule MyApp.Label do
  use TermUI.Component

  @impl true
  def render(props, _area) do
    text(props[:text] || "")
  end
end

Optional Callbacks

Components can also implement:

describe/0 - Returns metadata about the component
default_props/0 - Returns default prop values

Render Tree

The render/2 callback returns a render tree, which can be:

A RenderNode struct
A list of render nodes
A plain string (converted to text node)
A tuple/map node accepted by TermUI.Runtime.NodeRenderer

Props

Props are passed as a map to the render/2 callback. use TermUI.Component defines merge_props/1; call it inside render/2 when you want to merge default_props/0 with caller props. No runtime performs that merge automatically.

Area

The area parameter defines the available space for rendering:

%{x: integer(), y: integer(), width: integer(), height: integer()}

Components should respect these bounds when producing render output.

Summary

Types

component_info()

Component metadata

props()

Component props passed to render

rect()

Available rendering area

render_tree()

Render tree output accepted by the integrated node renderer

Callbacks

default_props()

Returns default prop values for the component.

describe()

Returns metadata about the component.

render(props, rect)

Renders the component given props and available area.

Types

component_info()

@type component_info() :: %{
  name: String.t(),
  description: String.t() | nil,
  version: String.t() | nil
}

Component metadata

props()

@type props() :: map()

Component props passed to render

rect()

@type rect() :: %{x: integer(), y: integer(), width: integer(), height: integer()}

Available rendering area

render_tree()

@type render_tree() ::
  TermUI.Component.RenderNode.t()
  | [render_tree()]
  | String.t()
  | tuple()
  | map()

Render tree output accepted by the integrated node renderer

Callbacks

default_props()

(optional)

@callback default_props() :: props()

Returns default prop values for the component.

These defaults are consumed by the generated merge_props/1 helper, with caller props taking precedence. render/2 must call that helper explicitly.

Examples

@impl true
def default_props do
  %{
    text: "",
    style: nil,
    align: :left
  }
end

describe()

(optional)

@callback describe() :: component_info()

Returns metadata about the component.

Useful for introspection, debugging, and documentation generation.

Examples

@impl true
def describe do
  %{
    name: "Label",
    description: "A simple text display component",
    version: "1.0.0"
  }
end

render(props, rect)

@callback render(props(), rect()) :: render_tree()

Renders the component given props and available area.

This is the only required callback. It receives the component's props and the available rendering area, and must return a render tree.

Parameters

props - Map of properties passed to the component
area - Available rendering area with x, y, width, height

Returns

A render tree (RenderNode, list, or string).

Examples

@impl true
def render(props, _area) do
  props = merge_props(props)
  text(props[:text] || "", props[:style])
end