nook: add minimap, the overview-model foundation for the minimap gutter

Author: truffle-dev

cmd/nook/internal/minimap/minimap.go

@@ -0,0 +1,124 @@
+// Package minimap models nook's document overview gutter: the narrow column
+// that shows a whole file downsampled to the editor's height with the current
+// viewport highlighted. Like splitlayout, it is pure geometry — no I/O, no
+// buffer access, constant-time construction — so it never blocks a frame and
+// stays inside nook's first-paint rule. The host feeds it a line count and the
+// viewport bounds and asks it three things: which source lines a minimap row
+// represents (so the host can render per-row density from the buffer), which
+// minimap rows the viewport covers (for the highlight band), and which source
+// line a clicked row maps to (for click-to-scroll). What a row looks like is
+// the host's concern; where a row sits is this package's.
+package minimap
+
+// Model is an immutable snapshot of the overview geometry for one frame. All
+// fields are in logical-line space; the host collapses soft wrap before
+// filling it in. Construct one per render from the current buffer and viewport
+// and throw it away — there is no mutable state to keep.
+type Model struct {
+	// TotalLines is the document's logical line count (>= 0).
+	TotalLines int
+	// MapHeight is the number of terminal rows the minimap column occupies.
+	MapHeight int
+	// ViewportTop is the 0-based first logical line visible in the editor.
+	ViewportTop int
+	// ViewportHeight is the number of logical lines visible in the editor.
+	ViewportHeight int
+}
+
+// Active reports whether the minimap has anything to draw. A zero-height column
+// or an empty document has no overview, and every other method degrades to a
+// safe empty answer when this is false.
+func (m Model) Active() bool {
+	return m.MapHeight > 0 && m.TotalLines > 0
+}
+
+// Downsampled reports whether the document is taller than the column, so each
+// minimap row stands in for more than one source line. When false the mapping
+// is identity and top-aligned: source line r draws on row r.
+func (m Model) Downsampled() bool {
+	return m.TotalLines > m.MapHeight
+}
+
+// LineRange returns the half-open span of source lines [start, end) that
+// minimap row draws. Rows past the end of a short document return an empty
+// span (start == end) so the host paints them blank. Out-of-range rows return
+// an empty span at the document end.
+func (m Model) LineRange(row int) (start, end int) {
+	if !m.Active() || row < 0 || row >= m.MapHeight {
+		return m.TotalLines, m.TotalLines
+	}
+	if !m.Downsampled() {
+		if row < m.TotalLines {
+			return row, row + 1
+		}
+		return m.TotalLines, m.TotalLines
+	}
+	start = row * m.TotalLines / m.MapHeight
+	end = (row + 1) * m.TotalLines / m.MapHeight
+	return start, end
+}
+
+// RowForLine returns the minimap row that contains source line, clamped into
+// [0, MapHeight-1]. It is the inverse of LineRange: RowForLine of a row's start
+// line lands back on that row.
+func (m Model) RowForLine(line int) int {
+	if !m.Active() {
+		return 0
+	}
+	if line < 0 {
+		line = 0
+	}
+	if line > m.TotalLines-1 {
+		line = m.TotalLines - 1
+	}
+	var row int
+	if m.Downsampled() {
+		// Exact inverse of LineRange's floor(row*Total/Height) tiling: the row
+		// whose half-open span contains line. A plain line*Height/Total floor
+		// lands one row early at some tile boundaries, so bias by the tile.
+		row = ((line+1)*m.MapHeight - 1) / m.TotalLines
+	} else {
+		row = line
+	}
+	return clamp(row, 0, m.MapHeight-1)
+}
+
+// ViewportWindow returns the half-open span of minimap rows [start, end) the
+// current viewport covers, for drawing the highlight band. The band is always
+// at least one row tall on an active map so it never disappears on a document
+// far taller than the column. Returns an empty span when the map is inactive
+// or the viewport has no height.
+func (m Model) ViewportWindow() (start, end int) {
+	if !m.Active() || m.ViewportHeight <= 0 {
+		return 0, 0
+	}
+	top := clamp(m.ViewportTop, 0, m.TotalLines-1)
+	bottom := clamp(m.ViewportTop+m.ViewportHeight-1, 0, m.TotalLines-1)
+	start = m.RowForLine(top)
+	end = m.RowForLine(bottom) + 1
+	if end <= start {
+		end = start + 1
+	}
+	return clamp(start, 0, m.MapHeight), clamp(end, 0, m.MapHeight)
+}
+
+// LineForRow returns the source line to scroll to when the user clicks minimap
+// row: the first line that row represents, clamped into the document. Used to
+// turn a click at a y offset into a scroll target.
+func (m Model) LineForRow(row int) int {
+	if !m.Active() {
+		return 0
+	}
+	start, _ := m.LineRange(clamp(row, 0, m.MapHeight-1))
+	return clamp(start, 0, m.TotalLines-1)
+}
+
+func clamp(v, lo, hi int) int {
+	if v < lo {
+		return lo
+	}
+	if v > hi {
+		return hi
+	}
+	return v
+}

cmd/nook/internal/minimap/minimap_test.go

@@ -0,0 +1,243 @@
+package minimap
+
+import "testing"
+
+func TestActive(t *testing.T) {
+	tests := []struct {
+		name string
+		m    Model
+		want bool
+	}{
+		{"zero", Model{}, false},
+		{"no height", Model{TotalLines: 100, MapHeight: 0}, false},
+		{"no lines", Model{TotalLines: 0, MapHeight: 20}, false},
+		{"negative height", Model{TotalLines: 100, MapHeight: -5}, false},
+		{"live", Model{TotalLines: 100, MapHeight: 20}, true},
+		{"single line single row", Model{TotalLines: 1, MapHeight: 1}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.m.Active(); got != tt.want {
+				t.Fatalf("Active() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDownsampled(t *testing.T) {
+	if !(Model{TotalLines: 100, MapHeight: 20}).Downsampled() {
+		t.Fatal("100 lines in 20 rows should downsample")
+	}
+	if (Model{TotalLines: 5, MapHeight: 10}).Downsampled() {
+		t.Fatal("5 lines in 10 rows should not downsample")
+	}
+	if (Model{TotalLines: 10, MapHeight: 10}).Downsampled() {
+		t.Fatal("equal lines and rows should not downsample")
+	}
+}
+
+func TestLineRangeInactive(t *testing.T) {
+	m := Model{TotalLines: 0, MapHeight: 10}
+	start, end := m.LineRange(0)
+	if start != 0 || end != 0 {
+		t.Fatalf("inactive LineRange = (%d,%d), want (0,0)", start, end)
+	}
+}
+
+func TestLineRangeOutOfRange(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10}
+	for _, row := range []int{-1, 10, 999} {
+		start, end := m.LineRange(row)
+		if start != 100 || end != 100 {
+			t.Fatalf("LineRange(%d) = (%d,%d), want (100,100)", row, start, end)
+		}
+	}
+}
+
+// When the document is shorter than the column, each source line draws on its
+// own row (identity, top-aligned) and rows past the end draw blank.
+func TestLineRangeNotDownsampled(t *testing.T) {
+	m := Model{TotalLines: 5, MapHeight: 10}
+	for row := 0; row < 5; row++ {
+		start, end := m.LineRange(row)
+		if start != row || end != row+1 {
+			t.Fatalf("LineRange(%d) = (%d,%d), want (%d,%d)", row, start, end, row, row+1)
+		}
+	}
+	for row := 5; row < 10; row++ {
+		start, end := m.LineRange(row)
+		if start != end {
+			t.Fatalf("LineRange(%d) = (%d,%d), want empty span", row, start, end)
+		}
+	}
+}
+
+// A downsampled map tiles every source line across the rows with no gaps and no
+// overlaps: row r's end is row r+1's start, the first row starts at 0, and the
+// last row ends at TotalLines.
+func TestLineRangeDownsampledTiling(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10}
+	prevEnd := 0
+	for row := 0; row < m.MapHeight; row++ {
+		start, end := m.LineRange(row)
+		if start != prevEnd {
+			t.Fatalf("row %d starts at %d, want %d (contiguous)", row, start, prevEnd)
+		}
+		if end < start {
+			t.Fatalf("row %d span (%d,%d) is inverted", row, start, end)
+		}
+		prevEnd = end
+	}
+	if prevEnd != m.TotalLines {
+		t.Fatalf("last row ends at %d, want %d", prevEnd, m.TotalLines)
+	}
+}
+
+// Uneven division must still tile without gaps: 7 lines over 3 rows.
+func TestLineRangeUnevenTiling(t *testing.T) {
+	m := Model{TotalLines: 7, MapHeight: 3}
+	prevEnd := 0
+	for row := 0; row < m.MapHeight; row++ {
+		start, end := m.LineRange(row)
+		if start != prevEnd {
+			t.Fatalf("row %d starts at %d, want %d", row, start, prevEnd)
+		}
+		prevEnd = end
+	}
+	if prevEnd != 7 {
+		t.Fatalf("tiling covered %d lines, want 7", prevEnd)
+	}
+}
+
+// RowForLine is the inverse of LineRange: the start line of a row maps back to
+// that row.
+func TestRowForLineInverseOfLineRange(t *testing.T) {
+	for _, m := range []Model{
+		{TotalLines: 100, MapHeight: 10},
+		{TotalLines: 7, MapHeight: 3},
+		{TotalLines: 10000, MapHeight: 20},
+	} {
+		for row := 0; row < m.MapHeight; row++ {
+			start, end := m.LineRange(row)
+			if start == end {
+				continue // blank row on a short doc has no start line
+			}
+			if got := m.RowForLine(start); got != row {
+				t.Fatalf("T=%d M=%d: RowForLine(start=%d) = %d, want %d",
+					m.TotalLines, m.MapHeight, start, got, row)
+			}
+		}
+	}
+}
+
+func TestRowForLineClamps(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10}
+	if got := m.RowForLine(-50); got != 0 {
+		t.Fatalf("RowForLine(-50) = %d, want 0", got)
+	}
+	if got := m.RowForLine(9999); got != m.MapHeight-1 {
+		t.Fatalf("RowForLine(9999) = %d, want %d", got, m.MapHeight-1)
+	}
+}
+
+func TestRowForLineInactive(t *testing.T) {
+	if got := (Model{}).RowForLine(5); got != 0 {
+		t.Fatalf("inactive RowForLine = %d, want 0", got)
+	}
+}
+
+func TestViewportWindowInactive(t *testing.T) {
+	start, end := (Model{}).ViewportWindow()
+	if start != 0 || end != 0 {
+		t.Fatalf("inactive ViewportWindow = (%d,%d), want (0,0)", start, end)
+	}
+}
+
+func TestViewportWindowZeroHeight(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10, ViewportTop: 5, ViewportHeight: 0}
+	start, end := m.ViewportWindow()
+	if start != 0 || end != 0 {
+		t.Fatalf("zero-height viewport = (%d,%d), want (0,0)", start, end)
+	}
+}
+
+// On a document far taller than the column the band must never vanish: it is at
+// least one row tall even when the viewport spans a fraction of a single row.
+func TestViewportWindowBandNeverVanishes(t *testing.T) {
+	m := Model{TotalLines: 10000, MapHeight: 20, ViewportTop: 0, ViewportHeight: 10}
+	start, end := m.ViewportWindow()
+	if end-start < 1 {
+		t.Fatalf("band = [%d,%d), want at least one row", start, end)
+	}
+}
+
+// A viewport covering the whole document should light the whole column.
+func TestViewportWindowFullDocument(t *testing.T) {
+	m := Model{TotalLines: 50, MapHeight: 10, ViewportTop: 0, ViewportHeight: 50}
+	start, end := m.ViewportWindow()
+	if start != 0 || end != m.MapHeight {
+		t.Fatalf("full-doc window = [%d,%d), want [0,%d)", start, end, m.MapHeight)
+	}
+}
+
+// The band tracks the viewport down the document and stays within the column.
+func TestViewportWindowTracksAndClamps(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10, ViewportTop: 90, ViewportHeight: 20}
+	start, end := m.ViewportWindow()
+	if start < 0 || end > m.MapHeight {
+		t.Fatalf("window [%d,%d) escapes column [0,%d]", start, end, m.MapHeight)
+	}
+	if end <= start {
+		t.Fatalf("window [%d,%d) is empty", start, end)
+	}
+	// Viewport at the bottom should light the last row.
+	if end != m.MapHeight {
+		t.Fatalf("bottom viewport window ends at %d, want %d", end, m.MapHeight)
+	}
+}
+
+func TestLineForRowRoundTrip(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10}
+	for row := 0; row < m.MapHeight; row++ {
+		line := m.LineForRow(row)
+		if m.RowForLine(line) != row {
+			t.Fatalf("LineForRow(%d)=%d does not round-trip via RowForLine", row, line)
+		}
+	}
+}
+
+func TestLineForRowClampsAndStaysInDocument(t *testing.T) {
+	m := Model{TotalLines: 100, MapHeight: 10}
+	for _, row := range []int{-5, 0, 9, 50} {
+		line := m.LineForRow(row)
+		if line < 0 || line > m.TotalLines-1 {
+			t.Fatalf("LineForRow(%d) = %d, out of document [0,%d]", row, line, m.TotalLines-1)
+		}
+	}
+}
+
+func TestLineForRowInactive(t *testing.T) {
+	if got := (Model{}).LineForRow(3); got != 0 {
+		t.Fatalf("inactive LineForRow = %d, want 0", got)
+	}
+}
+
+// A single-line, single-row map is the smallest active shape; every method must
+// stay in bounds.
+func TestSingletonMap(t *testing.T) {
+	m := Model{TotalLines: 1, MapHeight: 1, ViewportTop: 0, ViewportHeight: 1}
+	start, end := m.LineRange(0)
+	if start != 0 || end != 1 {
+		t.Fatalf("LineRange(0) = (%d,%d), want (0,1)", start, end)
+	}
+	if got := m.RowForLine(0); got != 0 {
+		t.Fatalf("RowForLine(0) = %d, want 0", got)
+	}
+	ws, we := m.ViewportWindow()
+	if ws != 0 || we != 1 {
+		t.Fatalf("ViewportWindow = [%d,%d), want [0,1)", ws, we)
+	}
+	if got := m.LineForRow(0); got != 0 {
+		t.Fatalf("LineForRow(0) = %d, want 0", got)
+	}
+}