@tuturuuu/ui 0.5.0 → 0.6.0

package/src/components/ui/finance/shared/use-finance-balance-mode.ts

@@ -0,0 +1,72 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+const BALANCE_MODE_COOKIE_NAME = 'finance-balance-mode';
+const BALANCE_MODE_CHANGE_EVENT = 'finance-balance-mode-change';
+
+export type FinanceBalanceMode = 'audited' | 'ledger';
+
+const isBalanceMode = (value: string | null): value is FinanceBalanceMode =>
+  value === 'audited' || value === 'ledger';
+
+const getCookie = (name: string): string | null => {
+  if (typeof document === 'undefined') return null;
+  const nameEQ = `${name}=`;
+  const cookies = document.cookie.split(';');
+  for (let i = 0; i < cookies.length; i += 1) {
+    let cookie = cookies[i];
+    if (!cookie) continue;
+    while (cookie.charAt(0) === ' ') cookie = cookie.substring(1);
+    if (cookie.indexOf(nameEQ) === 0) {
+      return cookie.substring(nameEQ.length);
+    }
+  }
+  return null;
+};
+
+const setCookie = (name: string, value: string, days = 365) => {
+  const expires = new Date();
+  expires.setTime(expires.getTime() + days * 24 * 60 * 60 * 1000);
+  // biome-ignore lint/suspicious/noDocumentCookie: Used for finance balance mode persistence.
+  document.cookie = `${name}=${value};expires=${expires.toUTCString()};path=/;SameSite=Lax`;
+};
+
+export function useFinanceBalanceMode() {
+  const [mode, setModeState] = useState<FinanceBalanceMode>('ledger');
+
+  useEffect(() => {
+    const saved = getCookie(BALANCE_MODE_COOKIE_NAME);
+    if (isBalanceMode(saved)) {
+      setModeState(saved);
+    }
+
+    const handleBalanceModeChange = () => {
+      const nextValue = getCookie(BALANCE_MODE_COOKIE_NAME);
+      if (isBalanceMode(nextValue)) {
+        setModeState(nextValue);
+      }
+    };
+
+    window.addEventListener(BALANCE_MODE_CHANGE_EVENT, handleBalanceModeChange);
+
+    return () => {
+      window.removeEventListener(
+        BALANCE_MODE_CHANGE_EVENT,
+        handleBalanceModeChange
+      );
+    };
+  }, []);
+
+  const setMode = useCallback((nextMode: FinanceBalanceMode) => {
+    setModeState(nextMode);
+    setCookie(BALANCE_MODE_COOKIE_NAME, nextMode);
+    window.dispatchEvent(new Event(BALANCE_MODE_CHANGE_EVENT));
+  }, []);
+
+  return {
+    isAuditedMode: mode === 'audited',
+    mode,
+    setMode,
+  };
+}

package/src/components/ui/finance/shared/wallet-balance-mode.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getWalletBalanceTone,
+  resolveWalletBalanceForMode,
+} from './wallet-balance-mode';
+
+describe('wallet balance mode resolver', () => {
+  it('uses ledger balance in ledger mode', () => {
+    expect(
+      resolveWalletBalanceForMode(
+        {
+          audit_balance: 150,
+          audit_status: 'unresolved',
+          balance: 100,
+        },
+        'ledger'
+      )
+    ).toMatchObject({
+      contextBalance: 150,
+      displayBalance: 100,
+      hasAuditedBalance: true,
+      usesAuditedBalance: false,
+    });
+  });
+
+  it('uses audited balance in audited mode when a checkpoint exists', () => {
+    expect(
+      resolveWalletBalanceForMode(
+        {
+          audit_balance: -25,
+          audit_status: 'unresolved',
+          balance: 100,
+        },
+        'audited'
+      )
+    ).toMatchObject({
+      contextBalance: 100,
+      displayBalance: -25,
+      hasAuditedBalance: true,
+      usesAuditedBalance: true,
+    });
+  });
+
+  it('falls back to ledger balance in audited mode without a checkpoint', () => {
+    expect(
+      resolveWalletBalanceForMode(
+        {
+          audit_status: 'no_checkpoint',
+          balance: 100,
+        },
+        'audited'
+      )
+    ).toMatchObject({
+      contextBalance: null,
+      displayBalance: 100,
+      hasAuditedBalance: false,
+      usesAuditedBalance: false,
+    });
+  });
+
+  it('derives tone from the effective balance', () => {
+    expect(getWalletBalanceTone(10)).toBe('positive');
+    expect(getWalletBalanceTone(-10)).toBe('negative');
+    expect(getWalletBalanceTone(0)).toBe('neutral');
+  });
+});

package/src/components/ui/finance/shared/wallet-balance-mode.ts

@@ -0,0 +1,42 @@
+import type { FinanceBalanceMode } from './use-finance-balance-mode';
+
+type WalletBalanceInput = {
+  audit_balance?: number | null;
+  audit_status?: 'clean' | 'no_checkpoint' | 'unresolved' | null;
+  audit_variance?: number | null;
+  balance?: number | null;
+};
+
+function toFiniteNumber(value: number | null | undefined) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export function resolveWalletBalanceForMode(
+  wallet: WalletBalanceInput,
+  mode: FinanceBalanceMode
+) {
+  const ledgerBalance = toFiniteNumber(wallet.balance) ?? 0;
+  const auditedBalance = toFiniteNumber(wallet.audit_balance);
+  const hasAuditedBalance = auditedBalance !== null;
+  const usesAuditedBalance = mode === 'audited' && hasAuditedBalance;
+  const displayBalance = usesAuditedBalance ? auditedBalance : ledgerBalance;
+  const contextBalance = usesAuditedBalance ? ledgerBalance : auditedBalance;
+
+  return {
+    auditedBalance,
+    auditStatus: wallet.audit_status ?? null,
+    auditVariance: toFiniteNumber(wallet.audit_variance),
+    contextBalance,
+    displayBalance,
+    hasAuditedBalance,
+    isAuditedMode: mode === 'audited',
+    ledgerBalance,
+    usesAuditedBalance,
+  };
+}
+
+export function getWalletBalanceTone(balance: number) {
+  if (balance > 0) return 'positive';
+  if (balance < 0) return 'negative';
+  return 'neutral';
+}

package/src/components/ui/finance/transactions/form-types.ts

@@ -23,6 +23,26 @@ export type TransactionCategory = DbTransactionCategory;
 export type Wallet = DbWallet;
 export type TagDraft = Pick<DbTag, 'name'> & Partial<Pick<DbTag, 'color'>>;
 
+export type TransactionFormInitialMode = 'transaction' | 'transfer';
+
+export interface TransactionFormInitialTransaction {
+  amount?: number;
+  category_id?: string;
+  categoryKind?: 'expense' | 'income';
+  description?: string;
+  origin_wallet_id?: string;
+  taken_at?: Date;
+}
+
+export interface TransactionFormInitialTransfer {
+  amount?: number;
+  description?: string;
+  destination_amount?: number;
+  destination_wallet_id?: string;
+  origin_wallet_id?: string;
+  taken_at?: Date;
+}
+
 export interface TransactionFormProps {
   wsId: string;
   data?: Partial<Transaction>;
@@ -33,6 +53,9 @@ export interface TransactionFormProps {
   canUpdateConfidentialTransactions?: boolean;
   canChangeFinanceWallets?: boolean;
   canSetFinanceWalletsOnCreate?: boolean;
+  initialMode?: TransactionFormInitialMode;
+  initialTransaction?: TransactionFormInitialTransaction;
+  initialTransfer?: TransactionFormInitialTransfer;
   permissionRequestUser?: FinancePermissionRequestUser | null;
 }
 

package/src/components/ui/finance/transactions/form.tsx

@@ -73,6 +73,9 @@ export function TransactionForm({
   canUpdateConfidentialTransactions,
   canChangeFinanceWallets = true,
   canSetFinanceWalletsOnCreate = true,
+  initialMode = 'transaction',
+  initialTransaction,
+  initialTransfer,
   permissionRequestUser,
 }: TransactionFormProps) {
   const t = useTranslations();
@@ -83,7 +86,8 @@ export function TransactionForm({
   const [attachments, setAttachments] = useState<TransactionAttachmentDraft[]>(
     []
   );
-  const [isTransfer, setIsTransfer] = useState(!!data?.transfer);
+  const initialIsTransfer = initialMode === 'transfer' || !!data?.transfer;
+  const [isTransfer, setIsTransfer] = useState(initialIsTransfer);
   // Start in override mode when editing an existing transfer (preserve stored amounts).
   // Start in auto mode for new transfers so the exchange rate pre-fills destination.
   const [isDestinationOverridden, setIsDestinationOverridden] = useState(
@@ -144,18 +148,39 @@ export function TransactionForm({
     resolver: zodResolver(TransactionFormSchema),
     defaultValues: {
       id: data?.id,
-      description: data?.description || '',
-      amount: data?.amount ? Math.abs(data.amount) : undefined,
-      origin_wallet_id: data?.wallet_id || '',
-      destination_wallet_id: data?.transfer?.linked_wallet_id || '',
+      description:
+        data?.description ||
+        (initialIsTransfer
+          ? initialTransfer?.description
+          : initialTransaction?.description) ||
+        '',
+      amount: data?.amount
+        ? Math.abs(data.amount)
+        : initialIsTransfer
+          ? initialTransfer?.amount
+          : initialTransaction?.amount,
+      origin_wallet_id:
+        data?.wallet_id ||
+        (initialIsTransfer
+          ? initialTransfer?.origin_wallet_id
+          : initialTransaction?.origin_wallet_id) ||
+        '',
+      destination_wallet_id:
+        data?.transfer?.linked_wallet_id ||
+        initialTransfer?.destination_wallet_id ||
+        '',
       destination_amount: data?.transfer?.linked_amount
         ? Math.abs(data.transfer.linked_amount)
-        : undefined,
-      category_id: data?.category_id || '',
-      taken_at: data?.taken_at ? new Date(data.taken_at) : new Date(),
+        : initialTransfer?.destination_amount,
+      category_id: data?.category_id || initialTransaction?.category_id || '',
+      taken_at: data?.taken_at
+        ? new Date(data.taken_at)
+        : initialIsTransfer
+          ? (initialTransfer?.taken_at ?? new Date())
+          : (initialTransaction?.taken_at ?? new Date()),
       report_opt_in: data?.report_opt_in ?? true,
       tag_ids: [] as string[],
-      is_transfer: !!data?.transfer,
+      is_transfer: initialIsTransfer,
       is_amount_confidential:
         (data as Record<string, unknown>)?.is_amount_confidential === true,
       is_description_confidential:
@@ -189,7 +214,12 @@ export function TransactionForm({
     const isUserEdited =
       originWalletState.isDirty || originWalletState.isTouched;
     const currentWalletId = form.getValues('origin_wallet_id');
-    const contextualWalletId = data?.wallet_id || '';
+    const contextualWalletId =
+      data?.wallet_id ||
+      (initialIsTransfer
+        ? initialTransfer?.origin_wallet_id
+        : initialTransaction?.origin_wallet_id) ||
+      '';
 
     if (data?.id || isUserEdited) return;
     if (!wallets || wallets.length === 0) return;
@@ -241,6 +271,9 @@ export function TransactionForm({
     data?.wallet_id,
     defaultWalletId,
     form,
+    initialIsTransfer,
+    initialTransaction?.origin_wallet_id,
+    initialTransfer?.origin_wallet_id,
     isLastSelectionsInitialized,
     isLoadingRememberLastSelections,
     lastSelections.walletId,
@@ -253,7 +286,22 @@ export function TransactionForm({
     const categoryState = form.getFieldState('category_id');
     const isUserEdited = categoryState.isDirty || categoryState.isTouched;
     const currentCategoryId = form.getValues('category_id');
-    const contextualCategoryId = data?.category_id || '';
+    const contextualCategoryId =
+      data?.category_id || initialTransaction?.category_id || '';
+    const categoryKind = initialTransaction?.categoryKind;
+    const matchesCategoryKind = (category: { is_expense?: boolean | null }) => {
+      if (!categoryKind) return true;
+      return categoryKind === 'income'
+        ? category.is_expense === false
+        : category.is_expense !== false;
+    };
+    const hasSelectableCategory = (categoryId?: string | null) =>
+      !!categoryId &&
+      (categories ?? []).some(
+        (category) =>
+          category.id === categoryId &&
+          (!categoryKind || matchesCategoryKind(category))
+      );
 
     if (data?.id || isUserEdited) return;
     if (!categories || categories.length === 0) return;
@@ -263,24 +311,33 @@ export function TransactionForm({
     const rememberedCategoryId =
       rememberLastSelections &&
       lastSelections.categoryId &&
-      categories.some((category) => category.id === lastSelections.categoryId)
+      hasSelectableCategory(lastSelections.categoryId)
         ? lastSelections.categoryId
         : '';
+    const contextualCategorySelection = hasSelectableCategory(
+      contextualCategoryId
+    )
+      ? contextualCategoryId
+      : '';
+    const defaultCategorySelection = hasSelectableCategory(defaultCategoryId)
+      ? defaultCategoryId
+      : '';
+    const intentCategorySelection =
+      categoryKind && categories.find(matchesCategoryKind)?.id
+        ? categories.find(matchesCategoryKind)?.id
+        : '';
     const nextCategorySelection =
       rememberedCategoryId ||
-      (contextualCategoryId &&
-      categories.some((category) => category.id === contextualCategoryId)
-        ? contextualCategoryId
-        : '') ||
-      (defaultCategoryId &&
-      categories.some((category) => category.id === defaultCategoryId)
-        ? defaultCategoryId
-        : '');
+      contextualCategorySelection ||
+      defaultCategorySelection ||
+      intentCategorySelection;
     const sourceLabel = rememberedCategoryId
       ? t('transaction-data-table.prefill_source_last_used')
-      : contextualCategoryId && nextCategorySelection === contextualCategoryId
+      : contextualCategorySelection &&
+          nextCategorySelection === contextualCategorySelection
         ? t('transaction-data-table.prefill_source_current_context')
-        : defaultCategoryId && nextCategorySelection === defaultCategoryId
+        : defaultCategorySelection &&
+            nextCategorySelection === defaultCategorySelection
           ? t('transaction-data-table.prefill_source_workspace_default')
           : '';
 
@@ -304,6 +361,8 @@ export function TransactionForm({
     data?.id,
     defaultCategoryId,
     form,
+    initialTransaction?.categoryKind,
+    initialTransaction?.category_id,
     isLastSelectionsInitialized,
     isLoadingRememberLastSelections,
     lastSelections.categoryId,

package/src/components/ui/finance/transactions/wallet-filter.tsx

@@ -20,10 +20,12 @@ import { getCurrencyLocale } from '@tuturuuu/utils/currencies';
 import { cn } from '@tuturuuu/utils/format';
 import { useTranslations } from 'next-intl';
 import { useState } from 'react';
+import { useFinanceBalanceMode } from '../shared/use-finance-balance-mode';
 import {
   FINANCE_HIDDEN_AMOUNT,
   useFinanceConfidentialVisibility,
 } from '../shared/use-finance-confidential-visibility';
+import { resolveWalletBalanceForMode } from '../shared/wallet-balance-mode';
 
 interface WalletFilterProps {
   wsId: string;
@@ -45,9 +47,11 @@ export function WalletFilter({
   className,
 }: WalletFilterProps) {
   const t = useTranslations();
+  const checkpointT = useTranslations('wallet-checkpoints');
   const [isOpen, setIsOpen] = useState(false);
   const { isConfidential: areNumbersHidden } =
     useFinanceConfidentialVisibility();
+  const { isAuditedMode } = useFinanceBalanceMode();
 
   const hasActiveFilters = selectedWalletIds.length > 0;
 
@@ -135,6 +139,14 @@ export function WalletFilter({
                     })
                     .map((wallet) => {
                       const isSelected = selectedWalletIds.includes(wallet.id);
+                      const { displayBalance, usesAuditedBalance } =
+                        resolveWalletBalanceForMode(
+                          wallet,
+                          isAuditedMode ? 'audited' : 'ledger'
+                        );
+                      const balanceLabel = usesAuditedBalance
+                        ? checkpointT('audited')
+                        : checkpointT('ledger');
 
                       return (
                         <CommandItem
@@ -161,7 +173,7 @@ export function WalletFilter({
                               <span className="text-muted-foreground text-xs">
                                 {areNumbersHidden
                                   ? FINANCE_HIDDEN_AMOUNT
-                                  : Intl.NumberFormat(
+                                  : `${balanceLabel}: ${Intl.NumberFormat(
                                       getCurrencyLocale(
                                         wallet.currency || 'USD'
                                       ),
@@ -171,7 +183,14 @@ export function WalletFilter({
                                         minimumFractionDigits: 0,
                                         maximumFractionDigits: 0,
                                       }
-                                    ).format(wallet.balance || 0)}
+                                    ).format(displayBalance)}`}
+                                {!areNumbersHidden &&
+                                  isAuditedMode &&
+                                  wallet.audit_status === 'no_checkpoint' && (
+                                    <span className="ml-1">
+                                      {checkpointT('no_checkpoint_short')}
+                                    </span>
+                                  )}
                               </span>
                             </div>
                           </div>

package/src/components/ui/finance/wallets/checkpoints/wallet-checkpoint-adjustment-dialog.tsx

@@ -2,9 +2,10 @@
 
 import { useMutation, useQuery } from '@tanstack/react-query';
 import {
-  createTransaction,
+  createWalletCheckpointReconciliation,
   listTransactionCategories,
 } from '@tuturuuu/internal-api/finance';
+import { FINANCE_DEFAULT_RECONCILIATION_CATEGORY_CONFIG_ID } from '@tuturuuu/internal-api/workspace-configs';
 import { Button } from '@tuturuuu/ui/button';
 import {
   Dialog,
@@ -14,6 +15,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@tuturuuu/ui/dialog';
+import { useWorkspaceConfig } from '@tuturuuu/ui/hooks/use-workspace-config';
 import { Input } from '@tuturuuu/ui/input';
 import { Label } from '@tuturuuu/ui/label';
 import {
@@ -27,12 +29,13 @@ import { toast } from '@tuturuuu/ui/sonner';
 import { Textarea } from '@tuturuuu/ui/textarea';
 import { formatCurrency } from '@tuturuuu/utils/format';
 import { useTranslations } from 'next-intl';
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
 const NO_CATEGORY = 'none';
 
 export function WalletCheckpointAdjustmentDialog({
   checkedAt,
+  checkpointId,
   currency,
   onCreated,
   onOpenChange,
@@ -43,6 +46,7 @@ export function WalletCheckpointAdjustmentDialog({
   wsId,
 }: {
   checkedAt: string;
+  checkpointId: string;
   currency: string;
   onCreated: () => void;
   onOpenChange: (open: boolean) => void;
@@ -55,21 +59,59 @@ export function WalletCheckpointAdjustmentDialog({
   const t = useTranslations('wallet-checkpoints');
   const [categoryId, setCategoryId] = useState(NO_CATEGORY);
   const [description, setDescription] = useState(
-    t('adjustment_description', {
+    t('reconciliation_description', {
       date: new Date(checkedAt).toLocaleDateString(),
       wallet: walletName,
     })
   );
-  const [takenAt, setTakenAt] = useState(() => {
-    const date = new Date(checkedAt);
-    const local = new Date(date.getTime() - date.getTimezoneOffset() * 60_000);
-    return local.toISOString().slice(0, 16);
-  });
+  const [categoryInitialized, setCategoryInitialized] = useState(false);
   const categoriesQuery = useQuery({
     queryKey: ['transaction-categories', wsId],
     queryFn: () => listTransactionCategories(wsId),
     enabled: open,
   });
+  const {
+    data: defaultReconciliationCategoryId,
+    isLoading: isLoadingDefaultReconciliationCategory,
+  } = useWorkspaceConfig<string>(
+    wsId,
+    FINANCE_DEFAULT_RECONCILIATION_CATEGORY_CONFIG_ID,
+    ''
+  );
+
+  useEffect(() => {
+    if (!open) {
+      setCategoryId(NO_CATEGORY);
+      setCategoryInitialized(false);
+      return;
+    }
+
+    if (
+      categoryInitialized ||
+      categoriesQuery.isLoading ||
+      isLoadingDefaultReconciliationCategory
+    ) {
+      return;
+    }
+
+    const defaultCategoryExists = (categoriesQuery.data ?? []).some(
+      (category) => category.id === defaultReconciliationCategoryId
+    );
+
+    setCategoryId(
+      defaultReconciliationCategoryId && defaultCategoryExists
+        ? defaultReconciliationCategoryId
+        : NO_CATEGORY
+    );
+    setCategoryInitialized(true);
+  }, [
+    categoriesQuery.data,
+    categoriesQuery.isLoading,
+    categoryInitialized,
+    defaultReconciliationCategoryId,
+    isLoadingDefaultReconciliationCategory,
+    open,
+  ]);
   const amountText = useMemo(
     () =>
       formatCurrency(variance, currency, undefined, {
@@ -78,24 +120,30 @@ export function WalletCheckpointAdjustmentDialog({
       }),
     [currency, variance]
   );
+  const checkedAtText = useMemo(
+    () =>
+      new Intl.DateTimeFormat(undefined, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+      }).format(new Date(checkedAt)),
+    [checkedAt]
+  );
   const mutation = useMutation({
     mutationFn: () =>
-      createTransaction(wsId, {
-        amount: variance,
+      createWalletCheckpointReconciliation(wsId, walletId, checkpointId, {
         category_id: categoryId === NO_CATEGORY ? undefined : categoryId,
         description,
-        origin_wallet_id: walletId,
-        report_opt_in: false,
-        taken_at: new Date(takenAt).toISOString(),
       }),
-    onSuccess: () => {
-      toast.success(t('adjustment_created'));
+    onSuccess: (result) => {
+      toast.success(
+        result.created ? t('reconciliation_created') : t('reconciliation_clean')
+      );
       onCreated();
       onOpenChange(false);
     },
     onError: (error) => {
       toast.error(
-        error instanceof Error ? error.message : t('adjustment_create_error')
+        error instanceof Error ? error.message : t('reconciliation_error')
       );
     },
   });
@@ -104,23 +152,22 @@ export function WalletCheckpointAdjustmentDialog({
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent>
         <DialogHeader>
-          <DialogTitle>{t('create_adjustment')}</DialogTitle>
+          <DialogTitle>{t('create_reconciliation_transaction')}</DialogTitle>
           <DialogDescription>
-            {t('create_adjustment_description')}
+            {t('create_reconciliation_description')}
           </DialogDescription>
         </DialogHeader>
         <div className="grid gap-4 py-2">
           <div className="grid gap-2">
-            <Label>{t('adjustment_amount')}</Label>
+            <Label>{t('offset_amount_preview')}</Label>
             <Input value={amountText} readOnly />
           </div>
           <div className="grid gap-2">
-            <Label htmlFor="checkpoint-adjustment-date">{t('date')}</Label>
+            <Label htmlFor="checkpoint-reconciliation-date">{t('date')}</Label>
             <Input
-              id="checkpoint-adjustment-date"
-              type="datetime-local"
-              value={takenAt}
-              onChange={(event) => setTakenAt(event.target.value)}
+              id="checkpoint-reconciliation-date"
+              value={checkedAtText}
+              readOnly
             />
           </div>
           <div className="grid gap-2">
@@ -160,10 +207,10 @@ export function WalletCheckpointAdjustmentDialog({
             {t('cancel')}
           </Button>
           <Button
-            disabled={mutation.isPending || variance === 0}
+            disabled={mutation.isPending || !categoryInitialized}
             onClick={() => mutation.mutate()}
           >
-            {mutation.isPending ? t('creating') : t('create_adjustment')}
+            {mutation.isPending ? t('creating') : t('reconcile')}
           </Button>
         </DialogFooter>
       </DialogContent>