r2ui 0.1.0 → 0.2.0

data/lib/r2ui/dsl/dashboard.rb

@@ -5,17 +5,27 @@ module R2UI
     Gauge = Data.define(:attr, :of, :label)
     Stat = Data.define(:attrs)
     Sparkline = Data.define(:attr, :label, :height)
-    Table = Data.define(:scope, :group_by, :sort, :limit)
+    # `motion`: marks moved/new lines in a left gutter and keeps the selection on its line across
+    # re-sorts (needs the app's Motion). `columns`: an Array of column keys to draw, in that order
+    # (nil: all of the resource's index columns).
+    Table = Data.define(:scope, :group_by, :sort, :limit, :motion, :columns) do
+      def initialize(scope: nil, group_by: nil, sort: nil, limit: nil, motion: false, columns: nil)
+        super(scope:, group_by:, sort:, limit:, motion:, columns: columns && Array(columns).map(&:to_sym).freeze)
+      end
+    end
 
-    Panel = Data.define(:name, :resource, :span, :title, :items) do
+    # `resource` is nil for a panel that shows only extension items (a text input, a spinner, ...).
+    # `options` holds keyword options the core doesn't know, for extensions to read.
+    Panel = Data.define(:name, :resource, :span, :title, :items, :options) do
       def table = items.find { |i| i.is_a?(Table) }
     end
 
     Row = Data.define(:height, :panels)
 
     # A screen made of rows of panels. Each panel shows one resource.
+    # Extensions record their own declarations (timers, key bindings, ...) under `declarations`.
     class Dashboard
-      attr_reader :name, :title, :rows
+      attr_reader :name, :title, :rows, :declarations
 
       def self.build(name, &block)
         dashboard = new(name)
@@ -32,21 +42,34 @@ module R2UI
         @name = name.to_sym
         @title = name.to_s.tr("_", " ").capitalize
         @rows = []
+        @declarations = Hash.new { |h, k| h[k] = [] }
       end
 
       def panels = rows.flat_map(&:panels)
 
+      # Everything an extension declared under `key`, in order ([] if none).
+      def declared(key) = declarations.fetch(key, [])
+
       class Builder
         def initialize(dashboard) = @d = dashboard
 
         def title(text) = @d.instance_variable_set(:@title, text)
 
-        # `height:` in terminal lines; rows without one share the remaining space.
+        # `height:` in terminal lines (or a callable returning them, evaluated each frame); rows
+        # without one share the remaining space.
         def row(height: nil, &block)
           builder = RowBuilder.new
           builder.instance_eval(&block)
           @d.rows << Row.new(height:, panels: builder.panels)
         end
+
+        private
+
+        # For extension keywords: record `value` under `key` on the dashboard. Returns `value`.
+        def declare(key, value)
+          @d.declarations[key] << value
+          value
+        end
       end
 
       class RowBuilder
@@ -55,10 +78,15 @@ module R2UI
         def initialize = @panels = []
 
         # `span:` is a relative width; panels in a row split it by their spans.
-        def panel(name, resource: name, span: 1, title: nil, &block)
+        # `resource: nil` makes a panel with no data source (extension items only).
+        def panel(name, resource: name, span: 1, title: nil, **options, &block)
           items = PanelBuilder.new.tap { |b| b.instance_eval(&block) if block }.items
-          items = [Table.new(scope: nil, group_by: nil, sort: nil, limit: nil)] if items.empty?
-          @panels << Panel.new(name:, resource:, span:, title:, items:)
+          if items.empty?
+            raise Error, "panel #{name} has no resource and nothing to show" unless resource
+
+            items = [Table.new(scope: nil, group_by: nil, sort: nil, limit: nil)]
+          end
+          @panels << Panel.new(name:, resource:, span:, title:, items:, options:)
         end
       end
 
@@ -73,8 +101,16 @@ module R2UI
 
         def sparkline(attr, label: nil, height: 3) = @items << Sparkline.new(attr:, label:, height:)
 
-        def table(scope: nil, group_by: nil, sort: nil, limit: nil)
-          @items << Table.new(scope:, group_by:, sort:, limit:)
+        def table(scope: nil, group_by: nil, sort: nil, limit: nil, motion: false, columns: nil)
+          @items << Table.new(scope:, group_by:, sort:, limit:, motion:, columns:)
+        end
+
+        private
+
+        # For extension keywords: add an item (any object) to the panel. Returns it.
+        def item(value)
+          @items << value
+          value
         end
       end
     end

data/lib/r2ui/dsl/resource.rb

@@ -33,8 +33,14 @@ module R2UI
         @columns = []
         @searchable = []
         @actions = []
+        @declarations = Hash.new { |h, k| h[k] = [] }
       end
 
+      # What extensions declared on this resource, by key.
+      attr_reader :declarations
+
+      def declared(key) = declarations.fetch(key, [])
+
       def column(key) = columns.find { |c| c.key == key }
 
       def default_scope = scopes.find(&:default) || scopes.first
@@ -99,6 +105,12 @@ module R2UI
 
         private
 
+        # For extension keywords: record `value` under `key` on the resource. Returns `value`.
+        def declare(key, value)
+          @r.declarations[key] << value
+          value
+        end
+
         def set(ivar, value) = @r.instance_variable_set(:"@#{ivar}", value)
 
         def humanize(sym) = sym.to_s.tr("_", " ").capitalize

data/lib/r2ui/ext/after.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# s06-after: a one-shot delay (a single Bubbletea tick).
+#
+#   R2UI.dashboard do
+#     every 60 do
+#       state[:banner] = "syncing…"
+#       after 3 do                    # seconds, or anything with #to_f
+#         state[:banner] = nil        # runs once, 3 s later, on the update thread
+#         flash "synced"              # any Context helper; a returned command runs too
+#       end
+#     end
+#   end
+#
+# `after` is a helper, so it works from any block: a key binding, a timer, an `on` handler, a
+# component callback. Each call schedules its own one-shot; a later `after` never cancels an
+# earlier one. It returns the Bubbletea command (already enqueued). The delay may be 0 (run on the
+# next update); a negative delay or a missing block raises.
+module R2UI
+  module Ext
+    module After
+      # The message a one-shot delivers. `app` scopes it to the app that scheduled it.
+      class Fire < Bubbletea::Message
+        attr_reader :block, :app
+
+        def initialize(block:, app:)
+          super()
+          @block = block
+          @app = app
+        end
+      end
+    end
+  end
+
+  extension :after do
+    helpers do
+      def after(seconds, &block)
+        raise ArgumentError, "after needs a block" unless block
+
+        seconds = seconds.to_f
+        raise ArgumentError, "after needs a non-negative delay, got #{seconds}" if seconds.negative?
+
+        target = app
+        command(Bubbletea.tick(seconds) { Ext::After::Fire.new(block:, app: target) })
+      end
+    end
+
+    on Ext::After::Fire do |fire|
+      pass unless fire.app.equal?(app)
+
+      call(fire.block)
+    end
+  end
+end

data/lib/r2ui/ext/async.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# s08-async: background work (a Bubbletea Proc command, with its result routed back).
+#
+#   R2UI.dashboard do
+#     every 30 do
+#       async(-> { Net::HTTP.get(URI("https://example.com/status")) }) do |body, error|
+#         if error
+#           flash "status failed: #{error.message}"
+#         else
+#           state[:status] = body     # any Context helper; a returned command runs too
+#         end
+#       end
+#     end
+#   end
+#
+# `async(callable) { |value, error| }` is a helper, usable from any block (a timer, a key
+# binding, a handler). The callable runs off the update thread, so the UI keeps drawing and taking
+# keys meanwhile; it must not touch app state. When it finishes, the block runs on the update
+# thread with its return value and nil, or with nil and the exception if it raised (StandardError).
+# Returns the command (already enqueued). Results that arrive after the app has quit are dropped.
+module R2UI
+  module Ext
+    module Async
+      # The message a finished callable delivers. `app` scopes it to the app that started it.
+      class Done < Bubbletea::Message
+        attr_reader :app, :block, :value, :error
+
+        def initialize(app:, block:, value:, error:)
+          super()
+          @app = app
+          @block = block
+          @value = value
+          @error = error
+        end
+      end
+
+      module_function
+
+      # The Proc command the runner calls on its own thread; it returns the Done message.
+      def command(app, callable, block)
+        proc do
+          Done.new(app:, block:, value: callable.call, error: nil)
+        rescue StandardError => e
+          Done.new(app:, block:, value: nil, error: e)
+        end
+      end
+
+      # True if `command` quits the program (alone, or inside a batch or sequence).
+      def quits?(command)
+        case command
+        when Bubbletea::QuitCommand then true
+        when Bubbletea::BatchCommand, Bubbletea::SequenceCommand then command.commands.any? { |c| quits?(c) }
+        else false
+        end
+      end
+    end
+  end
+
+  extension :async do
+    helpers do
+      def async(callable, &block)
+        raise ArgumentError, "async needs a callable, got #{callable.inspect}" unless callable.respond_to?(:call)
+        raise ArgumentError, "async needs a block" unless block
+
+        command(Ext::Async.command(app, callable, block))
+      end
+    end
+
+    # Remember that this app quit, so late results are dropped.
+    after_update do
+      store(:async)[:quit] = true if Ext::Async.quits?(commands)
+    end
+
+    on Ext::Async::Done do |done|
+      pass unless done.app.equal?(app)
+
+      call(done.block, done.value, done.error) unless store(:async)[:quit]
+    end
+  end
+end

data/lib/r2ui/ext/batch_sequence.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# s07-batch-sequence: command composition (Bubbletea.batch / Bubbletea.sequence, as blocks).
+#
+#   R2UI.dashboard do
+#     on_key "d", help: "deploy" do
+#       sequence do                        # in order; stops at quit
+#         flash "deploying"
+#         command(-> { Deploy.run })       # any command a helper enqueues, or the block returns
+#         batch do                         # concurrently
+#           command(-> { Slack.notify })
+#           command(-> { Metrics.bump })
+#         end
+#       end
+#     end
+#   end
+#
+# `batch { }` groups every command enqueued inside the block (by `command`, `quit`, any command
+# helper, or the block's return value) into one Bubbletea.batch; `sequence { }` into one
+# Bubbletea.sequence. The grouped commands don't also run on their own. Blocks nest. Each returns
+# the grouped command (already enqueued), or nil if the block enqueued nothing.
+module R2UI
+  module Ext
+    module BatchSequence
+      module_function
+
+      # Runs `block` on `context` with an empty command list, then enqueues what it collected as
+      # one command built by `combine` (Bubbletea.batch or Bubbletea.sequence).
+      def group(context, combine, block)
+        raise ArgumentError, "#{combine} needs a block" unless block
+
+        collected = context.instance_variable_get(:@commands)
+        context.instance_variable_set(:@commands, [])
+        begin
+          context.call(block)
+          inner = context.instance_variable_get(:@commands)
+        ensure
+          context.instance_variable_set(:@commands, collected)
+        end
+        return nil if inner.empty?
+
+        context.command(Bubbletea.public_send(combine, *inner))
+      end
+    end
+  end
+
+  extension :batch_sequence do
+    helpers do
+      def batch(&block) = Ext::BatchSequence.group(self, :batch, block)
+
+      def sequence(&block) = Ext::BatchSequence.group(self, :sequence, block)
+    end
+  end
+end

data/lib/r2ui/ext/countdown.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# s29-timer: a countdown in a panel (a hosted Bubbles::Timer).
+#
+#   R2UI.dashboard do
+#     row height: 3 do
+#       panel :clock, resource: nil do
+#         countdown :deadline, 90, on_timeout: -> { flash "time's up" }   # seconds, or anything with #to_f
+#       end
+#     end
+#   end
+#
+# The timer starts when the app starts, ticks once a second and shows the time left ("1m30s",
+# "5s", "0s"). When it ends, `on_timeout` runs once on the update thread (a Context: state, flash,
+# quit, ...); a command it returns runs too. `component(:deadline)` is the Bubbles::Timer, so a
+# block can `command(component(:deadline).stop)` / `.start` / `.toggle` it.
+#
+# Needs the bubbles gem (optional for apps).
+module R2UI
+  module Ext
+    module Countdown
+      # What `countdown` adds to the panel.
+      Item = Data.define(:name, :seconds, :on_timeout)
+
+      # Matches a Bubbles::Timer::TimeoutMessage without naming Bubbles at load time.
+      TIMEOUT = ->(msg) { defined?(::Bubbles::Timer::TimeoutMessage) && msg.is_a?(::Bubbles::Timer::TimeoutMessage) }
+    end
+  end
+
+  extension :countdown do
+    dsl :panel do
+      def countdown(name, seconds, on_timeout: nil)
+        seconds = seconds.to_f
+        raise ArgumentError, "countdown needs a positive duration, got #{seconds}" unless seconds.positive?
+
+        Component.require_bubbles!
+        item(Ext::Countdown::Item.new(name:, seconds:, on_timeout:))
+      end
+    end
+
+    component(Ext::Countdown::Item) { |item| Bubbles::Timer.new(item.seconds) }
+
+    observe Ext::Countdown::TIMEOUT do |msg|
+      instance = app.components.find { |c| c.item.is_a?(Ext::Countdown::Item) && c.model.id == msg.id }
+      fired = (store(:countdown)[:fired] ||= {})
+      if instance && !fired[msg.id]
+        fired[msg.id] = true
+        call(instance.item.on_timeout) if instance.item.on_timeout
+      end
+    end
+  end
+end

data/lib/r2ui/ext/data_table.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# s23-data-table: a bubbles Table in a panel.
+#
+#   R2UI.dashboard do
+#     row height: 12 do
+#       panel :services, resource: nil do
+#         data_table :services,
+#                    columns: [["Name", 20], ["Count", 5]],      # [title, width], ...
+#                    rows: -> { state[:services] || [] },        # Array of Arrays, read every frame
+#                    on_select: ->(row) { flash "picked #{row.first}" }
+#       end
+#     end
+#   end
+#
+# The panel hosts a `Bubbles::Table` (`component(:services)` returns it). Its height follows the
+# panel, and `rows` (run on a Context) is re-read on every frame. While the panel has focus the
+# table takes its keys (up/down, j/k, pgup/pgdown, home/end, as bubbles defines them); enter calls
+# `on_select` with the row under the cursor. Needs the bubbles gem.
+module R2UI
+  module Ext
+    module DataTable
+      Item = Data.define(:name, :columns, :rows, :on_select)
+
+      # Rows for the header and the separator under it.
+      CHROME = 2
+
+      module_function
+
+      def enter?(message) = message.is_a?(Bubbletea::KeyMessage) && Keys.name(message) == :enter
+
+      def columns(item) = item.columns.map { |title, width| { title: title.to_s, width: Integer(width) } }
+    end
+  end
+
+  extension :data_table do
+    dsl :panel do
+      def data_table(name = nil, columns: nil, rows: nil, on_select: nil)
+        raise ArgumentError, "data_table needs a name" unless name
+        raise ArgumentError, "data_table needs columns: [[title, width], ...]" if columns.nil? || columns.empty?
+        raise ArgumentError, "data_table needs rows: -> { [...] }" unless rows.respond_to?(:call)
+
+        R2UI::Component.require_bubbles!
+        item(Ext::DataTable::Item.new(name: name.to_sym, columns:, rows:, on_select:))
+      end
+    end
+
+    component(Ext::DataTable::Item, focusable: true) do |item|
+      Bubbles::Table.new(columns: Ext::DataTable.columns(item), rows: Array(call(item.rows)))
+    end
+
+    panel_item(Ext::DataTable::Item) do |item|
+      table = component(item.name)
+      table.height = [height - Ext::DataTable::CHROME, 1].max
+      table.rows = Array(call(item.rows))
+      table.view
+    end
+
+    # Enter on a focused table selects its row; runs before the table itself (which ignores enter).
+    on(->(message) { Ext::DataTable.enter?(message) }, priority: 50) do
+      item = focus&.items&.find { |i| i.is_a?(Ext::DataTable::Item) }
+      table = item && component(item.name)
+      pass unless table&.focused? && item.on_select
+
+      row = table.selected_row_data
+      pass unless row
+
+      call(item.on_select, row)
+    end
+  end
+end

data/lib/r2ui/ext/every.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# s01-every: repeating timers (Bubbletea's tick loop, declared).
+#
+#   R2UI.dashboard do
+#     every 5 do                      # seconds, or anything with #to_f (5.seconds)
+#       state[:checked_at] = Time.now
+#       flash "checked"               # any Context helper; a returned command runs too
+#     end
+#   end
+#
+# Each timer starts when the app starts and fires every `seconds` until it quits. The block runs
+# on the update thread (a Context), so it may touch app state freely.
+#
+# This is the reference extension: a story copies its shape (a DSL keyword that `declare`s plain
+# data, an `init` hook that starts things, an `on` handler for its own message) and its test
+# (test/ext/every_test.rb).
+module R2UI
+  module Ext
+    module Every
+      # What `every` declares on the dashboard.
+      Timer = Data.define(:seconds, :block)
+
+      # The message a timer's tick delivers. `app` scopes it to the app that scheduled it.
+      # Messages subclass Bubbletea::Message: the runner only delivers those from background commands.
+      class Tick < Bubbletea::Message
+        attr_reader :timer, :app
+
+        def initialize(timer:, app:)
+          super()
+          @timer = timer
+          @app = app
+        end
+      end
+
+      module_function
+
+      # The command that delivers `timer`'s next Tick to `app`.
+      def schedule(app, timer) = Bubbletea.tick(timer.seconds) { Tick.new(timer:, app:) }
+    end
+  end
+
+  extension :every do
+    dsl :dashboard do
+      def every(seconds, &block)
+        raise ArgumentError, "every needs a block" unless block
+
+        seconds = seconds.to_f
+        raise ArgumentError, "every needs a positive interval, got #{seconds}" unless seconds.positive?
+
+        declare(:every, Ext::Every::Timer.new(seconds:, block:))
+      end
+    end
+
+    init do
+      dashboard.declared(:every).each { |timer| command(Ext::Every.schedule(app, timer)) }
+    end
+
+    on Ext::Every::Tick do |tick|
+      pass unless tick.app.equal?(app)
+
+      call(tick.timer.block)
+      command(Ext::Every.schedule(app, tick.timer))
+    end
+  end
+end

data/lib/r2ui/ext/exec.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# s09-exec: run an external program in the foreground (Bubble Tea's ExecProcess).
+#
+#   R2UI.dashboard do
+#     on_key "ctrl+e" do
+#       execute(ENV.fetch("EDITOR", "vi"), "notes.md") { |status| flash "editor: #{status.exitstatus}" }
+#     end
+#   end
+#
+# `execute(*argv) { |status| }` enqueues a Bubbletea::ExecCommand and returns it. When the runner
+# runs it, the terminal is released (mouse off, cursor shown, cooked mode; the alt screen is left if
+# the app is in it), the program runs with the app's stdin/stdout/stderr and the app waits for it.
+# Then the terminal is taken back (alt screen entered again, the whole frame redrawn) and the block
+# runs on the update thread (a Context) with the program's Process::Status. A program that can't be
+# started gives a status with exit code 127, like a shell.
+#
+# The compat runner (upstream bubbletea 0.1.4, copied unchanged) only toggles raw mode, cursor and
+# mouse around an ExecCommand; it neither leaves the alt screen nor repaints. Go's Bubble Tea does
+# both (ReleaseTerminal / RestoreTerminal), so this extension finds the runner driving the app and
+# does them on its Program, which keeps the terminal's mode flags right for the cleanup at exit.
+module R2UI
+  module Ext
+    module Exec
+      # The message the runner delivers once the program has exited.
+      class Done < Bubbletea::Message
+        attr_reader :app, :block, :status
+
+        def initialize(app:, block:)
+          super()
+          @app = app
+          @block = block
+          @status = nil
+        end
+
+        def finish(status) = @status = status
+      end
+
+      module_function
+
+      # The ExecCommand that runs `argv` for `app`, then delivers a Done for `block`.
+      def command(app, argv, block)
+        done = Done.new(app:, block:)
+        Bubbletea.exec(-> { done.finish(run(app, argv)) }, message: done)
+      end
+
+      # Runs `argv` in the foreground with the terminal released; returns its Process::Status.
+      def run(app, argv)
+        terminal = Terminal.find(app)
+        terminal&.release
+        system(*argv)
+        $?
+      ensure
+        terminal&.restore
+      end
+
+      # The runner's Program and renderer for one app, for leaving and re-entering the alt screen.
+      class Terminal
+        def self.find(app)
+          runner = ObjectSpace.each_object(Bubbletea::Runner).find do |r|
+            r.instance_variable_get(:@model).equal?(app)
+          end
+          runner && new(runner)
+        end
+
+        def initialize(runner)
+          @runner = runner
+          @program = runner.instance_variable_get(:@program)
+          @renderer_id = runner.instance_variable_get(:@renderer_id)
+        end
+
+        def release
+          @alt_screen = @runner.instance_variable_get(:@in_alt_screen)
+          @program.exit_alt_screen if @alt_screen
+        end
+
+        # Re-enters the alt screen (which clears it) and makes the next frame draw in full.
+        def restore
+          @program.enter_alt_screen if @alt_screen
+          repaint
+        end
+
+        private
+
+        # Go's repaint + resetLinesRendered: forget the last frame so the next one is drawn whole,
+        # below the program's output when inline.
+        def repaint
+          renderer = @renderer_id && defined?(R2UI::Compat::Tea) && R2UI::Compat::Tea.renderer(@renderer_id)
+          return unless renderer
+
+          renderer.instance_variable_get(:@mutex).synchronize do
+            renderer.instance_variable_set(:@last_render, "".b)
+            renderer.instance_variable_set(:@last_lines, [])
+            renderer.instance_variable_set(:@lines_rendered, 0)
+          end
+        end
+      end
+    end
+  end
+
+  extension :exec do
+    helpers do
+      def execute(*argv, &block)
+        raise ArgumentError, "execute needs a program" if argv.empty?
+
+        command(Ext::Exec.command(app, argv.map(&:to_s), block))
+      end
+    end
+
+    on Ext::Exec::Done do |done|
+      pass unless done.app.equal?(app)
+
+      call(done.block, done.status) if done.block
+    end
+  end
+end