acts_as_calculator_editor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b0730de5b7917653aa2dc71dbf72e481ffccbe0a5c8e739b0e26620b4cd5c0e
+  data.tar.gz: ec17f8bf185a98d896eb0ef88a1d6780da76a0d73645c9da20bb0c1171bfb98e
+SHA512:
+  metadata.gz: 302ab53a61fb1fdde36d9138c7ee2be129659dfb3db0617067c1875a768f6ef4a090e6ffb2dc5feed0a0fe977d547e86b9649d142aa7eaee3d2f76cf9c36839c
+  data.tar.gz: 6e01ac956b1cc1596ee2a1ab6f4d10548f8030b631690aab87f53498ef29fb3b80cd37e3ec994c54df17f4bd1b4eb09cb2f9c99ca1340771e27b1767ec5ae96b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,107 @@
+# ActsAsCalculatorEditor
+
+A mountable Rails engine providing a Hotwire UI for authoring
+[`acts_as_calculator`](https://github.com/lautarograc/acts_as_calculator)
+formulas and templates — CRUD, live validation preview, and JSON export. No
+permissions layer; wire the engine's `current_owner` and route constraints to
+your host app's auth as needed.
+
+This gem never duplicates the core gem's persistence or calculation logic —
+every write goes through `acts_as_calculator`'s own service objects
+(`PublishFormulaVersion`, `PublishTemplate`, `ImportLookupTable`, etc.),
+called in-process rather than over HTTP. See
+[`docs/core-gem-contract.md`](docs/core-gem-contract.md) for the full
+contract this gem is built against.
+
+## Installation
+
+Add both gems (this one is not yet published, so a path or git reference is
+required until it is):
+
+```ruby
+gem "acts_as_calculator"
+gem "acts_as_calculator_editor"
+```
+
+Mount the engine:
+
+```ruby
+# config/routes.rb
+mount ActsAsCalculatorEditor::Engine => "/calculator-editor"
+```
+
+Pin Lexxy in your host's importmap (this gem does not do it for you, since a
+host may use a different JS bundler):
+
+```ruby
+# config/importmap.rb
+pin "lexxy"
+```
+```js
+// app/javascript/application.js
+import "lexxy"
+```
+
+Run `acts_as_calculator`'s own install generator if you haven't already —
+this engine reads and writes its tables directly, it ships no migrations of
+its own.
+
+## The two editors
+
+- **Templates** (`format: "html"`) use [Lexxy](https://github.com/basecamp/lexxy)
+  — a real rich text editor, since template bodies are genuinely prose/HTML
+  meant for a payslip, invoice, or policy document.
+- **Formula expressions** deliberately do **not** use Lexxy. A Dentaku
+  expression like `salary - (salary * federal_2026)` is not prose, and
+  Lexxy's editor value is HTML even in "plain" mode — an expression using `<`
+  without a following space (`salary <bonus`) gets parsed as the start of an
+  HTML tag and silently truncated, producing a shorter expression that still
+  parses as valid Dentaku but computes something different. See
+  [`docs/lexxy-decision.md`](docs/lexxy-decision.md) for the full
+  investigation, including a rejected markdown-based workaround. The formula
+  editor is a plain textarea with a Stimulus-driven syntax-highlighting
+  overlay and live validation instead.
+
+## A note on Lexxy and Rails version
+
+`lexxy` requires Rails ≥ 8.0.2, and this gemspec's floors match that — it
+cannot install against Rails 7.1/7.2 even though `acts_as_calculator` itself
+supports those versions. Lexxy also unconditionally touches `ActionText` at
+boot on Rails 8.0/8.1 (a `to_prepare` hook), regardless of whether any view
+in your app renders rich text — this gem requires `action_text/engine`
+itself to guarantee that's loaded, but if your host app hand-picks railties
+rather than requiring `rails/all`, be aware Action Text (and transitively,
+Active Storage) will load as a result of installing this gem.
+
+Lexxy also sets `config.lexxy.override_action_text_defaults = true` on Rails
+8.0/8.1, which aliases `rich_text_area` to its own helper **globally** — if
+your host app has its own Action Text fields and doesn't want them swapped to
+Lexxy, set that config to `false` yourself. This gem doesn't set it (a third
+gem changing a host-level setting silently would be worse than the problem).
+
+## Export / import
+
+`GET /export` produces the same JSON document shape `acts_as_calculator`'s
+own generator/rake task import, with `?key=`, `?scope=`, `?full_history=`,
+and `?disposition=` query params — see
+[`docs/core-gem-contract.md`](docs/core-gem-contract.md) for the exact
+shape and the deliberate differences from the core gem's API response
+serializers. There is no import UI yet; use the core gem's own
+`rails generate acts_as_calculator:import` or `POST /import` (if
+`enable_api` is on) to bring a document back in.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+The dummy app lives at `spec/dummy` and builds its schema by running
+`acts_as_calculator`'s own install-generator migration, so an upstream
+column rename shows up as a red spec here rather than silent drift.
+
+See `docs/` for the full integration contract and the Lexxy decision
+writeup, and `.claude/` for the harness (agents + skills) that built this
+gem — read `CLAUDE.md` for the pointer and change log.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/javascripts/acts_as_calculator_editor/application.js

@@ -0,0 +1,26 @@
+// Entry point for this engine's JavaScript, loaded by the layout with
+// `javascript_import_module_tag "acts_as_calculator_editor/application"`.
+//
+// It starts its OWN Stimulus application rather than registering onto the host's. Two
+// reasons: a host may not run Stimulus at all, and even when it does, its controller
+// identifiers are its own namespace — registering "expression-editor" into a shared
+// application would be this gem reaching into the host app's registry to claim a name.
+//
+// The root element is the layout's `<body class="acts-as-calculator-editor">`, so nothing
+// outside this engine's own pages is ever scanned.
+
+import { Application } from "@hotwired/stimulus"
+import ExpressionEditorController from "acts_as_calculator_editor/expression_editor_controller"
+import TemplateEditorController from "acts_as_calculator_editor/template_editor_controller"
+import ListFilterController from "acts_as_calculator_editor/list_filter_controller"
+
+const root = document.querySelector(".acts-as-calculator-editor") || document.documentElement
+
+const application = Application.start(root)
+application.debug = false
+
+application.register("expression-editor", ExpressionEditorController)
+application.register("template-editor", TemplateEditorController)
+application.register("list-filter", ListFilterController)
+
+export { application }

data/app/assets/javascripts/acts_as_calculator_editor/dentaku_tokenizer.js

@@ -0,0 +1,139 @@
+// A tokenizer for Dentaku expressions, used for the syntax-highlighting overlay and for
+// working out what word the caret sits in for autocomplete.
+//
+// This is deliberately NOT a parser. It never decides whether an expression is valid — the
+// server does that, through the real Dentaku parser with the real function registry
+// (POST /validations). Anything this file concludes is a colouring hint, and a wrong hint
+// must never be able to change the submitted string.
+//
+// Operator set is docs/core-gem-contract.md §5, verified there against Dentaku 4.0.2:
+//   + - * / % ^   < > <= >= == = !=   and or && ||
+// Note `<` and `>` are ordinary operators here. That is the whole reason this field is a
+// textarea and not a rich text editor (docs/lexxy-decision.md §3) — an HTML round-trip eats
+// `salary <bonus` down to `salary `, silently, and it still parses.
+
+// Longest-first: `<=` must be tried before `<`, or `a <= b` lexes as `<` then `=`.
+const OPERATORS = [
+  "<=", ">=", "==", "!=", "&&", "||",
+  "+", "-", "*", "/", "%", "^", "<", ">", "="
+]
+
+// Word-shaped operators and literals. `and`/`or` are operators in Dentaku, not functions.
+const WORD_OPERATORS = new Set([ "and", "or" ])
+const LITERALS = new Set([ "true", "false" ])
+
+const IDENTIFIER_START = /[A-Za-z_]/
+const IDENTIFIER_CHAR = /[A-Za-z0-9_]/
+const DIGIT = /[0-9]/
+
+// Dentaku is case-insensitive (BuildCalculator defaults to `case_sensitive: false`), so every
+// name comparison here folds case — matching what the server reports back in `identifiers`.
+export function normalize(name) {
+  return String(name).toLowerCase()
+}
+
+export function tokenize(source) {
+  const tokens = []
+  const text = String(source ?? "")
+  let i = 0
+
+  const push = (type, start, end) => tokens.push({ type, start, end, value: text.slice(start, end) })
+
+  while (i < text.length) {
+    const char = text[i]
+
+    if (char === " " || char === "\t" || char === "\n" || char === "\r") {
+      const start = i
+      while (i < text.length && /\s/.test(text[i])) i++
+      push("whitespace", start, i)
+      continue
+    }
+
+    // Strings. An unterminated quote runs to end-of-input and is tagged so the overlay can
+    // show it as broken without claiming to know why.
+    if (char === "'" || char === '"') {
+      const start = i
+      const quote = char
+      i++
+      while (i < text.length && text[i] !== quote) i++
+      const terminated = i < text.length
+      if (terminated) i++
+      push(terminated ? "string" : "unterminated-string", start, i)
+      continue
+    }
+
+    if (DIGIT.test(char) || (char === "." && DIGIT.test(text[i + 1] ?? ""))) {
+      const start = i
+      while (i < text.length && DIGIT.test(text[i])) i++
+      if (text[i] === ".") {
+        i++
+        while (i < text.length && DIGIT.test(text[i])) i++
+      }
+      push("number", start, i)
+      continue
+    }
+
+    if (IDENTIFIER_START.test(char)) {
+      const start = i
+      while (i < text.length && IDENTIFIER_CHAR.test(text[i])) i++
+      const word = text.slice(start, i)
+      const folded = normalize(word)
+
+      if (WORD_OPERATORS.has(folded)) {
+        push("operator", start, i)
+      } else if (LITERALS.has(folded)) {
+        push("literal", start, i)
+      } else {
+        // A name immediately followed by `(` is a call. Whitespace between the two is legal
+        // Dentaku, so skip it before deciding.
+        let lookahead = i
+        while (lookahead < text.length && /\s/.test(text[lookahead])) lookahead++
+        push(text[lookahead] === "(" ? "function" : "identifier", start, i)
+      }
+      continue
+    }
+
+    if (char === "(" || char === ")") {
+      push("paren", i, i + 1)
+      i++
+      continue
+    }
+
+    if (char === ",") {
+      push("comma", i, i + 1)
+      i++
+      continue
+    }
+
+    const operator = OPERATORS.find((candidate) => text.startsWith(candidate, i))
+    if (operator) {
+      push("operator", i, i + operator.length)
+      i += operator.length
+      continue
+    }
+
+    // Anything unrecognised is still emitted, so the overlay's concatenated text is always
+    // byte-for-byte the textarea's text. If that ever stops being true the overlay drifts out
+    // of alignment with the caret, which is the one bug this design can actually produce.
+    push("unknown", i, i + 1)
+    i++
+  }
+
+  return tokens
+}
+
+// The identifier the caret is sitting inside or at the end of, for autocomplete. Returns
+// null when the caret is not in a word (so typing `1 + ` does not open a menu).
+export function wordAt(source, caret) {
+  const text = String(source ?? "")
+  let start = caret
+
+  while (start > 0 && IDENTIFIER_CHAR.test(text[start - 1])) start--
+  if (start === caret) return null
+  if (!IDENTIFIER_START.test(text[start])) return null
+
+  let end = caret
+  while (end < text.length && IDENTIFIER_CHAR.test(text[end])) end++
+
+  return { start, end, value: text.slice(start, caret) }
+}

data/app/assets/javascripts/acts_as_calculator_editor/expression_editor_controller.js

@@ -0,0 +1,380 @@
+import { Controller } from "@hotwired/stimulus"
+import { tokenize, wordAt, normalize } from "acts_as_calculator_editor/dentaku_tokenizer"
+
+// The formula `expression` field.
+//
+// Three jobs, none of which may ever alter the submitted string:
+//   1. a syntax-highlighting overlay (a <pre> behind a transparent <textarea>)
+//   2. debounced validation against POST /validations
+//   3. autocomplete over the function list and the declared variable names
+//
+// The textarea IS the field. It keeps its `name` and `id`, it is never replaced, and nothing
+// here writes to `value` except the autocomplete accept path — which splices at exact offsets
+// and leaves the rest of the string untouched. This is the whole point of
+// docs/lexxy-decision.md §3: the value that reaches the server is the string the operator
+// typed, character for character.
+// Every field of a variable row, in the sibling section of the form. Kept as one selector so
+// the delegated listener and the readers below cannot drift apart.
+const VARIABLE_FIELD = '[name^="version[variables]"]'
+const VARIABLE_NAME_FIELD = 'input[name^="version[variables]"][name$="[name]"]'
+
+export default class extends Controller {
+  static targets = [ "input", "highlight", "status", "suggestions" ]
+
+  static values = {
+    validateUrl: String,
+    functions: { type: Array, default: [] },
+    scope: { type: String, default: "" },
+    delay: { type: Number, default: 400 }
+  }
+
+  connect() {
+    this.debounceTimer = null
+    this.inFlight = null
+    this.activeSuggestion = -1
+    this.suggestions = []
+
+    // The variable rows are NOT inside this controller's element — they are a sibling section
+    // of the same <form>. A Stimulus `data-action` only routes to a controller found on an
+    // ancestor, so `input->expression-editor#onVariablesChanged` written on those fields never
+    // fires; declaring a variable left a stale "not declared as a variable" error on screen
+    // until the expression itself was touched again. This controller already reaches out to
+    // the form to READ those fields (`variableNameFields`), so it listens out there too,
+    // delegated from the form rather than bound per row — the row count is not fixed.
+    this.variablesListener = (event) => {
+      if (event.target?.matches?.(VARIABLE_FIELD)) this.onVariablesChanged()
+    }
+
+    this.form = this.element.closest("form")
+    this.form?.addEventListener("input", this.variablesListener)
+    this.form?.addEventListener("change", this.variablesListener)
+
+    this.render()
+    this.scheduleValidation({ immediate: true })
+  }
+
+  disconnect() {
+    clearTimeout(this.debounceTimer)
+    this.inFlight?.abort()
+
+    this.form?.removeEventListener("input", this.variablesListener)
+    this.form?.removeEventListener("change", this.variablesListener)
+  }
+
+  // --- input plumbing ------------------------------------------------------------------
+
+  onInput() {
+    this.render()
+    this.refreshSuggestions()
+    this.scheduleValidation()
+  }
+
+  // Declared variable names live in sibling form rows the operator edits on this same page,
+  // so they are re-read rather than cached: renaming a variable should re-colour the
+  // expression and re-validate it without a reload.
+  onVariablesChanged() {
+    this.render()
+    this.scheduleValidation()
+  }
+
+  syncScroll() {
+    if (!this.hasHighlightTarget) return
+
+    this.highlightTarget.scrollTop = this.inputTarget.scrollTop
+    this.highlightTarget.scrollLeft = this.inputTarget.scrollLeft
+  }
+
+  // --- highlighting --------------------------------------------------------------------
+
+  render() {
+    if (!this.hasHighlightTarget) return
+
+    const declared = this.declaredNames()
+    const known = new Set(this.functionsValue.map(normalize))
+    const source = this.inputTarget.value
+
+    const html = tokenize(source).map((token) => {
+      const classes = [ `aac-tok aac-tok--${token.type}` ]
+
+      if (token.type === "identifier" && !declared.has(normalize(token.value))) {
+        classes.push("aac-tok--undeclared")
+      }
+      if (token.type === "function" && known.size > 0 && !known.has(normalize(token.value))) {
+        classes.push("aac-tok--unknown-function")
+      }
+
+      return `<span class="${classes.join(" ")}">${escapeHtml(token.value)}</span>`
+    }).join("")
+
+    // The trailing newline keeps a final "\n" in the textarea from collapsing the <pre>'s
+    // last line, which would put the overlay one line out of step with the caret.
+    this.highlightTarget.innerHTML = `${html}\n`
+    this.syncScroll()
+  }
+
+  declaredNames() {
+    return new Set(this.variableNameFields().map((field) => normalize(field.value)).filter(Boolean))
+  }
+
+  variableNameFields() {
+    if (!this.form) return []
+
+    return Array.from(this.form.querySelectorAll(VARIABLE_NAME_FIELD))
+  }
+
+  // --- validation ----------------------------------------------------------------------
+
+  scheduleValidation({ immediate = false } = {}) {
+    clearTimeout(this.debounceTimer)
+
+    if (!this.hasValidateUrlValue) return
+
+    this.debounceTimer = setTimeout(() => this.validate(), immediate ? 0 : this.delayValue)
+  }
+
+  async validate() {
+    const expression = this.inputTarget.value
+
+    // Nothing typed yet is not a problem worth shouting about — the server would call it
+    // `blank`, which is true but not useful on an untouched form.
+    if (expression.trim() === "") {
+      this.serverIdentifiers = []
+      this.renderStatus(null)
+      return
+    }
+
+    this.inFlight?.abort()
+    this.inFlight = new AbortController()
+
+    const payload = {
+      expression,
+      scope: this.scopeValue,
+      variables: this.variableRows()
+    }
+
+    try {
+      const response = await fetch(this.validateUrlValue, {
+        method: "POST",
+        signal: this.inFlight.signal,
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "X-CSRF-Token": csrfToken()
+        },
+        body: JSON.stringify(payload)
+      })
+
+      const result = await response.json()
+      this.serverIdentifiers = Array.isArray(result.identifiers) ? result.identifiers : []
+      this.renderStatus(result)
+    } catch (error) {
+      if (error.name === "AbortError") return
+
+      // A failed check is not a failed expression. Say which one it was.
+      this.renderStatus({ unreachable: true })
+    }
+  }
+
+  // Mirrors the row shape in _workspace/03_rails_report.md §3. `required` is sent as a real
+  // boolean rather than "1"/"0" because this payload is JSON, not a form post — but the name
+  // is the only field validation actually reads.
+  variableRows() {
+    const form = this.form
+    if (!form) return []
+
+    return this.variableNameFields().map((field) => {
+      const prefix = field.name.replace(/\[name\]$/, "")
+      const sourceType = form.querySelector(`[name="${prefix}[source_type]"]`)
+      const config = form.querySelector(`[name="${prefix}[source_config]"]`)
+      const required = form.querySelector(`input[type="checkbox"][name="${prefix}[required]"]`)
+
+      return {
+        name: field.value,
+        source_type: sourceType?.value || "context",
+        source_config: config?.value || "",
+        required: required ? required.checked : true
+      }
+    }).filter((row) => row.name.trim() !== "")
+  }
+
+  renderStatus(result) {
+    if (!this.hasStatusTarget) return
+
+    if (result === null) {
+      this.statusTarget.innerHTML = ""
+      return
+    }
+
+    if (result.unreachable) {
+      this.statusTarget.innerHTML = message("aac-status--unknown", "Could not reach the checker — the expression itself has not been judged.")
+      return
+    }
+
+    // The endpoint has TWO response shapes and both have to be handled here. The 200 shape is
+    // `{valid, errors, warnings, identifiers}`; anything ApplicationController rescues comes
+    // back as `{error: {type, message}}` with a 4xx — most reachably a 422 from
+    // `CastVariableRows`, which raises while a `source_config` is half-typed
+    // (`{"table":` is not yet a JSON object). Reading only the 200 shape left `parts` empty,
+    // so the status region silently blanked mid-keystroke and never said why.
+    if (result.error) {
+      this.statusTarget.innerHTML = message("aac-status--error", result.error.message || "The checker rejected this request.")
+      return
+    }
+
+    const parts = []
+
+    if (result.valid) {
+      // Carefully worded, per contract §7.10 and the Rails report's note: this endpoint sees
+      // syntax, declared names and lookup-table existence. It cannot see whether an
+      // `attribute` or `method` variable resolves against the host's model, because that
+      // needs a real record. Saying "valid" here would be a claim the check did not make.
+      parts.push(message("aac-status--ok", "Syntax and variable wiring check out. Attribute and method variables are only verified against real data when the formula runs."))
+    }
+
+    for (const error of result.errors || []) {
+      parts.push(message("aac-status--error", error.message))
+    }
+    for (const warning of result.warnings || []) {
+      parts.push(message("aac-status--warning", warning.message))
+    }
+
+    this.statusTarget.innerHTML = parts.join("")
+    this.render()
+  }
+
+  // --- autocomplete --------------------------------------------------------------------
+
+  refreshSuggestions() {
+    const word = wordAt(this.inputTarget.value, this.inputTarget.selectionStart)
+
+    if (!word || word.value.length === 0) return this.closeSuggestions()
+
+    const needle = normalize(word.value)
+    const declared = Array.from(this.declaredNames())
+
+    const candidates = [
+      ...declared.map((name) => ({ name, kind: "variable" })),
+      ...this.functionsValue.map((name) => ({ name, kind: "function" }))
+    ]
+
+    const seen = new Set()
+    this.suggestions = candidates
+      .filter(({ name }) => {
+        const folded = normalize(name)
+        if (!folded.startsWith(needle) || folded === needle || seen.has(folded)) return false
+        seen.add(folded)
+        return true
+      })
+      .slice(0, 8)
+
+    if (this.suggestions.length === 0) return this.closeSuggestions()
+
+    this.wordRange = word
+    this.activeSuggestion = 0
+    this.renderSuggestions()
+  }
+
+  renderSuggestions() {
+    if (!this.hasSuggestionsTarget) return
+
+    this.suggestionsTarget.innerHTML = this.suggestions.map((suggestion, index) => `
+      <li role="option" id="aac-suggestion-${index}" aria-selected="${index === this.activeSuggestion}"
+          class="aac-suggestion ${index === this.activeSuggestion ? "is-active" : ""}"
+          data-index="${index}"
+          data-action="mousedown->expression-editor#pick">
+        <span class="aac-suggestion__name">${escapeHtml(suggestion.name)}</span>
+        <span class="aac-suggestion__kind">${suggestion.kind}</span>
+      </li>
+    `).join("")
+
+    this.suggestionsTarget.hidden = false
+    this.inputTarget.setAttribute("aria-expanded", "true")
+    this.inputTarget.setAttribute("aria-activedescendant", `aac-suggestion-${this.activeSuggestion}`)
+  }
+
+  closeSuggestions() {
+    this.suggestions = []
+    this.activeSuggestion = -1
+
+    if (this.hasSuggestionsTarget) {
+      this.suggestionsTarget.hidden = true
+      this.suggestionsTarget.innerHTML = ""
+    }
+
+    this.inputTarget.setAttribute("aria-expanded", "false")
+    this.inputTarget.removeAttribute("aria-activedescendant")
+  }
+
+  onKeydown(event) {
+    if (this.suggestions.length === 0) return
+
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault()
+        this.activeSuggestion = (this.activeSuggestion + 1) % this.suggestions.length
+        this.renderSuggestions()
+        break
+      case "ArrowUp":
+        event.preventDefault()
+        this.activeSuggestion = (this.activeSuggestion - 1 + this.suggestions.length) % this.suggestions.length
+        this.renderSuggestions()
+        break
+      case "Enter":
+      case "Tab":
+        // Only swallow the key while the menu is genuinely open, so Enter still submits the
+        // form and Tab still moves on when it is not.
+        event.preventDefault()
+        this.accept(this.activeSuggestion)
+        break
+      case "Escape":
+        event.preventDefault()
+        this.closeSuggestions()
+        break
+    }
+  }
+
+  pick(event) {
+    // mousedown, not click: the textarea would blur first and close the menu.
+    event.preventDefault()
+    this.accept(Number(event.currentTarget.dataset.index))
+  }
+
+  accept(index) {
+    const suggestion = this.suggestions[index]
+    if (!suggestion || !this.wordRange) return this.closeSuggestions()
+
+    const { start, end } = this.wordRange
+    const source = this.inputTarget.value
+    const insert = suggestion.kind === "function" ? `${suggestion.name}(` : suggestion.name
+
+    this.inputTarget.value = source.slice(0, start) + insert + source.slice(end)
+    const caret = start + insert.length
+    this.inputTarget.setSelectionRange(caret, caret)
+
+    this.closeSuggestions()
+    this.inputTarget.focus()
+    this.render()
+    this.scheduleValidation()
+  }
+
+  onBlur() {
+    // Deferred so a mousedown on a suggestion still lands.
+    setTimeout(() => this.closeSuggestions(), 120)
+  }
+}
+
+function message(className, text) {
+  return `<p class="aac-status ${className}">${escapeHtml(text)}</p>`
+}
+
+function csrfToken() {
+  return document.querySelector('meta[name="csrf-token"]')?.content || ""
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}