tramway 3.1.2.6 → 3.1.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9b234f727ff8de6c0d6f910d4132ae760f304db2b2e4fb211c06a1983264a18
-  data.tar.gz: b94972e8d2862560cefca6f4343e15c3b362be56038426cda2b3a988b8705329
+  metadata.gz: 1bc6a1e219c499e701dd4ec09e3e04d722ba480744c25db62f4b8f5b75f3c365
+  data.tar.gz: 5fd9987b47419d936e0bd50dbf727147c149c33948188d53589cc3666482829b
 SHA512:
-  metadata.gz: 59d8c55e6c5300996bc0250d106715647180320c0ab044a1e99dde08188cc887f5de4d8d2f175246c06a73e25f90c7dcea537ff58f0ff29a07f01ba278f346e9
-  data.tar.gz: 5061f9357362cf45cfbfe5cc96ca937cdb4a1be8f58a6e156946c4ac2ea277ca3b3d5615f18fb66372a4ea33f57b39a71e33d15542ea2ff72ddf4b2bdf169ae3
+  metadata.gz: 7c4fb50d8f6579be7bb697af7a93b3e1b69199724e6ca23b1a54e03809bc8de896a43d2faf22dcfd0bc3f1755648689c888659c0ffcb19f90407a2036a2c0d44
+  data.tar.gz: cc2131f3a6f9302ab31db63ca04fce6339e770c9694a97d147e340e8294002ed1707bd5ed5c511b2e1293f369f23139bd57e6236d467fcc9a7f84b8bc0e00e68

data/README.md

@@ -535,6 +535,86 @@ class UserDecorator < Tramway::BaseDecorator
 end
 ```
 
+#### Show associations
+
+Entity show pages can render associated records by returning association names from
+the decorator's `show_associations` method. Each name must be an actual
+Active Record association on the decorated model; Tramway raises a clear error
+when the association is missing.
+
+*app/models/post.rb*
+```ruby
+class Post < ApplicationRecord
+  has_many :comments
+end
+```
+
+*app/decorators/post_decorator.rb*
+```ruby
+class PostDecorator < Tramway::BaseDecorator
+  association :comments
+
+  def show_associations
+    %i[comments]
+  end
+end
+```
+
+Tramway renders a `New` button for a shown association when it can determine a
+create path for that association. Define the associated model as a Tramway entity
+with a `:create` page to let Tramway build that path automatically:
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :post,
+      pages: [
+        { action: :show }
+      ]
+    },
+    {
+      name: :comment,
+      pages: [
+        { action: :create }
+      ]
+    }
+  ]
+end
+```
+
+When `new_record_path` is omitted, Tramway looks for a configured entity using
+the association reflection's class name in underscore format. This means aliases
+such as `has_many :responses, class_name: 'Comment'` use the `comment` entity,
+not a `response` entity.
+
+Generated association create paths include a `redirect` query parameter pointing
+to the current record's configured Tramway entity show path, for example:
+`/comments/new?redirect=%2Fposts%2F1`.
+
+You can override the path explicitly when the associated record should be created
+through a custom route:
+
+```ruby
+class PostDecorator < Tramway::BaseDecorator
+  association :comments
+
+  def show_associations
+    [
+      [
+        :comments,
+        { new_record_path: Rails.application.routes.url_helpers.new_post_comment_path(object) }
+      ]
+    ]
+  end
+end
+```
+
+Tramway still appends the `redirect` query parameter to custom paths. Associations
+without a create route and without `new_record_path` still render their records,
+but no creation button is displayed.
+
 #### Decorate nil
 
 Tramway Decorator does not decorate nil objects
@@ -1253,10 +1333,12 @@ will render [this](https://play.tailwindcss.com/xho3LfjKkK)
 Use `size:` to control the input sizing (`:small`, `:medium`, or `:large`). The default is `:medium`, and supported inputs
 rendered within the form will use the same size value.
 Date and datetime fields open the browser's native picker when clicking anywhere in the input, not only the picker icon.
+Use `hint:` on any field to render muted helper text below the input. The hint option is handled by Tramway and is not
+forwarded as an HTML attribute.
 
 ```erb
 <%= tramway_form_for @user, size: :large do |f| %>
-  <%= f.text_field :text %>
+  <%= f.text_field :text, hint: 'This name is visible to teammates.' %>
   <%= f.submit 'Create User' %>
 <% end %>
 ```

data/app/components/tailwind_component.rb

@@ -10,6 +10,7 @@ class TailwindComponent < Tramway::BaseComponent
   option :options
   option :label
   option :for
+  option :hint, optional: true, default: -> {}
   option :size, default: -> { :medium }
 
   SIZE_CLASSES = {
@@ -83,6 +84,10 @@ class TailwindComponent < Tramway::BaseComponent
       'peer-disabled:opacity-70'
   end
 
+  def form_hint_classes
+    'mt-1 text-sm text-zinc-400'
+  end
+
   def default_container_classes
     return if options[:horizontal]
 

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

@@ -210,11 +210,16 @@ module Tramway
           attribute:,
           label: label_build(attribute, options),
           for: options[:id].presence || for_id(attribute),
+          hint: hint_option(options),
           options: options,
           size: form_size
         }
       end
 
+      def hint_option(options)
+        options.delete(:hint) || options.delete('hint')
+      end
+
       def label_build(attribute, options)
         label_option = options[:label]
 

data/app/components/tramway/form/checkbox_component.html.haml

@@ -1,29 +1,32 @@
-.flex.items-center.gap-2{ class: default_container_classes, data: { controller: 'ui--checkbox' } }
-  - checkbox_checked = checked?
-  = @input.call @attribute, **hidden_checkbox_options
-  %button{ type: 'button',
-    role: 'checkbox',
-    'aria-checked' => checkbox_checked.to_s,
-    'data-action' => 'click->ui--checkbox#toggle',
-    'data-state' => checkbox_checked ? 'checked' : 'unchecked',
-    'data-ui--checkbox-target' => 'button',
-    value: 'on',
-    class: checkbox_button_classes,
-    style: checkbox_button_style,
-    for: @for,
-    id: @for }
-    %span{ class: checkbox_indicator_classes, style: 'pointer-events: none', data: { 'ui--checkbox-target' => 'indicator' } }
-      %svg{ xmlns: 'http://www.w3.org/2000/svg',
-        width: '24',
-        height: '24',
-        viewBox: '0 0 24 24',
-        fill: 'none',
-        stroke: 'currentColor',
-        'stroke-width' => '2',
-        'stroke-linecap' => 'round',
-        'stroke-linejoin' => 'round',
-        class: size_class(:checkbox_indicator) }
-        %polyline{ points: '20 6 9 17 4 12' }
-  - if @label
-    = component('tramway/form/label', for: @for, options: { class: label_classes, style: label_style, data: { action: 'click->ui--checkbox#toggle' } }) do
-      = @label
+%div{ class: default_container_classes, data: { controller: 'ui--checkbox' } }
+  .flex.items-center.gap-2
+    - checkbox_checked = checked?
+    = @input.call @attribute, **hidden_checkbox_options
+    %button{ type: 'button',
+      role: 'checkbox',
+      'aria-checked' => checkbox_checked.to_s,
+      'data-action' => 'click->ui--checkbox#toggle',
+      'data-state' => checkbox_checked ? 'checked' : 'unchecked',
+      'data-ui--checkbox-target' => 'button',
+      value: 'on',
+      class: checkbox_button_classes,
+      style: checkbox_button_style,
+      for: @for,
+      id: @for }
+      %span{ class: checkbox_indicator_classes, style: 'pointer-events: none', data: { 'ui--checkbox-target' => 'indicator' } }
+        %svg{ xmlns: 'http://www.w3.org/2000/svg',
+          width: '24',
+          height: '24',
+          viewBox: '0 0 24 24',
+          fill: 'none',
+          stroke: 'currentColor',
+          'stroke-width' => '2',
+          'stroke-linecap' => 'round',
+          'stroke-linejoin' => 'round',
+          class: size_class(:checkbox_indicator) }
+          %polyline{ points: '20 6 9 17 4 12' }
+    - if @label
+      = component('tramway/form/label', for: @for, options: { class: label_classes, style: label_style, data: { action: 'click->ui--checkbox#toggle' } }) do
+        = @label
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/date_field_component.html.haml

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:text_input)} #{text_input_base_classes}"
   = @input.call @attribute, **picker_options(classes), value: @value
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/datetime_field_component.html.haml

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:text_input)} #{text_input_base_classes}"
   = @input.call @attribute, **picker_options(classes), value: @value
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

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

@@ -5,3 +5,5 @@
     %label{ for: @for, class: classes }
       = @label
   = @input
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/number_field_component.html.haml

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:text_input)} #{text_input_base_classes}"
   = @input.call @attribute, **@options.merge(class: classes), value: @value
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/rich_text_area_component.html.haml

@@ -12,3 +12,5 @@
     = component('tramway/form/label', for: @for, class: 'mb-0') do
       = @label
   = @input.call @attribute, **rich_text_area_options
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/select_component.html.haml

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:select_input)} #{select_base_classes}"
   = @input.call(@attribute, @collection, { selected: @value }, @options.merge(class: classes))
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/text_area_component.html.haml

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:text_input)} #{text_input_base_classes}"
   = @input.call @attribute, **@options.merge(class: classes), value: @value
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

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

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:text_input)} #{text_input_base_classes}"
   = @input.call @attribute, **@options.merge(class: classes), value: @value
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/time_field_component.html.haml

@@ -4,3 +4,5 @@
       = @label
   - classes = "#{size_class(:text_input)} #{text_input_base_classes}"
   = @input.call @attribute, **@options.merge(class: classes), value: @value
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/components/tramway/form/tramway_select_component.html.haml

@@ -11,3 +11,5 @@
           = component 'tramway/form/tramway_select/caret', size:, direction: :down
         .caret-up.hidden{ data: { "tramway-select-target" => "caretUp" } }
           = component 'tramway/form/tramway_select/caret', size:, direction: :up
+  - if @hint.present?
+    %p{ class: form_hint_classes }= @hint

data/app/controllers/tramway/entities_controller.rb

@@ -91,35 +91,7 @@ module Tramway
     end
 
     def set_associations
-      @associations = @record.show_associations.map do |(association, options)|
-        options ||= {}
-        association_type = @record.object.class.reflect_on_association(association).macro
-
-        {
-          name: association,
-          association_type:,
-          **send("#{association_type}_associations", association, options)
-        }
-      end.compact
-    end
-
-    # rubocop:disable Naming/PredicatePrefix
-    def has_many_associations(association, options)
-      records = Kaminari.paginate_array(@record.public_send(association.name)).page(params[:page])
-
-      {
-        decorator: records.first&.class,
-        records:,
-        model_class: records.first&.object&.class,
-        new_record_path: options[:new_record_path]
-      }
-    end
-    # rubocop:enable Naming/PredicatePrefix
-
-    def belongs_to_associations(association, _options)
-      record = @record.public_send(association.name)
-
-      { decorator: record.class, record:, model_class: record.class }
+      @associations = @record.send(:__show_associations, params[:page])
     end
 
     def search(entities)

data/app/views/tramway/entities/show.html.haml

@@ -52,9 +52,10 @@
             custom_path_method: @entity.index_helper_method,
             custom_path_arguments: [@record.id]
 
-      = tramway_button text: t('tramway.actions.new'),
-        path: association[:new_record_path],
-        type: :will
+      - if association[:new_record_path].present?
+        = tramway_button text: t('tramway.actions.new'),
+          path: association[:new_record_path],
+          type: :will
 
     - if association[:records].any?
       = tramway_table class: 'mt-4' do 

data/docs/AGENTS.md

@@ -712,12 +712,15 @@ end
 
 ```ruby
 = tramway_form_for @user do |f|
-  = f.email_field :email
+  = f.email_field :email, hint: 'Use the address where you receive account notifications.'
   = f.password_field :password
   = f.select :role, [["Admin", "admin"], ["Manager", "manager"]], include_blank: "Select role"
   = f.submit 'Save'
 ```
 
+Use `hint:` on fields when short helper text should appear below the input. Tramway renders the hint separately and does
+not forward it to the input as an HTML attribute.
+
 Autocomplete select example:
 
 ```ruby

data/lib/tramway/base_decorator.rb

@@ -3,6 +3,7 @@
 require 'tramway/decorators/name_builder'
 require 'tramway/decorators/association'
 require 'tramway/decorators/collection_decorator'
+require 'tramway/decorators/show_associations'
 require 'tramway/helpers/decorate_helper'
 require 'tramway/helpers/component_helper'
 require 'tramway/helpers/views_helper'
@@ -14,6 +15,7 @@ module Tramway
   #
   class BaseDecorator
     include Tramway::Decorators::CollectionDecorators
+    include Tramway::Decorators::ShowAssociations
     include Tramway::Utils::Render
     include Tramway::DuckTyping::ActiveRecordCompatibility
     include Tramway::Helpers::DecorateHelper

data/lib/tramway/decorators/show_associations.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'rack/utils'
+
+module Tramway
+  module Decorators
+    # Builds metadata for associations rendered on Tramway entity show pages.
+    module ShowAssociations
+      private
+
+      def __show_associations(page)
+        show_associations.map do |(association, options)|
+          __show_association(association, options || {}, page)
+        end.compact
+      end
+
+      def __show_association(association, options, page)
+        reflection = __reflection_for_show_association(association)
+        association_type = reflection.macro
+        association_options = __association_options(association, association_type, options, page)
+        new_record_path = __association_new_record_path(reflection, association_options.delete(:new_record_path))
+
+        {
+          name: association,
+          association_type:,
+          new_record_path:,
+          **association_options
+        }
+      end
+
+      def __reflection_for_show_association(association)
+        reflection = object.class.reflect_on_association(association)
+
+        return reflection if reflection.present?
+
+        raise "You must define #{association} association in the #{object.class}"
+      end
+
+      def __association_options(association, association_type, options, page)
+        send("__#{association_type}_associations", association, options, page)
+      end
+
+      def __association_new_record_path(reflection, new_record_path)
+        new_record_path = __inferred_association_new_record_path(reflection) if new_record_path.blank?
+
+        return if new_record_path.blank?
+
+        __new_record_path_with_redirect(new_record_path)
+      end
+
+      def __inferred_association_new_record_path(reflection)
+        association_entity = __entity_for_name(reflection.class_name.underscore)
+
+        return if association_entity.blank? || association_entity.page(:create).blank?
+
+        Tramway::Engine.routes.url_helpers.public_send(association_entity.new_helper_method)
+      end
+
+      def __new_record_path_with_redirect(new_record_path)
+        redirect_path = __entity_show_path
+
+        return new_record_path if redirect_path.blank?
+
+        separator = new_record_path.include?('?') ? '&' : '?'
+
+        "#{new_record_path}#{separator}#{Rack::Utils.build_query(redirect: redirect_path)}"
+      end
+
+      def __entity_show_path
+        entity = __entity_for_name(object.class.name.underscore)
+
+        return if entity.blank? || entity.page(:show).blank?
+
+        Tramway::Engine.routes.url_helpers.public_send(entity.show_helper_method, object.id)
+      end
+
+      def __entity_for_name(name)
+        Tramway.config.entities.find do |config_entity|
+          config_entity.name == name
+        end
+      end
+
+      def __has_many_associations(association, options, page)
+        records = Kaminari.paginate_array(public_send(association.name)).page(page)
+
+        {
+          decorator: records.first&.class,
+          records:,
+          model_class: records.first&.object&.class,
+          new_record_path: options[:new_record_path]
+        }
+      end
+
+      def __belongs_to_associations(association, _options, _page)
+        record = public_send(association.name)
+
+        { decorator: record.class, record:, model_class: record.class }
+      end
+    end
+  end
+end

data/lib/tramway/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 3.1.2.6
+  version: 3.1.2.7
 platform: ruby
 authors:
 - kalashnikovisme
@@ -282,6 +282,7 @@ files:
 - lib/tramway/decorators/class_helper.rb
 - lib/tramway/decorators/collection_decorator.rb
 - lib/tramway/decorators/name_builder.rb
+- lib/tramway/decorators/show_associations.rb
 - lib/tramway/duck_typing.rb
 - lib/tramway/duck_typing/active_record_compatibility.rb
 - lib/tramway/engine.rb