odt-ui-rails 2.2.4 → 2.2.5

data/lib/odt_ui/helper.rb

@@ -2,28 +2,7 @@
 
 module OdtUi
   module Helper
-    # =========================================================================
-    # Helpers for ODT-Lightweight-UI
-    # Standalone CSS First with seamless Tailwind CSS v4 support.
-    # =========================================================================
-
-    # Renders an ODT Button component.
-    #
-    # @param text [String, nil]
-    # @param variant [:filled, :frosted, :capsule, :ghost, :light, :outline, :outlined, :subtle]
-    # @param color [:primary, :secondary, :surface, :muted, :inverse, :success, :warning, :danger, :info, :neutral]
-    # @param size [:xs, :sm, :md, :lg, :xl]
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @param shadow [:none, :card, :dropdown, :modal, :popover, nil]
-    # @param icon_only [Boolean]
-    # @param full_width [Boolean]
-    # @param loading [Boolean]
-    # @param disabled [Boolean]
-    # @param href [String, nil]
-    # @param icon [String, nil]
-    # @param right_icon [String, nil]
-    # @param type [String]
-    # @return [ActiveSupport::SafeBuffer]
+
     def odt_button(text = nil, variant: :filled, color: :primary, size: :md, radius: nil, shadow: nil, icon_only: false, full_width: false, loading: false, disabled: false, href: nil, icon: nil, right_icon: nil, type: "button", **html_options, &block)
       variant_key = normalize_button_variant(variant)
       color_key = color.to_s.tr("_", "-")
@@ -31,11 +10,10 @@ module OdtUi
 
       classes = [
         "odt-btn",
+        "odt-btn--#{variant_key}",
         "odt-btn--#{variant_key}-#{color_key}",
         "odt-btn--#{size_key}"
       ]
-
-      classes << "odt-btn--capsule" if variant.to_sym == :capsule
       classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
       classes << "odt-shadow-#{shadow.to_s.tr('_', '-')}" if shadow.present?
       classes << "odt-btn--full-width" if full_width
@@ -74,16 +52,6 @@ module OdtUi
       end
     end
 
-    # Renders an ODT Badge component.
-    #
-    # @param text [String, nil]
-    # @param variant [:subtle, :filled, :outlined, :outline]
-    # @param color [:primary, :secondary, :success, :warning, :danger, :info, :neutral]
-    # @param size [:sm, :md]
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @param dot [Boolean]
-    # @param icon [String, nil]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_badge(text = nil, variant: :subtle, color: :primary, size: :md, radius: nil, dot: false, icon: nil, **html_options, &block)
       variant_key = variant.to_sym == :outline ? "outlined" : variant.to_s.tr("_", "-")
       color_key = color.to_s.tr("_", "-")
@@ -91,6 +59,7 @@ module OdtUi
 
       classes = [
         "odt-badge",
+        "odt-badge--#{variant_key}",
         "odt-badge--#{variant_key}-#{color_key}",
         "odt-badge--#{size_key}"
       ]
@@ -111,20 +80,6 @@ module OdtUi
       tag.span(inner_content, **opts)
     end
 
-    # Renders an ODT Card container.
-    #
-    # @param title [String, nil]
-    # @param subtitle [String, nil]
-    # @param variant [:elevated, :outlined, :subtle, :muted, :ghost, :frosted]
-    # @param background [Symbol, String, nil]
-    # @param border [Symbol, String, Boolean, nil]
-    # @param shadow [Symbol, String, nil]
-    # @param radius [Symbol, String, nil]
-    # @param padding [Symbol, String, nil]
-    # @param hoverable [Boolean]
-    # @param hover [Boolean] Alias for hoverable
-    # @param as [:div, :article, :section, :aside, :main]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_card(title: nil, subtitle: nil, variant: :elevated, background: nil, border: nil, shadow: nil, radius: nil, padding: nil, hoverable: false, hover: false, as: :div, **html_options, &block)
       tag_name = as.to_sym
       variant_key = variant.to_s.tr("_", "-")
@@ -165,12 +120,6 @@ module OdtUi
       tag.public_send(tag_name, inner_content, **opts)
     end
 
-    # Renders an ODT Alert banner.
-    #
-    # @param message [String, nil]
-    # @param variant [:success, :warning, :danger, :info]
-    # @param icon [String, nil]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_alert(message = nil, variant: :success, icon: nil, **html_options, &block)
       variant_key = variant.to_sym
       default_icons = {
@@ -200,15 +149,6 @@ module OdtUi
       tag.div(inner_content, **opts)
     end
 
-    # Renders an ODT Heading element.
-    #
-    # @param text [String, nil]
-    # @param as [:h1, :h2, :h3, :h4, :h5, :h6]
-    # @param size [:5xl, :4xl, :3xl, :2xl, :xl, :lg, nil]
-    # @param weight [:light, :normal, :medium, :semibold, :bold, :extrabold, nil]
-    # @param color [:strong, :default, :muted, :subtle, :disabled, :primary, :secondary, :success, :warning, :danger, :info]
-    # @param truncate [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_heading(text = nil, as: :h2, size: nil, weight: nil, color: :strong, truncate: false, **html_options, &block)
       tag_name = as.to_sym
       default_sizes = {
@@ -240,15 +180,6 @@ module OdtUi
       tag.public_send(tag_name, inner_content, **opts)
     end
 
-    # Renders styled typography body text.
-    #
-    # @param text [String, nil]
-    # @param as [:p, :span, :div, :label, :small]
-    # @param size [:xs, :sm, :base, :lg, :xl, :"2xl"]
-    # @param weight [:light, :normal, :medium, :semibold, :bold, :extrabold, nil]
-    # @param color [:default, :strong, :muted, :subtle, :disabled, :primary, :secondary, :success, :warning, :danger, :info]
-    # @param truncate [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_text(text = nil, as: :p, size: :base, weight: nil, color: :default, truncate: false, **html_options, &block)
       tag_name = as.to_sym
       resolved_size = size.to_s.tr("_", "-")
@@ -270,15 +201,6 @@ module OdtUi
       tag.public_send(tag_name, inner_content, **opts)
     end
 
-    # Renders an ODT Avatar element.
-    #
-    # @param name [String, nil]
-    # @param src [String, nil]
-    # @param size [:xs, :sm, :md, :lg, :xl, :"2xl"]
-    # @param color [:secondary, :primary, :neutral]
-    # @param icon [String]
-    # @param fallback [String, nil]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_avatar(name: nil, src: nil, size: :md, color: :secondary, icon: "fa-solid fa-user", fallback: nil, **html_options)
       size_key = size.to_s.tr("_", "-")
       color_key = color.to_s.tr("_", "-")
@@ -305,27 +227,6 @@ module OdtUi
       tag.div(inner_content, **opts)
     end
 
-    # Renders an ODT text/number/email/password input.
-    #
-    # @param label [String, nil]
-    # @param variant [:outlined, :filled, :frosted]
-    # @param size [:sm, :md, :lg]
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @param type [String]
-    # @param placeholder [String, nil]
-    # @param error [String, nil]
-    # @param helper [String, nil]
-    # @param helper_text [String, nil] Alias for helper
-    # @param success [String, nil]
-    # @param left_icon [String, nil]
-    # @param right_icon [String, nil]
-    # @param prefix [String, nil]
-    # @param suffix [String, nil]
-    # @param addon_before [String, nil]
-    # @param addon_after [String, nil]
-    # @param disabled [Boolean]
-    # @param full_width [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_input(label: nil, variant: :outlined, size: :md, radius: nil, type: "text", placeholder: nil, error: nil, helper: nil, helper_text: nil, success: nil, left_icon: nil, right_icon: nil, prefix: nil, suffix: nil, addon_before: nil, addon_after: nil, disabled: false, full_width: true, **html_options)
       variant_key = variant.to_s.tr("_", "-")
       size_key = size.to_s.tr("_", "-")
@@ -405,21 +306,6 @@ module OdtUi
       end
     end
 
-    # Renders an ODT textarea field.
-    #
-    # @param label [String, nil]
-    # @param variant [:outlined, :filled, :frosted]
-    # @param size [:sm, :md, :lg]
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @param rows [Integer]
-    # @param resize [:none, :vertical, :horizontal, :both]
-    # @param error [String, nil]
-    # @param helper [String, nil]
-    # @param helper_text [String, nil]
-    # @param success [String, nil]
-    # @param disabled [Boolean]
-    # @param full_width [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_textarea(label: nil, variant: :outlined, size: :md, radius: nil, rows: 4, resize: :vertical, error: nil, helper: nil, helper_text: nil, success: nil, disabled: false, full_width: true, **html_options, &block)
       variant_key = variant.to_s.tr("_", "-")
       size_key = size.to_s.tr("_", "-")
@@ -468,81 +354,24 @@ module OdtUi
       end
     end
 
-    # Renders an ODT select dropdown.
-    #
-    # @param label [String, nil]
-    # @param options [Array] Options compatible with Rails options_for_select
-    # @param variant [:outlined, :filled, :frosted]
-    # @param size [:sm, :md, :lg]
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @param prompt [String, nil]
-    # @param error [String, nil]
-    # @param helper [String, nil]
-    # @param helper_text [String, nil]
-    # @param success [String, nil]
-    # @param disabled [Boolean]
-    # @param full_width [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_select(label: nil, options: [], variant: :outlined, size: :md, radius: nil, prompt: nil, error: nil, helper: nil, helper_text: nil, success: nil, disabled: false, full_width: true, **html_options)
-      variant_key = variant.to_s.tr("_", "-")
-      size_key = size.to_s.tr("_", "-")
-      resolved_helper = helper.presence || helper_text.presence
-      has_error = error.present?
-      has_success = success.present? && !has_error
-
-      classes = [
-        "odt-select",
-        "odt-select--#{variant_key}",
-        "odt-select--#{size_key}"
-      ]
-
-      classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
-      classes << "odt-select--error" if has_error
-      classes << "odt-select--success" if has_success
-      classes << html_options.delete(:class)
-
-      opts = html_options.merge(
-        class: classes.compact.reject(&:blank?).join(" "),
-        disabled: disabled
+      render_custom_select(
+        label: label,
+        options: options,
+        variant: variant,
+        size: size,
+        radius: radius,
+        prompt: prompt,
+        error: error,
+        helper: helper,
+        helper_text: helper_text,
+        success: success,
+        disabled: disabled,
+        full_width: full_width,
+        **html_options
       )
-
-      option_tags = if prompt.present?
-        tag.option(prompt, value: "") + (options.is_a?(String) ? options.html_safe : options_for_select(options))
-      else
-        options.is_a?(String) ? options.html_safe : options_for_select(options)
-      end
-
-      container_classes = ["odt-input-container"]
-      container_classes << "odt-input-container--full-width" if full_width
-
-      tag.div(class: container_classes.join(" ")) do
-        parts = []
-        parts << tag.label(label, class: "odt-label") if label.present?
-        parts << tag.select(option_tags, **opts)
-
-        if has_error
-          parts << tag.p(error, class: "odt-error-text", role: "alert")
-        elsif has_success
-          parts << tag.p(success, class: "odt-success-text")
-        elsif resolved_helper.present?
-          parts << tag.p(resolved_helper, class: "odt-helper-text")
-        end
-
-        safe_join(parts)
-      end
     end
 
-    # Renders an ODT styled Checkbox.
-    #
-    # @param label [String, nil]
-    # @param description [String, nil]
-    # @param checked [Boolean]
-    # @param color [:primary, :secondary, :success, :warning, :danger, :dark, :neutral]
-    # @param size [:sm, :md, :lg]
-    # @param radius [:none, :xs, :sm, :md, :lg, :full, nil]
-    # @param disabled [Boolean]
-    # @param error [String, nil]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_checkbox(label: nil, description: nil, checked: false, color: :primary, size: :md, radius: nil, disabled: false, error: nil, **html_options)
       color_key = color.to_sym == :dark ? "neutral" : color.to_s.tr("_", "-")
       size_key = size.to_s.tr("_", "-")
@@ -587,16 +416,6 @@ module OdtUi
       end
     end
 
-    # Renders an ODT styled Radio button.
-    #
-    # @param label [String, nil]
-    # @param description [String, nil]
-    # @param checked [Boolean]
-    # @param color [:primary, :secondary, :success, :warning, :danger, :dark, :neutral]
-    # @param size [:sm, :md, :lg]
-    # @param disabled [Boolean]
-    # @param error [String, nil]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_radio(label: nil, description: nil, checked: false, color: :primary, size: :md, disabled: false, error: nil, **html_options)
       color_key = color.to_sym == :dark ? "neutral" : color.to_s.tr("_", "-")
       size_key = size.to_s.tr("_", "-")
@@ -638,15 +457,6 @@ module OdtUi
       end
     end
 
-    # Renders a Form Group wrapper with label, slot, error, and helper texts.
-    #
-    # @param label [String, nil]
-    # @param error [String, nil]
-    # @param helper [String, nil]
-    # @param helper_text [String, nil]
-    # @param success [String, nil]
-    # @param required [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_form_group(label: nil, error: nil, helper: nil, helper_text: nil, success: nil, required: false, **html_options, &block)
       resolved_helper = helper.presence || helper_text.presence
       has_error = error.present?
@@ -677,12 +487,7 @@ module OdtUi
       end
     end
 
-    # Renders an ODT Toaster viewport container.
-    #
-    # @param position [:top_right, :top_center, :top_left, :bottom_right, :bottom_center, :bottom_left]
-    # @param id [String] Element ID for Turbo Stream targeting (default: "odt-toasts")
-    # @return [ActiveSupport::SafeBuffer]
-    def odt_toaster(position: :top_right, id: "odt-toasts", **html_options, &block)
+    def odt_toaster(position: :top_right, id: "odt-toasts", expand: true, **html_options, &block)
       pos_key = position.to_s.tr("_", "-")
       classes = [
         "odt-toaster",
@@ -690,44 +495,42 @@ module OdtUi
         html_options.delete(:class)
       ]
 
+      data_attrs = {
+        controller: "odt-toaster",
+        odt_toaster_position_value: pos_key,
+        odt_toaster_expand_value: expand,
+        action: "mouseenter->odt-toaster#hover mouseleave->odt-toaster#leave"
+      }.merge(html_options.delete(:data) || {})
+
       opts = html_options.merge(
         id: id,
         class: classes.compact.reject(&:blank?).join(" "),
         role: "region",
-        aria: { live: "polite" }
+        aria: { live: "polite" },
+        data: data_attrs
       )
 
       inner_content = block_given? ? capture(&block) : nil
       tag.div(inner_content, **opts)
     end
 
-    # Renders a single ODT Toast card with Stimulus controller.
-    #
-    # @param message [String, nil]
-    # @param title [String, nil]
-    # @param variant [:success, :warning, :danger, :error, :info, :loading, :frosted]
-    # @param icon [String, nil]
-    # @param duration [Integer] Auto-dismiss duration in milliseconds (0 to disable)
-    # @param dismissible [Boolean] Whether to display close button
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @return [ActiveSupport::SafeBuffer]
-    def odt_toast(message = nil, title: nil, variant: :success, icon: nil, duration: 4000, dismissible: true, radius: nil, **html_options, &block)
-      variant_key = variant.to_sym == :error ? :danger : variant.to_sym
-      default_icons = {
-        success: "fa-solid fa-circle-check",
-        warning: "fa-solid fa-triangle-exclamation",
-        danger:  "fa-solid fa-circle-xmark",
-        info:    "fa-solid fa-circle-info",
-        loading: "fa-solid fa-spinner"
-      }
-
-      icon_name = icon || default_icons[variant_key] || default_icons[:info]
+    def odt_toast(message = nil, title: nil, variant: :elevated, type: :default, icon: nil, duration: 4000, dismissible: true, radius: :"2xl", rich_colors: false, **html_options, &block)
+      semantic_types = %i[success warning danger error info loading]
+      
+      if semantic_types.include?(variant.to_sym)
+        resolved_type = variant.to_sym == :error ? :danger : variant.to_sym
+        resolved_variant = :elevated
+      else
+        resolved_variant = variant.to_sym
+        resolved_type = (type.to_sym == :error ? :danger : type.to_sym)
+      end
 
       classes = [
         "odt-toast",
-        "odt-toast--#{variant_key.to_s.tr('_', '-')}"
+        "odt-toast--variant-#{resolved_variant.to_s.tr('_', '-')}"
       ]
       classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      classes << "odt-toast--rich-#{resolved_type}" if rich_colors && resolved_type != :default
       classes << html_options.delete(:class)
 
       data_attrs = {
@@ -743,23 +546,54 @@ module OdtUi
       )
 
       parts = []
-      if icon_name.present?
-        icon_classes = ["odt-toast__icon", "odt-toast__icon--#{variant_key}"]
-        parts << tag.span(render_icon_element(icon_name), class: icon_classes.join(" "))
+
+      if icon.present?
+        icon_classes = ["odt-toast__icon", "odt-toast__icon--#{resolved_type}"]
+        parts << tag.span(render_icon_element(icon), class: icon_classes.join(" "))
+      elsif resolved_type != :default
+        icon_classes = ["odt-toast__icon", "odt-toast__icon--#{resolved_type}"]
+        svg_icon = case resolved_type
+        when :success
+          tag.svg(tag.path(d: "M20 6L9 17l-5-5"), width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2.5", "stroke-linecap": "round", "stroke-linejoin": "round")
+        when :info
+          tag.svg(safe_join([tag.circle(cx: "12", cy: "12", r: "10"), tag.line(x1: "12", y1: "16", x2: "12", y2: "12"), tag.line(x1: "12", y1: "8", x2: "12.01", y2: "8")]), width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2.5", "stroke-linecap": "round", "stroke-linejoin": "round")
+        when :warning
+          tag.svg(safe_join([tag.path(d: "M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"), tag.line(x1: "12", y1: "9", x2: "12", y2: "13"), tag.line(x1: "12", y1: "17", x2: "12.01", y2: "17")]), width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2.5", "stroke-linecap": "round", "stroke-linejoin": "round")
+        when :danger
+          tag.svg(safe_join([tag.circle(cx: "12", cy: "12", r: "10"), tag.line(x1: "15", y1: "9", x2: "9", y2: "15"), tag.line(x1: "9", y1: "9", x2: "15", y2: "15")]), width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2.5", "stroke-linecap": "round", "stroke-linejoin": "round")
+        when :loading
+          tag.svg(tag.path(d: "M21 12a9 9 0 11-6.219-8.56"), width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2.5", "stroke-linecap": "round", "stroke-linejoin": "round")
+        end
+        parts << tag.span(svg_icon, class: icon_classes.join(" ")) if svg_icon
       end
 
       body_content = block_given? ? capture(&block) : message
 
       parts << tag.div(class: "odt-toast__content") do
         c_parts = []
-        c_parts << tag.p(title, class: "odt-toast__title") if title.present?
-        c_parts << tag.p(body_content, class: "odt-toast__message") if body_content.present?
+        if title.present?
+          c_parts << tag.p(title, class: "odt-toast__title")
+          c_parts << tag.p(body_content, class: "odt-toast__description") if body_content.present?
+        elsif body_content.present?
+          c_parts << tag.p(body_content, class: "odt-toast__title")
+        end
         safe_join(c_parts)
       end
 
       if dismissible
+        close_svg = tag.svg(
+          safe_join([tag.line(x1: "18", y1: "6", x2: "6", y2: "18"), tag.line(x1: "6", y1: "6", x2: "18", y2: "18")]),
+          width: "14",
+          height: "14",
+          viewBox: "0 0 24 24",
+          fill: "none",
+          stroke: "currentColor",
+          "stroke-width": "2.5",
+          "stroke-linecap": "round",
+          "stroke-linejoin": "round"
+        )
         parts << tag.button(
-          "×".html_safe,
+          close_svg,
           type: "button",
           class: "odt-toast__close",
           aria: { label: "Close" },
@@ -771,11 +605,6 @@ module OdtUi
       tag.div(inner_content, **opts)
     end
 
-    # Renders all active flash messages as ODT Toasts.
-    #
-    # @param flash_hash [ActionDispatch::Flash::FlashHash, Hash] Flash messages hash (default: flash)
-    # @param duration [Integer] Auto-dismiss duration in milliseconds
-    # @return [ActiveSupport::SafeBuffer]
     def odt_flash_toasts(flash_hash = flash, duration: 4000)
       return "".html_safe if flash_hash.blank?
 
@@ -800,15 +629,6 @@ module OdtUi
       safe_join(toasts)
     end
 
-    # Generates a Turbo Stream action to render a toast asynchronously.
-    #
-    # @param message [String, nil]
-    # @param title [String, nil]
-    # @param variant [:success, :warning, :danger, :error, :info]
-    # @param target [String] Target container ID (default: "odt-toasts")
-    # @param action [:append, :prepend] Turbo stream action (default: :append)
-    # @param duration [Integer] Auto-dismiss duration in ms (default: 4000)
-    # @return [ActiveSupport::SafeBuffer]
     def odt_toast_stream(message = nil, title: nil, variant: :success, target: "odt-toasts", action: :append, duration: 4000, **options)
       toast_html = odt_toast(message, title: title, variant: variant, duration: duration, **options)
 
@@ -821,17 +641,6 @@ module OdtUi
       end
     end
 
-    # Renders an ODT Modal dialog container with Stimulus controller.
-    #
-    # @param id [String, nil] Unique HTML ID of the modal
-    # @param title [String, nil] Header title text
-    # @param subtitle [String, nil] Header subtitle text
-    # @param size [:sm, :md, :lg, :xl, :full] Dialog width size (default: :md)
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full, nil]
-    # @param dismissible [Boolean] Whether to render the header close button (default: true)
-    # @param open [Boolean] Whether modal is initially open (default: false)
-    # @param prevent_backdrop_close [Boolean] Prevent closing when clicking overlay (default: false)
-    # @return [ActiveSupport::SafeBuffer]
     def odt_modal(id: nil, title: nil, subtitle: nil, size: :md, radius: :"2xl", dismissible: true, open: false, prevent_backdrop_close: false, **html_options, &block)
       size_key = size.to_s.tr("_", "-")
       radius_key = radius.to_s.tr("_", "-")
@@ -885,12 +694,6 @@ module OdtUi
       end
     end
 
-    # Renders an ODT Modal Header subcomponent.
-    #
-    # @param title [String, nil]
-    # @param subtitle [String, nil]
-    # @param dismissible [Boolean]
-    # @return [ActiveSupport::SafeBuffer]
     def odt_modal_header(title: nil, subtitle: nil, dismissible: true, **html_options, &block)
       classes = ["odt-modal__header", html_options.delete(:class)]
       opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
@@ -922,9 +725,6 @@ module OdtUi
       end
     end
 
-    # Renders an ODT Modal Body subcomponent.
-    #
-    # @return [ActiveSupport::SafeBuffer]
     def odt_modal_body(**html_options, &block)
       classes = ["odt-modal__body", html_options.delete(:class)]
       opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
@@ -932,9 +732,6 @@ module OdtUi
       tag.div(content, **opts)
     end
 
-    # Renders an ODT Modal Footer subcomponent.
-    #
-    # @return [ActiveSupport::SafeBuffer]
     def odt_modal_footer(**html_options, &block)
       classes = ["odt-modal__footer", html_options.delete(:class)]
       opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
@@ -942,9 +739,256 @@ module OdtUi
       tag.div(content, **opts)
     end
 
+    def odt_dropdown_menu(open: false, close_on_click_outside: true, close_on_select: true, full_width: false, **html_options, &block)
+      classes = [
+        "odt-dropdown",
+        ("odt-dropdown--full-width" if full_width),
+        html_options.delete(:class)
+      ].compact.reject(&:blank?)
+
+      data_attrs = {
+        controller: "odt-dropdown",
+        odt_dropdown_open_value: open,
+        odt_dropdown_close_on_click_outside_value: close_on_click_outside,
+        odt_dropdown_close_on_select_value: close_on_select
+      }.merge(html_options.delete(:data) || {})
+
+      opts = html_options.merge(
+        class: classes.join(" "),
+        data: data_attrs
+      )
+
+      tag.div(**opts, &block)
+    end
+
+    def odt_dropdown_trigger(text = nil, label: nil, helper: nil, helper_text: nil, error: nil, variant: :outlined, size: :md, radius: :xl, chevron: true, placeholder: nil, left_icon: nil, right_icon: nil, full_width: false, disabled: false, **html_options, &block)
+      variant_key = variant.to_s.tr("_", "-")
+      size_key = size.to_s.tr("_", "-")
+      radius_key = radius.to_s.tr("_", "-")
+      resolved_helper = helper.presence || helper_text.presence
+      has_error = error.present?
+
+      button_classes = [
+        "odt-dropdown__trigger",
+        "odt-dropdown__trigger--#{variant_key}",
+        "odt-dropdown__trigger--#{size_key}",
+        "odt-radius-#{radius_key}",
+        ("w-full" if full_width),
+        ("odt-dropdown__trigger--error" if has_error),
+        html_options.delete(:class)
+      ].compact.reject(&:blank?)
+
+      btn_data = {
+        odt_dropdown_target: "trigger",
+        action: "click->odt-dropdown#toggle keydown->odt-dropdown#navigate"
+      }.merge(html_options.delete(:data) || {})
+
+      btn_opts = html_options.merge(
+        type: "button",
+        class: button_classes.join(" "),
+        disabled: disabled,
+        aria: { haspopup: "menu", expanded: "false" },
+        data: btn_data
+      )
+
+      button_content = block_given? ? capture(&block) : text
+      content_parts = []
+      if left_icon.present?
+        content_parts << render_icon_element(left_icon)
+      end
+
+      span_class = button_content.blank? && placeholder.present? ? "odt-dropdown__trigger-text odt-dropdown__placeholder" : "odt-dropdown__trigger-text"
+      content_parts << tag.span(button_content.presence || placeholder, class: span_class, data: { odt_dropdown_target: "text" })
+
+      if right_icon.present?
+        content_parts << render_icon_element(right_icon)
+      elsif chevron
+        content_parts << tag.span(class: "odt-dropdown__chevron", data: { odt_dropdown_target: "chevron" }) do
+          tag.svg(width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round", "stroke-linejoin": "round") do
+            tag.polyline(points: "6 9 12 15 18 9")
+          end
+        end
+      end
+
+      button_node = tag.button(safe_join(content_parts), **btn_opts)
+
+      if label.present? || resolved_helper.present? || has_error
+        container_classes = [
+          "odt-dropdown__container",
+          ("odt-dropdown__container--full-width" if full_width)
+        ].compact.join(" ")
+
+        tag.div(class: container_classes) do
+          wrapper_parts = []
+          wrapper_parts << tag.span(label, class: "odt-dropdown__label") if label.present?
+          wrapper_parts << button_node
+          if has_error
+            wrapper_parts << tag.p(error, class: "odt-error-text", role: "alert")
+          elsif resolved_helper.present?
+            wrapper_parts << tag.p(resolved_helper, class: "odt-helper-text")
+          end
+          safe_join(wrapper_parts)
+        end
+      else
+        button_node
+      end
+    end
+
+    def odt_dropdown_content(align: :start, side: :bottom, radius: :xl, shadow: :dropdown, full_width: false, **html_options, &block)
+      align_key = align.to_s.tr("_", "-")
+      side_key = side.to_s.tr("_", "-")
+      radius_key = radius.to_s.tr("_", "-")
+      shadow_key = shadow.to_s.tr("_", "-")
+
+      classes = [
+        "odt-dropdown__content",
+        "odt-dropdown__content--align-#{align_key}",
+        "odt-dropdown__content--side-#{side_key}",
+        "odt-radius-#{radius_key}",
+        "odt-shadow-#{shadow_key}",
+        ("w-full" if full_width),
+        "hidden",
+        html_options.delete(:class)
+      ].compact.reject(&:blank?)
+
+      opts = html_options.merge(
+        role: "menu",
+        tabindex: "-1",
+        class: classes.join(" "),
+        data: { odt_dropdown_target: "content" }.merge(html_options.delete(:data) || {})
+      )
+
+      tag.div(**opts, &block)
+    end
+
+    def odt_dropdown_item(text = nil, href: nil, left_icon: nil, right_icon: nil, shortcut: nil, destructive: false, disabled: false, inset: false, value: nil, **html_options, &block)
+      classes = [
+        "odt-dropdown__item",
+        ("odt-dropdown__item--destructive" if destructive),
+        ("odt-dropdown__item--disabled" if disabled),
+        ("odt-dropdown__item--inset" if inset),
+        html_options.delete(:class)
+      ].compact.reject(&:blank?)
+
+      data_attrs = {
+        action: "click->odt-dropdown#select"
+      }
+      data_attrs[:value] = value if value.present?
+      data_attrs.merge!(html_options.delete(:data) || {})
+
+      opts = html_options.merge(
+        role: "menuitem",
+        tabindex: disabled ? "-1" : "0",
+        class: classes.join(" "),
+        data: data_attrs
+      )
+      opts[:disabled] = true if disabled
+
+      content = block_given? ? capture(&block) : text
+      parts = []
+      if left_icon.present?
+        parts << tag.span(render_icon_element(left_icon), class: "odt-dropdown__item-icon")
+      end
+
+      parts << tag.span(content, class: "odt-dropdown__item-content")
+
+      if shortcut.present?
+        parts << tag.span(shortcut, class: "odt-dropdown__shortcut")
+      end
+
+      if right_icon.present?
+        parts << tag.span(render_icon_element(right_icon), class: "odt-dropdown__item-right-icon")
+      end
+
+      inner_content = safe_join(parts)
+
+      if href.present?
+        link_to(inner_content, href, opts)
+      else
+        opts[:type] = "button"
+        tag.button(inner_content, **opts)
+      end
+    end
+
+    def odt_dropdown_label(text = nil, inset: false, **html_options, &block)
+      classes = [
+        "odt-dropdown__label-heading",
+        ("odt-dropdown__label-heading--inset" if inset),
+        html_options.delete(:class)
+      ].compact.reject(&:blank?)
+
+      content = block_given? ? capture(&block) : text
+      tag.div(content, class: classes.join(" "), **html_options)
+    end
+
+    def odt_dropdown_separator(**html_options)
+      classes = ["odt-dropdown__separator", html_options.delete(:class)].compact.reject(&:blank?)
+      tag.hr(class: classes.join(" "), **html_options)
+    end
+
+    def odt_dropdown_shortcut(text = nil, **html_options, &block)
+      classes = ["odt-dropdown__shortcut", html_options.delete(:class)].compact.reject(&:blank?)
+      content = block_given? ? capture(&block) : text
+      tag.span(content, class: classes.join(" "), **html_options)
+    end
+
     private
 
-    # Normalizes button variant key with backwards compatibility
+    def render_custom_select(label: nil, options: [], variant: :outlined, size: :md, radius: nil, prompt: nil, error: nil, helper: nil, helper_text: nil, success: nil, disabled: false, full_width: true, **html_options)
+      resolved_helper = helper.presence || helper_text.presence
+      name = html_options.delete(:name)
+      id = html_options.delete(:id)
+      selected_value = html_options.delete(:selected) || html_options.delete(:value)
+
+      items = if options.is_a?(Array)
+        options.map do |opt|
+          if opt.is_a?(Array)
+            [opt[0].to_s, opt[1].to_s]
+          else
+            [opt.to_s, opt.to_s]
+          end
+        end
+      else
+        []
+      end
+
+      selected_pair = items.find { |_, val| val == selected_value.to_s }
+      display_text = selected_pair ? selected_pair[0] : (prompt || items.first&.first || "")
+      current_value = selected_pair ? selected_pair[1] : (prompt ? "" : items.first&.last)
+
+      odt_dropdown_menu(full_width: full_width) do
+        parts = []
+        if name.present?
+          parts << tag.input(type: "hidden", name: name, value: current_value, id: id, data: { odt_dropdown_target: "hiddenInput" })
+        end
+
+        parts << odt_dropdown_trigger(
+          display_text,
+          label: label,
+          helper: resolved_helper,
+          error: error,
+          variant: variant,
+          size: size,
+          radius: radius || :xl,
+          full_width: full_width,
+          disabled: disabled
+        )
+
+        parts << odt_dropdown_content(radius: radius || :xl, full_width: full_width) do
+          item_parts = []
+          if prompt.present?
+            item_parts << odt_dropdown_item(prompt, value: "")
+          end
+          items.each do |lbl, val|
+            item_parts << odt_dropdown_item(lbl, value: val)
+          end
+          safe_join(item_parts)
+        end
+
+        safe_join(parts)
+      end
+    end
+
     def normalize_button_variant(variant)
       case variant.to_sym
       when :light
@@ -964,7 +1008,6 @@ module OdtUi
       end
     end
 
-    # Computes initials from a full name (e.g., "John Doe" -> "JD")
     def compute_avatar_initials(name)
       return nil if name.blank?
 
@@ -976,7 +1019,6 @@ module OdtUi
       end
     end
 
-    # Safely renders an icon (SVG or HTML class)
     def render_icon_element(icon)
       return nil if icon.blank?