charming 0.1.1 → 0.1.3

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Charming
+  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

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Charming
+  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

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Charming
+  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)
+        content_rect = inner_rect(rect)
+        value = evaluate_content(content_rect)
+        return value unless clip || scroll
+
+        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
+
+      # 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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Charming
+  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

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Charming
+  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

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Charming
+  module Layout
+    # Split divides a parent Rect among its child nodes horizontally or vertically.
+    # Children with a configured `width`/`height` are placed at that fixed size; children
+    # without a fixed size share the remaining space according to their `grow` weight.
+    class Split
+      # The fixed width/height of the split (when set) and the grow weight for the split itself.
+      attr_reader :width, :height, :grow
+
+      # *direction* is `:horizontal` or `:vertical`. *gap* (in cells) separates children.
+      # *width*/*height* are optional fixed dimensions for the split as a whole.
+      # *grow* is the weight for distributing remaining space (used when this Split is a
+      # child of another Split).
+      def initialize(direction:, gap: 0, width: nil, height: nil, grow: nil)
+        @direction = direction.to_sym
+        @gap = gap.to_i
+        @width = width
+        @height = height
+        @grow = grow
+        @children = []
+      end
+
+      # Appends *node* (a child Split or Pane) to this Split.
+      def add_child(node)
+        children << node
+      end
+
+      # Returns the flattened list of focusable names from all child nodes.
+      def focusable_names
+        children.flat_map(&:focusable_names)
+      end
+
+      # Renders each child into its own sub-rect, then overlays them on a blank canvas
+      # of the parent's dimensions.
+      def render(rect)
+        frame = UI.place("", width: rect.width, height: rect.height)
+
+        child_rects(rect).zip(children).each do |child_rect, child|
+          frame = UI.overlay(frame, child.render(child_rect), top: child_rect.y - rect.y, left: child_rect.x - rect.x)
+        end
+
+        frame
+      end
+
+      private
+
+      # The split direction (`:horizontal` or `:vertical`) and the inter-child gap.
+      attr_reader :direction, :gap, :children
+
+      # Returns an array of child rects sized according to each child's fixed dimensions
+      # and grow weights. Raises ArgumentError when *direction* is neither horizontal nor vertical.
+      def child_rects(rect)
+        return horizontal_rects(rect) if direction == :horizontal
+        return vertical_rects(rect) if direction == :vertical
+
+        raise ArgumentError, "unknown split direction: #{direction.inspect}"
+      end
+
+      # Computes per-child rects for a horizontal split.
+      def horizontal_rects(rect)
+        sizes = child_sizes(axis: :horizontal, available: rect.width)
+        left = rect.x
+
+        sizes.map do |width|
+          child_rect = Rect.new(x: left, y: rect.y, width: width, height: rect.height)
+          left += width + gap
+          child_rect
+        end
+      end
+
+      # Computes per-child rects for a vertical split.
+      def vertical_rects(rect)
+        sizes = child_sizes(axis: :vertical, available: rect.height)
+        top = rect.y
+
+        sizes.map do |height|
+          child_rect = Rect.new(x: rect.x, y: top, width: rect.width, height: height)
+          top += height + gap
+          child_rect
+        end
+      end
+
+      # Computes the size of each child along the *axis* given the *available* cells.
+      # Subtracts the total gap, allocates fixed sizes first, and distributes the remainder
+      # among flexible (non-fixed) children by their grow weights.
+      def child_sizes(axis:, available:)
+        gap_size = gap * [children.length - 1, 0].max
+        available_for_children = [available - gap_size, 0].max
+        fixed = children.map { |child| fixed_size(child, axis) }
+        flexible_indexes = fixed.each_index.select { |index| fixed[index].nil? }
+        sizes = fixed.map { |size| size&.to_i }
+        remaining = [available_for_children - sizes.compact.sum, 0].max
+
+        distribute_remaining(sizes, flexible_indexes, remaining)
+      end
+
+      # Returns the fixed size of *child* along *axis* (`:horizontal` reads width, `:vertical` reads height).
+      def fixed_size(child, axis)
+        (axis == :horizontal) ? child.width : child.height
+      end
+
+      # Distributes the *remaining* cells across *flexible_indexes* by grow weight, with the
+      # last flexible child absorbing any rounding remainder.
+      def distribute_remaining(sizes, flexible_indexes, remaining)
+        return sizes.map { |size| size || 0 } if flexible_indexes.empty?
+
+        total_grow = flexible_indexes.sum { |index| grow_weight(children[index]) }
+        used = 0
+
+        flexible_indexes.each_with_index do |index, flexible_index|
+          size = if flexible_index == flexible_indexes.length - 1
+            remaining - used
+          else
+            (remaining * grow_weight(children[index]) / total_grow).floor
+          end
+
+          sizes[index] = size
+          used += size
+        end
+
+        sizes
+      end
+
+      # Returns the grow weight of *child*, defaulting to 1 when unset.
+      def grow_weight(child)
+        [child.grow.to_i, 1].max
+      end
+    end
+  end
+end

data/lib/charming/presentation/layout.rb

@@ -1,43 +1,41 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    # Layout contains generic screen-size math and composition helpers. It is
-    # intentionally unaware of application shells such as sidebars or nav panes.
-    module Layout
-      module_function
+  # Layout contains generic screen-size math and composition helpers. It is
+  # intentionally unaware of application shells such as sidebars or nav panes.
+  module Layout
+    module_function
 
-      def clamp_size(value, min: nil, max: nil)
-        size = value.to_i
-        size = [size, min].max if min
-        size = [size, max].min if max
-        size
-      end
+    def clamp_size(value, min: nil, max: nil)
+      size = value.to_i
+      size = [size, min].max if min
+      size = [size, max].min if max
+      size
+    end
 
-      def available_width(screen, reserved: 0, min: nil, max: nil)
-        clamp_size(screen.width - reserved, min: min, max: max)
-      end
+    def available_width(screen, reserved: 0, min: nil, max: nil)
+      clamp_size(screen.width - reserved, min: min, max: max)
+    end
 
-      def available_height(screen, reserved: 0, min: nil, max: nil)
-        clamp_size(screen.height - reserved, min: min, max: max)
-      end
+    def available_height(screen, reserved: 0, min: nil, max: nil)
+      clamp_size(screen.height - reserved, min: min, max: max)
+    end
 
-      def stack_or_row(*blocks, narrow:, gap: 0)
-        if narrow
-          UI.join_vertical(*blocks, gap: gap)
-        else
-          UI.join_horizontal(*blocks, gap: gap)
-        end
+    def stack_or_row(*blocks, narrow:, gap: 0)
+      if narrow
+        UI.join_vertical(*blocks, gap: gap)
+      else
+        UI.join_horizontal(*blocks, gap: gap)
       end
+    end
 
-      def selected_window_start(selected_index:, item_count:, window_size:)
-        count = item_count.to_i
-        size = [window_size.to_i, 1].max
-        selected = selected_index.to_i.clamp(0, [count - 1, 0].max)
-        max_start = [count - size, 0].max
+    def selected_window_start(selected_index:, item_count:, window_size:)
+      count = item_count.to_i
+      size = [window_size.to_i, 1].max
+      selected = selected_index.to_i.clamp(0, [count - 1, 0].max)
+      max_start = [count - size, 0].max
 
-        (selected - size + 1).clamp(0, max_start)
-      end
+      (selected - size + 1).clamp(0, max_start)
     end
   end
 end