better_ui 0.7.2 → 0.9.0

data/app/components/better_ui/fa_icon_component.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module BetterUi
+  class FaIconComponent < ApplicationComponent
+    STYLES = {
+      regular: "fa-regular",
+      solid: "fa-solid",
+      light: "fa-light",
+      thin: "fa-thin",
+      brands: "fa-brands"
+    }.freeze
+
+    SIZES = {
+      xs: "fa-xs",
+      sm: "fa-sm",
+      md: nil,
+      lg: "fa-lg",
+      xl: "fa-xl",
+      "2xl": "fa-2xl"
+    }.freeze
+
+    FLIPS = {
+      horizontal: "fa-flip-horizontal",
+      vertical: "fa-flip-vertical",
+      both: "fa-flip-both"
+    }.freeze
+
+    ROTATIONS = {
+      90 => "fa-rotate-90",
+      180 => "fa-rotate-180",
+      270 => "fa-rotate-270"
+    }.freeze
+
+    def initialize(
+      name:,
+      style: :regular,
+      variant: nil,
+      size: :md,
+      spin: false,
+      pulse: false,
+      flip: nil,
+      rotate: nil,
+      fixed_width: false,
+      container_classes: nil,
+      **options
+    )
+      @name = name
+      @style = validate_style(style)
+      @variant = validate_variant(variant)
+      @size = validate_size(size)
+      @spin = spin
+      @pulse = pulse
+      @flip = validate_flip(flip)
+      @rotate = validate_rotate(rotate)
+      @fixed_width = fixed_width
+      @container_classes = container_classes
+      @options = options
+    end
+
+    private
+
+    attr_reader :name, :style, :variant, :size, :spin, :pulse, :flip, :rotate,
+                :fixed_width, :container_classes, :options
+
+    def component_classes
+      css_classes([
+        style_class,
+        icon_class,
+        size_class,
+        variant_class,
+        animation_classes,
+        flip_class,
+        rotate_class,
+        fixed_width_class,
+        @container_classes
+      ].flatten.compact)
+    end
+
+    def style_class
+      STYLES[@style]
+    end
+
+    def icon_class
+      "fa-#{@name}"
+    end
+
+    def size_class
+      SIZES[@size]
+    end
+
+    def variant_class
+      case @variant
+      when nil       then nil
+      when :primary   then "text-primary-600"
+      when :secondary then "text-secondary-500"
+      when :accent    then "text-accent-500"
+      when :success   then "text-success-600"
+      when :danger    then "text-danger-600"
+      when :warning   then "text-warning-500"
+      when :info      then "text-info-500"
+      when :light     then "text-grayscale-400"
+      when :dark      then "text-grayscale-800"
+      end
+    end
+
+    def animation_classes
+      classes = []
+      classes << "fa-spin" if @spin
+      classes << "fa-pulse" if @pulse
+      classes
+    end
+
+    def flip_class
+      return nil unless @flip
+      FLIPS[@flip]
+    end
+
+    def rotate_class
+      return nil unless @rotate
+      ROTATIONS[@rotate]
+    end
+
+    def fixed_width_class
+      @fixed_width ? "fa-fw" : nil
+    end
+
+    def validate_style(style)
+      unless STYLES.key?(style)
+        raise ArgumentError, "Invalid style: #{style}. Must be one of: #{STYLES.keys.join(", ")}"
+      end
+      style
+    end
+
+    def validate_variant(variant)
+      return nil if variant.nil?
+      unless BetterUi::ApplicationComponent::VARIANTS.key?(variant)
+        raise ArgumentError, "Invalid variant: #{variant}. Must be one of: #{BetterUi::ApplicationComponent::VARIANTS.keys.join(", ")}"
+      end
+      variant
+    end
+
+    def validate_size(size)
+      unless SIZES.key?(size)
+        raise ArgumentError, "Invalid size: #{size}. Must be one of: #{SIZES.keys.join(", ")}"
+      end
+      size
+    end
+
+    def validate_flip(flip)
+      return nil if flip.nil?
+      unless FLIPS.key?(flip)
+        raise ArgumentError, "Invalid flip: #{flip}. Must be one of: #{FLIPS.keys.join(", ")}"
+      end
+      flip
+    end
+
+    def validate_rotate(rotate)
+      return nil if rotate.nil?
+      unless ROTATIONS.key?(rotate)
+        raise ArgumentError, "Invalid rotate: #{rotate}. Must be one of: #{ROTATIONS.keys.join(", ")}"
+      end
+      rotate
+    end
+  end
+end

data/app/components/better_ui/forms/base_component.rb

@@ -92,6 +92,7 @@ module BetterUi
         readonly: false,
         required: false,
         errors: nil,
+        shadow: :sm,
         container_classes: nil,
         label_classes: nil,
         input_classes: nil,
@@ -109,6 +110,7 @@ module BetterUi
         @readonly = readonly
         @required = required
         @errors = Array(errors).compact.reject(&:blank?)
+        @shadow = normalize_shadow(shadow)
         @container_classes = container_classes
         @label_classes = label_classes
         @input_classes = input_classes
@@ -238,7 +240,7 @@ module BetterUi
           "w-full",
           "rounded-md",
           "border",
-          "shadow-sm",
+          SHADOWS[@shadow],
           "transition-colors",
           "duration-200"
         ]

data/app/components/better_ui/forms/select_component/select_component.html.erb

@@ -0,0 +1,86 @@
+<div class="<%= wrapper_classes %>">
+  <% if @label.present? %>
+    <label for="<%= input_id %>" class="<%= label_element_classes %>">
+      <%= @label %>
+      <% if @required %>
+        <span class="text-danger-600">*</span>
+      <% end %>
+    </label>
+  <% end %>
+
+  <div class="relative" data-controller="better-ui--forms--select"
+       data-better-ui--forms--select-clearable-value="<%= @clearable %>"
+       data-better-ui--forms--select-placeholder-value="<%= placeholder_text %>"
+       data-better-ui--forms--select-disabled-value="<%= @disabled %>"
+       data-better-ui--forms--select-readonly-value="<%= @readonly %>">
+
+    <input <%= tag.attributes(hidden_input_attributes) %> />
+
+    <button <%= tag.attributes(trigger_attributes) %>>
+      <% if prefix_icon.present? %>
+        <span class="flex items-center mr-2">
+          <%= prefix_icon %>
+        </span>
+      <% end %>
+
+      <span class="<%= trigger_text_classes %>"
+            data-better-ui--forms--select-target="display">
+        <%= has_selection? ? selected_label : placeholder_text %>
+      </span>
+
+      <% if @clearable %>
+        <span class="<%= has_selection? ? 'flex items-center ml-1' : 'hidden flex items-center ml-1' %>"
+              data-better-ui--forms--select-target="clearButton"
+              data-action="click->better-ui--forms--select#clear">
+          <svg class="<%= caret_icon_size %> text-gray-400 hover:text-gray-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"/>
+          </svg>
+        </span>
+      <% end %>
+
+      <span class="flex items-center ml-2"
+            data-better-ui--forms--select-target="caret">
+        <svg class="<%= caret_icon_size %> text-gray-400 transition-transform duration-200" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
+        </svg>
+      </span>
+    </button>
+
+    <ul id="<%= listbox_id %>"
+        role="listbox"
+        class="<%= dropdown_element_classes %>"
+        data-better-ui--forms--select-target="listbox"
+        data-action="keydown->better-ui--forms--select#handleListboxKeydown">
+      <% @collection.each_with_index do |item, index| %>
+        <% value = item_value(item) %>
+        <% label = item_label(item) %>
+        <% selected = has_selection? && @value.to_s == value %>
+        <li role="option"
+            id="<%= input_id %>_option_<%= index %>"
+            class="<%= option_element_classes(selected) %>"
+            data-value="<%= value %>"
+            data-label="<%= label %>"
+            aria-selected="<%= selected %>"
+            data-better-ui--forms--select-target="option"
+            data-action="click->better-ui--forms--select#selectOption"
+            tabindex="-1">
+          <%= label %>
+        </li>
+      <% end %>
+    </ul>
+  </div>
+
+  <% if @hint.present? %>
+    <div class="<%= hint_element_classes %>">
+      <%= @hint %>
+    </div>
+  <% end %>
+
+  <% if has_errors? %>
+    <div class="<%= errors_element_classes %>">
+      <% @errors.each do |error| %>
+        <div><%= error %></div>
+      <% end %>
+    </div>
+  <% end %>
+</div>

data/app/components/better_ui/forms/select_component.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module BetterUi
+  module Forms
+    # A custom dropdown select component for choosing a single option from a collection.
+    #
+    # This component extends {BaseComponent} to provide a custom select dropdown with
+    # keyboard navigation, type-ahead search, and full ARIA support. It uses a hidden
+    # input for form submission and a Stimulus controller for interactivity.
+    #
+    # @example Basic select
+    #   <%= render BetterUi::Forms::SelectComponent.new(
+    #     name: "user[country]",
+    #     collection: [["Italy", "it"], ["France", "fr"], ["Germany", "de"]],
+    #     label: "Country"
+    #   ) %>
+    #
+    # @example With prefix icon
+    #   <%= render BetterUi::Forms::SelectComponent.new(
+    #     name: "country",
+    #     collection: [["Italy", "it"], ["France", "fr"]],
+    #     label: "Country",
+    #     clearable: true
+    #   ) do |component| %>
+    #     <% component.with_prefix_icon do %>
+    #       <svg class="h-5 w-5 text-gray-400">...</svg>
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example Simple array collection
+    #   <%= render BetterUi::Forms::SelectComponent.new(
+    #     name: "color",
+    #     collection: ["Red", "Blue", "Green"],
+    #     placeholder: "Pick a color"
+    #   ) %>
+    #
+    # @see BaseComponent
+    # @see BetterUi::UiFormBuilder#bui_select
+    class SelectComponent < BaseComponent
+      renders_one :prefix_icon
+
+      # @param name [String] the name attribute for the hidden input field
+      # @param collection [Array] array of values or [label, value] pairs
+      # @param clearable [Boolean] whether to show a clear button
+      # @param dropdown_classes [String, nil] custom CSS classes for the dropdown
+      # @param (see BaseComponent#initialize)
+      def initialize(
+        name:,
+        collection: [],
+        clearable: false,
+        dropdown_classes: nil,
+        value: nil,
+        label: nil,
+        hint: nil,
+        placeholder: nil,
+        size: :md,
+        disabled: false,
+        readonly: false,
+        required: false,
+        errors: nil,
+        shadow: :sm,
+        container_classes: nil,
+        label_classes: nil,
+        input_classes: nil,
+        hint_classes: nil,
+        error_classes: nil,
+        **options
+      )
+        @collection = collection
+        @clearable = clearable
+        @dropdown_classes = dropdown_classes
+        super(
+          name: name,
+          value: value,
+          label: label,
+          hint: hint,
+          placeholder: placeholder,
+          size: size,
+          disabled: disabled,
+          readonly: readonly,
+          required: required,
+          errors: errors,
+          shadow: shadow,
+          container_classes: container_classes,
+          label_classes: label_classes,
+          input_classes: input_classes,
+          hint_classes: hint_classes,
+          error_classes: error_classes,
+          **options
+        )
+      end
+
+      private
+
+      # Extracts the label from a collection item.
+      #
+      # @param item [String, Array] the collection item
+      # @return [String] the label text
+      def item_label(item)
+        item.is_a?(Array) ? item.first.to_s : item.to_s
+      end
+
+      # Extracts the value from a collection item.
+      #
+      # @param item [String, Array] the collection item
+      # @return [String] the value
+      def item_value(item)
+        item.is_a?(Array) ? item.last.to_s : item.to_s
+      end
+
+      # Finds the label for the currently selected value.
+      #
+      # @return [String, nil] the label of the selected option, or nil
+      def selected_label
+        return nil unless has_selection?
+
+        selected_item = @collection.find { |item| item_value(item) == @value.to_s }
+        selected_item ? item_label(selected_item) : @value.to_s
+      end
+
+      # Checks if there is a current selection.
+      #
+      # @return [Boolean] true if a value is present
+      def has_selection?
+        @value.present?
+      end
+
+      # Generates a unique ID based on the input name.
+      #
+      # @return [String] the generated ID
+      def input_id
+        @name.to_s.gsub(/\[|\]/, "_").gsub(/_+/, "_").chomp("_")
+      end
+
+      # Generates a unique ID for the listbox element.
+      #
+      # @return [String] the listbox element ID
+      def listbox_id
+        "#{input_id}_listbox"
+      end
+
+      # Returns CSS classes for the trigger button element.
+      #
+      # @return [String] merged CSS classes
+      def trigger_element_classes
+        css_classes([
+          trigger_base_classes,
+          size_input_classes,
+          trigger_state_classes,
+          @input_classes
+        ].flatten.compact)
+      end
+
+      # Returns the base CSS classes for the trigger element.
+      # Uses flex instead of block (unlike text inputs) for icon layout.
+      #
+      # @return [Array<String>] base trigger CSS classes
+      def trigger_base_classes
+        [
+          "block",
+          "w-full",
+          "rounded-md",
+          "border",
+          SHADOWS[@shadow],
+          "transition-colors",
+          "duration-200",
+          "flex",
+          "items-center",
+          "text-left"
+        ]
+      end
+
+      # Returns state-specific trigger classes with correct cursor.
+      # Cursor-pointer is only applied in normal and error states.
+      #
+      # @return [Array<String>] state CSS classes
+      def trigger_state_classes
+        if @disabled
+          disabled_classes
+        elsif @readonly
+          readonly_classes
+        elsif has_errors?
+          error_state_classes + [ "cursor-pointer" ]
+        else
+          normal_state_classes + [ "cursor-pointer" ]
+        end
+      end
+
+      # Returns CSS classes for the trigger display text.
+      #
+      # @return [String] merged CSS classes
+      def trigger_text_classes
+        if has_selection?
+          css_classes([ "flex-1", "truncate", "text-gray-900" ])
+        else
+          css_classes([ "flex-1", "truncate", "text-gray-400" ])
+        end
+      end
+
+      # Returns CSS classes for the dropdown listbox.
+      #
+      # @return [String] merged CSS classes
+      def dropdown_element_classes
+        css_classes([
+          "absolute",
+          "z-50",
+          "w-full",
+          "mt-1",
+          "bg-white",
+          "border",
+          "border-gray-300",
+          "rounded-md",
+          "shadow-lg",
+          "max-h-60",
+          "overflow-auto",
+          "py-1",
+          "hidden",
+          @dropdown_classes
+        ].flatten.compact)
+      end
+
+      # Returns CSS classes for an option element.
+      #
+      # @param selected [Boolean] whether this option is currently selected
+      # @return [String] merged CSS classes
+      def option_element_classes(selected)
+        css_classes([
+          "px-3",
+          "py-2",
+          "cursor-pointer",
+          "truncate",
+          option_size_classes,
+          selected ? "bg-primary-50 text-primary-700 font-medium" : "text-gray-900",
+          "hover:bg-gray-100"
+        ].flatten.compact)
+      end
+
+      # Returns size-specific classes for option text.
+      #
+      # @return [String] the text size class
+      def option_size_classes
+        case @size
+        when :xs then "text-xs"
+        when :sm then "text-sm"
+        when :md then "text-base"
+        when :lg then "text-lg"
+        when :xl then "text-xl"
+        end
+      end
+
+      # Returns SVG size classes for the caret icon.
+      #
+      # @return [String] the size classes
+      def caret_icon_size
+        case @size
+        when :xs, :sm then "w-4 h-4"
+        when :md, :lg then "w-5 h-5"
+        when :xl then "w-6 h-6"
+        end
+      end
+
+      # Returns the placeholder text with a default fallback.
+      #
+      # @return [String] the placeholder text
+      def placeholder_text
+        @placeholder || "Select..."
+      end
+
+      # Overrides disabled_classes to use cursor-not-allowed without focus styles.
+      #
+      # @return [Array<String>] CSS classes for disabled state
+      def disabled_classes
+        [
+          "border-gray-300",
+          "bg-gray-100",
+          "text-gray-500",
+          "cursor-not-allowed",
+          "opacity-60"
+        ]
+      end
+
+      # Overrides readonly_classes for the trigger.
+      #
+      # @return [Array<String>] CSS classes for readonly state
+      def readonly_classes
+        [
+          "border-gray-300",
+          "bg-gray-50",
+          "text-gray-700",
+          "cursor-default"
+        ]
+      end
+
+      # Returns the Stimulus controller wrapper data attributes.
+      #
+      # @return [Hash] data attributes hash
+      def controller_wrapper_attributes
+        attrs = {
+          controller: "better-ui--forms--select",
+          "better-ui--forms--select-clearable-value": @clearable,
+          "better-ui--forms--select-placeholder-value": placeholder_text,
+          "better-ui--forms--select-disabled-value": @disabled,
+          "better-ui--forms--select-readonly-value": @readonly
+        }
+        attrs
+      end
+
+      # Returns the complete set of HTML attributes for the trigger button.
+      #
+      # @return [Hash] trigger button attributes
+      def trigger_attributes
+        attrs = {
+          type: "button",
+          role: "combobox",
+          "aria-expanded": "false",
+          "aria-haspopup": "listbox",
+          "aria-controls": listbox_id,
+          class: trigger_element_classes,
+          disabled: @disabled || nil,
+          "aria-readonly": @readonly ? "true" : nil,
+          "data-better-ui--forms--select-target": "trigger",
+          "data-action": "click->better-ui--forms--select#toggle keydown->better-ui--forms--select#handleTriggerKeydown"
+        }.compact
+        attrs
+      end
+
+      # Returns the HTML attributes for the hidden input.
+      #
+      # @return [Hash] hidden input attributes
+      def hidden_input_attributes
+        attrs = {
+          type: "hidden",
+          name: @name,
+          value: @value,
+          "data-better-ui--forms--select-target": "hiddenInput"
+        }
+        attrs[:id] = @options[:id] if @options[:id]
+        attrs[:required] = true if @required
+        @options.each do |key, val|
+          next if key == :id
+          attrs[key] = val
+        end
+        attrs.compact
+      end
+    end
+  end
+end

data/app/components/better_ui/forms/text_input_component.rb

@@ -71,6 +71,13 @@ module BetterUi
     # @see BaseComponent
     # @see BetterUi::UiFormBuilder#ui_text_input
     class TextInputComponent < BaseComponent
+      # Available input types for text-based inputs.
+      # Password has its own component ({PasswordInputComponent}) with a Stimulus controller.
+      # Number has its own component ({NumberInputComponent}).
+      #
+      # @return [Array<Symbol>] the list of valid type options
+      TYPES = %i[text email tel date time].freeze
+
       # @!method with_prefix_icon
       #   Slot for rendering an icon or content before (left of) the input text.
       #   The icon is positioned absolutely and input padding is adjusted automatically.
@@ -95,6 +102,7 @@ module BetterUi
       # @see BaseComponent#initialize
       def initialize(
         name:,
+        type: :text,
         value: nil,
         label: nil,
         hint: nil,
@@ -111,6 +119,7 @@ module BetterUi
         error_classes: nil,
         **options
       )
+        @type = validate_type(type)
         super(
           name: name,
           value: value,
@@ -133,12 +142,25 @@ module BetterUi
 
       private
 
+      # Validates that the provided type is one of the allowed TYPES.
+      #
+      # @param type [Symbol] the type to validate
+      # @return [Symbol] the validated type
+      # @raise [ArgumentError] if type is not in TYPES
+      # @api private
+      def validate_type(type)
+        unless TYPES.include?(type)
+          raise ArgumentError, "Invalid type: #{type}. Must be one of #{TYPES.join(', ')}"
+        end
+        type
+      end
+
       # Returns the HTML input type attribute.
       #
-      # @return [String] the input type ("text")
+      # @return [String] the input type
       # @api private
       def input_type
-        "text"
+        @type.to_s
       end
 
       # Checks if a prefix icon has been provided via the slot.

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

@@ -0,0 +1,11 @@
+<div class="<%= wrapper_classes %>">
+  <div class="flex items-center justify-between">
+    <<%= heading_tag %> class="<%= component_classes %>" <%= tag.attributes(html_attributes) %>><%= content %></<%= heading_tag %>>
+    <% if actions? %>
+      <div class="flex items-center gap-2"><%= actions %></div>
+    <% end %>
+  </div>
+  <% if show_subtitle? %>
+    <p class="<%= subtitle_classes %>"><%= subtitle? ? subtitle : @subtitle_text %></p>
+  <% end %>
+</div>