review-lens-react 0.1.0

package/README.md

@@ -0,0 +1,352 @@
+# review-lens-react
+
+`review-lens-react` is a React overlay for UX reviews inside frontend apps. Designers can inspect real DOM elements, see computed spacing and typography details, lock an element, write feedback, and store that feedback in Google Sheets. Developers can open the same app, see page comments anchored to selectors, and resolve feedback while implementing the review.
+
+The package is intended to be mounted by the host app only when review mode is needed. It does not add a global launcher by default.
+
+## Features
+
+- Inspect elements in-place with a visual overlay.
+- Capture padding, margin, border, dimensions, font size, line height, colors, and selector metadata.
+- Prefer stable selectors such as `data-review-id`, `data-testid`, `id`, `aria-label`, and `name`.
+- Fall back to a generated CSS path when no stable attribute exists.
+- Save feedback with selector, URL, content id, author, status, timestamps, CSS snapshot, and element fingerprint.
+- Match feedback across localhost and production by `projectKey`, `contentId`, and normalized path.
+- Use Google OAuth in the browser and Google Sheets as the feedback store.
+- Support panel placement in all four corners.
+
+## Install
+
+```sh
+npm install review-lens-react
+```
+
+Import the component and its CSS once in the host app.
+
+```tsx
+import {
+  ReviewLensOverlay,
+  ReviewLensProvider
+} from "review-lens-react";
+import "review-lens-react/styles.css";
+```
+
+## Basic Usage
+
+```tsx
+import { useState } from "react";
+import {
+  ReviewLensOverlay,
+  ReviewLensProvider
+} from "review-lens-react";
+import "review-lens-react/styles.css";
+
+export function AppReviewMode() {
+  const [reviewOpen, setReviewOpen] = useState(false);
+
+  return (
+    <ReviewLensProvider
+      config={{
+        googleClientId: import.meta.env.VITE_GOOGLE_CLIENT_ID,
+        spreadsheetId: import.meta.env.VITE_REVIEW_LENS_SPREADSHEET_ID,
+        projectKey: "landing-pages-app",
+        contentId: "article-123"
+      }}
+    >
+      <button type="button" onClick={() => setReviewOpen(true)}>
+        Start UX review
+      </button>
+
+      <ReviewLensOverlay
+        open={reviewOpen}
+        onOpenChange={setReviewOpen}
+        placement="top-right"
+      />
+    </ReviewLensProvider>
+  );
+}
+```
+
+Add stable attributes to important review targets when possible:
+
+```tsx
+<button data-review-id="hero-cta">Register now</button>
+```
+
+## API
+
+### `ReviewLensProvider`
+
+Wrap the host app or the reviewed page area.
+
+```tsx
+<ReviewLensProvider config={config}>{children}</ReviewLensProvider>
+```
+
+Config:
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `googleClientId` | yes, unless `adapter` is provided | OAuth web client id from Google Cloud. |
+| `spreadsheetId` | yes, unless `adapter` is provided | Google Sheet id from the Sheet URL. |
+| `sheetName` | no | Feedback sheet name. Defaults to `Feedback`. |
+| `projectKey` | yes | Stable app/project key, for example `landing-pages-app`. |
+| `contentId` | yes | Stable content key shared by localhost and production. |
+| `currentUrl` | no | URL to store and normalize. Defaults to `window.location.href`. |
+| `normalizeUrl` | no | Custom URL normalization function. |
+| `adapter` | no | Custom storage adapter for tests, demos, or a future backend. |
+
+### `ReviewLensOverlay`
+
+Render this when review mode should be available.
+
+```tsx
+<ReviewLensOverlay
+  open={reviewOpen}
+  onOpenChange={setReviewOpen}
+  placement="bottom-left"
+  showResolved={false}
+/>
+```
+
+Props:
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `open` | yes | Controls whether the overlay is active. |
+| `onOpenChange` | no | Called when the overlay requests closing. |
+| `placement` | no | `top-left`, `top-right`, `bottom-left`, or `bottom-right`. Defaults to `top-right`. |
+| `showResolved` | no | Shows resolved comments when true. Defaults to false. |
+
+## Google Setup
+
+The default adapter uses Google Identity Services in the browser and the Google Sheets API. No API key is required.
+
+Official references:
+
+- Google Identity Services token model: https://developers.google.com/identity/oauth2/web/guides/use-token-model
+- Google Identity Services setup: https://developers.google.com/identity/oauth2/web/guides/load-3p-authorization-library
+- Google Sheets API values guide: https://developers.google.com/workspace/sheets/api/guides/values
+- Google Sheets `values.append`: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append
+
+### 1. Create or choose a Google Cloud project
+
+Open Google Cloud Console and choose the project that should own the OAuth client.
+
+### 2. Enable Google Sheets API
+
+In Google Cloud Console:
+
+1. Go to `APIs & Services`.
+2. Enable `Google Sheets API`.
+
+### 3. Configure OAuth consent
+
+In Google Cloud Console:
+
+1. Open the Google Auth Platform or OAuth consent configuration.
+2. Use `Internal` if the app should only be available inside your Google Workspace organization.
+3. Add the app name, support email, and developer contact.
+4. Add these scopes:
+
+```text
+https://www.googleapis.com/auth/spreadsheets
+https://www.googleapis.com/auth/userinfo.email
+```
+
+The Sheets scope is used to read/write feedback rows. The email scope is used to match the signed-in Google account against the `Users` tab.
+
+### 4. Create an OAuth web client
+
+In Google Cloud Console:
+
+1. Go to `APIs & Services` -> `Credentials`.
+2. Create an OAuth client.
+3. Choose `Web application`.
+4. Add authorized JavaScript origins for every host that will run review mode.
+
+Examples:
+
+```text
+http://localhost:5173
+http://localhost:3000
+https://your-staging-app.example.com
+https://your-production-app.example.com
+```
+
+Use the generated client id as `googleClientId`.
+
+### 5. Create the Google Sheet
+
+Create one shared Google Sheet and copy its id from the URL:
+
+```text
+https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit
+```
+
+Share the Sheet with every reviewer/developer who should use the overlay. Users need Sheet access because the browser writes directly to the Google Sheets API as the signed-in user.
+
+### 6. Add the `Feedback` tab
+
+Create a tab named `Feedback` with this exact header row:
+
+```csv
+id,projectKey,contentId,normalizedPath,originalUrl,selector,selectorStrategy,elementFingerprintJson,cssSnapshotJson,comment,status,authorEmail,createdAt,updatedAt,resolvedAt,resolvedBy
+```
+
+The library appends new feedback rows and updates existing rows when feedback is resolved.
+
+### 7. Add the `Users` tab
+
+Create a tab named `Users` with this header row:
+
+```csv
+email,role,active,projectKey
+```
+
+Example rows:
+
+```csv
+designer@example.com,designer,true,landing-pages-app
+developer@example.com,developer,true,landing-pages-app
+lead@example.com,admin,true,
+```
+
+Roles:
+
+| Role | Permissions |
+| --- | --- |
+| `designer` | Read and create feedback. |
+| `developer` | Read feedback and resolve it. |
+| `admin` | Read, create, and resolve feedback. |
+
+If `projectKey` is empty, the user role applies to every project using the Sheet. If `active` is `false`, the row is ignored.
+
+## URL and Content Matching
+
+Feedback is loaded by:
+
+- `projectKey`
+- `contentId`
+- normalized path
+
+By default, the normalizer removes origin, port, query params, hashes, and trailing slashes. This means these URLs match the same feedback when `projectKey` and `contentId` are equal:
+
+```text
+https://www.example.com/articles/123?utm_source=newsletter
+http://localhost:5173/articles/123
+```
+
+If your app has a different URL model, pass a custom normalizer:
+
+```tsx
+<ReviewLensProvider
+  config={{
+    googleClientId,
+    spreadsheetId,
+    projectKey: "landing-pages-app",
+    contentId: article.id,
+    normalizeUrl: (url) => new URL(url).pathname.replace(/^\/preview/, "")
+  }}
+>
+  {children}
+</ReviewLensProvider>
+```
+
+## Local Development
+
+This repository contains the package and a demo app.
+
+```sh
+npm install
+npm run dev --workspace review-lens-demo
+npm test
+npm run typecheck
+npm run build
+```
+
+The demo uses an in-memory adapter, so it does not require Google credentials.
+
+## Custom Adapter
+
+Use a custom adapter when testing, demoing, or replacing direct Google Sheets access with a backend later.
+
+```tsx
+const adapter = {
+  async getCurrentUser() {
+    return { email: "designer@example.com" };
+  },
+  async getPermissions() {
+    return ["create", "read", "resolve"];
+  },
+  async listFeedback(params) {
+    return [];
+  },
+  async createFeedback(input) {
+    return {
+      ...input,
+      id: crypto.randomUUID(),
+      status: "open",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+  },
+  async resolveFeedback(id, resolvedBy) {
+    throw new Error("Implement resolveFeedback");
+  }
+};
+```
+
+Then pass it to the provider:
+
+```tsx
+<ReviewLensProvider
+  config={{
+    adapter,
+    projectKey: "demo",
+    contentId: "article-123"
+  }}
+>
+  {children}
+</ReviewLensProvider>
+```
+
+## Troubleshooting
+
+### Google sign-in popup does not work
+
+Check that the current origin is listed as an authorized JavaScript origin on the OAuth web client. The origin must include protocol and host, for example `http://localhost:5173`.
+
+### `Google Sheets request failed with 403`
+
+Check that:
+
+- Google Sheets API is enabled.
+- The signed-in user has access to the Sheet.
+- OAuth consent includes the Sheets scope.
+- The Sheet id is correct.
+
+### The user can sign in but has the wrong permissions
+
+Check the `Users` tab:
+
+- `email` must match the Google account email.
+- `active` must not be `false`.
+- `role` must be `designer`, `developer`, or `admin`.
+- `projectKey` must be empty or match the provider config.
+
+### Feedback does not appear on localhost
+
+Check that production and localhost pass the same `projectKey`, the same `contentId`, and normalize to the same path. Use `normalizeUrl` when the routes differ between environments.
+
+### Markers do not anchor after DOM changes
+
+Prefer stable attributes on important elements:
+
+```tsx
+data-review-id="hero-cta"
+data-testid="registration-form"
+```
+
+Generated CSS paths work, but they are more likely to break when DOM structure changes.
+

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import "./styles.css";
+export { ReviewLensProvider, useReviewLens } from "./review-lens-provider";
+export { ReviewLensOverlay } from "./review-lens-overlay";
+export type { ReviewLensOverlayPlacement } from "./review-lens-overlay";
+export { createGoogleSheetsAdapter } from "./sheets/google-sheets-adapter";
+export { buildElementTarget } from "./selectors/build-element-target";
+export { normalizeReviewUrl } from "./url/normalize-review-url";
+export type { CssSnapshot, CreateFeedbackInput, ElementFingerprint, FeedbackStatus, ReviewLensAdapter, ReviewLensConfig, ReviewLensFeedback, ReviewLensPermission, ReviewLensRole, ReviewLensTarget } from "./types";

package/dist/review-lens-overlay.d.ts

@@ -0,0 +1,9 @@
+type ReviewLensOverlayProps = {
+    open: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placement?: ReviewLensOverlayPlacement;
+    showResolved?: boolean;
+};
+export type ReviewLensOverlayPlacement = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+export declare function ReviewLensOverlay({ open, onOpenChange, placement, showResolved }: ReviewLensOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/review-lens-provider.d.ts

@@ -0,0 +1,17 @@
+import type { CreateFeedbackInput, ReviewLensAdapter, ReviewLensConfig, ReviewLensFeedback, ReviewLensPermission, ReviewLensProviderProps } from "./types";
+type ReviewLensContextValue = {
+    config: ReviewLensConfig;
+    adapter: ReviewLensAdapter;
+    currentUser?: {
+        email: string;
+    };
+    permissions: ReviewLensPermission[];
+    feedback: ReviewLensFeedback[];
+    normalizedPath: string;
+    refreshFeedback: () => Promise<void>;
+    createFeedback: (input: CreateFeedbackInput) => Promise<ReviewLensFeedback>;
+    resolveFeedback: (id: string) => Promise<ReviewLensFeedback>;
+};
+export declare function ReviewLensProvider({ config, children }: ReviewLensProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useReviewLens(): ReviewLensContextValue;
+export {};

package/dist/review-lens-react.js

@@ -0,0 +1,576 @@
+import { jsx as c, jsxs as k, Fragment as q } from "react/jsx-runtime";
+import { createContext as D, useMemo as x, useState as E, useCallback as L, useEffect as R, useContext as H } from "react";
+const W = [
+  "https://www.googleapis.com/auth/spreadsheets",
+  "https://www.googleapis.com/auth/userinfo.email"
+].join(" "), _ = "https://www.googleapis.com/oauth2/v3/userinfo";
+function X(e) {
+  const n = e.feedbackSheetName ?? "Feedback", t = e.usersSheetName ?? "Users";
+  let r, o;
+  async function s() {
+    return r ?? (r = Z(e.googleClientId)), r;
+  }
+  async function v(i, l) {
+    const a = await s(), d = await fetch(
+      `https://sheets.googleapis.com/v4/spreadsheets/${e.spreadsheetId}${i}`,
+      {
+        ...l,
+        headers: {
+          Authorization: `Bearer ${a}`,
+          "Content-Type": "application/json",
+          ...l == null ? void 0 : l.headers
+        }
+      }
+    );
+    if (!d.ok)
+      throw new Error(`Google Sheets request failed with ${d.status}`);
+    return d.json();
+  }
+  async function b(i) {
+    return (await v(
+      `/values/${encodeURIComponent(i)}`
+    )).values ?? [];
+  }
+  return {
+    async getCurrentUser() {
+      if (!o) {
+        const i = await s(), l = await fetch(_, {
+          headers: { Authorization: `Bearer ${i}` }
+        });
+        if (!l.ok)
+          throw new Error(`Google userinfo request failed with ${l.status}`);
+        o = (await l.json()).email;
+      }
+      if (!o)
+        throw new Error("Google account did not return an email address");
+      return { email: o };
+    },
+    async getPermissions(i) {
+      const [{ email: l }, a] = await Promise.all([this.getCurrentUser(), b(t)]), d = U(a), y = l.toLowerCase(), u = d.find(
+        (f) => {
+          var p;
+          return ((p = f.email) == null ? void 0 : p.toLowerCase()) === y && f.active !== "false" && (!f.projectKey || f.projectKey === i);
+        }
+      );
+      return V((u == null ? void 0 : u.role) ?? "designer");
+    },
+    async listFeedback(i) {
+      return U(await b(n)).map(T).filter((a) => a !== null).filter(
+        (a) => a.projectKey === i.projectKey && a.contentId === i.contentId && a.normalizedPath === i.normalizedPath
+      ).sort((a, d) => d.createdAt.localeCompare(a.createdAt));
+    },
+    async createFeedback(i) {
+      const l = (/* @__PURE__ */ new Date()).toISOString(), a = {
+        ...i,
+        id: crypto.randomUUID(),
+        status: "open",
+        createdAt: l,
+        updatedAt: l
+      };
+      return await v(`/values/${encodeURIComponent(n)}:append?valueInputOption=RAW`, {
+        method: "POST",
+        body: JSON.stringify({ values: [Q(a)] })
+      }), a;
+    },
+    async resolveFeedback(i, l) {
+      const a = await b(n), d = a[0] ?? Y, y = d.indexOf("id"), u = d.indexOf("status"), f = d.indexOf("updatedAt"), p = d.indexOf("resolvedAt"), w = d.indexOf("resolvedBy"), m = a.findIndex((N, A) => A > 0 && N[y] === i);
+      if (m < 1)
+        throw new Error(`Feedback ${i} was not found`);
+      const g = [...a[m]], C = (/* @__PURE__ */ new Date()).toISOString();
+      g[u] = "resolved", g[f] = C, g[p] = C, g[w] = l, await v(
+        `/values/${encodeURIComponent(n)}!A${m + 1}:Q${m + 1}?valueInputOption=RAW`,
+        {
+          method: "PUT",
+          body: JSON.stringify({ values: [g] })
+        }
+      );
+      const $ = T(M(d, g));
+      if (!$)
+        throw new Error(`Feedback ${i} could not be parsed after resolving`);
+      return $;
+    }
+  };
+}
+const Y = [
+  "id",
+  "projectKey",
+  "contentId",
+  "normalizedPath",
+  "originalUrl",
+  "selector",
+  "selectorStrategy",
+  "elementFingerprintJson",
+  "cssSnapshotJson",
+  "comment",
+  "status",
+  "authorEmail",
+  "createdAt",
+  "updatedAt",
+  "resolvedAt",
+  "resolvedBy"
+];
+function Q(e) {
+  return [
+    e.id,
+    e.projectKey,
+    e.contentId,
+    e.normalizedPath,
+    e.originalUrl,
+    e.selector,
+    e.selectorStrategy,
+    JSON.stringify(e.elementFingerprint),
+    JSON.stringify(e.cssSnapshot),
+    e.comment,
+    e.status,
+    e.authorEmail,
+    e.createdAt,
+    e.updatedAt,
+    e.resolvedAt ?? "",
+    e.resolvedBy ?? ""
+  ];
+}
+function U(e) {
+  const [n, ...t] = e;
+  return n ? t.map((r) => M(n, r)) : [];
+}
+function M(e, n) {
+  return Object.fromEntries(e.map((t, r) => [t, n[r] ?? ""]));
+}
+function T(e) {
+  return e.id ? {
+    id: e.id,
+    projectKey: e.projectKey,
+    contentId: e.contentId,
+    normalizedPath: e.normalizedPath,
+    originalUrl: e.originalUrl,
+    selector: e.selector,
+    selectorStrategy: e.selectorStrategy === "stable-attribute" ? "stable-attribute" : "css-path",
+    elementFingerprint: O(e.elementFingerprintJson, {
+      tagName: "",
+      width: 0,
+      height: 0
+    }),
+    cssSnapshot: O(e.cssSnapshotJson, {
+      margin: "",
+      padding: "",
+      border: "",
+      fontFamily: "",
+      fontSize: "",
+      lineHeight: "",
+      color: "",
+      backgroundColor: "",
+      width: 0,
+      height: 0
+    }),
+    comment: e.comment,
+    status: e.status === "resolved" ? "resolved" : "open",
+    authorEmail: e.authorEmail,
+    createdAt: e.createdAt,
+    updatedAt: e.updatedAt,
+    resolvedAt: e.resolvedAt || void 0,
+    resolvedBy: e.resolvedBy || void 0
+  } : null;
+}
+function O(e, n) {
+  try {
+    return e ? JSON.parse(e) : n;
+  } catch {
+    return n;
+  }
+}
+function V(e) {
+  return e === "admin" ? ["create", "read", "resolve"] : e === "developer" ? ["read", "resolve"] : ["create", "read"];
+}
+async function Z(e) {
+  return await ee(), new Promise((n, t) => {
+    var o;
+    const r = (o = window.google) == null ? void 0 : o.accounts.oauth2.initTokenClient({
+      client_id: e,
+      scope: W,
+      callback: (s) => {
+        if (s.error || !s.access_token) {
+          t(new Error(s.error ?? "Google OAuth did not return an access token"));
+          return;
+        }
+        n(s.access_token);
+      }
+    });
+    r == null || r.requestAccessToken({ prompt: "" });
+  });
+}
+function ee() {
+  var e;
+  return (e = window.google) != null && e.accounts.oauth2 ? Promise.resolve() : new Promise((n, t) => {
+    const r = document.querySelector(
+      'script[src="https://accounts.google.com/gsi/client"]'
+    );
+    if (r) {
+      r.addEventListener("load", () => n(), { once: !0 }), r.addEventListener("error", () => t(new Error("Google Identity failed to load")), {
+        once: !0
+      });
+      return;
+    }
+    const o = document.createElement("script");
+    o.src = "https://accounts.google.com/gsi/client", o.async = !0, o.defer = !0, o.onload = () => n(), o.onerror = () => t(new Error("Google Identity failed to load")), document.head.append(o);
+  });
+}
+function te(e) {
+  return new URL(e, window.location.href).pathname.replace(/\/+$/, "") || "/";
+}
+const J = D(null);
+function me({ config: e, children: n }) {
+  const t = x(() => e.adapter ? e.adapter : X({
+    googleClientId: z(e.googleClientId, "googleClientId"),
+    spreadsheetId: z(e.spreadsheetId, "spreadsheetId"),
+    feedbackSheetName: e.sheetName ?? "Feedback"
+  }), [e.adapter, e.googleClientId, e.sheetName, e.spreadsheetId]), r = e.currentUrl ?? window.location.href, o = (e.normalizeUrl ?? te)(r), [s, v] = E(), [b, i] = E([]), [l, a] = E([]), d = L(async () => {
+    const p = await t.listFeedback({
+      projectKey: e.projectKey,
+      contentId: e.contentId,
+      normalizedPath: o
+    });
+    a(p);
+  }, [t, e.contentId, e.projectKey, o]);
+  R(() => {
+    let p = !0;
+    async function w() {
+      const [m, g] = await Promise.all([
+        t.getCurrentUser(),
+        t.getPermissions(e.projectKey)
+      ]);
+      p && (v(m), i(g), await d());
+    }
+    return w(), () => {
+      p = !1;
+    };
+  }, [t, e.projectKey, d]);
+  const y = L(
+    async (p) => {
+      const w = await t.createFeedback(p);
+      return a((m) => [w, ...m]), w;
+    },
+    [t]
+  ), u = L(
+    async (p) => {
+      const w = await t.resolveFeedback(p, (s == null ? void 0 : s.email) ?? "");
+      return a(
+        (m) => m.map((g) => g.id === p ? w : g)
+      ), w;
+    },
+    [t, s == null ? void 0 : s.email]
+  ), f = x(
+    () => ({
+      config: e,
+      adapter: t,
+      currentUser: s,
+      permissions: b,
+      feedback: l,
+      normalizedPath: o,
+      refreshFeedback: d,
+      createFeedback: y,
+      resolveFeedback: u
+    }),
+    [
+      t,
+      e,
+      y,
+      s,
+      l,
+      o,
+      b,
+      d,
+      u
+    ]
+  );
+  return /* @__PURE__ */ c(J.Provider, { value: f, children: n });
+}
+function ne() {
+  const e = H(J);
+  if (!e)
+    throw new Error("useReviewLens must be used inside ReviewLensProvider");
+  return e;
+}
+function z(e, n) {
+  if (!e)
+    throw new Error(`review-lens-react requires config.${n} when no adapter is provided`);
+  return e;
+}
+const re = [
+  "data-review-id",
+  "data-testid",
+  "data-test-id",
+  "aria-label",
+  "name"
+];
+function B(e) {
+  const n = e.getBoundingClientRect(), t = oe(e);
+  return {
+    selector: t.selector,
+    selectorStrategy: t.strategy,
+    fingerprint: ae(e, n),
+    cssSnapshot: ie(e, n),
+    rect: n
+  };
+}
+function oe(e) {
+  for (const n of re) {
+    const t = e.getAttribute(n);
+    if (t)
+      return {
+        selector: `[${n}="${K(t)}"]`,
+        strategy: "stable-attribute"
+      };
+  }
+  return e.id ? { selector: `#${K(e.id)}`, strategy: "stable-attribute" } : { selector: se(e), strategy: "css-path" };
+}
+function se(e) {
+  const n = [];
+  let t = e;
+  for (; t && t.nodeType === Node.ELEMENT_NODE && t !== document.body; ) {
+    const r = t.parentElement, o = t.tagName.toLowerCase();
+    if (!r) {
+      n.unshift(o);
+      break;
+    }
+    const s = t.tagName, v = Array.from(r.children).filter(
+      (i) => i.tagName === s
+    ), b = v.indexOf(t) + 1;
+    n.unshift(v.length > 1 ? `${o}:nth-of-type(${b})` : o), t = r;
+  }
+  return n.join(" > ");
+}
+function ae(e, n) {
+  var t;
+  return {
+    tagName: e.tagName.toLowerCase(),
+    id: e.id || void 0,
+    className: e.getAttribute("class") || void 0,
+    textSnippet: ((t = e.textContent) == null ? void 0 : t.trim().slice(0, 80)) || void 0,
+    ariaLabel: e.getAttribute("aria-label") || void 0,
+    width: Math.round(n.width),
+    height: Math.round(n.height)
+  };
+}
+function ie(e, n) {
+  const t = window.getComputedStyle(e);
+  return {
+    margin: j(t.marginTop, t.marginRight, t.marginBottom, t.marginLeft),
+    padding: j(
+      t.paddingTop,
+      t.paddingRight,
+      t.paddingBottom,
+      t.paddingLeft
+    ),
+    border: j(
+      t.borderTopWidth,
+      t.borderRightWidth,
+      t.borderBottomWidth,
+      t.borderLeftWidth
+    ),
+    fontFamily: t.fontFamily,
+    fontSize: t.fontSize,
+    lineHeight: t.lineHeight,
+    color: t.color,
+    backgroundColor: t.backgroundColor,
+    width: Math.round(n.width),
+    height: Math.round(n.height)
+  };
+}
+function j(e, n, t, r) {
+  return e === n && n === t && t === r ? e : `${e} ${n} ${t} ${r}`;
+}
+function K(e) {
+  return typeof CSS < "u" && typeof CSS.escape == "function" ? CSS.escape(e) : e.replace(/["\\]/g, "\\$&");
+}
+function fe({
+  open: e,
+  onOpenChange: n,
+  placement: t = "top-right",
+  showResolved: r = !1
+}) {
+  const {
+    config: o,
+    currentUser: s,
+    feedback: v,
+    normalizedPath: b,
+    permissions: i,
+    createFeedback: l,
+    resolveFeedback: a
+  } = ne(), [d, y] = E(), [u, f] = E(), [p, w] = E(""), [m, g] = E(), C = i.includes("create"), $ = i.includes("resolve"), N = x(
+    () => v.filter((h) => r || h.status !== "resolved"),
+    [v, r]
+  );
+  R(() => {
+    e || (y(void 0), f(void 0), w(""));
+  }, [e]);
+  const A = L((h) => {
+    const I = h.target instanceof Element ? h.target : null;
+    if (I)
+      return I.closest("[data-review-lens-ui]") ? null : I;
+    const S = document.elementFromPoint(h.clientX, h.clientY);
+    return !S || S.closest("[data-review-lens-ui]") ? null : S;
+  }, []);
+  if (R(() => {
+    if (!e || u)
+      return;
+    function h(S) {
+      const F = A(S);
+      F && y(B(F));
+    }
+    function I(S) {
+      const F = A(S);
+      F && (S.preventDefault(), S.stopPropagation(), f(B(F)));
+    }
+    return window.addEventListener("mousemove", h, !0), window.addEventListener("click", I, !0), () => {
+      window.removeEventListener("mousemove", h, !0), window.removeEventListener("click", I, !0);
+    };
+  }, [A, u, e]), !e)
+    return null;
+  const P = u ?? d;
+  async function G() {
+    !u || !p.trim() || !s || !C || (await l({
+      projectKey: o.projectKey,
+      contentId: o.contentId,
+      normalizedPath: b,
+      originalUrl: o.currentUrl ?? window.location.href,
+      selector: u.selector,
+      selectorStrategy: u.selectorStrategy,
+      elementFingerprint: u.fingerprint,
+      cssSnapshot: u.cssSnapshot,
+      comment: p.trim(),
+      authorEmail: s.email
+    }), w(""), f(void 0));
+  }
+  return /* @__PURE__ */ k("div", { className: "review-lens-root", "data-review-lens-ui": !0, children: [
+    P ? /* @__PURE__ */ c(ce, { target: P, locked: !!u }) : null,
+    /* @__PURE__ */ c(
+      le,
+      {
+        feedback: N,
+        selectedFeedback: m,
+        onSelect: g
+      }
+    ),
+    /* @__PURE__ */ k("aside", { className: `review-lens-panel review-lens-panel--${t}`, "data-review-lens-ui": !0, children: [
+      /* @__PURE__ */ k("header", { className: "review-lens-panel__header", children: [
+        /* @__PURE__ */ k("div", { children: [
+          /* @__PURE__ */ c("p", { className: "review-lens-kicker", children: "Review Lens" }),
+          /* @__PURE__ */ c("h2", { children: u ? "Element locked" : "Inspecting" })
+        ] }),
+        /* @__PURE__ */ c("button", { type: "button", onClick: () => n == null ? void 0 : n(!1), children: "Close" })
+      ] }),
+      P ? /* @__PURE__ */ c(de, { target: P }) : /* @__PURE__ */ c("p", { children: "Move over the app to inspect." }),
+      u ? /* @__PURE__ */ k(
+        "form",
+        {
+          className: "review-lens-feedback-form",
+          onSubmit: (h) => {
+            h.preventDefault(), G();
+          },
+          children: [
+            /* @__PURE__ */ c("label", { htmlFor: "review-lens-comment", children: "Feedback" }),
+            /* @__PURE__ */ c(
+              "textarea",
+              {
+                id: "review-lens-comment",
+                value: p,
+                disabled: !C,
+                onChange: (h) => w(h.target.value),
+                placeholder: C ? "Describe the UX issue..." : "You do not have permission to comment."
+              }
+            ),
+            /* @__PURE__ */ k("div", { className: "review-lens-actions", children: [
+              /* @__PURE__ */ c("button", { type: "button", onClick: () => f(void 0), children: "Unlock" }),
+              /* @__PURE__ */ c("button", { type: "submit", disabled: !p.trim() || !C, children: "Save feedback" })
+            ] })
+          ]
+        }
+      ) : null,
+      /* @__PURE__ */ k("section", { className: "review-lens-comments", children: [
+        /* @__PURE__ */ c("h3", { children: "Page feedback" }),
+        N.length === 0 ? /* @__PURE__ */ c("p", { children: "No feedback for this view." }) : null,
+        N.map((h) => /* @__PURE__ */ k(
+          "article",
+          {
+            className: (m == null ? void 0 : m.id) === h.id ? "review-lens-comment review-lens-comment--selected" : "review-lens-comment",
+            children: [
+              /* @__PURE__ */ c("p", { children: h.comment }),
+              /* @__PURE__ */ c("span", { children: h.authorEmail }),
+              h.status === "open" && $ ? /* @__PURE__ */ c("button", { type: "button", onClick: () => void a(h.id), children: "Resolve" }) : null
+            ]
+          },
+          h.id
+        ))
+      ] })
+    ] })
+  ] });
+}
+function ce({ target: e, locked: n }) {
+  return /* @__PURE__ */ c(
+    "div",
+    {
+      className: n ? "review-lens-highlight review-lens-highlight--locked" : "review-lens-highlight",
+      style: {
+        top: e.rect.top + window.scrollY,
+        left: e.rect.left + window.scrollX,
+        width: e.rect.width,
+        height: e.rect.height
+      }
+    }
+  );
+}
+function le({
+  feedback: e,
+  selectedFeedback: n,
+  onSelect: t
+}) {
+  return /* @__PURE__ */ c(q, { children: e.map((r) => {
+    const o = ue(r.selector), s = o == null ? void 0 : o.getBoundingClientRect();
+    return s ? /* @__PURE__ */ c(
+      "button",
+      {
+        type: "button",
+        className: (n == null ? void 0 : n.id) === r.id ? "review-lens-marker review-lens-marker--selected" : "review-lens-marker",
+        style: {
+          top: s.top + window.scrollY,
+          left: s.left + window.scrollX + s.width
+        },
+        onClick: () => t(r),
+        "aria-label": `Open feedback from ${r.authorEmail}`
+      },
+      r.id
+    ) : null;
+  }) });
+}
+function de({ target: e }) {
+  const n = [
+    ["Selector", e.selector],
+    ["Size", `${e.cssSnapshot.width} x ${e.cssSnapshot.height}`],
+    ["Margin", e.cssSnapshot.margin],
+    ["Padding", e.cssSnapshot.padding],
+    ["Border", e.cssSnapshot.border],
+    ["Font", `${e.cssSnapshot.fontSize} / ${e.cssSnapshot.lineHeight}`],
+    ["Family", e.cssSnapshot.fontFamily],
+    ["Color", e.cssSnapshot.color],
+    ["Background", e.cssSnapshot.backgroundColor]
+  ];
+  return /* @__PURE__ */ c("dl", { className: "review-lens-metrics", children: n.map(([t, r]) => /* @__PURE__ */ k("div", { children: [
+    /* @__PURE__ */ c("dt", { children: t }),
+    /* @__PURE__ */ c("dd", { children: r })
+  ] }, t)) });
+}
+function ue(e) {
+  try {
+    return document.querySelector(e);
+  } catch {
+    return null;
+  }
+}
+export {
+  fe as ReviewLensOverlay,
+  me as ReviewLensProvider,
+  B as buildElementTarget,
+  X as createGoogleSheetsAdapter,
+  te as normalizeReviewUrl,
+  ne as useReviewLens
+};

package/dist/review-lens-react.umd.cjs

@@ -0,0 +1 @@
+(function(w,r){typeof exports=="object"&&typeof module<"u"?r(exports,require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","react/jsx-runtime","react"],r):(w=typeof globalThis<"u"?globalThis:w||self,r(w.ReviewLensReact={},w.jsxRuntime,w.React))})(this,(function(w,r,p){"use strict";const J=["https://www.googleapis.com/auth/spreadsheets","https://www.googleapis.com/auth/userinfo.email"].join(" "),D="https://www.googleapis.com/oauth2/v3/userinfo";function T(e){const n=e.feedbackSheetName??"Feedback",t=e.usersSheetName??"Users";let o,s;async function a(){return o??(o=X(e.googleClientId)),o}async function y(c,l){const i=await a(),d=await fetch(`https://sheets.googleapis.com/v4/spreadsheets/${e.spreadsheetId}${c}`,{...l,headers:{Authorization:`Bearer ${i}`,"Content-Type":"application/json",...l==null?void 0:l.headers}});if(!d.ok)throw new Error(`Google Sheets request failed with ${d.status}`);return d.json()}async function S(c){return(await y(`/values/${encodeURIComponent(c)}`)).values??[]}return{async getCurrentUser(){if(!s){const c=await a(),l=await fetch(D,{headers:{Authorization:`Bearer ${c}`}});if(!l.ok)throw new Error(`Google userinfo request failed with ${l.status}`);s=(await l.json()).email}if(!s)throw new Error("Google account did not return an email address");return{email:s}},async getPermissions(c){const[{email:l},i]=await Promise.all([this.getCurrentUser(),S(t)]),d=U(i),k=l.toLowerCase(),u=d.find(g=>{var f;return((f=g.email)==null?void 0:f.toLowerCase())===k&&g.active!=="false"&&(!g.projectKey||g.projectKey===c)});return _((u==null?void 0:u.role)??"designer")},async listFeedback(c){return U(await S(n)).map(x).filter(i=>i!==null).filter(i=>i.projectKey===c.projectKey&&i.contentId===c.contentId&&i.normalizedPath===c.normalizedPath).sort((i,d)=>d.createdAt.localeCompare(i.createdAt))},async createFeedback(c){const l=new Date().toISOString(),i={...c,id:crypto.randomUUID(),status:"open",createdAt:l,updatedAt:l};return await y(`/values/${encodeURIComponent(n)}:append?valueInputOption=RAW`,{method:"POST",body:JSON.stringify({values:[W(i)]})}),i},async resolveFeedback(c,l){const i=await S(n),d=i[0]??H,k=d.indexOf("id"),u=d.indexOf("status"),g=d.indexOf("updatedAt"),f=d.indexOf("resolvedAt"),v=d.indexOf("resolvedBy"),m=i.findIndex((A,N)=>N>0&&A[k]===c);if(m<1)throw new Error(`Feedback ${c} was not found`);const b=[...i[m]],E=new Date().toISOString();b[u]="resolved",b[g]=E,b[f]=E,b[v]=l,await y(`/values/${encodeURIComponent(n)}!A${m+1}:Q${m+1}?valueInputOption=RAW`,{method:"PUT",body:JSON.stringify({values:[b]})});const P=x(O(d,b));if(!P)throw new Error(`Feedback ${c} could not be parsed after resolving`);return P}}}const H=["id","projectKey","contentId","normalizedPath","originalUrl","selector","selectorStrategy","elementFingerprintJson","cssSnapshotJson","comment","status","authorEmail","createdAt","updatedAt","resolvedAt","resolvedBy"];function W(e){return[e.id,e.projectKey,e.contentId,e.normalizedPath,e.originalUrl,e.selector,e.selectorStrategy,JSON.stringify(e.elementFingerprint),JSON.stringify(e.cssSnapshot),e.comment,e.status,e.authorEmail,e.createdAt,e.updatedAt,e.resolvedAt??"",e.resolvedBy??""]}function U(e){const[n,...t]=e;return n?t.map(o=>O(n,o)):[]}function O(e,n){return Object.fromEntries(e.map((t,o)=>[t,n[o]??""]))}function x(e){return e.id?{id:e.id,projectKey:e.projectKey,contentId:e.contentId,normalizedPath:e.normalizedPath,originalUrl:e.originalUrl,selector:e.selector,selectorStrategy:e.selectorStrategy==="stable-attribute"?"stable-attribute":"css-path",elementFingerprint:z(e.elementFingerprintJson,{tagName:"",width:0,height:0}),cssSnapshot:z(e.cssSnapshotJson,{margin:"",padding:"",border:"",fontFamily:"",fontSize:"",lineHeight:"",color:"",backgroundColor:"",width:0,height:0}),comment:e.comment,status:e.status==="resolved"?"resolved":"open",authorEmail:e.authorEmail,createdAt:e.createdAt,updatedAt:e.updatedAt,resolvedAt:e.resolvedAt||void 0,resolvedBy:e.resolvedBy||void 0}:null}function z(e,n){try{return e?JSON.parse(e):n}catch{return n}}function _(e){return e==="admin"?["create","read","resolve"]:e==="developer"?["read","resolve"]:["create","read"]}async function X(e){return await Y(),new Promise((n,t)=>{var s;const o=(s=window.google)==null?void 0:s.accounts.oauth2.initTokenClient({client_id:e,scope:J,callback:a=>{if(a.error||!a.access_token){t(new Error(a.error??"Google OAuth did not return an access token"));return}n(a.access_token)}});o==null||o.requestAccessToken({prompt:""})})}function Y(){var e;return(e=window.google)!=null&&e.accounts.oauth2?Promise.resolve():new Promise((n,t)=>{const o=document.querySelector('script[src="https://accounts.google.com/gsi/client"]');if(o){o.addEventListener("load",()=>n(),{once:!0}),o.addEventListener("error",()=>t(new Error("Google Identity failed to load")),{once:!0});return}const s=document.createElement("script");s.src="https://accounts.google.com/gsi/client",s.async=!0,s.defer=!0,s.onload=()=>n(),s.onerror=()=>t(new Error("Google Identity failed to load")),document.head.append(s)})}function B(e){return new URL(e,window.location.href).pathname.replace(/\/+$/,"")||"/"}const K=p.createContext(null);function Q({config:e,children:n}){const t=p.useMemo(()=>e.adapter?e.adapter:T({googleClientId:q(e.googleClientId,"googleClientId"),spreadsheetId:q(e.spreadsheetId,"spreadsheetId"),feedbackSheetName:e.sheetName??"Feedback"}),[e.adapter,e.googleClientId,e.sheetName,e.spreadsheetId]),o=e.currentUrl??window.location.href,s=(e.normalizeUrl??B)(o),[a,y]=p.useState(),[S,c]=p.useState([]),[l,i]=p.useState([]),d=p.useCallback(async()=>{const f=await t.listFeedback({projectKey:e.projectKey,contentId:e.contentId,normalizedPath:s});i(f)},[t,e.contentId,e.projectKey,s]);p.useEffect(()=>{let f=!0;async function v(){const[m,b]=await Promise.all([t.getCurrentUser(),t.getPermissions(e.projectKey)]);f&&(y(m),c(b),await d())}return v(),()=>{f=!1}},[t,e.projectKey,d]);const k=p.useCallback(async f=>{const v=await t.createFeedback(f);return i(m=>[v,...m]),v},[t]),u=p.useCallback(async f=>{const v=await t.resolveFeedback(f,(a==null?void 0:a.email)??"");return i(m=>m.map(b=>b.id===f?v:b)),v},[t,a==null?void 0:a.email]),g=p.useMemo(()=>({config:e,adapter:t,currentUser:a,permissions:S,feedback:l,normalizedPath:s,refreshFeedback:d,createFeedback:k,resolveFeedback:u}),[t,e,k,a,l,s,S,d,u]);return r.jsx(K.Provider,{value:g,children:n})}function M(){const e=p.useContext(K);if(!e)throw new Error("useReviewLens must be used inside ReviewLensProvider");return e}function q(e,n){if(!e)throw new Error(`review-lens-react requires config.${n} when no adapter is provided`);return e}const V=["data-review-id","data-testid","data-test-id","aria-label","name"];function L(e){const n=e.getBoundingClientRect(),t=Z(e);return{selector:t.selector,selectorStrategy:t.strategy,fingerprint:ee(e,n),cssSnapshot:te(e,n),rect:n}}function Z(e){for(const n of V){const t=e.getAttribute(n);if(t)return{selector:`[${n}="${G(t)}"]`,strategy:"stable-attribute"}}return e.id?{selector:`#${G(e.id)}`,strategy:"stable-attribute"}:{selector:R(e),strategy:"css-path"}}function R(e){const n=[];let t=e;for(;t&&t.nodeType===Node.ELEMENT_NODE&&t!==document.body;){const o=t.parentElement,s=t.tagName.toLowerCase();if(!o){n.unshift(s);break}const a=t.tagName,y=Array.from(o.children).filter(c=>c.tagName===a),S=y.indexOf(t)+1;n.unshift(y.length>1?`${s}:nth-of-type(${S})`:s),t=o}return n.join(" > ")}function ee(e,n){var t;return{tagName:e.tagName.toLowerCase(),id:e.id||void 0,className:e.getAttribute("class")||void 0,textSnippet:((t=e.textContent)==null?void 0:t.trim().slice(0,80))||void 0,ariaLabel:e.getAttribute("aria-label")||void 0,width:Math.round(n.width),height:Math.round(n.height)}}function te(e,n){const t=window.getComputedStyle(e);return{margin:j(t.marginTop,t.marginRight,t.marginBottom,t.marginLeft),padding:j(t.paddingTop,t.paddingRight,t.paddingBottom,t.paddingLeft),border:j(t.borderTopWidth,t.borderRightWidth,t.borderBottomWidth,t.borderLeftWidth),fontFamily:t.fontFamily,fontSize:t.fontSize,lineHeight:t.lineHeight,color:t.color,backgroundColor:t.backgroundColor,width:Math.round(n.width),height:Math.round(n.height)}}function j(e,n,t,o){return e===n&&n===t&&t===o?e:`${e} ${n} ${t} ${o}`}function G(e){return typeof CSS<"u"&&typeof CSS.escape=="function"?CSS.escape(e):e.replace(/["\\]/g,"\\$&")}function ne({open:e,onOpenChange:n,placement:t="top-right",showResolved:o=!1}){const{config:s,currentUser:a,feedback:y,normalizedPath:S,permissions:c,createFeedback:l,resolveFeedback:i}=M(),[d,k]=p.useState(),[u,g]=p.useState(),[f,v]=p.useState(""),[m,b]=p.useState(),E=c.includes("create"),P=c.includes("resolve"),A=p.useMemo(()=>y.filter(h=>o||h.status!=="resolved"),[y,o]);p.useEffect(()=>{e||(k(void 0),g(void 0),v(""))},[e]);const N=p.useCallback(h=>{const I=h.target instanceof Element?h.target:null;if(I)return I.closest("[data-review-lens-ui]")?null:I;const C=document.elementFromPoint(h.clientX,h.clientY);return!C||C.closest("[data-review-lens-ui]")?null:C},[]);if(p.useEffect(()=>{if(!e||u)return;function h(C){const F=N(C);F&&k(L(F))}function I(C){const F=N(C);F&&(C.preventDefault(),C.stopPropagation(),g(L(F)))}return window.addEventListener("mousemove",h,!0),window.addEventListener("click",I,!0),()=>{window.removeEventListener("mousemove",h,!0),window.removeEventListener("click",I,!0)}},[N,u,e]),!e)return null;const $=u??d;async function ie(){!u||!f.trim()||!a||!E||(await l({projectKey:s.projectKey,contentId:s.contentId,normalizedPath:S,originalUrl:s.currentUrl??window.location.href,selector:u.selector,selectorStrategy:u.selectorStrategy,elementFingerprint:u.fingerprint,cssSnapshot:u.cssSnapshot,comment:f.trim(),authorEmail:a.email}),v(""),g(void 0))}return r.jsxs("div",{className:"review-lens-root","data-review-lens-ui":!0,children:[$?r.jsx(re,{target:$,locked:!!u}):null,r.jsx(oe,{feedback:A,selectedFeedback:m,onSelect:b}),r.jsxs("aside",{className:`review-lens-panel review-lens-panel--${t}`,"data-review-lens-ui":!0,children:[r.jsxs("header",{className:"review-lens-panel__header",children:[r.jsxs("div",{children:[r.jsx("p",{className:"review-lens-kicker",children:"Review Lens"}),r.jsx("h2",{children:u?"Element locked":"Inspecting"})]}),r.jsx("button",{type:"button",onClick:()=>n==null?void 0:n(!1),children:"Close"})]}),$?r.jsx(se,{target:$}):r.jsx("p",{children:"Move over the app to inspect."}),u?r.jsxs("form",{className:"review-lens-feedback-form",onSubmit:h=>{h.preventDefault(),ie()},children:[r.jsx("label",{htmlFor:"review-lens-comment",children:"Feedback"}),r.jsx("textarea",{id:"review-lens-comment",value:f,disabled:!E,onChange:h=>v(h.target.value),placeholder:E?"Describe the UX issue...":"You do not have permission to comment."}),r.jsxs("div",{className:"review-lens-actions",children:[r.jsx("button",{type:"button",onClick:()=>g(void 0),children:"Unlock"}),r.jsx("button",{type:"submit",disabled:!f.trim()||!E,children:"Save feedback"})]})]}):null,r.jsxs("section",{className:"review-lens-comments",children:[r.jsx("h3",{children:"Page feedback"}),A.length===0?r.jsx("p",{children:"No feedback for this view."}):null,A.map(h=>r.jsxs("article",{className:(m==null?void 0:m.id)===h.id?"review-lens-comment review-lens-comment--selected":"review-lens-comment",children:[r.jsx("p",{children:h.comment}),r.jsx("span",{children:h.authorEmail}),h.status==="open"&&P?r.jsx("button",{type:"button",onClick:()=>void i(h.id),children:"Resolve"}):null]},h.id))]})]})]})}function re({target:e,locked:n}){return r.jsx("div",{className:n?"review-lens-highlight review-lens-highlight--locked":"review-lens-highlight",style:{top:e.rect.top+window.scrollY,left:e.rect.left+window.scrollX,width:e.rect.width,height:e.rect.height}})}function oe({feedback:e,selectedFeedback:n,onSelect:t}){return r.jsx(r.Fragment,{children:e.map(o=>{const s=ae(o.selector),a=s==null?void 0:s.getBoundingClientRect();return a?r.jsx("button",{type:"button",className:(n==null?void 0:n.id)===o.id?"review-lens-marker review-lens-marker--selected":"review-lens-marker",style:{top:a.top+window.scrollY,left:a.left+window.scrollX+a.width},onClick:()=>t(o),"aria-label":`Open feedback from ${o.authorEmail}`},o.id):null})})}function se({target:e}){const n=[["Selector",e.selector],["Size",`${e.cssSnapshot.width} x ${e.cssSnapshot.height}`],["Margin",e.cssSnapshot.margin],["Padding",e.cssSnapshot.padding],["Border",e.cssSnapshot.border],["Font",`${e.cssSnapshot.fontSize} / ${e.cssSnapshot.lineHeight}`],["Family",e.cssSnapshot.fontFamily],["Color",e.cssSnapshot.color],["Background",e.cssSnapshot.backgroundColor]];return r.jsx("dl",{className:"review-lens-metrics",children:n.map(([t,o])=>r.jsxs("div",{children:[r.jsx("dt",{children:t}),r.jsx("dd",{children:o})]},t))})}function ae(e){try{return document.querySelector(e)}catch{return null}}w.ReviewLensOverlay=ne,w.ReviewLensProvider=Q,w.buildElementTarget=L,w.createGoogleSheetsAdapter=T,w.normalizeReviewUrl=B,w.useReviewLens=M,Object.defineProperty(w,Symbol.toStringTag,{value:"Module"})}));

package/dist/selectors/build-element-target.d.ts

@@ -0,0 +1,2 @@
+import type { ReviewLensTarget } from "../types";
+export declare function buildElementTarget(element: Element): ReviewLensTarget;

package/dist/sheets/google-sheets-adapter.d.ts

@@ -0,0 +1,33 @@
+import type { ReviewLensAdapter } from "../types";
+type GoogleSheetsAdapterConfig = {
+    googleClientId: string;
+    spreadsheetId: string;
+    feedbackSheetName?: string;
+    usersSheetName?: string;
+    projectsSheetName?: string;
+};
+type TokenClient = {
+    requestAccessToken(options?: {
+        prompt?: string;
+    }): void;
+};
+declare global {
+    interface Window {
+        google?: {
+            accounts: {
+                oauth2: {
+                    initTokenClient(config: {
+                        client_id: string;
+                        scope: string;
+                        callback: (response: {
+                            access_token?: string;
+                            error?: string;
+                        }) => void;
+                    }): TokenClient;
+                };
+            };
+        };
+    }
+}
+export declare function createGoogleSheetsAdapter(config: GoogleSheetsAdapterConfig): ReviewLensAdapter;
+export {};

package/dist/styles.css

@@ -0,0 +1 @@
+.review-lens-root{color:#171717;font-family:ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;position:fixed;z-index:2147483647}.review-lens-highlight{border:2px solid #2563eb;box-shadow:0 0 0 9999px #0f172a14,0 0 0 4px #2563eb2e;pointer-events:none;position:absolute}.review-lens-highlight--locked{border-color:#f97316;box-shadow:0 0 0 9999px #0f172a1f,0 0 0 4px #f9731638}.review-lens-panel{background:#fafafa;border:1px solid #d4d4d4;border-radius:8px;box-shadow:0 24px 70px #0f172a38;box-sizing:border-box;max-height:calc(100vh - 32px);overflow:auto;padding:16px;position:fixed;width:min(380px,calc(100vw - 32px))}.review-lens-panel--top-left{left:16px;top:16px}.review-lens-panel--top-right{right:16px;top:16px}.review-lens-panel--bottom-left{bottom:16px;left:16px}.review-lens-panel--bottom-right{bottom:16px;right:16px}.review-lens-panel__header{align-items:flex-start;display:flex;gap:16px;justify-content:space-between}.review-lens-panel h2,.review-lens-panel h3,.review-lens-panel p{margin:0}.review-lens-panel h2{font-size:18px;line-height:1.25}.review-lens-panel h3{font-size:14px;margin-top:18px}.review-lens-kicker{color:#525252;font-size:11px;font-weight:700;letter-spacing:0;text-transform:uppercase}.review-lens-panel button{background:#171717;border:1px solid #171717;border-radius:6px;color:#fff;cursor:pointer;font:inherit;font-size:13px;min-height:32px;padding:6px 10px}.review-lens-panel button:disabled{cursor:not-allowed;opacity:.45}.review-lens-metrics{border:1px solid #e5e5e5;border-radius:8px;display:grid;gap:0;margin:16px 0 0;overflow:hidden}.review-lens-metrics div{display:grid;grid-template-columns:96px minmax(0,1fr)}.review-lens-metrics dt,.review-lens-metrics dd{border-bottom:1px solid #e5e5e5;font-size:12px;margin:0;min-width:0;padding:8px}.review-lens-metrics dt{background:#f5f5f5;color:#525252;font-weight:700}.review-lens-metrics dd{overflow-wrap:anywhere}.review-lens-feedback-form{display:grid;gap:8px;margin-top:16px}.review-lens-feedback-form label{font-size:13px;font-weight:700}.review-lens-feedback-form textarea{border:1px solid #d4d4d4;border-radius:8px;box-sizing:border-box;font:inherit;min-height:96px;padding:10px;resize:vertical;width:100%}.review-lens-actions{display:flex;gap:8px;justify-content:flex-end}.review-lens-comments{display:grid;gap:8px}.review-lens-comment{border:1px solid #e5e5e5;border-radius:8px;display:grid;gap:6px;padding:10px}.review-lens-comment--selected{border-color:#2563eb}.review-lens-comment span{color:#525252;font-size:12px}.review-lens-marker{background:#f97316;border:2px solid #ffffff;border-radius:999px;box-shadow:0 8px 20px #0f172a3d;cursor:pointer;height:18px;position:absolute;transform:translate(-50%,-50%);width:18px}.review-lens-marker--selected{background:#2563eb}

package/dist/types.d.ts

@@ -0,0 +1,78 @@
+import type { ReactNode } from "react";
+export type FeedbackStatus = "open" | "resolved";
+export type ReviewLensRole = "designer" | "developer" | "admin";
+export type ReviewLensPermission = "create" | "read" | "resolve";
+export type CssSnapshot = {
+    margin: string;
+    padding: string;
+    border: string;
+    fontFamily: string;
+    fontSize: string;
+    lineHeight: string;
+    color: string;
+    backgroundColor: string;
+    width: number;
+    height: number;
+};
+export type ElementFingerprint = {
+    tagName: string;
+    id?: string;
+    className?: string;
+    textSnippet?: string;
+    ariaLabel?: string;
+    width: number;
+    height: number;
+};
+export type ReviewLensTarget = {
+    selector: string;
+    selectorStrategy: "stable-attribute" | "css-path";
+    fingerprint: ElementFingerprint;
+    cssSnapshot: CssSnapshot;
+    rect: DOMRect;
+};
+export type ReviewLensFeedback = {
+    id: string;
+    projectKey: string;
+    contentId: string;
+    normalizedPath: string;
+    originalUrl: string;
+    selector: string;
+    selectorStrategy: ReviewLensTarget["selectorStrategy"];
+    elementFingerprint: ElementFingerprint;
+    cssSnapshot: CssSnapshot;
+    comment: string;
+    status: FeedbackStatus;
+    authorEmail: string;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt?: string;
+    resolvedBy?: string;
+};
+export type CreateFeedbackInput = Omit<ReviewLensFeedback, "id" | "status" | "createdAt" | "updatedAt" | "resolvedAt" | "resolvedBy">;
+export type ReviewLensAdapter = {
+    getCurrentUser(): Promise<{
+        email: string;
+    }>;
+    getPermissions(projectKey: string): Promise<ReviewLensPermission[]>;
+    listFeedback(params: {
+        projectKey: string;
+        contentId: string;
+        normalizedPath: string;
+    }): Promise<ReviewLensFeedback[]>;
+    createFeedback(input: CreateFeedbackInput): Promise<ReviewLensFeedback>;
+    resolveFeedback(id: string, resolvedBy: string): Promise<ReviewLensFeedback>;
+};
+export type ReviewLensConfig = {
+    googleClientId?: string;
+    spreadsheetId?: string;
+    sheetName?: string;
+    projectKey: string;
+    contentId: string;
+    currentUrl?: string;
+    normalizeUrl?: (url: string) => string;
+    adapter?: ReviewLensAdapter;
+};
+export type ReviewLensProviderProps = {
+    config: ReviewLensConfig;
+    children: ReactNode;
+};

package/dist/url/normalize-review-url.d.ts

@@ -0,0 +1 @@
+export declare function normalizeReviewUrl(url: string): string;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "review-lens-react",
+  "version": "0.1.0",
+  "description": "React overlay for UX review feedback backed by Google Sheets.",
+  "type": "module",
+  "main": "./dist/review-lens-react.umd.cjs",
+  "module": "./dist/review-lens-react.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/review-lens-react.js",
+      "require": "./dist/review-lens-react.umd.cjs"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^5.0.0",
+    "vite": "^6.3.5"
+  }
+}