GL Dynamic Image

Version: 1.0.11 Package: @gift-card-market/gl-dynamic-image
Last Updated: July 1, 2026

A React library (with Web Component support) for rendering a dynamic business preview image using a business ID and partner JWT.

Features
Requirements
Installation
Quick Start with React
Detailed API
Styling & Customization
Web Component Usage
API Endpoint
Development & Build

Features

Render dynamic preview data from partner API by businessId + searchProvider.
Display business name, rating, review count, image, and provider-specific visual style.
Expose imperative methods via ref (reset, refresh).
Expose global controller helpers (reset, refresh) from package entry.
Emit custom DOM events for success/error handling (gl:previewLoaded, gl:error).
Responsive layout with auto-scaling behavior.
Publish bundled stylesheet at dist/style.css.

Requirements

React: ^18.2.0 or compatible.
Install runtime dependencies in your app:

npm install react react-dom react-tooltip

Node 16+ is recommended.

Installation

1. Configure GitHub Packages (if package is still hosted on GitHub)

From package.json:

"publishConfig": {
  "registry": "https://npm.pkg.github.com/@Gift-Card-Market",
  "access": "public"
}

Configure npm auth:

Create a GitHub Personal Access Token with read:packages.
Run login:

npm login --registry=https://npm.pkg.github.com --scope=@gift-card-market

Or add to .npmrc:

@gift-card-market:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Install package

npm install @gift-card-market/gl-dynamic-image

3. Import CSS

import '@gift-card-market/gl-dynamic-image/dist/style.css';

Quick Start with React

Basic Example

import { useRef } from 'react';
import { GlDynamicImage, type GlDynamicImageHandle } from '@gift-card-market/gl-dynamic-image';
import '@gift-card-market/gl-dynamic-image/dist/style.css';

export default function DynamicImagePage() {
  const ref = useRef<GlDynamicImageHandle | null>(null);

  return (
    <div>
      <button onClick={() => ref.current?.reset()}>Reset</button>
      <button onClick={() => ref.current?.refresh()}>Refresh</button>

      <GlDynamicImage
        ref={ref}
        data={{
          jwt: 'YOUR_JWT_TOKEN',
          businessId: 'YOUR_BUSINESS_ID',
          environment: 'production',
          searchProvider: 'yelp',
        }}
      />
    </div>
  );
}

Using Named Exports (without ref)

import { reset, refresh } from '@gift-card-market/gl-dynamic-image';

reset();
refresh();

If no component instance is mounted, these calls do nothing.

Detailed API

Props `GlDynamicImage`

Prop	Type	Required	Description
`data`	`GlDynamicImageData`	✅	Input configuration for authentication, business lookup, and environment.

`GlDynamicImageData`

Defined in src/types/gl-dynamic-image.ts:

export interface GlDynamicImageProps {
  data: {
    jwt: string;
    businessId: string;
    environment?: string;
    searchProvider?: string;
  };
}

Field behavior in current implementation:

jwt (required): Partner JWT used as Authorization: Bearer <token>.
businessId (required): Business identifier for lookup.
environment (optional): defaults to production if omitted.
searchProvider (optional): defaults to yelp in fetch flow if omitted.

Validation behavior:

If jwt or businessId is missing, component renders: Invalid token or business id.

`GlDynamicImageHandle` (ref API)

Exposed by src/gl-dynamic-image.tsx:

export type GlDynamicImageHandle = {
  reset: () => void;
  refresh: () => void;
};

Methods:

reset(): clear loaded preview state.
refresh(): fetch latest business data with current businessId and searchProvider.

`GlDynamicImageEvents` (Event bus)

Custom DOM Events are dispatched directly on the custom element host instance and bubble up with composed: true (since the Web Component renders inside a Shadow DOM root for CSS isolation):

gl:previewLoaded
- Fired when API response is successful and preview image has loaded.
- event.detail: { businessId, metadata }
gl:error
- Fired when request fails or required params are missing.
- event.detail: { error }

You can listen to these events directly on the Web Component instance (recommended):

const imageEl = document.querySelector('gl-dynamic-image');
imageEl.addEventListener('gl:previewLoaded', (e) => {
  console.log('Preview loaded on host element:', e.detail);
});

Or listen globally on the document object:

document.addEventListener('gl:previewLoaded', (e) => {
  console.log('Global preview loaded event:', e.detail);
});

Styling & Customization

Import dist/style.css to apply component styles.
The preview automatically scales content based on container size.
You can wrap the component in your own container and control width/height externally.

Web Component Usage

The package includes browser build support in this repository (src/web.ts, build:vite).

Shadow DOM Isolation

The Custom Element <gl-dynamic-image> uses Shadow DOM (mode: 'open') to isolate styles. This ensures that the component's inner layout and styles (Tailwind CSS) do not bleed out into the hosting website, and parent layout styles do not disrupt the component layout. CSS imports are bundled and injected directly into the shadow root at runtime.

Embedding Pattern

Include the global script in your HTML page:

<script src="/path/to/@gift-card-market/gl-dynamic-image/dist/browser/gl-dynamic-image.global.js"></script>

Then mount the element:

<gl-dynamic-image jwt="YOUR_JWT_TOKEN" businessId="YOUR_BUSINESS_ID" environment="production" searchProvider="yelp"></gl-dynamic-image>

API Endpoint

Current fetch call:

Method: GET
Path: /partner/web-component/api/v1/business-detail
Query:
- searchProvider
- businessId
Headers:
- Authorization: Bearer <jwt>
- Content-Type: application/json

Base domain is resolved from environment:

production -> https://partnerapi.giftcardmarket.com
staging -> https://stagepartnerapi.giftcardmarket.com
qa -> https://qapartnerapi.giftcardmarket.com
development -> https://devpartnerapi.giftcardmarket.com

Development & Build

Common scripts from package.json:

npm run dev
npm run build
npm run preview

Build command detail:

tsup
npx tailwindcss -i ./src/styles.css -o ./dist/style.css --minify

Project Layout (Summary)

src/
  components/
  lib/
    controller.ts
  types/
    gl-dynamic-image.ts
    form-handle.ts
  utils/
    apiDomain.ts
  gl-dynamic-image.tsx
  index.ts
  styles.css
  web.ts

Troubleshooting

Issue	Suggestion
`Invalid token or business id`	Check `data.jwt` and `data.businessId`.
No preview loaded	Verify JWT validity, API availability, and network/CORS.
No styles	Ensure `dist/style.css` is imported.
Unknown environment error	Use one of: `production`, `staging`, `qa`, `development`.

Changelog

Version 1.0.11 (Current)

🔒 Encapsulated CSS bleeding fixes (scoped variables and nested selectors).
⚙️ Added Tailwind utility prefix and configured important option.
📐 Fixed layout ratio stretching issue under CSS isolation.

Version 1.0.8

🔒 CSS is encapsulated inside the Shadow DOM to prevent layout bleeding.
📢 Custom events (gl:previewLoaded, gl:error) are dispatched directly on the custom element host.
⏳ Added a loading state while fetching business preview data, eliminating layout shifts and the flash of "Invalid Business Id".

Version 1.0.7

🐛 Bug fixes and stability improvements.

Contact

Gift Card Market Development Team

Table of Contents​

Features​

Requirements​

Installation​

1. Configure GitHub Packages (if package is still hosted on GitHub)​

2. Install package​

3. Import CSS​

Quick Start with React​

Basic Example​

Using Named Exports (without ref)​

Detailed API​

Props GlDynamicImage​

GlDynamicImageData​

GlDynamicImageHandle (ref API)​

GlDynamicImageEvents (Event bus)​

Styling & Customization​

Web Component Usage​

Shadow DOM Isolation​

Embedding Pattern​

API Endpoint​

Development & Build​

Project Layout (Summary)​

Troubleshooting​

Changelog​

Version 1.0.11 (Current)​

Version 1.0.8​

Version 1.0.7​

Contact​

Table of Contents