@tuturuuu/ui 0.13.0 → 0.16.0

package/src/components/ui/finance/invoices/new-invoice-page.test.tsx

@@ -11,6 +11,7 @@ const invoiceMocks = vi.hoisted(() => ({
 
 const nuqsState = vi.hoisted(() => ({
   invoiceType: 'standard' as 'standard' | 'subscription',
+  values: new Map<string, number | null>(),
 }));
 
 vi.mock('next-intl', () => ({
@@ -23,7 +24,11 @@ vi.mock('nuqs', () => ({
       return [nuqsState.invoiceType, vi.fn()];
     }
 
-    if (key === 'amount') {
+    if (nuqsState.values.has(key)) {
+      return [nuqsState.values.get(key), vi.fn()];
+    }
+
+    if (['amount', 'billable_quantity', 'suggested_total'].includes(key)) {
       return [null, vi.fn()];
     }
 
@@ -80,11 +85,13 @@ describe('NewInvoicePage', () => {
     invoiceMocks.StandardInvoice.mockClear();
     invoiceMocks.SubscriptionInvoice.mockClear();
     nuqsState.invoiceType = 'standard';
+    nuqsState.values.clear();
     fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       json: async () => ({
         DEFAULT_CURRENCY: 'SGD',
         DEFAULT_SUBSCRIPTION_CATEGORY_ID: 'category-1',
+        default_category_id: 'category-general',
         default_wallet_id: 'wallet-1',
       }),
     });
@@ -101,7 +108,7 @@ describe('NewInvoicePage', () => {
     await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
 
     expect(fetchMock).toHaveBeenCalledWith(
-      '/api/v1/workspaces/ws-1/settings/configs?ids=default_wallet_id,DEFAULT_SUBSCRIPTION_CATEGORY_ID,DEFAULT_CURRENCY',
+      '/api/v1/workspaces/ws-1/settings/configs?ids=default_wallet_id,default_category_id,DEFAULT_SUBSCRIPTION_CATEGORY_ID,DEFAULT_CURRENCY',
       { cache: 'no-store' }
     );
     expect(invoiceMocks.StandardInvoice).toHaveBeenCalled();
@@ -110,6 +117,7 @@ describe('NewInvoicePage', () => {
     await waitFor(() =>
       expect(invoiceMocks.StandardInvoice).toHaveBeenLastCalledWith(
         expect.objectContaining({
+          defaultCategoryId: 'category-general',
           defaultCurrency: 'SGD',
           defaultWalletId: 'wallet-1',
         })
@@ -133,6 +141,86 @@ describe('NewInvoicePage', () => {
           defaultCategoryId: 'category-1',
           defaultCurrency: 'SGD',
           defaultWalletId: 'wallet-1',
+          workspaceTimezone: undefined,
+        })
+      )
+    );
+  });
+
+  it('forwards a pending invoice quantity and suggested monetary total', async () => {
+    nuqsState.invoiceType = 'subscription';
+    nuqsState.values.set('billable_quantity', 3);
+    nuqsState.values.set('suggested_total', 1_500_000);
+
+    renderPage();
+
+    await waitFor(() =>
+      expect(invoiceMocks.SubscriptionInvoice).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          prefillQuantity: 3,
+          suggestedTotal: 1_500_000,
+        })
+      )
+    );
+  });
+
+  it('keeps legacy amount links working as a quantity fallback', async () => {
+    nuqsState.invoiceType = 'subscription';
+    nuqsState.values.set('amount', 4);
+
+    renderPage();
+
+    await waitFor(() =>
+      expect(invoiceMocks.SubscriptionInvoice).toHaveBeenLastCalledWith(
+        expect.objectContaining({ prefillQuantity: 4 })
+      )
+    );
+  });
+
+  it('forwards server-seeded defaults and timezone before config refresh completes', async () => {
+    nuqsState.invoiceType = 'subscription';
+    fetchMock.mockReturnValueOnce(new Promise(() => {}));
+
+    renderPage({
+      defaultCurrency: 'VND',
+      initialDefaultCategoryId: 'category-general-server',
+      initialDefaultSubscriptionCategoryId: 'category-subscription-server',
+      initialDefaultWalletId: 'wallet-server',
+      workspaceTimezone: 'Asia/Ho_Chi_Minh',
+    });
+
+    await waitFor(() =>
+      expect(invoiceMocks.SubscriptionInvoice).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          defaultCategoryId: 'category-subscription-server',
+          defaultCurrency: 'VND',
+          defaultWalletId: 'wallet-server',
+          workspaceTimezone: 'Asia/Ho_Chi_Minh',
+        })
+      )
+    );
+  });
+
+  it('falls subscription invoice category back to the transaction default', async () => {
+    nuqsState.invoiceType = 'subscription';
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        DEFAULT_CURRENCY: 'SGD',
+        DEFAULT_SUBSCRIPTION_CATEGORY_ID: null,
+        default_category_id: 'category-general',
+        default_wallet_id: 'wallet-1',
+      }),
+    });
+
+    renderPage();
+
+    await waitFor(() =>
+      expect(invoiceMocks.SubscriptionInvoice).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          defaultCategoryId: 'category-general',
+          defaultCurrency: 'SGD',
+          defaultWalletId: 'wallet-1',
         })
       )
     );

package/src/components/ui/finance/invoices/new-invoice-page.tsx

@@ -27,6 +27,7 @@ import { SubscriptionInvoice } from './subscription-invoice';
 
 const INVOICE_DEFAULT_CONFIG_IDS = [
   'default_wallet_id',
+  'default_category_id',
   'DEFAULT_SUBSCRIPTION_CATEGORY_ID',
   'DEFAULT_CURRENCY',
 ] as const;
@@ -40,7 +41,11 @@ interface Props {
   canReadInvoiceProductStock?: boolean;
   canReadGroupLinkedProducts?: boolean;
   defaultCurrency?: string;
+  initialDefaultCategoryId?: string | null;
+  initialDefaultSubscriptionCategoryId?: string | null;
+  initialDefaultWalletId?: string | null;
   permissionRequestUser?: FinancePermissionRequestUser | null;
+  workspaceTimezone?: string | null;
 }
 
 export default function NewInvoicePage({
@@ -52,7 +57,11 @@ export default function NewInvoicePage({
   canReadInvoiceProductStock = true,
   canReadGroupLinkedProducts = true,
   defaultCurrency: workspaceDefaultCurrency,
+  initialDefaultCategoryId,
+  initialDefaultSubscriptionCategoryId,
+  initialDefaultWalletId,
   permissionRequestUser,
+  workspaceTimezone,
 }: Props) {
   const t = useTranslations();
   const [dropdownOpen, setDropdownOpen] = useState(false);
@@ -63,20 +72,44 @@ export default function NewInvoicePage({
     serialize: (value) => value,
   });
 
-  const [prefillAmount] = useQueryState('amount', {
+  const [billableQuantity] = useQueryState('billable_quantity', {
     parse: (value) => {
       const parsed = Number(value);
       return Number.isFinite(parsed) ? parsed : null;
     },
   });
+  const [legacyPrefillAmount] = useQueryState('amount', {
+    parse: (value) => {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    },
+  });
+  const [suggestedTotal] = useQueryState('suggested_total', {
+    parse: (value) => {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+    },
+  });
 
-  const { data: defaultConfigs = {} } = useWorkspaceConfigs(
+  const { data: refreshedDefaultConfigs = {} } = useWorkspaceConfigs(
     wsId,
     INVOICE_DEFAULT_CONFIG_IDS
   );
+  const defaultConfigs = {
+    DEFAULT_CURRENCY: workspaceDefaultCurrency ?? null,
+    DEFAULT_SUBSCRIPTION_CATEGORY_ID:
+      initialDefaultSubscriptionCategoryId ?? null,
+    default_category_id: initialDefaultCategoryId ?? null,
+    default_wallet_id: initialDefaultWalletId ?? null,
+    ...refreshedDefaultConfigs,
+  };
   const defaultWalletId = defaultConfigs.default_wallet_id ?? undefined;
-  const defaultCategoryId =
+  const defaultTransactionCategoryId =
+    defaultConfigs.default_category_id ?? undefined;
+  const defaultSubscriptionCategoryId =
     defaultConfigs.DEFAULT_SUBSCRIPTION_CATEGORY_ID ?? undefined;
+  const defaultCategoryId =
+    defaultSubscriptionCategoryId ?? defaultTransactionCategoryId;
   const defaultCurrency = resolveSupportedCurrency(
     defaultConfigs.DEFAULT_CURRENCY,
     resolveSupportedCurrency(workspaceDefaultCurrency)
@@ -231,6 +264,7 @@ export default function NewInvoicePage({
             <StandardInvoice
               wsId={wsId}
               defaultWalletId={defaultWalletId}
+              defaultCategoryId={defaultTransactionCategoryId}
               defaultCurrency={defaultCurrency}
               canChangeFinanceWallets={canChangeFinanceWallets}
               canSetFinanceWalletsOnCreate={canSetFinanceWalletsOnCreate}
@@ -247,10 +281,12 @@ export default function NewInvoicePage({
           {invoiceType === 'subscription' ? (
             <SubscriptionInvoice
               wsId={wsId}
-              prefillAmount={prefillAmount}
+              prefillQuantity={billableQuantity ?? legacyPrefillAmount}
+              suggestedTotal={suggestedTotal}
               defaultWalletId={defaultWalletId}
               defaultCategoryId={defaultCategoryId}
               defaultCurrency={defaultCurrency}
+              workspaceTimezone={workspaceTimezone}
               canChangeFinanceWallets={canChangeFinanceWallets}
               canSetFinanceWalletsOnCreate={canSetFinanceWalletsOnCreate}
               canReadInvoiceProducts={canReadInvoiceProducts}

package/src/components/ui/finance/invoices/pending-columns.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { buildPendingInvoiceCreateUrl } from './pending-columns';
+
+describe('buildPendingInvoiceCreateUrl', () => {
+  it('carries both the billable quantity and suggested monetary total', () => {
+    const url = new URL(
+      buildPendingInvoiceCreateUrl({
+        attendanceDays: 3,
+        financePrefix: '',
+        groupIds: ['group-1', 'group-2'],
+        month: '2026-07',
+        potentialTotal: 1_500_000,
+        useAttendanceBased: true,
+        userId: 'user-1',
+        wsId: 'ws-1',
+      }),
+      'https://finance.test'
+    );
+
+    expect(url.pathname).toBe('/ws-1/invoices/new');
+    expect(url.searchParams.get('billable_quantity')).toBe('3');
+    expect(url.searchParams.get('suggested_total')).toBe('1500000');
+    expect(url.searchParams.get('amount')).toBeNull();
+    expect(url.searchParams.get('group_ids')).toBe('group-1,group-2');
+  });
+});

package/src/components/ui/finance/invoices/pending-columns.tsx

@@ -21,6 +21,40 @@ type PendingInvoiceRow = PendingInvoice & {
   group_names?: string[];
 };
 
+export function buildPendingInvoiceCreateUrl({
+  attendanceDays,
+  financePrefix,
+  groupIds,
+  month,
+  potentialTotal,
+  useAttendanceBased,
+  userId,
+  wsId,
+}: {
+  attendanceDays: number;
+  financePrefix: string;
+  groupIds: string[];
+  month: string;
+  potentialTotal: number;
+  useAttendanceBased: boolean;
+  userId: string;
+  wsId: string;
+}) {
+  const searchParams = new URLSearchParams({
+    type: 'subscription',
+    user_id: userId,
+  });
+
+  if (month) searchParams.set('month', month);
+  if (useAttendanceBased) {
+    searchParams.set('billable_quantity', String(attendanceDays));
+  }
+  searchParams.set('suggested_total', String(potentialTotal));
+  if (groupIds.length > 0) searchParams.set('group_ids', groupIds.join(','));
+
+  return `/${wsId}${financePrefix}/invoices/new?${searchParams.toString()}`;
+}
+
 function PendingInvoicePotentialTotalCell({
   amount,
   currency,
@@ -268,6 +302,7 @@ export const pendingInvoiceColumns = (
         ).filter((id: string) => Boolean(id));
         const monthsOwed = row.getValue<string[]>('months_owed');
         const attendanceDays = row.getValue<number>('attendance_days');
+        const potentialTotal = row.getValue<number>('potential_total') || 0;
 
         // Get the LAST (most recent) unpaid month from the array
         const lastUnpaidMonth =
@@ -277,20 +312,16 @@ export const pendingInvoiceColumns = (
 
         if (!wsId) return null;
 
-        const searchParams = new URLSearchParams();
-        searchParams.set('type', 'subscription');
-        searchParams.set('user_id', userId);
-        if (lastUnpaidMonth) {
-          searchParams.set('month', lastUnpaidMonth);
-        }
-        if (useAttendanceBased) {
-          searchParams.set('amount', String(attendanceDays));
-        }
-        if (groupIds.length > 0) {
-          searchParams.set('group_ids', groupIds.join(','));
-        }
-
-        const createInvoiceUrl = `/${wsId}${financePrefix}/invoices/new?${searchParams.toString()}`;
+        const createInvoiceUrl = buildPendingInvoiceCreateUrl({
+          attendanceDays,
+          financePrefix,
+          groupIds,
+          month: lastUnpaidMonth ?? '',
+          potentialTotal,
+          useAttendanceBased,
+          userId,
+          wsId,
+        });
 
         return (
           <div className="flex items-center gap-2">

package/src/components/ui/finance/invoices/standard-invoice.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { resolveStandardInvoiceCategoryId } from './standard-invoice';
+
+describe('resolveStandardInvoiceCategoryId', () => {
+  it('prefers a single linked product finance category', () => {
+    expect(
+      resolveStandardInvoiceCategoryId({
+        defaultCategoryId: 'category-default',
+        linkedFinanceCategoryIds: ['category-linked'],
+      })
+    ).toBe('category-linked');
+  });
+
+  it('requires explicit selection when linked product finance categories are mixed', () => {
+    expect(
+      resolveStandardInvoiceCategoryId({
+        defaultCategoryId: 'category-default',
+        linkedFinanceCategoryIds: ['category-a', 'category-b'],
+      })
+    ).toBe('');
+  });
+
+  it('falls back to the transaction default when products do not provide a category', () => {
+    expect(
+      resolveStandardInvoiceCategoryId({
+        defaultCategoryId: 'category-default',
+        linkedFinanceCategoryIds: [],
+      })
+    ).toBe('category-default');
+  });
+});

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

@@ -57,6 +57,7 @@ interface Props {
   printAfterCreate?: boolean;
   downloadImageAfterCreate?: boolean;
   defaultWalletId?: string;
+  defaultCategoryId?: string;
   defaultCurrency?: string;
   canChangeFinanceWallets?: boolean;
   canSetFinanceWalletsOnCreate?: boolean;
@@ -71,6 +72,7 @@ export function StandardInvoice({
   printAfterCreate = false,
   downloadImageAfterCreate = false,
   defaultWalletId,
+  defaultCategoryId,
   defaultCurrency: rawDefaultCurrency = 'USD',
   canChangeFinanceWallets = true,
   canSetFinanceWalletsOnCreate = true,
@@ -194,7 +196,9 @@ export function StandardInvoice({
   }, [defaultWalletId]);
   const [selectedPromotionId, setSelectedPromotionId] =
     useState<string>('none');
-  const [selectedCategoryId, setSelectedCategoryId] = useState<string>('');
+  const [selectedCategoryId, setSelectedCategoryId] = useState<string>(
+    defaultCategoryId || ''
+  );
   const [invoiceContent, setInvoiceContent] = useState<string>('');
   const [invoiceNotes, setInvoiceNotes] = useState<string>('');
   const [isCreating, setIsCreating] = useState(false);
@@ -280,7 +284,6 @@ export function StandardInvoice({
     [selectedProducts]
   );
   const hasMixedLinkedFinanceCategories = linkedFinanceCategoryIds.length > 1;
-  const hasSingleLinkedFinanceCategory = linkedFinanceCategoryIds.length === 1;
 
   // Auto-generate invoice content based on selected products
   useEffect(() => {
@@ -318,19 +321,13 @@ export function StandardInvoice({
   }, [selectedUserId]);
 
   useEffect(() => {
-    if (hasSingleLinkedFinanceCategory) {
-      setSelectedCategoryId(linkedFinanceCategoryIds[0] ?? '');
-      return;
-    }
-
-    if (hasMixedLinkedFinanceCategories) {
-      setSelectedCategoryId('');
-    }
-  }, [
-    hasMixedLinkedFinanceCategories,
-    hasSingleLinkedFinanceCategory,
-    linkedFinanceCategoryIds,
-  ]);
+    setSelectedCategoryId(
+      resolveStandardInvoiceCategoryId({
+        defaultCategoryId,
+        linkedFinanceCategoryIds,
+      })
+    );
+  }, [defaultCategoryId, linkedFinanceCategoryIds]);
 
   useBestPromotionSelection({
     enabled: promotionsAllowed,
@@ -422,7 +419,7 @@ export function StandardInvoice({
         resetRounding();
         setSelectedUserId(null);
         setSelectedWalletId(defaultWalletId || '');
-        setSelectedCategoryId('');
+        setSelectedCategoryId(defaultCategoryId || '');
         setCustomerSearch('');
       }
     } catch (error) {
@@ -657,3 +654,23 @@ export function StandardInvoice({
     </div>
   );
 }
+
+export function resolveStandardInvoiceCategoryId({
+  defaultCategoryId,
+  linkedFinanceCategoryIds,
+}: {
+  defaultCategoryId?: string;
+  linkedFinanceCategoryIds: string[];
+}) {
+  const uniqueLinkedCategoryIds = [...new Set(linkedFinanceCategoryIds)];
+
+  if (uniqueLinkedCategoryIds.length === 1) {
+    return uniqueLinkedCategoryIds[0] ?? '';
+  }
+
+  if (uniqueLinkedCategoryIds.length > 1) {
+    return '';
+  }
+
+  return defaultCategoryId || '';
+}