npm package: @signal-js/react
Description: React hooks and components for Signal SDK
Latest version: 1.0.6

# @signal-js/react

React hooks and components for Signal SDK. Uses **@signal-js/browser** for the core SDK (included as a dependency).

## Installation

```bash
npm install @signal-js/react
# or
pnpm add @signal-js/react
# or
yarn add @signal-js/react
```

## Quick Start

### Provider Setup

```tsx
import { SignalProvider } from '@signal-js/react';

function App() {
  return (
    <SignalProvider
      options={{
        endpoint: 'https://your-api.com/events',
        apiKey: 'your-api-key',
        projectId: 'your-project-id',
        enableSessionReplay: true,
      }}
    >
      <YourApp />
    </SignalProvider>
  );
}
```

### Using Hooks

```tsx
import { useSignal, useSignalCapture, usePageView } from '@signal-js/react';

function MyComponent() {
  const { capture, identify, group, isRecording } = useSignal();
  
  // Track page view on mount
  usePageView('dashboard');
  
  const handleLogin = (user) => {
    // Identify the user
    identify(user.id, {
      email: user.email,
      name: user.name,
    });
    
    // Associate with company
    group('company', user.companyId);
  };
  
  const handleClick = () => {
    capture('button_clicked', { buttonId: 'submit' });
  };
  
  return (
    <div>
      <p>Recording: {isRecording ? 'Yes' : 'No'}</p>
      <button onClick={handleClick}>Submit</button>
    </div>
  );
}
```

## Hooks

### `useSignal()`

Main hook for accessing Signal SDK.

```tsx
const {
  signal,           // SignalJS instance
  isInitialized,    // Boolean
  isRecording,      // Boolean
  sessionId,        // Current session ID
  distinctId,       // Current user ID
  capture,          // (event, properties?) => void
  identify,         // (distinctId, traits?) => void
  group,            // (groupType, groupKey, properties?) => void
  register,         // (properties) => void
  reset,            // () => void
  startRecording,   // () => Promise<void>
  stopRecording,    // () => void
  pauseRecording,   // () => void
  resumeRecording,  // () => void
  flush,            // () => Promise<void>
} = useSignal();
```

### `useSignalCapture()`

Returns a memoized capture function.

```tsx
const capture = useSignalCapture();
capture('event_name', { property: 'value' });
```

### `useSignalIdentify()`

Hook for user identification.

```tsx
const { identify, distinctId, reset } = useSignalIdentify();
identify('user-123', { email: 'user@example.com' });
```

### `useSignalGroup()`

Hook for group management.

```tsx
const { group, getGroups } = useSignalGroup();
group('company', 'acme-corp', { plan: 'enterprise' });
```

### `useSignalSession()`

Hook for session information.

```tsx
const { sessionId, windowId, sessionDuration, isRecording } = useSignalSession();
```

### `usePageView()`

Captures page view on mount.

```tsx
usePageView('dashboard', { section: 'analytics' });
```

### `useTrackEvent()`

Returns a typed capture function for a specific event.

```tsx
const trackPurchase = useTrackEvent<{ amount: number }>('purchase');
trackPurchase({ amount: 99.99 });
```

## HOC

### `withSignal()`

Higher-order component for class components.

```tsx
import { withSignal, WithSignalProps } from '@signal-js/react';

class MyComponent extends React.Component<Props & WithSignalProps> {
  handleClick = () => {
    this.props.signal?.capture('clicked');
  };
  
  render() {
    return <button onClick={this.handleClick}>Click</button>;
  }
}

export default withSignal(MyComponent);
```

## License

MIT