@gusto/embedded-react-sdk 0.55.8 → 0.56.1

package/dist/src/components/Common/UI/Menu/MenuTypes.d.ts

@@ -61,7 +61,7 @@ export interface MenuProps extends DataAttributes {
     'aria-label': string;
     /**
      * Element to use as the portal container for the menu popover.
-     * Overrides the default SDK root container from context.
+     * Overrides the SDK's default portal root (a themed element appended to `document.body`).
      */
     portalContainer?: HTMLElement;
     /**

package/dist/src/components/Common/UI/MultiSelectComboBox/MultiSelectComboBox.d.ts

@@ -6,4 +6,4 @@ import { MultiSelectComboBoxProps } from './MultiSelectComboBoxTypes';
  * @returns The rendered multi-select combo box field.
  * @internal
  */
-export declare function MultiSelectComboBox({ className, description, errorMessage, id, inputRef: inputRefFromProps, isDisabled, isInvalid, isLoading, isRequired, label, name, onBlur, onChange, options, placeholder, value: selectedValues, shouldVisuallyHideLabel, }: MultiSelectComboBoxProps): import("react").JSX.Element;
+export declare function MultiSelectComboBox({ className, description, errorMessage, id, inputRef: inputRefFromProps, isDisabled, isInvalid, isLoading, isRequired, label, name, onBlur, onChange, options, placeholder, portalContainer, value: selectedValues, shouldVisuallyHideLabel, }: MultiSelectComboBoxProps): import("react").JSX.Element;

package/dist/src/components/Common/UI/MultiSelectComboBox/MultiSelectComboBoxTypes.d.ts

@@ -65,4 +65,9 @@ export interface MultiSelectComboBoxProps extends SharedFieldLayoutProps, Pick<I
      * Handler for blur events
      */
     onBlur?: () => void;
+    /**
+     * Element to use as the portal container for the dropdown popover.
+     * Overrides the SDK's default portal root (a themed element appended to `document.body`).
+     */
+    portalContainer?: HTMLElement;
 }

package/dist/src/components/Common/UI/Select/SelectTypes.d.ts

@@ -62,7 +62,8 @@ export interface SelectProps extends SharedFieldLayoutProps, Pick<SelectHTMLAttr
      */
     inputRef?: Ref<HTMLButtonElement>;
     /**
-     * Element to use as the portal container
+     * Element to use as the portal container for the popover.
+     * Overrides the SDK's default portal root (a themed element appended to `document.body`).
      */
     portalContainer?: HTMLElement;
 }

package/dist/src/components/Employee/EmployeeList/shared/useEmployeeList.d.ts

@@ -20,6 +20,8 @@ export interface EmployeeWithActions extends Employee {
     allowedActions: EmployeeAction[];
     /** The employee's primary job, if one is marked primary. */
     primaryJob?: Job;
+    /** Effective date of a termination that hasn't gone into effect yet, if one is scheduled. */
+    pendingDismissalDate?: string;
 }
 /**
  * Filter applied to {@link useEmployeeList} that scopes the result set and tailors the per-row action list.
@@ -73,8 +75,11 @@ export type UseEmployeeListResult = HookLoadingResult | UseEmployeeListReady;
  *
  * @remarks
  * `employeeType` maps to a server-side filter and changes which actions appear on each row:
- * `'active'` adds `dismiss`, `'terminated'` adds `rehire`, `'onboarding'` adds none. Omit it
- * to list every employee.
+ * `'active'` adds `dismiss` unless the employee already has a termination scheduled for a future
+ * date, `'terminated'` adds `rehire`, `'onboarding'` adds none. Omit it to list every employee.
+ *
+ * An `'active'` row with a pending termination carries its effective date on
+ * `pendingDismissalDate` instead of the `dismiss` action.
  *
  * `'onboarding'` includes employees who haven't completed onboarding as well as employees who
  * have completed onboarding but whose primary job's hire date hasn't arrived yet, so `onboarded`

package/dist/src/components/Employee/EmployeeListFlow/employeeListStateMachine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/components/Payroll/OffCycle/OffCycleFlow.d.ts

@@ -14,12 +14,14 @@ import { OffCycleFlowProps } from './OffCycleFlowComponents';
  * | ----- | ----------- | ---- |
  * | `breadcrumb/navigate` | User navigates via the flow breadcrumb header | `{ key: string }` |
  * | `offCycle/created` | Off-cycle payroll has been created and the flow transitions to execution | `{ payrollUuid: string }` |
+ * | `offCycle/blockers/viewAll` | User opens the payroll blockers step from the creation screen's blocker alert | none |
  *
  * Once the flow transitions to execution, all standard run-payroll events are emitted
  * (e.g. `runPayroll/calculated`, `runPayroll/submitted`, `runPayroll/processed`).
  *
  * @components
  * - {@link OffCycleCreation}
+ * - {@link PayrollBlockerList}
  * - {@link PayrollExecutionFlow}
  *
  * @param props - {@link OffCycleFlowProps}

package/dist/src/components/Payroll/OffCycle/OffCycleFlowComponents.d.ts

@@ -35,4 +35,6 @@ export interface OffCycleFlowProps {
 /** @internal */
 export declare function OffCycleCreationContextual(): import("react").JSX.Element;
 /** @internal */
+export declare function PayrollBlockerListContextual(): import("react").JSX.Element;
+/** @internal */
 export declare function OffCycleExecutionContextual(): import("react").JSX.Element;

package/dist/src/components/Payroll/OffCycle/offCycleStateMachine.d.ts

@@ -4,5 +4,6 @@ export declare const offCycleBreadcrumbsNodes: BreadcrumbNodes;
 /** @internal */
 export declare const offCycleMachine: {
     createOffCyclePayroll: import('robot3').MachineState<any>;
+    blockers: import('robot3').MachineState<any>;
     execution: import('robot3').MachineState<any>;
 };

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

@@ -10,6 +10,7 @@ import { OffCycleCreationProps } from './OffCycleCreationTypes';
  * | Event | Description | Data |
  * | ----- | ----------- | ---- |
  * | `offCycle/created` | The off-cycle payroll has been created | `{ payrollUuid: string }` |
+ * | `offCycle/blockers/viewAll` | The user chose to view the company's payroll blockers from the blocker alert | none |
  *
  * Changing the reason updates the deduction and withholding defaults — `'bonus'` skips
  * regular deductions and uses the supplemental withholding rate; `'correction'` includes

package/dist/src/components/Payroll/OffCycleCreation/OffCycleCreationPresentation.d.ts

@@ -1,3 +1,3 @@
 import { OffCycleCreationPresentationProps } from './OffCycleCreationTypes';
 /** @internal */
-export declare function OffCycleCreationPresentation({ employees, isPending, minCheckDate, minCheckOnlyDate, maxDate, minPayPeriodDate, taxWithholdingConfig, isTaxWithholdingModalOpen, onTaxWithholdingEditClick, onTaxWithholdingModalDone, onTaxWithholdingModalCancel, className, }: OffCycleCreationPresentationProps): import("react").JSX.Element;
+export declare function OffCycleCreationPresentation({ employees, blockers, onViewBlockersClick, isPending, minCheckDate, minCheckOnlyDate, maxDate, minPayPeriodDate, taxWithholdingConfig, isTaxWithholdingModalOpen, onTaxWithholdingEditClick, onTaxWithholdingModalDone, onTaxWithholdingModalCancel, className, }: OffCycleCreationPresentationProps): import("react").JSX.Element;

package/dist/src/components/Payroll/OffCycleCreation/OffCycleCreationTypes.d.ts

@@ -1,6 +1,7 @@
 import { OffCycleReason } from '../OffCycleReasonSelection';
 import { OffCyclePayPeriodDateFormData, OffCyclePayrollDateType } from '../OffCyclePayPeriodDateForm';
 import { OffCycleTaxWithholdingConfig } from '../OffCycleTaxWithholdingTable/OffCycleTaxWithholdingTableTypes';
+import { ApiPayrollBlocker } from '../PayrollBlocker/payrollHelpers';
 import { MultiSelectComboBoxOption } from '../../Common/UI/MultiSelectComboBox/MultiSelectComboBoxTypes';
 import { BaseComponentInterface } from '../../Base/Base';
 /**
@@ -33,6 +34,16 @@ export interface OffCycleCreationFormData extends OffCyclePayPeriodDateFormData
 export interface OffCycleCreationPresentationProps {
     /** Selectable employees rendered in the multi-select. */
     employees: MultiSelectComboBoxOption[];
+    /**
+     * Run-payroll blockers for the company. When non-empty, a blocker alert is shown and the
+     * submit action is disabled so the off-cycle payroll cannot be created while a blocker is active.
+     */
+    blockers: ApiPayrollBlocker[];
+    /**
+     * Invoked when the user activates the "View Blockers" action on the blocker alert. The alert
+     * only renders that action when there are multiple blockers or an actionable blocker to resolve.
+     */
+    onViewBlockersClick?: () => void;
     /** Whether the off-cycle create mutation is in flight. */
     isPending?: boolean;
     /** Earliest selectable payment date for direct deposit (today plus the ACH lead time). */

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

@@ -30,7 +30,7 @@ export interface PayrollConfigurationProps extends BaseComponentInterface<'Payro
  * @events
  * | Event | Description | Data |
  * | ----- | ----------- | ---- |
- * | `runPayroll/employee/edit` | An employee row is selected for editing | `{ employeeId, firstName, lastName }` |
+ * | `runPayroll/employee/edit` | An employee row is selected for editing | `{ payrollId, employeeId, firstName, lastName }` |
  * | `runPayroll/employee/skip` | An employee is skipped or unskipped for this payroll | `{ employeeId }` |
  * | `runPayroll/employee/saved` | Employee compensation changes are persisted | `{ payrollPrepared }` |
  * | `runPayroll/calculated` | Payroll calculation completes successfully | `{ payrollId, alert, payPeriod }` |

package/dist/src/components/Payroll/PayrollConfiguration/useCalculationPoll.d.ts

@@ -35,6 +35,11 @@ export interface UseCalculationPollOptions {
     refetch: () => Promise<QueryObserverResult<PayrollsGetQueryData, PayrollsGetQueryError>>;
     onCalculated: (payroll: PayrollShow | undefined) => void;
     onProcessingFailed: (payroll: PayrollShow | undefined) => void;
+    /**
+     * Called when the poll gives up on a non-retryable read error, without ever confirming a
+     * calculated/failed outcome. The raw error is reported to observability by this hook already.
+     */
+    onError: () => void;
 }
 /** @internal */
 export interface CalculationPoll {
@@ -46,5 +51,5 @@ export interface CalculationPoll {
  *
  * @internal
  */
-export declare function useCalculationPoll({ refetch, onCalculated, onProcessingFailed, }: UseCalculationPollOptions): CalculationPoll;
+export declare function useCalculationPoll({ refetch, onCalculated, onProcessingFailed, onError, }: UseCalculationPollOptions): CalculationPoll;
 export {};

package/dist/src/components/Payroll/PayrollEditEmployee/shared/usePayrollEditEmployeeForm/payrollEditEmployeeHelpers.d.ts

@@ -122,6 +122,24 @@ export declare function hasBreakdownsMatchingWorkweeks(hourlyCompensations: Payr
  * @internal
  */
 export declare function derivePayrollEditEmployeeDefaults(employeeCompensation: PayrollEmployeeCompensationsType | undefined, workweeks: NormalizedWorkweek[], hasDirectDepositSetup: boolean, overtimeEarningNames: Set<string>, isOvertimeEligible: boolean, withOvertime: boolean, fixedCompensations?: FixedCompensationEntry[]): PayrollEditEmployeeFormData;
+/**
+ * Coerces cleared-from-loaded workweek cells to `"0"` across both week-mapped
+ * sections (`hours`, `overtimeIncludedEarnings`).
+ *
+ * @remarks
+ * Run just before submit: a workweek input that loaded with a value and was
+ * cleared by the user should submit an explicit `0` for that cell (whether split
+ * by workweek or collapsed to a single box), instead of falling back to the
+ * original value or being blocked by the per-row completeness check. Cells that
+ * were blank at load are untouched. Each returned section is present only when it
+ * actually changed, so the caller can `setValue` selectively.
+ *
+ * @param current - The live form values.
+ * @param defaults - The form's loaded defaults (the API-seeded baseline for the current split mode).
+ * @returns The coerced `hours` and/or `overtimeIncludedEarnings` sections, each omitted when unchanged.
+ * @internal
+ */
+export declare function zeroFillClearedWorkweekCells(current: Pick<PayrollEditEmployeeFormData, 'hours' | 'overtimeIncludedEarnings'>, defaults: Pick<PayrollEditEmployeeFormData, 'hours' | 'overtimeIncludedEarnings'>): Partial<Pick<PayrollEditEmployeeFormData, 'hours' | 'overtimeIncludedEarnings'>>;
 /**
  * Builds the `PayrollUpdate` employee-compensation payload from form values.
  *

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

@@ -70,7 +70,7 @@ export interface PayrollExecutionInternalFlowProps extends PayrollExecutionFlowP
  * | `runPayroll/edit` | Fired when user chooses to edit payroll | — |
  * | `runPayroll/calculated` | Fired when payroll calculation completes | `{ payrollUuid, payPeriod?, alert? }` |
  * | `runPayroll/alreadyProcessed` | Fired when the payroll turns out to already be processed while configuring it; the flow moves to the review screen | `{ payrollId, alert?, payPeriod? }` |
- * | `runPayroll/employee/edit` | Fired when user opens an employee row to edit | `{ employeeId, firstName, lastName }` |
+ * | `runPayroll/employee/edit` | Fired when user opens an employee row to edit | `{ payrollId, employeeId, firstName, lastName }` |
  * | `runPayroll/employee/saved` | Fired when employee edits are saved | — |
  * | `runPayroll/employee/cancelled` | Fired when employee edits are cancelled | — |
  * | `runPayroll/submitting` | Fired when payroll submission begins | — |

package/dist/src/components/Payroll/PayrollExecutionFlow/payrollExecutionMachine.d.ts

@@ -2,6 +2,14 @@ import { BreadcrumbNodes } from '../../Common/FlowBreadcrumbs/FlowBreadcrumbsTyp
 /** @internal */
 export declare const getPayrollExecutionBreadcrumbsNodes: (isDismissal?: boolean) => BreadcrumbNodes;
 /** @internal */
+export declare const calculatedTransition: import('robot3').Transition<"runPayroll/calculated">;
+/** @internal */
+export declare const alreadyProcessedTransition: import('robot3').Transition<"runPayroll/alreadyProcessed">;
+/** @internal */
+export declare const employeeEditTransition: import('robot3').Transition<"runPayroll/employee/edit">;
+/** @internal */
+export declare const blockersViewAllTransition: import('robot3').Transition<"runPayroll/blockers/viewAll">;
+/** @internal */
 export declare const payrollExecutionMachine: {
     configuration: import('robot3').MachineState<any>;
     overview: import('robot3').MachineState<any>;

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

@@ -12,7 +12,7 @@ import { PayrollFlowProps } from './PayrollFlowComponents';
  * | `payroll/review` | A calculated payroll is opened for review | `{ payrollId: string }` |
  * | `runPayroll/calculated` | Payroll calculations complete | — |
  * | `runPayroll/edit` | The user returns to configuration to make changes | — |
- * | `runPayroll/employee/edit` | An employee row is opened for editing | `{ employeeId: string, firstName: string, lastName: string }` |
+ * | `runPayroll/employee/edit` | An employee row is opened for editing | `{ payrollId: string, employeeId: string, firstName: string, lastName: string }` |
  * | `runPayroll/employee/saved` | Employee payroll changes are saved | `{ payrollPrepared: object, employee: object }` |
  * | `runPayroll/employee/cancelled` | Employee editing is cancelled | — |
  * | `runPayroll/submitted` | Payroll is successfully submitted | Response from the submit payroll endpoint |

package/dist/src/components/Payroll/PayrollFlow/TransitionFlowContextual.d.ts

@@ -1,2 +1,7 @@
-/** @internal */
+/**
+ * Adapts the `PayrollFlow` machine context to {@link TransitionFlow}'s props. The resolve/resume
+ * lookup that used to live here now lives inside `TransitionPayroll`, so this is a thin bridge.
+ *
+ * @internal
+ */
 export declare function TransitionFlowContextual(): import("react").JSX.Element;

package/dist/src/components/Payroll/PayrollOverview/useSubmissionPoll.d.ts

@@ -25,6 +25,15 @@ export interface UseSubmissionPollOptions {
     refetch: () => Promise<QueryObserverResult<PayrollsGetQueryData, PayrollsGetQueryError>>;
     onProcessed: (payroll: PayrollShow | undefined) => void;
     onProcessingFailed: (payroll: PayrollShow | undefined) => void;
+    /**
+     * Called when the poll gives up on a non-retryable read error, but only for a run that was
+     * actually tracking a submission (`baseline` set, or a `submitting` status observed mid-run).
+     * A baseline-less mount poll that never saw `submitting` swallows the error here -- it was only
+     * guarding the initial render, not watching a real submission, so surfacing it as a processing
+     * failure would be a false failure. The raw error is reported to observability by this hook
+     * either way.
+     */
+    onError: () => void;
 }
 /** @internal */
 export interface SubmissionPoll {
@@ -36,4 +45,4 @@ export interface SubmissionPoll {
  *
  * @internal
  */
-export declare function useSubmissionPoll({ refetch, onProcessed, onProcessingFailed, }: UseSubmissionPollOptions): SubmissionPoll;
+export declare function useSubmissionPoll({ refetch, onProcessed, onProcessingFailed, onError, }: UseSubmissionPollOptions): SubmissionPoll;

package/dist/src/components/Payroll/Transition/TransitionFlow.d.ts

@@ -1,29 +1,31 @@
 import { TransitionFlowProps } from './TransitionFlowComponents';
 /**
- * Guided flow to run a transition payroll when employees move from one pay schedule to another.
+ * Macro flow that runs a transition payroll end to end: resolve or create the payroll, then
+ * configure, review, submit, and view receipts.
  *
  * @remarks
- * When employees switch from an old pay schedule to a new one, the change can leave a gap between
- * the last pay period on the old schedule and the first on the new one. A transition payroll covers
- * the wages earned during that gap.
+ * Renders {@link TransitionPayroll} as its entry step, then routes the events its configuration
+ * screen emits into the shared payroll-execution states (overview, edit-employee, receipts,
+ * blockers). It owns the breadcrumb chrome and back-navigation, and re-runs the same cached resolve
+ * lookup to seed its initial breadcrumb and payroll context.
  *
- * Starts on the creation step (configure check date, deductions, and tax withholding for the
- * transition pay period). After the payroll is created, the flow hands off to the standard
- * payroll execution experience — configure compensation, review, submit, and view receipts.
- *
- * If a `payrollUuid` is supplied, the flow skips creation and resumes directly in execution.
+ * There is no terminal state (SDK-1169). Completion events bubble via `onEvent` for the parent to
+ * handle (in `Payroll.PayrollFlow` the parent machine does).
  *
  * @events
  * | Event | Description | Data |
  * | ----- | ----------- | ---- |
- * | `breadcrumb/navigate` | Fired when the user navigates back to the creation step via breadcrumbs | `{ key: string }` |
- * | `transition/created` | Fired when the transition payroll is created and the flow advances to execution | `{ payrollUuid: string }` |
+ * | `transition/created` | Fired when the transition payroll is created and the flow advances to configuration | `{ payrollUuid: string }` |
+ * | `breadcrumb/navigate` | Fired when the user navigates via the breadcrumb header | `{ key: string }` |
  *
- * Once execution begins, all standard run-payroll events are emitted as well.
+ * All standard run-payroll events are emitted once configuration begins.
  *
  * @components
- * - {@link TransitionCreation}
- * - {@link PayrollExecutionFlow}
+ * - {@link TransitionPayroll}
+ * - {@link PayrollOverview}
+ * - {@link PayrollEditEmployee}
+ * - {@link PayrollReceipts}
+ * - {@link PayrollBlockerList}
  *
  * @param props - See {@link TransitionFlowProps}.
  * @returns The transition payroll flow.
@@ -50,4 +52,4 @@ import { TransitionFlowProps } from './TransitionFlowComponents';
  * }
  * ```
  */
-export declare function TransitionFlow({ companyId, startDate, endDate, payScheduleUuid, payrollUuid, onEvent, }: TransitionFlowProps): import("react").JSX.Element;
+export declare function TransitionFlow(props: TransitionFlowProps): import("react").JSX.Element;

package/dist/src/components/Payroll/Transition/TransitionFlowComponents.d.ts

@@ -1,22 +1,23 @@
-import { FlowContextInterface } from '../../Flow/useFlow';
+import { PayrollFlowContextInterface } from '../PayrollFlow/PayrollFlowComponents';
 import { OnEventType } from '../../Base/useBase';
 import { EventType } from '../../../shared/constants';
 /**
- * Flow context shape carried through the transition payroll state machine.
+ * Flow context shape carried through the transition payroll macro state machine.
+ *
+ * @remarks
+ * Extends {@link PayrollFlowContextInterface} so the payroll-execution reducers reused by the
+ * transition machine (overview, edit-employee, receipts, blockers) typecheck against a single
+ * shared context shape.
  *
  * @internal
  */
-export interface TransitionFlowContextInterface extends FlowContextInterface {
-    /** Company the transition payroll belongs to. */
-    companyId: string;
+export interface TransitionFlowContextInterface extends PayrollFlowContextInterface {
     /** 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 created transition payroll, populated once creation completes. */
-    payrollUuid?: string;
 }
 /**
  * Props for {@link TransitionFlow}.
@@ -32,12 +33,20 @@ export interface TransitionFlowProps {
     endDate: string;
     /** UUID of the pay schedule the transition is associated with. */
     payScheduleUuid: string;
-    /** UUID of an existing transition payroll. When provided, the flow skips creation and resumes in execution. */
+    /**
+     * UUID of an existing transition payroll. When provided, the flow 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 throughout the flow. Defaults to `true`. */
+    withReimbursements?: boolean;
     /** Callback invoked for each event emitted by the flow and its child steps. */
     onEvent: OnEventType<EventType, unknown>;
 }
-/** @internal */
-export declare function TransitionCreationContextual(): import("react").JSX.Element;
-/** @internal */
-export declare function TransitionExecutionContextual(): import("react").JSX.Element;
+/**
+ * Renders {@link TransitionPayroll} as the entry step of {@link TransitionFlow}, wiring its events
+ * up to the flow's state machine.
+ *
+ * @internal
+ */
+export declare function TransitionPayrollContextual(): import("react").JSX.Element;

package/dist/src/components/Payroll/Transition/transitionStateMachine.d.ts

@@ -1,8 +1,29 @@
 import { BreadcrumbNodes } from '../../Common/FlowBreadcrumbs/FlowBreadcrumbsTypes';
-/** @internal */
+/**
+ * Breadcrumb nodes for the transition payroll macro flow: the creation crumb merged with the
+ * shared payroll-execution crumbs. `configuration` is nested under the creation crumb so the
+ * "Transition Payroll" crumb persists in the trail once the flow advances past creation, matching
+ * the display-only prefix the flow rendered before this refactor.
+ *
+ * @internal
+ */
 export declare const transitionBreadcrumbsNodes: BreadcrumbNodes;
-/** @internal */
+/**
+ * Macro state machine for {@link TransitionFlow}.
+ *
+ * @remarks
+ * The entry state renders {@link TransitionPayroll}; the rest of the states are the shared
+ * {@link payrollExecutionMachine} states, reused via object spread. The entry state reuses that
+ * machine's onward transitions so configuration events route into overview / edit-employee /
+ * blockers.
+ *
+ * @internal
+ */
 export declare const transitionMachine: {
-    createTransitionPayroll: import('robot3').MachineState<any>;
-    execution: import('robot3').MachineState<any>;
+    configuration: import('robot3').MachineState<any>;
+    overview: import('robot3').MachineState<any>;
+    editEmployee: import('robot3').MachineState<any>;
+    receipts: import('robot3').MachineState<any>;
+    blockers: import('robot3').MachineState<any>;
+    transitionPayroll: import('robot3').MachineState<any>;
 };

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/contexts/ApiProvider/ApiProvider.d.ts

@@ -21,9 +21,11 @@ export interface ApiProviderProps {
  * Wires the `@gusto/embedded-api-v-2026-06-15` client and a React Query client into the React tree.
  *
  * @remarks
- * Registers the SDK's `X-Gusto-API-Version` header on every request, applies any default `headers`,
- * and registers user-supplied lifecycle hooks (`beforeCreateRequest`, `beforeRequest`, `afterSuccess`,
- * `afterError`). When no `queryClient` is supplied, one is created with the SDK's defaults so
+ * Registers the SDK's `X-Gusto-API-Version` header on every request, warns via `console.warn` if a
+ * response reports a different `X-Gusto-API-Version` than was requested (e.g. a proxy rewriting the
+ * header), applies any default `headers`, and registers user-supplied lifecycle hooks
+ * (`beforeCreateRequest`, `beforeRequest`, `afterSuccess`, `afterError`). When no `queryClient` is
+ * supplied, one is created with the SDK's defaults so
  * successful mutations under the `['@gusto/embedded-api-v-2026-06-15']` key invalidate every SDK
  * query automatically. Partners who supply their own `QueryClient` are responsible for matching that
  * contract.

package/dist/src/contexts/ApiProvider/apiVersionMismatchHook.d.ts

@@ -0,0 +1,3 @@
+import { AfterErrorHook, AfterSuccessHook } from '../../types/hooks';
+/** @internal */
+export declare const apiVersionMismatchHook: AfterSuccessHook & AfterErrorHook;

package/dist/src/contexts/ApiProvider/apiVersionMismatchHook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/contexts/GustoProvider/GustoProviderCustomUIAdapter.d.ts

@@ -45,7 +45,15 @@ export interface GustoBaseProviderProps {
      * Also exposed to custom UI components via `useNonce`.
      */
     nonce?: string;
-    /** Element to use as the portal container for SDK popovers and dropdowns. Useful when rendering inside a modal or shadow root. */
+    /**
+     * Element to use as the portal container for SDK popovers and dropdowns.
+     * Defaults to a themed root element the SDK appends to `document.body`.
+     *
+     * Pass an element here if rendering inside a modal, or **required** if
+     * rendering inside a shadow root — `document.body` sits outside every
+     * shadow boundary, so without an explicit container overlays would
+     * otherwise escape your shadow root's style encapsulation.
+     */
     portalContainer?: HTMLElement;
     /** Optional TanStack Query `QueryClient`. When omitted, the SDK creates its own client configured for Gusto's API. */
     queryClient?: QueryClient;