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.pyindex 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, TransferReadfrom app.schemas.transaction_calendar import TransactionCalendarResponsefrom app.services import transaction_servicefrom 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.pyindex 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: TransactionReadcredit: TransactionReaddiff --git a/backend/app/services/transaction_service.py b/backend/app/services/transaction_service.pyindex 7c1bbc75..933e5d89 100644--- a/backend/app/services/transaction_service.py+++ b/backend/app/services/transaction_service.py@@ -4,7 +4,7 @@ from datetime import datefrom decimal import Decimalfrom typing import Optional, cast-from sqlalchemy import CursorResult, delete, select, func, or_, not_, update+from sqlalchemy import CursorResult, case, delete, select, func, or_, not_, updatefrom sqlalchemy.ext.asyncio import AsyncSessionfrom sqlalchemy.orm import selectinload@@ -16,6 +16,7 @@ from app.models.category import Categoryfrom app.models.group import Group, GroupMemberfrom app.models.payee import Payeefrom 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.pynew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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+ <DescriptionInputvalue={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)+ }}requiredclassName="bg-card"/>diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.tsindex 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 datadiff --git a/frontend/src/types/index.ts b/frontend/src/types/index.tsindex 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. */