r2ui 0.1.0 → 0.2.0

data/lib/r2ui/ext/paginator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# s27-paginator: one page of a list at a time, with a bubbles Paginator under it.
+#
+#   R2UI.dashboard do
+#     row do
+#       panel :deploys, resource: nil do
+#         paginate :history, items: -> { DEPLOYS.last(200) }, per_page: 10 do |deploy|
+#           "#{deploy[:sha]}  #{deploy[:status]}"
+#         end
+#       end
+#     end
+#   end
+#
+# `items:` is read on every frame (a plain call of the lambda, so it sees the variables around
+# it); the block turns one item into its line and runs on a Context (state, helpers). Under the
+# page the panel shows a `Bubbles::Paginator`: dots ("● ○ ○", the default) or "1/3" with
+# `type: :arabic`. While the panel has focus, left/h and right/l change the page; other keys
+# (tab, q, ...) carry on as usual. When the list shrinks the page is clamped to the last one;
+# an empty list is one empty page. `component(:history)` is the Bubbles::Paginator.
+module R2UI
+  module Ext
+    module Paginator
+      Item = Data.define(:name, :items, :per_page, :type, :block)
+
+      TYPES = %i[dots arabic].freeze
+      STEPS = { left: -1, "h" => -1, right: 1, "l" => 1 }.freeze
+
+      # Bubbles::Paginator has no `update`; the component host sends it the non-key messages.
+      module Hosted
+        def update(_message) = [self, nil]
+      end
+
+      module_function
+
+      # Re-reads the items, resizes `paginator` to them (clamping the page) and returns them.
+      def refresh(paginator, item)
+        rows = Array(item.items.call)
+        paginator.update_total_pages(rows.size)
+        rows
+      end
+
+      def instance(app, item) = app.components.find { |c| c.item.equal?(item) }
+    end
+  end
+
+  extension :paginator do
+    dsl :panel do
+      def paginate(name, items: nil, per_page: 10, type: :dots, &block)
+        raise ArgumentError, "paginate needs items: -> { [...] }" unless items.respond_to?(:call)
+        raise ArgumentError, "paginate needs a block that draws one item" unless block
+        raise ArgumentError, "paginate per_page must be positive, got #{per_page}" unless per_page.to_i.positive?
+        unless Ext::Paginator::TYPES.include?(type)
+          raise ArgumentError, "paginate type must be one of #{Ext::Paginator::TYPES.join(", ")}, got #{type.inspect}"
+        end
+
+        Component.require_bubbles!
+        item(Ext::Paginator::Item.new(name:, items:, per_page: per_page.to_i, type:, block:))
+      end
+    end
+
+    component(Ext::Paginator::Item) do |item|
+      paginator = Bubbles::Paginator.new(type: item.type, per_page: item.per_page).extend(Ext::Paginator::Hosted)
+      Ext::Paginator.refresh(paginator, item)
+      paginator
+    end
+
+    # Keys the focused panel's paginator handles itself (50: before ordinary bindings).
+    on Bubbletea::KeyMessage, priority: 50 do |message|
+      step = Ext::Paginator::STEPS[Keys.name(message)]
+      hosted = step && app.components.find { |c| c.panel.equal?(focus) && c.item.is_a?(Ext::Paginator::Item) }
+      pass unless hosted
+
+      Ext::Paginator.refresh(hosted.model, hosted.item)
+      step.positive? ? hosted.model.next_page : hosted.model.prev_page
+    end
+
+    panel_item(Ext::Paginator::Item) do |item|
+      paginator = Ext::Paginator.instance(app, item).model
+      rows = Ext::Paginator.refresh(paginator, item)
+      from, to = paginator.slice_bounds(rows.size)
+      lines = rows[from...to].map { |row| call(item.block, row).to_s }
+      (lines.first([height - 1, 0].max) + [paginator.view]).join("\n")
+    end
+  end
+end

data/lib/r2ui/ext/paste.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+# s15-paste: bracketed paste (Bubbletea's `WithBracketedPaste`).
+#
+#   R2UI.dashboard do
+#     paste                                  # turn bracketed paste on
+#     on_paste { |text| state[:clip] = text } # optional; on_paste alone turns it on too
+#   end
+#
+# With bracketed paste on, the terminal sends a paste as one message instead of one key per
+# character, so pasted text never runs key bindings ("q" in a paste does not quit). A paste goes to:
+#
+# 1. the search prompt (`/`), if it is open: appended to the search, with newlines and other control
+#    characters dropped, so a paste never submits or cancels the prompt;
+# 2. the focused component (a text input, say), as one KeyMessage carrying the whole text;
+# 3. otherwise every `on_paste { |text| }` block, on a Context (it may flash, quit, return a
+#    command). With no `on_paste`, the paste is dropped.
+#
+# Bracketed paste is turned off again on every exit path (the runner restores the terminal).
+module R2UI
+  module Ext
+    module Paste
+      # What the search prompt held before a paste, to clean what the core appended.
+      Pending = Data.define(:panel, :search, :text)
+
+      module_function
+
+      # The engine decodes a paste as a runes KeyMessage named "[text]"; a typed key's name is its
+      # own text, so a typed "[" is not a paste.
+      def paste?(message)
+        message.is_a?(Bubbletea::KeyMessage) && message.runes? && !message.alt &&
+          !message.char.nil? && message.name == "[#{message.char}]"
+      end
+
+      MATCHER = ->(message) { paste?(message) }
+
+      def enabled?(dashboard) = dashboard.declared(:paste).any? || dashboard.declared(:on_paste).any?
+
+      def clean(text) = text.gsub(/[[:cntrl:]]/, "")
+    end
+  end
+
+  extension :paste do
+    dsl :dashboard do
+      def paste = declare(:paste, true)
+
+      def on_paste(&block)
+        raise ArgumentError, "on_paste needs a block" unless block
+
+        declare(:on_paste, block)
+      end
+    end
+
+    program_options do
+      { bracketed_paste: true } if Ext::Paste.enabled?(dashboard)
+    end
+
+    # The core search prompt takes keys before any handler and appends a pasted String as is.
+    # Remember the search so after_update can drop the control characters it appended.
+    observe Ext::Paste::MATCHER do |message|
+      next unless Ext::Paste.enabled?(dashboard)
+
+      search = app.panel_state(focus)&.search
+      store(:paste)[:pending] = Ext::Paste::Pending.new(panel: focus, search:, text: message.char) if search
+    end
+
+    after_update do
+      pending = store(:paste).delete(:pending)
+      next unless pending
+
+      panel_state = app.panel_state(pending.panel)
+      if panel_state.search == pending.search + pending.text
+        panel_state.search = pending.search + Ext::Paste.clean(pending.text)
+      end
+    end
+
+    # Runs after the focused component (priority 50) and before ordinary bindings (0), so a paste
+    # never reaches a key binding or the core keys.
+    on Ext::Paste::MATCHER, priority: App::COMPONENT_PRIORITY - 1 do |message|
+      pass unless Ext::Paste.enabled?(dashboard)
+
+      dashboard.declared(:on_paste).each { |block| call(block, message.char) }
+      nil # the blocks' commands are enqueued; returning the Array of blocks would enqueue them too
+    end
+  end
+end

data/lib/r2ui/ext/println.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# s11-println: print a line above the program (Bubbletea's `puts` command).
+#
+#   R2UI.dashboard do
+#     every 60 do
+#       println "#{Time.now.strftime("%H:%M")} checked #{state[:count].to_i} deploys"
+#     end
+#   end
+#
+# `println(text)` enqueues `Bubbletea.puts(text)` and returns that command, so a block may also
+# just end with it. In inline mode (no alt screen) the line is printed above the program's view
+# and stays in the terminal's scrollback; the runner handles it exactly as it handles
+# `Bubbletea.puts` returned from a plain Bubbletea model. Each call prints its own line, in call order. Available in every handler and user block.
+module R2UI
+  extension :println do
+    helpers do
+      def println(text) = command(Bubbletea.puts(text))
+    end
+  end
+end

data/lib/r2ui/ext/progress.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# s26-progress: a progress bar in a panel (bubbles Progress).
+#
+#   R2UI.dashboard do
+#     row height: 4 do
+#       panel :status, resource: nil do
+#         progress(:upload) { state[:sent].to_f / state[:size] }      # a fraction, 0.0..1.0
+#         progress(:build, width: 30, gradient: ["#5A56E0", "#EE6FF8"], animate: true) { state[:built] }
+#       end
+#       panel :job do
+#         progress :done, of: :total                                  # the record's done / total
+#       end
+#     end
+#   end
+#
+# Hosts a `Bubbles::Progress` (`app.component(name)`) drawn on one line: the bar fills the
+# panel's width (or `width:` columns) and ends with the percentage. The fraction comes from the
+# block, run on a Context every frame, or with `of:` from the panel resource's first record
+# (`done / total`, like the core `gauge`). Anything that isn't a finite number shows as 0;
+# values are clamped to 0..1.
+#
+# `gradient: [from, to]` blends the fill between two colours. `animate: true` makes the bar
+# spring towards the fraction (bubbles' animation) instead of jumping to it; the target is read
+# after every update, so a change shows from the next message on.
+module R2UI
+  module Ext
+    module Progress
+      Item = Data.define(:name, :width, :gradient, :animate, :of, :block)
+
+      module_function
+
+      def build(item) = Bubbles::Progress.new(**{ width: item.width, gradient: item.gradient }.compact)
+
+      # The fraction an item shows, in 0..1, read on `ctx` for an item in `panel`.
+      def fraction(ctx, panel, item)
+        value = item.block ? ctx.call(item.block) : from_record(ctx.app, panel, item)
+        value = Float(value, exception: false) if value.is_a?(Numeric) || value.is_a?(String)
+        value.is_a?(Float) && value.finite? ? value.clamp(0.0, 1.0) : 0.0
+      end
+
+      def from_record(app, panel, item)
+        record = panel.resource && app.feeds[panel.resource]&.rows&.first
+        return unless record
+
+        resource = app.registry.resource(panel.resource)
+        done, total = [item.name, item.of].map { |key| (resource.column(key) || DSL::Column.build(key)).read(record) }
+        done.to_f / total.to_f if done.is_a?(Numeric) && total.is_a?(Numeric)
+      end
+
+      def instances(app) = app.components.select { |c| c.item.is_a?(Item) }
+    end
+  end
+
+  extension :progress do
+    dsl :panel do
+      def progress(name, of: nil, width: nil, gradient: nil, animate: false, &block)
+        raise ArgumentError, "progress #{name} needs a block or of:, not both" if block.nil? == of.nil?
+        raise ArgumentError, "progress width must be a positive Integer" unless width.nil? || (width.is_a?(Integer) && width.positive?)
+        raise ArgumentError, "progress gradient must be two colours" unless gradient.nil? || (gradient.is_a?(Array) && gradient.size == 2)
+
+        R2UI::Component.require_bubbles!
+        item(Ext::Progress::Item.new(name:, width:, gradient:, animate:, of:, block:))
+      end
+    end
+
+    component(Ext::Progress::Item) { |item| Ext::Progress.build(item) }
+
+    # Animated bars: retarget when the fraction changed; set_percent returns the animation's tick.
+    after_update do
+      Ext::Progress.instances(app).each do |c|
+        next unless c.item.animate
+
+        target = Ext::Progress.fraction(self, c.panel, c.item)
+        command(c.model.set_percent(target)) if (target - c.model.percent).abs >= 0.001
+      end
+    end
+
+    panel_item(Ext::Progress::Item) do |item|
+      model = app.components.find { |c| c.item.equal?(item) }&.model || Ext::Progress.build(item)
+      model.width = item.width || width
+      item.animate ? model.view : model.view_as(Ext::Progress.fraction(self, panel, item))
+    end
+  end
+end

data/lib/r2ui/ext/refresh.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# s19-refresh: fetch a resource now instead of waiting for its interval.
+#
+#   R2UI.dashboard do
+#     on_key "r", help: "refresh" do refresh end   # the focused panel's resource
+#     every 60 do refresh(:process) end             # a resource by name
+#   end
+#
+# `refresh` is a helper for any handler or user block. It enqueues a background command that
+# fetches the resource once (the same fetch its interval runs, history included), so the update
+# thread never waits on the source; the next frame shows the new rows. The interval keeps running
+# as before. `refresh(:name)` refreshes that resource; an unknown name (one no panel shows) raises
+# ArgumentError. Plain `refresh` uses the focused panel's resource and just flashes "nothing to
+# refresh" when that panel has none. Returns the command.
+module R2UI
+  module Ext
+    module Refresh
+      module_function
+
+      # The feed `refresh` targets: the named one, or the focused panel's.
+      def feed(app, name)
+        if name.nil?
+          name = app.focus&.resource
+          return unless name
+        end
+        app.feeds.fetch(name.to_sym) do
+          raise ArgumentError, "refresh: unknown resource #{name.inspect} (known: #{app.feeds.keys.join(", ")})"
+        end
+      end
+
+      # The background command that fetches `feed` once. It delivers no message: the frame reads
+      # the feed's rows directly.
+      def command(feed)
+        proc do
+          feed.refresh!
+          nil
+        end
+      end
+    end
+  end
+
+  extension :refresh do
+    helpers do
+      def refresh(name = nil)
+        feed = Ext::Refresh.feed(app, name)
+        if feed
+          command(Ext::Refresh.command(feed))
+        else
+          flash("nothing to refresh")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/r2ui/ext/resize.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# s17-resize: react to the window size, and refuse to draw below a minimum.
+#
+#   R2UI.dashboard do
+#     on_resize { |width, height| state[:narrow] = width < 100 }
+#     min_size 80, 20
+#   end
+#
+# `on_resize` runs on every Bubbletea::WindowSizeMessage, the first one (sent at startup)
+# included, on the update thread (a Context); a command it returns runs. It only observes the
+# message, so the core still records the new size.
+#
+# Below `min_size` (width or height short) the whole view is a centered
+# "terminal too small (WxH, need 80x20)" message instead of the dashboard.
+module R2UI
+  module Ext
+    module Resize
+      MinSize = Data.define(:width, :height)
+
+      module_function
+
+      # `height` lines with `text` centered in them (clipped to `width`).
+      def too_small(width, height, min)
+        text = "terminal too small (#{width}x#{height}, need #{min.width}x#{min.height})"[0, [width, 0].max]
+        lines = Array.new([height, 1].max, "")
+        lines[(lines.size - 1) / 2] = (" " * ((width - text.length) / 2)) + text
+        lines.join("\n")
+      end
+    end
+  end
+
+  extension :resize do
+    dsl :dashboard do
+      def on_resize(&block)
+        raise ArgumentError, "on_resize needs a block" unless block
+
+        declare(:on_resize, block)
+      end
+
+      def min_size(width, height)
+        unless width.is_a?(Integer) && height.is_a?(Integer) && width.positive? && height.positive?
+          raise ArgumentError, "min_size needs positive integer width and height, got #{width}x#{height}"
+        end
+
+        declare(:min_size, Ext::Resize::MinSize.new(width:, height:))
+      end
+    end
+
+    observe Bubbletea::WindowSizeMessage do |message|
+      dashboard.declared(:on_resize).each { |block| call(block, message.width, message.height) }
+    end
+
+    view_override do
+      min = dashboard.declared(:min_size).last
+      next unless min && width && height
+      next if width >= min.width && height >= min.height
+
+      Ext::Resize.too_small(width, height, min)
+    end
+  end
+end

data/lib/r2ui/ext/screen.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# s32-screen: a program that draws itself, like a plain Bubble Tea model's `view`.
+#
+#   R2UI.dashboard do
+#     state count: 0                                   # s05
+#     on_key("+") { state[:count] += 1 }               # s03
+#     on_key("-") { state[:count] -= 1 }
+#     screen do |width, height|
+#       "count: #{state[:count]}\n\n+/- to change, q to quit (#{width}x#{height})"
+#     end
+#   end
+#
+# The block runs on a Context (state, helpers) every frame with the window size and returns the
+# whole view as a String ("\n" between lines, ANSI styling such as a lipgloss render kept). No
+# panels and no status bar are drawn, so the dashboard has no rows. Keys still go through the
+# usual routing: `on_key` / `on` handlers first, then the core, so `q` and ctrl+c quit unless a
+# binding takes `q`.
+module R2UI
+  module Ext
+    module Screen
+      Declaration = Data.define(:block)
+    end
+  end
+
+  extension :screen do
+    dsl :dashboard do
+      def screen(&block)
+        raise ArgumentError, "screen needs a block" unless block
+        raise ArgumentError, "screen is already set for this dashboard" if @d.declared(:screen).any?
+
+        declare(:screen, Ext::Screen::Declaration.new(block:))
+      end
+    end
+
+    setup do
+      if dashboard.declared(:screen).any? && dashboard.rows.any?
+        raise Error, "dashboard #{dashboard.name}: screen draws the whole view, so it can't have rows"
+      end
+    end
+
+    view_override do
+      screen = dashboard.declared(:screen).first
+      call(screen.block, width, height).to_s if screen
+    end
+  end
+end

data/lib/r2ui/ext/screen_mode.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# s13-screen-mode: alt screen vs inline (Bubbletea's WithAltScreen, EnterAltScreen, ExitAltScreen).
+#
+#   R2UI.dashboard do
+#     inline height: 10               # no alt screen; draw 10 lines under the prompt
+#     row { panel(:log, resource: nil) { view { state[:last].to_s } } }
+#   end
+#
+# A dashboard takes the whole terminal in the alt screen by default. `inline height: N` runs it in
+# the normal screen instead, drawn N lines tall (at the terminal's width), so the last frame stays
+# in the scrollback when the program quits.
+#
+# Any block can switch at runtime with the helpers, which enqueue Bubbletea's commands:
+#
+#   on_key "f" do enter_alt_screen end   # full screen (an inline dashboard then draws full height)
+#   on_key "i" do exit_alt_screen end    # back to the normal screen
+module R2UI
+  module Ext
+    module ScreenMode
+      # What `inline` declares on the dashboard.
+      Inline = Data.define(:height)
+
+      module_function
+
+      # The inline height the dashboard declared, or nil.
+      def inline_height(dashboard) = dashboard.declared(:inline).last&.height
+    end
+  end
+
+  extension :screen_mode do
+    dsl :dashboard do
+      def inline(height:)
+        unless height.is_a?(Integer) && height.positive?
+          raise ArgumentError, "inline needs a positive integer height, got #{height.inspect}"
+        end
+
+        declare(:inline, Ext::ScreenMode::Inline.new(height:))
+      end
+    end
+
+    helpers do
+      def enter_alt_screen
+        store(:screen_mode)[:alt] = true
+        command(Bubbletea.enter_alt_screen)
+      end
+
+      def exit_alt_screen
+        store(:screen_mode)[:alt] = false
+        command(Bubbletea.exit_alt_screen)
+      end
+    end
+
+    program_options do
+      Ext::ScreenMode.inline_height(dashboard) ? { alt_screen: false } : {}
+    end
+
+    frame_size do |width, height|
+      inline = Ext::ScreenMode.inline_height(dashboard)
+      inline && !store(:screen_mode)[:alt] ? [width, inline] : [width, height]
+    end
+  end
+end

data/lib/r2ui/ext/spinner.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# s25-spinner: bubbles' Spinner as a panel item.
+#
+#   R2UI.dashboard do
+#     row height: 3 do
+#       panel :work, resource: nil do
+#         spinner :busy, style: :dot, label: "deploying", while: -> { state[:busy] }
+#       end
+#     end
+#   end
+#
+# `style` names any of bubbles' spinners (`Bubbles::Spinners::DOT` is `:dot`, `MINI_DOT` is
+# `:mini_dot`, ...). The spinner starts ticking at init on its own TickMessages (bubbles scopes them
+# by id, so two spinners animate independently). With `while:` the item draws only while the lambda
+# (run on a Context) is true; it keeps ticking meanwhile, so it resumes in step.
+module R2UI
+  module Ext
+    module Spinner
+      Item = Data.define(:name, :style, :label, :visible)
+
+      module_function
+
+      # The Bubbles::Spinners entry for `style` (a Symbol or String such as :dot or :mini_dot).
+      def frames_for(style)
+        Component.require_bubbles!
+        const = style.to_s.upcase
+        spec = Bubbles::Spinners.const_get(const, false) if Bubbles::Spinners.const_defined?(const, false)
+        return spec if spec.is_a?(Hash) && spec[:frames]
+
+        known = Bubbles::Spinners.constants.select { |c| Bubbles::Spinners.const_get(c).is_a?(Hash) }
+        raise ArgumentError, "unknown spinner style #{style.inspect} (one of #{known.map { |c| c.to_s.downcase }.join(", ")})"
+      end
+    end
+  end
+
+  extension :spinner do
+    dsl :panel do
+      def spinner(name, style: :dot, label: nil, while: nil)
+        visible = binding.local_variable_get(:while)
+        raise ArgumentError, "spinner while: needs a callable" if visible && !visible.respond_to?(:call)
+
+        Ext::Spinner.frames_for(style)
+        item(Ext::Spinner::Item.new(name:, style:, label:, visible:))
+      end
+    end
+
+    component(Ext::Spinner::Item) { |item| Bubbles::Spinner.new(spinner: Ext::Spinner.frames_for(item.style)) }
+
+    panel_item(Ext::Spinner::Item) do |item|
+      next "" if item.visible && !call(item.visible)
+
+      model = app.components.find { |c| c.item.equal?(item) }&.model
+      next "" unless model
+
+      [model.view, item.label].compact.join(" ")
+    end
+  end
+end

data/lib/r2ui/ext/state.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# s05-state: declared initial state (a Bubbletea model's starting fields).
+#
+#   R2UI.dashboard do
+#     state count: 0, log: []
+#     state theme: :dark                  # a second call merges (later keys win)
+#
+#     every 1 do state[:count] += 1 end
+#   end
+#
+# The declared values seed the app's `state` Hash in `setup`, before init and before any frame,
+# so snapshots and the first frame see them. Each app gets a deep copy (Hashes, Arrays and
+# Strings are copied all the way down), so two apps never share the `log` array and mutating
+# one app's state never changes the declaration.
+module R2UI
+  module Ext
+    module State
+      module_function
+
+      # A copy of `value` whose Hashes, Arrays and unfrozen Strings are fresh objects.
+      def deep_copy(value)
+        case value
+        when Hash then value.to_h { |k, v| [deep_copy(k), deep_copy(v)] }
+        when Array then value.map { |v| deep_copy(v) }
+        when String then value.frozen? ? value : value.dup
+        else value
+        end
+      end
+    end
+  end
+
+  extension :state do
+    dsl :dashboard do
+      def state(values = nil, **fields)
+        values = (values || {}).merge(fields)
+        declare(:state, Ext::State.deep_copy(values))
+      end
+    end
+
+    setup do
+      dashboard.declared(:state).each { |values| state.merge!(Ext::State.deep_copy(values)) }
+    end
+  end
+end

data/lib/r2ui/ext/stopwatch.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# s30-stopwatch: an elapsed-time counter (bubbles' Stopwatch) as a panel item.
+#
+#   R2UI.dashboard do
+#     row height: 3 do
+#       panel :lap, resource: nil do
+#         stopwatch :lap                    # starts counting when the app starts
+#         # stopwatch :lap, autostart: false  # waits for `s`
+#       end
+#     end
+#   end
+#
+# The panel shows the elapsed time ("0:42.00", "1:02:03.00" past an hour), counting in whole
+# seconds. While the panel is focused, `s` starts or stops it and `r` resets it to zero; other keys
+# go on to your bindings and the core as usual. `component(:lap)` is the Bubbles::Stopwatch, for
+# reading `elapsed` / `running?` or sending its `start`, `stop`, `toggle` and `reset` commands.
+#
+# Needs the bubbles gem (it is loaded the first time `stopwatch` is used).
+module R2UI
+  module Ext
+    module Stopwatch
+      Item = Data.define(:name, :autostart)
+
+      HINTS = [%w[s start/stop], %w[r reset]].freeze
+
+      module_function
+
+      def build(item)
+        model = Bubbles::Stopwatch.new
+        model.define_singleton_method(:init) { nil } unless item.autostart
+        model
+      end
+
+      # The stopwatch hosted in the focused panel, if any.
+      def focused(app)
+        app.components.find { |c| c.item.is_a?(Item) && c.panel == app.focus }&.model
+      end
+    end
+  end
+
+  extension :stopwatch do
+    dsl :panel do
+      def stopwatch(name, autostart: true)
+        raise ArgumentError, "stopwatch needs a Symbol name, got #{name.inspect}" unless name.is_a?(Symbol)
+
+        Component.require_bubbles!
+        item(Ext::Stopwatch::Item.new(name:, autostart:))
+      end
+    end
+
+    component(Ext::Stopwatch::Item) { |item| Ext::Stopwatch.build(item) }
+
+    on Bubbletea::KeyMessage, priority: 50 do |message|
+      watch = Ext::Stopwatch.focused(app)
+      pass unless watch
+
+      case Keys.name(message)
+      when "s" then command(watch.toggle)
+      when "r" then command(watch.reset)
+      else pass
+      end
+    end
+
+    hints { focus.items.any?(Ext::Stopwatch::Item) ? Ext::Stopwatch::HINTS : [] }
+  end
+end