typr 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a6c88b12b4be9c1fe406898172147d1d874e0353af72d211d2530ef5a48d82f
-  data.tar.gz: 36dd949f072aa3ab232256d4c7d7c10d6989812c97977f65f72bd25ef7d6124a
+  metadata.gz: 65f06238b297e2c6f925f139336c89b5606e23c7a08a6fb94ed82848490e9e71
+  data.tar.gz: d958ec7e5f7cd5857c2b559b3e32327b590652c8fb759f0557effb33d8c27551
 SHA512:
-  metadata.gz: 87a3993d064a814f0c819a5466c4245029d38aeabd3b6b869a9d5f2f505b60daa45aecea6447dac70cee577605e8ec1d66ee5ce858751d1122614905a9983610
-  data.tar.gz: f29f2787e8cc2b606bfb215adebe21b1384bcc860b986318bfcff334105ebea72f30844124083dc6471c81a215698dbd3aa2fcfca9b63d92594c09ab89373bdf
+  metadata.gz: 8d651d702b4e5d019636814a021ef4ab62f300b841f482de5ed4aac8f3cc3fe636802ac34551b107bfaef2c19723805e7742fafa95ada76cb6c20f91066e101b
+  data.tar.gz: 723ef1823511febee158925266361dbe0afda106ad3974fc1f75edd83f31e5a2ed6be272e634762bbf6797df41e6e27d24c908fe48902892fcf1c34271f1d6d1

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [v1.4.0] — 2026-08-15
+
+### Added
+- `Browser#pick :directory` confirms the current directory with Return (clearing filters and sorting first), so callers can accept the directory itself; the `pick` type filter only applies to directory and MIME-type picks — `:file` and custom types like `:cmd` show the full listing
+- `sanitize` terminal helper — strips ANSI escape sequences and control characters (except `\n`, `\t`) from shell-generated text
+- Alt+digit hint selection — pressing Alt + a hint digit (sent as `ESC` + digit) selects that hint row and sets a `modifier` accessor on the picker (`:alt`), so callers can detect the modified selection; `Stack#pick` and `Grid#pick` both reset `modifier` to `nil` at the start of each pick
+
+### Changed
+- `Browser#switch_to` renamed to `change_view` — clearer name for switching column views (callers in `cd` and the `views` popup updated)
+- `read_line` scrolls horizontally instead of wrapping when the query exceeds the terminal width — the cursor stays pinned to the right edge of the line while overflowing
+- `read_line` now shows the terminal cursor while editing and hides it again on exit (previously the cursor stayed invisible after `Typr.init`)
+- `real_size` now measures via `sanitize`, so non-SGR CSI/OSC sequences and control characters count as zero width; the `printables` helper was removed in favor of `sanitize`
+- Sort, filter, and view popups open in `/` search mode — typing narrows the list and a hint digit picks the result; `Line#ask` Array questions can forward pick options as a 4th element (e.g. `{ column: 0 }`)
+- Default hints are digits only (`0-9`) — typing letters in any picker always filters/navigates instead of selecting by hint; explicit `hints:` overrides removed from `Browser`
+
+### Fixed
+- Popup grids keep their height while live-filtering in `/` search mode — the box no longer collapses as rows are filtered out
+- `read_key` assembles split escape sequences — CSI input (cursor keys, SGR mouse) reads on to its final byte, SS3 (`\eO`) completes to three bytes, and a lone `ESC` briefly polls for an Alt+key continuation, so a split key can no longer be mistaken for a plain Escape (which would close a popup or exit)
+- Spec cleanup — merged the duplicated `Text#print` describes, removed the redundant empty-input edge case, dropped stack-spec `#pick` examples that duplicated grid-spec coverage, and updated the browser username specs to stub the passwd lookup (the info bar intentionally shows the real user, not stale `$USER`) plus the grid format-reset spec to assert `@widths` clearing instead of the removed `@maxed` state
+
+## [v1.3.0] — 2026-08-03
+
+### Added
+- Mouse support — `Typr.init`/`Typr.exit` enable/disable mouse reporting (buttons + SGR coordinates, `CSI ? 1000 h/l` + `CSI ? 1006 h/l`); `read_key` decodes SGR and legacy X10 reports into a `Typr::Mouse` struct (`button`, `x`, `y`, `action`, `modifiers`) with `press?`/`release?`/`wheel?`/`left?`/`middle?`/`right?` predicates
+- `Stack#hit` — maps a 1-based terminal row/col to the data row id under the cursor (nil for header/margins/outside)
+- Click-to-act in pickers — a left click on a row in `Stack#pick`/`Browser#pick` acts like pressing its hint digit (selects the row; in `Browser` cd's into directories and returns file paths)
+- Wheel-to-scroll in pickers — mouse wheel up/down scrolls the listing in `Stack#pick`/`Browser#pick`
+
 ## [v1.2.0] — 2026-08-02
 
 ### Added

data/README.md

@@ -1,29 +1,44 @@
 # typr — Terminal UI Toolkit
 
-typr is a Ruby library for building interactive terminal-based user interfaces. It provides data-object based spaces and keyboard-driven interaction.
+typr is a Ruby library for building interactive, keyboard-driven terminal user interfaces. It is built from data-object based components: grids for arrays, a pager for text, a file picker, and lines for user interaction — each of which renders itself, handles its own keymap, and can be combined into full applications.
+
+typr is designed for speed: every interactive choice is one keystroke away. Selectable rows and columns carry number hints, popups open in `/` search mode so long lists can be distilled down and picked from in a couple of keystrokes. It is the toolkit behind the [Filecon](https://codeberg.org/typr/filecon) file manager.
+
+typr's terminal layer is self-contained: it ships a precompiled terminfo key table and a MIME-type database inside the gem, so it has no ncurses dependency and works on any raw, ANSI-capable terminal — including Android/Termux.
 
 ## Features
 
-### Spaces
+### Components
 
-- **Grid** — sortable, filterable table with formatted columns, colors, and row selection
-- **Text** — scrollable text viewer with word/line picking, search, and borders
-- **Browser** — file-system directory browser with MIME type detection
-- **Stack, Space** — layout containers for composing spaces
-- **Line** — interactive prompt/input with colored questions and answers
+- **Grid** — sortable, filterable table with formatted columns, per-cell colors, and row selection. Columns can be `:min`/`:max`/fixed-width, with built-in processors for dates, file sizes, and file trees. `Grid#pick column:` adds live `/` search
+- **Text** — scrollable text viewer with word/row picking, `/` search with `n`/`p` navigation and match highlighting, and borders
+- **Browser** — file-system directory browser with MIME-type detection (bundled database, optional magic detection), per-type coloring, and an interactive picker
+- **Line** — interactive prompt/input with colored questions and answers, configurable bindings, and strict `ask` question types (`Array`, `:key`, `:line`)
 
-### Frontends
+### Keyboard interaction
 
-typr supports two rendering backends, selectable via `require`:
+Navigation uses **hint numbers** displayed next to selectable items — rows in grids, words in text, and other elements. Press the number to select that item directly. When more items are visible than fit in one set of hints (1–9, 0), press **Tab** to cycle through hint groups. Arrow keys, Page Up/Down, Home/End work as expected, and all keys are dispatched through a configurable keymap.
 
-- **Terminal** (`require 'typr'`) — raw terminal IO, no dependencies beyond Ruby stdlib
-- **Graphical** (`require 'typr/graphical'`) — SDL2-based, for desktop GUI windows
+**Live `/` search** is built into listings and pickers: popups open in search mode, so you start typing to distill the list down to the matches, then press a number hint to pick from the few remaining results. `Text` adds less-style search (`/`, `n`, `p`) with smart-case matching and wrap-around.
 
-All spaces work identically across frontends.
+### Mouse support
 
-### Keyboard interaction
+typr reports and decodes mouse input. `Typr.init` enables mouse reporting and `Typr.exit` disables it; `Typr.read_key` decodes SGR and legacy X10 reports into a `Typr::Mouse` struct (`button`, `x`, `y`, `action`, `modifiers`) with `press?`/`release?`/`wheel?`/`left?`/`middle?`/`right?` predicates. Pickers accept the mouse directly: a left click acts like pressing the row's hint digit, and the wheel scrolls the listing.
 
-Navigation uses **hint numbers** displayed next to selectable items — rows in grids, columns, or other elements. Press the number to select that item directly. When more items are visible than fit in one set of hints (1-9, 0), press **Tab** to cycle through hint groups. Arrow keys, Page Up/Down, Home/End work as expected. All keys are dispatched through a configurable keymap.
+### Terminal layer
+
+The default terminal frontend is pure ANSI on raw TTY input — **no ncurses**. Key sequences and keypad escapes are precompiled into a bundled terminfo table (`share/terminfo`), and MIME types come from a bundled database (`share/mimetypes`); both ship with the gem, so typr runs anywhere a raw, ANSI-capable terminal exists. The only runtime dependency is `unicode-display_width`.
+
+### Colors
+
+Named colors (basic, shades, and `dark_*`), grey shades `grey0`–`grey100`, the terminal's 8-bit palette, and RGB triplets for true-color terminals. Every component takes a per-part `colors:` hash (columns, headers, hints, search matches, …).
+
+### Frontends
+
+- **Terminal** (`require 'typr'`) — the default: raw terminal IO, no ncurses, works over SSH and on Termux
+- **Graphical** (`require 'typr/graphical'`) — experimental: SDL2-based windows
+
+All components work identically across frontends.
 
 ## Installation
 
@@ -34,7 +49,7 @@ gem install typr
 Or in your Gemfile:
 
 ```ruby
-gem 'typr', '~> 1.0'
+gem 'typr', '~> 1.2'
 ```
 
 ## Usage
@@ -59,8 +74,8 @@ Typr.init
 
 Typr.clear
 @grid.show
-key = Typr.read(:key)   # reads a single keypress
-@grid.reset               # reset grid to default view
+key = Typr.read_key   # reads a single keypress
+@grid.reset            # reset grid to default view
 Typr.exit
 ```
 
@@ -82,7 +97,7 @@ Typr.init
 Typr.clear
 loop do
   @text.show
-  key = Typr.read(:key)
+  key = Typr.read_key
   case key
   when ?q then break
   else     @text.send(key)  # spacebar scrolls, j/k move up/down, etc.
@@ -104,7 +119,7 @@ Typr.init
   colors: { hints: [:white, :black] }
 )
 
-selected = @browser.pick("/home")   # interactive file picker, returns path
+selected = @browser.pick   # interactive file picker, returns the absolute path
 puts "You selected: #{selected}"
 Typr.exit
 ```
@@ -140,7 +155,7 @@ class MyApp
     loop do
       @grid.show
       @prompt.show
-      key = Typr.read(:key)
+      key = Typr.read_key
       case key
       when ?s then @grid.sort_by(@prompt.ask("sort column": [@grid, :column]))
       when ?f then @grid.add_filter(*@prompt.ask("filter column": [@grid, :column], with: :line))
@@ -163,31 +178,46 @@ end
 ## API Reference
 
 ### `Typr.init` / `Typr.exit`
-Initialize and tear down the terminal UI. Always call these at the start and end of your program.
+Initialize and tear down the terminal UI (hides the cursor, enables key-mode and mouse reporting; restores them on exit). Always call these at the start and end of your program.
 
 ### `Typr.clear([scope])`
 Clears the full screen or a single line (`:line`).
 
-### `Typr.read(type)`
-Reads input from the terminal. Types:
-- `:key` — a single keypress (returns `KEY_ESCAPE`, `?q`, etc.)
-- `:line` — a full line of text input
+### `Typr.read_key`
+Reads a single keypress in raw mode. Returns the key as a String (`KEY_ESCAPE`, `?q`, arrow escape sequences), a `Typr::Mouse` struct for mouse reports, or `nil` when input is unavailable.
+
+### `Typr.read_line(prompt, ...)`
+The shared interactive line editor. Renders a prompt and query at any position with arrow keys, ctrl-arrow word jumps, Home/End/Delete/Backspace; Enter confirms, Escape aborts (`nil`). An optional block runs after each keypress and may short-circuit with a result:
+
+```ruby
+Typr.read_line "/" do |key, query, cursor|
+  filter query
+  nil
+end
+```
+
+### `Line#ask`
+Strict question types:
+- `Array` — pick a row from an object/column (hint-driven)
+- `:key` — read a single key
+- `:line` — read a line of text
+
+The question and answer are rendered in `@colors[:question]`/`@colors[:answer]`.
 
-### Layout properties (all spaces)
+### Layout properties (all components)
 - `top`, `bottom`, `left`, `right` — placement. Integers for absolute offsets, floats (0-1) for relative sizing. Negative values position from the opposite edge. (`bottom: -1` = last row)
 
 ### Grid options
 | Option | Description |
 |---|---|
 | `input` | Array of arrays (data rows) |
-| `header` | Column titles array |
+| `header` | Column titles array (symbols define `Typr::NAME`-style constants) |
 | `format` | Per-column format: `:min`, `:max`, or a number for fixed width |
+| `procs` | Per-column processors (built-ins: `:datetime`, `:magnitudes`, `:filetree`, `:convert`) |
 | `colors` | `{ columns: [:yellow, :cyan], header: [:white, :black] }` etc. |
-| `sorted_by` | Column index the grid is sorted by (setter) |
-| `filters` | Active filters array (getter) |
-| `selected` | Selected row indices (getter/setter) |
-| `.sort_by` | Sort the grid on a given column |
-| `.select_rows / select_columns` | Multi-select via index picker |
+| `.sort_by` | Sort the grid on a given column (toggles direction) |
+| `.add_filter` | Add a substring/regex filter on a column (or `:all`) |
+| `.pick :row, column:` | Interactive row picker with live `/` search and number hints |
 
 ### Text options
 | Option | Description |
@@ -195,12 +225,13 @@ Reads input from the terminal. Types:
 | `input` | String or IO-like stream to display |
 | `header` | Header bar text |
 | `border` | Border style: `:round`, `" "`, etc. |
+| `.search` | Search the text (`/`); `.search_next`/`.search_prev` (`n`/`p`) |
 
 ### Browser options
 | Option | Description |
 |---|---|
 | `directory` | Root directory to start browsing |
-| `.pick(start_dir)` | Interactive file picker, returns the selected path |
+| `.pick([type])` | Interactive file picker, returns the absolute path; `type` filters by MIME family (`"image"`, `"audio"`, `"video"`, `"text"`, `"application"`, `"inode"`) |
 
 ## License
 

data/lib/browser.rb

@@ -63,33 +63,25 @@ module Typr
         Dir.chdir( @directory = File.expand_path( dir ) )
       end
       data = Dir.new(@directory).children.reject{|f|
-        !@show_hidden and f[0] == ?. }.map.with_index do |file,id|
-        if File.symlink? file
-          target = File.readlink( file ) rescue $!.to_s
-          next [file, target, "????", false, "?", "?", 0, 0, 0, 0, "inode", "symlink"] unless File.exist?(file)
+        !@show_hidden and f[0] == ?. }.map { |file| scan_file file }
+
+      data.each_with_index{ |row, id|
+        file = row[NAME]
+        ftype = File.ftype(file) rescue next
+        ftype = File.stat(file).ftype if ftype == 'link' and File.exist?(file)
+        mime = { 'directory' => 'inode/directory', 'characterSpecial' => 'inode/chardevice',
+          'blockSpecial' => 'inode/blockdevice', 'link' => 'inode/symlink',
+          'fifo' => 'inode/fifo', 'socket' => 'inode/socket' }[ftype]
+        unless mime
+          if @mimetype_db and ext = file.match(/.+\.(\w+)$/)
+            mime = MIMETYPES[ext[1].to_sym]
+          end
+          missing[file] = id unless mime
         end
-        stat = File.stat(file) rescue nil
-        next [file, "", "????", false, "?", "?", 0, 0, 0, 0, "?", "?"] unless stat
-        type = stat.ftype.to_sym
-
-        mime = { "directory": "inode/directory",
-          "characterSpecial": "inode/chardevice",
-          "blockSpecial": "inode/blockdevice", "link": "inode/symlink",
-          "fifo": "inode/fifo", "socket": "inode/socket"}[type]
-        if type == :file and @mimetype_db
-          ext = file.match(/.+\.(\w+)$/)
-          mime ||= MIMETYPES[ext[1].to_sym] if ext
-        end
-
-        ( missing[file] = id ; mime = "?/?" ) unless mime
-        [  file, target, stat.mode.to_s(8)[-3..-1].chars.map{|d|
-          "rwx".chars.map.with_index{|c,i| d.to_i[2-i]==0 ? ?- : c } }.join,
-          File.executable?(file), stat.uid, stat.gid, stat.size,
-          stat.atime.to_i, stat.mtime.to_i, stat.ctime.to_i,
-          *mime.to_s.split( ?/ ) ]
-      end
+        row[-2,2] = mime.to_s.split( ?/ ) if mime
+      }
 
-      if @mimetype_magic and not missing.empty?
+      if @mimetype_magic and missing.any?
         begin
           out = IO.popen(['file', '--mime-type', *missing.keys]){ |io| io.read }
         rescue Errno::ENOENT
@@ -106,12 +98,33 @@ module Typr
       filter
       unless append
         @directory += ?/ unless @directory == ?/
-        switch_to @view
+        change_view @view
         reset :position
       end
       return
     end
 
+    ##
+    # Build a row for a single directory entry from filesystem metadata only.
+    # MIME type detection (extension database and +file --mime-type+) happens
+    # in a batch pass inside {#cd}; type/subtype are left as +"?"+ here.
+    #
+    #   browser.scan_file "image.png"   # => 12-column row
+
+    def scan_file file
+      target = nil
+      if File.symlink? file
+        target = File.readlink( file ) rescue $!.to_s
+        return [file, target, "????", false, "?", "?", 0, 0, 0, 0, "?", "?"] unless File.exist?(file)
+      end
+      stat = File.stat(file) rescue nil
+      return [file, "", "????", false, "?", "?", 0, 0, 0, 0, "?", "?"] unless stat
+      [  file, target, stat.mode.to_s(8)[-3..-1].chars.map{|d|
+        "rwx".chars.map.with_index{|c,i| d.to_i[2-i]==0 ? ?- : c } }.join,
+        ( File.executable?(file) and stat.file? ), stat.uid, stat.gid, stat.size,
+        stat.atime.to_i, stat.mtime.to_i, stat.ctime.to_i, "?", "?" ]
+    end
+
     ##
     # Colors symlink names green/red based on target existence and applies
     # per-MIME-type foreground colors from +@colors[:types]+.
@@ -127,11 +140,11 @@ module Typr
     ##
     # Switch to a named or indexed column view. Resets format widths.
     #
-    #   browser.switch_to :full      # all columns
-    #   browser.switch_to 0          # first view key
-    #   browser.switch_to :stats     # name, size, perms, owner, group, modified
+    #   browser.change_view :full      # all columns
+    #   browser.change_view 0          # first view key
+    #   browser.change_view :stats     # name, size, perms, owner, group, modified
 
-    def switch_to view=nil
+    def change_view view=nil
       return unless view
       view = @views.keys[ view ] if view.is_a? Integer
       @sequence = @views[ view ].map{|title| @header.index title.to_s}
@@ -216,12 +229,7 @@ module Typr
     def help; @user.help end
 
     ##
-    # Recurse through the directory tree, adding subdirectory entries inline
-    # via +cd(path, true)+. Sorts by name with the filetree processor.
-    #
-    #   browser.recurse   # flattens tree into leaf names
-
-    ## Reset display, selection, and position state then re-sort.
+    # Reset display, selection, and position state then re-sort.
     #
     #   browser.reset_view
 
@@ -231,10 +239,12 @@ module Typr
     #
     #   browser.filter_view   # prompts for filter text
 
-    def search; pick :none, 0, column: NAME end
-
     def filter_view; add_filter *@user.ask(
-      filter: [ popup( type: :"[f]ilter" ), :row, NAME], with: :line ) end
+      filter: [ popup( type: :"[f]ilter" ), :row, NAME, { column: 0 }], with: :line ) end
+
+    ## Open live `/` search filtered on the name column.
+    #
+    #   browser.search   # type to narrow, Escape restores, Enter commits
 
     def search
       @suppress_user = true
@@ -246,13 +256,13 @@ module Typr
     #
     #   browser.sort_view   # pick a column header to sort
 
-    def sort_view; sort_by @user.ask( "sort by": [ popup( type: :"[s]ort" ), :row] ) end
+    def sort_view; sort_by @user.ask( "sort by": [ popup( type: :"[s]ort" ), :row, nil, { column: 0 }] ) end
 
     ## Open a view-picker popup and switch to the selected view.
     #
     #   browser.views   # choose :simple, :compact, :stats, or :full
 
-    def views; switch_to( popup( type: :"[v]iews", input: @views.keys ).pick :row )  end
+    def views; change_view( popup( type: :"[v]iews", input: @views.keys ).pick( :row, column: 0 ) )  end
 
     ## True when the row is a directory or passes base Grid filtering.
     #
@@ -262,36 +272,53 @@ module Typr
 
     ##
     # Interactive file/directory picker. Blocks until a selection or Escape.
-    # Return on a file wraps the path in single quotes. Enter on a directory
-    # triggers cd. +type+ optionally filters by MIME family (audio, video,
-    # image, text, application, inode).
+    # Return on a file yields its raw absolute path; multi-select joins the
+    # chosen paths double-quoted with spaces. Enter on a directory triggers
+    # cd. +type+ optionally filters by MIME family (audio, video, image,
+    # text, application, inode). Mouse: left-click a row to pick it; wheel
+    # up/down scrolls the listing.
     #
-    #   browser.pick              # => '/home/user/file.txt'
-    #   browser.pick 'image'      # => '/path/to/photo.png' (images only)
+    #   browser.pick              # => /home/user/file.txt
+    #   browser.pick 'image'      # => /path/to/photo.png (images only)
     #   browser.pick nil          # => anything, same as 'file'
 
     def pick type='file', **kw
       type ||= 'file'
       type = type.to_s
       return super(type, **kw) if type[/row|column|field|none/]
-      add_filter ( %w[audio video image text application inode].include?(
-        type) ? TYPE : SUBTYPE ), type if type != 'file'
+      types = %w[audio video image text application inode]
+      add_filter( types.include?( type ) ? TYPE : SUBTYPE, type ) if type == 'directory' or types.include?( type )
       loop do
         show
         draw_hints :row
         key = Typr.read_key
         if key == @keymap[:exit]
-          reset :display
+          @filters.clear
+          sort
           return
         end
-        next unless choice = send( key )
+        if key == @keymap[:confirm] and type == 'directory'
+          @filters.clear
+          sort
+          return @directory
+        end
+        if key.is_a?(Typr::Mouse)
+          if key.wheel? and key.press?
+            send( key.wheel_up? ? @keymap[:up] : @keymap[:down] )
+            next
+          elsif key.press? and key.left? and choice = hit( key.y, key.x )
+          else next end
+        else
+          next unless choice = send( key )
+        end
         case choice
           when Array; choice = choice.map{ |id| @data[id][NAME] }.join('" "')
           when Integer; file = @data[ choice ]
             if file[SUBTYPE] == 'directory'; cd file[TARGET] || file[NAME]; next
             else choice = file[NAME] end
         end
-        reset :display
+        @filters.clear
+        sort
         return choice
       end
     end
@@ -303,7 +330,7 @@ module Typr
     #   browser.show   # shows browser with info bar
 
     def show; super
-      user = ENV["USER"] || Etc.getlogin
+      user = Etc.getpwuid(Process.euid).name rescue ENV["USER"] || Etc.getlogin
       @head.colors[:columns][0] = user == "root" ? [:red, :black] : [:green, :black]
       @head.reset :format
       @head.show
@@ -440,7 +467,7 @@ module Typr
       @parent = self
       @head ||= Grid.new( parent:self, left: ->{@parent.left}, margin: '',
         right: ->{@parent.width + @parent.left - 1}, top: ->{@parent.top-1},
-        input: [ [->{ENV["USER"] || Etc.getlogin}, ->{@parent.directory},
+        input: [ [->{Etc.getpwuid(Process.euid).name rescue ENV["USER"] || Etc.getlogin}, ->{@parent.directory},
           ->{@parent.filter_display},
           ->{ (s = @parent.sorted_by(true)) &&
             "#{s} #{@parent.reverse ? "\u2193" : "\u2191"}"},

data/lib/graphical.rb

@@ -1,4 +1,4 @@
-require 'sdl2'
+require 'sdl3'
 require_relative 'frontend'
 
 module Visuals

data/lib/grid.rb

@@ -262,12 +262,18 @@ module Typr
       @filters = [[column, '']]
       @map = base.select{ |id| check id }
       @start = 0
+      @bottom ||= bottom
       show
       draw_hints
+      @modifier = nil
       result = Typr.read_line '/', left: left, top: self.bottom + 1,
         &->(key, query, _) {
           if key.is_a?(String) and idx = @hints[0..height-@hints_start-1].index(key)
             return page.to_a[idx + @hints_start]
+          elsif key.is_a?(String) and digit = key[/\A\e(\d)\z/, 1] and
+            idx = @hints[0..height-@hints_start-1].index(digit)
+            @modifier = :alt
+            return page.to_a[idx + @hints_start]
           end
           if key.is_a?(String) and !key.each_char.all?{ |c| c.ord.between?(32, 126) } and
             @keymap.values.include?(key) and ![KEY_BACKSPACE, "\b"].include?(key)
@@ -406,7 +412,8 @@ module Typr
       header = ( row == :header )
       return draw @header[0..width-1].ljust(width) if
         header and @header.is_a? String
-      fields = (header ? @header : @data[row] ).dup
+      return unless row_data = header ? @header : @data[row]
+      fields = row_data.dup
       @layer[row].each{ |col,value| fields[col] = value } if
         @layer[row] if @layer unless header
   	    for col,id in sequence.each_with_index

data/lib/line.rb

@@ -64,7 +64,9 @@ class Line < Space
   #
   # The +type+ selects how the answer is collected:
   #   Array - interactive pick via <widget>.pick(<type>); an optional third
-  #           element renders the chosen row's field into the line
+  #           element renders the chosen row's field into the line, and an
+  #           optional fourth element is passed as pick keyword arguments
+  #           (e.g. { column: 0 } to open the pick in / search mode)
   #   :key  - a single keypress via Typr.read_key
   #   :line - interactive line editor via Typr.read_line at the cursor
   #
@@ -95,7 +97,7 @@ class Line < Space
         draw prepare( colored, width, @align, @trim )
         color( @colors[:answer] )
         case object
-          when Array then answer << object.first.pick( object[1] )
+          when Array then answer << object.first.pick( object[1], **(object[3] || {}) )
           when :key then answer << Typr.read_key
           when :line then answer << Typr.read_line( colored + color_code( @colors[:answer] ),
             left: left, top: top )

data/lib/space.rb

@@ -29,6 +29,7 @@ include Typr
 STR
 eval( method % ([name]*11) ) }
 
+  # Deep-convert String keys to Symbols so string-keyed config (e.g. YAML) is honored.
   def symbolize obj
     case obj
     when Hash
@@ -40,17 +41,23 @@ eval( method % ([name]*11) ) }
   attr_writer :left, :top, :right, :bottom
   attr_accessor :margin, :colors, :interval, :borders
 
+  # Viewport width in cells (right - left + 1).
   def width; right - left + 1 end
+  # Viewport height in cells (bottom - top + 1).
   def height; bottom - top + 1 end
 
+  # Redraw every +interval+ seconds from a background thread.
   def start; @updater = Thread.new{ loop{show; sleep @interval }} end
+  # Stop the background refresh thread.
   def stop; @updater.terminate end
 
+  # Draw a border char at screen (x, y); skips nil and off-screen positions.
   def draw_border x,y,char
     draw move_code(x, y) + char unless not char or
       x < 0 or x > Typr.width or y < 0 or y > Typr.height
   end
 
+  # Draw the widget's border box (no-op when no borders are set).
   def show
     return if @borders.empty?
     color @colors[:border]
@@ -66,6 +73,8 @@ eval( method % ([name]*11) ) }
     draw_border(right + 1, bottom + 1, @borders[:bottom_right])
   end
 
+  # Set border style: :light/:heavy/:double/:round, a char repeated across
+  # the box, or nil for none.
   def border=(border)
     chars = case border
       when Symbol
@@ -78,6 +87,8 @@ eval( method % ([name]*11) ) }
       bottom_right ].map.with_index{ |part,id| [part.to_sym, chars[id]] }.to_h if chars
   end
 
+  # Build a widget from boundary (left/top/right/bottom), border, margin,
+  # colors, interval, and keymap.
   def initialize args={}
     @max, @keymap, @colors, @margin = 0, {}, {}, '  '
     @left, @top, @interval, @borders = 0, 0, 1, {}

data/lib/stack.rb

@@ -21,7 +21,7 @@ module Typr
     ## +alternate+ toggles striped rows (+:grey10+ background alternating with the default bg).
 
     attr_accessor :start, :keymap, :selected, :header
-    attr_accessor :separator, :hints, :hints_start
+    attr_accessor :separator, :hints, :hints_start, :modifier
 
     ##
     # Returns a +Range+ of internal data indices visible on the current page.
@@ -38,6 +38,20 @@ module Typr
 
     def headspace; @header ? 1 : 0 end
 
+    ##
+    # Map a mouse click at 1-based terminal (row, col) to a data row id on
+    # the current page, or nil when the click lands outside the widget (border,
+    # header, margins). Row ids match what hint presses return from `pick`.
+    #
+    #   stack.hit 3, 5   # => 0  (row 3, col 5 hits data row 0)
+
+    def hit row, col
+      return unless row and col
+      rel = row - 1 - top - headspace
+      return unless rel.between?(0, height - 1) and col.between?(left, right)
+      page.to_a[rel]
+    end
+
     ##
     # The usable height after subtracting any header space.
     #
@@ -193,10 +207,13 @@ module Typr
     #   stack.pick                # single row picker
     #   stack.pick :column, 3     # pick a column in row 3
     #   stack.pick "rows"         # multi-select rows
+    #
+    # Mouse: left-click a row to pick it; wheel up/down scrolls the page.
 
     def pick type = :row, row=0 #, key=nil
       type = type.to_s
       multiple = type[-1] == ?s
+      @modifier = nil
       loop do
         if type['field']
           row = pick( :row ) or return
@@ -207,12 +224,27 @@ module Typr
           draw_hints type, row unless type['none']
           limit = type['row'] ? height : positions(row).count
           key = Typr.read_key
-          if key.is_a?(String) and value =
+          if key.is_a?(Typr::Mouse)
+            if key.wheel? and key.press?
+              send( key.wheel_up? ? @keymap[:up] : @keymap[:down] )
+              next
+            elsif key.press? and key.left? and type['row'] and
+              value = hit( key.y, key.x )
+              relative = value if type['relative_']
+            end
+          elsif key.is_a?(String) and value =
             @hints[0..limit-@hints_start-1].index(key)
             value += @hints_start
             relative = value + @start if type['relative_']
             if type['row'] then value = page.to_a[ value ]
             elsif type['column'] and @sequence; value = @sequence[value] end
+          elsif key.is_a?(String) and digit = key[/\A\e(\d)\z/, 1] and
+            value = @hints[0..limit-@hints_start-1].index(digit)
+            @modifier = :alt
+            value += @hints_start
+            relative = value + @start if type['relative_']
+            if type['row'] then value = page.to_a[ value ]
+            elsif type['column'] and @sequence; value = @sequence[value] end
           end unless type['none']
         end
 
@@ -270,7 +302,7 @@ module Typr
       @keymap = { cycle: KEY_TAB, confirm: KEY_RETURN, exit: KEY_ESCAPE,
         page_down: KEY_PAGEDOWN, page_up: KEY_PAGEUP, up: KEY_UP,
         down: KEY_DOWN, to_top: KEY_HOME, to_bottom: KEY_END }.merge @keymap
-      @hints ||= "1234567890qwertyuiopasdfghjklzxcvbnm-=[];'\,./"
+      @hints ||= "1234567890"
     end
   end