charming 0.1.4 → 0.2.1

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

@@ -39,12 +39,12 @@ module Charming
         child.mouse_targets(Rect.new(x: 0, y: 0, width: screen.width, height: screen.height))
       end
 
-      # Renders the child into the full-screen rect, then overlays each registered overlay
-      # on top in order.
+      # Renders the child into the full-screen rect, then composites each overlay on top —
+      # ordered by z_index (higher paints last), with registration order breaking ties.
       def render
         body = UI.place(render_child, width: screen.width, height: screen.height, background: background)
 
-        overlays.reduce(body) do |current, overlay|
+        stacked_overlays.reduce(body) do |current, overlay|
           UI.overlay(current, overlay.render, top: overlay.top, left: overlay.left)
         end
       end
@@ -60,6 +60,15 @@ module Charming
 
         child.render(Rect.new(x: 0, y: 0, width: screen.width, height: screen.height))
       end
+
+      # Overlays sorted by z_index (stable: registration order breaks ties). Overlays
+      # without a z_index reader (custom nodes) sort at 0.
+      def stacked_overlays
+        overlays.each_with_index.sort_by do |overlay, index|
+          z = overlay.respond_to?(:z_index) ? overlay.z_index.to_i : 0
+          [z, index]
+        end.map(&:first)
+      end
     end
   end
 end

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

@@ -90,8 +90,10 @@ module Charming
       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.
+      # Subtracts the total gap, allocates fixed sizes first, distributes the remainder
+      # among flexible (non-fixed) children by their grow weights, then clamps every
+      # child to its min/max constraints (re-balancing the difference onto flexible
+      # children with remaining slack).
       def child_sizes(axis:, available:)
         gap_size = gap * [children.length - 1, 0].max
         available_for_children = [available - gap_size, 0].max
@@ -100,7 +102,39 @@ module Charming
         sizes = fixed.map { |size| size&.to_i }
         remaining = [available_for_children - sizes.compact.sum, 0].max
 
-        distribute_remaining(sizes, flexible_indexes, remaining)
+        sizes = distribute_remaining(sizes, flexible_indexes, remaining)
+        apply_constraints(sizes, flexible_indexes, axis, available_for_children)
+      end
+
+      # Clamps each child's size to its min/max constraints, then pushes the resulting
+      # surplus or deficit onto the last flexible child that can absorb it without
+      # violating its own constraints.
+      def apply_constraints(sizes, flexible_indexes, axis, available)
+        constrained = sizes.each_with_index.map { |size, index| clamp_size(size, children[index], axis) }
+        difference = available - constrained.sum
+        return constrained if difference.zero?
+
+        absorber = flexible_indexes.rfind do |index|
+          adjusted = constrained[index] + difference
+          adjusted >= 0 && adjusted == clamp_size(adjusted, children[index], axis)
+        end
+        constrained[absorber] += difference if absorber
+        constrained
+      end
+
+      # Clamps *size* to the child's min/max constraint along *axis* (when declared).
+      def clamp_size(size, child, axis)
+        min = constraint(child, (axis == :horizontal) ? :min_width : :min_height)
+        max = constraint(child, (axis == :horizontal) ? :max_width : :max_height)
+        size = [size, min].max if min
+        size = [size, max].min if max
+        size
+      end
+
+      # Reads a constraint reader from *child* when it responds to it (Panes do, nested
+      # Splits currently don't).
+      def constraint(child, name)
+        child.respond_to?(name) ? child.public_send(name) : nil
       end
 
       # Returns the fixed size of *child* along *axis* (`:horizontal` reads width, `:vertical` reads height).

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