Raxol.Effects.BorderBeam (Raxol v2.6.0)

View Source

Animated border beam effect for terminal interfaces.

Creates a traveling glow that orbits around an element's border, mirroring the border-beam React component. Three visual layers:

  1. Beam stroke -- bright colored highlight traveling clockwise
  2. Inner glow -- muted background color inside the border at the beam head
  3. Outer bloom -- dim foreground bleed outside the border at the beam head

Example

beam = BorderBeam.new(color_variant: :ocean, duration_ms: 2000)
beam = BorderBeam.set_bounds(beam, %{x: 5, y: 2, width: 30, height: 10})

# In your tick handler (30 FPS):
beam = BorderBeam.update(beam)
buffer = BorderBeam.apply(beam, buffer)

Configuration

BorderBeam.new(
  size: :full,             # :full | :compact | :line
  color_variant: :colorful, # :colorful | :mono | :ocean | :sunset
  strength: 0.8,           # 0.0-1.0 overall intensity
  duration_ms: 2000,       # ms for one full orbit
  trail_length: 0.25,      # fraction of perimeter the trail covers
  fade_ms: 300,            # fade in/out transition time
  static_colors: false     # disables color cycling when true
)

Summary

Types

bounds()
config()
size()
t()

Functions

apply(effect, buffer)

Renders the three beam layers onto the buffer.

new(opts \\ [])

Creates a new BorderBeam effect with the given options.

set_active(effect, arg2)

Toggles active state with fade transition.

set_bounds(effect, bounds)

Sets the target bounds and computes the perimeter path.

update(effect, now_ms \\ System.monotonic_time(:millisecond))

Updates timing state. Call each frame.

update_config(effect, opts)

Updates config fields. Recomputes perimeter if size changed.

visible?(border_beam)

Returns true if the effect is currently rendering (active or mid-fade).

Types

bounds()

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

config()

@type config() :: %{
  size: size(),
  color_variant: Raxol.Effects.BorderBeam.Colors.variant(),
  strength: float(),
  duration_ms: pos_integer(),
  brightness: float(),
  saturation: float(),
  hue_range: non_neg_integer(),
  border_style: atom(),
  fade_ms: pos_integer(),
  trail_length: float(),
  static_colors: boolean(),
  enabled: boolean()
}

size()

@type size() :: :full | :compact | :line

t()

@type t() :: %Raxol.Effects.BorderBeam{
  active: boolean(),
  bounds: bounds() | nil,
  config: config(),
  fade_start: integer() | nil,
  last_update: integer() | nil,
  perimeter: [{integer(), integer()}],
  started_at: integer() | nil
}

Functions

apply(effect, buffer)

@spec apply(t(), map()) :: map()

Renders the three beam layers onto the buffer.

Layer order: bloom (lowest) -> inner glow -> beam stroke (highest). Only modifies cell styles, never replaces characters.

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new BorderBeam effect with the given options.

set_active(effect, arg2)

@spec set_active(t(), boolean()) :: t()

Toggles active state with fade transition.

set_bounds(effect, bounds)

@spec set_bounds(t(), bounds()) :: t()

Sets the target bounds and computes the perimeter path.

update(effect, now_ms \\ System.monotonic_time(:millisecond))

@spec update(t(), integer()) :: t()

Updates timing state. Call each frame.

update_config(effect, opts)

@spec update_config(
  t(),
  keyword()
) :: t()

Updates config fields. Recomputes perimeter if size changed.

visible?(border_beam)

@spec visible?(t()) :: boolean()

Returns true if the effect is currently rendering (active or mid-fade).