charming 0.1.1 → 0.1.3

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

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

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

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

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

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

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

@@ -3,200 +3,108 @@
 require "kramdown"
 
 module Charming
-  module Presentation
-    module Markdown
-      class Renderer
-        DEFAULT_RULE_WIDTH = 40
-
-        def initialize(content:, width: nil, theme: UI::Theme.default, syntax_highlighting: true)
-          @content = content
-          @width = width
-          @theme = theme || UI::Theme.default
-          @syntax_highlighting = syntax_highlighting
-        end
-
-        def render
-          document = Kramdown::Document.new(content.to_s)
-          render_blocks(document.root.children)
-        end
-
-        private
-
-        attr_reader :content, :width, :theme
+  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
+        @theme = theme || UI::Theme.default
+        @syntax_highlighting = syntax_highlighting
+      end
 
-        def render_blocks(elements, list_depth: 0, width: @width)
-          elements.filter_map do |element|
-            rendered = render_block(element, list_depth: list_depth, width: width)
-            rendered unless rendered.to_s.empty?
-          end.join("\n\n")
-        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
 
-        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
+      # 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 = block_renderer.render(element, context: context)
+          rendered unless rendered.to_s.empty?
+        end.join("\n\n")
+      end
 
-        def render_unknown(element, list_depth:, width:)
-          return wrap(element.value.to_s, width: width) if element.children.empty?
+      # 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
 
-          render_blocks(element.children, list_depth: list_depth, width: width)
-        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
 
-        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
+        value.to_s.lines(chomp: true).map { |line| wrap_line(line, width) }.join("\n")
+      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))
+      # 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)
 
-          rendered.lines(chomp: true).map do |line|
-            "#{border} #{quote_style.render(line)}"
-          end.join("\n")
-        end
+        fallback
+      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")
-        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_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)
+        UI::Theme::DEFAULT_TOKENS.fetch(name).then { |token| UI::Theme.new(name => token).public_send(name) }
+      end
 
-          body.lines(chomp: true).each_with_index.map do |line, index|
-            "#{index.zero? ? first_prefix : rest_prefix}#{line}"
-          end.join("\n")
-        end
+      private
 
-        def ordered_start(element)
-          element.options.fetch(:start, 1).to_i
-        end
+      # The BlockRenderer instance, lazily built.
+      def block_renderer
+        @block_renderer ||= BlockRenderer.new(renderer: self)
+      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
+      # The InlineRenderer instance, lazily built.
+      def inline_renderer
+        @inline_renderer ||= InlineRenderer.new(renderer: self)
+      end
 
-          rendered.lines(chomp: true).map { |line| "  #{line}" }.join("\n")
-        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
 
-        def render_rule(width:)
-          style_for(:markdown_rule, fallback: theme_style(:border)).render("-" * (width || DEFAULT_RULE_WIDTH))
-        end
+        lines = []
+        current = +""
 
-        def render_inlines(elements)
-          elements.map { |element| render_inline(element) }.join
-        end
+        line.split(/\s+/).each do |word|
+          candidate = current.empty? ? word : "#{current} #{word}"
 
-        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
+          if !current.empty? && UI::Width.measure(candidate) > width
+            lines << current.rstrip
+            current = word
           else
-            element.children.empty? ? element.value.to_s : render_inlines(element.children)
+            current = candidate
           end
         end
 
-        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)
-        end
-
-        def code_language(element)
-          return element.options[:lang] if element.options[:lang]
-
-          element.attr["class"].to_s[/language-([^\s]+)/, 1]
-        end
-
-        def wrap(value, width:)
-          return value unless width
-
-          value.to_s.lines(chomp: true).map { |line| wrap_line(line, width) }.join("\n")
-        end
-
-        def wrap_line(line, width)
-          return line if UI::Width.measure(line) <= width
-
-          lines = []
-          current = +""
-
-          line.split(/\s+/).each do |word|
-            candidate = current.empty? ? word : "#{current} #{word}"
-
-            if !current.empty? && UI::Width.measure(candidate) > width
-              lines << current.rstrip
-              current = word
-            else
-              current = candidate
-            end
-          end
-
-          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
+        lines << current.rstrip unless current.empty?
+        lines.join("\n")
       end
     end
   end

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

@@ -3,60 +3,74 @@
 require "rouge"
 
 module Charming
-  module Presentation
-    module Markdown
-      class SyntaxHighlighter
-        def initialize(theme: UI::Theme.default)
-          @theme = theme || UI::Theme.default
-        end
+  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
 
-        def render(code, language: nil)
-          lexer = lexer_for(language, code)
-          lexer.lex(code.to_s).map do |token, value|
-            style_for(token).render(value)
-          end.join
-        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|
+          style_for(token).render(value)
+        end.join
+      end
 
-        private
+      private
 
-        attr_reader :theme
+      # The Charming theme used for token styling.
+      attr_reader :theme
 
-        def lexer_for(language, code)
-          Rouge::Lexer.find_fancy(language, code) || Rouge::Lexers::PlainText
-        end
+      # 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
 
-        def style_for(token)
-          name = token_name(token)
-
-          case name
-          when /Comment/
-            theme_style(:markdown_code_comment, fallback: theme_style(:muted).italic)
-          when /Keyword/
-            theme_style(:markdown_code_keyword, fallback: theme_style(:title))
-          when /String/
-            theme_style(:markdown_code_string, fallback: theme_style(:warn))
-          when /Number|Literal/
-            theme_style(:markdown_code_literal, fallback: theme_style(:info))
-          when /Name\.(Class|Constant|Function|Namespace)/
-            theme_style(:markdown_code_constant, fallback: theme_style(:info))
-          when /Error/
-            theme_style(:markdown_code_error, fallback: theme_style(:warn).bold)
-          else
-            theme_style(:markdown_code, fallback: theme_style(:text))
-          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)
+
+        case name
+        when /Comment/
+          theme_style(:markdown_code_comment, fallback: theme_style(:muted).italic)
+        when /Keyword/
+          theme_style(:markdown_code_keyword, fallback: theme_style(:title))
+        when /String/
+          theme_style(:markdown_code_string, fallback: theme_style(:warn))
+        when /Number|Literal/
+          theme_style(:markdown_code_literal, fallback: theme_style(:info))
+        when /Name\.(Class|Constant|Function|Namespace)/
+          theme_style(:markdown_code_constant, fallback: theme_style(:info))
+        when /Error/
+          theme_style(:markdown_code_error, fallback: theme_style(:warn).bold)
+        else
+          theme_style(:markdown_code, fallback: theme_style(:text))
         end
+      end
 
-        def token_name(token)
-          return token.qualname if token.respond_to?(:qualname)
+      # 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
+        token.to_s
+      end
 
-        def theme_style(name, fallback: nil)
-          return theme.public_send(name) if theme.respond_to?(name)
+      # 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)
 
-          fallback || UI.style
-        end
+        fallback || UI.style
       end
     end
   end

data/lib/charming/presentation/markdown.rb

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