add auto-completion for narration (#1888)

Co-authored-by: Jakob Schnitzer <[email protected]>

Author: dtrai2

frontend/src/api/index.ts

@@ -75,6 +75,8 @@ interface GetAPIParams {
   options: undefined;
   payee_accounts: { payee: string };
   payee_transaction: { payee: string };
+  narration_transaction: { narration: string };
+  narrations: undefined;
   query: Filters & { query_string: string };
   source: { filename: string };
 }

frontend/src/api/validators.ts

@@ -196,6 +196,8 @@ export const getAPIValidators = {
   }),
   payee_accounts: array(string),
   payee_transaction: Transaction.validator,
+  narration_transaction: Transaction.validator,
+  narrations: array(string),
   query: query_validator,
   source,
   trial_balance: tree_report,

frontend/src/entry-forms/Transaction.svelte

@@ -39,6 +39,19 @@
   });
 
   let narration = $derived(entry.get_narration_tags_links());
+  let narration_suggestions: string[] = $state.raw([]);
+  $effect(() => {
+    get("narrations")
+      .then((s) => {
+        narration_suggestions = s;
+      })
+      .catch((error: unknown) => {
+        notify_err(
+          error,
+          (err) => `Fetching narration suggestions failed: ${err.message}`,
+        );
+      });
+  });
 
   // Autofill complete transactions.
   async function autocompleteSelectPayee() {
@@ -50,6 +63,16 @@
     });
     entry = payee_transaction.set("date", entry.date);
   }
+  async function autocompleteSelectNarration() {
+    if (entry.payee || entry.postings.every((p) => !p.is_empty())) {
+      return;
+    }
+    const data = await get("narration_transaction", {
+      narration: narration,
+    });
+    entry = data;
+    narration = entry.get_narration_tags_links();
+  }
 
   // Always have one empty posting at the end.
   $effect(() => {
@@ -99,13 +122,14 @@
     </label>
     <label>
       <span>{_("Narration")}:</span>
-      <input
-        type="text"
-        name="narration"
+      <AutocompleteInput
+        className="narration"
         placeholder={_("Narration")}
-        value={narration}
-        onchange={({ currentTarget }) => {
-          entry = entry.set_narration_tags_links(currentTarget.value);
+        bind:value={narration}
+        suggestions={narration_suggestions}
+        onSelect={autocompleteSelectNarration}
+        onBlur={() => {
+          entry = entry.set_narration_tags_links(narration);
         }}
       />
       <AddMetadataButton
@@ -168,11 +192,6 @@
     flex-basis: 100px;
   }
 
-  input[name="narration"] {
-    flex-grow: 1;
-    flex-basis: 200px;
-  }
-
   label > span:first-child,
   .label > span:first-child {
     display: none;

src/fava/core/attributes.py

@@ -124,3 +124,20 @@ def payee_transaction(self, payee: str) -> Transaction | None:
             if txn.payee == payee:
                 return txn
         return None
+
+    def narration_transaction(self, narration: str) -> Transaction | None:
+        """Get the last transaction for a narration."""
+        transactions = self.ledger.all_entries_by_type.Transaction
+        for txn in reversed(transactions):
+            if txn.narration == narration:
+                return txn
+        return None
+
+    @property
+    def narrations(self) -> Sequence[str]:
+        """Get the narrations of all transactions."""
+        narration_ranker = ExponentialDecayRanker()
+        for txn in self.ledger.all_entries_by_type.Transaction:
+            if txn.narration:
+                narration_ranker.update(txn.narration, txn.date)
+        return narration_ranker.sort()

src/fava/json_api.py

@@ -345,6 +345,19 @@ def get_payee_transaction(payee: str) -> Any:
     return serialise(entry) if entry else None
 
 
+@api_endpoint
+def get_narration_transaction(narration: str) -> Any:
+    """Last transaction for the given narration."""
+    entry = g.ledger.attributes.narration_transaction(narration)
+    return serialise(entry) if entry else None
+
+
+@api_endpoint
+def get_narrations() -> Sequence[str]:
+    """List of all narrations in the ledger."""
+    return g.ledger.attributes.narrations
+
+
 @api_endpoint
 def get_source(filename: str) -> Mapping[str, str]:
     """Load one of the source files."""

tests/__snapshots__/test_core_attributes-test_narrations.json

@@ -0,0 +1,37 @@
+[
+  "Investing 40% of cash in VBMPX",
+  "Investing 60% of cash in RGAGX",
+  "Payroll",
+  "Buying groceries",
+  "Eating out alone",
+  "Employer match for contribution",
+  "Eating out with Julie",
+  "Eating out ",
+  "Eating out after work",
+  "Eating out with Bill",
+  "Eating out with Natasha",
+  "Monthly bank fee",
+  "Paying off credit card",
+  "Eating out with Joe",
+  "Paying the rent",
+  "Tram tickets",
+  "Eating out with work buddies",
+  "Buy shares of VEA",
+  "Buy shares of GLD",
+  "Dividends on portfolio",
+  "Transfering accumulated savings to other account",
+  "Buy shares of ITOT",
+  "Buy shares of VHT",
+  "Consume vacation days",
+  "Sell shares of GLD",
+  "STATE TAX & FINANC PYMT",
+  "FEDERAL TAXPYMT",
+  "Allowed contributions for one year",
+  "Sell shares of VEA",
+  "Filing taxes for 2015",
+  "Sell shares of VHT",
+  "Sell shares of ITOT",
+  "Filing taxes for 2014",
+  "Opening Balance for checking account",
+  "\u00c1rv\u00edzt\u0171r\u0151 t\u00fck\u00f6rf\u00far\u00f3g\u00e9p"
+]

tests/__snapshots__/test_json_api-test_api-narrations.json

@@ -0,0 +1,37 @@
+[
+  "Investing 40% of cash in VBMPX",
+  "Investing 60% of cash in RGAGX",
+  "Payroll",
+  "Buying groceries",
+  "Eating out alone",
+  "Employer match for contribution",
+  "Eating out with Julie",
+  "Eating out ",
+  "Eating out after work",
+  "Eating out with Bill",
+  "Eating out with Natasha",
+  "Monthly bank fee",
+  "Paying off credit card",
+  "Eating out with Joe",
+  "Paying the rent",
+  "Tram tickets",
+  "Eating out with work buddies",
+  "Buy shares of VEA",
+  "Buy shares of GLD",
+  "Dividends on portfolio",
+  "Transfering accumulated savings to other account",
+  "Buy shares of ITOT",
+  "Buy shares of VHT",
+  "Consume vacation days",
+  "Sell shares of GLD",
+  "STATE TAX & FINANC PYMT",
+  "FEDERAL TAXPYMT",
+  "Allowed contributions for one year",
+  "Sell shares of VEA",
+  "Filing taxes for 2015",
+  "Sell shares of VHT",
+  "Sell shares of ITOT",
+  "Filing taxes for 2014",
+  "Opening Balance for checking account",
+  "\u00c1rv\u00edzt\u0171r\u0151 t\u00fck\u00f6rf\u00far\u00f3g\u00e9p"
+]

tests/test_core_attributes.py

@@ -9,6 +9,8 @@
     from fava.beans.abc import Directive
     from fava.core import FavaLedger
 
+    from .conftest import SnapshotFunc
+
 
 def test_get_active_years(load_doc_entries: list[Directive]) -> None:
     """
@@ -63,3 +65,21 @@ def test_payee_transaction(example_ledger: FavaLedger) -> None:
     txn = attr.payee_transaction("BayBook")
     assert txn
     assert str(txn.date) == "2016-05-05"
+
+
+def test_narration_transaction(example_ledger: FavaLedger) -> None:
+    attr = example_ledger.attributes
+    assert attr.narration_transaction("NOTANARRATION") is None
+
+    txn = attr.narration_transaction("Monthly bank fee")
+    assert txn
+    assert str(txn.date) == "2016-05-04"
+
+
+def test_narrations(
+    example_ledger: FavaLedger,
+    snapshot: SnapshotFunc,
+) -> None:
+    narrations = example_ledger.attributes.narrations
+    assert narrations
+    snapshot(narrations, json=True)

tests/test_json_api.py

@@ -337,6 +337,21 @@ def test_api_payee_transaction(
     snapshot(data, json=True)
 
 
+def test_api_narration_transaction(
+    test_client: FlaskClient,
+) -> None:
+    response = test_client.get(
+        "/long-example/api/narration_transaction",
+        query_string={"narration": "Buying groceries"},
+    )
+    data = assert_api_success(response)
+    assert data["date"] == "2016-04-21"
+    assert data["narration"] == "Buying groceries"
+    assert data["payee"] == "Farmer Fresh"
+    assert len(data["postings"]) == 2
+    assert data["t"] == "Transaction"
+
+
 def test_api_imports(
     test_client: FlaskClient,
     snapshot: SnapshotFunc,
@@ -769,6 +784,7 @@ def test_api_filter_error(
         ("documents", "/example/api/documents"),
         ("events", "/long-example/api/events"),
         ("income_statement", "/long-example/api/income_statement?time=2014"),
+        ("narrations", "/long-example/api/narrations"),
         ("trial_balance", "/long-example/api/trial_balance?time=2014"),
         ("balance_sheet", "/long-example/api/balance_sheet"),
         (