tui_tui 0.3.0 → 0.4.0

data/examples/downloads.rb

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# A simulated download manager. It demonstrates a ticking dashboard built from
+# Widget::Table (name/size/progress/status columns with Span-colored status
+# cells), Widget::Spinner (animating the active row), Widget::Progress (overall
+# bar), and Widget::StatusBar, laid out with Rect#split_rows. Downloads advance
+# on each tick; finished ones promote the next queued item. Japanese file names
+# show the width-safe rendering. Colors come from TuiTui::Theme.auto.
+#
+#   ruby examples/downloads.rb
+#
+# Keys: j/k (or ↑/↓) move, Space pause/resume the selected download,
+# q (or Ctrl-C) quit.
+
+require_relative "../lib/tui_tui"
+
+module DownloadsSample
+  Download = Data.define(:name, :size_mb, :ratio, :state)
+
+  SEED = [
+    Download.new("ruby-3.4.tar.gz", 24.8, 0.0, :active),
+    Download.new("開発環境つくりかた.pdf", 8.2, 0.0, :queued),
+    Download.new("tui_tui-manual.epub", 3.5, 0.0, :queued),
+    Download.new("空の絶景写真集.zip", 412.0, 0.0, :queued),
+    Download.new("linux-firmware.img", 96.3, 0.0, :queued),
+    Download.new("soundtrack.flac", 58.1, 0.0, :queued),
+  ].freeze
+
+  class App
+    def initialize(downloads = SEED)
+      @downloads = downloads.dup
+      @theme = TuiTui::Theme.auto
+      @spinner = TuiTui::Widget::Spinner.new
+      @list = TuiTui::Widget::ScrollList.new(@downloads.size)
+      @table = TuiTui::Widget::Table.new(@list)
+    end
+
+    # Keep ticking only while something is downloading.
+    def wants_tick? = @downloads.any? { |d| d.state == :active }
+
+    def update(event)
+      case event
+      in TuiTui::KeyEvent(key: "q" | TuiTui::KeyCode::CTRL_C) then return :quit
+      in TuiTui::KeyEvent(key: "j" | :down) then @list.move(1)
+      in TuiTui::KeyEvent(key: "k" | :up) then @list.move(-1)
+      in TuiTui::KeyEvent(key: " ") then toggle_pause
+      in TuiTui::TickEvent then step
+      else nil
+      end
+      self
+    end
+
+    def view(size)
+      canvas = TuiTui::Canvas.blank(size)
+      table, bar, status = TuiTui::Rect.of(size).split_rows(:rest, 1, 1)
+
+      @list.ensure_visible([table.rows - 1, 1].max)
+      draw_table(canvas, table)
+      TuiTui::Widget::Progress.draw(canvas, bar, overall_ratio,
+                                    bar_style: @theme.selection, track_style: @theme.muted)
+      TuiTui::Widget::StatusBar.draw(canvas, status, style: @theme.bar,
+                                     left: " #{done_count}/#{@downloads.size} done",
+                                     right: "j/k move  Space pause  q quit ")
+      canvas
+    end
+
+    private
+
+    # Advance every active download; a finished one promotes the next queued.
+    def step
+      @spinner.advance
+      @downloads.each_with_index do |item, index|
+        next unless item.state == :active
+
+        ratio = item.ratio + rand(0.02..0.09)
+        @downloads[index] = ratio >= 1.0 ? item.with(ratio: 1.0, state: :done) : item.with(ratio: ratio)
+        promote_next if ratio >= 1.0
+      end
+    end
+
+    def promote_next
+      index = @downloads.index { |d| d.state == :queued }
+      @downloads[index] = @downloads[index].with(state: :active) if index
+    end
+
+    def toggle_pause
+      item = @downloads[@list.cursor]
+      case item.state
+      when :active then @downloads[@list.cursor] = item.with(state: :paused)
+      when :paused then @downloads[@list.cursor] = item.with(state: :active)
+      end
+    end
+
+    def draw_table(canvas, rect)
+      return if rect.rows <= 0 || rect.cols <= 0
+
+      name_width = [rect.cols - 9 - 6 - 10 - 3, 8].max # fixed columns + 3 gaps
+      columns = [["name", name_width], ["size", 9], ["prog", 6], ["status", 10]]
+      @table.draw(canvas, rect, columns: columns,
+                  header_style: @theme.bar, highlight: @theme.selection) do |index, _selected|
+        item = @downloads[index]
+        [item.name, format("%.1f MB", item.size_mb), "#{(item.ratio * 100).round}%", status_span(item)]
+      end
+    end
+
+    # Status cells carry their own Span style, so they stay colored even on
+    # the highlighted row.
+    def status_span(item)
+      case item.state
+      when :done then TuiTui::Span["done", @theme.success]
+      when :active then TuiTui::Span["#{@spinner.glyph} down", @theme.warning]
+      when :paused then TuiTui::Span["paused", @theme.danger]
+      else TuiTui::Span["queued", @theme.muted]
+      end
+    end
+
+    def overall_ratio
+      @downloads.sum(&:ratio) / @downloads.size
+    end
+
+    def done_count = @downloads.count { |d| d.state == :done }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  TuiTui::Runtime.new(DownloadsSample::App.new).run(tick: 0.1)
+end

data/examples/file_browser.rb

@@ -14,7 +14,8 @@
 #
 # `/` 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 (CommandPalette, Select, Help, Confirm).
+# The : / m / ? / q modals are TuiTui widgets (CommandPalette, Select, Help,
+# Confirm), opened and dispatched via TuiTui::ModalHost.
 
 require "strscan"
 require_relative "../lib/tui_tui"
@@ -204,7 +205,7 @@ module FileBrowserSample
   class Browser
     def initialize(path)
       @dir = File.expand_path(path)
-      @list = TuiTui::ScrollList.new
+      @list = TuiTui::Widget::ScrollList.new
       @preview_scroll = 0
       @preview_wrap = false # toggle with "w": wrap long lines vs. clip them
       @hl_path = nil        # cache key for syntax-highlighted preview lines
@@ -219,31 +220,21 @@ module FileBrowserSample
       @page = 1
       @preview_page = 1
       @split = 0.5 # divider position as a fraction of the body width (resize-safe)
-      @finder = nil # the fuzzy query while finding (a String), or nil when off
+      @finder = nil # a TuiTui::TextInput holding the fuzzy query while finding, or nil when off
       @matches = {} # entry name => matched char positions, for highlighting
-      @modal = nil
-      @on_result = nil
-      @clipboard = nil # a path queued for the clipboard; the Runtime drains it
+      @host = TuiTui::ModalHost.new
       load_entries
     end
 
-    # The Runtime calls this after `update` and copies the returned text (OSC 52),
-    # then clears it. Keeping the I/O out of `update` leaves the fold pure.
-    def take_clipboard
-      text = @clipboard
-      @clipboard = nil
-      text
-    end
-
     # Keep ticking only while a toast is showing, so it auto-dismisses.
     def wants_tick? = !@toast.nil?
 
     def update(event)
       @toast = nil if @toast&.expired?
       case event
-      when TuiTui::MouseEvent then @modal ? route_modal_mouse(event) : handle_mouse(event)
+      when TuiTui::MouseEvent then @host.open? ? route_modal(event) : handle_mouse(event)
       when TuiTui::KeyEvent
-        return route_modal(event.key) if @modal
+        return route_modal(event) if @host.open?
         return finder_key(event.key) if @finder
 
         handle_key(event.key)
@@ -320,7 +311,7 @@ module FileBrowserSample
       draw_preview(canvas, preview_rect) if preview_rect
       draw_status(canvas, status) if status
       @toast&.draw(canvas, size, style: @theme.selection)
-      @modal&.draw(canvas, size) # modal overlay on top of everything
+      @host.draw(canvas, size) # modal overlay on top of everything
       canvas
     end
 
@@ -329,28 +320,30 @@ module FileBrowserSample
     # --- modals ---
 
     # Show a modal widget; `on_result` interprets its resolved value (and may
-    # return :quit). A widget returns nil from `handle` while still open.
+    # return :quit). ModalHost routes events and runs on_result on resolve; this
+    # wrapper returns self so handle_key branches evaluate to the app model.
     def open_modal(widget, &on_result)
-      @modal = widget
-      @on_result = on_result
+      @host.open(widget, &on_result)
+      self
     end
 
-    def route_modal(key) = resolve_modal(@modal.handle(key))
-    def route_modal_mouse(event) = resolve_modal(@modal.handle_mouse(event))
-
-    def resolve_modal(result)
-      return self if result.nil? # still open
-
-      @modal = nil
-      @on_result.call(result) == :quit ? :quit : self
+    # Route one event to the open modal and normalize the outcome for update:
+    # nil while it stays open (or when on_result had nothing to say) means self;
+    # :quit and [app, *commands] (the palette's "Copy path") pass through.
+    def route_modal(event)
+      case (outcome = @host.handle(event))
+      when :quit then :quit
+      when Array then outcome
+      else self
+      end
     end
 
     def confirm_quit
-      open_modal(TuiTui::Confirm.new("Quit file browser?", theme: @theme)) { |r| :quit if r == :ok }
+      open_modal(TuiTui::Modal::Confirm.new("Quit file browser?", theme: @theme)) { |r| :quit if r == :ok }
     end
 
     def open_actions
-      open_modal(TuiTui::Select.new("Actions", ACTIONS.map(&:first), theme: @theme)) do |result|
+      open_modal(TuiTui::Modal::Select.new("Actions", ACTIONS.map(&:first), theme: @theme)) do |result|
         run_action(result) if result.is_a?(Integer)
       end
     end
@@ -363,13 +356,13 @@ module FileBrowserSample
       end
     end
 
-    def open_help = open_modal(TuiTui::Help.new("Keys", HELP, theme: @theme)) { nil }
+    def open_help = open_modal(TuiTui::Modal::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|
+      open_modal(TuiTui::Modal::CommandPalette.new(COMMANDS, theme: @theme) { |label, _action| label }) do |chosen|
         run_command(chosen.last) if chosen.is_a?(Array)
       end
     end
@@ -390,6 +383,7 @@ module FileBrowserSample
 
     # --- input ---
 
+    # Each branch evaluates to update's return value: self, [self, *commands], or :quit.
     def handle_key(key)
       case key
       when "q", TuiTui::KeyCode::CTRL_C then confirm_quit
@@ -399,38 +393,50 @@ module FileBrowserSample
       when "m" then open_actions
       when "l", "\r", :right then open_entry
       when "h", :left, TuiTui::KeyCode::BACKSPACE then up_dir # h / ← / Backspace
-      when "\t" then @focus = @focus.next
-      when "<" then @split = [@split - SPLIT_STEP, 0.1].max
-      when ">" then @split = [@split + SPLIT_STEP, 0.9].min
+      when "\t" then switch_focus
+      when "<" then nudge_split(-SPLIT_STEP)
+      when ">" then nudge_split(SPLIT_STEP)
       when "J" then scroll_preview(1) # always works, whichever pane is focused
       when "K" then scroll_preview(-1)
       when "w" then toggle_preview_wrap
       when "t" then cycle_theme
-      when "y" then copy_path
+      when "y" then copy_path # [self, Command::Copy] propagates out of update
       else navigate(key) # j/k, arrows, paging and g/G follow the focused pane
       end
+    end
+
+    def switch_focus
+      @focus = @focus.next
       self
     end
 
-    # Cycle the UI theme (default -> warm -> mono -> ...), rebuilding the chrome
-    # palette. Open modals read @theme when created, so the next one matches too.
-    # Queue the selected path for the clipboard (drained by the Runtime) and show
-    # a toast so the copy is visibly confirmed.
+    def nudge_split(delta)
+      @split = (@split + delta).clamp(0.1, 0.9)
+      self
+    end
+
+    # Return a Command::Copy for the selected path (the Runtime writes it to the
+    # clipboard via OSC 52) and show a toast so the copy is visibly confirmed.
     def copy_path
-      @clipboard = File.expand_path(File.join(@dir, selected.to_s))
-      @toast = TuiTui::Toast.new("copied path to clipboard")
+      path = File.expand_path(File.join(@dir, selected.to_s))
+      @toast = TuiTui::Widget::Toast.new("copied path to clipboard")
+      [self, TuiTui::Command::Copy.new(path)]
     end
 
+    # Cycle the UI theme (default -> warm -> mono -> ...), rebuilding the chrome
+    # palette. Open modals read @theme when created, so the next one matches too.
     def cycle_theme
       @theme_i = (@theme_i + 1) % THEMES.size
       @theme = FileBrowserSample.theme_for(THEMES[@theme_i])
       @styles = FileBrowserSample.palette(@theme)
+      self
     end
 
     # Move/page keys act on whichever pane Tab has focused: the directory list,
     # or the file preview (scrolling its text back and forth).
     def navigate(key)
       @focus.focused?(:preview) ? navigate_preview(key) : navigate_list(key)
+      self
     end
 
     def navigate_list(key)
@@ -457,27 +463,31 @@ module FileBrowserSample
 
     def scroll_preview(delta)
       @preview_scroll = [@preview_scroll + delta, 0].max # upper bound clamped in draw_preview
+      self
     end
 
     def toggle_preview_wrap
       @preview_wrap = !@preview_wrap
       @preview_scroll = 0 # the display-line count changes, so start from the top
+      self
     end
 
     def move(delta)
       @list.move(delta)
       @preview_scroll = 0
+      self
     end
 
     def go_to(index)
       @list.go_to(index)
       @preview_scroll = 0
+      self
     end
 
     def open_entry
       name = selected
       return up_dir if name == ".."
-      return unless directory?(name)
+      return self unless directory?(name)
 
       @dir = File.join(@dir, name)
       load_entries
@@ -486,7 +496,7 @@ module FileBrowserSample
 
     def up_dir
       parent = File.dirname(@dir)
-      return if parent == @dir # already at the filesystem root
+      return self if parent == @dir # already at the filesystem root
 
       came_from = File.basename(@dir)
       @dir = parent
@@ -499,8 +509,9 @@ module FileBrowserSample
     # --- fuzzy finder (incremental; built on TuiTui::Fuzzy) ---
 
     def enter_finder
-      @finder = ""
+      @finder = TuiTui::TextInput.new
       refilter
+      self
     end
 
     def exit_finder
@@ -524,16 +535,14 @@ module FileBrowserSample
     end
 
     def type_finder(key)
-      return unless key.bytes.all? { |b| b >= 0x20 && b != 0x7F } # printable only
-
-      @finder += key
-      refilter
+      # #type ignores control keys; the query is append-only (cursor at the end).
+      refilter if @finder.type(key)
     end
 
     def backspace_finder
       return if @finder.empty?
 
-      @finder = @finder[0...-1]
+      @finder.delete_back # by grapheme, so a multi-codepoint cluster deletes whole
       refilter
     end
 
@@ -562,7 +571,7 @@ module FileBrowserSample
     # with matched positions for highlighting), otherwise the full dir-first list.
     def refilter
       if @finder && !@finder.empty?
-        ranked = TuiTui::Fuzzy.new(@finder).rank(@all)
+        ranked = TuiTui::Fuzzy.new(@finder.value).rank(@all)
         @entries = ranked.map(&:first)
         @matches = ranked.to_h { |name, found| [name, found.positions] }
       else
@@ -603,7 +612,7 @@ module FileBrowserSample
 
     def draw_list(canvas, rect)
       highlight = @focus.focused?(:list) ? @styles[:select] : @styles[:select_blur]
-      TuiTui::List.new(@list).draw(canvas, rect, highlight: highlight, scrollbar: @theme) do |index, selected|
+      TuiTui::Widget::List.new(@list).draw(canvas, rect, highlight: highlight, scrollbar: @theme) do |index, selected|
         name = @entries[index]
         label = directory?(name) && name != ".." ? "#{name}/" : name
         base = selected ? highlight : (directory?(name) ? @styles[:dir] : @styles[:file])
@@ -635,7 +644,7 @@ module FileBrowserSample
       width = rect.split_gutter.first.cols # leave room for the scrollbar gutter when wrapping/truncating
       lines = preview_display(width)
       @preview_scroll = @preview_scroll.clamp(0, [lines.length - 1, 0].max)
-      TuiTui::TextView.draw(canvas, rect, lines, top: @preview_scroll, scrollbar: @theme)
+      TuiTui::Widget::TextView.draw(canvas, rect, lines, top: @preview_scroll, scrollbar: @theme)
     end
 
     # Preview as styled display lines (Line). Wrap mode wraps to the width (plain,
@@ -671,10 +680,10 @@ module FileBrowserSample
     end
 
     def draw_status(canvas, rect)
-      left = @finder ? " > #{@finder}" : " #{@dir}"
+      left = @finder ? " > #{@finder.value}" : " #{@dir}"
       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])
+      TuiTui::Widget::StatusBar.draw(canvas, rect, left: left, right: right, style: @styles[:bar])
     end
 
     # Lines of the selected file's preview, cached per selection so we do not