@bitux/review-layer-react 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @bitux/review-layer-react
+
+SDK de React para dejar comentarios de revisión (QA, UX, PM) directamente sobre la UI en entornos de staging. Se conecta a la API [review-layer-api](https://github.com/bitux/review-layer-api).
+
+## Instalación
+
+```bash
+npm install @bitux/review-layer-react
+```
+
+Requiere React 18+ y la API backend desplegada.
+
+## Uso
+
+Envuelve tu aplicación con `ReviewProvider` y configura la URL de la API y el API key del proyecto:
+
+```tsx
+import { ReviewProvider } from "@bitux/review-layer-react";
+
+<ReviewProvider
+  enabled={true}
+  apiUrl="http://localhost:8000/api"
+  apiKey="dev_test_key_123"
+>
+  <App />
+</ReviewProvider>
+```
+
+- **enabled**: activa o desactiva el SDK (p. ej. `import.meta.env.DEV` o `import.meta.env.VITE_REVIEW_ENABLED`).
+- **apiUrl**: base URL de la API (sin barra final), p. ej. `https://review-api.example.com/api`.
+- **apiKey**: API key del proyecto (generado en el backend por equipo/proyecto).
+
+## Atajos
+
+- **Shift + R**: activar/desactivar modo revisión.
+
+En modo revisión:
+
+- El cursor pasa a cruz.
+- Al pasar el ratón sobre un elemento se resalta con un borde.
+- Al hacer clic en un elemento se abre el modal para escribir un comentario y asignar revisor.
+- Los comentarios existentes se muestran como pins en la página; al hacer clic en un pin se ve el texto.
+
+## Variables de entorno (ejemplo)
+
+En tu app de staging (Vite):
+
+```env
+VITE_REVIEW_API_URL=http://localhost:8000/api
+VITE_REVIEW_API_KEY=rl_xxx
+```
+
+```tsx
+<ReviewProvider
+  enabled={import.meta.env.DEV}
+  apiUrl={import.meta.env.VITE_REVIEW_API_URL ?? ""}
+  apiKey={import.meta.env.VITE_REVIEW_API_KEY ?? ""}
+>
+  <App />
+</ReviewProvider>
+```
+
+## Navegación SPA (React Router, etc.)
+
+Si usas rutas del lado cliente, al cambiar de ruta conviene volver a cargar los comentarios de la página actual. Usa el hook `useReview` y llama a `loadComments()` cuando cambie la ruta:
+
+```tsx
+import { useReview } from "@bitux/review-layer-react";
+import { useLocation } from "react-router-dom";
+
+function AppWithReview() {
+  const { loadComments } = useReview();
+  const location = useLocation();
+
+  useEffect(() => {
+    loadComments();
+  }, [location.pathname, loadComments]);
+
+  return <Outlet />;
+}
+```
+
+## Probar antes de publicar
+
+### Tests unitarios
+
+```bash
+npm run test
+```
+
+Se ejecutan pruebas de `selector` y de la capa `api` (con `fetch` mockeado).
+
+### Demo local contra la API
+
+1. Arranca la API (en el repo `review-layer-api`):
+
+   ```bash
+   php artisan serve
+   ```
+
+2. En este repo, levanta la demo (usa el código fuente del SDK, sin publicar):
+
+   ```bash
+   npm run demo
+   ```
+
+   Se abre http://localhost:5174 con una miniapp envuelta en `ReviewProvider`. Por defecto usa `apiUrl=http://127.0.0.1:8000/api` y `apiKey=dev_test_key_123`. Puedes sobreescribirlos con un `.env` en la raíz o en `demo/`:
+
+   ```env
+   VITE_REVIEW_API_URL=http://127.0.0.1:8000/api
+   VITE_REVIEW_API_KEY=dev_test_key_123
+   ```
+
+3. En la demo: **Shift + R** para activar modo revisión, haz clic en un elemento y envía un comentario. Comprueba que los pins aparecen y que en la API se crean los comentarios.
+
+## Publicar en npm
+
+1. **Cuenta npm**: crea una en [npmjs.com](https://www.npmjs.com/) si no tienes. Para un paquete con scope (`@bitux/review-layer-react`) la primera vez debes publicar como público (en `package.json` ya está `"publishConfig": { "access": "public" }`).
+
+2. **Repository**: la URL del repo en `package.json` apunta a `github.com/bitux/review-layer-react`. Ajusta si el nombre del repo es otro.
+
+3. **Build y publicar**:
+
+```bash
+npm run build
+npm login
+npm publish
+```
+
+Las versiones siguientes: cambia `version` en `package.json` (o usa `npm version patch`) y vuelve a `npm run build` y `npm publish`.

package/dist/CommentModal.d.ts

@@ -0,0 +1,16 @@
+import { Reviewer, CreateCommentPayload } from './utils/api';
+
+interface CommentModalProps {
+    apiUrl: string;
+    apiKey: string;
+    reviewers: Reviewer[];
+    position: {
+        x: number;
+        y: number;
+    };
+    payload: Omit<CreateCommentPayload, "message" | "reviewerId">;
+    onClose: () => void;
+    onSuccess: () => void;
+}
+export declare function CommentModal({ apiUrl, apiKey, reviewers, position, payload, onClose, onSuccess, }: CommentModalProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/CommentPin.d.ts

@@ -0,0 +1,14 @@
+import { Comment } from './utils/api';
+
+export interface CommentPinProps {
+    comment: Comment;
+    /** Desplazamiento para no solaparse con otros pins en el mismo punto */
+    offset?: {
+        dx: number;
+        dy: number;
+    };
+    apiUrl: string;
+    apiKey: string;
+    onStatusChange: () => void;
+}
+export declare function CommentPin({ comment, offset, apiUrl, apiKey, onStatusChange, }: CommentPinProps): import("react/jsx-runtime").JSX.Element;

package/dist/ElementHighlight.d.ts

@@ -0,0 +1,11 @@
+export interface ElementHighlightProps {
+    /** CSS selector for the element to highlight */
+    selector: string | null;
+    /** When false, render nothing */
+    active: boolean;
+}
+/**
+ * Finds the element by selector, tracks its bounding rect, and renders
+ * a persistent highlight overlay. Updates on scroll and resize.
+ */
+export declare function ElementHighlight({ selector, active }: ElementHighlightProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/Overlay.d.ts

@@ -0,0 +1,13 @@
+import { Reviewer, Comment } from './utils/api';
+
+interface OverlayProps {
+    apiUrl: string;
+    apiKey: string;
+    reviewMode: boolean;
+    reviewers: Reviewer[];
+    comments: Comment[];
+    loadComments: () => void;
+    commentsLoadFailed?: boolean;
+}
+export declare function Overlay({ apiUrl, apiKey, reviewMode, reviewers, comments, loadComments, commentsLoadFailed, }: OverlayProps): import('react').ReactPortal | null;
+export {};

package/dist/ReviewProvider.d.ts

@@ -0,0 +1,22 @@
+import { Reviewer, Comment } from './utils/api';
+
+interface ReviewContextValue {
+    apiUrl: string;
+    apiKey: string;
+    reviewMode: boolean;
+    setReviewMode: (value: boolean) => void;
+    reviewers: Reviewer[];
+    comments: Comment[];
+    loadComments: () => void;
+    /** true si la última carga de comentarios falló (ej. backend dormido en Render) */
+    commentsLoadFailed: boolean;
+}
+export declare function useReview(): ReviewContextValue;
+export interface ReviewProviderProps {
+    children: React.ReactNode;
+    enabled?: boolean;
+    apiUrl: string;
+    apiKey: string;
+}
+export declare function ReviewProvider({ children, enabled, apiUrl, apiKey, }: ReviewProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/hooks/useReviewMode.d.ts

@@ -0,0 +1,3 @@
+import { Dispatch, SetStateAction } from 'react';
+
+export declare function useReviewMode(enabled: boolean, _reviewMode: boolean, setReviewMode: Dispatch<SetStateAction<boolean>>): void;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ReviewProvider, useReview } from './ReviewProvider';
+export type { ReviewProviderProps } from './ReviewProvider';
+export type { Reviewer, Comment } from './utils/api';