tramway 4.0 → 4.0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 148d9d2e8ff5ee611788d8242c4900f20b80d85b853fd3840b16d0d5e46499a2
-  data.tar.gz: 62f5e3d6272692fc77356597957d79a69fa027b1cb13882e9178fea55b466681
+  metadata.gz: c7d9ecf679835522a59184b0ffdbc6edf5cfa66aa5f1126429828497b3115e12
+  data.tar.gz: efa55f1a6971b64000f41f387b6a85b7d41756b4c5240c35ce3f283f6f878f4c
 SHA512:
-  metadata.gz: d70a7f1a483a8633c3c479d5fc9fd089f185f23b6c4e554113fdb8461f8ca09586bebf2765e7a35b0e52985fe63e020db0185b9ce9e82f5721b3944715c3d1e7
-  data.tar.gz: e117993ffe8ad1c3448975ee7944aab1b1138ab0132ca3cec0c2f56eee999f27f1e90f4d86a4b20401e02e9281def6d9fa35e9b351fb510e32e58647a0db9e75
+  metadata.gz: 67ac2fd8508f6a2d172638f3ac7f808721e5d4c1aa24f13e247238196c1fc90cdc5ddc1e0f7d5aa41cf13c1e47d0fa0d118d807f073afa1372ebc83b9b0f873b
+  data.tar.gz: 2bd0d71dbade50601a643f2c6c3567b00440d2104db60f53fc0f1a3937c73c77fde8509a8cddea9b68c908dfe92214c036e6b14bee02919c9a1a0b2f4ef5b1be

data/README.md

@@ -219,8 +219,47 @@ Tramway.configure do |config|
 end
 ```
 
-When search is enabled, Tramway uses `Model.search(query)` if defined. If not, it falls back to `Model.tramway_search(query)` and logs a warning.
-The fallback is generic and not tailored to your data structure, so it is not intended for long-term use and may be slow or not scalable.
+When search is enabled, a text input and a search icon button appear at the top of the index page. Tramway uses
+`Model.search(query)` if you define it (e.g. a `pg_search_scope` or any custom scope named `search`). If not, it falls back
+to `Model.tramway_search(query)`, which searches across all string/text columns of the model using the [`pg_search`](https://github.com/Casecommons/pg_search)
+gem, and logs a warning. The fallback is generic and not tailored to your data structure, so it is not intended for
+long-term use and may be slow or not scalable.
+
+`pg_search` requires PostgreSQL's full-text search functions. If your application's database is not PostgreSQL, calling
+the fallback raises `Tramway::Errors::UnsupportedDatabaseAdapterError` with an explanation and a suggestion to define your
+own `Model.search(query)` scope instead.
+
+`bin/rails g tramway:install` adds `gem "pg_search"` to your Gemfile automatically (like Tramway's other dependencies), so
+run it (and `bundle install`) if you see the fallback raise `Tramway::Errors::MissingGemError`. That error also fires if
+`pg_search` can't otherwise be loaded, and explains how to fix it or define your own `Model.search(query)` scope.
+
+**includes**
+
+If a decorator's `index_attributes` reads an association (e.g. `object.comments.map(&:text)`), each row triggers its own
+query unless the association is eager-loaded. Set `includes` on the `:index` page entry to preload it, using the same
+shape Rails' `.includes` accepts (a symbol, array, or nested hash):
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :campaign,
+      namespace: :admin,
+      pages: [
+        {
+          action: :index,
+          includes: [:user, :comments]
+        }
+      ]
+    }
+  ]
+end
+```
+
+In this example, Tramway calls `Campaign.includes(:user, :comments)` before applying `scope`/`search`, so accessing
+`campaign.user` or `campaign.comments` in the decorator's `index_attributes` does not issue an extra query per row.
+Omitting `includes` produces identical behavior to before this option existed.
 
 **show page**
 
@@ -946,6 +985,23 @@ renders the classic top navbar, and desktop `:vertical` renders the collapsible
 When `tramway_navbar` renders before `tramway_main_container`, the main container helper keeps the vertical
 sidebar offset in sync automatically and removes it for horizontal pages.
 
+The collapsed/expanded state of the vertical sidebar persists across page navigations. The Stimulus controller
+saves the state to the browser's `localStorage` (key `tramway-navbar-expanded`) whenever the toggle button is
+used, and reads it back on every page load, so collapsing the sidebar on one page keeps it collapsed everywhere
+else until it's expanded again. This is per-browser state: it isn't synced across devices or persisted server-side,
+and if `localStorage` is unavailable (e.g. private browsing with storage blocked), the sidebar simply falls back
+to always starting expanded.
+
+Since the server always renders the sidebar expanded (it has no way to know the browser's stored preference) and
+the Stimulus controller only applies the collapsed classes once it connects, `tramway_navbar` also renders a small
+blocking inline `<script>` alongside its markup. It reads `localStorage` synchronously, before the browser paints,
+and — if the sidebar was left collapsed — sets a `data-tramway-navbar-expanded="false"` attribute on `<html>`. A
+matching `@media (min-width: 768px)` CSS block (rendered alongside the navbar) keys off that attribute to apply the
+collapsed width, main-container padding, and faded header/menu immediately, before any JavaScript module has had a
+chance to load and run. This is what prevents the sidebar from flashing expanded and then snapping to collapsed on
+page load. The Stimulus controller keeps that `<html>` attribute in sync afterwards (on load and on every toggle),
+so this pre-paint styling and the controller's own classes never fight each other.
+
 **NOTE:** `tramway_navbar` method called without arguments and block of code will render only [Tramway CRUD](https://github.com/Purple-Magic/tramway#tramway-crud) links on the left.
 
 In case you want to hide entity links you can pass `with_entities: false`.

data/app/assets/javascripts/tramway/tramway.js

@@ -467,6 +467,7 @@ class Navbar extends Controller {
     this.desktopMainExpandedPaddingClass = 'md:pl-72'
     this.desktopMainCollapsedPaddingClass = 'md:pl-24'
     this.hiddenInteractionClasses = ['opacity-0', 'pointer-events-none']
+    this.expandedStorageKey = 'tramway-navbar-expanded'
 
     this.desktopNavbar = this.element
     this.desktopHeader = document.getElementById('desktop-navbar-header')
@@ -490,8 +491,22 @@ class Navbar extends Controller {
     document.addEventListener('turbo:before-cache', this.handleBeforeCache)
     window.addEventListener('resize', this.handleResize)
 
-    if (this.isDesktopViewport()) {
-      this.syncDesktopExpandedState()
+    this.syncDesktopExpandedState()
+  }
+
+  readStoredExpanded() {
+    try {
+      return window.localStorage.getItem(this.expandedStorageKey)
+    } catch {
+      return null
+    }
+  }
+
+  writeStoredExpanded(expanded) {
+    try {
+      window.localStorage.setItem(this.expandedStorageKey, expanded ? 'true' : 'false')
+    } catch {
+      /* localStorage unavailable (e.g. private mode) — state simply won't persist */
     }
   }
 
@@ -579,18 +594,31 @@ class Navbar extends Controller {
   }
 
   toggleDesktopExpanded() {
-    this.setDesktopExpanded(this.desktopNavbar.dataset.expanded === 'false')
+    this.setDesktopExpanded(this.desktopNavbar.dataset.expanded === 'false', { persist: true })
   }
 
   syncDesktopExpandedState() {
-    this.setDesktopExpanded(this.desktopNavbar.dataset.expanded !== 'false')
+    const storedExpanded = this.readStoredExpanded()
+    const expanded = storedExpanded === null ? this.desktopNavbar.dataset.expanded !== 'false' : storedExpanded !== 'false'
+
+    this.setDesktopExpanded(expanded)
   }
 
-  setDesktopExpanded(expanded) {
+  setDesktopExpanded(expanded, { persist = false } = {}) {
     if (!this.isVertical() || !this.desktopNavbar || !this.desktopHeader || !this.desktopMenu || !this.desktopMainContainer || !this.desktopToggleButton || !this.desktopToggleWrapper) {
       return
     }
 
+    if (persist) {
+      this.writeStoredExpanded(expanded)
+    }
+
+    if (expanded) {
+      document.documentElement.removeAttribute('data-tramway-navbar-expanded')
+    } else {
+      document.documentElement.setAttribute('data-tramway-navbar-expanded', 'false')
+    }
+
     this.desktopNavbar.classList.toggle(this.desktopNavbarExpandedWidthClass, expanded)
     this.desktopNavbar.classList.toggle(this.desktopNavbarCollapsedWidthClass, !expanded)
     this.desktopNavbar.dataset.expanded = expanded ? 'true' : 'false'

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

@@ -102,6 +102,17 @@
         Close
 
   - if vertical?
+    :javascript
+      (function () {
+        try {
+          if (window.localStorage.getItem('tramway-navbar-expanded') === 'false') {
+            document.documentElement.setAttribute('data-tramway-navbar-expanded', 'false');
+          } else {
+            document.documentElement.removeAttribute('data-tramway-navbar-expanded');
+          }
+        } catch (e) {}
+      })();
+
     :css
       .tramway-navbar-desktop-vertical .tramway-navbar-item {
         width: 100%;
@@ -121,3 +132,27 @@
         width: 100%;
         justify-content: flex-start;
       }
+
+      @media (min-width: 768px) {
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar {
+          width: 6rem;
+        }
+
+        html[data-tramway-navbar-expanded="false"] #tramway-main-container {
+          padding-left: 6rem;
+        }
+
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-header,
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-content {
+          opacity: 0;
+          pointer-events: none;
+        }
+
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-toggle-wrapper {
+          justify-content: center;
+        }
+
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-toggle-icon {
+          transform: rotate(180deg);
+        }
+      }

data/app/controllers/tramway/entities_controller.rb

@@ -19,6 +19,7 @@ module Tramway
         model_class.order(id: :desc)
       end => entities
 
+      entities = preload(entities)
       entities = search(entities)
       entities = entities.page(params[:page])
       @entities = entities
@@ -90,6 +91,12 @@ module Tramway
       entity.page(:index).scope
     end
 
+    def preload(entities)
+      includes = entity.page(:index).includes
+
+      includes.present? ? entities.includes(includes) : entities
+    end
+
     def set_associations
       @associations = @record.send(:__show_associations, params[:page])
     end

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

@@ -22,7 +22,8 @@
     - if @entity.page(:index).search
       = form_with url: public_send(custom_path_method), method: :get, local: true, builder: Tramway::Form::Builder, horizontal: true do |f|
         = f.text_field :query, label: false, value: params[:query], placeholder: t('tramway.actions.search')
-        = f.submit t('tramway.actions.search')
+        = f.submit nil, 'aria-label' => t('tramway.actions.search') do
+          %i.fa.fa-search{ 'aria-hidden' => 'true' }
 
     = paginate @entities, custom_path_method:
 

data/lib/generators/tramway/install/install_generator.rb

@@ -51,7 +51,8 @@ module Tramway
           { name: 'kaminari', declaration: 'gem "kaminari"' },
           { name: 'view_component', declaration: 'gem "view_component"' },
           { name: 'dry-initializer', declaration: "gem 'dry-initializer'" },
-          { name: 'dry-monads', declaration: "gem 'dry-monads'" }
+          { name: 'dry-monads', declaration: "gem 'dry-monads'" },
+          { name: 'pg_search', declaration: "gem 'pg_search'" }
         ]
       end
 

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

@@ -9,6 +9,7 @@ module Tramway
         attribute :action, Types::Coercible::String
         attribute? :scope, Types::Coercible::String
         attribute? :search, Types::Bool
+        attribute? :includes, Types::Array.default([].freeze)
       end
     end
   end

data/lib/tramway/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Tramway
+  # Namespace for Tramway-specific error classes
+  module Errors
+    # Raised when a Tramway feature depends on infrastructure (e.g. a specific
+    # database adapter) that the current application does not provide, so the
+    # developer gets an actionable error instead of a raw, confusing failure
+    # deep inside the underlying gem.
+    class UnsupportedDatabaseAdapterError < StandardError
+      def initialize(feature:, model_class:, adapter:, required_adapter: 'PostgreSQL')
+        super(<<~MESSAGE)
+          Tramway #{feature} requires #{required_adapter}, but #{model_class} is connected \
+          through the "#{adapter}" adapter.
+
+          This feature relies on the `pg_search` gem, which needs PostgreSQL's full-text \
+          search functions (to_tsvector/to_tsquery) and does not work on other adapters.
+
+          To fix this:
+            - switch #{model_class}'s database connection to PostgreSQL, or
+            - define a custom `#{model_class}.search(query)` scope that works with your \
+          adapter; Tramway will use it instead of the built-in pg_search fallback.
+        MESSAGE
+      end
+    end
+
+    # Raised when a Tramway feature depends on a gem that could not be loaded or used, so the
+    # developer (or an AI agent) gets a precise, actionable fix instead of a raw NoMethodError
+    # or LoadError deep inside the missing gem's call chain.
+    class MissingGemError < StandardError
+      def initialize(feature:, model_class:, gem_name:, original_error:)
+        super(<<~MESSAGE)
+          Tramway #{feature} for #{model_class} could not use the `#{gem_name}` gem \
+          (#{original_error.class}: #{original_error.message}).
+
+          To fix this:
+            - add `gem "#{gem_name}"` to your Gemfile, run `bundle install`, and restart your \
+          server (or re-run `bin/rails g tramway:install`, which adds it automatically), or
+            - define a custom `#{model_class}.search(query)` scope that does not depend on \
+          `#{gem_name}`; Tramway will use it instead of the built-in fallback.
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/tramway/pg_searchable.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'tramway/errors'
+
+module Tramway
+  # Wires up a default, generic search across all string/text columns using the
+  # `pg_search` gem, so entities#index search works out of the box for any model
+  # that does not define its own `.search` scope.
+  #
+  # This is only supported on PostgreSQL, since pg_search depends on PostgreSQL's
+  # full-text search functions. On any other adapter it raises a clear,
+  # actionable error instead of failing with a confusing SQL error deep inside
+  # pg_search.
+  module PgSearchable
+    module_function
+
+    def call(model_class, query)
+      ensure_postgres!(model_class)
+      ensure_pg_search_scope!(model_class)
+
+      model_class.tramway_pg_search(query)
+    end
+
+    def ensure_postgres!(model_class)
+      adapter = model_class.connection.adapter_name
+
+      return if adapter.casecmp('postgresql').zero?
+
+      raise Tramway::Errors::UnsupportedDatabaseAdapterError.new(
+        feature: 'the default entities#index search',
+        model_class:,
+        adapter:
+      )
+    end
+
+    def ensure_pg_search_scope!(model_class)
+      return if model_class.respond_to?(:tramway_pg_search)
+
+      define_pg_search_scope!(model_class)
+    rescue LoadError, NameError => e
+      raise missing_pg_search_gem_error(model_class, e)
+    end
+
+    def define_pg_search_scope!(model_class)
+      require 'pg_search'
+
+      model_class.include(PgSearch::Model)
+      model_class.pg_search_scope :tramway_pg_search,
+                                  against: model_class.searchable_column_names,
+                                  using: { tsearch: { prefix: true } }
+    end
+
+    def missing_pg_search_gem_error(model_class, original_error)
+      Tramway::Errors::MissingGemError.new(
+        feature: 'the default entities#index search',
+        model_class:,
+        gem_name: 'pg_search',
+        original_error:
+      )
+    end
+  end
+end

data/lib/tramway/searchable.rb

@@ -1,43 +1,25 @@
 # frozen_string_literal: true
 
+require 'tramway/pg_searchable'
+
 module Tramway
-  # Searchable module provides a class method `tramway_search` for ActiveRecord models to perform full-text search
-  # across all string and text columns using PostgreSQL's full-text search capabilities.
+  # Searchable module provides a class method `tramway_search` for ActiveRecord models to
+  # perform a generic search across all string and text columns, using the `pg_search` gem.
+  # It is the fallback Tramway::EntitiesController uses when a model does not define its
+  # own `.search` scope. See Tramway::PgSearchable for the PostgreSQL requirement.
   module Searchable
     extend ActiveSupport::Concern
 
     class_methods do
       def tramway_search(query)
-        tokens = search_tokens(query)
-        columns_to_search = searchable_column_names
-
-        return all if tokens.empty? || columns_to_search.empty?
-
-        where(
-          Arel.sql("to_tsvector('simple', #{tsvector_expression(columns_to_search)}) @@ to_tsquery('simple', ?)"),
-          tsquery_expression(tokens)
-        )
-      end
-
-      private
+        return all if query.blank?
 
-      def search_tokens(query)
-        query.to_s.scan(/[[:alnum:]]+/)
+        Tramway::PgSearchable.call(self, query)
       end
 
       def searchable_column_names
         columns.select { |column| column.type.in?(%i[string text]) }.map(&:name)
       end
-
-      def tsvector_expression(column_names)
-        column_names.map do |column_name|
-          "coalesce(#{connection.quote_column_name(column_name)}, '')"
-        end.join(" || ' ' || ")
-      end
-
-      def tsquery_expression(tokens)
-        tokens.map { |token| "#{token}:*" }.join(' & ')
-      end
     end
   end
 end

data/lib/tramway/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: '4.0'
+  version: 4.0.1.1
 platform: ruby
 authors:
 - kalashnikovisme
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg_search
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -309,6 +323,7 @@ files:
 - lib/tramway/duck_typing.rb
 - lib/tramway/duck_typing/active_record_compatibility.rb
 - lib/tramway/engine.rb
+- lib/tramway/errors.rb
 - lib/tramway/forms/class_helper.rb
 - lib/tramway/forms/fields.rb
 - lib/tramway/forms/normalizations.rb
@@ -322,6 +337,7 @@ files:
 - lib/tramway/helpers/table_helper.rb
 - lib/tramway/helpers/views_helper.rb
 - lib/tramway/navbar.rb
+- lib/tramway/pg_searchable.rb
 - lib/tramway/searchable.rb
 - lib/tramway/utils/field.rb
 - lib/tramway/utils/render.rb