@tuturuuu/ui 0.33.0 → 0.34.0

package/src/components/ui/finance/invoices/subscription-coverage.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  isSubscriptionMonthCoveredByInvoice as covered,
+  isSubscriptionMonthPaidForGroup as paid,
+  isSubscriptionRangePaidForGroup as range,
+  type SubscriptionCoverageInvoice,
+} from './subscription-coverage';
+import { getGroupPaymentStatus, type WorkspaceUserGroup } from './utils';
+
+const explicit: SubscriptionCoverageInvoice = {
+  group_id: 'g1',
+  valid_until: '2026-04-01T00:00:00Z',
+  covered_months: ['2026-01-01', '2026-03-01'],
+};
+describe('explicit tuition coverage', () => {
+  afterEach(() => vi.useRealTimers());
+  it.each(['2026-01', '2026-03'])('covers recorded month %s', (month) =>
+    expect(covered(month, explicit)).toBe(true)
+  );
+  it.each(['2025-12', '2026-02', '2026-04'])(
+    'does not infer unrecorded month %s from valid_until',
+    (month) => expect(covered(month, explicit)).toBe(false)
+  );
+  it('uses months even without a compatibility expiry', () =>
+    expect(covered('2026-01', { covered_months: ['2026-01-01'] })).toBe(true));
+  it('keeps null legacy coverage semantics', () => {
+    const legacy = { valid_until: '2026-03-01', covered_months: null };
+    expect(covered('2026-02', legacy)).toBe(true);
+    expect(covered('2026-03', legacy)).toBe(false);
+  });
+  it('treats empty explicit coverage as empty rather than legacy', () =>
+    expect(covered('2026-01', { ...explicit, covered_months: [] })).toBe(
+      false
+    ));
+  it('isolates groups', () =>
+    expect(paid('g2', '2026-01', [explicit])).toBe(false));
+  it('combines separate payments without masking gaps', () => {
+    const rows = [explicit, { ...explicit, covered_months: ['2026-02-01'] }];
+    expect(range('g1', '2026-01', 3, [explicit])).toBe(false);
+    expect(range('g1', '2026-01', 3, rows)).toBe(true);
+    expect(range('g1', '2026-01', 4, rows)).toBe(false);
+  });
+  it('combines legacy cutoff and exact modern months', () => {
+    const rows = [explicit, { group_id: 'g1', valid_until: '2026-03-01' }];
+    expect(range('g1', '2026-01', 3, rows)).toBe(true);
+    expect(paid('g1', '2026-04', rows)).toBe(false);
+  });
+  it('does not label an unpaid current-month gap active', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(2026, 1, 10));
+    expect(
+      getGroupPaymentStatus({ id: 'g1' } as WorkspaceUserGroup, explicit, [
+        explicit,
+      ])
+    ).toBe('expired');
+  });
+  it('uses all invoices for the current-month badge', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(2026, 1, 10));
+    const rows = [explicit, { ...explicit, covered_months: ['2026-02-01'] }];
+    expect(
+      getGroupPaymentStatus({ id: 'g1' } as WorkspaceUserGroup, explicit, rows)
+    ).toBe('active');
+  });
+  it('expires at the next gap rather than the latest paid month', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(2026, 0, 25));
+    expect(
+      getGroupPaymentStatus({ id: 'g1' } as WorkspaceUserGroup, explicit, [
+        explicit,
+      ])
+    ).toBe('expiringSoon');
+  });
+});

package/src/components/ui/finance/invoices/subscription-coverage.ts

@@ -0,0 +1,109 @@
+import {
+  getCoverageMonths,
+  getMonthStartDate,
+  parseLocalCalendarDate,
+} from './civil-month';
+export type SubscriptionCoverageInvoice = {
+  created_at?: string | null;
+  group_id?: string;
+  valid_until?: string | null;
+  covered_months?: string[] | null;
+};
+
+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?.covered_months != null)
+    return invoice.covered_months.some(
+      (month) => month.slice(0, 7) === selectedMonth
+    );
+  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 =>
+  latestInvoices.some(
+    (invoice) =>
+      invoice.group_id === groupId &&
+      isSubscriptionMonthCoveredByInvoice(selectedMonth, invoice)
+  );
+
+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
+    )
+  );
+};

package/src/components/ui/finance/invoices/subscription-invoice.tsx

@@ -61,6 +61,7 @@ import { useSubscriptionInvoiceContent } from './hooks/use-subscription-invoice-
 import { createSubscriptionInvoiceWithInternalApi } from './internal-api';
 import { formatInvoiceRecalculationDescription } from './invoice-visibility-format';
 import { ProductSelection } from './product-selection';
+import { invalidateInvoiceMutationQueries } from './query-invalidation';
 import type { SubscriptionInvoiceProps } from './subscription-invoice-props';
 import type { SelectedProductItem } from './types';
 import {
@@ -800,7 +801,7 @@ export function SubscriptionInvoice({
 
     setIsCreating(true);
     try {
-      const requestPayload = {
+      const result = await createSubscriptionInvoiceWithInternalApi(wsId, {
         customer_id: selectedUserId,
         group_ids: selectedGroupIdsForCreate,
         selected_month: effectiveSelectedMonth,
@@ -815,12 +816,8 @@ export function SubscriptionInvoice({
         frontend_discount_amount: discountAmount,
         frontend_total: subscriptionRoundedTotal,
         prepaid_month_count: prepaidMonthCount,
-      };
-
-      const result = await createSubscriptionInvoiceWithInternalApi(wsId, {
-        ...requestPayload,
-        customer_id: selectedUserId,
       });
+      void invalidateInvoiceMutationQueries(queryClient, wsId);
 
       if (result.data?.values_recalculated) {
         const { calculated_values, frontend_values } = result.data;

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>
+  );
+}