@gusto/embedded-react-sdk 0.55.8 → 0.56.0

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;

package/dist/src/contexts/ThemeProvider/ThemeProvider.d.ts

@@ -6,10 +6,15 @@ export interface ThemeProviderProps {
     theme?: Partial<GustoSDKTheme>;
     /**
      * Element to use as the portal container for all SDK overlays (Select, ComboBox,
-     * DatePicker, Menu, etc.). Defaults to the SDK's root article element.
+     * DatePicker, Menu, etc.). Defaults to a themed root element the SDK appends
+     * directly to `document.body`, so overlays are never affected by a host page's
+     * `position`, `transform`, `filter`, or `contain` on an intervening ancestor.
+     * That default root carries both the `GSDK` and `GSDK-portal-root` classes —
+     * the latter lets a host page's own `.GSDK` overrides exclude it
+     * (`.GSDK:not(.GSDK-portal-root)`) instead of reaching overlay content.
      *
-     * Pass `document.body` (or another stable element outside the SDK's container)
-     * when your app's scroll or clipping context interferes with overlay positioning.
+     * Pass a specific element (e.g. when rendering inside a modal or shadow root)
+     * to portal overlays there instead.
      */
     portalContainer?: HTMLElement;
     /** Subtree rendered inside the SDK's themed root element. */

package/dist/src/hooks/usePollingTask/usePollingTask.d.ts

@@ -1,15 +1,54 @@
 /**
  * The outcome of evaluating a single poll tick.
  *
+ * @remarks
+ * `'done'` (a domain-understood outcome, success or real failure) and `'error'` (the read failed
+ * in a way not worth retrying, so the poll never learned what happened) are both terminal but go
+ * to different callbacks — `onDone` and `onError` — so callers can't conflate the two.
+ *
  * @typeParam TValue - The terminal value handed to `onDone`.
  * @internal
  */
 export type PollTickResult<TValue> = {
-    done: true;
+    status: 'polling';
+} | {
+    status: 'done';
     value: TValue;
 } | {
-    done: false;
+    status: 'error';
+    error: unknown;
 };
+/**
+ * The result of one poll tick's read — the data it resolved to, or the error it rejected with.
+ *
+ * @remarks
+ * `lastData` (rejection only) is the most recent successfully-read data, or `null` if none has
+ * succeeded yet — the same value `onDeadline` receives, and worth verifying against for the same
+ * reason.
+ *
+ * @typeParam TData - The value a successful read resolves to.
+ * @internal
+ */
+export type PollReadOutcome<TData> = {
+    success: true;
+    data: TData;
+} | {
+    success: false;
+    error: unknown;
+    lastData: TData | null;
+};
+/**
+ * Whether a poll read's error is not worth retrying.
+ *
+ * @remarks
+ * `SDKValidationError` (also matches `ResponseValidationError`) means the response failed schema
+ * validation. A 401/403 means the session that started the poll expired mid-poll (SDK-1291) --
+ * neither recovers by retrying. Everything else (network blips, timeouts, transient 5xx) may
+ * still succeed on the next tick.
+ *
+ * @internal
+ */
+export declare function isNonRetryablePollError(error: unknown): boolean;
 /**
  * Configuration for {@link usePollingTask}.
  *
@@ -18,16 +57,18 @@ export type PollTickResult<TValue> = {
  * @internal
  */
 export interface UsePollingTaskOptions<TData, TValue> {
-    /** Reads the current server state for one tick. Rejections are tolerated and retried next tick. */
+    /** Reads the current server state for one tick. Rejections are passed to `evaluate`, not thrown. */
     fetch: (signal: AbortSignal) => Promise<TData>;
     /**
-     * Decides whether the operation has reached a terminal state, from the data this tick just
-     * read. Must not depend on rendered state — that dependency is the bug this hook exists to
-     * avoid.
+     * Decides whether the operation has reached a terminal state, from this tick's read outcome.
+     * Called on every tick, including ones where `fetch` rejected — see {@link PollReadOutcome} and
+     * {@link isNonRetryablePollError}.
      */
-    evaluate: (data: TData) => PollTickResult<TValue>;
-    /** Called once, from the poll loop, when `evaluate` reports a terminal state. */
+    evaluate: (outcome: PollReadOutcome<TData>) => PollTickResult<TValue>;
+    /** Called once, from the poll loop, when `evaluate` reports a `'done'` terminal state. */
     onDone: (value: TValue) => void;
+    /** Called once, from the poll loop, when `evaluate` reports an `'error'` terminal state. */
+    onError: (error: unknown) => void;
     /**
      * Called once when `deadlineMs` elapses without a terminal state, with the most recent data
      * successfully read (or `null` if no read ever succeeded). Verify against that data before
@@ -79,12 +120,12 @@ export interface PollingTask {
  *
  * - `start()` reads immediately, then every `intervalMs` after the previous read settles, so a
  *   slow read never stacks up overlapping requests.
- * - A rejected read is not a failed task. It is ignored and retried on the next tick, which
- *   matters because SDK queries are configured with `retry: false`. Note that when `fetch` reads
- *   through a shared query key, the failure is still recorded on that key, so observers of it
- *   see the error state even though the task carries on.
- * - A terminal result on the deadline tick wins over the deadline, and `onDeadline` receives the
- *   last data read so the caller can verify before declaring failure.
+ * - A rejected read isn't thrown; it's handed to `evaluate` as a {@link PollReadOutcome}, since
+ *   SDK queries are configured with `retry: false`. See {@link PollTickResult} for how `evaluate`
+ *   routes a read error to `'polling'` (retry) vs `'error'` (give up). When `fetch` reads through
+ *   a shared query key, observers of that key still see the error even though the task carries on.
+ * - A `'done'` or `'error'` result on the deadline tick wins over the deadline, and `onDeadline`
+ *   receives the last data read so the caller can verify before declaring failure.
  * - Each tick bumps internal state, which gives the calling component a render source
  *   independent of any query observer. Fresh cache data is then picked up on that render.
  * - `stop()` and unmount abort the in-flight read and guarantee no further callbacks fire.

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

@@ -6121,6 +6121,10 @@ export namespace Translations {
     statusLabel: string
     /** @defaultValue `"Last day"` */
     lastDayLabel: string
+    /** @defaultValue `"Pending dismissal"` */
+    pendingDismissalLabel: string
+    /** @defaultValue `"Last day {{date}}"` */
+    pendingDismissalBadge: string
     /** @defaultValue `"Edit employee"` */
     editCta: string
     /** @defaultValue `"Dismiss employee"` */
@@ -6977,6 +6981,8 @@ export namespace Translations {
     calculatingCta: string
     /** @defaultValue `"Apply"` */
     applyCta: string
+    /** @defaultValue `"Calculate a gross amount first to apply it."` */
+    applyHint: string
     /** @defaultValue `"Cancel"` */
     cancelCta: string
     /** @defaultValue `"Calculated gross pay"` */
@@ -7520,6 +7526,12 @@ export namespace Translations {
         /** @defaultValue `"{{employeeName}} updated successfully"` */
         label: string
       }
+      processingFailed: {
+        /** @defaultValue `"This payroll couldn't be calculated"` */
+        label: string
+        /** @defaultValue `"Please try calculating again."` */
+        message: string
+      }
     }
     /** @defaultValue `"Preparing payroll..."` */
     loadingTitle: string
@@ -7904,6 +7916,8 @@ export namespace Translations {
     alerts: {
       /** @defaultValue `"Payroll is not calculated"` */
       payrollNotCalculated: string
+      /** @defaultValue `"There was an issue loading this payroll. Please try again."` */
+      payrollLoadFailed: string
       /** @defaultValue `"To pay your employees with direct deposit by {{payDate}}, you'll need to run payroll by {{time}} on {{date}}."` */
       directDepositDeadline: string
       /** @defaultValue `"Make sure to submit before the deadline to ensure timely payments."` */