@revova/hydrogen 1.0.0

package/README.md

@@ -0,0 +1,384 @@
+# @revova/hydrogen
+
+Official Revova review widgets for Shopify Hydrogen storefronts.
+
+## Installation
+
+```bash
+npm install @revova/hydrogen
+```
+
+## Requirements
+
+- React 18+
+- Shopify Hydrogen storefront with the Revova app installed
+
+---
+
+## Quick Start
+
+The `proxyUrl` is always `/apps/revova` — Shopify's App Proxy routes requests to your Revova backend automatically. No API keys needed in the storefront.
+
+---
+
+## Components
+
+### `<ReviewWidget>`
+
+Full review list with pagination, sorting, and an inline submission form.
+
+```tsx
+import { ReviewWidget } from '@revova/hydrogen';
+
+export default function ProductPage() {
+  const { product } = useLoaderData<typeof loader>();
+
+  return (
+    <ReviewWidget
+      proxyUrl="/apps/revova"
+      productId={product.id}
+    />
+  );
+}
+```
+
+**Props**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `proxyUrl` | `string` | — | App proxy base URL (`/apps/revova`) |
+| `productId` | `string` | — | Shopify product GID |
+| `locale` | `string` | — | Locale code for translated reviews (e.g. `fr`) |
+| `pageSize` | `number` | `10` | Reviews per page |
+| `showForm` | `boolean` | `true` | Show the write-review button and form |
+| `starColor` | `string` | `#f59e0b` | Star fill colour |
+| `className` | `string` | — | CSS class on the wrapper |
+
+---
+
+### `<ReviewForm>`
+
+Standalone submission form — use when you want the form separate from the list.
+
+```tsx
+import { ReviewForm } from '@revova/hydrogen';
+
+// `form` comes from the ReviewsResponse returned by useReviews
+<ReviewForm
+  proxyUrl="/apps/revova"
+  productId={product.id}
+  form={data.form}
+  onSuccess={() => console.log('submitted')}
+/>
+```
+
+**Props:** `proxyUrl`, `productId`, `form` (required — `ResolvedForm` from loader), `onSuccess?`, `className?`
+
+---
+
+### `<StarRating>`
+
+Renders star icons for any numeric rating. Supports half-stars via linear gradient fill.
+
+```tsx
+import { StarRating } from '@revova/hydrogen';
+
+<StarRating rating={4.5} size={20} color="#f59e0b" />
+```
+
+**Props:** `rating` (0–5), `max?` (default 5), `size?` (px, default 16), `color?`, `className?`
+
+---
+
+### `<ReviewCount>`
+
+Aggregate rating + review count badge. Fetches from `widget-globals`.
+
+```tsx
+import { ReviewCount } from '@revova/hydrogen';
+
+// On a product card or PDP header
+<ReviewCount proxyUrl="/apps/revova" starSize={14} />
+```
+
+**Props:** `proxyUrl`, `starColor?`, `starSize?`, `className?`
+
+---
+
+### `<ReviewCarousel>`
+
+Auto-advancing carousel of recent reviews. Includes previous/next arrows and dot indicators.
+
+```tsx
+import { ReviewCarousel } from '@revova/hydrogen';
+
+<ReviewCarousel
+  proxyUrl="/apps/revova"
+  limit={10}
+  autoPlay
+  intervalMs={4000}
+/>
+```
+
+**Props:** `proxyUrl`, `limit?` (default 10), `autoPlay?` (default `true`), `intervalMs?` (default 4000), `starColor?`, `className?`
+
+---
+
+### `<ReviewGallery>`
+
+Masonry photo grid of reviews that have images. Clicking any photo opens a lightbox with the full review.
+
+```tsx
+import { ReviewGallery } from '@revova/hydrogen';
+
+<ReviewGallery
+  proxyUrl="/apps/revova"
+  columns={3}
+  limit={20}
+/>
+```
+
+**Props:** `proxyUrl`, `limit?` (default 20), `columns?` (default 3), `starColor?`, `className?`
+
+---
+
+### `<QnAWidget>`
+
+Product Q&A — lists questions with answers and includes an ask-a-question form.
+
+```tsx
+import { QnAWidget } from '@revova/hydrogen';
+
+<QnAWidget
+  proxyUrl="/apps/revova"
+  productId={product.id}
+/>
+```
+
+**Props:** `proxyUrl`, `productId`, `className?`
+
+---
+
+### `<TrustBadge>`
+
+Aggregate rating badge in three styles: `pill` (default), `inline`, or `card`.
+
+```tsx
+import { TrustBadge } from '@revova/hydrogen';
+
+// Pill — great for footers, headers
+<TrustBadge proxyUrl="/apps/revova" style="pill" />
+
+// Card — great for landing pages
+<TrustBadge proxyUrl="/apps/revova" style="card" />
+
+// Inline — great inside sentences or product specs
+<TrustBadge proxyUrl="/apps/revova" style="inline" />
+```
+
+**Props:** `proxyUrl`, `style?` (`'pill' | 'inline' | 'card'`, default `'pill'`), `starColor?`, `className?`
+
+---
+
+### `<ReviewTicker>`
+
+A continuously scrolling marquee of recent review snippets — ideal for homepages and hero sections.
+
+```tsx
+import { ReviewTicker } from '@revova/hydrogen';
+
+<ReviewTicker
+  proxyUrl="/apps/revova"
+  limit={20}
+  speedSeconds={30}
+/>
+```
+
+**Props:** `proxyUrl`, `limit?` (default 20), `speedSeconds?` (default 30), `starColor?`, `className?`
+
+---
+
+### `<SocialProofPopup>`
+
+A timed floating popup showing recent reviews one at a time. Appears after a short delay and cycles automatically.
+
+```tsx
+import { SocialProofPopup } from '@revova/hydrogen';
+
+// Add once to your root layout
+<SocialProofPopup
+  proxyUrl="/apps/revova"
+  position="bottom-left"
+  intervalMs={8000}
+  displayMs={5000}
+/>
+```
+
+**Props:** `proxyUrl`, `position?` (`'bottom-left' | 'bottom-right'`, default `'bottom-left'`), `intervalMs?` (default 8000), `displayMs?` (default 5000), `starColor?`, `className?`
+
+---
+
+### `<FloatingReviewsTab>`
+
+A sticky tab fixed to the left or right edge of the viewport. Clicking it slides out a panel of recent reviews.
+
+```tsx
+import { FloatingReviewsTab } from '@revova/hydrogen';
+
+<FloatingReviewsTab
+  proxyUrl="/apps/revova"
+  label="Reviews"
+  position="right"
+  color="#111827"
+/>
+```
+
+**Props:** `proxyUrl`, `label?` (default `'Reviews'`), `position?` (`'left' | 'right'`, default `'right'`), `color?`, `limit?` (default 5), `starColor?`, `className?`
+
+---
+
+### `<FloatingReviewButton>`
+
+A fixed "Write a Review" button that opens a modal with the submission form.
+
+```tsx
+import { FloatingReviewButton } from '@revova/hydrogen';
+
+<FloatingReviewButton
+  proxyUrl="/apps/revova"
+  productId={product.id}
+  text="Write a Review"
+  position="bottom-right"
+  color="#111827"
+/>
+```
+
+**Props:** `proxyUrl`, `productId`, `text?` (default `'Write a Review'`), `color?`, `position?` (`'bottom-left' | 'bottom-right'`, default `'bottom-right'`), `className?`
+
+---
+
+## Hooks
+
+Use hooks to build fully custom UIs while Revova handles data fetching.
+
+### `useReviews(options)`
+
+Paginated reviews for a product with sorting controls.
+
+```tsx
+import { useReviews } from '@revova/hydrogen';
+
+const { data, loading, error, setPage, setSort, currentPage, currentSort, refetch } = useReviews({
+  proxyUrl: '/apps/revova',
+  productId: product.id,
+  limit: 5,
+  sort: 'helpful',   // 'recent' | 'helpful' | 'rating_high' | 'rating_low'
+  locale: 'fr',      // optional — returns translated content
+});
+```
+
+### `useWidgetGlobals(options)`
+
+Shop-level stats and recent reviews. Used internally by `<ReviewCount>`, `<TrustBadge>`, `<ReviewCarousel>`, `<ReviewGallery>`, `<ReviewTicker>`, `<SocialProofPopup>`, and `<FloatingReviewsTab>`.
+
+```tsx
+import { useWidgetGlobals } from '@revova/hydrogen';
+
+const { data, loading, error } = useWidgetGlobals({
+  proxyUrl: '/apps/revova',
+  limit: 20,
+});
+
+// data.stats.averageRating  — "4.8"
+// data.stats.totalReviews   — 142
+// data.reviews              — recent GlobalReview[]
+// data.config               — merchant widget settings
+```
+
+### `useSubmitReview(proxyUrl)`
+
+Submit a new review programmatically.
+
+```tsx
+import { useSubmitReview } from '@revova/hydrogen';
+
+const { submit, submitting, success, error, result, reset } = useSubmitReview('/apps/revova');
+
+await submit({
+  productId: 'gid://shopify/Product/123',
+  email: 'buyer@example.com',
+  formId: 'form-id-from-loader',
+  fieldAnswers: [
+    { fieldId: 'star-field-id', value: 5 },
+    { fieldId: 'title-field-id', value: 'Great product!' },
+    { fieldId: 'body-field-id', value: 'Really happy with this purchase.' },
+  ],
+});
+```
+
+### `useQnA(options)`
+
+Fetch and submit Q&A for a product.
+
+```tsx
+import { useQnA } from '@revova/hydrogen';
+
+const {
+  data,
+  loading,
+  setPage,
+  submitQuestion,
+  submitAnswer,
+  submitState,
+  resetSubmit,
+} = useQnA({ proxyUrl: '/apps/revova', productId: product.id });
+
+// Submit a question
+await submitQuestion({
+  intent: 'question',
+  productId: product.id,
+  email: 'user@example.com',
+  body: 'Does this come in blue?',
+});
+```
+
+### `useHelpfulVote(proxyUrl)`
+
+Cast a helpful / not-helpful vote on a review.
+
+```tsx
+import { useHelpfulVote } from '@revova/hydrogen';
+
+const { vote, loading, voted } = useHelpfulVote('/apps/revova');
+
+<button onClick={() => vote({ reviewId: review.id, vote: 'helpful' })} disabled={voted}>
+  Helpful ({review.helpfulCount})
+</button>
+```
+
+---
+
+## Styling
+
+All components are **unstyled by default** — they render semantic HTML with inline structural styles only (layout, positioning). Pass a `className` prop and override with Tailwind, CSS Modules, or any CSS-in-JS solution.
+
+The `starColor` prop is available on every component that displays stars and defaults to `#f59e0b` (amber).
+
+---
+
+## Placement Guide
+
+| Widget | Where to use |
+|---|---|
+| `<ReviewWidget>` | Product detail page |
+| `<ReviewForm>` | Custom PDP, post-purchase page |
+| `<StarRating>` | Anywhere — product cards, PDPs, search results |
+| `<ReviewCount>` | Product cards, PDP header |
+| `<ReviewCarousel>` | Homepage, collection pages |
+| `<ReviewGallery>` | Homepage, dedicated reviews page |
+| `<QnAWidget>` | Product detail page (below reviews) |
+| `<TrustBadge>` | Homepage hero, footer, landing pages |
+| `<ReviewTicker>` | Homepage hero, announcement bar |
+| `<SocialProofPopup>` | Root layout (renders once site-wide) |
+| `<FloatingReviewsTab>` | Root layout (renders once site-wide) |
+| `<FloatingReviewButton>` | Product detail page |