tui_tui 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7ad8088986ea6e9bc201be5c89597019f4a256de1531f73184e489233752175
-  data.tar.gz: b08cec47d0355748b9fdf732527f29d2ad2cb104ae1e88c0af5c17a9e488f552
+  metadata.gz: 509e482a4d22483da9840ee1ea39021f27f747f2c6919d7782e46f41dbfdfea0
+  data.tar.gz: 731b150add99bd21eafef87e2a33c36679eb5998f01a78bf317217a1c7ee428a
 SHA512:
-  metadata.gz: 4058461db872786a4db951d4b1cd4b789ca7cc5cdfc07eeec8be7c4f2d1290bca30916f2405fe021f870465d74acab0f886128705567aca961346f389a048684
-  data.tar.gz: 3634ec3d3c0da6967adf48af668790559087690e543352a9bb3690d61b435553689e46647cbb13b8619deec409abd19fa95f9bb286d8140baaa1d328237ad114
+  metadata.gz: '068472d5d8dd0c5ae371ffe2516bbe1f1a548d3d55c97e85b898e821640ed6a64b0e8005fa3e8c219c20cfae79e1e86efafbb2f851f7dbbc6830e5ec2e59c455'
+  data.tar.gz: 37e91b9643cc30df3a887e90004859cc37035c52882f353a66148fce585d47c1ba1075af142650fad597e3d34652b9a1983a11f2c19019163740920cff4afadf

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## [0.3.0] - 2026-06-22
+
+### Added
+- `Pager` accepts styled lines for coloring: each line may be a plain `String`,
+  a `Line`, or an array of `Span`s, so a log / diff / error view can color whole
+  lines or runs within them. Unstyled spans fall back to `theme.muted`.
+- `Line.coerce(content, style = nil)`: shared `String` / `Span` / `Span`-array /
+  `Line` → `Line` conversion, used by `List`, `TextView`, and `Pager`.
+- `CommandPalette`: a fuzzy-filtered command palette modal (type to narrow,
+  arrows or Ctrl-N/Ctrl-P to move, Enter to pick, Esc to cancel). Items are
+  arbitrary objects with an optional label block; resolves to the chosen item.
+- Per-frame mouse-reporting toggle: an app may implement `wants_mouse?` and the
+  `Runtime` applies it each frame (via `Screen#mouse=` / `TerminalSession#mouse=`),
+  so it can release the mouse for a native terminal selection and recapture it.
+
+### Fixed
+- Raw mode now keeps the interrupt/quit/suspend characters live (`raw!(intr:
+  true)`), so Ctrl-C raises `SIGINT` (a real force-quit, restored by the INT
+  trap) instead of arriving as a byte.
+
+## [0.2.0] - 2026-06-17
+
+### Added
+- Optional Unicode box-drawing chrome: probed once at startup and used only when
+  the terminal renders it at width 1, else ASCII. Override with `TUITUI_BOX`.
+- `RenderContext` passed to `view` (a `Size`-compatible value with a `canvas`
+  factory); legacy `view(size)` apps keep working.
+- `Rect#include?(row, col)` and `Rect#hit?(mouse_event)` for mouse hit-testing.
+- `List#index_at(rect, event, scrollbar:)` to map a click to a list index,
+  accounting for the scroll offset and the scrollbar gutter.
+- `Theme` semantic status roles — `success` / `warning` / `danger` / `info`
+  (background-aware, hue-independent) — plus `Theme#status(kind)` to map
+  symbolic kinds (`:ok`, `:warn`, `:error`, `:info`, with aliases) to a role.
+- `ModalHost`: a host-side helper that owns the current modal widget, routing
+  `MouseEvent`s to `#handle_mouse` and other events to `#handle`, and running an
+  `on_result` callback when the widget resolves.
+- `auto:` option for `List.draw` / `TextView.draw`: reserve the scrollbar gutter
+  only when the content overflows the rect.
+
+### Fixed
+- Silence the "method redefined; discarding old []" warning from `Span` under
+  `-w` by removing the `Data`-generated `.[]` before redefining the convenience
+  constructor.
+
+## [0.1.0] - 2026-06-16
+
+### Added
+- Initial release: a lightweight, dependency-free (io/console only) TEA-inspired
+  (MVU) TUI toolkit — Canvas with per-cell diffing, Theme, layout `Rect`s,
+  widgets (List, TextView, Scrollbar, StatusBar, Toast, Modal, Confirm, Select,
+  Help, Prompt, Pager, Fuzzy), East-Asian-width-aware text, and a `Runtime`
+  event loop.

data/README.md

@@ -84,17 +84,12 @@ Glyphs are clipped at region edges, not split across them.
 Movement and redraw stay responsive, even with large content.
 Only changed rows are repainted, so cost scales with the change, not the screen size.
 
-#### N7: Width-safe UI chrome (ASCII).
+#### N7: Width-safe UI chrome.
 
-Self-drawn chrome uses only ASCII, color, and spacing.
-ASCII characters have a guaranteed width of 1.
-
-Unicode box-drawing characters are never used.
-Their width can vary under CJK terminal settings and break layouts.
-
-Vertical splits are drawn as a colored one-column gutter.
-Rules are drawn with ASCII `-` or a background fill.
-Selection is drawn with `:reverse`.
+Self-drawn chrome defaults to ASCII, color, and spacing, which have a guaranteed
+width of 1. Unicode box-drawing has an ambiguous width that can break layouts under
+CJK terminal settings, so it is only used when the terminal is confirmed to render
+it at width 1; otherwise the chrome falls back to ASCII.
 
 Content text, such as Japanese data, is measured with `Width`.
 It is clipped or padded to fit the available space.
@@ -105,6 +100,7 @@ Environment variables (all optional):
 
 - `TUITUI_MOUSE` — set to `0`/`off`/`false` to disable mouse reporting (on by default).
 - `TUITUI_BACKGROUND` — `light` or `dark` to pick the theme for your terminal background. Without it, `COLORFGBG` is read if present, otherwise `dark` is assumed (reliable auto-detection isn't possible on all terminals).
+- `TUITUI_BOX` — `ascii` / `unicode` / `auto` to force or auto-detect Unicode box-drawing chrome (default `auto`: used only when the terminal renders it at width 1, else ASCII).
 
 ## Installation
 

data/examples/file_browser.rb

@@ -10,11 +10,11 @@
 #
 # Keys: j/k (or ↑/↓) move, l/Enter/→ open dir, h/←/Backspace up, g/G top/bottom,
 # Tab switch pane, J/K (or mouse wheel) scroll the preview, w wrap, t theme, </> divider, / fuzzy find,
-# y copy the path (OSC 52), m actions menu, ? help, q (or Ctrl-C) quit.
+# y copy the path (OSC 52), : command palette, m actions menu, ? help, q (or Ctrl-C) quit.
 #
 # `/` is an incremental fuzzy finder built on TuiTui::Fuzzy (type to narrow,
 # matched characters highlighted, ↑↓ to navigate, Enter to open, Esc to cancel).
-# The m / ? / q modals are TuiTui widgets (Select, Help, Confirm).
+# The : / m / ? / q modals are TuiTui widgets (CommandPalette, Select, Help, Confirm).
 
 require "strscan"
 require_relative "../lib/tui_tui"
@@ -177,6 +177,7 @@ module FileBrowserSample
     ["t", "cycle theme (cool / warm / mono, follows light/dark)"],
     ["/", "fuzzy find (↑↓ navigate, Enter open, Esc cancel)"],
     ["y", "copy path to clipboard"],
+    [":", "command palette (fuzzy-run any command)"],
     ["m", "actions menu"],
     ["?", "this help"],
     ["q", "quit"],
@@ -184,6 +185,20 @@ module FileBrowserSample
 
   ACTIONS = [["Up to parent", :parent], ["Refresh", :refresh], ["Quit", :quit]].freeze
 
+  # Commands surfaced in the ":" command palette. Each is [label, action]; the
+  # palette ranks by the label and resolves to the chosen pair (see run_command).
+  COMMANDS = [
+    ["Open selected entry", :open],
+    ["Up to parent directory", :parent],
+    ["Refresh listing", :refresh],
+    ["Toggle preview wrap", :wrap],
+    ["Cycle theme", :theme],
+    ["Copy path to clipboard", :copy],
+    ["Fuzzy find", :find],
+    ["Keyboard help", :help],
+    ["Quit", :quit],
+  ].freeze
+
   # The app: responds to view(size) -> Canvas and update(event) -> self | :quit,
   # which is all TuiTui::Runtime asks of it.
   class Browser
@@ -288,8 +303,9 @@ module FileBrowserSample
 
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-    def view(size)
-      canvas = TuiTui::Canvas.blank(size)
+    def view(ctx)
+      size = ctx.size
+      canvas = ctx.canvas
       body, status = split_status(size)
       list_rect, preview_rect = split_panes(body)
       @list_rect = list_rect       # remembered so a click can hit-test the list
@@ -347,13 +363,39 @@ module FileBrowserSample
       end
     end
 
+    def open_help = open_modal(TuiTui::Help.new("Keys", HELP, theme: @theme)) { nil }
+
+    # The ":" command palette: a fuzzy-filtered list of every command. The palette
+    # ranks by the label and resolves to the chosen [label, action] pair (or
+    # :cancel on Esc), which run_command dispatches.
+    def open_palette
+      open_modal(TuiTui::CommandPalette.new(COMMANDS, theme: @theme) { |label, _action| label }) do |chosen|
+        run_command(chosen.last) if chosen.is_a?(Array)
+      end
+    end
+
+    def run_command(action)
+      case action
+      when :open then open_entry
+      when :parent then up_dir
+      when :refresh then load_entries
+      when :wrap then toggle_preview_wrap
+      when :theme then cycle_theme
+      when :copy then copy_path
+      when :find then enter_finder
+      when :help then open_help # palettes can chain into another modal
+      when :quit then :quit
+      end
+    end
+
     # --- input ---
 
     def handle_key(key)
       case key
       when "q", TuiTui::KeyCode::CTRL_C then confirm_quit
-      when "?" then open_modal(TuiTui::Help.new("Keys", HELP, theme: @theme)) { nil }
+      when "?" then open_help
       when "/" then enter_finder
+      when ":" then open_palette
       when "m" then open_actions
       when "l", "\r", :right then open_entry
       when "h", :left, TuiTui::KeyCode::BACKSPACE then up_dir # h / ← / Backspace
@@ -552,10 +594,11 @@ module FileBrowserSample
     # --- drawing ---
 
     # A dim vertical rule in the 1-column gutter between the panes (the column
-    # split_ratio left between list and preview). ASCII "|" (N7), dim like frames.
+    # split_ratio left between list and preview). Follows the canvas chrome:
+    # ASCII "|" by default, "│" when the terminal probed as Unicode-capable.
     def draw_divider(canvas, list_rect)
       col = list_rect.col + list_rect.cols
-      canvas.fill(TuiTui::Rect.new(row: list_rect.row, col: col, rows: list_rect.rows, cols: 1), @styles[:divider], "|")
+      canvas.fill(TuiTui::Rect.new(row: list_rect.row, col: col, rows: list_rect.rows, cols: 1), @styles[:divider], canvas.chrome.v)
     end
 
     def draw_list(canvas, rect)
@@ -629,7 +672,7 @@ module FileBrowserSample
 
     def draw_status(canvas, rect)
       left = @finder ? " > #{@finder}" : " #{@dir}"
-      hints = @finder ? "Esc=cancel  Enter=open" : "?=help  /=find  m=menu  t=#{THEMES[@theme_i]}  q=quit"
+      hints = @finder ? "Esc=cancel  Enter=open" : "?=help  /=find  :=cmds  m=menu  t=#{THEMES[@theme_i]}  q=quit"
       right = "#{@list.cursor + 1}/#{@entries.size}  #{hints} "
       TuiTui::StatusBar.draw(canvas, rect, left: left, right: right, style: @styles[:bar])
     end

data/examples/paint.rb

@@ -160,9 +160,10 @@ module PaintSample
       end
     end
 
-    def view(size)
+    def view(ctx)
+      size = ctx.size
       @rows = size.rows
-      canvas = TuiTui::Canvas.blank(size)
+      canvas = ctx.canvas
       @cells.each do |(row, col), color|
         next unless row.between?(PAINT_TOP, size.rows) && col.between?(1, size.cols)
 

data/examples/widgets.rb

@@ -46,8 +46,9 @@ module WidgetsSample
       end
     end
 
-    def view(size)
-      canvas = TuiTui::Canvas.blank(size)
+    def view(ctx)
+      size = ctx.size
+      canvas = ctx.canvas
       canvas.text(2, 3, "TuiTui widget gallery", @theme.title)
       canvas.text(4, 3, "theme: #{THEMES[@theme_i]}", @theme.accent)
       canvas.text(5, 3, "last result: #{@last}", @theme.text)

data/lib/tui_tui/box_chrome.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # The glyph set used to draw chrome (frame borders, dividers, scrollbar track).
+  BoxChrome = Data.define(:tl, :tr, :bl, :br, :h, :v, :lt, :rt, :tt, :bt, :cross, :track)
+
+  class BoxChrome
+    ASCII = new(
+      tl: "+", tr: "+", bl: "+", br: "+",
+      h: "-", v: "|",
+      lt: "+", rt: "+", tt: "+", bt: "+", cross: "+",
+      track: "|"
+    )
+
+    # Single-line box drawing (U+2500..U+253C).
+    UNICODE = new(
+      tl: "┌", tr: "┐", bl: "└", br: "┘",
+      h: "─", v: "│",
+      lt: "├", rt: "┤", tt: "┬", bt: "┴", cross: "┼",
+      track: "│"
+    )
+
+    # The distinct Unicode glyphs chrome can emit, probed as one string.
+    PROBE_GLYPHS = "─│┌┐└┘├┤┬┴┼"
+
+    # Narrower than this and the probe glyphs would wrap at column 1.
+    MIN_PROBE_COLS = 12
+
+    # Resolve an override string to a chrome, or :auto when a probe is needed.
+    def self.from(name)
+      case name.to_s.downcase
+      when "ascii", "0", "off", "false" then ASCII
+      when "unicode", "1", "on", "true" then UNICODE
+      else :auto
+      end
+    end
+
+    # The capability gate: every probed glyph must render at width 1, so the total
+    # advance equals the glyph count.
+    def self.supported?(total_width)
+      total_width == PROBE_GLYPHS.length
+    end
+
+    # Full resolution given a live console. Honors TUITUI_BOX, else probes; falls
+    # back to ASCII when forced off, the terminal is too narrow, or the probe fails.
+    def self.resolve(input:, output:, term_cols:, env: ENV, prober: BoxProber.new)
+      forced = from(env["TUITUI_BOX"].to_s)
+      return forced unless forced == :auto
+      return ASCII if term_cols < MIN_PROBE_COLS
+
+      supported?(prober.measure_all(input: input, output: output)) ? UNICODE : ASCII
+    end
+  end
+end

data/lib/tui_tui/box_prober.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "box_chrome"
+require_relative "clock"
+
+module TuiTui
+  # Measures how many columns a string of box-drawing glyphs actually occupies on
+  # the live terminal, by printing them and asking for the cursor position (DSR).
+  class BoxProber
+    # Cursor Position Report: ESC [ row ; col R -> capture the column.
+    CPR = /\e\[\d+;(\d+)R/
+    MAX_REPLY_BYTES = 64
+
+    def initialize(glyphs: BoxChrome::PROBE_GLYPHS, timeout: 0.2, wait: nil)
+      @glyphs = glyphs
+      @timeout = timeout
+      @wait = wait || method(:wait_readable)
+    end
+
+    def measure_all(input:, output:)
+      output.write("\r")     # known baseline: column 1
+      output.write(@glyphs)  # advances by the sum of glyph widths
+      output.write("\e[6n")  # DSR: request cursor position
+      output.flush
+      col = read_column(input)
+      cleanup(output)
+      col.nil? ? -1 : col - 1
+    end
+
+    private
+
+    # Wipe the probe line before the first render (the alt screen stays clean).
+    def cleanup(output)
+      output.write("\r\e[K")
+      output.flush
+    end
+
+    def read_column(input)
+      deadline = Clock.monotonic + @timeout
+      buf = +""
+      loop do
+        remaining = deadline - Clock.monotonic
+        break if remaining <= 0
+        break unless @wait.call(input, remaining)
+
+        char = input.getc
+        break if char.nil?
+
+        buf << char
+        if (match = CPR.match(buf))
+          return match[1].to_i
+        end
+        break if buf.bytesize > MAX_REPLY_BYTES
+      end
+      nil
+    end
+
+    def wait_readable(io, timeout) = io.wait_readable(timeout)
+  end
+end

data/lib/tui_tui/canvas.rb

@@ -5,6 +5,7 @@ require_relative "text_sanitizer"
 require_relative "display_text"
 require_relative "style"
 require_relative "cell"
+require_relative "box_chrome"
 
 module TuiTui
   # Pure drawing surface. Coordinates are 1-origin to match terminal cursor
@@ -14,18 +15,20 @@ module TuiTui
     CONTROL_GLYPH = "?"
     FRAME = Style.new(fg: :bright_black)
 
-    def self.blank(size)
-      new(size.rows, size.cols)
+    def self.blank(size, chrome: BoxChrome::ASCII)
+      new(size.rows, size.cols, chrome: chrome)
     end
 
     attr_reader :rows, :cols
     attr_reader :cursor
+    attr_reader :chrome
 
-    def initialize(rows, cols)
+    def initialize(rows, cols, chrome: BoxChrome::ASCII)
       @rows = rows
       @cols = cols
       @grid = Array.new(rows) { Array.new(cols, Cell::BLANK) }
       @cursor = nil
+      @chrome = chrome
     end
 
     def cursor_at(row, col)
@@ -92,14 +95,14 @@ module TuiTui
       text(row, col, char * len, style)
     end
 
-    def frame(rect, style: FRAME)
+    def frame(rect, style: FRAME, chrome: @chrome)
       fill(rect, nil)
-      bar = "+#{"-" * (rect.cols - 2)}+"
-      text(rect.row, rect.col, bar, style)
-      text(rect.row + rect.rows - 1, rect.col, bar, style)
+      mid = chrome.h * (rect.cols - 2)
+      text(rect.row, rect.col, chrome.tl + mid + chrome.tr, style)
+      text(rect.row + rect.rows - 1, rect.col, chrome.bl + mid + chrome.br, style)
       (1...(rect.rows - 1)).each do |dy|
-        text(rect.row + dy, rect.col, "|", style)
-        text(rect.row + dy, rect.col + rect.cols - 1, "|", style)
+        text(rect.row + dy, rect.col, chrome.v, style)
+        text(rect.row + dy, rect.col + rect.cols - 1, chrome.v, style)
       end
 
       self

data/lib/tui_tui/clock.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module TuiTui
+  # The single source of monotonic time, so timers and timeouts never depend on
+  # wall-clock adjustments. Injected as a callable where tests need to control it.
+  module Clock
+    module_function
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/tui_tui/command_palette.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require_relative "display_text"
+require_relative "text_sanitizer"
+require_relative "style"
+require_relative "scroll_list"
+require_relative "list"
+require_relative "line"
+require_relative "span"
+require_relative "rect"
+require_relative "modal"
+require_relative "fuzzy"
+require_relative "key_code"
+
+module TuiTui
+  # Fuzzy-filtered command palette modal (think Ctrl-P): type to narrow a list of
+  # commands, arrows or Ctrl-N/Ctrl-P to move, Enter to pick, Esc to cancel.
+  #
+  # Items are arbitrary objects; pass a block to derive each one's display label
+  # (defaults to #to_s). Resolves to the chosen item on Enter and :cancel on
+  # escape; stays open (nil) while the query has no matches.
+  #
+  #   host.open(CommandPalette.new(commands) { |c| c.title }) { |cmd| cmd.run; self }
+  class CommandPalette < Modal
+    MAX_ROWS = 10
+    MIN_INNER = 28
+    WHEEL = 3
+
+    def initialize(items, prompt: "> ", placeholder: "Type to search…", theme: Theme::DEFAULT, &label)
+      @items = items.to_a
+      @label = label || :to_s.to_proc
+      @prompt = DisplayText.new(prompt)
+      @placeholder = DisplayText.new(placeholder)
+      @theme = theme
+      @graphemes = []
+      @list = ScrollList.new(0)
+      refilter
+    end
+
+    def query = @graphemes.join
+
+    # The original item under the cursor, or nil when nothing matches.
+    def selection = @filtered[@list.cursor]&.first
+
+    def handle(key)
+      case key
+      when "\r"
+        selection
+      when :escape, KeyCode::CTRL_C
+        :cancel
+      when :up, KeyCode::CTRL_P
+        move(-1)
+      when :down, KeyCode::CTRL_N
+        move(1)
+      when :home
+        move_to(0)
+      when :end
+        move_to(@list.last)
+      when KeyCode::BACKSPACE, :backspace
+        edit { @graphemes.pop }
+      when String
+        edit { @graphemes.concat(key.grapheme_clusters) if TextSanitizer.printable?(key) }
+      end
+    end
+
+    # Wheel scrolls the highlight; a click on a row picks it (returns the item),
+    # otherwise nil to stay open.
+    def handle_mouse(event)
+      case event.action
+      when :wheel
+        move(event.button == :wheel_up ? -WHEEL : WHEEL)
+      when :press
+        click(event)
+      end
+    end
+
+    def draw(canvas, size)
+      rows = visible_rows(size)
+      inner = [MIN_INNER, *@filtered.map { |_item, label, _pos| label.width }].max
+      rect, col = panel(canvas, inner: inner, body_rows: rows + 2)
+
+      draw_query(canvas, rect.row + 1, col, inner)
+      draw_items(canvas, rect.row + 3, col, inner, rows)
+      canvas
+    end
+
+    private
+
+    def move(delta)
+      @list.move(delta)
+      nil
+    end
+
+    def move_to(index)
+      @list.go_to(index)
+      nil
+    end
+
+    # Apply a query edit, then refilter. Returns nil so the modal stays open.
+    def edit
+      yield
+      refilter
+      nil
+    end
+
+    # Recompute the visible list: fuzzy-ranked (best first, with matched positions
+    # for highlighting) while querying, otherwise the items in their given order.
+    # Each entry is [item, DisplayText(label), positions]; the cursor resets so a
+    # narrowed query always lands on the top match.
+    def refilter
+      @filtered =
+        if @graphemes.empty?
+          @items.map { |item| [item, label_text(item), []] }
+        else
+          Fuzzy.new(query).rank(@items) { |item| @label.call(item).to_s }
+               .map { |item, found| [item, label_text(item), found.positions] }
+        end
+      @list.count = @filtered.size
+      @list.go_to(0)
+    end
+
+    def label_text(item) = DisplayText.new(@label.call(item).to_s)
+
+    def visible_rows(size)
+      room = [size.rows - 4, 1].max
+      [[@filtered.size, 1].max, MAX_ROWS, room].min
+    end
+
+    def draw_query(canvas, row, col, inner)
+      canvas.text(row, col, @prompt, theme.accent)
+      text_col = col + @prompt.width
+      budget = inner - @prompt.width
+      if @graphemes.empty?
+        canvas.text(row, text_col, @placeholder.truncate(budget), theme.muted)
+      else
+        canvas.text(row, text_col, DisplayText.new(query).truncate(budget), theme.text)
+      end
+    end
+
+    def draw_items(canvas, row, col, inner, rows)
+      @items_rect = Rect.new(row: row, col: col, rows: rows, cols: inner)
+      if @filtered.empty?
+        canvas.text(row, col, DisplayText.new("No matches").truncate(inner), theme.muted)
+        return
+      end
+
+      List.new(@list).draw(canvas, @items_rect, highlight: theme.selection) do |index, focused|
+        _item, label, positions = @filtered[index]
+        base = focused ? theme.selection : theme.text
+        # Keep the focused row a single style; highlight matches with accent only
+        # on unfocused rows so the selection bar stays legible.
+        match = focused ? base : theme.accent
+        styled_line(label.to_s, positions, base, match)
+      end
+    end
+
+    # The label as a Line with matched graphemes in `match` and the rest in `base`;
+    # runs of the same style coalesce into one Span (grapheme indices line up with
+    # Fuzzy#positions).
+    def styled_line(label, positions, base, match)
+      return Line[Span[label, base]] if positions.empty?
+
+      spans = []
+      run = +""
+      run_style = nil
+      label.grapheme_clusters.each_with_index do |grapheme, i|
+        style = positions.include?(i) ? match : base
+        if style != run_style && !run.empty?
+          spans << Span[run, run_style]
+          run = +""
+        end
+        run_style = style
+        run << grapheme
+      end
+      spans << Span[run, run_style] unless run.empty?
+      Line.new(spans)
+    end
+
+    # The item under a click, picked, or nil if the click missed the list.
+    def click(event)
+      return nil unless @items_rect
+
+      index = List.new(@list).index_at(@items_rect, event)
+      return nil if index.nil?
+
+      @list.go_to(index)
+      selection
+    end
+  end
+end

data/lib/tui_tui/key_code.rb

@@ -4,6 +4,9 @@ module TuiTui
   module KeyCode
     ESCAPE = "\e"
     CTRL_C = "\u0003"
+    CTRL_L = "\u000C"
+    CTRL_N = "\u000E"
+    CTRL_P = "\u0010"
     BACKSPACE = "\u007F"
   end
 end

data/lib/tui_tui/line.rb

@@ -10,6 +10,17 @@ module TuiTui
     # Convenience constructor: Line[Span["a", s1], Span["b", s2]].
     def self.[](*spans) = new(spans)
 
+    # Coerce loose content into a Line: a Line passes through, a Span or an Array
+    # of Spans is wrapped, and anything else is one Span (in `style`, when given).
+    def self.coerce(content, style = nil)
+      case content
+      when Line then content
+      when Span then new([content])
+      when Array then new(content)
+      else Line[Span[content.to_s, style]]
+      end
+    end
+
     def initialize(spans = [])
       @spans = spans
     end