magic-presenter 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2d9f852b05ac3df9f02d0a6f43256155d36f0aa54c9b94887017c6695040000
-  data.tar.gz: 07f21527902b18f58d4ffc88655b3e37317a331fa8db2f37addaa421478a523b
+  metadata.gz: 17e4d44c0c2d9a9e09e7e099a4067b9e6aafe27e1b389cf01808ed0a77d0b9ae
+  data.tar.gz: 7d492486c2f4edb2407af461794e1f0c7e53c7f6b93e65595a618369fb845250
 SHA512:
-  metadata.gz: 3d230e25c5b5a5bfaef1e941df5388cdcc71315287fbf71177fa7ebe1ca13ff4fa16a2e6a07e358bbed35213053262e6900b390cdc9572f5e33ea5ae59161626
-  data.tar.gz: 36e3545b509b62c1c68f22d156adec1ef46ddf34ff0efeb9875aedf13bac1856a6387006211ad9c93a9dc118aa55f98a6a0db09133172d8b6453ed6f81e968e1
+  metadata.gz: fb2609c3dbba1cec025bca22aaa196c718b32084b2954b8184f9b5ce896e7a9289c0b7eb0660469edaf3571d27d99026f6e588f58004e395cee07a75820e38d7
+  data.tar.gz: 1a87908713cb7dbcb029687dd1d4b9006432e8ba9703ef1dbe813088060c471ada70f8d7d1f5de4cdc9210ba602bd0457b1bf061f6fd3d9a25c5a420003198e0

data/README.md

@@ -1,5 +1,8 @@
 # 🧙 Magic Presenter
 
+![GitHub Actions Workflow Status](
+	https://img.shields.io/github/actions/workflow/status/Alexander-Senko/magic-presenter/ci.yml
+)
 ![Code Climate maintainability](
 	https://img.shields.io/codeclimate/maintainability-percentage/Alexander-Senko/magic-presenter
 )
@@ -15,11 +18,15 @@ Based on [Magic Decorator](https://github.com/Alexander-Senko/magic-decorator),
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add magic-presenter
+	$ bundle add magic-presenter
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install magic-presenter
+	$ gem install magic-presenter
+
+After all the gems are `bundle`d run the installer in the project directory to generate the necessary files:
+
+	$ bin/rails generate magic:presenter:install
 
 ## Usage
 
@@ -51,7 +58,17 @@ When no presenter is found,
 - `#decorate!` raises `Magic::Lookup::Error`,
 - `#decorated` returns the original object.
 
-## Magic
+### Generators
+
+A generator can be used to generate a presenter:
+
+	$ bin/rails generate presenter Person
+
+See the help for more info:
+
+	$ bin/rails generate presenter --help
+
+## 🧙 Magic
 
 It’s based on [Magic Decorator](
 	https://github.com/Alexander-Senko/magic-decorator#magic
@@ -59,7 +76,7 @@ It’s based on [Magic Decorator](
 
 ### Presentable scope
 
-`Magic::Presentable` is mixed into `ActiveModel::Model` by default.
+`Magic::Presentable` is mixed into `ActiveModel::API` by default.
 It means that any model, be it `ActiveRecord::Base`, `Mongoid::Document` or whatever else, is _magically presentable_.
 
 ### Presenter class inference
@@ -68,9 +85,30 @@ Presenters provide automatic class inference for any model based on its class na
 	https://github.com/Alexander-Senko/magic-lookup
 ).
 
-For example, `MyNamespace::MyModel.new.decorate` looks for `MyNamespace::MyModelPresenter` first.
+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`.
 
+#### Mapping rules
+
+- `MyObject` → `MyObjectPresenter`
+- `MyModel`  → `MyPresenter`
+- `MyRecord` → `MyPresenter`
+
+> [!TIP]
+> That’s why `ApplicationPresenter` presents `ApplicationRecord`  alongside all its descendants automagically with no extra code.
+
+When in doubt, one can use `Magic::Presenter.name_for`:
+
+```ruby
+Magic::Presenter.name_for Person # => "PersonPresenter"
+```
+
+### In views
+
+> [!IMPORTANT]
+> Every object passed to views is decorated automagically.
+> This involves both implicit instance variables and `locals` passed explicitly.
+
 ## 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/{lib → app/models/concerns}/magic/presentable.rb

@@ -7,8 +7,16 @@ module Magic
 	module Presentable
 		include Decoratable
 
+		class << self
+			def classes
+				Magic.eager_load :models
+
+				super
+			end
+		end
+
 		private
 
-		def decorator = Presenter.for self.class
+		def decorator_base = Presenter
 	end
 end

data/config/initializers/action_view.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+ActiveSupport.on_load :action_view do
+	concerning :DecoratedAssignments, prepend: true do
+		def assign(assignments, ...)
+			assignments
+					.transform_values! &:decorated
+
+			super
+		end
+
+		def _run(method, template, locals, ...)
+			locals
+					.transform_values! &:decorated
+
+			super
+		end
+	end
+end

data/config/initializers/presentable.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-ActiveSupport.on_load :active_model do
-	include Magic::Presentable
+Rails.application.config.to_prepare do
+	ActiveModel::API.include Magic::Presentable
 end

data/config/initializers/rspec.rb

@@ -0,0 +1,7 @@
+# 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

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presenter
+		module Generator # :nodoc:
+			require 'generators/presenter/presenter_generator'
+
+			private
+
+			def file_name name = super()
+				name
+						.camelize
+						.then { Magic::Presenter.name_for _1 }
+						.underscore
+			end
+
+			def file_path path = super(), root: target_root
+				root / 'presenters' / path
+			end
+
+			def presenter_path(*) = file_path(*, root: PresenterGenerator.target_root)
+		end
+	end
+end

data/lib/generators/magic/presenter/install/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Generates application files used by Magic Presenter:
+        ApplicationPresenter:   a base class for other presenters to
+                                inherit from.
+
+Example:
+    bin/rails generate magic:presenter:install
+
+    This will create:
+        ApplicationPresenter:   app/presenters/application_presenter.rb

data/lib/generators/magic/presenter/install/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presenter
+		class InstallGenerator < Rails::Generators::Base # :nodoc:
+			include Generator
+
+			source_root File.expand_path('templates', __dir__)
+
+			def create_files
+				template 'application_presenter.rb', "#{presenter_path namespaced_file_name 'ApplicationRecord'}.rb"
+			end
+
+			private
+
+			def namespaced_file_name(*)
+				File.join *(namespaced_path if namespaced?), file_name(*)
+			end
+		end
+	end
+end

data/lib/generators/magic/presenter/install/templates/application_presenter.rb.tt

@@ -0,0 +1,6 @@
+<% module_namespacing do -%>
+class ApplicationPresenter < Magic::Presenter::Base
+  # Define presentation-specific methods here.
+  # They are shared by all the descendant presenters.
+end
+<% end -%>

data/lib/generators/presenter/USAGE

@@ -0,0 +1,28 @@
+Description:
+    Generates a new presenter for a model. Pass the model name, either
+    CamelCased or under_scored, as an argument.
+
+    This generator invokes your configured test framework, which
+    defaults to TestUnit. It supports both TestUnit and RSpec.
+
+    If a `--parent` option is given, it’s used as a superclass of the
+    created presenter.
+
+Example:
+    bin/rails generate presenter account
+
+    This will create:
+        Presenter:  app/presenters/account_presenter.rb
+      for TestUnit:
+        Test:       test/presenters/account_presenter_test.rb
+      for RSpec:
+        Spec:       spec/presenters/account_presenter_spec.rb
+
+    bin/rails generate presenter admin/account
+
+    This will create:
+        Presenter:  app/presenters/admin/account_presenter.rb
+      for TestUnit:
+        Test:       test/presenters/admin/account_presenter_test.rb
+      for RSpec:
+        Spec:       spec/presenters/admin/account_presenter_spec.rb

data/lib/generators/presenter/presenter_generator.rb

@@ -0,0 +1,26 @@
+# 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

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

@@ -0,0 +1,5 @@
+<% module_namespacing do -%>
+class <%= class_name %> < <%= parent_class_name %>
+  # Define presentation-specific methods here.
+end
+<% end -%>

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'generators/rspec'
+require 'generators/magic/presenter/generator'
+
+module Rspec # :nodoc:
+	module Generators # :nodoc:
+		class PresenterGenerator < Base # :nodoc:
+			include Magic::Presenter::Generator
+
+			source_root File.expand_path('templates', __dir__)
+
+			cattr_reader :target_root, default: Pathname('spec')
+
+			def create_test_file
+				template 'presenter_spec.rb', "#{file_path}_spec.rb"
+			end
+		end
+	end
+end

data/lib/generators/rspec/presenter/templates/presenter_spec.rb.tt

@@ -0,0 +1,7 @@
+require 'rails_helper'
+
+<% module_namespacing do -%>
+RSpec.describe <%= class_name %> do
+  pending "add some examples to (or delete) #{__FILE__}"
+end
+<% end -%>

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails/generators/test_unit'
+require 'generators/magic/presenter/generator'
+
+module TestUnit # :nodoc:
+	module Generators # :nodoc:
+		class PresenterGenerator < Base # :nodoc:
+			include Magic::Presenter::Generator
+
+			source_root File.expand_path('templates', __dir__)
+
+			check_class_collision suffix: 'PresenterTest'
+
+			cattr_reader :target_root, default: Pathname('test')
+
+			def create_test_file
+				template 'presenter_test.rb', "#{file_path}_test.rb"
+			end
+		end
+	end
+end

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

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

data/lib/magic/presenter/base.rb

@@ -13,12 +13,37 @@ module Magic
 		#
 		# Presenters provide automatic class inference for any model based
 		# on its class name powered by Magic Lookup.
-		# For example, `MyModel.new` looks for `MyModelPresenter` first.
+		# For example, `MyModel.new` looks for `MyPresenter` first.
 		# If not found, it looks for presenters of its ancestor classes,
 		# up to `ObjectPresenter`.
 		class Base < Decorator::Base
+			include GlobalID if defined? ::GlobalID
+
 			class << self
-				def name_for(object_class) = "#{object_class}Presenter"
+				def name_for object_class
+					object_class
+							.to_s
+							.delete_suffix('Model')
+							.delete_suffix('Record')
+							.then { "#{_1}Presenter" }
+				end
+
+				def model_class
+					Presentable.classes
+							.select { Presenter.for(_1) == self }
+							.sole
+				rescue Enumerable::SoleItemExpectedError => error
+					raise Lookup::Error, "#{error.message
+							.sub('items', 'model classes')
+							.sub('item',  'model class')
+					} for #{self}"
+				end
+
+				def descendants
+					Magic.eager_load :presenters
+
+					super
+				end
 			end
 		end
 	end

data/lib/magic/presenter/engine.rb

@@ -4,6 +4,10 @@ module Magic
 	module Presenter
 		class Engine < ::Rails::Engine # :nodoc:
 			isolate_namespace Magic::Presenter
+
+			config.generators do
+				_1.test_framework = :rspec
+			end
 		end
 	end
 end

data/lib/magic/presenter/global_id.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presenter
+		# = Active Job integration
+		#
+		# Active Job [accepts Active Record objects](
+		# 	http://edgeguides.rubyonrails.org/active_job_basics.html#globalid
+		# ).
+		# An object passed to a background job must implement [Global ID](
+		# 	https://github.com/rails/globalid
+		# ).
+		#
+		# This module implements Global ID for decorated models by defining
+		# `.find` method that uses the one from a model class and decorates
+		# the result.
+		# This means one can pass decorated objects to background jobs and
+		# get them decorated when deserialized.
+		module GlobalID
+			extend ActiveSupport::Concern
+
+			included do
+				include ::GlobalID::Identification
+			end
+
+			class_methods do
+				def find(...)
+					model_class
+							.find(...)
+							.decorated
+				end
+			end
+		end
+	end
+end

data/lib/magic/presenter/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Presenter
-		VERSION = '0.1.0'
+		VERSION = '0.3.0'
 	end
 end

data/lib/magic/presenter.rb

@@ -5,16 +5,29 @@ require 'magic/decorator'
 require_relative 'presenter/version'
 require_relative 'presenter/engine'
 
-module Magic
-	autoload :Presentable, 'magic/presentable'
-
+module Magic # :nodoc:
 	# Presentation layer for Rails models
 	module Presenter
-		autoload :Base, 'magic/presenter/base'
+		autoload :Base,      'magic/presenter/base'
+		autoload :GlobalID,  'magic/presenter/global_id'
+		autoload :Generator, 'generators/magic/presenter/generator'
 
 		module_function
 
 		def for(...)      = Base.for(...)
 		def name_for(...) = Base.name_for(...)
 	end
+
+	module_function
+
+	def eager_load *scopes
+		return if Rails.application.config.eager_load
+
+		scopes
+				.map(&:to_s)
+				.map(&:pluralize)
+				.map { Rails.root / 'app' / _1 }
+				.select(&:exist?)
+				.each { Rails.autoloaders.main.eager_load_dir _1 }
+	end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: magic-presenter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alexander Senko
 bindir: bin
 cert_chain: []
-date: 2024-10-19 00:00:00.000000000 Z
+date: 2024-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -33,16 +33,16 @@ dependencies:
   name: magic-decorator
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.3'
 description: Based on Magic Decorator, it’s meant to replace Draper.
 email:
 - Alexander.Senko@gmail.com
@@ -53,12 +53,26 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/models/concerns/magic/presentable.rb
+- config/initializers/action_view.rb
 - config/initializers/presentable.rb
-- lib/magic/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/rspec/presenter/presenter_generator.rb
+- lib/generators/rspec/presenter/templates/presenter_spec.rb.tt
+- lib/generators/test_unit/presenter/presenter_generator.rb
+- lib/generators/test_unit/presenter/templates/presenter_test.rb.tt
 - lib/magic/presenter.rb
 - lib/magic/presenter/authors.rb
 - lib/magic/presenter/base.rb
 - lib/magic/presenter/engine.rb
+- lib/magic/presenter/global_id.rb
 - lib/magic/presenter/version.rb
 - lib/tasks/magic/presenter_tasks.rake
 homepage: https://github.com/Alexander-Senko/magic-presenter
@@ -67,7 +81,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.1.0/CHANGELOG.md
+  changelog_uri: https://github.com/Alexander-Senko/magic-presenter/blob/v0.3.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib