tuile 0.11.0 → 0.13.0

data/book/README.md

@@ -66,17 +66,19 @@ one, not to fill an outline.
    `focusable?`, and the three-rung order in which a keystroke is offered
    to the tree — Tab, global shortcuts, then `handle_key` delivered to
    focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
-   form's default button) belong on an ancestor, and how `keyboard_hint`
-   drives the status bar.
+   form's default button) belong on an ancestor, why a paste rides its own
+   path rather than the ladder, and how to write a status line over
+   `on_focus_changed` — Tuile draws none for you.
 6. **[Theming](06-theming.md).** Semantic color tokens read at paint
    time, opt-in component backgrounds that inherit down the tree
    (`bg_color`), light/dark auto-detection at startup and live OS
    appearance flips, pairing variants in a `ThemeDef`, app-specific custom
    tokens, and rebuilding theme-derived content in `on_theme_changed`.
 7. **[The component library](07-components.md).** A narrative tour of
-   the shipped toolbox — Window, List, the text inputs and views,
-   ProgressBar, Popup, and the window conveniences — framed around
-   *when and why* you reach for each. Signatures stay in the rdoc.
+   the shipped toolbox — the text inputs and views, the value fields, the
+   selectors, Button, ProgressBar, Window, TabSheet, MenuBar, Popup and the
+   window conveniences — framed around *when and why* you reach for each.
+   Signatures stay in the rdoc.
 8. **[Testing a Tuile app](08-testing.md).** The testing approach:
    `FakeScreen`, asserting against the painted buffer, driving
    invalidation, and PTY-based end-to-end tests of runnable scripts.

data/examples/file_commander.rb

@@ -4,7 +4,9 @@
 # Tuile two-pane file commander. Two windows side by side, each showing a
 # directory listing. Tab switches active pane; arrows / jk move the cursor;
 # Enter descends into a directory (no-op on a regular file); Backspace
-# ascends to the parent. The header label shows the active pane's cwd.
+# ascends to the parent. The header label shows the active pane's cwd, and a
+# static status line spells out the keys — Tuile draws no status bar and
+# reserves no row, so both are ordinary children of the layout.
 # Unreadable directories surface an InfoWindow. Layout follows the
 # terminal on resize (WINCH) — the framework dispatches a TTYSizeEvent and
 # the layout's `rect=` rebuilds the geometry.
@@ -33,6 +35,7 @@ module FileCommanderExample
     def initialize(start_dir)
       super()
       self.cursor = Tuile::Component::List::Cursor.new
+      self.renderer = ->(entry) { Rainbow(entry[:display]).color(TYPE_COLORS[entry[:type]]) }
       @cwd = File.expand_path(start_dir)
       @on_cwd_changed = nil
       load_entries
@@ -60,8 +63,8 @@ module FileCommanderExample
 
     private
 
-    def descend(_index, line)
-      target = File.expand_path(File.join(@cwd, Rainbow.uncolor(line).chomp("/")))
+    def descend(_index, entry)
+      target = File.expand_path(File.join(@cwd, entry[:name]))
       change_to(target) if File.directory?(target)
     end
 
@@ -75,7 +78,7 @@ module FileCommanderExample
       @cwd = path
       load_entries
       self.cursor = Tuile::Component::List::Cursor.new
-      self.top_line = 0
+      self.scroll_top_row = 0
       @on_cwd_changed&.call
     rescue SystemCallError => e
       @cwd = previous
@@ -89,7 +92,7 @@ module FileCommanderExample
         { name: name, type: classify(path), display: is_dir ? "#{name}/" : name, dir_first: is_dir ? 0 : 1 }
       end
       entries.sort_by! { |e| [e[:dir_first], e[:name].downcase] }
-      self.lines = entries.map { |e| Rainbow(e[:display]).color(TYPE_COLORS[e[:type]]) }
+      self.items = entries
     end
 
     # Classify by symlink first so a symlink-to-dir still reads as a link.
@@ -106,18 +109,6 @@ module FileCommanderExample
     end
   end
 
-  # A pane window that advertises navigation shortcuts in the status bar.
-  # The active window's `keyboard_hint` is rendered by {Tuile::Screen}
-  # alongside the global `q` quit hint, so all the user-facing controls
-  # land in one place.
-  class PaneWindow < Tuile::Component::Window
-    def keyboard_hint
-      "Tab #{screen.theme.hint("Switch")}  " \
-        "Enter #{screen.theme.hint("Open")}  " \
-        "Bksp #{screen.theme.hint("Up")}"
-    end
-  end
-
   # Top-level layout. Header label on the first row, two side-by-side
   # windows below. `rect=` re-runs on the initial mount and on every WINCH,
   # so the split tracks the terminal size automatically.
@@ -127,19 +118,34 @@ module FileCommanderExample
       @header = Tuile::Component::Label.new
       add(@header)
 
-      @left_window = PaneWindow.new
+      @left_window = Tuile::Component::Window.new
       @left_list = DirList.new(left_dir)
       @left_list.on_cwd_changed = method(:refresh_header)
       @left_window.content = @left_list
       @left_window.scrollbar = true
       add(@left_window)
 
-      @right_window = PaneWindow.new
+      @right_window = Tuile::Component::Window.new
       @right_list = DirList.new(right_dir)
       @right_list.on_cwd_changed = method(:refresh_header)
       @right_window.content = @right_list
       @right_window.scrollbar = true
       add(@right_window)
+
+      # The status line. Every key here works in both panes, so the row never
+      # changes and nothing needs to watch focus — a status line is only worth
+      # wiring to Tuile::Screen#on_focus_changed= when its text actually varies
+      # with the focused component. `theme.hint` bakes its colors in, so the
+      # one thing this label does watch is a light/dark flip.
+      @status = Tuile::Component::Label.new
+      render_status = lambda do
+        t = screen.theme
+        @status.text = "q #{t.hint("quit")}  Tab #{t.hint("Switch")}  " \
+                       "Enter #{t.hint("Open")}  Bksp #{t.hint("Up")}"
+      end
+      render_status.call
+      @status.on_theme_changed = render_status
+      add(@status)
     end
 
     attr_reader :left_window
@@ -149,8 +155,9 @@ module FileCommanderExample
       return if rect.empty?
 
       @header.rect = Tuile::Rect.new(rect.left, rect.top, rect.width, 1)
+      @status.rect = Tuile::Rect.new(rect.left, rect.top + rect.height - 1, rect.width, 1)
       body_top = rect.top + 1
-      body_height = [rect.height - 1, 0].max
+      body_height = [rect.height - 2, 0].max
       half = rect.width / 2
       @left_window.rect = Tuile::Rect.new(rect.left, body_top, half, body_height)
       @right_window.rect = Tuile::Rect.new(rect.left + half, body_top,

data/examples/hello_world.rb

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Tuile hello-world. A Window wrapping a Label.
+# Tuile hello-world. A Window wrapping a Label, over a status line the app
+# owns — Tuile draws no chrome of its own and reserves no row.
 #
 # Run from the gem root:
 #   bundle exec ruby -Ilib examples/hello_world.rb
@@ -14,12 +15,23 @@ require "tuile"
 # Tuile::Screen.instance during invalidate/repaint hooks.
 screen = Tuile::Screen.new
 
-label = Tuile::Component::Label.new("Hello, world!")
-
 window = Tuile::Component::Window.new("Tuile")
-window.content = label
+window.content = Tuile::Component::Label.new("Hello, world!")
+
+# The status line. `theme.hint` styles the *description* half of a "key what"
+# pair, and bakes the color in — so the label rebuilds itself from
+# `on_theme_changed` to follow a light/dark flip.
+status = Tuile::Component::Label.new
+render_status = -> { status.text = "q #{screen.theme.hint("quit")}" }
+render_status.call
+status.on_theme_changed = render_status
+
+# One row for the status line, everything else to the window.
+root = Tuile::Component::Layout::Vertical.new
+root.add(window, Tuile::Component::Layout::Expand[1])
+root.add(status, Tuile::Component::Layout::Fixed[1])
 
-screen.content = window
+screen.content = root
 window.focus
 begin
   screen.run_event_loop