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/introduction/index.mdx ADDED Viewed

@@ -0,0 +1,125 @@
+---
+id: introduction/index
+title: Introduction
+description: Introduction to the JustiFi Web Component Library.
+sidebar_position: 1
+---
+import { getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+# Introduction to JustiFi Web Component Library
+Welcome to the JustiFi Web Component Library. These components can be used as HTML Web Components or as React components.
+## Usage
+### HTML Web Components
+The simplest way to use the Web Components is to include the following script within your HTML. This loads all the components into the browser's custom component registry.
+<pre><code className="language-html">{`<head>
+  <script
+    type="module"
+    src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"
+  ></script>
+</head>`}</code></pre>
+Then, you can use the custom elements as normal `HTML` tags.
+```html
+<justifi-checkout auth-token="token" checkout-id="chk_123"></justifi-checkout>
+```
+It can also be installed as a package with `npm` or `pnpm`:
+```bash
+npm install --save @justifi/webcomponents
+# or
+pnpm add @justifi/webcomponents
+```
+and import the component module using ES modules.
+```javascript
+import '@justifi/webcomponents/dist/module/justifi-checkout.js';
+```
+## Styling
+### How Parts Stack for Efficient Global Styling
+Parts are designed hierarchically to let you apply global styles like `color` or `font-family` universally, while components inherit these settings without repetitive targeting.
+### Core Parts and Inheritance
+1. **Base Parts**: `color`, `font-family`, and `background-color` define foundational styles.
+   - These propagate into higher-level parts like `text`, `button`, and `input`.
+2. **Higher-Level Parts**:
+   - **`text`**: Combines `color` and `font-family` for typography.
+   - **`input`, `button`, `label`**: Inherit `text`, ensuring consistent styles across components.
+### Global Styling in Action
+#### Universal Font
+Set the font for all components using `font-family`:
+```css
+::part(font-family) {
+  font-family: 'Inter', system-ui, sans-serif;
+}
+```
+#### Universal Text Color
+Set the text color once via `color`:
+```css
+::part(color) {
+  color: #1d1b2f;
+}
+```
+These apply to all components that rely on `text`, including buttons, inputs, and headings.
+### Component-Specific Overrides
+After defining global styles, customize specific components using their higher-level parts:
+#### Buttons
+```css
+::part(button-primary) {
+  background-color: #0d3b66;
+  color: #fff; /* Overrides `color` */
+}
+```
+#### Input States
+```css
+::part(input-focused) {
+  border-color: #0d3b66;
+  background-color: #f0f8ff;
+}
+```
+To view the full list of available parts for styling, consult the source file [here](https://github.com/justifi-tech/web-component-library/blob/main/packages/webcomponents/src/styles/parts.ts).
+### Best Practices
+1. **Style Base Parts First**: Focus on `color` and `font-family` for global consistency.
+2. **Override as Needed**: Use component-specific parts (e.g., `button-primary`) sparingly for deviations.
+3. **Inspect and Leverage Stacking**: Ensure you understand how parts like `text` layer to avoid redundant styles.
+This hierarchy ensures maintainable, reusable styles across all components with minimal effort.
+## Report Issues
+For bugs and issues, please:
+1. Go to our [GitHub Issues](https://github.com/justifi-tech/web-component-library/issues).
+2. Click "New Issue" and describe the problem.

package/docs/merchant-tools/checkouts-list/index.mdx ADDED Viewed

@@ -0,0 +1,107 @@
+---
+id: merchant-tools/checkouts-list/index
+title: Checkouts List
+description: Paginated reporting table for monitoring active and past checkouts.
+sidebar_position: 26
+---
+import { PropsTable, PartsTable } from '../../helpers';
+## Overview
+Component to render a formated list of checkouts for the requested account.
+## Usage
+### Basic list with filters
+<pre><code className="language-html">{`<justifi-checkouts-list-filters></justifi-checkouts-list-filters>
+<justifi-checkouts-list
+  account-id="acc_123"
+  auth-token="wct_reportingToken"
+/>`}</code></pre>
+### Custom columns
+Pass a comma-separated list to the `columns` prop (`created_at,payment_amount,status`) to match the data points your operators expect.
+## Props, Events & Methods
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'account-id',
+        type: 'string',
+        required: true,
+        description: 'Platform or sub-account whose checkouts should appear.',
+      },
+      {
+        name: 'auth-token',
+        type: 'string',
+        required: true,
+        description: 'Token with `read:checkouts` scope.',
+      },
+      {
+        name: 'columns',
+        type: 'string',
+        defaultValue:
+          'created_at,payment_amount,payment_description,payment_mode,status',
+        description: 'Controls which table columns render and their order.',
+      },
+    ]),
+  }}
+/>
+### Events
+- `click-event`: Emitted when a row or control is clicked. `event.detail.name` indicates the source.
+- `error-event`: Fires when the list cannot load data due to network/auth issues.
+### Methods
+1. `refresh()` – Re-fetches data. Combine with filter changes for dynamic searches.
+2. `exportCSV()` – (Coming soon) Provide your own download button and call this method for exports.
+## 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.',
+      },
+    ]),
+  }}
+/>
+- Filters component emits custom events; ensure both components share the same container so spacing stays consistent.
+## Static examples
+### Listening for row clicks
+<pre><code className="language-js">{`const list = document.querySelector('justifi-checkouts-list');
+list.addEventListener('click-event', (event) => {
+if (event.detail.name === 'row') {
+router.navigate('/checkouts/' + event.detail.checkout_id);
+}
+});`}</code></pre>

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

@@ -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 '../../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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 '../../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 ADDED Viewed

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

@@ -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 '../../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>