tramway 1.0.1.3 → 1.0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63be607c08e52f57b726d9f5c84f719febc22e35c0fb5d711f4c855268917203
-  data.tar.gz: 004a821c356a9f2e0e9503ddef030b3502510b4d9d9d72fe44ac1725443ee4b6
+  metadata.gz: 581bdfc4cccc870402d66738f53acc44cb84782ea875afa0abbe6a6d4adb7717
+  data.tar.gz: 236f05a1f96eed1f559b7d9aabe0aae2bb01e58588f54d124ccc879a4ca6fc0f
 SHA512:
-  metadata.gz: 0c53956b38f0110ea92c4d39e6c97e932534276a1d4d7cb11ca9087910ac4659861f3743c87416f480e57f5a3df3639434c7a5b7e921b80098e3efbf01b42c5a
-  data.tar.gz: b179d2f0c46930bdab407ac94a99f0eb33f361eb0833850ede97a6fcbdccba9090c68edbbbd453f6b318bc69f9c965b732f9f1d0a58f985e720bfae520646d14
+  metadata.gz: 5b1a3f26325a610c59c58781046848ed3457969f5e9f1a0715a35915474549933186b089bd1a0238d16535140f844b891167deaeb7247601a972616c3514eed0
+  data.tar.gz: f5f1fe2b2d30bc74be63fd1e0b22f36468bd10e60c7910005db112c713bd397f9fc4bfe7783731da73749cf3333fea449674c01c9899d680c3f88e234047facf

data/README.md

@@ -244,7 +244,7 @@ class UserDecorator < Tramway::BaseDecorator
 
   # you can provide representations with ViewComponent to avoid implementing views with Rails Helpers
   def posts_table
-    render TableComponent.new(object.posts)
+    component 'table', object.posts
   end
 end
 ```
@@ -299,6 +299,39 @@ end
 With this configuration in place, the index page will render the `Create`
 button component above the table of projects.
 
+#### Add header content to show pages
+
+To inject custom content above a record's details, define an
+object-level `show_header_content` method on its decorator. The method
+can return any rendered content and has full access to the decorated
+object's helpers and attributes.
+
+#### Use `view_context` in show and index pages
+
+Some helpers—such as `button_to` with non-`GET` methods—need access to the
+live request context to include CSRF tokens. Pass the Rails `view_context`
+into your decorated objects so their render calls execute inside the
+current request.
+
+```ruby
+def show
+  @project = tramway_decorate(Project.find(params[:id])).with(view_context:)
+end
+```
+
+For index pages, decorate each record with the current context before
+rendering headers or per-row components:
+
+```ruby
+def index
+  @projects = tramway_decorate(Project.all).map { |project| project.with(view_context:) }
+end
+```
+
+Passing the context this way ensures `show_header_content` and
+`index_header_content` blocks can safely call helpers that require the
+session-bound authenticity token.
+
 #### Decorate a single object
 
 You can use the same method to decorate a single object either
@@ -309,6 +342,11 @@ def show
 end
 ```
 
+All objects returned from `tramway_decorate` respond to
+`with(view_context:)`, so you can attach the current Rails `view_context`
+when you need decorator-rendered content to use helpers that rely on the
+active request (such as CSRF tokens).
+
 #### Decorate a collection of objects
 
 ```ruby
@@ -691,11 +729,14 @@ attributes, so you can pass things like `id`, `data` attributes, or additional c
 utility (e.g. a class that starts with `w-`), the component automatically appends `w-full` to keep the table responsive. This
 allows you to extend the default styling without losing the sensible defaults provided by the component.
 
+Use the optional `href:` argument on `tramway_row` to turn an entire row into a link. Linked rows gain pointer and hover styles
+(`cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-700`) to indicate interactivity.
+
 ```erb
 <%= tramway_table class: 'max-w-3xl border border-gray-200', data: { controller: 'table' } do %>
   <%= tramway_header', headers: ['Name', 'Email'] %>
 
-  <%= tramway_row do %>
+  <%= tramway_row href: user_path(user) do %>
     <%= tramway_cell do %>
       <%= user.name %>
     <% end %>
@@ -731,8 +772,14 @@ 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`. Pass `link: true` to render a button-styled link instead. All additional keyword
-  arguments are forwarded to the underlying component as HTML attributes.
+  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`.
+
+  ```erb
+  <%= tramway_button path: user_path(user), text: 'Open profile', link: true %>
+  ```
+
+  All additional keyword arguments are forwarded to the underlying component as HTML attributes.
 
   The `type` option maps semantic intent to Tailwind color families. The full set of supported values is:
 
@@ -964,7 +1011,6 @@ end
 * [Behave as ActiveRecord. Why do we want objects to be AR lookalikes?](https://kalashnikovisme.medium.com/behave-as-activerecord-why-do-we-want-objects-to-be-ar-lookalikes-d494d692e1d3)
 * [Decorating associations in Rails with Tramway](https://kalashnikovisme.medium.com/decorating-associations-in-rails-with-tramway-b46a28392f9e)
 * [Easy-to-use Tailwind-styled multi-select built with Stimulus](https://medium.com/@kalashnikovisme/easy-to-use-tailwind-styled-multi-select-built-with-stimulus-b3daa9e307aa)
-* 
 
 ## Contributing
 

data/app/controllers/tramway/entities_controller.rb

@@ -23,7 +23,10 @@ module Tramway
     end
 
     def show
-      @entity = tramway_decorate model_class.find(params[:id]), namespace: entity.namespace
+      @entity = tramway_decorate(
+        model_class.find(params[:id]),
+        namespace: entity.namespace
+      ).with(view_context:)
     end
 
     private

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

@@ -1,12 +1,18 @@
 = tramway_container do
-  %h1.text-4xl.font-bold.mb-4
-    = @entity.title
+  .flex.justify-between.items-center
+    %h1.text-4xl.font-bold.mb-4
+      = @entity.title
+
+  .flex.justify-end.mt-2
+    - if @entity.show_header_content.present?
+      = @entity.show_header_content
 
   - if @entity.show_attributes.empty?
     %p.text-center.mt-10
       You should fill object-level method `show_attributes` inside your
       = @entity.class.name
-  = tramway_table do
+
+  = tramway_table class: 'mt-4' do
     - @entity.show_attributes.each do |attribute|
       = tramway_row do
         = tramway_cell do

data/lib/tramway/base_decorator.rb

@@ -18,12 +18,18 @@ module Tramway
     include Tramway::Helpers::DecorateHelper
     include Tramway::Helpers::ComponentHelper
 
-    attr_reader :object
+    attr_reader :object, :view_context
 
     def initialize(object)
       @object = object
     end
 
+    def with(view_context:)
+      @view_context = view_context
+
+      self
+    end
+
     class << self
       include Tramway::Helpers::ComponentHelper
       include Tramway::Utils::Render
@@ -71,6 +77,10 @@ module Tramway
       []
     end
 
+    def show_header_content
+      nil
+    end
+
     # :reek:ManualDispatch { enabled: false } because there is the idea to manual dispatch
     def method_missing(method_name, *, &)
       url_helpers = Rails.application.routes.url_helpers

data/lib/tramway/utils/render.rb

@@ -6,6 +6,10 @@ module Tramway
     #
     module Render
       def render(*, &)
+        render_context = defined?(@view_context) && @view_context
+
+        return render_context.render(*, &) if render_context
+
         ActionController::Base.render(*, &)
       end
     end

data/lib/tramway/version.rb

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

metadata

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