tuile 0.9.0 → 0.11.0

data/lib/tuile/component/layout.rb

@@ -3,7 +3,13 @@
 module Tuile
   class Component
     # A layout doesn't paint anything by itself: its job is to position child
-    # components.
+    # components. Two families, both top-down (see book ch3):
+    #
+    # - {Absolute} — you override {Component#rect=} and compute every child's
+    #   rectangle yourself. Total control, and the base for anything unusual.
+    # - {Box} / {Vertical} / {Horizontal} — you declare each child's extent as
+    #   a {Fixed}, {Percent} or {Expand} constraint and the layout does the
+    #   arithmetic. Sugar over the same `rect=` assignment, for the common case.
     #
     # Children that fully tile the layout's rect repaint themselves and
     # cover everything; children that leave gaps (e.g. a form with widgets
@@ -11,13 +17,147 @@ module Tuile
     # the background is cleared and children are re-invalidated so they
     # paint over a clean surface.
     class Layout < Component
-      def initialize
-        super
-        @children = []
+      # How much space a child gets along one axis of a {Box}: exactly {#cells},
+      # clamped to whatever is still unassigned.
+      #
+      #   add(prompt, Fixed[4])                    # 4 rows in a Vertical
+      #   add(field, Fixed[1], cross: Fixed[30])   # 1 row, 30 columns wide
+      #
+      # `Fixed[0]` hides the child — it gets an empty rect and paints nothing.
+      #
+      # @!attribute [r] cells
+      #   @return [Integer] cell count along the axis.
+      class Fixed < Data.define(:cells)
+        # @param cells [Integer] cell count along the axis; `>= 0`.
+        # @raise [ArgumentError] unless `cells` is a non-negative Integer.
+        def initialize(cells:)
+          unless cells.is_a?(Integer) && !cells.negative?
+            raise ArgumentError, "Fixed expects a non-negative Integer, got #{cells.inspect}"
+          end
+
+          super
+        end
       end
 
-      # @return [Array<Component>]
-      def children = @children.to_a
+      # A percentage of the space *available* along a {Box}'s axis — measured
+      # after {Box#padding} and {Box#spacing} have come off, so two `Percent[50]`
+      # children fit exactly rather than overflowing by the gap between them.
+      #
+      #   add(left, Percent[60])
+      #   add(right, Percent[40])
+      #
+      # @!attribute [r] percent
+      #   @return [Numeric] percentage of the available extent, `0..100`.
+      class Percent < Data.define(:percent)
+        # @param percent [Numeric] percentage of the available extent, `0..100`.
+        # @raise [ArgumentError] unless `percent` is a Numeric in `0..100`.
+        def initialize(percent:)
+          unless percent.is_a?(Numeric) && percent.between?(0, 100)
+            raise ArgumentError, "Percent expects a Numeric in 0..100, got #{percent.inspect}"
+          end
+
+          super
+        end
+      end
+
+      # A share of whatever a {Box} has left once its {Fixed} and {Percent}
+      # children have taken theirs, split between the `Expand` children in
+      # proportion to their weights:
+      #
+      #   add(header, Fixed[1])
+      #   add(body, Expand[2])    # gets twice…
+      #   add(side, Expand[1])    # …what this one gets
+      #
+      # Main axis only — {Box#add} rejects one passed as `cross:`, where a child
+      # has no siblings to compete with and so nothing for a weight to mean.
+      #
+      # @!attribute [r] weight
+      #   @return [Integer] relative share of the leftover space.
+      class Expand < Data.define(:weight)
+        # @param weight [Integer] relative share; `>= 1`.
+        # @raise [ArgumentError] unless `weight` is a positive Integer.
+        def initialize(weight:)
+          unless weight.is_a?(Integer) && weight.positive?
+            raise ArgumentError, "Expand expects a positive Integer weight, got #{weight.inspect}"
+          end
+
+          super
+        end
+      end
+
+      # Per-edge padding for a {Box}, in cells:
+      #
+      #   Insets[top: 1]                     # one blank row above the children
+      #   Insets[top: 1, left: 2, right: 2]  # unnamed edges default to 0
+      #   Insets.coerce(1)                   # uniform on all four edges
+      #
+      # Keyword-only: AWT and JavaFX order these same four numbers differently,
+      # so a positional form would be a coin flip.
+      #
+      # @!attribute [r] top
+      #   @return [Integer] cells inset from the top edge.
+      # @!attribute [r] right
+      #   @return [Integer] cells inset from the right edge.
+      # @!attribute [r] bottom
+      #   @return [Integer] cells inset from the bottom edge.
+      # @!attribute [r] left
+      #   @return [Integer] cells inset from the left edge.
+      class Insets < Data.define(:top, :right, :bottom, :left)
+        # @param positional [Array] must be empty — see the class doc.
+        # @param kwargs [Hash{Symbol => Integer}] any of `top:`/`right:`/`bottom:`/`left:`.
+        # @raise [ArgumentError] if any positional argument is given.
+        # @return [Insets]
+        def self.new(*positional, **kwargs)
+          raise ArgumentError, "Insets is keyword-only, got #{positional.inspect}" unless positional.empty?
+
+          super(**kwargs)
+        end
+
+        # Needed because `Data`'s inherited `[]` never dispatches through a `new`
+        # override, so the guard above alone would miss `Insets[1, 2, 3, 4]`.
+        # @param positional [Array] must be empty.
+        # @param kwargs [Hash{Symbol => Integer}] any of `top:`/`right:`/`bottom:`/`left:`.
+        # @raise [ArgumentError] if any positional argument is given.
+        # @return [Insets]
+        def self.[](*positional, **kwargs) = new(*positional, **kwargs)
+
+        # @param value [Insets, Integer] an Integer becomes a uniform inset.
+        # @raise [ArgumentError] on anything else, or a negative Integer.
+        # @return [Insets]
+        def self.coerce(value)
+          return value if value.is_a?(Insets)
+          unless value.is_a?(Integer) && !value.negative?
+            raise ArgumentError, "expected Insets or a non-negative Integer, got #{value.inspect}"
+          end
+
+          new(top: value, right: value, bottom: value, left: value)
+        end
+
+        # @param top [Integer] cells inset from the top edge; `>= 0`.
+        # @param right [Integer] cells inset from the right edge; `>= 0`.
+        # @param bottom [Integer] cells inset from the bottom edge; `>= 0`.
+        # @param left [Integer] cells inset from the left edge; `>= 0`.
+        # @raise [ArgumentError] unless every edge is a non-negative Integer.
+        def initialize(top: 0, right: 0, bottom: 0, left: 0)
+          { top:, right:, bottom:, left: }.each do |edge, cells|
+            unless cells.is_a?(Integer) && !cells.negative?
+              raise ArgumentError, "Insets #{edge}: expected a non-negative Integer, got #{cells.inspect}"
+            end
+          end
+
+          super
+        end
+
+        # @return [Integer] `left` + `right`.
+        def horizontal = left + right
+
+        # @return [Integer] `top` + `bottom`.
+        def vertical = top + bottom
+
+        # No padding on any edge.
+        # @return [Insets]
+        ZERO = new
+      end
 
       # Layouts are focusable containers — like {Window} and {Popup}, they
       # don't accept input themselves but they need to participate in the
@@ -36,11 +176,7 @@ module Tuile
         if child.is_a? Enumerable
           child.each { add(_1) }
         else
-          raise TypeError, "expected Component, got #{child.inspect}" unless child.is_a? Component
-          raise ArgumentError, "#{child} already has a parent #{child.parent}" unless child.parent.nil?
-
-          @children << child
-          child.parent = self
+          add_child(child)
         end
       end
 
@@ -50,10 +186,8 @@ module Tuile
         raise TypeError, "expected Component, got #{child.inspect}" unless child.is_a? Component
         raise ArgumentError, "#{child}'s parent is #{child.parent}, not this layout #{self}" if child.parent != self
 
-        child.parent = nil
-        @children.delete(child)
-        invalidate if @children.empty?
-        on_child_removed(child)
+        remove_child(child)
+        invalidate if @children.empty? # nothing left to paint over the gap
       end
 
       # Dispatches the event to the child under the mouse cursor.

data/lib/tuile/component/list.rb

@@ -6,11 +6,9 @@ module Tuile
     #
     # Items are modeled as {StyledString}s and painted directly into the
     # component's {#rect}. Lines wider than the viewport are ellipsized via
-    # {StyledString#ellipsize} (span styles are preserved across the cut —
-    # unlike the older ANSI-as-bytes truncation, color does *not* get
-    # dropped on the surviving characters). Vertical scrolling is supported
-    # via {#top_line}; the list can also automatically scroll to the bottom
-    # if {#auto_scroll} is enabled.
+    # {StyledString#ellipsize} with span styles preserved across the cut.
+    # Vertical scrolling is via {#top_line}; enable {#auto_scroll} to keep the
+    # bottom in view.
     #
     # Cursor is supported; call {#cursor=} to change cursor behavior. The
     # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the
@@ -272,7 +270,10 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row of
       # {#rect} is painted below (with blank padding past the last item),
       # so the parent contract — "fully draw over your rect" — is met
-      # without an upfront wipe.
+      # without an upfront wipe. Rows go through {Component#draw_line}, so
+      # content *and* blank filler inherit {Component#effective_bg_color}
+      # (a {#bg_color} set here or on an ancestor); the cursor row's
+      # {Theme#active_bg_color} highlight composes on top of it.
       # @return [void]
       def repaint
         return if rect.empty?
@@ -282,7 +283,7 @@ module Tuile
                     end
         (0...rect.height).each do |row|
           line = paintable_line(row + @top_line, row, scrollbar)
-          screen.buffer.set_line(rect.left, row + rect.top, line)
+          draw_line(rect.left, row + rect.top, line)
         end
       end
 

data/lib/tuile/component/list_dropdown.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A borderless, tinted, non-focusable floating selection list — the dropdown
+    # a *driver* drops open, drives by forwarding movement keys, and commits a
+    # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
+    # focus stays on the driver while the caller refills the rows, moves the
+    # highlight, and reads the pick.
+    #
+    #   drop = Component::ListDropdown.new
+    #   drop.on_item_chosen = ->(index, _line) { commit(index) } # caller commits
+    #   # …then, from the driver's key handler:
+    #   drop.lines = matches.map { |m| render(m) }   # caller filters + renders
+    #   drop.anchor_to(rect, rows: matches.size)     # below the driver, or flipped
+    #   drop.open
+    #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
+    #   drop.choose if key == Keys::ENTER            # commit the highlight
+    #
+    # It owns only what every such dropdown shares — *placement* included, via
+    # {#anchor_to}. What stays with the driver: the width **policy** ({#anchor_to}
+    # measures nothing itself), filtering, row rendering, the commit action, and
+    # ESC/Enter handling. ESC and Enter carry driver-specific tails (ESC may
+    # revert a query; Enter may commit via {#choose} *or* via a separate submit
+    # path), so {#move} claims neither — the driver calls {#choose} and {#close}
+    # from its own branches.
+    #
+    # == Theming
+    # Borderless, told apart from the content beneath by a background tint —
+    # {Theme#input_bg_color} by default, assigned as a live {Theme::Ref} so it
+    # tracks light/dark flips with no hook. Reassign {Component#bg_color=} for a
+    # different tint (a `Theme.ref(:token)` keeps the flip-tracking).
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class ListDropdown < Popup
+      # The dropdown's {List}. Non-focusable on purpose: the driver forwards keys
+      # while focus stays on it, and a mouse click selects an item without
+      # stealing focus — so a driving text input never loses its caret
+      # mid-interaction.
+      class Menu < List
+        def focusable? = false
+        def tab_stop? = false
+      end
+
+      # Cursor-movement keys forwarded to the list by {#move}: the two vertical
+      # arrows, page up/down, and Ctrl+U/D half-page jumps. Deliberately excludes
+      # Home/End and `j`/`k` — a jump to the first/last row is the driver's call,
+      # and both drivers decline it ({ComboBox}'s field needs Home/End for the
+      # caret; {Select} would spend a branch on what a second arrow press already
+      # does) — and Enter/ESC, which carry driver-specific tails (see the class
+      # docs).
+      # @return [Array<String>]
+      MOVE_KEYS = [Keys::UP_ARROW, Keys::DOWN_ARROW, Keys::PAGE_UP, Keys::PAGE_DOWN,
+                   Keys::CTRL_U, Keys::CTRL_D].freeze
+
+      # Most rows shown before the list scrolls; {#anchor_to}'s `max_rows`
+      # default.
+      # @return [Integer]
+      MAX_VISIBLE_ROWS = 10
+
+      def initialize
+        @list = Menu.new
+        @list.cursor = List::Cursor.new
+        @list.show_cursor_when_inactive = true # highlight the selection though focus stays on the driver
+        super(content: @list, modal: false)
+        self.bg_color = Theme.ref(:input_bg_color)
+      end
+
+      # @param lines [Array] the rows to show; see {List#lines=}.
+      # @return [void]
+      def lines=(lines)
+        @list.lines = lines
+      end
+
+      # @return [Array<StyledString>] the current rows.
+      def lines = @list.lines
+
+      # @param proc [Proc, Method, nil] commit callback; see {List#on_item_chosen}.
+      # @return [void]
+      def on_item_chosen=(proc)
+        @list.on_item_chosen = proc
+      end
+
+      # @param cursor [List::Cursor] the highlight; see {List#cursor=}.
+      # @return [void]
+      def cursor=(cursor)
+        @list.cursor = cursor
+      end
+
+      # @return [List::Cursor] the list's cursor (the current highlight).
+      def cursor = @list.cursor
+
+      # Sizes and places the dropdown against `anchor`: directly beneath it,
+      # flipped above when `rows` won't fit below, clamped — with the list
+      # scrolling — when neither side has room. Horizontally the left edges line
+      # up, sliding left only far enough to keep the panel on screen.
+      #
+      #   drop.anchor_to(field.rect, rows: matches.size)            # field width
+      #   drop.anchor_to(rect, rows: items.size, width: measured)   # own width
+      #
+      # Vertical flips but horizontal slides because covering the driver would
+      # hide what is being chosen, while sharing its columns is the point.
+      #
+      # @param anchor [Rect] the driver's rect; the dropdown never covers it.
+      # @param rows [Integer] how many rows there are to show — the content
+      #   count, not the height: more than fits turns the scrollbar on. `0`
+      #   collapses the dropdown to an empty rect (drivers close instead).
+      # @param width [Integer] the panel's width in columns, clamped to the
+      #   screen. Defaults to the anchor's, which lines both edges up with a
+      #   field; a driver that measured its labels passes its own. A label wider
+      #   than the screen clips — {List} has no horizontal scrolling.
+      # @param max_rows [Integer] rows shown before the list scrolls.
+      # @return [void]
+      def anchor_to(anchor, rows:, width: anchor.width, max_rows: MAX_VISIBLE_ROWS)
+        desired = [rows, max_rows].min
+        below = screen.size.height - (anchor.top + 1)
+        above = anchor.top
+        if desired <= below
+          top = anchor.top + 1
+          height = desired
+        elsif above >= below
+          height = [desired, above].min
+          top = anchor.top - height
+        else
+          height = below
+          top = anchor.top + 1
+        end
+        width = [width, screen.size.width].min
+        self.size = Size.new(width, height)
+        self.rect = Rect.new([anchor.left, screen.size.width - width].min.clamp(0, nil), top, width, height)
+        # After the geometry: the setter rebuilds the list's padded rows against
+        # the width it can see, and the gutter takes a column off it.
+        @list.scrollbar_visibility = rows > height ? :visible : :gone
+      end
+
+      # Forwards a cursor-movement key to the list. The driver calls this from
+      # its own key handler; a truthy return means "consumed — stop here", falsy
+      # means "not mine — proceed with normal editing/dispatch". Only {MOVE_KEYS}
+      # are claimed, and only while open.
+      # @param key [String]
+      # @return [Boolean] true iff the key was consumed.
+      def move(key)
+        return false unless open? && MOVE_KEYS.include?(key)
+
+        @list.handle_key(key)
+        true
+      end
+
+      # Commits the highlighted row by firing {List#on_item_chosen}, exactly as
+      # pressing Enter on the focused list would — the driver calls this from its
+      # own Enter branch.
+      # @return [Boolean] true iff a row was chosen (false when the cursor is
+      #   off-content).
+      def choose = @list.handle_key(Keys::ENTER)
+    end
+  end
+end

data/lib/tuile/component/password_field.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A {TextField} that paints one mask glyph per character instead of the
+    # text. Editing, caret, clicks and horizontal scrolling are the field's,
+    # unchanged:
+    #
+    #   pf = Component::PasswordField.new
+    #   pf.rect  = Rect.new(0, 0, 20, 1)
+    #   pf.value                          # => the plaintext String
+    #   pf.mask_char = "•"                # default "*"
+    #   pf.revealed  = true               # show the plaintext, e.g. behind a Checkbox
+    #
+    # A password's value *is* its text, so this subclasses {TextField} rather
+    # than composing one the way {IntegerField} does — the delta is presentation
+    # only, and it lands entirely on {TextField#display_text}.
+    #
+    # == What it hides, and what it doesn't
+    # The plaintext is an ordinary Ruby `String`: not pinned, not wiped, not
+    # kept out of GC. Anything stronger needs a frozen-buffer type and the
+    # cooperation of every consumer, which is out of scope for a widget.
+    #
+    # The mask shows the text's *length* — accepted, since a caret has to sit
+    # somewhere. Its *word structure* is hidden: CTRL+LEFT / CTRL+RIGHT jump to
+    # the ends while masked instead of hopping the spaces a watcher could then
+    # read off the caret. They resume word-jumping when {#revealed}.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class PasswordField < TextField
+      def initialize
+        super
+        @mask_char = "*"
+        @revealed = false
+      end
+
+      # @return [String] the glyph painted per character; `"*"` by default.
+      attr_reader :mask_char
+
+      # The default is `"*"` rather than a prettier `"•"` because U+2022 is
+      # East-Asian-*Ambiguous*: a CJK-configured terminal draws it two columns
+      # wide, shifting every column past the caret. Validation can't catch that
+      # one — Tuile measures Ambiguous as 1 by construction — so the default
+      # carries it, and this setter is the knob for someone who knows their
+      # terminal.
+      # @param char [String] one grapheme cluster, one column wide.
+      # @return [void]
+      # @raise [TypeError] unless `char` is a String.
+      # @raise [ArgumentError] if `char` isn't exactly one single-column
+      #   grapheme cluster — a multi-cluster mask would break the
+      #   one-glyph-per-character contract {TextField#display_text} rests on,
+      #   a wide one the column axis.
+      def mask_char=(char)
+        raise TypeError, "expected String, got #{char.inspect}" unless char.is_a?(String)
+        raise ArgumentError, "expected one grapheme cluster, got #{char.inspect}" unless single_cluster?(char)
+        raise ArgumentError, "expected a 1-column glyph, got #{char.inspect}" unless Buffer.display_width(char) == 1
+
+        return if @mask_char == char
+
+        @mask_char = char
+        invalidate
+      end
+
+      # @return [Boolean] whether the plaintext is shown; `false` by default.
+      attr_reader :revealed
+
+      # @return [Boolean] {#revealed} in predicate form.
+      def revealed? = @revealed
+
+      # Shows or re-masks the plaintext. There is no built-in reveal *button* —
+      # a TTY field has no room for an in-field affordance — so an app flips
+      # this from a key binding or a sibling {Checkbox}.
+      # @param flag [Object] anything; truthiness decides.
+      # @return [void]
+      def revealed=(flag)
+        flag = flag ? true : false
+        return if @revealed == flag
+
+        @revealed = flag
+        # The plaintext and the mask differ in *columns* (a CJK passphrase is
+        # wider than its mask), so the scroll window has to be recomputed —
+        # the caret index it must keep visible has not moved.
+        adjust_left_column
+        invalidate
+      end
+
+      protected
+
+      # @return [String] the mask, one glyph per character, unless {#revealed}.
+      def display_text = revealed? ? super : @mask_char * @text.length
+
+      private
+
+      # @param char [String]
+      # @return [Boolean]
+      def single_cluster?(char) = char.each_grapheme_cluster.take(2).size == 1
+
+      # @return [Integer] caret target for CTRL+LEFT: the start, while masked.
+      def word_left = revealed? ? super : 0
+
+      # @return [Integer] caret target for CTRL+RIGHT: the end, while masked.
+      def word_right = revealed? ? super : @text.length
+    end
+  end
+end

data/lib/tuile/component/popup.rb

@@ -18,16 +18,11 @@ module Tuile
     #
     # Modal by default: it centers on the screen, grabs focus, eats keys, and
     # blocks clicks beneath it. Pass `modal: false` for a non-modal overlay
-    # that floats above the content (still painted on top) without taking focus
-    # or capturing input — the caller positions it (via {#rect=}) and drives it
-    # from app code. That is the building block for an autocomplete/slash-command
-    # list anchored to a {Component::TextField} or {Component::TextArea} caret:
-    # typing keeps focus (and the cursor) in the input, an
-    # {Component::TextInput#on_change} listener refills the list, and an
-    # {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
-    # Such a caller owns the list data, so it sizes the overlay itself
-    # (`overlay.size = Size.new(longest, [items.size, 8].min)`) — still
-    # caller-decides, top-down.
+    # that floats above the content without taking focus or capturing input —
+    # the caller positions it (via {#rect=}), sizes it, and drives it from app
+    # code. That's the building block for an autocomplete/slash-command list
+    # anchored to a text field's caret: typing keeps focus in the input while
+    # the caller refills and drives the overlay.
     #
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -40,10 +35,11 @@ module Tuile
     # Bare content also works (a {Component::Label}, a {Component::List}…), in
     # which case the popup is borderless.
     #
-    # `q` and ESC close the popup. Any nested {Component::TextField} that owns
-    # the hardware cursor swallows printable keys first via the standard
-    # cursor-owner suppression in {Component#handle_key}, so typing `q` into a
-    # text field doesn't dismiss the popup.
+    # `q` and ESC close the popup — handled here, at the top of the popup's own
+    # subtree, so the key only arrives after every component on the focus chain
+    # declined it (see {ScreenPane#handle_key}). That's why typing `q` into a
+    # nested {Component::TextField} doesn't dismiss the popup: the field
+    # consumes it first.
     class Popup < Component
       include Component::HasContent