markbridge 0.4.2 → 0.5.0

data/lib/markbridge/renderers/discourse/rendering_interface.rb

@@ -32,6 +32,12 @@ module Markbridge
           @renderer.render_children(element, context:, &block)
         end
 
+        # The output of the children as inline tokens, for a tag that
+        # returns tokens itself — see Renderer#render_tokens.
+        def render_tokens(element, context: @context)
+          @renderer.render_tokens(element, context:)
+        end
+
         # Context operations
         def with_parent(element)
           @context.with_parent(element)
@@ -45,6 +51,30 @@ module Markbridge
           @context.html_mode?
         end
 
+        # Markdown that Discourse has to read as Markdown because it has
+        # no HTML form: the BBCode of a plugin (`[poll]`, `[event]`), an
+        # upload (`![a|64x64](upload://…)`), or a placeholder the
+        # importer replaces with one of them. Outside an HTML block it is
+        # the Markdown itself, with a blank line on both sides when
+        # +block+ is true, so a poll or an event stands alone. Inside an
+        # HTML block (see #html_mode?) it is a Markdown island in a
+        # `<div>`, block or not: the blank lines end the HTML block, so
+        # Discourse cooks the Markdown, and the `</div>` line opens the
+        # block again for the rest of the cell. See
+        # HtmlBlock.enclosed_island. A tag that returns a String writes
+        # such Markdown through this method only; the html_mode contract
+        # check rejects a bare blank line inside an HTML block.
+        # @param markdown [String]
+        # @param block [Boolean] whether the Markdown is a block of its own
+        # @return [String]
+        # @example A placeholder for a poll
+        #   interface.markdown_island("[poll|3]", block: true)
+        def markdown_island(markdown, block:)
+          return HtmlBlock.enclosed_island(markdown) if html_mode?
+
+          block ? HtmlBlock.island(markdown) : markdown
+        end
+
         def find_parent(klass)
           @context.find_parent(klass)
         end
@@ -61,6 +91,99 @@ module Markbridge
           @context.root?
         end
 
+        # The node in front of +element+ among the children of its parent.
+        # nil when +element+ is the first child, or when the parent is not
+        # known.
+        # @param element [AST::Node]
+        # @return [AST::Node, nil]
+        def previous_sibling(element)
+          sibling(element, offset: -1)
+        end
+
+        # The node after +element+ among the children of its parent.
+        # @param element [AST::Node]
+        # @return [AST::Node, nil]
+        def next_sibling(element)
+          sibling(element, offset: 1)
+        end
+
+        # The node +offset+ positions away from +element+ among the
+        # children of its parent (negative: in front of it). nil when
+        # there is no node at that position, or when the parent is not
+        # known.
+        #
+        # The renderer knows the element whose children it renders and
+        # the position of the child it renders right now, so the usual
+        # call costs no search, and an element without a tag (which is
+        # not on the parent chain) is found as the parent too. For any
+        # other element the parent is the element on top of the parent
+        # chain, or the root element when the chain is empty, and its
+        # children are searched.
+        # @param element [AST::Node]
+        # @param offset [Integer]
+        # @return [AST::Node, nil]
+        def sibling(element, offset:)
+          if @renderer.current_child?(element)
+            parent = @renderer.child_parent
+            index = @renderer.child_index
+          else
+            parent = @context.element || @context.root
+            return nil if parent.nil?
+
+            index = parent.children.index { |child| child.equal?(element) }
+            return nil if index.nil?
+          end
+
+          target = index + offset
+          parent.children.at(target) unless target.negative?
+        end
+
+        # The last list among the siblings in front of +element+ with
+        # nothing but whitespace, or nodes that rendered to nothing,
+        # after it. See Renderer#previous_list.
+        # @param element [AST::Node]
+        # @return [AST::List, nil]
+        def previous_list(element)
+          @renderer.previous_list(element)
+        end
+
+        # The marker for the items of +node+, a list or a node whose
+        # output is a list: the one the list in front did not use, so the
+        # two stay apart. See Renderer#choose_list_marker.
+        # @param node [AST::Node]
+        # @param ordered [Boolean]
+        # @return [String] "- " or "* ", "1. " or "1) "
+        def choose_list_marker(node, ordered:)
+          @renderer.choose_list_marker(node, ordered:)
+        end
+
+        # The marker chosen for +node+ in this render call, nil when none
+        # was. See Renderer#list_marker.
+        # @param node [AST::Node]
+        # @return [String, nil]
+        def list_marker(node)
+          @renderer.list_marker(node)
+        end
+
+        # The list the output of +node+ starts with, as its tag says, or
+        # nil. With +children: true+ the answer of the first child with
+        # something in it, for a tag whose output starts with the
+        # children's; see Tag#leading_list and Renderer#leading_list.
+        # @param node [AST::Node]
+        # @param children [Boolean]
+        # @return [AST::List, nil]
+        def leading_list(node, children: false)
+          @renderer.leading_list(node, @context, children:)
+        end
+
+        # The list the output of +node+ ends with, see #leading_list.
+        # @param node [AST::Node]
+        # @param children [Boolean]
+        # @return [AST::List, nil]
+        def trailing_list(node, children: false)
+          @renderer.trailing_list(node, @context, children:)
+        end
+
         # Check if element should be rendered in block context
         # @param node [AST::Node] container node or leaf like HorizontalRule
         # @return [Boolean]
@@ -76,50 +199,6 @@ module Markbridge
           # Check if content has newlines
           node.children.any? { |c| c.instance_of?(AST::Text) && c.text.include?("\n") }
         end
-
-        # Leading or trailing whitespace (Unicode-aware, matching the
-        # flanking-preservation sub in #wrap_inline).
-        EDGE_WHITESPACE = /\A[[:space:]]|[[:space:]]\z/m
-        private_constant :EDGE_WHITESPACE
-
-        # Helper: wrap inline content with markers
-        # Handles edge cases like existing markers and whitespace
-        def wrap_inline(content, open_marker, close_marker = nil)
-          close_marker ||= open_marker
-          return content unless content.match?(/[^[:space:]]/)
-
-          # Handle conflicts with existing markers
-          if content.include?(open_marker) || content.include?(close_marker)
-            # Use HTML fallback for common cases
-            case open_marker
-            when "**"
-              return "<strong>#{content}</strong>"
-            when "*"
-              return "<em>#{content}</em>"
-            when "~~"
-              return "<s>#{content}</s>"
-            end
-          end
-
-          apply_markers(content, open_marker, close_marker)
-        end
-
-        private
-
-        # Wrap content in markers, keeping leading/trailing whitespace
-        # outside the markers (Unicode-aware, since CommonMark's flanking
-        # rules treat e.g. nbsp as whitespace).
-        def apply_markers(content, open_marker, close_marker)
-          # Fast path: no edge whitespace to preserve (the common case), so
-          # plain interpolation replaces the capture-group sub below and its
-          # MatchData + capture allocations.
-          return "#{open_marker}#{content}#{close_marker}" unless content.match?(EDGE_WHITESPACE)
-
-          content.sub(/\A([[:space:]]*)(.+?)([[:space:]]*)\z/m) do
-            match = Regexp.last_match
-            "#{match[1]}#{open_marker}#{match[2]}#{close_marker}#{match[3]}"
-          end
-        end
       end
     end
   end

data/lib/markbridge/renderers/discourse/tag.rb

@@ -19,12 +19,14 @@ module Markbridge
         # and is not re-parsed for Markdown except across blank lines.
         # Every tag must pick one of two contracts:
         #
-        # 1. Emit raw HTML (e.g. `<strong>` for `**`).
-        # 2. Wrap Markdown output in `\n\n…\n\n` so the blank lines close
-        #    the HTML block, CommonMark parses the content as a Markdown
-        #    island, then re-opens. Visible: blank-line wrapping forces a
-        #    `<p>` margin around inline content, so prefer (1) when the
-        #    tag has an HTML form.
+        # 1. Emit raw HTML (e.g. `<strong>` for `**`), with no blank line
+        #    in it.
+        # 2. Write the Markdown through `interface.markdown_island`, which
+        #    puts it between blank lines inside a `<div>`: the blank lines
+        #    close the HTML block, CommonMark parses the content as a
+        #    Markdown island, and the `</div>` line re-opens the block.
+        #    Visible: blank-line wrapping forces a `<p>` margin around
+        #    inline content, so prefer (1) when the tag has an HTML form.
         #
         # @param element [AST::Node] the node to render
         # @param interface [RenderingInterface] the rendering interface
@@ -37,15 +39,57 @@ module Markbridge
           end
         end
 
+        # The list the output of this tag starts with, when it starts with
+        # one. Two lists of the same kind with only whitespace between
+        # them cook as one list, so the renderer keeps track of the last
+        # list it wrote (see RenderingInterface#previous_list) and ListTag
+        # puts a separator in front of a list that would continue it. A
+        # tag whose output starts with the output of a child, like the
+        # plain form of DetailsTag, answers with that child's list:
+        # +interface.leading_list(element, children: true)+. ListTag
+        # answers with the list itself. The default is nil: the output
+        # starts with something of its own, or with nothing.
+        #
+        # @param element [AST::Node]
+        # @param interface [RenderingInterface]
+        # @return [AST::List, nil]
+        def leading_list(_element, _interface)
+        end
+
+        # The list the output of this tag ends with, when it ends with
+        # one, see #leading_list. +interface.trailing_list(element,
+        # children: true)+ is the answer of the last child with something
+        # in it.
+        #
+        # @param element [AST::Node]
+        # @param interface [RenderingInterface]
+        # @return [AST::List, nil]
+        def trailing_list(_element, _interface)
+        end
+
         # A tag that renders only the element's children, with the element
         # pushed on the parent chain. Tag dispatch matches by ancestry, so
         # a subclass normally inherits its base class tag; register
         # PASSTHROUGH for the subclass to opt out — the exact-class hit
         # wins and the base tag is not used.
         PASSTHROUGH =
-          new do |element, interface|
-            interface.render_children(element, context: interface.with_parent(element))
-          end.freeze
+          Class
+            .new(self) do
+              def render(element, interface)
+                interface.render_children(element, context: interface.with_parent(element))
+              end
+
+              # The output is the children's, so its edges are theirs.
+              def leading_list(element, interface)
+                interface.leading_list(element, children: true)
+              end
+
+              def trailing_list(element, interface)
+                interface.trailing_list(element, children: true)
+              end
+            end
+            .new
+            .freeze
       end
     end
   end

data/lib/markbridge/renderers/discourse/tags/bold_tag.rb

@@ -4,14 +4,12 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering bold text
+        # Strong emphasis. The serializer writes the markers, or the HTML
+        # tags where the markers would not work.
         class BoldTag < Tag
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-            return "<strong>#{content}</strong>" if interface.html_mode?
-
-            interface.wrap_inline(content, "**")
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            tokens.unshift(Inline::Tokens.open(:strong)) << Inline::Tokens.close(:strong)
           end
         end
       end

data/lib/markbridge/renderers/discourse/tags/code_tag.rb

@@ -5,13 +5,22 @@ module Markbridge
     module Discourse
       module Tags
         class CodeTag < Tag
+          BACKTICKS = /`+/
+          TILDES = /~+/
+          private_constant :BACKTICKS, :TILDES
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
             # An empty element renders to nothing — a bare `` pair or an
-            # empty fence would only add noise to the output.
-            return "" if content.empty?
+            # empty fence would only add noise to the output. An empty code
+            # block is still a block, so a blank line keeps the text in
+            # front and after it apart, except in an HTML block, which a
+            # blank line would end.
+            if content.empty?
+              return interface.block_context?(element) && !interface.html_mode? ? "\n\n" : ""
+            end
 
             if interface.block_context?(element)
               if interface.html_mode?
@@ -22,14 +31,34 @@ module Markbridge
             elsif interface.html_mode?
               "<code>#{content}</code>"
             else
+              # A pipe in a code span still splits the cell of a Markdown
+              # table, the escaped pipe does not and reads back as a pipe.
+              content = content.gsub("|", "\\|") if interface.has_parent?(AST::TableCell)
               render_inline(content)
             end
           end
 
           private
 
+          # The delimiter is one backtick longer than the longest backtick
+          # run in the content. A space on each side keeps a backtick at
+          # the edge of the content away from the delimiter. Content that
+          # starts and ends with a space gets the same padding, because
+          # CommonMark strips one space from each end of such a span.
           def render_inline(content)
-            "`#{content}`"
+            delimiter = "`" * (longest_run(content, BACKTICKS) + 1)
+            padding = " " if needs_padding?(content)
+
+            "#{delimiter}#{padding}#{content}#{padding}#{delimiter}"
+          end
+
+          def needs_padding?(content)
+            return true if content.start_with?("`") || content.end_with?("`")
+
+            # A span of spaces only is not stripped by CommonMark, so it
+            # needs no padding.
+            content.start_with?(" ") && content.end_with?(" ") &&
+              content.count(" ") < content.length
           end
 
           # Leading and trailing blank lines: the trailing one keeps an
@@ -38,20 +67,22 @@ module Markbridge
           # from prior raw text or inline content.
           def render_block(content, language)
             fence = calculate_fence(content)
-            "\n\n#{fence}#{language}\n#{content}\n#{fence}\n\n"
+            # The newline in front of the closing fence is part of the fence
+            # syntax, not of the code. A content that already ends with a
+            # newline (as <pre> content from HTML usually does) would
+            # otherwise cook with a blank line too many at the end.
+            "\n\n#{fence}#{language}\n#{content.chomp}\n#{fence}\n\n"
           end
 
+          # A blank line in the code would end the HTML block around it.
           def render_html_block(content, language)
             class_attr = %( class="language-#{HtmlEscaper.escape(language)}") if language
-            "<pre><code#{class_attr}>#{content}</code></pre>"
+            "<pre><code#{class_attr}>#{HtmlBlock.without_blank_lines(content)}</code></pre>"
           end
 
           def calculate_fence(content)
-            max_backticks = content.scan(/`+/).map(&:length).max || 0
-            max_tildes = content.scan(/~+/).map(&:length).max || 0
-
-            required_backticks = [3, max_backticks + 1].max
-            required_tildes = [3, max_tildes + 1].max
+            required_backticks = [3, longest_run(content, BACKTICKS) + 1].max
+            required_tildes = [3, longest_run(content, TILDES) + 1].max
 
             if required_backticks <= required_tildes
               "`" * required_backticks
@@ -59,6 +90,13 @@ module Markbridge
               "~" * required_tildes
             end
           end
+
+          # The length of the longest run that +pattern+ finds in
+          # +content+, 0 when there is none. A delimiter or a fence has to
+          # be longer than that.
+          def longest_run(content, pattern)
+            content.scan(pattern).map(&:length).max || 0
+          end
         end
       end
     end

data/lib/markbridge/renderers/discourse/tags/color_tag.rb

@@ -4,21 +4,81 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering colored text
-        # Note: Discourse doesn't support inline color by default
-        # Renders as plain text with HTML comment noting the color was lost
+        # Tag for rendering colored text.
+        #
+        # Discourse core removes the style of a span. Only the
+        # discourse-bbcode plugin can show colors, so the tag needs to
+        # know whether the site has it. Until it knows, a color raises
+        # {UndecidedFeatureError}.
+        #
+        # - +bbcode: nil+ (the default): a color raises.
+        # - +bbcode: false+: the text only, as inline tokens that the
+        #   serializer joins with the neighbors.
+        # - +bbcode: true+: +[color=…]…[/color]+, with the value mapped
+        #   through +colors:+ when there is a mapping. A value the plugin
+        #   would not accept (+#rgb+, +#rrggbb+ or a name) raises
+        #   ArgumentError; a mapping that returns nil drops the color on
+        #   purpose.
+        #
+        # Inside a link the text is written without BBCode in every case,
+        # Discourse doesn't render BBCode in the text of a link.
         class ColorTag < Tag
+          # #rgb, #rrggbb or a color name. Anything else (and anything that
+          # could end the BBCode tag early) is refused.
+          VALUE = /\A(?:#\h{3}|#\h{6}|[a-z]+)\z/i
+          private_constant :VALUE
+
+          UNDECIDED =
+            "a [color] tag needs a decision: pass features: { bbcode: false } to " \
+              "Markbridge.discourse_renderer to write the text only, or " \
+              "features: { bbcode: true } for the discourse-bbcode plugin"
+          private_constant :UNDECIDED
+
+          # @param bbcode [Boolean, nil] whether the site has discourse-bbcode
+          # @param colors [Hash, #call, nil] a mapping from the source value
+          #   to the value written. A Hash is read with +fetch+, so an
+          #   unknown value raises KeyError.
+          def initialize(bbcode: nil, colors: nil)
+            @bbcode = bbcode
+            @colors = colors
+          end
+
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
-
-            if element.color
-              # Render as HTML span with style - requires HTML to be enabled
-              # Alternative: just output the text without color
-              "<span style=\"color: #{element.color}\">#{content}</span>"
-            else
-              content
-            end
+            context = interface.with_parent(element)
+            color = bbcode_color(element.color, interface)
+            return interface.render_tokens(element, context:) if color.nil?
+
+            content = interface.render_children(element, context:)
+            # The style that the discourse-bbcode plugin lets through.
+            return %(<span style="color:#{color}">#{content}</span>) if interface.html_mode?
+
+            Paragraphs.wrap(content, "[color=#{color}]", "[/color]")
+          end
+
+          private
+
+          # @return [String, nil] the color to write, nil for the text only
+          def bbcode_color(value, interface)
+            return if text_only?(value, interface)
+            raise UndecidedFeatureError, UNDECIDED if @bbcode.nil?
+
+            mapped = @colors ? apply(@colors, value) : value
+            return mapped if mapped.nil? || VALUE.match?(mapped)
+
+            raise ArgumentError,
+                  "color #{value.inspect} maps to #{mapped.inspect}, discourse-bbcode accepts " \
+                    "#rgb, #rrggbb or a name; pass colors: to map it, or to drop it with nil"
+          end
+
+          def apply(mapping, value)
+            mapping.respond_to?(:call) ? mapping.call(value) : mapping.fetch(value)
+          end
+
+          # No value, the plugin decided against, or a link around it: the
+          # text is all there can be, and no decision changes that.
+          def text_only?(value, interface)
+            value.to_s.match?(/\A[[:space:]]*\z/) || @bbcode == false ||
+              interface.has_parent?(AST::Url) || interface.has_parent?(AST::Email)
           end
         end
       end

data/lib/markbridge/renderers/discourse/tags/details_tag.rb

@@ -4,37 +4,68 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Renders {AST::Details} as a Discourse +[details=…]…[/details]+
-        # collapsible block.
+        # Renders {AST::Details} as the +[details="…"]…[/details]+ block of
+        # the discourse-details plugin.
         #
-        # Markdown form: the BBCode is bracketed with leading and trailing
-        # blank lines so consecutive details blocks don't merge and
-        # adjacent inline content starts a new paragraph against the
-        # block. Inside, the rendered children are stripped so the
-        # +[details]+ opener and the body sit on adjacent lines without
-        # a stray blank between them — matching Discourse's BBCode
-        # parser expectations.
+        # Markdown form: the BBCode has blank lines around it, so
+        # consecutive details blocks don't merge and inline content next
+        # to the block starts a new paragraph. The content inside is
+        # stripped, so the opening tag and the body stand on adjacent
+        # lines.
         #
-        # HTML-block form (inside a CommonMark HTML block — when
-        # +interface.html_mode?+ is +true+): a raw
-        # +<details><summary>…</summary>…</details>+ element. The
-        # +title+ is HTML-escaped for the +<summary>+ text.
+        # html_mode form: a raw +<details><summary>…</summary>…</details>+,
+        # with the title HTML-escaped.
+        #
+        # With +bbcode: false+, for a site without the plugin, the title is
+        # a paragraph in bold in front of the content. Discourse core's
+        # sanitizer has no +<details>+, so there is no HTML form.
         class DetailsTag < Tag
           DEFAULT_TITLE = "Summary"
           private_constant :DEFAULT_TITLE
 
+          # @param bbcode [Boolean] write the BBCode of the plugin
+          def initialize(bbcode: true)
+            @bbcode = bbcode
+          end
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context).strip
 
             # A details block with nothing to show renders to nothing —
             # an empty [details] shell would only add noise to the output.
-            return "" if content.empty?
+            # It is still a block, so a blank line keeps the text in front
+            # and after it apart, except in an HTML block, which a blank
+            # line would end.
+            return interface.html_mode? ? "" : "\n\n" if content.empty?
 
+            return without_plugin(element, content, interface) unless @bbcode
             return render_html(element.title, content) if interface.html_mode?
 
+            # Blank lines keep the content apart from the two tag lines:
+            # a table right in front of the closing tag would take the
+            # tag line as a row, and a `---` right after the opening tag
+            # would make it a heading. Discourse finds the closing tag
+            # line first and reads the lines between as blocks, so the
+            # blank lines change nothing there.
             opener = element.title ? %([details="#{element.title}"]) : "[details]"
-            "\n\n#{opener}\n#{content}\n[/details]\n\n"
+            "\n\n#{opener}\n\n#{content}\n\n[/details]\n\n"
+          end
+
+          # The plain form starts with the content when there is no title,
+          # and ends with the content in any case, so a list at that edge
+          # of the content is at the edge of the output (see
+          # Tag#leading_list). The BBCode form has its own lines there.
+          def leading_list(element, interface)
+            return nil if @bbcode || !element.title.to_s.strip.empty?
+
+            interface.leading_list(element, children: true)
+          end
+
+          def trailing_list(element, interface)
+            return nil if @bbcode
+
+            interface.trailing_list(element, children: true)
           end
 
           private
@@ -43,6 +74,22 @@ module Markbridge
             label = title ? HtmlEscaper.escape(title) : DEFAULT_TITLE
             "<details><summary>#{label}</summary>#{content}</details>"
           end
+
+          # The title as a paragraph in bold, rendered like any paragraph,
+          # then the content. In html_mode a div keeps the block apart from
+          # the text around it, as the blank lines do in Markdown.
+          def without_plugin(element, content, interface)
+            title = element.title.to_s.strip
+            heading = ""
+            unless title.empty?
+              paragraph = AST::Paragraph.new << (AST::Bold.new << AST::Text.new(title))
+              heading = interface.render_node(paragraph)
+            end
+            return "<div>#{heading}#{content}</div>" if interface.html_mode?
+
+            heading = "#{heading.strip}\n\n" unless heading.empty?
+            "\n\n#{heading}#{content}\n\n"
+          end
         end
       end
     end

data/lib/markbridge/renderers/discourse/tags/email_tag.rb

@@ -4,20 +4,19 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering email links
+        # Mail links: a link token pair with a mailto: destination around
+        # the children. Without an address the children stand alone;
+        # without visible text the address is written as a bare URL.
         class EmailTag < Tag
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            text = interface.render_children(element, context: child_context)
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
             address = element.address
+            return tokens unless address
 
-            return text unless address
+            destination = "mailto:#{address}"
+            return [Inline::Tokens.bare_url(destination)] unless Inline::Tokens.visible?(tokens)
 
-            if interface.html_mode?
-              %(<a href="mailto:#{HtmlEscaper.escape(address)}">#{text}</a>)
-            else
-              "[#{text}](mailto:#{address})"
-            end
+            tokens.unshift(Inline::Tokens.link_open(destination)) << Inline::Tokens.link_close
           end
         end
       end