querylane 0.1.0

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

@@ -0,0 +1,137 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Lives on the results <turbo-frame> (which persists while its contents are
+// replaced): ↑/↓ move between records, Enter opens the focused record, Space
+// previews its group (the preview follows ↑/↓, Esc closes it), opening a
+// group's "more records" loads them once, the focused record survives a frame
+// refresh, selects submit the search form.
+export default class extends Controller {
+  static targets = ["preview", "previewButton"]
+
+  connect() {
+    this.focusFirst = () => this.move(0, true)
+    this.remember = (event) => {
+      if (event.target !== this.element) return
+      const focused = this.element.contains(document.activeElement) ? document.activeElement.closest("[data-querylane-record]") : null
+      this.focusedKey = focused?.dataset.querylaneRecord
+    }
+    // A preview answer that arrives after Esc must not reopen it.
+    this.guardPreview = (event) => {
+      if (event.target !== this.previewTargetOrNull || this.previewGroup) return
+      event.detail.render = () => {}
+    }
+    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)
+    this.element.addEventListener("turbo:before-frame-render", this.remember)
+    this.element.addEventListener("turbo:frame-render", this.restore)
+  }
+
+  disconnect() {
+    this.element.removeEventListener("querylane:focus-first", this.focusFirst)
+    this.element.removeEventListener("turbo:before-frame-render", this.remember)
+    this.element.removeEventListener("turbo:frame-render", this.restore)
+    this.element.removeEventListener("turbo:before-frame-render", this.guardPreview)
+  }
+
+  keys(event) {
+    const record = event.target.closest("[data-querylane-record]")
+    if (!record) return
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault()
+      const next = this.move(this.records.indexOf(record) + (event.key === "ArrowDown" ? 1 : -1))
+      if (next && this.previewing) this.showPreview(next)
+    } else if (event.key === "Enter" && event.target === record) {
+      event.preventDefault()
+      record.querySelector("[data-querylane-open]")?.click()
+    } else if (event.key === " " && event.target === record) {
+      event.preventDefault()
+      this.previewing ? this.closePreview() : this.showPreview(record)
+    } else if (event.key === "Escape" && this.previewing) {
+      event.preventDefault()
+      this.closePreview()
+    }
+  }
+
+  // A group's "more records" <details>: the first open loads them.
+  more(event) {
+    const details = event.currentTarget
+    if (!details.open || details.dataset.loaded) return
+    details.dataset.loaded = "true"
+    const button = details.querySelector("[data-querylane-more]")
+    button?.form?.requestSubmit(button)
+  }
+
+  // A facet's "Find…" box: show the loaded values matching it (all of them,
+  // not only the first few); empty shows the first few again.
+  findValue(event) {
+    const text = event.target.value.trim().toLowerCase()
+    event.target.closest(".ql-facet").querySelectorAll(".ql-facet-value").forEach((value) => {
+      const label = value.querySelector(".ql-facet-label").textContent.toLowerCase()
+      value.hidden = text ? !label.includes(text) : value.hasAttribute("data-querylane-beyond")
+    })
+  }
+
+  // Enter in a field that names its button (data-querylane-enter) clicks it.
+  enter(event) {
+    event.preventDefault()
+    document.getElementById(event.target.dataset.querylaneEnter)?.click()
+  }
+
+  closePreview() {
+    if (!this.hasPreviewTarget) return
+    this.previewTarget.innerHTML = ""
+    this.previewGroup = null
+    this.element.querySelector("[data-querylane-previewing]")?.removeAttribute("data-querylane-previewing")
+    this.element.querySelector(`[data-querylane-record="${CSS.escape(this.previewKey || "")}"]`)?.focus()
+    this.previewKey = null
+  }
+
+  submitForm(event) {
+    if (event.target.matches("select[form]")) event.target.form?.requestSubmit()
+  }
+
+  // private
+
+  get records() {
+    return Array.from(this.element.querySelectorAll("[data-querylane-record]"))
+  }
+
+  get previewTargetOrNull() {
+    return this.hasPreviewTarget ? this.previewTarget : null
+  }
+
+  get previewing() {
+    return Boolean(this.previewGroup)
+  }
+
+  move(index, first = false) {
+    const records = this.records
+    if (records.length === 0) return null
+    const target = records[Math.max(0, Math.min(first ? 0 : index, records.length - 1))]
+    target.focus()
+    return target
+  }
+
+  // Loads the record's group into the preview frame (once per group).
+  showPreview(record) {
+    const group = record.closest("[data-querylane-group]")
+    if (!group || !this.hasPreviewButtonTarget) return
+    this.element.querySelector("[data-querylane-previewing]")?.removeAttribute("data-querylane-previewing")
+    record.setAttribute("data-querylane-previewing", "")
+    this.previewKey = record.dataset.querylaneRecord
+    if (this.previewGroup === group.dataset.querylaneGroup) return
+    this.previewGroup = group.dataset.querylaneGroup
+    this.previewButtonTarget.value = this.previewGroup
+    this.previewButtonTarget.form?.requestSubmit(this.previewButtonTarget)
+  }
+
+  restoreFocus() {
+    if (!this.focusedKey) return
+    this.element.querySelector(`[data-querylane-record="${CSS.escape(this.focusedKey)}"]`)?.focus()
+  }
+}

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

@@ -0,0 +1,187 @@
+import { Controller } from "@hotwired/stimulus"
+import Combobox from "@github/combobox-nav"
+
+// A search box with suggestions (header dropdown or ⌘K palette). Typing posts
+// the text into the list frame (debounced, stale answers dropped); ↑/↓ and
+// Enter come from combobox-nav; Tab completes an operator; Enter with nothing
+// chosen, or "Search all", posts the text to the search page.
+export default class extends Controller {
+  static targets = ["input", "list", "pop", "dialog", "revision", "searchAll", "openOptions"]
+  static values = { debounce: { type: Number, default: 300 }, palette: Boolean }
+
+  connect() {
+    this.combobox = new Combobox(this.inputTarget, this.listTarget, { tabInsertsSuggestions: false })
+    this.forget = () => this.clearAll()
+    document.addEventListener("turbo:before-cache", this.forget)
+    this.guardStale = (event) => this.guard(event)
+    this.listTarget.addEventListener("turbo:before-frame-render", this.guardStale)
+    this.outside = (event) => {
+      if (!this.paletteValue && !this.element.contains(event.target)) this.hide()
+    }
+    document.addEventListener("click", this.outside)
+  }
+
+  disconnect() {
+    clearTimeout(this.timer)
+    this.combobox.destroy()
+    this.listTarget.removeEventListener("turbo:before-frame-render", this.guardStale)
+    document.removeEventListener("click", this.outside)
+    document.removeEventListener("turbo:before-cache", this.forget)
+  }
+
+  // Every keystroke makes the shown suggestions stale: they stop answering
+  // keys and clicks until the answer for the new text arrives.
+  typed() {
+    this.bump()
+    this.combobox.stop()
+    this.listTarget.setAttribute("data-querylane-stale", "")
+    clearTimeout(this.timer)
+    if (this.composing) return
+    if (this.inputTarget.value.trim() === "") return this.hide()
+    this.timer = setTimeout(() => this.inputTarget.form.requestSubmit(), this.debounceValue)
+  }
+
+  compose() {
+    this.composing = true
+    clearTimeout(this.timer)
+  }
+
+  composed() {
+    this.composing = false
+    this.typed()
+  }
+
+  submitted() {
+    clearTimeout(this.timer)
+  }
+
+  keys(event) {
+    if (event.key === "Tab" && !event.shiftKey && this.visible) {
+      // While the next answer loads, Tab waits rather than leaving the box.
+      if (this.listTarget.hasAttribute("data-querylane-stale")) return event.preventDefault()
+      const option = this.listTarget.querySelector('[aria-selected="true"][data-querylane-complete]') ||
+        this.listTarget.querySelector("[data-querylane-complete]")
+      if (!option) return
+      event.preventDefault()
+      this.complete(option.dataset.querylaneComplete)
+    } else if (event.key === "Enter" && (this.listTarget.hasAttribute("data-querylane-stale") || !this.listTarget.querySelector('[aria-selected="true"]'))) {
+      event.preventDefault()
+      this.go("search")
+    } else if (event.key === "Escape" && !this.paletteValue) {
+      if (this.visible) this.hide()
+      else this.inputTarget.blur()
+    }
+  }
+
+  // combobox-nav: an option was chosen (Enter or click). Stale options do nothing.
+  commit(event) {
+    if (this.listTarget.hasAttribute("data-querylane-stale")) return
+    const option = event.target.closest('[role="option"]')
+    if (!option) return
+    if (option.dataset.querylaneComplete) return this.complete(option.dataset.querylaneComplete)
+    if (option.dataset.querylaneGo) return this.go(option.dataset.querylaneGo)
+    const open = option.querySelector("[data-querylane-open]")
+    open ? open.click() : this.go("search")
+  }
+
+  // "/" focuses the header box (unless the page has its own box); ⌘K / Ctrl-K opens the palette.
+  shortcut(event) {
+    if (this.paletteValue) {
+      if (event.key.toLowerCase() === "k" && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault()
+        this.open()
+      }
+      return
+    }
+    if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey) return
+    if (event.target.closest("input, textarea, select, [contenteditable]")) return
+    if (document.querySelector(".ql-box-input")) return
+    event.preventDefault()
+    this.inputTarget.focus()
+  }
+
+  open() {
+    this.dialogTarget.showModal()
+    this.inputTarget.focus()
+  }
+
+  closed() {
+    this.hide()
+  }
+
+  backdrop(event) {
+    if (event.target === this.dialogTarget) this.dialogTarget.close()
+  }
+
+  // Focus shows the last list again; a stale one stays inert until its answer renders.
+  reopen() {
+    if (this.listTarget.childElementCount === 0 || this.inputTarget.value.trim() === "") return
+    if (this.listTarget.hasAttribute("data-querylane-stale")) this.popTarget.hidden = false
+    else this.show()
+  }
+
+  // private
+
+  get visible() {
+    return !this.popTarget.hidden
+  }
+
+  get revision() {
+    return Number(this.revisionTarget.value)
+  }
+
+  bump() {
+    this.revisionTarget.value = String(this.revision + 1)
+  }
+
+  // Replaces the last word; the shown completions no longer apply, so they go
+  // until the next answer arrives (a quick Enter cannot pick a stale one).
+  complete(word) {
+    this.listTarget.querySelectorAll("[data-querylane-complete]").forEach((option) => option.remove())
+    const value = this.inputTarget.value.replace(/\S*$/, word)
+    this.inputTarget.value = word.endsWith(":") ? value : `${value} `
+    this.inputTarget.focus()
+    this.typed()
+  }
+
+  go(where) {
+    clearTimeout(this.timer)
+    const button = where === "options" ? this.openOptionsTarget : this.searchAllTarget
+    this.inputTarget.form.requestSubmit(button)
+  }
+
+  show() {
+    if (this.inputTarget.value.trim() === "") return
+    this.listTarget.removeAttribute("data-querylane-stale")
+    this.popTarget.hidden = false
+    this.combobox.start()
+  }
+
+  // Before Turbo snapshots the page: nothing typed or suggested is kept.
+  clearAll() {
+    clearTimeout(this.timer)
+    this.bump()
+    this.inputTarget.value = ""
+    this.inputTarget.removeAttribute("value")
+    this.listTarget.innerHTML = ""
+    this.hide()
+    if (this.paletteValue && this.dialogTarget.open) this.dialogTarget.close()
+  }
+
+  hide() {
+    this.popTarget.hidden = true
+    this.combobox.stop()
+  }
+
+  guard(event) {
+    if (event.target !== this.listTarget) return
+    const answered = Number(event.detail.newFrame?.dataset?.revision)
+    if (!Number.isFinite(answered)) return
+    const render = event.detail.render
+    event.detail.render = (current, next) => {
+      if (answered < this.revision) return
+      render(current, next)
+      this.show()
+    }
+  }
+}

data/app/javascript/querylane/index.js

@@ -0,0 +1,33 @@
+// querylane — Stimulus controllers and a Turbo stream action.
+//
+//   import { registerControllers } from "querylane"
+//   registerControllers(application)   // the host's Stimulus application
+//
+// Never starts Stimulus or changes Turbo settings; the host owns both. Never
+// imports Turbo either: the stream action is handled through a DOM event, so
+// it works with whichever Turbo copy the page loaded (turbo-rails' bundle too).
+import BoxController from "querylane/controllers/box_controller.js"
+import ResultsController from "querylane/controllers/results_controller.js"
+import OptionsController from "querylane/controllers/options_controller.js"
+import SuggestController from "querylane/controllers/suggest_controller.js"
+
+// Server rewrote the query (facet toggle, chip ×, Clear): set the box text in
+// place, only if the box is still at the revision the response answers.
+// Replacing `detail.render` is Turbo's documented hook for a custom action.
+document.addEventListener("turbo:before-stream-render", (event) => {
+  if (event.target.getAttribute("action") !== "querylane_set_query") return
+
+  event.detail.render = (stream) => {
+    const detail = { revision: Number(stream.dataset.revision), query: stream.templateContent.textContent }
+    stream.targetElements.forEach((box) => box.dispatchEvent(new CustomEvent("querylane:set-query", { detail })))
+  }
+})
+
+export function registerControllers(application) {
+  application.register("querylane--box", BoxController)
+  application.register("querylane--results", ResultsController)
+  application.register("querylane--options", OptionsController)
+  application.register("querylane--suggest", SuggestController)
+}
+
+export { BoxController, OptionsController, ResultsController, SuggestController }

data/app/javascript/querylane/overlay.js

@@ -0,0 +1,46 @@
+// Paints the decorative overlay behind the transparent input text: operator
+// keys coloured, masked runs shown as dots (same width: the font is
+// monospace), the server's error range underlined. Uses textContent only.
+const TOKEN = /(-?)([A-Za-z][A-Za-z0-9_]*:)|\b(OR|NOT)\b|([()])/g
+
+export function paint(overlay, input, { mask = "", error = null } = {}) {
+  const text = input.value
+  // One entry per UTF-16 unit, matching regexp indexes and input positions.
+  const classes = Array.from({ length: text.length }, () => new Set())
+
+  for (const match of text.matchAll(TOKEN)) {
+    const start = match.index + (match[1] ? match[1].length : 0)
+    const kind = match[2] ? "ql-tok-key" : "ql-tok-op"
+    if (match[1]) classes[match.index].add("ql-tok-op")
+    for (let i = start; i < match.index + match[0].length; i++) classes[i].add(kind)
+  }
+  if (mask) {
+    for (const match of text.matchAll(new RegExp(mask, "g"))) {
+      for (let i = match.index; i < match.index + match[0].length; i++) if (/[0-9A-Za-z]/.test(text[i])) classes[i].add("ql-tok-mask")
+    }
+  }
+  if (error) for (let i = error[0]; i < Math.min(error[1], text.length); i++) classes[i].add("ql-tok-error")
+
+  overlay.replaceChildren(...runs(text, classes))
+  overlay.scrollLeft = input.scrollLeft
+}
+
+function runs(text, classes) {
+  const spans = []
+  let start = 0
+  for (let i = 1; i <= text.length; i++) {
+    if (i < text.length && same(classes[i], classes[start])) continue
+    const span = document.createElement("span")
+    const names = Array.from(classes[start])
+    if (names.length) span.className = names.join(" ")
+    const chunk = text.slice(start, i)
+    span.textContent = names.includes("ql-tok-mask") ? chunk.replace(/[0-9A-Za-z]/g, "•") : chunk
+    spans.push(span)
+    start = i
+  }
+  return spans
+}
+
+function same(a, b) {
+  return a.size === b.size && [...a].every((name) => b.has(name))
+}

data/app/javascript/querylane/package.json

@@ -0,0 +1,7 @@
+{
+    "name"            : "querylane",
+    "version"         : "0.1.0",
+    "type"            : "module",
+    "exports"         : {".": "./index.js", "./*": "./*"},
+    "peerDependencies": {"@github/combobox-nav": "^3.0.0", "@hotwired/stimulus": "^3.2.0", "@hotwired/turbo": "^8.0.0"}
+}

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

@@ -0,0 +1,15 @@
+<%# "Searching for" chips. × removes that term (server rewrites the query). Locals: result, id. %>
+<% if result.chips.any? %>
+  <div class="ql-chips">
+    <span class="ql-chips-label"><%= t("querylane.chips.searching_for") %></span>
+    <% result.chips.each do |chip| %>
+      <span class="ql-chip"><%= chip.label %><button type="submit" form="<%= id %>-form" name="remove" value="<%= chip.index %>"
+        class="ql-chip-remove" aria-label="<%= t("querylane.chips.remove", label: chip.label) %>">&times;</button></span>
+      <% chip.alternatives.each do |alternative| %>
+        <button type="submit" form="<%= id %>-form" name="instead" value="<%= chip.index %>.<%= alternative.index %>" class="ql-link"><%= alternative.label %></button>
+      <% end %>
+    <% end %>
+    <%= render "querylane/help", definition: result.definition, id: id %>
+    <button type="submit" form="<%= id %>-form" name="clear" value="1" class="ql-link"><%= t("querylane.chips.clear") %></button>
+  </div>
+<% end %>

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

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

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

@@ -0,0 +1,17 @@
+<%# No hits: say what found nothing and offer one-click ways to widen. Locals: result, id. %>
+<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>
+    <% 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>
+    <% 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>
+    <% end %>
+  </div>
+  <p class="ql-facet-note"><%= t("querylane.states.empty_note") %></p>
+</div>

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

@@ -0,0 +1,30 @@
+<%# 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">
+  <% result.facets.each do |facet| %>
+    <section class="ql-facet">
+      <h3 class="ql-facet-title"><%= facet.label %></h3>
+      <% if facet.failed %>
+        <div class="ql-facet-note"><%= t("querylane.facets.unavailable") %></div>
+      <% else %>
+        <% shown = facet.values.select { |value| value.ticked || value.count.positive? } %>
+        <% if facet.search && shown.size > facet.show.to_i %>
+          <input type="search" class="form-control form-control-sm ql-facet-find" autocomplete="off"
+                 aria-label="<%= t("querylane.facets.find_label", facet: facet.label) %>" placeholder="<%= t("querylane.facets.find", facet: facet.label.downcase) %>"
+                 data-action="input->querylane--results#findValue">
+        <% end %>
+        <% shown.each_with_index do |value, position| %>
+          <% beyond = facet.show && position >= facet.show && !value.ticked %>
+          <button type="submit" form="<%= id %>-form" name="toggle" value="<%= facet.key %>:<%= value.value %>"
+                  class="ql-facet-value" role="checkbox" aria-checked="<%= value.ticked %>" <%= "hidden" if beyond %>
+                  <%= tag.attributes(data: {querylane_beyond: (true if beyond)}) %>>
+            <span class="ql-check" aria-hidden="true"></span>
+            <span class="ql-facet-label"><%= value.label %></span>
+            <span class="ql-facet-count"><%= "~" if facet.approximate %><%= number_with_delimiter(value.count) %></span>
+          </button>
+        <% end %>
+      <% end %>
+    </section>
+  <% end %>
+  <p class="ql-facet-note"><%= t("querylane.facets.note") %></p>
+</aside>

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

@@ -0,0 +1,15 @@
+<%# Before anything is typed: what to type, with the definition's examples. Locals: definition. %>
+<div class="ql-first-load">
+  <div class="ql-first-load-lead">
+    <h2><%= t("querylane.states.first_load_title") %></h2>
+    <p><%= t("querylane.states.first_load") %></p>
+  </div>
+  <% if definition.examples.any? %>
+    <div class="ql-first-load-examples">
+      <div class="ql-facet-title"><%= t("querylane.states.try") %></div>
+      <% definition.examples.each do |example| %>
+        <div class="ql-example"><code><%= example.query %></code><span><%= example.description %></span></div>
+      <% end %>
+    </div>
+  <% end %>
+</div>

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

@@ -0,0 +1,46 @@
+<%# 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",
+             querylane__box_debounce_value: Querylane.configuration.debounce_ms,
+             querylane__box_mask_value: mask.to_s,
+             querylane__box_frame_value: "#{id}-results",
+             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). %>
+  <button type="submit" hidden tabindex="-1" aria-hidden="true"></button>
+  <%= hidden_field_tag :revision, result.revision, id: nil, data: {querylane__box_target: "revision"} %>
+  <div class="ql-box" id="<%= id %>-box" data-querylane--box-target="box" data-action="querylane:set-query->querylane--box#setQuery">
+    <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>
+      <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(" ") %>"
+             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>
+    <span class="ql-box-busy-label" aria-hidden="true"><%= t("querylane.states.searching") %></span>
+    <button type="button" class="ql-box-clear" aria-label="<%= t("querylane.box.clear") %>" data-action="querylane--box#clear">&times;</button>
+    <%= extra %>
+    <% if result.definition.saved_store %>
+      <%# Filled star only while the box holds one of the user's saved searches. %>
+      <button type="button" class="ql-box-saved" popovertarget="<%= id %>-saved" aria-pressed="<%= result.saved_active? %>"
+              data-querylane--box-target="saved">
+        <span class="ql-star-off" aria-hidden="true">☆</span><span class="ql-star-on" aria-hidden="true">★</span> <%= t("querylane.saved.button") %>
+      </button>
+    <% end %>
+    <% if options %>
+      <%# Opens the panel; while it is open, a click closes it (a plain search). %>
+      <button type="submit" name="options" value="1" class="ql-box-options" aria-expanded="<%= result.options_open? %>" aria-controls="<%= id %>-options"
+              data-querylane--box-target="options" data-action="querylane--box#toggleOptions">
+        <svg viewBox="0 0 20 20" width="16" height="16" aria-hidden="true"><path d="M3 5h8M15 5h2M3 10h2M9 10h8M3 15h10M17 15h0" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/><circle cx="13" cy="5" r="2" fill="none" stroke="currentColor" stroke-width="1.6"/><circle cx="7" cy="10" r="2" fill="none" stroke="currentColor" stroke-width="1.6"/><circle cx="15" cy="15" r="2" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>
+        <%= 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>
+  </div>
+  <% if help %><p class="ql-box-help" id="<%= id %>-help-text"><%= 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 %>

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

@@ -0,0 +1,21 @@
+<%# 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. %>
+<% token = presenter.group_token(group) %>
+<div class="ql-group" <%= tag.attributes(data: {querylane_group: token}) %>>
+  <div class="ql-group-head">
+    <div class="ql-group-title"><%= presenter.title(group) %></div>
+    <% if (subtitle = presenter.subtitle(group)) %><div class="ql-group-subtitle"><%= subtitle %></div><% end %>
+    <% if (note = presenter.note(group)) %><div class="ql-group-note"><%= note %></div><% end %>
+  </div>
+  <% group.hits.each do |hit| %>
+    <%= render "querylane/record", presenter: presenter, hit: hit, columns: columns %>
+  <% end %>
+  <% if token && (more = presenter.more_count(group)) %>
+    <details class="ql-more" data-action="toggle->querylane--results#more">
+      <summary class="ql-link"><span class="ql-more-open"><%= t("querylane.group.more", count: more) %></span><span class="ql-more-hide"><%= t("querylane.group.hide") %></span></summary>
+      <button type="submit" form="<%= presenter.id %>-form" name="group" value="<%= token %>" hidden tabindex="-1"
+              data-turbo-frame="<%= presenter.related_frame_id(group) %>" data-querylane-more></button>
+      <turbo-frame id="<%= presenter.related_frame_id(group) %>" class="ql-related"></turbo-frame>
+    </details>
+  <% end %>
+</div>

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

@@ -0,0 +1,29 @@
+<%# 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") %>
+<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">
+    <strong><%= t("querylane.help.title") %></strong>
+    <span><%= t("querylane.help.lead") %></span>
+  </div>
+  <dl class="ql-help-list">
+    <% definition.texts.each do |text| %>
+      <dt><%= text.default ? t("querylane.help.words") : "#{text.key}:" %></dt><dd><%= text.label.gsub("%{value}", "…") %><%= " · #{t("querylane.help.masked")}" if text.sensitive %></dd>
+    <% end %>
+    <% definition.filters.each do |filter| %>
+      <dt><%= filter.key %>:</dt><dd><%= filter.label.gsub("%{value}", "…") %><%= " · #{t("querylane.help.masked")}" if filter.sensitive %></dd>
+    <% end %>
+    <% definition.flags.each do |flags| %>
+      <dt><%= ([flags.key] + flags.aliases).map { |key| "#{key}:" }.join(" ") %></dt><dd><%= flags.values.keys.join(", ") %></dd>
+    <% end %>
+    <dt>- NOT OR ( )</dt><dd><%= t("querylane.help.boolean") %></dd>
+  </dl>
+  <% if definition.examples.any? %>
+    <div class="ql-help-examples">
+      <% definition.examples.each do |example| %>
+        <div><code><%= example.query %></code> <span><%= example.description %></span></div>
+      <% end %>
+    </div>
+  <% end %>
+</div>

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

@@ -0,0 +1,32 @@
+<%# 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. %>
+<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">
+  <header class="ql-options-head">
+    <h2 id="<%= id %>-options-title"><%= t("querylane.options.title") %></h2>
+    <span><%= t("querylane.options.lead") %></span>
+  </header>
+  <div class="ql-options-groups">
+    <% result.definition.panel.each do |group| %>
+      <fieldset class="ql-options-group">
+        <% if group.label %><legend><%= group.label %></legend><% end %>
+        <% group.rows.each do |row| %>
+          <%= render "querylane/options_row", row: row, values: result.panel.values, held: result.panel.held, definition: result.definition, id: id %>
+        <% end %>
+      </fieldset>
+    <% end %>
+  </div>
+  <button type="submit" form="<%= id %>-form" name="compose_preview" value="1" data-turbo-frame="<%= id %>-writes" hidden
+          tabindex="-1" data-querylane--options-target="preview"></button>
+  <%= render "querylane/writes", preview: result.preview, id: id %>
+  <footer class="ql-options-foot">
+    <%= 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"
+            data-querylane--options-target="apply"><%= t("querylane.options.search") %></button>
+  </footer>
+</section>