TermUI.ComponentServer (TermUI v1.0.0)

View Source

GenServer that manages the lifecycle of a component.

ComponentServer wraps any component implementing TermUI behaviours, managing its lifecycle stages: init, mount, update, and unmount. It handles initialization timeouts, lifecycle callbacks, and its legacy command tuples. It does not render the component and is not automatically started or routed by TermUI.Runtime.

This server invokes init, mount, props-update, event, and unmount callbacks. It does not delegate arbitrary GenServer calls or mailbox messages to a component's optional handle_call/3 or handle_info/2. Its legacy timer tuple schedules a message to the server but, without a custom host, that message is unhandled; {:send, pid, message} is the safe built-in side effect.

Lifecycle Stages

  1. Init - Create initial state from props
  2. Mount - Component enters active tree, ready for events
  3. Update - Props changed, state may update
  4. Unmount - Component removed, cleanup performed

Usage

Components are typically started via ComponentSupervisor:

{:ok, pid} = ComponentSupervisor.start_component(MyButton, %{label: "OK"})

Direct usage:

{:ok, pid} = ComponentServer.start_link(MyButton, %{label: "OK"}, [])

Summary

Types

state()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

child_spec(module, props, opts \\ [])

Returns a child specification for starting a component in a supervisor.

get_lifecycle(pid)

Gets the lifecycle state.

get_props(pid)

Gets the current props.

get_state(pid)

Gets the current component state.

mount(pid)

Triggers the mount lifecycle stage.

register_hook(pid, hook_type, fun)

Registers a lifecycle hook.

send_event(pid, event)

Sends an event to the component.

start_link(module, props, opts \\ [])

Starts a component server.

unmount(pid)

Triggers the unmount lifecycle stage.

update_props(pid, new_props)

Updates the component's props.

Types

state()

@type state() :: %{
  module: module(),
  component_state: term(),
  props: map(),
  lifecycle: :initialized | :mounted | :unmounted,
  id: term(),
  hooks: %{required(atom()) => [function()]},
  recovery: :reset | :last_props | :last_state
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

child_spec(module, props, opts \\ [])

@spec child_spec(module(), map(), keyword()) :: Supervisor.child_spec()

Returns a child specification for starting a component in a supervisor.

get_lifecycle(pid)

@spec get_lifecycle(pid()) :: :initialized | :mounted | :unmounted

Gets the lifecycle state.

get_props(pid)

@spec get_props(pid()) :: map()

Gets the current props.

get_state(pid)

@spec get_state(pid()) :: term()

Gets the current component state.

mount(pid)

@spec mount(pid()) :: :ok | {:error, term()}

Triggers the mount lifecycle stage.

Called when the component is added to the active component tree.

register_hook(pid, hook_type, fun)

@spec register_hook(pid(), atom(), function()) :: :ok

Registers a lifecycle hook.

Hook Types

  • :after_mount - Called after successful mount
  • :before_unmount - Called before unmount cleanup
  • :on_prop_change - Called when props change

send_event(pid, event)

@spec send_event(pid(), term()) :: :ok | {:error, term()}

Sends an event to the component.

start_link(module, props, opts \\ [])

@spec start_link(module(), map(), keyword()) :: GenServer.on_start()

Starts a component server.

Parameters

  • module - Component module
  • props - Initial properties
  • opts - Options (:id, :timeout)

unmount(pid)

@spec unmount(pid()) :: :ok

Triggers the unmount lifecycle stage.

Called when the component is removed from the tree.

update_props(pid, new_props)

@spec update_props(pid(), map()) :: :ok | {:error, term()}

Updates the component's props.

Triggers the update callback if props have changed.