@8ui/iframe-widget-core

Universal widget core for iframe-based services (iframe side).

This package provides React hooks and utilities for creating widgets that communicate with parent SDKs via PostMessage.

Features

• createWidgetCommunication: Imperative API for non-React contexts
• useWidgetCommunication: Unified hook for widget communication
• useMessageListener: Hook for listening to parent messages
• useParentCommunication: Hook for sending messages to parent
• Utilities: Message factory, validators, origin checker

Installation

npm install @8ui/iframe-widget-core

Note: This package requires React >= 17.0.0 as a peer dependency.

Usage

Imperative API (Non-React contexts)

Use createWidgetCommunication when you need to send messages from outside React components (setTimeout, async functions, event listeners, utility modules, etc.).

Step 1: Create instance at app initialization

// src/lib/widgetComm.ts
import { createWidgetCommunication } from '@8ui/iframe-widget-core';

export const widgetComm = createWidgetCommunication({
  widgetType: 'messaging',
  trustedOrigins: ['https://example.com'],
  enableLogging: false, // optional
});

Step 2: Use anywhere in your code

// src/utils/auth.ts
import { widgetComm } from '@/lib/widgetComm';

async function refreshToken() {
  try {
    const result = await fetch('/api/refresh');
    widgetComm.sendMessage('TOKEN_REFRESHED', { expiresAt: '...' });
  } catch (error) {
    widgetComm.sendError({ code: 'AUTH_FAILED' });
  }
}

// Works in setTimeout, setInterval, etc.
setTimeout(() => {
  widgetComm.sendMessage('HEARTBEAT', { timestamp: Date.now() });
}, 60000);

Available methods:

• sendMessage(type, payload) - Send any message to parent
• sendReady(data?) - Send APP_READY message
• sendCompleted(result) - Send COMPLETED message
• sendError(error) - Send ERROR message
• requestClose(reason?) - Request parent to close the widget
• isInIframe() - Check if running inside an iframe
• isTrustedOrigin(origin) - Check if origin is trusted

React Hook API

Use useWidgetCommunication inside React components for full communication with automatic message handling.

import { useWidgetCommunication } from '@8ui/iframe-widget-core';

function MyWidget() {
  const { sendMessage, sendCompleted, isInitialized } = useWidgetCommunication({
    widgetType: 'my-widget',
    onThemeChange: (theme) => {
      // Apply theme
    },
    onConfigReceived: (config) => {
      // Handle config
    },
    autoSendReady: true,
  });

  if (!isInitialized) {
    return <div>Loading...</div>;
  }

  const handleComplete = () => {
    sendCompleted({ result: 'success' });
  };

  return (
    <div>
      <button onClick={handleComplete}>Complete</button>
    </div>
  );
}

API

See the TypeScript types for full API documentation.

License

MIT