Minga.Popup.Rule (Minga v0.1.0)

Declarative rule for how a popup buffer should be displayed.

Each rule matches a buffer name (by exact string or regex) and specifies the display mode, positioning, sizing, and behavior. Rules are registered in the Popup.Registry and checked when a buffer is opened.

Display modes

:split — edge-anchored managed pane (Doom Emacs style). The popup appears as a temporary split on one side of the editor, governed by side and size. Closing the popup restores the original layout.
:float — bordered floating panel (Neovim/LazyVim style). The popup appears as an overlay with configurable width, height, position, and border style. Requires the FloatingWindow primitive (#343).

Examples

Popup.Rule.new("*Warnings*", side: :bottom, size: {:percent, 30}, focus: false)

Popup.Rule.new(~r/\*Help/, display: :float, width: {:percent, 60},
  height: {:percent, 70}, border: :rounded, focus: true, auto_close: true)

Summary

Types

border()

Border style for float display mode.

display()

How the popup is rendered.

position()

Popup position for float display mode.

side()

Which edge a split popup anchors to.

size()

Popup size as a percentage of available space or fixed rows/cols.

t()

Functions

matches?(rule, buffer_name)

Returns true if the given buffer name matches this rule's pattern.

new(pattern, opts \\ [])

Creates a new popup rule from a pattern and keyword options.

Types

border()

@type border() :: :rounded | :single | :double | :none

Border style for float display mode.

display()

@type display() :: :split | :float

How the popup is rendered.

position()

@type position() :: :center | {:offset, integer(), integer()}

Popup position for float display mode.

side()

@type side() :: :bottom | :right | :left | :top

Which edge a split popup anchors to.

size()

@type size() :: {:percent, 1..100} | {:rows, pos_integer()} | {:cols, pos_integer()}

Popup size as a percentage of available space or fixed rows/cols.

t()

@type t() :: %Minga.Popup.Rule{
  auto_close: boolean(),
  border: border(),
  display: display(),
  focus: boolean(),
  height: size() | nil,
  modeline: boolean(),
  pattern: Regex.t() | String.t(),
  position: position(),
  priority: integer(),
  quit_key: String.t(),
  side: side(),
  size: size(),
  width: size() | nil
}

Functions

matches?(rule, buffer_name)

@spec matches?(t(), String.t()) :: boolean()

Returns true if the given buffer name matches this rule's pattern.

String patterns match exactly. Regex patterns match anywhere in the name.

new(pattern, opts \\ [])

@spec new(
  Regex.t() | String.t(),
  keyword()
) :: t()

Creates a new popup rule from a pattern and keyword options.

The pattern can be an exact string (e.g. "*Warnings*") or a Regex (e.g. ~r/\*Help/). All other fields are optional and default to a bottom split at 30% height with focus.

Raises ArgumentError if any option is invalid.

Options

:display — :split (default) or :float
:side — :bottom (default), :right, :left, :top (split mode)
:size — {:percent, n} or {:rows, n} / {:cols, n} (split mode, default {:percent, 30})
:width — float mode width (default nil, uses {:percent, 50} when display is :float)
:height — float mode height (default nil, uses {:percent, 50} when display is :float)
:position — :center (default) or {:offset, row, col} (float mode)
:border — :rounded (default), :single, :double, :none (float mode)
:focus — whether opening the popup steals focus (default true)
:auto_close — close when the popup loses focus (default false)
:quit_key — key to dismiss the popup (default "q")
:modeline — show a modeline in the popup (default false, split mode only)
:priority — rule ordering; higher priority wins on conflict (default 0)