tuile 0.1.0 → 0.2.0

data/sig/tuile.rbs

@@ -26,9 +26,13 @@ module Tuile
     UP_ARROWS: ::Array[String]
     LEFT_ARROW: String
     RIGHT_ARROW: String
+    CTRL_LEFT_ARROW: String
+    CTRL_RIGHT_ARROW: String
     ESC: String
     HOME: String
     END_: String
+    HOMES: ::Array[String]
+    ENDS_: ::Array[String]
     PAGE_UP: String
     PAGE_DOWN: String
     BACKSPACE: String
@@ -38,6 +42,8 @@ module Tuile
     CTRL_U: String
     CTRL_D: String
     ENTER: String
+    TAB: String
+    SHIFT_TAB: String
 
     # Grabs a key from stdin and returns it. Blocks until the key is obtained.
     # Reads a full ESC key sequence; see constants above for some values returned
@@ -212,6 +218,19 @@ module Tuile
     # function exits when the 'ESC' or 'q' key is pressed.
     def run_event_loop: () -> void
 
+    # 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_ — true if focus moved.
+    def focus_next: () -> bool
+
+    # Mirror of {#focus_next} that walks backwards through the tab order.
+    # 
+    # _@return_ — true if focus moved.
+    def focus_previous: () -> bool
+
     # _@return_ — current active tiled component.
     def active_window: () -> Component?
 
@@ -240,7 +259,23 @@ module Tuile
 
     def self.close: () -> void
 
-    # 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` — stuff to print.
     def print: (*String args) -> void
@@ -255,6 +290,17 @@ module Tuile
     # but only one focused.
     def cursor_position: () -> Point?
 
+    # 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`
+    # 
+    # _@return_ — true if focus moved.
+    def cycle_focus: (forward: bool) -> bool
+
     # Collects a component and all its descendants in tree order
     # (parent before children).
     # 
@@ -276,6 +322,11 @@ 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`
     # 
     # _@return_ — true if the key was handled by some window.
@@ -322,6 +373,39 @@ module Tuile
     attr_accessor focused: Component?
   end
 
+  # Truncates a string to a given column width, preserving ANSI escape
+  # sequences and accounting for Unicode display width. Truncated output is
+  # suffixed with an ellipsis (`…`).
+  # 
+  # Extracted from `strings-truncation` 0.1.0 (MIT, Piotr Murach) — only the
+  # default end-position, default-omission, no-separator path Tuile uses.
+  module Truncate
+    ANSI_REGEXP: Regexp
+    RESET: String
+    RESET_REGEXP: Regexp
+    END_REGEXP: Regexp
+    OMISSION: String
+    OMISSION_WIDTH: Integer
+
+    # Truncate `text` to at most `length` display columns. ANSI escape
+    # sequences pass through without consuming budget; when characters are
+    # dropped, an ellipsis (`…`) is appended (and counts toward `length`).
+    # 
+    # _@param_ `text`
+    # 
+    # _@param_ `length` — target column width. A `nil` returns `text` unchanged.
+    def truncate: (String text, length: Integer?) -> String
+
+    # Truncate `text` to at most `length` display columns. ANSI escape
+    # sequences pass through without consuming budget; when characters are
+    # dropped, an ellipsis (`…`) is appended (and counts toward `length`).
+    # 
+    # _@param_ `text`
+    # 
+    # _@param_ `length` — target column width. A `nil` returns `text` unchanged.
+    def self.truncate: (String text, length: Integer?) -> String
+  end
+
   # A UI component which is positioned on the screen and draws characters into
   # its bounding rectangle (in {#repaint}).
   # 
@@ -336,12 +420,28 @@ module Tuile
     # Focuses this component. Equivalent to `screen.focused = self`.
     def focus: () -> void
 
-    # Repaints the component. Default implementation does nothing.
+    # Repaints the component.
+    # 
+    # The default does the bookkeeping that almost every component would
+    # otherwise have to remember: it clears the background and re-invalidates
+    # any direct children whose rects leave gaps in {#rect}. Concretely:
+    # 
+    # - Leaf (no children): always clears, so subclasses can paint their
+    #   content directly without an explicit `clear_background` call.
+    # - Container with children that fully tile {#rect}: skipped — the
+    #   children themselves will repaint and cover everything.
+    # - Container with gappy children (e.g. a form layout where widgets
+    #   don't tile): clears, then invalidates the children so they re-paint
+    #   on top of the cleared background. This is what makes mixed
+    #   field/button forms safe without each container learning a custom
+    #   damage-tracking pass.
     # 
-    # The component must fully draw over {#rect}, and must not draw outside of
-    # {#rect}.
+    # Subclasses that paint their entire rect themselves (e.g. {Window}'s
+    # border draws over the area the default would clear; {Component::List}
+    # explicitly paints every row) may skip super and take full
+    # responsibility for {#rect}. Everything else should call super.
     # 
-    # Tip: use {#clear_background} to clear component background before painting.
+    # A component must not draw outside of {#rect}.
     def repaint: () -> void
 
     # Called when a character is pressed on the keyboard.
@@ -386,9 +486,23 @@ module Tuile
     # only focusable ones can become a focus target that puts themselves and
     # their ancestors on the active chain.
     # 
+    # See also {#tab_stop?}: focusable controls _can_ receive focus (via click
+    # or programmatic assignment), but only tab stops participate in Tab /
+    # Shift+Tab cycling. Containers like {Window} and {Popup} are focusable
+    # (so a click on chrome lands focus) but are not tab stops.
+    # 
     # _@return_ — true if this component can be focused.
     def focusable?: () -> bool
 
+    # Whether this component participates in Tab / Shift+Tab focus cycling.
+    # `false` by default. Only true on components that accept direct user
+    # input (e.g. {TextField}, {List}, {Component::Button}). Implies
+    # {#focusable?} — Screen will skip non-focusable tab stops, but in
+    # practice every override should keep the two consistent.
+    # 
+    # _@return_ — true if Tab / Shift+Tab should land on this component.
+    def tab_stop?: () -> bool
+
     # _@return_ — the distance from the root component; 0 if {#parent}
     # is nil.
     def depth: () -> Integer
@@ -450,6 +564,15 @@ module Tuile
     # needs-repaint and once all events are processed, will call {#repaint}.
     def invalidate: () -> void
 
+    # Whether direct children fully tile {#rect}. Used by the default
+    # {#repaint} to decide whether the framework needs to wipe gaps.
+    # 
+    # Approximated by area: sum of (non-empty) child areas vs the parent's
+    # area. Cheap, and correct as long as siblings don't overlap each other
+    # — which Tuile already requires (no clipping in the tiled tree).
+    # Children with empty rects contribute zero, since they paint nothing.
+    def children_tile_rect?: () -> bool
+
     # Clears the background: prints spaces into all characters occupied by the
     # component's rect.
     def clear_background: () -> void
@@ -513,6 +636,8 @@ module Tuile
 
       def focusable?: () -> bool
 
+      def tab_stop?: () -> bool
+
       # _@param_ `key` — a key.
       # 
       # _@return_ — true if the key was handled.
@@ -542,6 +667,11 @@ module Tuile
       def handle_mouse: (MouseEvent event) -> void
 
       # Paints the list items into {#rect}.
+      # 
+      # Skips the {Component#repaint} default's auto-clear: every row of
+      # {#rect} is painted below (with padded content past the last item),
+      # so the parent contract — "fully draw over your rect" — is met
+      # without an upfront wipe.
       def repaint: () -> void
 
       # _@return_ — true if the cursor sits on a real content line.
@@ -551,6 +681,14 @@ module Tuile
       # Caller must ensure {#cursor_on_item?}.
       def fire_item_chosen: () -> void
 
+      # _@return_ — `[position, line_at_position]`,
+      # with `line` nil when the cursor is off-content.
+      def cursor_state: () -> [[Integer, String, NilClass]]
+
+      # Fires {#on_cursor_changed} if {#cursor_state} differs from the last
+      # fired state. Idempotent — safe to call after any mutation.
+      def notify_cursor_changed: () -> void
+
       # _@param_ `query`
       # 
       # _@param_ `include_current`
@@ -627,6 +765,16 @@ module Tuile
       # {Cursor::None}, or empty content).
       attr_accessor on_item_chosen: Proc?
 
+      # _@return_ — callback fired when the `(index, line)` tuple under
+      # the cursor changes. Called as `proc.call(index, line)` where `line`
+      # is `nil` when the cursor is off-content ({Cursor::None}, empty list,
+      # or `index` past the last line). Fires on cursor moves (key, mouse,
+      # search), on {#cursor=}, and on {#lines=}/{#add_lines} when the line
+      # at the cursor's index changes (or its in-range/out-of-range status
+      # flips). Useful for keeping a details pane in sync with the
+      # highlighted row.
+      attr_accessor on_cursor_changed: Proc?
+
       # _@return_ — if true and a line is added or new content is set,
       # auto-scrolls to the bottom.
       attr_accessor auto_scroll: bool
@@ -854,17 +1002,70 @@ module Tuile
       def on_focus: () -> void
     end
 
+    # A clickable button. Activated by Enter, Space, or a left mouse click;
+    # fires the {#on_click} callback. Renders as `[ caption ]` on a single
+    # row; the background is highlighted when the button is focused so the
+    # user can see which button is active.
+    # 
+    # Buttons are tab stops — Tab and Shift+Tab will land on them as part of
+    # the standard focus cycle. Click-to-focus also works via the inherited
+    # {Component#handle_mouse}.
+    # 
+    # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
+    # show `[ caption ]`; {#content_size} reports that natural width.
+    class Button < Component
+      # _@param_ `caption` — the button's label.
+      def initialize: (?String caption) -> void
+
+      def focusable?: () -> bool
+
+      def tab_stop?: () -> bool
+
+      # _@return_ — natural width is `caption.length + 4` to fit
+      # `[ caption ]`; height is 1.
+      def content_size: () -> Size
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      # _@return_ — the button's label.
+      attr_accessor caption: String
+
+      # Callback fired when the button is activated (Enter, Space, or
+      # left-click). The callable receives no arguments.
+      # 
+      # _@return_ — no-arg callable, or nil.
+      attr_accessor on_click: (Proc | Method)?
+    end
+
     # A layout doesn't paint anything by itself: its job is to position child
     # components.
     # 
-    # All children must completely cover the contents of a layout: that way,
-    # the layout itself doesn't have to draw and no clipping algorithm is
-    # necessary.
+    # Children that fully tile the layout's rect repaint themselves and
+    # cover everything; children that leave gaps (e.g. a form with widgets
+    # of varying widths) trigger {Component#repaint}'s default behavior —
+    # the background is cleared and children are re-invalidated so they
+    # paint over a clean surface.
     class Layout < Component
       def initialize: () -> void
 
       def children: () -> ::Array[Component]
 
+      # Layouts are focusable containers — like {Window} and {Popup}, they
+      # don't accept input themselves but they need to participate in the
+      # {HasContent} focus cascade so a Popup wrapping a Layout wrapping a
+      # {TextField} ends up focusing the field rather than parking focus on
+      # the popup. Layouts don't paint any visible chrome of their own
+      # (the auto-cleared background is just blank space), so this has no
+      # mouse-routing consequences — clicks on a gap area land back on the
+      # Layout itself and the on_focus cascade forwards to a tab stop.
+      def focusable?: () -> bool
+
       # Adds a child component to this layout.
       # 
       # _@param_ `child`
@@ -875,8 +1076,6 @@ module Tuile
 
       def content_size: () -> Size
 
-      def repaint: () -> void
-
       # Dispatches the event to the child under the mouse cursor.
       # 
       # _@param_ `event`
@@ -938,6 +1137,15 @@ module Tuile
       def visible?: () -> bool
 
       # Fully repaints the window: both frame and contents.
+      # 
+      # Window deliberately paints over its entire rect (border around the
+      # edge, content/footer over the interior), so we don't need the
+      # {Component#repaint} default's auto-clear — but we do still want its
+      # "re-invalidate children" effect, since the border overpaints
+      # whatever the content/footer drew on the perimeter. Calling super
+      # handles both: the auto-clear is harmless (we re-paint over it), and
+      # the invalidation queues content + footer for repaint in the same
+      # cycle.
       def repaint: () -> void
 
       # _@param_ `key`
@@ -972,6 +1180,119 @@ module Tuile
       attr_accessor caption: String
     end
 
+    # A multi-line, word-wrapping text input.
+    # 
+    # Sized by the caller — {#rect} is fixed; the area does not grow with
+    # content. Text is wrapped to {Rect#width} columns and any text that
+    # doesn't fit vertically is reached by scrolling: {#top_display_row}
+    # follows the caret so the line being edited stays visible. There is no
+    # horizontal scrolling.
+    # 
+    # The caret is a logical index in `0..text.length`. When the caret falls
+    # inside a whitespace run that was absorbed by a soft wrap, it displays
+    # at the end of the previous row (which is visually identical to the
+    # start of the next row in nearly all cases).
+    # 
+    # Currently only {#on_change} is wired; Enter inserts a newline as in any
+    # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
+    # callback may opt out of that by consuming Enter instead.
+    class TextArea < Component
+      ACTIVE_BG_SGR: String
+      INACTIVE_BG_SGR: String
+      SGR_RESET: String
+
+      def initialize: () -> void
+
+      def focusable?: () -> bool
+
+      def tab_stop?: () -> bool
+
+      def cursor_position: () -> Point?
+
+      # _@param_ `key`
+      def handle_key: (String key) -> bool
+
+      # _@param_ `event`
+      def handle_mouse: (MouseEvent event) -> void
+
+      def repaint: () -> void
+
+      def on_width_changed: () -> void
+
+      # _@return_ — cached wrap of {#text} for the
+      # current {Rect#width}. Each entry is `{start:, length:}`.
+      def display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+
+      # Greedy word-wrap. Whitespace at a soft-wrap break point is absorbed
+      # (not rendered on either row). A token longer than {Rect#width} hard-
+      # wraps inside the token. Newlines force a hard break and the wrap
+      # restarts on the next character.
+      def compute_display_rows: () -> ::Array[::Hash[Symbol, Integer]]
+
+      # Trims trailing space/tab characters off a row's visible length so the
+      # whitespace at a soft-wrap point is absorbed (not rendered) rather than
+      # left at the end of the row. Without this, soft-wrapping `"foo bar"`
+      # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
+      # end-of-row caret position would coincide with row 1's start.
+      # 
+      # _@param_ `row_start`
+      # 
+      # _@param_ `row_chars`
+      # 
+      # _@return_ — new row_chars.
+      def trim_trailing_whitespace: (Integer row_start, Integer row_chars) -> Integer
+
+      # _@param_ `caret`
+      # 
+      # _@return_ — `[row_index, column]` for `caret`.
+      def caret_to_display: (Integer caret) -> [Integer, Integer]
+
+      # _@param_ `delta` — `+1` for down, `-1` for up.
+      def move_caret_vertical: (Integer delta) -> void
+
+      def move_caret_to_row_start: () -> void
+
+      def move_caret_to_row_end: () -> void
+
+      # _@param_ `char`
+      # 
+      # _@return_ — always true.
+      def insert_char: (String char) -> bool
+
+      def delete_before_caret: () -> void
+
+      def delete_at_caret: () -> void
+
+      # Keeps the caret visible by scrolling vertically.
+      def adjust_top_display_row: () -> void
+
+      # _@param_ `key`
+      def printable?: (String key) -> bool
+
+      # Same semantics as {TextField}'s ctrl+left.
+      def word_left: () -> Integer
+
+      # Same semantics as {TextField}'s ctrl+right.
+      def word_right: () -> Integer
+
+      # _@return_ — current text contents (may contain embedded `\n`).
+      attr_accessor text: String
+
+      # _@return_ — caret index in `0..text.length`.
+      attr_accessor caret: Integer
+
+      # _@return_ — index of the topmost display row currently visible.
+      attr_reader top_display_row: Integer
+
+      # Optional callback fired whenever {#text} changes. Receives the new text
+      # as a single argument. Not fired by {#caret=} (text unchanged), not
+      # fired by a no-op setter, and not fired by a re-wrap caused by a width
+      # change ({#text} itself is unchanged).
+      # 
+      # _@return_ — one-arg callable, or nil.
+      attr_accessor on_change: (Proc | Method)?
+    end
+
     # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
     # log lines into this window:
     # 
@@ -1015,10 +1336,16 @@ module Tuile
     # positioned by {Screen} after each repaint cycle when this component is
     # focused; see {Component#cursor_position}.
     class TextField < Component
+      ACTIVE_BG_SGR: String
+      INACTIVE_BG_SGR: String
+      SGR_RESET: String
+
       def initialize: () -> void
 
       def focusable?: () -> bool
 
+      def tab_stop?: () -> bool
+
       def cursor_position: () -> Point?
 
       # _@param_ `key`
@@ -1044,6 +1371,16 @@ module Tuile
       # _@param_ `key`
       def printable?: (String key) -> bool
 
+      # Caret target for ctrl+left: skip whitespace going left, then a run of
+      # non-whitespace. Lands at the beginning of the current word, or the
+      # beginning of the previous word if already there.
+      def word_left: () -> Integer
+
+      # Caret target for ctrl+right: skip non-whitespace going right, then a
+      # run of whitespace. Lands at the beginning of the next word, or at the
+      # end of the text if no further word exists.
+      def word_right: () -> Integer
+
       # _@return_ — current text contents.
       attr_accessor text: String
 
@@ -1433,13 +1770,26 @@ module Tuile
 
     # 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`
     def on_child_removed: (Component child) -> void
 
+    # 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`
+    def first_tab_stop_or_root: (Component? root) -> Component?
+
     # _@return_ — the tiled content component.
     attr_accessor content: Component?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tuile
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Martin Vysny
@@ -51,20 +51,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
-- !ruby/object:Gem::Dependency
-  name: strings-truncation
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: tty-cursor
   requirement: !ruby/object:Gem::Requirement
@@ -145,8 +131,10 @@ files:
 - README.md
 - examples/file_commander.rb
 - examples/hello_world.rb
+- examples/sampler.rb
 - lib/tuile.rb
 - lib/tuile/component.rb
+- lib/tuile/component/button.rb
 - lib/tuile/component/has_content.rb
 - lib/tuile/component/info_window.rb
 - lib/tuile/component/label.rb
@@ -155,6 +143,7 @@ files:
 - lib/tuile/component/log_window.rb
 - lib/tuile/component/picker_window.rb
 - lib/tuile/component/popup.rb
+- lib/tuile/component/text_area.rb
 - lib/tuile/component/text_field.rb
 - lib/tuile/component/window.rb
 - lib/tuile/event_queue.rb
@@ -167,6 +156,7 @@ files:
 - lib/tuile/screen.rb
 - lib/tuile/screen_pane.rb
 - lib/tuile/size.rb
+- lib/tuile/truncate.rb
 - lib/tuile/version.rb
 - lib/tuile/vertical_scroll_bar.rb
 - sig/tuile.rbs
@@ -184,14 +174,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A component-oriented terminal UI toolkit for Ruby.
 test_files: []