npm package: @plmojica/feedback-widget
Description: A framework-agnostic feedback widget that creates GitHub Issues
Latest version: 0.5.3

# @plmojica/feedback-widget

A framework-agnostic feedback widget that lets users submit bug reports and feature requests directly as GitHub Issues. Built as a Web Component with Shadow DOM for style isolation.

## Features

- **Web Component** — works with any framework or plain HTML
- **Shadow DOM** — widget styles are fully isolated from the host page
- **GitHub Issues integration** — submissions create issues with structured Markdown bodies
- **Element selector** — users can click any element to attach it to their report
- **Screenshots** — capture the page, paste from clipboard, or drag-and-drop images
- **Configurable** — theme colors, border radius, placement, project name, and default labels

## Installation

```bash
npm install @plmojica/feedback-widget
```

Or via CDN:

```html
<script src="https://unpkg.com/@plmojica/feedback-widget"></script>
```

## Prerequisites

This widget requires a backend proxy to securely create GitHub Issues and generate client keys. See the [backend setup guide](https://github.com/plmojica/feedback-widget#set-up-the-backend) for details.

## Usage

### Via JavaScript (recommended)

```js
import { createFeedbackWidget } from "@plmojica/feedback-widget";

const widget = createFeedbackWidget({
  proxyUrl: "https://your-backend.example.com",
  clientKey: "fwk_xxxxxxxxxxxxxxxxx",
  repo: "owner/repo",
  projectName: "My App",
  theme: {
    primaryColor: "#3b82f6",
  },
});
```

### Via CDN (script tag)

```html
<script src="https://unpkg.com/@plmojica/feedback-widget"></script>
<script>
  FeedbackWidget.createFeedbackWidget({
    proxyUrl: "https://your-backend.example.com",
    clientKey: "fwk_xxxxxxxxxxxxxxxxx",
    repo: "owner/repo",
    projectName: "My App",
  });
</script>
```

Pin a specific version:

```html
<script src="https://unpkg.com/@plmojica/feedback-widget@0.1.0"></script>
```

Or use jsDelivr:

```html
<script src="https://cdn.jsdelivr.net/npm/@plmojica/feedback-widget"></script>
```

### Via HTML attributes

```html
<script src="https://unpkg.com/@plmojica/feedback-widget"></script>

<feedback-widget
  proxy-url="https://your-backend.example.com"
  client-key="fwk_xxxxxxxxxxxxxxxxx"
  repo="owner/repo"
  project-name="My App"
></feedback-widget>
```

### Via `configure()` method

```js
const widget = document.createElement("feedback-widget");
widget.configure({
  proxyUrl: "https://your-backend.example.com",
  clientKey: "fwk_xxxxxxxxxxxxxxxxx",
  repo: "owner/repo",
  projectName: "My App",
  placement: "bottom-left",
  labels: ["feedback"],
  theme: {
    primaryColor: "#8b5cf6",
    backgroundColor: "#ffffff",
    textColor: "#1f2937",
    borderRadius: "12px",
  },
});
document.body.appendChild(widget);
```

## Configuration

### Widget options

| Option        | Type                              | Required | Default          | Description                               |
| ------------- | --------------------------------- | -------- | ---------------- | ----------------------------------------- |
| `proxyUrl`    | `string`                          | Yes      | —                | URL of the backend proxy                  |
| `clientKey`   | `string`                          | No\*     | —                | Key field sent as `X-Feedback-Client-Key` |
| `repo`        | `string`                          | Yes      | —                | Target GitHub repo in `owner/repo` format |
| `projectName` | `string`                          | No       | —                | Label shown in issue metadata             |
| `placement`   | `'bottom-right' \| 'bottom-left'` | No       | `'bottom-right'` | Default anchor before user drag overrides |
| `labels`      | `string[]`                        | No       | `[]`             | Default labels applied to created issues  |
| `theme`       | `Partial<FeedbackTheme>`          | No       | See below        | Visual customization                      |

\* `clientKey` is required once backend legacy fallback is disabled.

Users can drag the widget (launcher or toolbar area), and the last dragged position is saved in `localStorage` per repo.

### Theme defaults

| Property          | Default   |
| ----------------- | --------- |
| `primaryColor`    | `#3b82f6` |
| `backgroundColor` | `#ffffff` |
| `textColor`       | `#1f2937` |
| `borderRadius`    | `8px`     |

## License

MIT