philiprehberger-html_builder 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a1ed5d63b82c40002240f74e0f808a5e62926efd8b55a0c52b482d804a23bab
-  data.tar.gz: 814fd3cf20cf2cf358f25e38d14dcf9f02e84e32827a584c0c94a947d4404f48
+  metadata.gz: ae55b58a30868dfa5bc7afd1f3300723c88c8f05e97470571a02619e07dd3dfd
+  data.tar.gz: 39f947b3d37ac2a914da3fa42f99dd9a3fddd9d43b09498d548b03eae269b694
 SHA512:
-  metadata.gz: 0e0214af812ff0754349ee79c494f544f34b6b5a16852387d3c51c30b1580c7e88f75d0392f4761dacf754c91722cc83015f95131f065c60eaa073df64453217
-  data.tar.gz: eb761b219b3a40319752ba84628ed2a7a88f0ea423581619a641a98932a3c39f8deabb83edb077be8c0319436d60f7ccac2f53f5acaa6e63cb5d469e4d04b271
+  metadata.gz: e4147ae709bc12f9c0d422169e2a8183bc90a92d3ae9b19cda6c62ad7fa927923b436d0a68f1c496eee6de843d9585a26a60786fee3611c3bcf8c765cf0365bd
+  data.tar.gz: 37cbec88f3da3293458bdbd8c42270c44d7f6f1b6f1e4b7052154968df53de570f9921dd27f9dde0a4221c56cf1ade5902168c2b98bd7af1f32327134b0b08f2

data/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

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
@@ -198,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:
@@ -349,6 +370,7 @@ Philiprehberger::HtmlBuilder.merge(header, body, footer)
 | `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

@@ -308,6 +308,28 @@ module Philiprehberger
         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.8.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.8.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 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.