Files
HOA_Financial_Platform/frontend/src/pages/assessment-groups/AssessmentGroupsPage.tsx
olsch01 1e31595d7f feat: add flexible billing frequency support for invoices
Assessment groups can now define billing frequency (monthly, quarterly,
annual) with configurable due months and due day. Invoice generation
respects each group's schedule - only generating invoices when the
selected month is a billing month for that group. Adds a generation
preview showing which groups will be billed, period tracking on
invoices, and billing period context in the payments UI.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 19:08:56 -05:00

435 lines
16 KiB
TypeScript

import { useState } from 'react';
import {
Title, Text, Card, Table, SimpleGrid, Group, Stack, Badge, Loader, Center,
ThemeIcon, Button, Modal, TextInput, NumberInput, Textarea, Select, ActionIcon, Tooltip,
MultiSelect,
} from '@mantine/core';
import { useForm } from '@mantine/form';
import { useDisclosure } from '@mantine/hooks';
import { notifications } from '@mantine/notifications';
import {
IconPlus, IconEdit, IconCategory, IconCash, IconHome, IconArchive, IconStarFilled, IconStar,
} from '@tabler/icons-react';
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import api from '../../services/api';
import { useIsReadOnly } from '../../stores/authStore';
interface AssessmentGroup {
id: string;
name: string;
description: string;
regular_assessment: string;
special_assessment: string;
unit_count: number;
frequency: string;
due_months: number[];
due_day: number;
actual_unit_count: string;
monthly_operating_income: string;
monthly_reserve_income: string;
total_monthly_income: string;
is_default: boolean;
is_active: boolean;
}
interface Summary {
group_count: string;
total_monthly_operating: string;
total_monthly_reserve: string;
total_monthly_income: string;
total_units: string;
}
const frequencyLabels: Record<string, string> = {
monthly: 'Monthly',
quarterly: 'Quarterly',
annual: 'Annual',
};
const frequencyColors: Record<string, string> = {
monthly: 'blue',
quarterly: 'teal',
annual: 'violet',
};
const MONTH_OPTIONS = [
{ value: '1', label: 'January' },
{ value: '2', label: 'February' },
{ value: '3', label: 'March' },
{ value: '4', label: 'April' },
{ value: '5', label: 'May' },
{ value: '6', label: 'June' },
{ value: '7', label: 'July' },
{ value: '8', label: 'August' },
{ value: '9', label: 'September' },
{ value: '10', label: 'October' },
{ value: '11', label: 'November' },
{ value: '12', label: 'December' },
];
const MONTH_ABBREV = ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
const DEFAULT_DUE_MONTHS: Record<string, string[]> = {
monthly: ['1','2','3','4','5','6','7','8','9','10','11','12'],
quarterly: ['1','4','7','10'],
annual: ['1'],
};
export function AssessmentGroupsPage() {
const [opened, { open, close }] = useDisclosure(false);
const [editing, setEditing] = useState<AssessmentGroup | null>(null);
const queryClient = useQueryClient();
const isReadOnly = useIsReadOnly();
const { data: groups = [], isLoading } = useQuery<AssessmentGroup[]>({
queryKey: ['assessment-groups'],
queryFn: async () => { const { data } = await api.get('/assessment-groups'); return data; },
});
const { data: summary } = useQuery<Summary>({
queryKey: ['assessment-groups-summary'],
queryFn: async () => { const { data } = await api.get('/assessment-groups/summary'); return data; },
});
const form = useForm({
initialValues: {
name: '',
description: '',
regularAssessment: 0,
specialAssessment: 0,
unitCount: 0,
frequency: 'monthly',
dueMonths: DEFAULT_DUE_MONTHS.monthly,
dueDay: 1,
},
validate: {
name: (v) => (v.length > 0 ? null : 'Required'),
regularAssessment: (v) => (v >= 0 ? null : 'Must be >= 0'),
dueMonths: (v, values) => {
if (values.frequency === 'quarterly' && v.length !== 4) return 'Quarterly requires exactly 4 months';
if (values.frequency === 'annual' && v.length !== 1) return 'Annual requires exactly 1 month';
return null;
},
dueDay: (v) => (v >= 1 && v <= 28 ? null : 'Must be 1-28'),
},
});
const saveMutation = useMutation({
mutationFn: (values: any) => {
const payload = {
...values,
dueMonths: values.dueMonths.map(Number),
};
return editing
? api.put(`/assessment-groups/${editing.id}`, payload)
: api.post('/assessment-groups', payload);
},
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['assessment-groups'] });
queryClient.invalidateQueries({ queryKey: ['assessment-groups-summary'] });
notifications.show({ message: editing ? 'Group updated' : 'Group created', color: 'green' });
close();
setEditing(null);
form.reset();
},
onError: (err: any) => {
notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' });
},
});
const archiveMutation = useMutation({
mutationFn: (group: AssessmentGroup) =>
api.put(`/assessment-groups/${group.id}`, { isActive: !group.is_active }),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['assessment-groups'] });
queryClient.invalidateQueries({ queryKey: ['assessment-groups-summary'] });
notifications.show({ message: 'Group status updated', color: 'green' });
},
});
const setDefaultMutation = useMutation({
mutationFn: (id: string) => api.put(`/assessment-groups/${id}/set-default`),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['assessment-groups'] });
notifications.show({ message: 'Default group updated', color: 'green' });
},
onError: (err: any) => {
notifications.show({ message: err.response?.data?.message || 'Error', color: 'red' });
},
});
const handleEdit = (group: AssessmentGroup) => {
setEditing(group);
const dueMonths = group.due_months
? group.due_months.map(String)
: DEFAULT_DUE_MONTHS[group.frequency] || DEFAULT_DUE_MONTHS.monthly;
form.setValues({
name: group.name,
description: group.description || '',
regularAssessment: parseFloat(group.regular_assessment || '0'),
specialAssessment: parseFloat(group.special_assessment || '0'),
unitCount: group.unit_count || 0,
frequency: group.frequency || 'monthly',
dueMonths,
dueDay: group.due_day || 1,
});
open();
};
const handleNew = () => {
setEditing(null);
form.reset();
open();
};
const handleFrequencyChange = (value: string | null) => {
if (!value) return;
form.setFieldValue('frequency', value);
form.setFieldValue('dueMonths', DEFAULT_DUE_MONTHS[value] || DEFAULT_DUE_MONTHS.monthly);
};
const fmt = (v: string | number) =>
parseFloat(String(v || '0')).toLocaleString('en-US', { style: 'currency', currency: 'USD' });
const freqSuffix = (freq: string) => {
switch (freq) {
case 'quarterly': return '/qtr';
case 'annual': return '/yr';
default: return '/mo';
}
};
const formatDueMonths = (months: number[], frequency: string) => {
if (!months || frequency === 'monthly') return 'Every month';
return months.map((m) => MONTH_ABBREV[m]).join(', ');
};
if (isLoading) return <Center h={300}><Loader /></Center>;
return (
<Stack>
<Group justify="space-between">
<div>
<Title order={2}>Assessment Groups</Title>
<Text c="dimmed" size="sm">Manage property types with different assessment rates and frequencies</Text>
</div>
{!isReadOnly && (
<Button leftSection={<IconPlus size={16} />} onClick={handleNew}>
Add Group
</Button>
)}
</Group>
<SimpleGrid cols={{ base: 1, sm: 2, md: 4 }}>
<Card withBorder padding="lg">
<Group justify="space-between">
<div>
<Text size="xs" c="dimmed" tt="uppercase" fw={700}>Groups</Text>
<Text fw={700} size="xl">{summary?.group_count || 0}</Text>
</div>
<ThemeIcon color="blue" variant="light" size={48} radius="md">
<IconCategory size={28} />
</ThemeIcon>
</Group>
</Card>
<Card withBorder padding="lg">
<Group justify="space-between">
<div>
<Text size="xs" c="dimmed" tt="uppercase" fw={700}>Total Units</Text>
<Text fw={700} size="xl">{summary?.total_units || 0}</Text>
</div>
<ThemeIcon color="green" variant="light" size={48} radius="md">
<IconHome size={28} />
</ThemeIcon>
</Group>
</Card>
<Card withBorder padding="lg">
<Group justify="space-between">
<div>
<Text size="xs" c="dimmed" tt="uppercase" fw={700}>Monthly Equiv. Operating</Text>
<Text fw={700} size="xl">{fmt(summary?.total_monthly_operating || '0')}</Text>
</div>
<ThemeIcon color="teal" variant="light" size={48} radius="md">
<IconCash size={28} />
</ThemeIcon>
</Group>
</Card>
<Card withBorder padding="lg">
<Group justify="space-between">
<div>
<Text size="xs" c="dimmed" tt="uppercase" fw={700}>Monthly Equiv. Reserve</Text>
<Text fw={700} size="xl">{fmt(summary?.total_monthly_reserve || '0')}</Text>
</div>
<ThemeIcon color="violet" variant="light" size={48} radius="md">
<IconCash size={28} />
</ThemeIcon>
</Group>
</Card>
</SimpleGrid>
<Card withBorder>
<Table striped highlightOnHover>
<Table.Thead>
<Table.Tr>
<Table.Th>Group Name</Table.Th>
<Table.Th ta="center">Units</Table.Th>
<Table.Th>Frequency</Table.Th>
<Table.Th>Due Months</Table.Th>
<Table.Th ta="right">Regular Assessment</Table.Th>
<Table.Th ta="right">Special Assessment</Table.Th>
<Table.Th ta="right">Monthly Equiv.</Table.Th>
<Table.Th>Status</Table.Th>
<Table.Th></Table.Th>
</Table.Tr>
</Table.Thead>
<Table.Tbody>
{groups.length === 0 && (
<Table.Tr>
<Table.Td colSpan={9}>
<Text ta="center" c="dimmed" py="lg">
No assessment groups yet. Create groups like "Single Family Homes", "Condos", etc.
</Text>
</Table.Td>
</Table.Tr>
)}
{groups.map((g) => (
<Table.Tr key={g.id} style={{ opacity: g.is_active ? 1 : 0.5 }}>
<Table.Td>
<Group gap={8}>
<div>
<Group gap={6}>
<Text fw={500}>{g.name}</Text>
{g.is_default && (
<Badge color="yellow" variant="light" size="xs">Default</Badge>
)}
</Group>
{g.description && <Text size="xs" c="dimmed">{g.description}</Text>}
</div>
</Group>
</Table.Td>
<Table.Td ta="center">
<Badge variant="light">{g.actual_unit_count || g.unit_count}</Badge>
</Table.Td>
<Table.Td>
<Badge
color={frequencyColors[g.frequency] || 'blue'}
variant="light"
size="sm"
>
{frequencyLabels[g.frequency] || 'Monthly'}
</Badge>
</Table.Td>
<Table.Td>
<Text size="xs" c="dimmed">{formatDueMonths(g.due_months, g.frequency)}</Text>
</Table.Td>
<Table.Td ta="right" ff="monospace">
{fmt(g.regular_assessment)}{freqSuffix(g.frequency)}
</Table.Td>
<Table.Td ta="right" ff="monospace">
{parseFloat(g.special_assessment || '0') > 0 ? (
<Badge color="orange" variant="light">{fmt(g.special_assessment)}{freqSuffix(g.frequency)}</Badge>
) : '-'}
</Table.Td>
<Table.Td ta="right" ff="monospace">{fmt(g.total_monthly_income)}</Table.Td>
<Table.Td>
<Badge color={g.is_active ? 'green' : 'gray'} variant="light" size="sm">
{g.is_active ? 'Active' : 'Archived'}
</Badge>
</Table.Td>
<Table.Td>
{!isReadOnly && (
<Group gap={4}>
<Tooltip label={g.is_default ? 'Default group' : 'Set as default'}>
<ActionIcon
variant="subtle"
color={g.is_default ? 'yellow' : 'gray'}
onClick={() => !g.is_default && setDefaultMutation.mutate(g.id)}
disabled={g.is_default}
>
{g.is_default ? <IconStarFilled size={16} /> : <IconStar size={16} />}
</ActionIcon>
</Tooltip>
<ActionIcon variant="subtle" onClick={() => handleEdit(g)}>
<IconEdit size={16} />
</ActionIcon>
<ActionIcon
variant="subtle"
color={g.is_active ? 'gray' : 'green'}
onClick={() => archiveMutation.mutate(g)}
>
<IconArchive size={16} />
</ActionIcon>
</Group>
)}
</Table.Td>
</Table.Tr>
))}
</Table.Tbody>
</Table>
</Card>
<Modal opened={opened} onClose={close} title={editing ? 'Edit Assessment Group' : 'New Assessment Group'} size="md">
<form onSubmit={form.onSubmit((values) => saveMutation.mutate(values))}>
<Stack>
<TextInput label="Group Name" placeholder="e.g. Single Family Homes" required {...form.getInputProps('name')} />
<Textarea label="Description" placeholder="Optional description" {...form.getInputProps('description')} />
<Select
label="Assessment Frequency"
description="How often assessments are collected"
data={[
{ value: 'monthly', label: 'Monthly' },
{ value: 'quarterly', label: 'Quarterly' },
{ value: 'annual', label: 'Annual' },
]}
value={form.values.frequency}
onChange={handleFrequencyChange}
/>
{form.values.frequency !== 'monthly' && (
<MultiSelect
label={form.values.frequency === 'quarterly' ? 'Billing Quarters (select 4 months)' : 'Due Month'}
description={form.values.frequency === 'quarterly'
? 'Select the first month of each quarter when assessments are due'
: 'Select the month when the annual assessment is due'}
data={MONTH_OPTIONS}
value={form.values.dueMonths}
onChange={(v) => form.setFieldValue('dueMonths', v)}
error={form.errors.dueMonths}
maxValues={form.values.frequency === 'annual' ? 1 : 4}
/>
)}
<Group grow>
<NumberInput
label={`Regular Assessment (per unit${freqSuffix(form.values.frequency)})`}
prefix="$"
decimalScale={2}
min={0}
{...form.getInputProps('regularAssessment')}
/>
<NumberInput
label={`Special Assessment (per unit${freqSuffix(form.values.frequency)})`}
prefix="$"
decimalScale={2}
min={0}
{...form.getInputProps('specialAssessment')}
/>
</Group>
<Group grow>
<NumberInput label="Expected Unit Count" min={0} {...form.getInputProps('unitCount')} />
<NumberInput
label="Due Day of Month"
description="Day invoices are due (1-28)"
min={1}
max={28}
{...form.getInputProps('dueDay')}
/>
</Group>
<Button type="submit" loading={saveMutation.isPending}>
{editing ? 'Update' : 'Create'}
</Button>
</Stack>
</form>
</Modal>
</Stack>
);
}