charming 0.1.1 → 0.1.2

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

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

data/lib/charming/presentation/markdown/block_renderers.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Markdown
+      # BlockRenderer dispatches Kramdown block-level elements (paragraph, header, list,
+      # code block, etc.) to their individual rendering handlers. Handlers are built once
+      # at construction time as a frozen hash of element-type symbols to callables.
+      class BlockRenderer
+        # *renderer* is the parent Renderer (used to wrap text, render inlines, and look up styles).
+        def initialize(renderer:)
+          @renderer = renderer
+          build_handlers
+        end
+
+        # Renders *element* using the handler registered for `element.type`. Unknown types
+        # fall through to `render_unknown`.
+        def render(element, context:)
+          handler = @handlers[element.type] || method(:render_unknown)
+          handler.call(element, context)
+        end
+
+        private
+
+        # The frozen hash of element-type → handler mapping.
+        attr_reader :handlers
+
+        # Builds the handler hash. Each handler is a small lambda that calls back into the
+        # parent renderer (or one of the private render_* methods below).
+        def build_handlers
+          r = @renderer
+          @handlers = {
+            p: ->(element, context) { r.wrap(r.render_inlines(element.children), width: context.width) },
+            header: ->(element, context) { send(:render_header, element, context) },
+            blockquote: ->(element, context) { send(:render_blockquote, element, context) },
+            ul: ->(element, context) { send(:render_list, element, ordered: false, context: context) },
+            ol: ->(element, context) { send(:render_list, element, ordered: true, context: context) },
+            li: ->(element, context) { r.render_blocks(element.children, list_depth: context.list_depth, width: context.width) },
+            codeblock: ->(element, _context) { send(:render_codeblock, element) },
+            hr: ->(element, context) { send(:render_rule, width: context.width) },
+            blank: ->(_element, _context) {}
+          }.freeze
+        end
+
+        # Fallback for unknown block types: wraps the raw value when there are no children,
+        # otherwise recurses into the children.
+        def render_unknown(element, context)
+          return @renderer.wrap(element.value.to_s, width: context.width) if element.children.empty?
+
+          @renderer.render_blocks(element.children, list_depth: context.list_depth, width: context.width)
+        end
+
+        # Renders a header element, using the `markdown_heading` style for h1 and the
+        # `markdown_subheading` style for h2+.
+        def render_header(element, context)
+          rendered = @renderer.wrap(@renderer.render_inlines(element.children), width: context.width)
+          style = if element.options[:level].to_i == 1
+            @renderer.style_for(:markdown_heading, fallback: @renderer.theme_style(:title))
+          else
+            @renderer.style_for(:markdown_subheading, fallback: @renderer.theme_style(:title))
+          end
+          style.render(rendered)
+        end
+
+        def render_blockquote(element, context)
+          quote_width = context.width ? [context.width - 2, 1].max : nil
+          rendered = @renderer.render_blocks(element.children, list_depth: context.list_depth, width: quote_width)
+          border = @renderer.style_for(:markdown_quote_border, fallback: @renderer.theme_style(:border)).render("|")
+          quote_style = @renderer.style_for(:markdown_quote, fallback: @renderer.theme_style(:muted))
+
+          rendered.lines(chomp: true).map { |line| "#{border} #{quote_style.render(line)}" }.join("\n")
+        end
+
+        def render_list(element, ordered:, context:)
+          element.children.each_with_index.map do |item, index|
+            marker = ordered ? "#{ordered_start(element) + index}." : "-"
+            render_list_item(item, marker: marker, context: context)
+          end.join("\n")
+        end
+
+        def render_list_item(element, marker:, context:)
+          indent = "  " * context.list_depth
+          first_prefix = "#{indent}#{marker} "
+          rest_prefix = "#{indent}#{" " * (marker.length + 1)}"
+          item_width = context.width ? [context.width - UI::Width.measure(first_prefix), 1].max : nil
+          body = @renderer.render_blocks(element.children, list_depth: context.list_depth + 1, width: item_width)
+
+          body.lines(chomp: true).each_with_index.map do |line, index|
+            "#{index.zero? ? first_prefix : rest_prefix}#{line}"
+          end.join("\n")
+        end
+
+        def ordered_start(element)
+          element.options.fetch(:start, 1).to_i
+        end
+
+        def render_codeblock(element)
+          code = element.value.to_s
+          rendered = if @renderer.syntax_highlighting
+            SyntaxHighlighter.new(theme: @renderer.theme).render(code, language: code_language(element))
+          else
+            @renderer.style_for(:markdown_code, fallback: @renderer.theme_style(:warn)).render(code)
+          end
+
+          rendered.lines(chomp: true).map { |line| "  #{line}" }.join("\n")
+        end
+
+        def render_rule(width:)
+          @renderer.style_for(:markdown_rule, fallback: @renderer.theme_style(:border)).render("-" * (width || Renderer::DEFAULT_RULE_WIDTH))
+        end
+
+        def code_language(element)
+          return element.options[:lang] if element.options[:lang]
+
+          element.attr["class"].to_s[/language-([^\s]+)/, 1]
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/markdown/inline_renderers.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Markdown
+      # InlineRenderer dispatches Kramdown inline-level elements (text, strong, em,
+      # codespan, link, line break, HTML entity) to their individual rendering handlers.
+      # Handlers are built once at construction as a frozen hash of element-type symbols
+      # to callables.
+      class InlineRenderer
+        # *renderer* is the parent Renderer (used to render nested inlines and look up styles).
+        def initialize(renderer:)
+          @renderer = renderer
+          build_handlers
+        end
+
+        # Renders *element* using the handler registered for `element.type`. Unknown types
+        # fall through to `render_unknown`.
+        def render(element, context:)
+          handler = @handlers[element.type] || method(:render_unknown)
+          handler.call(element, context)
+        end
+
+        private
+
+        # The frozen hash of element-type → handler mapping.
+        attr_reader :handlers
+
+        # Builds the handler hash for text, strong, em, codespan, link, br, and entity.
+        def build_handlers
+          r = @renderer
+          @handlers = {
+            text: ->(element, _context) { element.value.to_s },
+            strong: ->(element, context) { render_styled(element, context, :markdown_strong) { |s| s.bold } },
+            em: ->(element, context) { render_styled(element, context, :markdown_emphasis) { |s| s.italic } },
+            codespan: ->(element, _context) { r.style_for(:markdown_inline_code, fallback: r.theme_style(:warn)).render(element.value.to_s) },
+            a: ->(element, context) { send(:render_link, element, context) },
+            br: ->(_element, _context) { "\n" },
+            entity: ->(element, _context) { element.value.respond_to?(:char) ? element.value.char : element.value.to_s }
+          }.freeze
+        end
+
+        # Renders a styled inline (strong/em) by first rendering children, then applying
+        # the theme style and the block-form (e.g., `bold`/`italic`) decoration.
+        def render_styled(element, context, style_name)
+          rendered = @renderer.render_inlines(element.children, width: context.width)
+          style = @renderer.style_for(style_name, fallback: yield(@renderer.theme_style(:text)))
+          style.render(rendered)
+        end
+
+        # Renders a Markdown link as "label <href>" (URL omitted when empty), styled with
+        # the markdown_link theme token or the info+underline fallback.
+        def render_link(element, context)
+          label = @renderer.render_inlines(element.children, width: context.width)
+          href = element.attr["href"].to_s
+          rendered = href.empty? ? label : "#{label} <#{href}>"
+          @renderer.style_for(:markdown_link, fallback: @renderer.theme_style(:info).underline).render(rendered)
+        end
+
+        # Fallback for unknown inline types: returns the value when there are no children,
+        # otherwise recurses into the children.
+        def render_unknown(element, context)
+          element.children.empty? ? element.value.to_s : @renderer.render_inlines(element.children, width: context.width)
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/markdown/render_context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    module Markdown
+      # RenderContext carries the state needed to render nested Markdown blocks: the current
+      # list nesting depth (used for indentation) and the wrap width.
+      RenderContext = Data.define(:list_depth, :width) do
+        # Builds a new RenderContext with the given *width* and optional starting *list_depth*.
+        def self.from(width:, list_depth: 0)
+          new(list_depth: list_depth, width: width)
+        end
+
+        # Returns a derived context with the list depth incremented by *depth_increment*
+        # and the wrap width overridden to *width* (defaults to the current width).
+        def nested(depth_increment: 0, width: self.width)
+          self.class.new(list_depth: list_depth + depth_increment, width: width)
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/markdown/renderer.rb

@@ -5,9 +5,20 @@ require "kramdown"
 module Charming
   module Presentation
     module Markdown
+      # Renderer is the top-level Markdown-to-ANSI renderer. Parses the *content* with
+      # Kramdown, then walks the document's block and inline trees to produce styled
+      # terminal output. Code blocks are highlighted via Rouge when `syntax_highlighting`
+      # is enabled.
       class Renderer
+        # Wrap width used by `render_rule` when no width is otherwise specified.
         DEFAULT_RULE_WIDTH = 40
 
+        # The Markdown source, configured wrap width, theme, and syntax-highlighting flag.
+        attr_reader :content, :width, :theme, :syntax_highlighting
+
+        # *content* is the Markdown source string. *width* optionally wraps paragraphs to that
+        # many display columns. *theme* is the Charming theme used to style blocks/inlines.
+        # *syntax_highlighting* enables Rouge-backed code block highlighting (default true).
         def initialize(content:, width: nil, theme: UI::Theme.default, syntax_highlighting: true)
           @content = content
           @width = width
@@ -15,156 +26,67 @@ module Charming
           @syntax_highlighting = syntax_highlighting
         end
 
+        # Parses the content and returns the fully-rendered Markdown as a single string.
         def render
           document = Kramdown::Document.new(content.to_s)
           render_blocks(document.root.children)
         end
 
-        private
-
-        attr_reader :content, :width, :theme
-
+        # Renders a list of Kramdown block *elements* into a string, joined by blank lines.
+        # *list_depth* is forwarded to the render context for list indentation. *width*
+        # defaults to the renderer's configured width.
         def render_blocks(elements, list_depth: 0, width: @width)
+          context = RenderContext.from(width: width, list_depth: list_depth)
           elements.filter_map do |element|
-            rendered = render_block(element, list_depth: list_depth, width: width)
+            rendered = block_renderer.render(element, context: context)
             rendered unless rendered.to_s.empty?
           end.join("\n\n")
         end
 
-        def render_block(element, list_depth: 0, width: @width)
-          case element.type
-          when :p
-            wrap(render_inlines(element.children), width: width)
-          when :header
-            render_header(element, width: width)
-          when :blockquote
-            render_blockquote(element, list_depth: list_depth, width: width)
-          when :ul
-            render_list(element, ordered: false, list_depth: list_depth, width: width)
-          when :ol
-            render_list(element, ordered: true, list_depth: list_depth, width: width)
-          when :li
-            render_blocks(element.children, list_depth: list_depth, width: width)
-          when :codeblock
-            render_codeblock(element)
-          when :hr
-            render_rule(width: width)
-          when :blank
-            nil
-          else
-            render_unknown(element, list_depth: list_depth, width: width)
-          end
-        end
-
-        def render_unknown(element, list_depth:, width:)
-          return wrap(element.value.to_s, width: width) if element.children.empty?
-
-          render_blocks(element.children, list_depth: list_depth, width: width)
-        end
-
-        def render_header(element, width:)
-          rendered = wrap(render_inlines(element.children), width: width)
-          style = if element.options[:level].to_i == 1
-            style_for(:markdown_heading, fallback: theme_style(:title))
-          else
-            style_for(:markdown_subheading, fallback: theme_style(:title))
-          end
-          style.render(rendered)
-        end
-
-        def render_blockquote(element, list_depth:, width:)
-          quote_width = width ? [width - 2, 1].max : nil
-          rendered = render_blocks(element.children, list_depth: list_depth, width: quote_width)
-          border = style_for(:markdown_quote_border, fallback: theme_style(:border)).render("|")
-          quote_style = style_for(:markdown_quote, fallback: theme_style(:muted))
-
-          rendered.lines(chomp: true).map do |line|
-            "#{border} #{quote_style.render(line)}"
-          end.join("\n")
-        end
-
-        def render_list(element, ordered:, list_depth:, width:)
-          element.children.each_with_index.map do |item, index|
-            marker = ordered ? "#{ordered_start(element) + index}." : "-"
-            render_list_item(item, marker: marker, list_depth: list_depth, width: width)
-          end.join("\n")
+        # Renders a list of Kramdown inline *elements* into a single concatenated string.
+        # *width* defaults to the renderer's configured width.
+        def render_inlines(elements, width: @width)
+          context = RenderContext.from(width: width)
+          elements.map { |element| inline_renderer.render(element, context: context) }.join
         end
 
-        def render_list_item(element, marker:, list_depth:, width:)
-          indent = "  " * list_depth
-          first_prefix = "#{indent}#{marker} "
-          rest_prefix = "#{indent}#{" " * (marker.length + 1)}"
-          item_width = width ? [width - UI::Width.measure(first_prefix), 1].max : nil
-          body = render_blocks(element.children, list_depth: list_depth + 1, width: item_width)
-
-          body.lines(chomp: true).each_with_index.map do |line, index|
-            "#{index.zero? ? first_prefix : rest_prefix}#{line}"
-          end.join("\n")
-        end
-
-        def ordered_start(element)
-          element.options.fetch(:start, 1).to_i
-        end
-
-        def render_codeblock(element)
-          code = element.value.to_s
-          rendered = if @syntax_highlighting
-            SyntaxHighlighter.new(theme: theme).render(code, language: code_language(element))
-          else
-            style_for(:markdown_code, fallback: theme_style(:warn)).render(code)
-          end
+        # Word-wraps *value* to *width* display columns (when *width* is given), preserving
+        # any ANSI styling on each line. Returns *value* unchanged when *width* is nil.
+        def wrap(value, width:)
+          return value unless width
 
-          rendered.lines(chomp: true).map { |line| "  #{line}" }.join("\n")
+          value.to_s.lines(chomp: true).map { |line| wrap_line(line, width) }.join("\n")
         end
 
-        def render_rule(width:)
-          style_for(:markdown_rule, fallback: theme_style(:border)).render("-" * (width || DEFAULT_RULE_WIDTH))
-        end
+        # Returns the theme's style for *name* if the theme defines it, otherwise returns
+        # *fallback*. Lets views override markdown-specific theme tokens.
+        def style_for(name, fallback:)
+          return theme.public_send(name) if theme.respond_to?(name)
 
-        def render_inlines(elements)
-          elements.map { |element| render_inline(element) }.join
+          fallback
         end
 
-        def render_inline(element)
-          case element.type
-          when :text
-            element.value.to_s
-          when :strong
-            style_for(:markdown_strong, fallback: theme_style(:text).bold).render(render_inlines(element.children))
-          when :em
-            style_for(:markdown_emphasis, fallback: theme_style(:text).italic).render(render_inlines(element.children))
-          when :codespan
-            style_for(:markdown_inline_code, fallback: theme_style(:warn)).render(element.value.to_s)
-          when :a
-            render_link(element)
-          when :br
-            "\n"
-          when :entity
-            element.value.respond_to?(:char) ? element.value.char : element.value.to_s
-          else
-            element.children.empty? ? element.value.to_s : render_inlines(element.children)
-          end
-        end
+        # Returns the theme's style for *name*, building a one-token default theme when
+        # the active theme doesn't define it. Used as a final fallback for markdown styling.
+        def theme_style(name)
+          return theme.public_send(name) if theme.respond_to?(name)
 
-        def render_link(element)
-          label = render_inlines(element.children)
-          href = element.attr["href"].to_s
-          rendered = href.empty? ? label : "#{label} <#{href}>"
-          style_for(:markdown_link, fallback: theme_style(:info).underline).render(rendered)
+          UI::Theme::DEFAULT_TOKENS.fetch(name).then { |token| UI::Theme.new(name => token).public_send(name) }
         end
 
-        def code_language(element)
-          return element.options[:lang] if element.options[:lang]
+        private
 
-          element.attr["class"].to_s[/language-([^\s]+)/, 1]
+        # The BlockRenderer instance, lazily built.
+        def block_renderer
+          @block_renderer ||= BlockRenderer.new(renderer: self)
         end
 
-        def wrap(value, width:)
-          return value unless width
-
-          value.to_s.lines(chomp: true).map { |line| wrap_line(line, width) }.join("\n")
+        # The InlineRenderer instance, lazily built.
+        def inline_renderer
+          @inline_renderer ||= InlineRenderer.new(renderer: self)
         end
 
+        # Word-wraps a single *line* to *width* display columns using greedy space-splitting.
         def wrap_line(line, width)
           return line if UI::Width.measure(line) <= width
 
@@ -185,18 +107,6 @@ module Charming
           lines << current.rstrip unless current.empty?
           lines.join("\n")
         end
-
-        def style_for(name, fallback:)
-          return theme.public_send(name) if theme.respond_to?(name)
-
-          fallback
-        end
-
-        def theme_style(name)
-          return theme.public_send(name) if theme.respond_to?(name)
-
-          UI::Theme::DEFAULT_TOKENS.fetch(name).then { |token| UI::Theme.new(name => token).public_send(name) }
-        end
       end
     end
   end

data/lib/charming/presentation/markdown/syntax_highlighter.rb

@@ -5,11 +5,19 @@ require "rouge"
 module Charming
   module Presentation
     module Markdown
+      # SyntaxHighlighter turns a code block string into ANSI-styled terminal text using
+      # Rouge lexers. The theme provides markdown_code_* tokens for per-token styling;
+      # when a token is undefined in the theme, the highlighter falls back to a sensible
+      # base style (muted italic for comments, title for keywords, etc.).
       class SyntaxHighlighter
+        # *theme* is the active Charming theme. Defaults to UI::Theme.default.
         def initialize(theme: UI::Theme.default)
           @theme = theme || UI::Theme.default
         end
 
+        # Highlights *code* (using Rouge) for the given *language* (auto-detected when nil)
+        # and returns a styled multi-line string. Each Rouge token is rendered with the
+        # theme style matching its token type.
         def render(code, language: nil)
           lexer = lexer_for(language, code)
           lexer.lex(code.to_s).map do |token, value|
@@ -19,12 +27,16 @@ module Charming
 
         private
 
+        # The Charming theme used for token styling.
         attr_reader :theme
 
+        # Picks a Rouge lexer for *language* and *code*, falling back to plain text.
         def lexer_for(language, code)
           Rouge::Lexer.find_fancy(language, code) || Rouge::Lexers::PlainText
         end
 
+        # Returns the Charming style for a given Rouge *token*, mapping token qualifiers
+        # to theme tokens and falling back to a sensible base style per category.
         def style_for(token)
           name = token_name(token)
 
@@ -46,12 +58,16 @@ module Charming
           end
         end
 
+        # Returns the qualified token name when the token object supports it, otherwise
+        # the token's default `to_s`.
         def token_name(token)
           return token.qualname if token.respond_to?(:qualname)
 
           token.to_s
         end
 
+        # Returns the theme's style for *name*, falling back to *fallback* (or a default
+        # empty style) when the theme doesn't define it.
         def theme_style(name, fallback: nil)
           return theme.public_send(name) if theme.respond_to?(name)
 

data/lib/charming/presentation/markdown.rb

@@ -2,6 +2,9 @@
 
 module Charming
   module Presentation
+    # Markdown is the namespace for the Markdown rendering pipeline. Parsing is delegated to
+    # Kramdown; per-block and per-inline element rendering is handled by `BlockRenderer`
+    # and `InlineRenderer`; code blocks are highlighted by `SyntaxHighlighter` (Rouge-backed).
     module Markdown
     end
   end

data/lib/charming/presentation/template_view.rb

@@ -2,6 +2,9 @@
 
 module Charming
   module Presentation
+    # TemplateView wraps a resolved ERB template and exposes it as a renderable View. The
+    # template is rendered with the view's helpers (`text`, `box`, `row`, `column`, `style`,
+    # `theme`, etc.) and the view's assigns available as reader methods inside the template.
     class TemplateView < View
       def initialize(template:, namespace: nil, **assigns)
         super(**assigns)
@@ -9,10 +12,14 @@ module Charming
         @namespace = namespace
       end
 
+      # Renders the wrapped template to a string, evaluated in the view's binding context.
       def render
         template.render(self).to_s
       end
 
+      # Returns the binding used by ERB handlers to evaluate the template body. When *namespace*
+      # is set, the binding is created by a proc generated in the namespace's context so the
+      # template can resolve constants relative to the application.
       def template_binding
         return binding unless namespace