Raxol.UI.Components.AbsoluteLayer (Raxol v2.6.1)

View Source

Absolute / overlay layer primitive for terminal chrome.

Wraps a flow child with positioned overlays that draw at fixed coordinates inside the layer's available space without consuming layout flow. Use this for screen frames, status rails, breadcrumb borders, and other decorative chrome that must not push or reflow body content.

Element shape

%{
  type: :absolute_layer,
  flow_child: body_element,
  overlays: [
    %{x: 0, y: 0, element: top_border},
    %{x: 0, y: :bottom, element: bottom_border},
    %{x: 0, y: 1, element: left_rail},
    %{x: :right, y: 1, element: right_rail}
  ]
}

Coordinates accept:

  • non-negative integers -- pixel offsets from the layer's top-left corner
  • negative integers -- offsets from the far edge (-1 = last cell)
  • :left / :top -- alias for 0
  • :right -- last column (width - 1)
  • :bottom -- last row (height - 1)
  • :center -- midpoint on the axis (the overlay's own origin lands there; its bounding box is not centered unless it happens to be 1 cell wide/tall)
  • {:center_of, size} -- centers an overlay of known size on that axis, i.e. origin + (length - size) / 2. Use this to actually center a fixed-width/height overlay such as a modal dialog.

Overlays whose resolved coordinates fall outside the layer's space are clipped silently (no cells emitted).

Usage

import Raxol.UI.Components.AbsoluteLayer

def view(model) do
  absolute_layer(
    body(model),
    [
      overlay(0, 0, top_border()),
      overlay(0, :bottom, bottom_border()),
      overlay(0, 1, left_rail()),
      overlay(:right, 1, right_rail())
    ]
  )
end

Summary

Types

axis_coord()
overlay()

Functions

absolute_layer(flow_child, overlays \\ [])

Builds an :absolute_layer element wrapping flow_child with overlays.

dialog_overlay(width, height, element)

Builds a dialog overlay descriptor: element (a width x height surface, e.g. a modal box) centered on both axes via {:center_of, _}, and marked dialog: true.

overlay(x, y, element)

Builds a single overlay descriptor at coordinates {x, y}.

Types

axis_coord()

@type axis_coord() ::
  non_neg_integer()
  | integer()
  | :left
  | :right
  | :top
  | :bottom
  | :center
  | {:center_of, non_neg_integer()}

overlay()

@type overlay() :: %{
  :x => axis_coord(),
  :y => axis_coord(),
  :element => map(),
  optional(:dialog) => boolean()
}

Functions

absolute_layer(flow_child, overlays \\ [])

@spec absolute_layer(map() | nil, [overlay()]) :: map()

Builds an :absolute_layer element wrapping flow_child with overlays.

Either argument may be nil / [] -- a layer with neither flow nor overlays is a no-op but is still valid.

dialog_overlay(width, height, element)

@spec dialog_overlay(non_neg_integer(), non_neg_integer(), map()) :: overlay()

Builds a dialog overlay descriptor: element (a width x height surface, e.g. a modal box) centered on both axes via {:center_of, _}, and marked dialog: true.

The :dialog marker tells the layout engine to dim every element the layer's flow content produces (pulling painted fg/bg toward the background) while leaving this overlay's own cells at full color -- the "dialog active" / "inside active dialog" pair described in Raxol.UI.Layout.Engine's :absolute_layer handling.

overlay(x, y, element)

@spec overlay(axis_coord(), axis_coord(), map()) :: overlay()

Builds a single overlay descriptor at coordinates {x, y}.