wallaby-core 0.2.11 → 0.3.0.beta1

data/lib/services/wallaby/engine_url_for.rb

@@ -1,46 +1,91 @@
 # frozen_string_literal: true
 
 module Wallaby
-  # {Wallaby::ApplicationHelper#url_for} helper for Wallaby engine
+  # URL service object for {Urlable#url_for} helper
+  #
+  # Since {Engine}'s {https://github.com/wallaby-rails/wallaby-core/blob/master/config/routes.rb routes}
+  # are declared in
+  # {https://guides.rubyonrails.org/routing.html#routing-to-rack-applications Rack application}
+  # fashion via {ResourcesRouter} to recoganize path in the pattern of `/:mount_path/:resources`.
+  # It means when the current request path (e.g. `/admin/categories`)
+  # is under the same mount path of {Engine} (e.g. `/admin`),
+  # using the original Rails **usl_for** (e.g. `url_for action: :index`)
+  # without providing the `:resources` param and script name
+  # will lead to an **ActionController::RoutingError** exception.
+  #
+  # To generate the proper URL from given params and options for this kind of requests,
+  # there are three kinds of scenarios that need to be considered
+  # (assume that {Engine} is mounted at `/admin`):
+  #
+  # - if the URL to generate is a regular route defined before mounting the {Engine}
+  #   that does not override the resources `categories` routes handled by {Engine}, such as:
+  #
+  #       namespace :admin do
+  #         resources :custom_categories
+  #       end
+  #       wallaby_mount at: '/admin'
+  #
+  # - if the URL to generate is a route that overrides the existing {Engine} route
+  #   (assume that `categories` is one of the resources handled by {Engine}):
+  #
+  #       namespace :admin do
+  #         resources :categories
+  #       end
+  #       wallaby_mount at: '/admin'
+  #
+  # - regular resources handled by {ResourcesRouter}, e.g. (`/admin/products`)
   class EngineUrlFor
-    # A constant to map actions to their route paths defined in Wallaby routes.
-    ACTION_TO_PATH_MAP =
-      Wallaby::ERRORS.each_with_object(ActiveSupport::HashWithIndifferentAccess.new) do |error, map|
-        map[error] = :"#{error}_path"
-      end.merge(
-        home: :root_path,
-        index: :resources_path,
-        new: :new_resource_path,
-        show: :resource_path,
-        edit: :edit_resource_path
-      ).freeze
-
-    class << self
-      # Generate URL that Wallaby engine supports (e.g. home/resourceful/errors)
-      # @see https://github.com/reinteractive/wallaby/blob/master/config/routes.rb config/routes.rb
-      # @param engine_name [string]
-      # @param parameters [ActionController::Parameters, Hash]
-      # @return [String] path string for wallaby engine
-      # @return [nil] nil if given engine name cannot be found
-      def handle(engine_name:, parameters:)
-        route = Rails.application.routes.named_routes[engine_name]
-        return unless route
-
-        params = { script_name: route.path.spec.to_s }.merge(parameters).symbolize_keys
-
-        ModuleUtils.try_to(
-          Engine.routes.url_helpers, action_path_from(params), params
-        )
-      end
+    include ActiveModel::Model
+
+    # @!attribute context
+    # @return [ActionController::Base, ActionView::Base]
+    attr_accessor :context
+    # @!attribute options
+    # @return [Hash]
+    attr_accessor :options
+    # @!attribute params
+    # @return [Hash, ActionController::Parameters]
+    attr_accessor :params
+
+    # Generate the proper URL depending on the context
+    # @param context [ActionController::Base, ActionView::Base]
+    # @param params [Hash, ActionController::Parameters]
+    # @param options [Hash]
+    # @option model_class [Class]
+    # @option with_query [true] indicate if all query params should be included
+    # @return [nil] nil if params is not a **Hash** or **ActionController::Parameters**
+    # @see #execute
+    def self.execute(context:, params:, options:)
+      return unless params.is_a?(Hash) || params.try(:permitted?)
+
+      new(context: context, params: params, options: options).execute
+    end
+
+    # @return [String] URL
+    # @return [nil] nil if current request is not under any mounted {Engine}
+    # @see https://github.com/reinteractive/wallaby/blob/master/config/routes.rb
+    def execute
+      return if context.current_engine_route.blank?
+      return custom_app_route.url if custom_app_route.exist?
 
-      protected
+      engine_route.url
+    end
+
+    private
+
+    # @return [Wallaby::Engines::CustomAppRoute]
+    def custom_app_route
+      @custom_app_route ||=
+        Engines::CustomAppRoute.new(
+          context: context, params: params, options: options
+        )
+    end
 
-      # Find out the named path from given params
-      # @return [Symbol] named path
-      def action_path_from(params)
-        action = params[:action] || params.fetch(:_recall, {})[:action]
-        ACTION_TO_PATH_MAP[action]
-      end
+    # @return [Wallaby::Engines::EngineRoute]
+    def engine_route
+      Engines::EngineRoute.new(
+        context: context, params: params, options: options
+      )
     end
   end
 end

data/lib/services/wallaby/fields_regulator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Wallaby
+  # Validate and convert the field metadata to `ActiveSupport::HashWithIndifferentAccess`
+  FieldsRegulator = Struct.new(:fields) do
+    # @return [ActiveSupport::HashWithIndifferentAccess]
+    def execute
+      ensure_fields_is_a_hash
+      ensure_type_is_present
+      normalized_fields
+    end
+
+    protected
+
+    def ensure_fields_is_a_hash
+      return if fields.is_a?(Hash)
+
+      raise ArgumentError, 'Please provide a Hash metadata'
+    end
+
+    def ensure_type_is_present
+      missing_types = normalized_fields.select do |_field, metadata|
+        metadata[:type].blank?
+      end
+      return if missing_types.blank?
+
+      raise ArgumentError, "Please provide the type for #{missing_types.keys.join(',')}"
+    end
+
+    def normalized_fields
+      @normalized_fields ||= fields.with_indifferent_access
+    end
+  end
+end

data/lib/services/wallaby/map/mode_mapper.rb

@@ -2,14 +2,14 @@
 
 module Wallaby
   class Map
-    # Go through each {Wallaby::Mode} (e.g. **ActiveRecord**/**Her**)
+    # Go through each {Mode} (e.g. **ActiveRecord**/**Her**)
     # and find out all the model classes respectively.
-    # Then a hash (Model => {Wallaby::Mode}) is constructed
-    # to tell {Wallaby} which {Wallaby::Mode} to use for a given model.
+    # Then a hash (Model => {Mode}) is constructed
+    # to tell {Wallaby} which {Mode} to use for a given model.
     class ModeMapper
       extend Classifier
 
-      # @param class_names [Wallaby::ClassArray] mode class names
+      # @param class_names [ClassArray] mode class names
       # @return [WallabyClassHash]
       def self.execute(class_names)
         ClassHash.new.tap do |hash|

data/lib/services/wallaby/map/model_class_mapper.rb

@@ -5,7 +5,7 @@ module Wallaby
     # Go through the class list and generate a {.map .map} that uses the class's model_class as the key.
     class ModelClassMapper
       # @param class_array [Array<Class>]
-      # @return [Wallaby::ClassHash] model class => descendant class
+      # @return [ClassHash] model class => descendant class
       def self.map(class_array)
         (class_array || EMPTY_ARRAY).each_with_object(ClassHash.new) do |klass, hash|
           next if ModuleUtils.anonymous_class?(klass)

data/lib/services/wallaby/model_class_filter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Wallaby
+  # Fitler the model classes using
+  class ModelClassFilter
+    class << self
+      # @param all [Array<Class>]
+      # @param allowlisted [Array<Class>]
+      # @param denylisted [Array<Class>]
+      def execute(all:, allowlisted:, denylisted:)
+        invalid, valid =
+          allowlisted.present? ? [allowlisted - all, allowlisted] : [denylisted - all, all - denylisted]
+        return valid if invalid.blank?
+
+        raise InvalidError, <<~INSTRUCTION
+          Wallaby can't handle these models: #{invalid.map(&:name).to_sentence}.
+          If it's set via controller_class.models= or controller_class.models_to_exclude=,
+          please remove them from the list.
+
+          Or they can be added to Custom model list as below, and custom implementation will be required:
+
+            Wallaby.config do |config|
+              config.custom_models = #{invalid.map(&:name).join ', '}
+            end
+        INSTRUCTION
+      end
+    end
+  end
+end

data/lib/services/wallaby/paginator_finder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Wallaby
+  # (see #execute)
+  class PaginatorFinder < ServicerFinder
+    # Find paginator class by script name and model class from the following places:
+    #
+    # - {#current_controller_class #current_controller_class}'s
+    #   {Configurable::ClassMethods#model_paginator #model_paginator}
+    # - possible paginator class built from script name and model class,
+    #   e.g. **/admin** and **Order::Item** will give us the possible paginators:
+    #   - Admin::Order::ItemPaginator
+    #   - Order::ItemPaginator
+    #   - ItemPaginator
+    # - {#current_controller_class #current_controller_class}'s default
+    #   {Configurable::ClassMethods#application_paginator #application_paginator}
+    # @return [Class] paginator class
+    def execute
+      current_controller_class.model_paginator ||
+        possible_default_class ||
+        current_controller_class.application_paginator
+    end
+  end
+end

data/lib/services/wallaby/prefixes_builder.rb

@@ -1,32 +1,73 @@
 # frozen_string_literal: true
 
 module Wallaby
-  # To extend prefixes to provide more possibility
+  # (see #execute)
   class PrefixesBuilder
     include ActiveModel::Model
 
+    delegate :controller_path, to: :controller_class
+
+    # @!attribute prefixes
+    # @return [Array<String>]
     attr_accessor :prefixes
+    # @!attribute resources_name
+    # @return [String, nil]
     attr_accessor :resources_name
+    # @!attribute script_name
+    # @return [String]
     attr_accessor :script_name
+    # @!attribute controller_class
+    # @return [String]
+    attr_accessor :controller_class
 
+    # To extend prefixes to be able to look up the directory
+    # even if the custom controller doesn't not exist
+    # @return [Array<String>] modified prefixes
     def execute
-      return if prefixes.include? resources_path
+      return prefixes_dup unless resourceful?
+      return prefixes_dup if possible_resources_path == controller_path
 
-      full_prefix = [script_path, resources_path].compact.join(SLASH)
+      prefixes_dup.insert(
+        prefixes_dup.index(controller_path) + offset,
+        possible_resources_path
+      )
+    end
 
-      return if prefixes.include? full_prefix
+    protected
 
-      prefixes.insert 0, full_prefix
+    # @return [Array<String>]
+    def prefixes_dup
+      @prefixes_dup ||= prefixes.dup
     end
 
-    private
+    # @return [Boolean]
+    def resourceful?
+      resources_name.present?
+    end
+
+    # @return [Boolean]
+    def based_controller?
+      controller_class.model_class.blank?
+    end
+
+    # @return [Integer] 0 or 1
+    def offset
+      based_controller? ? 0 : 1
+    end
+
+    # @return [String]
+    def possible_resources_path
+      [script_path, resources_path].compact.join(SLASH)
+    end
 
+    # @return [String, nil]
     def resources_path
-      @resources_path ||= resources_name.try :gsub, COLONS, SLASH
+      resources_name.try(:gsub, COLONS, SLASH)
     end
 
+    # @return [String, nil]
     def script_path
-      @script_path ||= script_name.try :[], 1..-1
+      script_name.try(:[], 1..-1)
     end
   end
 end

data/lib/services/wallaby/servicer_finder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wallaby
+  # (see #execute)
+  class ServicerFinder < ControllerFinder
+    # Find servicer class by script name and model class from the following places:
+    #
+    # - {#current_controller_class #current_controller_class}'s
+    #   {Configurable::ClassMethods#model_servicer #model_servicer}
+    # - possible servicer class built from script name and model class,
+    #   e.g. **/admin** and **Order::Item** will give us the possible servicers:
+    #   - Admin::Order::ItemServicer
+    #   - Order::ItemServicer
+    #   - ItemServicer
+    # - {#current_controller_class #current_controller_class}'s default
+    #   {Configurable::ClassMethods#application_servicer #application_servicer}
+    # @return [Class] servicer class
+    def execute
+      current_controller_class.model_servicer ||
+        possible_default_class ||
+        current_controller_class.application_servicer
+    end
+
+    protected
+
+    # (see ClassFinder#denamespace?)
+    def denamespace?
+      true
+    end
+  end
+end

data/lib/services/wallaby/sorting/hash_builder.rb

@@ -14,6 +14,15 @@ module Wallaby
           (sort_string || EMPTY_STRING).scan(SORT_REGEX) { |_, key, order| hash[key] = order }
         end
       end
+
+      def self.to_str(hash)
+        hash.each_with_object(EMPTY_STRING.dup) do |(name, sort), str|
+          next unless /\A(asc|desc)( nulls (first|last))?\Z/i.match?(sort)
+
+          str << (str == EMPTY_STRING ? str : COMMA)
+          str << name.to_s << SPACE << sort << (block_given? ? yield(name) : EMPTY_STRING)
+        end
+      end
     end
   end
 end

data/lib/services/wallaby/sorting/link_builder.rb

@@ -9,7 +9,7 @@ module Wallaby
       delegate :model_class, to: :@model_decorator
       delegate :index_link, :url_for, to: :@helper
 
-      # @param model_decorator [Wallaby::ModelDecorator]
+      # @param model_decorator [ModelDecorator]
       # @param params [ActionController::Parameters]
       # @param helper [ActionView::Helpers]
       def initialize(model_decorator, params, helper, strategy)
@@ -28,15 +28,11 @@ module Wallaby
 
       # Build sort link for given field name:
       #
-      # ```
-      # <a title="Product" href="/admin/products?sort=published_at+asc">Name</a>
-      # ```
+      #     <a title="Product" href="/admin/products?sort=published_at+asc">Name</a>
       #
       # If the field is not sortable, it returns a text, e.g.:
       #
-      # ```
-      # Name
-      # ```
+      #     Name
       # @param field_name [String]
       # @return [String] link or text
       def build(field_name)
@@ -46,13 +42,14 @@ module Wallaby
 
         sort_field_name = metadata[:sort_field_name] || field_name
         url_params = next_builder.next_params sort_field_name
-        url = url_for url_params.merge(with_query: true)
-        index_link(model_class, options: { url: url }) { label }
+        index_link(
+          model_class, url_params: url_params.merge(with_query: true)
+        ) { label }
       end
 
       private
 
-      # @return [Wallaby::Sorting::NextBuilder]
+      # @return [Sorting::NextBuilder]
       def next_builder
         @next_builder ||= begin
           klass = SORT_STRATEGIES[@strategy] || NextBuilder

data/lib/services/wallaby/sorting/next_builder.rb

@@ -35,18 +35,7 @@ module Wallaby
         hash = @hash.except field_name
         current_sort = @hash[field_name]
         hash[field_name] = next_value_for current_sort
-        rebuild_str_from hash
-      end
-
-      # @param hash [Hash] sort order hash
-      # @return [String] a sort order string, e.g. `'name asc'`
-      def rebuild_str_from(hash)
-        hash.each_with_object(EMPTY_STRING.dup) do |(name, sort), str|
-          next unless sort
-
-          str << (str == EMPTY_STRING ? str : COMMA)
-          str << name.to_s << SPACE << sort
-        end
+        HashBuilder.to_str(hash)
       end
 
       # @param current [String, nil] current sort order

data/lib/services/wallaby/sorting/single_builder.rb

@@ -13,7 +13,7 @@ module Wallaby
         hash = {}
         current_sort = @hash[field_name]
         hash[field_name] = next_value_for current_sort
-        rebuild_str_from hash
+        HashBuilder.to_str(hash)
       end
     end
   end

data/lib/support/action_dispatch/routing/mapper.rb

@@ -2,8 +2,33 @@
 
 module ActionDispatch
   module Routing
-    # Re-open `ActionDispatch::Routing::Mapper` to add route helpers for Wallaby.
+    # Re-open {https://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper.html
+    # ActionDispatch::Routing::Mapper}
+    # to add route helpers for {Wallaby}.
     class Mapper
+      # Mount {Wallaby::Engine} at given path.
+      # And prepend custom routes to Rails app if block is given.
+      # @example Mount {Wallaby::Engine} at a path
+      #   wallaby_mount at: '/admin'
+      # @example Mount {Wallaby::Engine} and prepend custom routes
+      #   wallaby_mount at: '/super_admin' do
+      #     resource :accounts
+      #   end
+      #   # the above code is the same as:
+      #   namespace :super_admin do
+      #     resource :accounts
+      #   end
+      #   mount Wallaby::Engine, at: '/super_admin'
+      # @param options [Hash]
+      # @option options [String] :at the path which {Wallaby::Engine} is mounted at
+      # @option options [Symbol, String] :as {Wallaby::Engine} alias name for URL helpers
+      # @option options [Array] :via HTTP methods that {Wallaby::Engine} processes
+      def wallaby_mount(options, &block)
+        # define routes under namespace (e.g. `:admin`) before mounting the {Wallaby:Engine} (e.g. at `/admin`)
+        namespace(options[:at][1..] || '', options.except(:at), &block) if block
+        mount Wallaby::Engine, options.slice(:at, :as, :via)
+      end
+
       # Generate **resourceful** routes that works for Wallaby.
       # @example To generate resourceful routes that works for Wallaby:
       #   wresources :postcodes
@@ -53,7 +78,7 @@ module ActionDispatch
       # @param options [Hash]
       def wallaby_resources_options_for(resources_name, options)
         { path: ':resources' }.merge!(options).tap do |new_options|
-          %i(defaults constraints).each do |key|
+          %i[defaults constraints].each do |key|
             new_options[key] = { resources: resources_name }.merge!(new_options[key] || {})
           end
         end
@@ -63,9 +88,9 @@ module ActionDispatch
       # @param resource_name [String, Symbol]
       # @param options [Hash]
       def wallaby_resource_options_for(resource_name, options)
-        plural_resources = Wallaby::ModelUtils.to_resources_name resource_name
+        plural_resources = Wallaby::Inflector.to_resources_name resource_name
         { path: ':resource' }.merge!(options).tap do |new_options|
-          %i(defaults constraints).each do |key|
+          %i[defaults constraints].each do |key|
             new_options[key] = { resource: resource_name, resources: plural_resources }.merge!(new_options[key] || {})
           end
         end

data/lib/utils/wallaby/field_utils.rb

@@ -7,8 +7,8 @@ module Wallaby
       # Find the first field that meets the first condition.
       # @example to find the possible text field
       #   Wallaby::FieldUtils.first_field_by({ name: /name|title/ }, { type: 'string' }, fields)
-      #   # => if any field name that has `name` or `title`, return this field
-      #   # => otherwise, find the first field that has type `string`
+      #   # => if any field name that includes `name` or `title`, return this field
+      #   # => otherwise, find the first field whose type is `string`
       # @param conditions [Array<Hash>]
       # @param fields [Hash] field metadata
       # @return [String, Symbol] field name
@@ -17,25 +17,26 @@ module Wallaby
 
         conditions.each do |condition|
           fields.each do |field_name, metadata|
-            return field_name if meet? field_name, metadata.with_indifferent_access, condition
+            return field_name if meet? condition, field_name, metadata
           end
         end
+
         nil
       end
 
       protected
 
+      # @param condition [Hash]
       # @param field_name [String]
       # @param metadata [Hash]
-      # @param condition [Hash]
       # @return [true] if field's metadata meets the condition
       # @return [true] otherwise
-      def meet?(field_name, metadata, condition)
+      def meet?(condition, field_name, metadata)
         condition.all? do |key, requirement|
-          operator = requirement.is_a?(::Regexp) ? '=~' : '=='
-          value = metadata[key]
+          value = metadata.with_indifferent_access[key]
           value ||= field_name.to_s if key.to_sym == :name
-          ModuleUtils.try_to value, operator, requirement
+          value = value.to_s if value.is_a? Symbol
+          requirement === value
         end
       end
     end

data/lib/utils/wallaby/inflector.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Wallaby
+  # Convert strings
+  module Inflector
+    extend self
+
+    # @param name [String]
+    # @return [String] class name
+    # @return [nil] if name is blank
+    def to_class_name(name)
+      return EMPTY_STRING if name.blank?
+
+      name = name.to_s unless name.is_a?(String)
+      name.gsub(COLONS, SLASH).classify
+    end
+
+    # @param script_name [String]
+    # @param resources_name [Class,String]
+    # @param suffix [String,nil]
+    # @return [String] generate the prefix for all classes
+    def to_script(script_name, resources_name, suffix = nil)
+      normalized_suffix = suffix.try(:underscore).try(:gsub, /\A_?/, UNDERSCORE)
+      "#{script_name}/#{resources_name}#{normalized_suffix}".gsub(%r{\A/+}, EMPTY_STRING)
+    end
+
+    # @param script_name [String]
+    # @param resources_name [Class,String]
+    # @return [String] controller name
+    def to_controller_name(script_name, resources_name)
+      to_class_name(to_script(script_name, to_resources_name(resources_name), CONTROLLER))
+    end
+
+    # @param script_name [String]
+    # @param resources_name [Class,String]
+    # @return [String] decorator name
+    def to_decorator_name(script_name, resources_name)
+      to_class_name(to_script(script_name, to_resource_name(resources_name), DECORATOR))
+    end
+
+    # @param script_name [String]
+    # @param resources_name [Class,String]
+    # @return [String] authorizer name
+    def to_authorizer_name(script_name, resources_name)
+      to_class_name(to_script(script_name, to_resource_name(resources_name), AUTHORIZER))
+    end
+
+    # @param script_name [String]
+    # @param resources_name [Class,String]
+    # @return [String] servicer name
+    def to_servicer_name(script_name, resources_name)
+      to_class_name(to_script(script_name, to_resource_name(resources_name), SERVICER))
+    end
+
+    # @param script_name [String]
+    # @param resources_name [Class,String]
+    # @return [String] paginator name
+    def to_paginator_name(script_name, resources_name)
+      to_class_name(to_script(script_name, to_resource_name(resources_name), PAGINATOR))
+    end
+
+    # @param name [Class, String]
+    # @return [String] resources name
+    def to_resources_name(name)
+      return EMPTY_STRING if name.blank?
+
+      name = name.to_s unless name.is_a?(String)
+      name.tableize.gsub(SLASH, COLONS)
+    end
+
+    # @param name [Class, String]
+    # @return [String] resource name
+    def to_resource_name(name)
+      to_resources_name(name).singularize
+    end
+
+    # @param name [Class, String]
+    # @return [String] resource name
+    def to_model_name(name)
+      to_class_name(to_resource_name(name))
+    end
+
+    # Produce model label (e.g. `Namespace / Product`) for model class (e.g. `Namespace::Product`)
+    # @param model_class [Class, String] model class
+    # @return [String] model label
+    def to_model_label(model_class)
+      # TODO: change to use i18n translation
+      return EMPTY_STRING if model_class.blank?
+
+      model_class_name = to_model_name model_class
+      model_class_name.titleize.gsub(SLASH, SPACE + SLASH + SPACE)
+    end
+  end
+end

data/lib/utils/wallaby/locale.rb

@@ -11,11 +11,11 @@ module Wallaby
       # @return [String] translation
       def t(key, options = {})
         translator = options.delete(:translator) || I18n.method(:t)
-        return translator.call(key, **options) unless key.is_a?(String) || key.is_a?(Symbol)
+        return translator.call(key, options) unless key.is_a?(String) || key.is_a?(Symbol)
 
         new_key, new_defaults = normalize key, options.delete(:default)
 
-        translator.call(new_key, **{ default: new_defaults }.merge(options))
+        translator.call(new_key, default: new_defaults, **options)
       end
 
       private