better_ui 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b3c7255ce65e6a53ed2ee42174475f656461303920e1a4e6c9912fe3ecd4d4a
-  data.tar.gz: 4c4c5063560d6edcb534fd1856869928e4b3f0456e7d86dea76f216bb3c4ae2e
+  metadata.gz: 2c218661dc93efb93042ba9a4a5277091a7dac3de216acc162d50c8d36077bc8
+  data.tar.gz: b06ea500b4d3c547249664dcee953910457263029549d77af2a3314cef45ef58
 SHA512:
-  metadata.gz: b06273f6f5fbdd050f7f1fcdc20b1a15663af200f25d076472d31c77bc953e39a68db31633de2f64c888e0a0f0459c1fa8b75cefd4dc919bb4a18f2397da09de
-  data.tar.gz: 1ecb849cc505cda578e2c93493dcc8464e52ca3e64d55a618cb3d4181b1d6eb55130c0a3173c93d3761539ac0fd402e0c52a4a3a050b8df291f5dece55095739
+  metadata.gz: 238ed43c059619f7f8ab17ffcc28aa6e6d461b1de72a7bfe57a9a188da44e4f810381ad2c0aac5118b79013855f985635f4bbc01355558640a7f3cb377695fd9
+  data.tar.gz: 5a8971012b178358d34198642446a423da9ccee69f6418f6d2cc3bc77529bb96a4185e5f281d14b0a6d83fd5195cc20255e61664c7fa4899ef2c06758b63b04e

data/README.md

@@ -69,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
 
@@ -230,11 +230,12 @@ 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 %>
@@ -242,23 +243,65 @@ BetterUi includes a custom form builder for seamless Rails form integration:
 
 ## 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

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>

data/app/components/better_ui/breadcrumb/breadcrumb_component.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Breadcrumb
+    # A breadcrumb navigation component that renders an ordered list of items
+    # with configurable separators and sizes.
+    #
+    # This is a compound component that uses ItemComponent for individual breadcrumb items.
+    # The last item (without href) is typically rendered as the current page indicator.
+    #
+    # @example Basic breadcrumb
+    #   <%= render BetterUi::Breadcrumb::BreadcrumbComponent.new do |breadcrumb| %>
+    #     <% breadcrumb.with_item(label: "Home", href: "/") %>
+    #     <% breadcrumb.with_item(label: "Products", href: "/products") %>
+    #     <% breadcrumb.with_item(label: "Widget") %>
+    #   <% end %>
+    #
+    # @example With chevron separator and large size
+    #   <%= render BetterUi::Breadcrumb::BreadcrumbComponent.new(separator: :chevron, size: :lg) do |breadcrumb| %>
+    #     <% breadcrumb.with_item(label: "Home", href: "/") %>
+    #     <% breadcrumb.with_item(label: "Settings") %>
+    #   <% end %>
+    class BreadcrumbComponent < ApplicationComponent
+      # @!method with_item
+      #   Slot for rendering breadcrumb items.
+      #   @param label [String] the item label text
+      #   @param href [String, nil] the item link URL
+      #   @yieldparam [BetterUi::Breadcrumb::ItemComponent] item the item component instance
+      #   @yieldreturn [String] the HTML content for the item
+      renders_many :items, BetterUi::Breadcrumb::ItemComponent
+
+      # Allowed separator types
+      SEPARATORS = %i[slash chevron dot].freeze
+
+      # Allowed size options
+      SIZES = %i[sm md lg].freeze
+
+      # Initializes a new breadcrumb component.
+      #
+      # @param separator [Symbol] the separator type (:slash, :chevron, :dot), defaults to :slash
+      # @param size [Symbol] the text size (:sm, :md, :lg), defaults to :md
+      # @param container_classes [String, nil] additional CSS classes for the nav element
+      # @param options [Hash] additional HTML attributes passed to the nav element
+      #
+      # @raise [ArgumentError] if separator is not one of the allowed values
+      # @raise [ArgumentError] if size is not one of the allowed values
+      def initialize(
+        separator: :slash,
+        size: :md,
+        container_classes: nil,
+        **options
+      )
+        @separator = validate_separator(separator)
+        @size = validate_size(size)
+        @container_classes = container_classes
+        @options = options
+      end
+
+      private
+
+      # Returns the complete CSS classes for the ordered list element.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def component_classes
+        css_classes(
+          "flex",
+          "items-center",
+          "flex-wrap",
+          "gap-1",
+          size_classes
+        )
+      end
+
+      # Returns CSS classes for separator elements.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def separator_classes
+        css_classes(
+          "mx-2",
+          "text-grayscale-400"
+        )
+      end
+
+      # Returns the separator content (character or SVG) based on the separator type.
+      #
+      # @return [String] the separator HTML content
+      # @api private
+      def separator_content
+        case @separator
+        when :slash
+          "/"
+        when :chevron
+          chevron_svg
+        when :dot
+          "\u00B7"
+        end
+      end
+
+      # Returns the size-specific CSS class.
+      #
+      # @return [String] the Tailwind text size class
+      # @api private
+      def size_classes
+        case @size
+        when :sm then "text-sm"
+        when :md then "text-base"
+        when :lg then "text-lg"
+        end
+      end
+
+      # Returns an SVG chevron-right icon for the chevron separator.
+      #
+      # @return [String] the SVG HTML markup
+      # @api private
+      def chevron_svg
+        '<svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M7.293 14.707a1 1 0 010-1.414L10.586 10 7.293 6.707a1 1 0 011.414-1.414l4 4a1 1 0 010 1.414l-4 4a1 1 0 01-1.414 0z" clip-rule="evenodd" /></svg>'.html_safe
+      end
+
+      # Validates the separator parameter.
+      #
+      # @param separator [Symbol] the separator to validate
+      # @return [Symbol] the validated separator
+      # @raise [ArgumentError] if separator is invalid
+      # @api private
+      def validate_separator(separator)
+        unless SEPARATORS.include?(separator)
+          raise ArgumentError, "Invalid separator: #{separator}. Must be one of: #{SEPARATORS.join(', ')}"
+        end
+        separator
+      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.include?(size)
+          raise ArgumentError, "Invalid size: #{size}. Must be one of: #{SIZES.join(', ')}"
+        end
+        size
+      end
+    end
+  end
+end