charming 0.2.0 → 0.2.2

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    # Tree renders a collapsible hierarchy (file explorers, nested data). Nodes are
+    # hashes: `{label: "src", children: [...], expanded: true}` — `children` and
+    # `expanded` are optional. Navigation: up/down move the cursor through *visible*
+    # nodes, right expands, left collapses (or jumps to the parent), Enter returns
+    # `[:selected, node]` for leaves and toggles branches. Mouse clicks move the cursor
+    # and toggle branches.
+    class Tree < Component
+      include KeyboardHandler
+
+      KEY_ACTIONS = {
+        up: :move_up,
+        down: :move_down,
+        left: :collapse_or_parent,
+        right: :expand,
+        home: :move_home,
+        end: :move_end
+      }.freeze
+
+      # The root node list and the cursor index into the visible-node list.
+      attr_reader :nodes, :cursor_index
+
+      # *nodes* is the array of root node hashes (mutated in place to track expansion).
+      # *height* optionally constrains the visible window.
+      def initialize(nodes:, cursor_index: 0, height: nil, keymap: :vim, theme: nil)
+        super(theme: theme)
+        @nodes = nodes
+        @cursor_index = cursor_index
+        @height = height
+        @keymap = keymap
+        clamp_cursor
+      end
+
+      # Enter selects a leaf (`[:selected, node]`) or toggles a branch. Navigation keys
+      # are handled by KeyboardHandler.
+      def handle_key(event)
+        node = current_node
+        return nil unless node
+        return select_or_toggle(node) if Charming.key_of(event) == :enter
+
+        super
+      end
+
+      # A click moves the cursor to the clicked row; clicking a branch toggles it.
+      def handle_mouse(event)
+        return nil unless event.respond_to?(:click?) && event.click?
+
+        clicked = viewport_start + event.y
+        return nil if clicked >= visible_nodes.length || event.y.negative?
+
+        @cursor_index = clicked
+        node = current_node
+        toggle(node) if branch?(node)
+        :handled
+      end
+
+      # The node under the cursor (a node hash), or nil for an empty tree.
+      def current_node
+        visible_nodes[cursor_index]&.fetch(:node)
+      end
+
+      # Renders the visible window of the flattened tree.
+      def render
+        window = visible_nodes[viewport_start, viewport_height] || []
+        window.each_with_index.map do |entry, index|
+          render_node(entry, viewport_start + index)
+        end.join("\n")
+      end
+
+      private
+
+      # Flattens the tree into visible rows: `{node:, depth:}` entries, skipping
+      # children of collapsed branches.
+      def visible_nodes
+        flatten(nodes, 0)
+      end
+
+      def flatten(list, depth)
+        Array(list).flat_map do |node|
+          entry = [{node: node, depth: depth}]
+          entry += flatten(node[:children], depth + 1) if branch?(node) && node[:expanded]
+          entry
+        end
+      end
+
+      # Renders one row: indentation, expansion marker, label; cursor row uses the
+      # selected style.
+      def render_node(entry, index)
+        node = entry.fetch(:node)
+        marker = if branch?(node)
+          node[:expanded] ? "▾ " : "▸ "
+        else
+          "  "
+        end
+        line = "#{"  " * entry.fetch(:depth)}#{marker}#{node[:label]}"
+        (index == cursor_index) ? theme.selected.render(line) : line
+      end
+
+      def branch?(node)
+        node && node[:children] && !node[:children].empty?
+      end
+
+      def select_or_toggle(node)
+        return [:selected, node] unless branch?(node)
+
+        toggle(node)
+        :handled
+      end
+
+      def toggle(node)
+        node[:expanded] = !node[:expanded]
+      end
+
+      def expand
+        node = current_node
+        node[:expanded] = true if branch?(node)
+      end
+
+      # Collapses an expanded branch, or moves the cursor to the parent of a leaf or
+      # collapsed node.
+      def collapse_or_parent
+        node = current_node
+        if branch?(node) && node[:expanded]
+          node[:expanded] = false
+        else
+          parent = parent_index(cursor_index)
+          @cursor_index = parent if parent
+        end
+      end
+
+      # Index of the nearest row above with a smaller depth (the parent), or nil.
+      def parent_index(index)
+        rows = visible_nodes
+        depth = rows[index]&.fetch(:depth)
+        return nil unless depth&.positive?
+
+        (index - 1).downto(0).find { |candidate| rows[candidate].fetch(:depth) < depth }
+      end
+
+      def move_up
+        @cursor_index -= 1 if cursor_index.positive?
+      end
+
+      def move_down
+        @cursor_index += 1 if cursor_index < visible_nodes.length - 1
+      end
+
+      def move_home
+        @cursor_index = 0
+      end
+
+      def move_end
+        @cursor_index = [visible_nodes.length - 1, 0].max
+      end
+
+      # Top row of the visible window, keeping the cursor in view.
+      def viewport_start
+        return 0 unless @height
+
+        Layout.selected_window_start(selected_index: cursor_index, item_count: visible_nodes.length, window_size: @height)
+      end
+
+      def viewport_height
+        @height || visible_nodes.length
+      end
+
+      def clamp_cursor
+        max = [visible_nodes.length - 1, 0].max
+        @cursor_index = cursor_index.clamp(0, max)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Viewport
+      # ContentLines normalizes viewport content into display lines.
+      class ContentLines
+        def initialize(content:, width:, wrap:)
+          @content = content
+          @window_width = width
+          @wrap = wrap
+        end
+
+        def lines
+          return wrapped_lines if wrap?
+
+          rendered_content.lines(chomp: true)
+        end
+
+        def display_width
+          UI::Width.widest(lines)
+        end
+
+        private
+
+        attr_reader :content, :window_width, :wrap
+
+        def wrapped_lines
+          rendered_content.lines(chomp: true).flat_map { |line| wrap_line(line) }
+        end
+
+        def wrap_line(line)
+          line_width = UI::Width.measure(line)
+          return [""] if line_width.zero?
+
+          wrap_slices(line, line_width)
+        end
+
+        def wrap_slices(line, line_width)
+          (0...line_width).step(window_width).map do |start_column|
+            UI.visible_slice(line, start_column, window_width)
+          end
+        end
+
+        def rendered_content
+          content.respond_to?(:render) ? content.render.to_s : content.to_s
+        end
+
+        def wrap?
+          wrap && window_width&.positive?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module Charming
+  module Components
+    class Viewport
+      # LineWindow renders one content line inside the viewport's horizontal window.
+      class LineWindow
+        ANSI_PATTERN = /\e\[[0-9;]*m/
+
+        def initialize(width:, column:, wrap:)
+          @width = width
+          @column = column
+          @wrap = wrap
+        end
+
+        def render(line)
+          return line unless width
+          return pad_line(line, width) if wrap
+
+          pad_line(clip_line(line), width)
+        end
+
+        private
+
+        attr_reader :width, :column, :wrap
+
+        def clip_line(line)
+          clipped = clip_tokens(line.to_s)
+          needs_reset?(clipped) ? "#{clipped}\e[0m" : clipped
+        end
+
+        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
+
+        def append_ansi(state, token)
+          state.fetch(:output) << token
+        end
+
+        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
+
+        def visible?(cursor, char_width)
+          cursor >= column && cursor + char_width <= column + width
+        end
+
+        def needs_reset?(value)
+          value.match?(ANSI_PATTERN) && !value.end_with?("\e[0m")
+        end
+
+        def pad_line(line, target_width)
+          UI::Width.pad_to(line, target_width)
+        end
+
+        def ansi?(token)
+          token.match?(ANSI_PATTERN)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Charming
+  module Components
+    class Viewport
+      # Position owns the viewport's mutable row and column offsets.
+      class Position
+        attr_reader :offset, :column
+
+        def initialize(offset:, column:)
+          @offset = offset
+          @column = column
+        end
+
+        def scroll_up(bounds)
+          @offset -= 1
+          clamp(bounds)
+        end
+
+        def scroll_down(bounds)
+          @offset += 1
+          clamp(bounds)
+        end
+
+        def page_up(page_size, bounds)
+          @offset -= page_size
+          clamp(bounds)
+        end
+
+        def page_down(page_size, bounds)
+          @offset += page_size
+          clamp(bounds)
+        end
+
+        def home
+          @offset = 0
+          @column = 0
+        end
+
+        def end_at(bounds)
+          @offset = bounds.fetch(:max_offset)
+          @column = bounds.fetch(:max_column)
+        end
+
+        def scroll_left(bounds)
+          @column -= 1
+          clamp(bounds)
+        end
+
+        def scroll_right(bounds)
+          @column += 1
+          clamp(bounds)
+        end
+
+        def move_to(row, bounds)
+          @offset = row
+          clamp(bounds)
+        end
+
+        def clamp(bounds)
+          @offset = offset.clamp(0, bounds.fetch(:max_offset))
+          @column = column.clamp(0, bounds.fetch(:max_column))
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "unicode/display_width"
-
 module Charming
   module Components
     # Viewport is a scrollable region over multi-line content. Supports keyboard scrolling
@@ -12,9 +10,6 @@ module Charming
     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,
@@ -27,9 +22,6 @@ module Charming
         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.
@@ -38,11 +30,10 @@ module Charming
         @content = content
         @width = width
         @height = height
-        @offset = offset
-        @column = column
+        @position = Position.new(offset: offset, column: column)
         @wrap = wrap
         @keymap = keymap
-        clamp_position
+        position.clamp(bounds)
       end
 
       # Renders the visible window of content as a multi-line string.
@@ -50,6 +41,16 @@ module Charming
         visible_lines.map { |line| render_line(line) }.join("\n")
       end
 
+      # The current top-visible row.
+      def offset
+        @position.offset
+      end
+
+      # The current left-visible column.
+      def column
+        @position.column
+      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)
@@ -57,77 +58,61 @@ module Charming
 
         if event.scroll?
           scroll_delta = (event.button_name == :scroll_up) ? -1 : 1
-          @offset += scroll_delta
-          clamp_position
+          position.move_to(offset + scroll_delta, bounds)
           return :handled
         end
 
         return nil unless event.click?
 
         clicked_row = event.y
-        return nil if clicked_row < offset || clicked_row >= offset + viewport_height
+        return nil if clicked_row < 0 || clicked_row >= viewport_height
 
-        @offset = clicked_row
-        clamp_position
+        position.move_to(offset + clicked_row, bounds)
         :handled
       end
 
       private
 
-      attr_reader :content, :width, :height
+      attr_reader :content, :width, :height, :position
 
       # Scrolls the viewport up by one row.
       def scroll_up
-        @offset -= 1
-        clamp_position
+        position.scroll_up(bounds)
       end
 
       # Scrolls the viewport down by one row.
       def scroll_down
-        @offset += 1
-        clamp_position
+        position.scroll_down(bounds)
       end
 
       # Scrolls up by one viewport page.
       def page_up
-        @offset -= page_size
-        clamp_position
+        position.page_up(page_size, bounds)
       end
 
       # Scrolls down by one viewport page.
       def page_down
-        @offset += page_size
-        clamp_position
+        position.page_down(page_size, bounds)
       end
 
       # Scrolls to the top-left of the content.
       def scroll_home
-        @offset = 0
-        @column = 0
+        position.home
       end
 
       # Scrolls to the bottom-right of the content.
       def scroll_end
-        @offset = max_offset
-        @column = max_column
+        position.end_at(bounds)
       end
 
       # Scrolls one column left.
       def scroll_left
-        @column -= 1
-        clamp_position
+        position.scroll_left(bounds)
       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)
+        position.scroll_right(bounds)
       end
 
       # Returns the slice of content lines visible in the current viewport, padded to *height*.
@@ -141,89 +126,12 @@ module Charming
       # 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
-
-      # 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)
-      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
-
-      # 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
-
-      # 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)
+        line_window.render(line)
       end
 
       # 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
-
-      # 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
-
-      # 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
+        content_source.lines
       end
 
       # Returns the visible row count (the configured *height* or the content's line count).
@@ -253,18 +161,25 @@ module Charming
 
       # Returns the maximum display width across all content lines.
       def content_width
-        content_lines.map { |line| UI::Width.measure(line) }.max || 0
+        content_source.display_width
       end
 
-      # True when *token* is an ANSI escape sequence.
-      def ansi?(token)
-        token.match?(ANSI_PATTERN)
+      def bounds
+        {max_offset: max_offset, max_column: max_column}
       end
 
       # True when soft-wrapping is enabled and a positive width is configured.
       def wrap?
         @wrap && width&.positive?
       end
+
+      def line_window
+        LineWindow.new(width: width, column: column, wrap: wrap?)
+      end
+
+      def content_source
+        ContentLines.new(content: content, width: width, wrap: @wrap)
+      end
     end
   end
 end

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

@@ -41,7 +41,10 @@ module Charming
       def pane(name = nil, content = nil, **options, &block)
         node = Pane.new(
           name: name, content: content, block: block, view: view,
-          geometry: PaneGeometry.build(**options.slice(:width, :height, :grow, :border, :padding)),
+          geometry: PaneGeometry.build(**options.slice(
+            :width, :height, :grow, :border, :padding,
+            :min_width, :max_width, :min_height, :max_height
+          )),
           style: PaneStyle.build(**options.slice(:style, :focused_style)),
           behavior: PaneBehavior.build(**options.slice(:focus, :scroll, :clip, :wrap))
         )

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

@@ -8,13 +8,14 @@ module Charming
     # with an outer *style*.
     class Overlay
       # The vertical and horizontal offset (cell count or `:center`) of the overlay
-      # within the parent canvas.
-      attr_reader :top, :left
+      # within the parent canvas, and its stacking order (higher paints later/on top).
+      attr_reader :top, :left, :z_index
 
       # *content* (or a *block*) provides the body. *top*/*left* default to :center.
       # *width*/*height* fix the overlay's dimensions; when unset, the content's natural
-      # size is used. *style* wraps the rendered content in a UI::Style.
-      def initialize(content: nil, block: nil, view: nil, top: :center, left: :center, width: nil, height: nil, style: nil)
+      # size is used. *style* wraps the rendered content in a UI::Style. *z_index*
+      # controls stacking: higher values composite on top (ties keep registration order).
+      def initialize(content: nil, block: nil, view: nil, top: :center, left: :center, width: nil, height: nil, style: nil, z_index: 0)
         @content = content
         @block = block
         @view = view
@@ -23,6 +24,7 @@ module Charming
         @width = width
         @height = height
         @style = style
+        @z_index = z_index
       end
 
       # Renders the overlay's content; when *width* or *height* is set, places the rendered

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

@@ -8,7 +8,8 @@ module Charming
     # focusable slots in the controller's focus ring.
     class Pane
       attr_reader :name
-      delegate :width, :height, :grow, to: :geometry
+      delegate :width, :height, :grow,
+        :min_width, :max_width, :min_height, :max_height, to: :geometry
 
       # *name* is the focus slot identifier. *content* (or a *block*) is the body; *view*
       # is the view used for instance_exec when the block is given. *geometry*, *style*, and