Class: BetterUi::HeadingComponent

Inherits:

Object
ViewComponent::Base
ApplicationComponent
BetterUi::HeadingComponent

show all

Defined in:: app/components/better_ui/heading_component.rb

Overview

A flexible heading component for rendering semantic HTML headings with optional subtitle, actions, divider, and color variant support.

This component renders headings (h1-h6) with consistent typography, alignment, and optional subtitle text. It supports an actions slot for placing buttons or other controls alongside the heading.

Examples:

Basic heading

<%= render BetterUi::HeadingComponent.new(level: :h2) { "Page Title" } %>

Heading with subtitle

<%= render BetterUi::HeadingComponent.new(level: :h1, subtitle: "A brief description") { "Dashboard" } %>

Heading with actions slot

<%= render BetterUi::HeadingComponent.new(level: :h2) do |heading| %>
  <% heading.with_actions do %>
    <%= render BetterUi::ButtonComponent.new(variant: :primary) { "Add New" } %>
  <% end %>
  Page Title
<% end %>

Heading with divider and variant

<%= render BetterUi::HeadingComponent.new(level: :h3, variant: :primary, divider: true) { "Section Title" } %>

Heading with rich subtitle slot

<%= render BetterUi::HeadingComponent.new(level: :h2) do |heading| %>
  <% heading.with_subtitle do %>
    Rich subtitle content
  <% end %>
  Page Title
<% end %>

Constant Summary collapse

LEVELS = Available heading levels

%i[h1 h2 h3 h4 h5 h6].freeze

ALIGNMENTS = Available alignment options

%i[left center right].freeze

Constants inherited from ApplicationComponent

ApplicationComponent::SHADOWS, ApplicationComponent::VARIANTS, ApplicationComponent::VARIANT_BODY_DIVIDE, ApplicationComponent::VARIANT_DIVIDE, ApplicationComponent::VARIANT_HEADER_BG, ApplicationComponent::VARIANT_HEADER_TEXT, ApplicationComponent::VARIANT_HIGHLIGHTED, ApplicationComponent::VARIANT_HOVERABLE, ApplicationComponent::VARIANT_RING, ApplicationComponent::VARIANT_SORT_ICON, ApplicationComponent::VARIANT_STRIPED

Instance Method Summary collapse

#initialize(level: :h2, subtitle: nil, divider: false, variant: nil, align: :left, container_classes: nil, **options) ⇒ HeadingComponent constructor
Initializes a new heading component.
#with_actions ⇒ Object
Slot for rendering action buttons or controls aligned to the right of the heading.
#with_subtitle ⇒ Object
Slot for rendering rich subtitle content below the heading.

Constructor Details

#initialize(level: :h2, subtitle: nil, divider: false, variant: nil, align: :left, container_classes: nil, **options) ⇒ `HeadingComponent`

Initializes a new heading component.

Parameters:

level (Symbol) (defaults to: :h2) —
the heading level (:h1, :h2, :h3, :h4, :h5, :h6), defaults to :h2
subtitle (String, nil) (defaults to: nil) —
subtitle text displayed below the heading
divider (Boolean) (defaults to: false) —
whether to show a divider line below the heading block, defaults to false
variant (Symbol, nil) (defaults to: nil) —
the color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark). Defaults to nil (inherits color from parent).
align (Symbol) (defaults to: :left) —
text alignment (:left, :center, :right), defaults to :left
container_classes (String, nil) (defaults to: nil) —
additional CSS classes for the outer wrapper
options (Hash) —
additional HTML attributes passed to the heading element

Raises:

(ArgumentError) —
if level is not one of the allowed values
(ArgumentError) —
if align is not one of the allowed values
(ArgumentError) —
if variant is provided but not one of the allowed values

# File 'app/components/better_ui/heading_component.rb', line 67

def initialize(
  level: :h2,
  subtitle: nil,
  divider: false,
  variant: nil,
  align: :left,
  container_classes: nil,
  **options
)
  @level = validate_level(level)
  @subtitle_text = subtitle
  @divider = divider
  @variant = variant ? validate_variant(variant) : nil
  @align = validate_align(align)
  @container_classes = container_classes
  @options = options
end

Instance Method Details

#with_actions ⇒ `Object`

Slot for rendering action buttons or controls aligned to the right of the heading.

Yield Returns:

(String) —
the HTML content for the actions area

51	# File 'app/components/better_ui/heading_component.rb', line 51 renders_one :actions

#with_subtitle ⇒ `Object`

Slot for rendering rich subtitle content below the heading. Takes precedence over the subtitle string parameter when both are provided.