natty-ui 0.34.0 → 1.0.2

data/lib/natty-ui/features.rb

@@ -1,1055 +1,956 @@
 # frozen_string_literal: true
 
 module NattyUI
-  # These are all supported features by {NattyUI} or any other sub- element
-  # like {section}, {message}, {task}, ...
-  #
-  # Any printed text can contain *BBCode*-like embedded ANSI attributes which
-  # will be used when the output terminal supports attributes and colors.
+  # Mixin that provides all UI methods to {NattyUI} and every {Element}.
   #
+  # You never include or extend this module directly.  It is already available
+  # on {NattyUI} (via `extend`) and on every {Element} subclass (via
+  # `include`).  The {Kernel#ui} helper always returns an object that responds
+  # to every method defined here.
   module Features
     #
-    # @!group Printing Methods
-    #
-
-    # Print given text as lines.
-    #
-    # @example Print two lines text, right aligned
-    #   ui.puts "Two lines", "of nice text", align: :right
-    #   # =>    Two lines
-    #   # => of nice text
-    #
-    # @example Print two lines text, with a prefix
-    #   ui.puts "Two lines", "of nice text", prefix: ': '
-    #   # => : Two lines
-    #   # => : of nice text
-    #
-    # @see #pin
-    #
-    # @param text [#to_s]
-    #   one or more convertible objects to print line by line
-    # @param options [{Symbol => Object}]
-    # @option options [:left, :right, :centered] :align (:left)
-    #   text alignment
-    # @option options [true, false] :eol (true)
-    #   whether to respect newline characters
-    #
-    # @return [Features]
-    #   itself
-    def puts(*text, **options)
-      if options.empty?
-        bbcode = true
-        max_width = Terminal.columns
+    # @!group Output methods
+    #
+
+    # Formats and prints text to the terminal.
+    #
+    # Text is word-wrapped to fit the available column width. BBCode-like
+    # markup is interpreted by default (e.g. `[b]bold[/b]`, `[red]text[/fg]`).
+    #
+    # @example Simple output with BBCode markup
+    #   ui.puts 'Hello, [b]world[/b]!'
+    #
+    # @example Centred text with a prefix
+    #   ui.puts 'Step 1 of 3', 'Connect to server',
+    #           align: :center, prefix: '[cyan]→ '
+    #
+    # @example Suppress line breaks and compact spaces
+    #   ui.puts <<~TEXT, eol: false, spaces: false
+    #     Line    one
+    #     Line    two     here
+    #   TEXT
+    #   # => Line one Line two here
+    #
+    # @param text [#to_s, ...] one or more text values to print
+    # @param popts [Hash] a customizable set of print options
+    # @option popts [Boolean] :bbcode (true)
+    #   interpret BBCode-like markup in the text
+    # @option popts [Boolean] :eol (true)
+    #   when `false`, line breaks inside the text are collapsed to spaces
+    # @option popts [Boolean] :spaces (true)
+    #   when `false`, runs of whitespace are compacted to a single space
+    # @option popts [:left, :center, :right, nil] :align
+    #   horizontal text alignment within the available width
+    # @option popts [#to_s, nil] :prefix
+    #   string prepended to the first output line
+    # @option popts [#to_s, nil] :suffix
+    #   string appended to the last output line
+    # @option popts [#to_int, Float, nil] :max_width
+    #   maximum line width in characters; `nil` uses the full terminal width;
+    #   a negative `#to_int` value is an offset from the terminal width;
+    #   a `Float` in `0.0..1.0` is a fraction of the terminal width
+    # @return [Features] itself
+    def puts(*text, **popts)
+      return if text.empty?
+
+      popts.delete(:pin) # ignore!
+
+      if popts.empty?
+        popts[:bbcode] = true
+        popts[:width] = max_width = columns
+        return self if max_width < 1
       else
-        bbcode = true if (bbcode = options[:bbcode]).nil?
-        ignore_newline = options[:eol] == false || options[:ignore_newline]
+        popts[:bbcode] = true unless popts.key?(:bbcode)
+        max_width = __determine_max_width(popts.delete(:max_width))
+        return self if max_width < 1
 
-        if (max_width = options[:max_width]).nil?
-          max_width = Terminal.columns
-        elsif max_width < 1
-          if max_width > 0
-            max_width *= Terminal.columns
-          elsif max_width < 0
-            max_width += Terminal.columns
-          else
-            return self
-          end
+        unless (prefix = popts.delete(:prefix)).nil?
+          prefix = StrConst[prefix] unless StrConst === prefix
+          return self if (max_width -= prefix.width) < 1
         end
 
-        return self if max_width <= 0
-
-        prefix_width =
-          if (prefix = options[:prefix])
-            prefix = Ansi.bbcode(prefix) if bbcode
-            options[:prefix_width] || Text.width(prefix, bbcode: false)
-          else
-            0
-          end
-
-        if (first_line = options[:first_line_prefix])
-          first_line = Ansi.bbcode(first_line) if bbcode
-          first_line_width =
-            options[:first_line_prefix_width] ||
-              Text.width(first_line, bbcode: false)
-
-          if prefix_width < first_line_width
-            prefix_next = "#{prefix}#{' ' * (first_line_width - prefix_width)}"
-            prefix = first_line
-            prefix_width = first_line_width
-          else
-            prefix_next = prefix
-            prefix =
-              if first_line_width < prefix_width
-                first_line + (' ' * (prefix_width - first_line_width))
-              else
-                first_line
-              end
+        if (cprefix = popts.delete(:cprefix)).nil?
+          cprefix = prefix
+        elsif cprefix == true
+          prefix, cprefix = StrConst.spacer(prefix.width), prefix if prefix
+        else
+          cprefix = StrConst[cprefix] unless StrConst === cprefix
+          unless prefix
+            return self if (max_width -= cprefix.width) < 1
+            prefix = StrConst.spacer(cprefix.width)
           end
         end
 
-        max_width -= prefix_width
-
-        if (suffix = options[:suffix])
-          suffix = Ansi.bbcode(suffix) if bbcode
-          max_width -=
-            options[:suffix_width] || Text.width(suffix, bbcode: false)
+        unless (suffix = popts.delete(:suffix)).nil?
+          suffix = StrConst[suffix] unless StrConst === suffix
+          return self if (max_width -= suffix.width) < 1
         end
-      end
-
-      return self if max_width <= 0
 
-      lines =
-        Text.each_line_with_size(
-          *text,
-          limit: max_width,
-          bbcode: bbcode,
-          ansi: Terminal.ansi?,
-          ignore_newline: ignore_newline
-        )
-      tail = options[:tail] and lines = lines.to_a.last(tail)
-      @__eol ||= Terminal.ansi? ? "\e[m\n" : "\n"
-
-      if (align = options[:align]).nil?
-        lines.each do |line, _|
-          Terminal.print(prefix, line, suffix, @__eol, bbcode: false)
-          @lines_written += 1
-          prefix, prefix_next = prefix_next, nil if prefix_next
+        if (csuffix = popts.delete(:csuffix)).nil?
+          csuffix = suffix
+        elsif csuffix == true
+          suffix, csuffix = StrConst.spacer(suffix.width), suffix if suffix
+        else
+          csuffix = StrConst[csuffix] unless StrConst === csuffix
+          return self if (max_width -= csuffix.width) < 1
+          suffix = StrConst.spacer(csuffix.width)
         end
-        return self
-      end
 
-      unless options[:expand]
-        max_width = (lines = lines.to_a).max_by(&:last)[-1]
+        popts[:width] = max_width
       end
 
-      case align
-      when :right
-        lines.each do |line, width|
-          Terminal.print(
-            prefix,
-            ' ' * (max_width - width),
-            line,
-            suffix,
-            @__eol,
-            bbcode: false
-          )
-          @lines_written += 1
-          prefix, prefix_next = prefix_next, nil if prefix_next
-        end
-      when :centered
-        lines.each do |line, width|
-          space = max_width - width
-          Terminal.print(
-            prefix,
-            ' ' * (lw = space / 2),
-            line,
-            ' ' * (space - lw),
-            suffix,
-            @__eol,
-            bbcode: false
-          )
-          @lines_written += 1
-          prefix, prefix_next = prefix_next, nil if prefix_next
-        end
-      else
-        lines.each do |line, width|
-          Terminal.print(
-            prefix,
-            line,
-            ' ' * (max_width - width),
-            suffix,
-            @__eol,
-            bbcode: false
-          )
-          @lines_written += 1
-          prefix, prefix_next = prefix_next, nil if prefix_next
+      popts[:ansi] = Terminal.ansi?
+      lines = Text.format(*text, **popts)
+      if cprefix || csuffix
+        lines.map! do |line|
+          line = "#{cprefix}#{line}#{csuffix}"
+          cprefix, prefix = prefix, nil if prefix
+          csuffix, suffix = suffix, nil if suffix
+          line
         end
       end
+      Terminal.puts(*lines, bbcode: false)
+      @lines_written += lines.size
       self
     end
 
-    # Print given text with a decoration mark.
-    #
-    # @param text (see puts)
-    # @param mark [Symbol, #to_s]
-    #   marker type
-    #
-    # @return (see puts)
-    def mark(*text, mark: :default, **options)
-      mark = Theme.current.mark(mark)
-      options[:first_line_prefix] = mark
-      options[:first_line_prefix_width] = mark.width
-      puts(*text, **options)
-    end
-
-    # Print given text as lines like {#puts}. Used in elements with temporary
-    # output like {#task} the text will be kept ("pinned").
-    #
-    # It can optionally have a decoration marker in first line like {#mark}.
+    # Prints one or more blank lines.
     #
-    # @example Print two lines decorated as information which are pinned
-    #   ui.task 'Do something important' do |task|
-    #     # ...
-    #     task.pin("This is text", "which is pinned", mark: :information)
-    #     # ...
-    #   end
-    #   # => ✓ Do something important
-    #   # =>   𝒊 This is text
-    #   # =>     which is pinned.
+    # @example Print a single blank line
+    #   ui.space
     #
-    # @param (see #puts)
-    # @param mark (see #mark)
-    # @option (see #puts)
+    # @example Print three blank lines
+    #   ui.space 3
     #
-    # @return (see puts)
-    def pin(*text, mark: nil, **options)
-      mark(*text, mark: mark, pin: true, **options)
-    end
-
-    # Print given text as a quotation.
-    #
-    # @param text (see puts)
-    #
-    # @return (see puts)
-    def quote(*text)
-      width = columns * 0.75
-      quote = Theme.current.mark(:quote)
-      puts(
-        *text,
-        prefix: quote,
-        prefix_width: quote.width,
-        max_width: width < 20 ? nil : width.round
-      )
-    end
-
-    # Print given text as a heading.
-    #
-    # There are specific shortcuts for heading levels:
-    # {#h1}, {#h2}, {#h3}, {#h4}, {#h5}, {#h6}.
-    #
-    # @example Print a level 1 heading
-    #   ui.heading(1, 'This is a H1 heading element')
-    #   # => ╴╶╴╶─═══ This is a H1 heading element ═══─╴╶╴╶
-    #
-    # @param level [#to_i]
-    #   heading level, one of 1..6
-    # @param text (see puts)
-    #
-    # @return (see puts)
-    def heading(level, *text)
-      prefix, suffix = Theme.current.heading(level)
-      puts(
-        *text,
-        max_width: columns,
-        prefix: prefix,
-        prefix_width: prefix.width,
-        suffix: suffix,
-        suffix_width: suffix.width,
-        align: :centered
-      )
+    # @param count [#to_int] number of blank lines to print
+    # @return (see #puts)
+    def space(count = 1)
+      (count = count.to_int) < 1 ? self : puts(" \n" * count)
     end
 
-    # Print given text as a H1 {#heading}.
+    # Prints text with a leading mark symbol.
     #
-    # @param text (see puts)
+    # @example Default mark
+    #   ui.mark 'Item one'
     #
-    # @return (see puts)
-    def h1(*text) = heading(1, *text)
-
-    # Print given text as a H2 {#heading}.
+    # @example Named symbol mark
+    #   ui.mark 'Done!', mark: :checkmark
     #
-    # @param text (see puts)
+    # @example Custom string mark
+    #   ui.mark 'Warning', mark: '[bright_red]!'
     #
-    # @return (see puts)
-    def h2(*text) = heading(2, *text)
+    # @param text (see #puts)
+    # @param mark [Symbol, #to_s] mark to use as prefix:
+    #   - `:default` — blue bullet •
+    #   - `:checkmark` — green check mark ✓
+    #   - `:item` — dim bullet •
+    #   - any other object — converted via `#to_s` and used as the literal prefix
+    # @param popts [Hash] a customizable set of print options, see {#puts}
+    # @return (see #puts)
+    def mark(*text, mark: :default, **popts)
+      Mark.render(self, mark, *text, **popts)
+    end
 
-    # Print given text as a H3 {#heading}.
+    # Prints text with a green check-mark prefix.
+    #
+    # Shorthand for `mark(*text, mark: :checkmark, **options)`.
     #
-    # @param text (see puts)
+    # @example
+    #   ui.ok 'All tests passed'
     #
-    # @return (see puts)
-    def h3(*text) = heading(3, *text)
+    # @param text (see #puts)
+    # @param popts (see #mark)
+    # @return (see #puts)
+    def ok(*text, **popts) = mark(*text, mark: :checkmark, **popts)
 
-    # Print given text as a H4 {#heading}.
+    # Prints text with a mark that persists after a {Temporary} element closes.
+    #
+    # Identical to {#mark} but survives when the surrounding {Temporary} element
+    # (see {#temporary}, {#task}, {#progress})  is erased.
     #
-    # @param text (see puts)
+    # @example Pin a success note inside a task
+    #   ui.task 'Deploy' do
+    #     do_deploy
+    #     ui.pin 'Deployed to production', mark: :checkmark
+    #   end
     #
-    # @return (see puts)
-    def h4(*text) = heading(4, *text)
+    # @param (see mark)
+    # @return (see #puts)
+    def pin(*text, mark: :default, **popts)
+      mark(*text, mark:, pin: true, **popts)
+    end
 
-    # Print given text as a H5 {#heading}.
+    # Prints text with a left-side quotation border.
     #
-    # @param text (see puts)
+    # @example
+    #   ui.quote "To be or not to be,\nthat is the question."
     #
-    # @return (see puts)
-    def h5(*text) = heading(5, *text)
+    # @param (see #puts)
+    # @return (see #puts)
+    def quote(*text) = Quote.render(self, *text)
 
-    # Print given text as a H6 {#heading}.
+    # Prints a heading at the given level.
     #
-    # @param text (see puts)
+    # Six heading levels are supported (similarly to HTML `<h1>`–`<h6>`).
+    # Use the shorthand helpers {#h1}–{#h6} for convenience.
     #
-    # @return (see puts)
-    def h6(*text) = heading(6, *text)
-
-    # Print a horizontal rule.
+    # @example Large heading
+    #   ui.heading 1, 'Chapter One'
     #
-    # @example Print double line
-    #   ui.hr :double
+    # @example Sub-heading
+    #   ui.heading 3, 'Section [i]Overview[/i]'
     #
-    # @param type [Symbol]
-    #   border type
+    # @param level [#to_int] heading level, `1` (largest) to `6` (smallest)
+    # @param title [#to_s] heading text
+    # @return (see #puts)
+    def heading(level, title) = Heading.render(self, level, title)
+
+    # Prints a level-1 heading.
     #
-    # @return (see puts)
-    def hr(type = :default)
-      theme = Theme.current
-      bc = theme.border(type)[10]
-      puts("#{theme.heading_sytle}#{bc * columns}")
-    end
+    # @param title (see #heading)
+    # @return (see #puts)
+    def h1(title) = heading(1, title)
 
-    # Print one or more space lines.
+    # Prints a level-2 heading.
     #
-    # @param count [#to_i]
-    #   lines to print
+    # @param title (see #heading)
+    # @return (see #puts)
+    def h2(title) = heading(2, title)
+
+    # Prints a level-3 heading.
     #
-    # @return (see puts)
-    def space(count = 1)
-      (count = count.to_i).positive? ? puts("\n" * count) : self
-    end
+    # @param title (see #heading)
+    # @return (see #puts)
+    def h3(title) = heading(3, title)
 
-    # Print given items as list (like 'ls' command).
+    # Prints a level-4 heading.
     #
-    # Each list item will optionally be decorated with the given glyph as:
+    # @param title (see #heading)
+    # @return (see #puts)
+    def h4(title) = heading(4, title)
+
+    # Prints a level-5 heading.
     #
-    # - `Integer` as the start value for a numbered list
-    # - `Symbol` as the start symbol
-    # - `:hex` to create a hexadecimal numbered list
-    # - any text as prefix
+    # @param title (see #heading)
+    # @return (see #puts)
+    def h5(title) = heading(5, title)
+
+    # Prints a level-6 heading.
     #
-    # @example Print all Ruby files as a numbered list
-    #   ui.ls Dir['*/**/*.rb'], glyph: 1
+    # @param title (see #heading)
+    # @return (see #puts)
+    def h6(title) = heading(6, title)
+
+    # Prints a horizontal rule spanning the available width.
     #
-    # @example Print all Ruby files as a bullet point list (with green bullets)
-    #   ui.ls Dir['*/**/*.rb'], glyph: '[green]•[/fg]'
+    # @example Default rule
+    #   ui.hr
     #
-    # @param items [#to_s]
-    #   one or more convertible objects to list
-    # @param compact [true, false]
-    #   whether the compact display format should be used
-    # @param glyph [Integer, :hex, Symbol, #to_s]
-    #   glyph to be used as prefix
+    # @example Named style
+    #   ui.hr :double
     #
-    # @return (see puts)
+    # @example Repeated string
+    #   ui.hr '+-'
+    #
+    # @param kind [Symbol, #to_s, nil]
+    #   - `nil` — default style
+    #   - `Symbol` — named style: `:single`, `:double`, `:heavy`
+    #   - `#to_s` — string repeated to fill the available width
+    # @return (see #puts)
+    def hr(kind = nil) = HorizontalRule.render(self, kind)
+
+    # Prints a multi-column list.
+    #
+    # Items are arranged in columns to fit the terminal width.
+    #
+    # @example Plain list
+    #   ui.ls 'Alice', 'Bob', 'Carol'
+    #
+    # @example Hex-numbered list
+    #   ui.ls 'red', 'green', 'blue', glyph: :hex
+    #
+    # @param items [#to_s, ...] items to list; nested arrays are flattened
+    # @param compact [Boolean] `true` = ordered in columns,
+    #   `false` = ordered left to right per row
+    # @param glyph prefix applied to every item:
+    #   - `nil` / `false` — no prefix
+    #   - `Integer` — decimal counter starting at the given number
+    #   - `Symbol` — alphabetic sequence starting at the given symbol
+    #     (e.g. `:a` → `a`, `b`, `c`, …)
+    #   - `:hex` — zero-based hex counter (`01`, `02`, …)
+    #   - a `#to_s` value matching a hex value — hex counter at the given
+    #     offset (e.g. `"0x0a"` starts at `0a`)
+    #   - any other `#to_s` value — used as a literal prefix for every item
+    # @return (see #puts)
     def ls(*items, compact: true, glyph: nil)
       return self if items.empty?
-      renderer = compact ? CompactLSRenderer : LSRenderer
-      puts(*renderer.lines(items, glyph, columns))
-    end
-
-    # Generate and print a table.
-    # See {Table} for much more details about table generation.
-    #
-    # @example Draw a very simple 3x4 table with complete borders
-    #   ui.table(border: :default, border_around: true, padding: [0, 1]) do |table|
-    #     table.add 1, 2, 3, 4
-    #     table.add 5, 6, 7, 8
-    #     table.add 9, 10, 11, 12
-    #   end
-    #
-    # @param attributes [{Symbol => Object}]
-    #   attributes for the table and default attributes for table cells
-    # @option attributes [Symbol] :border (nil)
-    #   kind of border,
-    #   see {Table::Attributes}
-    # @option attributes [Enumerable<Symbol>] :border_style (nil)
-    #   style of border,
-    #   see {Table::Attributes}
-    # @option attributes [true, false] :border_around (false)
-    #   whether the table should have a border around,
-    #   see {Table::Attributes}
-    # @option attributes [:left, :right, :centered] :position (false)
-    #   where to align the table,
-    #   see {Table::Attributes}
-    #
-    # @yieldparam table [Table]
-    #   helper to define the table layout
-    #
-    # @return (see puts)
-    def table(**attributes)
-      return self unless block_given?
-      yield(table = Table.new(**attributes))
-      puts(
-        *TableRenderer[table, columns],
-        align: table.attributes.position,
-        expand: true
-      )
-    end
-
-    # Print text in columns.
-    # This is a shorthand to define a {Table} with a single row.
-    #
-    # @param columns [#to_s]
-    #   two or more convertible objects to print side by side
-    # @param attributes (see table)
-    # @option attributes (see table)
-    # @option attributes [Integer] :width (nil)
-    #   width of a column,
-    #   see {Attributes::Width}
-    #
-    # @yieldparam row [Table::Row]
-    #   helper to define the row layout
-    #
-    # @return (see puts)
-    def cols(*columns, **attributes)
-      tab_att, att = Utils.split_table_attr(attributes)
-      table(**tab_att) do |table|
-        table.add do |row|
-          columns.each { row.add(_1, **att) }
-          yield(row) if block_given?
-        end
-      end
+      puts(*(compact ? CompactLS : LS).lines(columns, items, glyph))
     end
 
-    # Print a text division with attributes.
-    # This is a shorthand to define a {Table} with a single cell.
-    #
-    # @param text (see puts)
-    # @param attributes [{Symbol => Object}]
-    #   attributes for the division
-    # @option attributes [:left, :right, :centered] :align (:left)
-    #   text alignment,
-    #   see {Attributes::Align}
-    # @option attributes [Integer, Enumerable<Integer>] :padding (nil)
-    #   text padding,
-    #   see {Attributes::Padding}
-    # @option attributes [Enumerable<Symbol>] :style (nil)
-    #   text style,
-    #   see {Attributes::Style}
-    # @option attributes [Integer] :width (nil)
-    #   width of the cell,
-    #   see {Attributes::Width}
-    # @option attributes (see table)
-    #
-    # @return (see puts)
-    def div(*text, **attributes)
-      return self if text.empty?
-      tab_att, att = Utils.split_table_attr(attributes)
-      tab_att[:border_around] = true
-      table(**tab_att) { |table| table.add { _1.add(*text, **att) } }
-    end
-
-    # Dump given values as vertical bars.
-    #
-    # @example Draw green bars
-    #   ui.vbars 1..10, style: :green
-    #
-    # @example Draw very big bars
-    #   ui.vbars 1..10, bar_width: 5, height: 20
-    #
-    # @param values [#to_a, Array<Numeric>] values to print
-    # @param normalize [true, false] whether the values should be normalized
-    # @param height [Integer] output height
-    # @param bar_width [:auto, :min, Integer] with of each bar
-    # @param style [Symbol, Array<Symbol>, nil] drawing style
-    #
-    # @raise [ArgumentError] if any value is negative
-    #
-    # @return (see puts)
+    # Prints a vertical bar chart.
+    #
+    # All values must be non-negative.
+    #
+    # @example Simple bar chart
+    #   ui.vbars [3, 7, 2, 9, 5]
+    #
+    # @example Normalised chart with custom height
+    #   ui.vbars [10, 40, 25, 60], normalize: true, height: 15
+    #
+    # @param values [#each]
+    #   collection of non-negative `Numeric` values
+    # @param min [Numeric, nil]
+    #   lower bound for scaling; `nil` uses the data minimum
+    # @param max [Numeric, nil]
+    #   upper bound for scaling; `nil` uses the data maximum
+    # @param normalize [Boolean]
+    #   when `true` applies min-max normalization;
+    #   when `false` scales each bar relative to the maximum value
+    # @param height [#to_int]
+    #   chart height in lines (minimum 3; default: 10)
+    # @param bar_width [#to_int, :auto]
+    #   width of each bar in characters; `:auto` fits the graph in available
+    #   terminal width
+    # @param style [Symbol, String, Array<Style>, Array<String>, nil]
+    #   ANSI style applied to the bars
+    # @return (see #puts)
     def vbars(
       values,
+      min: nil,
+      max: nil,
       normalize: false,
       height: 10,
-      bar_width: :auto,
+      bar_width: 3,
       style: nil
     )
-      return self if (values = values.to_a).empty?
-      if values.any?(&:negative?)
-        raise(ArgumentError, 'values can not be negative')
-      end
-      puts(
-        *VBarsRenderer.lines(
-          values,
-          columns,
-          height,
-          normalize,
-          bar_width,
-          Terminal.ansi? ? style : nil
-        )
-      )
+      bars = VBars.new(values, min, max, normalize)
+      return self if bars.empty?
+      raise(ArgumentError, 'values can not be negative') unless bars.valid?
+      puts(*bars.lines(columns, height, bar_width, style), bbcode: false)
     end
 
-    # Dump given values as horizontal bars.
-    #
-    # @example Draw green bars
-    #   ui.hbars 1..10, style: :green
+    # Prints a horizontal bar chart.
     #
-    # @example Draw bars in half sreen width
-    #   ui.hbars 1..10, style: :blue, width: 0.5
+    # All values must be non-negative.
     #
-    # @param values [#to_a, Array<Numeric>] values to print
-    # @param min [#to_f] start value
-    # @param max [#to_f] end value
-    # @param normalize [true, false] whether the values should be normalized
-    # @param text [true, false] whether the values should be printed too
-    # @param width [:auto, :min, Integer] with of each bar
-    # @param style [Symbol, Array<Symbol>, nil] bar drawing style
-    # @param text_style [Symbol, Array<Symbol>, nil] text style
+    # @example Simple horizontal chart
+    #   ui.hbars [3, 7, 2, 9, 5]
     #
-    # @raise [ArgumentError] if any value is negative
+    # @example Chart without value labels
+    #   ui.hbars [10, 40, 25, 60], text: false, normalize: true
     #
-    # @return (see puts)
+    # @param values (see #vbars)
+    # @param min (see #vbars)
+    # @param max (see #vbars)
+    # @param normalize (see #vbars)
+    # @param style (see #vbars)
+    # @param width [#to_int, Float, :auto] maximum bar width in characters;
+    #   a `Float` is a fraction of available width; `:auto` fills available width
+    # @param text [Boolean] when `true` prints the numeric value next to each bar
+    # @param text_style [Symbol, String, Array<Style>, Array<String>, nil]
+    #   ANSI style applied to the value labels
+    # @return (see #puts)
     def hbars(
       values,
       min: nil,
       max: nil,
       normalize: false,
-      text: true,
       width: :auto,
       style: nil,
+      text: true,
       text_style: nil
     )
-      return self if (values = values.to_a).empty?
-      if values.any?(&:negative?)
-        raise(ArgumentError, 'values can not be negative')
-      end
-      style = text_style = nil unless Terminal.ansi?
-      renderer = HBarsRenderer.new(values, min, max)
-      renderer.with_text(text_style) if text
-      puts(*renderer.lines(Utils.as_size(3..columns, width), style, normalize))
+      bars = HBars.new(values, min, max, normalize)
+      return self if bars.empty?
+      raise(ArgumentError, 'values can not be negative') unless bars.valid?
+      bars.with_text(text_style) if text
+      puts(*bars.lines(columns, width, style), bbcode: false)
     end
 
-    # Dynamically display a task progress.
-    # When a `max` parameter is given the progress will be displayed as a
-    # progress bar below the `title`. Otherwise the progress is displayed just
-    # by accumulating dots.
-    #
-    # @example Display a progress bar
-    #   ui.progress('Download file', max: 1024) do |progress|
-    #     while progress.value < progress.max
-    #       # just to simulate the download
-    #       sleep(0.1)
-    #       bytes_read = rand(10..128)
-    #
-    #       # here we actualize the progress
-    #       progress.value += bytes_read
-    #     end
-    #   end
+    # Renders a {Table} to the terminal.
+    #
+    # The method yields a {Table} object for population; if no block is given
+    # nothing is rendered.
     #
-    # @example Display simple progress
-    #   progress = ui.progress 'Check some stuff'
-    #   10.times do
-    #     # simulate some work
-    #     sleep 0.1
+    # Border name symbols:
+    # `:rounded` (default), `:single`, `:double`, `:heavy`,
+    # `:single_double`, `:double_single`, `:single_heavy`, `:heavy_single`
     #
-    #     # here we actualize the progress
-    #     progress.step
+    # @example Simple table with a double outer frame
+    #   ui.table border_frame: :double do |t|
+    #     t.add_row '[b]Name', '[b]Score', align: :center
+    #     t.add_row 'Alice', 42
+    #     t.add_row 'Bob',   17
     #   end
-    #   progress.ok 'Stuff checked ok'
-    #
-    # @overload progress(title, max: nil, pin: false)
-    #   @param title [#to_s]
-    #     title text to display
-    #   @param max [#to_f]
-    #     expected maximum value
-    #   @param pin [true, false]
-    #     whether the final progress state should be "pinned" to parent element
-    #
-    #   @return [ProgressHelper]
-    #     itself
-    #
-    # @overload progress(title, max: nil, pin: false, &block)
-    #   @param title [#to_s]
-    #     title text
-    #   @param max [#to_f]
-    #     expected maximum value
-    #   @param pin [true, false]
-    #     whether the final progress state should be "pinned" to parent element
-    #
-    #   @yieldparam progress [ProgressHelper]
-    #     itself
-    #
-    #   @return [Object]
-    #     the result of the given block
-    def progress(title, max: nil, pin: false, &block)
-      progress =
-        if Terminal.ansi?
-          Progress.new(self, title, max, pin)
-        else
-          DumbProgress.new(self, title, max)
-        end
-      block ? __with(progress, &block) : progress
+    #
+    # @option options [:default, :none, :single, :double, :heavy] :border (:default)
+    #   default border used for all border parts
+    # @option options [nil, :none, :single, :double, :heavy] :border_frame
+    #   outer frame; falls back to `:border`
+    # @option options [nil, :none, :single, :double, :heavy] :border_vertical
+    #   vertical column separators; falls back to `:border`
+    # @option options [nil, :none, :single, :double, :heavy] :border_horizontal
+    #   horizontal row separators; falls back to `:border`
+    # @option options [Symbol, String, Array<Style>, Array<String>, nil] :border_style
+    #   ANSI style applied to all borders
+    # @option options [Symbol, Array<Symbol>] :frame (:all)
+    #   which frame sides to draw: `:all` or an enumerable of
+    #   `:top`, `:right`, `:bottom`, `:left`
+    # @option options [#to_int, Float, :max, nil] :width
+    #   `:max` expands to the full terminal width;
+    #   a negative `#to_int` is an offset from the terminal width;
+    #   a `Float` is a fraction of the terminal width
+    # @yield [table] a {Table} instance to populate with rows and cells
+    # @yieldparam table [Table] the table
+    # @return [Features]
+    def table(**options)
+      return self unless block_given?
+      yield(table = Table.new)
+      return self if table.empty?
+      puts(*TableRenderer.lines(columns, table, **options), bbcode: false)
     end
 
-    # Execute a program.
-    #
-    # @example Execute a simple command
-    #   ui.sh 'ls'
-    #
-    # @example Execute a command wih arguments
-    #   ret = ui.sh('curl', '--version')
-    #   raise('Curl not found') unless ret&.success?
     #
-    # @example Execute shell commands
-    #   ui.sh "mkdir 'test' && cd 'test'"
-    #
-    # @example Execute a command with environment variables
-    #   ui.sh({'ENV' => 'test'}, 'rails')
-    #
-    # @see run
+    # @!endgroup
     #
-    # @param cmd (see run)
-    # @param preserve_spaces (see run)
-    # @param options (see run)
-    # @return [Process::Status]
-    #   when command was executed
-    # @return [nil]
-    #   in error case (like command not found)
-    def sh(*cmd, preserve_spaces: false, **options)
-      ShellRenderer.sh(self, cmd, options, preserve_spaces)
-    end
-
-    # Execute a shell program and return output. Limit the lines displayed.
-    #
-    # @example Capture output and error
-    #   status, out, err = ui.run('ls ./ && ls ./this_does_not_exist')
-    #   # => #<Process::Status: pid 25562 exit 1>
-    #   # => [...] # the output of first `ls`
-    #   # => ["ls: ./this_does_not_exist: No such file or directory"]
-    #
-    # @see sh
-    #
-    # @param cmd [String]
-    #   command and optional arguments
-    # @param preserve_spaces [true,false]
-    #   whether the spaces and tabs of the output should be preserve
-    # @param max_lines [Integer]
-    #   limit of displayed lines
-    # @param options [Hash] executions options
-    # @return [[Process::Status, Array<String>, Array<String>]]
-    #   process status, output and error output when command was executed
-    # @return [nil]
-    #   in error case (like command not found)
-    def run(*cmd, preserve_spaces: false, max_lines: 10, **options)
-      result =
-        ShellRenderer.run(
-          self,
-          cmd,
-          options,
-          preserve_spaces,
-          max_lines.clamp(1, Terminal.rows)
-        )
-      result if result[0]
-    end
 
     #
-    # @!endgroup
+    # @!group Section elements
     #
 
+    # Creates a {Temporary} element whose output is erased when it closes.
+    #
+    # @example Manual close
+    #   tmp = ui.temporary
+    #   ui.puts 'Loading…'
+    #   sleep 1
+    #   tmp.end   # erases "Loading…"
     #
-    # @!group Sub-Elements
+    # @example Block form
+    #   ui.temporary do
+    #     ui.puts 'Thinking…'
+    #     sleep 2
+    #   end  # "Thinking…" is erased here
     #
+    # @yield [temp] the {Temporary} element
+    # @yieldparam temp [Temporary]
+    # @return [Object] return value of the block
+    # @return [Temporary] itself, if no block is specified
+    def temporary(&) = __with(Temporary.new(self), &)
 
-    # Create a visually separated section for the output of text elements.
-    # Like any other {Element} sections support all {Features}.
+    # Creates a {Margin} element that adds horizontal and vertical whitespace.
     #
     # @example
-    #   ui.section do |section|
-    #     section.h1 'About Sections'
-    #     section.space
-    #     section.puts 'Sections are areas of text elements.'
-    #     section.puts 'You can use any other feature inside such an area.'
+    #   ui.margin 0, 0.25 do
+    #     ui.puts 'This text has 25% width horizontal margin.'
     #   end
-    #   # => ╭────╶╶╶
-    #   # => │ ╴╶╴╶─═══ About Sections ═══─╴╶╴╶
-    #   # => │
-    #   # => │ Sections are areas of text elements.
-    #   # => │ You can use any other feature inside such an area.
-    #   # => ╰──── ─╶╶╶
     #
-    # @param text [#to_s]
-    #   convertible objects to print line by line
+    # @overload margin(value)
+    #   Margin for all sides.
+    #   @param value [#to_int, Float] margin of all four sides
+    #
+    # @overload margin(vertical = 0, horizontal = 1)
+    #   Seperate vertical and horizontal margin.
+    #   @param vertical [#to_int] top and bottom margin
+    #   @param horizontal [#to_int, Float] left and right margin
+    #
+    # @overload margin(top, horizontal, bottom)
+    #   Seperate top, bottom and horizontal margin.
+    #   @param top [#to_int] top margin
+    #   @param horizontal [#to_int, Float] left and right margin
+    #   @param bottom [#to_int] bottom margin
+    #
+    # @overload margin(top, right, bottom, left)
+    #   Seperate margins.
+    #   @param top [#to_int] top margin
+    #   @param right [#to_int, Float] right margin
+    #   @param bottom [#to_int] bottom margin
+    #   @param left [#to_int, Float] left margin
+    #
+    # @overload margin(top: 0, right: 0, bottom: 0, left: 0)
+    #   Specific margin.
+    #   @param top [#to_int] top margin
+    #   @param right [#to_int, Float] right margin
+    #   @param bottom [#to_int] bottom margin
+    #   @param left [#to_int, Float] left margin
+    #
+    # @yield [margin] the {Margin} element
+    # @yieldparam margin [Margin]
+    # @return [Object] return value of the block
+    # @return [Margin] itself, if no block is specified
+    def margin(*, &) = __with(Margin.new(self, *), &)
+
+    # Creates a {Section} element — a bordered container with an optional title.
+    #
+    # @example Manual close
+    #   sec = ui.section 'Results'
+    #   ui.ok 'All good'
+    #   sec.end
+    #
+    # @example Block form with title
+    #   ui.section 'Summary' do
+    #     ui.puts '3 files processed.'
+    #   end
     #
-    # @yieldparam section [Section]
-    #   itself
+    # @example Block form without title
+    #   ui.section do
+    #     ui.puts 'Anonymous section content.'
+    #   end
     #
-    # @return [Object]
-    #   the result of the given block
-    def section(*text, &block) = __sec(:default, nil, text, &block)
-
-    # @!macro like_msg
-    #   @see section
-    #   @param title [#to_s]
-    #     title to print as section head
-    #   @param text (see section)
-    #   @yieldparam (see section)
-    #   @return (see section)
+    # @param title [#to_s, nil]
+    #   optional header text
+    # @param type [:default, :message, :information, :warning, :error, :fatal]
+    #   visual style of the section
+    # @param border [:default, :rounded, :single, :double, :heavy]
+    #   border style
+    # @yield [section] the {Section} element
+    # @yieldparam section [Section]
+    # @return [Object] return value of the block
+    # @return [Section] itself, if no block is specified
+    def section(title = nil, type: :default, border: :default, &)
+      __with(Section.new(self, title, type, border), &)
+    end
+    alias begin section
 
-    # Create a visually separated section with a title for the output of text
-    # elements.
+    # Creates a {Section} with `:message` styling.
     #
-    # @macro like_msg
-    def message(title, *text, &block) = __sec(:message, title, text, &block)
+    # @param title [#to_s] header text
+    # @param border (see #section)
+    # @yield (see #section)
+    # @yieldparam (see #section)
+    # @return (see #section)
+    def message(title, border: :default, &)
+      section(title, border:, type: :message, &)
+    end
     alias msg message
 
-    # Create a visually separated section marked as informational with a title
-    # for the output of text elements.
+    # Creates a {Section} with `:information` styling.
     #
-    # @macro like_msg
-    def information(title, *text, &block)
-      __tsec(:information, title, text, &block)
+    # @param (see #message)
+    # @yield (see #message)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def information(title, border: :default, &)
+      section(title, border:, type: :information, &)
     end
     alias info information
 
-    # Create a visually separated section marked as a warning with a title for
-    # the output of text elements.
+    # Creates a {Section} with `:warning` styling.
     #
-    # @macro like_msg
-    def warning(title, *text, &block) = __tsec(:warning, title, text, &block)
+    # @param (see #message)
+    # @yield (see #message)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def warning(title, border: :default, &)
+      section(title, border:, type: :warning, &)
+    end
     alias warn warning
 
-    # Create a visually separated section marked as an error with a title for
-    # the output of text elements.
+    # Creates a {Section} with `:error` styling.
     #
-    # @macro like_msg
-    def error(title, *text, &block) = __tsec(:error, title, text, &block)
-    alias err error
+    # @param (see #message)
+    # @yield (see #message)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def error(title, border: :default, &)
+      section(title, border:, type: :error, &)
+    end
 
-    # Create a visually separated section marked as a failure with a title for
-    # the output of text elements.
+    # Creates a {Section} with `:fatal` styling.
     #
-    # @macro like_msg
-    def failed(title, *text, &block) = __tsec(:failed, title, text, &block)
-
-    # Create a framed section.
-    #
-    # @param text (see section)
-    # @param align [:left, :right, :centered]
-    #   text alignment,
-    #   see {Attributes::Align}
-    # @param border [Symbol]
-    #   kind of border,
-    #   see {Attributes::Border}
-    # @param border_style [Enumerable<Symbol>]
-    #   style of border,
-    #   see {Attributes::BorderStyle}
-    #
-    # @yieldparam frame [Framed] itself
-    #
-    # @return (see section)
-    def framed(*text, align: :left, border: :default, border_style: nil, &block)
-      __with(
-        Framed.new(
-          self,
-          Utils.align(align),
-          Theme.current.border(border),
-          Utils.style(border_style),
-          text
-        ),
-        &block
-      )
+    # @param (see #message)
+    # @yield (see #message)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def fatal(title, border: :default, &)
+      section(title, border:, type: :fatal, &)
     end
 
-    # Generate a task section.
+    # Creates a {Frame} element — a bordered box with an optional title.
     #
-    # @param title [#to_s]
-    #   task title text
-    # @param text (see section)
-    # @param pin [true, false] whether to keep text "pinned"
+    # @example Manual close
+    #   frm = ui.frame 'Preview'
+    #   ui.puts 'Content inside the frame.'
+    #   frm.end
     #
-    # @yieldparam task [Task] itself
+    # @example Block form with title and custom border
+    #   ui.frame 'Results', border: :double do
+    #     ui.puts 'All checks passed.'
+    #   end
+    #
+    # @example Block form without a title
+    #   ui.frame do
+    #     ui.puts 'Framed content.'
+    #   end
     #
-    # @return (see section)
-    def task(title, *text, pin: false, &block)
-      __with(Task.new(self, title, text, pin), &block)
+    # @param title (see #section)
+    # @param border (see #section)
+    # @param style [Symbol, String, Array<Style>, Array<String>, nil]
+    #   ANSI style applied to the frame
+    # @yield [frame] the {Frame} element
+    # @yieldparam frame [Frame]
+    # @return [Object] return value of the block
+    # @return [Frame] itself, if no block is specified
+    def frame(title = nil, border: :default, style: nil, &)
+      __with(Frame.new(self, title, border, style), &)
     end
 
+    # Creates a {Task} element — a labelled step that shows a spinner while
+    # running and a check mark on success.
     #
-    # @!endgroup
+    # @example Manual close
+    #   t = ui.task 'Installing dependencies'
+    #   run_install
+    #   t.end
+    #
+    # @example Block form
+    #   ui.task 'Installing dependencies' do
+    #     run_install
+    #   end
     #
+    # @param title [#to_s] task description
+    # @param pin [Boolean] whether the task title should be pinned
+    # @yield [task] the {Task} element
+    # @yieldparam task [Task]
+    # @return [Object] return value of the block
+    # @return [Task] itself, if no block is specified
+    def task(title, pin: false, &) = __with(Task.new(self, title, pin), &)
 
+    # Creates a {Progress} element for tracking incremental work.
     #
-    # @!group User Interaction
+    # When `max` is given the progress is displayed as a percentage bar.
+    # When `max` is `nil` an open-ended dot animation is shown instead.
+    #
+    # @example Bounded progress
+    #   ui.progress 'Processing', max: items.size do |bar|
+    #     items.each { process(it); bar.step }
+    #   end
     #
+    # @example Open-ended progress
+    #   ui.progress 'Working…' do |bar|
+    #     loop { bar.step; break if done? }
+    #   end
+    #
+    # @param title (see #section)
+    # @param max [Numeric, nil] maximum value
+    # @param popts (see #mark)
+    # @yield [progress] the {Progress} element
+    # @yieldparam progress [Progress]
+    # @return [Object] return value of the block
+    # @return [Progress] itself when no block is given
+    def progress(*title, max: nil, **popts, &)
+      __with(
+        (Terminal.ansi? ? Progress : DumbProgress).new(
+          self,
+          max,
+          *title,
+          **popts
+        ),
+        &
+      )
+    end
 
-    # Wait for user input.
     #
-    # @example Wait until user wants to coninue
-    #   ui.await { ui.puts '[faint][\\Press ENTER to continue...][/faint]' }
+    # @!endgroup
     #
-    # @example Ask yes/no-question
-    #   ui.await(yes: %w[j o t s y d Enter], no: %w[n Esc]) do
-    #     ui.puts 'Do you like NayttUI?'
-    #   end
-    #   # => true, for user's YES
-    #   # => false, for user's NO
-    #   # Info:
-    #   # The keys will work for Afrikaans, Dutch, English, French, German,
-    #   # Italian, Polish, Portuguese, Romanian, Spanish and Swedish.
+    # @!group User Interaction
     #
-    # @overload await(yes: 'Enter', no: 'Esc')
+
+    # Waits for the user to press any key.
     #
-    # @overload await(yes: 'Enter', no: 'Esc', &block)
-    #   @yieldparam temp [Temporary]
-    #     temporary displayed section (section will be erased after input)
+    # @example Plain wait
+    #   ui.puts 'Press any key to continue…'
+    #   ui.await
     #
-    # @param yes [String, Enumerable<String>]
-    #   key code/s a user can input to return positive result
-    # @param no [String, Enumerable<String>]
-    #   key code/s a user can input to return negative resault
+    # @example With temporary prompt
+    #   ui.await { ui.puts '[faint]Press any key to continue…' }
     #
-    # @return [true, false]
-    #   whether the user inputs a positive result
+    # @yield (see #temporary)
+    # @yieldparam (see #temporary)
     # @return [nil]
-    #   in error case
-    def await(yes: 'Enter', no: 'Esc')
-      return __await(yes, no) unless block_given?
-      temporary do |temp|
-        yield(temp)
-        __await(yes, no)
-      end
+    def await
+      yield(temp = temporary) if block_given?
+      Terminal.read_key_event
+      nil
+    ensure
+      temp&.end
     end
 
-    # Allows the user to select an option from a selection.
-    # The selected option is returned.
-    #
-    # @overload choice(*choices, abortable: false)
-    #   @param choices [#to_s]
-    #     one or more alternatives to select from
-    #   @param abortable [true, false]
-    #     whether the user is allowed to abort with 'Esc' or 'Ctrl+c'
-    #
-    #   @return [Integer]
-    #     index of selected choice
-    #   @return [nil]
-    #     when user aborted the selection
-    #
-    # @overload choice(*choices, abortable: false, &block)
-    #   @example Request a fruit
-    #     ui.choice('Apple', 'Banana', 'Orange') { ui.puts 'What do you prefer?' }
-    #     # => 0, when user likes apples
-    #     # => 1, when bananas are user's favorite
-    #     # => 2, when user is a oranges lover
-    #
-    #   @param choices[#to_s]
-    #     one or more alternatives to select from
-    #   @param abortable[true, false]
-    #     whether the user is allowed to abort with 'Esc' or 'Ctrl+c'
-    #
-    #   @yieldparam temp [Temporary]
-    #     temporary displayed section (section will be erased after input)
-    #
-    #   @return [Integer]
-    #     index of selected choice
-    #   @return [nil]
-    #     when user aborted the selection
-    #
-    # @overload choice(**choices, abortable: false)
-    #   @param choices [#to_s]
-    #     one or more alternatives to select from
-    #   @param abortable [true, false]
-    #     whether the user is allowed to abort with 'Esc' or 'Ctrl+c'
-    #   @param selected [#to_s, nil]
-    #     optionally pre-selected option
-    #
-    #   @return [Object]
-    #     key for selected choice
-    #   @return [nil]
-    #     when user aborted the selection
-    #
-    # @overload choice(**choices, abortable: false, &block)
-    #   @example Request a preference
-    #     ui.choice(
-    #       k: 'Kitty',
-    #       i: 'iTerm2',
-    #       g: 'Ghostty',
-    #       t: 'Tabby',
-    #       r: 'Rio',
-    #       abortable: true
-    #     ) { ui.puts 'Which terminal emulator do you like?' }
-    #     # => whether the user selected: :k, :i, :g, :t, :r
-    #     # => nil, when the user aborted
-    #   @param choices[#to_s]
-    #     one or more alternatives to select from
-    #   @param abortable[true, false]
-    #     whether the user is allowed to abort with 'Esc' or 'Ctrl+c'
-    #   @param selected[Integer]
-    #     pre-selected option index
-    #
-    #   @yieldparam temp [Temporary]
-    #     temporary displayed section (section will be erased after input)
-    #
-    #   @return [Object]
-    #     key for selected choice
-    #   @return [nil]
-    #     when user aborted the selection
-    #
-    def choice(*choices, abortable: false, selected: nil, **kwchoices, &block)
-      return if choices.empty? && kwchoices.empty?
-      choice =
-        if Terminal.ansi?
-          Choice.new(self, choices, kwchoices, abortable, selected)
-        else
-          DumbChoice.new(self, choices, kwchoices, abortable)
-        end
-      __with(choice) { choice.select(&block) }
-    end
-
-    # Allows the user to select from several options.
-    # All options are returned with their selection status.
+    # Waits for a key event and returns information about it.
     #
-    # @param choices [{#to_s => [true,false]}]
-    #   Hash of options and their selection state
-    # @param abortable [true, false]
-    #   whether the user is allowed to abort with 'Esc' or 'Ctrl+c'
-    # @param selected [#to_s, nil]
-    #   optionally pre-selected key
+    # Key names are strings such as `"a"`, `"Enter"`, `"Esc"`, `"Back"`,
+    # `"Shift+Alt+F1"`.
     #
-    # @yieldparam temp [Temporary]
-    #   temporary displayed section (section will be erased after input)
+    # @example
+    #   answer = ui.query yes: 'y', no: 'n'
+    #   ui.puts answer == :yes ? 'Confirmed!' : 'Cancelled.'
     #
-    # @return [{#to_s => [true,false]}]
-    #   Hash of options and their selection state
-    # @return [nil]
-    #   when user aborted the selection
-    def options(abortable: false, selected: nil, **choices, &block)
-      return {} if choices.empty?
-      options =
-        if Terminal.ansi?
-          Options.new(self, choices, abortable, selected)
-        else
-          DumbOptions.new(self, choices, abortable, selected)
-        end
-      __with(options) { options.select(&block) }
+    # @example With a temporary prompt
+    #   answer = ui.query(yes: 'y', no: 'n') do
+    #     ui.puts 'Continue? ([b]y[/b]/[b]n[/b])'
+    #   end
+    #
+    # @param options [Hash<Object => String, #each>]
+    #   map of return values to key names or enumerables of key names;
+    #   e.g. `{ yes: 'y', no: %w[n Esc] }`
+    # @yield (see #temporary)
+    # @yieldparam (see #temporary)
+    # @return [Object] matched option key
+    def query(**options)
+      yield(temp = temporary) if block_given?
+      return Terminal.read_key_event.name if options.empty?
+      Terminal.on_key_event do |event|
+        event = event.name
+        found, =
+          options.find do |_, value|
+            (value.is_a?(Enumerable) && value.include?(event)) || value == event
+          end
+        break found if found
+      end
+    ensure
+      temp&.end
     end
 
-    # Allows the user to select from several options.
-    # The selected options are returned.
+    # Presents a list of options and returns the one the user selects.
     #
-    # @example Select a terminal
-    #   ui.select %w[Kitty iTerm2 Ghostty Tabby Rio] do
-    #    ui.puts '[i]Which terminal applications did you already tested?[/i]'
+    # In ANSI mode the user navigates with arrow keys and confirms with Enter.
+    # In dumb mode items are numbered and the user types the item number.
+    #
+    # @example Positional items
+    #   answer = ui.choice 'Yes', 'No', 'Cancel'
+    #
+    # @example Positional items
+    #   answer = ui.choice 'Yes', 'No', abortable: true do
+    #     ui.puts 'Overwrite the file?'
     #   end
     #
-    # @param choices [Array<#to_s>]
-    #   selectable options
-    # @param abortable [true, false]
-    #   whether the user is allowed to abort with 'Esc' or 'Ctrl+c'
-    # @param selected [Integer, :all, nil]
-    #   optionally pre-selected option index or `:all` to pre-select all items
-    # @yieldparam temp [Temporary]
-    #   temporary displayed section (section will be erased after input)
+    # @example Keyword pairs
+    #   action = ui.choice(overwrite: 'Overwrite', skip: 'Skip') do
+    #     ui.puts 'File already exists.'
+    #   end
     #
-    # @return [Array<#to_s>]
-    #   selected options
-    # @return [nil]
-    #   when user aborted the selection
-    def select(*choices, abortable: false, selected: nil, &block)
-      return [] if choices.empty?
-      choices = choices[0] if choices.size == 1 && choices[0].is_a?(Enumerable)
-      if selected == :all
-        sel = true
-      elsif selected
-        selected = choices[selected.to_i]
-      end
-      options(
-        abortable: abortable,
-        selected: selected,
-        **choices.to_h { [_1, sel] },
-        &block
-      ).filter_map { |key, selected| key if selected }
+    # @overload choice(*items, abortable: false, selected: nil)
+    #   Items are passed as positional arguments; the selected item itself is
+    #   returned.
+    #   @param items [#to_s, ...] options to choose from
+    #   @param abortable [Boolean] when `true` the user can press Esc to cancel
+    #   @param selected pre-selected item value, or `nil`
+    #
+    # @overload choice(abortable: false, selected: nil, **pairs)
+    #   Items are passed as keyword pairs `{ return_value => label }`; the
+    #   matching key is returned.
+    #   @param abortable [Boolean] when `true` the user can press Esc to cancel
+    #   @param selected pre-selected return value, or `nil`
+    #   @param pairs [Hash{Object => #to_s}] map of return values to display labels
+    #
+    # @yield (see #temporary)
+    # @yieldparam (see #temporary)
+    # @return [Object] the key of the selected pair, or `nil` if aborted
+    def choice(*items, abortable: false, selected: nil, **pairs)
+      return if items.empty? && pairs.empty?
+      yield(temp = temporary) if block_given?
+      (Terminal.ansi? ? Choice : DumbChoice).new(
+        self,
+        items + pairs.values,
+        Array.new(items.size, &:itself) + pairs.keys
+      ).select(abortable, selected)
+    ensure
+      temp&.end
     end
 
+    # Presents a list of options and returns all items the user selects.
     #
-    # @!endgroup
+    # In ANSI mode the user toggles items with Space and confirms with Enter.
+    # In dumb mode items are numbered and the user types item numbers.
     #
-
+    # @example Positional items
+    #   picks = ui.select 'Kitty', 'iTerm2', 'Ghostty'
     #
-    # @!group Utilities
+    # @example Positional items with all pre-selected
+    #   picks = ui.select 'A', 'B', 'C', selected: :all do
+    #     ui.puts 'Choose features to enable:'
+    #   end
     #
+    # @example Keyword pairs
+    #   flags = ui.select verbose: 'Verbose', debug: 'Debug', trace: 'Trace'
+    #
+    # @overload select(*items, abortable: false, selected: nil)
+    #   Items are passed as positional arguments; the selected items themselves
+    #   are returned.
+    #   @param items [#to_s, ...] options to choose from
+    #   @param abortable [Boolean] when `true` the user can press Esc to cancel
+    #   @param selected [nil, :all, #each]
+    #     pre-selected items: `nil` = none, `:all` = all,
+    #     or an enumerable of item values to pre-select
+    #
+    # @overload select(abortable: false, selected: nil, **pairs)
+    #   Items are passed as keyword pairs `{ return_value => label }`; the
+    #   matching keys are returned.
+    #   @param abortable [Boolean] when `true` the user can press Esc to cancel
+    #   @param selected [nil, :all, #each]
+    #   @param pairs [Hash{Object => #to_s}] map of return values to labels
+    #
+    # @yield (see #temporary)
+    # @yieldparam (see #temporary)
+    # @return [Array] keys of selected pairs, or `nil` if aborted
+    def select(*items, abortable: false, selected: nil, **pairs)
+      return if items.empty? && pairs.empty?
+      yield(temp = temporary) if block_given?
+      items = items.to_h { [it, it] }.merge!(pairs)
+      (Terminal.ansi? ? Select : DumbSelect).new(
+        self,
+        if selected == :all
+          items.map { it << true }
+        elsif selected.is_a?(Enumerable)
+          items.map { |ret, txt| [ret, txt, selected.include?(ret)] }
+        elsif selected
+          items.map { |ret, txt| [ret, txt, selected == ret] }
+        else
+          items.map { it << false }
+        end
+      ).select(abortable)
+    ensure
+      temp&.end
+    end
 
-    # @private
-    def columns = Terminal.columns
-
-    # Display some temporary content.
-    # The content displayed in the block will be erased after the block ends.
     #
-    # @example Show tempoary information
-    #   ui.temporary do
-    #     ui.info 'Information', 'This text will disappear when you pressed ENTER.'
-    #     ui.await
-    #   end
+    # @!endgroup
     #
-    # @yieldparam temp [Temporary]
-    #   itself
+    # @!group Utilities
     #
-    # @return (see section)
-    def temporary(&block) = __with(Temporary.new(self), &block)
+
+    # Executes a shell command and prints its output to the terminal.
+    #
+    # All arguments and options are forwarded to `Terminal.sh`, which in turn
+    # uses `Process.spawn`.
+    #
+    # @example Run a simple command
+    #   ui.sh 'echo "Hello Ruby!"'
+    #
+    # @example Pipe a string as stdin
+    #   ui.sh 'cat', input: 'Hello from stdin'
+    #
+    # @overload sh(*cmd, env = {}, shell: false, input: nil, **spawn_options)
+    #   @param cmd [#to_s, ...] command and arguments, same as `Process.spawn`
+    #   @param env [Hash, nil] additional environment variables
+    #   @param shell [Boolean] when `true` runs the command through a system shell
+    #   @param input piped standard input; accepts any object with `#readpartial`,
+    #     `#to_io`, `#each`, `#to_a`, or anything `IO.write` accepts (e.g. a String)
+    #   @param spawn_options [Hash] additional options forwarded to `Process.spawn`
+    #   @return (see #puts)
+    def sh(...) = Shell.render(self, ...)
+
+    # Executes a shell command, captures its output, and returns it.
+    #
+    # Stdout and stderr lines are displayed in a scrolling region limited to
+    # `max_lines`.  All other arguments are identical to {#sh}.
+    #
+    # @example Capture and inspect output
+    #   status, out, err = ui.run 'ls', '-la'
+    #   ui.puts "exit #{status.exitstatus}"
+    #
+    # @example Limit displayed lines and pipe input
+    #   File.open('data.txt') { |f| ui.run 'wc', '-l', input: f, max_lines: 5 }
+    #
+    # @overload run(*cmd, env = {}, shell: false, input: nil, max_lines: 10, **spawn_options)
+    #   @param cmd (see #sh)
+    #   @param max_lines [#to_int] maximum number of output lines shown at once
+    #   @param env (see #sh)
+    #   @param shell (see #sh)
+    #   @param input (see #sh)
+    #   @param spawn_options (see #sh)
+    #   @return [Array(Process::Status, Array<String>, Array<String>)]
+    #     three-element array of exit status, stdout lines, and stderr lines
+    #   @return [nil] when the command could not be started
+    def run(*, max_lines: 10, **)
+      (Terminal.ansi? ? ShellRunner : DumbShellRunner).render(
+        self,
+        max_lines,
+        *,
+        **
+      )
+    end
 
     #
     # @!endgroup
     #
 
-    private
-
-    def __with(element, &block) = NattyUI.__send__(:with, element, &block)
+    # @private
+    def columns = Terminal.columns
 
-    def __sec(color, title, text, &block)
-      __with(Section.new(self, title, text, color), &block)
-    end
+    private
 
-    def __tsec(color, title, text, &block)
-      __sec(color, "#{Theme.current.mark(color)}#{title}", text, &block)
+    def __determine_max_width(value)
+      return columns unless value
+      return 0 if value == 0
+      return value.to_int + columns if value < 0
+      return (value * columns).round if value < 1
+      [value.to_int, columns].min
     end
 
-    def __await(yes, no)
-      Terminal.on_key_event do |event|
-        event = event.name
-        if (no == event) || (no.is_a?(Enumerable) && no.include?(event))
-          return false
-        end
-        if (yes == event) || (yes.is_a?(Enumerable) && yes.include?(event))
-          return true
-        end
-        true
+    def __with(element)
+      NattyUI.__send__(:_begin, element)
+      return element unless block_given?
+      begin
+        yield(element)
+      ensure
+        NattyUI.__send__(:_end, element)
       end
     end
   end
 
-  dir = __dir__ # call the function once
+  dir = __dir__
 
-  autoload :Framed, "#{dir}/framed.rb"
+  # @comment Elements:
+  autoload :Frame, "#{dir}/frame.rb"
+  autoload :Margin, "#{dir}/margin.rb"
+  autoload :Progress, "#{dir}/progress.rb"
+  autoload :DumbProgress, "#{dir}/dumb_progress.rb"
   autoload :Section, "#{dir}/section.rb"
-  autoload :Table, "#{dir}/table.rb"
   autoload :Task, "#{dir}/task.rb"
   autoload :Temporary, "#{dir}/temporary.rb"
-  autoload :Theme, "#{dir}/theme.rb"
-  autoload :Utils, "#{dir}/utils.rb"
-  private_constant(:Framed, :Utils)
 
-  autoload :Choice, "#{dir}/choice.rb"
-  autoload :DumbChoice, "#{dir}/dumb_choice.rb"
-  autoload :Options, "#{dir}/options.rb"
-  autoload :DumbOptions, "#{dir}/dumb_options.rb"
-  autoload :Progress, "#{dir}/progress.rb"
-  autoload :DumbProgress, "#{dir}/progress.rb"
+  # @comment Helper:
+  autoload :Table, "#{dir}/helper/table.rb"
+
+  # @comment Utils:
+  autoload :Utils, "#{dir}/utils/utils.rb"
+  autoload :StrConst, "#{dir}/utils/str_const.rb"
+  private_constant(:Utils, :StrConst)
+
+  # @comment Renderer:
+  autoload :VBars, "#{dir}/renderer/bars.rb"
+  autoload :HBars, "#{dir}/renderer/bars.rb"
+  autoload :Choice, "#{dir}/renderer/choice.rb"
+  autoload :DumbChoice, "#{dir}/renderer/dumb_choice.rb"
+  autoload :Heading, "#{dir}/renderer/heading.rb"
+  autoload :HorizontalRule, "#{dir}/renderer/horizontal_rule.rb"
+  autoload :LS, "#{dir}/renderer/ls.rb"
+  autoload :CompactLS, "#{dir}/renderer/ls.rb"
+  autoload :Mark, "#{dir}/renderer/mark.rb"
+  autoload :Quote, "#{dir}/renderer/quote.rb"
+  autoload :Select, "#{dir}/renderer/select.rb"
+  autoload :DumbSelect, "#{dir}/renderer/dumb_select.rb"
+  autoload :Shell, "#{dir}/renderer/shell.rb"
+  autoload :ShellRunner, "#{dir}/renderer/shell_runner.rb"
+  autoload :DumbShellRunner, "#{dir}/renderer/dumb_shell_runner.rb"
+  autoload :TableRenderer, "#{dir}/renderer/table_renderer.rb"
   private_constant(
+    :VBars,
+    :HBars,
     :Choice,
     :DumbChoice,
-    :Options,
-    :DumbOptions,
-    :Progress,
-    :DumbProgress
-  )
-
-  autoload :CompactLSRenderer, "#{dir}/ls_renderer.rb"
-  autoload :HBarsRenderer, "#{dir}/hbars_renderer.rb"
-  autoload :LSRenderer, "#{dir}/ls_renderer.rb"
-  autoload :ShellRenderer, "#{dir}/shell_renderer.rb"
-  autoload :VBarsRenderer, "#{dir}/vbars_renderer.rb"
-  private_constant(
-    :CompactLSRenderer,
-    :HBarsRenderer,
-    :LSRenderer,
-    :ShellRenderer,
-    :VBarsRenderer
+    :Heading,
+    :HorizontalRule,
+    :LS,
+    :CompactLS,
+    :Mark,
+    :Quote,
+    :Select,
+    :DumbSelect,
+    :Shell,
+    :ShellRunner,
+    :DumbShellRunner,
+    :TableRenderer
   )
 end