v0.6.0 mouse: every wheel direction and side button named; tui: a scrollbar the pointer drives

* mouse: the wheel's four directions and the side buttons

parseSGRMouse read a report's low two bits alone, so a wheel tilted left or
right (66, 67) reported as WheelDown, and a mouse's back and forward buttons
(128, 129) as a left or middle press. It now decodes by bank: bits 0-1 number
a button within the main three and none, the wheel's four directions (bit 6),
or buttons 8 to 11 (bit 7). WheelLeft and WheelRight join MouseButton after
Forward, so every existing value keeps its number; Back and Forward are
reported for buttons 8 and 9; buttons 10 and 11, and a report with both bank
bits set, are dropped as KeyNone. A wheel step is a press with no release in
every direction.

* tui: ScrollThumb and ScrollDrag

ScrollThumb is the thumb ScrollBarStyled draws, its first row and height,
exported so an application hit-tests the bar it drew. ScrollDrag drives a bar
by the pointer, rows counted from the track's top: a press on the thumb takes
hold where it lands, a press on the track moves the thumb's middle there and
takes hold, and each drag keeps the held row under the pointer, clamped at the
track's ends, at the nearest offset when there are fewer offsets than rows.
Each call returns the offset to show.

A table of SGR reports covers each bank and drops the buttons past 9; a
property test over every track of 3 to 10 rows and content up to 30 checks
each press and drag against the thumb ScrollThumb draws.

tui/README.md

@@ -187,6 +187,28 @@ r.List(items, state.Selection, state.Offset, tui.ListOpts{CursorBg: color.DarkSl
 r.ScrollBar(r.W-1, state.Offset, state.Visible, state.Total, color.IronGray)
 ```
 
+`ScrollThumb` is the thumb a bar draws. `ScrollDrag` drives one by the
+pointer, rows counted from the track's top: a press on the thumb takes hold
+of it, a press on the track moves the thumb's middle there and takes hold, and
+a drag keeps the held row under the pointer, each returning the offset to show.
+
+```go
+var drag tui.ScrollDrag        // kept across events
+bar := r.Sub(r.W-1, 0, 1, r.H) // the column ScrollBar draws, in screen cells at bar.X, bar.Y
+
+// per left button event:
+switch ev.MouseAction {
+case terminal.MouseActionPress:
+    if ev.MouseX == bar.X {
+        state.ScrollTo(drag.Press(ev.MouseY-bar.Y, bar.H, state.Offset, state.Visible, state.Total))
+    }
+case terminal.MouseActionDrag:
+    state.ScrollTo(drag.Drag(ev.MouseY-bar.Y, bar.H, state.Offset, state.Visible, state.Total))
+case terminal.MouseActionRelease:
+    drag.Release()
+}
+```
+
 ### Modal dialog
 
 ```go
@@ -265,5 +287,6 @@ Pure logic, no rendering — usable independently:
   (widget default or row background) — check specific widget docs. A zero
   background with no Bg color bits is transparent: the cell keeps the
   background beneath it, bits and all.
-- Mouse hit testing: `TabBar` returns `[]TabBounds`; other widgets require
-  application-side geometry from the regions used.
+- Mouse hit testing: `TabBar` returns `[]TabBounds`, and `ScrollDrag` maps a
+  scrollbar's rows to offsets; other widgets require application-side
+  geometry from the regions used.

tui/scrollbar.go

@@ -35,8 +35,8 @@ func (r Region) ScrollBarStyled(x int, offset, visible, total int, opts ScrollBa
 	}
 
 	trackH := r.H
-	if total <= visible || trackH < 3 {
-		// No scrolling needed or track too small
+	thumbY, thumbH := ScrollThumb(trackH, offset, visible, total)
+	if thumbH == 0 {
 		if opts.HideIdle {
 			return
 		}
@@ -46,14 +46,6 @@ func (r Region) ScrollBarStyled(x int, offset, visible, total int, opts ScrollBa
 		return
 	}
 
-	thumbH := min(max((visible*trackH)/total, 1), trackH)
-	maxScroll := total - visible
-	thumbY := 0
-	if maxScroll > 0 {
-		thumbY = (offset * (trackH - thumbH)) / maxScroll
-	}
-	thumbY = min(max(thumbY, 0), trackH-thumbH)
-
 	for y := range trackH {
 		if y >= thumbY && y < thumbY+thumbH {
 			r.Cell(x, y, thumbCh, opts.ThumbFg, opts.Bg, terminal.AttrNone)
@@ -63,6 +55,68 @@ func (r Region) ScrollBarStyled(x int, offset, visible, total int, opts ScrollBa
 	}
 }
 
+// ScrollThumb is the thumb a scrollbar trackH rows tall draws for offset: its
+// first row and its height, 0 when content fits or the track is under 3 rows
+func ScrollThumb(trackH, offset, visible, total int) (y, h int) {
+	if total <= visible || trackH < 3 {
+		return 0, 0
+	}
+	h = min(max((visible*trackH)/total, 1), trackH)
+	y = (offset * (trackH - h)) / (total - visible)
+	return min(max(y, 0), trackH-h), h
+}
+
+// ScrollDrag holds a scrollbar's thumb under the pointer, rows counted from the
+// track's top: a press on the thumb takes hold where it lands, a press on the
+// track moves the thumb's middle there first, and each drag keeps the row held
+// under the pointer. Each call returns the offset to show.
+type ScrollDrag struct {
+	Active bool // The thumb is held
+	Grab   int  // The thumb's row the pointer holds
+}
+
+// Press takes hold of the thumb at track row y; off the track it holds nothing
+func (d *ScrollDrag) Press(y, trackH, offset, visible, total int) int {
+	top, h := ScrollThumb(trackH, offset, visible, total)
+	d.Active = h > 0 && y >= 0 && y < trackH
+	if !d.Active {
+		return offset
+	}
+	if y < top || y >= top+h {
+		offset = scrollOffsetAt(y-h/2, trackH, h, visible, total)
+		top, _ = ScrollThumb(trackH, offset, visible, total)
+	}
+	d.Grab = min(max(y-top, 0), h-1)
+	return offset
+}
+
+// Drag moves the held row to track row y, clamped at the track's ends
+func (d *ScrollDrag) Drag(y, trackH, offset, visible, total int) int {
+	_, h := ScrollThumb(trackH, offset, visible, total)
+	if !d.Active || h == 0 {
+		return offset
+	}
+	return scrollOffsetAt(y-d.Grab, trackH, h, visible, total)
+}
+
+// Release lets go of the thumb
+func (d *ScrollDrag) Release() { *d = ScrollDrag{} }
+
+// scrollOffsetAt is the offset whose thumb, h rows tall, starts nearest row top
+func scrollOffsetAt(top, trackH, h, visible, total int) int {
+	span, maxScroll := trackH-h, total-visible
+	top = min(max(top, 0), span)
+	o := (top*maxScroll + span - 1) / span // The first offset whose thumb starts at or past top
+	if o > 0 {
+		at, _ := ScrollThumb(trackH, o, visible, total)
+		before, _ := ScrollThumb(trackH, o-1, visible, total)
+		if at-top > top-before {
+			return o - 1
+		}
+	}
+	return o
+}
+
 // ScrollIndicator draws compact indicator text (Top/Bot/XX%)
 func (r Region) ScrollIndicator(y int, offset, visible, total int, fg color.RGB) {
 	if y < 0 || y >= r.H {

tui/widget_test.go

@@ -468,6 +468,60 @@ func TestWindowShowsTheRowsInView(t *testing.T) {
 	r.Sub(8, 0, 4, 3).Window(10, &v, MonoTheme.Text, content) // no columns, past the right edge
 }
 
+// A press on a scrollbar's track moves the thumb's middle to it and a press on
+// the thumb leaves it, either taking hold; a drag keeps the held row under the
+// pointer, clamped at the ends, or as near as an offset can put it when there are
+// fewer offsets than rows. A bar with no thumb, or a row off it, holds nothing.
+func TestScrollDragHoldsTheThumbUnderThePointer(t *testing.T) {
+	near := func(tops []int, want, got int) bool {
+		for _, top := range tops {
+			if max(top-want, want-top) < max(got-want, want-got) {
+				return false
+			}
+		}
+		return true
+	}
+	for trackH := 3; trackH <= 10; trackH++ {
+		for total := 1; total <= 30; total++ {
+			for visible := 1; visible <= total+1; visible++ {
+				var tops []int
+				for o := 0; o <= total-visible; o++ {
+					top, _ := ScrollThumb(trackH, o, visible, total)
+					tops = append(tops, top)
+				}
+				for y := -1; y <= trackH; y++ {
+					var d ScrollDrag
+					from := (total - visible) / 3
+					fromTop, h := ScrollThumb(trackH, from, visible, total)
+					off := d.Press(y, trackH, from, visible, total)
+					top, _ := ScrollThumb(trackH, off, visible, total)
+					onThumb := func(top int) bool { return y >= top && y < top+h }
+					switch {
+					case h == 0 || y < 0 || y >= trackH:
+						if d.Active || off != from {
+							t.Fatalf("%d/%d/%d: a press at %d off the bar holds %v at %d", trackH, visible, total, y, d.Active, off)
+						}
+						continue
+					case onThumb(fromTop):
+						if off != from {
+							t.Fatalf("%d/%d/%d: a press on the thumb moved it %d to %d", trackH, visible, total, from, off)
+						}
+					case !near(tops, min(max(y-h/2, 0), trackH-h), top) || !onThumb(top) && slices.ContainsFunc(tops, onThumb):
+						t.Fatalf("%d/%d/%d: a press at %d starts the thumb at %d", trackH, visible, total, y, top)
+					}
+					for to := -2; to <= trackH+1; to++ {
+						got, _ := ScrollThumb(trackH, d.Drag(to, trackH, off, visible, total), visible, total)
+						if want := min(max(to-d.Grab, 0), trackH-h); !near(tops, want, got) {
+							t.Fatalf("%d/%d/%d: held at %d and dragged to %d, the thumb starts at %d, want near %d",
+								trackH, visible, total, d.Grab, to, got, want)
+						}
+					}
+				}
+			}
+		}
+	}
+}
+
 // A label is drawn a column a rune, so one holding runes of more than a byte
 // keeps them together: each widget draws s as many times as it is given it
 func TestLabelsKeepTheirRunesTogether(t *testing.T) {