TermUI.Event.Propagation (TermUI v1.0.0)

View Source

Event propagation utilities for the component tree.

Handles bubbling and capturing phases of event propagation. Events bubble up from target to root until handled.

This utility operates on mounted ComponentServer processes registered in the standalone ComponentRegistry. TermUI.Runtime does not call it; the 1.0 Elm runtime sends events only to its root module.

Propagation Phases

  1. Capture - Event travels from root to target (optional)
  2. Target - Event delivered to target component
  3. Bubble - Event travels from target to root (default)

Usage

# Propagate event up through parent chain
Propagation.bubble(event, component_id)

# Build parent chain for propagation
parents = Propagation.get_parent_chain(component_id)

Summary

Types

phase()
propagation_result()

Functions

bubble(event, start_id, opts \\ [])

Bubbles an event up through the parent chain.

capture(event, target_id)

Captures an event down through the parent chain to target.

get_children(component_id)

Gets children of a component.

get_parent_chain(component_id)

Gets the parent chain for a component.

set_parent(component_id, parent_id)

Sets the parent for a component.

stopped?(result)

Checks if an event should stop propagating.

with_phase(event, phase)

Adds metadata about propagation phase to event.

Types

phase()

@type phase() :: :capture | :target | :bubble

propagation_result()

@type propagation_result() :: :handled | :unhandled | :stopped

Functions

bubble(event, start_id, opts \\ [])

@spec bubble(term(), term(), keyword()) :: propagation_result()

Bubbles an event up through the parent chain.

Starts from the given component and propagates up to parents until a component handles the event or the root is reached.

Parameters

  • event - The event to propagate
  • start_id - Component to start bubbling from
  • opts - Options:
    • :skip_start - Skip the starting component (default: false)

Returns

  • :handled - A component handled the event
  • :unhandled - No component handled the event

capture(event, target_id)

@spec capture(term(), term()) :: propagation_result()

Captures an event down through the parent chain to target.

Starts from the root and propagates down to the target component. Each component can intercept before reaching target.

Parameters

  • event - The event to propagate
  • target_id - Target component

Returns

  • :handled - A component handled the event
  • :unhandled - No component handled the event

get_children(component_id)

@spec get_children(term()) :: [term()]

Gets children of a component.

Returns

List of child component ids.

get_parent_chain(component_id)

@spec get_parent_chain(term()) :: [term()]

Gets the parent chain for a component.

Returns list of parent component ids from immediate parent to root.

Example

# If component tree is: root -> container -> button
get_parent_chain(:button)
# => [:container, :root]

set_parent(component_id, parent_id)

@spec set_parent(term(), term() | nil) :: :ok

Sets the parent for a component.

Used to build the component tree for propagation.

Parameters

  • component_id - Child component
  • parent_id - Parent component (or nil for root)

stopped?(result)

@spec stopped?(term()) :: boolean()

Checks if an event should stop propagating.

Events can be marked to stop propagation by returning :stop from handle_event.

with_phase(event, phase)

@spec with_phase(term(), phase()) :: map()

Adds metadata about propagation phase to event.

Parameters

  • event - The event
  • phase - Current propagation phase

Returns

Event with :propagation_phase metadata.