tramway 2.2.2.7 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0aaa3638083ec75bcbbcd0004e0bce38e3d8ec1bcd49a0aff0ced804ad96889
-  data.tar.gz: 1abdc26dfa0d58657f6df30405f919f24e7b7bde9fcb81a769fd2f3689100b33
+  metadata.gz: 073b1293c7f3778243b4402bd9db528eea16b9897145f5ac7a50bb0751607dfd
+  data.tar.gz: 980e71accc0572795aaa87764af580f50d883fa504b4b148fd5224826941c110
 SHA512:
-  metadata.gz: 6f8827bba6e448bd4af639c2a4490ba3cc954082874c60846d7e479d211000afa4bd47b2b9ab2608d2e61117bf12117e618f2d7e8d75715dddd9030a813a1a12
-  data.tar.gz: 767e7bbb7a246905feb4d90f24dc5d783fc05cb8496fabafc70da4dd423a715ec102b494e1e185202128693cdaad6a8c2ac0219d5c563947704b0bc5eb9322e5
+  metadata.gz: 4819641881ea15d5ef0211470aab28fad0c758ac2f733bab1c8b2a319ae0b4794973df321a45d0bc054c273c9d567db1c86325a9b2739e40a818b101106c9b3a
+  data.tar.gz: 331ddb0387c6ee4339e1988a69c79cb9851d5f33f2ccd519036dec9d88c5b8d7fcd3744418e881550c915f568a6efb8fe352c4e80d0a08eb79b3833469221662

data/README.md

@@ -264,7 +264,7 @@ Tramway.configure do |config|
 end
 ```
 
-**form_fields method**
+**fields method**
 
 Use `form_fields` in your form class to customize which form helpers get rendered and which options are passed to them.
 Each field must map to a form helper method name. When you need to pass options, use a hash where `:type` is the helper
@@ -275,6 +275,7 @@ class UserForm < Tramway::BaseForm
   properties :email, :about_me
 
   fields email: :email,
+    name: :text,
     about_me: {
       type: :text_area,
       rows: 5
@@ -287,6 +288,7 @@ The configuration above renders:
 ```erb
 <%= tramway_form_for .... do |f| %>
   <%= f.email_field :email %>
+  <%= f.text_field :name %>
   <%= f.text_area :about_me, rows: 5 %>
 ```
 
@@ -893,13 +895,46 @@ component applies.
 
 Tramway ships with helpers for common UI patterns built on top of Tailwind components.
 
-* `tramway_button` renders a button-styled form submit by default and accepts `path`, optional `text`, HTTP `method`, and styling
-  options such as `color`, `type`, and `size`. It uses Rails' `button_to` helper by default (or when `link: false` is passed),
-  and switches to `link_to` when you set `link: true`.
+`tramway_button` helper is designed for developers who don't want to think about what type of button must be used now. It can render 3 types of buttons: `a` (links), `button`, `form` with button.
 
-  ```erb
-  <%= tramway_button path: user_path(user), text: 'Open profile', link: true %>
-  ```
+You can set a type to render explicitly:
+
+```ruby
+tramway_button tag: :a, text: 'Link' #=> <a class=BUTTON_CLASSES>Link</a>
+tramway_button tag: :button, text: 'Link' #=> <button class=BUTTON_CLASSES>Link</button>
+tramway_button tag: :form, text: 'Link' #=> <form><button class=BUTTON_CLASSES>Link</button></form>
+```
+
+OR `tramway_button` choose the most appropriate button type by the arguments received.
+
+#### `tramway_button` options
+
+**path**
+
+Example 1: rendering link
+```erb
+<%= tramway_button path: '/projects', text: 'Projects' %>
+
+#=> <a href='/projects' class="...">Projects</a>
+```
+
+Example 2: rendering form
+```erb
+<%= tramway_button path: '/projects/1', text: 'Destroy', method: :delete %>
+
+#> <form action="/projects/1"  method="post">
+#>   ....
+#>   <button class: "..." type="submit">
+#>     Delete
+#>   </button>
+```
+
+Example 3: rendering button
+```
+<%= tramway_button path: '/projects/1', text: 'Edit', tag: :button %>
+
+#> <button onclick="window.location.href='/projects/1' class="...">Edit</button>
+```
 
   All additional keyword arguments are forwarded to the underlying component as HTML attributes.
 
@@ -914,30 +949,6 @@ Tramway ships with helpers for common UI patterns built on top of Tailwind compo
 
   The `type` option maps semantic intent to [Lantern Color Palette](https://github.com/TrinityMonsters/tramway/blob/main/README.md#lantern-color-palette).
 
-  If none of the predefined semantic types fit your needs, you can supply a Tailwind color family directly using the `color`
-  option—for example: `color: :gray`. When you pass a custom color ensure the corresponding utility classes exist in your
-  Tailwind configuration. Add the following safelist entries (adjusting the color name as needed) to `config/tailwind.config.js`:
-
-  ```js
-  // config/tailwind.config.js
-  module.exports = {
-    // ...
-    safelist: [
-      // existing entries …
-      {
-        pattern: /(bg|hover:bg|dark:bg|dark:hover:bg)-gray-(500|600|700|800)/,
-      },
-    ],
-  }
-  ```
-
-  Tailwind will then emit the `bg-gray-500`, `hover:bg-gray-700`, `dark:bg-gray-600`, and `dark:hover:bg-gray-800` classes that
-  Tramway buttons expect when you opt into a custom color.
-
-  ```erb
-  <%= tramway_button path: user_path(user), text: 'View profile', color: :emerald, data: { turbo: false } %>
-  ```
-
 * `tramway_badge` renders a Tailwind-styled badge with the provided `text`. Pass a semantic `type` (for example, `:success` or
   `:danger`) to use the built-in color mappings, or supply a custom Tailwind color family with `color:`. When you opt into a
   custom color, ensure the corresponding background utilities are available in your Tailwind safelist.

data/app/components/tailwinds/button_component.html.haml

@@ -1,20 +1,20 @@
 - if text.present?
-  - if render_a_tag?
+  - case @tag
+  - when :a
     = link_to text, path, class: classes, **render_options
-  - else
-    - if type&.to_sym == :submit
-      %button{ type: :submit, name: :commit, class: classes, **render_options }
-        = text
-    - else
-      = button_to text, path, method:, form: form_options, class: classes, **render_options
+  - when :button
+    %button{ class: classes, **render_options }
+      = text
+  - when :form
+    = helpers.button_to text, path, method:, form: form_options, class: classes, **render_options
 - else
-  - if render_a_tag?
+  - case @tag
+  - when :a
     = link_to path, class: classes, **render_options do
       = content
-  - else
-    - if type&.to_sym == :submit
-      %button{ type: :submit, name: :commit, class: classes, **render_options }
-        = content
-    - else
-      = button_to path, method:, class: classes, form: form_options, **render_options do
-        = content
+  - when :button
+    %button{ type: :submit, name: :commit, class: classes, **render_options }
+      = content
+  - when :form
+    = helpers.button_to path, method:, class: classes, form: form_options, **render_options do
+      = content

data/app/components/tailwinds/button_component.rb

@@ -10,10 +10,21 @@ module Tailwinds
     option :type, optional: true
     option :size, default: -> { :medium }
     option :method, optional: true, default: -> { :get }
-    option :link, optional: true, default: -> { false }
+    option :tag, optional: true, default: -> { false }
     option :options, optional: true, default: -> { {} }
     option :form_options, optional: true, default: -> { {} }
 
+    def before_render
+      return if tag.present?
+      return @tag = :button if type == :submit
+
+      URI.parse(path)
+
+      return @tag = :a if method.to_s.downcase == 'get'
+
+      @tag = :form
+    end
+
     def size_classes
       unless size.in?(%i[small medium large])
         raise ArgumentError, "Invalid size: #{size}. Valid sizes are :small, :medium, :large."
@@ -29,7 +40,7 @@ module Tailwinds
     def classes
       (default_classes +
         color_classes +
-        (render_a_tag? ? %w[px-1 h-fit w-fit] : [cursor_class])).compact.join(' ')
+        (@tag == :a ? %w[px-1 h-fit w-fit] : [cursor_class])).compact.join(' ')
     end
 
     def default_classes
@@ -57,17 +68,6 @@ module Tailwinds
       options[:disabled] || false
     end
 
-    def render_a_tag?
-      return true if link
-      return true if path == '#' && type != :submit
-
-      uri = URI.parse(path)
-
-      return true if method.to_s.downcase == 'get' && uri.query && !uri.query.empty?
-
-      false
-    end
-
     def render_options
       base_options = options.except(:class)
       return base_options unless stop_cell_propagation?
@@ -88,7 +88,7 @@ module Tailwinds
     end
 
     def cursor_class
-      if !render_a_tag? && !disabled?
+      if @tag != :a && !disabled?
         'cursor-pointer'
       else
         'cursor-not-allowed'

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

@@ -92,7 +92,7 @@ module Tailwinds
       def submit(action, **options, &)
         sanitized_options = sanitize_options(options)
 
-        render(Tailwinds::Form::SubmitButtonComponent.new(action, size: form_size, **sanitized_options), &)
+        render(Tailwinds::ButtonComponent.new(text: action, size: form_size, type: :submit, **sanitized_options), &)
       end
 
       private

data/app/components/tramway/entity_component.html.haml

@@ -9,7 +9,8 @@
           = tramway_button text: t('tramway.actions.edit'),
             path: Tramway::Engine.routes.url_helpers.public_send(entity.routes.edit, item.id),
             type: :will,
-            size: :small
+            size: :small,
+            tag: :form
 
         - if @entity.page(:destroy).present?
           = tramway_button text: t('tramway.actions.destroy'),

data/docs/AGENTS.md

@@ -78,14 +78,285 @@ config/
 
 ## Rules
 
-- Use Tramway Entities and Tramway actions (index, show, create, update, destroy) by default unless custom behavior is needed. Configure in `config/initializers/tramway.rb`.
-- Normalize input with `normalizes` (from Tramway) for attributes like email, phone, etc.
-- Use Tramway Navbar for navigation
-- Use Tramway Flash for user notifications.
-- Use Tramway Table for tabular data display.
-- Use Tramway Button for buttons.
-- Use `tramway_form_for` instead `form_with`, `form_for`
-- Inherit all components from Tramway::BaseComponent
+### Rule 1
+If CRUD is requested or some default actions like (index, show, create, update, destroy) are requestsed, use Tramway Entities by default unless custom behavior is needed. Configure in `config/initializers/tramway.rb`. Do not create controllers, views, or routes manually for CRUD actions if Tramway Entities can handle it.
+
+When `namespace` is mentioned in the request, configure it in the entity definition.
+
+Example of CRUD configuration for model `Participant`:
+
+*config/initializers/tramway.rb*:
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :participant,
+      pages: [
+        { action: :index },
+        { action: :show },
+        { action: :create },
+        { action: :update },
+        { action: :destroy }
+      ]
+    }
+  ]
+end
+```
+
+### Rule 2
+Normalize input with `normalizes` (from Tramway) for attributes like email, phone, etc. Don't use `normalizes` in model unless it requested explicitly.
+
+### Rule 3
+Use Tramway Navbar for navigation
+
+### Rule 4
+Use Tramway Flash for user notifications.
+
+### Rule 5
+Use Tramway Table for tabular data display.
+
+### Rule 6
+Use Tramway Button for buttons.
+
+### Rule 7
+Use `tramway_form_for` instead `form_with`, `form_for`
+
+### Rule 8
+Inherit all components from Tramway::BaseComponent
+
+### Rule 9
+If page `create` or `update` is configured for an entity, use Tramway Form pattern for forms. Visible fields are configured via `form_fields` method.
+
+Use form_fields in your form class to customize which form helpers get rendered and which options are passed to them. Each field must map to a form helper method name. When you need to pass options, use a hash where :type is the helper method name and the remaining keys are passed as named arguments.
+
+Example:
+
+*app/forms/user_form.rb*:
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :about_me
+
+  fields email: :email,
+    name: :text,
+    about_me: {
+      type: :text_area,
+      rows: 5
+    }
+end
+```
+
+### Rule 10
+Do not use `strong_parameters` in controllers. Use Tramway Form pattern for parameter whitelisting.
+
+### Rule 11
+Create tests for show models pages inside `spec/features/#{pluralized model_name}/show_spec.rb` using RSpec and Capybara if it needed.
+
+Here is an example for `Task` model:
+
+```ruby
+describe 'Tasks Show Page', type: :feature do
+  let!(:task) do
+    create(:task)
+  end
+
+  it 'displays the task' do
+    visit task_path(task)
+
+    expect(page).to have_current_path(task_path(task))
+    expect(page).to have_content(task.name)
+    expect(page).to have_content('Pending')
+  end
+end
+```
+
+### Rule 12
+Create tests for index models pages inside `spec/features/#{pluralized model_name}/index_spec.rb` using RSpec and Capybara if it needed.
+
+Here is an example for `Project` model:
+
+```ruby
+describe 'Projects Index Page', type: :feature do
+  let!(:projects) { create_list(:project, 3) }
+
+  describe 'visiting the index page' do
+    before do
+      visit projects_path
+    end
+
+    it 'displays all projects' do
+      expect(page).to have_current_path(projects_path)
+
+      projects.each do |project|
+        expect(page).to have_content(project.name)
+      end
+    end
+  end
+end
+```
+
+### Rule 13
+Create tests for create models pages inside `spec/features/#{pluralized model_name}/create_spec.rb` using RSpec and Capybara if it needed.
+
+Here is an example for `Project` model:
+
+```ruby
+describe 'Projects Create', type: :feature do
+  let!(:project_attributes) do
+    attributes_for(:project)
+  end
+  
+  let(:project) { Project.last }
+
+  it 'creates a new project' do
+    visit new_project_path
+
+    expect(page).to have_current_path(new_project_path)
+
+    fill_in 'project[name]', with: project_attributes[:name]
+    fill_in 'project[description]', with: project_attributes[:description]
+    select project_attributes[:project_type], from: 'project[project_type]'
+
+    click_on 'Save'
+
+    expect(project).to have_attributes(
+      name: project_attributes[:name],
+      description: project_attributes[:description],
+    )
+  end
+end
+```
+
+### Rule 14
+Create tests for update models pages inside `spec/features/#{pluralized model_name}/update_spec.rb` using RSpec and Capybara if it needed.
+
+Here is an example for `Project` model:
+
+```ruby
+describe 'Projects Update', type: :feature do
+  let!(:project) do
+    create('project', user: current_user)
+  end
+
+  let!(:project_attributes) do
+    attributes_for(:project)
+  end
+
+  it 'updates the project' do
+    visit edit_project_path(project)
+
+    expect(page).to have_current_path(edit_project_path(project))
+
+    fill_in 'project[name]', with: project_attributes[:name]
+    fill_in 'project[description]', with: project_attributes[:description]
+
+    click_on 'Save'
+
+    expect(page).to have_content('Project was successfully updated.')
+    expect(page).to have_content(project_attributes[:name])
+    expect(page).to have_content(project_attributes[:description])
+
+    project.reload
+
+    expect(project).to have_attributes(
+      name: project_attributes[:name],
+      description: project_attributes[:description]
+    )
+  end
+end
+```
+
+### Rule 15
+Create tests for destroy models pages inside `spec/features/#{pluralized model_name}/destroy_spec.rb` using RSpec and Capybara if it needed.
+
+Here is an example for `Project` model:
+
+```ruby
+describe 'Project Destroy', type: :feature do
+  let!(:project) do
+    create('project')
+  end
+
+  it 'destroys the project' do
+    visit project_path(project)
+
+    expect(page).to have_current_path(project_path(project))
+
+    click_on 'Delete'
+
+    expect(page).to have_content('Project was successfully destroyed.')
+
+    expect { Project.find(project.id) }.to raise_error(ActiveRecord::RecordNotFound)
+  end
+end
+```
+
+### Rule 16
+If you created any tests for Tramway Entities pages, make sure to add this to `spec/rails_helper.rb`.
+
+*spec/rails_helper.rb*:
+```ruby
+RSpec.configure do |config|
+  config.include Tramway::Helpers::RoutesHelper, type: :feature
+end
+```
+
+### Rule 17
+If application has authentication in the web then use `application_controller` config in `config/initializers/tramway.rb` to setup authentication method for Tramway Entities.
+
+*config/initializers/tramway.rb*:
+```ruby
+Tramway.configure do |config|
+  config.application_controller = 'ApplicationController'
+end
+```
+
+### Rule 18
+If you use `index` page for Tramway Entity, make sure to create `index_attributes` method in the entity decorator.
+
+Example for `Participant` model:
+
+*app/decorators/participant_decorator.rb*:
+```ruby
+class ParticipantDecorator < Tramway::BaseDecorator
+  def self.index_attributes
+    [
+      :id,
+      :name,
+      :email,
+      :created_at
+    ]
+  end
+end
+```
+
+### Rule 19
+In specs ALWAYS use factories (FactoryBot gem) to create models and attributes hash. In case there is no factory for the model, create one inside `spec/factories/#{pluralized model_name}.rb`.
+
+### Rule 20
+In case you need enumerize for model attribute, make sure to use `enumerize` gem for that. DO NOT use `boolean` or `integer` types for enumerations.
+
+### Rule 21
+In case you need something that looks like enumerize but it's a process state, use `aasm` gem for that.
+
+### Rule 22
+Use model scopes instead of creating private methods for object collections.
+
+### Rule 23
+Use `tramway_title` for the main title on pages
+
+Example
+*app/models/user.rb*
+```ruby
+class User < ApplicationRecord
+  scope :this_month_registered_users, -> { where(created_at: Time.current.all_month) }
+end
+```
+
+### Rule 24
+In case you implementing API, use `api` namespaces for forms and decorators.
+
+### Rule 25
+DO NOT use `#{model_name}_params` method with `permit` method inside controllers. When you use `tramway_form`, it's unnecessary.
 
 ## Controller Patterns
 
@@ -141,6 +412,7 @@ class ParticipantsController < ApplicationController
 end
 ```
 
+
 ---
 
 ## Tailwind Practices

data/lib/tramway/helpers/views_helper.rb

@@ -40,12 +40,11 @@ module Tramway
         component 'tailwinds/table/cell', &
       end
 
-      # rubocop:disable Metrics/ParameterLists
-      def tramway_button(path: nil, text: nil, method: :get, link: false, form_options: {}, **options, &)
-        component 'tailwinds/button', text:, path:, method:, link:, form_options:, color: options.delete(:color),
-                                      type: options.delete(:type), size: options.delete(:size), options:, &
+      def tramway_button(path: nil, text: nil, method: :get, form_options: {}, **options, &)
+        component 'tailwinds/button', text:, path:, method:, form_options:, color: options.delete(:color),
+                                      type: options.delete(:type), size: options.delete(:size),
+                                      tag: options.delete(:tag), options:, &
       end
-      # rubocop:enable Metrics/ParameterLists
 
       def tramway_back_button
         component 'tailwinds/back_button'

data/lib/tramway/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 2.2.2.7
+  version: 2.2.3
 platform: ruby
 authors:
 - kalashnikovisme
@@ -178,8 +178,6 @@ files:
 - app/components/tailwinds/form/number_field_component.rb
 - app/components/tailwinds/form/select_component.html.haml
 - app/components/tailwinds/form/select_component.rb
-- app/components/tailwinds/form/submit_button_component.html.haml
-- app/components/tailwinds/form/submit_button_component.rb
 - app/components/tailwinds/form/text_area_component.html.haml
 - app/components/tailwinds/form/text_area_component.rb
 - app/components/tailwinds/form/text_field_component.html.haml

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

@@ -1,11 +0,0 @@
-.flex.items-center.justify-between
-  - classes = "#{size_class(:submit_button)} #{submit_button_base_classes}"
-
-  = helpers.tramway_button text: @text,
-    type: :submit,
-    name: :commit,
-    size:,
-    class: classes,
-    **@options
-
-  = @content

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

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Tailwinds
-  module Form
-    # Tailwind-styled submit button
-    class SubmitButtonComponent < TailwindComponent
-      def initialize(action, size: :medium, **options)
-        unless size.in?(%i[small medium large])
-          raise ArgumentError, "Invalid size: #{size}. Valid sizes are :small, :medium, :large."
-        end
-
-        @text = action.is_a?(String) ? action : action.to_s.capitalize
-
-        super(input: nil, attribute: nil, value: nil, options: options.except(:type), label: nil, for: nil, size:)
-      end
-    end
-  end
-end