r2ui 0.1.0 → 0.2.0

data/lib/r2ui/extension.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module R2UI
+  # One capability in one file. An extension registers everything it needs without editing shared
+  # files: DSL keywords on the builders, helpers for handler blocks, Bubbletea init/update hooks,
+  # panel item drawers, status-bar hints and program options. Files in lib/r2ui/ext/ load
+  # automatically. See docs/dsl.md and lib/r2ui/ext/every.rb (the reference extension).
+  #
+  #   R2UI.extension :every do
+  #     dsl(:dashboard) { def every(seconds, &block) = declare(:every, ...) }
+  #     init { dashboard.declared(:every).each { |t| command(tick_for(t)) } }
+  #     on(Tick) { |tick| ... }
+  #   end
+  #
+  # Every hook block runs on a Context (instance_exec), so it can call the core helpers
+  # (state, flash, quit, command, pass, ...) and any extension's `helpers`.
+  class Extension
+    # The builder classes `dsl` can add keywords to.
+    TARGETS = {
+      dashboard: -> { DSL::Dashboard::Builder },
+      row: -> { DSL::Dashboard::RowBuilder },
+      panel: -> { DSL::Dashboard::PanelBuilder },
+      resource: -> { DSL::Resource::Builder }
+    }.freeze
+
+    Hook = Data.define(:extension, :matcher, :priority, :order, :block) do
+      def match?(message) = matcher.nil? || matcher === message # rubocop:disable Style/CaseEquality
+    end
+
+    attr_reader :name, :modules, :hooks
+
+    def initialize(name)
+      @name = name.to_sym
+      @modules = [] # [target class, module] pairs, for remove
+      @hooks = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Adds the methods defined in the block as keywords on a DSL builder (:dashboard, :row,
+    # :panel, :resource). Inside them, `declare(key, value)` records on the dashboard/resource
+    # and `item(value)` adds a panel item. A keyword that already exists is an error.
+    def dsl(target, &body)
+      builder = TARGETS.fetch(target) { raise Error, "unknown DSL target #{target.inspect}" }.call
+      add_module(builder, Module.new(&body))
+    end
+
+    # Methods available inside every hook and every user block (a Context).
+    def helpers(&body) = add_module(Context, Module.new(&body))
+
+    # Runs in App.new, before any frame (snapshots included): seed state here. Commands are ignored.
+    def setup(&block) = hook(:setup, nil, block)
+
+    # Runs once in App#init. Enqueue startup commands with `command(...)` (or return one).
+    def init(&block) = hook(:init, nil, block)
+
+    # Runs after init and after every update, on the same Context (its commands go out with that
+    # update's): e.g. re-send the window title when the value it shows has changed.
+    def after_update(&block) = hook(:after_update, nil, block)
+
+    # Handles messages matching `matcher` (anything with ===: a class, a proc, a regexp...).
+    # A matching handler consumes the message unless it calls `pass`. Higher priority runs first:
+    # 100 = an open modal capturing keys, 50 and up = before the focused component (which comes
+    # next), 0 = ordinary bindings, -100 = fallbacks. Core keys (tab, q, the table keys) run after
+    # every handler; ctrl+c and the core search/confirm prompts run before them. See docs/dsl.md.
+    def on(matcher, priority: 0, &block) = hook(:on, matcher, block, priority:)
+
+    # Sees every matching message before any `on` handler; never consumes it.
+    def observe(matcher = nil, &block) = hook(:observe, matcher, block)
+
+    # Draws panel items of class `klass`. The block gets the item and returns a String (ANSI
+    # allowed, lines split on "\n"); `width`, `height` and `panel` give the space it has. The panel
+    # gives it as many lines as the string has (at most `height`).
+    def panel_item(klass, &block) = hook(:panel_item, klass, block)
+
+    # Hosts a Bubbletea-style model for each panel item of class `klass`; the block builds it from
+    # the item. See R2UI::Component for what the app does with it. `focusable: true` routes keys
+    # to it while its panel has focus.
+    def component(klass, focusable: false, &build)
+      raise ArgumentError, "component needs a build block" unless build
+
+      hook(:component, klass, Component::Spec.new(matcher: klass, options: { focusable: }, build:))
+    end
+
+    # Extra status-bar hints: return [[key, label], ...] or nil.
+    def hints(&block) = hook(:hints, nil, block)
+
+    # Text for the left of the status bar when the core shows nothing (no prompt or flash).
+    def status(&block) = hook(:status, nil, block)
+
+    # Options for Bubbletea::Runner (alt_screen:, mouse_cell_motion:, bracketed_paste:, ...).
+    # Return a Hash; later extensions win on the same key.
+    def program_options(&block) = hook(:program_options, nil, block)
+
+    # Replaces the whole view (no panels, no status bar) when it returns a String; nil leaves the
+    # dashboard. `width` and `height` are the frame size. The first non-nil one wins.
+    def view_override(&block) = hook(:view_override, nil, block)
+
+    # Changes the size the app draws at: gets [width, height], returns [width, height].
+    def frame_size(&block) = hook(:frame_size, nil, block)
+
+    # Canvas styles: return { style_name => "SGR params" } to add or override (see Canvas::STYLES).
+    def styles(&block) = hook(:styles, nil, block)
+
+    # Empties its modules (they stay included, with no methods) and drops its hooks.
+    def remove!
+      @modules.each do |_target, mod|
+        (mod.instance_methods(false) + mod.private_instance_methods(false)).each do |m|
+          mod.send(:remove_method, m)
+        end
+      end
+      @hooks.clear
+      Extensions.changed!
+    end
+
+    private
+
+    def hook(kind, matcher, block, priority: 0)
+      raise ArgumentError, "#{kind} needs a block" unless block
+
+      @hooks[kind] << Hook.new(extension: name, matcher:, priority:, order: Extensions.next_order, block:)
+      Extensions.changed!
+      @hooks[kind]
+    end
+
+    def add_module(target, mod)
+      defined = mod.instance_methods(false) + mod.private_instance_methods(false)
+      taken = defined.select do |m|
+        target.method_defined?(m) || target.private_method_defined?(m)
+      end
+      raise Error, "extension #{name}: #{target} already has #{taken.join(", ")}" if taken.any?
+
+      target.include(mod)
+      @modules << [target, mod]
+      mod
+    end
+  end
+
+  # The loaded extensions, in load order.
+  module Extensions
+    @all = {}
+    @order = 0
+    @lock = Mutex.new
+    @sorted = {} # kind => frozen sorted hooks; replaced (not cleared) on any change
+
+    class << self
+      def register(name, &block)
+        name = name.to_sym
+        raise Error, "extension #{name} is already registered" if @all.key?(name)
+
+        extension = Extension.new(name)
+        @all[name] = extension
+        changed!
+        begin
+          extension.instance_eval(&block) if block
+        rescue StandardError
+          remove(name)
+          raise
+        end
+        extension
+      end
+
+      def [](name) = @all[name.to_sym]
+
+      def names = @all.keys
+
+      # Unregisters an extension and removes its keywords and helpers (for tests).
+      def remove(name)
+        removed = @all.delete(name.to_sym)
+        changed!
+        removed&.remove!
+      end
+
+      # Hooks of one kind across all extensions: highest priority first, then load order. Cached
+      # until an extension or hook is added or removed; the list is frozen (callers only read it).
+      def hooks(kind)
+        sorted = @sorted
+        sorted[kind] || (sorted[kind] = sort_hooks(kind))
+      end
+
+      # Drops the cached hook lists (an extension or hook was added or removed). A list being
+      # built concurrently lands in the dropped cache, never in the new one.
+      def changed! = @sorted = {}
+
+      def next_order = @lock.synchronize { @order += 1 }
+
+      # Loads every file in `dir` (default lib/r2ui/ext/), sorted by name.
+      def load_all(dir = File.expand_path("ext", __dir__))
+        Dir[File.join(dir, "*.rb")].sort.each { |file| require file }
+      end
+
+      private
+
+      def sort_hooks(kind)
+        @all.values.flat_map { |e| e.hooks.fetch(kind, []) }.sort_by { |h| [-h.priority, h.order] }.freeze
+      end
+    end
+  end
+
+  def self.extension(name, &) = Extensions.register(name, &)
+end

data/lib/r2ui/history.rb

@@ -16,8 +16,11 @@ module R2UI
 
     def [](id, key) = @series.fetch([id, key], [])
 
-    # Sum several series aligned at their newest value (for grouped lines).
+    # Sum several series aligned at their newest value (for grouped lines). For one id this is that
+    # series itself (not a copy): callers read it and must not change it.
     def sum(ids, key)
+      return self[ids.first, key] if ids.size == 1
+
       lists = ids.map { |id| self[id, key] }.reject(&:empty?)
       return [] if lists.empty?
 

data/lib/r2ui/keys.rb

@@ -1,18 +1,45 @@
 # frozen_string_literal: true
 
 module R2UI
-  # Splits raw terminal input into key names (:up, :tab, "q", ...).
+  # Converts between Bubbletea key messages and the key names r2ui's core uses:
+  # typed text as a String ("q", "K", " ", or a whole paste), named keys as Symbols
+  # (:up, :page_down, :enter, :escape, :interrupt, :back_tab, ...); keys the core has no name for
+  # keep their Bubbletea name as a Symbol (:"ctrl+r", :f1, :delete, :"alt+x").
   module Keys
-    SEQUENCES = {
-      "\e[A" => :up, "\e[B" => :down, "\e[C" => :right, "\e[D" => :left,
-      "\e[5~" => :page_up, "\e[6~" => :page_down, "\e[H" => :home, "\e[F" => :end,
-      "\e[Z" => :back_tab, "\t" => :tab, "\r" => :enter, "\n" => :enter,
-      "\x7F" => :backspace, "\b" => :backspace, "\x03" => :interrupt, "\e" => :escape
+    # Bubbletea name => core name, where they differ.
+    NAMES = {
+      "pgup" => :page_up, "pgdown" => :page_down, "shift+tab" => :back_tab, "esc" => :escape,
+      "ctrl+c" => :interrupt, "ctrl+h" => :backspace, "ctrl+j" => :enter, "space" => " "
     }.freeze
-    PATTERN = Regexp.union(*SEQUENCES.keys.sort_by { -_1.length }, /./m)
+    # Core name => Bubbletea name, for building messages (App#press).
+    BUBBLETEA = NAMES.reject { |k, _| %w[ctrl+h ctrl+j].include?(k) }.to_h { |k, v| [v, k] }.freeze
 
     module_function
 
-    def parse(input) = input.scan(PATTERN).map { |k| SEQUENCES.fetch(k, k) }
+    # The core name for a Bubbletea::KeyMessage.
+    def name(message)
+      return message.char if message.runes? && !message.alt
+
+      key = message.to_s
+      NAMES.fetch(key) { key.to_sym }
+    end
+
+    # A Bubbletea::KeyMessage for a core name (:up, "q", " ") or a Bubbletea name ("ctrl+r", "f1").
+    def message(key)
+      return key if key.is_a?(Bubbletea::KeyMessage)
+
+      name = BUBBLETEA.fetch(key, key.to_s)
+      alt = name.start_with?("alt+") && name.length > 4
+      base = alt ? name.delete_prefix("alt+") : name
+      type = key_type(base)
+      return Bubbletea::KeyMessage.new(key_type: type, runes: base == "space" ? [32] : [], alt:) if type
+
+      Bubbletea::KeyMessage.new(key_type: Bubbletea::KeyMessage::KEY_RUNES, runes: base.codepoints, alt:)
+    end
+
+    def key_type(name)
+      @types ||= R2UI::Compat::Tea::Input::KEY_NAMES.to_h { |type, n| [n, type] }.except("runes")
+      @types[name]
+    end
   end
 end

data/lib/r2ui/motion.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module R2UI
+  # Time-based animation state for one app: tweens (a number glides to its new value), pulses (a
+  # flash that fades after an event) and ages (how long a value has been what it is). Everything is
+  # keyed by whatever the caller passes (a pid, [:row, id], ...), evaluated while drawing a frame.
+  #
+  # `active?` tells the app whether anything was still moving at the last evaluation, so it keeps
+  # drawing frames only while something animates.
+  class Motion
+    EASES = {
+      linear: ->(t) { t },
+      out_cubic: ->(t) { 1 - ((1 - t)**3) },
+      in_out_sine: ->(t) { -(Math.cos(Math::PI * t) - 1) / 2 },
+      out_back: lambda do |t|
+        c1 = 1.70158
+        1 + ((c1 + 1) * ((t - 1)**3)) + (c1 * ((t - 1)**2))
+      end
+    }.freeze
+
+    # How long `active?` may stay true after the last evaluation if nothing evaluates again (e.g. the
+    # animated thing stopped being drawn).
+    GRACE = 1.0
+
+    attr_accessor :enabled, :clock
+
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @clock = clock
+      @enabled = true
+      @tweens = {} # key => [from, to, start, duration, ease]
+      @pulses = {} # key => [fired, start, duration]
+      @ages = {}   # key => [value, since]
+      @seen = {}   # key => last evaluated at
+      @busy_until = nil
+      @evaluated_at = nil
+    end
+
+    def self.lerp(a, b, t) = a + ((b - a) * t)
+
+    # "#rrggbb" between two "#rrggbb" colours (t in 0..1, plain RGB lerp).
+    def self.mix_hex(from_hex, to_hex, t)
+      t = t.to_f.clamp(0.0, 1.0)
+      ar, ag, ab = rgb(from_hex)
+      br, bg, bb = rgb(to_hex)
+      format("#%02x%02x%02x", lerp(ar, br, t).round.clamp(0, 255), lerp(ag, bg, t).round.clamp(0, 255),
+             lerp(ab, bb, t).round.clamp(0, 255))
+    end
+
+    RGB_CACHE_LIMIT = 4096
+    @rgb_cache = {}
+
+    # [r, g, b] (frozen) for "#rrggbb" or "#rgb". Memoized (bounded).
+    def self.rgb(hex)
+      cached = @rgb_cache[hex]
+      return cached if cached
+
+      @rgb_cache.clear if @rgb_cache.size >= RGB_CACHE_LIMIT
+      @rgb_cache[hex] = parse_rgb(hex)
+    end
+
+    def self.parse_rgb(hex)
+      h = hex.to_s.delete_prefix("#")
+      h = h.chars.map { |c| c * 2 }.join if h.length == 3
+      [h[0, 2], h[2, 2], h[4, 2]].map { |p| p.to_i(16) }.freeze
+    end
+    private_class_method :parse_rgb
+
+    def now = @clock.call
+
+    # The displayed value for `key`: glides from the displayed value to `target` whenever the target
+    # changes. nil forgets the key; a non-numeric target is returned unchanged.
+    def tween(key, target, duration: 0.4, ease: :out_cubic)
+      if target.nil?
+        forget(key)
+        return nil
+      end
+      return target unless target.is_a?(Numeric)
+
+      t = mark(key)
+      state = @tweens[key]
+      if state.nil? || !@enabled
+        @tweens[key] = [target.to_f, target.to_f, t, duration, ease]
+        return target.to_f
+      end
+      if target.to_f != state[1]
+        from = tween_value(state, t)
+        state = @tweens[key] = [from, target.to_f, t, duration, ease]
+      end
+      tween_value(state, t)
+    end
+
+    # 1.0 on the frame `fire` turns truthy, easing out to 0.0 over `duration`; 0.0 otherwise.
+    def pulse(key, fire, duration: 1.0)
+      t = mark(key)
+      fired, start, = @pulses[key]
+      start = t if fire && !fired
+      @pulses[key] = [fire ? true : false, start, duration]
+      return 0.0 unless @enabled && start
+
+      progress = duration.positive? ? (t - start) / duration : 1.0
+      return 0.0 if progress >= 1
+
+      busy(start + duration)
+      1.0 - EASES[:out_cubic].call(progress.clamp(0.0, 1.0))
+    end
+
+    # Seconds since `value` last changed for `key` (0.0 the first time it is seen).
+    def age(key, value)
+      t = mark(key)
+      old, since = @ages[key]
+      if since.nil? || old != value
+        @ages[key] = [value, t]
+        return 0.0
+      end
+      t - since
+    end
+
+    # Keeps `active?` true for `seconds` more (for marks drawn from `age` that are still fading).
+    def hold(seconds)
+      t = now
+      @evaluated_at = t
+      busy(t + seconds) if @enabled && seconds.positive?
+    end
+
+    # Whether a tween, pulse or hold was still in progress at the last evaluation.
+    def active?
+      return false unless @enabled && @busy_until && @evaluated_at
+
+      @evaluated_at < @busy_until && now < @busy_until + GRACE
+    end
+
+    # Forgets keys not evaluated for `older_than` seconds.
+    def sweep!(older_than: 30)
+      cutoff = now - older_than
+      stale = @seen.select { |_, at| at < cutoff }.keys
+      stale.each { |key| forget(key) }
+      stale.size
+    end
+
+    def forget(key)
+      @tweens.delete(key)
+      @pulses.delete(key)
+      @ages.delete(key)
+      @seen.delete(key)
+    end
+
+    private
+
+    def mark(key)
+      t = now
+      @seen[key] = t
+      @evaluated_at = t
+      t
+    end
+
+    def busy(until_time)
+      @busy_until = until_time if @busy_until.nil? || until_time > @busy_until
+    end
+
+    def tween_value(state, t)
+      from, to, start, duration, ease = state
+      progress = duration.positive? ? (t - start) / duration : 1.0
+      return to if progress >= 1
+
+      busy(start + duration)
+      Motion.lerp(from, to, EASES.fetch(ease).call(progress.clamp(0.0, 1.0)))
+    end
+  end
+end

data/lib/r2ui/panel_state.rb

@@ -7,6 +7,9 @@ module R2UI
   class PanelState
     attr_accessor :search
     attr_reader :sort, :selected, :offset, :collapsed
+    # For tables with motion: the id of the selected line in the last frame, each line id's index
+    # in the last frame (nil before the first), and the gutter mark (:up, :down, :new) per line id.
+    attr_reader :selected_id, :positions, :marks
 
     def initialize(resource, table = nil)
       @resource = resource
@@ -17,6 +20,42 @@ module R2UI
       @selected = 0
       @offset = 0
       @collapsed = Set.new
+      @selected_id = nil
+      @positions = nil
+      @marks = {}
+      @column_keys = table&.columns&.select { |k| resource.column(k) }
+    end
+
+    # Keeps the selection on the same line when lines re-sort: if the line selected last frame is
+    # now at another index, the selection moves there. Then remembers the selected line's id.
+    def follow_selection(lines)
+      if @selected_id && (index = lines.index { |l| l.id == @selected_id }) && index != @selected
+        @selected = index
+      end
+      @selected_id = lines[@selected.clamp(0, [lines.size - 1, 0].max)]&.id
+    end
+
+    # Records where each line is this frame. Lines that moved since the last frame get an :up or
+    # :down mark, lines not there before a :new mark; the first frame (or one after the view
+    # changed: scope, grouping, sort, search) marks nothing. Returns the new marks ({id => kind}).
+    def track_positions(lines)
+      signature = [@scope_index, @group_index, @sort, @search]
+      current = {}
+      lines.each_with_index { |line, i| current[line.id] = i }
+      changes = {}
+      if @positions && signature == @positions_signature
+        current.each do |id, i|
+          before = @positions[id]
+          if before.nil? then changes[id] = :new
+          elsif before != i then changes[id] = i < before ? :up : :down
+          end
+        end
+      end
+      @positions = current
+      @positions_signature = signature
+      @marks.select! { |id, _| current.key?(id) }
+      @marks.merge!(changes)
+      changes
     end
 
     def scope = @scope_index && @resource.scopes[@scope_index]
@@ -41,9 +80,12 @@ module R2UI
       reset_position
     end
 
-    # Next column; numbers sort descending first, text ascending.
+    # Next column (of the table's `columns:` when it picks some); numbers sort descending first,
+    # text ascending.
     def cycle_sort
-      keys = @resource.columns.map(&:key)
+      keys = @column_keys || @resource.columns.map(&:key)
+      return if keys.empty?
+
       current = keys.index(@sort&.first)
       key = keys[current.nil? ? 0 : (current + 1) % keys.size]
       @sort = [key, @resource.column(key).numeric? ? :desc : :asc]
@@ -55,6 +97,7 @@ module R2UI
 
     def move(delta, count)
       @selected = (@selected + delta).clamp(0, [count - 1, 0].max)
+      @selected_id = nil
     end
 
     def toggle(line)
@@ -82,6 +125,7 @@ module R2UI
 
     def reset_position
       @selected = 0
+      @selected_id = nil
       @offset = 0
     end