fix: preserve custom human_name for both states and events

- Cherry-picked fix from PR #38 to use ||= instead of = in add_states
- Applied same fix to add_events method to preserve event human names
- Added comprehensive tests for both state and event human_name preservation
- Added regression test specifically for issue #37

This ensures that hard-coded human_name values are not overwritten by
the default translation lambdas when using ActiveModel integration.

Fixes #37
Closes #38

Author: seuros

lib/state_machines/integrations/active_model.rb

@@ -8,7 +8,7 @@
 require 'state_machines/integrations/active_model/version'
 
 module StateMachines
-  module Integrations #:nodoc:
+  module Integrations # :nodoc:
     # Adds support for integrating state machines with ActiveModel classes.
     #
     # == Examples
@@ -189,64 +189,6 @@ module Integrations #:nodoc:
     # Note, also, that the transition can be accessed by simply defining
     # additional arguments in the callback block.
     #
-    # == Observers
-    #
-    # In order to hook in observer support for your application, the
-    # ActiveModel::Observing feature must be included.  This can be added by including the
-    # https://github.com/state-machines/state_machines-activemodel-observers gem in your
-    # Gemfile. Because of the way
-    # ActiveModel observers are designed, there is less flexibility around the
-    # specific transitions that can be hooked in.  However, a large number of
-    # hooks *are* supported.  For example, if a transition for a object's
-    # +state+ attribute changes the state from +parked+ to +idling+ via the
-    # +ignite+ event, the following observer methods are supported:
-    # * before/after/after_failure_to-_ignite_from_parked_to_idling
-    # * before/after/after_failure_to-_ignite_from_parked
-    # * before/after/after_failure_to-_ignite_to_idling
-    # * before/after/after_failure_to-_ignite
-    # * before/after/after_failure_to-_transition_state_from_parked_to_idling
-    # * before/after/after_failure_to-_transition_state_from_parked
-    # * before/after/after_failure_to-_transition_state_to_idling
-    # * before/after/after_failure_to-_transition_state
-    # * before/after/after_failure_to-_transition
-    #
-    # The following class shows an example of some of these hooks:
-    #
-    #   class VehicleObserver < ActiveModel::Observer
-    #     # Callback for :ignite event *before* the transition is performed
-    #     def before_ignite(vehicle, transition)
-    #       # log message
-    #     end
-    #
-    #     # Callback for :ignite event *after* the transition has been performed
-    #     def after_ignite(vehicle, transition)
-    #       # put on seatbelt
-    #     end
-    #
-    #     # Generic transition callback *before* the transition is performed
-    #     def after_transition(vehicle, transition)
-    #       Audit.log(vehicle, transition)
-    #     end
-    #
-    #     def after_failure_to_transition(vehicle, transition)
-    #       Audit.error(vehicle, transition)
-    #     end
-    #   end
-    #
-    # More flexible transition callbacks can be defined directly within the
-    # model as described in StateMachine::Machine#before_transition
-    # and StateMachine::Machine#after_transition.
-    #
-    # To define a single observer for multiple state machines:
-    #
-    #   class StateMachineObserver < ActiveModel::Observer
-    #     observe Vehicle, Switch, Project
-    #
-    #     def after_transition(object, transition)
-    #       Audit.log(object, transition)
-    #     end
-    #   end
-    #
     # == Internationalization
     #
     # Any error message that is generated from performing invalid transitions
@@ -403,14 +345,14 @@ def reset(object)
       end
 
       # Runs state events around the object's validation process
-      def around_validation(object)
-        object.class.state_machines.transitions(object, action, after: false).perform { yield }
+      def around_validation(object, &)
+        object.class.state_machines.transitions(object, action, after: false).perform(&)
       end
 
       protected
 
       def define_state_initializer
-        define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
           def initialize(params = nil, **kwargs)
             # Support both positional hash and keyword arguments
             attrs = params.nil? ? kwargs : params
@@ -428,7 +370,7 @@ def initialize(params = nil, **kwargs)
               end
             end
           end
-        end_eval
+        END_EVAL
       end
 
       # Whether validations are supported in the integration.  Only true if
@@ -446,7 +388,7 @@ def runs_validations_on_action?
 
       # Gets the terminator to use for callbacks
       def callback_terminator
-        @terminator ||= ->(result) { result == false }
+        @callback_terminator ||= ->(result) { result == false }
       end
 
       # Determines the base scope to use when looking up translations
@@ -476,7 +418,7 @@ def translate(klass, key, value)
         # Generate all possible translation keys
         translations = ancestors.map { |ancestor| :"#{ancestor.model_name.to_s.underscore}.#{name}.#{group}.#{value}" }
         translations.concat(ancestors.map { |ancestor| :"#{ancestor.model_name.to_s.underscore}.#{group}.#{value}" })
-        translations.concat([:"#{name}.#{group}.#{value}", :"#{group}.#{value}", value.humanize.downcase])
+        translations.push(:"#{name}.#{group}.#{value}", :"#{group}.#{value}", value.humanize.downcase)
         I18n.translate(translations.shift, default: translations, scope: [i18n_scope(klass), :state_machines])
       end
 
@@ -490,10 +432,12 @@ def ancestors_for(klass)
       def define_state_accessor
         name = self.name
 
+        return unless supports_validations?
+
         owner_class.validates_each(attribute) do |object|
           machine = object.class.state_machine(name)
           machine.invalidate(object, :state, :invalid) unless machine.states.match(object)
-        end if supports_validations?
+        end
       end
 
       # Adds hooks into validation for automatically firing events
@@ -511,22 +455,32 @@ def define_validation_hook
       # Creates a new callback in the callback chain, always inserting it
       # before the default Observer callbacks that were created after
       # initialization.
-      def add_callback(type, options, &block)
+      def add_callback(type, options, &)
         options[:terminator] = callback_terminator
         super
       end
 
       # Configures new states with the built-in humanize scheme
       def add_states(*)
         super.each do |new_state|
-          new_state.human_name ||= ->(state, klass) { translate(klass, :state, state.name) }
+          # Only set the translation lambda if human_name is the default auto-generated value
+          # This preserves user-specified human names while still applying translations for defaults
+          default_human_name = new_state.name ? new_state.name.to_s.tr('_', ' ') : 'nil'
+          if new_state.human_name == default_human_name
+            new_state.human_name = ->(state, klass) { translate(klass, :state, state.name) }
+          end
         end
       end
 
       # Configures new event with the built-in humanize scheme
       def add_events(*)
         super.each do |new_event|
-          new_event.human_name = ->(event, klass) { translate(klass, :event, event.name) }
+          # Only set the translation lambda if human_name is the default auto-generated value
+          # This preserves user-specified human names while still applying translations for defaults
+          default_human_name = new_event.name ? new_event.name.to_s.tr('_', ' ') : 'nil'
+          if new_event.human_name == default_human_name
+            new_event.human_name = ->(event, klass) { translate(klass, :event, event.name) }
+          end
         end
       end
     end

test/event_human_name_test.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+class EventHumanNameTest < BaseTestCase
+  def setup
+    @model = new_model do
+      include ActiveModel::Validations
+      attr_accessor :status
+    end
+  end
+
+  def test_should_allow_custom_human_name_on_event
+    machine = StateMachines::Machine.new(@model, :status, initial: :parked) do
+      event :start, human_name: 'Start Engine' do
+        transition parked: :running
+      end
+
+      event :stop do
+        transition running: :parked
+      end
+
+      event :pause, human_name: 'Temporarily Pause' do
+        transition running: :paused
+      end
+    end
+
+    assert_equal 'Start Engine', machine.events[:start].human_name(@model)
+    assert_equal 'Temporarily Pause', machine.events[:pause].human_name(@model)
+  end
+
+  def test_should_not_override_custom_event_human_name_with_translation
+    # Set up I18n translations
+    I18n.backend.store_translations(:en, {
+                                      activemodel: {
+                                        state_machines: {
+                                          events: {
+                                            ignite: 'Translation for Ignite',
+                                            park: 'Translation for Park',
+                                            repair: 'Translation for Repair'
+                                          }
+                                        }
+                                      }
+                                    })
+
+    machine = StateMachines::Machine.new(@model, :status, initial: :parked) do
+      event :ignite, human_name: 'Custom Ignition' do
+        transition parked: :idling
+      end
+
+      event :park do
+        transition idling: :parked
+      end
+
+      event :repair, human_name: 'Custom Repair Process' do
+        transition any => :parked
+      end
+    end
+
+    # Custom human names should be preserved
+    assert_equal 'Custom Ignition', machine.events[:ignite].human_name(@model)
+    assert_equal 'Custom Repair Process', machine.events[:repair].human_name(@model)
+
+    # Event without custom human_name should use translation
+    assert_equal 'Translation for Park', machine.events[:park].human_name(@model)
+  end
+
+  def test_should_allow_custom_event_human_name_as_string
+    machine = StateMachines::Machine.new(@model, :status) do
+      event :activate, human_name: 'Turn On'
+    end
+
+    assert_equal 'Turn On', machine.events[:activate].human_name(@model)
+  end
+
+  def test_should_allow_custom_event_human_name_as_lambda
+    machine = StateMachines::Machine.new(@model, :status) do
+      event :process, human_name: ->(event, klass) { "#{klass.name}: #{event.name.to_s.capitalize} Action" }
+    end
+
+    assert_equal 'Foo: Process Action', machine.events[:process].human_name(@model)
+  end
+
+  def test_should_use_default_translation_when_no_custom_event_human_name
+    machine = StateMachines::Machine.new(@model, :status) do
+      event :idle
+    end
+
+    # Should fall back to humanized version when no translation exists
+    assert_equal 'idle', machine.events[:idle].human_name(@model)
+  end
+
+  def test_should_handle_nil_event_human_name
+    machine = StateMachines::Machine.new(@model, :status) do
+      event :wait
+    end
+
+    # Explicitly set to nil
+    machine.events[:wait].human_name = nil
+
+    # When human_name is nil, Event#human_name returns nil
+    assert_nil machine.events[:wait].human_name(@model)
+  end
+
+  def test_should_preserve_event_human_name_through_multiple_definitions
+    machine = StateMachines::Machine.new(@model, :status, initial: :draft)
+
+    # First define event with custom human name
+    machine.event :publish, human_name: 'Make Public' do
+      transition draft: :published
+    end
+
+    # Redefine the same event (this should not override the human_name)
+    machine.event :publish do
+      transition pending: :published
+    end
+
+    assert_equal 'Make Public', machine.events[:publish].human_name(@model)
+  end
+
+  def test_should_work_with_state_machine_helper_method
+    @model.class_eval do
+      state_machine :status, initial: :pending do
+        event :approve, human_name: 'Grant Approval' do
+          transition pending: :approved
+        end
+
+        event :reject do
+          transition pending: :rejected
+        end
+      end
+    end
+
+    machine = @model.state_machine(:status)
+    assert_equal 'Grant Approval', machine.events[:approve].human_name(@model)
+  end
+
+  def test_should_handle_complex_i18n_lookup_with_custom_event_human_name
+    # Set up complex I18n structure
+    I18n.backend.store_translations(:en, {
+                                      activemodel: {
+                                        state_machines: {
+                                          foo: {
+                                            status: {
+                                              events: {
+                                                submit: 'Model Specific Submit'
+                                              }
+                                            }
+                                          },
+                                          status: {
+                                            events: {
+                                              submit: 'Machine Specific Submit'
+                                            }
+                                          },
+                                          events: {
+                                            submit: 'Generic Submit'
+                                          }
+                                        }
+                                      }
+                                    })
+
+    machine = StateMachines::Machine.new(@model, :status) do
+      event :submit, human_name: 'Send for Review' do
+        transition draft: :pending
+      end
+    end
+
+    # Should use the custom human_name, not any of the I18n translations
+    assert_equal 'Send for Review', machine.events[:submit].human_name(@model)
+  end
+
+  def teardown
+    # Clear I18n translations after each test
+    I18n.backend.reload!
+  end
+end