@spaceinvoices/react-ui 0.1.1

package/src/components/documents/create/use-document-customer-form.ts

@@ -0,0 +1,161 @@
+import { useState } from "react";
+import type { FieldValues, Path, PathValue, UseFormReturn } from "react-hook-form";
+
+/**
+ * Customer data structure used in document forms.
+ * All fields are optional to support partial customer data.
+ */
+export type CustomerData = {
+  name?: string | null;
+  address?: string | null;
+  address_2?: string | null;
+  post_code?: string | null;
+  city?: string | null;
+  state?: string | null;
+  country?: string | null;
+  tax_number?: string | null;
+};
+
+/**
+ * Form schema requirements for document customer handling.
+ * Documents must have customer_id and customer fields.
+ */
+export type DocumentFormWithCustomer = FieldValues & {
+  customer_id?: string | null;
+  customer?: CustomerData | null;
+};
+
+/**
+ * Type-safe setValue wrapper for document forms.
+ */
+function _setFormValue<TForm extends FieldValues>(
+  form: UseFormReturn<TForm>,
+  name: Path<TForm>,
+  value: PathValue<TForm, Path<TForm>>,
+) {
+  form.setValue(name, value);
+}
+
+/**
+ * Shared hook for managing customer selection and form state in document forms.
+ * Used by invoices, estimates, credit notes, and advance invoices.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   originalCustomer,
+ *   showCustomerForm,
+ *   shouldFocusName,
+ *   selectedCustomerId,
+ *   handleCustomerSelect,
+ *   handleCustomerClear,
+ * } = useDocumentCustomerForm(form);
+ * ```
+ */
+export function useDocumentCustomerForm<TForm extends DocumentFormWithCustomer>(form: UseFormReturn<TForm>) {
+  // Initialize states based on form's default values (for duplication scenarios)
+  const formDefaults = form.formState.defaultValues;
+  const initialCustomerId = formDefaults?.customer_id as string | undefined;
+  const initialCustomer = formDefaults?.customer as CustomerData | undefined;
+  const hasInitialCustomer = !!(initialCustomerId || initialCustomer?.name);
+
+  const [originalCustomer, setOriginalCustomer] = useState<CustomerData | null>(
+    hasInitialCustomer && initialCustomer ? initialCustomer : null,
+  );
+  const [showCustomerForm, setShowCustomerForm] = useState(hasInitialCustomer);
+  const [shouldFocusName, setShouldFocusName] = useState(false);
+  const [selectedCustomerId, setSelectedCustomerId] = useState<string | undefined>(initialCustomerId);
+
+  // Type-safe setValue that works with the generic form type
+  const setValue = <K extends Path<TForm>>(name: K, value: PathValue<TForm, K>) => {
+    form.setValue(name, value);
+  };
+
+  const handleCustomerSelect = (customerId: string, customer: CustomerData) => {
+    const isNewCustomer = !customerId || customerId === "";
+
+    // Helper to convert empty/null to undefined for optional fields,
+    // but keep empty string for required fields (name) so form shows them
+    const toFormValue = (value: string | null | undefined, isRequired = false): string | undefined => {
+      if (value === null || value === undefined || value === "") {
+        return isRequired ? "" : undefined;
+      }
+      return value;
+    };
+
+    if (isNewCustomer) {
+      // New customer - clear customer_id and set customer data
+      setValue("customer_id" as Path<TForm>, undefined as PathValue<TForm, Path<TForm>>);
+      setValue(
+        "customer" as Path<TForm>,
+        {
+          name: toFormValue(customer.name, true),
+          address: toFormValue(customer.address),
+          address_2: toFormValue(customer.address_2),
+          post_code: toFormValue(customer.post_code),
+          city: toFormValue(customer.city),
+          state: toFormValue(customer.state),
+          country: toFormValue(customer.country),
+          tax_number: toFormValue(customer.tax_number),
+        } as PathValue<TForm, Path<TForm>>,
+      );
+      setOriginalCustomer(null);
+      setSelectedCustomerId(undefined);
+      setShouldFocusName(!customer.name);
+    } else {
+      // Existing customer - set customer_id and populate fields
+      setValue("customer_id" as Path<TForm>, customerId as PathValue<TForm, Path<TForm>>);
+
+      const customerData: CustomerData = {
+        name: toFormValue(customer.name, true),
+        address: toFormValue(customer.address),
+        address_2: toFormValue(customer.address_2),
+        post_code: toFormValue(customer.post_code),
+        city: toFormValue(customer.city),
+        state: toFormValue(customer.state),
+        country: toFormValue(customer.country),
+        tax_number: toFormValue(customer.tax_number),
+      };
+
+      setValue("customer" as Path<TForm>, customerData as PathValue<TForm, Path<TForm>>);
+      setOriginalCustomer(customerData);
+      setSelectedCustomerId(customerId);
+      setShouldFocusName(false);
+    }
+
+    setShowCustomerForm(true);
+  };
+
+  const handleCustomerClear = () => {
+    setValue("customer_id" as Path<TForm>, undefined as PathValue<TForm, Path<TForm>>);
+    // Clear customer object entirely - use undefined for optional fields
+    setValue(
+      "customer" as Path<TForm>,
+      {
+        name: "",
+        address: undefined,
+        address_2: undefined,
+        post_code: undefined,
+        city: undefined,
+        state: undefined,
+        country: undefined,
+        tax_number: undefined,
+      } as PathValue<TForm, Path<TForm>>,
+    );
+    setOriginalCustomer(null);
+    setSelectedCustomerId(undefined);
+    setShouldFocusName(false);
+    setShowCustomerForm(false);
+  };
+
+  return {
+    originalCustomer,
+    showCustomerForm,
+    shouldFocusName,
+    selectedCustomerId,
+    /** Initial customer name from form defaults (for duplication display) */
+    initialCustomerName: initialCustomer?.name ?? undefined,
+    handleCustomerSelect,
+    handleCustomerClear,
+  };
+}

package/src/components/documents/document-preview.tsx

@@ -0,0 +1,13 @@
+import type { CreateInvoiceRequest } from "@spaceinvoices/js-sdk";
+
+type DocumentPreviewProps = {
+  data: Partial<CreateInvoiceRequest>;
+};
+
+export default function DocumentPreview({ data }: DocumentPreviewProps) {
+  return (
+    <div className="rounded-lg border p-4">
+      <pre>{JSON.stringify(data, null, 2)}</pre>
+    </div>
+  );
+}

package/src/components/documents/documents.hooks.ts

@@ -0,0 +1,146 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { AUTH_COOKIES } from "@/ui/lib/auth";
+import { getCookie } from "@/ui/lib/browser-cookies";
+
+// Document type union for API calls
+export type DocumentType = "invoice" | "estimate" | "credit_note" | "advance_invoice";
+
+// Cache key map for invalidation
+const CACHE_KEYS: Record<DocumentType, string> = {
+  invoice: "invoices",
+  estimate: "estimates",
+  credit_note: "credit-notes",
+  advance_invoice: "advance-invoices",
+};
+
+/**
+ * Get API base URL from environment
+ */
+function getApiBaseUrl(): string {
+  if (typeof window === "undefined") return "";
+  return (import.meta.env?.VITE_API_URL || import.meta.env?.BUN_PUBLIC_API_URL || "") as string;
+}
+
+/**
+ * Make authenticated API request
+ */
+async function apiRequest<T>(path: string, options: RequestInit & { entityId: string }): Promise<T> {
+  const token = getCookie(AUTH_COOKIES.TOKEN);
+  const baseUrl = getApiBaseUrl();
+
+  const response = await fetch(`${baseUrl}${path}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      "x-entity-id": options.entityId,
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new Error(errorData.message || `Request failed with status ${response.status}`);
+  }
+
+  // DELETE returns 204 No Content
+  if (response.status === 204) {
+    return undefined as T;
+  }
+
+  return response.json();
+}
+
+// ============================================================================
+// Finalize Document Hook
+// ============================================================================
+
+type FinalizeDocumentOptions = {
+  entityId: string;
+  onSuccess?: (data: unknown) => void;
+  onError?: (error: Error) => void;
+};
+
+type FinalizeDocumentVariables = {
+  documentId: string;
+  documentType: DocumentType;
+};
+
+/**
+ * Hook to finalize a draft document
+ * Assigns a document number and runs fiscalization (if applicable)
+ */
+export function useFinalizeDocument(options: FinalizeDocumentOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ documentId, documentType }: FinalizeDocumentVariables) => {
+      return apiRequest(`/documents/${documentId}/finalize?type=${documentType}`, {
+        method: "POST",
+        entityId: options.entityId,
+      });
+    },
+    onSuccess: (data, variables) => {
+      // Invalidate list cache
+      const cacheKey = CACHE_KEYS[variables.documentType];
+      queryClient.invalidateQueries({ queryKey: [cacheKey] });
+
+      // Invalidate document detail cache
+      queryClient.invalidateQueries({
+        queryKey: ["documents", variables.documentType, variables.documentId],
+      });
+
+      options.onSuccess?.(data);
+    },
+    onError: (error: Error) => {
+      options.onError?.(error);
+    },
+  });
+}
+
+// ============================================================================
+// Delete Draft Document Hook
+// ============================================================================
+
+type DeleteDraftDocumentOptions = {
+  entityId: string;
+  onSuccess?: () => void;
+  onError?: (error: Error) => void;
+};
+
+type DeleteDraftDocumentVariables = {
+  documentId: string;
+  documentType: DocumentType;
+};
+
+/**
+ * Hook to delete a draft document
+ * Only draft documents can be deleted
+ */
+export function useDeleteDraftDocument(options: DeleteDraftDocumentOptions) {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({ documentId, documentType }: DeleteDraftDocumentVariables) => {
+      return apiRequest(`/documents/${documentId}?type=${documentType}`, {
+        method: "DELETE",
+        entityId: options.entityId,
+      });
+    },
+    onSuccess: (_, variables) => {
+      // Invalidate list cache
+      const cacheKey = CACHE_KEYS[variables.documentType];
+      queryClient.invalidateQueries({ queryKey: [cacheKey] });
+
+      // Remove document from detail cache
+      queryClient.removeQueries({
+        queryKey: ["documents", variables.documentType, variables.documentId],
+      });
+
+      options.onSuccess?.();
+    },
+    onError: (error: Error) => {
+      options.onError?.(error);
+    },
+  });
+}

package/src/components/documents/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Documents - Shared components for all document types (invoices, estimates, credit notes)
+ */
+
+export { default as DocumentAddItemForm } from "./create/document-add-item-form";
+export { default as DocumentAddItemTaxRateField } from "./create/document-add-item-tax-rate-field";
+// Create form components
+export { DocumentDetailsSection } from "./create/document-details-section";
+export { DocumentItemsSection } from "./create/document-items-section";
+export { DocumentRecipientSection } from "./create/document-recipient-section";
+export { LiveInvoicePreview } from "./create/live-preview";
+export { MarkAsPaidSection } from "./create/mark-as-paid-section";
+// Shared utilities
+export { prepareDocumentSubmission } from "./create/prepare-document-submission";
+export { useDocumentCustomerForm } from "./create/use-document-customer-form";
+// Preview components
+export { default as DocumentPreview } from "./document-preview";
+export { ScaledDocumentPreview } from "./shared/scaled-document-preview";
+export { useA4Scaling } from "./shared/use-a4-scaling";
+// Types
+export * from "./types";
+// View components
+export { DocumentActionsBar, DocumentDetailsCard, DocumentPaymentsList } from "./view";

package/src/components/documents/shared/document-preview-display.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import type { AdvanceInvoice, CreditNote, Estimate, Invoice } from "@spaceinvoices/js-sdk";
+import { AlertCircle, FileText, Loader2 } from "lucide-react";
+import { useEffect, useState } from "react";
+import { cn } from "@/ui/lib/utils";
+import { useEntitiesOptional } from "@/ui/providers/entities-context";
+import { useSDK } from "@/ui/providers/sdk-provider";
+import { ScaledDocumentPreview } from "./scaled-document-preview";
+import { useA4Scaling } from "./use-a4-scaling";
+
+type Document = Invoice | Estimate | CreditNote | AdvanceInvoice;
+
+/**
+ * Get API path segment from shareable ID prefix
+ * Shareable IDs are prefixed with document type: inv_share_, est_share_, cre_share_, adv_share_
+ */
+function getDocTypePathFromShareableId(shareableId: string): string {
+  if (shareableId.startsWith("inv_share_")) return "invoices";
+  if (shareableId.startsWith("est_share_")) return "estimates";
+  if (shareableId.startsWith("cre_share_")) return "credit-notes";
+  if (shareableId.startsWith("adv_share_")) return "advance-invoices";
+  // Fallback to invoices for backwards compatibility
+  return "invoices";
+}
+
+type DocumentPreviewDisplayProps = {
+  /** The document to display (invoice, estimate, credit note, or advance invoice) */
+  document: Document;
+  template?: "modern";
+  className?: string;
+  apiBaseUrl?: string;
+  /** Locale for document rendering (e.g., "en-US", "sl-SI"). Uses user's UI language. */
+  locale?: string;
+  /** Whether this is a public view (no auth required) */
+  isPublicView?: boolean;
+  /** Shareable ID for public view (required when isPublicView is true) */
+  shareableId?: string;
+};
+
+/**
+ * Document Preview Display Component
+ *
+ * Fetches and displays the HTML preview of a saved document.
+ * Works with any document type (invoice, estimate, credit note, advance invoice).
+ * Document type is auto-detected from the ID prefix.
+ */
+export function DocumentPreviewDisplay({
+  document,
+  template,
+  className,
+  apiBaseUrl,
+  locale,
+  isPublicView = false,
+  shareableId,
+}: DocumentPreviewDisplayProps) {
+  const [previewHtml, setPreviewHtml] = useState<string>("");
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const entitiesContext = useEntitiesOptional();
+  const activeEntity = entitiesContext?.activeEntity;
+  const { sdk } = useSDK();
+
+  const { containerRef, contentRef, scale, contentHeight, A4_WIDTH_PX } = useA4Scaling(previewHtml);
+
+  useEffect(() => {
+    const fetchPreview = async () => {
+      // For public view, use per-type shareable HTML endpoint
+      if (isPublicView && shareableId && apiBaseUrl) {
+        setIsLoading(true);
+        setError(null);
+        try {
+          // Determine document type from shareable ID prefix
+          const docTypePath = getDocTypePathFromShareableId(shareableId);
+          const response = await fetch(
+            `${apiBaseUrl}/${docTypePath}/shareable/${shareableId}/html${locale ? `?locale=${locale}` : ""}`,
+          );
+          if (!response.ok) {
+            throw new Error("Failed to load preview");
+          }
+          const html = await response.text();
+          setPreviewHtml(html);
+        } catch (err) {
+          setError(err instanceof Error ? err.message : "Failed to load preview");
+          setPreviewHtml("");
+        } finally {
+          setIsLoading(false);
+        }
+        return;
+      }
+
+      // Authenticated view - require entity context and SDK
+      if (!document?.id || !activeEntity?.id || !sdk) {
+        return;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        // Fetch the rendered HTML by document ID using SDK wrapper
+        // Document type is auto-detected from ID prefix (inv_, est_, cre_, adv_)
+        const html = await sdk.invoices.renderHtml(document.id, { template, locale }, { entity_id: activeEntity.id });
+
+        setPreviewHtml(html);
+        setError(null);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to load preview");
+        setPreviewHtml("");
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchPreview();
+  }, [document?.id, activeEntity?.id, template, apiBaseUrl, locale, isPublicView, shareableId, sdk]);
+
+  return (
+    <div ref={containerRef} className={cn("relative h-full", className)}>
+      {/* Loading state */}
+      {isLoading && (
+        <div className="flex h-full items-center justify-center rounded-lg border bg-muted/50">
+          <div className="flex flex-col items-center gap-2">
+            <Loader2 className="h-8 w-8 animate-spin text-primary" />
+            <p className="text-muted-foreground text-sm">Loading preview...</p>
+          </div>
+        </div>
+      )}
+
+      {/* Error state */}
+      {error && !isLoading && (
+        <div className="flex h-full items-center justify-center rounded-lg border border-destructive/50 bg-destructive/10 p-8">
+          <div className="flex flex-col items-center gap-2 text-center">
+            <AlertCircle className="h-8 w-8 text-destructive" />
+            <p className="font-semibold text-destructive">Preview Error</p>
+            <p className="text-muted-foreground text-sm">{error}</p>
+          </div>
+        </div>
+      )}
+
+      {/* Empty state - no preview available */}
+      {!previewHtml && !error && !isLoading && (
+        <div className="flex h-full items-center justify-center rounded-lg border border-dashed bg-muted/30">
+          <div className="flex flex-col items-center gap-3 text-center">
+            <div className="rounded-full bg-muted p-4">
+              <FileText className="h-8 w-8 text-muted-foreground" />
+            </div>
+            <div>
+              <p className="font-medium text-muted-foreground">Document Preview</p>
+              <p className="text-muted-foreground/70 text-sm">Preview will appear here</p>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {/* Preview - Scoped HTML injection with A4 scaling */}
+      {previewHtml && !error && !isLoading && (
+        <ScaledDocumentPreview
+          htmlContent={previewHtml}
+          scale={scale}
+          contentHeight={contentHeight}
+          A4_WIDTH_PX={A4_WIDTH_PX}
+          contentRef={contentRef}
+          entityUpdatedAt={activeEntity?.updated_at ? new Date(activeEntity.updated_at) : null}
+        />
+      )}
+    </div>
+  );
+}
+
+/** @deprecated Use DocumentPreviewDisplay instead */
+export const InvoicePreviewDisplay = DocumentPreviewDisplay;

package/src/components/documents/shared/index.ts

@@ -0,0 +1,3 @@
+export { DocumentPreviewDisplay, InvoicePreviewDisplay } from "./document-preview-display";
+export { ScaledDocumentPreview } from "./scaled-document-preview";
+export { useA4Scaling } from "./use-a4-scaling";

package/src/components/documents/shared/scaled-document-preview.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { type FC, useEffect, useRef, useState } from "react";
+
+interface ScaledDocumentPreviewProps {
+  htmlContent: string;
+  scale: number;
+  contentHeight: number | null;
+  A4_WIDTH_PX: number;
+  contentRef: React.RefObject<HTMLDivElement | null>;
+  entityUpdatedAt?: Date | null;
+}
+
+/**
+ * Scaled Document Preview Component
+ *
+ * Renders HTML content in a Shadow DOM with A4 scaling applied using CSS transforms.
+ * Uses Shadow DOM to completely isolate template CSS from the parent page.
+ */
+export const ScaledDocumentPreview: FC<ScaledDocumentPreviewProps> = ({ htmlContent, scale, A4_WIDTH_PX }) => {
+  const shadowHostRef = useRef<HTMLDivElement>(null);
+  const shadowRootRef = useRef<ShadowRoot | null>(null);
+  const [contentHeight, setContentHeight] = useState<number>(1123); // A4 height default
+
+  useEffect(() => {
+    const host = shadowHostRef.current;
+    if (!host) return;
+
+    // Create shadow root only once
+    if (!shadowRootRef.current) {
+      shadowRootRef.current = host.attachShadow({ mode: "open" });
+    }
+
+    const shadowRoot = shadowRootRef.current;
+    shadowRoot.innerHTML = htmlContent;
+
+    // Measure content height after render
+    const measureHeight = () => {
+      const firstChild = shadowRoot.firstElementChild as HTMLElement;
+      if (firstChild) {
+        setContentHeight(firstChild.scrollHeight || 1123);
+      }
+    };
+
+    setTimeout(measureHeight, 50);
+  }, [htmlContent]);
+
+  return (
+    <div className="rounded-lg border bg-neutral-100 p-4">
+      <div
+        style={{
+          width: A4_WIDTH_PX * scale,
+          height: contentHeight * scale,
+          margin: "0 auto",
+          overflow: "hidden",
+        }}
+      >
+        <div
+          ref={shadowHostRef}
+          style={{
+            width: A4_WIDTH_PX,
+            transform: `scale(${scale})`,
+            transformOrigin: "top left",
+            background: "white",
+          }}
+        />
+      </div>
+    </div>
+  );
+};

package/src/components/documents/shared/use-a4-scaling.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * Custom hook for A4 document scaling
+ * Handles responsive scaling of A4-sized documents to fit container width
+ *
+ * @returns Object containing scale, contentHeight, and refs for container and content
+ */
+export function useA4Scaling(_htmlContent?: string) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState(1);
+  const [contentHeight, setContentHeight] = useState<number | null>(null);
+
+  // A4 width in pixels at 96 DPI (210mm)
+  const A4_WIDTH_PX = 794;
+
+  // Observe container width and calculate scale
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const width = entry.contentRect.width;
+        // Subtract padding
+        const availableWidth = width - 32;
+        // Round to 2 decimal places and only update if significant change (>1%)
+        const newScale = Math.round((availableWidth / A4_WIDTH_PX) * 100) / 100;
+        setScale((prev) => (Math.abs(prev - newScale) > 0.01 ? newScale : prev));
+      }
+    });
+
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, []);
+
+  // Observe content height for proper container sizing
+  useEffect(() => {
+    const content = contentRef.current;
+    if (!content) return;
+
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const newHeight = Math.round(entry.contentRect.height);
+        // Only update if height changed by more than 5px to avoid jitter
+        setContentHeight((prev) => (prev === null || Math.abs(prev - newHeight) > 5 ? newHeight : prev));
+      }
+    });
+
+    observer.observe(content);
+    return () => observer.disconnect();
+  }, []);
+
+  return {
+    containerRef,
+    contentRef,
+    scale,
+    contentHeight,
+    A4_WIDTH_PX,
+  };
+}