dry-cli-ui 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555aba61a68d2f480ae76f61d6851786e83e46afd0855c276e5eba01fe0d8dc8
-  data.tar.gz: 584e4a3268d121ecdb3e85f3ead9afef643e5c1a086b0c4702b418f550c1b8d7
+  metadata.gz: 71d205edc6e78bba4bffbeebe70fc24ba7c992cd08a4f9856f1d9c1e4fd20ae4
+  data.tar.gz: 4070740b8964f52e87b33f2094cc5638d4323eeaad6882723c3593db5d1b77f3
 SHA512:
-  metadata.gz: 86e23d86e7eca50b4a7ed51bf7dc6d4a784c4711f7ddfc5c10fbc90ebc53d44647da0eaea7ea00296e7228ba73c08920a1dd08ff6c435cbd4d10f2b3266d4c37
-  data.tar.gz: 3b73f7e064fd7dfd35540a034ef1e721e4aed3e368d4d474ffa8ccc283fd4c06d4913bba72343b3760e8ecaf9ec8a64645c4d97f6c160bfb26cf7c7cb5021f30
+  metadata.gz: e053b8d527886759bbc2c72a8825d3e99ff0b5abe54211acc798ceab0b15238d0a0bd2442717d851d3c713e96117290100b8bd7e77a78a3f333cc3216b2d3dda
+  data.tar.gz: feeafcdddf3d3f620acf6e45b2fb77ef0cbc00b9bf1028b515f0d7d8a6c56a72a34a7c86e1e928320cb5755056ad72e3edafeaa96780b5dcdae023bb98d10b8b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+- `ui.multi_spinner(title, concurrent: true)` runs several jobs at once, each under a spinner of its own, beneath a headline spinner. `ui.multi_progress(title, concurrent: true)` does the same with a progress bar per job and a headline bar that counts them all. The block declares the jobs with `m.spinner(label)` or `m.progress(label, total:)`; they run once it returns, all at once or at most `concurrent:` at a time, and the call returns what each job returned. Waiting jobs show `[ ]`, a job that raises is marked `[𝘅]`, jobs not yet started are skipped, and the first error is re-raised.
+- Task trees and the multi widgets mark every row in brackets: `[ ]` while it waits and a turning `[⠏]` while it runs, both bold yellow, then a green `[✓]`, a red `[𝘅]`, or a yellow `[—]` for work that was skipped. Outcome lines use the same glyphs, so a failed spinner now ends `𝘅 Loading (0.5s)`.
+- `Dry::CLI::UI.configure` sets `spinner_format` (a TTY::Spinner format name, or `{ interval:, frames: }`), `bar_format` (a TTY::ProgressBar bar format name, or `{ complete:, incomplete: }`), `bar_color` and `bar_background` (Pastel styles, or nil) for every spinner and bar. Spinners default to `:dots`. Bars now draw a green `◼` for each finished part on a gray track, between brackets, rather than `███░░░`. `Console.new` takes `config:` for a configuration of its own.
+- `ui.status_bar(title, hints:)` keeps a status line at the bottom of the screen while its block runs: what started last, how many things are running, done and failed, overall progress, elapsed time and hints. Every widget inside the block reports to it. It sets no scroll region, so scrollback stays intact, and does nothing when `err` is not animated.
+- `ui.multi_progress` right-aligns every count, so `8/503` and `1/8` end in the same column.
+
 ## [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.

data/README.md

@@ -51,7 +51,7 @@ When the output is piped, and the import fails part way:
 Loading tax rules...
 ✓ Loading tax rules (0.3s)
 Importing rules...
-✗ Importing rules 1482/1900 (4.1s)
+𝘅 Importing rules 1482/1900 (4.1s)
 ┌─ Error ──────────────────────────────────────────────────┐
 │                                                          │
 │  Import failed                                           │
@@ -62,7 +62,7 @@ Importing rules...
 └──────────────────────────────────────────────────────────┘
 ```
 
-On a terminal the spinner turns and the bar fills in place, with percent, count and ETA, and each is replaced by the same `✓` or `✗` line when its block ends.
+On a terminal the spinner turns and the bar fills in place, with percent, count and ETA, and each is replaced by the same `✓` or `𝘅` line when its block ends.
 
 Include the module once in a base class and every command has `ui`. Including it loads nothing: the TTY gems load the first time `ui` is used.
 
@@ -107,7 +107,7 @@ ui.status "Disk nearly full", level: :warn               # ⚠ Disk nearly full
 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.
+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:
 
@@ -118,7 +118,7 @@ ui.spinner("Importing rules") do |line|
 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.
+`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
 
@@ -131,7 +131,126 @@ ui.progress("Importing rules", total: rules.size) do |bar|
 end
 ```
 
-The bar shows percent, `current/total` and ETA, and ends with `✓ Importing rules 1900/1900 (4.2s)`.
+The bar shows percent, `current/total` and ETA, `Importing rules [◼◼◼◼◼◼    ] 61%  1159/1900  ETA 2.7s`, and ends with `✓ Importing rules 1900/1900 (4.2s)`. On a terminal the `◼`s are green and the whole bar sits on a gray background; see [Configuration](#configuration) to change either.
+
+### Several spinners at once
+
+```ruby
+ui.multi_spinner("Fetching", concurrent: 2) do |m|
+  m.spinner("fonts") { fetch(:fonts) }
+  m.spinner("images") do |line|
+    fetch(:images) { |done, all| line.detail = "#{done} of #{all}" }
+  end
+  m.spinner("video") { fetch(:video) }
+end
+```
+
+The block declares the jobs; they run once it returns, all at once by default, or at most `concurrent: 2` at a time. It returns what each job returned, in declaration order. While they run, every job has a row of its own under a headline spinner, and a job still waiting shows `[ ]`:
+
+```text
+[⠹] Fetching
+├─ [⠹] fonts
+├─ [⠹] images 12 of 40
+└─ [ ] video
+```
+
+Once they finish, the headline ends `✓`, or `𝘅` when any job failed:
+
+```text
+[𝘅] Fetching (0.5s)
+├─ [✓] fonts (0.3s)
+├─ [𝘅] images: 2 timed out (0.3s)
+└─ [✓] video (0.2s)
+```
+
+Each job is given a `Line`, as a single spinner's block is. When a job raises, jobs already running finish, jobs not yet started are marked skipped (`[—]`), and the error is re-raised. Piped, it prints `Fetching...`, then each job's outcome as it ends, then the headline's.
+
+### Several progress bars at once
+
+```ruby
+ui.multi_progress("Downloading") do |m|
+  files.each do |file|
+    m.progress(file.name, total: file.size) do |bar|
+      download(file) { |bytes| bar.advance(bytes) }
+    end
+  end
+end
+```
+
+The same shape as `multi_spinner`, with a bar per job and a headline bar that counts them all. Bars start and end in the same columns, and counts are right-aligned:
+
+```text
+[⠋] Downloading      [◼◼◼◼             ]  27%   66/240  ETA 2.1s
+├─ [⠋] fonts.zip     [◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼ ]  95%    38/40  ETA 0.1s
+├─ [⠋] images.tar.gz [◼◼◼              ]  23%   28/120  ETA 2.4s
+└─ [ ] video.mp4
+```
+
+Each job is given the same handle as `ui.progress`, with `advance(step = 1)`, `current` and `total`. A finished job's row reads `[✓] fonts.zip 40/40 (0.1s)`, and the headline's `[✓] Downloading 240/240 (0.3s)`.
+
+### Example: fetching many URLs
+
+With `multi_spinner`, each URL gets a spinner, and the call returns every page in the same order as `urls`. Nothing writes to a shared file from several threads:
+
+```ruby
+bodies = ui.multi_spinner("Fetching #{urls.size} URLs", concurrent: 8) do |m|
+  urls.each { |url| m.spinner(url) { fetch(url) } }
+end
+
+File.write("urls.txt", bodies.join("\n"))
+```
+
+With `multi_progress`, each URL gets a bar that fills one byte at a time as the body arrives. A bar's `total` is fixed when it is declared, so a `HEAD` request asks each URL for its size first:
+
+```ruby
+found = urls.filter_map do |url|
+  [url, content_length(url)]
+rescue StandardError => e
+  ui.status "#{url}: #{e.message}", level: :warn
+  nil
+end
+
+bodies = ui.multi_progress("Fetching #{found.size} URLs", concurrent: 8) do |m|
+  found.each do |url, size|
+    m.progress(url, total: size || 1) do |bar|
+      body = download(url) { |bytes| bytes.times { bar.advance } if size }
+      bar.advance unless size # no Content-Length: done in one step
+      body
+    end
+  end
+end
+
+File.write("urls.txt", bodies.join("\n"))
+```
+
+The two helpers, with `Net::HTTP`:
+
+```ruby
+require "net/http"
+
+def content_length(url)
+  uri = URI(url)
+  Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+    http.head(uri.request_uri).content_length # nil when the server does not say
+  end
+end
+
+def download(url)
+  uri = URI(url)
+  body = +""
+  Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+    http.request_get(uri.request_uri) do |response|
+      response.read_body do |chunk|
+        body << chunk
+        yield chunk.bytesize
+      end
+    end
+  end
+  body
+end
+```
+
+In both, at most eight requests run at once and the rest wait as `[ ]` rows. The headline counts every URL, and in `multi_progress` every byte. A server that sends no `Content-Length` gets a bar of one unit, which sits at 0% and fills when its download ends. These helpers are kept short: a real one follows redirects, and sends `Accept-Encoding: identity` so the bytes counted match `Content-Length`. With more URLs than the screen has rows, each finished URL prints one line instead.
 
 ### Task trees
 
@@ -156,19 +275,19 @@ On a terminal, once it finishes:
 
 ```text
 Deploy
-├─ ✓ Build assets (0.4s)
-├─ ✓ Migrate (0.3s)
-│  ├─ ✓ users (0.1s)
-│  └─ ✓ orders (0.2s)
-├─ ✓ Warm caches (0.5s)
-│  ├─ ✓ fonts (0.5s)
-│  └─ ✓ images (0.3s)
-└─ ✓ Restart (0.3s)
+├─ [✓] Build assets (0.4s)
+├─ [✓] Migrate (0.3s)
+│  ├─ [✓] users (0.1s)
+│  └─ [✓] orders (0.2s)
+├─ [✓] Warm caches (0.5s)
+│  ├─ [✓] fonts (0.5s)
+│  └─ [✓] images (0.3s)
+└─ [✓] 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, 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.
+While it runs, the tree redraws in place and every running task has its own spinner. Every row is marked in brackets, in bold yellow while it waits, `[ ]`, and while it runs, a turning `[⠏]`; then a green `[✓]` when it is done, a red `[𝘅]` when it failed, or a yellow `[—]` when it was skipped. 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:
+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|
@@ -182,6 +301,66 @@ ui.tasks("Fetching", concurrent: 4) do |t|
 end
 ```
 
+### Status bar
+
+```ruby
+ui.status_bar("deploy", hints: ["^C cancel"]) do
+  ui.spinner("Building assets") { build }
+  ui.multi_progress("Uploading", concurrent: 2) { |m| ... }
+  ui.tasks("Migrate") { |t| ... }
+end
+```
+
+While the block runs, the bottom of the screen shows how the whole command is doing, under a rule: what started last, how many things are running, done and failed, a bar over every progress bar so far, the elapsed time, and your hints at the right edge. Everything the widgets print scrolls above it, and it disappears when the block ends:
+
+```text
+✓ Building assets (0.2s)
+[⠙] Uploading    [◼◼◼◼◼◼◼◼◼◼◼◼◼◼                         ]  37%   49/132  ETA 0.3s
+├─ [✓] app.js 40/40 (0.2s)
+├─ [⠙] app.css   [◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼◼          ]  75%     9/12  ETA 0.1s
+└─ [⠙] fonts.zip [                                       ]   0%     0/80  ETA --
+──────────────────────────────────────────────────────────────────────────────────────────
+ ⠸ deploy · fonts.zip · 2 running · 2 done · [◼◼◼       ] 37% · 0.4s            ^C cancel
+```
+
+Nothing reports to it by hand: every `spinner`, `progress`, `multi_spinner`, `multi_progress` and task started inside the block does so on its own. Hints that do not fit are left out, and a status that does not fit is cut short with `…`.
+
+It sets no scroll region, so the scrollback keeps everything, and an interrupted command leaves nothing behind. Piped, or without animation, it just runs the block. Write through `ui` while it runs: a bare `puts` lands where the bar is, until the next `ui` call draws the bar again.
+
+### Putting it together
+
+```ruby
+class Deploy < Dry::CLI::Command
+  include Dry::CLI::UI
+
+  def call(**)
+    ui.status_bar("deploy", hints: ["^C cancel"]) do
+      assets = ui.spinner("Building assets") { build_assets }
+
+      ui.multi_progress("Uploading", concurrent: 3) do |m|
+        assets.each do |asset|
+          m.progress(asset.name, total: asset.bytesize) do |bar|
+            upload(asset) { |sent| bar.advance(sent) }
+          end
+        end
+      end
+
+      ui.multi_spinner("Warming caches") do |m|
+        regions.each do |region|
+          m.spinner(region) do |line|
+            warm(region) { |host| line.detail = host }
+          end
+        end
+      end
+    end
+
+    ui.success "Deployed #{assets.size} assets"
+  rescue => e
+    ui.error("Deploy failed", e.message)
+  end
+end
+```
+
 ### Tables
 
 ```ruby
@@ -218,9 +397,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`, `popup`, 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, their multi forms, task trees, the status bar, 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.
 
@@ -228,6 +407,28 @@ A stream that is not a terminal, or runs under `TERM=dumb`, gets no animation, n
 
 ## Configuration
 
+Spinners and bars look the same everywhere, and are set once for the whole process:
+
+```ruby
+Dry::CLI::UI.configure do
+  spinner_format :dots                                 # any TTY::Spinner format name
+  bar_format(complete: "◼", incomplete: " ")           # or any TTY::ProgressBar bar format name, such as :box
+  bar_color :green                                     # the finished part: any Pastel style, or nil
+  bar_background :on_bright_black                      # the whole bar: any Pastel style, or nil
+end
+```
+
+Those are the defaults: spinners turn through `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏` ten times a second, and bars draw a green `◼` for each finished part on a gray track. Without colour the track is blank, and the brackets still show where the bar ends. Every spinner reads the same format, including `multi_spinner`, task trees and the status bar, and every bar reads the same characters and colours. The formats also take a definition of your own:
+
+```ruby
+Dry::CLI::UI.configure do |config|
+  config.spinner_format = { interval: 8, frames: %w[◐ ◓ ◑ ◒] }   # frames per second, and the frames
+  config.bar_format = { complete: "#", incomplete: "." }
+end
+```
+
+An unknown name or a malformed definition raises `ArgumentError` when it is set.
+
 Override `ui` to configure the console:
 
 ```ruby

data/SPECIFICATION.md

@@ -63,7 +63,7 @@ Example output, piped, when the import fails part way:
 Loading tax rules...
 ✓ Loading tax rules (0.3s)
 Importing rules...
-✗ Importing rules 1482/1900 (4.1s)
+𝘅 Importing rules 1482/1900 (4.1s)
 ┌─ Error ──────────────────────────────────────────────────┐
 │                                                          │
 │  Import failed                                           │
@@ -89,8 +89,11 @@ ui.error(...)
 ui.fatal(...)
 
 ui.spinner(...)
+ui.multi_spinner(...)
 ui.progress(...)
+ui.multi_progress(...)
 ui.status(...)
+ui.status_bar(...)
 
 ui.box(...)
 ui.popup(...)
@@ -226,10 +229,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`, `popup`, `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`, `multi_spinner`, `progress`, `multi_progress`, `tasks`, `status_bar`, 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.
 
@@ -248,8 +251,10 @@ Each stream is judged on its own:
 
 | 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)` |
+| 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                                                                                                      |
+| multi_spinner         | `Title...` before, each job's outcome indented as it ends, skipped ones at the end, then the headline's outcome                                                                  |
+| multi_progress        | as multi_spinner, each outcome with its count: `✓ a.zip 40/40 (0.1s)`, and the headline with the total count                                                                     |
 | 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                                                                                                                                                      |
@@ -257,7 +262,7 @@ Each stream is judged on its own:
 
 ### 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.
+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:
 
@@ -265,7 +270,7 @@ Both run a block, return what it returns, and re-raise what it raises after mark
 | --------------- | -------------------------------------------------------------------------------------------------------- |
 | `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       |
+| `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                                                                                    |
 
@@ -273,6 +278,58 @@ Every method may be called from any thread, which is how work that reports from
 
 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.
 
+### Several at once: `multi_spinner` and `multi_progress`
+
+```ruby
+ui.multi_spinner("Fetching", concurrent: 2) do |m|
+  m.spinner("fonts") { fetch(:fonts) }
+  m.spinner("images") { |line| fetch(:images) { |n| line.detail = "#{n} of 40" } }
+end
+
+ui.multi_progress("Downloading") do |m|
+  files.each { |f| m.progress(f.name, total: f.size) { |bar| download(f) { |n| bar.advance(n) } } }
+end
+```
+
+- The block declares the jobs; nothing runs until it returns, so every row, including those of jobs waiting under a concurrency limit, is drawn before the first job starts. TTY::Spinner::Multi and TTY::ProgressBar::Multi give a row only to a job that has started and move the cursor relative to the last row drawn, which is why these widgets draw their rows themselves, as task trees do.
+- Jobs run all at once by default. `concurrent:` takes the same values as on `ui.tasks`, with the same meaning.
+- The call returns what each job returned, in declaration order, and `nil` for a job that never ran.
+- The headline turns while any job runs and ends `✓` when every job succeeded, `𝘅` otherwise. Every row, the headline's included, is marked in brackets as task rows are: `[ ]` while waiting, a turning `[⠏]` while running, then `[✓]`, `[𝘅]` or `[—]` with its elapsed time.
+- `multi_spinner` gives each job a `Line`; its detail follows the label while the job runs, and `fail` marks the job `𝘅 label: reason` without raising. `multi_progress` gives each job a `Widgets::Progress::Handle`; its row shows a bar, a percentage, a count and an ETA, and the headline's bar counts every job. Labels are padded so every bar starts and ends in the same columns.
+- When a job raises, jobs already running finish, jobs not yet started are marked skipped, and the first error is re-raised.
+- As with task trees, rows are redrawn in place only when they all fit on the screen; otherwise they print as without animation.
+
+### Configuration
+
+`Dry::CLI::UI.configure` sets how every spinner and bar in the process looks. A `Console` reads `Dry::CLI::UI.config` unless given `config:`.
+
+| Setting          | Takes                                                                        | Default                              | Draws                                |
+| ---------------- | ---------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------ |
+| `spinner_format` | A `TTY::Formats::FORMATS` name, or `{ interval:, frames: }`                  | `:dots`                              | `⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏`, 10 a second   |
+| `bar_format`     | A `TTY::ProgressBar::Formats::FORMATS` name, or `{ complete:, incomplete: }` | `{ complete: "◼", incomplete: " " }` | `[◼◼◼   ]`                           |
+| `bar_color`      | A Pastel style, or nil                                                       | `:green`                             | The finished part of every bar       |
+| `bar_background` | A Pastel style, or nil                                                       | `:on_bright_black`                   | The whole of every bar, a gray track |
+
+An unknown name, a malformed definition or a style Pastel does not know raises `ArgumentError` when it is set, not when a spinner first turns. Loading the configuration loads only the two format tables and Pastel, never a TTY widget. Colours follow the stream, as everything else does: without colour a bar is its characters alone, and the brackets show its extent.
+
+Every count in a `multi_progress` is right-aligned to the widest any row can show, the headline's total, so `8/503` and `1/8` end in the same column.
+
+### Status bar
+
+`ui.status_bar(title = nil, hints: [])` keeps two rows at the bottom of the screen while its block runs: a rule, then
+
+```text
+ ⠸ deploy · fonts.zip · 2 running · 2 done · [◼◼◼       ] 37% · 0.4s            ^C cancel
+```
+
+- The glyph turns while anything runs. Then come the title in bold, the label of the work started most recently, the counts of what is running, done and failed, a bar over every progress bar reported so far, finished or not, and the elapsed time. Hints are right-aligned when they fit and left out when they do not; a status too wide for the screen is truncated with `…`.
+- Every `spinner`, `progress`, `multi_spinner` and `multi_progress` job, and every task (not group) in a tree, reports its start and end to the bar through its `Terminal`. Commands supply only the title and the hints.
+- It is drawn at the bottom rather than pinned to the top. Pinning a top row needs a scroll region, terminals such as iTerm2 and tmux drop lines scrolled out of a region from the scrollback, and a crash that skips cleanup leaves the region set. A bottom line needs neither.
+- While it runs, the console's terminals write through a `StatusBar::Output`. Each write clears from the cursor to the end of the screen, writes, draws the rule and status line below, and moves the cursor back to where the write left it, in one write to the stream. The column is followed through the text, carriage returns, `CSI n G/C/D` and cursor save and restore, so a spinner redrawing its own line keeps working. The status line alone is redrawn ten times a second.
+- `Terminal#height` is two rows short while it runs, so live widgets fall back to plain output two rows sooner.
+- `out` writes through it too when `out` is animated, since both streams share the screen. Writes that bypass the console land where the bar is until the next write draws over them.
+- Without an animated `err`, and inside another status bar, it only runs the block.
+
 ### 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.
@@ -293,8 +350,8 @@ 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. `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.
+- 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.
+- Each row is marked with its state in brackets: pending `[ ]` and running `[▸]` in bold yellow, done `[✓]` in green, failed `[𝘅]` in red and skipped `[—]` in yellow. On an animated terminal a running task shows a turning spinner instead, `[⠏]`, drawn from the configured spinner format, 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. 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.
@@ -336,6 +393,9 @@ With a fixed width, TTY::Box 0.7 wraps text but sizes the box from the unwrapped
 - [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, at most as many at once as asked, and mark failed and skipped tasks.
+- [x] `multi_spinner` and `multi_progress` run declared jobs at once, at most as many as asked, draw every row including waiting ones, return each job's value, and mark failed and skipped jobs.
+- [x] `Dry::CLI::UI.configure` sets the spinner frames, bar characters and bar colours every widget draws with, and rejects unknown formats and styles when set.
+- [x] `status_bar` keeps an automatically fed status line below everything the command prints, restores the cursor after every write, leaves the scrollback intact, and removes itself when the block ends or raises.
 - [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.
@@ -346,6 +406,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; `popup` positions itself, and takes no coordinates.
+- Full-screen applications, alternate screen buffers, scroll regions, 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/configuration.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "pastel"
+require "tty/spinner/formats"
+require "tty/progressbar/formats"
+
+module Dry
+  class CLI
+    module UI
+      # Process-wide settings, made once through {UI.configure}:
+      #
+      #   Dry::CLI::UI.configure do
+      #     spinner_format :dots                          # any TTY::Spinner format name
+      #     bar_format :box                               # any TTY::ProgressBar bar format name
+      #     bar_color :cyan                               # any Pastel style, or nil
+      #     bar_background nil                            # any Pastel style, or nil
+      #   end
+      #
+      #   Dry::CLI::UI.configure do |config|
+      #     config.spinner_format = { interval: 8, frames: %w[◐ ◓ ◑ ◒] }
+      #     config.bar_format = { complete: "#", incomplete: "." }
+      #   end
+      #
+      # Anything not set reads from {DEFAULTS}.
+      class Configuration
+        # What a setting reads before it is set: a green `◼` for each finished
+        # part of a bar, over a gray track the whole bar's width.
+        DEFAULTS = {
+          spinner_format: :dots,
+          bar_format: { complete: "◼", incomplete: " " }.freeze,
+          bar_color: :green,
+          bar_background: :on_bright_black
+        }.freeze
+
+        # Every style name Pastel knows, for checking colour settings.
+        STYLES = Pastel.new(enabled: true).styles.keys.freeze
+
+        # Marks a DSL call made without a value, which reads instead of writes.
+        UNSET = Object.new.freeze
+        private_constant :UNSET
+
+        def initialize
+          @values = {}
+        end
+
+        # @!method spinner_format(value = UNSET)
+        #   Reads the spinner format, or sets it when given a value.
+        #   @param value [Symbol, Hash] a key of `TTY::Formats::FORMATS`, or
+        #     `{ interval:, frames: }`: frames per second, and the frames
+        #   @return [Symbol, Hash]
+        # @!method bar_format(value = UNSET)
+        #   Reads the bar format, or sets it when given a value.
+        #   @param value [Symbol, Hash] a key of `TTY::ProgressBar::Formats::FORMATS`,
+        #     or `{ complete:, incomplete: }`
+        #   @return [Symbol, Hash]
+        # @!method bar_color(value = UNSET)
+        #   Reads the colour a bar's finished part is drawn in, or sets it.
+        #   @param value [Symbol, nil] a Pastel style, such as :green; nil for none
+        #   @return [Symbol, nil]
+        # @!method bar_background(value = UNSET)
+        #   Reads the background the whole bar is drawn on, or sets it.
+        #   @param value [Symbol, nil] a Pastel style, such as :on_bright_black; nil for none
+        #   @return [Symbol, nil]
+        DEFAULTS.each_key do |name|
+          define_method(name) do |value = UNSET|
+            return @values.fetch(name) { DEFAULTS.fetch(name) } if UNSET.equal?(value)
+
+            public_send(:"#{name}=", value)
+          end
+        end
+
+        # @param value [Symbol, Hash] see {#spinner_format}
+        # @raise [ArgumentError] for an unknown name or a malformed Hash
+        def spinner_format=(value)
+          @values[:spinner_format] = spinner_definition(value) && value
+        end
+
+        # @param value [Symbol, Hash] see {#bar_format}
+        # @raise [ArgumentError] for an unknown name or a malformed Hash
+        def bar_format=(value)
+          @values[:bar_format] = bar_definition(value) && value
+        end
+
+        # @param value [Symbol, nil] see {#bar_color}
+        # @raise [ArgumentError] for a style Pastel does not know
+        def bar_color=(value)
+          @values[:bar_color] = style(:bar_color, value)
+        end
+
+        # @param value [Symbol, nil] see {#bar_background}
+        # @raise [ArgumentError] for a style Pastel does not know
+        def bar_background=(value)
+          @values[:bar_background] = style(:bar_background, value)
+        end
+
+        # @return [Array<String>] the frames a spinner cycles through
+        def spinner_frames
+          frames = spinner_definition(spinner_format).fetch(:frames)
+          frames.is_a?(String) ? frames.chars : frames
+        end
+
+        # @return [Float] seconds between two spinner frames
+        def spinner_frame_seconds
+          1.0 / spinner_definition(spinner_format).fetch(:interval)
+        end
+
+        # @return [String] what a finished part of a bar is drawn with
+        def bar_complete
+          bar_definition(bar_format).fetch(:complete)
+        end
+
+        # @return [String] what an unfinished part of a bar is drawn with
+        def bar_incomplete
+          bar_definition(bar_format).fetch(:incomplete)
+        end
+
+        private
+
+        # @param value [Symbol, Hash]
+        # @return [Hash{Symbol => Object}] with :interval and :frames
+        def spinner_definition(value)
+          return TTY::Formats::FORMATS.fetch(value) { unknown(:spinner_format, value) } if value.is_a?(Symbol)
+
+          valid = value.is_a?(Hash) && value[:interval].is_a?(Numeric) && value[:interval].positive? &&
+                  (value[:frames].is_a?(String) || value[:frames].is_a?(Array)) && !value[:frames].empty?
+          valid ? value : malformed(:spinner_format, value, "{ interval: Numeric, frames: Array }")
+        end
+
+        # @param value [Symbol, Hash]
+        # @return [Hash{Symbol => String}] with :complete and :incomplete
+        def bar_definition(value)
+          return TTY::ProgressBar::Formats::FORMATS.fetch(value) { unknown(:bar_format, value) } if value.is_a?(Symbol)
+
+          valid = value.is_a?(Hash) && value[:complete].is_a?(String) && value[:incomplete].is_a?(String)
+          valid ? value : malformed(:bar_format, value, "{ complete: String, incomplete: String }")
+        end
+
+        # @param setting [Symbol]
+        # @param value [Symbol, nil]
+        # @return [Symbol, nil] the value
+        # @raise [ArgumentError] for anything but nil or a style Pastel knows
+        def style(setting, value)
+          return value if value.nil? || STYLES.include?(value)
+
+          raise ArgumentError, "#{setting} must be a Pastel style or nil, got #{value.inspect}"
+        end
+
+        # @raise [ArgumentError]
+        def unknown(setting, value)
+          raise ArgumentError, "#{setting} #{value.inspect} is not a known format"
+        end
+
+        # @raise [ArgumentError]
+        def malformed(setting, value, shape)
+          raise ArgumentError, "#{setting} must be a format name or #{shape}, got #{value.inspect}"
+        end
+      end
+    end
+  end
+end