papercraft 0.9 → 0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1f7aa5872a78830c1a5662f055639ae2012b5b9d0f029640dce041f58d1ef4e
-  data.tar.gz: 0c5acc8b14254c63db2132caab42ce003a8ae4713ae6daea7225d0390a420219
+  metadata.gz: be072094c35a6f89327b9c88b90264ad3db61cb43311d0e3baca865f403fdbc5
+  data.tar.gz: 7e565933dd83c48c05bac8c648cbe9b0007bc43f8fc5bd862af46dcd00dfb328
 SHA512:
-  metadata.gz: 02bf1f7bc1300f4fa7871a6942c6a2eae2dd2f8202c7f3cc354171806f82e8a68262c3ca5e2232b7b6dcf6788a33b134b5811641561fa5baba3b7c342643b082
-  data.tar.gz: 97a68a0f854f631a6a36b52a350faae4b1da1e337b27701209c6eec9dc16c62856555fdff3ab3d8f33e144e7fed8dc892b22433f38dd3f951a04010f710b63c4
+  metadata.gz: 9b8da36fb3c7298e8121b9c612cb81752609e1e3d1f01a94e4bf939864b29de718884989203077c5c1392926a54205c921adbcaa1bf3aa75d84694b7b4db4dcc
+  data.tar.gz: 778163311cb86ee425c4617ff54b10e8853d9b92404ef29abac848a4252818386b2e23058c355678c286a5bae3db9d4a7bfb182acb0a4aacf00a042431cc196a

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 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
+
+## 0.10.1 2021-12-25
+
+- Fix tag rendering with empty text in Ruby 3.0
+
+## 0.10 2021-12-25
+
+- Add support for extensions
+
 ## 0.9 2021-12-23
 
 - Add support for emitting Markdown

data/README.md

@@ -1,8 +1,24 @@
-# Papercraft - Composable HTML templating for Ruby
-
-[INSTALL](#installing-papercraft) |
-[TUTORIAL](#getting-started) |
-[DOCS](https://www.rubydoc.info/gems/papercraft)
+<h1 align="center">
+  Papercraft
+</h1>
+
+<h4 align="center">Composable HTML templating for Ruby</h4>
+
+<p align="center">
+  <a href="http://rubygems.org/gems/papercraft">
+    <img src="https://badge.fury.io/rb/papercraft.svg" alt="Ruby gem">
+  </a>
+  <a href="https://github.com/digital-fabric/papercraft/actions?query=workflow%3ATests">
+    <img src="https://github.com/digital-fabric/papercraft/workflows/Tests/badge.svg" alt="Tests">
+  </a>
+  <a href="https://github.com/digital-fabric/papercraft/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
+</p>
 
 ## What is Papercraft?
 
@@ -32,9 +48,7 @@ features:
 - Explicit parameter passing to nested components
 - Higher order components
 - Built-in support for rendering [Markdown](#emitting-markdown)
-
-With Papercraft you can structure your templates as nested HTML components, in a
-somewhat similar fashion to React.
+- Support for namespaced extensions
 
 ## Installing Papercraft
 
@@ -52,43 +66,25 @@ $ gem install papercraft
 
 ## Getting started
 
-To use Papercraft in your code just require it:
+To create a template use the global method `Kernel#H`:
 
 ```ruby
 require 'papercraft'
-```
-
-To create a template use `Papercraft::Component.new` or the global method
-`Kernel#H`:
 
-```ruby
-# can also use Papercraft.new
 html = H {
-  div { p 'hello' }
+  div(id: 'greeter') { p 'Hello!' }
 }
 ```
 
-## Rendering a template
-
-To render a Papercraft template use the `#render` method:
-
-```ruby
-H { span 'best span' }.render  #=> "<span>best span</span>"
-```
-
-The render method accepts an arbitrary context variable:
+Rendering a template is done using `#render`:
 
 ```ruby
-html = H {
-  h1 context[:title]
-}
-
-html.render(title: 'My title') #=> "<h1>My title</h1>"
+html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
 
 ## All about tags
 
-Tags are added using unqualified method calls, and are nested using blocks:
+Tags are added using unqualified method calls, and can be nested using blocks:
 
 ```ruby
 H {
@@ -370,13 +366,131 @@ 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
 ```
 
-## Documentation
+## Deferred evaluation
+
+Deferred evaluation allows deferring the rendering of parts of a template until
+the last moment, thus allowing an inner component to manipulate the state of the
+outer component. To in order to defer a part of a template, use `#defer`, and
+include any markup in the provided block. This technique, in in conjunction with
+holding state in instance variables, is an alternative to passing parameters,
+which can be limiting in some situations.
+
+A few use cases for deferred evaulation come to mind:
+
+- Setting the page title.
+- Adding a flash message to a page.
+- Using components that dynamically add static dependencies (JS and CSS) to the
+  page.
+
+The last use case is particularly interesting. Imagine a `DependencyMananger`
+class that can collect JS and CSS dependencies from the different components
+integrated into the page, and adds them to the page's `<head>` element:
+
+```ruby
+default_layout = H { |**args|
+  @dependencies = DependencyMananger.new
+  head {
+    defer { emit @dependencies.head_markup }
+  }
+  body { emit_yield **args }
+}
+
+button = proc { |text, onclick|
+  @dependencies.js '/static/js/button.js'
+  @dependencies.css '/static/css/button.css'
+
+  button text, onclick: onclick
+}
+
+heading = proc { |text|
+  @dependencies.js '/static/js/heading.js'
+  @dependencies.css '/static/css/heading.css'
+
+  h1 text
+}
+
+page = default_layout.apply {
+  emit heading, "What's your favorite cheese?"
+
+  emit button, 'Beaufort', 'eat_beaufort()'
+  emit button, 'Mont d''or', 'eat_montdor()'
+  emit button, 'Époisses', 'eat_epoisses()'
+}
+```
+
+## Papercraft extensions
+
+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`.
+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/).
+
+For example, to create a Bootstrap card component, the following HTML markup is
+needed (example taken from the [Bootstrap
+docs](https://getbootstrap.com/docs/5.1/components/card/#titles-text-and-links)):
+
+```html
+<div class="card" style="width: 18rem;">
+  <div class="card-body">
+    <h5 class="card-title">Card title</h5>
+    <h6 class="card-subtitle mb-2 text-muted">Card subtitle</h6>
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+    <a href="#" class="card-link">Card link</a>
+    <a href="#" class="card-link">Another link</a>
+  </div>
+</div>
+```
+
+With Papercraft, we could create a `Bootstrap` extension with a `#card` method
+and other associated methods:
+
+```ruby
+module BootstrapComponents
+  ...
+
+  def card(**props)
+    div(class: 'card', **props) {
+      div(class: 'card-body') {
+        emit_yield
+      }
+    }
+  end
+
+  def card_title(title)
+    h5 title, class: 'card-title'
+  end
+
+  ...
+end
+
+Papercraft.extension(bootstrap: BootstrapComponents)
+```
+
+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:
+
+```ruby
+H {
+  bootstrap.card(style: 'width: 18rem') {
+    bootstrap.card_title 'Card title'
+    bootstrap.card_subtitle 'Card subtitle'
+    bootstrap.card_text 'Some quick example text to build on the card title and make up the bulk of the card''s content.'
+    bootstrap.card_link '#', 'Card link'
+    bootstrap.card_link '#', 'Another link'
+  }
+}
+```
+
+## API Reference
 
-The complete documentation for this library can be found
+The API reference for this library can be found
 [here](https://www.rubydoc.info/gems/papercraft).

data/lib/papercraft/extension_proxy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Papercraft
+  
+  # An ExtensionProxy proxies method calls to a renderer. Extension proxies are
+  # used to provide an namespaced interface to Papercraft extensions. When an
+  # extension is installed using `Papercraft.extension`, a corresponding method
+  # is defined on the `Papercraft::Renderer` class that creates an extension
+  # proxy that gives access to the different extension methods.
+  class ExtensionProxy
+
+    # Initializes a new ExtensionProxy.
+    # @param renderer [Papercraft::Renderer] renderer to proxy to
+    # @param mod [Module] extension module
+    # @return [void]
+    def initialize(renderer, mod)
+      @renderer = renderer
+      extend(mod)
+    end
+  
+    # Proxies missing methods to the renderer
+    # @param sym [Symbol] method name
+    # @param *args [Array] arguments
+    # @param &block [Proc] block
+    # @return void
+    def method_missing(sym, *args, &block)
+      @renderer.send(sym, *args, &block)
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative './html'
+require_relative './extension_proxy'
 
 module Papercraft
   
@@ -31,15 +32,60 @@ module Papercraft
         if param_count > args.size
           raise Papercraft::Error, "Missing template parameters"
         end
-      end  
+      end
+
+      # 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)
+        map.each do |sym, mod|
+          define_extension_method(sym, mod)
+        end
+      end
+
+      private
+
+      # Defines a method returning an extension proxy for the given module
+      # @param sym [Symbol] method name
+      # @param mod [Module] extension module
+      # @return [void]
+      def define_extension_method(sym, mod)
+        define_method(sym) do
+          (@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
+        end
+      end
     end
 
+    INITIAL_BUFFER_CAPACITY = 8192
+
     # Initializes the renderer and evaulates the given template in the
     # renderer's scope.
     #
     # @param &template [Proc] template block
     def initialize(&template)
-      @buffer = +''
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
       instance_eval(&template)
     end
 
@@ -47,15 +93,36 @@ module Papercraft
     #
     # @return [String]
     def to_s
+      if @parts
+        last = @buffer
+        @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+        parts = @parts
+        @parts = nil
+        parts.each do |p|
+          if Proc === p
+            render_deferred_proc(&p)
+          else
+            @buffer << p
+          end
+        end
+        @buffer << last unless last.empty?
+      end
       @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?
+          props = text
+          text = nil
+        end
+
         @buffer << S_TAG_%<TAG>s_PRE
         emit_props(props) unless props.empty?
 
@@ -75,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
@@ -83,11 +192,13 @@ module Papercraft
     # @param &block [Proc] block passed to method
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
-      value = @local && @local[sym]
-      return value if value
-
       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
@@ -135,6 +246,42 @@ module Papercraft
       
       instance_exec(*a, **b, &@inner_block)
     end
+
+    # Defers the given block to be evaluated later. Deferred evaluation allows
+    # Papercraft components to inject state into sibling components, regardless
+    # of the component's order in the container component. For example, a nested
+    # component may set an instance variable used by another component. This is
+    # an elegant solution to the problem of setting the HTML page's title, or
+    # adding elements to the `<head>` section. Here's how a title can be
+    # controlled from a nested component:
+    #
+    #   layout = H {
+    #     html {
+    #       head {
+    #         defer { title @title }
+    #       }
+    #       body {
+    #         emit_yield
+    #       }
+    #     }
+    #   }
+    #
+    #   html.render {
+    #     @title = 'My super page'
+    #     h1 'content'
+    #   }
+    #
+    # @param &block [Proc] Deferred block to be emitted
+    # @return [void]
+    def defer(&block)
+      if !@parts
+        @parts = [@buffer, block]
+      else
+        @parts << @buffer unless @buffer.empty?
+        @parts << block
+      end
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+    end
     
     S_LT              = '<'
     S_GT              = '>'
@@ -192,6 +339,23 @@ module Papercraft
         end
       }
     end
+
+    # Renders a deferred proc by evaluating it, then adding the rendered result
+    # to the buffer.
+    #
+    # @param &block [Proc] deferred proc
+    # @return [void]
+    def render_deferred_proc(&block)
+      old_buffer = @buffer
+      
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+      @parts = nil
+
+      instance_eval(&block)
+
+      old_buffer << to_s
+      @buffer = old_buffer
+    end
   end
 
   # Implements an HTML renderer
@@ -200,6 +364,7 @@ module Papercraft
 
     private
 
+    # Escapes the given text using HTML entities.
     def escape_text(text)
       EscapeUtils.escape_html(text.to_s)
     end
@@ -209,6 +374,7 @@ module Papercraft
   class XMLRenderer < Renderer
     private
 
+    # Escapes the given text using XML entities.
     def escape_text(text)
       EscapeUtils.escape_xml(text.to_s)
     end

data/lib/papercraft/version.rb

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

data/lib/papercraft.rb

@@ -11,6 +11,20 @@ require_relative 'papercraft/encoding'
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
+
+  # Installs one or more extensions. Extensions enhance templating capabilities
+  # 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
 end
 
 # Kernel extensions

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: '0.12'
 platform: ruby
 authors:
 - Sharon Rosner
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-23 00:00:00.000000000 Z
+date: 2022-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -122,7 +122,7 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 2.0.9
-description: 
+description:
 email: sharon@noteflakes.com
 executables: []
 extensions: []
@@ -135,6 +135,7 @@ files:
 - lib/papercraft/compiler.rb
 - lib/papercraft/component.rb
 - lib/papercraft/encoding.rb
+- lib/papercraft/extension_proxy.rb
 - lib/papercraft/html.rb
 - lib/papercraft/renderer.rb
 - lib/papercraft/version.rb
@@ -146,7 +147,7 @@ metadata:
   documentation_uri: https://www.rubydoc.info/gems/papercraft
   homepage_uri: https://github.com/digital-fabric/papercraft
   changelog_uri: https://github.com/digital-fabric/papercraft/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options:
 - "--title"
 - Papercraft
@@ -165,8 +166,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.3
+signing_key:
 specification_version: 4
 summary: 'Papercraft: component-based HTML templating for Ruby'
 test_files: []