@agentaily/feedback-widget

一个可嵌入任意 React 站点的**「评审模式」。开开关 → hover 高亮 + 点选任意元素** → 写意见 → 提交。提交会发到共享的 agentaily-feedback Worker,由它在 agentaily/agentaily 里开一个带着这条笔记(一份 reviews/<ts>.md 文件)的 GitHub PR。

• 零硬依赖 —— React 是 peerDependency;不依赖 @agentaily/design-system(借用了它的视觉语汇 —— geek-blue 高亮框 / 角标 chip / 胶囊 —— 但并不 import),所以它能落进任意 React 应用,包括外部仓库。
• 为每个元素挑一个尽量稳定的定位:data-testid → 稳定 id → data-mk-label → 一段短 CSS 路径,外加最近的 React 组件名(从 fiber 上读出)。与 @agentaily/storybook-addon-review 的定位逻辑一致。
• 优雅降级:没配 endpoint 时,你仍可选元素 + 写意见,但提交被禁用并给出提示。

Install

npm i @agentaily/feedback-widget            # external repo (e.g. the official website)
# inside this monorepo it's a workspace dep: "@agentaily/feedback-widget": "workspace:*"

Use

import { FeedbackWidget } from '@agentaily/feedback-widget';

<FeedbackWidget
  endpoint="https://agentaily-feedback.<account>.workers.dev" // the agentaily-feedback Worker
  site="official-website"                                       // identifies the source
  route="/pricing"                                              // optional logical route
/>;

把它在应用根附近只挂载一次,这样那个浮动启动器就在全应用范围可用。它会自己注入一次 <style>,并在极高的 z-index 上渲染一个 fixed 定位的浮层 —— 无需 import 任何 CSS。

Props

Prop	Type	Notes
endpoint	string?	agentaily-feedback Worker 的 URL。falsy → 禁用提交 + 提示(静态 / 无后端)。
site	string	随每次提交一起发送(如 "official-website" / "chatapp")。
route	string?	可选的逻辑路由 / 页面名,随每次提交一起发送。
defaultEnabled	boolean?	是否以评审模式启动(默认 false —— 启动器可见,模式关闭)。
label	string?	浮动启动器上的文字(默认 "评审反馈")。
onSubmitted	(r: SubmitResult) => void	PR 开好后被调用。

Keyboard

• 在笔记框里 Cmd/Ctrl + Enter → 提交。
• Esc → 关闭弹框,或退出评审模式。

Wire shape

widget 向 endpoint POST JSON:

interface FeedbackSubmission {
  site: string;
  url?: string;          // window.location.href at submit time
  route?: string;
  comment: string;       // the reviewer's note (required)
  selector?: Locator | null;   // the picked element (see below)
  screenshot?: string | null;  // forward-compat; not yet embedded in the PR
}
interface Locator {
  selector: string | null; component: string | null; tag: string;
  testid: string | null; mkLabel: string | null; id: string | null;
  classes: string[]; text: string | null;
  rect?: { left: number; top: number; width: number; height: number };
}

Worker 回复 { ok: true, url, number }(PR URL + 编号)或 { ok: false, error }。后端见 apps/feedback,部署 + GITHUB_TOKEN secret 见 OPERATIONS.md。

submitFeedback、buildLocator、locatorLabel 也一并导出,供进阶用法 / 测试使用。

Build & test

pnpm --filter @agentaily/feedback-widget build   # tsup → dist/index.js (ESM) + dist/index.d.ts
pnpm --filter @agentaily/feedback-widget test    # vitest (jsdom + @testing-library/react)

dist/ 被 gitignore;pnpm build(turbo)会在 apps/web 之前按依赖顺序重建它。

Publishing to external repos

本包可发布(exports 指向构建产物 dist/)。对于官网(一个独立仓库),要么在它上了 registry 后 npm i @agentaily/feedback-widget,要么 vendor 进 dist/ + package.json。无论哪种方式,挂上 <FeedbackWidget endpoint=… site="official-website" /> 并把 endpoint 指向已部署的 agentaily-feedback Worker。该 Worker 的 CORS 白名单已覆盖 agentaily.com / *.agentaily.com / agentaily.pages.dev / localhost。