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

package/docs/merchant-tools/gross-payments-chart/index.mdx

@@ -0,0 +1,81 @@
+---
+id: merchant-tools/gross-payments-chart/index
+title: Gross Payments Chart
+description: Visualizes gross payment volume over time with tooltips and range selection.
+sidebar_position: 43
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render chart displaying last 30 days of gross payment data.
+
+## Usage
+
+### Chart monthly volume
+
+<pre><code className="language-html">{`<justifi-gross-payment-chart
+  account-id="acc_123"
+  auth-token="wct_reporting"
+  interval="month"
+  range="12m"
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Determines which payments to graph.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `read:payments` scope.',
+    },
+    {
+      name: 'interval',
+      type: '"day" | "week" | "month"',
+      defaultValue: 'day',
+      description: 'Bucket size for data points.',
+    },
+    {
+      name: 'range',
+      type: 'string',
+      defaultValue: '30d',
+      description: 'Total timeframe (e.g., `7d`, `3m`, `12m`).',
+    },
+  ]) }} />
+
+### Events
+
+- `point-hover`: Emits when a user hovers/focuses a data point; includes amount and date.
+
+### Public methods
+
+1. `refresh()` – Re-fetch chart data (useful when filters change).
+
+## Theming & Layout
+
+<div dangerouslySetInnerHTML={{ __html: PartsTable([
+    { name: 'chart', description: 'SVG/Canvas container for the line chart.' },
+    {
+      name: 'tooltip',
+      description: 'Floating tooltip bubble when hovering/focusing a point.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Toggle ranges
+
+<pre><code className="language-js">{`const chart = document.querySelector('justifi-gross-payment-chart');
+
+document.querySelector('#range').addEventListener('change', (event) => {
+chart.setAttribute('range', event.target.value);
+chart.refresh();
+});`}</code></pre>

package/docs/merchant-tools/index.mdx

@@ -0,0 +1,25 @@
+---
+id: merchant-tools/index
+title: Merchant Tools
+description: Operational dashboards for tracking payouts, payments, and terminals.
+---
+
+Merchant Tools components expose the same operational insights that platforms
+use internally. Mix and match them to build tailored portals:
+
+1. [Checkouts List](./checkouts-list/index) – monitor in-flight checkout
+   sessions and states.
+2. [Payments List](./payments-list/index) / [Payment Details](./payment-details/index)
+   – audit every transaction from authorization through settlement.
+3. [Payment Transactions List](./payment-transactions-list/index) – deep dive
+   into ledger-level events.
+4. [Payouts List](./payouts-list/index), [Payout Details](./payout-details/index),
+   and [Payout Transactions List](./payout-transactions-list/index) – reconcile
+   disbursements end to end.
+5. [Gross Payments Chart](./gross-payments-chart/index) – visualize trends.
+6. [Order Terminals](./order-terminals/index), [Terminal Orders List](./terminal-orders-list/index),
+   and [Terminals List](./terminals-list/index) – manage hardware fulfillment.
+
+> Most teams embed just a handful of these components per view. Keep pages
+> focused so operators can answer one question without sifting through noise.
+

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

@@ -0,0 +1,84 @@
+---
+id: merchant-tools/order-terminals/index
+title: Order Terminals
+description: Guided purchasing flow for ordering in-person terminals and accessories.
+sidebar_position: 50
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a form for terminal order requests.
+
+## Usage
+
+<pre><code className="language-html">{`<justifi-order-terminals
+  account-id="acc_123"
+  auth-token="wct_terminals"
+  shipping-contact="contact_456"
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Merchant placing the order.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `write:terminals` scope.',
+    },
+    {
+      name: 'shipping-contact',
+      type: 'string',
+      description:
+        'Optional saved contact ID; when omitted the component collects address info inline.',
+    },
+    {
+      name: 'allowed-products',
+      type: 'string',
+      description: 'Comma-separated SKU list to limit which devices appear.',
+    },
+  ]) }} />
+
+### Events
+
+- `submitted`: Fires when an order is placed; includes order ID and device list.
+- `error-event`: Emits network or validation errors.
+
+### Public methods
+
+1. `submit()` – Trigger the order (useful if you host CTAs externally).
+
+## 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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Restrict SKUs
+
+<pre><code className="language-html">{`<justifi-order-terminals
+  account-id="acc_123"
+  auth-token="wct_terminals"
+  allowed-products="WISEPAD_3,WISEPOS_E"
+/>`}</code></pre>

package/docs/merchant-tools/payment-details/index.mdx

@@ -0,0 +1,130 @@
+---
+id: merchant-tools/payment-details/index
+title: Payment Details
+description: Detailed view for a single payment, including customer data, timeline events, and dispute shortcuts.
+sidebar_position: 30
+---
+
+import { PropsTable, PartsTable, getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to display detailed information about a specific payment.
+
+## 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-payment-details</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>
+      ::part(font-family) {
+        font-family: georgia;   
+      }
+        
+      ::part(color) {
+        color: darkslategray;
+      }
+
+      ::part(background-color) {
+        background-color: transparent;
+      }
+    </style>
+
+</head>
+
+<body>
+  <justifi-payment-details payment-id="py_123" auth-token="authToken" />
+</body>
+
+<script>
+  (function () {
+    const paymentDetails = document.querySelector('justifi-payment-details');
+
+    paymentDetails.addEventListener('error-event', (event) => {
+      // here is where you would handle the error
+      console.error('error-event', event.detail);
+    });
+  })();
+</script>
+
+</html>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Owning platform account for authorization.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `read:payments` scope.',
+    },
+    {
+      name: 'payment-id',
+      type: 'string',
+      required: true,
+      description: 'Payment to display.',
+    },
+    {
+      name: 'show-actions',
+      type: 'boolean',
+      defaultValue: 'true',
+      description: 'Hide when you only need a read-only audit surface.',
+    },
+  ]) }} />
+
+### Events
+
+- `refund-requested`: emitted when an operator clicks the refund CTA.
+- `dispute-opened`: indicates that the “Open dispute” action was invoked.
+
+### Public methods
+
+1. `refresh()` – Re-fetch the payment to reflect new statuses after an action.
+
+## 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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Hook into refund events
+
+<pre><code className="language-js">{`const details = document.querySelector('justifi-payment-details');
+
+details.addEventListener('refund-requested', ({ detail }) => {
+console.log('Starting refund flow for payment', detail.payment_id);
+});`}</code></pre>

package/docs/merchant-tools/payment-transactions-list/index.mdx

@@ -0,0 +1,85 @@
+---
+id: merchant-tools/payment-transactions-list/index
+title: Payment Transactions List
+description: Transaction-level ledger for payments, grouped by status and funding state.
+sidebar_position: 32
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to display a list of payment transactions for a specific payment.
+
+## Usage
+
+<pre><code className="language-html">{`<justifi-payment-transactions-list
+  account-id="acc_123"
+  auth-token="wct_reporting"
+  filters='{"payment_id":"pay_456"}'
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Determines which transactions a user can view.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `read:payments` scope.',
+    },
+    {
+      name: 'filters',
+      type: 'string | Record<string, unknown>',
+      description:
+        'JSON string or object specifying filter criteria (payment_id, status, date range).',
+    },
+    {
+      name: 'enable-export',
+      type: 'boolean',
+      defaultValue: 'false',
+      description: 'Adds export controls when true.',
+    },
+  ]) }} />
+
+### Events
+
+- `filter-changed`: emits whenever the internal filter UI updates.
+- `error-event`: surfaces API or token failures.
+
+### Public methods
+
+1. `refresh()` – Re-run the ledger 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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Listening for filter changes
+
+<pre><code className="language-js">{`const ledger = document.querySelector('justifi-payment-transactions-list');
+
+ledger.addEventListener('filter-changed', (event) => {
+console.log('Filters now', event.detail);
+});`}</code></pre>

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

@@ -0,0 +1,111 @@
+---
+id: merchant-tools/payments-list/index
+title: Payments List
+description: Paginated table of payments with filtering, export, and quick actions for ops teams.
+sidebar_position: 31
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a formated list of payments for the requested account.
+
+## Usage
+
+<pre><code className="language-html">{`<div class="payments-report">
+  <justifi-filters
+    account-id="acc_123"
+    auth-token="wct_reporting"
+    target="payments"
+  ></justifi-filters>
+  <justifi-payments-list
+    account-id="acc_123"
+    auth-token="wct_reporting"
+    columns="created_at,customer_name,payment_amount,status"
+  ></justifi-payments-list>
+</div>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Scope results to the platform or sub-account.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `read:payments` scope.',
+    },
+    {
+      name: 'columns',
+      type: 'string',
+      defaultValue:
+        'created_at,customer_name,payment_amount,payment_description,status',
+      description:
+        'Comma-delimited list that controls which columns render and their order.',
+    },
+    {
+      name: 'page-size',
+      type: 'number',
+      defaultValue: '25',
+      description: 'Override default pagination size.',
+    },
+    {
+      name: 'enable-export',
+      type: 'boolean',
+      defaultValue: 'false',
+      description: 'Adds an export button that streams CSV data when true.',
+    },
+  ]) }} />
+
+### Events
+
+- `click-event`: emitted when users select a row or click an inline action; `event.detail` surfaces `payment_id`.
+- `error-event`: surfaces API or token errors for logging.
+
+### Public methods
+
+1. `refresh()` – Re-run the underlying query (useful after applying filters).
+2. `exportCSV()` – Programmatically trigger an export if `enable-export` is true.
+
+## 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
+
+### Reacting to row clicks
+
+<pre><code className="language-js">{`const list = document.querySelector('justifi-payments-list');
+
+list.addEventListener('click-event', (event) => {
+if (event.detail.name === 'row') {
+router.push('/payments/' + event.detail.payment_id);
+}
+});`}</code></pre>

package/docs/merchant-tools/payout-details/index.mdx

@@ -0,0 +1,90 @@
+---
+id: merchant-tools/payout-details/index
+title: Payout Details
+description: Drill-down view for a single payout, including ledger items and bank destination info.
+sidebar_position: 41
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to display detailed information about a specific payout.
+
+## Usage
+
+<pre><code className="language-html">{`<justifi-payout-details
+  account-id="acc_123"
+  auth-token="wct_reporting"
+  payout-id="po_456"
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'account-id',
+        type: 'string',
+        required: true,
+        description: 'Scope the payout to a platform or merchant.',
+      },
+      {
+        name: 'auth-token',
+        type: 'string',
+        required: true,
+        description: 'Token with `read:payouts` scope.',
+      },
+      {
+        name: 'payout-id',
+        type: 'string',
+        required: true,
+        description: 'Identifier for the payout you want to view.',
+      },
+      {
+        name: 'show-ledger',
+        type: 'boolean',
+        defaultValue: 'true',
+        description: 'Hide the ledger table when you only need summary data.',
+      },
+    ]),
+  }}
+/>
+
+### Events
+
+- `error-event`: Emits when payout data cannot be loaded.
+
+### Public methods
+
+1. `refresh()` – Reload payout data after remediation steps.
+
+## 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.',
+      },
+    ]),
+  }}
+/>
+
+## Static examples
+
+### Auto-refresh
+
+<pre><code className="language-js">{`const payout = document.querySelector('justifi-payout-details');
+
+setInterval(() => payout.refresh(), 60_000);`}</code></pre>

package/docs/merchant-tools/payout-transactions-list/index.mdx

@@ -0,0 +1,84 @@
+---
+id: merchant-tools/payout-transactions-list/index
+title: Payout Transactions List
+description: Ledger of transactions contributing to a payout, with filtering and export support.
+sidebar_position: 42
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to display a list of payout transactions for a specific payout.
+
+## Usage
+
+<pre><code className="language-html">{`<justifi-payout-transactions-list
+  account-id="acc_123"
+  auth-token="wct_reporting"
+  payout-id="po_456"
+/>`}</code></pre>
+
+## Props, Events & Methods
+
+<div dangerouslySetInnerHTML={{ __html: PropsTable([
+    {
+      name: 'account-id',
+      type: 'string',
+      required: true,
+      description: 'Authorization context.',
+    },
+    {
+      name: 'auth-token',
+      type: 'string',
+      required: true,
+      description: 'Token with `read:payouts` scope.',
+    },
+    {
+      name: 'payout-id',
+      type: 'string',
+      required: true,
+      description: 'Payout whose transactions should be displayed.',
+    },
+    {
+      name: 'columns',
+      type: 'string',
+      defaultValue: 'type,amount,source,status',
+      description: 'Column ordering and selection.',
+    },
+  ]) }} />
+
+### Events
+
+- `click-event`: row selection event that surfaces `transaction_id`.
+
+### Public methods
+
+1. `refresh()` – Reloads the ledger.
+
+## 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.',
+    },
+  ]) }} />
+
+## Static examples
+
+### Open payment details
+
+<pre><code className="language-js">{`const payoutLedger = document.querySelector('justifi-payout-transactions-list');
+
+payoutLedger.addEventListener('click-event', ({ detail }) => {
+router.push('/payments/' + detail.transaction_id);
+});`}</code></pre>