charming 0.1.1 → 0.1.2

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

@@ -5,10 +5,18 @@ 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,
@@ -20,8 +28,12 @@ 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.
         def initialize(content:, width: nil, height: nil, offset: 0, column: 0, wrap: false, keymap: :vim)
           super()
           @content = content
@@ -34,10 +46,13 @@ module Charming
           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
 
+        # 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
 
@@ -62,51 +77,61 @@ module Charming
 
         attr_reader :content, :width, :height
 
+        # 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 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 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 one column left.
         def scroll_left
           @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
 
+        # 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
@@ -114,6 +139,8 @@ module Charming
           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?
@@ -121,11 +148,14 @@ module Charming
           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|
@@ -134,10 +164,13 @@ module Charming
           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)
@@ -145,28 +178,36 @@ module Charming
           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)
         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?
@@ -180,22 +221,30 @@ module Charming
           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
         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 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 row offset (so the bottom of the content is reachable).
         def max_offset
           [content_lines.length - viewport_height, 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
@@ -203,14 +252,17 @@ module Charming
           [content_width - width, 0].max
         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 *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

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

@@ -0,0 +1,86 @@
+# 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
+
+        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
+
+        # 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 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
+
+        def method_missing(name, ...)
+          return view.__send__(name, ...) if view.respond_to?(name, true)
+
+          super
+        end
+
+        private
+
+        attr_reader :root, :stack, :view
+
+        # 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?
+
+          stack.push(node)
+          instance_eval(&)
+        ensure
+          stack.pop
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# 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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# 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
+
+        # 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
+
+        # 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
+
+        private
+
+        # 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
+
+        # 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
+
+          Components::Viewport.new(content: value, width: inner_rect(rect).width, height: inner_rect(rect).height, wrap: wrap).render
+        end
+
+        # 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
+
+        # 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
+
+        # 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?
+
+          style || UI.style
+        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
+
+        # 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 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
+
+        # Resolves the border style symbol: :normal when border is `true`, otherwise the configured value.
+        def border_style
+          (border == true) ? :normal : border
+        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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# 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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# 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
+
+        # 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
+
+        # 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
+
+        # 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
+        end
+
+        private
+
+        # 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
+
+          child.render(Rect.new(x: 0, y: 0, width: screen.width, height: screen.height))
+        end
+      end
+    end
+  end
+end