tramway 4.0.1.3 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b083339a12222cbc2f03468e474dd7b909fda5f60a8d9d8d3f64f6bc55881de
-  data.tar.gz: c049ab9613c2aacb337b716d6ee24c097199f19e82a19d96fca7f4241bc01aac
+  metadata.gz: d1254075cd4e025f5a4f46d4951fc391bd8c90a4c1a486b3bbe471b0d79cfebb
+  data.tar.gz: d37cb6b0408b55f635f75b8cc8f0fb90d5d5efa454a1db5c4303fdf800e45726
 SHA512:
-  metadata.gz: 83a5d1fff5a20503ba9e80ebbe9dae8c980973e0943f9d33df8b2ede46e8c6aad4442fb34a47ab7884e483a5c475a217d0525c09b116e30971e3f77d75642272
-  data.tar.gz: 3c7d778b02ab2b42d96f9668a8c5c65a94204ab7e3e83873b685d3718b1267d81236fc5d5bcfc59a4fc4a2b2f0d1d53a9d23837b4198cd2be8851e7acde6db77
+  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
@@ -436,7 +470,9 @@ end
 
 You can inject custom content above an entity's index table by defining an
 `index_header_content` lambda on its decorator. The lambda receives the
-collection of decorated records and can render any component you need.
+collection of decorated records and can render any component you need. See
+[docs/users/tramway_entities.md](docs/users/tramway_entities.md) for where exactly this content is placed on
+the page.
 
 *config/initializers/tramway.rb*
 ```ruby
@@ -480,7 +516,7 @@ end
 ```
 
 With this configuration in place, the index page will render the `Create`
-button component above the table of projects.
+button and the header content above the table of projects.
 
 #### Add header content to show pages
 
@@ -947,6 +983,22 @@ end
 
 will render [this](https://play.tailwindcss.com/UZPTCudFw5)
 
+#### Icons on navbar items
+
+`nav.item` accepts an optional `icon:` option with a Font Awesome class string, rendered before the item's label:
+
+```ruby
+nav.left do
+  nav.item 'Users', '/users', icon: 'fa fa-users'
+  nav.item 'Podcasts', '/podcasts', icon: 'fa fa-podcast'
+end
+```
+
+Icons are optional — items without one just render as plain text links. When the vertical sidebar is collapsed on
+desktop, items rendered with an `icon:` stay visible and clickable as icon-only links (their text label is hidden
+but still available to screen readers via the item's `aria-label`); items without an icon have nothing to show once
+collapsed.
+
 #### tramway_navbar
 
 This helper provides several options. Here is YAML view of `tramway_navbar` options structure

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

@@ -457,13 +457,10 @@ class Navbar extends Controller {
 
     this.hiddenInteractionClasses.forEach((className) => {
       this.desktopHeader.classList.toggle(className, !expanded)
-      this.desktopMenu.classList.toggle(className, !expanded)
     })
 
     this.desktopHeader.toggleAttribute('inert', !expanded)
-    this.desktopMenu.toggleAttribute('inert', !expanded)
     this.desktopHeader.setAttribute('aria-hidden', expanded ? 'false' : 'true')
-    this.desktopMenu.setAttribute('aria-hidden', expanded ? 'false' : 'true')
 
     this.desktopToggleWrapper.classList.toggle('justify-end', expanded)
     this.desktopToggleWrapper.classList.toggle('justify-center', !expanded)
@@ -485,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/components/tramway/nav/item/button_component.html.haml

@@ -1,3 +1,6 @@
 %li.whitespace-nowrap
   = button_to @href, method: @method, class: "#{style} cursor-pointer", **@options do
-    = content
+    - if icon?
+      %i{ class: icon_classes, aria: { hidden: true } }
+    %span.tramway-navbar-item-label
+      = content

data/app/components/tramway/nav/item/button_component.rb

@@ -11,7 +11,8 @@ module Tramway
         def initialize(**options)
           @href = options[:href]
           @method = options[:method]
-          @options = options.except(:href, :method)
+          @icon = options[:icon]
+          @options = options.except(:href, :method, :icon)
         end
       end
     end

data/app/components/tramway/nav/item/link_component.html.haml

@@ -1,3 +1,6 @@
 %li.whitespace-nowrap
   = link_to @href, class: style, **@options do
-    = content
+    - if icon?
+      %i{ class: icon_classes, aria: { hidden: true } }
+    %span.tramway-navbar-item-label
+      = content

data/app/components/tramway/nav/item/link_component.rb

@@ -10,7 +10,10 @@ module Tramway
       class LinkComponent < Tramway::Nav::ItemComponent
         def initialize(**options)
           @href = options[:href]
-          @options = Rules::TurboHtmlAttributesRules.prepare_turbo_html_attributes(options:)
+          @icon = options[:icon]
+          @options = Rules::TurboHtmlAttributesRules.prepare_turbo_html_attributes(
+            options: options.except(:href, :icon)
+          )
         end
       end
     end

data/app/components/tramway/nav/item_component.rb

@@ -7,10 +7,18 @@ module Tramway
     class ItemComponent < TailwindComponent
       def style
         @style ||= [
-          'tramway-navbar-item inline-flex items-center rounded-md px-4 py-3 text-base font-medium text-zinc-100',
-          'transition-colors hover:bg-zinc-800 hover:text-zinc-50 sm:px-3 sm:py-2 sm:text-sm'
+          'tramway-navbar-item inline-flex items-center gap-2 rounded-md px-4 py-3 text-base font-medium',
+          'text-zinc-100 transition-colors hover:bg-zinc-800 hover:text-zinc-50 sm:px-3 sm:py-2 sm:text-sm'
         ].join(' ')
       end
+
+      def icon?
+        @icon.present?
+      end
+
+      def icon_classes
+        [@icon, 'tramway-navbar-item-icon w-5 shrink-0 text-center'].join(' ')
+      end
     end
   end
 end

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

@@ -114,21 +114,16 @@
       })();
 
     :css
-      .tramway-navbar-desktop-vertical .tramway-navbar-item {
-        width: 100%;
-      }
-
-      .tramway-navbar-desktop-vertical .tramway-navbar-item > a,
-      .tramway-navbar-desktop-vertical .tramway-navbar-item > form {
+      .tramway-navbar-desktop-vertical li.whitespace-nowrap {
         width: 100%;
       }
 
-      .tramway-navbar-desktop-vertical .tramway-navbar-item > form {
+      .tramway-navbar-desktop-vertical li.whitespace-nowrap > form {
         display: block;
+        width: 100%;
       }
 
-      .tramway-navbar-desktop-vertical .tramway-navbar-item > a,
-      .tramway-navbar-desktop-vertical .tramway-navbar-item > form > button {
+      .tramway-navbar-desktop-vertical .tramway-navbar-item {
         width: 100%;
         justify-content: flex-start;
       }
@@ -142,12 +137,26 @@
           padding-left: 6rem;
         }
 
-        html[data-tramway-navbar-expanded="false"] #desktop-navbar-header,
-        html[data-tramway-navbar-expanded="false"] #desktop-navbar-content {
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-header {
           opacity: 0;
           pointer-events: none;
         }
 
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-content {
+          opacity: 1;
+          pointer-events: auto;
+        }
+
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-content .tramway-navbar-item-label {
+          display: none;
+        }
+
+        html[data-tramway-navbar-expanded="false"] #desktop-navbar-content .tramway-navbar-item {
+          justify-content: center;
+          padding-left: 0;
+          padding-right: 0;
+        }
+
         html[data-tramway-navbar-expanded="false"] #desktop-navbar-toggle-wrapper {
           justify-content: center;
         }

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

@@ -16,16 +16,32 @@
           path: Tramway::Engine.routes.url_helpers.public_send(@entity.routes.new),
           type: :will
 
-      = decorator.constantize.index_header_content.call(@entities) if decorator.constantize.index_header_content.present?
-
-  .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:
+  - if decorator.constantize.index_header_content.present?
+    .mt-4
+      = decorator.constantize.index_header_content.call(@entities)
+
+  - 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

@@ -6,6 +6,9 @@ const buildUtilities = (prefix, start, end) =>
 module.exports = {
   safelist: [
     // === Navbar ===
+    'w-5',
+    'shrink-0',
+    'text-center',
     'ml-4',
     'text-white',
     'md:flex',
@@ -58,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',
@@ -416,6 +420,7 @@ module.exports = {
     'mb-4',
     'mb-2',
     'mt-8',
+    'mt-4',
     'mt-2',
 
     // === Pagination styles ===
@@ -464,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/navbar.rb

@@ -35,13 +35,13 @@ module Tramway
       reset_filling
     end
 
-    def item(text_or_url, url = nil, **, &)
+    def item(text_or_url, url = nil, icon: nil, **, &)
       raise 'You cannot provide an argument and a code block at the same time' if provided_url_and_block?(url, &)
 
       if url.present?
-        render_ignoring_block(text_or_url, url, **)
+        render_ignoring_block(text_or_url, url, icon:, **)
       else
-        render_using_block(text_or_url, **, &)
+        render_using_block(text_or_url, icon:, **, &)
       end => rendered_item
 
       @items[@filling] << rendered_item
@@ -73,8 +73,9 @@ module Tramway
       @filling = nil
     end
 
-    def render_ignoring_block(text_or_url, url, method: nil, **options)
-      options.merge!(href: url)
+    def render_ignoring_block(text_or_url, url, method: nil, icon: nil, **options)
+      options.merge!(href: url, icon:)
+      apply_icon_accessibility_attributes(options, label: text_or_url, icon:)
 
       if method.present? && method.to_sym != :get
         context.render(Tramway::Nav::Item::ButtonComponent.new(method:, **options)) { text_or_url }
@@ -83,8 +84,8 @@ module Tramway
       end
     end
 
-    def render_using_block(text_or_url, method: nil, **options, &)
-      options.merge!(href: text_or_url)
+    def render_using_block(text_or_url, method: nil, icon: nil, **options, &)
+      options.merge!(href: text_or_url, icon:)
 
       if method.present? && method.to_sym != :get
         context.render(Tramway::Nav::Item::ButtonComponent.new(method:, **options), &)
@@ -92,5 +93,12 @@ module Tramway
         context.render(Tramway::Nav::Item::LinkComponent.new(method:, **options), &)
       end
     end
+
+    def apply_icon_accessibility_attributes(options, label:, icon:)
+      return if icon.blank?
+
+      options[:title] = label if options[:title].blank?
+      options[:'aria-label'] = label if options[:'aria-label'].blank?
+    end
   end
 end

data/lib/tramway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tramway
-  VERSION = '4.0.1.3'
+  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.3
+  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