element_component 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8b23fff0ff2bf1424f46a3db32fb706973f1601f153dd68f9786018979eb1ef
-  data.tar.gz: 631db1928c37d32d3a82190a0285e9fc85fb32693dc9fdba0fab9f118476fbcb
+  metadata.gz: 9cbfcfb824fb827c1bd03d08c5b2d0eec50fefa7b06c392b3e3393ce07c445be
+  data.tar.gz: ef7c00a35e38318c158fd43397552d37559d62c6996ca2f9a1a0dd05c2e32fc7
 SHA512:
-  metadata.gz: a1cf9210199d4eecaf263df1f99f8862541291cf0fa22fb9c6f92cf55cb1a68f60f72b154503dbce5889a5ffe3c42fd520ce915c7d3e08259d98008692b2d627
-  data.tar.gz: 248a8b0ad689bc29c4c8b9c05b42479c6c613789f87d8992ae34cfbc5d06710955117782eb0db683073e8239b2dfc339c65ffbeb4f46e60414427423e87d8c84
+  metadata.gz: f8297bcae5e86b8201fec505845b928dcf77bcfe4fc28d2d034c29b702446cf0e5566cc82468826b70173aa2392ea4c8b400b9eeeeeabad173923688ff4b5364
+  data.tar.gz: 934369f2c1d3a14b74437f6b71427ae1c92fa4ba3e27054f5755fe793e1442fa3c565783d96ce1cfa209a8cbbd35b5da338688910228240c291736ed9d24d46c

data/AGENTS.md

@@ -44,21 +44,21 @@ Components live under `ElementComponent::Components`. Each component folder cont
 
 | Component | Class | Description |
 |---|---|---|
-| Alert | `Components::Alert` | `.alert` container with context |
+| 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(context: :primary, dismissible: false, **attributes, &block)`
-- `context`: one of `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:light`, `:dark`
+**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
+- `&block`: block with element parameter 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
+- `block.call(self)` lives in `Element#initialize` — passes element to block via block parameter
 - Pass user attributes last via `add_attribute(attributes)`
 
 ### Sub-component example pattern:

data/README.md

@@ -1,6 +1,15 @@
 # ElementComponent
 
-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.
+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 block parameters 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
 
@@ -32,9 +41,9 @@ puts p.render
 Use a block to add content inline:
 
 ```ruby
-div = ElementComponent::Element.new("div", class: "container") do
-  add_content("Welcome")
-  add_content(ElementComponent::Element.new("h1") { add_content("Title") })
+div = ElementComponent::Element.new("div", class: "container") do |e|
+  e.add_content("Welcome")
+  e.add_content(ElementComponent::Element.new("h1") { |h| h.add_content("Title") })
 end
 puts div.render
 # => <div class="container">Welcome<h1>Title</h1></div>
@@ -45,9 +54,9 @@ puts div.render
 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") })
+div = ElementComponent::Element.new("div") do |e|
+  e.add_content(e.new_element("h1") { |h| h.add_content("Hello") })
+  e.add_content(e.new_element("p", class: "lead") { |p| p.add_content("World") })
 end
 puts div.render
 # => <div><h1>Hello</h1><p class="lead">World</p></div>
@@ -64,10 +73,10 @@ div = ElementComponent::Element.new("div")
 div.add_content("plain text")
 
 # Element instance
-div.add_content(ElementComponent::Element.new("span") { add_content("nested") })
+div.add_content(ElementComponent::Element.new("span") { |s| s.add_content("nested") })
 
 # Block (evaluated at render time, has access to new_element)
-div.add_content { new_element("em") { add_content("deferred") } }
+div.add_content { |e| e.new_element("em") { |em| em.add_content("deferred") } }
 
 puts div.render
 # => <div>plain text<span>nested</span><em>deferred</em></div>
@@ -111,59 +120,356 @@ puts div.render
 # => <div class="dynamic">content</div>
 ```
 
-## Pre-built Components
+## 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` |
 
-Components live under `ElementComponent::Components`.
+### Alert
 
-### Alert (Bootstrap 5)
 
 ```ruby
-alert = ElementComponent::Components::Alert.new(context: :success) do
-  add_content("Operation completed!")
+alert = ElementComponent::Components::Alert.new(variant: :success) do |e|
+  e.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`
+**Variants**: `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:light`, `:dark`
 
-#### Dismissible Alert
+Dismissible alerts, headings, and links use sub-components:
 
 ```ruby
-alert = ElementComponent::Components::Alert.new(context: :warning, dismissible: true) do
-  add_content("This can be closed.")
+alert = ElementComponent::Components::Alert.new(variant: :warning, dismissible: true) do |e|
+  e.add_content(ElementComponent::Components::AlertHeading.new { |h| h.add_content("Warning") })
+  e.add_content("Please review. ")
+  e.add_content(ElementComponent::Components::AlertLink.new(href: "/details") { |l| l.add_content("Details") })
 end
-puts alert.render
 # => <div class="alert alert-warning alert-dismissible" role="alert">
-#      This can be closed.
+#      <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>
 ```
 
-#### Alert with Heading and Link
+**Sub-components**:
+
+| Class | Tag | CSS Class |
+|---|---|---|
+| `AlertHeading` | `<h4>` | `.alert-heading` |
+| `AlertLink` | `<a>` | `.alert-link` |
+| `AlertCloseButton` | `<button>` (self-closing) | `.btn-close` |
+
+### Button
+
 
 ```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") })
+# Standard button
+btn = ElementComponent::Components::Button.new(variant: :primary) { |b| b.add_content("Click") }
+# => <button class="btn btn-primary" type="button">Click</button>
+
+# Outline variant
+btn = ElementComponent::Components::Button.new(variant: :danger, outline: true) { |b| b.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") { |b| b.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) { |b| b.add_content("New") }
+# => <span class="badge bg-primary">New</span>
+
+pill = ElementComponent::Components::Badge.new(variant: :danger, pill: true) { |b| b.add_content("99+") }
+# => <span class="badge bg-danger rounded-pill">99+</span>
+```
+
+### Card
+
+
+```ruby
+card = ElementComponent::Components::Card.new do |c|
+  c.add_content(ElementComponent::Components::CardImage.new(src: "photo.jpg", top: true))
+  c.add_content(ElementComponent::Components::CardBody.new do |body|
+    body.add_content(ElementComponent::Components::CardTitle.new { |t| t.add_content("Title") })
+    body.add_content(ElementComponent::Components::CardText.new { |t| t.add_content("Some text.") })
+  end)
+  c.add_content(ElementComponent::Components::CardFooter.new { |f| f.add_content("Footer") })
 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
+**Sub-components**:
 
-| Class | Tag | Class |
+| Class | Tag | CSS Class |
 |---|---|---|
-| `Alert` | `<div>` | `.alert .alert-{context}` |
-| `AlertHeading` | `<h4>` | `.alert-heading` |
-| `AlertLink` | `<a>` | `.alert-link` |
-| `AlertCloseButton` | `<button>` (self-closing) | `.btn-close` |
+| `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 |n|
+  n.add_content(ElementComponent::Components::NavItem.new do |item|
+    item.add_content(ElementComponent::Components::NavLink.new(href: "/", active: true) { |l| l.add_content("Home") })
+  end)
+  n.add_content(ElementComponent::Components::NavItem.new do |item|
+    item.add_content(ElementComponent::Components::NavLink.new(href: "/profile") { |l| l.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 |b|
+  b.add_content(ElementComponent::Components::BreadcrumbItem.new(href: "/") { |i| i.add_content("Home") })
+  b.add_content(ElementComponent::Components::BreadcrumbItem.new(href: "/section") { |i| i.add_content("Section") })
+  b.add_content(ElementComponent::Components::BreadcrumbItem.new(active: true) { |i| i.add_content("Current") })
+end
+# => <nav aria-label="breadcrumb"><ol class="breadcrumb">...</ol></nav>
+```
+
+### ListGroup
+
+
+```ruby
+list = ElementComponent::Components::ListGroup.new(flush: true) do |l|
+  l.add_content(ElementComponent::Components::ListGroupItem.new { |i| i.add_content("Item 1") })
+  l.add_content(ElementComponent::Components::ListGroupItem.new(active: true) { |i| i.add_content("Item 2") })
+  l.add_content(ElementComponent::Components::ListGroupItem.new(href: "/link") { |i| i.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 |p|
+  p.add_content(ElementComponent::Components::ProgressBar.new(value: 75, variant: :success, striped: true) do |bar|
+    bar.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 |t|
+  t.add_content("<thead><tr><th>Name</th><th>Age</th></tr></thead>")
+  t.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 |p|
+  p.add_content(ElementComponent::Components::PageItem.new(active: true) { |i| i.add_content("1") })
+  p.add_content(ElementComponent::Components::PageItem.new { |i| i.add_content("2") })
+end
+# => <nav aria-label="Pagination"><ul class="pagination pagination-lg">...</ul></nav>
+```
+
+### ButtonGroup
+
+
+```ruby
+group = ElementComponent::Components::ButtonGroup.new do |g|
+  g.add_content(ElementComponent::Components::Button.new(variant: :primary) { |b| b.add_content("Left") })
+  g.add_content(ElementComponent::Components::Button.new(variant: :primary) { |b| b.add_content("Middle") })
+  g.add_content(ElementComponent::Components::Button.new(variant: :primary) { |b| b.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 |m|
+  m.add_content(ElementComponent::Components::ModalContent.new do |content|
+    content.add_content(ElementComponent::Components::ModalHeader.new do |header|
+      header.add_content(ElementComponent::Components::ModalTitle.new { |t| t.add_content("Modal title") })
+    end)
+    content.add_content(ElementComponent::Components::ModalBody.new { |body| body.add_content("Modal body text.") })
+    content.add_content(ElementComponent::Components::ModalFooter.new do |footer|
+      footer.add_content(ElementComponent::Components::Button.new(variant: :secondary) { |b| b.add_content("Close") })
+      footer.add_content(ElementComponent::Components::Button.new(variant: :primary) { |b| b.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 |c|
+  c.add_content(ElementComponent::Components::CarouselItem.new(active: true) do |item|
+    item.add_content(%(<img src="slide1.jpg" class="d-block w-100" alt="...">))
+  end)
+  c.add_content(ElementComponent::Components::CarouselItem.new do |item|
+    item.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 |d|
+  d.add_content(
+    ElementComponent::Element.new("button",
+      class: "btn btn-secondary dropdown-toggle",
+      type: "button",
+      "data-bs-toggle": "dropdown",
+      "aria-expanded": "false") { |b| b.add_content("Dropdown") }
+  )
+  d.add_content(
+    ElementComponent::Components::DropdownMenu.new do |menu|
+      menu.add_content(ElementComponent::Components::DropdownItem.new { |i| i.add_content("Action") })
+      menu.add_content(ElementComponent::Components::DropdownItem.new(active: true) { |i| i.add_content("Active") })
+      menu.add_content(ElementComponent::Components::DropdownDivider.new)
+      menu.add_content(ElementComponent::Components::DropdownItem.new(disabled: true) { |i| i.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 |n|
+  n.add_content(ElementComponent::Components::NavbarBrand.new(href: "/") { |b| b.add_content("Brand") })
+  n.add_content(ElementComponent::Components::NavbarToggler.new(target: "nav"))
+  n.add_content(ElementComponent::Components::NavbarCollapse.new(id: "nav") do |collapse|
+    collapse.add_content(ElementComponent::Components::NavbarNav.new do |nav|
+      nav.add_content(ElementComponent::Components::NavItem.new do |item|
+        item.add_content(ElementComponent::Components::NavLink.new(href: "/", active: true) { |l| l.add_content("Home") })
+      end)
+      nav.add_content(ElementComponent::Components::NavItem.new do |item|
+        item.add_content(ElementComponent::Components::NavLink.new(href: "/about") { |l| l.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
 
@@ -174,6 +480,9 @@ 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
@@ -196,9 +505,7 @@ 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 (more)
-- [ ] 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
 

data/examples/alert_example.rb

@@ -5,19 +5,19 @@ require_relative "../lib/element_component"
 # =============================================================================
 # Basic Alert
 # =============================================================================
-alert = ElementComponent::Components::Alert.new(context: :success)
+alert = ElementComponent::Components::Alert.new(variant: :success)
 alert.add_content("Operation completed successfully!")
 puts "=== Basic Alert ==="
 puts alert.render
 puts
 
 # =============================================================================
-# All Contexts
+# All Variants
 # =============================================================================
 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.")
+ElementComponent::Components::Alert::VALID_VARIANTS.each do |variant|
+  alert = ElementComponent::Components::Alert.new(variant: variant)
+  alert.add_content("#{variant.capitalize} alert message here.")
   puts alert.render
 end
 puts
@@ -25,8 +25,8 @@ 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.")
+alert = ElementComponent::Components::Alert.new(variant: :warning, dismissible: true) do |e|
+  e.add_content("This alert can be dismissed.")
 end
 puts "=== Dismissible Alert ==="
 puts alert.render
@@ -36,7 +36,7 @@ puts
 # Alert with Custom Attributes
 # =============================================================================
 alert = ElementComponent::Components::Alert.new(
-  context: :primary,
+  variant: :primary,
   id: "main-alert",
   style: "margin-top: 20px;"
 )
@@ -48,10 +48,10 @@ 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") })
+alert = ElementComponent::Components::Alert.new(variant: :info) do |e|
+  e.add_content(ElementComponent::Components::AlertHeading.new.tap { |h| h.add_content("Information") })
+  e.add_content("This is an important notice. ")
+  e.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
@@ -60,10 +60,10 @@ 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|
+alert = ElementComponent::Components::Alert.new(variant: :danger, dismissible: true) do |e|
+  e.add_content(ElementComponent::Components::AlertHeading.new.tap { |h| h.add_content("Error!") })
+  e.add_content("Something went wrong. ")
+  e.add_content(ElementComponent::Components::AlertLink.new(href: "/support").tap do |l|
     l.add_content("Contact support")
   end)
 end
@@ -74,7 +74,7 @@ puts
 # =============================================================================
 # Chained API Usage
 # =============================================================================
-alert = ElementComponent::Components::Alert.new(context: :secondary)
+alert = ElementComponent::Components::Alert.new(variant: :secondary)
                                            .add_content("This alert was built using chained calls.")
 puts "=== Chained API ==="
 puts alert.render

data/examples/badge_example.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../lib/element_component"
+
+# =============================================================================
+# Basic Badge
+# =============================================================================
+badge = ElementComponent::Components::Badge.new(variant: :primary)
+badge.add_content("New")
+puts "=== Basic Badge ==="
+puts badge.render
+puts
+
+# =============================================================================
+# Pill Badge
+# =============================================================================
+badge = ElementComponent::Components::Badge.new(variant: :danger, pill: true)
+badge.add_content("99+")
+puts "=== Pill Badge ==="
+puts badge.render
+puts
+
+# =============================================================================
+# All Contexts
+# =============================================================================
+puts "=== All Badge Variants ==="
+ElementComponent::Components::Badge::VALID_VARIANTS.each do |variant|
+  badge = ElementComponent::Components::Badge.new(variant: variant)
+  badge.add_content(variant.to_s.capitalize)
+  puts badge.render
+end
+puts
+
+# =============================================================================
+# Badge with Block
+# =============================================================================
+badge = ElementComponent::Components::Badge.new(variant: :success) do |b|
+  b.add_content("Completed")
+end
+puts "=== Badge with Block ==="
+puts badge.render
+puts
+
+# =============================================================================
+# Chained API
+# =============================================================================
+badge = ElementComponent::Components::Badge.new(variant: :warning)
+                                           .add_content("Warning")
+puts "=== Chained API ==="
+puts badge.render
+puts
+
+# =============================================================================
+# Badge with Custom Attributes
+# =============================================================================
+badge = ElementComponent::Components::Badge.new(
+  variant: :info,
+  id: "badge-1",
+  style: "font-size: 1.2em;"
+)
+badge.add_content("Custom")
+puts "=== Badge with Custom Attributes ==="
+puts badge.render