tramway 4.0.1.3 → 4.0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b083339a12222cbc2f03468e474dd7b909fda5f60a8d9d8d3f64f6bc55881de
-  data.tar.gz: c049ab9613c2aacb337b716d6ee24c097199f19e82a19d96fca7f4241bc01aac
+  metadata.gz: 9d8281006bde6f8928a12ffc94cef931ff7b3c4e8bdc774ad4e690b7a529a0e8
+  data.tar.gz: 644f44899bc6919f0ea8f08fbb9708fa4fec87b54a398668714209f905a54d87
 SHA512:
-  metadata.gz: 83a5d1fff5a20503ba9e80ebbe9dae8c980973e0943f9d33df8b2ede46e8c6aad4442fb34a47ab7884e483a5c475a217d0525c09b116e30971e3f77d75642272
-  data.tar.gz: 3c7d778b02ab2b42d96f9668a8c5c65a94204ab7e3e83873b685d3718b1267d81236fc5d5bcfc59a4fc4a2b2f0d1d53a9d23837b4198cd2be8851e7acde6db77
+  metadata.gz: 506f5ed78da723c554832b299ef0f0415f63b328fa9e4ff72e6f52b4972d699398a26b5101f869563eb91ce786cd244fd977cbab9f634d7bfdbbab7cef96dcff
+  data.tar.gz: f68ae4382f2301f34ac572d725d41b0503f9ff5b6d2396e97a3afc95053d2c66e1f5818f2d9a0a6808f968e71ab386e3c789cbf9138f2616d0ee72f2af3c9104

data/README.md

@@ -436,7 +436,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 +482,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 +949,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)

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/views/tramway/entities/_list.html.haml

@@ -16,7 +16,9 @@
           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?
+  - if decorator.constantize.index_header_content.present?
+    .mt-4
+      = decorator.constantize.index_header_content.call(@entities)
 
   .flex.flex-row.justify-end.mt-2.gap-4
     - if @entity.page(:index).search

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',
@@ -416,6 +419,7 @@ module.exports = {
     'mb-4',
     'mb-2',
     'mt-8',
+    'mt-4',
     'mt-2',
 
     // === Pagination styles ===

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.1.4'
 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.1.4
 platform: ruby
 authors:
 - kalashnikovisme