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

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

@@ -0,0 +1,94 @@
+---
+id: merchant-tools/payouts-list/index
+title: Payouts List
+description: Reporting table for outbound payouts including status, destination, and expected arrival.
+sidebar_position: 40
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a formated list of payouts for the requested account.
+
+## Usage
+
+<pre><code className="language-html">{`<justifi-payouts-list
+  account-id="acc_123"
+  auth-token="wct_reporting"
+  columns="created_at,amount,destination,status"
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Filters payouts to the merchant or platform account.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `read:payouts` scope.',
+    },
+    {
+      name: 'columns',
+      type: 'string',
+      defaultValue: 'created_at,amount,destination,status,expected_arrival',
+      description: 'Comma-separated list controlling table columns.',
+    },
+    {
+      name: 'timezone',
+      type: 'string',
+      defaultValue: 'UTC',
+      description: 'Controls formatting for timestamps.',
+    },
+  ]) }} />
+
+### Events
+
+- `click-event`: Fires when a row is clicked; `detail.payout_id` indicates which payout to drill into.
+
+### Public methods
+
+1. `refresh()` – Reload the payouts query.
+
+## 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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Navigate to payout details
+
+<pre><code className="language-js">{`const payouts = document.querySelector('justifi-payouts-list');
+
+payouts.addEventListener('click-event', (event) => {
+if (event.detail.name === 'row') {
+router.push('/payouts/' + event.detail.payout_id);
+}
+});`}</code></pre>

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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Navigate to order details
+
+<pre><code className="language-js">{`const orders = document.querySelector('justifi-terminal-orders-list');
+
+orders.addEventListener('click-event', ({ detail }) => {
+if (detail.name === 'row') router.push('/terminals/orders/' + detail.order_id);
+});`}</code></pre>

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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Open device detail
+
+<pre><code className="language-js">{`const terminals = document.querySelector('justifi-terminals-list');
+
+terminals.addEventListener('click-event', ({ detail }) => {
+router.push('/terminals/' + detail.terminal_id);
+});`}</code></pre>

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/docs/index.mdx

@@ -0,0 +1,32 @@
+---
+id: modular-checkout/docs/index
+title: Modular Checkout Docs
+sidebar_label: Docs
+description: Standards for documenting Modular Checkout and every child component.
+---
+
+Document every Modular Checkout building block the same way so product, design,
+and engineering teams can stay in sync. The guidance below applies to the parent
+shell plus each entry in [`Sub-components`](../sub-components/index).
+
+## How component docs are structured
+
+Every page follows the same scaffolding:
+
+1. **Overview** – when to use the component.
+2. **Usage** – minimal markup plus contextual variants.
+3. **Props & Events** – rendered via `<PropsTable>` for consistency.
+4. **Theming & Parts** – CSS custom properties and enumerated `::part` selectors (via `<PartsTable>`).
+5. **Accessibility** – focus management, aria attributes, localization guidance.
+6. **Static Examples** – non-interactive snippets that mirror Storybook stories.
+
+## Authoring checklist
+
+- Duplicate `../../templates/component-template.mdx` and adjust the frontmatter
+  `id` plus title to match the new slug.
+- Keep prose declarative and actionable—no conversational filler.
+- Include at least one code example using `<pre><code>`, `<PropsTable>`, and `<PartsTable>` block.
+- Reference shared guides when overlapping content would otherwise drift.
+- Document `::part` styling hooks plus any CSS variables the component exposes.
+- Add cross-links back to [`Modular Checkout`](../index) and any related
+  components so readers can navigate without scrolling the sidebar.

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

@@ -0,0 +1,25 @@
+---
+id: modular-checkout/example/index
+title: Modular Checkout Example
+sidebar_label: Example
+description: Minimal implementation that wires auth, account, and summary slots.
+---
+
+Plug this snippet into any HTML sandbox to validate auth tokens, slot content,
+and submission hooks before integrating into your production host app.
+
+### Embedded checkout with summary
+
+<pre><code className="language-html">{`<justifi-modular-checkout
+  account-id="acc_demo"
+  auth-token="token_checkout"
+  checkout-id="chk_demo"
+  submit-label="Pay now"
+>
+  <justifi-modular-checkout-card-form slot="payment-methods" />
+  <justifi-modular-checkout-summary slot="summary" />
+</justifi-modular-checkout>`}</code></pre>
+
+> Combine this structure with your own `<justifi-payment-method-options>` UI
+> when you need to pre-select rails outside of the checkout shell.
+

package/docs/modular-checkout/index.mdx

@@ -0,0 +1,25 @@
+---
+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.
+- [Docs](./docs/index) when you are authoring or updating technical reference
+  material for new sub-components.
+- [Example](./example/index) for a single-file snippet that you can paste into
+  a sandbox or CMS.
+- [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,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 '@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.' },
+  ]) }} />
+
+## 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

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