charming 0.2.0 → 0.2.1

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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "commonmarker"
-require "uri"
 
 module Charming
   module Markdown
@@ -9,15 +8,19 @@ module Charming
     class Renderer
       DEFAULT_RULE_WIDTH = 40
 
-      attr_reader :content, :width, :theme, :syntax_highlighting, :style, :base_url
+      attr_reader :content, :width, :theme, :syntax_highlighting, :style, :base_url, :hyperlinks
 
-      def initialize(content:, width: nil, theme: UI::Theme.default, syntax_highlighting: true, style: :dark, base_url: nil)
+      # *hyperlinks* (default false) wraps links in OSC 8 escape sequences so modern
+      # terminals make them clickable; the ` <url>` suffix is omitted since the target
+      # is embedded in the escape.
+      def initialize(content:, width: nil, theme: UI::Theme.default, syntax_highlighting: true, style: :dark, base_url: nil, hyperlinks: false)
         @content = content
         @width = width
         @theme = theme || UI::Theme.default
         @syntax_highlighting = syntax_highlighting
         @style = StyleConfig.from(style)
         @base_url = base_url
+        @hyperlinks = hyperlinks
       end
 
       def render
@@ -42,9 +45,7 @@ module Charming
       end
 
       def wrap(value, width:)
-        return value unless width
-
-        value.to_s.lines(chomp: true).map { |line| wrap_line(line, width) }.join("\n")
+        TextWrapper.new(width: width).wrap(value)
       end
 
       def style_for(name, fallback:)
@@ -99,6 +100,10 @@ module Charming
           render_rule(context: context)
         when :table
           render_table(node, context: context)
+        when :description_list
+          render_definition_list(node, context: context)
+        when :footnote_definition
+          render_footnote_definition(node, context: context)
         when :html_block
           render_html_block(node, context: context)
         else
@@ -126,6 +131,8 @@ module Charming
           render_link(node, context: context)
         when :image
           render_image(node, context: context)
+        when :footnote_reference
+          render_footnote_reference(node, context: context)
         when :html_inline
           ""
         else
@@ -185,9 +192,15 @@ module Charming
         checked_task?(node, context: context) ? (task_style.ticked || "[x] ") : (task_style.unticked || "[ ] ")
       end
 
+      # Matches a checked task marker anchored to the list-item prefix, so prose that
+      # merely mentions "[x]" can't check the box.
+      TASK_CHECKED_PATTERN = /\A\s*(?:[-*+]|\d+[.)])\s+\[[xX]\]/
+
+      # Commonmarker exposes no checked-state accessor on taskitem nodes, so the
+      # original source line is inspected instead.
       def checked_task?(node, context:)
         line = context.source_lines[node.source_position[:start_line].to_i - 1].to_s
-        line.match?(/\[[xX]\]/)
+        line.match?(TASK_CHECKED_PATTERN)
       end
 
       def render_code_block(node, context:)
@@ -205,7 +218,10 @@ module Charming
 
       def render_rule(context:)
         rule_style = context.current_style.inherit_visual(context.style[:hr])
-        body = rule_style.format.empty? ? "-" * (context.width || DEFAULT_RULE_WIDTH) : rule_style.format
+        available_width = context.width || DEFAULT_RULE_WIDTH
+        padding = rule_style.indent.to_i * 2
+        rule_width = [available_width - padding, 1].max
+        body = repeat_to_width(rule_style.format.empty? ? "-" : rule_style.format, rule_width)
         render_block_with_style(rule_style, body)
       end
 
@@ -214,15 +230,70 @@ module Charming
         rows = children_of(node).map do |row|
           children_of(row).map { |cell| render_inlines(children_of(cell), context: context.with(current_style: table_style)) }
         end
-        return "" if rows.empty?
 
-        widths = table_widths(rows)
-        rendered_rows = rows.each_with_index.map do |row, index|
-          line = table_row(row, widths, table_style)
-          index.zero? ? [line, table_separator(widths, table_style)].join("\n") : line
+        body = TableRenderer.new(rows: rows, style: table_style).render
+        return "" if body.empty?
+
+        render_block_with_style(table_style, body)
+      end
+
+      # Renders `Term / : definition` description lists: terms in the definition_term
+      # style, details indented per the definition_description style.
+      def render_definition_list(node, context:)
+        children_of(node).map { |item| render_definition_item(item, context: context) }.join("\n")
+      end
+
+      def render_definition_item(node, context:)
+        parts = children_of(node).map do |child|
+          case child.type
+          when :description_term
+            render_definition_term(child, context: context)
+          when :description_details
+            render_definition_details(child, context: context)
+          else
+            render_block(child, context: context)
+          end
         end
+        parts.reject { |part| part.to_s.empty? }.join("\n")
+      end
 
-        render_block_with_style(table_style, rendered_rows.join("\n"))
+      def render_definition_term(node, context:)
+        term_style = context.current_style.inherit_visual(context.style[:definition_term])
+        term_style.render(render_inlines(children_of(node), context: context.with(current_style: term_style)))
+      end
+
+      def render_definition_details(node, context:)
+        details_style = context.current_style.inherit_visual(context.style[:definition_description])
+        indent = " " * (details_style.indent || 4)
+        details_width = context.width ? [context.width - indent.length, 1].max : nil
+        body = render_blocks(children_of(node), context: context.with(width: details_width, current_style: details_style))
+        body.lines(chomp: true).map { |line| "#{indent}#{line}" }.join("\n")
+      end
+
+      # Renders an inline `[^name]` reference as a bracketed label in the link style.
+      def render_footnote_reference(node, context:)
+        context.inherit(:link).render("[#{footnote_name(node)}]")
+      end
+
+      # Renders a footnote definition as a labeled block with hanging indentation.
+      def render_footnote_definition(node, context:)
+        label_style = context.current_style.inherit_visual(context.style[:link_text])
+        label = "[#{footnote_name(node)}]: "
+        indent = " " * UI::Width.measure(label)
+        body_width = context.width ? [context.width - UI::Width.measure(label), 1].max : nil
+        body = render_blocks(children_of(node), context: context.with(width: body_width))
+        lines = body.lines(chomp: true)
+        return label_style.render(label.rstrip) if lines.empty?
+
+        first = "#{label_style.render(label)}#{lines.first}"
+        rest = lines.drop(1).map { |line| "#{indent}#{line}" }
+        [first, *rest].join("\n")
+      end
+
+      # Commonmarker exposes no name accessor on footnote nodes; the round-tripped
+      # commonmark source (`"[^name]\n"` / `"[^name]:\n..."`) carries the label.
+      def footnote_name(node)
+        node.to_commonmark[/\A\[\^(.+?)\]/, 1].to_s
       end
 
       def render_html_block(_node, context:)
@@ -242,6 +313,8 @@ module Charming
         text_style = context.inherit(:link_text)
         link_style = context.inherit(:link)
         label = render_inlines(children_of(node), context: context.with(current_style: text_style))
+        return osc8_hyperlink(href, link_style.render(label)) if hyperlinks && !href.empty?
+
         rendered = if href.empty? || UI::Width.strip_ansi(label) == href
           label
         else
@@ -250,6 +323,12 @@ module Charming
         link_style.render(rendered)
       end
 
+      # Wraps *rendered* in an OSC 8 hyperlink to *href*. Modern terminals make the
+      # text clickable; the sequence is invisible to width math (UI::Width strips OSC).
+      def osc8_hyperlink(href, rendered)
+        "\e]8;;#{href}\e\\#{rendered}\e]8;;\e\\"
+      end
+
       def render_image(node, context:)
         href = resolve_url(node.url.to_s, context: context)
         image_style = context.inherit(:image)
@@ -268,26 +347,11 @@ module Charming
         style.render(style.apply_block_layout(body))
       end
 
-      def table_widths(rows)
-        column_count = rows.map(&:length).max || 0
-        Array.new(column_count) do |index|
-          rows.map { |row| UI::Width.measure(row[index].to_s) }.max || 0
-        end
-      end
-
-      def table_row(row, widths, style)
-        separator = style.column_separator || "|"
-        cells = widths.each_with_index.map do |width, index|
-          value = row[index].to_s
-          " #{value}#{" " * [width - UI::Width.measure(value), 0].max} "
-        end
-        "#{separator}#{cells.join(separator)}#{separator}"
-      end
-
-      def table_separator(widths, style)
-        separator = style.column_separator || "|"
-        row = style.row_separator || "-"
-        "#{separator}#{widths.map { |table_width| row * (table_width + 2) }.join(separator)}#{separator}"
+      def repeat_to_width(value, width)
+        token = value.to_s
+        token_width = [UI::Width.measure(token), 1].max
+        repeated = token * ((width.to_i + token_width - 1) / token_width)
+        UI.visible_slice(repeated, 0, width)
       end
 
       def quote_indent_width(style)
@@ -297,40 +361,12 @@ module Charming
       end
 
       def resolve_url(value, context:)
-        return value if context.base_url.to_s.empty? || value.empty?
-
-        uri = URI.parse(value)
-        return value if uri.absolute?
-
-        URI.join(context.base_url, value).to_s
-      rescue URI::InvalidURIError
-        value
+        URLResolver.new(base_url: context.base_url).resolve(value)
       end
 
       def children_of(node)
         node.each.to_a
       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
     end
   end
 end

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

@@ -23,13 +23,14 @@ module Charming
           emph: {block_prefix: "*", block_suffix: "*"},
           strong: {block_prefix: "**", block_suffix: "**"},
           strikethrough: {block_prefix: "~~", block_suffix: "~~"},
-          hr: {format: "--------"},
+          hr: {format: "-", indent: 2, margin: 1},
           item: {block_prefix: "- "},
           enumeration: {block_prefix: ". "},
           task: {ticked: "[x] ", unticked: "[ ] "},
           code: {block_prefix: "`", block_suffix: "`"},
           code_block: {margin: 1},
           table: {column_separator: "|", row_separator: "-"},
+          definition_description: {indent: 4},
           image_text: {format: "Image: {{text}} ->"}
         },
         dark: {
@@ -46,7 +47,7 @@ module Charming
           strikethrough: {crossed_out: true},
           emph: {italic: true},
           strong: {bold: true},
-          hr: {color: "240", format: "--------"},
+          hr: {color: "240", format: "─", indent: 2, margin: 1},
           item: {block_prefix: "• "},
           enumeration: {block_prefix: ". "},
           task: {ticked: "[✓] ", unticked: "[ ] "},
@@ -56,7 +57,9 @@ module Charming
           image_text: {color: "243", format: "Image: {{text}} ->"},
           code: {prefix: " ", suffix: " ", color: "203", background_color: "236"},
           code_block: {color: "244", margin: 1},
-          table: {column_separator: "|", row_separator: "-"}
+          table: {column_separator: "|", row_separator: "-"},
+          definition_term: {bold: true},
+          definition_description: {indent: 4, color: "244"}
         },
         light: {
           document: {color: "236"},
@@ -72,7 +75,7 @@ module Charming
           strikethrough: {crossed_out: true},
           emph: {italic: true},
           strong: {bold: true},
-          hr: {color: "250", format: "--------"},
+          hr: {color: "250", format: "─", indent: 2, margin: 1},
           item: {block_prefix: "• "},
           enumeration: {block_prefix: ". "},
           task: {ticked: "[✓] ", unticked: "[ ] "},
@@ -82,7 +85,9 @@ module Charming
           image_text: {color: "244", format: "Image: {{text}} ->"},
           code: {prefix: " ", suffix: " ", color: "161", background_color: "255"},
           code_block: {color: "244", margin: 1},
-          table: {column_separator: "|", row_separator: "-"}
+          table: {column_separator: "|", row_separator: "-"},
+          definition_term: {bold: true},
+          definition_description: {indent: 4, color: "244"}
         }
       }.freeze
 

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

@@ -21,7 +21,7 @@ module Charming
       def render(code, language: nil)
         lexer = lexer_for(language, code)
         lexer.lex(code.to_s).map do |token, value|
-          style_for(token).render(value)
+          render_token(token, value)
         end.join
       end
 
@@ -30,6 +30,16 @@ module Charming
       # The Charming theme used for token styling.
       attr_reader :theme, :style
 
+      def render_token(token, value)
+        token_style = style_for(token)
+        value.to_s.each_line(chomp: false).map do |line|
+          next "\n" if line == "\n"
+          next token_style.render(line.chomp("\n")) + "\n" if line.end_with?("\n")
+
+          token_style.render(line)
+        end.join
+      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

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Charming
+  module Markdown
+    # TableRenderer formats parsed Markdown table rows for terminal display.
+    class TableRenderer
+      def initialize(rows:, style:)
+        @rows = rows
+        @style = style
+      end
+
+      def render
+        return "" if rows.empty?
+
+        rows.each_with_index.map { |row, index| render_row(row, index) }.join("\n")
+      end
+
+      private
+
+      attr_reader :rows, :style
+
+      def render_row(row, index)
+        line = table_row(row)
+        index.zero? ? [line, table_separator].join("\n") : line
+      end
+
+      def table_row(row)
+        cells = widths.each_with_index.map { |width, index| table_cell(row, width, index) }
+        "#{separator}#{cells.join(separator)}#{separator}"
+      end
+
+      def table_cell(row, width, index)
+        value = row[index].to_s
+        " #{value}#{" " * [width - UI::Width.measure(value), 0].max} "
+      end
+
+      def table_separator
+        "#{separator}#{widths.map { |table_width| row_separator * (table_width + 2) }.join(separator)}#{separator}"
+      end
+
+      def widths
+        @widths ||= Array.new(column_count) do |index|
+          rows.map { |row| UI::Width.measure(row[index].to_s) }.max || 0
+        end
+      end
+
+      def column_count
+        rows.map(&:length).max || 0
+      end
+
+      def separator
+        style.column_separator || "|"
+      end
+
+      def row_separator
+        style.row_separator || "-"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Charming
+  module Markdown
+    # TextWrapper wraps Markdown text blocks to a configured terminal width.
+    class TextWrapper
+      def initialize(width:)
+        @width = width
+      end
+
+      def wrap(value)
+        return value unless width
+
+        value.to_s.lines(chomp: true).map { |line| wrap_line(line) }.join("\n")
+      end
+
+      private
+
+      attr_reader :width
+
+      def wrap_line(line)
+        return line if UI::Width.measure(line) <= width
+
+        wrap_words(line.split(/\s+/))
+      end
+
+      def wrap_words(words)
+        words.each_with_object([]) { |word, lines| append_word(lines, word) }.join("\n")
+      end
+
+      def append_word(lines, word)
+        current = lines.pop.to_s
+        candidate = current.empty? ? word : "#{current} #{word}"
+        return lines.push(candidate) if current.empty? || UI::Width.measure(candidate) <= width
+
+        lines.push(current.rstrip, word)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Charming
+  module Markdown
+    # URLResolver resolves Markdown link destinations against an optional base URL.
+    class URLResolver
+      def initialize(base_url: nil)
+        @base_url = base_url
+      end
+
+      def resolve(value)
+        return value if base_url.to_s.empty? || value.empty?
+        return value if URI.parse(value).absolute?
+
+        URI.join(base_url, value).to_s
+      rescue URI::InvalidURIError
+        value
+      end
+
+      private
+
+      attr_reader :base_url
+    end
+  end
+end

data/lib/charming/presentation/templates/erb_handler.rb

@@ -4,9 +4,42 @@ require "erb"
 
 module Charming
   module Templates
+    # ErbHandler renders `.tui.erb` / `.txt.erb` templates. Compiled ERB objects are
+    # cached per path: in development the cache is invalidated by file mtime so edits
+    # show up live; in other environments templates are compiled once.
     class ErbHandler
-      def self.render(path, view)
-        ERB.new(File.read(path), trim_mode: "-").result(view.template_binding)
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        def render(path, view)
+          erb(path).result(view.template_binding)
+        end
+
+        # Clears the compiled-template cache (used by tests).
+        def reset_cache
+          @mutex.synchronize { @cache.clear }
+        end
+
+        private
+
+        # Returns the compiled ERB for *path*, recompiling in development when the
+        # file's mtime changes.
+        def erb(path)
+          @mutex.synchronize do
+            entry = @cache[path]
+            mtime = Charming.env.development? ? File.mtime(path) : nil
+            if entry.nil? || (mtime && entry[:mtime] != mtime)
+              entry = {erb: compile(path), mtime: mtime}
+              @cache[path] = entry
+            end
+            entry[:erb]
+          end
+        end
+
+        def compile(path)
+          ERB.new(File.read(path), trim_mode: "-")
+        end
       end
     end
   end

data/lib/charming/presentation/ui/ansi_codes.rb

@@ -56,8 +56,11 @@ module Charming
         @attributes.map { |attribute| ATTRIBUTES.fetch(attribute) }
       end
 
+      # Resolves *color* to SGR codes, downconverting to the terminal's capability
+      # (see UI::ColorSupport): truecolor → 256 → 16 → none.
       def color_codes(color, foreground:)
         return [] unless color
+        return [] if ColorSupport.level == :none
         return indexed_color_code(color, foreground: foreground) if color.is_a?(Integer)
         return named_color_code(color, foreground: foreground) if COLORS.key?(color.to_sym)
         return truecolor_codes(color, foreground: foreground) if color.to_s.start_with?("#")
@@ -72,6 +75,7 @@ module Charming
 
       def indexed_color_code(color, foreground:)
         raise ArgumentError, "indexed color must be between 0 and 255" unless color.between?(0, 255)
+        return basic_color_code(ColorSupport.index_to_16(color), foreground: foreground) unless ColorSupport.at_least?(:color256)
 
         [foreground ? 38 : 48, 5, color]
       end
@@ -79,9 +83,16 @@ module Charming
       def truecolor_codes(color, foreground:)
         hex = color.to_s.delete_prefix("#")
         raise ArgumentError, "truecolor must be #rrggbb" unless hex.match?(/\A[0-9a-fA-F]{6}\z/)
+        return [foreground ? 38 : 48, 5, ColorSupport.hex_to_256(hex)] if ColorSupport.level == :color256
+        return basic_color_code(ColorSupport.hex_to_16(hex), foreground: foreground) if ColorSupport.level == :color16
 
         [foreground ? 38 : 48, 2, hex[0..1].to_i(16), hex[2..3].to_i(16), hex[4..5].to_i(16)]
       end
+
+      # Wraps a basic SGR foreground code (30-37/90-97) for the requested plane.
+      def basic_color_code(code, foreground:)
+        [foreground ? code : code + 10]
+      end
     end
   end
 end

data/lib/charming/presentation/ui/ansi_slicer.rb

@@ -6,6 +6,10 @@ module Charming
     # escape sequences, preserving the styling that is active at the start of
     # the slice and emitting a trailing reset if any styled content was copied.
     class ANSISlicer
+      # One ANSI escape sequence or one grapheme cluster (`\X`). The ANSI branch
+      # comes first so a valid escape is consumed whole rather than as graphemes.
+      TOKEN_PATTERN = /#{Width::ANSI_PATTERN}|\X/
+
       def self.slice(line, start_column, width)
         return "" unless width.positive?
 
@@ -27,16 +31,12 @@ module Charming
       end
 
       def self.each_ansi_or_char(line)
-        index = 0
-        while index < line.length
-          match = line.match(Width::ANSI_PATTERN, index)
-          if match&.begin(0) == index
-            yield match[0], true
-            index = match.end(0)
-          else
-            yield line[index], false
-            index += 1
-          end
+        # Iterate one ANSI escape or one *grapheme cluster* (`\X`) at a time. A
+        # single emoji may be several codepoints (ZWJ sequences, skin-tone and
+        # variation selectors, e.g. "🧙‍♂️"); treating it as one unit keeps its full
+        # display width together so a slice never splits it mid-glyph.
+        line.scan(TOKEN_PATTERN) do |token|
+          yield token, token.start_with?("\e")
         end
       end
 
@@ -57,10 +57,17 @@ module Charming
         char_start = state[:column]
         char_end = char_start + char_width
         state[:column] = char_end
-        return unless char_end > start_column && char_start < end_column
+
+        visible = [char_end, end_column].min - [char_start, start_column].max
+        return unless visible.positive?
 
         start_slice(state)
-        state[:output] << char
+        # A multi-column glyph cut by a slice boundary cannot be partially drawn,
+        # so render the in-range columns as spaces (standard terminal behavior).
+        # This keeps the slice exactly *width* columns wide regardless of where
+        # the boundaries fall relative to wide glyphs.
+        fits = char_start >= start_column && char_end <= end_column
+        state[:output] << (fits ? char : " " * visible)
       end
 
       def self.start_slice(state)
@@ -81,7 +88,7 @@ module Charming
         if token.include?("[0m")
           active.clear
         else
-          active << token
+          active << token unless active.include?(token)
         end
       end