kramdown-components 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d12fd7ba367f8b2ff86e9e6d313781b88757b37c456a94654ade598c0b47df41
-  data.tar.gz: 7a02bd99bce593452e2d3f510718b474a1acc894c730d66e1f9eba07ecd3e0bd
+  metadata.gz: 88fc82100145b4d17743313e5975016be37fbee2887a415ac784d5443b42ef43
+  data.tar.gz: 423666e61c2b28eb8ed764a688cfb3c0ec4e260ca7932810f32dcf075ef28217
 SHA512:
-  metadata.gz: 6db57afee5989ac53ab2cd7b1668e9f110fd88e1da20195f724a218c4d59530487ed8bd095267441e9805b046a321530118c53382bed55783df63fc5e7bbbf39
-  data.tar.gz: e86b0cd86885dce1175a6384b03f037f39d32cc962e1d5ad176f37604e38008a0f884f125f150fc119f6fd2f1ab34fe4234ac532b6fbe549bbdb0e2cdc4b5589
+  metadata.gz: 83c176d9d2e3affcf7f33a128550fb9a8af84b2193c2a39cca6d704d790a8ddba3be314e82b84e96c6b995def86fe438ab7911a4707c4c71c8a7351c9af48e17
+  data.tar.gz: ef7a2f3d053ab444fb87044f0ffe26a3ca8f929b03f23b753a199f99a333def509aa9e6ff568ef317be04183d8633e76712aedd3cfbb47084c0f632da2f49b20

data/.gitignore

@@ -0,0 +1 @@
+kramdown-components-*.gem

data/README.md

@@ -1,8 +1,8 @@
 # Kramdown Components
 
-Rewrite sections of Markdown documents using HTML Custom Elements.
+Rewrite and capture sections of Markdown documents using HTML Custom Elements.
 
-Useful for enhancing code blocks and formatted markup with more sophisticated controls while maintaining a clean separation of presentation and content.
+Useful for enhancing code blocks and formatted markup with more sophisticated controls while maintaining a clean separation of presentation and content. Extract content from custom elements.
 
 ## How it Works
 
@@ -22,10 +22,135 @@ doc = Kramdown::CustomDocument("# Title")
 puts doc.to_html
 ```
 
-### Registration Phase
+### Registering Components
 
-```rb
+To define a custom element that can wrap child elements with the Markdown document, use the `define_element` class method to set the tag name.
 
+```ruby
+Kramdown::CustomDocument.define_element("wrapped-block")
+```
+
+You can customise the behaviour of components by extending `CustomElement` and binding the class to the tag name.
+
+```ruby
+class ImageGallery < Kramdown::CustomElement; end
+
+Kramdown::CustomDocument.define_element("image-gallery", ImageGallery)
+```
+
+### Rewriting the DOM
+
+To rewrite DOM subtrees wrapped by the component, implement the `parse_dom` method of `CustomElement` and manipulate the internal `root` and `children` elements, with instances of `Kramdown::Element` to represent each node.
+
+```ruby
+class ButtonList < Kramdown::CustomElement
+  def parse_dom(root)
+    uls = root.children.filter { |child_el| child_el.type == :ul }
+    uls.each do |ul|
+      ul.children.each do |li|
+        button = Kramdown::Element.new(:html_element, "button")
+        button.children = li.children
+        li.children = [button]
+      end
+    end
+  end
+end
+
+Kramdown::CustomDocument.define_element("button-list", ButtonList)
+```
+
+When this `#parse_dom` hook is applied, all child lists nested within the `<button-list>` component get rewritten to have the content of each list item wrapped in a `<button>`.
+
+**Source:**
+
+```md
+<button-list>
+
+- One
+- Two
+- Three
+
+</button-list>
+```
+
+**Result:**
+
+```html
+<button-list id="bl-uftcpsbnzytd">
+  <ul>
+    <li><button>One</button></li>
+    <li><button>Two</button></li>
+    <li><button>Three</button></li>
+  </ul>
+</button-list>
+```
+
+## Extracting Content from the DOM
+
+It’s also possible to use `#parse_dom` to extract content from the document, with or without rewriting.
+
+```ruby
+class Color
+  def self.from_hex(value)
+    r, g, b = value.match(/^#(..)(..)(..)$/).captures.map(&:hex)
+    new(r, g, b)
+  end
+
+  attr_reader :r, :g, :b
+
+  def initialize(r, g, b)
+    @r = r
+    @g = g
+    @b = b
+  end
+
+  def to_css
+    "rgb(#{r}, #{g}, #{b})"
+  end
+end
+
+class ColorSwatch < Kramdown::CustomElement
+  def parse_dom(root)
+    ul = root.children.find { |child_el| child_el.type == :ul }
+    @colors = ul.children.map do |li|
+      li.children.first.children.first.value
+    end
+  end
+
+  def to_a
+    @colors.map { |hex| Color.from_hex(hex) }
+  end
+end
+
+Kramdown::CustomDocument.define_element("color-swatch", ColorSwatch)
+```
+
+**Source:**
+
+```md
+Using the [HoneyGB palette](https://lospec.com/palette-list/honeygb):
+
+<color-swatch>
+
+- #3e3a42
+- #877286
+- #f0b695
+- #e9f5da
+
+</color-swatch>
 ```
 
-### Compile Phase
+**Result:**
+
+```ruby
+document = Kramdown::CustomDocument(source)
+
+# Get a reference to the parsed `ColorSwatch` instance
+color_swatch = document.custom_elements.first
+
+# Use the custom `#to_a` method to get the first extracted color
+color = color_swatch.to_a.first
+
+# Render the color value as an RGB string
+color.to_css
+```

data/kramdown-components.gemspec

@@ -1,15 +1,15 @@
 Gem::Specification.new do |spec|
   spec.name = "kramdown-components"
-  spec.version = "0.0.1"
+  spec.version = "0.2.0"
   spec.platform = Gem::Platform::RUBY
-  spec.summary = "Rewrite sections of Markdown documents using HTML Custom Elements."
-  spec.description = "Mix and match HTML and Markdown syntax. Generate nested DOM trees from a single top level element."
+  spec.summary = "Rewrite and capture sections of Markdown documents using HTML Custom Elements."
+  spec.description = "Mix and match HTML and Markdown syntax. Generate nested DOM trees from a single top level element. Extract content from custom elements."
   spec.authors = ["Mark Rickerby"]
   spec.email = "me@maetl.net"
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.add_runtime_dependency "kramdown", '~> 2.4.0'
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rspec"
+  spec.add_runtime_dependency "kramdown", "~> 2.4.0"
+  spec.add_development_dependency "bundler", "~> 2.3.22"
+  spec.add_development_dependency "rspec", "~> 3.11.0"
   #spec.add_development_dependency "rspec-html"
   spec.homepage = "https://github.com/maetl/kramdown-components"
   spec.license = "MIT"

data/lib/kramdown/custom_document.rb

@@ -13,15 +13,15 @@ module Kramdown
       @@custom_elements[tag_name] = element
     end
 
+    DEFAULTS = {
+      parse_block_html: true
+    }
+
     attr_reader :custom_elements
 
-    def initialize(source)
+    def initialize(source, options={})
       @source = source
-      @parsed_dom = Kramdown::Document.new(@source, {
-        input: "GFM",
-        parse_block_html: true,
-        syntax_highlighter: "rouge"
-      })
+      @parsed_dom = Kramdown::Document.new(@source, DEFAULTS.merge(options))
       @custom_elements = extract_custom_elements
     end
 
@@ -37,25 +37,12 @@ module Kramdown
       @parsed_dom.to_html
     end
 
-    def has_js?
-      !@custom_elements.empty?
-    end
-
-    def to_js
-      bundle = ["const EXAMPLE_HANDLERS = {}"]
-
-      @custom_elements.each do |element|
-        bundle << element.to_js
-        bundle << "EXAMPLE_HANDLERS[\"#{element.id}\"] = #{element.name}"
-      end
-
-      bundle.join("\n\n")
-    end
-
     def method_missing(id, *attr, &block)
       @parsed_dom.send(id, attr, &block)
     end
 
+    private
+
     def generate_el_id(tagname)
       alphabet = [('a'..'z')].map(&:to_a).flatten
       tag_id = (0...12).map { alphabet[rand(alphabet.length)] }.join
@@ -74,23 +61,8 @@ module Kramdown
           end
 
           custom_element_cls = @@custom_elements[outer_el.value]
-          element = custom_element_cls.new(outer_el.attr["id"], outer_el)
-          element.parse_dom
-
-          # codeblocks = outer_el.children.filter { |child_el| child_el.type == :codeblock }
-          #
-          # outer_el.children = codeblocks.map do |codeblock|
-          #   wrapper = Kramdown::Element.new(
-          #     :html_element,
-          #     "example-script",
-          #     { label: LANG_LABELS[codeblock.options[:lang]] },
-          #     { content_model: :block }
-          #   )
-          #   wrapper.children << codeblock
-          #   wrapper
-          # end
-          #
-          # outer_el.children.first.attr[:selected] = true
+          element = custom_element_cls.new(outer_el.attr["id"])
+          element.parse_dom(outer_el)
 
           elements << element
         end

data/lib/kramdown/custom_element.rb

@@ -1,13 +1,12 @@
 module Kramdown
   class CustomElement
-    attr_reader :id, :outer_el
+    attr_reader :id
 
-    def initialize(id, outer_el)
+    def initialize(id)
       @id = id
-      @outer_el = outer_el
     end
 
-    def parse_dom
+    def parse_dom(root)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kramdown-components
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Mark Rickerby
@@ -28,32 +28,32 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.3.22
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.3.22
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.11.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.11.0
 description: Mix and match HTML and Markdown syntax. Generate nested DOM trees from
-  a single top level element.
+  a single top level element. Extract content from custom elements.
 email: me@maetl.net
 executables: []
 extensions: []
@@ -90,5 +90,5 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key:
 specification_version: 4
-summary: Rewrite sections of Markdown documents using HTML Custom Elements.
+summary: Rewrite and capture sections of Markdown documents using HTML Custom Elements.
 test_files: []