philiprehberger-html_builder 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2422583ee49313a76a8eb70b50d6d8de0040b3f8ea9a9e22722013b0ab7537f5
-  data.tar.gz: b61ca71f0b42e279fdd9fa4375b7d67c7c9c8db7a85cc4c6575d5e9ba455b87e
+  metadata.gz: ae55b58a30868dfa5bc7afd1f3300723c88c8f05e97470571a02619e07dd3dfd
+  data.tar.gz: 39f947b3d37ac2a914da3fa42f99dd9a3fddd9d43b09498d548b03eae269b694
 SHA512:
-  metadata.gz: 16b555765bd466535c05261da722bdacd670ee72bae7fc635e09de789a02eed4ad6f9020e17404fcb140e34060e1c1be2c5bfff05674e8c5d3867e4f9c8917ed
-  data.tar.gz: 75d90b85a6a865213dda114f6e3880d1f059a96ebbfbe348ad872b702fd644c5eece3e86bb56bb1237eae573b74c721dcbf004d3377a05503fce95319e200b69
+  metadata.gz: e4147ae709bc12f9c0d422169e2a8183bc90a92d3ae9b19cda6c62ad7fa927923b436d0a68f1c496eee6de843d9585a26a60786fee3611c3bcf8c765cf0365bd
+  data.tar.gz: 37cbec88f3da3293458bdbd8c42270c44d7f6f1b6f1e4b7052154968df53de570f9921dd27f9dde0a4221c56cf1ade5902168c2b98bd7af1f32327134b0b08f2

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-05-20
+
+### Added
+- `Builder#capture { ... }` — render a block in an isolated scope and return the HTML as a string without appending to the current document. Inherits previously defined components, so component reuse works inside captured fragments. Pairs naturally with `Builder#raw` for inserting the captured HTML into the document.
+- Card image reference in the README for registry-side rendering
+
+## [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

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-html_builder.svg)](https://rubygems.org/gems/philiprehberger-html_builder)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-html-builder)](https://github.com/philiprehberger/rb-html-builder/commits/main)
 
+![philiprehberger-html_builder](https://raw.githubusercontent.com/philiprehberger/rb-html-builder/main/package-card.webp)
+
 Programmatic HTML builder with tag DSL, auto-escaping, form helpers, components, and output formatting
 
 ## Requirements
@@ -163,6 +165,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:
@@ -176,6 +200,25 @@ end
 # => <div class="btn btn-lg active">Click me</div>
 ```
 
+### Capturing Fragments
+
+Render a block in a separate scope and capture the HTML as a string instead of appending it to the document. Useful when the same fragment is needed in more than one place or as a value:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  badge = capture { strong 'NEW', class: 'badge' }
+  article do
+    h2 'Headline'
+    raw badge
+    p 'Body text'
+    raw badge
+  end
+end
+# => <article><h2>Headline</h2><strong class="badge">NEW</strong><p>Body text</p><strong class="badge">NEW</strong></article>
+```
+
+`capture` inherits any components defined on the parent builder, so component reuse works inside captured fragments.
+
 ### Fragment Caching
 
 Cache rendered block results by key. On subsequent calls with the same key, the cached HTML is returned without re-executing the block:
@@ -324,7 +367,10 @@ 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 |
+| `Builder#capture { ... }` | Render the block in an isolated scope and return its HTML string (no append) |
 | `Escape.html(value)` | Escape HTML special characters in a string |
 
 ## Development

data/lib/philiprehberger/html_builder/builder.rb

@@ -265,6 +265,71 @@ 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
+
+      # Render a block in an isolated builder scope and return the HTML string
+      # without appending anything to the current document.
+      #
+      # Useful for template helpers that need to compute a fragment once and
+      # then insert it in multiple places (e.g. via {#raw}) or pass it as a
+      # string attribute (e.g. ``title:`` containing a small piece of escaped
+      # markup) — none of which can be expressed with the regular tag DSL
+      # because every tag method side-effects into the current scope.
+      #
+      # @yield block evaluated against a fresh builder; the same DSL methods
+      #   (tags, `text`, `raw`, components, etc.) are available
+      # @return [String] the captured HTML (minified)
+      # @raise [Error] if no block is given
+      def capture(&block)
+        raise Error, 'a block is required for capture' unless block
+
+        nested = Builder.new
+        @components.each { |name, b| nested.instance_variable_get(:@components)[name] = b }
+        nested.instance_eval(&block)
+        nested.to_html
+      end
+
       # Cache a rendered block result by key
       #
       # On the first call with a given key, the block is executed, its rendered

data/lib/philiprehberger/html_builder/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-html_builder
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-05-20 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.