recourse 7.7.1 → 7.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7701d1c2564537b038401ab7224c1adebed9e766a9c3c316090e7b931a8eea2e
-  data.tar.gz: 72c419b28ec5ec1e6ed9704b753b36663daee1dfbc91a9d84b96dce934548f23
+  metadata.gz: db928d015c6b427908eac64f93319534dafb40dd089916ab38782241ba6264dd
+  data.tar.gz: 68abc102048e76b5440c010cba4f039e2c5388496c258bc8cc73c23adadfb940
 SHA512:
-  metadata.gz: aadd0f9de7e9f02148030d1eae72c31eef0e5a4b74108ccae7243366d749e1d251521ff91aa78db616313725cb9bd90cd1f83e7ddc18c4544b6ee62bbed90482
-  data.tar.gz: a00d680bd48d7c9fa32aaf17d4feee6327853b8c267f3497d8c2372d986fb646010278cb1ab1c7648512713383822c2c78a80f588760bee3a49035b037e46ef7
+  metadata.gz: ce01d852728a901751c26b717fa7008143a36b96038cf9e672f121a38c3929d83bd24b4e45575bbe13439362a850a11a513288e4bed372678e2d4385071c833d
+  data.tar.gz: 798c8ccef55728658d9ec54b7a5076b80c6f83888e8c6728ba53958445ee0b4c12c599744c88134650c3ec4989fb690dd4480ecf280b2f9751cefd14c20c0e92

data/CHANGELOG.md

@@ -7,6 +7,29 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 7.8.1 - 2026-09-20
+
+* [FIX] A retrieval route is named after its resource
+
+  A collection route takes its name from the scope around it, so four retrievable
+  resources under one parent all answered to `provider_retrieval` and only the first
+  kept the name. Each is `provider_visits_retrieval` now, and the other three have a
+  path helper again.
+
+## 7.8.0 - 2026-09-20
+
+* [FEATURE] A resource may say its rows can be fetched again
+
+  `recourses :visits, only: :index, retrievable: true` draws `POST /providers/5/visits/retrieval`
+  and puts the button that asks for it on the table that lists them. Where the rows came
+  from is the host's to know, so the controller is the host's to write and the gem makes
+  one only where there is none.
+
+  A page says when there is nothing to fetch from: `recourse_retrievable?` answers true
+  unless a host narrows it, which is how an index of a CRM's work offers nothing to a
+  provider who has connected none. And a resource asking for it without an index is
+  refused while the routes draw, the button having nowhere to stand.
+
 ## 7.7.1 - 2026-09-20
 
 * [FIX] The filters the gem offers itself are ones Ransack will answer

data/app/controllers/concerns/recourse/retrieving.rb

@@ -0,0 +1,16 @@
+module Recourse
+  # Whether a page offers to fetch its rows again from wherever they came.
+  module Retrieving
+    extend ActiveSupport::Concern
+
+    included { helper_method :recourse_retrievable? }
+
+  private
+
+    # Whether this page offers to fetch its rows again, where the routes said it may.
+    # True unless the host says otherwise, since a provider with no CRM connected has
+    # nothing to fetch from and only the host knows it: `def recourse_retrievable? =
+    # @provider.integrated?`. Private, so narrowing it adds no action.
+    def recourse_retrievable? = true
+  end
+end

data/app/controllers/recourse/base_controller.rb

@@ -5,7 +5,7 @@ module Recourse
   class BaseController < ApplicationController
     include Pagy::Method, Positioned, AttachmentResolution, AttachmentWriting,
             Landing, Paging, ListResolution, ParameterResolution, ParentNaming,
-            ParentResolution, ReferenceResolution, ResourceResolution,
+            ParentResolution, ReferenceResolution, ResourceResolution, Retrieving,
             Weeks, Zoning
 
     helper Helpers

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

@@ -12,6 +12,8 @@
   <% end %>
 <% end %>
 
+<% content_for :actions, retrieval_button %>
+
 <% content_for :search do %>
   <%= search_form %>
 <% end %>

data/config/locales/recourse.en.yml

@@ -71,6 +71,11 @@ en:
       has no %{model} model.
     nested: You nested `recourses %{names}` inside `resources :%{parent}`, which does
       not namespace what it holds. Nest it under `recourses :%{parent}` instead.
+    # What the button that fetches a table's rows again is named to a screen reader.
+    retrieve: Retrieve %{models} again
+    unretrieved: "You asked for `recourses %{names}, retrievable: true`, which draws no
+      index to fetch them onto. The button that asks for them stands on the table that
+      lists them, so there is nowhere to put it."
     unindexed: "You asked for `recourses %{names}, positionable: true`, which draws no
       index to put in order. A row is dragged from the table that lists it, so there is
       nowhere for a drop to be reported from."

data/lib/recourse/helpers/retrievals.rb

@@ -0,0 +1,31 @@
+module Recourse
+  module Helpers
+    # The button that fetches a table's rows again from wherever they came.
+    module Retrievals
+    private
+
+      # Offered where the routes said the rows may be fetched again and the page says
+      # there is anything to fetch them from — an index of a CRM's work is no use to a
+      # provider who has connected none, and only the host knows that.
+      def retrieval_button
+        return unless Recourse.retrievable?(controller.controller_path) && recourse_retrievable?
+
+        button_to retrieval_path, class: 'btn btn-sm btn-solid theme-primary ms-3',
+                                  form_class: 'd-inline-block',
+                                  aria: { label: retrieval_label } do
+          icon_tag :sync
+        end
+      end
+
+      # The one route a retrievable resource earns, under the resource itself.
+      def retrieval_path
+        url_for controller: "/#{controller.controller_path}/retrievals", action: :create
+      end
+
+      def retrieval_label
+        t 'recourse.retrieve', models: Recourse.model_title(resource_model,
+                                                            lower: true)
+      end
+    end
+  end
+end

data/lib/recourse/helpers.rb

@@ -35,6 +35,7 @@ require_relative 'helpers/pictures'
 require_relative 'helpers/previews'
 require_relative 'helpers/reaches'
 require_relative 'helpers/references'
+require_relative 'helpers/retrievals'
 require_relative 'helpers/resources'
 require_relative 'helpers/refreshes'
 require_relative 'helpers/routing'
@@ -61,7 +62,8 @@ module Recourse
             Deletions, Densities, Details, Events, Examples, Fields, FilterMenus, Filters,
             Flashes, Formats, Inputs, Kinds, Limits, Links, Maps, Names, Navigation,
             Parents, Pictures, Previews, Reaches, References, Refreshes, Routing,
-            Resources, Rows, Searches, Shapes, Shortcuts, Sidebars, Sorts, Spans, Tabs,
+            Resources, Retrievals, Rows, Searches, Shapes, Shortcuts, Sidebars, Sorts, Spans,
+            Tabs,
             Themes, Times, Values, Warnings, Weeks, Zones
 
     # The grid a record's own two pages lay an attribute out in: two columns on a large

data/lib/recourse/registry.rb

@@ -19,6 +19,14 @@ module Recourse
       @parents[child.to_s] = parent.to_s
     end
 
+    # Records that a resource's rows may be fetched again from wherever they came.
+    def retrieve(path)
+      @retrievable << path.to_s unless @retrievable.include? path.to_s
+    end
+
+    # Whether that resource's index offers to fetch them.
+    def retrievable?(path) = @retrievable.include?(path.to_s)
+
     # The resources nested under one parent path, in the order they were drawn.
     def nested_under(parent)
       @nested.fetch parent.to_s, []

data/lib/recourse/routes/nested.rb

@@ -8,12 +8,13 @@ module Recourse
       # What a resource holds: the square that keeps one of its rows, the place a row
       # holds in a table somebody positioned, and whatever the host's own block declared —
       # each under the resource's own module, which is what every nested page relies on.
-      def draw_within(keepable, positionable, block)
+      def draw_within(keepable, positionable, retrievable, block)
         addressable = addressable_rows?
 
         scope module: parent_resource.name do
           draw_bookmark if keepable && addressable
           draw_position if positionable && addressable
+          draw_retrieval if retrievable
           instance_exec(&block) if block
         end
       end
@@ -37,6 +38,21 @@ module Recourse
         resource :position, only: :update
       end
 
+      # The fetch a table's own button asks for, at `/providers/5/visits/retrieval`.
+      # Where the rows came from is the host's to know, so the controller is the
+      # host's to write and the gem only makes one where there is none — the same
+      # bargain a bare action strikes. Recorded nowhere, for the reason the bookmark
+      # gives: a tab and a bare-action button both look under a resource, and this is
+      # neither.
+      def draw_retrieval
+        Controllers.define_missing [current_module, 'retrievals'].compact.join('/')
+        # Named after the resource as well as the parent: a collection route takes its
+        # name from the scope around it, so four retrievals under one parent would all
+        # answer to `provider_retrieval` and only the first would keep the name.
+        named = "#{parent_resource.name}_retrieval"
+        collection { resource :retrieval, only: :create, as: named }
+      end
+
       # The row a table's bookmark square writes: one record kept by whoever is looking,
       # at `/places/5/bookmark`. Deliberately not recorded through `Recourse.nest` — it
       # would sit directly under the resource, where a tab and a bare-action button both

data/lib/recourse/routes/refusals.rb

@@ -0,0 +1,34 @@
+module Recourse
+  module Routes
+    # What the routes file is not allowed to say, said back to whoever wrote it while
+    # the routes draw rather than answered with a broken page later.
+    module Refusals
+    private
+
+      # The two that mean nothing without a page listing rows: a row is dragged from the
+      # table that lists it, and a button fetching them again stands on that same table.
+      # The retrieval is recorded here too, where a helper reads it back.
+      def refuse_unindexed(names, positioned, fetched, options)
+        refuse_unlisted names, 'unindexed', options if positioned
+        refuse_unlisted names, 'unretrieved', options if fetched
+        names.each { |name| Recourse.retrieve declared_path(name) } if fetched
+
+        options
+      end
+
+      def refuse_unlisted(names, word, options)
+        return if indexed? options
+
+        raise Error, I18n.t("recourse.#{word}", names: names.map(&:inspect).join(', '))
+      end
+
+      def refuse_unscoped_nesting(names)
+        parent = parent_resource
+        return if parent.nil? || current_module.to_s.split('/').include?(parent.name)
+
+        raise Error, I18n.t('recourse.nested', names: names.map(&:inspect).join(', '),
+                                               parent: parent.name)
+      end
+    end
+  end
+end

data/lib/recourse/routes.rb

@@ -1,9 +1,10 @@
 require_relative 'routes/nested'
+require_relative 'routes/refusals'
 
 module Recourse
   # Extends the config/routes.rb DSL, so `recourses` works anywhere `resources` does.
   module Routes
-    include Nested
+    include Nested, Refusals
 
     # Draws what `resources` draws, after supplying any controller the host lacks. A
     # block nests what it declares under each resource — ZIPs at
@@ -26,13 +27,12 @@ module Recourse
       names.each { |name| declare_resource name }
       # The host's word, and taken out before Rails sees the rest: `resources` would
       # refuse a keyword it does not know.
-      positionable = options.delete(:positionable) { false }
-      options = default_nested_actions options
-      refuse_unindexed_positioning names, positionable, options
+      positioned = options.delete(:positionable) { false }
+      fetched = options.delete(:retrievable) { false }
+      options = refuse_unindexed names, positioned, fetched, default_nested_actions(options)
+      return resources(*names, **options) unless [keepable, positioned, fetched, block].any?
 
-      return resources(*names, **options) unless block || keepable || positionable
-
-      resources(*names, **options) { draw_within keepable, positionable, block }
+      resources(*names, **options) { draw_within keepable, positioned, fetched, block }
     end
 
     # What `resource` draws, recorded the same way: one record reached without an id,
@@ -57,18 +57,16 @@ module Recourse
     # The module is the namespace being drawn in, so a resource is declared and its
     # controller defined under the path Rails will route to.
     def declare_resource(name)
-      path = [current_module, name].compact.join '/'
-      record_declaration path
-      Controllers.define_missing path
+      record_declaration declared_path(name)
+      Controllers.define_missing declared_path(name)
     end
 
+    # Where a resource of this name is routed, which is the name under everything the
+    # routes file remembers about it.
+    def declared_path(name) = [current_module, name].compact.join('/')
+
     # A table is put in order from its index and from nowhere else, so asking for the
     # route without drawing one is a host saying two things that cannot both hold.
-    def refuse_unindexed_positioning(names, positionable, options)
-      return unless positionable && !indexed?(options)
-
-      raise Error, I18n.t('recourse.unindexed', names: names.map(&:inspect).join(', '))
-    end
 
     # Whether `index` survived the `only:` or `except:` the host wrote. Neither of
     # them is the common case, and both name the action plainly.
@@ -84,13 +82,5 @@ module Recourse
 
       options.merge only: %i[index new create]
     end
-
-    def refuse_unscoped_nesting(names)
-      parent = parent_resource
-      return if parent.nil? || current_module.to_s.split('/').include?(parent.name)
-
-      raise Error, I18n.t('recourse.nested', names: names.map(&:inspect).join(', '),
-                                             parent: parent.name)
-    end
   end
 end

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 = '7.7.1'
+  VERSION = '7.8.1'
 end

data/lib/recourse.rb

@@ -54,6 +54,7 @@ module Recourse
   end
 
   @declared = []
+  @retrievable = []
   @nested = {}
   @parents = {}
   @declared_bookmarks = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recourse
 version: !ruby/object:Gem::Version
-  version: 7.7.1
+  version: 7.8.1
 platform: ruby
 authors:
 - claudiob
@@ -146,6 +146,7 @@ files:
 - app/controllers/concerns/recourse/positioned.rb
 - app/controllers/concerns/recourse/reference_resolution.rb
 - app/controllers/concerns/recourse/resource_resolution.rb
+- app/controllers/concerns/recourse/retrieving.rb
 - app/controllers/concerns/recourse/weeks.rb
 - app/controllers/concerns/recourse/zoning.rb
 - app/controllers/recourse/base_controller.rb
@@ -230,6 +231,7 @@ files:
 - lib/recourse/helpers/references.rb
 - lib/recourse/helpers/refreshes.rb
 - lib/recourse/helpers/resources.rb
+- lib/recourse/helpers/retrievals.rb
 - lib/recourse/helpers/routing.rb
 - lib/recourse/helpers/rows.rb
 - lib/recourse/helpers/searches.rb
@@ -256,6 +258,7 @@ files:
 - lib/recourse/registry.rb
 - lib/recourse/routes.rb
 - lib/recourse/routes/nested.rb
+- lib/recourse/routes/refusals.rb
 - lib/recourse/routing.rb
 - lib/recourse/scopes.rb
 - lib/recourse/search.rb