better_ui 0.7.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64c0ed9d31f8392770eaedb20fe0727444877a4fa8886b6241bf70c5d093b03e
-  data.tar.gz: bbf85b45c167057d13b403d3270eb0bf744cab5d1b2646ee3c6ed88c6cdfceca
+  metadata.gz: 2c218661dc93efb93042ba9a4a5277091a7dac3de216acc162d50c8d36077bc8
+  data.tar.gz: b06ea500b4d3c547249664dcee953910457263029549d77af2a3314cef45ef58
 SHA512:
-  metadata.gz: 9fa81ccba17b2fc8bf7922ebb4e41a38328cd8439d851008dce1eb1a9b06e47b0481db570f2377ca4a69b65ae91814306584ec24f0d1514e2114763b34db4d89
-  data.tar.gz: 92ac9e0d3d760f148f25c0b0fa11e2d57aa7d56d8cf367df637b2521deb8f7bdc11b59063e8fd523e11db0c3de4d8276e824ef1388fada0c71199c4fe05d5395
+  metadata.gz: 238ed43c059619f7f8ab17ffcc28aa6e6d461b1de72a7bfe57a9a188da44e4f810381ad2c0aac5118b79013855f985635f4bbc01355558640a7f3cb377695fd9
+  data.tar.gz: 5a8971012b178358d34198642446a423da9ccee69f6418f6d2cc3bc77529bb96a4185e5f281d14b0a6d83fd5195cc20255e61664c7fa4899ef2c06758b63b04e

data/README.md

@@ -44,13 +44,9 @@ registerControllers(application)
 /* @import "@pandev-srl/better-ui/utilities"; */
 ```
 
+**Start using components** - `bui_*` helpers are available automatically:
 ```erb
-<!-- In your views -->
-<%= render BetterUi::ButtonComponent.new(
-  label: "Get Started",
-  variant: "primary",
-  size: "lg"
-) %>
+<%= bui_button(label: "Get Started", variant: :primary, size: :lg) %>
 ```
 
 ## Features
@@ -59,6 +55,7 @@ registerControllers(application)
 - **ViewComponent Architecture**: Encapsulated, testable, and reusable components
 - **Tailwind CSS v4**: Leverages the latest Tailwind features with OKLCH color space
 - **Fully Customizable**: 9 semantic color variants with complete theme control
+- **View Helpers**: Concise `bui_*` helpers available automatically (no setup required)
 - **Form Builder Integration**: Seamless integration with Rails forms via `UiFormBuilder`
 - **Stimulus Controllers**: Interactive components with built-in JavaScript behaviors
 - **Accessible by Default**: ARIA attributes and keyboard navigation support
@@ -72,7 +69,7 @@ For detailed installation and configuration instructions, see the [Installation
 
 - Rails 8.1.1 or higher
 - Node.js and npm (for Tailwind CSS)
-- Tailwind CSS v4 (currently in beta)
+- Tailwind CSS v4
 
 ## Component Overview
 
@@ -86,11 +83,7 @@ A versatile button component with multiple styles, sizes, and states.
 - **Features**: Loading states, icons, disabled states
 
 ```erb
-<%= render BetterUi::ButtonComponent.new(
-  label: "Save Changes",
-  variant: "success",
-  style: "solid"
-) do |c| %>
+<%= bui_button(label: "Save Changes", variant: :success, style: :solid) do |c| %>
   <% c.with_icon_before { "💾" } %>
 <% end %>
 ```
@@ -103,7 +96,7 @@ A flexible container component with customizable padding and optional slots.
 - **Slots**: header, body, footer
 
 ```erb
-<%= render BetterUi::CardComponent.new(size: :lg, style: :bordered) do |c| %>
+<%= bui_card(size: :lg, style: :bordered) do |c| %>
   <% c.with_header { "Card Title" } %>
   <% c.with_body { "Card content goes here" } %>
   <% c.with_footer { "Footer content" } %>
@@ -117,8 +110,8 @@ Display notifications, alerts, and validation messages with style.
 - **Features**: Dismissible, auto-dismiss, titles, icons
 
 ```erb
-<%= render BetterUi::ActionMessagesComponent.new(
-  variant: "danger",
+<%= bui_action_messages(
+  variant: :danger,
   title: "Validation Errors",
   messages: @model.errors.full_messages,
   dismissible: true,
@@ -132,7 +125,7 @@ Display notifications, alerts, and validation messages with style.
 Standard text input with error handling and icon support.
 
 ```erb
-<%= render BetterUi::Forms::TextInputComponent.new(
+<%= bui_text_input(
   name: "user[email]",
   label: "Email Address",
   hint: "We'll never share your email",
@@ -146,7 +139,7 @@ Standard text input with error handling and icon support.
 Numeric input with min/max validation and optional spinners.
 
 ```erb
-<%= render BetterUi::Forms::NumberInputComponent.new(
+<%= bui_number_input(
   name: "product[price]",
   label: "Price",
   min: 0,
@@ -161,7 +154,7 @@ Numeric input with min/max validation and optional spinners.
 Password field with visibility toggle functionality.
 
 ```erb
-<%= render BetterUi::Forms::PasswordInputComponent.new(
+<%= bui_password_input(
   name: "user[password]",
   label: "Password",
   hint: "Minimum 8 characters"
@@ -172,7 +165,7 @@ Password field with visibility toggle functionality.
 Multi-line text input with resizing options.
 
 ```erb
-<%= render BetterUi::Forms::TextareaComponent.new(
+<%= bui_textarea(
   name: "post[content]",
   label: "Content",
   rows: 6,
@@ -185,7 +178,7 @@ Multi-line text input with resizing options.
 Single checkbox with color variants and label positioning.
 
 ```erb
-<%= render BetterUi::Forms::CheckboxComponent.new(
+<%= bui_checkbox(
   name: "user[terms]",
   label: "I agree to the terms and conditions",
   variant: :primary
@@ -196,7 +189,7 @@ Single checkbox with color variants and label positioning.
 Multiple checkboxes for selecting from a collection.
 
 ```erb
-<%= render BetterUi::Forms::CheckboxGroupComponent.new(
+<%= bui_checkbox_group(
   name: "user[roles]",
   collection: [["Admin", "admin"], ["Editor", "editor"]],
   legend: "User Roles",
@@ -215,13 +208,13 @@ BetterUi provides a complete drawer layout system for building responsive admin
 - **NavGroupComponent**: Grouped navigation with titles
 
 ```erb
-<%= render BetterUi::Drawer::LayoutComponent.new do |layout| %>
+<%= bui_drawer_layout do |layout| %>
   <% layout.with_header do |header| %>
     <% header.with_logo { "MyApp" } %>
   <% end %>
   <% layout.with_sidebar do |sidebar| %>
     <% sidebar.with_navigation do %>
-      <%= render BetterUi::Drawer::NavGroupComponent.new(title: "Menu") do |group| %>
+      <%= bui_drawer_nav_group(title: "Menu") do |group| %>
         <% group.with_item(label: "Dashboard", href: "/", active: true) %>
         <% group.with_item(label: "Settings", href: "/settings") %>
       <% end %>
@@ -237,16 +230,80 @@ BetterUi includes a custom form builder for seamless Rails form integration:
 
 ```erb
 <%= form_with model: @user, builder: BetterUi::UiFormBuilder do |f| %>
-  <%= f.ui_text_input :name %>
-  <%= f.ui_text_input :email, hint: "We'll never share your email" %>
-  <%= f.ui_password_input :password %>
-  <%= f.ui_textarea :bio, rows: 6 %>
-  <%= f.ui_number_input :age, min: 0, max: 120 %>
+  <%= f.bui_text_input :name %>
+  <%= f.bui_text_input :email, hint: "We'll never share your email" %>
+  <%= f.bui_password_input :password %>
+  <%= f.bui_textarea :bio, rows: 6 %>
+  <%= f.bui_number_input :age, min: 0, max: 120 %>
+  <%= f.bui_select :role, [["Admin", "admin"], ["Editor", "editor"]] %>
   <%= f.bui_checkbox :newsletter, label: "Subscribe to newsletter" %>
   <%= f.bui_checkbox_group :roles, [["Admin", "admin"], ["Editor", "editor"]] %>
 <% end %>
 ```
 
+## Available View Helpers
+
+### Core Components
+
+| Helper | Component |
+|--------|-----------|
+| `bui_button` | ButtonComponent |
+| `bui_link` | LinkComponent |
+| `bui_card` | CardComponent |
+| `bui_action_messages` | ActionMessagesComponent |
+| `bui_avatar` | AvatarComponent |
+| `bui_badge` | BadgeComponent |
+| `bui_tag` | TagComponent |
+| `bui_heading` | HeadingComponent |
+| `bui_spinner` | SpinnerComponent |
+| `bui_progress` | ProgressComponent |
+| `bui_divider` | DividerComponent |
+| `bui_tooltip` | TooltipComponent |
+| `bui_container` | ContainerComponent |
+| `bui_fa_icon` | FaIconComponent |
+| `bui_breadcrumb` | Breadcrumb::BreadcrumbComponent |
+
+### Form Components
+
+| Helper | Component |
+|--------|-----------|
+| `bui_text_input` | Forms::TextInputComponent |
+| `bui_email_input` | Forms::TextInputComponent (type: :email) |
+| `bui_tel_input` | Forms::TextInputComponent (type: :tel) |
+| `bui_date_input` | Forms::TextInputComponent (type: :date) |
+| `bui_time_input` | Forms::TextInputComponent (type: :time) |
+| `bui_number_input` | Forms::NumberInputComponent |
+| `bui_password_input` | Forms::PasswordInputComponent |
+| `bui_textarea` | Forms::TextareaComponent |
+| `bui_checkbox` | Forms::CheckboxComponent |
+| `bui_checkbox_group` | Forms::CheckboxGroupComponent |
+| `bui_select` | Forms::SelectComponent |
+
+### Layout & Navigation
+
+| Helper | Component |
+|--------|-----------|
+| `bui_drawer_layout` | Drawer::LayoutComponent |
+| `bui_drawer_sidebar` | Drawer::SidebarComponent |
+| `bui_drawer_header` | Drawer::HeaderComponent |
+| `bui_drawer_nav_item` | Drawer::NavItemComponent |
+| `bui_drawer_nav_group` | Drawer::NavGroupComponent |
+
+### Interactive Components
+
+| Helper | Component |
+|--------|-----------|
+| `bui_dialog` | Dialog::DialogComponent |
+| `bui_dialog_alert` | Dialog::AlertComponent |
+| `bui_dialog_confirm` | Dialog::ConfirmComponent |
+| `bui_dropdown` | Dropdown::DropdownComponent |
+| `bui_tabs` | Tabs::ContainerComponent |
+| `bui_tab` | Tabs::TabComponent |
+| `bui_tab_panel` | Tabs::PanelComponent |
+| `bui_table` | Table::TableComponent |
+
+> **Note**: You can also use ViewComponent directly with `render BetterUi::*Component.new(...)` if you prefer the explicit rendering syntax.
+
 ## Documentation
 
 - [**Installation Guide**](doc/INSTALLATION.md) - Detailed setup and configuration instructions
@@ -343,4 +400,4 @@ Powered by:
 
 ## Acknowledgments
 
-Special thanks to the Ruby on Rails community and all contributors who help make BetterUi better.
+Special thanks to the Ruby on Rails community and all contributors who help make BetterUi better.

data/app/components/better_ui/application_component.rb

@@ -49,8 +49,42 @@ module BetterUi
       dark: 900          # Dark backgrounds and dark text
     }.freeze
 
+    # Shadow size definitions mapping to Tailwind shadow classes.
+    # Used across all components for consistent elevation styling.
+    #
+    # @example Usage in component
+    #   SHADOWS[@shadow] # => "shadow-sm"
+    SHADOWS = {
+      none: nil,
+      sm: "shadow-sm",
+      md: "shadow-md",
+      lg: "shadow-lg",
+      xl: "shadow-xl"
+    }.freeze
+
     private
 
+    # Normalizes a shadow parameter value.
+    # Accepts Symbol sizes (:sm, :md, etc.), booleans for backward compatibility,
+    # or false/nil to disable shadows.
+    #
+    # @param value [Symbol, Boolean] the shadow value to normalize
+    # @param default [Symbol] the default shadow size (used when value is true)
+    # @return [Symbol] normalized shadow key
+    def normalize_shadow(value, default: :sm)
+      case value
+      when false, nil, :none then :none
+      when true then default
+      when Symbol
+        unless SHADOWS.key?(value)
+          raise ArgumentError, "Invalid shadow: #{value}. Must be one of: #{SHADOWS.keys.join(', ')}"
+        end
+        value
+      else
+        raise ArgumentError, "Invalid shadow: #{value}. Must be a Symbol or Boolean"
+      end
+    end
+
     # Helper to merge CSS classes intelligently using TailwindMerge
     # Resolves conflicting Tailwind utility classes
     #

data/app/components/better_ui/avatar_component/avatar_component.html.erb

@@ -0,0 +1,15 @@
+<div class="relative inline-flex <%= @container_classes %>">
+  <% if @src %>
+    <img src="<%= @src %>" alt="<%= alt_text %>" class="<%= component_classes %> object-cover" />
+  <% else %>
+    <div class="<%= component_classes %> flex items-center justify-center font-medium">
+      <%= initials %>
+    </div>
+  <% end %>
+  <% if @status %>
+    <span class="absolute bottom-0 right-0 block <%= status_classes %> rounded-full ring-2 ring-white"></span>
+  <% end %>
+  <% if badge? %>
+    <span class="absolute -top-1 -right-1"><%= badge %></span>
+  <% end %>
+</div>

data/app/components/better_ui/avatar_component.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module BetterUi
+  # An avatar component for displaying user profile images or initials.
+  #
+  # Supports image display, initials fallback from a name, multiple sizes,
+  # shapes, color variants, status indicators, and a badge slot.
+  #
+  # @example With image
+  #   <%= render BetterUi::AvatarComponent.new(src: user.avatar_url, alt: user.name) %>
+  #
+  # @example With initials fallback
+  #   <%= render BetterUi::AvatarComponent.new(name: "John Doe", variant: :primary) %>
+  #
+  # @example With status indicator
+  #   <%= render BetterUi::AvatarComponent.new(
+  #     src: user.avatar_url,
+  #     name: user.name,
+  #     status: :online,
+  #     size: :lg
+  #   ) %>
+  #
+  # @example With badge slot
+  #   <%= render BetterUi::AvatarComponent.new(src: user.avatar_url) do |avatar| %>
+  #     <% avatar.with_badge do %>
+  #       <span class="bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">3</span>
+  #     <% end %>
+  #   <% end %>
+  class AvatarComponent < ApplicationComponent
+    # Size configurations mapping to Tailwind dimension and text classes
+    SIZES = {
+      xs: "w-6 h-6 text-xs",
+      sm: "w-8 h-8 text-sm",
+      md: "w-10 h-10 text-base",
+      lg: "w-14 h-14 text-lg",
+      xl: "w-20 h-20 text-xl"
+    }.freeze
+
+    # Shape configurations mapping to Tailwind border-radius classes
+    SHAPES = {
+      circle: "rounded-full",
+      square: "rounded-none",
+      rounded: "rounded-lg"
+    }.freeze
+
+    # Status indicator colors
+    STATUSES = %i[online offline busy away].freeze
+
+    # Status dot size classes scaled by avatar size
+    STATUS_DOT_SIZES = {
+      xs: "w-2 h-2",
+      sm: "w-2 h-2",
+      md: "w-2.5 h-2.5",
+      lg: "w-3 h-3",
+      xl: "w-4 h-4"
+    }.freeze
+
+    # @!method with_badge
+    #   Slot for rendering an optional badge overlay (e.g., notification count).
+    #   Positioned at top-right of the avatar.
+    #   @yieldreturn [String] the HTML content for the badge
+    renders_one :badge
+
+    # Initializes a new avatar component.
+    #
+    # @param src [String, nil] URL of the avatar image
+    # @param alt [String, nil] Alt text for the image (falls back to name)
+    # @param name [String, nil] Full name used to generate initials fallback
+    # @param variant [Symbol] Color variant for initials background
+    # @param size [Symbol] Avatar size (:xs, :sm, :md, :lg, :xl)
+    # @param shape [Symbol] Avatar shape (:circle, :square, :rounded)
+    # @param status [Symbol, nil] Status indicator (:online, :offline, :busy, :away)
+    # @param container_classes [String, nil] Additional CSS classes for the outer wrapper
+    # @param options [Hash] Additional HTML attributes
+    #
+    # @raise [ArgumentError] if variant, size, shape, or status is invalid
+    def initialize(
+      src: nil,
+      alt: nil,
+      name: nil,
+      variant: :primary,
+      size: :md,
+      shape: :circle,
+      status: nil,
+      container_classes: nil,
+      **options
+    )
+      @src = src
+      @alt = alt
+      @name = name
+      @variant = validate_variant(variant)
+      @size = validate_size(size)
+      @shape = validate_shape(shape)
+      @status = validate_status(status) if status
+      @container_classes = container_classes
+      @options = options
+    end
+
+    private
+
+    attr_reader :src, :alt, :name, :variant, :size, :shape, :status,
+                :container_classes, :options
+
+    # Returns the combined CSS classes for the avatar element (img or div).
+    #
+    # @return [String] merged CSS class string
+    # @api private
+    def component_classes
+      css_classes(
+        SIZES[@size],
+        SHAPES[@shape],
+        variant_classes,
+        @container_classes
+      )
+    end
+
+    # Returns variant-specific background and text color classes for initials mode.
+    # When an image is provided, no variant background is needed.
+    #
+    # @return [String, nil] variant CSS classes or nil
+    # @api private
+    def variant_classes
+      return nil if @src
+
+      case @variant
+      when :primary   then "bg-primary-100 text-primary-700"
+      when :secondary then "bg-secondary-100 text-secondary-700"
+      when :accent    then "bg-accent-100 text-accent-700"
+      when :success   then "bg-success-100 text-success-700"
+      when :danger    then "bg-danger-100 text-danger-700"
+      when :warning   then "bg-warning-100 text-warning-700"
+      when :info      then "bg-info-100 text-info-700"
+      when :light     then "bg-grayscale-100 text-grayscale-700"
+      when :dark      then "bg-grayscale-800 text-grayscale-100"
+      end
+    end
+
+    # Returns CSS classes for the status indicator dot.
+    #
+    # @return [String] combined status color and size classes
+    # @api private
+    def status_classes
+      color = case @status
+      when :online  then "bg-success-500"
+      when :offline then "bg-grayscale-400"
+      when :busy    then "bg-danger-500"
+      when :away    then "bg-warning-500"
+      end
+
+      "#{color} #{STATUS_DOT_SIZES[@size]}"
+    end
+
+    # Extracts initials from the name.
+    # Takes the first letter of the first word and the first letter of the second word (if present).
+    #
+    # @return [String] uppercase initials (e.g., "JD" for "John Doe", "A" for "Alice")
+    # @api private
+    def initials
+      return "" unless @name
+
+      parts = @name.strip.split(/\s+/)
+      result = parts[0][0].to_s
+      result += parts[1][0].to_s if parts.length > 1
+      result.upcase
+    end
+
+    # Returns the alt text for the image, falling back to name.
+    #
+    # @return [String, nil] alt text
+    # @api private
+    def alt_text
+      @alt || @name
+    end
+
+    # Validates the variant parameter.
+    #
+    # @param variant [Symbol] the variant to validate
+    # @return [Symbol] the validated variant
+    # @raise [ArgumentError] if variant is invalid
+    # @api private
+    def validate_variant(variant)
+      unless BetterUi::ApplicationComponent::VARIANTS.key?(variant)
+        raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{BetterUi::ApplicationComponent::VARIANTS.keys.join(', ')}"
+      end
+      variant
+    end
+
+    # Validates the size parameter.
+    #
+    # @param size [Symbol] the size to validate
+    # @return [Symbol] the validated size
+    # @raise [ArgumentError] if size is invalid
+    # @api private
+    def validate_size(size)
+      unless SIZES.key?(size)
+        raise ArgumentError, "Invalid size: #{size}. Must be one of: #{SIZES.keys.join(', ')}"
+      end
+      size
+    end
+
+    # Validates the shape parameter.
+    #
+    # @param shape [Symbol] the shape to validate
+    # @return [Symbol] the validated shape
+    # @raise [ArgumentError] if shape is invalid
+    # @api private
+    def validate_shape(shape)
+      unless SHAPES.key?(shape)
+        raise ArgumentError, "Invalid shape: #{shape}. Must be one of: #{SHAPES.keys.join(', ')}"
+      end
+      shape
+    end
+
+    # Validates the status parameter.
+    #
+    # @param status [Symbol] the status to validate
+    # @return [Symbol] the validated status
+    # @raise [ArgumentError] if status is invalid
+    # @api private
+    def validate_status(status)
+      unless STATUSES.include?(status)
+        raise ArgumentError, "Invalid status: #{status}. Must be one of: #{STATUSES.join(', ')}"
+      end
+      status
+    end
+  end
+end

data/app/components/better_ui/badge_component/badge_component.html.erb

@@ -0,0 +1,16 @@
+<span <%= tag.attributes(component_attributes) %> class="<%= component_classes %>">
+  <% if dot %>
+    <span class="w-2 h-2 rounded-full <%= dot_classes %>"></span>
+  <% else %>
+    <% if icon_before? %>
+      <span class="inline-flex items-center <%= SIZES[size][:icon] %>">
+        <%= icon_before %>
+      </span>
+    <% end %>
+    <% if counter %>
+      <%= counter %>
+    <% else %>
+      <%= content %>
+    <% end %>
+  <% end %>
+</span>

data/app/components/better_ui/badge_component.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module BetterUi
+  class BadgeComponent < ApplicationComponent
+    include BetterUi::Concerns::InlineLabelStyles
+
+    renders_one :icon_before
+
+    SIZES = {
+      xs: { padding: "px-1.5 py-0.5", text: "text-xs", icon: "w-3 h-3", gap: "gap-1" },
+      sm: { padding: "px-2 py-0.5", text: "text-xs", icon: "w-3.5 h-3.5", gap: "gap-1" },
+      md: { padding: "px-2.5 py-1", text: "text-sm", icon: "w-4 h-4", gap: "gap-1.5" },
+      lg: { padding: "px-3 py-1.5", text: "text-base", icon: "w-5 h-5", gap: "gap-2" }
+    }.freeze
+
+    STYLES = %i[solid outline soft ghost].freeze
+
+    def initialize(
+      variant: :primary,
+      style: :solid,
+      size: :md,
+      pill: true,
+      dot: false,
+      counter: nil,
+      container_classes: nil,
+      **options
+    )
+      @variant = validate_variant(variant)
+      @style = validate_style(style)
+      @size = validate_size(size)
+      @pill = pill
+      @dot = dot
+      @counter = counter
+      @container_classes = container_classes
+      @options = options
+    end
+
+    private
+
+    attr_reader :variant, :style, :size, :pill, :dot, :counter, :container_classes, :options
+
+    def component_classes
+      css_classes([
+        base_classes,
+        style_classes,
+        size_classes,
+        shape_classes,
+        @container_classes
+      ].flatten.compact)
+    end
+
+    def component_attributes
+      @options
+    end
+
+    def base_classes
+      [
+        "inline-flex items-center",
+        "font-medium",
+        "transition-colors duration-200"
+      ]
+    end
+
+    def shape_classes
+      @pill ? "rounded-full" : "rounded-md"
+    end
+
+    def style_classes
+      case @style
+      when :solid then solid_classes
+      when :outline then outline_classes
+      when :soft then soft_classes
+      when :ghost then ghost_classes
+      end
+    end
+
+    def size_classes
+      size_config = SIZES[@size]
+      [
+        size_config[:padding],
+        size_config[:text],
+        size_config[:gap]
+      ]
+    end
+
+    def dot_classes
+      case @variant
+      when :primary   then "bg-primary-600"
+      when :secondary then "bg-secondary-600"
+      when :accent    then "bg-accent-600"
+      when :success   then "bg-success-600"
+      when :danger    then "bg-danger-600"
+      when :warning   then "bg-warning-600"
+      when :info      then "bg-info-600"
+      when :light     then "bg-grayscale-400"
+      when :dark      then "bg-grayscale-900"
+      end
+    end
+
+    def validate_style(style)
+      unless STYLES.include?(style)
+        raise ArgumentError, "Invalid style: #{style}. Must be one of: #{STYLES.join(", ")}"
+      end
+      style
+    end
+
+    def validate_size(size)
+      unless SIZES.key?(size)
+        raise ArgumentError, "Invalid size: #{size}. Must be one of: #{SIZES.keys.join(", ")}"
+      end
+      size
+    end
+  end
+end

data/app/components/better_ui/breadcrumb/breadcrumb_component/breadcrumb_component.html.erb

@@ -0,0 +1,12 @@
+<nav aria-label="Breadcrumb" class="<%= @container_classes %>">
+  <ol class="<%= component_classes %>">
+    <% items.each_with_index do |item, index| %>
+      <li class="inline-flex items-center">
+        <% if index > 0 %>
+          <span class="<%= separator_classes %>" aria-hidden="true"><%= separator_content %></span>
+        <% end %>
+        <%= item %>
+      </li>
+    <% end %>
+  </ol>
+</nav>