@gusto/embedded-react-sdk 0.46.2 → 0.47.0

package/dist/partner-hook-utils/collectErrors.d.ts

@@ -2,5 +2,6 @@ import { SDKError } from '../types/sdkError';
 interface QueryWithError {
     error: Error | null;
 }
+/** @internal */
 export declare function collectErrors(queries: QueryWithError[], submitError: SDKError | null): SDKError[];
 export {};

package/dist/partner-hook-utils/collectErrors.js.map

@@ -1 +1 @@
-{"version":3,"file":"collectErrors.js","sources":["../../src/partner-hook-utils/collectErrors.ts"],"sourcesContent":["import { type SDKError, normalizeToSDKError } from '@/types/sdkError'\n\ninterface QueryWithError {\n  error: Error | null\n}\n\nexport function collectErrors(queries: QueryWithError[], submitError: SDKError | null): SDKError[] {\n  const queryErrors = queries\n    .filter((q): q is QueryWithError & { error: Error } => q.error != null)\n    .map(q => normalizeToSDKError(q.error))\n\n  if (submitError) {\n    queryErrors.push(submitError)\n  }\n\n  return queryErrors\n}\n"],"names":["collectErrors","queries","submitError","queryErrors","q","normalizeToSDKError"],"mappings":";AAMO,SAASA,EAAcC,GAA2BC,GAA0C;AACjG,QAAMC,IAAcF,EACjB,OAAO,CAACG,MAA8CA,EAAE,SAAS,IAAI,EACrE,IAAI,CAAAA,MAAKC,EAAoBD,EAAE,KAAK,CAAC;AAExC,SAAIF,KACFC,EAAY,KAAKD,CAAW,GAGvBC;AACT;"}
+{"version":3,"file":"collectErrors.js","sources":["../../src/partner-hook-utils/collectErrors.ts"],"sourcesContent":["import { type SDKError, normalizeToSDKError } from '@/types/sdkError'\n\ninterface QueryWithError {\n  error: Error | null\n}\n\n/** @internal */\nexport function collectErrors(queries: QueryWithError[], submitError: SDKError | null): SDKError[] {\n  const queryErrors = queries\n    .filter((q): q is QueryWithError & { error: Error } => q.error != null)\n    .map(q => normalizeToSDKError(q.error))\n\n  if (submitError) {\n    queryErrors.push(submitError)\n  }\n\n  return queryErrors\n}\n"],"names":["collectErrors","queries","submitError","queryErrors","q","normalizeToSDKError"],"mappings":";AAOO,SAASA,EAAcC,GAA2BC,GAA0C;AACjG,QAAMC,IAAcF,EACjB,OAAO,CAACG,MAA8CA,EAAE,SAAS,IAAI,EACrE,IAAI,CAAAA,MAAKC,EAAoBD,EAAE,KAAK,CAAC;AAExC,SAAIF,KACFC,EAAY,KAAKD,CAAW,GAGvBC;AACT;"}

package/dist/partner-hook-utils/composeErrorHandler.d.ts

@@ -3,22 +3,79 @@ import { HookErrorHandling } from './types';
 import { SDKError } from '../types/sdkError';
 type QueryWithRefetch = Pick<UseQueryResult, 'error' | 'refetch'>;
 /**
- * Submit-side error state to merge with query errors. From `useBaseSubmit`, destructure
- * `{ error: submitError, setError: setSubmitError }` and pass `{ submitError, setSubmitError }`.
+ * Submit-side error state to merge into a composed {@link HookErrorHandling}.
+ *
+ * @remarks
+ * Pass to {@link composeErrorHandler} when a screen has its own submit state outside of
+ * any SDK form hook, so submit errors appear in the same error surface as query errors
+ * and can be cleared together with `clearSubmitError`.
+ *
+ * @public
  */
 export type SubmitStateForErrorHandling = {
+    /** The current submit error, or `null` when cleared. */
     submitError: SDKError | null;
+    /** Sets or clears the submit error. */
     setSubmitError: (error: SDKError | null) => void;
 };
+/**
+ * Accepted input shape for {@link composeErrorHandler}: either a React Query result
+ * (anything with `error` and `refetch`) or another SDK hook result that exposes
+ * an `errorHandling` object.
+ *
+ * @public
+ */
 export type MixedErrorSource = QueryWithRefetch | {
     errorHandling: HookErrorHandling;
 };
 /**
- * Composes `HookErrorHandling` from React Query results, optional submit state from `useBaseSubmit`,
- * and/or nested SDK hook results that expose `errorHandling`.
+ * Merges multiple error sources into a single {@link HookErrorHandling}.
+ *
+ * @remarks
+ * Accepts any mix of `@gusto/embedded-api-v-2025-11-15` React Query results and SDK hook
+ * results that already expose an `errorHandling` object (including the value returned by
+ * {@link composeSubmitHandler}). Query errors are normalized to `SDKError`, nested hook
+ * errors are flattened in, and an optional submit-state argument adds a submit error to
+ * the same list.
+ *
+ * The returned `retryQueries` refetches every failed query and delegates into each nested
+ * hook so their retries fire too. `clearSubmitError` clears the optional submit state and
+ * delegates into each nested hook.
+ *
+ * Pairs with {@link composeSubmitHandler} by name only — this composes error state and
+ * recovery, not a submit callback.
+ *
+ * @param sources - Error sources to merge. Each entry is either a React Query result or
+ *   an object with an `errorHandling` property.
+ * @param submitState - Optional screen-level submit state to fold into the result.
+ * @returns A single `HookErrorHandling` covering every source.
+ * @public
+ *
+ * @example
+ * ```tsx
+ * import { composeErrorHandler, useEmployeeDetailsForm } from '@gusto/embedded-react-sdk'
+ * import { useEmployeeFormsList } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeFormsList'
+ *
+ * function EmployeeProfileView({ companyId, employeeId }: { companyId: string; employeeId: string }) {
+ *   const employeeDetails = useEmployeeDetailsForm({ companyId, employeeId })
+ *   const formsListQuery = useEmployeeFormsList({ employeeId })
+ *
+ *   const errorHandling = composeErrorHandler([employeeDetails, formsListQuery])
+ *
+ *   if (errorHandling.errors.length > 0) {
+ *     return (
+ *       <div role="alert">
+ *         {errorHandling.errors.map((error, i) => (
+ *           <p key={i}>{error.message}</p>
+ *         ))}
+ *         <button onClick={errorHandling.retryQueries}>Retry</button>
+ *       </div>
+ *     )
+ *   }
  *
- * Pairs with `composeSubmitHandler` by name: this composes **error state and recovery**; it is not a
- * submit callback.
+ *   return null
+ * }
+ * ```
  */
 export declare function composeErrorHandler(sources: MixedErrorSource[], submitState?: SubmitStateForErrorHandling): HookErrorHandling;
 export {};

package/dist/partner-hook-utils/composeErrorHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"composeErrorHandler.js","sources":["../../src/partner-hook-utils/composeErrorHandler.ts"],"sourcesContent":["import type { UseQueryResult } from '@tanstack/react-query'\nimport { collectErrors } from './collectErrors'\nimport type { HookErrorHandling } from './types'\nimport type { SDKError } from '@/types/sdkError'\n\ntype QueryWithRefetch = Pick<UseQueryResult, 'error' | 'refetch'>\n\n/**\n * Submit-side error state to merge with query errors. From `useBaseSubmit`, destructure\n * `{ error: submitError, setError: setSubmitError }` and pass `{ submitError, setSubmitError }`.\n */\nexport type SubmitStateForErrorHandling = {\n  submitError: SDKError | null\n  setSubmitError: (error: SDKError | null) => void\n}\n\nexport type MixedErrorSource = QueryWithRefetch | { errorHandling: HookErrorHandling }\n\nfunction isHookResultWithErrorHandling(\n  source: MixedErrorSource,\n): source is { errorHandling: HookErrorHandling } {\n  return 'errorHandling' in source\n}\n\n/**\n * Composes `HookErrorHandling` from React Query results, optional submit state from `useBaseSubmit`,\n * and/or nested SDK hook results that expose `errorHandling`.\n *\n * Pairs with `composeSubmitHandler` by name: this composes **error state and recovery**; it is not a\n * submit callback.\n */\nexport function composeErrorHandler(\n  sources: MixedErrorSource[],\n  submitState?: SubmitStateForErrorHandling,\n): HookErrorHandling {\n  const queries: QueryWithRefetch[] = []\n  const errorHandlingsFromNestedHooks: HookErrorHandling[] = []\n\n  for (const source of sources) {\n    if (isHookResultWithErrorHandling(source)) {\n      errorHandlingsFromNestedHooks.push(source.errorHandling)\n    } else {\n      queries.push(source)\n    }\n  }\n\n  const nestedErrors = errorHandlingsFromNestedHooks.flatMap(handling => handling.errors)\n\n  let errors: SDKError[]\n  if (errorHandlingsFromNestedHooks.length === 0) {\n    errors = collectErrors(queries, submitState?.submitError ?? null)\n  } else {\n    const standaloneQueryErrors = collectErrors(queries, null)\n    errors = [...nestedErrors, ...standaloneQueryErrors]\n    if (submitState?.submitError) {\n      errors.push(submitState.submitError)\n    }\n  }\n\n  const retryQueries = () => {\n    for (const handling of errorHandlingsFromNestedHooks) {\n      handling.retryQueries()\n    }\n    queries.filter(q => q.error != null).forEach(q => void q.refetch())\n  }\n\n  const clearSubmitError = () => {\n    for (const handling of errorHandlingsFromNestedHooks) {\n      handling.clearSubmitError()\n    }\n    submitState?.setSubmitError(null)\n  }\n\n  return { errors, retryQueries, clearSubmitError }\n}\n"],"names":["isHookResultWithErrorHandling","source","composeErrorHandler","sources","submitState","queries","errorHandlingsFromNestedHooks","nestedErrors","handling","errors","collectErrors","standaloneQueryErrors","q"],"mappings":";AAkBA,SAASA,EACPC,GACgD;AAChD,SAAO,mBAAmBA;AAC5B;AASO,SAASC,EACdC,GACAC,GACmB;AACnB,QAAMC,IAA8B,CAAA,GAC9BC,IAAqD,CAAA;AAE3D,aAAWL,KAAUE;AACnB,IAAIH,EAA8BC,CAAM,IACtCK,EAA8B,KAAKL,EAAO,aAAa,IAEvDI,EAAQ,KAAKJ,CAAM;AAIvB,QAAMM,IAAeD,EAA8B,QAAQ,CAAAE,MAAYA,EAAS,MAAM;AAEtF,MAAIC;AACJ,MAAIH,EAA8B,WAAW;AAC3C,IAAAG,IAASC,EAAcL,GAASD,GAAa,eAAe,IAAI;AAAA,OAC3D;AACL,UAAMO,IAAwBD,EAAcL,GAAS,IAAI;AACzD,IAAAI,IAAS,CAAC,GAAGF,GAAc,GAAGI,CAAqB,GAC/CP,GAAa,eACfK,EAAO,KAAKL,EAAY,WAAW;AAAA,EAEvC;AAgBA,SAAO,EAAE,QAAAK,GAAQ,cAdI,MAAM;AACzB,eAAWD,KAAYF;AACrB,MAAAE,EAAS,aAAA;AAEX,IAAAH,EAAQ,OAAO,CAAAO,MAAKA,EAAE,SAAS,IAAI,EAAE,QAAQ,CAAAA,MAAK,KAAKA,EAAE,QAAA,CAAS;AAAA,EACpE,GAS+B,kBAPN,MAAM;AAC7B,eAAWJ,KAAYF;AACrB,MAAAE,EAAS,iBAAA;AAEX,IAAAJ,GAAa,eAAe,IAAI;AAAA,EAClC,EAE+B;AACjC;"}
+{"version":3,"file":"composeErrorHandler.js","sources":["../../src/partner-hook-utils/composeErrorHandler.ts"],"sourcesContent":["import type { UseQueryResult } from '@tanstack/react-query'\nimport { collectErrors } from './collectErrors'\nimport type { HookErrorHandling } from './types'\nimport type { SDKError } from '@/types/sdkError'\n\ntype QueryWithRefetch = Pick<UseQueryResult, 'error' | 'refetch'>\n\n/**\n * Submit-side error state to merge into a composed {@link HookErrorHandling}.\n *\n * @remarks\n * Pass to {@link composeErrorHandler} when a screen has its own submit state outside of\n * any SDK form hook, so submit errors appear in the same error surface as query errors\n * and can be cleared together with `clearSubmitError`.\n *\n * @public\n */\nexport type SubmitStateForErrorHandling = {\n  /** The current submit error, or `null` when cleared. */\n  submitError: SDKError | null\n  /** Sets or clears the submit error. */\n  setSubmitError: (error: SDKError | null) => void\n}\n\n/**\n * Accepted input shape for {@link composeErrorHandler}: either a React Query result\n * (anything with `error` and `refetch`) or another SDK hook result that exposes\n * an `errorHandling` object.\n *\n * @public\n */\nexport type MixedErrorSource = QueryWithRefetch | { errorHandling: HookErrorHandling }\n\nfunction isHookResultWithErrorHandling(\n  source: MixedErrorSource,\n): source is { errorHandling: HookErrorHandling } {\n  return 'errorHandling' in source\n}\n\n/**\n * Merges multiple error sources into a single {@link HookErrorHandling}.\n *\n * @remarks\n * Accepts any mix of `@gusto/embedded-api-v-2025-11-15` React Query results and SDK hook\n * results that already expose an `errorHandling` object (including the value returned by\n * {@link composeSubmitHandler}). Query errors are normalized to `SDKError`, nested hook\n * errors are flattened in, and an optional submit-state argument adds a submit error to\n * the same list.\n *\n * The returned `retryQueries` refetches every failed query and delegates into each nested\n * hook so their retries fire too. `clearSubmitError` clears the optional submit state and\n * delegates into each nested hook.\n *\n * Pairs with {@link composeSubmitHandler} by name only — this composes error state and\n * recovery, not a submit callback.\n *\n * @param sources - Error sources to merge. Each entry is either a React Query result or\n *   an object with an `errorHandling` property.\n * @param submitState - Optional screen-level submit state to fold into the result.\n * @returns A single `HookErrorHandling` covering every source.\n * @public\n *\n * @example\n * ```tsx\n * import { composeErrorHandler, useEmployeeDetailsForm } from '@gusto/embedded-react-sdk'\n * import { useEmployeeFormsList } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeFormsList'\n *\n * function EmployeeProfileView({ companyId, employeeId }: { companyId: string; employeeId: string }) {\n *   const employeeDetails = useEmployeeDetailsForm({ companyId, employeeId })\n *   const formsListQuery = useEmployeeFormsList({ employeeId })\n *\n *   const errorHandling = composeErrorHandler([employeeDetails, formsListQuery])\n *\n *   if (errorHandling.errors.length > 0) {\n *     return (\n *       <div role=\"alert\">\n *         {errorHandling.errors.map((error, i) => (\n *           <p key={i}>{error.message}</p>\n *         ))}\n *         <button onClick={errorHandling.retryQueries}>Retry</button>\n *       </div>\n *     )\n *   }\n *\n *   return null\n * }\n * ```\n */\nexport function composeErrorHandler(\n  sources: MixedErrorSource[],\n  submitState?: SubmitStateForErrorHandling,\n): HookErrorHandling {\n  const queries: QueryWithRefetch[] = []\n  const errorHandlingsFromNestedHooks: HookErrorHandling[] = []\n\n  for (const source of sources) {\n    if (isHookResultWithErrorHandling(source)) {\n      errorHandlingsFromNestedHooks.push(source.errorHandling)\n    } else {\n      queries.push(source)\n    }\n  }\n\n  const nestedErrors = errorHandlingsFromNestedHooks.flatMap(handling => handling.errors)\n\n  let errors: SDKError[]\n  if (errorHandlingsFromNestedHooks.length === 0) {\n    errors = collectErrors(queries, submitState?.submitError ?? null)\n  } else {\n    const standaloneQueryErrors = collectErrors(queries, null)\n    errors = [...nestedErrors, ...standaloneQueryErrors]\n    if (submitState?.submitError) {\n      errors.push(submitState.submitError)\n    }\n  }\n\n  const retryQueries = () => {\n    for (const handling of errorHandlingsFromNestedHooks) {\n      handling.retryQueries()\n    }\n    queries.filter(q => q.error != null).forEach(q => void q.refetch())\n  }\n\n  const clearSubmitError = () => {\n    for (const handling of errorHandlingsFromNestedHooks) {\n      handling.clearSubmitError()\n    }\n    submitState?.setSubmitError(null)\n  }\n\n  return { errors, retryQueries, clearSubmitError }\n}\n"],"names":["isHookResultWithErrorHandling","source","composeErrorHandler","sources","submitState","queries","errorHandlingsFromNestedHooks","nestedErrors","handling","errors","collectErrors","standaloneQueryErrors","q"],"mappings":";AAiCA,SAASA,EACPC,GACgD;AAChD,SAAO,mBAAmBA;AAC5B;AAmDO,SAASC,EACdC,GACAC,GACmB;AACnB,QAAMC,IAA8B,CAAA,GAC9BC,IAAqD,CAAA;AAE3D,aAAWL,KAAUE;AACnB,IAAIH,EAA8BC,CAAM,IACtCK,EAA8B,KAAKL,EAAO,aAAa,IAEvDI,EAAQ,KAAKJ,CAAM;AAIvB,QAAMM,IAAeD,EAA8B,QAAQ,CAAAE,MAAYA,EAAS,MAAM;AAEtF,MAAIC;AACJ,MAAIH,EAA8B,WAAW;AAC3C,IAAAG,IAASC,EAAcL,GAASD,GAAa,eAAe,IAAI;AAAA,OAC3D;AACL,UAAMO,IAAwBD,EAAcL,GAAS,IAAI;AACzD,IAAAI,IAAS,CAAC,GAAGF,GAAc,GAAGI,CAAqB,GAC/CP,GAAa,eACfK,EAAO,KAAKL,EAAY,WAAW;AAAA,EAEvC;AAgBA,SAAO,EAAE,QAAAK,GAAQ,cAdI,MAAM;AACzB,eAAWD,KAAYF;AACrB,MAAAE,EAAS,aAAA;AAEX,IAAAH,EAAQ,OAAO,CAAAO,MAAKA,EAAE,SAAS,IAAI,EAAE,QAAQ,CAAAA,MAAK,KAAKA,EAAE,QAAA,CAAS;AAAA,EACpE,GAS+B,kBAPN,MAAM;AAC7B,eAAWJ,KAAYF;AACrB,MAAAE,EAAS,iBAAA;AAEX,IAAAJ,GAAa,eAAe,IAAI;AAAA,EAClC,EAE+B;AACjC;"}

package/dist/partner-hook-utils/form/FormFieldsMetadataContext.d.ts

@@ -1,8 +1,26 @@
 import { FieldsMetadata } from '../types';
 import { SDKError } from '../../types/sdkError';
+/**
+ * Value published by {@link FormFieldsMetadataProvider} to descendant hook fields.
+ *
+ * @internal
+ */
 export interface FormFieldsMetadataContextValue {
     metadata: FieldsMetadata;
     errors: SDKError[];
 }
+/**
+ * React context that carries form field metadata and current error state down to
+ * descendant hook fields rendered inside an SDK form provider.
+ *
+ * @internal
+ */
 export declare const FormFieldsMetadataContext: import('react').Context<FormFieldsMetadataContextValue | null>;
+/**
+ * Reads the nearest {@link FormFieldsMetadataContext} value, or `null` when no
+ * provider is mounted above.
+ *
+ * @returns The provider value when one is mounted, otherwise `null`.
+ * @internal
+ */
 export declare function useFormFieldsMetadataContext(): FormFieldsMetadataContextValue | null;

package/dist/partner-hook-utils/form/FormFieldsMetadataContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"FormFieldsMetadataContext.js","sources":["../../../src/partner-hook-utils/form/FormFieldsMetadataContext.ts"],"sourcesContent":["import { createContext, useContext } from 'react'\nimport type { FieldsMetadata } from '../types'\nimport type { SDKError } from '@/types/sdkError'\n\nexport interface FormFieldsMetadataContextValue {\n  metadata: FieldsMetadata\n  errors: SDKError[]\n}\n\nexport const FormFieldsMetadataContext = createContext<FormFieldsMetadataContextValue | null>(null)\n\nexport function useFormFieldsMetadataContext(): FormFieldsMetadataContextValue | null {\n  return useContext(FormFieldsMetadataContext)\n}\n"],"names":["FormFieldsMetadataContext","createContext","useFormFieldsMetadataContext","useContext"],"mappings":";AASO,MAAMA,IAA4BC,EAAqD,IAAI;AAE3F,SAASC,IAAsE;AACpF,SAAOC,EAAWH,CAAyB;AAC7C;"}
+{"version":3,"file":"FormFieldsMetadataContext.js","sources":["../../../src/partner-hook-utils/form/FormFieldsMetadataContext.ts"],"sourcesContent":["import { createContext, useContext } from 'react'\nimport type { FieldsMetadata } from '../types'\nimport type { SDKError } from '@/types/sdkError'\n\n/**\n * Value published by {@link FormFieldsMetadataProvider} to descendant hook fields.\n *\n * @internal\n */\nexport interface FormFieldsMetadataContextValue {\n  metadata: FieldsMetadata\n  errors: SDKError[]\n}\n\n/**\n * React context that carries form field metadata and current error state down to\n * descendant hook fields rendered inside an SDK form provider.\n *\n * @internal\n */\nexport const FormFieldsMetadataContext = createContext<FormFieldsMetadataContextValue | null>(null)\n\n/**\n * Reads the nearest {@link FormFieldsMetadataContext} value, or `null` when no\n * provider is mounted above.\n *\n * @returns The provider value when one is mounted, otherwise `null`.\n * @internal\n */\nexport function useFormFieldsMetadataContext(): FormFieldsMetadataContextValue | null {\n  return useContext(FormFieldsMetadataContext)\n}\n"],"names":["FormFieldsMetadataContext","createContext","useFormFieldsMetadataContext","useContext"],"mappings":";AAoBO,MAAMA,IAA4BC,EAAqD,IAAI;AAS3F,SAASC,IAAsE;AACpF,SAAOC,EAAWH,CAAyB;AAC7C;"}

package/dist/partner-hook-utils/form/FormFieldsMetadataProvider.d.ts

@@ -6,5 +6,12 @@ interface FormFieldsMetadataProviderProps {
     errors: SDKError[];
     children: ReactNode;
 }
-export declare function FormFieldsMetadataProvider({ metadata, errors, children, }: FormFieldsMetadataProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Publishes field metadata and current form errors via {@link FormFieldsMetadataContext}
+ * so descendant hook fields can resolve their requiredness, options, and inline
+ * error messages without prop drilling.
+ *
+ * @internal
+ */
+export declare function FormFieldsMetadataProvider({ metadata, errors, children, }: FormFieldsMetadataProviderProps): import("react").JSX.Element;
 export {};

package/dist/partner-hook-utils/form/FormFieldsMetadataProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"FormFieldsMetadataProvider.js","sources":["../../../src/partner-hook-utils/form/FormFieldsMetadataProvider.tsx"],"sourcesContent":["import type { ReactNode } from 'react'\nimport type { FieldMetadata, FieldMetadataWithOptions } from '../types'\nimport { FormFieldsMetadataContext } from './FormFieldsMetadataContext'\nimport type { SDKError } from '@/types/sdkError'\n\ninterface FormFieldsMetadataProviderProps {\n  metadata: Record<string, FieldMetadata | FieldMetadataWithOptions>\n  errors: SDKError[]\n  children: ReactNode\n}\n\nexport function FormFieldsMetadataProvider({\n  metadata,\n  errors,\n  children,\n}: FormFieldsMetadataProviderProps) {\n  return (\n    <FormFieldsMetadataContext.Provider value={{ metadata, errors }}>\n      {children}\n    </FormFieldsMetadataContext.Provider>\n  )\n}\n"],"names":["FormFieldsMetadataProvider","metadata","errors","children","jsx","FormFieldsMetadataContext"],"mappings":";;AAWO,SAASA,EAA2B;AAAA,EACzC,UAAAC;AAAA,EACA,QAAAC;AAAA,EACA,UAAAC;AACF,GAAoC;AAClC,SACE,gBAAAC,EAACC,EAA0B,UAA1B,EAAmC,OAAO,EAAE,UAAAJ,GAAU,QAAAC,KACpD,UAAAC,GACH;AAEJ;"}
+{"version":3,"file":"FormFieldsMetadataProvider.js","sources":["../../../src/partner-hook-utils/form/FormFieldsMetadataProvider.tsx"],"sourcesContent":["import type { ReactNode } from 'react'\nimport type { FieldMetadata, FieldMetadataWithOptions } from '../types'\nimport { FormFieldsMetadataContext } from './FormFieldsMetadataContext'\nimport type { SDKError } from '@/types/sdkError'\n\ninterface FormFieldsMetadataProviderProps {\n  metadata: Record<string, FieldMetadata | FieldMetadataWithOptions>\n  errors: SDKError[]\n  children: ReactNode\n}\n\n/**\n * Publishes field metadata and current form errors via {@link FormFieldsMetadataContext}\n * so descendant hook fields can resolve their requiredness, options, and inline\n * error messages without prop drilling.\n *\n * @internal\n */\nexport function FormFieldsMetadataProvider({\n  metadata,\n  errors,\n  children,\n}: FormFieldsMetadataProviderProps) {\n  return (\n    <FormFieldsMetadataContext.Provider value={{ metadata, errors }}>\n      {children}\n    </FormFieldsMetadataContext.Provider>\n  )\n}\n"],"names":["FormFieldsMetadataProvider","metadata","errors","children","jsx","FormFieldsMetadataContext"],"mappings":";;AAkBO,SAASA,EAA2B;AAAA,EACzC,UAAAC;AAAA,EACA,QAAAC;AAAA,EACA,UAAAC;AACF,GAAoC;AAClC,SACE,gBAAAC,EAACC,EAA0B,UAA1B,EAAmC,OAAO,EAAE,UAAAJ,GAAU,QAAAC,KACpD,UAAAC,GACH;AAEJ;"}

package/dist/partner-hook-utils/form/SDKFormProvider.d.ts

@@ -16,7 +16,35 @@ interface SDKFormProviderProps<TFormData extends FieldValues = FieldValues, TFie
     };
     children: ReactNode;
 }
+/**
+ * Provides form context to field components so they can read metadata, control,
+ * and error state without an explicit `formHookResult` prop on each field.
+ * Server-side field errors are automatically synced onto their corresponding fields.
+ *
+ * @public
+ *
+ * @example
+ * ```tsx
+ * const formHookResult = useEmployeeDetailsForm({ employeeId })
+ * const { Fields } = formHookResult.form
+ *
+ * // SDKFormProvider supplies context only — wire up submission and render the
+ * // <form> element yourself.
+ * const handleSubmit = () =>
+ *   formHookResult.actions.onSubmit({ onEmployeeUpdated: (emp) => { ... } })
+ *
+ * return (
+ *   <SDKFormProvider formHookResult={formHookResult}>
+ *     <form onSubmit={handleSubmit}>
+ *       <Fields.FirstName label="First name" />
+ *       <Fields.LastName label="Last name" />
+ *       <button type="submit">Save</button>
+ *     </form>
+ *   </SDKFormProvider>
+ * )
+ * ```
+ */
 export declare function SDKFormProvider<TFormData extends FieldValues = FieldValues, TFieldsMetadata extends {
     [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions;
-} = Record<string, FieldMetadata | FieldMetadataWithOptions>>({ formHookResult, children }: SDKFormProviderProps<TFormData, TFieldsMetadata>): import("react/jsx-runtime").JSX.Element;
+} = Record<string, FieldMetadata | FieldMetadataWithOptions>>({ formHookResult, children }: SDKFormProviderProps<TFormData, TFieldsMetadata>): import("react").JSX.Element;
 export {};

package/dist/partner-hook-utils/form/SDKFormProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"SDKFormProvider.js","sources":["../../../src/partner-hook-utils/form/SDKFormProvider.tsx"],"sourcesContent":["import { type ReactNode, useEffect } from 'react'\nimport type { FieldPath, FieldValues } from 'react-hook-form'\nimport { FormProvider } from 'react-hook-form'\nimport type { FieldMetadata, FieldMetadataWithOptions, HookFormInternals } from '../types'\nimport { FormFieldsMetadataProvider } from './FormFieldsMetadataProvider'\nimport { FieldElementRegistryProvider } from '@/components/Common/Fields/hooks/FieldElementRegistryProvider'\nimport { normalizeErrorKeyForForm } from '@/helpers/formattedStrings'\nimport type { SDKError, SDKFieldError } from '@/types/sdkError'\n\nfunction useSyncFieldErrors<\n  TFormData extends FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  },\n>(\n  fieldErrors: SDKFieldError[],\n  form: {\n    fieldsMetadata: TFieldsMetadata\n    hookFormInternals: HookFormInternals<TFormData>\n  },\n) {\n  const { fieldsMetadata } = form\n  const { setError } = form.hookFormInternals.formMethods\n\n  useEffect(() => {\n    if (!fieldErrors.length) return\n    const knownFields = new Set(Object.keys(fieldsMetadata))\n    for (const fieldError of fieldErrors) {\n      const normalizedField = normalizeErrorKeyForForm(fieldError.field)\n      if (knownFields.has(normalizedField)) {\n        setError(normalizedField as FieldPath<TFormData>, {\n          type: 'custom',\n          message: fieldError.message,\n        })\n      }\n    }\n  }, [fieldErrors, setError, fieldsMetadata])\n}\n\ninterface SDKFormProviderProps<\n  TFormData extends FieldValues = FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  } = Record<string, FieldMetadata | FieldMetadataWithOptions>,\n> {\n  formHookResult: {\n    errorHandling: { errors: SDKError[] }\n    form: {\n      fieldsMetadata: TFieldsMetadata\n      hookFormInternals: HookFormInternals<TFormData>\n    }\n  }\n  children: ReactNode\n}\n\nexport function SDKFormProvider<\n  TFormData extends FieldValues = FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  } = Record<string, FieldMetadata | FieldMetadataWithOptions>,\n>({ formHookResult, children }: SDKFormProviderProps<TFormData, TFieldsMetadata>) {\n  const { errorHandling, form } = formHookResult\n  const allFieldErrors = errorHandling.errors.flatMap(e => e.fieldErrors)\n  useSyncFieldErrors(allFieldErrors, form)\n\n  return (\n    <FormFieldsMetadataProvider metadata={form.fieldsMetadata} errors={errorHandling.errors}>\n      <FieldElementRegistryProvider registry={form.hookFormInternals._fieldElementRegistry}>\n        <FormProvider {...form.hookFormInternals.formMethods}>{children}</FormProvider>\n      </FieldElementRegistryProvider>\n    </FormFieldsMetadataProvider>\n  )\n}\n"],"names":["useSyncFieldErrors","fieldErrors","form","fieldsMetadata","setError","useEffect","knownFields","fieldError","normalizedField","normalizeErrorKeyForForm","SDKFormProvider","formHookResult","children","errorHandling","allFieldErrors","e","jsx","FormFieldsMetadataProvider","FieldElementRegistryProvider","FormProvider"],"mappings":";;;;;;AASA,SAASA,EAMPC,GACAC,GAIA;AACA,QAAM,EAAE,gBAAAC,MAAmBD,GACrB,EAAE,UAAAE,EAAA,IAAaF,EAAK,kBAAkB;AAE5C,EAAAG,EAAU,MAAM;AACd,QAAI,CAACJ,EAAY,OAAQ;AACzB,UAAMK,IAAc,IAAI,IAAI,OAAO,KAAKH,CAAc,CAAC;AACvD,eAAWI,KAAcN,GAAa;AACpC,YAAMO,IAAkBC,EAAyBF,EAAW,KAAK;AACjE,MAAID,EAAY,IAAIE,CAAe,KACjCJ,EAASI,GAAyC;AAAA,QAChD,MAAM;AAAA,QACN,SAASD,EAAW;AAAA,MAAA,CACrB;AAAA,IAEL;AAAA,EACF,GAAG,CAACN,GAAaG,GAAUD,CAAc,CAAC;AAC5C;AAkBO,SAASO,EAKd,EAAE,gBAAAC,GAAgB,UAAAC,KAA8D;AAChF,QAAM,EAAE,eAAAC,GAAe,MAAAX,EAAA,IAASS,GAC1BG,IAAiBD,EAAc,OAAO,QAAQ,CAAAE,MAAKA,EAAE,WAAW;AACtE,SAAAf,EAAmBc,GAAgBZ,CAAI,GAGrC,gBAAAc,EAACC,KAA2B,UAAUf,EAAK,gBAAgB,QAAQW,EAAc,QAC/E,UAAA,gBAAAG,EAACE,GAAA,EAA6B,UAAUhB,EAAK,kBAAkB,uBAC7D,4BAACiB,GAAA,EAAc,GAAGjB,EAAK,kBAAkB,aAAc,UAAAU,EAAA,CAAS,EAAA,CAClE,EAAA,CACF;AAEJ;"}
+{"version":3,"file":"SDKFormProvider.js","sources":["../../../src/partner-hook-utils/form/SDKFormProvider.tsx"],"sourcesContent":["import { type ReactNode, useEffect } from 'react'\nimport type { FieldPath, FieldValues } from 'react-hook-form'\nimport { FormProvider } from 'react-hook-form'\nimport type { FieldMetadata, FieldMetadataWithOptions, HookFormInternals } from '../types'\nimport { FormFieldsMetadataProvider } from './FormFieldsMetadataProvider'\nimport { FieldElementRegistryProvider } from '@/components/Common/Fields/hooks/FieldElementRegistryProvider'\nimport { normalizeErrorKeyForForm } from '@/helpers/formattedStrings'\nimport type { SDKError, SDKFieldError } from '@/types/sdkError'\n\nfunction useSyncFieldErrors<\n  TFormData extends FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  },\n>(\n  fieldErrors: SDKFieldError[],\n  form: {\n    fieldsMetadata: TFieldsMetadata\n    hookFormInternals: HookFormInternals<TFormData>\n  },\n) {\n  const { fieldsMetadata } = form\n  const { setError } = form.hookFormInternals.formMethods\n\n  useEffect(() => {\n    if (!fieldErrors.length) return\n    const knownFields = new Set(Object.keys(fieldsMetadata))\n    for (const fieldError of fieldErrors) {\n      const normalizedField = normalizeErrorKeyForForm(fieldError.field)\n      if (knownFields.has(normalizedField)) {\n        setError(normalizedField as FieldPath<TFormData>, {\n          type: 'custom',\n          message: fieldError.message,\n        })\n      }\n    }\n  }, [fieldErrors, setError, fieldsMetadata])\n}\n\ninterface SDKFormProviderProps<\n  TFormData extends FieldValues = FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  } = Record<string, FieldMetadata | FieldMetadataWithOptions>,\n> {\n  formHookResult: {\n    errorHandling: { errors: SDKError[] }\n    form: {\n      fieldsMetadata: TFieldsMetadata\n      hookFormInternals: HookFormInternals<TFormData>\n    }\n  }\n  children: ReactNode\n}\n\n/**\n * Provides form context to field components so they can read metadata, control,\n * and error state without an explicit `formHookResult` prop on each field.\n * Server-side field errors are automatically synced onto their corresponding fields.\n *\n * @public\n *\n * @example\n * ```tsx\n * const formHookResult = useEmployeeDetailsForm({ employeeId })\n * const { Fields } = formHookResult.form\n *\n * // SDKFormProvider supplies context only — wire up submission and render the\n * // <form> element yourself.\n * const handleSubmit = () =>\n *   formHookResult.actions.onSubmit({ onEmployeeUpdated: (emp) => { ... } })\n *\n * return (\n *   <SDKFormProvider formHookResult={formHookResult}>\n *     <form onSubmit={handleSubmit}>\n *       <Fields.FirstName label=\"First name\" />\n *       <Fields.LastName label=\"Last name\" />\n *       <button type=\"submit\">Save</button>\n *     </form>\n *   </SDKFormProvider>\n * )\n * ```\n */\nexport function SDKFormProvider<\n  TFormData extends FieldValues = FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  } = Record<string, FieldMetadata | FieldMetadataWithOptions>,\n>({ formHookResult, children }: SDKFormProviderProps<TFormData, TFieldsMetadata>) {\n  const { errorHandling, form } = formHookResult\n  const allFieldErrors = errorHandling.errors.flatMap(e => e.fieldErrors)\n  useSyncFieldErrors(allFieldErrors, form)\n\n  return (\n    <FormFieldsMetadataProvider metadata={form.fieldsMetadata} errors={errorHandling.errors}>\n      <FieldElementRegistryProvider registry={form.hookFormInternals._fieldElementRegistry}>\n        <FormProvider {...form.hookFormInternals.formMethods}>{children}</FormProvider>\n      </FieldElementRegistryProvider>\n    </FormFieldsMetadataProvider>\n  )\n}\n"],"names":["useSyncFieldErrors","fieldErrors","form","fieldsMetadata","setError","useEffect","knownFields","fieldError","normalizedField","normalizeErrorKeyForForm","SDKFormProvider","formHookResult","children","errorHandling","allFieldErrors","e","jsx","FormFieldsMetadataProvider","FieldElementRegistryProvider","FormProvider"],"mappings":";;;;;;AASA,SAASA,EAMPC,GACAC,GAIA;AACA,QAAM,EAAE,gBAAAC,MAAmBD,GACrB,EAAE,UAAAE,EAAA,IAAaF,EAAK,kBAAkB;AAE5C,EAAAG,EAAU,MAAM;AACd,QAAI,CAACJ,EAAY,OAAQ;AACzB,UAAMK,IAAc,IAAI,IAAI,OAAO,KAAKH,CAAc,CAAC;AACvD,eAAWI,KAAcN,GAAa;AACpC,YAAMO,IAAkBC,EAAyBF,EAAW,KAAK;AACjE,MAAID,EAAY,IAAIE,CAAe,KACjCJ,EAASI,GAAyC;AAAA,QAChD,MAAM;AAAA,QACN,SAASD,EAAW;AAAA,MAAA,CACrB;AAAA,IAEL;AAAA,EACF,GAAG,CAACN,GAAaG,GAAUD,CAAc,CAAC;AAC5C;AA8CO,SAASO,EAKd,EAAE,gBAAAC,GAAgB,UAAAC,KAA8D;AAChF,QAAM,EAAE,eAAAC,GAAe,MAAAX,EAAA,IAASS,GAC1BG,IAAiBD,EAAc,OAAO,QAAQ,CAAAE,MAAKA,EAAE,WAAW;AACtE,SAAAf,EAAmBc,GAAgBZ,CAAI,GAGrC,gBAAAc,EAACC,KAA2B,UAAUf,EAAK,gBAAgB,QAAQW,EAAc,QAC/E,UAAA,gBAAAG,EAACE,GAAA,EAA6B,UAAUhB,EAAK,kBAAkB,uBAC7D,4BAACiB,GAAA,EAAc,GAAGjB,EAAK,kBAAkB,aAAc,UAAAU,EAAA,CAAS,EAAA,CAClE,EAAA,CACF;AAEJ;"}

package/dist/partner-hook-utils/form/buildFormSchema.d.ts

@@ -1,7 +1,28 @@
 import { z } from 'zod';
 import { FieldMetadata } from '../types';
-export type FormMode = 'create' | 'update';
-export type RequiredFieldRule<TData = Record<string, unknown>> = 'create' | 'update' | 'always' | 'never' | ((data: TData, mode: FormMode) => boolean);
+/**
+ * Form lifecycle mode used to vary requiredness and validation rules.
+ *
+ * @internal
+ */
+type FormMode = 'create' | 'update';
+/**
+ * Per-field requiredness rule.
+ *
+ * String values apply requiredness in a fixed mode (`'always'`, `'create'`,
+ * `'update'`, or `'never'`). A function form receives the current form data
+ * and mode so requiredness can depend on other field values at runtime.
+ *
+ * @typeParam TData - The shape of the form data passed to predicate rules.
+ * @internal
+ */
+type RequiredFieldRule<TData = Record<string, unknown>> = 'create' | 'update' | 'always' | 'never' | ((data: TData, mode: FormMode) => boolean);
+/**
+ * Mapping from each field name in a schema to its {@link RequiredFieldRule}.
+ *
+ * @typeParam TSchema - The map of field names to their Zod validators.
+ * @internal
+ */
 export type RequiredFieldConfig<TSchema extends Record<string, z.ZodType>> = Partial<{
     [K in keyof TSchema & string]: RequiredFieldRule<{
         [F in keyof TSchema]: z.infer<TSchema[F]>;
@@ -13,6 +34,16 @@ type OptionalOnCreate<TConfig> = {
 type OptionalOnUpdate<TConfig> = {
     [K in keyof TConfig & string]: TConfig[K] extends 'create' | 'never' ? K : never;
 }[keyof TConfig & string];
+/**
+ * Per-mode list of optional fields a caller can promote to required.
+ *
+ * Only fields whose base rule allows the override appear in the `create` /
+ * `update` arrays — fields that are already required in a given mode are
+ * excluded from that mode's list at the type level.
+ *
+ * @typeParam TConfig - The {@link RequiredFieldConfig} that constrains which fields are eligible.
+ * @internal
+ */
 export type OptionalFieldsToRequire<TConfig> = {
     create?: Array<OptionalOnCreate<TConfig>>;
     update?: Array<OptionalOnUpdate<TConfig>>;
@@ -32,6 +63,13 @@ interface BuildFormSchemaOptions<T extends Record<string, z.ZodType>, TConfig ex
         [K in keyof T]: z.infer<T[K]>;
     }, ctx: z.RefinementCtx) => void;
 }
+/**
+ * Companion config returned alongside a built schema, used to derive per-field
+ * metadata and to identify which form values predicate-based rules depend on.
+ *
+ * @typeParam T - The map of field names to their Zod validators.
+ * @internal
+ */
 export interface FieldsMetadataConfig<T extends Record<string, z.ZodType>> {
     getFieldsMetadata: (data?: Record<string, unknown>) => Record<keyof T, FieldMetadata>;
     /** Form field names that predicate-based requiredness rules read at runtime. */
@@ -40,9 +78,39 @@ export interface FieldsMetadataConfig<T extends Record<string, z.ZodType>> {
 type FormDataFromValidators<T extends Record<string, z.ZodType>> = {
     [K in keyof T]: z.infer<T[K]>;
 };
+/**
+ * Tuple returned by {@link buildFormSchema}: the composed Zod schema followed
+ * by its {@link FieldsMetadataConfig}.
+ *
+ * @typeParam T - The map of field names to their Zod validators.
+ * @internal
+ */
 export type BuildFormSchemaResult<T extends Record<string, z.ZodType>> = [
     schema: z.ZodType<FormDataFromValidators<T>, FormDataFromValidators<T>>,
     metadataConfig: FieldsMetadataConfig<T>
 ];
+/**
+ * Composes a Zod object schema and matching metadata config from a map of
+ * per-field validators, applying mode-aware requiredness rules.
+ *
+ * @remarks
+ * Every field is wrapped to coerce empty strings, `null`, `undefined`, and
+ * `NaN` to `undefined` before validation, so blank inputs surface as missing
+ * rather than as type-mismatch errors. Required-field checks run in a
+ * `superRefine` pass that emits an issue keyed by `requiredErrorCode` (defaults
+ * to `REQUIRED`) for each unfilled required field.
+ *
+ * Fields listed in `fieldsWithRedactedValues` remain in the schema for format
+ * validation and appear in metadata with `hasRedactedValue: true`, but are
+ * exempt from required-field validation because a server-side value already
+ * exists.
+ *
+ * @typeParam T - The map of field names to their Zod validators.
+ * @typeParam TConfig - The shape of the requiredness configuration.
+ * @param fieldValidators - Map from field name to the validator that runs when a value is present.
+ * @param options - Mode, required-field config, redaction list, and optional `superRefine`.
+ * @returns A {@link BuildFormSchemaResult} tuple: the schema and its metadata config.
+ * @internal
+ */
 export declare function buildFormSchema<T extends Record<string, z.ZodType>, TConfig extends RequiredFieldConfig<T>>(fieldValidators: T, options: BuildFormSchemaOptions<T, TConfig>): BuildFormSchemaResult<T>;
 export {};

package/dist/partner-hook-utils/form/buildFormSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"buildFormSchema.js","sources":["../../../src/partner-hook-utils/form/buildFormSchema.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { FieldMetadata } from '../types'\n\n// ── Types ────────────────────────────────────────────────────────────\n\nexport type FormMode = 'create' | 'update'\n\nexport type RequiredFieldRule<TData = Record<string, unknown>> =\n  | 'create'\n  | 'update'\n  | 'always'\n  | 'never'\n  | ((data: TData, mode: FormMode) => boolean)\n\nexport type RequiredFieldConfig<TSchema extends Record<string, z.ZodType>> = Partial<{\n  [K in keyof TSchema & string]: RequiredFieldRule<{\n    [F in keyof TSchema]: z.infer<TSchema[F]>\n  }>\n}>\n\ntype OptionalOnCreate<TConfig> = {\n  [K in keyof TConfig & string]: TConfig[K] extends 'update' | 'never' ? K : never\n}[keyof TConfig & string]\n\ntype OptionalOnUpdate<TConfig> = {\n  [K in keyof TConfig & string]: TConfig[K] extends 'create' | 'never' ? K : never\n}[keyof TConfig & string]\n\nexport type OptionalFieldsToRequire<TConfig> = {\n  create?: Array<OptionalOnCreate<TConfig>>\n  update?: Array<OptionalOnUpdate<TConfig>>\n}\n\n// ── buildFormSchema ──────────────────────────────────────────────────\n\ninterface BuildFormSchemaOptions<\n  T extends Record<string, z.ZodType>,\n  TConfig extends RequiredFieldConfig<T>,\n> {\n  requiredFieldsConfig?: TConfig\n  requiredErrorCode?: string\n  mode: FormMode\n  optionalFieldsToRequire?: OptionalFieldsToRequire<TConfig>\n  excludeFields?: Array<keyof T & string>\n  /** Fields with existing server-side values that are redacted in the API response\n   *  (e.g. SSN, EIN). These fields remain in the schema for format validation and\n   *  appear in metadata (with `hasRedactedValue: true`) but are exempt from required\n   *  validation — an empty submission is valid because a value already exists. */\n  fieldsWithRedactedValues?: Array<keyof T & string>\n  superRefine?: (data: { [K in keyof T]: z.infer<T[K]> }, ctx: z.RefinementCtx) => void\n}\n\nexport interface FieldsMetadataConfig<T extends Record<string, z.ZodType>> {\n  getFieldsMetadata: (data?: Record<string, unknown>) => Record<keyof T, FieldMetadata>\n  /** Form field names that predicate-based requiredness rules read at runtime. */\n  predicateDeps: string[]\n}\n\ntype FormDataFromValidators<T extends Record<string, z.ZodType>> = {\n  [K in keyof T]: z.infer<T[K]>\n}\n\nexport type BuildFormSchemaResult<T extends Record<string, z.ZodType>> = [\n  schema: z.ZodType<FormDataFromValidators<T>, FormDataFromValidators<T>>,\n  metadataConfig: FieldsMetadataConfig<T>,\n]\n\nexport function buildFormSchema<\n  T extends Record<string, z.ZodType>,\n  TConfig extends RequiredFieldConfig<T>,\n>(fieldValidators: T, options: BuildFormSchemaOptions<T, TConfig>): BuildFormSchemaResult<T> {\n  const {\n    mode,\n    requiredFieldsConfig = {} as Record<string, RequiredFieldRule>,\n    requiredErrorCode = 'REQUIRED',\n    excludeFields = [],\n  } = options\n  const excluded = new Set(excludeFields.map(String))\n  const redacted = new Set((options.fieldsWithRedactedValues ?? []).map(String))\n  const partnerRequired = new Set(\n    resolveOptionalFieldsToRequire(options.optionalFieldsToRequire, mode),\n  )\n\n  const shape: Record<string, z.ZodType> = {}\n  const dynamicRequired: Array<{\n    name: string\n    predicate: (data: Record<string, unknown>, mode: FormMode) => boolean\n  }> = []\n  const includedFieldNames: string[] = []\n  const config = requiredFieldsConfig as Record<string, RequiredFieldRule>\n\n  for (const [name, validator] of Object.entries(fieldValidators)) {\n    if (excluded.has(name)) continue\n    includedFieldNames.push(name)\n\n    const effectiveRule = config[name] ?? 'always'\n\n    shape[name] = makeOptional(validator)\n\n    if (!redacted.has(name)) {\n      const isPartnerRequired = partnerRequired.has(name)\n\n      if (typeof effectiveRule === 'function') {\n        dynamicRequired.push({\n          name,\n          predicate: isPartnerRequired ? () => true : effectiveRule,\n        })\n      } else {\n        const isRequired = effectiveRule === 'always' || effectiveRule === mode || isPartnerRequired\n        if (isRequired) {\n          dynamicRequired.push({ name, predicate: () => true })\n        }\n      }\n    }\n  }\n\n  const hasSuperRefine = dynamicRequired.length > 0 || options.superRefine\n  let schema: z.ZodType = z.object(shape)\n\n  if (hasSuperRefine) {\n    schema = (schema as z.ZodObject).superRefine(\n      (data: Record<string, unknown>, ctx: z.RefinementCtx) => {\n        for (const { name, predicate } of dynamicRequired) {\n          if (predicate(data, mode) && isEmpty(data[name])) {\n            ctx.addIssue({\n              code: z.ZodIssueCode.custom,\n              path: [name],\n              message: requiredErrorCode,\n            })\n          }\n        }\n\n        options.superRefine?.(data as { [K in keyof T]: z.infer<T[K]> }, ctx)\n      },\n    )\n  }\n\n  const predicateDeps = detectPredicateDeps(dynamicRequired, mode)\n\n  function getFieldsMetadata(data?: Record<string, unknown>) {\n    const metadata: Record<string, FieldMetadata> = {}\n\n    for (const name of includedFieldNames) {\n      const effectiveRule = config[name] ?? 'always'\n\n      if (partnerRequired.has(name)) {\n        metadata[name] = { name, isRequired: true }\n      } else if (typeof effectiveRule === 'function') {\n        metadata[name] = { name, isRequired: data ? effectiveRule(data, mode) : false }\n      } else {\n        metadata[name] = {\n          name,\n          isRequired: effectiveRule === 'always' || effectiveRule === mode,\n        }\n      }\n\n      if (redacted.has(name)) {\n        metadata[name].hasRedactedValue = true\n      }\n    }\n\n    return metadata as Record<keyof T, FieldMetadata>\n  }\n\n  // makeOptional wraps fields with z.preprocess, which causes z.input to infer\n  // `unknown`. Cast the schema to carry the original field types so zodResolver\n  // infers correct form data types — consumers don't need per-hook casts.\n  return [\n    schema as z.ZodType<FormDataFromValidators<T>, FormDataFromValidators<T>>,\n    { getFieldsMetadata, predicateDeps },\n  ]\n}\n\n// ── Internal helpers ─────────────────────────────────────────────────\n\nfunction resolveOptionalFieldsToRequire<TConfig>(\n  value: OptionalFieldsToRequire<TConfig> | undefined,\n  mode: FormMode,\n): string[] {\n  if (!value) return []\n  return ((mode === 'create' ? value.create : value.update) ?? []) as string[]\n}\n\nfunction makeOptional(validator: z.ZodType): z.ZodType {\n  return z.preprocess(v => (isEmpty(v) ? undefined : v), validator.optional())\n}\n\nfunction isEmpty(value: unknown): boolean {\n  if (value === undefined || value === null) return true\n  if (typeof value === 'string' && value.trim() === '') return true\n  if (typeof value === 'number' && Number.isNaN(value)) return true\n  return false\n}\n\n/**\n * Determines which form field names are read by predicate-based requiredness\n * rules. This enables `useDeriveFieldsMetadata` to watch only the specific\n * fields that predicates depend on, rather than subscribing to every form\n * value change (which defeats react-hook-form's per-field render optimization).\n *\n * Works by running each predicate against a recording Proxy. The Proxy\n * intercepts property access and logs the keys, giving us the dependency list\n * without requiring manual declaration.\n *\n * Limitation: JavaScript short-circuit evaluation (`a && b`) can prevent the\n * Proxy from seeing later operands when earlier ones are falsy. In practice\n * this is acceptable — our predicate rules read a single form value each\n * (e.g. `data => data.adjustForMinimumWage`). Multi-field predicates with\n * equality guards should be expressed as `superRefine` rules instead.\n */\nfunction detectPredicateDeps(\n  dynamicRequired: Array<{\n    name: string\n    predicate: (data: Record<string, unknown>, mode: FormMode) => boolean\n  }>,\n  mode: FormMode,\n): string[] {\n  const deps = new Set<string>()\n\n  for (const { predicate } of dynamicRequired) {\n    if (isConstantPredicate(predicate)) continue\n\n    const accessed: string[] = []\n    const proxy = new Proxy({} as Record<string, unknown>, {\n      get(_target, prop) {\n        if (typeof prop === 'string') accessed.push(prop)\n        return undefined\n      },\n    })\n\n    try {\n      predicate(proxy, mode)\n    } catch {\n      /* Predicate may throw on undefined values — that's fine, we already captured the property accesses */\n    }\n\n    for (const key of accessed) deps.add(key)\n  }\n\n  return [...deps]\n}\n\n/**\n * Static predicates (e.g. `() => true` from 'always' / mode rules / partner\n * overrides) don't access form data, so we skip them during dependency\n * detection. We identify them by running against an empty proxy and checking\n * whether any properties were accessed.\n */\nfunction isConstantPredicate(\n  predicate: (data: Record<string, unknown>, mode: FormMode) => boolean,\n): boolean {\n  const accessed: string[] = []\n  const proxy = new Proxy({} as Record<string, unknown>, {\n    get(_target, prop) {\n      if (typeof prop === 'string') accessed.push(prop)\n      return undefined\n    },\n  })\n  try {\n    predicate(proxy, 'create')\n  } catch {\n    /* ignore */\n  }\n  return accessed.length === 0\n}\n"],"names":["buildFormSchema","fieldValidators","options","mode","requiredFieldsConfig","requiredErrorCode","excludeFields","excluded","redacted","partnerRequired","resolveOptionalFieldsToRequire","shape","dynamicRequired","includedFieldNames","config","name","validator","effectiveRule","makeOptional","isPartnerRequired","hasSuperRefine","schema","z","data","ctx","predicate","isEmpty","predicateDeps","detectPredicateDeps","getFieldsMetadata","metadata","value","v","deps","isConstantPredicate","accessed","proxy","_target","prop","key"],"mappings":"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"}
+{"version":3,"file":"buildFormSchema.js","sources":["../../../src/partner-hook-utils/form/buildFormSchema.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { FieldMetadata } from '../types'\n\n// ── Types ────────────────────────────────────────────────────────────\n\n/**\n * Form lifecycle mode used to vary requiredness and validation rules.\n *\n * @internal\n */\ntype FormMode = 'create' | 'update'\n\n/**\n * Per-field requiredness rule.\n *\n * String values apply requiredness in a fixed mode (`'always'`, `'create'`,\n * `'update'`, or `'never'`). A function form receives the current form data\n * and mode so requiredness can depend on other field values at runtime.\n *\n * @typeParam TData - The shape of the form data passed to predicate rules.\n * @internal\n */\ntype RequiredFieldRule<TData = Record<string, unknown>> =\n  | 'create'\n  | 'update'\n  | 'always'\n  | 'never'\n  | ((data: TData, mode: FormMode) => boolean)\n\n/**\n * Mapping from each field name in a schema to its {@link RequiredFieldRule}.\n *\n * @typeParam TSchema - The map of field names to their Zod validators.\n * @internal\n */\nexport type RequiredFieldConfig<TSchema extends Record<string, z.ZodType>> = Partial<{\n  [K in keyof TSchema & string]: RequiredFieldRule<{\n    [F in keyof TSchema]: z.infer<TSchema[F]>\n  }>\n}>\n\ntype OptionalOnCreate<TConfig> = {\n  [K in keyof TConfig & string]: TConfig[K] extends 'update' | 'never' ? K : never\n}[keyof TConfig & string]\n\ntype OptionalOnUpdate<TConfig> = {\n  [K in keyof TConfig & string]: TConfig[K] extends 'create' | 'never' ? K : never\n}[keyof TConfig & string]\n\n/**\n * Per-mode list of optional fields a caller can promote to required.\n *\n * Only fields whose base rule allows the override appear in the `create` /\n * `update` arrays — fields that are already required in a given mode are\n * excluded from that mode's list at the type level.\n *\n * @typeParam TConfig - The {@link RequiredFieldConfig} that constrains which fields are eligible.\n * @internal\n */\nexport type OptionalFieldsToRequire<TConfig> = {\n  create?: Array<OptionalOnCreate<TConfig>>\n  update?: Array<OptionalOnUpdate<TConfig>>\n}\n\n// ── buildFormSchema ──────────────────────────────────────────────────\n\ninterface BuildFormSchemaOptions<\n  T extends Record<string, z.ZodType>,\n  TConfig extends RequiredFieldConfig<T>,\n> {\n  requiredFieldsConfig?: TConfig\n  requiredErrorCode?: string\n  mode: FormMode\n  optionalFieldsToRequire?: OptionalFieldsToRequire<TConfig>\n  excludeFields?: Array<keyof T & string>\n  /** Fields with existing server-side values that are redacted in the API response\n   *  (e.g. SSN, EIN). These fields remain in the schema for format validation and\n   *  appear in metadata (with `hasRedactedValue: true`) but are exempt from required\n   *  validation — an empty submission is valid because a value already exists. */\n  fieldsWithRedactedValues?: Array<keyof T & string>\n  superRefine?: (data: { [K in keyof T]: z.infer<T[K]> }, ctx: z.RefinementCtx) => void\n}\n\n/**\n * Companion config returned alongside a built schema, used to derive per-field\n * metadata and to identify which form values predicate-based rules depend on.\n *\n * @typeParam T - The map of field names to their Zod validators.\n * @internal\n */\nexport interface FieldsMetadataConfig<T extends Record<string, z.ZodType>> {\n  getFieldsMetadata: (data?: Record<string, unknown>) => Record<keyof T, FieldMetadata>\n  /** Form field names that predicate-based requiredness rules read at runtime. */\n  predicateDeps: string[]\n}\n\ntype FormDataFromValidators<T extends Record<string, z.ZodType>> = {\n  [K in keyof T]: z.infer<T[K]>\n}\n\n/**\n * Tuple returned by {@link buildFormSchema}: the composed Zod schema followed\n * by its {@link FieldsMetadataConfig}.\n *\n * @typeParam T - The map of field names to their Zod validators.\n * @internal\n */\nexport type BuildFormSchemaResult<T extends Record<string, z.ZodType>> = [\n  schema: z.ZodType<FormDataFromValidators<T>, FormDataFromValidators<T>>,\n  metadataConfig: FieldsMetadataConfig<T>,\n]\n\n/**\n * Composes a Zod object schema and matching metadata config from a map of\n * per-field validators, applying mode-aware requiredness rules.\n *\n * @remarks\n * Every field is wrapped to coerce empty strings, `null`, `undefined`, and\n * `NaN` to `undefined` before validation, so blank inputs surface as missing\n * rather than as type-mismatch errors. Required-field checks run in a\n * `superRefine` pass that emits an issue keyed by `requiredErrorCode` (defaults\n * to `REQUIRED`) for each unfilled required field.\n *\n * Fields listed in `fieldsWithRedactedValues` remain in the schema for format\n * validation and appear in metadata with `hasRedactedValue: true`, but are\n * exempt from required-field validation because a server-side value already\n * exists.\n *\n * @typeParam T - The map of field names to their Zod validators.\n * @typeParam TConfig - The shape of the requiredness configuration.\n * @param fieldValidators - Map from field name to the validator that runs when a value is present.\n * @param options - Mode, required-field config, redaction list, and optional `superRefine`.\n * @returns A {@link BuildFormSchemaResult} tuple: the schema and its metadata config.\n * @internal\n */\nexport function buildFormSchema<\n  T extends Record<string, z.ZodType>,\n  TConfig extends RequiredFieldConfig<T>,\n>(fieldValidators: T, options: BuildFormSchemaOptions<T, TConfig>): BuildFormSchemaResult<T> {\n  const {\n    mode,\n    requiredFieldsConfig = {} as Record<string, RequiredFieldRule>,\n    requiredErrorCode = 'REQUIRED',\n    excludeFields = [],\n  } = options\n  const excluded = new Set(excludeFields.map(String))\n  const redacted = new Set((options.fieldsWithRedactedValues ?? []).map(String))\n  const partnerRequired = new Set(\n    resolveOptionalFieldsToRequire(options.optionalFieldsToRequire, mode),\n  )\n\n  const shape: Record<string, z.ZodType> = {}\n  const dynamicRequired: Array<{\n    name: string\n    predicate: (data: Record<string, unknown>, mode: FormMode) => boolean\n  }> = []\n  const includedFieldNames: string[] = []\n  const config = requiredFieldsConfig as Record<string, RequiredFieldRule>\n\n  for (const [name, validator] of Object.entries(fieldValidators)) {\n    if (excluded.has(name)) continue\n    includedFieldNames.push(name)\n\n    const effectiveRule = config[name] ?? 'always'\n\n    shape[name] = makeOptional(validator)\n\n    if (!redacted.has(name)) {\n      const isPartnerRequired = partnerRequired.has(name)\n\n      if (typeof effectiveRule === 'function') {\n        dynamicRequired.push({\n          name,\n          predicate: isPartnerRequired ? () => true : effectiveRule,\n        })\n      } else {\n        const isRequired = effectiveRule === 'always' || effectiveRule === mode || isPartnerRequired\n        if (isRequired) {\n          dynamicRequired.push({ name, predicate: () => true })\n        }\n      }\n    }\n  }\n\n  const hasSuperRefine = dynamicRequired.length > 0 || options.superRefine\n  let schema: z.ZodType = z.object(shape)\n\n  if (hasSuperRefine) {\n    schema = (schema as z.ZodObject).superRefine(\n      (data: Record<string, unknown>, ctx: z.RefinementCtx) => {\n        for (const { name, predicate } of dynamicRequired) {\n          if (predicate(data, mode) && isEmpty(data[name])) {\n            ctx.addIssue({\n              code: z.ZodIssueCode.custom,\n              path: [name],\n              message: requiredErrorCode,\n            })\n          }\n        }\n\n        options.superRefine?.(data as { [K in keyof T]: z.infer<T[K]> }, ctx)\n      },\n    )\n  }\n\n  const predicateDeps = detectPredicateDeps(dynamicRequired, mode)\n\n  function getFieldsMetadata(data?: Record<string, unknown>) {\n    const metadata: Record<string, FieldMetadata> = {}\n\n    for (const name of includedFieldNames) {\n      const effectiveRule = config[name] ?? 'always'\n\n      if (partnerRequired.has(name)) {\n        metadata[name] = { name, isRequired: true }\n      } else if (typeof effectiveRule === 'function') {\n        metadata[name] = { name, isRequired: data ? effectiveRule(data, mode) : false }\n      } else {\n        metadata[name] = {\n          name,\n          isRequired: effectiveRule === 'always' || effectiveRule === mode,\n        }\n      }\n\n      if (redacted.has(name)) {\n        metadata[name].hasRedactedValue = true\n      }\n    }\n\n    return metadata as Record<keyof T, FieldMetadata>\n  }\n\n  // makeOptional wraps fields with z.preprocess, which causes z.input to infer\n  // `unknown`. Cast the schema to carry the original field types so zodResolver\n  // infers correct form data types — consumers don't need per-hook casts.\n  return [\n    schema as z.ZodType<FormDataFromValidators<T>, FormDataFromValidators<T>>,\n    { getFieldsMetadata, predicateDeps },\n  ]\n}\n\n// ── Internal helpers ─────────────────────────────────────────────────\n\nfunction resolveOptionalFieldsToRequire<TConfig>(\n  value: OptionalFieldsToRequire<TConfig> | undefined,\n  mode: FormMode,\n): string[] {\n  if (!value) return []\n  return ((mode === 'create' ? value.create : value.update) ?? []) as string[]\n}\n\nfunction makeOptional(validator: z.ZodType): z.ZodType {\n  return z.preprocess(v => (isEmpty(v) ? undefined : v), validator.optional())\n}\n\nfunction isEmpty(value: unknown): boolean {\n  if (value === undefined || value === null) return true\n  if (typeof value === 'string' && value.trim() === '') return true\n  if (typeof value === 'number' && Number.isNaN(value)) return true\n  return false\n}\n\n/**\n * Determines which form field names are read by predicate-based requiredness\n * rules. This enables `useDeriveFieldsMetadata` to watch only the specific\n * fields that predicates depend on, rather than subscribing to every form\n * value change (which defeats react-hook-form's per-field render optimization).\n *\n * Works by running each predicate against a recording Proxy. The Proxy\n * intercepts property access and logs the keys, giving us the dependency list\n * without requiring manual declaration.\n *\n * Limitation: JavaScript short-circuit evaluation (`a && b`) can prevent the\n * Proxy from seeing later operands when earlier ones are falsy. In practice\n * this is acceptable — our predicate rules read a single form value each\n * (e.g. `data => data.adjustForMinimumWage`). Multi-field predicates with\n * equality guards should be expressed as `superRefine` rules instead.\n */\nfunction detectPredicateDeps(\n  dynamicRequired: Array<{\n    name: string\n    predicate: (data: Record<string, unknown>, mode: FormMode) => boolean\n  }>,\n  mode: FormMode,\n): string[] {\n  const deps = new Set<string>()\n\n  for (const { predicate } of dynamicRequired) {\n    if (isConstantPredicate(predicate)) continue\n\n    const accessed: string[] = []\n    const proxy = new Proxy({} as Record<string, unknown>, {\n      get(_target, prop) {\n        if (typeof prop === 'string') accessed.push(prop)\n        return undefined\n      },\n    })\n\n    try {\n      predicate(proxy, mode)\n    } catch {\n      /* Predicate may throw on undefined values — that's fine, we already captured the property accesses */\n    }\n\n    for (const key of accessed) deps.add(key)\n  }\n\n  return [...deps]\n}\n\n/**\n * Static predicates (e.g. `() => true` from 'always' / mode rules / partner\n * overrides) don't access form data, so we skip them during dependency\n * detection. We identify them by running against an empty proxy and checking\n * whether any properties were accessed.\n */\nfunction isConstantPredicate(\n  predicate: (data: Record<string, unknown>, mode: FormMode) => boolean,\n): boolean {\n  const accessed: string[] = []\n  const proxy = new Proxy({} as Record<string, unknown>, {\n    get(_target, prop) {\n      if (typeof prop === 'string') accessed.push(prop)\n      return undefined\n    },\n  })\n  try {\n    predicate(proxy, 'create')\n  } catch {\n    /* ignore */\n  }\n  return accessed.length === 0\n}\n"],"names":["buildFormSchema","fieldValidators","options","mode","requiredFieldsConfig","requiredErrorCode","excludeFields","excluded","redacted","partnerRequired","resolveOptionalFieldsToRequire","shape","dynamicRequired","includedFieldNames","config","name","validator","effectiveRule","makeOptional","isPartnerRequired","hasSuperRefine","schema","z","data","ctx","predicate","isEmpty","predicateDeps","detectPredicateDeps","getFieldsMetadata","metadata","value","v","deps","isConstantPredicate","accessed","proxy","_target","prop","key"],"mappings":"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"}

package/dist/partner-hook-utils/form/composeSubmitHandler.d.ts

@@ -28,20 +28,32 @@ interface ComposableFormHookResult {
 /**
  * Accepted input for a single slot of `composeSubmitHandler`'s `forms` array.
  *
+ * @remarks
  * - SDK form hook results (anything matching `ComposableFormHookResult`) are composed directly.
  * - A raw `react-hook-form` `UseFormReturn<T>` is supported for screen-local auxiliary forms
  *   that don't warrant a dedicated SDK hook. Raw forms contribute validation/focus behavior
  *   but no `errorHandling` (fields surface their own inline errors via react-hook-form).
+ *
+ * @typeParam T - The shape of the form values when a raw `UseFormReturn` is passed.
+ * @internal
  */
 export type ComposeSubmitInput<T extends FieldValues = FieldValues> = ComposableFormHookResult | UseFormReturn<T>;
+/**
+ * Result returned by {@link composeSubmitHandler}: a single submit handler that
+ * coordinates validation across the composed forms, and aggregated error state.
+ *
+ * @public
+ */
 export interface ComposeSubmitHandlerResult {
+    /** Submit handler to pass to a form's `onSubmit`. Validates all composed forms before calling `onAllValid`. */
     handleSubmit: (e: SyntheticEvent) => Promise<void>;
+    /** Aggregated error state across all composed SDK form hooks. Pass to {@link composeErrorHandler} for screen-level error surfaces. */
     errorHandling: HookErrorHandling;
 }
 /**
- * Coordinates validation and submission across multiple form hooks on the same page, and
- * returns aggregated `errorHandling` for those forms so you can drive a single error surface.
+ * Coordinates validation and submission across multiple form hooks on the same page.
  *
+ * @remarks
  * Validates all forms simultaneously via `handleSubmit()`, then focuses the visually first
  * invalid field across all forms (sorted by `getBoundingClientRect()`). Only calls
  * `onAllValid` when every form passes.
@@ -55,11 +67,17 @@ export interface ComposeSubmitHandlerResult {
  * cross-form focus instead.
  *
  * The returned `errorHandling` is the same shape every SDK hook returns, so the whole result
- * can be passed back into `composeErrorHandler` when you need to add extra
- * `@gusto/embedded-api` queries or screen-level submit state.
+ * can be passed back into {@link composeErrorHandler} when you need to add extra
+ * `@gusto/embedded-api-v-2025-11-15` queries or screen-level submit state.
+ *
+ * @typeParam TForms - Tuple of form value shapes, one per slot of `forms`.
+ * @param forms - Form hook results and/or raw `UseFormReturn` instances to coordinate.
+ * @param onAllValid - Async callback invoked once every form has passed validation.
+ * @returns A {@link ComposeSubmitHandlerResult} with a unified `handleSubmit` and aggregated `errorHandling`.
+ * @public
  *
  * @example
- * ```ts
+ * ```tsx
  * const detailsForm = useEmployeeDetailsForm({ employeeId, shouldFocusError: false })
  * const addressForm = useHomeAddressForm({ employeeId, shouldFocusError: false })
  *
@@ -71,9 +89,6 @@ export interface ComposeSubmitHandlerResult {
  *   },
  * )
  *
- * // With extra queries or screen-level submit state:
- * // const errorHandling = composeErrorHandler([submitResult, extraQuery], { submitError, setSubmitError })
- *
  * return <form onSubmit={handleSubmit}>...</form>
  * ```
  */

package/dist/partner-hook-utils/form/composeSubmitHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"composeSubmitHandler.js","sources":["../../../src/partner-hook-utils/form/composeSubmitHandler.ts"],"sourcesContent":["import type { SyntheticEvent } from 'react'\nimport type { FieldValues, UseFormReturn } from 'react-hook-form'\nimport { composeErrorHandler } from '../composeErrorHandler'\nimport type { HookErrorHandling, HookFormInternals } from '../types'\n\n/**\n * Minimal shape required for a form hook result to participate in `composeSubmitHandler`.\n * Any hook returning `BaseFormHookReady` satisfies this interface.\n *\n * `formMethods` is declared with method-call syntax (rather than reused from\n * `HookFormInternals`) so TypeScript applies bivariant parameter checking,\n * allowing hooks with specific form data generics to be passed without casts.\n * `_fieldElementRegistry` is reused directly since its type doesn't depend on\n * the form's generic.\n */\ninterface ComposableFormHookResult {\n  form: {\n    hookFormInternals: Pick<HookFormInternals, '_fieldElementRegistry'> & {\n      formMethods: {\n        handleSubmit(\n          onValid: () => void,\n          onInvalid?: (errors: Record<string, unknown>) => void,\n        ): () => Promise<void>\n        setFocus(name: string): void\n        formState: { errors: Record<string, unknown> }\n      }\n    }\n  }\n  errorHandling: HookErrorHandling\n}\n\n/**\n * Accepted input for a single slot of `composeSubmitHandler`'s `forms` array.\n *\n * - SDK form hook results (anything matching `ComposableFormHookResult`) are composed directly.\n * - A raw `react-hook-form` `UseFormReturn<T>` is supported for screen-local auxiliary forms\n *   that don't warrant a dedicated SDK hook. Raw forms contribute validation/focus behavior\n *   but no `errorHandling` (fields surface their own inline errors via react-hook-form).\n */\nexport type ComposeSubmitInput<T extends FieldValues = FieldValues> =\n  | ComposableFormHookResult\n  | UseFormReturn<T>\n\ninterface FormValidationResult {\n  input: ComposeSubmitInput\n  formMethods: FormMethods\n  valid: boolean\n  errors: Record<string, unknown>\n}\n\nexport interface ComposeSubmitHandlerResult {\n  handleSubmit: (e: SyntheticEvent) => Promise<void>\n  errorHandling: HookErrorHandling\n}\n\ntype FormMethods = ComposableFormHookResult['form']['hookFormInternals']['formMethods']\n\nfunction isRawUseForm<T extends FieldValues>(\n  input: ComposeSubmitInput<T>,\n): input is UseFormReturn<T> {\n  return 'handleSubmit' in input && typeof input.handleSubmit === 'function'\n}\n\nfunction extractFormMethods<T extends FieldValues>(input: ComposeSubmitInput<T>): FormMethods {\n  if (isRawUseForm(input)) return input as unknown as FormMethods\n  return input.form.hookFormInternals.formMethods\n}\n\n/**\n * Picks the visually first invalid field across all composed forms using live\n * `getBoundingClientRect()` positions, then focuses its DOM element. Falls back\n * to array-order (first form's first error) when no element can be resolved —\n * raw `UseFormReturn` inputs have no registry, and forms rendered without\n * `SDKFormProvider` or a HookField wrapper won't have their fields registered\n * either, so we let react-hook-form's `setFocus` attempt it instead.\n *\n * Consumes `results` (captured from each form's `onInvalid` callback) rather\n * than reading `formState.errors` — the latter is a proxy that returns `{}`\n * when accessed outside a component subscription.\n */\nfunction focusFirstInvalidAcrossForms(results: FormValidationResult[]): void {\n  type Candidate = {\n    formMethods: FormMethods\n    name: string\n    element: HTMLElement\n  }\n  const candidates: Candidate[] = []\n  for (const { input, formMethods, errors } of results) {\n    if (isRawUseForm(input)) continue\n    const registry = input.form.hookFormInternals._fieldElementRegistry\n    if (!registry) continue\n    for (const name of Object.keys(errors)) {\n      const element = registry.get(name)\n      if (element) {\n        candidates.push({ formMethods, name, element })\n      }\n    }\n  }\n\n  if (candidates.length > 0) {\n    candidates.sort((a, b) => {\n      const ar = a.element.getBoundingClientRect()\n      const br = b.element.getBoundingClientRect()\n      return ar.top - br.top || ar.left - br.left\n    })\n    const winner = candidates[0]!\n    // Focus the DOM element directly. Bypasses react-hook-form's `setFocus`,\n    // which depends on `_fields[name]._f.ref` and isn't reliably populated\n    // when fields are rendered through libraries like react-aria-components.\n    winner.element.focus()\n    return\n  }\n\n  for (const { formMethods, errors } of results) {\n    const firstErrorField = Object.keys(errors)[0]\n    if (firstErrorField) {\n      formMethods.setFocus(firstErrorField)\n      return\n    }\n  }\n}\n\n/**\n * Coordinates validation and submission across multiple form hooks on the same page, and\n * returns aggregated `errorHandling` for those forms so you can drive a single error surface.\n *\n * Validates all forms simultaneously via `handleSubmit()`, then focuses the visually first\n * invalid field across all forms (sorted by `getBoundingClientRect()`). Only calls\n * `onAllValid` when every form passes.\n *\n * Uses `handleSubmit` rather than `trigger` so that react-hook-form sets\n * `formState.isSubmitted = true`, which enables `reValidateMode` (default: `onChange`).\n * Without this, errors set by manual `trigger()` calls would never clear as the user types.\n *\n * Each hook passed to `forms` should be initialized with `shouldFocusError: false` so that\n * react-hook-form's built-in per-form focus is disabled and `composeSubmitHandler` can manage\n * cross-form focus instead.\n *\n * The returned `errorHandling` is the same shape every SDK hook returns, so the whole result\n * can be passed back into `composeErrorHandler` when you need to add extra\n * `@gusto/embedded-api` queries or screen-level submit state.\n *\n * @example\n * ```ts\n * const detailsForm = useEmployeeDetailsForm({ employeeId, shouldFocusError: false })\n * const addressForm = useHomeAddressForm({ employeeId, shouldFocusError: false })\n *\n * const { handleSubmit, errorHandling } = composeSubmitHandler(\n *   [detailsForm, addressForm],\n *   async () => {\n *     await detailsForm.actions.onSubmit()\n *     await addressForm.actions.onSubmit()\n *   },\n * )\n *\n * // With extra queries or screen-level submit state:\n * // const errorHandling = composeErrorHandler([submitResult, extraQuery], { submitError, setSubmitError })\n *\n * return <form onSubmit={handleSubmit}>...</form>\n * ```\n */\nexport function composeSubmitHandler<TForms extends readonly FieldValues[]>(\n  forms: readonly [...{ [K in keyof TForms]: ComposeSubmitInput<TForms[K]> }],\n  onAllValid: () => Promise<void>,\n): ComposeSubmitHandlerResult {\n  const errorSources = forms.filter((form): form is ComposableFormHookResult => !isRawUseForm(form))\n\n  const handleSubmit = async (e: SyntheticEvent) => {\n    e.preventDefault()\n\n    const validationResults = await Promise.all(\n      forms.map(\n        input =>\n          new Promise<FormValidationResult>(resolve => {\n            const formMethods = extractFormMethods(input)\n            void formMethods.handleSubmit(\n              () => {\n                resolve({ input, formMethods, valid: true, errors: {} })\n              },\n              errors => {\n                resolve({ input, formMethods, valid: false, errors })\n              },\n            )()\n          }),\n      ),\n    )\n\n    const allValid = validationResults.every(r => r.valid)\n\n    if (!allValid) {\n      focusFirstInvalidAcrossForms(validationResults)\n      return\n    }\n\n    await onAllValid()\n  }\n\n  const errorHandling = composeErrorHandler(errorSources)\n\n  return { handleSubmit, errorHandling }\n}\n"],"names":["isRawUseForm","input","extractFormMethods","focusFirstInvalidAcrossForms","results","candidates","formMethods","errors","registry","name","element","a","b","ar","br","firstErrorField","composeSubmitHandler","forms","onAllValid","errorSources","form","handleSubmit","e","validationResults","resolve","r","errorHandling","composeErrorHandler"],"mappings":";AAyDA,SAASA,EACPC,GAC2B;AAC3B,SAAO,kBAAkBA,KAAS,OAAOA,EAAM,gBAAiB;AAClE;AAEA,SAASC,EAA0CD,GAA2C;AAC5F,SAAID,EAAaC,CAAK,IAAUA,IACzBA,EAAM,KAAK,kBAAkB;AACtC;AAcA,SAASE,EAA6BC,GAAuC;AAM3E,QAAMC,IAA0B,CAAA;AAChC,aAAW,EAAE,OAAAJ,GAAO,aAAAK,GAAa,QAAAC,EAAA,KAAYH,GAAS;AACpD,QAAIJ,EAAaC,CAAK,EAAG;AACzB,UAAMO,IAAWP,EAAM,KAAK,kBAAkB;AAC9C,QAAKO;AACL,iBAAWC,KAAQ,OAAO,KAAKF,CAAM,GAAG;AACtC,cAAMG,IAAUF,EAAS,IAAIC,CAAI;AACjC,QAAIC,KACFL,EAAW,KAAK,EAAE,aAAAC,GAAa,MAAAG,GAAM,SAAAC,GAAS;AAAA,MAElD;AAAA,EACF;AAEA,MAAIL,EAAW,SAAS,GAAG;AACzB,IAAAA,EAAW,KAAK,CAACM,GAAGC,MAAM;AACxB,YAAMC,IAAKF,EAAE,QAAQ,sBAAA,GACfG,IAAKF,EAAE,QAAQ,sBAAA;AACrB,aAAOC,EAAG,MAAMC,EAAG,OAAOD,EAAG,OAAOC,EAAG;AAAA,IACzC,CAAC,GACcT,EAAW,CAAC,EAIpB,QAAQ,MAAA;AACf;AAAA,EACF;AAEA,aAAW,EAAE,aAAAC,GAAa,QAAAC,EAAA,KAAYH,GAAS;AAC7C,UAAMW,IAAkB,OAAO,KAAKR,CAAM,EAAE,CAAC;AAC7C,QAAIQ,GAAiB;AACnB,MAAAT,EAAY,SAASS,CAAe;AACpC;AAAA,IACF;AAAA,EACF;AACF;AAyCO,SAASC,EACdC,GACAC,GAC4B;AAC5B,QAAMC,IAAeF,EAAM,OAAO,CAACG,MAA2C,CAACpB,EAAaoB,CAAI,CAAC,GAE3FC,IAAe,OAAOC,MAAsB;AAChD,IAAAA,EAAE,eAAA;AAEF,UAAMC,IAAoB,MAAM,QAAQ;AAAA,MACtCN,EAAM;AAAA,QACJ,CAAAhB,MACE,IAAI,QAA8B,CAAAuB,MAAW;AAC3C,gBAAMlB,IAAcJ,EAAmBD,CAAK;AAC5C,UAAKK,EAAY;AAAA,YACf,MAAM;AACJ,cAAAkB,EAAQ,EAAE,OAAAvB,GAAO,aAAAK,GAAa,OAAO,IAAM,QAAQ,CAAA,GAAI;AAAA,YACzD;AAAA,YACA,CAAAC,MAAU;AACR,cAAAiB,EAAQ,EAAE,OAAAvB,GAAO,aAAAK,GAAa,OAAO,IAAO,QAAAC,GAAQ;AAAA,YACtD;AAAA,UAAA,EACF;AAAA,QACF,CAAC;AAAA,MAAA;AAAA,IACL;AAKF,QAAI,CAFagB,EAAkB,MAAM,CAAAE,MAAKA,EAAE,KAAK,GAEtC;AACb,MAAAtB,EAA6BoB,CAAiB;AAC9C;AAAA,IACF;AAEA,UAAML,EAAA;AAAA,EACR,GAEMQ,IAAgBC,EAAoBR,CAAY;AAEtD,SAAO,EAAE,cAAAE,GAAc,eAAAK,EAAA;AACzB;"}
+{"version":3,"file":"composeSubmitHandler.js","sources":["../../../src/partner-hook-utils/form/composeSubmitHandler.ts"],"sourcesContent":["import type { SyntheticEvent } from 'react'\nimport type { FieldValues, UseFormReturn } from 'react-hook-form'\nimport { composeErrorHandler } from '../composeErrorHandler'\nimport type { HookErrorHandling, HookFormInternals } from '../types'\n\n/**\n * Minimal shape required for a form hook result to participate in `composeSubmitHandler`.\n * Any hook returning `BaseFormHookReady` satisfies this interface.\n *\n * `formMethods` is declared with method-call syntax (rather than reused from\n * `HookFormInternals`) so TypeScript applies bivariant parameter checking,\n * allowing hooks with specific form data generics to be passed without casts.\n * `_fieldElementRegistry` is reused directly since its type doesn't depend on\n * the form's generic.\n */\ninterface ComposableFormHookResult {\n  form: {\n    hookFormInternals: Pick<HookFormInternals, '_fieldElementRegistry'> & {\n      formMethods: {\n        handleSubmit(\n          onValid: () => void,\n          onInvalid?: (errors: Record<string, unknown>) => void,\n        ): () => Promise<void>\n        setFocus(name: string): void\n        formState: { errors: Record<string, unknown> }\n      }\n    }\n  }\n  errorHandling: HookErrorHandling\n}\n\n/**\n * Accepted input for a single slot of `composeSubmitHandler`'s `forms` array.\n *\n * @remarks\n * - SDK form hook results (anything matching `ComposableFormHookResult`) are composed directly.\n * - A raw `react-hook-form` `UseFormReturn<T>` is supported for screen-local auxiliary forms\n *   that don't warrant a dedicated SDK hook. Raw forms contribute validation/focus behavior\n *   but no `errorHandling` (fields surface their own inline errors via react-hook-form).\n *\n * @typeParam T - The shape of the form values when a raw `UseFormReturn` is passed.\n * @internal\n */\nexport type ComposeSubmitInput<T extends FieldValues = FieldValues> =\n  | ComposableFormHookResult\n  | UseFormReturn<T>\n\ninterface FormValidationResult {\n  input: ComposeSubmitInput\n  formMethods: FormMethods\n  valid: boolean\n  errors: Record<string, unknown>\n}\n\n/**\n * Result returned by {@link composeSubmitHandler}: a single submit handler that\n * coordinates validation across the composed forms, and aggregated error state.\n *\n * @public\n */\nexport interface ComposeSubmitHandlerResult {\n  /** Submit handler to pass to a form's `onSubmit`. Validates all composed forms before calling `onAllValid`. */\n  handleSubmit: (e: SyntheticEvent) => Promise<void>\n  /** Aggregated error state across all composed SDK form hooks. Pass to {@link composeErrorHandler} for screen-level error surfaces. */\n  errorHandling: HookErrorHandling\n}\n\ntype FormMethods = ComposableFormHookResult['form']['hookFormInternals']['formMethods']\n\nfunction isRawUseForm<T extends FieldValues>(\n  input: ComposeSubmitInput<T>,\n): input is UseFormReturn<T> {\n  return 'handleSubmit' in input && typeof input.handleSubmit === 'function'\n}\n\nfunction extractFormMethods<T extends FieldValues>(input: ComposeSubmitInput<T>): FormMethods {\n  if (isRawUseForm(input)) return input as unknown as FormMethods\n  return input.form.hookFormInternals.formMethods\n}\n\n/**\n * Picks the visually first invalid field across all composed forms using live\n * `getBoundingClientRect()` positions, then focuses its DOM element. Falls back\n * to array-order (first form's first error) when no element can be resolved —\n * raw `UseFormReturn` inputs have no registry, and forms rendered without\n * `SDKFormProvider` or a HookField wrapper won't have their fields registered\n * either, so we let react-hook-form's `setFocus` attempt it instead.\n *\n * Consumes `results` (captured from each form's `onInvalid` callback) rather\n * than reading `formState.errors` — the latter is a proxy that returns `{}`\n * when accessed outside a component subscription.\n */\nfunction focusFirstInvalidAcrossForms(results: FormValidationResult[]): void {\n  type Candidate = {\n    formMethods: FormMethods\n    name: string\n    element: HTMLElement\n  }\n  const candidates: Candidate[] = []\n  for (const { input, formMethods, errors } of results) {\n    if (isRawUseForm(input)) continue\n    const registry = input.form.hookFormInternals._fieldElementRegistry\n    if (!registry) continue\n    for (const name of Object.keys(errors)) {\n      const element = registry.get(name)\n      if (element) {\n        candidates.push({ formMethods, name, element })\n      }\n    }\n  }\n\n  if (candidates.length > 0) {\n    candidates.sort((a, b) => {\n      const ar = a.element.getBoundingClientRect()\n      const br = b.element.getBoundingClientRect()\n      return ar.top - br.top || ar.left - br.left\n    })\n    const winner = candidates[0]!\n    // Focus the DOM element directly. Bypasses react-hook-form's `setFocus`,\n    // which depends on `_fields[name]._f.ref` and isn't reliably populated\n    // when fields are rendered through libraries like react-aria-components.\n    winner.element.focus()\n    return\n  }\n\n  for (const { formMethods, errors } of results) {\n    const firstErrorField = Object.keys(errors)[0]\n    if (firstErrorField) {\n      formMethods.setFocus(firstErrorField)\n      return\n    }\n  }\n}\n\n/**\n * Coordinates validation and submission across multiple form hooks on the same page.\n *\n * @remarks\n * Validates all forms simultaneously via `handleSubmit()`, then focuses the visually first\n * invalid field across all forms (sorted by `getBoundingClientRect()`). Only calls\n * `onAllValid` when every form passes.\n *\n * Uses `handleSubmit` rather than `trigger` so that react-hook-form sets\n * `formState.isSubmitted = true`, which enables `reValidateMode` (default: `onChange`).\n * Without this, errors set by manual `trigger()` calls would never clear as the user types.\n *\n * Each hook passed to `forms` should be initialized with `shouldFocusError: false` so that\n * react-hook-form's built-in per-form focus is disabled and `composeSubmitHandler` can manage\n * cross-form focus instead.\n *\n * The returned `errorHandling` is the same shape every SDK hook returns, so the whole result\n * can be passed back into {@link composeErrorHandler} when you need to add extra\n * `@gusto/embedded-api-v-2025-11-15` queries or screen-level submit state.\n *\n * @typeParam TForms - Tuple of form value shapes, one per slot of `forms`.\n * @param forms - Form hook results and/or raw `UseFormReturn` instances to coordinate.\n * @param onAllValid - Async callback invoked once every form has passed validation.\n * @returns A {@link ComposeSubmitHandlerResult} with a unified `handleSubmit` and aggregated `errorHandling`.\n * @public\n *\n * @example\n * ```tsx\n * const detailsForm = useEmployeeDetailsForm({ employeeId, shouldFocusError: false })\n * const addressForm = useHomeAddressForm({ employeeId, shouldFocusError: false })\n *\n * const { handleSubmit, errorHandling } = composeSubmitHandler(\n *   [detailsForm, addressForm],\n *   async () => {\n *     await detailsForm.actions.onSubmit()\n *     await addressForm.actions.onSubmit()\n *   },\n * )\n *\n * return <form onSubmit={handleSubmit}>...</form>\n * ```\n */\nexport function composeSubmitHandler<TForms extends readonly FieldValues[]>(\n  forms: readonly [...{ [K in keyof TForms]: ComposeSubmitInput<TForms[K]> }],\n  onAllValid: () => Promise<void>,\n): ComposeSubmitHandlerResult {\n  const errorSources = forms.filter((form): form is ComposableFormHookResult => !isRawUseForm(form))\n\n  const handleSubmit = async (e: SyntheticEvent) => {\n    e.preventDefault()\n\n    const validationResults = await Promise.all(\n      forms.map(\n        input =>\n          new Promise<FormValidationResult>(resolve => {\n            const formMethods = extractFormMethods(input)\n            void formMethods.handleSubmit(\n              () => {\n                resolve({ input, formMethods, valid: true, errors: {} })\n              },\n              errors => {\n                resolve({ input, formMethods, valid: false, errors })\n              },\n            )()\n          }),\n      ),\n    )\n\n    const allValid = validationResults.every(r => r.valid)\n\n    if (!allValid) {\n      focusFirstInvalidAcrossForms(validationResults)\n      return\n    }\n\n    await onAllValid()\n  }\n\n  const errorHandling = composeErrorHandler(errorSources)\n\n  return { handleSubmit, errorHandling }\n}\n"],"names":["isRawUseForm","input","extractFormMethods","focusFirstInvalidAcrossForms","results","candidates","formMethods","errors","registry","name","element","a","b","ar","br","firstErrorField","composeSubmitHandler","forms","onAllValid","errorSources","form","handleSubmit","e","validationResults","resolve","r","errorHandling","composeErrorHandler"],"mappings":";AAqEA,SAASA,EACPC,GAC2B;AAC3B,SAAO,kBAAkBA,KAAS,OAAOA,EAAM,gBAAiB;AAClE;AAEA,SAASC,EAA0CD,GAA2C;AAC5F,SAAID,EAAaC,CAAK,IAAUA,IACzBA,EAAM,KAAK,kBAAkB;AACtC;AAcA,SAASE,EAA6BC,GAAuC;AAM3E,QAAMC,IAA0B,CAAA;AAChC,aAAW,EAAE,OAAAJ,GAAO,aAAAK,GAAa,QAAAC,EAAA,KAAYH,GAAS;AACpD,QAAIJ,EAAaC,CAAK,EAAG;AACzB,UAAMO,IAAWP,EAAM,KAAK,kBAAkB;AAC9C,QAAKO;AACL,iBAAWC,KAAQ,OAAO,KAAKF,CAAM,GAAG;AACtC,cAAMG,IAAUF,EAAS,IAAIC,CAAI;AACjC,QAAIC,KACFL,EAAW,KAAK,EAAE,aAAAC,GAAa,MAAAG,GAAM,SAAAC,GAAS;AAAA,MAElD;AAAA,EACF;AAEA,MAAIL,EAAW,SAAS,GAAG;AACzB,IAAAA,EAAW,KAAK,CAACM,GAAGC,MAAM;AACxB,YAAMC,IAAKF,EAAE,QAAQ,sBAAA,GACfG,IAAKF,EAAE,QAAQ,sBAAA;AACrB,aAAOC,EAAG,MAAMC,EAAG,OAAOD,EAAG,OAAOC,EAAG;AAAA,IACzC,CAAC,GACcT,EAAW,CAAC,EAIpB,QAAQ,MAAA;AACf;AAAA,EACF;AAEA,aAAW,EAAE,aAAAC,GAAa,QAAAC,EAAA,KAAYH,GAAS;AAC7C,UAAMW,IAAkB,OAAO,KAAKR,CAAM,EAAE,CAAC;AAC7C,QAAIQ,GAAiB;AACnB,MAAAT,EAAY,SAASS,CAAe;AACpC;AAAA,IACF;AAAA,EACF;AACF;AA4CO,SAASC,EACdC,GACAC,GAC4B;AAC5B,QAAMC,IAAeF,EAAM,OAAO,CAACG,MAA2C,CAACpB,EAAaoB,CAAI,CAAC,GAE3FC,IAAe,OAAOC,MAAsB;AAChD,IAAAA,EAAE,eAAA;AAEF,UAAMC,IAAoB,MAAM,QAAQ;AAAA,MACtCN,EAAM;AAAA,QACJ,CAAAhB,MACE,IAAI,QAA8B,CAAAuB,MAAW;AAC3C,gBAAMlB,IAAcJ,EAAmBD,CAAK;AAC5C,UAAKK,EAAY;AAAA,YACf,MAAM;AACJ,cAAAkB,EAAQ,EAAE,OAAAvB,GAAO,aAAAK,GAAa,OAAO,IAAM,QAAQ,CAAA,GAAI;AAAA,YACzD;AAAA,YACA,CAAAC,MAAU;AACR,cAAAiB,EAAQ,EAAE,OAAAvB,GAAO,aAAAK,GAAa,OAAO,IAAO,QAAAC,GAAQ;AAAA,YACtD;AAAA,UAAA,EACF;AAAA,QACF,CAAC;AAAA,MAAA;AAAA,IACL;AAKF,QAAI,CAFagB,EAAkB,MAAM,CAAAE,MAAKA,EAAE,KAAK,GAEtC;AACb,MAAAtB,EAA6BoB,CAAiB;AAC9C;AAAA,IACF;AAEA,UAAML,EAAA;AAAA,EACR,GAEMQ,IAAgBC,EAAoBR,CAAY;AAEtD,SAAO,EAAE,cAAAE,GAAc,eAAAK,EAAA;AACzB;"}

package/dist/partner-hook-utils/form/fields/CheckboxHookField.d.ts

@@ -1,10 +1,30 @@
 import { ComponentType } from 'react';
 import { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types';
 import { CheckboxProps } from '../../../components/Common/UI/Checkbox/CheckboxTypes';
+/**
+ * Props accepted by a checkbox field surfaced through a form hook.
+ * Exposes `validationMessages` for custom error text alongside the shared base
+ * field attributes (`label`, `description`).
+ *
+ * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
+ * @public
+ */
 export interface CheckboxHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {
+    /** The field name; must match the corresponding key in the form schema. */
     name: string;
+    /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */
     formHookResult?: FormHookResult;
+    /** Custom error text keyed by validation error code. */
     validationMessages?: ValidationMessages<TErrorCode>;
+    /** Replaces the default checkbox UI component; must accept the same props as `CheckboxProps`. */
     FieldComponent?: ComponentType<CheckboxProps>;
 }
+/**
+ * Checkbox field connected to a partner form hook result via `useHookFieldResolution`.
+ *
+ * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
+ * @param props - Field configuration including `name`, `formHookResult`, and label content.
+ * @returns The rendered checkbox field wrapped in the field element registry.
+ * @internal
+ */
 export declare function CheckboxHookField<TErrorCode extends string>({ name, formHookResult, label, description, validationMessages, FieldComponent, }: CheckboxHookFieldProps<TErrorCode>): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;

package/dist/partner-hook-utils/form/fields/CheckboxHookField.js

@@ -1,10 +1,9 @@
 import { jsx as n } from "react/jsx-runtime";
-import { useHookFieldResolution as p } from "../useHookFieldResolution.js";
-import { withFieldElementRegistry as c } from "./withFieldElementRegistry.js";
-import "classnames";
+import { useHookFieldResolution as c } from "../useHookFieldResolution.js";
+import { withFieldElementRegistry as p } from "./withFieldElementRegistry.js";
 import "../../../shared/constants.js";
 import { CheckboxField as u } from "../../../components/Common/Fields/CheckboxField/CheckboxField.js";
-function h({
+function g({
   name: e,
   formHookResult: o,
   label: t,
@@ -12,12 +11,12 @@ function h({
   validationMessages: s,
   FieldComponent: d
 }) {
-  const { metadata: l, control: m, errorMessage: a, fieldElementRegistry: f } = p(
+  const { metadata: l, control: m, errorMessage: a, fieldElementRegistry: f } = c(
     e,
     o,
     s
   ), i = l[e];
-  return c(
+  return p(
     f,
     /* @__PURE__ */ n(
       u,
@@ -35,6 +34,6 @@ function h({
   );
 }
 export {
-  h as CheckboxHookField
+  g as CheckboxHookField
 };
 //# sourceMappingURL=CheckboxHookField.js.map