superform 0.5.0 → 0.6.0

data/lib/superform/rails/form.rb

@@ -0,0 +1,240 @@
+module Superform
+  module Rails
+    # A Phlex::HTML view module that accepts a model and sets a `Superform::Namespace`
+    # with the `Object#model_name` as the key and maps the object to form fields
+    # and namespaces.
+    #
+    # The `Form::Field` is a class that's meant to be extended so you can customize the `Form` inputs
+    # to your applications needs. Defaults for the `input`, `button`, `label`, and `textarea` tags
+    # are provided.
+    #
+    # The `Form` component also handles Rails authenticity tokens via the `authenticity_toklen_field`
+    # method and the HTTP verb via the `_method_field`.
+    class Form < Component
+      include Phlex::Rails::Helpers::FormAuthenticityToken
+      include Phlex::Rails::Helpers::URLFor
+
+      attr_accessor :model
+
+      delegate \
+          :Field,
+          :field,
+          :collection,
+          :namespace,
+          :assign,
+          :serialize,
+        to: :@namespace
+
+      # The Field class is designed to be extended to create custom forms. To override,
+      # in your subclass you may have something like this:
+      #
+      # ```ruby
+      # class MyForm < Superform::Rails::Form
+      #   class MyLabel < Superform::Rails::Components::Label
+      #     def view_template(&content)
+      #       label(form: @field.dom.name, class: "text-bold", &content)
+      #     end
+      #   end
+      #
+      #   class Field < Field
+      #     def label(**attributes)
+      #       MyLabel.new(self, **attributes)
+      #     end
+      #   end
+      # end
+      # ```
+      #
+      # Now all calls to `label` will have the `text-bold` class applied to it.
+      class Field < Superform::Field
+        def button(**attributes)
+          Components::Button.new(self, attributes:)
+        end
+
+        def input(**attributes)
+          Components::Input.new(self, attributes:)
+        end
+
+        def text(*, **, &)
+          input(*, **, type: :text, &)
+        end
+
+        def checkbox(**attributes)
+          Components::Checkbox.new(self, attributes:)
+        end
+
+        def label(**attributes, &)
+          Components::Label.new(self, attributes:, &)
+        end
+
+        def textarea(**attributes)
+          Components::Textarea.new(self, attributes:)
+        end
+
+        def select(*collection, **attributes, &)
+          Components::Select.new(self, attributes:, collection:, &)
+        end
+
+        # HTML5 input type convenience methods - clean API without _field suffix
+        # Examples:
+        #   field(:email).email(class: "form-input")
+        #   field(:age).number(min: 18, max: 99)
+        #   field(:birthday).date
+        #   field(:secret).hidden(value: "token123")
+        #   field(:gender).radio("male", id: "user_gender_male")
+        def hidden(*, **, &)
+          input(*, **, type: :hidden, &)
+        end
+
+        def password(*, **, &)
+          input(*, **, type: :password, &)
+        end
+
+        def email(*, **, &)
+          input(*, **, type: :email, &)
+        end
+
+        def url(*, **, &)
+          input(*, **, type: :url, &)
+        end
+
+        def tel(*, **, &)
+          input(*, **, type: :tel, &)
+        end
+        alias_method :phone, :tel
+
+        def number(*, **, &)
+          input(*, **, type: :number, &)
+        end
+
+        def range(*, **, &)
+          input(*, **, type: :range, &)
+        end
+
+        def date(*, **, &)
+          input(*, **, type: :date, &)
+        end
+
+        def time(*, **, &)
+          input(*, **, type: :time, &)
+        end
+
+        def datetime(*, **, &)
+          input(*, **, type: :"datetime-local", &)
+        end
+
+        def month(*, **, &)
+          input(*, **, type: :month, &)
+        end
+
+        def week(*, **, &)
+          input(*, **, type: :week, &)
+        end
+
+        def color(*, **, &)
+          input(*, **, type: :color, &)
+        end
+
+        def search(*, **, &)
+          input(*, **, type: :search, &)
+        end
+
+        def file(*, **, &)
+          input(*, **, type: :file, &)
+        end
+
+        def radio(value, *, **, &)
+          input(*, **, type: :radio, value: value, &)
+        end
+
+        # Rails compatibility aliases
+        alias_method :check_box, :checkbox
+        alias_method :text_area, :textarea
+
+        def title
+          key.to_s.titleize
+        end
+      end
+
+      def build_field(...)
+        self.class::Field.new(...)
+      end
+
+      def initialize(model, action: nil, method: nil, **attributes)
+        @model = model
+        @action = action
+        @method = method
+        @attributes = attributes
+        @namespace = Namespace.root(key, object: model, form: self)
+      end
+
+      def around_template(&)
+        form_tag do
+          authenticity_token_field
+          _method_field
+          super
+        end
+      end
+
+      def form_tag(&)
+        form action: form_action, method: form_method, **@attributes, &
+      end
+
+      def view_template(&block)
+        yield self if block_given?
+      end
+
+      def submit(value = submit_value, **attributes)
+        input **attributes.merge(
+          name: "commit",
+          type: "submit",
+          value: value
+        )
+      end
+
+      def key
+        @model.model_name.param_key
+      end
+
+      protected
+        def authenticity_token_field
+          input(
+            name: "authenticity_token",
+            type: "hidden",
+            value: form_authenticity_token
+          )
+        end
+
+        def _method_field
+          input(
+            name: "_method",
+            type: "hidden",
+            value: _method_field_value
+          )
+        end
+
+        def _method_field_value
+          @method || resource_method_field_value
+        end
+
+        def resource_method_field_value
+          @model.persisted? ? "patch" : "post"
+        end
+
+        def submit_value
+          "#{resource_action.to_s.capitalize} #{@model.model_name}"
+        end
+
+        def resource_action
+          @model.persisted? ? :update : :create
+        end
+
+        def form_action
+          @action ||= url_for(action: resource_action)
+        end
+
+        def form_method
+          @method.to_s.downcase == "get" ? "get" : "post"
+        end
+    end
+  end
+end

data/lib/superform/rails/option_mapper.rb

@@ -0,0 +1,36 @@
+module Superform
+  module Rails
+    # Accept a collection of objects and map them to options suitable for form controls, like `select > options`
+    class OptionMapper
+      include Enumerable
+
+      def initialize(collection)
+        @collection = collection
+      end
+
+      def each(&options)
+        @collection.each do |object|
+          case object
+            in ActiveRecord::Relation => relation
+              active_record_relation_options_enumerable(relation).each(&options)
+            in id, value
+              options.call id, value
+            in value
+              options.call value, value.to_s
+          end
+        end
+      end
+
+      def active_record_relation_options_enumerable(relation)
+        Enumerator.new do |collection|
+          relation.each do |object|
+            attributes = object.attributes
+            id = attributes.delete(relation.primary_key)
+            value = attributes.values.join(" ")
+            collection << [ id, value ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superform/rails/strong_parameters.rb

@@ -0,0 +1,73 @@
+module Superform
+  module Rails
+    module StrongParameters
+      protected
+      # Assigns permitted params to the given form and returns the model.
+      # Usage in a controller when you want to build/validate without saving:
+      #
+      # def preview
+      #   @post = Post.new
+      #   post = permit PostForm.new(@post)
+      #   # post now has attributes from params, but is not persisted
+      #   render :preview
+      # end
+      def permit(form)
+        form_params = params.require(form.key)
+        assign(form_params, to: form).model
+      end
+
+      # Saves the form's underlying model after assigning permitted params.
+      # Typical Rails controller usage (create):
+      #
+      # def create
+      #   @post = Post.new
+      #   if save PostForm.new(@post)
+      #     redirect_to @post
+      #   else
+      #     render :new, status: :unprocessable_entity
+      #   end
+      # end
+      #
+      # Typical Rails controller usage (update):
+      #
+      # def update
+      #   @post = Post.find(params[:id])
+      #   if save PostForm.new(@post)
+      #     redirect_to @post
+      #   else
+      #     render :edit, status: :unprocessable_entity
+      #   end
+      # end
+      def save(form)
+        permit(form).save
+      end
+
+      # Bang version that raises on validation failure.
+      # Useful when you prefer exceptions or are in a transaction:
+      #
+      # def create
+      #   @post = Post.new
+      #   save! PostForm.new(@post)
+      #   redirect_to @post
+      # rescue ActiveRecord::RecordInvalid
+      #   render :new, status: :unprocessable_entity
+      # end
+      def save!(form)
+        permit(form).save!
+      end
+
+      # Assigns params to the form and returns the form.
+      def assign(params, to:)
+        to.tap do |form|
+          # This output of this string goes nowhere since it likely
+          # won't be used. I'm not sure if I'm right about this though,
+          # If I'm wrong, then I think I need to encapsulate this module
+          # into a class that can store the rendered HTML that can be
+          # rendered later.
+          render_to_string form
+          form.assign params
+        end
+      end
+    end
+  end
+end