recourse 3.0.4 → 4.0.0

data/lib/recourse/helpers/counters.rb

@@ -0,0 +1,75 @@
+module Recourse
+  module Helpers
+    # A counter cache's column in a table: an icon heading over bare figures, or —
+    # where the table is wide enough to read them — the counted model's own words.
+    module Counters
+    private
+
+      # The class a counter's cells carry, which is what sizes the column like the
+      # action columns beside it rather than like the columns carrying text.
+      def counter_class(column)
+        'recourse-counter' if resource_model.recourse_counters.key? column
+      end
+
+      # A figure, and the word saying what it counts. The `aria-label` carries both,
+      # since a link whose whole text is a number announces as `10` and nothing else.
+      # A span where there is no index to link to, so an unlinked count is named the
+      # same as a linked one.
+      def counter_cell(resource, value, association)
+        # Delimited like every other count on the page: the filter menu beside the
+        # table already reads 38,405, and one figure in two spellings reads as two.
+        count = number_with_delimiter value
+        counted = counter_counted count, value, association
+        named = counter_naming count, association
+        path = resource_controller_path
+        nested = nested_path_of path, association
+        return tag.span(counted, **named) unless nested && routed?(nested, 'index')
+
+        turbo_link_to counted, nested_url(resource, path, nested), **named
+      end
+
+      # The two forms of one count, of which a stylesheet ever shows one: the bare
+      # figure where the column is a square, and the figure with the counted model's
+      # own word where the table is wide enough to read it. `count:` is what makes it
+      # `1 place` rather than `1 places`, and `lower:` what leaves it reading as a
+      # phrase. Written out twice rather than as a figure and a suffix, so that each
+      # is a whole thing to show or hide — which is what lets the tooltip ride on the
+      # first of them and keep quiet beside the second.
+      def counter_counted(count, value, association)
+        title = Recourse.model_title association.klass
+        word = Recourse.model_title association.klass, count: value, lower: true
+
+        safe_join [
+          tag.span(count, class: 'recourse-counter-figure', data: tooltip_on_top(title)),
+          tag.span("#{count} #{word}", class: 'recourse-counter-word'),
+        ]
+      end
+
+      # The label reads the figure and the word, which is the order somebody hearing it
+      # needs them in — and it is on the link either way, since nothing is hidden from
+      # a screen reader by a width.
+      def counter_naming(count, association)
+        { aria: { label: "#{count} #{Recourse.model_title association.klass}" } }
+      end
+
+      # Where the counted rows were nested under this resource, read off the routes
+      # rather than joined onto the parent's path: a `namespace` between the two is
+      # part of the address and nothing here would know to put it back.
+      def nested_path_of(path, association)
+        Recourse.nested_under(path).find { |one| one.split('/').last == association.name.to_s }
+      end
+
+      # The icon the sidebar and the breadcrumb already draw for the counted model,
+      # speaking the heading's word to a screen reader — and that word itself, for the
+      # table with room to read it. Exactly one of the two is ever shown, and the icon's
+      # tooltip leaves with the icon: what cannot be hovered repeats nothing.
+      def counter_title(association)
+        title = Recourse.model_title association.klass
+        icon = icon_heading association.klass.recourse_icon, title,
+                            class: 'recourse-counter-icon'
+
+        safe_join [icon, tag.span(title, class: 'recourse-counter-word')]
+      end
+    end
+  end
+end

data/lib/recourse/helpers/deletions.rb

@@ -0,0 +1,87 @@
+module Recourse
+  module Helpers
+    # The button that deletes the record a form is showing, and the warning it puts
+    # in front of whoever clicked it.
+    module Deletions
+      # `dependent:` values that take the children with the parent.
+      DESTROYED = %i[destroy destroy_async].freeze
+
+      # And the one that keeps them, holding the key open. Anything else — a bare
+      # `has_many`, a `:restrict` — is left unsaid rather than guessed at.
+      NULLIFIED = %i[nullify].freeze
+
+    private
+
+      # Deletes the record on the page, or nothing at all where no action is routed
+      # to delete it with — the same two guards the edit link answers to.
+      def destroy_resource_button(record)
+        path = destroy_resource_path record
+        return unless path
+
+        options = {
+          method: :delete, class: 'btn btn-sm btn-solid theme-danger ms-3',
+          form_class: 'd-inline-block', data: { turbo_confirm: destroy_warning(record) },
+        }
+
+        button_to t('recourse.delete', model: resource_name), path, **options
+      end
+
+      # What deleting this record takes with it, counted a level down and no further:
+      # a state reaches counties, then ZIPs, then locations, and counting that far
+      # would join 40,965 rows to draw one page.
+      def destroy_warning(record)
+        lines = [t('recourse.deletion.title', record: destroy_title(record)), nil]
+
+        [*lines, *dependent_lines(record), nil, t('recourse.deletion.undone')].join "\n"
+      end
+
+      def destroy_resource_path(record)
+        return unless routed_action? 'destroy'
+
+        url_for action: :destroy, id: record
+      end
+
+      # The middle of the warning, in the order it reads: what goes, what stays, and
+      # only then what is under what goes — the levels this stops short of counting.
+      def dependent_lines(record)
+        going = dependents record, DESTROYED
+        staying = dependents record, NULLIFIED
+        lines = []
+        lines << t('recourse.deletion.going', list: going.to_sentence) if going.any?
+        lines << staying_line(staying) if staying.any?
+        lines << t('recourse.deletion.under') if going.any?
+
+        lines
+      end
+
+      def staying_line(staying)
+        t 'recourse.deletion.staying', list: staying.to_sentence, model: resource_name
+      end
+
+      def dependents(record, kinds)
+        record.class.reflect_on_all_associations(:has_many).filter_map do |association|
+          next if association.through_reflection || kinds.exclude?(association.options[:dependent])
+
+          dependent_count record, association
+        end
+      end
+
+      # `association.reader` rather than a method named at runtime, and `count` rather
+      # than loading them: the warning needs how many, never which.
+      def dependent_count(record, association)
+        count = record.association(association.name).reader.count
+        return if count.zero?
+
+        name = Recourse.downcase association.klass.model_name.human
+
+        "#{number_with_delimiter count} #{name.pluralize count}"
+      end
+
+      # What the record is called, or what it is, for one that answers to no label.
+      def destroy_title(record)
+        record.attributes[record.class.recourse_label.to_s].presence ||
+          record.class.model_name.human
+      end
+    end
+  end
+end

data/lib/recourse/helpers/details.rb

@@ -0,0 +1,41 @@
+module Recourse
+  module Helpers
+    # What a value is drawn behind when it is worth more room than a page will give it
+    # unasked: closed to begin with, so a column of values stays a column of values.
+    module Details
+    private
+
+      # The shape itself, said once: what the thing is, and the thing under it. A
+      # picture and a list are both this, and neither should be spelling it out.
+      def detailed(summary, body)
+        tag.details { safe_join [tag.summary(summary), body] }
+      end
+
+      # A list reads as how many first — the values are what opening it is for — and
+      # then as the values themselves. Nil rather than an empty `<details>` where there
+      # is nothing in it, so an empty list reads as the dash every other empty value
+      # reads as rather than as a summary with nothing behind it.
+      def listed(values)
+        count = listed_count values
+        return unless count
+
+        detailed count, listed_items(values)
+      end
+
+      # How many a list holds, and nothing else: what a table shows in place of the
+      # values, and what the summary above reads before anybody opens it. Nil for an
+      # empty one, which reads as blank in a cell and as the dash on a record's page.
+      def listed_count(values)
+        return if values.blank?
+
+        t 'recourse.items', count: values.size
+      end
+
+      # `mb-0`, because the row below it draws the rule between them and a list's own
+      # bottom margin would push that rule away from the values it closes.
+      def listed_items(values)
+        tag.ul safe_join(values.map { |one| tag.li one }), class: 'mb-0 mt-2'
+      end
+    end
+  end
+end

data/lib/recourse/helpers/examples.rb

@@ -0,0 +1,35 @@
+module Recourse
+  module Helpers
+    # Reads an example of an accepted value off the pattern that accepts it.
+    module Examples
+      # One token of a pattern and the `{n}` that may repeat it, so `\d{5}` reads
+      # as a single digit five times over rather than as five separate characters.
+      # `\d`, a bracket class and a literal are all it knows; nothing else is used.
+      PATTERN_TOKENS = /(\\d|\[[^\]]*\]|[^{])(?:\{(\d+),?\d*\})?/
+
+      # A token that is a bracket class, so `[2-9]` counts as one rather than five.
+      CLASS_TOKEN = /\A\[/
+
+      # First character a bracket class offers, past the bracket and any negation.
+      CLASS_SAMPLE = /[^\[^]/
+
+    private
+
+      # What the pattern accepts, so a field can name the shape it wants instead of
+      # only reporting that what was typed is wrong.
+      def pattern_example(pattern)
+        tokens = pattern.scan PATTERN_TOKENS
+
+        tokens.map { |token, count| pattern_sample(token) * (count || 1).to_i }.join
+      end
+
+      def pattern_sample(token)
+        case token
+        when '\d' then '0'
+        when CLASS_TOKEN then token[CLASS_SAMPLE]
+        else token
+        end
+      end
+    end
+  end
+end

data/lib/recourse/helpers/fields.rb

@@ -0,0 +1,78 @@
+module Recourse
+  module Helpers
+    # Chooses the form field a column deserves, and labels it.
+    module Fields
+    private
+
+      # One labelled field in the form's grid. `label:` overrides the heading and
+      # `type:` overrides the input the column would otherwise have chosen.
+      def field(name, **options)
+        column = name.to_s
+        label = options.fetch :label, reference_title(column, belongs_to_association(column))
+
+        tag.div class: ROW do
+          safe_join [
+            @recourse_form.label(column, label, class: 'form-label'),
+            resource_field(@recourse_form, column, type: options[:type]),
+            field_comment(column),
+          ].compact
+        end
+      end
+
+      # What the database says the column is for, under the field that sets it.
+      def field_comment(column)
+        field_note resource_model.recourse_comment(column), field_note_id(column)
+      end
+
+      # What the control points at, where it should point at anything. Only where there
+      # is a note to point at — and only where the field has nothing more urgent to say,
+      # since an error outranks a hint. `field_error_proc` is the host's and writes its
+      # own `aria-describedby` for an invalid field, so rather than leave a second one
+      # for the browser to throw away, this one stands down and says so here.
+      def field_described(column)
+        return if resource_model.recourse_comment(column).blank?
+        return if errors_on(column).any?
+
+        field_note_id column
+      end
+
+      # Named off the field's own id, the way Rails names everything else about it.
+      def field_note_id(column)
+        id = @recourse_form.field_id column
+
+        "#{id}_help"
+      end
+
+      # The line under a field saying what somebody wants to know before filling it in:
+      # what the column is for. Nothing at all where there is nothing to say.
+      #
+      # `mt-1` because Bootstrap's `.form-text` declares `--bs-form-text-margin-top` and
+      # never applies it; `.25rem` is what that variable holds, so this is the gap the
+      # class already meant. `fg-secondary` for a line that answers a question nobody
+      # asked — quieter than the value it sits under, and quieter than `.form-text`'s
+      # own `--bs-fg-2`, which a utility later in the cascade is what overrides.
+      def field_note(text, id)
+        tag.div text, class: 'form-text mt-1 fg-secondary', id: id if text.present?
+      end
+
+      # A field typed by what the column holds, not merely a text box.
+      def resource_field(form, column, type: nil)
+        association = belongs_to_association column
+        return reference_field form, column, association if association
+
+        # Rails mirrors `maxlength` into `size`, which would shrink the box to it.
+        aria = { describedby: field_described(column) }
+        options = { class: 'form-control', size: nil, aria: }.merge field_html(column, type)
+
+        return form.text_field column, **options, type: type if type
+        return form.email_field column, **options if column == 'email'
+
+        kind_field form, column, **options
+      end
+
+      def encrypted_column?(column)
+        resource_model.recourse_encrypted_names.include? column
+      end
+    end
+  end
+end

data/lib/recourse/helpers/filters.rb

@@ -0,0 +1,91 @@
+module Recourse
+  module Helpers
+    # The menus beside a search box: one per foreign key a table can be narrowed by,
+    # and one per column whose values are a known few.
+    module Filters
+    private
+
+      # The filters this page draws, as the markup each one is. A declared filter
+      # that draws nothing falls out here — a foreign key whose label is typed
+      # rather than picked — so what is left is what a form would hold, which is
+      # what decides whether there is a form at all.
+      def resource_filter_fields
+        resource_filters.filter_map { |predicate, options| filter_field predicate, **options }
+      end
+
+      # The model's filters, less the one a nested route already answered:
+      # /markets/1/sectors is filtered by market_id in the URL itself, and a menu
+      # for it would only offer to re-ask — or to contradict — the address.
+      def resource_filters
+        parent = resource_parent_association
+        filters = resource_model.filter_fields
+        return filters unless parent
+
+        filters.except "#{parent.foreign_key}_in"
+      end
+
+      # One filter: the values a column of its own admits, or a menu of the records a
+      # foreign key points at, holding whichever the request already asked for.
+      def filter_field(predicate, label: nil, scope: nil)
+        column = predicate.to_s.sub Search::LIST_PREDICATES, ''
+
+        choice_filter(predicate, column, label) || reference_filter(predicate, column, label, scope)
+      end
+
+      # A menu of the records a foreign key points at. Nothing where that key is typed
+      # rather than picked, which is the same question the field beside it asks: the
+      # label is bounded, or the table is too long to list. Either way the menu would
+      # be a table of its own. A `scope:` draws one anyway.
+      def reference_filter(predicate, column, label, scope)
+        association = belongs_to_association column
+        return if association.nil? ||
+                  (scope.nil? && association.klass.recourse_typed_reference?)
+
+        filter_combobox predicate, label || reference_title(column, association),
+                        (scope || association.klass).all
+      end
+
+      def filter_combobox(predicate, title, recourses)
+        label = recourses.klass.recourse_label
+        counter = filter_counter recourses.klass
+        # What it reads as when nothing is ticked, so the way back is a line in the menu.
+        models = Recourse.model_title recourses.klass, lower: true
+
+        filter_menu predicate, title, nil, t('recourse.all', models: models),
+                    label: label.to_s, counter: counter,
+                    recourses: filter_options(recourses, label, counter)
+      end
+
+      # The commonest choice first where the model keeps a count, since a menu is read
+      # from the top and most requests want the option most rows are behind — and by
+      # name where it keeps none. The name breaks ties, or two markets on the same
+      # number would swap places between one request and the next.
+      def filter_options(recourses, label, counter)
+        return recourses.select(:id, label).order label unless counter
+
+        recourses.select(:id, label, counter).order counter => :desc, label => :asc
+      end
+
+      # The column on the model a filter lists that counts the rows being filtered —
+      # `markets.zips_count` on `/zips`. Read from the counter caches that model keeps
+      # rather than from a column named after this one, so a `zips_count` nobody
+      # maintains is not a count.
+      def filter_counter(klass)
+        klass.recourse_counters.find { |_, one| one.klass == resource_model }&.first
+      end
+
+      # Never invalid and never required: a filter narrows rather than sets.
+      def filter_menu(predicate, title, values, all, **)
+        render('recourses/combobox', name: "q[#{predicate}]", id: "q_#{predicate}",
+                                     placeholder: title, multiple: true, aria_label: title,
+                                     selected: filter_values(predicate), small: true,
+                                     all: all, values: Array(values), **)
+      end
+
+      # A multiple combobox submits one comma-joined input, read back out the same way.
+      def filter_values(predicate)
+        query_params[predicate].to_s.split ','
+      end
+    end
+  end
+end

data/lib/recourse/helpers/formats.rb

@@ -0,0 +1,94 @@
+module Recourse
+  module Helpers
+    # How one attribute reads on a page that only reads it.
+    module Formats
+      # One absolute web address and nothing else: a value to follow, not to read.
+      # Anything around it — words, a second address — reads as text instead. What it
+      # captures is what a link says: the host, less any `www.`, and whatever follows.
+      WEB_URL = %r{\Ahttps?://(?:www\.)?([^/?#\s]+)(\S*)\z}
+
+    private
+
+      # What the record says for one column, formatted by what the column holds.
+      def formatted_value(column)
+        association = belongs_to_association column
+        return named_cell resource_record, association if association
+
+        formatted_attribute column, resource_record.attributes[column]
+      end
+
+      # One value, formatted by the kind its column holds — the one ladder a table
+      # cell and a show page's value both come down, so a boolean is the same icon
+      # and an enum the same badge on either. A block, where the caller has one,
+      # marks the search terms inside whichever arm ends up as words.
+      def formatted_attribute(column, value, &)
+        kind = attribute_kind column
+        return listed Array(value) if kind == :list
+        return formatted_number kind, column, value if numeric_kind? kind
+
+        formatted_text kind, value, &
+      end
+
+      def formatted_number(kind, column, value)
+        return uncounted kind, value if Kinds::UNCOUNTED_KINDS.include? kind
+
+        case kind
+        when :integer then number_with_delimiter value
+        when :phone then number_to_phone value
+        when :monetary then number_to_currency value, **precision_option(column)
+        when :percentage then number_to_percentage value, **precision_option(column)
+        when :decimal then number_with_precision value, **precision_option(column)
+        else number_with_precision value
+        end
+      end
+
+      def formatted_text(kind, value, &)
+        case kind
+        when :enum then value && enum_badge(marked(value, &))
+        when :date, :datetime, :time then value && localized(kind, value)
+        when *Kinds::JSON_KINDS then value.presence && json_block(value)
+        else linked_or_marked(value, &)
+        end
+      end
+
+      # One whole web address is a value to follow rather than to read, and anything
+      # else is words — which the caller may have marking of its own for.
+      def linked_or_marked(value, &)
+        web_url?(value) ? url_link(value) : marked(value, &)
+      end
+
+      # The caller's own marking, where it has one: a table marks what a search
+      # matched, and a show page, which no search reached, has nothing to mark.
+      def marked(value, &)
+        block_given? ? yield(value) : value
+      end
+
+      # A payload read as the JSON it is rather than as the Hash Ruby prints. In a block
+      # of its own that scrolls rather than grows: one of these is as tall as a page, and
+      # nothing else on a record's page should have to move aside for it. `presence`, so
+      # an empty payload reads as the dash every other empty value does.
+      def json_block(value)
+        tag.pre JSON.pretty_generate(value), class: 'recourse-payload'
+      end
+
+      def enum_badge(value)
+        tag.span value, class: 'badge'
+      end
+
+      def web_url?(value)
+        value.is_a?(String) && value.match?(WEB_URL)
+      end
+
+      # Bootstrap's icon link, saying the value leads somewhere the way text cannot.
+      # What it reads is the host, and an ellipsis where the address goes further --
+      # a path is how a machine finds the page, and the href is already carrying it.
+      def url_link(value)
+        host, rest = value.match(WEB_URL).captures
+        said = rest.delete_suffix('/').empty? ? host : "#{host}/…"
+
+        tag.a safe_join([said, icon_tag(:point_right)], ' '),
+              href: value, class: 'icon-link icon-link-hover'
+      end
+    end
+  end
+end

data/lib/recourse/helpers/inputs.rb

@@ -0,0 +1,92 @@
+module Recourse
+  module Helpers
+    # The control an attribute is typed into, chosen by what the attribute holds.
+    module Inputs
+      # Numbers a field takes whole. A month and a year are counted in no smaller unit
+      # than themselves, so neither admits the decimals a `step` would otherwise allow.
+      WHOLE_KINDS = %i[integer month year].freeze
+
+    private
+
+      # A field for a column whose kind is what decides it, the fallback being a text
+      # box for anything that never said what it holds. The checkbox is handed one
+      # option by name rather than the whole hash: the rest is `maxlength`, `pattern`,
+      # `placeholder`, `inputmode` and `required`, none of which a box that is either
+      # ticked or not has any use for.
+      def kind_field(form, column, **options)
+        kind = attribute_kind column
+        return numeric_field(form, column, kind, **options) if numeric_kind? kind
+        return menu_field form, column, kind if menu_kind? kind
+
+        case kind
+        when :boolean then tag.div form.check_box(column, class: 'check', aria: options[:aria])
+        when :date then form.date_field(column, **options)
+        when :datetime then form.datetime_local_field(column, **options)
+        when :text, :list then area_field(form, column, kind, **options)
+        else form.text_field(column, **options)
+        end
+      end
+
+      # A list is typed one value to a line, a newline being the one separator a value
+      # cannot itself contain. Handed its value, since a box left to read an Array off
+      # the record would print the brackets.
+      def area_field(form, column, kind, **)
+        return form.text_area(column, **, rows: 1) if kind == :text
+
+        values = Array form.object&.attributes&.fetch(column, nil)
+        form.text_area column, **, rows: 3, value: values.join("\n")
+      end
+
+      # `step` is what limits a field to whole numbers, and what admits the decimals a
+      # column keeps: two of them for a `scale: 2`, any number at all for a float,
+      # which says how precise it is nowhere.
+      def numeric_field(form, column, kind, **)
+        return form.telephone_field(column, **) if kind == :phone
+        return adorned_field(form, column, **) if %i[monetary percentage].include? kind
+
+        form.number_field(column, **, **step_options(column, kind))
+      end
+
+      def step_options(column, kind)
+        return { step: 1 } if WHOLE_KINDS.include? kind
+
+        scale = attribute_scale column
+        return { step: :any } unless scale
+
+        { step: 10.0**-scale, max: digit_ceiling(column, scale) }
+      end
+
+      # Bootstrap adorns a control by wrapping it: the border and the padding are the
+      # wrapper's, the input inside is a `.form-ghost` with neither, and
+      # `.form-adorn-end` is what moves the unit to the far side of it.
+      def adorned_field(form, column, **options)
+        end_ = attribute_kind(column) == :percentage
+        classes = ['form-control form-adorn d-flex', ('form-adorn-end' if end_)].compact
+        unit = tag.span adorn_unit(end_), class: 'form-adorn-text'
+
+        tag.div class: classes.join(' ') do
+          safe_join [unit, adorned_input(form, column, **options)]
+        end
+      end
+
+      def adorned_input(form, column, **)
+        form.number_field(column, **, class: 'form-ghost',
+                                      **step_options(column, attribute_type(column)))
+      end
+
+      # The currency the app counts in, which is what its number formats already say.
+      def adorn_unit(percentage)
+        percentage ? '%' : I18n.t('number.currency.format.unit', default: '$')
+      end
+
+      # The largest value the column has room for: `precision: 4, scale: 2` keeps four
+      # digits of which two are decimals, so 99.99 and nothing above it.
+      def digit_ceiling(column, scale)
+        precision = attribute_precision column
+        return unless precision
+
+        (10.0**(precision - scale)) - (10.0**-scale)
+      end
+    end
+  end
+end