Component API reference

The optional component layer is loaded with require "zaniah/ui". Components use the same request_layout / prepaint / paint protocol as elements and may be placed directly in an element tree. Builder methods return the component.

require "zaniah/ui"

save = Zaniah::UI::Button.new("Save", variant: :primary, size: :md)
  .icon(:check)
  .on_click { |_event, cx| cx.window.request_frame }

Applications may extend variant tables:

Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
  {background: theme.colors.success, hover: theme.colors.success,
   foreground: theme.colors.text_inverse, border: theme.colors.success}
}

Component reference

All input components are keyboard operable. Disabled controls remain visible but are removed from focus traversal. Overlay components close on Esc; modal overlays restore the previous focus. See TUI for terminal representations.

Calendar and DateRangePicker use Ruby’s Date and ISO 8601 strings. Pass week_start: 0..6 (Sunday is 0) and twelve month_names: to localize the grid without an i18n dependency. A range picker returns a two-element array of dates; its second value is nil while the user is choosing the end. HoverCard accepts an element/component as its anchor to open on pointer hover or keyboard focus, or a Point/Bounds for positioned use. Its delays follow the window’s injected clock.

ZoomPanView uses content-local coordinates for zoom_to and view_to_content. Call fit after the first layout; it scales the content into the current viewport. Native macOS pinch emits Input::Magnify, while Ctrl+wheel provides a desktop fallback.

DockLayout is a validated tree of tab groups and horizontal/vertical splits with stable string IDs. Use DockLayout.tabs and .split to build it, and persist layout.to_h in the application; DockLayout.from_h restores it. DockWorkspace passes the active panel ID to render: and emits a new layout on tab changes. on_detach is a notification only; the application decides whether to open a window and remove the panel. A pointer drop in the outer 20% of a group splits it. PropertyGrid schema entries use key, optional label, type (text, textarea, number, boolean, select, color, date, time), options for select, and an optional Validation. Invalid edits remain in the control while the last valid value is retained. Both components expose terminal fallbacks.

Combobox and CommandPalette default to case-insensitive substring matching in input order. Pass matcher: to either component, or set a default with Zaniah.configure { |config| config.matcher = matcher }. A matcher implements match(query, labels) and returns UI::Matcher::Match values with an original label index, descending score, and half-open UTF-8 byte ranges for highlighting. It may also implement refine(previous_matches, query) for incremental queries. CommandPalette.from(app.actions) uses registered action titles, disables unavailable actions, and displays shortcuts with UI::Kbd. See Menus.

UI::RichText accepts UTF-8 byte ranges at grapheme boundaries. Inline styles are bold, italic, size, color, font, link, underline (:single, :double, :wavy), underline_color, strikethrough, background, baseline (:superscript or :subscript), letter_spacing, ruby: "reading", and combine_upright: true. Ruby parent text is one unbreakable selection cluster; copying omits the annotation, while accessibility and TUI expose it in parentheses. Ruby and combine-upright cannot be set together on one run. writing_mode: :vertical_rl uses top-to-bottom lines and right-to-left columns; text_orientation: :mixed rotates ordinary Latin by default, whereas :upright keeps it upright. Paragraph styles include alignment, lists, levels, indent, quote, background, and before/after spacing. insert_embed(offset, key:, width:, height:) { |cx| element } stores U+FFFC in the text and lays the element out at that inline position. append(text, style:) reuses cached layouts for unchanged earlier fragments. RichText is read-only by default; set editable: true to enable keyboard editing and IME.

UI::CodeEditor keeps the legacy positional constructor and also accepts a line-addressable buffer: with line_count, line(index), line_start(index), line_of(offset), replace(range, text), undo, and redo. A plain string or TextBuffer uses the bundled adapter. Optional highlighter: provides tokens(line_index, text) byte ranges with scopes and receives edited(range, new_text) notifications. Scopes use theme.syntax colors. Only visible logical lines are shaped; wrapped display rows share one line number. The editor supports one caret/selection, standard text actions, IME placement, and Tab indentation. See ADR 020.

Image decoding

Image.from_bytes(bytes) detects PNG, GIF, and baseline JPEG by signature. Pass format: :png, :gif, or :jpeg to choose explicitly. JPEG supports 8-bit baseline grayscale and three-component RGB/YCbCr, JFIF frame dimensions, Exif orientation 1–8, and 4:4:4, 4:2:2, and 4:2:0 sampling. Progressive, CMYK, arithmetic-coded, and multi-scan JPEG files raise JPEG::Error; the default pixel limit is 16,777,216.

Table columns are hashes with key, and optional label, width, sortable, resizable, editable, and render. Tree items accept hashes containing id, label, and either an array or lazy proc in children. A lazy proc receives the item value, runs on first expansion, and is cached after it succeeds; a raised exception leaves it available for retry. A loader can return a placeholder while work runs elsewhere; call replace_children(id, children) on the UI thread to apply the result without changing selection, focus, or expansion. It returns false when the ID is missing or is not lazy. invalidate(id) likewise returns false for missing or non-lazy items; otherwise it discards that lazy result and its loaded descendants so the next expansion calls the loader again. Omit the ID to invalidate all loaded results. replace(items) starts a new source generation, so it never inherits loaded children from the old source. Completed children must be an array with unique, non-nil stable IDs, at most 64 levels deep and 100,000 items total. Invalid results leave the previous children unchanged. Tree rows and accessibility nodes are built only for the current viewport.

In a table, Up/Down/Home/End/Page keys move and select rows, Shift+Up/Down extends a range, and Cmd/Ctrl+A selects every row in multiple-selection mode. Sortable headers and resize handles are separate Tab stops; Enter sorts and arrow/Page keys resize. Grid and Table clipboard hooks receive half-open Grid::Area ranges; Table areas follow the current display order without changing its stable-ID selection. See Layout. Tree views use Up/Down to select, Right to expand or enter the first child, and Left to collapse or return to the parent.