formalist 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3a25ed29e5310c5707691b6e42089f845acda96d
-  data.tar.gz: ae3ec66e1957062442a116068671e7924009a49d
+SHA256:
+  metadata.gz: 1ef816ca82a212ab5b8eba60fd57c68393d1443876b527b85b507c933974fdb9
+  data.tar.gz: 539b605da36b8383a5645fd191920e9c16c7ff7c6f1582dc435bf521a96366a8
 SHA512:
-  metadata.gz: 75991212d87c5a71fc2b8805fc9b1905c271d50e29684ffb65484ae37e70e3adada85a561e42feab49414da1fb91c4ba7d038ee82c30c352f07c2318c706d8b6
-  data.tar.gz: 344e4392c1b1d8749c2520397451be67b143a5338153dfafb15ba2dbc6a3958607d20fef7f05e280df31a29300451fb28b3ffe778e0e618c0c17b47ec2c9d4b8
+  metadata.gz: 9c23dd6b7f40ead5fa9fd81008bef073a7b94fe3e98738f3a03a22733e7a732b5e1ba92e0ec26cc66cf41380a96155c643144e90f450500f8039e8fa0e663087
+  data.tar.gz: e58de764348c401f5321864f761e421415536a31e607ea13567d2e0374c563125162c395f4ed0d70488c026c44b841f655fd43fba359e8cc18565a0349f3aa39

data/.gitignore

@@ -0,0 +1,7 @@
+/.byebug_history
+/.yardoc
+/doc
+/coverage
+/spec/examples.txt
+/pkg
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,21 @@
+language: ruby
+dist: trusty
+sudo: false
+cache: bundler
+before_install:
+  - gem update bundler
+script:
+  - bundle exec rake
+after_success:
+  # Send coverage report from the job #1 == current MRI release
+- '[ "${TRAVIS_JOB_NUMBER#*.}" = "1" ] && [ "$TRAVIS_BRANCH" = "master" ] && bundle exec codeclimate-test-reporter'
+rvm:
+  - 2.4.0
+  - 2.3.3
+  - 2.2.6
+  - jruby-9.1.6.0
+addons:
+  code_climate:
+    repo_token: 2c2c7c253435c02667371778ca886b069d4d24590748fbd7396b9b080016bfa7
+notifications:
+  email: false

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# 0.4.0 / 2018-03-28
+
+### Added
+
+- `rich_text_area` field type, support for embedding and validating forms within rich text areas, and rendering the rich text from its native draft.js AST format to HTML
+- `search_selection_field` and `multi_search_selection_field` field types
+- Various improvements to the upload fields, including support for passing `presign_options`
+
+### Changed
+
+- [BREAKING] Form definition blocks are now evaluated within the context of the form instance's `self`, which mean dependencies can be injected into the form object and accessed from the form definition block. `#dep` within the definition block has thusly been removed.
+- [BREAKING] `Formalist::Form` should now be instantiated (`form = MyForm.new`) and then filled with `form.fill(input: input_data, errors: error_messages)`. `Form#fill` returns a copy of the form object with all the elements filled with the input data and error messages as required. `Form#call` has been removed, along with `Formalist::Form::Result` (which was the object returned from `#call`).
+
+### Removed
+
+- Form elements no longer have a `permitted_children` config. For now, this should be handled by convention only.
+
+# 0.3.0 / 2016-05-04
+
+Add support for upload and multi upload fields.
+
+# 0.2.3 / 2016-04-07
+
+Default check_box element values to false.
+
+# 0.2.2 / 2016-02-23
+
+Remove local type coercion using dry-data. We rely on a `Dry::Validation::Schema` to do this now. The form definition API has not yet changed, though. We still require field types to be specified, but there is no longer any restriction over what is entered. We'll remove this in a future release, once we can infer types from the schema.
+
+# 0.2.1 / 2016-02-23
+
+Fix issue where form could not be built with input data with native data types (it presuming input would be HTML form-style input everywhere).
+
+Add default (empty) input data argument for `Form#build`. This allows you simply to call `MyForm.build` for creating a "new" form (i.e. one without any existing input data).
+
+# 0.2.0 / 2016-02-22
+
+Require a dry-validation schema for each form. The schema should completely represent the form's expected data structure.
+
+Update the API to better support the two main use cases for a form. First, to prepare a form with sane, initial input from your database and send it to a view for rendering:
+
+```ruby
+my_form = MyForm.new(my_schema)
+my_form.build(input) # returns a `Formalist::Form::Result`
+```
+
+Then, to receive the data from the posted form, coerce it and validate it (and potentially re-display the form with errors):
+
+```ruby
+my_form = MyForm.new(my_schema)
+my_form.receive(input).validate # returns a `Formalist::Form::ValidatedResult`
+```
+
+The main differences are as such:
+
+* `#build` expects already-clean (e.g. properly structured and typed) data
+* `#receive` expects the kind of data that your form will submit, and will then coerce it according to the validation schema, and then send the sanitised output to `#build`
+* Calling `#validate` on a result object will validate the input data and include any error messages in its AST
+
+# 0.1.0 / 2016-01-18
+
+Initial release.

data/Gemfile

@@ -5,8 +5,7 @@ gemspec
 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"
+  gem "dry-validation", "~> 0.11"
 end
 
 group :tools do

data/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+
+require "pry"
+begin
+  require "byebug"
+rescue LoadError; end
+require "formalist"
+require "formalist/elements/standard"
+require "dry-validation"
+
+Pry.start

data/formalist.gemspec

@@ -0,0 +1,33 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "formalist/version"
+
+Gem::Specification.new do |spec|
+  spec.name           = "formalist"
+  spec.version        = Formalist::VERSION
+  spec.authors        = ["Tim Riley"]
+  spec.email          = ["tim@icelab.com.au"]
+  spec.license        = "MIT"
+
+  spec.summary        = "Flexible form builder"
+  spec.homepage       = "https://github.com/icelab/formalist"
+
+  spec.files          = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir         = 'exe'
+  spec.executables    = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths  = ['lib']
+
+  spec.required_ruby_version = ">= 2.2.0"
+
+  spec.add_runtime_dependency "dry-configurable", "~> 0.7"
+  spec.add_runtime_dependency "dry-core", "~> 0.4"
+  spec.add_runtime_dependency "dry-container", "~> 0.6"
+  spec.add_runtime_dependency "dry-types", "~> 0.12"
+  spec.add_runtime_dependency "inflecto"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.4.2"
+  spec.add_development_dependency "rspec", "~> 3.3.0"
+  spec.add_development_dependency "simplecov", "~> 0.13.0"
+  spec.add_development_dependency "yard"
+end

data/lib/formalist/definition.rb

@@ -0,0 +1,65 @@
+module Formalist
+  class Definition
+    DuplicateElementError = Class.new(StandardError)
+
+    attr_reader :form
+    attr_reader :config
+    attr_reader :elements
+
+    def initialize(form, config, &block)
+      @form = form
+      @config = config
+      @elements = []
+
+      instance_eval(&block) if block
+    end
+
+    def with(**new_options, &block)
+      new_config = new_options.each_with_object(config.dup) { |(key, value), config|
+        config.send :"#{key}=", value
+      }
+
+      self.class.new(form, new_config, &block)
+    end
+
+    def method_missing(name, *args, &block)
+      if element_type?(name)
+        add_element(name, *args, &block)
+      elsif form.respond_to?(name)
+        form.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    private
+
+    def respond_to_missing?(name, _include_private = false)
+      element_type?(name) || form.respond_to?(name)
+    end
+
+    def element_type?(type)
+      config.elements_container.key?(type)
+    end
+
+    def add_element(type, *args, &block)
+      element_name = args.shift unless args.first.is_a?(Hash)
+      element_attrs = args.last.is_a?(Hash) ? args.last : {}
+
+      if element_name && elements.any? { |element| element.name == element_name }
+        raise DuplicateElementError, "element +#{element_name}+ is already defined in this context"
+      end
+
+      element_class = config.elements_container[type]
+      element_children = with(&block).elements
+
+      element = element_class.build(
+        name: element_name,
+        attributes: element_attrs,
+        children: element_children,
+      )
+
+      elements << element
+    end
+  end
+end

data/lib/formalist/element/class_interface.rb

@@ -1,28 +1,23 @@
 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
+      # Returns the element's type, which is a symbolized, underscored
       # 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.
+      # This is important for 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 Basic element Formalist::Elements::Field.type # => :field
       #
-      # @example Custom element
-      #   class MyField < Formalist::Elements::Field
-      #   end
+      # @example Custom element class MyField < Formalist::Elements::Field end
       #
       #   MyField.type # => :my_field
       #
-      # @!scope class
-      # @return [Symbol] the element type.
+      # @!scope class @return [Symbol] the element type.
       def type
         Inflecto.underscore(Inflecto.demodulize(name)).to_sym
       end
@@ -71,53 +66,6 @@ module Formalist
         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

data/lib/formalist/element.rb

@@ -7,42 +7,60 @@ module Formalist
     extend ClassInterface
 
     # @api private
-    attr_reader :attributes, :children, :input, :errors
+    attr_reader :name, :attributes, :children, :input, :errors
 
     # @api private
-    def initialize(*args, attributes, children, input, errors)
+    def self.build(**args)
+      new(args)
+    end
+
+    # @api private
+    def self.fill(input: {}, errors: {}, **args)
+      new(args).fill(input: input, errors: errors)
+    end
+
+    # @api private
+    def initialize(name: nil, attributes: {}, children: [], input: nil, errors: [])
+      @name = Types::ElementName[name]
+
       # Set supplied attributes or their defaults
-      full_attributes = self.class.attributes_schema.each_with_object({}) { |(name, defn), memo|
+      all_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)
+      @attributes = Types::Hash.schema(
+        self.class.attributes_schema.map { |name, defn| [name, defn[:type]] }.to_h
+      )[all_attributes]
 
-      @children = []
+      @children = 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 fill(input: {}, errors: {}, **args)
+      return self if input == @input && errors == @errors
+
+      args = {
+        name: @name,
+        attributes: @attributes,
+        children: @children,
+        input: input,
+        errors: errors,
+      }.merge(args)
+
+      self.class.new(args)
+    end
+
     def type
       self.class.type
     end
 
+    def ==(other)
+      name && type == other.type && name == other.name
+    end
+
     # @abstract
     def to_ast
       raise NotImplementedError

data/lib/formalist/elements/attr.rb

@@ -4,21 +4,17 @@ 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
+      def fill(input:, errors:)
+        input = input[name] || {}
+        errors = errors[name] || {}
 
-        @name = Types::ElementName.(args.first)
-        @input = input.fetch(@name, {})
-        @errors = errors[@name]
-        @children = build_children(children)
+        children = self.children.map { |child|
+          child.fill(input: input, errors: errors)
+        }
+
+        super(input: input, errors: errors, children: children)
       end
 
       # Converts the attribute into an abstract syntax tree.
@@ -61,14 +57,6 @@ module Formalist
           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

@@ -4,11 +4,12 @@ require "formalist/types"
 module Formalist
   class Elements
     class CompoundField < Element
-      permitted_children :field
+      def fill(input: {}, errors: {})
+        children = self.children.map { |child|
+          child.fill(input: input, errors: errors)
+        }
 
-      def initialize(*args, attributes, children, input, errors)
-        super
-        @children = children.map { |definition| definition.(input, errors) }
+        super(input: input, errors: errors, children: children)
       end
 
       # Converts the compound field into an abstract syntax tree.

data/lib/formalist/elements/field.rb

@@ -4,11 +4,6 @@ require "formalist/types"
 module Formalist
   class Elements
     class Field < Element
-      permitted_children :none
-
-      # @api private
-      attr_reader :name
-
       attribute :label, Types::String
       attribute :hint, Types::String
       attribute :placeholder, Types::String
@@ -18,13 +13,11 @@ module Formalist
       # @api private
       attr_reader :predicates
 
-      # @api private
-      def initialize(*args, attributes, children, input, errors)
-        super
-
-        @name = Types::ElementName.(args.first)
-        @input = input[@name] if input
-        @errors = errors[@name].to_a
+      def fill(input: {}, errors: {})
+        super(
+          input: input[name],
+          errors: errors[name].to_a,
+        )
       end
 
       # Converts the field into an abstract syntax tree.

data/lib/formalist/elements/group.rb

@@ -4,13 +4,14 @@ require "formalist/types"
 module Formalist
   class Elements
     class Group < Element
-      permitted_children :attr, :compound_field, :field, :many
-
       attribute :label, Types::String
 
-      def initialize(*args, attributes, children, input, errors)
-        super
-        @children = children.map { |definition| definition.(input, errors) }
+      def fill(input: {}, errors: {})
+        children = self.children.map { |child|
+          child.fill(input: input, errors: errors)
+        }
+
+        super(input: input, errors: errors, children: children)
       end
 
       # Converts the group into an abstract syntax tree.

data/lib/formalist/elements/many.rb

@@ -4,11 +4,6 @@ require "formalist/types"
 module Formalist
   class Elements
     class Many < Element
-      permitted_children :attr, :compound_field, :group, :field
-
-      # @api private
-      attr_reader :name
-
       attribute :label, Types::String
       attribute :action_label, Types::String
       attribute :placeholder, Types::String
@@ -18,14 +13,35 @@ module Formalist
       attr_reader :child_template
 
       # @api private
-      def initialize(*args, attributes, children, input, errors)
-        super
+      def self.build(children: [], **args)
+        child_template = children.dup
+        super(child_template: child_template, **args)
+      end
+
+      # @api private
+      def initialize(child_template:, **args)
+        @child_template = child_template
+        super(**args)
+      end
+
+      # @api private
+      def fill(input: {}, errors: {})
+        input = input.fetch(name) { [] }
+        errors = errors.fetch(name) { {} }
+
+        children = input.each_with_index.map { |child_input, index|
+          # Child errors look like this: {0=>{:summary=>["must be filled"]}
+          child_errors = errors.fetch(index) { {} }
 
-        @name = Types::ElementName.(args.first)
-        @input = input.fetch(name, [])
-        @errors = errors[@name]
-        @child_template = build_child_template(children)
-        @children = build_children(children)
+          child_template.map { |child| child.fill(input: child_input, errors: child_errors) }
+        }
+
+        super(
+          input: input,
+          errors: errors,
+          children: children,
+          child_template: child_template,
+        )
       end
 
       # Until we can put defaults on `Types::Bool`, supply them here
@@ -103,23 +119,6 @@ module Formalist
           children.map { |el_list| el_list.map(&:to_ast) },
         ]]
       end
-
-      private
-
-      def build_child_template(definitions)
-        definitions.map { |el| el.({}, {})}
-      end
-
-      def build_children(definitions)
-        # Child errors look like this: {0=>{:summary=>["must be filled"]}
-        child_errors = errors.is_a?(Hash) ? errors : {}
-
-        input.each_with_index.map { |child_input, index|
-          errors = child_errors.fetch(index, {})
-
-          definitions.map { |el| el.(child_input, errors) }
-        }
-      end
     end
   end
 end

data/lib/formalist/elements/section.rb

@@ -4,18 +4,14 @@ require "formalist/types"
 module Formalist
   class Elements
     class Section < Element
-      permitted_children :all
-
-      # @api private
-      attr_reader :name
-
       attribute :label, Types::String
 
-      def initialize(*args, attributes, children, input, errors)
-        super
-
-        @name = Types::ElementName.(args.first)
-        @children = children.map { |definition| definition.(input, errors) }
+      def fill(input: {}, errors: {})
+        super(
+          input: input,
+          errors: errors,
+          children: children.map { |child| child.fill(input: input, errors: errors) },
+        )
       end
 
       # Converts the section into an abstract syntax tree.

data/lib/formalist/elements/standard/multi_upload_field.rb

@@ -6,6 +6,14 @@ module Formalist
   class Elements
     class MultiUploadField < Field
       attribute :presign_url, Types::String
+      attribute :presign_options, Types::Hash
+      attribute :render_uploaded_as, Types::String
+      attribute :upload_prompt, Types::String
+      attribute :upload_action_label, Types::String
+      attribute :max_file_size, Types::String
+      attribute :max_file_size_message, Types::String
+      attribute :permitted_file_type_message, Types::String
+      attribute :permitted_file_type_regex, Types::String
     end
 
     register :multi_upload_field, MultiUploadField