r2ui 0.1.0 → 0.2.0

data/lib/r2ui/ext/file_picker.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# s31-file-picker: a file browser in a panel (bubbles' FilePicker).
+#
+#   R2UI.dashboard do
+#     row do
+#       panel :files, resource: nil do
+#         file_picker :browser, dir: ".", allowed: %w[.rb .md],
+#                               on_select: ->(path) { state[:open] = path; flash "picked #{path}" }
+#       end
+#     end
+#   end
+#
+# Hosts a `Bubbles::FilePicker` on `dir` (default "."), sized to the panel's height. While the
+# panel has focus the picker takes the keys: up/down (k/j), pgup/pgdown, home/end (g/G),
+# enter/right (l) to open a directory or select a file, left (h)/backspace to go back up.
+# `allowed` lists the selectable extensions, with or without the dot; empty (the default) allows
+# every file. `on_select` runs on a Context with the selected file's absolute path, once per
+# selection; a command it returns runs. `component(:browser)` is the picker itself.
+module R2UI
+  module Ext
+    module FilePicker
+      Item = Data.define(:name, :dir, :allowed, :on_select)
+
+      module_function
+
+      # The bubbles model for `item`. Each selection it makes is pushed onto `selections` as
+      # [item, path], for the after_update hook to hand to on_select.
+      def build(item, selections)
+        picker = Bubbles::FilePicker.new(directory: item.dir)
+        picker.allowed_types = item.allowed.map { |ext| ext.to_s.delete_prefix(".") }
+        picker.singleton_class.prepend(Module.new do
+          define_method(:update) do |message|
+            super(message).tap { selections << [item, path] if did_select_file? }
+          end
+        end)
+        picker
+      end
+
+      # Fits the listing under the picker's two header lines (path, blank).
+      def fit(picker, height)
+        rows = [height - 2, 1].max
+        return if picker.height == rows
+
+        picker.height = rows
+        picker.send(:update_offset) if picker.respond_to?(:update_offset, true)
+      end
+    end
+  end
+
+  extension :file_picker do
+    dsl :panel do
+      def file_picker(name, dir: ".", allowed: [], on_select: nil)
+        Component.require_bubbles!
+        item(Ext::FilePicker::Item.new(name: name.to_sym, dir: dir.to_s, allowed: Array(allowed), on_select:))
+      end
+    end
+
+    component(Ext::FilePicker::Item, focusable: true) do |item|
+      Ext::FilePicker.build(item, store(:file_picker)[:selections] ||= [])
+    end
+
+    after_update do
+      selections = store(:file_picker)[:selections]
+      while (item, path = selections&.shift)
+        call(item.on_select, path) if item.on_select
+      end
+    end
+
+    panel_item(Ext::FilePicker::Item) do |item|
+      instance = app.components.find { |c| c.item.equal?(item) && c.panel == panel }
+      next "" unless instance
+
+      Ext::FilePicker.fit(instance.model, height)
+      instance.model.view
+    end
+  end
+end

data/lib/r2ui/ext/focus_report.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# s16-focus-report: terminal focus in/out (Bubbletea's report_focus, FocusMessage, BlurMessage).
+#
+#   R2UI.dashboard do
+#     report_focus                          # ask the terminal to report focus changes
+#     on_blur  { state[:paused] = true }    # the terminal window lost focus
+#     on_focus { state[:paused] = false }   # ... and got it back
+#
+#     row do
+#       panel :status, resource: nil do
+#         view { state[:terminal_focused] ? "watching" : "paused" }
+#       end
+#     end
+#   end
+#
+# `state[:terminal_focused]` tracks the terminal's focus: true at start, false after a blur, true
+# again after a focus. `on_focus` / `on_blur` blocks run on the update thread (a Context) in the
+# order they were declared, after the state is updated; a command they return or enqueue runs.
+# Declaring `on_focus` or `on_blur` turns focus reporting on as well (without it they would never
+# fire). The runner turns reporting off again on exit.
+module R2UI
+  module Ext
+    module FocusReport
+      module_function
+
+      # Whether the dashboard uses focus reporting at all.
+      def enabled?(dashboard) = %i[report_focus on_focus on_blur].any? { |k| dashboard.declared(k).any? }
+    end
+  end
+
+  extension :focus_report do
+    dsl :dashboard do
+      def report_focus = declare(:report_focus, true)
+
+      def on_focus(&block)
+        raise ArgumentError, "on_focus needs a block" unless block
+
+        declare(:on_focus, block)
+      end
+
+      def on_blur(&block)
+        raise ArgumentError, "on_blur needs a block" unless block
+
+        declare(:on_blur, block)
+      end
+    end
+
+    setup do
+      state[:terminal_focused] = true if Ext::FocusReport.enabled?(dashboard) && !state.key?(:terminal_focused)
+    end
+
+    program_options { { report_focus: true } if Ext::FocusReport.enabled?(dashboard) }
+
+    observe(Bubbletea::FocusMessage) { state[:terminal_focused] = true if Ext::FocusReport.enabled?(dashboard) }
+    observe(Bubbletea::BlurMessage) { state[:terminal_focused] = false if Ext::FocusReport.enabled?(dashboard) }
+
+    # `call` enqueues each block's command; return nil so the declared blocks aren't taken as commands.
+    on Bubbletea::FocusMessage do
+      dashboard.declared(:on_focus).each { |block| call(block) }
+      nil
+    end
+
+    on Bubbletea::BlurMessage do
+      dashboard.declared(:on_blur).each { |block| call(block) }
+      nil
+    end
+  end
+end

data/lib/r2ui/ext/help.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# s28-help: a panel showing the app's keys with bubbles' Help.
+#
+#   R2UI.dashboard do
+#     on_key "r", help: "refresh" do refresh end
+#     row do panel :deploys do table end end
+#     row(height: 3) { panel(:keys, resource: nil) { help } }
+#   end
+#
+# `help` draws `Bubbles::Help` short help ("? help • r refresh • tab panel • … • q quit") from
+# `app.hint_pairs`: every extension's hints, then the core's. `?` toggles full help, which lays the
+# same hints out in columns as tall as the panel. Both are cut to the panel's width. While a help
+# panel is on the dashboard, `?` is bound (an ordinary binding, priority 0) and "? help" leads the
+# hints. Needs the bubbles gem.
+module R2UI
+  module Ext
+    module Help
+      # What `help` adds to the panel.
+      Item = Data.define
+
+      # The keymap Bubbles::Help reads: one binding per [key, label] hint pair.
+      Keymap = Data.define(:bindings, :column_height) do
+        def short_help = bindings
+        def full_help = bindings.each_slice(column_height).to_a
+      end
+
+      module_function
+
+      def present?(dashboard) = dashboard.panels.any? { |panel| panel.items.any?(Item) }
+
+      def keymap(pairs, column_height)
+        bindings = pairs.map { |key, label| Bubbles::Key.binding(keys: [key], help: [key, label]) }
+        Keymap.new(bindings:, column_height: [column_height, 1].max)
+      end
+    end
+  end
+
+  extension :help do
+    dsl :panel do
+      def help
+        Component.require_bubbles!
+        item(Ext::Help::Item.new)
+      end
+    end
+
+    hints { [["?", "help"]] if Ext::Help.present?(dashboard) }
+
+    on ->(msg) { msg.is_a?(Bubbletea::KeyMessage) && Keys.name(msg) == "?" } do
+      pass unless Ext::Help.present?(dashboard)
+
+      store(:help)[:full] = !store(:help)[:full]
+    end
+
+    panel_item Ext::Help::Item do
+      help = Bubbles::Help.new
+      help.width = width
+      help.show_all = store(:help)[:full] ? true : false
+      help.view(Ext::Help.keymap(app.hint_pairs(self), height))
+    end
+  end
+end

data/lib/r2ui/ext/keys.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# s03-keys: custom key bindings.
+#
+#   R2UI.dashboard do
+#     on_key "r", help: "refresh" do        # typed text, as the core names it
+#       state[:refreshed_at] = Time.now
+#       flash "refreshed"                   # any Context helper; a returned command runs too
+#     end
+#     on_key "ctrl+r", :f1, "enter" do      # Bubbletea names ("ctrl+r", "f1", "pgup") or core
+#       quit                                # names (:enter, :page_up), as String or Symbol
+#     end
+#   end
+#
+# The block runs on the update thread (a Context; `message` is the Bubbletea::KeyMessage). A
+# binding beats the core's own key (binding "s" stops the sort key), but not the search (/) or
+# confirm (y/n) prompts while they're open, nor a focused component. `help:` adds a status-bar
+# hint. Binding the same key twice in one dashboard raises.
+module R2UI
+  module Ext
+    # Not `Keys`: that would shadow R2UI::Keys for every other extension under R2UI::Ext.
+    module KeyBindings
+      # What `on_key` declares on the dashboard: `keys` are core key names (R2UI::Keys.name).
+      Binding = Data.define(:keys, :label, :help, :block)
+
+      module_function
+
+      # The core name of a key given as a core or Bubbletea name ("r", "ctrl+r", :f1, "enter").
+      def normalize(key) = R2UI::Keys.name(R2UI::Keys.message(key))
+    end
+  end
+
+  extension :keys do
+    dsl :dashboard do
+      def on_key(*keys, help: nil, &block)
+        raise ArgumentError, "on_key needs at least one key" if keys.empty?
+        raise ArgumentError, "on_key needs a block" unless block
+
+        names = keys.map { |key| Ext::KeyBindings.normalize(key) }
+        taken = @d.declared(:on_key).flat_map(&:keys)
+        names.each do |name|
+          raise ArgumentError, "on_key: #{name.inspect} is already bound" if taken.include?(name)
+
+          taken << name
+        end
+
+        label = keys.map(&:to_s).join("/")
+        declare(:on_key, Ext::KeyBindings::Binding.new(keys: names, label:, help:, block:))
+      end
+    end
+
+    hints do
+      dashboard.declared(:on_key).filter_map { |b| [b.label, b.help.to_s] if b.help }
+    end
+
+    on Bubbletea::KeyMessage do |key|
+      name = R2UI::Keys.name(key)
+      binding = dashboard.declared(:on_key).find { |b| b.keys.include?(name) }
+      pass unless binding
+
+      call(binding.block)
+    end
+  end
+end

data/lib/r2ui/ext/list.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# s22-list: a bubbles List in a panel (browse, filter with `/`, pick with enter).
+#
+#   R2UI.dashboard do
+#     row do
+#       panel :fruit, resource: nil do
+#         list :fruit, items: -> { state[:fruits] }, title: "Fruit",
+#                      on_select: ->(fruit) { flash "picked #{fruit}" }
+#       end
+#       panel :process do
+#         list :procs, resource: :process, label: :name, filter: true,
+#                      on_select: ->(row) { state[:pid] = row.pid }
+#       end
+#     end
+#   end
+#
+# Options:
+# - `items:` a lambda returning the items, re-read on every frame (it runs on a Context, so it can
+#   read `state`); or `resource:` a resource name, whose latest rows are the items (some panel
+#   must show that resource, so its feed runs). Give exactly one.
+# - `title:` the list's title line; without it the list shows no title (the panel has one).
+# - `filter:` (default true) whether `/` starts filtering; false turns filtering off.
+# - `label:` how an item reads: an attribute name (`:name`) or a lambda (`->(item) { ... }`).
+#   Without it, bubbles' own rule applies: `title`, then a Hash's `:title`, then `to_s`. Filtering
+#   matches the same text.
+# - `on_select:` called with the selected item (the original item or row, not its label) when
+#   enter is pressed; it runs on a Context, so it can touch `state`, `flash`, return commands.
+#
+# The list is a `Bubbles::List`, sized to the panel on every frame, and takes keys while its
+# panel has focus (tab and shift+tab still move focus): up/down/k/j, home/end/g/G, pgup/pgdown,
+# `/` to filter (enter applies, esc clears). Item changes keep the selection and the filter.
+# `component(:name)` gives the `Bubbles::List`.
+module R2UI
+  module Ext
+    module List
+      Item = Data.define(:name, :items, :resource, :title, :filter, :label, :on_select)
+
+      # What the list holds when `label:` is given: bubbles shows and filters by `title`.
+      Entry = Data.define(:item, :title)
+
+      module_function
+
+      def build(item)
+        Component.require_bubbles!
+        list = Bubbles::List.new([], width: 0, height: 1)
+        list.title = item.title.to_s
+        list.show_title = !item.title.nil?
+        list.show_filter = item.filter
+        list
+      end
+
+      # The current items: from the lambda or the resource's feed, mapped through `label:`.
+      def source(ctx, item)
+        raw = if item.resource
+                feed = ctx.app.feeds[item.resource]
+                raise Error, "list #{item.name}: no panel shows resource #{item.resource.inspect}" unless feed
+
+                feed.rows
+              else
+                ctx.call(item.items)
+              end
+        Array(raw)
+      end
+
+      def entries(ctx, item, raw)
+        case item.label
+        when nil then raw
+        when Symbol, String then raw.map { |r| Entry.new(item: r, title: Value.fetch(r, item.label.to_sym).to_s) }
+        else raw.map { |r| Entry.new(item: r, title: ctx.call(item.label, r).to_s) }
+        end
+      end
+
+      # Gives `list` new items, keeping its filter (state and text) and selection; bubbles'
+      # `items=` alone would clear both.
+      def replace(list, items)
+        filter_state = list.filter_state
+        query = list.filter_input.value
+        selected = list.selected_index
+
+        list.items = items
+        unless filter_state == Bubbles::List::UNFILTERED
+          list.start_filtering
+          list.filter_input.value = query
+          list.apply_filter
+          list.start_filtering if filter_state == Bubbles::List::FILTERING
+        end
+        list.select(selected)
+      end
+
+      def resize(list, width, height)
+        return if list.width == width && list.height == height
+
+        list.width = width
+        list.height = height
+        list.select(list.selected_index) # keeps the selection in view
+        list.update(Bubbletea::Message.new) # bubbles recounts its pages in update
+      end
+
+      def unwrap(entry) = entry.is_a?(Entry) ? entry.item : entry
+    end
+  end
+
+  extension :list do
+    dsl :panel do
+      def list(name, items: nil, resource: nil, title: nil, filter: true, label: nil, on_select: nil)
+        raise ArgumentError, "list #{name} needs `items:` or `resource:`, not both" unless items.nil? ^ resource.nil?
+        raise ArgumentError, "list #{name}: `items:` must be callable" if items && !items.respond_to?(:call)
+
+        item(Ext::List::Item.new(name:, items:, resource: resource&.to_sym, title:, filter:, label:, on_select:))
+      end
+    end
+
+    component(Ext::List::Item, focusable: true) { |item| Ext::List.build(item) }
+
+    panel_item(Ext::List::Item) do |item|
+      instance = app.components.find { |c| c.item.equal?(item) && c.panel == panel }
+      next "" unless instance
+
+      list = instance.model
+      raw = Ext::List.source(self, item)
+      shown = (store(:list)[:shown] ||= {}.compare_by_identity)
+      unless shown.key?(item) && shown[item] == raw
+        Ext::List.replace(list, Ext::List.entries(self, item, raw))
+        shown[item] = raw.dup # a copy: the lambda may hand back the same array, changed in place
+      end
+      Ext::List.resize(list, width, height)
+      list.view
+    end
+
+    # Enter picks the selected item, unless the list is typing a filter (then bubbles applies it).
+    on Bubbletea::KeyMessage, priority: 50 do |msg|
+      pass unless Keys.name(msg) == :enter
+
+      instance = app.components.find do |c|
+        c.focused && c.panel == app.focus && c.item.is_a?(Ext::List::Item)
+      end
+      pass unless instance
+      pass if instance.model.filter_state == Bubbles::List::FILTERING
+
+      selected = instance.model.selected_item
+      call(instance.item.on_select, Ext::List.unwrap(selected)) if selected && instance.item.on_select
+    end
+  end
+end

data/lib/r2ui/ext/messages.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# s04-messages: your own messages and events, like a Bubbletea model's `update` cases.
+#
+#   class Deployed < Bubbletea::Message
+#     attr_reader :name
+#     def initialize(name) = (super(); @name = name)
+#   end
+#
+#   R2UI.dashboard do
+#     on Deployed do |msg|                         # any Bubbletea::Message subclass
+#       state[:last] = msg.name
+#     end
+#     on :poll do |payload|                        # an event sent with `emit`
+#       state[:polls] = state[:polls].to_i + 1
+#       -> { Deployed.new(fetch_latest) }          # a Proc command runs in the background;
+#     end                                          # the message it returns reaches `on Deployed`
+#     every 5 do emit :poll end                    # emit(name, payload = nil, delay: 0)
+#   end
+#
+# `on(matcher) { |msg| }` handles every message `matcher === msg` (a class, a lambda, ...); a
+# Symbol handles the events `emit` sends with that name, and its block gets the payload. Handlers
+# run on a Context (state, flash, quit, command, ...), in the order they were declared; the first
+# that matches handles the message (call `pass` to let the next one see it), and a command it
+# returns or enqueues runs. They are ordinary bindings: a focused component and higher-priority
+# handlers see keys first, and messages nobody handles go on to the core.
+#
+# `emit(name, payload = nil, delay: 0)` (any block) enqueues `Bubbletea.send_message` with the
+# event, after `delay` seconds; it returns the command. Events nobody handles are ignored, and an
+# app ignores events another app emitted.
+module R2UI
+  module Ext
+    module Messages
+      # What `on` declares on the dashboard.
+      Handler = Data.define(:matcher, :block) do
+        def match?(message)
+          return message.name == matcher if matcher.is_a?(Symbol) && message.is_a?(Event)
+
+          matcher === message # rubocop:disable Style/CaseEquality
+        end
+
+        def argument(message) = matcher.is_a?(Symbol) ? message.payload : message
+      end
+
+      # The message `emit` sends. `app` scopes it to the app that emitted it.
+      class Event < Bubbletea::Message
+        attr_reader :name, :payload, :app
+
+        def initialize(name:, payload:, app:)
+          super()
+          @name = name
+          @payload = payload
+          @app = app
+        end
+      end
+    end
+  end
+
+  extension :messages do
+    dsl :dashboard do
+      def on(matcher, &block)
+        raise ArgumentError, "on needs a block" unless block
+
+        declare(:on, Ext::Messages::Handler.new(matcher:, block:))
+      end
+    end
+
+    helpers do
+      def emit(name, payload = nil, delay: 0)
+        raise ArgumentError, "emit needs an event name" unless name.is_a?(Symbol) || name.is_a?(String)
+
+        event = Ext::Messages::Event.new(name: name.to_sym, payload:, app:)
+        command(Bubbletea.send_message(event, delay:))
+      end
+    end
+
+    on Bubbletea::Message do |message|
+      own_event = message.is_a?(Ext::Messages::Event) && message.app.equal?(app)
+      pass if message.is_a?(Ext::Messages::Event) && !own_event
+
+      handled = dashboard.declared(:on).any? do |handler|
+        handler.match?(message) && handle(handler.block, handler.argument(message))
+      end
+      pass unless handled || own_event
+    end
+  end
+end

data/lib/r2ui/ext/mouse.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# s14-mouse: mouse reporting, clicks and the wheel.
+#
+#   R2UI.dashboard do
+#     mouse :cell                       # or :all (motion without a button held too); default :cell
+#     on_click do |msg, panel|          # a Bubbletea::MouseMessage, and the panel under it (or nil)
+#       flash "clicked #{panel&.name} at #{msg.x},#{msg.y}"
+#     end
+#     row { panel :process }
+#   end
+#
+# With `mouse`, the program turns on mouse reporting (Bubbletea's `mouse_cell_motion` or
+# `mouse_all_motion`) and turns it off again on exit. A left click focuses the panel under the
+# pointer and, on a table row, selects that row; the wheel moves the selection of the table under
+# the pointer (or of the focused one). `on_click` blocks run on a Context for every button press
+# (left, middle, right; not the wheel, releases or motion), after the click has focused and
+# selected, so `focus` and `selected_rows` already show the clicked row; a returned command runs.
+#
+# Buttons are Bubbletea 0.1.4's numbers, which pass the terminal's SGR button through: a left
+# click is 0, middle 1, right 2, wheel up 4 and wheel down 5.
+module R2UI
+  module Ext
+    module Mouse
+      MODES = { cell: :mouse_cell_motion, all: :mouse_all_motion }.freeze
+      LEFT = 0
+      WHEEL = { Bubbletea::MouseMessage::BUTTON_WHEEL_UP => -1, Bubbletea::MouseMessage::BUTTON_WHEEL_DOWN => 1 }.freeze
+
+      module_function
+
+      # The panel drawn at x, y in the last frame (nil if none).
+      def panel_at(app, x, y)
+        app.panel_rects.each do |panel, rect|
+          return panel if x >= rect.x && x < rect.x + rect.width && y >= rect.y && y < rect.bottom
+        end
+        nil
+      end
+
+      # Selects the table row drawn at screen row y in `panel`, if there is one there.
+      def select_row(app, panel, y)
+        state = app.panel_state(panel)
+        top = table_top(app, panel)
+        return unless state && top
+
+        index = state.offset + (y - top - 1) # the row under the table's header line
+        lines = app.panel_lines(panel)
+        state.move(index - state.selected, lines.size) if y > top && index < lines.size
+      end
+
+      # Moves the selection of a table panel by `delta` rows.
+      def scroll(app, panel, delta)
+        state = panel && app.panel_state(panel)
+        state&.move(delta, app.panel_lines(panel).size)
+      end
+
+      # The screen row of the table's header in `panel`, laid out as the renderer does: inside the
+      # border, below a feed error line and the items before the table.
+      def table_top(app, panel)
+        rect = app.panel_rects[panel]
+        return unless rect
+
+        inner = rect.width < 2 || rect.height < 2 ? rect : rect.inner
+        y = inner.y
+        y += 1 if panel.resource && app.feeds[panel.resource]&.error
+        panel.items.each do |item|
+          return y if item.is_a?(DSL::Table)
+
+          y += item_height(app, panel, item, inner.width, inner.bottom - y)
+          return if y >= inner.bottom
+        end
+        nil
+      end
+
+      def item_height(app, panel, item, width, room)
+        lines = case item
+                when DSL::Gauge then 1
+                when DSL::Stat then item.attrs.size
+                when DSL::Sparkline then item.height + 1
+                else extension_lines(app, panel, item, width, room)
+                end
+        lines.clamp(0, room)
+      end
+
+      def extension_lines(app, panel, item, width, height)
+        ctx = Context.new(app)
+        ctx.panel = panel
+        ctx.width = width
+        ctx.height = height
+        drawer = Extensions.hooks(:panel_item).find { |h| h.match?(item) }
+        text = drawer ? ctx.call(drawer.block, item) : app.components.find { |c| c.item.equal?(item) }&.model&.view
+        text.to_s.split("\n").size
+      end
+    end
+  end
+
+  extension :mouse do
+    dsl :dashboard do
+      def mouse(mode = :cell)
+        unless Ext::Mouse::MODES.key?(mode)
+          raise ArgumentError, "mouse takes #{Ext::Mouse::MODES.keys.map(&:inspect).join(" or ")}, got #{mode.inspect}"
+        end
+
+        declare(:mouse, mode)
+      end
+
+      def on_click(&block)
+        raise ArgumentError, "on_click needs a block" unless block
+
+        declare(:on_click, block)
+      end
+    end
+
+    program_options do
+      mode = dashboard.declared(:mouse).last
+      mode ? { Ext::Mouse::MODES.fetch(mode) => true } : {}
+    end
+
+    on Bubbletea::MouseMessage do |msg|
+      pass if dashboard.declared(:mouse).empty? || !msg.press?
+
+      panel = Ext::Mouse.panel_at(app, msg.x, msg.y)
+      if (delta = Ext::Mouse::WHEEL[msg.button])
+        Ext::Mouse.scroll(app, panel && app.panel_state(panel) ? panel : focus, delta)
+      else
+        if msg.button == Ext::Mouse::LEFT && panel
+          app.focus = panel
+          Ext::Mouse.select_row(app, panel, msg.y)
+        end
+        dashboard.declared(:on_click).each { |block| call(block, msg, panel) }
+      end
+      nil # the handler's own value would be enqueued as a command (the blocks are Procs)
+    end
+  end
+end