recourse 3.0.3 → 4.0.0

data/lib/recourse/engine.rb

@@ -1,20 +1,40 @@
-# A module to manage administered resources.
-module Recourse
-  # Common acronyms
-  ACRONYMS = %w[API CRM OpenAI PIN URL ZIP]
+# rails/engine alone raises NoMethodError: railtie.rb calls delegate_missing_to too early.
+require 'rails'
+
+require_relative 'routes'
 
-  # Makes Recourse methods like `recourses` available in config/routes.rb
+module Recourse
+  # Hooks the gem into a host app's boot so its controllers and views are found.
   class Engine < ::Rails::Engine
-    initializer 'recourse.inflections' do
-      ActiveSupport::Inflector.inflections do |inflect|
-        ACRONYMS.each { |acronym| inflect.acronym acronym }
-      end
+    # Prefix the gem answers for with a file. `Rack::Static` matches on
+    # `start_with?`, so dropping the slash would swallow `/recourses` itself.
+    STATIC_URLS = %w[/recourse/].freeze
+
+    # Initializers all run before routes are drawn, so `recourses` exists in time.
+    initializer 'recourse.routes' do
+      ActionDispatch::Routing::Mapper.include Scopes, Routes
     end
 
-    config.to_prepare do
-      require 'recourse/routing'
-      require 'recourse/recoursive'
-      require 'recourse/searchable'
+    # Serves what a page needs, since a host may run no asset pipeline at all. The
+    # prefix keeps its slash: without it `/recourses` would be served as a file.
+    # Turbo answers first, by exact path — matched on the prefix alone, the statics
+    # below would swallow it with a 404 instead of passing it on. Then vendored
+    # files, cascading so our own JavaScript shares the URL. All of it sits before
+    # `Rails::Rack::Logger`, so fetching a stylesheet writes no `Started GET` line:
+    # a file is not what a log is about, and placement says so without the gem
+    # touching a host's logging.
+    initializer 'recourse.assets' do |app|
+      # turbo-rails' own bundle: the same Turbo plus the cable element, in the
+      # version that gem signs its streams for. A dependency rather than something
+      # to find, since a page here cannot do without it.
+      app.middleware.insert_before Rails::Rack::Logger, Rack::Static,
+                                   urls: { '/recourse/turbo.min.js' => 'turbo.min.js' },
+                                   root: Turbo::Engine.root.join('app/assets/javascripts').to_s
+      app.middleware.insert_before Rails::Rack::Logger, Rack::Static,
+                                   urls: STATIC_URLS, root: Engine.root.join('vendor'),
+                                   cascade: true
+      app.middleware.insert_before Rails::Rack::Logger, Rack::Static,
+                                   urls: STATIC_URLS, root: Engine.root.join('app/javascript')
     end
   end
 end

data/lib/recourse/helpers/actions.rb

@@ -0,0 +1,56 @@
+module Recourse
+  module Helpers
+    # The action columns a row opens with: a look at a record, then a change to it.
+    module Actions
+      # The two pages a record has, named as the concepts an icon set knows rather
+      # than as one set's own word for them, so what draws them is Unicon's business
+      # here as everywhere else. A row's links and a card's tabs read the same map,
+      # so the two cannot drift apart — and its order is the order a row opens with.
+      ICONS = { show: :view, edit: :edit }.freeze
+
+    private
+
+      # Which of those two this table draws a column for. Read into a local by the
+      # table, so the routes are asked once per render rather than twice for the
+      # heading and twice more for every row.
+      def resource_actions
+        ICONS.keys.select { |action| resource_action? action }
+      end
+
+      # An action column's heading: the icon on the header row — the column is as
+      # narrow as the icon in it, with no room for a word — and the action's own
+      # word in every other, which is what each `data-cell` labels itself with.
+      def action_header(action)
+        label = t "recourse.#{action}"
+        return label unless @recourse_headers
+
+        icon_heading ICONS[action], label
+      end
+
+      # Whether a record's own page is there to be linked to, wherever its routes
+      # were drawn: a nested table's rows lead to the resource's own pages, the ones
+      # a nested route leaves to it, so the columns are the same either way.
+      def resource_action?(action)
+        routed_action? action.to_s, resource_controller_path
+      end
+
+      # The icon linking to one of those pages, or nothing where the page is not
+      # routed. Which of the two it is, is the whole difference between them.
+      def resource_action_link(action, record)
+        path = resource_action_path action, record
+        return unless path
+
+        turbo_link_to icon_tag(ICONS[action]), path, aria: { label: t("recourse.#{action}") }
+      end
+
+      # Named by controller rather than by action alone: on a nested page the two
+      # differ, and a bare `action:` would look for the member route the nesting
+      # does not draw.
+      def resource_action_path(action, record)
+        return unless resource_action? action
+
+        url_for controller: "/#{resource_controller_path}", action: action, id: record
+      end
+    end
+  end
+end

data/lib/recourse/helpers/bookmarks.rb

@@ -0,0 +1,88 @@
+module Recourse
+  module Helpers
+    # The bookmark a table's first column carries: one square per row, hollow where
+    # the viewer has not kept it and filled where they have.
+    module Bookmarks
+    private
+
+      # How this model's bookmarks point back at it, or nil where it keeps none and
+      # the column is not drawn at all. Looked up once per render, like the model.
+      def resource_bookmarks
+        return @resource_bookmarks if defined? @resource_bookmarks
+
+        @resource_bookmarks = Recourse.bookmarks_for resource_model
+      end
+
+      # The rows this viewer has kept, read once for the page rather than a query a
+      # row: a page is twenty rows and the answer is one integer column.
+      def bookmarked_ids
+        @bookmarked_ids ||= Recourse.bookmarks_of(resource_bookmarks)
+                                    .pluck(resource_bookmarks.foreign_key).to_set
+      end
+
+      # What the table's cache key carries for the bookmarks, and nil where there are
+      # none. The rows are the model's own and never change when a bookmark does, so
+      # without this a fragment drawn before the last click outlives it — and the
+      # ids are the viewer's, so this is also what keeps one agent's icons off
+      # another's page. The name leads because an expanded key renders `nil` and `[]`
+      # alike.
+      def bookmark_digest
+        [:bookmarked, *bookmarked_ids.to_a.sort] if resource_bookmarks
+      end
+
+      # The class that tints a kept row, and nothing at all where the viewer has not
+      # kept it — or where this model keeps none, since `bookmarked_ids` has no column
+      # to read then. The square already says which rows are theirs, and says it to a
+      # reader who cannot see a tint; this is what a page of twenty is scanned by.
+      def bookmark_row_class(record)
+        'recourse-kept' if resource_bookmarks && bookmarked_ids.include?(record.id)
+      end
+
+      # The column's heading: the hollow square on the header row — the column is as
+      # narrow as the icon in it — and the word on every other, which is what each
+      # `data-cell` labels itself with, the way an action column's does.
+      def bookmark_header
+        label = t 'recourse.bookmark'
+        return label unless @recourse_headers
+
+        icon_heading :bookmark, label
+      end
+
+      # Kept or not, one square either way: the same path with the verb reversed, so
+      # the button toggles by flipping the method Rails already wrote into the form.
+      def bookmark_button(record)
+        kept = bookmarked_ids.include? record.id
+        label = t "recourse.#{kept ? 'unbookmark' : 'bookmark'}"
+
+        button_to bookmark_icon(kept, label), bookmark_url(record),
+                  method: kept ? :delete : :post, form_class: 'd-inline-block',
+                  class: 'btn btn-sm btn-link p-0 border-0 lh-1',
+                  **bookmark_data(kept, label)
+      end
+
+      def bookmark_icon(kept, label)
+        icon_tag kept ? :bookmarked : :bookmark, label:
+      end
+
+      # What the Stimulus controller flips, and the wording it cannot look up itself:
+      # a `.js` file has no `t`, so the message it may have to show travels with it.
+      def bookmark_data(kept, label)
+        # No tooltip, unlike every other icon here. This one is in every row rather
+        # than in a heading, and a label that follows the cursor down a column of
+        # squares is noise — the `aria-label` still names it for a reader who cannot
+        # see which way the square is filled.
+        data = {
+          controller: 'bookmark', bookmark_kept_value: kept,
+          bookmark_error_value: t('recourse.bookmark_error'),
+        }
+
+        { aria: { label:, pressed: kept }, data: }
+      end
+
+      def bookmark_url(record)
+        url_for controller: "/#{resource_controller_path}/bookmarks", action: :create,
+                "#{resource_model.model_name.singular}_id": record.id
+      end
+    end
+  end
+end

data/lib/recourse/helpers/buttons.rb

@@ -0,0 +1,65 @@
+module Recourse
+  module Helpers
+    # The buttons a record's pages carry: an action the routes drew under it that has
+    # no page of its own for a link to sit on.
+    module Buttons
+    private
+
+      # A nested resource routed `create` without an `index` is reached from nowhere, so
+      # its button lives on the record it hangs off — beside the breadcrumbs. Which of
+      # that record's pages is the host's business as much as the button is: the
+      # routes say where it goes as well as whether it exists.
+      def bare_action_buttons(record)
+        Recourse.nested_under(card_path).filter_map do |nested|
+          next unless bare_action_page? nested
+
+          bare_action_button record, nested
+        end
+      end
+
+      # Whether this is that page. An index is a page to reach the action from and a
+      # `new` is a form to fill in on the way: either one means there is more to this
+      # than a button. A nesting with no page anywhere stands on the record's own page,
+      # since every other page of the record is about something else — a place's memos
+      # are not where a sweep of the place is offered.
+      def bare_action_page?(nested)
+        return false if routed?(nested, 'index') || routed?(nested, 'new')
+
+        record_page?
+      end
+
+      # The one page every record has, which is where a pageless action's button goes.
+      def record_page?
+        !resource_parent && controller.action_name == 'show'
+      end
+
+      # The `create` the routes drew on the collection, which needs no id: a member
+      # action wants the row it acts on, and a row is what a table is for.
+      def bare_action_button(record, nested)
+        return unless routed? nested, 'create'
+
+        [bare_action_label(nested), bare_action_url(record, nested), :post]
+      end
+
+      # The resource's own word, which a host renames in a locale like any other
+      # model: `Add Jobber retrieval` rather than `Add booking exchange`. Led by
+      # whatever namespace the routes put between the record and the action, because
+      # that is the only thing telling two routes to the same model apart — without it
+      # a `quick/memos` action and the `memos` beside it both read `Add memo`. The tab
+      # for a nested index is named from the same split, so the two agree.
+      def bare_action_label(nested)
+        name, namespace = nested_segments nested, card_path
+        model = Recourse.downcase Recourse.known_singular(name)
+        lead = namespace_words namespace
+
+        t 'recourse.add', model: [lead.presence, model].compact.join(' ')
+      end
+
+      def bare_action_url(record, nested)
+        parent = card_path.split('/').last.singularize
+
+        url_for controller: "/#{nested}", action: :create, "#{parent}_id": record.id
+      end
+    end
+  end
+end

data/lib/recourse/helpers/cards.rb

@@ -0,0 +1,67 @@
+module Recourse
+  module Helpers
+    # The tabs on the card a record's pages share: a look, a change, and each
+    # nested index under the record — counted where the record keeps a count.
+    module Cards
+    private
+
+      # The pages of the record the card is about, as `[label, path, current]` — a
+      # look first, a change second, then one tab per nested index: `8 ZIPs` where
+      # a counter cache answers, the bare `Settings` where none does. On a nested
+      # index the card is the parent record's, so the tabs are too, and the nested
+      # tab is the current one.
+      def resource_tabs(record)
+        path = card_path
+        actions = %i[show edit].filter_map { |action| action_tab record, path, action }
+
+        actions + nested_tabs(record, path)
+      end
+
+      # The resource the card belongs to: the parent's, on a page nested under it —
+      # read off the routes rather than chopped off this page's own path, which a
+      # `namespace` between the two would leave pointing at the namespace.
+      def card_path
+        return Recourse.parent_of controller.controller_path if resource_parent
+
+        controller.controller_path
+      end
+
+      def action_tab(record, path, action)
+        return unless routed? path, action.to_s
+
+        [
+          tab_label(action), url_for(controller: "/#{path}", action:, id: record),
+          current_action_tab?(action),
+        ]
+      end
+
+      # `update` redraws the form it rejected, so the edit tab is current there too.
+      # On a nested page neither is: the count tab is the page being read.
+      def current_action_tab?(action)
+        return false if resource_parent
+
+        action == (controller.action_name == 'show' ? :show : :edit)
+      end
+
+      # One tab per resource nested under the record, in the order routes.rb nested
+      # them — the order the sidebar already keeps. The nested index is the whole
+      # requirement: a `has_many` of that name decides how the tab reads, and a counter
+      # cache whether it carries a number, but neither is what puts it there. A nesting
+      # with no index is an action, and its button stands beside the breadcrumbs instead.
+      def nested_tabs(record, path)
+        Recourse.nested_under(path).filter_map do |nested|
+          next unless routed? nested, 'index'
+
+          name, namespace = nested_segments nested, path
+
+          [nested_tab_label(record, name, namespace), nested_url(record, path, nested),
+           nested == controller.controller_path,]
+        end
+      end
+
+      def tab_label(action)
+        safe_join [icon_tag(Actions::ICONS[action]), t("recourse.#{action}")], ' '
+      end
+    end
+  end
+end

data/lib/recourse/helpers/cells.rb

@@ -0,0 +1,89 @@
+module Recourse
+  module Helpers
+    # Helpers for the cells of a table and the fields of a form.
+    module Cells
+      # One cell: a heading in the header row, the block's output in every other.
+      # Public because a row partial of a host's own is written out of these, and
+      # is rendered once for the header row and once for each row after it.
+      def column(header:, **, &)
+        return tag.th(header, scope: :col, **) if @recourse_headers
+
+        tag.td(capture(&), 'data-cell': header, **)
+      end
+
+    private
+
+      # Columns the table shows: every attribute that is not encrypted and not
+      # read-only, less the primary key — an id is how a row is addressed, not
+      # something to read about it — in the order `Recourse.ordered` reads a row,
+      # which is what leaves the counts last of all, past even the timestamps.
+      def resource_columns
+        Recourse.ordered resource_model, resource_model.column_names - hidden_columns
+      end
+
+      # What no table shows, less whatever the model asked to draw anyway. Each of
+      # the four below is a default the gem picks, and a host is what answers for
+      # its own screens — so naming one overrules it.
+      def hidden_columns
+        columns_hidden_by_default - Array(resource_model.recourse_displayed).map(&:to_s)
+      end
+
+      # Ciphertext, the id that addresses the row, the parent a nested route already
+      # names, the timestamps and every JSON payload — what a machine keeps rather than
+      # what a row is about — and whatever the model asked to hide, the one of these a
+      # host decides without the override above.
+      def columns_hidden_by_default
+        [
+          resource_model.recourse_encrypted_names, resource_model.primary_key, TIMESTAMPS,
+          resource_parent_association&.foreign_key, json_columns,
+          Recourse.hidden_columns(resource_model),
+        ].flatten.compact
+      end
+
+      # Columns a form offers — less the parent a nested route has already
+      # answered: a comment under `/posts/2` is for post 2, not for one picked
+      # from a menu, so no field asks.
+      def editable_columns
+        Recourse.editable_columns(resource_model) - Array(resource_parent_association&.foreign_key)
+      end
+
+      # Columns the show page reads out: what the form offers, what the model draws
+      # anyway, and the timestamps last — a computed column is read where it is not typed.
+      def shown_columns
+        drawn = Array(resource_model.recourse_displayed).map(&:to_s) - TIMESTAMPS
+        (editable_columns + drawn).uniq + (TIMESTAMPS & resource_model.column_names)
+      end
+
+      # Heading for a column, which a host app can translate like any attribute. A
+      # counter is headed with what it counts — `ZIPs`, not `ZIPs count` — since the
+      # column holds a number and the heading says what the number is of.
+      def resource_column_title(column)
+        counted = resource_model.recourse_counters[column]
+        return resource_model.human_attribute_name column unless counted
+
+        Recourse.model_title counted.klass
+      end
+
+      # Value for one cell, formatted according to what the column holds.
+      def resource_cell(resource, column)
+        association = belongs_to_association column
+        return search_highlight named_cell(resource, association), column if association
+
+        value = resource.attributes[column]
+        counted = resource_model.recourse_counters[column]
+
+        # A count is the bare number — the icon in the heading already says what it
+        # counts — linking to the counted rows where a block nested their index here.
+        return counter_cell resource, value, counted if counted
+
+        # A list is counted rather than drawn: the values are the record's own page to
+        # read out, and a column of them inside a column of them is not a table.
+        return listed_count value if attribute_kind(column) == :list
+
+        # The same ladder the show page comes down, with the search's own marking
+        # handed in: a table is the only page a search ever reached.
+        formatted_attribute(column, value) { |text| search_highlight text, column }
+      end
+    end
+  end
+end

data/lib/recourse/helpers/choices.rb

@@ -0,0 +1,49 @@
+module Recourse
+  module Helpers
+    # The filter menus whose options are values rather than records: what a column
+    # itself admits, read off the model rather than out of another table.
+    module Choices
+    private
+
+      # The values a column admits of itself, where it admits a known set of them:
+      # an enum's words, or a boolean's two. Nil for anything else, which is what
+      # hands the question on to the key it might be.
+      def choice_filter(predicate, column, label)
+        return enum_filter predicate, column, label if resource_model.defined_enums.key? column
+
+        boolean_filter predicate, column, label if boolean_column? column
+      end
+
+      # The two a boolean admits, as the words a table already prints for them. The
+      # way back is the bare `All`: a column called `signed` pluralizes to nothing
+      # anybody would write, so the line says what it does rather than what it is of.
+      def boolean_filter(predicate, column, label)
+        title = label || resource_model.human_attribute_name(column)
+
+        filter_menu predicate, title, %w[true false], t('recourse.all_values')
+      end
+
+      def boolean_column?(column)
+        resource_model.column_names.include?(column) &&
+          resource_model.type_for_attribute(column).type == :boolean
+      end
+
+      # A menu of the words the column admits, which are the words the form's own menu
+      # offers and the badge on a show page reads. Headed by the attribute rather than
+      # by a model, since a status is the table's own and not another table's.
+      def enum_filter(predicate, column, label)
+        title = label || resource_model.human_attribute_name(column)
+        values = resource_model.defined_enums[column].keys
+
+        filter_menu predicate, title, values, choices_all(title)
+      end
+
+      # The way back to no filter at all, named after what the menu is of: `All
+      # statuses`, `All CRMs`. An acronym keeps its capitals, the way every title
+      # the gem lower-cases does.
+      def choices_all(title)
+        t 'recourse.all', models: Recourse.downcase(title).pluralize
+      end
+    end
+  end
+end

data/lib/recourse/helpers/colors.rb

@@ -0,0 +1,20 @@
+module Recourse
+  module Helpers
+    # The primary color, where a host has named one.
+    module Colors
+    private
+
+      # The `:root` block that makes `Recourse.color` the primary one, or nothing at all
+      # where no color is named — Bootstrap's own blue is already there, and a palette
+      # names its own lead accent in its own file. It wins on being later rather than on
+      # being more specific, every selector being `:root`, so it belongs after both the
+      # stylesheet link and the palette's, and never before either.
+      def primary_color_style
+        color = Recourse.color
+        return unless color
+
+        render 'recourses/color', color: color, ink: Recourse.ink(color)
+      end
+    end
+  end
+end

data/lib/recourse/helpers/comboboxes.rb

@@ -0,0 +1,87 @@
+module Recourse
+  module Helpers
+    # The menu a foreign key offers when its label is too long to be typed.
+    module Comboboxes
+    private
+
+      # A combobox of labels. The query fetches the two columns the menu shows and
+      # nothing else, and the errors are its own work: `field_error_proc` only ever
+      # sees the tags a form builder drew, and this is a partial.
+      def combobox(form, column, association)
+        label = association.klass.recourse_label
+
+        render 'recourses/combobox', **combobox_locals(form, column),
+                                     label: label.to_s,
+                                     recourses: combobox_options(association.klass, label)
+      end
+
+      # Whichever menu a kind whose values are known in advance is drawn as.
+      def menu_field(form, column, kind)
+        kind == :enum ? enum_combobox(form, column) : zone_combobox(form, column)
+      end
+
+      # The words an enum admits, as a menu of one. The values are the model's own, so
+      # nothing here has to know what any of them mean.
+      def enum_combobox(form, column)
+        render 'recourses/combobox', **combobox_locals(form, column),
+                                     values: resource_model.defined_enums[column].keys,
+                                     selected: [form.object.attributes[column]].compact
+      end
+
+      # Whether a menu's rows can be kept, which turns on the one thing a relation is
+      # versioned by: `cache` reads `MAX(updated_at)` off the table without asking
+      # whether there is such a column, and a model Rails keeps no timestamps on has
+      # none to read. Reference data is exactly where that happens — a table of states
+      # or of postal codes is written by a migration and never again — so those menus
+      # are drawn each time rather than kept under a key nothing can version.
+      def keepable_menu?(recourses)
+        recourses.klass.column_names.include? 'updated_at'
+      end
+
+      # What every combobox needs to know about the column it sets, whatever it offers
+      # as choices: the enum one asks for these too, and gives `values:` instead.
+      def combobox_locals(form, column)
+        messages = errors_on column
+        required = required? resource_model, column
+
+        {
+          name: form.field_name(column), id: form.field_id(column), invalid: messages.any?,
+          feedback: messages.to_sentence.upcase_first.presence,
+          described: combobox_described(form, column, messages),
+          placeholder: combobox_placeholder(column), required: required,
+          # A menu of records can say which one; only this can say none of them, and
+          # a key that may be nothing has to be settable back to it.
+          none: (t 'recourse.unset' unless required),
+          selected: combobox_selected(form, column),
+        }
+      end
+
+      # What the toggle points at: its own error where it has one, and otherwise the
+      # note under it. The same order of precedence every other control follows.
+      def combobox_described(form, column, messages)
+        id = form.field_id column
+        return "#{id}_error" if messages.any?
+
+        field_described column
+      end
+
+      # What the record already holds, as the menu spells its values: an id for a
+      # foreign key and the word itself for an enum. Without it a form opens on the
+      # placeholder however full the record is — and the plugin's hidden input opens
+      # empty with it, so saving would write that emptiness back.
+      def combobox_selected(form, column)
+        value = form.object&.attributes&.fetch column.to_s, nil
+
+        Array(value).map(&:to_s)
+      end
+
+      def combobox_options(klass, label)
+        klass.select(:id, label).order label
+      end
+
+      def combobox_placeholder(column)
+        placeholder(resource_model, column, nil) || t('recourse.select')
+      end
+    end
+  end
+end

data/lib/recourse/helpers/constraints.rb

@@ -0,0 +1,92 @@
+module Recourse
+  module Helpers
+    # Turns a model's validators into the HTML that constrains a form field.
+    module Constraints
+      # Shown for a field whose shape has one canonical example.
+      SAMPLE_PLACEHOLDERS = { 'phone' => '555-555-5555', 'email' => 'michael@example.com' }.freeze
+
+      # What the browser checks where the typed shape differs from the stored one: a
+      # phone is ten digits in the database but is typed with its separators.
+      DISPLAY_PATTERNS = { 'phone' => '[2-9]\d{2}-[2-9]\d{2}-\d{4}' }.freeze
+
+      # Hands a phone field to the Stimulus controller that types its separators.
+      PHONE_CONTROLLER = {
+        controller: 'phone', action: 'keydown->phone#down input->phone#input',
+      }.freeze
+
+    private
+
+      # Browser-side constraints, every one read from the validators of `model` —
+      # which is the page's model unless a field asks about another one's attribute.
+      def field_html(column, type = nil, model = resource_model)
+        key = (type || column).to_s
+        pattern = DISPLAY_PATTERNS[key] || column_pattern(model, column)
+
+        {
+          maxlength: length_option(model, column, :maximum),
+          minlength: length_option(model, column, :minimum), pattern:,
+          title: title(key, pattern), placeholder: placeholder(model, column, type),
+          inputmode: (:numeric if numeric? model, column, pattern),
+          required: (true if required? model, column),
+          data: (PHONE_CONTROLLER if key == 'phone'),
+        }.compact
+      end
+
+      # The canonical sample where the field has one, so the title agrees with the
+      # placeholder; otherwise a shape read off the pattern itself.
+      def title(key, pattern)
+        return unless pattern
+
+        t 'recourse.format', example: SAMPLE_PLACEHOLDERS[key] || pattern_example(pattern)
+      end
+
+      def length_option(model, column, bound)
+        length_options(model, column).values_at(bound, :is).compact.first
+      end
+
+      def length_options(model, column)
+        validator(model, column, ActiveModel::Validations::LengthValidator)&.options || {}
+      end
+
+      # An HTML pattern is anchored already, so \A and \z come off the Ruby one.
+      def column_pattern(model, column)
+        shape = validator model, column, ActiveModel::Validations::FormatValidator
+        regexp = shape&.options&.dig :with
+        return unless regexp
+
+        regexp.source.delete_prefix('\A').delete_suffix '\z'
+      end
+
+      # An explicit type states what the field is, so it picks the sample; without
+      # one a required field shows the shape it expects and an optional one says so.
+      def placeholder(model, column, type)
+        sample = SAMPLE_PLACEHOLDERS[(type || column).to_s]
+        return sample if sample && (type || required?(model, column))
+
+        t 'recourse.optional' unless required? model, column
+      end
+
+      def required?(model, column)
+        Recourse.validated_names(column).any? { |name| presence_validated? model, name }
+      end
+
+      def presence_validated?(model, attribute)
+        validator(model, attribute, ActiveModel::Validations::PresenceValidator).present?
+      end
+
+      def numeric?(model, column, pattern)
+        digits_only?(pattern) ||
+          validator(model, column, ActiveModel::Validations::NumericalityValidator).present?
+      end
+
+      # `\d` carries a letter, so it has to go before looking for real ones.
+      def digits_only?(pattern)
+        pattern.present? && !pattern.gsub('\d', '').match?(/[A-Za-z]/)
+      end
+
+      def validator(model, attribute, kind)
+        model.validators_on(attribute).find { |one| one.is_a? kind }
+      end
+    end
+  end
+end