charming 0.1.0 → 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/layout.rb

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+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
+          @theme = theme || UI::Theme.default
+          @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
+
+        # 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
+
+        # 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
+
+        # 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
+
+          value.to_s.lines(chomp: true).map { |line| wrap_line(line, width) }.join("\n")
+        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)
+
+          fallback
+        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)
+
+          UI::Theme::DEFAULT_TOKENS.fetch(name).then { |token| UI::Theme.new(name => token).public_send(name) }
+        end
+
+        private
+
+        # The BlockRenderer instance, lazily built.
+        def block_renderer
+          @block_renderer ||= BlockRenderer.new(renderer: self)
+        end
+
+        # 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
+
+          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
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+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|
+            style_for(token).render(value)
+          end.join
+        end
+
+        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)
+
+          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
+
+        # 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)
+
+          fallback || UI.style
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/markdown.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+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
+end

data/lib/charming/presentation/template_view.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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)
+        @template = template
+        @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
+
+        namespace.module_eval("->(view) { view.instance_eval { binding } }", __FILE__, __LINE__).call(self)
+      end
+
+      private
+
+      attr_reader :template, :namespace
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Charming
+  module Presentation
+    module Templates
+      class ErbHandler
+        def self.render(path, view)
+          ERB.new(File.read(path), trim_mode: "-").result(view.template_binding)
+        end
+      end
+    end
+  end
+end