element_component 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ebf642383684b4ac3419d63b6538ab4ddccc14c6275ad9913e2aa4d6fd14938
-  data.tar.gz: 1bfd4f8d575c2f92804c7c62868e3c303ca8a01f6238addee9d4bf93cd3b6d68
+  metadata.gz: a8b23fff0ff2bf1424f46a3db32fb706973f1601f153dd68f9786018979eb1ef
+  data.tar.gz: 631db1928c37d32d3a82190a0285e9fc85fb32693dc9fdba0fab9f118476fbcb
 SHA512:
-  metadata.gz: 99e132b0e8a5e168dfb9bae745cb46c235a3249ef42e61263bbbd4ae384472523ac5d110a3dc3afe12fec1a0436defd795afdd227f36efa11f515d4eb64a52f1
-  data.tar.gz: 5d721e3aa5aefc886c74eea0a04c94e9d408417b6e5660ef6976e5f8ea603e13f1c2c4ef9b559e256532e195e289f14ebe9cf60820cd33efbc492da731133296
+  metadata.gz: a1cf9210199d4eecaf263df1f99f8862541291cf0fa22fb9c6f92cf55cb1a68f60f72b154503dbce5889a5ffe3c42fd520ce915c7d3e08259d98008692b2d627
+  data.tar.gz: 248a8b0ad689bc29c4c8b9c05b42479c6c613789f87d8992ae34cfbc5d06710955117782eb0db683073e8239b2dfc339c65ffbeb4f46e60414427423e87d8c84

data/AGENTS.md

@@ -0,0 +1,126 @@
+# ElementComponent - Agent Instructions
+
+## Project Overview
+Ruby gem for building HTML programmatically with an object-oriented API. Provides dynamic attribute management, content nesting, and rendering hooks.
+
+## Architecture
+
+```
+lib/
+  element_component.rb              # Entry point, requires modules
+  element_component/
+    version.rb                      # VERSION constant
+    element.rb                      # Core Element class
+    components.rb                   # Component index, requires all components
+    components/
+      alert.rb                      # Alert component
+      alert/
+        heading.rb                  # AlertHeading component
+        link.rb                     # AlertLink component
+        close_button.rb             # AlertCloseButton component
+spec/
+  element_component_spec.rb         # Version check
+  lib/
+    element_spec.rb                 # Element unit tests
+    components/
+      alert_spec.rb                 # Alert component tests
+  spec_helper.rb                    # RSpec config
+examples/
+  alert_example.rb                  # Complete Alert usage examples
+```
+
+## Core Classes
+
+### `ElementComponent::Element`
+- **Attributes**: `element` (tag name), `attributes` (Hash), `contents` (Array), `html` (rendered output)
+- **Constructor**: `Element.new(tag_name, closing_tag: true, **attributes)`
+- **Content methods**: `add_content`, `add_content!`, `add_content(&block)`
+- **Attribute methods**: `add_attribute`, `add_attribute!`, `remove_attribute`, `remove_attribute_value`
+- **Render**: `render` (with hooks: `before_render`, `after_render`, `around_render`)
+
+### Pre-built Components
+
+Components live under `ElementComponent::Components`. Each component folder contains the main class and its sub-components in separate files.
+
+| Component | Class | Description |
+|---|---|---|
+| Alert | `Components::Alert` | `.alert` container with context |
+| Alert Heading | `Components::AlertHeading` | `.alert-heading` (`<h4>`) |
+| Alert Link | `Components::AlertLink` | `.alert-link` (`<a>`) |
+| Alert Close | `Components::AlertCloseButton` | `.btn-close` (self-closing `<button>`) |
+
+**Alert constructor**: `Alert.new(context: :primary, dismissible: false, **attributes, &block)`
+- `context`: one of `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:light`, `:dark`
+- `dismissible`: adds `.alert-dismissible` class and appends a `CloseButton`
+- `&block`: instance_eval DSL for adding content inside the element
+
+**Component guidelines**:
+- Always use `add_attribute()` instead of manipulating the `attributes` hash directly
+- Each class in its own file under a component-named folder
+- Call `super("tag_name", closing_tag: ..., &block)` first, then chain `add_attribute` calls
+- `instance_eval(&block)` lives in `Element#initialize` — do NOT repeat it in components
+- Pass user attributes last via `add_attribute(attributes)`
+
+### Sub-component example pattern:
+
+```ruby
+class AlertHeading < Element
+  def initialize(**attributes, &block)
+    super("h4", &block)
+    add_attribute(class: "alert-heading")
+    add_attribute(attributes)
+  end
+end
+```
+
+## Coding Conventions
+
+- **Language**: Ruby 3.1+
+- **Style**: Double quotes for strings
+- **Testing**: RSpec with `expect` syntax, `subject` pattern
+- **Linting**: RuboCop (run `bundle exec rubocop`)
+- **Pattern matching**: Use `in` pattern matching (`case content; in Element; ...`)
+
+## Common Commands
+
+```bash
+bin/setup              # Install dependencies
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Lint
+bundle exec rake spec  # Run tests via rake
+bundle exec rake rubocop # Lint via rake
+bundle exec rake       # Default: spec + rubocop
+bin/console            # Interactive console
+ruby examples/alert_example.rb  # Run Alert examples
+```
+
+## Testing Patterns
+
+- Use `subject` for the element under test
+- Use `before` blocks to set up state
+- Test render output as raw HTML strings
+- Test attribute hashes directly
+- Follow existing describe/context/it structure
+
+## Development Workflow
+
+1. Write/update specs first
+2. Implement in `lib/element_component/element.rb` or `lib/element_component/components/`
+3. Run `bundle exec rspec` to verify
+4. Run `bundle exec rubocop` for linting
+5. Run `bundle exec rake` for full check
+
+## Key Design Decisions
+
+- Attributes stored as Hash of Symbol => Array of values (supports multiple values per attribute)
+- Contents stored as Array (supports strings, Elements, and Procs/blocks)
+- `!` suffix methods reset state before adding (e.g., `add_content!` clears then adds)
+- Hooks (`before_render`, `after_render`, `around_render`) are optional, detected via `respond_to?`
+- Self-closing tags controlled by `closing_tag:` parameter
+- Component classes use `add_attribute()` instead of direct hash manipulation
+
+## Roadmap Features (from README)
+- Caching support
+- Pre-built Bulma components
+- Pre-built Bootstrap components
+- Enhanced DSL for nested structures

data/README.md

@@ -1,16 +1,16 @@
 # ElementComponent
 
-A lightweight and flexible HTML builder for Ruby. `ElementComponent` provides a simple, object-oriented way to construct HTML structures programmatically, allowing for dynamic attribute management and content nesting.
+A lightweight and flexible HTML builder for Ruby. `ElementComponent` provides a simple, object-oriented way to construct HTML structures programmatically, with dynamic attribute management, content nesting, rendering hooks, and pre-built components.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add to your application's Gemfile:
 
 ```bash
 bundle add element_component
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install directly:
 
 ```bash
 gem install element_component
@@ -18,9 +18,7 @@ gem install element_component
 
 ## Usage
 
-### Basic Usage
-
-Create a simple element and render it to HTML:
+### Creating Elements
 
 ```ruby
 p = ElementComponent::Element.new("p", class: "text-bold")
@@ -29,30 +27,58 @@ puts p.render
 # => <p class="text-bold">Hello, World!</p>
 ```
 
-### Nesting Elements
+### Block DSL
 
-You can nest elements by adding another `ElementComponent::Element` instance as content:
+Use a block to add content inline:
 
 ```ruby
-div = ElementComponent::Element.new("div", class: "container")
-h1  = ElementComponent::Element.new("h1")
-h1.add_content("Welcome")
+div = ElementComponent::Element.new("div", class: "container") do
+  add_content("Welcome")
+  add_content(ElementComponent::Element.new("h1") { add_content("Title") })
+end
+puts div.render
+# => <div class="container">Welcome<h1>Title</h1></div>
+```
+
+### The `new_element` Helper
 
-div.add_content(h1)
-div.add_content("This is a simple HTML builder.")
+Inside a block, use `new_element` as a shorthand:
 
+```ruby
+div = ElementComponent::Element.new("div") do
+  add_content(new_element("h1") { add_content("Hello") })
+  add_content(new_element("p", class: "lead") { add_content("World") })
+end
 puts div.render
-# => <div class="container"><h1>Welcome</h1>This is a simple HTML builder.</div>
+# => <div><h1>Hello</h1><p class="lead">World</p></div>
 ```
 
-### Attribute Management
+### Content Types
 
-`ElementComponent` allows for easy manipulation of HTML attributes:
+Content can be a string, an Element, or a block (Proc):
+
+```ruby
+div = ElementComponent::Element.new("div")
+
+# String
+div.add_content("plain text")
+
+# Element instance
+div.add_content(ElementComponent::Element.new("span") { add_content("nested") })
+
+# Block (evaluated at render time, has access to new_element)
+div.add_content { new_element("em") { add_content("deferred") } }
+
+puts div.render
+# => <div>plain text<span>nested</span><em>deferred</em></div>
+```
+
+### Attribute Management
 
 ```ruby
 btn = ElementComponent::Element.new("button", class: "btn", type: "button")
 
-# Add more values to an attribute (e.g., adding another class)
+# Add more values to an attribute
 btn.add_attribute(class: "btn-primary")
 
 # Reset attributes and set new ones
@@ -67,8 +93,6 @@ btn.remove_attribute_value(:class, "btn-primary")
 
 ### Self-Closing Tags
 
-You can specify if an element should have a closing tag:
-
 ```ruby
 img = ElementComponent::Element.new("img", closing_tag: false, src: "image.png", alt: "Logo")
 puts img.render
@@ -77,19 +101,103 @@ puts img.render
 
 ### Rendering Hooks
 
-`ElementComponent` supports `before_render`, `after_render`, and `around_render` hooks if implemented in a subclass or by extending an instance.
+`ElementComponent` supports `before_render`, `after_render`, and `around_render` hooks:
+
+```ruby
+div = ElementComponent::Element.new("div")
+div.define_singleton_method(:before_render) { add_attribute(class: "dynamic") }
+div.add_content("content")
+puts div.render
+# => <div class="dynamic">content</div>
+```
+
+## Pre-built Components
+
+Components live under `ElementComponent::Components`.
+
+### Alert (Bootstrap 5)
+
+```ruby
+alert = ElementComponent::Components::Alert.new(context: :success) do
+  add_content("Operation completed!")
+end
+puts alert.render
+# => <div class="alert alert-success" role="alert">Operation completed!</div>
+```
+
+**Contexts**: `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:light`, `:dark`
+
+#### Dismissible Alert
+
+```ruby
+alert = ElementComponent::Components::Alert.new(context: :warning, dismissible: true) do
+  add_content("This can be closed.")
+end
+puts alert.render
+# => <div class="alert alert-warning alert-dismissible" role="alert">
+#      This can be closed.
+#      <button class="btn-close" data-bs-dismiss="alert" aria-label="Close">
+#    </div>
+```
+
+#### Alert with Heading and Link
+
+```ruby
+alert = ElementComponent::Components::Alert.new(context: :info) do
+  add_content(ElementComponent::Components::AlertHeading.new.tap { |h| h.add_content("Notice") })
+  add_content("Please review. ")
+  add_content(ElementComponent::Components::AlertLink.new(href: "/details").tap { |l| l.add_content("Details") })
+end
+puts alert.render
+# => <div class="alert alert-info" role="alert">
+#      <h4 class="alert-heading">Notice</h4>
+#      Please review.
+#      <a class="alert-link" href="/details">Details</a>
+#    </div>
+```
+
+#### Sub-components
+
+| Class | Tag | Class |
+|---|---|---|
+| `Alert` | `<div>` | `.alert .alert-{context}` |
+| `AlertHeading` | `<h4>` | `.alert-heading` |
+| `AlertLink` | `<a>` | `.alert-link` |
+| `AlertCloseButton` | `<button>` (self-closing) | `.btn-close` |
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+bin/setup              # Install dependencies
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Lint
+bundle exec rake       # Spec + RuboCop
+bin/console            # Interactive console
+ruby examples/alert_example.rb  # Run Alert examples
+```
+
+### Test Coverage
+
+Run with coverage reporting:
+
+```bash
+COVERAGE=true bundle exec rspec
+```
+
+### Release
+
+```bash
+# Update version in lib/element_component/version.rb
+bundle exec rake release
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Or push a version tag (e.g., `v0.6.0`) to trigger the automated release workflow.
 
 ## Roadmap
 
 - [ ] Support for Caching
 - [ ] Pre-built Bulma components
-- [ ] Pre-built Bootstrap components
+- [ ] Pre-built Bootstrap components (more)
 - [ ] Enhanced DSL for nested structures
 
 ## Contributing

data/examples/alert_example.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "../lib/element_component"
+
+# =============================================================================
+# Basic Alert
+# =============================================================================
+alert = ElementComponent::Components::Alert.new(context: :success)
+alert.add_content("Operation completed successfully!")
+puts "=== Basic Alert ==="
+puts alert.render
+puts
+
+# =============================================================================
+# All Contexts
+# =============================================================================
+puts "=== All Alert Contexts ==="
+ElementComponent::Components::Alert::VALID_CONTEXTS.each do |context|
+  alert = ElementComponent::Components::Alert.new(context: context)
+  alert.add_content("#{context.capitalize} alert message here.")
+  puts alert.render
+end
+puts
+
+# =============================================================================
+# Dismissible Alert (use block DSL so close button is always last)
+# =============================================================================
+alert = ElementComponent::Components::Alert.new(context: :warning, dismissible: true) do
+  add_content("This alert can be dismissed.")
+end
+puts "=== Dismissible Alert ==="
+puts alert.render
+puts
+
+# =============================================================================
+# Alert with Custom Attributes
+# =============================================================================
+alert = ElementComponent::Components::Alert.new(
+  context: :primary,
+  id: "main-alert",
+  style: "margin-top: 20px;"
+)
+alert.add_content("This alert has a custom ID and inline style.")
+puts "=== Alert with Custom Attributes ==="
+puts alert.render
+puts
+
+# =============================================================================
+# Alert with Heading and Link (block DSL)
+# =============================================================================
+alert = ElementComponent::Components::Alert.new(context: :info) do
+  add_content(ElementComponent::Components::AlertHeading.new.tap { |h| h.add_content("Information") })
+  add_content("This is an important notice. ")
+  add_content(ElementComponent::Components::AlertLink.new(href: "/details").tap { |l| l.add_content("View details") })
+end
+puts "=== Alert with Heading and Link ==="
+puts alert.render
+puts
+
+# =============================================================================
+# Dismissible Alert with Heading and Link
+# =============================================================================
+alert = ElementComponent::Components::Alert.new(context: :danger, dismissible: true) do
+  add_content(ElementComponent::Components::AlertHeading.new.tap { |h| h.add_content("Error!") })
+  add_content("Something went wrong. ")
+  add_content(ElementComponent::Components::AlertLink.new(href: "/support").tap do |l|
+    l.add_content("Contact support")
+  end)
+end
+puts "=== Dismissible Alert with Heading and Link ==="
+puts alert.render
+puts
+
+# =============================================================================
+# Chained API Usage
+# =============================================================================
+alert = ElementComponent::Components::Alert.new(context: :secondary)
+                                           .add_content("This alert was built using chained calls.")
+puts "=== Chained API ==="
+puts alert.render
+puts
+
+# =============================================================================
+# Using Sub-Components Independently
+# =============================================================================
+heading = ElementComponent::Components::AlertHeading.new
+heading.add_content("Standalone Heading")
+
+link = ElementComponent::Components::AlertLink.new(href: "https://example.com")
+link.add_content("Standalone Link")
+
+close_btn = ElementComponent::Components::AlertCloseButton.new
+
+puts "=== Sub-Components Rendered Independently ==="
+puts heading.render
+puts link.render
+puts close_btn.render

data/lib/element_component/components/alert/close_button.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ElementComponent
+  module Components
+    class AlertCloseButton < Element
+      def initialize(**attributes)
+        super("button", closing_tag: false)
+
+        add_attribute(class: "btn-close")
+        add_attribute(type: "button")
+        add_attribute("data-bs-dismiss": "alert")
+        add_attribute("aria-label": "Close")
+        add_attribute(attributes) unless attributes.empty?
+      end
+    end
+  end
+end

data/lib/element_component/components/alert/heading.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ElementComponent
+  module Components
+    class AlertHeading < Element
+      def initialize(**attributes)
+        super("h4")
+
+        add_attribute(class: "alert-heading")
+        add_attribute(attributes) unless attributes.empty?
+      end
+    end
+  end
+end

data/lib/element_component/components/alert/link.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ElementComponent
+  module Components
+    class AlertLink < Element
+      def initialize(href: "#", **attributes)
+        super("a")
+
+        add_attribute(class: "alert-link")
+        add_attribute(href: href)
+        add_attribute(attributes) unless attributes.empty?
+      end
+    end
+  end
+end

data/lib/element_component/components/alert.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "alert/heading"
+require_relative "alert/link"
+require_relative "alert/close_button"
+
+module ElementComponent
+  module Components
+    class Alert < Element
+      VALID_CONTEXTS = %i[primary secondary success danger warning info light dark].freeze
+
+      def initialize(context: :primary, dismissible: false, **attributes, &block)
+        super("div", &block)
+
+        add_attribute(class: "alert")
+        add_attribute(class: "alert-#{context}")
+        add_attribute(class: "alert-dismissible") if dismissible
+        add_attribute(role: "alert")
+
+        add_attribute(attributes) unless attributes.empty?
+        add_content(AlertCloseButton.new) if dismissible
+      end
+    end
+  end
+end

data/lib/element_component/components.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "components/alert"
+
+module ElementComponent
+  module Components
+  end
+end

data/lib/element_component/element.rb

@@ -1,14 +1,17 @@
+# frozen_string_literal: true
+
 module ElementComponent
   class Element
     attr_reader :element, :attributes, :contents, :html
 
-    def initialize(element, closing_tag: true, **attribute)
+    def initialize(element, closing_tag: true, **attribute, &block)
       @element = element
       @closing_tag = closing_tag
-      @html = ""
+      @html = String.new
 
       add_attribute!(attribute)
       reset_contents!
+      instance_eval(&block) if block
     end
 
     def add_content!(content)
@@ -64,18 +67,20 @@ module ElementComponent
       @attributes = {}
     end
 
-    def new_element(*args, **kargs) = Element.new(*args, **kargs)
+    def new_element(...) = Element.new(...)
 
     def render
-      before_render if respond_to? 'before_render'
+      @html = String.new
+
+      before_render if respond_to? "before_render"
 
-      if respond_to? 'around_render'
+      if respond_to? "around_render"
         around_render { build }
       else
         build
       end
 
-      after_render(@html) if respond_to? 'after_render'
+      after_render(@html) if respond_to? "after_render"
 
       @html
     end
@@ -95,10 +100,19 @@ module ElementComponent
     end
 
     def mount_content
-      @contents.map do |content|
+      @contents.dup.map do |content|
         case content
         in Element
           content.render
+        in Proc
+          result = instance_eval(&content)
+          if result.equal?(self)
+            ""
+          elsif result.respond_to?(:render)
+            result.render
+          else
+            result.to_s
+          end
         else
           content.to_s
         end

data/lib/element_component/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ElementComponent
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/element_component.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require_relative "element_component/version"
 require_relative "element_component/element"
+require_relative "element_component/components"
 
 module ElementComponent
   class Error < StandardError; end
-  # Your code goes here...
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: element_component
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - João Paulo Correia
@@ -18,10 +18,17 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- AGENTS.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/alert_example.rb
 - lib/element_component.rb
+- lib/element_component/components.rb
+- lib/element_component/components/alert.rb
+- lib/element_component/components/alert/close_button.rb
+- lib/element_component/components/alert/heading.rb
+- lib/element_component/components/alert/link.rb
 - lib/element_component/element.rb
 - lib/element_component/version.rb
 homepage: https://github.com/joaopaulocorreia/element_component