@spaceinvoices/react-ui 0.1.1

package/src/lib/schemas/advance-invoice.ts

@@ -0,0 +1,43 @@
+/**
+ * Advance invoice form schema.
+ *
+ * Requires: ./shared.ts
+ */
+import type { CreateAdvanceInvoiceBody } from "@spaceinvoices/js-sdk";
+import { z } from "zod";
+import { customerSchema, lineItemSchema, transformItemsForApi } from "./shared";
+
+// Advance invoices don't have payment_terms - they are documents requesting payment
+export const advanceInvoiceFormSchema = z.object({
+  number: z.string().max(100).optional(),
+  date: z.string().optional(),
+  date_due: z.string().optional(),
+  customer_id: z.string().nullish(),
+  customer: customerSchema,
+  items: z.array(lineItemSchema).min(1),
+  note: z.string().nullish(),
+  currency_code: z.string().max(3).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  linked_documents: z.array(z.string()).optional(),
+  furs: z
+    .object({
+      business_premise_name: z.string().optional(),
+      electronic_device_name: z.string().optional(),
+      operator_tax_number: z.string().optional(),
+      operator_label: z.string().optional(),
+      skip: z.boolean().optional(),
+    })
+    .optional(),
+  eslog: z.object({ validation_enabled: z.boolean().optional() }).optional(),
+  bank_account_index: z.number().optional(),
+});
+
+export type AdvanceInvoiceFormValues = z.infer<typeof advanceInvoiceFormSchema>;
+
+/** Convert form values to API request */
+export function toCreateAdvanceInvoiceRequest(values: AdvanceInvoiceFormValues): CreateAdvanceInvoiceBody {
+  return {
+    ...values,
+    items: transformItemsForApi(values.items ?? []),
+  } as CreateAdvanceInvoiceBody;
+}

package/src/lib/schemas/credit-note.ts

@@ -0,0 +1,32 @@
+/**
+ * Credit note form schema.
+ *
+ * Requires: ./shared.ts
+ */
+import type { CreateCreditNoteBody } from "@spaceinvoices/js-sdk";
+import { z } from "zod";
+import { customerSchema, lineItemSchema, transformItemsForApi } from "./shared";
+
+export const creditNoteFormSchema = z.object({
+  number: z.string().max(100).optional(),
+  date: z.string().optional(),
+  customer_id: z.string().nullish(),
+  customer: customerSchema,
+  items: z.array(lineItemSchema).min(1),
+  note: z.string().nullish(),
+  payment_terms: z.string().nullish(),
+  currency_code: z.string().max(3).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  linked_documents: z.array(z.string()).optional(),
+  eslog: z.object({ validation_enabled: z.boolean().optional() }).optional(),
+});
+
+export type CreditNoteFormValues = z.infer<typeof creditNoteFormSchema>;
+
+/** Convert form values to API request */
+export function toCreateCreditNoteRequest(values: CreditNoteFormValues): CreateCreditNoteBody {
+  return {
+    ...values,
+    items: transformItemsForApi(values.items ?? []),
+  } as CreateCreditNoteBody;
+}

package/src/lib/schemas/estimate.ts

@@ -0,0 +1,31 @@
+/**
+ * Estimate form schema.
+ *
+ * Requires: ./shared.ts
+ */
+import type { CreateEstimateBody } from "@spaceinvoices/js-sdk";
+import { z } from "zod";
+import { customerSchema, lineItemSchema, transformItemsForApi } from "./shared";
+
+export const estimateFormSchema = z.object({
+  number: z.string().max(100).optional(),
+  date: z.string().optional(),
+  date_valid_till: z.string().optional(),
+  customer_id: z.string().nullish(),
+  customer: customerSchema,
+  items: z.array(lineItemSchema).min(1),
+  note: z.string().nullish(),
+  payment_terms: z.string().nullish(),
+  currency_code: z.string().max(3).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type EstimateFormValues = z.infer<typeof estimateFormSchema>;
+
+/** Convert form values to API request */
+export function toCreateEstimateRequest(values: EstimateFormValues): CreateEstimateBody {
+  return {
+    ...values,
+    items: transformItemsForApi(values.items ?? []),
+  } as CreateEstimateBody;
+}

package/src/lib/schemas/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Form schemas for document creation.
+ *
+ * For copy-paste usage, grab the specific schema file you need + shared.ts:
+ * - shared.ts (required) - common building blocks
+ * - invoice.ts - invoice form
+ * - credit-note.ts - credit note form
+ * - estimate.ts - estimate form
+ * - advance-invoice.ts - advance invoice form
+ */
+
+export * from "./advance-invoice";
+export * from "./credit-note";
+export * from "./estimate";
+// Document-specific schemas
+export * from "./invoice";
+// Shared building blocks
+export * from "./shared";

package/src/lib/schemas/invoice.ts

@@ -0,0 +1,43 @@
+/**
+ * Invoice form schema.
+ *
+ * Requires: ./shared.ts
+ */
+import type { CreateInvoiceBody } from "@spaceinvoices/js-sdk";
+import { z } from "zod";
+import { customerSchema, lineItemSchema, transformItemsForApi } from "./shared";
+
+export const invoiceFormSchema = z.object({
+  number: z.string().max(100).optional(),
+  date: z.string().optional(),
+  date_due: z.string().optional(),
+  customer_id: z.string().nullish(),
+  customer: customerSchema,
+  items: z.array(lineItemSchema).min(1),
+  note: z.string().nullish(),
+  payment_terms: z.string().nullish(),
+  currency_code: z.string().max(3).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  linked_documents: z.array(z.string()).optional(),
+  furs: z
+    .object({
+      business_premise_name: z.string().optional(),
+      electronic_device_name: z.string().optional(),
+      operator_tax_number: z.string().optional(),
+      operator_label: z.string().optional(),
+      skip: z.boolean().optional(),
+    })
+    .optional(),
+  eslog: z.object({ validation_enabled: z.boolean().optional() }).optional(),
+  bank_account_index: z.number().optional(),
+});
+
+export type InvoiceFormValues = z.infer<typeof invoiceFormSchema>;
+
+/** Convert form values to API request */
+export function toCreateInvoiceRequest(values: InvoiceFormValues): CreateInvoiceBody {
+  return {
+    ...values,
+    items: transformItemsForApi(values.items ?? []),
+  } as CreateInvoiceBody;
+}

package/src/lib/schemas/shared.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared form schema building blocks.
+ *
+ * These are reusable across document forms (invoice, estimate, credit note, etc.)
+ * Copy this file along with any document-specific schema you need.
+ */
+import { z } from "zod";
+
+/** Customer schema - for inline customer data on documents */
+export const customerSchema = z
+  .object({
+    name: z.string().nullish(),
+    email: z.string().email().nullish(),
+    address: z.string().nullish(),
+    address_2: z.string().nullish(),
+    post_code: z.string().nullish(),
+    city: z.string().nullish(),
+    state: z.string().nullish(),
+    country: z.string().nullish(),
+    country_code: z.string().nullish(),
+    tax_number: z.string().nullish(),
+    save_customer: z.boolean().optional(),
+  })
+  .nullish();
+
+export type CustomerFormData = z.infer<typeof customerSchema>;
+
+/** Tax schema for line items */
+export const taxSchema = z.object({
+  rate: z.number().optional(),
+  tax_id: z.string().optional(),
+  classification: z.string().optional(),
+  reverse_charge: z.boolean().optional(),
+  amount: z.number().optional(),
+});
+
+export type TaxFormData = z.infer<typeof taxSchema>;
+
+/** Discount schema for line items */
+export const discountSchema = z.object({
+  value: z.number().min(0),
+  type: z.enum(["percent", "amount"]).optional().default("percent"),
+});
+
+export type DiscountFormData = z.infer<typeof discountSchema>;
+
+/**
+ * Line item schema with UI-only is_gross_price flag.
+ *
+ * The `is_gross_price` field is UI-only - when true, the `price` field
+ * contains the gross (tax-inclusive) price and should be sent as `gross_price`
+ * to the API instead of `price`.
+ */
+export const lineItemSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().nullish(),
+  price: z.number().optional(),
+  gross_price: z.number().optional(),
+  quantity: z.number(),
+  unit: z.string().nullish(),
+  taxes: z.array(taxSchema).optional(),
+  discounts: z.array(discountSchema).max(5).optional(),
+  metadata: z.unknown().optional(),
+  /** UI-only: when true, price field contains gross (tax-inclusive) price */
+  is_gross_price: z.boolean().optional().default(false),
+});
+
+export type LineItemFormData = z.infer<typeof lineItemSchema>;
+
+/**
+ * Transform line items for API submission.
+ * Converts is_gross_price flag to proper price/gross_price fields.
+ */
+export function transformItemsForApi<T extends LineItemFormData>(items: T[]) {
+  return items.map(({ is_gross_price, price, ...item }) => ({
+    ...item,
+    ...(is_gross_price ? { gross_price: price } : { price }),
+  }));
+}

package/src/lib/translation.ts

@@ -0,0 +1,38 @@
+import { useCallback } from "react";
+
+type TranslationFunction = (key: string) => string;
+
+export type ComponentTranslationProps = {
+  t?: TranslationFunction;
+  namespace?: string;
+  locale?: string;
+  translations?: Record<string, Record<string, string>>;
+};
+
+export function createTranslation({ t, namespace, locale = "en", translations = {} }: ComponentTranslationProps = {}) {
+  return useCallback(
+    (key: string): string => {
+      // 1. If external translation function provided, use it
+      if (t) {
+        const fullKey = namespace ? `${namespace}.${key}` : key;
+        const result = t(fullKey);
+
+        // If translation found (result is not the key), return it.
+        // We check against both fullKey (standard i18next behavior) and key (in case namespace was stripped)
+        if (result !== fullKey && result !== key) {
+          return result;
+        }
+      }
+
+      // 2. Look up in local translations for current locale
+      if (locale !== "en" && translations[locale]) {
+        const translation = translations[locale][key];
+        if (translation) return translation;
+      }
+
+      // 3. Fall back to key itself (which is the English text)
+      return key;
+    },
+    [t, namespace, locale, translations],
+  );
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/providers/entities-context.tsx

@@ -0,0 +1,41 @@
+import type { GetEntities200DataItem } from "@spaceinvoices/js-sdk";
+
+import { createContext, useContext } from "react";
+
+/** Entity type with country_rules included (from getEntities response) */
+export type Entity = GetEntities200DataItem;
+
+export type EntityEnvironment = "live" | "sandbox";
+
+export type EntitiesContextType = {
+  entities: Entity[];
+  activeEntity: Entity | null;
+  setActiveEntity: (entity: Entity | null) => void;
+  environment: EntityEnvironment;
+  setEnvironment: (environment: EntityEnvironment) => void;
+  isLoading: boolean;
+  refetchEntities: () => Promise<void>;
+  isError: boolean;
+  error: Error | null;
+  status: "loading" | "error" | "success" | "pending";
+};
+
+export const EntitiesContext = createContext<EntitiesContextType | undefined>(undefined);
+
+export const useEntities = () => {
+  const context = useContext(EntitiesContext);
+  if (!context) {
+    throw new Error("useEntities must be used within an EntitiesProvider");
+  }
+  return context;
+};
+
+/** Optional version that returns undefined when outside EntitiesProvider (for public views) */
+export const useEntitiesOptional = () => {
+  return useContext(EntitiesContext);
+};
+
+export const useActiveEntity = () => {
+  const { activeEntity, setActiveEntity } = useEntities();
+  return { activeEntity, setActiveEntity };
+};

package/src/providers/entities-provider.tsx

@@ -0,0 +1,201 @@
+import { useQuery } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCookies } from "react-cookie";
+import { ACTIVE_ENTITY_COOKIE, ACTIVE_ENVIRONMENT_COOKIE } from "@/ui/components/entities/keys";
+
+import { useSDK } from "@/ui/providers/sdk-provider";
+
+import { EntitiesContext, type Entity, type EntityEnvironment } from "./entities-context";
+
+// Define a constant for the entities cache key
+export const ENTITIES_QUERY_KEY = ["entities"] as const;
+
+function LoadingFallback() {
+  return (
+    <div className="fixed inset-0 flex items-center justify-center bg-background/50">
+      <div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
+    </div>
+  );
+}
+
+type EntitiesProviderProps = {
+  children: ReactNode;
+  initialActiveEntity?: Entity | null;
+  onNoEntities?: () => void;
+};
+
+export function EntitiesProvider({ children, initialActiveEntity, onNoEntities }: EntitiesProviderProps) {
+  const { sdk, isInitialized } = useSDK();
+  const [cookies, setCookie, removeCookie] = useCookies([ACTIVE_ENTITY_COOKIE, ACTIVE_ENVIRONMENT_COOKIE]);
+  const isInitialMount = useRef(true);
+  const initialEnvironmentFromCookie = cookies[ACTIVE_ENVIRONMENT_COOKIE] as EntityEnvironment | undefined;
+  const initialEntityFromCookie = cookies[ACTIVE_ENTITY_COOKIE] as Entity | undefined;
+
+  const resolvedInitialEnvironment: EntityEnvironment =
+    initialEnvironmentFromCookie ??
+    (initialEntityFromCookie?.environment as EntityEnvironment | undefined) ??
+    (initialActiveEntity?.environment as EntityEnvironment | undefined) ??
+    "live";
+
+  const [environment, setEnvironmentState] = useState<EntityEnvironment>(resolvedInitialEnvironment);
+  const previousEnvironment = useRef(environment);
+
+  // Initialize active entity from cookie or prop that matches the selected environment
+  const [activeEntityState, setActiveEntityState] = useState<Entity | null>(() => {
+    try {
+      if (initialEntityFromCookie && initialEntityFromCookie.environment === resolvedInitialEnvironment) {
+        return initialEntityFromCookie;
+      }
+    } catch (_e) {
+      // Ignore cookie parsing errors
+    }
+
+    if (initialActiveEntity && initialActiveEntity.environment === resolvedInitialEnvironment) {
+      return initialActiveEntity;
+    }
+
+    return null;
+  });
+
+  const {
+    data: entities = [],
+    isLoading,
+    refetch,
+    isError,
+    error,
+    status,
+  } = useQuery({
+    queryKey: [...ENTITIES_QUERY_KEY, environment],
+    queryFn: async () => {
+      if (!sdk) return [];
+
+      // Pass environment to filter entities for user tokens
+      const response = await sdk.entities.list({ limit: 100, environment });
+      return response.data;
+    },
+    enabled: !!sdk && isInitialized,
+    staleTime: 1000 * 60 * 5,
+    gcTime: 1000 * 60 * 60,
+    retry: 2,
+    refetchOnMount: true,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: true,
+  });
+
+  // Redirect to add entity page when no entities exist
+  const hasCalledNoEntities = useRef(false);
+  useEffect(() => {
+    if (!isLoading && entities.length === 0 && !hasCalledNoEntities.current) {
+      hasCalledNoEntities.current = true;
+      onNoEntities?.();
+    }
+  }, [isLoading, entities.length, onNoEntities]);
+
+  // Memoize entities to prevent unnecessary re-renders
+  const memoizedEntities = useMemo(() => entities, [entities]);
+
+  useEffect(() => {
+    if (previousEnvironment.current !== environment) {
+      previousEnvironment.current = environment;
+      setActiveEntityState(null);
+    }
+  }, [environment]);
+
+  // Sync active entity when entities list changes
+  // Use ref to read current activeEntityState without causing re-runs
+  const activeEntityRef = useRef(activeEntityState);
+  activeEntityRef.current = activeEntityState;
+
+  useEffect(() => {
+    if (!memoizedEntities.length) return;
+
+    const currentActive = activeEntityRef.current;
+
+    try {
+      if (currentActive) {
+        const updatedEntity = memoizedEntities.find((entity) => entity.id === currentActive.id);
+
+        if (updatedEntity) {
+          // Always update with fresh data from the server
+          setActiveEntityState(updatedEntity);
+        } else {
+          // If active entity no longer exists, fall back to first entity
+          setActiveEntityState(memoizedEntities[0]);
+        }
+      } else {
+        setActiveEntityState(memoizedEntities[0]);
+      }
+    } catch (_e) {
+      if (memoizedEntities.length > 0) {
+        setActiveEntityState(memoizedEntities[0]);
+      }
+    } finally {
+      if (isInitialMount.current) {
+        isInitialMount.current = false;
+      }
+    }
+  }, [memoizedEntities]); // Only depend on entities list
+
+  // Update cookie when active entity changes
+  useEffect(() => {
+    if (activeEntityState) {
+      setCookie(ACTIVE_ENTITY_COOKIE, activeEntityState, {
+        path: "/",
+        maxAge: 60 * 60 * 24 * 365,
+        sameSite: "lax",
+      });
+    } else {
+      removeCookie(ACTIVE_ENTITY_COOKIE, { path: "/" });
+    }
+  }, [activeEntityState, setCookie, removeCookie]);
+
+  useEffect(() => {
+    setCookie(ACTIVE_ENVIRONMENT_COOKIE, environment, {
+      path: "/",
+      maxAge: 60 * 60 * 24 * 365,
+      sameSite: "lax",
+    });
+  }, [environment, setCookie]);
+
+  const refetchEntities = useCallback(async () => {
+    await refetch();
+  }, [refetch]);
+
+  const handleEnvironmentChange = useCallback((nextEnvironment: EntityEnvironment) => {
+    setEnvironmentState((current) => (current === nextEnvironment ? current : nextEnvironment));
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      entities: memoizedEntities,
+      activeEntity: activeEntityState,
+      setActiveEntity: setActiveEntityState,
+      environment,
+      setEnvironment: handleEnvironmentChange,
+      isLoading,
+      refetchEntities,
+      isError,
+      error,
+      status,
+    }),
+    [
+      memoizedEntities,
+      activeEntityState,
+      environment,
+      handleEnvironmentChange,
+      isLoading,
+      refetchEntities,
+      isError,
+      error,
+      status,
+    ],
+  );
+
+  // Show loading state only if entities are still loading
+  if (isLoading) {
+    return <LoadingFallback />;
+  }
+
+  return <EntitiesContext value={value}>{children}</EntitiesContext>;
+}

package/src/providers/form-footer-context.tsx

@@ -0,0 +1,72 @@
+import { createContext, type ReactNode, useContext, useEffect, useState } from "react";
+
+type SecondaryAction = {
+  label: string;
+  onClick: () => void;
+  isPending?: boolean;
+};
+
+type FormFooterState = {
+  formId: string;
+  isPending: boolean;
+  isDirty: boolean;
+  label: string;
+  onSubmit?: () => void;
+  secondaryAction?: SecondaryAction;
+};
+
+type FormFooterContextType = {
+  state: FormFooterState | null;
+  setFormFooter: (state: FormFooterState | null) => void;
+};
+
+const FormFooterContext = createContext<FormFooterContextType | undefined>(undefined);
+
+export function FormFooterProvider({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<FormFooterState | null>(null);
+
+  return <FormFooterContext.Provider value={{ state, setFormFooter: setState }}>{children}</FormFooterContext.Provider>;
+}
+
+export function useFormFooterContext() {
+  const context = useContext(FormFooterContext);
+  if (!context) {
+    throw new Error("useFormFooterContext must be used within FormFooterProvider");
+  }
+  return context;
+}
+
+type UseFormFooterRegistrationProps = {
+  formId: string;
+  isPending: boolean;
+  isDirty: boolean;
+  label: string;
+  onSubmit?: () => void;
+  secondaryAction?: SecondaryAction;
+};
+
+export function useFormFooterRegistration({
+  formId,
+  isPending,
+  isDirty,
+  label,
+  onSubmit,
+  secondaryAction,
+}: UseFormFooterRegistrationProps) {
+  const { setFormFooter } = useFormFooterContext();
+
+  useEffect(() => {
+    setFormFooter({
+      formId,
+      isPending,
+      isDirty,
+      label,
+      onSubmit,
+      secondaryAction,
+    });
+
+    return () => {
+      setFormFooter(null);
+    };
+  }, [formId, isPending, isDirty, label, onSubmit, secondaryAction, setFormFooter]);
+}