philiprehberger-html_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c6da441bb1020a1c99449e57883c95c26bac54e7c3d40cd087d8eb39878d16b
+  data.tar.gz: b446dc852ecb4f57d9da26e759eef7b529fadfcc828eb0adede1521aedae9680
+SHA512:
+  metadata.gz: d0e59c8ddaf4c5dd5b9db5ad6f5b1f1c69710c71075667e1dc7d388d37c11dd8b391d2425bc2a0be7dbe49a98f78e89e6b3961f56cbc1a57b96917a411a7d6a8
+  data.tar.gz: 5fac133068612fe23b7a9be0aea9ae411d91f884263497153fe1cff5745a31218f8eed3e20f10af996679e136a0c4b353d2b37be0d70f5b6f758041b4ab13642

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Tag DSL with nested block syntax for building HTML
+- Auto-escaping of text content and attribute values
+- Void element support (br, hr, img, input, meta, link, and others)
+- Attributes hash support on all elements
+- Raw HTML insertion for pre-rendered content

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# 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)
+
+Programmatic HTML builder with tag DSL and auto-escaping
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-html_builder"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-html_builder
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/html_builder"
+
+html = Philiprehberger::HtmlBuilder.build do
+  div(class: 'card') do
+    h1 'Title'
+    p 'Content'
+  end
+end
+# => '<div class="card"><h1>Title</h1><p>Content</p></div>'
+```
+
+### Auto-Escaping
+
+Text content and attribute values are automatically escaped:
+
+```ruby
+Philiprehberger::HtmlBuilder.build { p '<script>alert("xss")</script>' }
+# => '<p>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</p>'
+```
+
+### Void Elements
+
+Self-closing elements like `br`, `hr`, `img`, `input`, `meta`, and `link` render without closing tags:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  img(src: 'photo.jpg', alt: 'Photo')
+  br
+  input(type: 'text', name: 'email')
+end
+# => '<img src="photo.jpg" alt="Photo"><br><input type="text" name="email">'
+```
+
+### Attributes
+
+Pass attributes as keyword arguments to any tag:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  a(href: '/about', class: 'nav-link') { text 'About' }
+  input(type: 'checkbox', checked: true, disabled: false)
+end
+```
+
+### Raw HTML
+
+Insert pre-rendered HTML without escaping:
+
+```ruby
+Philiprehberger::HtmlBuilder.build do
+  div { raw '<em>pre-rendered</em>' }
+end
+```
+
+## 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 |
+| `Builder#text(content)` | Add escaped text content to the current element |
+| `Builder#raw(html)` | Add raw HTML without escaping |
+| `Escape.html(value)` | Escape HTML special characters in a string |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/html_builder/builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HtmlBuilder
+    # DSL-based HTML builder that creates a tree of nodes
+    class Builder
+      STANDARD_TAGS = %i[
+        a abbr address article aside audio b bdi bdo blockquote body button
+        canvas caption cite code colgroup data datalist dd del details dfn
+        dialog div dl dt em fieldset figcaption figure footer form
+        h1 h2 h3 h4 h5 h6 head header hgroup html i iframe ins kbd label
+        legend li main map mark menu meter nav noscript object ol optgroup
+        option output p picture pre progress q rp rt ruby s samp script
+        section select slot small span strong style sub summary sup table
+        tbody td template textarea tfoot th thead time title tr u ul var video
+      ].freeze
+
+      VOID_TAGS = %i[area base br col embed hr img input link meta param source track wbr].freeze
+
+      ALL_TAGS = (STANDARD_TAGS + VOID_TAGS).freeze
+
+      def initialize
+        @root_children = []
+        @stack = []
+      end
+
+      # Render all root-level nodes to HTML
+      #
+      # @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
+
+      ALL_TAGS.each do |tag_name|
+        define_method(tag_name) do |content = nil, **attrs, &block|
+          node = Node.new(tag_name, attributes: attrs)
+          node.add_child(content.to_s) if content
+          current_children << node
+
+          if block
+            @stack.push(node)
+            instance_eval(&block)
+            @stack.pop
+          end
+
+          node
+        end
+      end
+
+      # Add raw text content to the current context
+      #
+      # @param content [String] the text content (will be escaped)
+      # @return [void]
+      def text(content)
+        current_children << content.to_s
+      end
+
+      # Add raw HTML content without escaping
+      #
+      # @param html [String] the raw HTML string
+      # @return [void]
+      def raw(html)
+        node = RawNode.new(html)
+        current_children << node
+      end
+
+      private
+
+      # @return [Array] the children array for the current context
+      def current_children
+        if @stack.empty?
+          @root_children
+        else
+          @stack.last.children
+        end
+      end
+    end
+
+    # A node that renders raw HTML without escaping
+    class RawNode
+      # @param html [String] the raw HTML
+      def initialize(html)
+        @html = html
+      end
+
+      # @return [String] the raw HTML
+      def to_html
+        @html
+      end
+    end
+  end
+end

data/lib/philiprehberger/html_builder/escape.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HtmlBuilder
+    # HTML entity escaping utilities
+    module Escape
+      ENTITIES = {
+        '&' => '&',
+        '<' => '&lt;',
+        '>' => '&gt;',
+        '"' => '&quot;',
+        "'" => '&#39;'
+      }.freeze
+
+      ENTITY_PATTERN = Regexp.union(ENTITIES.keys).freeze
+
+      # Escape HTML special characters in a string
+      #
+      # @param value [String] the string to escape
+      # @return [String] the escaped string
+      def self.html(value)
+        value.to_s.gsub(ENTITY_PATTERN, ENTITIES)
+      end
+    end
+  end
+end

data/lib/philiprehberger/html_builder/node.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HtmlBuilder
+    # Represents an HTML element node with tag, attributes, and children
+    class Node
+      # @return [Symbol] the tag name
+      attr_reader :tag
+
+      # @return [Hash] the element attributes
+      attr_reader :attributes
+
+      # @return [Array] the child nodes
+      attr_reader :children
+
+      # @param tag [Symbol] the HTML tag name
+      # @param attributes [Hash] HTML attributes
+      def initialize(tag, attributes: {})
+        @tag = tag
+        @attributes = attributes
+        @children = []
+      end
+
+      # Add a child node
+      #
+      # @param child [Node, String] child node or text content
+      # @return [void]
+      def add_child(child)
+        @children << child
+      end
+
+      # Render the node to an HTML string
+      #
+      # @return [String] the rendered HTML
+      def to_html
+        if void_element?
+          "<#{tag}#{render_attributes}>"
+        elsif children.empty?
+          "<#{tag}#{render_attributes}></#{tag}>"
+        else
+          inner = children.map { |c| c.respond_to?(:to_html) ? c.to_html : Escape.html(c.to_s) }.join
+          "<#{tag}#{render_attributes}>#{inner}</#{tag}>"
+        end
+      end
+
+      private
+
+      VOID_ELEMENTS = %i[area base br col embed hr img input link meta param source track wbr].freeze
+
+      # @return [Boolean] true if this is a void (self-closing) element
+      def void_element?
+        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?
+            ''
+          else
+            " #{key}=\"#{Escape.html(value)}\""
+          end
+        end.join
+
+        attrs
+      end
+    end
+  end
+end

data/lib/philiprehberger/html_builder/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module HtmlBuilder
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/html_builder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'html_builder/version'
+require_relative 'html_builder/escape'
+require_relative 'html_builder/node'
+require_relative 'html_builder/builder'
+
+module Philiprehberger
+  module HtmlBuilder
+    class Error < StandardError; end
+
+    # Build HTML using a tag DSL
+    #
+    # @yield [Builder] the builder instance for DSL evaluation
+    # @return [String] the rendered HTML string
+    # @raise [Error] if no block is given
+    def self.build(&block)
+      raise Error, 'a block is required' unless block
+
+      builder = Builder.new
+      builder.instance_eval(&block)
+      builder.to_html
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-html_builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 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.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/html_builder.rb
+- lib/philiprehberger/html_builder/builder.rb
+- lib/philiprehberger/html_builder/escape.rb
+- lib/philiprehberger/html_builder/node.rb
+- lib/philiprehberger/html_builder/version.rb
+homepage: https://github.com/philiprehberger/rb-html-builder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-html-builder
+  source_code_uri: https://github.com/philiprehberger/rb-html-builder
+  changelog_uri: https://github.com/philiprehberger/rb-html-builder/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-html-builder/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Programmatic HTML builder with tag DSL and auto-escaping
+test_files: []