better_ui 0.7.2 → 0.9.0

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

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

@@ -0,0 +1,11 @@
+<% if current? %>
+  <span class="<%= current_classes %>" aria-current="page">
+    <%= icon_before if icon_before? %>
+    <%= @label %>
+  </span>
+<% else %>
+  <a href="<%= @href %>" class="<%= link_classes %>">
+    <%= icon_before if icon_before? %>
+    <%= @label %>
+  </a>
+<% end %>

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Breadcrumb
+    # A breadcrumb item component that renders as a link or current page indicator.
+    #
+    # When an href is provided, the item renders as a link. When href is nil,
+    # it renders as a span with aria-current="page" to indicate the current page.
+    #
+    # @example Link item
+    #   <%= render BetterUi::Breadcrumb::ItemComponent.new(label: "Home", href: "/") %>
+    #
+    # @example Current page item (no href)
+    #   <%= render BetterUi::Breadcrumb::ItemComponent.new(label: "Settings") %>
+    #
+    # @example With icon
+    #   <%= render BetterUi::Breadcrumb::ItemComponent.new(label: "Home", href: "/") do |item| %>
+    #     <% item.with_icon_before do %>
+    #       <svg>...</svg>
+    #     <% end %>
+    #   <% end %>
+    class ItemComponent < ApplicationComponent
+      # @!method with_icon_before
+      #   Slot for rendering an icon before the label.
+      #   @yieldreturn [String] the SVG or icon HTML content
+      renders_one :icon_before
+
+      # Initializes a new breadcrumb item component.
+      #
+      # @param label [String] the text to display (required)
+      # @param href [String, nil] the link URL (nil renders as current page)
+      # @param options [Hash] additional HTML attributes passed to the element
+      def initialize(label:, href: nil, **options)
+        @label = label
+        @href = href
+        @options = options
+      end
+
+      # Whether this item represents the current page.
+      #
+      # @return [Boolean] true if no href is provided
+      def current?
+        @href.nil?
+      end
+
+      private
+
+      # Returns CSS classes for the current page indicator.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def current_classes
+        css_classes(
+          "text-grayscale-500",
+          "font-medium",
+          "inline-flex",
+          "items-center",
+          "gap-1"
+        )
+      end
+
+      # Returns CSS classes for the link element.
+      #
+      # @return [String] the merged CSS class string
+      # @api private
+      def link_classes
+        css_classes(
+          "text-grayscale-600",
+          "hover:text-grayscale-900",
+          "inline-flex",
+          "items-center",
+          "gap-1",
+          "transition-colors"
+        )
+      end
+    end
+  end
+end

data/app/components/better_ui/card_component.rb

@@ -43,7 +43,7 @@ module BetterUi
   #   # Soft: Light colored background
   #   <%= render BetterUi::CardComponent.new(style: :soft) { "Soft card" } %>
   #
-  #   # Bordered: Neutral gray border (variant-agnostic)
+  #   # Bordered: White background with variant-colored border (defaults to :light)
   #   <%= render BetterUi::CardComponent.new(style: :bordered) { "Bordered card" } %>
   class CardComponent < ApplicationComponent
     # Size configurations for padding, text, and border radius
@@ -78,7 +78,8 @@ module BetterUi
 
     # Initializes a new card component.
     #
-    # @param variant [Symbol] the color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark), defaults to :primary
+    # @param variant [Symbol, nil] the color variant (:primary, :secondary, :accent, :success, :danger, :warning, :info, :light, :dark).
+    #   Defaults to :primary for most styles, :light for :bordered style.
     # @param style [Symbol] the visual style (:solid, :outline, :ghost, :soft, :bordered), defaults to :solid
     # @param size [Symbol] the size variant (:xs, :sm, :md, :lg, :xl), defaults to :md
     # @param shadow [Boolean] whether to apply shadow, defaults to true
@@ -127,10 +128,10 @@ module BetterUi
     #     <% end %>
     #   <% end %>
     def initialize(
-      variant: :primary,
+      variant: nil,
       style: :solid,
       size: :md,
-      shadow: true,
+      shadow: :sm,
       header_padding: true,
       body_padding: true,
       footer_padding: true,
@@ -140,10 +141,11 @@ module BetterUi
       footer_classes: nil,
       **options
     )
-      @variant = validate_variant(variant)
       @style = validate_style(style)
+      resolved_variant = variant || default_variant_for_style
+      @variant = validate_variant(resolved_variant)
       @size = validate_size(size)
-      @shadow = shadow
+      @shadow = normalize_shadow(shadow)
       @header_padding = header_padding
       @body_padding = body_padding
       @footer_padding = footer_padding
@@ -299,13 +301,23 @@ module BetterUi
     end
 
     # Returns CSS classes for bordered style.
-    # Neutral white background with gray border, variant-agnostic.
-    # Perfect for visual content separation and isolation.
+    # White background with variant-colored border.
+    # Positioned between soft and outline in visual weight.
     #
     # @return [Array<String>] array of CSS classes
     # @api private
     def bordered_classes
-      [ "bg-white", "border", "border-gray-300", "text-gray-900" ]
+      case @variant
+      when :primary   then [ "bg-white", "border", "border-primary-300",   "text-grayscale-900" ]
+      when :secondary then [ "bg-white", "border", "border-secondary-300", "text-grayscale-900" ]
+      when :accent    then [ "bg-white", "border", "border-accent-300",    "text-grayscale-900" ]
+      when :success   then [ "bg-white", "border", "border-success-300",   "text-grayscale-900" ]
+      when :danger    then [ "bg-white", "border", "border-danger-300",    "text-grayscale-900" ]
+      when :warning   then [ "bg-white", "border", "border-warning-300",   "text-grayscale-900" ]
+      when :info      then [ "bg-white", "border", "border-info-300",      "text-grayscale-900" ]
+      when :light     then [ "bg-white", "border", "border-grayscale-300", "text-grayscale-900" ]
+      when :dark      then [ "bg-white", "border", "border-grayscale-700", "text-grayscale-900" ]
+      end
     end
 
     # Returns shadow CSS classes based on the shadow parameter.
@@ -313,7 +325,7 @@ module BetterUi
     # @return [String, nil] shadow class or nil
     # @api private
     def shadow_classes
-      @shadow ? "shadow-md" : nil
+      SHADOWS[@shadow]
     end
 
     # Returns the size configuration hash for the current size.
@@ -406,7 +418,17 @@ module BetterUi
       when :ghost
         "border-transparent"
       when :bordered
-        "border-gray-300"
+        case @variant
+        when :primary   then "border-primary-200"
+        when :secondary then "border-secondary-200"
+        when :accent    then "border-accent-200"
+        when :success   then "border-success-200"
+        when :danger    then "border-danger-200"
+        when :warning   then "border-warning-200"
+        when :info      then "border-info-200"
+        when :light     then "border-grayscale-200"
+        when :dark      then "border-grayscale-600"
+        end
       end
     end
 
@@ -418,6 +440,18 @@ module BetterUi
       @options
     end
 
+    # Returns the default variant for the current style.
+    # Bordered style defaults to :light (neutral gray), all others default to :primary.
+    #
+    # @return [Symbol] the default variant
+    # @api private
+    def default_variant_for_style
+      case @style
+      when :bordered then :light
+      else :primary
+      end
+    end
+
     # Validates the variant parameter.
     #
     # @param variant [Symbol] the variant to validate

data/app/components/better_ui/concerns/inline_label_styles.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Concerns
+    # Shared styling methods for inline label components (Badge, Tag).
+    #
+    # Provides variant-aware color classes for solid, outline, soft, and ghost styles.
+    # Components including this concern must define their own STYLES constant and
+    # may override hook methods for style divergence.
+    #
+    # Hook methods:
+    #   - outline_light_text_class: CSS class for light variant outline text
+    #     (default: "text-grayscale-400")
+    module InlineLabelStyles
+      extend ActiveSupport::Concern
+
+      private
+
+      def solid_classes
+        bg_classes = case @variant
+        when :primary
+          [ "bg-primary-600" ]
+        when :secondary
+          [ "bg-secondary-600" ]
+        when :accent
+          [ "bg-accent-600" ]
+        when :success
+          [ "bg-success-600" ]
+        when :danger
+          [ "bg-danger-600" ]
+        when :warning
+          [ "bg-warning-600" ]
+        when :info
+          [ "bg-info-600" ]
+        when :light
+          [ "bg-grayscale-100" ]
+        when :dark
+          [ "bg-grayscale-900" ]
+        end
+
+        bg_classes + [ text_color_for_solid ]
+      end
+
+      def outline_classes
+        color_classes = case @variant
+        when :primary
+          [ "border-primary-600", "text-primary-600" ]
+        when :secondary
+          [ "border-secondary-600", "text-secondary-600" ]
+        when :accent
+          [ "border-accent-600", "text-accent-600" ]
+        when :success
+          [ "border-success-600", "text-success-600" ]
+        when :danger
+          [ "border-danger-600", "text-danger-600" ]
+        when :warning
+          [ "border-warning-600", "text-warning-600" ]
+        when :info
+          [ "border-info-600", "text-info-600" ]
+        when :light
+          [ "border-grayscale-400", outline_light_text_class ]
+        when :dark
+          [ "border-grayscale-700", "text-grayscale-700" ]
+        end
+
+        [ "bg-transparent", "border" ] + color_classes
+      end
+
+      def soft_classes
+        case @variant
+        when :primary
+          [ "bg-primary-100", "text-primary-700" ]
+        when :secondary
+          [ "bg-secondary-100", "text-secondary-700" ]
+        when :accent
+          [ "bg-accent-100", "text-accent-700" ]
+        when :success
+          [ "bg-success-100", "text-success-700" ]
+        when :danger
+          [ "bg-danger-100", "text-danger-700" ]
+        when :warning
+          [ "bg-warning-100", "text-warning-700" ]
+        when :info
+          [ "bg-info-100", "text-info-700" ]
+        when :light
+          [ "bg-grayscale-100", "text-grayscale-700" ]
+        when :dark
+          [ "bg-grayscale-800", "text-grayscale-100" ]
+        end
+      end
+
+      def ghost_classes
+        color_classes = case @variant
+        when :primary
+          [ "text-primary-600" ]
+        when :secondary
+          [ "text-secondary-600" ]
+        when :accent
+          [ "text-accent-600" ]
+        when :success
+          [ "text-success-600" ]
+        when :danger
+          [ "text-danger-600" ]
+        when :warning
+          [ "text-warning-600" ]
+        when :info
+          [ "text-info-600" ]
+        when :light
+          [ "text-grayscale-700" ]
+        when :dark
+          [ "text-grayscale-700" ]
+        end
+
+        [ "bg-transparent" ] + color_classes
+      end
+
+      def text_color_for_solid
+        @variant == :light ? "text-grayscale-900" : "text-grayscale-50"
+      end
+
+      # Hook method for outline light variant text class.
+      # Override in including component to customize.
+      #
+      # @return [String] CSS class for outline light text color
+      def outline_light_text_class
+        "text-grayscale-400"
+      end
+
+      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
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+<div class="<%= component_classes %>" <%= tag.attributes(html_attributes) %>>
+  <%= content %>
+</div>

data/app/components/better_ui/container_component.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module BetterUi
+  # A responsive container component for constraining content width.
+  #
+  # This component provides a simple wrapper div with configurable max-width,
+  # horizontal padding, and centering. It is ideal for wrapping page content
+  # to maintain readable line lengths and consistent layout across breakpoints.
+  #
+  # @example Basic container (default: lg, padded, centered)
+  #   <%= render BetterUi::ContainerComponent.new do %>
+  #     Page content here
+  #   <% end %>
+  #
+  # @example Extra-large container
+  #   <%= render BetterUi::ContainerComponent.new(size: :xl) do %>
+  #     Wide content area
+  #   <% end %>
+  #
+  # @example Full-width container without padding
+  #   <%= render BetterUi::ContainerComponent.new(size: :full, padding: false) do %>
+  #     Edge-to-edge content
+  #   <% end %>
+  #
+  # @example Non-centered container
+  #   <%= render BetterUi::ContainerComponent.new(centered: false) do %>
+  #     Left-aligned content
+  #   <% end %>
+  class ContainerComponent < ApplicationComponent
+    # Available container sizes mapped to Tailwind max-width classes.
+    #
+    # @note Classes must be hardcoded strings for Tailwind JIT detection.
+    SIZES = {
+      sm: "max-w-screen-sm",
+      md: "max-w-screen-md",
+      lg: "max-w-screen-lg",
+      xl: "max-w-screen-xl",
+      full: "max-w-full"
+    }.freeze
+
+    # Initializes a new container component.
+    #
+    # @param size [Symbol] the max-width size (:sm, :md, :lg, :xl, :full), defaults to :lg
+    # @param padding [Boolean] whether to apply horizontal padding, defaults to true
+    # @param centered [Boolean] whether to center the container with mx-auto, defaults to true
+    # @param container_classes [String, nil] additional CSS classes for the container
+    # @param options [Hash] additional HTML attributes passed to the container div
+    #
+    # @raise [ArgumentError] if size is not one of the allowed values
+    #
+    # @example With all options
+    #   <%= render BetterUi::ContainerComponent.new(
+    #     size: :xl,
+    #     padding: true,
+    #     centered: true,
+    #     container_classes: "my-8",
+    #     id: "main-content",
+    #     data: { controller: "page" }
+    #   ) do %>
+    #     Content here
+    #   <% end %>
+    def initialize(
+      size: :lg,
+      padding: true,
+      centered: true,
+      container_classes: nil,
+      **options
+    )
+      @size = validate_size(size)
+      @padding = padding
+      @centered = centered
+      @container_classes = container_classes
+      @options = options
+    end
+
+    private
+
+    attr_reader :size, :padding, :centered, :container_classes, :options
+
+    # Returns the complete CSS classes for the container element.
+    #
+    # @return [String] the merged CSS class string
+    # @api private
+    def component_classes
+      css_classes([
+        "w-full",
+        size_classes,
+        padding_classes,
+        centered_classes,
+        @container_classes
+      ].flatten.compact)
+    end
+
+    # Returns the max-width class for the current size.
+    #
+    # @return [String] Tailwind max-width class
+    # @api private
+    def size_classes
+      SIZES[@size]
+    end
+
+    # Returns horizontal padding classes when padding is enabled.
+    #
+    # @return [String, nil] padding classes or nil
+    # @api private
+    def padding_classes
+      return nil unless @padding
+
+      "px-4 sm:px-6 lg:px-8"
+    end
+
+    # Returns centering class when centered is enabled.
+    #
+    # @return [String, nil] centering class or nil
+    # @api private
+    def centered_classes
+      return nil unless @centered
+
+      "mx-auto"
+    end
+
+    # Returns HTML attributes for the container element.
+    #
+    # @return [Hash] HTML attributes hash
+    # @api private
+    def html_attributes
+      @options
+    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
+  end
+end