@tuturuuu/ui 0.10.0 → 0.11.0

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

@@ -37,6 +37,7 @@ import {
 } from './components/invoice-products-permission-warning';
 import { SubscriptionAttendanceSummary } from './components/subscription-attendance-summary';
 import { SubscriptionGroupSelector } from './components/subscription-group-selector';
+import { SubscriptionPrepaidControls } from './components/subscription-prepaid-controls';
 import { CreatePromotionDialog } from './create-promotion-dialog';
 import type { AvailablePromotion } from './hooks';
 import {
@@ -63,15 +64,19 @@ import { formatInvoiceRecalculationDescription } from './invoice-visibility-form
 import { ProductSelection } from './product-selection';
 import type { SelectedProductItem } from './types';
 import {
+  formatCoverageRangeLabel,
+  formatMonthLabel,
   formatMonthValue,
   getAvailableMonths,
-  getBillableAttendanceRecords,
-  getBillableSessionsForGroups,
+  getBillableAttendanceRecordsInRange,
+  getBillableSessionsForGroupsInRange,
+  getCoverageValidUntilMonthValue,
   getGroupsDateRange,
   getLinkedFinanceCategorySelection,
   getMonthStartDate,
   getSubscriptionAttendanceDisplayData,
-  isSubscriptionMonthPaidForGroup,
+  isSubscriptionRangeFullyPaidForGroups,
+  PREPAID_MONTH_OPTION_HORIZON,
 } from './utils';
 
 interface Props {
@@ -131,6 +136,7 @@ export function SubscriptionInvoice({
     defaultValue: formatMonthValue(new Date()),
     shallow: true,
   });
+  const [prepaidMonthCount, setPrepaidMonthCount] = useState(1);
 
   const [customerSearch, setCustomerSearch] = useState('');
   const [debouncedCustomerSearch] = useDebounce(customerSearch, 300);
@@ -279,7 +285,8 @@ export function SubscriptionInvoice({
         selectedGroupIds,
         [],
         locale,
-        selectedMonth
+        selectedMonth,
+        PREPAID_MONTH_OPTION_HORIZON
       ),
     [locale, selectedGroupIds, selectedMonth, userGroups]
   );
@@ -324,7 +331,8 @@ export function SubscriptionInvoice({
     wsId,
     selectedUserId,
     selectedGroupIds,
-    effectiveSelectedMonth
+    effectiveSelectedMonth,
+    prepaidMonthCount
   );
 
   const userAttendance = subscriptionInvoiceContext?.attendance ?? [];
@@ -335,35 +343,62 @@ export function SubscriptionInvoice({
       ? subscriptionInvoiceContextError
       : null;
 
-  const isSelectedMonthPaid = useMemo(() => {
+  const coverageRangeLabel = useMemo(
+    () =>
+      formatCoverageRangeLabel({
+        locale,
+        prepaidMonthCount,
+        selectedMonth: effectiveSelectedMonth,
+      }),
+    [effectiveSelectedMonth, locale, prepaidMonthCount]
+  );
+  const coverageValidUntilLabel = useMemo(
+    () =>
+      formatMonthLabel(
+        getCoverageValidUntilMonthValue(
+          effectiveSelectedMonth,
+          prepaidMonthCount
+        ),
+        locale
+      ),
+    [effectiveSelectedMonth, locale, prepaidMonthCount]
+  );
+
+  const isSelectedRangePaid = useMemo(() => {
     if (selectedGroupIds.length === 0 || !effectiveSelectedMonth) return false;
 
     const selectedMonthStart = getMonthStartDate(effectiveSelectedMonth);
 
-    // A month is considered paid ONLY if ALL selected groups have paid for it.
-    // If ANY selected group has not paid, we allow creating an invoice.
+    // A range is paid only if all selected groups have coverage for every month.
+    // If any selected group has an unpaid month, invoice creation stays enabled.
     if (Number.isNaN(selectedMonthStart.getTime())) return false;
 
-    return selectedGroupIds.every((groupId) =>
-      isSubscriptionMonthPaidForGroup(
-        groupId,
-        effectiveSelectedMonth,
-        latestSubscriptionInvoices
-      )
+    return isSubscriptionRangeFullyPaidForGroups(
+      selectedGroupIds,
+      effectiveSelectedMonth,
+      prepaidMonthCount,
+      latestSubscriptionInvoices
     );
-  }, [effectiveSelectedMonth, latestSubscriptionInvoices, selectedGroupIds]);
+  }, [
+    effectiveSelectedMonth,
+    latestSubscriptionInvoices,
+    prepaidMonthCount,
+    selectedGroupIds,
+  ]);
 
   const billableAttendance = useMemo(
     () =>
-      getBillableAttendanceRecords(
+      getBillableAttendanceRecordsInRange(
         userAttendance,
         selectedGroupIds,
         effectiveSelectedMonth,
+        prepaidMonthCount,
         latestSubscriptionInvoices
       ),
     [
       effectiveSelectedMonth,
       latestSubscriptionInvoices,
+      prepaidMonthCount,
       selectedGroupIds,
       userAttendance,
     ]
@@ -371,15 +406,17 @@ export function SubscriptionInvoice({
 
   const billableSessions = useMemo(
     () =>
-      getBillableSessionsForGroups(
+      getBillableSessionsForGroupsInRange(
         userGroups,
         selectedGroupIds,
         effectiveSelectedMonth,
+        prepaidMonthCount,
         latestSubscriptionInvoices
       ),
     [
       effectiveSelectedMonth,
       latestSubscriptionInvoices,
+      prepaidMonthCount,
       selectedGroupIds,
       userGroups,
     ]
@@ -387,22 +424,29 @@ export function SubscriptionInvoice({
 
   const monthlyAttendance = useMemo(
     () =>
-      getBillableAttendanceRecords(
+      getBillableAttendanceRecordsInRange(
         userAttendance,
         selectedGroupIds,
-        effectiveSelectedMonth
+        effectiveSelectedMonth,
+        prepaidMonthCount
       ),
-    [effectiveSelectedMonth, selectedGroupIds, userAttendance]
+    [
+      effectiveSelectedMonth,
+      prepaidMonthCount,
+      selectedGroupIds,
+      userAttendance,
+    ]
   );
 
   const monthlySessions = useMemo(
     () =>
-      getBillableSessionsForGroups(
+      getBillableSessionsForGroupsInRange(
         userGroups,
         selectedGroupIds,
-        effectiveSelectedMonth
+        effectiveSelectedMonth,
+        prepaidMonthCount
       ),
-    [effectiveSelectedMonth, selectedGroupIds, userGroups]
+    [effectiveSelectedMonth, prepaidMonthCount, selectedGroupIds, userGroups]
   );
 
   const {
@@ -414,7 +458,7 @@ export function SubscriptionInvoice({
   } = useMemo(
     () =>
       getSubscriptionAttendanceDisplayData({
-        isSelectedMonthPaid,
+        isSelectedMonthPaid: isSelectedRangePaid,
         billableAttendance,
         billableSessions,
         monthlyAttendance,
@@ -423,7 +467,7 @@ export function SubscriptionInvoice({
     [
       billableAttendance,
       billableSessions,
-      isSelectedMonthPaid,
+      isSelectedRangePaid,
       monthlyAttendance,
       monthlySessions,
     ]
@@ -502,6 +546,7 @@ export function SubscriptionInvoice({
     userAttendance: billableAttendance,
     latestSubscriptionInvoices,
     onSelectedProductsChange: setSubscriptionSelectedProducts,
+    prepaidMonthCount,
   });
 
   useSubscriptionInvoiceContent({
@@ -513,10 +558,11 @@ export function SubscriptionInvoice({
     subscriptionSelectedProducts,
     userAttendance: billableAttendance,
     latestSubscriptionInvoices,
-    isSelectedMonthPaid,
+    isSelectedMonthPaid: isSelectedRangePaid,
     locale,
     onContentChange: setInvoiceContent,
     onNotesChange: setInvoiceNotes,
+    prepaidMonthCount,
   });
 
   const subtotal = useInvoiceSubtotal(subscriptionSelectedProducts);
@@ -582,6 +628,7 @@ export function SubscriptionInvoice({
       setSelectedCategoryId(defaultCategoryId || '');
       setSelectedGroupIds(null);
       setSelectedMonth(null);
+      setPrepaidMonthCount(1);
     }
   }, [
     selectedUserId,
@@ -629,7 +676,8 @@ export function SubscriptionInvoice({
         selectedGroupIds,
         latestSubscriptionInvoices,
         locale,
-        effectiveSelectedMonth
+        effectiveSelectedMonth,
+        PREPAID_MONTH_OPTION_HORIZON
       ),
     [
       effectiveSelectedMonth,
@@ -778,6 +826,7 @@ export function SubscriptionInvoice({
         frontend_subtotal: subtotal,
         frontend_discount_amount: discountAmount,
         frontend_total: subscriptionRoundedTotal,
+        prepaid_month_count: prepaidMonthCount,
       };
 
       const result = await createSubscriptionInvoiceWithInternalApi(wsId, {
@@ -824,6 +873,7 @@ export function SubscriptionInvoice({
         setSelectedWalletId(defaultWalletId || '');
         setSelectedCategoryId(defaultCategoryId || '');
         setSelectedGroupIds(null);
+        setPrepaidMonthCount(1);
         setCustomerSearch('');
       }
     } catch (error) {
@@ -905,7 +955,16 @@ export function SubscriptionInvoice({
           />
         )}
 
-        {selectedGroupIds.length > 0 && !isSelectedMonthPaid && !isBlocked && (
+        {selectedGroupIds.length > 0 && (
+          <SubscriptionPrepaidControls
+            coverageRangeLabel={coverageRangeLabel}
+            prepaidMonthCount={prepaidMonthCount}
+            validUntilLabel={coverageValidUntilLabel}
+            onPrepaidMonthCountChange={setPrepaidMonthCount}
+          />
+        )}
+
+        {selectedGroupIds.length > 0 && !isSelectedRangePaid && !isBlocked && (
           <>
             <ProductSelection
               products={products}
@@ -965,7 +1024,7 @@ export function SubscriptionInvoice({
               <SubscriptionAttendanceSummary
                 selectedGroupIds={selectedGroupIds}
                 selectedMonth={effectiveSelectedMonth}
-                isSelectedMonthPaid={isSelectedMonthPaid}
+                isSelectedMonthPaid={isSelectedRangePaid}
                 locale={locale}
                 navigateMonth={navigateMonth}
                 canNavigateMonth={canNavigateMonth}
@@ -979,11 +1038,13 @@ export function SubscriptionInvoice({
                 attendanceStats={attendanceStats}
                 totalSessions={totalSessions}
                 attendanceRate={attendanceRate}
+                coverageRangeLabel={coverageRangeLabel}
+                prepaidMonthCount={prepaidMonthCount}
               />
             )}
 
             {subscriptionSelectedProducts.length > 0 &&
-              !isSelectedMonthPaid && (
+              !isSelectedRangePaid && (
                 <Card>
                   <CardHeader>
                     <CardTitle>
@@ -1095,7 +1156,7 @@ export function SubscriptionInvoice({
                           !selectedWalletId ||
                           !selectedCategoryId ||
                           isCreating ||
-                          isSelectedMonthPaid
+                          isSelectedRangePaid
                         }
                       >
                         {isCreating ? (

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

@@ -1,11 +1,16 @@
 import { describe, expect, it } from 'vitest';
 import {
+  formatCoverageRangeLabel,
+  getAvailableMonths,
   getBillableAttendanceRecords,
+  getBillableQuantityMapForGroupsRange,
   getBillableSessionsForGroups,
+  getCoverageMonths,
   getLinkedFinanceCategorySelection,
   getSubscriptionAttendanceDisplayData,
   getSubscriptionCoverageInvoiceForGroup,
   isSubscriptionMonthPaidForGroup,
+  isSubscriptionRangeFullyPaidForGroups,
   type UserGroup,
 } from './utils';
 
@@ -138,6 +143,21 @@ describe('subscription invoice attendance display data', () => {
 });
 
 describe('subscription invoice coverage', () => {
+  it('builds coverage months and labels multi-month ranges', () => {
+    expect(getCoverageMonths('2026-06', 3)).toEqual([
+      '2026-06',
+      '2026-07',
+      '2026-08',
+    ]);
+    expect(
+      formatCoverageRangeLabel({
+        locale: 'en-US',
+        prepaidMonthCount: 3,
+        selectedMonth: '2026-06',
+      })
+    ).toBe('June 2026 - August 2026');
+  });
+
   it('treats valid_until as the exclusive first unpaid month', () => {
     const latestInvoices = [{ group_id: groupId, valid_until: '2026-06-01' }];
 
@@ -183,6 +203,68 @@ describe('subscription invoice coverage', () => {
       isSubscriptionMonthPaidForGroup(groupId, '2026-06', latestInvoices)
     ).toBe(true);
   });
+
+  it('requires every coverage month to be paid before marking a range paid', () => {
+    expect(
+      isSubscriptionRangeFullyPaidForGroups([groupId], '2026-06', 3, [
+        { group_id: groupId, valid_until: '2026-08-01' },
+      ])
+    ).toBe(false);
+    expect(
+      isSubscriptionRangeFullyPaidForGroups([groupId], '2026-06', 3, [
+        { group_id: groupId, valid_until: '2026-09-01' },
+      ])
+    ).toBe(true);
+  });
+
+  it('generates prepaid future month options capped by group ending dates', () => {
+    const groups = [
+      {
+        workspace_user_groups: {
+          id: groupId,
+          name: 'Math 7',
+          sessions: ['2026-06-05', '2026-07-05', '2026-08-05'],
+          starting_date: '2026-06-01',
+          ending_date: '2026-08-31',
+        } as NonNullable<UserGroup['workspace_user_groups']>,
+      },
+    ] satisfies UserGroup[];
+
+    expect(
+      getAvailableMonths(groups, [groupId], [], 'en-US', '2026-06', 12).map(
+        (month) => month.value
+      )
+    ).toEqual(['2026-06', '2026-07', '2026-08']);
+  });
+
+  it('skips paid months and uses scheduled sessions for future prepaid quantities', () => {
+    const groups = [
+      {
+        workspace_user_groups: {
+          id: groupId,
+          name: 'Math 7',
+          sessions: ['2026-06-05', '2026-07-05', '2026-08-05'],
+          starting_date: '2026-06-01',
+          ending_date: null,
+        } as NonNullable<UserGroup['workspace_user_groups']>,
+      },
+    ] satisfies UserGroup[];
+
+    expect(
+      getBillableQuantityMapForGroupsRange({
+        groupIds: [groupId],
+        latestInvoices: [{ group_id: groupId, valid_until: '2026-07-01' }],
+        now: new Date(2026, 5, 15),
+        prepaidMonthCount: 3,
+        selectedMonth: '2026-06',
+        useAttendanceBased: true,
+        userAttendance: [
+          { group_id: groupId, date: '2026-06-05', status: 'PRESENT' },
+        ],
+        userGroups: groups,
+      })
+    ).toEqual({ [groupId]: 2 });
+  });
 });
 
 describe('linked finance category selection', () => {