Raxol.UI.Components.Base.Component behaviour (Raxol v0.4.0)

View Source

Defines the behavior for UI components in the Raxol system.

This module provides the core structure for building reusable UI components with lifecycle hooks, state management, and event handling. Components follow a similar pattern to the main application architecture but at a smaller scale.

Component Lifecycle

  1. init/1 - Initialize component state with props
  2. mount/1 - Called when the component is first mounted
  3. update/2 - Handle messages and update component state
  4. render/1 - Generate the visual representation of the component
  5. handle_event/2 - Handle UI events
  6. unmount/1 - Clean up resources when component is removed

Example

defmodule MyComponent do
  use Raxol.UI.Components.Base.Component

  def init(props) do
    Map.merge(%{count: 0}, props)
  end

  def mount(state) do
    {state, []}
  end

  def update(:increment, state) do
    %{state | count: state.count + 1}
  end

  def render(state) do
    row do
      button(label: "-", on_click: :decrement)
      text("Count: #{state.count}")
      button(label: "+", on_click: :increment)
    end
  end

  def handle_event({:click, :increment}, state) do
    {update(:increment, state), []}
  end

  def handle_event({:click, :decrement}, state) do
    {%{state | count: state.count - 1}, []}
  end
end

Summary

Callbacks

Handles UI events that occur on the component.

Initializes the component with the given props.

Called when the component is mounted in the UI.

Renders the component based on its current state.

Called when the component is being removed from the UI.

Updates the component state in response to messages.

Types

command()

@type command() :: term()

context()

@type context() :: map()

element()

@type element() :: term()

event()

@type event() :: term()

message()

@type message() :: term()

props()

@type props() :: map()

state()

@type state() :: map()

Callbacks

handle_event(event, state, context)

@callback handle_event(event(), state(), context()) :: {state(), [command()]}

Handles UI events that occur on the component.

The context map provides additional event details or UI state. Returns the potentially modified state and any commands to execute.

init(props)

@callback init(props()) :: state()

Initializes the component with the given props.

Called when the component is created. Should merge default values with the provided props to create the initial state.

mount(state)

(optional)
@callback mount(state()) :: {state(), [command()]}

Called when the component is mounted in the UI.

This is where you can set up subscriptions, execute initial commands, or perform other setup tasks. Returns the potentially modified state and any commands to execute.

render(state, context)

@callback render(state(), context()) :: element()

Renders the component based on its current state.

Returns an element tree that will be rendered to the screen. The context map contains theme, layout constraints, etc.

unmount(state)

(optional)
@callback unmount(state()) :: state()

Called when the component is being removed from the UI.

Use this to clean up any resources or perform final actions.

update(message, state)

@callback update(message(), state()) :: state()

Updates the component state in response to messages.

Similar to the application update function, this handles messages sent to the component and returns the new state.