typr 1.9.0 → 1.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74b0a2cd082b9a2ee58f9fb64356a7ed4f5a970c0427768acae334ae3325748a
-  data.tar.gz: af90bbcfff025ba60f1d8de7cae5171152f8939a00a7fac5975cc95785a28547
+  metadata.gz: cdabc3f928eb42904b0f1cd0778384bca290ae56dfbb050236cda6a6578d19e8
+  data.tar.gz: 236970a28d8cd9265651985504a60a8113cdfaf2b8378303388c0a9e4883469e
 SHA512:
-  metadata.gz: c29e087834938ef34608086cb90ec221760ca50f0be054e7d9602f46cc6e63c73fbe06a960c8b55e551b17159f404d796f275e3a11cddcb3f70baccefc67636b
-  data.tar.gz: a33662ba4009f34cef2e91b5295a6fc1e3f2b17ebd9edf118052caa016e6dc0d8dd4d6f2c3fb468244f2e488e589c1ec79236f2a7001bc4e6622064fcf9a3365
+  metadata.gz: 82420afecbc67164d9271e315cd571f33898f4f4ae4ee4186da231cbb6d461df5714180e47c6237d7a54224fd0742777084d44c38e221931f763418bdc19df7d
+  data.tar.gz: cafd2cf36cdbf58e70249042e7952ca1048325b61ae404b0c4a154eabcb9684cbe8bf75b3aaee239d0c169da7057826a1b7e1bcae1e6dd2b81fa9145942424d9

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [vx.y.z] — __DATE__
 
+## [v1.9.3] — 2026-10-19
+
+### Fixed
+- Grid rendering can no longer crash with `ArgumentError: negative argument` on emoji-wide cell text — the pad in `prepare` is clamped at zero, and `clip` measures grapheme clusters (flags, `‼️`-style presentation sequences) instead of single chars so its width accounting matches `real_size`
+- Numeric hints no longer vanish when the list shrinks below the Tab-cycled hint offset (after a `move`/transfer or `cd` into a smaller directory) — `show` re-clamps `hints_start` so the existing single redraw shows the digits again without any extra drawing
+- A one-entry filtered pick auto-returns before the popup is drawn — `Grid#pick` checks the initial match set before showing, so a single-entry grid returns its entry without ever displaying
+- The `text` example wires `regex: :generic` colors into its Text widget, so regex highlighting is demonstrated out of the box
+
+## [v1.9.2] — 2026-10-13
+
+### Fixed
+- Text renders multibyte UTF-8 correctly — `show` split rows through StringIO, whose byte-based reads and positions shifted and garbled every row after the first multibyte character; page rows are sliced by character offsets instead. Chunks that fill the viewport exactly also record a line break now instead of merging with (and hiding) their continuation
+
+## [v1.9.1] — 2026-10-12
+
+### Changed
+- `rake docs:check` — fails when any class, method, attribute, or constant is undocumented (CI-style gate for the RI pass; currently 221/221)
+
 ## [v1.9.0] — 2026-10-12
 
 ### Changed
@@ -11,7 +29,9 @@
 - Live list narrowing is labeled `[/]:narrow`, not `[/]:search` — the bar action shrinks the listing as you type, while `search` keeps meaning only pager find-in-text (`/`, `n`, `p`). The method is renamed `Browser#search` → `#narrow` (`search` stays as an alias, so stale configs wired to `!search` keep working)
 
 ### Fixed
+- Aborting the mark-range prompt no longer crashes — Escape returns nil from `ask` and `mark_range` passed it straight to `join`; it now returns nil like `mark`
 - Overtype guard scoped to `Grid#pick` and fixed for canonical ttys — private `drain_quiet` (called bare by `read_key`) waits out an armed window in raw mode, since canonical-buffered keystrokes are invisible to `select` and the old guard timed out only to deliver them late; each arrival restarts the window; `flush_overtype` and the `quiet_window?` predicate are gone, `drain_input` is back to a plain pending-bytes flush, and `suppress_keys` remains the sole arming seam for `Grid#pick` selections (filecon drops its two `flush_overtype` calls)
+- RI accepted-values pass — every enum-like parameter now lists its values with examples: `Stack#pick` documents all types (`:row`/`:rows`, `:column`/`:columns`, `:field(s)`, `:relative_row`, `:none`) with per-type returns and the Grid/Text-only constraint; `Grid` format tokens (`Integer`/`:min`/`:max`) explained and the `:right`-in-format examples corrected (alignment is `align:`, numbers auto-right-align); `Grid#pick` column and `add_filter` column are `Integer`/`:all` only; `Line#ask` documents the `with:`-as-question convention; `read_line` gains full `@param`s plus the single-arg completions contract; `Stack#send`/`Browser#pick` gain `@param`/`@return`; stale claims removed (`keysyms`, `colors[:dir_history]`, `cd` dir_history, `sorted_by` false, README `cli` `completions:`); three one-word code fixes where docs were right and code wrong (`Grid#<<`/`Text#build` return `self`, `Line#append` returns the content, as their examples claim)
 - Doc comments corrected where they disagreed with the code — `Grid#header=` defines `Typr::NAME` holding the column index (not `NAME_0 = "name"`); the mouse header-click sort doc sat on `sort_by` instead of `Grid#send`; `Grid#pick` now documents the single-match auto-return, the 0.5s overtype quiet window, and `:none` disabling both; `Line#ask` documents the `[:line, { initial: }]` inline-editor form; `Line#cli` no longer mentions a removed `completions:` option; `Browser#bottom` reserves only the command-line row (the path bar is `top`)
 
 ## [v1.8.0] — 2026-10-11

data/README.md

@@ -67,7 +67,7 @@ Typr.init
     ["Carol",   35, "manager"]
   ],
   header:  ["Name", "Age", "Role"],
-  format:  [:min, :right, :max],
+  format:  [:min, :min, :max],
   colors:  { columns: [:yellow, :cyan, :magenta] }
 )
 
@@ -139,7 +139,7 @@ class MyApp
         ["Item C", 20, true]
       ],
       header:  ["Name", "Qty", "Active"],
-      format:  [:max, :right, :min],
+      format:  [:max, :min, :min],
       colors:  { columns: [:yellow, :cyan, :green] }
     )
     @prompt = Typr::Line.new(
@@ -202,10 +202,10 @@ Strict question types:
 The question and answer are rendered in `@colors[:question]`/`@colors[:answer]`.
 
 ### `Line#cli`
-Prompts for a single command line with TAB completion matched against the shell (bash commands, options, and files). `completions: true` switches on the content; `initial:` seeds the line; `redraw:` repaints while the completion grid is up. With `regex: :shell` the typed command tints red for the first word, blue for `--options`. Completion candidates are plain strings.
+Prompts for a single command line with TAB completion matched against the shell (bash commands, options, and files). `initial:` seeds the line; `history:` recalls previous commands with Up/Down; `prefixes:` lists command-start characters stripped before matching; `redraw:` repaints while the completion grid is up. With `regex: :shell` the typed command tints red for the first word, blue for `--options`. Completion candidates are plain strings.
 
 ```ruby
-line.cli "> ", initial: "cp %name %dir", completions: true, redraw: -> { show }
+line.cli "> ", initial: "ls ", history: @recent
 ```
 
 ### Layout properties (all components)

data/example/text

@@ -33,7 +33,7 @@ class TextTest
       input: $<, header: "Text Area Header",
       top: 2, left: 0.1, right: 0.9, bottom: -4, 
       border: :round, borders:{ left: ?┆, right: ?┆, top: ?╌, bottom: ?╌ },
-      colors: { header: [:yellow, :grey30], hints: [:black, :white] }
+      colors: { header: [:yellow, :grey30], hints: [:black, :white], regex: :generic }
     )
     @user = Line.new( top: -1, 
       default: "[/]:search [n]ext [p]rev, pick [r]ow/[R]ows, [w]ord/[W]ords, [esc] quit",

data/lib/browser.rb

@@ -71,17 +71,15 @@ module Typr
     def top; super + 1 end
 
     ##
-    # Change to +dir+ (absolute path, +".."+, +"~"+, or integer index into
-    # dir_history). When +append+ is false (default), clears data and colors
-    # before scanning. Pushes onto dir_history.
+    # Change to +dir+ (absolute path, +".."+, or +"~"+). Unless +append+,
+    # clears data and colors before scanning.
     #
     #   browser.cd "/tmp"        # => changes to /tmp
     #   browser.cd "~"           # => changes to home
     #   browser.cd ".."          # => parent directory
-    #   browser.cd 2             # => jump to history entry 2
     #
-    # @param dir [String, Integer] target path or history index
-    # @param append [Boolean] scan without clearing (used by history)
+    # @param dir [String] target path
+    # @param append [Boolean] scan without clearing
     # @param trim [Integer] path prefix trim for the +path+ column
     # @return [false, nil] false when the directory cannot be opened
 
@@ -195,6 +193,8 @@ module Typr
     #   browser.change_view :full      # all columns
     #   browser.change_view 0          # first view key
     #   browser.change_view :stats     # name, size, perms, owner, group, modified
+    #
+    # @return [nil]
 
     def change_view view=nil
       return unless view
@@ -257,11 +257,11 @@ module Typr
     #
     #   browser.mark_range   # prompts for from/to, toggles selection
     #
-    # @return [Array<Integer>] the toggled ids
+    # @return [Array<Integer>, nil] the toggled ids, or nil on abort
 
-    def mark_range; return ids[ ( eval @user.ask(
+    def mark_range; return unless picked = @user.ask(
       'mark from': [self, :relative_row], 'to': [self, :relative_row]
-      ).join '..' ) ].each{|id| @selected[:rows].include?(id) ?
+      ); return ids[ ( eval picked.join '..' ) ].each{|id| @selected[:rows].include?(id) ?
         @selected[:rows].delete(id) : @selected[:rows] << id } end
 
     ## Selects all non-directory rows.
@@ -383,6 +383,12 @@ module Typr
     #   browser.pick              # => /home/user/file.txt
     #   browser.pick 'image'      # => /path/to/photo.png (images only)
     #   browser.pick nil          # => anything, same as 'file'
+    #
+    # @param type [String, Symbol, nil] MIME family, +"file"+ (default), nil for anything,
+    #   or a picker type (+:row+, +:rows+, +:column+, +:columns+, +:field+,
+    #   +:fields+, +:relative_row+, +:none+) forwarded to {Stack#pick}
+    # @param kw [Hash] +column:+ for / search (forwarded to {Grid#pick})
+    # @return [String, nil] quoted path(s), the directory on Enter (directory type), or nil
 
     def pick type='file', **kw
       type ||= 'file'
@@ -470,6 +476,8 @@ module Typr
     # within each prefix grouping.
     #
     #   browser.sort   # re-sorts with dirs first
+    #
+    # @return [nil]
 
     def sort
       @sort ||= NAME
@@ -500,10 +508,13 @@ module Typr
     #   Option               | Default                         | Description
     #   --------------------|---------------------------------|-----------------------------------
     #   +directory+          | +"~"+                           | Starting directory to browse
+    #   +views+              | {}                              | Extra named column lists (Array of headers) merged over the built-ins
+    #   +bindings+           | (built-in keybar)               | Bottom-bar label to method-name map (e.g. +"[v]iews"+ to +"!views"+)
+    #   +filter_dirs+        | nil                             | When set, directories must pass +filters+ like files
+    #   +keymap+             | {}                              | Custom name-to-key mappings (merged over navigation defaults)
     #   +mimetype_db+       | true                            | Load MIME from file extensions
     #   +mimetype_magic+    | true                            | Use +file --mime-type+ for unknowns
     #   +colors[:actions]+  | { filter: :red, ... }           | Status bar item colors
-    #   +colors[:dir_history]+ | :yellow                      | History picker column color
     #   +colors[:types]+     | (see below)                    | Per MIME-type foreground color
     #
     # == Type Color Defaults

data/lib/grid.rb

@@ -8,11 +8,15 @@ module Typr
   #   grid = Typr::Grid.new(
   #     input:  [ ["Alice", 30], ["Bob", 25] ],
   #     header: [:name, :age],
-  #     format: [:max, :right]
+  #     format: [:max, :min]
   #   )
   #   grid.show
   #
-  # Column format tokens: +Integer+ (fixed width), +:min+ (auto), +:max+ (fill remaining).
+  # Column widths (+format+): an +Integer+ fixes the width; +:min+ sizes to
+  # the widest visible cell; +:max+ sizes to content and absorbs leftover
+  # viewport width. Anything else behaves like +:min+. Numbers right-align
+  # automatically (see +align+). When the content overflows the viewport,
+  # the widest columns shrink to fit.
   #
   # Built-in procs: +:filetree+, +:datetime+, +:magnitudes+, +:convert+.
 
@@ -25,11 +29,20 @@ module Typr
     #
     #   grid.filters  #=> [[0, "Ali"]]
     #   grid.map      #=> [0, 2]
+    #
+    # +procs+ values are built-in names (+:filetree+, +:datetime+,
+    # +:magnitudes+, +:convert+) or callables: a lambda takes the cell,
+    # a full proc takes cell, row, and column.
+    #
+    #   grid.procs[1] = ->(v) { v * 2 }   # cell only
 
     attr_accessor :format, :procs, :filters, :data, :map
     ##
     # +align+ is per-column alignment, +rawsort+/+rawfilter+ flag columns
     # to bypass their +procs+, and +reverse+ flips the sort direction.
+    # +align+ is +:left+ or +:right+ (numeric cells default to +:right+);
+    # +rawsort+/+rawfilter+ are arrays indexed by column where truthy
+    # bypasses the column's proc.
     #
     #   grid.reverse = true
     #   grid.rawsort[0] = true   # sort raw values for column 0
@@ -139,12 +152,14 @@ module Typr
     ##
     # Set column headers. Symbols are auto-defined as +UPCASE+ constants
     # holding the column index.
+    # A plain String instead draws as a label bar with no column meaning.
     #
     #   grid.header = ["name", "age"]
     #   Typr::NAME  #=> 0
     #   Typr::AGE   #=> 1
+    #   grid.header = "People"   # label bar, defines no constants
     #
-    # @param h [Array<String, Symbol>] header labels
+    # @param h [Array<String, Symbol>, String] header labels or a label bar
 
     def header=( h ); super
       h.each_with_index{ |h,i|
@@ -206,8 +221,8 @@ module Typr
     #   grid.add_filter(1, /^\d{2}$/) # age matches regex
     #   grid.add_filter(:all, "ip")  # any column contains "ip"
     #
-    # @param column [Integer, Symbol]
-    # @param query [String, Regexp]
+    # @param column [Integer, :all] column index (Typr::NAME-style) or +:all+
+    # @param query [String, Regexp] substring or pattern the cell must match
 
     def add_filter column=nil, query=nil
       return unless column and query
@@ -259,27 +274,51 @@ module Typr
     #   grid.sorted_by true  #=> "age"
     #
     # @param name [Boolean] pass truthy to get display name
-    # @return [String, Integer, false, nil]
+    # @return [String, Integer, nil]
 
     def sorted_by name=false; (name and @sort) ? @header[@sort] : @sort end
 
     ##
-    # Pick a row with live filtering. When the query narrows the list to a
-    # single row it returns immediately (no Enter needed) and arms a 0.5s
-    # overtype quiet window via +Typr.suppress_keys+, so a trailing Enter
-    # or extra characters cannot re-trigger anything. +:none+ disables the
-    # auto-return (used by {Browser#narrow}, where Escape must restore).
-    #
-    # With no +column+, passes through to {Stack#pick}.
+    # Pick a row with live filtering (+column:+ given) or via {Stack#pick}
+    # (without it, supporting all its types). In filter mode the query
+    # narrows the list as you type; when one row remains it returns
+    # immediately (no Enter needed) and arms a 0.5s overtype quiet window
+    # via +Typr.suppress_keys+. +:none+ disables the auto-return (used by
+    # {Browser#narrow}, where Escape must restore); other types behave as
+    # single picks here.
+    #
+    # Without +column:+, all {Stack#pick} types apply. Anything ending in
+    # +s+ multi-selects: hint presses toggle, Return confirms with the
+    # selection, Escape aborts (confirming an empty selection returns nil).
+    #
+    #   Type               | Picks
+    #   -------------------|------------------------------------------------
+    #   +:row+             | Single row id
+    #   +:rows+            | Multi-select row ids (Return confirms)
+    #   +:column+          | One column of the given row (real index via {#sequence})
+    #   +:columns+         | Multi-select columns (Return confirms)
+    #   +:field+           | One [row, column] pair, picked row-then-column
+    #   +:fields+          | Multi-select [row, column] pairs
+    #   +:relative_row+    | Viewport-absolute row index (0-based)
+    #   +:none+            | Navigation only; always returns nil
     #
     #   grid.pick :row, 0, column: 0    # type to narrow, auto-returns at 1 match
     #   grid.pick :row, 0, column: :all # match any column
     #   grid.pick :none, column: 0      # narrowing only, Enter commits
+    #   grid.pick :column, 3           # column of the 4th visible row (page index, not id)
+    #   grid.pick :rows                # multi-select rows
     #
-    # @param type [Symbol, String] picker type; +:none+ disables auto-return
-    # @param row [Integer] ignored (always :row); passed to super otherwise
-    # @param column [Integer, Symbol, String] column index/name to filter on, or :all
-    # @return [Integer, nil] picked row id, or nil on abort
+    # Pressing Alt with a hint digit (ESC + digit) picks that hint row and
+    # sets +modifier+ to +:alt+ for the caller. The Return and Escape keys
+    # come from +@keymap+ (+confirm+/+exit+, Return/Escape by default).
+    #
+    # Mouse: left-click a row to pick it (row pickers only); wheel up/down
+    # scrolls the page; clicking outside the grid cancels like Escape.
+    #
+    # @param type [Symbol, String] picker type (tables above; symbols documented)
+    # @param row [Integer] unused in filter mode; page-relative row for +:column+ hints otherwise
+    # @param column [Integer, :all] column index (Typr::NAME-style) or +:all+
+    # @return [Integer, Array, nil] row id, [row, column], confirmed selection, or nil
 
     def pick type = :row, row=0, column: nil
       return super(type, row) unless column
@@ -290,6 +329,7 @@ module Typr
       @filters = [[column, '']]
       @map = base.select{ |id| check id }
       @start = 0
+      return @map.first if auto and @map.one?
       @bottom ||= bottom
       show
       draw_hints
@@ -378,7 +418,7 @@ module Typr
     ##
     # Execute the sort and update +@map+.
     #
-    # @return [false, void]
+    # @return [false, nil]
 
     def sort
       return false unless @sort
@@ -508,6 +548,7 @@ module Typr
       data.each_with_index{ |row, id|
         self[ is_hash? ? row.shift : id + skip ] = row }
       sort
+      self
     end
 
     ##
@@ -521,7 +562,16 @@ module Typr
     #     colors: { columns: [:cyan, nil] }
     #   )
     #
-    # @param args [Hash] +input+, +header+, +format+, +procs+, +colors+, +align+, +functions+
+    # @param args [Hash]
+    #
+    #   Option    | Value
+    #   ----------|--------------------------------------------------------
+    #   +input+   | Array of rows, or Hash of key to row
+    #   +header+  | column labels (see {#header=})
+    #   +format+  | per-column +Integer+ width, +:min+, or +:max+
+    #   +procs+   | column index to built-in name or callable (see above)
+    #   +colors+  | +columns:+ per-column, +fields:+ per +[row, col]+
+    #   +align+   | per-column +:left+/+:right+ (numbers default +:right+)
 
     def initialize args={}
       @columns,@functions = 0,{}

data/lib/line.rb

@@ -13,9 +13,10 @@ module Typr
 
 class Line < Space
   ##
-  # Line state: +default+ text restored by {#reset}, +prompt+ character
-  # before answers, +bindings+ the clickable keybinding labels, +data+ the
-  # currently rendered text, +align+ (:left/:right) horizontal alignment,
+  # Line state: +default+ (a String, Proc, or Space) restored by {#reset},
+  # +prompt+ (a single char, +>?+ by default) shown before answers,
+  # +bindings+ the clickable keybinding labels, +data+ the currently
+  # rendered text, +align+ (:left/:right) horizontal alignment,
   # +trim+ (:left/:right) the side clipped on overflow.
   #
   #   line.default = "status: ok"
@@ -46,7 +47,7 @@ class Line < Space
   #   line.append " world"   #=> "hello world"
   #   line << "!"            #=> "hello world!"
 
-  def append(str); show @data+str end
+  def append(str); show @data+str; @data end
   alias :<< :append
 
   # The keybinding list as a clickable grid of the line's own bindings. It
@@ -109,6 +110,11 @@ class Line < Space
   #   :key  - a single keypress via Typr.read_key
   #   :line - interactive line editor via Typr.read_line at the cursor
   #
+  # Every entry — including a trailing +with:+ — is simply another
+  # question in order (a +with:+ entry is labeled "with" when drawn), so
+  # +ask(pick: [grid, :row], with: :line)+ first picks, then reads
+  # free text. Hash order is insertion order.
+  #
   # Pressing the exit key (@keymap[:exit], Escape by default) aborts the
   # remaining questions and returns nil.
   #
@@ -116,6 +122,7 @@ class Line < Space
   #   line.ask(keys: :key)                   #=> "a"
   #   line.ask(open: [grid, :row, :name])    #=> 2   (picked row id)
   #   line.ask(nick: [:line, { initial: "bob" }])  #=> edited string
+  #   line.ask(pick: [grid, :row], with: :line)  #=> [2, "typed text"]
   #   line.ask([ ["Name?", :line], ["Ok?", :key] ])  #=> ["Alice", "a"]
 
   def ask sentence
@@ -181,6 +188,7 @@ class Line < Space
   #   line.cli "> ", history: @recent, prefixes: "$>"
   #
   # @param prompt [String] rendered before the typed input
+  # @param initial [String] prefilled input
   # @return [String, nil] the accepted command, or nil on Escape
 
   def cli prompt, initial: '', redraw: nil, history: nil, prefixes: nil, regex: nil

data/lib/stack.rb

@@ -95,7 +95,9 @@ module Typr
     #   stack.reset              # resets position and selection
     #   stack.reset :position    # only scrolls back to top
     #   stack.reset :selection   # clears all selected rows/columns/fields
-    #   stack.reset [:display, :format]
+    #   stack.reset [:position, :selection]
+    #
+    # @param type [:all, :position, :selection, Array<Symbol>] anything else is ignored
 
     def reset type=:all
       case type
@@ -147,6 +149,7 @@ module Typr
         mode :reset
       end
       list = page.to_a
+      @hints_start = 0 if @hints_start > [height-1, rows-1+headspace].min
       list[ height-1 ] = nil if list.length < height
       for id, relative_id in list.each_with_index
       	move left,top + relative_id + headspace
@@ -165,10 +168,16 @@ module Typr
 
     ##
     # Dispatches a key from the terminal to its semantic action and clamps the current page
-    # offset.
+    # offset. Unknown keys only clamp. +confirm+ dispatches to a +confirm+
+    # method, which only Browser defines.
+    #
+    #   stack.send Typr::KEY_DOWN   # scrolls down one row
     #
-    #   stack.send Typr::KEY_UP      # scrolls up one row
-    #   stack.send Typr::KEY_RETURN   # confirms selection
+    # Mouse: wheel scrolls (+:scroll+), a click that misses is +:outside+,
+    # a left/right press on a row returns its id.
+    #
+    # @param key [String, Typr::Mouse] key sequence or mouse event
+    # @return [Object] the keymap action's result; +:scroll+/:outside+/row id for mouse
 
     def send key#, map=nil
       if key.is_a?(Typr::Mouse)
@@ -244,33 +253,45 @@ module Typr
     def page_up; @start -= height; return end
 
     ##
-    # Blocks the calling thread and lets the user interactively pick items from the current
-    # page using hint characters or arrow keys. After selection, the user must press Return to
-    # confirm (or Escape to abort).
+    # Blocks the calling thread for an interactive pick from the current
+    # page with hint characters or arrow keys. Single picks return the
+    # moment they're made; multi (+...+s+) picks toggle until Return
+    # confirms the selection (Escape aborts, and confirming an empty
+    # selection returns nil).
     #
     # The +type+ argument controls what kind of picker is shown:
     #
-    #   Symbol/String type           | Purpose
-    #   -----------------------------|-------------------------------------------
-    #   +:row, +"file"+              | Pick a single row id
-    #   +"rows"+                     | Multi-select rows
-    #   +:column, +"field"+          | Nested: pick a row then a column
-    #   +:fields+                    | Multi-select fields
-    #   +:none+                      | Navigation-only mode
-    #   anything with +relative_|    | Returns the internal integer index
+    #   Type               | Picks
+    #   -------------------|------------------------------------------------
+    #   +:row+             | Single row id
+    #   +:rows+            | Multi-select row ids (Return confirms)
+    #   +:column+          | One column of the given row (Grid: real index, Text: word offset)
+    #   +:columns+         | Multi-select columns (Return confirms)
+    #   +:field+           | One [row, column] pair, picked row-then-column
+    #   +:fields+          | Multi-select [row, column] pairs
+    #   +:relative_row+    | Viewport-absolute row index (0-based)
+    #   +:none+            | Navigation only; always returns nil
+    #
+    # +:column+, +:columns+, +:field+ (+:fields+) and +:none+ need row
+    # positions, so they only work on Grid and Text — a bare Stack
+    # supports +:row+ and +:rows+. (The +"file"+ type belongs to
+    # {Browser#pick}.)
     #
     #   stack.pick                # single row picker
-    #   stack.pick :column, 3     # pick a column in row 3
-    #   stack.pick "rows"         # multi-select rows
+    #   stack.pick :column, 3     # column of the 4th visible row (page index, not id)
+    #   stack.pick :rows          # multi-select rows
+    #   stack.pick :relative_row  # 0-based index into the viewport
     #
     # Pressing Alt with a hint digit (ESC + digit) picks that hint row and
-    # sets +modifier+ to +:alt+ for the caller.
+    # sets +modifier+ to +:alt+ for the caller. The Return and Escape keys
+    # come from +@keymap+ (+confirm+/+exit+, Return/Escape by default).
     #
-    # Mouse: left-click a row to pick it; wheel up/down scrolls the page.
+    # Mouse: left-click a row to pick it (row pickers only); wheel up/down
+    # scrolls the page; clicking outside cancels like Escape.
     #
-    # @param type [Symbol, String] picker type (table above)
-    # @param row [Integer] starting row for column/field hints
-    # @return [Integer, Array, nil] picked id(s), selection on confirm, or nil on abort
+    # @param type [Symbol, String] picker type (table above; symbols documented)
+    # @param row [Integer] page-relative row for +:column+ hints (ignored otherwise)
+    # @return [Integer, Array, nil] row id, [row, column], confirmed selection, or nil
 
     def pick type = :row, row=0 #, key=nil
       type = type.to_s
@@ -360,11 +381,15 @@ module Typr
     #
     #   Option          | Default | Description
     #   ----------------|---------|-------------------------------------------
-    #   +keysyms+       | {}      | Custom key-to-method mappings
-    #   +hints+         | +"1234..."+ | Characters used in the hint overlay
+    #   +keymap+        | {}      | Custom name-to-key mappings (override navigation defaults)
+    #   +hints+         | +"1234567890"+ | Characters used in the hint overlay
     #   +alternate+     | true    | Striped row backgrounds
     #   +header+        | nil     | Label shown in a header bar
     #   +separator+     | +" "+   | String drawn between columns (used by Grid)
+    #   +colors+        | {}      | Per-part colors (+hints+, +header+, +selected+, +alternate+, +rows+)
+    #   +selected+      | {}      | Pre-picked ids per type (+rows+, +columns+, +fields+)
+    #
+    #   stack = Typr::Stack.new(keymap: { exit: "q" })   # quit on q instead
 
     def initialize args={}
       @keymap, @separator, @selected = {}, " ", {}

data/lib/terminal.rb

@@ -89,6 +89,7 @@ module Typr
   #   m.left?     #=> true
   #   m.alt?      #=> true   (with the SGR alt bit set)
   #   m.to_s      #=> "press button=0 x=10 y=5"
+  # +action+ is +:press+, +:release+, or +:motion+ (move with a button held).
   Mouse = Struct.new(:button, :x, :y, :action, :modifiers) do
     # True on button press (the moment to pick a row).
     def press?;   action == :press end
@@ -146,7 +147,7 @@ module Typr
 
   def prepare str, max, align=:left, side=:right
     str = clip str, max, side if real_size(str) >= max
-    pad = " " * (max - real_size(str))
+    pad = " " * [max - real_size(str), 0].max
     align == :right ? pad + str : str + pad
   end
 
@@ -184,14 +185,14 @@ module Typr
         used += size
       elsif used < max
         need = max - used
-        chars = token.chars
-        chars.reverse! if side == :left
+        clusters = token.grapheme_clusters
+        clusters.reverse! if side == :left
         width = 0
         out = ""
-        chars.each do |char|
-          width += Unicode::DisplayWidth.of char
+        clusters.each do |cluster|
+          width += Unicode::DisplayWidth.of cluster
           break if width > need
-          out << char
+          out << cluster
         end
         out.reverse! if side == :left
         kept << out
@@ -600,6 +601,9 @@ module Typr
   # until a full window passes with none — each arrival restarts it.
   # No-op unless armed by {Typr.suppress_keys}. Best-effort: never raises.
   #
+  #   Typr.suppress_keys          # arm a 0.5s window
+  #   Typr.send(:drain_quiet)     # wait it out, swallowing arrivals
+  #
   # @return [nil]
 
   def self.drain_quiet
@@ -635,6 +639,7 @@ module Typr
   # of candidates; TAB then replaces the word through a pick grid. Each
   # candidate is either a plain String or [text, color-pair] to tint the
   # pick entry. The callable's content is arbitrary - shells, tags, ...
+  # It takes the text before the cursor and returns an Array of candidates.
   #
   # +regex+ is a Hash of Regexp => color (see {.paint}) applied to the
   # query as it is rendered; matched regions restore the prompt's trailing
@@ -649,6 +654,17 @@ module Typr
   #   end
   #   Typr.read_line "> ", initial: "ls ", history: @recent   #=> "ls -l"
 
+  # @param prompt [String] text rendered before the query (keep a color code trailing)
+  # @param left [Integer] screen column (0-based)
+  # @param top [Integer] screen row (0-based)
+  # @param initial [String] prefilled query
+  # @param completions [#call, nil] +->(prefix) { candidates }+ or nil
+  # @param redraw [#call, nil] zero-arg repaint after a completion pick
+  # @param regex [Hash, Symbol, nil] paint map or scheme (see {.paint})
+  # @param history [Array<String>, nil] previous queries for Up/Down
+  # @param block [Proc] +->(key, query, cursor)+ inspector (non-nil short-circuits)
+  # @return [Object, nil] the query, a block short-circuit, or nil on Escape
+
   def self.read_line prompt='', left: 0, top: 0, initial: '', completions: nil, redraw: nil, regex: nil, history: nil, &block
     return $stdin.gets&.chomp unless $stdin.tty?
     query, cursor = initial.dup, initial.length

data/lib/text.rb

@@ -4,7 +4,9 @@ require_relative 'stack.rb'
 module Typr
 
   # A vertically scrollable text viewer with word-wrapping, header bar,
-  # row selection via hint characters, and pager-style search (/ n p).
+  # row selection via hint characters (+pick :row+), word selection via
+  # +pick :column+ (hints sit on word boundaries), and pager-style
+  # search (/ n p).
   #
   # Accepts String, IO, or StringIO input. Content is split into display
   # rows by newlines and line width, then rendered as a sliding window.
@@ -37,6 +39,9 @@ module Typr
     #   text.build("one\ntwo three")  # => #<Typr::Text ...>
     #   text << "appended line"       # alias for build
 
+    # @param input [String, IO, nil] text (or stream) to append; nil reflows
+    # @return [Text] self
+
     def build input=nil
       ( input, @data, @lines = @data, "", [0] ) if rebuild = !input
       return self if rebuild && input == ""
@@ -82,7 +87,7 @@ module Typr
         else
           @tail = ""
         end
-        @lines << @data.length if wrap < line.length || line.include?("\n")
+        @lines << @data.length if line.include?("\n") || pos < str.size || !@tail.empty?
       end
       until @tail.empty?
         wrap_idx = @tail.index("\n") || @tail.rindex(" ") || @tail.length
@@ -97,6 +102,7 @@ module Typr
       end
       @lines << @data.length unless @lines.last == @data.length
       highlight if @re
+      self
     end
     alias :<< :build
 
@@ -137,8 +143,7 @@ module Typr
     def show
       (build; @lastwidth = width) if width != @lastwidth
       range = @lines[@start..@start+height]
-      page = StringIO.new @data[range.first..range.last]
-      @page=range[1..-1].map{|pos| page.read(pos-range.first-page.pos).rstrip}
+      @page = range.each_cons(2).map{ |a, b| @data[a...b].rstrip }
       super
     end
 
@@ -229,6 +234,12 @@ module Typr
     #
     #   text = Typr::Text.new(input: "hello", header: "Title")
     #   text = Typr::Text.new(input: $stdin, tabspace: 4)
+    #
+    #   Option     | Value
+    #   -----------|------------------------------------------------
+    #   +input+    | String, IO, or StringIO (nil reflows from empty)
+    #   +tabspace+ | tabstop width in spaces (default 2)
+    #   +colors+   | +regex:+ paint map or scheme name (see {Typr.paint})
 
     def initialize args={}
       @tabspace = 2

data/lib/typr.rb

@@ -37,7 +37,7 @@
 #   grid = Typr::Grid.new(
 #     input:  [['Alice', 30], ['Bob', 25]],
 #     header: ['Name', 'Age'],
-#     format: [:max, :right]
+#     format: [:max, :min]
 #   )
 #   grid.show
 #   key = Typr.read_key

data/typr.gemspec

@@ -2,8 +2,8 @@
 
 Gem::Specification.new do |s|
   s.name = "typr"
-  s.version = "1.9.0"
-  s.date = "2026-10-12"
+  s.version = "1.9.3"
+  s.date = "2026-10-19"
   s.homepage = "https://codeberg.org/typr/typr"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: typr
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.9.3
 platform: ruby
 authors:
 - Kilian Reitmayr
 bindir: bin
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: unicode-display_width