r2ui 0.1.0 → 0.2.0

data/lib/r2ui/ext/suspend.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# s10-suspend: ctrl+z suspend / resume (Bubbletea's SuspendCommand and ResumeMessage).
+#
+#   R2UI.dashboard do
+#     suspendable                     # ctrl+z suspends the app, like a shell job
+#     on_resume { flash "welcome back" }
+#
+#     on_key "ctrl+s" do suspend end  # or suspend from any block with the `suspend` helper
+#   end
+#
+# Suspending gives the terminal back (raw mode off, cursor shown, mouse off) and stops the process
+# with SIGTSTP; `fg` (SIGCONT) takes the terminal again and delivers a Bubbletea::ResumeMessage,
+# which runs every `on_resume` block in order on the update thread (a Context: state, flash, a
+# returned command runs too). ctrl+z is an ordinary binding (priority 0), so it does nothing on a
+# dashboard that isn't `suspendable`.
+module R2UI
+  module Ext
+    module Suspend
+      module_function
+
+      def ctrl_z?(message) = message.is_a?(Bubbletea::KeyMessage) && Keys.name(message) == :"ctrl+z"
+    end
+  end
+
+  extension :suspend do
+    dsl :dashboard do
+      def suspendable = declare(:suspendable, true)
+
+      def on_resume(&block)
+        raise ArgumentError, "on_resume needs a block" unless block
+
+        declare(:on_resume, block)
+      end
+    end
+
+    helpers do
+      # Suspends the program (Bubbletea.suspend); a ResumeMessage arrives when it's resumed.
+      def suspend = command(Bubbletea.suspend)
+    end
+
+    on(->(msg) { Ext::Suspend.ctrl_z?(msg) }) do
+      pass if dashboard.declared(:suspendable).empty?
+
+      suspend
+    end
+
+    on Bubbletea::ResumeMessage do
+      blocks = dashboard.declared(:on_resume)
+      pass if blocks.empty?
+
+      blocks.each { |block| call(block) }
+      nil # not `blocks`: a handler's returned Procs would run again as background commands
+    end
+  end
+end

data/lib/r2ui/ext/text_area.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# s21-text-area: a multi-line text box (bubbles' TextArea) in a panel.
+#
+#   R2UI.dashboard do
+#     row height: 8 do
+#       panel :notes, resource: nil do
+#         text_area :notes, placeholder: "write here", height: 4   # height: optional, else the panel's
+#       end
+#     end
+#     on_key "ctrl+s" do File.write("notes.md", area_value(:notes)) end
+#   end
+#
+# The area takes the keys while its panel has focus: typing, enter for a new line, arrows and
+# the usual editing keys (all bubbles' own behavior). esc hands keys back to the dashboard (the
+# panel stays focused; tab away and back to type again). `area_value(:name)` reads the text from
+# any block. The area is as wide as the panel and as tall as `height:` (at most the panel's
+# space); without `height:` it fills the panel.
+module R2UI
+  module Ext
+    module TextArea
+      Item = Data.define(:name, :placeholder, :height)
+
+      module_function
+
+      # The focused panel's text area item, if its area has key focus (else nil).
+      def focused(app)
+        app.focus&.items&.each do |item|
+          next unless item.is_a?(Item)
+
+          model = app.component(item.name)
+          return item if model&.focused?
+        end
+        nil
+      end
+    end
+  end
+
+  extension :text_area do
+    dsl :panel do
+      def text_area(name, placeholder: "", height: nil)
+        raise ArgumentError, "text_area needs a positive height, got #{height}" if height && height.to_i < 1
+
+        Component.require_bubbles!
+        item(Ext::TextArea::Item.new(name:, placeholder: placeholder.to_s, height: height&.to_i))
+      end
+    end
+
+    helpers do
+      def area_value(name) = component(name)&.value
+    end
+
+    component(Ext::TextArea::Item, focusable: true) do |item|
+      Bubbles::TextArea.new(height: item.height || Bubbles::TextArea::DEFAULT_HEIGHT).tap do |area|
+        area.placeholder = item.placeholder
+      end
+    end
+
+    # Sizes the area to the space it has, then lets bubbles draw it.
+    panel_item(Ext::TextArea::Item) do |item|
+      area = component(item.name)
+      area.width = [width, 1].max
+      area.height = [item.height || height, height].min.clamp(1..)
+      area.view
+    end
+
+    on(->(msg) { msg.is_a?(Bubbletea::KeyMessage) && Keys.name(msg) == :escape }, priority: 50) do
+      pass unless Ext::TextArea.focused(app)
+
+      focus_component(nil)
+    end
+  end
+end

data/lib/r2ui/ext/text_input.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# s20-text-input: a one-line text field (bubbles' TextInput) in a panel.
+#
+#   R2UI.dashboard do
+#     row height: 3 do
+#       panel :search, resource: nil do
+#         text_input :query, placeholder: "filter…", prompt: "> ", width: 30, char_limit: 64,
+#                            on_submit: ->(value) { state[:q] = value }
+#       end
+#     end
+#   end
+#
+# While its panel has focus, typed keys go to the input (tab / shift+tab still move panel focus,
+# ctrl+c still quits). enter calls `on_submit` with the value (on a Context, so `state`, `flash`
+# and returned commands work); esc blurs it, handing keys back to the core and your bindings while
+# the panel stays focused; enter on its panel focuses it again. `input_value(:query)` reads the
+# value from any block. Options left out keep bubbles' defaults; the field is drawn by bubbles.
+module R2UI
+  module Ext
+    module TextInput
+      Item = Data.define(:name, :options, :on_submit)
+
+      # Bubbles::TextInput setters the keyword takes.
+      OPTIONS = %i[placeholder prompt width char_limit].freeze
+
+      module_function
+
+      def build(item)
+        Component.require_bubbles!
+        model = Bubbles::TextInput.new
+        item.options.each { |key, value| model.public_send(:"#{key}=", value) }
+        model
+      end
+
+      def enter?(msg) = msg.is_a?(Bubbletea::KeyMessage) && Keys.name(msg) == :enter
+      def escape?(msg) = msg.is_a?(Bubbletea::KeyMessage) && Keys.name(msg) == :escape
+
+      # The text-input instances in the focused panel.
+      def in_focus(app) = app.components.select { |c| c.panel == app.focus && c.item.is_a?(Item) }
+    end
+  end
+
+  extension :text_input do
+    dsl :panel do
+      def text_input(name, on_submit: nil, **options)
+        raise ArgumentError, "text_input needs a name" unless name
+
+        unknown = options.keys - Ext::TextInput::OPTIONS
+        raise ArgumentError, "text_input: unknown option #{unknown.join(", ")}" if unknown.any?
+
+        Component.require_bubbles!
+        item(Ext::TextInput::Item.new(name: name.to_sym, options: options.compact, on_submit:))
+      end
+    end
+
+    helpers do
+      def input_value(name) = component(name.to_sym)&.value
+    end
+
+    component(Ext::TextInput::Item, focusable: true) { |item| Ext::TextInput.build(item) }
+
+    # The focused input handles enter and esc itself (before ordinary bindings).
+    on(->(m) { Ext::TextInput.enter?(m) || Ext::TextInput.escape?(m) }, priority: 50) do |msg|
+      input = Ext::TextInput.in_focus(app).find(&:focused)
+      pass unless input
+
+      if Ext::TextInput.escape?(msg)
+        focus_component(nil)
+      elsif input.item.on_submit
+        call(input.item.on_submit, input.model.value)
+      end
+    end
+
+    # enter on the panel of a blurred input focuses it again.
+    on(->(m) { Ext::TextInput.enter?(m) }) do
+      input = Ext::TextInput.in_focus(app).first
+      pass unless input
+
+      focus_component(input.name)
+    end
+  end
+end

data/lib/r2ui/ext/theme.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# s18-theme: lipgloss styling for the dashboard's own drawing and for your `view` blocks.
+#
+#   R2UI.dashboard do
+#     theme do
+#       title foreground: "#7D56F4", bold: true     # panel titles
+#       focus foreground: "#04B575"                 # the focused panel's border
+#       border foreground: "240"                    # other borders (ANSI 256 index)
+#       selected reverse: true, foreground: "#FAFAFA", background: "#7D56F4"
+#     end
+#
+#     row do
+#       panel :hello, resource: nil do
+#         view { style(foreground: "#FF5F87", italic: true).render("hello") }
+#       end
+#     end
+#   end
+#
+# `theme` restyles the canvas styles (`:title`, `:header`, `:border`, `:focus`, `:selected`, `:ok`,
+# `:warn`, `:alert`, `:accent`, `:muted`, `:dim`, ...; a new name adds a style). Each line is a style
+# name and lipgloss options: `foreground:`, `background:` (any lipgloss colour: "#RRGGBB", "201",
+# "5", `Lipgloss::AdaptiveColor`, ...), and `bold:`, `italic:`, `underline:`, `reverse:`, `faint:`,
+# `strikethrough:`, `blink:`. The colours come out exactly as lipgloss renders them for the
+# terminal's colour profile (truecolor, 256, 16 colours, or none). `theme` may be used more than
+# once; later lines win.
+#
+# `style(**options)` (any block) returns a `Lipgloss::Style` with each option applied as the
+# lipgloss method of that name (`style(bold: true, padding: [0, 1], width: 20)`), so a `view` block
+# can `render` with it.
+#
+# Lipgloss loads on first use: r2ui's pure-Ruby one (through `r2ui/drop_in`), unless the app has
+# already loaded a `Lipgloss`.
+module R2UI
+  module Ext
+    module Theme
+      # The options a canvas style can take: the ones lipgloss turns into SGR parameters.
+      OPTIONS = %i[foreground background bold italic underline reverse faint strikethrough blink].freeze
+
+      # The body of a `theme` block: every call is `style_name **options`. A BasicObject, so names
+      # like `warn` or `select` reach method_missing instead of Kernel.
+      class Builder < BasicObject
+        def initialize = @styles = {}
+
+        def method_missing(name, *args, **options)
+          ::Kernel.raise ::ArgumentError, "theme: #{name} takes only keyword options" unless args.empty?
+          ::Kernel.raise ::ArgumentError, "theme: #{name} needs lipgloss options" if options.empty?
+
+          unknown = options.keys - OPTIONS
+          unless unknown.empty?
+            ::Kernel.raise ::ArgumentError, "theme: #{name} got #{unknown.join(", ")}; use #{OPTIONS.join(", ")}"
+          end
+
+          @styles[name] = Theme.style(**options)
+        end
+
+        def respond_to_missing?(*) = true
+
+        def __styles = @styles
+      end
+
+      module_function
+
+      # Makes `Lipgloss` available: r2ui's pure-Ruby lipgloss unless one is already loaded.
+      def require_lipgloss!
+        return if defined?(::Lipgloss::Style)
+
+        require_relative "../drop_in"
+        require "lipgloss"
+      end
+
+      # A Lipgloss::Style with each option applied as the lipgloss method of that name.
+      def style(**options)
+        require_lipgloss!
+        options.reduce(::Lipgloss::Style.new) do |style, (name, value)|
+          unless ::Lipgloss::Style.public_method_defined?(name) && name != :render
+            raise ArgumentError, "style: lipgloss has no #{name} option"
+          end
+
+          style.public_send(name, *(value.is_a?(Array) ? value : [value]))
+        end
+      end
+
+      PROBE_SGR = /\A\e\[([0-9;:]*)m/
+
+      # The SGR parameters lipgloss uses for `style` (for the current colour profile); "0" (plain)
+      # when it renders no styling.
+      def sgr(style) = style.render("x")[PROBE_SGR, 1] || "0"
+    end
+  end
+
+  extension :theme do
+    dsl :dashboard do
+      def theme(&block)
+        raise ArgumentError, "theme needs a block" unless block
+
+        builder = Ext::Theme::Builder.new
+        builder.instance_eval(&block)
+        declare(:theme, builder.__styles)
+      end
+    end
+
+    helpers do
+      def style(**options) = Ext::Theme.style(**options)
+    end
+
+    styles do
+      themes = dashboard.declared(:theme)
+      themes.reduce({}, :merge).transform_values { |style| Ext::Theme.sgr(style) } unless themes.empty?
+    end
+  end
+end

data/lib/r2ui/ext/view.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# s02-view: a panel item drawn by a block, like a Bubbletea model's `view`.
+#
+#   R2UI.dashboard do
+#     row height: 3 do
+#       panel :clock, resource: nil do
+#         view { "#{state[:ticks].to_i} ticks · #{width}x#{height}" }
+#       end
+#     end
+#   end
+#
+# The block runs on a Context (state, width, height, panel, helpers) on every frame and returns a
+# String; "\n" splits lines and ANSI styling (a lipgloss render) is kept. The panel gives it as
+# many lines as it returns, up to the space left.
+#
+# The reference for panel items: a component story copies this shape (a `dsl :panel` keyword that
+# adds an `item`, plus a `panel_item` drawer or a `component`).
+module R2UI
+  module Ext
+    module View
+      Item = Data.define(:block)
+    end
+  end
+
+  extension :view do
+    dsl :panel do
+      def view(&block)
+        raise ArgumentError, "view needs a block" unless block
+
+        item(Ext::View::Item.new(block:))
+      end
+    end
+
+    panel_item(Ext::View::Item) { |item| call(item.block).to_s }
+  end
+end

data/lib/r2ui/ext/viewport.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# s24-viewport: a scrollable text pane (bubbles' Viewport) in a panel.
+#
+#   R2UI.dashboard do
+#     state log: []
+#     row do
+#       panel :log, resource: nil do
+#         viewport(:log, follow: true) { state[:log].join("\n") }
+#       end
+#     end
+#   end
+#
+# `viewport(name) { text }` hosts a `Bubbles::Viewport` sized to the panel. The block runs on a
+# Context every frame and returns the text ("\n" splits lines, ANSI kept); the scroll position is
+# kept as the text changes. While the panel is focused, bubbles' viewport keys scroll it (up/down,
+# pgup/pgdown, j/k, ctrl+u/ctrl+d, g/G, home/end); keys that don't move it go on to the rest of the
+# app, so "q" still quits. The mouse wheel scrolls it too, by the viewport's `mouse_wheel_delta`
+# lines, when mouse reporting is on (`mouse :cell`). With `follow: true` it sticks to the bottom
+# as the text grows, until you scroll up; scrolling back to the bottom follows again.
+#
+# `component(:log)` in any block is the Bubbles::Viewport (set `style`, `horizontal_step`, ...).
+module R2UI
+  module Ext
+    module Viewport
+      Item = Data.define(:name, :follow, :block)
+
+      module_function
+
+      # The hosted viewport instance in the focused panel, or nil.
+      def focused(ctx) = ctx.app.components.find { |c| c.item.is_a?(Item) && c.panel.equal?(ctx.focus) }
+
+      # Yields the focused viewport's instance; false if there is none or it didn't move.
+      def scroll(ctx)
+        instance = focused(ctx)
+        return false unless instance
+
+        before = [instance.model.y_offset, instance.model.x_offset]
+        yield instance
+        before != [instance.model.y_offset, instance.model.x_offset]
+      end
+    end
+  end
+
+  extension :viewport do
+    dsl :panel do
+      def viewport(name, follow: false, &block)
+        raise ArgumentError, "viewport needs a block" unless block
+
+        Component.require_bubbles!
+        item(Ext::Viewport::Item.new(name:, follow:, block:))
+      end
+    end
+
+    component(Ext::Viewport::Item) { |_item| Bubbles::Viewport.new(width: 0, height: 0) }
+
+    panel_item(Ext::Viewport::Item) do |item|
+      viewport = app.components.find { |c| c.item.equal?(item) && c.panel.equal?(panel) }.model
+      at_bottom = viewport.at_bottom?
+      viewport.width = width
+      viewport.height = height
+      viewport.content = call(item.block).to_s
+      if item.follow && at_bottom
+        viewport.goto_bottom
+      else
+        viewport.y_offset = viewport.y_offset # the panel may have grown
+      end
+      viewport.view
+    end
+
+    # Keys go to the focused panel's viewport before ordinary bindings; those it ignores pass on.
+    on Bubbletea::KeyMessage, priority: 50 do |message|
+      moved = Ext::Viewport.scroll(self) do |instance|
+        instance.model, = Component.split(instance.model, instance.model.update(message))
+      end
+      pass unless moved
+    end
+
+    # bubbles' Viewport leaves the wheel to its host (its mouse handler is empty): scroll it here.
+    on Bubbletea::MouseMessage, priority: 50 do |message|
+      up = message.button == Bubbletea::MouseMessage::BUTTON_WHEEL_UP
+      down = message.button == Bubbletea::MouseMessage::BUTTON_WHEEL_DOWN
+      moved = (up || down) && Ext::Viewport.scroll(self) do |instance|
+        viewport = instance.model
+        next unless viewport.mouse_wheel_enabled
+
+        up ? viewport.scroll_up(viewport.mouse_wheel_delta) : viewport.scroll_down(viewport.mouse_wheel_delta)
+      end
+      pass unless moved
+    end
+  end
+end

data/lib/r2ui/ext/window_title.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# s12-window-title: the terminal window title (Bubbletea's SetWindowTitle, OSC 2).
+#
+#   R2UI.dashboard do
+#     window_title "Agents"                              # set once, when the app starts
+#     window_title { "#{state[:count]} deploys" }        # or: set at start, and again when it changes
+#   end
+#
+#   on_key "r" do set_window_title("refreshing") end     # any block: set it now
+#
+# The block form runs on a Context after init and after every update; the title is sent only when
+# its value differs from the last one sent, so an idle app writes nothing. A dashboard has one
+# `window_title`. `set_window_title(text)` sends a title right away (it returns the command).
+module R2UI
+  module Ext
+    module WindowTitle
+      # What `window_title` declares on the dashboard: fixed text or a block.
+      Title = Data.define(:text, :block) do
+        def value(context) = (block ? context.call(block) : text).to_s
+      end
+    end
+  end
+
+  extension :window_title do
+    dsl :dashboard do
+      def window_title(text = nil, &block)
+        raise ArgumentError, "window_title needs text or a block" if text.nil? == block.nil?
+        raise ArgumentError, "window_title is already set" if @d.declared(:window_title).any?
+
+        declare(:window_title, Ext::WindowTitle::Title.new(text:, block:))
+      end
+    end
+
+    helpers do
+      def set_window_title(text) = command(Bubbletea.set_window_title(text.to_s)) # rubocop:disable Naming/AccessorMethodName
+    end
+
+    after_update do
+      title = dashboard.declared(:window_title).first
+      next unless title
+
+      sent = store(:window_title)
+      value = title.value(self)
+      next if sent.key?(:last) && sent[:last] == value
+
+      sent[:last] = value
+      set_window_title(value)
+    end
+  end
+end