@justifi/webcomponents 6.7.1 → 6.7.2

package/docs/entities/payment-provisioning/index.mdx

@@ -0,0 +1,128 @@
+---
+id: entities/payment-provisioning/index
+title: Payment Provisioning
+description: Embed-ready workflow for collecting payout bank info and provisioning merchants for funding.
+sidebar_position: 12
+---
+
+import { PropsTable, PartsTable } from '@justifi/webcomponents/docs/helpers';
+
+## Overview
+
+Component to render a business onboarding form, segmented into multiple steps. You will need to first create a business via [Business API](https://docs.justifi.tech/api-spec#tag/Business) to get the business-id required for this component.
+
+## Usage
+
+<pre>
+  <code className="language-html">{`<justifi-payment-provisioning
+  account-id="acc_123"
+  auth-token="wct_provisioning"
+  business-id="biz_456"
+  on-success-text="Payout method saved"
+/>`}</code>
+</pre>
+
+## Props, Events & Methods
+
+<div
+  dangerouslySetInnerHTML={{
+    __html: PropsTable([
+      {
+        name: 'account-id',
+        type: 'string',
+        required: true,
+        description:
+          'Platform account or sub-account context for provisioning.',
+      },
+      {
+        name: 'auth-token',
+        type: 'string',
+        required: true,
+        description:
+          'Token with `write:provisioning` scope to securely store payout details.',
+      },
+      {
+        name: 'business-id',
+        type: 'string',
+        required: true,
+        description: 'Business whose payout method is being added.',
+      },
+      {
+        name: 'on-success-text',
+        type: 'string',
+        description:
+          'Overrides the confirmation copy once the payout account is linked.',
+      },
+      {
+        name: 'disable-ach',
+        type: 'boolean',
+        defaultValue: 'false',
+        description:
+          'Hide ACH specific fields when you only support push-to-card or other rails.',
+      },
+    ]),
+  }}
+/>
+
+### Events
+
+- `submitted`: Fires when payout information is collected and saved; payload includes the provisioning status.
+- `error-event`: Provides `code`/`message` details when token scopes or API calls fail.
+
+### Public methods
+
+1. `submit()` – Trigger provisioning if you render external controls.
+2. `focus()` – Move focus to the first interactive element (helpful after displaying a banner).
+
+## 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: 'input',
+        description: 'Input field styles.',
+      },
+      {
+        name: 'input-focused',
+        description: 'Input styles when focused.',
+      },
+      {
+        name: 'input-invalid',
+        description: 'Input styles when invalid.',
+      },
+      {
+        name: 'input-invalid-and-focused',
+        description: 'Input styles when invalid and focused.',
+      },
+      {
+        name: 'button',
+        description: 'Button styles.',
+      },
+      {
+        name: 'button-primary',
+        description: 'Primary button styles.',
+      },
+      {
+        name: 'button-disabled',
+        description: 'Disabled button styles.',
+      },
+      {
+        name: 'tooltip-inner',
+        description: 'Tooltip inner content styles.',
+      },
+    ]),
+  }}
+/>

package/docs/frameworks/angular/index.mdx

@@ -0,0 +1,112 @@
+---
+id: frameworks/angular/index
+title: Angular
+description: Registering and using JustiFi web components inside Angular projects.
+sidebar_position: 2
+---
+
+import { getWebcomponentsVersion } from '@justifi/webcomponents/docs/helpers';
+
+Angular can render the JustiFi custom elements once you load the library and allow custom schemas.
+
+## Usage
+
+### Load the bundle
+
+<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:
+
+```bash
+npm install --save @justifi/webcomponents
+```
+
+Import specific elements where needed:
+
+```ts
+import '@justifi/webcomponents/dist/module/justifi-checkout.js';
+```
+
+### Allow custom elements
+
+```ts
+import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { AppComponent } from './app.component';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule],
+  providers: [],
+  bootstrap: [AppComponent],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class AppModule {}
+```
+
+## Props and event handling
+
+Use Angular bindings for attributes and `(event)` syntax for emitted events.
+
+```html
+<justifi-checkout
+  [auth-token]="authToken"
+  [checkout-id]="checkoutId"
+  [disable-bank-account]="true"
+  (submit-event)="handleSubmit($event)"
+  (error-event)="handleError($event)"
+></justifi-checkout>
+```
+
+## Calling methods
+
+Leverage `ViewChild` to call public methods on the web component.
+
+```html
+<!-- app.component.html -->
+<justifi-checkout
+  #checkoutForm
+  [auth-token]="authToken"
+  [checkout-id]="checkoutId"
+  (submit-event)="handleSubmit($event)"
+></justifi-checkout>
+<button (click)="fillBillingForm()">Fill billing form</button>
+```
+
+```ts
+// app.component.ts
+import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+})
+export class AppComponent implements AfterViewInit {
+  @ViewChild('checkoutForm')
+  checkoutForm!: ElementRef<HTMLJustifiCheckoutElement>;
+
+  ngAfterViewInit() {
+    // Safe place to call component methods
+  }
+
+  fillBillingForm() {
+    const billing = {
+      name: 'John Doe',
+      address_line1: 'Main St',
+      address_city: 'Beverly Hills',
+      address_state: 'CA',
+      address_postal_code: '90210',
+    };
+
+    this.checkoutForm.nativeElement.fillBillingForm(billing);
+  }
+}
+```
+
+> `HTMLJustifiCheckoutElement` is available from `@justifi/webcomponents/dist/components` if you want stronger typing.

package/docs/frameworks/index.mdx

@@ -0,0 +1,18 @@
+---
+id: frameworks/index
+title: Frameworks
+description: Entry point for Angular, React, and Vue 3 integration guides.
+---
+
+Pick the framework-specific guide that matches your host app. Each page covers
+bundle registration, component typing, and ergonomics for that stack.
+
+1. [Angular](./angular/index) – schemas, module setup, and DI-friendly helpers.
+2. [React](./react/index) – rendering custom elements from JSX plus refs/events.
+3. [Vue 3](./vue/index) – registering components globally or per-view with full
+   TypeScript support.
+
+> Need another framework? Duplicate `templates/guide-template.mdx`, follow the
+> checklist inside, and add it to this directory so it picks up the same
+> navigation pattern.
+

package/docs/frameworks/react/index.mdx

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

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

@@ -0,0 +1,50 @@
+function escapeHtml(text) {
+  const map = {
+    '&': '&',
+    '<': '&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

@@ -0,0 +1,56 @@
+function escapeHtml(text) {
+  const map = {
+    '&': '&',
+    '<': '&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

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

package/docs/helpers/version.js

@@ -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';
+    }
+  }
+};
+