querylane 0.1.0 → 0.2.0

data/config/locales/querylane.en.yml

@@ -59,8 +59,33 @@ en:
       more:
         one: "+1 more"
         other: "+%{count} more"
+    # Query errors (Querylane::Query::MESSAGES holds the same English as defaults).
+    # Values a user typed are interpolated; a sensitive value never is.
     errors:
       parked: "%{key}: is not available yet."
+      unknown_operator: "%{key}: is not an operator."
+      did_you_mean: "%{key}: is not an operator. Did you mean %{suggestion}:?"
+      filter_value: "\"%{value}\" is not a valid %{key}: value."
+      filter_value_hidden: "That value is not a valid %{key}: value."
+      flag_value: "%{value} is not a value of %{key}:. Try %{values}."
+      text_in_or: "OR joins operators, not names. Search one name at a time."
+      text_in_not: "- and NOT apply to operators, not names."
+      text_in_group: "Parentheses group operators, not names."
+      one_text_operator: "Search %{operators} one at a time, or combine with %{filters}."
+      one_text_operator_alone: "Search %{operators} one at a time."
+      # Joins the operator and filter lists of the two messages above.
+      list_or: " or "
+      too_long: "Search is too long (%{max} characters at most)."
+      close_quote: "Close the quote."
+      needs_value: "%{key}: needs a value."
+      unexpected: "Unexpected %{text}."
+      or_needs_terms: "OR needs a term on both sides."
+      needs_term: "%{operator} needs a term."
+      ended_early: "Search ended early."
+      too_deep: "Too many nested parentheses (%{max} at most)."
+      close_parenthesis: "Add the closing )."
+      empty_parentheses: "Empty parentheses."
+      too_many_terms: "Too many terms (%{max} at most)."
     group:
       more:
         one: "1 more record for this person"
@@ -107,6 +132,7 @@ en:
     facets:
       find: "Find a %{facet}…"
       find_label: "Find a %{facet} value"
+      label: "Filters"
       note: "Counts are records. Ticking more boxes in one group widens the search (OR); the counts beside unticked boxes show what they would add. Different groups narrow (AND)."
       unavailable: "Counts unavailable"
     help:
@@ -124,6 +150,7 @@ en:
       widen: "Search all %{facet}"
       drop: "Drop %{label}"
       relax: "Allow fewer name matches"
+      as_words: "Search \"%{value}\" as part of a name"
       empty_note: "Each button changes the search box, so the new search is visible."
       empty: "No matching records found"
       unavailable_title: "Search is not answering right now."

data/lib/querylane/chips.rb

@@ -6,9 +6,11 @@ module Querylane
   # sensitive value in clear.
   module Chips
     # alternatives: other readings of an interpreted term ("Division 5432 instead");
-    # words: the chip of the query's words (names), not a filter.
-    Chip = Data.define(:index, :label, :ranges, :alternatives, :words) do
-      def initialize(index:, label:, ranges:, alternatives: [], words: false)
+    # words: the chip of the query's words (names), not a filter;
+    # as_words: for a filter whose operator opts in (`as_words: true`), the
+    # value as typed, which an empty search offers to search as plain words.
+    Chip = Data.define(:index, :label, :ranges, :alternatives, :words, :as_words) do
+      def initialize(index:, label:, ranges:, alternatives: [], words: false, as_words: nil)
         super
       end
     end
@@ -29,13 +31,25 @@ module Querylane
       query.nodes.each do |node|
         next if node.is_a?(Query::Term) && node.kind == :text
 
-        chips << [label(node), [node.range], alternatives(query, node)]
+        chips << [label(node), [node.range], alternatives(query, node), false, as_words(query, node)]
       end
-      chips.each_with_index.map do |(text, ranges, others, words), index|
-        Chip.new(index: index, label: text, ranges: ranges, alternatives: others || [], words: words || false)
+      chips.each_with_index.map do |(text, ranges, others, words, typed), index|
+        Chip.new(index: index, label: text, ranges: ranges, alternatives: others || [], words: words || false, as_words: typed)
       end
     end
 
+    # The typed value of a top-level filter term whose operator offers it as
+    # plain words (never a sensitive one: the definition refuses that), or nil.
+    # Not offered while another text operator holds the words (one per query).
+    def as_words(query, node)
+      return unless node.is_a?(Query::Term) && node.kind == :filter && node.operator.as_words && !node.interpreted
+      return if query.text_operator && !query.text_operator.equal?(query.definition.default_text)
+
+      typed = node.raw.to_s.strip.presence
+      # Offered only when the rewritten query still runs (length and term limits).
+      typed if typed && Query.analyze(query.definition, Rewriter.words_in_place(query, node.range, typed), config: query.config).valid?
+    end
+
     # Other readings of an interpreted term, each with the explicit text it
     # would become (e.g. "div:5432").
     def alternatives(query, node)
@@ -63,7 +77,7 @@ module Querylane
 
     def term_label(term)
       case term.kind
-      when :filter then format(term.operator, mask(term.value, term.operator.mask))
+      when :filter then format(term.operator, mask(filter_value(term), term.operator.mask))
       when :flag then "#{term.operator.label} #{term.operator.values.fetch(term.value)}"
       when :text then format(term.operator, term.value)
       end
@@ -71,6 +85,9 @@ module Querylane
 
     def format(operator, value) = operator.label.gsub("%{value}", value.to_s)
 
+    # The value a filter chip shows: normalized, or as typed (`display_value: :typed`).
+    def filter_value(term) = (term.operator.display_value == :typed && !term.interpreted) ? term.raw.to_s : term.value.to_s
+
     # @param value [String]
     # @param mask [Symbol] :none, :all, :last4, :count
     def mask(value, mask)

data/lib/querylane/configuration.rb

@@ -5,6 +5,7 @@ module Querylane
   #
   #   Querylane.configure do |config|
   #     config.searcher = -> { Querylane::Searchers::Meilisearch.new(client: MeilisearchService.client) }
+  #     config.logger = Rails.logger
   #   end
   class Configuration
     # Name of the query parameter (filtered from logs by the engine).
@@ -18,6 +19,10 @@ module Querylane
 
     attr_writer :searcher
 
+    # Where querylane writes why a search could not run. A host passes its
+    # own (Rails.logger); without one querylane logs to standard output.
+    attr_writer :logger
+
     # How long a group token ("more records", preview) stays valid.
     attr_accessor :group_token_ttl
 
@@ -35,8 +40,12 @@ module Querylane
       @debounce_ms = 300
       @allow_get_query = false
       @searcher = nil
+      @logger = ActiveSupport::Logger.new($stdout)
     end
 
+    # @return [Logger]
+    attr_reader :logger
+
     # The searcher for this request. A callable is resolved on every call, so
     # it can follow code reloading and per-request clients.
     #

data/lib/querylane/copy.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Querylane
+  # Host-supplied copy that may be a locale key or plain text: a panel row's
+  # `hint:` and `placeholder:`, a filter's `invalid:` sentence. Resolved when
+  # shown (never when the definition is built), so a memoized definition still
+  # follows the current locale.
+  #
+  #   Copy.text(:"search.hints.name")        # => I18n.t("search.hints.name")
+  #   Copy.text("search.hints.name")         # => the same (a dotted key)
+  #   Copy.text("Exact last name, any case") # => as given
+  module Copy
+    # A dotted locale key: no spaces, at least one dot between word parts.
+    KEY = /\A[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)+\z/
+
+    module_function
+
+    # @param value [String, Symbol, nil] a locale key or text
+    # @return [String, nil] the translation for a key, the text otherwise
+    def text(value)
+      case value
+      when nil then nil
+      when Symbol then I18n.t(value)
+      else value.to_s.match?(KEY) ? I18n.t(value.to_s) : value.to_s
+      end
+    end
+  end
+end

data/lib/querylane/definition.rb

@@ -17,7 +17,16 @@ module Querylane
   class Definition
     Index = Data.define(:key, :name)
     Text = Data.define(:key, :attributes, :sensitive, :default, :label, :mask)
-    FilterOperator = Data.define(:key, :attribute, :sensitive, :normalize, :format, :label, :mask)
+    # invalid: a second sentence for the bad-value error (locale key or text);
+    # as_words: an empty search offers to search the value as plain words;
+    # display_value: :normalized (chips and the panel show the normalized value) or
+    # :typed (they show the value as typed).
+    FilterOperator = Data.define(:key, :attribute, :sensitive, :normalize, :format, :label, :mask, :invalid, :as_words, :display_value) do
+      # The newer members default, so code built for the earlier members still works.
+      def initialize(key:, attribute:, sensitive:, normalize:, format:, label:, mask:, invalid: nil, as_words: false, display_value: :normalized)
+        super
+      end
+    end
     Flags = Data.define(:key, :aliases, :attribute, :values, :rules, :label)
     # values: for a flag facet, the flag values it shows (nil: all of them).
     # top: filter-facet values loaded; show: how many show before "Find…";
@@ -44,7 +53,14 @@ module Querylane
     # values: for a :flags row, the flag values it shows (nil: all of them).
     # masked: an operator in the row masks its values (mask other than :none):
     # the field starts empty and hides what is typed.
-    PanelRow = Data.define(:label, :keys, :kind, :bare, :masked, :values) do
+    # hint: a line under the row; placeholder: the empty inputs' placeholder
+    # (each a locale key or text, see Querylane::Copy).
+    PanelRow = Data.define(:label, :keys, :kind, :bare, :masked, :values, :hint, :placeholder) do
+      # hint and placeholder default, so code built for the earlier members still works.
+      def initialize(label:, keys:, kind:, bare:, masked:, values:, hint: nil, placeholder: nil)
+        super
+      end
+
       # @return [String] the compose field name (unique per row, also when two
       #   rows show different values of one flag family)
       def name
@@ -63,6 +79,7 @@ module Querylane
       strip: ->(value) { value.strip }
     }.freeze
     MASKS = %i[none all last4 count].freeze
+    DISPLAYS = %i[normalized typed].freeze
 
     attr_reader :name, :indexes, :texts, :filters, :flags, :facets, :sorts, :per_options, :retrieve, :highlight, :hooks, :group,
       :saved_store, :min_text_length, :parked
@@ -228,11 +245,14 @@ module Querylane
       [nil, rows]
     end
 
-    # [label, [[row_label, keys, {bare:}], ...]] → PanelGroup, checked against the operators
+    # [label, [[row_label, keys, bare, values, hint, placeholder], ...]] → PanelGroup,
+    # checked against the operators
     def build_group((label, rows))
-      PanelGroup.new(label, rows.map do |row_label, keys, bare, values|
+      PanelGroup.new(label, rows.map do |row_label, keys, bare, values, hint, placeholder|
         if keys.all? { |key| option(key) }
-          PanelRow.new(row_label, keys, :options, false, false, nil)
+          raise ConfigurationError, "#{@name}: panel row #{row_label} takes placeholder: only for inputs" if placeholder
+
+          PanelRow.new(row_label, keys, :options, false, false, nil, hint, nil)
         else
           operators = keys.map { |key| operator(key) || raise(ConfigurationError, "#{@name}: panel field #{key} is not an operator or option") }
           kind = operators.all?(Flags) ? :flags : :inputs
@@ -242,8 +262,10 @@ module Querylane
           raise ConfigurationError, "#{@name}: panel row #{row_label} takes values: only for flags" if values && kind != :flags
           unknown = Array(values) - ((kind == :flags) ? operators.first.values.keys : [])
           raise ConfigurationError, "#{@name}: panel row #{row_label} has unknown values #{unknown.join(", ")}" if unknown.any?
+          raise ConfigurationError, "#{@name}: panel row #{row_label} takes placeholder: only for inputs" if placeholder && kind != :inputs
 
-          PanelRow.new(row_label, keys, kind, bare, operators.any? { |operator| operator.respond_to?(:mask) && operator.mask != :none }, values)
+          masked = operators.any? { |operator| operator.respond_to?(:mask) && operator.mask != :none }
+          PanelRow.new(row_label, keys, kind, bare, masked, values, hint, placeholder)
         end
       end.freeze)
     end
@@ -394,12 +416,22 @@ module Querylane
 
       # An exact-match operator. `normalize` runs before `format` is checked.
       # `mask` controls how chips show sensitive values: :none, :all, :last4, :count.
-      def filter(key, attribute:, sensitive: false, normalize: nil, format: nil, label: nil, mask: nil)
+      # `invalid` (locale key or text) follows "… is not a valid key: value."
+      # as a second sentence. `as_words: true` lets an empty search offer the
+      # value as plain words. `display_value: :typed` shows the value as typed in
+      # chips and the options panel (the search still uses the normalized value).
+      def filter(key, attribute:, sensitive: false, normalize: nil, format: nil, label: nil, mask: nil, invalid: nil, as_words: false,
+        display_value: :normalized)
         normalizer = normalize.is_a?(Symbol) ? NORMALIZERS.fetch(normalize) : normalize
         mask ||= sensitive ? :all : :none
         raise ConfigurationError, "Unknown mask #{mask}" unless MASKS.include?(mask)
+        raise ConfigurationError, "Unknown display_value #{display_value}" unless DISPLAYS.include?(display_value)
+        raise ConfigurationError, "filter #{key}: display_value: :typed needs mask: :none" if display_value == :typed && mask != :none
+        # The link would repeat the value in clear.
+        raise ConfigurationError, "filter #{key}: as_words cannot be sensitive" if as_words && sensitive
 
-        @filters << FilterOperator.new(key.to_sym, attribute.to_s, sensitive, normalizer, format, label || "#{key.to_s.humanize} %{value}", mask)
+        @filters << FilterOperator.new(key.to_sym, attribute.to_s, sensitive, normalizer, format, label || "#{key.to_s.humanize} %{value}", mask,
+          invalid, as_words ? true : false, display_value)
       end
 
       # A family of named values (`is:active`). Either `attribute:` (value
@@ -439,8 +471,10 @@ module Querylane
       # A labelled row of operators (or option keys). `bare: true` gives the
       # operators one shared input written without a prefix.
       # `values:` limits a flags row to some of its values (the rest stay in the box).
-      def row(label, *keys, bare: false, values: nil)
-        @rows << [label, keys.map(&:to_sym), bare, values&.map(&:to_sym)]
+      # `hint:` is a line under the row; `placeholder:` sits in the row's empty
+      # inputs (inputs rows only). Each is a locale key or text (Querylane::Copy).
+      def row(label, *keys, bare: false, values: nil, hint: nil, placeholder: nil)
+        @rows << [label, keys.map(&:to_sym), bare, values&.map(&:to_sym), hint, placeholder]
       end
     end
   end

data/lib/querylane/parser.rb

@@ -40,7 +40,7 @@ module Querylane
 
     def parse
       if @source.length > @config.max_length
-        raise Error.new("Search is too long (#{@config.max_length} characters at most).", 0...@source.length)
+        raise Error.new(message(:too_long, max: @config.max_length), 0...@source.length)
       end
 
       @tokens = tokenize
@@ -73,7 +73,7 @@ module Querylane
       elsif scanner.scan(/-(?=[^\s)])/) then token(:minus, scanner, start)
       elsif scanner.scan(KEY) then key_token(scanner, start, scanner[1])
       elsif scanner.scan(QUOTED) then token(:term, scanner, start, value: unescape(scanner[1]), quoted: true)
-      elsif scanner.scan('"') then raise Error.new("Close the quote.", start...@source.length)
+      elsif scanner.scan('"') then raise Error.new(message(:close_quote), start...@source.length)
       else
         scanner.scan(BARE)
         token(:term, scanner, start, value: scanner.matched)
@@ -86,7 +86,7 @@ module Querylane
       elsif scanner.scan(BARE)
         token(:term, scanner, start, key: key, value: scanner.matched)
       else
-        raise Error.new("#{key}: needs a value.", start...scanner.charpos)
+        raise Error.new(message(:needs_value, key: key), start...scanner.charpos)
       end
     end
 
@@ -99,7 +99,7 @@ module Querylane
     def parse_sequence(closing:)
       nodes = []
       until done? || (closing && peek?(:rparen))
-        raise Error.new("Unexpected ).", current.range) if peek?(:rparen)
+        raise Error.new(message(:unexpected, text: ")"), current.range) if peek?(:rparen)
 
         nodes << parse_or
       end
@@ -110,7 +110,7 @@ module Querylane
       parts = [parse_unary]
       while peek?(:or)
         operator = advance
-        raise Error.new("OR needs a term on both sides.", operator.range) if done? || peek?(:rparen) || peek?(:or)
+        raise Error.new(message(:or_needs_terms), operator.range) if done? || peek?(:rparen) || peek?(:or)
 
         parts << parse_unary
       end
@@ -122,7 +122,7 @@ module Querylane
     def parse_unary
       if peek?(:minus) || peek?(:not)
         operator = advance
-        raise Error.new("#{(operator.type == :not) ? "NOT" : "-"} needs a term.", operator.range) if done?
+        raise Error.new(message(:needs_term, operator: (operator.type == :not) ? "NOT" : "-"), operator.range) if done?
 
         node = parse_atom
         return Ast::Not.new(node, operator.range.begin...node.range.end)
@@ -131,24 +131,24 @@ module Querylane
     end
 
     def parse_atom
-      raise Error.new("Search ended early.", @source.length...@source.length) if done?
+      raise Error.new(message(:ended_early), @source.length...@source.length) if done?
 
       case current.type
       when :lparen then parse_group
-      when :or then raise Error.new("OR needs a term on both sides.", current.range)
+      when :or then raise Error.new(message(:or_needs_terms), current.range)
       when :term then parse_term
-      else raise Error.new("Unexpected #{@source[current.range]}.", current.range)
+      else raise Error.new(message(:unexpected, text: @source[current.range]), current.range)
       end
     end
 
     def parse_group
       open = advance
       @depth += 1
-      raise Error.new("Too many nested parentheses (#{@config.max_depth} at most).", open.range) if @depth > @config.max_depth
+      raise Error.new(message(:too_deep, max: @config.max_depth), open.range) if @depth > @config.max_depth
 
       nodes = parse_sequence(closing: true)
-      raise Error.new("Add the closing ).", open.range.begin...@source.length) unless peek?(:rparen)
-      raise Error.new("Empty parentheses.", open.range) if nodes.empty?
+      raise Error.new(message(:close_parenthesis), open.range.begin...@source.length) unless peek?(:rparen)
+      raise Error.new(message(:empty_parentheses), open.range) if nodes.empty?
 
       close = advance
       @depth -= 1
@@ -158,11 +158,14 @@ module Querylane
     def parse_term
       term = advance
       @terms += 1
-      raise Error.new("Too many terms (#{@config.max_terms} at most).", term.range) if @terms > @config.max_terms
+      raise Error.new(message(:too_many_terms, max: @config.max_terms), term.range) if @terms > @config.max_terms
 
       Ast::Term.new(term.key&.downcase, term.value, term.quoted, term.range)
     end
 
+    # Syntax errors share Query's localized messages (`querylane.errors.*`).
+    def message(name, **values) = Query.message(name, **values)
+
     def current = @tokens[@position]
 
     def advance

data/lib/querylane/presenter.rb

@@ -30,7 +30,13 @@ module Querylane
         super
       end
     end
-    Group = Data.define(:key, :hits)
+    # lead: the hit that placed the group on the page (the first of its hits
+    # to come back, in the page's sort); hits may be reordered after it.
+    Group = Data.define(:key, :hits, :lead) do
+      def initialize(key:, hits:, lead: hits.first)
+        super
+      end
+    end
     # A group in suggestions: a short detail, its status, and what choosing it
     # does (an Action opens it; nil runs the full search).
     Suggestion = Data.define(:detail, :badge, :action)
@@ -87,7 +93,8 @@ module Querylane
     # @return [String] the id of the group's "more records" frame
     def related_frame_id(group) = "#{id}-related-#{record_key(group.hits.first)}"
 
-    # @return [Array<Group>] in hit order, the best-ranked hit leading each group
+    # @return [Array<Group>] in hit order: each group sits where its first hit
+    #   came back (best-ranked, or first in the chosen sort), which leads it
     def groups
       order = []
       grouped = {}
@@ -96,12 +103,15 @@ module Querylane
         order << key unless grouped.key?(key)
         (grouped[key] ||= []) << hit
       end
-      order.map { |key| Group.new(key, order_records(grouped.fetch(key))) }
+      order.map do |key|
+        hits = grouped.fetch(key)
+        Group.new(key: key, hits: order_records(hits), lead: hits.first)
+      end
     end
 
     # A group's records in the definition's group order (the order "more
-    # records" and the preview use); unchanged without one. The best-ranked
-    # record still decides where the group sits on the page.
+    # records" and the preview use); unchanged without one. The lead record
+    # still decides where the group sits on the page and what it is called.
     def order_records(hits)
       order = result.definition.group&.order
       return hits if order.nil? || hits.one?
@@ -120,10 +130,12 @@ module Querylane
       0
     end
 
-    # Group heading (HTML-safe); default: the first highlighted text attribute.
+    # Group heading (HTML-safe); default: the lead record's first highlighted
+    # text attribute, so headings follow the page's order (Name A–Z reads in
+    # name order even when one person's records carry different names).
     def title(group)
       attribute = result.definition.highlight.first
-      view.querylane_highlight(group.hits.first, attribute)
+      view.querylane_highlight(group.lead, attribute)
     end
 
     # Secondary heading next to the title (HTML-safe or plain), or nil.

data/lib/querylane/query.rb

@@ -14,6 +14,9 @@ module Querylane
 
     attr_reader :definition, :source, :nodes, :error
 
+    # @return [Querylane::Configuration] the limits the query was read with
+    attr_reader :config
+
     # @param definition [Querylane::Definition]
     # @param source [String]
     # @return [Querylane::Query]
@@ -21,6 +24,41 @@ module Querylane
       new(definition, source.to_s, config)
     end
 
+    # English defaults of `querylane.errors.*` (the locale file repeats them).
+    MESSAGES = {
+      parked: "%{key}: is not available yet.",
+      unknown_operator: "%{key}: is not an operator.",
+      did_you_mean: "%{key}: is not an operator. Did you mean %{suggestion}:?",
+      filter_value: "\"%{value}\" is not a valid %{key}: value.",
+      filter_value_hidden: "That value is not a valid %{key}: value.",
+      flag_value: "%{value} is not a value of %{key}:. Try %{values}.",
+      text_in_or: "OR joins operators, not names. Search one name at a time.",
+      text_in_not: "- and NOT apply to operators, not names.",
+      text_in_group: "Parentheses group operators, not names.",
+      one_text_operator: "Search %{operators} one at a time, or combine with %{filters}.",
+      one_text_operator_alone: "Search %{operators} one at a time.",
+      list_or: " or ",
+      too_long: "Search is too long (%{max} characters at most).",
+      close_quote: "Close the quote.",
+      needs_value: "%{key}: needs a value.",
+      unexpected: "Unexpected %{text}.",
+      or_needs_terms: "OR needs a term on both sides.",
+      needs_term: "%{operator} needs a term.",
+      ended_early: "Search ended early.",
+      too_deep: "Too many nested parentheses (%{max} at most).",
+      close_parenthesis: "Add the closing ).",
+      empty_parentheses: "Empty parentheses.",
+      too_many_terms: "Too many terms (%{max} at most)."
+    }.freeze
+
+    # A query error message in the current locale.
+    #
+    # @param name [Symbol] a key of MESSAGES (`querylane.errors.<name>`)
+    # @return [String]
+    def self.message(name, **values)
+      I18n.t("querylane.errors.#{name}", **values, default: MESSAGES.fetch(name))
+    end
+
     def valid? = error.nil?
 
     def blank? = source.strip.empty?
@@ -67,6 +105,7 @@ module Querylane
     def initialize(definition, source, config)
       @definition = definition
       @source = source
+      @config = config
       @nodes = []
       @error = nil
       root = Parser.parse(source, config: config)
@@ -106,7 +145,7 @@ module Querylane
       end
       return text_term(definition.default_text, value, term, context, interpreted) if key.nil?
 
-      raise Invalid.new(I18n.t("querylane.errors.parked", key: key, default: "%{key}: is not available yet."), term.range) if definition.parked.include?(key.to_s.downcase)
+      raise Invalid.new(message(:parked, key: key), term.range) if definition.parked.include?(key.to_s.downcase)
 
       operator = definition.operator(key) || raise(unknown_key(key, term))
       resolve_operator(operator, value, term, context, interpreted)
@@ -121,22 +160,18 @@ module Querylane
     end
 
     def text_term(operator, value, term, context, interpreted)
-      if context
-        message = {
-          or: "OR joins operators, not names. Search one name at a time.",
-          not: "- and NOT apply to operators, not names.",
-          group: "Parentheses group operators, not names."
-        }.fetch(context)
-        raise Invalid.new(message, term.range)
-      end
+      raise Invalid.new(message(:"text_in_#{context}"), term.range) if context
+
       Term.new(:text, operator, value, term.quoted, term.range, interpreted, term.value)
     end
 
     def filter_term(operator, value, term, interpreted)
-      normalized = operator.normalize ? operator.normalize.call(value) : value
+      # A copy: a normalizer that edits its argument must not change the typed value.
+      normalized = operator.normalize ? operator.normalize.call(value.dup) : value
       if operator.format && !operator.format.match?(normalized)
-        shown = operator.sensitive ? "That value" : "\"#{value}\""
-        raise Invalid.new("#{shown} is not a valid #{operator.key}: value.", term.range)
+        # A sensitive value is never repeated, not even to the host's copy.
+        text = operator.sensitive ? message(:filter_value_hidden, key: operator.key) : message(:filter_value, key: operator.key, value: value)
+        raise Invalid.new([text, Copy.text(operator.invalid)].compact.join(" "), term.range)
       end
       Term.new(:filter, operator, normalized, term.quoted, term.range, interpreted, term.value)
     end
@@ -144,7 +179,7 @@ module Querylane
     def flag_term(operator, value, term, interpreted)
       symbol = value.to_s.downcase.to_sym
       unless operator.values.key?(symbol)
-        raise Invalid.new("#{value} is not a value of #{operator.key}:. Try #{operator.values.keys.join(", ")}.", term.range)
+        raise Invalid.new(message(:flag_value, key: operator.key, value: value, values: operator.values.keys.join(", ")), term.range)
       end
       Term.new(:flag, operator, symbol, term.quoted, term.range, interpreted, term.value)
     end
@@ -154,19 +189,26 @@ module Querylane
       return if operators.size <= 1
 
       second = text_terms.find { |term| term.operator == operators.last }
-      others = definition.filters.map { |filter| "#{filter.key}:" }.first(2).join(" or ")
-      raise Invalid.new("Search #{operators.map(&:key).join(" or ")} one at a time, or combine with #{others}.", second.range)
+      joiner = message(:list_or)
+      keys = operators.map(&:key).join(joiner)
+      # The first two filters, in declaration order (a host declares its best companions first).
+      others = definition.filters.first(2).map { |filter| "#{filter.key}:" }.join(joiner)
+      text = others.empty? ? message(:one_text_operator_alone, operators: keys) : message(:one_text_operator, operators: keys, filters: others)
+      raise Invalid.new(text, second.range)
     end
 
     # "stauts: is not an operator. Did you mean status:?", with the corrected term as the fix.
     def unknown_key(key, term)
       suggestion = definition.operator_keys.min_by { |candidate| distance(candidate, key) }
-      return Invalid.new("#{key}: is not an operator.", term.range) unless suggestion && distance(suggestion, key) <= 2
+      return Invalid.new(message(:unknown_operator, key: key), term.range) unless suggestion && distance(suggestion, key) <= 2
 
       fixed = source[term.range].sub(/\A[^:]+/, suggestion)
-      Invalid.new("#{key}: is not an operator. Did you mean #{suggestion}:?", term.range, fixed)
+      Invalid.new(message(:did_you_mean, key: key, suggestion: suggestion), term.range, fixed)
     end
 
+    # A query error from `querylane.errors.*`, English by default.
+    def message(name, **values) = Query.message(name, **values)
+
     # Levenshtein distance (short strings only).
     def distance(a, b)
       previous = (0..b.length).to_a

data/lib/querylane/request.rb

@@ -4,29 +4,31 @@ module Querylane
   # One search request, bounded and allowlisted against the definition.
   #
   # Params: query (Configuration#param_name), toggle ("facet:value"),
-  # remove (chip index), clear, instead, widen, relax, compose (with
+  # remove (chip index), as_words (chip index), clear, instead, widen, relax, compose (with
   # compose_submit), options, sort, page, per, revision.
   class Request
-    attr_reader :fix, :saved, :save_search, :saved_name, :group, :query, :toggle, :remove, :clear, :instead, :widen, :relax, :compose, :options, :sort, :page, :per, :revision
+    attr_reader :fix, :saved, :save_search, :saved_name, :group, :query, :toggle, :remove, :as_words, :clear, :instead, :widen, :relax, :compose, :options, :sort, :page, :per, :revision
 
     # @param params [ActionController::Parameters, Hash]
     # @param definition [Querylane::Definition]
     def self.from_params(params, definition:, config: Querylane.configuration)
       values = params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h
       values = values.transform_keys(&:to_s)
-      new(definition: definition, query: values[config.param_name.to_s], toggle: values["toggle"], remove: values["remove"], clear: values["clear"],
+      new(definition: definition, query: values[config.param_name.to_s], toggle: values["toggle"], remove: values["remove"],
+        as_words: values["as_words"], clear: values["clear"],
         instead: values["instead"], widen: values["widen"], relax: values["relax"],
         compose: (values["compose"] if values["compose_submit"].present?), options: values["options"],
         fix: values["fix"], group: values["group"], saved: values["saved"], save_search: values["save_search"], saved_name: values["saved_name"], sort: values["sort"], page: values["page"], per: values["per"], revision: values["revision"])
     end
 
     # instead: "chip.alternative" (use another reading of an interpreted term);
-    # widen: a facet key (drop that facet's terms); relax: match fewer words.
+    # widen: a facet key (drop that facet's terms); relax: match fewer words;
+    # as_words: a chip index (search that filter's typed value as plain words).
     # compose: options-panel fields {"name" => "…", "policy" => "1 2", "is" => [...], "options" => [...]}
     # (applied only with compose_submit); options: open the options panel;
     # group: a GroupToken (all records of one group, see Search#related);
     # saved: a saved search id to run; save_search with saved_name: save the query.
-    def initialize(definition:, query: nil, toggle: nil, remove: nil, clear: nil, instead: nil, widen: nil, relax: nil,
+    def initialize(definition:, query: nil, toggle: nil, remove: nil, as_words: nil, clear: nil, instead: nil, widen: nil, relax: nil,
       compose: nil, options: nil, fix: nil, group: nil, saved: nil, save_search: nil, saved_name: nil, sort: nil, page: nil, per: nil, revision: nil)
       @query = query.to_s
       @clear = clear.present?
@@ -42,6 +44,7 @@ module Querylane
       @compose = compose.is_a?(Hash) ? compose.to_h.transform_keys(&:to_s) : nil
       @toggle = parse_toggle(definition, toggle)
       @remove = (Integer(remove.to_s, exception: false) if remove.present?)
+      @as_words = (Integer(as_words.to_s, exception: false) if as_words.present?)
       @sort = definition.sort(sort)
       @per = definition.per_options.include?(per.to_i) ? per.to_i : definition.per_options.first
       @page = rewriting? ? 1 : [page.to_i, 1].max
@@ -52,7 +55,7 @@ module Querylane
     def offset = (page - 1) * per
 
     # Whether this request asks the server to rewrite the query text.
-    def rewriting? = (@toggle || @remove || @clear || @instead || @widen || @compose || @saved) ? true : false
+    def rewriting? = (@toggle || @remove || @as_words || @clear || @instead || @widen || @compose || @saved) ? true : false
 
     private