tramway 0.6 → 0.6.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff761d41cd4748bf3d7e1451825da24764f69077b842e92f7be6baf0f14dff55
-  data.tar.gz: d9c3b25519ab3eb4dfe9c7d2e26d8dffb339a2743b6c5c494495bd4c5b71fc6c
+  metadata.gz: c3ac70ce33de0d7c3fbfd61650ff031137d8961713e9db94b93f0758ef2eba32
+  data.tar.gz: c8853c8169ac8821acafb3d47de20112400bd0e2d3e4c6390c3aec61917978a1
 SHA512:
-  metadata.gz: bb0c9c5121dc9a8213a0011c07265b2c42a486218966725df559c31f48b1f1e0cbbb50dc7fd10ddaac13f00a14d55ae57be42e121a1c1d44b1560822425f54af
-  data.tar.gz: 4488ab5046c8fee6150ee80459df3859f0a2d8b62948cfb91af93052dce2f0788aa067dde8261c9df0708ad31c853c522adc65c91c907cc71b4418c17bfc4244
+  metadata.gz: 485ff69148ae02c0967fa8d5bb75674b10a515a88c195ab86c7d6346b3710594bc3fb710e7d861d40f29287998c6f9a95ff2ddc63f4c0a14a8c69381179d12d6
+  data.tar.gz: ea7258f63f8adab1936e0f71e6a554857a8b650e3fb9182fe481a885a1823dee3ef5008280a849af141cffcfc10ed9324e9c01fd27106097df1af5938d6e57a4

data/README.md

@@ -133,13 +133,56 @@ Tramway Entity supports several options that are used in different features.
 ```ruby
 Tramway.configure do |config|
   config.entities = [
-    { name: :user, route: { namespace: :admin } },                                 # `admin_users_path` link in the Tramway Navbar
-    { name: :podcast, route: { route_method: :shows } },                           # `shows_path` link in the Tramway Navbar
-    { name: :episodes, route: { namespace: :podcasts, route_method: :episodes } }, # `podcasts_episodes_path` link in the Tramway Navbar
+    {
+      name: :user,
+      route: { namespace: :admin }
+    }, # `/admin/users` link in the Tramway Navbar
+    {
+      name: :episodes,
+      route: {
+        namespace: :podcasts,
+        route_method: :episodes
+      }
+    }, # `/podcasts/episodes` link in the Tramway Navbar
   ]
 end
 ```
 
+**scope**
+
+By default, Tramway lists all records for an entity on the index page. You can narrow the records displayed by providing a
+`scope`. When set, Tramway will call the named scope on the entity before rendering the index view.
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :campaign,
+      route: { namespace: :admin },
+      pages: [
+        {
+          action: :index,
+          scope: :active
+        }
+      ]
+    }
+  ]
+end
+```
+
+In this example, the `Campaign` entity will display only records returned by the `active` scope on its index page, while all
+other pages continue to show every record unless another scope is specified.
+
+**route_helper**
+
+To get routes Tramway generated just Tramway::Engine.
+
+```ruby
+Tramway::Engine.routes.url_helpers.users_path => '/admin/users'
+Tramway::Engine.routes.url_helpers.podcasts_episodes_path => '/podcasts/episodes'
+```
+
 ### Tramway Decorators
 
 Tramway provides convenient decorators for your objects. **NOTE:** This is not the decorator pattern in its usual representation.
@@ -455,15 +498,19 @@ tramway_navbar title: 'Purple Magic', background: { color: :red, intensity: 500
 end
 ```
 
-# Haml example
+# ERB example
+
+```erb
+<%= tramway_navbar title: 'Purple Magic', background: { color: :red, intensity: 500 } do |nav| %>
+  <% nav.left do %>
+    <%= nav.item 'Users', '/users' %>
+    <%= nav.item 'Podcasts', '/podcasts' %>
+  <% end %>
 
-```haml
-= tramway_navbar title: 'Purple Magic', background: { color: :red, intensity: 500 } do |nav|
-  - nav.left do
-    - nav.item 'Users', '/users'
-    - nav.item 'Podcasts', '/podcasts'
-  - nav.right do
-    - nav.item 'Sign out', '/users/sessions', method: :delete, confirm: 'Wanna quit?'
+  <% nav.right do %>
+    <%= nav.item 'Sign out', '/users/sessions', method: :delete, confirm: 'Wanna quit?' %>
+  <% end %>
+<% end %>
 ```
 
 will render [this](https://play.tailwindcss.com/UZPTCudFw5)
@@ -485,13 +532,16 @@ with_entities: Show Tramway Entities index page links to navbar. Default: true
 
 In case you want to hide entity links you can pass `with_entities: false`.
 
-```haml
-- if current_user.present?
-  = tramway_navbar title: 'WaiWai' do |nav|
-    - nav.left do
-      - nav.item 'Board', admin_board_path
-- else
-  = tramway_navbar title: 'WaiWai', with_entities: false
+```erb
+<% if current_user.present? %>
+  <%= tramway_navbar title: 'WaiWai' do |nav| %>
+    <% nav.left do %>
+      <%= nav.item 'Board', admin_board_path %>
+    <% end %>
+  <% end %>
+<% else %>
+  <%= tramway_navbar title: 'WaiWai', with_entities: false %>
+<% end %>
 ```
 
 #### nav.left and nav.right
@@ -529,31 +579,43 @@ end
 
 ### Tramway Table Component
 
-Tramway provides a responsive, tailwind-styled table with light and dark themes.
+Tramway provides a responsive, tailwind-styled table with light and dark themes. Use the `tramway_table`, `tramway_row`, and
+`tramway_cell` helpers to build tables with readable ERB templates while still leveraging the underlying ViewComponent
+implementations.
 
-```haml
-= component 'tailwinds/table' do
-  = component 'tailwinds/table/header', headers: ['Column 1', 'Column 2']
-  = component 'tailwinds/table/row' do
-    = component 'tailwinds/table/cell' do
+```erb
+<%= tramway_table do %>
+  <%= tramway_header headers: ['Column 1', 'Column 2'] %>
+
+  <%= tramway_row do %>
+    <%= tramway_cell do %>
       Something
-    = component 'tailwinds/table/cell' do
+    <% end %>
+    <%= tramway_cell do %>
       Another
+    <% end %>
+  <% end %>
+<% end %>
 ```
 
-`Tailwinds::TableComponent` accepts an optional `options` hash that is merged into the outer `.div-table` element. The hash is
-forwarded as HTML attributes, so you can pass things like `id`, `data` attributes, or additional classes. If you do not supply
-your own width 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.
+`tramway_table` accepts the same optional `options` hash as `Tailwinds::TableComponent`. The hash is forwarded as HTML
+attributes, so you can pass things like `id`, `data` attributes, or additional classes. If you do not supply your own width
+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.
+
+```erb
+<%= tramway_table class: 'max-w-3xl border border-gray-200', data: { controller: 'table' } do %>
+  <%= tramway_header', headers: ['Name', 'Email'] %>
 
-```haml
-= component 'tailwinds/table', options: { class: 'max-w-3xl border border-gray-200', data: { controller: 'table' } } do
-  = component 'tailwinds/table/header', headers: ['Name', 'Email']
-  = component 'tailwinds/table/row' do
-    = component 'tailwinds/table/cell' do
-      = user.name
-    = component 'tailwinds/table/cell' do
-      = user.email
+  <%= tramway_row do %>
+    <%= tramway_cell do %>
+      <%= user.name %>
+    <% end %>
+    <%= tramway_cell do %>
+      <%= user.email %>
+    <% end %>
+  <% end %>
+<% end %>
 ```
 
 When you render a header you can either pass the `headers:` array, as in the examples above, or render custom header content in
@@ -561,18 +623,48 @@ the block. `Tailwinds::Table::HeaderComponent` uses the length of the `headers`
 If you omit the array and provide custom content, pass the `columns:` argument so the component knows how many grid columns to
 generate.
 
-```haml
-= component 'tailwinds/table/header', columns: 4 do
-  = component 'tailwinds/table/cell' do
+```erb
+<%= component 'tailwinds/table/header', columns: 4 do %>
+  <%= tramway_cell do %>
     Custom header cell
-  = component 'tailwinds/table/cell' do
+  <% end %>
+  <%= tramway_cell do %>
     Another header cell
-  / ...
+  <% end %>
+  <!-- ... -->
+<% end %>
 ```
 
 With this approach you control the header layout while still benefiting from the default Tailwind grid classes that the header
 component applies.
 
+### Tramway Buttons and Containers
+
+Tramway ships with helpers for common UI patterns built on top of Tailwind components.
+
+* `tramway_button` renders a button-styled link and accepts `path`, optional `text`, HTTP `method`, and styling options such as
+  `color`, `type`, and `size`. All additional keyword arguments are forwarded to the underlying component as HTML attributes.
+
+  ```erb
+  <%= tramway_button path: user_path(user), text: 'View profile', color: :emerald, data: { turbo: false } %>
+  ```
+
+* `tramway_back_button` renders a standardized "Back" link.
+
+  ```erb
+  <%= tramway_back_button %>
+  ```
+
+* `tramway_container` wraps content in a responsive, narrow layout container. Pass an `id` if you need to target the container
+  with JavaScript or CSS.
+
+  ```erb
+  <%= tramway_container id: 'user-settings' do %>
+    <h2 class="text-xl font-semibold">Settings</h2>
+    <p class="mt-2 text-gray-600">Update your preferences below.</p>
+  <% 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).
@@ -581,15 +673,16 @@ Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are
 
 Tramway provides `tramway_form_for` helper that renders Tailwind-styled forms by default.
 
-```ruby
-= tramway_form_for @user do |f|
-  = f.text_field :text
-  = f.email_field :email
-  = f.password_field :password
-  = f.select :role, [:admin, :user]
-  = f.multiselect :permissions, [['Create User', 'create_user'], ['Update user', 'update_user']]
-  = f.file_field :file
-  = f.submit "Create User"
+```erb
+<%= tramway_form_for @user do |f| %>
+  <%= f.text_field :text %>
+  <%= f.email_field :email %>
+  <%= f.password_field :password %>
+  <%= f.select :role, [:admin, :user] %>
+  <%= f.multiselect :permissions, [['Create User', 'create_user'], ['Update user', 'update_user']] %>
+  <%= f.file_field :file %>
+  <%= f.submit 'Create User' %>
+<% end %>
 ```
 
 will render [this](https://play.tailwindcss.com/xho3LfjKkK)
@@ -607,25 +700,27 @@ Available form helpers:
 
 1. Sign In Form for `devise` authentication
 
-*app/views/devise/sessions/new.html.haml*
-```haml
-  = tramway_form_for(resource, as: resource_name, url: session_path(resource_name), class: 'bg-white shadow-md rounded px-8 pt-6 pb-8 mb-4') do |f|
-    = component 'forms/errors', record: resource
+*app/views/devise/sessions/new.html.erb*
+```erb
+<%= tramway_form_for(resource, as: resource_name, url: session_path(resource_name), class: 'bg-white shadow-md rounded px-8 pt-6 pb-8 mb-4') do |f| %>
+  <%= component 'forms/errors', record: resource %>
 
-    = f.text_field :email, placeholder: "Your email"
-    = f.password_field :password, placeholder: "Your password"
+  <%= f.text_field :email, placeholder: 'Your email' %>
+  <%= f.password_field :password, placeholder: 'Your password' %>
 
-    = f.submit "Sign In"
+  <%= f.submit 'Sign In' %>
+<% end %>
 ```
 
 2. Sign In Form for Rails authorization
 
-*app/views/sessions/new.html.haml*
-```haml
-= form_with url: login_path, scope: :session, local: true, builder: Tailwinds::Form::Builder do |form|
-    = form.email_field :email
-    = form.password_field :password
-    = form.submit "Log in"
+*app/views/sessions/new.html.erb*
+```erb
+<%= form_with url: login_path, scope: :session, local: true, builder: Tailwinds::Form::Builder do |form| %>
+  <%= form.email_field :email %>
+  <%= form.password_field :password %>
+  <%= form.submit 'Log in' %>
+<% end %>
 ```
 
 #### Stimulus-based inputs
@@ -636,10 +731,11 @@ Available form helpers:
 
 In case you want to use tailwind-styled multiselect this way
 
-```haml
-= tramway_form_for @user do |f|
-  = f.multiselect :permissions, [['Create User', 'create_user'], ['Update user', 'update_user']]
-  #- ...
+```erb
+<%= tramway_form_for @user do |f| %>
+  <%= f.multiselect :permissions, [['Create User', 'create_user'], ['Update user', 'update_user']] %>
+  <%# ... %>
+<% end %>
 ```
 
 you should add Tramway Multiselect Stimulus controller to your application.
@@ -663,9 +759,10 @@ application.register('multiselect', Multiselect) // register Multiselect control
 
 Use Stimulus `change` action with Tramway Multiselect
 
-```ruby
-= tramway_form_for @user do |f|
-  = f.multiselect :role, data: { action: 'change->user-form#updateForm' } # user-form is your Stimulus controller, updateForm is a method inside user-form Stimulus controller
+```erb
+<%= tramway_form_for @user do |f| %>
+  <%= f.multiselect :role, data: { action: 'change->user-form#updateForm' } %>
+<% end %>
 ```
 
 ### Tailwind-styled pagination for Kaminari
@@ -687,9 +784,9 @@ Tramway.configure do |config|
 end
 ```
 
-*app/views/users/index.html.haml*
-```haml
-= paginate @users # it will render tailwind-styled pagination buttons by default
+*app/views/users/index.html.erb*
+```erb
+<%= paginate @users %> <%# it will render tailwind-styled pagination buttons by default %>
 ```
 
 Pagination buttons looks like [this](https://play.tailwindcss.com/mqgDS5l9oY)
@@ -710,11 +807,41 @@ user_2 = tramway_form User.first
 user_2.object #=> returns pure user object
 ```
 
+## Configuration
+
+### Custom layout
+
+In case you wanna use a custom layout:
+
+1. Create a controller
+2. Set the layout there
+3. Set this controller as `application_controller` in Tramway initializer
+4. Reload your server
+
+**Example**
+
+*app/controllers/admin/application_controller.rb*
+```ruby
+class Admin::ApplicationController < ApplicationController
+  layout 'admin/application'
+end
+```
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.application_controller = 'Admin::ApplicationController'
+end
+```
+
 ## Articles
 * [Tramway on Rails](https://kalashnikovisme.medium.com/tramway-on-rails-32158c35ed68)
+* [Tramway is the way to deal with little things for Rails developers](https://medium.com/@kalashnikovisme/tramway-is-the-way-to-deal-with-little-things-for-rails-developers-4f502172a18c)
 * [Delegating ActiveRecord methods to decorators in Rails](https://kalashnikovisme.medium.com/delegating-activerecord-methods-to-decorators-in-rails-4e4ec1c6b3a6)
 * [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/views/tramway/entities/_list.html.haml

@@ -17,12 +17,12 @@
     %p.text-center.mt-10
       You should fill class-level method `self.list_attributes` inside your
       = decorator
+  - else
+    = component 'tailwinds/table' do
+      = component 'tailwinds/table/header', headers: list_attributes.map { |attribute| @model_class.human_attribute_name(attribute) }
+      - @entities.each do |item|
+        = render 'tramway/entities/entity', entity: item
 
-  = component 'tailwinds/table' do
-    = component 'tailwinds/table/header', headers: list_attributes.map { |attribute| @model_class.human_attribute_name(attribute) }
-    - @entities.each do |item|
-      = render 'tramway/entities/entity', entity: item
-
-    - if Tramway.config.pagination[:enabled]
-      .flex.mt-4
-        = paginate @entities, custom_path_method: "#{@model_class.model_name.plural}_path"
+      - if Tramway.config.pagination[:enabled]
+        .flex.mt-4
+          = paginate @entities, custom_path_method: "#{@model_class.model_name.plural}_path"

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

@@ -1 +1,2 @@
-= render 'tramway/entities/list'
+= tramway_container do
+  = render 'tramway/entities/list'

data/lib/tramway/helpers/views_helper.rb

@@ -17,6 +17,14 @@ module Tramway
         component 'tailwinds/table', options:, &
       end
 
+      def tramway_header(headers: nil, columns: nil, &)
+        component 'tailwinds/table/header',
+                  headers:,
+                  columns:,
+                  options:,
+                  &
+      end
+
       def tramway_row(**options, &)
         component 'tailwinds/table/row',
                   cells: options.delete(:cells),

data/lib/tramway/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: '0.6'
+  version: 0.6.0.2
 platform: ruby
 authors:
 - kalashnikovisme
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-10-25 00:00:00.000000000 Z
+date: 2025-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: anyway_config