npm - @justifi/webcomponents - Versions diffs - 6.5.1-rc.2 → 6.5.1-rc.4 - Mend

@justifi/webcomponents 6.5.1-rc.2 → 6.5.1-rc.4

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

package/docs/modular-checkout/introduction/index.mdx ADDED Viewed

@@ -0,0 +1,100 @@
+---
+id: modular-checkout/introduction/index
+title: Modular Checkout
+sidebar_label: Introduction
+description: Layout manager that composes payment, summary, and confirmation subcomponents into a cohesive flow.
+sidebar_position: 21
+---
+import { PropsTable, PartsTable } from '../../helpers';
+## Overview
+The `justifi-modular-checkout` wrapper component serves as a container for checkout-related sub components. It manages the tokenization of payment methods, billing information, insurance, and overall form submission to complete the checkout. It also supports saving a payment method to a payment method group for future use.
+## Usage
+<pre><code className="language-html">{`<justifi-modular-checkout
+  account-id="acc_123"
+  auth-token="wct_checkout"
+  checkout-id="chk_456"
+>
+  <justifi-modular-checkout-card-form slot="payment-methods" />
+  <justifi-modular-checkout-summary slot="summary" />
+</justifi-modular-checkout>`}</code></pre>
+## Props, Events & Methods
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Platform or merchant account for the checkout session.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description:
+        'Token with scopes for reading checkout data and tokenizing payment methods.',
+    },
+    {
+      name: 'checkout-id',
+      type: 'string',
+      required: true,
+      description:
+        'Server-side checkout object controlling totals and allowed rails.',
+    },
+    {
+      name: 'submit-label',
+      type: 'string',
+      defaultValue: 'Pay now',
+      description: 'Override the CTA copy.',
+    },
+    {
+      name: 'locale',
+      type: 'string',
+      defaultValue: 'en-US',
+      description: 'Controls currency format + copy.',
+    },
+  ]) }} />
+### Events
+- `completed`: Fired when all nested components finish and a payment succeeds.
+- `error`: Emitted when nested components report a failure (validation, network, etc.).
+- `step-changed`: Surfaces stepper transitions for analytics.
+### Public methods
+1. `submit()` – Programmatically trigger the checkout CTA.
+2. `reset()` – Reset the flow back to the first step and clear transient state.
+## Theming & Layout
+- Slots expose `::part(summary)` and `::part(payment-methods)` so you can adjust spacing for each region.
+<div dangerouslySetInnerHTML={{ __html: PartsTable([
+    {
+      name: 'shell',
+      description: 'Outer wrapper that surrounds the full modular checkout.',
+    },
+    {
+      name: 'payment-methods',
+      description: 'Region that houses card/bank/alternative rails.',
+    },
+    {
+      name: 'summary',
+      description: 'Order summary slot, typically on the right on desktop.',
+    },
+    { name: 'cta', description: 'Primary submit button container.' },
+  ]) }} />
+## Static examples
+### Programmatic submission
+<pre><code className="language-js">{`const modCheckout = document.querySelector('justifi-modular-checkout');
+document.querySelector('#submit-order').addEventListener('click', () => modCheckout.submit());`}</code></pre>

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

@@ -0,0 +1,97 @@
+---
+id: modular-checkout/sub-components/apple-pay
+title: Apple Pay
+description: Apple Pay rail for Modular Checkout that exposes wallet buttons and handles tokenization.
+sidebar_position: 22
+---
+import { PropsTable, PartsTable } from '../../helpers';
+import { getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+## Overview
+Renders an Apple Pay button for eligible devices and orchestrates the Apple Pay flow. Designed to be used within `justifi-modular-checkout`.
+## 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-apple-pay</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(button) {
+        // button styles
+      }
+    </style>
+</head>
+<body>
+  <justifi-modular-checkout
+    auth-token="authToken"
+    checkout-id="ch_123"
+  >
+    <justifi-apple-pay slot="payment-methods" />
+    <justifi-modular-checkout-summary slot="summary" />
+  </justifi-modular-checkout>
+</body>
+</html>`}</code></pre>
+## Props, Events & Methods
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'button-style',
+      type: '"black" | "white" | "white-outline"',
+      defaultValue: 'black',
+      description: 'Matches Apple\'s Human Interface Guidelines.',
+    },
+    {
+      name: 'button-type',
+      type: '"buy" | "donate" | "plain"',
+      defaultValue: 'buy',
+      description: 'Set the label/icon on the wallet button.',
+    },
+    {
+      name: 'locale',
+      type: 'string',
+      defaultValue: 'en-US',
+      description:
+        'Controls the region on the underlying `ApplePaySession` request.',
+    },
+  ]) }} />
+### Events
+- `availability-changed`: Notifies the parent when Apple Pay is disabled for the current device/browser.
+- `error`: Surfaces tokenization failures (network, customer cancel, etc.).
+### Public methods
+1. `begin()` – Trigger the Apple Pay sheet programmatically if you hide the built-in button.
+## Theming & Layout
+- Styling is intentionally limited to keep Apple compliance.
+<div dangerouslySetInnerHTML={{ __html: PartsTable([
+    {
+      name: 'button',
+      description:
+        'Wrapper around the native Apple Pay button for margin/padding tweaks.',
+    },
+  ]) }} />
+## Static examples
+### Custom launch button
+<pre><code className="language-js">{`const applePay = document.querySelector('justifi-apple-pay');
+document.querySelector('#apple-pay-launch').onclick = () => applePay.begin();`}</code></pre>

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

@@ -0,0 +1,163 @@
+---
+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 } from '../../helpers';
+import { 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,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 } from '../../helpers';
+import { 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 '../../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>