Raxol.LiveView.TerminalBridge (Raxol v2.0.1)

View Source

Converts Raxol.Core buffers to HTML for Phoenix LiveView rendering.

This module provides efficient buffer-to-HTML conversion with performance optimizations for 60fps rendering (< 16ms per frame).

Features

  • Virtual DOM-style diffing (only update changed cells)
  • Character and style caching for performance
  • CSS class generation for theming
  • Inline style support for custom colors
  • Accessibility features (ARIA labels)

Performance

Target: < 16ms per frame for 60fps Actual: ~2-5ms for typical 80x24 buffers

Examples

# Basic conversion
buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)
buffer = Raxol.Core.Buffer.write_at(buffer, 5, 3, "Hello, World!")
html = Raxol.LiveView.TerminalBridge.buffer_to_html(buffer)

# With theme
html = Raxol.LiveView.TerminalBridge.buffer_to_html(buffer, theme: :nord)

# With custom CSS classes
html = Raxol.LiveView.TerminalBridge.buffer_to_html(buffer,
  css_prefix: "terminal",
  use_inline_styles: false
)

Integration with LiveView

defmodule MyAppWeb.TerminalLive do
  use MyAppWeb, :live_view
  alias Raxol.LiveView.TerminalBridge

  def mount(_params, _session, socket) do
    buffer = Raxol.Core.Buffer.create_blank_buffer(80, 24)
    {:ok, assign(socket, buffer: buffer)}
  end

  def render(assigns) do
    ~H"""
    <div class="terminal-container">
      <%= raw(TerminalBridge.buffer_to_html(@buffer, theme: :dracula)) %>
    </div>
    """
  end
end

Summary

Functions

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

Converts a buffer to HTML string.

Converts a style map to CSS classes.

Converts a style map to inline CSS styles.

Types

html_opts()

@type html_opts() :: [
  theme: theme(),
  css_prefix: String.t(),
  use_inline_styles: boolean(),
  show_cursor: boolean(),
  cursor_position: {non_neg_integer(), non_neg_integer()} | nil,
  cursor_style: :block | :underline | :bar
]

theme()

@type theme() ::
  :nord | :dracula | :solarized_dark | :solarized_light | :monokai | :default

Functions

buffer_diff_to_html(old_buffer, new_buffer, opts \\ [])

@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

buffer_to_html(buffer, opts \\ [])

@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)

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>"

style_to_classes(style, css_prefix \\ "raxol")

@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"

style_to_inline(style)

@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);"