Icon System in LooposUi

This documentation outlines how icons are handled throughout the LooposUi framework, focusing on the FaviconAware concern and its implementation in various components.

FaviconAware Concern

The FaviconAware concern provides a standardized way to handle icons across components. It allows components to accept either Font Awesome format icons or simplified symbol/string names that get converted to Font Awesome format.

Implementation

module LooposUi
  module FaviconAware
    def faviconize(icon)
      return unless icon
      icon.match?(/fa-/) ? icon : "fa-regular fa-#{icon.to_s.dasherize}"
    end
  end
end

The faviconize method:

• Returns nil if the input is nil
• Returns the icon string as-is if it already contains the fa- prefix (e.g., fa-solid fa-user)
• Converts symbols or simple strings to Font Awesome format using the regular style (e.g., :user → fa-regular fa-user)
• Handles multi-word icons by properly converting them to dashed format (e.g., :user_group → fa-regular fa-user-group)

Components Using FaviconAware

Several components in the system include the FaviconAware concern:

1. Icon Component: The base component for rendering icons
2. Button Component: Uses FaviconAware for leading and trailing icons
3. Sidebar::Item Component: Uses FaviconAware for navigation icons
4. AssociationOverlay::Header Component: Uses FaviconAware for header icons

Usage Examples

Basic Icon Usage

# Using Font Awesome format
render LooposUi::Icon.new(icon: "fa-solid fa-user")
# Using symbol format (preferred) - automatically converted to "fa-regular fa-user"
render LooposUi::Icon.new(icon: :user)
# String format also works
render LooposUi::Icon.new(icon: "user")

Button with Icons

# Leading icon with symbol (preferred)
render LooposUi::Button.new(
  text: "Add User", 
  leading_icon: :user_plus
)
# Leading icon in Font Awesome format
render LooposUi::Button.new(
  text: "Submit", 
  leading_icon: "fa-solid fa-paper-plane"
)
# Using shorthand icon parameter with symbol (sets leading_icon)
render LooposUi::Button.new(
  text: "Delete", 
  icon: :trash
)
# Trailing icon with symbol
render LooposUi::Button.new(
  text: "Next", 
  trailing_icon: :arrow_right
)

AssociationOverlay with Icon

render_inline(LooposUi::AssociationOverlay.new) do |overlay|
  # Using symbol for icon (preferred)
  overlay.with_header(title: "Select Users", icon: :users)
end

Best Practices

1. Prefer Symbols: Use symbols for icon names whenever possible (e.g., :user instead of "user").

2. Consistency: Choose either symbols, simplified strings, or the full Font Awesome format and use it consistently throughout your application.

3. Default Style: When using symbols or simplified strings, icons default to the fa-regular style. If you need solid, light, or duotone versions, use the full Font Awesome format.

4. Testing: When testing components with icons, test both formats:

   # Test with Font Awesome format
   test "renders with full Font Awesome icon format" do
    render_inline(LooposUi::Icon.new(icon: "fa-solid fa-user"))
    assert_selector("i.fa-solid.fa-user")
   end

# Test with symbol format (preferred) test "renders with symbol icon format" do renderinline(LooposUi::Icon.new(icon: :user)) assertselector("i.fa-regular.fa-user") end