npm - @justifi/webcomponents - Versions diffs - 6.7.0 → 6.7.2 - Mend

@justifi/webcomponents 6.7.0 → 6.7.2

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

package/docs/frameworks/react/index.mdx ADDED Viewed

@@ -0,0 +1,125 @@
+---
+id: frameworks/react/index
+title: React
+description: How to consume JustiFi web components inside React applications.
+sidebar_position: 1
+---
+import { getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+React treats JustiFi web components like any other custom element. Load the bundle, optionally declare types, and use refs for method calls or event wiring.
+## Usage
+### Load the components
+<pre><code className="language-html">{`<head>
+  <script
+    async
+    type="module"
+    src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@${getWebcomponentsVersion()}/dist/webcomponents/webcomponents.esm.js"
+  ></script>
+</head>`}</code></pre>
+Or install the package:
+```bash
+npm install --save @justifi/webcomponents
+```
+Then import the module you need:
+```javascript
+import '@justifi/webcomponents/dist/module/justifi-checkout.js';
+```
+### Render inside JSX
+```jsx
+export function CheckoutExample() {
+  return (
+    <justifi-checkout auth-token="token" checkout-id="chk_123" locale="en-US" />
+  );
+}
+```
+## TypeScript integration
+Let TypeScript know about the generated intrinsic elements so JSX understands attributes and custom events.
+```ts
+// register-web-components.ts
+import { JSX as LocalJSX } from '@justifi/webcomponents/dist/loader';
+import { HTMLAttributes } from 'react';
+type StencilToReact<T> = {
+  [K in keyof T]?: T[K] &
+    Omit<HTMLAttributes<Element>, 'className'> & {
+      class?: string;
+    };
+};
+declare global {
+  export namespace JSX {
+    interface IntrinsicElements extends StencilToReact<LocalJSX.IntrinsicElements> {}
+  }
+}
+```
+Import that file once at the edge of your application (for example inside `src/main.tsx`) so the declarations register globally.
+## Calling methods with refs
+```tsx
+import { useRef } from 'react';
+export default function CheckoutWithRef() {
+  const checkoutRef = useRef<any>(null);
+  const fillBillingForm = () => {
+    checkoutRef.current?.fillBillingForm({
+      name: 'John Doe',
+      address_line1: '123 Main St',
+      address_city: 'Minneapolis',
+      address_state: 'MN',
+      address_postal_code: '55401',
+    });
+  };
+  return (
+    <>
+      <justifi-checkout ref={checkoutRef} auth-token="token" checkout-id="chk_123" />
+      <button onClick={fillBillingForm}>Prefill billing</button>
+    </>
+  );
+}
+```
+## Listening to events
+Attach listeners with `addEventListener` inside `useEffect` or via inline handlers if you wrap the component.
+```tsx
+import { useEffect, useRef } from 'react';
+export function CheckoutWithEvents() {
+  const checkoutRef = useRef<any>(null);
+  useEffect(() => {
+    const element = checkoutRef.current;
+    if (!element) {
+      return;
+    }
+    const handleSubmit = (event: CustomEvent) => {
+      console.log('Submit payload', event.detail);
+    };
+    element.addEventListener('submit-event', handleSubmit);
+    return () => element.removeEventListener('submit-event', handleSubmit);
+  }, []);
+  return <justifi-checkout ref={checkoutRef} auth-token="token" checkout-id="chk_123" />;
+}
+```

package/docs/frameworks/vue/index.mdx ADDED Viewed

@@ -0,0 +1,102 @@
+---
+id: frameworks/vue/index
+title: Vue 3
+description: Consume the JustiFi web components inside modern Vue applications.
+sidebar_position: 3
+---
+import { getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+Vue treats the JustiFi custom elements like native HTML tags. Load the script, import what you need, and wire up refs/events.
+## Integration steps
+### Load the components
+<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>
+Or install locally and import the desired module:
+```bash
+npm install --save @justifi/webcomponents
+```
+```ts
+import '@justifi/webcomponents/dist/module/justifi-checkout.js';
+```
+### Use inside templates
+```html
+<template>
+  <justifi-checkout
+    ref="checkoutFormRef"
+    :auth-token="authToken"
+    :checkout-id="checkoutId"
+    :disable-credit-card="true"
+  />
+</template>
+```
+## Event handling
+Leverage Vue's `@event-name` syntax for the custom events we emit.
+```html
+<template>
+  <justifi-checkout
+    ref="checkoutFormRef"
+    :auth-token="authToken"
+    :checkout-id="checkoutId"
+    @submit-event="onSubmit"
+    @error-event="onError"
+  />
+</template>
+<script setup lang="ts">
+const onSubmit = (event: CustomEvent) => {
+  console.log('Submit payload', event.detail);
+};
+const onError = (event: CustomEvent) => {
+  console.error('Error payload', event.detail);
+};
+</script>
+```
+## Calling methods
+Grab a ref to the element and call the public APIs directly.
+```html
+<template>
+  <justifi-checkout
+    ref="checkoutFormRef"
+    :auth-token="authToken"
+    :checkout-id="checkoutId"
+  />
+  <button @click="fillBillingForm">Prefill billing</button>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+const checkoutFormRef = ref<any>(null);
+const fillBillingForm = () => {
+  checkoutFormRef.value?.fillBillingForm({
+    name: 'John Doe',
+    address_line1: 'Main St',
+    address_city: 'Beverly Hills',
+    address_state: 'CA',
+    address_postal_code: '90210',
+  });
+};
+</script>
+```

package/docs/helpers/PartsTable.js ADDED Viewed

@@ -0,0 +1,50 @@
+function escapeHtml(text) {
+  const map = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;',
+  };
+  return text.replace(/[&<>"']/g, (m) => map[m]);
+}
+export function PartsTable(parts, caption) {
+  if (!parts?.length) {
+    return '';
+  }
+  let html = '<table class="docs-parts-table">';
+  if (caption) {
+    html += `<caption>${escapeHtml(caption)}</caption>`;
+  }
+  html += `
+    <thead>
+      <tr>
+        <th scope="col">Part</th>
+        <th scope="col">Description</th>
+        <th scope="col">DOM target</th>
+      </tr>
+    </thead>
+    <tbody>`;
+  for (const part of parts) {
+    html += `
+      <tr>
+        <td>
+          <code>::part(${escapeHtml(part.name)})</code>
+        </td>
+        <td>${escapeHtml(part.description)}</td>
+        <td>${part.target ? escapeHtml(part.target) : '—'}</td>
+      </tr>`;
+  }
+  html += `
+    </tbody>
+  </table>`;
+  return html;
+}

package/docs/helpers/PropsTable.js ADDED Viewed

@@ -0,0 +1,56 @@
+function escapeHtml(text) {
+  const map = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;',
+  };
+  return text.replace(/[&<>"']/g, (m) => map[m]);
+}
+export function PropsTable(rows, caption) {
+  if (!rows?.length) {
+    return '';
+  }
+  let html = '<table class="docs-props-table">';
+  if (caption) {
+    html += `<caption>${escapeHtml(caption)}</caption>`;
+  }
+  html += `
+    <thead>
+      <tr>
+        <th scope="col">Name</th>
+        <th scope="col">Type</th>
+        <th scope="col">Required</th>
+        <th scope="col">Default</th>
+        <th scope="col">Description</th>
+      </tr>
+    </thead>
+    <tbody>`;
+  for (const row of rows) {
+    html += `
+      <tr>
+        <td>
+          <code>${escapeHtml(row.name)}</code>
+        </td>
+        <td>
+          <code>${escapeHtml(row.type)}</code>
+        </td>
+        <td>${row.required ? 'Yes' : 'No'}</td>
+        <td>${row.defaultValue ? `<code>${escapeHtml(row.defaultValue)}</code>` : '—'}</td>
+        <td>${escapeHtml(row.description)}</td>
+      </tr>`;
+  }
+  html += `
+    </tbody>
+  </table>`;
+  return html;
+}

package/docs/helpers/index.ts ADDED Viewed

@@ -0,0 +1,3 @@
+export { PropsTable } from './PropsTable';
+export { PartsTable } from './PartsTable';
+export { getWebcomponentsVersion } from './version';

package/docs/helpers/version.js ADDED Viewed

@@ -0,0 +1,32 @@
+let cachedVersion = null;
+export const getWebcomponentsVersion = () => {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+  try {
+    // Try to import from the package (works in both Storybook and consumer apps)
+    const packageJson = require('@justifi/webcomponents/package.json');
+    const version = packageJson.version;
+    cachedVersion = version;
+    return version;
+  } catch (error) {
+    // Fallback: try to read from local package.json (for build-time)
+    try {
+      const fs = require('fs');
+      const path = require('path');
+      const packageJsonPath = path.resolve(__dirname, '../../package.json');
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+      const version = packageJson.version;
+      cachedVersion = version;
+      return version;
+    } catch (fallbackError) {
+      // Last resort: return 'latest' if we can't determine the version
+      console.warn(
+        'Could not determine @justifi/webcomponents version, using "latest"'
+      );
+      return 'latest';
+    }
+  }
+};

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,97 @@
+---
+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 '@justifi/webcomponents/docs/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.

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

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

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.