magic-presenter 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ca84b456b21332f6eeba63a5667ed1c8cf7ac97d59141192f138d1698c504bf
-  data.tar.gz: c380ea14f2ddd44150ae71095063e895486d33077521fe1067fca81d4c4b36b0
+  metadata.gz: ea088d296d049e126830600bfcc99c5265fbecb41e9d5db51c0d27c02c73e6c8
+  data.tar.gz: e5932ed2865e3f534d181ee18c9eccf26aefb250b48e5564cd3d56cf8b55040d
 SHA512:
-  metadata.gz: 728dbf1b11115069bb58bfb47c81258f358d22c3570c35dc4a5e7e4d9429a2fa5a6dc3237d0ef0e6a0442d88ca7e9b405e481bd5ea2da90c618800593c8f5155
-  data.tar.gz: f014751ea9cf0470fd1387f25f63b56291a63a434abd177ca0e1aaab27ba1d9a4da4e590354b729fcd12a40fa19f125866daedfba4bd904f37e8d48b3c281ea6
+  metadata.gz: 3cd7a2241b4eae01cc861951d165cff4c52a563ee517c0f05f9e90fab79ac6c53f81a0ca561fb09a1fdaf88d9d39ef435953dcc87a3642c3a632735401d0a0b1
+  data.tar.gz: b4fb57b18de8d450e2297722ab69b09761fb9c5bb89d3b93dfb418f5f064771c5736f9423a617ddab404fb0193608c2c331f415c6a2bd44daee85321dd635bec

data/README.md

@@ -12,7 +12,9 @@
 
 A bit of history: this gem was inspired by digging deeper into [Draper](https://github.com/drapergem/draper) with an eye on a refactoring.
 
-Based on [Magic Decorator](https://github.com/Alexander-Senko/magic-decorator), it implements a presenter logic.
+Based on [Magic Decorator](
+	https://github.com/Alexander-Senko/magic-decorator
+), it implements a presenter logic.
 
 ## Installation
 
@@ -85,7 +87,7 @@ end
 ```
 
 A view context must be set to enable helpers.
-It’s done automagically [wherever possible](#helpers).
+It’s done automagically [wherever possible](#view-context).
 However, one can set it explicitly anywhere:
 
 ```ruby
@@ -99,9 +101,10 @@ end
 
 ## 🧙 Magic
 
-It’s based on [Magic Decorator](
-	https://github.com/Alexander-Senko/magic-decorator#magic
-), so get familiar with that one as well.
+> [!IMPORTANT]
+> It’s based on [Magic Decorator](
+> 	https://github.com/Alexander-Senko/magic-decorator#magic
+> ), so get familiar with that one as well.
 
 ### Presentable scope
 
@@ -115,7 +118,7 @@ Presenters provide automatic class inference for any model based on its class na
 ).
 
 For example, `MyNamespace::MyModel.new.decorate` looks for `MyNamespace::MyPresenter` first.
-When missing, it further looks for decorators for its ancestor classes, up to `ObjectPresenter`.
+When missing, it further looks for presenters for its ancestor classes, up to `ObjectPresenter`.
 
 #### Mapping rules
 
@@ -132,19 +135,87 @@ When in doubt, one can use `Magic::Presenter.name_for`:
 Magic::Presenter.name_for Person # => "PersonPresenter"
 ```
 
-### In views
+#### Preloading
+
+> [!NOTE]
+> Magic Lookup doesn’t try to autoload any classes, it searches among already loaded ones instead.
+> Thus, presenters should be preloaded to be visible via [lookups](#presenter-class-inference).
+
+This is done automatically in both _test_ and _production_ environments by Rails.
+All the application’s presenters and models are eagerly loaded before normal and reverse lookups by Magic Presenter as well.
+So, normally one shouldn’t worry about that.
 
 > [!IMPORTANT]
+> When developing a Rails engine that defines its own presenters, one should take care of the preloading themselves.
+
+That could be done in an initializer with a helper method provided:
+
+```ruby
+Rails.application.config.to_prepare do
+  Magic.eager_load :presenters, engine: MyLib::Engine
+end
+```
+
+### Class methods delegation
+
+Missing class methods of a presenter are delegated to a matching model class if the latter can be inferred unambiguously.
+`Magic::Lookup::Error` is raised otherwise.
+
+### In views
+
+> [!NOTE]
 > Every object passed to views is decorated automagically.
 > This involves both implicit instance variables and `locals` passed explicitly.
 
 ### Helpers
 
+One can call helpers directly without explicit `helper` or `h`:
+
+```ruby
+class PersonPresenter < Magic::Presenter::Base
+  def self.links
+    [ link_to('All', model_class) ]
+  end
+
+  def link(...) = link_to(name, self, ...)
+end
+```
+
+#### View context
+
 View context is set automagically to enable helpers:
 - in views,
 - in controller actions,
 - in mailer actions.
 
+## Generators
+
+> [!NOTE]
+> The built-in `helper` generator is overridden with `presenter` one to generate presenters instead of helpers.
+
+## Testing presenters
+
+Magic Presenter supports RSpec and Test::Unit.
+The appropriate tests are generated alongside a presenter.
+
+Testing presenters is much like [testing Rails helpers](
+	https://guides.rubyonrails.org/testing.html#testing-helpers
+).
+Since the test class inherits from `ActionView::TestCase`, Rails’ helper methods such as `link_to`, `localize` and many others are available in tests.
+
+As any presenter is a decorator, see also [how to test decorators](
+	https://github.com/Alexander-Senko/magic-decorator#testing-decorators
+).
+
+### RSpec
+
+Presenter specs are expected to live in `spec/presenters`.
+If a different path is used, `type: :presenter` metadata should be set explicitly.
+
+### Test::Unit
+
+Tests related to the presenters are located under the `test/presenters` directory and inherit from `Magic::Presenter::TestCase`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/config/initializers/action_view.rb

@@ -2,7 +2,7 @@
 
 ActiveSupport.on_load :action_view do # rubocop:disable Metrics/BlockLength
 	concerning :DecoratedAssignments, prepend: true do
-		def assign(assignments, ...)
+		def assign assignments
 			decorate assignments
 
 			super
@@ -24,7 +24,7 @@ ActiveSupport.on_load :action_view do # rubocop:disable Metrics/BlockLength
 
 	concerning :PresenterContext, prepend: true do
 		def in_rendering_context(...)
-			Magic::Presenter::Base.with view_context: self do
+			Magic::Presenter.with view_context: self do
 				super
 			end
 		end

data/config/initializers/generators.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+if defined? Rails::Generators
+	# HACK: eliminates the following Thor warning:
+	#
+	#   Deprecation warning: Expected boolean default value for '--helper'; got :presenter (string).
+	Thor::Option.prepend Module.new {
+		def validate_default_type!
+			return if @name == 'helper'
+
+			super
+		end
+	}
+
+	Magic.each_engine do |engine|
+		engine.config.generators do
+			_1.helper = :presenter
+		end
+	end
+end

data/config/initializers/rspec.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
-RSpec.configure do |config|
-	config.include concern(:PresenterExampleGroup) {
-		included { metadata[:type] = :presenter }
-	}, file_path: %r'spec/presenters', type: :presenter
-end if defined? RSpec
+if defined? RSpec::Core
+	RSpec.configure do |config|
+		if defined? RSpec::Rails
+			require 'rspec/rails/example/presenter_example_group'
+
+			config.include RSpec::Rails::PresenterExampleGroup, type: :presenter
+		end
+
+		# Tag all groups and examples in the spec/presenters directory with
+		# type: :presenter
+		config.define_derived_metadata file_path: %r'/spec/presenters/' do |metadata|
+			metadata[:type] ||= :presenter
+		end
+	end
+end

data/lib/generators/magic/presenter/generator.rb

@@ -3,7 +3,7 @@
 module Magic
 	module Presenter
 		module Generator # :nodoc:
-			require 'generators/presenter/presenter_generator'
+			require 'generators/rails/presenter/presenter_generator'
 
 			private
 
@@ -18,7 +18,7 @@ module Magic
 				root / 'presenters' / path
 			end
 
-			def presenter_path(*) = file_path(*, root: PresenterGenerator.target_root)
+			def presenter_path(*) = file_path(*, root: Rails::PresenterGenerator.target_root)
 		end
 	end
 end

data/lib/generators/rails/presenter/presenter_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Rails
+	class PresenterGenerator < Generators::NamedBase # :nodoc:
+		include Magic::Presenter::Generator
+		include Generators::ResourceHelpers
+
+		source_root File.expand_path('templates', __dir__)
+
+		check_class_collision suffix: 'Presenter'
+
+		class_option :parent,
+				type:    :string,
+				default: 'ApplicationPresenter',
+				desc:    'The parent class for the generated presenter'
+
+		cattr_reader :target_root, default: Pathname('app')
+
+		def create_presenter_file
+			template 'presenter.rb', "#{file_path}.rb"
+		end
+
+		hook_for :test_framework do |generator|
+			invoke generator, [ name ]
+		end
+
+		private
+
+		def parent_class_name = options[:parent].classify
+	end
+end

data/lib/generators/test_unit/presenter/templates/presenter_test.rb.tt

@@ -1,9 +1,6 @@
 require "test_helper"
 
 <% module_namespacing do -%>
-class <%= class_name %>Test < ActiveSupport::TestCase
-  # test "the truth" do
-  #   assert true
-  # end
+class <%= class_name %>Test < Magic::Presenter::TestCase
 end
 <% end -%>

data/lib/magic/presenter/base.rb

@@ -40,6 +40,8 @@ module Magic
 					} for #{self}"
 				end
 
+				delegate_missing_to :model_class
+
 				def descendants
 					Magic.eager_load :presenters
 

data/lib/magic/presenter/test_case.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'action_view/test_case'
+
+module Magic
+	module Presenter
+		# = Magic Presenter test case
+		#
+		class TestCase < ActiveSupport::TestCase
+			module Behavior # :nodoc:
+				extend ActiveSupport::Concern
+
+				include ActionView::TestCase::Behavior
+
+				included do
+					Magic.each_engine { include _1.routes.url_helpers }
+				end
+			end
+
+			include Behavior
+		end
+	end
+end

data/lib/magic/presenter/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Presenter
-		VERSION = '0.4.0'
+		VERSION = '1.0.0'
 	end
 end

data/lib/magic/presenter.rb

@@ -11,6 +11,7 @@ module Magic # :nodoc:
 		autoload :Base,      'magic/presenter/base'
 		autoload :Helpers,   'magic/presenter/helpers'
 		autoload :GlobalID,  'magic/presenter/global_id'
+		autoload :TestCase,  'magic/presenter/test_case'
 		autoload :Generator, 'generators/magic/presenter/generator'
 
 		singleton_class.delegate *%i[
@@ -19,16 +20,23 @@ module Magic # :nodoc:
 		], to: Base
 	end
 
-	module_function
+	module_function # TODO: extract to Magic Support
 
-	def eager_load *scopes
+	def eager_load *scopes, engine: Rails.application
 		return if Rails.application.config.eager_load
 
 		scopes
 				.map(&:to_s)
 				.map(&:pluralize)
-				.map { Rails.root / 'app' / _1 }
+				.map { engine.root / 'app' / _1 }
 				.select(&:exist?)
 				.each { Rails.autoloaders.main.eager_load_dir _1 }
 	end
+
+	def each_engine(&)
+		Rails.application
+				.then { [ _1, *_1.railties ] }
+				.grep(Rails::Engine)
+				.each(&)
+	end
 end

data/lib/rspec/rails/example/presenter_example_group.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'rspec/rails'
+
+module RSpec
+	module Rails
+		# @api public
+		# Container module for presenter specs.
+		module PresenterExampleGroup
+			extend  ActiveSupport::Concern
+			include HelperExampleGroup
+			include Magic::Presenter::TestCase::Behavior
+
+			included do
+				around { Magic::Presenter.with view_context: self, &_1 }
+			end
+		end
+	end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: magic-presenter
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-29 00:00:00.000000000 Z
+date: 2024-11-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -35,14 +35,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: magic-lookup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Based on Magic Decorator, it’s meant to replace Draper.
 email:
 - Alexander.Senko@gmail.com
@@ -56,15 +70,16 @@ files:
 - app/models/concerns/magic/presentable.rb
 - config/initializers/action_controller.rb
 - config/initializers/action_view.rb
+- config/initializers/generators.rb
 - config/initializers/presentable.rb
 - config/initializers/rspec.rb
 - lib/generators/magic/presenter/generator.rb
 - lib/generators/magic/presenter/install/USAGE
 - lib/generators/magic/presenter/install/install_generator.rb
 - lib/generators/magic/presenter/install/templates/application_presenter.rb.tt
-- lib/generators/presenter/USAGE
-- lib/generators/presenter/presenter_generator.rb
-- lib/generators/presenter/templates/presenter.rb.tt
+- lib/generators/rails/presenter/USAGE
+- lib/generators/rails/presenter/presenter_generator.rb
+- lib/generators/rails/presenter/templates/presenter.rb.tt
 - lib/generators/rspec/presenter/presenter_generator.rb
 - lib/generators/rspec/presenter/templates/presenter_spec.rb.tt
 - lib/generators/test_unit/presenter/presenter_generator.rb
@@ -75,7 +90,9 @@ files:
 - lib/magic/presenter/engine.rb
 - lib/magic/presenter/global_id.rb
 - lib/magic/presenter/helpers.rb
+- lib/magic/presenter/test_case.rb
 - lib/magic/presenter/version.rb
+- lib/rspec/rails/example/presenter_example_group.rb
 - lib/tasks/magic/presenter_tasks.rake
 homepage: https://github.com/Alexander-Senko/magic-presenter
 licenses:
@@ -83,7 +100,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/Alexander-Senko/magic-presenter
   source_code_uri: https://github.com/Alexander-Senko/magic-presenter
-  changelog_uri: https://github.com/Alexander-Senko/magic-presenter/blob/v0.4.0/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/magic-presenter/blob/v1.0.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib

data/lib/generators/presenter/presenter_generator.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-class PresenterGenerator < Rails::Generators::NamedBase # :nodoc:
-	include Magic::Presenter::Generator
-
-	source_root File.expand_path('templates', __dir__)
-
-	check_class_collision suffix: 'Presenter'
-
-	class_option :parent,
-			type:    :string,
-			default: 'ApplicationPresenter',
-			desc:    'The parent class for the generated presenter'
-
-	cattr_reader :target_root, default: Pathname('app')
-
-	def create_presenter_file
-		template 'presenter.rb', "#{file_path}.rb"
-	end
-
-	hook_for :test_framework
-
-	private
-
-	def parent_class_name = options[:parent].classify
-end