html-native 0.1.0 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec4658fd7a7e2a040535c411ca661cc80291d705b59099c93b6eecd184fb35e
-  data.tar.gz: e96476a674a70ad4e28ba9ab223057bbc3bbdcab00ae91d1ff39c1788e383131
+  metadata.gz: 10608cfe99deda77bf919d12ed385dff6364260d596fbb672968c6ed708ca320
+  data.tar.gz: 511d614f09a21a27506d25289a0f31f36d92864d1235eb2cc26f4c5008ac0aa8
 SHA512:
-  metadata.gz: 85deca5f040b4268a9b3cf533483f2fbe91de270e5b6dbaf35817cea6363e49e008863481d24eea85c9c18123715caf21cfbe08f2f2c872cd844866ab95c956f
-  data.tar.gz: 7eca06fcf63a3159af0e2de5c4502ad5d969707de4c3f0221df07ca73b9d0b49e224edae049d8c6a5f59c1f390664c56221c9b74bc499ee4e213817c100ac6e6
+  metadata.gz: 476f3e92ab73de39f6d05bf96fca229237e44de9e140f25f012e3556a04f61500dc85b8a5c216a1c799bf7db1b8cc14514f8ab65e48563813b6d98792b0964e2
+  data.tar.gz: 804e56ce1f00a988bc5a590d13351ccd11175d1a7c7be64d7076a4c653ed8a868fb3bd0955da6251f32af161dfeabc3466930b2f8a4bdddc352ea88f1f3b60f6

data/lib/html-native.rb

@@ -3,13 +3,6 @@ require "html-native/builder"
 
 module HTMLComponent
  
-  # Excluded currently because it makes checking in `Builder` ugly
-  # Makes `include` and `extend` work exactly the same.
-  # It's a dirty hack based on laziness, and strict use of `extend` is preferred.
-  # def self.included(base)
-  #   base.extend(self)
-  # end
-
   # Generates generation methods for each HTML5-valid tag. These methods have the 
   # name of the tag. Note that this interferes with the builtin `p` method.
   TAG_LIST.each do |tag|
@@ -24,6 +17,10 @@ module HTMLComponent
     end
   end
 
+  # Creates a module that encompasses the given block in an HTMLComponent
+  # context. This gives access to methods in the block as though the block was 
+  # declared as the `render` function in a module extending HTMLComponent 
+  # (pretty much because it is).
   def self.singleton(&block)
     Module.new do
       extend HTMLComponent
@@ -55,6 +52,6 @@ module HTMLComponent
         "#{k}=\"#{v}\"" # render this appropriately for numeric fields (might already)
       end
     end.join(" ")
-    formatted.empty? ? "" : " " + formatted
+    formatted.prepend(" ") unless formatted.empty?
   end
 end

data/lib/html-native/builder.rb

@@ -1,14 +1,29 @@
 require "html-native"
 module HTMLComponent
+  # Represents a String being constructed, and can be more or less treated 
+  # as a String. Builder creates a String from whatever is put into it, but 
+  # it delays construction until it's absolutely necessary, then it caches the
+  # result.
   class Builder
+    # Build a new string builder instance, immediately constructing and caching 
+    # the initial value.
     def initialize(strings = [])
-      if strings.kind_of? String 
-        @strings = [strings]
+      @strings = []
+      @cache = case strings.class 
+      when Array
+        strings.join
+      when Enumerable
+        strings.to_a.join
       else
-        @strings = strings.dup
+        strings.to_s
       end
+      @cached = true
     end
 
+    # Appends a value to the Builder instance. If it is another builder, it is 
+    # added, but not converted to a String yet. If it is an HTMLComponent, it is 
+    # rendered. If it is anything else, it is converted to a String. This 
+    # invalidates the cache.
     def +(string)
       if string.kind_of? Builder 
         @strings << string
@@ -17,11 +32,49 @@ module HTMLComponent
       else
         @strings << string.to_s
       end
+      @cached = false
       self
     end
 
+    alias_method :<<, :+
+
+    # Same as +, but allows multiple values to be appended. 
+    def concat(*strings)
+      strings.each do |s|
+        self + s
+      end
+      self
+    end
+
+    # Converts the Builder to a String. If the cache is valid, it is returned. 
+    # Otherwise, the new result is created, cached, and returned.
     def to_s
-      @strings.join
+      unless @cached
+        @cache << @strings.join
+        @strings.clear
+        @cached = true
+      end
+      @cache
     end
+
+    alias_method :to_str, :to_s
+
+    # If the method does not exist on Builder, it is sent to String, by way 
+    # of the rendered Builder result. Modify-in-place methods will affect the 
+    # underlying String.
+    def method_missing(method, *args, &block)
+      to_s.send(method, *args, &block)
+    end
+    
+    # If String responds to the method, then Builder also responds to it.
+    def respond_to_missing?(method, include_all)
+      "".respond_to?(method, include_all)
+    end
+  end
+end
+
+class String
+  def component
+    HTMLComponent::Builder.new(self)
   end
 end

data/lib/html-native/collections.rb

@@ -2,6 +2,11 @@ require "html-native"
 require "html-native/builder"
 
 module Enumerable
+  # Maps the given block to each element of *enum*. The result of each iteration
+  # is added to an HTMLComponent::Builder instance, which is returned after the
+  # final iteration.
+  #
+  # If no block is given, an enumerator is returned instead.
   def component_map 
     if block_given?
       result = HTMLComponent::Builder.new
@@ -14,134 +19,276 @@ module Enumerable
     end
   end
 
+  # Returns an OrderedListComponent representing the *enum*.
+  # 
+  # See OrderedListComponent#new for details on how to apply attributes.
   def to_ol(attributes: {})
     OrderedListComponent.new(self, attributes: attributes)
   end
   
+  # Returns an UnorderedListComponent representing the *enum*.
+  # 
+  # See UnorderedListComponent#new for details on how to apply attributes.
   def to_ul(attributes: {})
     UnorderedListComponent.new(self, attributes: attributes)
   end
 end
 
+# OrderedListComponent represents an HTML ordered list based on an Enumerable
+# collection.
+#
+# Attributes in an OrderedListComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - list - The attributes associated with the <ol> element
+# - item - The attributes associated with <li> elements
+#
+# For example, to have a list with 20px padding and the class of "list-item" 
+# given to each item, you could write:
+# ```
+# OrderedListComponent.new(data, attributes: 
+#   {list: {style: "padding: 20px"}, item: {class: "list-item"}})
+#
+# ```
+# which is equivalent to
+# ```
+# <ol style="padding: 20px">
+#   <li class="list-item">...</li>
+#   <li class="list-item">...</li>
+#   ...
+# </ol>
+# ```
 class OrderedListComponent
   include HTMLComponent
 
-  def initialize(data, attributes: {})
+  # Creates a new instance of OrderedListComponent from the values of *data*.
+  #
+  # If a block is given, each item in *data* is passed to it to render the list
+  # items. If no block is given, *data* are used directly.
+  def initialize(data, attributes: {}, &block)
     @list_data = data
     @list_attributes = attributes[:list] || {}
     @item_attributes = attributes[:item] || {}
+    @block = block
   end
 
-  def render(&block)
+  # Converts the OrderedListComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
     ol(@list_attributes) do
       @list_data.component_map do |l|
         li(@item_attributes) do
-          block_given? ? yield(l) : l.to_s
+          @block ? @block.call(l) : l
         end
       end
     end
   end
 end
 
+# UnorderedListComponent represents an HTML unordered list generated from an 
+# Enumerable collection.
+#
+# Attributes in an UnorderedListComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - list - The attributes associated with the <ul> element
+# - item - The attributes associated with <li> elements
+#
+# For example, to have a list with 20px padding and the class of "list-item" 
+# given to each item, you could write:
+# ```
+# UnorderedListComponent.new(data, attributes: 
+#   {list: {style: "padding: 20px"}, item: {class: "list-item"}})
+#
+# ```
+# which is equivalent to
+# ```
+# <ul style="padding: 20px">
+#   <li class="list-item">...</li>
+#   <li class="list-item">...</li>
+#   ...
+# </ul>
+# ```
 class UnorderedListComponent
   include HTMLComponent
 
-  def initialize(data, attributes: {})
+  # Creates a new instance of UnorderedListComponent from the values of *data*.
+  #
+  # If a block is given, each item in *data* is passed to it to render the list
+  # items. If no block is given, *data* are used directly.
+  def initialize(data, attributes: {}, &block)
     @list_data = data
     @list_attributes = attributes[:list] || {}
     @item_attributes = attributes[:item] || {}
+    @block = block
   end
 
-  def render(&block)
+  # Converts the UnorderedListComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
     ul(@list_attributes) do
       @list_data.component_map do |l|
         li(@item_attributes) do
-          block_given? ? yield(l) : l.to_s
+          @block ? @block.call(l) : l
         end
       end
     end
   end
 end
 
+# ListComponent represents an HTML list based on an Enumerable collection.
+#
+# Attributes in an ListComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - list - The attributes associated with the <ul> element
+# - item - The attributes associated with <li> elements
+#
+# For example, to have an ordered list with 20px padding and the class of 
+# "list-item" given to each item, you could write:
+# ```
+# ListComponent.new(data, ordered: true, attributes: 
+#   {list: {style: "padding: 20px"}, item: {class: "list-item"}})
+#
+# ```
+# which is equivalent to
+# ```
+# <ol style="padding: 20px">
+#   <li class="list-item">...</li>
+#   <li class="list-item">...</li>
+#   ...
+# </ol>
+# ```
 class ListComponent
-  def initialize(data, attributes: {}, ordered: false)
-    @list = ordered ? OrderedListComponent.new(data, attributes) : 
-                      UnorderedListComponent.new(data, attributes)
+  # Creates a new instance of ListComponent from the values of *data*.
+  # 
+  # This list can be either ordered or unordered, depending on *ordered* parameter.
+  # If *ordered* is true, the list will be ordered, otherwise it will be unordered.
+  # *ordered* is false by default.
+  #
+  # If a block is given, each item in *data* is passed to it to render the list
+  # items. If no block is given, *data* are used directly.
+  def initialize(data, attributes: {}, ordered: false, &block)
+    @list = ordered ? OrderedListComponent.new(data, attributes, &block) : 
+                      UnorderedListComponent.new(data, attributes, &block)
   end
 
-  def render(&block)
-    @list.render(&block)
+  # Converts the ListComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
+    @list.render
   end
 end
 
+# TableRowComponent represents an HTML table row generated from an 
+# Enumerable collection.
+#
+# Attributes in an TableRowComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - row - The attributes associated with the <tr> element
+# - cell - The attributes associated with <td> elements
+#
+# For example, to have a row with 20px padding and the class of "table-cell" 
+# given to each cell, you could write:
+# ```
+# TableRowComponent.new(data, attributes: 
+#   {row: {style: "padding: 20px"}, cell: {class: "list-item"}})
+#
+# ```
+# which is equivalent to
+# ```
+# <tr style="padding: 20px">
+#   <td class="list-item">...</td>
+#   <td class="list-item">...</td>
+#   ...
+# </tr>
+# ```
 class TableRowComponent
   include HTMLComponent
 
-  def initialize(data, attributes: {})
+  # Creates a new instance of TableRowComponent from the values of *data*.
+  #
+  # If a block is given, each item in *data* is passed to it to render the row
+  # cells. If no block is given, *data* are used directly.
+  def initialize(data, attributes: {}, &block)
     @data = data
     @row_attributes = attributes[:row] || {}
     @cell_attributes = attributes[:cell] || {}
+    @block = block
   end
 
-  def render(&block)
+  # Converts the TableRowComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
     tr(@row_attributes) do
       @data.component_map do |c|
-        td(@cell_attributes) {block_given? ? yield(c) : c}
+        td(@cell_attributes) {@block ? @block.call(c) : c}
       end
     end
   end
 end
 
-# This needs some reworking, since it's not intuitive
+# TableComponent represents an HTML table generated from an Enumerable 
+# collection.
+#
+# Attributes in an TableComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - table - The attributes associated with the <table> element.
+# - header - The attributes associated with <tr> element representing the header.
+# - header_cell - The attributes associated with <th> elements.
+# - row - The attributes associated with all <tr> elements, including the header.
+# - cell - The attributes associated with <td> and <th> elements.
+#
+# Refer to other components for the format for applying attributes.
 class TableComponent
   include HTMLComponent
 
-  def initialize(header, rows, attributes: {})
-    @header = header
-    @rows = rows
+  # Creates a new instance of TableComponent from the values of *rows*.
+  #
+  # *rows* is an Enumerable collection of Enumerable objects.
+  #
+  # If a block is given, each item in *rows* is passed to it to render the table
+  # cells, not including the header. If no block is given, *rows* is used directly.
+  def initialize(rows, col_names: [], row_names: [], attributes: {}, &block)
+    @rows = rows.map(&:to_a)
+    @header = col_names.to_a
+    row_names = row_names.to_a
+    unless row_names.empty?
+      row_names.each_with_index do |name, i|
+        if i < @rows.size
+          @rows[i].prepend(name) 
+        else
+          @rows << [name]
+        end
+      end
+    end
+    @header.prepend("") unless row_names.empty? || @header.empty?
+
     @table_attributes = attributes[:table] || {}
     @header_attributes = attributes[:header] || {}
     @header_cell_attributes = attributes[:header_cell] || {}
     @row_attributes = attributes[:row] || {}
     @cell_attributes = attributes[:cell] || {}
+    @block = block
   end
 
-  # header options:
-  # array - use as header
-  # symbol - if :from_data, then use first row, if :none, set @header to nil
-  def self.from_array(data, attributes: {}, header: :none)
-    head = rows = nil
-    if header == :from_data
-      head = data[0]
-      rows = data[1..]
-    else
-      head = header.kind_of?(Array) ? header : nil
-      rows = data
-    end
-    new(head, rows, attributes: attributes)
-  end
-
-  def self.from_hash(data, attributes: {}, vertical: true)
-    if vertical
-      rowcount = data.values.map(&:length).max
-      rows = [] * rowcount
-      data.each do |k,col|
-        rowcount.times do |i|
-          rows[i] << (i < col.size ? col[i] : nil)
-        end
-      end
-      new(data.keys, rows, attributes: attributes)
-    else
-      rows = data.map do |k, v|
-        [k] + v
-      end
-      new(nil, rows, attributes: attributes)
-    end
-  end
-
-  def render(&block)
+  # Converts the TableComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
     table(@table_attributes) do
-      if @header
+      unless @header.empty?
         tr(@row_attributes.merge(@header_attributes)) do
           @header.component_map do |h|
             th(@cell_attributes.merge(@header_cell_attributes)) {h}
@@ -151,47 +298,87 @@ class TableComponent
         Builder.new
       end +
       @rows.component_map do |row|
-        TableRowComponent.new(row, attributes: {row: @row_attributes, cell: @cell_attributes}).render(&block)
+        attributes = {row: @row_attributes, cell: @cell_attributes}
+        TableRowComponent.new(row, attributes: attributes, &@block)
       end
     end
   end
 end
 
+# DropdownComponent represents an HTML table row generated from an 
+# Enumerable collection.
+#
+# Attributes in an DropdownComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - menu - The attributes associated with the <select> element
+# - item - The attributes associated with <option> elements
 class DropdownComponent
   include HTMLComponent
 
-  def initialize(choices, name, attributes: {})
+  # Creates a new instance of DropdownComponent from the values of *choices*.
+  #
+  # If a block is given, each item in *choices* is passed to it to render the
+  # item. If no block is given, *choices* is used directly.
+  def initialize(choices, name, attributes: {}, &block)
     @choices = choices
     @name = name
     @menu_attributes = attributes[:menu]
     @item_attributes = attributes[:item]
+    @block = block
   end
 
-  def render(&block)
+  # Converts the DropdownComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
     select(@menu_attributes.merge({name: @name, id: "#{@name}-dropdown"})) do
       @choices.component_map do |c|
-        option(@item_attributes.merge({value: c})) {block_given? ? yield(c) : c}
+        option(@item_attributes.merge({value: c})) {@block ? @block.call(c) : c}
       end
     end
   end
 end
 
+# RadioGroupComponent represents an HTML radio button group generated from an 
+# Enumerable collection.
+#
+# Each item has a unique id of the form of `"#{name}-{choice}"`, where name is 
+# the provided *name* option, and choice is value of that button. 
+#
+# Each item produces a button and a label.
+#
+# Attributes in an RadioGroupComponent are separated into multiple groups since
+# there are multiple kinds of tags. These groups are:
+# - button - The attributes associated with the <input type: "radio"> elements.
+# - label - The attributes associated with <label> elements.
 class RadioGroupComponent
   include HTMLComponent
 
-  def initialize(choices, name, attributes: {}, labelled: true)
+  # Creates a new instance of RadioGroupComponent from the values of *choices*.
+  #
+  # If a block is given, each item in *choices* is passed to it to render the
+  # label. If no block is given, *choices* is used directly.
+  def initialize(choices, name, attributes: {}, labelled: true, &block)
     @choices = choices
     @name = name
     @button_attributes = attributes[:button]
     @label_attributes = attributes[:label]
     @labelled = labelled
+    @block = block
   end
 
-  def render(&block)
+  # Converts the RadioGroupComponent instance to the equivalent HTML. 
+  #
+  # *render* can be called directly, but that usually isn't necessary.
+  # HTMLComponent::Builder handles this automatically, so it only needs to be 
+  # done if there is no prior instance of one.
+  def render
     @choices.component_map do |c|
       id = "#{@name}-#{c}" 
       input({type: "radio", id: id, name: @name, value: c}) +
-        (@labelled ? (label({for: id}) {block_given? ? yield(c) : c}) : nil)
+        (@labelled ? (label({for: id}) {@block ? @block.call(c) : c}) : nil)
     end
   end
 end

data/lib/html-native/constants.rb

@@ -1,4 +1,6 @@
 module HTMLComponent
+  # A list of all valid HTML5 elements. These are used to generate generator 
+  # methods within HTMLComponent contexts.
   TAG_LIST = [
     :html, 
     :base, :head, :link, :meta, :style, :title,
@@ -19,12 +21,12 @@ module HTMLComponent
         :option, :output, :progress, :select, :textarea,
     :details, :dialog, :menu, :summary,
     :slot, :template
-  ] + (1..6).map{|i| :"h#{i}"}
-
-  def self.tags
-    TAG_LIST.dup
-  end
+  ]
 
+  # A list of all limited attributes in HTML5. Any attribute not listed here are 
+  # free to use in any element, as long as it is not in FORBIDDEN_ATTRIBUTES.
+  #
+  # Any attributes listed here will only be allowed in the associated elements.
   LIMITED_ATTRIBUTES = {
     accept: [:form, :input],
     "accept-charset": [:form],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: html-native
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.4
 platform: ruby
 authors:
 - Kellen Watt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-01-25 00:00:00.000000000 Z
+date: 2021-02-01 00:00:00.000000000 Z
 dependencies: []
 description: An html generation DSL designed for fluid code creation.
 email: