@spaceinvoices/react-ui 0.1.1

package/src/components/customers/customers.hooks.test.ts

@@ -0,0 +1,348 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { renderHook, waitFor } from "@testing-library/react";
+import { createMockSDK, createTestSetup, resetSDKMocks } from "../../../test/test-utils";
+import { CUSTOMERS_CACHE_KEY, useCustomerSearch, useRecentCustomers } from "./customers.hooks";
+
+describe("customers.hooks", () => {
+  let sdk: ReturnType<typeof createMockSDK>;
+
+  beforeEach(() => {
+    sdk = createMockSDK();
+    resetSDKMocks(sdk);
+  });
+
+  describe("useCustomerSearch", () => {
+    test("searches customers with search term", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+      const searchTerm = "John";
+
+      sdk.customers.list.mockResolvedValueOnce({
+        data: [
+          { id: "customer-1", name: "John Doe", email: "john@example.com" },
+          { id: "customer-2", name: "John Smith", email: "johnsmith@example.com" },
+        ],
+        pagination: { total: 2 },
+      });
+
+      const { result } = renderHook(() => useCustomerSearch(entityId, searchTerm), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true);
+      });
+
+      expect(sdk.customers.list).toHaveBeenCalledWith({
+        entity_id: entityId,
+        search: searchTerm,
+        limit: 10,
+      });
+
+      expect(result.current.data?.data).toHaveLength(2);
+      expect(result.current.data?.data[0].name).toBe("John Doe");
+    });
+
+    test("does not call API when search term is empty", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+      const searchTerm = "";
+
+      renderHook(() => useCustomerSearch(entityId, searchTerm), { wrapper });
+
+      // Wait a bit to ensure no API call is made
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Should not call API when search is empty
+      expect(sdk.customers.list).not.toHaveBeenCalled();
+    });
+
+    test("is disabled when entityId is missing", () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const searchTerm = "John";
+
+      const { result } = renderHook(() => useCustomerSearch("", searchTerm), { wrapper });
+
+      // Should not make API call
+      expect(sdk.customers.list).not.toHaveBeenCalled();
+
+      // Query should be disabled
+      expect(result.current.isFetching).toBe(false);
+    });
+
+    test("is disabled when search term is empty", () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      const { result } = renderHook(() => useCustomerSearch(entityId, ""), { wrapper });
+
+      // Query should be disabled (but returns empty data immediately)
+      expect(result.current.isFetching).toBe(false);
+    });
+
+    test("limits results to 10 customers", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+      const searchTerm = "test";
+
+      sdk.customers.list.mockResolvedValueOnce({
+        data: Array.from({ length: 10 }, (_, i) => ({
+          id: `customer-${i}`,
+          name: `Test Customer ${i}`,
+          email: `test${i}@example.com`,
+        })),
+        pagination: { total: 10 },
+      });
+
+      const { result } = renderHook(() => useCustomerSearch(entityId, searchTerm), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true);
+      });
+
+      expect(sdk.customers.list).toHaveBeenCalledWith({
+        entity_id: entityId,
+        search: searchTerm,
+        limit: 10,
+      });
+    });
+
+    test("creates unique cache keys for different searches", async () => {
+      const { wrapper, queryClient } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      sdk.customers.list.mockResolvedValue({
+        data: [{ id: "customer-1", name: "Test", email: "test@example.com" }],
+        pagination: { total: 1 },
+      });
+
+      // First search
+      const { result: result1 } = renderHook(() => useCustomerSearch(entityId, "john"), { wrapper });
+
+      await waitFor(() => {
+        expect(result1.current.isSuccess).toBe(true);
+      });
+
+      // Second search with different term
+      const { result: result2 } = renderHook(() => useCustomerSearch(entityId, "jane"), { wrapper });
+
+      await waitFor(() => {
+        expect(result2.current.isSuccess).toBe(true);
+      });
+
+      // Should have made two separate API calls
+      expect(sdk.customers.list).toHaveBeenCalledTimes(2);
+
+      // Check cache has both queries
+      const cache = queryClient.getQueryCache().getAll();
+      const customerSearchQueries = cache.filter(
+        (query) => query.queryKey[0] === CUSTOMERS_CACHE_KEY && query.queryKey[1] === "search",
+      );
+
+      expect(customerSearchQueries.length).toBeGreaterThanOrEqual(2);
+    });
+
+    test("handles API errors gracefully", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+      const searchTerm = "error";
+
+      sdk.customers.list.mockRejectedValueOnce(new Error("API Error"));
+
+      const { result } = renderHook(() => useCustomerSearch(entityId, searchTerm), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true);
+      });
+
+      expect(result.current.error).toBeDefined();
+    });
+  });
+
+  describe("useRecentCustomers", () => {
+    test("fetches recent customers", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      const mockCustomers = [
+        { id: "customer-1", name: "Recent Customer 1", email: "recent1@example.com", created_at: "2024-01-15" },
+        { id: "customer-2", name: "Recent Customer 2", email: "recent2@example.com", created_at: "2024-01-14" },
+      ];
+
+      sdk.customers.list.mockResolvedValueOnce({
+        data: mockCustomers,
+        pagination: { total: 2 },
+      });
+
+      const { result } = renderHook(() => useRecentCustomers(entityId), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true);
+      });
+
+      expect(sdk.customers.list).toHaveBeenCalledWith({
+        entity_id: entityId,
+        limit: 5,
+        order_by: "-created_at",
+      });
+
+      expect(result.current.data?.data).toHaveLength(2);
+      expect(result.current.data?.data[0].name).toBe("Recent Customer 1");
+    });
+
+    test("limits results to 5 customers", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      sdk.customers.list.mockResolvedValueOnce({
+        data: Array.from({ length: 5 }, (_, i) => ({
+          id: `customer-${i}`,
+          name: `Customer ${i}`,
+          email: `customer${i}@example.com`,
+          created_at: new Date(Date.now() - i * 1000).toISOString(),
+        })),
+        pagination: { total: 5 },
+      });
+
+      const { result } = renderHook(() => useRecentCustomers(entityId), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true);
+      });
+
+      expect(sdk.customers.list).toHaveBeenCalledWith({
+        entity_id: entityId,
+        limit: 5,
+        order_by: "-created_at",
+      });
+    });
+
+    test("is disabled when entityId is missing", () => {
+      const { wrapper } = createTestSetup({ sdk });
+
+      const { result } = renderHook(() => useRecentCustomers(""), { wrapper });
+
+      // Should not make API call
+      expect(sdk.customers.list).not.toHaveBeenCalled();
+
+      // Query should be disabled
+      expect(result.current.isFetching).toBe(false);
+    });
+
+    test("sorts customers by created_at descending", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      sdk.customers.list.mockResolvedValueOnce({
+        data: [],
+        pagination: { total: 0 },
+      });
+
+      renderHook(() => useRecentCustomers(entityId), { wrapper });
+
+      await waitFor(() => {
+        expect(sdk.customers.list).toHaveBeenCalled();
+      });
+
+      // Verify order_by parameter
+      expect(sdk.customers.list).toHaveBeenCalledWith(
+        expect.objectContaining({
+          order_by: "-created_at",
+        }),
+      );
+    });
+
+    test("caches results for 5 minutes", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      sdk.customers.list.mockResolvedValue({
+        data: [{ id: "customer-1", name: "Test", email: "test@example.com", created_at: "" }],
+        pagination: { total: 1 },
+      });
+
+      const { result, rerender } = renderHook(() => useRecentCustomers(entityId), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true);
+      });
+
+      expect(sdk.customers.list).toHaveBeenCalledTimes(1);
+
+      // Rerender to trigger another fetch (but should use cache)
+      rerender();
+
+      // Wait a bit to ensure it doesn't refetch
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      // Should still only have been called once (cached)
+      expect(sdk.customers.list).toHaveBeenCalledTimes(1);
+    });
+
+    test("creates unique cache keys for different entities", async () => {
+      const { wrapper, queryClient } = createTestSetup({ sdk });
+
+      sdk.customers.list.mockResolvedValue({
+        data: [{ id: "customer-1", name: "Test", email: "test@example.com", created_at: "" }],
+        pagination: { total: 1 },
+      });
+
+      // First entity
+      const { result: result1 } = renderHook(() => useRecentCustomers("entity-1"), { wrapper });
+
+      await waitFor(() => {
+        expect(result1.current.isSuccess).toBe(true);
+      });
+
+      // Second entity
+      const { result: result2 } = renderHook(() => useRecentCustomers("entity-2"), { wrapper });
+
+      await waitFor(() => {
+        expect(result2.current.isSuccess).toBe(true);
+      });
+
+      // Should have made two separate API calls
+      expect(sdk.customers.list).toHaveBeenCalledTimes(2);
+
+      // Check cache has both queries
+      const cache = queryClient.getQueryCache().getAll();
+      const recentCustomersQueries = cache.filter(
+        (query) => query.queryKey[0] === CUSTOMERS_CACHE_KEY && query.queryKey[1] === "recent",
+      );
+
+      expect(recentCustomersQueries.length).toBeGreaterThanOrEqual(2);
+    });
+
+    test("handles API errors gracefully", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      sdk.customers.list.mockRejectedValueOnce(new Error("API Error"));
+
+      const { result } = renderHook(() => useRecentCustomers(entityId), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isError).toBe(true);
+      });
+
+      expect(result.current.error).toBeDefined();
+    });
+
+    test("handles empty results", async () => {
+      const { wrapper } = createTestSetup({ sdk });
+      const entityId = "entity-123";
+
+      sdk.customers.list.mockResolvedValueOnce({
+        data: [],
+        pagination: { total: 0 },
+      });
+
+      const { result } = renderHook(() => useRecentCustomers(entityId), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.isSuccess).toBe(true);
+      });
+
+      expect(result.current.data?.data).toEqual([]);
+      expect(result.current.data?.pagination.total).toBe(0);
+    });
+  });
+});

package/src/components/customers/customers.hooks.ts

@@ -0,0 +1,57 @@
+import type { CreateCustomerBody, Customer } from "@spaceinvoices/js-sdk";
+
+import { useQuery } from "@tanstack/react-query";
+
+import { createResourceHooks } from "@/ui/hooks/create-resource-hooks";
+import { useSDK } from "@/ui/providers/sdk-provider";
+
+// Define a constant for the customers cache key
+export const CUSTOMERS_CACHE_KEY = "customers";
+
+export const useCustomerSearch = (entityId: string, search: string) => {
+  const { sdk } = useSDK();
+
+  return useQuery({
+    // Don't include SDK in query key - it's guaranteed non-null by provider
+    // Including it breaks cache due to object reference changes
+    queryKey: [CUSTOMERS_CACHE_KEY, "search", entityId, search],
+    queryFn: async () => {
+      if (!search) return { data: [] };
+
+      const response = await sdk.customers.list({
+        entity_id: entityId,
+        search,
+        limit: 10,
+      });
+
+      return response;
+    },
+    // SDK is always available, only check search and entityId
+    enabled: Boolean(entityId && search),
+  });
+};
+
+export const useRecentCustomers = (entityId: string) => {
+  const { sdk } = useSDK();
+
+  return useQuery({
+    queryKey: [CUSTOMERS_CACHE_KEY, "recent", entityId],
+    queryFn: async () => {
+      const response = await sdk.customers.list({
+        entity_id: entityId,
+        limit: 5,
+        order_by: "-created_at", // Sort by most recently created
+      });
+
+      return response;
+    },
+    enabled: Boolean(entityId),
+    staleTime: 1000 * 60 * 5, // Cache for 5 minutes
+  });
+};
+
+export const {
+  useCreateResource: useCreateCustomer,
+  useUpdateResource: useUpdateCustomer,
+  useDeleteResource: useDeleteCustomer,
+} = createResourceHooks<Customer, CreateCustomerBody>("customers", CUSTOMERS_CACHE_KEY);

package/src/components/customers/index.ts

@@ -0,0 +1,5 @@
+export { default as CreateCustomerForm } from "./create-customer-form/create-customer-form";
+export { CustomerAutocomplete } from "./customer-autocomplete";
+export { CustomerCombobox } from "./customer-combobox";
+export * from "./customer-list-table";
+export * from "./customers.hooks";

package/src/components/dashboard/chart-empty-state.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+type ChartEmptyStateProps = {
+  /** The chart to render (will be muted) */
+  children: ReactNode;
+  /** Label to show over the chart */
+  label?: string;
+  /** Height of the container */
+  className?: string;
+};
+
+/**
+ * Empty state wrapper that shows a muted chart with an overlay label
+ */
+export function ChartEmptyState({ children, label = "No data", className }: ChartEmptyStateProps) {
+  return (
+    <div className={`relative ${className || ""}`}>
+      {/* Muted chart */}
+      <div className="pointer-events-none opacity-30 grayscale">{children}</div>
+
+      {/* Overlay label */}
+      <div className="absolute inset-0 flex items-center justify-center">
+        <div className="rounded-md bg-muted/80 px-3 py-1.5 text-muted-foreground text-sm">{label}</div>
+      </div>
+    </div>
+  );
+}

package/src/components/dashboard/collection-rate-card/collection-rate-card.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { Card, CardContent, CardHeader, CardTitle } from "@/ui/components/ui/card";
+import { createTranslation } from "@/ui/lib/translation";
+import { LoadingCard } from "../loading-card";
+import sl from "./locales/sl";
+import { useCollectionRateData } from "./use-collection-rate";
+
+const translations = { sl } as const;
+
+type BaseProps = {
+  locale?: string;
+  t?: (key: string) => string;
+  namespace?: string;
+};
+
+type DataProps = BaseProps & {
+  collectionRate: number;
+  totalCollected: number;
+  totalInvoiced: number;
+  currency: string;
+  entityId?: never;
+};
+
+type TurnkeyProps = BaseProps & {
+  entityId: string;
+  collectionRate?: never;
+  totalCollected?: never;
+  totalInvoiced?: never;
+  currency?: never;
+};
+
+export type CollectionRateCardProps = DataProps | TurnkeyProps;
+
+export function CollectionRateCard(props: CollectionRateCardProps) {
+  const { locale, t: externalT, namespace } = props;
+  const t = createTranslation({ t: externalT, namespace, locale, translations });
+
+  // Turnkey mode - fetch own data
+  const hookResult = useCollectionRateData("entityId" in props ? props.entityId : undefined);
+
+  // Determine data source
+  const collectionRate = "entityId" in props ? hookResult.data.collectionRate : props.collectionRate;
+  const totalCollected = "entityId" in props ? hookResult.data.totalCollected : props.totalCollected;
+  const totalInvoiced = "entityId" in props ? hookResult.data.totalInvoiced : props.totalInvoiced;
+  const currency = "entityId" in props ? hookResult.data.currency : props.currency;
+  const isLoading = "entityId" in props ? hookResult.isLoading : false;
+
+  if (isLoading) {
+    return <LoadingCard />;
+  }
+
+  const formatCurrency = (value: number) =>
+    new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency,
+      minimumFractionDigits: 0,
+      maximumFractionDigits: 0,
+    }).format(value);
+
+  const getVariantColor = (rate: number) => {
+    if (rate >= 80) return "text-green-600 dark:text-green-400";
+    if (rate >= 50) return "text-yellow-600 dark:text-yellow-400";
+    return "text-red-600 dark:text-red-400";
+  };
+
+  return (
+    <Card>
+      <CardHeader className="pb-2">
+        <CardTitle className="font-medium text-muted-foreground text-sm">{t("Collection Rate")}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <div className={`font-bold text-2xl ${getVariantColor(collectionRate)}`}>{collectionRate.toFixed(1)}%</div>
+        <p className="mt-1 text-muted-foreground text-xs">
+          {formatCurrency(totalCollected)} / {formatCurrency(totalInvoiced)}
+        </p>
+      </CardContent>
+    </Card>
+  );
+}

package/src/components/dashboard/collection-rate-card/index.ts

@@ -0,0 +1,4 @@
+export type { CollectionRateCardProps } from "./collection-rate-card";
+export { CollectionRateCard } from "./collection-rate-card";
+export type { CollectionRateData } from "./use-collection-rate";
+export { COLLECTION_RATE_CACHE_KEY, useCollectionRateData } from "./use-collection-rate";

package/src/components/dashboard/collection-rate-card/locales/sl.ts

@@ -0,0 +1,3 @@
+export default {
+  "Collection Rate": "Stopnja izterjave",
+} as const;

package/src/components/dashboard/collection-rate-card/use-collection-rate.ts

@@ -0,0 +1,74 @@
+/**
+ * Collection rate hook using the entity stats API.
+ * Server-side aggregation for accurate totals.
+ */
+import { useQueries } from "@tanstack/react-query";
+import { useSDK } from "@/ui/providers/sdk-provider";
+import { STATS_QUERY_CACHE_KEY } from "../shared/use-stats-query";
+
+export const COLLECTION_RATE_CACHE_KEY = "dashboard-collection-rate";
+
+export type CollectionRateData = {
+  collectionRate: number;
+  totalCollected: number;
+  totalInvoiced: number;
+  currency: string;
+};
+
+export function useCollectionRateData(entityId: string | undefined) {
+  const { sdk } = useSDK();
+
+  const queries = useQueries({
+    queries: [
+      // Total invoiced (non-voided)
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "total-invoiced"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            {
+              metrics: [{ type: "sum", field: "total_with_tax", alias: "total" }],
+              table: "invoices",
+              filters: { is_draft: false, voided_at: null },
+            },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+      // Total collected (payments)
+      {
+        queryKey: [STATS_QUERY_CACHE_KEY, entityId, "total-collected"],
+        queryFn: async () => {
+          if (!entityId || !sdk) throw new Error("Missing entity or SDK");
+          return sdk.entityStats.queryEntityStats(
+            {
+              metrics: [{ type: "sum", field: "amount", alias: "total" }],
+              table: "payments",
+            },
+            { entity_id: entityId },
+          );
+        },
+        enabled: !!entityId && !!sdk,
+        staleTime: 30_000,
+      },
+    ],
+  });
+
+  const [invoicedQuery, collectedQuery] = queries;
+
+  const totalInvoiced = Number(invoicedQuery.data?.data?.[0]?.total) || 0;
+  const totalCollected = Number(collectedQuery.data?.data?.[0]?.total) || 0;
+  const collectionRate = totalInvoiced > 0 ? (totalCollected / totalInvoiced) * 100 : 0;
+
+  return {
+    data: {
+      collectionRate,
+      totalCollected,
+      totalInvoiced,
+      currency: "EUR", // TODO: Get from entity settings
+    } as CollectionRateData,
+    isLoading: queries.some((q) => q.isLoading),
+  };
+}

package/src/components/dashboard/index.ts

@@ -0,0 +1,54 @@
+// Chart components with hooks (turnkey)
+
+// Simple presentational components (no hooks)
+export { ChartEmptyState } from "./chart-empty-state";
+export type { CollectionRateCardProps, CollectionRateData } from "./collection-rate-card";
+export {
+  COLLECTION_RATE_CACHE_KEY,
+  CollectionRateCard,
+  useCollectionRateData,
+} from "./collection-rate-card";
+export type { InvoiceStatusChartData, InvoiceStatusChartProps, InvoiceStatusData } from "./invoice-status-chart";
+export {
+  INVOICE_STATUS_CACHE_KEY,
+  InvoiceStatusChart,
+  useInvoiceStatusData,
+} from "./invoice-status-chart";
+export type { LoadingCardProps } from "./loading-card";
+export { LoadingCard } from "./loading-card";
+export type { PaymentMethodsChartData, PaymentMethodsChartProps, PaymentMethodsData } from "./payment-methods-chart";
+export {
+  PAYMENT_METHODS_CACHE_KEY,
+  PaymentMethodsChart,
+  usePaymentMethodsData,
+} from "./payment-methods-chart";
+export type { PaymentTrendChartData, PaymentTrendChartProps, PaymentTrendData } from "./payment-trend-chart";
+export {
+  PAYMENT_TREND_CACHE_KEY,
+  PaymentTrendChart,
+  usePaymentTrendData,
+} from "./payment-trend-chart";
+export type { RevenueCardProps } from "./revenue-card";
+export { RevenueCard } from "./revenue-card";
+export type { RevenueTrendChartData, RevenueTrendChartProps, RevenueTrendData } from "./revenue-trend-chart";
+export {
+  REVENUE_TREND_CACHE_KEY,
+  RevenueTrendChart,
+  useRevenueTrendData,
+} from "./revenue-trend-chart";
+export type { RevenueData, StatsCountsData } from "./shared";
+// Shared hooks for presentational cards
+export {
+  REVENUE_DATA_CACHE_KEY,
+  STATS_COUNTS_CACHE_KEY,
+  useRevenueData,
+  useStatsCountsData,
+} from "./shared";
+export type { StatCardProps } from "./stat-card";
+export { StatCard } from "./stat-card";
+export type { TopCustomersChartData, TopCustomersChartProps, TopCustomersData } from "./top-customers-chart";
+export {
+  TOP_CUSTOMERS_CACHE_KEY,
+  TopCustomersChart,
+  useTopCustomersData,
+} from "./top-customers-chart";

package/src/components/dashboard/invoice-status-chart/index.ts

@@ -0,0 +1,4 @@
+export type { InvoiceStatusChartData, InvoiceStatusChartProps } from "./invoice-status-chart";
+export { InvoiceStatusChart } from "./invoice-status-chart";
+export type { InvoiceStatusData } from "./use-invoice-status";
+export { INVOICE_STATUS_CACHE_KEY, useInvoiceStatusData } from "./use-invoice-status";