element_component 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c74ab0abe47013ad19304fcd1ad108855de1c85fdb4d7406e141d1797343d038
-  data.tar.gz: 6b77e4cf5c1c73f90c251d45b6a83bde06aaf052452850bac7463f437c5c604e
+  metadata.gz: b327f66396580a4106a123f22a80cf6edb726a1d98b5b47dcea4f00d4df8649a
+  data.tar.gz: 2ba097718efa76c3418a62657eb9f2f897d67501a88f9942d8b002d7ac783acf
 SHA512:
-  metadata.gz: dbf84809def7f1bd6b2ea85ebdafa81f217254bcba2505f123487063029d962cfd6c2379fe3dd308030cbb8ed97e800746fdbf2fe229888aaee53eeffa868d7c
-  data.tar.gz: '039a7ccd1efb00032379fc3465a4f9c4b52feb7df276ad581a92d57f4970d9c471e65c8e37d545bfc81889e98793e4d8c97b8bd296adbdb1f97fe269d84ae36a'
+  metadata.gz: 83f7331b27128641ca774e75f5fd4e8ee4681402630f0091c31f27afe2397523e530e529ffb8481504555196a94ea530de820dbb278e03e9773eaf7a2bf55aa9
+  data.tar.gz: 988bada7149ec432984c71638e3cf4a53f309910093d10cebaf6a30ee13ff524697ebf19c7118c96625ff94575068eb5660c71902d992847943fa786b692a943

data/AGENTS.md

@@ -12,6 +12,7 @@ lib/
     version.rb                      # VERSION constant
     element.rb                      # Core Element class
     components.rb                   # Component index, requires all components
+    aliases.rb                      # Namespace aliases and shortcuts
     components/
       alert.rb                      # Alert component
       alert/
@@ -76,6 +77,7 @@ spec/
   element_component_spec.rb         # Version check
   lib/
     element_spec.rb                 # Element unit tests
+    aliases_spec.rb                 # Namespace aliases tests
     components/
       alert_spec.rb                 # Alert component tests
       badge_spec.rb                 # Badge component tests
@@ -99,18 +101,56 @@ examples/
   alert_example.rb                  # Complete Alert usage examples
 ```
 
+## Namespace Aliases
+
+All components and the Element class can be accessed in multiple ways to reduce verbosity:
+
+### 1. Direct aliases (recommended)
+```ruby
+ElementComponent::Card.new("content")
+ElementComponent::Alert.new("message", variant: :success)
+ElementComponent::E.new("div", "content")
+```
+
+### 2. Short module alias
+```ruby
+EC::Card.new("content")
+EC::E.new("span", "text")
+```
+
+### 3. Helper method for generic elements
+```ruby
+ElementComponent.tag("div", "content", class: "container")
+ElementComponent.tag("div") { |e| e.add_content("block") }
+```
+
+### 4. View shortcuts (include in views/helpers)
+```ruby
+class MyView
+  include ElementComponent::Shortcuts
+
+  def render
+    Card.new("content")
+    E.new("span", "text")
+    tag("div", "content")
+  end
+end
+```
+
+**All 48 components are available** via all four access patterns above.
+
 ## Core Classes
 
-### `ElementComponent::Element`
+### `ElementComponent::Element` (alias: `ElementComponent::E`)
 - **Attributes**: `element` (tag name), `attributes` (Hash), `contents` (Array), `html` (rendered output)
-- **Constructor**: `Element.new(tag_name, closing_tag: true, **attributes)`
+- **Constructor**: `Element.new(tag_name, content = nil, closing_tag: true, **attributes, &block)`
 - **Content methods**: `add_content`, `add_content!`, `add_content(&block)` — `content` can be a single value or an Array of values
 - **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.
+Components live under `ElementComponent::Components` (alias: `EC`). Direct aliases are also available under `ElementComponent::`.
 
 | Component | Class | Tag | Key Options |
 |---|---|---|---|
@@ -132,7 +172,8 @@ Components live under `ElementComponent::Components`. Each component folder cont
 | Spinner | `Spinner` | `<div>` | `type` (border/grow), `variant` |
 | Table | `Table` | `<table>` | `striped`, `bordered`, `hover`, `small`, `variant` |
 
-**Alert constructor**: `Alert.new(variant: :primary, dismissible: false, **attributes, &block)`
+**Alert constructor**: `Alert.new(content = nil, variant: :primary, dismissible: false, **attributes, &block)`
+- `content`: optional content string or array, added before block content
 - `variant`: one of `:primary`, `:secondary`, `:success`, `:danger`, `:warning`, `:info`, `:light`, `:dark`
 - `dismissible`: adds `.alert-dismissible` class and appends a `CloseButton`
 - `&block`: block with element parameter for adding content inside the element
@@ -140,18 +181,61 @@ Components live under `ElementComponent::Components`. Each component folder cont
 **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
-- `block.call(self)` lives in `Element#initialize` — passes element to block via block parameter
+- **Constructor pattern**: `def initialize(content = nil, **keyword_args, **attributes, &block)`
+- Call `super("tag_name", &block)` first, then chain `add_attribute` calls, then `add_content(content) if content`
+- Content from the `content` argument is added **before** block content
 - Pass user attributes last via `add_attribute(attributes)`
 
-### Sub-component example pattern:
+### Component constructor pattern:
 
 ```ruby
 class AlertHeading < Element
-  def initialize(**attributes, &block)
-    super("h4", &block)
+  def initialize(content = nil, **attributes)
+    super("h4")
     add_attribute(class: "alert-heading")
-    add_attribute(attributes)
+    add_attribute(attributes) unless attributes.empty?
+    add_content(content) if content
+  end
+end
+```
+
+### Components with internal content (e.g., Alert, ModalHeader):
+
+```ruby
+class Alert < Element
+  def initialize(content = nil, variant: :primary, dismissible: false, **attributes, &block)
+    super("div", &block)
+
+    add_attribute(class: "alert")
+    add_attribute(class: "alert-\#{variant}")
+    add_attribute(class: "alert-dismissible") if dismissible
+    add_attribute(role: "alert")
+
+    add_attribute(attributes) unless attributes.empty?
+    add_content(content) if content              # user content first
+    add_content(AlertCloseButton.new) if dismissible  # internal content after
+  end
+end
+```
+
+### Components with conditional tag names (e.g., Button, ListGroupItem):
+
+```ruby
+class Button < Element
+  def initialize(content = nil, variant: :primary, outline: false, size: nil, href: nil, **attributes, &block)
+    if href
+      super("a", &block)
+      add_attribute(href: href)
+    else
+      super("button", &block)
+      add_attribute(type: "button")
+    end
+
+    add_attribute(class: "btn")
+    add_attribute(class: outline ? "btn-outline-\#{variant}" : "btn-\#{variant}")
+    add_attribute(class: "btn-\#{size}") if size
+    add_attribute(attributes) unless attributes.empty?
+    add_content(content) if content
   end
 end
 ```
@@ -184,6 +268,7 @@ ruby examples/alert_example.rb  # Run Alert examples
 - Test render output as raw HTML strings
 - Test attribute hashes directly
 - Follow existing describe/context/it structure
+- Test new aliases in `spec/lib/aliases_spec.rb`
 
 ## Development Workflow
 
@@ -202,6 +287,13 @@ ruby examples/alert_example.rb  # Run Alert examples
 - 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
+- `content` as first positional argument in all constructors (optional, default `nil`)
+- Content argument is added before block content when both are provided
+- All 48 components are aliased directly under `ElementComponent::` for convenience
+- `ElementComponent::E` is an alias for `ElementComponent::Element`
+- `ElementComponent::EC` is an alias for `ElementComponent::Components`
+- `ElementComponent.tag()` is a helper method for creating generic elements
+- `ElementComponent::Shortcuts` module provides instance methods for use in views/helpers
 
 ## Roadmap Features (from README)
 - Caching support

data/lib/element_component/aliases.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module ElementComponent
+  E = Element
+
+  def self.tag(name, content = nil, **attributes, &)
+    Element.new(name, content, **attributes, &)
+  end
+
+  EC = Components
+
+  Alert = Components::Alert
+  Badge = Components::Badge
+  Breadcrumb = Components::Breadcrumb
+  Button = Components::Button
+  ButtonGroup = Components::ButtonGroup
+  Card = Components::Card
+  Carousel = Components::Carousel
+  CloseButton = Components::CloseButton
+  Dropdown = Components::Dropdown
+  ListGroup = Components::ListGroup
+  Modal = Components::Modal
+  Nav = Components::Nav
+  Navbar = Components::Navbar
+  Pagination = Components::Pagination
+  Progress = Components::Progress
+  Spinner = Components::Spinner
+  Table = Components::Table
+
+  AlertHeading = Components::AlertHeading
+  AlertLink = Components::AlertLink
+  AlertCloseButton = Components::AlertCloseButton
+  BreadcrumbItem = Components::BreadcrumbItem
+  CardHeader = Components::CardHeader
+  CardBody = Components::CardBody
+  CardFooter = Components::CardFooter
+  CardTitle = Components::CardTitle
+  CardText = Components::CardText
+  CardImage = Components::CardImage
+  CarouselItem = Components::CarouselItem
+  CarouselCaption = Components::CarouselCaption
+  DropdownMenu = Components::DropdownMenu
+  DropdownItem = Components::DropdownItem
+  DropdownDivider = Components::DropdownDivider
+  DropdownHeader = Components::DropdownHeader
+  ListGroupItem = Components::ListGroupItem
+  ModalDialog = Components::ModalDialog
+  ModalContent = Components::ModalContent
+  ModalHeader = Components::ModalHeader
+  ModalTitle = Components::ModalTitle
+  ModalBody = Components::ModalBody
+  ModalFooter = Components::ModalFooter
+  NavItem = Components::NavItem
+  NavLink = Components::NavLink
+  NavbarBrand = Components::NavbarBrand
+  NavbarToggler = Components::NavbarToggler
+  NavbarCollapse = Components::NavbarCollapse
+  NavbarNav = Components::NavbarNav
+  PageItem = Components::PageItem
+  ProgressBar = Components::ProgressBar
+
+  # rubocop:disable Naming/MethodName
+  module Shortcuts
+    def Card(...) = ElementComponent::Card.new(...)
+    def Alert(...) = ElementComponent::Alert.new(...)
+    def Badge(...) = ElementComponent::Badge.new(...)
+    def Button(...) = ElementComponent::Button.new(...)
+    def ButtonGroup(...) = ElementComponent::ButtonGroup.new(...)
+    def Breadcrumb(...) = ElementComponent::Breadcrumb.new(...)
+    def Carousel(...) = ElementComponent::Carousel.new(...)
+    def CloseButton(...) = ElementComponent::CloseButton.new(...)
+    def Dropdown(...) = ElementComponent::Dropdown.new(...)
+    def ListGroup(...) = ElementComponent::ListGroup.new(...)
+    def Modal(...) = ElementComponent::Modal.new(...)
+    def Nav(...) = ElementComponent::Nav.new(...)
+    def Navbar(...) = ElementComponent::Navbar.new(...)
+    def Pagination(...) = ElementComponent::Pagination.new(...)
+    def Progress(...) = ElementComponent::Progress.new(...)
+    def Spinner(...) = ElementComponent::Spinner.new(...)
+    def Table(...) = ElementComponent::Table.new(...)
+    def AlertHeading(...) = ElementComponent::AlertHeading.new(...)
+    def AlertLink(...) = ElementComponent::AlertLink.new(...)
+    def AlertCloseButton(...) = ElementComponent::AlertCloseButton.new(...)
+    def BreadcrumbItem(...) = ElementComponent::BreadcrumbItem.new(...)
+    def CardHeader(...) = ElementComponent::CardHeader.new(...)
+    def CardBody(...) = ElementComponent::CardBody.new(...)
+    def CardFooter(...) = ElementComponent::CardFooter.new(...)
+    def CardTitle(...) = ElementComponent::CardTitle.new(...)
+    def CardText(...) = ElementComponent::CardText.new(...)
+    def CardImage(...) = ElementComponent::CardImage.new(...)
+    def CarouselItem(...) = ElementComponent::CarouselItem.new(...)
+    def CarouselCaption(...) = ElementComponent::CarouselCaption.new(...)
+    def DropdownMenu(...) = ElementComponent::DropdownMenu.new(...)
+    def DropdownItem(...) = ElementComponent::DropdownItem.new(...)
+    def DropdownDivider(...) = ElementComponent::DropdownDivider.new(...)
+    def DropdownHeader(...) = ElementComponent::DropdownHeader.new(...)
+    def ListGroupItem(...) = ElementComponent::ListGroupItem.new(...)
+    def ModalDialog(...) = ElementComponent::ModalDialog.new(...)
+    def ModalContent(...) = ElementComponent::ModalContent.new(...)
+    def ModalHeader(...) = ElementComponent::ModalHeader.new(...)
+    def ModalTitle(...) = ElementComponent::ModalTitle.new(...)
+    def ModalBody(...) = ElementComponent::ModalBody.new(...)
+    def ModalFooter(...) = ElementComponent::ModalFooter.new(...)
+    def NavItem(...) = ElementComponent::NavItem.new(...)
+    def NavLink(...) = ElementComponent::NavLink.new(...)
+    def NavbarBrand(...) = ElementComponent::NavbarBrand.new(...)
+    def NavbarToggler(...) = ElementComponent::NavbarToggler.new(...)
+    def NavbarCollapse(...) = ElementComponent::NavbarCollapse.new(...)
+    def NavbarNav(...) = ElementComponent::NavbarNav.new(...)
+    def PageItem(...) = ElementComponent::PageItem.new(...)
+    def ProgressBar(...) = ElementComponent::ProgressBar.new(...)
+    def E(...) = ElementComponent::E.new(...)
+    def tag(...) = ElementComponent.tag(...)
+  end
+  # rubocop:enable Naming/MethodName
+end

data/lib/element_component/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElementComponent
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/element_component.rb

@@ -3,6 +3,7 @@
 require_relative "element_component/version"
 require_relative "element_component/element"
 require_relative "element_component/components"
+require_relative "element_component/aliases"
 
 module ElementComponent
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: element_component
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - João Paulo Correia
@@ -40,6 +40,7 @@ files:
 - examples/spinner_example.rb
 - examples/table_example.rb
 - lib/element_component.rb
+- lib/element_component/aliases.rb
 - lib/element_component/components.rb
 - lib/element_component/components/alert.rb
 - lib/element_component/components/alert/close_button.rb