@spec animation_css([map()]) :: String.t()

Generates CSS transition rules from animation hints on positioned elements.

Takes a list of positioned element maps (output of LayoutEngine) and extracts animation hints from elements that have an :id field. Returns a <style> block with CSS transition rules targeting [data-raxol-id] selectors, plus a prefers-reduced-motion media query.

Also emits overflow-anchor rules for elements carrying an :overflow_anchor field (:auto or :none) -- the browser-native counterpart to the terminal Viewport component's overflow_anchor scroll-pinning behavior. :auto lets the browser hold scroll position as content grows above the fold (mirrors the terminal's follow-mode / hold semantics); :none opts an element out entirely.

Returns an empty string if no elements carry animation hints or an overflow-anchor setting.

Examples

elements = [
  %{id: "panel", type: :box, animation_hints: [
    %{property: :opacity, duration_ms: 300, easing: :ease_out_cubic, delay_ms: 0}
  ]}
]
css = animation_css(elements)
# => "<style>[data-raxol-id=\"panel\"] { transition: opacity 300ms cubic-bezier(...) 0ms; }\n..."

elements = [%{id: "log", type: :box, overflow_anchor: :auto}]
css = animation_css(elements)
# => "<style>[data-raxol-id=\"log\"] { overflow-anchor: auto; }\n...</style>"

@spec aria_mode_of(String.t()) :: aria_mode()

The :aria_mode a screen rendered by buffer_to_html/2 was rendered in.

A caller that owns the <pre> itself (see buffer_to_rows/2) strips the one buffer_to_html/2 wrote, and the container semantics with it. Reading the mode back off the markup keeps the two in step without a second channel: Raxol.LiveView.TEALive receives the screen as a bare string and has nothing else to learn it from. It previously hardcoded :log, so an app rendering in :application mode had that silently reversed and its screen became a whole-screen live region again -- which is the exact thing :application exists to opt out of, and the failure is audible only to a screen-reader user.

Defaults to :log, matching buffer_to_html/2's own default.

@spec buffer_diff_to_html(Raxol.Core.Buffer.t(), Raxol.Core.Buffer.t(), html_opts()) ::
  String.t()

Converts a buffer to HTML with diff highlighting (for debugging).

Useful for visualizing which cells changed between frames.

Examples

old_buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)
new_buffer = Raxol.Core.Buffer.write_at(old_buffer, 5, 3, "Changed")
html = buffer_diff_to_html(old_buffer, new_buffer)
# Changed cells will have "raxol-diff-changed" class

@spec buffer_to_html(Raxol.Core.Buffer.t(), html_opts()) :: String.t()

Converts a buffer to HTML string.

Options

• :theme - Color theme to use (default: :default)
• :css_prefix - CSS class prefix (default: "raxol")
• :use_inline_styles - Use inline styles instead of classes (default: false)
• :show_cursor - Show cursor indicator (default: false)
• :cursor_position - Cursor position {x, y} (default: nil)
• :cursor_style - Cursor style (default: :block)
• :aria_mode - Coarse container semantics (default: :log). :log wraps the terminal in <pre role="log" aria-live="polite"> so screen readers announce output as it changes. :application emits <pre role="application"> with no live region, so per-element ARIA and a dedicated announcement region drive announcements instead of a whole-screen re-read.
• :a11y_map - id -> accessibility_node map (from Raxol.Core.Accessibility.Projection.by_id/1). Spans whose data-raxol-id matches an entry get per-element ARIA (role/aria-label/aria-disabled/aria-checked/aria-selected/aria-expanded/aria-required).

Examples

buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)
html = buffer_to_html(buffer)
# => "<pre class=\"raxol-terminal\">...</pre>"

html = buffer_to_html(buffer, theme: :nord, show_cursor: true, cursor_position: {5, 3})
# => "<pre class=\"raxol-terminal raxol-theme-nord\">...</pre>"

@spec buffer_to_rows(Raxol.Core.Buffer.t(), html_opts()) :: [row()]

Converts a buffer to a list of addressable rows.

Takes the same options as buffer_to_html/2 and produces the same per-row markup: joining the :html values with "\n" inside that function's <pre> wrapper reproduces its output byte for byte.

Rows exist so a caller can give each one its own DOM node. With the screen as a single string, a LiveView sees one changed dynamic and resends every row on every frame, even when one cell moved.

Ids are "<css_prefix>-row-<y>": stable for a given row across frames, so a DOM patch strategy can key on them, and prefixed so two terminals on one page do not collide.

Examples

buffer = Raxol.Core.Buffer.create_blank_buffer(3, 2)
buffer_to_rows(buffer)
# => [
#      %{id: "raxol-row-0", y: 0, html: "   "},
#      %{id: "raxol-row-1", y: 1, html: "   "}
#    ]

@spec container_attrs(aria_mode()) :: keyword()

Container ARIA attributes for an :aria_mode, as a keyword list.

Public because a caller that renders rows itself owns the <pre> wrapper (see buffer_to_rows/2) and has to emit the same container semantics. Two hand-written copies drift, and the failure mode is a nested or duplicated live region that re-reads the whole screen.

@spec html_to_rows(String.t(), html_opts()) :: [row()]

Splits a screen rendered by buffer_to_html/2 back into buffer_to_rows/2 rows.

The LiveView render backend broadcasts the screen as one already-rendered string, so a LiveView that wants per-row DOM nodes has no buffer to call buffer_to_rows/2 on. This is the exact inverse of the "\n" join, and it leans on the same property that join already leans on: a row's html never contains a newline, because cells hold single graphemes.

Pass the same :css_prefix used to render, or the ids will not match.

@spec style_to_classes(map(), String.t()) :: String.t()

Converts a style map to CSS classes.

Examples

iex> style = %{bold: true, fg_color: :blue}
iex> style_to_classes(style, "raxol")
"raxol-bold raxol-fg-blue"

@spec style_to_inline(map()) :: String.t()

Converts a style map to inline CSS styles.

Examples

iex> style = %{bold: true, fg_color: {255, 0, 0}}
iex> style_to_inline(style)
"font-weight: bold; color: rgb(255, 0, 0);"