philiprehberger-html_builder 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dbf0a37df1293a248006f06e88aa73e80fb4ee09bd526e69927cc872d64c3dc
-  data.tar.gz: cbf9e1056bacaf1013e4c1f42fe256d9abb75ac127b06296c12eb6d9cc1eb12a
+  metadata.gz: 595807de03e97765d4e856e8c1948bf1bf5a2d47ab75fd847589ae3fb2751e95
+  data.tar.gz: 6783b0d074ef48345176cf2dc69ea05a502eba3ab217399f0485d506e43789e3
 SHA512:
-  metadata.gz: 8465923f3f60987cd19ee14c21393c1d6043b11a53fb559d406bb654969a09b97df3afbd4bd4f4b68d649366bc9d021a0f730dc6f4ba115c9a5de25116cfa30a
-  data.tar.gz: afd25e6739d13c758c15d8373a66695e1fe83c74bbf4bb144dbec8fba7840f89f0b60d12baf5adc31324e8c2f764e68422aa3fe6a7e1c2674d9c7ec13348037a
+  metadata.gz: e36fc11adf732b544ad9f42d43a91fbc2b230ed5bc5803ab2c16f8515ae7ccfe691dfc40a301e604a1cb10cf0aa8e6e2c82513a4e926b42e2ab2c35d8a5239ca
+  data.tar.gz: b0ac790fd555a82e537f1b023a8f74f3de1d330ccfe3113fb4e11996d252f2d00221ac7c1109cf171080f693a283362d36b7abf6330aa8decf275c74a73588b4

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-28
+
+### Added
+- Form builder helpers (`form_for`, `field`, `select_field`, `textarea_field`) for streamlined form construction
+- HTML5 data/aria attribute support via hash syntax (`data: { id: 1 }` renders as `data-id="1"`)
+- Conditional rendering with `render_if` and `render_unless` blocks
+- Component/partial system with `define_component` and `use_component` for reusable named blocks
+- Pretty-printed output mode via `build_pretty` with configurable indentation
+- Minified output mode via `build_minified` (alias for `build`)
+- HTML fragment merging via `HtmlBuilder.merge` to combine multiple builder outputs
+
 ## [0.1.3] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -1,10 +1,8 @@
 # philiprehberger-html_builder
 
-[![Tests](https://github.com/philiprehberger/rb-html-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-html-builder/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/philiprehberger-html_builder.svg)](https://rubygems.org/gems/philiprehberger-html_builder)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-html-builder)](LICENSE)
+[![Tests](https://github.com/philiprehberger/rb-html-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-html-builder/actions/workflows/ci.yml) [![Gem Version](https://img.shields.io/gem/v/philiprehberger-html_builder)](https://rubygems.org/gems/philiprehberger-html_builder) [![GitHub release](https://img.shields.io/github/v/release/philiprehberger/rb-html-builder)](https://github.com/philiprehberger/rb-html-builder/releases) [![GitHub last commit](https://img.shields.io/github/last-commit/philiprehberger/rb-html-builder)](https://github.com/philiprehberger/rb-html-builder/commits/main) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Bug Reports](https://img.shields.io/badge/bug-reports-red.svg)](https://github.com/philiprehberger/rb-html-builder/issues) [![Feature Requests](https://img.shields.io/badge/feature-requests-blue.svg)](https://github.com/philiprehberger/rb-html-builder/issues) [![GitHub Sponsors](https://img.shields.io/badge/sponsor-philiprehberger-ea4aaa.svg?logo=github)](https://github.com/sponsors/philiprehberger)
 
-Programmatic HTML builder with tag DSL and auto-escaping
+Programmatic HTML builder with tag DSL, auto-escaping, form helpers, components, and output formatting.
 
 ## Requirements
 
@@ -71,6 +69,19 @@ Philiprehberger::HtmlBuilder.build do
 end
 ```
 
+### Data and Aria Attributes
+
+Use hash syntax for HTML5 `data-*` and `aria-*` attributes:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  div(data: { id: 1, action: 'click' }, aria: { label: 'Panel' }) do
+    button('Toggle', aria: { expanded: 'false' })
+  end
+end
+# => '<div data-id="1" data-action="click" aria-label="Panel"><button aria-expanded="false">Toggle</button></div>'
+```
+
 ### Raw HTML
 
 Insert pre-rendered HTML without escaping:
@@ -81,14 +92,115 @@ Philiprehberger::HtmlBuilder.build do
 end
 ```
 
+### Form Builder Helpers
+
+Streamlined helpers for building forms with automatic label generation:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  form_for('/signup', class: 'form') do
+    field(:email, type: 'email')
+    field(:first_name)
+    select_field(:country, [%w[USA us], %w[Canada ca]], selected: 'us')
+    textarea_field(:bio, rows: '5')
+    button 'Submit', type: 'submit'
+  end
+end
+```
+
+The `field` helper generates a `<label>` and `<input>` pair. The `select_field` helper generates a `<label>` and `<select>` with `<option>` tags. The `textarea_field` helper generates a `<label>` and `<textarea>`. Label text is auto-generated from the field name (underscores become spaces, words are capitalized).
+
+### Conditional Rendering
+
+Render blocks based on conditions:
+
+```ruby
+logged_in = true
+admin = false
+
+Philiprehberger::HtmlBuilder.build do
+  render_if(logged_in) { p 'Welcome back!' }
+  render_unless(admin) { p 'Standard user' }
+end
+# => '<p>Welcome back!</p><p>Standard user</p>'
+```
+
+### Components
+
+Define reusable named blocks and render them anywhere:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  define_component(:card) do |locals|
+    div(class: 'card') do
+      h2 locals[:title]
+      p locals[:body]
+    end
+  end
+
+  use_component(:card, title: 'First', body: 'Content 1')
+  use_component(:card, title: 'Second', body: 'Content 2')
+end
+```
+
+Components without parameters use a simple block with no arguments. Components with parameters receive a hash of locals.
+
+### Output Modes
+
+Choose between minified and pretty-printed output:
+
+```ruby
+# Minified (default)
+Philiprehberger::HtmlBuilder.build do
+  div { p 'Hello' }
+end
+# => '<div><p>Hello</p></div>'
+
+# Pretty-printed
+Philiprehberger::HtmlBuilder.build_pretty do
+  div { p 'Hello' }
+end
+# => "<div>\n  <p>Hello</p>\n</div>"
+
+# Pretty-printed with custom indent
+Philiprehberger::HtmlBuilder.build_pretty(indent_size: 4) do
+  div { p 'Hello' }
+end
+```
+
+### Fragment Merging
+
+Combine multiple builder outputs into a single HTML string:
+
+```ruby
+header = Philiprehberger::HtmlBuilder.build { header { h1 'Title' } }
+body = Philiprehberger::HtmlBuilder.build { main { p 'Content' } }
+footer = Philiprehberger::HtmlBuilder.build { footer { p 'Copyright' } }
+
+Philiprehberger::HtmlBuilder.merge(header, body, footer)
+# => '<header><h1>Title</h1></header><main><p>Content</p></main><footer><p>Copyright</p></footer>'
+```
+
 ## API
 
 | Method | Description |
 |--------|-------------|
-| `HtmlBuilder.build { ... }` | Build HTML using the tag DSL, returns a string |
-| `Builder#to_html` | Render the builder contents to an HTML string |
+| `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.merge(*fragments)` | Merge multiple HTML fragment strings into one |
+| `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#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 |
+| `Builder#use_component(name, **locals)` | Render a previously defined component |
+| `Builder#form_for(action, method_type:, **attrs) { ... }` | Build a form tag with common defaults |
+| `Builder#field(name, label_text:, type:, **attrs)` | Build a label + input pair |
+| `Builder#select_field(name, options, label_text:, selected:, **attrs)` | Build a label + select with options |
+| `Builder#textarea_field(name, content, label_text:, **attrs)` | Build a label + textarea |
 | `Escape.html(value)` | Escape HTML special characters in a string |
 
 ## Development
@@ -99,6 +211,10 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Philip%20Rehberger-blue?logo=linkedin)](https://linkedin.com/in/philiprehberger) [![More Packages](https://img.shields.io/badge/more-packages-blue.svg)](https://github.com/philiprehberger?tab=repositories)
+
 ## License
 
 MIT

data/lib/philiprehberger/html_builder/builder.rb

@@ -22,15 +22,30 @@ module Philiprehberger
       def initialize
         @root_children = []
         @stack = []
+        @components = {}
       end
 
-      # Render all root-level nodes to HTML
+      # Render all root-level nodes to HTML (minified)
       #
       # @return [String] the rendered HTML
       def to_html
         @root_children.map { |c| c.respond_to?(:to_html) ? c.to_html : Escape.html(c.to_s) }.join
       end
 
+      # Render all root-level nodes to pretty-printed HTML with indentation
+      #
+      # @param indent_size [Integer] number of spaces per indent level (default 2)
+      # @return [String] the pretty-printed HTML
+      def to_pretty_html(indent_size: 2)
+        @root_children.map do |c|
+          if c.respond_to?(:to_html)
+            c.to_html(indent: 0, indent_size: indent_size)
+          else
+            Escape.html(c.to_s)
+          end
+        end.join("\n")
+      end
+
       ALL_TAGS.each do |tag_name|
         define_method(tag_name) do |content = nil, **attrs, &block|
           node = Node.new(tag_name, attributes: attrs)
@@ -64,6 +79,124 @@ module Philiprehberger
         current_children << node
       end
 
+      # Conditionally render a block if the condition is truthy
+      #
+      # @param condition [Object] the condition to evaluate
+      # @yield the block to render if condition is truthy
+      # @return [void]
+      def render_if(condition, &block)
+        return unless condition
+        raise Error, 'a block is required for render_if' unless block
+
+        instance_eval(&block)
+      end
+
+      # Conditionally render a block if the condition is falsy
+      #
+      # @param condition [Object] the condition to evaluate
+      # @yield the block to render if condition is falsy
+      # @return [void]
+      def render_unless(condition, &block)
+        return if condition
+        raise Error, 'a block is required for render_unless' unless block
+
+        instance_eval(&block)
+      end
+
+      # Define a reusable named component
+      #
+      # @param name [Symbol, String] the component name
+      # @yield the block that defines the component's HTML
+      # @return [void]
+      def define_component(name, &block)
+        raise Error, 'a block is required for define_component' unless block
+
+        @components[name.to_sym] = block
+      end
+
+      # Render a previously defined component
+      #
+      # @param name [Symbol, String] the component name
+      # @param locals [Hash] local variables passed to the component block
+      # @return [void]
+      def use_component(name, **locals)
+        block = @components[name.to_sym]
+        raise Error, "undefined component: #{name}" unless block
+
+        if block.arity.zero? || (block.arity.negative? && locals.empty?)
+          instance_eval(&block)
+        else
+          instance_exec(locals, &block)
+        end
+      end
+
+      # Form builder helper: builds a form tag with common defaults
+      #
+      # @param action [String] the form action URL
+      # @param method_type [String] the HTTP method (default "post")
+      # @param attrs [Hash] additional attributes
+      # @yield the form contents
+      # @return [Node]
+      def form_for(action, method_type: 'post', **attrs, &block)
+        form(action: action, method: method_type, **attrs, &block)
+      end
+
+      # Form builder helper: builds a label + input pair
+      #
+      # @param name [String, Symbol] the field name
+      # @param label_text [String] the label text
+      # @param type [String] the input type (default "text")
+      # @param attrs [Hash] additional input attributes
+      # @return [void]
+      def field(name, label_text: nil, type: 'text', **attrs)
+        field_id = attrs.delete(:id) || name.to_s.tr('_', '-')
+        label_str = label_text || name.to_s.gsub('_', ' ').split.map(&:capitalize).join(' ')
+        label label_str, for: field_id
+        input(type: type, name: name.to_s, id: field_id, **attrs)
+      end
+
+      # Form builder helper: builds a label + select with options
+      #
+      # @param name [String, Symbol] the field name
+      # @param options_list [Array<Array, String>] list of [text, value] pairs or plain strings
+      # @param label_text [String] the label text
+      # @param selected [String, nil] the selected value
+      # @param attrs [Hash] additional select attributes
+      # @return [void]
+      def select_field(name, options_list, label_text: nil, selected: nil, **attrs)
+        field_id = attrs.delete(:id) || name.to_s.tr('_', '-')
+        label_str = label_text || name.to_s.gsub('_', ' ').split.map(&:capitalize).join(' ')
+        label label_str, for: field_id
+        select(name: name.to_s, id: field_id, **attrs) do
+          options_list.each do |opt|
+            if opt.is_a?(Array)
+              opt_text, opt_value = opt
+              option_attrs = { value: opt_value.to_s }
+              option_attrs[:selected] = true if opt_value.to_s == selected.to_s
+              option opt_text, **option_attrs
+            else
+              option_attrs = { value: opt.to_s }
+              option_attrs[:selected] = true if opt.to_s == selected.to_s
+              option opt.to_s, **option_attrs
+            end
+          end
+        end
+      end
+
+      # Form builder helper: builds a label + textarea
+      #
+      # @param name [String, Symbol] the field name
+      # @param content [String, nil] the textarea content
+      # @param label_text [String] the label text
+      # @param attrs [Hash] additional textarea attributes
+      # @return [void]
+      def textarea_field(name, content = nil, label_text: nil, **attrs)
+        field_id = attrs.delete(:id) || name.to_s.tr('_', '-')
+        label_str = label_text || name.to_s.gsub('_', ' ').split.map(&:capitalize).join(' ')
+        label label_str, for: field_id
+        textarea(content, name: name.to_s, id: field_id, **attrs)
+      end
+
       private
 
       # @return [Array] the children array for the current context
@@ -84,8 +217,12 @@ module Philiprehberger
       end
 
       # @return [String] the raw HTML
-      def to_html
-        @html
+      def to_html(indent: nil, indent_size: 2)
+        if indent
+          "#{' ' * (indent * indent_size)}#{@html}"
+        else
+          @html
+        end
       end
     end
   end

data/lib/philiprehberger/html_builder/node.rb

@@ -31,15 +31,16 @@ module Philiprehberger
 
       # Render the node to an HTML string
       #
+      # @param indent [Integer, nil] current indentation level (nil for minified)
+      # @param indent_size [Integer] number of spaces per indent level
       # @return [String] the rendered HTML
-      def to_html
-        if void_element?
-          "<#{tag}#{render_attributes}>"
-        elsif children.empty?
-          "<#{tag}#{render_attributes}></#{tag}>"
+      def to_html(indent: nil, indent_size: 2)
+        flat_attrs = flatten_attributes(attributes)
+
+        if indent
+          render_pretty(flat_attrs, indent: indent, indent_size: indent_size)
         else
-          inner = children.map { |c| c.respond_to?(:to_html) ? c.to_html : Escape.html(c.to_s) }.join
-          "<#{tag}#{render_attributes}>#{inner}</#{tag}>"
+          render_inline(flat_attrs)
         end
       end
 
@@ -52,21 +53,87 @@ module Philiprehberger
         VOID_ELEMENTS.include?(tag)
       end
 
-      # @return [String] rendered attribute string
-      def render_attributes
-        return '' if attributes.empty?
-
-        attrs = attributes.map do |key, value|
-          if value == true
-            " #{key}"
-          elsif value == false || value.nil?
-            ''
+      # Flatten nested hash attributes (data, aria) into hyphenated keys
+      #
+      # @param attrs [Hash] the attributes hash
+      # @return [Hash] flattened attributes
+      def flatten_attributes(attrs)
+        result = {}
+        attrs.each do |key, value|
+          if value.is_a?(Hash)
+            value.each do |sub_key, sub_value|
+              result[:"#{key}-#{sub_key}"] = sub_value
+            end
           else
-            " #{key}=\"#{Escape.html(value)}\""
+            result[key] = value
           end
-        end.join
+        end
+        result
+      end
+
+      # Render a single attribute pair
+      #
+      # @param key [Symbol] attribute name
+      # @param value [Object] attribute value
+      # @return [String] rendered attribute string
+      def render_attribute(key, value)
+        if value == true
+          " #{key}"
+        elsif value == false || value.nil?
+          ''
+        else
+          " #{key}=\"#{Escape.html(value)}\""
+        end
+      end
+
+      # @return [String] rendered attribute string
+      def render_attributes(attrs)
+        return '' if attrs.empty?
 
-        attrs
+        attrs.map { |key, value| render_attribute(key, value) }.join
+      end
+
+      # Render inline (minified) HTML
+      def render_inline(flat_attrs)
+        attr_str = render_attributes(flat_attrs)
+        if void_element?
+          "<#{tag}#{attr_str}>"
+        elsif children.empty?
+          "<#{tag}#{attr_str}></#{tag}>"
+        else
+          inner = children.map { |c| c.respond_to?(:to_html) ? c.to_html : Escape.html(c.to_s) }.join
+          "<#{tag}#{attr_str}>#{inner}</#{tag}>"
+        end
+      end
+
+      # Render pretty-printed HTML with indentation
+      def render_pretty(flat_attrs, indent:, indent_size:)
+        attr_str = render_attributes(flat_attrs)
+        pad = ' ' * (indent * indent_size)
+
+        if void_element?
+          "#{pad}<#{tag}#{attr_str}>"
+        elsif children.empty?
+          "#{pad}<#{tag}#{attr_str}></#{tag}>"
+        else
+          # Check if all children are text-only (no Node children)
+          all_text = children.none? { |c| c.respond_to?(:to_html) }
+          if all_text
+            inner = children.map { |c| Escape.html(c.to_s) }.join
+            "#{pad}<#{tag}#{attr_str}>#{inner}</#{tag}>"
+          else
+            lines = ["#{pad}<#{tag}#{attr_str}>"]
+            children.each do |c|
+              lines << if c.respond_to?(:to_html)
+                         c.to_html(indent: indent + 1, indent_size: indent_size)
+                       else
+                         "#{' ' * ((indent + 1) * indent_size)}#{Escape.html(c.to_s)}"
+                       end
+            end
+            lines << "#{pad}</#{tag}>"
+            lines.join("\n")
+          end
+        end
       end
     end
   end

data/lib/philiprehberger/html_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module HtmlBuilder
-    VERSION = '0.1.3'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/html_builder.rb

@@ -9,7 +9,7 @@ module Philiprehberger
   module HtmlBuilder
     class Error < StandardError; end
 
-    # Build HTML using a tag DSL
+    # Build HTML using a tag DSL (minified output)
     #
     # @yield [Builder] the builder instance for DSL evaluation
     # @return [String] the rendered HTML string
@@ -21,5 +21,36 @@ module Philiprehberger
       builder.instance_eval(&block)
       builder.to_html
     end
+
+    # Build pretty-printed HTML using a tag DSL
+    #
+    # @param indent_size [Integer] number of spaces per indent level (default 2)
+    # @yield [Builder] the builder instance for DSL evaluation
+    # @return [String] the pretty-printed HTML string
+    # @raise [Error] if no block is given
+    def self.build_pretty(indent_size: 2, &block)
+      raise Error, 'a block is required' unless block
+
+      builder = Builder.new
+      builder.instance_eval(&block)
+      builder.to_pretty_html(indent_size: indent_size)
+    end
+
+    # Build minified HTML (alias for build)
+    #
+    # @yield [Builder] the builder instance for DSL evaluation
+    # @return [String] the rendered HTML string
+    # @raise [Error] if no block is given
+    def self.build_minified(&)
+      build(&)
+    end
+
+    # Merge multiple HTML fragment strings into one
+    #
+    # @param fragments [Array<String>] HTML fragments to merge
+    # @return [String] the merged HTML string
+    def self.merge(*fragments)
+      fragments.join
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-html_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-03-28 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.