querylane 0.1.0 → 0.3.0

data/app/views/querylane/_suggest_box.html.erb

@@ -1,8 +1,9 @@
-<%# A search box with suggestions for any page (M7 header, M13 palette).
-    The form posts the text for suggestions into the list frame; the hidden
-    submitters post it to the search page (full page, never in a URL).
-    Locals: id, url, search_url, mode (:header or :palette), label, placeholder,
-    trigger (palette: show its button; ⌘K / Ctrl-K always opens it). %>
+<%# locals: (id:, url:, search_url:, mode:, label:, placeholder:, trigger:) -%>
+<%# A search box with suggestions for any page (M7 header, M13 palette), in a
+    search landmark. The form posts the text for suggestions into the list
+    frame; the hidden submitters post it to the search page (full page, never
+    in a URL). mode is :header or :palette; trigger (palette) shows its
+    button; ⌘K / Ctrl-K always opens it. %>
 <% palette = mode == :palette %>
 <div class="ql-suggest ql-suggest-<%= mode %>" data-controller="querylane--suggest"
      data-querylane--suggest-debounce-value="<%= Querylane.configuration.debounce_ms %>"
@@ -17,11 +18,12 @@
     <dialog class="ql-palette" aria-label="<%= label %>" data-querylane--suggest-target="dialog"
             data-action="close->querylane--suggest#closed click->querylane--suggest#backdrop">
   <% end %>
-  <%= form_with url: url, method: :post, id: "#{id}-form", class: "ql-suggest-form", html: {role: "search"},
+  <search class="ql-search">
+  <%= form_with url: url, method: :post, id: "#{id}-form", class: "ql-suggest-form",
         data: {turbo: true, turbo_frame: "#{id}-list", action: "submit->querylane--suggest#submitted"} do %>
     <%= hidden_field_tag :revision, 0, id: nil, data: {querylane__suggest_target: "revision"} %>
     <svg class="ql-box-icon" viewBox="0 0 20 20" width="16" height="16" aria-hidden="true"><circle cx="8.5" cy="8.5" r="6" fill="none" stroke="currentColor" stroke-width="2"/><path d="M13 13l5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
-    <label class="visually-hidden" for="<%= id %>-input"><%= label %></label>
+    <label class="ql-visually-hidden" for="<%= id %>-input"><%= label %></label>
     <input type="text" id="<%= id %>-input" name="<%= Querylane.configuration.param_name %>" class="ql-suggest-input"
            placeholder="<%= placeholder %>" autocomplete="off" autocapitalize="off" spellcheck="false"
            role="combobox" aria-autocomplete="list" aria-controls="<%= id %>-list" aria-expanded="false"
@@ -31,6 +33,7 @@
     <button type="submit" formaction="<%= search_url %>" data-turbo="false" hidden tabindex="-1" data-querylane--suggest-target="searchAll"></button>
     <button type="submit" formaction="<%= search_url %>" name="options" value="1" data-turbo="false" hidden tabindex="-1" data-querylane--suggest-target="openOptions"></button>
   <% end %>
+  </search>
   <div class="ql-suggest-pop" hidden data-querylane--suggest-target="pop">
     <turbo-frame id="<%= id %>-list" class="ql-suggest-list" role="listbox" aria-label="<%= label %>"
                  data-querylane--suggest-target="list" data-action="combobox-commit->querylane--suggest#commit"></turbo-frame>

data/app/views/querylane/_suggestions.html.erb

@@ -1,6 +1,6 @@
+<%# locals: (result:, presenter:, groups:, id:) -%>
 <%# Suggestions: operator completions, people (groups), go-to. Options carry
-    no query text: a completion holds only its word, people their own Action.
-    Locals: result, presenter, groups, id. %>
+    no query text: a completion holds only its word, people their own Action. %>
 <turbo-frame id="<%= id %>-list" class="ql-suggest-list" role="listbox" data-revision="<%= result.revision %>">
   <% if result.completions.any? %>
     <div role="group" aria-labelledby="<%= id %>-operators">

data/app/views/querylane/_toolbar.html.erb

@@ -1,4 +1,5 @@
-<%# Count, sort, page size and pager; controls belong to the search form. Locals: result, id, per_id. %>
+<%# locals: (result:, id:, per_id:) -%>
+<%# Count, sort, page size and pager; controls belong to the search form. %>
 <div class="ql-toolbar">
   <div class="ql-count">
     <%= case result.total_kind

data/app/views/querylane/_unavailable.html.erb

@@ -1,5 +1,6 @@
+<%# locals: (result:, id:) -%>
 <%# The backend did not answer: nothing was searched. Hosts override this
-    partial to add their own way round (e.g. a roster page). Locals: result, id. %>
+    partial to add their own way round (e.g. a roster page). %>
 <div class="ql-state ql-state-unavailable" role="status">
   <h2><%= t("querylane.states.unavailable_title") %></h2>
   <p><%= t("querylane.states.unavailable") %></p>

data/app/views/querylane/_writes.html.erb

@@ -1,6 +1,7 @@
-<%# The options panel's "Writes" line: what Search would put in the box, with
-    sensitive values masked. Its own frame, refreshed as fields change.
-    Locals: preview (Querylane::Preview), id. %>
+<%# locals: (preview:, id:) -%>
+<%# The options panel's "Writes" line (a Querylane::Preview): what Search
+    would put in the box, with sensitive values masked. Its own frame,
+    refreshed as fields change. %>
 <turbo-frame id="<%= id %>-writes" class="ql-writes" aria-live="polite">
   <div class="ql-writes-line">
     <span class="ql-writes-label"><%= t("querylane.options.writes") %></span>

data/config/locales/querylane.en.yml

@@ -44,6 +44,9 @@ en:
       title: "Save this search"
       name: "Name"
       save: "Save"
+      delete: "Delete"
+      delete_label: "Delete saved search %{name}"
+      delete_confirm: "Delete this saved search?"
       yours: "Your saved searches"
       none: "Nothing saved yet."
       used: "used %{date}"
@@ -53,14 +56,41 @@ en:
       refusal_alone: "Remove it first."
       notice:
         saved: "Search saved."
+        deleted: "Search deleted."
+        not_available: "Saved search is not available."
         refused: "This search was not saved: it holds a member ID, SSN or last four."
         store_failed: "Saved searches are unavailable right now."
     reasons:
       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 +137,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 +155,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/controller.rb

@@ -63,7 +63,11 @@ module Querylane
     # in), and no response is cached. Only the URL's own query string is
     # checked: a host may pass a query it restored on the server (e.g. a
     # remembered search) to a GET.
-    def querylane_guard!(_params, config)
+    def querylane_guard!(params, config)
+      if Request.delete_saved_param(params) && !request.post?
+        raise ActionController::BadRequest, "Saved searches are deleted by POST"
+      end
+
       url = request.query_parameters
       carries_text = [config.param_name, :compose, :group].any? { |name| url[name.to_s].present? }
       if request.get? && carries_text && !config.allow_get_query

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.