RubyGems - philiprehberger-html_builder - Versions diffs - 0.4.0 → 0.6.0 - Mend

philiprehberger-html_builder 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +10 -0
data/README.md +49 -0
data/lib/philiprehberger/html_builder/builder.rb +44 -0
data/lib/philiprehberger/html_builder/version.rb +1 -1
data/lib/philiprehberger/html_builder.rb +21 -0
metadata +2 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a1603e5f6aca91335bcd511801b9bf397d9dfc1b003f96113991639b5a36133
-  data.tar.gz: 3ec0488c7996705017a7d33cf53a0b1828557b602efbf312d271f5e6b062f99e
+  metadata.gz: 2422583ee49313a76a8eb70b50d6d8de0040b3f8ea9a9e22722013b0ab7537f5
+  data.tar.gz: b61ca71f0b42e279fdd9fa4375b7d67c7c9c8db7a85cc4c6575d5e9ba455b87e
 SHA512:
-  metadata.gz: 7694f0a5189a3f0fb4bfe1eac88edc7ef971ab6d48c21d280eb26d7bbd9d0048728effe37f89c14ec770296def739a12ac2c4d65ecef97502dba9924f3226765
-  data.tar.gz: f156d490b18bf1a1db8010064e0d2fd83887b7928faf24558290844b27189e40aa23132adf8984e9f7481348702df825cd616bba6c4b956884c6c170175c74af
+  metadata.gz: 16b555765bd466535c05261da722bdacd670ee72bae7fc635e09de789a02eed4ad6f9020e17404fcb140e34060e1c1be2c5bfff05674e8c5d3867e4f9c8917ed
+  data.tar.gz: 75d90b85a6a865213dda114f6e3880d1f059a96ebbfbe348ad872b702fd644c5eece3e86bb56bb1237eae573b74c721dcbf004d3377a05503fce95319e200b69

data/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.6.0] - 2026-04-16
+### Added
+- HTML5 `<!DOCTYPE html>` helper via `Builder#doctype` and `HtmlBuilder.document`
+## [0.5.0] - 2026-04-15
+### Added
+- `list(items, ordered: false, **attrs, &block)` helper for building `<ul>` or `<ol>` lists from an array of items with optional custom rendering via block
 ## [0.4.0] - 2026-04-15
 ### Added

data/README.md CHANGED Viewed

@@ -142,6 +142,27 @@ Philiprehberger::HtmlBuilder.build do
 end
 ```
+### Lists
+Build `<ul>` or `<ol>` lists from an array of items. Items are text-escaped by default. Pass `ordered: true` for an ordered list. Use a block for custom rendering of each item:
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  list(%w[Apple Banana Cherry])
+end
+# => '<ul><li>Apple</li><li>Banana</li><li>Cherry</li></ul>'
+Philiprehberger::HtmlBuilder.build do
+  list(%w[First Second], ordered: true, class: 'steps')
+end
+# => '<ol class="steps"><li>First</li><li>Second</li></ol>'
+Philiprehberger::HtmlBuilder.build do
+  list(%w[Alice Bob]) { |name| strong name }
+end
+# => '<ul><li><strong>Alice</strong></li><li><strong>Bob</strong></li></ul>'
+```
 ### CSS Class Helpers
 Build conditional CSS class strings from mixed arguments. Strings are included as-is, hash keys are included when their value is truthy:
@@ -206,6 +227,31 @@ end
 Components without parameters use a simple block with no arguments. Components with parameters receive a hash of locals.
+### HTML5 Documents
+Emit a standards-compliant `<!DOCTYPE html>` declaration via the `doctype` DSL helper, or use `HtmlBuilder.document` for a full HTML5 document shortcut that prefixes the doctype automatically. The block decides the root element, so no hardcoded `<html>` wrapper is added:
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  doctype
+  html { head { title 'Home' } }
+end
+# => '<!DOCTYPE html><html><head><title>Home</title></head></html>'
+Philiprehberger::HtmlBuilder.document do
+  html do
+    head { title 'Home' }
+    body { h1 'Welcome' }
+  end
+end
+# => "<!DOCTYPE html>\n<html><head><title>Home</title></head><body><h1>Welcome</h1></body></html>"
+Philiprehberger::HtmlBuilder.document(pretty: true) do
+  html { head { title 'Home' } }
+end
+# pretty-printed with the doctype on its own line
+```
 ### Output Modes
 Choose between minified and pretty-printed output:
@@ -258,12 +304,14 @@ Philiprehberger::HtmlBuilder.merge(header, body, footer)
 | `HtmlBuilder.build { ... }` | Build minified HTML using the tag DSL, returns a string |
 | `HtmlBuilder.build_pretty { ... }` | Build pretty-printed HTML with indentation |
 | `HtmlBuilder.build_minified { ... }` | Alias for `build`, explicitly produces minified output |
+| `HtmlBuilder.document(pretty:, indent_size:) { ... }` | Build an HTML5 document; prefixes `<!DOCTYPE html>` before the block output |
 | `HtmlBuilder.merge(*fragments)` | Merge multiple HTML fragment strings into one |
 | `HtmlBuilder.escape(value)` | Escape HTML special characters in a string using the DSL's escaper |
 | `Builder#to_html` | Render builder contents to a minified HTML string |
 | `Builder#to_pretty_html` | Render builder contents to a pretty-printed HTML string |
 | `Builder#text(content)` | Add escaped text content to the current element |
 | `Builder#raw(html)` | Add raw HTML without escaping |
+| `Builder#doctype` | Emit an HTML5 `<!DOCTYPE html>` declaration |
 | `Builder#render_if(condition) { ... }` | Conditionally render a block if condition is truthy |
 | `Builder#render_unless(condition) { ... }` | Conditionally render a block if condition is falsy |
 | `Builder#define_component(name) { ... }` | Define a reusable named block |
@@ -274,6 +322,7 @@ Philiprehberger::HtmlBuilder.merge(header, body, footer)
 | `Builder#textarea_field(name, content, label_text:, **attrs)` | Build a label + textarea |
 | `Builder#hidden_field(name, value)` | Generate a hidden input element |
 | `Builder#submit(text, **attrs)` | Generate a submit button (default text "Submit") |
+| `Builder#list(items, ordered:, **attrs, &block)` | Build a `<ul>` or `<ol>` from an array of items |
 | `Builder#class_names(*args)` | Build a conditional CSS class string from strings and hashes |
 | `Builder#cache(key) { ... }` | Cache rendered block output by key; return cached HTML on repeat calls |
 | `Escape.html(value)` | Escape HTML special characters in a string |

data/lib/philiprehberger/html_builder/builder.rb CHANGED Viewed

@@ -80,6 +80,16 @@ module Philiprehberger
         current_children << node
       end
+      # Emit an HTML5 doctype declaration (`<!DOCTYPE html>`)
+      #
+      # Has no children and no attributes. In pretty mode the declaration is
+      # rendered on its own line at the current indentation.
+      #
+      # @return [void]
+      def doctype
+        current_children << DoctypeNode.new
+      end
       # Conditionally render a block if the condition is truthy
       #
       # @param condition [Object] the condition to evaluate
@@ -216,6 +226,26 @@ module Philiprehberger
         button(text, type: 'submit', **attrs)
       end
+      # Build a list (ul or ol) from an array of items
+      #
+      # @param items [Array] the list items
+      # @param ordered [Boolean] use ol instead of ul (default false)
+      # @param attrs [Hash] additional attributes for the list element
+      # @yield [item] optional block for custom rendering of each item
+      # @return [Node]
+      def list(items, ordered: false, **attrs, &block)
+        tag_name = ordered ? :ol : :ul
+        send(tag_name, **attrs) do
+          items.each do |item|
+            if block
+              li { block.call(item) }
+            else
+              li item.to_s
+            end
+          end
+        end
+      end
       # Build a space-joined CSS class string from mixed arguments
       #
       # Strings are included as-is. Hash keys are included when their value is truthy.
@@ -286,5 +316,19 @@ module Philiprehberger
         end
       end
     end
+    # A node that renders the HTML5 doctype declaration
+    class DoctypeNode
+      DECLARATION = '<!DOCTYPE html>'
+      # @return [String] the doctype declaration
+      def to_html(indent: nil, indent_size: 2)
+        if indent
+          "#{' ' * (indent * indent_size)}#{DECLARATION}"
+        else
+          DECLARATION
+        end
+      end
+    end
   end
 end

data/lib/philiprehberger/html_builder/version.rb CHANGED Viewed

@@ -2,6 +2,6 @@
 module Philiprehberger
   module HtmlBuilder
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/html_builder.rb CHANGED Viewed

@@ -45,6 +45,27 @@ module Philiprehberger
       build(&)
     end
+    # Build a full HTML5 document: emits `<!DOCTYPE html>` followed by the
+    # rendered block, separated by a newline.
+    #
+    # The block is evaluated at the root level exactly like `.build` / `.build_pretty`,
+    # so the caller decides whether to add an `<html>` wrapper. When `pretty: true`,
+    # output is pretty-printed with the given indent size.
+    #
+    # @param pretty [Boolean] whether to pretty-print the block output (default false)
+    # @param indent_size [Integer] number of spaces per indent level when pretty (default 2)
+    # @yield [Builder] the builder instance for DSL evaluation
+    # @return [String] the rendered HTML document string
+    # @raise [Error] if no block is given
+    def self.document(pretty: false, indent_size: 2, &block)
+      raise Error, 'a block is required' unless block
+      builder = Builder.new
+      builder.instance_eval(&block)
+      body = pretty ? builder.to_pretty_html(indent_size: indent_size) : builder.to_html
+      "#{DoctypeNode::DECLARATION}\n#{body}"
+    end
     # Merge multiple HTML fragment strings into one
     #
     # @param fragments [Array<String>] HTML fragments to merge

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-html_builder
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies: []
 description: Build HTML programmatically using a clean tag DSL with nested blocks,
   automatic content escaping, void element support, and attribute hashes.