magic-presenter 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17e4d44c0c2d9a9e09e7e099a4067b9e6aafe27e1b389cf01808ed0a77d0b9ae
-  data.tar.gz: 7d492486c2f4edb2407af461794e1f0c7e53c7f6b93e65595a618369fb845250
+  metadata.gz: ea088d296d049e126830600bfcc99c5265fbecb41e9d5db51c0d27c02c73e6c8
+  data.tar.gz: e5932ed2865e3f534d181ee18c9eccf26aefb250b48e5564cd3d56cf8b55040d
 SHA512:
-  metadata.gz: fb2609c3dbba1cec025bca22aaa196c718b32084b2954b8184f9b5ce896e7a9289c0b7eb0660469edaf3571d27d99026f6e588f58004e395cee07a75820e38d7
-  data.tar.gz: 1a87908713cb7dbcb029687dd1d4b9006432e8ba9703ef1dbe813088060c471ada70f8d7d1f5de4cdc9210ba602bd0457b1bf061f6fd3d9a25c5a420003198e0
+  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
 
@@ -68,11 +70,41 @@ See the help for more info:
 
 	$ bin/rails generate presenter --help
 
+### View helpers
+
+A presenter can use any helpers via `#helpers` (aliased as `#h`) both in class and instance methods:
+
+```ruby
+class PersonPresenter < Magic::Presenter::Base
+  def self.links
+    [ h.link_to('All', model_class) ]
+  end
+  
+  def link(...) 
+    helpers.link_to(name, self, ...)
+  end
+end
+```
+
+A view context must be set to enable helpers.
+It’s done automagically [wherever possible](#view-context).
+However, one can set it explicitly anywhere:
+
+```ruby
+Magic::Presenter.with view_context: ApplicationController.new.view_context do
+  # put the code that uses helpers within presenters here
+end
+```
+
+> [!NOTE]
+> A valid `request` may be needed for URL helpers to get host info.
+
 ## 🧙 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
 
@@ -86,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
 
@@ -103,12 +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_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+presenter_context = proc do
+	around_action :set_presenter_context
+
+	private
+
+	def set_presenter_context(&)
+		Magic::Presenter.with view_context:, &
+	end
+end
+
+ActiveSupport.on_load :action_controller, &presenter_context
+ActiveSupport.on_load :action_mailer,     &presenter_context

data/config/initializers/action_view.rb

@@ -1,19 +1,41 @@
 # frozen_string_literal: true
 
-ActiveSupport.on_load :action_view do
+ActiveSupport.on_load :action_view do # rubocop:disable Metrics/BlockLength
 	concerning :DecoratedAssignments, prepend: true do
-		def assign(assignments, ...)
-			assignments
-					.transform_values! &:decorated
+		def assign assignments
+			decorate assignments
 
 			super
 		end
 
 		def _run(method, template, locals, ...)
-			locals
-					.transform_values! &:decorated
+			decorate locals
 
 			super
 		end
+
+		private
+
+		def decorate objects
+			objects
+					.transform_values!(&:decorated)
+		end
+	end
+
+	concerning :PresenterContext, prepend: true do
+		def in_rendering_context(...)
+			Magic::Presenter.with view_context: self do
+				super
+			end
+		end
+
+		private
+
+		def decorate(...)
+			super
+					.each_value
+					.grep(Magic::Presenter::Base)
+					.each { _1.view_context = self }
+		end
 	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

@@ -18,6 +18,7 @@ module Magic
 		# up to `ObjectPresenter`.
 		class Base < Decorator::Base
 			include GlobalID if defined? ::GlobalID
+			prepend Helpers  if defined? ::ActionView
 
 			class << self
 				def name_for object_class
@@ -39,6 +40,8 @@ module Magic
 					} for #{self}"
 				end
 
+				delegate_missing_to :model_class
+
 				def descendants
 					Magic.eager_load :presenters
 

data/lib/magic/presenter/helpers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presenter
+		module Helpers # :nodoc:
+			extend ActiveSupport::Concern
+
+			# The Magic::Presenter::Helpers::MissingContext exception is
+			# raised when no view context to run helpers in has been set.
+			class MissingContext < RuntimeError
+				def message
+					<<~TEXT
+						missing view context
+						You should set Magic::Presenter.view_context first
+					TEXT
+				end
+			end
+
+			prepended do
+				class_attribute :view_context
+			end
+
+			class_methods do
+				include Helpers
+
+				alias __raise__ raise
+			end
+
+			private
+
+			def helpers
+				view_context or
+						__raise__ MissingContext
+			end
+
+			alias_method :h, :helpers
+
+			def method_missing(method, ...)
+				super
+			rescue NoMethodError
+				__raise__ unless view_context
+				__raise__ unless helpers.respond_to? method
+
+				helpers.send(method, ...)
+			end
+
+			def respond_to_missing?(method, ...)
+				super or
+						(helpers if view_context).respond_to?(method, ...)
+			end
+		end
+	end
+end

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.3.0'
+		VERSION = '1.0.0'
 	end
 end

data/lib/magic/presenter.rb

@@ -9,25 +9,34 @@ module Magic # :nodoc:
 	# Presentation layer for Rails models
 	module Presenter
 		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'
 
-		module_function
-
-		def for(...)      = Base.for(...)
-		def name_for(...) = Base.name_for(...)
+		singleton_class.delegate *%i[
+				for name_for
+				view_context view_context=
+		], 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.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-27 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
@@ -54,16 +68,18 @@ files:
 - README.md
 - Rakefile
 - 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
@@ -73,7 +89,10 @@ files:
 - lib/magic/presenter/base.rb
 - 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:
@@ -81,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.3.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