super 0.0.2 → 0.0.3

data/lib/super/action_inquirer.rb

@@ -1,7 +1,20 @@
 module Super
+  # ```ruby
+  # action = Super::ActionInquirer.new(
+  #   Super::ActionInquirer.default_resources,
+  #   :index
+  # )
+  #
+  # action.read? # => true
+  # action.index? # => true
+  # action.show? # => false
+  # action.write? # => false
+  # ```
   class ActionInquirer
     attr_reader :action
 
+    # @return [Hash<Symbol, Array<Symbol>>] default settings for initialization
+    #
     def self.default_resources
       {
         read: %i[index show new edit],

data/lib/super/assets.rb

@@ -1,4 +1,5 @@
 module Super
+  # Utilities for determining whether to use Sprockets or Webpacker
   class Assets
     def self.sprockets_available?
       Gem::Dependency.new("sprockets").matching_specs.any?

data/lib/super/configuration.rb

@@ -1,4 +1,6 @@
 module Super
+  # @yield [Configuration]
+  # @return [Configuration]
   def self.configuration
     @configuration ||= Configuration.new
 
@@ -9,78 +11,91 @@ module Super
     @configuration
   end
 
-  module ConfigurationLogic
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    def initialize
-      self.class.defaults.each do |key, value|
-        if value.respond_to?(:call)
-          value = value.call
-        end
-
-        public_send("#{key}=", value)
+  # Allows setting global configuration
+  #
+  # ```ruby
+  # Super.configuration do |c|
+  #   c.title = "My Admin Site"
+  # end
+  # ```
+  class Configuration
+    module ConfigurationLogic # @api private
+      def self.included(base)
+        base.extend(ClassMethods)
       end
-    end
 
-    def configured?(attr)
-      instance_variable_defined?("@#{attr}")
-    end
+      def initialize
+        self.class.defaults.each do |key, value|
+          if value.respond_to?(:call)
+            value = value.call
+          end
 
-    module ClassMethods
-      def defaults
-        @defaults ||= {}
+          public_send("#{key}=", value)
+        end
       end
 
-      def wraps
-        @wraps ||= {}
+      def configured?(attr)
+        instance_variable_defined?("@#{attr}")
       end
 
-      def configure(attr, wrap: nil, enum: nil, **kwargs)
-        if kwargs.key?(:default)
-          defaults[attr] = kwargs[:default]
+      module ClassMethods
+        def defaults
+          @defaults ||= {}
         end
 
-        define_method(attr) do
-          if !configured?(attr)
-            raise Error::UnconfiguredConfiguration, "unconfigured: #{attr}"
+        def wraps
+          @wraps ||= {}
+        end
+
+        def configure(attr, wrap: nil, enum: nil, **kwargs)
+          if kwargs.key?(:default)
+            defaults[attr] = kwargs[:default]
           end
 
-          result = instance_variable_get("@#{attr}")
+          define_method(attr) do
+            if !configured?(attr)
+              raise Error::UnconfiguredConfiguration, "unconfigured: #{attr}"
+            end
 
-          if wrap.nil?
-            result
-          else
-            wrap.call(result)
-          end
-        end
+            result = instance_variable_get("@#{attr}")
 
-        define_method("#{attr}=") do |value|
-          if enum.is_a?(Array)
-            if !enum.include?(value)
-              raise Error::InvalidConfiguration,
-                "tried to set `#{attr}` to `#{value.inspect}`, " \
-                "expected: #{enum.join(", ")}"
+            if wrap.nil?
+              result
+            else
+              wrap.call(result)
             end
           end
 
-          instance_variable_set("@#{attr}", value)
-          value
+          define_method("#{attr}=") do |value|
+            if enum.is_a?(Array)
+              if !enum.include?(value)
+                raise Error::InvalidConfiguration,
+                  "tried to set `#{attr}` to `#{value.inspect}`, " \
+                  "expected: #{enum.join(", ")}"
+              end
+            end
+
+            instance_variable_set("@#{attr}", value)
+            value
+          end
         end
       end
     end
-  end
 
-  class Configuration
     include ConfigurationLogic
 
+    # @!attribute [rw]
     configure :title
+    # @!attribute [rw]
     configure :index_resources_per_page, default: 20
+    # @!attribute [rw]
     configure :controller_namespace, default: "admin"
+    # @!attribute [rw]
     configure :route_namespace, default: :admin, wrap: -> (val) { [val].flatten }
+    # @!attribute [rw]
     configure :asset_handler, default: -> { Super::Assets.auto }
 
+    # @api private
     def path_parts(*parts)
       route_namespace + parts
     end

data/lib/super/controls.rb

@@ -1,25 +1,41 @@
 module Super
+  # A wrapper around the per-controller Controls classes. This class often
+  # directly delegates to the per-controller classes, but it can also provide
+  # some default implementation.
   class Controls
-    def initialize(dashboard)
-      @dashboard = dashboard
+    def initialize(actual)
+      @actual = actual
     end
 
-    attr_reader :dashboard
+    attr_reader :actual
 
-    def method_missing(method_name, *args)
-      if @dashboard.respond_to?(method_name)
-        @dashboard.public_send(method_name, *args)
-      else
-        super
-      end
+    def title
+      @actual.title
     end
 
-    def respond_to_missing?(method_name, _ = false)
-      if @dashboard.respond_to?(method_name)
-        true
-      else
-        super
-      end
+    def model
+      @actual.model
+    end
+
+    # @param action [ActionInquirer]
+    def scope(action:)
+      @actual.scope(action: action)
+    end
+
+    # @param params [ActionController::Parameters]
+    # @param action [ActionInquirer]
+    def permitted_params(params, action:)
+      @actual.permitted_params(params, action: action)
+    end
+
+    # @param action [ActionInquirer]
+    def display_schema(action:)
+      @actual.display_schema(action: action)
+    end
+
+    # @param action [ActionInquirer]
+    def form_schema(action:)
+      @actual.form_schema(action: action)
     end
   end
 end

data/lib/super/display/schema_types.rb

@@ -3,25 +3,24 @@ module Super
     # This schema type is meant to be used for +#index+ or +#show+ actions to
     # transform database fields into something that is human friendly.
     #
-    # Note: The constants under "Defined Under Namespace" are considered
-    # private.
+    # ```
+    # class MembersController::Controls
+    #   # ...
     #
-    #   class MemberDashboard
-    #     # ...
-    #
-    #     def show_schema
-    #       Super::Schema.new(Super::Display::SchemaTypes.new) do |fields, type|
-    #         fields[:name] = type.dynamic { |name| name }
-    #         fields[:rank] = type.dynamic { |rank| rank }
-    #         fields[:position] = type.dynamic { |position| position }
-    #         fields[:ship] = type.dynamic { |ship| "#{ship.name} (Ship ##{ship.id})" }
-    #         fields[:created_at] = type.dynamic { |created_at| created_at.iso8601 }
-    #         fields[:updated_at] = type.dynamic { |updated_at| updated_at.iso8601 }
-    #       end
+    #   def show_schema
+    #     Super::Schema.new(Super::Display::SchemaTypes.new) do |fields, type|
+    #       fields[:name] = type.dynamic { |name| name }
+    #       fields[:rank] = type.dynamic { |rank| rank }
+    #       fields[:position] = type.dynamic { |position| position }
+    #       fields[:ship] = type.dynamic { |ship| "#{ship.name} (Ship ##{ship.id})" }
+    #       fields[:created_at] = type.dynamic { |created_at| created_at.iso8601 }
+    #       fields[:updated_at] = type.dynamic { |updated_at| updated_at.iso8601 }
     #     end
-    #
-    #     # ...
     #   end
+    #
+    #   # ...
+    # end
+    # ```
     class SchemaTypes
       class Dynamic
         def initialize(transform_block)

data/lib/super/engine.rb

@@ -1,4 +1,5 @@
 module Super
+  # Configures the host Rails app to work with Super
   class Engine < ::Rails::Engine
     initializer "super.assets.precompile" do |app|
       if Super::Assets.sprockets_available?

data/lib/super/error.rb

@@ -1,4 +1,5 @@
 module Super
+  # A container class for all custom errors thrown by this library
   class Error < StandardError
     class UnconfiguredConfiguration < Error; end
     class InvalidConfiguration < Error; end

data/lib/super/form/schema_types.rb

@@ -2,33 +2,41 @@ module Super
   class Form
     # This schema type is used on your +#edit+ and +#new+ forms
     #
-    # Note: The constants under "Defined Under Namespace" are considered
-    # private.
+    # ```ruby
+    # class MembersController::Controls
+    #   # ...
     #
-    #   class MemberDashboard
-    #     # ...
-    #
-    #     def new_schema
-    #       Super::Schema.new(Super::Form::SchemaTypes.new) do |fields, type|
-    #         fields[:name] = type.generic("write_type_text")
-    #         fields[:rank] = type.generic("write_type_select", collection: Member.ranks.keys)
-    #         fields[:position] = type.generic("write_type_text")
-    #         fields[:ship_id] = type.generic(
-    #           "write_type_select",
-    #           collection: Ship.all.map { |s| ["#{s.name} (Ship ##{s.id})", s.id] },
-    #         )
-    #       end
+    #   def new_schema
+    #     Super::Schema.new(Super::Form::SchemaTypes.new) do |fields, type|
+    #       fields[:name] = type.generic("form_field_text")
+    #       fields[:rank] = type.generic("form_field_select", collection: Member.ranks.keys)
+    #       fields[:position] = type.generic("form_field_text")
+    #       fields[:ship_id] = type.generic(
+    #         "form_field_select",
+    #         collection: Ship.all.map { |s| ["#{s.name} (Ship ##{s.id})", s.id] },
+    #       )
     #     end
-    #
-    #     # ...
     #   end
+    #
+    #   # ...
+    # end
+    # ```
     class SchemaTypes
       class Generic
-        def initialize(partial_path:, extras:)
+        def initialize(partial_path:, extras:, nested:)
           @partial_path = partial_path
           @extras = extras
+          @nested_fields = nested
         end
 
+        attr_reader :nested_fields
+
+        # This takes advantage of a feature of Rails. If the value of
+        # `#to_partial_path` is `my_form_field`, Rails renders
+        # `app/views/super/application/_my_form_field.html.erb`, and this
+        # instance of Generic is accessible via `my_form_field`
+        #
+        # @return [String] the filename of the partial that will be rendered.
         def to_partial_path
           @partial_path
         end
@@ -36,11 +44,71 @@ module Super
         def [](key)
           @extras[key]
         end
+
+        def reader
+          @extras[:reader]
+        end
+
+        def label
+          if @extras.key?(:label)
+            return @extras[:label]
+          end
+
+          if @extras.key?(:reader)
+            return @extras[:reader].to_s.singularize.humanize
+          end
+        end
+
+        def ==(other)
+          return false if other.class != self.class
+          return false if other.instance_variable_get(:@partial_path) != @partial_path
+          return false if other.instance_variable_get(:@extras) != @extras
+          return false if other.instance_variable_get(:@nested) != @nested
+
+          true
+        end
       end
 
-      def generic(partial_path, extras = nil)
-        extras ||= {}
-        Generic.new(partial_path: partial_path, extras: extras)
+      def setup(fields:)
+        @fields = fields
+      end
+
+      def generic(partial_path, **extras)
+        Generic.new(partial_path: partial_path, extras: extras, nested: {})
+      end
+
+      def has_many(reader, **extras)
+        nested = @fields.nested do
+          yield
+        end
+
+        Generic.new(
+          partial_path: "form_has_many",
+          extras: extras.merge(reader: reader),
+          nested: nested
+        )
+      end
+
+      def has_one(reader, **extras)
+        nested = @fields.nested do
+          yield
+        end
+
+        Generic.new(
+          partial_path: "form_has_one",
+          extras: extras.merge(reader: reader),
+          nested: nested
+        )
+      end
+
+      alias_method :belongs_to, :has_one
+
+      def _destroy(**extras)
+        Generic.new(
+          partial_path: "form_field__destroy",
+          extras: extras,
+          nested: {}
+        )
       end
     end
   end

data/lib/super/navigation/automatic.rb

@@ -1,5 +1,7 @@
 module Super
   class Navigation
+    # Traverses the defined Rails Routes and attempts to build a list of links.
+    # This is used for building the nav bar on each admin page.
     class Automatic
       def initialize(route_namespace:)
         route_namespace = route_namespace.to_s

data/lib/super/schema.rb

@@ -8,7 +8,11 @@ module Super
     # @param schema_type [Display::SchemaTypes, Form::SchemaTypes]
     def initialize(schema_type)
       @schema_type = schema_type
-      @fields = {}
+      @fields = Fields.new
+
+      if @schema_type.respond_to?(:setup)
+        @schema_type.setup(fields: @fields)
+      end
 
       if block_given?
         yield(@fields, @schema_type)
@@ -20,5 +24,50 @@ module Super
     def field_keys
       fields.keys
     end
+
+    class Fields
+      include Enumerable
+
+      def initialize
+        @backing = {}
+      end
+
+      def [](key)
+        @backing[key]
+      end
+
+      def []=(key, value)
+        @backing[key] = value
+      end
+
+      def keys
+        @backing.keys
+      end
+
+      def each
+        if block_given?
+          return @backing.each(&Proc.new)
+        end
+
+        enum_for(:each)
+      end
+
+      def replace(other)
+        @backing = other
+      end
+
+      def to_h
+        @backing
+      end
+
+      def nested
+        outside = @backing
+        inside = {}
+        @backing = inside
+        yield
+        @backing = outside
+        inside
+      end
+    end
   end
 end