formalist 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 213025004cb07e1b9962e338b59d4170e2f20c9d
-  data.tar.gz: f17a38dd7de60b6672ec18027b988119b73be9f3
+  metadata.gz: 96b43ff385384015c3c6c1cac64a8e9cccaa753c
+  data.tar.gz: 42acab631e93a3c52c73de8a5822c96622e7b2af
 SHA512:
-  metadata.gz: dafc943fc98d96e5a671b81ebbe6be0eebc20a9ab3f9558bae54ae4c8535cd542cb1e56b304dc6c89494b3f4d410694063192e993a51c79748d3aea2fa9b6681
-  data.tar.gz: b0bf744c37494e443e294f25d0a8cc4f549955149ffa205e44be3ccee791d0b53fc60ca5bfd3471ce6ed80c1dac277c5dcac36fa606eeccf82526e2e5d314707
+  metadata.gz: 1cdeb2f130a14bceb9a8af2a71fcf22c463c1fc1554b42fc98ccc20bb826804853004553a3cee82114500ba49139d4413adb0ab3855cae19f73c2fa2a06e4594
+  data.tar.gz: b87cd081725b0fe4556858d33b8648f0dead749122d74f2e5371eb720958d5610deb104e0de09a6d1341d4ec7825a01907aad807072ac2747d2536c852505b87

data/Gemfile

@@ -1,11 +1,15 @@
 source "https://rubygems.org"
 
-# Gem dependencies are specified in formalist.gemspec
 gemspec
 
-# Lock to a version of dry-v that'll offer the AST/error message structures we expect
-gem "dry-validation", git: "https://github.com/dryrb/dry-validation", ref: "6447302f3b53766b29f29230831890a5cc3822e0"
+group :test do
+  gem "codeclimate-test-reporter", require: nil
+  gem "dry-auto_inject"
+  gem "dry-validation", git: "https://github.com/dryrb/dry-validation", branch: "master"
+  gem "dry-types", git: "https://github.com/dryrb/dry-types", branch: "master"
+end
 
 group :tools do
   gem "pry"
+  gem "byebug", platform: :mri
 end

data/Gemfile.lock

@@ -1,63 +1,67 @@
+GIT
+  remote: https://github.com/dryrb/dry-types
+  revision: 9d72307cfaa33afa8b597646cd77a06de8b6bb88
+  branch: master
+  specs:
+    dry-types (0.7.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.1)
+      dry-container (~> 0.3)
+      dry-equalizer (~> 0.2)
+      dry-logic (~> 0.2, >= 0.2.0)
+      inflecto (~> 0.0.0, >= 0.0.2)
+      kleisli (~> 0.2)
+
 GIT
   remote: https://github.com/dryrb/dry-validation
-  revision: 6447302f3b53766b29f29230831890a5cc3822e0
-  ref: 6447302f3b53766b29f29230831890a5cc3822e0
+  revision: 6167d6f778faefe13916d3d8eee8bdb4197398d3
+  branch: master
   specs:
-    dry-validation (0.6.0)
+    dry-validation (0.7.4)
+      concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
       dry-container (~> 0.2, >= 0.2.8)
-      dry-data (~> 0.5, >= 0.5.0)
       dry-equalizer (~> 0.2)
-      dry-logic (~> 0.1, >= 0.1.4)
+      dry-logic (~> 0.2, >= 0.2.2)
+      dry-types (~> 0.6, >= 0.6.0)
 
 PATH
   remote: .
   specs:
-    formalist (0.2.2)
+    formalist (0.2.3)
       dry-configurable
       dry-container
-      dry-validation (~> 0.6.0)
+      dry-types
       inflecto
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.1.0)
-    astrolabe (1.3.1)
-      parser (~> 2.2)
-    byebug (8.2.1)
-    coderay (1.1.0)
+    byebug (8.2.3)
+    codeclimate-test-reporter (0.5.0)
+      simplecov (>= 0.7.1, < 1.0.0)
+    coderay (1.1.1)
+    concurrent-ruby (1.0.1)
     diff-lcs (1.2.5)
     docile (1.1.5)
-    dry-configurable (0.1.3)
-      thread_safe
-    dry-container (0.2.8)
+    dry-auto_inject (0.2.0)
+    dry-configurable (0.1.4)
+      concurrent-ruby (~> 1.0)
+    dry-container (0.3.1)
+      concurrent-ruby (~> 1.0)
       dry-configurable (~> 0.1, >= 0.1.3)
-      thread_safe
-    dry-data (0.5.1)
-      dry-configurable (~> 0.1)
-      dry-container (~> 0.2)
-      dry-equalizer (~> 0.2)
-      dry-logic (~> 0.1)
-      inflecto (~> 0.0.0, >= 0.0.2)
-      kleisli (~> 0.2)
-      thread_safe (~> 0.3)
     dry-equalizer (0.2.0)
-    dry-logic (0.1.4)
+    dry-logic (0.2.2)
       dry-container (~> 0.2, >= 0.2.6)
       dry-equalizer (~> 0.2)
     inflecto (0.0.2)
     json (1.8.3)
     kleisli (0.2.7)
     method_source (0.8.2)
-    parser (2.2.3.0)
-      ast (>= 1.1, < 3.0)
-    powerpack (0.1.1)
     pry (0.10.3)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
-    rainbow (2.0.0)
     rake (10.4.2)
     rspec (3.3.0)
       rspec-core (~> 3.3.0)
@@ -72,20 +76,12 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.3.0)
     rspec-support (3.3.0)
-    rubocop (0.34.2)
-      astrolabe (~> 1.3)
-      parser (>= 2.2.2.5, < 3.0)
-      powerpack (~> 0.1)
-      rainbow (>= 1.99.1, < 3.0)
-      ruby-progressbar (~> 1.4)
-    ruby-progressbar (1.7.5)
     simplecov (0.10.0)
       docile (~> 1.1.0)
       json (~> 1.8)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
     slop (3.6.0)
-    thread_safe (0.3.5)
     yard (0.8.7.6)
 
 PLATFORMS
@@ -94,12 +90,14 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.10)
   byebug
+  codeclimate-test-reporter
+  dry-auto_inject
+  dry-types!
   dry-validation!
   formalist!
   pry
   rake (~> 10.4.2)
   rspec (~> 3.3.0)
-  rubocop (~> 0.34.2)
   simplecov (~> 0.10.0)
   yard
 

data/README.md

@@ -1,20 +1,24 @@
+[gem]: https://rubygems.org/gems/formalist
 [travis]: https://travis-ci.org/icelab/formalist
+[code_climate]: https://codeclimate.com/github/icelab/formalist
+[inch]: http://inch-ci.org/github/icelab/formalist
 
 # Formalist
 
+[![Gem Version](https://img.shields.io/gem/v/formalist.svg)][gem]
 [![Build Status](https://travis-ci.org/icelab/formalist.svg?branch=master)][travis]
+[![Code Climate](https://img.shields.io/codeclimate/github/icelab/formalist.svg)][code_climate]
+[![Test Coverage](https://img.shields.io/codeclimate/coverage/github/icelab/formalist.svg)][code_climate]
+[![API Documentation Coverage](http://inch-ci.org/github/icelab/formalist.svg)][inch]
 
 ## Installation
 
-Add these lines to your application’s `Gemfile`:
+Add this line to your application’s `Gemfile`:
 
 ```ruby
-gem "dry-validation", git: "https://github.com/dryrb/dry-validation", ref: "6447302f3b53766b29f29230831890a5cc3822e0"
 gem "formalist"
 ```
 
-The dry-validation dependency is a temporary lock to a version that offers the AST/error message structures we expect. You should be able to remove this after future releases of formalist and dry-validation.
-
 Run `bundle` to install the gems.
 
 ## Contributing

data/Rakefile

@@ -3,11 +3,4 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new
 
-require "rubocop/rake_task"
-RuboCop::RakeTask.new
-
 task default: :spec
-# task default: :ci
-
-desc "Run the test suite"
-task ci: %w(rubocop spec)

data/lib/formalist/element/attributes.rb

@@ -0,0 +1,54 @@
+module Formalist
+  class Element
+    class Attributes
+      # Returns the attributes hash.
+      attr_reader :attrs
+
+      # Creates an attributes object from the supplied hash.
+      #
+      # @param attrs [Hash] hash of form element attributes
+      def initialize(attrs = {})
+        @attrs = attrs
+      end
+
+      # Returns the attributes as an abstract syntax tree.
+      #
+      # @return [Array] the abstract syntax tree
+      def to_ast
+        deep_to_ast(deep_simplify(attrs))
+      end
+
+      private
+
+      def deep_to_ast(value)
+        case value
+          when Hash
+            [:object, [value.map { |k,v| [k.to_sym, deep_to_ast(v)] }].reject(&:empty?).flatten(1)]
+          when Array
+            [:array, value.map { |v| deep_to_ast(v) }]
+          when String, Numeric, TrueClass, FalseClass, NilClass
+            [:value, [value]]
+          else
+            [:value, [value.to_s]]
+        end
+      end
+
+      def deep_simplify(value)
+        case value
+          when Hash
+            value.each_with_object({}) { |(k,v), output| output[k] = deep_simplify(v) }
+          when Array
+            value.map { |v| deep_simplify(v) }
+          when String, Numeric, TrueClass, FalseClass, NilClass
+            value
+          else
+            if value.respond_to?(:to_h)
+              deep_simplify(value.to_h)
+            else
+              value.to_s
+            end
+        end
+      end
+    end
+  end
+end

data/lib/formalist/element/class_interface.rb

@@ -0,0 +1,133 @@
+require "inflecto"
+require "formalist/element/permitted_children"
+
+module Formalist
+  class Element
+    # Class-level API for form elements.
+    module ClassInterface
+      # Returns the element's type, which is a symbolized, camlized
+      # representation of the element's class name.
+      #
+      # This is a critical hook for customising form rendering when using
+      # custom form elements, since the type in this case will be based on the
+      # name of form element's sublass.
+      #
+      # @example Basic element
+      #   Formalist::Elements::Field.type # => :field
+      #
+      # @example Custom element
+      #   class MyField < Formalist::Elements::Field
+      #   end
+      #
+      #   MyField.type # => :my_field
+      #
+      # @!scope class
+      # @return [Symbol] the element type.
+      def type
+        Inflecto.underscore(Inflecto.demodulize(name)).to_sym
+      end
+
+      # Define a form element attribute.
+      #
+      # Form element attributes can be set when the element is defined, and
+      # can be further populated by the form element object itself, when the
+      # form is being built, using both the user input and any dependencies
+      # passed to the element via the form.
+      #
+      # Attributes are the way to ensure the form renderer has all the
+      # information it needs to render the element appropriately. Attributes
+      # are type-checked in order to ensure they're being passed appropriate
+      # values. Attributes can hold any type of value as long as it can be
+      # reduced to an abstract syntax tree representation by
+      # `Form::Element::Attributes#to_ast`.
+      #
+      # @see Formalist::Element::Attributes#to_ast
+      #
+      # @!scope class
+      # @param name [Symbol] attribute name
+      # @param type [Dry::Data::Type, #call] value type coercer/checker
+      # @param default default value (applied when the attribute is not explicitly populated)
+      # @return void
+      def attribute(name, type, default: nil)
+        attributes(name => {type: type, default: default})
+      end
+
+      # Returns the attributes schema for the form element.
+      #
+      # Each item in the schema includes a type definition and a default value
+      # (`nil` if none specified).
+      #
+      # @example
+      #   Formalist::Elements::Field.attributes_schema
+      #   # => {
+      #     :name => {:type => #<Dry::Data::Type>, :default => "Default name"},
+      #     :email => {:type => #<Dry::Data::Type>, :default => "default email"}
+      #   }
+      #
+      # @!scope class
+      # @return [Hash<Symbol, Hash>] the attributes schema
+      def attributes_schema
+        super_schema = superclass.respond_to?(:attributes_schema) ? superclass.attributes_schema : {}
+        super_schema.merge(@attributes_schema || {})
+      end
+
+      # Sets or fetches the policy for the element's permitted child form elements.
+      #
+      # @overload permitted_children(policy)
+      #   Set a policy for whether the element permits child form elements.
+      #
+      #   Specify `:all` to allow all children, or `:none` to permit no
+      #   children.
+      #
+      #   @example Permitting all children
+      #     permitted_children :all
+      #
+      #   @example Permitting no children
+      #     permitted_children :none
+      #
+      #   @return void
+      #
+      # @overload permitted_children(element_type, ...)
+      #   Permit the element to contain only the specified element types as children.
+      #
+      #   @example
+      #     permit_children :section, :field
+      #
+      #   @param element_type [Symbol] the name of a child element type to permit
+      #   @param ... [Symbol] more child element types to permit
+      #   @return void
+      #
+      # @overload permitted_children
+      #   Returns the permitted child element types for the element.
+      #
+      #   If no `permitted_children` policy was previously specified, then it
+      #   allows all children by default.
+      #
+      #   @return [#permitted?] permissions object.
+      #
+      #   @see Formalist::Element::PermittedChildren
+      #
+      # @!scope class
+      def permitted_children(*args)
+        return @permitted_children ||= PermittedChildren.all if args.empty?
+
+        @permitted_children = if %i[all none].include?(args.first)
+          PermittedChildren.send(args.first)
+        else
+          PermittedChildren[args]
+        end
+      end
+
+      private
+
+      # @!scope class
+      # @api private
+      def attributes(new_schema)
+        prev_schema = @attributes_schema || {}
+        @attributes_schema = prev_schema.merge(new_schema)
+
+        self
+      end
+    end
+  end
+end

data/lib/formalist/element/definition.rb

@@ -0,0 +1,55 @@
+require "formalist/types"
+
+module Formalist
+  class Element
+    class Definition
+      Deferred = Struct.new(:name)
+
+      attr_reader :type
+      attr_reader :args
+      attr_reader :attributes
+      attr_reader :children
+
+      def initialize(type, *args, attributes, children)
+        @type = type
+        @args = args
+        @attributes = attributes
+        @children = children
+      end
+
+      def ==(other)
+        # Require a matching type.
+        return false if type != other.type
+
+        # If there are no primary args, it means that the element has no real
+        # "identifier" that requires uniqueness, so it's safe to say they don't
+        # match here.
+        return false if args.empty?
+
+        # Otherwise, use the primary args as a marker of a definitions
+        # uniqueness. With the current set of base form elements, the primary
+        # args only ever contains a name, so this is effectively a uniqueness
+        # check on the element's name.
+        args == other.args
+      end
+
+      def resolve(scope)
+        resolved_args = args.map { |arg|
+          arg.is_a?(Deferred) ? scope.send(arg.name) : arg
+        }
+
+        resolved_attributes = attributes.each_with_object({}) { |(key, val), hsh|
+          hsh[key] = val.is_a?(Deferred) ? scope.send(val.name) : val
+        }
+
+        resolved_children = children.map { |c| c.resolve(scope) }
+
+        self.class.new(type, *resolved_args, resolved_attributes, resolved_children)
+      end
+
+      def call(input, messages)
+        type.new(*args, attributes, children, input, messages)
+      end
+    end
+  end
+end

data/lib/formalist/element/permitted_children.rb

@@ -0,0 +1,46 @@
+require "inflecto"
+
+module Formalist
+  class Element
+    class PermittedChildren
+      All = Class.new do
+        def permitted?(*)
+          true
+        end
+      end.new
+
+      None = Class.new do
+        def permitted?(*)
+          false
+        end
+      end.new
+
+      class Some
+        attr_reader :permitted_children
+
+        def initialize(children)
+          @permitted_children = children
+        end
+
+        def permitted?(child)
+          permitted_children.any? { |permitted_child|
+            permitted_child_class = Elements.const_get(Inflecto.camelize(permitted_child))
+            child.ancestors.include?(permitted_child_class)
+          }
+        end
+      end
+
+      def self.all
+        All
+      end
+
+      def self.none
+        None
+      end
+
+      def self.[](children)
+        Some.new(children)
+      end
+    end
+  end
+end

data/lib/formalist/element.rb

@@ -0,0 +1,51 @@
+require "formalist/element/attributes"
+require "formalist/element/class_interface"
+require "formalist/types"
+
+module Formalist
+  class Element
+    extend ClassInterface
+
+    # @api private
+    attr_reader :attributes, :children, :input, :errors
+
+    # @api private
+    def initialize(*args, attributes, children, input, errors)
+      # Set supplied attributes or their defaults
+      full_attributes = self.class.attributes_schema.each_with_object({}) { |(name, defn), memo|
+        value = attributes[name] || defn[:default]
+        memo[name] = value unless value.nil?
+      }
+
+      # Then run them through the schema
+      @attributes = Types::Hash.schema(self.class.attributes_schema.map { |name, defn| [name, defn[:type]] }.to_h).(full_attributes)
+
+      @children = []
+      @input = input
+      @errors = errors
+    end
+
+    # Returns the element's type, which is a symbolized, camlized
+    # representation of the element's class name.
+    #
+    # This is a critical hook for customising form rendering when using custom
+    # form elements, since the type in this case will be based on the name of
+    # form element's sublass.
+    #
+    # @example Basic element
+    #   field.type # => :field
+    #
+    # @example Custom element
+    #   my_field.type # => :my_field
+    #
+    # @return [Symbol] the element type.
+    def type
+      self.class.type
+    end
+
+    # @abstract
+    def to_ast
+      raise NotImplementedError
+    end
+  end
+end

data/lib/formalist/elements/attr.rb

@@ -0,0 +1,74 @@
+require "formalist/element"
+require "formalist/types"
+
+module Formalist
+  class Elements
+    class Attr < Element
+      permitted_children :all
+
+      # @api private
+      attr_reader :name
+
+      attribute :label, Types::String
+
+      # @api private
+      def initialize(*args, attributes, children, input, errors)
+        super
+
+        @name = Types::ElementName.(args.first)
+        @input = input.fetch(@name, {})
+        @errors = errors[@name]
+        @children = build_children(children)
+      end
+
+      # Converts the attribute into an abstract syntax tree.
+      #
+      # It takes the following format:
+      #
+      # ```
+      # [:attr, [params]]
+      # ```
+      #
+      # With the following parameters:
+      #
+      # 1. Attribute name
+      # 2. Custom element type (or `:attr` otherwise)
+      # 3. Error messages
+      # 4. Form element attributes
+      # 5. Child form elements
+      #
+      # @see Formalist::Element::Attributes#to_ast "Form element attributes" structure
+      #
+      # @example "metadata" attr
+      #   attr.to_ast
+      #   # => [:attr, [
+      #     :metadata,
+      #     :attr,
+      #     ["metadata is missing"],
+      #     [:object, []],
+      #     [...child elements...]
+      #   ]]
+      #
+      # @return [Array] the attribute as an abstract syntax tree.
+      def to_ast
+        local_errors = errors.is_a?(Array) ? errors : []
+
+        [:attr, [
+          name,
+          type,
+          local_errors,
+          Element::Attributes.new(attributes).to_ast,
+          children.map(&:to_ast),
+        ]]
+      end
+
+      private
+
+      def build_children(definitions)
+        child_errors = errors.is_a?(Hash) ? errors : {}
+
+        definitions.map { |definition| definition.(input, child_errors) }
+      end
+    end
+  end
+end

data/lib/formalist/elements/compound_field.rb

@@ -0,0 +1,49 @@
+require "formalist/element"
+require "formalist/types"
+
+module Formalist
+  class Elements
+    class CompoundField < Element
+      permitted_children :field
+
+      def initialize(*args, attributes, children, input, errors)
+        super
+        @children = children.map { |definition| definition.(input, errors) }
+      end
+
+      # Converts the compound field into an abstract syntax tree.
+      #
+      # It takes the following format:
+      #
+      # ```
+      # [:compound_field, [params]]
+      # ```
+      #
+      # With the following parameters:
+      #
+      # 1. Custom element type (or `:compound_field` otherwise)
+      # 2. Form element attributes
+      # 3. Child form elements
+      #
+      # @see Formalist::Element::Attributes#to_ast "Form element attributes" structure
+      #
+      # @example
+      #   compound_field.to_ast
+      #   # => [:compound_field, [
+      #     :content,
+      #     :compound_field,
+      #     [:object, []],
+      #     [...child elements...],
+      #   ]]
+      #
+      # @return [Array] the compound field as an abstract syntax tree.
+      def to_ast
+        [:compound_field, [
+          type,
+          Element::Attributes.new(attributes).to_ast,
+          children.map(&:to_ast),
+        ]]
+      end
+    end
+  end
+end