npm - @justifi/webcomponents - Versions diffs - 6.5.1-rc.3 → 6.5.1-rc.5 - Mend

@justifi/webcomponents 6.5.1-rc.3 → 6.5.1-rc.5

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 (524) hide show

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

@@ -0,0 +1,162 @@
+---
+id: modular-checkout/sub-components/bank-account-form
+title: Bank Account Form
+description: Bank account rail for Modular Checkout that tokenizes ACH details with hosted inputs.
+sidebar_position: 28
+---
+import { PropsTable, PartsTable, getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+## Overview
+Renders a form for collecting bank account details as part of a checkout flow.
+This subcomponent is **designed to be used within** the `justifi-modular-checkout` and **does not accept props directly**. Instead, it relies on the shared state passed through the Stencil Store, managed by the `justifi-modular-checkout` component.
+> **Note:** If you are using this sub component, you also need to provide billing information. This can be done by adding the `justifi-billing-form-full` sub component for complete billing address, the `justifi-bank-account-billing-form-simple` sub component for account owner name only, or by passing the `billingInformation` object as an argument to the `submitCheckout` method called on the `justifi-modular-checkout`. See the [modular checkout docs](../introduction/index) for more information.
+**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-bank-account-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-bank-account-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:
+        'Match the parent checkout\'s group when you want to toggle which rails appear.',
+    },
+    {
+      name: 'show-account-type',
+      type: 'boolean',
+      defaultValue: 'true',
+      description: 'Hide when you only accept checking accounts.',
+    },
+    {
+      name: 'locale',
+      type: 'string',
+      defaultValue: 'en-US',
+      description: 'Controls labels + validation messages.',
+    },
+  ]) }} />
+### Events
+- Emits the same `submit` / `error` events as other modular rails via the parent checkout; no direct listeners required.
+### Public methods
+1. `focus()` – Focuses the first hosted field (routing number).
+## Theming & Layout
+<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.',
+    },
+  ]) }} />
+## Static examples
+### Auto-focus fields
+Tie custom UI to the public `focus()` method.
+<pre><code className="language-js">{`const bankForm = document.querySelector('justifi-bank-account-form');
+document.querySelector('#focus-bank').onclick = () => bankForm.focus();`}</code></pre>

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

@@ -0,0 +1,177 @@
+---
+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.
+## Static examples
+### Card form with disabled save option
+<pre><code className="language-html">{`<justifi-modular-checkout-card-form
+  show-save-payment-method="false"
+/>`}</code></pre>
+### Force brand icons off
+<pre><code className="language-html">{`<justifi-modular-checkout-card-form
+  card-brand-icons="none"
+/>`}</code></pre>

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,85 @@
+---
+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.',
+    },
+  ]) }} />
+## Static examples
+### Programmatic selection
+<pre><code className="language-js">{`const options = document.querySelector('justifi-payment-method-options');
+document.querySelector('#select-ach').onclick = () => options.select('ach');`}</code></pre>

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

@@ -0,0 +1,175 @@
+---
+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.',
+    },
+  ]) }} />
+## Static examples
+### Listening for success
+<pre><code className="language-js">{`const plaidRail = document.querySelector('justifi-plaid-payment-method');
+plaidRail.addEventListener('plaid-success', ({ detail }) => {
+console.log('Bank linked: ', detail.institution.name);
+});`}</code></pre>