typr 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdcaef4b1bc2c40e6fab6bd7d1462ddf19aeca03babcdbb9be74629551230647
-  data.tar.gz: b4e927b5237f27e2366ed15057054b33d9f070ef5a50c234533699182c7228ee
+  metadata.gz: 6f464a51f6c8356a1571fcebe51bbe315428ec054d9b1b819753a688764ce347
+  data.tar.gz: '0367917e4ce7b2f67c0605bb321f358aa81e17f27ab555ab558a6655b646dc9a'
 SHA512:
-  metadata.gz: 889fd403e345e89dc6777c02c6736d0865b7266b16157e13e4cf2469b9a3664d68f4fe672d1f9b5b6d72316d697c2c8e20e1f920853ae495014c9fb049fed6cd
-  data.tar.gz: 662df0d3ef61d964cd8a03a1cd1f7caa7fb14a15d87c22afa3a2cdf9115f4780b944446ebcdc9f538c33ee80753e48c362fea7f716d2ef7fca2070f07fe5483f
+  metadata.gz: 6f3f59d78bfc8831542c843de4eb51aa1507774b95436f97d9cf906f12945808f25c1add663945ad3d94ba8f33a543bc8f2cb960eac2adf995e6c6ec62fb715e
+  data.tar.gz: bf0a175749a29714fa07e0e8124b72a031dd9606c7d077cdcf7f214dc81783d28a2cce6b0e265afbbee9155a82cef742916c0a4956522c3edf56b66b6c223bbd

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [v1.5.0] — 2026-09-05
+
+### Added
+- Shell TAB completion in `read_line` — when `completions: true`, each keypress queries the shell's completion system (`/usr/share/bash-completion/completions/[cmd]`) via `IO.popen` and shows a pickable `Grid` above the edit line; selecting an item inserts it at the cursor. Handles `+`, `|`, `=` command prefixes
+- `Space#data_at` / `Space#extract_key` — the clickable-element lookup every widget overrides (`Stack` returns an Integer row id, `Line` returns a String binding, `Browser`'s head maps its filter/sort/views columns to actions) and the trigger-key extraction for labels like "[h]elp"; `Stack#hit` now delegates to `data_at`
+- Mouse dispatch through `Stack#send` — the mouse is handled in `send` itself (wheel scrolls and returns `:scroll`, a left or right press returns `data_at`), so pickers and `Browser#pick` route clicks through `send`; `Browser#send` intercepts clicks on `@head` and `@user` to dispatch their bindings, and `Grid#send` sorts by column header on click
+- `Line#list` — the line's keybindings as a clickable auto-width KEYBINDINGS grid (starting at column 1, floored to fit its header) and `Line#help` as `list.pick :row`: click a row or press its hint digit to return its row id, Escape or Return to return nil. Apps compose their own help around the grid — Filecon aligns a HELP text panel at `list.right + 2` and mirrors navigation by sending every event to both panels
+- Clicking outside a popup cancels it — `Stack#send` returns `:outside` for a press outside a widget's bounds, and pickers (`Stack#pick`, `Grid#pick`'s column filter, `Line#help`) treat it like Escape: state is restored and nil is returned, while the main browser listing ignores outside clicks
+
+### Fixed
+- `Browser#send` chains string dispatches from `@head`/`@user` binding clicks — the modifier-while returned immediately after the first `send`, so clicking a bottom-bar binding that opened a sub-screen (e.g. help) and returned a trigger key would drop it; the loop now re-dispatches until the result is no longer a String
+- Mousewheel scrolling works in live-filter popups (`Grid#pick` with `column:`) — the wheel scrolled `@start` but the trailing filter reapply then reset it to the top, so the popup never visibly moved; mouse events now skip that reset and just redraw
+- `extract_key` strips ANSI color codes before matching — colored binding labels like "\e[31m[f]ilter\e[0m" now resolve to their trigger key (previously the color code's own `[31m` matched and returned nil, so colored bottom-bar bindings and help-grid rows were not clickable)
+- `Browser`'s head `data_at` matches the 1-based mouse row — the head action columns (filter/sort/views) are clickable in a real terminal again, not just at test coordinates
+- `Line#data_at` matches the bottom-bar row — mouse coordinates are 1-based while widget rows are 0-based, so the clickable line sat one row above the rendered bindings; the row check now adds 1, matching `Stack#data_at`
+- `Text` rebuilds on width change instead of blanking — `show` re-wraps the existing content whenever the width differs from the width it was built at (a `left` proc that resolves later, or a terminal resize), so a `Text` panel no longer renders an empty body after its first draw
+- `Text` rows fit the panel interior — `print` draws `width - margin` cells so content rows stay inside the box instead of overflowing onto the next line (the overflow wrapped spaces with the alternating background into the neighboring widget's left-border column)
+- `draw_border` allows the last column and row — the guard now only skips `x > width` / `y > height` (genuinely off-screen), so a panel flush with the terminal edge draws its right border and corners on the last column
+- `Text#build` wraps ANSI-colored content correctly — the capacity calculation uses display width instead of byte length, so escape sequences don't inflate the line count
+- `reset_view` reloads the directory again — it calls `cd @directory` before clearing display/selection/position and re-sorting, so reset picks up new and removed files instead of only reshuffling the stale listing
+- Head path lookup — `@head.path_at(x, y)` maps a click to a target directory: the username column returns the resolved home directory, each `/`-separated segment of the directory cell returns that ancestor path (padding, action columns and array listings return nil); mouse `x` is adjusted from 1-based terminal columns so boundary clicks resolve to the cell under the cursor
+
+## [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

data/README.md

@@ -23,7 +23,7 @@ Navigation uses **hint numbers** displayed next to selectable items — rows in
 
 ### Mouse support
 
-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.
+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, the wheel scrolls the listing, and a click outside the picker's bounds cancels it like Escape. Any widget can expose clickable elements through `Space#data_at` (a row id, a binding label, or an action) and `Stack#send` dispatches mouse events to them — so `Browser`'s head columns and the bottom binding bar are clickable too, and `Line#help` is `Line#list.pick :row` — the line's keybinding grid, exposed so apps can compose their own help beside it (e.g. Filecon aligns a HELP text panel at `list.right + 2` and mirrors navigation to both panels).
 
 ### Terminal layer
 

data/example/grid

@@ -4,7 +4,7 @@
 # Usage:
 #   cd example && ruby grid [file]
 #
-# Reads csv file and displays it as an interactive table.
+# Reads a comma-separated file and displays it as an interactive table.
 #
 # Keys:
 #   s         Sort by a column (prompts for column number)
@@ -20,54 +20,49 @@
 # The header line shows current time, active sort, filters,
 # and selected rows. The user line shows available commands.
 
-require 'csv'
 require_relative '../lib/typr.rb'
 
 class GridTest
-  # extend Typr
   include Typr
-  # Typr.frontend :terminal
+
   def initialize
-    Typr.init 
-    input = CSV.new($<.read).to_a
+    Typr.init
+    input = $<.read.split("\n").map{|l| l.split(',') }
     header = input.shift
-    @grid = Grid.new( 
-      # input: open( "top5000.csv").read.split.map{|l| l.split(',') } ,
+    @grid = Grid.new(
       input: input,
       top: 1, right: -1, bottom: -2,
-      # hints: "1234",
-      format: [ 4, :max, 1, :min, :min ], 
-      # procs: { 2 => proc( &:upcase ) },
-      header: header, # ["rank", "word", "p", "count", "quot"], 
-      colors: { columns: [ :yellow, :blue, :red, :green, :magenta] } ) 
-    @user = Line.new( top: -1, default: 
+      format: [ 4, :max, 1, :min, :min ],
+      header: header,
+      colors: { columns: [ :yellow, :blue, :red, :green, :magenta] } )
+    @user = Line.new( top: -1, default:
       "(s)ort, (f)ilter, (r)eset, select (R)ows/(C)olumns/(F)ields, [esc] quit")
     @head = Line.new( interval: 1,
-      default: proc{ draw " %s, sort:%s filter:%s selected:%s" % 
-        [ Time.now.strftime("%D %T"), 
-          (@grid.header[@grid.sorted_by.abs] if @grid.sorted_by),
-          @grid.filters.join, @grid.selected ||= [] ] } )
+      default: proc{ draw " %s, sort:%s filter:%s selected:%s" %
+        [ Time.now.strftime("%D %T"),
+          (@grid.header[@grid.sorted_by] if @grid.sorted_by),
+          @grid.filters.join, @grid.selected ] } )
   end
 
   def run
     Typr.clear
-    loop do       
+    loop do
       @grid.show
       @user.show
-      @head.start  
-      key = Typr.read( :key )
+      @head.start
+      key = Typr.read_key
       @head.stop
       case key
-      	when KEY_ESCAPE; exit
-      	when ?` then (line = Typr.read(:line)) and @user.show(eval(line))
+        when KEY_ESCAPE; exit
+        when ?` then (line = Typr.read_line) and @user.show(eval(line))
         when ?s then @grid.sort_by( @user.ask "sort column": [@grid, :column] )
         when ?F then @user.ask("pick fields": [@grid, :fields])
         when ?R then @user.ask("pick rows": [@grid, :rows])
         when ?C then @user.ask("pick columns": [@grid, :columns])
-        when ?f then @grid.add_filter( *@user.ask("filter column": 
+        when ?f then @grid.add_filter( *@user.ask("filter column":
           [@grid, :column], with: :line))
-        when ?r then @grid.reset; @user.reset 
-        else @grid.send key; @user.reset 
+        when ?r then @grid.reset; @user.reset
+        else @grid.send key; @user.reset
       end
     end
   end
@@ -77,4 +72,4 @@ begin
   GridTest.new.run
 ensure
   Typr.exit
-end 
+end

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[TYPE, 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
@@ -98,7 +90,7 @@ module Typr
         out.split($/).each{ |line|
           file, mime = line.match(/^(.*):\s+(\w+\/[\w\-\.]+)$/)&.captures
           next unless file
-          data[ missing[file] ][-2,2] = mime.split( ?/ ) if missing[file] }
+          data[ missing[file] ][TYPE, 2] = mime.split( ?/ ) if missing[file] }
       end
       data.each { |row| row[0] = File.join(@directory, row[0]) }
       self << data
@@ -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, "?", "?", nil] unless File.exist?(file)
+      end
+      stat = File.stat(file) rescue nil
+      return [file, "", "????", false, "?", "?", 0, 0, 0, 0, "?", "?", nil] 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, "?", "?", nil ]
+    end
+
     ##
     # Colors symlink names green/red based on target existence and applies
     # per-MIME-type foreground colors from +@colors[:types]+.
@@ -127,14 +140,18 @@ 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}
+      if @show_path
+        @data.each { |row| row[PATH] = File.dirname(row[NAME]) } if @data.any?
+        @sequence.insert(@sequence.index(NAME) || 0, PATH) unless @sequence.include?(PATH)
+      end
       reset :format
       @view = view
       return
@@ -147,6 +164,18 @@ module Typr
     #   browser.send "1"   # => row id if hint "1" is visible
 
     def send key
+      if key.is_a?(Typr::Mouse) and key.press? and key.left?
+        [@head, @user].each do |w|
+          next unless w.respond_to?(:data_at)
+          value = w.data_at(key.x, key.y)
+          next unless value
+          key = extract_key(value.to_s)
+          while key.is_a?(String)
+            key = send(key)
+          end
+          return key
+        end
+      end
       if key.is_a?(String) and
         id = @hints[0..[height, rows-1+headspace].min-@hints_start-1].index(key)
         return page[id+@hints_start]
@@ -227,7 +256,7 @@ module Typr
     #   browser.filter_view   # prompts for filter text
 
     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.
     #
@@ -243,13 +272,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.
     #
@@ -273,32 +302,37 @@ module Typr
       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
+        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
+          choice = send key
+          next if choice == :scroll or choice == :outside
         else
           next unless choice = send( key )
         end
+        next unless choice
         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
@@ -394,7 +428,7 @@ module Typr
 
     def initialize args={}
       @mimetype_db, @mimetype_magic = true, true
-      @view, @sort, @views, @positions, @show_hidden = :compact, 0, {}, {}, false
+      @view, @sort, @views, @positions, @show_hidden, @show_path = :compact, 0, {}, {}, false, false
       @filter_dirs = args[:filter_dirs]
       super
       @left ||= 0
@@ -422,7 +456,7 @@ module Typr
         toggle_hidden: ?H}.merge @keymap
 
       self.header = %w[ name target permissions executable owner group size
-        accessed modified created type subtype ]
+        accessed modified created type subtype path ]
 
       @format[NAME] = :max
       @format[TYPE] = 5
@@ -455,6 +489,27 @@ module Typr
         colors: { columns: [@colors[:default], @colors[:default],
           @colors[:actions][:"[f]ilter"], @colors[:actions][:"[s]ort"],
           @colors[:actions][:"[v]iews"]] } )
+      @head.define_singleton_method( :data_at ) do |x, y|
+        return unless x and y and y.between?( top + 1, bottom + 1 ) and
+          x.between?( left, right )
+        offs = positions( 0 )
+        col = offs.each_index.find { |i| x <= left + offs[i] + width_for( i ) - 1 }
+        @parent.instance_variable_get( :@positions ).keys[ col - 2 ] if col and col >= 2
+      end
+      @head.define_singleton_method( :path_at ) do |x, y|
+        return unless x and y and y.between?( top + 1, bottom + 1 )
+        x -= 1
+        return unless x.between?( left, right )
+        offs = positions( 0 )
+        col = offs.each_index.find { |i| x <= left + offs[i] + width_for( i ) - 1 }
+        return (Etc.getpwuid(Process.euid).dir rescue (Dir.home rescue "~")) if col == 0
+        return unless col == 1 and @parent.directory.is_a?( String )
+        text = ((@layer and @layer[0] and @layer[0][1]) || @data[0][1].call).to_s
+        rel = x - ( left + offs[1] )
+        return if rel < 0 or rel >= real_size( text )
+        pre = prepare( text, rel + 1 )
+        ( pre + ( pre.end_with?( "/" ) ? "" : text[pre.length..-1][/\A[^\/]*/] ) ).sub( %r{(?<=.)/$}, "" )
+      end
 
       @user ||= Line.new( parent:self, left:->{@parent.left},top:->{@parent.bottom+1},
         bindings: %w[ [h]elp [/]:search ] + @colors[:actions].map{|name,color|

data/lib/graphical.rb

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

data/lib/grid.rb

@@ -262,17 +262,27 @@ 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)
+          if key.is_a?(Typr::Mouse)
+            value = send key
+            return value if value.is_a?( Integer )
+            return :outside if value == :outside
+          elsif 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)
             send key
-          else
+          elsif !key.is_a?(Typr::Mouse)
             @filters = [[column, query]]
             @map = base.select{ |id| check id }
             @start = 0
@@ -282,7 +292,7 @@ module Typr
           nil
         }
       case result
-      when nil;      @filters, @map, @start = saved
+      when nil, :outside; @filters, @map, @start = saved
       when Integer; return result
       else
         @filters = result.empty? ? saved[0] : saved[0] + [[column, result]]
@@ -299,6 +309,19 @@ module Typr
     #
     # @param column [Integer, Symbol]
 
+    def send key
+      if key.is_a?(Typr::Mouse) and key.press? and key.left? and
+          @header.is_a?(Array) and key.y == top + 1
+        rel = key.x - left - 1 - @margin.size
+        if rel >= 0
+          col = positions(0).count{|pos| pos <= rel} - 1
+          sort_by(sequence[col]) if col >= 0 && col < sequence.size
+        end
+        return :scroll
+      end
+      super
+    end
+
     def sort_by column
       column = @header.index( column.to_s ) if column.is_a? Symbol
       if @sort and (column == @sort) then @reverse = !@reverse
@@ -382,6 +405,7 @@ module Typr
       gaps = @margin.size + @separator.size * (columns - 1)
       sum = @widths.sum
       @max = sum + gaps - 1
+      @max = [ @max, @header.length ].max if @header.is_a?(String)
       space = width - gaps
       if (extra = sum - space  ) > 0
         extra.times{ |i| @widths[ @widths.index(@widths.max) ] -= 1 }
@@ -406,7 +430,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

@@ -39,17 +39,43 @@ class Line < Space
   def append(str); show @data+str end
   alias :<< :append
 
-  # Display keybinding help in a floating grid.
+  # The keybinding list as a clickable grid of the line's own bindings. It
+  # auto-sizes to its widest binding (floored to fit the header) and starts
+  # at column 1, so apps can align side panels at +list.right + 2+.
   #
-  #   line.bindings = ["Ctrl-S: Save", "Ctrl-Q: Quit"]
-  #   line.help
+  #   line.list   # => a Grid whose rows are the bindings
 
-  def help conf={}
-    Grid.new( { input: ['']+@bindings+[''], top: 3, left:0.4,
+  def list
+    Grid.new( input: @bindings, top: 2, left: 1, bottom: -3,
       header: "KEYBINDINGS",
-      colors: { header: [:white,:black], border:[:white,:grey10] },
-      alternate: false, border: ' ' }.merge conf ).pick :none
-    return
+      colors: { header: [:yellow,:black], border:[:white,:grey10] },
+      alternate: false, border: :light )
+  end
+
+  # Pick a keybinding from the list: click a row (or press its hint digit) to
+  # return the row id, Escape or Return to return nil.
+  #
+  #   line.help   # => 0 (the picked row) or nil
+
+  def help; list.pick :row end
+
+  ##
+  # The binding label under terminal (x, y) on this line, or nil when the
+  # click is outside the row or off the current bindings text (see
+  # {Space#data_at}).
+  #
+  #   line.data_at 3, 8   # => "[h]elp"
+
+  def data_at x, y
+    return unless x and y and y == top + 1 and x.between?( left, right ) and
+      @bindings and @data == @bindings.join( ' ' )
+    pos = left
+    @bindings.each do |b|
+      width = real_size( b )
+      return b if x.between?( pos, pos + width - 1 )
+      pos += width + 1
+    end
+    nil
   end
 
   # Reset the line to its default text or prompt.
@@ -64,7 +90,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 +123,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

@@ -46,6 +46,27 @@ eval( method % ([name]*11) ) }
   # Viewport height in cells (bottom - top + 1).
   def height; bottom - top + 1 end
 
+  ##
+  # The clickable element at terminal (x, y), or nil when outside the widget.
+  # Widgets with data override this: Stack returns an Integer row id, Line
+  # returns a String binding. Applications dispatch mouse events by iterating
+  # their spaces and taking the first non-nil result.
+  #
+  #   space.data_at 3, 8   # => nil (base Space has no data)
+
+  def data_at x, y; nil end
+
+  ##
+  # The trigger key for a binding label like "[h]elp" or "[/]:search", or nil
+  # for named keys ("[up]", "[esc]") which stay keyboard-only.
+  #
+  #   line.extract_key "[R]ecurse"   # => "R"
+
+  def extract_key binding
+    key = sanitize( binding.to_s )[/\[([^\]]+)\]/, 1]
+    key if key and key.size == 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.

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.
@@ -45,10 +45,18 @@ module Typr
     #
     #   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)
+    def hit row, col; data_at col, row end
+
+    ##
+    # The data row id at terminal (x, y), or nil when the click is outside the
+    # viewport (see {Space#data_at}).
+    #
+    #   stack.data_at 5, 3   # => 0
+
+    def data_at x, y
+      return unless x and y
+      rel = y - 1 - top - headspace
+      return unless rel.between?(0, height - 1) and x.between?(left, right)
       page.to_a[rel]
     end
 
@@ -146,6 +154,18 @@ module Typr
     #   stack.send Typr::KEY_RETURN   # confirms selection
 
     def send key#, map=nil
+      if key.is_a?(Typr::Mouse)
+        if key.wheel? and key.press?
+          send( key.wheel_up? ? @keymap[:up] : @keymap[:down] )
+          return :scroll
+        end
+        if key.press? and ( key.left? or key.right? )
+          return :outside unless key.x and key.y and
+            key.x.between?( left, right ) and key.y.between?( top + 1, bottom + 1 )
+          return data_at( key.x, key.y )
+        end
+        return
+      end
       response = eval @keymap.invert[key].to_s if @keymap.values.include? key
       @start = rows - height if @start > rows - height
       @start = 0 if @start < 0
@@ -213,6 +233,7 @@ module Typr
     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
@@ -224,20 +245,25 @@ module Typr
           limit = type['row'] ? height : positions(row).count
           key = Typr.read_key
           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 =
+            value = send( key )
+            next if value == :scroll
+            return if value == :outside
+            value = nil unless type['row'] and key.left?
+            relative = value if value and type['relative_']
+          elsif !type['none'] and 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
-          end unless type['none']
+          elsif !type['none'] and 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
         end
 
         if value
@@ -270,6 +296,13 @@ module Typr
       return
     end
 
+    def cycle_back
+      max = [height-1, rows-1+headspace].min
+      @hints_start -= @hints.size
+      @hints_start = (max / @hints.size) * @hints.size if @hints_start < 0
+      return
+    end
+
     ##
     # Constructs a Stack widget.
     #
@@ -291,10 +324,10 @@ module Typr
       @colors = { hints: [255, :black ], header: [232,:grey60 ],
         selected: :grey25, alternate: :grey10, rows: {} }.merge @colors
       @selected = { fields:[], columns:[], rows:[] }.merge @selected
-      @keymap = { cycle: KEY_TAB, confirm: KEY_RETURN, exit: KEY_ESCAPE,
+      @keymap = { cycle: KEY_TAB, cycle_back: KEY_BACK_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
 

data/lib/terminal.rb

@@ -49,6 +49,10 @@ module Typr
   KEY_ESCAPE = "\e"
   KEY_RETURN = CARRIAGE_RETURN
   KEY_TAB = "\t"
+  KEY_BACK_TAB = "\e[Z"
+  KEY_ALT_BACKSPACE = "\e\x7f"
+  KEY_ALT_LEFT = "\e[1;3D"
+  KEY_ALT_RIGHT = "\e[1;3C"
   KEY_PAGEDOWN = KEY_NPAGE
   KEY_PAGEUP = KEY_PPAGE
 
@@ -56,6 +60,8 @@ module Typr
   # terminfo: 1000 = button press/release/wheel, 1006 = SGR coordinates.
   MOUSE_ON = "\e[?1000h\e[?1006h"
   MOUSE_OFF = "\e[?1000l\e[?1006l"
+  ALT_SCREEN_ON  = "\e[?1049h"
+  ALT_SCREEN_OFF = "\e[?1049l"
 
   # A mouse event decoded from the input stream. +x+ / +y+ are 1-based
   # terminal coordinates; +button+ is 0=left, 1=middle, 2=right, or 4-7 for
@@ -166,11 +172,16 @@ module Typr
       str[0..-num-1] + chars )
   end
 
-  # Strip ANSI escape sequences from +str+.
-  def printables str; str.gsub(/\x1b\[[^m]+m|/,'') end
+  # Strip ANSI escape sequences and control characters (except \n, \t)
+  # from shell-generated text, leaving only printable content.
+  def sanitize str
+    str.scrub
+       .gsub(/\e(?:\[[0-9;?]*[ -\/]*[@-~]|\][^\a\e]*(?:\a|\e\\)|[()=><0A])/, '')
+       .gsub(/[\x00-\x08\x0b-\x1f\x7f]/, '')
+  end
 
-  # Display width of +str+ after stripping ANSI escapes.
-  def real_size str; Unicode::DisplayWidth.of( printables(str) ) end
+  # Display width of +str+ after stripping ANSI escapes and control chars.
+  def real_size str; Unicode::DisplayWidth.of( sanitize(str) ) end
 
   # Coerce a string into Integer, Float, or Boolean when it matches those
   # forms (yes/no, true/false); otherwise return it unchanged.
@@ -250,11 +261,15 @@ module Typr
   def self.read_key
     read = ->(tty) do
       str = tty.sysread 6
-      if str.start_with?("\e[<")
-        # SGR mouse reports (CSI < b ; x ; y M/m) can exceed six bytes.
+      if str.start_with?("\e[M") and str.size < 6
+        str << tty.sysread(6 - str.size) # X10 mouse reports
+      elsif str.start_with?("\e[")
+        # CSI sequences (arrows, SGR mouse, ...) end with a byte >= 0x40.
         str << tty.sysread(1) until str[-1].ord >= 0x40
-      elsif str.start_with?("\e[M") and str.size < 6
-        str << tty.sysread(6 - str.size)
+      elsif str.start_with?("\eO") and str.size < 3
+        str << tty.sysread(3 - str.size) # SS3 (application) cursor keys
+      elsif str == "\e" and IO.select([tty], nil, nil, 0.03)
+        str << tty.read_nonblock(6) rescue nil # alt+key continuation
       end
       str
     end
@@ -301,41 +316,80 @@ module Typr
   #     nil
   #   end
 
-  def self.read_line prompt='', left: 0, top: 0, initial: '', &block
+  def self.read_line prompt='', left: 0, top: 0, initial: '', completions: nil, redraw: nil, &block
     return $stdin.gets&.chomp unless $stdin.tty?
     query, cursor = initial.dup, initial.length
-    loop do
-      $>.print "\e[%i;%if" % [ top + 1, left + 1 ]
-      $>.print ERASE_LINE
-      $>.print prompt + query
-      $>.print "\e[%i;%if" % [ top + 1, left + 1 +
-        text_width( prompt + query[0...cursor] ) ]
-      key = read_key
-      return nil if key.nil? or key == KEY_ESCAPE
-      return query if key == KEY_RETURN or key == "\n"
-      case key
-        when KEY_LEFT, "\e[D";    cursor -= 1 if cursor > 0
-        when KEY_RIGHT, "\e[C";   cursor += 1 if cursor < query.length
-        when "\e[1;5D", "\eOd";   cursor = word_prev query, cursor
-        when "\e[1;5C", "\eOc";   cursor = word_next query, cursor
-        when KEY_HOME;            cursor = 0
-        when KEY_END;             cursor = query.length
-        when KEY_DC, "\e[3~";     query.slice!(cursor, 1) if cursor < query.length
-        when KEY_BACKSPACE, "\b"
-          if cursor > 0
-            query.slice!(cursor - 1, 1)
-            cursor -= 1
-          end
-        else
-          if key.is_a?(String) and key.each_char.all?{ |char| char.ord.between?(32, 126) }
-            query.insert(cursor, key)
-            cursor += key.length
+    $>.print CURSOR_NORMAL
+    begin
+      loop do
+        $>.print "\e[%i;%if" % [ top + 1, left + 1 ]
+        $>.print ERASE_LINE
+        before = text_width( prompt + query[0...cursor] )
+        offset = [ left + before - Typr.width, 0 ].max
+        $>.print slice_width( prompt + query, offset, Typr.width - left + 1 )
+        $>.print "\e[%i;%if" % [ top + 1, left + 1 + before - offset ]
+        key = read_key
+        return nil if key.nil? or key == KEY_ESCAPE
+        return query if key == KEY_RETURN or key == "\n"
+        case key
+          when KEY_LEFT, "\e[D";    cursor -= 1 if cursor > 0
+          when KEY_RIGHT, "\e[C";   cursor += 1 if cursor < query.length
+          when KEY_ALT_LEFT, "\eD";    cursor = word_prev query, cursor
+          when KEY_ALT_RIGHT, "\eC";   cursor = word_next query, cursor
+          when KEY_HOME;            cursor = 0
+          when KEY_END;             cursor = query.length
+          when KEY_DC, "\e[3~";     query.slice!(cursor, 1) if cursor < query.length
+          when KEY_ALT_BACKSPACE
+            old = cursor
+            cursor = word_prev query, cursor
+            query.slice!(cursor, old - cursor)
+          when KEY_BACKSPACE, "\b"
+            if cursor > 0
+              query.slice!(cursor - 1, 1)
+              cursor -= 1
+            end
+          else
+            if key.is_a?(String) and key.each_char.all?{ |char| char.ord.between?(32, 126) }
+              query.insert(cursor, key)
+              cursor += key.length
+            end
+        end
+        cursor = 0 if cursor < 0
+        cursor = query.length if cursor > query.length
+        result = block.call( key, query, cursor ) if block
+        return result unless result.nil?
+        if completions and key == KEY_TAB
+          raw = query[0...cursor]
+          cmd = raw[/\w+/]
+          if cmd
+            items = IO.popen([{ 'COMP_LINE' => raw, 'COMP_POINT' => raw.bytesize.to_s },
+              'bash', '-c', <<~SH], err: '/dev/null', &:read)
+              _init_completion(){ cur=${COMP_WORDS[COMP_CWORD]}; prev=${COMP_WORDS[COMP_CWORD-1]}; }
+              source /usr/share/bash-completion/completions/#{cmd} 2>/dev/null || exit
+              COMP_WORDS=($COMP_LINE) COMP_CWORD=$(( ${#COMP_WORDS[@]} - 1 ))
+              Fn=$(complete -p #{cmd} 2>/dev/null | awk '{print $(NF-1)}')
+              eval "$Fn" 2>/dev/null && printf '%s\\n' "${COMPREPLY[@]}"
+            SH
+            items = items.split("\n").reject(&:empty?).uniq
+            if items.any?
+              grid = Grid.new(left: left, top: [top - items.size - 3, 0].max,
+                input: items.map{ |s| [s] }, border: :light,
+                colors: { columns: [[:blue, :default]] })
+              picked = grid.pick(:row, column: 0)
+              redraw&.call
+              $>.print CURSOR_NORMAL
+              if picked.is_a?(Integer)
+                word_start = cursor
+                word_start -= 1 while word_start > 0 and query[word_start - 1] != ' '
+                query[word_start...cursor] = items[picked]
+                cursor = word_start + items[picked].length
+              end
+            end
           end
+        end
       end
-      cursor = 0 if cursor < 0
-      cursor = query.length if cursor > query.length
-      result = block.call( key, query, cursor ) if block
-      return result unless result.nil?
+    ensure
+      $>.print CURSOR_INVISIBLE
     end
   end
 
@@ -344,6 +398,28 @@ module Typr
     Unicode::DisplayWidth.of( str.gsub(/\x1b\[[^m]+m/, '') )
   end
 
+  # Visible substring of +str+ starting at display-width +offset+, at most
+  # +width+ cells wide. ANSI escapes are zero-width and carried through so
+  # color state applies inside the window.
+  def self.slice_width str, offset, width
+    vis = 0
+    slice = +""
+    i = 0
+    while i < str.length
+      if str[i] == "\e"
+        seq = str[i..][/\A\e(\[[0-9;?]*[ -\/]*[@-~]|\][^\a\e]*(?:\a|\e\\)|[()=>0-9])/]
+        slice << seq if seq
+        i += seq ? seq.length : 1
+        next
+      end
+      cell = Unicode::DisplayWidth.of(str[i])
+      vis += cell
+      slice << str[i] if vis > offset and vis <= offset + width
+      i += 1
+    end
+    slice
+  end
+
   # Move the cursor back to the start of the previous word in +str+.
   def self.word_prev str, cursor
     cursor -= 1 while cursor > 0 and str[cursor - 1] == ' '

data/lib/text.rb

@@ -33,28 +33,40 @@ module Typr
     #   text << "appended line"       # alias for build
 
     def build input=nil
-      ( @lines = [0]; input = "" ) if rebuild = !input
+      ( input, @data, @lines = @data, "", [0] ) if rebuild = !input
       return self if rebuild && input == ""
-      input = StringIO.new( input.to_s.dup ) unless input.respond_to?(:read)
+      str = input.respond_to?(:read) ? input.read : input.to_s
       @tail = ""
-      until input.closed? or input.eof?
-        capacity = width - @margin.size - @tail.length
-        chunk = (capacity < 1) ? "x" : capacity
-        line = @tail + input.read(chunk)
-        if line.empty?
-          break
-        else
-          wrap_idx = line.index("\n") || line.rindex(" ") || line.length
-          wrap = [wrap_idx, line.length].min + 1
-          @data += line[0...wrap]
-          if wrap < line.length
-            @tail = line[wrap..-1]
-            @lines << @data.length
+      pos = 0
+      while pos < str.size || !@tail.empty?
+        capacity = width - @margin.size - real_size(@tail)
+        cap = [capacity, 1].max
+        added = 0; cells = 0
+        while pos + added < str.size
+          c = str[pos + added]
+          if c == ?\e
+            seq = str[(pos+added)..][/\A\e\[[0-9;]*m/]
+            added += seq ? seq.size : 1
+          elsif c == ?\n
+            added += 1; break
           else
-            @tail = ""
+            cw = Unicode::DisplayWidth.of(c)
+            break if cells + cw > cap
+            cells += cw; added += 1
           end
         end
-        break if rebuild && line[-1] == "\n"
+        line = @tail + str[pos, added]
+        pos += added
+        break if line.empty?
+        wrap_idx = line.index("\n") || line.rindex(" ") || line.length
+        wrap = [wrap_idx, line.length].min + 1
+        @data += line[0...wrap]
+        if wrap < line.length
+          @tail = line[wrap..-1]
+        else
+          @tail = ""
+        end
+        @lines << @data.length if wrap < line.length || line.include?("\n")
       end
       until @tail.empty?
         wrap_idx = @tail.index("\n") || @tail.rindex(" ") || @tail.length
@@ -84,10 +96,10 @@ module Typr
       text = ( header ? @header : @page[ row-@start ] )
       if row.is_a?(Integer) and @search[:matches].include? row
         background @colors[:search]
-        draw prepare( text, width )
+        draw prepare( text, width - @margin.size )
         background
       else
-        draw prepare( text, width )
+        draw prepare( text, width - @margin.size )
       end
     end
 

data/typr.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = "typr"
-  s.version = "1.3.0"
+  s.version = "1.5.0"
   s.date = "2026-07-25"
   s.homepage = "https://codeberg.org/typr/typr"
   s.licenses = ["MIT"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typr
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Kilian Reitmayr