npm package: @korala/react
Description: React components and hooks for Korala document signing integration
Latest version: 1.0.1

# @korala/react

React components and hooks for embedding Korala document signing in your application.

## Installation

```bash
pnpm add @korala/react
```

## Usage

### KoralaSigner Component

The main component for embedding the signing experience:

```tsx
import { KoralaSigner } from '@korala/react';

function SigningPage({ signingToken }: { signingToken: string }) {
  return (
    <KoralaSigner
      token={signingToken}
      signingUrl="https://sign.yourdomain.com" // Optional, defaults to env var
      className="w-full h-[600px]"
      onReady={() => console.log('Embed ready')}
      onLoaded={(data) => console.log('Document loaded:', data)}
      onViewed={(data) => console.log('Document viewed:', data)}
      onFieldFilled={(data) => console.log('Field filled:', data)}
      onSigned={(data) => console.log('Document signed:', data)}
      onDeclined={(data) => console.log('Document declined:', data)}
      onError={(data) => console.error('Error:', data)}
    />
  );
}
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `token` | `string` | Yes | The signer's access token |
| `signingUrl` | `string` | No | Base URL of the signing app. Defaults to `NEXT_PUBLIC_KORALA_SIGNING_URL` env var |
| `className` | `string` | No | CSS class for the iframe |
| `style` | `CSSProperties` | No | Inline styles for the iframe |
| `allowedOrigins` | `string[]` | No | Restrict postMessage origins |
| `onReady` | `(data) => void` | No | Called when embed is initialized |
| `onLoaded` | `(data) => void` | No | Called when document is loaded |
| `onViewed` | `(data) => void` | No | Called when signer views the document |
| `onFieldFilled` | `(data) => void` | No | Called when a field is filled |
| `onSigned` | `(data) => void` | No | Called when signing is complete |
| `onDeclined` | `(data) => void` | No | Called when signer declines |
| `onError` | `(data) => void` | No | Called on errors |

### useKoralaEvents Hook

Alternative to callbacks - listen to all events via a hook:

```tsx
import { useKoralaEvents } from '@korala/react';

function SigningStatus() {
  const { status, events, lastEvent } = useKoralaEvents();

  return (
    <div>
      <p>Status: {status}</p>
      <p>Events received: {events.length}</p>
    </div>
  );
}
```

Returns:
- `status`: `'loading' | 'ready' | 'loaded' | 'viewed' | 'signing' | 'signed' | 'declined' | 'error'`
- `events`: Array of all received events
- `lastEvent`: Most recent event
- `clearEvents`: Function to clear stored events

## Event Data Types

### LoadedEventData
```ts
{
  documentId: string;
  documentName: string;
  signerName: string;
  signerEmail: string;
  totalFields: number;
  requiredFields: number;
}
```

### SignedEventData
```ts
{
  documentId: string;
  signerId: string;
  signedAt: string;
}
```

### DeclinedEventData
```ts
{
  documentId: string;
  signerId: string;
  reason?: string;
  declinedAt: string;
}
```

### ErrorEventData
```ts
{
  code: string;
  message: string;
  recoverable: boolean;
}
```

## Environment Variables

Set in your `.env.local`:

```
NEXT_PUBLIC_KORALA_SIGNING_URL=http://localhost:3003
```