charming 0.1.2 → 0.1.4

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

@@ -1,56 +1,54 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Layout
-      # Overlay is a compositing node used by ScreenLayout for floating elements (modals,
-      # dialogs, command palettes). It positions its content at *top*/*left* (each may be
-      # `:center` or an absolute cell offset) and optionally sizes it via *width*/*height*
-      # 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
-
-        # *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)
-          @content = content
-          @block = block
-          @view = view
-          @top = top
-          @left = left
-          @width = width
-          @height = height
-          @style = style
-        end
-
-        # Renders the overlay's content; when *width* or *height* is set, places the rendered
-        # content into a sized canvas before returning.
-        def render
-          return styled_content unless width || height
-
-          UI.place(styled_content, width: width || UI.block_width(styled_content.lines(chomp: true)), height: height || styled_content.lines.count)
-        end
-
-        private
-
-        # The raw content, body block, view, and sizing/style options.
-        attr_reader :content, :block, :view, :width, :height, :style
-
-        # Returns the rendered content wrapped in the configured *style* (when present).
-        def styled_content
-          return rendered_content unless style
-
-          style.render(rendered_content)
-        end
-
-        # Evaluates the content (block or constant) and returns its rendered string.
-        def rendered_content
-          value = block ? view.instance_exec(&block) : content
-          value.respond_to?(:render) ? value.render.to_s : value.to_s
-        end
+  module Layout
+    # Overlay is a compositing node used by ScreenLayout for floating elements (modals,
+    # dialogs, command palettes). It positions its content at *top*/*left* (each may be
+    # `:center` or an absolute cell offset) and optionally sizes it via *width*/*height*
+    # 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
+
+      # *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)
+        @content = content
+        @block = block
+        @view = view
+        @top = top
+        @left = left
+        @width = width
+        @height = height
+        @style = style
+      end
+
+      # Renders the overlay's content; when *width* or *height* is set, places the rendered
+      # content into a sized canvas before returning.
+      def render
+        return styled_content unless width || height
+
+        UI.place(styled_content, width: width || UI.block_width(styled_content.lines(chomp: true)), height: height || styled_content.lines.count)
+      end
+
+      private
+
+      # The raw content, body block, view, and sizing/style options.
+      attr_reader :content, :block, :view, :width, :height, :style
+
+      # Returns the rendered content wrapped in the configured *style* (when present).
+      def styled_content
+        return rendered_content unless style
+
+        style.render(rendered_content)
+      end
+
+      # Evaluates the content (block or constant) and returns its rendered string.
+      def rendered_content
+        value = block ? view.instance_exec(&block) : content
+        value.respond_to?(:render) ? value.render.to_s : value.to_s
       end
     end
   end

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

@@ -1,143 +1,154 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Layout
-      # Pane is a leaf layout node: a single rectangle with optional border, padding, and
-      # styling, containing a piece of content (a string, a View, or a block evaluated in the
-      # view's context). Panes with a `name` and `focus: true` are registered as focusable
-      # slots in the controller's focus ring.
-      class Pane
-        # The pane's focus slot name, fixed width, fixed height, and grow weight.
-        attr_reader :name, :width, :height, :grow
-
-        # *name* is the focus slot identifier (optional). *content* or *block* provides the body.
-        # *width*/*height*/*grow* control sizing. *border* may be `true` (normal border) or a
-        # border name symbol. *padding* may be 1, 2, or 4 values (CSS-style shorthand).
-        # *style* sets the base style; *focused_style* overrides it when the pane is focused.
-        # *focus: true* marks the pane as focusable. *scroll*/*clip*/*wrap* control how
-        # overflow content is rendered (via the embedded Viewport).
-        def initialize(name: nil, content: nil, block: nil, view: nil, width: nil, height: nil, grow: nil, border: nil, padding: nil, style: nil, focused_style: nil, focus: false, scroll: false, clip: true, wrap: false)
-          @name = name
-          @content = content
-          @block = block
-          @view = view
-          @width = width
-          @height = height
-          @grow = grow
-          @border = border
-          @padding = padding
-          @style = style
-          @focused_style = focused_style
-          @focus = focus
-          @scroll = scroll
-          @clip = clip
-          @wrap = wrap
-        end
+  module Layout
+    # Pane is a leaf layout node: a single rectangle with optional border, padding, and
+    # styling, containing a piece of content (a string, a View, or a block evaluated in the
+    # view's context). Panes with a `name` and `focus: true` are registered as focusable
+    # slots in the controller's focus ring.
+    class Pane
+      # The pane's focus slot name, fixed width, fixed height, and grow weight.
+      attr_reader :name, :width, :height, :grow
+
+      # *name* is the focus slot identifier (optional). *content* or *block* provides the body.
+      # *width*/*height*/*grow* control sizing. *border* may be `true` (normal border) or a
+      # border name symbol. *padding* may be 1, 2, or 4 values (CSS-style shorthand).
+      # *style* sets the base style; *focused_style* overrides it when the pane is focused.
+      # *focus: true* marks the pane as focusable. *scroll*/*clip*/*wrap* control how
+      # overflow content is rendered (via the embedded Viewport).
+      def initialize(name: nil, content: nil, block: nil, view: nil, width: nil, height: nil, grow: nil, border: nil, padding: nil, style: nil, focused_style: nil, focus: false, scroll: false, clip: true, wrap: false)
+        @name = name
+        @content = content
+        @block = block
+        @view = view
+        @width = width
+        @height = height
+        @grow = grow
+        @border = border
+        @padding = padding
+        @style = style
+        @focused_style = focused_style
+        @focus = focus
+        @scroll = scroll
+        @clip = clip
+        @wrap = wrap
+      end
 
-        # Raises ArgumentError — panes are leaves and cannot contain layout children.
-        def add_child(_node)
-          raise ArgumentError, "pane cannot contain layout children"
-        end
+      # Raises ArgumentError — panes are leaves and cannot contain layout children.
+      def add_child(_node)
+        raise ArgumentError, "pane cannot contain layout children"
+      end
 
-        # Returns [name] when the pane is marked focusable and has a name, otherwise [].
-        def focusable_names
-          (focus && name) ? [name] : []
-        end
+      # Returns [name] when the pane is marked focusable and has a name, otherwise [].
+      def focusable_names
+        (focus && name) ? [name] : []
+      end
 
-        # Renders the pane into *rect*, applying the configured style, border, and padding
-        # around the evaluated content.
-        def render(rect)
-          outer_style(rect).render(rendered_content(rect))
-        end
+      # Returns the mouse target represented by this pane, if it has a name.
+      def mouse_targets(rect)
+        return [] unless name
 
-        private
+        [{name: name, rect: rect, inner_rect: inner_rect(rect)}]
+      end
 
-        # The raw content, the body block, the view used for instance_exec, and styling options.
-        attr_reader :content, :block, :view, :border, :padding, :style, :focused_style, :focus, :scroll, :clip, :wrap
+      # Renders the pane into *rect*, applying the configured style, border, and padding
+      # around the evaluated content.
+      def render(rect)
+        outer_style(rect).render(rendered_content(rect))
+      end
 
-        # Returns the content string for *rect*, optionally clipped/scrolled by an embedded Viewport.
-        def rendered_content(rect)
-          value = evaluate_content
-          return value unless clip || scroll
+      private
 
-          Components::Viewport.new(content: value, width: inner_rect(rect).width, height: inner_rect(rect).height, wrap: wrap).render
-        end
+      # The raw content, the body block, the view used for instance_exec, and styling options.
+      attr_reader :content, :block, :view, :border, :padding, :style, :focused_style, :focus, :scroll, :clip, :wrap
 
-        # Evaluates the configured content (block or constant) and renders it to a string.
-        def evaluate_content
-          value = block ? view.instance_exec(&block) : content
-          value.respond_to?(:render) ? value.render.to_s : value.to_s
-        end
+      # Returns the content string for *rect*, optionally clipped/scrolled by an embedded Viewport.
+      def rendered_content(rect)
+        content_rect = inner_rect(rect)
+        value = evaluate_content(content_rect)
+        return value unless clip || scroll
 
-        # Builds the outer style object with optional border and padding, sized to the
-        # inner rect of the pane.
-        def outer_style(rect)
-          styled = current_style
-          styled = styled.border(border_style) if border
-          styled = styled.padding(*padding_values) if padding
-          styled.width(inner_rect(rect).width).height(inner_rect(rect).height)
+        Components::Viewport.new(content: value, width: content_rect.width, height: content_rect.height, wrap: wrap).render
+      end
+
+      # Evaluates the configured content (block or constant) and renders it to a string.
+      # Pane blocks may accept the inner content Rect when they need exact available dimensions.
+      def evaluate_content(content_rect)
+        value = if block
+          block.arity.zero? ? view.instance_exec(&block) : view.instance_exec(content_rect, &block)
+        else
+          content
         end
+        value.respond_to?(:render) ? value.render.to_s : value.to_s
+      end
 
-        # Returns the active style: the focused variant when the pane is focused, otherwise
-        # the configured style or a default UI::Style.
-        def current_style
-          return focused_pane_style if focused?
+      # Builds the outer style object with optional border and padding, sized to the
+      # inner rect of the pane.
+      def outer_style(rect)
+        styled = current_style
+        styled = styled.border(border_style) if border
+        styled = styled.padding(*padding_values) if padding
+        styled.width(inner_rect(rect).width).height(inner_rect(rect).height)
+      end
 
-          style || UI.style
-        end
+      # Returns the active style: the focused variant when the pane is focused, otherwise
+      # the configured style or a default UI::Style.
+      def current_style
+        return focused_pane_style if focused?
 
-        # Returns the focused-pane style: the focused_style override, or the theme's title style.
-        def focused_pane_style
-          focused_style || view.__send__(:theme).title
-        end
+        style || UI.style
+      end
 
-        # True when the pane is configured for focus and the view reports it as currently focused.
-        def focused?
-          focus && name && view.focused?(name)
-        end
+      # Returns the focused-pane style: the focused_style override, or the theme's title style.
+      def focused_pane_style
+        focused_style || view.__send__(:theme).title
+      end
 
-        # Returns the inner Rect after border and padding insets are applied.
-        def inner_rect(rect)
-          rect.inset(
-            top: border_top + padding_top,
-            right: border_right + padding_right,
-            bottom: border_bottom + padding_bottom,
-            left: border_left + padding_left
-          )
-        end
+      # True when the pane is configured for focus and the view reports it as currently focused.
+      def focused?
+        focus && name && view.focused?(name)
+      end
 
-        # Resolves the border style symbol: :normal when border is `true`, otherwise the configured value.
-        def border_style
-          (border == true) ? :normal : border
-        end
+      # Returns the inner Rect after border and padding insets are applied.
+      def inner_rect(rect)
+        rect.inset(
+          top: border_top + padding_top,
+          right: border_right + padding_right,
+          bottom: border_bottom + padding_bottom,
+          left: border_left + padding_left
+        )
+      end
 
-        # Border thickness on each side (1 when a border is configured, 0 otherwise).
-        def border_top = border ? 1 : 0
-        def border_right = border ? 1 : 0
-        def border_bottom = border ? 1 : 0
-        def border_left = border ? 1 : 0
+      # Resolves the border style symbol: :normal when border is `true`, otherwise the configured value.
+      def border_style
+        (border == true) ? :normal : border
+      end
 
-        # The padding values normalized to [top, right, bottom, left] form.
-        def padding_values
-          @padding_values ||= expand_padding(Array(padding))
-        end
+      # Border thickness on each side (1 when a border is configured, 0 otherwise).
+      def border_top = border ? 1 : 0
+      def border_right = border ? 1 : 0
+      def border_bottom = border ? 1 : 0
+      def border_left = border ? 1 : 0
+
+      # The padding values normalized to [top, right, bottom, left] form.
+      def padding_values
+        @padding_values ||= expand_padding(Array(padding))
+      end
 
-        # Per-side padding values (0 when no padding is configured).
-        def padding_top = padding ? padding_values[0] : 0
-        def padding_right = padding ? padding_values[1] : 0
-        def padding_bottom = padding ? padding_values[2] : 0
-        def padding_left = padding ? padding_values[3] : 0
-
-        # Normalizes 1/2/4 padding arguments to [top, right, bottom, left].
-        def expand_padding(values)
-          case values.length
-          when 1 then [values[0], values[0], values[0], values[0]]
-          when 2 then [values[0], values[1], values[0], values[1]]
-          when 4 then values
-          else
-            raise ArgumentError, "padding expects 1, 2, or 4 values"
-          end
+      # Per-side padding values (0 when no padding is configured).
+      def padding_top = padding ? padding_values[0] : 0
+      def padding_right = padding ? padding_values[1] : 0
+      def padding_bottom = padding ? padding_values[2] : 0
+      def padding_left = padding ? padding_values[3] : 0
+
+      # Normalizes 1/2/4 padding arguments to [top, right, bottom, left].
+      def expand_padding(values)
+        case values.length
+        when 1 then [values[0], values[0], values[0], values[0]]
+        when 2 then [values[0], values[1], values[0], values[1]]
+        when 4 then values
+        else
+          raise ArgumentError, "padding expects 1, 2, or 4 values"
         end
       end
     end

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

@@ -1,22 +1,25 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Layout
-      # Rect is an immutable rectangle with a top-left position (x, y) and dimensions
-      # (width, height). Layout operations produce new Rect instances rather than mutating
-      # existing ones.
-      Rect = Data.define(:x, :y, :width, :height) do
-        # Returns a new Rect inset by *top*/*right*/*bottom*/*left* cells. The result is
-        # clamped to a minimum width/height of 0.
-        def inset(top: 0, right: 0, bottom: 0, left: 0)
-          Rect.new(
-            x: x + left,
-            y: y + top,
-            width: [width - left - right, 0].max,
-            height: [height - top - bottom, 0].max
-          )
-        end
+  module Layout
+    # Rect is an immutable rectangle with a top-left position (x, y) and dimensions
+    # (width, height). Layout operations produce new Rect instances rather than mutating
+    # existing ones.
+    Rect = Data.define(:x, :y, :width, :height) do
+      # Returns true when the zero-based cell coordinate falls within this rectangle.
+      def cover?(point_x, point_y)
+        point_x >= x && point_x < x + width && point_y >= y && point_y < y + height
+      end
+
+      # Returns a new Rect inset by *top*/*right*/*bottom*/*left* cells. The result is
+      # clamped to a minimum width/height of 0.
+      def inset(top: 0, right: 0, bottom: 0, left: 0)
+        Rect.new(
+          x: x + left,
+          y: y + top,
+          width: [width - left - right, 0].max,
+          height: [height - top - bottom, 0].max
+        )
       end
     end
   end

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

@@ -1,59 +1,64 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Layout
-      # ScreenLayout is the root of a layout tree. It owns a single child (typically a Split
-      # or Pane) rendered into the full terminal screen, and an ordered list of Overlays
-      # composited on top of the rendered body.
-      class ScreenLayout
-        # *screen* is the Charming::Screen whose dimensions define the layout area.
-        # *background* (optional) is a UI::Style applied to the empty canvas behind the body.
-        def initialize(screen:, background: nil)
-          @screen = screen
-          @background = background
-          @child = nil
-          @overlays = []
-        end
+  module Layout
+    # ScreenLayout is the root of a layout tree. It owns a single child (typically a Split
+    # or Pane) rendered into the full terminal screen, and an ordered list of Overlays
+    # composited on top of the rendered body.
+    class ScreenLayout
+      # *screen* is the Charming::Screen whose dimensions define the layout area.
+      # *background* (optional) is a UI::Style applied to the empty canvas behind the body.
+      def initialize(screen:, background: nil)
+        @screen = screen
+        @background = background
+        @child = nil
+        @overlays = []
+      end
 
-        # Sets the single root child. Raises ArgumentError when a child is already present.
-        def add_child(node)
-          raise ArgumentError, "screen_layout accepts one root layout node" if child
+      # Sets the single root child. Raises ArgumentError when a child is already present.
+      def add_child(node)
+        raise ArgumentError, "screen_layout accepts one root layout node" if child
 
-          @child = node
-        end
+        @child = node
+      end
 
-        # Appends an overlay to be composited on top of the body, in registration order.
-        def add_overlay(node)
-          overlays << node
-        end
+      # Appends an overlay to be composited on top of the body, in registration order.
+      def add_overlay(node)
+        overlays << node
+      end
 
-        # Returns the focusable names from the child, or [] when no child has been added.
-        def focusable_names
-          child ? child.focusable_names : []
-        end
+      # Returns the focusable names from the child, or [] when no child has been added.
+      def focusable_names
+        child ? child.focusable_names : []
+      end
+
+      # Returns all named pane mouse targets for the full screen layout.
+      def mouse_targets
+        return [] unless child
+
+        child.mouse_targets(Rect.new(x: 0, y: 0, width: screen.width, height: screen.height))
+      end
 
-        # Renders the child into the full-screen rect, then overlays each registered overlay
-        # on top in order.
-        def render
-          body = UI.place(render_child, width: screen.width, height: screen.height, background: background)
+      # Renders the child into the full-screen rect, then overlays each registered overlay
+      # on top in order.
+      def render
+        body = UI.place(render_child, width: screen.width, height: screen.height, background: background)
 
-          overlays.reduce(body) do |current, overlay|
-            UI.overlay(current, overlay.render, top: overlay.top, left: overlay.left)
-          end
+        overlays.reduce(body) do |current, overlay|
+          UI.overlay(current, overlay.render, top: overlay.top, left: overlay.left)
         end
+      end
 
-        private
+      private
 
-        # The screen, background style, the single child, and the list of overlays.
-        attr_reader :screen, :background, :child, :overlays
+      # The screen, background style, the single child, and the list of overlays.
+      attr_reader :screen, :background, :child, :overlays
 
-        # Renders the child into a full-screen Rect, or returns an empty string when no child.
-        def render_child
-          return "" unless child
+      # Renders the child into a full-screen Rect, or returns an empty string when no child.
+      def render_child
+        return "" unless child
 
-          child.render(Rect.new(x: 0, y: 0, width: screen.width, height: screen.height))
-        end
+        child.render(Rect.new(x: 0, y: 0, width: screen.width, height: screen.height))
       end
     end
   end