tramway 4.1.0.1 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7992bbaa872dc64b21203cb0350463136687e0bfe033a1b461c87bf15804f6b
-  data.tar.gz: 24024ccfa23c7e0718a8dcfd708ce4fcfe232e67c352e5fa28360b017f0b323e
+  metadata.gz: 157c85b21871fba844d2da67a40213a63b7613a9110e5fd8e72b430eea52c1cb
+  data.tar.gz: 19448d06038afe21efe938b9abe4db4eca02bb37c79b63a6d3dabc303fbff362
 SHA512:
-  metadata.gz: 5a8e09bf7ab1d4c09d881f87d99cd1ab5841e92b29a17e2bab144bc009e70263af0cf3ffc71930a027dd589beb13f50c933f4ffcc9fb292e3c36e75f2015b699
-  data.tar.gz: 0110e0d22d0f745d459021d97b929ed4915e08d292a706d7a06dd0c409cd2426c42f2fdb0e40af5ef243e1609b8c37c5ad20204c38b7d16db4f4d0f9d5599b89
+  metadata.gz: d0c54e34d0017715e2b4d0b0f351abebf0f02a3029cc4762bf40c07abd0198e8945b7b1bf3e474051263afddb9a65e518fa8febdae127b323e755c67c814049f
+  data.tar.gz: 8acef7a5b516284dfa3d44901cf059f8c9632aedc41bf2bbe1a93f8c7b840bb6988f424449e9fde2f53558e0f78a5dba2cc02b61d478669bdb05318d33d6102e

data/README.md

@@ -331,6 +331,18 @@ end
 With this configuration in place, visiting the show page displays a two-column table where the left column contains the
 localized attribute names and the right column renders their values.
 
+Each entry in `show_attributes` can also be a Hash instead of a plain symbol, to pass options to the `tramway_cell`
+rendering that attribute's value. The Hash requires an `attribute:` key (the method to display) and accepts an
+`options:` key (a Hash forwarded as-is to `tramway_cell`, e.g. `truncate: false`):
+
+```ruby
+class CampaignDecorator < Tramway::BaseDecorator
+  def show_attributes
+    [:name, { attribute: :status, options: { truncate: false } }, :starts_at]
+  end
+end
+```
+
 **create page**
 
 To render a create page for an entity, declare a `:create` action inside the `pages` array in
@@ -430,6 +442,62 @@ Tramway.configure do |config|
 end
 ```
 
+**custom page**
+
+Besides the built-in `index`, `show`, `create`, `update`, and `destroy` pages, an entity can declare **Custom Pages**:
+your own controller action and view, loaded through the same routing, layout, and navbar as the rest of the entity's
+pages. Use a Custom Page for anything that doesn't fit the built-in CRUD actions — a report, a bulk tool, an
+"impersonate" button's target page, and so on.
+
+Declare it by adding a page whose `action` is not one of the built-in ones:
+
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :user,
+      namespace: :admin,
+      pages: [
+        { action: :index },
+        {
+          action: :impersonate,
+          member: true,       # nests the route under /:id (default: false, an entity-level route)
+          via: :post,         # HTTP method(s) the route accepts (default: :get); also accepts an array, e.g. %i[get post]
+          params: [:redirect_to] # extra required path segments, e.g. /admin/users/:id/impersonate/:redirect_to
+        }
+      ]
+    }
+  ]
+end
+```
+
+Then implement the action yourself, by Rails naming convention, in the controller Tramway would otherwise generate
+for that namespace/entity (here, `Admin::UsersController`), inheriting from `Tramway::EntitiesController` so it gets
+the same layout, navbar, and `entity`/`model_class` lookups as the built-in pages:
+
+```ruby
+# app/controllers/admin/users_controller.rb
+module Admin
+  class UsersController < Tramway::EntitiesController
+    def impersonate
+      @user = model_class.find(params[:id])
+      # ...
+    end
+  end
+end
+```
+
+And add its view at the conventional Rails path for that controller/action:
+
+```haml
+-# app/views/admin/users/impersonate.html.haml
+= tramway_container do
+  %p Impersonating #{@user.email}
+```
+
+See [docs/users/tramway_custom_pages.md](docs/users/tramway_custom_pages.md) for how the routing/controller/view
+resolution works under the hood.
+
 **route_helper**
 
 To get routes Tramway generated just Tramway::Engine.
@@ -1319,6 +1387,15 @@ interactivity.
 Cell content that does not fit its column is truncated with an ellipsis. This is a pure CSS behavior (`truncate` +
 `min-w-0` on each cell) — no JavaScript is involved, and no configuration is needed to enable it.
 
+Pass `truncate: false` to `tramway_cell` to opt a specific cell out of this behavior and let its content wrap/overflow
+normally:
+
+```erb
+<%= tramway_cell truncate: false do %>
+  <%= user.bio %>
+<% end %>
+```
+
 On narrow screens all columns always render, and the table scrolls horizontally within itself (the page never
 stretches past the viewport width) so every column stays reachable. See
 [docs/users/tramway_table.md](docs/users/tramway_table.md) for the full details of the mobile scroll behavior.

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

@@ -78,14 +78,16 @@ module Tramway
 
       private
 
+      # Selections round-trip as a comma-joined string; normalize back to an array here so the
+      # stimulus controller's JSON.parse(data-value) doesn't crash on a saved value.
+      def value = Array(super).flat_map { |item| item.is_a?(String) ? item.split(',') : item }.map(&:to_s)
+
       def tramway_select_size_class
         classes = size_class(:tramway_select_input)
         multiple ? classes.gsub(/\bh-/, 'min-h-') : classes
       end
 
-      def action
-        'click->tramway-select#toggleDropdown'
-      end
+      def action = 'click->tramway-select#toggleDropdown'
 
       def items
         collection

data/app/components/tramway/table/cell_component.rb

@@ -5,17 +5,17 @@ module Tramway
     # Component for rendering a cell in a table
     class CellComponent < Tramway::BaseComponent
       SIZE_CLASSES = {
-        small: 'div-table-cell truncate min-w-0 bg-transparent px-4 py-2 text-sm font-medium text-zinc-100',
-        medium: 'div-table-cell truncate min-w-0 bg-transparent px-6 py-4 text-base font-medium ' \
-                'text-zinc-100',
-        large: 'div-table-cell truncate min-w-0 bg-transparent px-6 py-6 text-lg font-medium ' \
-               'text-zinc-100'
+        small: 'div-table-cell min-w-0 bg-transparent px-4 py-2 text-sm font-medium text-zinc-100',
+        medium: 'div-table-cell min-w-0 bg-transparent px-6 py-4 text-base font-medium text-zinc-100',
+        large: 'div-table-cell min-w-0 bg-transparent px-6 py-6 text-lg font-medium text-zinc-100'
       }.freeze
 
       option :options, optional: true, default: -> { {} }
+      option :truncate, optional: true, default: -> { true }
 
       def cell_classes
-        SIZE_CLASSES.fetch(tramway_table_size) { SIZE_CLASSES[:medium] }
+        base_classes = SIZE_CLASSES.fetch(tramway_table_size) { SIZE_CLASSES[:medium] }
+        truncate ? "#{base_classes} truncate" : base_classes
       end
     end
   end

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

@@ -35,11 +35,13 @@
           = association[:record].title
 
     - @record.show_attributes.each do |attribute|
+      - attribute_name = @record.show_attribute_name(attribute)
+      - attribute_options = @record.show_attribute_options(attribute)
       = tramway_row do
         = tramway_cell do
-          = @model_class.human_attribute_name(attribute)
-        = tramway_cell do
-          = @record.public_send(attribute)
+          = @model_class.human_attribute_name(attribute_name)
+        = tramway_cell(**attribute_options) do
+          = @record.public_send(attribute_name)
 
   - @associations.select { _1[:association_type] == :has_many }.each do |association|
     .flex.flex-row.justify-between.mt-8.text-white

data/config/routes.rb

@@ -13,9 +13,10 @@ Tramway::Engine.routes.draw do
     end => segments
 
     resource_name = segments.pop
+    controller_path = (segments + [resource_name.pluralize]).join('/')
 
     define_resource = proc do
-      entity.pages.reduce([]) do |acc, page|
+      entity.built_in_pages.reduce([]) do |acc, page|
         case page.action
         when 'index'
           acc << :index
@@ -27,15 +28,24 @@ Tramway::Engine.routes.draw do
           acc + %i[edit update]
         when 'destroy'
           acc << :destroy
-        else
-          acc
         end
       end => actions
 
       resources resource_name.pluralize.to_sym,
                 only: actions.map(&:to_sym),
                 controller: '/tramway/entities',
-                defaults: { entity: }
+                defaults: { entity: } do
+        entity.custom_pages.each do |page|
+          path = ([page.action] + page.params.map { |param| ":#{param}" }).join('/')
+          to = "/#{controller_path}##{page.action}"
+
+          if page.member
+            member { match path, to:, via: page.via, defaults: { entity: } }
+          else
+            collection { match path, to:, via: page.via, defaults: { entity: } }
+          end
+        end
+      end
     end
 
     if segments.empty?

data/lib/tramway/base_decorator.rb

@@ -92,6 +92,20 @@ module Tramway
       []
     end
 
+    def show_attribute_name(attribute)
+      return attribute unless attribute.is_a?(Hash)
+
+      attribute.fetch(:attribute) do
+        raise ArgumentError, 'Each show_attributes Hash entry must include an :attribute key'
+      end
+    end
+
+    def show_attribute_options(attribute)
+      return {} unless attribute.is_a?(Hash)
+
+      attribute.fetch(:options, {})
+    end
+
     def show_associations
       []
     end

data/lib/tramway/configs/entities/page.rb

@@ -11,6 +11,9 @@ module Tramway
         attribute? :search, Types::Bool
         attribute? :includes, Types::Array.default([].freeze)
         attribute? :filters, Types::Array.default([].freeze)
+        attribute? :member, Types::Bool.default(false)
+        attribute? :via, (Types::Coercible::Symbol | Types::Array.of(Types::Coercible::Symbol)).default(:get)
+        attribute? :params, Types::Array.of(Types::Coercible::Symbol).default([].freeze)
       end
     end
   end

data/lib/tramway/configs/entity.rb

@@ -16,6 +16,10 @@ module Tramway
       ACTIONS = %i[index show new create edit update destroy].freeze
       RouteStruct = Struct.new(*ACTIONS)
 
+      # Page#action values handled by Tramway's built-in CRUD controller and routing.
+      # Any other page is a Custom Page, routed to a host app controller instead.
+      BUILT_IN_PAGE_ACTIONS = %w[index show create update destroy].freeze
+
       # HumanName Struct contains human names forms for the entity
       HumanNameStruct = Struct.new(:single, :plural)
 
@@ -39,6 +43,14 @@ module Tramway
         pages.find { |page| page.action == name.to_s }
       end
 
+      def built_in_pages
+        pages.select { |page| BUILT_IN_PAGE_ACTIONS.include?(page.action) }
+      end
+
+      def custom_pages
+        pages.reject { |page| BUILT_IN_PAGE_ACTIONS.include?(page.action) }
+      end
+
       def show_helper_method
         build_helper_method(name, route:, namespace:, plural: false)
       end

data/lib/tramway/helpers/views_helper.rb

@@ -50,8 +50,8 @@ module Tramway
                   &
       end
 
-      def tramway_cell(**options, &)
-        component 'tramway/table/cell', options:, &
+      def tramway_cell(truncate: true, **options, &)
+        component 'tramway/table/cell', truncate:, options:, &
       end
 
       def tramway_button(path: nil, text: nil, method: :get, form_options: {}, **options, &)

data/lib/tramway/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 4.1.0.1
+  version: 4.1.1
 platform: ruby
 authors:
 - kalashnikovisme