recourse 4.3.0 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00e1253a6c0a7e462efb88f9c46765d51cbc90b20073cf72fefc38ac468d31b2
-  data.tar.gz: 51271fdc26d6a06cf53089e747f70a842b51d71ffa1fe163e4dc08927e1ba005
+  metadata.gz: 063f5551f5b89bbb95660522a2a0177b9570f96961c5d5e28cfa83877ece91bf
+  data.tar.gz: 9f778ea100e50837483382e814936c1fc0697e462151445b144b7472e115132b
 SHA512:
-  metadata.gz: 3526cb175143ce2fae2919654b9f7afb7c1e44e6188462084e56c784f81aaf624cc128b760499991d79bf809fab97b14a50156c15f1e4969fff710309bfee4e2
-  data.tar.gz: a4aac6c9576b269c9df0f66fa4f0e60ca4e8da4461500be1a534caa2f25f33ff6c08d88e4e7ec431edc15d3ad4cb6c9af80725245f45d82557586640c79cab46
+  metadata.gz: 8538e6114d90e004f0b2f895bb5a0431c3569ddb6c05e4c93e3618aaa5056d7b44d24e974a197f546a387bfde58922ade7a25f5697444fce60637ff60864ce0c
+  data.tar.gz: 1b7776b83766984e18861aade3f0f79938358c24cba295c4bedca84c8f21b0aaefb1bad095da258bbcead01ea9a2ac6a1d5a2598d155935335189482a78283a0

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 4.4.0 - 2026-09-08
+
+* [Fix] Tapping the light/dark toggle or the log out on a phone leaves no tint behind
+* [Feature] On a phone a resource's breadcrumb is its icon alone, leaving the row to the search box and the button
+* [Feature] On a phone a card's tabs are their icons and figures: Show and Edit their
+  icons, a counted tab its icon and its number
+* [Feature] On a phone the whole `Franchises: 21` of a stacked counter cell is the link
+* [Fix] A touch screen shows no tooltips, a tap being what would open the link beneath one
+* [Fix] Safari no longer zooms in on the search box or a filter: the controls are 16px on a phone, where the body itself is 14
+* [Fix] A sidebar link tapped on a phone leaves no hover tint on it or on the link the next page puts under the finger
+
 ## 4.3.0 - 2026-09-08
 
 * [Feature] On a phone a stacked cell reads as one line, `Estimate hi: 600`

data/README.md

@@ -1,14 +1,6 @@
 # Recourse
 
-Admin screens for a Rails app, drawn from its models. One word in `config/routes.rb`
-serves a resource's seven actions — a paginated, searchable, sortable, filterable index
-table, a record's page, its form and its delete — with no controller, view or partial
-added to the app. What each screen shows is read off the model: its columns, its
-validators, its associations and its indexes.
-
-Everything a host may call is listed below with a link to its reference on
-[RubyDoc](https://rubydoc.info/gems/recourse). Every default can be overridden by
-defining the same thing in the app.
+Swap two characters in your `config/routes.rb` and get awesome admin screens for your Rails app.
 
 ## How to install
 
@@ -26,80 +18,44 @@ breaking change. Rails 8.1 and Ruby 3.2 are the minimum; the pages need Turbo, w
 `turbo-rails` brings, and nothing else — Bootstrap and its icons are vendored and served
 by the engine, so a host without an asset pipeline gets the same screens.
 
-## In `config/routes.rb`
+## Step 1. Edit your routes
 
-[`recourses`](https://rubydoc.info/gems/recourse/Recourse/Routes#recourses-instance_method)
-is `resources` with a controller and views supplied. It takes the same `only:` and
-`except:`, and a block nests children under the parent:
+This is as easy as replacing any call to `resources` to use [`recourses`](https://rubydoc.info/gems/recourse/Recourse/Routes#recourses-instance_method) instead:
 
-```ruby
-scope module: :admin do
-  recourses :providers do
-    recourses :markets, only: :index               # a counted tab on each provider
-    recourses :retrievals, only: :create           # a button on each provider
-  end
-  recourses :searches, only: %i[index show new create]
+```diff
+- resources :posts, only: %i[ index show ] do
++ recourses :posts, only: %i[ index show ] do
+-   resources :comments, except: :destroy
++   recourses :comments, except: :destroy
 end
 ```
 
-- Every resource with an `index` gets a sidebar entry, in routes order, with a keyboard
-  shortcut on its first letter. `only: []` declares a resource with no page of its own.
-- A nested `index` is a tab on the parent's card, counted where a `counter_cache` exists.
-- A nested `create` with no index is a button on the parent's page, named after the
-  route. The host answers it in a controller of its own, or the gem creates the record.
-- Nested controllers are namespaced after the parent (`Admin::Providers::MarketsController`),
-  and a nested index lists only the parent's rows.
-- Do you name a route `exit`? The sidebar ends with a log-out button submitting a
-  `DELETE` to it:
+Every recourse with `index` gets a sidebar entry (in routes order), a keyboard shortcut on its
+first letter, and a paginated, searchable, sortable, filterable index table:
 
-  ```ruby
-  resource :session, only: :destroy, as: :exit
-  ```
+[image]
 
-## In `app/controllers/recourses_controller.rb`
+Every recourse with `show` gets a detail page where attributes are displayed with the appropriate
+formatting, or masked if sensitive:
 
-Every controller the gem defines inherits
-[`RecoursesController`](https://rubydoc.info/gems/recourse/Recourse/BaseController),
-which the host defines to put behavior above every screen at once:
+[image]
 
-```ruby
-class RecoursesController < Recourse::BaseController
-  before_action :authenticate!
-end
-```
+Every recourse with `new` or `edit` gets a form with appropriate browser formatting and validation:
 
-A controller the app already defines is left alone.
+[image]
 
-## In `config/initializers/recourse.rb`
+Every recourse with `destroy` gets a button with a detailed confirmation message:
 
-- [`Recourse.color=`](https://rubydoc.info/gems/recourse/Recourse#color%3D-class_method):
-  which Bootstrap family is primary on every page. Readers switch light and dark themselves.
-- [`Recourse.bookmarks=`](https://rubydoc.info/gems/recourse/Recourse#bookmarks%3D-class_method):
-  a Proc answering the viewer's bookmark rows. Every table of a model with a `has_many`
-  at that class then opens with a square to keep a row by, kept rows first.
+[image]
 
-```ruby
-Recourse.color = :orange
-Recourse.bookmarks = -> { Keepsake.where agent: Current.agent }
-```
+Every nested recourse gets namespaced after the parent:
 
-## In a model
+[image]
 
-Every Active Record model answers these; a model overrides one in a
-[`Recoursive`](https://rubydoc.info/gems/recourse/Recourse/Recoursive) concern of its own.
 
-```ruby
-# app/models/market/recoursive.rb
-module Market::Recoursive extend ActiveSupport::Concern
-  class_methods do
-    def recourse_label = :slug                     # what a menu and a cell call one
-    def recourse_hidden = %i[callback_url payload] # off every screen
-    def recourse_displayed = :created_at           # back on the table
-    def recourse_order = { size: :desc }           # how the index sorts
-    def recourse_icon = :question                  # a Unicon concept
-  end
-end
-```
+## Step 2. Enhance your models
+
+To change the content displayed in the `index` table of a model, override any of these class methods:
 
 | Hook | Default | Decides |
 | --- | --- | --- |
@@ -109,44 +65,74 @@ end
 | [`recourse_order`](https://rubydoc.info/gems/recourse/Recourse/Recoursive#recourse_order-instance_method) | `:id` | the index's order, a Symbol or a Hash; rows with nothing in the column come last |
 | [`recourse_icon`](https://rubydoc.info/gems/recourse/Recourse/Recoursive#recourse_icon-instance_method) | the model's name | the icon on the sidebar, the crumbs and the tabs |
 
-What needs no hook, being read off the model:
-
-- The index eager-loads every `belongs_to` the table names, sorts by whatever an index
-  covers, searches through its indexed string columns and the labels behind its foreign
-  keys, marks what it matched, and offers a filter menu per enum, boolean and `belongs_to`.
-- Saving a row refreshes every open index of it.
-- A form field per column, carrying the rules the validators state: a length is a
-  `maxlength`, a format a `pattern`, a numericality a numeric keyboard.
-- An enum is a badge on a page and a menu on a form; a foreign key is a menu of the
-  records it points at, or a field to type the label into where there are too many.
-- Values formatted by kind: delimited integers, money, phone numbers, dates and times in
-  the reader's own time zone, a `<time>` saying how long ago, a URL as a link, a list as
-  a count that opens.
-- An encrypted column stays off the table, arrives masked on the record's page behind a
-  `Show`, and is edited in the clear.
-- The delete button names what goes with the record, counted one association down.
-
-## In `app/views`
-
-Do you want your own cells? Add `app/views/<resources>/_row.html.erb` and build it from
-[`column`](https://rubydoc.info/gems/recourse/Recourse/Helpers/Cells#column-instance_method),
+For instance, this would yield a more compact `index` than the default configuration:
+
+```ruby
+class Post < ActiveRecord::Base
+  def self.recourse_label = :title                    # Label a post with its title
+  def self.recourse_hidden = %i[ip_address]           # Hide the IP address from the views
+  def self.recourse_displayed = :created_at           # Display the created_at in the views
+  def self.recourse_order = { published_at: :desc }   # Sort posts by last published first
+  def self.recourse_icon = :question                  # Represent Posts with a question icon
+end
+````
+
+[image]
+
+## Step 3. Delete your views
+
+If you are happy with the generated HTML files, then be happy to skip this step!
+If you want even more configuration, then just add a `app/views/<resources>/_row.html.erb` partial.
+You can use [`column`](https://rubydoc.info/gems/recourse/Recourse/Helpers/Cells#column-instance_method),
 [`sort_header`](https://rubydoc.info/gems/recourse/Recourse/Helpers/Sorts#sort_header-instance_method)
-and [`search_highlight`](https://rubydoc.info/gems/recourse/Recourse/Helpers/Searches#search_highlight-instance_method):
+and [`search_highlight`](https://rubydoc.info/gems/recourse/Recourse/Helpers/Searches#search_highlight-instance_method)
+to define the columns you want:
 
 ```erb
 <%# app/views/admin/providers/_row.html.erb %>
 <%# locals: (provider:) -%>
+
 <%= column header: sort_header(:name) do %>
   <%= search_highlight provider.name, :name %>
 <% end %>
-<%= column header: 'Phone' do %><%= number_to_phone provider.phone %><% end %>
+
+<%= column header: 'Phone' do %>
+  <%= number_to_phone provider.phone %>
+<% end %>
+```
+
+[image]
+
+## Step 4. Secure your controllers
+
+Every controller the gem defines inherits
+[`RecoursesController`](https://rubydoc.info/gems/recourse/Recourse/BaseController),
+which the host defines to put behavior above every screen at once:
+
+```ruby
+class RecoursesController < Recourse::BaseController
+  before_action :authenticate!
+end
 ```
 
-Any template or partial of the gem's is replaced by defining it in the app, under the
-resource (`app/views/admin/providers/index.html.erb`) or for every resource at once
-(`app/views/recourses/_sidebar.html.erb`). Every string the gem shows is a key under
-`recourse` in `config/locales/recourse.en.yml`, so a host rewords `Add provider` in a
-locale file of its own.
+A controller the app already defines is left alone.
+
+
+## Step 5. Enjoy the extras
+
+Here are some bonus features the gem provides. Customize them by editing their values in
+your `config/initializers/recourse.rb` file:
+
+- [`Recourse.color=`](https://rubydoc.info/gems/recourse/Recourse#color%3D-class_method):
+  which Bootstrap family is primary on every page. Readers switch light and dark themselves.
+- [`Recourse.bookmarks=`](https://rubydoc.info/gems/recourse/Recourse#bookmarks%3D-class_method):
+  a Proc answering the viewer's bookmark rows. Every table of a model with a `has_many`
+  at that class then opens with a square to keep a row by, kept rows first.
+
+```ruby
+Recourse.color = :orange
+Recourse.bookmarks = -> { Keepsake.where agent: Current.agent }
+```
 
 ## Development
 

data/app/javascript/recourse/tooltip_controller.js

@@ -5,12 +5,17 @@ import { Tooltip } from '/recourse/bootstrap.bundle.min.js'
 // and a Stimulus lifecycle is what survives Turbo redrawing the table: connect
 // makes it, disconnect takes it down before the element goes, so a sorted or
 // searched table never strands one over an element that left.
+//
+// None where nothing can hover: on a touch screen the tap that would open a link
+// is also what shows a tooltip, and a word popping up over a tap reads as a hitch.
 export default class extends Controller {
   connect() {
+    if (matchMedia('(hover: none)').matches) return
+
     this.tooltip = Tooltip.getOrCreateInstance(this.element)
   }
 
   disconnect() {
-    this.tooltip.dispose()
+    this.tooltip?.dispose()
   }
 }

data/app/views/layouts/recourses.html.erb

@@ -107,13 +107,15 @@
          scrolled to it is a page Safari zooms out of and draws the navbar short on. */
       html, .recourse-shell { overflow-x: hidden; }
 
-      /* A finger does not hover. The tint a pointer leaves on the row under it would
-         stay on whatever row was last touched, so a touch screen gets none. */
+      /* A finger does not hover. The tint a pointer leaves on the row under it, or on
+         the link under it, would stay on whatever was last touched — or land on whatever
+         the redrawn page put under the finger — so a touch screen gets none. */
       @media (hover: none) {
         .table-hover > tbody > tr:hover > * {
           --bs-table-color-state: initial;
           --bs-table-bg-state: initial;
         }
+        .nav-link:hover:not(.active) { background-color: transparent; }
       }
 
       /* The navbar and the sidebar stack over the main column: a menu opened from a
@@ -148,6 +150,13 @@
           font-weight: var(--bs-font-weight-semibold);
         }
         .sm\:table-stacked > tbody > tr > td:first-child { font-weight: inherit; }
+        /* A counter's heading goes inside its link, so the whole `Franchises: 21` is
+           one thing to tap; the cell's own heading steps aside for it. */
+        .sm\:table-stacked > tbody > tr > td.recourse-counter::before { content: none; }
+        .sm\:table-stacked > tbody > tr > td.recourse-counter > [data-cell]::before {
+          content: attr(data-cell) ': ';
+          font-weight: var(--bs-font-weight-semibold);
+        }
         .sm\:table-stacked > tbody > tr > td:not(:first-child) + td::before { margin-block-start: 0; }
         .sm\:table-stacked > tbody > tr > td { overflow-wrap: anywhere; }
       }
@@ -260,9 +269,10 @@
         .recourse-search { max-width: none; }
         .recourse-search-box,
         .recourse-search .combobox-toggle { flex: 1 1 100%; }
-        /* Safari zooms in on a field whose text is under 16px, and the small controls
-           are 14px: on a phone they take the body's size, and focusing one moves nothing. */
-        .recourse-search { --bs-btn-input-sm-font-size: var(--bs-body-font-size); }
+        /* Safari zooms in on a field whose text is under 16px, an absolute figure: the
+           small controls are 14px, and so is the body on a phone, so the controls say
+           16px themselves and focusing one moves nothing. */
+        .recourse-search .form-control { font-size: 16px; }
       }
 
       /* Held Option marks the letter each sidebar link answers to. Marked rather than
@@ -382,8 +392,12 @@
       .recourse-foot { display: flex; }
       .recourse-foot > * { flex: 1 1 0; display: flex; justify-content: center; }
       .recourse-foot .nav-link { border-radius: var(--bs-radius-5); }
-      /* A hand cursor alone says little on an icon: a tint under it says it is a control. */
-      .recourse-foot .nav-link:hover { background-color: var(--bs-bg-1); color: var(--bs-fg-body); }
+      /* A hand cursor alone says little on an icon: a tint under it says it is a control.
+         Only where something can hover: a finger's tap leaves `:hover` set until the next
+         tap elsewhere, and a tint that stays reads as a button stuck down. */
+      @media (hover: hover) {
+        .recourse-foot .nav-link:hover { background-color: var(--bs-bg-1); color: var(--bs-fg-body); }
+      }
 
       /* The foot sits at the bottom of the sidebar and stretches across it while the
          sidebar is a column, and is simply the last item of the row while it is not
@@ -415,6 +429,20 @@
         }
       }
 
+      /* A phone's card has room for a row of tabs only as pictures and figures: Show
+         and Edit are their icons, a counted tab its icon and its number. A tab with
+         neither keeps its word, there being nothing else to stand for it. */
+      @media (width < 768px) {
+        .recourse-tab-word { display: none; }
+      }
+
+      /* And the trail at the top: a resource's crumb is its icon alone on a phone, so the
+         search box and the button beside it have the row. A record's crumb has no icon
+         and keeps its words. */
+      @media (width < 768px) {
+        .recourse-crumb-word { display: none; }
+      }
+
       /* While the sidebar is a row its foot has room for words, so each icon is followed
          by its own; as a column the words are read but not seen, the way Bootstrap's
          `.visually-hidden` does it. */

data/app/views/recourses/_breadcrumb.html.erb

@@ -9,7 +9,7 @@
         <%# A crumb naming a record — the parent a nested page is under — links
             without an icon: the crumb before it already carries the resource's. -%>
         <li class='breadcrumb-item'>
-          <%= link_to resource ? resource_label(resource, title) : title, path,
+          <%= link_to resource ? crumb_label(resource, title) : title, path,
                       class: class_names('breadcrumb-link', 'gap-2': resource) %>
         </li>
       <% elsif index < crumbs.size - 1 %>
@@ -21,7 +21,7 @@
         </li>
       <% elsif resource %>
         <li class='breadcrumb-item' aria-current='page'>
-          <span class='breadcrumb-link active gap-2'><%= resource_label resource, title %></span>
+          <span class='breadcrumb-link active gap-2'><%= crumb_label resource, title %></span>
         </li>
       <% else %>
         <%# A leaf names a page rather than a resource — `New market`, or a record by

data/lib/recourse/helpers/cards.rb

@@ -60,7 +60,9 @@ module Recourse
       end
 
       def tab_label(action)
-        safe_join [icon_tag(Actions::ICONS[action]), t("recourse.#{action}")], ' '
+        word = tag.span t("recourse.#{action}"), class: 'recourse-tab-word'
+
+        safe_join [icon_tag(Actions::ICONS[action]), word], ' '
       end
     end
   end

data/lib/recourse/helpers/counters.rb

@@ -21,6 +21,9 @@ module Recourse
         count = number_with_delimiter value
         counted = counter_counted count, value, association
         named = counter_naming count, association
+        # The heading again, for a stacked table to draw inside the link rather than
+        # before it: `Franchises: 21` is then one thing to tap.
+        named[:data] = { cell: Recourse.model_title(association.klass) }
         path = resource_controller_path
         nested = nested_path_of path, association
         return tag.span(counted, **named) unless nested && routed?(nested, 'index')

data/lib/recourse/helpers/navigation.rb

@@ -63,6 +63,17 @@ module Recourse
         safe_join [icon && tag.i(class: "bi bi-#{icon}"), name].compact, ' '
       end
 
+      # The same for a crumb, whose words a phone drops where the icon stands for them:
+      # the row at the top has a search box and a button to fit beside the trail.
+      def crumb_label(resource, title)
+        icon = Recourse.known_icon resource
+        return title unless icon
+
+        word = tag.span title, class: 'recourse-crumb-word'
+
+        safe_join [tag.i(class: "bi bi-#{icon}"), word], ' '
+      end
+
       # Only a page beneath the index names itself, and names what it is showing.
       def breadcrumb_leaf
         case controller.action_name

data/lib/recourse/helpers/tabs.rb

@@ -29,27 +29,30 @@ module Recourse
         [lead.presence&.upcase_first, title].compact.join ' '
       end
 
-      # The icon is the counted model's own, whatever leads the words beside it.
+      # The icon is the counted model's own, whatever leads the words beside it. The
+      # words are wrapped where a picture or a figure stands beside them, so a phone,
+      # which has room for neither, keeps the picture and the figure and drops the words.
       def association_tab_label(record, association, namespace)
         icon = Recourse.known_model_icon association.klass
+        count = tab_count record, association
+        words = tab_words association, namespace, count
+        words = tag.span words, class: 'recourse-tab-word' if icon || count
 
-        words = [icon && tag.i(class: "bi bi-#{icon}"), tab_name(record, association, namespace)]
-
-        safe_join words.compact, ' '
+        safe_join [icon && tag.i(class: "bi bi-#{icon}"), count, words].compact, ' '
       end
 
-      # `8 ZIPs` where the record keeps a count — read off the record itself, no
-      # query, like the column — and the bare `ZIPs` where it keeps none. A namespace
-      # the routes drew leads either of those, so two nestings of one model read
-      # apart: `10 visited places` beside `4 booked places`, `Visited places` beside
-      # `Booked places`. Whatever leads earns the downcase, and a title that leads
-      # keeps its capital — which is what puts these beside Show and Edit.
-      def tab_name(record, association, namespace)
-        count = tab_count record, association
-        lead = [count, namespace_words(namespace)].compact_blank.join ' '
-        title = Recourse.model_title association.klass, count: count, lower: lead.present?
+      # `ZIPs` where the record keeps no count, and `places` after the `8` where it
+      # does — read off the record itself, no query, like the column. A namespace the
+      # routes drew leads either, so two nestings of one model read apart: `10 visited
+      # places` beside `4 booked places`, `Visited places` beside `Booked places`.
+      # Whatever leads earns the downcase, and a title that leads keeps its capital —
+      # which is what puts these beside Show and Edit.
+      def tab_words(association, namespace, count)
+        lead = namespace_words namespace
+        lead = lead.upcase_first unless count
+        title = Recourse.model_title association.klass, count: count, lower: count || lead.present?
 
-        [lead.presence&.upcase_first, title].compact.join ' '
+        [lead.presence, title].compact.join ' '
       end
 
       def tab_count(record, association)

data/lib/recourse/version.rb

@@ -1,4 +1,4 @@
 module Recourse
   # Version of the gem, read by the gemspec and by hosts checking compatibility.
-  VERSION = '4.3.0'
+  VERSION = '4.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recourse
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 4.4.0
 platform: ruby
 authors:
 - claudiob