RubyGems - philiprehberger-html_builder - Versions diffs - 0.5.0 → 0.7.0 - Mend

philiprehberger-html_builder 0.5.0 → 0.7.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 +11 -0
data/README.md +51 -0
data/lib/philiprehberger/html_builder/builder.rb +67 -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: c951cd5a9e74ab6642a9181b01235a4a5a63b39015fd05cf5c41ab0157bc6106
-  data.tar.gz: ab129d21a86612912a83f460cd49424b4005ac95fe6f7c8c6471f3f5309a6640
+  metadata.gz: 9a1ed5d63b82c40002240f74e0f808a5e62926efd8b55a0c52b482d804a23bab
+  data.tar.gz: 814fd3cf20cf2cf358f25e38d14dcf9f02e84e32827a584c0c94a947d4404f48
 SHA512:
-  metadata.gz: c6ceba75c99ca6620ba8434521b02703cb42d0113f662fe0789928dec1b1e38f4e3057c4fd44495eefd30bd53d08127d6b95daa470e4d67bf15ed56f61e085a9
-  data.tar.gz: c70fd51be8e402a223a7a1114a0f0950dd66267f2cf20506a1437a32905ba3185634a980fa314fd9785c985600a947890e05768b35dccdaabdbb40a395cb0191
+  metadata.gz: 0e0214af812ff0754349ee79c494f544f34b6b5a16852387d3c51c30b1580c7e88f75d0392f4761dacf754c91722cc83015f95131f065c60eaa073df64453217
+  data.tar.gz: eb761b219b3a40319752ba84628ed2a7a88f0ea423581619a641a98932a3c39f8deabb83edb077be8c0319436d60f7ccac2f53f5acaa6e63cb5d469e4d04b271

data/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.7.0] - 2026-04-26
+### Added
+- `merge_attrs(*hashes)` helper for merging attribute hashes; concatenates `:class` (space-separated) and `:style` (semicolon-separated) values rather than overwriting
+- `aria(**pairs)` helper for building ARIA attribute hashes from snake_case keyword pairs (converted to `aria-kebab-case` string keys; nil values omitted)
+## [0.6.0] - 2026-04-16
+### Added
+- HTML5 `<!DOCTYPE html>` helper via `Builder#doctype` and `HtmlBuilder.document`
 ## [0.5.0] - 2026-04-15
 ### Added

data/README.md CHANGED Viewed

@@ -163,6 +163,28 @@ end
 # => '<ul><li><strong>Alice</strong></li><li><strong>Bob</strong></li></ul>'
 ```
+### Attribute Helpers
+Merge multiple attribute hashes — concatenating `:class` (single space) and `:style` (`'; '`) values rather than overwriting — and build ARIA attribute hashes from snake_case keyword pairs:
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  base = { class: 'btn', style: 'color: red' }
+  variant = { class: 'btn-primary', style: 'font-weight: bold' }
+  attrs = merge_attrs(base, variant)
+  button('Save', **attrs)
+end
+# => '<button class="btn btn-primary" style="color: red; font-weight: bold">Save</button>'
+Philiprehberger::HtmlBuilder.build do
+  aria(label: 'Save', expanded: false, describedby: nil)
+end
+# => { 'aria-label' => 'Save', 'aria-expanded' => 'false' }
+```
+`merge_attrs` joins `:class` values with a single space and `:style` values with `'; '`. Other keys follow last-write-wins, and input hashes are not mutated. `aria` converts snake_case keys to `aria-kebab-case` string keys, stringifies values, and omits keys whose value is `nil`.
 ### 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:
@@ -227,6 +249,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:
@@ -279,12 +326,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 |
@@ -297,6 +346,8 @@ Philiprehberger::HtmlBuilder.merge(header, body, footer)
 | `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#merge_attrs(*hashes)` | Merge attribute hashes, concatenating `:class` (space) and `:style` (`'; '`) values |
+| `Builder#aria(**pairs)` | Build an ARIA attribute hash from snake_case keys (rendered as `aria-kebab-case`); omits nil values |
 | `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
@@ -255,6 +265,49 @@ module Philiprehberger
         result.join(' ')
       end
+      # Merge multiple attribute hashes into one
+      #
+      # `:class` values are concatenated with a single space, and `:style` values
+      # are concatenated with a semicolon and space. All other keys follow last-write-wins
+      # semantics. Input hashes are not mutated.
+      #
+      # @param hashes [Array<Hash>] one or more attribute hashes to merge
+      # @return [Hash] the merged attribute hash
+      def merge_attrs(*hashes)
+        result = {}
+        hashes.each do |h|
+          next if h.nil?
+          h.each do |key, value|
+            if key == :class && result.key?(:class)
+              result[:class] = "#{result[:class]} #{value}"
+            elsif key == :style && result.key?(:style)
+              result[:style] = "#{result[:style]}; #{value}"
+            else
+              result[key] = value
+            end
+          end
+        end
+        result
+      end
+      # Build an ARIA attribute hash from keyword pairs
+      #
+      # snake_case keys are converted to `aria-kebab-case` string keys. Values are
+      # converted to strings. Keys whose value is `nil` are omitted from the result.
+      #
+      # @param pairs [Hash] keyword pairs to convert into ARIA attributes
+      # @return [Hash<String, String>] hash with `"aria-*"` string keys and string values
+      def aria(**pairs)
+        result = {}
+        pairs.each do |key, value|
+          next if value.nil?
+          result["aria-#{key.to_s.tr('_', '-')}"] = value.to_s
+        end
+        result
+      end
       # Cache a rendered block result by key
       #
       # On the first call with a given key, the block is executed, its rendered
@@ -306,5 +359,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.5.0'
+    VERSION = '0.7.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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-04-27 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.