phlex-forms 0.1.0 → 0.2.0

data/lib/forms/plain/select.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # Bare native <select>. Reuses Forms::Select's prompt/choice rendering
+    # (arrays, pairs, hashes/optgroups, selected comparison). Also fills the
+    # :choices_select theme role, so it swallows searchable: — there is no
+    # choices.js in the plain theme.
+    class Select < Forms::Select
+      def initialize(*modifiers, searchable: false, **) # rubocop:disable Lint/UnusedMethodArgument
+        super(*modifiers, **)
+      end
+
+      def view_template
+        select(**unstyled_attributes) do
+          render_prompt(self) if @prompt || @include_blank
+          render_choices(self)
+        end
+      end
+    end
+  end
+end

data/lib/forms/plain/submit.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # Bare <button type="submit">, reusing Forms::Submit's Create/Update label
+    # derivation.
+    class Submit < Forms::Submit
+      def view_template(&block)
+        attrs = { type: "submit", **@attributes }
+        attrs[:disabled] = true if @disabled
+        button(**attrs) { block ? yield : button_text }
+      end
+    end
+  end
+end

data/lib/forms/plain/textarea.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # Bare <textarea>. Also fills the :rich_textarea theme role (documented
+    # degradation — rich text needs an editor integration the plain theme
+    # doesn't ship), so it swallows the rich-text-only value handling.
+    class Textarea < Forms::Textarea
+      def view_template
+        textarea(rows: @rows, **unstyled_attributes) { @value }
+      end
+    end
+  end
+end

data/lib/forms/plain/wrapped_input.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Forms
+  module Plain
+    # The icon/text-inside-the-field pattern without daisyui: a bare <label>
+    # wrapping the leading block, the input, and any trailing content.
+    class WrappedInput < Forms::WrappedInput
+      def view_template(&leading)
+        label do
+          leading&.call
+          input(**plain_input_attributes)
+          render_trailing
+        end
+      end
+
+      private
+
+      def plain_input_attributes
+        attrs = {
+          type: @type,
+          name: @name,
+          id: @id,
+          value: @value.to_s,
+          placeholder: @placeholder,
+          **@attributes.except(:error, :value, :class)
+        }
+        attrs[:disabled] = true if @disabled
+        attrs[:required] = true if @required
+        attrs[:"aria-invalid"] = true if @error
+        attrs.compact
+      end
+    end
+  end
+end

data/lib/forms/row.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Forms
+  # Side-by-side fields in a responsive grid: stacked on mobile, `columns`
+  # across from the sm breakpoint. The class strings are literals (not
+  # interpolated) so host Tailwind scanners pick them up.
+  #
+  #   f.row { f.field :first_name; f.field :last_name }
+  #   f.row(columns: 3) { ... }
+  class Row < Phlex::HTML
+    COLUMN_CLASSES = {
+      2 => "sm:grid-cols-2",
+      3 => "sm:grid-cols-3",
+      4 => "sm:grid-cols-4"
+    }.freeze
+
+    def initialize(columns: 2, **options)
+      @columns = columns
+      @options = options
+      super()
+    end
+
+    def view_template(&)
+      div(class: row_classes, **@options.except(:class), &)
+    end
+
+    private
+
+    def row_classes
+      base = ["grid grid-cols-1 gap-4", COLUMN_CLASSES[@columns]].compact.join(" ")
+      PhlexForms::ClassMerge.merge(base, @options[:class])
+    end
+  end
+end

data/lib/phlex_forms/builder.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
 module PhlexForms
-  # The shared form-builder surface, included by Forms::Form, Forms::Field, and
-  # Forms::FieldsForBuilder so the three no longer copy-paste the API three times.
+  # The shared form-builder surface, included by Forms::Form and
+  # Forms::FieldsForBuilder so the two no longer copy-paste the API.
   #
   # Two layers:
   #
   #   * The Control-first primary verb `field` — renders label + input +
   #     error/hint in one call, inferring the input type and the `required` flag
-  #     from the model.
+  #     from the model (structure, column types, validators — see
+  #     PhlexForms::Inference) with the attribute-name map as tiebreaker.
   #
   #   * Lower-level escape hatches (`Input`, `Select`, `Textarea`, `Checkbox`,
   #     `Toggle`, `FileInput`, `Hidden`, `Label`, `Control`, `submit`) with the
@@ -48,9 +49,10 @@ module PhlexForms
     # Render a complete field: label + control-wrapped input + error/hint.
     #
     #   f.field :email                          # type=email, label auto, required inferred
-    #   f.field :role, as: :select, choices: roles
-    #   f.field :bio, as: :textarea, rows: 6
-    #   f.field :accept, as: :toggle
+    #   f.field :notify                         # boolean column -> toggle
+    #   f.field :role                           # AR enum -> select, humanized
+    #   f.field :country                        # belongs_to -> select over the association
+    #   f.field :bio, as: :textarea, rows: 6    # explicit as: always wins
     #   f.field :name, :primary, label: "Full name", hint: "As on your ID"
     #
     # Options:
@@ -58,22 +60,48 @@ module PhlexForms
     #             pass false to omit the label)
     #   hint:     help text shown when there is no error
     #   as:       override the rendered control (:select, :textarea, :toggle,
-    #             :checkbox, :file, :hidden, and text-like types)
+    #             :checkbox, :file, :hidden, :rich_textarea, and text-like types)
     #   required: force the required flag (otherwise inferred from validations)
-    #   choices:  choices for :select
+    #   choices:  choices for :select (implies as: :select when given)
     # Remaining positional modifiers/keywords pass through to the inner input.
     def field(name, *modifiers, label: nil, hint: nil, as: nil, required: nil,
               choices: nil, **options)
-      fo = field_object(name)
-      req = required.nil? ? fo.required? : required
-      label_text = label == false ? nil : (label || fo.field_label)
+      modifiers = default_field_variants + modifiers
+      inferred = PhlexForms::Inference.resolve(model:, name:, as:, modifiers:, choices:)
+      # error_name: for a rewritten field (:country -> :country_id) errors still
+      # live on the association name.
+      fo = field_object(inferred.name, error_name: name)
+      req = required.nil? ? (fo.required? || inferred.required == true) : required
+      label_text = label == false ? nil : (label || inferred.label || fo.field_label)
+      options = inferred.attributes.merge(options)
+      if inferred.multiple
+        options[:multiple] = true unless options.key?(:multiple)
+        options[:name] ||= "#{fo.field_name}[]"
+      end
       options = fo.apply_validations(options)
+      choices ||= materialize_choices(inferred.choices)
 
       render fo.control(label: label_text, hint:, required: req) do
-        render_field_input(fo, name, as, modifiers, choices:, required: req, **options)
+        render_field_input(fo, inferred.name, inferred.as, modifiers, choices:, required: req, **options)
       end
     end
 
+    # ------------------------------------------------------------------
+    # Layout helpers
+    # ------------------------------------------------------------------
+
+    # Side-by-side fields in a responsive grid (stacked on mobile).
+    #   f.row { f.field :first_name; f.field :last_name }
+    def row(columns: 2, **, &)
+      render theme[:row].new(columns:, **), &
+    end
+
+    # A fieldset with a legend for sectioning related fields.
+    #   f.group(legend: "Address") { f.field :street }
+    def group(legend: nil, **, &)
+      render theme[:group].new(legend:, **), &
+    end
+
     # ------------------------------------------------------------------
     # Escape-hatch component API (stable signatures)
     # ------------------------------------------------------------------
@@ -133,18 +161,23 @@ module PhlexForms
     def render_field_input(fo, name, as, modifiers, choices:, required:, **)
       kind = as || resolve_input_type(name, modifiers)
       case kind
-      when :select   then render fo.choices_select(choices, *modifiers, required:, **)
-      when :textarea then render fo.textarea(*modifiers, required:, **)
-      when :toggle   then render fo.toggle(*modifiers, required:, **)
-      when :checkbox then render fo.checkbox(*modifiers, required:, **)
-      when :file     then render fo.file(*modifiers, required:, **)
-      when :hidden   then render fo.hidden(**)
+      when :select        then render fo.choices_select(choices, *modifiers, required:, **)
+      when :textarea      then render fo.textarea(*modifiers, required:, **)
+      when :toggle        then render fo.toggle(*modifiers, required:, **)
+      when :checkbox      then render fo.checkbox(*modifiers, required:, **)
+      when :file          then render fo.file(*modifiers, required:, **)
+      when :hidden        then render fo.hidden(**)
+      when :rich_textarea then render fo.rich_textarea(*modifiers, **)
       else
         type = kind == :datetime ? :"datetime-local" : kind
         render fo.input(*(modifiers - INPUT_TYPE_MODIFIERS), type:, required:, **)
       end
     end
 
+    def materialize_choices(choices)
+      choices.respond_to?(:call) ? choices.call : choices
+    end
+
     def resolve_input_type(name, modifiers)
       explicit = modifiers.find { |m| INPUT_TYPE_MODIFIERS.include?(m) }
       explicit || INPUT_TYPE_INFERENCE[name.to_sym] || :text

data/lib/phlex_forms/configuration.rb

@@ -36,6 +36,34 @@ module PhlexForms
 
     attr_writer :icon_renderer
 
+    # Kill-switch for model-driven inference (columns/enums/associations/
+    # validator attributes). Defaults to on; set false to restore pure
+    # attribute-name inference for `field`.
+    attr_writer :infer_from_model
+
+    # Global daisyui variants prepended to every `field`'s inner input, e.g.
+    # `c.field_variants = [:primary]`. Form-level `field_variants:` and
+    # call-site modifiers stack after (later wins).
+    attr_writer :field_variants
+
+    def field_variants
+      @field_variants ||= []
+    end
+
+    # The default theme: :daisy, :plain, or a PhlexForms::Theme instance.
+    # Defaults to daisy when the daisyui gem is loaded, plain otherwise.
+    attr_writer :theme
+
+    def theme
+      @theme ||= defined?(DaisyUI) ? Theme.daisy : Theme.plain
+    end
+
+    def infer_from_model
+      return @infer_from_model if defined?(@infer_from_model) && !@infer_from_model.nil?
+
+      true
+    end
+
     def icon_renderer
       @icon_renderer ||= ->(name, **opts) { InlineIcons.render(name, **opts) }
     end

data/lib/phlex_forms/delegated_field.rb

@@ -47,5 +47,22 @@ module PhlexForms
 
       ["w-full", @attributes[:class]].compact.join(" ")
     end
+
+    # Unstyled variant of binding_attributes for the Plain theme: caller classes
+    # pass through verbatim, no width class, and an invalid field is flagged via
+    # aria-invalid instead of an error variant class.
+    def unstyled_attributes(**extra)
+      attrs = {
+        name: @name,
+        id: @id,
+        class: @attributes[:class],
+        **@attributes.except(:error, :value, :class),
+        **extra
+      }
+      attrs[:disabled] = true if @disabled
+      attrs[:required] = true if @required
+      attrs[:"aria-invalid"] = true if @error
+      attrs.compact
+    end
   end
 end

data/lib/phlex_forms/engine.rb

@@ -31,5 +31,12 @@ module PhlexForms
       locales = Dir[root.join("config/locales/*.yml")].map(&:to_s)
       app.config.i18n.load_path.unshift(*locales)
     end
+
+    # The raw-hash param type Forms::Live's :validate action schema declares.
+    # Registered from an initializer because phlex-reactive freezes its
+    # param-type registry after boot.
+    initializer "phlex_forms.live_param_type" do
+      Forms::Live.register_param_type! if defined?(Phlex::Reactive)
+    end
   end
 end

data/lib/phlex_forms/inference.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module PhlexForms
+  # Model-driven input inference for Builder#field. Pure introspection: every
+  # model touch sits behind respond_to? guards and a StandardError rescue (the
+  # same posture as Forms::Field#required?), so plain objects, Structs, and
+  # POROs fall through to the attribute-name map exactly as before. No
+  # ActiveRecord dependency.
+  #
+  # Precedence (first hit wins):
+  #   1. explicit as:                      (caller always wins)
+  #   2. positional type modifier          (f.field :price, :number)
+  #   3. explicit choices:                 -> :select
+  #   4. model structure: rich text, attachment, enum, belongs_to
+  #   5. non-string column type            (COLUMN_TYPE_MAP)
+  #   6. attribute-name map                (Builder::INPUT_TYPE_INFERENCE)
+  #   7. :text
+  #
+  # Validator-derived attributes (maxlength/min/max) merge orthogonally and
+  # always lose to caller-passed options. Steps 4-5 and the validator attrs are
+  # gated by `PhlexForms.config.infer_from_model` (default on).
+  module Inference
+    Result = Data.define(:as, :name, :label, :choices, :attributes, :multiple, :required) do
+      def self.blank(as:, name:)
+        new(as:, name:, label: nil, choices: nil, attributes: {}, multiple: false, required: nil)
+      end
+    end
+
+    # Option-text methods tried in order when building association choices.
+    LABEL_METHODS = %i[name title label to_s].freeze
+
+    # Column type -> control kind, for non-string columns only (the name map
+    # disambiguates strings; the column type is ground truth for other shapes).
+    COLUMN_TYPE_MAP = {
+      boolean: :toggle,
+      text: :textarea,
+      date: :date,
+      datetime: :datetime,
+      timestamptz: :datetime,
+      time: :time,
+      integer: :number,
+      decimal: :number,
+      float: :number
+    }.freeze
+
+    # Kinds that accept a maxlength attribute.
+    TEXT_LIKE = %i[text email password tel url search textarea].freeze
+
+    module_function
+
+    def resolve(model:, name:, as: nil, modifiers: [], choices: nil)
+      result = base_result(model:, name:, as:, modifiers:, choices:)
+      return result unless infer_from_model?
+
+      validator_attrs = validator_attributes(model, result.name, result.as)
+      return result if validator_attrs.empty?
+
+      result.with(attributes: validator_attrs.merge(result.attributes))
+    end
+
+    def base_result(model:, name:, as:, modifiers:, choices:)
+      return Result.blank(as:, name:) if as
+
+      if (explicit = modifiers.find { |m| Builder::INPUT_TYPE_MODIFIERS.include?(m) })
+        return Result.blank(as: explicit, name:)
+      end
+      return Result.blank(as: :select, name:) if choices
+      return name_map_result(name) unless infer_from_model?
+
+      structural(model, name) || from_column(model, name) || name_map_result(name)
+    end
+
+    def infer_from_model?
+      PhlexForms.config.infer_from_model
+    end
+
+    def name_map_result(name)
+      Result.blank(as: Builder::INPUT_TYPE_INFERENCE[name.to_sym] || :text, name:)
+    end
+
+    def structural(model, name)
+      return nil unless model
+
+      rich_text(model, name) || attachment(model, name) ||
+        enum(model, name) || association(model, name)
+    rescue StandardError
+      nil
+    end
+
+    # ActionText defines a has_one :rich_text_<name> association.
+    def rich_text(model, name)
+      return nil unless reflect(model, :"rich_text_#{name}")
+
+      Result.blank(as: :rich_textarea, name:)
+    end
+
+    def attachment(model, name)
+      klass = model.class
+      return nil unless klass.respond_to?(:reflect_on_attachment)
+
+      reflection = klass.reflect_on_attachment(name)
+      return nil unless reflection
+
+      Result.blank(as: :file, name:).with(multiple: reflection.macro == :has_many_attached)
+    end
+
+    def enum(model, name)
+      klass = model.class
+      return nil unless klass.respond_to?(:defined_enums) && klass.defined_enums.key?(name.to_s)
+
+      pairs = klass.defined_enums[name.to_s].keys.map { |key| [key.humanize, key] }
+      Result.blank(as: :select, name:).with(choices: pairs)
+    end
+
+    # A non-polymorphic belongs_to, matched by the association name (:country)
+    # or its foreign key (:country_id). The field name is rewritten to the
+    # foreign key; the label and required flag come from the association.
+    def association(model, name)
+      assoc_name = name.to_s.delete_suffix("_id").to_sym
+      reflection = reflect(model, name) || reflect(model, assoc_name)
+      return nil unless reflection && reflection.macro == :belongs_to && !reflection.polymorphic?
+
+      Result.blank(as: :select, name: reflection.foreign_key.to_sym).with(
+        label: association_label(model, reflection),
+        choices: -> { association_choices(reflection.klass) }, # lazy: only called without a choices: override
+        required: presence_validated?(model, reflection.name)
+      )
+    end
+
+    def from_column(model, name)
+      type = column_type(model, name)
+      kind = COLUMN_TYPE_MAP[type&.type]
+      return nil unless kind
+
+      attrs = {}
+      if kind == :number && (step = step_for(type))
+        attrs[:step] = step
+      end
+      Result.blank(as: kind, name:).with(attributes: attrs)
+    rescue StandardError
+      nil
+    end
+
+    def column_type(model, name)
+      return nil unless model
+
+      klass = model.class
+      if klass.respond_to?(:type_for_attribute)
+        klass.type_for_attribute(name.to_s)
+      elsif klass.respond_to?(:attribute_types)
+        klass.attribute_types[name.to_s]
+      end
+    end
+
+    def step_for(type)
+      case type.type
+      when :integer then 1
+      when :decimal, :float
+        scale = type.respond_to?(:scale) ? type.scale : nil
+        scale ? (10**-scale).to_f : "any"
+      end
+    end
+
+    def association_label(model, reflection)
+      klass = model.class
+      return nil unless klass.respond_to?(:human_attribute_name)
+
+      klass.human_attribute_name(reflection.name)
+    end
+
+    def association_choices(klass)
+      label_method = nil
+      klass.all.map do |record|
+        label_method ||= LABEL_METHODS.find { |m| record.respond_to?(m) }
+        [record.public_send(label_method), record.id]
+      end
+    end
+
+    def presence_validated?(model, attr)
+      klass = model.class
+      return false unless klass.respond_to?(:validators_on)
+
+      klass.validators_on(attr).any? do |v|
+        v.is_a?(ActiveModel::Validations::PresenceValidator) && !conditional?(v)
+      end
+    end
+
+    # Length maximum -> maxlength (text-like kinds); numericality bounds ->
+    # min/max (number kind only; exclusive bounds map +/-1 only for
+    # only_integer, otherwise skipped).
+    def validator_attributes(model, name, kind)
+      return {} unless model.respond_to?(:class) && model.class.respond_to?(:validators_on)
+
+      attrs = {}
+      model.class.validators_on(name).each do |validator|
+        next if conditional?(validator)
+
+        case validator
+        when ActiveModel::Validations::LengthValidator
+          max = validator.options[:maximum]
+          attrs[:maxlength] = max if max && TEXT_LIKE.include?(kind)
+        when ActiveModel::Validations::NumericalityValidator
+          attrs.merge!(numericality_attributes(validator.options)) if kind == :number
+        end
+      end
+      attrs
+    rescue StandardError
+      {}
+    end
+
+    def numericality_attributes(options)
+      attrs = {}
+      integer = options[:only_integer]
+      if (min = options[:greater_than_or_equal_to])
+        attrs[:min] = min
+      elsif integer && (gt = options[:greater_than])
+        attrs[:min] = gt + 1
+      end
+      if (max = options[:less_than_or_equal_to])
+        attrs[:max] = max
+      elsif integer && (lt = options[:less_than])
+        attrs[:max] = lt - 1
+      end
+      attrs
+    end
+
+    def reflect(model, name)
+      klass = model.class
+      return nil unless klass.respond_to?(:reflect_on_association)
+
+      klass.reflect_on_association(name)
+    end
+
+    def conditional?(validator)
+      validator.options.key?(:if) || validator.options.key?(:unless) || validator.options.key?(:on)
+    end
+  end
+end

data/lib/phlex_forms/theme.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PhlexForms
+  # A theme maps component roles (:input, :select, :control, ...) to component
+  # classes. The binding contract — the leaf initializer signatures
+  # (*modifiers, name:, id:, value:, error:, required:, ...) — is the stable
+  # interface, so the same form class renders under any theme.
+  #
+  # Built-ins:
+  #   Theme.daisy — the DaisyUI-delegating Forms::* leaves (default when the
+  #                 daisyui gem is loaded)
+  #   Theme.plain — bare semantic HTML (Forms::Plain::*): variants accepted and
+  #                 ignored, zero styling classes, aria/data hooks only
+  #
+  # Select per form (`Form(model:, theme: :plain)`), per class
+  # (`form_options theme: :plain`), or globally
+  # (`PhlexForms.configure { |c| c.theme = :plain }`). Override single roles:
+  #
+  #   PhlexForms::Theme.resolve(:plain).with(input: MyInput)
+  class Theme
+    def initialize(components)
+      @components = components.freeze
+    end
+
+    def [](role)
+      @components.fetch(role) do
+        raise KeyError, "unknown theme role #{role.inspect} (roles: #{@components.keys.join(', ')})"
+      end
+    end
+
+    def with(**overrides)
+      self.class.new(@components.merge(overrides))
+    end
+
+    class << self
+      def resolve(value)
+        value = PhlexForms.config.theme if value.nil?
+        case value
+        when Theme then value
+        when :daisy then daisy
+        when :plain then plain
+        else
+          raise ArgumentError, "unknown theme #{value.inspect} (use :daisy, :plain, or a PhlexForms::Theme)"
+        end
+      end
+
+      def daisy
+        unless defined?(DaisyUI)
+          raise PhlexForms::FeatureUnavailable,
+            "the daisy theme requires the daisyui gem. Add `gem \"daisyui\"` to your " \
+            "Gemfile, or use the plain theme."
+        end
+
+        @daisy ||= new(
+          input: Forms::Input, select: Forms::Select, choices_select: Forms::ChoicesSelect,
+          textarea: Forms::Textarea, rich_textarea: Forms::RichTextarea,
+          checkbox: Forms::Checkbox, toggle: Forms::Toggle, radio: Forms::Radio,
+          file: Forms::FileInput, wrapped_input: Forms::WrappedInput,
+          control: Forms::FormControl, label: Forms::Label,
+          field_error: Forms::FieldError, field_hint: Forms::FieldHint,
+          submit: Forms::Submit, row: Forms::Row, group: Forms::Group
+        )
+      end
+
+      # choices_select degrades to the native plain select (no choices.js) and
+      # rich_textarea to a plain textarea; toggle renders as a checkbox.
+      def plain
+        @plain ||= new(
+          input: Forms::Plain::Input, select: Forms::Plain::Select, choices_select: Forms::Plain::Select,
+          textarea: Forms::Plain::Textarea, rich_textarea: Forms::Plain::Textarea,
+          checkbox: Forms::Plain::Checkbox, toggle: Forms::Plain::Checkbox, radio: Forms::Plain::Radio,
+          file: Forms::Plain::FileInput, wrapped_input: Forms::Plain::WrappedInput,
+          control: Forms::Plain::Control, label: Forms::Plain::Label,
+          field_error: Forms::Plain::FieldError, field_hint: Forms::Plain::FieldHint,
+          submit: Forms::Plain::Submit, row: Forms::Plain::Row, group: Forms::Plain::Group
+        )
+      end
+    end
+  end
+end

data/lib/phlex_forms/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PhlexForms
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/phlex_forms.rb

@@ -2,11 +2,29 @@
 
 require "date" # Phlex's attribute serializer references Date; ensure it's loaded.
 require "active_support/core_ext/object/blank" # blank?/present?/presence
+require "active_support/core_ext/enumerable" # exclude?
+require "active_support/core_ext/string" # underscore/pluralize/humanize (scope/url/label derivation)
 require "phlex"
-require "daisy_ui"
 require "glyphs"
 require "zeitwerk"
 
+begin
+  require "daisy_ui"
+rescue LoadError
+  # daisyui is a soft dependency: without it the Plain theme is the default.
+  # The daisy leaf components only reference DaisyUI inside view_template, so
+  # they load fine — they just must not be rendered (Theme.daisy raises).
+end
+
+begin
+  require "phlex/reactive"
+rescue LoadError
+  # phlex-reactive is a soft dependency: without it the `live` server-truth
+  # validation macro raises a FeatureUnavailable pointing here, and the live
+  # files are excluded from autoloading below (they include
+  # Phlex::Reactive::Component at class level, so they must not load).
+end
+
 require_relative "phlex_forms/version"
 
 # phlex-forms exposes its components under the `Forms::` namespace (Form, Input,
@@ -72,6 +90,13 @@ loader.ignore("#{__dir__}/phlex_forms/rubocop.rb") # cop entry point (RuboCop::
 # Rails), so it must not be autoloaded/eager-loaded by Zeitwerk.
 loader.ignore("#{__dir__}/phlex_forms/engine.rb")
 
+# The live-validation layer includes Phlex::Reactive::Component at class level,
+# so it can only load when the phlex-reactive soft dependency is present.
+unless defined?(Phlex::Reactive)
+  loader.ignore("#{__dir__}/forms/live.rb")
+  loader.ignore("#{__dir__}/forms/live")
+end
+
 loader.setup
 
 # Optional Rails integration (Stimulus controllers via importmap/assets, and