formula 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b3c844a3b82fc2394cc192c4eaaf04990a6b21a7
-  data.tar.gz: 4539895dac54e7330b3c5f2c429499fabb1b11f5
+SHA256:
+  metadata.gz: 8e753004d2065d2a0aa15c73ac8393b54de9ae40086f2f5da874e0cd1a0ccd8a
+  data.tar.gz: 21797db2580b4ae567942e4b3c36e2c86caed7645d58ecd4ba10cecb25449ad5
 SHA512:
-  metadata.gz: e6e13d92a4e16f4aebdfd1925edd425223404984fd2fb721454011b72d331a2080684eafb619781afc803d13c48d4cff34aa5ff31f360792ae95587d26a64f86
-  data.tar.gz: c4cb45eb4a68624974886b3c62c16209e89f6447a20e5d5daef21ef904a82b98e8271bd52207be19486f4019bb8c4afa26c410efe810fbf76e144d34d700d1d2
+  metadata.gz: 59d014229aa1940f2b0d08b263d6bc49ab9caa836b4e4b993bc3c9407b2544fd789e8a36f1e324a19f467d8895b23ab3d15fa14fd3af27c77b426abe25c908b4
+  data.tar.gz: cd47a5b0382b1bf898a2e0691c3234504e016ab29d96496290127903ae3bafe6140cedd651e554f3f2a626ecf43293d1cb4fc318ef833e236417cca9bd11b522

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'bcrypt'
+gem 'puma'
+gem 'rubocop'
+gem 'sqlite3'
+gem 'yard'

data/README.md

@@ -0,0 +1,71 @@
+# Formula
+
+Formula is a Rails form helper that generates awesome markup. The project lets users create semantically beautiful forms without introducing too much syntax.
+
+## Requirements
+
+The gem is tested with:
+
+- Ruby 3.3
+- Rails 7.2
+
+## Installation
+
+```bash
+gem install formula
+```
+
+## Examples
+
+```erb
+<%= formula_form_for @user do |f| %>
+  <%= f.input :email %>
+  <%= f.input :password %>
+  <%= f.button 'Save' %>
+<% end %>
+```
+
+```erb
+<%= formula_form_for @user do |f| %>
+  <%= f.input :email, label: "Email:", hint: "We promise never to bother you." %>
+  <%= f.input :password, label: "Password:", hint: "Must be at least six characters." %>
+  <%= f.button 'Save' %>
+<% end %>
+```
+
+```erb
+<%= formula_form_for @company do |f|
+  <%= f.input :url, container: { class: 'third' }, input: { class: 'fill' } %>
+  <%= f.input :phone, container: { class: 'third' }, input: { class: 'fill' } %>
+  <%= f.input :email, container: { class: 'third' }, input: { class: 'fill' } %>
+  <%= f.button 'Save', button: { class: 'fancy' } %>
+<% end %>
+```
+
+```erb
+<%= formula_form_for @user do |f| %>
+  <%= f.input :email, label: "Email:" %>
+  <%= f.input :password, label: "Password:" %>
+  <%= f.input :gender, label: 'Gender:', as: :select, choices: User::GENDERS %>
+  <%= formula_fields_for @user.payment do |payment_f| %>
+    <%= payment_f.input :credit_card_number, label: 'Number:' %>
+    <%= payment_f.input :credit_card_expiration, label: 'Expiration:' %>
+  <% end %>
+  <%= f.button 'Save', button: { class: 'fancy' } %>
+<% end %>
+```
+
+```erb
+<%= formula_form_for @user do |f| %>
+  <%= f.block :favourite %>
+    <% @favourites.each do |favourite| %>
+      ...
+    <% end %>
+  <% end %>
+  <%= f.button 'Save', button: { class: 'fancy' } %>
+<% end %>
+```
+
+## Copyright
+
+Copyright (c) 2010 - 2024 Kevin Sylvestre. See LICENSE for details.

data/bin/rubocop

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require "rubygems"
+require "bundler/setup"
+
+# explicit rubocop config increases performance slightly while avoiding config confusion.
+ARGV.unshift("--config", File.expand_path("../.rubocop.yml", __dir__))
+
+load Gem.bin_path("rubocop", "rubocop")

data/bin/test

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$: << File.expand_path("../test", __dir__)
+
+require "bundler/setup"
+require "rails/plugin/test"

data/lib/formula/config.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Formula
+  class Config
+    # @!attribute [rw] box_options
+    #   @return [Hash]
+    attr_accessor :box_options
+
+    # @!attribute [rw] area_options
+    #   @return [Hash]
+    attr_accessor :area_options
+
+    # @!attribute [rw] file_options
+    #   @return [Hash]
+    attr_accessor :file_options
+
+    # @!attribute [rw] field_options
+    #   @return [Hash]
+    attr_accessor :field_options
+
+    # @!attribute [rw] select_options
+    #   @return [Hash]
+    attr_accessor :select_options
+
+    # @!attribute [rw] label_options
+    #   @return [Hash]
+    attr_accessor :label_options
+
+    # Default class assigned to block (<div class="block">...</div>).
+    #
+    # @!attribute [rw] block_class
+    #   @return [String]
+    attr_accessor :block_class
+
+    # Default class assigned to input (<div class="input">...</div>).
+    #
+    # @!attribute [rw] input_class
+    #   @return [String]
+    attr_accessor :input_class
+
+    # Default class assigned to association (<div class="association">...</div>).
+    #
+    # @!attribute [rw] association_class
+    #   @return [String]
+    attr_accessor :association_class
+
+    # Default class assigned to block with errors (<div class="block errors">...</div>).
+    #
+    # @!attribute [rw] block_error_class
+    #   @return [String]
+    attr_accessor :block_error_class
+
+    # Default class assigned to input with errors (<div class="input errors">...</div>).
+    #
+    # @!attribute [rw] input_error_class
+    #   @return [String]
+    attr_accessor :input_error_class
+
+    # Default class assigned to input with errors (<div class="association errors">...</div>).
+    #
+    # @!attribute [rw] association_error_class
+    #   @return [String]
+    attr_accessor :association_error_class
+
+    # Default class assigned to error (<div class="error">...</div>).
+    #
+    # @!attribute [rw] error_class
+    #   @return [String]
+    attr_accessor :error_class
+
+    # Default class assigned to hint (<div class="hint">...</div>).
+    #
+    # @!attribute [rw] hint_class
+    #   @return [String]
+    attr_accessor :hint_class
+
+    # Default tag assigned to block (<div class="input">...</div>).
+    #
+    # @!attribute [rw] block_tag
+    #   @return [Symbol]
+    attr_accessor :block_tag
+
+    # Default tag assigned to input (<div class="input">...</div>).
+    #
+    # @!attribute [rw] input_tag
+    #   @return [Symbol]
+    attr_accessor :input_tag
+
+    # Default tag assigned to association (<div class="association">...</div>).
+    #
+    # @!attribute [rw] association_tag
+    #   @return [Symbol]
+    attr_accessor :association_tag
+
+    # Default tag assigned to error (<div class="error">...</div>).
+    #
+    # @!attribute [rw] error_tag
+    #   @return [Symbol]
+    attr_accessor :error_tag
+
+    # Default tag assigned to hint (<div class="hint">...</div>).
+    #
+    # @!attribute [rw] hint_tag
+    #   @return [Symbol]
+    attr_accessor :hint_tag
+
+    # Default as is :string.
+    #
+    # @!attribute [rw] default_as
+    #   @return [Symbol]
+    attr_accessor :default_as
+
+    def initialize
+      @box_options = {}
+      @area_options = {}
+      @file_options = {}
+      @field_options = {}
+      @select_options = {}
+      @label_options = {}
+      @block_class = 'block'
+      @input_class = 'input'
+      @association_class = 'association'
+      @block_error_class = 'errors'
+      @input_error_class = false
+      @association_error_class = false
+      @error_class = 'error'
+      @hint_class = 'hint'
+      @block_tag = :div
+      @input_tag = :div
+      @association_tag = :div
+      @error_tag = :div
+      @hint_tag = :div
+      @default_as = :string
+    end
+  end
+end

data/lib/formula/form_builder.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module Formula
+  class FormBuilder < ::ActionView::Helpers::FormBuilder
+    # Generate a form button.
+    #
+    # Options:
+    #
+    # * :container - add custom options to the container
+    # * :button    - add custom options to the button
+    #
+    # Usage:
+    #
+    #   f.button(:name)
+    #
+    # Equivalent:
+    #
+    #   <div class="block">
+    #     <%= f.submit("Save")
+    #   </div>
+    def button(value = nil, options = {})
+      options[:button] ||= {}
+
+      options[:container] ||= {}
+      options[:container][:class] = arrayorize(options[:container][:class]) << config.block_class
+
+      @template.content_tag(config.block_tag, options[:container]) do
+        submit value, options[:button]
+      end
+    end
+
+    # Basic container generator for use with blocks.
+    #
+    # Options:
+    #
+    # * :hint       - specify a hint to be displayed ('We promise not to spam you.', etc.)
+    # * :label      - override the default label used ('Name:', 'URL:', etc.)
+    # * :error      - override the default error used ('invalid', 'incorrect', etc.)
+    #
+    # Usage:
+    #
+    #   f.block(:name, :label => "Name:", :hint => "Please use your full name.", :container => { :class => 'fill' }) do
+    #     ...
+    #   end
+    #
+    # Equivalent:
+    #
+    #   <div class='block fill'>
+    #     <%= f.label(:name, "Name:") %>
+    #     ...
+    #     <div class="hint">Please use your full name.</div>
+    #     <div class="error">...</div>
+    #   </div>
+    def block(method = nil, options = {}, &block)
+      options[:error] ||= error(method) if method
+
+      components = ''.html_safe
+
+      components << label(method, options[:label], config.label_options) if method
+
+      components << @template.capture(&block)
+
+      options[:container] ||= {}
+      options[:container][:class] = arrayorize(options[:container][:class]) << config.block_class << method
+      options[:container][:class] << config.block_error_class if config.block_error_class.present? and error?(method)
+
+      if options[:hint]
+        components << @template.content_tag(config.hint_tag, options[:hint],
+                                            class: config.hint_class)
+      end
+      if options[:error]
+        components << @template.content_tag(config.error_tag, options[:error],
+                                            class: config.error_class)
+      end
+
+      @template.content_tag(config.block_tag, options[:container]) do
+        components
+      end
+    end
+
+    # Generate a suitable form input for a given method by performing introspection on the type.
+    #
+    # Options:
+    #
+    # * :as         - override the default type used (:url, :email, :phone, :password, :number, :text)
+    # * :label      - override the default label used ('Name:', 'URL:', etc.)
+    # * :error      - override the default error used ('invalid', 'incorrect', etc.)
+    # * :input      - add custom options to the input ({ :class => 'goregous' }, etc.)
+    # * :container  - add custom options to the container ({ :class => 'gorgeous' }, etc.)
+    #
+    # Usage:
+    #
+    #   f.input(:name)
+    #   f.input(:email)
+    #   f.input(:password_a, :label => "Password", :hint => "It's a secret!", :container => { :class => "half" })
+    #   f.input(:password_b, :label => "Password", :hint => "It's a secret!", :container => { :class => "half" })
+    #
+    # Equivalent:
+    #
+    #   <div class="block name">
+    #     <%= f.label(:name)
+    #     <div class="input string"><%= f.text_field(:name)</div>
+    #      <div class="error">...</div>
+    #   </div>
+    #   <div class="block email">
+    #     <%= f.label(:email)
+    #     <div class="input string"><%= f.email_field(:email)</div>
+    #      <div class="error">...</div>
+    #   </div>
+    #   <div class="block half password_a">
+    #     <div class="input">
+    #       <%= f.label(:password_a, "Password")
+    #       <%= f.password_field(:password_a)
+    #       <div class="hint">It's a secret!</div>
+    #       <div class="error">...</div>
+    #     </div>
+    #   </div>
+    #   <div class="block half password_b">
+    #     <div class="input">
+    #       <%= f.label(:password_b, "Password")
+    #       <%= f.password_field(:password_b)
+    #       <div class="hint">It's a secret!</div>
+    #       <div class="error">...</div>
+    #     </div>
+    #   </div>
+    def input(method, options = {})
+      options[:as] ||= as(method)
+      options[:input] ||= {}
+
+      return hidden_field method, options[:input] if options[:as] == :hidden
+
+      klass = [config.input_class, options[:as]]
+      klass << config.input_error_class if config.input_error_class.present? and error?(method)
+
+      block(method, options) do
+        @template.content_tag(config.input_tag, class: klass) do
+          case options[:as]
+          when :text     then text_area       method, config.area_options.merge(options[:input] || {})
+          when :file     then file_field      method, config.file_options.merge(options[:input] || {})
+          when :string   then text_field      method, config.field_options.merge(options[:input] || {})
+          when :password then password_field  method, config.field_options.merge(options[:input] || {})
+          when :url      then url_field       method, config.field_options.merge(options[:input] || {})
+          when :email    then email_field     method, config.field_options.merge(options[:input] || {})
+          when :phone    then phone_field     method, config.field_options.merge(options[:input] || {})
+          when :number   then number_field    method, config.field_options.merge(options[:input] || {})
+          when :boolean  then check_box       method, config.box_options.merge(options[:input] || {})
+          when :country  then country_select  method, config.select_options.merge(options[:input] || {})
+          when :date     then date_select     method, config.select_options.merge(options[:input] || {}),
+                                              options[:input].delete(:html) || {}
+          when :time     then time_select     method, config.select_options.merge(options[:input] || {}),
+                                              options[:input].delete(:html) || {}
+          when :datetime then datetime_select method, config.select_options.merge(options[:input] || {}),
+                                              options[:input].delete(:html) || {}
+          when :select   then select          method, options[:choices],
+                                              config.select_options.merge(options[:input] || {}), options[:input].delete(:html) || {}
+          end
+        end
+      end
+    end
+
+    # Generate a suitable form association for a given method by performing introspection on the type.
+    #
+    # Options:
+    #
+    # * :label       - override the default label used ('Name:', 'URL:', etc.)
+    # * :error       - override the default error used ('invalid', 'incorrect', etc.)
+    # * :association - add custom options to the input ({ :class => 'goregous' }, etc.)
+    # * :container   - add custom options to the container ({ :class => 'gorgeous' }, etc.)
+    #
+    # Usage:
+    #
+    #   f.association(:category, Category.all, :id, :name, :hint => "What do you do?")
+    #   f.association(:category, Category.all, :id, :name, :association => { :prompt => "Category?" })
+    #   f.association(:category, Category.all, :id, :name, :association => { :html => { :class => "category" } })
+    #
+    # Equivalent:
+    #
+    #   <div>
+    #     <div class="association category">
+    #       <%= f.label(:category)
+    #       <div class="association">
+    #         <%= f.collection_select(:category, Category.all, :id, :name) %>
+    #       </div>
+    #       <div class="hint">What do you do?</div>
+    #       <div class="error">...</div>
+    #     </div>
+    #   </div>
+    #   <div>
+    #     <div class="association category">
+    #       <%= f.label(:category)
+    #       <div class="association">
+    #         <%= f.collection_select(:category, Category.all, :id, :name, { :prompt => "Category") } %>
+    #       </div>
+    #       <div class="error">...</div>
+    #     </div>
+    #   </div>
+    #   <div>
+    #     <div class="association category">
+    #       <%= f.label(:category)
+    #       <div class="association">
+    #         <%= f.collection_select(:category, Category.all, :id, :name, {}, { :class => "category" } %>
+    #       </div>
+    #       <div class="error">...</div>
+    #     </div>
+    #   </div>
+    def association(method, collection, value, text, options = {})
+      options[:as] ||= :select
+      options[:association] ||= {}
+
+      klass = [config.association_class, options[:as]]
+      klass << config.association_error_class if config.association_error_class.present? and error?(method)
+
+      block(method, options) do
+        @template.content_tag(config.association_tag, class: klass) do
+          case options[:as]
+          when :select then collection_select :"#{method}_id", collection, value, text,
+                                              options[:association], options[:association].delete(:html) || {}
+          end
+        end
+      end
+    end
+
+    private
+
+    def config
+      ::Formula.config
+    end
+
+    # Introspection on the column to determine how to render a method. The method is used to
+    # identify a method type (if the method corresponds to a column)
+    #
+    # Returns:
+    #
+    # * :text     - for columns of type 'text'
+    # * :string   - for columns of type 'string'
+    # * :integer  - for columns of type 'integer'
+    # * :float    - for columns of type 'float'
+    # * :decimal  - for columns of type 'decimal'
+    # * :datetime - for columns of type 'datetime'
+    # * :date     - for columns of type 'date'
+    # * :time     - for columns of type 'time'
+    # * nil       - for unkown columns
+    def type(method)
+      return unless @object.respond_to?(:has_attribute?) && @object.has_attribute?(method)
+
+      column = @object.column_for_attribute(method) if @object.respond_to?(:column_for_attribute)
+      column.type if column
+    end
+
+    # Introspection on an association to determine if a method is a file. This
+    # is determined by the methods ability to respond to file methods.
+    def file?(method)
+      @files ||= {}
+      @files[method] ||= begin
+        file = @object.send(method) if @object && @object.respond_to?(method)
+        file.is_a?(::ActiveStorage::Attached)
+      end
+    end
+
+    # Introspection on the field and method to determine how to render a method. The method is
+    # used to generate form element types.
+    #
+    # Returns:
+    #
+    # * :url      - for columns containing 'url'
+    # * :email    - for columns containing 'email'
+    # * :phone    - for columns containing 'phone'
+    # * :password - for columns containing 'password'
+    # * :number   - for integer, float or decimal columns
+    # * :datetime - for datetime or timestamp columns
+    # * :date     - for date column
+    # * :time     - for time column
+    # * :text     - for time column
+    # * :string   - for all other cases
+    def as(method)
+      case "#{method}"
+      when /url/      then return :url
+      when /email/    then return :email
+      when /phone/    then return :phone
+      when /password/ then return :password
+      end
+
+      case type(method)
+      when :string    then return :string
+      when :integer   then return :number
+      when :float     then return :number
+      when :decimal   then return :number
+      when :timestamp then return :datetime
+      when :datetime  then return :datetime
+      when :date      then return :date
+      when :time      then return :time
+      when :text      then return :text
+      end
+
+      return :file if file?(method)
+
+      config.default_as
+    end
+
+    # Generate error messages by combining all errors on an object into a comma seperated string
+    # representation.
+    def error(method)
+      errors = @object.errors[method] if @object
+      errors.to_sentence if errors.present?
+    end
+
+    # Identify if error message exists for a given method by checking for the presence of the object
+    # followed by the presence of errors.
+    def error?(method)
+      @object.present? and @object.errors[method].present?
+    end
+
+    # Create an array from a string, a symbol, or an undefined value. The default is to return
+    # the value and assume it has already is valid.
+    def arrayorize(value)
+      case value
+      when nil    then []
+      when String then value.to_s.split
+      when Symbol then value.to_s.split
+      else value
+      end
+    end
+
+    public
+
+    # Generates a wrapper around fields_form with :builder set to FormBuilder.
+    #
+    # Supports:
+    #
+    # * f.formula_fields_for(@user.company)
+    # * f.fieldsula_for(@user.company)
+    #
+    # Equivalent:
+    #
+    # * f.fields_for(@user.company, builder: Formula::FormBuilder))
+    #
+    # Usage:
+    #
+    #   <% f.formula_fields_for(@user.company) do |company_f| %>
+    #     <%= company_f.input :url %>
+    #     <%= company_f.input :phone %>
+    #   <% end %>
+    def formula_fields_for(record_or_name_or_array, *args, &block)
+      options = args.extract_options!
+      options[:builder] ||= self.class
+      fields_for(record_or_name_or_array, *(args << options), &block)
+    end
+
+    alias fieldsula_for formula_fields_for
+  end
+end

data/lib/formula/form_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Formula
+  module FormHelper
+    # Generates a wrapper around form_for with :builder set to Formula::FormBuilder.
+    #
+    # Supports:
+    #
+    # * formula_form_for(@user)
+    #
+    # Equivalent:
+    #
+    # * form_for(@user, builder: Formula::FormBuilder))
+    #
+    # Usage:
+    #
+    #   <% formula_form_for(@user) do |f| %>
+    #     <%= f.input :email %>
+    #     <%= f.input :password %>
+    #   <% end %>
+    def formula_form_for(record_or_name_or_array, *args, &proc)
+      options = args.extract_options!
+      options[:builder] ||= ::Formula::FormBuilder
+      form_for(record_or_name_or_array, *(args << options), &proc)
+    end
+
+    # Generates a wrapper around fields_for with :builder set to Formula::FormBuilder.
+    #
+    # Supports:
+    #
+    # * f.formula_fields_for(@user.company)
+    #
+    # Equivalent:
+    #
+    # * f.fields_for(@user.company, builder: Formula::FormulaFormBuilder))
+    #
+    # Usage:
+    #
+    #   <% f.formula_fields_for(@user.company) do |company_f| %>
+    #     <%= company_f.input :url %>
+    #     <%= company_f.input :phone %>
+    #   <% end %>
+    def formula_fields_for(record_or_name_or_array, *args, &block)
+      options = args.extract_options!
+      options[:builder] ||= ::Formula::FormBuilder
+      fields_for(record_or_name_or_array, *(args << options), &block)
+    end
+  end
+end

data/lib/formula/railtie.rb

@@ -1,10 +1,11 @@
-require 'formula'
+# frozen_string_literal: true
+
 require 'rails'
 
 module Formula
   class Railtie < Rails::Railtie
     initializer 'formula.initialize' do
-      ActionView::Base.send :include, Formula::FormulaFormHelper
+      ActionView::Base.include Formula::FormHelper
     end
   end
 end

data/lib/formula/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Formula
-  VERSION = "1.1.1"
+  VERSION = '2.0.0'
 end