fernandes-ui 0.1.0 → 0.1.2

data/app/behaviors/ui/select_behavior.rb

@@ -4,81 +4,131 @@
 #
 # Shared behavior for Select component across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent size styling and HTML attribute generation.
+#
+# @ui_component Select
+# @ui_description Displays a list of options for the user to pick from, triggered by a button.
+# @ui_category forms
+#
+# @ui_anatomy Select - Root container with state management (required)
+# @ui_anatomy Trigger - Button that opens the dropdown (required)
+# @ui_anatomy Content - Container for the dropdown options (required)
+# @ui_anatomy Item - Individual selectable option (required)
+# @ui_anatomy Group - Groups related items with a label
+# @ui_anatomy Label - Label for item groups
+# @ui_anatomy Separator - Visual separator between items
+#
+# @ui_feature Single selection from a list of options
+# @ui_feature Keyboard navigation with arrow keys
+# @ui_feature Type-ahead search functionality
+# @ui_feature Grouped options with labels
+# @ui_feature Disabled items support
+# @ui_feature Custom trigger with asChild pattern
+# @ui_feature Placeholder text when no selection
+# @ui_feature Form integration with hidden input
+#
+# @ui_data_attr data-state ["open", "closed"] Current open/closed state
+# @ui_data_attr data-placeholder ["true"] Present when showing placeholder
+#
+# @ui_css_var --trigger-width Width of the trigger element
+#
+# @ui_aria_pattern Listbox
+# @ui_aria_reference https://www.w3.org/WAI/ARIA/apg/patterns/listbox/
+# @ui_aria_attr role="combobox" on the trigger
+# @ui_aria_attr role="listbox" on the content container
+# @ui_aria_attr role="option" on each item
+# @ui_aria_attr aria-expanded on trigger
+# @ui_aria_attr aria-selected on the selected item
+# @ui_aria_attr aria-disabled on disabled items
+# @ui_aria_attr aria-labelledby for label association
+#
+# @ui_keyboard Space Opens dropdown when trigger is focused
+# @ui_keyboard Enter Opens dropdown / selects highlighted item
+# @ui_keyboard ArrowDown Opens dropdown / moves to next item
+# @ui_keyboard ArrowUp Moves to previous item
+# @ui_keyboard Home Moves to first item
+# @ui_keyboard End Moves to last item
+# @ui_keyboard Escape Closes dropdown
+# @ui_keyboard A-Z,a-z Type-ahead to find matching item
+#
+# @ui_related combobox
+# @ui_related dropdown_menu
+# @ui_related radio_group
+#
 module UI::SelectBehavior
   # Returns HTML attributes for the select element
-    def select_html_attributes
-      data_attrs = {
-        controller: "ui--select",
-        ui__select_open_value: "false"
-      }
-
-      # Add value if provided
-      if @value.present?
-        data_attrs[:ui__select_value_value] = @value.to_s
-      end
+  def select_html_attributes
+    data_attrs = {
+      controller: "ui--select",
+      ui__select_open_value: "false"
+    }
 
-      attrs = {
-        class: select_classes,
-        data: data_attrs
-      }
+    # Add value if provided
+    if @value.present?
+      data_attrs[:ui__select_value_value] = @value.to_s
+    end
 
-      # Add data-placeholder attribute if there's a placeholder and no selected value
-      if @placeholder.present? && @selected.nil?
-        attrs[:"data-placeholder"] = "true"
-      end
+    attrs = {
+      class: select_classes,
+      data: data_attrs
+    }
 
-      attrs.compact
+    # Add data-placeholder attribute if there's a placeholder and no selected value
+    if @placeholder.present? && @selected.nil?
+      attrs[:"data-placeholder"] = "true"
     end
 
-    # Returns combined CSS classes for the select
-    def select_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_base_classes,
-        select_size_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+    attrs.compact
+  end
 
-    private
+  # Returns combined CSS classes for the select
+  def select_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_base_classes,
+      select_size_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    # Base classes applied to all selects
-    # The select container is just a wrapper for Stimulus controller
-    # All visual styling is on the trigger button
-    # h-fit prevents wrapper from expanding to include absolutely positioned content
-    def select_base_classes
-      "relative h-fit"
-    end
+  private
 
-    # Size-specific classes based on @size
-    # No size classes needed on container, they go on trigger
-    def select_size_classes
-      ""
-    end
+  # Base classes applied to all selects
+  # The select container is just a wrapper for Stimulus controller
+  # All visual styling is on the trigger button
+  # h-fit prevents wrapper from expanding to include absolutely positioned content
+  def select_base_classes
+    "relative h-fit"
+  end
+
+  # Size-specific classes based on @size
+  # No size classes needed on container, they go on trigger
+  def select_size_classes
+    ""
+  end
 
-    # Renders options for the select element
-    # Handles both array format [label, value] and hash format { label: x, value: y }
-    def render_options
-      return "" if @options.nil?
+  # Renders options for the select element
+  # Handles both array format [label, value] and hash format { label: x, value: y }
+  def render_options
+    return "" if @options.nil?
 
-      @options.map do |option|
-        label, value = extract_option_values(option)
-        selected = @selected.to_s == value.to_s ? "selected" : nil
+    @options.map do |option|
+      label, value = extract_option_values(option)
+      selected = (@selected.to_s == value.to_s) ? "selected" : nil
 
-        { label: label, value: value, selected: selected }
-      end
+      {label: label, value: value, selected: selected}
     end
+  end
 
-    # Extracts label and value from different option formats
-    def extract_option_values(option)
-      if option.is_a?(Array)
-        [option[0], option[1]]
-      elsif option.is_a?(Hash)
-        label = option[:label] || option["label"]
-        value = option[:value] || option["value"]
-        [label, value]
-      else
-        [option, option]
-      end
+  # Extracts label and value from different option formats
+  def extract_option_values(option)
+    if option.is_a?(Array)
+      [option[0], option[1]]
+    elsif option.is_a?(Hash)
+      label = option[:label] || option["label"]
+      value = option[:value] || option["value"]
+      [label, value]
+    else
+      [option, option]
     end
+  end
 end

data/app/behaviors/ui/select_content_behavior.rb

@@ -5,38 +5,38 @@
 # Shared behavior for Select dropdown content across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent HTML attribute generation and styling.
 module UI::SelectContentBehavior
-    # Returns HTML attributes for the select content element
-    def select_content_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      {
-        class: select_content_classes,
-        data: {
-          ui__select_target: "content",
-          state: "closed",
-          slot: "select-content"
-        },
-        role: "listbox",
-        # CSS variables for positioning (set by JavaScript)
-        style: "box-sizing: border-box; display: flex; flex-direction: column; outline: none;"
-      }.merge(attributes_value || {})
-    end
+  # Returns HTML attributes for the select content element
+  def select_content_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    {
+      class: select_content_classes,
+      data: {
+        ui__select_target: "content",
+        state: "closed",
+        slot: "select-content"
+      },
+      role: "listbox",
+      # CSS variables for positioning (set by JavaScript)
+      style: "box-sizing: border-box; display: flex; flex-direction: column; outline: none;"
+    }.merge(attributes_value || {})
+  end
 
-    # Returns combined CSS classes
-    def select_content_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_content_base_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+  # Returns combined CSS classes
+  def select_content_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_content_base_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    private
+  private
 
-    # Base classes for select content dropdown
-    # FIXED: overflow-x-hidden overflow-y-auto instead of overflow-hidden
-    # FIXED: removed data-[state=closed]:hidden, use invisible pattern
-    # ADDED: max-h, origin, and translate classes for proper positioning
-    def select_content_base_classes
-      "absolute z-50 flex min-w-[8rem] flex-col overflow-x-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1 data-[state=closed]:invisible data-[state=open]:visible"
-    end
+  # Base classes for select content dropdown
+  # FIXED: overflow-x-hidden overflow-y-auto instead of overflow-hidden
+  # FIXED: removed data-[state=closed]:hidden, use invisible pattern
+  # ADDED: max-h, origin, and translate classes for proper positioning
+  def select_content_base_classes
+    "absolute z-50 flex min-w-[8rem] flex-col overflow-x-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1 data-[state=closed]:invisible data-[state=open]:visible"
   end
+end

data/app/behaviors/ui/select_group_behavior.rb

@@ -5,31 +5,31 @@
 # Shared behavior for Select options group across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent HTML attribute generation and styling.
 module UI::SelectGroupBehavior
-    # Returns HTML attributes for the select group element
-    def select_group_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      {
-        class: select_group_classes,
-        role: "group",
-        data: {
-          slot: "select-group" # ADDED: data-slot attribute
-        }
-      }.merge(attributes_value || {})
-    end
+  # Returns HTML attributes for the select group element
+  def select_group_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    {
+      class: select_group_classes,
+      role: "group",
+      data: {
+        slot: "select-group" # ADDED: data-slot attribute
+      }
+    }.merge(attributes_value || {})
+  end
 
-    # Returns combined CSS classes
-    def select_group_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_group_base_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+  # Returns combined CSS classes
+  def select_group_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_group_base_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    private
+  private
 
-    # Base classes for select group
-    def select_group_base_classes
-      "w-full"
-    end
+  # Base classes for select group
+  def select_group_base_classes
+    "w-full"
   end
+end

data/app/behaviors/ui/select_item_behavior.rb

@@ -5,44 +5,44 @@
 # Shared behavior for Individual select option across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent HTML attribute generation and styling.
 module UI::SelectItemBehavior
-    # Returns HTML attributes for the select item element
-    def select_item_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      attrs = {
-        class: select_item_classes,
-        role: "option",
-        "aria-selected": "false",
-        data: {
-          ui__select_target: "item",
-          action: "click->ui--select#selectItem mouseenter->ui--select#handleItemMouseEnter mouseleave->ui--select#handleItemMouseLeave",
-          value: @value,
-          slot: "select-item" # ADDED: data-slot attribute
-        }
+  # Returns HTML attributes for the select item element
+  def select_item_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    attrs = {
+      class: select_item_classes,
+      role: "option",
+      "aria-selected": "false",
+      data: {
+        ui__select_target: "item",
+        action: "click->ui--select#selectItem mouseenter->ui--select#handleItemMouseEnter mouseleave->ui--select#handleItemMouseLeave",
+        value: @value,
+        slot: "select-item" # ADDED: data-slot attribute
       }
+    }
 
-      # Add disabled state if specified
-      if @disabled
-        attrs[:data][:disabled] = "true"
-        attrs[:"aria-disabled"] = "true"
-        attrs[:data][:state] = "disabled"
-      end
-
-      attrs.merge(attributes_value || {})
+    # Add disabled state if specified
+    if @disabled
+      attrs[:data][:disabled] = "true"
+      attrs[:"aria-disabled"] = "true"
+      attrs[:data][:state] = "disabled"
     end
 
-    # Returns combined CSS classes
-    def select_item_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_item_base_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+    attrs.merge(attributes_value || {})
+  end
 
-    private
+  # Returns combined CSS classes
+  def select_item_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_item_base_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    # Base classes for select item
-    def select_item_base_classes
-      "relative flex w-full cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50"
-    end
+  private
+
+  # Base classes for select item
+  def select_item_base_classes
+    "relative flex w-full cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50"
   end
+end

data/app/behaviors/ui/select_label_behavior.rb

@@ -5,30 +5,30 @@
 # Shared behavior for Select group label across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent HTML attribute generation and styling.
 module UI::SelectLabelBehavior
-    # Returns HTML attributes for the select label element
-    def select_label_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      {
-        class: select_label_classes,
-        data: {
-          slot: "select-label" # ADDED: data-slot attribute
-        }
-      }.merge(attributes_value || {})
-    end
+  # Returns HTML attributes for the select label element
+  def select_label_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    {
+      class: select_label_classes,
+      data: {
+        slot: "select-label" # ADDED: data-slot attribute
+      }
+    }.merge(attributes_value || {})
+  end
 
-    # Returns combined CSS classes
-    def select_label_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_label_base_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+  # Returns combined CSS classes
+  def select_label_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_label_base_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    private
+  private
 
-    # Base classes for select label
-    def select_label_base_classes
-      "px-2 py-1.5 text-xs text-muted-foreground"
-    end
+  # Base classes for select label
+  def select_label_base_classes
+    "px-2 py-1.5 text-xs text-muted-foreground"
   end
+end

data/app/behaviors/ui/select_scroll_down_button_behavior.rb

@@ -5,47 +5,47 @@
 # Shared behavior for Select scroll down button across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent HTML attribute generation and styling.
 module UI::SelectScrollDownButtonBehavior
-    # Returns HTML attributes for the select scroll down button element
-    def select_scroll_down_button_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      {
-        class: select_scroll_down_button_classes,
-        "aria-hidden": "true",
-        # FIXED: Removed display: flex - visibility controlled by JavaScript/aria-hidden
-        # ADDED: flex-shrink: 0 as per shadcn implementation
-        style: "flex-shrink: 0;",
-        data: select_scroll_down_button_data_attributes
-      }.merge(attributes_value || {})
-    end
+  # Returns HTML attributes for the select scroll down button element
+  def select_scroll_down_button_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    {
+      class: select_scroll_down_button_classes,
+      "aria-hidden": "true",
+      # FIXED: Removed display: flex - visibility controlled by JavaScript/aria-hidden
+      # ADDED: flex-shrink: 0 as per shadcn implementation
+      style: "flex-shrink: 0;",
+      data: select_scroll_down_button_data_attributes
+    }.merge(attributes_value || {})
+  end
 
-    # Returns data attributes for Stimulus
-    def select_scroll_down_button_data_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      base_data = {
-        ui__select_target: "scrollDownButton",
-        action: "mouseenter->ui--select#scrollDown mouseleave->ui--select#stopScroll",
-        slot: "select-scroll-down-button" # ADDED: data-slot attribute
-      }
+  # Returns data attributes for Stimulus
+  def select_scroll_down_button_data_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    base_data = {
+      ui__select_target: "scrollDownButton",
+      action: "mouseenter->ui--select#scrollDown mouseleave->ui--select#stopScroll",
+      slot: "select-scroll-down-button" # ADDED: data-slot attribute
+    }
 
-      (attributes_value&.fetch(:data, {}) || {}).merge(base_data)
-    end
+    (attributes_value&.fetch(:data, {}) || {}).merge(base_data)
+  end
 
-    # Returns combined CSS classes
-    def select_scroll_down_button_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_scroll_down_button_base_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+  # Returns combined CSS classes
+  def select_scroll_down_button_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_scroll_down_button_base_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    private
+  private
 
-    # Base classes for select scroll down button
-    # FIXED: Removed absolute positioning (absolute bottom-0 left-0 right-0 z-10)
-    # FIXED: Removed hover:bg-accent bg-popover (not in shadcn)
-    # Now matches shadcn structure: simple flex layout
-    def select_scroll_down_button_base_classes
-      "flex cursor-default items-center justify-center py-1"
-    end
+  # Base classes for select scroll down button
+  # FIXED: Removed absolute positioning (absolute bottom-0 left-0 right-0 z-10)
+  # FIXED: Removed hover:bg-accent bg-popover (not in shadcn)
+  # Now matches shadcn structure: simple flex layout
+  def select_scroll_down_button_base_classes
+    "flex cursor-default items-center justify-center py-1"
   end
+end

data/app/behaviors/ui/select_scroll_up_button_behavior.rb

@@ -5,47 +5,47 @@
 # Shared behavior for Select scroll up button across ERB, ViewComponent, and Phlex implementations.
 # This module provides consistent HTML attribute generation and styling.
 module UI::SelectScrollUpButtonBehavior
-    # Returns HTML attributes for the select scroll up button element
-    def select_scroll_up_button_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      {
-        class: select_scroll_up_button_classes,
-        "aria-hidden": "true",
-        # FIXED: Removed display: none - visibility controlled by JavaScript/aria-hidden
-        # ADDED: flex-shrink: 0 as per shadcn implementation
-        style: "flex-shrink: 0;",
-        data: select_scroll_up_button_data_attributes
-      }.merge(attributes_value || {})
-    end
+  # Returns HTML attributes for the select scroll up button element
+  def select_scroll_up_button_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    {
+      class: select_scroll_up_button_classes,
+      "aria-hidden": "true",
+      # FIXED: Removed display: none - visibility controlled by JavaScript/aria-hidden
+      # ADDED: flex-shrink: 0 as per shadcn implementation
+      style: "flex-shrink: 0;",
+      data: select_scroll_up_button_data_attributes
+    }.merge(attributes_value || {})
+  end
 
-    # Returns data attributes for Stimulus
-    def select_scroll_up_button_data_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      base_data = {
-        ui__select_target: "scrollUpButton",
-        action: "mouseenter->ui--select#scrollUp mouseleave->ui--select#stopScroll",
-        slot: "select-scroll-up-button" # ADDED: data-slot attribute
-      }
+  # Returns data attributes for Stimulus
+  def select_scroll_up_button_data_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    base_data = {
+      ui__select_target: "scrollUpButton",
+      action: "mouseenter->ui--select#scrollUp mouseleave->ui--select#stopScroll",
+      slot: "select-scroll-up-button" # ADDED: data-slot attribute
+    }
 
-      (attributes_value&.fetch(:data, {}) || {}).merge(base_data)
-    end
+    (attributes_value&.fetch(:data, {}) || {}).merge(base_data)
+  end
 
-    # Returns combined CSS classes
-    def select_scroll_up_button_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        select_scroll_up_button_base_classes,
-        classes_value
-      ].compact.join(" "))
-    end
+  # Returns combined CSS classes
+  def select_scroll_up_button_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      select_scroll_up_button_base_classes,
+      classes_value
+    ].compact.join(" "))
+  end
 
-    private
+  private
 
-    # Base classes for select scroll up button
-    # FIXED: Removed absolute positioning (absolute top-0 left-0 right-0 z-10)
-    # FIXED: Removed hover:bg-accent bg-popover (not in shadcn)
-    # Now matches shadcn structure: simple flex layout
-    def select_scroll_up_button_base_classes
-      "flex cursor-default items-center justify-center py-1"
-    end
+  # Base classes for select scroll up button
+  # FIXED: Removed absolute positioning (absolute top-0 left-0 right-0 z-10)
+  # FIXED: Removed hover:bg-accent bg-popover (not in shadcn)
+  # Now matches shadcn structure: simple flex layout
+  def select_scroll_up_button_base_classes
+    "flex cursor-default items-center justify-center py-1"
   end
+end