lcp 0.1.0

data/app/helpers/lcp_ruby/form_helper.rb

@@ -0,0 +1,1020 @@
+module LcpRuby
+  module FormHelper
+    include LcpRuby::AssociationOptionsBuilder
+
+    # Dispatches form rendering by input_type. Accepts any field_def
+    # implementing the duck-typed contract:
+    #   * Metadata::FieldDefinition — backed by an AR column
+    #   * LcpRuby::VirtualFields::VirtualField — synthetic field, no
+    #     backing column (used by filter forms and other future
+    #     consumers — wizards, virtual show pages, …)
+    # Both implement:
+    #   #type, #enum?, #enum_value_names,
+    #   #enum_label_for(value, model_name:), #attachment_options.
+    # See spec § 5 step 8 for the exhaustive callsite audit.
+    def render_form_input(form, field_name, input_type, field_config, field_def)
+      input_options = field_config["input_options"] || {}
+
+      case input_type.to_s
+      when "text", "textarea", "rich_text_editor"
+        opts = { placeholder: field_config["placeholder"] }
+        opts[:rows] = input_options["rows"] if input_options["rows"]
+        opts[:maxlength] = input_options["max_length"] if input_options["max_length"]
+        if field_def&.type == "json"
+          raw_value = form.object&.public_send(field_name)
+          opts[:value] = pretty_print_json_value(raw_value) if raw_value.present?
+        end
+        if input_options["show_counter"] && input_options["max_length"]
+          content_tag(:div, data: { controller: "lcp-char-counter" }) do
+            form.text_area(field_name, **opts.compact.merge(
+              data: { "lcp-char-counter-target": "input", action: "input->lcp-char-counter#update" }
+            )) +
+              content_tag(:span, "", class: "lcp-char-counter",
+                data: { "lcp-char-counter-target": "display" })
+          end
+        else
+          form.text_area(field_name, **opts.compact)
+        end
+      when "select"
+        render_select_input(form, field_name, field_config, field_def)
+      when "radio"
+        render_radio_input(form, field_name, field_config, field_def)
+      when "number"
+        opts = { step: input_options["step"] || "any", placeholder: field_config["placeholder"] }
+        opts[:min] = input_options["min"] if input_options["min"]
+        opts[:max] = input_options["max"] if input_options["max"]
+        form.number_field(field_name, **opts.compact)
+      when "date_picker", "date"
+        form.date_field(field_name)
+      when "datetime"
+        form.datetime_local_field(field_name)
+      when "date_range"
+        render_date_range(form, field_name, field_config)
+      when "boolean", "checkbox"
+        form.check_box(field_name)
+      when "association_select"
+        render_association_select(form, field_name, field_config)
+      when "multi_select"
+        render_multi_select(form, field_name, field_config, field_def)
+      when "tree_select"
+        render_tree_select(form, field_name, field_config)
+      when "email"
+        form.email_field(field_name,
+          placeholder: field_config["placeholder"],
+          autofocus: field_config["autofocus"])
+      when "tel"
+        form.telephone_field(field_name,
+          placeholder: field_config["placeholder"],
+          autofocus: field_config["autofocus"])
+      when "url"
+        form.url_field(field_name,
+          placeholder: field_config["placeholder"],
+          autofocus: field_config["autofocus"])
+      when "enum"
+        render_select_input(form, field_name, field_config, field_def)
+      when "color"
+        form.color_field(field_name)
+      when "file_upload"
+        render_file_upload_input(form, field_name, field_config, field_def)
+      when "slider"
+        render_slider_input(form, field_name, input_options)
+      when "toggle"
+        render_toggle_input(form, field_name)
+      when "rating"
+        render_rating_input(form, field_name, input_options)
+      when "array_input", "tags"
+        render_array_input(form, field_name, field_config, field_def)
+      when "field_picker"
+        render_field_picker_input(form, field_name, field_config)
+      when "formatting_options"
+        render_formatting_options_input(form, field_name, field_config)
+      when "import_mapper"
+        render_import_mapper_input(form, field_name, field_config)
+      when "hidden"
+        raw_value = form.object&.respond_to?(field_name) ? form.object.send(field_name) : nil
+        value = case raw_value
+        when Hash, Array then raw_value.to_json
+        else raw_value.to_s
+        end
+        form.hidden_field(field_name, value: value)
+      else
+        form.text_field(field_name,
+          placeholder: field_config["placeholder"],
+          autofocus: field_config["autofocus"])
+      end
+    end
+
+    # Render a form input for JSON field items using raw name attributes (no form builder).
+    # Also used by render_manage_input for the manage page.
+    # Resolves select options from: field_options override > enum definition >
+    # input_options.values > options array > field_config["options"].
+    def render_json_field_input(name, value, input_type, field_config, field_def, field_options: nil, field_name: nil)
+      # Controller-provided select list override (used by manage page)
+      if field_options.is_a?(Hash) && field_name && field_options[field_name].is_a?(Array)
+        opts = field_options[field_name].map { |v| [ v.humanize, v ] }
+        return select_tag(name, options_for_select([ [ "", "" ] ] + opts, value.to_s))
+      end
+
+      # Enum fields
+      if field_def&.enum?
+        options = field_def.enum_value_names.map { |v| [ field_def.enum_label_for(v), v ] }
+        options_html = options_for_select([ [ "", "" ] ] + options, value.to_s)
+        return select_tag(name, options_html)
+      end
+
+      case input_type.to_s
+      when "boolean"
+        hidden = hidden_field_tag(name, "0")
+        checkbox = check_box_tag(name, "1", value == true || value == "1" || value == 1 || value == "true")
+        hidden + checkbox
+      when "number", "integer", "float", "decimal"
+        number_field_tag(name, value, step: "any", placeholder: field_config["placeholder"])
+      when "text", "textarea"
+        text_area_tag(name, value, placeholder: field_config["placeholder"])
+      when "date", "date_picker"
+        date_field_tag(name, value)
+      when "datetime"
+        datetime_field_tag(name, value)
+      when "select"
+        select_values = resolve_raw_select_options(field_config)
+        if select_values
+          opts = select_values.map { |o| [ o.to_s.humanize, o ] }
+          select_tag(name, options_for_select([ [ "", "" ] ] + opts, value.to_s))
+        else
+          text_field_tag(name, value, placeholder: field_config["placeholder"])
+        end
+      else
+        text_field_tag(name, value, placeholder: field_config["placeholder"])
+      end
+    end
+
+    # Render a form input for the manage page, using raw name prefix instead of a form builder.
+    # Delegates to render_json_field_input after resolving name/value and field_options override.
+    def render_manage_input(prefix, field_name, input_type, field_config, field_def, record, field_options)
+      name = "#{prefix}[#{field_name}]"
+      value = record.respond_to?(field_name) ? record.send(field_name) : nil
+
+      render_json_field_input(name, value, input_type, field_config, field_def,
+                              field_options: field_options, field_name: field_name)
+    end
+
+    private
+
+    def non_lcp_association_fallback_field(form, field_name)
+      form.number_field(field_name, placeholder: I18n.t("lcp_ruby.form.id_placeholder", default: "ID"))
+    end
+
+    # Resolve select option values from field_config.
+    # Supports both YAML format (options: [a, b]) and DSL format (input_options: { values: [a, b] }).
+    def resolve_raw_select_options(field_config)
+      # Direct options array (YAML: options: [a, b, c])
+      return field_config["options"] if field_config["options"].is_a?(Array)
+
+      # DSL-style input_options with values key (input_options: { values: [a, b, c] })
+      io = field_config["input_options"]
+      return io["values"] if io.is_a?(Hash) && io["values"].is_a?(Array)
+
+      nil
+    end
+
+    def render_array_input(form, field_name, field_config, field_def)
+      input_options = field_config["input_options"] || {}
+      current_value = Array(form.object&.send(field_name))
+      placeholder = input_options["placeholder"] || I18n.t("lcp_ruby.array_input.placeholder", default: "Add item...")
+      max = input_options["max"]
+      suggestions = input_options["suggestions"] || []
+
+      wrapper_data = { controller: "lcp-array-input" }
+      wrapper_data["lcp-array-input-max-value"] = max if max
+      wrapper_data["lcp-array-input-suggestions-value"] = suggestions.to_json if suggestions.any?
+
+      content_tag(:div, class: "lcp-array-input-wrapper", data: wrapper_data) do
+        parts = ActiveSupport::SafeBuffer.new
+
+        # Hidden field to submit the array as JSON
+        parts << form.hidden_field(field_name,
+          value: current_value.to_json,
+          data: { "lcp-array-input-target": "hidden" })
+
+        # Tag chips container
+        parts << content_tag(:div, class: "lcp-array-chips",
+          data: { "lcp-array-input-target": "chips" }) {
+          safe_join(current_value.map { |item|
+            content_tag(:span, class: "lcp-array-chip") do
+              content_tag(:span, item.to_s, class: "lcp-array-chip-text") +
+                content_tag(:button, "\u00d7", type: "button", class: "lcp-array-chip-remove",
+                  data: { "lcp-array-remove": item.to_s })
+            end
+          })
+        }
+
+        # Text input for adding new items
+        parts << tag(:input, type: "text", class: "lcp-array-text-input",
+          placeholder: placeholder,
+          data: {
+            "lcp-array-input-target": "text",
+            action: "keydown->lcp-array-input#keydown input->lcp-array-input#filter focus->lcp-array-input#showSuggestions blur->lcp-array-input#schedulHideSuggestions"
+          })
+
+        parts
+      end
+    end
+
+    def render_file_upload_input(form, field_name, field_config, field_def)
+      input_options = field_config["input_options"] || {}
+      options = field_def&.attachment_options || {}
+      multiple = options["multiple"] == true
+      accept = options["accept"]
+      max_size = options["max_size"]
+      preview = input_options["preview"]
+      drag_drop = input_options["drag_drop"]
+      direct_upload = input_options["direct_upload"]
+
+      data_attrs = { controller: "lcp-file-upload" }
+      data_attrs["lcp-file-upload-max-size-value"] = max_size if max_size
+
+      content_tag(:div, class: "lcp-file-upload", data: data_attrs) do
+        parts = ActiveSupport::SafeBuffer.new
+
+        # Show existing attachment(s)
+        if form.object && form.object.respond_to?(field_name)
+          attachment = form.object.send(field_name)
+          if multiple && attachment.respond_to?(:attached?) && attachment.attached?
+            parts << render_existing_multiple_attachments(form, field_name, attachment)
+          elsif !multiple && attachment.respond_to?(:attached?) && attachment.attached?
+            parts << render_existing_single_attachment(form, field_name, attachment)
+          end
+        end
+
+        # File input
+        file_opts = {}
+        file_opts[:multiple] = true if multiple
+        file_opts[:accept] = accept if accept
+        file_opts[:direct_upload] = true if direct_upload
+        file_opts[:class] = "lcp-file-input"
+        input_data = { "lcp-file-upload-target": "input" }
+        input_data[:action] = "change->lcp-file-upload#preview" if preview
+        file_opts[:data] = input_data
+
+        if drag_drop
+          # Hide the actual file input, show drop zone
+          file_opts[:style] = "display: none"
+          parts << form.file_field(field_name, **file_opts)
+          drop_zone_text = if multiple
+            I18n.t("lcp_ruby.file_upload.drop_zone_multiple", default: "Drop files here or click to browse")
+          else
+            I18n.t("lcp_ruby.file_upload.drop_zone_single", default: "Drop file here or click to browse")
+          end
+          drop_zone_data = {
+            "lcp-file-upload-target": "dropZone",
+            action: "click->lcp-file-upload#openPicker dragenter->lcp-file-upload#dragEnter dragover->lcp-file-upload#dragOver dragleave->lcp-file-upload#dragLeave drop->lcp-file-upload#drop"
+          }
+          parts << content_tag(:div, class: "lcp-drop-zone", data: drop_zone_data) do
+            content_tag(:span, drop_zone_text)
+          end
+        else
+          parts << form.file_field(field_name, **file_opts)
+        end
+
+        # Preview container
+        if preview
+          parts << content_tag(:div, "", class: "lcp-file-preview-container",
+            data: { "lcp-file-upload-target": "preview" })
+        end
+
+        parts
+      end
+    end
+
+    def render_existing_single_attachment(form, field_name, attachment)
+      content_tag(:div, class: "lcp-existing-attachment") do
+        parts = ActiveSupport::SafeBuffer.new
+        blob = attachment.blob
+
+        if blob.image?
+          parts << image_tag(Rails.application.routes.url_helpers.rails_blob_path(attachment, only_path: true), class: "lcp-attachment-thumbnail", style: "max-width: 120px; max-height: 120px;")
+        else
+          parts << content_tag(:span, blob.filename.to_s, class: "lcp-attachment-filename")
+          parts << " "
+          parts << content_tag(:span, "(#{number_to_human_size(blob.byte_size)})", class: "lcp-attachment-size")
+        end
+
+        # Remove checkbox
+        parts << content_tag(:label, class: "lcp-attachment-remove") do
+          check_box_tag("record[remove_#{field_name}]", "1", false) +
+            " ".html_safe +
+            I18n.t("lcp_ruby.file_upload.remove", default: "Remove")
+        end
+
+        parts
+      end
+    rescue StandardError => e
+      LcpRuby.record_error(e, subsystem: "form_helper", field: field_name)
+      content_tag(:div, class: "lcp-existing-attachment") do
+        blob = attachment.blob
+        content_tag(:span, blob.filename.to_s, class: "lcp-attachment-filename") +
+          content_tag(:label, class: "lcp-attachment-remove") do
+            check_box_tag("record[remove_#{field_name}]", "1", false) +
+              " ".html_safe +
+              I18n.t("lcp_ruby.file_upload.remove", default: "Remove")
+          end
+      end
+    end
+
+    def render_existing_multiple_attachments(form, field_name, attachments)
+      content_tag(:div, class: "lcp-existing-attachments") do
+        safe_join(attachments.map { |att|
+          content_tag(:div, class: "lcp-existing-attachment") do
+            blob = att.blob
+            parts = ActiveSupport::SafeBuffer.new
+
+            if blob.image?
+              parts << begin
+                image_tag(Rails.application.routes.url_helpers.rails_blob_path(att, only_path: true), class: "lcp-attachment-thumbnail", style: "max-width: 80px; max-height: 80px;")
+              rescue StandardError => e
+                LcpRuby.record_error(e, subsystem: "form_helper", field: field_name)
+                content_tag(:span, blob.filename.to_s)
+              end
+            else
+              parts << content_tag(:span, blob.filename.to_s, class: "lcp-attachment-filename")
+              parts << " "
+              parts << content_tag(:span, "(#{number_to_human_size(blob.byte_size)})", class: "lcp-attachment-size")
+            end
+
+            parts
+          end
+        })
+      end
+    end
+
+    def render_radio_input(form, field_name, field_config, field_def)
+      input_options = field_config["input_options"] || {}
+      explicit_options = field_config["select_options"]
+
+      unless field_def&.enum? || explicit_options
+        return form.text_field(field_name, placeholder: field_config["placeholder"])
+      end
+
+      # FilterForm-supplied `select_options` are already `[label, value]`
+      # pairs; the enum path needs lookup + label resolution. Same dual
+      # source as render_select_input.
+      if explicit_options
+        labeled_values = explicit_options.map do |opt|
+          opt.is_a?(Array) ? opt : [ opt.to_s.humanize, opt ]
+        end
+      else
+        values = field_def.enum_value_names
+        values = apply_role_value_filters(values, input_options)
+        i18n_scope = input_options["label_i18n_scope"]
+
+        model_name = current_model_name
+        labeled_values = values.map do |v|
+          label_text = if i18n_scope
+            I18n.t("#{i18n_scope}.#{v}", default: v.humanize)
+          else
+            field_def.enum_label_for(v, model_name: model_name)
+          end
+          [ label_text, v ]
+        end
+      end
+
+      # Apply optional sorting (by label, consistent with select)
+      case input_options["sort"]
+      when "alphabetical"
+        labeled_values = labeled_values.sort_by { |label, _| label.to_s.downcase }
+      when "reverse"
+        labeled_values = labeled_values.reverse
+      end
+
+      content_tag(:div, class: "lcp-radio-group") do
+        labeled_values.map do |label_text, v|
+          content_tag(:label, class: "lcp-radio-label") do
+            form.radio_button(field_name, v) + " ".html_safe + label_text
+          end
+        end.join.html_safe
+      end
+    end
+
+    def render_select_input(form, field_name, field_config, field_def)
+      input_options = field_config["input_options"] || {}
+      explicit_options = field_config["select_options"]
+
+      unless field_def&.enum? || explicit_options
+        return form.text_field(field_name, placeholder: field_config["placeholder"])
+      end
+
+      if explicit_options
+        options = explicit_options.map do |opt|
+          opt.is_a?(Array) ? opt : [ opt.to_s.humanize, opt ]
+        end
+      else
+        values = field_def.enum_value_names
+        values = apply_role_value_filters(values, input_options)
+        i18n_scope = input_options["label_i18n_scope"]
+        model_name = current_model_name
+        options = values.map do |v|
+          label = if i18n_scope
+            I18n.t("#{i18n_scope}.#{v}", default: v.humanize)
+          else
+            field_def.enum_label_for(v, model_name: model_name)
+          end
+          [ label, v ]
+        end
+      end
+
+      # Apply optional sorting
+      case input_options["sort"]
+      when "alphabetical"
+        options = options.sort_by { |label, _| label.to_s.downcase }
+      when "reverse"
+        options = options.reverse
+      end
+
+      include_blank = input_options.fetch("include_blank", true)
+      html_attrs = input_options.fetch("html", {}).dup
+
+      # `input_options.multi: true` on a static-value select (filter_form
+      # `status: ["active", "on_leave"]` shape) needs to render an actual
+      # <select multiple>. Rails auto-appends `[]` to the field name and
+      # Tom Select picks up multiple from the DOM. Without this branch
+      # the value re-render after submit collapses an Array to a string
+      # and the URL stays scalar — submit/reload silently drops it.
+      if input_options["multi"]
+        html_attrs[:multiple] = true
+        html_attrs["data-controller"] ||= "lcp-tom-select"
+        html_attrs["data-lcp-tom-select-mode-value"] ||= "local"
+        # include_blank is meaningless on a multi-select (no "empty" slot
+        # — empty selection IS the absence of any value).
+        include_blank = false
+      end
+
+      form.select(field_name, options, { include_blank: include_blank }, html_attrs)
+    end
+
+    def render_association_select(form, field_name, field_config)
+      assoc = field_config["association"]
+      return non_lcp_association_fallback_field(form, field_name) unless assoc&.lcp_model?
+
+      input_options = field_config["input_options"] || {}
+      include_blank = input_options.fetch("include_blank", I18n.t("lcp_ruby.select.include_blank"))
+
+      html_attrs = {}
+
+      apply_depends_on_attrs!(html_attrs, input_options)
+
+      # Inline create integration
+      if input_options["allow_inline_create"] && respond_to?(:current_presenter) && current_presenter
+        html_attrs["data-lcp-inline-create"] = "true"
+        html_attrs["data-lcp-inline-create-url"] = lcp_ruby.inline_create_path(lcp_slug: current_page.slug)
+        html_attrs["data-lcp-inline-create-form-url"] = lcp_ruby.inline_create_form_path(lcp_slug: current_page.slug)
+        html_attrs["data-lcp-target-model"] = assoc.target_model
+        html_attrs["data-lcp-label-method"] = input_options["label_method"] || ""
+        html_attrs["data-lcp-tom-select-inline-create-value"] = "true"
+      end
+
+      # API-backed target model: always use remote search mode
+      api_target = api_association_target?(assoc)
+
+      # Tom Select integration
+      search_url = (input_options["search"] || api_target) ? select_options_url_for(field_name) : nil
+      if (input_options["search"] || api_target) && search_url
+        html_attrs["data-controller"] = "lcp-tom-select"
+        html_attrs["data-lcp-tom-select-mode-value"] = "remote"
+        html_attrs["data-lcp-tom-select-search-url-value"] = search_url
+        html_attrs["data-lcp-tom-select-per-page-value"] = input_options["per_page"] || 25
+        html_attrs["data-lcp-tom-select-min-query-value"] = input_options["min_query_length"] || (api_target ? 0 : 1)
+        # For remote mode, options are fetched on demand; render empty select
+        options = []
+        # If record already has a value, include that option so it displays correctly
+        if form.object&.send(field_name).present?
+          current_id = form.object.send(field_name)
+          target_class = LcpRuby.registry.model_for(assoc.target_model)
+          label_method = (input_options["label_method"] || resolve_default_label_method(assoc)).to_sym
+          join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+          if api_target
+            current_record = begin
+              target_class.find(current_id)
+            rescue LcpRuby::DataSource::RecordNotFound
+              nil
+            end
+          else
+            current_record = target_class.find_by(join_col => current_id)
+          end
+          options = [ [ resolve_label(current_record, label_method), current_record.public_send(join_col) ] ] if current_record
+        end
+      else
+        html_attrs["data-controller"] = "lcp-tom-select"
+        html_attrs["data-lcp-tom-select-mode-value"] = "local"
+        options = build_association_options(assoc, input_options, record: form.object)
+      end
+
+      # Legacy scope: inject disabled option for archived/deactivated records on edit
+      if input_options["legacy_scope"] && form.object && !form.object.new_record?
+        current_value = form.object.send(field_name)
+        if current_value.present? && !option_ids_include?(options, current_value)
+          legacy = resolve_legacy_record(assoc, input_options, current_value)
+          if legacy
+            options = inject_legacy_option(options, legacy)
+          end
+        end
+      end
+
+      if input_options["group_by"] && !input_options["search"]
+        form.select(field_name, grouped_options_for_select(options, form.object&.send(field_name)),
+                    { include_blank: include_blank }, html_attrs)
+      else
+        form.select(field_name, options, { include_blank: include_blank }, html_attrs)
+      end
+    end
+
+    def render_multi_select(form, field_name, field_config, field_def)
+      input_options = field_config["input_options"] || {}
+      assoc = field_config["multi_select_association"]
+      return form.text_field(field_name) unless assoc&.lcp_model?
+
+      options = build_association_options(assoc, input_options, record: form.object)
+      html_attrs = { multiple: true }
+      html_attrs[:"data-min"] = input_options["min"] if input_options["min"]
+      html_attrs[:"data-max"] = input_options["max"] if input_options["max"]
+      html_attrs["data-controller"] = "lcp-tom-select"
+      html_attrs["data-lcp-tom-select-mode-value"] = "local"
+
+      apply_depends_on_attrs!(html_attrs, input_options)
+
+      display_mode = input_options["display_mode"]
+      html_attrs["data-lcp-tom-select-display-mode-value"] = display_mode if display_mode
+
+      form.select(field_name, options, { include_blank: false }, html_attrs)
+    end
+
+    # Mutates html_attrs to add the four data attributes that wire the
+    # cascading_selects + Tom Select JS controllers to a depends_on parent.
+    # Shared by render_association_select and render_multi_select so the
+    # contract stays in one place.
+    def apply_depends_on_attrs!(html_attrs, input_options)
+      depends = input_options["depends_on"]
+      return unless depends
+
+      html_attrs["data-lcp-depends-on"] = depends["field"]
+      html_attrs["data-lcp-depends-fk"] = depends["foreign_key"]
+      html_attrs["data-lcp-depends-reset"] = depends.fetch("reset_strategy", "clear")
+      html_attrs["data-lcp-tom-select-depends-on-value"] = depends["field"]
+    end
+
+    # Renders a date range as a paired <input type="date"> for
+    # `<field>_from` and `<field>_to`. Used by AR forms (model must
+    # have two date columns following the naming convention) and by
+    # filter forms (declare two AM::Attribute date attrs of the same
+    # names). The outer form section template emits a single <label>
+    # pointing at the _from input; the fieldset legend (sr-only) gives
+    # screen readers the group context, and per-input aria-labels
+    # distinguish "from" / "to" without relying on visible affordance.
+    def render_date_range(form, field_name, field_config)
+      input_options = field_config["input_options"] || {}
+      legend_text   = field_config["label"].presence ||
+                      I18n.t("lcp_ruby.form.date_range.legend",
+                             default: field_name.to_s.humanize)
+      from_label    = I18n.t("lcp_ruby.form.date_range.from", default: "From")
+      to_label      = I18n.t("lcp_ruby.form.date_range.to",   default: "To")
+
+      common = { min: input_options["min"], max: input_options["max"] }.compact
+      from_opts = common.merge(placeholder: input_options["placeholder_from"],
+                               aria: { label: from_label }).compact
+      to_opts   = common.merge(placeholder: input_options["placeholder_to"],
+                               aria: { label: to_label }).compact
+
+      content_tag(:fieldset, class: "lcp-date-range") do
+        safe_join([
+          content_tag(:legend, legend_text, class: "sr-only"),
+          form.date_field("#{field_name}_from", **from_opts),
+          content_tag(:span, " – ", class: "lcp-date-range-separator"),
+          form.date_field("#{field_name}_to", **to_opts)
+        ])
+      end
+    end
+
+    def build_association_options(assoc, input_options, record: nil)
+      depends_on_values = extract_depends_on_from_record(input_options, record)
+      oq = build_options_query(assoc, input_options, role: current_user_role,
+                               depends_on_values: depends_on_values, user: LcpRuby::Current.user)
+      format_options_for_select(oq, input_options)
+    end
+
+    def extract_depends_on_from_record(input_options, record)
+      depends_on = input_options["depends_on"]
+      return {} unless depends_on && record
+
+      parent_field = depends_on["field"]
+      if parent_field && record.respond_to?(parent_field)
+        parent_value = record.send(parent_field)
+        parent_value.present? ? { parent_field => parent_value } : {}
+      else
+        {}
+      end
+    end
+
+    def api_association_target?(assoc)
+      return false unless assoc&.target_model
+
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      target_class.respond_to?(:lcp_api_model?) && target_class.lcp_api_model?
+    rescue LcpRuby::RegistryError
+      false
+    end
+
+    def select_options_url_for(field_name)
+      if respond_to?(:current_presenter) && current_presenter && respond_to?(:lcp_ruby)
+        lcp_ruby.select_options_path(lcp_slug: current_page.slug, field: field_name)
+      end
+    rescue StandardError => e
+      raise unless Rails.env.production?
+      LcpRuby.record_error(e, subsystem: "form_helper", field: field_name)
+      nil
+    end
+
+    # Sibling of select_options_url_for for filter-form contexts:
+    # dashboard routes have no current_presenter, so the presenter
+    # guard above would short-circuit. This helper requires only
+    # current_page (and a non-empty filter_form_definition) to emit
+    # a usable /select_options path. Pinned by spec acceptance test
+    # #18 — `filter_options_url_for` must be nil-safe when current_
+    # presenter is nil but current_page is a filter-form page.
+    def filter_options_url_for(field_name)
+      return nil unless respond_to?(:current_page) && current_page&.slug
+      return nil unless current_page.respond_to?(:filter_form_definition)
+      return nil if current_page.filter_form_definition.blank?
+      return nil unless respond_to?(:lcp_ruby)
+
+      lcp_ruby.select_options_path(lcp_slug: current_page.slug, field: field_name)
+    rescue StandardError => e
+      raise unless Rails.env.production?
+      LcpRuby.record_error(e, subsystem: "form_helper", field: field_name)
+      nil
+    end
+
+    def apply_role_value_filters(values, input_options)
+      role = current_user_role
+
+      if input_options["include_values"]&.key?(role)
+        allowed = Array(input_options.dig("include_values", role))
+        values = values.select { |v| allowed.include?(v) }
+      end
+
+      if input_options["exclude_values"]&.key?(role)
+        denied = Array(input_options.dig("exclude_values", role))
+        values = values.reject { |v| denied.include?(v) }
+      end
+
+      values
+    end
+
+    def current_user_role
+      LcpRuby::Current.user&.send(LcpRuby.configuration.role_method).to_s
+    rescue NoMethodError => e
+      raise unless Rails.env.production?
+      LcpRuby.record_error(e, subsystem: "form_helper")
+      ""
+    end
+
+    def render_slider_input(form, field_name, input_options)
+      min = input_options["min"] || 0
+      max = input_options["max"] || 100
+      step = input_options["step"] || 1
+      show_value = input_options["show_value"]
+
+      result = content_tag(:div, class: "lcp-slider-wrapper",
+        data: show_value ? { controller: "lcp-slider" } : {}) do
+        slider = form.range_field(field_name, min: min, max: max, step: step,
+          class: "lcp-slider", data: show_value ? {
+            "lcp-slider-target": "input",
+            action: "input->lcp-slider#update"
+          } : {})
+        if show_value
+          slider += content_tag(:span, "", class: "lcp-slider-value",
+            data: { "lcp-slider-target": "display" })
+        end
+        slider
+      end
+      result
+    end
+
+    def render_toggle_input(form, field_name)
+      content_tag(:label, class: "lcp-toggle") do
+        form.check_box(field_name, class: "lcp-toggle-input") +
+          content_tag(:span, "", class: "lcp-toggle-slider")
+      end
+    end
+
+    def render_rating_input(form, field_name, input_options)
+      max = (input_options["max"] || 5).to_i
+      form.select(field_name, (0..max).map { |i| [ i.to_s, i ] }, include_blank: false)
+    end
+
+    # Check if the current value exists in the flat or grouped options array.
+    # Compares as strings so both integer and string join keys work
+    # without coercion (e.g. "0042" must not match "42").
+    def option_ids_include?(options, value)
+      value_s = value.to_s
+      if options.is_a?(Hash)
+        # Grouped: { "group" => [[label, value], ...] }
+        options.values.flatten(1).any? { |opt| opt.is_a?(Array) && opt[1].to_s == value_s }
+      elsif options.is_a?(Array)
+        options.any? { |opt| opt.is_a?(Array) && opt[1].to_s == value_s }
+      else
+        false
+      end
+    end
+
+    # Inject a legacy (archived) option as disabled into the flat options list
+    def inject_legacy_option(options, legacy_option)
+      label, id = legacy_option
+      disabled_opt = [ "#{label} (#{I18n.t('lcp_ruby.select.legacy_group')})", id, { disabled: "disabled", class: "lcp-legacy-option" } ]
+      if options.is_a?(Array)
+        options + [ disabled_opt ]
+      else
+        options
+      end
+    end
+
+    def render_tree_select(form, field_name, field_config)
+      assoc = field_config["association"]
+      return non_lcp_association_fallback_field(form, field_name) unless assoc&.lcp_model?
+
+      input_options = field_config["input_options"] || {}
+      parent_field = input_options["parent_field"] || "parent_id"
+      label_method = (input_options["label_method"] || resolve_default_label_method(assoc)).to_sym
+      max_depth = (input_options["max_depth"] || 10).to_i
+
+      target_class = LcpRuby.registry.model_for(assoc.target_model)
+      records = target_class.all
+      records = records.order(input_options["sort"]) if input_options["sort"]
+
+      join_col = LcpRuby::AssociationJoinColumn.for(assoc, target_class).to_sym
+      tree_data = build_tree_data(records, parent_field, label_method, max_depth, join_col: join_col)
+      current_value = form.object&.send(field_name)
+      current_label = resolve_tree_current_label(records, current_value, label_method, join_col: join_col)
+      include_blank = input_options.fetch("include_blank", I18n.t("lcp_ruby.select.include_blank"))
+
+      hidden = form.hidden_field(field_name, data: {
+        "lcp-tree-select-target": "input"
+      })
+      trigger = content_tag(:button, current_label || include_blank,
+        type: "button", class: "lcp-tree-trigger",
+        data: { "lcp-tree-select-target": "trigger", action: "lcp-tree-select#toggle" })
+      dropdown = content_tag(:div, "", class: "lcp-tree-dropdown",
+        data: { "lcp-tree-select-target": "dropdown" })
+
+      content_tag(:div, hidden + trigger + dropdown, class: "lcp-tree-select-wrapper",
+        data: {
+          controller: "lcp-tree-select",
+          "lcp-tree-select-tree-data-value": tree_data.to_json,
+          "lcp-tree-select-include-blank-value": include_blank
+        })
+    end
+
+    # Internal recursion still walks via r.id because the target's
+    # parent_field references the actual id column — that is how the
+    # tree is structured in the database. The emitted payload carries
+    # `value: r.send(join_col)` which is what the select posts; the JS
+    # tree_select_controller reads node.value (not node.id).
+    def build_tree_data(records, parent_field, label_method, max_depth, parent_id = nil, depth = 0, join_col: :id)
+      return [] if depth >= max_depth
+
+      records.select { |r| r.send(parent_field) == parent_id }.map do |r|
+        {
+          value: r.public_send(join_col),
+          label: resolve_label(r, label_method),
+          children: build_tree_data(records, parent_field, label_method, max_depth, r.id, depth + 1, join_col: join_col)
+        }
+      end
+    end
+
+    def resolve_tree_current_label(records, current_value, label_method, join_col: :id)
+      return nil unless current_value.present?
+      record = records.find { |r| r.public_send(join_col).to_s == current_value.to_s }
+      record ? resolve_label(record, label_method) : nil
+    end
+
+    def render_field_picker_input(form, field_name, field_config)
+      source_presenter = form.object&.respond_to?(:source_presenter) ? form.object.source_presenter : nil
+      source_presenter = params[:source_presenter] if source_presenter.blank? && params[:source_presenter].present?
+      current_value = form.object&.respond_to?(field_name) ? form.object.send(field_name) : nil
+      json_value = case current_value
+      when Array then current_value.to_json
+      when String then current_value
+      else "[]"
+      end
+
+      presenter_def = source_presenter && LcpRuby.loader.presenter_definition(source_presenter)
+      presenter_slug = presenter_def&.slug ||
+        (presenter_def && Widgets::PresenterZoneResolver.routable_slug_for_model(presenter_def.model)) ||
+        source_presenter
+      fields_url = presenter_slug ? lcp_ruby.export_fields_path(lcp_slug: presenter_slug) : nil
+      profiles_url = presenter_slug ? lcp_ruby.export_profiles_path(lcp_slug: presenter_slug) : nil
+
+      content_tag(:div, class: "lcp-field-picker-wrapper",
+        data: {
+          controller: "lcp-field-picker",
+          "lcp-field-picker-source-presenter-value" => source_presenter,
+          "lcp-field-picker-fields-url-value" => fields_url,
+          "lcp-field-picker-profiles-url-value" => profiles_url,
+          "lcp-field-picker-field-name-value" => "record[#{field_name}]"
+        }) do
+        # Profile dropdown
+        content_tag(:div, class: "lcp-field-picker-profile mb-2") do
+          content_tag(:label, I18n.t("lcp_ruby.export.load_profile_label", default: "Load profile"), class: "form-label") +
+          content_tag(:select, "", class: "form-select form-select-sm",
+            data: { "lcp-field-picker-target" => "profileSelect" })
+        end +
+        # Stale fields notice
+        content_tag(:div, "", class: "lcp-field-picker-stale-notice alert alert-warning small", hidden: true,
+          data: { "lcp-field-picker-target" => "staleNotice" }) +
+        # Hidden field for serialized selection
+        form.hidden_field(field_name, value: json_value,
+          data: { "lcp-field-picker-target" => "hiddenInput" }) +
+        # Field tree container
+        content_tag(:div, "", data: { "lcp-field-picker-target" => "tree" })
+      end
+    end
+
+    def render_import_mapper_input(form, field_name, field_config)
+      source_presenter = form.object&.respond_to?(:source_presenter) ? form.object.source_presenter : nil
+      source_presenter = params[:source_presenter] if source_presenter.blank? && params[:source_presenter].present?
+      # Fallback: read target_model from form object and find a presenter for it
+      if source_presenter.blank?
+        target_model = form.object&.respond_to?(:target_model) ? form.object.target_model : nil
+        if target_model.present?
+          # Find a presenter that has this model and import enabled
+          LcpRuby.loader.presenter_definitions.each do |_name, pdef|
+            if pdef.model == target_model && pdef.import_enabled?
+              source_presenter = pdef.name
+              break
+            end
+          end
+        end
+      end
+
+      presenter_def = source_presenter && LcpRuby.loader.presenter_definition(source_presenter)
+      presenter_slug = presenter_def&.slug ||
+        (presenter_def && Widgets::PresenterZoneResolver.routable_slug_for_model(presenter_def.model)) ||
+        source_presenter
+      fields_url = presenter_slug ? lcp_ruby.import_fields_path(lcp_slug: presenter_slug) : nil
+      profiles_url = presenter_slug ? lcp_ruby.import_profiles_path(lcp_slug: presenter_slug) : nil
+
+      source_headers = form.object&.respond_to?(:source_headers) ? form.object.source_headers : nil
+      headers_json = serialize_json_value(source_headers, "[]")
+
+      current_mapping = form.object&.respond_to?(field_name) ? form.object.send(field_name) : nil
+      mapping_json = serialize_json_value(current_mapping, "{}")
+
+      lookup_config = form.object&.respond_to?(:lookup_config) ? form.object.lookup_config : nil
+      lookup_json = serialize_json_value(lookup_config, "{}")
+
+      content_tag(:div, class: "lcp-import-mapper-wrapper",
+        data: {
+          controller: "lcp-import-mapper",
+          "lcp-import-mapper-fields-url-value" => fields_url,
+          "lcp-import-mapper-profiles-url-value" => profiles_url,
+          "lcp-import-mapper-source-headers-value" => headers_json,
+          "lcp-import-mapper-field-name-value" => "record[#{field_name}]",
+          "lcp-import-mapper-lookup-field-name-value" => "record[lookup_config]"
+        }) do
+        # Profile dropdown
+        content_tag(:div, class: "lcp-import-mapper-profile mb-2") do
+          content_tag(:label, I18n.t("lcp_ruby.import.load_profile_label", default: "Load profile"), class: "form-label") +
+          content_tag(:select, "", class: "form-select form-select-sm",
+            data: { "lcp-import-mapper-target" => "profileSelect" })
+        end +
+        # Hidden fields for serialized mapping and lookup config
+        form.hidden_field(field_name, value: mapping_json,
+          data: { "lcp-import-mapper-target" => "mappingInput" }) +
+        form.hidden_field(:lookup_config, value: lookup_json,
+          data: { "lcp-import-mapper-target" => "lookupInput" }) +
+        # Mapping table container
+        content_tag(:div, "", class: "lcp-import-mapper-table",
+          data: { "lcp-import-mapper-target" => "table" })
+      end
+    end
+
+    def render_formatting_options_input(form, field_name, _field_config)
+      current_value = form.object&.respond_to?(field_name) ? form.object.send(field_name) : nil
+      opts = case current_value
+      when Hash then current_value.transform_keys(&:to_s)
+      when String then (JSON.parse(current_value) rescue {}).transform_keys(&:to_s)
+      else {}
+      end
+
+      content_tag(:div, class: "lcp-formatting-options-body") do
+        formatting_option_select(
+          "enum_mode", opts,
+          I18n.t("lcp_ruby.export.enum_mode_label", default: "Enum values"),
+          [
+            [ I18n.t("lcp_ruby.export.enum_mode_label_option", default: "Human label"), "label" ],
+            [ I18n.t("lcp_ruby.export.enum_mode_key_option", default: "Raw key"), "key" ],
+            [ I18n.t("lcp_ruby.export.enum_mode_both_option", default: "Key | Label"), "both" ]
+          ],
+          "label"
+        ) +
+        formatting_option_select(
+          "date_format", opts,
+          I18n.t("lcp_ruby.export.date_format_label", default: "Date format"),
+          [
+            [ I18n.t("lcp_ruby.export.date_format_iso8601", default: "ISO 8601"), "iso" ],
+            [ I18n.t("lcp_ruby.export.locale_format", default: "Locale format"), "locale" ]
+          ],
+          "iso"
+        ) +
+        formatting_option_select(
+          "datetime_format", opts,
+          I18n.t("lcp_ruby.export.datetime_format_label", default: "Datetime format"),
+          [
+            [ I18n.t("lcp_ruby.export.date_format_iso8601", default: "ISO 8601"), "iso" ],
+            [ I18n.t("lcp_ruby.export.locale_format", default: "Locale format"), "locale" ],
+            [ I18n.t("lcp_ruby.export.date_format_epoch", default: "Unix epoch"), "epoch" ]
+          ],
+          "iso"
+        ) +
+        formatting_option_select(
+          "boolean_mode", opts,
+          I18n.t("lcp_ruby.export.boolean_mode_label", default: "Boolean values"),
+          [
+            [ I18n.t("lcp_ruby.export.boolean_true_false", default: "true / false"), "true_false" ],
+            [ I18n.t("lcp_ruby.export.boolean_yes_no", default: "Yes / No"), "yes_no" ],
+            [ I18n.t("lcp_ruby.export.boolean_one_zero", default: "1 / 0"), "one_zero" ]
+          ],
+          "true_false"
+        ) +
+        formatting_option_select(
+          "decimal_separator", opts,
+          I18n.t("lcp_ruby.export.decimal_separator_label", default: "Decimal separator"),
+          [
+            [ I18n.t("lcp_ruby.export.decimal_dot", default: ". (dot)"), "." ],
+            [ I18n.t("lcp_ruby.export.decimal_comma", default: ", (comma)"), "," ]
+          ],
+          "."
+        )
+      end
+    end
+
+    def formatting_option_select(key, current_opts, label, choices, default)
+      selected = current_opts[key] || default
+      content_tag(:div, class: "mb-2") do
+        content_tag(:label, label, class: "form-label small", for: "record_formatting_options_#{key}") +
+        select_tag("record[formatting_options][#{key}]",
+          options_for_select(choices, selected),
+          class: "form-select form-select-sm",
+          id: "record_formatting_options_#{key}")
+      end
+    end
+
+    def serialize_json_value(value, default = "{}")
+      case value
+      when Hash, Array then value.to_json
+      when String then value
+      else default
+      end
+    end
+
+    def pretty_print_json_value(value)
+      raw = value.is_a?(String) ? value : value.to_json
+      parsed = JSON.parse(raw)
+      JSON.pretty_generate(parsed)
+    rescue JSON::ParserError
+      value.to_s
+    end
+
+    def form_action_label(action, record, presenter_name)
+      if action["label"].present?
+        return action["label"]
+      end
+
+      # Presenter-specific override always wins (lets configurators rename
+      # built_in save/cancel for a specific form, e.g. "Generate Token").
+      presenter_key = "lcp_ruby.presenters.#{presenter_name}.actions.form.#{action["name"]}"
+      presenter_value = I18n.t(presenter_key, default: nil)
+      return presenter_value if presenter_value.present?
+
+      if action["type"] == "built_in" && action["name"] == "save"
+        record.new_record? ? I18n.t("lcp_ruby.form.create") : I18n.t("lcp_ruby.form.update")
+      else
+        I18n.t("lcp_ruby.actions.form.#{action["name"]}", default: action["name"].humanize)
+      end
+    end
+
+    # In-progress label shown on the submit button while the form is submitting.
+    # Resolution order: explicit action["submitting_label"] → presenter-specific
+    # i18n key → global i18n key → final "Working…" default.
+    def submitting_label_for(action, presenter_name)
+      return action["submitting_label"] if action["submitting_label"].present?
+
+      name = action["name"].to_s
+      I18n.t("lcp_ruby.presenters.#{presenter_name}.form.submitting.#{name}",
+        default: I18n.t("lcp_ruby.form.submitting.#{name}",
+          default: I18n.t("lcp_ruby.form.submitting.default", default: "Working…")))
+    end
+
+    def current_model_name
+      current_model_definition&.name if respond_to?(:current_model_definition)
+    end
+  end
+end