TermUI.Component behaviour (TermUI v0.2.0)

View Source

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.

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)

Props

Props are passed as a map to the render/2 callback. Use default_props/0 to define defaults that are merged with passed props.

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 - can be a node, list of nodes, or string

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()

Render tree output - can be a node, list of nodes, or string

Callbacks

default_props()

(optional) 
@callback default_props() :: props()

Returns default prop values for the component.

These defaults are merged with props passed to render/2, with passed props taking precedence.

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
  text = props[:text] || ""
  style = props[:style]

  if style do
    styled_text(text, style)
  else
    text(text)
  end
end