cli-ui 1.5.0 → 2.0.0

data/lib/cli/ui/frame/frame_stack.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 module CLI
   module UI
     module Frame
@@ -6,8 +8,18 @@ module CLI
         STYLE_ENVVAR = 'CLI_STYLE_STACK'
 
         class StackItem
-          attr_reader :color, :frame_style
+          extend T::Sig
+
+          sig { returns(CLI::UI::Color) }
+          attr_reader :color
+
+          sig { returns(CLI::UI::Frame::FrameStyle) }
+          attr_reader :frame_style
 
+          sig do
+            params(color_name: CLI::UI::Colorable, style_name: FrameStylable)
+              .void
+          end
           def initialize(color_name, style_name)
             @color = CLI::UI.resolve_color(color_name)
             @frame_style = CLI::UI.resolve_style(style_name)
@@ -15,13 +27,16 @@ module CLI
         end
 
         class << self
+          extend T::Sig
+
           # Fetch all items off the frame stack
+          sig { returns(T::Array[StackItem]) }
           def items
             colors = ENV.fetch(COLOR_ENVVAR, '').split(':').map(&:to_sym)
             styles = ENV.fetch(STYLE_ENVVAR, '').split(':').map(&:to_sym)
 
-            colors.length.times.map do |i|
-              StackItem.new(colors[i], styles[i] || Frame.frame_style)
+            colors.each_with_index.map do |color, i|
+              StackItem.new(color, styles[i] || Frame.frame_style)
             end
           end
 
@@ -43,18 +58,20 @@ module CLI
           # If both an item and a color/style pair are given, raises an +ArgumentError+
           # If the given item is not a +StackItem+, raises an +ArgumentError+
           #
+          sig do
+            params(
+              item: T.nilable(StackItem),
+              color: T.nilable(CLI::UI::Color),
+              style: T.nilable(CLI::UI::Frame::FrameStyle),
+            )
+              .void
+          end
           def push(item = nil, color: nil, style: nil)
-            unless item.nil?
-              unless item.is_a?(StackItem)
-                raise ArgumentError, 'item must be a StackItem'
-              end
-
-              unless color.nil? && style.nil?
-                raise ArgumentError, 'Must give one of item or color: and style:'
-              end
+            if color.nil? != style.nil? || item.nil? == color.nil?
+              raise ArgumentError, 'Must give one of item or color: and style:'
             end
 
-            item ||= StackItem.new(color, style)
+            item ||= StackItem.new(T.must(color), T.must(style))
 
             curr = items
             curr << item
@@ -63,6 +80,7 @@ module CLI
           end
 
           # Removes and returns the last stack item off the stack
+          sig { returns(T.nilable(StackItem)) }
           def pop
             curr = items
             ret = curr.pop
@@ -79,13 +97,14 @@ module CLI
           # This is done to preserve backward compatibility with earlier versions of cli/ui.
           # This ensures that any code that relied upon previous stack behavior should continue
           # to work.
+          sig { params(items: T::Array[StackItem]).void }
           def serialize(items)
             colors = []
             styles = []
 
             items.each do |item|
               colors << item.color.name
-              styles << item.frame_style.name
+              styles << item.frame_style.style_name
             end
 
             ENV[COLOR_ENVVAR] = colors.join(':')

data/lib/cli/ui/frame/frame_style/box.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 module CLI
   module UI
     module Frame
@@ -12,10 +14,14 @@ module CLI
           BOTTOM_LEFT = '┗'
 
           class << self
-            def name
-              'box'
+            extend T::Sig
+
+            sig { override.returns(Symbol) }
+            def style_name
+              :box
             end
 
+            sig { override.returns(String) }
             def prefix
               VERTICAL
             end
@@ -34,7 +40,8 @@ module CLI
             #
             #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
             #
-            def open(text, color:)
+            sig { override.params(text: String, color: CLI::UI::Color).returns(String) }
+            def start(text, color:)
               edge(text, color: color, first: TOP_LEFT)
             end
 
@@ -52,6 +59,7 @@ module CLI
             #
             #   ┣━━ Divider ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
             #
+            sig { override.params(text: String, color: CLI::UI::Color).returns(String) }
             def divider(text, color:)
               edge(text, color: color, first: DIVIDER)
             end
@@ -71,12 +79,16 @@ module CLI
             #
             #   ┗━━ Close ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
             #
+            sig { override.params(text: String, color: CLI::UI::Color, right_text: T.nilable(String)).returns(String) }
             def close(text, color:, right_text: nil)
               edge(text, color: color, right_text: right_text, first: BOTTOM_LEFT)
             end
 
             private
 
+            sig do
+              params(text: String, color: CLI::UI::Color, first: String, right_text: T.nilable(String)).returns(String)
+            end
             def edge(text, color:, first:, right_text: nil)
               color = CLI::UI.resolve_color(color)
 
@@ -84,7 +96,6 @@ module CLI
 
               preamble << color.code << first << (HORIZONTAL * 2)
 
-              text ||= ''
               unless text.empty?
                 preamble << ' ' << CLI::UI.resolve_text("{{#{color.name}:#{text}}}") << ' '
               end

data/lib/cli/ui/frame/frame_style/bracket.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 module CLI
   module UI
     module Frame
@@ -12,10 +14,14 @@ module CLI
           BOTTOM_LEFT = '┗'
 
           class << self
-            def name
-              'bracket'
+            extend T::Sig
+
+            sig { override.returns(Symbol) }
+            def style_name
+              :bracket
             end
 
+            sig { override.returns(String) }
             def prefix
               VERTICAL
             end
@@ -34,7 +40,8 @@ module CLI
             #
             #   ┏━━ Open
             #
-            def open(text, color:)
+            sig { override.params(text: String, color: CLI::UI::Color).returns(String) }
+            def start(text, color:)
               edge(text, color: color, first: TOP_LEFT)
             end
 
@@ -52,6 +59,7 @@ module CLI
             #
             #   ┣━━ Divider
             #
+            sig { override.params(text: String, color: CLI::UI::Color).returns(String) }
             def divider(text, color:)
               edge(text, color: color, first: DIVIDER)
             end
@@ -71,12 +79,16 @@ module CLI
             #
             #   ┗━━ Close
             #
+            sig { override.params(text: String, color: CLI::UI::Color, right_text: T.nilable(String)).returns(String) }
             def close(text, color:, right_text: nil)
               edge(text, color: color, right_text: right_text, first: BOTTOM_LEFT)
             end
 
             private
 
+            sig do
+              params(text: String, color: CLI::UI::Color, first: String, right_text: T.nilable(String)).returns(String)
+            end
             def edge(text, color:, first:, right_text: nil)
               color = CLI::UI.resolve_color(color)
 
@@ -84,7 +96,6 @@ module CLI
 
               preamble << color.code << first << (HORIZONTAL * 2)
 
-              text ||= ''
               unless text.empty?
                 preamble << ' ' << CLI::UI.resolve_text("{{#{color.name}:#{text}}}") << ' '
               end
@@ -117,16 +128,16 @@ module CLI
               # the final space, since we're going to write over it.
               preamble_start -= 1 unless preamble_start.zero?
 
-              # Prefix_width includes the width of the terminal space, which we
-              # want to remove.  The clamping is done to avoid a negative
-              # preamble start which can occur for the first frame.
+              # Jumping around the line can cause some unwanted flashes
               o << CLI::UI::ANSI.hide_cursor
 
               # reset to column 1 so that things like ^C don't ruin formatting
               o << "\r"
+
               o << color.code
               o << print_at_x(preamble_start, preamble + color.code + suffix)
               o << CLI::UI::Color::RESET.code
+              o << CLI::UI::ANSI.show_cursor
               o << "\n"
 
               o

data/lib/cli/ui/frame/frame_style.rb

@@ -1,120 +1,117 @@
+# typed: true
+
 require 'cli/ui/frame'
 
 module CLI
   module UI
     module Frame
       module FrameStyle
-        class << self
-          # rubocop:disable Style/ClassVars
-          @@loaded_styles = []
+        include Kernel
+        extend T::Sig
+        extend T::Helpers
+        abstract!
 
-          def loaded_styles
-            @@loaded_styles.map(&:name)
-          end
+        autoload(:Box, 'cli/ui/frame/frame_style/box')
+        autoload(:Bracket, 'cli/ui/frame/frame_style/bracket')
+
+        MAP = {
+          box: -> { FrameStyle::Box },
+          bracket: -> { FrameStyle::Bracket },
+        }
+
+        class << self
+          extend T::Sig
 
           # Lookup a frame style via its name
           #
           # ==== Attributes
           #
           # * +symbol+ - frame style name to lookup
+          sig { params(name: T.any(String, Symbol)).returns(FrameStyle) }
           def lookup(name)
-            @@loaded_styles
-              .find { |style| style.name.to_sym == name }
-              .tap  { |style| raise InvalidFrameStyleName, name if style.nil? }
+            MAP.fetch(name.to_sym).call
+          rescue KeyError
+            raise(InvalidFrameStyleName, name)
           end
-
-          def extended(base)
-            @@loaded_styles << base
-            base.extend(Interface)
-          end
-          # rubocop:enable Style/ClassVars
         end
 
-        class InvalidFrameStyleName < ArgumentError
-          def initialize(name)
-            super
-            @name = name
-          end
+        sig { abstract.returns(Symbol) }
+        def style_name; end
 
-          def message
-            keys = FrameStyle.loaded_styles.map(&:inspect).join(',')
-            "invalid frame style: #{@name.inspect}" \
-              ' -- must be one of CLI::UI::Frame::FrameStyle.loaded_styles ' \
-              "(#{keys})"
-          end
+        # Returns the character(s) that should be printed at the beginning
+        # of lines inside this frame
+        sig { abstract.returns(String) }
+        def prefix; end
+
+        # Returns the printing width of the prefix
+        sig { returns(Integer) }
+        def prefix_width
+          CLI::UI::ANSI.printing_width(prefix)
         end
 
-        # Public interface for FrameStyles
-        # Applied by extending FrameStyle
-        module Interface
-          def name
-            raise NotImplementedError
-          end
+        # Draws the "Open" line for this frame style
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - (required) The color of the frame.
+        #
+        sig { abstract.params(text: String, color: CLI::UI::Color).returns(String) }
+        def start(text, color:); end
 
-          # Returns the character(s) that should be printed at the beginning
-          # of lines inside this frame
-          def prefix
-            raise NotImplementedError
-          end
+        # Draws the "Close" line for this frame style
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - (required) The color of the frame.
+        # * +:right_text+ - Text to print at the right of the line. Defaults to nil
+        #
+        sig { abstract.params(text: String, color: CLI::UI::Color, right_text: T.nilable(String)).returns(String) }
+        def close(text, color:, right_text: nil); end
 
-          # Returns the printing width of the prefix
-          def prefix_width
-            CLI::UI::ANSI.printing_width(prefix)
-          end
+        # Draws a "divider" line for the current frame style
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - (required) The color of the frame.
+        #
+        sig { abstract.params(text: String, color: CLI::UI::Color).returns(String) }
+        def divider(text, color:); end
 
-          # Draws the "Open" line for this frame style
-          #
-          # ==== Attributes
-          #
-          # * +text+ - (required) the text/title to output in the frame
-          #
-          # ==== Options
-          #
-          # * +:color+ - (required) The color of the frame.
-          #
-          def open(text, color:)
-            raise NotImplementedError
-          end
+        sig { params(x: Integer, str: String).returns(String) }
+        def print_at_x(x, str)
+          CLI::UI::ANSI.cursor_horizontal_absolute(1 + x) + str
+        end
 
-          # Draws the "Close" line for this frame style
-          #
-          # ==== Attributes
-          #
-          # * +text+ - (required) the text/title to output in the frame
-          #
-          # ==== Options
-          #
-          # * +:color+ - (required) The color of the frame.
-          # * +:right_text+ - Text to print at the right of the line. Defaults to nil
-          #
-          def close(text, color:, right_text: nil)
-            raise NotImplementedError
-          end
+        class InvalidFrameStyleName < ArgumentError
+          extend T::Sig
 
-          # Draws a "divider" line for the current frame style
-          #
-          # ==== Attributes
-          #
-          # * +text+ - (required) the text/title to output in the frame
-          #
-          # ==== Options
-          #
-          # * +:color+ - (required) The color of the frame.
-          #
-          def divider(text, color: nil)
-            raise NotImplementedError
+          sig { params(name: T.any(String, Symbol)).void }
+          def initialize(name)
+            super
+            @name = name
           end
 
-          private
-
-          def print_at_x(x, str)
-            CLI::UI::ANSI.cursor_horizontal_absolute(1 + x) + str
+          sig { returns(String) }
+          def message
+            keys = FrameStyle::MAP.keys.map(&:inspect).join(', ')
+            "invalid frame style: #{@name.inspect}" \
+              ' -- must be one of CLI::UI::Frame::FrameStyle::MAP ' \
+              "(#{keys})"
           end
         end
       end
     end
   end
 end
-
-require 'cli/ui/frame/frame_style/box'
-require 'cli/ui/frame/frame_style/bracket'

data/lib/cli/ui/frame.rb

@@ -1,4 +1,7 @@
 # coding: utf-8
+
+# typed: true
+
 require 'cli/ui'
 require 'cli/ui/frame/frame_stack'
 require 'cli/ui/frame/frame_style'
@@ -7,9 +10,12 @@ module CLI
   module UI
     module Frame
       class UnnestedFrameException < StandardError; end
+      DEFAULT_FRAME_COLOR = CLI::UI.resolve_color(:cyan)
+
       class << self
-        DEFAULT_FRAME_COLOR = CLI::UI.resolve_color(:cyan)
+        extend T::Sig
 
+        sig { returns(FrameStyle) }
         def frame_style
           @frame_style ||= FrameStyle::Box
         end
@@ -22,6 +28,7 @@ module CLI
         #
         # * +symbol+ or +FrameStyle+ - the default frame style to use for frames
         #
+        sig { params(frame_style: FrameStylable).void }
         def frame_style=(frame_style)
           @frame_style = CLI::UI.resolve_style(frame_style)
         end
@@ -67,13 +74,25 @@ module CLI
         #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
         #
         #
+        sig do
+          type_parameters(:T).params(
+            text: String,
+            color: Colorable,
+            failure_text: T.nilable(String),
+            success_text: T.nilable(String),
+            timing: T.any(T::Boolean, Numeric),
+            frame_style: FrameStylable,
+            block: T.nilable(T.proc.returns(T.type_parameter(:T))),
+          ).returns(T.nilable(T.type_parameter(:T)))
+        end
         def open(
           text,
           color: DEFAULT_FRAME_COLOR,
           failure_text: nil,
           success_text: nil,
-          timing:       nil,
-          frame_style:  self.frame_style
+          timing: block_given?,
+          frame_style: self.frame_style,
+          &block
         )
           frame_style = CLI::UI.resolve_style(frame_style)
           color = CLI::UI.resolve_color(color)
@@ -91,7 +110,7 @@ module CLI
           t_start = Time.now
           CLI::UI.raw do
             print(prefix.chop)
-            puts frame_style.open(text, color: color)
+            puts frame_style.start(text, color: color)
           end
           FrameStack.push(color: color, style: frame_style)
 
@@ -103,15 +122,15 @@ module CLI
             success = yield
           rescue
             closed = true
-            t_diff = elasped(t_start, timing)
+            t_diff = elapsed(t_start, timing)
             close(failure_text, color: :red, elapsed: t_diff)
             raise
           else
             success
           ensure
             unless closed
-              t_diff = elasped(t_start, timing)
-              if success != false
+              t_diff = elapsed(t_start, timing)
+              if T.unsafe(success) != false
                 close(success_text, color: color, elapsed: t_diff)
               else
                 close(failure_text, color: :red, elapsed: t_diff)
@@ -145,16 +164,17 @@ module CLI
         #
         # MUST be inside an open frame or it raises a +UnnestedFrameException+
         #
+        sig { params(text: T.nilable(String), color: T.nilable(Colorable), frame_style: T.nilable(FrameStylable)).void }
         def divider(text, color: nil, frame_style: nil)
           fs_item = FrameStack.pop
           raise UnnestedFrameException, 'No frame nesting to unnest' unless fs_item
 
-          color = CLI::UI.resolve_color(color) || fs_item.color
-          frame_style = CLI::UI.resolve_style(frame_style) || fs_item.frame_style
+          divider_color = CLI::UI.resolve_color(color || fs_item.color)
+          frame_style = CLI::UI.resolve_style(frame_style || fs_item.frame_style)
 
           CLI::UI.raw do
             print(prefix.chop)
-            puts frame_style.divider(text, color: color)
+            puts frame_style.divider(text.to_s, color: divider_color)
           end
 
           FrameStack.push(fs_item)
@@ -184,21 +204,25 @@ module CLI
         #
         # MUST be inside an open frame or it raises a +UnnestedFrameException+
         #
+        sig do
+          params(
+            text: T.nilable(String),
+            color: T.nilable(Colorable),
+            elapsed: T.nilable(Numeric),
+            frame_style: T.nilable(FrameStylable),
+          ).void
+        end
         def close(text, color: nil, elapsed: nil, frame_style: nil)
           fs_item = FrameStack.pop
           raise UnnestedFrameException, 'No frame nesting to unnest' unless fs_item
 
-          color = CLI::UI.resolve_color(color) || fs_item.color
-          frame_style = CLI::UI.resolve_style(frame_style) || fs_item.frame_style
-
-          kwargs = {}
-          if elapsed
-            kwargs[:right_text] = "(#{elapsed.round(2)}s)"
-          end
+          close_color = CLI::UI.resolve_color(color || fs_item.color)
+          frame_style = CLI::UI.resolve_style(frame_style || fs_item.frame_style)
+          elapsed_string = elapsed ? "(#{elapsed.round(2)}s)" : nil
 
           CLI::UI.raw do
             print(prefix.chop)
-            puts frame_style.close(text, color: color, **kwargs)
+            puts frame_style.close(text.to_s, color: close_color, right_text: elapsed_string)
           end
         end
 
@@ -208,11 +232,12 @@ module CLI
         #
         # * +:color+ - The color of the prefix. Defaults to +Thread.current[:cliui_frame_color_override]+
         #
+        sig { params(color: T.nilable(Colorable)).returns(String) }
         def prefix(color: Thread.current[:cliui_frame_color_override])
           +''.tap do |output|
             items = FrameStack.items
 
-            items[0..-2].each do |item|
+            items[0..-2].to_a.each do |item|
               output << item.color.code << item.frame_style.prefix
             end
 
@@ -227,6 +252,7 @@ module CLI
         end
 
         # The width of a prefix given the number of Frames in the stack
+        sig { returns(Integer) }
         def prefix_width
           w = FrameStack.items.reduce(0) do |width, item|
             width + item.frame_style.prefix_width
@@ -241,7 +267,12 @@ module CLI
         #
         # * +color+ - The color to override to
         #
-        def with_frame_color_override(color)
+        sig do
+          type_parameters(:T)
+            .params(color: Colorable, block: T.proc.returns(T.type_parameter(:T)))
+            .returns(T.type_parameter(:T))
+        end
+        def with_frame_color_override(color, &block)
           prev = Thread.current[:cliui_frame_color_override]
           Thread.current[:cliui_frame_color_override] = color
           yield
@@ -254,13 +285,13 @@ module CLI
         # If timing is:
         #   Numeric: return it
         #   false: return nil
-        #   true or nil: defaults to Time.new
-        #   Time: return the difference with start
-        def elasped(start, timing)
+        #   true: defaults to Time.new
+        sig { params(start: Time, timing: T.any(Numeric, T::Boolean)).returns(T.nilable(Numeric)) }
+        def elapsed(start, timing)
           return timing if timing.is_a?(Numeric)
           return if timing.is_a?(FalseClass)
 
-          timing = Time.new if timing.is_a?(TrueClass) || timing.nil?
+          timing = Time.new
           timing - start
         end
       end