permission_forge 0.14.1 → 0.15.0

data/app/helpers/permission_forge/sentences_helper.rb

@@ -1,138 +1,153 @@
 module PermissionForge
-  # Plain-language sentences for activation conditions and record rules
-  # (audit events: AuditSentencesHelper; "Review and save" change
-  # descriptions: ChangesHelper).
+  # Plain-language sentences for record rules and resources (activation
+  # conditions: ConditionsHelper; audit events: AuditSentencesHelper;
+  # "Review and save" change descriptions: ChangesHelper).
   #
   # @api private
   module SentencesHelper
-    NULLABLE_OPERATORS = %w[equal not_equal in not_in].freeze
-    LIST_OPERATORS = %w[in not_in].freeze
-    NO_VALUE_OPERATORS = %w[is_null is_not_null].freeze
-    USER_OPERATORS = %w[equal not_equal in not_in is_null is_not_null].freeze
-    CURRENT_USER = 'current_user'.freeze
-
-    # --- activation conditions ------------------------------------------------
-
-    def pf_condition_parts(permission_set)
-      [pf_condition_ips(permission_set), pf_condition_hours(permission_set), pf_condition_flag(permission_set)].compact
-    end
-
-    def pf_condition_ips(permission_set)
-      ips = pf_ip_list(permission_set.allowed_ips)
-      return if ips.empty?
-
-      connector = pf_ui('conditions.or')
-      pf_ui('conditions.from_ips', ips: ips.to_sentence(two_words_connector: connector, last_word_connector: connector))
-    end
-
-    def pf_condition_hours(permission_set)
-      from = permission_set.allowed_hours_start
-      to = permission_set.allowed_hours_end
-      return unless from.present? && to.present?
-
-      key = to.to_i <= from.to_i ? 'hours_overnight' : 'hours'
-      pf_ui("conditions.#{key}", from: pf_hour(from), to: pf_hour(to))
-    end
-
-    def pf_condition_flag(permission_set)
-      flag = permission_set.requires_session_flag
-      pf_flag_phrase(flag) if flag.present?
-    end
-
-    def pf_condition_sentence(permission_set)
-      parts = pf_condition_parts(permission_set)
-      return pf_ui('conditions.always') if parts.empty?
-
-      pf_ui('conditions.only_works', parts: parts.join(', '))
-    end
-
-    def pf_ip_list(value)
-      value.to_s.split(/[,\n]/).map(&:strip).reject(&:empty?)
+    # Resource flags a Muting Permission Set can take away, in the order the page shows them.
+    MUTED_FLAGS = %i[read_access create_access edit_access delete_access].freeze
+
+    # --- resources ------------------------------------------------------------
+
+    # The toast after "Add resource": how many fields it got. In a Muting
+    # Permission Set "with 0 fields" reads like a gap, so there it says what
+    # the resource takes away, or that it takes nothing away yet.
+    def pf_added_resource_notice(resource, muting:)
+      label = pf_resource_label(resource)
+      count = resource.resource_fields.size
+      return t('permission_forge.flash.resources.added', resource: label, count: count) unless muting
+
+      taken = pf_muted_parts(resource, count)
+      return t('permission_forge.flash.resources.added_muting_nothing', resource: label) if taken.empty?
+
+      t('permission_forge.flash.resources.added_muting', resource: label, what: pf_to_sentence(taken))
+    end
+
+    # What a muting resource takes away: its muted flags, then its field rows.
+    def pf_muted_parts(resource, field_count)
+      parts = MUTED_FLAGS.select { |flag| resource.public_send(flag) }.map { |flag| pf_ui("flags_short.#{flag}") }
+      parts << t('permission_forge.flash.resources.muted_fields', count: field_count) if field_count.positive?
+      parts
+    end
+
+    # --- field levels ---------------------------------------------------------
+
+    # What one Permission Set does to a field, by its level (an
+    # Admin::EffectiveAccess::FieldSource): "Sales rep shows this field masked (Email)."
+    # `set_name`: how the set is named (LabelsHelper#pf_chain_set_name on a
+    # person's effective access); the set's name by default.
+    def pf_field_source_sentence(source, set_name: pf_record_name(source.permission_set))
+      strategy = pf_mask_strategy_label(source.mask_strategy)
+      pf_t_markup(set: set_name) { |held| pf_ui("level_sentences.#{source.level}", **held, strategy: strategy) }
+    end
+
+    # A person's Effective access row for a field a Muting Permission Set
+    # decides (FieldOutcome#reason :muted): the level the deciding mutes
+    # give (FieldOutcome#deciding_mutes: hidden, masked or read-only) and
+    # their sets, each named with the Resource whose row mutes
+    # (#pf_field_source_set_name; B#38).
+    def pf_field_muted_by(field, leaf_name)
+      pf_t_markup(set: pf_deciding_mute_names(field, leaf_name)) do |held|
+        case field.blocked_level
+        when 'mask' then t('permission_forge.people.effective_field_source.masked_by', **held)
+        when 'no_edit' then t('permission_forge.people.effective_field_source.read_only_by', **held)
+        else t('permission_forge.people.effective_field_source.muted_by', **held)
+        end
+      end
     end
 
-    def pf_flag_label(flag)
-      configured = PermissionForge.configuration.admin_session_flags || {}
-      configured[flag.to_s] || configured[flag.to_sym] ||
-        t("permission_forge.ui.flags.#{flag}", default: flag.to_s.humanize)
+    # The field drawer's "Explain for" for the same decision: the level and
+    # the same sets as the row (#pf_field_muted_by), counted for the verb.
+    def pf_field_muted_explain(field, leaf_name, person_name)
+      count = field.deciding_mutes.size
+      pf_t_markup(sets: pf_deciding_mute_names(field, leaf_name)) do |held|
+        case field.blocked_level
+        when 'mask' then t('permission_forge.resource_fields.explain.masked_by', name: person_name, count: count, **held)
+        when 'no_edit' then t('permission_forge.resource_fields.explain.read_only_by', name: person_name, count: count, **held)
+        else t('permission_forge.resource_fields.explain.hidden_by', name: person_name, count: count, **held)
+        end
+      end
     end
 
-    def pf_flag_phrase(flag)
-      t("permission_forge.ui.conditions.flags.#{flag}",
-        default: pf_ui('conditions.flag_generic', flag: pf_flag_label(flag)))
+    # The sets of FieldOutcome#deciding_mutes as one list, each named with its Resource.
+    def pf_deciding_mute_names(field, leaf_name)
+      pf_markup_sentence(field.deciding_mutes.map { |source| pf_field_source_set_name(source, leaf_name) })
     end
 
     # --- record rules ---------------------------------------------------------
 
     def pf_operator_label(operator)
-      t("permission_forge.ui.operators.#{operator}", default: operator.to_s.humanize.downcase)
+      t("permission_forge.ui.operators.#{operator}", default: operator.to_s)
     end
 
     # Labels along a rule's relationship path and the final field, e.g.
-    # ["Organization", "Members", "User"].
+    # ["Organization", "Members", "User"]. The path is walked by
+    # Operators::RulePath (the one walk of a path); one it cannot follow is
+    # labelled from its names (a rule that matches nothing is drawn by
+    # RuleProblemsHelper first).
     def pf_rule_field_labels(model_name, rule)
-      klass = model_name.to_s.safe_constantize
-      labels = rule.field_accessor_path.to_s.split('.').map do |assoc|
-        label = pf_attribute_label(klass, assoc)
-        klass = pf_association_class(klass, assoc)
-        label
-      end
-      labels << pf_attribute_label(klass, rule.field_name)
+      segments = PermissionForge::Operators::RuleColumn.path_segments(rule.field_accessor_path)
+      models = pf_rule_path_models(PermissionForge::ModelLookup.model_for(model_name), segments)
+      labels = segments.each_with_index.map { |assoc, index| pf_attribute_label(models[index], assoc) }
+      labels << pf_attribute_label(models[segments.size], rule.field_name)
     end
 
+    # The label of a stored attribute or association name (Admin::FieldLabel),
+    # as text: the host's translation, else the name as stored.
     def pf_attribute_label(klass, attribute)
-      klass ? klass.human_attribute_name(attribute) : attribute.to_s.humanize
+      pf_field_label_text(klass, attribute)
     end
 
-    # Target class of an association, or nil (unknown or polymorphic).
-    def pf_association_class(klass, assoc)
-      reflection = klass&.reflect_on_association(assoc.to_sym)
-      begin
-        reflection&.klass
-      rescue StandardError
-        nil
-      end
+    # The model, then the model of each association on the path; the model
+    # alone when the path cannot be followed (or nothing, without a model).
+    def pf_rule_path_models(klass, segments)
+      return [] unless klass.is_a?(Class) && klass < ActiveRecord::Base
+
+      PermissionForge::Operators::RulePath.follow(klass, segments).models.presence || [klass]
+    rescue *PermissionForge::Operators::RuleColumn::UNTELLABLE
+      [klass]
     end
 
+    # The value as the rule compares it: "the current user" only where
+    # ValueTyping substitutes the user's id (one value compared:
+    # ValueTyping.current_user?); in a list the word is an element as written.
     def pf_rule_value_text(rule)
       value = rule.field_value.to_s
       return '…' if value.strip.empty? # builder preview before a value is entered
-      return pf_ui('rules.current_user') if value == CURRENT_USER
+      return pf_ui('rules.current_user') if PermissionForge::Operators::ValueTyping.current_user?(rule.operator, value)
 
       pf_rule_value_parts(rule.operator, value)
     end
 
-    # List values as "a, b"; ranges as "a and b"; anything else verbatim.
+    # A list's values as "a, b"; a range's ends as "a and b" — split as
+    # ValueTyping splits them (its SHAPES: :list, :pair); anything else verbatim.
     def pf_rule_value_parts(operator, value)
-      return value.split(',').map(&:strip).join(', ') if LIST_OPERATORS.include?(operator)
-      return value.split(',', 2).map(&:strip).join(" #{pf_ui('rules.and')} ") if operator == 'between'
-
-      value
+      parts = PermissionForge::Operators::ValueTyping.split(value)
+      case PermissionForge::Operators::ValueTyping::SHAPES[operator]
+      when :list then parts.join(', ')
+      when :pair then parts.join(" #{pf_ui('rules.and')} ")
+      else value
+      end
     end
 
+    # Whether the sentence adds "or … is empty": the rule includes the NULL
+    # rows and its operator's strategy adds them (Operators::Registry::NULL_INCLUDING).
     def pf_rule_nullable?(rule)
-      rule.include_nulls && NULLABLE_OPERATORS.include?(rule.operator)
+      rule.include_nulls && PermissionForge::Operators::Registry::NULL_INCLUDING.include?(rule.operator)
     end
 
-    # Plural model label. model_name.human(count: 2) falls back to the singular
-    # when the host app has no model translations, so pluralize English then.
-    def pf_resource_plural(name)
-      klass = name.to_s.safe_constantize
-      return name.to_s.demodulize.pluralize unless klass.respond_to?(:model_name)
-
-      plural = klass.model_name.human(count: 2)
-      plural == klass.model_name.human && I18n.locale.to_s == 'en' ? plural.pluralize : plural
-    end
-
-    def pf_resource_label(resource_or_name)
-      name = resource_or_name.respond_to?(:name) ? resource_or_name.name : resource_or_name.to_s
-      return resource_or_name.label if resource_or_name.respond_to?(:label) && resource_or_name.label.present?
-
-      klass = name.safe_constantize
-      klass.respond_to?(:model_name) ? klass.model_name.human : name.demodulize.titleize
+    # Whether the operator takes no value (Operators::Validations::VALUELESS: the null checks).
+    def pf_rule_valueless?(rule)
+      PermissionForge::Operators::Validations.valueless?(rule.operator)
     end
 
-    # Token sentence: Only show [Customers] where [Owner] [is] [the current user], or Owner is empty
+    # Token sentence: Only show [Customers] where [Owner] [is] [the current user], or Owner is empty.
+    # A rule that matches nothing says so, and what it names as written.
     def pf_rule_sentence(rule, model_name = rule.resource&.name)
+      problem = pf_rule_problem(rule)
+      return pf_rule_problem_sentence(rule, problem) if problem
+
       field = pf_rule_field_labels(model_name, rule).join(' › ')
       sentence = safe_join(pf_rule_tokens(rule, model_name, field), ' ')
       sentence = safe_join([sentence, content_tag(:span, ", #{pf_ui('rules.or_empty', field: field)}")]) if pf_rule_nullable?(rule)
@@ -151,24 +166,30 @@ module PermissionForge
     end
 
     def pf_rule_value_token(rule)
-      return if NO_VALUE_OPERATORS.include?(rule.operator)
+      return if pf_rule_valueless?(rule)
 
       content_tag(:span, pf_rule_value_text(rule), class: 'pf-token pf-token--value')
     end
 
     def pf_rule_text(rule, model_name = rule.resource&.name)
+      problem = pf_rule_problem(rule)
+      return pf_rule_problem_line(problem) if problem
+
       field = pf_rule_field_labels(model_name, rule).join(' › ')
       text = "#{pf_ui('rules.only_show')} #{pf_resource_plural(model_name)} #{pf_ui('rules.where')} #{field} " \
              "#{pf_operator_label(rule.operator)}"
-      text += " #{pf_rule_value_text(rule)}" unless NO_VALUE_OPERATORS.include?(rule.operator)
+      text += " #{pf_rule_value_text(rule)}" unless pf_rule_valueless?(rule)
       text += ", #{pf_ui('rules.or_empty', field: field)}" if pf_rule_nullable?(rule)
       text
     end
 
     # Short form used in matrix cells: "Owner is the current user".
     def pf_rule_summary(rule, model_name = rule.resource&.name)
+      problem = pf_rule_problem(rule)
+      return safe_join(['⊘ ', pf_rule_problem_line(problem)]) if problem
+
       field = pf_rule_field_labels(model_name, rule).join(' › ')
-      value = NO_VALUE_OPERATORS.include?(rule.operator) ? nil : pf_rule_value_text(rule)
+      value = pf_rule_valueless?(rule) ? nil : pf_rule_value_text(rule)
       [field, pf_operator_label(rule.operator), value].compact.join(' ')
     end
   end

data/app/helpers/permission_forge/settings_helper.rb

@@ -54,7 +54,7 @@ module PermissionForge
       options << row.value unless options.include?(row.value.to_s)
       pills = options.map do |opt|
         current = opt == row.value.to_s
-        content_tag(:span, opt, class: "pf-pill pf-pill--opt#{' pf-pill--current' if current}", 'aria-current': (current ? 'true' : nil))
+        content_tag(:code, opt, class: "pf-pill pf-pill--opt#{' pf-pill--current' if current}", 'aria-current': (current ? 'true' : nil))
       end
       content_tag(:span, safe_join(pills, ' '), class: 'pf-row pf-row--tight')
     end
@@ -88,7 +88,7 @@ module PermissionForge
       value = row.value
       return content_tag(:span, t('permission_forge.settings.values.empty'), class: 'pf-text-3') if value.blank?
 
-      content_tag(:span, safe_join(value.map { |k, v| content_tag(:span, "#{k} → #{v}") }), class: 'pf-map')
+      content_tag(:span, safe_join(value.map { |k, v| content_tag(:code, "#{k} → #{v}") }), class: 'pf-map')
     end
 
     def pf_setting_secret(row)

data/app/helpers/permission_forge/ui_helper.rb

@@ -6,8 +6,6 @@ module PermissionForge
   #
   # @api private
   module UiHelper
-    STATE_GLYPHS = { granted: '✓', blocked: '⊘', none: '–' }.freeze
-
     # --- assets ---------------------------------------------------------------
 
     def pf_asset_url(file)
@@ -41,6 +39,40 @@ module PermissionForge
       t("permission_forge.ui.#{key}", **)
     end
 
+    # A translation whose interpolated values may be markup (a SafeBuffer:
+    # a name marked as host data) although its key does not end in `_html`:
+    # the block translates with a marker in place of each value, and the
+    # pieces are joined with safe_join — the translation's own text escaped,
+    # the markup kept, nothing marked safe by hand. The `t(...)` stays in the
+    # caller (i18n-tasks sees the key).
+    #
+    #   pf_t_markup(set: pf_host_data(name)) { |held| t('.flag_granted', **held, flag: word) }
+    #
+    # A marker no value was given for (text that happens to hold one, such
+    # as a stored value interpolated as text) is left as written, escaped.
+    #
+    # @yieldparam held [Hash{Symbol => String}] the markers, by value name
+    # @return [ActiveSupport::SafeBuffer]
+    def pf_t_markup(**values)
+      held = values.to_h { |name, _| [name, "\u0001#{name}\u0001"] }
+      by_name = values.transform_keys(&:to_s)
+      pieces = yield(held).to_s.split(/\u0001(\w+)\u0001/)
+      safe_join(pieces.each_with_index.map { |piece, index| index.odd? ? by_name.fetch(piece) { "\u0001#{piece}\u0001" } : piece })
+    end
+
+    # "Bob, Carol and Dan" in the page's language (Admin::ListSentence): never
+    # a bare to_sentence, whose connectors stay English without rails-i18n.
+    def pf_to_sentence(items, **)
+      PermissionForge::Admin::ListSentence.call(items, **)
+    end
+
+    # #pf_to_sentence for items that carry markup (a set named with its
+    # Resource as host data): each item is kept as it is (#pf_t_markup).
+    def pf_markup_sentence(items)
+      values = items.each_with_index.to_h { |item, index| [:"item#{index}", item] }
+      pf_t_markup(**values) { |held| pf_to_sentence(held.values) }
+    end
+
     def pf_people_text(count)
       pf_ui('people_count', count: count)
     end
@@ -79,11 +111,28 @@ module PermissionForge
       format('%02d:00', hour.to_i)
     end
 
+    # --- states (Admin::StateLabel: one registry of glyphs and words) -----------
+
+    # A state (Admin::StateLabel::Label): `.word`, `.glyph`, and `.to_s` for
+    # both — pf_state(:field_level, :none).word → "Not configured",
+    # pf_state(:effective, :blocked).to_s → "⊘ Blocked".
+    def pf_state(kind, state)
+      PermissionForge::Admin::StateLabel.for(kind, state)
+    end
+
+    # The glyph (hidden from assistive technology) and the word of a state
+    # (pf_state), for a cell (`<span class="pf-cell__glyph">`) or a legend
+    # (`glyph_tag: :b`, one space between) that styles the glyph itself.
+    def pf_state_parts(label, glyph_tag: :span, separator: '')
+      glyph = content_tag(glyph_tag, label.glyph, class: ('pf-cell__glyph' if glyph_tag == :span), 'aria-hidden': true)
+      safe_join([glyph, label.word], separator)
+    end
+
     # Read-only state cell (effective access grid, across-sets lists).
     def pf_state_cell(state, aria:, href: nil, why: nil, current: false)
       state = state.to_sym
-      label = pf_ui("states.#{state}")
-      content = safe_join([content_tag(:span, STATE_GLYPHS.fetch(state), class: 'pf-cell__glyph', 'aria-hidden': true),
+      label = pf_state(:effective, state).word
+      content = safe_join([content_tag(:span, pf_state(:effective, state).glyph, class: 'pf-cell__glyph', 'aria-hidden': true),
                            content_tag(:span, label)], ' ')
       opts = { class: "pf-state pf-state--#{state}", 'aria-label': "#{aria}: #{label}" }
       opts[:'aria-current'] = 'true' if current
@@ -135,6 +184,18 @@ module PermissionForge
       content_tag(pf_fragment? ? :h3 : :h2, text, class: 'pf-h3', id: id)
     end
 
+    # A frame that scrolls sideways when its content (a wide grid) is wider than the page: a
+    # tab stop with a name (aria-label, or aria-labelledby on a section), so the keyboard
+    # reaches the region and assistive technology says what scrolls; the stylesheet paints the
+    # cue at its edges and clips what it contains. Every grid 480px or wider goes in one
+    # (html/layout_lint_test.rb).
+    #   <%= pf_scroll_frame('aria-label': t('.label'), class: 'pf-card') do %> … <% end %>
+    #   <%= pf_scroll_frame(tag: :section, 'aria-labelledby': 'pf-changes', class: 'pf-card') do %> … <% end %>
+    def pf_scroll_frame(tag: :div, **options, &)
+      classes = ['pf-scroll-x', options.delete(:class)].compact.join(' ')
+      content_tag(tag, class: classes, role: (tag == :section ? nil : 'region'), tabindex: '0', **options, &)
+    end
+
     # Breadcrumb from [[label, path], ..., label]
     def pf_breadcrumb(*items)
       parts = items.map do |item|

data/app/models/permission_forge/audit_event.rb

@@ -25,6 +25,10 @@ module PermissionForge
     ACTOR_TYPES = PermissionForge::Audit::Actor::TYPES
     SOURCES = PermissionForge::Audit::Source::SOURCES
 
+    # actor_label and record_label name people: #inspect hides them whenever
+    # the application's filters hide a `name` (InspectionFilters).
+    PermissionForge::InspectionFilters.hide_people_labels(self)
+
     # JSON text that works on SQLite, PostgreSQL and MySQL alike; times are
     # written in ISO 8601 (ActiveSupport::JSON), nothing reads as nil.
     #
@@ -68,7 +72,7 @@ module PermissionForge
     # @return [Symbol, nil]
     def self.tenant_column
       column = PermissionForge.configuration.resolved_tenant_column
-      column if column && column_names.include?(column.to_s)
+      column if column && PermissionForge::SchemaRead.column?(self, column.to_s, ignored: false)
     end
 
     # The events of one tenant, on the relation it is called on; every event