charming 0.1.2 → 0.1.3

data/lib/charming/presentation/components/viewport.rb

@@ -3,269 +3,267 @@
 require "unicode/display_width"
 
 module Charming
-  module Presentation
-    module Components
-      # Viewport is a scrollable region over multi-line content. Supports keyboard scrolling
-      # (up/down/left/right, page up/down, home/end) and mouse interactions (scroll wheel and
-      # click-to-position). Lines are clipped with ANSI awareness via `UI::ANSISlicer` so styled
-      # text is preserved across horizontal scrolls. When `wrap:` is true, long lines are wrapped
-      # to the configured *width* before scrolling.
-      class Viewport < Component
-        include KeyboardHandler
-
-        # Matches an ANSI SGR escape sequence (e.g., "\e[31m" for red foreground).
-        ANSI_PATTERN = /\e\[[0-9;]*m/
-
-        # Maps scroll keys to the instance methods that perform them via KeyboardHandler.
-        KEY_ACTIONS = {
-          up: :scroll_up,
-          down: :scroll_down,
-          page_up: :page_up,
-          page_down: :page_down,
-          home: :scroll_home,
-          end: :scroll_end,
-          left: :scroll_left,
-          right: :scroll_right
-        }.freeze
-
-        # The current top-visible row and left-visible column, respectively.
-        attr_reader :offset, :column
-
-        # *content* may be a string, an array of lines, or any object responding to `render`.
-        # *width* and *height* constrain the visible window; *offset* is the top-visible row
-        # and *column* is the left-visible column. *wrap* enables soft-wrapping of long lines.
-        def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim)
-          super()
-          @content = content
-          @width = width
-          @height = height
-          @offset = offset
-          @column = column
-          @wrap = wrap
-          @keymap = keymap
-          clamp_position
-        end
+  module Components
+    # Viewport is a scrollable region over multi-line content. Supports keyboard scrolling
+    # (up/down/left/right, page up/down, home/end) and mouse interactions (scroll wheel and
+    # click-to-position). Lines are clipped with ANSI awareness via `UI::ANSISlicer` so styled
+    # text is preserved across horizontal scrolls. When `wrap:` is true, long lines are wrapped
+    # to the configured *width* before scrolling.
+    class Viewport < Component
+      include KeyboardHandler
+
+      # Matches an ANSI SGR escape sequence (e.g., "\e[31m" for red foreground).
+      ANSI_PATTERN = /\e\[[0-9;]*m/
+
+      # Maps scroll keys to the instance methods that perform them via KeyboardHandler.
+      KEY_ACTIONS = {
+        up: :scroll_up,
+        down: :scroll_down,
+        page_up: :page_up,
+        page_down: :page_down,
+        home: :scroll_home,
+        end: :scroll_end,
+        left: :scroll_left,
+        right: :scroll_right
+      }.freeze
+
+      # The current top-visible row and left-visible column, respectively.
+      attr_reader :offset, :column
+
+      # *content* may be a string, an array of lines, or any object responding to `render`.
+      # *width* and *height* constrain the visible window; *offset* is the top-visible row
+      # and *column* is the left-visible column. *wrap* enables soft-wrapping of long lines.
+      def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim)
+        super()
+        @content = content
+        @width = width
+        @height = height
+        @offset = offset
+        @column = column
+        @wrap = wrap
+        @keymap = keymap
+        clamp_position
+      end
 
-        # Renders the visible window of content as a multi-line string.
-        def render
-          visible_lines.map { |line| render_line(line) }.join("\n")
-        end
+      # Renders the visible window of content as a multi-line string.
+      def render
+        visible_lines.map { |line| render_line(line) }.join("\n")
+      end
 
-        # Handles mouse events: scroll wheel adjusts the row offset, click moves the top
-        # visible row to the clicked position. Returns :handled on success.
-        def handle_mouse(event)
-          return nil unless height
+      # Handles mouse events: scroll wheel adjusts the row offset, click moves the top
+      # visible row to the clicked position. Returns :handled on success.
+      def handle_mouse(event)
+        return nil unless height
 
-          if event.scroll?
-            scroll_delta = (event.button_name == :scroll_up) ? -1 : 1
-            @offset += scroll_delta
-            clamp_position
-            return :handled
-          end
+        if event.scroll?
+          scroll_delta = (event.button_name == :scroll_up) ? -1 : 1
+          @offset += scroll_delta
+          clamp_position
+          return :handled
+        end
 
-          return nil unless event.click?
+        return nil unless event.click?
 
-          clicked_row = event.y
-          return nil if clicked_row < offset || clicked_row >= offset + viewport_height
+        clicked_row = event.y
+        return nil if clicked_row < offset || clicked_row >= offset + viewport_height
 
-          @offset = clicked_row
-          clamp_position
-          :handled
-        end
+        @offset = clicked_row
+        clamp_position
+        :handled
+      end
 
-        private
+      private
 
-        attr_reader :content, :width, :height
+      attr_reader :content, :width, :height
 
-        # Scrolls the viewport up by one row.
-        def scroll_up
-          @offset -= 1
-          clamp_position
-        end
+      # Scrolls the viewport up by one row.
+      def scroll_up
+        @offset -= 1
+        clamp_position
+      end
 
-        # Scrolls the viewport down by one row.
-        def scroll_down
-          @offset += 1
-          clamp_position
-        end
+      # Scrolls the viewport down by one row.
+      def scroll_down
+        @offset += 1
+        clamp_position
+      end
 
-        # Scrolls up by one viewport page.
-        def page_up
-          @offset -= page_size
-          clamp_position
-        end
+      # Scrolls up by one viewport page.
+      def page_up
+        @offset -= page_size
+        clamp_position
+      end
 
-        # Scrolls down by one viewport page.
-        def page_down
-          @offset += page_size
-          clamp_position
-        end
+      # Scrolls down by one viewport page.
+      def page_down
+        @offset += page_size
+        clamp_position
+      end
 
-        # Scrolls to the top-left of the content.
-        def scroll_home
-          @offset = 0
-          @column = 0
-        end
+      # Scrolls to the top-left of the content.
+      def scroll_home
+        @offset = 0
+        @column = 0
+      end
 
-        # Scrolls to the bottom-right of the content.
-        def scroll_end
-          @offset = max_offset
-          @column = max_column
-        end
+      # Scrolls to the bottom-right of the content.
+      def scroll_end
+        @offset = max_offset
+        @column = max_column
+      end
 
-        # Scrolls one column left.
-        def scroll_left
-          @column -= 1
-          clamp_position
-        end
+      # Scrolls one column left.
+      def scroll_left
+        @column -= 1
+        clamp_position
+      end
 
-        # Scrolls one column right.
-        def scroll_right
-          @column += 1
-          clamp_position
-        end
+      # Scrolls one column right.
+      def scroll_right
+        @column += 1
+        clamp_position
+      end
 
-        # Clamps both the row offset and the column to their valid ranges.
-        def clamp_position
-          @offset = offset.clamp(0, max_offset)
-          @column = column.clamp(0, max_column)
-        end
+      # Clamps both the row offset and the column to their valid ranges.
+      def clamp_position
+        @offset = offset.clamp(0, max_offset)
+        @column = column.clamp(0, max_column)
+      end
 
-        # Returns the slice of content lines visible in the current viewport, padded to *height*.
-        def visible_lines
-          lines = content_lines.slice(offset, viewport_height) || []
-          return lines unless height
+      # Returns the slice of content lines visible in the current viewport, padded to *height*.
+      def visible_lines
+        lines = content_lines.slice(offset, viewport_height) || []
+        return lines unless height
 
-          lines + Array.new([height - lines.length, 0].max, "")
-        end
+        lines + Array.new([height - lines.length, 0].max, "")
+      end
 
-        # Renders a single line according to the configured width and wrap mode: clips to the
-        # visible column window when not wrapping, otherwise wraps the line to the width.
-        def render_line(line)
-          return line unless width
-          return pad_line(line, width) if wrap?
+      # Renders a single line according to the configured width and wrap mode: clips to the
+      # visible column window when not wrapping, otherwise wraps the line to the width.
+      def render_line(line)
+        return line unless width
+        return pad_line(line, width) if wrap?
 
-          pad_line(clip_line(line), width)
-        end
+        pad_line(clip_line(line), width)
+      end
 
-        # Clips *line* to the visible column window while preserving active ANSI styling.
-        def clip_line(line)
-          clipped = clip_tokens(line.to_s)
-          needs_reset?(clipped) ? "#{clipped}\e[0m" : clipped
-        end
+      # Clips *line* to the visible column window while preserving active ANSI styling.
+      def clip_line(line)
+        clipped = clip_tokens(line.to_s)
+        needs_reset?(clipped) ? "#{clipped}\e[0m" : clipped
+      end
 
-        # Walks *line* token-by-token, copying ANSI escapes through and emitting only the
-        # characters that fall inside the visible column window.
-        def clip_tokens(line)
-          state = {cursor: 0, output: +""}
-          line.scan(/#{ANSI_PATTERN}|./mo) do |token|
-            ansi?(token) ? append_ansi(state, token) : append_character(state, token)
-          end
-          state.fetch(:output)
+      # Walks *line* token-by-token, copying ANSI escapes through and emitting only the
+      # characters that fall inside the visible column window.
+      def clip_tokens(line)
+        state = {cursor: 0, output: +""}
+        line.scan(/#{ANSI_PATTERN}|./mo) do |token|
+          ansi?(token) ? append_ansi(state, token) : append_character(state, token)
         end
+        state.fetch(:output)
+      end
 
-        # Appends an ANSI escape token to the output buffer unchanged.
-        def append_ansi(state, token)
-          state.fetch(:output) << token
-        end
+      # Appends an ANSI escape token to the output buffer unchanged.
+      def append_ansi(state, token)
+        state.fetch(:output) << token
+      end
 
-        # Appends a single character token to the output buffer when it falls inside the
-        # visible column window, advancing the visual cursor.
-        def append_character(state, char)
-          char_width = Unicode::DisplayWidth.of(char)
-          cursor = state.fetch(:cursor)
-          state.fetch(:output) << char if visible?(cursor, char_width)
-          state[:cursor] = cursor + char_width
-        end
+      # Appends a single character token to the output buffer when it falls inside the
+      # visible column window, advancing the visual cursor.
+      def append_character(state, char)
+        char_width = Unicode::DisplayWidth.of(char)
+        cursor = state.fetch(:cursor)
+        state.fetch(:output) << char if visible?(cursor, char_width)
+        state[:cursor] = cursor + char_width
+      end
 
-        # True when the character at *cursor* (with the given display *char_width*) is within
-        # the visible column window.
-        def visible?(cursor, char_width)
-          cursor >= column && cursor + char_width <= column + width
-        end
+      # True when the character at *cursor* (with the given display *char_width*) is within
+      # the visible column window.
+      def visible?(cursor, char_width)
+        cursor >= column && cursor + char_width <= column + width
+      end
 
-        # True when *value* contains ANSI codes but does not end with a reset — needed because
-        # the clip may truncate styling in the middle of a styled run.
-        def needs_reset?(value)
-          value.match?(ANSI_PATTERN) && !value.end_with?("\e[0m")
-        end
+      # True when *value* contains ANSI codes but does not end with a reset — needed because
+      # the clip may truncate styling in the middle of a styled run.
+      def needs_reset?(value)
+        value.match?(ANSI_PATTERN) && !value.end_with?("\e[0m")
+      end
 
-        # Pads *line* to *target_width* with trailing spaces, leaving the line itself unchanged.
-        def pad_line(line, target_width)
-          line + (" " * [target_width - UI::Width.measure(line), 0].max)
-        end
+      # Pads *line* to *target_width* with trailing spaces, leaving the line itself unchanged.
+      def pad_line(line, target_width)
+        line + (" " * [target_width - UI::Width.measure(line), 0].max)
+      end
 
-        # Returns the content lines, wrapped to *width* when wrap is enabled.
-        def content_lines
-          return wrapped_content_lines if wrap?
+      # Returns the content lines, wrapped to *width* when wrap is enabled.
+      def content_lines
+        return wrapped_content_lines if wrap?
 
-          rendered_content.lines(chomp: true)
-        end
+        rendered_content.lines(chomp: true)
+      end
 
-        # Wraps the content to *width* via UI::visible_slice, returning an array of wrapped lines.
-        def wrapped_content_lines
-          rendered_content.lines(chomp: true).flat_map { |line| wrap_line(line) }
-        end
+      # Wraps the content to *width* via UI::visible_slice, returning an array of wrapped lines.
+      def wrapped_content_lines
+        rendered_content.lines(chomp: true).flat_map { |line| wrap_line(line) }
+      end
 
-        # Wraps a single *line* into chunks of *width* display columns.
-        def wrap_line(line)
-          line_width = UI::Width.measure(line)
-          return [""] if line_width.zero?
-
-          start_column = 0
-          out = []
-          while start_column < line_width
-            out << UI.visible_slice(line, start_column, width)
-            start_column += width
-          end
-          out
-        end
+      # Wraps a single *line* into chunks of *width* display columns.
+      def wrap_line(line)
+        line_width = UI::Width.measure(line)
+        return [""] if line_width.zero?
 
-        # Returns the rendered content string, calling `render.to_s` on the content object when
-        # it responds to render.
-        def rendered_content
-          content.respond_to?(:render) ? content.render.to_s : content.to_s
+        start_column = 0
+        out = []
+        while start_column < line_width
+          out << UI.visible_slice(line, start_column, width)
+          start_column += width
         end
+        out
+      end
 
-        # Returns the visible row count (the configured *height* or the content's line count).
-        def viewport_height
-          height || content_lines.length
-        end
+      # Returns the rendered content string, calling `render.to_s` on the content object when
+      # it responds to render.
+      def rendered_content
+        content.respond_to?(:render) ? content.render.to_s : content.to_s
+      end
 
-        # Returns the number of rows to advance on a page up/down: at least 1, otherwise the
-        # viewport height.
-        def page_size
-          [viewport_height, 1].max
-        end
+      # Returns the visible row count (the configured *height* or the content's line count).
+      def viewport_height
+        height || content_lines.length
+      end
 
-        # Returns the maximum allowed row offset (so the bottom of the content is reachable).
-        def max_offset
-          [content_lines.length - viewport_height, 0].max
-        end
+      # Returns the number of rows to advance on a page up/down: at least 1, otherwise the
+      # viewport height.
+      def page_size
+        [viewport_height, 1].max
+      end
 
-        # Returns the maximum allowed column offset. Returns 0 when wrapping is enabled or
-        # when no width is configured.
-        def max_column
-          return 0 if wrap?
-          return 0 unless width
+      # Returns the maximum allowed row offset (so the bottom of the content is reachable).
+      def max_offset
+        [content_lines.length - viewport_height, 0].max
+      end
 
-          [content_width - width, 0].max
-        end
+      # Returns the maximum allowed column offset. Returns 0 when wrapping is enabled or
+      # when no width is configured.
+      def max_column
+        return 0 if wrap?
+        return 0 unless width
 
-        # Returns the maximum display width across all content lines.
-        def content_width
-          content_lines.map { |line| UI::Width.measure(line) }.max || 0
-        end
+        [content_width - width, 0].max
+      end
 
-        # True when *token* is an ANSI escape sequence.
-        def ansi?(token)
-          token.match?(ANSI_PATTERN)
-        end
+      # Returns the maximum display width across all content lines.
+      def content_width
+        content_lines.map { |line| UI::Width.measure(line) }.max || 0
+      end
 
-        # True when soft-wrapping is enabled and a positive width is configured.
-        def wrap?
-          @wrap && width&.positive?
-        end
+      # True when *token* is an ANSI escape sequence.
+      def ansi?(token)
+        token.match?(ANSI_PATTERN)
+      end
+
+      # True when soft-wrapping is enabled and a positive width is configured.
+      def wrap?
+        @wrap && width&.positive?
       end
     end
   end

data/lib/charming/presentation/layout/builder.rb

@@ -1,85 +1,83 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Layout
-      # Builder turns a declarative `screen_layout { ... }` block into a layout tree of
-      # ScreenLayout → Split → Pane nodes. The block DSL is `split(direction) { ... }`,
-      # `pane(name) { ... }`, and `overlay { ... }`. Unknown method calls in the block are
-      # forwarded to the underlying view so view helpers (e.g., `text`) work inside layout blocks.
-      class Builder
-        # Builds the layout tree by evaluating the *block* in the builder's context.
-        # Returns the root ScreenLayout node.
-        def self.build(screen:, view:, background: nil, &)
-          new(screen: screen, view: view, background: background).build(&)
-        end
+  module Layout
+    # Builder turns a declarative `screen_layout { ... }` block into a layout tree of
+    # ScreenLayout → Split → Pane nodes. The block DSL is `split(direction) { ... }`,
+    # `pane(name) { ... }`, and `overlay { ... }`. Unknown method calls in the block are
+    # forwarded to the underlying view so view helpers (e.g., `text`) work inside layout blocks.
+    class Builder
+      # Builds the layout tree by evaluating the *block* in the builder's context.
+      # Returns the root ScreenLayout node.
+      def self.build(screen:, view:, background: nil, &)
+        new(screen: screen, view: view, background: background).build(&)
+      end
 
-        def initialize(screen:, view:, background: nil)
-          @view = view
-          @root = ScreenLayout.new(screen: screen, background: background)
-          @stack = [@root]
-        end
+      def initialize(screen:, view:, background: nil)
+        @view = view
+        @root = ScreenLayout.new(screen: screen, background: background)
+        @stack = [@root]
+      end
 
-        # Evaluates *block* in the builder's context, then returns the root ScreenLayout node.
-        def build(&)
-          instance_eval(&) if block_given?
-          root
-        end
+      # Evaluates *block* in the builder's context, then returns the root ScreenLayout node.
+      def build(&)
+        instance_eval(&) if block_given?
+        root
+      end
 
-        # Adds a Split node to the current scope. *direction* is `:horizontal` or `:vertical`.
-        # *gap* (in cells) is inserted between children. Additional *options* are forwarded
-        # to Split. The block, if given, is evaluated in the split's scope (for nested children).
-        def split(direction, gap: 0, **options, &)
-          node = Split.new(direction: direction, gap: gap, **options)
-          append(node)
-          within(node, &)
-          node
-        end
+      # Adds a Split node to the current scope. *direction* is `:horizontal` or `:vertical`.
+      # *gap* (in cells) is inserted between children. Additional *options* are forwarded
+      # to Split. The block, if given, is evaluated in the split's scope (for nested children).
+      def split(direction, gap: 0, **options, &)
+        node = Split.new(direction: direction, gap: gap, **options)
+        append(node)
+        within(node, &)
+        node
+      end
 
-        # Adds a Pane leaf node to the current scope. *name* (optional) is the focus slot name;
-        # *content* (or a *block*) is the body. *options* are forwarded to Pane.
-        def pane(name = nil, content = nil, **options, &block)
-          node = Pane.new(name: name, content: content, block: block, view: view, **options)
-          append(node)
-          node
-        end
+      # Adds a Pane leaf node to the current scope. *name* (optional) is the focus slot name;
+      # *content* (or a *block*) is the body. *options* are forwarded to Pane.
+      def pane(name = nil, content = nil, **options, &block)
+        node = Pane.new(name: name, content: content, block: block, view: view, **options)
+        append(node)
+        node
+      end
 
-        # Adds an Overlay node to the root ScreenLayout. *top* and *left* default to :center.
-        # The block, if given, is evaluated in the view's context.
-        def overlay(content = nil, top: :center, left: :center, **options, &block)
-          root.add_overlay(Overlay.new(content: content, block: block, view: view, top: top, left: left, **options))
-        end
+      # Adds an Overlay node to the root ScreenLayout. *top* and *left* default to :center.
+      # The block, if given, is evaluated in the view's context.
+      def overlay(content = nil, top: :center, left: :center, **options, &block)
+        root.add_overlay(Overlay.new(content: content, block: block, view: view, top: top, left: left, **options))
+      end
 
-        # Forwards unknown method calls to the underlying view so helpers like `text` work
-        # inside layout blocks.
-        def respond_to_missing?(name, include_private = false)
-          view.respond_to?(name, include_private) || super
-        end
+      # Forwards unknown method calls to the underlying view so helpers like `text` work
+      # inside layout blocks.
+      def respond_to_missing?(name, include_private = false)
+        view.respond_to?(name, include_private) || super
+      end
 
-        def method_missing(name, ...)
-          return view.__send__(name, ...) if view.respond_to?(name, true)
+      def method_missing(name, ...)
+        return view.__send__(name, ...) if view.respond_to?(name, true)
 
-          super
-        end
+        super
+      end
 
-        private
+      private
 
-        attr_reader :root, :stack, :view
+      attr_reader :root, :stack, :view
 
-        # Appends *node* to the topmost scope on the stack.
-        def append(node)
-          stack.last.add_child(node)
-        end
+      # Appends *node* to the topmost scope on the stack.
+      def append(node)
+        stack.last.add_child(node)
+      end
 
-        # Pushes *node* onto the stack, evaluates *block* in the builder's context, then pops it.
-        def within(node, &)
-          return unless block_given?
+      # Pushes *node* onto the stack, evaluates *block* in the builder's context, then pops it.
+      def within(node, &)
+        return unless block_given?
 
-          stack.push(node)
-          instance_eval(&)
-        ensure
-          stack.pop
-        end
+        stack.push(node)
+        instance_eval(&)
+      ensure
+        stack.pop
       end
     end
   end