recourse 3.0.3 → 4.0.0

data/lib/recourse/helpers/kinds.rb

@@ -0,0 +1,87 @@
+module Recourse
+  module Helpers
+    # What an attribute holds, which is the one question a value and a field are both
+    # answers to.
+    module Kinds
+      # Numbers, which differ by what they are of rather than by how they are stored.
+      NUMERIC_KINDS = %i[integer decimal float phone monetary percentage month year].freeze
+
+      # The two of those that count nothing, and so are neither delimited nor rounded:
+      # a month is a word for one and a year is when something happened.
+      UNCOUNTED_KINDS = %i[month year].freeze
+
+      # The kinds whose values are a list known before anybody types: an enum's are the
+      # model's own, and a time zone's are Rails'. Each is drawn as the menu of them.
+      MENU_KINDS = %i[enum time_zone].freeze
+
+      # A payload, under both names an adapter has for one: SQLite and MySQL report a
+      # JSON column as `json`, and PostgreSQL's own type reports `jsonb`. Two names for
+      # the thing a page does the same with, so the gem asks for either.
+      JSON_KINDS = %i[json jsonb].freeze
+
+    private
+
+      # Whether a kind is one of those, which is what both pages branch on first.
+      def numeric_kind?(kind) = NUMERIC_KINDS.include?(kind)
+
+      def menu_kind?(kind) = MENU_KINDS.include?(kind)
+
+      # A month read as the word for one, and a year as the digits it is. Neither counts
+      # anything, so neither wears the delimiter a quantity does: 2,025 is a number of
+      # things, and 2025 is when they happened.
+      def uncounted(kind, value)
+        return unless value
+
+        kind == :month ? Date::MONTHNAMES[value] : value.to_s
+      end
+
+      # Asked in the order that settles it. A counter cache is a counter whatever its
+      # column says, since no page may show one and no form may set one; an enum is
+      # one however it is stored, and is asked before a list because Rails wraps a
+      # column's type to map an enum's words onto it, which reads as a list otherwise;
+      # a phone is a phone by its name, the convention the placeholders and the pattern
+      # already follow; and everything else is the type the attribute itself reports —
+      # `:monetary` included, where a host has registered a type that says so.
+      def attribute_kind(column)
+        return :counter if resource_model.recourse_counters.key? column
+        return :enum if resource_model.defined_enums.key? column
+        return :list if Recourse.list_column? resource_model, column
+        return :phone if column == 'phone'
+
+        attribute_type column
+      end
+
+      # The model's own attribute type, so an `attribute` override still counts and
+      # `columns_hash` is never asked.
+      def attribute_type(column)
+        resource_model.type_for_attribute(column).type
+      end
+
+      # Columns holding JSON, under whichever name this adapter reports. A payload is a
+      # service's answer kept whole — machinery rather than anything a row is about —
+      # and one of them is as wide as a page, so no table draws one until a model names
+      # it back. Asked through `type_for_attribute` like every other kind, so an
+      # `attribute` override counts here too.
+      def json_columns
+        resource_model.column_names.select { |column| JSON_KINDS.include? attribute_type(column) }
+      end
+
+      # How many decimals the attribute keeps, and how many digits in all. Read from
+      # the type rather than the column, and nil for anything that never said.
+      def attribute_scale(column)
+        resource_model.type_for_attribute(column).scale
+      end
+
+      # Total digits the attribute holds, the scale included.
+      def attribute_precision(column)
+        resource_model.type_for_attribute(column).precision
+      end
+
+      # What to round a number to, where the attribute says how much it keeps.
+      def precision_option(column)
+        scale = attribute_scale column
+        scale ? { precision: scale } : {}
+      end
+    end
+  end
+end

data/lib/recourse/helpers/limits.rb

@@ -0,0 +1,37 @@
+module Recourse
+  module Helpers
+    # The switch under a table saying how much of it one page shows.
+    module Limits
+    private
+
+      # It names the size it is not showing, since the sentence beside it already says
+      # how much of the table is on the page: what is left to say is where a click
+      # goes. A button rather than a link — it performs something rather than leading
+      # anywhere, and there is no address for a size the query string is not asked for.
+      def limit_link(pagy)
+        tag.button limit_label(other_limit(pagy)),
+                   type: :button, data: { action: 'limit#toggle' },
+                   class: 'btn btn-link btn-sm p-0 align-baseline recourse-limit'
+      end
+
+      # Two sizes, so the other one is the whole of the choice.
+      def other_limit(pagy)
+        (Recourse::LIMITS - [pagy.limit]).first
+      end
+
+      def limit_label(limit)
+        t 'recourse.per_page', limit: limit
+      end
+
+      # What the switch behind the button needs: where to keep the choice, and the one
+      # size a click writes there. Worked out here rather than in the browser, so the
+      # page and the cookie can only ever agree.
+      def limit_data(pagy)
+        {
+          controller: 'limit', limit_storage_value: Recourse::LIMIT_STORAGE,
+          limit_to_value: other_limit(pagy),
+        }
+      end
+    end
+  end
+end

data/lib/recourse/helpers/names.rb

@@ -0,0 +1,44 @@
+module Recourse
+  module Helpers
+    # What a foreign key is called, rather than the id that points at it.
+    module Names
+    private
+
+      # What one key says: the label of the record it points at, led to that record's
+      # page where the routes drew one.
+      def named_cell(resource, association)
+        record = resource.association(association.name).reader
+
+        record && led(reference_cell(resource, association), association.klass.name, record.id)
+      end
+
+      # The words of a cell, led to the record's own page where the routes drew one that
+      # can be linked to. Here rather than inside `reference_cell`, which also fills a
+      # form field's value -- an anchor inside an input is markup a reader would see
+      # spelled out. A cell with nothing in it leads nowhere: there would be no words
+      # to click.
+      def led(said, kind, id)
+        path = shown_resource kind
+        return said if path.nil? || said.blank?
+
+        turbo_link_to said, url_for(controller: "/#{path}", action: :show, id:)
+      end
+
+      # The resource a kind is read on, where the routes drew one that can be linked to
+      # at all: declared at the top level, so no parent id is wanted that a row like
+      # this has no way to supply; listing that model; and answering `show`. Nil where
+      # any of the three is missing, which is a cell that reads as words rather than one
+      # leading somewhere the router would refuse. Remembered per kind and per render:
+      # a table asks this once a row, and no route is drawn while a page is drawing.
+      def shown_resource(kind)
+        @recourse_shown ||= {}
+        return @recourse_shown[kind] if @recourse_shown.key? kind
+
+        @recourse_shown[kind] = Recourse.declared.find do |path|
+          Recourse.parent_of(path).nil? && Recourse.model?(path)&.name == kind &&
+            routed?(path, 'show')
+        end
+      end
+    end
+  end
+end

data/lib/recourse/helpers/navigation.rb

@@ -0,0 +1,75 @@
+module Recourse
+  module Helpers
+    # Helpers for the navbar: the trail across it, and the links and forms it draws.
+    module Navigation
+    private
+
+      # Trail to the current page as [resource, title, path] triples, opening with
+      # the parent a nested page sits under; a nil path is not a link.
+      def resource_breadcrumbs
+        crumbs = parent_breadcrumbs
+        leaf = breadcrumb_leaf
+        here = controller.controller_path
+        return crumbs << [here, resources_name, nil] unless leaf
+
+        crumbs << [here, resources_name, index_url] << [nil, leaf, nil]
+      end
+
+      # Where this resource's index is, or nil where it has none, in which case the crumb
+      # naming it is read out rather than linked.
+      def index_url
+        url_for action: :index if routed_action? 'index'
+      end
+
+      # A link out of a table. Every cell is inside the results frame, and the page a
+      # cell links to has no frame of that name, so Turbo would replace the table with
+      # `Content missing` rather than leaving the page. `_top` is what leaves it.
+      # Takes everything `link_to` takes, and a `data:` of its own still wins.
+      def turbo_link_to(name, path, **options)
+        data = { turbo_frame: '_top' }.merge options.fetch(:data, {})
+
+        link_to name, path, **options, data: data
+      end
+
+      # Where a form submits: the action that saves it, in the namespace the resource
+      # was drawn in. `form_with model:` would ask polymorphic routing instead, which
+      # knows the model and not the namespace, and names a route that does not exist.
+      def resource_form_url(record)
+        return url_for action: :create if record.new_record?
+
+        url_for action: :update, id: record
+      end
+
+      # Path to this resource's new page, or nil when there is not one to link to.
+      def new_resource_path
+        return unless routed_action? 'new'
+
+        url_for action: :new
+      end
+
+      # True where `create` is routed with no `new` to draw a form: the navbar then
+      # offers a Create button in the Add link's place. Routing it that way is the
+      # host saying a bare record can stand — the routes are the whole check.
+      def bare_create?
+        new_resource_path.nil? && routed_action?('create')
+      end
+
+      # Label for a link to a resource: the icon its model picked, then its title,
+      # with the letter at `key` marked where the link answers to one.
+      def resource_label(resource, title, key = nil)
+        name = key ? shortcut_title(title, key) : title
+        icon = Recourse.known_icon resource
+
+        safe_join [icon && tag.i(class: "bi bi-#{icon}"), name].compact, ' '
+      end
+
+      # Only a page beneath the index names itself, and names what it is showing.
+      def breadcrumb_leaf
+        case controller.action_name
+        when 'new', 'create' then t 'recourse.new', model: resource_name
+        when 'show', 'edit', 'update' then resource_record_label
+        end
+      end
+    end
+  end
+end

data/lib/recourse/helpers/parents.rb

@@ -0,0 +1,82 @@
+module Recourse
+  module Helpers
+    # What a page knows about the records either side of it: the one a nested route
+    # names above it, and the ones a count or a tab reaches below.
+    module Parents
+    private
+
+      # The record a nested route names above this page, or nil at the top level.
+      def resource_parent
+        controller_assign 'recourse_parent'
+      end
+
+      # The belongs_to that record is reached through, which names the foreign key
+      # every row on the page shares.
+      def resource_parent_association
+        controller_assign 'recourse_parent_association'
+      end
+
+      # The page a nested resource keeps under one record: the index of its children at
+      # `/counties/1/zips`, or -- where the routes drew a singular resource -- the one
+      # record itself at `/places/5/zip`, reached with no id of its own. The key is
+      # named after the path the children are nested under rather than after the page
+      # being served, since a page nested one level up is served by another controller
+      # entirely.
+      def nested_url(record, path, nested)
+        url_for controller: "/#{nested}", action: :index,
+                "#{path.split('/').last.singularize}_id": record.id
+      end
+
+      # The crumbs a nested page sits under: the parent's own index, then the record
+      # the path names — `Counties`, then `Alameda County`, before `ZIPs`. The
+      # record's crumb links to its show page, where one is routed to link to.
+      def parent_breadcrumbs
+        parent = resource_parent
+        return [] unless parent
+
+        path = Recourse.parent_of controller.controller_path
+        [
+          [path, Recourse.title(path), parent_url(path, :index)],
+          [nil, parent_title(parent), parent_url(path, :show, id: parent)],
+        ]
+      end
+
+      # Where this resource's own routes are drawn. A nested route answers the
+      # collection actions and no more, so a member page — and a count reaching one
+      # of the resource's own nested indexes — is looked up above the nesting: this
+      # resource's name, drawn where its parent was drawn, so `admin/counties/zips`
+      # leaves `admin/zips` however many segments the nesting took. Unless the nesting
+      # drew a member page of its own: a county a provider serves is read under that
+      # provider and nowhere else, and its pages are where the host put them.
+      def resource_controller_path
+        path = controller.controller_path
+        return path if !resource_parent || routed?(path, 'show') || routed?(path, 'edit')
+
+        module_of = Recourse.parent_of(path).rpartition('/').first
+
+        [module_of.presence, path.split('/').last].compact.join '/'
+      end
+
+      def parent_title(parent)
+        # A label is not always words: a numeric one is spoken as a string —
+        # `truncate` has no patience for an Integer — and where a record says
+        # nothing at all, the model's own name stands in, as the delete warning's
+        # title already does.
+        label = parent.attributes[parent.class.recourse_label.to_s]
+
+        # Forty characters of the label, no more: a record named by an address or a
+        # sentence would otherwise walk the crumb into the navbar's search form.
+        truncate label.presence&.to_s || parent.class.model_name.human, length: 40
+      end
+
+      # One of the parent's own pages, or nil where the host drew no route to it —
+      # a crumb without a path is read out rather than linked. Both crumbs ask,
+      # since a parent reached through a nesting need not be listed or shown at all.
+      def parent_url(path, action, **)
+        return unless routed? path, action
+
+        url_for controller: "/#{path}", action:, **
+      end
+    end
+  end
+end

data/lib/recourse/helpers/pictures.rb

@@ -0,0 +1,33 @@
+module Recourse
+  module Helpers
+    # The pictures a page draws: an icon on its own, and an icon standing in for a
+    # heading where a column is too narrow to carry the word.
+    module Pictures
+    private
+
+      # One icon, named by the concept it means rather than by what this set calls it.
+      # Whatever else the caller hands over — a role, a tooltip's data, a class to hide
+      # it by — rides along, a class of the caller's joining the two named here rather
+      # than replacing them.
+      def icon_tag(concept, label: nil, **options)
+        classes = ['bi', "bi-#{Unicon[concept][:bootstrap]}", options.delete(:class)]
+
+        tag.i class: classes.compact, aria: { label: }, **options
+      end
+
+      # A heading that is a picture: an action column's, as narrow as the icon in it,
+      # and a counter's, headed with what it counts. Named to a screen reader, since
+      # an icon alone says nothing to one, and given the tooltip that says the same
+      # word to everyone else.
+      def icon_heading(concept, title, **)
+        icon_tag concept, label: title, role: :img, data: tooltip_on_top(title), **
+      end
+
+      def tooltip_on_top(title)
+        # `bs_title` is what Bootstrap's tooltip reads, and the controller is what
+        # makes one: Bootstrap never wires a tooltip on its own.
+        { controller: 'tooltip', bs_placement: 'top', bs_title: title }
+      end
+    end
+  end
+end

data/lib/recourse/helpers/references.rb

@@ -0,0 +1,99 @@
+module Recourse
+  module Helpers
+    # Fields for a foreign key: a value to type, or a list to pick from.
+    module References
+    private
+
+      # The belongs_to a column is the foreign key of, or nil when it is not one.
+      # Every key at once and once per render, rather than a scan of the model's
+      # associations for each cell of each row that holds one.
+      def belongs_to_association(column)
+        @recourse_belongs_to ||= resource_model.recourse_references
+                                               .index_by { |one| one.foreign_key.to_s }
+
+        @recourse_belongs_to[column]
+      end
+
+      # A field for a foreign key. Where the label has a length it is short enough
+      # to type, and typing it beats listing every record there is to pick from.
+      def reference_field(form, column, association)
+        return typed_reference form, column, association if typed_reference? association
+
+        combobox form, column, association
+      end
+
+      # What the record a foreign key points at is called, rather than the id that
+      # points at it. `association` reads the target without naming a method for it.
+      def reference_cell(resource, association)
+        record = resource.association(association.name).reader
+        return unless record
+
+        record.attributes[association.klass.recourse_label.to_s]
+      end
+
+      # Heading for a column, naming the attribute too where one has to be typed:
+      # `ZIP code` rather than `ZIP`, since a code is what the field asks for.
+      def reference_title(column, association)
+        return resource_column_title column unless typed_reference? association
+
+        association.klass.recourse_reference_name
+      end
+
+      def typed_reference?(association)
+        association&.klass&.recourse_typed_reference?
+      end
+
+      def typed_reference(form, column, association)
+        messages = errors_on column
+        id = form.field_id column
+        html = typed_html(column, association).merge(
+          class: messages.any? ? 'form-control is-invalid' : 'form-control',
+          value: typed_reference_value(form, column, association),
+          'aria-describedby': (messages.any? ? "#{id}_error" : field_described(column))
+        )
+
+        safe_join [form.text_field(column, **html), invalid_feedback(messages, id)]
+      end
+
+      # What the field opens on: the record's own label, so an edit that changes
+      # something else does not have to retype this. The request wins where it has
+      # anything to say — a code matching nothing was never assigned, so only what
+      # was typed is left to show, and a code cleared on purpose stays cleared.
+      def typed_reference_value(form, column, association)
+        typed = params.dig resource_key, column
+        return typed if typed
+
+        reference_cell form.object, association
+      end
+
+      # The shape belongs to the attribute typed; whether it is required does not,
+      # since that is the association's rule and not the other model's.
+      def typed_html(column, association)
+        klass = association.klass
+        shape = field_html klass.recourse_label.to_s, nil, klass
+        own = {
+          required: (true if required? resource_model, column), size: nil,
+          placeholder: placeholder(resource_model, column, nil),
+        }
+
+        shape.except(:required, :placeholder).merge own
+      end
+
+      # Bootstrap only reveals this next to an `.is-invalid` sibling of its own.
+      def invalid_feedback(messages, id)
+        return if messages.empty?
+
+        tag.small messages.to_sentence.upcase_first, class: 'invalid-feedback', id: "#{id}_error"
+      end
+
+      # A belongs_to reports on the association, so `state_id` asks about `state`.
+      def errors_on(column)
+        attribute = column.delete_suffix '_id'
+        messages = resource_record.errors[column]
+        return messages if attribute == column
+
+        messages + resource_record.errors[attribute]
+      end
+    end
+  end
+end

data/lib/recourse/helpers/refreshes.rb

@@ -0,0 +1,27 @@
+module Recourse
+  module Helpers
+    # Subscribes an index page to the refreshes its model broadcasts.
+    module Refreshes
+    private
+
+      # The subscription tag, after asking the head for the two metas that make a
+      # refresh morph in place and keep the scroll — and nothing at all when the
+      # model broadcasts nothing, so a host without turbo-rails is untouched.
+      def refresh_subscription
+        return unless resource_model.recourse_broadcasting?
+
+        content_for :head, refresh_metas
+        turbo_stream_from resource_model.model_name.plural
+      end
+
+      # Without these Turbo answers a refresh by replacing the whole body, which
+      # drops the caret, the scroll and any menu that was open.
+      def refresh_metas
+        safe_join [
+          tag.meta(name: 'turbo-refresh-method', content: 'morph'),
+          tag.meta(name: 'turbo-refresh-scroll', content: 'preserve'),
+        ]
+      end
+    end
+  end
+end

data/lib/recourse/helpers/resources.rb

@@ -0,0 +1,47 @@
+module Recourse
+  module Helpers
+    # What the page is about and what it is called: the model behind it, the record
+    # on it, and the words both are read out under.
+    module Resources
+      # Human, plural name of the resource on the page, e.g. `Contacts`. `known_title`,
+      # since a host page wearing this layout may be named after no model at all — a
+      # contact's home is a `Location`, and the path is the only word for it.
+      def resources_name = Recourse.known_title(controller.controller_name)
+
+      # Singular, lowercase name of the resource, e.g. 'contact'.
+      def resource_name
+        Recourse.downcase resource_model.model_name.human
+      end
+
+      # Local name a row partial receives its record under, e.g. :contact.
+      def resource_key
+        controller.controller_name.singularize.to_sym
+      end
+
+      # The record the action built, read from the assigns rather than by ivar name.
+      def resource_record
+        controller_assign resource_key.to_s
+      end
+
+      # The one door to what the controller assigned. `view_assigns` is public API,
+      # and every name the gem reads through it walks this method, so the untyped
+      # contract with the controller's ivar names has a single seam.
+      def controller_assign(name)
+        controller.view_assigns[name]
+      end
+
+      # What the record on the page is called, by whatever its model labels it with —
+      # and nothing where there is no record to name.
+      def resource_record_label
+        resource_record&.attributes&.dig resource_model.recourse_label.to_s
+      end
+
+    private
+
+      # Resolved by the controller, where a host may have named a model the route does not.
+      def resource_model
+        controller_assign('recourse_model') || Recourse.model(controller.controller_name)
+      end
+    end
+  end
+end

data/lib/recourse/helpers/routing.rb

@@ -0,0 +1,28 @@
+module Recourse
+  module Helpers
+    # What the router will answer, which is what decides whether a link is drawn.
+    module Routing
+    private
+
+      # True where this controller both implements an action and has a route drawn to
+      # it. Either alone is a link that 404s or raises. The path is the one being
+      # served unless a caller names another: a nested page asks about the resource's
+      # own routes, which is where the member actions a nesting leaves out are drawn.
+      def routed_action?(action, path = controller.controller_path)
+        return false unless controller.class.action_methods.include? action
+
+        routed? path, action
+      end
+
+      def routed?(controller_path, action)
+        # The route set as one set of "controller#action" words, built once per
+        # render: the table asks four times per row, and routes never change mid-page.
+        @recourse_routed ||= Rails.application.routes.routes.to_set do |route|
+          "#{route.defaults[:controller]}##{route.defaults[:action]}"
+        end
+
+        @recourse_routed.include? "#{controller_path}##{action}"
+      end
+    end
+  end
+end

data/lib/recourse/helpers/rows.rb

@@ -0,0 +1,33 @@
+module Recourse
+  module Helpers
+    # The row partial a table renders: the host's for this resource where one is
+    # defined — every column its own — and the gem's generic row otherwise.
+    module Rows
+    private
+
+      # What the cache key reads so the table notices its row partial. Rails
+      # resolves `render 'row'` per request, but the fragment's own digest never
+      # follows it there — so a host `_row` added or edited after a fragment was
+      # written would keep serving the row it replaced. The digestor walks the
+      # resolved template's own dependencies too, so a partial a host's row
+      # renders from inside expires the table as well.
+      def row_digest
+        row = lookup_context.find 'row', lookup_context.prefixes, true
+
+        ActionView::Digestor.digest name: row.virtual_path, format: :html, finder: lookup_context
+      end
+
+      # Whether the table may be kept at all. A sorted or filtered one never is: two
+      # requests can ask for one relation and want different rows, and only one of them
+      # clicked a heading to say so.
+      #
+      # Nor a table of rows nothing versions. `cache` reads `MAX(updated_at)` off the
+      # relation without asking whether there is such a column, and reference data — a
+      # table of counties written by a migration and never again — keeps none. The same
+      # question `keepable_menu?` asks of a menu, for the same reason.
+      def cacheable_table?
+        params[:q].blank? && resource_model.column_names.include?('updated_at')
+      end
+    end
+  end
+end

data/lib/recourse/helpers/schemes.rb

@@ -0,0 +1,14 @@
+module Recourse
+  module Helpers
+    # The reader's own say in whether a page is light or dark.
+    module Schemes
+    private
+
+      # What the sidebar's toggle needs to flip the mode: where to keep what the reader
+      # picked, so the layout's script can put it back on the next visit.
+      def scheme_data
+        { controller: 'scheme', action: 'scheme#rotate', scheme_storage_value: Recourse::SCHEME_STORAGE }
+      end
+    end
+  end
+end

data/lib/recourse/helpers/searches.rb

@@ -0,0 +1,57 @@
+module Recourse
+  module Helpers
+    # The form above a table: the box, its filters, and the marks a match earns.
+    module Searches
+      # A value with the searched text marked, so a row says why it is in the table.
+      # Only what the search looked through is marked: a word marked in a column
+      # nobody searched would claim a match that never happened. Public because a
+      # row partial of a host's own draws its cells itself and marks them the same.
+      def search_highlight(value, column)
+        term = query_params[resource_search_field]
+        return value if term.blank? || !searched_column?(column)
+
+        highlight value.to_s, term
+      end
+
+    private
+
+      # The form above the table, or nothing at all where the model offers neither
+      # of the two things it holds: a box to type in, and menus to narrow by. Either
+      # earns it — a table with nothing worth searching may still be worth filtering,
+      # and a model whose only columns are an enum and a foreign key is the case.
+      def search_form
+        field = resource_search_field
+        filters = resource_filter_fields
+        return if field.blank? && filters.empty?
+
+        render 'recourses/search', query: resource_search, url: url_for(action: :index),
+                                   field: field, prompt: resource_search_prompt,
+                                   filters: filters, sort: sort_param
+      end
+
+      # The model's search field, less the reach-through a nested route already
+      # answered: a page pinned to one provider offers no box to search them all.
+      def resource_search_field
+        resource_model.search_field except: resource_parent_association
+      end
+
+      def resource_search_prompt
+        resource_model.search_prompt except: resource_parent_association
+      end
+
+      # A foreign key's cell shows a label from the other table, so what decides is
+      # whether the search reaches through that association rather than reads a column.
+      def searched_column?(column)
+        association = belongs_to_association column.to_s
+        return resource_model.recourse_searchable_associations.include? association if association
+
+        resource_model.recourse_searchable_columns.include? column.to_s
+      end
+
+      # The search the action built, under Ransack's own name for one.
+      def resource_search
+        controller_assign 'q'
+      end
+    end
+  end
+end