@tesouro/embedded-components-react 0.5.224 → 0.5.225

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +335 -413
  2. package/dist/libs/tesouro-embedded-components-react/shared/feature/dist/lib/analytics/build-info.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -13,7 +13,7 @@ npm install @tesouro/embedded-components-react
13
13
  # or: yarn add @tesouro/embedded-components-react
14
14
  ```
15
15
 
16
- **Import the stylesheet once** at your app's entry point — widgets render
16
+ **Import the stylesheet once** at your app's entry point. Widgets render
17
17
  unstyled without it:
18
18
 
19
19
  ```ts
@@ -42,70 +42,42 @@ export function App() {
42
42
  }
43
43
  ```
44
44
 
45
- Every provider and widget prop is fully typed in the shipped declarations, so
46
- your editor documents the full auth/config model inline — per-widget
47
- `WidgetProvider`, config inheritance, token refresh, and the built-in error
48
- boundary.
45
+ Every provider and widget prop is typed in the shipped declarations, so your
46
+ editor documents them inline.
49
47
 
50
48
  ### Entry points
51
49
 
52
- | Import path | What you get |
53
- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
54
- | `@tesouro/embedded-components-react` | All widgets, `WidgetSuite`, plus `RootWidgetProvider` / `WidgetProvider`. |
55
- | `@tesouro/embedded-components-react/styles.css` | The widget stylesheet — see [About the stylesheet](#about-the-stylesheet). |
56
- | `@tesouro/embedded-components-react/core` | Framework-agnostic token utilities (`createWidgetTokenManager`). |
57
- | `@tesouro/embedded-components-react/monite-sdk` | Legacy Monite surface, being removed — no compatibility promise. See [below](#monite-sdk-entry-point). |
58
- | `@tesouro/embedded-components-react/experimental` | Work in progress — no compatibility promise. See [below](#experimental-entry-point). |
50
+ | Import path | What you get |
51
+ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
52
+ | `@tesouro/embedded-components-react` | All widgets, `WidgetSuite`, plus `RootWidgetProvider` / `WidgetProvider`. |
53
+ | `@tesouro/embedded-components-react/styles.css` | The widget stylesheet. See [About the stylesheet](#about-the-stylesheet). |
54
+ | `@tesouro/embedded-components-react/core` | Framework-agnostic token utilities (`createWidgetTokenManager`). |
55
+ | `@tesouro/embedded-components-react/monite-sdk` | Legacy surface being removed, with no compatibility promise. See [below](#monite-sdk-entry-point). |
56
+ | `@tesouro/embedded-components-react/experimental` | Work in progress, with no compatibility promise. See [below](#experimental-entry-point). |
59
57
 
60
58
  ### Experimental entry point
61
59
 
62
- `@tesouro/embedded-components-react/experimental` (and the per-module
63
- `@tesouro/embedded-components-react/experimental/<Module>`) is a staging area for
64
- work in progress. It is **currently empty** — nothing ships on it today — and it
65
- is **outside this package's semver contract**:
66
-
67
- - Anything exported there can change shape or be **removed outright in any
68
- release, including a patch**. There is no deprecation window.
69
- - Its exports are deliberately not documented here — no prop tables, no
70
- reference entry. Read the shipped types.
71
- - It is unsupported. If you hit a problem with it, use the released widget on
72
- the main entry point instead.
73
-
74
- Use it only when we have pointed you at a specific module, and pin the package
75
- to an exact version if you do.
76
-
77
- The supported surface — the main entry point, `./core`, `./lib/*` and the
78
- stylesheet — carries the normal compatibility promise and is unaffected by churn
79
- on this path. `./monite-sdk` does not; see below.
60
+ `@tesouro/embedded-components-react/experimental` (and `.../experimental/<Module>`)
61
+ holds work in progress. It is **outside semver**: exports
62
+ can change or disappear in any release, including a patch, and aren't documented
63
+ here. Use it only if we point you at a specific module, and pin an exact version.
80
64
 
81
65
  ### Monite SDK entry point
82
66
 
83
- `@tesouro/embedded-components-react/monite-sdk` is a **legacy compatibility
84
- export, not an integration surface.** It exists because an earlier generation of
85
- Tesouro's own apps mounted Monite components directly. It was never meant for
86
- anyone else to build on, and it is **outside this package's compatibility
87
- promise**, on the same footing as `./experimental`:
88
-
89
- - Its exports are **being removed**, surface by surface, as each Monite-backed
90
- screen is replaced by a native Tesouro widget. Names disappear from it with no
91
- deprecation window.
92
- - It is deliberately undocumented here — no prop tables, no reference entries.
93
- - The subpath itself goes away once nothing needs it.
94
-
95
- Every Monite-backed widget on the main entry point already wraps Monite for you
96
- and exposes Tesouro props. That is the surface to build on. Reach for
97
- `./monite-sdk` only if we have pointed you at it, and pin an exact version if
98
- you do.
67
+ `@tesouro/embedded-components-react/monite-sdk` is a **legacy export being
68
+ removed** and is **outside the compatibility promise**, like `./experimental`.
69
+ Its exports disappear with no deprecation window as native widgets replace them.
70
+ Widgets on the main entry point that use it already wrap it for you, so build on
71
+ those. Use `./monite-sdk` only if we point you at it, and pin an exact
72
+ version.
99
73
 
100
74
  ### About the stylesheet
101
75
 
102
- The stylesheet is host-safe by design. It ships **no
103
- global CSS reset**: Tailwind's Preflight is omitted and instead re-expressed
104
- scoped under the `.tesouro-embedded` wrapper that every widget renders, and all
105
- utilities are `ttw`-prefixed — so loading it won't restyle your host page or
106
- collide with your own Tailwind. Design tokens (`--ttw-*`) are declared on
107
- `:root`/`.dark`; dark mode follows an ancestor `.dark` class, and the widget
108
- font can be white-labeled via `--ttw-font-family`.
76
+ The stylesheet won't restyle your host page. It ships no global CSS reset (the
77
+ reset is scoped under the `.tesouro-embedded` wrapper every widget renders), and
78
+ all utilities are `ttw`-prefixed, so it won't collide with your own Tailwind.
79
+ Design tokens (`--ttw-*`) are declared on `:root` / `.dark`. Dark mode follows an
80
+ ancestor `.dark` class, and you can set the widget font with `--ttw-font-family`.
109
81
 
110
82
  <!-- BEGIN GENERATED REFERENCE -->
111
83
 
@@ -127,21 +99,21 @@ App-level provider. Resolves `baseUrl` / `widgetToken` / `organizationId` (falli
127
99
 
128
100
  #### Props
129
101
 
130
- | Prop | Type | Description |
131
- | ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
132
- | `baseUrl` | `string` | Base URL of the Tesouro embedded API (e.g. `"https://api.tesouro.com"`). Falls back to `global.baseUrl` when omitted. |
133
- | `widgetToken` | `string \| null` | Bearer token for widget auth. Falls back to `global.widgetToken` when omitted. Pass `null` to suppress auth. |
134
- | `organizationId` | `string \| null` | Org ID forwarded to data-access hooks. Falls back to `global.organizationId` when omitted; if still unset, defaults to `initResponse.organizationId` once the fetch resolves. Pass `null` to clear org scoping (never falls back). |
135
- | `configClient` | `(client: EmbeddedClient) => EmbeddedClient` | Optional post-creation hook for the HTTP client. Called after the built-in auth and gateway-routing interceptors. Falls back to `global.configClient`. |
136
- | `gatewayRouting` | `boolean` | Overrides widget-gateway routing (the `/api/widget-gateway/proxy` path prefix plus the `X-Widget-Token` header). Unset, routing applies per request when the request origin is a known Tesouro API host; `true` forces it on (e.g. a custom domain in front of the gateway), `false` forces it off (a host that routes its own requests). Falls back to `global.gatewayRouting`. |
137
- | `linkComponent` | `LinkComponent` | Host link component widgets use to render navigational links. Falls back to `global.linkComponent`. |
138
- | `uiFramework` | `'shadcn' \| 'tecton' \| null` | UI framework the widget UI layer renders with for this tree. Falls back to `global.uiFramework`, then to `'shadcn'`. See UI framework selection. |
139
- | `implementation` | `'native' \| 'monite' \| null` | Which implementation the widgets render with for this tree. Falls back to `global.implementation`, then to `'native'`. See Implementation selection. |
140
- | `analytics` | `boolean` | Enables anonymous analytics for this provider tree (default `true`). `RootWidgetProvider` is the analytics owner; set `false` to disable capture and skip loading PostHog. |
141
- | `unstable_initResponseOverride` | `WidgetInitResponse` | First-party hosts only. Skips the `GET /api/widget-gateway/init` fetch and exposes this host-authored object as `initResponse` to the subtree. Use when the host authenticates users directly against the Tesouro issuer and passes the user's bearer access token as `widgetToken`. Embed integrations minting widget JWEs must leave this unset. |
142
- | `disclosuresAcceptance` | `ReactNode` | Accept surface shown when the caller owes disclosures (`INVITED`, or `REQUIRED` with `disclosuresAccepted: false`). Pass `<AcceptDisclosuresWidget />`. Cascades to nested providers. |
143
- | `providerLabels` | `Partial<WidgetProviderLabels>` | Overrides the copy a provider renders in place of a widget: the error-boundary fallback and the disclosures gate. Any subset; unlisted keys keep their defaults. Cascades to nested providers. See Provider copy. |
144
- | `children` | `ReactNode` | The React subtree that consumes the widget context. |
102
+ | Prop | Type | Description |
103
+ | ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
104
+ | `baseUrl` | `string` | Base URL of the Tesouro embedded API, such as `"https://api.tesouro.com"`. Falls back to `global.baseUrl`. |
105
+ | `widgetToken` | `string \| null` | Bearer token for widget auth. Falls back to `global.widgetToken`; `null` suppresses auth. |
106
+ | `organizationId` | `string \| null` | Org ID sent with data requests. Falls back to `global.organizationId`, then to `initResponse.organizationId`; `null` clears org scoping. |
107
+ | `configClient` | `(client: EmbeddedClient) => EmbeddedClient` | Post-creation hook for the HTTP client, applied after the built-in auth and routing interceptors. Falls back to `global.configClient`. |
108
+ | `gatewayRouting` | `boolean` | Forces widget-gateway routing on (`true`) or off (`false`); unset, it applies automatically to known Tesouro API hosts. Falls back to `global.gatewayRouting`. |
109
+ | `linkComponent` | `LinkComponent` | Host link component widgets use for navigational links. Falls back to `global.linkComponent`. |
110
+ | `uiFramework` | `'shadcn' \| 'tecton' \| null` | UI framework for this tree; falls back to `global.uiFramework`, then `'shadcn'`. |
111
+ | `implementation` | `'native' \| 'monite' \| null` | Widget implementation for this tree; falls back to `global.implementation`, then `'native'`. |
112
+ | `analytics` | `boolean` | Enables anonymous analytics (default `true`); `false` disables capture and skips loading PostHog. |
113
+ | `unstable_initResponseOverride` | `WidgetInitResponse` | First-party hosts only: skips the init fetch and uses this object as `initResponse`. Embed integrations minting widget JWEs must leave this unset. |
114
+ | `disclosuresAcceptance` | `ReactNode` | Accept surface shown when the user owes disclosures; pass `<AcceptDisclosuresWidget />`. Cascades to nested providers. |
115
+ | `providerLabels` | `Partial<WidgetProviderLabels>` | Overrides the copy a provider renders in place of a widget (error fallback, disclosures gate). Cascades to nested providers. |
116
+ | `children` | `ReactNode` | The React subtree that consumes the widget context. |
145
117
 
146
118
  ### `WidgetProvider`
147
119
 
@@ -149,22 +121,22 @@ Mid-tree or standalone provider. With no props it is a transparent pass-through
149
121
 
150
122
  #### Props
151
123
 
152
- | Prop | Type | Description |
153
- | ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
- | `baseUrl` | `string` | Override the base URL for this subtree. Recreates the HTTP client. When omitted, inherits from the nearest ancestor. |
155
- | `widgetToken` | `string \| null` | Override the widget token for this subtree. Triggers a new `/api/widget-gateway/init` fetch. Pass `null` to suppress auth at this level. When omitted, inherits from parent. |
156
- | `organizationId` | `string \| null` | Override the org ID for this subtree. Does **not** trigger a re-fetch on its own. When omitted, inherits from parent; if unset through the whole cascade, defaults to this level's `initResponse.organizationId` (an ancestor's explicit org wins over it). Pass `null` to explicitly clear org scoping (never falls back). |
157
- | `configClient` | `(client: EmbeddedClient) => EmbeddedClient` | Optional post-creation hook for the scoped HTTP client. Only called when this provider creates its own client (i.e. not in pass-through mode). When omitted, inherits from parent. |
158
- | `gatewayRouting` | `boolean` | Overrides widget-gateway routing (the `/api/widget-gateway/proxy` path prefix plus the `X-Widget-Token` header) for this subtree's scoped client. Unset, routing applies per request when the request origin is a known Tesouro API host; `true` forces it on, `false` forces it off. When omitted, inherits from parent. |
159
- | `linkComponent` | `LinkComponent` | Override the host link component for this subtree. When omitted, inherits from parent. |
160
- | `uiFramework` | `'shadcn' \| 'tecton' \| null` | Override the UI framework for this subtree. When omitted (or `null`), inherits the nearest ancestor's selection, defaulting to `'shadcn'`. See UI framework selection. |
161
- | `implementation` | `'native' \| 'monite' \| null` | Override the implementation for this subtree. When omitted (or `null`), inherits the nearest ancestor's selection, defaulting to `'native'`. See Implementation selection. |
162
- | `errorFallback` | `ReactNode \| (props: FallbackProps) => ReactNode` | Custom fallback for the built-in error boundary in this subtree. A `ReactNode` is rendered as-is; a function receives `{ error, resetErrorBoundary }`. Defaults to a generic `role="alert"` message. |
163
- | `onError` | `(error: unknown, info: ErrorInfo) => void` | Optional telemetry hook. Runs once per caught error before the fallback renders. |
164
- | `analytics` | `boolean` | Enables anonymous analytics (default `true`). Honored only when this is a standalone analytics owner (no `RootWidgetProvider` ancestor); on a nested provider it is a no-op. |
165
- | `disclosuresAcceptance` | `ReactNode` | Accept surface shown when the caller owes disclosures (`INVITED`, or `REQUIRED` with `disclosuresAccepted: false`). Pass `<AcceptDisclosuresWidget />`. When omitted, inherits from the nearest ancestor. |
166
- | `providerLabels` | `Partial<WidgetProviderLabels>` | Overrides the copy this provider renders in place of the widget: the error-boundary fallback and the disclosures gate. Any subset; unlisted keys keep their defaults. When omitted, inherits from the nearest ancestor. See Provider copy. |
167
- | `children` | `ReactNode` | The React subtree that consumes the overridden context. |
124
+ | Prop | Type | Description |
125
+ | ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | `baseUrl` | `string` | Overrides the base URL for this subtree and creates a new client. Inherits when omitted. |
127
+ | `widgetToken` | `string \| null` | Overrides the token for this subtree and reloads init; `null` suppresses auth here. Inherits when omitted. |
128
+ | `organizationId` | `string \| null` | Overrides the org ID for this subtree without reloading init; `null` clears org scoping. Inherits when omitted. |
129
+ | `configClient` | `(client: EmbeddedClient) => EmbeddedClient` | Post-creation hook for this provider's client; not called in pass-through mode. Inherits when omitted. |
130
+ | `gatewayRouting` | `boolean` | Forces widget-gateway routing on or off for this subtree's client; unset, it applies to known Tesouro API hosts. Inherits when omitted. |
131
+ | `linkComponent` | `LinkComponent` | Overrides the host link component for this subtree. Inherits when omitted. |
132
+ | `uiFramework` | `'shadcn' \| 'tecton' \| null` | Overrides the UI framework for this subtree; omitted or `null` inherits, defaulting to `'shadcn'`. |
133
+ | `implementation` | `'native' \| 'monite' \| null` | Overrides the implementation for this subtree; omitted or `null` inherits, defaulting to `'native'`. |
134
+ | `errorFallback` | `ReactNode \| (props: FallbackProps) => ReactNode` | Custom error-boundary fallback: a node, or a function receiving `{ error, resetErrorBoundary }`. |
135
+ | `onError` | `(error: unknown, info: ErrorInfo) => void` | Telemetry hook, called once per caught error before the fallback renders. |
136
+ | `analytics` | `boolean` | Enables anonymous analytics (default `true`); honored only in standalone mode, ignored on a nested provider. |
137
+ | `disclosuresAcceptance` | `ReactNode` | Accept surface shown when the user owes disclosures; pass `<AcceptDisclosuresWidget />`. Inherits when omitted. |
138
+ | `providerLabels` | `Partial<WidgetProviderLabels>` | Overrides the copy this provider renders in place of the widget. Inherits when omitted. |
139
+ | `children` | `ReactNode` | The React subtree that consumes the overridden context. |
168
140
 
169
141
  ### `WidgetTokenRefreshProvider`
170
142
 
@@ -172,12 +144,12 @@ Owns the token-refresh lifecycle: calls your `fetcher`, proactively refreshes be
172
144
 
173
145
  #### Props
174
146
 
175
- | Prop | Type | Default | Description |
176
- | ------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
177
- | `fetcher` | `() => Promise<{ widgetToken: string; exp?: number }>` | — | Required. Called on mount and whenever a refresh is scheduled or requested. `exp` is unix seconds; if omitted, no proactive refresh is scheduled. |
178
- | `leadSeconds` | `number` | `60` | Schedule the next refresh `leadSeconds` before `exp`. Lower this if your tokens have a very short lifetime. |
179
- | `onToken` | `(widgetToken: string) => void` | — | Optional callback fired once per **distinct** token produced by the manager. Useful for telemetry, persistence, or — for non-React hosts (web components, cross-React-root setups) — mirroring the token into the global store via `updateGlobalWidgetConfig`. React consumers should drive `widgetToken` from `useWidgetToken()` instead. |
180
- | `children` | `ReactNode` | — | The React subtree that consumes the manager via `useWidgetToken()`. |
147
+ | Prop | Type | Default | Description |
148
+ | ------------- | ------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
149
+ | `fetcher` | `() => Promise<{ widgetToken: string; exp?: number }>` | **Required** | Returns a token and its `exp` (unix seconds); see The fetcher. |
150
+ | `leadSeconds` | `number` | `60` | Refresh this many seconds before `exp`. Lower it for very short-lived tokens. |
151
+ | `onToken` | `(widgetToken: string) => void` | `undefined` | Called once per distinct token, for telemetry, persistence, or mirroring the token into the global store for non-React hosts. |
152
+ | `children` | `ReactNode` | `undefined` | The subtree that reads the token via `useWidgetToken()`. |
181
153
 
182
154
  ### `RefreshingRootWidgetProvider`
183
155
 
@@ -185,23 +157,23 @@ Bundles `WidgetTokenRefreshProvider` + `RootWidgetProvider` and wires the live t
185
157
 
186
158
  #### Props
187
159
 
188
- | Prop | Source | Notes |
189
- | ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
190
- | `baseUrl` | `RootWidgetProvider` | Falls back to the global store when omitted. |
191
- | `organizationId` | `RootWidgetProvider` | Pass `null` to clear the org scope; falls back to the global store when omitted. |
192
- | `configClient` | `RootWidgetProvider` | Optional post-creation hook for the scoped HTTP client. |
193
- | `gatewayRouting` | `RootWidgetProvider` | Overrides widget-gateway routing; unset, it applies per request when the request origin is a known Tesouro API host. |
194
- | `linkComponent` | `RootWidgetProvider` | Component used in place of plain `<a>` tags inside widgets. |
195
- | `uiFramework` | `RootWidgetProvider` | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade. |
196
- | `implementation` | `RootWidgetProvider` | `'native'` (default) or `'monite'`; inherits down the provider cascade. |
197
- | `analytics` | `RootWidgetProvider` | Enables anonymous analytics (default `true`); set `false` to disable capture. |
198
- | `unstable_initResponseOverride` | `RootWidgetProvider` | First-party hosts only. Skips the gateway init fetch and supplies host-authored identity for the subtree. |
199
- | `disclosuresAcceptance` | `RootWidgetProvider` | Accept surface shown when the caller owes disclosures (`INVITED`, or `REQUIRED` with `disclosuresAccepted: false`). Cascades to nested providers. |
200
- | `providerLabels` | `RootWidgetProvider` | Overrides the copy a provider renders in place of a widget (error-boundary fallback, disclosures gate). Any subset. Cascades to nested providers. |
201
- | `fetcher` | `WidgetTokenRefreshProvider` | Required. |
202
- | `leadSeconds` | `WidgetTokenRefreshProvider` | Default `60`. |
203
- | `onToken` | `WidgetTokenRefreshProvider` | Fires once per distinct token; useful for telemetry, persistence, or — for non-React hosts — mirroring the token via `updateGlobalWidgetConfig`. |
204
- | `children` | — | Render inside both providers' contexts (so `useWidgetToken()` and `useWidgetConfig()` both work in descendants). |
160
+ | Prop | Source | Notes |
161
+ | ------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
162
+ | `baseUrl` | `RootWidgetProvider` | Falls back to the global store when omitted. |
163
+ | `organizationId` | `RootWidgetProvider` | Pass `null` to clear the org scope; falls back to the global store when omitted. |
164
+ | `configClient` | `RootWidgetProvider` | Optional post-creation hook for the scoped HTTP client. |
165
+ | `gatewayRouting` | `RootWidgetProvider` | Overrides widget-gateway routing; unset, it applies automatically for known Tesouro API hosts. |
166
+ | `linkComponent` | `RootWidgetProvider` | Component used in place of plain `<a>` tags inside widgets. |
167
+ | `uiFramework` | `RootWidgetProvider` | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade. |
168
+ | `implementation` | `RootWidgetProvider` | `'native'` (default) or `'monite'`; inherits down the provider cascade. |
169
+ | `analytics` | `RootWidgetProvider` | Enables anonymous analytics (default `true`); set `false` to disable capture. |
170
+ | `unstable_initResponseOverride` | `RootWidgetProvider` | First-party hosts only. Skips the init fetch and supplies host-authored identity for the subtree. |
171
+ | `disclosuresAcceptance` | `RootWidgetProvider` | Accept surface shown when the user owes disclosures. Cascades to nested providers. |
172
+ | `providerLabels` | `RootWidgetProvider` | Overrides the copy a provider renders in place of a widget (error fallback, disclosures gate). Cascades. |
173
+ | `fetcher` | `WidgetTokenRefreshProvider` | Required. |
174
+ | `leadSeconds` | `WidgetTokenRefreshProvider` | Default `60`. |
175
+ | `onToken` | `WidgetTokenRefreshProvider` | Fires once per distinct token. |
176
+ | `children` | Both | Rendered inside both providers. |
205
177
 
206
178
  ## Components
207
179
 
@@ -212,43 +184,35 @@ listed here.
212
184
 
213
185
  ### WidgetSuite
214
186
 
215
- A whole banking page in one component: a section menu over the widgets behind it, served by a single widget-init call. Unlike a widget — a content area you drop onto a page you own — a suite owns the page it is placed on, exists once per page, and decides which widgets appear on it.
187
+ A whole banking page in one component: a section menu over the widgets behind it, served by a single widget-init call. Unlike a widget, a suite owns the page it is placed on, so mount one per page.
216
188
 
217
189
  #### Props
218
190
 
219
- | Prop | Type | Default | Description |
220
- | --------------------------- | --------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
221
- | `sections` | `readonly WidgetSuiteSectionId[]` | `WIDGET_SUITE_DEFAULT_SECTIONS` | Which sections the suite offers, in menu order. A listed section is still hidden when the token does not earn it. |
222
- | `section` | `WidgetSuiteSectionId` | — | Which section is showing. Supplying it puts the menu in controlled mode for the lifetime of the mount, so pair it with `onSectionChange`. |
223
- | `defaultSection` | `WidgetSuiteSectionId` | first of `sections` | Which section the suite opens on. Read once per mount, and ignored when `section` is supplied. |
224
- | `onSectionChange` | `(section) => void` | `undefined` | Called when a person moves the suite. Never fired on mount, and never for the entitlement fallback, so a URL mirroring it cannot erase a deep link. |
225
- | `labels` | `WidgetSuiteLabelOverrides` | `WIDGET_SUITE_LABELS_EN` | Every string on the page, in one tree: a group for the shell, the menu names, the section heading, the disclosure states, and one per section carrying that section's widget copy. Override any leaf and its siblings keep their defaults. |
226
- | `showSectionTitle` | `boolean` | `true` | Shows a heading above each section, named as its menu item is. Set `false` when your page already heads the suite. |
227
- | `onboardingDisclosureLinks` | `DisclosureLinks` | `undefined` | Legal disclosure URLs (Terms, Privacy, Electronic Communication, Patriot Act) for the entry-point onboarding widget's business-details agreement step, shown to a session whose organization has no application yet. Omitted fields render as plain, non-clickable text. |
228
- | `cardArtSrc` | `string` | `undefined` | Card artwork URL for the debit list's built-in Create card sheet and details card face. Omit it and the sheet uses a built-in neutral plastic while the face falls back to the bank logo. Create card shows when the token holds the issue, roster and funding scopes. Credit Create card is always hidden in the suite. |
191
+ | Prop | Type | Default | Description |
192
+ | --------------------------- | --------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
193
+ | `sections` | `readonly WidgetSuiteSectionId[]` | `WIDGET_SUITE_DEFAULT_SECTIONS` | Which sections the suite offers, in menu order. A listed section is still hidden when the token doesn't earn it. |
194
+ | `section` | `WidgetSuiteSectionId` | `undefined` | Which section is showing. Supplying it makes the menu controlled for the lifetime of the mount, so pair it with `onSectionChange`. |
195
+ | `defaultSection` | `WidgetSuiteSectionId` | first of `sections` | Which section the suite opens on. Read once per mount, and ignored when `section` is supplied. |
196
+ | `onSectionChange` | `(section) => void` | `undefined` | Called when the user moves the suite. Never fired on mount or for the entitlement fallback. |
197
+ | `labels` | `WidgetSuiteLabelOverrides` | `WIDGET_SUITE_LABELS_EN` | Every string on the page in one tree, including the copy of each section's widget. Override any leaf and its siblings keep their defaults. |
198
+ | `showSectionTitle` | `boolean` | `true` | Shows a heading above each section, named as its menu item is. Set `false` when your page already heads the suite. |
199
+ | `onboardingDisclosureLinks` | `DisclosureLinks` | `undefined` | Legal disclosure URLs for the onboarding agreement step, shown when the organization has no application yet. Omitted fields render as non-clickable text. |
200
+ | `cardArtSrc` | `string` | `undefined` | Card artwork URL for the debit Create card sheet and card face; omitted, a neutral plastic and the bank logo are used. Credit Create card is always hidden. |
229
201
 
230
202
  ### AcceptDisclosuresWidget
231
203
 
232
- A self-contained widget for reviewing and accepting required banking disclosures. Fetches the caller's disclosure document set (title/url pairs, in presentation order) from `GET /identity/v1/disclosures` and renders an inline bordered card with those links, an agreement checkbox, and an Accept action. The host supplies no document URLs — the document set, its titles, and its order are entirely backend configuration for the bank partner's program. The provider attribution and agreement copy come from the widget init tenant identity.
233
-
234
- The widget token identifies the caller on both the disclosures lookup and the accept. Mount this when widget init reports `status: 'INVITED'`, **or** `disclosuresRequired: 'REQUIRED'` with `disclosuresAccepted: false`. The first covers an invited teammate who is not yet active — including orgs whose requirement is `NOT_REQUIRED`, where Accept still posts a `null` version to activate them. The second covers an already-active user who owes a newly published version. Do not gate on `REQUIRED` alone: that would skip `INVITED` users in `NOT_REQUIRED` orgs and leave them stuck.
235
-
236
- Accept posts `POST /api/widget-gateway/disclosure-acceptance` with the version that was on screen, after a second `GET /identity/v1/disclosures` confirms that version is still in force (hosts rewrite that onto `/api/widget-gateway/proxy/identity/v1/disclosures` the same way as other identity calls — do not call the generated catch-all proxy helper, which percent-encodes path slashes and surfaces as a browser CORS error). If a newer version was published while the caller was reading, accept is refused (no POST) and the widget refetches so they can review the documents that are now in force. `version` may be `null` when the org's requirement is `NOT_REQUIRED`; that value is posted through and ignored by the gateway so invitees in those orgs can still activate. The accept is one transaction: it activates the invitee (when they are still invited) and records disclosure acceptance together, so a failed second hop cannot leave an `ACTIVE` user with no acceptance on record. After accept succeeds, the widget awaits any async `onAccepted` continuation, then kicks a widget-init refresh so host gates keyed on `INVITED` — or on the disclosure flags — can clear. Accept and `onAccepted` failures are handled separately — a rejected host continuation does not look like (or re-run) a failed gateway accept. The refresh is fire-and-forget and runs only after `onAccepted` settles — hosts that unmount this widget when status leaves `INVITED` would otherwise hide a rejected continuation. Auth uses the normal `widgetToken` provider contract — **never** pass an application (APP) / M2M bearer as `widgetToken`. This widget does not take invite-link credentials and does not read URL search params.
237
-
238
- A failed disclosures fetch renders an error surface with retry instead of a blank INVITED screen. The widget otherwise renders nothing until the disclosures fetch resolves **and** init resolves a `bankName` — it never substitutes another tenant's legal copy, and never falls back to a Tesouro-hosted document (a published embeddable library must not depend on infrastructure a consumer's content-security policy cannot see). An empty document list (`requirement: NOT_REQUIRED`, `version: null`) is a resolved payload, not missing data: the widget still renders Accept so those invitees can activate. Agreement copy names the returned document titles, in backend order, so the sentence cannot list instruments the links do not show. If init omits `vspName`, provider attribution falls back to the bank name so the sentence remains complete.
239
-
240
- Once the atomic accept _and_ any async `onAccepted` continuation succeed, the checkbox and Accept control stay disabled, so a legal acceptance is never posted twice even if the host does not navigate away. A failed accept or rejected `onAccepted` shows an inline error and leaves the control usable for a retry; a successful accept is skipped on retry after a later failure. Init refresh is kicked only after `onAccepted` succeeds.
204
+ Shows the bank partner's required disclosure documents with an agreement checkbox and an Accept button. The document set, titles and order come from your program's backend configuration, so you pass no URLs.
241
205
 
242
206
  #### Props
243
207
 
244
- | Prop | Type | Default | Description |
245
- | ------------ | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
246
- | `labels` | `Partial<AcceptDisclosuresWidgetLabels>` | — | Override shell copy (title, Accept, agreement/attribution templates). `{documents}` in `agreementTextTemplate` is replaced with the backend-returned titles; a template that omits `{documents}` still has those titles appended. When the backend returns no documents, `noDocumentsTitle` / `noDocumentsAgreementTextTemplate` / `noDocumentsAgreementCheckboxAriaLabel` replace the disclosures copy (including the checkbox `aria-label`). Document titles themselves are not overridable. |
247
- | `onAccepted` | `() => void \| Promise<void>` | — | Called after the atomic accept succeeds and before init refresh; awaited before the widget locks. Reject to surface an error and keep Accept retryable. |
208
+ | Prop | Type | Default | Description |
209
+ | ------------ | ---------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
210
+ | `labels` | `Partial<AcceptDisclosuresWidgetLabels>` | English labels | Override widget copy. `{documents}` in `agreementTextTemplate` is replaced with the document titles. The `noDocuments*` labels apply when there are no documents. Document titles aren't overridable. |
211
+ | `onAccepted` | `() => void \| Promise<void>` | `undefined` | Called after the atomic accept succeeds and before init refresh; awaited before the widget locks. Reject to surface an error and keep Accept retryable. |
248
212
 
249
213
  ### BankAccountsWidget
250
214
 
251
- A self-contained banking widget for listing Tesouro bank accounts, creating an account with team access, and viewing account details.
215
+ Lists the organization's Tesouro bank accounts, lets the user open an account with team access, and shows each account's details.
252
216
 
253
217
  #### Props
254
218
 
@@ -257,7 +221,7 @@ A self-contained banking widget for listing Tesouro bank accounts, creating an a
257
221
  | `isBankingTaglineVisible` | `boolean` | `true` | Shows the banking tagline at the top of the widget. The page heading above it belongs to your page. |
258
222
  | `bankLogoSrc` | `string` | `undefined` | Bank logo for the tagline row. Omit and the row shows the bank name alone. |
259
223
  | `bankLogoAlt` | `string` | `undefined` | Alt text when `bankLogoSrc` is set. |
260
- | `depositAgreementUrl` | `string` | `undefined` | Deposit-agreement PDF linked from the create-account legal copy. Omit and the clause naming it is not rendered. |
224
+ | `depositAgreementUrl` | `string` | `undefined` | Deposit-agreement PDF linked from the create-account legal copy. Omit and the clause naming it isn't rendered. |
261
225
  | `bankAddress` | `string` | `undefined` | Bank postal address shown in the account-details domestic wire panel. |
262
226
  | `supportTeamUrl` | `string` | `undefined` | Support URL linked from the account-details domestic wire copy. |
263
227
  | `labels` | `Partial<BankAccountsWidgetLabels>` | English labels | Overrides list/create-account UI copy. |
@@ -270,371 +234,345 @@ A self-contained banking widget for listing Tesouro bank accounts, creating an a
270
234
 
271
235
  ### BillPayWidget
272
236
 
273
- A Monite-backed bill pay widget wrapped in Tesouro widget auth and theming.
237
+ A bill pay widget with Tesouro widget auth and theming. It renders the `'monite'` implementation unless you set `implementation="native"`.
274
238
 
275
239
  #### Props
276
240
 
277
- | Prop | Type | Default | Description |
278
- | -------------------- | ------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
279
- | `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Pass-through | Customizes Monite's page title action region. |
280
- | `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Optional Monite theme color overrides. |
281
- | `initialTab` | `'bills' \| 'vendors'` | `'bills'` | Tab to open on initial mount. Native implementation only (`implementation="native"`); has no effect under the default Monite implementation. |
282
- | `poweredByBankName` | `string` | `undefined` | Bank shown as "Powered by {bank}" next to the source account when paying a bill. Native implementation only (`implementation="native"`); has no effect under the default Monite implementation. |
283
- | `onSettingsClick` | `() => void` | `undefined` | Opens your bill pay settings surface from a cog beside the bill list's "Add bill" button. The cog renders only when this is supplied and the user's scopes reach that surface. Native implementation only; under Monite, build a settings button into `pageTitleComponent` instead. |
241
+ | Prop | Type | Default | Description |
242
+ | -------------------- | ------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
243
+ | `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Pass-through | Customizes the page title action region. |
244
+ | `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Optional theme color overrides for the `'monite'` implementation. |
245
+ | `initialTab` | `'bills' \| 'vendors'` | `'bills'` | Tab to open on initial mount. Native implementation only (`implementation="native"`); has no effect under the default `'monite'` implementation. |
246
+ | `poweredByBankName` | `string` | `undefined` | Bank shown as "Powered by {bank}" next to the source account when paying a bill. Native implementation only (`implementation="native"`); has no effect under the default `'monite'` implementation. |
247
+ | `onSettingsClick` | `() => void` | `undefined` | Opens your bill pay settings surface from a cog beside the bill list's "Add bill" button. The cog renders only when this is supplied and the user's scopes reach that surface. Native implementation only; under `'monite'`, build a settings button into `pageTitleComponent` instead. |
284
248
 
285
249
  ### CreditCardsWidget
286
250
 
287
- One page of an organization's **credit** cards, with a scope-gated "Show my cards" toggle and a per-row Activate affordance. Selecting a row opens that card's read-only details in a side sheet. Create card is host-owned: supply `onCreateCard` or the button is not rendered.
251
+ Lists an organization's **credit** cards one page at a time, with a "Show my cards" toggle and per-row Activate. Selecting a row opens the card's details in a side sheet. There is no built-in credit issuance flow, so Create card appears only when you supply `onCreateCard`.
288
252
 
289
253
  #### Props
290
254
 
291
- | Prop | Type | Default | Description |
292
- | --------------------------- | --------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
293
- | `pagination` | `{ paginationToken?, pageSize? }` | `undefined` | Controlled cursor and page size. Supply with `onPaginationChange` when your app owns the list position. |
294
- | `defaultPagination` | `{ paginationToken?, pageSize? }` | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied. |
295
- | `onPaginationChange` | `(pagination: CardsPagination) => void` | `undefined` | Called whenever the widget moves page or changes page size. Persist the whole object, not the token alone. |
296
- | `labels` | `PartialDeep<CardsLabels>` | English labels | Overrides the copy of the list screen — its controls, columns, states, and the details sheet's screen-reader name under `detailsSheet`. Nested groups merge per group. |
297
- | `featureLabels` | `PartialDeep<CardsFeatureLabels>` | English labels | Overrides the copy this widget resolves rather than passes through — status and form-factor vocabulary, the empty-cell placeholder, and name fallbacks. |
298
- | `selectedCardId` | `string \| null` | `undefined` | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. See **Selection** below. |
299
- | `defaultSelectedCardId` | `string \| null` | `undefined` | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied. |
300
- | `onSelectedCardIdChange` | `(cardId: string \| null) => void` | `undefined` | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders. |
301
- | `cardDetailsLabels` | `PartialDeep<CardDetailsWidgetLabels>` | English labels | Label overrides forwarded into the details panel. |
302
- | `cardDetailsFeatureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides for the copy the panel's feature layer resolves — status vocabulary, form-factor copy, program label, copy-success toast. Distinct from `featureLabels`. |
303
- | `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>` | English labels | Overrides for the Activate Card form the details panel opens — its heading, the two field labels, and its validation and status copy. |
304
- | `bankLogoSrc` | `string` | `undefined` | Bank logo for the details panel's card face. Omit and the face renders without a logo rather than with a placeholder. |
305
- | `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. |
306
- | `onCreateCard` | `() => void` | `undefined` | Host-owned Create card handler. Required for the button to render at all. See **Create card** below. |
307
- | `headerStart` | `ReactNode` | `undefined` | Your own markup for the start of the header row, beside Create card. Pass your heading here so the two share one row; the widget renders no heading of its own, so you choose the element and level. |
308
- | `onActivateCard` | `(cardId: string) => void` | `undefined` | Called when a row's Activate button is clicked. Omit it and the button is not rendered. |
255
+ | Prop | Type | Default | Description |
256
+ | --------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
257
+ | `pagination` | `{ paginationToken?, pageSize? }` | `undefined` | Controlled cursor and page size. Supply with `onPaginationChange`. |
258
+ | `defaultPagination` | `{ paginationToken?, pageSize? }` | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied. |
259
+ | `onPaginationChange` | `(pagination: CardsPagination) => void` | `undefined` | Called on every page or page-size change. Persist the whole object, not the token alone. |
260
+ | `labels` | `PartialDeep<CardsLabels>` | English labels | Overrides the list screen's copy, including the details sheet's screen-reader name under `detailsSheet`. |
261
+ | `featureLabels` | `PartialDeep<CardsFeatureLabels>` | English labels | Overrides status and form-factor vocabulary, the empty-cell placeholder and name fallbacks. |
262
+ | `selectedCardId` | `string \| null` | `undefined` | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. |
263
+ | `defaultSelectedCardId` | `string \| null` | `undefined` | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied. |
264
+ | `onSelectedCardIdChange` | `(cardId: string \| null) => void` | `undefined` | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders. |
265
+ | `cardDetailsLabels` | `PartialDeep<CardDetailsWidgetLabels>` | English labels | Label overrides forwarded into the details panel. |
266
+ | `cardDetailsFeatureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides the details panel's status, form-factor and program copy and its copy-success toast. |
267
+ | `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>` | English labels | Overrides the copy of the Activate Card form the details panel opens. |
268
+ | `bankLogoSrc` | `string` | `undefined` | Bank logo for the details panel's card face. Omit it and the face renders no logo. |
269
+ | `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. |
270
+ | `onCreateCard` | `() => void` | `undefined` | Your own Create card handler. Required for the button to render. |
271
+ | `headerStart` | `ReactNode` | `undefined` | Your markup for the start of the header row, beside Create card. Put your heading here; you choose the element and level. |
272
+ | `onActivateCard` | `(cardId: string) => void` | `undefined` | Called when a row's Activate button is clicked. Omit it and the button isn't rendered. |
309
273
 
310
274
  ### DebitCardsWidget
311
275
 
312
- One page of an organization's **debit** cards, with a scope-gated "Show my cards" toggle, Create card and per-row Activate affordances. Selecting a row opens that card's read-only details in a side sheet. Create card opens the same sheet with the built-in debit issuance flow.
276
+ Lists an organization's **debit** cards one page at a time, with a "Show my cards" toggle, Create card and per-row Activate. Selecting a row opens the card's details in a side sheet, and Create card opens the built-in debit issuance flow in the same sheet.
313
277
 
314
278
  #### Props
315
279
 
316
- | Prop | Type | Default | Description |
317
- | --------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
318
- | `pagination` | `{ paginationToken?, pageSize? }` | `undefined` | Controlled cursor and page size. Supply with `onPaginationChange` when your app owns the list position. |
319
- | `defaultPagination` | `{ paginationToken?, pageSize? }` | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied. |
320
- | `onPaginationChange` | `(pagination: CardsPagination) => void` | `undefined` | Called whenever the widget moves page or changes page size. Persist the whole object, not the token alone. |
321
- | `labels` | `PartialDeep<CardsLabels>` | English labels | Overrides the copy of the list screen — its controls, columns, states, the details sheet's screen-reader name under `detailsSheet` and the create sheet's under `createSheet`. Nested groups merge per group. |
322
- | `featureLabels` | `PartialDeep<CardsFeatureLabels>` | English labels | Overrides the copy this widget resolves rather than passes through — status and form-factor vocabulary, the empty-cell placeholder, and name fallbacks. |
323
- | `selectedCardId` | `string \| null` | `undefined` | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. See **Selection** below. |
324
- | `defaultSelectedCardId` | `string \| null` | `undefined` | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied. |
325
- | `onSelectedCardIdChange` | `(cardId: string \| null) => void` | `undefined` | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders. |
326
- | `cardDetailsLabels` | `PartialDeep<CardDetailsWidgetLabels>` | English labels | Label overrides forwarded into the details panel. |
327
- | `cardDetailsFeatureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides for the copy the panel's feature layer resolves — status vocabulary, form-factor copy, program label, copy-success toast. Distinct from `featureLabels`. |
328
- | `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>` | English labels | Overrides for the Activate Card form the details panel opens — its heading, the two field labels, and its validation and status copy. |
329
- | `bankLogoSrc` | `string` | `undefined` | Bank logo for the details panel's card face. Ignored there when `cardArtSrc` is set. Omit both and the face renders without a logo rather than with a placeholder. |
330
- | `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. |
331
- | `cardArtSrc` | `string` | `undefined` | Plastic art for the built-in create sheet **and** the details panel's card face. Omit it and the create sheet draws a built-in neutral plastic, while the details face falls back to `bankLogoSrc`. See **Create card** below. |
332
- | `createCardLabels` | `PartialDeep<CreateCardWidgetLabels>` | English labels | Label overrides forwarded into the nested create-card panel. |
333
- | `createCardFeatureLabels` | toast / untitled-funding overrides | English labels | Overrides for the copy the create panel's feature layer resolves — mutation toasts, untitled funding-account fallback, pending-activation success copy. |
334
- | `onCreateCard` | `() => void` | `undefined` | Host-owned Create card handler. When supplied, the built-in sheet does not open — use it for a custom issuance flow. |
335
- | `headerStart` | `ReactNode` | `undefined` | Your own markup for the start of the header row, beside Create card. Pass your heading here so the two share one row; the widget renders no heading of its own, so you choose the element and level. |
336
- | `onActivateCard` | `(cardId: string) => void` | `undefined` | Called when a row's Activate button is clicked. Omit it and the button is not rendered. |
280
+ | Prop | Type | Default | Description |
281
+ | --------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
282
+ | `pagination` | `{ paginationToken?, pageSize? }` | `undefined` | Controlled cursor and page size. Supply with `onPaginationChange`. |
283
+ | `defaultPagination` | `{ paginationToken?, pageSize? }` | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied. |
284
+ | `onPaginationChange` | `(pagination: CardsPagination) => void` | `undefined` | Called on every page or page-size change. Persist the whole object, not the token alone. |
285
+ | `labels` | `PartialDeep<CardsLabels>` | English labels | Overrides the list screen's copy, including the sheets' screen-reader names under `detailsSheet` and `createSheet`. |
286
+ | `featureLabels` | `PartialDeep<CardsFeatureLabels>` | English labels | Overrides status and form-factor vocabulary, the empty-cell placeholder and name fallbacks. |
287
+ | `selectedCardId` | `string \| null` | `undefined` | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. |
288
+ | `defaultSelectedCardId` | `string \| null` | `undefined` | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied. |
289
+ | `onSelectedCardIdChange` | `(cardId: string \| null) => void` | `undefined` | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders. |
290
+ | `cardDetailsLabels` | `PartialDeep<CardDetailsWidgetLabels>` | English labels | Label overrides forwarded into the details panel. |
291
+ | `cardDetailsFeatureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides the details panel's status, form-factor and program copy and its copy-success toast. |
292
+ | `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>` | English labels | Overrides the copy of the Activate Card form the details panel opens. |
293
+ | `bankLogoSrc` | `string` | `undefined` | Bank logo for the details panel's card face, ignored when `cardArtSrc` is set. Omit both and the face renders no logo. |
294
+ | `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. |
295
+ | `cardArtSrc` | `string` | `undefined` | Card art for the create sheet and the details card face. Omitted, the sheet uses a neutral plastic. |
296
+ | `createCardLabels` | `PartialDeep<CreateCardWidgetLabels>` | English labels | Label overrides forwarded into the built-in create sheet. |
297
+ | `createCardFeatureLabels` | toast / untitled-funding overrides | English labels | Overrides the create sheet's toasts, untitled funding-account fallback and pending-activation success copy. |
298
+ | `onCreateCard` | `() => void` | `undefined` | Your own Create card handler. When supplied, the built-in sheet doesn't open. |
299
+ | `headerStart` | `ReactNode` | `undefined` | Your markup for the start of the header row, beside Create card. Put your heading here; you choose the element and level. |
300
+ | `onActivateCard` | `(cardId: string) => void` | `undefined` | Called when a row's Activate button is clicked. Omit it and the button isn't rendered. |
337
301
 
338
302
  ### CardDetailsWidget
339
303
 
340
- Details for one credit **or** debit card — status, form factor, program, masked card number, and copyable cardholder, nickname and billing-address rows. A debit card can also reveal its number, expiry and security code on demand, lock and unlock itself, and be renamed in place. It renders panel content rather than its own drawer, so it sits on a page of your own as readily as inside chrome you already have.
304
+ Details for one credit or debit card: status, form factor, program, masked number, and copyable cardholder, nickname and billing-address rows. It renders panel content rather than its own drawer, so it fits on a page of your own or inside chrome you already have.
341
305
 
342
306
  #### Props
343
307
 
344
- | Prop | Type | Default | Description |
345
- | ---------------- | --------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
346
- | `cardId` | `string` | **Required** | Id of the card to show. |
347
- | `cardProgram` | `'credit' \| 'debit'` | **Required** | Which issuing program `cardId` belongs to. Selects the endpoint the card is fetched from. |
348
- | `onClose` | `() => void` | `undefined` | Called when the reader is finished with the widget: the details panel's close control, and **Done** on the activation success screen. Omit it and neither is rendered. The activation form keeps its own close either way, which returns to the details. |
349
- | `labels` | `PartialDeep<CardDetailsWidgetLabels>` | English labels | Overrides the panel's own copy — header, card face alt text, row headings, copy-button accessible names, the nickname editor, the lock control and its locked notice, and the loading/error/not-found screens. |
350
- | `activateLabels` | `PartialDeep<ActivateCardPanelLabels>` | English labels | Overrides the Activate Card form's copy — its heading, the two field labels, the security-code explanation, and the validation and status text. |
351
- | `featureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides the copy this widget resolves rather than passes through — status, form-factor and program vocabulary, the copy-success and nickname-updated toasts, the activation, lock and nickname conflict toasts, and the refused-reveal sentence. |
352
- | `cardArtSrc` | `string` | `undefined` | Full per-tenant plastic art for the card face — the same asset you pass `CreateCardWidget`. Takes priority over `bankLogoSrc`; see **Card art** below. |
353
- | `bankLogoSrc` | `string` | `undefined` | Bank logo for the card face. Ignored when `cardArtSrc` is set. Omit and the face renders without a logo rather than with a placeholder. |
354
- | `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. Falls back to `labels.cardFace.bankLogoAlt`. |
308
+ | Prop | Type | Default | Description |
309
+ | ---------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
310
+ | `cardId` | `string` | **Required** | Id of the card to show. |
311
+ | `cardProgram` | `'credit' \| 'debit'` | **Required** | Which issuing program `cardId` belongs to. |
312
+ | `onClose` | `() => void` | `undefined` | Called by the panel's close control and the activation **Done** button. Omit it and neither is rendered. |
313
+ | `labels` | `PartialDeep<CardDetailsWidgetLabels>` | English labels | Overrides the panel's copy. See the exported `CardDetailsWidgetLabels` type for every key. |
314
+ | `activateLabels` | `PartialDeep<ActivateCardPanelLabels>` | English labels | Overrides the Activate Card form's copy. See the exported `ActivateCardPanelLabels` type for every key. |
315
+ | `featureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides status, form-factor and program wording, toasts, and the refused-reveal sentence. See `CardDetailsFeatureLabels`. |
316
+ | `cardArtSrc` | `string` | `undefined` | Full plastic art for the card face (the same asset you pass `CreateCardWidget`). Takes priority over `bankLogoSrc`. |
317
+ | `bankLogoSrc` | `string` | `undefined` | Bank logo for the card face; ignored when `cardArtSrc` is set. The widget ships no bank artwork, so omit it and no logo shows. |
318
+ | `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. Falls back to `labels.cardFace.bankLogoAlt`. |
355
319
 
356
320
  ### CounterpartsWidget
357
321
 
358
- A self-contained widget for managing an organization's customers or vendors with searchable lists, money columns, details, editing, and deletion.
322
+ Manages an organization's customers or vendors: a searchable list with money columns, a details sheet, and create, edit and delete flows, including addresses and a vendor's ACH payment method.
359
323
 
360
324
  #### Props
361
325
 
362
- | Prop | Type | Default | Description |
363
- | -------------------- | ------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364
- | `counterpartType` | `'customer' \| 'vendor'` | — | Required. Selects receivables/customer copy and queries or payables/vendor copy and queries. |
365
- | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size choices shown by the table. |
366
- | `onViewAllDocuments` | `(counterpart: CounterpartActionTarget) => void` | `undefined` | Reveals a "View all" action beside the recent-bills/invoices heading in the details sheet, and hands over the counterpart's `id` and `name` so the destination can filter to them. Omit when the host has no document list to navigate to; the action stays hidden rather than dead. |
367
- | `onCreateDocument` | `(counterpart: CounterpartActionTarget) => void` | `undefined` | Runs the details sheet's primary CTA — "Send a payment" for a vendor, "Issue an invoice" for a customer — with the counterpart's `id` and `name`, so the host can open its create flow pre-linked to them. Omit and the button renders disabled. The destination's own scope (payable/invoice write) is the host's to check. |
368
-
369
- | Prop | Type | Description |
370
- | ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
371
- | `screenLabels` | `Partial<CounterpartsScreenLabels>` | Table title, columns, search/filter, empty, error, access-restricted, and row-action copy. |
372
- | `formLabels` | `Partial<CounterpartFormSheetLabels>` | Create/edit counterpart form copy. |
373
- | `detailsLabels` | `Partial<CounterpartDetailsSheetLabels>` | Details sheet sections, summary labels, subtitle/entity/reminder/payment-method labels, row labels, and actions. |
374
- | `bankAccountLabels` | `PartialDeep<BankAccountFormSheetLabels>` | Vendor payment-method form copy, including nested field-marker labels. |
375
- | `addressLabels` | `PartialDeep<AddressFormSheetLabels>` | Address form copy. |
376
- | `deleteLabels` | `Partial<ConfirmDeleteDialogLabels>` | Delete-dialog copy. |
377
- | `messageLabels` | `Partial<CounterpartMessageLabels>` | Validation, API failure, and delete-prompt messages produced by feature logic. |
326
+ | Prop | Type | Default | Description |
327
+ | -------------------- | ------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
328
+ | `counterpartType` | `'customer' \| 'vendor'` | **Required** | Selects the customer or vendor surface. |
329
+ | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size choices shown by the table. |
330
+ | `onViewAllDocuments` | `(counterpart: CounterpartActionTarget) => void` | `undefined` | Shows a "View all" action by the details sheet's recent bills/invoices and passes the counterpart's `id` and `name`. Hidden when omitted. |
331
+ | `onCreateDocument` | `(counterpart: CounterpartActionTarget) => void` | `undefined` | Runs the details sheet's "Send a payment" (vendor) or "Issue an invoice" (customer) button. Disabled when omitted; you check the scopes it needs. |
332
+ | `screenLabels` | `Partial<CounterpartsScreenLabels>` | English labels | Table, search/filter, empty, error and access-restricted copy. |
333
+ | `formLabels` | `PartialDeep<CounterpartFormSheetLabels>` | English labels | Create/edit form copy. |
334
+ | `detailsLabels` | `Partial<CounterpartDetailsSheetLabels>` | English labels | Details sheet copy. |
335
+ | `bankAccountLabels` | `PartialDeep<BankAccountFormSheetLabels>` | English labels | Vendor payment-method form copy. |
336
+ | `addressLabels` | `PartialDeep<AddressFormSheetLabels>` | English labels | Address form copy. |
337
+ | `deleteLabels` | `Partial<ConfirmDeleteDialogLabels>` | English labels | Delete-dialog copy. |
338
+ | `messageLabels` | `Partial<CounterpartMessageLabels>` | English labels | Validation, API failure and delete-prompt messages. |
378
339
 
379
340
  ### CustomersWidget
380
341
 
381
- A self-contained widget for managing an organization's customers: searchable list, money columns, details, editing, and deletion.
342
+ Manages an organization's customers: a searchable list with money columns, a details sheet, and create, edit and delete flows.
382
343
 
383
344
  #### Props
384
345
 
385
- | Prop | Type | Default | Description |
386
- | -------------------- | --------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
387
- | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size choices shown by the table. |
388
- | `onViewAllDocuments` | `(customer: CounterpartActionTarget) => void` | `undefined` | Reveals a "View all" action beside the recent-invoices heading in the details sheet, and hands over the customer's `id` and `name` so the destination can filter to them. Omit when the host has no invoice list to navigate to. Under `implementation="monite"`, `name` is always empty. |
389
- | `onCreateDocument` | `(customer: CounterpartActionTarget) => void` | `undefined` | Runs the details sheet's "Issue an invoice" action with the customer's `id` and `name`, so the host can open its create flow pre-linked to them. Omit and the button renders disabled. The destination's own invoice-write scope is the host's to check. Under `implementation="monite"`, `name` is always empty. |
390
-
391
- | Prop | Type | Description |
392
- | --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
393
- | `screenLabels` | `Partial<CounterpartsScreenLabels>` | Table title, columns, search/filter, empty, error, and access-restricted copy. |
394
- | `formLabels` | `Partial<CounterpartFormSheetLabels>` | Create/edit customer form copy. |
395
- | `detailsLabels` | `Partial<CounterpartDetailsSheetLabels>` | Details sheet sections, summary labels, subtitle/entity/reminder labels, row labels, and actions. |
396
- | `addressLabels` | `PartialDeep<AddressFormSheetLabels>` | Address form copy. |
397
- | `deleteLabels` | `Partial<ConfirmDeleteDialogLabels>` | Delete-dialog copy. |
398
- | `messageLabels` | `Partial<CounterpartMessageLabels>` | Validation, API failure, and delete-prompt messages produced by feature logic. |
346
+ | Prop | Type | Default | Description |
347
+ | -------------------- | --------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
348
+ | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size choices shown by the table. |
349
+ | `onViewAllDocuments` | `(customer: CounterpartActionTarget) => void` | `undefined` | Shows a "View all" action on the details sheet's recent invoices and passes the customer's `id` and `name`; omit to hide it. |
350
+ | `onCreateDocument` | `(customer: CounterpartActionTarget) => void` | `undefined` | Handles "Issue an invoice" with the customer's `id` and `name`; omit and the button is disabled. You check invoice scopes. |
351
+ | `screenLabels` | `Partial<CounterpartsScreenLabels>` | English labels | Table, search, filter, empty and error copy. |
352
+ | `formLabels` | `Partial<CounterpartFormSheetLabels>` | English labels | Create/edit customer form copy. |
353
+ | `detailsLabels` | `Partial<CounterpartDetailsSheetLabels>` | English labels | Details sheet copy. |
354
+ | `addressLabels` | `PartialDeep<AddressFormSheetLabels>` | English labels | Address form copy. |
355
+ | `deleteLabels` | `Partial<ConfirmDeleteDialogLabels>` | English labels | Delete-dialog copy. |
356
+ | `messageLabels` | `Partial<CounterpartMessageLabels>` | English labels | Validation, API failure and delete-prompt copy. |
399
357
 
400
358
  ### ExpenseManagementWidget
401
359
 
402
- A self-contained expenses widget: a bank-attribution header, My/Team transactions tabs with count badges, per-tab Action Items, a searchable/filterable/paginated transactions table, receipt upload (mailbox or drag-and-drop), and a full-screen transaction review dialog opened from a row or an Action Item.
360
+ A complete expenses surface: My and Team transactions tabs with Action Items, a searchable transactions table, receipt upload, and a full-screen transaction review dialog.
403
361
 
404
362
  #### Props
405
363
 
406
- | Prop | Type | Default | Description |
407
- | --------------------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
408
- | `bankDisplayName` | `string` | — | Bank name shown in the attribution header. |
409
- | `bankLogoSrc` | `string` | — | URL for the bank logo in the attribution header. |
410
- | `bankLogoAlt` | `string` | — | Alt text for the bank logo. |
411
- | `isBankingTaglineVisible` | `boolean` | — | Shows the "Business Banking provided by" tagline beside the header. |
412
- | `onSettingsClick` | `() => void` | — | Renders a settings entry point in the header (host routing ban — the widget never navigates itself). Gated on scopes. |
413
- | `receiptUpload` | `UploadReceiptWidgetProps` | — | Overrides the built-in receipt-upload control's `onFileUpload` / `onAwaitMatching` and other `UploadReceiptWidget` props. |
414
- | `screenLabels` | `Partial<ExpensesScreenLabels>` | English | Tab labels and other `ExpensesScreen` shell copy. |
415
- | `headerLabels` | `Partial<ExpensesHeaderLabels>` | English | Bank-attribution header copy. |
416
- | `transactionsTableLabels` | `Partial<ExpensesTransactionsTableLabels>` | English | Transactions table column headers and empty/loading copy. |
417
- | `filterBarLabels` | `Partial<ExpensesTransactionsFilterBarLabels>` | English | Search/filter bar copy. |
418
- | `actionItemsLabels` | `Partial<ActionItemsListLabels>` | English | Action Items list copy. |
419
- | `statusBadgeLabels` | `Partial<ExpenseStatusBadgeLabels>` | English | Status pill copy, shared between the table and the review dialog. |
420
- | `transactionDetailsLabels` | `Partial<TransactionDetailsLabels>` | English | Copy for the full-screen review dialog opened from a row or an Action Item. |
421
- | `transactionDetailsCardLabels` | `Partial<AccordionItemCardLabels>` | English | Copy for the accordion cards inside the review dialog. |
422
- | `transactionDetailsActionsLabels` | `Partial<TransactionDetailsActionsLabels>` | English | Copy for the review dialog's action buttons. |
423
- | `fileViewerLabels` | `Partial<FileViewerLabels>` | English | Copy for the receipt/attachment file viewer inside the review dialog. |
364
+ | Prop | Type | Default | Description |
365
+ | --------------------------------- | ---------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
366
+ | `bankDisplayName` | `string` | `undefined` | Bank name shown in the attribution header. |
367
+ | `bankLogoSrc` | `string` | `undefined` | URL for the bank logo in the attribution header. |
368
+ | `bankLogoAlt` | `string` | `undefined` | Alt text for the bank logo. |
369
+ | `isBankingTaglineVisible` | `boolean` | `undefined` | Shows the "Business Banking provided by" tagline beside the header. |
370
+ | `onSettingsClick` | `() => void` | `undefined` | Renders a scope-gated settings entry point in the header; navigate from this callback. |
371
+ | `receiptUpload` | `UploadReceiptWidgetProps` | `undefined` | Overrides the receipt-upload control's props, such as `onFileUpload` / `onAwaitMatching`. |
372
+ | `screenLabels` | `Partial<ExpensesScreenLabels>` | English | Tab labels and other screen shell copy. |
373
+ | `headerLabels` | `Partial<ExpensesHeaderLabels>` | English | Bank-attribution header copy. |
374
+ | `transactionsTableLabels` | `Partial<ExpensesTransactionsTableLabels>` | English | Transactions table column headers and empty/loading copy. |
375
+ | `filterBarLabels` | `Partial<ExpensesTransactionsFilterBarLabels>` | English | Search/filter bar copy. |
376
+ | `actionItemsLabels` | `Partial<ActionItemsListLabels>` | English | Action Items list copy. |
377
+ | `statusBadgeLabels` | `Partial<ExpenseStatusBadgeLabels>` | English | Status pill copy, shared between the table and the review dialog. |
378
+ | `transactionDetailsLabels` | `Partial<TransactionDetailsLabels>` | English | Review dialog copy. |
379
+ | `transactionDetailsCardLabels` | `Partial<AccordionItemCardLabels>` | English | Copy for the accordion cards inside the review dialog. |
380
+ | `transactionDetailsActionsLabels` | `Partial<TransactionDetailsActionsLabels>` | English | Copy for the review dialog's action buttons. |
381
+ | `fileViewerLabels` | `Partial<FileViewerLabels>` | English | Copy for the receipt/attachment file viewer inside the review dialog. |
424
382
 
425
383
  ### UploadReceiptWidget
426
384
 
427
- A self-contained "Upload receipts" control: a toggle button that opens a popover with a drag-and-drop / click-to-browse file picker plus a copyable forwarding email address. It is a controlled, presentational widget — the host owns the actual upload via `onFileUpload` and toasts batch progress, success, and failure.
385
+ An "Upload receipts" button that opens a popover with a drag-and-drop file picker and a copyable forwarding email address. It makes no network calls: your `onFileUpload` does the upload, and the widget shows progress and result toasts.
428
386
 
429
387
  _Standalone presentational widget — it does not take the shared auth/scope props._
430
388
 
431
389
  #### Props
432
390
 
433
- | Prop | Type | Default | Description |
434
- | ----------------- | --------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
435
- | `emailAddress` | `string` | `undefined` | Forwarding email address shown in the popover with a copy button. Omit it to hide the email option. |
436
- | `onFileUpload` | `(file: File) => unknown \| Promise<unknown>` | `undefined` | Called once per selected file. The widget awaits each call and counts resolutions vs. rejections to drive its toasts. Omit to disable uploading. |
437
- | `onAwaitMatching` | `(uploadedCount: number) => Promise<ReceiptMatchSummary>` | `undefined` | Awaited after every file in a batch has uploaded. Resolve once the backend has finished OCR and auto-matching, and the widget reports the aggregate outcome in its batch toast. Omit to stop at the upload confirmation. |
438
- | `isUploading` | `boolean` | `false` | Host-controlled loading flag. While `true` (or while a batch is in flight) the popover shows a processing state and blocks new uploads. |
391
+ | Prop | Type | Default | Description |
392
+ | ----------------- | --------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
393
+ | `emailAddress` | `string` | `undefined` | Forwarding email address shown with a copy button. Omit it to hide the email option. |
394
+ | `onFileUpload` | `(file: File) => unknown \| Promise<unknown>` | `undefined` | Called once per selected file and awaited; a rejection counts as a failed upload. Omit to disable uploading. |
395
+ | `onAwaitMatching` | `(uploadedCount: number) => Promise<ReceiptMatchSummary>` | `undefined` | Awaited after every file in a batch uploads. Resolve once matching finishes. Omit to stop at upload. |
396
+ | `isUploading` | `boolean` | `false` | Host loading flag. While `true` (or while a batch runs) the popover shows a processing state and blocks new uploads. |
439
397
 
440
398
  ### BalancesWidget
441
399
 
442
- A self-contained widget that loads embedded bank accounts for the organization, shows up to a configurable number of account balance rows, optionally aggregates a total when multiple accounts exist, and can link out to a host “view all accounts” destination.
400
+ Shows the organization's embedded bank account balances, up to a configurable number of rows, with a total when there are several accounts and an optional **View all accounts** link.
443
401
 
444
402
  #### Props
445
403
 
446
- | Prop | Type | Default | Description |
447
- | ------------------------ | ------------------------------- | ------- | --------------------------------------------------------------------------- |
448
- | `maxAccounts` | `number` | `5` | Maximum rows rendered in-card; additional accounts use the view-all CTA. |
449
- | `labels` | `Partial<BalancesWidgetLabels>` | — | Override shell copy (title, errors, view-all label, total balance tooltip). |
450
- | `onBalanceRowClick` | `(accountId: string) => void` | — | When set, balance rows are clickable and receive the account id. |
451
- | `onViewAllAccountsClick` | `() => void` | — | When set and more than `maxAccounts` exist, shows **View all accounts**. |
404
+ | Prop | Type | Default | Description |
405
+ | ------------------------ | ------------------------------- | -------------- | --------------------------------------------------------------------------- |
406
+ | `maxAccounts` | `number` | `5` | Maximum rows rendered in-card; additional accounts use the view-all CTA. |
407
+ | `labels` | `Partial<BalancesWidgetLabels>` | English labels | Override shell copy (title, errors, view-all label, total balance tooltip). |
408
+ | `onBalanceRowClick` | `(accountId: string) => void` | `undefined` | When set, balance rows are clickable and receive the account id. |
409
+ | `onViewAllAccountsClick` | `() => void` | `undefined` | When set and more than `maxAccounts` exist, shows **View all accounts**. |
452
410
 
453
411
  ### InsightsWidget
454
412
 
455
- A self-contained widget that derives onboarding-style insights from embedded and external bank account data, persists dismissed insight ids via the embed **user-data** API, and exposes optional host callbacks for routing and linking external accounts.
413
+ Shows onboarding-style insights derived from the organization's embedded and external bank accounts, in **Active** and **Dismissed** tabs. Users can dismiss insights, and the widget remembers dismissals per organization.
456
414
 
457
415
  #### Props
458
416
 
459
- | Prop | Type | Default | Description |
460
- | ---------------------------- | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
461
- | `routingEnabled` | `boolean` | `false` | Controlled switch state for the routing onboarding insight. |
462
- | `onRoutingToggleChange` | `(enabled: boolean) => void` | — | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. |
463
- | `onLinkExternalAccountClick` | `() => void` | — | When set, the connect-external-account insight shows a **Link account** CTA. |
464
- | `labels` | `Partial<InsightsWidgetLabels>` | — | Shell copy (tabs, empty, error). |
465
- | `singleInsightLabels` | `Partial<SingleInsightLabels>` | — | Per-row UI strings (e.g. dismiss aria label). |
466
- | `featureLabels` | `Partial<InsightsFeatureLabels>` | — | Generated insight body copy and action labels. |
417
+ | Prop | Type | Default | Description |
418
+ | ---------------------------- | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
419
+ | `routingEnabled` | `boolean` | `false` | Controlled switch state for the routing onboarding insight. |
420
+ | `onRoutingToggleChange` | `(enabled: boolean) => void` | `undefined` | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. |
421
+ | `onLinkExternalAccountClick` | `() => void` | `undefined` | When set, the connect-external-account insight shows a **Link account** CTA. |
422
+ | `labels` | `Partial<InsightsWidgetLabels>` | English labels | Shell copy (tabs, empty, error). |
423
+ | `singleInsightLabels` | `Partial<SingleInsightLabels>` | English labels | Per-row UI strings, such as the dismiss button's `aria-label`. |
424
+ | `featureLabels` | `Partial<InsightsFeatureLabels>` | English labels | Generated insight body copy and action labels. |
467
425
 
468
426
  ### InvoicingWidget
469
427
 
470
- A self-contained invoicing widget that renders the Monite SDK receivables experience (invoices, quotes, and credit notes) against your widget auth — the host only supplies credentials and optional theming.
428
+ A full invoicing experience: invoices, quotes and credit notes. You supply widget auth and, optionally, theme colors and a page-title wrapper.
471
429
 
472
430
  #### Props
473
431
 
474
- | Prop | Type | Default | Description |
475
- | -------------------- | ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
476
- | `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Overrides the Monite theme's primary colors. Omit to use Monite defaults. |
477
- | `embeddedBankName` | `string` | `undefined` | Display name of the sponsor bank powering embedded bank accounts (e.g. `"Zenith Bank"`). Shown next to embedded accounts in the invoice payment-account picker as "Powered by {embeddedBankName}". |
478
- | `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Passthrough | Wraps the page header region. The default returns its children unchanged; supply a wrapper to add a title, branding, or toolbar around the widget's action buttons. |
432
+ | Prop | Type | Default | Description |
433
+ | -------------------- | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------ |
434
+ | `finopsThemeColors` | `FinopsThemeColors` | `undefined` | `{ primary?: string; primaryForeground?: string }` overriding the theme's primary colors. |
435
+ | `embeddedBankName` | `string` | `undefined` | Sponsor bank name, shown as "Powered by {embeddedBankName}" next to embedded accounts in the payment picker. |
436
+ | `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Passthrough | Wraps the header region (which holds the widget's action buttons) to add a title or toolbar. |
479
437
 
480
438
  ### LinkedAccountsWidget
481
439
 
482
- A self-contained widget that lists and manages external bank accounts, including connect, edit, micro-deposit initiation, micro-deposit validation, and unlink actions.
440
+ Lists the organization's external bank accounts and lets the user connect, edit, verify with micro-deposits, and unlink them.
483
441
 
484
442
  #### Props
485
443
 
486
- | Prop | Type | Default | Description |
487
- | --------------- | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
488
- | `labels` | `Partial<LinkedAccountsWidgetLabels>` | English labels | Overrides visible UI copy such as button, dialog, empty-state, loading, and error labels. Unspecified labels fall back to defaults. |
489
- | `featureLabels` | `Partial<LinkedAccountsWidgetFeatureLabels>` | English labels | Overrides strings produced by the feature layer, such as row title fallback, account-number subtitle fragments, and the success toast messages shown after editing or unlinking an account. |
444
+ | Prop | Type | Default | Description |
445
+ | --------------- | -------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
446
+ | `labels` | `Partial<LinkedAccountsWidgetLabels>` | English labels | Override UI copy. `stepIndicator` takes `{current}` and `{total}`; `verifySuccessDescription` and `unlinkDescription` take `{account}`. |
447
+ | `featureLabels` | `Partial<LinkedAccountsWidgetFeatureLabels>` | English labels | Override row fallback text, the account-number prefix, and the edit/unlink success toasts. |
490
448
 
491
449
  ### BankAccountOnboardingWidget
492
450
 
493
- A self-contained widget that walks an applicant through the embedded bank-account onboarding flow: business details, personal details, optional additional owners, and a result screen. It owns all REST mutations (`createApplication`, `updateApplication`, `submitApplication`), step navigation, validation, and polling for provisioning to complete — the host application only supplies auth credentials and two callbacks.
451
+ Walks an applicant through bank-account onboarding: business details, personal details, optional additional owners, and a result screen. The widget handles saving, validation, submission and waiting for the account to open; you supply auth and two callbacks.
494
452
 
495
453
  #### Props
496
454
 
497
- | Prop | Type | Required | Description |
498
- | ------------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
499
- | `onEmbeddedOnboardingCompletedSuccessfully` | `() => void` | Yes | Called when the application is submitted and approved. |
500
- | `onNavigateToDashboard` | `() => void` | Yes | Called when the user clicks the dashboard CTA on the result screen. |
501
- | `initialBusinessDetails` | `Partial<HostSupplied<BusinessDetailsValues>>` | No | Prefills step 1 (business details). Unset fields start empty; the user can still edit before continuing. Excludes the resume-only `taxIdOnFileLast4` / `taxIdOnFileStructure`, which only a stored application may set. |
502
- | `initialPersonalDetails` | `Partial<HostSupplied<PersonalDetailsValues>>` | No | Prefills step 2 (personal / about-you details). Unset fields start empty; the user can still edit before continuing. Excludes the resume-only `ssnOnFileLast4`. |
503
- | `initialAdditionalOwners` | `HostSuppliedOwner[]` | No | Prefills step 3 (additional owners). Defaults to an empty list when omitted. Excludes `id`, which names an owner the server already stores, so a seeded one would update instead of create. |
504
- | `open` | `boolean` | No | Controlled open state for the modal. When provided the host owns open/close and must update it via `onOpenChange`. Omit for uncontrolled mode. |
505
- | `defaultOpen` | `boolean` | No | Initial open state when uncontrolled. Defaults to `false` so the modal stays closed until the host opens it. Ignored when `open` is set. |
506
- | `onOpenChange` | `(open: boolean) => void` | No | Notified whenever the modal opens or closes — fires on overlay click, escape key, the close button, and any controlled state update. Used both as the change handler in controlled mode and a side hook. |
507
- | `labels` | `BankAccountOnboardingWidgetLabels` | No | Per-step label overrides — see Labels section. Accepts a `modalTitle` override for the modal's accessible title (default: `Bank account onboarding`). |
508
- | `bankLogoSrc` | `string` | No | URL for the bank logo rendered on the result screen; falls back to bank name text. |
509
- | `disclosureLinks` | `DisclosureLinks` | No | Host-resolved URLs for Terms of Use, Privacy Policy, Electronic Communication, and Patriot Act on the business-details agreement step. Omit to leave those links unset. |
510
- | `isFullScreenInline` | `boolean` | No | Renders the widget inline — filling the width/height of its host container — instead of in a modal. `open` / `defaultOpen` are ignored in this mode; the widget always renders once mounted, and the host controls mounting instead. `onOpenChange` still fires for gestures like Cancel, so hosts can react (e.g. by unmounting the widget). Defaults to `false`. |
455
+ | Prop | Type | Default | Description |
456
+ | ------------------------------------------- | ---------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
457
+ | `onEmbeddedOnboardingCompletedSuccessfully` | `() => void` | **Required** | Called when the application is approved and the account is open. |
458
+ | `onNavigateToDashboard` | `() => void` | **Required** | Called when the user clicks the dashboard CTA on the result screen. |
459
+ | `initialBusinessDetails` | `Partial<HostSupplied<BusinessDetailsValues>>` | `undefined` | Prefills step 1 (business details); the user can still edit. |
460
+ | `initialPersonalDetails` | `Partial<HostSupplied<PersonalDetailsValues>>` | `undefined` | Prefills step 2 (personal details); the user can still edit. |
461
+ | `initialAdditionalOwners` | `HostSuppliedOwner[]` | `[]` | Prefills step 3 (additional owners). |
462
+ | `open` | `boolean` | `undefined` | Controlled open state for the modal; update it from `onOpenChange`. Omit for uncontrolled mode. |
463
+ | `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. Ignored when `open` is set. |
464
+ | `onOpenChange` | `(open: boolean) => void` | `undefined` | Fires whenever the modal opens or closes (overlay click, Escape, close button, Cancel, save or delete). |
465
+ | `labels` | `BankAccountOnboardingWidgetLabels` | English labels | Per-step and shell copy overrides, merged with the English defaults. |
466
+ | `bankLogoSrc` | `string` | `undefined` | Bank logo URL for the result screen; falls back to the bank name as text. |
467
+ | `disclosureLinks` | `DisclosureLinks` | `undefined` | URLs for Terms of Use, Privacy Policy, Electronic Communication and Patriot Act on step 1. You resolve these; omit to leave unset. |
468
+ | `isFullScreenInline` | `boolean` | `false` | Renders inline, filling its container, instead of in a modal. `open` / `defaultOpen` are ignored. |
511
469
 
512
470
  ### MarketingWidget
513
471
 
514
- A self-contained marketing card and modal that presents host-supplied banking product copy (logo, captions, "How it works" steps, benefits, colors). The card renders two CTAs — Apply now and Learn more — and the modal's own CTA. The host wires all three to whatever should happen next — typically opening `BankAccountOnboardingWidget`.
515
-
516
- The widget renders nothing until widget init and the organization's `application-status` read resolve. It hides itself when the caller is already onboarded (`ACTIVE` / `INACTIVE`), invited (`INVITED`), or their organization's bank-account application is `COMPLETE`.
517
-
518
- Otherwise the card follows the organization's bank-account application:
519
-
520
- | Application status | Started by the caller | Started by a colleague |
521
- | ---------------------- | ------------------------------------------ | ------------------------------ |
522
- | none | Normal offer | Normal offer |
523
- | `DRAFT` | Normal offer, CTA reads Resume application | Status chip + message, no CTAs |
524
- | `SUBMITTED` | Status chip + message, no CTAs | Status chip + message, no CTAs |
525
- | `DENIED` | Status chip + message, no CTAs | Status chip + message, no CTAs |
526
- | `DELETED` / `CANCELED` | Normal offer | Normal offer |
527
- | `COMPLETE` | Hidden | Hidden |
528
-
529
- Resume application calls the same `onPrimaryCtaClick`: `BankAccountOnboardingWidget` resumes the caller's own draft by itself. The bank's name in the messages comes from widget init (`bankName`). Tenant-specific assets and copy are always passed in as `content` — the published package does not look up white-label or bank maps.
472
+ A marketing card and modal that presents your banking product copy (logo, captions, "How it works" steps, benefits, colors). Its Apply now and modal CTAs call `onPrimaryCtaClick`, which you typically wire to open `BankAccountOnboardingWidget`.
530
473
 
531
474
  #### Props
532
475
 
533
- | Prop | Type | Required | Description |
534
- | ------------------- | ------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
535
- | `content` | `MarketingWidgetContent` | Yes | Host-resolved card and modal copy, images, "How it works" steps, benefits, and appearance. |
536
- | `onPrimaryCtaClick` | `() => void` | Yes | Called when the applicant clicks Apply now on the card or the modal CTA (default label: Start application). Closes the modal first. |
537
- | `labels` | `PartialDeep<MarketingWidgetLabels>` | No | Override Apply now, Learn more, the modal CTA + subtext, and the modal dismiss `aria-label`. |
538
- | `statusLabels` | `PartialDeep<MarketingWidgetStatusLabels>` | No | Override the Resume application label and the chip, heading and body copy of each application-status message. Heading and body are functions of `{ bankName }`. |
476
+ | Prop | Type | Default | Description |
477
+ | ------------------- | ------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
478
+ | `content` | `MarketingWidgetContent` | **Required** | Host-resolved card and modal copy, images, "How it works" steps, benefits, and appearance. |
479
+ | `onPrimaryCtaClick` | `() => void` | **Required** | Called when the applicant clicks Apply now on the card or the modal CTA (default label: Start application). Closes the modal first. |
480
+ | `labels` | `PartialDeep<MarketingWidgetLabels>` | English labels | Override the card and modal copy. See the exported `MarketingWidgetLabels` type for every key. |
481
+ | `statusLabels` | `PartialDeep<MarketingWidgetStatusLabels>` | English labels | Override the Resume application label and each status message. Heading and body are functions of `{ bankName }`. |
539
482
 
540
483
  ### ProductsWidget
541
484
 
542
- A self-contained widget for managing an organization's products and services: it lists them in a filterable, sortable, cursor-paginated table and handles creating, editing, viewing, and deleting them — including full measure-unit management. The host only supplies auth credentials and optional label overrides.
485
+ Manages an organization's products and services: a filterable, sortable table with create, edit, view and delete flows, plus measure-unit management.
543
486
 
544
487
  #### Props
545
488
 
546
- | Prop | Type | Description |
547
- | ------------------------- | ---------------------------------------- | ---------------------------------------------------- |
548
- | `pageSizeOptions` | `number[]` | Rows-per-page choices (default `[10, 25, 50, 100]`). |
549
- | `screenLabels` | `Partial<ProductsScreenLabels>` | Table/header/filter/empty/error copy. |
550
- | `formLabels` | `Partial<ProductFormSheetLabels>` | Create/edit form copy. |
551
- | `detailsLabels` | `Partial<ProductDetailsSheetLabels>` | Details sheet copy. |
552
- | `deleteLabels` | `Partial<ProductDeleteDialogLabels>` | Product delete confirmation copy. |
553
- | `measureUnitsLabels` | `Partial<MeasureUnitsManagerLabels>` | Measure-units manager copy. |
554
- | `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | Measure-unit delete confirmation copy. |
555
- | `messageLabels` | `Partial<ProductMessageLabels>` | Validation / error messages produced by the widget. |
489
+ | Prop | Type | Default | Description |
490
+ | ------------------------- | ---------------------------------------- | ------------------- | --------------------------------------------------- |
491
+ | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Rows-per-page choices. |
492
+ | `screenLabels` | `Partial<ProductsScreenLabels>` | English labels | Table/header/filter/empty/error copy. |
493
+ | `formLabels` | `Partial<ProductFormSheetLabels>` | English labels | Create/edit form copy. |
494
+ | `detailsLabels` | `Partial<ProductDetailsSheetLabels>` | English labels | Details sheet copy. |
495
+ | `deleteLabels` | `Partial<ProductDeleteDialogLabels>` | English labels | Product delete confirmation copy. |
496
+ | `measureUnitsLabels` | `Partial<MeasureUnitsManagerLabels>` | English labels | Measure-units manager copy. |
497
+ | `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | English labels | Measure-unit delete confirmation copy. |
498
+ | `messageLabels` | `Partial<ProductMessageLabels>` | English labels | Validation / error messages produced by the widget. |
556
499
 
557
500
  ### ReceivablesWidget
558
501
 
559
- A self-contained native widget for listing, creating, editing, and acting on customer receivables.
502
+ Lists, creates, edits and acts on an organization's invoices, quotes and credit notes, including sending by email and recording payments. It's the in-progress native replacement for `InvoicingWidget`.
560
503
 
561
504
  #### Props
562
505
 
563
- | Prop | Type | Default | Description |
564
- | ------------------------- | ---------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
565
- | `defaultTab` | `ReceivablesWidgetTab` | `'invoices'` | Initial tab when that tab is enabled. If it is omitted or disabled, the widget starts on the first enabled tab. |
566
- | `enabledTabs` | `ReceivablesWidgetTab[]` | `['invoices', 'quotes', 'credit_notes']` | Tabs visible to the user. Duplicate or unknown values are ignored. |
567
- | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Rows-per-page choices shown by the table. The first page loads with a page size of `10`. |
568
- | `onReceivableCreated` | `(id: string, type: ReceivableDocumentType) => void` | `undefined` | Called after create or clone succeeds. The widget switches to the new document's tab and opens its details. |
569
- | `onReceivableOpened` | `(id: string, type: ReceivableDocumentType) => void` | `undefined` | Called when the user opens a row's detail sheet. |
570
- | `onTemplateSettingsClick` | `() => void` | `undefined` | Shows a template settings action in the header and calls this handler when selected. |
571
-
572
- | Prop | Type | Default | Description |
573
- | -------------------------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
574
- | `embeddedBankName` | `string` | `undefined` | Display name of the sponsor bank powering embedded bank accounts (e.g. `"Zenith Bank"`). Shown next to embedded accounts in the invoice payment-account picker as "Powered by {embeddedBankName}"; omitted when unset. |
575
- | `screenLabels` | `Partial<ReceivablesScreenLabels>` | English defaults | Overrides table, tab, filter, empty, error, action, and status badge copy. |
576
- | `formLabels` | `Partial<ReceivableFormSheetLabels>` | English defaults | Overrides create/edit form labels and button copy. |
577
- | `detailsLabels` | `Partial<ReceivableDetailsSheetLabels>` | English defaults | Overrides detail sheet headings, actions, empty copy, and status badge copy. |
578
- | `sendLabels` | `Partial<ReceivableSendDialogLabels>` | English defaults | Overrides send-email dialog labels and buttons. |
579
- | `paymentLabels` | `Partial<ReceivablePaymentDialogLabels>` | English defaults | Overrides manual payment dialog labels and buttons. |
580
- | `actionLabels` | `Partial<ReceivableActionDialogLabels>` | English defaults | Overrides generic confirmation dialog buttons. Action-specific title and body copy come from `messageLabels`. |
581
- | `counterpartFormLabels` | `Partial<CounterpartFormSheetLabels>` | English defaults | Overrides inline customer creation copy from the shared counterpart-management flow. |
582
- | `measureUnitsLabels` | `Partial<MeasureUnitsManagerLabels>` | English defaults | Overrides copy of the measure-unit manager opened from a line item's unit select. |
583
- | `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | English defaults | Overrides measure-unit delete confirmation copy. |
584
- | `messageLabels` | `Partial<ReceivableMessageLabels>` | English defaults | Overrides validation, fallback, summary, activity, reminder, and action-confirmation messages generated by the feature layer, including the subject and body saved on a reminder created from the form. |
585
- | `productMessageLabels` | `Partial<ProductMessageLabels>` | English defaults | Overrides product flow validation and error messages. |
586
- | `counterpartMessageLabels` | `Partial<CounterpartMessageLabels>` | English defaults | Overrides customer flow validation and error messages. |
506
+ | Prop | Type | Default | Description |
507
+ | -------------------------- | ---------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
508
+ | `defaultTab` | `ReceivablesWidgetTab` | `'invoices'` | Initial tab; if omitted or disabled, the widget starts on the first enabled tab. |
509
+ | `enabledTabs` | `ReceivablesWidgetTab[]` | `['invoices', 'quotes', 'credit_notes']` | Tabs visible to the user. Duplicate or unknown values are ignored. |
510
+ | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Rows-per-page choices. The first page loads with a page size of `10`. |
511
+ | `onReceivableCreated` | `(id: string, type: ReceivableDocumentType) => void` | `undefined` | Called after a create or clone succeeds. |
512
+ | `onReceivableOpened` | `(id: string, type: ReceivableDocumentType) => void` | `undefined` | Called when the user opens a row's detail sheet. |
513
+ | `onTemplateSettingsClick` | `() => void` | `undefined` | Shows a template settings action in the header and calls this handler when clicked. |
514
+ | `embeddedBankName` | `string` | `undefined` | Sponsor bank name shown as "Powered by {embeddedBankName}" next to embedded accounts in the invoice payment-account picker. Omitted when unset. |
515
+ | `screenLabels` | `ReceivablesScreenLabelOverrides` | English labels | Table, tab, filter, empty, error, action and status badge copy. |
516
+ | `formLabels` | `Partial<ReceivableFormSheetLabels>` | English labels | Create/edit form copy. |
517
+ | `detailsLabels` | `ReceivableDetailsSheetLabelOverrides` | English labels | Detail sheet copy, including status badges. |
518
+ | `sendLabels` | `Partial<ReceivableSendDialogLabels>` | English labels | Send-email dialog copy. |
519
+ | `paymentLabels` | `Partial<ReceivablePaymentDialogLabels>` | English labels | Manual payment dialog copy. |
520
+ | `actionLabels` | `Partial<ReceivableActionDialogLabels>` | English labels | Confirmation dialog buttons; per-action titles come from `messageLabels`. |
521
+ | `counterpartFormLabels` | `PartialDeep<CounterpartFormSheetLabels>` | English labels | Inline customer creation copy. |
522
+ | `measureUnitsLabels` | `Partial<MeasureUnitsManagerLabels>` | English labels | Measure-unit manager copy. |
523
+ | `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | English labels | Measure-unit delete confirmation copy. |
524
+ | `messageLabels` | `Partial<ReceivableMessageLabels>` | English labels | Validation, fallback, summary, activity, reminder and confirmation messages, including a new reminder's subject and body. |
525
+ | `productMessageLabels` | `Partial<ProductMessageLabels>` | English labels | Product validation and error messages. |
526
+ | `counterpartMessageLabels` | `Partial<CounterpartMessageLabels>` | English labels | Customer validation and error messages. |
587
527
 
588
528
  ### SettingsWidget
589
529
 
590
- A composite settings widget that combines profile, team, invoice, bill-pay, expense, accounting, legal and help settings in one navigable surface.
530
+ A single navigable settings surface combining profile, team, invoice, bill-pay, expense, accounting, legal and help sections.
591
531
 
592
532
  #### Props
593
533
 
594
- | Prop | Type | Default | Description |
595
- | ------------------------- | -------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
596
- | `acceptInviteRedirectUri` | `string` | Same-origin `/accept-invite` | Forwarded to the Team section's widget — allowlisted URL invite emails link to. Defaults to `${window.location.origin}/accept-invite`; set it when the host app's registered landing route differs from the widget's same-origin default, or the origin is not on the OIDC redirect-URI allowlist (preview/localhost). |
597
- | `labels` | `Partial<Labels>` | English labels | Overrides the settings heading copy. |
598
- | `featureLabels` | `Partial<FeatureLabels>` | English labels | Overrides section labels. |
599
- | `profileContent` | `ReactNode` | Profile widget | Replaces the profile section content. |
600
- | `teamContent` | `ReactNode` | Empty | Supplies the team section content. |
601
- | `invoiceContent` | `ReactNode` | Invoice settings widget | Replaces invoice settings content. |
602
- | `billPayContent` | `ReactNode` | Approval policies settings | Replaces bill-pay settings content. |
603
- | `accountingContent` | `ReactNode` | Chart of accounts widget | Replaces accounting content. |
604
- | `expenseContent` | `ReactNode` | Expense policies and requirements | Replaces expense content. |
605
- | `legalContent` | `ReactNode` | Bank disclosures widget | Replaces the Legal section content. |
606
- | `profileContactUrl` | `string` | `undefined` | Forwarded to the Profile section's widget — where its "to change this information, contact your bank" line links. Left unset, the card shows the plain unlinked sentence instead; the bank name comes from widget init. |
607
- | `selectedSection` | `SettingsWidgetSectionId` | `undefined` | The section to show. Leave unset to let the widget own the selection; supply it (with `onSelectedSectionChange`) to drive navigation from a route or search param. A section the user's scopes hide falls back to the first visible one. |
608
- | `defaultSelectedSection` | `SettingsWidgetSectionId` | First visible section | The section to open on, for a host that wants a deep link without owning the selection. Read once per mount and ignored when `selectedSection` is supplied. Scopes arrive with widget init, so a section this names opens as soon as it becomes visible; one the user's scopes never grant leaves the first visible section on screen. |
609
- | `onSelectedSectionChange` | `(section: SettingsWidgetSectionId) => void` | `undefined` | Called with the id of the section the user selected. Fires whether or not `selectedSection` is supplied, so a host can mirror the selection into its URL without taking ownership of it. |
610
- | `additionalSections` | `SettingsWidgetAdditionalSection[]` | `undefined` | Host-owned sections rendered alongside the built-in ones. Each is `{ id, label, content }` plus an optional `after` naming the built-in section to place it behind. Unlike the built-ins, these are not scope-gated. |
611
- | `helpContactUrl` | `string` | `undefined` | Forwarded to the Help section's widget — where its "Contact Us" line links (a support page URL or a `mailto:`). The line is hidden while unset, since the package has no tenant-agnostic support address to fall back on; the bank name in that line comes from widget init. |
612
- | `helpFaq` | `HelpFaqSection[]` | `HELP_FAQ_EN` | Forwarded to the Help section: the FAQ it renders. Extend the exported `HELP_FAQ_EN` and pass the result to answer questions the package cannot (passwords, for example) without replacing the whole section. |
613
- | `helpContent` | `ReactNode` | Help widget | Replaces the help section content. |
614
- | `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Optional Monite theme color overrides. Nothing under this widget renders Monite any more, so it currently changes nothing here; it is still accepted rather than removed in the same release as the section it themed. |
534
+ | Prop | Type | Default | Description |
535
+ | ------------------------- | -------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
536
+ | `acceptInviteRedirectUri` | `string` | Same-origin `/accept-invite` | Where Team invite emails link to; set it when your landing route differs or the origin isn't allowlisted. |
537
+ | `labels` | `Partial<Labels>` | English labels | Overrides the settings heading copy. |
538
+ | `featureLabels` | `Partial<FeatureLabels>` | English labels | Overrides section labels. |
539
+ | `profileContent` | `ReactNode` | Profile widget | Replaces the profile section content. |
540
+ | `teamContent` | `ReactNode` | Team widget | Replaces the team section content. |
541
+ | `invoiceContent` | `ReactNode` | Invoice settings widget | Replaces invoice settings content. |
542
+ | `billPayContent` | `ReactNode` | Approval policies settings | Replaces bill-pay settings content. |
543
+ | `accountingContent` | `ReactNode` | Chart of accounts widget | Replaces accounting content. |
544
+ | `expenseContent` | `ReactNode` | Expense policies and requirements | Replaces expense content. |
545
+ | `legalContent` | `ReactNode` | Bank disclosures widget | Replaces the Legal section content. |
546
+ | `profileContactUrl` | `string` | `undefined` | Link for the Profile section's "contact your bank" line; unlinked when unset. |
547
+ | `selectedSection` | `SettingsWidgetSectionId` | `undefined` | The section to show (controlled). Pair with `onSelectedSectionChange`; leave unset to let the widget own it. |
548
+ | `defaultSelectedSection` | `SettingsWidgetSectionId` | First visible section | The section to open on; read once per mount and ignored when `selectedSection` is set. |
549
+ | `onSelectedSectionChange` | `(section: SettingsWidgetSectionId) => void` | `undefined` | Called with the section the user selected, whether or not `selectedSection` is supplied. |
550
+ | `additionalSections` | `SettingsWidgetAdditionalSection[]` | `undefined` | Host-owned `{ id, label, content, after? }` sections; `after` names the built-in section to place it behind. |
551
+ | `helpContactUrl` | `string` | `undefined` | Link (URL or `mailto:`) for the Help section's "Contact Us" line; hidden when unset. |
552
+ | `helpFaq` | `HelpFaqSection[]` | `HELP_FAQ_EN` | FAQ shown in the Help section. Extend the exported `HELP_FAQ_EN` to add your own questions. |
553
+ | `helpContent` | `ReactNode` | Help widget | Replaces the help section content. |
554
+ | `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Legacy theme overrides; currently has no effect. |
615
555
 
616
556
  ### TransfersWidget
617
557
 
618
- A self-contained banking widget for creating book or ACH transfers and reviewing recent movement across embedded accounts.
558
+ Lists recent transfers across the organization's embedded bank accounts and lets the user send a book or ACH transfer.
619
559
 
620
560
  #### Props
621
561
 
622
- | Prop | Type | Default | Description |
623
- | ---------------------------- | --------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
624
- | `labels` | `Partial<TransfersWidgetLabels>` | English labels | Override shell and modal copy. |
625
- | `featureLabels` | `Partial<TransfersWidgetFeatureLabels>` | English defaults | Override routing copy, fallbacks, default currency, and ACH SEC code. |
626
- | `isTransferMoneyOpen` | `boolean` | Uncontrolled | Whether the transfer money modal is showing. Supplying it makes the modal controlled: the widget reports every open and close and changes nothing until you re-supply a new value. |
627
- | `defaultIsTransferMoneyOpen` | `boolean` | `false` | The modal's state on first render, for a host that only wants to seed it. Ignored when `isTransferMoneyOpen` is supplied. |
628
- | `onTransferMoneyOpenChange` | `(open: boolean) => void` | `undefined` | Called on every open and close — the **Transfer money** CTA, the modal's own dismissals (Esc, overlay, close), and the close after a completed transfer. |
562
+ | Prop | Type | Default | Description |
563
+ | ---------------------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
564
+ | `labels` | `Partial<TransfersWidgetLabels>` | English labels | Override list and modal copy. |
565
+ | `featureLabels` | `Partial<TransfersWidgetFeatureLabels>` | English defaults | Override route separator, fallback text, default currency and ACH SEC code. |
566
+ | `isTransferMoneyOpen` | `boolean` | Uncontrolled | Controls the transfer modal. When set, the widget only reports open/close requests and waits for you. |
567
+ | `defaultIsTransferMoneyOpen` | `boolean` | `false` | Initial modal state when uncontrolled. Ignored when `isTransferMoneyOpen` is set. |
568
+ | `onTransferMoneyOpenChange` | `(open: boolean) => void` | `undefined` | Called on every open and close: the button, the modal's own dismissals, and the close after a transfer. |
629
569
 
630
570
  <!-- END GENERATED REFERENCE -->
631
571
 
632
572
  ## UI frameworks (shadcn default, Tecton optional)
633
573
 
634
- Widgets render with the default shadcn/native surface out of the box — no extra
635
- install, no configuration. An alternate UI framework (Tecton, built on the Q2 /
636
- Stencil design system) is shipped as a **separate, opt-in package** so the core
637
- package never carries Stencil or its build-time/runtime weight:
574
+ Widgets render with the default shadcn surface and need no configuration. Tecton
575
+ (the Q2 / Stencil design system) ships as a separate, opt-in package:
638
576
 
639
577
  ```bash
640
578
  npm i @tesouro/embedded-components-react-tecton-ui
@@ -642,38 +580,22 @@ npm i @tesouro/embedded-components-react-tecton-ui
642
580
 
643
581
  ```ts
644
582
  import { registerTectonUI } from '@tesouro/embedded-components-react-tecton-ui';
645
- registerTectonUI(); // once, at app startup
583
+ registerTectonUI();
646
584
  ```
647
585
 
648
- Then select it via the provider cascade (`uiFramework="tecton"`). Without the
649
- extension installed, `uiFramework="tecton"` degrades gracefully to shadcn. See
650
- the extension's README for setup, the migration guide, and the Turbopack /
651
- `@stencil/core` note that applies only when the Tecton extension is installed.
586
+ Call `registerTectonUI()` once at app startup, then set `uiFramework="tecton"` on a provider. Without the extension installed it
587
+ falls back to shadcn. See the extension's README for setup.
652
588
 
653
589
  ### TypeScript module resolution
654
590
 
655
- This package ships ESM with TypeScript declarations and is intended for
656
- **bundler-based** consumers — Vite, webpack, esbuild, Next.js — which is how
657
- React apps are built. Its types are exposed through the package `exports` map, so
658
- set TypeScript's `"moduleResolution"` to **`"bundler"`** (the modern default) and
659
- every entrypoint (`.`, `./core`, `./monite-sdk`, `./lib/*`, `./experimental`,
660
- `./experimental/*`) resolves cleanly.
661
-
662
- The published declarations are **self-contained**: the build bundles each
663
- entrypoint's `.d.ts` (`scripts/bundle-dts.mjs`) so it inlines the internal
664
- workspace types instead of re-exporting them from unpublished `@tesouro-fe/*`
665
- packages, and only genuine dependencies (react, MUI, …) remain as bare imports.
666
- An ESM consumer therefore type-checks cleanly under `"bundler"` **and**
667
- `"node16"` / `"nodenext"`, even with `skipLibCheck: false`.
668
-
669
- Legacy `"moduleResolution": "node"` (a.k.a. `node10` / classic) is **not
670
- supported**: it ignores the `exports` map, and this package carries no top-level
671
- `types` field, so the type checker reports `TS2307` for the package and its
672
- subpaths. Use `"bundler"` instead — every bundler-based toolchain supports it.
673
- As an ESM-only package it is not `require()`-able from CommonJS.
591
+ Set `"moduleResolution"` to **`"bundler"`** (or `"node16"` / `"nodenext"`); every
592
+ entry point then resolves, and the declarations type-check with
593
+ `skipLibCheck: false`. Legacy `"node"` / `node10` resolution is **not supported**
594
+ (it ignores the `exports` map and reports `TS2307`). The package is ESM-only and
595
+ can't be `require()`d from CommonJS.
674
596
 
675
597
  ## Contributing
676
598
 
677
- Maintainer notes — the monorepo build/publishing model, the publish-verification
678
- gate, and how to run the unit tests — live in `CONTRIBUTING.md` in the source
679
- repository.
599
+ Maintainer notes live in `CONTRIBUTING.md` in the source repository: the
600
+ monorepo build and publishing model, the publish-verification gate, and how to
601
+ run the unit tests.