element_component 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ebf642383684b4ac3419d63b6538ab4ddccc14c6275ad9913e2aa4d6fd14938
-  data.tar.gz: 1bfd4f8d575c2f92804c7c62868e3c303ca8a01f6238addee9d4bf93cd3b6d68
+  metadata.gz: 27a79b6578d299e674340e4c1e3c7a0061ff6ac3b9c233f102bb3d4d3fd89011
+  data.tar.gz: 501d6617270b0e5bc9cef324d270126d5cd531677cdd8ee43bb3a8e18bf1cd4c
 SHA512:
-  metadata.gz: 99e132b0e8a5e168dfb9bae745cb46c235a3249ef42e61263bbbd4ae384472523ac5d110a3dc3afe12fec1a0436defd795afdd227f36efa11f515d4eb64a52f1
-  data.tar.gz: 5d721e3aa5aefc886c74eea0a04c94e9d408417b6e5660ef6976e5f8ea603e13f1c2c4ef9b559e256532e195e289f14ebe9cf60820cd33efbc492da731133296
+  metadata.gz: d7317e82f7fc54008e4f4152372fc1f3575edf3f0956790a87298025707bbcd507422c3a3e32800dd6aa6a3954f1006ac470fde4e44ffb35ba7aba1bfe9ed5e8
+  data.tar.gz: c358120b8d90a4ef0ea864094cae08d245286a20266c4c645814f7f60ec5795f5a62756a740e91be566b08159914674b91b0ba9af76013de02c0f3e20927d731

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 variant |
+| 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(variant: :primary, dismissible: false, **attributes, &block)`
+- `variant`: 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,25 @@
 # 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 a comprehensive set of pre-built Bootstrap 5 components.
+
+## Key Features
+
+- **Object-Oriented HTML Construction** — Build HTML trees using Ruby objects with dynamic attribute management
+- **Block DSL** — Nest content inline with `instance_eval`-based blocks and the `new_element` helper
+- **Rendering Hooks** — `before_render`, `after_render`, and `around_render` callbacks for dynamic content
+- **17 Bootstrap 5 Components** — Ready-to-use Alert, Badge, Breadcrumb, Button, ButtonGroup, Card, Carousel, CloseButton, Dropdown, ListGroup, Modal, Nav, Navbar, Pagination, Progress, Spinner, and Table
+- **Chained API** — All `add_*` methods return `self` for method chaining
+- **Self-Closing Tags** — Support for void elements like `<img>`, `<input>`, `<br>`
 
 ## 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 +27,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 +36,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>
+```
 
-div.add_content(h1)
-div.add_content("This is a simple HTML builder.")
+### The `new_element` Helper
 
+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
+
+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>
+```
 
-`ElementComponent` allows for easy manipulation of HTML attributes:
+### 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 +102,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,20 +110,402 @@ 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 (Bootstrap 5)
+
+All components live under `ElementComponent::Components` and support the block DSL, chained `add_content`, and custom HTML attributes via `**attributes`.
+
+### Quick Reference
+
+| Component | Class | Tag | Key Options |
+|---|---|---|---|
+| Alert | `Alert` | `<div>` | `variant`, `dismissible` |
+| Badge | `Badge` | `<span>` | `variant`, `pill` |
+| Breadcrumb | `Breadcrumb` | `<nav>` → `<ol>` | `BreadcrumbItem` (`href`, `active`) |
+| Button | `Button` | `<button>` / `<a>` | `variant`, `outline`, `size`, `href` |
+| ButtonGroup | `ButtonGroup` | `<div>` | `size`, `vertical` |
+| Card | `Card` | `<div>` | Sub-components: Header, Body, Footer, Title, Text, Image |
+| Carousel | `Carousel` | `<div>` | `fade`, `indicators`, `controls`; `CarouselItem`, `CarouselCaption` |
+| CloseButton | `CloseButton` | `<button>` (self-closing) | `disabled` |
+| Dropdown | `Dropdown` | `<div>` | `direction`; `DropdownMenu`, `DropdownItem`, `DropdownDivider`, `DropdownHeader` |
+| ListGroup | `ListGroup` | `<ul>` | `flush`, `numbered`; `ListGroupItem` (`variant`, `active`, `disabled`, `href`) |
+| Modal | `Modal` | `<div>` | `fade`, `static`, `scrollable`, `centered`, `size`; `ModalContent`, `ModalHeader`, `ModalBody`, `ModalFooter` |
+| Nav | `Nav` | `<ul>` | `type` (tabs/pills/underline), `fill`, `justified`, `vertical` |
+| Navbar | `Navbar` | `<nav>` | `expand`, `theme`, `background`, `fixed`, `sticky`; `NavbarBrand`, `NavbarNav`, `NavbarToggler` |
+| Pagination | `Pagination` | `<nav>` → `<ul>` | `size`; `PageItem` (`active`, `disabled`) |
+| Progress | `Progress` | `<div>` | `ProgressBar` (`value`, `variant`, `striped`, `animated`) |
+| Spinner | `Spinner` | `<div>` | `type` (border/grow), `variant` |
+| Table | `Table` | `<table>` | `striped`, `bordered`, `hover`, `small`, `variant` |
+
+### Alert
+
+
+```ruby
+alert = ElementComponent::Components::Alert.new(variant: :success) do
+  add_content("Operation completed!")
+end
+# => <div class="alert alert-success" role="alert">Operation completed!</div>
+```
+
+**Variants**: `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:light`, `:dark`
+
+Dismissible alerts, headings, and links use sub-components:
+
+```ruby
+alert = ElementComponent::Components::Alert.new(variant: :warning, dismissible: true) do
+  add_content(ElementComponent::Components::AlertHeading.new { add_content("Warning") })
+  add_content("Please review. ")
+  add_content(ElementComponent::Components::AlertLink.new(href: "/details") { add_content("Details") })
+end
+# => <div class="alert alert-warning alert-dismissible" role="alert">
+#      <h4 class="alert-heading">Warning</h4>
+#      Please review.
+#      <a class="alert-link" href="/details">Details</a>
+#      <button class="btn-close" data-bs-dismiss="alert" aria-label="Close">
+#    </div>
+```
+
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `AlertHeading` | `<h4>` | `.alert-heading` |
+| `AlertLink` | `<a>` | `.alert-link` |
+| `AlertCloseButton` | `<button>` (self-closing) | `.btn-close` |
+
+### Button
+
+
+```ruby
+# Standard button
+btn = ElementComponent::Components::Button.new(variant: :primary) { add_content("Click") }
+# => <button class="btn btn-primary" type="button">Click</button>
+
+# Outline variant
+btn = ElementComponent::Components::Button.new(variant: :danger, outline: true) { add_content("Delete") }
+# => <button class="btn btn-outline-danger" type="button">Delete</button>
+
+# As a link
+btn = ElementComponent::Components::Button.new(variant: :primary, href: "/home") { add_content("Home") }
+# => <a class="btn btn-primary" href="/home">Home</a>
+```
+
+**Options**: `variant` (primary/secondary/success/danger/warning/info/light/dark/link), `outline`, `size` (sm/lg), `href`
+
+### Badge
+
+
+```ruby
+badge = ElementComponent::Components::Badge.new(variant: :primary) { add_content("New") }
+# => <span class="badge bg-primary">New</span>
+
+pill = ElementComponent::Components::Badge.new(variant: :danger, pill: true) { add_content("99+") }
+# => <span class="badge bg-danger rounded-pill">99+</span>
+```
+
+### Card
+
+
+```ruby
+card = ElementComponent::Components::Card.new do
+  add_content(ElementComponent::Components::CardImage.new(src: "photo.jpg", top: true))
+  add_content(ElementComponent::Components::CardBody.new do
+    add_content(ElementComponent::Components::CardTitle.new { add_content("Title") })
+    add_content(ElementComponent::Components::CardText.new { add_content("Some text.") })
+  end)
+  add_content(ElementComponent::Components::CardFooter.new { add_content("Footer") })
+end
+```
+
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `CardHeader` | `<div>` | `.card-header` |
+| `CardBody` | `<div>` | `.card-body` |
+| `CardFooter` | `<div>` | `.card-footer` |
+| `CardTitle` | `<h5>` | `.card-title` |
+| `CardText` | `<p>` | `.card-text` |
+| `CardImage` | `<img>` (self-closing) | `.card-img[-top\|-bottom]` |
+
+### Nav
+
+
+```ruby
+nav = ElementComponent::Components::Nav.new(type: :tabs) do
+  add_content(ElementComponent::Components::NavItem.new do
+    add_content(ElementComponent::Components::NavLink.new(href: "/", active: true) { add_content("Home") })
+  end)
+  add_content(ElementComponent::Components::NavItem.new do
+    add_content(ElementComponent::Components::NavLink.new(href: "/profile") { add_content("Profile") })
+  end)
+end
+# => <ul class="nav nav-tabs">...</ul>
+```
+
+**Options**: `type` (tabs/pills/underline), `fill`, `justified`, `vertical`
+
+### Breadcrumb
+
+
+```ruby
+crumb = ElementComponent::Components::Breadcrumb.new do
+  add_content(ElementComponent::Components::BreadcrumbItem.new(href: "/") { add_content("Home") })
+  add_content(ElementComponent::Components::BreadcrumbItem.new(href: "/section") { add_content("Section") })
+  add_content(ElementComponent::Components::BreadcrumbItem.new(active: true) { add_content("Current") })
+end
+# => <nav aria-label="breadcrumb"><ol class="breadcrumb">...</ol></nav>
+```
+
+### ListGroup
+
+
+```ruby
+list = ElementComponent::Components::ListGroup.new(flush: true) do
+  add_content(ElementComponent::Components::ListGroupItem.new { add_content("Item 1") })
+  add_content(ElementComponent::Components::ListGroupItem.new(active: true) { add_content("Item 2") })
+  add_content(ElementComponent::Components::ListGroupItem.new(href: "/link") { add_content("Link") })
+end
+# => <ul class="list-group list-group-flush">...</ul>
+```
+
+**Options**: `flush`, `numbered`; `ListGroupItem` options: `variant`, `active`, `disabled`, `href`
+
+### Progress
+
+
+```ruby
+progress = ElementComponent::Components::Progress.new do
+  add_content(ElementComponent::Components::ProgressBar.new(value: 75, variant: :success, striped: true) do
+    add_content("75%")
+  end)
+end
+# => <div class="progress" role="progressbar"><div class="progress-bar bg-success progress-bar-striped" ...>75%</div></div>
+```
+
+### Spinner
+
+
+```ruby
+border = ElementComponent::Components::Spinner.new(type: :border, variant: :primary)
+# => <div class="spinner-border text-primary" role="status"></div>
+
+grow = ElementComponent::Components::Spinner.new(type: :grow, variant: :success)
+# => <div class="spinner-grow text-success" role="status"></div>
+```
+
+### Table
+
+
+```ruby
+table = ElementComponent::Components::Table.new(striped: true, bordered: true, hover: true) do
+  add_content("<thead><tr><th>Name</th><th>Age</th></tr></thead>")
+  add_content("<tbody><tr><td>John</td><td>30</td></tr></tbody>")
+end
+# => <table class="table table-striped table-bordered table-hover">...</table>
+```
+
+**Options**: `striped`, `bordered`, `hover`, `small`, `variant`
+
+### Pagination
+
+
+```ruby
+nav = ElementComponent::Components::Pagination.new(size: :lg) do
+  add_content(ElementComponent::Components::PageItem.new(active: true) { add_content("1") })
+  add_content(ElementComponent::Components::PageItem.new { add_content("2") })
+end
+# => <nav aria-label="Pagination"><ul class="pagination pagination-lg">...</ul></nav>
+```
+
+### ButtonGroup
+
+
+```ruby
+group = ElementComponent::Components::ButtonGroup.new do
+  add_content(ElementComponent::Components::Button.new(variant: :primary) { add_content("Left") })
+  add_content(ElementComponent::Components::Button.new(variant: :primary) { add_content("Middle") })
+  add_content(ElementComponent::Components::Button.new(variant: :primary) { add_content("Right") })
+end
+# => <div class="btn-group" role="group">...</div>
+```
+
+**Options**: `size` (sm/lg), `vertical`
+
+### CloseButton
+
+
+```ruby
+btn = ElementComponent::Components::CloseButton.new
+# => <button class="btn-close" type="button" aria-label="Close">
+
+disabled = ElementComponent::Components::CloseButton.new(disabled: true)
+# => <button class="btn-close" type="button" aria-label="Close" disabled>
+```
+
+### Modal
+
+
+```ruby
+modal = ElementComponent::Components::Modal.new(id: "exampleModal") do
+  add_content(ElementComponent::Components::ModalContent.new do
+    add_content(ElementComponent::Components::ModalHeader.new do
+      add_content(ElementComponent::Components::ModalTitle.new { add_content("Modal title") })
+    end)
+    add_content(ElementComponent::Components::ModalBody.new { add_content("Modal body text.") })
+    add_content(ElementComponent::Components::ModalFooter.new do
+      add_content(ElementComponent::Components::Button.new(variant: :secondary) { add_content("Close") })
+      add_content(ElementComponent::Components::Button.new(variant: :primary) { add_content("Save") })
+    end)
+  end)
+end
+```
+
+**Options**: `fade`, `static`, `scrollable`, `centered`, `size` (sm/lg/xl), `fullscreen`
+
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `ModalDialog` | `<div>` | `.modal-dialog` |
+| `ModalContent` | `<div>` | `.modal-content` |
+| `ModalHeader` | `<div>` | `.modal-header` |
+| `ModalTitle` | `<h5>` | `.modal-title` |
+| `ModalBody` | `<div>` | `.modal-body` |
+| `ModalFooter` | `<div>` | `.modal-footer` |
+
+### Carousel
+
+
+```ruby
+carousel = ElementComponent::Components::Carousel.new(id: "slides") do
+  add_content(ElementComponent::Components::CarouselItem.new(active: true) do
+    add_content(%(<img src="slide1.jpg" class="d-block w-100" alt="...">))
+  end)
+  add_content(ElementComponent::Components::CarouselItem.new do
+    add_content(%(<img src="slide2.jpg" class="d-block w-100" alt="...">))
+  end)
+end
+```
+
+**Options**: `fade` (crossfade), `indicators`, `controls`; indicators and navigation controls are auto-generated
+
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `CarouselItem` | `<div>` | `.carousel-item` |
+| `CarouselCaption` | `<div>` | `.carousel-caption` |
+
+### Dropdown
+
+
+```ruby
+dropdown = ElementComponent::Components::Dropdown.new do
+  add_content(
+    ElementComponent::Element.new("button",
+      class: "btn btn-secondary dropdown-toggle",
+      type: "button",
+      "data-bs-toggle": "dropdown",
+      "aria-expanded": "false") { add_content("Dropdown") }
+  )
+  add_content(
+    ElementComponent::Components::DropdownMenu.new do
+      add_content(ElementComponent::Components::DropdownItem.new { add_content("Action") })
+      add_content(ElementComponent::Components::DropdownItem.new(active: true) { add_content("Active") })
+      add_content(ElementComponent::Components::DropdownDivider.new)
+      add_content(ElementComponent::Components::DropdownItem.new(disabled: true) { add_content("Disabled") })
+    end
+  )
+end
+```
+
+**Options**: `direction` (dropup/dropend/dropstart)
+
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `DropdownMenu` | `<ul>` | `.dropdown-menu` |
+| `DropdownItem` | `<li>` → `<a>`/`<button>` | `.dropdown-item` |
+| `DropdownDivider` | `<li>` → `<hr>` | `.dropdown-divider` |
+| `DropdownHeader` | `<li>` → `<h6>` | `.dropdown-header` |
+
+### Navbar
+
+
+```ruby
+navbar = ElementComponent::Components::Navbar.new(theme: :dark, background: :dark) do
+  add_content(ElementComponent::Components::NavbarBrand.new(href: "/") { add_content("Brand") })
+  add_content(ElementComponent::Components::NavbarToggler.new(target: "nav"))
+  add_content(ElementComponent::Components::NavbarCollapse.new(id: "nav") do
+    add_content(ElementComponent::Components::NavbarNav.new do
+      add_content(ElementComponent::Components::NavItem.new do
+        add_content(ElementComponent::Components::NavLink.new(href: "/", active: true) { add_content("Home") })
+      end)
+      add_content(ElementComponent::Components::NavItem.new do
+        add_content(ElementComponent::Components::NavLink.new(href: "/about") { add_content("About") })
+      end)
+    end)
+  end)
+end
+```
+
+**Options**: `expand` (sm/md/lg/xl/xxl), `theme` (light/dark), `background`, `fixed` (top/bottom), `sticky` (top/bottom), `container`
+
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `NavbarBrand` | `<a>` | `.navbar-brand` |
+| `NavbarToggler` | `<button>` (self-closing) | `.navbar-toggler` |
+| `NavbarCollapse` | `<div>` | `.collapse .navbar-collapse` |
+| `NavbarNav` | `<ul>` | `.navbar-nav` |
 
 ## 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
+ruby examples/button_example.rb # Run Button examples
+ruby examples/card_example.rb   # Run Card examples
+# See all examples in the examples/ directory
+```
+
+### 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
-- [ ] Enhanced DSL for nested structures
+- [x] Pre-built Bootstrap components (Alert, Badge, Breadcrumb, Button, ButtonGroup, Card, Carousel, CloseButton, Dropdown, ListGroup, Modal, Nav, Navbar, Pagination, Progress, Spinner, Table)
 
 ## Contributing