dry-cli-ui 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1cbc8893268017d5d41b730292d9f6a640230ff87aa2282afd4cfc0a0084487
-  data.tar.gz: 3781eb7e227b6466555153687b6cf1783a7f4acbc6dffc1b5cd86c5b209dad91
+  metadata.gz: 412754e986acfa5b60ce22a1d447cd470098ffe42434ec453636cf563e65a8d3
+  data.tar.gz: 23fcbd8f9cbd0cdda55e6f88883b36092b07703e3895f47f8348a11743f4f3a8
 SHA512:
-  metadata.gz: c7a31f33372b1432c461f11319daad6503755f6c173a5bba9aee8508034de826c77ef662579471c9ce18b802098f1c426942f71e46e0d6a18c0b492fbd2a3fd9
-  data.tar.gz: 96c0528c1e32b927abf1d5f042a4879bb67e5d3cc9fa408a4d655ff020e9a01d17483a99da83aaa573d632486f8e2532a7f6c760105eb46c7b94b97083357491
+  metadata.gz: 46f47189bba69663ef98407036a101983ff870f8daa56e02fcbd788bf4a82f83d9a8546730c2cfc61056548a26ccc84102fe2f1a64d70ff1a063d5517c8179fe
+  data.tar.gz: b83ec6dd332065f8fdc8cb346abe35773e5ddb3cc14a01cec09dd7eabcba04529194e003d837336c1891d21f140b2e344d8ef1f0fedab942b21facd4c1634b96

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0]
+
+- `ui.spinner` and every `ui.tasks` task give their block a `Dry::CLI::UI::Line`. `line.detail = "..."` shows text after the label while the work runs, redrawn in place on an animated terminal and never printed otherwise. `line.fail("reason")` ends the work as `✗ label: reason` without raising; the spinner still returns the block's value, and a task tree runs on past a task that fails this way.
+- `concurrent:` on `ui.tasks` and `group` also takes a positive Integer, the most tasks that run at once. Anything other than `true`, `false` or a positive Integer raises `ArgumentError`.
+- `ui.popup(*paragraphs, title:, width:)` draws a box on `err` over whatever is on the screen: sized to its text, centred, with the cursor left where it was. Without animation it is the same box `ui.box` draws.
+
 ## [0.1.0]
 
 - Initial release of `dry-cli-ui`, which replaces `dry-cli-autocomplete` in this repository.

data/README.md

@@ -86,6 +86,14 @@ ui.info "Short and narrow", width: 40
 ui.box "Name: Alan Turing", "Role: Cryptanalyst", title: "Profile"   # untitled without title:
 ```
 
+### Popups
+
+```ruby
+ui.popup "h  help", "q  quit", title: "Keys"
+```
+
+On a terminal, a box drawn over whatever is on the screen: only as wide as its text, centred, and leaving the cursor where it was, so a spinner or a redrawn screen carries on underneath. Piped, it is the same box `ui.box` draws, on `err`.
+
 ### Status lines
 
 ```ruby
@@ -101,6 +109,17 @@ rules = ui.spinner("Loading tax rules") { load_rules }
 
 Returns the block's value. Leaves `✓ Loading tax rules (0.3s)` behind, or `✗` and the re-raised error when the block fails.
 
+The block is given a `Dry::CLI::UI::Line`, for work that has more to say while it runs, or that can fail without raising:
+
+```ruby
+ui.spinner("Importing rules") do |line|
+  rules.each { |rule| line.detail = rule.name; import(rule) }
+  line.fail("#{skipped.size} rules skipped") if skipped.any?
+end
+```
+
+`line.detail = "..."` shows text after the label, redrawn in place as it changes. Piped, the detail is kept and never printed, since it can change many times a second. `line.fail(reason)` ends the spinner as `✗ Importing rules: 3 rules skipped (4.1s)` without raising, and the block's value is still returned. `line.failed?` and `line.reason` read it back. Every `Line` method is safe to call from any thread.
+
 ### Progress bars
 
 ```ruby
@@ -147,7 +166,21 @@ Deploy
 └─ ✓ Restart (0.3s)
 ```
 
-While it runs, the tree redraws in place and every running task has its own spinner. Piped, each line is printed once it is final, and a group's line appears as `▸` when it starts. `concurrent: true` runs a group's tasks at the same time, on a group or on `ui.tasks` itself. When a task fails, it is marked `✗`, tasks already running finish, the rest are marked skipped (`–`), and the error is re-raised.
+While it runs, the tree redraws in place and every running task has its own spinner. Piped, each line is printed once it is final, and a group's line appears as `▸` when it starts. `concurrent: true` runs a group's tasks at the same time, on a group or on `ui.tasks` itself, and `concurrent: 3` runs at most three at once. When a task raises, it is marked `✗`, tasks already running finish, the rest are marked skipped (`–`), and the error is re-raised.
+
+Each task is given a `Line`, as a spinner's block is. Its detail is drawn after the task's name while it runs, and `line.fail(reason)` marks the task `✗ name: reason` and its groups `✗`, while the rest of the tree runs on:
+
+```ruby
+ui.tasks("Fetching", concurrent: 4) do |t|
+  assets.each do |asset|
+    t.task(asset.name) do |line|
+      fetch(asset) { |percent| line.detail = "#{percent}%" }
+    rescue Timeout::Error
+      line.fail("timed out")
+    end
+  end
+end
+```
 
 ### Tables
 
@@ -185,9 +218,9 @@ When the input runs out, a prompt returns its default, or raises `Dry::CLI::UI::
 
 ## Where output goes
 
-| To `out` (results)                                          | To `err` (everything else)                                                      |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `info`, `success`, `box`, `table`, `status` at those levels | `debug`, `warn`, `error`, `fatal`, spinners, progress bars, task trees, prompts |
+| To `out` (results)                                          | To `err` (everything else)                                                               |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `info`, `success`, `box`, `table`, `status` at those levels | `debug`, `warn`, `error`, `fatal`, `popup`, spinners, progress bars, task trees, prompts |
 
 `mycli export > rules.csv` therefore writes only the command's results to the file, while its progress stays on the screen. `ui` writes to the streams dry-cli was called with, so `Dry::CLI.new(registry).call(out: io, err: io)` captures everything.
 

data/SPECIFICATION.md

@@ -93,6 +93,7 @@ ui.progress(...)
 ui.status(...)
 
 ui.box(...)
+ui.popup(...)
 ui.table(...)
 ui.tasks(...)
 
@@ -225,10 +226,10 @@ Only files under `widgets/` and `terminal.rb` touch a TTY class. A future render
 
 Results go to `out`; everything about the command's own progress goes to `err`. Piping a command therefore captures its results and nothing else.
 
-| `out`                             | `err`                                                                      |
-| --------------------------------- | -------------------------------------------------------------------------- |
-| `info`, `success`, `box`, `table` | `debug`, `warn`, `error`, `fatal`, `spinner`, `progress`, `tasks`, prompts |
-| `status` at `info` or `success`   | `status` at `debug`, `warn`, `error` or `fatal`                            |
+| `out`                             | `err`                                                                               |
+| --------------------------------- | ----------------------------------------------------------------------------------- |
+| `info`, `success`, `box`, `table` | `debug`, `warn`, `error`, `fatal`, `popup`, `spinner`, `progress`, `tasks`, prompts |
+| `status` at `info` or `success`   | `status` at `debug`, `warn`, `error` or `fatal`                                     |
 
 `#ui` uses the command's own `out` and `err` when dry-cli has set them (`Dry::CLI#call(out:, err:)`), and `$stdout` and `$stderr` otherwise. Every write flushes, so the two streams stay in order when both are piped to the same place.
 
@@ -245,18 +246,33 @@ Each stream is judged on its own:
 
 `Console.new(color:, animate:, width:)` overrides detection. Without animation:
 
-| Widget                | Plain output                                                                                       |
-| --------------------- | -------------------------------------------------------------------------------------------------- |
-| spinner               | `Label...` before the block, `✓ Label (1.2s)` or `✗ Label (1.2s)` after it                         |
-| progress              | `Label...` before, `✓ Label 1900/1900 (4.2s)` after, with the count reached                        |
-| tasks                 | each line printed once final: a group when it starts, a task when it ends, skipped ones at the end |
-| prompts               | the question on `err`, one line read from input                                                    |
-| boxes, tables, status | unchanged apart from colour                                                                        |
+| Widget                | Plain output                                                                                                                                                                     |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| spinner               | `Label...` before the block, `✓ Label (1.2s)` or `✗ Label (1.2s)` after it; a `Line`'s detail is never printed, a `Line#fail` reason follows the label: `✗ Label: reason (1.2s)` |
+| progress              | `Label...` before, `✓ Label 1900/1900 (4.2s)` after, with the count reached                                                                                                      |
+| tasks                 | each line printed once final: a group when it starts, a task when it ends, skipped ones at the end                                                                               |
+| prompts               | the question on `err`, one line read from input                                                                                                                                  |
+| boxes, tables, status | unchanged apart from colour                                                                                                                                                      |
+| popup                 | the same box `ui.box` draws, on `err`, where the output scrolls rather than over it                                                                                              |
 
 ### Spinners and progress bars
 
 Both run a block, return what it returns, and re-raise what it raises after marking the outcome `✗`. The elapsed time comes from a monotonic clock. `ui.progress` yields a handle with `advance(step = 1)`, `current` and `total`; progress is clamped to `0..total`, and `total: 0` is allowed.
 
+`ui.spinner` yields a `Dry::CLI::UI::Line`, the same handle every task in a tree is given:
+
+| Method          | Effect                                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| `detail = text` | Text after the label while the work runs, redrawn in place when animated; kept, never printed, otherwise |
+| `detail`        | The current text, `""` for none                                                                          |
+| `fail(reason)`  | Ends the work as `✗ label: reason` when the block returns, without raising; the reason is optional       |
+| `failed?`       | Whether `fail` was called                                                                                |
+| `reason`        | What `fail` was given                                                                                    |
+
+Every method may be called from any thread, which is how work that reports from a reader thread (a child process's output, say) updates its line. A block that ignores the line works as before, and so does a lambda that takes no arguments. The detail is never printed without animation because it can change many times a second, and a log of every change is not what a pipe asked for.
+
+A spinner whose block calls `fail` still returns the block's value. That is the difference from raising: the work finished and has a result, and the result is that it did not succeed.
+
 ### Task trees
 
 The block declares the tree; nothing runs until it returns. Knowing the whole shape first is what lets the tree draw `├─` and `└─` correctly before the first task starts.
@@ -276,12 +292,23 @@ ui.tasks("Deploy") do |t|
 end
 ```
 
-- Tasks run in order. A group declared `concurrent: true`, or `ui.tasks(concurrent: true)` at the top level, runs its tasks at the same time on `concurrent-ruby` futures.
+- Tasks run in order. A group declared `concurrent: true`, or `ui.tasks(concurrent: true)` at the top level, runs its tasks at the same time on `concurrent-ruby` futures. `concurrent: 3` runs at most three at once, taking tasks in declaration order as each finishes. Anything but `true`, `false` or a positive Integer raises `ArgumentError`.
+- Each task is given a `Line`. Its detail is drawn after the task's name while it runs, on a live tree only. A task that calls `fail` is marked `✗ name: reason`, every group above it ends `✗`, and the rest of the tree runs on: nothing is skipped and nothing is raised.
 - States are pending `○`, running `▸`, done `✓`, failed `✗` and skipped `–`. On an animated terminal a running task shows a turning spinner instead of `▸`, so a concurrent group is a multi-spinner.
-- When a task raises, it and its enclosing groups are marked failed, tasks already running beside it finish, tasks not yet started are marked skipped, and the first error is re-raised.
+- When a task raises, it and its enclosing groups are marked failed, tasks already running beside it finish, tasks not yet started are marked skipped, and the first error is re-raised. Under a concurrency limit, no further task is started once one has raised.
 - The live tree is redrawn in place with cursor movement, which cannot reach above the top of the screen. A tree with as many rows as the screen, or more, is printed line by line instead.
 - Task blocks should not write to the terminal while a live tree is drawn; the next redraw overwrites their output.
 
+### Popups
+
+`ui.popup(*paragraphs, title:, width:)` draws a box on `err` over whatever the terminal is showing, such as a key reference over a running spinner. On an animated terminal it is:
+
+- as wide as its widest line or its title needs, never narrower than 20 columns and never wider than the box width (`width:`, then the console's `box_width`, then the terminal less the margin);
+- centred on the screen by absolute cursor positioning;
+- wrapped in a cursor save and restore, with no trailing newline, so it neither moves the cursor nor scrolls the screen.
+
+Whatever redraws that part of the screen next draws over it, which is all the dismissal a popup needs. Without animation the output cannot be drawn over, so it is the box `ui.box` draws, on `err`.
+
 ### Tables
 
 `ui.table(rows, header:)` renders with box-drawing borders and a bold header. Tables are data, so they are never narrowed, truncated or rotated to fit the screen. TTY::Table otherwise measures the screen, prints a warning on STDERR, and turns a wide table on its side.
@@ -308,7 +335,9 @@ With a fixed width, TTY::Box 0.7 wraps text but sizes the box from the unwrapped
 - [x] `#ui` writes to the streams dry-cli was called with.
 - [x] `debug`, `info`, `success`, `warn`, `error` and `fatal` draw white single-line boxes titled by level, wrapped, as wide as configured or the terminal less a margin, and never lose text.
 - [x] `spinner`, `progress` and `tasks` return their block's value, re-raise its error, and leave an outcome line with the elapsed time; progress shows percent, count and ETA.
-- [x] Task trees nest, run groups concurrently when asked, and mark failed and skipped tasks.
+- [x] Task trees nest, run groups concurrently when asked, at most as many at once as asked, and mark failed and skipped tasks.
+- [x] Spinner and task blocks get a thread-safe `Line` whose detail is drawn while they run, and which can fail them without raising.
+- [x] `popup` draws a content-sized, centred box that leaves the cursor where it was, and a plain box without animation.
 - [x] Tables render rows and a header without truncation.
 - [x] Prompts work interactively and from piped input, and never block on an exhausted input.
 - [x] Output that is not a TTY, or runs under `TERM=dumb`, contains no escape sequences; `NO_COLOR` removes colour.
@@ -317,6 +346,6 @@ With a fixed width, TTY::Box 0.7 wraps text but sizes the box from the unwrapped
 
 ## Out of scope
 
-- Full-screen applications, alternate screen buffers, and a public cursor-positioning API. TTY::Cursor and TTY::Screen are used internally only.
+- Full-screen applications, alternate screen buffers, and a public cursor-positioning API. TTY::Cursor and TTY::Screen are used internally only; `popup` positions itself, and takes no coordinates.
 - Keyboard input beyond prompts.
 - Renderers other than the TTY toolkit. The widget boundary allows one later.

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

@@ -93,6 +93,23 @@ module Dry
           nil
         end
 
+        # A box drawn over whatever is on the screen, on `err`. On an animated
+        # terminal it is as wide as its text needs, up to the box width, and
+        # centred, and the cursor is left where it was. Otherwise it is the
+        # same box {#box} draws.
+        #
+        # @example
+        #   ui.popup("h  help", "q  quit", title: "Keys")
+        #
+        # @param paragraphs [Array<#to_s>] each one wrapped on its own, separated by a blank line
+        # @param title [String, nil]
+        # @param width [Integer, nil] the widest it may be, overriding the console's box width
+        # @return [nil]
+        def popup(*paragraphs, title: nil, width: nil)
+          err.print(Widgets::Box.new(err, width: width || box_width).popup(paragraphs, title: title))
+          nil
+        end
+
         # One line with a coloured glyph, going to the level's stream.
         #
         # @example
@@ -109,10 +126,17 @@ module Dry
         end
 
         # Runs a block under a spinner and leaves `✓ label (1.2s)` behind, or
-        # `✗ label` when the block raises.
+        # `✗ label` when the block raises. The block is given a {Line}: its
+        # detail is drawn after the label while the spinner turns, and
+        # {Line#fail} leaves `✗ label: reason` without raising.
+        #
+        # @example
+        #   ui.spinner("Importing") do |line|
+        #     rules.each { |rule| line.detail = rule.name }
+        #   end
         #
         # @param label [String]
-        # @yield the work
+        # @yieldparam line [Line] reports on the work while it runs
         # @return [Object] whatever the block returns
         # @raise [ArgumentError] without a block
         def spinner(label, &)
@@ -143,11 +167,17 @@ module Dry
         #     t.task("images") { fetch(:images) }
         #   end
         #
+        # @example At most two at a time, each saying what it is doing
+        #   ui.tasks("Fetching", concurrent: 2) do |t|
+        #     assets.each { |asset| t.task(asset.name) { |line| fetch(asset) { |pct| line.detail = "#{pct}%" } } }
+        #   end
+        #
         # @param title [String, nil]
-        # @param concurrent [Boolean] run the top-level tasks at the same time
+        # @param concurrent [Boolean, Integer] run the top-level tasks at the
+        #   same time: all of them, or at most this many
         # @yieldparam tasks [Widgets::Tasks::Builder] declares `task`s and `group`s
         # @return [nil]
-        # @raise [ArgumentError] without a block
+        # @raise [ArgumentError] without a block, or with an invalid concurrent
         def tasks(title = nil, concurrent: false, &)
           raise ArgumentError, "tasks needs a block" unless block_given?
 

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # What a spinner or a task gives its block, so the work can report on
+      # itself while it runs.
+      #
+      # `detail` is shown after the label while the work runs, and redrawn in
+      # place on an animated terminal. Without animation it is kept and never
+      # printed, since it may change many times a second.
+      #
+      # `fail` ends the work as a failure without raising: the outcome line
+      # reads `✗ label: reason (1.2s)`, and the block's value is still
+      # returned. Every method may be called from any thread.
+      #
+      # @example
+      #   ui.spinner("Importing") do |line|
+      #     rules.each { |rule| line.detail = rule.name }
+      #     line.fail("3 rules skipped") if skipped.any?
+      #   end
+      class Line
+        # @yieldparam detail [String] called whenever the detail changes, by
+        #   the widget that draws the line
+        def initialize(&on_change)
+          @on_change = on_change
+          @lock = Mutex.new
+          @detail = ""
+          @failed = false
+          @reason = nil
+        end
+
+        # Calls a block with a line, or without one when the block is a
+        # lambda that takes no arguments and would reject it.
+        #
+        # @param job [Proc]
+        # @param line [Line]
+        # @return [Object] whatever the block returns
+        def self.call(job, line)
+          job.lambda? && job.arity.zero? ? job.call : job.call(line)
+        end
+
+        # @return [String] the text shown after the label, empty for none
+        def detail = lock.synchronize { @detail }
+
+        # @param text [#to_s, nil] the text to show after the label; nil for none
+        def detail=(text)
+          text = text.to_s
+          lock.synchronize { @detail = text }
+          on_change&.call(text)
+        end
+
+        # Ends the work as a failure when the block returns, without raising.
+        #
+        # @param reason [#to_s, nil] shown after the label
+        # @return [self]
+        def fail(reason = nil)
+          lock.synchronize do
+            @failed = true
+            @reason = reason&.to_s
+          end
+          self
+        end
+
+        # @return [Boolean] whether {#fail} was called
+        def failed? = lock.synchronize { @failed }
+
+        # @return [String, nil] what {#fail} was given
+        def reason = lock.synchronize { @reason }
+
+        # The label with the failure's reason after it, when there is one.
+        #
+        # @param label [String]
+        # @return [String]
+        def summary(label)
+          text = reason
+          failed? && !text.to_s.empty? ? "#{label}: #{text}" : label
+        end
+
+        private
+
+        # @return [Proc, nil]
+        attr_reader :on_change
+
+        # @return [Mutex]
+        attr_reader :lock
+      end
+    end
+  end
+end

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

@@ -11,7 +11,7 @@ module Dry
     # Presentation helpers for Dry::CLI commands.
     module UI
       # The gem version.
-      VERSION = "0.1.0"
+      VERSION = "0.3.0"
     end
   end
 end

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

@@ -12,7 +12,7 @@ module Dry
         #
         # The box is as wide as it is told to be: a fixed number of columns,
         # or the whole terminal less {MARGIN}. It never grows wider than the
-        # terminal.
+        # terminal. A {#popup} is only as wide as its text, up to that width.
         class Box
           # Columns left free on the right when the box fills the terminal.
           MARGIN = 2
@@ -49,6 +49,33 @@ module Dry
             )
           end
 
+          # Renders a box over whatever is on the screen: as wide as its text
+          # and title need, no wider than {#render}'s box, and centred. The
+          # cursor is saved before and restored after, so drawing it neither
+          # moves the cursor nor scrolls. Without animation it is the same box
+          # {#render} draws.
+          #
+          # @param paragraphs [Array<#to_s>]
+          # @param title [String, nil]
+          # @return [String]
+          def popup(paragraphs, title: nil)
+            return render(paragraphs, title: title) unless terminal.animated?
+
+            text = wrap(paragraphs)
+            width = popup_width(text, title)
+            height = text.lines.size + 2 + (PADDING[0] * 2)
+            frame = TTY::Box.frame(
+              text,
+              top: [(terminal.height - height) / 2, 0].max,
+              left: [(terminal.width - width) / 2, 0].max,
+              width: width, height: height, padding: PADDING, border: :light,
+              title: title ? { top_left: heading(title, nil) } : {},
+              style: { border: { fg: :white } },
+              enable_color: terminal.color?
+            )
+            "#{terminal.cursor.save}#{frame}#{terminal.cursor.restore}"
+          end
+
           private
 
           # @return [Terminal]
@@ -68,6 +95,18 @@ module Dry
             paragraphs.map { |p| Strings::Wrap.wrap(p.to_s, text_width).gsub(/[ \t]+$/, "") }.join("\n\n")
           end
 
+          # Columns a popup needs: its widest line or its title, whichever is
+          # wider, with the border and padding around it.
+          #
+          # @param text [String] already wrapped
+          # @param title [String, nil]
+          # @return [Integer]
+          def popup_width(text, title)
+            content = text.lines.map { |line| Unicode::DisplayWidth.of(Strings::ANSI.sanitize(line.chomp)) }
+            content << (Unicode::DisplayWidth.of(title) + 3) if title
+            (content.max.to_i + 2 + (PADDING[1] * 2)).clamp(MIN_WIDTH, box_width)
+          end
+
           # @return [Integer]
           def box_width
             available = terminal.width - MARGIN

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

@@ -11,6 +11,10 @@ module Dry
         # On an animated terminal the spinner turns until the block returns
         # and is replaced by the outcome line. Anywhere else it prints
         # `Label...` before the block and the outcome line after it.
+        #
+        # The block is given a {Line}. Its detail is drawn after the label
+        # while the spinner turns, and {Line#fail} ends it as a failure
+        # without raising.
         class Spinner
           # @param terminal [Terminal]
           # @param clock [#call] returns monotonic seconds
@@ -22,19 +26,21 @@ module Dry
           # Runs the block under a spinner.
           #
           # @param label [String]
-          # @yield the work to show progress for
+          # @yieldparam line [Line] reports on the work while it runs
           # @return [Object] whatever the block returns
           # @raise [Exception] whatever the block raises, after marking the spinner failed
-          def run(label)
+          def run(label, &job)
+            spinner = nil
+            line = Line.new { |text| spinner&.update(detail: text.empty? ? "" : " #{text}") }
             started = clock.call
             spinner = start(label)
             ok = false
-            result = yield
-            ok = true
+            result = Line.call(job, line)
+            ok = !line.failed?
             result
           ensure
             spinner&.stop
-            terminal.puts(Outcome.line(terminal, ok ? :done : :failed, label, clock.call - started))
+            terminal.puts(Outcome.line(terminal, ok ? :done : :failed, line.summary(label), clock.call - started))
           end
 
           private
@@ -53,7 +59,9 @@ module Dry
               return
             end
 
-            TTY::Spinner.new(":spinner #{label}", output: terminal.io, format: :dots, hide_cursor: true, clear: true)
+            TTY::Spinner.new(":spinner #{label}:detail", output: terminal.io, format: :dots, hide_cursor: true,
+                                                         clear: true)
+                        .tap { |spinner| spinner.update(detail: "") }
                         .tap(&:auto_spin)
           end
         end

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

@@ -19,6 +19,11 @@ module Dry
         # tree is taller than the screen, each line is printed once it has
         # something final to say.
         #
+        # Every task is given a {Line}. Its detail is drawn after the task's
+        # name while it runs, on an animated terminal. A task that calls
+        # {Line#fail} is marked failed with its reason, as is every group above
+        # it, and the rest of the tree runs on.
+        #
         # When a task raises, it and every group above it are marked failed,
         # tasks already running beside it finish, everything that had not
         # started is marked skipped, and the error is re-raised.
@@ -26,8 +31,8 @@ module Dry
         # @example
         #   ui.tasks("Deploy") do |t|
         #     t.task("Build assets") { build }
-        #     t.group("Migrate", concurrent: true) do |g|
-        #       g.task("users") { migrate(:users) }
+        #     t.group("Migrate", concurrent: 2) do |g|
+        #       g.task("users") { |line| migrate(:users) { |table| line.detail = table } }
         #       g.task("orders") { migrate(:orders) }
         #     end
         #   end
@@ -38,11 +43,24 @@ module Dry
           # Seconds between spinner frames.
           INTERVAL = 0.1
 
+          # Checks a `concurrent:` setting.
+          #
+          # @param value [Boolean, Integer] true for all at once, false for one
+          #   at a time, or the most that may run at once
+          # @return [Boolean, Integer] the value
+          # @raise [ArgumentError] for anything else
+          def self.concurrency(value)
+            return value if [true, false].include?(value) || (value.is_a?(Integer) && value.positive?)
+
+            raise ArgumentError, "concurrent must be true, false or a positive Integer, got #{value.inspect}"
+          end
+
           # One task, or a group of them.
           class Node
             # @param name [String]
             # @param job [Proc, nil] the work; nil for a group
-            # @param concurrent [Boolean] whether a group runs its tasks at once
+            # @param concurrent [Boolean, Integer] whether, or how many of, a
+            #   group's tasks run at once
             def initialize(name, job = nil, concurrent: false)
               @name = name
               @job = job
@@ -50,6 +68,7 @@ module Dry
               @children = []
               @state = :pending
               @seconds = nil
+              @line = Line.new
             end
 
             # @return [String]
@@ -58,9 +77,11 @@ module Dry
             # @return [Proc, nil]
             attr_reader :job
 
-            # @return [Boolean]
+            # @return [Boolean, Integer]
             attr_reader :concurrent
-            alias concurrent? concurrent
+
+            # @return [Line] what the task's work reports through
+            attr_reader :line
 
             # @return [Array<Node>]
             attr_reader :children
@@ -73,6 +94,17 @@ module Dry
 
             # @return [Boolean] whether this node holds tasks rather than work
             def group? = job.nil?
+
+            # Whether the work reported a failure without raising: through its
+            # line, or for a group, through any of its children.
+            #
+            # @return [Boolean]
+            def failed?
+              group? ? children.any? { |child| child.state == :failed } : line.failed?
+            end
+
+            # @return [String] the name, with the reason once the work has failed
+            def label = line.summary(name)
           end
 
           # What the declaration block is given.
@@ -85,7 +117,7 @@ module Dry
             # Declares a task.
             #
             # @param name [String]
-            # @yield the work
+            # @yieldparam line [Line] reports on the work while it runs
             # @return [self]
             # @raise [ArgumentError] without a block
             def task(name, &job)
@@ -98,14 +130,15 @@ module Dry
             # Declares a group of tasks.
             #
             # @param name [String]
-            # @param concurrent [Boolean] run the group's tasks at the same time
+            # @param concurrent [Boolean, Integer] run the group's tasks at the
+            #   same time: all of them, or at most this many
             # @yieldparam group [Builder] declares the tasks inside the group
             # @return [self]
-            # @raise [ArgumentError] without a block
+            # @raise [ArgumentError] without a block, or with an invalid concurrent
             def group(name, concurrent: false)
               raise ArgumentError, "group #{name.inspect} needs a block" unless block_given?
 
-              node = Node.new(name, concurrent: concurrent)
+              node = Node.new(name, concurrent: Tasks.concurrency(concurrent))
               nodes << node
               yield Builder.new(node.children)
               self
@@ -131,10 +164,13 @@ module Dry
           # Declares the tree with the block, then runs it.
           #
           # @param title [String, nil] a heading printed above the tree
-          # @param concurrent [Boolean] run the top-level tasks at the same time
+          # @param concurrent [Boolean, Integer] run the top-level tasks at the
+          #   same time: all of them, or at most this many
           # @yieldparam tasks [Builder]
           # @return [nil]
+          # @raise [ArgumentError] with an invalid concurrent
           def run(title = nil, concurrent: false)
+            Tasks.concurrency(concurrent)
             yield Builder.new(roots)
             terminal.puts(terminal.pastel.bold(title)) if title
             ticker = start_ticker
@@ -166,25 +202,59 @@ module Dry
           attr_accessor :frame
 
           # @param nodes [Array<Node>]
-          # @param concurrent [Boolean]
+          # @param concurrent [Boolean, Integer]
           # @return [void]
           def run_all(nodes, concurrent)
             return nodes.each { |node| execute(node) } unless concurrent
 
-            futures = nodes.map { |node| Concurrent::Promises.future(node) { |each| execute(each) } }
+            futures = concurrent == true ? all_at_once(nodes) : at_most(concurrent, nodes)
             futures.each(&:wait)
             failed = futures.find(&:rejected?)
             raise failed.reason if failed
           end
 
+          # @param nodes [Array<Node>]
+          # @return [Array<Concurrent::Promises::Future>] one per node
+          def all_at_once(nodes)
+            nodes.map { |node| Concurrent::Promises.future(node) { |each| execute(each) } }
+          end
+
+          # Workers that take nodes off a queue until it is empty, or until
+          # one of them raises. A node no worker took stays pending, and is
+          # marked skipped once the tree ends.
+          #
+          # @param limit [Integer]
+          # @param nodes [Array<Node>]
+          # @return [Array<Concurrent::Promises::Future>] one per worker
+          def at_most(limit, nodes)
+            queue = Queue.new
+            nodes.each { |node| queue << node }
+            queue.close
+            stop = Concurrent::AtomicBoolean.new
+            Array.new([limit, nodes.size].min) { Concurrent::Promises.future { work(queue, stop) } }
+          end
+
+          # @param queue [Queue] closed, so `pop` returns nil once it is empty
+          # @param stop [Concurrent::AtomicBoolean] set once any worker raises
+          # @return [void]
+          def work(queue, stop)
+            ok = false
+            while (node = queue.pop) && stop.false?
+              execute(node)
+            end
+            ok = true
+          ensure
+            stop.make_true unless ok
+          end
+
           # @param node [Node]
           # @return [void]
           def execute(node)
             started = clock.call
             change(node, :running)
             ok = false
-            node.group? ? run_all(node.children, node.concurrent?) : node.job.call
-            ok = true
+            node.group? ? run_all(node.children, node.concurrent) : Line.call(node.job, node.line)
+            ok = !node.failed?
           ensure
             change(node, ok ? :done : :failed, seconds: clock.call - started)
           end
@@ -262,7 +332,19 @@ module Dry
             glyph, color = Theme::STATES.fetch(node.state)
             glyph = FRAMES[frame % FRAMES.size] if node.state == :running && live?
             elapsed = " #{pastel.bright_black("(#{Duration.format(node.seconds)})")}" if node.seconds
-            "#{pastel.bright_black(rows.fetch(node))}#{pastel.decorate(glyph, color)} #{node.name}#{elapsed}"
+            "#{pastel.bright_black(rows.fetch(node))}#{pastel.decorate(glyph, color)} #{text(node)}#{elapsed}"
+          end
+
+          # What follows the glyph: the name, then the detail while the task
+          # runs, or the reason once it has failed.
+          #
+          # @param node [Node]
+          # @return [String]
+          def text(node)
+            detail = node.line.detail
+            return node.label unless node.state == :running && !detail.empty?
+
+            "#{node.name} #{detail}"
           end
 
           # Every node in display order, with the tree branch drawn before it.

data/lib/dry/cli/ui.rb

@@ -33,6 +33,7 @@ module Dry
 
       autoload :Console, File.expand_path("ui/console", __dir__)
       autoload :Duration, File.expand_path("ui/duration", __dir__)
+      autoload :Line, File.expand_path("ui/line", __dir__)
       autoload :Terminal, File.expand_path("ui/terminal", __dir__)
       autoload :Theme, File.expand_path("ui/theme", __dir__)
       autoload :Widgets, File.expand_path("ui/widgets", __dir__)

data/sig/dry/cli/ui.rbs

@@ -11,6 +11,17 @@ module Dry
 
       def ui: () -> Console
 
+      class Line
+        def self.call: [T] (^(Line) -> T job, Line line) -> T
+        def initialize: () ?{ (String detail) -> void } -> void
+        def detail: () -> String
+        def detail=: (_ToS? text) -> void
+        def fail: (?_ToS? reason) -> self
+        def failed?: () -> bool
+        def reason: () -> String?
+        def summary: (String label) -> String
+      end
+
       class Console
         def debug: (*_ToS paragraphs, ?width: Integer?) -> nil
         def info: (*_ToS paragraphs, ?width: Integer?) -> nil
@@ -20,9 +31,10 @@ module Dry
         def fatal: (*_ToS paragraphs, ?width: Integer?) -> nil
         def box: (*_ToS paragraphs, ?title: String?, ?level: Symbol?, ?width: Integer?) -> nil
         def status: (*_ToS words, ?level: Symbol) -> nil
-        def spinner: [T] (String label) { () -> T } -> T
+        def popup: (*_ToS paragraphs, ?title: String?, ?width: Integer?) -> nil
+        def spinner: [T] (String label) { (Line line) -> T } -> T
         def progress: [T] (String label, total: Integer) { (untyped progress) -> T } -> T
-        def tasks: (?String? title, ?concurrent: bool) { (untyped tasks) -> void } -> nil
+        def tasks: (?String? title, ?concurrent: (bool | Integer)) { (untyped tasks) -> void } -> nil
         def table: (Array[Array[_ToS]] rows, ?header: Array[_ToS]?) -> nil
         def prompt: (String question, ?default: untyped, ?choices: (Array[String] | Hash[String, untyped])?) -> untyped
         def confirm: (String question, ?default: bool) -> bool

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dry-cli-ui
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -181,6 +181,7 @@ files:
 - lib/dry/cli/ui.rb
 - lib/dry/cli/ui/console.rb
 - lib/dry/cli/ui/duration.rb
+- lib/dry/cli/ui/line.rb
 - lib/dry/cli/ui/terminal.rb
 - lib/dry/cli/ui/theme.rb
 - lib/dry/cli/ui/version.rb