npm package: @preview-kit/react
Description: PreviewKit React components and vanilla JS widget for adding comments and feedback to your web applications
Latest version: 0.1.17

# @preview-kit/react

A flexible comment and feedback widget that can be used both as a React component library and as a vanilla JavaScript widget.

## 📦 Installation

### As a React Library (NPM Package)

```bash
npm install @preview-kit/react
# or
pnpm add @preview-kit/react
# or
yarn add @preview-kit/react
```

### As a Vanilla JavaScript Widget

Download the prebuilt JavaScript file or use a CDN:

```html
<!-- Via CDN -->
<script src="https://cdn.jsdelivr.net/npm/@preview-kit/react/dist/browser/previewkit.min.js"></script>
```

## 🚀 Usage

### React Library Usage

```tsx
import { PreviewKitWidget, ThemeProvider } from "@preview-kit/react"

function App() {
	return (
		<ThemeProvider theme="light">
			<div>
				<h1>My App</h1>
				<PreviewKitWidget
					apiUrl="https://your-api.com"
					projectId="your-project-id"
				/>
			</div>
		</ThemeProvider>
	)
}
```

#### Advanced React Usage

```tsx
import {
	PreviewKitWidget,
	ThemeProvider,
	ShortcutProvider,
	useAppStore,
} from "@preview-kit/react"

function MyComponent() {
	const { comments, addComment } = useAppStore()

	return (
		<ThemeProvider theme="dark">
			<ShortcutProvider shortcuts={{ toggle: "cmd+/" }}>
				<PreviewKitWidget
					apiUrl="https://your-api.com"
					projectId="your-project-id"
					onCommentAdd={(comment) => {
						console.log("New comment:", comment)
					}}
				/>
			</ShortcutProvider>
		</ThemeProvider>
	)
}
```

### Vanilla JavaScript Usage

The vanilla JavaScript version automatically mounts the widget:

```html
<!DOCTYPE html>
<html>
	<head>
		<title>My Website</title>
	</head>
	<body>
		<h1>My Website</h1>
		<p>Content goes here...</p>

		<!-- PreviewKit will automatically mount -->
		<script src="https://cdn.jsdelivr.net/npm/@preview-kit/react/dist/browser/previewkit.min.js"></script>

		<script>
			// Optional: Configure after load
			window.addEventListener("previewkit:ready", () => {
				console.log("PreviewKit is ready!")
			})
		</script>
	</body>
</html>
```

## 📋 API Reference

### React Components

#### `<PreviewKitWidget>`

Main widget component for React applications.

**Props:**

| Prop           | Type                                                           | Required | Description                               |
| -------------- | -------------------------------------------------------------- | -------- | ----------------------------------------- |
| `apiUrl`       | `string`                                                       | Yes      | Your PreviewKit API endpoint              |
| `projectId`    | `string`                                                       | Yes      | Your project identifier                   |
| `theme`        | `'light' \| 'dark' \| 'auto'`                                  | No       | Widget theme (default: 'auto')            |
| `position`     | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | No       | Widget position (default: 'bottom-right') |
| `onCommentAdd` | `(comment: Comment) => void`                                   | No       | Callback when comment is added            |

### Vanilla JavaScript API

#### Global Methods

| Method                                 | Description              |
| -------------------------------------- | ------------------------ |
| `window.PreviewKit.show()`             | Show the widget          |
| `window.PreviewKit.hide()`             | Hide the widget          |
| `window.PreviewKit.toggle()`           | Toggle widget visibility |
| `window.PreviewKit.configure(options)` | Update configuration     |

#### Events

| Event              | Payload   | Description                |
| ------------------ | --------- | -------------------------- |
| `previewkit:ready` | `null`    | Widget is loaded and ready |
| `comment:add`      | `Comment` | New comment was added      |