thaum 0.1.0 → 0.2.0

data/examples/status_bar.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/status_bar.rb
+#
+# Demonstrates Thaum::StatusBar. Three segments along the bottom:
+# - "Ready"          (plain)
+# - clock            (plain, updates each tick)
+# - "[ Quit ]"       (clickable — exits the app)
+#
+# Click the Quit segment with the mouse, or press esc.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class Body
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    inner = canvas.border(fg: theme.border, style: :rounded)
+    inner.text(content: " StatusBar demo", y: 1, fg: theme.fg)
+    inner.text(content: " Click [ Quit ] in the bar, or press esc.", y: 3, fg: theme.info_fg)
+  end
+end
+
+class StatusBarApp
+  include Thaum::App
+
+  def initialize
+    @body = Body.new
+    @bar  = Thaum::StatusBar.new(segments: segments)
+  end
+
+  def theme = Thaum::Themes::CATPPUCCIN_MOCHA
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def on_tick(_event)
+    new_segments = segments
+    @bar.segments = new_segments
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @body }
+      region(height: 1)     { @bar }
+    end
+  end
+
+  private
+
+  def segments
+    [
+      "Ready",
+      Time.now.strftime("%H:%M:%S"),
+      { label: "[ Quit ]", on_click: -> { quit } }
+    ]
+  end
+end
+
+Thaum.run(StatusBarApp.new)

data/examples/stopwatch.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/stopwatch.rb
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class StopwatchSigil
+  include Thaum::Sigil
+
+  def initialize
+    @elapsed = 0.0
+    @running = false
+  end
+
+  def on_key(event)
+    case event.key
+    when " " then @running = !@running
+    when "r" then @elapsed = 0.0
+    else emit(event)
+    end
+  end
+
+  def on_tick(event)
+    return unless @running
+
+    @elapsed += event.delta
+    request_render
+  end
+
+  def render(canvas:, theme:)
+    mid = canvas.height / 2
+    canvas.fill(bg: theme.bg)
+    canvas.text(content: format_time, fg: @running ? theme.accent : theme.fg, align: :center, y: mid - 1)
+    hint = @running ? "space pause  r reset  t theme  esc quit" : "space start  r reset  t theme  esc quit"
+    canvas.text(content: hint, fg: theme.dim, align: :center, y: mid + 1)
+  end
+
+  private
+
+  def format_time
+    minutes = (@elapsed / 60).to_i
+    seconds = (@elapsed % 60).to_i
+    centis  = ((@elapsed * 100) % 100).to_i
+    format("%<m>02d:%<s>02d.%<c>02d", m: minutes, s: seconds, c: centis)
+  end
+end
+
+class StopwatchApp
+  include Thaum::App
+
+  THEME_CYCLE = %i[catppuccin_mocha gruvbox_dark nord dracula solarized_dark catppuccin_latte].freeze
+
+  def initialize
+    @stopwatch   = StopwatchSigil.new
+    @theme_index = 0
+  end
+
+  # Thaum.run reads this fresh every frame; swapping the index and requesting
+  # a render is all that's needed to retheme the whole app.
+  def theme = Thaum::Themes[THEME_CYCLE[@theme_index]]
+
+  def on_key(event)
+    case event.key
+    when :escape then quit
+    when "t" then cycle_theme
+    end
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @stopwatch }
+    end
+  end
+
+  private
+
+  def cycle_theme
+    @theme_index = (@theme_index + 1) % THEME_CYCLE.length
+    request_render
+  end
+end
+
+Thaum.run(StopwatchApp.new, tick: 0.05)

data/examples/table.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/table.rb
+#
+# Demonstrates Thaum::Table. Auto-computed column widths, vertical
+# scrolling, row selection. Enter prints the selected row after exit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+HEADERS = %w[Name Size Type Modified].freeze
+
+ROWS = [
+  ["CLAUDE.md",        "1.2K",  "doc",   "2026-05-27"],
+  ["DECISIONS.md",     "8.4K",  "doc",   "2026-06-10"],
+  ["Gemfile",          "237B",  "ruby",  "2026-05-27"],
+  ["LICENSE.txt",      "1.1K",  "text",  "2026-05-27"],
+  ["README.md",        "412B",  "doc",   "2026-05-27"],
+  ["Rakefile",         "188B",  "ruby",  "2026-05-27"],
+  ["bin/console",      "187B",  "ruby",  "2026-05-27"],
+  ["bin/setup",        "133B",  "ruby",  "2026-05-27"],
+  ["examples/counter.rb", "1.1K", "ruby", "2026-05-31"],
+  ["examples/layout_demo.rb", "2.3K", "ruby", "2026-06-04"],
+  ["examples/picker.rb",     "3.6K",  "ruby",  "2026-06-15"],
+  ["examples/stopwatch.rb",  "1.9K",  "ruby",  "2026-06-02"],
+  ["examples/theme_picker.rb", "2.0K", "ruby", "2026-06-10"],
+  ["examples/todo.rb", "5.4K", "ruby", "2026-06-09"],
+  ["lib/thaum.rb", "4.7K", "ruby", "2026-06-15"],
+  ["lib/thaum/action.rb",    "1.4K",  "ruby",  "2026-06-04"],
+  ["lib/thaum/app.rb",       "2.9K",  "ruby",  "2026-06-10"],
+  ["lib/thaum/buffer.rb",    "1.6K",  "ruby",  "2026-06-02"],
+  ["lib/thaum/canvas.rb",    "5.1K",  "ruby",  "2026-06-10"],
+  ["lib/thaum/color.rb",     "3.3K",  "ruby",  "2026-06-08"],
+  ["lib/thaum/escape_parser.rb", "4.2K", "ruby", "2026-06-02"],
+  ["lib/thaum/events.rb",    "418B",  "ruby",  "2026-06-10"],
+  ["lib/thaum/layout.rb",    "3.7K",  "ruby",  "2026-06-04"],
+  ["lib/thaum/renderer.rb",  "4.5K",  "ruby",  "2026-06-08"],
+  ["lib/thaum/sigil.rb",     "1.1K",  "ruby",  "2026-06-04"],
+  ["lib/thaum/sigils/button.rb", "744B", "ruby", "2026-06-05"],
+  ["lib/thaum/sigils/scroll_view.rb", "2.6K", "ruby", "2026-06-15"],
+  ["lib/thaum/sigils/select.rb",    "1.1K",  "ruby", "2026-06-05"],
+  ["lib/thaum/sigils/table.rb",     "3.9K",  "ruby", "2026-06-15"],
+  ["lib/thaum/sigils/text.rb",      "316B",  "ruby", "2026-06-04"],
+  ["lib/thaum/sigils/text_input.rb", "1.7K", "ruby", "2026-06-15"],
+  ["lib/thaum/themes.rb", "2.8K", "ruby", "2026-06-10"]
+].freeze
+
+class Hint
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(content: " ↑/↓ navigate   pgup/pgdn jump   home/end edges   enter picks   esc quits",
+                fg: theme.muted_fg)
+  end
+end
+
+class FileTable
+  include Thaum::Sigil
+
+  PAGE_STEP = 10
+
+  attr_reader :rows, :cursor, :offset
+
+  def initialize(headers:, rows:)
+    @headers = headers
+    @rows    = rows
+    @cursor  = 0
+    @offset  = 0
+  end
+
+  SelectedEvent = Thaum::Event.define(:index, :row)
+
+  def on_key(event)
+    case event.key
+    when :up        then @cursor = [@cursor - 1, 0].max
+    when :down      then @cursor = [@cursor + 1, rows.length - 1].min if rows.any?
+    when :home      then @cursor = 0
+    when :end       then @cursor = rows.length - 1 if rows.any?
+    when :page_up   then @cursor = [@cursor - PAGE_STEP, 0].max
+    when :page_down then @cursor = [@cursor + PAGE_STEP, rows.length - 1].min if rows.any?
+    when :enter     then emit_selected
+    else                 emit event
+    end
+  end
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    visible_offset(canvas)
+
+    render_header(canvas: canvas, theme: theme)
+    render_separator(canvas: canvas, theme: theme)
+    render_data_rows(canvas: canvas, theme: theme)
+  end
+
+  private
+
+  def emit_selected
+    return if rows.empty?
+
+    emit SelectedEvent.new(index: @cursor, row: rows[@cursor])
+  end
+
+  def render_header(canvas:, theme:)
+    row = canvas.row(0) or return
+
+    row.fill(bg: theme.bar_bg)
+    row.text(content: @headers.join(" | "), fg: theme.accent, bg: theme.bar_bg)
+  end
+
+  def render_separator(canvas:, theme:)
+    row = canvas.row(1) or return
+
+    row.fill(bg: theme.bg)
+    row.text(content: "─" * canvas.width, fg: theme.border, bg: theme.bg)
+  end
+
+  def render_data_rows(canvas:, theme:, widths: nil)
+    visible_rows = canvas.height - 2
+    return if visible_rows <= 0
+
+    visible_rows.times do |i|
+      file_idx = @offset + i
+      row_data = rows[file_idx] or break
+      row      = canvas.row(i + 2) or break
+
+      selected = file_idx == @cursor
+      bg = selected ? theme.selection : theme.bg
+      fg = color_for_type(row_data[2], selected: selected, theme: theme)
+      row.fill(bg: bg)
+      row.text(content: row_data.join(" | "), fg: fg, bg: bg)
+    end
+  end
+
+  def visible_offset(canvas)
+    visible_rows = canvas.height - 2
+    return if visible_rows <= 0
+
+    if @cursor < @offset
+      @offset = @cursor
+    elsif @cursor >= @offset + visible_rows
+      @offset = @cursor - visible_rows + 1
+    end
+  end
+
+  def color_for_type(file_type, selected:, theme:)
+    return theme.selection_fg if selected
+
+    case file_type
+    when "ruby"  then theme.success_fg
+    when "doc"   then theme.info_fg
+    when "text"  then theme.muted_fg
+    else              theme.fg
+    end
+  end
+end
+
+class TableApp
+  include Thaum::App
+
+  attr_reader :result
+
+  def initialize
+    @table  = FileTable.new(headers: HEADERS, rows: ROWS)
+    @hint   = Hint.new
+    @result = nil
+  end
+
+  def on_mount
+    focus(@table)
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def on_event(event)
+    return unless event.is_a?(FileTable::SelectedEvent)
+
+    @result = event.row
+    quit
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @table }
+      region(height: 1)     { @hint }
+    end
+  end
+end
+
+app = TableApp.new
+Thaum.run(app)
+puts app.result.join(" | ") if app.result

data/examples/tabs.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/tabs.rb
+#
+# Demonstrates Thaum::Tabs. Four tabs along the top; ←/→ navigate, the
+# content pane below switches via Tabs::ActivatedEvent. Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+PAGES = {
+  "Overview" => [
+    "Thaum is a Ruby TUI framework.",
+    "",
+    "Sigils render and handle events.",
+    "Layouts partition space.",
+    "Octagrams package both as composites."
+  ],
+  "Sigils" => [
+    "Built-in sigils:",
+    "",
+    "  Text, TextInput, Select, Button",
+    "  Table, ScrollView",
+    "  Spinner, ProgressBar, Checkbox, Tabs"
+  ],
+  "Themes" => [
+    "Eight themes ship with the framework:",
+    "",
+    "  Catppuccin Mocha / Latte",
+    "  Gruvbox Dark, Nord, Dracula",
+    "  Solarized Dark / Light, Material"
+  ],
+  "Keys" => [
+    "Universal: Ctrl-C exits.",
+    "",
+    "Tab / Shift-Tab cycle focus.",
+    "Bracketed paste becomes PasteEvent.",
+    "Mouse support arrives in a later phase."
+  ]
+}.freeze
+
+class Page
+  include Thaum::Sigil
+
+  def initialize(tabs)
+    @tabs = tabs
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    inner = canvas.border(fg: theme.border, style: :rounded)
+    lines = PAGES.fetch(@tabs.current)
+    lines.each_with_index do |line, i|
+      break if i >= inner.height
+
+      inner.text(content: " #{line}", y: i, fg: theme.fg)
+    end
+  end
+end
+
+class Hint
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(content: " ←/→ switch tabs   esc quits", fg: theme.dim)
+  end
+end
+
+class TabsApp
+  include Thaum::App
+
+  def initialize
+    @tabs = Thaum::Tabs.new(labels: PAGES.keys)
+    @page = Page.new(@tabs)
+    @hint = Hint.new
+  end
+
+  def theme = Thaum::Themes::CATPPUCCIN_MOCHA
+
+  def on_mount
+    focus(@tabs)
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  # Tabs::ActivatedEvent bubbles up every time the active tab changes. The
+  # Page sigil reads @tabs.current on each render, so we don't need to
+  # do anything with it — but acknowledging it silences the framework's
+  # default "unhandled event" warning to stderr.
+  def on_event(event)
+    return if event.is_a?(Thaum::Tabs::ActivatedEvent)
+
+    super
+  end
+
+  def partition
+    vertical do
+      region(height: 1)     { @tabs }
+      region(height: :fill) { @page }
+      region(height: 1)     { @hint }
+    end
+  end
+end
+
+Thaum.run(TabsApp.new)

data/examples/text.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/text.rb
+#
+# Demonstrates Thaum::Text — the configurable drop-in Sigil for static
+# content. Each row shows a different (align, wrap) combination.
+# Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+LONG = "Thaum is a Ruby TUI framework. Sigils render and handle events; " \
+       "Layouts partition space. This sentence is long enough to demonstrate " \
+       "word-wrap inside a bounded region."
+
+class Bar
+  include Thaum::Sigil
+
+  def initialize(label:, semantic_fg: nil)
+    @label = label
+    @semantic_fg = semantic_fg
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    fg = @semantic_fg ? theme.send(@semantic_fg) : theme.muted_fg
+    canvas.text(content: " #{@label}", fg: fg)
+  end
+end
+
+class SemanticText
+  include Thaum::Sigil
+
+  def initialize(label:, semantic_color:)
+    @label = label
+    @semantic_color = semantic_color
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    fg = theme.send(@semantic_color)
+    content = "#{@label}: #{@semantic_color}".ljust(60)
+
+    canvas.fill(bg: theme.bg)
+    canvas.text(content:, fg:)
+  end
+end
+
+class TextApp
+  include Thaum::App
+
+  def initialize
+    @bar_align = Bar.new(label: "alignment — left / center / right")
+    @left      = Thaum::Text.new(content: "left-aligned",   align: :left)
+    @center    = Thaum::Text.new(content: "center-aligned", align: :center)
+    @right     = Thaum::Text.new(content: "right-aligned",  align: :right)
+
+    @bar_wrap  = Bar.new(label: "wrap — :word (4-line box) vs :none (truncated)")
+    @wrapped   = Thaum::Text.new(content: LONG, align: :left, wrap: :word)
+    @no_wrap   = Thaum::Text.new(content: LONG, align: :left, wrap: :none)
+
+    @bar_semantic = Bar.new(label: "semantic color tokens", semantic_fg: :accent)
+    @success   = SemanticText.new(label: "✓ Success", semantic_color: :success_fg)
+    @warning   = SemanticText.new(label: "⚠ Warning", semantic_color: :warning_fg)
+    @error     = SemanticText.new(label: "✗ Error", semantic_color: :error_fg)
+    @info      = SemanticText.new(label: "ℹ Info", semantic_color: :info_fg)
+    @muted     = SemanticText.new(label: "◻ Muted", semantic_color: :muted_fg)
+    @disabled  = SemanticText.new(label: "⊘ Disabled", semantic_color: :disabled_fg)
+
+    @hint      = Bar.new(label: "esc to quit")
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def partition
+    vertical do
+      region(height: 1) { @bar_align }
+      region(height: 1) { @left }
+      region(height: 1) { @center }
+      region(height: 1) { @right }
+      region(height: 1) { @bar_wrap }
+      region(height: 4) { @wrapped }
+      region(height: 1) { @no_wrap }
+      region(height: 1) { @bar_semantic }
+      region(height: 1) { @success }
+      region(height: 1) { @warning }
+      region(height: 1) { @error }
+      region(height: 1) { @info }
+      region(height: 1) { @muted }
+      region(height: 1) { @disabled }
+      region(height: :fill) { @hint }
+    end
+  end
+end
+
+Thaum.run(TextApp.new)

data/examples/theme_picker.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/theme_picker.rb
+#
+# The App's theme is whatever the list cursor is on. Thaum resolves
+# app.theme fresh each frame, so a cursor move reflects instantly in
+# the preview pane — no events, no context, no on_update.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+SLOTS = %i[
+  bg fg accent border
+  success_fg warning_fg error_fg info_fg
+  dim muted_fg disabled_fg
+  selection selection_fg pressed
+  input_bg bar_bg
+].freeze
+
+class ThemeList
+  include Thaum::Sigil
+
+  def initialize
+    @themes = Thaum::Themes.names
+    @cursor = 0
+  end
+
+  def current = @themes.fetch(@cursor)
+
+  def on_key(event)
+    case event.key
+    when :up then move(-1)
+    when :down then move(1)
+    else emit(event)
+    end
+  end
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    @themes.each_with_index do |item, i|
+      row = canvas.row(i) or break
+
+      selected = i == @cursor
+      bg = selected ? theme.selection : theme.bar_bg
+      fg = selected ? theme.accent    : theme.fg
+      row.fill(bg: bg)
+      row.text(content: " #{item}", fg: fg, bg: bg)
+    end
+  end
+
+  def move(offset)
+    @cursor = (@cursor + offset) % @themes.size
+  end
+end
+
+class PreviewSigil
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    SLOTS.each_with_index do |slot, i|
+      row = canvas.row(i + 1) or break
+
+      hex = theme.send(slot)
+      row.fill(bg: hex, x: 2, width: 6)
+      row.text(content: "#{slot.to_s.ljust(14)} #{hex}", fg: theme.fg, x: 10)
+    end
+  end
+end
+
+class ThemePickerApp
+  include Thaum::App
+
+  def initialize
+    @list    = ThemeList.new
+    @preview = PreviewSigil.new
+  end
+
+  def theme = Thaum::Themes[@list.current]
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def partition
+    horizontal do
+      region(width: 22) { @list }
+      region(width: :fill) { @preview }
+    end
+  end
+end
+
+Thaum.run(ThemePickerApp.new)