npm - @justifi/webcomponents - Versions diffs - 6.5.1-rc.3 → 6.5.1-rc.5 - Mend

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

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

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/PartsTable.ts ADDED Viewed

@@ -0,0 +1,55 @@
+export interface PartsTableRow {
+  name: string;
+  description: string;
+  target?: string;
+}
+function escapeHtml(text: string): string {
+  const map: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;',
+  };
+  return text.replace(/[&<>"']/g, (m) => map[m]);
+}
+export function PartsTable(parts: PartsTableRow[], caption?: string): string {
+  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/PropsTable.ts ADDED Viewed

@@ -0,0 +1,63 @@
+export interface PropsTableRow {
+  name: string;
+  type: string;
+  required?: boolean;
+  description: string;
+  defaultValue?: string;
+}
+function escapeHtml(text: string): string {
+  const map: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#039;',
+  };
+  return text.replace(/[&<>"']/g, (m) => map[m]);
+}
+export function PropsTable(rows: PropsTableRow[], caption?: string): string {
+  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.js ADDED Viewed

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

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/helpers/version.ts ADDED Viewed

@@ -0,0 +1,32 @@
+let cachedVersion: string | null = null;
+export const getWebcomponentsVersion = (): string => {
+  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,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 '@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.
+## 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>