@gusto/embedded-react-sdk 0.56.0 → 0.56.1

package/dist/src/components/Payroll/TransitionPayroll/TransitionPayroll.d.ts

@@ -0,0 +1,55 @@
+import { TransitionPayrollProps } from './TransitionPayrollTypes';
+/**
+ * Resolves and runs a transition payroll for a pay-schedule change, picking up an existing
+ * unprocessed transition payroll when one exists and creating one otherwise.
+ *
+ * @remarks
+ * A transition payroll covers the gap that opens when a company changes its pay schedule. This
+ * component looks up whether one already exists for the pay period and picks the starting screen:
+ *
+ * - If it exists, it starts on {@link PayrollConfiguration} for that payroll.
+ * - Otherwise it starts on {@link TransitionCreation}, then advances to {@link PayrollConfiguration}
+ *   once the payroll is created.
+ *
+ * Configuration events (calculate, employee edit, blockers, etc.) are emitted through `onEvent` for
+ * the host to route. Compose it inside {@link TransitionFlow} for the full run-payroll experience,
+ * or handle the events yourself.
+ *
+ * @events
+ * | Event | Description | Data |
+ * | ----- | ----------- | ---- |
+ * | `transition/created` | The transition payroll has been created and the flow advances to configuration | `{ payrollUuid: string }` |
+ *
+ * Once configuration begins, all standard run-payroll events are emitted as well (e.g.
+ * `runPayroll/calculated`, `runPayroll/employee/edit`, `runPayroll/blockers/viewAll`).
+ *
+ * @components
+ * - {@link TransitionCreation}
+ * - {@link PayrollConfiguration}
+ *
+ * @param props - See {@link TransitionPayrollProps}.
+ * @returns The transition payroll component.
+ * @public
+ *
+ * @example
+ * ```tsx title="App.tsx"
+ * import { Payroll, type EventType } from '@gusto/embedded-react-sdk'
+ *
+ * function MyApp() {
+ *   return (
+ *     <Payroll.TransitionPayroll
+ *       companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+ *       startDate="2025-01-16"
+ *       endDate="2025-01-31"
+ *       payScheduleUuid="c75c1ef6-2ec0-4cca-94a5-8b4cf7e5ea21"
+ *       onEvent={(eventType: EventType) => {
+ *         if (eventType === 'runPayroll/calculated') {
+ *           // Payroll calculated — navigate to your review screen
+ *         }
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export declare function TransitionPayroll(props: TransitionPayrollProps): import("react").JSX.Element;

package/dist/src/components/Payroll/TransitionPayroll/TransitionPayrollComponents.d.ts

@@ -0,0 +1,24 @@
+import { FlowContextInterface } from '../../Flow/useFlow';
+/**
+ * Flow context shape carried through the {@link TransitionPayroll} state machine.
+ *
+ * @internal
+ */
+export interface TransitionPayrollContextInterface extends FlowContextInterface {
+    /** Company the transition payroll belongs to. */
+    companyId: string;
+    /** Start date of the transition pay period (YYYY-MM-DD). */
+    startDate: string;
+    /** End date of the transition pay period (YYYY-MM-DD). */
+    endDate: string;
+    /** UUID of the pay schedule the transition is associated with. */
+    payScheduleUuid: string;
+    /** UUID of the transition payroll once it has been resolved or created. */
+    payrollUuid?: string;
+    /** Whether reimbursement fields are shown on the configuration screen. Defaults to `true`. */
+    withReimbursements?: boolean;
+}
+/** @internal */
+export declare function TransitionCreationContextual(): import("react").JSX.Element;
+/** @internal */
+export declare function PayrollConfigurationContextual(): import("react").JSX.Element;

package/dist/src/components/Payroll/TransitionPayroll/TransitionPayrollTypes.d.ts

@@ -0,0 +1,23 @@
+import { BaseComponentInterface } from '../../Base/Base';
+/**
+ * Props for {@link TransitionPayroll}.
+ *
+ * @public
+ */
+export interface TransitionPayrollProps extends BaseComponentInterface {
+    /** The company running the transition payroll. */
+    companyId: string;
+    /** The start date of the transition pay period (YYYY-MM-DD). */
+    startDate: string;
+    /** The end date of the transition pay period (YYYY-MM-DD). */
+    endDate: string;
+    /** The UUID of the pay schedule the transition is associated with. */
+    payScheduleUuid: string;
+    /**
+     * UUID of an existing transition payroll. When provided, the component skips the lookup and starts
+     * on configuration for this payroll. When omitted, it resolves the payroll for the pay period.
+     */
+    payrollUuid?: string;
+    /** Whether reimbursement fields are shown on the configuration screen. Defaults to `true`. */
+    withReimbursements?: boolean;
+}

package/dist/src/components/Payroll/TransitionPayroll/index.d.ts

@@ -0,0 +1,2 @@
+export { TransitionPayroll } from './TransitionPayroll';
+export type { TransitionPayrollProps } from './TransitionPayrollTypes';

package/dist/src/components/Payroll/TransitionPayroll/transitionPayrollStateMachine.d.ts

@@ -0,0 +1,15 @@
+/**
+ * State machine for {@link TransitionPayroll}.
+ *
+ * @remarks
+ * `creation` shows {@link TransitionCreation}; `configuration` shows {@link PayrollConfiguration}.
+ * The component freezes the initial state from the resolve lookup. `configuration` has no outgoing
+ * transitions (a plain zero-transition state, not a robot3 final state per SDK-1169) so its events
+ * bubble via `onEvent` and the screen keeps working if the host stays mounted past completion.
+ *
+ * @internal
+ */
+export declare const transitionPayrollMachine: {
+    creation: import('robot3').MachineState<any>;
+    configuration: import('robot3').MachineState<any>;
+};

package/dist/src/components/Payroll/TransitionPayroll/useResolveTransitionPayroll.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Arguments describing the transition pay period to resolve.
+ *
+ * @internal
+ */
+export interface ResolveTransitionPayrollArgs {
+    companyId: string;
+    startDate: string;
+    endDate: string;
+    payScheduleUuid: string;
+}
+/**
+ * Looks up an existing unprocessed transition payroll for the given pay period.
+ *
+ * @remarks
+ * A transition payroll is an unprocessed off-cycle payroll whose `offCycleReason` is
+ * `"Transition from old pay schedule"` and whose pay period matches the supplied
+ * `startDate`, `endDate`, and `payScheduleUuid`. When the company changed its pay schedule
+ * the platform creates exactly one such payroll for the coverage gap; this hook finds it so
+ * the caller can resume it instead of creating a duplicate.
+ *
+ * Backed by a suspense query, so callers must render it under a suspense boundary.
+ *
+ * @param args - The pay period to match. See {@link ResolveTransitionPayrollArgs}.
+ * @returns The matching payroll's UUID, or `undefined` when none exists yet.
+ * @internal
+ */
+export declare function useResolveTransitionPayroll({ companyId, startDate, endDate, payScheduleUuid, }: ResolveTransitionPayrollArgs): string | undefined;

package/dist/src/components/Payroll/index.d.ts

@@ -40,3 +40,5 @@ export { TransitionFlow } from './Transition';
 export type { TransitionFlowProps } from './Transition';
 export { TransitionCreation } from './TransitionCreation';
 export type { TransitionCreationProps, TransitionCreationFormData } from './TransitionCreation';
+export { TransitionPayroll } from './TransitionPayroll';
+export type { TransitionPayrollProps } from './TransitionPayroll';

package/dist/src/i18n/types.d.ts

@@ -7230,7 +7230,13 @@ export namespace Translations {
     defaultBlockerDescription: string
     /** @defaultValue `"Please contact support."` */
     defaultBlockerHelp: string
+    /** @defaultValue `"Payroll blocker"` */
+    genericBlockerTitle: string
     blockers: {
+      partner_tos_not_accepted: {
+        /** @defaultValue `"Terms of Service Required"` */
+        title: string
+      }
       geocode_error: {
         /** @defaultValue `"Address Verification Failed"` */
         title: string

package/dist/src/shared/constants.d.ts

@@ -446,6 +446,7 @@ export declare const printChecksEvents: {
  */
 export declare const offCycleEvents: {
     readonly OFF_CYCLE_CREATED: "offCycle/created";
+    readonly OFF_CYCLE_BLOCKERS_VIEW_ALL: "offCycle/blockers/viewAll";
     readonly DISMISSAL_PAY_PERIOD_SELECTED: "dismissal/payPeriod/selected";
     readonly TRANSITION_CREATED: "transition/created";
     readonly RUN_TRANSITION_PAYROLL: "transition/runPayroll";
@@ -559,6 +560,7 @@ export declare const componentEvents: {
     readonly EMPLOYEE_TERMINATION_RUN_OFF_CYCLE_PAYROLL: "employee/termination/runOffCyclePayroll";
     readonly EMPLOYEE_TERMINATION_VIEW_SUMMARY: "employee/termination/viewSummary";
     readonly OFF_CYCLE_CREATED: "offCycle/created";
+    readonly OFF_CYCLE_BLOCKERS_VIEW_ALL: "offCycle/blockers/viewAll";
     readonly DISMISSAL_PAY_PERIOD_SELECTED: "dismissal/payPeriod/selected";
     readonly TRANSITION_CREATED: "transition/created";
     readonly RUN_TRANSITION_PAYROLL: "transition/runPayroll";

package/docs/guides/endpoint-inventory.json

@@ -297,11 +297,6 @@
     },
     "Payroll.PayrollFlow": {
       "endpoints": [
-        {
-          "method": "GET",
-          "path": "/v1/companies/:companyId/payrolls",
-          "docsUrl": "https://docs.gusto.com/embedded-payroll/v2026-06-15/reference/get-v1-companies-company_id-payrolls"
-        },
         {
           "method": "GET",
           "path": "/v1/companies/:companyId/payrolls/:payrollId",
@@ -507,19 +502,6 @@
         "payrollId"
       ]
     },
-    "Payroll.TransitionFlow": {
-      "endpoints": [
-        {
-          "method": "GET",
-          "path": "/v1/companies/:companyId/payrolls/:payrollId",
-          "docsUrl": "https://docs.gusto.com/embedded-payroll/v2026-06-15/reference/get-v1-companies-company_id-payrolls-payroll_id"
-        }
-      ],
-      "variables": [
-        "companyId",
-        "payrollId"
-      ]
-    },
     "Payroll.TransitionCreation": {
       "endpoints": [
         {
@@ -543,6 +525,18 @@
         "companyUuid"
       ]
     },
+    "Payroll.TransitionPayroll": {
+      "endpoints": [
+        {
+          "method": "GET",
+          "path": "/v1/companies/:companyId/payrolls",
+          "docsUrl": "https://docs.gusto.com/embedded-payroll/v2026-06-15/reference/get-v1-companies-company_id-payrolls"
+        }
+      ],
+      "variables": [
+        "companyId"
+      ]
+    },
     "TimeOff.PolicyList": {
       "endpoints": [
         {
@@ -2654,6 +2648,7 @@
     "Payroll.OffCycleFlow": {
       "blocks": [
         "Payroll.OffCycleCreation",
+        "Payroll.PayrollBlockerList",
         "Payroll.PayrollExecutionFlow"
       ]
     },
@@ -2678,7 +2673,7 @@
     "Payroll.TransitionFlow": {
       "blocks": [
         "Payroll.PayrollExecutionFlow",
-        "Payroll.TransitionCreation"
+        "Payroll.TransitionPayroll"
       ]
     },
     "TimeOff.TimeOffFlow": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusto/embedded-react-sdk",
-  "version": "0.56.0",
+  "version": "0.56.1",
   "homepage": "https://github.com/Gusto/embedded-react-sdk",
   "bugs": {
     "url": "https://github.com/Gusto/embedded-react-sdk/issues"
@@ -125,7 +125,7 @@
     "ajv": "^8.20.0",
     "axe-core": "^4.13.0",
     "cspell": "^10.3.3",
-    "dotenv": "^18.0.0",
+    "dotenv": "^18.0.1",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
@@ -152,7 +152,7 @@
     "react-dnd": "^16.0.1",
     "react-dnd-html5-backend": "^16.0.1",
     "react-router-dom": "^7.18.4",
-    "release-it": "^21.0.3",
+    "release-it": "^21.1.0",
     "sass-embedded": "^1.104.1",
     "storybook": "^10.5.5",
     "stylelint-config-standard": "^40.0.0",
@@ -185,7 +185,7 @@
     "conventional-commits-filter": "^5.0.0"
   },
   "dependencies": {
-    "@gusto/embedded-api": "npm:@gusto/embedded-api-v-2026-06-15@0.3.0-rc.2",
+    "@gusto/embedded-api": "npm:@gusto/embedded-api-v-2026-06-15@0.3.0-rc.5",
     "@hookform/error-message": "^2.0.1",
     "@hookform/resolvers": "^5.9.1",
     "@internationalized/date": "^3.12.4",