dry-cli-ui 0.1.0

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

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # The object {UI#ui} returns: a small semantic API for what a command
+      # wants to say, independent of how the terminal renders it.
+      #
+      # Messages about the command itself (`debug`, `warn`, `error`, `fatal`),
+      # spinners, progress bars, task trees and prompts go to `err`. The
+      # command's results (`info`, `success`, tables, plain boxes) go to
+      # `out`. Piping a command's output therefore captures its results and
+      # nothing else.
+      #
+      # @example
+      #   ui = Dry::CLI::UI::Console.new
+      #   ui.info "Importing tax rules..."
+      #   rules = ui.spinner("Loading YAML") { load_rules }
+      #   ui.progress("Importing", total: rules.size) do |bar|
+      #     rules.each do |rule|
+      #       import(rule)
+      #       bar.advance
+      #     end
+      #   end
+      #   ui.success "Imported #{rules.size} rules"
+      class Console
+        # @!method debug(*paragraphs, width: nil)
+        #   A grey "Debug" box on `err`.
+        #   @param paragraphs [Array<#to_s>] each one wrapped on its own, separated by a blank line
+        #   @param width [Integer, nil] columns, overriding the console's box width
+        #   @return [nil]
+        # @!method info(*paragraphs, width: nil)
+        #   A cyan "Info" box on `out`.
+        #   @param (see #debug)
+        #   @return [nil]
+        # @!method success(*paragraphs, width: nil)
+        #   A green "Success" box on `out`.
+        #   @param (see #debug)
+        #   @return [nil]
+        # @!method warn(*paragraphs, width: nil)
+        #   A yellow "Warning" box on `err`.
+        #   @param (see #debug)
+        #   @return [nil]
+        # @!method error(*paragraphs, width: nil)
+        #   A red "Error" box on `err`.
+        #   @param (see #debug)
+        #   @return [nil]
+        # @!method fatal(*paragraphs, width: nil)
+        #   A magenta "Fatal" box on `err`.
+        #   @param (see #debug)
+        #   @return [nil]
+        Theme::LEVELS.each_key do |level|
+          define_method(level) do |*paragraphs, width: nil|
+            box(*paragraphs, level: level, width: width)
+          end
+        end
+
+        # @param out [IO] where results go
+        # @param err [IO] where diagnostics, progress and prompts go
+        # @param input [IO] where prompt answers come from
+        # @param env [Hash{String => String}] read for NO_COLOR and TERM
+        # @param color [Boolean, nil] force colour on or off; nil decides per stream
+        # @param animate [Boolean, nil] force animation on or off; nil decides per stream
+        # @param width [Integer, nil] force the terminal width; nil asks the terminal
+        # @param box_width [Integer, nil] box width in columns; nil fills the terminal
+        # @param clock [#call] returns monotonic seconds
+        def initialize(out: $stdout, err: $stderr, input: $stdin, env: ENV, color: nil, animate: nil,
+                       width: nil, box_width: nil, clock: Duration::CLOCK)
+          @out = Terminal.new(out, env: env, color: color, animate: animate, width: width)
+          @err = Terminal.new(err, env: env, color: color, animate: animate, width: width)
+          @input = input
+          @box_width = box_width
+          @clock = clock
+        end
+
+        # A framed panel. Given a level, it takes that level's title, colour
+        # and stream; without one it is untitled unless given a title, and goes
+        # to `out`.
+        #
+        # @example
+        #   ui.box("Name: Alan Turing", "Role: Cryptanalyst", title: "Profile")
+        #
+        # @param paragraphs [Array<#to_s>] each one wrapped on its own, separated by a blank line
+        # @param title [String, nil] overrides the level's title
+        # @param level [Symbol, nil] one of {Theme::LEVELS}
+        # @param width [Integer, nil] columns, overriding the console's box width
+        # @return [nil]
+        def box(*paragraphs, title: nil, level: nil, width: nil)
+          theme = level && Theme.level(level)
+          terminal = theme ? stream(theme) : out
+          widget = Widgets::Box.new(terminal, width: width || box_width)
+          terminal.print(widget.render(paragraphs, title: title || theme&.title, color: theme&.color))
+          nil
+        end
+
+        # One line with a coloured glyph, going to the level's stream.
+        #
+        # @example
+        #   ui.status "Connected to the database", level: :success   # ✓ Connected to the database
+        #
+        # @param words [Array<#to_s>] joined with spaces
+        # @param level [Symbol] one of {Theme::LEVELS}
+        # @return [nil]
+        def status(*words, level: :info)
+          theme = Theme.level(level)
+          terminal = stream(theme)
+          terminal.puts(Widgets::Status.line(terminal, theme, words.join(" ")))
+          nil
+        end
+
+        # Runs a block under a spinner and leaves `✓ label (1.2s)` behind, or
+        # `✗ label` when the block raises.
+        #
+        # @param label [String]
+        # @yield the work
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block
+        def spinner(label, &)
+          raise ArgumentError, "spinner needs a block" unless block_given?
+
+          Widgets::Spinner.new(err, clock: clock).run(label, &)
+        end
+
+        # Runs a block with a progress bar showing percent, count and ETA.
+        #
+        # @param label [String]
+        # @param total [Integer] units of work
+        # @yieldparam progress [Widgets::Progress::Handle] call `advance` as units complete
+        # @return [Object] whatever the block returns
+        # @raise [ArgumentError] without a block, or when total is not a non-negative Integer
+        def progress(label, total:, &)
+          raise ArgumentError, "progress needs a block" unless block_given?
+
+          Widgets::Progress.new(err, clock: clock).run(label, total: total, &)
+        end
+
+        # Declares a tree of tasks, then runs it, showing each task's state
+        # and elapsed time. See {Widgets::Tasks}.
+        #
+        # @example Several operations at once
+        #   ui.tasks("Fetching", concurrent: true) do |t|
+        #     t.task("fonts") { fetch(:fonts) }
+        #     t.task("images") { fetch(:images) }
+        #   end
+        #
+        # @param title [String, nil]
+        # @param concurrent [Boolean] run the top-level tasks at the same time
+        # @yieldparam tasks [Widgets::Tasks::Builder] declares `task`s and `group`s
+        # @return [nil]
+        # @raise [ArgumentError] without a block
+        def tasks(title = nil, concurrent: false, &)
+          raise ArgumentError, "tasks needs a block" unless block_given?
+
+          Widgets::Tasks.new(err, clock: clock).run(title, concurrent: concurrent, &)
+        end
+
+        # Prints a table to `out`.
+        #
+        # @example
+        #   ui.table([["Alan Turing", 41]], header: ["Name", "Age"])
+        #
+        # @param rows [Array<Array<#to_s>>]
+        # @param header [Array<#to_s>, nil]
+        # @return [nil]
+        def table(rows, header: nil)
+          out.print(Widgets::Table.new(out).render(rows, header: header))
+          nil
+        end
+
+        # Asks a question. See {Widgets::Prompt#ask}.
+        #
+        # @example
+        #   ui.prompt("Environment?", choices: %w[staging production], default: "staging")
+        #
+        # @param question [String]
+        # @param default [Object, nil]
+        # @param choices [Array<String>, Hash{String => Object}, nil]
+        # @return [Object, nil]
+        # @raise [NonInteractiveError] when the input is exhausted and there is no default
+        def prompt(question, default: nil, choices: nil)
+          prompter.ask(question, default: default, choices: choices)
+        end
+
+        # Asks a yes/no question.
+        #
+        # @param question [String]
+        # @param default [Boolean]
+        # @return [Boolean]
+        def confirm(question, default: false)
+          prompter.confirm(question, default: default)
+        end
+
+        private
+
+        # @return [Terminal]
+        attr_reader :out
+
+        # @return [Terminal]
+        attr_reader :err
+
+        # @return [IO]
+        attr_reader :input
+
+        # @return [Integer, nil]
+        attr_reader :box_width
+
+        # @return [#call]
+        attr_reader :clock
+
+        # @param theme [Theme::Level]
+        # @return [Terminal]
+        def stream(theme)
+          theme.stream == :err ? err : out
+        end
+
+        # @return [Widgets::Prompt]
+        def prompter
+          @prompter ||= Widgets::Prompt.new(input: input, terminal: err)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # Measures and formats elapsed time.
+      module Duration
+        # The default clock: monotonic seconds, immune to wall-clock changes.
+        CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+        # Formats a number of seconds for a human.
+        #
+        # @example
+        #   Duration.format(0.42)  # => "0.4s"
+        #   Duration.format(62)    # => "1m 02s"
+        #   Duration.format(3720)  # => "1h 02m"
+        #
+        # @param seconds [Numeric]
+        # @return [String]
+        def self.format(seconds)
+          case seconds
+          in ...60 then Kernel.format("%<s>.1fs", s: seconds)
+          in ...3600 then Kernel.format("%<m>dm %<s>02ds", m: seconds / 60, s: seconds % 60)
+          else Kernel.format("%<h>dh %<m>02dm", h: seconds / 3600, m: (seconds % 3600) / 60)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "pastel"
+require "tty-cursor"
+require "tty-screen"
+
+module Dry
+  class CLI
+    module UI
+      # One output stream, and what it can do.
+      #
+      # A stream that is not a TTY, or runs under `TERM=dumb`, gets no
+      # animation and no cursor movement. `NO_COLOR` (https://no-color.org)
+      # additionally switches colour off. Widgets ask these questions rather
+      # than inspecting the IO themselves, which is what keeps the fallback in
+      # one place.
+      class Terminal
+        # Width assumed for a stream that is not a TTY.
+        DEFAULT_WIDTH = 80
+
+        # Height assumed for a stream that is not a TTY.
+        DEFAULT_HEIGHT = 24
+
+        # @param io [IO] the stream to write to
+        # @param env [Hash{String => String}] the environment to read NO_COLOR and TERM from
+        # @param color [Boolean, nil] force colour on or off; nil decides from the stream
+        # @param animate [Boolean, nil] force animation on or off; nil decides from the stream
+        # @param width [Integer, nil] force the width; nil asks the terminal
+        def initialize(io, env: ENV, color: nil, animate: nil, width: nil)
+          @io = io
+          @env = env
+          @color = color
+          @animate = animate
+          @width = width
+        end
+
+        # @return [IO] the stream this terminal writes to
+        attr_reader :io
+
+        # Whether the stream is an interactive terminal.
+        #
+        # @return [Boolean]
+        def tty?
+          io.respond_to?(:tty?) && io.tty?
+        end
+
+        # Whether spinners may animate and the cursor may move.
+        #
+        # @return [Boolean]
+        def animated?
+          return animate unless animate.nil?
+
+          tty? && env["TERM"] != "dumb"
+        end
+
+        # Whether to emit ANSI colour codes.
+        #
+        # @return [Boolean]
+        def color?
+          return color unless color.nil?
+
+          animated? && env["NO_COLOR"].to_s.empty?
+        end
+
+        # @return [Integer] columns available
+        def width
+          @width || (tty? ? TTY::Screen.width : DEFAULT_WIDTH)
+        end
+
+        # @return [Integer] rows available
+        def height
+          tty? ? TTY::Screen.height : DEFAULT_HEIGHT
+        end
+
+        # @return [Pastel::Delegator] a colouriser that is a no-op when colour is off
+        def pastel
+          @pastel ||= Pastel.new(enabled: color?)
+        end
+
+        # @return [Module] TTY::Cursor, for widgets that redraw in place
+        def cursor = TTY::Cursor
+
+        # Writes a string without a newline. Flushes, so that output on `out`
+        # and `err` stays in the order it was written even when piped.
+        #
+        # @param text [String]
+        # @return [void]
+        def print(text)
+          io.print(text)
+          io.flush if io.respond_to?(:flush)
+        end
+
+        # Writes a line, flushing as {#print} does.
+        #
+        # @param text [String]
+        # @return [void]
+        def puts(text = "")
+          print("#{text}\n")
+        end
+
+        private
+
+        # @return [Hash{String => String}]
+        attr_reader :env
+
+        # @return [Boolean, nil]
+        attr_reader :color
+
+        # @return [Boolean, nil]
+        attr_reader :animate
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      # The six message levels and how each one looks.
+      module Theme
+        # How one message level is presented.
+        #
+        # @!attribute [r] name
+        #   @return [Symbol] the level, e.g. `:error`
+        # @!attribute [r] title
+        #   @return [String] the box title, e.g. "Error"
+        # @!attribute [r] glyph
+        #   @return [String] the status-line marker, e.g. "✗"
+        # @!attribute [r] color
+        #   @return [Symbol] a Pastel colour for the title and glyph
+        # @!attribute [r] stream
+        #   @return [Symbol] `:out` or `:err`, where messages at this level go
+        Level = ::Data.define(:name, :title, :glyph, :color, :stream)
+
+        # Every level, keyed by name. Diagnostics go to STDERR so that a
+        # command's real output can still be piped.
+        LEVELS = {
+          debug: Level.new(name: :debug, title: "Debug", glyph: "·", color: :bright_black, stream: :err),
+          info: Level.new(name: :info, title: "Info", glyph: "ℹ", color: :cyan, stream: :out),
+          success: Level.new(name: :success, title: "Success", glyph: "✓", color: :green, stream: :out),
+          warn: Level.new(name: :warn, title: "Warning", glyph: "⚠", color: :yellow, stream: :err),
+          error: Level.new(name: :error, title: "Error", glyph: "✗", color: :red, stream: :err),
+          fatal: Level.new(name: :fatal, title: "Fatal", glyph: "✖", color: :magenta, stream: :err)
+        }.freeze
+
+        # Glyphs for the states an operation passes through.
+        STATES = {
+          pending: ["○", :bright_black],
+          running: ["▸", :cyan],
+          done: ["✓", :green],
+          failed: ["✗", :red],
+          skipped: ["–", :bright_black]
+        }.freeze
+
+        # Looks up a level by name.
+        #
+        # @param name [Symbol] one of {LEVELS}' keys
+        # @return [Level]
+        # @raise [ArgumentError] when the level does not exist
+        def self.level(name)
+          LEVELS.fetch(name) { raise ArgumentError, "unknown level #{name.inspect}, expected one of #{LEVELS.keys}" }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dry
+  # Reopened rather than defined: dry-cli declares `class CLI`, not a module,
+  # and getting that wrong raises TypeError the moment both are loaded.
+  #
+  # Declared here without requiring dry-cli, because the gemspec loads this
+  # file at build time when the dependency may not be installed. dry-cli's CLI
+  # inherits from Object, so an empty reopening is compatible either way.
+  class CLI
+    # Presentation helpers for Dry::CLI commands.
+    module UI
+      # The gem version.
+      VERSION = "0.1.0"
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "strings"
+require "tty-box"
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # A framed panel with a single white border and an optional coloured
+        # title.
+        #
+        # 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.
+        class Box
+          # Columns left free on the right when the box fills the terminal.
+          MARGIN = 2
+
+          # Narrowest box drawn, however small the terminal.
+          MIN_WIDTH = 20
+
+          # Blank rows above and below the text, and columns either side of it.
+          PADDING = [1, 2].freeze
+
+          # @param terminal [Terminal]
+          # @param width [Integer, nil] columns; nil fills the terminal
+          def initialize(terminal, width: nil)
+            @terminal = terminal
+            @width = width
+          end
+
+          # Renders a box. Each paragraph is wrapped on its own and separated
+          # from the next by a blank line.
+          #
+          # @param paragraphs [Array<#to_s>]
+          # @param title [String, nil]
+          # @param color [Symbol, nil] Pastel colour for the title
+          # @return [String] the box, ending in a newline
+          def render(paragraphs, title: nil, color: nil)
+            TTY::Box.frame(
+              wrap(paragraphs),
+              width: box_width,
+              padding: PADDING,
+              border: :light,
+              title: title ? { top_left: heading(title, color) } : {},
+              style: { border: { fg: :white } },
+              enable_color: terminal.color?
+            )
+          end
+
+          private
+
+          # @return [Terminal]
+          attr_reader :terminal
+
+          # @return [Integer, nil]
+          attr_reader :width
+
+          # TTY::Box wraps text itself but sizes the box from the unwrapped
+          # lines, which silently drops everything past the first few rows.
+          # Wrapping here first means its own wrap has nothing left to do.
+          #
+          # @param paragraphs [Array<#to_s>]
+          # @return [String]
+          def wrap(paragraphs)
+            text_width = box_width - 2 - (PADDING[1] * 2)
+            paragraphs.map { |p| Strings::Wrap.wrap(p.to_s, text_width).gsub(/[ \t]+$/, "") }.join("\n\n")
+          end
+
+          # @return [Integer]
+          def box_width
+            available = terminal.width - MARGIN
+            [width ? [width, available].min : available, MIN_WIDTH].max
+          end
+
+          # @param title [String]
+          # @param color [Symbol, nil]
+          # @return [String]
+          def heading(title, color)
+            pastel = terminal.pastel
+            styled = color ? pastel.decorate(title, color, :bold) : pastel.bold(title)
+            "─ #{styled} "
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Dry
+  class CLI
+    module UI
+      module Widgets
+        # The line an operation leaves behind when it ends: `✓ Loading (1.2s)`.
+        # Spinners and progress bars share it, so every operation finishes the
+        # same way whether or not the terminal could animate it.
+        module Outcome
+          # @param terminal [Terminal]
+          # @param state [Symbol] `:done` or `:failed`
+          # @param label [String] what the operation was
+          # @param seconds [Numeric] how long it took
+          # @return [String] the line, without a newline
+          def self.line(terminal, state, label, seconds)
+            glyph, color = Theme::STATES.fetch(state)
+            pastel = terminal.pastel
+            "#{pastel.decorate(glyph, color)} #{label} #{pastel.bright_black("(#{Duration.format(seconds)})")}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "tty-progressbar"
+
+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.
+        #
+        # 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
+            # @param total [Integer]
+            # @param bar [TTY::ProgressBar, nil]
+            def initialize(total, bar)
+              @total = total
+              @bar = bar
+              @current = 0
+            end
+
+            # @return [Integer] the number of units the operation has
+            attr_reader :total
+
+            # @return [Integer] the number of units completed so far
+            attr_reader :current
+
+            # Marks units as complete. Progress never passes {#total}.
+            #
+            # @param step [Integer]
+            # @return [self]
+            def advance(step = 1)
+              self.current = (current + step).clamp(0, total)
+              bar&.advance(step)
+              self
+            end
+
+            private
+
+            # @return [TTY::ProgressBar, nil]
+            attr_reader :bar
+
+            attr_writer :current
+          end
+
+          # Columns kept for the label, percentage, count and ETA around the bar.
+          CHROME = 34
+
+          # Narrowest bar drawn.
+          MIN_BAR = 10
+
+          # @param terminal [Terminal]
+          # @param clock [#call] returns monotonic seconds
+          def initialize(terminal, clock:)
+            @terminal = terminal
+            @clock = clock
+          end
+
+          # Runs the block with a progress bar.
+          #
+          # @param label [String]
+          # @param total [Integer] the number of units of work
+          # @yieldparam progress [Handle]
+          # @return [Object] whatever the block returns
+          # @raise [ArgumentError] when total is not a non-negative Integer
+          def run(label, total:)
+            raise ArgumentError, "total must be a non-negative Integer, got #{total.inspect}" unless total.is_a?(Integer) && total >= 0
+
+            started = clock.call
+            bar = start(label, total)
+            handle = Handle.new(total, bar)
+            ok = false
+            result = yield handle
+            ok = true
+            result
+          ensure
+            if handle
+              bar&.stop
+              summary = "#{label} #{handle.current}/#{total}"
+              terminal.puts(Outcome.line(terminal, ok ? :done : :failed, summary, clock.call - started))
+            end
+          end
+
+          private
+
+          # @return [Terminal]
+          attr_reader :terminal
+
+          # @return [#call]
+          attr_reader :clock
+
+          # @param label [String]
+          # @param total [Integer]
+          # @return [TTY::ProgressBar, nil]
+          def start(label, total)
+            unless terminal.animated? && 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: "█",
+              incomplete: "░",
+              clear: true,
+              hide_cursor: true
+            )
+          end
+        end
+      end
+    end
+  end
+end