recourse 3.0.4 → 4.0.0

data/lib/recourse/routes.rb

@@ -0,0 +1,57 @@
+require_relative 'routes/nested'
+
+module Recourse
+  # Extends the config/routes.rb DSL, so `recourses` works anywhere `resources` does.
+  module Routes
+    include Nested
+
+    # Draws what `resources` draws, after supplying any controller the host lacks. A
+    # block nests what it declares under each resource — ZIPs at
+    # `/counties/:county_id/zips` — with the nested controller namespaced after the
+    # parent, so it and the top-level `ZIPsController` stay two controllers. Only a
+    # `recourses` block adds that namespace, which every nested page relies on, so
+    # nesting inside a plain `resources` block raises here rather than serving a
+    # broken page. A `namespace` may sit in between — what is refused is a nesting
+    # that adds no namespace at all. A nested resource defaults to
+    # `only: %i[index new create]`, and an explicit `only:` or `except:` is the
+    # host's word, which wins.
+    def recourses(*names, **options, &block)
+      refuse_unscoped_nesting names
+      # Asked before the block, where every resource is its own parent. Top level
+      # only: a resource nested under another is reached through its parent, and its
+      # rows are kept at the resource's own route rather than at a second one drawn
+      # under every parent that happens to list them.
+      keepable = Recourse.bookmarks? && parent_resource.nil?
+
+      names.each { |name| declare_resource name }
+      options = default_nested_actions options
+      return resources(*names, **options) unless block || keepable
+
+      resources(*names, **options) { draw_within keepable, block }
+    end
+
+  private
+
+    # 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
+    end
+
+    def default_nested_actions(options)
+      return options if !parent_resource || options.key?(:only) || options.key?(:except)
+
+      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/routing.rb

@@ -1,38 +1,17 @@
-# A module to manage administered resources.
+# Reopened for the one question a controller and a view both ask of the router.
 module Recourse
-  # Makes Recourse methods like `recourses` available in config/routes.rb
+  # What the router will answer. A view asks it through `Helpers::Routing`, which keeps
+  # a set of its own for the table that asks four times a row; a controller asks here,
+  # at most once a request, so this scans rather than remembering — a set kept between
+  # requests would outlive the routes file it was built from.
   module Routing
-    # This method is equivalent to Rails `resources` with the added bonus that we store
-    # the name of these administered resources so we can display them to admins in the navbar.
-    def recourses(*args, **kwargs, &block)
-      store_recourses args, kwargs
-      resources(*args, **kwargs, &scoped(args, &block))
-    end
-
-  private
-
-    def store_recourses(args, kwargs)
-      if @scope[:scope_level_resource]
-        Recourse.resources[@scope[:scope_level_resource].name.to_sym][:nested] = args
-      else
-        routes = Array(kwargs.fetch :only, self.class::Resource.default_actions(false))
-        routes-= Array(kwargs.fetch :except, [])
-
-        Recourse.resources.merge! args.to_h { |arg| [arg, { module: @scope[:module], routes: routes }] }
+    # True where a route is drawn to this controller and action.
+    def routed?(controller_path, action)
+      Rails.application.routes.routes.any? do |route|
+        route.defaults[:controller] == controller_path && route.defaults[:action] == action.to_s
       end
     end
-
-    def scoped(args, &block)
-      return unless block_given?
-
-      parent_module = args.sole
-      Proc.new { scope module: parent_module, &block }
-      # :nocov:
-    rescue Enumerable::SoleItemExpectedError
-      raise ArgumentError, 'recourses accepts only one resource if a block is given'
-      # :nocov:
-    end
   end
-end
 
-ActionDispatch::Routing::Mapper.include Recourse::Routing
+  extend Routing
+end

data/lib/recourse/schemes.rb

@@ -0,0 +1,6 @@
+# Reopened for the one thing a reader says about how every page looks.
+module Recourse
+  # Where a reader's chosen mode is kept in their browser. Named once: the sidebar's
+  # controller writes it and the layout's own script reads it back before the first paint.
+  SCHEME_STORAGE = 'recourse-scheme'
+end

data/lib/recourse/scopes.rb

@@ -0,0 +1,37 @@
+module Recourse
+  # What the routes DSL reads back out of the Mapper as it draws, and what it records
+  # from that: the module a resource is being declared in, and the resource a block is
+  # nesting under.
+  module Scopes
+  private
+
+    # The Mapper keeps its scope in an internal frame with no reader, so the two
+    # facts this DSL needs — the module being drawn in, and the resource a block
+    # nests under — are read in these two methods and nowhere else: a Rails
+    # upgrade that moves the frame edits one file, twice.
+    def current_module
+      @scope[:module]
+    end
+
+    def parent_resource
+      @scope[:scope_level_resource]
+    end
+
+    def record_declaration(path)
+      # A nested resource is reached through its parent rather than the sidebar,
+      # so it is recorded under the parent's path — that order is its tabs' order.
+      return Recourse.declare path unless parent_resource
+
+      Recourse.nest parent_path, path
+    end
+
+    # The parent's own controller path: the module being drawn in, cut off after the
+    # parent resource's own segment, so a `namespace` between the two is left out
+    # rather than mistaken for the parent itself.
+    def parent_path
+      parts = current_module.to_s.split '/'
+
+      parts[0..parts.rindex(parent_resource.name)].join '/'
+    end
+  end
+end

data/lib/recourse/search.rb

@@ -0,0 +1,65 @@
+module Recourse
+  # The Ransack search behind an index: what a heading asked to sort by, what the
+  # search box asked to match, and the relation those add up to.
+  class Search
+    # Predicates whose value is a list, which is how a multiple combobox submits:
+    # one input holding every chosen value, comma-joined.
+    LIST_PREDICATES = /_(not_)?in\z/
+
+    # The Ransack object the form and the sort links read.
+    attr_reader :query
+
+    # A search of `relation` for the `q` parameters the request carried. A relation
+    # rather than a model, so a host that narrowed the index is searched inside what
+    # it narrowed to rather than around it — the model is still what answers for the
+    # order, the eager loads and the allowlist, and a relation knows its own.
+    #
+    def initialize(relation, params)
+      @model = relation.klass
+      @query = relation.ransack conditions(params)
+    end
+
+    # The relation the index lists. Ransack has already ordered it where a heading
+    # asked, so the model's own order only applies when nothing did.
+    def scope
+      scope = @query.result
+      scope = scope.order(*kept_first, @model.recourse_order) if @query.sorts.empty?
+      includes = @model.recourse_includes
+      return scope if includes.blank?
+
+      scope.includes includes
+    end
+
+  private
+
+    # The rows this viewer has kept, ahead of whatever the model orders by — but only
+    # where nobody clicked a heading, which is the same word `recourse_order` answers
+    # to. A semi-join rather than an outer one: it cannot multiply a row, and it
+    # leaves the count pagy runs over this relation well-formed.
+    def kept_first
+      reflection = Recourse.bookmarks_for @model
+      return [] unless reflection
+
+      kept = Recourse.bookmarks_of(reflection).select reflection.foreign_key
+      # `true` before `false` in PostgreSQL and `1` before `0` in the other two, so
+      # descending puts the kept rows first wherever this runs.
+      [@model.arel_table[@model.primary_key].in(kept.arel).desc]
+    end
+
+    # Ransack reads nothing it has not been shown — `ransackable_attributes` is the
+    # allowlist — so what arrives here needs no permitting, only untangling: a list
+    # predicate is split back into values, and a filter nobody set is dropped,
+    # since `IN ()` would match no row rather than every one.
+    def conditions(params)
+      # `?q=anything` reaches here as a String rather than as parameters of its own,
+      # and a search nobody asked for reaches here as nil. Neither is a condition.
+      return {} unless params.is_a? ActionController::Parameters
+
+      params.to_unsafe_h.filter_map do |key, value|
+        next if value.blank?
+
+        [key, key.match?(LIST_PREDICATES) ? value.to_s.split(',') : value]
+      end.to_h
+    end
+  end
+end

data/lib/recourse/searchable/columns.rb

@@ -0,0 +1,99 @@
+module Recourse
+  module Searchable
+    # What a model's own schema offers a search: which of its columns are worth
+    # looking through, and which of its foreign keys are worth looking past.
+    module Columns
+      # Column types a search box can match on containment. An enum is a Postgres
+      # type of its own, and what it holds is a word, so it reads as a string too.
+      SEARCHABLE_TYPES = %i[string text citext enum].freeze
+
+      # Columns worth searching: the indexed strings a table also shows. An index is
+      # the only signal a schema carries about which column identifies a row rather
+      # than describes it, and a column no page draws is not one to search by — a row
+      # would arrive with nothing on it explaining why. That is also what keeps a
+      # `recourse_hidden` column out: hidden from every screen means hidden here.
+      def recourse_searchable_columns
+        recourse_indexed_strings - recourse_encrypted_names - Recourse.hidden_columns(self)
+      end
+
+      # The attributes Active Record Encryption holds, as column names.
+      def recourse_encrypted_names
+        Array(encrypted_attributes).map(&:to_s)
+      end
+
+      # Foreign keys a search reaches through rather than filters by: the ones whose
+      # other model is too long to list, since a menu is only a control while every row
+      # fits in one. The label has to be a word to match, and the key one a screen
+      # draws -- a row matched through a hidden key arrives saying nothing about why.
+      def recourse_searchable_associations
+        hidden = Recourse.hidden_columns self
+
+        recourse_references.select do |association|
+          next false if hidden.include? association.foreign_key.to_s
+
+          !association.klass.recourse_listable? && association.klass.recourse_searchable_label?
+        end
+      end
+
+      # True where the label is a column a `cont` can match. Reaching through a foreign
+      # key to compare an id or a date against typed text says nothing -- and neither
+      # does naming a column Ransack will not answer to. Encryption leaves a column's
+      # type alone, so a label the search could never match reads as a word here and is
+      # caught by the allowlist instead: a term built from one raises on the reader the
+      # box asks for, taking down every index that reaches this model through a key.
+      def recourse_searchable_label?
+        label = recourse_label.to_s
+
+        SEARCHABLE_TYPES.include?(type_for_attribute(label).type) &&
+          ransackable_attributes.include?(label)
+      end
+
+    private
+
+      # The same columns where they are encrypted, which a search matches whole
+      # rather than by containment: a LIKE reads ciphertext and matches nothing,
+      # while a deterministic value encrypts to the same bytes every time, so `=`
+      # still finds it. Rails' own `deterministic_encrypted_attributes` is that
+      # list — a column encrypted any other way never compares equal twice.
+      def recourse_encrypted_searchable_columns
+        deterministic = Array(deterministic_encrypted_attributes).map(&:to_s)
+
+        (recourse_indexed_strings & deterministic) -
+          Recourse.hidden_columns(self)
+      end
+
+      # Every indexed column whose value is a word, whether or not it is encrypted.
+      # Asked through `type_for_attribute` — the one door the whole gem uses — so
+      # an `attribute` override counts here the way it counts on a form.
+      def recourse_indexed_strings
+        column_names.intersection(recourse_indexed_columns).select do |column|
+          type = type_for_attribute column
+          # An array column answers with its subtype's own name — `text[]` reads as
+          # `:text` — and a LIKE against an array is SQL that never runs. A type
+          # wrapping a subtype is a collection, not a word, so it stays out.
+          SEARCHABLE_TYPES.include?(type.type) && !type.respond_to?(:subtype)
+        end
+      end
+
+      # Those foreign keys as Ransack names them: `zip_code`, for the ZIP that
+      # `/locations` asks to be typed rather than picked out of 40,965 options.
+      # `except:` leaves out the one a nested route has already answered.
+      def recourse_searchable_references(except: nil)
+        (recourse_searchable_associations - [except]).map do |association|
+          "#{association.name}_#{association.klass.recourse_label}"
+        end
+      end
+
+      # Columns an index covers, the primary key among them. Read from the schema
+      # cache, so asking costs nothing after the first look — and the gem's one
+      # reach into that cache, whose spelling moves across Rails majors, is fenced
+      # in this method so an upgrade edits one place.
+      def recourse_indexed_columns
+        indexes = connection_pool.schema_cache.indexes table_name
+        # An expression index reports a string rather than a list of columns, and it
+        # names no column an ORDER BY could use, so intersecting drops it.
+        column_names.intersection [primary_key, *indexes.flat_map { |one| Array one.columns }]
+      end
+    end
+  end
+end

data/lib/recourse/searchable/filters.rb

@@ -0,0 +1,58 @@
+module Recourse
+  module Searchable
+    # What a model offers as a filter beside the search box: a menu for every column
+    # whose values are a short known list, and one for every key pointing at a table
+    # short enough to list.
+    module Filters
+      # Filters offered beside the search box, as a Ransack predicate to the options
+      # that draw it — `label:` for its heading, `scope:` for the records it offers.
+      # One per enum, one per boolean, then one per belongs_to, less the ones the
+      # search box reaches through instead: a typed label says the other model is too
+      # big to list. The model's own columns come first, before the menus that name
+      # other tables.
+      def filter_fields
+        enum_filter_fields.merge(boolean_filter_fields).merge reference_filter_fields
+      end
+
+    private
+
+      # Columns a filter may name at all. A menu narrowing the table by a column no
+      # screen shows asks a reader to choose by something they cannot see, which is the
+      # reason `recourse_searchable_columns` leaves the same columns out of the search
+      # box: hidden from every screen means hidden here.
+      def filterable_columns
+        column_names - Recourse.hidden_columns(self)
+      end
+
+      # Every one of the three comes to the same shape, and `_in` is what lets a
+      # request tick more than one of the values a menu offers.
+      def filters_for(names)
+        names.index_with({}).transform_keys { |name| "#{name}_in" }
+      end
+
+      # One per enum: a dozen words a column admits are a menu whatever else is on the
+      # page.
+      def enum_filter_fields
+        filters_for defined_enums.keys & filterable_columns
+      end
+
+      # One per boolean: a column admitting two values is a menu for the same reason a
+      # dozen words are, and the two are the type's own rather than anything declared.
+      def boolean_filter_fields
+        booleans = filterable_columns.select { |one| type_for_attribute(one).type == :boolean }
+
+        filters_for booleans
+      end
+
+      # One per belongs_to the search box does not reach through instead.
+      def reference_filter_fields
+        searched = recourse_searchable_associations
+        keys = recourse_references.filter_map do |one|
+          one.foreign_key.to_s unless searched.include? one
+        end
+
+        filters_for keys & filterable_columns
+      end
+    end
+  end
+end

data/lib/recourse/searchable/terms.rb

@@ -0,0 +1,56 @@
+module Recourse
+  module Searchable
+    # What the search box above a table submits, and what it says while it is empty.
+    module Terms
+      # The predicate a search box submits: everything it looks through at once,
+      # joined by `or`. Nil where a model has nothing worth looking through, which
+      # is also what leaves that model's index without the form — filters and all.
+      # `except:` takes the association a nested route already answered, so a page
+      # pinned to one provider offers no box to search them all.
+      def search_field(except: nil)
+        fields, predicate = recourse_search_terms(except:)
+        return if fields.empty?
+
+        "#{fields.join '_or_'}_#{predicate}"
+      end
+
+      # What the search box says while it is empty, naming what it looks through.
+      def search_prompt(except: nil)
+        fields, predicate = recourse_search_terms(except:)
+        return if fields.empty?
+
+        list = recourse_search_names(except:).join ' or '
+        I18n.t "recourse.searched_#{predicate}", list: list
+      end
+
+    private
+
+      # What a search box looks through, and how it matches: the plaintext columns
+      # and the labels behind foreign keys — less the one `except:` names — on
+      # containment; or, for a model that keeps nothing in plaintext worth
+      # searching, its encrypted columns, whole.
+      def recourse_search_terms(except: nil)
+        plain = recourse_searchable_columns + recourse_searchable_references(except:)
+        return [plain, 'cont'] if plain.any?
+
+        [recourse_encrypted_searchable_columns, 'eq']
+      end
+
+      # Those same terms as words, lower case but for the acronyms among them.
+      def recourse_search_names(except: nil)
+        fields, = recourse_search_terms(except:)
+
+        fields.map { |field| Recourse.downcase recourse_term_name(field) }
+      end
+
+      # A term is a column of this model, or a `zip_code` reaching through one of its
+      # foreign keys — which a form and a table already have a name for.
+      def recourse_term_name(field)
+        reached = recourse_searchable_associations.find { |one| field.start_with? "#{one.name}_" }
+        return reached.klass.recourse_reference_name if reached
+
+        human_attribute_name field
+      end
+    end
+  end
+end

data/lib/recourse/searchable.rb

@@ -1,38 +1,63 @@
-# A module to manage administered resources.
+require 'active_support'
+
+require_relative 'searchable/columns'
+require_relative 'searchable/filters'
+require_relative 'searchable/terms'
+
 module Recourse
-  # Extends any model to be searchable with Ransack.
+  # Extends every Active Record model with what Ransack asks of it, so an index
+  # sorts, searches and filters before a model has said anything at all.
   module Searchable
-    # Returns the attributes that can be searched.
-    def ransackable_attributes(auth_object = nil)
-      %w[ ]
-    end
+    include Columns, Filters, Terms
 
-    # Returns the associations that can be searched (by default: none).
-    def ransackable_associations(auth_object = nil)
-      %w[ ]
-    end
+    # How many rows a menu may hold before it stops being a menu. Fifty states are a
+    # list to pick from; three thousand counties are a page of HTML nobody reads.
+    MENU_LIMIT = 100
 
-    # Returns the associations that can be sorted by (by default: none).
-    def ransortable_attributes(auth_object = nil)
-      %w[ ]
+    # Attributes Ransack may read: every column that is not encrypted, plus the
+    # encrypted ones a search can still match whole — `cont` reads ciphertext and
+    # finds nothing, but a deterministic `eq` compares the same bytes every time.
+    def ransackable_attributes(_auth_object = nil)
+      (column_names - recourse_encrypted_names) + recourse_encrypted_searchable_columns
     end
 
-    # @note to be overriden by subclasses -- the name of the field to search with.
-    def search_field
+    # Associations Ransack may reach through: the ones the search box looks into,
+    # and no others, so a predicate joins another table only where one is searched.
+    def ransackable_associations(_auth_object = nil)
+      recourse_searchable_associations.map { |association| association.name.to_s }
     end
 
-    # @note to be overriden by subclasses -- the placeholder for the field to search with.
-    def search_prompt
+    # Columns a heading may sort by: the timestamps, whatever an index covers, and
+    # every counter cache — a count is a number a reader ranks by, and the one column
+    # whose heading says what it counts. Never a foreign key: its cell shows a label
+    # from the other table, and the id under it is not the order that label reads in.
+    # And never one the model hides, for the reason `recourse_searchable_columns` gives
+    # for leaving those out too: hidden from every screen means hidden here.
+    def ransortable_attributes(_auth_object = nil)
+      readable = ransackable_attributes - recourse_encrypted_names
+      indexed = recourse_indexed_columns + recourse_counters.keys + Recourse::TIMESTAMPS
+
+      keys = recourse_references.map { |one| one.foreign_key.to_s }
+
+      (readable & indexed) - keys - Recourse.hidden_columns(self)
     end
 
-    # @note to be overriden by subclasses -- the name of the field to filter by.
-    def filter_fields = {}
+    # True where a foreign key pointing here is typed rather than picked, which a
+    # form and the controller reading its parameters back have to agree on: the label
+    # is bounded, or the table is too long to list.
+    def recourse_typed_reference? = recourse_typed_label? || !recourse_listable?
 
-    # Returns the names of all the search and filter fields.
-    def searchable_fields = [search_field, filter_fields.keys]
+    # True where every row of this model could be listed in one menu. The count is
+    # bounded, so the question costs the same on ten rows as on ten million, and it
+    # is asked once per class — a table that crosses the line is noticed at boot.
+    def recourse_listable?
+      return @recourse_listable unless @recourse_listable.nil?
+
+      @recourse_listable = limit(MENU_LIMIT + 1).count <= MENU_LIMIT
+    end
   end
 end
 
-ActiveSupport.on_load(:active_record) do
+ActiveSupport.on_load :active_record do
   extend Recourse::Searchable
 end

data/lib/recourse/titles.rb

@@ -0,0 +1,56 @@
+# Reopened for what a page calls things: the words a resource, a model and a column
+# are read out under, which several helpers were each spelling for themselves.
+module Recourse
+  # What a resource and a model are called on a page. Extended onto `Recourse`, so
+  # every one of these is `Recourse.something` wherever it is called from.
+  module Titles
+    # Lower case, but for the words Rails was told are acronyms: `ZIP code` reads as
+    # `ZIP code` and never `zip code`, while `Code or Name` becomes `code or name`.
+    # The plural of one counts as one, so `8 ZIPs` survives a host that registered
+    # `ZIP` alone — pluralizing an acronym is the gem's job, not the host's.
+    def downcase(text)
+      acronyms = ActiveSupport::Inflector.inflections.acronyms
+
+      text.split.map do |word|
+        known = [word, word.singularize].any? { |one| acronyms.key? one.downcase }
+
+        known ? word : word.downcase
+      end.join ' '
+    end
+
+    # The plural title a resource is shown under, read off its model rather than out
+    # of its path: `ZIP` pluralizes to `ZIPs`, where humanizing `zips` says `Zips`
+    # unless the host registers that word as an acronym of its own. It also follows a
+    # model renamed in a locale file, which humanizing a path never would.
+    def title(name)
+      model_title model(name)
+    end
+
+    # The same for a name that may resolve to no model at all: an action drawn under
+    # a record still needs a word for its button, and `pause` is a verb this app never
+    # made a class for.
+    def known_title(name)
+      segment = name.to_s.split('/').last
+      model = segment.classify.safe_constantize
+
+      model ? model_title(model) : segment.humanize
+    end
+
+    # And the singular of that, for the button a bare action earns: `Add sweep` is one
+    # sweep, and the same split that names the tab beside it.
+    def known_singular(name)
+      known_title(name).singularize
+    end
+
+    # And the same for a model already in hand — the far side of an association, the
+    # model a filter lists. `count:` picks the singular where one is meant, and
+    # `lower:` is for a title that follows a word rather than opening the line.
+    def model_title(model, count: nil, lower: false)
+      title = model.model_name.human.pluralize count
+
+      lower ? downcase(title) : title
+    end
+  end
+
+  extend Titles
+end

data/lib/recourse/version.rb

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

data/lib/recourse/writes.rb

@@ -0,0 +1,12 @@
+# Reopened for what a page is told about the write that brought it here.
+module Recourse
+  # The flash key naming the row a write just landed on. Data for the page rather than
+  # a message for the reader, so `_flash` keeps it out of the loop that draws the rest:
+  # every other key there becomes a toast, whoever invented it.
+  WRITTEN = 'recourse_written'
+
+  # The name a row goes by in the page it is drawn on, which a write reports itself by
+  # and a square keeps its own row by. Read by a controller and by a view, which is why
+  # it lives here rather than in either.
+  def self.row_id(record) = ActionView::RecordIdentifier.dom_id(record)
+end

data/lib/recourse/zones.rb

@@ -0,0 +1,6 @@
+# Reopened for whose clock the gem's own pages are read against.
+module Recourse
+  # Where the reader's own time zone is kept in their browser, for the server to read
+  # back. An IANA name — `America/Los_Angeles` — as the browser itself reports it.
+  ZONE_STORAGE = 'recourse-zone'
+end