tramway 4.0.1.4 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d8281006bde6f8928a12ffc94cef931ff7b3c4e8bdc774ad4e690b7a529a0e8
-  data.tar.gz: 644f44899bc6919f0ea8f08fbb9708fa4fec87b54a398668714209f905a54d87
+  metadata.gz: d1254075cd4e025f5a4f46d4951fc391bd8c90a4c1a486b3bbe471b0d79cfebb
+  data.tar.gz: d37cb6b0408b55f635f75b8cc8f0fb90d5d5efa454a1db5c4303fdf800e45726
 SHA512:
-  metadata.gz: 506f5ed78da723c554832b299ef0f0415f63b328fa9e4ff72e6f52b4972d699398a26b5101f869563eb91ce786cd244fd977cbab9f634d7bfdbbab7cef96dcff
-  data.tar.gz: f68ae4382f2301f34ac572d725d41b0503f9ff5b6d2396e97a3afc95053d2c66e1f5818f2d9a0a6808f968e71ab386e3c789cbf9138f2616d0ee72f2af3c9104
+  metadata.gz: 29d854a96abfcadda07911e326932a2347c509a0465dc5e6d4c19533dd7b5299f05aa011d3d928490dc6a17969143dc0490f81206618ecd13bd37040bc5306a3
+  data.tar.gz: d176134cef60ad20d9c2617067d0e4c498a966fef4119ef182dd2d13b32ae7919cce4ab2a3d18d076b0a20a7a6a08bda88b667190c072bfd41a2021ffa84c1af

data/README.md

@@ -261,6 +261,40 @@ In this example, Tramway calls `Campaign.includes(:user, :comments)` before appl
 `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.
 
+**filters**
+
+Filters are disabled by default on index pages. Enable them by listing the scope names you want selectable under
+`filters` on the `:index` page entry:
+
+*config/initializers/tramway.rb*
+```ruby
+Tramway.configure do |config|
+  config.entities = [
+    {
+      name: :campaign,
+      namespace: :admin,
+      pages: [
+        {
+          action: :index,
+          filters: [:active, :archived]
+        }
+      ]
+    }
+  ]
+end
+```
+
+When filters are configured, Tramway adds a "Filters" toggle to the same row as the search box and pagination, above
+the index listing. Clicking it reveals a list of small buttons, one per configured filter, each showing how many
+records currently match it (e.g. "ACTIVE · 34"). Clicking a button navigates to the index page with that filter
+applied, keeping any existing search query. The currently applied filter is highlighted, and the toggle remembers
+whether the list was last left open or closed.
+
+Visiting the index page with `?filter=active` calls `Campaign.active` (the scope must already exist on the model) in
+addition to any configured `scope`. If `filter` does not match one of the configured filters, Tramway raises
+`Tramway::Errors::InvalidFilterError` explaining which filters are available. Omitting `filters` (the default) makes
+Tramway ignore `params[:filter]` entirely.
+
 **show page**
 
 To render a show page for an entity, declare a `:show` action inside the `pages` array in

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

@@ -482,4 +482,86 @@ class Navbar extends Controller {
   }
 }
 
-export { TramwaySelect, UiCheckbox, Tooltip, Navbar }
+class Collapsible extends Controller {
+  static targets = ["panel", "icon", "toggle"]
+
+  connect() {
+    this.expanded = true
+
+    const stored = this.readStored()
+    const expanded = stored === null ? true : stored === 'true'
+
+    this.setExpanded(expanded, { animate: false })
+  }
+
+  toggle(event) {
+    event.preventDefault()
+
+    this.setExpanded(!this.expanded, { persist: true })
+  }
+
+  setExpanded(expanded, { persist = false, animate = true } = {}) {
+    this.expanded = expanded
+
+    if (animate) {
+      this.animateTo(expanded)
+    } else {
+      this.panelTarget.style.height = expanded ? 'auto' : '0px'
+      this.panelTarget.style.opacity = expanded ? '1' : '0'
+    }
+
+    const expandedCarrier = this.hasToggleTarget ? this.toggleTarget : this.element
+    expandedCarrier.setAttribute('aria-expanded', expanded ? 'true' : 'false')
+
+    if (this.hasIconTarget) {
+      this.iconTarget.classList.toggle('rotate-180', !expanded)
+    }
+
+    if (persist) {
+      this.writeStored(expanded)
+    }
+  }
+
+  // Animates between the panel's current rendered height and its target height, rather than
+  // to/from `auto` directly (which cannot be transitioned). `height` is one of the few
+  // properties animate.md tolerates outside transform/opacity, since an accordion has no
+  // transform equivalent.
+  animateTo(expanded) {
+    const panel = this.panelTarget
+    const targetHeight = expanded ? panel.scrollHeight : 0
+
+    panel.style.height = `${panel.getBoundingClientRect().height}px`
+    panel.getBoundingClientRect() // force reflow so the browser registers the start value
+
+    requestAnimationFrame(() => {
+      panel.style.height = `${targetHeight}px`
+      panel.style.opacity = expanded ? '1' : '0'
+    })
+
+    panel.addEventListener('transitionend', () => {
+      if (this.expanded) panel.style.height = 'auto'
+    }, { once: true })
+  }
+
+  readStored() {
+    try {
+      return window.localStorage.getItem(this.storageKey)
+    } catch {
+      return null
+    }
+  }
+
+  writeStored(expanded) {
+    try {
+      window.localStorage.setItem(this.storageKey, expanded ? 'true' : 'false')
+    } catch {
+      /* localStorage unavailable (e.g. private mode) — state simply won't persist */
+    }
+  }
+
+  get storageKey() {
+    return `tramway-collapsible-${this.element.dataset.key || 'default'}`
+  }
+}
+
+export { TramwaySelect, UiCheckbox, Tooltip, Navbar, Collapsible }

data/app/controllers/tramway/entities_controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'tramway/warnings'
+require 'tramway/errors'
 
 module Tramway
   # Main controller for entities pages
@@ -13,18 +14,15 @@ module Tramway
     include Rails.application.routes.url_helpers
 
     def index
-      if index_scope.present?
-        model_class.public_send(index_scope)
-      else
-        model_class.order(id: :desc)
-      end => entities
-
+      entities = base_entities
+      entities = apply_filter(entities)
       entities = preload(entities)
       entities = search(entities)
       entities = entities.page(params[:page])
       @entities = entities
 
       @namespace = entity.namespace
+      @filter_counts = filter_counts if filters.present?
     end
 
     def show
@@ -91,6 +89,37 @@ module Tramway
       entity.page(:index).scope
     end
 
+    def base_entities
+      if index_scope.present?
+        model_class.public_send(index_scope)
+      else
+        model_class.order(id: :desc)
+      end
+    end
+
+    def filters
+      entity.page(:index).filters
+    end
+
+    def apply_filter(entities)
+      return entities if params[:filter].blank? || filters.blank?
+
+      filter = params[:filter].to_s
+
+      unless filters.map(&:to_s).include?(filter)
+        raise Tramway::Errors::InvalidFilterError.new(filter:, available_filters: filters, model_class:)
+      end
+
+      entities.public_send(filter)
+    end
+
+    def filter_counts
+      # Count by :id explicitly: a bare `.count` reuses any custom `select` values from the
+      # index page's `scope` (e.g. a raw-SQL aliased subquery column), which breaks the
+      # generated SQL. Counting a real column side-steps that entirely.
+      filters.index_with { |filter| base_entities.public_send(filter).count(:id) }
+    end
+
     def preload(entities)
       includes = entity.page(:index).includes
 

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

@@ -0,0 +1,15 @@
+- current_filter = params[:filter]
+
+.overflow-hidden.duration-200.ease-out-strong.motion-reduce:duration-0{ class: 'transition-[height,opacity]', data: { 'tramway--collapsible-target': 'panel' } }
+  .flex.flex-wrap.gap-2.mt-2
+    - @filter_counts.each do |filter_name, count|
+      - filter_params = request.query_parameters.except('page').merge(filter: filter_name)
+      - button_type = filter_name.to_s == current_filter ? :primary : :inverse
+      = tramway_button text: "#{filter_name.to_s.upcase} · #{count}",
+        path: public_send(custom_path_method, filter_params), type: button_type, size: :small
+
+    - if current_filter.present?
+      - clear_params = request.query_parameters.except('page', 'filter')
+      = tramway_button tag: :a, path: public_send(custom_path_method, clear_params), type: :inverse,
+        size: :small, tooltip: { text: t('tramway.actions.clear_filter'), event: :hover } do
+        %i.fa.fa-times{ 'aria-hidden' => 'true' }

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

@@ -20,14 +20,28 @@
     .mt-4
       = decorator.constantize.index_header_content.call(@entities)
 
-  .flex.flex-row.justify-end.mt-2.gap-4
-    - 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 nil, 'aria-label' => t('tramway.actions.search') do
-          %i.fa.fa-search{ 'aria-hidden' => 'true' }
-
-    = paginate @entities, custom_path_method:
+  - filters_key = "#{@entity.namespace}-#{@entity.name}-index-filters" if @filter_counts.present?
+
+  %div{ data: (@filter_counts.present? ? { controller: 'tramway--collapsible', key: filters_key } : {}) }
+    .flex.flex-row.items-center.mt-2.gap-4{ class: (@filter_counts.present? ? 'justify-between' : 'justify-end') }
+      - if @filter_counts.present?
+        = tramway_button tag: :button, type: :inverse,
+          data: { action: 'tramway--collapsible#toggle', 'tramway--collapsible-target': 'toggle' } do
+          %i.fa.fa-filter.mr-1{ 'aria-hidden' => 'true' }
+          = t('tramway.actions.filters')
+          %i.fa.fa-chevron-down.ml-1.transition-transform.duration-200.ease-out-strong.motion-reduce:duration-0{ 'aria-hidden' => 'true', data: { 'tramway--collapsible-target': 'icon' } }
+
+      .flex.flex-row.items-center.gap-4
+        - 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 nil, 'aria-label' => t('tramway.actions.search') do
+              %i.fa.fa-search{ 'aria-hidden' => 'true' }
+
+        = paginate @entities, custom_path_method:
+
+    - if @filter_counts.present?
+      = render 'tramway/entities/filters', custom_path_method:
 
   - if index_attributes.empty?
     %p.text-center.mt-10

data/config/locales/en.yml

@@ -14,6 +14,8 @@ en:
       save: "Save"
       cancel: "Cancel"
       search: "Search"
+      filters: "Filters"
+      clear_filter: "Clear filter"
     notices:
       created: "The record is created"
       updated: "The record is updated"

data/config/tailwind.config.js

@@ -61,6 +61,7 @@ module.exports = {
     'ease-in-out',
     'md:transition-[width]',
     'transition-[padding-left]',
+    'transition-[height,opacity]',
     'ease-in-out-strong',
     'md:ease-in-out-strong',
     'ease-out-strong',
@@ -468,6 +469,8 @@ module.exports = {
     'whitespace-nowrap',
     'h-fit',
     'gap-1',
+    'mr-1',
+    'ml-1',
     'h-10',
     'px-2.5',
     'py-0.5',

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

@@ -115,7 +115,7 @@ module Tramway
 
       def stimulus_controller_imports
         [
-          'import { Navbar, TramwaySelect, UiCheckbox, Tooltip } from "@tramway/tramway"'
+          'import { Navbar, TramwaySelect, UiCheckbox, Tooltip, Collapsible } from "@tramway/tramway"'
         ]
       end
 
@@ -124,7 +124,8 @@ module Tramway
           "application.register('tramway-navbar', Navbar)",
           "application.register('tramway-select', TramwaySelect)",
           "application.register('ui--checkbox', UiCheckbox)",
-          "application.register('tramway-tooltip', Tooltip)"
+          "application.register('tramway-tooltip', Tooltip)",
+          "application.register('tramway--collapsible', Collapsible)"
         ]
       end
 
@@ -299,7 +300,8 @@ module Tramway
           "application.register('tramway-select'",
           "application.register('table-row-preview'",
           "application.register('ui--checkbox'",
-          "application.register('tramway-tooltip'"
+          "application.register('tramway-tooltip'",
+          "application.register('tramway--collapsible'"
         ]
       end
 

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

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

data/lib/tramway/errors.rb

@@ -41,5 +41,25 @@ module Tramway
         MESSAGE
       end
     end
+
+    # Raised when `params[:filter]` on an entities#index page does not match any of the
+    # filters declared for that page in the Tramway config, so the developer (or the user
+    # following a crafted link) gets a clear explanation instead of a raw NoMethodError from
+    # calling an arbitrary, possibly non-existent scope.
+    class InvalidFilterError < StandardError
+      def initialize(filter:, available_filters:, model_class:)
+        super(<<~MESSAGE)
+          Tramway received an unknown filter "#{filter}" for #{model_class} on the \
+          entities#index page.
+
+          Available filters: #{available_filters.join(', ')}.
+
+          To fix this:
+            - pass one of the available filters above in `params[:filter]`, or
+            - add `:#{filter}` to this entity's `filters:` list for the `:index` page in your \
+          Tramway config if it should be selectable.
+        MESSAGE
+      end
+    end
   end
 end

data/lib/tramway/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 4.0.1.4
+  version: 4.0.2
 platform: ruby
 authors:
 - kalashnikovisme
@@ -289,6 +289,7 @@ files:
 - app/views/kaminari/_prev_page.html.haml
 - app/views/tramway/chats/_message.html.haml
 - app/views/tramway/chats/_messages.html.haml
+- app/views/tramway/entities/_filters.html.haml
 - app/views/tramway/entities/_form.html.haml
 - app/views/tramway/entities/_list.html.haml
 - app/views/tramway/entities/edit.html.haml