Raxol.UI.CellDim (Raxol v2.6.1)

View Source

Cell-level color dimming for content sitting behind an active modal dialog.

Every element type eventually becomes {x, y, char, fg, bg, attrs} cells before paint (Raxol.UI.Renderer), so dimming is implemented once here at that choke point instead of duplicating a "dim" branch in every render_visible_element/3 clause.

Dimming pulls a color's H-K-compensated apparent lightness (via Raxol.UI.Theming.Salience), not its raw RGB channels, toward the detected terminal ground -- naive rgb * factor scaling reads chromatic colors (blues especially) darker than gray at the same nominal scale, and interpolating in apparent-lightness space makes the darken-on-dark-ground / wash-on-light-ground direction fall out of the same formula instead of being hand-branched per theme.

nil fg/bg (never painted) always stays nil. ElementRenderer/ BorderRenderer default every unpainted background to the atom :black (see their resolve_bg/1), so :black is the de facto unpainted-bg sentinel and passes through undimmed for backgrounds -- dim_fg/2 treats a painted fg: :black as a real color and dims it.

Summary

Functions

dim_bg(color, ground_al)

Dims a background color. nil is the unpainted-background sentinel and passes through: there is nothing to dim, and painting one would turn a transparent cell opaque.

dim_cells(cells)

Dims every cell's fg/bg in a list toward the detected terminal ground.

dim_color(color)

Dims a single color value against the detected (or reference-fallback) terminal ground. See dim_color/2 for per-type behavior.

dim_color(color, ground_al)

Dims a single color value against an explicit ground apparent lightness (as returned by ground_apparent_lightness/0). Bg-oriented -- see dim_fg/2 for foregrounds.

dim_fg(color, ground_al)

Dims a foreground color. Same as dim_color/2 except a painted :black is treated as a real color (dimmed), not the bg-only unpainted sentinel -- see moduledoc.

ground_apparent_lightness()

Apparent lightness of the current ground: the OSC 11-detected terminal background when available, else Raxol.UI.Theming.Salience's reference ground.

Functions

dim_bg(color, ground_al)

@spec dim_bg(any(), float()) :: any()

Dims a background color. nil is the unpainted-background sentinel and passes through: there is nothing to dim, and painting one would turn a transparent cell opaque.

dim_cells(cells)

@spec dim_cells([tuple()]) :: [tuple()]

Dims every cell's fg/bg in a list toward the detected terminal ground.

dim_color(color)

@spec dim_color(any()) :: any()

Dims a single color value against the detected (or reference-fallback) terminal ground. See dim_color/2 for per-type behavior.

dim_color(color, ground_al)

@spec dim_color(any(), float()) :: any()

Dims a single color value against an explicit ground apparent lightness (as returned by ground_apparent_lightness/0). Bg-oriented -- see dim_fg/2 for foregrounds.

  • nil stays nil; :black stays :black (bg unpainted sentinel, see moduledoc).
  • Other ANSI-16 atoms resolve to canonical RGB first (unknown atoms, including :default and theme-custom names, resolve to mid-gray).
  • {r, g, b} tuples and "#rrggbb" hex strings dim via OKLCH.
  • Integers (256-color palette indices) pass through unchanged -- there is no general reverse mapping from an index to a hue without inventing one.

dim_fg(color, ground_al)

@spec dim_fg(any(), float()) :: any()

Dims a foreground color. Same as dim_color/2 except a painted :black is treated as a real color (dimmed), not the bg-only unpainted sentinel -- see moduledoc.

ground_apparent_lightness()

@spec ground_apparent_lightness() :: float()

Apparent lightness of the current ground: the OSC 11-detected terminal background when available, else Raxol.UI.Theming.Salience's reference ground.