@gusto/embedded-react-sdk 0.47.1 → 0.48.0

package/dist/components/Employee/Profile/shared/useHomeAddressForm/homeAddressSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"homeAddressSchema.js","sources":["../../../../../../src/components/Employee/Profile/shared/useHomeAddressForm/homeAddressSchema.ts"],"sourcesContent":["import { z } from 'zod'\nimport {\n  buildFormSchema,\n  type RequiredFieldConfig,\n  type OptionalFieldsToRequire,\n} from '@/partner-hook-utils/form/buildFormSchema'\n\n// ── Error codes ────────────────────────────────────────────────────────\n\nexport const HomeAddressErrorCodes = {\n  REQUIRED: 'REQUIRED',\n  INVALID_ZIP: 'INVALID_ZIP',\n} as const\n\nexport type HomeAddressErrorCode =\n  (typeof HomeAddressErrorCodes)[keyof typeof HomeAddressErrorCodes]\n\n// ── Field validators ───────────────────────────────────────────────────\n\nconst ZIP_REGEX = /(^\\d{5}$)|(^\\d{5}-\\d{4}$)/\n\nconst fieldValidators = {\n  street1: z.string(),\n  street2: z.string(),\n  city: z.string(),\n  state: z.string(),\n  zip: z.string().regex(ZIP_REGEX, { message: HomeAddressErrorCodes.INVALID_ZIP }),\n  courtesyWithholding: z.boolean(),\n  effectiveDate: z.iso.date({ error: () => HomeAddressErrorCodes.REQUIRED }),\n}\n\nexport type HomeAddressField = keyof typeof fieldValidators\n\nexport type HomeAddressFormData = {\n  [K in keyof typeof fieldValidators]: z.infer<(typeof fieldValidators)[K]>\n}\nexport type HomeAddressFormOutputs = HomeAddressFormData\n\n// ── Required fields config ─────────────────────────────────────────────\n\nconst requiredFieldsConfig = {\n  street2: 'never',\n} satisfies RequiredFieldConfig<typeof fieldValidators>\n\n// ── Schema factory ─────────────────────────────────────────────────────\n\nexport type HomeAddressOptionalFieldsToRequire = OptionalFieldsToRequire<\n  typeof requiredFieldsConfig\n>\n\ninterface HomeAddressSchemaOptions {\n  mode?: 'create' | 'update'\n  optionalFieldsToRequire?: HomeAddressOptionalFieldsToRequire\n  withEffectiveDateField?: boolean\n}\n\nexport function createHomeAddressSchema(options: HomeAddressSchemaOptions = {}) {\n  const { mode = 'create', optionalFieldsToRequire, withEffectiveDateField = true } = options\n\n  return buildFormSchema(fieldValidators, {\n    requiredFieldsConfig,\n    requiredErrorCode: HomeAddressErrorCodes.REQUIRED,\n    mode,\n    optionalFieldsToRequire,\n    excludeFields: withEffectiveDateField ? [] : ['effectiveDate'],\n  })\n}\n"],"names":["HomeAddressErrorCodes","ZIP_REGEX","fieldValidators","z","requiredFieldsConfig","createHomeAddressSchema","options","mode","optionalFieldsToRequire","withEffectiveDateField","buildFormSchema"],"mappings":";;AASO,MAAMA,IAAwB;AAAA,EACnC,UAAU;AAAA,EACV,aAAa;AACf,GAOMC,IAAY,6BAEZC,IAAkB;AAAA,EACtB,SAASC,EAAE,OAAA;AAAA,EACX,SAASA,EAAE,OAAA;AAAA,EACX,MAAMA,EAAE,OAAA;AAAA,EACR,OAAOA,EAAE,OAAA;AAAA,EACT,KAAKA,EAAE,OAAA,EAAS,MAAMF,GAAW,EAAE,SAASD,EAAsB,aAAa;AAAA,EAC/E,qBAAqBG,EAAE,QAAA;AAAA,EACvB,eAAeA,EAAE,IAAI,KAAK,EAAE,OAAO,MAAMH,EAAsB,SAAA,CAAU;AAC3E,GAWMI,IAAuB;AAAA,EAC3B,SAAS;AACX;AAcO,SAASC,EAAwBC,IAAoC,IAAI;AAC9E,QAAM,EAAE,MAAAC,IAAO,UAAU,yBAAAC,GAAyB,wBAAAC,IAAyB,OAASH;AAEpF,SAAOI,EAAgBR,GAAiB;AAAA,IACtC,sBAAAE;AAAA,IACA,mBAAmBJ,EAAsB;AAAA,IACzC,MAAAO;AAAA,IACA,yBAAAC;AAAA,IACA,eAAeC,IAAyB,CAAA,IAAK,CAAC,eAAe;AAAA,EAAA,CAC9D;AACH;"}
+{"version":3,"file":"homeAddressSchema.js","sources":["../../../../../../src/components/Employee/Profile/shared/useHomeAddressForm/homeAddressSchema.ts"],"sourcesContent":["import { z } from 'zod'\nimport {\n  buildFormSchema,\n  type RequiredFieldConfig,\n  type OptionalFieldsToRequire,\n} from '@/partner-hook-utils/form/buildFormSchema'\n\n// ── Error codes ────────────────────────────────────────────────────────\n\n/**\n * Validation error codes emitted by the home address form schema. Map these\n * codes to localized copy in `validationMessages` when composing the hook.\n *\n * @public\n */\nexport const HomeAddressErrorCodes = {\n  REQUIRED: 'REQUIRED',\n  INVALID_ZIP: 'INVALID_ZIP',\n} as const\n\n/**\n * Union of validation error code strings emitted by the home address form\n * schema.\n *\n * @public\n */\nexport type HomeAddressErrorCode =\n  (typeof HomeAddressErrorCodes)[keyof typeof HomeAddressErrorCodes]\n\n// ── Field validators ───────────────────────────────────────────────────\n\nconst ZIP_REGEX = /(^\\d{5}$)|(^\\d{5}-\\d{4}$)/\n\nconst fieldValidators = {\n  street1: z.string(),\n  street2: z.string(),\n  city: z.string(),\n  state: z.string(),\n  zip: z.string().regex(ZIP_REGEX, { message: HomeAddressErrorCodes.INVALID_ZIP }),\n  courtesyWithholding: z.boolean(),\n  effectiveDate: z.iso.date({ error: () => HomeAddressErrorCodes.REQUIRED }),\n}\n\n/**\n * Field names accepted by the home address form.\n *\n * @public\n */\nexport type HomeAddressField = keyof typeof fieldValidators\n\n/**\n * Shape of the values managed by the home address form.\n *\n * @public\n */\nexport type HomeAddressFormData = {\n  [K in keyof typeof fieldValidators]: z.infer<(typeof fieldValidators)[K]>\n}\n/**\n * Shape of the validated values produced by the home address form on submit.\n *\n * @public\n */\nexport type HomeAddressFormOutputs = HomeAddressFormData\n\n// ── Required fields config ─────────────────────────────────────────────\n\nconst requiredFieldsConfig = {\n  street2: 'never',\n} satisfies RequiredFieldConfig<typeof fieldValidators>\n\n// ── Schema factory ─────────────────────────────────────────────────────\n\n/**\n * Keys of optional home address fields that can be promoted to required via\n * the hook's `optionalFieldsToRequire` option.\n *\n * @public\n */\nexport type HomeAddressOptionalFieldsToRequire = OptionalFieldsToRequire<\n  typeof requiredFieldsConfig\n>\n\n/** @internal */\ninterface HomeAddressSchemaOptions {\n  mode?: 'create' | 'update'\n  optionalFieldsToRequire?: HomeAddressOptionalFieldsToRequire\n  withEffectiveDateField?: boolean\n}\n\n/** @internal */\nexport function createHomeAddressSchema(options: HomeAddressSchemaOptions = {}) {\n  const { mode = 'create', optionalFieldsToRequire, withEffectiveDateField = true } = options\n\n  return buildFormSchema(fieldValidators, {\n    requiredFieldsConfig,\n    requiredErrorCode: HomeAddressErrorCodes.REQUIRED,\n    mode,\n    optionalFieldsToRequire,\n    excludeFields: withEffectiveDateField ? [] : ['effectiveDate'],\n  })\n}\n"],"names":["HomeAddressErrorCodes","ZIP_REGEX","fieldValidators","z","requiredFieldsConfig","createHomeAddressSchema","options","mode","optionalFieldsToRequire","withEffectiveDateField","buildFormSchema"],"mappings":";;AAeO,MAAMA,IAAwB;AAAA,EACnC,UAAU;AAAA,EACV,aAAa;AACf,GAaMC,IAAY,6BAEZC,IAAkB;AAAA,EACtB,SAASC,EAAE,OAAA;AAAA,EACX,SAASA,EAAE,OAAA;AAAA,EACX,MAAMA,EAAE,OAAA;AAAA,EACR,OAAOA,EAAE,OAAA;AAAA,EACT,KAAKA,EAAE,OAAA,EAAS,MAAMF,GAAW,EAAE,SAASD,EAAsB,aAAa;AAAA,EAC/E,qBAAqBG,EAAE,QAAA;AAAA,EACvB,eAAeA,EAAE,IAAI,KAAK,EAAE,OAAO,MAAMH,EAAsB,SAAA,CAAU;AAC3E,GA0BMI,IAAuB;AAAA,EAC3B,SAAS;AACX;AAsBO,SAASC,EAAwBC,IAAoC,IAAI;AAC9E,QAAM,EAAE,MAAAC,IAAO,UAAU,yBAAAC,GAAyB,wBAAAC,IAAyB,OAASH;AAEpF,SAAOI,EAAgBR,GAAiB;AAAA,IACtC,sBAAAE;AAAA,IACA,mBAAmBJ,EAAsB;AAAA,IACzC,MAAAO;AAAA,IACA,yBAAAC;AAAA,IACA,eAAeC,IAAyB,CAAA,IAAK,CAAC,eAAe;AAAA,EAAA,CAC9D;AACH;"}

package/dist/components/Employee/Profile/shared/useHomeAddressForm/index.d.ts

@@ -1,7 +1,8 @@
 import "./types/i18next.d.ts"
 export { useHomeAddressForm } from './useHomeAddressForm';
 export { useCurrentHomeAddressForm } from './useCurrentHomeAddressForm';
-export type { HomeAddressSubmitOptions, HomeAddressOptionalFieldsToRequire, UseHomeAddressFormProps, UseHomeAddressFormResult, UseHomeAddressFormReady, HomeAddressFieldsMetadata, HomeAddressFormFields, } from './useHomeAddressForm';
+export type { HomeAddressSubmitOptions, HomeAddressOptionalFieldsToRequire, UseHomeAddressFormProps, UseHomeAddressFormResult, UseHomeAddressFormReady, HomeAddressFieldsMetadata, HomeAddressFormFields, HomeAddressFields, } from './useHomeAddressForm';
 export type { UseCurrentHomeAddressFormProps } from './useCurrentHomeAddressForm';
 export { createHomeAddressSchema, HomeAddressErrorCodes, type HomeAddressErrorCode, type HomeAddressFormData, type HomeAddressFormOutputs, type HomeAddressField, } from './homeAddressSchema';
+export { Street1Field, Street2Field, CityField, StateField, ZipField, CourtesyWithholdingField, EffectiveDateField, } from './fields';
 export type { RequiredValidation as HomeAddressRequiredValidation, ZipValidation, Street1FieldProps, Street2FieldProps, CityFieldProps, StateFieldProps, ZipFieldProps, CourtesyWithholdingFieldProps, EffectiveDateFieldProps as HomeAddressEffectiveDateFieldProps, } from './fields';

package/dist/components/Employee/Profile/shared/useHomeAddressForm/useCurrentHomeAddressForm.d.ts

@@ -1,3 +1,48 @@
 import { UseHomeAddressFormProps, UseHomeAddressFormResult } from './useHomeAddressForm';
+/**
+ * Options for {@link useCurrentHomeAddressForm}.
+ *
+ * @remarks
+ * Same shape as {@link UseHomeAddressFormProps} minus `homeAddressUuid` —
+ * the hook resolves the current home address itself.
+ *
+ * @public
+ */
 export type UseCurrentHomeAddressFormProps = Omit<UseHomeAddressFormProps, 'homeAddressUuid'>;
+/**
+ * Convenience wrapper around {@link useHomeAddressForm} that auto-resolves the employee's current home address.
+ *
+ * @remarks
+ * Lists the employee's home addresses and selects the active one (or the
+ * first when none are active) as the row to edit. When the employee has no
+ * home address on file the hook operates in create mode. The returned
+ * shape is identical to {@link useHomeAddressForm}, so the same `Fields`,
+ * `actions.onSubmit`, and `errorHandling` apply.
+ *
+ * @param props - See {@link UseCurrentHomeAddressFormProps}.
+ * @returns A {@link HookLoadingResult} while loading, or a {@link UseHomeAddressFormReady} once ready.
+ * @public
+ *
+ * @example
+ * ```tsx
+ * import { useCurrentHomeAddressForm } from '@gusto/embedded-react-sdk'
+ *
+ * function HomeAddressEditor({ employeeId }: { employeeId: string }) {
+ *   const homeAddress = useCurrentHomeAddressForm({ employeeId })
+ *
+ *   if (homeAddress.isLoading) return <div>Loading...</div>
+ *
+ *   const { Fields } = homeAddress.form
+ *   return (
+ *     <form onSubmit={e => { e.preventDefault(); void homeAddress.actions.onSubmit() }}>
+ *       <Fields.Street1 label="Street" />
+ *       <Fields.City label="City" />
+ *       <Fields.State label="State" />
+ *       <Fields.Zip label="ZIP" />
+ *       <button type="submit">Save</button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
 export declare function useCurrentHomeAddressForm(props: UseCurrentHomeAddressFormProps): UseHomeAddressFormResult;

package/dist/components/Employee/Profile/shared/useHomeAddressForm/useCurrentHomeAddressForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"useCurrentHomeAddressForm.js","sources":["../../../../../../src/components/Employee/Profile/shared/useHomeAddressForm/useCurrentHomeAddressForm.tsx"],"sourcesContent":["import { useEmployeeAddressesGet } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesGet'\nimport { useHomeAddressForm } from './useHomeAddressForm'\nimport type { UseHomeAddressFormProps, UseHomeAddressFormResult } from './useHomeAddressForm'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\n\nexport type UseCurrentHomeAddressFormProps = Omit<UseHomeAddressFormProps, 'homeAddressUuid'>\n\nexport function useCurrentHomeAddressForm(\n  props: UseCurrentHomeAddressFormProps,\n): UseHomeAddressFormResult {\n  const { employeeId, ...rest } = props\n\n  const listQuery = useEmployeeAddressesGet({ employeeId }, { enabled: !!employeeId })\n\n  const homeAddresses = listQuery.data?.employeeAddressList\n  const currentHomeAddress = homeAddresses?.find(a => a.active) ?? homeAddresses?.[0]\n\n  const base = useHomeAddressForm({\n    ...rest,\n    employeeId,\n    homeAddressUuid: currentHomeAddress?.uuid,\n  })\n\n  const listInitiallyBlocking = listQuery.isLoading && !listQuery.data\n\n  if (listInitiallyBlocking) {\n    return {\n      isLoading: true as const,\n      errorHandling: composeErrorHandler([listQuery]),\n    }\n  }\n\n  if (base.isLoading) {\n    return {\n      ...base,\n      errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n    }\n  }\n\n  return {\n    ...base,\n    errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n  }\n}\n"],"names":["useCurrentHomeAddressForm","props","employeeId","rest","listQuery","useEmployeeAddressesGet","homeAddresses","currentHomeAddress","a","base","useHomeAddressForm","composeErrorHandler"],"mappings":";;;AAOO,SAASA,EACdC,GAC0B;AAC1B,QAAM,EAAE,YAAAC,GAAY,GAAGC,EAAA,IAASF,GAE1BG,IAAYC,EAAwB,EAAE,YAAAH,EAAA,GAAc,EAAE,SAAS,CAAC,CAACA,GAAY,GAE7EI,IAAgBF,EAAU,MAAM,qBAChCG,IAAqBD,GAAe,KAAK,CAAAE,MAAKA,EAAE,MAAM,KAAKF,IAAgB,CAAC,GAE5EG,IAAOC,EAAmB;AAAA,IAC9B,GAAGP;AAAA,IACH,YAAAD;AAAA,IACA,iBAAiBK,GAAoB;AAAA,EAAA,CACtC;AAID,SAF8BH,EAAU,aAAa,CAACA,EAAU,OAGvD;AAAA,IACL,WAAW;AAAA,IACX,eAAeO,EAAoB,CAACP,CAAS,CAAC;AAAA,EAAA,IAI9CK,EAAK,YACA;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA,IAIlF;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA;AAEzF;"}
+{"version":3,"file":"useCurrentHomeAddressForm.js","sources":["../../../../../../src/components/Employee/Profile/shared/useHomeAddressForm/useCurrentHomeAddressForm.tsx"],"sourcesContent":["import { useEmployeeAddressesGet } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesGet'\nimport { useHomeAddressForm } from './useHomeAddressForm'\nimport type { UseHomeAddressFormProps, UseHomeAddressFormResult } from './useHomeAddressForm'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\n\n/**\n * Options for {@link useCurrentHomeAddressForm}.\n *\n * @remarks\n * Same shape as {@link UseHomeAddressFormProps} minus `homeAddressUuid` —\n * the hook resolves the current home address itself.\n *\n * @public\n */\nexport type UseCurrentHomeAddressFormProps = Omit<UseHomeAddressFormProps, 'homeAddressUuid'>\n\n/**\n * Convenience wrapper around {@link useHomeAddressForm} that auto-resolves the employee's current home address.\n *\n * @remarks\n * Lists the employee's home addresses and selects the active one (or the\n * first when none are active) as the row to edit. When the employee has no\n * home address on file the hook operates in create mode. The returned\n * shape is identical to {@link useHomeAddressForm}, so the same `Fields`,\n * `actions.onSubmit`, and `errorHandling` apply.\n *\n * @param props - See {@link UseCurrentHomeAddressFormProps}.\n * @returns A {@link HookLoadingResult} while loading, or a {@link UseHomeAddressFormReady} once ready.\n * @public\n *\n * @example\n * ```tsx\n * import { useCurrentHomeAddressForm } from '@gusto/embedded-react-sdk'\n *\n * function HomeAddressEditor({ employeeId }: { employeeId: string }) {\n *   const homeAddress = useCurrentHomeAddressForm({ employeeId })\n *\n *   if (homeAddress.isLoading) return <div>Loading...</div>\n *\n *   const { Fields } = homeAddress.form\n *   return (\n *     <form onSubmit={e => { e.preventDefault(); void homeAddress.actions.onSubmit() }}>\n *       <Fields.Street1 label=\"Street\" />\n *       <Fields.City label=\"City\" />\n *       <Fields.State label=\"State\" />\n *       <Fields.Zip label=\"ZIP\" />\n *       <button type=\"submit\">Save</button>\n *     </form>\n *   )\n * }\n * ```\n */\nexport function useCurrentHomeAddressForm(\n  props: UseCurrentHomeAddressFormProps,\n): UseHomeAddressFormResult {\n  const { employeeId, ...rest } = props\n\n  const listQuery = useEmployeeAddressesGet({ employeeId }, { enabled: !!employeeId })\n\n  const homeAddresses = listQuery.data?.employeeAddressList\n  const currentHomeAddress = homeAddresses?.find(a => a.active) ?? homeAddresses?.[0]\n\n  const base = useHomeAddressForm({\n    ...rest,\n    employeeId,\n    homeAddressUuid: currentHomeAddress?.uuid,\n  })\n\n  const listInitiallyBlocking = listQuery.isLoading && !listQuery.data\n\n  if (listInitiallyBlocking) {\n    return {\n      isLoading: true as const,\n      errorHandling: composeErrorHandler([listQuery]),\n    }\n  }\n\n  if (base.isLoading) {\n    return {\n      ...base,\n      errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n    }\n  }\n\n  return {\n    ...base,\n    errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n  }\n}\n"],"names":["useCurrentHomeAddressForm","props","employeeId","rest","listQuery","useEmployeeAddressesGet","homeAddresses","currentHomeAddress","a","base","useHomeAddressForm","composeErrorHandler"],"mappings":";;;AAoDO,SAASA,EACdC,GAC0B;AAC1B,QAAM,EAAE,YAAAC,GAAY,GAAGC,EAAA,IAASF,GAE1BG,IAAYC,EAAwB,EAAE,YAAAH,EAAA,GAAc,EAAE,SAAS,CAAC,CAACA,GAAY,GAE7EI,IAAgBF,EAAU,MAAM,qBAChCG,IAAqBD,GAAe,KAAK,CAAAE,MAAKA,EAAE,MAAM,KAAKF,IAAgB,CAAC,GAE5EG,IAAOC,EAAmB;AAAA,IAC9B,GAAGP;AAAA,IACH,YAAAD;AAAA,IACA,iBAAiBK,GAAoB;AAAA,EAAA,CACtC;AAID,SAF8BH,EAAU,aAAa,CAACA,EAAU,OAGvD;AAAA,IACL,WAAW;AAAA,IACX,eAAeO,EAAoB,CAACP,CAAS,CAAC;AAAA,EAAA,IAI9CK,EAAK,YACA;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA,IAIlF;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA;AAEzF;"}

package/dist/components/Employee/Profile/shared/useHomeAddressForm/useHomeAddressForm.d.ts

@@ -4,12 +4,28 @@ import { HomeAddressOptionalFieldsToRequire, HomeAddressFormData } from './homeA
 import { Street1Field, Street2Field, CityField, StateField, ZipField, CourtesyWithholdingField, EffectiveDateField } from './fields';
 import { BaseFormHookReady, FieldsMetadata, HookLoadingResult, HookSubmitResult } from '../../../../../partner-hook-utils/types';
 export type { HomeAddressOptionalFieldsToRequire } from './homeAddressSchema';
+/**
+ * Optional overrides passed to {@link UseHomeAddressFormReady.actions.onSubmit | onSubmit}.
+ *
+ * @public
+ */
 export interface HomeAddressSubmitOptions {
+    /** Override the employee identifier supplied to the hook (e.g. after creating a new employee in the same flow). */
     employeeId?: string;
-    /** When omitted on update without an effective-date field, the row’s `effectiveDate` from the fetched address is used. */
+    /** Override the effective date submitted with the address. When omitted on update without an effective-date field, the row's `effectiveDate` from the fetched address is used. */
     effectiveDate?: string;
 }
+/**
+ * Configuration options for {@link useHomeAddressForm}.
+ *
+ * @remarks
+ * Presence or absence of `homeAddressUuid` selects the API verb — see the
+ * `homeAddressUuid` field description.
+ *
+ * @public
+ */
 export interface UseHomeAddressFormProps {
+    /** UUID of the employee whose home address is being created or edited. */
     employeeId: string;
     /**
      * When set, loads that home address via GET `/v1/home_addresses/{uuid}` and updates it (PUT).
@@ -21,35 +37,95 @@ export interface UseHomeAddressFormProps {
      * instead of issuing a GET — useful when the parent already has the row from a list query.
      */
     initialAddress?: EmployeeAddress;
+    /** When `true`, renders `Fields.EffectiveDate`; otherwise it is `undefined`. Defaults to `true`. */
     withEffectiveDateField?: boolean;
+    /** Override fields that are optional on a given mode to be required. See `HomeAddressOptionalFieldsToRequire`. */
     optionalFieldsToRequire?: HomeAddressOptionalFieldsToRequire;
+    /** Pre-fill form values. Server data takes precedence on update. */
     defaultValues?: Partial<HomeAddressFormData>;
+    /** Passed through to react-hook-form. Defaults to `'onSubmit'`. */
     validationMode?: UseFormProps['mode'];
+    /** Auto-focus the first invalid field on submit. Set to `false` when using `composeSubmitHandler` so submit-time focus is coordinated across multiple forms. Defaults to `true`. */
     shouldFocusError?: boolean;
 }
+/**
+ * Pre-bound field components exposed on `useHomeAddressForm().form.Fields`.
+ *
+ * @remarks
+ * `EffectiveDate` is `undefined` when `withEffectiveDateField` is `false`.
+ * Always null-check it before rendering.
+ *
+ * @public
+ */
 export interface HomeAddressFields {
+    /** Street address line 1 text input. Always available. */
     Street1: typeof Street1Field;
+    /** Street address line 2 text input. Always available. */
     Street2: typeof Street2Field;
+    /** City text input. Always available. */
     City: typeof CityField;
+    /** State selector. Always available. */
     State: typeof StateField;
+    /** ZIP code text input. Always available. */
     Zip: typeof ZipField;
+    /** Courtesy withholding checkbox. Always available. */
     CourtesyWithholding: typeof CourtesyWithholdingField;
+    /** Effective-date picker. Only available when `withEffectiveDateField` is `true`. */
     EffectiveDate: typeof EffectiveDateField | undefined;
 }
+/**
+ * Ready-state shape returned by {@link useHomeAddressForm} once data has loaded.
+ *
+ * @remarks
+ * Discriminated by `isLoading: false`. Extends {@link BaseFormHookReady} with
+ * the home-address-specific `data`, `status`, `actions`, and `form.Fields` shape.
+ *
+ * @public
+ */
 export interface UseHomeAddressFormReady extends BaseFormHookReady<FieldsMetadata, HomeAddressFormData, HomeAddressFields> {
+    /** Static entity data resolved from the API. */
     data: {
         /** The address row loaded for update; `null` in create mode. */
         homeAddress: EmployeeAddress | null;
     };
+    /** Reactive status flags. */
     status: {
         isPending: boolean;
         mode: 'create' | 'update';
     };
+    /** Available actions. */
     actions: {
         onSubmit: (options?: HomeAddressSubmitOptions) => Promise<HookSubmitResult<EmployeeAddress> | undefined>;
     };
 }
+/**
+ * Form hook for creating or editing an employee's home address.
+ *
+ * @remarks
+ * When `homeAddressUuid` is supplied the hook loads that address and issues a PUT on submit;
+ * when omitted it operates in create mode and issues a POST. Pass `initialAddress` to
+ * skip the fetch when the parent already holds the row.
+ *
+ * @param props - See {@link UseHomeAddressFormProps}.
+ * @returns A {@link HookLoadingResult} while loading, or a {@link UseHomeAddressFormReady} once ready.
+ * @public
+ */
 export declare function useHomeAddressForm({ employeeId, homeAddressUuid, initialAddress, withEffectiveDateField, optionalFieldsToRequire, defaultValues: partnerDefaults, validationMode, shouldFocusError, }: UseHomeAddressFormProps): HookLoadingResult | UseHomeAddressFormReady;
+/**
+ * Discriminated union returned by {@link useHomeAddressForm}.
+ *
+ * @public
+ */
 export type UseHomeAddressFormResult = HookLoadingResult | UseHomeAddressFormReady;
+/**
+ * Type of `form.fieldsMetadata` returned by {@link useHomeAddressForm}.
+ *
+ * @public
+ */
 export type HomeAddressFieldsMetadata = UseHomeAddressFormReady['form']['fieldsMetadata'];
+/**
+ * Type of `form.Fields` returned by {@link useHomeAddressForm}.
+ *
+ * @public
+ */
 export type HomeAddressFormFields = UseHomeAddressFormReady['form']['Fields'];

package/dist/components/Employee/Profile/shared/useHomeAddressForm/useHomeAddressForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHomeAddressForm.js","sources":["../../../../../../src/components/Employee/Profile/shared/useHomeAddressForm/useHomeAddressForm.tsx"],"sourcesContent":["import { useMemo } from 'react'\nimport { useForm } from 'react-hook-form'\nimport type { UseFormProps } from 'react-hook-form'\nimport { zodResolver } from '@hookform/resolvers/zod'\nimport type { EmployeeAddress } from '@gusto/embedded-api-v-2025-11-15/models/components/employeeaddress'\nimport { useEmployeeAddressesRetrieveHomeAddress } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesRetrieveHomeAddress'\nimport { useEmployeeAddressesCreateMutation } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesCreate'\nimport { useEmployeeAddressesUpdateMutation } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesUpdate'\nimport { RFCDate } from '@gusto/embedded-api-v-2025-11-15/types/rfcdate'\nimport {\n  createHomeAddressSchema,\n  type HomeAddressOptionalFieldsToRequire,\n  type HomeAddressFormData,\n  type HomeAddressFormOutputs,\n} from './homeAddressSchema'\nimport {\n  Street1Field,\n  Street2Field,\n  CityField,\n  StateField,\n  ZipField,\n  CourtesyWithholdingField,\n  EffectiveDateField,\n} from './fields'\nimport { useDeriveFieldsMetadata } from '@/partner-hook-utils/form/useDeriveFieldsMetadata'\nimport { useHookFormInternals } from '@/partner-hook-utils/form/useHookFormInternals'\nimport { createGetFormSubmissionValues } from '@/partner-hook-utils/form/getFormSubmissionValues'\nimport { withOptions } from '@/partner-hook-utils/form/withOptions'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\nimport type {\n  BaseFormHookReady,\n  FieldsMetadata,\n  HookLoadingResult,\n  HookSubmitResult,\n} from '@/partner-hook-utils/types'\nimport { useBaseSubmit } from '@/components/Base/useBaseSubmit'\nimport { SDKInternalError } from '@/types/sdkError'\nimport { STATES_ABBR } from '@/shared/constants'\n\nexport type { HomeAddressOptionalFieldsToRequire } from './homeAddressSchema'\n\nexport interface HomeAddressSubmitOptions {\n  employeeId?: string\n  /** When omitted on update without an effective-date field, the row’s `effectiveDate` from the fetched address is used. */\n  effectiveDate?: string\n}\n\nexport interface UseHomeAddressFormProps {\n  employeeId: string\n  /**\n   * When set, loads that home address via GET `/v1/home_addresses/{uuid}` and updates it (PUT).\n   * When omitted, the form is in create mode (POST).\n   */\n  homeAddressUuid?: string\n  /**\n   * Pre-loaded address matching `homeAddressUuid`. When supplied, the form uses it directly\n   * instead of issuing a GET — useful when the parent already has the row from a list query.\n   */\n  initialAddress?: EmployeeAddress\n  withEffectiveDateField?: boolean\n  optionalFieldsToRequire?: HomeAddressOptionalFieldsToRequire\n  defaultValues?: Partial<HomeAddressFormData>\n  validationMode?: UseFormProps['mode']\n  shouldFocusError?: boolean\n}\n\nexport interface HomeAddressFields {\n  Street1: typeof Street1Field\n  Street2: typeof Street2Field\n  City: typeof CityField\n  State: typeof StateField\n  Zip: typeof ZipField\n  CourtesyWithholding: typeof CourtesyWithholdingField\n  EffectiveDate: typeof EffectiveDateField | undefined\n}\n\nexport interface UseHomeAddressFormReady extends BaseFormHookReady<\n  FieldsMetadata,\n  HomeAddressFormData,\n  HomeAddressFields\n> {\n  data: {\n    /** The address row loaded for update; `null` in create mode. */\n    homeAddress: EmployeeAddress | null\n  }\n  status: { isPending: boolean; mode: 'create' | 'update' }\n  actions: {\n    onSubmit: (\n      options?: HomeAddressSubmitOptions,\n    ) => Promise<HookSubmitResult<EmployeeAddress> | undefined>\n  }\n}\n\nexport function useHomeAddressForm({\n  employeeId,\n  homeAddressUuid,\n  initialAddress,\n  withEffectiveDateField = true,\n  optionalFieldsToRequire,\n  defaultValues: partnerDefaults,\n  validationMode = 'onSubmit',\n  shouldFocusError = true,\n}: UseHomeAddressFormProps): HookLoadingResult | UseHomeAddressFormReady {\n  const hasInitialAddressMatch = !!homeAddressUuid && initialAddress?.uuid === homeAddressUuid\n\n  const retrieveHomeAddressQuery = useEmployeeAddressesRetrieveHomeAddress(\n    { homeAddressUuid: homeAddressUuid ?? '' },\n    { enabled: !!homeAddressUuid && !hasInitialAddressMatch },\n  )\n\n  const isCreateMode = !homeAddressUuid\n\n  const fetchedHomeAddress = homeAddressUuid\n    ? hasInitialAddressMatch\n      ? initialAddress\n      : retrieveHomeAddressQuery.data?.employeeAddress\n    : undefined\n\n  const schemaMode = isCreateMode ? 'create' : 'update'\n\n  const [schema, metadataConfig] = useMemo(\n    () =>\n      createHomeAddressSchema({\n        mode: schemaMode,\n        optionalFieldsToRequire,\n        withEffectiveDateField,\n      }),\n    [schemaMode, optionalFieldsToRequire, withEffectiveDateField],\n  )\n\n  const resolvedDefaults: HomeAddressFormData = useMemo(\n    () => ({\n      street1: fetchedHomeAddress?.street1 ?? partnerDefaults?.street1 ?? '',\n      street2: fetchedHomeAddress?.street2 ?? partnerDefaults?.street2 ?? '',\n      city: fetchedHomeAddress?.city ?? partnerDefaults?.city ?? '',\n      state: fetchedHomeAddress?.state ?? partnerDefaults?.state ?? '',\n      zip: fetchedHomeAddress?.zip ?? partnerDefaults?.zip ?? '',\n      courtesyWithholding:\n        fetchedHomeAddress?.courtesyWithholding ?? partnerDefaults?.courtesyWithholding ?? false,\n      effectiveDate:\n        fetchedHomeAddress?.effectiveDate?.toString() ?? partnerDefaults?.effectiveDate ?? '',\n    }),\n    [fetchedHomeAddress, partnerDefaults],\n  )\n\n  const formMethods = useForm<HomeAddressFormData, unknown, HomeAddressFormOutputs>({\n    resolver: zodResolver(schema),\n    mode: validationMode,\n    shouldFocusError,\n    defaultValues: resolvedDefaults,\n    values: resolvedDefaults,\n    resetOptions: { keepDirtyValues: true },\n  })\n\n  const createHomeAddressMutation = useEmployeeAddressesCreateMutation()\n  const updateHomeAddressMutation = useEmployeeAddressesUpdateMutation()\n\n  const isPending = createHomeAddressMutation.isPending || updateHomeAddressMutation.isPending\n\n  const {\n    baseSubmitHandler,\n    error: submitError,\n    setError: setSubmitError,\n  } = useBaseSubmit('HomeAddressForm')\n\n  const queriesForErrors = homeAddressUuid ? [retrieveHomeAddressQuery] : []\n  const errorHandling = composeErrorHandler(queriesForErrors, { submitError, setSubmitError })\n\n  const stateOptions = STATES_ABBR.map(abbr => ({\n    value: abbr,\n    label: abbr,\n  }))\n\n  const baseMetadata = useDeriveFieldsMetadata(metadataConfig, formMethods.control)\n  const fieldsMetadata = {\n    street1: baseMetadata.street1,\n    street2: baseMetadata.street2,\n    city: baseMetadata.city,\n    state: withOptions(baseMetadata.state, stateOptions, STATES_ABBR),\n    zip: baseMetadata.zip,\n    courtesyWithholding: baseMetadata.courtesyWithholding,\n    effectiveDate: baseMetadata.effectiveDate,\n  }\n\n  const onSubmit = async (\n    options?: HomeAddressSubmitOptions,\n  ): Promise<HookSubmitResult<EmployeeAddress> | undefined> => {\n    let submitResult: HookSubmitResult<EmployeeAddress> | undefined\n\n    await new Promise<void>(resolve => {\n      void formMethods.handleSubmit(\n        async (data: HomeAddressFormOutputs) => {\n          await baseSubmitHandler(data, async payload => {\n            const resolvedEmployeeId = options?.employeeId ?? employeeId\n\n            const resolvedEffectiveDate =\n              withEffectiveDateField && payload.effectiveDate\n                ? payload.effectiveDate\n                : (options?.effectiveDate ??\n                  (!withEffectiveDateField && !isCreateMode\n                    ? fetchedHomeAddress?.effectiveDate?.toString()\n                    : undefined))\n\n            const effectiveDateParam = resolvedEffectiveDate\n              ? new RFCDate(new Date(resolvedEffectiveDate))\n              : undefined\n\n            let updatedHomeAddress: EmployeeAddress\n\n            if (isCreateMode) {\n              const result = await createHomeAddressMutation.mutateAsync({\n                request: {\n                  employeeId: resolvedEmployeeId,\n                  requestBody: {\n                    street1: payload.street1,\n                    street2: payload.street2 || undefined,\n                    city: payload.city,\n                    state: payload.state,\n                    zip: payload.zip,\n                    courtesyWithholding: payload.courtesyWithholding,\n                    effectiveDate: effectiveDateParam,\n                  },\n                },\n              })\n\n              if (!result.employeeAddress) {\n                throw new SDKInternalError('Home address creation failed')\n              }\n\n              updatedHomeAddress = result.employeeAddress\n            } else {\n              if (!fetchedHomeAddress || !homeAddressUuid) {\n                throw new SDKInternalError(\n                  'Cannot update home address: no matching address on file',\n                )\n              }\n\n              const result = await updateHomeAddressMutation.mutateAsync({\n                request: {\n                  homeAddressUuid: fetchedHomeAddress.uuid,\n                  requestBody: {\n                    version: fetchedHomeAddress.version,\n                    street1: payload.street1,\n                    street2: payload.street2 || undefined,\n                    city: payload.city,\n                    state: payload.state,\n                    zip: payload.zip,\n                    courtesyWithholding: payload.courtesyWithholding,\n                    effectiveDate: effectiveDateParam,\n                  },\n                },\n              })\n\n              if (!result.employeeAddress) {\n                throw new SDKInternalError('Home address update failed')\n              }\n\n              updatedHomeAddress = result.employeeAddress\n            }\n\n            submitResult = {\n              mode: isCreateMode ? 'create' : 'update',\n              data: updatedHomeAddress,\n            }\n          })\n          resolve()\n        },\n        () => {\n          resolve()\n        },\n      )()\n    })\n\n    return submitResult\n  }\n\n  const hookFormInternals = useHookFormInternals(formMethods)\n\n  if (homeAddressUuid && !fetchedHomeAddress) {\n    return { isLoading: true as const, errorHandling }\n  }\n\n  return {\n    isLoading: false as const,\n    data: {\n      homeAddress: fetchedHomeAddress ?? null,\n    },\n    status: {\n      isPending,\n      mode: isCreateMode ? ('create' as const) : ('update' as const),\n    },\n    actions: { onSubmit },\n    errorHandling,\n    form: {\n      Fields: {\n        Street1: Street1Field,\n        Street2: Street2Field,\n        City: CityField,\n        State: StateField,\n        Zip: ZipField,\n        CourtesyWithholding: CourtesyWithholdingField,\n        EffectiveDate: withEffectiveDateField ? EffectiveDateField : undefined,\n      },\n      fieldsMetadata,\n      hookFormInternals,\n      getFormSubmissionValues: createGetFormSubmissionValues(formMethods, schema),\n    },\n  }\n}\n\nexport type UseHomeAddressFormResult = HookLoadingResult | UseHomeAddressFormReady\nexport type HomeAddressFieldsMetadata = UseHomeAddressFormReady['form']['fieldsMetadata']\nexport type HomeAddressFormFields = UseHomeAddressFormReady['form']['Fields']\n"],"names":["useHomeAddressForm","employeeId","homeAddressUuid","initialAddress","withEffectiveDateField","optionalFieldsToRequire","partnerDefaults","validationMode","shouldFocusError","hasInitialAddressMatch","retrieveHomeAddressQuery","useEmployeeAddressesRetrieveHomeAddress","isCreateMode","fetchedHomeAddress","schemaMode","schema","metadataConfig","useMemo","createHomeAddressSchema","resolvedDefaults","formMethods","useForm","zodResolver","createHomeAddressMutation","useEmployeeAddressesCreateMutation","updateHomeAddressMutation","useEmployeeAddressesUpdateMutation","isPending","baseSubmitHandler","submitError","setSubmitError","useBaseSubmit","errorHandling","composeErrorHandler","stateOptions","STATES_ABBR","abbr","baseMetadata","useDeriveFieldsMetadata","fieldsMetadata","withOptions","onSubmit","options","submitResult","resolve","data","payload","resolvedEmployeeId","resolvedEffectiveDate","effectiveDateParam","RFCDate","updatedHomeAddress","result","SDKInternalError","hookFormInternals","useHookFormInternals","Street1Field","Street2Field","CityField","StateField","ZipField","CourtesyWithholdingField","EffectiveDateField","createGetFormSubmissionValues"],"mappings":"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"}
+{"version":3,"file":"useHomeAddressForm.js","sources":["../../../../../../src/components/Employee/Profile/shared/useHomeAddressForm/useHomeAddressForm.tsx"],"sourcesContent":["import { useMemo } from 'react'\nimport { useForm } from 'react-hook-form'\nimport type { UseFormProps } from 'react-hook-form'\nimport { zodResolver } from '@hookform/resolvers/zod'\nimport type { EmployeeAddress } from '@gusto/embedded-api-v-2025-11-15/models/components/employeeaddress'\nimport { useEmployeeAddressesRetrieveHomeAddress } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesRetrieveHomeAddress'\nimport { useEmployeeAddressesCreateMutation } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesCreate'\nimport { useEmployeeAddressesUpdateMutation } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesUpdate'\nimport { RFCDate } from '@gusto/embedded-api-v-2025-11-15/types/rfcdate'\nimport {\n  createHomeAddressSchema,\n  type HomeAddressOptionalFieldsToRequire,\n  type HomeAddressFormData,\n  type HomeAddressFormOutputs,\n} from './homeAddressSchema'\nimport {\n  Street1Field,\n  Street2Field,\n  CityField,\n  StateField,\n  ZipField,\n  CourtesyWithholdingField,\n  EffectiveDateField,\n} from './fields'\nimport { useDeriveFieldsMetadata } from '@/partner-hook-utils/form/useDeriveFieldsMetadata'\nimport { useHookFormInternals } from '@/partner-hook-utils/form/useHookFormInternals'\nimport { createGetFormSubmissionValues } from '@/partner-hook-utils/form/getFormSubmissionValues'\nimport { withOptions } from '@/partner-hook-utils/form/withOptions'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\nimport type {\n  BaseFormHookReady,\n  FieldsMetadata,\n  HookLoadingResult,\n  HookSubmitResult,\n} from '@/partner-hook-utils/types'\nimport { useBaseSubmit } from '@/components/Base/useBaseSubmit'\nimport { SDKInternalError } from '@/types/sdkError'\nimport { STATES_ABBR } from '@/shared/constants'\n\nexport type { HomeAddressOptionalFieldsToRequire } from './homeAddressSchema'\n\n/**\n * Optional overrides passed to {@link UseHomeAddressFormReady.actions.onSubmit | onSubmit}.\n *\n * @public\n */\nexport interface HomeAddressSubmitOptions {\n  /** Override the employee identifier supplied to the hook (e.g. after creating a new employee in the same flow). */\n  employeeId?: string\n  /** Override the effective date submitted with the address. When omitted on update without an effective-date field, the row's `effectiveDate` from the fetched address is used. */\n  effectiveDate?: string\n}\n\n/**\n * Configuration options for {@link useHomeAddressForm}.\n *\n * @remarks\n * Presence or absence of `homeAddressUuid` selects the API verb — see the\n * `homeAddressUuid` field description.\n *\n * @public\n */\nexport interface UseHomeAddressFormProps {\n  /** UUID of the employee whose home address is being created or edited. */\n  employeeId: string\n  /**\n   * When set, loads that home address via GET `/v1/home_addresses/{uuid}` and updates it (PUT).\n   * When omitted, the form is in create mode (POST).\n   */\n  homeAddressUuid?: string\n  /**\n   * Pre-loaded address matching `homeAddressUuid`. When supplied, the form uses it directly\n   * instead of issuing a GET — useful when the parent already has the row from a list query.\n   */\n  initialAddress?: EmployeeAddress\n  /** When `true`, renders `Fields.EffectiveDate`; otherwise it is `undefined`. Defaults to `true`. */\n  withEffectiveDateField?: boolean\n  /** Override fields that are optional on a given mode to be required. See `HomeAddressOptionalFieldsToRequire`. */\n  optionalFieldsToRequire?: HomeAddressOptionalFieldsToRequire\n  /** Pre-fill form values. Server data takes precedence on update. */\n  defaultValues?: Partial<HomeAddressFormData>\n  /** Passed through to react-hook-form. Defaults to `'onSubmit'`. */\n  validationMode?: UseFormProps['mode']\n  /** Auto-focus the first invalid field on submit. Set to `false` when using `composeSubmitHandler` so submit-time focus is coordinated across multiple forms. Defaults to `true`. */\n  shouldFocusError?: boolean\n}\n\n/**\n * Pre-bound field components exposed on `useHomeAddressForm().form.Fields`.\n *\n * @remarks\n * `EffectiveDate` is `undefined` when `withEffectiveDateField` is `false`.\n * Always null-check it before rendering.\n *\n * @public\n */\nexport interface HomeAddressFields {\n  /** Street address line 1 text input. Always available. */\n  Street1: typeof Street1Field\n  /** Street address line 2 text input. Always available. */\n  Street2: typeof Street2Field\n  /** City text input. Always available. */\n  City: typeof CityField\n  /** State selector. Always available. */\n  State: typeof StateField\n  /** ZIP code text input. Always available. */\n  Zip: typeof ZipField\n  /** Courtesy withholding checkbox. Always available. */\n  CourtesyWithholding: typeof CourtesyWithholdingField\n  /** Effective-date picker. Only available when `withEffectiveDateField` is `true`. */\n  EffectiveDate: typeof EffectiveDateField | undefined\n}\n\n/**\n * Ready-state shape returned by {@link useHomeAddressForm} once data has loaded.\n *\n * @remarks\n * Discriminated by `isLoading: false`. Extends {@link BaseFormHookReady} with\n * the home-address-specific `data`, `status`, `actions`, and `form.Fields` shape.\n *\n * @public\n */\nexport interface UseHomeAddressFormReady extends BaseFormHookReady<\n  FieldsMetadata,\n  HomeAddressFormData,\n  HomeAddressFields\n> {\n  /** Static entity data resolved from the API. */\n  data: {\n    /** The address row loaded for update; `null` in create mode. */\n    homeAddress: EmployeeAddress | null\n  }\n  /** Reactive status flags. */\n  status: { isPending: boolean; mode: 'create' | 'update' }\n  /** Available actions. */\n  actions: {\n    onSubmit: (\n      options?: HomeAddressSubmitOptions,\n    ) => Promise<HookSubmitResult<EmployeeAddress> | undefined>\n  }\n}\n\n/**\n * Form hook for creating or editing an employee's home address.\n *\n * @remarks\n * When `homeAddressUuid` is supplied the hook loads that address and issues a PUT on submit;\n * when omitted it operates in create mode and issues a POST. Pass `initialAddress` to\n * skip the fetch when the parent already holds the row.\n *\n * @param props - See {@link UseHomeAddressFormProps}.\n * @returns A {@link HookLoadingResult} while loading, or a {@link UseHomeAddressFormReady} once ready.\n * @public\n */\nexport function useHomeAddressForm({\n  employeeId,\n  homeAddressUuid,\n  initialAddress,\n  withEffectiveDateField = true,\n  optionalFieldsToRequire,\n  defaultValues: partnerDefaults,\n  validationMode = 'onSubmit',\n  shouldFocusError = true,\n}: UseHomeAddressFormProps): HookLoadingResult | UseHomeAddressFormReady {\n  const hasInitialAddressMatch = !!homeAddressUuid && initialAddress?.uuid === homeAddressUuid\n\n  const retrieveHomeAddressQuery = useEmployeeAddressesRetrieveHomeAddress(\n    { homeAddressUuid: homeAddressUuid ?? '' },\n    { enabled: !!homeAddressUuid && !hasInitialAddressMatch },\n  )\n\n  const isCreateMode = !homeAddressUuid\n\n  const fetchedHomeAddress = homeAddressUuid\n    ? hasInitialAddressMatch\n      ? initialAddress\n      : retrieveHomeAddressQuery.data?.employeeAddress\n    : undefined\n\n  const schemaMode = isCreateMode ? 'create' : 'update'\n\n  const [schema, metadataConfig] = useMemo(\n    () =>\n      createHomeAddressSchema({\n        mode: schemaMode,\n        optionalFieldsToRequire,\n        withEffectiveDateField,\n      }),\n    [schemaMode, optionalFieldsToRequire, withEffectiveDateField],\n  )\n\n  const resolvedDefaults: HomeAddressFormData = useMemo(\n    () => ({\n      street1: fetchedHomeAddress?.street1 ?? partnerDefaults?.street1 ?? '',\n      street2: fetchedHomeAddress?.street2 ?? partnerDefaults?.street2 ?? '',\n      city: fetchedHomeAddress?.city ?? partnerDefaults?.city ?? '',\n      state: fetchedHomeAddress?.state ?? partnerDefaults?.state ?? '',\n      zip: fetchedHomeAddress?.zip ?? partnerDefaults?.zip ?? '',\n      courtesyWithholding:\n        fetchedHomeAddress?.courtesyWithholding ?? partnerDefaults?.courtesyWithholding ?? false,\n      effectiveDate:\n        fetchedHomeAddress?.effectiveDate?.toString() ?? partnerDefaults?.effectiveDate ?? '',\n    }),\n    [fetchedHomeAddress, partnerDefaults],\n  )\n\n  const formMethods = useForm<HomeAddressFormData, unknown, HomeAddressFormOutputs>({\n    resolver: zodResolver(schema),\n    mode: validationMode,\n    shouldFocusError,\n    defaultValues: resolvedDefaults,\n    values: resolvedDefaults,\n    resetOptions: { keepDirtyValues: true },\n  })\n\n  const createHomeAddressMutation = useEmployeeAddressesCreateMutation()\n  const updateHomeAddressMutation = useEmployeeAddressesUpdateMutation()\n\n  const isPending = createHomeAddressMutation.isPending || updateHomeAddressMutation.isPending\n\n  const {\n    baseSubmitHandler,\n    error: submitError,\n    setError: setSubmitError,\n  } = useBaseSubmit('HomeAddressForm')\n\n  const queriesForErrors = homeAddressUuid ? [retrieveHomeAddressQuery] : []\n  const errorHandling = composeErrorHandler(queriesForErrors, { submitError, setSubmitError })\n\n  const stateOptions = STATES_ABBR.map(abbr => ({\n    value: abbr,\n    label: abbr,\n  }))\n\n  const baseMetadata = useDeriveFieldsMetadata(metadataConfig, formMethods.control)\n  const fieldsMetadata = {\n    street1: baseMetadata.street1,\n    street2: baseMetadata.street2,\n    city: baseMetadata.city,\n    state: withOptions(baseMetadata.state, stateOptions, STATES_ABBR),\n    zip: baseMetadata.zip,\n    courtesyWithholding: baseMetadata.courtesyWithholding,\n    effectiveDate: baseMetadata.effectiveDate,\n  }\n\n  const onSubmit = async (\n    options?: HomeAddressSubmitOptions,\n  ): Promise<HookSubmitResult<EmployeeAddress> | undefined> => {\n    let submitResult: HookSubmitResult<EmployeeAddress> | undefined\n\n    await new Promise<void>(resolve => {\n      void formMethods.handleSubmit(\n        async (data: HomeAddressFormOutputs) => {\n          await baseSubmitHandler(data, async payload => {\n            const resolvedEmployeeId = options?.employeeId ?? employeeId\n\n            const resolvedEffectiveDate =\n              withEffectiveDateField && payload.effectiveDate\n                ? payload.effectiveDate\n                : (options?.effectiveDate ??\n                  (!withEffectiveDateField && !isCreateMode\n                    ? fetchedHomeAddress?.effectiveDate?.toString()\n                    : undefined))\n\n            const effectiveDateParam = resolvedEffectiveDate\n              ? new RFCDate(new Date(resolvedEffectiveDate))\n              : undefined\n\n            let updatedHomeAddress: EmployeeAddress\n\n            if (isCreateMode) {\n              const result = await createHomeAddressMutation.mutateAsync({\n                request: {\n                  employeeId: resolvedEmployeeId,\n                  requestBody: {\n                    street1: payload.street1,\n                    street2: payload.street2 || undefined,\n                    city: payload.city,\n                    state: payload.state,\n                    zip: payload.zip,\n                    courtesyWithholding: payload.courtesyWithholding,\n                    effectiveDate: effectiveDateParam,\n                  },\n                },\n              })\n\n              if (!result.employeeAddress) {\n                throw new SDKInternalError('Home address creation failed')\n              }\n\n              updatedHomeAddress = result.employeeAddress\n            } else {\n              if (!fetchedHomeAddress || !homeAddressUuid) {\n                throw new SDKInternalError(\n                  'Cannot update home address: no matching address on file',\n                )\n              }\n\n              const result = await updateHomeAddressMutation.mutateAsync({\n                request: {\n                  homeAddressUuid: fetchedHomeAddress.uuid,\n                  requestBody: {\n                    version: fetchedHomeAddress.version,\n                    street1: payload.street1,\n                    street2: payload.street2 || undefined,\n                    city: payload.city,\n                    state: payload.state,\n                    zip: payload.zip,\n                    courtesyWithholding: payload.courtesyWithholding,\n                    effectiveDate: effectiveDateParam,\n                  },\n                },\n              })\n\n              if (!result.employeeAddress) {\n                throw new SDKInternalError('Home address update failed')\n              }\n\n              updatedHomeAddress = result.employeeAddress\n            }\n\n            submitResult = {\n              mode: isCreateMode ? 'create' : 'update',\n              data: updatedHomeAddress,\n            }\n          })\n          resolve()\n        },\n        () => {\n          resolve()\n        },\n      )()\n    })\n\n    return submitResult\n  }\n\n  const hookFormInternals = useHookFormInternals(formMethods)\n\n  if (homeAddressUuid && !fetchedHomeAddress) {\n    return { isLoading: true as const, errorHandling }\n  }\n\n  return {\n    isLoading: false as const,\n    data: {\n      homeAddress: fetchedHomeAddress ?? null,\n    },\n    status: {\n      isPending,\n      mode: isCreateMode ? ('create' as const) : ('update' as const),\n    },\n    actions: { onSubmit },\n    errorHandling,\n    form: {\n      Fields: {\n        Street1: Street1Field,\n        Street2: Street2Field,\n        City: CityField,\n        State: StateField,\n        Zip: ZipField,\n        CourtesyWithholding: CourtesyWithholdingField,\n        EffectiveDate: withEffectiveDateField ? EffectiveDateField : undefined,\n      },\n      fieldsMetadata,\n      hookFormInternals,\n      getFormSubmissionValues: createGetFormSubmissionValues(formMethods, schema),\n    },\n  }\n}\n\n/**\n * Discriminated union returned by {@link useHomeAddressForm}.\n *\n * @public\n */\nexport type UseHomeAddressFormResult = HookLoadingResult | UseHomeAddressFormReady\n/**\n * Type of `form.fieldsMetadata` returned by {@link useHomeAddressForm}.\n *\n * @public\n */\nexport type HomeAddressFieldsMetadata = UseHomeAddressFormReady['form']['fieldsMetadata']\n/**\n * Type of `form.Fields` returned by {@link useHomeAddressForm}.\n *\n * @public\n */\nexport type HomeAddressFormFields = UseHomeAddressFormReady['form']['Fields']\n"],"names":["useHomeAddressForm","employeeId","homeAddressUuid","initialAddress","withEffectiveDateField","optionalFieldsToRequire","partnerDefaults","validationMode","shouldFocusError","hasInitialAddressMatch","retrieveHomeAddressQuery","useEmployeeAddressesRetrieveHomeAddress","isCreateMode","fetchedHomeAddress","schemaMode","schema","metadataConfig","useMemo","createHomeAddressSchema","resolvedDefaults","formMethods","useForm","zodResolver","createHomeAddressMutation","useEmployeeAddressesCreateMutation","updateHomeAddressMutation","useEmployeeAddressesUpdateMutation","isPending","baseSubmitHandler","submitError","setSubmitError","useBaseSubmit","errorHandling","composeErrorHandler","stateOptions","STATES_ABBR","abbr","baseMetadata","useDeriveFieldsMetadata","fieldsMetadata","withOptions","onSubmit","options","submitResult","resolve","data","payload","resolvedEmployeeId","resolvedEffectiveDate","effectiveDateParam","RFCDate","updatedHomeAddress","result","SDKInternalError","hookFormInternals","useHookFormInternals","Street1Field","Street2Field","CityField","StateField","ZipField","CourtesyWithholdingField","EffectiveDateField","createGetFormSubmissionValues"],"mappings":"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"}

package/dist/components/Employee/Profile/shared/useWorkAddressForm/fields.d.ts

@@ -3,8 +3,51 @@ import { WorkAddressErrorCodes } from './workAddressSchema';
 import { SelectHookFieldProps } from '../../../../../partner-hook-utils/form/fields/SelectHookField';
 import { DatePickerHookFieldProps } from '../../../../../partner-hook-utils/form/fields/DatePickerHookField';
 import { HookFieldProps } from '../../../../../partner-hook-utils/types';
+/**
+ * The required-field error code produced by {@link useWorkAddressForm} fields that only emit `REQUIRED`.
+ *
+ * @remarks
+ * Used as the `validationMessages` key for the location and effective date fields.
+ * See `WorkAddressErrorCodes`.
+ *
+ * @public
+ */
 export type RequiredValidation = typeof WorkAddressErrorCodes.REQUIRED;
+/**
+ * Props accepted by {@link useWorkAddressForm}'s `Fields.Location` component.
+ *
+ * @public
+ */
 export type LocationFieldProps = HookFieldProps<SelectHookFieldProps<RequiredValidation, Location>>;
+/**
+ * Select bound to the `locationUuid` field of {@link useWorkAddressForm}.
+ *
+ * @remarks
+ * Available on the hook result as `form.Fields.Location`. Options are the
+ * company's active locations; the hook populates them from the locations
+ * query. Required.
+ *
+ * @param props - {@link LocationFieldProps} — accepts the standard hook field props plus `getOptionLabel` to format location display names.
+ * @returns The rendered select bound to `locationUuid`.
+ * @public
+ */
 export declare function LocationField(props: LocationFieldProps): import("react").JSX.Element;
+/**
+ * Props accepted by {@link useWorkAddressForm}'s `Fields.EffectiveDate` component.
+ *
+ * @public
+ */
 export type EffectiveDateFieldProps = HookFieldProps<DatePickerHookFieldProps<RequiredValidation>>;
+/**
+ * Date picker bound to the `effectiveDate` field of {@link useWorkAddressForm}.
+ *
+ * @remarks
+ * Available on the hook result as `form.Fields.EffectiveDate` when
+ * `withEffectiveDateField` is `true`; `undefined` otherwise. Always
+ * null-check before rendering.
+ *
+ * @param props - {@link EffectiveDateFieldProps} — accepts the standard hook field props (label, description, validationMessages, FieldComponent override).
+ * @returns The rendered date picker bound to `effectiveDate`.
+ * @public
+ */
 export declare function EffectiveDateField(props: EffectiveDateFieldProps): import("react").JSX.Element;

package/dist/components/Employee/Profile/shared/useWorkAddressForm/fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"fields.js","sources":["../../../../../../src/components/Employee/Profile/shared/useWorkAddressForm/fields.tsx"],"sourcesContent":["import type { Location } from '@gusto/embedded-api-v-2025-11-15/models/components/location'\nimport type { WorkAddressErrorCodes } from './workAddressSchema'\nimport type { SelectHookFieldProps } from '@/partner-hook-utils/form/fields/SelectHookField'\nimport type { DatePickerHookFieldProps } from '@/partner-hook-utils/form/fields/DatePickerHookField'\nimport { SelectHookField, DatePickerHookField } from '@/partner-hook-utils/form/fields'\nimport type { HookFieldProps } from '@/partner-hook-utils/types'\n\nexport type RequiredValidation = typeof WorkAddressErrorCodes.REQUIRED\n\nexport type LocationFieldProps = HookFieldProps<SelectHookFieldProps<RequiredValidation, Location>>\n\nexport function LocationField(props: LocationFieldProps) {\n  return <SelectHookField {...props} name=\"locationUuid\" />\n}\n\nexport type EffectiveDateFieldProps = HookFieldProps<DatePickerHookFieldProps<RequiredValidation>>\n\nexport function EffectiveDateField(props: EffectiveDateFieldProps) {\n  return <DatePickerHookField {...props} name=\"effectiveDate\" />\n}\n"],"names":["LocationField","props","jsx","SelectHookField","EffectiveDateField","DatePickerHookField"],"mappings":";;;AAWO,SAASA,EAAcC,GAA2B;AACvD,SAAO,gBAAAC,EAACC,GAAA,EAAiB,GAAGF,GAAO,MAAK,gBAAe;AACzD;AAIO,SAASG,EAAmBH,GAAgC;AACjE,SAAO,gBAAAC,EAACG,GAAA,EAAqB,GAAGJ,GAAO,MAAK,iBAAgB;AAC9D;"}
+{"version":3,"file":"fields.js","sources":["../../../../../../src/components/Employee/Profile/shared/useWorkAddressForm/fields.tsx"],"sourcesContent":["import type { Location } from '@gusto/embedded-api-v-2025-11-15/models/components/location'\nimport type { WorkAddressErrorCodes } from './workAddressSchema'\nimport type { SelectHookFieldProps } from '@/partner-hook-utils/form/fields/SelectHookField'\nimport type { DatePickerHookFieldProps } from '@/partner-hook-utils/form/fields/DatePickerHookField'\nimport { SelectHookField, DatePickerHookField } from '@/partner-hook-utils/form/fields'\nimport type { HookFieldProps } from '@/partner-hook-utils/types'\n\n/**\n * The required-field error code produced by {@link useWorkAddressForm} fields that only emit `REQUIRED`.\n *\n * @remarks\n * Used as the `validationMessages` key for the location and effective date fields.\n * See `WorkAddressErrorCodes`.\n *\n * @public\n */\nexport type RequiredValidation = typeof WorkAddressErrorCodes.REQUIRED\n\n/**\n * Props accepted by {@link useWorkAddressForm}'s `Fields.Location` component.\n *\n * @public\n */\nexport type LocationFieldProps = HookFieldProps<SelectHookFieldProps<RequiredValidation, Location>>\n\n/**\n * Select bound to the `locationUuid` field of {@link useWorkAddressForm}.\n *\n * @remarks\n * Available on the hook result as `form.Fields.Location`. Options are the\n * company's active locations; the hook populates them from the locations\n * query. Required.\n *\n * @param props - {@link LocationFieldProps} — accepts the standard hook field props plus `getOptionLabel` to format location display names.\n * @returns The rendered select bound to `locationUuid`.\n * @public\n */\nexport function LocationField(props: LocationFieldProps) {\n  return <SelectHookField {...props} name=\"locationUuid\" />\n}\n\n/**\n * Props accepted by {@link useWorkAddressForm}'s `Fields.EffectiveDate` component.\n *\n * @public\n */\nexport type EffectiveDateFieldProps = HookFieldProps<DatePickerHookFieldProps<RequiredValidation>>\n\n/**\n * Date picker bound to the `effectiveDate` field of {@link useWorkAddressForm}.\n *\n * @remarks\n * Available on the hook result as `form.Fields.EffectiveDate` when\n * `withEffectiveDateField` is `true`; `undefined` otherwise. Always\n * null-check before rendering.\n *\n * @param props - {@link EffectiveDateFieldProps} — accepts the standard hook field props (label, description, validationMessages, FieldComponent override).\n * @returns The rendered date picker bound to `effectiveDate`.\n * @public\n */\nexport function EffectiveDateField(props: EffectiveDateFieldProps) {\n  return <DatePickerHookField {...props} name=\"effectiveDate\" />\n}\n"],"names":["LocationField","props","jsx","SelectHookField","EffectiveDateField","DatePickerHookField"],"mappings":";;;AAqCO,SAASA,EAAcC,GAA2B;AACvD,SAAO,gBAAAC,EAACC,GAAA,EAAiB,GAAGF,GAAO,MAAK,gBAAe;AACzD;AAqBO,SAASG,EAAmBH,GAAgC;AACjE,SAAO,gBAAAC,EAACG,GAAA,EAAqB,GAAGJ,GAAO,MAAK,iBAAgB;AAC9D;"}

package/dist/components/Employee/Profile/shared/useWorkAddressForm/index.d.ts

@@ -2,6 +2,7 @@ import "./types/i18next.d.ts"
 export { useWorkAddressForm } from './useWorkAddressForm';
 export { useCurrentWorkAddressForm } from './useCurrentWorkAddressForm';
 export type { UseCurrentWorkAddressFormProps } from './useCurrentWorkAddressForm';
-export type { WorkAddressSubmitCallbacks, WorkAddressSubmitOptions, WorkAddressOptionalFieldsToRequire, UseWorkAddressFormProps, UseWorkAddressFormResult, UseWorkAddressFormReady, WorkAddressFieldsMetadata, WorkAddressFormFields, } from './useWorkAddressForm';
+export type { WorkAddressSubmitCallbacks, WorkAddressSubmitOptions, WorkAddressOptionalFieldsToRequire, UseWorkAddressFormProps, UseWorkAddressFormResult, UseWorkAddressFormReady, WorkAddressFieldsMetadata, WorkAddressFormFields, WorkAddressFields, } from './useWorkAddressForm';
 export { createWorkAddressSchema, WorkAddressErrorCodes, type WorkAddressErrorCode, type WorkAddressFormData, type WorkAddressFormOutputs, type WorkAddressField, } from './workAddressSchema';
+export { LocationField, EffectiveDateField } from './fields';
 export type { RequiredValidation as WorkAddressRequiredValidation, LocationFieldProps, EffectiveDateFieldProps, } from './fields';

package/dist/components/Employee/Profile/shared/useWorkAddressForm/useCurrentWorkAddressForm.d.ts

@@ -1,3 +1,45 @@
 import { UseWorkAddressFormProps, UseWorkAddressFormResult } from './useWorkAddressForm';
+/**
+ * Options for {@link useCurrentWorkAddressForm}.
+ *
+ * @remarks
+ * Same shape as {@link UseWorkAddressFormProps} minus `workAddressUuid` —
+ * the hook resolves the current work address itself.
+ *
+ * @public
+ */
 export type UseCurrentWorkAddressFormProps = Omit<UseWorkAddressFormProps, 'workAddressUuid'>;
+/**
+ * Convenience wrapper around {@link useWorkAddressForm} that auto-resolves the employee's current work address.
+ *
+ * @remarks
+ * Lists the employee's work addresses and selects the active one (or the
+ * first when none are active) as the row to edit. When the employee has no
+ * work address on file the hook operates in create mode. The returned shape
+ * is identical to {@link useWorkAddressForm}, so the same `Fields`,
+ * `actions.onSubmit`, and `errorHandling` apply.
+ *
+ * @param props - See {@link UseCurrentWorkAddressFormProps}.
+ * @returns A {@link HookLoadingResult} while loading, or a {@link UseWorkAddressFormReady} once ready.
+ * @public
+ *
+ * @example
+ * ```tsx
+ * import { useCurrentWorkAddressForm } from '@gusto/embedded-react-sdk'
+ *
+ * function WorkAddressEditor({ employeeId, companyId }: { employeeId: string; companyId: string }) {
+ *   const workAddress = useCurrentWorkAddressForm({ employeeId, companyId })
+ *
+ *   if (workAddress.isLoading) return <div>Loading...</div>
+ *
+ *   const { Fields } = workAddress.form
+ *   return (
+ *     <form onSubmit={e => { e.preventDefault(); void workAddress.actions.onSubmit() }}>
+ *       <Fields.Location label="Work location" />
+ *       <button type="submit">Save</button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
 export declare function useCurrentWorkAddressForm(props: UseCurrentWorkAddressFormProps): UseWorkAddressFormResult;

package/dist/components/Employee/Profile/shared/useWorkAddressForm/useCurrentWorkAddressForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"useCurrentWorkAddressForm.js","sources":["../../../../../../src/components/Employee/Profile/shared/useWorkAddressForm/useCurrentWorkAddressForm.tsx"],"sourcesContent":["import { useEmployeeAddressesGetWorkAddresses } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesGetWorkAddresses'\nimport { useWorkAddressForm } from './useWorkAddressForm'\nimport type { UseWorkAddressFormProps, UseWorkAddressFormResult } from './useWorkAddressForm'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\n\nexport type UseCurrentWorkAddressFormProps = Omit<UseWorkAddressFormProps, 'workAddressUuid'>\n\nexport function useCurrentWorkAddressForm(\n  props: UseCurrentWorkAddressFormProps,\n): UseWorkAddressFormResult {\n  const { employeeId, ...rest } = props\n\n  const listQuery = useEmployeeAddressesGetWorkAddresses({ employeeId }, { enabled: !!employeeId })\n\n  const workAddresses = listQuery.data?.employeeWorkAddressesList\n  const currentWorkAddress = workAddresses?.find(w => w.active) ?? workAddresses?.[0]\n\n  const base = useWorkAddressForm({\n    ...rest,\n    employeeId,\n    workAddressUuid: currentWorkAddress?.uuid,\n  })\n\n  const listInitiallyBlocking = listQuery.isLoading && !listQuery.data\n\n  if (listInitiallyBlocking) {\n    return {\n      isLoading: true as const,\n      errorHandling: composeErrorHandler([listQuery]),\n    }\n  }\n\n  if (base.isLoading) {\n    return {\n      ...base,\n      errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n    }\n  }\n\n  return {\n    ...base,\n    errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n  }\n}\n"],"names":["useCurrentWorkAddressForm","props","employeeId","rest","listQuery","useEmployeeAddressesGetWorkAddresses","workAddresses","currentWorkAddress","w","base","useWorkAddressForm","composeErrorHandler"],"mappings":";;;AAOO,SAASA,EACdC,GAC0B;AAC1B,QAAM,EAAE,YAAAC,GAAY,GAAGC,EAAA,IAASF,GAE1BG,IAAYC,EAAqC,EAAE,YAAAH,EAAA,GAAc,EAAE,SAAS,CAAC,CAACA,GAAY,GAE1FI,IAAgBF,EAAU,MAAM,2BAChCG,IAAqBD,GAAe,KAAK,CAAAE,MAAKA,EAAE,MAAM,KAAKF,IAAgB,CAAC,GAE5EG,IAAOC,EAAmB;AAAA,IAC9B,GAAGP;AAAA,IACH,YAAAD;AAAA,IACA,iBAAiBK,GAAoB;AAAA,EAAA,CACtC;AAID,SAF8BH,EAAU,aAAa,CAACA,EAAU,OAGvD;AAAA,IACL,WAAW;AAAA,IACX,eAAeO,EAAoB,CAACP,CAAS,CAAC;AAAA,EAAA,IAI9CK,EAAK,YACA;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA,IAIlF;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA;AAEzF;"}
+{"version":3,"file":"useCurrentWorkAddressForm.js","sources":["../../../../../../src/components/Employee/Profile/shared/useWorkAddressForm/useCurrentWorkAddressForm.tsx"],"sourcesContent":["import { useEmployeeAddressesGetWorkAddresses } from '@gusto/embedded-api-v-2025-11-15/react-query/employeeAddressesGetWorkAddresses'\nimport { useWorkAddressForm } from './useWorkAddressForm'\nimport type { UseWorkAddressFormProps, UseWorkAddressFormResult } from './useWorkAddressForm'\nimport { composeErrorHandler } from '@/partner-hook-utils/composeErrorHandler'\n\n/**\n * Options for {@link useCurrentWorkAddressForm}.\n *\n * @remarks\n * Same shape as {@link UseWorkAddressFormProps} minus `workAddressUuid` —\n * the hook resolves the current work address itself.\n *\n * @public\n */\nexport type UseCurrentWorkAddressFormProps = Omit<UseWorkAddressFormProps, 'workAddressUuid'>\n\n/**\n * Convenience wrapper around {@link useWorkAddressForm} that auto-resolves the employee's current work address.\n *\n * @remarks\n * Lists the employee's work addresses and selects the active one (or the\n * first when none are active) as the row to edit. When the employee has no\n * work address on file the hook operates in create mode. The returned shape\n * is identical to {@link useWorkAddressForm}, so the same `Fields`,\n * `actions.onSubmit`, and `errorHandling` apply.\n *\n * @param props - See {@link UseCurrentWorkAddressFormProps}.\n * @returns A {@link HookLoadingResult} while loading, or a {@link UseWorkAddressFormReady} once ready.\n * @public\n *\n * @example\n * ```tsx\n * import { useCurrentWorkAddressForm } from '@gusto/embedded-react-sdk'\n *\n * function WorkAddressEditor({ employeeId, companyId }: { employeeId: string; companyId: string }) {\n *   const workAddress = useCurrentWorkAddressForm({ employeeId, companyId })\n *\n *   if (workAddress.isLoading) return <div>Loading...</div>\n *\n *   const { Fields } = workAddress.form\n *   return (\n *     <form onSubmit={e => { e.preventDefault(); void workAddress.actions.onSubmit() }}>\n *       <Fields.Location label=\"Work location\" />\n *       <button type=\"submit\">Save</button>\n *     </form>\n *   )\n * }\n * ```\n */\nexport function useCurrentWorkAddressForm(\n  props: UseCurrentWorkAddressFormProps,\n): UseWorkAddressFormResult {\n  const { employeeId, ...rest } = props\n\n  const listQuery = useEmployeeAddressesGetWorkAddresses({ employeeId }, { enabled: !!employeeId })\n\n  const workAddresses = listQuery.data?.employeeWorkAddressesList\n  const currentWorkAddress = workAddresses?.find(w => w.active) ?? workAddresses?.[0]\n\n  const base = useWorkAddressForm({\n    ...rest,\n    employeeId,\n    workAddressUuid: currentWorkAddress?.uuid,\n  })\n\n  const listInitiallyBlocking = listQuery.isLoading && !listQuery.data\n\n  if (listInitiallyBlocking) {\n    return {\n      isLoading: true as const,\n      errorHandling: composeErrorHandler([listQuery]),\n    }\n  }\n\n  if (base.isLoading) {\n    return {\n      ...base,\n      errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n    }\n  }\n\n  return {\n    ...base,\n    errorHandling: composeErrorHandler([listQuery, { errorHandling: base.errorHandling }]),\n  }\n}\n"],"names":["useCurrentWorkAddressForm","props","employeeId","rest","listQuery","useEmployeeAddressesGetWorkAddresses","workAddresses","currentWorkAddress","w","base","useWorkAddressForm","composeErrorHandler"],"mappings":";;;AAiDO,SAASA,EACdC,GAC0B;AAC1B,QAAM,EAAE,YAAAC,GAAY,GAAGC,EAAA,IAASF,GAE1BG,IAAYC,EAAqC,EAAE,YAAAH,EAAA,GAAc,EAAE,SAAS,CAAC,CAACA,GAAY,GAE1FI,IAAgBF,EAAU,MAAM,2BAChCG,IAAqBD,GAAe,KAAK,CAAAE,MAAKA,EAAE,MAAM,KAAKF,IAAgB,CAAC,GAE5EG,IAAOC,EAAmB;AAAA,IAC9B,GAAGP;AAAA,IACH,YAAAD;AAAA,IACA,iBAAiBK,GAAoB;AAAA,EAAA,CACtC;AAID,SAF8BH,EAAU,aAAa,CAACA,EAAU,OAGvD;AAAA,IACL,WAAW;AAAA,IACX,eAAeO,EAAoB,CAACP,CAAS,CAAC;AAAA,EAAA,IAI9CK,EAAK,YACA;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA,IAIlF;AAAA,IACL,GAAGA;AAAA,IACH,eAAeE,EAAoB,CAACP,GAAW,EAAE,eAAeK,EAAK,eAAe,CAAC;AAAA,EAAA;AAEzF;"}

package/dist/components/Employee/Profile/shared/useWorkAddressForm/useWorkAddressForm.d.ts

@@ -5,17 +5,46 @@ import { WorkAddressOptionalFieldsToRequire, WorkAddressFormData } from './workA
 import { LocationField, EffectiveDateField } from './fields';
 import { BaseFormHookReady, FieldsMetadata, HookLoadingResult, HookSubmitResult } from '../../../../../partner-hook-utils/types';
 export type { WorkAddressOptionalFieldsToRequire } from './workAddressSchema';
+/**
+ * Optional callbacks passed to {@link UseWorkAddressFormReady.actions.onSubmit | onSubmit}.
+ *
+ * @remarks
+ * Only the callback matching the submit mode fires —
+ * `onWorkAddressCreated` on create, `onWorkAddressUpdated` on update.
+ *
+ * @public
+ */
 export interface WorkAddressSubmitCallbacks {
+    /** Fired after a new work address is successfully created. */
     onWorkAddressCreated?: (workAddress: EmployeeWorkAddress) => void;
+    /** Fired after an existing work address is successfully updated. */
     onWorkAddressUpdated?: (workAddress: EmployeeWorkAddress) => void;
 }
+/**
+ * Optional overrides passed to {@link UseWorkAddressFormReady.actions.onSubmit | onSubmit}.
+ *
+ * @public
+ */
 export interface WorkAddressSubmitOptions {
+    /** Override the employee identifier supplied to the hook (e.g. after creating a new employee in the same flow). */
     employeeId?: string;
+    /** Override the effective date submitted with the address. */
     effectiveDate?: string;
 }
+/**
+ * Configuration options for {@link useWorkAddressForm}.
+ *
+ * @remarks
+ * Presence or absence of `workAddressUuid` selects the API verb — see the
+ * `workAddressUuid` field description. `companyId` is required to fetch
+ * the location list; pass it when it is known.
+ *
+ * @public
+ */
 export interface UseWorkAddressFormProps {
     /** Company UUID for locations; omit or leave unset while resolving from the employee record. */
     companyId?: string;
+    /** UUID of the employee whose work address is being created or edited. */
     employeeId: string;
     /**
      * When set, loads that work address via GET `/v1/work_addresses/{work_address_uuid}` and updates it (PUT).
@@ -27,31 +56,87 @@ export interface UseWorkAddressFormProps {
      * instead of issuing a GET — useful when the parent already has the row from a list query.
      */
     initialAddress?: EmployeeWorkAddress;
+    /** When `true`, renders `Fields.EffectiveDate`; otherwise it is `undefined`. Defaults to `true`. */
     withEffectiveDateField?: boolean;
+    /** Override fields that are optional on a given mode to be required. See `WorkAddressOptionalFieldsToRequire`. */
     optionalFieldsToRequire?: WorkAddressOptionalFieldsToRequire;
+    /** Pre-fill form values. Server data takes precedence on update. */
     defaultValues?: Partial<WorkAddressFormData>;
+    /** Passed through to react-hook-form. Defaults to `'onSubmit'`. */
     validationMode?: UseFormProps['mode'];
+    /** Auto-focus the first invalid field on submit. Set to `false` when using `composeSubmitHandler` so submit-time focus is coordinated across multiple forms. Defaults to `true`. */
     shouldFocusError?: boolean;
 }
+/**
+ * Pre-bound field components exposed on `useWorkAddressForm().form.Fields`.
+ *
+ * @remarks
+ * `EffectiveDate` is `undefined` when `withEffectiveDateField` is `false`.
+ * Always null-check it before rendering.
+ *
+ * @public
+ */
 export interface WorkAddressFields {
+    /** Location selector. Always available. */
     Location: typeof LocationField;
+    /** Effective-date picker. Only available when `withEffectiveDateField` is `true`. */
     EffectiveDate: typeof EffectiveDateField | undefined;
 }
+/**
+ * Ready-state shape returned by {@link useWorkAddressForm} once data has loaded.
+ *
+ * @remarks
+ * Discriminated by `isLoading: false`. Extends {@link BaseFormHookReady} with
+ * the work-address-specific `data`, `status`, `actions`, and `form.Fields` shape.
+ *
+ * @public
+ */
 export interface UseWorkAddressFormReady extends BaseFormHookReady<FieldsMetadata, WorkAddressFormData, WorkAddressFields> {
+    /** Static entity data resolved from the API. */
     data: {
         /** The address row loaded for update; `null` in create mode. */
         workAddress: EmployeeWorkAddress | null;
+        /** Company locations available for selection; `undefined` until the locations query resolves. */
         companyLocations: Location[] | undefined;
     };
+    /** Reactive status flags. */
     status: {
         isPending: boolean;
         mode: 'create' | 'update';
     };
+    /** Available actions. */
     actions: {
         onSubmit: (callbacks?: WorkAddressSubmitCallbacks, options?: WorkAddressSubmitOptions) => Promise<HookSubmitResult<EmployeeWorkAddress> | undefined>;
     };
 }
+/**
+ * Form hook for creating or editing an employee's work address.
+ *
+ * @remarks
+ * When `workAddressUuid` is supplied the hook loads that address and issues a PUT on submit;
+ * when omitted it operates in create mode and issues a POST. The hook requires `companyId`
+ * to fetch the company's location list — it stays in loading state until `companyId` is known.
+ *
+ * @param props - See {@link UseWorkAddressFormProps}.
+ * @returns A {@link HookLoadingResult} while loading, or a {@link UseWorkAddressFormReady} once ready.
+ * @public
+ */
 export declare function useWorkAddressForm({ companyId, employeeId, workAddressUuid, initialAddress, withEffectiveDateField, optionalFieldsToRequire, defaultValues: partnerDefaults, validationMode, shouldFocusError, }: UseWorkAddressFormProps): HookLoadingResult | UseWorkAddressFormReady;
+/**
+ * Discriminated union returned by {@link useWorkAddressForm}.
+ *
+ * @public
+ */
 export type UseWorkAddressFormResult = HookLoadingResult | UseWorkAddressFormReady;
+/**
+ * Type of `form.fieldsMetadata` returned by {@link useWorkAddressForm}.
+ *
+ * @public
+ */
 export type WorkAddressFieldsMetadata = UseWorkAddressFormReady['form']['fieldsMetadata'];
+/**
+ * Type of `form.Fields` returned by {@link useWorkAddressForm}.
+ *
+ * @public
+ */
 export type WorkAddressFormFields = UseWorkAddressFormReady['form']['Fields'];