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.

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:

import '@tesouro/embedded-components-react/styles.css';

Then render a widget inside a provider that establishes its authenticated scope:

import '@tesouro/embedded-components-react/styles.css';
import {
  RootWidgetProvider,
  BankAccountsWidget,
} from '@tesouro/embedded-components-react';

export function App() {
  return (
    <RootWidgetProvider
      baseUrl="https://api.tesouro.com"
      widgetToken="wt_live_…"
      organizationId="org_…"
    >
      <BankAccountsWidget />
    </RootWidgetProvider>
  );
}

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. | | @tesouro/embedded-components-react/core | Framework-agnostic token utilities (createWidgetTokenManager). | | @tesouro/embedded-components-react/monite-sdk | Monite SDK surface for Monite-backed widgets. |

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 interceptor. Falls back to global.configClient. | | 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. | | 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. | | 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. | | 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. | | linkComponent | RootWidgetProvider | Component used in place of plain <a> 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. | | 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), so it can inherit config from a parent provider or take it directly. Only each widget’s own props are listed here.

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 | Optional bank logo for the tagline row. | | bankLogoAlt | string | undefined | Alt text when bankLogoSrc is set. | | labels | Partial<BankAccountsWidgetLabels> | English labels | Overrides list/create-account UI copy. | | accountDetailsLabels | Partial<AccountDetailsWidgetLabels> | English labels | Overrides the internal account details UI copy. | | featureLabels | Partial<BankAccountsWidgetFeatureLabels> | English labels | Overrides feature-level copy (account fallback name, toasts, balance formatting). | | 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. |

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. |

| Prop | Type | Description | | ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | screenLabels | Partial<CounterpartsScreenLabels> | Table title, columns, search/filter, empty, error, access-restricted, and row-action copy. | | formLabels | Partial<CounterpartFormSheetLabels> | Create/edit counterpart form copy. | | detailsLabels | Partial<CounterpartDetailsSheetLabels> | Details sheet sections, summary labels, subtitle/entity/reminder/payment-method labels, row labels, and actions. | | bankAccountLabels | Partial<BankAccountFormSheetLabels> | Vendor payment-method form copy. | | addressLabels | Partial<AddressFormSheetLabels> | Address form copy. | | deleteLabels | Partial<ConfirmDeleteDialogLabels> | Delete-dialog copy. | | messageLabels | Partial<CounterpartMessageLabels> | 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<Labels> | 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.

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.

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<BalancesWidgetLabels> | — | 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<InsightsWidgetLabels> | — | Shell copy (tabs, empty, error). | | singleInsightLabels | Partial<SingleInsightLabels> | — | Per-row UI strings (e.g. dismiss aria label). | | featureLabels | Partial<InsightsFeatureLabels> | — | Generated insight body copy and action labels. |

GLCodeTableWidget

A self-contained widget that fetches and displays a paginated, sortable table of General Ledger (GL) codes. 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 | | ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | labels | Partial<GlCodeTableLabels> | Override any subset of UI strings (column headers, action labels, empty/error state copy). Merged with the English defaults. | | onEdit | (row: GlCode) => void | When provided, adds an Edit action to the row dropdown menu. | | onDelete | (row: GlCode) => void | When provided, adds a Delete action to the row dropdown menu. | | onAddIntegration | () => void | Renders an Add integration button in the empty state. | | onImportCsv | () => void | Renders an Import CSV button in the empty state. | | learnMoreHref | string | Renders a Learn more link in the empty state. |

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 | undefined | Bank/provider name interpolated into the contact line. | | contactUrl | string | undefined | When set, renders a "Contact Us" card linking here. Omit to hide it. | | labels | Partial<HelpWidgetLabels> | 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. | | 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<LinkedAccountsWidgetLabels> | English labels | Overrides visible UI copy such as button, dialog, empty-state, loading, and error labels. Unspecified labels fall back to defaults. | | 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. |

OnboardingWidget

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. | | 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 true so the modal renders on mount. 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 | OnboardingWidgetLabels | 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. | | termsHref | string | No | URL for the Terms of Use document linked in step 1. | | privacyHref | string | No | URL for the Privacy Policy document linked in step 1. | | electronicCommunicationHref | string | No | URL for the Electronic Communication document linked in step 1. | | patriotActHref | string | No | URL for the Patriot Act document linked in step 1. |

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<ProductsScreenLabels> | Table/header/filter/empty/error copy. | | formLabels | Partial<ProductFormSheetLabels> | Create/edit form copy. | | detailsLabels | Partial<ProductDetailsSheetLabels> | Details sheet copy. | | deleteLabels | Partial<ProductDeleteDialogLabels> | Product delete confirmation copy. | | measureUnitsLabels | Partial<MeasureUnitsManagerLabels> | Measure-units manager copy. | | measureUnitDeleteLabels | Partial<MeasureUnitDeleteDialogLabels> | Measure-unit delete confirmation copy. | | messageLabels | Partial<ProductMessageLabels> | 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<Labels> | Overrides the card's own copy (loading announcement). | | featureLabels | Partial<FeatureLabels> | Overrides tab labels, field labels, banner alt text, and the subtitle. |

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<ReceivablesScreenLabels> | English defaults | Overrides table, tab, filter, empty, error, action, and status badge copy. | | formLabels | Partial<ReceivableFormSheetLabels> | English defaults | Overrides create/edit form labels and button copy. | | detailsLabels | Partial<ReceivableDetailsSheetLabels> | English defaults | Overrides detail sheet headings, actions, empty copy, and status badge copy. | | sendLabels | Partial<ReceivableSendDialogLabels> | English defaults | Overrides send-email dialog labels and buttons. | | paymentLabels | Partial<ReceivablePaymentDialogLabels> | English defaults | Overrides manual payment dialog labels and buttons. | | actionLabels | Partial<ReceivableActionDialogLabels> | English defaults | Overrides generic confirmation dialog buttons. Action-specific title and body copy come from messageLabels. | | productFormLabels | Partial<ProductFormSheetLabels> | English defaults | Overrides inline product creation copy from the shared product catalog flow. | | counterpartFormLabels | Partial<CounterpartFormSheetLabels> | English defaults | Overrides inline customer creation copy from the shared counterpart-management flow. | | measureUnitsLabels | Partial<MeasureUnitsManagerLabels> | English defaults | Overrides measure-unit manager copy used by the product creation flow. | | measureUnitDeleteLabels | Partial<MeasureUnitDeleteDialogLabels> | English defaults | Overrides measure-unit delete confirmation copy. | | messageLabels | Partial<ReceivableMessageLabels> | English defaults | Overrides validation, fallback, summary, activity, and action-confirmation messages generated by the feature layer. | | productMessageLabels | Partial<ProductMessageLabels> | English defaults | Overrides product flow validation and error messages. | | counterpartMessageLabels | Partial<CounterpartMessageLabels> | 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 | | ------------------- | ------------------------ | --------------------------------- | --------------------------------------------------------- | | labels | Partial<Labels> | English labels | Overrides the settings heading copy. | | featureLabels | Partial<FeatureLabels> | 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. | | 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<TagsScreenLabels> | undefined | Override table/header/empty/error copy. Merged over the English defaults. | | formLabels | Partial<TagFormSheetLabels> | undefined | Override create/edit form copy. | | deleteLabels | Partial<TagDeleteDialogLabels> | undefined | Override delete-confirmation copy. | | messageLabels | Partial<TagMessageLabels> | 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<TeamWidgetLabels> | Overrides table, detail, invite, edit, and dialog UI copy. | | featureLabels | Partial<TeamWidgetFeatureLabels> | Overrides role display names, validation messages, and deactivate confirmation copy. |

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<TransfersWidgetLabels> | English labels | Override shell and modal copy. | | featureLabels | Partial<TransfersWidgetFeatureLabels> | 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<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. | | 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:

npm i @tesouro/embedded-components-react-tecton-ui

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/*) 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.