tuile 0.1.0 → 0.3.0

data/lib/tuile/screen.rb

@@ -186,6 +186,17 @@ module Tuile
       $stdin.echo = true
     end
 
+    # Advances focus to the next {Component#tab_stop?} in tree order, wrapping
+    # around. Scope is the topmost popup if one is open, otherwise {#content}
+    # — this keeps Tab confined inside a modal popup. No-op (returns false) if
+    # the modal scope has no tab stops or no content at all.
+    # @return [Boolean] true if focus moved.
+    def focus_next = cycle_focus(forward: true)
+
+    # Mirror of {#focus_next} that walks backwards through the tab order.
+    # @return [Boolean] true if focus moved.
+    def focus_previous = cycle_focus(forward: false)
+
     # @return [Component, nil] current active tiled component.
     def active_window
       check_locked
@@ -235,11 +246,31 @@ module Tuile
       @@instance&.close
     end
 
-    # Prints given strings.
+    # Prints given strings. While {#repaint} is running, writes are
+    # accumulated into a frame buffer and flushed to the terminal as a
+    # single `$stdout.write` at the end of the cycle. This stops the
+    # emulator from rendering half-finished frames (e.g. a layout's
+    # clear-background pass before its children have re-painted), which
+    # was visible as a brief flicker when the auto-clear path triggers.
+    #
+    # Outside repaint, writes go straight to stdout. We deliberately
+    # don't raise on a "print outside repaint" — that would be a useful
+    # guardrail against components painting outside the repaint loop,
+    # but it'd force terminal-housekeeping writes (`Screen#clear`,
+    # mouse-tracking start/stop, cursor-show on teardown) to bypass
+    # this method entirely and write directly to `$stdout`. {FakeScreen}
+    # overrides `print` to capture every byte into its `@prints` array,
+    # and tests that exercise `run_event_loop` against a real {Screen}
+    # would otherwise leak escape sequences to the test runner's stdout.
+    # Keeping `print` as the single sink preserves that override seam.
     # @param args [String] stuff to print.
     # @return [void]
     def print(*args)
-      Kernel.print(*args)
+      if @frame_buffer
+        args.each { |s| @frame_buffer << s.to_s }
+      else
+        Kernel.print(*args)
+      end
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
@@ -255,43 +286,56 @@ module Tuile
       # simple and very fast in common cases.
 
       did_paint = false
-      until @invalidated.empty?
-        did_paint = true
-        popups = @pane.popups
-
-        # Partition invalidated components into tiled vs popup-tree. Sorting
-        # by depth across the whole tree would interleave them: a tiled
-        # grandchild (depth 3) sorts after a popup's content (depth 2) and
-        # overdraws it.
-        popup_tree = Set.new
-        popups.each { |p| p.on_tree { popup_tree << it } }
-        tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }
-
-        # Within the tiled tree, paint parents before children.
-        tiled.sort_by!(&:depth)
-
-        repaint = if tiled.empty?
-                    # Only popups need repaint — paint just their invalidated
-                    # components in depth order.
-                    popup_invalidated.sort_by(&:depth)
-                  else
-                    # Tiled components may overdraw popups; repaint each open
-                    # popup's full subtree on top, in stacking order
-                    # (parent-before-child within each popup).
-                    tiled + popups.flat_map { |p| collect_subtree(p) }
-                  end
-
-        @repainting = repaint.to_set
-        @invalidated.clear
-
-        # Don't call {#clear} before repaint — causes flickering, and only
-        # needed when @content doesn't cover the entire screen.
-        repaint.each(&:repaint)
-
-        # Repaint done, mark all components as up-to-date.
-        @repainting.clear
+      @frame_buffer = +""
+      begin
+        until @invalidated.empty?
+          did_paint = true
+          popups = @pane.popups
+
+          # Partition invalidated components into tiled vs popup-tree. Sorting
+          # by depth across the whole tree would interleave them: a tiled
+          # grandchild (depth 3) sorts after a popup's content (depth 2) and
+          # overdraws it.
+          popup_tree = Set.new
+          popups.each { |p| p.on_tree { popup_tree << it } }
+          tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }
+
+          # Within the tiled tree, paint parents before children.
+          tiled.sort_by!(&:depth)
+
+          repaint = if tiled.empty?
+                      # Only popups need repaint — paint just their invalidated
+                      # components in depth order.
+                      popup_invalidated.sort_by(&:depth)
+                    else
+                      # Tiled components may overdraw popups; repaint each open
+                      # popup's full subtree on top, in stacking order
+                      # (parent-before-child within each popup).
+                      tiled + popups.flat_map { |p| collect_subtree(p) }
+                    end
+
+          @repainting = repaint.to_set
+          @invalidated.clear
+
+          # Don't call {#clear} before repaint — causes flickering, and only
+          # needed when @content doesn't cover the entire screen.
+          repaint.each(&:repaint)
+
+          # Repaint done, mark all components as up-to-date.
+          @repainting.clear
+        end
+        position_cursor if did_paint
+        unless @frame_buffer.empty?
+          $stdout.write(@frame_buffer)
+          $stdout.flush
+        end
+      ensure
+        # Always release the frame buffer, even on exception, so any
+        # subsequent {#print} call (e.g. teardown emits during crash unwind)
+        # reaches stdout instead of being swallowed by a stranded buffer.
+        # The partial frame we hold here is incoherent — discard it.
+        @frame_buffer = nil
       end
-      position_cursor if did_paint
     end
 
     # Returns the absolute screen coordinates where the hardware cursor should
@@ -303,6 +347,34 @@ module Tuile
 
     private
 
+    # Walks the current modal scope in pre-order, collects tab stops, and
+    # advances focus by one (wrapping). When the focused component isn't in
+    # the tab order (e.g. focus is parked on a popup/window chrome with no
+    # interactable widgets), Tab goes to the first stop and Shift+Tab to the
+    # last.
+    # @param forward [Boolean]
+    # @return [Boolean] true if focus moved.
+    def cycle_focus(forward:)
+      check_locked
+      scope = @pane.popups.last || @pane.content
+      return false if scope.nil?
+
+      stops = []
+      scope.on_tree { |c| stops << c if c.tab_stop? }
+      return false if stops.empty?
+
+      idx = @focused.nil? ? nil : stops.index(@focused)
+      target = if idx.nil?
+                 forward ? stops.first : stops.last
+               else
+                 stops[(idx + (forward ? 1 : -1)) % stops.size]
+               end
+      return false if target.equal?(@focused)
+
+      self.focused = target
+      true
+    end
+
     # Collects a component and all its descendants in tree order
     # (parent before children).
     # @param component [Component]
@@ -344,9 +416,25 @@ module Tuile
 
     # A key has been pressed on the keyboard. Handle it, or forward to active
     # window.
+    #
+    # Tab / Shift+Tab are reserved navigation keys: intercepted here before
+    # the pane sees them, so a focused {Component::TextField} (which would
+    # otherwise swallow printable keys via the standard cursor-owner
+    # suppression) doesn't trap them.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
-    def handle_key(key) = @pane.handle_key(key)
+    def handle_key(key)
+      case key
+      when Keys::TAB
+        focus_next
+        true
+      when Keys::SHIFT_TAB
+        focus_previous
+        true
+      else
+        @pane.handle_key(key)
+      end
+    end
 
     # Finds target window and calls {Component::Window#handle_mouse}.
     # @param event [MouseEvent]

data/lib/tuile/screen_pane.rb

@@ -140,16 +140,22 @@ module Tuile
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
-      clicked = @popups.rfind { it.rect.contains?(event.point) }
+      clicked = @popups.reverse_each.find { it.rect.contains?(event.point) }
       clicked = @content if clicked.nil? && @popups.empty?
       clicked&.handle_mouse(event)
     end
 
     # Focus repair when a child detaches. Default {Component#on_child_removed}
     # would refocus to `self` (the pane), which isn't a useful focus target.
-    # Instead, route focus to the now-topmost popup, then to the prior focus
-    # snapshotted when this popup was opened (if still attached), then to
-    # content, then nil.
+    # Instead, route focus to the first interactable widget in the now-topmost
+    # popup; falling back to the focus snapshotted when this popup was opened
+    # (if still attached and still focusable); then to the first interactable
+    # widget in {#content}; then to {#content} itself; then nil.
+    #
+    # "First interactable widget" = first {Component#tab_stop?} in pre-order;
+    # if a scope has no tab stops at all (a borderless ESC-to-close popup, or
+    # tiled content made entirely of {Label}s), we focus the scope's root so
+    # `q`/ESC still has somewhere to dispatch from.
     # @param child [Component]
     # @return [void]
     def on_child_removed(child)
@@ -161,14 +167,30 @@ module Tuile
       cursor = f
       while cursor
         if cursor == child
-          fallback = @popups.last
-          fallback ||= @removing_popup_prior if @removing_popup_prior&.attached?
-          fallback ||= @content
+          fallback = first_tab_stop_or_root(@popups.last)
+          if fallback.nil? && @removing_popup_prior&.attached? && @removing_popup_prior.focusable?
+            fallback = @removing_popup_prior
+          end
+          fallback ||= first_tab_stop_or_root(@content)
           screen.focused = fallback
           return
         end
         cursor = cursor.parent
       end
     end
+
+    private
+
+    # First {Component#tab_stop?} in `root`'s subtree (pre-order), falling
+    # back to `root` itself when the subtree has no tab stops. Returns `nil`
+    # if `root` is `nil`.
+    # @param root [Component, nil]
+    # @return [Component, nil]
+    def first_tab_stop_or_root(root)
+      return nil if root.nil?
+
+      root.on_tree { |c| return c if c.tab_stop? }
+      root
+    end
   end
 end