@tuturuuu/ui 0.32.0 → 0.34.0

package/src/components/ui/finance/invoices/subscription-payment-analytics.test.tsx

@@ -0,0 +1,168 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SubscriptionPaymentAnalytics } from './subscription-payment-analytics';
+
+const mocks = vi.hoisted(() => ({
+  get: vi.fn(),
+  chart: vi.fn(),
+  userIds: ['u1'],
+  walletIds: ['w1'],
+}));
+vi.mock('@tuturuuu/internal-api/finance-subscription-analytics', () => ({
+  getSubscriptionPaymentAnalytics: mocks.get,
+}));
+vi.mock('next-intl', () => ({
+  useLocale: () => 'en',
+  useTranslations: () => (key: string, values?: Record<string, unknown>) =>
+    values?.count !== undefined ? `${key}:${values.count}` : key,
+}));
+vi.mock('nuqs', () => ({
+  parseAsString: {},
+  parseAsArrayOf: () => ({ withDefault: () => ({}) }),
+  useQueryState: (key: string) => [
+    key === 'userIds' ? mocks.userIds : mocks.walletIds,
+  ],
+}));
+vi.mock('./charts/subscription-payment-chart', () => ({
+  SubscriptionPaymentChart: (props: unknown) => {
+    mocks.chart(props);
+    return <div data-testid="payment-chart" />;
+  },
+}));
+const metrics = {
+  paidUsers: 2,
+  paidGroups: 3,
+  memberships: 4,
+  invoiceCount: 5,
+  amount: 1234,
+};
+const report = {
+  year: 2026,
+  granularity: 'monthly',
+  unallocatedInvoices: 2,
+  currencies: [
+    {
+      currency: 'VND',
+      summary: metrics,
+      periods: [{ period: '2026-01', ...metrics }],
+      distribution: [{ groupCount: 2, userCount: 2 }],
+    },
+  ],
+};
+function mount() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return render(
+    <QueryClientProvider client={client}>
+      <SubscriptionPaymentAnalytics wsId="ws" currency="VND" />
+    </QueryClientProvider>
+  );
+}
+describe('tuition analytics interaction', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // biome-ignore lint/suspicious/noDocumentCookie: Reset the persisted visibility preference for each test.
+    document.cookie = 'finance-confidential-mode=true;path=/';
+    mocks.get.mockResolvedValue(report);
+  });
+  it('loads selected user and wallet filters and starts with hidden amounts', async () => {
+    mount();
+    await screen.findByText('unallocated:2');
+    expect(mocks.get).toHaveBeenCalledWith(
+      'ws',
+      expect.objectContaining({
+        granularity: 'monthly',
+        userIds: ['u1'],
+        walletIds: ['w1'],
+      })
+    );
+    expect(screen.queryByText(/1,234/)).not.toBeInTheDocument();
+    expect(screen.getAllByText('•••••').length).toBeGreaterThan(0);
+    expect(mocks.chart).toHaveBeenLastCalledWith(
+      expect.objectContaining({ hidden: true, metric: 'paidUsers' })
+    );
+  });
+  it('switches coverage granularity and year', async () => {
+    mount();
+    await screen.findByTestId('payment-chart');
+    fireEvent.click(screen.getByRole('button', { name: 'yearly' }));
+    await waitFor(() =>
+      expect(mocks.get).toHaveBeenLastCalledWith(
+        'ws',
+        expect.objectContaining({ granularity: 'yearly' })
+      )
+    );
+    fireEvent.change(screen.getByLabelText('ending_year'), {
+      target: { value: '2025' },
+    });
+    await waitFor(() =>
+      expect(mocks.get).toHaveBeenLastCalledWith(
+        'ws',
+        expect.objectContaining({ year: 2025, granularity: 'yearly' })
+      )
+    );
+  });
+  it('switches the chart metric and reveals value only when requested', async () => {
+    mount();
+    await screen.findByTestId('payment-chart');
+    fireEvent.click(screen.getByRole('button', { name: /amount/ }));
+    expect(mocks.chart).toHaveBeenLastCalledWith(
+      expect.objectContaining({ metric: 'amount', hidden: true })
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'show' }));
+    expect(mocks.chart).toHaveBeenLastCalledWith(
+      expect.objectContaining({ hidden: false })
+    );
+    expect(screen.getAllByText(/1,234/).length).toBeGreaterThan(0);
+  });
+  it('switches currencies without combining values', async () => {
+    mocks.get.mockResolvedValue({
+      ...report,
+      currencies: [
+        ...report.currencies,
+        {
+          ...report.currencies[0],
+          currency: 'USD',
+          summary: { ...metrics, amount: 99 },
+        },
+      ],
+    });
+    mount();
+    await screen.findByLabelText('currency');
+    fireEvent.change(screen.getByLabelText('currency'), {
+      target: { value: 'USD' },
+    });
+    expect(mocks.chart).toHaveBeenLastCalledWith(
+      expect.objectContaining({ currency: 'USD' })
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'show' }));
+    expect(screen.getByText('$99.00')).toBeInTheDocument();
+  });
+  it('shows an error and supports retry', async () => {
+    mocks.get.mockRejectedValueOnce(new Error('unavailable'));
+    mount();
+    await screen.findByRole('alert');
+    expect(screen.queryByTestId('payment-chart')).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: 'retry' }));
+    await screen.findByTestId('payment-chart');
+  });
+  it('distinguishes unallocated legacy invoices from an empty exact-coverage report', async () => {
+    mocks.get.mockResolvedValue({ ...report, currencies: [] });
+    mount();
+    await screen.findByText('empty');
+    expect(screen.getByText('unallocated:2')).toBeInTheDocument();
+    expect(screen.queryByTestId('payment-chart')).not.toBeInTheDocument();
+  });
+  it('exposes period values in an accessible table and group distribution', async () => {
+    mount();
+    await screen.findByText('table');
+    fireEvent.click(screen.getByText('table'));
+    await screen.findByRole('table');
+    expect(
+      screen.getByRole('rowheader', { name: '2026-01' })
+    ).toBeInTheDocument();
+    expect(screen.getByLabelText('distribution_value')).toBeInTheDocument();
+  });
+});

package/src/components/ui/finance/invoices/subscription-payment-analytics.tsx

@@ -0,0 +1,253 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import { Eye, EyeOff, RefreshCw } from '@tuturuuu/icons';
+import { getSubscriptionPaymentAnalytics } from '@tuturuuu/internal-api/finance-subscription-analytics';
+import { useLocale, useTranslations } from 'next-intl';
+import { parseAsArrayOf, parseAsString, useQueryState } from 'nuqs';
+import { useId, useState } from 'react';
+import { Button } from '../../button';
+import { Card, CardContent, CardHeader } from '../../card';
+import { Skeleton } from '../../skeleton';
+import {
+  FINANCE_HIDDEN_AMOUNT,
+  useFinanceConfidentialVisibility,
+} from '../shared/use-finance-confidential-visibility';
+import {
+  type PaymentMetric,
+  SubscriptionPaymentChart,
+} from './charts/subscription-payment-chart';
+import { SubscriptionPaymentDetails } from './charts/subscription-payment-details';
+
+export function SubscriptionPaymentAnalytics({
+  wsId,
+  currency = 'USD',
+}: {
+  wsId: string;
+  currency?: string;
+}) {
+  const t = useTranslations('invoice-subscriptions');
+  const locale = useLocale();
+  const [year, setYear] = useState(() => new Date().getFullYear());
+  const [granularity, setGranularity] = useState<'monthly' | 'yearly'>(
+    'monthly'
+  );
+  const [metric, setMetric] = useState<PaymentMetric>('paidUsers');
+  const [selectedCurrency, setCurrency] = useState(currency);
+  const { isConfidential, toggleConfidential } =
+    useFinanceConfidentialVisibility();
+  const [userIds] = useQueryState(
+    'userIds',
+    parseAsArrayOf(parseAsString).withDefault([])
+  );
+  const [walletIds] = useQueryState(
+    'walletIds',
+    parseAsArrayOf(parseAsString).withDefault([])
+  );
+  const id = useId();
+  const query = useQuery({
+    queryKey: [
+      'invoice-subscription-analytics',
+      wsId,
+      year,
+      granularity,
+      userIds,
+      walletIds,
+    ],
+    queryFn: () =>
+      getSubscriptionPaymentAnalytics(wsId, {
+        year,
+        granularity,
+        userIds,
+        walletIds,
+      }),
+    staleTime: 30_000,
+    retry: false,
+  });
+  const data =
+    query.data?.currencies.find(
+      (value) => value.currency === selectedCurrency
+    ) ?? query.data?.currencies[0];
+  const format = (value: number, key: string) =>
+    key === 'amount'
+      ? isConfidential
+        ? FINANCE_HIDDEN_AMOUNT
+        : new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: data?.currency ?? currency,
+          }).format(value)
+      : new Intl.NumberFormat(locale).format(value);
+  return (
+    <Card>
+      <CardHeader className="space-y-4">
+        <div className="flex flex-wrap items-start justify-between gap-4">
+          <div className="max-w-2xl">
+            <h2 className="font-semibold text-lg tracking-tight">
+              {t('title')}
+            </h2>
+            <p className="mt-1 text-muted-foreground text-sm">
+              {t('description')}
+            </p>
+          </div>
+          <div className="flex gap-2">
+            <Button
+              variant="ghost"
+              size="icon"
+              aria-label={t(isConfidential ? 'show' : 'hide')}
+              onClick={toggleConfidential}
+            >
+              {isConfidential ? (
+                <Eye className="size-4" />
+              ) : (
+                <EyeOff className="size-4" />
+              )}
+            </Button>
+            <Button
+              variant="ghost"
+              size="icon"
+              aria-label={t('refresh')}
+              disabled={query.isFetching}
+              onClick={() => query.refetch()}
+            >
+              <RefreshCw className="size-4" />
+            </Button>
+          </div>
+        </div>
+        <div className="flex flex-wrap items-end gap-3">
+          <fieldset
+            className="inline-flex rounded-lg border p-1"
+            aria-label={t('granularity')}
+          >
+            {(['monthly', 'yearly'] as const).map((value) => (
+              <Button
+                key={value}
+                size="sm"
+                variant={granularity === value ? 'secondary' : 'ghost'}
+                aria-pressed={granularity === value}
+                onClick={() => setGranularity(value)}
+              >
+                {t(value)}
+              </Button>
+            ))}
+          </fieldset>
+          <label className="grid gap-1 text-xs" htmlFor={`${id}-year`}>
+            {t(granularity === 'monthly' ? 'year' : 'ending_year')}
+            <select
+              id={`${id}-year`}
+              className="h-9 rounded-lg border bg-background px-3 text-sm"
+              value={year}
+              onChange={(event) => setYear(Number(event.target.value))}
+            >
+              {Array.from(
+                { length: new Date().getFullYear() - 2000 + 3 },
+                (_, index) => new Date().getFullYear() + 2 - index
+              ).map((value) => (
+                <option key={value} value={value}>
+                  {value}
+                </option>
+              ))}
+            </select>
+          </label>
+          {(query.data?.currencies.length ?? 0) > 1 && (
+            <label className="grid gap-1 text-xs" htmlFor={`${id}-currency`}>
+              {t('currency')}
+              <select
+                id={`${id}-currency`}
+                className="h-9 rounded-lg border bg-background px-3 text-sm"
+                value={data?.currency}
+                onChange={(event) => setCurrency(event.target.value)}
+              >
+                {query.data?.currencies.map((value) => (
+                  <option key={value.currency}>{value.currency}</option>
+                ))}
+              </select>
+            </label>
+          )}
+          <p className="text-muted-foreground text-xs">{t('filters')}</p>
+        </div>
+      </CardHeader>
+      <CardContent className="space-y-5" aria-busy={query.isFetching}>
+        {query.isLoading ? (
+          <div className="space-y-4">
+            <Skeleton className="h-20 w-full" />
+            <Skeleton className="h-72 w-full" />
+          </div>
+        ) : query.isError ? (
+          <div
+            role="alert"
+            className="rounded-lg border border-destructive/30 p-6 text-sm"
+          >
+            <p>{t('error')}</p>
+            <Button
+              className="mt-3"
+              variant="outline"
+              onClick={() => query.refetch()}
+            >
+              {t('retry')}
+            </Button>
+          </div>
+        ) : (
+          <>
+            {(query.data?.unallocatedInvoices ?? 0) > 0 && (
+              <p
+                role="status"
+                className="rounded-lg border bg-muted/40 p-3 text-sm"
+              >
+                {t('unallocated', { count: query.data!.unallocatedInvoices })}
+              </p>
+            )}
+            {!data ? (
+              <div className="rounded-xl border border-dashed p-10 text-center">
+                <p className="font-medium">{t('empty')}</p>
+                <p className="mt-2 text-muted-foreground text-sm">
+                  {t('empty_help')}
+                </p>
+              </div>
+            ) : (
+              <>
+                <div className="grid grid-cols-3 gap-3 lg:grid-cols-4">
+                  {(
+                    [
+                      'paidUsers',
+                      'paidGroups',
+                      'memberships',
+                      'amount',
+                    ] as const
+                  ).map((key) => (
+                    <button
+                      key={key}
+                      type="button"
+                      aria-pressed={metric === key}
+                      onClick={() => setMetric(key)}
+                      className={`flex flex-col justify-between rounded-xl border p-3 text-start sm:p-4 ${key === 'amount' ? 'col-span-3 lg:col-span-1' : ''} transition-colors focus-visible:outline-2 focus-visible:outline-ring ${metric === key ? 'border-primary bg-primary/5' : 'hover:bg-muted/50'}`}
+                    >
+                      <span className="text-muted-foreground text-xs">
+                        {t(key)}
+                      </span>
+                      <span className="mt-2 block break-words font-semibold text-xl tabular-nums tracking-tight">
+                        {format(data.summary[key], key)}
+                      </span>
+                    </button>
+                  ))}
+                </div>
+                <SubscriptionPaymentChart
+                  periods={data.periods}
+                  metric={metric}
+                  currency={data.currency}
+                  hidden={isConfidential}
+                />
+                <SubscriptionPaymentDetails
+                  data={data}
+                  hidden={isConfidential}
+                />
+              </>
+            )}
+            <p className="text-muted-foreground text-xs leading-relaxed">
+              {t('method')}
+            </p>
+          </>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/ui/finance/invoices/utils.ts

@@ -1,3 +1,18 @@
+import {
+  getSubscriptionCoverageInvoiceForGroup,
+  isSubscriptionMonthPaidForGroup,
+  type SubscriptionCoverageInvoice,
+} from './subscription-coverage';
+
+export {
+  getSubscriptionCoverageInvoiceForGroup,
+  isSubscriptionMonthCoveredByInvoice,
+  isSubscriptionMonthPaidForGroup,
+  isSubscriptionRangeFullyPaidForGroups,
+  isSubscriptionRangePaidForGroup,
+  type SubscriptionCoverageInvoice,
+} from './subscription-coverage';
+
 import type { Database } from '@tuturuuu/types';
 import {
   formatMonthLabel,
@@ -48,12 +63,6 @@ export type UserGroup = {
   workspace_user_groups: WorkspaceUserGroup | null;
 };
 
-export type SubscriptionCoverageInvoice = {
-  created_at?: string | null;
-  group_id?: string;
-  valid_until?: string | null;
-};
-
 export type BillableSession = {
   date: string;
   groupId: string;
@@ -114,99 +123,6 @@ export const resolveSubscriptionInvoiceCategoryId = ({
   return defaultCategoryId ?? '';
 };
 
-const getComparableTimestamp = (value: string | null | undefined): number => {
-  if (!value) return 0;
-  const timestamp = new Date(value).getTime();
-  return Number.isNaN(timestamp) ? 0 : timestamp;
-};
-
-const getComparableValidUntilTimestamp = (
-  invoice: SubscriptionCoverageInvoice
-): number => {
-  const validUntil = parseLocalCalendarDate(invoice.valid_until);
-  return Number.isNaN(validUntil.getTime()) ? 0 : validUntil.getTime();
-};
-
-export const getSubscriptionCoverageInvoiceForGroup = (
-  latestInvoices: SubscriptionCoverageInvoice[],
-  groupId: string
-): SubscriptionCoverageInvoice | undefined =>
-  latestInvoices
-    .filter((invoice) => invoice.group_id === groupId)
-    .filter((invoice) => getComparableValidUntilTimestamp(invoice) > 0)
-    .sort((a, b) => {
-      const validUntilDiff =
-        getComparableValidUntilTimestamp(b) -
-        getComparableValidUntilTimestamp(a);
-      if (validUntilDiff !== 0) return validUntilDiff;
-
-      return (
-        getComparableTimestamp(b.created_at) -
-        getComparableTimestamp(a.created_at)
-      );
-    })[0];
-
-export const isSubscriptionMonthCoveredByInvoice = (
-  selectedMonth: string,
-  invoice: SubscriptionCoverageInvoice | null | undefined
-): boolean => {
-  if (!invoice?.valid_until) return false;
-
-  const selectedMonthStart = getMonthStartDate(selectedMonth);
-  const validUntilMonthStart = getMonthStartDate(invoice.valid_until);
-
-  if (
-    Number.isNaN(selectedMonthStart.getTime()) ||
-    Number.isNaN(validUntilMonthStart.getTime())
-  ) {
-    return false;
-  }
-
-  return selectedMonthStart < validUntilMonthStart;
-};
-
-export const isSubscriptionMonthPaidForGroup = (
-  groupId: string,
-  selectedMonth: string,
-  latestInvoices: SubscriptionCoverageInvoice[]
-): boolean =>
-  isSubscriptionMonthCoveredByInvoice(
-    selectedMonth,
-    getSubscriptionCoverageInvoiceForGroup(latestInvoices, groupId)
-  );
-
-export const isSubscriptionRangePaidForGroup = (
-  groupId: string,
-  selectedMonth: string,
-  prepaidMonthCount: number,
-  latestInvoices: SubscriptionCoverageInvoice[]
-): boolean => {
-  const coverageMonths = getCoverageMonths(selectedMonth, prepaidMonthCount);
-  if (coverageMonths.length === 0) return false;
-
-  return coverageMonths.every((month) =>
-    isSubscriptionMonthPaidForGroup(groupId, month, latestInvoices)
-  );
-};
-
-export const isSubscriptionRangeFullyPaidForGroups = (
-  groupIds: string[],
-  selectedMonth: string,
-  prepaidMonthCount: number,
-  latestInvoices: SubscriptionCoverageInvoice[]
-): boolean => {
-  if (groupIds.length === 0) return false;
-
-  return groupIds.every((groupId) =>
-    isSubscriptionRangePaidForGroup(
-      groupId,
-      selectedMonth,
-      prepaidMonthCount,
-      latestInvoices
-    )
-  );
-};
-
 export const getAttendanceStats = (
   attendance: AttendanceRecord[]
 ): AttendanceStats => {
@@ -251,7 +167,7 @@ const getGroupValidUntilDate = (
   groupId: string
 ): Date | null => {
   const latestInvoice = getSubscriptionCoverageInvoiceForGroup(
-    latestInvoices,
+    latestInvoices.filter((invoice) => invoice.covered_months == null),
     groupId
   );
   if (!latestInvoice?.valid_until) return null;
@@ -285,7 +201,11 @@ export const getBillableSessionsForGroups = (
       (candidate) => candidate.workspace_user_groups?.id === groupId
     )?.workspace_user_groups;
 
-    if (!group?.sessions?.length) return [];
+    if (
+      !group?.sessions?.length ||
+      isSubscriptionMonthPaidForGroup(groupId, selectedMonth, latestInvoices)
+    )
+      return [];
 
     const validUntil = getGroupValidUntilDate(latestInvoices, groupId);
 
@@ -330,7 +250,12 @@ export const getBillableAttendanceRecords = (
 
   return attendance.filter((record) => {
     const groupId = record.group_id;
-    if (!groupId || !groupIds.includes(groupId)) return false;
+    if (
+      !groupId ||
+      !groupIds.includes(groupId) ||
+      isSubscriptionMonthPaidForGroup(groupId, selectedMonth, latestInvoices)
+    )
+      return false;
 
     const attendanceDate = parseLocalCalendarDate(record.date);
     if (!isDateInMonth(attendanceDate, selectedMonth)) return false;
@@ -668,9 +593,10 @@ const EXPIRING_SOON_DAYS = 14;
 export type GroupPaymentStatus = 'active' | 'expiringSoon' | 'expired';
 export function getGroupPaymentStatus(
   group: WorkspaceUserGroup | null,
-  latestInvoice:
-    | { valid_until?: string | null; created_at?: string | null }
-    | undefined
+  latestInvoice: SubscriptionCoverageInvoice | undefined,
+  coverageInvoices: SubscriptionCoverageInvoice[] = latestInvoice
+    ? [latestInvoice]
+    : []
 ): GroupPaymentStatus {
   const today = new Date();
   today.setHours(0, 0, 0, 0);
@@ -685,9 +611,25 @@ export function getGroupPaymentStatus(
     if (today > endDate) return 'expired';
   }
 
-  const validUntil = latestInvoice?.valid_until
+  let validUntil = latestInvoice?.valid_until
     ? parseLocalCalendarDate(latestInvoice.valid_until)
     : null;
+  if (coverageInvoices.some((invoice) => invoice.covered_months != null)) {
+    const cursor = new Date(today.getFullYear(), today.getMonth(), 1);
+    const month = () =>
+      `${cursor.getFullYear()}-${String(cursor.getMonth() + 1).padStart(2, '0')}`;
+    if (!isSubscriptionMonthPaidForGroup(group.id, month(), coverageInvoices))
+      return 'expired';
+    // Walk contiguous paid months so a later payment cannot conceal a gap.
+    for (
+      let i = 0;
+      i < 1200 &&
+      isSubscriptionMonthPaidForGroup(group.id, month(), coverageInvoices);
+      i++
+    )
+      cursor.setMonth(cursor.getMonth() + 1);
+    validUntil = cursor;
+  }
   if (validUntil) {
     validUntil.setHours(0, 0, 0, 0);
     const daysUntilExpiry = Math.ceil(