Wrap styled text using terminal display widths

Assisted-By: devx/b840c1e6-d979-473d-9216-a53477380bf1

Author: GoodForOneFare

lib/cli/ui/wrap.rb

@@ -5,6 +5,10 @@
 module CLI
   module UI
     class Wrap
+      # SGR parameters are separated by ; or, in the underspecified-but-real
+      # colon form of extended colors (\x1b[38:2::255:0:0m), by :.
+      SGR = /\A\x1b\[[\d;:]*m\z/
+
       #: (String input) -> void
       def initialize(input)
         @input = input
@@ -14,43 +18,143 @@ def initialize(input)
       def wrap(total_width = Terminal.width)
         max_width = total_width - Frame.prefix_width
         width = 0 #: Integer
-        final = []
-        # Create an alternation of format codes of parameter lengths 1-20, since + and {1,n} not allowed in lookbehind
-        format_codes = (1..20).map { |n| /\x1b\[[\d;]{#{n}}m/ }.join('|')
-        codes = ''
-        @input.split(/(?=\s|\x1b\[[\d;]+m|\r)|(?<=\s|#{format_codes})/).each do |token|
-          case token
-          when '\x1B[0?m'
-            codes = ''
-            final << token
-          when /\x1b\[[\d;]+m/
-            codes += token # Track in use format codes so that they are resent after frame coloring
+        final = +''
+        # SGR codes in effect, resent after each line break so that frame
+        # coloring doesn't clobber them mid-paragraph. An open hyperlink
+        # likewise gets closed at the break and reopened after it, keeping
+        # the frame gutter outside the link.
+        sgr_state = {} #: Hash[String, String]
+        open_hyperlink = nil #: String?
+        break_line = -> do
+          final << ANSI::HYPERLINK_END if open_hyperlink
+          final << "\n" << active_sgr(sgr_state) << open_hyperlink.to_s
+          width = 0
+        end
+
+        ANSI.each_token(@input) do |kind, token|
+          if kind == :sequence
+            case token
+            when SGR
+              track_sgr(token, sgr_state)
+            when ANSI::HYPERLINK
+              match = ANSI::HYPERLINK.match(token) #: as !nil
+              open_hyperlink = match[:uri].to_s.empty? ? nil : token
+            end
             final << token
-          when "\n"
-            final << "\n#{codes}"
-            width = 0
-          when /\s/
-            token_width = ANSI.printing_width(token)
-            if width + token_width <= max_width
-              final << token
-              width += token_width
-            else
-              final << "\n#{codes}"
-              width = 0
+            next
+          end
+
+          # Split the text run so each whitespace character is its own
+          # token: lines break at whitespace, and a space that would sit in
+          # the last column becomes the break itself.
+          token.split(/(?=\s)|(?<=\s)/).each do |chunk|
+            if chunk == "\n"
+              break_line.call
+              next
             end
-          else
-            token_width = ANSI.printing_width(token)
-            if width + token_width <= max_width
-              final << token
-              width += token_width
+
+            chunk_width = ANSI.printing_width(chunk)
+            if width + chunk_width <= max_width
+              final << chunk
+              width += chunk_width
+            elsif chunk.match?(/\A\s\z/)
+              break_line.call
             else
-              final << "\n#{codes}"
-              final << token
-              width = token_width
+              break_line.call
+              final << chunk
+              width = chunk_width
             end
           end
         end
-        final.join
+        final
+      end
+
+      private
+
+      # Reconstructs the active SGR commands as one deduplicated sequence.
+      #
+      #: (Hash[String, String] state) -> String
+      def active_sgr(state)
+        state.empty? ? '' : "\e[#{state.values.join(";")}m"
+      end
+
+      # Keeps only the most recent command for each SGR parameter, with shared
+      # slots for the color commands whose payloads can vary. Deleting before
+      # reinserting preserves the order of each command's last occurrence, so
+      # an on/off/on sequence replays in the same effective order without
+      # retaining the full formatting history.
+      #
+      # A reset can hide mid-list: parameters reset at a 0 or an empty entry
+      # (\e[0;33m, \e[;1m), while zeros inside a colon-form parameter are
+      # subparameters rather than commands.
+      #
+      #: (String token, Hash[String, String] state) -> void
+      def track_sgr(token, state)
+        params = token[2...-1].to_s.split(';', -1)
+        params = ['0'] if params.empty?
+        index = 0
+        while index < params.length
+          param = params.fetch(index)
+          param = '0' if param.empty?
+          code = param.split(':', 2).first.to_i
+          command = param
+          consumed = 0
+
+          if code == 38 || code == 48 || code == 58
+            command, consumed = color_command(params, index)
+          end
+          remember_sgr(state, code, command) if command
+          index += consumed + 1
+        end
+      end
+
+      # Semicolon-form extended colors consume their following parameters;
+      # colon-form colors are already one parameter and need no grouping.
+      #
+      #: (Array[String] params, Integer index) -> [String?, Integer]
+      def color_command(params, index)
+        param = params.fetch(index)
+        return [param, 0] if param.include?(':')
+
+        case params[index + 1]
+        when '5'
+          return [nil, params.length - index - 1] if params[index + 2].nil?
+
+          [params[index, 3].to_a.join(';'), 2]
+        when '2'
+          length = params[index + 2].to_s.empty? ? 6 : 5
+          return [nil, params.length - index - 1] if params.length < index + length
+
+          [params[index, length].to_a.join(';'), length - 1]
+        else
+          [nil, 0]
+        end
+      end
+
+      #: (Hash[String, String] state, Integer code, String command) -> void
+      def remember_sgr(state, code, command)
+        if code.zero?
+          state.clear
+          return
+        end
+
+        key = sgr_key(code)
+        state.delete(key)
+        state[key] = command
+      end
+
+      #: (Integer code) -> String
+      def sgr_key(code)
+        case code
+        when 30..39, 90..97
+          'foreground'
+        when 40..49, 100..107
+          'background'
+        when 58, 59
+          'underline_color'
+        else
+          code.to_s
+        end
       end
     end
   end

test/cli/ui/wide_glyph_layout_test.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+module CLI
+  module UI
+    # Locks ANSI's width table into real layout: a wide glyph measured one
+    # column short would shift every character after it in these strings.
+    # Expectations are spelled out as exact output rather than measured
+    # with printing_width, which is the very thing under test. Color and
+    # cursor movement are disabled so layout arrives as plain text instead
+    # of repaints.
+    class WideGlyphLayoutTest < Minitest::Test
+      def setup
+        CLI::UI.enable_color = false
+        CLI::UI.enable_cursor = false
+        super
+      end
+
+      def teardown
+        CLI::UI.enable_color = true
+        CLI::UI.enable_cursor = true
+        super
+      end
+
+      def test_frame_pads_an_emoji_title_like_a_plain_one
+        Terminal.stubs(:width).returns(20)
+
+        with_emoji = capture_io { Frame.open('🚀 go', timing: false) {} }.first.lines.first.chomp
+        plain = capture_io { Frame.open('ab go', timing: false) {} }.first.lines.first.chomp
+
+        assert_equal('┏━━ 🚀 go ━━━━━━━━━', with_emoji)
+        # 🚀 spans two columns, like 'ab': the rules must line up.
+        assert_equal('┏━━ ab go ━━━━━━━━━', plain)
+      end
+
+      def test_table_pads_emoji_cells_by_column
+        rows = Table.capture_table([['✅ pass', 'ok'], ['status', 'ok']])
+
+        assert_equal(['✅ pass ok', 'status  ok'], rows)
+      end
+
+      def test_spin_group_truncates_a_vs16_glyph_title_by_column
+        Terminal.stubs(:width).returns(12)
+
+        out, _ = capture_io do
+          StdoutRouter.ensure_activated
+          sg = Spinner::SpinGroup.new
+          sg.add('⚠️ wide glyph title') { true }
+          sg.wait
+        end
+
+        # ⚠️ (U+26A0 + VS16) takes two columns, so twelve fill at the g.
+        assert_equal("✓ ⚠️ wide g\e[0m…", out.lines.last.chomp)
+      end
+    end
+  end
+end

test/cli/ui/wrap_test.rb

@@ -14,6 +14,85 @@ def test_wrap
         Terminal.stubs(:width).returns(20)
         assert_equal(ex, w.wrap)
       end
+
+      def test_wrap_resends_active_codes_after_a_break
+        wrapped = Wrap.new("\x1b[31maaaa bbbb cccc").wrap(9)
+
+        assert_equal("\x1b[31maaaa bbbb\n\x1b[31mcccc", wrapped)
+      end
+
+      def test_wrap_stops_resending_codes_after_a_reset
+        wrapped = Wrap.new("\x1b[31maaaa\x1b[0m bbbb cccc").wrap(9)
+
+        assert_equal("\x1b[31maaaa\x1b[0m bbbb\ncccc", wrapped)
+      end
+
+      def test_wrap_detects_a_reset_hidden_in_a_parameter_list
+        # \e[0;33m resets, then applies 33: earlier codes die at the reset
+        # and only the survivors are resent after a break.
+        wrapped = Wrap.new("\x1b[1m\x1b[0;33maaaa bbbb cccc").wrap(9)
+
+        assert_equal("\x1b[1m\x1b[0;33maaaa bbbb\n\x1b[33mcccc", wrapped)
+      end
+
+      def test_wrap_detects_an_empty_parameter_as_a_reset
+        # An empty SGR parameter (\e[;m) is a 0 to a terminal.
+        wrapped = Wrap.new("\x1b[31maaaa\x1b[;m bbbb cccc").wrap(9)
+
+        assert_equal("\x1b[31maaaa\x1b[;m bbbb\ncccc", wrapped)
+      end
+
+      def test_wrap_tracks_colon_form_sgr_codes
+        wrapped = Wrap.new("\e[38:2::255:0:0maaaa bbbb cccc").wrap(9)
+
+        assert_equal("\e[38:2::255:0:0maaaa bbbb\n\e[38:2::255:0:0mcccc", wrapped)
+      end
+
+      def test_wrap_keeps_sgr_replay_bounded
+        input = 8.times.map { |i| "\e[#{31 + (i % 7)}m#{(97 + i).chr * 4}" }.join(' ')
+        wrapped = Wrap.new(input).wrap(5)
+
+        assert_equal([2, 2, 2, 2, 2, 2, 2, 1], wrapped.lines.map { |line| line.scan(/\e\[[\d;:]*m/).length })
+        assert_operator(wrapped.bytesize, :<, input.bytesize * 2)
+      end
+
+      def test_wrap_reconstructs_independent_sgr_attributes
+        wrapped = Wrap.new("\e[1m\e[31maaaa bbbb").wrap(4)
+
+        assert_equal("\e[1m\e[31maaaa\n\e[1;31mbbbb", wrapped)
+      end
+
+      def test_wrap_groups_semicolon_form_extended_colors
+        wrapped = Wrap.new("\e[1m\e[38;2;1;2;3maaaa bbbb").wrap(4)
+
+        assert_equal("\e[1m\e[38;2;1;2;3maaaa\n\e[1;38;2;1;2;3mbbbb", wrapped)
+      end
+
+      def test_wrap_does_not_reinterpret_incomplete_extended_colors
+        wrapped = Wrap.new("\e[38;2;255maaaa bbbb").wrap(4)
+
+        assert_equal("\e[38;2;255maaaa\nbbbb", wrapped)
+      end
+
+      def test_wrap_deduplicates_parameters_in_last_used_order
+        wrapped = Wrap.new("\e[1m\e[22m\e[1maaaa bbbb").wrap(4)
+
+        assert_equal("\e[1m\e[22m\e[1maaaa\n\e[22;1mbbbb", wrapped)
+      end
+
+      def test_wrap_preserves_distinct_unrecognized_parameters
+        wrapped = Wrap.new("\e[76m\e[77maaaa bbbb").wrap(4)
+
+        assert_equal("\e[76m\e[77maaaa\n\e[76;77mbbbb", wrapped)
+      end
+
+      def test_wrap_reopens_a_hyperlink_after_a_break
+        open_link = "\e]8;;https://example.com\e\\"
+        close_link = ANSI::HYPERLINK_END
+        wrapped = Wrap.new("#{open_link}aaaa bbbb cccc#{close_link}").wrap(9)
+
+        assert_equal("#{open_link}aaaa bbbb#{close_link}\n#{open_link}cccc#{close_link}", wrapped)
+      end
     end
   end
 end