raindown 0.5.1 → 0.6.0

data/lib/raindown/tui/navigator/commands.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative '../../actions'
+
+module Raindown
+  module TUI
+    # What a Navigator does to the open file: run an endpoint, open the editor, write back and read it again.
+    # Each sets the status, so the Screen shows how it went, and returns what the Screen should do next, if anything.
+    module Commands
+      def run(file, line, name) = Wait.new(message: "Running #{name}...", task: -> { run_endpoint(file, line) })
+
+      # Opens the editor at the file's line, and writes the file back after it closes.
+      def edit_at(file, line)
+        @edited = file
+        Run.new(command: Actions.edit_command(file, line:))
+      end
+
+      private
+
+      # Runs the endpoint selected in the outline, or listed below the files. One opened beside them runs itself.
+      def execute
+        target = selected&.target
+        return run(target.path, target.line, target.text) if target.is_a?(Endpoint)
+        return error('Select an endpoint to run') unless target.is_a?(Document::Directive) && target.endpoint?
+
+        run(path, target.line, "the endpoint on line #{target.line}")
+      end
+
+      def run_endpoint(file, line)
+        changed = @workers.for(file).call(:execute, file, line)
+        view.load
+        info(changed ? "Ran the endpoint on line #{line}" : 'The response is the same')
+      rescue StandardError => e
+        error(e.message)
+      end
+
+      # In the nav pane, the selected file opens at its top, and in the outline, the open file at the selected line.
+      def edit
+        row = selected
+        return error('Select a file to edit') if @focus == :nav && row&.kind != :file
+
+        return edit_at(row.target, 1) if @focus == :nav
+        return error('Open a file to edit') unless path
+
+        edit_at(path, row ? row.line : 1)
+      end
+
+      def write_back(file = path)
+        return error('Open a file to write back') unless file
+
+        changed = @workers.for(file).call(:write_back, file)
+        view.load
+        info(changed ? "Updated #{relative(file)}" : "#{relative(file)} is up to date")
+      rescue StandardError => e
+        error(e.message)
+      end
+
+      # The workers start again too, loading their projects' nodes again, like when one of them has changed.
+      def reload
+        @workers.restart
+        @files.load
+        @endpoints.load
+        view.load
+        info('Reloaded')
+      end
+
+      # Reads the file again when it's changed, like when it's saved in an editor or a watcher writes back to it.
+      def refresh
+        view.load if view.changed?
+        nil
+      end
+
+      def info(message)
+        @status = [:info, message]
+        nil
+      end
+
+      def error(message)
+        @status = [:error, message]
+        nil
+      end
+    end
+  end
+end

data/lib/raindown/tui/navigator/focus.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # How a Navigator's focus and cursor move: Tab or left and right between the files and the view,
+    # and up and down in the pane with the focus.
+    module Focus
+      private
+
+      def other_pane
+        @focus == :nav ? :main : :nav
+      end
+
+      def move(by)
+        content(@focus).move(by)
+        nil
+      end
+
+      def switch(pane)
+        @focus = pane
+        nil
+      end
+    end
+  end
+end

data/lib/raindown/tui/navigator/navigator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative '../file_tree'
+require_relative 'commands'
+require_relative '../endpoints'
+require_relative 'focus'
+require_relative '../events'
+require_relative '../views/outline_view'
+require_relative '../views/list_view'
+require_relative 'project_menu'
+require_relative 'views'
+require_relative '../workers/workers'
+
+module Raindown
+  module TUI
+    # What the terminal UI shows and does, in plain Ruby, with no terminal: a FileTree of the project's Markdown files,
+    # beside the open file's Outline, or the Dashboard of its charts. The Screen draws it and sends it events, keys like
+    # :down, or a Click, and next_step returns what the Screen does next: nil to draw again, :quit to stop, or a Run or Wait.
+    class Navigator
+      include Commands
+      include Views
+      include ProjectMenu
+      include Focus
+
+      # Keys of the events that move the cursor or the focus, and those that act on what's selected.
+      MOVES = { up: -1, down: 1 }.freeze
+      PANES = { tab: nil, left: :nav, right: :main }.freeze
+      ACTIONS = { execute: :execute, edit: :edit, write_back: :write_back, reload: :reload, tick: :refresh }.freeze
+
+      attr_reader :focus, :status
+
+      def initialize(root:, path: nil, workers: Workers.new(root:))
+        @workers = workers
+        @files = FileTree.new(root:, workers:)
+        @endpoints = Endpoints.new(workers:)
+        @dashboard = DashboardView.new(root:, workers:)
+        @nav = ListView.new { nav_rows }
+        first = Projects.files(root, nested: true).first
+        # The dashboard is the first page, unless a file is asked for, and "d" goes from it to the first file.
+        @view = OutlineView.new(first, workers:) if first
+        path ? open_at(path, nil) : open_view(dashboard)
+      end
+
+      # An event nothing has, like a mouse button's release, does nothing.
+      def next_step(event)
+        case event
+        when nil then nil
+        when Click then click(event)
+        else route(event)
+        end
+      end
+
+      # After the editor closes, the file is written back, like a save while it's watched, and read again.
+      def ran
+        write_back(@edited)
+        @endpoints.load
+      end
+
+      def root = @files.root
+      def relative(path) = @files.relative(path)
+
+      # The folder the files are shown from: the chosen project's, or the root's.
+      def base = @files.base
+
+      # What's in a pane: the nav's ListView on the left, or the view on the right, which keeps its own cursor.
+      def content(pane) = pane == :nav ? @nav : view
+
+      private
+
+      def route(name)
+        return :quit if name == :quit
+        return menu_event(name) if menu
+        return toggle_menu if name == :projects
+        return toggle_dashboard if name == :dashboard
+        return view.next_step(name)&.take(self) if @focus == :main && view.next_step?(name)
+
+        browser_event(name)
+      end
+
+      # A click moves the cursor where it's clicked, and does the click's action there, like a key, unless that would
+      # leave the terminal UI, like for the editor, so a stray click only moves the cursor.
+      # While the project menu's open, only its projects are clicked.
+      def click(click)
+        return if menu && click.pane != :menu
+
+        point(click)
+        effect = route(click.action)
+        effect unless effect.is_a?(Run)
+      end
+
+      def point(click)
+        return @menu = click.index if click.pane == :menu
+
+        content(click.pane).cursor = click.index
+        @focus = click.pane
+      end
+
+      def browser_event(name)
+        return move(MOVES[name]) if MOVES.key?(name)
+        return switch(PANES[name] || other_pane) if PANES.key?(name)
+        return activate(name) if %i[enter toggle].include?(name)
+
+        send(ACTIONS[name]) if ACTIONS.key?(name)
+      end
+
+      # The Dashboard, which every terminal draws two columns wide, then the files and the endpoints,
+      # with a blank line between each section that has rows.
+      def nav_rows
+        dashboard_row = Row.new(text: '📊 Dashboard', depth: 0, kind: :dashboard, target: dashboard, open: OpenView.new(view: dashboard))
+        [[dashboard_row], @files.rows, @endpoints.rows].reject(&:empty?).flat_map { [Row::SEPARATOR, *it] }.drop(1)
+      end
+
+      def selected
+        content(@focus).selected
+      end
+
+      # Enter opens what's selected, or folds it, and Space only folds.
+      def activate(name)
+        row = selected
+        return row.open.take(self) if name == :enter && row&.open
+
+        row&.fold&.call
+        nil
+      end
+    end
+  end
+end

data/lib/raindown/tui/navigator/project_menu.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # The list of projects that drops down from the header's path, with "p" or a click, when there's more than one.
+    # Choosing one narrows the files and the dashboard to its own, and "All projects" shows every project's again.
+    # It stays open until a project's chosen, with Enter or a click, while up and down move its cursor.
+    # Esc or "p" close it without choosing, and other keys and clicks do nothing while it's open.
+    module ProjectMenu
+      # The menu's cursor, while it's open.
+      attr_reader :menu
+
+      # The project the files and the dashboard are narrowed to, or nil for every project.
+      attr_reader :project
+
+      def projects = @workers.roots
+
+      # The menu's items: nil for all the projects, then each project's root.
+      def menu_items = [nil, *projects]
+
+      def projects? = projects.length > 1
+
+      private
+
+      def toggle_menu
+        return info("There's one project here") unless projects?
+
+        @menu = @menu ? nil : menu_items.index(project) || 0
+        nil
+      end
+
+      def menu_event(name)
+        case name
+        when :up, :down then move_menu(name == :up ? -1 : 1)
+        when :enter then choose(menu_items[@menu])
+        when :escape, :projects then close_menu
+        end
+      end
+
+      def move_menu(by)
+        @menu = (@menu + by).clamp(0, menu_items.length - 1)
+        nil
+      end
+
+      def close_menu
+        @menu = nil
+        nil
+      end
+
+      # Shows the project's dashboard, or every project's.
+      def choose(project)
+        @menu = nil
+        @project = project
+        @files.scope = project
+        @endpoints.project = project
+        dashboard.project = project
+        open_view(dashboard)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative '../views/dashboard_view'
+require_relative '../views/endpoint_view'
+require_relative '../views/outline_view'
+
+module Raindown
+  module TUI
+    # Beside the files, a Navigator shows a view: the open file's Outline, the Dashboard of the project's charts,
+    # which is the first item in the files and "d" switches to, or an EndpointView of an endpoint listed below them.
+    # A view has the pane that draws it, a next step for the keys it takes while it has the focus, and a target,
+    # what's opened it in the files. It loads when it's opened, and again after a change.
+    module Views
+      attr_reader :view, :dashboard
+
+      # The path of the file the view shows, if any.
+      def path = view.path
+
+      # Shows the view right of the files, with the focus, and the files' cursor on the row that opened it.
+      def open_view(view)
+        @previous = @view unless view == @view
+        @view = view
+        @focus = :main
+        @nav.cursor = @nav.rows.index { it.target == view.target } || 0
+        view.load
+        @status = view.status(self)
+        nil
+      end
+
+      # Opens the file in the outline, on the directive at the line.
+      def open_at(path, line)
+        path = File.expand_path(path)
+        @files.reveal(path)
+        open_view(OutlineView.new(path, workers: @workers))
+        view.cursor = view.rows.index { it.kind == :directive && it.target.line == line } || 0
+        nil
+      end
+
+      private
+
+      # Switches between the dashboard and the view before it.
+      def toggle_dashboard
+        return open_view(@previous) if view == dashboard && @previous
+
+        open_view(dashboard)
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/dashboard_renderer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'renderer'
+
+module Raindown
+  module TUI
+    # The dashboard, right of the files: a card for each of the projects' charts, as wide as its chart,
+    # with as many in a row as fit. With more than one project, each project's charts are under its path.
+    # A card has its file and heading, and its directive, both cut to the chart's width, then the chart,
+    # in a border with rounded corners:
+    #    ╭─────────────────────────────╮  ╭────────────────────────────────╮
+    #    │ raindown.rd › Charts        │  │ raindown.rd › Commits          │
+    #    │ chart: 'data/downloads.csv' │  │ chart: 'data/commits.csv' min… │
+    #    │ Jun  ██████▊           640  │  │ c2f98fc  -18  █│███▊      +96  │
+    #    ╰─────────────────────────────╯  ╰────────────────────────────────╯
+    class DashboardRenderer < Renderer
+      BUTTONS = [['Tab', 'Pane', :tab], ['Enter', 'Open', :enter], ['e', 'Edit', :edit], ['r', 'Reload', :reload],
+                 ['q', 'Quit', :quit]].freeze
+      PROJECTS_BUTTON = ['p', 'Projects', :projects].freeze
+
+      # Room for the project menu's button, when there's more than one project.
+      def buttons
+        if navigator.projects? then BUTTONS.dup.insert(3, PROJECTS_BUTTON)
+        else BUTTONS
+        end
+      end
+
+      def page = 'Dashboard'
+
+      def lines
+        cards = dashboard.cards
+        return blank(height, " No charts in #{File.basename(navigator.root)} yet, like <{ chart: '3 5 2 8' }>") if cards.empty?
+
+        rows = dashboard.rows(width)
+        @headings = headings(rows, cards)
+        grid(rows, cards)
+      end
+
+      private
+
+      def dashboard = navigator.dashboard
+
+      # Each project's path above its first row of cards, by the row's index, when there's more than one project.
+      def headings(rows, cards)
+        firsts = rows.each_index.chunk_while { |a, b| cards[rows[a].first].project == cards[rows[b].first].project }.map(&:first)
+        return {} if firsts.one?
+
+        firsts.to_h { [it, cards[rows[it].first].project] }
+      end
+
+      # The rows of cards from the first that's scrolled to, each card's lines side by side, with a line between rows.
+      def grid(rows, cards)
+        heights = rows.each_with_index.map { |row, index| row_height(row, cards) + (@headings.key?(index) ? 1 : 0) }
+        first = dashboard.scroll(heights, height)
+        lines = (first...rows.length).flat_map { |index| row_lines(rows[index], cards, heading: @headings[index]) }
+
+        (lines + blank(height)).first(height)
+      end
+
+      # The tallest card's lines, in its border, and one line below it.
+      def row_height(row, cards)
+        row.map { cards[it].box_height }.max + 1
+      end
+
+      def row_line(row, cards, line)
+        segments = [segment('', :blank, width: 1)]
+
+        row.each_with_index do |index, column|
+          segments << segment('', :blank, width: DashboardView::GAP) unless column.zero?
+          segments.concat(card_line(cards[index], index, line))
+        end
+
+        padded(segments)
+      end
+
+      # A card opens chart source when it's clicked, like Enter, but not the space below a card shorter than its row.
+      # The selected card's title is highlighted, like a selected row.
+      def card_line(card, index, line)
+        title_style = dashboard.cursor == index ? row_style(pane, nil, true) : :heading
+        event = Click.new(pane:, index:, action: :enter) if line < card.box_height
+        box_width = card.box_width(within: dashboard.card_widths(width))
+        card.format_line(line, box_width:, title_style:).map do |text, style, part_width|
+          segment(text, style, width: part_width, event:)
+        end
+      end
+
+      # A row of cards' lines, under its project's heading when it's the project's first row.
+      def row_lines(row, cards, heading:)
+        [*([heading_line(heading)] if heading), *Array.new(row_height(row, cards)) { |line| row_line(row, cards, line) }]
+      end
+
+      # A project's path from the home folder, above its charts.
+      def heading_line(project)
+        [segment(" #{from_home(project)}", :project)]
+      end
+
+      def blank(count, message = '')
+        [[segment(message, :info)], *Array.new([count - 1, 0].max) { [segment('', :blank)] }].first(count)
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/endpoint_renderer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'renderer'
+require_relative 'outline_renderer'
+
+module Raindown
+  module TUI
+    # An endpoint opened from the files, right of them: its URL in a bar with rounded corners, and a button to run it,
+    # then its response:
+    #    ╭──────────────────────────────────────────╮
+    #    │ GET https://httpbin.org/uuid     [ Run ] │
+    #    ╰──────────────────────────────────────────╯
+    #
+    #    Response · json · fetched 2026-10-26
+    #    {
+    #      "uuid": "48024974-f1b1-431a-a0cf-5cac0099a1a5"
+    #    }
+    class EndpointRenderer < Renderer
+      RUN = '[ Run ]'
+      RUN_WIDTH = RUN.length
+      BUTTONS = OutlineRenderer::BUTTONS.reject { it.last == :write_back }.freeze
+
+      def buttons = BUTTONS
+      def page = navigator.view.endpoint.text
+
+      def lines
+        view = navigator.view
+        top = [*url_bar(view.endpoint), [segment('', :blank, width:)], about(view)]
+
+        (top + response(view, height - top.length)).first(height)
+      end
+
+      private
+
+      # A click on the response moves the focus to it, to scroll it.
+      def focus = Click.new(pane:, index: 0, action: :focus)
+
+      def response(view, lines)
+        texts = view.visible([lines, 0].max)
+        Array.new([lines, 0].max) { [segment(texts[it] ? " #{texts[it]}" : '', :response, width:, event: focus)] }
+      end
+
+      # The bar is a column in from each side of the pane, with the URL and the button inside its border.
+      def url_bar(endpoint)
+        inner = [width - 6, 0].max
+        [edge('╭', '╮', inner), padded([margin, segment('│ ', :border, width: 2), *request(endpoint, inner)]),
+         edge('╰', '╯', inner)]
+      end
+
+      # The method in its colour, then the URL, cut to what the method and button leave, then the button,
+      # and the border's side.
+      def request(endpoint, inner)
+        method_width = display_width(endpoint.method)
+        url_width = [inner - method_width - RUN_WIDTH - 1, 0].max
+
+        [segment(endpoint.method, endpoint.style, width: method_width), segment(" #{endpoint.url} ", :url, width: url_width + 1),
+         run_button, segment(' │', :border, width: 2)]
+      end
+
+      def run_button = segment(RUN, :run, width: RUN_WIDTH, event: Click.new(pane:, index: 0, action: :execute))
+
+      def edge(left, right, inner)
+        padded([margin, segment("#{left}#{'─' * (inner + 2)}#{right}", :border, width: inner + 4)])
+      end
+
+      def margin = segment('', :blank, width: 1)
+
+      def about(view)
+        text = if view.error then view.error
+               elsif view.response.empty? then 'No response yet. X runs the request.'
+               else ['Response', view.language, ("fetched #{view.fetched}" if view.fetched)].reject { it.to_s.empty? }.join(' · ')
+               end
+        [segment(" #{text}", view.error ? :error : :heading, width:)]
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/list_renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative 'renderer'
+
+module Raindown
+  module TUI
+    # A ListView's rows in its pane, like the files in the nav or a file's outline, each with its buttons.
+    class ListRenderer < Renderer
+      def lines
+        list = navigator.content(pane).visible(height)
+        Array.new(height) { |index| cell(pane, *list, index, width) }
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/outline_renderer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'list_renderer'
+
+module Raindown
+  module TUI
+    # The open file's outline, right of the files: a row on each line, with its buttons.
+    class OutlineRenderer < ListRenderer
+      BUTTONS = [['Tab', 'Pane', :tab], ['Enter', 'Open', :enter], ['x', 'Run', :execute], ['e', 'Edit', :edit],
+                 ['w', 'Write back', :write_back], ['r', 'Reload', :reload], ['q', 'Quit', :quit]].freeze
+
+      def buttons = BUTTONS
+
+      def page
+        if navigator.path then navigator.relative(navigator.path)
+        else 'No Markdown files'
+        end
+      end
+    end
+  end
+end

data/lib/raindown/tui/renderers/renderer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../events'
+require_relative '../rows'
+require_relative '../text'
+
+module Raindown
+  module TUI
+    # Draws what's in a pane, :nav or :main, as lines of the pane's width and height, which the Layout puts in it.
+    Renderer = Struct.new(:navigator, :pane, :width, :height) do
+      include Rows
+      include Text
+    end
+  end
+end

data/lib/raindown/tui/row.rb

@@ -3,14 +3,21 @@
 module Raindown
   module TUI
     # A line of a pane. Target is what it's about: a folder or file path, a Heading or Directive, or a line number.
-    # Buttons are [label, event] pairs, like ['[Run]', :execute].
-    Row = Data.define(:text, :depth, :kind, :target, :buttons) do
-      def initialize(buttons: [], **) = super
+    # Buttons are [label, event] pairs, like ['[Run]', :execute], and a tag is an Endpoint, whose method is before its text.
+    # Open is the Navigator's next step on Enter, like an Open of a file, and fold, a block that folds or expands the row.
+    Row = Data.define(:text, :depth, :kind, :target, :buttons, :tag, :open, :fold) do
+      def initialize(buttons: [], tag: nil, open: nil, fold: nil, **) = super
+
+      # A separator is space between a pane's sections, which the cursor skips and clicks don't reach.
+      def selectable? = kind != :separator
 
       # The line the editor opens at for the row.
       def line
         target.is_a?(Integer) ? target : target.line
       end
     end
+
+    # Space between a pane's sections, like the Dashboard and the files.
+    Row::SEPARATOR = Row.new(text: '', depth: 0, kind: :separator, target: nil)
   end
 end

data/lib/raindown/tui/rows.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Raindown
+  module TUI
+    # A ListRenderer's rows, like the files and the outline, each a line of the pane's width: a row's text, after its tag,
+    # like an endpoint's method, then its buttons.
+    module Rows
+      private
+
+      # A row as its text, then its buttons, or blank below its last row.
+      def cell(pane, rows, offset, index, cell_width)
+        row = rows[index]
+        return [segment('', :blank, width: cell_width)] unless row&.selectable?
+
+        index += offset
+        selected = navigator.content(pane).cursor == index
+        buttons = row_buttons(row, pane:, index:, selected:, cell_width:)
+        text_width = cell_width - display_width(buttons.map(&:text).join)
+        parts = row_parts(row, row_style(pane, row, selected), selected)
+
+        [*spread_segments(parts, text_width, event: Click.new(pane:, index:, action: :enter)), *buttons]
+      end
+
+      # A line's segments, then blank to the edge.
+      def padded(segments) = [*segments, segment('', :blank, width: [width - segments.sum { display_width(it.text) }, 0].max)]
+
+      # [text, style] parts side by side in the width, each a segment.
+      def spread_segments(parts, width, event: nil)
+        parts.zip(spread(parts.map(&:first), width)).map { |(text, style), part| segment(text, style, width: part, event:) }
+      end
+
+      # The row's text, after its tag in the tag's style, unless the row's selected.
+      def row_parts(row, style, selected)
+        lead = " #{Text::INDENT * row.depth}"
+        return [["#{lead}#{row.text}", style]] unless row.tag
+
+        [["#{lead}#{row.tag.method} ", selected ? style : row.tag.style], [row.text, style]]
+      end
+
+      # The row's buttons, right of its text, unless they'd take more than half the pane.
+      def row_buttons(row, pane:, index:, selected:, cell_width:)
+        buttons = row.buttons.map do |label, event|
+          style = selected ? :"#{row_style(pane, row, true)}_button" : :button
+          segment(" #{label}", style, width: display_width(" #{label}"), event: Click.new(pane:, index:, action: event))
+        end
+        display_width(buttons.map(&:text).join) > cell_width / 2 ? [] : buttons
+      end
+
+      # The cursor's row is highlighted in the pane with the focus, and dimmer in the other, like the file a chart opened.
+      def row_style(pane, row, selected)
+        return row.kind unless selected
+
+        navigator.focus == pane ? :selected : :cursor
+      end
+    end
+  end
+end