Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

feat(transactions): suggest past descriptions when typing one (#1129)

Rogerio Camorim8276f3656e80
diff --git a/backend/app/api/transactions.py b/backend/app/api/transactions.py
index 4a209d25..ee296cc6 100644
--- a/backend/app/api/transactions.py
+++ b/backend/app/api/transactions.py
@@ -16,7 +16,7 @@ from app.core.workspace_context import (
current_workspace,
current_writable_workspace,
)
-from app.schemas.transaction import BulkAddToGroupRequest, BulkCategorizeRequest, BulkTagsRequest, CreateCounterpartRequest, InstallmentSeriesCreate, LinkTransferRequest, TransactionBulkDeleteRequest, TransactionCreate, TransactionRead, TransactionUpdate, TransferCreate, TransferRead
+from app.schemas.transaction import BulkAddToGroupRequest, BulkCategorizeRequest, DescriptionSuggestion, BulkTagsRequest, CreateCounterpartRequest, InstallmentSeriesCreate, LinkTransferRequest, TransactionBulkDeleteRequest, TransactionCreate, TransactionRead, TransactionUpdate, TransferCreate, TransferRead
from app.schemas.transaction_calendar import TransactionCalendarResponse
from app.services import transaction_service
from app.services.admin_service import get_credit_card_accounting_mode
@@ -187,6 +187,17 @@ async def transaction_calendar(
)
[email protected]("/description-suggestions", response_model=list[DescriptionSuggestion])
+async def description_suggestions(
+ q: str = Query("", max_length=100),
+ limit: int = Query(8, ge=1, le=20),
+ ctx: WorkspaceContext = Depends(current_workspace),
+ session: AsyncSession = Depends(get_async_session),
+):
+ """Descriptions used before in this workspace that contain ``q``."""
+ return await transaction_service.suggest_descriptions(session, ctx.workspace.id, q, limit)
+
+
@router.get("/export")
async def export_transactions(
account_id: Optional[uuid.UUID] = Query(None),
diff --git a/backend/app/schemas/transaction.py b/backend/app/schemas/transaction.py
index 7b93b731..bc67c02c 100644
--- a/backend/app/schemas/transaction.py
+++ b/backend/app/schemas/transaction.py
@@ -267,6 +267,14 @@ class BulkTagsRequest(BaseModel):
tags: list[str]
+class DescriptionSuggestion(BaseModel):
+ """A description typed before, with what was last filed under it."""
+
+ description: str
+ category_id: Optional[uuid.UUID] = None
+ payee_id: Optional[uuid.UUID] = None
+
+
class TransferRead(BaseModel):
debit: TransactionRead
credit: TransactionRead
diff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.py
index 7c1bbc75..933e5d89 100644
--- a/backend/app/services/transaction_service.py
+++ b/backend/app/services/transaction_service.py
@@ -4,7 +4,7 @@ from datetime import date
from decimal import Decimal
from typing import Optional, cast
-from sqlalchemy import CursorResult, delete, select, func, or_, not_, update
+from sqlalchemy import CursorResult, case, delete, select, func, or_, not_, update
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import selectinload
@@ -16,6 +16,7 @@ from app.models.category import Category
from app.models.group import Group, GroupMember
from app.models.payee import Payee
from app.schemas.transaction import (
+ DescriptionSuggestion,
InstallmentSeriesCreate,
TransactionCreate,
TransactionUpdate,
@@ -1969,3 +1970,102 @@ async def bulk_delete_transactions(
)
await session.commit()
return len(valid_ids)
+
+
+async def suggest_descriptions(
+ session: AsyncSession,
+ workspace_id: uuid.UUID,
+ query: str,
+ limit: int = 8,
+) -> list[DescriptionSuggestion]:
+ """Distinct descriptions in the workspace that contain ``query``.
+
+ Powers the description autocomplete in the transaction form (issue
+ #1127). Each suggestion carries the category and payee of the most
+ recent transaction with that description, so picking one can prefill
+ them. Matching is case-insensitive; descriptions that *start* with the
+ query rank before ones that merely contain it, newest first otherwise.
+ """
+ term = query.strip()
+ if len(term) < 2:
+ return []
+ escaped = term.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+ filters = (
+ Transaction.workspace_id == workspace_id,
+ Transaction.source != "opening_balance",
+ Transaction.is_ignored.is_(False),
+ Transaction.description.ilike(f"%{escaped}%", escape="\\"),
+ )
+ # Distinct and ranked in SQL *before* the limit, so many recent rows of
+ # one description can't push an older prefix match out of the results.
+ prefix_rank = func.min(
+ case((Transaction.description.ilike(f"{escaped}%", escape="\\"), 0), else_=1)
+ )
+ # Headroom over `limit` for spellings that differ only by case or
+ # surrounding spaces, which collapse into one suggestion below.
+ candidates = (
+ await session.execute(
+ select(Transaction.description)
+ .where(*filters)
+ .group_by(Transaction.description)
+ .order_by(prefix_rank, func.max(Transaction.date).desc(), Transaction.description)
+ .limit(limit * 4)
+ )
+ ).scalars().all()
+
+ chosen: dict[str, str] = {} # casefolded key -> displayed description
+ spellings: dict[str, list[str]] = {}
+ for description in candidates:
+ key = description.strip().casefold()
+ if not key:
+ continue
+ if key not in chosen:
+ if len(chosen) == limit:
+ continue
+ chosen[key] = description.strip()
+ spellings.setdefault(key, []).append(description)
+ if not chosen:
+ return []
+
+ # Category and payee from the latest use of each chosen description: one
+ # row per spelling (ranked in SQL), however often it was used.
+ recency = (
+ func.row_number()
+ .over(
+ partition_by=Transaction.description,
+ order_by=(Transaction.date.desc(), Transaction.created_at.desc()),
+ )
+ .label("recency")
+ )
+ newest = (
+ select(
+ Transaction.description,
+ Transaction.category_id,
+ Transaction.payee_id,
+ Transaction.date,
+ Transaction.created_at,
+ recency,
+ )
+ .where(
+ *filters[:3],
+ Transaction.description.in_([d for k in chosen for d in spellings[k]]),
+ )
+ .subquery()
+ )
+ rows = await session.execute(
+ select(newest.c.description, newest.c.category_id, newest.c.payee_id)
+ .where(newest.c.recency == 1)
+ .order_by(newest.c.date.desc(), newest.c.created_at.desc())
+ )
+ latest: dict[str, tuple[Optional[uuid.UUID], Optional[uuid.UUID]]] = {}
+ for description, category_id, payee_id in rows:
+ latest.setdefault(description.strip().casefold(), (category_id, payee_id))
+
+ return [
+ DescriptionSuggestion(
+ description=display,
+ category_id=latest.get(key, (None, None))[0],
+ payee_id=latest.get(key, (None, None))[1],
+ )
+ for key, display in chosen.items()
+ ]
diff --git a/backend/tests/test_description_suggestions.py b/backend/tests/test_description_suggestions.py
new file mode 100644
index 00000000..74a85ac0
--- /dev/null
+++ b/backend/tests/test_description_suggestions.py
@@ -0,0 +1,146 @@
+"""Description autocomplete for the transaction form (issue #1127).
+
+Suggestions are the distinct descriptions already used in the request's
+workspace, each carrying the category and payee of its most recent use so
+the form can prefill them.
+"""
+import uuid
+from datetime import date, datetime, timedelta, timezone
+from decimal import Decimal
+
+from httpx import AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.account import Account
+from app.models.category import Category
+from app.models.transaction import Transaction
+from app.models.user import User
+from app.models.workspace import Workspace, WorkspaceMember
+
+URL = "/api/transactions/description-suggestions"
+
+
+def _tx(account: Account, workspace_id: uuid.UUID, description: str, days_ago: int, **kw) -> Transaction:
+ return Transaction(
+ id=uuid.uuid4(),
+ user_id=account.user_id,
+ workspace_id=workspace_id,
+ account_id=account.id,
+ description=description,
+ amount=Decimal("10.00"),
+ currency="BRL",
+ date=date.today() - timedelta(days=days_ago),
+ type="debit",
+ created_at=datetime.now(timezone.utc),
+ **{"source": "manual", **kw},
+ )
+
+
+async def test_suggests_distinct_descriptions_with_latest_category(
+ client: AsyncClient,
+ session: AsyncSession,
+ auth_headers: dict,
+ test_account: Account,
+ test_workspace: Workspace,
+ test_categories: list[Category],
+):
+ old_cat, new_cat = test_categories[0], test_categories[1]
+ session.add_all([
+ _tx(test_account, test_workspace.id, "Supermarket Extra", 30, category_id=old_cat.id),
+ _tx(test_account, test_workspace.id, "supermarket extra ", 2, category_id=new_cat.id),
+ _tx(test_account, test_workspace.id, "Big Supermarket", 1),
+ _tx(test_account, test_workspace.id, "Pharmacy", 1),
+ ])
+ await session.commit()
+
+ resp = await client.get(URL, params={"q": "super"}, headers=auth_headers)
+
+ assert resp.status_code == 200
+ body = resp.json()
+ # Prefix matches first, case-insensitive duplicates collapsed to the newest.
+ assert [s["description"] for s in body] == ["supermarket extra", "Big Supermarket"]
+ assert body[0]["category_id"] == str(new_cat.id)
+
+
+async def test_scoped_to_the_request_workspace(
+ client: AsyncClient,
+ session: AsyncSession,
+ auth_headers: dict,
+ test_user: User,
+ test_account: Account,
+ test_workspace: Workspace,
+):
+ other = Workspace(
+ id=uuid.uuid4(), name="Other", kind="personal",
+ created_by_user_id=test_user.id, default_currency="BRL",
+ )
+ session.add(other)
+ await session.flush()
+ session.add(WorkspaceMember(id=uuid.uuid4(), workspace_id=other.id, user_id=test_user.id, role="owner"))
+ session.add_all([
+ _tx(test_account, test_workspace.id, "Coffee Shop", 1),
+ _tx(test_account, other.id, "Coffee Roasters", 1),
+ ])
+ await session.commit()
+
+ resp = await client.get(URL, params={"q": "coffee"}, headers=auth_headers)
+
+ assert [s["description"] for s in resp.json()] == ["Coffee Shop"]
+
+
+async def test_skips_ignored_opening_balance_and_short_queries(
+ client: AsyncClient,
+ session: AsyncSession,
+ auth_headers: dict,
+ test_account: Account,
+ test_workspace: Workspace,
+):
+ session.add_all([
+ _tx(test_account, test_workspace.id, "Opening balance", 5, source="opening_balance"),
+ _tx(test_account, test_workspace.id, "Open bar tab", 5, is_ignored=True),
+ _tx(test_account, test_workspace.id, "Open air market", 5),
+ ])
+ await session.commit()
+
+ resp = await client.get(URL, params={"q": "open"}, headers=auth_headers)
+ assert [s["description"] for s in resp.json()] == ["Open air market"]
+
+ short = await client.get(URL, params={"q": "o"}, headers=auth_headers)
+ assert short.json() == []
+
+
+async def test_like_wildcards_are_literal(
+ client: AsyncClient,
+ session: AsyncSession,
+ auth_headers: dict,
+ test_account: Account,
+ test_workspace: Workspace,
+):
+ session.add_all([
+ _tx(test_account, test_workspace.id, "100% juice", 1),
+ _tx(test_account, test_workspace.id, "1000 widgets", 1),
+ ])
+ await session.commit()
+
+ resp = await client.get(URL, params={"q": "0%"}, headers=auth_headers)
+
+ assert [s["description"] for s in resp.json()] == ["100% juice"]
+
+
+async def test_older_prefix_match_is_not_crowded_out_by_recent_rows(
+ client: AsyncClient,
+ session: AsyncSession,
+ auth_headers: dict,
+ test_account: Account,
+ test_workspace: Workspace,
+):
+ # Many recent rows that only *contain* the query, one old prefix match.
+ session.add_all(
+ [_tx(test_account, test_workspace.id, "Supermarket", i) for i in range(1, 600)]
+ + [_tx(test_account, test_workspace.id, "Market Hall", 900)]
+ )
+ await session.commit()
+
+ resp = await client.get(URL, params={"q": "market"}, headers=auth_headers)
+
+ assert [s["description"] for s in resp.json()] == ["Market Hall", "Supermarket"]
diff --git a/frontend/src/components/description-input.test.tsx b/frontend/src/components/description-input.test.tsx
new file mode 100644
index 00000000..1aa3c0e5
--- /dev/null
+++ b/frontend/src/components/description-input.test.tsx
@@ -0,0 +1,82 @@
+import { useState } from 'react'
+import { fireEvent, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DescriptionInput } from './description-input'
+import { renderWithProviders } from '@/test/utils'
+import { transactions } from '@/lib/api'
+import type { DescriptionSuggestion } from '@/types'
+
+vi.mock('@/lib/api', () => ({
+ transactions: { descriptionSuggestions: vi.fn() },
+}))
+
+const suggestions: DescriptionSuggestion[] = [
+ { description: 'Supermarket Extra', category_id: 'cat-1', payee_id: null },
+ { description: 'Big Supermarket', category_id: null, payee_id: 'payee-1' },
+]
+
+function Harness({ onPick }: { onPick: (s: DescriptionSuggestion) => void }) {
+ const [value, setValue] = useState('')
+ return <DescriptionInput value={value} onChange={setValue} onPick={onPick} />
+}
+
+function setup() {
+ const onPick = vi.fn()
+ renderWithProviders(<Harness onPick={onPick} />)
+ const input = screen.getByRole('combobox')
+ fireEvent.focus(input)
+ return { input, onPick }
+}
+
+describe('DescriptionInput', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ vi.mocked(transactions.descriptionSuggestions).mockResolvedValue(suggestions)
+ })
+
+ it('suggests past descriptions and fills the one picked', async () => {
+ const { input, onPick } = setup()
+ fireEvent.change(input, { target: { value: 'sup' } })
+
+ const option = await screen.findByRole('option', { name: 'Supermarket Extra' })
+ expect(transactions.descriptionSuggestions).toHaveBeenCalledWith('sup')
+ fireEvent.mouseDown(option)
+
+ expect(input).toHaveValue('Supermarket Extra')
+ expect(onPick).toHaveBeenCalledWith(suggestions[0])
+ expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+ })
+
+ it('picks with the keyboard', async () => {
+ const { input, onPick } = setup()
+ fireEvent.change(input, { target: { value: 'sup' } })
+ await screen.findByRole('listbox')
+
+ fireEvent.keyDown(input, { key: 'ArrowDown' })
+ fireEvent.keyDown(input, { key: 'ArrowDown' })
+ fireEvent.keyDown(input, { key: 'Enter' })
+
+ expect(input).toHaveValue('Big Supermarket')
+ expect(onPick).toHaveBeenCalledWith(suggestions[1])
+ })
+
+ it('keeps free text and stays quiet below two characters', async () => {
+ const { input } = setup()
+ fireEvent.change(input, { target: { value: 's' } })
+ await new Promise((r) => setTimeout(r, 300))
+ expect(transactions.descriptionSuggestions).not.toHaveBeenCalled()
+
+ fireEvent.change(input, { target: { value: 'something new' } })
+ await waitFor(() => expect(transactions.descriptionSuggestions).toHaveBeenCalled())
+ expect(input).toHaveValue('something new')
+ })
+
+ it('hides results from the previous query while the next one is debounced', async () => {
+ const { input } = setup()
+ fireEvent.change(input, { target: { value: 'sup' } })
+ await screen.findByRole('listbox')
+
+ fireEvent.change(input, { target: { value: 'market' } })
+ expect(screen.queryByRole('option', { name: 'Supermarket Extra' })).not.toBeInTheDocument()
+ })
+})
diff --git a/frontend/src/components/description-input.tsx b/frontend/src/components/description-input.tsx
new file mode 100644
index 00000000..a6266687
--- /dev/null
+++ b/frontend/src/components/description-input.tsx
@@ -0,0 +1,134 @@
+import { useEffect, useId, useState } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { Input } from '@/components/ui/input'
+import { Popover, PopoverAnchor, PopoverContent } from '@/components/ui/popover'
+import { transactions as transactionsApi } from '@/lib/api'
+import { cn } from '@/lib/utils'
+import type { DescriptionSuggestion } from '@/types'
+
+const MIN_QUERY = 2
+const DEBOUNCE_MS = 200
+
+interface DescriptionInputProps {
+ value: string
+ onChange: (value: string) => void
+ /** Called when the user picks a suggestion, after `onChange`. */
+ onPick?: (suggestion: DescriptionSuggestion) => void
+ required?: boolean
+ className?: string
+}
+
+/**
+ * Free-text description field that offers descriptions used before in the
+ * workspace (issue #1127). Suggestions are a shortcut only: whatever the user
+ * types is kept as typed.
+ */
+export function DescriptionInput({ value, onChange, onPick, required, className }: DescriptionInputProps) {
+ const listId = useId()
+ const [focused, setFocused] = useState(false)
+ const [dismissed, setDismissed] = useState(false)
+ const [active, setActive] = useState(-1)
+ const [query, setQuery] = useState(value.trim())
+
+ useEffect(() => {
+ const id = setTimeout(() => setQuery(value.trim()), DEBOUNCE_MS)
+ return () => clearTimeout(id)
+ }, [value])
+
+ const { data: suggestions = [] } = useQuery({
+ queryKey: ['transactions', 'description-suggestions', query],
+ queryFn: () => transactionsApi.descriptionSuggestions(query),
+ enabled: focused && query.length >= MIN_QUERY,
+ staleTime: 30_000,
+ })
+ // Offering exactly what's already typed is noise.
+ const options = suggestions.filter((s) => s.description !== value.trim())
+ // Until the debounce catches up, the results belong to an older query:
+ // don't offer "coffee" suggestions under "market".
+ const settled = query === value.trim()
+ const open = focused && !dismissed && settled && value.trim().length >= MIN_QUERY && options.length > 0
+
+ function pick(suggestion: DescriptionSuggestion) {
+ onChange(suggestion.description)
+ onPick?.(suggestion)
+ setDismissed(true)
+ setActive(-1)
+ }
+
+ function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
+ if (!open) return
+ if (e.key === 'ArrowDown') {
+ e.preventDefault()
+ setActive((i) => (i + 1) % options.length)
+ } else if (e.key === 'ArrowUp') {
+ e.preventDefault()
+ setActive((i) => (i <= 0 ? options.length - 1 : i - 1))
+ } else if (e.key === 'Enter' && active >= 0 && active < options.length) {
+ // Pick instead of submitting the form; Enter with nothing highlighted
+ // still saves, as it does on a plain input.
+ e.preventDefault()
+ pick(options[active])
+ } else if (e.key === 'Escape') {
+ // Close the list without closing the surrounding dialog.
+ e.preventDefault()
+ e.stopPropagation()
+ setDismissed(true)
+ }
+ }
+
+ return (
+ <Popover open={open}>
+ <PopoverAnchor asChild>
+ <Input
+ value={value}
+ onChange={(e) => {
+ onChange(e.target.value)
+ setDismissed(false)
+ setActive(-1)
+ }}
+ onFocus={() => setFocused(true)}
+ onBlur={() => setFocused(false)}
+ onKeyDown={handleKeyDown}
+ required={required}
+ autoComplete="off"
+ role="combobox"
+ aria-autocomplete="list"
+ aria-expanded={open}
+ aria-controls={open ? listId : undefined}
+ aria-activedescendant={open && active >= 0 ? `${listId}-${active}` : undefined}
+ className={className}
+ />
+ </PopoverAnchor>
+ <PopoverContent
+ align="start"
+ className="w-[var(--radix-popover-trigger-width)] p-1"
+ // Keep focus (and typing) in the input.
+ onOpenAutoFocus={(e) => e.preventDefault()}
+ onCloseAutoFocus={(e) => e.preventDefault()}
+ >
+ <ul id={listId} role="listbox" className="max-h-60 overflow-y-auto">
+ {options.map((s, i) => (
+ <li
+ key={s.description}
+ id={`${listId}-${i}`}
+ role="option"
+ aria-selected={i === active}
+ // mousedown, not click: the input's blur would close the list first.
+ onMouseDown={(e) => {
+ e.preventDefault()
+ pick(s)
+ }}
+ onMouseEnter={() => setActive(i)}
+ className={cn(
+ 'cursor-pointer truncate rounded-md px-2 py-1.5 text-sm',
+ i === active && 'bg-accent text-accent-foreground',
+ )}
+ >
+ {s.description}
+ </li>
+ ))}
+ </ul>
+ </PopoverContent>
+ </Popover>
+ )
+}
diff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsx
index eca8f69e..b972a55d 100644
--- a/frontend/src/components/transaction-dialog.tsx
+++ b/frontend/src/components/transaction-dialog.tsx
@@ -15,6 +15,7 @@ import { flattenConditions, hasConditionGroups } from '@/lib/rule-conditions'
import { cn, normalizeText } from '@/lib/utils'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
+import { DescriptionInput } from '@/components/description-input'
import { Label } from '@/components/ui/label'
import { DatePickerInput } from '@/components/ui/date-picker-input'
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
@@ -974,9 +975,15 @@ function TransactionForm({
rows={1}
/>
) : (
- <Input
+ <DescriptionInput
value={description}
- onChange={(e) => setDescription(e.target.value)}
+ onChange={setDescription}
+ // Prefill what was last filed under this description, without
+ // overwriting anything the user already chose (issue #1127).
+ onPick={(suggestion) => {
+ if (!categoryId && suggestion.category_id) setCategoryId(suggestion.category_id)
+ if (!payeeId && suggestion.payee_id) setPayeeId(suggestion.payee_id)
+ }}
required
className="bg-card"
/>
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index ed8812f1..bbdbfbaa 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -17,6 +17,7 @@ import type {
AccountSummary,
Collection,
CreditCardBill,
+ DescriptionSuggestion,
Transaction,
Payee,
PayeeSummary,
@@ -550,6 +551,10 @@ export const transactions = {
const { data } = await api.get(`/transactions/${id}`)
return data
},
+ descriptionSuggestions: async (q: string, limit = 8): Promise<DescriptionSuggestion[]> => {
+ const { data } = await api.get('/transactions/description-suggestions', { params: { q, limit } })
+ return data
+ },
create: async (transaction: TransactionEditPayload): Promise<Transaction> => {
const { data } = await api.post('/transactions', transaction)
return data
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 860a84ea..e020def3 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -240,6 +240,13 @@ export interface TransactionInvoiceLink {
amount: string
}
+/** A description used before, with the category and payee of its latest use. */
+export interface DescriptionSuggestion {
+ description: string
+ category_id: string | null
+ payee_id: string | null
+}
+
export interface Transaction {
/** Every invoice this transaction settles — a payout net of fees
* settles several. Absent in a workspace without the module. */