fernandes-ui 0.1.0 → 0.1.2

data/app/behaviors/ui/radio_button_behavior.rb

@@ -1,46 +1,61 @@
 # frozen_string_literal: true
 
-module UI
-  # RadioButton Behavior - Shared logic for radio button component across ERB, ViewComponent, and Phlex
-  module RadioButtonBehavior
-    def radio_button_html_attributes
-      attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
-      {
-        type: "radio",
-        class: radio_button_classes,
-        name: @name,
-        id: radio_button_id,
-        value: @value,
-        checked: (@checked ? true : nil),
-        disabled: (@disabled ? true : nil),
-        required: (@required ? true : nil),
-        data: radio_button_data_attributes
-      }.merge(attributes_value).compact
-    end
+# UI::RadioButtonBehavior
+#
+# @ui_component Radio Button
+# @ui_category forms
+#
+# @ui_anatomy Radio Button - Root container for radio button (required)
+#
+# @ui_feature Custom styling with Tailwind classes
+# @ui_feature Disabled state support
+# @ui_feature ARIA attributes for accessibility
+#
+# @ui_aria_pattern Radio Group
+# @ui_aria_reference https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+#
+# @ui_related toggle_group
+# @ui_related checkbox
+# @ui_related select
+#
+module UI::RadioButtonBehavior
+  def radio_button_html_attributes
+    attributes_value = respond_to?(:attributes, true) ? attributes : @attributes
+    {
+      type: "radio",
+      class: radio_button_classes,
+      name: @name,
+      id: radio_button_id,
+      value: @value,
+      checked: (@checked ? true : nil),
+      disabled: (@disabled ? true : nil),
+      required: (@required ? true : nil),
+      data: radio_button_data_attributes
+    }.merge(attributes_value).compact
+  end
 
-    def radio_button_classes
-      classes_value = respond_to?(:classes, true) ? classes : @classes
-      TailwindMerge::Merger.new.merge([
-        radio_button_base_classes,
-        classes_value
+  def radio_button_classes
+    classes_value = respond_to?(:classes, true) ? classes : @classes
+    TailwindMerge::Merger.new.merge([
+      radio_button_base_classes,
+      classes_value
 
-      ].compact.join(" "))
-    end
+    ].compact.join(" "))
+  end
 
-    def radio_button_data_attributes
-      {
-        slot: "radio-group-item"
-      }
-    end
+  def radio_button_data_attributes
+    {
+      slot: "radio-group-item"
+    }
+  end
 
-    def radio_button_id
-      @id || "radio-#{SecureRandom.hex(4)}"
-    end
+  def radio_button_id
+    @id || "radio-#{SecureRandom.hex(4)}"
+  end
 
-    private
+  private
 
-    def radio_button_base_classes
-      "peer appearance-none border-input text-primary focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 aspect-square size-4 shrink-0 rounded-full border shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 cursor-pointer"
-    end
+  def radio_button_base_classes
+    "peer appearance-none border-input text-primary focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 aspect-square size-4 shrink-0 rounded-full border shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 cursor-pointer"
   end
 end

data/app/behaviors/ui/resizable_handle_behavior.rb

@@ -1,81 +1,81 @@
 # frozen_string_literal: true
 
-    # Shared behavior for ResizableHandle component
-    # Handles data attributes for resize handles
-    module UI::ResizableHandleBehavior
-      # Base CSS classes for the handle
-      # The handle uses a thin visual line (w-px) but has padding for easier interaction
-      def handle_base_classes
-        base = [
-          "relative z-10 flex shrink-0 items-center justify-center",
-          "w-2 -mx-[3.5px]", # 8px wide handle with negative margin to overlap panels
-          "bg-transparent cursor-col-resize",
-          "touch-none select-none", # Prevent scroll interference on touch devices
-          # The visible line is drawn with ::after
-          "after:absolute after:inset-y-0 after:left-1/2 after:w-px after:-translate-x-1/2 after:bg-border",
-          "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1",
-          # Vertical direction
-          "data-[panel-group-direction=vertical]:h-2 data-[panel-group-direction=vertical]:w-full",
-          "data-[panel-group-direction=vertical]:-my-[3.5px] data-[panel-group-direction=vertical]:mx-0",
-          "data-[panel-group-direction=vertical]:cursor-row-resize",
-          "data-[panel-group-direction=vertical]:after:inset-x-0 data-[panel-group-direction=vertical]:after:inset-y-auto",
-          "data-[panel-group-direction=vertical]:after:top-1/2 data-[panel-group-direction=vertical]:after:left-0",
-          "data-[panel-group-direction=vertical]:after:h-px data-[panel-group-direction=vertical]:after:w-full",
-          "data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0",
-          "[&[data-panel-group-direction=vertical]>div]:rotate-90"
-        ]
-        base << @classes if @classes.present?
-        base.join(" ")
-      end
+# Shared behavior for ResizableHandle component
+# Handles data attributes for resize handles
+module UI::ResizableHandleBehavior
+  # Base CSS classes for the handle
+  # The handle uses a thin visual line (w-px) but has padding for easier interaction
+  def handle_base_classes
+    base = [
+      "relative z-10 flex shrink-0 items-center justify-center",
+      "w-2 -mx-[3.5px]", # 8px wide handle with negative margin to overlap panels
+      "bg-transparent cursor-col-resize",
+      "touch-none select-none", # Prevent scroll interference on touch devices
+      # The visible line is drawn with ::after
+      "after:absolute after:inset-y-0 after:left-1/2 after:w-px after:-translate-x-1/2 after:bg-border",
+      "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1",
+      # Vertical direction
+      "data-[panel-group-direction=vertical]:h-2 data-[panel-group-direction=vertical]:w-full",
+      "data-[panel-group-direction=vertical]:-my-[3.5px] data-[panel-group-direction=vertical]:mx-0",
+      "data-[panel-group-direction=vertical]:cursor-row-resize",
+      "data-[panel-group-direction=vertical]:after:inset-x-0 data-[panel-group-direction=vertical]:after:inset-y-auto",
+      "data-[panel-group-direction=vertical]:after:top-1/2 data-[panel-group-direction=vertical]:after:left-0",
+      "data-[panel-group-direction=vertical]:after:h-px data-[panel-group-direction=vertical]:after:w-full",
+      "data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0",
+      "[&[data-panel-group-direction=vertical]>div]:rotate-90"
+    ]
+    base << @classes if @classes.present?
+    base.join(" ")
+  end
 
-      # Generate data attributes for the handle
-      def handle_data_attributes
-        {
-          ui__resizable_target: "handle",
-          resize_handle: "",
-          resize_handle_state: "inactive"
-        }
-      end
+  # Generate data attributes for the handle
+  def handle_data_attributes
+    {
+      ui__resizable_target: "handle",
+      resize_handle: "",
+      resize_handle_state: "inactive"
+    }
+  end
 
-      # Merge user-provided data attributes with handle data
-      def merged_handle_data_attributes
-        user_data = @attributes&.fetch(:data, {}) || {}
-        user_data.merge(handle_data_attributes)
-      end
+  # Merge user-provided data attributes with handle data
+  def merged_handle_data_attributes
+    user_data = @attributes&.fetch(:data, {}) || {}
+    user_data.merge(handle_data_attributes)
+  end
 
-      # Stimulus actions for the handle
-      def handle_actions
-        [
-          "pointerdown->ui--resizable#startDrag",
-          "pointerenter->ui--resizable#handleEnter",
-          "pointerleave->ui--resizable#handleLeave",
-          "focus->ui--resizable#handleFocus",
-          "blur->ui--resizable#handleBlur"
-        ].join(" ")
-      end
+  # Stimulus actions for the handle
+  def handle_actions
+    [
+      "pointerdown->ui--resizable#startDrag",
+      "pointerenter->ui--resizable#handleEnter",
+      "pointerleave->ui--resizable#handleLeave",
+      "focus->ui--resizable#handleFocus",
+      "blur->ui--resizable#handleBlur"
+    ].join(" ")
+  end
 
-      # Build complete HTML attributes hash for handle
-      def handle_html_attributes
-        base_attrs = @attributes&.except(:data) || {}
-        data_attrs = merged_handle_data_attributes
-        data_attrs[:action] = handle_actions
+  # Build complete HTML attributes hash for handle
+  def handle_html_attributes
+    base_attrs = @attributes&.except(:data) || {}
+    data_attrs = merged_handle_data_attributes
+    data_attrs[:action] = handle_actions
 
-        base_attrs.merge(
-          class: handle_base_classes,
-          "data-slot": "resizable-handle",
-          tabindex: "0",
-          role: "separator",
-          "aria-valuenow": "50",
-          "aria-valuemin": "0",
-          "aria-valuemax": "100",
-          data: data_attrs
-        )
-      end
+    base_attrs.merge(
+      class: handle_base_classes,
+      "data-slot": "resizable-handle",
+      tabindex: "0",
+      role: "separator",
+      "aria-valuenow": "50",
+      "aria-valuemin": "0",
+      "aria-valuemax": "100",
+      data: data_attrs
+    )
+  end
 
-      # CSS classes for the grip icon container (when with_handle is true)
-      def grip_container_classes
-        [
-          "z-10 flex h-4 w-3 items-center justify-center rounded-sm border bg-border"
-        ].join(" ")
-      end
-    end
+  # CSS classes for the grip icon container (when with_handle is true)
+  def grip_container_classes
+    [
+      "z-10 flex h-4 w-3 items-center justify-center rounded-sm border bg-border"
+    ].join(" ")
+  end
+end

data/app/behaviors/ui/resizable_panel_behavior.rb

@@ -1,53 +1,60 @@
 # frozen_string_literal: true
 
-    # Shared behavior for ResizablePanel component
-    # Handles data attributes for individual panels
-    module UI::ResizablePanelBehavior
-      # Base CSS classes for the panel
-      # Uses min-w-0/min-h-0 and overflow-hidden to allow panels to shrink to 0
-      def panel_base_classes
-        classes = ["relative overflow-hidden min-w-0 min-h-0"]
-        classes << @classes if @classes.present?
-        classes.join(" ")
-      end
+# UI::ResizablePanelBehavior
+#
+# @ui_component Resizable Panel
+# @ui_description ResizablePanel component (Phlex) Individual resizable panel within a panel group
+# @ui_category other
+#
+# @ui_anatomy Resizable Panel - Resizable Panel component part (required)
+# @ui_anatomy Group - Container for grouping related items
+#
+module UI::ResizablePanelBehavior
+  # Base CSS classes for the panel
+  # Uses min-w-0/min-h-0 and overflow-hidden to allow panels to shrink to 0
+  def panel_base_classes
+    classes = ["relative overflow-hidden min-w-0 min-h-0"]
+    classes << @classes if @classes.present?
+    classes.join(" ")
+  end
 
-      # Generate data attributes for the panel
-      def panel_data_attributes
-        attrs = {
-          ui__resizable_target: "panel"
-        }
-        attrs[:default_size] = @default_size if @default_size
-        attrs[:min_size] = @min_size if @min_size
-        attrs[:max_size] = @max_size if @max_size
-        attrs
-      end
+  # Generate data attributes for the panel
+  def panel_data_attributes
+    attrs = {
+      ui__resizable_target: "panel"
+    }
+    attrs[:default_size] = @default_size if @default_size
+    attrs[:min_size] = @min_size if @min_size
+    attrs[:max_size] = @max_size if @max_size
+    attrs
+  end
 
-      # Merge user-provided data attributes with panel data
-      def merged_panel_data_attributes
-        user_data = @attributes&.fetch(:data, {}) || {}
-        user_data.merge(panel_data_attributes)
-      end
+  # Merge user-provided data attributes with panel data
+  def merged_panel_data_attributes
+    user_data = @attributes&.fetch(:data, {}) || {}
+    user_data.merge(panel_data_attributes)
+  end
 
-      # Build complete HTML attributes hash for panel
-      def panel_html_attributes
-        base_attrs = @attributes&.except(:data) || {}
+  # Build complete HTML attributes hash for panel
+  def panel_html_attributes
+    base_attrs = @attributes&.except(:data) || {}
 
-        # Use flex-grow for proportional sizing instead of flex-basis percentage
-        # This works correctly with min-height containers in vertical layouts
-        style_parts = []
-        if @default_size
-          style_parts << "flex-grow: #{@default_size}"
-          style_parts << "flex-shrink: #{@default_size}"
-          style_parts << "flex-basis: 0"
-        end
+    # Use flex-grow for proportional sizing instead of flex-basis percentage
+    # This works correctly with min-height containers in vertical layouts
+    style_parts = []
+    if @default_size
+      style_parts << "flex-grow: #{@default_size}"
+      style_parts << "flex-shrink: #{@default_size}"
+      style_parts << "flex-basis: 0"
+    end
 
-        attrs = base_attrs.merge(
-          class: panel_base_classes,
-          "data-slot": "resizable-panel",
-          data: merged_panel_data_attributes
-        )
+    attrs = base_attrs.merge(
+      class: panel_base_classes,
+      "data-slot": "resizable-panel",
+      data: merged_panel_data_attributes
+    )
 
-        attrs[:style] = style_parts.join("; ") if style_parts.any?
-        attrs
-      end
-    end
+    attrs[:style] = style_parts.join("; ") if style_parts.any?
+    attrs
+  end
+end

data/app/behaviors/ui/resizable_panel_group_behavior.rb

@@ -1,41 +1,41 @@
 # frozen_string_literal: true
 
-    # Shared behavior for ResizablePanelGroup container component
-    # Handles Stimulus controller setup and data attributes
-    module UI::ResizablePanelGroupBehavior
-      # Generate Stimulus controller data attributes
-      def panel_group_data_attributes
-        {
-          controller: "ui--resizable",
-          ui__resizable_direction_value: @direction || "horizontal",
-          ui__resizable_keyboard_resize_by_value: @keyboard_resize_by || 10
-        }
-      end
+# Shared behavior for ResizablePanelGroup container component
+# Handles Stimulus controller setup and data attributes
+module UI::ResizablePanelGroupBehavior
+  # Generate Stimulus controller data attributes
+  def panel_group_data_attributes
+    {
+      controller: "ui--resizable",
+      ui__resizable_direction_value: @direction || "horizontal",
+      ui__resizable_keyboard_resize_by_value: @keyboard_resize_by || 10
+    }
+  end
 
-      # Merge user-provided data attributes with panel group controller data
-      def merged_panel_group_data_attributes
-        user_data = @attributes&.fetch(:data, {}) || {}
-        user_data.merge(panel_group_data_attributes)
-      end
+  # Merge user-provided data attributes with panel group controller data
+  def merged_panel_group_data_attributes
+    user_data = @attributes&.fetch(:data, {}) || {}
+    user_data.merge(panel_group_data_attributes)
+  end
 
-      # Base CSS classes for the panel group container
-      def panel_group_base_classes
-        classes = [
-          "flex h-full w-full overflow-hidden",
-          @direction == "vertical" ? "flex-col" : "flex-row"
-        ]
-        classes << @classes if @classes.present?
-        classes.join(" ")
-      end
+  # Base CSS classes for the panel group container
+  def panel_group_base_classes
+    classes = [
+      "flex h-full w-full overflow-hidden",
+      (@direction == "vertical") ? "flex-col" : "flex-row"
+    ]
+    classes << @classes if @classes.present?
+    classes.join(" ")
+  end
 
-      # Build complete HTML attributes hash for panel group container
-      def panel_group_html_attributes
-        base_attrs = @attributes&.except(:data) || {}
-        base_attrs.merge(
-          class: panel_group_base_classes,
-          "data-panel-group-direction": @direction || "horizontal",
-          "data-slot": "resizable-panel-group",
-          data: merged_panel_group_data_attributes
-        )
-      end
-    end
+  # Build complete HTML attributes hash for panel group container
+  def panel_group_html_attributes
+    base_attrs = @attributes&.except(:data) || {}
+    base_attrs.merge(
+      class: panel_group_base_classes,
+      "data-panel-group-direction": @direction || "horizontal",
+      "data-slot": "resizable-panel-group",
+      data: merged_panel_group_data_attributes
+    )
+  end
+end

data/app/behaviors/ui/responsive_dialog_behavior.rb

@@ -2,40 +2,50 @@
 
 require "tailwind_merge"
 
-    # Shared behavior for ResponsiveDialog component
-    # Combines Dialog (desktop) and Drawer (mobile) with responsive switching
-    module UI::ResponsiveDialogBehavior
-      # Generate data attributes for Stimulus controller
-      def responsive_dialog_data_attributes
-        {
-          controller: "ui--responsive-dialog",
-          ui__responsive_dialog_open_value: @open,
-          ui__responsive_dialog_breakpoint_value: @breakpoint || 768
-        }
-      end
+# UI::ResponsiveDialogBehavior
+#
+# @ui_component Responsive Dialog
+# @ui_description ResponsiveDialog - Renders Dialog on desktop, Drawer on mobile Uses hybrid CSS + Stimulus approach for responsive switching at 768px (md breakpoint)
+# @ui_category other
+#
+# @ui_anatomy Responsive Dialog - Root container with state management (required)
+#
+# @ui_feature Custom styling with Tailwind classes
+# @ui_feature Focus management
+# @ui_feature Animation support
+#
+module UI::ResponsiveDialogBehavior
+  # Generate data attributes for Stimulus controller
+  def responsive_dialog_data_attributes
+    {
+      controller: "ui--responsive-dialog",
+      ui__responsive_dialog_open_value: @open,
+      ui__responsive_dialog_breakpoint_value: @breakpoint || 768
+    }
+  end
 
-      # Merge user-provided data attributes
-      def merged_responsive_dialog_data_attributes
-        user_data = @attributes&.fetch(:data, {}) || {}
-        user_data.merge(responsive_dialog_data_attributes)
-      end
+  # Merge user-provided data attributes
+  def merged_responsive_dialog_data_attributes
+    user_data = @attributes&.fetch(:data, {}) || {}
+    user_data.merge(responsive_dialog_data_attributes)
+  end
 
-      # Build complete HTML attributes hash
-      def responsive_dialog_html_attributes
-        base_attrs = @attributes&.except(:data) || {}
-        base_attrs.merge(
-          class: responsive_dialog_classes,
-          data: merged_responsive_dialog_data_attributes
-        )
-      end
+  # Build complete HTML attributes hash
+  def responsive_dialog_html_attributes
+    base_attrs = @attributes&.except(:data) || {}
+    base_attrs.merge(
+      class: responsive_dialog_classes,
+      data: merged_responsive_dialog_data_attributes
+    )
+  end
 
-      # Base CSS classes
-      def responsive_dialog_base_classes
-        ""
-      end
+  # Base CSS classes
+  def responsive_dialog_base_classes
+    ""
+  end
 
-      # Generate final classes using TailwindMerge
-      def responsive_dialog_classes
-        TailwindMerge::Merger.new.merge([responsive_dialog_base_classes, @classes].compact.join(" "))
-      end
-    end
+  # Generate final classes using TailwindMerge
+  def responsive_dialog_classes
+    TailwindMerge::Merger.new.merge([responsive_dialog_base_classes, @classes].compact.join(" "))
+  end
+end

data/app/behaviors/ui/scroll_area_behavior.rb

@@ -2,8 +2,23 @@
 
 # UI::ScrollAreaBehavior
 #
-# Shared behavior for ScrollArea root across ERB, ViewComponent, and Phlex implementations.
-# This module provides consistent HTML attribute generation and styling.
+# @ui_component Scroll Area
+# @ui_description ScrollArea - Phlex implementation
+# @ui_category layout
+#
+# @ui_anatomy Scroll Area - Augments native scroll functionality for custom, cross-browser styling. (required)
+# @ui_anatomy Viewport - Scrollable content container with hidden native scrollbar.
+#
+# @ui_feature Custom styling with Tailwind classes
+#
+# @ui_aria_pattern Scrollable Region
+# @ui_aria_reference https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/
+#
+# @ui_keyboard Enter Activates the focused element
+# @ui_keyboard End Moves focus to last item
+#
+# @ui_related carousel
+#
 module UI::ScrollAreaBehavior
   # Returns HTML attributes for the scroll area root element
   def scroll_area_html_attributes

data/app/behaviors/ui/scroll_area_corner_behavior.rb

@@ -2,8 +2,14 @@
 
 # UI::ScrollAreaCornerBehavior
 #
-# Shared behavior for ScrollArea corner across ERB, ViewComponent, and Phlex implementations.
-# This module provides consistent HTML attribute generation and styling.
+# @ui_component Scroll Area Corner
+# @ui_description Corner - Phlex implementation
+# @ui_category other
+#
+# @ui_anatomy Scroll Area Corner - Intersection element between vertical and horizontal scrollbars. (required)
+#
+# @ui_feature Custom styling with Tailwind classes
+#
 module UI::ScrollAreaCornerBehavior
   # Returns HTML attributes for the corner element
   def scroll_area_corner_html_attributes

data/app/behaviors/ui/scroll_area_scrollbar_behavior.rb

@@ -2,8 +2,14 @@
 
 # UI::ScrollAreaScrollbarBehavior
 #
-# Shared behavior for ScrollArea scrollbar across ERB, ViewComponent, and Phlex implementations.
-# This module provides consistent HTML attribute generation and styling.
+# @ui_component Scroll Area Scrollbar
+# @ui_description Scrollbar - Phlex implementation
+# @ui_category other
+#
+# @ui_anatomy Scroll Area Scrollbar - Custom scrollbar track that contains the draggable thumb. (required)
+#
+# @ui_feature Custom styling with Tailwind classes
+#
 module UI::ScrollAreaScrollbarBehavior
   # Returns HTML attributes for the scrollbar element
   def scroll_area_scrollbar_html_attributes

data/app/behaviors/ui/scroll_area_thumb_behavior.rb

@@ -2,8 +2,14 @@
 
 # UI::ScrollAreaThumbBehavior
 #
-# Shared behavior for ScrollArea thumb across ERB, ViewComponent, and Phlex implementations.
-# This module provides consistent HTML attribute generation and styling.
+# @ui_component Scroll Area Thumb
+# @ui_description Thumb - Phlex implementation
+# @ui_category other
+#
+# @ui_anatomy Scroll Area Thumb - Draggable scroll indicator inside the scrollbar. (required)
+#
+# @ui_feature Custom styling with Tailwind classes
+#
 module UI::ScrollAreaThumbBehavior
   # Returns HTML attributes for the thumb element
   def scroll_area_thumb_html_attributes