@justifi/webcomponents 6.7.0 → 6.7.2

package/docs/merchant-tools/terminal-orders-list/index.mdx

@@ -0,0 +1,85 @@
+---
+id: merchant-tools/terminal-orders-list/index
+title: Terminal Orders List
+description: Reporting table of hardware orders with fulfillment status and tracking info.
+sidebar_position: 51
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a formated list of terminal device orders for the requested account.
+
+## Usage
+
+<pre>
+  <code className="language-html">{`<justifi-terminal-orders-list
+  account-id="acc_123"
+  auth-token="wct_terminals"
+/>`}</code>
+</pre>
+
+## Props, Events & Methods
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'account-id',
+        type: 'string',
+        required: true,
+        description: 'Restricts orders to a merchant/platform.',
+      },
+      {
+        name: 'auth-token',
+        type: 'string',
+        required: true,
+        description: 'Token with `read:terminals` scope.',
+      },
+      {
+        name: 'columns',
+        type: 'string',
+        defaultValue: 'created_at,order_number,items,status,tracking_number',
+        description: 'Customize visible columns.',
+      },
+    ]),
+  }}
+/>
+
+### Events
+
+- `click-event`: Surfaces the order ID for navigation.
+
+### Public methods
+
+1. `refresh()` – Reload order data.
+
+## Theming & Layout
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: PartsTable([
+      {
+        name: 'font-family',
+        description: 'Controls the font family for the component.',
+      },
+      {
+        name: 'color',
+        description: 'Controls the text color.',
+      },
+      {
+        name: 'background-color',
+        description: 'Controls the background color.',
+      },
+      {
+        name: 'button',
+        description: 'Button styles.',
+      },
+      {
+        name: 'button-disabled',
+        description: 'Disabled button styles.',
+      },
+    ]),
+  }}
+/>

package/docs/merchant-tools/terminals-list/index.mdx

@@ -0,0 +1,93 @@
+---
+id: merchant-tools/terminals-list/index
+title: Terminals List
+description: Inventory table showing active, inactive, and assigned terminals in the field.
+sidebar_position: 52
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a formated list of terminals for the requested account.
+
+## Usage
+
+<pre>
+  <code className="language-html">{`<justifi-terminals-list
+  account-id="acc_123"
+  auth-token="wct_terminals"
+  filters='{"status":"online"}'
+/>`}</code>
+</pre>
+
+## Props, Events & Methods
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'account-id',
+        type: 'string',
+        required: true,
+        description: 'Scope inventory to a merchant/platform.',
+      },
+      {
+        name: 'auth-token',
+        type: 'string',
+        required: true,
+        description: 'Token with `read:terminals` scope.',
+      },
+      {
+        name: 'filters',
+        type: 'string | Record<string, unknown>',
+        description:
+          'Optional JSON to preset status, location, or software filters.',
+      },
+      {
+        name: 'columns',
+        type: 'string',
+        defaultValue: 'name,status,location,last_check_in',
+        description: 'Customize visible columns.',
+      },
+    ]),
+  }}
+/>
+
+### Events
+
+- `click-event`: Row click event that surfaces `terminal_id`.
+- `filter-changed`: Emits when the built-in filters change.
+
+### Public methods
+
+1. `refresh()` – Reloads terminal data.
+
+## Theming & Layout
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: PartsTable([
+      {
+        name: 'font-family',
+        description: 'Controls the font family for the component.',
+      },
+      {
+        name: 'color',
+        description: 'Controls the text color.',
+      },
+      {
+        name: 'background-color',
+        description: 'Controls the background color.',
+      },
+      {
+        name: 'button',
+        description: 'Button styles.',
+      },
+      {
+        name: 'button-disabled',
+        description: 'Disabled button styles.',
+      },
+    ]),
+  }}
+/>

package/docs/modular-checkout/complete-examples/index.mdx

@@ -0,0 +1,20 @@
+---
+id: modular-checkout/complete-examples/index
+title: Modular Checkout Complete Examples
+sidebar_label: Complete Examples
+description: Storybook-driven layouts that demonstrate real-world checkout flows.
+---
+
+Reference these Storybook stories when you need production-ready layout
+patterns or want to hand designers a live sandbox.
+
+- [Layout 1](https://storybook.justifi.ai/?path=/docs/modular-checkout-complete-examples-layout-1--docs):
+  responsive two-column layout with summary pinned on desktop.
+- [Layout 2](https://storybook.justifi.ai/?path=/docs/modular-checkout-complete-examples-layout-2--docs):
+  hero-style payment rail picker plus collapsible summaries.
+- [Layout 3](https://storybook.justifi.ai/?path=/docs/modular-checkout-complete-examples-layout-3--docs):
+  condensed layout optimized for embedded partner portals.
+
+> These examples map 1:1 with production code, so you can inspect the DOM,
+> props, and CSS custom properties without digging through story sources.
+

package/docs/modular-checkout/index.mdx

@@ -0,0 +1,20 @@
+---
+id: modular-checkout/index
+title: Modular Checkout
+description: Orientation hub for the JustiFi modular checkout experience.
+---
+
+Modular Checkout stitches every payment surface, summary view, and auxiliary
+experience into one cohesive flow. Use this hub to jump into the right phase of
+the journey:
+
+- [Introduction](./introduction/index) for architecture, props, events, and
+  theming guidance.
+- [Complete Examples](./complete-examples/index) for Storybook layouts that
+  demonstrate multi-step funnels.
+- [Sub-components](./sub-components/index) for deep dives on each child element
+  (card form, bank form, payment method picker, etc.).
+
+> Ship custom layouts fast: combine `[sub-components](./sub-components/index)`
+> with the patterns in `[Example](./example/index)` so you can validate UX
+> decisions before plumbing real data.

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

@@ -0,0 +1,102 @@
+---
+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 '@justifi/webcomponents/docs/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.' },
+    ]),
+  }}
+/>

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

@@ -0,0 +1,106 @@
+---
+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,
+  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.',
+      },
+    ]),
+  }}
+/>

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

@@ -0,0 +1,167 @@
+---
+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.',
+      },
+    ]),
+  }}
+/>