odt-ui-rails 2.0.1 → 2.2.0

data/lib/odt_ui/helper.rb

@@ -2,154 +2,68 @@
 
 module OdtUi
   module Helper
-    BUTTON_VARIANTS = {
-      filled: {
-        primary: "bg-primary-500 text-white hover:bg-primary-600 active:bg-primary-700 shadow-card hover:shadow-lg focus-visible:ring-primary-400",
-        secondary: "bg-secondary-500 text-slate-900 hover:bg-secondary-600 active:bg-secondary-700 shadow-card hover:shadow-lg focus-visible:ring-secondary-400",
-        success: "bg-success text-white hover:opacity-90 active:opacity-100 shadow-sm focus-visible:ring-green-400",
-        warning: "bg-warning text-slate-900 hover:opacity-90 active:opacity-100 shadow-sm focus-visible:ring-amber-400",
-        danger: "bg-danger text-white hover:opacity-90 active:opacity-100 shadow-sm focus-visible:ring-red-400",
-        neutral: "bg-neutral-800 text-white hover:bg-neutral-900 active:bg-neutral-950 shadow-sm focus-visible:ring-neutral-400"
-      },
-      light: {
-        primary: "bg-primary-50 text-primary-700 hover:bg-primary-100 active:bg-primary-200 focus-visible:ring-primary-300",
-        secondary: "bg-secondary-50 text-secondary-900 hover:bg-secondary-100 active:bg-secondary-200 focus-visible:ring-secondary-300",
-        success: "bg-surface-success text-fg-success hover:bg-green-100 active:bg-green-200 focus-visible:ring-green-300",
-        warning: "bg-surface-warning text-fg-warning hover:bg-amber-100 active:bg-amber-200 focus-visible:ring-amber-300",
-        danger: "bg-surface-danger text-fg-danger hover:bg-red-100 active:bg-red-200 focus-visible:ring-red-300",
-        neutral: "bg-surface-muted text-fg-muted hover:bg-surface-subtle active:bg-surface-subtle focus-visible:ring-neutral-300"
-      },
-      outline: {
-        primary: "border border-primary-300 text-primary-600 bg-transparent hover:bg-primary-50 active:bg-primary-100 focus-visible:ring-primary-300",
-        secondary: "border border-secondary-300 text-secondary-900 bg-transparent hover:bg-secondary-50 active:bg-secondary-100 focus-visible:ring-secondary-300",
-        danger: "border border-danger text-danger bg-transparent hover:bg-surface-danger active:bg-red-100 focus-visible:ring-red-300",
-        neutral: "border border-line text-fg bg-transparent hover:bg-surface-subtle active:bg-surface-muted focus-visible:ring-neutral-300"
-      },
-      subtle: {
-        primary: "bg-transparent text-primary-600 hover:bg-primary-50 active:bg-primary-100",
-        secondary: "bg-transparent text-secondary-900 hover:bg-secondary-50 active:bg-secondary-100",
-        neutral: "bg-transparent text-fg hover:bg-surface-subtle active:bg-surface-muted",
-        danger: "bg-transparent text-danger hover:bg-surface-danger active:bg-red-100"
-      },
-      ghost: {
-        primary: "bg-transparent text-fg-primary hover:text-primary-600 hover:bg-primary-50 active:bg-primary-100",
-        secondary: "bg-transparent text-fg hover:bg-surface-muted active:bg-surface-subtle",
-        neutral: "bg-transparent text-fg-muted hover:text-fg hover:bg-surface-muted active:bg-surface-subtle"
-      }
-    }.freeze
-
-    BUTTON_SIZES = {
-      xs: "px-2.5 py-1 text-xs gap-1",
-      sm: "px-3.5 py-1.5 text-xs gap-1.5 font-medium",
-      md: "px-5 py-2.5 text-sm gap-2 font-medium",
-      lg: "px-6 py-3 text-base gap-2.5 font-semibold",
-      xl: "px-7 py-3.5 text-lg gap-3 font-semibold"
-    }.freeze
-
-    RADIUS_CLASSES = {
-      none: "rounded-none",
-      xs: "rounded-xs",
-      sm: "rounded-sm",
-      md: "rounded-md",
-      lg: "rounded-lg",
-      xl: "rounded-xl",
-      "2xl": "rounded-2xl",
-      "3xl": "rounded-3xl",
-      "4xl": "rounded-4xl",
-      full: "rounded-full"
-    }.freeze
-
-    BADGE_VARIANTS = {
-      subtle: {
-        primary: "bg-primary-50 text-primary-600",
-        secondary: "bg-secondary-100 text-secondary-900",
-        success: "bg-surface-success text-success",
-        warning: "bg-surface-warning text-warning",
-        danger: "bg-surface-danger text-danger",
-        info: "bg-surface-info text-info",
-        neutral: "bg-surface-muted text-fg-muted"
-      },
-      filled: {
-        primary: "bg-primary-500 text-white",
-        secondary: "bg-secondary-500 text-slate-900",
-        success: "bg-success text-white",
-        warning: "bg-warning text-slate-900",
-        danger: "bg-danger text-white",
-        info: "bg-info text-white",
-        neutral: "bg-neutral-800 text-white"
-      },
-      outline: {
-        primary: "border border-primary-300 text-primary-600 bg-transparent",
-        secondary: "border border-secondary-300 text-secondary-800 bg-transparent",
-        success: "border border-line-success text-success bg-transparent",
-        warning: "border border-line-warning text-warning bg-transparent",
-        danger: "border border-line-danger text-danger bg-transparent",
-        info: "border border-info text-info bg-transparent",
-        neutral: "border border-line text-fg-muted bg-transparent"
-      }
-    }.freeze
-
-    BADGE_SIZES = {
-      sm: "px-3 py-1.5 text-xs font-semibold",
-      md: "px-3.5 py-1.5 text-sm font-semibold"
-    }.freeze
-
-    CARD_VARIANTS = {
-      elevated: "bg-surface shadow-card",
-      frosted: "bg-surface/70 backdrop-blur-xl shadow-card",
-      subtle: "bg-surface-subtle",
-      muted: "bg-surface-muted",
-      outlined: "bg-surface border border-line shadow-none"
-    }.freeze
-
-    AVATAR_SIZES = {
-      xs: "w-6 h-6 min-w-6 min-h-6 text-[10px]",
-      sm: "w-8 h-8 min-w-8 min-h-8 text-xs",
-      md: "w-10 h-10 min-w-10 min-h-10 text-sm",
-      lg: "w-12 h-12 min-w-12 min-h-12 text-base",
-      xl: "w-16 h-16 min-w-16 min-h-16 text-xl"
-    }.freeze
-
-    AVATAR_COLORS = {
-      secondary: "bg-secondary-100 text-secondary-900",
-      primary: "bg-primary-100 text-primary-700",
-      neutral: "bg-surface-muted text-fg"
-    }.freeze
+    # =========================================================================
+    # 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, :light, :outline, :subtle, :ghost]
-    # @param color [:primary, :secondary, :success, :warning, :danger, :neutral]
+    # @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]
+    # @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 full_width [Boolean]
-    # @param disabled [Boolean]
     # @param type [String]
     # @return [ActiveSupport::SafeBuffer]
-    def odt_button(text = nil, variant: :filled, color: :primary, size: :md, radius: :full, href: nil, icon: nil, right_icon: nil, full_width: false, disabled: false, type: "button", **html_options, &block)
-      variant_key = variant.to_sym
-      color_key = color.to_sym
-      size_key = size.to_sym
-      radius_key = radius.to_s.to_sym
-
-      base_class = "inline-flex items-center justify-center font-medium transition-all duration-200 select-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none cursor-pointer"
-      
-      variant_map = BUTTON_VARIANTS[variant_key] || BUTTON_VARIANTS[:filled]
-      style_class = variant_map[color_key] || variant_map[:primary] || variant_map.values.first
-      size_class = BUTTON_SIZES[size_key] || BUTTON_SIZES[:md]
-      radius_class = RADIUS_CLASSES[radius_key] || RADIUS_CLASSES[:full]
-      width_class = full_width ? "w-full" : ""
-
-      classes = [base_class, style_class, size_class, radius_class, width_class, html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
-      opts[:disabled] = true if disabled
+    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("_", "-")
+      size_key = size.to_s.tr("_", "-")
+
+      classes = [
+        "odt-btn",
+        "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
+      classes << "odt-btn--icon-only" if icon_only
+      classes << "odt-btn--loading" if loading
+      classes << "odt-btn--disabled" if disabled
+      classes << html_options.delete(:class)
+
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+      opts[:disabled] = true if disabled || loading
+      opts[:aria] = (opts[:aria] || {}).merge(busy: true) if loading
 
       parts = []
-      parts << (icon.start_with?("<") ? icon.html_safe : tag.i(class: icon)) if icon.present?
-      parts << (block_given? ? capture(&block) : text)
-      parts << (right_icon.start_with?("<") ? right_icon.html_safe : tag.i(class: right_icon)) if right_icon.present?
+      if loading
+        parts << tag.span(class: "odt-spinner", aria: { hidden: "true" })
+      elsif icon.present?
+        parts << render_icon_element(icon)
+      end
+
+      button_text = block_given? ? capture(&block) : text
+      if button_text.present?
+        parts << (icon_only ? button_text : tag.span(button_text))
+      end
+
+      if right_icon.present? && !loading
+        parts << render_icon_element(right_icon)
+      end
+
       inner_content = safe_join(parts.compact, " ")
 
       if href.present?
@@ -160,179 +74,652 @@ module OdtUi
       end
     end
 
+    # Renders an ODT Badge component.
+    #
     # @param text [String, nil]
-    # @param variant [:subtle, :filled, :outline]
+    # @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]
+    # @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: :neutral, size: :sm, radius: :full, dot: false, icon: nil, **html_options, &block)
-      variant_key = variant.to_sym
-      color_key = color.to_sym
-      size_key = size.to_sym
-      radius_key = radius.to_s.to_sym
+    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("_", "-")
+      size_key = size.to_s.tr("_", "-")
 
-      base_class = "inline-flex items-center gap-1.5 leading-none transition-colors select-none font-medium shrink-0"
-      variant_map = BADGE_VARIANTS[variant_key] || BADGE_VARIANTS[:subtle]
-      style_class = variant_map[color_key] || variant_map[:neutral] || variant_map.values.first
-      size_class = BADGE_SIZES[size_key] || BADGE_SIZES[:sm]
-      radius_class = RADIUS_CLASSES[radius_key] || RADIUS_CLASSES[:full]
+      classes = [
+        "odt-badge",
+        "odt-badge--#{variant_key}-#{color_key}",
+        "odt-badge--#{size_key}"
+      ]
 
-      classes = [base_class, style_class, size_class, radius_class, html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
+      classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      classes << html_options.delete(:class)
+
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
 
       parts = []
-      parts << tag.span(class: "w-1.5 h-1.5 rounded-full bg-current opacity-80 shrink-0") if dot
-      parts << (icon.start_with?("<") ? icon.html_safe : tag.i(class: icon)) if icon.present?
-      parts << (block_given? ? capture(&block) : text)
-      inner_content = safe_join(parts.compact, " ")
+      parts << tag.span(class: "odt-badge__dot", aria: { hidden: "true" }) if dot
+      parts << render_icon_element(icon) if icon.present?
 
+      badge_text = block_given? ? capture(&block) : text
+      parts << tag.span(badge_text) if badge_text.present?
+
+      inner_content = safe_join(parts.compact, " ")
       tag.span(inner_content, **opts)
     end
 
+    # Renders an ODT Card container.
+    #
     # @param title [String, nil]
     # @param subtitle [String, nil]
-    # @param variant [:elevated, :frosted, :subtle, :muted, :outlined]
-    # @param radius [:none, :xs, :sm, :md, :lg, :xl, :"2xl", :"3xl", :"4xl", :full]
-    # @param border [Boolean, Symbol, String]
-    # @param hover [Boolean]
+    # @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: :frosted, radius: :"3xl", border: false, hover: true, **html_options, &block)
-      variant_class = CARD_VARIANTS[variant.to_sym] || CARD_VARIANTS[:frosted]
-      radius_class = RADIUS_CLASSES[radius.to_s.to_sym] || RADIUS_CLASSES[:"3xl"]
-      hover_class = hover ? "hover:shadow-primary-200/50 hover:-translate-y-0.5 transition-all duration-300" : ""
-      border_class = if border == true
-        "border border-line"
-      elsif border.is_a?(Symbol) || border.is_a?(String)
-        "border border-#{border}"
-      else
-        "border-0"
+    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("_", "-")
+
+      classes = ["odt-card", "odt-card--#{variant_key}"]
+
+      if background.present?
+        bg_key = background.to_s.tr("_", "-")
+        classes << "odt-card--bg-#{bg_key}"
       end
 
-      classes = ["p-6 flex flex-col h-full", variant_class, border_class, radius_class, hover_class, html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
+      if border.present?
+        if border == true
+          classes << "odt-card--border-base"
+        else
+          classes << "odt-card--border-#{border.to_s.tr('_', '-')}"
+        end
+      end
+
+      classes << "odt-shadow-#{shadow.to_s.tr('_', '-')}" if shadow.present?
+      classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      classes << "odt-card--padding-#{padding.to_s.tr('_', '-')}" if padding.present?
+      classes << "odt-card--hoverable" if hoverable || hover
+      classes << html_options.delete(:class)
 
-      header = if title.present?
-        tag.div(class: "mb-3") do
-          concat tag.h3(title, class: "text-xl font-bold text-fg-strong leading-tight")
-          concat tag.p(subtitle, class: "text-sm text-fg-muted mt-1") if subtitle.present?
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+
+      header = if title.present? || subtitle.present?
+        tag.div(class: "odt-card__header") do
+          concat tag.h3(title, class: "odt-card__title") if title.present?
+          concat tag.p(subtitle, class: "odt-card__subtitle") if subtitle.present?
         end
       end
-      content = block_given? ? capture(&block) : nil
-      inner_content = safe_join([header, content].compact)
 
-      tag.div(inner_content, **opts)
+      body_content = block_given? ? capture(&block) : nil
+      inner_content = safe_join([header, body_content].compact)
+
+      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)
-      styles = {
-        success: { bg: "bg-surface-success border-green-200 text-fg-success", icon: "fa-solid fa-circle-check" },
-        warning: { bg: "bg-surface-warning border-amber-200 text-fg-warning", icon: "fa-solid fa-triangle-exclamation" },
-        danger: { bg: "bg-surface-danger border-red-200 text-fg-danger", icon: "fa-solid fa-circle-xmark" },
-        info: { bg: "bg-surface-info border-blue-200 text-fg-info", icon: "fa-solid fa-circle-info" }
+      variant_key = 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"
       }
 
-      config = styles[variant.to_sym] || styles[:info]
-      icon_name = icon || config[:icon]
+      icon_name = icon || default_icons[variant_key] || default_icons[:info]
 
-      classes = ["p-4 rounded-2xl border flex items-center gap-3 text-sm shadow-sm", config[:bg], html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
+      classes = [
+        "odt-alert",
+        "odt-alert--#{variant_key}",
+        html_options.delete(:class)
+      ]
+
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "), role: "alert")
 
       parts = []
-      parts << tag.i(class: "#{icon_name} text-base shrink-0") if icon_name.present?
-      parts << (block_given? ? capture(&block) : tag.p(message, class: "font-medium"))
-      inner_content = safe_join(parts.compact)
+      parts << tag.span(render_icon_element(icon_name), class: "odt-alert__icon") if icon_name.present?
 
+      content = block_given? ? capture(&block) : message
+      parts << tag.div(content, class: "odt-alert__content") if content.present?
+
+      inner_content = safe_join(parts.compact)
       tag.div(inner_content, **opts)
     end
 
+    # Renders an ODT Heading element.
+    #
     # @param text [String, nil]
-    # @param as [:h1, :h2, :h3, :h4, :h5]
+    # @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, **html_options, &block)
+    def odt_heading(text = nil, as: :h2, size: nil, weight: nil, color: :strong, truncate: false, **html_options, &block)
       tag_name = as.to_sym
-      heading_styles = {
-        h1: "text-3xl font-bold text-fg-strong tracking-tight",
-        h2: "text-2xl font-bold text-fg-strong tracking-tight",
-        h3: "text-xl font-bold text-fg-strong leading-tight",
-        h4: "text-lg font-semibold text-fg-strong",
-        h5: "text-base font-semibold text-fg-strong"
+      default_sizes = {
+        h1: "4xl",
+        h2: "3xl",
+        h3: "2xl",
+        h4: "xl",
+        h5: "lg",
+        h6: "lg"
       }
 
-      style_class = heading_styles[tag_name] || heading_styles[:h2]
-      classes = [style_class, html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
+      resolved_size = (size || default_sizes[tag_name] || "2xl").to_s.tr("_", "-")
+      resolved_weight = (weight || "bold").to_s.tr("_", "-")
+      resolved_color = (color || "strong").to_s.tr("_", "-")
+
+      classes = [
+        "odt-heading",
+        "odt-heading--#{resolved_size}",
+        "odt-weight-#{resolved_weight}",
+        "odt-color-#{resolved_color}"
+      ]
+
+      classes << "odt-truncate" if truncate
+      classes << html_options.delete(:class)
+
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
       inner_content = block_given? ? capture(&block) : text
 
       tag.public_send(tag_name, inner_content, **opts)
     end
 
+    # Renders styled typography body text.
+    #
     # @param text [String, nil]
-    # @param color [:default, :strong, :muted, :subtle, :primary]
-    # @param size [:xs, :sm, :base, :lg]
+    # @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, color: :default, size: :base, **html_options, &block)
-      color_styles = {
-        default: "text-fg",
-        strong: "text-fg-strong font-medium",
-        muted: "text-fg-muted",
-        subtle: "text-fg-subtle",
-        primary: "text-primary-600 font-medium"
-      }
+    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("_", "-")
+      resolved_color = color.to_s.tr("_", "-")
 
-      size_styles = {
-        xs: "text-xs",
-        sm: "text-sm",
-        base: "text-base",
-        lg: "text-lg"
-      }
+      classes = [
+        "odt-text",
+        "odt-text--#{resolved_size}",
+        "odt-color-#{resolved_color}"
+      ]
 
-      c_class = color_styles[color.to_sym] || color_styles[:default]
-      s_class = size_styles[size.to_sym] || size_styles[:base]
+      classes << "odt-weight-#{weight.to_s.tr('_', '-')}" if weight.present?
+      classes << "odt-truncate" if truncate
+      classes << html_options.delete(:class)
 
-      classes = [c_class, s_class, html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
       inner_content = block_given? ? capture(&block) : text
 
-      tag.p(inner_content, **opts)
+      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]
+    # @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: :sm, color: :secondary, icon: "fa-solid fa-user", **html_options)
-      s_class = AVATAR_SIZES[size.to_sym] || AVATAR_SIZES[:sm]
-      c_class = AVATAR_COLORS[color.to_sym] || AVATAR_COLORS[:secondary]
-      classes = ["aspect-square rounded-full flex items-center justify-center font-bold uppercase select-none shrink-0 overflow-hidden ring-2 ring-white shadow-xs", s_class, c_class, html_options[:class]].compact.join(" ")
-      opts = html_options.merge(class: classes)
-
-      initials = if name.present?
-        parts = name.strip.split(/\s+/)
-        if parts.length == 1
-          parts[0].slice(0, 2).upcase
-        else
-          "#{parts.first[0]}#{parts.last[0]}".upcase
-        end
-      end
+    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("_", "-")
+
+      classes = [
+        "odt-avatar",
+        "odt-avatar--#{size_key}",
+        "odt-avatar--#{color_key}",
+        html_options.delete(:class)
+      ]
+
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+
+      initials = fallback.presence || compute_avatar_initials(name)
 
       inner_content = if src.present?
-        image_tag(src, alt: name || "Avatar", class: "w-full h-full object-cover")
+        image_tag(src, alt: name || "Avatar", class: "odt-avatar__image")
       elsif initials.present?
-        tag.span(initials, class: "leading-none")
+        tag.span(initials, class: "odt-avatar__fallback")
       else
-        tag.i(class: icon)
+        tag.span(render_icon_element(icon), class: "odt-avatar__fallback")
       end
 
       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("_", "-")
+      resolved_helper = helper.presence || helper_text.presence
+      has_error = error.present?
+      has_success = success.present? && !has_error
+
+      input_classes = [
+        "odt-input",
+        "odt-input--#{variant_key}",
+        "odt-input--#{size_key}"
+      ]
+
+      input_classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      input_classes << "odt-input--error" if has_error
+      input_classes << "odt-input--success" if has_success
+      input_classes << "odt-input--has-left-icon" if left_icon.present? || prefix.present?
+      input_classes << "odt-input--has-right-icon" if right_icon.present? || suffix.present?
+      input_classes << "odt-input--has-addon-before" if addon_before.present?
+      input_classes << "odt-input--has-addon-after" if addon_after.present?
+      input_classes << html_options.delete(:class)
+
+      input_opts = html_options.merge(
+        type: type,
+        class: input_classes.compact.reject(&:blank?).join(" "),
+        disabled: disabled
+      )
+      input_opts[:placeholder] = placeholder if placeholder.present?
+
+      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?
+
+        input_field = tag.div(class: "odt-input-wrapper") do
+          wrap_parts = []
+          if left_icon.present?
+            wrap_parts << tag.span(render_icon_element(left_icon), class: "odt-input__left-icon")
+          elsif prefix.present?
+            wrap_parts << tag.span(prefix, class: "odt-input__left-icon")
+          end
+
+          wrap_parts << tag.input(**input_opts)
+
+          if right_icon.present?
+            wrap_parts << tag.span(render_icon_element(right_icon), class: "odt-input__right-icon")
+          elsif suffix.present?
+            wrap_parts << tag.span(suffix, class: "odt-input__right-icon")
+          end
+
+          safe_join(wrap_parts)
+        end
+
+        if addon_before.present? || addon_after.present?
+          parts << tag.div(class: "odt-input__addon-group") do
+            addon_parts = []
+            addon_parts << tag.span(addon_before, class: "odt-input__addon-before") if addon_before.present?
+            addon_parts << input_field
+            addon_parts << tag.span(addon_after, class: "odt-input__addon-after") if addon_after.present?
+            safe_join(addon_parts)
+          end
+        else
+          parts << input_field
+        end
+
+        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 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("_", "-")
+      resize_key = resize.to_s.tr("_", "-")
+      resolved_helper = helper.presence || helper_text.presence
+      has_error = error.present?
+      has_success = success.present? && !has_error
+
+      classes = [
+        "odt-textarea",
+        "odt-textarea--#{variant_key}",
+        "odt-textarea--#{size_key}",
+        "odt-textarea--resize-#{resize_key}"
+      ]
+
+      classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      classes << "odt-textarea--error" if has_error
+      classes << "odt-textarea--success" if has_success
+      classes << html_options.delete(:class)
+
+      opts = html_options.merge(
+        class: classes.compact.reject(&:blank?).join(" "),
+        rows: rows,
+        disabled: disabled
+      )
+
+      content = block_given? ? capture(&block) : html_options.delete(:value)
+
+      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.textarea(content, **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 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
+      )
+
+      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("_", "-")
+      has_error = error.present?
+
+      classes = [
+        "odt-checkbox",
+        "odt-checkbox--#{color_key}",
+        "odt-checkbox--#{size_key}"
+      ]
+
+      classes << "odt-radius-#{radius.to_s.tr('_', '-')}" if radius.present?
+      classes << "odt-checkbox--error" if has_error
+      classes << html_options.delete(:class)
+
+      opts = html_options.merge(
+        type: "checkbox",
+        class: classes.compact.reject(&:blank?).join(" "),
+        disabled: disabled
+      )
+      opts[:checked] = "checked" if checked
+
+      tag.div(class: "odt-checkbox-wrapper") do
+        parts = []
+        parts << tag.label(class: "odt-checkbox-container") do
+          label_parts = [tag.input(**opts)]
+
+          if label.present? || description.present?
+            label_parts << tag.div(class: "odt-checkbox__label-content") do
+              d_parts = []
+              d_parts << tag.span(label, class: "odt-checkbox__label") if label.present?
+              d_parts << tag.span(description, class: "odt-checkbox__description") if description.present?
+              safe_join(d_parts)
+            end
+          end
+
+          safe_join(label_parts)
+        end
+
+        parts << tag.p(error, class: "odt-error-text", role: "alert") if has_error
+        safe_join(parts)
+      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("_", "-")
+      has_error = error.present?
+
+      classes = [
+        "odt-radio",
+        "odt-radio--#{color_key}",
+        "odt-radio--#{size_key}",
+        html_options.delete(:class)
+      ]
+
+      opts = html_options.merge(
+        type: "radio",
+        class: classes.compact.reject(&:blank?).join(" "),
+        disabled: disabled
+      )
+      opts[:checked] = "checked" if checked
+
+      tag.div(class: "odt-radio-wrapper") do
+        parts = []
+        parts << tag.label(class: "odt-radio-container") do
+          label_parts = [tag.input(**opts)]
+
+          if label.present? || description.present?
+            label_parts << tag.div(class: "odt-radio__label-content") do
+              d_parts = []
+              d_parts << tag.span(label, class: "odt-radio__label") if label.present?
+              d_parts << tag.span(description, class: "odt-radio__description") if description.present?
+              safe_join(d_parts)
+            end
+          end
+
+          safe_join(label_parts)
+        end
+
+        parts << tag.p(error, class: "odt-error-text", role: "alert") if has_error
+        safe_join(parts)
+      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?
+      has_success = success.present? && !has_error
+
+      classes = ["odt-form-group", html_options.delete(:class)]
+      opts = html_options.merge(class: classes.compact.reject(&:blank?).join(" "))
+
+      tag.div(**opts) do
+        parts = []
+        if label.present?
+          label_classes = ["odt-label"]
+          label_classes << "odt-label--required" if required
+          parts << tag.label(label, class: label_classes.join(" "))
+        end
+
+        parts << capture(&block) if block_given?
+
+        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
+
+    private
+
+    # Normalizes button variant key with backwards compatibility
+    def normalize_button_variant(variant)
+      case variant.to_sym
+      when :light
+        "light"
+      when :outline, :outlined
+        "outline"
+      when :subtle
+        "subtle"
+      when :frosted
+        "frosted"
+      when :capsule
+        "capsule"
+      when :ghost
+        "ghost"
+      else
+        "filled"
+      end
+    end
+
+    # Computes initials from a full name (e.g., "John Doe" -> "JD")
+    def compute_avatar_initials(name)
+      return nil if name.blank?
+
+      parts = name.strip.split(/\s+/)
+      if parts.length == 1
+        parts[0].slice(0, 2).upcase
+      else
+        "#{parts.first[0]}#{parts.last[0]}".upcase
+      end
+    end
+
+    # Safely renders an icon (SVG or HTML class)
+    def render_icon_element(icon)
+      return nil if icon.blank?
+
+      if icon.start_with?("<")
+        icon.html_safe
+      else
+        tag.i(class: icon, aria: { hidden: "true" })
+      end
+    end
   end
 end