HTML Renderer (#6)

build out HTML renderer.

Author: Greg MacWilliam

README.md

@@ -99,3 +99,152 @@ Retain operations have a Number `retain` key defined representing the number of
 { retain: 5, attributes: { bold: null } }
 ```
 
+## HTML Formatting
+
+Rich-text deltas may be formatted as HTML by calling `delta.to_html`. The rendered markup will be generated based on formatting rules configured for the `RichText` module.
+
+### Inline formats
+
+Inline formatting rules are used to build tags for the flow of content elements.
+
+```ruby
+# Config:
+RichText.configure do |c|
+  c.html_default_block_format = 'p'
+  c.html_inline_formats = {
+    bold:        { tag: 'strong' },
+    italic:      { tag: 'em' },
+    br:          { tag: 'br' },
+    link:        { tag: 'a', apply: ->(el, op, ctx){ el[:href] = op.attributes[:link] } }
+  }
+end
+
+# Delta:
+[
+  { insert: "a man," },
+  { insert: "\n", attributes: { br: true } },
+  { insert: "a plan", attributes: { bold: true, italic: true } },
+  { insert: "\n" },
+  { insert: "panama\n", attributes: { link: 'https://visitpanama.com' } }
+]
+
+# HTML result:
+%(
+  <p>a man,<br><strong><em>a plan</em></strong></p>
+  <p><a href="https://visitpanama.com">panama</a></p>
+)
+```
+
+Each newline (`"\n"`) character denotes a block separation, at which time the inline flow will be wrapped in a block tag specified by `html_default_block_format`. An inline element's block wrapper maybe customized with the `block_format` setting, or omitted with the `omit_block` setting. For soft or visible line breaks such as `br` or `hr` tags, you may assign them inline formats to render them as content flow.
+
+```ruby
+# Config:
+RichText.configure do |c|
+  c.html_default_block_format = 'p'
+  c.html_inline_formats = {
+    hr:    { tag: 'hr', omit_block: true },
+    code:  { tag: 'code', block_format: 'div' }
+  }
+end
+
+# Delta:
+[
+  { insert: "sample code" },
+  { insert: "\n", attributes: { hr: true } },
+  { insert: "published = true", attributes: { code: true } },
+  { insert: "\n" }
+]
+
+# HTML result:
+%(
+  <p>sample code</p>
+  <hr>
+  <div><code>published = true</code></div>
+)
+```
+
+### Block formats
+
+Block tags are wrapped around a flow of elements whenever a newline is encountered (unless it has an inline format). Block formats should always apply to newline (`"\n"`) inserts.
+
+```ruby
+RichText.configure do |c|
+  c.html_block_formats = {
+    firstheader: { tag: 'h1' },
+    bullet:      { tag: 'li', parent: 'ul' },
+    id:          { apply: ->(el, op, ctx){ el[:id] = op.attributes[:id] } }
+  }
+end
+
+# Delta:
+[
+  { insert: "Blocks are fun" },
+  { insert: "\n", attributes: { firstheader: true, id: 'blockfun' } },
+  { insert: "item 1" },
+  { insert: "\n", attributes: { bullet: true } },
+  { insert: "item 2" },
+  { insert: "\n", attributes: { bullet: true } }
+]
+
+# HTML result:
+%(
+  <h1 id="blockfun">Blocks are fun</h1>
+  <ul>
+    <li>item 1</li>
+    <li>item 2</li>
+  </ul>
+)
+```
+
+Block tags may define a `parent` tag, or an array of parents. When a block has a parent, its full parent tree is constructed and/or merged with a compatible node tree that preceeds it.
+
+### Formatting lambdas
+
+Use `tag` and `apply` lambdas to customize tag structures.
+
+```ruby
+# Config:
+RichText.configure do |c|
+  c.html_default_block_format = 'p'
+  c.html_inline_formats = {
+    image: {
+      omit_block: true,
+      tag: ->(el, op, ctx){
+        el.name = 'figure'
+        el.add_child(%(<img src="#{ op.value[:image][:src] }">))
+        el.add_child(%(<figcaption>#{ op.value[:image][:caption] }</figcaption>))
+        el
+      }
+    },
+    link: {
+      tag: 'a',
+      apply: ->(el, op, ctx){ el[:href] = op.attributes[:link] }
+    }
+  }
+end
+
+# Delta:
+[
+  { insert: { image: { src: 'https://placekitten.com/100/100', caption: 'cute' } } },
+  { insert: "\n" },
+  { insert: "more kittens", attributes: { link: 'https://placekitten.com' } },
+  { insert: "\n" }
+]
+
+# HTML result:
+%(
+  <figure>
+    <img src="https://placekitten.com/100/100">
+    <figcaption>cute</figcaption>
+  </figure>
+  <p><a href="https://placekitten.com">more kittens</a></p>
+)
+```
+
+A `tag` lambda is called once when an element is created. The tag lambda returns a customized node structure, or nil to render nothing. An `apply` lambda is called for each formatting rule applied to an element. An apply lambda does not return a value.
+
+**Both `tag` and `apply` receive the same arguments:**
+
+- `el`: the [Nokogiri::XML::Node](https://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/Node) instance being rendered. For `tag` lambdas, this will be a new `span`.
+- `op`: the `RichText::Op` instance being rendered. You may references its `attributes` and `value`.
+- `ctx`: an optional context object passed via `delta.to_html(context: obj)`. Providing a render context allows data to be shared across all formatting functions.

lib/rich-text.rb

@@ -14,18 +14,24 @@ def self.configure
 require 'rich-text/html'
 
 RichText.configure do |c|
-  c.safe_mode = true
-  c.html_default_block_tag = 'p'
-  c.html_block_tags = {
-    firstheader: 'h1',
-    secondheader: 'h2',
-    thirdheader: 'h3',
-    list: ->(content, value) { %(<ol><li>#{value}</li></ol>) },
-    bullet: ->(content, value) { %(<ul><li>#{value}</li></ul>) }
+
+  c.html_inline_formats = {
+    bold:           { tag: 'strong' },
+    br:             { tag: 'br' },
+    hr:             { tag: 'hr', block_format: false },
+    italic:         { tag: 'em' },
+    link:           { tag: 'a', apply: ->(el, op, ctx){ el[:href] = op.attributes[:link] } }
   }
-  c.html_inline_tags = {
-    bold: 'strong',
-    italic: 'em',
-    link: ->(content, value) { %(<a href="#{value}">#{content}</a>) }
+
+  c.html_block_formats = {
+    firstheader:    { tag: 'h1' },
+    secondheader:   { tag: 'h2' },
+    thirdheader:    { tag: 'h3' },
+    bullet:         { tag: 'li', parent: 'ul' },
+    list:           { tag: 'li', parent: 'ol' },
+    id:             { apply: ->(el, op, ctx){ el[:id] = op.attributes[:id] } }
   }
+
+  c.html_default_block_format = 'p'
+  c.safe_mode = true
 end

lib/rich-text/config.rb

@@ -1,6 +1,6 @@
 module RichText
   # @api private
   class Config
-    attr_accessor :safe_mode, :html_default_block_tag, :html_block_tags, :html_inline_tags
+    attr_accessor :safe_mode, :html_inline_formats, :html_block_formats, :html_default_block_format
   end
 end