raindown 0.5.1 → 0.7.0

data/lib/raindown/tui/terminal/ncurses_shim.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'curses'
+
+module Raindown
+  module TUI
+    # ncurses before 6.1, like macOS's, repeats a character with the terminal's rep capability by writing one byte of it,
+    # so a run of █ in a bar chart draws as ?. Terminals with their own terminfo entries, like Ghostty's and kitty's,
+    # have rep, while the system's entries from those ncurses versions don't. So with old ncurses, a terminal whose
+    # entry isn't the system's starts curses as xterm-256color, which they draw the same, and TERM is put back after,
+    # for the commands run from the screen, like the editor.
+    module NcursesShim
+      FALLBACK = 'xterm-256color'
+      SYSTEM_TERMINFO = %w[/usr/share/terminfo /usr/lib/terminfo /lib/terminfo].freeze
+      FIXED_VERSION = [6, 1].freeze
+
+      module_function
+
+      def starting(version: Curses::VERSION)
+        term = ENV.fetch('TERM', nil)
+        ENV['TERM'] = FALLBACK if fallback?(term, version)
+        yield
+      ensure
+        ENV['TERM'] = term
+      end
+
+      def fallback?(term, version)
+        return false if term.nil? || term.empty? || term == FALLBACK
+
+        old?(version) && !system_entry?(term)
+      end
+
+      def old?(version)
+        numbers = version.to_s[/ncurses (\d+)\.(\d+)/, 0]&.scan(/\d+/)&.map(&:to_i)
+        numbers ? (numbers <=> FIXED_VERSION).negative? : false
+      end
+
+      # Entries are in a folder named by their first letter, or on macOS, its hex code, like 78/xterm-256color.
+      def system_entry?(term)
+        SYSTEM_TERMINFO.any? do |folder|
+          [term[0], term[0].ord.to_s(16)].any? { File.exist?(File.join(folder, it, term)) }
+        end
+      end
+    end
+  end
+end

data/lib/raindown/tui/terminal/quiet.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Raindown
+  module TUI
+    # Keeps text off the screen while it's up, since it would be written over it, and scroll it from the bottom line.
+    module Quiet
+      module_function
+
+      # What's written to stderr while the block runs, like a warning, is written once it's done.
+      def holding_stderr
+        stderr = $stderr
+        $stderr = StringIO.new
+        yield
+      ensure
+        held = $stderr.string
+        $stderr = stderr
+        $stderr.write(held) unless held.empty?
+      end
+
+      # Ruby's warnings are off while the block runs.
+      def quietly
+        verbose = $VERBOSE
+        $VERBOSE = nil
+        yield
+      ensure
+        $VERBOSE = verbose
+      end
+    end
+  end
+end

data/lib/raindown/tui/{screen.rb → terminal/screen.rb}

@@ -3,7 +3,9 @@
 require 'curses'
 
 require_relative 'input'
-require_relative 'layout'
+require_relative '../layout'
+require_relative 'quiet'
+require_relative 'ncurses_shim'
 require_relative 'styles'
 
 module Raindown
@@ -11,8 +13,9 @@ module Raindown
     # Paints a Navigator's Layout with curses, and sends the Navigator the events of keys and clicks, read with Input.
     # Only this class draws on the terminal, so another library could draw the same Layout.
     class Screen
-      # How often, in milliseconds, the open file is checked for changes while no key is pressed.
-      TICK = 500
+      # How often, in milliseconds, the open file is checked for changes while no key is pressed, or, while the view
+      # animates, like Code feelings' rain, it's drawn.
+      TICKS = { false => 500, true => 60 }.freeze
 
       def initialize(navigator)
         @navigator = navigator
@@ -20,14 +23,20 @@ module Raindown
       end
 
       def run
+        Quiet.holding_stderr { loop_screen }
+      end
+
+      private
+
+      def loop_screen
         start
 
         loop do
           draw
-          effect = @navigator.handle(read)
+          effect = @navigator.next_step(read)
           break if effect == :quit
 
-          perform(*effect) if effect.is_a?(Array)
+          perform(effect)
         end
       rescue Interrupt
         nil
@@ -35,35 +44,29 @@ module Raindown
         stop
       end
 
-      private
-
-      def perform(name, *args)
-        case name
-        when :run
-          suspend { system(*args.first) }
-          @navigator.ran
-        when :wait
-          message, task = args
-          show(message)
-          task.call
+      # Runs a command, like the editor, then tells the Navigator, or shows a message while a slow task runs.
+      def perform(effect)
+        case effect
+        in Run(command:) then suspend { system(*command) }.then { @navigator.ran }
+        in Wait(message:, task:) then show(message).then { task.call }
+        else nil
         end
       end
 
       def start
         ENV['ESCDELAY'] ||= '25'
-        Curses.init_screen
+        NcursesShim.starting { Curses.init_screen }
         @styles = Styles.start
         Curses.noecho
         Curses.cbreak
         Curses.nonl
         Curses.curs_set(0)
         Curses.stdscr.keypad(true)
-        Curses.stdscr.timeout = TICK
-        Curses.mousemask(Curses::BUTTON1_PRESSED | Curses::BUTTON1_CLICKED | Input.wheel.keys.sum)
-        Curses.mouseinterval(0)
+        Input.track_mouse
       end
 
       def stop
+        Input.untrack_mouse
         Curses.close_screen
       end
 
@@ -80,11 +83,21 @@ module Raindown
           segments.each { |segment| paint(window, segment) }
         end
 
+        repaint_title(lines.first, window)
         window.refresh
       end
 
+      # The title's rain cloud is one column to ncurses, and two in terminals like iTerm and kitty, which would put
+      # the rest of the title a column out when ncurses changes part of it. So when it changes, the screen is
+      # repainted, and the title is written in one go.
+      def repaint_title(title, window)
+        text = title&.map(&:text)&.join
+        window.redraw if @title && text != @title
+        @title = text
+      end
+
       def paint(window, segment)
-        window.attron(@styles.fetch(segment.style, Curses::A_NORMAL)) { window.addstr(segment.text) }
+        window.attron(@styles[segment.style]) { window.addstr(segment.text) }
       end
 
       def last_line(segments)
@@ -94,16 +107,18 @@ module Raindown
 
       # The next event, or :tick when no key is pressed in time, or nil for keys without one, like a resize.
       def read
+        Curses.stdscr.timeout = TICKS.fetch(@navigator.animating?)
         key = Curses.stdscr.getch
         return :tick if key.nil?
         return mouse if key == Curses::KEY_MOUSE
 
         Curses.stdscr.clear if key == Curses::KEY_RESIZE
-        Input.key_event(key)
+        Input.key_event(key, typing: @navigator.typing?)
       end
 
+      # The curses gem warns the first time it makes a MouseEvent, that it's "undefining the allocator" of the class.
       def mouse
-        event = Curses.getmouse
+        event = Quiet.quietly { Curses.getmouse }
         Input.mouse_event(event, @zones) if event
       end
 
@@ -116,13 +131,16 @@ module Raindown
         window.refresh
       end
 
-      # Leaves the screen to the command, like the editor, and comes back to it after.
+      # Leaves the screen to the command, like the editor, and comes back to it after. The command isn't sent the
+      # mouse's moves meanwhile.
       def suspend
         Curses.def_prog_mode
+        Input.untrack_mouse
         Curses.close_screen
         yield
       ensure
         Curses.reset_prog_mode
+        Input.track_mouse
         Curses.stdscr.clear
         Curses.refresh
       end

data/lib/raindown/tui/terminal/styles.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'curses'
+
+module Raindown
+  module TUI
+    # The curses attributes of a Layout's styles. Text is periwinkle where there are 256 colours, and the terminal's own
+    # colour otherwise, like the line between the panes, while the title and headings are cornflower blue. The selected
+    # row is white on blue, or on dark grey in the panes without the focus, while other colours are on the terminal's own
+    # background.
+    # With only 8 colours, there's no dark grey, so those rows are underlined, and without colours,
+    # the rest are in reverse.
+    module Styles
+      COLORS = { button: Curses::COLOR_YELLOW, error: Curses::COLOR_RED }.freeze
+      # Directives, like charts' on the Dashboard, in purple, and the folders, projects and pages in the files, the title,
+      # and headings, like the outline's and the Dashboard cards', in cornflower blue, from the 256 colours most terminals
+      # have, or magenta and blue with 8.
+      ACCENTS = { directive: 141, folder: 111, title: 111, heading: 111 }.freeze
+      BASIC_ACCENTS = { directive: Curses::COLOR_MAGENTA, folder: Curses::COLOR_BLUE, title: Curses::COLOR_BLUE,
+                        heading: Curses::COLOR_BLUE }.freeze
+      # The colours of endpoints' HTTP methods, like GET in green, from the 256 colours most terminals have,
+      # which are the same in every theme, unlike the 8 they all do, where green can look yellow.
+      METHODS = { get: 40, post: 33, delete: 196, put: 220, patch: 171, head: 44, options: 44 }.freeze
+      BASIC_METHODS = { get: Curses::COLOR_GREEN, post: Curses::COLOR_BLUE, delete: Curses::COLOR_RED,
+                        put: Curses::COLOR_YELLOW, patch: Curses::COLOR_MAGENTA, head: Curses::COLOR_CYAN,
+                        options: Curses::COLOR_CYAN }.freeze
+      # Highlighted code's colours, by the kind of token, from the 256 colours most terminals have, or the 8 they all do,
+      # where comments are dim instead of grey.
+      CODE = { code_keyword: 204, code_string: 114, code_number: 179, code_function: 75, code_constant: 117,
+               code_comment: 244 }.freeze
+      BASIC_CODE = { code_keyword: Curses::COLOR_MAGENTA, code_string: Curses::COLOR_GREEN, code_number: Curses::COLOR_YELLOW,
+                     code_function: Curses::COLOR_BLUE, code_constant: Curses::COLOR_CYAN, code_comment: Curses::COLOR_WHITE }.freeze
+      # Code feelings' bright colours, for its rain and fireworks, from the 256 colours most terminals have, or
+      # the 8 they all do.
+      BRIGHT = { bright_red: 203, bright_orange: 215, bright_yellow: 227, bright_green: 120, bright_cyan: 87,
+                 bright_blue: 75, bright_purple: 177, bright_pink: 213 }.freeze
+      BASIC_BRIGHT = { bright_red: Curses::COLOR_RED, bright_orange: Curses::COLOR_YELLOW, bright_yellow: Curses::COLOR_YELLOW,
+                       bright_green: Curses::COLOR_GREEN, bright_cyan: Curses::COLOR_CYAN, bright_blue: Curses::COLOR_BLUE,
+                       bright_purple: Curses::COLOR_MAGENTA, bright_pink: Curses::COLOR_MAGENTA }.freeze
+      # The selected row's blue, from the 256 colours most terminals have, or the 8 they all do.
+      BLUES = { selected: 33 }.freeze
+      BASIC_BLUES = { selected: Curses::COLOR_CYAN }.freeze
+      # Text that has no colour of its own, from the 256 colours most terminals have, or the terminal's own with 8.
+      PERIWINKLE = 147
+      # Code feelings' text and lines, the Dashboard cards' charts, and code blocks, in lavender, or magenta in 8 colours.
+      FEELINGS = { feelings: 183 }.freeze
+      BASIC_FEELINGS = { feelings: Curses::COLOR_MAGENTA }.freeze
+      BRIGHT_WHITE = 15
+      DARK_GREY = 238
+
+      module_function
+
+      # Sets up the colours, once the screen has started, and returns the attribute of each style.
+      def start
+        return plain unless Curses.has_colors?
+
+        start_colors
+        colored
+      end
+
+      # Without colours, a style that isn't here is the terminal's own.
+      def plain
+        Hash.new(Curses::A_NORMAL).merge(
+          title: Curses::A_REVERSE | Curses::A_BOLD, selected: Curses::A_REVERSE, selected_button: Curses::A_REVERSE,
+          cursor: Curses::A_UNDERLINE, cursor_button: Curses::A_UNDERLINE | Curses::A_BOLD, heading: Curses::A_BOLD,
+          body: Curses::A_DIM, error: Curses::A_BOLD, button: Curses::A_BOLD, folder: Curses::A_BOLD, project: Curses::A_BOLD, page: Curses::A_BOLD,
+          key: Curses::A_REVERSE, border: Curses::A_DIM, divider: Curses::A_BOLD,
+          selected_divider: Curses::A_REVERSE, cursor_divider: Curses::A_BOLD,
+          code_keyword: Curses::A_BOLD, code_comment: Curses::A_DIM
+        )
+      end
+
+      def colored
+        in_text_color.merge(
+          title: pair(:title) | Curses::A_BOLD, selected: pair(:selected) | white_bold,
+          selected_button: pair(:selected_button) | Curses::A_BOLD, directive: pair(:directive),
+          error: pair(:error) | Curses::A_BOLD, button: pair(:button) | Curses::A_BOLD, **emphasis,
+          **dividers, **code_tokens, **bright, **files, **unfocused
+        )
+      end
+
+      # The styles without a colour of their own, or that are only bold, dim or the like, in the text's colour, which is
+      # also any style that isn't here.
+      def in_text_color
+        text = pair(:text)
+        Hash.new(text).merge(plain.transform_values { it | text })
+      end
+
+      # Headings, and Code feelings' text and lines, whose lavender the Dashboard cards' charts and code
+      # blocks are too, apart from highlighted code's keywords, strings and the like.
+      def emphasis
+        lavender = pair(:feelings)
+        { heading: pair(:heading) | Curses::A_BOLD, feelings: lavender, chart: lavender, code: lavender }
+      end
+
+      # Highlighted code's tokens, like keywords and comments, with comments dim in 8 colours, where there's no grey.
+      def code_tokens
+        tokens = CODE.keys.to_h { [it, pair(it)] }
+        tokens[:code_comment] |= Curses::A_DIM if Curses.colors < 256
+        tokens
+      end
+
+      # The bright colours, bold, so they're bright in 8 colours too.
+      def bright = BRIGHT.keys.to_h { [it, pair(it) | Curses::A_BOLD] }
+
+      # The line between the panes, and where it meets a selected row.
+      def dividers = { divider: pair(:divider), selected_divider: pair(:selected_divider) }
+
+      def files
+        { folder: pair(:folder) | Curses::A_BOLD, project: pair(:folder) | Curses::A_BOLD,
+          page: pair(:folder) | Curses::A_BOLD, **METHODS.keys.to_h { [:"method_#{it}", pair(:"method_#{it}") | Curses::A_BOLD] } }
+      end
+
+      # The selected rows of the panes without the focus, on dark grey where there's one.
+      def unfocused
+        return { cursor_button: pair(:button) | Curses::A_BOLD, cursor_divider: pair(:divider) } unless Curses.colors >= 256
+
+        { cursor: pair(:cursor), cursor_button: pair(:cursor_button) | Curses::A_BOLD, cursor_divider: pair(:cursor_divider) }
+      end
+
+      # Each colour pair as [name, foreground, background], where -1 is the terminal's own background.
+      def pairs
+        many = Curses.colors >= 256
+        blues = many ? BLUES : BASIC_BLUES
+        white = many ? BRIGHT_WHITE : Curses::COLOR_WHITE
+        text = many ? PERIWINKLE : -1
+
+        [*COLORS.map { |name, color| [name, color, -1] },
+         *(many ? METHODS : BASIC_METHODS).map { |name, color| [:"method_#{name}", color, -1] },
+         *(many ? CODE.merge(BRIGHT, FEELINGS, ACCENTS) : BASIC_CODE.merge(BASIC_BRIGHT, BASIC_FEELINGS, BASIC_ACCENTS))
+           .map { |name, color| [name, color, -1] },
+         [:text, text, -1],
+         [:selected, white, blues[:selected]], [:selected_button, Curses::COLOR_YELLOW, blues[:selected]],
+         [:cursor, white, DARK_GREY], [:cursor_button, Curses::COLOR_YELLOW, DARK_GREY], [:divider, text, -1],
+         [:selected_divider, text, blues[:selected]], [:cursor_divider, text, DARK_GREY]]
+      end
+
+      def pair(name)
+        Curses.color_pair(pairs.index { it.first == name } + 1)
+      end
+
+      # The 8 colour white is grey, which bold brightens.
+      def white_bold
+        Curses.colors >= 256 ? Curses::A_NORMAL : Curses::A_BOLD
+      end
+
+      def start_colors
+        Curses.start_color
+        Curses.use_default_colors
+        pairs.each.with_index(1) { |(_name, foreground, background), index| Curses.init_pair(index, foreground, background) }
+      end
+    end
+  end
+end

data/lib/raindown/tui/text.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+
+module Raindown
+  module TUI
+    # Text measured in a terminal's columns, where a wide character like 界 takes two, cut to fit them in styled Segments.
+    module Text
+      Segment = Data.define(:text, :style, :event)
+      INDENT = '  '
+
+      private
+
+      # A path from the home folder when it's in it, like ~/dev/raindown.
+      def from_home(path)
+        home = Dir.home
+        path == home || path.start_with?(File.join(home, '')) ? path.sub(home, '~') : path
+      rescue ArgumentError
+        path
+      end
+
+      # The text fit to the width, as a Segment in the style.
+      def segment(text, style, width: self.width, event: nil)
+        Segment.new(text: fit(printable(text), width), style:, event:)
+      end
+
+      # Text cut or padded to the width, with a cut shown by an ellipsis.
+      def fit(text, width)
+        return '' if width <= 0
+        return text + (' ' * (width - display_width(text))) if display_width(text) <= width
+
+        cut = +''
+        cut_width = 0
+        text.each_char do |char|
+          break if cut_width + display_width(char) > width - 1
+
+          cut << char
+          cut_width += display_width(char)
+        end
+        "#{cut}…#{' ' * (width - 1 - cut_width)}"
+      end
+
+      # The widths of texts side by side in a width: each as wide as it is, and the last as wide as what's left,
+      # with none past the width.
+      def spread(texts, width)
+        texts.each_with_index.map do |text, index|
+          part = index == texts.length - 1 ? width : [display_width(text), width].min
+          width -= part
+          part
+        end
+      end
+
+      # A line of highlighted code's [text, style] parts as segments, cut or padded to the width.
+      def code_segments(parts, width, event: nil)
+        segments = segments_between(parts.map { |text, style| Segment.new(text: printable(text), style:, event:) }, 0, width)
+        [*segments, segment('', :code, width: width - segments.sum { display_width(it.text) }, event:)]
+      end
+
+      # The text in lines that fit the width, broken at spaces where it can, and inside a word too long for a line.
+      def wrap(text, width)
+        return [text] unless width.positive?
+
+        text.scan(/\S+|\s+/).each_with_object([+'']) do |part, lines|
+          next lines.last << part if display_width(lines.last + part) <= width
+          next lines << +'' if part.strip.empty?
+
+          lines << +'' unless lines.last.empty?
+          break_word(part, width, lines)
+        end
+      end
+
+      # Adds a word too long for a line to the lines, a character at a time, starting a new line when one's full.
+      def break_word(word, width, lines)
+        word.each_char do |char|
+          lines << +'' if display_width(lines.last + char) > width
+          lines.last << char
+        end
+      end
+
+      # The line's segments, with others drawn over its columns from the column on, like a box over the screen.
+      def overlay_segments(line, segments, column:)
+        width = segments.sum { display_width(it.text) }
+        [*segments_between(line, 0, column), *segments, *segments_between(line, column + width, Float::INFINITY)]
+      end
+
+      # The parts of the line's segments between two columns, where a wide character cut in two leaves spaces.
+      def segments_between(line, from, to)
+        column = 0
+        line.filter_map do |segment|
+          text = segment.text.each_char.map do |char|
+            start = column
+            column += display_width(char)
+            overlap = [column, to].min - [start, from].max
+            overlap == display_width(char) ? char : ' ' * [overlap, 0].max
+          end.join
+          segment.with(text:) unless text.empty?
+        end
+      end
+
+      # Tabs and control characters, like in a directive's output, would move the terminal's cursor.
+      def printable(text)
+        text.gsub("\t", INDENT).gsub(/[[:cntrl:]]/, '')
+      end
+
+      def display_width(text)
+        Unicode::DisplayWidth.of(text)
+      end
+    end
+  end
+end

data/lib/raindown/tui/title.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # A Layout's title line: Raindown's name, the folder the files are shown from, and the page.
+    module Title
+      # The rain cloud without the emoji variation selector, like the nav's projects, which terminals draw one column wide,
+      # as it's measured, so the title line reaches the edge.
+      NAME = '🌧  Raindown'
+
+      private
+
+      # The name, the folder, which opens the project menu when there's more than one project, and the page.
+      def title
+        parts = [[name, nil], ["#{location}#{' ▾' if navigator.projects?}", (:projects if navigator.projects?)],
+                 [" › #{view_renderer.page}", nil]]
+
+        parts.zip(spread(parts.map(&:first), width)).map do |(text, event), part_width|
+          segment(text, :title, width: part_width, event:)
+        end
+      end
+
+      def name = " #{NAME}  "
+
+      # The folder the files are shown from.
+      def location = from_home(navigator.base)
+    end
+  end
+end

data/lib/raindown/tui/views/dashboard_view.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative '../events'
+
+module Raindown
+  module TUI
+    # Every chart in the projects' Markdown files, drawn from its data by its project's Worker, as cards in a grid
+    # with a cursor. A chart is a chart: directive, or a project's own node that's a Raindown::Chart, like
+    # "Sales < Raindown::Chart", or a Raindown::Stat, one big number, like "CodeDebt < Raindown::Stat". Charts are drawn
+    # again every few seconds, so they follow changes to their data, like a CSV file, without a save.
+    # A key's next step, for the Navigator, is nil, or an Open or Edit of a chart's directive.
+    class DashboardView
+      # Seconds between drawing the charts again.
+      REDRAW = 2
+      MOVES = %i[up down left right].freeze
+      # Columns between the cards, and the narrowest a card is, with its border.
+      GAP = 2
+      MIN_CARD_WIDTH = 28
+
+      attr_reader :root, :errors, :cursor, :project
+
+      def initialize(root:, workers:)
+        @root = root
+        @workers = workers
+        @cursor = 0
+        @offset = 0
+        @rows = []
+      end
+
+      def renderer = DashboardRenderer
+      def target = self
+      def path = nil
+      def changed? = false
+      def typing? = false
+      def animating? = false
+
+      def status(_navigator)
+        found = "#{charts.length} #{charts.length == 1 ? 'chart' : 'charts'} in #{File.basename(project || root)}"
+        errors.empty? ? [:info, found] : [:error, "#{found}, but couldn't read #{errors.join(', ')}"]
+      end
+
+      # Finds the charts again, like when it's opened, or a file is saved or added.
+      def load
+        draw(find: true)
+        @cursor = @cursor.clamp(0, [charts.length - 1, 0].max)
+      end
+
+      # The charts, as each project's Worker drew them, of the project they're narrowed to, if any.
+      def charts
+        project ? @cards.filter { it.project == project } : @cards
+      end
+
+      # Narrows the charts to a project's, or with nil, shows every project's.
+      def project=(project)
+        @project = project
+        @cursor = 0
+        @offset = 0
+      end
+
+      def cards
+        draw if Process.clock_gettime(Process::CLOCK_MONOTONIC) - @drawn_at >= REDRAW
+        charts
+      end
+
+      # The charts' indexes in rows, as many of a project's as fit across the width after a column of margin, with each
+      # project's charts starting a row. They're kept, so up and down move a row.
+      def rows(width)
+        @rows = charts.each_index.chunk_while { |a, b| charts[a].project == charts[b].project }.flat_map { group_rows(it, width) }
+      end
+
+      # The widths a card can be: no narrower than MIN_CARD_WIDTH, when there's room, and no wider than the width.
+      def card_widths(width) = [MIN_CARD_WIDTH, width - 1].min..(width - 1)
+
+      def selected = charts[@cursor]
+
+      def first_in_row?
+        @rows.empty? || @rows.any? { it.first == @cursor }
+      end
+
+      # Every key but Tab to the files, or left from the first card in a row.
+      def next_step?(key) = !%i[tab tick].include?(key) && !(key == :left && first_in_row?)
+
+      def next_step(key)
+        chart = selected
+        case key
+        when *MOVES then move(key).then { nil }
+        when :enter then chart && Open.new(path: chart.path, line: chart.line)
+        when :edit then chart && Edit.new(path: chart.path, line: chart.line)
+        when :reload then load.then { nil }
+        end
+      end
+
+      def cursor=(index)
+        @cursor = index.clamp(0, [charts.length - 1, 0].max)
+      end
+
+      # The first row of cards to show, given each row's height, scrolled so the cursor's row is shown.
+      def scroll(row_heights, height)
+        row = row_of(@cursor)
+        @offset = row if row < @offset
+        @offset += 1 while @offset < row && row_heights[@offset..row].sum > height
+        @offset = @offset.clamp(0, [row_heights.length - 1, 0].max)
+      end
+
+      private
+
+      def draw(find: false)
+        @cards = []
+        @errors = []
+        @workers.each do |worker|
+          answer = worker.call(:charts, find:)
+          @cards.concat(answer[:cards])
+          @errors.concat(answer[:errors])
+        rescue Worker::Error => e
+          @errors << "#{File.basename(worker.root)}: #{e.message}"
+        end
+        @cards.sort_by! { [it.project, it.path, it.line] }
+        @drawn_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def group_rows(indexes, width)
+        indexes.each_with_object([[]]) do |index, rows|
+          rows << [] if rows.last.any? && row_width(rows.last + [index], width) > width
+          rows.last << index
+        end
+      end
+
+      # A row of cards' width, after a column of margin, with a gap between each.
+      def row_width(row, width)
+        1 + row.sum { charts[it].box_width(within: card_widths(width)) } + (GAP * (row.length - 1))
+      end
+
+      # Left and right move along the cards, and up and down to the card in the same place in the row above or below.
+      def move(name)
+        return self.cursor = @cursor + (name == :left ? -1 : 1) if %i[left right].include?(name)
+
+        row = row_of(@cursor)
+        target = @rows[(row + (name == :up ? -1 : 1)).clamp(0, [@rows.length - 1, 0].max)]
+        self.cursor = target ? target[[@rows[row].index(@cursor), target.length - 1].min] : @cursor
+      end
+
+      def row_of(index)
+        @rows.index { it.include?(index) } || 0
+      end
+    end
+  end
+end