@spaceinvoices/react-ui 0.1.1

package/src/hooks/create-resource-hooks.ts

@@ -0,0 +1,300 @@
+import type SDK from "@spaceinvoices/js-sdk";
+import type { UseMutationOptions } from "@tanstack/react-query";
+
+import { useQueryClient } from "@tanstack/react-query";
+import { useResourceMutation } from "./use-resource-mutation";
+
+/**
+ * Options for resource mutation hooks
+ */
+type ResourceMutationHookOptions<TData, TError, TVariables = any> = {
+  entityId?: string | null;
+  accountId?: string | null;
+  onSuccess?: (data: TData, variables: TVariables, context: unknown) => void;
+  onError?: (error: TError, variables: TVariables, context: unknown) => void;
+  mutationOptions?: Omit<UseMutationOptions<TData, TError, any, unknown>, "mutationFn" | "onSuccess" | "onError">;
+};
+
+/**
+ * Build query key with optional filters
+ */
+function buildQueryKey(
+  baseKey: string,
+  filters?: { entityId?: string | null; accountId?: string | null },
+): [string, Record<string, string>?] {
+  if (!filters?.entityId && !filters?.accountId) {
+    return [baseKey];
+  }
+
+  const params: Record<string, string> = {};
+  if (filters.entityId) params.entityId = filters.entityId;
+  if (filters.accountId) params.accountId = filters.accountId;
+
+  return [baseKey, params];
+}
+
+/**
+ * Invalidate resource-specific queries
+ */
+function invalidateResourceQueries(
+  queryClient: ReturnType<typeof useQueryClient>,
+  cacheKey: string,
+  resourceId: string,
+  filters?: { entityId?: string | null; accountId?: string | null },
+): void {
+  const detailKey = `${cacheKey}-${resourceId}`;
+  queryClient.invalidateQueries({ queryKey: buildQueryKey(detailKey, filters) });
+}
+
+/**
+ * Factory function to create resource-specific CRUD hooks
+ *
+ * @param resourceName - The name of the resource in the SDK (e.g., 'customers')
+ * @param cacheKey - The cache key for the resource queries
+ *
+ * @example
+ * ```ts
+ * const { useCreateResource, useUpdateResource, useDeleteResource } =
+ *   createResourceHooks<Customer, CreateCustomerRequest['data']>('customers', 'customers');
+ *
+ * // Usage
+ * const createCustomer = useCreateResource();
+ * ```
+ */
+export function createResourceHooks<
+  TResource extends { id: string },
+  TCreateData = unknown,
+  TUpdateData = Partial<Omit<TResource, "id">>,
+>(resourceName: keyof SDK, cacheKey: string) {
+  /**
+   * Hook for creating a new resource
+   */
+  function useCreateResource<TError = Error>(
+    options: ResourceMutationHookOptions<TResource, TError, TCreateData> = {},
+  ) {
+    const queryClient = useQueryClient();
+
+    return useResourceMutation<TResource, TError, TCreateData>({
+      resourceName,
+      methodName: "create",
+      cacheKey,
+      entityId: options.entityId,
+      accountId: options.accountId,
+      mutationOptions: {
+        onMutate: async (variables) => {
+          // Cancel any outgoing refetches to avoid overwriting optimistic update
+          const listQueryKey = buildQueryKey(cacheKey, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+          await queryClient.cancelQueries({ queryKey: listQueryKey });
+
+          // Snapshot the previous value
+          const previousData = queryClient.getQueryData(listQueryKey);
+
+          // Optimistically add the new resource to the cache
+          queryClient.setQueryData(listQueryKey, (oldData: any) => {
+            if (!oldData?.data) return oldData;
+
+            // Create temporary resource for optimistic update
+            // Use 'unknown' as intermediate to safely cast
+            const tempResource = {
+              ...variables,
+              id: `temp-${Date.now()}`,
+              created_at: new Date().toISOString(),
+              updated_at: new Date().toISOString(),
+            } as unknown as TResource;
+
+            return {
+              ...oldData,
+              data: [tempResource, ...oldData.data],
+              pagination: oldData.pagination
+                ? {
+                    ...oldData.pagination,
+                    total: oldData.pagination.total + 1,
+                  }
+                : undefined,
+            };
+          });
+
+          return { previousData };
+        },
+        onSuccess: options.onSuccess,
+        onError: (error, variables, context: any) => {
+          // Rollback on error
+          if (context?.previousData) {
+            const listQueryKey = buildQueryKey(cacheKey, {
+              entityId: options.entityId,
+              accountId: options.accountId,
+            });
+            queryClient.setQueryData(listQueryKey, context.previousData);
+          }
+          options.onError?.(error, variables, context);
+        },
+        onSettled: () => {
+          // Always refetch after error or success to ensure consistency
+          const listQueryKey = buildQueryKey(cacheKey, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+          queryClient.invalidateQueries({ queryKey: listQueryKey });
+        },
+        ...options.mutationOptions,
+      },
+    });
+  }
+
+  /**
+   * Hook for updating an existing resource
+   */
+  function useUpdateResource<TError = Error>(
+    options: ResourceMutationHookOptions<TResource, TError, { id: string; data: TUpdateData }> = {},
+  ) {
+    const queryClient = useQueryClient();
+
+    return useResourceMutation<TResource, TError, { id: string; data: TUpdateData }>({
+      resourceName,
+      methodName: "update",
+      cacheKey: [cacheKey, `${cacheKey}-detail`],
+      entityId: options.entityId,
+      accountId: options.accountId,
+      mutationOptions: {
+        onMutate: async (variables) => {
+          const listQueryKey = buildQueryKey(cacheKey, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+          const detailKey = `${cacheKey}-${variables.id}`;
+          const detailQueryKey = buildQueryKey(detailKey, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+
+          // Cancel outgoing refetches
+          await queryClient.cancelQueries({ queryKey: listQueryKey });
+          await queryClient.cancelQueries({ queryKey: detailQueryKey });
+
+          // Snapshot previous values
+          const previousListData = queryClient.getQueryData(listQueryKey);
+          const previousDetailData = queryClient.getQueryData(detailQueryKey);
+
+          // Optimistically update list cache
+          queryClient.setQueryData(listQueryKey, (oldData: any) => {
+            if (!oldData?.data) return oldData;
+
+            return {
+              ...oldData,
+              data: oldData.data.map((resource: TResource) =>
+                resource.id === variables.id
+                  ? {
+                      ...resource,
+                      ...variables.data,
+                      updated_at: new Date().toISOString(),
+                    }
+                  : resource,
+              ),
+            };
+          });
+
+          // Optimistically update detail cache
+          queryClient.setQueryData(detailQueryKey, (oldData: any) => {
+            if (!oldData) return oldData;
+            return {
+              ...oldData,
+              ...variables.data,
+              updated_at: new Date().toISOString(),
+            };
+          });
+
+          return { previousListData, previousDetailData };
+        },
+        onSuccess: (data, variables, context) => {
+          // Invalidate the specific resource detail cache
+          invalidateResourceQueries(queryClient, cacheKey, variables.id, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+
+          options.onSuccess?.(data, variables, context);
+        },
+        onError: (error, variables, context: any) => {
+          // Rollback on error
+          if (context?.previousListData) {
+            const listQueryKey = buildQueryKey(cacheKey, {
+              entityId: options.entityId,
+              accountId: options.accountId,
+            });
+            queryClient.setQueryData(listQueryKey, context.previousListData);
+          }
+          if (context?.previousDetailData) {
+            const detailKey = `${cacheKey}-${variables.id}`;
+            const detailQueryKey = buildQueryKey(detailKey, {
+              entityId: options.entityId,
+              accountId: options.accountId,
+            });
+            queryClient.setQueryData(detailQueryKey, context.previousDetailData);
+          }
+          options.onError?.(error, variables, context);
+        },
+        onSettled: () => {
+          // Always refetch to ensure consistency
+          const listQueryKey = buildQueryKey(cacheKey, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+          queryClient.invalidateQueries({ queryKey: listQueryKey });
+        },
+        ...options.mutationOptions,
+      },
+    });
+  }
+
+  /**
+   * Hook for deleting a resource
+   */
+  function useDeleteResource<TError = Error>(options: ResourceMutationHookOptions<void, TError, { id: string }> = {}) {
+    const queryClient = useQueryClient();
+
+    return useResourceMutation<void, TError, { id: string }>({
+      resourceName,
+      methodName: "delete",
+      cacheKey,
+      entityId: options.entityId,
+      accountId: options.accountId,
+      mutationOptions: {
+        onSuccess: (data, variables, context) => {
+          // Invalidate the specific resource detail cache
+          invalidateResourceQueries(queryClient, cacheKey, variables.id, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+
+          // Optimistically remove from list cache
+          const listQueryKey = buildQueryKey(cacheKey, {
+            entityId: options.entityId,
+            accountId: options.accountId,
+          });
+
+          queryClient.setQueriesData({ queryKey: listQueryKey }, (oldData: any) => {
+            if (!oldData?.data) return oldData;
+
+            return {
+              ...oldData,
+              data: oldData.data.filter((resource: TResource) => resource.id !== variables.id),
+            };
+          });
+
+          options.onSuccess?.(data, variables, context);
+        },
+        onError: options.onError,
+        ...options.mutationOptions,
+      },
+    });
+  }
+
+  return {
+    useCreateResource,
+    useUpdateResource,
+    useDeleteResource,
+  };
+}

package/src/hooks/use-debounce.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/hooks/use-duplicate-document.ts

@@ -0,0 +1,185 @@
+import type {
+  AdvanceInvoiceWithItems,
+  CreateAdvanceInvoiceRequest,
+  CreateCreditNoteRequest,
+  CreateEstimateRequest,
+  CreateInvoiceRequest,
+  CreditNoteWithItems,
+  EstimateWithItems,
+  InvoiceWithItems,
+} from "@spaceinvoices/js-sdk";
+import { useQuery } from "@tanstack/react-query";
+
+import { useEntities } from "@/ui/providers/entities-context";
+import { useSDK } from "@/ui/providers/sdk-provider";
+
+export type DocumentType = "invoice" | "estimate" | "credit_note" | "advance_invoice";
+type Document = InvoiceWithItems | EstimateWithItems | CreditNoteWithItems | AdvanceInvoiceWithItems;
+type CreateRequest =
+  | CreateInvoiceRequest
+  | CreateEstimateRequest
+  | CreateCreditNoteRequest
+  | CreateAdvanceInvoiceRequest;
+
+/**
+ * Get document type from ID prefix
+ */
+export function getDocumentTypeFromId(id: string): DocumentType | null {
+  if (id.startsWith("inv_")) return "invoice";
+  if (id.startsWith("est_")) return "estimate";
+  if (id.startsWith("cn_")) return "credit_note";
+  if (id.startsWith("adv_")) return "advance_invoice";
+  return null;
+}
+
+/**
+ * Get allowed target types for duplication/conversion
+ */
+export function getAllowedDuplicateTargets(sourceType: DocumentType): DocumentType[] {
+  switch (sourceType) {
+    case "invoice":
+      return ["invoice", "credit_note"];
+    case "estimate":
+      return ["estimate", "invoice"];
+    case "credit_note":
+      return ["credit_note"];
+    case "advance_invoice":
+      return ["advance_invoice", "invoice"];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Transform a source document into form-compatible initial values
+ * Copies relevant fields and resets computed/generated ones
+ */
+function transformDocumentForDuplication(source: Document, _targetType: DocumentType): Partial<CreateRequest> {
+  // Transform items - copy only the fields needed for creation
+  const items = source.items?.map((item: (typeof source.items)[number]) => ({
+    name: item.name,
+    description: item.description,
+    quantity: item.quantity,
+    // Use gross_price if set, otherwise use price. The form uses is_gross_price as a UI toggle.
+    price: (item as { gross_price?: number }).gross_price ?? item.price,
+    // Copy tax references (tax_id), not computed tax data
+    taxes: item.taxes?.map((tax: { tax_id?: string }) => ({ tax_id: tax.tax_id })),
+    // Derive is_gross_price from whether gross_price is set
+    gross_price: (item as { gross_price?: number }).gross_price,
+  }));
+
+  // Build customer data - always copy if available (form needs this for display)
+  const customerData = source.customer
+    ? {
+        name: source.customer.name,
+        address: source.customer.address,
+        address_2: source.customer.address_2,
+        city: source.customer.city,
+        post_code: source.customer.post_code,
+        country: source.customer.country,
+        country_code: source.customer.country_code,
+        tax_number: source.customer.tax_number,
+        email: source.customer.email,
+      }
+    : undefined;
+
+  // Build base duplicate data
+  const baseData: Partial<CreateRequest> = {
+    // Customer - always pass both customer_id AND customer data when available
+    // The form needs customer data for display, even when customer_id is set
+    ...(source.customer_id ? { customer_id: source.customer_id } : {}),
+    ...(customerData ? { customer: customerData } : {}),
+    // Items
+    items,
+    // Currency
+    currency_code: source.currency_code,
+    // Notes
+    note: source.note,
+    payment_terms: source.payment_terms,
+    // Date - use today's date as ISO string
+    date: new Date().toISOString(),
+    // Number - leave empty for auto-generation
+    // Do NOT copy: number, totals, taxes, payments, furs, eslog, vies, shareable_id
+  };
+
+  return baseData;
+}
+
+export type UseDuplicateDocumentOptions = {
+  /** Source document ID to duplicate from */
+  sourceId: string | undefined;
+  /** Target document type (may differ from source for conversions) */
+  targetType: DocumentType;
+  /** Whether to enable the query */
+  enabled?: boolean;
+};
+
+export type UseDuplicateDocumentResult = {
+  /** Transformed initial values for the form */
+  initialValues: Partial<CreateRequest> | undefined;
+  /** Loading state */
+  isLoading: boolean;
+  /** Error if fetch failed */
+  error: Error | null;
+  /** Source document type */
+  sourceType: DocumentType | null;
+};
+
+/**
+ * Hook to fetch and transform a document for duplication
+ *
+ * @example
+ * ```tsx
+ * const { initialValues, isLoading } = useDuplicateDocument({
+ *   sourceId: searchParams.duplicateFrom,
+ *   targetType: 'invoice',
+ * });
+ * ```
+ */
+export function useDuplicateDocument({
+  sourceId,
+  targetType,
+  enabled = true,
+}: UseDuplicateDocumentOptions): UseDuplicateDocumentResult {
+  const { sdk } = useSDK();
+  const { activeEntity } = useEntities();
+
+  const sourceType = sourceId ? getDocumentTypeFromId(sourceId) : null;
+
+  const query = useQuery({
+    queryKey: ["duplicate-document", sourceId, targetType, activeEntity?.id],
+    queryFn: async () => {
+      if (!sourceId || !activeEntity?.id || !sourceType) {
+        throw new Error("Source document ID and entity ID are required");
+      }
+
+      // Fetch source document based on its type
+      let source: Document;
+      if (sourceType === "invoice") {
+        source = await sdk.invoices.get(sourceId, undefined, { entity_id: activeEntity.id });
+      } else if (sourceType === "estimate") {
+        // estimates.get only takes 2 args (no params)
+        source = await sdk.estimates.get(sourceId, { entity_id: activeEntity.id });
+      } else if (sourceType === "advance_invoice") {
+        source = await sdk.advanceInvoices.get(sourceId, undefined, { entity_id: activeEntity.id });
+      } else {
+        // Credit note
+        source = await sdk.creditNotes.get(sourceId, undefined, { entity_id: activeEntity.id });
+      }
+
+      if (!source) {
+        throw new Error("Source document not found");
+      }
+
+      return transformDocumentForDuplication(source, targetType);
+    },
+    enabled: enabled && !!sourceId && !!activeEntity?.id && !!sourceType,
+  });
+
+  return {
+    initialValues: query.data,
+    isLoading: query.isLoading,
+    error: query.error,
+    sourceType,
+  };
+}

package/src/hooks/use-media-query.tsx

@@ -0,0 +1,19 @@
+import * as React from "react";
+
+export function useMediaQuery(query: string) {
+  const [value, setValue] = React.useState(false);
+
+  React.useEffect(() => {
+    function onChange(event: MediaQueryListEvent) {
+      setValue(event.matches);
+    }
+
+    const result = matchMedia(query);
+    result.addEventListener("change", onChange);
+    setValue(result.matches);
+
+    return () => result.removeEventListener("change", onChange);
+  }, [query]);
+
+  return value;
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+
+const MOBILE_BREAKPOINT = 768;
+const SMALL_SCREEN_BREAKPOINT = 1024;
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined);
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
+    mql.addEventListener("change", onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
+
+  return !!isMobile;
+}
+
+export function useIsSmallScreen() {
+  const [isSmallScreen, setIsSmallScreen] = React.useState<boolean | undefined>(undefined);
+
+  React.useEffect(() => {
+    const checkSize = () => {
+      const width = window.innerWidth;
+      setIsSmallScreen(width >= MOBILE_BREAKPOINT && width < SMALL_SCREEN_BREAKPOINT);
+    };
+    const mql = window.matchMedia(
+      `(min-width: ${MOBILE_BREAKPOINT}px) and (max-width: ${SMALL_SCREEN_BREAKPOINT - 1}px)`,
+    );
+    mql.addEventListener("change", checkSize);
+    checkSize();
+    return () => mql.removeEventListener("change", checkSize);
+  }, []);
+
+  return !!isSmallScreen;
+}

package/src/hooks/use-next-document-number.ts

@@ -0,0 +1,57 @@
+import { useQuery } from "@tanstack/react-query";
+
+import { useSDK } from "@/ui/providers/sdk-provider";
+
+export const NEXT_DOCUMENT_NUMBER_CACHE_KEY = "next-document-number";
+
+export type DocumentType = "invoice" | "estimate" | "credit_note" | "advance_invoice";
+
+/** Response type for next document number preview */
+export type NextDocumentNumberResponse = {
+  number: string | null;
+  furs: {
+    business_premise_name: string;
+    electronic_device_name: string;
+  } | null;
+};
+
+/**
+ * Hook to fetch the next document number preview
+ * Does not increment the sequence - purely for preview purposes
+ *
+ * Uses sdk.documents.getNextNumber() - the shared documents API
+ */
+export function useNextDocumentNumber(
+  entityId: string,
+  type: DocumentType,
+  options?: {
+    businessPremiseName?: string;
+    electronicDeviceName?: string;
+    enabled?: boolean;
+  },
+) {
+  const { sdk } = useSDK();
+
+  return useQuery<NextDocumentNumberResponse>({
+    queryKey: [
+      NEXT_DOCUMENT_NUMBER_CACHE_KEY,
+      entityId,
+      type,
+      options?.businessPremiseName,
+      options?.electronicDeviceName,
+    ],
+    queryFn: async () => {
+      const response = await sdk.documents.getNextNumber(
+        {
+          type,
+          business_premise_name: options?.businessPremiseName,
+          electronic_device_name: options?.electronicDeviceName,
+        },
+        { entity_id: entityId },
+      );
+      return response;
+    },
+    enabled: options?.enabled !== false && !!entityId && !!sdk?.documents,
+    staleTime: 0, // Always refetch when form opens
+  });
+}