has_helpers 5.0.2

data/app/models/has_helpers/cards/card_builder/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    module CardBuilder
+      class Base
+        class << self
+          # DSL macro:
+          #
+          # class FooCard < Base
+          #   application "AgenciesHQ"
+          # end
+          #
+          # - setter when name is provided
+          # - getter when called without args
+          def application(name = nil)
+            if name
+              @application_name = name.to_s
+            end
+            @application_name || (superclass.respond_to?(:application) ? superclass.application : nil)
+          end
+        end
+
+        # DSL entry point:
+        #
+        # class DemographicsCard < HasHelpers::Cards::CardBuilder::Base
+        #   define do
+        #     resources { add Advisor }
+        #     card "Demo", relationship: "demo", identifier: "CardIdentifier::DEMOGRAPHICS", layout: LayoutType::KEY_VALUE
+        #   end
+        # end
+        #
+        # This:
+        # - evaluates the DSL in a DefinitionContext
+        # - builds normalized hashes
+        # - stores them in .definitions
+        # - registers them in HasHelpers::Cards::Registry
+
+        def self.define(&block)
+          raise ArgumentError, "Block required for .define" unless block
+
+          @definition_block = block
+          @definitions = nil
+          HasHelpers::Cards::Registry.register_definition(owner: self, block: block)
+        end
+
+        def self.definitions
+          HasHelpers::Cards::Registry.ensure_definitions_for(self)
+          @definitions
+        end
+
+        def self.build_definitions_from(block)
+          context = DefinitionContext.new(self)
+          context.instance_eval(&block)
+          card_definitions = context.build_each
+
+          @definitions = card_definitions.map do |card_hash|
+            # propagate application from the card class (if set)
+            card_hash[:application] ||= application
+            # ensure identifier constant exists when derived (identifier is a name string here)
+            if card_hash[:identifier].present? && card_hash[:identifier].is_a?(String) &&
+               ::HasHelpers::Cards::CardIdentifier.respond_to?(:define_constant) &&
+               ::HasHelpers::Cards::CardIdentifier.respond_to?(:lookup) &&
+               ::HasHelpers::Cards::CardIdentifier.lookup(card_hash[:identifier]).nil?
+              ::HasHelpers::Cards::CardIdentifier.define_constant(card_hash[:identifier])
+            end
+            HasHelpers::Cards::Registry.register_card!(card_hash)
+            card_hash
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/cards/card_builder/card_definition_builder.rb

@@ -0,0 +1,486 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    module CardBuilder
+      class CardDefinitionBuilder
+        class ValidationError < StandardError; end
+
+        attr_reader :name,
+                    :identifier,
+                    :relationship,
+                    :relationship_klass,
+                    :scope,
+                    :layout_type,
+                    :virtual,
+                    :hover_only,
+                    :variant,
+                    :is_customizable,
+                    :default_visibility,
+                    :default_position,
+                    :resources,
+                    :fields,
+                    :data_sources,
+                    :expansion_scope,
+                    :custom_label,
+                    :custom_label_key,
+                    :icon_name,
+                    :icon_color
+
+        def initialize(name:, relationship:, relationship_klass:, identifier:, layout:, resources:, variant:, virtual:, hover_only:, is_customizable:, default_visibility:, default_position:, scope: nil, icon_name: nil, icon_color: nil, owner_class: nil)
+          @owner_class  = owner_class
+          @identifier   = identifier || derive_identifier!
+          @name         = name
+          @relationship = relationship
+          @relationship_klass = (relationship_klass && (relationship_klass.is_a?(Class) ? relationship_klass.name : relationship_klass.to_s)) || nil
+          @scope = scope
+          @layout_type = normalize_enum(layout)
+          @virtual = !!virtual
+          @hover_only = hover_only ? true : nil
+          @variant = variant && normalize_enum(variant)
+
+          # Optional, non-persisted presentation hints at the card level.
+          # They live in the registry (in-memory) only and are never written to
+          # card_definitions; consumers read them from the DSL registry.
+          @icon_name  = icon_name.presence
+          @icon_color = icon_color.presence
+
+          # Defaults at card level
+          @description        = nil
+          @is_customizable    = is_customizable
+          @default_visibility = default_visibility.nil? ? true : default_visibility
+          @default_position   = default_position
+
+          @resources = Array(resources).map { |r| r.respond_to?(:to_h) ? r.to_h : r }
+          @fields    = []
+          @data_sources = []
+          @expansions = []
+
+          @next_field_position = 10
+        end
+
+        # DSL:
+        #
+        # description "Basic details"
+        def description(text = nil)
+          # setter
+          @description = text.to_s if text
+          # getter
+          @description
+        end
+
+        # DSL:
+        #
+        # field :age, data_type: :integer
+        #
+        # Defaults:
+        # - default_visibility: true
+        # - is_required: false
+        # - default_position: inferred (10, 20, 30...)
+        def field(ref, data_type:, name: nil, **opts)
+          ensure_unique_field!(kind: :resource, ref: ref, key: nil)
+
+          position   = opts[:default_position] || next_field_position!
+          visibility = opts.key?(:default_visibility) ? !!opts[:default_visibility] : true
+          required   = opts.fetch(:is_required, false)
+          url_proc   = opts[:url]
+          badge_color = opts[:badge_color]
+          source = opts[:source]
+          custom_label = opts[:custom_label] ? true : false
+          custom_label_key = opts[:custom_label_key]
+          hover_card, hover_card_source =
+            split_static_or_source(opts[:hover_card], opts[:hover_card_source])
+          hover_card ||= derive_hover_card(ref, data_type) unless hover_card_source
+          hover_record_source = opts[:hover_record_source]
+          hover_resource, hover_resource_source =
+            split_static_or_source(opts[:hover_resource], opts[:hover_resource_source])
+          hover_resource ||= derive_hover_resource(ref, data_type) unless hover_resource_source
+          icon = opts[:icon]
+
+          @fields << FieldBuilder.new(
+            kind:                  :resource,
+            ref:                   ref,
+            key:                   nil,
+            name:                  name,
+            data_type:             data_type,
+            mapper:                nil,
+            source:                source,
+            url:                   url_proc,
+            badge_color:           badge_color,
+            hover_card:            hover_card,
+            hover_card_source:     hover_card_source,
+            hover_record_source:   hover_record_source,
+            hover_resource:        hover_resource,
+            hover_resource_source: hover_resource_source,
+            icon:                  icon,
+            default_visibility: visibility,
+            default_position:   position,
+            is_required:        required,
+            custom_label:       custom_label,
+            custom_label_key:   custom_label_key
+          )
+        end
+
+        # DSL:
+        #
+        # field_custom name: "Full Name",
+        #              data_type: HasHelpers::Cards::CardDataType::String,
+        #              mapper: "CardsFieldMapper::Demographics::FullName"
+        #
+        # Defaults:
+        # - default_visibility: true
+        # - is_required: false
+        # - default_position: inferred (10, 20, 30...)
+        # Legacy API: first positional argument accepted for backward compatibility but ignored.
+        def field_custom(legacy_key = nil, name:, data_type:, mapper:, **opts)
+          if legacy_key
+            ActiveSupport::Deprecation.warn(
+              "Passing a CardCustomField constant as the first argument to field_custom is deprecated and will be removed in future versions."
+            )
+          end
+
+          key = name.to_s
+
+          ensure_unique_field!(kind: :custom, ref: key, key: key)
+
+          position   = opts[:default_position] || next_field_position!
+          visibility = opts.key?(:default_visibility) ? !!opts[:default_visibility] : true
+          required   = opts.fetch(:is_required, false)
+          url_proc   = opts[:url]
+          badge_color = opts[:badge_color]
+          source = opts[:source]
+          hover_card, hover_card_source =
+            split_static_or_source(opts[:hover_card], opts[:hover_card_source])
+          hover_record_source = opts[:hover_record_source]
+          hover_resource, hover_resource_source =
+            split_static_or_source(opts[:hover_resource], opts[:hover_resource_source])
+          icon = opts[:icon]
+
+          @fields << FieldBuilder.new(
+            kind:                  :custom,
+            ref:                   key,
+            key:                   key,
+            name:                  name,
+            data_type:             data_type,
+            mapper:                mapper,
+            source:                source,
+            url:                   url_proc,
+            badge_color:           badge_color,
+            hover_card:            hover_card,
+            hover_card_source:     hover_card_source,
+            hover_record_source:   hover_record_source,
+            hover_resource:        hover_resource,
+            hover_resource_source: hover_resource_source,
+            icon:                  icon,
+            default_visibility: visibility,
+            default_position:   position,
+            is_required:        required
+          )
+        end
+
+        # DSL:
+        #
+        # field_virtual :foo, name: "Foo", data_type: :string, source: { from: :details, key: :foo }
+        def field_virtual(ref, name:, data_type:, source:, **opts)
+          ensure_unique_field!(kind: :virtual, ref: ref, key: nil)
+
+          position   = opts[:default_position] || next_field_position!
+          visibility = opts.key?(:default_visibility) ? !!opts[:default_visibility] : true
+          required   = opts.fetch(:is_required, false)
+          url_proc   = opts[:url]
+          badge_color = opts[:badge_color]
+          hover_card, hover_card_source =
+            split_static_or_source(opts[:hover_card], opts[:hover_card_source])
+          hover_record_source = opts[:hover_record_source]
+          hover_resource, hover_resource_source =
+            split_static_or_source(opts[:hover_resource], opts[:hover_resource_source])
+          icon = opts[:icon]
+
+          custom_label     = opts[:custom_label] ? true : false
+          custom_label_key = opts[:custom_label_key]
+
+          @fields << FieldBuilder.new(
+            kind:                  :virtual,
+            ref:                   ref,
+            key:                   nil,
+            name:                  name,
+            data_type:             data_type,
+            mapper:                nil,
+            source:                source,
+            url:                   url_proc,
+            badge_color:           badge_color,
+            hover_card:            hover_card,
+            hover_card_source:     hover_card_source,
+            hover_record_source:   hover_record_source,
+            hover_resource:        hover_resource,
+            hover_resource_source: hover_resource_source,
+            icon:                  icon,
+            default_visibility: visibility,
+            default_position:   position,
+            is_required:        required,
+            custom_label:       custom_label,
+            custom_label_key:   custom_label_key
+          )
+        end
+
+        # DSL:
+        #
+        # data_source :details do |record, ctx|
+        #   { ... }
+        # end
+        def data_source(name, &block)
+          raise ArgumentError, "data_source block required" unless block
+
+          @data_sources << { name: name.to_sym, resolver: block }
+        end
+
+        # DSL:
+        #
+        # expand "Primary Emails", identifier: :emails_primary, expansion_scope: ->(rel) { rel.where(is_primary: true) }
+        def expand(name, identifier: nil, expansion_scope: nil, default_visibility: nil, default_position: nil, description: nil, resources: nil)
+          @expansions << {
+            name:               name,
+            identifier:         identifier,
+            expansion_scope:    expansion_scope,
+            default_visibility: default_visibility,
+            default_position:   default_position,
+            description:        description,
+            resources:          resources
+          }
+        end
+
+        # DSL:
+        #
+        # expand_each "Emails by Location", values: HasContactInfo::Location::ALL do |loc|
+        #   {
+        #     name: "Emails (#{loc.name})",
+        #     identifier: :"emails_#{loc.id}",
+        #     expansion_scope: ->(rel) { rel.where(location_id: loc.id) },
+        #     default_visibility: false,
+        #     default_position: 40 + loc.id.to_i
+        #   }
+        # end
+        def expand_each(_label, values:, &block)
+          raise ArgumentError, "values required" if values.nil?
+          raise ArgumentError, "expand_each block required" unless block
+
+          Array(resources).each_with_index do |res, res_idx|
+            res_values =
+              if values.respond_to?(:call)
+                case values.arity
+                when 0 then values.call
+                when 1 then values.call(res)
+                else values.call(res, res_idx)
+                end
+              else
+                values
+              end
+
+            Array(res_values).each_with_index do |value, idx|
+              attrs =
+                case block.arity
+                when 1 then block.call(value)
+                when 2 then block.call(value, res)
+                else block.call(value, res, idx)
+                end
+
+              expand(
+                attrs[:name] || value.to_s,
+                identifier:         attrs[:identifier],
+                expansion_scope:    attrs[:expansion_scope],
+                default_visibility: attrs[:default_visibility],
+                default_position:   attrs[:default_position] || (@default_position.to_i + (idx + 1)),
+                description:        attrs[:description],
+                resources:          [res]
+              )
+            end
+          end
+        end
+
+        # Normalized representation that the Importer will consume later.
+        def to_h
+          validate!
+
+          {
+            name:               name,
+            identifier:         identifier,
+            relationship:       relationship,
+            relationship_klass: relationship_klass,
+            layout_type:        layout_type,
+            virtual:            virtual,
+            hover_only:         hover_only,
+            variant:            variant,
+            description:        description,
+            is_customizable:    is_customizable,
+            default_visibility: default_visibility,
+            default_position:   default_position,
+            expansion_scope:    nil,
+            scope:              scope,
+            data_sources:       data_sources,
+            resources:          resources,
+            fields:             fields.map(&:to_h),
+            custom_label:       custom_label,
+            custom_label_key:   custom_label_key,
+            icon_name:          icon_name,
+            icon_color:         icon_color
+          }
+        end
+
+        # Builds base card plus any expansions defined.
+        def build
+          base_hash = to_h
+          [base_hash] + build_expansions(base_hash)
+        end
+
+        def as_json(*)
+          to_h
+        end
+
+        private
+
+        def blank?(value)
+          value.respond_to?(:empty?) ? value.to_s.empty? : value.nil?
+        end
+
+        def normalize_enum(value)
+          return nil if value.nil?
+
+          # Case 1: instance of option (HasHelpers::Cards::CardLayoutType::SUMMARY, HasHelpers::Cards::CardVariantType::EMAILS, etc.)
+          # Isn't a Module/Class, and responds to `name` (AR attribute).
+          if value.respond_to?(:name) && !value.is_a?(Module)
+            value.name.to_s
+
+          # Case 2: symbol (:SUMMARY, :LIST, :EMAILS, etc.)
+          elsif value.is_a?(Symbol)
+            value.to_s
+
+          # Case 3: string ("Summary", "List", "EMAILS", etc.)
+          else
+            value.to_s
+          end
+        end
+
+        def next_field_position!
+          pos = @next_field_position
+          @next_field_position += 10
+          pos
+        end
+
+        def ensure_unique_field!(kind:, ref:, key:)
+          existing = @fields.find do |f|
+            if kind == :resource
+              f.kind == :resource && f.ref == ref
+            elsif kind == :custom
+              f.kind == :custom && f.key == key.to_sym
+            else
+              f.kind == :virtual && f.ref == ref
+            end
+          end
+
+          if existing
+            label =
+              if kind == :resource
+                "resource field '#{ref}'"
+              elsif kind == :custom
+                "custom field key '#{key}'"
+              else
+                "virtual field '#{ref}'"
+              end
+
+            raise ValidationError, "Duplicate #{label} in card '#{identifier}'"
+          end
+        end
+
+        def build_expansions(base_hash)
+          @expansions.map.with_index do |exp, idx|
+            dup = base_hash.deep_dup
+            dup[:name]               = exp[:name] if exp[:name]
+            dup[:identifier]         = exp[:identifier] || infer_identifier_from_name(exp[:name] || base_hash[:name])
+            dup[:expansion_scope]    = exp[:expansion_scope] if exp.key?(:expansion_scope)
+            dup[:default_visibility] = exp[:default_visibility] unless exp[:default_visibility].nil?
+            dup[:default_position]   = exp[:default_position] || (base_hash[:default_position].to_i + idx + 1)
+            dup[:description]        = exp[:description] if exp[:description]
+            dup[:resources]          = exp[:resources] if exp[:resources]
+            dup
+          end
+        end
+
+        def infer_identifier_from_name(name)
+          return nil if name.blank?
+          name.to_s.gsub(/[^a-zA-Z0-9]+/, " ").split.map(&:capitalize).join
+        end
+
+        def validate!
+          raise ValidationError, "name is required" if blank?(name)
+          raise ValidationError, "identifier is required" if blank?(identifier)
+          raise ValidationError, "layout is required" if blank?(layout_type)
+          raise ValidationError, "at least one resource is required" if resources.empty?
+
+          fields.each(&:validate!)
+        end
+
+        def derive_identifier!
+          return nil unless @owner_class
+          class_name = @owner_class.name
+          raise ValidationError, "identifier is required for anonymous card classes" if class_name.blank?
+
+          identifier_name = class_name.demodulize
+          if HasHelpers::Cards::CardIdentifier.respond_to?(:lookup) &&
+             HasHelpers::Cards::CardIdentifier.lookup(identifier_name).nil? &&
+             HasHelpers::Cards::CardIdentifier.respond_to?(:define_constant)
+            HasHelpers::Cards::CardIdentifier.define_constant(identifier_name)
+          end
+          identifier_name
+        end
+
+        # Convention-based defaults for hover-card fields:
+        #   field :carrier_id, data_type: HOVER_CARD
+        # becomes equivalent to:
+        #   field :carrier_id,
+        #         data_type: HOVER_CARD,
+        #         hover_card: "CarrierInfoCard",
+        #         hover_resource: "Carrier"
+        # Returns nil for non-hover fields or refs that can't be inferred.
+        # Lets DSL writers pass `hover_card:`/`hover_resource:` with either a String
+        # (static identifier) OR a Hash like `{ from: :ds, key: :foo }` (dynamic source).
+        # Returns [static_value, source_hash], at most one of which is non-nil. The
+        # explicit `_source` option always wins if both are given.
+        def split_static_or_source(value, explicit_source)
+          return [nil, explicit_source] if explicit_source
+          return [nil, value] if value.is_a?(Hash)
+
+          [value, nil]
+        end
+
+        def derive_hover_card(ref, data_type)
+          return nil unless hover_card_data_type?(data_type)
+          base = hover_base_from_ref(ref)
+          base && "#{base}InfoCard"
+        end
+
+        def derive_hover_resource(ref, data_type)
+          return nil unless hover_card_data_type?(data_type)
+          hover_base_from_ref(ref)
+        end
+
+        def hover_card_data_type?(data_type)
+          name =
+            case data_type
+            when Symbol then data_type.to_s
+            when String then data_type
+            else
+              data_type.respond_to?(:name) ? data_type.name.to_s : data_type.to_s
+            end
+          name.underscore == "hover_card"
+        end
+
+        def hover_base_from_ref(ref)
+          return nil if ref.nil?
+          stem = ref.to_s.delete_suffix("_id")
+          return nil if stem.empty?
+          stem.camelize
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/cards/card_builder/definition_context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    module CardBuilder
+      class DefinitionContext
+        def initialize(owner_class)
+          @owner_class        = owner_class
+          @resource_builder   = ResourceBuilder.new
+          @card_builders      = []
+          @next_card_position = 10
+        end
+
+        # DSL:
+        #
+        # resources do
+        #   add Advisor
+        #   add Client
+        # end
+        def resources(&block)
+          raise ArgumentError, "resources block required" unless block
+
+          @resource_builder.instance_eval(&block)
+        end
+
+        # DSL:
+        #
+        # card "Demographics",
+        #      relationship: "demographics",
+        #      identifier: "CardIdentifier::DEMOGRAPHICS",
+        #      layout: LayoutType::KEY_VALUE,
+        #      variant: VariantType::EMAILS
+        def card(name, relationship: nil, relationship_klass: nil, identifier: nil, layout:, variant: nil, virtual: false, hover_only: nil, is_customizable: true, default_visibility: true, default_position: nil, scope: nil, icon_name: nil, icon_color: nil, &block)
+          default_position ||= next_card_position!
+
+          builder = CardDefinitionBuilder.new(
+            name:             name,
+            relationship:     relationship,
+            relationship_klass:     relationship_klass,
+            identifier:       identifier,
+            layout:           layout,
+            resources:        @resource_builder.resources,
+            variant:          variant,
+            virtual:          virtual,
+            hover_only:       hover_only,
+            is_customizable:    is_customizable,
+            default_visibility: default_visibility,
+            default_position:   default_position,
+            scope:              scope,
+            icon_name:          icon_name,
+            icon_color:         icon_color,
+            owner_class:        @owner_class
+          )
+
+          builder.instance_eval(&block) if block
+          @card_builders << builder
+        end
+
+        # Builds an array of normalized hashes (one per card).
+        def build_each
+          if @resource_builder.resources.empty?
+            raise ArgumentError, "At least one resource must be defined with `resources do ... end`"
+          end
+
+          if @card_builders.empty?
+            raise ArgumentError, "No cards defined in #{@owner_class.name}"
+          end
+
+          @card_builders.flat_map(&:build)
+        end
+
+        private
+
+        def next_card_position!
+          pos = @next_card_position
+          @next_card_position += 10
+          pos
+        end
+      end
+    end
+  end
+end