has_helpers 5.0.2

data/app/commands/has_helpers/cards/card_data_command.rb

@@ -0,0 +1,1062 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    # Command object that resolves the effective card configuration
+    # (card + fields) for a given role/resource/identifier/record combo and
+    # returns serialized data for GraphQL or other consumers.
+    #
+    # Usage:
+    #   result = HasHelpers::Cards::CardDataCommand.call(
+    #     role_id:       role_id,
+    #     resource_id:   resource_id,
+    #     identifier_id: identifier_id,
+    #     record_id:     record_id
+    #   )
+    #
+    # Usage (optimized API, receives a preloaded record to avoid N+1):
+    #   result = HasHelpers::Cards::CardDataCommand.call_with_record(
+    #     role_id:       role_id,
+    #     resource_id:   resource,        # HasHelpers::Resource instance or id
+    #     identifier_id: identifier,      # HasHelpers::Cards::CardIdentifier instance or id
+    #     record:        record           # ActiveRecord instance
+    #   )
+    #
+    #   result.card    # => Hash
+    #   result.fields  # => Array<Hash>
+    #   result.entries # => Array<Hash>
+    class CardDataCommand
+      Response = Struct.new(:card, :fields, :entries, keyword_init: true) # rubocop:disable Lint/StructNewOverride
+      MAPPER_NOT_APPLIED = Object.new
+
+      # Public entry point: original API, keeps backward compatibility.
+      # It receives record_id and will load the record internally.
+      def self.call(role_id:, resource_id:, identifier_id:, record_id:)
+        new(
+          role_id:       role_id,
+          resource_id:   resource_id,
+          identifier_id: identifier_id,
+          record_id:     record_id
+        ).call
+      end
+
+      # Public entry point: optimized variant that receives a preloaded record.
+      # This avoids doing resource.klass.find(record_id) for each card.
+      def self.call_with_record(role_id:, resource_id:, identifier_id:, record:)
+        new(
+          role_id:       role_id,
+          resource_id:   resource_id,
+          identifier_id: identifier_id,
+          record:        record
+        ).call
+      end
+
+      # Public entry point: hover-only cards live entirely in-memory.
+      # Caller supplies a pre-built (unpersisted) CardDefinition + preloaded record;
+      # no DB lookup for the definition is performed, and role customization is skipped.
+      def self.call_with_definition(resource_id:, card_definition:, record:)
+        new(
+          role_id:         nil,
+          resource_id:     resource_id,
+          identifier_id:   card_definition.identifier,
+          record:          record,
+          card_definition: card_definition
+        ).call
+      end
+
+      # Constructor supports both styles:
+      #   - record_id only (classic)
+      #   - record only (preloaded)
+      #   - or both, but record takes precedence when present.
+      def initialize(role_id:, resource_id:, identifier_id:, record_id: nil, record: nil, card_definition: nil)
+        @role            = ::HasHelpers::Role.find_by(id: role_id)
+        @resource        = find_resource(resource_id)
+        # Hover-only definitions are passed in-memory; we don't look up the CardIdentifier
+        # option in the DB for those (the identifier may just be a plain string).
+        @identifier      = card_definition ? identifier_id : find_identifier(identifier_id)
+        @record_id       = record_id
+        @record          = record
+        @card_definition = card_definition
+      end
+
+      def call
+        card_definition    = @card_definition || find_card_definition!
+        registry_card      = registry_card_for(card_definition)
+        role_resource_card = @card_definition ? nil : find_role_resource_card(card_definition)
+
+        card_visible  = resolve_card_visibility(card_definition, role_resource_card)
+        card_position = resolve_card_position(card_definition, role_resource_card)
+
+        # Build field configs with all metadata in memory.
+        field_configs = build_field_configs(card_definition, role_resource_card, registry_card)
+
+        # If the card is hidden for this role, we only return the card metadata.
+        return Response.new(
+          card:    serialize_card(card_definition, card_visible, card_position),
+          fields:  [],
+          entries: []
+        ) unless card_visible
+
+        # In hover-only mode the parent record IS the target — no relationship navigation.
+        relationship = @card_definition ? nil : relationship_for(card_definition, registry_card)
+
+        targets = target_records(
+          load_record,
+          relationship,
+          scope_for(card_definition, registry_card),
+          expansion_scope_for(card_definition, registry_card),
+          registry_card
+        )
+
+        Response.new(
+          card:    serialize_card(card_definition, card_visible, card_position),
+          fields:  serialize_fields(field_configs),
+          entries: build_entries(targets, field_configs, registry_card)
+        )
+      end
+
+      private
+
+      attr_reader :role, :resource, :identifier, :record_id
+
+      # Basics lookups
+      def find_resource(resource_or_id)
+        return resource_or_id if resource_or_id.is_a?(::HasHelpers::Resource)
+
+        ::HasHelpers::Resource.find(resource_or_id)
+      end
+
+      def find_identifier(identifier_or_id)
+        return identifier_or_id if identifier_or_id.is_a?(::HasHelpers::Cards::CardIdentifier)
+
+        ::HasHelpers::Cards::CardIdentifier.find(identifier_or_id)
+      end
+
+      def find_card_definition!
+        ::HasHelpers::Cards::CardDefinition.
+          joins(:card_definition_resources).
+          where(identifier_id: identifier.id, card_definition_resources: { resource_id: resource.id }).
+          first! # unique per identifier/resource
+      end
+
+      def find_role_resource_card(card_definition)
+        ::HasHelpers::Cards::RoleResourceCard.find_by(
+          role_id:            role&.id,
+          resource_id:        resource.id,
+          card_definition_id: card_definition.id,
+          organization_id:    role&.organization_id
+        )
+      end
+
+      # Visibility resolution
+      def resolve_card_visibility(card_definition, role_resource_card)
+        return !!card_definition.default_visibility unless role_resource_card
+
+        # bi_state_boolean columns default to true, but nil means "inherit"
+        role_resource_card.is_visible.nil? ? true : role_resource_card.is_visible
+      end
+
+      def resolve_card_position(card_definition, role_resource_card)
+        role_resource_card&.position || card_definition.position
+      end
+
+      # Configuration of fields (meta)
+      def build_field_configs(card_definition, role_resource_card, _registry_card)
+        overrides = role_resource_card ? role_resource_card.role_card_fields.index_by(&:card_field_id) : {}
+        registry_map = registry_field_map_for(card_definition)
+
+        fields_scope =
+          if card_definition.new_record?
+            card_definition.card_fields
+          else
+            card_definition.card_fields.includes(:field_resource, :data_type)
+          end
+
+        fields_scope.
+          map do |field|
+            override      = overrides[field.id]
+            visible       = resolve_field_visibility(field, override)
+            position      = override&.position || field.default_position
+            registry_meta = registry_map[field_identity(field)]
+
+            next unless visible
+
+            source_meta = registry_meta && registry_meta[:source]
+
+            {
+              card_field: field,
+              key:        effective_field_key(field),
+              label:      effective_field_label(field, registry_meta),
+              data_type:  field.data_type.name.underscore.to_sym,
+              required:   !!field.is_required,
+              position:   position || 0,
+              mapper:     registry_meta && registry_meta[:mapper],
+              kind:       registry_meta && registry_meta[:kind] ? registry_meta[:kind].to_sym : inferred_field_kind(field),
+              source:     source_meta,
+              hover_card: registry_meta && registry_meta[:hover_card],
+              hover_card_source: registry_meta && registry_meta[:hover_card_source],
+              hover_record_source: registry_meta && registry_meta[:hover_record_source],
+              hover_resource: registry_meta && registry_meta[:hover_resource],
+              hover_resource_source: registry_meta && registry_meta[:hover_resource_source],
+              icon:       registry_meta && registry_meta[:icon],
+              badge_color: resolve_badge_color_source(field, registry_meta),
+              url_resolver: resolve_url_resolver_source(field, registry_meta),
+              custom_label: registry_meta && !!registry_meta[:custom_label],
+              custom_label_key: registry_meta && registry_meta[:custom_label_key].presence
+            }
+          end.
+          compact.
+          sort_by { |cfg| [cfg[:position], cfg[:key].to_s] }
+      end
+
+      def resolve_field_visibility(field, override)
+        return override.is_visible unless override&.is_visible.nil?
+
+        # default_visibility is bi_state_boolean, nil means visible by default
+        field.default_visibility != false
+      end
+
+      # Identity for mapping with the registry and with overrides
+      #   [:custom, "DEMOGRAPHICS_FULL_NAME"]
+      #   [:resource, "age"]
+      def field_identity(field)
+        if field.respond_to?(:field_resource) && field.field_resource.present?
+          [:resource, field.field_resource&.name.to_s]
+        elsif field.respond_to?(:virtual_ref) && field.virtual_ref.present?
+          [:virtual, field.virtual_ref.to_s]
+        else
+          [:custom, normalized_custom_key(field)]
+        end
+      end
+
+      def effective_field_key(field)
+        has_resource =
+          if field.respond_to?(:field_resource_id)
+            field.field_resource_id.present?
+          elsif field.respond_to?(:field_resource)
+            field.field_resource.present?
+          else
+            false
+          end
+
+        if has_resource
+          field.field_resource&.name&.to_sym
+        elsif field.respond_to?(:virtual_ref) && field.virtual_ref.present?
+          field.virtual_ref.to_sym
+        else
+          normalized_custom_key(field)&.to_sym
+        end
+      end
+
+      def effective_field_label(field, registry_meta = nil)
+        return field.field_custom_name if field.field_custom_name.present?
+        return registry_meta[:name] if registry_meta && registry_meta[:name].present?
+
+        resource = field.field_resource
+        label = resource&.alias_name.presence || resource&.name
+        label ? label.to_s.humanize.titleize : nil
+      end
+
+      def inferred_field_kind(field)
+        has_resource =
+          if field.respond_to?(:field_resource_id)
+            field.field_resource_id.present?
+          elsif field.respond_to?(:field_resource)
+            field.field_resource.present?
+          else
+            false
+          end
+
+        return :resource if has_resource
+        return :virtual if field.respond_to?(:virtual_ref) && field.virtual_ref.present?
+
+        :custom
+      end
+
+      def normalized_custom_key(field)
+        raw = field.respond_to?(:field_custom_name) ? field.field_custom_name : nil
+        return nil if raw.blank?
+
+        raw.to_s.strip.gsub(/\s+/, "_").underscore
+      end
+
+      # Accepts a CardIdentifier option (DB-backed, has an id) or an unsaved/in-memory
+      # one used by hover-only cards (no id — fall back to name).
+      def serialize_identifier(identifier_value)
+        return nil if identifier_value.nil?
+        if identifier_value.respond_to?(:id) && identifier_value.id
+          identifier_value.id
+        elsif identifier_value.respond_to?(:name) && identifier_value.name
+          identifier_value.name.to_s
+        else
+          identifier_value.to_s
+        end
+      end
+
+      # Serialize card metadata
+      def serialize_card(card_definition, visible, position)
+        {
+          id:           card_definition.id,
+          name:         card_definition.name,
+          identifier:   serialize_identifier(card_definition.identifier),
+          layout:       card_definition.layout_type.name.downcase.to_sym,
+          variant:      card_definition.variant&.name&.downcase&.to_sym,
+          description:  card_definition.description,
+          position:     position,
+          visible:      visible
+        }
+      end
+
+      def serialize_fields(field_configs)
+        field_configs.map do |cfg|
+          {
+            id:        cfg[:card_field].id,
+            key:       cfg[:key],
+            label:     cfg[:label],
+            data_type: cfg[:data_type],
+            required:  cfg[:required],
+            position:  cfg[:position],
+            custom_label_key: cfg[:custom_label_key]
+          }
+        end
+      end
+
+      def build_entries(targets, field_configs, registry_card)
+        targets.flat_map do |target|
+          data_sources = data_source_payloads(target, registry_card)
+
+          # If any data source returns an Array, treat each element as a separate entry.
+          _array_ds_key, array_ds_values = data_sources.find { |_k, v| v.is_a?(Array) }
+
+          if array_ds_values
+            array_ds_values.map do |element|
+              entry_sources = data_sources.transform_values do |v|
+                v.is_a?(Array) ? element : v
+              end
+
+              {
+                record_id: safe_id(target),
+                fields:    render_fields(target, field_configs, entry_sources, registry_card)
+              }
+            end
+          else
+            {
+              record_id: safe_id(target),
+              fields:    render_fields(target, field_configs, data_sources, registry_card)
+            }
+          end
+        end
+      end
+
+      def data_source_payloads(target, registry_card)
+        return {} unless registry_card && registry_card[:data_sources].present?
+
+        @data_source_cache ||= {}
+        cache_key = [registry_card[:identifier], target.object_id].join(":")
+        return @data_source_cache[cache_key] if @data_source_cache.key?(cache_key)
+
+        payloads = {}
+        registry_card[:data_sources].each do |ds|
+          resolver = ds[:resolver]
+          next unless resolver.respond_to?(:call)
+
+          payloads[ds[:name].to_sym] =
+            if resolver.arity == 2
+              resolver.call(target, data_source_context)
+            else
+              resolver.call(target)
+            end
+        end
+
+        @data_source_cache[cache_key] = payloads
+      end
+
+      def render_fields(target, field_configs, data_sources, registry_card)
+        field_configs.map do |cfg|
+          value, url, badge_color_override = resolve_field_value_and_url(target, cfg, data_sources, registry_card)
+
+          custom_label =
+          if cfg[:kind].to_sym == :virtual && cfg[:custom_label] && cfg[:custom_label_key].present?
+            dig_any(data_sources, cfg[:custom_label_key])
+          end
+
+          field_hash = {
+            id:    cfg[:card_field].id,
+            label: cfg[:label],
+            value: value
+          }
+
+          field_hash[:icon] = cfg[:icon] if cfg[:icon].present?
+
+          # Emit url for link fields and for hover_card fields (so the trigger can also
+          # act as a clickable link to the target record).
+          field_hash[:url] = url if link_field?(cfg[:card_field]) || hover_card_field?(cfg)
+          if badge_field?(cfg[:card_field])
+            field_hash[:badge_color] = badge_color_override || resolve_badge_color(cfg, value)
+          end
+
+          if hover_card_field?(cfg) || cfg[:hover_card].present? || cfg[:hover_card_source].present?
+            hover_meta = resolve_hover_metadata(target, cfg, data_sources, value)
+            field_hash[:hover_card_identifier] = hover_meta[:identifier]
+            field_hash[:hover_target_resource] = hover_meta[:resource_name]
+            field_hash[:hover_target_record_id] = hover_meta[:record_id]
+          elsif link_field?(cfg[:card_field]) && hover_config_blank?(cfg)
+            # Link fields with no explicit hover config: infer a hover card by
+            # convention when an <Resource>InfoCard hover-only card exists in
+            # the registry. Falls back to a plain link when nothing matches.
+            inferred = infer_link_hover_metadata(cfg, value, raw_value_for_link(target, cfg, data_sources))
+            if inferred
+              field_hash[:hover_card_identifier] = inferred[:identifier]
+              field_hash[:hover_target_resource] = inferred[:resource_name]
+              field_hash[:hover_target_record_id] = inferred[:record_id]
+            end
+          end
+
+          if badge_list_field?(cfg)
+            field_hash[:value]  = nil
+            field_hash[:badges] = resolve_badge_list(value)
+          end
+
+          field_hash[:custom_label] = custom_label.to_s if custom_label.present?
+
+          field_hash
+        end
+      end
+
+      def resolve_field_value_and_url(target, cfg, data_sources, registry_card)
+        return [nil, nil, nil] unless target
+
+        field     = cfg[:card_field]
+        attr_name = field_attribute_name(field)
+        raw_value = resolve_raw_field_value(target, cfg, attr_name, data_sources, registry_card)
+
+        hash_payload =
+          case raw_value
+          when Hash
+            raw_value.symbolize_keys
+          when ActionController::Parameters
+            # Parameters may be unpermitted; we explicitly opt into a safe hash for serialization.
+            raw_value.to_unsafe_h.symbolize_keys
+          end
+
+        value_from_hash = hash_payload&.key?(:value) ? hash_payload[:value] : raw_value
+        value           = jsonify_value(option_name_or_value(value_from_hash))
+
+        url_override    = hash_payload&.[](:url) || hash_payload&.[](:href)
+        badge_override  = hash_payload&.[](:badge_color) || hash_payload&.[](:badgeColor)
+
+        url = url_override || resolve_url(field, cfg, raw_value, value, attr_name)
+
+        [value, url, badge_override]
+      end
+
+      def field_attribute_name(field)
+        if field.field_resource
+          field.field_resource.alias_name.presence || field.field_resource.name
+        elsif field.respond_to?(:virtual_ref) && field.virtual_ref.present?
+          field.virtual_ref
+        elsif field.field_custom_name.present?
+          field.field_custom_name.to_s.strip.gsub(/\s+/, "_").underscore
+        end
+      end
+
+      def resolve_raw_field_value(target, cfg, attr_name, data_sources, _registry_card)
+        return nil unless target
+
+        source_value = resolve_source_value(target, cfg, data_sources)
+        return source_value unless source_value.equal?(MAPPER_NOT_APPLIED)
+
+        mapped_value = resolve_mapper_value(target, cfg[:mapper])
+        return mapped_value unless mapped_value.equal?(MAPPER_NOT_APPLIED)
+
+        # 2) Fallback: direct reading from the model
+        field = cfg[:card_field]
+        # byebug if field.data_type_id == HasHelpers::Cards::CardDataType::LINK.id
+        if field.field_resource && attr_name.present?
+          attr_str = attr_name.to_s
+
+          # For *_id, try to use the association first
+          if attr_str.end_with?("_id")
+            assoc_method = attr_str.delete_suffix("_id")
+            if target.respond_to?(assoc_method)
+              associated = target.public_send(assoc_method)
+              return associated if associated
+            end
+
+            return target.public_send(attr_str) if target.respond_to?(attr_str)
+          else
+            if target.respond_to?(attr_str)
+              return target.public_send(attr_str)
+            end
+          end
+        elsif field.field_custom_name.present? && attr_name.present?
+          return target.public_send(attr_name) if target.respond_to?(attr_name)
+
+          # Fallbacks: use cfg key variants in case attr_name normalization differs
+          if cfg[:key]
+            key_str = cfg[:key].to_s
+            return target.public_send(key_str) if target.respond_to?(key_str)
+            key_underscored = key_str.underscore
+            return target.public_send(key_underscored) if target.respond_to?(key_underscored)
+          end
+        end
+
+        nil
+      end
+
+      def resolve_mapper_value(target, mapper)
+        return MAPPER_NOT_APPLIED if mapper.blank?
+
+        mapper_class =
+          mapper.to_s.safe_constantize ||
+          ::HasHelpers::ApplicationHelper.translate_klass(mapper.to_s)
+        if mapper_class.respond_to?(:call)
+          mapper_class.call(target)
+        elsif mapper_class && mapper_class.instance_methods(false).include?(:call)
+          mapper_instance =
+            begin
+              mapper_class.new(target)
+            rescue ArgumentError
+              mapper_class.new
+            end
+
+          call_method = mapper_instance.method(:call)
+          call_method.arity.zero? ? mapper_instance.call : mapper_instance.call(target)
+        else
+          MAPPER_NOT_APPLIED
+        end
+      end
+
+      def resolve_source_value(target, cfg, data_sources)
+        source = cfg[:source]
+        return MAPPER_NOT_APPLIED if source.blank?
+
+        if source[:from] && data_sources
+          payload = data_sources[source[:from].to_sym]
+          if payload
+            return payload if source[:key].blank?
+            if payload.respond_to?(:key?)
+              return payload[source[:key].to_sym] if payload.key?(source[:key].to_sym)
+              return payload[source[:key].to_s] if payload.key?(source[:key].to_s)
+            elsif payload.respond_to?(:[])
+              return payload[source[:key].to_sym]
+            end
+          end
+        end
+
+        if source[:mapper]
+          mapped = resolve_mapper_value(target, source[:mapper])
+          return mapped unless mapped.equal?(MAPPER_NOT_APPLIED)
+        end
+
+        proc_source = source[:proc]
+        if proc_source.respond_to?(:call)
+          return proc_source.arity == 1 ? proc_source.call(target) : proc_source.call(target, data_source_context)
+        end
+
+        MAPPER_NOT_APPLIED
+      end
+
+      def link_field?(field)
+        return false unless field&.data_type_id
+
+        link_id  = ::HasHelpers::Cards::CardDataType::LINK.id
+        title_id = ::HasHelpers::Cards::CardDataType::TITLE.id
+
+        field.data_type_id == link_id || field.data_type_id == title_id
+      end
+
+      def resolve_url(field, cfg, raw_value, value, attr_name)
+        return nil unless link_field?(field) || hover_card_field?(cfg)
+
+        if cfg[:url_resolver].respond_to?(:call)
+          return cfg[:url_resolver].call(cfg, field, raw_value, value)
+        end
+
+        value.present? ? build_link_url(raw_value, attr_name, field) : nil
+      end
+
+      def badge_field?(field)
+        field.data_type_id == ::HasHelpers::Cards::CardDataType::BADGE.id
+      end
+
+      def hover_card_field?(cfg)
+        cfg[:data_type].to_sym == :hover_card
+      end
+
+      # Default record-id source for a hover_card field with no explicit hover_record_source.
+      # Reads the raw column off `target` (e.g. `target.carrier_id`).
+      def default_hover_record_value(target, cfg)
+        return nil unless target
+
+        field = cfg[:card_field]
+        attr_name =
+          if field.respond_to?(:field_resource) && field.field_resource
+            field.field_resource.name.to_s
+          elsif field.respond_to?(:virtual_ref) && field.virtual_ref.present?
+            field.virtual_ref.to_s
+          end
+        return nil if attr_name.blank?
+        return nil unless target.respond_to?(attr_name)
+
+        target.public_send(attr_name)
+      end
+
+      BADGE_THEMES = %w[default yellow green red redBackground blue purple sky pink orange].freeze
+
+      def badge_list_field?(cfg)
+        cfg[:data_type].to_sym == :badge_list
+      end
+
+      def resolve_badge_list(raw_value)
+        return [] unless raw_value.is_a?(Array)
+
+        raw_value.map do |entry|
+          hash =
+            case entry
+            when Hash then entry.symbolize_keys
+            when ActionController::Parameters then entry.to_unsafe_h.symbolize_keys
+            else next nil
+            end
+          label = hash[:label].to_s
+          next nil if label.empty?
+
+          color = hash[:color].to_s
+          { label: label, color: BADGE_THEMES.include?(color) ? color : "default" }
+        end.compact
+      end
+
+      def resolve_hover_metadata(target, cfg, data_sources, _field_value = nil)
+        null_hover_metadata = { identifier: nil, resource_name: nil, record_id: nil }
+        resolved_cfg = resolve_dynamic_hover_keys(target, cfg, data_sources)
+        resource_name, hover_identifier = canonicalize_hover_target(resolved_cfg)
+        return null_hover_metadata unless hover_identifier
+
+        # If the DSL provides an explicit `hover_record_source`, resolve through it.
+        # Otherwise, fall back to reading the raw column off the target (e.g. for
+        # `field :carrier_id, data_type: HOVER_CARD` we read `target.carrier_id`).
+        hover_value =
+          if resolved_cfg[:hover_record_source].present?
+            resolve_source_value(
+              target,
+              resolved_cfg.merge(source: resolved_cfg[:hover_record_source]),
+              data_sources
+            )
+          else
+            default_hover_record_value(target, resolved_cfg)
+          end
+
+        return null_hover_metadata if hover_value.nil? || hover_value.equal?(MAPPER_NOT_APPLIED)
+
+        payload =
+          case hover_value
+          when Hash
+            hover_value.symbolize_keys
+          when ActionController::Parameters
+            hover_value.to_unsafe_h.symbolize_keys
+          end
+
+        record_id =
+          if payload
+            payload[:record_id] || payload[:id]
+          elsif hover_value.respond_to?(:id)
+            hover_value.id
+          else
+            hover_value
+          end
+
+        # Payload may carry an explicit resource_name (e.g. polymorphic case
+        # where the data_source returns { resource_name:, record_id: }). Prefer
+        # that over the cfg-derived value when present.
+        resolved_resource_name = (payload && payload[:resource_name].presence) || resource_name
+
+        {
+          identifier:    hover_identifier,
+          resource_name: resolved_resource_name,
+          record_id:     record_id
+        }
+      end
+
+      # If the DSL provides `hover_card_source` / `hover_resource_source`, resolve those
+      # against the data sources and substitute into a copy of the cfg so downstream
+      # logic can treat them as if they were static `hover_card` / `hover_resource`.
+      def resolve_dynamic_hover_keys(target, cfg, data_sources)
+        hover_card = cfg[:hover_card]
+        hover_resource = cfg[:hover_resource]
+
+        if cfg[:hover_card_source].present?
+          dynamic = resolve_source_value(
+            target,
+            cfg.merge(source: cfg[:hover_card_source]),
+            data_sources
+          )
+          hover_card = dynamic.to_s if dynamic.present? && !dynamic.equal?(MAPPER_NOT_APPLIED)
+        end
+
+        if cfg[:hover_resource_source].present?
+          dynamic = resolve_source_value(
+            target,
+            cfg.merge(source: cfg[:hover_resource_source]),
+            data_sources
+          )
+          hover_resource = dynamic.to_s if dynamic.present? && !dynamic.equal?(MAPPER_NOT_APPLIED)
+        end
+
+        cfg.merge(hover_card: hover_card, hover_resource: hover_resource)
+      end
+
+      # True when the dev provided no hover_* config at all on this field, so
+      # we're free to infer one from convention.
+      def hover_config_blank?(cfg)
+        cfg[:hover_card].blank? &&
+          cfg[:hover_card_source].blank? &&
+          cfg[:hover_resource].blank? &&
+          cfg[:hover_resource_source].blank?
+      end
+
+      # Re-derive raw_value cheaply for inference. (We don't have it in scope
+      # from resolve_field_value_and_url after the splat, so this is the same
+      # path that resolves through the source/mapper/attribute fallback chain.)
+      def raw_value_for_link(target, cfg, data_sources)
+        resolve_raw_field_value(target, cfg, field_attribute_name(cfg[:card_field]), data_sources, nil)
+      end
+
+      # Infer hover metadata for a plain link field by checking whether the
+      # registry has a `<Resource>InfoCard` hover-only card for the resource
+      # class the link points at. Returns nil when the resource class can't
+      # be determined or no matching hover card exists.
+      def infer_link_hover_metadata(cfg, _value, raw_value)
+        record_id = extract_link_record_id(raw_value)
+        return nil if record_id.blank?
+
+        klass = infer_link_klass(raw_value, cfg)
+        return nil unless klass
+
+        identifier = "#{klass.name.demodulize}InfoCard"
+        registry_card = find_hover_only_registry_card(identifier)
+        return nil unless registry_card
+
+        {
+          identifier:    identifier,
+          resource_name: klass.name.to_s,
+          record_id:     record_id
+        }
+      end
+
+      # Determine the AR class the link is pointing at — same priority order
+      # as link_path_segment: virtual_ref instance class → field_resource
+      # klass → attr_name-as-class.
+      def infer_link_klass(raw_value, cfg)
+        field = cfg[:card_field]
+        if raw_value && !primitive_link_value?(raw_value) && raw_value.class.respond_to?(:base_class)
+          return raw_value.class.base_class
+        end
+
+        if field.respond_to?(:field_resource) && field.field_resource.present?
+          name = field.field_resource.field_class_name
+          klass = name && (name.safe_constantize || ::HasHelpers::ApplicationHelper.translate_klass(name))
+          return klass if klass
+        end
+
+        attr_name = field_attribute_name(field)
+        if attr_name.present?
+          guess = attr_name.to_s.delete_suffix("_id").camelize
+          klass = guess.safe_constantize || ::HasHelpers::ApplicationHelper.translate_klass(guess)
+          return klass if klass
+        end
+
+        nil
+      end
+
+      def find_hover_only_registry_card(identifier_name)
+        @hover_only_cards_by_identifier ||=
+          ::HasHelpers::Cards::Registry.cards.each_with_object({}) do |card, memo|
+            next unless card[:hover_only]
+            id = card[:identifier]
+            id_str = id.respond_to?(:name) && !id.is_a?(String) ? id.name.to_s : id.to_s
+            memo[id_str] = card
+          end
+        @hover_only_cards_by_identifier[identifier_name.to_s]
+      end
+
+      # The builder may derive `:created_by_id` → `hover_resource: "CreatedBy"` from the column
+      # name, but "CreatedBy" is not always a real class (it's the role on Policy). When that's
+      # the case we fall back to the application's klass translator (e.g. iamhq maps
+      # "CreatedBy" → `HasHelpers::User`) and rewrite both `hover_resource` and `hover_card`
+      # to point at the real class.
+      def canonicalize_hover_target(cfg)
+        resource_name = cfg[:hover_resource].presence
+        identifier = cfg[:hover_card].presence
+        return [resource_name, identifier] unless resource_name
+
+        klass = resource_name.safe_constantize ||
+                ::HasHelpers::ApplicationHelper.translate_klass(resource_name)
+        return [resource_name, identifier] unless klass
+
+        canonical = klass.name.to_s
+        # Rewrite identifier only if it was the convention-derived one (matches the original
+        # hover_resource), preserving explicit user values.
+        rewritten_identifier =
+          identifier == "#{resource_name}InfoCard" ? "#{canonical.demodulize}InfoCard" : identifier
+
+        [canonical, rewritten_identifier]
+      end
+
+      def build_link_url(raw_value, attr_name, field)
+        record_id = extract_link_record_id(raw_value)
+        path_segment = link_path_segment(raw_value, attr_name, field)
+
+        return nil unless record_id && path_segment
+
+        "/#{path_segment}/#{record_id}"
+      end
+
+      def extract_link_record_id(raw_value)
+        return raw_value if raw_value.is_a?(String) || raw_value.is_a?(Numeric)
+        return raw_value.id if raw_value.respond_to?(:id)
+
+        nil
+      end
+
+      def link_path_segment(raw_value, attr_name, field)
+        if field.respond_to?(:virtual_ref) && field.virtual_ref.present? &&
+          raw_value && !primitive_link_value?(raw_value)
+          return demodulized_plural(raw_value.class)
+        end
+
+        if field.field_resource.present?
+          klass_segment = field_resource_class_segment(field)
+          return klass_segment if klass_segment
+        end
+
+        source = attr_name.presence || field.field_resource&.name
+        if source.present?
+          return source.to_s.delete_suffix("_id").underscore.pluralize
+        end
+
+        return demodulized_plural(raw_value.class) if raw_value && !primitive_link_value?(raw_value)
+
+        nil
+      end
+
+      def field_resource_class_segment(field)
+        class_name = field.field_resource&.field_class_name
+        return nil if class_name.blank?
+
+        klass =
+          class_name.safe_constantize ||
+          ::HasHelpers::ApplicationHelper.translate_klass(class_name)
+        return demodulized_plural(klass) if klass
+
+        nil
+      end
+
+      def primitive_link_value?(value)
+        value.is_a?(String) || value.is_a?(Numeric) || value.is_a?(Symbol)
+      end
+
+      def demodulized_plural(klass)
+        return nil unless klass
+
+        base = klass.respond_to?(:base_class) ? klass.base_class : klass
+        base.name.demodulize.underscore.pluralize
+      end
+
+      def data_source_context
+        @data_source_context ||= Struct.new(:role, :resource, :identifier).new(role, resource, identifier)
+      end
+
+      def resolve_badge_color(cfg, value)
+        source = cfg[:badge_color]
+        color_value =
+          if source.respond_to?(:call)
+            source.call(cfg, value)
+          else
+            source
+          end
+
+        color_value.presence || ::Color::GREY.name
+      end
+
+      def resolve_badge_color_source(field, registry_meta)
+        return field.badge_color if field.respond_to?(:badge_color) && field.badge_color
+
+        registry_meta && registry_meta[:badge_color]
+      end
+
+      def resolve_url_resolver_source(field, registry_meta)
+        return field.url if field.respond_to?(:url) && field.url
+
+        registry_meta && registry_meta[:url]
+      end
+
+      def option_name_or_value(value)
+        return nil if value.nil?
+        return value.name if value.respond_to?(:name)
+
+        value
+      end
+
+      # Protection against infinite recursion: cap depth and degrade gracefully to string.
+      MAX_JSONIFY_DEPTH = 6
+
+      def jsonify_value(value, depth: 0)
+        return nil if value.nil?
+
+        # 1. Handling objects with ID (Models or RSpec Mocks)
+        return value.id if value.respond_to?(:id) && !value.is_a?(Class)
+
+        # 2. Primitive types: return as-is (strings, numbers, booleans)
+        case value
+        when String, Integer, Float, TrueClass, FalseClass
+          return value
+        when Symbol
+          return value.to_s
+        when BigDecimal
+          return value.to_f
+        when Time, Date, DateTime
+          return value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+        end
+
+        # 3. Security control against infinite recursion
+        return value.to_s if depth >= MAX_JSONIFY_DEPTH
+
+        # 4. Data structures: recursively jsonify Hashes, Arrays, and Parameters, with depth control
+        case value
+        when ActionController::Parameters
+          jsonify_value(value.to_unsafe_h, depth: depth + 1)
+        when Hash
+          value.each_with_object({}) do |(k, v), acc|
+            acc[k.to_s] = jsonify_value(v, depth: depth + 1)
+          end
+        when Array
+          value.map { |v| jsonify_value(v, depth: depth + 1) }
+        else
+          # Fallback for other objects: try as_json, but avoid infinite recursion if it returns self
+          if value.respond_to?(:as_json)
+            json_data = value.as_json
+            # Avoid infinite recursion if as_json returns the object itself
+            json_data.equal?(value) ? value.to_s : jsonify_value(json_data, depth: depth + 1)
+          else
+            value.to_s
+          end
+        end
+      end
+
+      # Record + relationship
+      def load_record
+        # Prefer a preloaded record when available (used by .call_with_record)
+        return @load_record if defined?(@load_record) && @load_record
+
+        if @record
+          @load_record = @record
+        elsif record_id.present?
+          @load_record = resource.klass.find(record_id)
+        else
+          raise ArgumentError, "CardDataCommand requires either record or record_id"
+        end
+      end
+
+      def target_records(record, relationship, scope, expansion_scope, _registry_card)
+        return Array.wrap(record) if relationship.blank?
+
+        assoc =
+          if record.respond_to?(relationship.to_s)
+            record.public_send(relationship.to_s)
+          elsif record.respond_to?(relationship.to_s.singularize)
+            record.public_send(relationship.to_s.singularize)
+          end
+
+        records = assoc.presence
+        records = apply_scope(records, scope)
+        records = apply_scope(records, expansion_scope)
+
+        Array.wrap(records.presence)
+      end
+
+      def apply_scope(records, scope)
+        return records if scope.blank?
+
+        if scope.respond_to?(:call)
+          case scope.arity
+          when 1 then scope.call(records)
+          when 2 then scope.call(records, data_source_context)
+          else scope.call(records)
+          end
+        elsif records.respond_to?(scope.to_s)
+          records.public_send(scope.to_s)
+        else
+          records
+        end
+      end
+
+      # Registry (HasHelpers::Cards::Registry)
+      def relationship_for(card_definition, registry_card = nil)
+        registry_card ||= registry_card_for(card_definition)
+        registry_card && registry_card[:relationship].presence
+      end
+
+      def expansion_scope_for(card_definition, registry_card = nil)
+        registry_card ||= registry_card_for(card_definition)
+        registry_card && registry_card[:expansion_scope].presence
+      end
+
+      def scope_for(card_definition, registry_card = nil)
+        registry_card ||= registry_card_for(card_definition)
+        registry_card && registry_card[:scope].presence
+      end
+
+      def registry_card_for(card_definition)
+        @registry_cards ||= ::HasHelpers::Cards::Registry.cards.index_by { |c| normalize_identifier(c[:identifier]) }
+        @registry_cards[normalize_identifier(card_definition.identifier)]
+      end
+
+      def registry_field_map_for(card_definition)
+        card = registry_card_for(card_definition)
+        return {} unless card
+
+        Array(card[:fields]).each_with_object({}) do |field_hash, memo|
+          identity =
+            case field_hash[:kind].to_sym
+            when :custom
+              [:custom, field_hash[:key].to_s.strip.gsub(/\s+/, "_").underscore]
+            when :virtual
+              [:virtual, field_hash[:ref].to_s]
+            else
+              [:resource, field_hash[:ref].to_s]
+            end
+
+          memo[identity] = field_hash
+        end
+      end
+
+      def normalize_identifier(identifier_value)
+        if identifier_value.respond_to?(:name) && !identifier_value.is_a?(String)
+          identifier_value.name.to_s
+        else
+          identifier_value.to_s
+        end
+      end
+
+      def safe_id(record)
+        record.respond_to?(:id) ? record.id : nil
+      end
+
+      def dig_any(obj, key)
+        # - "foo" (hash key)
+        # - "foo.bar.baz" (path)
+        # - symbol keys vs string keys
+        parts = key.to_s.split(".")
+        parts.reduce(obj) do |acc, k|
+          break nil if acc.nil?
+          if acc.is_a?(Hash)
+            acc[k] || acc[k.to_sym]
+          else
+            # optional: support OpenStruct
+            acc.respond_to?(k) ? acc.public_send(k) : nil
+          end
+        end
+      end
+    end
+  end
+end