natty-ui 0.32.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92532c7a8557373cb4e26efb2a0bae197e1da2daddac5853ef40800c7cfbf344
-  data.tar.gz: 3da178c8e00a752802e8cf1fc4822ce6d187516fc7af5af31e03b85b123fd348
+  metadata.gz: 0c61c16b1c5d1611a98f1505bb9eb86b71a0289021a9332f41e2095f7810b144
+  data.tar.gz: e8acc6fdf67bd259fd671defd80533f5de0fa9aa7b005cef9f092b7ebf097606
 SHA512:
-  metadata.gz: 0e41a869ea4dfde35449314f95662e2fcb837f50a76ab49cdd9e0f7cc462c5c12481e83e2eec66029468b2ef91d9f05e56f3702e0d488329c0fb3e1ee61f4431
-  data.tar.gz: da9d3545c79c99d6d09cc924a2d0dcbff6e697c264228a8ec657103c2fda7fc77583e7a5fb60db04f3a3189fd7161059e9841d155038f83cd9de88f88ee6cf65
+  metadata.gz: a38c19bc286fff4f5776fde2bb1a1de897ea3cdc8498c774691c449de6c2614b229f50a84d6eaf3a89c90af8a99500f6fc8e9237fea9dea7c8234370d4629399
+  data.tar.gz: 9d74ccf3a7202619718e8dd67e19cf53534996738c2e04522e3ba6b67aac51323167e7989577c9ace0c793e729130e984eeffb2eae9d98b8458e5f401249b7cc

data/.yardopts

@@ -6,7 +6,6 @@
 --embed-mixins
 --tag comment
 --hide-tag comment
---exclude lib/natty-ui/ansi_wrapper.rb
 lib/**/*.rb
 -
 README.md

data/README.md

@@ -63,3 +63,7 @@ After that you only need one line of code to have everything together
 ```ruby
 require 'natty-ui'
 ```
+
+## Dependencies
+
+It uses only the fantastic [Terminal.rb](https://rubygems.org/gems/terminal_rb) gem.

data/examples/hbars.rb

@@ -11,7 +11,7 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Print Horizontal Bars[/]' do
 
   ui.space
   ui.hbars values, style: :green, normalize: true, width: 0.5, min: 10
-  ui.puts(
-    'These are the same values but [i]normalized[/i] and printed in half width.'
-  )
+  ui.puts <<~INFO, eol: false
+    These are the same values but [i]normalized[/i] and printed in half width.
+  INFO
 end

data/examples/info.rb

@@ -19,8 +19,8 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Terminal Information[/]' do
     table.add 'Identifier', Terminal.application || 'unidentified'
     table.add 'ANSI support', Terminal.ansi? ? 'yes' : 'no'
     table.add 'Input mode', Terminal.input_mode
-    table.add 'Colors', colors
     table.add 'Screen size', Terminal.size.join(' x ')
+    table.add 'Colors', colors
     table.columns[0].assign(width: 15, padding_right: 2, align: :right)
     table.columns[1].style = %i[bold bright_yellow]
   end

data/examples/key-codes.rb

@@ -2,29 +2,24 @@
 
 require_relative '../lib/natty-ui'
 
-event = nil
-while true
-  ui.temporary do
-    ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Keyboard Key Codes[/]' do
-      ui.puts(
-        "
-        #{
-          if event
-            "#{event.to_a.size < 2 ? ' Key' : 'Keys'}: [bold bright_green]#{
-              event.to_a.map { "[\\#{_1}]" }.join(' ')
-            }[/]
-            Code: [bright_blue]#{event.raw.inspect}[/]"
-          else
-            "Your terminal uses [bright_blue]#{
-              Terminal.input_mode
-            }[/] mode. Press a key!"
-          end
-        }
+ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Keyboard Key Codes[/]' do
+  ui.space
+  ui.puts(
+    "Your terminal uses [bright_blue]#{Terminal.input_mode}[/] mode. Press a key!",
+    '[dim](Exit with ESC)'
+  )
 
-        [faint](Exit with ESC)"
-      )
-    end
-    event = Terminal.read_key_event
-    exit if event.nil? || event.name == 'Esc'
+  ui.space
+  # if you like to have mouse position changes reported then use
+  # 'mouse_move: true' in next line
+  Terminal.on_key_event(mouse: true, focus: true, mouse_move: false) do |event|
+    ui.puts(
+      "#{event.raw.inspect} [dim]→[/dim] [bold bright_green]#{
+        event.to_a.map { "[\\#{_1}]" }.join('+')
+      }#{" @ #{event.position.join(', ')}" if event.position}"
+    )
+    event.name != 'Esc'
   end
+
+  ui.space
 end

data/examples/named-colors.rb

@@ -3,13 +3,15 @@
 require_relative '../lib/natty-ui'
 
 ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Named Colors Support[/]' do
-  ui.puts <<~INFO
-
-    NattyUI supports a series of named color values, such as those  supported by Kitty.
-
+  ui.space
+  ui.puts <<~INFO, eol: false
+    NattyUI supports a series of named color values,
+    such as those supported by Kitty.
   INFO
-  ui.information('Note') do
-    ui.puts('Not all terminal emulators support true-colors.')
+
+  ui.space
+  ui.information 'Note' do
+    ui.puts 'Not all terminal emulators support true-colors.'
   end
 
   ui.space

data/examples/sh.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../lib/natty-ui'
+
+ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Call Shell[/]' do
+  ui.space
+  ui.message 'Pipe this file to [i]cat[/i]; limit to five lines' do
+    File.open(__FILE__) do |file|
+      ui.run 'cat', input: file, preserve_spaces: true, max_lines: 5
+    end
+  end
+
+  ui.space
+  ui.message 'Call [i]cat[/i] with invalid option' do
+    ui.sh 'cat', '-?'
+  end
+end

data/examples/tasks.rb

@@ -17,9 +17,9 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Tasks[/]' do
 
   ui.space
   ui.task 'Actualize Reading List' do
-    ui.puts('This is a simple which actualizes the book reading list.')
+    ui.puts 'This is a simple which actualizes the book reading list.'
 
-    ui.task('Connect to Library') do
+    ui.task 'Connect to Library' do
       do_something
       ui.mark 'Server Found', mark: :checkmark
       ui.task('Login...') { do_something_heavy }
@@ -36,14 +36,14 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Tasks[/]' do
 
     ui.task('Disconnect from Library') { do_something_heavy }
 
-    ui.progress('Read Cover Images', max: 11) do |progress|
+    ui.progress 'Read Cover Images', max: 11 do |progress|
       while progress.value < progress.max
         do_something
         progress.step
       end
     end
 
-    ui.pin('New Books Marked', mark: :checkmark)
+    ui.pin 'New Books Marked', mark: :checkmark
 
     ui.task('Optimize Database') { do_something_heavy }
 

data/examples/vbars.rb

@@ -32,8 +32,8 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Print Vertical Bars[/]' do
 
   ui.space
   ui.vbars values, style: :green, normalize: true, bar_width: 2
-  ui.puts(
-    'These are the same values but [i]normalized[/i] and printed with ' \
-      'a fixed bar width.'
-  )
+  ui.puts <<~INFO, eol: false
+    These are the same values but [i]normalized[/i]
+    and printed with a fixed bar width.
+  INFO
 end

data/lib/natty-ui/attributes.rb

@@ -13,10 +13,10 @@ module NattyUI
     def merge!(**attributes) = attributes.empty? ? self : _assign(attributes)
     alias assign merge!
 
-    # @!visibility private
+    # @private
     def to_hash = _store({})
 
-    # @!visibility private
+    # @private
     def to_h(&block) = block ? _store({}).to_h(&block) : _store({})
 
     private
@@ -506,7 +506,7 @@ module NattyUI
         end
       end
 
-      # @!visibility private
+      # @private
       # @return [String, nil]
       attr_reader :border_chars
 
@@ -549,11 +549,14 @@ module NattyUI
       @attributes = @attributes.dup
     end
   end
+
   private_constant :WithAttributes
 
   module TextWithAttributes
     include WithAttributes
+
     attr_reader :text
+
     def empty? = @text.empty?
     alias _to_s to_s
     private :_to_s
@@ -585,5 +588,6 @@ module NattyUI
       @text = @text.map(&:dup)
     end
   end
+
   private_constant :TextWithAttributes
 end

data/lib/natty-ui/choice.rb

@@ -9,12 +9,12 @@ module NattyUI
       pin_line = NattyUI.lines_written
       draw
       last = @current
-      while (event = Terminal.read_key_event)
+      Terminal.on_key_event do |event|
         case event.name
         when 'Esc', 'Ctrl+c'
-          break nil if @abortable
+          return if @abortable
         when 'Enter', 'Space'
-          break @ret[@current]
+          return @ret[@current]
         when 'Home'
           @current = 0
         when 'End'
@@ -24,11 +24,11 @@ module NattyUI
         when 'Down', 'Tab', 'k', 's'
           @current = 0 if (@current += 1) == @texts.size
         else
-          next unless event.simple?
+          next true unless event.simple?
           c = event.key.ord
           @current = (c - 48).clamp(0, @texts.size - 1) if c.between?(48, 57)
         end
-        next if last == @current
+        next true if last == @current
         pin_line = NattyUI.back_to_line(pin_line, erase: false)
         draw
         last = @current
@@ -62,5 +62,6 @@ module NattyUI
       end
     end
   end
+
   private_constant :Choice
 end

data/lib/natty-ui/dumb_choice.rb

@@ -7,15 +7,15 @@ module NattyUI
     def select
       yield(self) if block_given?
       draw
-      while (event = Terminal.read_key_event)
+      Terminal.on_key_event do |event|
         return if @abortable && %w[Esc Ctrl+c].include?(event.name)
-        next unless event.simple?
+        next true unless event.simple?
         code = event.raw.upcase
         if @ret.size <= 9
-          next unless ('1'..'9').include?(code)
-          code = @ret[code.ord - 49] and break code
+          next true unless ('1'..'9').include?(code)
+          code = @ret[code.ord - 49] and return code
         elsif ('A'..'Z').include?(code)
-          code = @ret[code.ord - 65] and break code
+          code = @ret[code.ord - 65] and return code
         end
       end
     end
@@ -42,5 +42,6 @@ module NattyUI
       @abortable = abortable
     end
   end
+
   private_constant :DumbChoice
 end

data/lib/natty-ui/dumb_options.rb

@@ -7,20 +7,20 @@ module NattyUI
     def select
       yield(self) if block_given?
       draw
-      while (event = Terminal.read_key_event)
+      Terminal.on_key_event do |event|
         return if @abortable && %w[Esc Ctrl+c].include?(event.name)
         return @opts.transform_values(&:last) if event.name == 'Enter'
-        next unless event.simple?
+        next true unless event.simple?
         code = event.raw.upcase
         if @opts.size <= 9
-          next unless ('1'..'9').include?(code)
+          next true unless ('1'..'9').include?(code)
           offset = 49
         elsif ('A'..'Z').include?(code)
           offset = 65
         else
-          next
+          next true
         end
-        key = @opts.keys[code.ord - offset] or next
+        key = @opts.keys[code.ord - offset] or next true
         @opts[key][-1] = !@opts[key][-1]
         @parent.space
         draw
@@ -59,5 +59,6 @@ module NattyUI
       end
     end
   end
+
   private_constant :DumbOptions
 end

data/lib/natty-ui/element.rb

@@ -8,10 +8,10 @@ module NattyUI
   class Element
     include Features
 
-    # @!visibility private
+    # @private
     def columns = @parent.columns - @prefix_width - @suffix_width
 
-    # @!visibility private
+    # @private
     def puts(*objects, **options)
       if @prefix
         options[:prefix] = "#{@prefix}#{options[:prefix]}"
@@ -32,7 +32,7 @@ module NattyUI
       self
     end
 
-    # @!visibility private
+    # @private
     alias to_s inspect
 
     alias _to_s to_s
@@ -46,13 +46,32 @@ module NattyUI
     end
   end
 
+  # Methods for elements with status like {ProgressHelper}, {Section}, {Task}.
+  #
   module WithStatus
+    # @return [Symbol, nil] element's current status
     attr_reader :status
+
+    # @attribute [r] active?
+    # @return [true, false] whether the element is still active
     def active? = @status.nil?
+
+    # @attribute [r] closed?
+    # @return [true, false] whether the element is closed
     def closed? = !active?
+
+    # @attribute [r] closed?
+    # @return [true, false] whether the element is completed
     def ok? = @state == :ok
+
+    # @attribute [r] failed?
+    # @return [true, false] whether the element is completed with failure
     def failed? = @state == :failed
 
+    # Close the element.
+    #
+    # @param [#to_s] text optional message
+    # @return [Element] itself
     def ok(*text)
       return self if @state
       text = [@title] if text.empty? && @title
@@ -62,6 +81,12 @@ module NattyUI
     end
     alias done ok
 
+    # Close the element with a failure.
+    #
+    # @param text [#to_s] optional message
+    # @yield optionally, when block is given
+    # @yieldparam failed [Section] see {Features.failed}
+    # @return [Element] itself
     def failed(*text, &block)
       return self if @state
       _failed