dry-cli-ui 0.6.0 → 0.7.0

data/lib/dry/cli/ui/widgets/multi.rb

@@ -171,6 +171,17 @@ module Dry
           # @return [String]
           def summary(job) = job.label
 
+          # What a job's row says after its elapsed time once it has ended.
+          #
+          # @param job [Job]
+          # @return [String, nil]
+          def note(_job) = nil
+
+          # What the headline says after its elapsed time once every job has ended.
+          #
+          # @return [String, nil]
+          def headline_note = nil
+
           # What follows the headline's glyph while jobs run.
           #
           # @param width [Integer] the columns the title is padded to
@@ -221,7 +232,7 @@ module Dry
             lock.synchronize do
               self.state = outcome
               @seconds = clock.call - started
-              live? ? redraw : terminal.puts(Outcome.line(terminal, state, headline_summary, @seconds))
+              live? ? redraw : terminal.puts(Outcome.line(terminal, state, headline_summary, @seconds, note: headline_note))
             end
           end
 
@@ -318,7 +329,7 @@ module Dry
             return "#{glyph(state)} #{running_headline(width)}#{stopping}" if state == :running
 
             elapsed = " #{terminal.pastel.bright_black("(#{Duration.format(@seconds)})")}"
-            "#{glyph(state)} #{headline_summary}#{elapsed}"
+            "#{glyph(state)} #{headline_summary}#{elapsed}#{noted(headline_note)}"
           end
 
           # @return [String] ` stopping` once a stop is asked for, or nothing
@@ -331,9 +342,15 @@ module Dry
             return "#{glyph(:running)} #{running(job, width)}" if job.state == :running
 
             elapsed = " #{terminal.pastel.bright_black("(#{Duration.format(job.seconds)})")}" if job.seconds
-            "#{glyph(job.state)} #{job.state == :pending ? job.label : summary(job)}#{elapsed}"
+            return "#{glyph(job.state)} #{job.label}" if job.state == :pending
+
+            "#{glyph(job.state)} #{summary(job)}#{elapsed}#{noted(note(job))}"
           end
 
+          # @param text [String, nil]
+          # @return [String] the note, two spaces after what it follows; or nothing
+          def noted(text) = text ? "  #{text}" : ""
+
           # A state's marker, `[✓]`; a turning spinner, `[⠏]`, for a running row, live.
           #
           # @param state [Symbol]

data/lib/dry/cli/ui/widgets/multi_progress.rb

@@ -58,7 +58,7 @@ module Dry
 
               Progress.total(total) unless total.nil?
 
-              @jobs << Multi::Job.new(label, work, Progress::Handle.new(total, nil, color: Progress.color(color)))
+              @jobs << Multi::Job.new(label, work, Progress::Handle.new(total, color: Progress.color(color)))
               self
             end
 
@@ -112,9 +112,11 @@ module Dry
           # @return [Object]
           def call(job) = spinner?(job) ? Line.call(job.work, job.handle) : super
 
+          # A bar whose total is known and zero ends failed, as {Progress::Handle#finish} says.
+          #
           # @param job [Job]
-          # @return [Boolean]
-          def reported_failure?(job) = spinner?(job) && job.handle.failed?
+          # @return [Boolean] whether its line or its bar was told to fail
+          def reported_failure?(job) = spinner?(job) ? job.handle.failed? : job.handle.finish.failed?
 
           # @param job [Job]
           # @return [Progress::Handle, nil] nil for a spinner, which has no progress
@@ -126,26 +128,42 @@ module Dry
           def running(job, width)
             return [job.label, job.handle.detail].reject(&:empty?).join(" ") if spinner?(job)
 
-            "#{job.label.ljust(width)} #{meter(job.handle.current, job.handle.total, job.started, job.handle.color)}"
+            handle = job.handle
+            "#{job.label.ljust(width)} #{meter(handle.current, handle.total, job.started, handle.color, handle.counts)}"
           end
 
           # @param job [Job]
           # @return [String]
-          def summary(job)
-            return job.handle.summary(job.label) if spinner?(job)
+          def summary(job) = job.handle.summary(job.label)
 
-            "#{job.label} #{job.handle.current}/#{job.handle.total || '?'}"
-          end
+          # @param job [Job]
+          # @return [String, nil] a bar's failed and auxiliary counts, if any
+          def note(job) = spinner?(job) ? nil : Progress.breakdown(terminal.pastel, config, job.handle.counts)
 
           # @param width [Integer]
           # @return [String]
           def running_headline(width)
-            "#{title.ljust(width)} #{meter(current, total, started)}"
+            "#{title.ljust(width)} #{meter(current, total, started, nil, counts)}"
           end
 
           # @return [String]
           def headline_summary = "#{title} #{current}/#{total}"
 
+          # @return [String, nil] every bar's failed and auxiliary counts, if
+          #   any, when the headline counts units
+          def headline_note
+            tally = counts
+            tally && Progress.breakdown(terminal.pastel, config, tally)
+          end
+
+          # @return [Hash{Symbol => Integer}, nil] units by outcome across every
+          #   bar; nil when counting jobs
+          def counts
+            return if @count == :jobs
+
+            Progress::Handle::OUTCOMES.to_h { |outcome| [outcome, bars.sum { it.handle.counts[outcome] }] }
+          end
+
           # @return [Integer] units completed across every job, or jobs ended
           def current
             return jobs.count(&:seconds) if @count == :jobs
@@ -167,22 +185,17 @@ module Dry
 
           # `[◼◼◼   ] 48%  96/200  ETA 3.1s`, with the count right-aligned to
           # the widest any row can show, so every count ends in one column.
-          #
-          # A bar whose total is not known yet is drawn empty, counting `12/?`.
+          # See {Progress.meter}.
           #
           # @param done [Integer]
           # @param all [Integer, nil]
-          # @param since [Float, nil] when the work started, by the clock
+          # @param since [Float] when the work started, by the clock
           # @param color [Symbol, nil] the bar's own colour, if any
+          # @param tally [Hash{Symbol => Integer}, nil] units by outcome
           # @return [String]
-          def meter(done, all, since, color = nil)
-            ratio = if all.nil? then 0.0
-                    elsif all.zero? then 1.0
-                    else done.fdiv(all)
-                    end
-            bar = Progress.bar(terminal.pastel, config, ratio, bar_columns, color: color)
-            format("%<bar>s %<percent>3d%%  %<count>s  ETA %<eta>s",
-                   bar: bar, percent: (ratio * 100).floor, count: "#{done}/#{all || '?'}".rjust(count_width), eta: eta(done, all, since))
+          def meter(done, all, since, color, tally)
+            Progress.meter(terminal.pastel, config, done: done, all: all, columns: bar_columns, eta: eta(done, all, since),
+                                                    color: color, counts: tally, count_width: count_width)
           end
 
           # The widest count any row shows: the headline's, once every job is done.
@@ -199,14 +212,9 @@ module Dry
 
           # @param done [Integer]
           # @param all [Integer, nil]
-          # @param since [Float, nil]
-          # @return [String] the time left at the rate so far, or `--` before
-          #   any progress or while the total is not known
-          def eta(done, all, since)
-            return "--" if since.nil? || done.zero? || all.nil?
-
-            Duration.format((clock.call - since) / done * (all - done))
-          end
+          # @param since [Float] when the work started, by the clock
+          # @return [String] see {Progress.eta}
+          def eta(done, all, since) = Progress.eta(done, all) { clock.call - since }
         end
       end
     end

data/lib/dry/cli/ui/widgets/outcome.rb

@@ -12,11 +12,13 @@ module Dry
           # @param state [Symbol] `:done` or `:failed`
           # @param label [String] what the operation was
           # @param seconds [Numeric] how long it took
+          # @param note [String, nil] said after the time, such as a progress
+          #   bar's breakdown `20 failed, 5 auxiliary`
           # @return [String] the line, without a newline
-          def self.line(terminal, state, label, seconds)
+          def self.line(terminal, state, label, seconds, note: nil)
             glyph, color = Theme::STATES.fetch(state)
             pastel = terminal.pastel
-            "#{pastel.decorate(glyph, *color)} #{label} #{pastel.bright_black("(#{Duration.format(seconds)})")}"
+            "#{pastel.decorate(glyph, *color)} #{label} #{pastel.bright_black("(#{Duration.format(seconds)})")}#{"  #{note}" if note}"
           end
         end
       end

data/lib/dry/cli/ui/widgets/progress.rb

@@ -1,27 +1,39 @@
 # frozen_string_literal: true
 
-require "tty-progressbar"
+require "concurrent"
 
 module Dry
   class CLI
     module UI
       module Widgets
-        # A progress bar with a percentage, a count and an ETA, followed by
-        # the outcome line once the block ends.
+        # A progress bar with a turning spinner, a percentage, a count and an
+        # ETA, followed by the outcome line once the block ends.
+        #
+        # Each unit can be counted as a success, as auxiliary, or as a failure
+        # (see {Handle#advance}). The bar's finished part is drawn left to
+        # right in {Configuration#bar_failed_color}, {Configuration#bar_aux_color}
+        # and the bar's own colour, each part as wide as its share, and the
+        # outcome line ends with the breakdown: `✓ Placing 100/100 (2.1s)  20 failed, 5 auxiliary`.
         #
         # Without an animated terminal it prints `Label...` before the block
         # and the outcome line, with the final count, after it.
         class Progress
           # What the block is given to report progress through.
           class Handle
+            # What {#advance} can count a unit as: a success, something
+            # relevant but auxiliary, or a failure.
+            OUTCOMES = %i[ok aux failed].freeze
+
             # @param total [Integer, nil] nil until the work finds out
-            # @param bar [TTY::ProgressBar, nil]
+            # @param on_change [#call, nil] called with no arguments whenever
+            #   the count or the total changes, by the widget that draws the bar
             # @param color [Symbol, nil] see {Progress.color}
-            def initialize(total, bar, color: nil)
+            def initialize(total, on_change = nil, color: nil)
               @total = total
-              @bar = bar
+              @on_change = on_change
               @color = color
               @current = 0
+              @tally = OUTCOMES.to_h { [it, 0] }
             end
 
             # @return [Integer, nil] the number of units the operation has; nil
@@ -35,41 +47,116 @@ module Dry
             # @return [Integer] the number of units completed so far
             attr_reader :current
 
+            # @return [Hash{Symbol => Integer}] the units completed so far by
+            #   outcome, `{ ok:, aux:, failed: }`, adding up to {#current}; frozen
+            def counts = @tally.dup.freeze
+
             # Sets the number of units once the work finds out, such as a download
-            # learning its size. {#current} is lowered to fit.
+            # learning its size. {#current} is lowered to fit, taking the units
+            # off {#counts} from `:ok` first.
             #
             # @param value [Integer]
             # @raise [ArgumentError] when value is not a non-negative Integer
             def total=(value)
               @total = Progress.total(value)
-              self.current = current.clamp(0, value)
-              bar&.update(total: value)
+              settle(current.clamp(0, value), :ok)
+              changed
             end
 
-            # Marks units as complete. Progress never passes {#total} once it is known.
+            # Marks units as complete, each counted as the outcome given.
+            # Progress never passes {#total} once it is known.
+            #
+            # @example
+            #   bar.advance                  # one unit that succeeded
+            #   bar.advance(as: :failed)     # one that failed
+            #   bar.advance(3, as: :aux)     # three relevant but auxiliary ones
             #
             # @param step [Integer]
+            # @param as [Symbol] one of {OUTCOMES}
             # @return [self]
-            def advance(step = 1)
-              self.current = (current + step).clamp(0, total)
-              bar&.advance(step)
+            # @raise [ArgumentError] when as is not one of {OUTCOMES}
+            def advance(step = 1, as: :ok)
+              Progress.outcome(as)
+              settle((current + step).clamp(0, total), as)
+              changed
               self
             end
 
+            # Ends the work as a failure when the block returns, without
+            # raising: for work that went on after some of its units failed.
+            #
+            # @param reason [#to_s, nil] said after the count, such as "2 failed"
+            # @return [self]
+            def fail(reason = nil)
+              @failed = true
+              @reason = reason&.to_s
+              self
+            end
+
+            # @return [Boolean] whether {#fail} was called
+            def failed? = @failed == true
+
+            # @return [String, nil] what {#fail} was given
+            attr_reader :reason
+
+            # Called by the widget when the block returns. A total that is known
+            # and zero ends the work as a failure, with {Progress::NOTHING} as
+            # the reason, unless {#fail} was already called.
+            #
+            # @return [self]
+            def finish
+              fail(NOTHING) if total&.zero? && !failed?
+
+              self
+            end
+
+            # The label and the count, with the failure's reason after it when
+            # there is one: `Extracting 1002/1002: 2 failed`.
+            #
+            # @param label [String]
+            # @return [String]
+            def summary(label)
+              count = "#{label} #{current}/#{total || '?'}"
+              failed? && !reason.to_s.empty? ? "#{count}: #{reason}" : count
+            end
+
             private
 
-            # @return [TTY::ProgressBar, nil]
-            attr_reader :bar
+            # Moves {#current} to a new value, adding the units gained to an
+            # outcome, or taking the units lost off that outcome first.
+            #
+            # @param value [Integer]
+            # @param outcome [Symbol]
+            # @return [void]
+            def settle(value, outcome)
+              change = value - current
+              @current = value
+              return @tally[outcome] += change unless change.negative?
+
+              [outcome, *(OUTCOMES - [outcome])].reduce(-change) do |left, key|
+                taken = [left, @tally[key]].min
+                @tally[key] -= taken
+                left - taken
+              end
+            end
 
-            attr_writer :current
+            # @return [void]
+            def changed = @on_change&.call
           end
 
-          # Columns kept for the brackets, percentage, count and ETA around the bar.
+          # The reason a bar fails with when it ends with nothing to do.
+          NOTHING = "nothing to process"
+
+          # Columns kept for the spinner, brackets, percentage, count and ETA around the bar.
           CHROME = 36
 
           # Narrowest bar drawn.
           MIN_BAR = 10
 
+          # The words the outcome line's breakdown counts with, and the setting
+          # each one is painted with.
+          BREAKDOWN = { failed: ["failed", :bar_failed_color], aux: ["auxiliary", :bar_aux_color] }.freeze
+
           # Checks a bar's total.
           #
           # @param value [Integer]
@@ -92,19 +179,121 @@ module Dry
             raise ArgumentError, "color must be a Pastel style or nil, got #{value.inspect}"
           end
 
+          # Checks what a unit is counted as.
+          #
+          # @param value [Symbol] one of {Handle::OUTCOMES}
+          # @return [Symbol] the value
+          # @raise [ArgumentError] for anything else
+          def self.outcome(value)
+            return value if Handle::OUTCOMES.include?(value)
+
+            raise ArgumentError, "as must be one of #{Handle::OUTCOMES.inspect}, got #{value.inspect}"
+          end
+
           # A bar between brackets, painted as the configuration says: the
           # finished part in {Configuration#bar_color}, or in the bar's own
           # colour when it has one, and all of it on {Configuration#bar_background}.
           #
+          # Given counts, the finished part starts with the failed units in
+          # {Configuration#bar_failed_color}, then the auxiliary ones in
+          # {Configuration#bar_aux_color}, each as wide as its share (see {.segments}).
+          #
           # @param pastel [Pastel::Delegator] a no-op when colour is off
           # @param config [Configuration]
           # @param ratio [Float] how much is finished, from 0 to 1
           # @param columns [Integer] the bar's width inside the brackets
           # @param color [Symbol, nil] the finished part's style; nil for {Configuration#bar_color}
+          # @param counts [Hash{Symbol => Integer}, nil] units by outcome, as {Handle#counts}
           # @return [String]
-          def self.bar(pastel, config, ratio, columns, color: nil)
+          def self.bar(pastel, config, ratio, columns, color: nil, counts: nil)
             filled = (ratio * columns).floor
-            "[#{complete(pastel, config, color) * filled}#{incomplete(pastel, config) * (columns - filled)}]"
+            failed, aux, ok = counts ? segments(filled, counts) : [0, 0, filled]
+            [
+              "[",
+              paint(pastel, config, config.bar_failed_color) * failed,
+              paint(pastel, config, config.bar_aux_color) * aux,
+              complete(pastel, config, color) * ok,
+              incomplete(pastel, config) * (columns - filled),
+              "]"
+            ].join
+          end
+
+          # Splits a bar's finished cells between the failed, auxiliary and
+          # successful units, in proportion to their counts. The cells always
+          # add up to the finished width, and each outcome that has units gets
+          # at least one cell while the width allows.
+          #
+          # @param filled [Integer] the finished cells
+          # @param counts [Hash{Symbol => Integer}] units by outcome, as {Handle#counts}
+          # @return [Array(Integer, Integer, Integer)] failed, auxiliary and successful cells
+          def self.segments(filled, counts)
+            values = counts.values_at(:failed, :aux, :ok)
+            sum = values.sum
+            return [0, 0, filled] if sum.zero?
+
+            shares = values.map { it * filled / sum.to_f }
+            cells = shares.map(&:floor)
+            shares.each_index.sort_by { |index| [cells[index] - shares[index], index] }
+                  .first(filled - cells.sum).each { cells[it] += 1 }
+            values.each_index do |index|
+              next unless values[index].positive? && cells[index].zero?
+
+              donor = cells.index(cells.max)
+              next unless cells[donor] > 1
+
+              cells[donor] -= 1
+              cells[index] += 1
+            end
+            cells
+          end
+
+          # `[◼◼◼   ]  48%  96/200  ETA 3.1s`. A bar whose total is not known
+          # yet is drawn empty, counting `12/?`; an empty one is drawn full.
+          #
+          # @param pastel [Pastel::Delegator]
+          # @param config [Configuration]
+          # @param done [Integer]
+          # @param all [Integer, nil]
+          # @param columns [Integer] the bar's width inside the brackets
+          # @param eta [String] the time left, as {.eta} says it
+          # @param color [Symbol, nil] the bar's own colour, if any
+          # @param counts [Hash{Symbol => Integer}, nil] units by outcome
+          # @param count_width [Integer] the columns the count is right-aligned to
+          # @return [String]
+          def self.meter(pastel, config, done:, all:, columns:, eta:, color: nil, counts: nil, count_width: 0)
+            ratio = if all.nil? then 0.0
+                    elsif all.zero? then 1.0
+                    else done.fdiv(all)
+                    end
+            format("%<bar>s %<percent>3d%%  %<count>s  ETA %<eta>s",
+                   bar: bar(pastel, config, ratio, columns, color: color, counts: counts),
+                   percent: (ratio * 100).floor, count: "#{done}/#{all || '?'}".rjust(count_width), eta: eta)
+          end
+
+          # The time left at the rate so far.
+          #
+          # @param done [Integer]
+          # @param all [Integer, nil]
+          # @yieldreturn [Numeric] the seconds spent so far; asked only when needed
+          # @return [String] `--` before any progress or while the total is not known
+          def self.eta(done, all)
+            return "--" if done.zero? || all.nil?
+
+            Duration.format(yield / done * (all - done))
+          end
+
+          # The failed and auxiliary counts, each in its configured colour:
+          # `20 failed, 5 auxiliary`.
+          #
+          # @param pastel [Pastel::Delegator]
+          # @param config [Configuration]
+          # @param counts [Hash{Symbol => Integer}] units by outcome, as {Handle#counts}
+          # @return [String, nil] nil when no unit failed or was auxiliary
+          def self.breakdown(pastel, config, counts)
+            parts = BREAKDOWN.filter_map do |key, (word, setting)|
+              pastel.decorate("#{counts[key]} #{word}", *[config.public_send(setting)].compact) if counts[key].positive?
+            end
+            parts.join(", ") unless parts.empty?
           end
 
           # @param pastel [Pastel::Delegator]
@@ -112,7 +301,15 @@ module Dry
           # @param color [Symbol, nil] the style; nil for {Configuration#bar_color}
           # @return [String] one finished cell, painted
           def self.complete(pastel, config, color = nil)
-            pastel.decorate(config.bar_complete, *[color || config.bar_color, config.bar_background].compact)
+            paint(pastel, config, color || config.bar_color)
+          end
+
+          # @param pastel [Pastel::Delegator]
+          # @param config [Configuration]
+          # @param style [Symbol, nil] the cell's style; nil for none
+          # @return [String] one finished cell in the style, on {Configuration#bar_background}
+          def self.paint(pastel, config, style)
+            pastel.decorate(config.bar_complete, *[style, config.bar_background].compact)
           end
 
           # @param pastel [Pastel::Delegator]
@@ -129,6 +326,9 @@ module Dry
             @terminal = terminal
             @clock = clock
             @config = config
+            @lock = Mutex.new
+            @live = false
+            @frame = 0
           end
 
           # Runs the block with a progress bar.
@@ -144,20 +344,21 @@ module Dry
           def run(label, total:, color: nil)
             Progress.total(total)
             Progress.color(color)
-            started = clock.call
-            bar = start(label, total, color)
-            handle = Handle.new(total, bar, color: color)
+            @label = label
+            @started = clock.call
+            handle = @handle = Handle.new(total, method(:refresh), color: color)
             terminal.started(handle, label, progress: handle)
+            ticker = start
             ok = false
             result = yield handle
-            ok = true
+            ok = !handle.finish.failed?
             result
           ensure
             if handle
-              bar&.stop
+              stop(ticker)
               terminal.finished(handle, ok)
-              summary = "#{label} #{handle.current}/#{handle.total}"
-              terminal.puts(Outcome.line(terminal, ok ? :done : :failed, summary, clock.call - started))
+              note = Progress.breakdown(terminal.pastel, config, handle.counts)
+              terminal.puts(Outcome.line(terminal, ok ? :done : :failed, handle.summary(label), clock.call - started, note: note))
             end
           end
 
@@ -172,26 +373,73 @@ module Dry
           # @return [Configuration]
           attr_reader :config
 
-          # @param label [String]
-          # @param total [Integer]
-          # @param color [Symbol, nil]
-          # @return [TTY::ProgressBar, nil]
-          def start(label, total, color)
-            unless terminal.animated? && total.positive?
+          # @return [Mutex] held while the bar is drawn
+          attr_reader :lock
+
+          # @return [String]
+          attr_reader :label
+
+          # @return [Handle]
+          attr_reader :handle
+
+          # @return [Float] when the block started, by the clock
+          attr_reader :started
+
+          # Draws the bar and starts its spinner turning when live, or prints
+          # the label otherwise.
+          #
+          # @return [Concurrent::TimerTask, nil]
+          def start
+            unless terminal.animated? && handle.total.positive?
               terminal.puts("#{label}...")
               return
             end
 
-            TTY::ProgressBar.new(
-              "#{label} [:bar] :percent  :current/:total  ETA :eta",
-              total: total,
-              width: [terminal.width - label.length - CHROME, MIN_BAR].max,
-              output: terminal.io,
-              complete: Progress.complete(terminal.pastel, config, color),
-              incomplete: Progress.incomplete(terminal.pastel, config),
-              clear: true,
-              hide_cursor: true
-            )
+            terminal.print(terminal.cursor.hide)
+            @live = true
+            refresh
+            Concurrent::TimerTask.new(execution_interval: config.spinner_frame_seconds) { refresh(1) }.tap(&:execute)
+          end
+
+          # Stops the spinner and clears the bar.
+          #
+          # @param ticker [Concurrent::TimerTask, nil]
+          # @return [void]
+          def stop(ticker)
+            ticker&.shutdown
+            ticker&.wait_for_termination(1)
+            lock.synchronize do
+              next unless @live
+
+              @live = false
+              terminal.print("#{terminal.cursor.clear_line}#{terminal.cursor.show}")
+            end
+          end
+
+          # Draws the bar over itself, turning the spinner by some frames.
+          #
+          # @param turn [Integer] frames to move the spinner on
+          # @return [void]
+          def refresh(turn = 0)
+            lock.synchronize do
+              next unless @live
+
+              @frame += turn
+              terminal.print("#{terminal.cursor.clear_line}#{row}")
+            end
+          end
+
+          # `⠋ Importing [◼◼◼   ]  48%  96/200  ETA 3.1s`
+          #
+          # @return [String]
+          def row
+            frames = config.spinner_frames
+            done = handle.current
+            all = handle.total
+            meter = Progress.meter(terminal.pastel, config, done: done, all: all, color: handle.color, counts: handle.counts,
+                                                            columns: [terminal.width - label.length - CHROME, MIN_BAR].max,
+                                                            eta: Progress.eta(done, all) { clock.call - started })
+            "#{frames[@frame % frames.size]} #{label} #{meter}"
           end
         end
       end

data/lib/dry/cli/ui/widgets/prompt.rb

@@ -17,6 +17,9 @@ module Dry
         # An exhausted input returns the default. A question without a
         # default raises {NonInteractiveError} rather than inventing an answer.
         class Prompt
+          # The choices {#confirm} offers on an interactive terminal.
+          CONFIRM_CHOICES = { "YES" => true, "NO" => false }.freeze
+
           # @param input [IO] where answers come from
           # @param terminal [Terminal] where questions go
           # @param backend [TTY::Prompt, nil] the interactive implementation; built on first use when nil
@@ -43,13 +46,14 @@ module Dry
             end
           end
 
-          # Asks a yes/no question.
+          # Asks a yes/no question. On an interactive terminal it is a list to pick YES or NO from,
+          # starting on the default; otherwise it reads `y`, `yes`, `n` or `no`.
           #
           # @param question [String]
           # @param default [Boolean] returned for an empty answer or an exhausted input
           # @return [Boolean]
           def confirm(question, default: false)
-            return backend.yes?(question, default: default) if interactive?
+            return backend.select(question, CONFIRM_CHOICES, default: default ? 1 : 2) if interactive?
 
             loop do
               terminal.print("#{question} #{default ? '(Y/n)' : '(y/N)'} ")

data/lib/dry/cli/ui/widgets.rb

@@ -8,6 +8,7 @@ module Dry
       # namespace touches a TTY toolkit class.
       module Widgets
         autoload :Box, File.expand_path("widgets/box", __dir__)
+        autoload :Legend, File.expand_path("widgets/legend", __dir__)
         autoload :Multi, File.expand_path("widgets/multi", __dir__)
         autoload :MultiProgress, File.expand_path("widgets/multi_progress", __dir__)
         autoload :MultiSpinner, File.expand_path("widgets/multi_spinner", __dir__)