phlex-forms 0.1.0

data/lib/forms/field.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+# Per-field context: knows a field's name, its scope, the bound model, and the
+# error set. Builds the concrete leaf components (input/textarea/select/...) with
+# name/id/value/error wired in, and derives the label text and required flag.
+#
+# Not usually built directly — `Form#field(:name)` / the builder return one.
+module Forms
+  class Field
+    attr_reader :name, :model, :scope, :errors
+
+    def initialize(name:, model:, scope:, errors:, form:)
+      @name = name
+      @model = model
+      @scope = scope
+      @errors = errors
+      @form = form
+    end
+
+    # --- leaf component builders (return component instances to render) ---
+
+    def input(*modifiers, type: :text, **)
+      Forms::Input.new(*modifiers, type:, **field_attributes, **)
+    end
+
+    def textarea(*modifiers, **)
+      Forms::Textarea.new(*modifiers, **field_attributes, **)
+    end
+    alias text_area textarea
+
+    def rich_textarea(*modifiers, **)
+      Forms::RichTextarea.new(*modifiers, name: field_name, id: field_id, value: field_value, **)
+    end
+    alias rich_text_area rich_textarea
+
+    def hidden(**)
+      Forms::Input.new(type: :hidden, **field_attributes, **)
+    end
+
+    # daisyui v5 "icon/text inside the field" wrapper. The block renders the
+    # leading content (icon, prefix); the bare input is wired to this field.
+    def wrapped_input(*modifiers, type: :text, **, &)
+      Forms::WrappedInput.new(*modifiers, type:, **field_attributes.except(:error), error: invalid?, **, &)
+    end
+
+    def file(*modifiers, **)
+      Forms::FileInput.new(*modifiers, **field_attributes.except(:value), **)
+    end
+
+    def checkbox(*modifiers, **)
+      Forms::Checkbox.new(*modifiers, checked: field_value, **field_attributes.except(:value), **)
+    end
+    alias check_box checkbox
+
+    def toggle(*modifiers, **)
+      Forms::Toggle.new(*modifiers, checked: field_value, **field_attributes.except(:value), **)
+    end
+
+    def radio(value, *modifiers, **options)
+      Forms::Radio.new(
+        *modifiers,
+        value:,
+        checked: field_value == value,
+        **field_attributes.merge(options).merge(id: "#{field_id}_#{value}")
+      )
+    end
+    alias radio_button radio
+
+    def select(choices = nil, **options)
+      Forms::Select.new(choices:, selected: field_value, **select_options(options))
+    end
+
+    # Enhanced select: choices.js-backed when searchable, native otherwise.
+    def choices_select(choices = nil, *modifiers, **options)
+      searchable = options.delete(:searchable) { false }
+      opts = select_options(options)
+      if searchable
+        Forms::ChoicesSelect.new(*modifiers, choices:, selected: field_value, searchable: true, **opts)
+      else
+        Forms::Select.new(*modifiers, choices:, selected: field_value, **opts)
+      end
+    end
+
+    def label(text = nil, *modifiers, **, &block)
+      Forms::Label.new(*modifiers, text: text || (block ? nil : field_label), for: field_id, **, &block)
+    end
+
+    def control(label: nil, hint: nil, required: false, **, &)
+      Forms::FormControl.new(label:, hint:, error: field_error_message, for: field_id, required:, **, &)
+    end
+
+    # --- derived metadata ---
+
+    # Humanized label text: the model's human_attribute_name when available.
+    def field_label
+      if @model.respond_to?(:class) && @model.class.respond_to?(:human_attribute_name)
+        @model.class.human_attribute_name(@name)
+      else
+        @name.to_s.tr("_", " ").capitalize
+      end
+    end
+
+    # Inferred from the model's presence validators (ActiveModel). False when the
+    # model doesn't expose validators.
+    def required?
+      return false unless @model.respond_to?(:class) && @model.class.respond_to?(:validators_on)
+
+      @model.class.validators_on(@name).any? do |v|
+        v.is_a?(ActiveModel::Validations::PresenceValidator) && !conditional?(v)
+      end
+    rescue StandardError
+      false
+    end
+
+    def invalid?
+      @errors&.include?(@name)
+    end
+
+    def field_name
+      @scope ? "#{@scope}[#{@name}]" : @name.to_s
+    end
+
+    def field_id
+      if @scope
+        "#{@scope.tr('[', '_').delete(']')}_#{@name}"
+      else
+        @name.to_s
+      end
+    end
+
+    # Ransack-safe getter: dispatches through method_missing consumers (e.g.
+    # Ransack::Search predicate getters) but only swallows the direct dispatch miss.
+    def field_value
+      return nil unless @model
+
+      @model.public_send(@name)
+    rescue NoMethodError => e
+      raise unless e.receiver.equal?(@model) && e.name == @name
+
+      nil
+    end
+
+    # --- client-side validation wiring (pairs with Forms::Validations) ---
+
+    # Merge a per-call `validate:` override into the field's option hash. Strips
+    # `:validate` and, when rules apply, merges the Stimulus data into `data:`.
+    # Falls back to the form-level introspector when `:validate` is absent.
+    #
+    #   validate: false           → opt this field out
+    #   validate: true            → the form-level introspector
+    #   validate: { length: {…} } → explicit inline rules
+    def apply_validations(options)
+      return consume_validate(options) if options.key?(:validate)
+
+      data = form_introspector.data_attributes_for(@name)
+      return options if data.empty?
+
+      options.merge(data: merge_data(options[:data], data))
+    end
+
+    private
+
+    def consume_validate(options)
+      return options unless options.key?(:validate)
+
+      override = options.delete(:validate)
+      data = validation_data_for(override)
+      return options if data.empty?
+
+      options.merge(data: merge_data(options[:data], data))
+    end
+
+    def validation_data_for(override)
+      case override
+      when true then form_introspector.data_attributes_for(@name)
+      when Hash then Forms::Validations::ManualRules.new(override).data_attributes
+      else {} # false / nil / anything else → no client-side validation
+      end
+    end
+
+    def form_introspector
+      if @form.respond_to?(:validations_introspector)
+        @form.validations_introspector
+      else
+        Forms::Validations::Introspector::Null.new
+      end
+    end
+
+    def merge_data(existing, additions)
+      existing = (existing || {}).dup
+      additions.each do |key, value|
+        if key == :controller
+          existing[:controller] = [existing[:controller], value].compact.reject { |s| s.to_s.empty? }.join(" ")
+        else
+          existing[key] = value
+        end
+      end
+      existing
+    end
+
+    def conditional?(validator)
+      validator.options.key?(:if) || validator.options.key?(:unless) || validator.options.key?(:on)
+    end
+
+    def field_attributes
+      { name: field_name, id: field_id, value: field_value, error: invalid? }
+    end
+
+    def field_error_message
+      @errors&.full_messages_for(@name)&.first if invalid?
+    end
+
+    def select_options(options)
+      include_blank = options.delete(:include_blank)
+      prompt = options.delete(:prompt)
+      opts = field_attributes.merge(options)
+      opts[:include_blank] = include_blank unless include_blank.nil?
+      opts[:prompt] = prompt unless prompt.nil?
+      opts
+    end
+  end
+end

data/lib/forms/field_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Forms
+  # Inline validation error shown beneath a field. Uses the same visual treatment
+  # (`text-error text-sm`) the client-side validation controllers apply, so a
+  # server-rendered error and a live client-rendered one look identical.
+  class FieldError < Phlex::HTML
+    def initialize(message: nil, **options)
+      @message = message
+      @options = options
+      super()
+    end
+
+    def view_template
+      return unless @message
+
+      p(class: classes) { @message }
+    end
+
+    private
+
+    def classes
+      PhlexForms::ClassMerge.merge("text-error text-sm mt-1", @options[:class])
+    end
+  end
+end

data/lib/forms/field_hint.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Forms
+  # Inline hint/help text shown beneath a field.
+  class FieldHint < Phlex::HTML
+    def initialize(text: nil, **options)
+      @text = text
+      @options = options
+      super()
+    end
+
+    def view_template
+      return unless @text
+
+      p(class: classes) { @text }
+    end
+
+    private
+
+    def classes
+      PhlexForms::ClassMerge.merge("text-base-content/60 text-sm mt-1", @options[:class])
+    end
+  end
+end

data/lib/forms/fields_for_builder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Forms
+  # Yielded inside Form#fields_for for nested attributes. Reuses the shared
+  # Builder API (f.field, f.Input, ...) against a nested scope, rendering through
+  # the parent form.
+  class FieldsForBuilder
+    include PhlexForms::Builder
+
+    attr_reader :model, :scope, :errors, :parent_form
+
+    def initialize(model:, scope:, errors:, parent_form:)
+      @model = model
+      @scope = scope
+      @errors = errors
+      @parent_form = parent_form
+    end
+
+    # The Builder mixin renders through `render`; delegate to the parent form.
+    def render(...)
+      @parent_form.render(...)
+    end
+
+    def field_object(name)
+      Forms::Field.new(name:, model: @model, scope: @scope, errors: @errors, form: @parent_form)
+    end
+
+    # Nested fields_for (single association or has_many collection).
+    def fields_for(association_name, model = nil, &)
+      return unless block_given?
+
+      associated = model || (@model.public_send(association_name) if @model.respond_to?(association_name))
+      base_scope = "#{@scope}[#{association_name}_attributes]"
+
+      if associated.respond_to?(:each_with_index)
+        associated.each_with_index do |item, index|
+          yield build_nested("#{base_scope}[#{index}]", item)
+        end
+      else
+        yield build_nested(base_scope, associated)
+      end
+    end
+
+    def field_name(name) = "#{@scope}[#{name}]"
+    def field_id(name)   = "#{@scope.tr('[', '_').delete(']')}_#{name}"
+
+    private
+
+    def build_nested(scope, item)
+      self.class.new(
+        model: item,
+        scope:,
+        errors: (item.errors if item.respond_to?(:errors)),
+        parent_form: @parent_form
+      )
+    end
+  end
+end

data/lib/forms/file_input.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Forms
+  # A model-bound `<input type="file">`, delegating to DaisyUI::FileInput.
+  class FileInput < Phlex::HTML
+    include PhlexForms::DelegatedField
+
+    def initialize(*modifiers, name: nil, id: nil, multiple: false, accept: nil,
+                   error: false, disabled: false, required: false, full_width: true, **attributes)
+      @modifiers = normalize_modifiers(modifiers)
+      @name = name
+      @id = id
+      @multiple = multiple
+      @accept = accept
+      @error = error
+      @disabled = disabled
+      @required = required
+      @full_width = full_width
+      @attributes = attributes
+      super()
+    end
+
+    def view_template
+      attrs = binding_attributes(accept: @accept)
+      attrs[:multiple] = true if @multiple
+      render DaisyUI::FileInput.new(*daisy_modifiers, **attrs)
+    end
+  end
+end

data/lib/forms/form.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+# The model-bound form. Yields itself as the builder:
+#
+#   Form(model: @user) do |f|
+#     f.field :email
+#     f.field :role, as: :select, choices: roles
+#     f.submit
+#   end
+#
+# Derives scope/url/method from the model (including the polymorphic array form
+# `model: [parent, child]`), emits the CSRF + method-override hidden fields, and
+# always sets multipart encoding for non-GET forms so file inputs never silently
+# fail to upload.
+module Forms
+  class Form < Phlex::HTML
+    include Phlex::Rails::Helpers::FormAuthenticityToken if defined?(Phlex::Rails::Helpers::FormAuthenticityToken)
+    include PhlexForms::Builder
+
+    attr_reader :model, :scope, :url, :method, :errors, :validate
+
+    def initialize(*modifiers, model: nil, scope: nil, url: nil, method: nil, validate: false, **options)
+      super()
+      @base_modifiers = modifiers
+      @options = options
+      @model = record_from(model)
+      @scope = scope&.to_s || derive_scope(@model)
+      @url = url || derive_url(model)
+      @method = method || derive_method(@model)
+      @errors = (@model.errors if @model.respond_to?(:errors))
+      @validate = validate
+    end
+
+    # Introspector for the bound model when client-side validation is enabled, or
+    # a no-op Null otherwise. Callers can always call #data_attributes_for(attr).
+    def validations_introspector
+      @validations_introspector ||=
+        if @validate
+          Forms::Validations::Introspector.for(@model)
+        else
+          Forms::Validations::Introspector::Null.new
+        end
+    end
+
+    def view_template(&)
+      form(action: @url, accept_charset: "UTF-8", method: form_method, **form_attributes) do
+        authenticity_token_field unless @method&.to_sym == :get
+        method_field if @method && %i[get post].exclude?(@method.to_sym)
+        yield self if block_given?
+      end
+    end
+
+    # Return a Forms::Field for a name (used by the Builder mixin).
+    def field_object(name)
+      Forms::Field.new(name:, model: @model, scope: @scope, errors: @errors, form: self)
+    end
+
+    def submit(*, **, &)
+      render Forms::Submit.new(*, model: @model, **, &)
+    end
+
+    def rich_textarea(name, *modifiers, **)
+      render field_object(name).rich_textarea(*modifiers, **)
+    end
+    alias rich_text_area rich_textarea
+
+    def time_zone_select(name, *modifiers, selected: nil, **)
+      render Forms::TimeZoneSelect.new(
+        *modifiers,
+        name: field_name(name),
+        id: field_id(name),
+        selected: selected || @model&.public_send(name),
+        **
+      )
+    end
+
+    # Nested attributes. Yields a FieldsForBuilder per association (single) or per
+    # item (has_many), with the correctly-indexed nested scope.
+    def fields_for(association_name, model = nil, &)
+      return unless block_given?
+
+      associated = model || (@model.public_send(association_name) if @model.respond_to?(association_name))
+      attributes_key = "#{association_name}_attributes"
+      base_scope = @scope ? "#{@scope}[#{attributes_key}]" : attributes_key
+
+      if associated.respond_to?(:each_with_index)
+        associated.each_with_index do |item, index|
+          yield build_fields_for("#{base_scope}[#{index}]", item)
+        end
+      else
+        yield build_fields_for(base_scope, associated)
+      end
+    end
+
+    # Rails-style collection_check_boxes. Emits a hidden field so an empty
+    # selection still submits, then yields a builder per collection item.
+    def collection_check_boxes(name, collection, value_method, text_method, &)
+      return unless block_given?
+
+      input(type: "hidden", name: "#{field_name(name)}[]", value: "")
+      current = Array(@model&.public_send(name))
+      current_ids = current.map { |v| v.respond_to?(value_method) ? v.public_send(value_method) : v }
+
+      collection.each do |item|
+        item_value = item.public_send(value_method)
+        item_text = text_method.is_a?(Proc) ? text_method.call(item) : item.public_send(text_method)
+        yield Forms::CollectionCheckBoxBuilder.new(
+          object: item, value: item_value, text: item_text,
+          checked: current_ids.include?(item_value),
+          name: "#{field_name(name)}[]", id: "#{field_id(name)}_#{item_value}"
+        )
+      end
+    end
+
+    # Rails-style collection_select over an enumerable of records.
+    def collection_select(name, collection, value_method, text_method, options = {}, html_options = {})
+      choices = collection.map do |item|
+        text = text_method.is_a?(Proc) ? text_method.call(item) : item.public_send(text_method)
+        [text, item.public_send(value_method)]
+      end
+      choices = [[options[:prompt], ""]] + choices if options[:prompt]
+      render field_object(name).select(choices, **options.except(:prompt), **html_options)
+    end
+
+    # Public name/id/value helpers for external components mirroring the Rails API.
+    def field_name(name) = @scope ? "#{@scope}[#{name}]" : name.to_s
+    def field_id(name)   = @scope ? "#{@scope}_#{name}" : name.to_s
+
+    private
+
+    def build_fields_for(scope, item)
+      Forms::FieldsForBuilder.new(
+        model: item,
+        scope:,
+        errors: (item.errors if item.respond_to?(:errors)),
+        parent_form: self
+      )
+    end
+
+    # For a polymorphic array model, the record is the last element.
+    def record_from(model)
+      model.is_a?(Array) ? model.last : model
+    end
+
+    def form_method
+      %i[get post].include?(@method.to_sym) ? @method : :post
+    end
+
+    def form_attributes
+      attrs = @options.except(:class, :local, :multipart, :turbo_frame, :id, :data)
+      attrs[:id] = @options[:id] if @options[:id]
+      if (classes = form_classes)
+        attrs[:class] = classes
+      end
+      attrs[:data] = (@options[:data] || {}).dup
+      attrs[:data][:turbo] = "false" if @options[:local] == true
+      attrs[:data][:turbo_frame] = @options[:turbo_frame] if @options[:turbo_frame]
+      apply_validation_coordinator(attrs) if @validate
+      attrs[:data].transform_values! { |v| v == false ? "false" : v }
+      attrs[:enctype] = "multipart/form-data" unless @method&.to_sym == :get
+      attrs
+    end
+
+    # When client-side validation is on, attach the form-level coordinator
+    # controller (submit interceptor) and turn OFF the native browser validation
+    # UI (novalidate) — the Stimulus layer owns error display.
+    def apply_validation_coordinator(attrs)
+      existing = attrs[:data][:controller].to_s
+      coordinator = "forms--validations--form"
+      attrs[:data][:controller] = [existing, coordinator].reject(&:empty?).join(" ")
+      attrs[:novalidate] = true
+    end
+
+    def form_classes
+      classes = []
+      classes << "space-y-4" if @base_modifiers.include?(:spaced)
+      classes << "space-y-6" if @base_modifiers.include?(:spacious)
+      PhlexForms::ClassMerge.merge(classes.join(" "), @options[:class]).presence
+    end
+
+    def authenticity_token_field
+      return unless respond_to?(:form_authenticity_token)
+
+      token = form_authenticity_token
+      input(type: "hidden", name: "authenticity_token", value: token) if token
+    end
+
+    def method_field
+      input(type: "hidden", name: "_method", value: @method)
+    end
+
+    def derive_scope(record)
+      return nil unless record
+
+      if record.respond_to?(:model_name)
+        record.model_name.param_key
+      elsif record.is_a?(Symbol) || record.is_a?(String)
+        record.to_s
+      else
+        record.class.name.underscore.tr("/", "_")
+      end
+    end
+
+    # For an array model, build the url from the whole array (polymorphic nesting);
+    # otherwise from the record.
+    def derive_url(model)
+      return "/" unless model
+
+      record = record_from(model)
+      persisted = record.respond_to?(:persisted?) && record.persisted?
+      prefix = url_prefix(model, record)
+      persisted ? "#{prefix}/#{record.to_param}" : prefix
+    end
+
+    def url_prefix(model, record)
+      parents = model.is_a?(Array) ? model[0...-1] : []
+      segments = parents.map { |p| "/#{p.class.name.underscore.pluralize}/#{p.to_param}" }
+      "#{segments.join}/#{derive_scope(record).pluralize}"
+    end
+
+    def derive_method(record)
+      record.respond_to?(:persisted?) && record.persisted? ? :patch : :post
+    end
+  end
+end

data/lib/forms/form_control.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Forms
+  # Wraps a field in the daisyui form-control layout: optional label on top, the
+  # field (yielded block), then an error (if present) or a hint. This is the
+  # workhorse behind the Control-first `f.field` API and the explicit `f.Control`
+  # escape hatch.
+  class FormControl < Phlex::HTML
+    def initialize(*modifiers, label: nil, hint: nil, error: nil, for: nil, required: false, **options)
+      @modifiers = modifiers
+      @label = label
+      @hint = hint
+      @error = error
+      @field_id = grab(for:)
+      @required = required
+      @options = options
+      super()
+    end
+
+    def view_template(&)
+      div(class: control_classes, **@options.except(:class)) do
+        render Forms::Label.new(text: @label, for: @field_id, required: @required) if @label
+
+        yield if block_given?
+
+        if @error
+          render Forms::FieldError.new(message: @error)
+        elsif @hint
+          render Forms::FieldHint.new(text: @hint)
+        end
+      end
+    end
+
+    private
+
+    def control_classes
+      base = %w[form-control w-full]
+      base << "flex flex-row items-center gap-4" if @modifiers.include?(:horizontal)
+      PhlexForms::ClassMerge.merge(base.join(" "), @options[:class])
+    end
+  end
+end

data/lib/forms/input.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Forms
+  # A model-bound text-like input. Thin form-binding layer over DaisyUI::Input:
+  # it wires name/id/value/error/required onto the field, then delegates all
+  # markup and variant handling to the daisyui gem's component (which stacks
+  # positional color/size/style modifiers and passes a block straight through).
+  #
+  #   Forms::Input.new(:primary, :lg, type: "email", name: "user[email]")
+  #
+  # `w-full` is added by default. For the daisyui v5 "icon/text inside the field"
+  # pattern (a <label class="input"> wrapper), use Forms::WrappedInput.
+  class Input < Phlex::HTML
+    include PhlexForms::DelegatedField
+
+    def initialize(*modifiers, type: "text", name: nil, id: nil, value: nil,
+                   error: false, disabled: false, required: false, full_width: true, **attributes)
+      @modifiers = normalize_modifiers(modifiers)
+      @type = type
+      @name = name
+      @id = id
+      @value = value
+      @error = error
+      @disabled = disabled
+      @required = required
+      @full_width = full_width
+      @attributes = attributes
+      super()
+    end
+
+    def view_template(&)
+      render DaisyUI::Input.new(*daisy_modifiers, type: @type, value: @value.to_s, **binding_attributes, &)
+    end
+  end
+end

data/lib/forms/label.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Forms
+  # A standalone form label: `<label for><span class="label">text</span></label>`
+  # with an optional required marker. A block, when given, is yielded directly
+  # inside the `<label>` so checkboxes/toggles can nest as direct children.
+  #
+  # For the daisyui v5 "text/icon inside the field" wrapper (<label class="input">
+  # {span.label}{input}), use Forms::WrappedInput instead.
+  class Label < Phlex::HTML
+    def initialize(text: nil, for: nil, required: false, **attributes)
+      @text = text
+      @for = grab(for:)
+      @required = required
+      @attributes = attributes
+      super()
+    end
+
+    def view_template(&block)
+      label(for: @for, class: @attributes[:class], **@attributes.except(:class)) do
+        if block
+          yield
+        elsif @text
+          span(class: "label") do
+            plain @text
+            span(class: "text-error ml-1") { "*" } if @required
+          end
+        end
+      end
+    end
+  end
+end