@gusto/embedded-react-sdk 0.52.0 → 0.52.1

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

@@ -6,6 +6,7 @@ import { SDKError } from '../types/sdkError';
  * {@link composeErrorHandler} reads from an additional query passed as a source.
  *
  * @public
+ * @childOf {@link composeErrorHandler}
  */
 export type QueryWithRefetch = Pick<UseQueryResult, 'error' | 'refetch'>;
 /**
@@ -17,6 +18,7 @@ export type QueryWithRefetch = Pick<UseQueryResult, 'error' | 'refetch'>;
  * and can be cleared together with `clearSubmitError`.
  *
  * @public
+ * @childOf {@link composeErrorHandler}
  */
 export type SubmitStateForErrorHandling = {
     /** The current submit error, or `null` when cleared. */
@@ -30,6 +32,7 @@ export type SubmitStateForErrorHandling = {
  * an `errorHandling` object.
  *
  * @public
+ * @childOf {@link composeErrorHandler}
  */
 export type MixedErrorSource = QueryWithRefetch | {
     errorHandling: HookErrorHandling;
@@ -56,6 +59,7 @@ export type MixedErrorSource = QueryWithRefetch | {
  * @param submitState - Optional screen-level submit state to fold into the result.
  * @returns A single `HookErrorHandling` covering every source.
  * @public
+ * @group Form composition
  *
  * @example
  * ```tsx

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\n/**\n * The subset of a TanStack Query result — its `error` and `refetch` — that\n * {@link composeErrorHandler} reads from an additional query passed as a source.\n *\n * @public\n */\nexport type 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-2026-06-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-2026-06-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":";AAuCA,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,MAAA;AAAK,MAAKA,EAAE,QAAA;AAAA,KAAS;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\n/**\n * The subset of a TanStack Query result — its `error` and `refetch` — that\n * {@link composeErrorHandler} reads from an additional query passed as a source.\n *\n * @public\n * @childOf {@link composeErrorHandler}\n */\nexport type 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 * @childOf {@link composeErrorHandler}\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 * @childOf {@link composeErrorHandler}\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-2026-06-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 * @group Form composition\n *\n * @example\n * ```tsx\n * import { composeErrorHandler, useEmployeeDetailsForm } from '@gusto/embedded-react-sdk'\n * import { useEmployeeFormsList } from '@gusto/embedded-api-v-2026-06-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":";AA0CA,SAASA,EACPC,GACgD;AAChD,SAAO,mBAAmBA;AAC5B;AAoDO,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,MAAA;AAAK,MAAKA,EAAE,QAAA;AAAA,KAAS;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/SDKFormProvider.d.ts

@@ -31,6 +31,7 @@ export interface SDKFormProviderProps<TFormData extends FieldValues = FieldValue
  * Server-side field errors are automatically synced onto their corresponding fields.
  *
  * @public
+ * @group Providers
  *
  * @example
  * ```tsx

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 type { FieldElementRegistry } from '@/components/Common/Fields/hooks/fieldElementRegistry'\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\n/**\n * Props for {@link SDKFormProvider}.\n *\n * @typeParam TFormData - Shape of the form values managed by the wrapped form hook.\n * @typeParam TFieldsMetadata - The form hook's field-metadata map.\n * @public\n */\nexport interface SDKFormProviderProps<\n  TFormData extends FieldValues = FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  } = Record<string, FieldMetadata | FieldMetadataWithOptions>,\n> {\n  /** The form hook result whose fields, metadata, and errors are shared with descendant field components. */\n  formHookResult: {\n    errorHandling: { errors: SDKError[] }\n    form: {\n      fieldsMetadata: TFieldsMetadata\n      hookFormInternals: HookFormInternals<TFormData>\n    }\n  }\n  /** Field components (or any content) that consume the provided form context. */\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\n        registry={form.hookFormInternals._fieldElementRegistry as FieldElementRegistry | undefined}\n      >\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","FormFieldsMetadataProvider","jsx","FieldElementRegistryProvider","FormProvider"],"mappings":";;;;;;AAUA,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;AAuDO,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,qBAGpCc,GAAA,EAA2B,UAAUd,EAAK,gBAAgB,QAAQW,EAAc,QAC/E,UAAA,gBAAAI;AAAA,IAACC;AAAA,IAAA;AAAA,MACC,UAAUhB,EAAK,kBAAkB;AAAA,MAEjC,4BAACiB,GAAA,EAAc,GAAGjB,EAAK,kBAAkB,aAAc,UAAAU,EAAA,CAAS;AAAA,IAAA;AAAA,EAAA,GAEpE;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 type { FieldElementRegistry } from '@/components/Common/Fields/hooks/fieldElementRegistry'\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\n/**\n * Props for {@link SDKFormProvider}.\n *\n * @typeParam TFormData - Shape of the form values managed by the wrapped form hook.\n * @typeParam TFieldsMetadata - The form hook's field-metadata map.\n * @public\n */\nexport interface SDKFormProviderProps<\n  TFormData extends FieldValues = FieldValues,\n  TFieldsMetadata extends {\n    [K in keyof TFieldsMetadata]: FieldMetadata | FieldMetadataWithOptions\n  } = Record<string, FieldMetadata | FieldMetadataWithOptions>,\n> {\n  /** The form hook result whose fields, metadata, and errors are shared with descendant field components. */\n  formHookResult: {\n    errorHandling: { errors: SDKError[] }\n    form: {\n      fieldsMetadata: TFieldsMetadata\n      hookFormInternals: HookFormInternals<TFormData>\n    }\n  }\n  /** Field components (or any content) that consume the provided form context. */\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 * @group Providers\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\n        registry={form.hookFormInternals._fieldElementRegistry as FieldElementRegistry | undefined}\n      >\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","FormFieldsMetadataProvider","jsx","FieldElementRegistryProvider","FormProvider"],"mappings":";;;;;;AAUA,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;AAwDO,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,qBAGpCc,GAAA,EAA2B,UAAUd,EAAK,gBAAgB,QAAQW,EAAc,QAC/E,UAAA,gBAAAI;AAAA,IAACC;AAAA,IAAA;AAAA,MACC,UAAUhB,EAAK,kBAAkB;AAAA,MAEjC,4BAACiB,GAAA,EAAc,GAAGjB,EAAK,kBAAkB,aAAc,UAAAU,EAAA,CAAS;AAAA,IAAA;AAAA,EAAA,GAEpE;AAEJ;"}

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

@@ -12,6 +12,7 @@ import { HookErrorHandling, HookFormInternals } from '../types';
  * the form's generic.
  *
  * @public
+ * @childOf {@link composeSubmitHandler}
  */
 export interface ComposableFormHookResult {
     /** The form surface: the react-hook-form internals used to validate and focus fields. */
@@ -40,6 +41,7 @@ export interface ComposableFormHookResult {
  *
  * @typeParam T - The shape of the form values when a raw `UseFormReturn` is passed.
  * @public
+ * @childOf {@link composeSubmitHandler}
  */
 export type ComposeSubmitInput<T extends FieldValues = FieldValues> = ComposableFormHookResult | UseFormReturn<T>;
 /**
@@ -47,6 +49,7 @@ export type ComposeSubmitInput<T extends FieldValues = FieldValues> = Composable
  * coordinates validation across the composed forms, and aggregated error state.
  *
  * @public
+ * @childOf {@link composeSubmitHandler}
  */
 export interface ComposeSubmitHandlerResult {
     /** Submit handler to pass to a form's `onSubmit`. Validates all composed forms before calling `onAllValid`. */
@@ -79,6 +82,7 @@ export interface ComposeSubmitHandlerResult {
  * @param onAllValid - Async callback invoked once every form has passed validation.
  * @returns A {@link ComposeSubmitHandlerResult} with a unified `handleSubmit` and aggregated `errorHandling`.
  * @public
+ * @group Form composition
  *
  * @example
  * ```tsx

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'\nimport type { FieldElementRegistry } from '@/components/Common/Fields/hooks/fieldElementRegistry'\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 *\n * @public\n */\nexport interface ComposableFormHookResult {\n  /** The form surface: the react-hook-form internals used to validate and focus fields. */\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  /** The error-handling surface aggregated across the composed forms. */\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 * @public\n */\nexport type ComposeSubmitInput<T extends FieldValues = FieldValues> =\n  ComposableFormHookResult | 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 as\n      FieldElementRegistry | undefined\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-2026-06-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":";AAyEA,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;AAE9C,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;"}
+{"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'\nimport type { FieldElementRegistry } from '@/components/Common/Fields/hooks/fieldElementRegistry'\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 *\n * @public\n * @childOf {@link composeSubmitHandler}\n */\nexport interface ComposableFormHookResult {\n  /** The form surface: the react-hook-form internals used to validate and focus fields. */\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  /** The error-handling surface aggregated across the composed forms. */\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 * @public\n * @childOf {@link composeSubmitHandler}\n */\nexport type ComposeSubmitInput<T extends FieldValues = FieldValues> =\n  ComposableFormHookResult | 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 * @childOf {@link composeSubmitHandler}\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 as\n      FieldElementRegistry | undefined\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-2026-06-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 * @group Form composition\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":";AA4EA,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;AAE9C,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;AA6CO,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

@@ -8,6 +8,7 @@ import { CheckboxProps } from '../../../components/Common/UI/Checkbox/CheckboxTy
  *
  * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
  * @public
+ * @group Hook field props
  */
 export interface CheckboxHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {
     /** The field name; must match the corresponding key in the form schema. */

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

@@ -1 +1 @@
-{"version":3,"file":"CheckboxHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/CheckboxHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { CheckboxField } from '@/components/Common'\nimport type { CheckboxProps } from '@/components/Common/UI/Checkbox/CheckboxTypes'\n\n/**\n * Props accepted by a checkbox field surfaced through a form hook.\n * Exposes `validationMessages` for custom error text alongside the shared base\n * field attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n */\nexport interface CheckboxHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default checkbox UI component; must accept the same props as `CheckboxProps`. */\n  FieldComponent?: ComponentType<CheckboxProps>\n}\n\n/**\n * Checkbox field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, and label content.\n * @returns The rendered checkbox field wrapped in the field element registry.\n * @internal\n */\nexport function CheckboxHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  FieldComponent,\n}: CheckboxHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <CheckboxField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["CheckboxHookField","name","formHookResult","label","description","validationMessages","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","CheckboxField"],"mappings":";;;;;;;AAkCO,SAASA,EAA6C;AAAA,EAC3D,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AACF,GAAuC;AACrC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEV;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIO,IAAgBL,EAASN,CAAI;AAEnC,SAAOY;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAd;AAAA,QACA,SAAAO;AAAA,QACA,OAAAL;AAAA,QACA,aAAAC;AAAA,QACA,cAAAK;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,gBAAAN;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}
+{"version":3,"file":"CheckboxHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/CheckboxHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { CheckboxField } from '@/components/Common'\nimport type { CheckboxProps } from '@/components/Common/UI/Checkbox/CheckboxTypes'\n\n/**\n * Props accepted by a checkbox field surfaced through a form hook.\n * Exposes `validationMessages` for custom error text alongside the shared base\n * field attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n * @group Hook field props\n */\nexport interface CheckboxHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default checkbox UI component; must accept the same props as `CheckboxProps`. */\n  FieldComponent?: ComponentType<CheckboxProps>\n}\n\n/**\n * Checkbox field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, and label content.\n * @returns The rendered checkbox field wrapped in the field element registry.\n * @internal\n */\nexport function CheckboxHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  FieldComponent,\n}: CheckboxHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <CheckboxField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["CheckboxHookField","name","formHookResult","label","description","validationMessages","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","CheckboxField"],"mappings":";;;;;;;AAmCO,SAASA,EAA6C;AAAA,EAC3D,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AACF,GAAuC;AACrC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEV;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIO,IAAgBL,EAASN,CAAI;AAEnC,SAAOY;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAd;AAAA,QACA,SAAAO;AAAA,QACA,OAAAL;AAAA,QACA,aAAAC;AAAA,QACA,cAAAK;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,gBAAAN;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}

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

@@ -10,6 +10,7 @@ import { DatePickerProps } from '../../../components/Common/UI/DatePicker/DatePi
  *
  * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
  * @public
+ * @group Hook field props
  */
 export interface DatePickerHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps, Pick<DatePickerProps, 'portalContainer' | 'minDate' | 'maxDate'> {
     /** The field name; must match the corresponding key in the form schema. */

package/dist/partner-hook-utils/form/fields/DatePickerHookField.js.map

@@ -1 +1 @@
-{"version":3,"file":"DatePickerHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/DatePickerHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { DatePickerField } from '@/components/Common/Fields/DatePickerField'\nimport type { DatePickerProps } from '@/components/Common/UI/DatePicker/DatePickerTypes'\nimport { normalizeToDate } from '@/helpers/dateFormatting'\n\n/**\n * Props accepted by a date picker field surfaced through a form hook.\n * Exposes `minDate` and `maxDate` bounds (override server-provided constraints when\n * supplied), `portalContainer` for correct stacking inside modals, and\n * `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n */\nexport interface DatePickerHookFieldProps<TErrorCode extends string = never>\n  extends BaseFieldProps, Pick<DatePickerProps, 'portalContainer' | 'minDate' | 'maxDate'> {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default date picker UI component; must accept the same props as `DatePickerProps`. */\n  FieldComponent?: ComponentType<DatePickerProps>\n  /** When used inside a modal, pass the modal backdrop ref's element so the calendar popover stacks correctly. */\n  portalContainer?: DatePickerProps['portalContainer']\n}\n\n/**\n * Date picker field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, label content, and optional date bounds.\n * @returns The rendered date picker field wrapped in the field element registry.\n * @internal\n */\nexport function DatePickerHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  FieldComponent,\n  portalContainer,\n  minDate,\n  maxDate,\n}: DatePickerHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <DatePickerField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      FieldComponent={FieldComponent}\n      portalContainer={portalContainer}\n      minDate={\n        minDate ??\n        (fieldMetadata?.minDate ? (normalizeToDate(fieldMetadata.minDate) ?? undefined) : undefined)\n      }\n      maxDate={\n        maxDate ??\n        (fieldMetadata?.maxDate ? (normalizeToDate(fieldMetadata.maxDate) ?? undefined) : undefined)\n      }\n    />,\n  )\n}\n"],"names":["DatePickerHookField","name","formHookResult","label","description","validationMessages","FieldComponent","portalContainer","minDate","maxDate","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","DatePickerField","normalizeToDate"],"mappings":";;;;;AAwCO,SAASA,EAA+C;AAAA,EAC7D,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,iBAAAC;AAAA,EACA,SAAAC;AAAA,EACA,SAAAC;AACF,GAAyC;AACvC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEb;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIU,IAAgBL,EAAST,CAAI;AAEnC,SAAOe;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAjB;AAAA,QACA,SAAAU;AAAA,QACA,OAAAR;AAAA,QACA,aAAAC;AAAA,QACA,cAAAQ;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,gBAAAT;AAAA,QACA,iBAAAC;AAAA,QACA,SACEC,MACCO,GAAe,UAAWI,EAAgBJ,EAAc,OAAO,KAAK,SAAa;AAAA,QAEpF,SACEN,MACCM,GAAe,UAAWI,EAAgBJ,EAAc,OAAO,KAAK,SAAa;AAAA,MAAA;AAAA,IAAA;AAAA,EAEtF;AAEJ;"}
+{"version":3,"file":"DatePickerHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/DatePickerHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { DatePickerField } from '@/components/Common/Fields/DatePickerField'\nimport type { DatePickerProps } from '@/components/Common/UI/DatePicker/DatePickerTypes'\nimport { normalizeToDate } from '@/helpers/dateFormatting'\n\n/**\n * Props accepted by a date picker field surfaced through a form hook.\n * Exposes `minDate` and `maxDate` bounds (override server-provided constraints when\n * supplied), `portalContainer` for correct stacking inside modals, and\n * `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n * @group Hook field props\n */\nexport interface DatePickerHookFieldProps<TErrorCode extends string = never>\n  extends BaseFieldProps, Pick<DatePickerProps, 'portalContainer' | 'minDate' | 'maxDate'> {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default date picker UI component; must accept the same props as `DatePickerProps`. */\n  FieldComponent?: ComponentType<DatePickerProps>\n  /** When used inside a modal, pass the modal backdrop ref's element so the calendar popover stacks correctly. */\n  portalContainer?: DatePickerProps['portalContainer']\n}\n\n/**\n * Date picker field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, label content, and optional date bounds.\n * @returns The rendered date picker field wrapped in the field element registry.\n * @internal\n */\nexport function DatePickerHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  FieldComponent,\n  portalContainer,\n  minDate,\n  maxDate,\n}: DatePickerHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <DatePickerField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      FieldComponent={FieldComponent}\n      portalContainer={portalContainer}\n      minDate={\n        minDate ??\n        (fieldMetadata?.minDate ? (normalizeToDate(fieldMetadata.minDate) ?? undefined) : undefined)\n      }\n      maxDate={\n        maxDate ??\n        (fieldMetadata?.maxDate ? (normalizeToDate(fieldMetadata.maxDate) ?? undefined) : undefined)\n      }\n    />,\n  )\n}\n"],"names":["DatePickerHookField","name","formHookResult","label","description","validationMessages","FieldComponent","portalContainer","minDate","maxDate","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","DatePickerField","normalizeToDate"],"mappings":";;;;;AAyCO,SAASA,EAA+C;AAAA,EAC7D,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,iBAAAC;AAAA,EACA,SAAAC;AAAA,EACA,SAAAC;AACF,GAAyC;AACvC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEb;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIU,IAAgBL,EAAST,CAAI;AAEnC,SAAOe;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAjB;AAAA,QACA,SAAAU;AAAA,QACA,OAAAR;AAAA,QACA,aAAAC;AAAA,QACA,cAAAQ;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,gBAAAT;AAAA,QACA,iBAAAC;AAAA,QACA,SACEC,MACCO,GAAe,UAAWI,EAAgBJ,EAAc,OAAO,KAAK,SAAa;AAAA,QAEpF,SACEN,MACCM,GAAe,UAAWI,EAAgBJ,EAAc,OAAO,KAAK,SAAa;AAAA,MAAA;AAAA,IAAA;AAAA,EAEtF;AAEJ;"}

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

@@ -9,6 +9,7 @@ import { NumberInputProps } from '../../../components/Common/UI/NumberInput/Numb
  *
  * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
  * @public
+ * @group Hook field props
  */
 export interface NumberInputHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {
     /** The field name; must match the corresponding key in the form schema. */

package/dist/partner-hook-utils/form/fields/NumberInputHookField.js.map

@@ -1 +1 @@
-{"version":3,"file":"NumberInputHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/NumberInputHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { NumberInputField } from '@/components/Common'\nimport type { NumberInputProps } from '@/components/Common/UI/NumberInput/NumberInputTypes'\n\n/**\n * Props accepted by a number input field surfaced through a form hook.\n * Exposes numeric constraints (`min`, `max`), display `format`, `placeholder` text,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n */\nexport interface NumberInputHookFieldProps<\n  TErrorCode extends string = never,\n> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Display format for the number value (e.g. `'currency'`). */\n  format?: NumberInputProps['format']\n  /** Minimum allowed numeric value. */\n  min?: NumberInputProps['min']\n  /** Maximum allowed numeric value. */\n  max?: NumberInputProps['max']\n  /** Placeholder text displayed when the field has no value. */\n  placeholder?: NumberInputProps['placeholder']\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default number input UI component; must accept the same props as `NumberInputProps`. */\n  FieldComponent?: ComponentType<NumberInputProps>\n}\n\n/**\n * Number input field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, formatting, and numeric bounds.\n * @returns The rendered number input field wrapped in the field element registry.\n * @internal\n */\nexport function NumberInputHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  format,\n  min,\n  max,\n  placeholder,\n  validationMessages,\n  FieldComponent,\n}: NumberInputHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <NumberInputField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      format={format}\n      min={min}\n      max={max}\n      placeholder={placeholder}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["NumberInputHookField","name","formHookResult","label","description","format","min","max","placeholder","validationMessages","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","NumberInputField"],"mappings":";;;;;;;AA6CO,SAASA,EAAgD;AAAA,EAC9D,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,QAAAC;AAAA,EACA,KAAAC;AAAA,EACA,KAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AACF,GAA0C;AACxC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEd;AAAA,IACAC;AAAA,IACAO;AAAA,EAAA,GAEIO,IAAgBL,EAASV,CAAI;AAEnC,SAAOgB;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAlB;AAAA,QACA,SAAAW;AAAA,QACA,OAAAT;AAAA,QACA,aAAAC;AAAA,QACA,cAAAS;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,QAAAX;AAAA,QACA,KAAAC;AAAA,QACA,KAAAC;AAAA,QACA,aAAAC;AAAA,QACA,gBAAAE;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}
+{"version":3,"file":"NumberInputHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/NumberInputHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { NumberInputField } from '@/components/Common'\nimport type { NumberInputProps } from '@/components/Common/UI/NumberInput/NumberInputTypes'\n\n/**\n * Props accepted by a number input field surfaced through a form hook.\n * Exposes numeric constraints (`min`, `max`), display `format`, `placeholder` text,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n * @group Hook field props\n */\nexport interface NumberInputHookFieldProps<\n  TErrorCode extends string = never,\n> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Display format for the number value (e.g. `'currency'`). */\n  format?: NumberInputProps['format']\n  /** Minimum allowed numeric value. */\n  min?: NumberInputProps['min']\n  /** Maximum allowed numeric value. */\n  max?: NumberInputProps['max']\n  /** Placeholder text displayed when the field has no value. */\n  placeholder?: NumberInputProps['placeholder']\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default number input UI component; must accept the same props as `NumberInputProps`. */\n  FieldComponent?: ComponentType<NumberInputProps>\n}\n\n/**\n * Number input field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, formatting, and numeric bounds.\n * @returns The rendered number input field wrapped in the field element registry.\n * @internal\n */\nexport function NumberInputHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  format,\n  min,\n  max,\n  placeholder,\n  validationMessages,\n  FieldComponent,\n}: NumberInputHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <NumberInputField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      format={format}\n      min={min}\n      max={max}\n      placeholder={placeholder}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["NumberInputHookField","name","formHookResult","label","description","format","min","max","placeholder","validationMessages","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","NumberInputField"],"mappings":";;;;;;;AA8CO,SAASA,EAAgD;AAAA,EAC9D,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,QAAAC;AAAA,EACA,KAAAC;AAAA,EACA,KAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AACF,GAA0C;AACxC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEd;AAAA,IACAC;AAAA,IACAO;AAAA,EAAA,GAEIO,IAAgBL,EAASV,CAAI;AAEnC,SAAOgB;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAlB;AAAA,QACA,SAAAW;AAAA,QACA,OAAAT;AAAA,QACA,aAAAC;AAAA,QACA,cAAAS;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,QAAAX;AAAA,QACA,KAAAC;AAAA,QACA,KAAAC;AAAA,QACA,aAAAC;AAAA,QACA,gBAAAE;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}

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

@@ -10,6 +10,7 @@ import { RadioGroupProps } from '../../../components/Common/UI/RadioGroup/RadioG
  * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
  * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.
  * @public
+ * @group Hook field props
  */
 export interface RadioGroupHookFieldProps<TErrorCode extends string = never, TEntry = unknown> extends BaseFieldProps {
     /** The field name; must match the corresponding key in the form schema. */

package/dist/partner-hook-utils/form/fields/RadioGroupHookField.js.map

@@ -1 +1 @@
-{"version":3,"file":"RadioGroupHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/RadioGroupHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport { getFieldWithOptions } from '../getFieldWithOptions'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { RadioGroupField } from '@/components/Common'\nimport type { RadioGroupProps } from '@/components/Common/UI/RadioGroup/RadioGroupTypes'\n\n/**\n * Props accepted by a radio group field surfaced through a form hook.\n * Exposes `getOptionLabel` to customize how option entries are rendered as labels,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @public\n */\nexport interface RadioGroupHookFieldProps<\n  TErrorCode extends string = never,\n  TEntry = unknown,\n> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook. */\n  getOptionLabel?: (entry: TEntry) => string\n  /** Replaces the default radio group UI component; must accept the same props as `RadioGroupProps`. */\n  FieldComponent?: ComponentType<RadioGroupProps>\n}\n\n/**\n * Radio group field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @param props - Field configuration including `name`, `formHookResult`, and an optional `getOptionLabel`.\n * @returns The rendered radio group field wrapped in the field element registry.\n * @internal\n */\nexport function RadioGroupHookField<TErrorCode extends string, TEntry = unknown>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  getOptionLabel,\n  FieldComponent,\n}: RadioGroupHookFieldProps<TErrorCode, TEntry>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = getFieldWithOptions<TEntry>(metadata, name)\n\n  const defaultOptions = fieldMetadata?.options ?? []\n  const options =\n    getOptionLabel && fieldMetadata?.entries\n      ? fieldMetadata.entries.map((entry, index) => ({\n          value: defaultOptions[index]?.value ?? '',\n          label: getOptionLabel(entry),\n        }))\n      : defaultOptions\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <RadioGroupField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      options={options}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["RadioGroupHookField","name","formHookResult","label","description","validationMessages","getOptionLabel","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","getFieldWithOptions","defaultOptions","options","entry","index","withFieldElementRegistry","jsx","RadioGroupField"],"mappings":";;;;;;;;AA2CO,SAASA,EAAiE;AAAA,EAC/E,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,gBAAAC;AACF,GAAiD;AAC/C,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEX;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIQ,IAAgBC,EAA4BN,GAAUP,CAAI,GAE1Dc,IAAiBF,GAAe,WAAW,CAAA,GAC3CG,IACJV,KAAkBO,GAAe,UAC7BA,EAAc,QAAQ,IAAI,CAACI,GAAOC,OAAW;AAAA,IAC3C,OAAOH,EAAeG,CAAK,GAAG,SAAS;AAAA,IACvC,OAAOZ,EAAeW,CAAK;AAAA,EAAA,EAC3B,IACFF;AAEN,SAAOI;AAAA,IACLR;AAAA,IACA,gBAAAS;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAApB;AAAA,QACA,SAAAQ;AAAA,QACA,OAAAN;AAAA,QACA,aAAAC;AAAA,QACA,cAAAM;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,SAAAG;AAAA,QACA,gBAAAT;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}
+{"version":3,"file":"RadioGroupHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/RadioGroupHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport { getFieldWithOptions } from '../getFieldWithOptions'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { RadioGroupField } from '@/components/Common'\nimport type { RadioGroupProps } from '@/components/Common/UI/RadioGroup/RadioGroupTypes'\n\n/**\n * Props accepted by a radio group field surfaced through a form hook.\n * Exposes `getOptionLabel` to customize how option entries are rendered as labels,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @public\n * @group Hook field props\n */\nexport interface RadioGroupHookFieldProps<\n  TErrorCode extends string = never,\n  TEntry = unknown,\n> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook. */\n  getOptionLabel?: (entry: TEntry) => string\n  /** Replaces the default radio group UI component; must accept the same props as `RadioGroupProps`. */\n  FieldComponent?: ComponentType<RadioGroupProps>\n}\n\n/**\n * Radio group field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @param props - Field configuration including `name`, `formHookResult`, and an optional `getOptionLabel`.\n * @returns The rendered radio group field wrapped in the field element registry.\n * @internal\n */\nexport function RadioGroupHookField<TErrorCode extends string, TEntry = unknown>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  getOptionLabel,\n  FieldComponent,\n}: RadioGroupHookFieldProps<TErrorCode, TEntry>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = getFieldWithOptions<TEntry>(metadata, name)\n\n  const defaultOptions = fieldMetadata?.options ?? []\n  const options =\n    getOptionLabel && fieldMetadata?.entries\n      ? fieldMetadata.entries.map((entry, index) => ({\n          value: defaultOptions[index]?.value ?? '',\n          label: getOptionLabel(entry),\n        }))\n      : defaultOptions\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <RadioGroupField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      options={options}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["RadioGroupHookField","name","formHookResult","label","description","validationMessages","getOptionLabel","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","getFieldWithOptions","defaultOptions","options","entry","index","withFieldElementRegistry","jsx","RadioGroupField"],"mappings":";;;;;;;;AA4CO,SAASA,EAAiE;AAAA,EAC/E,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,gBAAAC;AACF,GAAiD;AAC/C,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEX;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIQ,IAAgBC,EAA4BN,GAAUP,CAAI,GAE1Dc,IAAiBF,GAAe,WAAW,CAAA,GAC3CG,IACJV,KAAkBO,GAAe,UAC7BA,EAAc,QAAQ,IAAI,CAACI,GAAOC,OAAW;AAAA,IAC3C,OAAOH,EAAeG,CAAK,GAAG,SAAS;AAAA,IACvC,OAAOZ,EAAeW,CAAK;AAAA,EAAA,EAC3B,IACFF;AAEN,SAAOI;AAAA,IACLR;AAAA,IACA,gBAAAS;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAApB;AAAA,QACA,SAAAQ;AAAA,QACA,OAAAN;AAAA,QACA,aAAAC;AAAA,QACA,cAAAM;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,SAAAG;AAAA,QACA,gBAAAT;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}

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

@@ -11,6 +11,7 @@ import { SelectProps } from '../../../components/Common/UI/Select/SelectTypes';
  * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
  * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.
  * @public
+ * @group Hook field props
  */
 export interface SelectHookFieldProps<TErrorCode extends string = never, TEntry = unknown> extends BaseFieldProps, Pick<SelectProps, 'portalContainer'> {
     /** The field name; must match the corresponding key in the form schema. */

package/dist/partner-hook-utils/form/fields/SelectHookField.js.map

@@ -1 +1 @@
-{"version":3,"file":"SelectHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/SelectHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport { getFieldWithOptions } from '../getFieldWithOptions'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { SelectField } from '@/components/Common'\nimport type { SelectProps } from '@/components/Common/UI/Select/SelectTypes'\n\n/**\n * Props accepted by a select field surfaced through a form hook.\n * Exposes `getOptionLabel` to customize how option entries are rendered as labels,\n * `placeholder` text, `portalContainer` for correct stacking inside modals,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @public\n */\nexport interface SelectHookFieldProps<TErrorCode extends string = never, TEntry = unknown>\n  extends BaseFieldProps, Pick<SelectProps, 'portalContainer'> {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook. */\n  getOptionLabel?: (entry: TEntry) => string\n  /**\n   * Placeholder text displayed when no option is selected.\n   * Required so empty dropdowns always communicate the action — pass an empty string only when a default value is guaranteed.\n   */\n  placeholder: string\n  /** Replaces the default select UI component; must accept the same props as `SelectProps`. */\n  FieldComponent?: ComponentType<SelectProps>\n  /** When used inside a modal, pass the modal backdrop ref's element so the listbox stacks correctly. */\n  portalContainer?: SelectProps['portalContainer']\n}\n\n/**\n * Select field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @param props - Field configuration including `name`, `formHookResult`, and an optional `getOptionLabel`.\n * @returns The rendered select field wrapped in the field element registry.\n * @internal\n */\nexport function SelectHookField<TErrorCode extends string, TEntry = unknown>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  getOptionLabel,\n  placeholder,\n  FieldComponent,\n  portalContainer,\n}: SelectHookFieldProps<TErrorCode, TEntry>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = getFieldWithOptions<TEntry>(metadata, name)\n\n  const defaultOptions = fieldMetadata?.options ?? []\n  const options =\n    getOptionLabel && fieldMetadata?.entries\n      ? fieldMetadata.entries.map((entry, index) => ({\n          value: defaultOptions[index]?.value ?? '',\n          label: getOptionLabel(entry),\n        }))\n      : defaultOptions\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <SelectField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      options={options}\n      placeholder={placeholder}\n      FieldComponent={FieldComponent}\n      portalContainer={portalContainer}\n    />,\n  )\n}\n"],"names":["SelectHookField","name","formHookResult","label","description","validationMessages","getOptionLabel","placeholder","FieldComponent","portalContainer","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","getFieldWithOptions","defaultOptions","options","entry","index","withFieldElementRegistry","jsx","SelectField"],"mappings":";;;;;;;;AAiDO,SAASA,EAA6D;AAAA,EAC3E,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,aAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,iBAAAC;AACF,GAA6C;AAC3C,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEb;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIU,IAAgBC,EAA4BN,GAAUT,CAAI,GAE1DgB,IAAiBF,GAAe,WAAW,CAAA,GAC3CG,IACJZ,KAAkBS,GAAe,UAC7BA,EAAc,QAAQ,IAAI,CAACI,GAAOC,OAAW;AAAA,IAC3C,OAAOH,EAAeG,CAAK,GAAG,SAAS;AAAA,IACvC,OAAOd,EAAea,CAAK;AAAA,EAAA,EAC3B,IACFF;AAEN,SAAOI;AAAA,IACLR;AAAA,IACA,gBAAAS;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAtB;AAAA,QACA,SAAAU;AAAA,QACA,OAAAR;AAAA,QACA,aAAAC;AAAA,QACA,cAAAQ;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,SAAAG;AAAA,QACA,aAAAX;AAAA,QACA,gBAAAC;AAAA,QACA,iBAAAC;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}
+{"version":3,"file":"SelectHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/SelectHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport { getFieldWithOptions } from '../getFieldWithOptions'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { SelectField } from '@/components/Common'\nimport type { SelectProps } from '@/components/Common/UI/Select/SelectTypes'\n\n/**\n * Props accepted by a select field surfaced through a form hook.\n * Exposes `getOptionLabel` to customize how option entries are rendered as labels,\n * `placeholder` text, `portalContainer` for correct stacking inside modals,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @public\n * @group Hook field props\n */\nexport interface SelectHookFieldProps<TErrorCode extends string = never, TEntry = unknown>\n  extends BaseFieldProps, Pick<SelectProps, 'portalContainer'> {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook. */\n  getOptionLabel?: (entry: TEntry) => string\n  /**\n   * Placeholder text displayed when no option is selected.\n   * Required so empty dropdowns always communicate the action — pass an empty string only when a default value is guaranteed.\n   */\n  placeholder: string\n  /** Replaces the default select UI component; must accept the same props as `SelectProps`. */\n  FieldComponent?: ComponentType<SelectProps>\n  /** When used inside a modal, pass the modal backdrop ref's element so the listbox stacks correctly. */\n  portalContainer?: SelectProps['portalContainer']\n}\n\n/**\n * Select field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @typeParam TEntry - Shape of each option entry consumed by `getOptionLabel`.\n * @param props - Field configuration including `name`, `formHookResult`, and an optional `getOptionLabel`.\n * @returns The rendered select field wrapped in the field element registry.\n * @internal\n */\nexport function SelectHookField<TErrorCode extends string, TEntry = unknown>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  getOptionLabel,\n  placeholder,\n  FieldComponent,\n  portalContainer,\n}: SelectHookFieldProps<TErrorCode, TEntry>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = getFieldWithOptions<TEntry>(metadata, name)\n\n  const defaultOptions = fieldMetadata?.options ?? []\n  const options =\n    getOptionLabel && fieldMetadata?.entries\n      ? fieldMetadata.entries.map((entry, index) => ({\n          value: defaultOptions[index]?.value ?? '',\n          label: getOptionLabel(entry),\n        }))\n      : defaultOptions\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <SelectField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      options={options}\n      placeholder={placeholder}\n      FieldComponent={FieldComponent}\n      portalContainer={portalContainer}\n    />,\n  )\n}\n"],"names":["SelectHookField","name","formHookResult","label","description","validationMessages","getOptionLabel","placeholder","FieldComponent","portalContainer","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","getFieldWithOptions","defaultOptions","options","entry","index","withFieldElementRegistry","jsx","SelectField"],"mappings":";;;;;;;;AAkDO,SAASA,EAA6D;AAAA,EAC3E,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,aAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,iBAAAC;AACF,GAA6C;AAC3C,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEb;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIU,IAAgBC,EAA4BN,GAAUT,CAAI,GAE1DgB,IAAiBF,GAAe,WAAW,CAAA,GAC3CG,IACJZ,KAAkBS,GAAe,UAC7BA,EAAc,QAAQ,IAAI,CAACI,GAAOC,OAAW;AAAA,IAC3C,OAAOH,EAAeG,CAAK,GAAG,SAAS;AAAA,IACvC,OAAOd,EAAea,CAAK;AAAA,EAAA,EAC3B,IACFF;AAEN,SAAOI;AAAA,IACLR;AAAA,IACA,gBAAAS;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAtB;AAAA,QACA,SAAAU;AAAA,QACA,OAAAR;AAAA,QACA,aAAAC;AAAA,QACA,cAAAQ;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,SAAAG;AAAA,QACA,aAAAX;AAAA,QACA,gBAAAC;AAAA,QACA,iBAAAC;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}

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

@@ -8,6 +8,7 @@ import { SwitchProps } from '../../../components/Common/UI/Switch/SwitchTypes';
  *
  * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.
  * @public
+ * @group Hook field props
  */
 export interface SwitchHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {
     /** The field name; must match the corresponding key in the form schema. */

package/dist/partner-hook-utils/form/fields/SwitchHookField.js.map

@@ -1 +1 @@
-{"version":3,"file":"SwitchHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/SwitchHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { SwitchField } from '@/components/Common'\nimport type { SwitchProps } from '@/components/Common/UI/Switch/SwitchTypes'\n\n/**\n * Props accepted by a toggle switch field surfaced through a form hook.\n * Exposes `validationMessages` for custom error text alongside the shared base\n * field attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n */\nexport interface SwitchHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default toggle switch UI component; must accept the same props as `SwitchProps`. */\n  FieldComponent?: ComponentType<SwitchProps>\n}\n\n/**\n * Switch field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, and label content.\n * @returns The rendered switch field wrapped in the field element registry.\n * @internal\n */\nexport function SwitchHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  FieldComponent,\n}: SwitchHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <SwitchField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["SwitchHookField","name","formHookResult","label","description","validationMessages","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","SwitchField"],"mappings":";;;;;;;AAkCO,SAASA,EAA2C;AAAA,EACzD,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AACF,GAAqC;AACnC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEV;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIO,IAAgBL,EAASN,CAAI;AAEnC,SAAOY;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAd;AAAA,QACA,SAAAO;AAAA,QACA,OAAAL;AAAA,QACA,aAAAC;AAAA,QACA,cAAAK;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,gBAAAN;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}
+{"version":3,"file":"SwitchHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/SwitchHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { SwitchField } from '@/components/Common'\nimport type { SwitchProps } from '@/components/Common/UI/Switch/SwitchTypes'\n\n/**\n * Props accepted by a toggle switch field surfaced through a form hook.\n * Exposes `validationMessages` for custom error text alongside the shared base\n * field attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @public\n * @group Hook field props\n */\nexport interface SwitchHookFieldProps<TErrorCode extends string = never> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode>\n  /** Replaces the default toggle switch UI component; must accept the same props as `SwitchProps`. */\n  FieldComponent?: ComponentType<SwitchProps>\n}\n\n/**\n * Switch field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, and label content.\n * @returns The rendered switch field wrapped in the field element registry.\n * @internal\n */\nexport function SwitchHookField<TErrorCode extends string>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  FieldComponent,\n}: SwitchHookFieldProps<TErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <SwitchField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["SwitchHookField","name","formHookResult","label","description","validationMessages","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","SwitchField"],"mappings":";;;;;;;AAmCO,SAASA,EAA2C;AAAA,EACzD,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,gBAAAC;AACF,GAAqC;AACnC,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEV;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIO,IAAgBL,EAASN,CAAI;AAEnC,SAAOY;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAd;AAAA,QACA,SAAAO;AAAA,QACA,OAAAL;AAAA,QACA,aAAAC;AAAA,QACA,cAAAK;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,gBAAAN;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}

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

@@ -10,6 +10,7 @@ import { TextInputProps } from '../../../components/Common/UI/TextInput/TextInpu
  * @typeParam TErrorCode - Required validation error code keys mapped via `validationMessages`.
  * @typeParam TOptionalErrorCode - Optional validation error code keys mapped via `validationMessages`.
  * @public
+ * @group Hook field props
  */
 export interface TextInputHookFieldProps<TErrorCode extends string = never, TOptionalErrorCode extends string = never> extends BaseFieldProps {
     /** The field name; must match the corresponding key in the form schema. */

package/dist/partner-hook-utils/form/fields/TextInputHookField.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextInputHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/TextInputHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { TextInputField } from '@/components/Common'\nimport type { TextInputProps } from '@/components/Common/UI/TextInput/TextInputTypes'\n\n/**\n * Props accepted by a text input field surfaced through a form hook.\n * Exposes a `transform` function for preprocessing raw input, `placeholder` text,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Required validation error code keys mapped via `validationMessages`.\n * @typeParam TOptionalErrorCode - Optional validation error code keys mapped via `validationMessages`.\n * @public\n */\nexport interface TextInputHookFieldProps<\n  TErrorCode extends string = never,\n  TOptionalErrorCode extends string = never,\n> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode, TOptionalErrorCode>\n  /** Transforms the raw string value on every change before storing it; use for normalization such as trimming or changing case. */\n  transform?: (value: string) => string\n  /** Placeholder text displayed when the field has no value. */\n  placeholder?: string\n  /** Replaces the default text input UI component; must accept the same props as `TextInputProps`. */\n  FieldComponent?: ComponentType<TextInputProps>\n}\n\n/**\n * Text input field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Required validation error code keys mapped via `validationMessages`.\n * @typeParam TOptionalErrorCode - Optional validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, `transform`, `placeholder`, and label content.\n * @returns The rendered text input field wrapped in the field element registry.\n * @internal\n */\nexport function TextInputHookField<\n  TErrorCode extends string,\n  TOptionalErrorCode extends string = never,\n>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  transform,\n  placeholder,\n  FieldComponent,\n}: TextInputHookFieldProps<TErrorCode, TOptionalErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <TextInputField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      transform={transform}\n      placeholder={placeholder}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["TextInputHookField","name","formHookResult","label","description","validationMessages","transform","placeholder","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","TextInputField"],"mappings":";;;;;;;AA4CO,SAASA,EAGd;AAAA,EACA,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,WAAAC;AAAA,EACA,aAAAC;AAAA,EACA,gBAAAC;AACF,GAA4D;AAC1D,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEZ;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIS,IAAgBL,EAASR,CAAI;AAEnC,SAAOc;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAhB;AAAA,QACA,SAAAS;AAAA,QACA,OAAAP;AAAA,QACA,aAAAC;AAAA,QACA,cAAAO;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,WAAAR;AAAA,QACA,aAAAC;AAAA,QACA,gBAAAC;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}
+{"version":3,"file":"TextInputHookField.js","sources":["../../../../src/partner-hook-utils/form/fields/TextInputHookField.tsx"],"sourcesContent":["import type { ComponentType } from 'react'\nimport { useHookFieldResolution } from '../useHookFieldResolution'\nimport type { BaseFieldProps, ValidationMessages, FormHookResult } from '../../types'\nimport { withFieldElementRegistry } from './withFieldElementRegistry'\nimport { TextInputField } from '@/components/Common'\nimport type { TextInputProps } from '@/components/Common/UI/TextInput/TextInputTypes'\n\n/**\n * Props accepted by a text input field surfaced through a form hook.\n * Exposes a `transform` function for preprocessing raw input, `placeholder` text,\n * and `validationMessages` for custom error text alongside the shared base field\n * attributes (`label`, `description`).\n *\n * @typeParam TErrorCode - Required validation error code keys mapped via `validationMessages`.\n * @typeParam TOptionalErrorCode - Optional validation error code keys mapped via `validationMessages`.\n * @public\n * @group Hook field props\n */\nexport interface TextInputHookFieldProps<\n  TErrorCode extends string = never,\n  TOptionalErrorCode extends string = never,\n> extends BaseFieldProps {\n  /** The field name; must match the corresponding key in the form schema. */\n  name: string\n  /** Form hook result to connect to; falls back to the nearest `SDKFormProvider` when omitted. */\n  formHookResult?: FormHookResult\n  /** Custom error text keyed by validation error code. */\n  validationMessages?: ValidationMessages<TErrorCode, TOptionalErrorCode>\n  /** Transforms the raw string value on every change before storing it; use for normalization such as trimming or changing case. */\n  transform?: (value: string) => string\n  /** Placeholder text displayed when the field has no value. */\n  placeholder?: string\n  /** Replaces the default text input UI component; must accept the same props as `TextInputProps`. */\n  FieldComponent?: ComponentType<TextInputProps>\n}\n\n/**\n * Text input field connected to a partner form hook result via `useHookFieldResolution`.\n *\n * @typeParam TErrorCode - Required validation error code keys mapped via `validationMessages`.\n * @typeParam TOptionalErrorCode - Optional validation error code keys mapped via `validationMessages`.\n * @param props - Field configuration including `name`, `formHookResult`, `transform`, `placeholder`, and label content.\n * @returns The rendered text input field wrapped in the field element registry.\n * @internal\n */\nexport function TextInputHookField<\n  TErrorCode extends string,\n  TOptionalErrorCode extends string = never,\n>({\n  name,\n  formHookResult,\n  label,\n  description,\n  validationMessages,\n  transform,\n  placeholder,\n  FieldComponent,\n}: TextInputHookFieldProps<TErrorCode, TOptionalErrorCode>) {\n  const { metadata, control, errorMessage, fieldElementRegistry } = useHookFieldResolution(\n    name,\n    formHookResult,\n    validationMessages,\n  )\n  const fieldMetadata = metadata[name]\n\n  return withFieldElementRegistry(\n    fieldElementRegistry,\n    <TextInputField\n      name={name}\n      control={control}\n      label={label}\n      description={description}\n      errorMessage={errorMessage}\n      isRequired={fieldMetadata?.isRequired}\n      isDisabled={fieldMetadata?.isDisabled}\n      transform={transform}\n      placeholder={placeholder}\n      FieldComponent={FieldComponent}\n    />,\n  )\n}\n"],"names":["TextInputHookField","name","formHookResult","label","description","validationMessages","transform","placeholder","FieldComponent","metadata","control","errorMessage","fieldElementRegistry","useHookFieldResolution","fieldMetadata","withFieldElementRegistry","jsx","TextInputField"],"mappings":";;;;;;;AA6CO,SAASA,EAGd;AAAA,EACA,MAAAC;AAAA,EACA,gBAAAC;AAAA,EACA,OAAAC;AAAA,EACA,aAAAC;AAAA,EACA,oBAAAC;AAAA,EACA,WAAAC;AAAA,EACA,aAAAC;AAAA,EACA,gBAAAC;AACF,GAA4D;AAC1D,QAAM,EAAE,UAAAC,GAAU,SAAAC,GAAS,cAAAC,GAAc,sBAAAC,MAAyBC;AAAA,IAChEZ;AAAA,IACAC;AAAA,IACAG;AAAA,EAAA,GAEIS,IAAgBL,EAASR,CAAI;AAEnC,SAAOc;AAAA,IACLH;AAAA,IACA,gBAAAI;AAAA,MAACC;AAAA,MAAA;AAAA,QACC,MAAAhB;AAAA,QACA,SAAAS;AAAA,QACA,OAAAP;AAAA,QACA,aAAAC;AAAA,QACA,cAAAO;AAAA,QACA,YAAYG,GAAe;AAAA,QAC3B,YAAYA,GAAe;AAAA,QAC3B,WAAAR;AAAA,QACA,aAAAC;AAAA,QACA,gBAAAC;AAAA,MAAA;AAAA,IAAA;AAAA,EACF;AAEJ;"}

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

@@ -77,6 +77,7 @@ export type ValidationMessages<TErrorCode extends string, TOptionalErrorCode ext
  * Common presentation props accepted by every hook field component.
  *
  * @public
+ * @group Hook field props
  */
 export interface BaseFieldProps {
     /** Visible label rendered above the field. */
@@ -90,6 +91,7 @@ export interface BaseFieldProps {
  *
  * @typeParam TProps - Original hook field props type that includes a `name` property.
  * @public
+ * @group Hook field props
  */
 export type HookFieldProps<TProps extends {
     name: string;
@@ -107,6 +109,7 @@ export type HookFieldProps<TProps extends {
  *
  * @typeParam TFormData - Shape of the form values managed by react-hook-form.
  * @public
+ * @group Form hook results
  */
 export interface HookFormInternals<TFormData extends FieldValues = FieldValues> {
     /** The full react-hook-form return value; use for watching fields, setting values, or triggering validation. */
@@ -138,6 +141,7 @@ export interface HookFormInternals<TFormData extends FieldValues = FieldValues>
  * ready-state shape (data, form, actions, status) becomes available.
  *
  * @public
+ * @group Common hook results
  */
 export interface HookLoadingResult {
     /** Always `true` in this branch; narrows to `false` once the hook's ready-state shape is available. */
@@ -156,6 +160,7 @@ export interface HookLoadingResult {
  *
  * @typeParam T - Type of the saved entity returned by the underlying mutation.
  * @public
+ * @group Form hook results
  */
 export interface HookSubmitResult<T> {
     /** Whether the submission created a new entity or updated an existing one. */
@@ -175,6 +180,7 @@ export interface HookSubmitResult<T> {
  * the supported way to discriminate fetch vs submit failures today.
  *
  * @public
+ * @group Common hook results
  */
 export interface HookErrorHandling {
     /** Aggregated fetch and submit errors as normalized {@link SDKError} values. */
@@ -196,6 +202,7 @@ export interface HookErrorHandling {
  * @typeParam TData - Shape of the data the hook exposes once loaded.
  * @typeParam TStatus - Shape of the status flags the hook exposes.
  * @public
+ * @group Common hook results
  */
 export interface BaseHookReady<TData extends Record<string, unknown> = Record<string, unknown>, TStatus extends Record<string, unknown> = Record<string, unknown>> {
     /** Always `false` in this branch; discriminates from {@link HookLoadingResult}. */
@@ -225,6 +232,7 @@ export interface BaseHookReady<TData extends Record<string, unknown> = Record<st
  * @typeParam TFields - Shape of the pre-bound `Fields` component map.
  * @typeParam TFormOutputs - Shape of the values produced once the schema parses on submit (the resolver output / `TTransformedValues`). Defaults to `TFormData`, which holds whenever the form's input and parsed-output shapes coincide; pass it explicitly when a schema transform makes them diverge.
  * @public
+ * @group Form hook results
  */
 export interface BaseFormHookReady<TFieldsMetadata extends FieldsMetadata = FieldsMetadata, TFormData extends FieldValues = FieldValues, TFields extends object = Record<string, unknown>, TFormOutputs = TFormData> {
     /** Always `false` in this branch; discriminates from {@link HookLoadingResult}. */
@@ -259,6 +267,7 @@ export interface BaseFormHookReady<TFieldsMetadata extends FieldsMetadata = Fiel
  * under an `SDKFormProvider`.
  *
  * @public
+ * @group Form hook results
  * @privateRemarks
  * `_fieldElementRegistry` is forwarded from {@link HookFormInternals} so HookFields
  * can self-publish the registry for descendant `useField` calls when partners

package/dist/shared/constants.d.ts

@@ -185,6 +185,7 @@ export declare const companyEvents: {
 export declare const contractorEvents: {
     readonly CONTRACTOR_SELF_ONBOARDING_START: "contractor/selfOnboarding/start";
     readonly CONTRACTOR_SELF_ONBOARDING_DONE: "contractor/selfOnboarding/done";
+    readonly CONTRACTOR_SELF_ONBOARDING_CANCELLED: "contractor/selfOnboarding/cancelled";
     readonly CONTRACTOR_ADDRESS_UPDATED: "contractor/address/updated";
     readonly CONTRACTOR_ADDRESS_DONE: "contractor/address/done";
     readonly CONTRACTOR_PAYMENT_METHOD_UPDATED: "contractor/paymentMethod/updated";
@@ -553,6 +554,7 @@ export declare const componentEvents: {
     readonly RUN_PAYROLL_GROSS_UP_CALCULATED: "runPayroll/grossUp/calculated";
     readonly CONTRACTOR_SELF_ONBOARDING_START: "contractor/selfOnboarding/start";
     readonly CONTRACTOR_SELF_ONBOARDING_DONE: "contractor/selfOnboarding/done";
+    readonly CONTRACTOR_SELF_ONBOARDING_CANCELLED: "contractor/selfOnboarding/cancelled";
     readonly CONTRACTOR_ADDRESS_UPDATED: "contractor/address/updated";
     readonly CONTRACTOR_ADDRESS_DONE: "contractor/address/done";
     readonly CONTRACTOR_PAYMENT_METHOD_UPDATED: "contractor/paymentMethod/updated";
@@ -765,6 +767,7 @@ export type EventType = (typeof componentEvents)[keyof typeof componentEvents];
  * record. The values mirror the strings returned by the API.
  *
  * @public
+ * @page employee/types
  */
 export declare const EmployeeOnboardingStatus: {
     readonly ADMIN_ONBOARDING_INCOMPLETE: "admin_onboarding_incomplete";
@@ -785,6 +788,7 @@ export declare const EmployeeOnboardingStatus: {
  * flow (invited, started, or overdue) versus an admin-driven onboarding flow.
  *
  * @public
+ * @page employee/types
  */
 export declare const EmployeeSelfOnboardingStatuses: Set<string>;
 /**
@@ -795,6 +799,7 @@ export declare const EmployeeSelfOnboardingStatuses: Set<string>;
  * record. The values mirror the strings returned by the API.
  *
  * @public
+ * @page contractor/types
  */
 export declare const ContractorOnboardingStatus: {
     readonly ADMIN_ONBOARDING_INCOMPLETE: "admin_onboarding_incomplete";
@@ -815,6 +820,7 @@ export declare const ContractorOnboardingStatus: {
  * onboarding flow.
  *
  * @public
+ * @page contractor/types
  */
 export declare const ContractorSelfOnboardingStatuses: Set<ContractorOnboardingStatus1>;
 /**
@@ -862,6 +868,7 @@ export declare const HOURS_PER_PAY_PERIOD_ANNUALLY = 2080;
  * `SignatureForm`.
  *
  * @public
+ * @page employee/types
  */
 export declare const I9_FORM_NAME = "US_I-9";
 /**
@@ -869,6 +876,7 @@ export declare const I9_FORM_NAME = "US_I-9";
  * in state selection controls.
  *
  * @public
+ * @page employee/types
  */
 export declare const STATES_ABBR: readonly ["AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY"];
 /**
@@ -876,6 +884,7 @@ export declare const STATES_ABBR: readonly ["AL", "AK", "AZ", "AR", "CA", "CO",
  * {@link STATES_ABBR}.
  *
  * @public
+ * @page employee/types
  */
 export type StateAbbreviation = (typeof STATES_ABBR)[number];
 /** @internal */
@@ -892,6 +901,7 @@ export declare const SIGNATORY_TITLES: {
  * Pay period unit values for the `paymentUnit` field on a compensation, describing the unit a pay rate is expressed against.
  *
  * @public
+ * @page employee/types
  */
 export declare const PAY_PERIODS: {
     readonly HOUR: "Hour";