Skip to content

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

feat(frontend): improve People table interactions (#831)

João Vitor Lucena421ba5d148b4
diff --git a/frontend/src/lib/payee-sorting.ts b/frontend/src/lib/payee-sorting.ts
new file mode 100644
index 00000000..06b02e9d
--- /dev/null
+++ b/frontend/src/lib/payee-sorting.ts
@@ -0,0 +1,61 @@
+import type { Payee } from '@/types'
+
+export type PayeeSortBy = 'name' | 'type' | 'transaction_count'
+export type PayeeSortDirection = 'asc' | 'desc'
+
+export type PayeeSort = {
+ by: PayeeSortBy
+ direction: PayeeSortDirection
+}
+
+export const PAYEE_SORT_STORAGE_KEY = 'securo.payees.sort'
+export const DEFAULT_PAYEE_SORT: PayeeSort = { by: 'name', direction: 'asc' }
+export const INITIAL_SORT_DIRECTIONS: Record<PayeeSortBy, PayeeSortDirection> = {
+ name: 'asc',
+ type: 'asc',
+ transaction_count: 'desc',
+}
+
+export function loadPayeeSort(): PayeeSort {
+ try {
+ const raw = localStorage.getItem(PAYEE_SORT_STORAGE_KEY)
+ if (!raw) return DEFAULT_PAYEE_SORT
+
+ const parsed = JSON.parse(raw)
+ if (
+ (parsed?.by === 'name' || parsed?.by === 'type' || parsed?.by === 'transaction_count')
+ && (parsed?.direction === 'asc' || parsed?.direction === 'desc')
+ ) {
+ return { by: parsed.by, direction: parsed.direction }
+ }
+ } catch {
+ // Storage may be unavailable or contain data from an older version.
+ }
+ return DEFAULT_PAYEE_SORT
+}
+
+export function sortPayees(
+ payees: Payee[],
+ sort: PayeeSort,
+ locale: string,
+ typeLabels: Record<string, string>,
+): Payee[] {
+ const direction = sort.direction === 'asc' ? 1 : -1
+ const collator = new Intl.Collator(locale, { sensitivity: 'base' })
+
+ return [...payees].sort((a, b) => {
+ if (sort.by === 'transaction_count') {
+ return direction * (a.transaction_count - b.transaction_count)
+ }
+
+ if (sort.by === 'type') {
+ if (!a.type || !b.type) {
+ if (a.type === b.type) return 0
+ return a.type ? -direction : direction
+ }
+ return direction * collator.compare(typeLabels[a.type], typeLabels[b.type])
+ }
+
+ return direction * collator.compare(a.name, b.name)
+ })
+}
diff --git a/frontend/src/pages/groups.tsx b/frontend/src/pages/groups.tsx
index afac3216..502cdd8e 100644
--- a/frontend/src/pages/groups.tsx
+++ b/frontend/src/pages/groups.tsx
@@ -19,7 +19,7 @@ import {
} from '@/components/ui/dialog'
import { GroupForm } from '@/components/group-form'
import { PageHeader } from '@/components/page-header'
-import { Archive, ChevronRight, Trash2, Users } from 'lucide-react'
+import { Archive, ChevronRight, Plus, Trash2, Users } from 'lucide-react'
import type { Group, GroupKind } from '@/types'
type StatusFilter = 'active' | 'archived' | 'all'
@@ -142,7 +142,14 @@ export default function GroupsPage() {
section={t('splitGroups.section')}
title={t('splitGroups.title')}
action={
- canWrite ? <Button onClick={openCreate}>+ {t('splitGroups.add')}</Button> : undefined
+ canWrite ? (
+ <div className="flex w-full flex-wrap items-center gap-2 sm:w-auto">
+ <Button size="sm" className="h-8 gap-1.5" onClick={openCreate}>
+ <Plus size={13} />
+ <span>{t('splitGroups.add')}</span>
+ </Button>
+ </div>
+ ) : undefined
}
/>
diff --git a/frontend/src/pages/payees-page.test.tsx b/frontend/src/pages/payees-page.test.tsx
new file mode 100644
index 00000000..73faad2a
--- /dev/null
+++ b/frontend/src/pages/payees-page.test.tsx
@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { screen, waitFor, within } from '@testing-library/react'
+
+import PayeesPage from '@/pages/payees'
+import { PAYEE_SORT_STORAGE_KEY } from '@/lib/payee-sorting'
+import { renderWithProviders, t } from '@/test/utils'
+
+const api = vi.hoisted(() => ({
+ payees: {
+ list: vi.fn(),
+ summary: vi.fn(),
+ create: vi.fn(),
+ update: vi.fn(),
+ delete: vi.fn(),
+ merge: vi.fn(),
+ bulkDelete: vi.fn(),
+ },
+ transactions: { list: vi.fn() },
+ fiscal: { taxIdKinds: vi.fn() },
+}))
+
+vi.mock('@/lib/api', () => ({
+ payees: api.payees,
+ transactions: api.transactions,
+ fiscal: api.fiscal,
+}))
+
+vi.mock('@/hooks/use-display-locale', () => ({
+ useDisplayLocale: () => 'en-US',
+ useDateLocale: () => 'en-US',
+}))
+
+vi.mock('@/contexts/auth-context', () => ({
+ useAuth: () => ({ user: { preferences: { currency_display: 'USD' } } }),
+}))
+
+vi.mock('@/contexts/workspace-context', () => ({
+ useWorkspace: () => ({ canWrite: false }),
+}))
+
+vi.mock('@/hooks/use-privacy-mode', () => ({
+ usePrivacyMode: () => ({ mask: (value: string) => value }),
+}))
+
+const payees = [
+ {
+ id: 'alpha', user_id: 'user-1', name: 'Alpha', type: 'person', source: 'manual', is_favorite: false,
+ notes: null, email: null, phone: null, address: null, website: null, tax_ids: [],
+ created_at: '2026-01-01T00:00:00Z', transaction_count: 1,
+ },
+ {
+ id: 'zeta', user_id: 'user-1', name: 'Zeta', type: 'company', source: 'manual', is_favorite: false,
+ notes: null, email: null, phone: null, address: null, website: null, tax_ids: [],
+ created_at: '2026-01-01T00:00:00Z', transaction_count: 3,
+ },
+]
+
+function firstPayeeRow() {
+ return screen.getAllByRole('row')[1]
+}
+
+describe('PayeesPage sorting', () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ api.payees.list.mockResolvedValue(payees)
+ api.fiscal.taxIdKinds.mockResolvedValue({ kinds: [], jurisdiction: null })
+ })
+
+ it('sorts transactions descending then ascending and persists the choice', async () => {
+ const { user } = renderWithProviders(<PayeesPage />, { route: '/payees' })
+ await screen.findByText('Alpha')
+
+ const transactionsHeader = screen.getByRole('button', { name: t('payees.transactionCount') })
+ await user.click(transactionsHeader)
+
+ expect(within(firstPayeeRow()).getByText('Zeta')).toBeInTheDocument()
+ expect(transactionsHeader).toHaveAccessibleName(t('payees.transactionCount'))
+ expect(transactionsHeader.closest('th')).toHaveAttribute('aria-sort', 'descending')
+ await waitFor(() => expect(localStorage.getItem(PAYEE_SORT_STORAGE_KEY)).toBe(
+ JSON.stringify({ by: 'transaction_count', direction: 'desc' }),
+ ))
+
+ await user.click(transactionsHeader)
+
+ expect(within(firstPayeeRow()).getByText('Alpha')).toBeInTheDocument()
+ expect(transactionsHeader.closest('th')).toHaveAttribute('aria-sort', 'ascending')
+ await waitFor(() => expect(localStorage.getItem(PAYEE_SORT_STORAGE_KEY)).toBe(
+ JSON.stringify({ by: 'transaction_count', direction: 'asc' }),
+ ))
+ })
+})
diff --git a/frontend/src/pages/payees.test.ts b/frontend/src/pages/payees.test.ts
new file mode 100644
index 00000000..f19b2569
--- /dev/null
+++ b/frontend/src/pages/payees.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import type { Payee } from '@/types'
+import { DEFAULT_PAYEE_SORT, loadPayeeSort, PAYEE_SORT_STORAGE_KEY, sortPayees } from '@/lib/payee-sorting'
+
+const typeLabels = { person: 'Person', company: 'Company' }
+
+function payee(name: string, overrides: Partial<Payee> = {}): Payee {
+ return {
+ id: name,
+ user_id: 'user-1',
+ name,
+ type: null,
+ source: 'manual',
+ is_favorite: false,
+ notes: null,
+ email: null,
+ phone: null,
+ address: null,
+ website: null,
+ tax_ids: [],
+ created_at: '2026-01-01T00:00:00Z',
+ transaction_count: 0,
+ ...overrides,
+ }
+}
+
+describe('sortPayees', () => {
+ it('sorts names ascending without changing the source list', () => {
+ const payees = [payee('Zeta'), payee('Alpha')]
+
+ const result = sortPayees(payees, { by: 'name', direction: 'asc' }, 'en-US', typeLabels)
+
+ expect(result.map(({ name }) => name)).toEqual(['Alpha', 'Zeta'])
+ expect(payees.map(({ name }) => name)).toEqual(['Zeta', 'Alpha'])
+ })
+
+ it('sorts transaction counts descending', () => {
+ const payees = [payee('One', { transaction_count: 1 }), payee('Three', { transaction_count: 3 })]
+
+ const result = sortPayees(payees, { by: 'transaction_count', direction: 'desc' }, 'en-US', typeLabels)
+
+ expect(result.map(({ name }) => name)).toEqual(['Three', 'One'])
+ })
+
+ it('moves unset types with the selected direction', () => {
+ const payees = [payee('Unset'), payee('Person', { type: 'person' })]
+
+ const ascending = sortPayees(payees, { by: 'type', direction: 'asc' }, 'en-US', typeLabels)
+ const descending = sortPayees(payees, { by: 'type', direction: 'desc' }, 'en-US', typeLabels)
+
+ expect(ascending.map(({ name }) => name)).toEqual(['Person', 'Unset'])
+ expect(descending.map(({ name }) => name)).toEqual(['Unset', 'Person'])
+ })
+
+ it('preserves API order for equal values', () => {
+ const payees = [payee('First', { transaction_count: 2 }), payee('Second', { transaction_count: 2 })]
+
+ const result = sortPayees(payees, { by: 'transaction_count', direction: 'asc' }, 'en-US', typeLabels)
+
+ expect(result.map(({ name }) => name)).toEqual(['First', 'Second'])
+ })
+})
+
+describe('loadPayeeSort', () => {
+ it('uses the default when no saved preference exists', () => {
+ expect(loadPayeeSort()).toEqual(DEFAULT_PAYEE_SORT)
+ })
+
+ it('loads a valid saved preference and rejects invalid data', () => {
+ localStorage.setItem(PAYEE_SORT_STORAGE_KEY, JSON.stringify({ by: 'transaction_count', direction: 'desc' }))
+ expect(loadPayeeSort()).toEqual({ by: 'transaction_count', direction: 'desc' })
+
+ localStorage.setItem(PAYEE_SORT_STORAGE_KEY, JSON.stringify({ by: 'favorite', direction: 'asc' }))
+ expect(loadPayeeSort()).toEqual(DEFAULT_PAYEE_SORT)
+ })
+})
diff --git a/frontend/src/pages/payees.tsx b/frontend/src/pages/payees.tsx
index 7bf1d48b..1d1b297d 100644
--- a/frontend/src/pages/payees.tsx
+++ b/frontend/src/pages/payees.tsx
@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef } from 'react'
+import { useState, useEffect, useMemo, useRef } from 'react'
import { useTranslation } from 'react-i18next'
import { useDisplayLocale, useDateLocale } from '@/hooks/use-display-locale'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
@@ -44,13 +44,21 @@ import {
import { cn } from '@/lib/utils'
import { PageHeader } from '@/components/page-header'
import { calculateRangeSelection } from '@/lib/selection-utils'
-import { Search, Star, Merge, Trash2, ArrowRight, ListFilter, X, Check, Pencil, Plus } from 'lucide-react'
+import { Search, Star, Merge, Trash2, ArrowRight, ListFilter, X, Check, Pencil, Plus, ArrowDown, ArrowUp } from 'lucide-react'
import { usePrivacyMode } from '@/hooks/use-privacy-mode'
import { useAuth } from '@/contexts/auth-context'
import { useWorkspace } from '@/contexts/workspace-context'
import type { Payee } from '@/types'
import { formatCurrency } from '@/lib/format'
import { payeeErrorMessage } from '@/lib/payee-error-message'
+import {
+ INITIAL_SORT_DIRECTIONS,
+ loadPayeeSort,
+ PAYEE_SORT_STORAGE_KEY,
+ sortPayees,
+ type PayeeSort,
+ type PayeeSortBy,
+} from '@/lib/payee-sorting'
export default function PayeesPage() {
const { t } = useTranslation()
@@ -65,10 +73,10 @@ export default function PayeesPage() {
// No entry for an unset type: most rows come from sync, which cannot know
// a legal nature from a bank descriptor, and a badge reading "unknown" on
// hundreds of rows is noise rather than information.
- const typeLabels: Record<string, string> = {
+ const typeLabels = useMemo<Record<string, string>>(() => ({
person: t('payees.typePerson'),
company: t('payees.typeCompany'),
- }
+ }), [t])
const queryClient = useQueryClient()
const [search, setSearch] = useState(() => searchParams.get('q') ?? '')
const [searchQuery, setSearchQuery] = useState(() => searchParams.get('q') ?? '')
@@ -84,7 +92,9 @@ export default function PayeesPage() {
const [filterFavorites, setFilterFavorites] = useState(() => searchParams.get('is_favorite') === 'true')
const [deleteDialogOpen, setDeleteDialogOpen] = useState(false)
const [payeesToDelete, setPayeesToDelete] = useState<string[]>([])
+ const [sort, setSort] = useState<PayeeSort>(() => loadPayeeSort())
const prevSearchRef = useRef<string | null>(null)
+ const summaryRef = useRef<HTMLDivElement>(null)
// Sync state from URL when navigating
useEffect(() => {
@@ -132,6 +142,24 @@ export default function PayeesPage() {
setLastSelectedId(null)
}, [searchQuery, filterType, filterFavorites])
+ useEffect(() => {
+ if (!summaryPayee) return
+
+ const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+ summaryRef.current?.scrollIntoView({
+ behavior: prefersReducedMotion ? 'auto' : 'smooth',
+ block: 'start',
+ })
+ }, [summaryPayee])
+
+ useEffect(() => {
+ try {
+ localStorage.setItem(PAYEE_SORT_STORAGE_KEY, JSON.stringify(sort))
+ } catch {
+ // A disabled or full storage must not prevent sorting the current list.
+ }
+ }, [sort])
+
// Form state
const [formName, setFormName] = useState('')
// '' means the legal nature was not stated, which is the resting state for
@@ -342,27 +370,37 @@ export default function PayeesPage() {
}
}
+ const sortedPayees = useMemo(
+ () => sortPayees(payeesList ?? [], sort, locale, typeLabels),
+ [payeesList, sort, locale, typeLabels],
+ )
+
+ const toggleSort = (by: PayeeSortBy) => {
+ setSort((current) => {
+ if (current.by !== by) return { by, direction: INITIAL_SORT_DIRECTIONS[by] }
+ return { ...current, direction: current.direction === 'asc' ? 'desc' : 'asc' }
+ })
+ }
+
const toggleSelect = (id: string, isShiftKey: boolean = false) => {
setSelectedIds(prev =>
- calculateRangeSelection(prev, lastSelectedId, id, filtered, isShiftKey)
+ calculateRangeSelection(prev, lastSelectedId, id, sortedPayees, isShiftKey)
)
setLastSelectedId(id)
}
- const filtered = payeesList ?? []
-
const toggleSelectAll = () => {
- if (!filtered.length) return
- const allSelected = filtered.every(payee => selectedIds.has(payee.id))
+ if (!sortedPayees.length) return
+ const allSelected = sortedPayees.every(payee => selectedIds.has(payee.id))
if (allSelected) {
setSelectedIds(new Set())
} else {
- setSelectedIds(new Set(filtered.map(payee => payee.id)))
+ setSelectedIds(new Set(sortedPayees.map(payee => payee.id)))
}
}
- const allSelected = filtered.length > 0 && filtered.every(payee => selectedIds.has(payee.id))
- const someSelected = filtered.some(payee => selectedIds.has(payee.id)) && !allSelected
+ const allSelected = sortedPayees.length > 0 && sortedPayees.every(payee => selectedIds.has(payee.id))
+ const someSelected = sortedPayees.some(payee => selectedIds.has(payee.id)) && !allSelected
return (
<div>
@@ -371,24 +409,25 @@ export default function PayeesPage() {
title={t('payees.title')}
action={
canWrite ? (
- <div className="flex items-center gap-2">
+ <div className="flex w-full flex-wrap items-center gap-2 sm:w-auto">
{selectedIds.size >= 2 && (
- <div className="flex items-center gap-2">
- <Button variant="outline" onClick={() => { setMergeTargetId(''); setMergeDialogOpen(true) }}>
- <Merge size={16} className="mr-1.5" />
+ <>
+ <Button size="sm" variant="outline" className="h-8 gap-1.5" onClick={() => { setMergeTargetId(''); setMergeDialogOpen(true) }}>
+ <Merge size={13} />
{t('payees.merge')} ({selectedIds.size})
</Button>
- <Button variant="destructive" onClick={() => {
+ <Button size="sm" variant="destructive" className="h-8 gap-1.5" onClick={() => {
setPayeesToDelete(Array.from(selectedIds))
setDeleteDialogOpen(true)
}} disabled={bulkDeleteMutation.isPending}>
- <Trash2 size={16} className="mr-1.5" />
+ <Trash2 size={13} />
{t('common.delete')} ({selectedIds.size})
</Button>
- </div>
+ </>
)}
- <Button onClick={openCreate}>
- + {t('payees.add')}
+ <Button size="sm" className="h-8 gap-1.5" onClick={openCreate}>
+ <Plus size={13} />
+ <span>{t('payees.add')}</span>
</Button>
</div>
) : undefined
@@ -561,7 +600,7 @@ export default function PayeesPage() {
were created by sync has hundreds of rows, and a panel rendered after
the table opens below the fold, which reads as the click doing nothing. */}
{summaryPayee && (
- <div className="bg-card rounded-xl border border-border shadow-sm p-5 mb-4">
+ <div ref={summaryRef} className="scroll-mt-16 bg-card rounded-xl border border-border shadow-sm p-5 mb-4">
{summaryLoading ? (
<Skeleton className="h-24 w-full" />
) : summaryData ? (
@@ -664,16 +703,55 @@ export default function PayeesPage() {
className="h-4 w-4 rounded border-border accent-primary cursor-pointer"
/>
</TableHead>
- )}
+ )}
<TableHead className="text-xs font-medium text-muted-foreground py-3 w-[32px]" />
- <TableHead className="text-xs font-medium text-muted-foreground py-3">{t('payees.name')}</TableHead>
- <TableHead className="hidden md:table-cell text-xs font-medium text-muted-foreground py-3 w-[120px]">{t('payees.type')}</TableHead>
- <TableHead className="text-xs font-medium text-muted-foreground py-3 text-right w-[120px]">{t('payees.transactionCount')}</TableHead>
+ <TableHead
+ aria-sort={sort.by === 'name' ? (sort.direction === 'asc' ? 'ascending' : 'descending') : undefined}
+ className="text-xs font-medium text-muted-foreground py-3"
+ >
+ <button
+ type="button"
+ onClick={() => toggleSort('name')}
+ className="w-full inline-flex cursor-pointer items-center gap-1 transition-colors hover:text-foreground"
+ >
+ {t('payees.name')}
+ {sort.by === 'name'
+ && (sort.direction === 'asc' ? <ArrowUp size={12} aria-hidden="true" /> : <ArrowDown size={12} aria-hidden="true" />)}
+ </button>
+ </TableHead>
+ <TableHead
+ aria-sort={sort.by === 'type' ? (sort.direction === 'asc' ? 'ascending' : 'descending') : undefined}
+ className="hidden text-left text-xs font-medium text-muted-foreground py-3 md:table-cell w-[120px]"
+ >
+ <button
+ type="button"
+ onClick={() => toggleSort('type')}
+ className="inline-flex w-full cursor-pointer items-center gap-1 transition-colors hover:text-foreground"
+ >
+ {t('payees.type')}
+ {sort.by === 'type'
+ && (sort.direction === 'asc' ? <ArrowUp size={12} aria-hidden="true" /> : <ArrowDown size={12} aria-hidden="true" />)}
+ </button>
+ </TableHead>
+ <TableHead
+ aria-sort={sort.by === 'transaction_count' ? (sort.direction === 'asc' ? 'ascending' : 'descending') : undefined}
+ className="text-left text-xs font-medium text-muted-foreground py-3 w-[120px]"
+ >
+ <button
+ type="button"
+ onClick={() => toggleSort('transaction_count')}
+ className="inline-flex w-full cursor-pointer items-center gap-1 transition-colors hover:text-foreground"
+ >
+ {t('payees.transactionCount')}
+ {sort.by === 'transaction_count'
+ && (sort.direction === 'asc' ? <ArrowUp size={12} aria-hidden="true" /> : <ArrowDown size={12} aria-hidden="true" />)}
+ </button>
+ </TableHead>
{canWrite && <TableHead className="w-[100px]" />}
</TableRow>
</TableHeader>
<TableBody>
- {filtered.map((payee) => (
+ {sortedPayees.map((payee) => (
<TableRow
key={payee.id}
className={`cursor-pointer hover:bg-muted border-b border-border last:border-0 ${
@@ -725,12 +803,12 @@ export default function PayeesPage() {
<p className="text-xs text-muted-foreground mt-0.5 truncate max-w-[300px]">{payee.notes}</p>
)}
</TableCell>
- <TableCell className="hidden md:table-cell py-2.5">
+ <TableCell className="hidden py-2.5 text-left md:table-cell">
{payee.type && (
<span className="text-xs bg-muted text-muted-foreground px-2 py-0.5 rounded-full capitalize">{typeLabels[payee.type]}</span>
)}
</TableCell>
- <TableCell className="py-2.5 text-right">
+ <TableCell className="py-2.5 text-left">
<span className="text-sm tabular-nums text-muted-foreground">{payee.transaction_count}</span>
</TableCell>
{canWrite && (
@@ -760,7 +838,7 @@ export default function PayeesPage() {
)}
</TableRow>
))}
- {filtered.length === 0 && (
+ {sortedPayees.length === 0 && (
<TableRow>
<TableCell colSpan={canWrite ? 6 : 4} className="text-center py-16 text-muted-foreground">
{t('payees.empty')}