philiprehberger-html_builder 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a1ed5d63b82c40002240f74e0f808a5e62926efd8b55a0c52b482d804a23bab
-  data.tar.gz: 814fd3cf20cf2cf358f25e38d14dcf9f02e84e32827a584c0c94a947d4404f48
+  metadata.gz: 56b6f4a4c8e09045d724f5f67b3f8cec1e87fc2daddd397e04604cf13bcd33d8
+  data.tar.gz: 1b820c958ea1cafe11fa4aa415fb76b17aebef39aa611b6f100dedcdf01f2411
 SHA512:
-  metadata.gz: 0e0214af812ff0754349ee79c494f544f34b6b5a16852387d3c51c30b1580c7e88f75d0392f4761dacf754c91722cc83015f95131f065c60eaa073df64453217
-  data.tar.gz: eb761b219b3a40319752ba84628ed2a7a88f0ea423581619a641a98932a3c39f8deabb83edb077be8c0319436d60f7ccac2f53f5acaa6e63cb5d469e4d04b271
+  metadata.gz: '0398ad1acd04f45d1e28dc890a8436e01d42b9ed4e9bab2f0ee6d8e278d505016f74bee609c8743a0f8e3d69c111b3e03c83e9e2779bcb7437a51f7167183e1a'
+  data.tar.gz: 693dbcc9294f41267f54e66ef5c9a082f24c1a222d4db7d3c648623a392cf8ca6e6a80ac7fea0c944eb080c87ef598fba5b1292829ac4cc6825495bbbe54f1c3

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-30
+
+### Added
+- `HtmlBuilder.data(**attrs)` helper to build `data-*` attribute hashes, mirroring the existing `aria` helper
+
+### Fixed
+- Bug report issue template now includes a required `gem-version` field and marks `ruby-version` as required, matching the standard template
+
+## [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

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
@@ -181,9 +183,14 @@ Philiprehberger::HtmlBuilder.build do
   aria(label: 'Save', expanded: false, describedby: nil)
 end
 # => { 'aria-label' => 'Save', 'aria-expanded' => 'false' }
+
+Philiprehberger::HtmlBuilder.build do
+  data(controller: 'menu', modal_target: 'dialog', open: true)
+end
+# => { 'data-controller' => 'menu', 'data-modal-target' => 'dialog', 'data-open' => 'true' }
 ```
 
-`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`.
+`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`. `data` mirrors `aria` for the `data-*` attribute namespace.
 
 ### CSS Class Helpers
 
@@ -198,6 +205,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:
@@ -348,7 +374,9 @@ Philiprehberger::HtmlBuilder.merge(header, body, footer)
 | `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#data(**attrs)` | Build a `data-*` attribute hash from snake_case keys (rendered as `data-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

@@ -308,6 +308,47 @@ module Philiprehberger
         result
       end
 
+      # Build a `data-*` attribute hash from keyword pairs
+      #
+      # snake_case keys are converted to `data-kebab-case` string keys. Values are
+      # converted to strings. Keys whose value is `nil` are omitted from the result.
+      # String keys are passed through with a `data-` prefix and underscores
+      # converted to dashes (e.g. `"modal-target"` becomes `"data-modal-target"`).
+      #
+      # @param attrs [Hash] keyword pairs to convert into `data-*` attributes
+      # @return [Hash<String, String>] hash with `"data-*"` string keys and string values
+      def data(**attrs)
+        result = {}
+        attrs.each do |key, value|
+          next if value.nil?
+
+          result["data-#{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.7.0'
+    VERSION = '0.9.0'
   end
 end

metadata

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