papercraft 0.11 → 0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3452d115d85742018d1497b369ea27970f0c144e3dcb1772f4d81e33315dce51
-  data.tar.gz: e7217a9d9bcfd7af0dc92482650bc03392b0406cf4f3d6141c253a2918638545
+  metadata.gz: be072094c35a6f89327b9c88b90264ad3db61cb43311d0e3baca865f403fdbc5
+  data.tar.gz: 7e565933dd83c48c05bac8c648cbe9b0007bc43f8fc5bd862af46dcd00dfb328
 SHA512:
-  metadata.gz: 8f76b9e73aa48f91af932af3308d3dd43239c3d5ca39e305cb1535417b5997483aa884f0e34ed128800b07a3135ebc1d18ea81d0df64e6170726a66c86969288
-  data.tar.gz: dbe744ca25996c3d263ff609ca26f42076784fdbceabd2dd1604dd1016e2d840830230f4205a673b9e5ba14eb8e480627612971b71ca6631e0a6e473d59ccb73
+  metadata.gz: 9b8da36fb3c7298e8121b9c612cb81752609e1e3d1f01a94e4bf939864b29de718884989203077c5c1392926a54205c921adbcaa1bf3aa75d84694b7b4db4dcc
+  data.tar.gz: 778163311cb86ee425c4617ff54b10e8853d9b92404ef29abac848a4252818386b2e23058c355678c286a5bae3db9d4a7bfb182acb0a4aacf00a042431cc196a

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.12 2022-01-06
+
+- Improve documentation
+- Add `Renderer#tag` method
+- Add `HTML#style`, `HTML#script` methods
+
 ## 0.11 2022-01-04
 
 - Add deferred evaluation

data/README.md

@@ -20,8 +20,6 @@
   <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
 </p>
 
-# Papercraft - Composable HTML templating for Ruby
-
 ## What is Papercraft?
 
 ```ruby
@@ -368,7 +366,7 @@ The default Kramdown options are:
 ```
 
 The deafult options can be configured by accessing
-`Papercraft::HTML.kramdown_options`:
+`Papercraft::HTML.kramdown_options`, e.g.:
 
 ```ruby
 Papercraft::HTML.kramdown_options[:auto_ids] = false
@@ -430,7 +428,7 @@ page = default_layout.apply {
 
 Papercraft extensions are modules that contain one or more methods that can be
 used to render complex HTML components. Extension modules can be used by
-installing them as a namespaced extension using `Papercraft.extension`.
+installing them as a namespaced extension using `Papercraft::extension`.
 Extensions are particularly useful when you work with CSS frameworks such as
 [Bootstrap](https://getbootstrap.com/), [Tailwind](https://tailwindui.com/) or
 [Primer](https://primer.style/).
@@ -476,7 +474,7 @@ end
 Papercraft.extension(bootstrap: BootstrapComponents)
 ```
 
-The call to `Papercraft.extension` lets us access the different methods of
+The call to `Papercraft::extension` lets us access the different methods of
 `BootstrapComponents` by calling `#bootstrap` inside a template. With this,
 we'll be able to express the above markup as follows:
 

data/lib/papercraft/html.rb

@@ -44,15 +44,53 @@ module Papercraft
       link(**attributes)
     end
 
-    def emit_markdown(markdown, **opts)
-      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
+    # Emits an inline CSS style element.
+    #
+    # @param css [String] CSS code
+    # @param **props [Hash] optional element attributes
+    # @return [void]
+    def style(css, **props, &block)
+      @buffer << '<style'
+      emit_props(props) unless props.empty?
+
+      @buffer << '>' << css << '</style>'
     end
+  
+    # Emits an inline JS script element.
+    #
+    # @param js [String, nil] Javascript code
+    # @param **props [Hash] optional element attributes
+    # @return [void]
+    def script(js = nil, **props, &block)
+      @buffer << '<script'
+      emit_props(props) unless props.empty?
 
-    def kramdown_options(opts)
-      HTML.kramdown_options.merge(**opts)
+      if js
+        @buffer << '>' << js << '</script>'
+      else
+        @buffer << '></script>'
+      end
+    end
+  
+    # Converts and emits the given markdown. Papercraft uses
+    # [Kramdown](https://github.com/gettalong/kramdown/) to do the Markdown to
+    # HTML conversion. Optional Kramdown settings can be provided in order to
+    # control the conversion. Those are merged with the default Kramdown
+    # settings, which can be controlled using
+    # `Papercraft::HTML.kramdown_options`.
+    #
+    # @param markdown [String] Markdown content
+    # @param **opts [Hash] Kramdown options
+    # @return [void]
+    def emit_markdown(markdown, **opts)
+      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
     end
 
     class << self
+      # Returns the default Kramdown options used for converting Markdown to
+      # HTML.
+      #
+      # @return [Hash] Default Kramdown options
       def kramdown_options
         @kramdown_options ||= {
           entity_output: :numeric,
@@ -62,9 +100,24 @@ module Papercraft
         }
       end
 
+      # Sets the default Kramdown options used for converting Markdown to
+      # HTML.
+      #
+      # @param opts [Hash] New deafult Kramdown options
+      # @return [Hash] New default Kramdown options
       def kramdown_options=(opts)
         @kramdown_options = opts
       end
     end
+
+    private
+
+    # Returns the default Kramdown options, merged with the given overrides.
+    # 
+    # @param opts [Hash] Kramdown option overrides
+    # @return [Hash] Merged Kramdown options
+    def kramdown_options(opts)
+      HTML.kramdown_options.merge(**opts)
+    end
   end
 end

data/lib/papercraft/renderer.rb

@@ -34,8 +34,29 @@ module Papercraft
         end
       end
 
-      # Installs the given extensions, mapping a method name to the extension
-      # module.
+      # call_seq:
+      #   Papercraft::Renderer.extension(name => mod, ...)
+      #   Papercraft.extension(name => mod, ...)
+      #
+      # Installs the given extensions, passed in the form of a Ruby hash mapping
+      # methods to extension modules. The methods will be available to all
+      # Papercraft components. Extension methods are executed in the context of
+      # the the renderer instance, so they can look just like normal proc
+      # components. In cases where method names in the module clash with HTML
+      # tag names, you can use the `#tag` method to emit the relevant tag.
+      # 
+      # module ComponentLibrary
+      #   def card(title, content)
+      #     div(class: 'card') {
+      #       h3 title
+      #       div(class: 'card-content') { emit_markdown content }
+      #     }
+      #   end
+      # end
+      #
+      # Papercraft.extension(components: ComponentLibrary)
+      # H { components.card('Foo', '**Bar**') }
+      #
       # @param map [Hash] hash mapping methods to extension modules
       # @return [void]
       def extension(map)
@@ -89,10 +110,12 @@ module Papercraft
       @buffer
     end
 
+    # The tag method template below is optimized for performance. Do not touch!
+
     S_TAG_METHOD_LINE = __LINE__ + 1
     S_TAG_METHOD = <<~EOF
-      S_TAG_%<TAG>s_PRE = '<%<tag>s'.tr('_', '-')
-      S_TAG_%<TAG>s_CLOSE = '</%<tag>s>'.tr('_', '-')
+      S_TAG_%<TAG>s_PRE = %<tag_pre>s
+      S_TAG_%<TAG>s_CLOSE = %<tag_close>s
 
       def %<tag>s(text = nil, **props, &block)
         if text.is_a?(Hash) && props.empty?
@@ -119,6 +142,48 @@ module Papercraft
       end
     EOF
 
+    # Emits an HTML tag with the given content, properties and optional block.
+    # This method is an alternative to emitting HTML tags using dynamically
+    # created methods. This is particularly useful when using extensions that
+    # have method names that clash with HTML tags, such as `button` or `a`, or
+    # when you need to override the behaviour of a particular HTML tag.
+    #
+    # The following two method calls have the same effect:
+    #
+    # button 'text', id: 'button1'
+    # tag :button, 'text', id: 'button1'
+    #
+    # @param sym [Symbol, String] HTML tag
+    # @param text [String, nil] tag content
+    # @param **props [Hash] tag attributes
+    # @param &block [Proc] optional inner HTML
+    # @return [void]
+    def tag(sym, text = nil, **props, &block)
+      if text.is_a?(Hash) && props.empty?
+        props = text
+        text = nil
+      end
+
+      tag = sym.to_s.tr('_', '-')
+
+      @buffer << S_LT << tag
+      emit_props(props) unless props.empty?
+
+      if block
+        @buffer << S_GT
+        instance_eval(&block)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif Proc === text
+        @buffer << S_GT
+        emit(text)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif text
+        @buffer << S_GT << escape_text(text.to_s) << S_LT_SLASH << tag << S_GT
+      else
+        @buffer << S_SLASH_GT
+      end
+    end
+
     # Catches undefined tag method call and handles it by defining the method.
     #
     # @param sym [Symbol] HTML tag or component identifier
@@ -128,7 +193,12 @@ module Papercraft
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
       tag = sym.to_s
-      code = S_TAG_METHOD % { tag: tag, TAG: tag.upcase }
+      code = S_TAG_METHOD % {
+        tag: tag,
+        TAG: tag.upcase,
+        tag_pre: "<#{tag.tr('_', '-')}".inspect,
+        tag_close: "</#{tag.tr('_', '-')}>".inspect
+      }
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
       send(sym, *args, **opts, &block)
     end

data/lib/papercraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Papercraft
-  VERSION = '0.11'
+  VERSION = '0.12'
 end

data/lib/papercraft.rb

@@ -16,6 +16,12 @@ module Papercraft
   # by adding namespaced methods to emplates. An extension is implemented as a
   # Ruby module containing one or more methods. Each method in the extension
   # module can be used to render a specific HTML element or a set of elements.
+  #
+  # This is a convenience method. For more information on using Papercraft
+  # extensions, see `Papercraft::Renderer::extension`
+  #
+  # @param map [Hash] hash mapping methods to extension modules
+  # @return [void]
   def self.extension(map)
     Renderer.extension(map)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.11'
+  version: '0.12'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-04 00:00:00.000000000 Z
+date: 2022-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils