Terminal ANSI escape sequences: colors (Ansi.Color), styles (Ansi.Style), and attributes (Ansi.Attr).

Border character sets for box-drawing. Provides Border.single, Border.rounded, Border.heavy, Border.double, and Border.ascii.

Input event types for keyboard, mouse, and paste events.

Mutable cell-level drawing surface.

The type for 2-dimensional sizes. See size and size_wh.

The type for axis-aligned rectangles with four edges. See padding, margin, and inset.

The type for 2-dimensional points.

The type for line segments with start and end values. Used by Grid.line_range and Grid.span_range for grid placement.

The type for CSS dimensions: a fixed length, a percentage, or auto. Create values with px, pct, or auto.

The type for CSS length-or-percentage values. Produced by helpers such as padding, gap, and gap_xy.

The type for CSS length-or-percentage-or-auto values. Produced by helpers such as margin, margin_xy, and inset.

A contiguous run of text with a single visual style. Used by code for syntax highlighting via its ~spans argument.

CSS display property controlling box generation and child layout algorithm.

CSS position property controlling normal flow participation.

CSS box-sizing property.

CSS overflow property.

CSS text-align property for block layout.

CSS flex-direction property.

CSS flex-wrap property.

Alignment along the cross/block axis (align-items, align-self, justify-items, justify-self).

Distribution of space between and around content items (align-content, justify-content).

CSS grid-auto-flow property.

Grid layout constructors for defining tracks and placing items.

Companion types for the select widget.

Companion types for the tab_select widget.

Companion types for the table widget.

Companion types for the tree widget.

Companion types for the spinner widget.

Companion types for the slider widget.

Companion types for the scroll_bar widget.

Companion types for the text and code widgets.

Companion types for the line_number widget.

Companion types for the markdown widget.

Syntax themes: maps capture-group names to terminal styles.

The type for view nodes parameterized by message type 'msg. Event handlers embedded in a node return 'msg option: Some msg dispatches the message into the update loop; None ignores the event.

Build values of this type with the element constructors (box, text, input, etc.) and compose them with fragment.

map f view is view with every message transformed by f.

Use map to embed a child component whose message type differs from the parent's.

Side-effects issued by the application.

Ongoing event interests declared by the application.

The type for a Mosaic application. Provide a value of this type to run.

run ?matrix ?process_perform app starts app and blocks until the application exits (via Cmd.quit or an OS signal).

• matrix -- the low-level terminal backend. Defaults to a backend with target_fps = Some 60. and a hidden cursor.
• process_perform -- controls how Cmd.t.Perform callbacks are executed. Receives a thunk that wraps the user callback with the dispatch function already wired in. The default spawns a native Thread per callback so that long-running operations (e.g. HTTP requests) never block the UI loop.

Eio integration. Pass a matrix and process_perform built with the matrix_eio library:

  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let matrix =
    Matrix_eio.create ~sw ~clock:(Eio.Stdenv.clock env) ~stdin:env#stdin
      ~stdout:env#stdout ()
  in
  let process_perform thunk =
    Eio.Fiber.fork_daemon ~sw (fun () ->
        thunk ();
        `Stop_daemon)
  in
  Mosaic.run ~matrix ~process_perform { init; update; view; subscriptions }

Daemon fibers are cancelled when the switch completes, so long-running perform operations do not block application shutdown.

px n is a dimension of exactly n terminal columns or rows.

pct n is a dimension of n percent of the parent's available space.

auto is the automatic dimension, letting the layout engine determine the size.

size ~width ~height is a fixed size with the given width and height measured in terminal cells.

size_wh w h is a size with the given w width and h height dimensions.

gap n is a uniform gap of n cells applied to both axes of a flex or grid container.

gap_xy x y is a gap of x cells on the horizontal axis and y cells on the vertical axis.

padding n is a uniform padding of n cells on all four sides.

padding_xy x y is padding of x cells on the left and right sides and y cells on the top and bottom sides.

padding_lrtb l r t b is padding of l cells on the left, r on the right, t on the top, and b on the bottom.

margin n is a uniform margin of n cells on all four sides.

margin_xy x y is margin of x cells on the left and right sides and y cells on the top and bottom sides.

margin_lrtb l r t b is margin of l cells on the left, r on the right, t on the top, and b on the bottom.

inset n is a uniform inset of n cells on all four sides, used with position = `Absolute or position = `Fixed.

inset_lrtb l r t b is inset of l cells on the left, r on the right, t on the top, and b on the bottom.

empty is the empty view that renders nothing and occupies no space. Useful as a placeholder.

fragment views groups views into a single view node without introducing a wrapping container element. Layout is applied to each child independently within the parent.

embed r wraps a pre-rendered Mosaic_ui.Renderable.t as a view node. Use this to integrate non-TEA rendering into the view tree.

box children is a generic container element that lays out children according to the common layout arguments (see UI elements).

Box-specific optional arguments:

• border -- when true draws a border using border_style. Defaults to false.
• border_style -- the border character set. Defaults to Border.single.
• border_sides -- which sides to draw. Defaults to all four.
• border_color -- color of the border when unfocused. Defaults to white.
• focused_border_color -- color of the border when the element has focus. Defaults to bright cyan.
• background -- background fill color. Defaults to transparent.
• fill -- when true fills the background over the entire allocated area. Defaults to true.
• title -- text drawn in the top border. Has no effect when border is false.
• title_alignment -- alignment of title within the top border. Defaults to `Left.

text s is a text element that renders the string s.

Text-specific optional arguments:

• style -- ANSI style applied to the whole element. Defaults to Ansi.Style.default.
• text_style -- ANSI style applied to the text content only, composing with style. Defaults to Ansi.Style.default.
• wrap -- line-wrapping mode. Defaults to `None.
• selectable -- when true the user can select text with the mouse. Defaults to true.
• selection_bg -- background color of selected text. Defaults to the terminal default.
• selection_fg -- foreground color of selected text. Defaults to the terminal default.
• tab_width -- number of cells a tab character expands to. Defaults to 2.
• truncate -- when true clips content that overflows the allocated area instead of wrapping. Defaults to false.

slider () is an interactive range slider.

Slider-specific optional arguments:

• orientation -- `Horizontal or `Vertical. Defaults to `Horizontal.
• value -- current thumb position. Defaults to 0..
• min -- minimum value of the range. Defaults to 0..
• max -- maximum value of the range. Defaults to 1..
• viewport_size -- size of the visible viewport relative to the total range; used to size the thumb proportionally.
• track_color -- color of the slider track.
• thumb_color -- color of the slider thumb.
• on_value_change -- callback fired when the value changes; receives the new value and returns an optional message.

input () is a single-line text input field.

See textarea for the multi-line variant.

Input-specific optional arguments:

• value -- current content of the field. Defaults to "".
• cursor -- optional controlled cursor grapheme offset.
• selection -- optional controlled selection range.
• placeholder -- hint text shown when the field is empty. Defaults to "".
• max_length -- maximum number of characters accepted. Defaults to 1000.
• text_color -- foreground color of the text. Defaults to white.
• background_color -- background color of the field. Defaults to the terminal default.
• focused_text_color -- foreground color when focused. Defaults to white.
• focused_background_color -- background color when focused. Defaults to the terminal default.
• placeholder_color -- color of the placeholder text. Defaults to bright black (dark gray).
• selection_color -- background color of selected text. Defaults to blue.
• selection_fg -- foreground color of selected text. Defaults to the terminal default.
• cursor_style -- cursor shape: `Block, `Line, or `Underline. Defaults to `Block.
• cursor_color -- color of the cursor. Defaults to white.
• cursor_blinking -- when true the cursor blinks. Defaults to true.
• on_input -- fired on every keystroke; receives the full current value after the change.
• on_change -- fired when the value changes after editing; semantics may differ from on_input depending on the component.
• on_submit -- fired when the user presses Enter; receives the current value.
• on_cursor -- fired when cursor position or selection changes.

select items is a vertical list from which the user can choose one item.

See tab_select for a horizontal tab-bar variant.

Select-specific optional arguments:

• selected_index -- zero-based index of the highlighted item. Defaults to 0.
• background -- background color of unselected items.
• text_color -- foreground color of unselected items.
• focused_background -- background when the widget has focus.
• focused_text_color -- foreground when the widget has focus.
• selected_background -- background of the selected item.
• selected_text_color -- foreground of the selected item.
• description_color -- color of item description text.
• selected_description_color -- description color for the selected item.
• show_description -- when true shows item descriptions. Defaults to true.
• show_scroll_indicator -- when true shows a scroll indicator when the list overflows. Defaults to false.
• wrap_selection -- when true wraps the selection from the last item back to the first and vice versa. Defaults to false.
• item_spacing -- number of blank lines between items. Defaults to 0.
• fast_scroll_step -- number of items skipped per fast-scroll action (e.g. Page Down). Defaults to 5.
• on_change -- fired when the highlighted index changes; receives the new index.
• on_activate -- fired when the user confirms the selection (e.g. by pressing Enter); receives the confirmed index.

tab_select items is a horizontal tab-bar selector.

See select for the vertical list variant.

Tab-select-specific optional arguments:

• selected -- zero-based index of the active tab. Defaults to 0.
• tab_width -- fixed width for each tab in cells. Defaults to 12.
• background -- background color of inactive tabs.
• text_color -- foreground color of inactive tabs.
• focused_background -- background when the widget has focus.
• focused_text_color -- foreground when the widget has focus.
• selected_background -- background of the active tab.
• selected_text_color -- foreground of the active tab.
• description_color -- color of tab description text.
• selected_description_color -- description color for the active tab.
• show_underline -- when true draws an underline below tabs. Defaults to true.
• show_description -- when true shows tab descriptions. Defaults to false.
• show_scroll_arrows -- when true shows arrows when tabs overflow the available width. Defaults to true.
• wrap_selection -- when true wraps from the last tab to the first and vice versa. Defaults to false.
• on_change -- fired when the active tab index changes.
• on_activate -- fired when the user confirms the tab selection.

canvas draw is a free-form drawing surface. draw c ~delta is called on every frame with a fresh Canvas.t c and the elapsed time delta in seconds since the previous frame. The canvas fills its allocated layout area.

Canvas-specific optional arguments:

• respect_alpha -- when true the canvas composites with alpha blending. Defaults to true.

spinner () is an animated activity indicator.

Spinner-specific optional arguments:

• frame_set -- the animation frame sequence. Defaults to Spinner.dots.
• color -- foreground color of the spinner character. Defaults to white.

progress_bar () is a read-only progress indicator.

Progress-bar-specific optional arguments:

• value -- current progress value. Defaults to 0..
• min -- value representing 0% progress. Defaults to 0..
• max -- value representing 100% progress. Defaults to 1..
• orientation -- `Horizontal or `Vertical. Defaults to `Horizontal.
• filled_color -- color of the filled portion of the bar. Defaults to medium gray.
• empty_color -- color of the unfilled portion of the bar. Defaults to dark gray.

scroll_bar () is a standalone scroll-bar widget. Use this when you manage scroll state externally; for automatic scrolling consider scroll_box instead.

Scroll-bar-specific optional arguments:

• orientation -- `Horizontal or `Vertical. Defaults to `Vertical.
• show_arrows -- when true renders arrow buttons at each end. Defaults to false.
• track_color -- color of the scroll track. Defaults to dark gray.
• thumb_color -- color of the scroll thumb. Defaults to medium gray.
• arrow_fg -- foreground color of the arrow buttons. Defaults to white.
• arrow_bg -- background color of the arrow buttons. Defaults to the terminal default.
• on_change -- fired when the scroll position changes; receives the new position in scroll units.

scroll_box children is a scrollable container. It clips its children to the allocated area and manages scroll state internally.

Scroll-box-specific optional arguments:

• scroll_x -- when true enables horizontal scrolling. Defaults to false.
• scroll_y -- when true enables vertical scrolling. Defaults to true.
• sticky_scroll -- when true the viewport follows new content appended at the sticky edge. Defaults to false.
• sticky_start -- the edge to which sticky scrolling anchors. Defaults to `Bottom.
• background -- background fill color of the scroll area.
• on_scroll -- fired after a scroll event; receives the new scroll position ~x and ~y in cells.

textarea () is a multi-line text editing area. It shares its optional argument set with input; see that entry for argument descriptions.

Textarea-specific optional arguments not present on input:

• cursor -- optional controlled cursor grapheme offset.
• selection -- optional controlled selection range.
• spans -- optional styled spans used for syntax highlighting. When provided, the span text must match value.
• ghost_text -- optional inline ghost completion rendered at the cursor.
• ghost_text_color -- color used for ghost_text.
• wrap -- line-wrapping mode within the editing area. Defaults to the surface default.
• on_cursor -- fired when cursor position or selection changes.

code s is a read-only code display element that renders s with optional syntax highlighting spans.

Wrap with line_number to add a gutter with line numbers.

Code-specific optional arguments:

• spans -- list of span values that apply syntax-highlighting styles to ranges of the text.
• text_style -- base ANSI style applied to unstyled text.
• wrap -- line-wrapping mode. Defaults to no wrap.
• tab_width -- number of cells a tab character expands to. Defaults to 4.
• selectable -- when true the user can select text with the mouse. Defaults to true.
• selection_bg -- background color of selected text.
• selection_fg -- foreground color of selected text.
• on_selection -- fired when the current selection changes.

line_number child wraps child with a gutter that displays line numbers alongside each line of child's content. Commonly used with code or textarea as the child.

Line-number-specific optional arguments:

• fg -- foreground color of the line-number gutter.
• bg -- background color of the line-number gutter.
• min_width -- minimum width of the gutter in cells. Widens automatically as the line count grows. Defaults to 3.
• padding_right -- cells of padding between the gutter and the content. Defaults to 1.
• show_line_numbers -- when false hides the numeric labels but keeps the gutter structure. Defaults to true.
• line_number_offset -- added to each displayed line number. Useful when the content is a slice of a larger document. Defaults to 0.
• line_colors -- per-line foreground color overrides, given as (line_index, color) pairs.
• line_signs -- per-line sign icons shown in the gutter, given as (line_index, sign) pairs.
• hidden_line_numbers -- line indices whose number labels are suppressed.

markdown s is a rendered Markdown view of the string s.

Markdown-specific optional arguments:

• md_style -- theme controlling heading, code, and emphasis colors. Defaults to the built-in style.
• conceal -- when true hides Markdown syntax characters (asterisks, backticks, etc.) from the rendered output. Defaults to false.
• streaming -- when true the renderer tolerates incomplete Markdown (e.g. an unclosed code fence) as it arrives from a streaming source. Defaults to false.

table () is a scrollable data table.

Table-specific optional arguments:

• columns -- column definitions (Table.column), including headers and sizing. Defaults to [].
• rows -- table data as a list of cell arrays. Each array must have the same length as columns. Defaults to [].
• selected_row -- zero-based index of the highlighted row. Defaults to 0.
• border -- when true draws an outer border. Defaults to true.
• border_style -- character set for the outer border. Defaults to Border.single.
• show_header -- when true renders a header row. Defaults to true.
• show_column_separator -- when true draws vertical lines between columns. Defaults to false.
• show_row_separator -- when true draws horizontal lines between rows. Defaults to false.
• cell_padding -- horizontal padding in cells within each cell. Defaults to 0.
• header_color -- foreground color of the header row.
• header_background -- background color of the header row.
• text_color -- foreground color of body cells.
• background -- background color of body cells.
• selected_text_color -- foreground of the selected row.
• selected_background -- background of the selected row.
• focused_selected_text_color -- foreground of the selected row when the table has focus.
• focused_selected_background -- background of the selected row when the table has focus.
• row_styles -- repeating list of styles applied to body rows, useful for alternating row colors.
• wrap_selection -- when true wraps selection past the last or first row. Defaults to false.
• fast_scroll_step -- rows skipped per fast-scroll action. Defaults to 5.
• on_change -- fired when the selected row index changes.
• on_activate -- fired when the user confirms the selected row (e.g. by pressing Enter).

tree () is an interactive collapsible tree view.

Tree-specific optional arguments:

• items -- the root-level Tree.item nodes. Defaults to [].
• selected_index -- zero-based flat index of the highlighted item. Defaults to 0.
• expand_depth -- number of levels expanded on first render. 0 collapses all; use max_int to expand everything. Defaults to 0.
• indent_size -- cells of indentation per nesting level. Defaults to 2.
• show_guides -- when true draws vertical guide lines. Defaults to false.
• guide_style -- border character set used for guide lines.
• expand_icon -- string shown next to collapsible nodes when collapsed. Defaults to "▶".
• collapse_icon -- string shown next to collapsible nodes when expanded. Defaults to "▼".
• leaf_icon -- string shown next to leaf nodes. Defaults to " ".
• background -- background color of unselected items.
• text_color -- foreground color of unselected items.
• selected_background -- background of the selected item.
• selected_text_color -- foreground of the selected item.
• focused_selected_background -- background of the selected item when the widget has focus.
• focused_selected_text_color -- foreground of the selected item when the widget has focus.
• guide_color -- color of the vertical guide lines.
• icon_color -- color of the expand/collapse/leaf icons.
• wrap_selection -- when true wraps selection past the last or first visible item. Defaults to false.
• fast_scroll_step -- items skipped per fast-scroll action. Defaults to 5.
• on_change -- fired when the selected index changes.
• on_activate -- fired when the user confirms the selection.
• on_expand -- fired when a node is expanded or collapsed; receives the flat index and true if expanded, false if collapsed.

The virtual-DOM reconciler used by run.