typr 1.8.0 → 1.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02fb4a45192b9a6bc2b3a751033a71e058b2abcb33b77d8873c991a2d6031dd1
-  data.tar.gz: 878f286e0c40eb45b0b5c5216633bc0a9ff82c7f6bc03d18531a80090936e2af
+  metadata.gz: 5c61c73e0ce9201962acda993655743ab611ae86a2a3102d64dd05bacb223751
+  data.tar.gz: d0474937ff2a6ad8cb5eb39918eac2302d7114998e9e6775a99f6b52a1727b13
 SHA512:
-  metadata.gz: 921906f7edae965d3ea48ed62e8eae91a770ad63dcf7cc3f20bb8463c9bbef280bcca2d2577317e4dd6c71d48b3740630bfaedf2d8c617cc9878d01381eebb9e
-  data.tar.gz: d0db793255d8969a1181193dee6b06227efc2c0248fff99ca6407f6d5944ece37dc330e8cdabafa26229e98a299a576ebc245ea4e4ebd5a25661b20526d094cc
+  metadata.gz: 76773590e95c2693fdc3df40a9020a07f5817357748cb9aca13490d26deb27c8d07c54815b4a8e118ea562e1167672edfea312ed4f3b372e2cc4be00edfa0845
+  data.tar.gz: 3452ef2e2b11a67f19ffbca386ebac9c3abddd730db58c5dd09038edbafbc528c04fcf13042fef4339ce3edb7a2af62b8be99a673d98ecfd4be3b63886c07c1c

data/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [vx.y.z] — __DATE__
 
+## [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
+- RI documentation pass — every class, method, attribute, and constant now carries a doc comment with behavior, `@param`/`@return` contracts, and runnable examples: RDoc reports 222/222 parts documented (previously 38 undocumented). Grouped comments were split so RDoc attaches them to each sibling attribute/method, and the generated `Space` edge accessors are documented through their `attr_writer` entry
+- `Typr#prepare` slimmed to pad-or-delegate — the 13-line manual width scan duplicated `real_size` and `clip`, so it now clips overflow via `clip` (the single truncation engine) and pads the result to exact width; the uncalled and broken `fade` flag (standalone `fade` is unchanged) is dropped
+- Read-line internals made private — `Typr.slice_width` and `word_prev`/`word_next` serve only `read_line`, so they are `private_class_method` now; their doc blocks stay for RI
+- 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
 
 ### Changed

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/lib/browser.rb

@@ -5,6 +5,7 @@ require_relative 'line.rb'
 
 module Typr
 
+  # Bundled extension => MIME-type database (share/mimetypes).
   MIMETYPES = eval File.read( __dir__ + "/../share/mimetypes" )
 
   # A file-system directory browser built on Grid. Renders entries as rows
@@ -33,26 +34,54 @@ module Typr
   #   Escape          | quit, returns nil
 
   class Browser < Grid
+    ##
+    # Browser state: +directory+ the current path, +user+ the login name
+    # shown in the info bar, +pwd+ alias of +directory+, +view+ the active
+    # column view name.
+    #
+    #   browser.directory   #=> "/tmp/"
+    #   browser.view        #=> :compact
+
     attr_accessor :directory, :user, :pwd, :view
+    ##
+    # +mimetype_db+ toggles the bundled extension database, +mimetype_magic+
+    # the +file --mime-type+ fallback for unknown extensions.
+    #
+    #   browser.mimetype_db = false   # skip extension lookups
+
     attr_accessor :mimetype_db, :mimetype_magic
 
-    ## Height minus 2 rows reserved for path bar and command line.
+    ##
+    # Bottom edge pulled in one row for the command line (the path bar is
+    # reserved by {#top}).
+    #
+    #   browser.bottom   #=> terminal_bottom - 1
+    #
+    # @return [Integer]
 
     def bottom; super - 1 end
 
-    ## Top offset plus one row for the path info bar.
+    ##
+    # Top edge pushed down one row for the path info bar.
+    #
+    #   browser.top   #=> constructor top + 1
+    #
+    # @return [Integer]
 
     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] 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
 
     def cd dir, append=false, trim=0
       return unless dir
@@ -164,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
@@ -176,10 +207,15 @@ module Typr
     end
 
     ##
-    # Resolves hint characters typed on a row. Returns the matching row id
-    # for fast navigation, otherwise falls through to Stack#send.
+    # Resolve hint characters typed on a row to a row id; a click on the
+    # info bar or command line dispatches that binding instead. Falls
+    # through to {Stack#send} for keys and navigation.
+    #
+    #   browser.send "1"    # => row id if hint "1" is visible
+    #   browser.send ?s      # => runs the sort command (a bound key)
     #
-    #   browser.send "1"   # => row id if hint "1" is visible
+    # @param key [Typr::Mouse, String] mouse event, hint char, or key sequence
+    # @return [Integer, String, Symbol, nil] picked row id, bound command result, or super's response
 
     def send key
       if key.is_a?(Typr::Mouse) and key.press? and key.left?
@@ -200,23 +236,32 @@ module Typr
       else super end
     end
 
-    ## Returns the current directory path as the confirm result.
+    ##
+    # Returns the current directory path as the confirm result.
+    #
+    #   browser.confirm   #=> "/tmp/"
+    #
+    # @return [String]
 
     def confirm; return @directory end
 
     ## Prompts to select rows by index. Returns chosen ids or nil.
     #
     #   browser.mark   # => [0, 2, 5] or nil
+    #
+    # @return [Array<Integer>, nil]
 
     def mark; return @user.ask( 'mark files': [self, :rows] ) end
 
     ## Toggles selection for every row within a "from..to" range.
     #
     #   browser.mark_range   # prompts for from/to, toggles selection
+    #
+    # @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.
@@ -234,24 +279,32 @@ module Typr
     ## Navigate up one directory.
     #
     #   browser.back   # equivalent to cd ".."
+    #
+    # @return [void]
 
     def back; cd ".." end
 
     ## Navigate to the root directory.
     #
     #   browser.root   # => cd "/"
+    #
+    # @return [void]
 
     def root; cd ?/ end
 
     ## Navigate to the home directory.
     #
     #   browser.home   # => cd "~"
+    #
+    # @return [void]
 
     def home; cd ?~ end
 
     ## Toggle visibility of hidden files (those starting with a dot).
     #
-    #   browser.toggle_hidden
+    #   browser.toggle_hidden   # rescans the directory
+    #
+    # @return [void]
 
     def toggle_hidden
       @show_hidden = !@show_hidden
@@ -259,6 +312,10 @@ module Typr
     end
 
     ## Display a help grid listing all keybindings.
+    #
+    #   browser.help   # => picked binding row id or nil
+    #
+    # @return [Integer, nil]
 
     def help; @user.help end
 
@@ -266,35 +323,46 @@ module Typr
     # Reset display, selection, and position state then re-sort.
     #
     #   browser.reset_view
+    #
+    # @return [void]
 
     def reset_view; reset [:display, :selection]; cd @directory; sort end
 
     ## Open a filter popup on the chosen row/column and apply the input.
     #
     #   browser.filter_view   # prompts for filter text
+    #
+    # @return [void]
 
     def filter_view; add_filter *@user.ask(
       filter: [ popup( type: :"[f]ilter" ), :row, NAME, { column: 0 }], with: :line ) end
 
-    ## Open live `/` search filtered on the name column.
+    ## Open live `/` narrowing filtered on the name column.
+    #
+    #   browser.narrow   # type to narrow, Escape restores, Enter commits
     #
-    #   browser.search   # type to narrow, Escape restores, Enter commits
+    # @return [void]
 
-    def search
+    def narrow
       @suppress_user = true
       pick :none, column: NAME
       @suppress_user = false
     end
+    alias search narrow
 
     ## Open a sort-picker popup to choose a column to sort by.
     #
     #   browser.sort_view   # pick a column header to sort
+    #
+    # @return [void]
 
     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
+    #
+    # @return [void]
 
     def views; change_view( popup( type: :"[v]iews", input: @views.keys ).pick( :row, column: 0 ) )  end
 
@@ -315,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'
@@ -402,6 +476,8 @@ module Typr
     # within each prefix grouping.
     #
     #   browser.sort   # re-sorts with dirs first
+    #
+    # @return [nil]
 
     def sort
       @sort ||= NAME
@@ -432,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
@@ -551,13 +630,13 @@ full:    %i[ name size permissions executable printable owner group
         @user ||= Line.new( parent:self, left:->{@parent.left}, top:->{@parent.bottom+1},
           bindings: bindings_labels )
       else
-        cmds = { "[h]elp" => :help, "[/]:search" => :search,
+        cmds = { "[h]elp" => :help, "[/]:narrow" => :narrow,
           "[f]ilter" => :filter_view, "[s]ort" => :sort_view, "[v]iews" => :views,
           "[r]eset" => :reset_view, "[m]ark" => :mark,
           "[M]ark_range" => :mark_range, "mark_[a]ll" => :mark_all,
           "[i]nvert_mark" => :mark_invert, "[~]:home" => :home,
           "[H]idden_files" => :toggle_hidden }
-        plain = ["[h]elp", "[/]:search"] +
+        plain = ["[h]elp", "[/]:narrow"] +
           @colors[:actions].map { |name, _| "[" + name.to_s[0] + "]" + name.to_s[1..] } +
           %w[ [r]eset [m]ark [M]ark_range mark_[a]ll
           [i]nvert_mark [~]:home [H]idden_files [back]:.. [up] [down] [pageup] [pagedown] [home] [end] [esc]:quit [return]:confirm\  ]

data/lib/grid.rb

@@ -8,17 +8,51 @@ module Typr
   #   grid = Typr::Grid.new(
   #     input:  [ ["Alice", 30], ["Bob", 25] ],
   #     header: [:name, :age],
-  #     format: [:max, :right]
-#   )
-#   grid.show
-#
-  # Column format tokens: +Integer+ (fixed width), +:min+ (auto), +:max+ (fill remaining).
+  #     format: [:max, :min]
+  #   )
+  #   grid.show
+  #
+  # 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+.
 
   class Grid < Stack # Table
+    ##
+    # Display and transform state: +format+ per-column width tokens,
+    # +procs+ per-column processors, +filters+ the active [column, query]
+    # pairs, +data+ the rows (Array or Hash), and +map+ the visible row
+    # ids after filtering/sorting.
+    #
+    #   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
+
     attr_accessor :align, :rawsort, :rawfilter, :reverse
+    ##
+    # Overrides the column render order (see {#sequence}).
+    #
+    #   grid.sequence = [2, 0, 1]
+
     attr_writer :sequence
 
     ##
@@ -52,7 +86,8 @@ module Typr
     ##
     # Column render order. Defaults to 0..n-1; override with +sequence=+.
     #
-    #   grid.sequence  #=> [0, 1, 2]
+    #   grid.sequence      #=> [0, 1, 2]
+    #   grid.sequence = [2, 0, 1]
     #
     # @return [Array<Integer>]
 
@@ -115,12 +150,16 @@ module Typr
     end
 
     ##
-    # Set column headers. Symbols are auto-defined as +UPCASE_I+ constants.
+    # 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]
-    #   # defines NAME_0 = "name", AGE_1 = "age"
+    #   grid.header = ["name", "age"]
+    #   Typr::NAME  #=> 0
+    #   Typr::AGE   #=> 1
+    #   grid.header = "People"   # label bar, defines no constants
     #
-    # @param h [Array<String, Symbol>]
+    # @param h [Array<String, Symbol>, String] header labels or a label bar
 
     def header=( h ); super
       h.each_with_index{ |h,i|
@@ -182,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
@@ -235,23 +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 column is given, `Grid` overrides `Stack#pick` to add interactive
-    # text filtering of rows by the given column. Filter text is shown at the
-    # bottom of the grid. Passes through to `super` for all other types or
-    # when no column is given.
-    #
-    #   grid.pick :row, 0, column: :name
-    #   grid.pick :row, 0, column: :all   # match any column
-    #
-    # @param type [Symbol] type is ignored (always :row); passed to super otherwise
-    # @param column [Symbol, String] column name to filter on, or :all (default nil)
+    # 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
+    #
+    # 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
@@ -308,12 +375,15 @@ module Typr
     end
 
     ##
-    # Sort by column (toggle direction on repeat).
+    # Dispatch a mouse press on the header row to a column sort (clicking
+    # the header cell for a column calls +sort_by+); everything else falls
+    # through to {Stack#send}.
     #
-    #   grid.sort_by :age
-    #   grid.sort_by :age  # reverses
+    #   grid.send Typr::Mouse.new(0, 12, grid.top + 1, :press, 0)  #=> :scroll
+    #   grid.send Typr::KEY_DOWN                                    # scrolls
     #
-    # @param column [Integer, Symbol]
+    # @param key [Typr::Mouse, String] mouse event or key sequence
+    # @return [Symbol, Object] +:scroll+ on a header click, super's response otherwise
 
     def send key
       if key.is_a?(Typr::Mouse) and key.press? and key.left? and
@@ -328,6 +398,15 @@ module Typr
       super
     end
 
+    ##
+    # Sort by column (toggle direction on repeat).
+    #
+    #   grid.sort_by :age
+    #   grid.sort_by :age  # reverses
+    #
+    # @param column [Integer, Symbol] column index or header-name symbol
+    # @return [void]
+
     def sort_by column
       column = @header.index( column.to_s ) if column.is_a? Symbol
       if @sort and (column == @sort) then @reverse = !@reverse
@@ -338,7 +417,7 @@ module Typr
     ##
     # Execute the sort and update +@map+.
     #
-    # @return [false, void]
+    # @return [false, nil]
 
     def sort
       return false unless @sort
@@ -468,6 +547,7 @@ module Typr
       data.each_with_index{ |row, id|
         self[ is_hash? ? row.shift : id + skip ] = row }
       sort
+      self
     end
 
     ##
@@ -481,7 +561,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,{}