# tesouro-embedded-components-react
This package is the public npm surface for Tesouro embedded React widgets.
## Consuming the package
`@tesouro/embedded-components-react` is an ESM package for bundler-based React
apps (Vite, webpack, esbuild, Next.js). `react` and `react-dom` (v19) are peer
dependencies.
```bash
npm install @tesouro/embedded-components-react
# or: yarn add @tesouro/embedded-components-react
```
**Import the stylesheet once** at your app's entry point — widgets render
unstyled without it:
```ts
import '@tesouro/embedded-components-react/styles.css';
```
Then render a widget inside a provider that establishes its authenticated scope:
```tsx
import '@tesouro/embedded-components-react/styles.css';
import {
RootWidgetProvider,
BankAccountsWidget,
} from '@tesouro/embedded-components-react';
export function App() {
return (
);
}
```
Every provider and widget prop is fully typed in the shipped declarations, so
your editor documents the full auth/config model inline — per-widget
`WidgetProvider`, config inheritance, token refresh, and the built-in error
boundary.
### Entry points
| Import path | What you get |
| ------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `@tesouro/embedded-components-react` | All widgets plus `RootWidgetProvider` / `WidgetProvider`. |
| `@tesouro/embedded-components-react/styles.css` | The widget stylesheet — see [About the stylesheet](#about-the-stylesheet). |
| `@tesouro/embedded-components-react/core` | Framework-agnostic token utilities (`createWidgetTokenManager`). |
| `@tesouro/embedded-components-react/monite-sdk` | Monite SDK surface for Monite-backed widgets. |
| `@tesouro/embedded-components-react/experimental` | Work in progress — no compatibility promise. See [below](#experimental-entry-point). |
### Experimental entry point
`@tesouro/embedded-components-react/experimental` (and the per-module
`@tesouro/embedded-components-react/experimental/`) is a staging area for
work in progress. It is **outside this package's semver contract**:
- Anything exported there can change shape or be **removed outright in any
release, including a patch**. There is no deprecation window.
- Its exports are deliberately not documented here — no prop tables, no
reference entry. Read the shipped types.
- It is unsupported. If you hit a problem with it, use the released widget on
the main entry point instead.
Use it only when we have pointed you at a specific module, and pin the package
to an exact version if you do.
Everything else in this package — the main entry point, `./core`,
`./monite-sdk`, `./lib/*` and the stylesheet — carries the normal compatibility
promise and is unaffected by churn on this path.
### About the stylesheet
The stylesheet is host-safe by design. It ships **no
global CSS reset**: Tailwind's Preflight is omitted and instead re-expressed
scoped under the `.tesouro-embedded` wrapper that every widget renders, and all
utilities are `ttw`-prefixed — so loading it won't restyle your host page or
collide with your own Tailwind. Design tokens (`--ttw-*`) are declared on
`:root`/`.dark`; dark mode follows an ancestor `.dark` class, and the widget
font can be white-labeled via `--ttw-font-family`.
## Providers
Every widget renders inside a provider that establishes its authenticated
scope. Place a **`RootWidgetProvider`** once near the root of your app; use a
**`WidgetProvider`** to override config (token, base URL, UI framework) for a
subtree, or as a standalone root when you mount a single widget on its own. For
automatic token rotation, use **`WidgetTokenRefreshProvider`** (or the bundled
**`RefreshingRootWidgetProvider`**). Providers wrap their subtree in a built-in
error boundary and expose the resolved config through the `useWidgetConfig`,
`useWidgetLoading`, `useWidgetError`, and `useRefetchWidget` hooks; non-React
hosts can seed config through the global store (`setGlobalWidgetConfig`).
### `RootWidgetProvider`
App-level provider. Resolves `baseUrl` / `widgetToken` / `organizationId` (falling back to the global store), calls the widget init endpoint once a base URL and token both resolve, and shares the response with every descendant.
#### Props
| Prop | Type | Description |
| ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl` | `string` | Base URL of the Tesouro embedded API (e.g. `"https://api.tesouro.com"`). Falls back to `global.baseUrl` when omitted. |
| `widgetToken` | `string \| null` | Bearer token for widget auth. Falls back to `global.widgetToken` when omitted. Pass `null` to suppress auth. |
| `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). |
| `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`. |
| `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`. |
| `linkComponent` | `LinkComponent` | Host link component widgets use to render navigational links. Falls back to `global.linkComponent`. |
| `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. |
| `implementation` | `'native' \| 'monite' \| null` | Which implementation the widgets render with for this tree. Falls back to `global.implementation`, then to `'native'`. See Implementation selection. |
| `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. |
| `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. |
| `disclosuresAcceptance` | `ReactNode` | Accept surface shown when an ACTIVE user owes a new disclosure version. Pass `` with no invite credentials. Cascades to nested providers. Omit for INVITED — that path still uses invite-link `invitationToken` / `userId` on the host landing page. |
| `children` | `ReactNode` | The React subtree that consumes the widget context. |
### `WidgetProvider`
Mid-tree or standalone provider. With no props it is a transparent pass-through that inherits everything from its parent; set `baseUrl` or `widgetToken` and it fetches its own init response for that subtree; with no provider ancestor it behaves as a standalone root — the right pattern for a single embedded widget.
#### Props
| Prop | Type | Description |
| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl` | `string` | Override the base URL for this subtree. Recreates the HTTP client. When omitted, inherits from the nearest ancestor. |
| `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. |
| `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). |
| `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. |
| `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. |
| `linkComponent` | `LinkComponent` | Override the host link component for this subtree. When omitted, inherits from parent. |
| `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. |
| `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. |
| `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. |
| `onError` | `(error: unknown, info: ErrorInfo) => void` | Optional telemetry hook. Runs once per caught error before the fallback renders. |
| `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. |
| `disclosuresAcceptance` | `ReactNode` | Accept surface shown when an ACTIVE user owes a new disclosure version. Pass `` with no invite credentials. When omitted, inherits from the nearest ancestor. |
| `children` | `ReactNode` | The React subtree that consumes the overridden context. |
### `WidgetTokenRefreshProvider`
Owns the token-refresh lifecycle: calls your `fetcher`, proactively refreshes before expiry, and exposes the live token via `useWidgetToken()` to feed into a `RootWidgetProvider`.
#### Props
| Prop | Type | Default | Description |
| ------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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. |
| `leadSeconds` | `number` | `60` | Schedule the next refresh `leadSeconds` before `exp`. Lower this if your tokens have a very short lifetime. |
| `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. |
| `children` | `ReactNode` | — | The React subtree that consumes the manager via `useWidgetToken()`. |
### `RefreshingRootWidgetProvider`
Bundles `WidgetTokenRefreshProvider` + `RootWidgetProvider` and wires the live token through automatically — the recommended one-provider setup. Takes the `RootWidgetProvider` props (minus `widgetToken`) plus the refresh provider’s.
#### Props
| Prop | Source | Notes |
| ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `baseUrl` | `RootWidgetProvider` | Falls back to the global store when omitted. |
| `organizationId` | `RootWidgetProvider` | Pass `null` to clear the org scope; falls back to the global store when omitted. |
| `configClient` | `RootWidgetProvider` | Optional post-creation hook for the scoped HTTP client. |
| `gatewayRouting` | `RootWidgetProvider` | Overrides widget-gateway routing; unset, it applies per request when the request origin is a known Tesouro API host. |
| `linkComponent` | `RootWidgetProvider` | Component used in place of plain `` tags inside widgets. |
| `uiFramework` | `RootWidgetProvider` | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade. |
| `implementation` | `RootWidgetProvider` | `'native'` (default) or `'monite'`; inherits down the provider cascade. |
| `analytics` | `RootWidgetProvider` | Enables anonymous analytics (default `true`); set `false` to disable capture. |
| `unstable_initResponseOverride` | `RootWidgetProvider` | First-party hosts only. Skips the gateway init fetch and supplies host-authored identity for the subtree. |
| `disclosuresAcceptance` | `RootWidgetProvider` | Accept surface for an ACTIVE user who owes a new disclosure version. Cascades to nested providers. |
| `fetcher` | `WidgetTokenRefreshProvider` | Required. |
| `leadSeconds` | `WidgetTokenRefreshProvider` | Default `60`. |
| `onToken` | `WidgetTokenRefreshProvider` | Fires once per distinct token; useful for telemetry, persistence, or — for non-React hosts — mirroring the token via `updateGlobalWidgetConfig`. |
| `children` | — | Render inside both providers' contexts (so `useWidgetToken()` and `useWidgetConfig()` both work in descendants). |
## Components
Every widget below also accepts the shared auth/scope props from
`WidgetProviderProps` (see [Providers](#providers)), so it can inherit config
from a parent provider or take it directly. Only each widget’s own props are
listed here.
### AcceptDisclosuresWidget
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.
**Two flows, one surface.** In the **pre-auth invite flow**, pass `invitationToken` and `userId` from the invite link. For an **already-active user who owes a re-acceptance** — a new disclosure version was published, so widget init reports `disclosuresRequired: 'REQUIRED'` with `disclosuresAccepted: false` — pass neither: they hold no invite, and the widget token identifies them on both calls. Read those two init fields rather than `status` to decide whether to mount this widget, because an active user can owe an acceptance while never being invited again.
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. When you pass the invite credential, the disclosures lookup can reject a revoked/expired invite before activation. The accept is one transaction: it activates the invitee 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`. In the invite flow, the host passes `invitationToken` and `userId` from the invite link; this widget does not read URL search params.
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.
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.
#### Props
| Prop | Type | Default | Description |
| ----------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `invitationToken` | `string` | `undefined` | Invitation token from the invite link (`code` query param). Bound into the disclosures lookup before activation. |
| `userId` | `string` | `undefined` | Invited user id from the invite link (`userId` query param). Paired with `invitationToken`. |
| Prop | Type | Default | Description |
| ----------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labels` | `Partial` | — | 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. |
| `onAccepted` | `() => void \| Promise` | — | Called after the atomic accept succeeds and before init refresh; awaited before the widget locks. Reject to surface an error and keep Accept retryable. |
| `disclosureLinks` | `AcceptDisclosuresLinks` | — | **Deprecated.** Ignored. Documents come from `GET /identity/v1/disclosures`. Kept so existing hosts continue to typecheck until a breaking release. |
### BankAccountsWidget
A self-contained banking widget for listing Tesouro bank accounts, creating an account with team access, and viewing account details.
#### Props
| Prop | Type | Default | Description |
| --------------------------- | ------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `isBankingTaglineVisible` | `boolean` | `true` | Shows the banking tagline under the page title. |
| `bankLogoSrc` | `string` | `undefined` | Bank logo for the tagline row. Omit and the row shows the bank name alone. |
| `bankLogoAlt` | `string` | `undefined` | Alt text when `bankLogoSrc` is set. |
| `depositAgreementUrl` | `string` | `undefined` | Deposit-agreement PDF linked from the create-account legal copy. Omit and the clause naming it is not rendered. |
| `bankAddress` | `string` | `undefined` | Bank postal address shown in the account-details domestic wire panel. |
| `supportTeamUrl` | `string` | `undefined` | Support URL linked from the account-details domestic wire copy. |
| `labels` | `Partial` | English labels | Overrides list/create-account UI copy. |
| `accountDetailsLabels` | `Partial` | English labels | Overrides the internal account details UI copy. |
| `featureLabels` | `Partial` | English labels | Overrides feature-level copy (account fallback name, create/edit/copy toasts, and account-details export toasts). |
| `data-testid` | `string` | `undefined` | Optional test id forwarded to the widget root. |
| `selectedAccountId` | `string \| null` | `undefined` | Controls the open details account. |
| `defaultSelectedAccountId` | `string \| null` | `undefined` | Initial uncontrolled details account. |
| `onSelectedAccountIdChange` | `(id: string \| null) => void` | `undefined` | Called when the user opens details or goes back. |
### BillPayWidget
A Monite-backed bill pay widget wrapped in Tesouro widget auth and theming.
#### Props
| Prop | Type | Default | Description |
| -------------------- | ------------------------------------ | ------------ | ----------------------------------------------- |
| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Pass-through | Customizes Monite's page title action region. |
| `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Optional Monite theme color overrides. |
### CardsWidget
One page of an organization's credit **or** 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. On a debit list with `cardArtSrc`, Create card opens the same sheet with the built-in debit issuance flow.
#### Props
| Prop | Type | Default | Description |
| -------------------------- | --------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardProgram` | `'credit' \| 'debit'` | **Required** | Which issuing program the list shows. Also selects the scopes that gate each affordance. |
| `pagination` | `{ paginationToken?, pageSize? }` | `undefined` | Controlled cursor and page size. Supply with `onPaginationChange` when your app owns the list position. |
| `defaultPagination` | `{ paginationToken?, pageSize? }` | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied. |
| `onPaginationChange` | `(pagination) => void` | `undefined` | Called whenever the widget moves page or changes page size. Persist the whole object, not the token alone. |
| `labels` | `PartialDeep` | English labels | Overrides the copy of the list screen, including the details sheet's screen-reader name under `detailsSheet` and the create sheet's under `createSheet`. Nested groups merge per group. |
| `featureLabels` | `PartialDeep` | English labels | Overrides the copy this widget resolves rather than passes through — status and form-factor vocabulary, the empty-cell placeholder, and name fallbacks. |
| `selectedCardId` | `string \| null` | `undefined` | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. See **Selection** below. |
| `defaultSelectedCardId` | `string \| null` | `undefined` | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied. |
| `onSelectedCardIdChange` | `(cardId: string \| null) => void` | `undefined` | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders. |
| `cardDetailsLabels` | `PartialDeep` | English labels | Label overrides forwarded into the details panel. |
| `cardDetailsFeatureLabels` | `PartialDeep` | 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`. |
| `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. |
| `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. |
| `cardArtSrc` | `string` | `undefined` | Plastic art for the built-in debit create sheet. Required for that sheet: omit it (with no `onCreateCard`) and Create card is hidden. See **Create card** below. |
| `createCardLabels` | `PartialDeep` | English labels | Label overrides forwarded into the nested create-card panel. |
| `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. |
| `onCreateCard` | `() => void` | `undefined` | Host-owned Create card handler. When supplied, the built-in debit sheet does not open. Credit Create card still requires this callback. |
| `onActivateCard` | `(cardId: string) => void` | `undefined` | Called when a row's Activate button is clicked. Omit it and the button is not rendered. |
### CardDetailsWidget
Read-only details for one credit **or** debit card — status, form factor, program, masked card number, and copyable cardholder and nickname rows. 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.
#### Props
| Prop | Type | Default | Description |
| ---------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardId` | `string` | **Required** | Id of the card to show. |
| `cardProgram` | `'credit' \| 'debit'` | **Required** | Which issuing program `cardId` belongs to. Selects the endpoint the card is fetched from. |
| `onClose` | `() => void` | `undefined` | Called when the header's close control is pressed. Omit it and no close control is rendered at all. |
| `labels` | `PartialDeep` | English labels | Overrides the panel's own copy — header, card face alt text, row headings, copy-button accessible names, and the loading/error/not-found screens. |
| `featureLabels` | `PartialDeep` | English labels | Overrides the copy this widget resolves rather than passes through — status, form-factor and program vocabulary, plus the copy-success toast. |
| `bankLogoSrc` | `string` | `undefined` | Bank logo for the card face. Omit and the face renders without a logo rather than with a placeholder. |
| `bankLogoAlt` | `string` | `undefined` | Alt text for `bankLogoSrc`. Falls back to `labels.cardFace.bankLogoAlt`. |
### CreateCardWidget
Issues a new **debit** card for an enrolled team member: cardholder, format
(virtual / physical), funding bank account, and — for physical cards — a mailing
destination. Loading, success, and error feedback use both full-screen views and
sonner toasts.
#### Props
| Prop | Type | Default | Description |
| --------------- | ------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `cardArtSrc` | `string` | **Required** | Static card plastic image URL (no name overlays). |
| `labels` | `PartialDeep` | English labels | Overrides presentational copy (header, setup, mailing, preparing, success, footer). Nested groups merge per group. |
| `featureLabels` | toast / untitled-funding overrides | English labels | Overrides mutation toast strings and the funding-account fallback name. |
| `className` | `string` | — | Optional class on the presentational root. |
| `onClose` | `() => void` | — | Header close control. Omit and no close control is rendered. |
| `onCancel` | `() => void` | — | Called when Cancel is pressed (also invokes `onClose` when both are set). |
| `onViewCard` | `(cardId: string) => void` | — | Called with the new debit card id after a successful create when the user presses **View card**. |
### CounterpartsWidget
A self-contained widget for managing an organization's customers or vendors with searchable lists, money columns, details, editing, and deletion.
#### Props
| Prop | Type | Default | Description |
| -------------------- | ------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `counterpartType` | `'customer' \| 'vendor'` | — | Required. Selects receivables/customer copy and queries or payables/vendor copy and queries. |
| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size choices shown by the table. |
| `showTitle` | `boolean` | `true` | Whether to render the screen title row. Pass `false` when the embedding surface already titles this screen; the create action then moves into the search row. |
| `onViewAllDocuments` | `() => void` | `undefined` | Reveals a "View all" action beside the recent-bills/invoices heading in the details sheet. Omit when the host has no document list to navigate to; the action stays hidden rather than dead. |
| Prop | Type | Description |
| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `screenLabels` | `Partial` | Table title, columns, search/filter, empty, error, access-restricted, and row-action copy. |
| `formLabels` | `Partial` | Create/edit counterpart form copy. |
| `detailsLabels` | `Partial` | Details sheet sections, summary labels, subtitle/entity/reminder/payment-method labels, row labels, and actions. |
| `bankAccountLabels` | `Partial` | Vendor payment-method form copy. |
| `addressLabels` | `Partial` | Address form copy. |
| `deleteLabels` | `Partial` | Delete-dialog copy. |
| `messageLabels` | `Partial` | Validation, API failure, and delete-prompt messages produced by feature logic. |
### ExpenseManagementWidget
A composite expense widget for receipt upload, matching slots, approval policies, and transaction requirements.
#### Props
| Prop | Type | Default | Description |
| --------------------- | -------------------------- | ------------------------ | -------------------------------------------------- |
| `labels` | `Partial` | English labels | Overrides tab and heading copy. |
| `receiptUpload` | `UploadReceiptWidgetProps` | `undefined` | Enables the default receipt upload control. |
| `receiptsContent` | `ReactNode` | Upload widget or empty | Replaces the receipts tab content. |
| `matchingContent` | `ReactNode` | Empty | Supplies host-owned matching UI without URL state. |
| `policiesContent` | `ReactNode` | Approval policies widget | Replaces the policies tab content. |
| `requirementsContent` | `ReactNode` | Requirements widget | Replaces the requirements tab content. |
### ExpenseApprovalPoliciesWidget
Lets an organization view and manage its expense approval rules — each rule maps an amount range to an outcome (auto-approve or require approval) and, where approval is required, the approving roles. It is backed by the embedded REST API.
#### Props
_No props beyond the shared [auth/scope props](#providers)._
### ExpenseRequirementsWidget
An editable settings surface for an organization's transaction validation rules. It lets an admin toggle whether a receipt and a description/memo are required on expenses, set per-field amount thresholds, and save the changes back to the embedded REST API.
#### Props
_No props beyond the shared [auth/scope props](#providers)._
### BalancesWidget
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.
#### Props
| Prop | Type | Default | Description |
| ------------------------ | ------------------------------- | ------- | --------------------------------------------------------------------------- |
| `maxAccounts` | `number` | `5` | Maximum rows rendered in-card; additional accounts use the view-all CTA. |
| `labels` | `Partial` | — | Override shell copy (title, errors, view-all label, total balance tooltip). |
| `onBalanceRowClick` | `(accountId: string) => void` | — | When set, balance rows are clickable and receive the account id. |
| `onViewAllAccountsClick` | `() => void` | — | When set and more than `maxAccounts` exist, shows **View all accounts**. |
### InsightsWidget
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.
#### Props
| Prop | Type | Default | Description |
| ---------------------------- | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `routingEnabled` | `boolean` | `false` | Controlled switch state for the routing onboarding insight. |
| `onRoutingToggleChange` | `(enabled: boolean) => void` | — | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. |
| `onLinkExternalAccountClick` | `() => void` | — | When set, the connect-external-account insight shows a **Link account** CTA. |
| `labels` | `Partial` | — | Shell copy (tabs, empty, error). |
| `singleInsightLabels` | `Partial` | — | Per-row UI strings (e.g. dismiss aria label). |
| `featureLabels` | `Partial` | — | Generated insight body copy and action labels. |
### ChartOfAccountsWidget
A self-contained widget that renders an organization's chart of accounts: a paginated, sortable table of ledger accounts with built-in create, edit, and delete. It handles its own API communication, loading and error states, server-side sorting, and cursor-based pagination. The host application only needs to supply auth credentials and optional UI callbacks.
#### Props
| Prop | Type | Description |
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `title` | `string` | Overrides the built-in "Chart of accounts" heading. Pass an empty string to suppress it when the host renders its own. |
| `onEdit` | `(row: LedgerAccountRow) => void` | Overrides the built-in edit flow. Not offered on externally-synced rows (`is_external`), which the API refuses to update. |
| `onDelete` | `(row: LedgerAccountRow) => void` | Overrides the built-in delete flow. Not offered on externally-synced rows (`is_external`), which the API refuses to delete. |
| `onAdd` | `() => void` | Overrides the built-in create flow. Omit it to use the widget's own create sheet. |
| Prop | Type | Covers |
| --------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| `screenLabels` | `Partial` | Table copy: heading, column headers, row actions, sort control, empty/error states. |
| `formLabels` | `Partial` | Create/edit sheet: titles, field labels, placeholders, counter, buttons, menu. |
| `deleteLabels` | `Partial` | Delete confirmation: title, message, buttons. |
| `messageLabels` | `Partial` | Validation messages, save/delete failure fallbacks, and success toasts. |
### HelpWidget
A self-contained Help widget: a static FAQ accordion with an optional "Contact Us" card. It renders no network requests — all content comes from props, defaulting to the built-in English FAQ so the widget works with no configuration.
#### Props
| Prop | Type | Default | Description |
| ------------ | --------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `faq` | `HelpFaqSection[]` | `HELP_FAQ_EN` | FAQ content to render, grouped into titled sections. |
| `bankName` | `string` | `initResponse.bankName` | Bank/provider name interpolated into the contact line. Defaults to the bank resolved by widget init; pass this only to override it. |
| `contactUrl` | `string` | `undefined` | When set, renders a "Contact Us" card linking here. Omit to hide it. The card also needs a bank name, so it appears once widget init resolves. |
| `labels` | `Partial` | `HELP_WIDGET_LABELS_EN` | Display-string overrides, merged over `HELP_WIDGET_LABELS_EN` (FAQ + contact copy). |
### InvoicingWidget
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.
#### Props
| Prop | Type | Default | Description |
| -------------------- | ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Overrides the Monite theme's primary colors. Omit to use Monite defaults. |
| `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}". |
| `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. |
### LinkedAccountsWidget
A self-contained widget that lists and manages external bank accounts, including connect, edit, micro-deposit initiation, micro-deposit validation, and unlink actions.
#### Props
| Prop | Type | Default | Description |
| --------------- | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labels` | `Partial` | English labels | Overrides visible UI copy such as button, dialog, empty-state, loading, and error labels. Unspecified labels fall back to defaults. |
| `featureLabels` | `Partial` | 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. |
### BankAccountOnboardingWidget
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.
#### Props
| Prop | Type | Required | Description |
| ------------------------------------------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onEmbeddedOnboardingCompletedSuccessfully` | `() => void` | Yes | Called when the application is submitted and approved. |
| `onNavigateToDashboard` | `() => void` | Yes | Called when the user clicks the dashboard CTA on the result screen. |
| `initialBusinessDetails` | `Partial` | No | Prefills step 1 (business details). Unset fields start empty; the user can still edit before continuing. |
| `initialPersonalDetails` | `Partial` | No | Prefills step 2 (personal / about-you details). Unset fields start empty; the user can still edit before continuing. |
| `initialAdditionalOwners` | `AdditionalOwner[]` | No | Prefills step 3 (additional owners). Defaults to an empty list when omitted. |
| `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. |
| `defaultOpen` | `boolean` | No | Initial open state when uncontrolled. Defaults to `false` so the modal stays closed until the host or marketing CTA opens it. Ignored when `open` is set. |
| `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. |
| `labels` | `BankAccountOnboardingWidgetLabels` | No | Per-step label overrides — see Labels section. Accepts a `modalTitle` override for the modal's accessible title (default: `Bank account onboarding`). |
| `bankLogoSrc` | `string` | No | URL for the bank logo rendered on the result screen; falls back to bank name text. |
| `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. |
| `marketingContent` | `MarketingWidgetContent \| null` | No | Host-resolved marketing card/modal content. When omitted or `null`, the marketing surface is not rendered. |
### ProductsWidget
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.
#### Props
| Prop | Type | Description |
| ------------------------- | ---------------------------------------- | ---------------------------------------------------- |
| `pageSizeOptions` | `number[]` | Rows-per-page choices (default `[10, 25, 50, 100]`). |
| `screenLabels` | `Partial` | Table/header/filter/empty/error copy. |
| `formLabels` | `Partial` | Create/edit form copy. |
| `detailsLabels` | `Partial` | Details sheet copy. |
| `deleteLabels` | `Partial` | Product delete confirmation copy. |
| `measureUnitsLabels` | `Partial` | Measure-units manager copy. |
| `measureUnitDeleteLabels` | `Partial` | Measure-unit delete confirmation copy. |
| `messageLabels` | `Partial` | Validation / error messages produced by the widget. |
### ProfileWidget
A self-contained, read-only profile card for the current entity user. It shows a personal tab (name, email, phone) and a business tab (legal name, company address, company phone, company email) backed by the embedded REST API.
#### Props
| Prop | Type | Description |
| --------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `labels` | `Partial` | Overrides the card's own copy (loading announcement, contact line). |
| `featureLabels` | `Partial` | Overrides tab labels, field labels, and the subtitle. |
| `contactUrl` | `string` | Where the "to change this information, contact your bank" line links (a support page URL or a `mailto:`). Left unset, the card shows the plain unlinked subtitle instead. The bank name in that line comes from widget init, so no other value is needed. |
### ReceivablesWidget
A self-contained native widget for listing, creating, editing, and acting on customer receivables.
#### Props
| Prop | Type | Default | Description |
| ------------------------- | ---------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `defaultTab` | `ReceivablesWidgetTab` | `'invoices'` | Initial tab when that tab is enabled. If it is omitted or disabled, the widget starts on the first enabled tab. |
| `enabledTabs` | `ReceivablesWidgetTab[]` | `['invoices', 'quotes', 'credit_notes']` | Tabs visible to the user. Duplicate or unknown values are ignored. |
| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Rows-per-page choices shown by the table. The first page loads with a page size of `10`. |
| `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. |
| `onReceivableOpened` | `(id: string, type: ReceivableDocumentType) => void` | `undefined` | Called when the user opens a row's detail sheet. |
| `onTemplateSettingsClick` | `() => void` | `undefined` | Shows a template settings action in the header and calls this handler when selected. |
| Prop | Type | Default | Description |
| -------------------------- | ---------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `screenLabels` | `Partial` | English defaults | Overrides table, tab, filter, empty, error, action, and status badge copy. |
| `formLabels` | `Partial` | English defaults | Overrides create/edit form labels and button copy. |
| `detailsLabels` | `Partial` | English defaults | Overrides detail sheet headings, actions, empty copy, and status badge copy. |
| `sendLabels` | `Partial` | English defaults | Overrides send-email dialog labels and buttons. |
| `paymentLabels` | `Partial` | English defaults | Overrides manual payment dialog labels and buttons. |
| `actionLabels` | `Partial` | English defaults | Overrides generic confirmation dialog buttons. Action-specific title and body copy come from `messageLabels`. |
| `productFormLabels` | `Partial` | English defaults | Overrides inline product creation copy from the shared product catalog flow. |
| `counterpartFormLabels` | `Partial` | English defaults | Overrides inline customer creation copy from the shared counterpart-management flow. |
| `measureUnitsLabels` | `Partial` | English defaults | Overrides measure-unit manager copy used by the product creation flow. |
| `measureUnitDeleteLabels` | `Partial` | English defaults | Overrides measure-unit delete confirmation copy. |
| `messageLabels` | `Partial` | English defaults | Overrides validation, fallback, summary, activity, and action-confirmation messages generated by the feature layer. |
| `productMessageLabels` | `Partial` | English defaults | Overrides product flow validation and error messages. |
| `counterpartMessageLabels` | `Partial` | English defaults | Overrides customer flow validation and error messages. |
### ReceiptMatchWidget
A slide-out wizard for attaching uploaded receipts to bank-card transactions. It lists the signed-in user's unmatched receipts, lets them pick a transaction per receipt, and persists each match against the embedded REST API.
#### Props
| Prop | Type | Default | Description |
| --------------------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isOpen` | `boolean` | `false` | Controls sidebar visibility. The widget renders `null` while falsy and opens when true; it also closes itself when a flow finishes. |
| `onClose` | `() => void` | `undefined` | Called on every dismissal (Done, attach, Esc, overlay). Provide it to keep your `isOpen` state in sync — the widget still self-closes if omitted. |
| `preSelectedReceiptIds` | `string[]` | `[]` | Receipt ids checked when the wizard opens, seeding the batch selection. |
| `targetTransactionId` | `string` | `undefined` | Attach mode: when set, the user picks one receipt and it is attached directly to this transaction (single-select, no transaction-search step). |
| `onSingleTransactionUpdate` | `() => void` | `undefined` | Called after a successful attach in `targetTransactionId` mode, before the widget closes. Use to refresh the host's view of that transaction. |
### SettingsWidget
A composite settings widget that combines Monite document settings, tags, GL codes, and expense configuration.
#### Props
| Prop | Type | Default | Description |
| ------------------------- | -------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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). |
| `labels` | `Partial` | English labels | Overrides the settings heading copy. |
| `featureLabels` | `Partial` | English labels | Overrides section labels. |
| `profileContent` | `ReactNode` | Profile widget | Replaces the profile section content. |
| `teamContent` | `ReactNode` | Empty | Supplies the team section content. |
| `invoiceContent` | `ReactNode` | Monite template settings | Replaces invoice settings content. |
| `billPayContent` | `ReactNode` | Monite approval policies | Replaces bill-pay settings content. |
| `accountingContent` | `ReactNode` | GL code table widget | Replaces accounting content. |
| `tagsContent` | `ReactNode` | Monite tags | Replaces tags content. |
| `expenseContent` | `ReactNode` | Expense policies and requirements | Replaces expense content. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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. |
| `helpContent` | `ReactNode` | Help widget | Replaces the help section content. |
| `finopsThemeColors` | `FinopsThemeColors` | `undefined` | Optional Monite theme color overrides. |
### TagsWidget
A self-contained widget for managing an organization's tags: it lists tags in a sortable, cursor-paginated table and handles creating, editing, and deleting them — including each tag's OCR auto-tagging keywords. The host only supplies auth credentials and optional label overrides.
#### Props
| Prop | Type | Default | Description |
| ----------------- | -------------------------------- | ------------------- | ------------------------------------------------------------------------- |
| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Choices in the rows-per-page selector. |
| `screenLabels` | `Partial` | `undefined` | Override table/header/empty/error copy. Merged over the English defaults. |
| `formLabels` | `Partial` | `undefined` | Override create/edit form copy. |
| `deleteLabels` | `Partial` | `undefined` | Override delete-confirmation copy. |
| `messageLabels` | `Partial` | `undefined` | Override validation / submit-error messages. |
### TeamWidget
A self-contained team management surface for embedded integrators. It lists organization members in a paginated table and, when the widget token carries the appropriate write scopes, enables inviting new members, editing a member's name and role, and deactivating a member.
#### Props
| Prop | Type | Description |
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title` | `string` | Optional page heading rendered above the team table. Omit when the host already provides its own title. |
| `labels` | `Partial` | Overrides table, detail, invite, edit, and dialog UI copy. |
| `featureLabels` | `Partial` | Overrides role display names, validation messages, and deactivate confirmation copy. |
| `acceptInviteRedirectUri` | `string` | Allowlisted URL invite/resend 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). |
### TransfersWidget
A self-contained banking widget for creating book or ACH transfers and reviewing recent movement across embedded accounts.
#### Props
| Prop | Type | Default | Description |
| --------------- | --------------------------------------- | ---------------- | --------------------------------------------------------------------- |
| `labels` | `Partial` | English labels | Override shell and modal copy. |
| `featureLabels` | `Partial` | English defaults | Override routing copy, fallbacks, default currency, and ACH SEC code. |
### UploadReceiptWidget
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.
_Standalone presentational widget — it does not take the shared auth/scope props._
#### Props
| Prop | Type | Default | Description |
| ----------------- | --------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `emailAddress` | `string` | _required_ | Forwarding email address shown in the popover with a copy button; receipts emailed here are processed automatically. |
| `onFileUpload` | `(file: File) => unknown \| Promise` | `undefined` | Called once per selected file. The widget awaits each call and counts resolutions vs. rejections to drive its toasts. Omit to disable uploading. |
| `onAwaitMatching` | `(uploadedCount: number) => Promise` | `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. |
| `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. |
## UI frameworks (shadcn default, Tecton optional)
Widgets render with the default shadcn/native surface out of the box — no extra
install, no configuration. An alternate UI framework (Tecton, built on the Q2 /
Stencil design system) is shipped as a **separate, opt-in package** so the core
package never carries Stencil or its build-time/runtime weight:
```bash
npm i @tesouro/embedded-components-react-tecton-ui
```
```ts
import { registerTectonUI } from '@tesouro/embedded-components-react-tecton-ui';
registerTectonUI(); // once, at app startup
```
Then select it via the provider cascade (`uiFramework="tecton"`). Without the
extension installed, `uiFramework="tecton"` degrades gracefully to shadcn. See
the extension's README for setup, the migration guide, and the Turbopack /
`@stencil/core` note that applies only when the Tecton extension is installed.
### TypeScript module resolution
This package ships ESM with TypeScript declarations and is intended for
**bundler-based** consumers — Vite, webpack, esbuild, Next.js — which is how
React apps are built. Its types are exposed through the package `exports` map, so
set TypeScript's `"moduleResolution"` to **`"bundler"`** (the modern default) and
every entrypoint (`.`, `./core`, `./monite-sdk`, `./lib/*`, `./experimental`,
`./experimental/*`) resolves cleanly.
The published declarations are **self-contained**: the build bundles each
entrypoint's `.d.ts` (`scripts/bundle-dts.mjs`) so it inlines the internal
workspace types instead of re-exporting them from unpublished `@tesouro-fe/*`
packages, and only genuine dependencies (react, MUI, …) remain as bare imports.
An ESM consumer therefore type-checks cleanly under `"bundler"` **and**
`"node16"` / `"nodenext"`, even with `skipLibCheck: false`.
Legacy `"moduleResolution": "node"` (a.k.a. `node10` / classic) is **not
supported**: it ignores the `exports` map, and this package carries no top-level
`types` field, so the type checker reports `TS2307` for the package and its
subpaths. Use `"bundler"` instead — every bundler-based toolchain supports it.
As an ESM-only package it is not `require()`-able from CommonJS.
## Contributing
Maintainer notes — the monorepo build/publishing model, the publish-verification
gate, and how to run the unit tests — live in `CONTRIBUTING.md` in the source
repository.