thaum 0.1.0 → 0.2.0

data/examples/octagram_picker.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/octagram_picker.rb
+#
+# Demonstrates Thaum::Octagram by packaging a filter-as-you-type picker
+# (TextInput + filtered list) as a single distributable component.
+#
+# The Picker Octagram:
+# - declares its own partition (TextInput on top, filtered list below)
+# - draws a rounded border behind its children (the Octagram render hook)
+# - intercepts events bubbling up from its children:
+#     :up/:down → forward to the internal list (App never sees them)
+#     :escape   → emit Picker::CancelledEvent
+#     SubmittedEvent → translate to Picker::SelectedEvent(value:)
+#
+# Compare with examples/picker.rb (same UX, but the App had to know
+# about the filter list and route :up/:down itself). With Octagram, the
+# App only knows about Picker::SelectedEvent and Picker::CancelledEvent.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+LANGUAGES = %w[
+  Ruby Python Elixir Erlang Haskell OCaml Rust Go Crystal Zig
+  JavaScript TypeScript CoffeeScript Lua Perl Raku Tcl
+  C C++ Java Kotlin Scala Clojure Groovy
+  Swift Dart Nim D Julia
+  Lisp Scheme Racket Prolog SmallTalk Forth
+].freeze
+
+class FilteredList
+  include Thaum::Sigil
+
+  def initialize(source:, query_source:)
+    @source       = source
+    @query_source = query_source
+    @cursor       = 0
+    @cached_query = nil
+    @cached_items = source
+  end
+
+  def focusable? = false
+
+  def items
+    q = @query_source.value
+    return @cached_items if q == @cached_query
+
+    @cached_query = q
+    @cached_items = q.empty? ? @source : @source.select { |s| s.downcase.include?(q.downcase) }
+    @cursor = @cursor.clamp(0, [@cached_items.length - 1, 0].max)
+    @cached_items
+  end
+
+  def current   = items[@cursor]
+  def cursor_up = (@cursor = [@cursor - 1, 0].max)
+
+  def cursor_down
+    last = [items.length - 1, 0].max
+    @cursor = (@cursor + 1).clamp(0, last)
+  end
+
+  def render(canvas:, theme:)
+    list = items
+    canvas.fill(bg: theme.bg)
+    list.each_with_index do |item, i|
+      break if i >= canvas.height
+
+      draw_row(canvas: canvas, item: item, i: i, theme: theme)
+    end
+  end
+
+  private
+
+  def draw_row(canvas:, item:, i:, theme:)
+    row = canvas.row(i) or return
+
+    sel = i == @cursor
+    bg  = sel ? theme.selection    : theme.bg
+    fg  = sel ? theme.selection_fg : theme.fg
+    row.fill(bg: bg)
+    row.text(content: " #{item}", fg: fg, bg: bg)
+  end
+end
+
+class Picker
+  include Thaum::Octagram
+
+  SelectedEvent  = Thaum::Event.define(:value)
+  CancelledEvent = Thaum::Event.define
+
+  attr_reader :input, :list
+
+  def initialize(items:)
+    @input = Thaum::TextInput.new
+    @list  = FilteredList.new(source: items, query_source: @input)
+  end
+
+  def partition
+    vertical do
+      region(height: 1)     { @input }
+      region(height: :fill) { @list }
+    end
+  end
+
+  # Reserve a 1-cell ring around the children so the rounded border
+  # the render hook draws underneath survives.
+  def partition_inset = { top: 1, bottom: 1, left: 1, right: 1 }
+
+  def render(canvas:, theme:)
+    canvas.border(fg: theme.border, style: :rounded)
+  end
+
+  def on_key(event)
+    case event.key
+    when :up     then @list.cursor_up
+    when :down   then @list.cursor_down
+    when :escape then emit CancelledEvent.new
+    else              emit event
+    end
+  end
+
+  def on_event(event)
+    case event
+    when Thaum::TextInput::SubmittedEvent
+      value = @list.current
+      emit(value ? SelectedEvent.new(value: value) : event)
+    else
+      emit event
+    end
+  end
+end
+
+class Hint
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(content: " type to filter   ↑/↓ navigate   enter picks   esc cancels", fg: theme.dim)
+  end
+end
+
+# Sits next to the Picker. Belongs to the App, not the Octagram —
+# visible proof that the App composes the Picker alongside other
+# sigils it owns. Updates when the user navigates inside the Picker,
+# polling the Picker's exposed list state at render time.
+class Notes
+  include Thaum::Sigil
+
+  def initialize(picker:)
+    @picker = picker
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    inner = canvas.border(fg: theme.dim, style: :single)
+    draw_header(canvas: inner, theme: theme)
+    draw_state(canvas: inner, theme: theme)
+  end
+
+  private
+
+  def draw_header(canvas:, theme:)
+    canvas.text(content: "App-owned sigil",   y: 0, fg: theme.accent)
+    canvas.text(content: "(not inside the",   y: 1, fg: theme.dim)
+    canvas.text(content: " Picker Octagram)", y: 2, fg: theme.dim)
+  end
+
+  def draw_state(canvas:, theme:)
+    cursor  = @picker.list.current || "—"
+    matches = @picker.list.items.length
+    canvas.text(content: "Query:    #{@picker.input.value.inspect}", y: 4, fg: theme.fg)
+    canvas.text(content: "Matches:  #{matches}",                     y: 5, fg: theme.fg)
+    canvas.text(content: "Cursor:   #{cursor}",                      y: 6, fg: theme.fg)
+  end
+end
+
+class PickerApp
+  include Thaum::App
+
+  attr_reader :result
+
+  def initialize
+    @picker = Picker.new(items: LANGUAGES)
+    @notes  = Notes.new(picker: @picker)
+    @hint   = Hint.new
+    @result = nil
+  end
+
+  def theme = Thaum::Themes::CATPPUCCIN_MOCHA
+
+  def on_mount
+    focus(@picker.input)
+  end
+
+  def on_event(event)
+    case event
+    when Picker::SelectedEvent
+      @result = event.value
+      quit
+    when Picker::CancelledEvent
+      quit
+    end
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) do
+        horizontal do
+          region(width: 42)    { @picker }
+          region(width: :fill) { @notes }
+        end
+      end
+      region(height: 1) { @hint }
+    end
+  end
+end
+
+app = PickerApp.new
+Thaum.run(app)
+puts app.result if app.result

data/examples/picker.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/picker.rb
+#
+# Filter-as-you-type list selector. The TextInput on top filters the
+# list below as you type. Arrow keys navigate the filtered results
+# (focus stays on the input — :up/:down bubble out of TextInput, so the
+# App routes them to the list). Enter picks the highlighted item and
+# quits, printing the selection.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+LANGUAGES = %w[
+  Ruby Python Elixir Erlang Haskell OCaml Rust Go Crystal Zig
+  JavaScript TypeScript CoffeeScript Lua Perl Raku Tcl
+  C C++ Java Kotlin Scala Clojure Groovy
+  Swift Dart Nim D Julia
+  Lisp Scheme Racket Prolog SmallTalk Forth
+].freeze
+
+class FilteredList
+  include Thaum::Sigil
+
+  PickedEvent = Thaum::Event.define(:value)
+
+  def initialize(source:, query_source:)
+    @source       = source
+    @query_source = query_source
+    @cursor       = 0
+    @cached_query = nil
+    @cached_items = source
+  end
+
+  def focusable? = false
+
+  def current = items[@cursor]
+
+  def items
+    q = @query_source.value
+    return @cached_items if q == @cached_query
+
+    @cached_query = q
+    @cached_items = q.empty? ? @source : @source.select { |s| s.downcase.include?(q.downcase) }
+    @cursor = @cursor.clamp(0, [@cached_items.length - 1, 0].max)
+    @cached_items
+  end
+
+  def cursor_up
+    @cursor = [@cursor - 1, 0].max
+  end
+
+  def cursor_down
+    last = [items.length - 1, 0].max
+    @cursor = (@cursor + 1).clamp(0, last)
+  end
+
+  def pick
+    return if items.empty?
+
+    emit PickedEvent.new(value: current)
+  end
+
+  def render(canvas:, theme:)
+    list   = items
+    offset = scroll_offset(height: canvas.height, count: list.length)
+    canvas.fill(bg: theme.bg)
+    visible = list[offset, canvas.height] || []
+    visible.each_with_index do |item, row_idx|
+      draw_row(canvas: canvas, item: item, item_idx: offset + row_idx, row_idx: row_idx, theme: theme)
+    end
+  end
+
+  private
+
+  def draw_row(canvas:, item:, item_idx:, row_idx:, theme:)
+    row = canvas.row(row_idx) or return
+
+    sel = item_idx == @cursor
+    bg  = sel ? theme.selection    : theme.bg
+    fg  = sel ? theme.selection_fg : theme.fg
+    row.fill(bg: bg)
+    row.text(content: " #{item}", fg: fg, bg: bg)
+  end
+
+  def scroll_offset(height:, count:)
+    return 0 if @cursor < height || count <= height
+
+    [@cursor - height + 1, count - height].min
+  end
+end
+
+class HintBar
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(content: " type to filter   ↑/↓ navigate   enter picks   esc quits", fg: theme.dim)
+  end
+end
+
+class PickerApp
+  include Thaum::App
+
+  def initialize
+    @input = Thaum::TextInput.new
+    @list  = FilteredList.new(source: LANGUAGES, query_source: @input)
+    @hint  = HintBar.new
+    @picked = nil
+  end
+
+  def theme  = Thaum::Themes::CATPPUCCIN_MOCHA
+  def result = @picked
+
+  def on_mount
+    focus(@input)
+  end
+
+  def on_key(event)
+    case event.key
+    when :up     then @list.cursor_up
+    when :down   then @list.cursor_down
+    when :escape then quit
+    end
+  end
+
+  def on_event(event)
+    case event
+    when Thaum::TextInput::SubmittedEvent
+      @list.pick
+    when FilteredList::PickedEvent
+      @picked = event.value
+      quit
+    end
+  end
+
+  def partition
+    vertical do
+      region(height: 1)     { @input }
+      region(height: :fill) { @list }
+      region(height: 1)     { @hint }
+    end
+  end
+end
+
+app = PickerApp.new
+Thaum.run(app)
+puts app.result if app.result

data/examples/progress_bar.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/progress_bar.rb
+#
+# Demonstrates Thaum::ProgressBar in both modes:
+# - Top bar: determinate, auto-fills from 0 to 1.0 over ~5s; resets at 100%
+# - Bottom bar: indeterminate, a fixed-width block walks across forever
+#
+# Press esc to quit, r to reset the determinate bar.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class Driver
+  include Thaum::Sigil
+
+  def initialize(bar:, interval: 0.1, step: 0.01)
+    @bar      = bar
+    @interval = interval
+    @step     = step
+    @elapsed  = 0.0
+  end
+
+  def focusable? = false
+
+  def on_tick(event)
+    @elapsed += event.delta
+    advanced = false
+    while @elapsed >= @interval
+      @elapsed -= @interval
+      @bar.value = (@bar.value + @step) > 1.0 ? 0.0 : @bar.value + @step
+      advanced = true
+    end
+    request_render if advanced
+  end
+
+  def render(canvas:, theme:); end
+end
+
+class Label
+  include Thaum::Sigil
+
+  def initialize(text:, semantic_fg: nil)
+    @text = text
+    @semantic_fg = semantic_fg
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    fg = @semantic_fg ? theme.send(@semantic_fg) : theme.dim
+    canvas.text(content: @text, fg: fg)
+  end
+end
+
+class ProgressApp
+  include Thaum::App
+
+  def initialize
+    @determinate   = Thaum::ProgressBar.new(value: 0.0)
+    @indeterminate = Thaum::ProgressBar.new(indeterminate: true)
+    @driver        = Driver.new(bar: @determinate)
+    @det_label     = Label.new(text: " determinate (auto-fills, resets at 100%)", semantic_fg: :info_fg)
+    @indet_label   = Label.new(text: " indeterminate (always animating)", semantic_fg: :muted_fg)
+    @hint          = Label.new(text: " esc to quit   r to reset determinate bar", semantic_fg: :dim)
+  end
+
+  def theme = Thaum::Themes::CATPPUCCIN_MOCHA
+
+  def on_key(event)
+    case event.key
+    when :escape then quit
+    when "r" then @determinate.value = 0.0
+    end
+  end
+
+  def partition
+    vertical do
+      region(height: 1) { @det_label }
+      region(height: 1) { @determinate }
+      region(height: 1) { @indet_label }
+      region(height: 1) { @indeterminate }
+      region(height: :fill) { @hint }
+      region(height: 0) { @driver } # off-screen ticker (height: 0 → no render)
+    end
+  end
+end
+
+Thaum.run(ProgressApp.new)

data/examples/scroll_view.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/scroll_view.rb
+#
+# Demonstrates Thaum::ScrollView. Renders a long, optionally wide buffer
+# of pre-formatted text rows. Vertical and horizontal scrolling, ▲/▼
+# indicators when off-viewport content exists.
+#
+# Keys: ↑/↓/pgup/pgdn/home/end for vertical, ←/→ for horizontal, esc to quit.
+# Mouse wheel scrolls vertically.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+ROWS = (1..120).map do |n|
+  num = n.to_s.rjust(3)
+  case n % 5
+  when 0 then "#{num}  #{'─' * 90}"
+  when 1 then "#{num}  the quick brown fox jumps over the lazy dog #{n} times"
+  when 2 then "#{num}  ねこは魚を食べる — wide chars stay aligned because ScrollView slices by display column"
+  when 3 then "#{num}  far-right column reachable only by horizontal scrolling →→→→→→→→→ here: #{n * 7}"
+  else        "#{num}  short row"
+  end
+end.freeze
+
+class Hint
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(
+      content: " ↑/↓ or wheel scroll   pgup/pgdn page   ←/→ horizontal   home/end edges   esc quits",
+      fg: theme.dim
+    )
+  end
+end
+
+class ScrollViewApp
+  include Thaum::App
+
+  def initialize
+    @view = Thaum::ScrollView.new(rows: ROWS)
+    @hint = Hint.new
+  end
+
+  def on_mount
+    focus(@view)
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @view }
+      region(height: 1)     { @hint }
+    end
+  end
+end
+
+Thaum.run(ScrollViewApp.new)

data/examples/select.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/select.rb
+#
+# Demonstrates Thaum::Select. Up/down to navigate, Enter to pick.
+# The chosen item is printed after the app exits.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+FRUITS = %w[
+  apricot banana cherry date elderberry fig grape honeydew
+  imbe jujube kiwi lemon mango nectarine orange papaya
+  quince raspberry strawberry tangerine ugni vanilla watermelon
+].freeze
+
+class Hint
+  include Thaum::Sigil
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bar_bg)
+    canvas.text(content: " ↑/↓ navigate   enter picks   esc quits", fg: theme.info_fg)
+  end
+end
+
+class SelectApp
+  include Thaum::App
+
+  attr_reader :result
+
+  def initialize
+    @select = Thaum::Select.new(items: FRUITS)
+    @hint   = Hint.new
+    @result = nil
+  end
+
+  def on_mount
+    focus(@select)
+  end
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def on_event(event)
+    return unless event.is_a?(Thaum::Select::SelectedEvent)
+
+    @result = event.item
+    quit
+  end
+
+  def partition
+    vertical do
+      region(height: :fill) { @select }
+      region(height: 1)     { @hint }
+    end
+  end
+end
+
+app = SelectApp.new
+Thaum.run(app)
+puts app.result if app.result

data/examples/spinner.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/spinner.rb
+#
+# Demonstrates Thaum::Spinner — animation frame driven by on_tick.
+# Shows the default braille spinner and two custom-frame variants
+# stacked side by side. Press esc to quit.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "thaum"
+
+class Label
+  include Thaum::Sigil
+
+  def initialize(text)
+    @text = text
+  end
+
+  def focusable? = false
+
+  def render(canvas:, theme:)
+    canvas.fill(bg: theme.bg)
+    canvas.text(content: @text, fg: theme.dim)
+  end
+end
+
+class SpinnerApp
+  include Thaum::App
+
+  def initialize
+    @default = Thaum::Spinner.new # ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
+    @dots    = Thaum::Spinner.new(frames: %w[. .. ...], interval: 0.3)
+    @arrow   = Thaum::Spinner.new(frames: %w[← ↖ ↑ ↗ → ↘ ↓ ↙], interval: 0.12)
+
+    @label_a = Label.new(" default braille")
+    @label_b = Label.new(" three dots")
+    @label_c = Label.new(" arrow rotation")
+    @hint    = Label.new(" esc to quit")
+  end
+
+  def theme = Thaum::Themes::CATPPUCCIN_MOCHA
+
+  def on_key(event)
+    quit if event.key == :escape
+  end
+
+  def partition
+    vertical do
+      region(height: 1) { spinner_row(spinner: @default, label: @label_a) }
+      region(height: 1) { spinner_row(spinner: @dots,    label: @label_b) }
+      region(height: 1) { spinner_row(spinner: @arrow,   label: @label_c) }
+      region(height: :fill) { @hint }
+    end
+  end
+
+  private
+
+  def spinner_row(spinner:, label:)
+    horizontal do
+      region(width: 4)     { spinner }
+      region(width: :fill) { label }
+    end
+  end
+end
+
+Thaum.run(SpinnerApp.new)