Add ViewComponent::Deprecation (#1277)

* Add ViewComponent::Deprecation

This should allow consumers to see deprecation warnings that correctly
mention the next version of VC.

Co-Authored-By: Elia Schito <elia@schito.me>
Co-Authored-By: Hans Lemuet <Spone@users.noreply.github.com>

* Avoid warning about polymorphic slots getter being redefined

```
lib/view_component/polymorphic_slots.rb:42: warning: method redefined; discarding old header
lib/view_component/polymorphic_slots.rb:42: warning: previous definition of header was here
lib/view_component/polymorphic_slots.rb:42: warning: method redefined; discarding old items
lib/view_component/polymorphic_slots.rb:42: warning: previous definition of items was here
```

* Remove the unsupported frozen_string_literal comment from jbuilder template

Was generating this warning:

```
test/sandbox/app/components/jbuilder_component.json.jbuilder:1: warning: `frozen_string_literal' is ignored after any tokens
```

See also: https://bugs.ruby-lang.org/issues/16602

* Add deprecation horizon management to the release script

* Update deprecation copy for manually loading the engine

Co-authored-by: Cameron Dutro <camertron@github.com>

---

Co-authored-by: Max Beizer <max.beizer@gmail.com>
Co-authored-by: Hans Lemuet <Spone@users.noreply.github.com>
Co-authored-by: Cameron Dutro <camertron@github.com>

.rubocop.yml

@@ -25,3 +25,7 @@ Layout/LineLength:
 
 Layout/SpaceBeforeBrackets:
   Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - "**/*.jbuilder" # not yet supported inside jbuilder templates

docs/CHANGELOG.md

@@ -7,6 +7,10 @@ title: Changelog
 
 ## main
 
+* Use a dedicated deprecation instance, silence it while testing
+
+    *Max Beizer, Hans Lemuet, Elia Schito*
+
 * Fix Ruby warnings.
 
     *Hans Lemuet*

lib/view_component.rb

@@ -11,6 +11,7 @@ module ViewComponent
   autoload :CompileCache
   autoload :ComponentError
   autoload :GlobalBuffer
+  autoload :Deprecation
   autoload :Instrumentation
   autoload :Preview
   autoload :PreviewTemplateError
@@ -22,8 +23,8 @@ module ViewComponent
 
 # :nocov:
 if defined?(ViewComponent::Engine)
-  ActiveSupport::Deprecation.warn(
-    "This manually engine loading is deprecated and will be removed in v3.0.0. " \
+  ViewComponent::Deprecation.warn(
+    "Manually loading the engine is deprecated and will be removed in v3.0.0. " \
     "Remove `require \"view_component/engine\"`."
   )
 elsif defined?(Rails::Engine)

lib/view_component/base.rb

@@ -249,14 +249,11 @@ def format
     # @param variant [Symbol] The variant to be used by the component.
     # @return [self]
     def with_variant(variant)
-      ActiveSupport::Deprecation.warn(
-        "`with_variant` is deprecated and will be removed in ViewComponent v3.0.0."
-      )
-
       @__vc_variant = variant
 
       self
     end
+    deprecate :with_variant, deprecator: ViewComponent::Deprecation
 
     # The current request. Use sparingly as doing so introduces coupling that
     # inhibits encapsulation & reuse, often making testing difficult.

lib/view_component/compiler.rb

@@ -49,7 +49,7 @@ def compile(raise_errors: false)
         end
 
         if subclass_instance_methods.include?(:before_render_check)
-          ActiveSupport::Deprecation.warn(
+          ViewComponent::Deprecation.warn(
             "`#before_render_check` will be removed in v3.0.0.\n\n" \
             "To fix this issue, use `#before_render` instead."
           )

lib/view_component/content_areas.rb

@@ -31,7 +31,7 @@ def with(area, content = nil, &block)
 
     class_methods do
       def with_content_areas(*areas)
-        ActiveSupport::Deprecation.warn(
+        ViewComponent::Deprecation.warn(
           "`with_content_areas` is deprecated and will be removed in ViewComponent v3.0.0.\n\n" \
           "Use slots (https://viewcomponent.org/guide/slots.html) instead."
         )

lib/view_component/deprecation.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "active_support/deprecation"
+
+module ViewComponent
+  DEPRECATION_HORIZON = 3
+  Deprecation = ActiveSupport::Deprecation.new(DEPRECATION_HORIZON.to_s, "ViewComponent")
+end

lib/view_component/engine.rb

@@ -28,7 +28,7 @@ class Engine < Rails::Engine # :nodoc:
         )
 
         if options.preview_path.present?
-          ActiveSupport::Deprecation.warn(
+          ViewComponent::Deprecation.warn(
             "`preview_path` will be removed in v3.0.0. Use `preview_paths` instead."
           )
           options.preview_paths << options.preview_path
@@ -160,7 +160,9 @@ class Engine < Rails::Engine # :nodoc:
 
 # :nocov:
 unless defined?(ViewComponent::Base)
-  ActiveSupport::Deprecation.warn(
+  require "view_component/deprecation"
+
+  ViewComponent::Deprecation.warn(
     "This manually engine loading is deprecated and will be removed in v3.0.0. " \
     "Remove `require \"view_component/engine\"`."
   )

lib/view_component/polymorphic_slots.rb

@@ -25,23 +25,26 @@ def renders_many(slot_name, callable = nil)
       end
 
       def register_polymorphic_slot(slot_name, types, collection:)
+        unless types.empty?
+          getter_name = slot_name
+
+          define_method(getter_name) do
+            get_slot(slot_name)
+          end
+        end
+
         renderable_hash = types.each_with_object({}) do |(poly_type, poly_callable), memo|
           memo[poly_type] = define_slot(
             "#{slot_name}_#{poly_type}", collection: collection, callable: poly_callable
           )
 
-          getter_name = slot_name
           setter_name =
             if collection
               "#{ActiveSupport::Inflector.singularize(slot_name)}_#{poly_type}"
             else
               "#{slot_name}_#{poly_type}"
             end
 
-          define_method(getter_name) do
-            get_slot(slot_name)
-          end
-
           define_method(setter_name) do |*args, &block|
             set_polymorphic_slot(slot_name, poly_type, *args, &block)
           end

lib/view_component/slotable.rb

@@ -23,7 +23,7 @@ module Slotable
       #   class_name: "Header" # class name string, used to instantiate Slot
       # )
       def with_slot(*slot_names, collection: false, class_name: nil)
-        ActiveSupport::Deprecation.warn(
+        ViewComponent::Deprecation.warn(
           "`with_slot` is deprecated and will be removed in ViewComponent v3.0.0.\n" \
           "Use the new slots API (https://viewcomponent.org/guide/slots.html) instead."
         )

script/release

@@ -46,6 +46,12 @@ update_ruby_version() {
       -e "s/MINOR = [0-9]+/MINOR = $2/g" \
       -e "s/PATCH = [0-9]+/PATCH = $3/g" \
       lib/view_component/version.rb
+
+  # Update deprecation horizon version
+  major=$1
+  sed -E -i '' \
+      -e "s/DEPRECATION_HORIZON = [0-9]+/DEPRECATION_HORIZON = $((major + 1))/g" \
+      lib/view_component/deprecation.rb
 }
 
 update_gemfiles() {

test/sandbox/app/components/jbuilder_component.json.jbuilder

@@ -1,4 +1,2 @@
-# frozen_string_literal: true
-
 json.message @message
 json.conent content

test/test_helper.rb

@@ -19,6 +19,9 @@
 # Configure Rails Environment
 ENV["RAILS_ENV"] = "test"
 
+require "view_component/deprecation"
+ViewComponent::Deprecation.behavior = :silence
+
 require File.expand_path("../sandbox/config/environment.rb", __FILE__)
 require "rails/test_help"