@tesouro/embedded-components-react 0.2.206 → 0.2.211

package/README.md

@@ -207,6 +207,46 @@ A Monite-backed bill pay widget wrapped in Tesouro widget auth and theming.
 | `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.
+
+#### 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<CardsWidgetLabels>`        | English labels | Overrides the copy of the list screen, including the details sheet's screen-reader name under `detailsSheet`. Nested groups merge per group.                       |
+| `featureLabels`            | `PartialDeep<CardsWidgetFeatureLabels>` | 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<CardDetailsWidgetLabels>`  | English labels | Label overrides forwarded into the details panel.                                                                                                                  |
+| `cardDetailsFeatureLabels` | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides for the copy the panel's feature layer resolves — status vocabulary, form-factor copy, program label, copy-success toast. Distinct from `featureLabels`. |
+| `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`.                                                                                                                                        |
+| `onCreateCard`             | `() => void`                            | `undefined`    | Called when Create card is clicked. Omit it and the button is not rendered.                                                                                        |
+| `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<CardDetailsWidgetLabels>`  | 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<CardDetailsFeatureLabels>` | 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`.                                                                          |
+
 ### CounterpartsWidget
 
 A self-contained widget for managing an organization's customers or vendors with searchable lists, money columns, details, editing, and deletion.