npm package: @h2games/feedback
Description: A lightweight Lit web component for collecting user feedback via Lark/Feishu webhooks
Author: im-cho
Latest version: 1.0.2

# @h2games/feedback

A lightweight Lit web component for collecting user feedback (bug reports & suggestions) and delivering them to a Lark/Feishu group chat via Custom Bot Webhook.

[Live Demo](https://stackblitz.com/edit/h2games-feedback)

## Installation

```bash
npm install @h2games/feedback
```

> **Peer dependencies:** `lit ^3.0.0` is required. `react ^18 || ^19` is optional (only needed if using the React wrapper).

## Quick Start

### 1. Next.js

Web components require client-side rendering. Create a wrapper component:

```tsx
// components/feedback-widget-wrapper.tsx
"use client";

import dynamic from "next/dynamic";

const FeedbackWidget = dynamic(
  () =>
    import("@h2games/feedback/react").then((mod) => ({
      default: mod.FeedbackWidget,
    })),
  { ssr: false },
);

export const FeedbackWidgetWrapper = (
  props: React.ComponentProps<typeof FeedbackWidget>,
) => {
  return <FeedbackWidget {...props} />;
};
```

Then use it in your layout:

```tsx
// app/layout.tsx
import { FeedbackWidgetWrapper } from "@/components/feedback-widget-wrapper";

export default function Layout({ children }) {
  return (
    <>
      {children}
      <FeedbackWidgetWrapper
        webhookUrl="https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID"
        appName="My App"
      />
    </>
  );
}
```

### 2. Vite + React

```tsx
import { FeedbackWidget } from "@h2games/feedback/react";

export default function App() {
  return (
    <FeedbackWidget
      webhookUrl="https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID"
      appName="My App"
    />
  );
}
```

### 3. Vanilla JS / Any Framework

```html
<script type="module">
  import { FeedbackWidget } from "@h2games/feedback";

  FeedbackWidget.configure({
    webhookUrl: "https://open.feishu.cn/open-apis/bot/v2/hook/YOUR_HOOK_ID",
    appName: "My App",
  });
</script>

<feedback-widget></feedback-widget>
```

## Props / Config

| Property     | Type                              | Required | Default          | Description                           |
| ------------ | --------------------------------- | -------- | ---------------- | ------------------------------------- |
| `webhookUrl` | `string`                          | Yes      | —                | Feishu Custom Bot webhook URL         |
| `secret`     | `string`                          | No       | —                | Signing secret (if signature enabled) |
| `appName`    | `string`                          | No       | `document.title` | App name shown in the Feishu message  |
| `position`   | `'bottom-right' \| 'bottom-left'` | No       | `'bottom-right'` | Which corner the FAB appears in       |

## CSS Custom Properties

Override these on the `feedback-widget` element to customise appearance and position:

```css
feedback-widget {
  /* Position offsets */
  --fb-offset-x: 24px;
  --fb-offset-y: 24px;

  /* Colors */
  --fb-primary: #3370ff;
  --fb-primary-hover: #2860e0;
  --fb-danger: #f54a45;
  --fb-success: #34c724;

  /* Layout */
  --fb-radius: 8px;
  --fb-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
}
```

## Webhook Setup

1. Open a **Feishu/Lark** group chat
2. Go to **Settings > Bots > Add Bot > Custom Bot**
3. Copy the **Webhook URL** — this is your `webhookUrl`
4. _(Optional)_ Enable **Signature Verification** and copy the secret — this is your `secret`

## Form Fields

The widget collects:

- **Type** — Bug Report or Suggestion
- **Name** — required
- **Email** — optional
- **Description** — required (10+ characters)
- **Page URL** — captured automatically

## Changelog

### 1.0.2

- Added link to the demo

### 1.0.0

- Initial release
- Feedback widget with bug report & suggestion types
- Lark/Feishu webhook integration with optional HMAC-SHA256 signing
- React wrapper component
- CSS custom properties for theming
- Configurable position (bottom-right / bottom-left)

## License

MIT