html-native 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec4658fd7a7e2a040535c411ca661cc80291d705b59099c93b6eecd184fb35e
-  data.tar.gz: e96476a674a70ad4e28ba9ab223057bbc3bbdcab00ae91d1ff39c1788e383131
+  metadata.gz: f4e5910254a0afad80152339f40b75051ac6045ab51b95f3a0cfd44c6d9d9c81
+  data.tar.gz: a291bbadcb69cb44f067c7c17c01a39b542f8f9bfaebceb95f1b76731c6bbbef
 SHA512:
-  metadata.gz: 85deca5f040b4268a9b3cf533483f2fbe91de270e5b6dbaf35817cea6363e49e008863481d24eea85c9c18123715caf21cfbe08f2f2c872cd844866ab95c956f
-  data.tar.gz: 7eca06fcf63a3159af0e2de5c4502ad5d969707de4c3f0221df07ca73b9d0b49e224edae049d8c6a5f59c1f390664c56221c9b74bc499ee4e213817c100ac6e6
+  metadata.gz: 27da9d8f7a378e0a2eff7b989fae29f8ab04b000715542f87906ecda76cae0b4dd31a82fd3fab4e3dd50ca64954efd64727ac3d4bdbda13d497d6c3cffcba7d4
+  data.tar.gz: 846abdea65fb7711610a9a22a5b80c85527fc67c34af386924af7b4092bd32e41a0b1587eef4ff26a8d13c1949801dd4e4e18274ba99f8a7b5aea046b06a1658

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

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.0
 platform: ruby
 authors:
 - Kellen Watt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-01-25 00:00:00.000000000 Z
+date: 2021-01-26 00:00:00.000000000 Z
 dependencies: []
 description: An html generation DSL designed for fluid code creation.
 email: