Allow calculators to implement adjustment labels by adjustable type

Prior to this, the `adjustment_label` method on
`SolidusPromotions::Benefit` could only output a relatively static
string. This commit allows calculators to define one of these methods:

- `#line_item_adjustment_label(line_item, options = {})`
- `#shipment_adjustment_label(shipment, options = {})`
- `#shipping_rate_adjustment_label(shipping_rate, options = {})`
- `#price_adjustment_label(price, options = {})`

These have access to the inner workings of the calculator, so they can
provide dynamic labels (to reflect e.g. which tier a promotion chooses,
making that transparent to the customer.

Author: mamhoff

promotions/app/models/solidus_promotions/benefit.rb

@@ -175,14 +175,48 @@ def compute_amount(adjustable, ...)
 
     # Builds the localized label for adjustments created by this benefit.
     #
-    # @param adjustable [Object]
-    # @return [String]
-    def adjustment_label(adjustable)
-      I18n.t(
-        "solidus_promotions.adjustment_labels.#{adjustable.class.name.demodulize.underscore}",
-        promotion: SolidusPromotions::Promotion.model_name.human,
-        promotion_customer_label: promotion.customer_label
-      )
+    # This method attempts to use a calculator-specific label method if available,
+    # falling back to a localized string key based on the adjustable's class name.
+    #
+    # ## Calculator Override
+    #
+    # Calculators can provide custom labels by implementing a method named after the
+    # adjustable type. For example, a calculator that discounts line items could
+    # implement `line_item_adjustment_label`:
+    #
+    # @example Custom calculator with adjustment label
+    #   class MyCalculator < Spree::Calculator
+    #     def compute(adjustable, *args)
+    #       # calculation logic
+    #     end
+    #
+    #     def line_item_adjustment_label(line_item, *args)
+    #       "Custom discount for #{line_item.product.name}"
+    #     end
+    #   end
+    #
+    # The method name follows the pattern: `{adjustable_type}_adjustment_label`
+    # where `{adjustable_type}` is the underscored class name of the adjustable
+    # (e.g., `line_item`, `shipment`, `shipping_rate`).
+    #
+    # If the calculator does not respond to the expected method, the benefit will
+    # fall back to using an i18n translation key based on the adjustable's class.
+    #
+    # @param adjustable [Object] the object being discounted (e.g., Spree::LineItem, Spree::Shipment)
+    # @param ... [args, kwargs] additional arguments forwarded to the calculator's label method
+    # @return [String] a localized label suitable for display in adjustments
+    #
+    # @see #adjustment_label_method_for
+    def adjustment_label(adjustable, ...)
+      if calculator.respond_to?(adjustment_label_method_for(adjustable))
+        calculator.send(adjustment_label_method_for(adjustable), adjustable, ...)
+      else
+        I18n.t(
+          "solidus_promotions.adjustment_labels.#{adjustable.class.name.demodulize.underscore}",
+          promotion: SolidusPromotions::Promotion.model_name.human,
+          promotion_customer_label: promotion.customer_label
+        )
+      end
     end
 
     # Partial path used for admin forms for this benefit type.
@@ -277,6 +311,10 @@ def discount_method_for(adjustable)
       :"discount_#{adjustable.class.name.demodulize.underscore}"
     end
 
+    def adjustment_label_method_for(adjustable)
+      :"#{adjustable.class.name.demodulize.underscore}_adjustment_label"
+    end
+
     # Prevents destroying a benefit when it has adjustments on completed orders.
     #
     # Adds an error and aborts the destroy callback chain when such adjustments exist.

promotions/spec/models/solidus_promotions/benefit_spec.rb

@@ -265,4 +265,42 @@ def discount_line_item(order, ...)
       expect { subject }.to raise_exception(NotImplementedError)
     end
   end
+
+  describe "#adjustment_label" do
+    let(:benefit_class) do
+      Class.new(described_class) do
+      end
+    end
+
+    let(:calculator_class) do
+      Class.new(Spree::Calculator) do
+        include SolidusPromotions::Calculators::PromotionCalculator
+      end
+    end
+
+    let(:calculator) { calculator_class.new }
+
+    let(:promotion) { build_stubbed(:solidus_promotion, customer_label: "Winter Sale") }
+
+    let(:benefit) { benefit_class.new(calculator:, promotion:) }
+    let(:adjustable) { Spree::LineItem.new }
+
+    subject { benefit.adjustment_label(adjustable) }
+
+    it { is_expected.to eq("Promotion (Winter Sale)") }
+
+    context "if the calculator implements #line_item_adjustment_label" do
+      let(:calculator_class) do
+        Class.new(Spree::Calculator) do
+          include SolidusPromotions::Calculators::PromotionCalculator
+
+          def line_item_adjustment_label(_line_item, _options = {})
+            "Something entirely different"
+          end
+        end
+      end
+
+      it { is_expected.to eq("Something entirely different") }
+    end
+  end
 end