querylane 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f62396550c8585a01958050e34f4e31628ddb53ad02cf97074900e0882a6e510
-  data.tar.gz: 68f1c601f5a1083d1fd6711db29c87fde0a994962091578cb7f58c5b0b12f98d
+  metadata.gz: 76873d12e555209a71b9eafed1f3fa4beee0c3377015cf3bc064a13b01098153
+  data.tar.gz: fd06740404a5f449fe11b43e0669be267cea0f8ef0ce1a44243b472eca985b5b
 SHA512:
-  metadata.gz: 8c35bb1029b86f33ca864824980c847c532a0a6b5ad4ee9bcd44a53c6ec3370fded089c1146025cf4db3d17736baf5c1383d8ee31edd030c677e3fb78b43b460
-  data.tar.gz: 82f3e9d07e46f33876573d5f4227070965f352e3ec67bf479c90f9a98e457b5e017cdb822e1e7355af17a2e208b9a22b479acf474c546c60078cee98474a4b9e
+  metadata.gz: a31aa8846f0f7338af5ac7cf6c28b0b840a1e0a423653b04d68d5127f0a00c973a47a9d368273b0010679ea1e5165896df38693bb808a5d8d19311949a393ee3
+  data.tar.gz: e42d68c96660e86fa202330655388f411a5993a7cbda5d7ad14e6341fd66dd25d90b1ce83d4aee6d22e346c2ea8c3341d4e26f0afdb2121b5135f03ae6b80f97

data/CHANGELOG.md

@@ -7,6 +7,77 @@ change public APIs; each entry says how.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-10
+
+### Added
+
+- `config.logger`: querylane logs why a search was unavailable (Meilisearch
+  unreachable, timed out, or an API error such as a missing index). API
+  errors are logged by code, type and HTTP status only, never their message,
+  which can echo the filter; connection errors lose any URL credentials and
+  query string. The default logger writes to standard output; a Rails host
+  passes `Rails.logger`.
+- `p.row ... hint:, placeholder:` on options-panel rows: a line under the row
+  (its fields' `aria-describedby`) and a placeholder for its empty inputs (a
+  masked field's "In the box: …" still wins). `placeholder:` on a flags or
+  options row raises.
+- `d.filter ... invalid:`: a second sentence for the bad-value error.
+- `d.filter ... as_words: true`: when nothing matches, the empty state offers
+  "Search "smiht" as part of a name" (`querylane.states.as_words`, request
+  param `as_words=<chip index>`, `Rewriter.as_words`), which replaces the
+  filter term with its typed value as plain words. Refused on a sensitive
+  filter.
+- `d.filter ... display_value: :typed`: chips and the options panel show the
+  value as typed, and the panel writes it back as typed; the search still
+  uses the normalized value. Needs `mask: :none`.
+- `hint:`, `placeholder:` and `invalid:` take a locale key (a Symbol or a
+  dotted String) or plain text (`Querylane::Copy`), translated when shown.
+
+### Changed
+
+- Development and CI dependencies: rspec-rails 8.1.0, playwright 1.65.0,
+  ruby/setup-ruby 1.338.0.
+- Development Ruby 3.3.13 (from 3.3.10): the lowest supported series' release
+  with the Onigmo regexp fixes (CVE-2026-89078, CVE-2026-93577,
+  CVE-2026-97229, CVE-2026-110264). `required_ruby_version` and the CI
+  matrix are unchanged.
+- Every query error is a translation under `querylane.errors.*` (syntax,
+  limits, unknown and parked operators, bad filter and flag values, names in
+  OR, NOT and parentheses, one text operator). The English text is unchanged
+  and stays the default (`Querylane::Query::MESSAGES`).
+- With no filters declared, the one-text-operator error no longer ends in
+  "or combine with ."; it reads "Search name or id one at a time."
+- `Definition::FilterOperator` gains `invalid`, `as_words` and
+  `display_value`, `Definition::PanelRow` gains `hint` and `placeholder`, and
+  `Chips::Chip` gains `as_words`. Each new member has a default, so code that
+  builds these structs with the earlier members, by position or keyword,
+  still works.
+
+- Every partial declares its locals on its first line (Rails strict locals,
+  `<%# locals: (...) -%>`). A host override must keep the line, and a render
+  with other locals now raises. `_help` takes `popover_id: nil` instead of
+  reading `local_assigns`.
+- Controls follow one hierarchy (theming guide, "Bootstrap"): the box's
+  Search and the options panel's Search are outline buttons
+  (`btn-outline-primary`); Open and View are Go links (`.ql-go`, still a
+  button that posts); the empty state's actions and the panel's Cancel are
+  quiet links (`.ql-link`). `Presenter::Action#style` no longer changes the
+  look.
+- No Bootstrap utility classes: `.ql-visually-hidden` replaces
+  `visually-hidden`, `.ql-open-form` replaces `d-inline`, and `.ql-pager`
+  sets its own margin instead of `mb-0`.
+- The search box and the suggestion box sit in a `<search>` landmark
+  (`.ql-search`) instead of a form with `role="search"`.
+- The facet column's accessible name comes from `querylane.facets.label`.
+
+### Fixed
+
+- Space on a record right after a new answer drew its rows opens the preview.
+  The preview state was reset on `turbo:frame-render`, which Turbo fires a few
+  repaints after the rows are in, so the preview's answer was dropped as if
+  Esc had closed it. It is now reset when the new, empty preview frame
+  connects.
+
 ## [0.1.0] - 2026-10-20
 
 The first release.
@@ -80,5 +151,6 @@ The first release.
 - `search.querylane` and `saved_search_failed.querylane` instrumentation, without
   query text. The query parameter and `compose` are filtered from logs.
 
-[Unreleased]: https://github.com/clearstackio/querylane/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/clearstackio/querylane/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/clearstackio/querylane/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/clearstackio/querylane/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -73,7 +73,7 @@ also the example the guides quote.
   request (`spec/requests/`) or browser (`spec/system/`).
 - **Changelog:** add a line under `[Unreleased]` in [CHANGELOG.md](CHANGELOG.md)
   for anything a host would notice.
-- **CI:** GitHub Actions (`.github/workflows/ci.yml`): `rake` on Ruby 3.3, 3.4
+- **CI:** GitHub Actions ([design](docs/design/ci.md), [operations](docs/ops/ci.md)): `rake` on Ruby 3.3, 3.4
   and 4.0 against Meilisearch 1.13 and headless Chromium. Actions are pinned to
   commit SHAs. FracturedJSON is not run in CI; run `bin/lint` before pushing.
 - **Security:** no secrets in the repo; see [SECURITY.md](SECURITY.md).

data/README.md

@@ -169,6 +169,8 @@ A complete, working version of this example lives in [`spec/dummy`](spec/dummy).
 Rails.application.config.to_prepare do
   Querylane.configure do |config|
     config.searcher = -> { Querylane::Searchers::Meilisearch.new(client: Meilisearch::Client.new(ENV["MEILISEARCH_URL"], ENV["MEILISEARCH_API_KEY"])) }
+    # Why a search could not run (default: standard output).
+    config.logger = Rails.logger
   end
 end
 ```

data/app/assets/stylesheets/querylane.css

@@ -6,6 +6,11 @@
  */
 /* The hidden attribute wins over the display rules below. */
 :where(.querylane-form, .ql-results, .ql-suggest, .ql-palette) [hidden] { display: none !important; }
+/* A label read by assistive technology only. */
+.ql-visually-hidden { position: absolute !important; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
+  clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* The search landmark around a box and its form. */
+.ql-search { display: block; }
 
 :root {
   --ql-accent: var(--bs-primary, #0d6efd);
@@ -69,6 +74,9 @@
   border-radius: 13px; background: var(--ql-chip); color: var(--ql-text); }
 .ql-chip-remove { border: 0; background: none; padding: 0; color: var(--ql-muted); line-height: 1; }
 .ql-link { border: 0; background: none; padding: 0; color: var(--bs-link-color, #0865d1); font-weight: 500; }
+/* A Go link: opens a record or a page (bold, no box), even when it is a button that posts. */
+.ql-go { border: 0; background: none; padding: 0; color: var(--bs-link-color, #0865d1); font-weight: 700; }
+.ql-link:hover, .ql-go:hover { text-decoration: underline; }
 [data-querylane-stale] .ql-chips { opacity: 0.55; }
 .ql-state { padding: 28px 0; font-size: 15px; color: var(--ql-muted); }
 .ql-state-unavailable { padding: 20px 24px; border-left: 3px solid #977405; background: #fffbea; color: var(--ql-text); }
@@ -95,6 +103,7 @@
 .ql-count-note { margin-left: 10px; font-size: 13px; font-weight: 400; color: var(--ql-muted); }
 .ql-count { font-size: 18px; line-height: 22px; font-weight: 700; color: var(--ql-heading); }
 .ql-toolbar-controls { display: flex; align-items: center; gap: 16px; }
+.ql-pager { margin-bottom: 0; }
 .ql-control { display: flex; align-items: center; gap: 6px; margin: 0; font-size: 13px; color: var(--ql-muted); }
 .ql-control .form-select { width: auto; }
 
@@ -125,7 +134,7 @@
 .ql-badge-neutral { background: var(--ql-neutral-bg); color: var(--ql-neutral-fg); }
 .ql-flag-neutral { border: 1px solid var(--ql-border); color: var(--ql-muted); }
 .ql-reason { font-size: 13px; line-height: 17px; color: var(--ql-muted); }
-.ql-open { font-weight: 700; }
+.ql-open-form { display: inline; }
 
 /* Footer ---------------------------------------------------------------------- */
 .ql-footer { display: flex; align-items: center; justify-content: space-between; padding-top: 16px; font-size: 13px; color: var(--ql-muted); }
@@ -173,6 +182,8 @@
 .ql-options-inputs { display: flex; gap: 12px; }
 .ql-options-input { position: relative; flex: 1; min-width: 0; }
 .ql-options-input input { width: 100%; }
+/* A row's hint: under its fields, in the field column. */
+.ql-options-hint { grid-column: 2; margin: -6px 0 0; color: var(--ql-muted); font-size: 12px; line-height: 16px; }
 .ql-masked { -webkit-text-security: disc; }
 /* Above the field even when a host lifts a focused .form-control (Bootstrap 3 themes set z-index: 2). */
 .ql-options-reveal { position: absolute; top: 50%; right: 10px; z-index: 3; transform: translateY(-50%); font-size: 13px; }

data/app/javascript/querylane/controllers/box_controller.js

@@ -90,7 +90,7 @@ export default class extends Controller {
   // new revision; the rewrite comes back at that same revision.
   submitted(event) {
     clearTimeout(this.timer)
-    if (["toggle", "remove", "clear", "compose_submit", "saved", "fix", "instead", "widen", "relax"].includes(event.submitter?.name)) this.bump()
+    if (["toggle", "remove", "clear", "compose_submit", "saved", "fix", "instead", "widen", "relax", "as_words"].includes(event.submitter?.name)) this.bump()
   }
 
   setQuery(event) {

data/app/javascript/querylane/controllers/results_controller.js

@@ -23,7 +23,6 @@ export default class extends Controller {
     this.element.addEventListener("turbo:before-frame-render", this.guardPreview)
     this.restore = (event) => {
       if (event.target !== this.element) return
-      this.previewGroup = null
       this.restoreFocus()
     }
     this.element.addEventListener("querylane:focus-first", this.focusFirst)
@@ -95,6 +94,14 @@ export default class extends Controller {
     if (event.target.matches("select[form]")) event.target.form?.requestSubmit()
   }
 
+  // A new answer brings a new, empty preview frame: nothing is previewed any
+  // more. Stimulus calls this as the rows are swapped in; turbo:frame-render
+  // comes a few repaints later, after a quick Space may have started a preview.
+  previewTargetConnected() {
+    this.previewGroup = null
+    this.previewKey = null
+  }
+
   // private
 
   get records() {

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

@@ -1,4 +1,5 @@
-<%# "Searching for" chips. × removes that term (server rewrites the query). Locals: result, id. %>
+<%# locals: (result:, id:) -%>
+<%# "Searching for" chips. × removes that term (server rewrites the query). %>
 <% if result.chips.any? %>
   <div class="ql-chips">
     <span class="ql-chips-label"><%= t("querylane.chips.searching_for") %></span>

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

@@ -1,5 +1,6 @@
+<%# locals: (result:, id:) -%>
 <%# The user's access could not be checked (Querylane::Scope.denied): nothing
-    is shown rather than records outside it. Locals: result, id. %>
+    is shown rather than records outside it. %>
 <div class="ql-state ql-state-denied" role="alert">
   <h2><%= t("querylane.states.denied_title") %></h2>
   <p><%= t("querylane.states.denied") %></p>

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

@@ -1,16 +1,22 @@
-<%# No hits: say what found nothing and offer one-click ways to widen. Locals: result, id. %>
+<%# locals: (result:, id:) -%>
+<%# No hits: say what found nothing and offer one-click ways to widen. Each
+    way only rewrites the query, so it is a quiet link, never a button. %>
 <div class="ql-empty">
   <h2><%= t("querylane.states.empty_title", searched: result.chips.map(&:label).join(" · ")) %></h2>
   <div class="ql-empty-actions">
     <% result.widenable_facets.each do |facet| %>
-      <button type="submit" form="<%= id %>-form" name="widen" value="<%= facet.key %>" class="btn btn-outline-primary btn-sm"><%= t("querylane.states.widen_#{facet.key}", default: t("querylane.states.widen", facet: facet.label.downcase)) %></button>
+      <button type="submit" form="<%= id %>-form" name="widen" value="<%= facet.key %>" class="ql-link"><%= t("querylane.states.widen_#{facet.key}", default: t("querylane.states.widen", facet: facet.label.downcase)) %></button>
     <% end %>
     <%# Every filter can be dropped; the words are the search itself. %>
     <% result.chips.reject(&:words).each do |chip| %>
-      <button type="submit" form="<%= id %>-form" name="remove" value="<%= chip.index %>" class="btn btn-outline-secondary btn-sm"><%= t("querylane.states.drop", label: chip.label) %></button>
+      <button type="submit" form="<%= id %>-form" name="remove" value="<%= chip.index %>" class="ql-link"><%= t("querylane.states.drop", label: chip.label) %></button>
+    <% end %>
+    <%# An exact filter that opts in (as_words) can search its typed value as plain words. %>
+    <% result.chips.select(&:as_words).each do |chip| %>
+      <button type="submit" form="<%= id %>-form" name="as_words" value="<%= chip.index %>" class="ql-link"><%= t("querylane.states.as_words", value: chip.as_words) %></button>
     <% end %>
     <% unless result.relaxed %>
-      <button type="submit" form="<%= id %>-form" name="relax" value="1" class="btn btn-outline-secondary btn-sm"><%= t("querylane.states.relax") %></button>
+      <button type="submit" form="<%= id %>-form" name="relax" value="1" class="ql-link"><%= t("querylane.states.relax") %></button>
     <% end %>
   </div>
   <p class="ql-facet-note"><%= t("querylane.states.empty_note") %></p>

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

@@ -1,6 +1,7 @@
+<%# locals: (result:, id:) -%>
 <%# Facets. A value is a submit button with checkbox semantics: it asks the server
-    to tick or untick that value in the query text. Locals: result, id. %>
-<aside class="ql-facets" aria-label="Filters">
+    to tick or untick that value in the query text. %>
+<aside class="ql-facets" aria-label="<%= t("querylane.facets.label") %>">
   <% result.facets.each do |facet| %>
     <section class="ql-facet">
       <h3 class="ql-facet-title"><%= facet.label %></h3>

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

@@ -1,4 +1,5 @@
-<%# Before anything is typed: what to type, with the definition's examples. Locals: definition. %>
+<%# locals: (definition:) -%>
+<%# Before anything is typed: what to type, with the definition's examples. %>
 <div class="ql-first-load">
   <div class="ql-first-load-lead">
     <h2><%= t("querylane.states.first_load_title") %></h2>

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

@@ -1,10 +1,19 @@
-<%# The search form and box. Outside the results frame, so typing never loses the caret.
-    Locals: result, id, url, input_id, label, placeholder, mask, button_id, options, help, extra. %>
-<%= form_with url: url, method: :post, id: "#{id}-form", class: "querylane-form",
-      data: {turbo: true, turbo_frame: "#{id}-results", controller: "querylane--box",
+<%# locals: (result:, id:, url:, input_id:, label:, placeholder:, mask:, button_id:, options:, help:, extra:) -%>
+<%# The search form and box, in a search landmark. Outside the results frame,
+    so typing never loses the caret. Search applies the box (an outline
+    button): the host's page keeps its one solid button for a commit. %>
+<%
+  form_id = "#{id}-form"
+  frame_id = "#{id}-results"
+  help_id = "#{id}-help-text" if help
+  described_by = [help_id, "#{id}-error"].compact.join(" ")
+%>
+<search class="ql-search">
+<%= form_with url: url, method: :post, id: form_id, class: "querylane-form",
+      data: {turbo: true, turbo_frame: frame_id, controller: "querylane--box",
              querylane__box_debounce_value: Querylane.configuration.debounce_ms,
              querylane__box_mask_value: mask.to_s,
-             querylane__box_frame_value: "#{id}-results",
+             querylane__box_frame_value: frame_id,
              querylane__box_min_value: result.definition.min_text_length.to_i,
              action: "submit->querylane--box#submitted turbo:before-cache@document->querylane--box#forget keydown@document->querylane--box#shortcut"} do %>
   <%# The default button: Enter in the box searches (Options comes first in the box). %>
@@ -14,10 +23,10 @@
     <svg class="ql-box-icon" viewBox="0 0 20 20" width="20" height="20" 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>
     <div class="ql-box-field">
       <div class="ql-box-overlay" aria-hidden="true" data-querylane--box-target="overlay"></div>
-      <label class="visually-hidden" for="<%= input_id %>"><%= label %></label>
+      <label class="ql-visually-hidden" for="<%= input_id %>"><%= label %></label>
       <input type="text" id="<%= input_id %>" name="<%= Querylane.configuration.param_name %>" value="<%= result.query %>"
              class="ql-box-input" placeholder="<%= placeholder %>" autocomplete="off" autocapitalize="off" spellcheck="false"
-             aria-describedby="<%= [("#{id}-help-text" if help), "#{id}-error"].compact.join(" ") %>"
+             aria-describedby="<%= described_by %>"
              data-querylane--box-target="input"
              data-action="input->querylane--box#typed keydown->querylane--box#keys scroll->querylane--box#paint select->querylane--box#paint click->querylane--box#paint compositionstart->querylane--box#compose compositionend->querylane--box#composed">
     </div>
@@ -39,8 +48,9 @@
         <%= t("querylane.box.options") %>
       </button>
     <% end %>
-    <button type="submit" class="btn btn-primary ql-box-submit" <%= %(id="#{button_id}").html_safe if button_id %>><%= t("querylane.box.search") %></button>
+    <button type="submit" class="btn btn-outline-primary ql-box-submit" <%= tag.attributes(id: button_id) %>><%= t("querylane.box.search") %></button>
   </div>
-  <% if help %><p class="ql-box-help" id="<%= id %>-help-text"><%= help %></p><% end %>
+  <% if help %><p class="ql-box-help" id="<%= help_id %>"><%= help %></p><% end %>
   <div class="ql-hint" role="status" hidden data-querylane--box-target="hint"><%= t("querylane.states.short", count: result.definition.min_text_length) if result.definition.min_text_length %></div>
 <% end %>
+</search>

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

@@ -1,5 +1,6 @@
+<%# locals: (presenter:, group:, columns:) -%>
 <%# One group (e.g. a person) and its records, with "N more records" only
-    when the group has records the page does not show. Locals: presenter, group, columns. %>
+    when the group has records the page does not show. %>
 <% token = presenter.group_token(group) %>
 <div class="ql-group" <%= tag.attributes(data: {querylane_group: token}) %>>
   <div class="ql-group-head">

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

@@ -1,6 +1,7 @@
+<%# locals: (definition:, id:, popover_id: nil) -%>
 <%# Syntax help card generated from the definition; a native popover (no JS).
-    Locals: definition, id, popover_id (optional, when shown twice on a page). %>
-<% popover_id = local_assigns.fetch(:popover_id, "#{id}-help") %>
+    popover_id names it when it is shown twice on a page. %>
+<% popover_id ||= "#{id}-help" %>
 <button type="button" class="ql-link" popovertarget="<%= popover_id %>"><%= t("querylane.chips.syntax_help") %></button>
 <div id="<%= popover_id %>" popover class="ql-help">
   <div class="ql-help-head">

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

@@ -1,6 +1,8 @@
+<%# locals: (result:, id:) -%>
 <%# The options panel (M3): fields read from the box, Search writes them back.
     Fields belong to the search form (form=…), so the live box text travels with
-    them; the server composes. Locals: result, id. %>
+    them; the server composes. Search applies the panel (outline), Cancel and
+    Reset are quiet links. %>
 <section class="ql-options" id="<%= id %>-options" aria-labelledby="<%= id %>-options-title"
          data-controller="querylane--options" data-querylane--options-debounce-value="<%= Querylane.configuration.debounce_ms %>"
          data-action="input->querylane--options#changed change->querylane--options#changed keydown.esc->querylane--options#cancel keydown.enter->querylane--options#apply">
@@ -25,8 +27,8 @@
     <%= render "querylane/help", definition: result.definition, id: id, popover_id: "#{id}-options-help" %>
     <button type="button" class="ql-link" data-action="querylane--options#reset"><%= t("querylane.options.reset") %></button>
     <span class="ql-options-spacer"></span>
-    <button type="submit" form="<%= id %>-form" class="btn btn-link" data-querylane--options-target="cancel"><%= t("querylane.options.cancel") %></button>
-    <button type="submit" form="<%= id %>-form" name="compose_submit" value="1" class="btn btn-primary"
+    <button type="submit" form="<%= id %>-form" class="ql-link" data-querylane--options-target="cancel"><%= t("querylane.options.cancel") %></button>
+    <button type="submit" form="<%= id %>-form" name="compose_submit" value="1" class="btn btn-outline-primary"
             data-querylane--options-target="apply"><%= t("querylane.options.search") %></button>
   </footer>
 </section>

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

@@ -1,7 +1,15 @@
-<%# One options-panel row. Locals: row (Definition::PanelRow), values, held, definition, id.
+<%# locals: (row:, values:, held:, definition:, id:) -%>
+<%# One options-panel row (a Definition::PanelRow).
     A masked field starts empty: its current terms stay in the box (shown
-    masked as the placeholder); what is typed here is added. %>
-<% field_id = ->(name) { "#{id}-compose-#{name}" } %>
+    masked as the placeholder, which wins over the row's own placeholder);
+    what is typed here is added. The row's hint sits under it and describes
+    its fields. %>
+<%
+  field_id = ->(name) { "#{id}-compose-#{name}" }
+  hint = Querylane::Copy.text(row.hint)
+  hint_id = "#{field_id.(row.name)}-hint" if hint
+  placeholder = Querylane::Copy.text(row.placeholder)
+%>
 <div class="ql-options-row">
   <% case row.kind %>
   <% when :inputs %>
@@ -13,8 +21,8 @@
           <%# Sensitive fields stay type=text (a password field would invite the browser to save it), masked by CSS. %>
           <input type="text" id="<%= field_id.(name) %>" name="compose[<%= name %>]" form="<%= id %>-form"
                  value="<%= values[name] %>" class="form-control form-control-sm <%= "ql-masked" if row.masked %>" autocomplete="off" spellcheck="false"
-                 <%= tag.attributes(placeholder: (t("querylane.options.held", text: held[name]) if held[name])) %>
-                 <%= tag.attributes(aria: {label: ("#{row.label} #{name.humanize}" if position.positive?)}) %>
+                 <%= tag.attributes(placeholder: (held[name] ? t("querylane.options.held", text: held[name]) : placeholder)) %>
+                 <%= tag.attributes(aria: {label: ("#{row.label} #{name.humanize}" if position.positive?), describedby: hint_id}) %>
                  data-querylane--options-target="field">
           <% if row.masked %>
             <button type="button" class="ql-link ql-options-reveal" aria-controls="<%= field_id.(name) %>" aria-pressed="false"
@@ -27,7 +35,7 @@
   <% when :flags %>
     <% flags = definition.operator(row.keys.first) %>
     <span class="ql-options-label" id="<%= field_id.(row.name) %>-label"><%= row.label %></span>
-    <div class="ql-options-checks" role="group" aria-labelledby="<%= field_id.(row.name) %>-label">
+    <div class="ql-options-checks" role="group" aria-labelledby="<%= field_id.(row.name) %>-label" <%= tag.attributes(aria: {describedby: hint_id}) %>>
       <% definition.flag_values(flags, row.values).each do |value, label| %>
         <label class="ql-options-check">
           <input type="checkbox" name="compose[<%= row.name %>][]" value="<%= value %>" form="<%= id %>-form"
@@ -42,10 +50,13 @@
       <% row.keys.each do |key| %>
         <label class="ql-options-check">
           <input type="checkbox" name="compose[options][]" value="<%= key %>" form="<%= id %>-form"
-                 <%= "checked" if values["options"].include?(key.to_s) %> data-querylane--options-target="field">
+                 <%= "checked" if values["options"].include?(key.to_s) %> <%= tag.attributes(aria: {describedby: hint_id}) %> data-querylane--options-target="field">
           <%= definition.option(key).label %>
         </label>
       <% end %>
     </div>
   <% end %>
+  <% if hint %>
+    <p class="ql-options-hint" id="<%= hint_id %>"><%= hint %></p>
+  <% end %>
 </div>

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

@@ -1,9 +1,11 @@
-<%# Open/View button (full-page POST) or the reason it cannot be opened. Locals: outcome. %>
+<%# locals: (outcome:) -%>
+<%# Open/View or the reason a record cannot be opened. Open/View is a Go link
+    (rows hold no buttons) drawn on a button, because it posts (a full page). %>
 <% case outcome %>
 <% when Querylane::Presenter::Action %>
   <%= button_to outcome.label, outcome.url, params: outcome.params || {}, method: :post,
-        class: "btn btn-sm #{(outcome.style == :primary) ? "btn-primary" : "btn-outline-primary"} ql-open",
-        form: {class: "d-inline", data: {turbo: false}}, data: {querylane_open: true} %>
+        class: "ql-go ql-open",
+        form: {class: "ql-open-form", data: {turbo: false}}, data: {querylane_open: true} %>
 <% when Querylane::Presenter::Reason %>
   <span class="ql-reason"><%= outcome.text %><% if outcome.link_url %> <%= link_to outcome.link_label, outcome.link_url, data: {turbo: false} %><% end %>
     <% if outcome.more.any? %>

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

@@ -1,9 +1,10 @@
-<%# Previous, up to five pages, Next. Submit buttons of the search form. Locals: result, id. %>
+<%# locals: (result:, id:) -%>
+<%# Previous, up to five pages, Next. Submit buttons of the search form. %>
 <% pages = [result.pages, 1].max
    start = [[result.page - 2, 1].max, [pages - 4, 1].max].min
    window = (start..[start + 4, pages].min) %>
 <nav aria-label="<%= t("querylane.toolbar.pages") %>">
-  <ul class="pagination pagination-sm mb-0 ql-pager">
+  <ul class="pagination pagination-sm ql-pager">
     <li class="page-item previous <%= "disabled" if result.page <= 1 %>">
       <button type="submit" form="<%= id %>-form" name="page" value="<%= result.page - 1 %>" class="page-link" <%= "disabled" if result.page <= 1 %>><%= t("querylane.toolbar.previous") %></button>
     </li>

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

@@ -1,5 +1,6 @@
+<%# locals: (result:, presenter:, id:) -%>
 <%# The preview (Space on a record): every record of its group, any status.
-    Locals: result (from querylane_related), presenter, id. %>
+    result comes from querylane_related. %>
 <turbo-frame id="<%= id %>-preview" class="ql-preview">
   <section class="ql-preview-card" aria-labelledby="<%= id %>-preview-title">
     <% if result.state == :unavailable %>

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

@@ -1,4 +1,5 @@
-<%# One record in lanes. Focusable for ↑/↓/Enter. Locals: presenter, hit, columns. %>
+<%# locals: (presenter:, hit:, columns:) -%>
+<%# One record in lanes. Focusable for ↑/↓/Enter. %>
 <div class="ql-record" tabindex="-1" data-querylane-record="<%= presenter.record_key(hit) %>">
   <% presenter.cells(hit).each_with_index do |cell, index| %>
     <% width = columns[index]&.width %>

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

@@ -1,5 +1,6 @@
+<%# locals: (result:, presenter:, frame:) -%>
 <%# "More records": every record of one group the page did not show.
-    Locals: result (from querylane_related), presenter, frame. %>
+    result comes from querylane_related; frame is the requesting frame id. %>
 <turbo-frame id="<%= frame %>" class="ql-related">
   <% if result.state == :unavailable %>
     <div class="ql-related-head" role="status"><%= t("querylane.group.unavailable") %></div>

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

@@ -1,5 +1,5 @@
-<%# The results frame: everything one search request answers.
-    Locals: result, id, info_id, per_id, first_load, rows. %>
+<%# locals: (result:, id:, info_id:, per_id:, first_load:, rows:) -%>
+<%# The results frame: everything one search request answers. %>
 <turbo-frame id="<%= id %>-results" class="ql-results" data-revision="<%= result.revision %>" data-controller="querylane--results"
              data-action="change->querylane--results#submitForm keydown->querylane--results#keys">
   <%# The answer's state, inside the frame (Turbo keeps the frame element's own

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

@@ -1,4 +1,5 @@
-<%# Grouped records drawn from a Querylane::Presenter. Locals: presenter. %>
+<%# locals: (presenter:) -%>
+<%# Grouped records drawn from a Querylane::Presenter. %>
 <% columns = presenter.columns %>
 <div class="ql-record ql-record-head" aria-hidden="true">
   <% columns.each do |column| %>

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

@@ -1,6 +1,7 @@
+<%# locals: (result:, id:) -%>
 <%# Saved searches (M12): a native popover opened by the box's Saved button.
     Name and Save belong to the search form; choosing one sends its id and the
-    server rewrites the box. Locals: result, id. %>
+    server rewrites the box. %>
 <div id="<%= id %>-saved" popover class="ql-saved">
   <div class="ql-saved-head">
     <label for="<%= id %>-saved-name"><%= t("querylane.saved.title") %></label>

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>