npm - @justifi/webcomponents - Versions diffs - 6.7.0 → 6.7.2 - Mend

@justifi/webcomponents 6.7.0 → 6.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (167) hide show

package/docs/modular-checkout/sub-components/card-form.mdx ADDED Viewed

@@ -0,0 +1,178 @@
+---
+id: modular-checkout/sub-components/card-form
+title: Card Form
+description: Card entry sub-component for Modular Checkout layouts with shared validation and token orchestration.
+sidebar_position: 2
+---
+import {
+  PropsTable,
+  PartsTable,
+  getWebcomponentsVersion,
+} from '@justifi/webcomponents/docs/helpers';
+## Overview
+Renders a form for collecting credit and debit card details as part of a checkout flow.
+This component is **designed to be used within** the `justifi-modular-checkout` and **does not accept props directly**. Instead, it relies on shared state passed through the Stencil Store, managed by the wrapper component.
+> **Note:** If you are using the card payment method, you also need to provide billing information. This can be done by using either the `justifi-billing-form-full` component for complete billing address, the `justifi-card-billing-form-simple` component for ZIP code only, or by passing the `billingInformation` object as an argument to the `submitCheckout` method called on the wrapper. The `billingInformation` object can contain all the fields or just the `address_postal_code` field.
+**Authorization** and business context are also handled by `justifi-modular-checkout`, which manages authentication tokens and related configuration.
+This component exposes **no public methods or properties** and is not intended for standalone use.
+## Usage
+<pre><code className="language-html">{`<!DOCTYPE html>
+<html dir="ltr" lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+  <title>justifi-card-form</title>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"></script>
+<script
+  nomodule
+  src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.js"
+></script>
+<style>
+  /** These are the available parts for styling the component. */
+  ::part(skeleton){' '}
+  {
+    // skeleton styles
+  }
+  ::part(label){' '}
+  {
+    // label styles
+  }
+  ::part(input-invalid-and-focused){' '}
+  {
+    // input invalid and focused styles
+  }
+  ::part(input-invalid){' '}
+  {
+    // input invalid styles
+  }
+  ::part(input-focused){' '}
+  {
+    // input focused styles
+  }
+  ::part(input){' '}
+  {
+    // input styles
+  }
+</style>
+</head>
+<body>
+  <justifi-modular-checkout auth-token="authToken" checkout-id="ch_123">
+    <justifi-card-form />
+    <button id="submit-button">Submit Checkout</button>
+  </justifi-modular-checkout>
+</body>
+<script>
+  (function() {
+    const checkoutWrapper = document.querySelector('justifi-modular-checkout');
+    const submitButton = document.querySelector('#submit-button');
+    submitButton.addEventListener('click', () => {
+      checkoutWrapper.submitCheckout();
+    });
+    checkoutWrapper.addEventListener('error-event', (event) => {
+      console.error(event.detail);
+    });
+    document.addEventListener('submit-event', (event) => {
+      console.log('Checkout completed successfully!', event.detail);
+    });
+  })();
+</script>
+</html>`}</code></pre>
+## Props, Events & Methods
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'payment-method-group-id',
+        type: 'string',
+        description:
+          'Matches the group configured in the parent checkout to toggle allowed rails.',
+      },
+      {
+        name: 'show-save-payment-method',
+        type: 'boolean',
+        defaultValue: 'true',
+        description:
+          'Displays a checkbox that surfaces the modular checkout save-preference state.',
+      },
+      {
+        name: 'card-brand-icons',
+        type: '"auto" | "none"',
+        defaultValue: 'auto',
+        description: 'Controls whether brand icons display above inputs.',
+      },
+      {
+        name: 'locale',
+        type: 'string',
+        defaultValue: 'en-US',
+        description: 'Overrides localized labels if needed.',
+      },
+    ]),
+  }}
+/>
+### Events
+All submit and error events bubble through the parent `<justifi-modular-checkout>`, so no additional listeners are required on the card form.
+### Public methods
+- `focus()` – moves focus to the iframe representing the current active field (useful for custom UX flows).
+## Theming & Layout
+- When embedded inside cards, wrap the host element in your layout container and scope typography overrides via the parts listed below.
+<div
+  dangerouslySetInnerHTML={{
+    __html: PartsTable([
+      {
+        name: 'skeleton',
+        description: 'Skeleton loading state styles.',
+      },
+      {
+        name: 'label',
+        description: 'Label styles.',
+      },
+      {
+        name: 'input-invalid-and-focused',
+        description: 'Input styles when invalid and focused.',
+      },
+      {
+        name: 'input-invalid',
+        description: 'Input styles when invalid.',
+      },
+      {
+        name: 'input-focused',
+        description: 'Input styles when focused.',
+      },
+      {
+        name: 'input',
+        description: 'Input field styles.',
+      },
+    ]),
+  }}
+/>
+- Use the `card-form` CSS part (`::part(card-form)`) to apply box shadows or wrapper padding.

package/docs/modular-checkout/sub-components/index.mdx ADDED Viewed

@@ -0,0 +1,23 @@
+---
+id: modular-checkout/sub-components/index
+title: Modular Checkout Sub-components
+sidebar_label: Sub-components
+description: Directory of every child element that plugs into the checkout shell.
+---
+Each sub-component inherits authentication context from the parent checkout and
+can be slotted wherever your layout requires. Dive into the dedicated docs for
+implementation details:
+- [Card form](./card-form)
+- [Bank account form](./bank-account-form)
+- [Plaid payment method](./plaid-payment-method)
+- [Sezzle payment method](./sezzle-payment-method)
+- [Apple Pay](./apple-pay)
+- [Saved payment methods](./saved-payment-methods)
+- [Season interruption insurance](./season-interruption-insurance)
+- [Payment method options](./payment-method-options)
+- [Summary](./summary)
+> Looking for additional rails? Duplicate any of these MDX files, adjust the
+> front matter `id`, and follow the existing documentation scaffolding.

package/docs/modular-checkout/sub-components/payment-method-options.mdx ADDED Viewed

@@ -0,0 +1,87 @@
+---
+id: modular-checkout/sub-components/payment-method-options
+title: Payment Method Options
+description: Render-only component that lists available payment rails and lets customers switch between them.
+sidebar_position: 25
+---
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+## Overview
+`<justifi-payment-method-options>` exposes the same selector UI used inside Storybook examples. It pairs well with `<justifi-modular-checkout>` when you need more control over where the payment rail picker appears.
+## Usage
+<pre>
+  <code className="language-html">{`<justifi-payment-method-options
+  selected="card"
+  options='[
+    {"id":"card","label":"Credit or debit card"},
+    {"id":"ach","label":"Bank account"},
+    {"id":"wallet","label":"Digital wallet"}
+  ]'
+></justifi-payment-method-options>`}</code>
+</pre>
+## Props, Events & Methods
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'options',
+        type: 'Array<{ id: string; label: string; description?: string; icon?: string }>',
+        required: true,
+        description: 'List of payment rails to display.',
+      },
+      {
+        name: 'selected',
+        type: 'string',
+        description: 'Currently selected option ID.',
+      },
+      {
+        name: 'display-style',
+        type: '"list" | "tabs" | "cards"',
+        defaultValue: 'list',
+        description: 'Controls the visual layout.',
+      },
+      {
+        name: 'disabled',
+        type: 'boolean',
+        defaultValue: 'false',
+        description:
+          'Prevent users from switching rails (e.g., while submitting).',
+      },
+    ]),
+  }}
+/>
+### Events
+- `selection-changed`: Emits `{ optionId }` whenever customers pick a different rail.
+### Public methods
+1. `select(optionId)` – Programmatically activate a rail.
+## Theming & Layout
+<div
+  dangerouslySetInnerHTML={{
+    __html: PartsTable([
+      {
+        name: 'option',
+        description: 'Individual rail container (card/tab/list row).',
+      },
+      {
+        name: 'option-label',
+        description: 'Typography target for the option label.',
+      },
+      {
+        name: 'option-description',
+        description: 'Secondary text area for additional guidance.',
+      },
+    ]),
+  }}
+/>

package/docs/modular-checkout/sub-components/plaid-payment-method.mdx ADDED Viewed

@@ -0,0 +1,158 @@
+---
+id: modular-checkout/sub-components/plaid-payment-method
+title: Plaid Payment Method
+description: Plaid-powered ACH rail for Modular Checkout with hosted Link flow.
+sidebar_position: 23
+---
+import {
+  PropsTable,
+  PartsTable,
+  getWebcomponentsVersion,
+} from '@justifi/webcomponents/docs/helpers';
+## Overview
+Renders a radio input for selecting the Plaid bank account payment method, and orchestrates the Plaid Link flow to securely connect a bank account when selected.
+This component is designed to be used within the `justifi-modular-checkout` and does not accept props directly. It relies on the shared state and context managed by `justifi-modular-checkout` (auth token, account ID, and checkout ID). Saving a new payment method is controlled via the `justifi-save-new-payment-method` checkbox when a payment method group is available.
+It exposes no public properties for configuration, but does emit Plaid-specific events for error handling and recovery.
+> Note: This component renders nothing and logs a console warning when bank account verification is not enabled for the checkout (`payment_settings.bank_account_verification !== true`).
+## Usage
+<pre><code className="language-html">{`<!DOCTYPE html>
+<html dir="ltr" lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+  <title>justifi-plaid-payment-method</title>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"></script>
+<script
+  nomodule
+  src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.js"
+></script>
+<style>
+  /** These are the available parts for styling the component. */ ::part(text){' '}
+  {/* text styles */}
+  ::part(text-danger) {/* text danger styles */}
+  ::part(label) {/* label styles */}
+  ::part(input-radio) {/* input radio styles */}
+  ::part(input-radio-focused) {/* input radio focused styles */}
+  ::part(input-radio-checked) {/* input radio checked styles */}
+  ::part(input-radio-checked-focused) {/* input radio checked focused styles */}
+  ::part(input-radio-invalid) {/* input radio invalid styles */}
+</style>
+</head>
+<body>
+  <justifi-modular-checkout auth-token="authToken" checkout-id="ch_123">
+    <justifi-plaid-payment-method />
+  </justifi-modular-checkout>
+</body>
+<script>
+  (function() {
+    const modularCheckout = document.querySelector('justifi-modular-checkout');
+    modularCheckout?.addEventListener('plaidError', (event) => {
+      console.warn('Plaid error', event.detail);
+    });
+    modularCheckout?.addEventListener('plaidErrorRecovered', (event) => {
+      console.log('Plaid recovered', event.detail);
+    });
+  })();
+</script>
+</html>`}</code></pre>
+## Props, Events & Methods
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'link-token',
+        type: 'string',
+        required: true,
+        description:
+          'Server-generated Plaid link token scoped to the current customer.',
+      },
+      {
+        name: 'locale',
+        type: 'string',
+        defaultValue: 'en-US',
+        description: 'Pass through to Plaid for language + formatting.',
+      },
+      {
+        name: 'theme',
+        type: '"dark" | "light"',
+        defaultValue: 'dark',
+        description: 'Controls Plaid Link UI theme.',
+      },
+    ]),
+  }}
+/>
+### Events
+- `plaid-success`: Provides the Plaid public token and metadata when customers finish linking.
+- `plaid-exit`: Emits when Link closes without success and includes exit metadata.
+- `error`: Surfaces integration failures (expired link token, network issues).
+### Public methods
+1. `open()` – Programmatically open Plaid Link (if you render a custom CTA).
+2. `close()` – Force-close the Link flow.
+## Theming & Layout
+- Styling is limited to the wrapper since Plaid controls the Link modal.
+- Provide fallback instructions for devices where Plaid is unavailable.
+<div
+  dangerouslySetInnerHTML={{
+    __html: PartsTable([
+      {
+        name: 'text',
+        description: 'Text styles.',
+      },
+      {
+        name: 'text-danger',
+        description: 'Danger/error text styles.',
+      },
+      {
+        name: 'label',
+        description: 'Label styles.',
+      },
+      {
+        name: 'input-radio',
+        description: 'Radio input styles.',
+      },
+      {
+        name: 'input-radio-focused',
+        description: 'Radio input styles when focused.',
+      },
+      {
+        name: 'input-radio-checked',
+        description: 'Radio input styles when checked.',
+      },
+      {
+        name: 'input-radio-checked-focused',
+        description: 'Radio input styles when checked and focused.',
+      },
+      {
+        name: 'input-radio-invalid',
+        description: 'Radio input styles when invalid.',
+      },
+    ]),
+  }}
+/>

package/docs/modular-checkout/sub-components/saved-payment-methods.mdx ADDED Viewed

@@ -0,0 +1,183 @@
+---
+id: modular-checkout/sub-components/saved-payment-methods
+title: Saved Payment Methods
+description: Saved payment selector for Modular Checkout that handles defaulting, deletion, and fallback to new entries.
+sidebar_position: 26
+---
+import {
+  PropsTable,
+  PartsTable,
+  getWebcomponentsVersion,
+} from '@justifi/webcomponents/docs/helpers';
+## Overview
+Renders a radio input list of saved payment methods as part of a checkout flow.
+> Note: This sub component will only display saved payment methods if a `payment_method_group_id` with associated payment methods was passed to the [create checkout](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CreateCheckout) API request.
+This component is **designed to be used within** the `justifi-modular-checkout` and **does not accept props directly**. Instead, it relies on shared state passed through the Stencil Store, managed by the wrapper component.
+**Authorization** and business context are also handled by `justifi-modular-checkout`, which manages authentication tokens and related configuration.
+This component exposes **no public methods or properties** and is not intended for standalone use.
+## Usage
+<pre><code className="language-html">{`<!DOCTYPE html>
+<html dir="ltr" lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
+  <title>justifi-saved-payment-methods</title>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"></script>
+<script
+  nomodule
+  src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.js"
+></script>
+<style>
+  /** These are the available parts for styling the component. */ ::part(text){' '}
+  {
+    // text styles
+  }
+  ::part(text-danger){' '}
+  {
+    // text danger styles
+  }
+  ::part(label){' '}
+  {
+    // label styles
+  }
+  ::part(input-radio){' '}
+  {
+    // input radio styles
+  }
+  ::part(input-radio-focused){' '}
+  {
+    // input radio focused styles
+  }
+  ::part(input-radio-checked){' '}
+  {
+    // input radio checked styles
+  }
+  ::part(input-radio-checked-focused){' '}
+  {
+    // input radio checked focused styles
+  }
+  ::part(input-radio-invalid){' '}
+  {
+    // input radio invalid styles
+  }
+</style>
+</head>
+<body>
+  <justifi-modular-checkout auth-token="authToken" checkout-id="ch_123">
+    <justifi-saved-payment-methods />
+  </justifi-modular-checkout>
+</body>
+<script>
+  (function() {
+    const checkoutWrapper = document.querySelector('justifi-modular-checkout');
+    const submitButton = document.querySelector('#submit-button');
+    submitButton.addEventListener('click', () => {
+      checkoutWrapper.submitCheckout();
+    });
+    checkoutWrapper.addEventListener('error-event', (event) => {
+      console.error(event.detail);
+    });
+    document.addEventListener('submit-event', (event) => {
+      console.log('Checkout completed successfully!', event.detail);
+    });
+  })();
+</script>
+</html>`}</code></pre>
+## Props, Events & Methods
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'customer-id',
+        type: 'string',
+        required: true,
+        description: 'Identifies which saved methods to fetch.',
+      },
+      {
+        name: 'allow-delete',
+        type: 'boolean',
+        defaultValue: 'true',
+        description: 'Shows the delete button for each saved method.',
+      },
+      {
+        name: 'show-add-new',
+        type: 'boolean',
+        defaultValue: 'true',
+        description:
+          'Displays a control that reveals the card/bank forms when no method is selected.',
+      },
+    ]),
+  }}
+/>
+### Events
+- `selection-changed`: Emits when customers choose a different saved method.
+- `delete-requested`: Fires when someone clicks delete on a saved method (confirm server-side permissions).
+### Public methods
+1. `clearSelection()` – Deselect saved methods so the new card/bank forms reappear.
+## Theming & Layout
+<div
+  dangerouslySetInnerHTML={{
+    __html: PartsTable([
+      {
+        name: 'text',
+        description: 'Text styles.',
+      },
+      {
+        name: 'text-danger',
+        description: 'Danger/error text styles.',
+      },
+      {
+        name: 'label',
+        description: 'Label styles.',
+      },
+      {
+        name: 'input-radio',
+        description: 'Radio input styles.',
+      },
+      {
+        name: 'input-radio-focused',
+        description: 'Radio input styles when focused.',
+      },
+      {
+        name: 'input-radio-checked',
+        description: 'Radio input styles when checked.',
+      },
+      {
+        name: 'input-radio-checked-focused',
+        description: 'Radio input styles when checked and focused.',
+      },
+      {
+        name: 'input-radio-invalid',
+        description: 'Radio input styles when invalid.',
+      },
+    ]),
+  }}
+/>