tuile 0.8.0 → 0.10.0

data/lib/tuile/fake_screen.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 module Tuile
-  # Testing only — a screen which doesn't paint anything and pretends that the
-  # lock is held. This way, the TTY running the tests is not painted over.
+  # Testing only — a screen which doesn't paint anything, so the TTY running
+  # the tests is not painted over. It runs no event loop, so
+  # {Screen#check_locked} admits the thread that called {Screen.fake}: a spec
+  # mutating the UI from a *spawned* thread raises, exactly as an app would.
   #
   # Intended for unit-testing individual components: instantiate a component,
   # mutate it, and assert against {#prints} or {#invalidated?}. It does not
@@ -35,9 +37,6 @@ module Tuile
     #   on `prints` for cursor and housekeeping escapes.
     attr_reader :prints
 
-    # @return [void]
-    def check_locked; end
-
     # @return [void]
     def clear
       @prints.clear

data/lib/tuile/fraction.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A width/height ratio, each a float in `0.0..1.0` — the single relational
+  # sizing primitive in Tuile, scoped to one job: sizing a {Component::Popup}
+  # against the screen (a popup has no siblings competing for space, so "half
+  # the screen, centered" beats a hard-coded cell count that breaks on the next
+  # terminal size). It is deliberately *not* a general layout primitive — tiled
+  # components get explicit integer rects computed by their parent's `rect=`.
+  # See book ch3 for the layout model.
+  #
+  # Resolve it against a reference {Size} (the screen) to get concrete integer
+  # cells:
+  #
+  #   Fraction::HALF.resolve(Size.new(80, 24))  # => 40x12
+  #
+  # Integer arguments are coerced to float, so `Fraction.new(1, 1) == FULL`.
+  class Fraction < Data.define(:width, :height)
+    # @param width [Numeric] fraction of the reference width, `0.0..1.0`.
+    # @param height [Numeric] fraction of the reference height, `0.0..1.0`.
+    def initialize(width:, height:)
+      super(width: width.to_f, height: height.to_f)
+    end
+
+    # Resolves this fraction against a reference size, rounding each axis to the
+    # nearest cell and flooring at 1 — so a fraction never yields a zero-size
+    # result on a tiny terminal.
+    # @param reference [Size] the size to take a fraction of (usually the screen).
+    # @return [Size]
+    def resolve(reference)
+      Size.new([(reference.width * width).round, 1].max,
+               [(reference.height * height).round, 1].max)
+    end
+
+    # Half the reference size on each axis — the default {Component::Popup} size.
+    # @return [Fraction]
+    HALF = new(0.5, 0.5)
+    # The full reference size on each axis — fullscreen for a {Component::Popup}.
+    # @return [Fraction]
+    FULL = new(1.0, 1.0)
+  end
+end

data/lib/tuile/screen.rb

@@ -1,25 +1,54 @@
 # frozen_string_literal: true
 
 module Tuile
-  # The TTY screen. There is exactly one screen per app.
+  # The process-singleton runtime: one {Screen} per app, reached through
+  # {Screen.instance}. It owns everything the UI needs to exist — the
+  # {#event_queue}, the UI lock, the invalidation set, the terminal IO, the
+  # back {#buffer}, the {#theme}/{#theme_def}, the {#focused} component, the
+  # global-shortcut registry, and the single {ScreenPane} under which *all*
+  # UI lives. Construct one with {Screen.new} (or {Screen.fake} in tests),
+  # tear it down with {Screen.close}.
   #
-  # A screen runs the event loop; call {#run_event_loop} to do that.
+  # ## The component tree
   #
-  # A screen holds the screen lock; any UI modifications must be called from
-  # the event queue.
+  # Everything on screen hangs off {#pane} (a {ScreenPane}): the tiled
+  # {#content} (set via {#content=}, filling the whole terminal and laying
+  # out its own children), the modal/overlay {#popups} stack (opened via
+  # {Component::Popup#open}, drawn on top of the content), and the bottom
+  # status bar. Popups are *not* sized from their content — each carries its
+  # own top-down {Component::Popup#size} — and they deliberately overdraw the
+  # content without clipping.
   #
-  # All UI lives under a single {ScreenPane} owned by the screen. Set tiled
-  # content via {#content=}; the pane fills the entire terminal and is
-  # responsible for laying out its children.
+  # ## Repaint model
   #
-  # Modal popups are supported too, via {Component::Popup#open}. They
-  # auto-size to their wrapped content and are drawn centered over the
-  # tiled content.
+  # Components never draw to the terminal directly. They call
+  # {Component#invalidate} to mark themselves dirty, and when they do paint
+  # they write styled cells into {#buffer}. Once the event loop drains its
+  # queue, {#repaint} walks the invalidated set in z-order, has each
+  # component paint into the buffer, then flushes the buffer's *minimal diff*
+  # (only cells that changed) to the terminal in one synchronized-output
+  # batch — which is what keeps repaint flicker-free and coalesces many
+  # invalidations into a single frame per tick. See the book (ch. 2) for the
+  # why.
   #
-  # The drawing procedure is very simple: when a window needs repaint, it
-  # invalidates itself, but won't draw immediately. After the keyboard press
-  # event processing is done in the event loop, {#repaint} is called which
-  # then repaints all invalidated windows. This prevents repeated paintings.
+  # ## Thread-safety
+  #
+  # **UI-thread-confined**, where "the UI thread" changes hands once: it is the
+  # loop's thread while {#run_event_loop} is in progress, and the thread that
+  # *created* the screen whenever no loop is running ({#state} `:idle`). So an
+  # app builds its tree on its own thread, hands ownership to the loop, and
+  # gets it back for teardown — the loop needn't run on the creating thread.
+  # *All* UI mutations — {#content=}, {#focused=}, {#theme=},
+  # {Component#invalidate}, `rect=`, … — obey it via {#check_locked}.
+  #
+  # A worker marshals back with `screen.event_queue.submit { … }`, which runs
+  # the block only while a loop is draining the queue — outside `:running` it
+  # silently never fires. Terminal resize, key/mouse input and OS color-scheme
+  # flips arrive as events on that same queue.
+  #
+  # The singleton slot survives subclassing (`FakeScreen < Screen`), so
+  # {FakeScreen} — which captures output in memory — is what
+  # {Screen.instance} returns under test.
   class Screen
     # Class variable (not class instance var) so the singleton survives
     # subclassing — `FakeScreen < Screen` and `Screen.instance` see the same slot.
@@ -33,11 +62,13 @@ module Tuile
       # Components being repainted right now. A component may invalidate its
       # children during its repaint phase; this prevents double-draw.
       @repainting = Set.new
-      # Until the event loop is run, we pretend we're in the UI thread.
-      @pretend_ui_lock = true
-      @scheme = detect_scheme
+      # The thread that owns the UI whenever no event loop is running — i.e.
+      # during :idle, at both ends of the screen's life. See {#check_locked}.
+      @ui_thread = Thread.current
+      @closed = false
+      @color_scheme = detect_scheme
       @theme_def = ThemeDef.default
-      @theme = @theme_def.for(@scheme)
+      @theme = @theme_def.for(@color_scheme)
       # Structural root of the component tree: holds tiled content, popup
       # stack and status bar.
       @pane = ScreenPane.new
@@ -57,9 +88,31 @@ module Tuile
     Shortcut = Data.define(:block, :over_popups, :hint)
     private_constant :Shortcut
 
+    # Keys {#register_global_shortcut} refuses because every editable widget
+    # needs them: the registry sits *above* the component tree, so binding one
+    # app-wide would silently break text entry everywhere — a
+    # {Component::TextArea}'s newline, a caret move, a deletion. `ENTER` is the
+    # trap worth naming: it is unprintable, so nothing else stops it, and
+    # "bind Enter to submit" is the obvious wrong way to build a default
+    # button. The right way is a `handle_key` on the form itself, where a
+    # focused field still gets first refusal — see {ScreenPane#handle_key}.
+    #
+    # Deliberately *not* reserved: `HOME`/`END`/`PAGE_UP`/`PAGE_DOWN`. They
+    # move within a widget rather than mutate its value, and binding them
+    # app-wide (scroll the log pane) is a real use case.
+    # @return [Array<String>]
+    EDITING_KEYS = [
+      Keys::ENTER, Keys::DELETE, *Keys::BACKSPACES,
+      Keys::UP_ARROW, Keys::DOWN_ARROW, Keys::LEFT_ARROW, Keys::RIGHT_ARROW,
+      Keys::CTRL_LEFT_ARROW, Keys::CTRL_RIGHT_ARROW
+    ].freeze
+
     # @return [ScreenPane] the structural root of the component tree.
     attr_reader :pane
 
+    # @return [Symbol] `:light` or `:dark`
+    attr_reader :color_scheme
+
     # @return [Buffer] the back buffer components paint into
     #   ({Buffer#set_line} / {Buffer#fill} / {Buffer#set_char}).
     attr_reader :buffer
@@ -97,6 +150,9 @@ module Tuile
     # @param content [Component]
     # @return [void]
     def content=(content)
+      # Not left to ScreenPane#content='s own checks: after #close there's no
+      # pane to forward to, and NoMethodError-for-nil is a poor error.
+      check_locked
       @pane.content = content
       layout
     end
@@ -133,23 +189,16 @@ module Tuile
 
       check_locked
       @theme_def = theme_def
-      self.theme = @theme_def.for(@scheme)
+      self.theme = @theme_def.for(@color_scheme)
     end
 
     # Replaces the theme and restyles the whole UI: fires
-    # {Component#on_theme_changed} across the attached tree (so the app can
-    # rebuild styled content whose colors were derived from the old theme),
-    # refreshes the status bar and invalidates every attached component so
-    # the next repaint uses the new colors. No-op when `new_theme` equals
-    # the current theme.
-    #
-    # This is a transient override: the next OS appearance flip re-picks
-    # from {#theme_def} and replaces it. To theme an app durably, assign
-    # {#theme_def=} instead.
-    #
-    # Note status-bar hints supplied by the host as preformatted strings
-    # (see {#register_global_shortcut}) have their colors baked in and are
-    # not restyled by this.
+    # {Component#on_theme_changed} across the attached tree, refreshes the
+    # status bar, and invalidates every attached component. No-op when
+    # `new_theme` equals the current theme. This is a *transient* override —
+    # the next OS appearance flip re-picks from {#theme_def}; assign {#theme_def=}
+    # for durable theming. Preformatted status-bar hints (see
+    # {#register_global_shortcut}) have their colors baked in and aren't restyled.
     # @param new_theme [Theme]
     # @return [void]
     def theme=(new_theme)
@@ -171,15 +220,41 @@ module Tuile
     # @return [EventQueue] the event queue.
     attr_reader :event_queue
 
-    # Checks that the UI lock is held and the current code runs in the "UI
-    # thread".
+    # `:idle` covers *both* ends of the screen's life — before the first
+    # {#run_event_loop} and after it returns — and a screen may cycle
+    # `:idle` → `:running` → `:idle` repeatedly. `:closed` is terminal.
+    # @return [Symbol] `:idle` (no event loop running), `:running` (a
+    #   {#run_event_loop} is in progress) or `:closed` (after {#close}).
+    def state
+      return :closed if @closed
+
+      @event_queue.running? ? :running : :idle
+    end
+
+    # Raises unless the calling thread currently owns the UI (see the
+    # class-level threading contract).
+    #
+    #   screen.check_locked   # from a worker: raises; wrap the work in
+    #                         # screen.event_queue.submit { ... } instead
+    #
+    # @raise [Tuile::Error] if {#state} is `:closed`, or the calling thread
+    #   isn't the current owner.
     # @return [void]
     def check_locked
-      return if @pretend_ui_lock || @event_queue.locked?
-
-      raise Tuile::Error,
-            "UI lock not held: UI mutations must run on the event-loop thread; " \
-            "marshal via screen.event_queue.submit { ... }"
+      raise Tuile::Error, "Screen is closed: no UI mutation is possible after Screen#close" if @closed
+      return if @event_queue.running? ? @event_queue.on_loop_thread? : Thread.current.equal?(@ui_thread)
+
+      # `submit` is the wrong remedy with no loop running — nothing would drain
+      # the queue, so the block silently never fires.
+      message = if @event_queue.running?
+                  "UI lock not held: UI mutations must run on the event-loop thread; " \
+                  "marshal via screen.event_queue.submit { ... }"
+                else
+                  "UI not owned by #{Thread.current}: no event loop is running, so UI mutations must " \
+                  "come from #{@ui_thread}, the thread that created this screen " \
+                  "(or start the event loop first)"
+                end
+      raise Tuile::Error, message
     end
 
     # Clears the TTY screen.
@@ -280,8 +355,13 @@ module Tuile
       # current screen contents.
     end
 
-    # Runs event loop – waits for keys and sends them to active window. The
-    # function exits when the 'ESC' or 'q' key is pressed.
+    # Runs the event loop on the calling thread, taking over stdin (raw mode,
+    # echo off): keys and mouse events are dispatched via {#handle_key} /
+    # {#handle_mouse}, and the loop repaints once per drained tick. Returns
+    # when `q` or ESC is pressed unhandled. Restores terminal state on exit.
+    #
+    # For the duration this thread owns the UI ({#state} is `:running`);
+    # ownership reverts to the creating thread once it returns.
     #
     # @param capture_mouse [Boolean] when true (default), enables xterm mouse
     #   tracking so clicks and scroll wheel arrive as {MouseEvent}s and feed
@@ -290,23 +370,30 @@ module Tuile
     #   you want if the app benefits more from select-to-copy than from
     #   click-to-focus. Components' `handle_mouse` is simply never invoked
     #   from the loop in that mode (the terminal stops sending the bytes).
+    # @raise [Tuile::Error] if the screen is already {#close}d.
     # @return [void]
     def run_event_loop(capture_mouse: true)
-      @pretend_ui_lock = false
-      $stdin.echo = false
-      print MouseEvent.start_tracking if capture_mouse
-      # Follow OS light/dark flips live: terminals supporting mode 2031
-      # push color-scheme reports that the key thread turns into
-      # {EventQueue::ColorSchemeEvent}s.
-      print TerminalBackground::NOTIFY_ON
-      $stdin.raw do
-        event_loop
+      raise Tuile::Error, "Screen is closed: cannot run the event loop" if @closed
+
+      # The guard above stays outside the begin: teardown for a setup that never
+      # happened restores echo on a non-TTY stdin, and the ENOTTY masks the
+      # real error.
+      begin
+        $stdin.echo = false
+        print MouseEvent.start_tracking if capture_mouse
+        # Follow OS light/dark flips live: terminals supporting mode 2031
+        # push color-scheme reports that the key thread turns into
+        # {EventQueue::ColorSchemeEvent}s.
+        print TerminalBackground::NOTIFY_ON
+        $stdin.raw do
+          event_loop
+        end
+      ensure
+        print TerminalBackground::NOTIFY_OFF
+        print MouseEvent.stop_tracking if capture_mouse
+        print TTY::Cursor.show
+        $stdin.echo = true
       end
-    ensure
-      print TerminalBackground::NOTIFY_OFF
-      print MouseEvent.stop_tracking if capture_mouse
-      print TTY::Cursor.show
-      $stdin.echo = true
     end
 
     # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
@@ -320,31 +407,23 @@ module Tuile
     # @return [Boolean] true if focus moved.
     def focus_previous = cycle_focus(forward: false)
 
-    # Registers an app-level keyboard shortcut. When `key` arrives, the block
-    # is invoked on the event-loop thread (so it may freely mutate UI) before
-    # the key reaches any component. Re-registering the same key replaces the
-    # previous binding; use {#unregister_global_shortcut} to remove one.
-    #
-    # Only unprintable keys are accepted — control characters (Ctrl+letter,
-    # ESC, BACKSPACE, ENTER, …) and multi-character escape sequences (arrows,
-    # F-keys, …). Printable keys raise {ArgumentError}: they'd hijack typing
-    # into a {Component::TextField} and should be expressed as
-    # {Component#key_shortcut} instead, which the dispatcher suppresses while
-    # a text widget owns the hardware cursor. TAB and SHIFT_TAB are also
-    # rejected because {#handle_key} intercepts them for focus navigation
-    # before the global registry is consulted, so a binding on them would
-    # silently never fire.
+    # Registers an app-level keyboard shortcut: when `key` arrives, the block
+    # runs on the event-loop thread (free to mutate UI) before the key reaches
+    # any component. Re-registering a key replaces its binding.
     #
-    # Pass `hint:` to surface the shortcut in the status bar. It's a
-    # preformatted string the caller fully owns (so colors and the key label
-    # style stay consistent with whatever the host app uses elsewhere). The
-    # framework splices it in like any other status hint: in the tiled case,
-    # right after `q quit` and before the active window's own hint; while a
-    # popup is open, only hints from `over_popups: true` shortcuts are
-    # shown, and they're prepended before the popup's `q Close`.
+    # This registry is the *only* keyboard mechanism above the component tree,
+    # and nothing suppresses it — so it accepts only keys no widget can need.
+    # Three groups raise at registration rather than misbehaving at runtime:
     #
-    # Example — open a log popup with Ctrl+L from anywhere, even while a
-    # popup is already on screen:
+    # - **Printable keys** — they'd hijack typing into a
+    #   {Component::TextField}. A scope-wide one-key binding belongs on the
+    #   scope root's own `handle_key`, where a focused field consumes it first
+    #   (see {ScreenPane#handle_key}).
+    # - **TAB / SHIFT_TAB** — {#handle_key} intercepts them for focus
+    #   navigation before the registry is consulted, so a binding would never
+    #   fire.
+    # - **{EDITING_KEYS}** — `ENTER`, `BACKSPACE`, `DELETE` and the arrows,
+    #   which every editable widget needs.
     #
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
@@ -352,16 +431,12 @@ module Tuile
     #     log_popup.open
     #   end
     #
-    # @param key [String] unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC},
-    #   {Keys::PAGE_UP}).
-    # @param over_popups [Boolean] when true, fires even while a modal popup
-    #   is open (pre-empting the popup's own key handling). When false
-    #   (default), the shortcut is suppressed while any popup is open and
-    #   the popup gets the key instead.
-    # @param hint [String, nil] preformatted status-bar hint (e.g.
-    #   `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut
-    #   is silent in the status bar. The colors are baked into the string,
-    #   so a later {#theme=} does not restyle it — re-register if needed.
+    # @param key [String] unprintable key (e.g. {Keys::CTRL_L}, {Keys::ESC}).
+    # @param over_popups [Boolean] when true, fires even while a modal popup is
+    #   open (pre-empting the popup); when false (default), suppressed while any
+    #   popup is open so the popup gets the key.
+    # @param hint [String, nil] preformatted status-bar hint; nil (default) is
+    #   silent. Colors are baked in — re-register after a {#theme=} to recolor.
     # @yield invoked with no arguments when `key` is pressed.
     # @return [void]
     def register_global_shortcut(key, over_popups: false, hint: nil, &block)
@@ -371,13 +446,21 @@ module Tuile
       if Keys.printable?(key)
         raise ArgumentError,
               "global shortcut key must be unprintable; got #{key.inspect}. " \
-              "Use Component#key_shortcut for printable keys (it's suppressed " \
-              "while a text widget owns the cursor, so it won't hijack typing)."
+              "For a one-key binding, override handle_key on the scope root " \
+              "(your content layout, or the popup) — a focused text field then " \
+              "consumes the key first, so typing isn't hijacked."
       end
       if [Keys::TAB, Keys::SHIFT_TAB].include?(key)
         raise ArgumentError,
               "#{key == Keys::TAB ? "TAB" : "SHIFT_TAB"} is reserved for focus navigation"
       end
+      if EDITING_KEYS.include?(key)
+        raise ArgumentError,
+              "#{key.inspect} is reserved: every editable widget needs it, and this registry " \
+              "sits above the component tree with nothing to suppress it. For a default " \
+              "button, handle ENTER in the form's own handle_key instead — a focused " \
+              "TextArea/TextField gets first refusal there."
+      end
       raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}" unless hint.nil? || hint.is_a?(String)
 
       @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups, hint: hint)
@@ -445,11 +528,31 @@ module Tuile
     # @return [FakeScreen]
     def self.fake = FakeScreen.new
 
+    # Tears the screen down and vacates the singleton slot, moving {#state} to
+    # the terminal `:closed`. Unmounts the tree first, so every component gets
+    # its {Component#on_detached}. Idempotent.
+    # @raise [Tuile::Error] if an event loop is still running — stop it with
+    #   `event_queue.stop` and let {#run_event_loop} return first, since closing
+    #   under a live loop drops the pane it is still painting — or if the caller
+    #   doesn't own the UI.
     # @return [void]
     def close
-      clear
-      @pane = nil
-      @@instance = nil # rubocop:disable Style/ClassVars
+      return if @closed
+
+      raise Tuile::Error, "Screen is running: stop the event loop before closing" if state == :running
+
+      check_locked
+      begin
+        @pane.detach_all
+      ensure
+        # A raising on_detached propagates — it's a bug to fix, not something the
+        # framework guards — but teardown still has to finish, or one such bug
+        # leaves a half-closed screen behind and every later example fails with it.
+        clear
+        @pane = nil
+        @closed = true
+        @@instance = nil # rubocop:disable Style/ClassVars
+      end
     end
 
     # @return [void]
@@ -470,7 +573,10 @@ module Tuile
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
-    # considering invalidated windows.
+    # considering invalidated components and flushing just the changed cells
+    # of {#buffer}. Called once per event-loop tick (on {EventQueue::EmptyQueueEvent});
+    # components should {Component#invalidate} and let the loop coalesce rather
+    # than call this directly.
     # @return [void]
     def repaint
       check_locked
@@ -525,11 +631,7 @@ module Tuile
         @repainting = repaint.to_set
         @invalidated.clear
 
-        # Components write into @buffer; overdraw is free and correct here
-        # because the buffer only diffs net-visible changes to the terminal.
         repaint.each(&:repaint)
-
-        # Repaint done, mark all components as up-to-date.
         @repainting.clear
       end
       return unless did_paint
@@ -565,8 +667,8 @@ module Tuile
     # @param scheme [Symbol] `:dark` or `:light`.
     # @return [void]
     def on_color_scheme(scheme)
-      @scheme = scheme
-      self.theme = @theme_def.for(@scheme)
+      @color_scheme = scheme
+      self.theme = @theme_def.for(@color_scheme)
     end
 
     # Walks the current modal scope in pre-order, collects tab stops, and
@@ -615,9 +717,10 @@ module Tuile
       $stdout.flush
     end
 
-    # Recalculates positions of all windows, and repaints the scene.
-    # Automatically called whenever terminal size changes. Call when the app
-    # starts. {#size} provides correct size of the terminal.
+    # Resizes {#buffer} and {#pane} to the current {#size}, invalidates the
+    # whole tree and repaints. Run whenever the terminal size changes (the
+    # {EventQueue::TTYSizeEvent} path) and once at startup via the first
+    # {#content=}.
     # @return [void]
     def layout
       check_locked
@@ -632,17 +735,15 @@ module Tuile
     #
     # Dispatch order:
     #   1. Tab / Shift+Tab — reserved focus navigation, intercepted before
-    #      anything else so a focused {Component::TextField} (which would
-    #      otherwise swallow printable keys via cursor-owner suppression)
-    #      doesn't trap them.
+    #      anything else so a focused {Component::TextField} (which swallows
+    #      printable keys) can't trap them.
     #   2. App-level shortcuts from {#register_global_shortcut}. An entry
     #      registered with `over_popups: true` always fires; one with the
     #      default `over_popups: false` fires only when no modal popup is open
     #      (otherwise the modal popup receives the key normally). A non-modal
     #      overlay doesn't suppress global shortcuts.
-    #   3. {ScreenPane#handle_key}, which captures a matching {#key_shortcut}
-    #      in the active scope, then delivers the key to {#focused} and bubbles
-    #      it up the focus chain.
+    #   3. {ScreenPane#handle_key} — delivery to {#focused}, bubbling up the
+    #      focus chain to the scope root.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
     def handle_key(key)