tramway 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eee7e8b57c93fd646e96a26e07e9dab81b6deee977c50c2ab34b1df93f48e96d
-  data.tar.gz: 48d411dcce7d057eb867862f2b8410b5320bbf2dfdc47f5a0e06508f34049139
+  metadata.gz: 817cf3ad464278dbd553e1e6d48c740a85305ca7ad8e4caac6a3d2fecc87041a
+  data.tar.gz: c3b5dadac4b6283f251c5647cb1d5dd2703c858a3e2a4730e0a80424b7c71e1a
 SHA512:
-  metadata.gz: dc78481a707c0688c774469549b8c1dc319adfe51f67cdd871b4b4751f03367206c674298c764a54110aa9c9b634082c6c844e1b97df0e9d2b2411fb536fa527
-  data.tar.gz: 2bdf9eca337acd11afacb0fca442e6047b1b600d5b6a499bad31ad7522777edf0c2079c247491334a32eb3bb8682d54c78e596256b120c14a6c4a62593592150
+  metadata.gz: '079777145b30d2bf2695a14c71b77ef0470a5e29ddd4c0b2bcc43f14bf711e9f96d674bfa814b84eb7dda438167ddaa584717aa52039c2b1a2e8b787ac7e8719'
+  data.tar.gz: be3904286806a86296274d42026d11a00308e80eb5fa14e0f7e794fc78e70b70040a813f727c2723b7b87289b6ff355e068a30a3cbe2ea4bdd95ee9680ca0258

data/README.md

@@ -1,6 +1,14 @@
 # Tramway
 Unite Ruby on Rails brilliance. Streamline development with Tramway.
 
+* [Installation](https://github.com/Purple-Magic/tramway#installation)
+* [Usage](https://github.com/Purple-Magic/tramway#usage)
+  * [Tramway Entities](https://github.com/Purple-Magic/tramway#tramway-entities)
+  * [Tramway Decorators](https://github.com/Purple-Magic/tramway#tramway-decorators)
+  * [Tramway Form](https://github.com/Purple-Magic/tramway#tramway-form)
+  * [Tramway Navbar](https://github.com/Purple-Magic/tramway#tramway-navbar)
+  * [Tailwind-styled forms](https://github.com/Purple-Magic/tramway#tailwind-styled-forms)
+
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -43,10 +51,6 @@ Tramway.configure do |config|
 end
 ```
 
-### Tailwind components
-
-Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are implemented with [ViewComponent](https://github.com/viewcomponent/view_component).
-
 ### Tramway Decorators
 
 Tramway provides convenient decorators for your objects. **NOTE:** This is not the decorator pattern in its usual representation.
@@ -97,6 +101,152 @@ def show
 end
 ```
 
+### Tramway Form
+
+Tramway provides **convenient** form objects for Rails applications. List properties you want to change and the rules in Form classes. No controllers overloading.
+
+*app/forms/user_form.rb
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :password, :first_name, :last_name, :phone
+
+  def password=(value)
+    object.password = value if value.present?
+  end
+end
+```
+
+**Controllers without Tramway Form**
+
+*app/controllers/users_controller.rb*
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new
+    if @user.save user_params
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = User.find params[:id]
+    if @user.save user_params
+      render :show
+    else
+      render :edit
+    end
+  end
+  
+  private
+
+  def user_params
+    params[:user].permit(:email, :password, :first_name, :last_name, :phone)
+  end
+end
+```
+
+**Controllers with Tramway Form**
+
+*app/controllers/users_controller.rb*
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = tramway_form User.new
+    if @user.submit params[:user]
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = tramway_form User.find params[:id]
+    if @user.submit params[:user]
+      render :show
+    else
+      render :edit
+    end
+  end
+end
+```
+
+#### Implement Form objects for any case
+
+*app/forms/user_updating_email_form.rb*
+```ruby
+class UserUpdatingEmailForm < Tramway::BaseForm
+  properties :email
+end
+```
+
+*app/controllers/updating_emails_controller.rb*
+```ruby
+def update
+  @user = UserUpdatingEmailForm.new User.find params[:id]
+  if @user.submit params[:user]
+    # success
+  else
+    # failure
+  end
+end
+```
+
+#### Create form namespaces
+
+*app/forms/admin/user_form.rb*
+```ruby
+class Admin::UserForm < Tramway::BaseForm
+  properties :email, :password, :first_name, :last_name, :etc
+end
+```
+
+*app/controllers/admin/users_controller.rb*
+```ruby
+class Admin::UsersController < Admin::ApplicationController
+  def create
+    @user = tramway_form User.new, namespace: :admin
+    if @user.submit params[:user]
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = tramway_form User.find(params[:id]), namespace: :admin
+    if @user.submit params[:user]
+      render :show
+    else
+      render :edit
+    end
+  end
+end
+```
+
+### Make flexible and extendable forms
+
+Tramway Form properties are not mapped to a model. You're able to make extended forms.
+
+*app/forms/user_form.rb*
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :password, :full_name
+
+  # RULE: in case password is empty, don't save
+  def password=(value)
+    object.password = value if value.present?
+  end
+
+  # EXTENDED FIELD: full name
+  def full_name=(value)
+    object.first_name = value.split(' ').first
+    object.last_name = value.split(' ').last
+  end
+end
+```
+
 ### Tramway Navbar
 
 Tramway provides DSL for rendering Tailwind Navgiation bar.
@@ -163,6 +313,30 @@ tramway_navbar title: 'Purple Magic' do |nav|
 end
 ```
 
+### Tailwind-styled forms
+
+Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are implemented with [ViewComponent](https://github.com/viewcomponent/view_component).
+
+#### tramway_form_for
+
+Tramway provides `tramway_form_for` helper that renders Tailwind-styled forms by default.
+
+```ruby
+= tramway_form_for User.new do |f|
+  = f.text_field :text
+  = f.password_field :password
+  = f.file_field :file
+  = f.submit "Create User"
+```
+
+will render [this](https://play.tailwindcss.com/xho3LfjKkK)
+
+Available form helpers:
+* text_field
+* password_field
+* file_field
+* submit
+
 ## Contributing
 
 Install [lefthook](https://github.com/evilmartians/lefthook)

data/app/components/tailwinds/form/builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Tailwinds
+  module Form
+    # Provides Tailwind-styled forms
+    class Builder < Tramway::Views::FormBuilder
+      def text_field(attribute, **options, &)
+        input = super(attribute, **options.merge(class: text_input_class))
+        render(Tailwinds::Form::TextFieldComponent.new(input, attribute, object_name:, **options), &)
+      end
+
+      def password_field(attribute, **options, &)
+        input = super(attribute, **options.merge(class: text_input_class))
+        render(Tailwinds::Form::TextFieldComponent.new(input, attribute, object_name:, **options), &)
+      end
+
+      def file_field(attribute, **options, &)
+        input = super(attribute, **options.merge(class: :hidden))
+
+        render(Tailwinds::Form::FileFieldComponent.new(input, attribute, object_name:, **options), &)
+      end
+
+      def submit(action, **options, &)
+        render(Tailwinds::Form::SubmitButtonComponent.new(action, **options), &)
+      end
+
+      private
+
+      def text_input_class
+        'w-full px-3 py-2 border border-gray-300 rounded focus:outline-none focus:border-red-500'
+      end
+    end
+  end
+end

data/app/components/tailwinds/form/file_field_component.html.haml

@@ -0,0 +1,4 @@
+.mb-4
+  %label.inline-block.bg-blue-500.hover:bg-blue-700.text-white.font-bold.py-2.px-4.rounded.cursor-pointer.mt-4{ for: @for }
+    = @label
+  = @input

data/app/components/tailwinds/form/file_field_component.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tailwinds
+  module Form
+    # Tailwind-styled file_field input
+    class FileFieldComponent < TailwindComponent
+      def initialize(input, attribute, object_name: nil, **options)
+        @label = options[:label] || attribute.to_s.capitalize
+        @for = "#{object_name}_#{attribute}"
+        @input = input
+      end
+    end
+  end
+end

data/app/components/tailwinds/form/submit_button_component.html.haml

@@ -0,0 +1,4 @@
+.flex.items-center.justify-between
+  %button.bg-red-500.hover:bg-red-700.text-white.font-bold.py-2.px-4.rounded.focus:outline-none.focus:shadow-outline{ type: :submit, name: :commit, **@options }
+    = @text
+  = @content

data/app/components/tailwinds/form/submit_button_component.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tailwinds
+  module Form
+    # Tailwind-styled submit button
+    class SubmitButtonComponent < TailwindComponent
+      def initialize(action, **options)
+        @options = options.except :type
+
+        @text = action.is_a?(String) ? action : action.to_s.capitalize
+      end
+    end
+  end
+end

data/app/components/tailwinds/form/text_field_component.html.haml

@@ -0,0 +1,4 @@
+.mb-4
+  %label.block.text-gray-700.text-sm.font-bold.mb-2{ for: @for }
+    = @label
+  = @input

data/app/components/tailwinds/form/text_field_component.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tailwinds
+  module Form
+    # Tailwind-styled text field
+    class TextFieldComponent < TailwindComponent
+      def initialize(input, attribute, object_name: nil, **options)
+        @label = options[:label] || attribute.to_s.humanize
+        @for = "#{object_name}_#{attribute}"
+        @input = input
+      end
+    end
+  end
+end

data/lib/tramway/base_form.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Tramway
+  # Provides form object for Tramway
+  #
+  class BaseForm
+    attr_reader :object
+
+    %i[model_name to_key to_model errors attributes].each do |method_name|
+      delegate method_name, to: :object
+    end
+
+    def initialize(object)
+      @object = object
+    end
+
+    class << self
+      def property(attribute, _proc_obj = nil)
+        @properties ||= []
+        @properties << attribute
+
+        delegate attribute, to: :object
+      end
+
+      def properties(*attributes)
+        if attributes.any?
+          attributes.each do |attribute|
+            property(attribute)
+          end
+        else
+          @properties || []
+        end
+      end
+    end
+
+    def submit(params)
+      __submit params
+
+      object.save.tap do
+        __object
+      end
+    end
+
+    def submit!(params)
+      __submit params
+
+      object.save!.tap do
+        __object
+      end
+    end
+
+    def method_missing(method_name, *args)
+      if method_name.to_s.end_with?('=') && args.count == 1
+        object.public_send(method_name, args.first)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name.to_s.end_with?('=') || super
+    end
+
+    private
+
+    def __submit(params)
+      self.class.properties.each do |attribute|
+        public_send("#{attribute}=", params[attribute])
+      end
+    end
+
+    def __object
+      object.persisted? ? object.reload : object
+    end
+  end
+end

data/lib/tramway/engine.rb

@@ -13,11 +13,23 @@ module Tramway
         loaded_class.include Tramway::Helpers::NavbarHelper
       end
 
+      ActiveSupport.on_load(:action_view) do |loaded_class|
+        require 'tramway/helpers/views_helper'
+
+        loaded_class.include Tramway::Helpers::ViewsHelper
+      end
+
       ActiveSupport.on_load(:action_controller) do |loaded_class|
         require 'tramway/helpers/decorate_helper'
 
         loaded_class.include Tramway::Helpers::DecorateHelper
       end
+
+      ActiveSupport.on_load(:action_controller) do |loaded_class|
+        require 'tramway/helpers/form_helper'
+
+        loaded_class.include Tramway::Helpers::FormHelper
+      end
     end
   end
 end

data/lib/tramway/forms/class_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Forms
+    # Provides method to determine decorators classes
+    module ClassHelper
+      module_function
+
+      def form_class(object, form, namespace)
+        object_class = object.class
+
+        if form.present?
+          form
+        elsif namespace.present?
+          "#{namespace.to_s.camelize}::#{object_class}Form".constantize
+        else
+          "#{object_class}Form".constantize
+        end
+      end
+    end
+  end
+end

data/lib/tramway/helpers/form_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'tramway/forms/class_helper'
+
+module Tramway
+  module Helpers
+    # Provides methods into Rails ActionController
+    #
+    module FormHelper
+      def tramway_form(object, form: nil, namespace: nil)
+        Tramway::Forms::ClassHelper.form_class(object, form, namespace).new object
+      end
+    end
+  end
+end

data/lib/tramway/helpers/navbar_helper.rb

@@ -4,7 +4,7 @@ require 'tramway/navbar'
 
 module Tramway
   module Helpers
-    # Providing navbar helpers for ActionView
+    # Provides navbar helpers for ActionView
     module NavbarHelper
       def tramway_navbar(**options)
         initialize_navbar

data/lib/tramway/helpers/views_helper.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Helpers
+    # Provides view-oriented helpers for ActionView
+    module ViewsHelper
+      def tramway_form_for(object, *args, **options, &)
+        form_for(object, *args, **options.merge(builder: Tailwinds::Form::Builder), &)
+      end
+    end
+  end
+end

data/lib/tramway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tramway
-  VERSION = '0.2.3'
+  VERSION = '0.3.1'
 end

data/lib/tramway/views/form_builder.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Tramway
+  module Views
+    # ActionView Form Builder helps us use ViewComponent as form helpers
+    class FormBuilder < ActionView::Helpers::FormBuilder
+      attr_reader :template
+
+      private
+
+      def render(component, &)
+        component.render_in(template, &)
+      end
+    end
+  end
+end

data/lib/tramway.rb

@@ -4,7 +4,9 @@ require 'types'
 require 'tramway/version'
 require 'tramway/engine'
 require 'tramway/base_decorator'
+require 'tramway/base_form'
 require 'tramway/config'
+require 'tramway/views/form_builder'
 require 'view_component/compiler'
 require 'view_component/engine'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - kalashnikovisme
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-08-17 00:00:00.000000000 Z
+date: 2023-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-struct
@@ -93,6 +93,13 @@ files:
 - Rakefile
 - app/components/tailwind_component.html.haml
 - app/components/tailwind_component.rb
+- app/components/tailwinds/form/builder.rb
+- app/components/tailwinds/form/file_field_component.html.haml
+- app/components/tailwinds/form/file_field_component.rb
+- app/components/tailwinds/form/submit_button_component.html.haml
+- app/components/tailwinds/form/submit_button_component.rb
+- app/components/tailwinds/form/text_field_component.html.haml
+- app/components/tailwinds/form/text_field_component.rb
 - app/components/tailwinds/nav/item_component.html.haml
 - app/components/tailwinds/nav/item_component.rb
 - app/components/tailwinds/navbar_component.html.haml
@@ -102,17 +109,22 @@ files:
 - lib/tasks/tramway_tasks.rake
 - lib/tramway.rb
 - lib/tramway/base_decorator.rb
+- lib/tramway/base_form.rb
 - lib/tramway/config.rb
 - lib/tramway/configs/entities/route.rb
 - lib/tramway/configs/entity.rb
 - lib/tramway/decorators/class_helper.rb
 - lib/tramway/decorators/collection_decorator.rb
 - lib/tramway/engine.rb
+- lib/tramway/forms/class_helper.rb
 - lib/tramway/helpers/decorate_helper.rb
+- lib/tramway/helpers/form_helper.rb
 - lib/tramway/helpers/navbar_helper.rb
+- lib/tramway/helpers/views_helper.rb
 - lib/tramway/navbar.rb
 - lib/tramway/utils/render.rb
 - lib/tramway/version.rb
+- lib/tramway/views/form_builder.rb
 - lib/types.rb
 homepage: https://github.com/purple-magic/tramway
 licenses: