@mohasinac/appkit 4.11.2 → 4.11.3

package/dist/features/reviews/components/ReviewsListingPanel.js

@@ -0,0 +1,226 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useState } from "react";
+import { useUrlTable } from "../../../react/hooks/useUrlTable";
+import { Div, ListingFilterDrawer, ListingToolbar, Pagination, Row, Span, Stack, StickyToolbar, Text, } from "../../../ui";
+import { ReviewCard } from "./ReviewsList";
+import { ReviewFilters, REVIEW_PUBLIC_SORT_OPTIONS } from "./ReviewFilters";
+import { useReviews } from "../hooks/useReviews";
+import { useStoreReviews } from "../../stores/hooks/useStores";
+import { TABLE_KEYS, VIEW_MODE } from "../../../constants/table-keys";
+import { sortBy } from "../../../constants/sort";
+import { REVIEW_FIELDS } from "../../../constants/field-names";
+import { REVIEWS_DETAIL_PAGE_SIZE, REVIEWS_PAGE_SIZE, } from "../../../_internal/shared/features/reviews/config";
+const __P = {
+    p4: "p-[var(--appkit-space-4)]",
+};
+const __O = {
+    hidden: "overflow-hidden",
+};
+const DEFAULT_SORT = sortBy(REVIEW_FIELDS.CREATED_AT);
+const SORT_OPTION_LABELS = {
+    sortNewest: "Newest First",
+    sortOldest: "Oldest First",
+    sortHighestRated: "Highest Rated",
+    sortLowestRated: "Lowest Rated",
+};
+/**
+ * Filter keys per source — these are the filters the panel actually applies, and
+ * `ReviewFilters` is handed the same list so the drawer can never render a control
+ * that silently does nothing.
+ *
+ * `product` drops the helpful-vote range: that is a Firestore inequality, and an
+ * inequality filter forces the first `orderBy` onto the same field, which would break
+ * every sort this panel offers. `hasImages` is only offered on `store`, whose route
+ * filters in memory — the `productId`-scoped query has no index for it.
+ */
+const FILTER_KEYS_BY_KIND = {
+    product: [TABLE_KEYS.RATING, TABLE_KEYS.DATE_FROM, TABLE_KEYS.DATE_TO],
+    store: [TABLE_KEYS.RATING, TABLE_KEYS.DATE_FROM, TABLE_KEYS.DATE_TO, "hasImages"],
+    all: [TABLE_KEYS.RATING, TABLE_KEYS.DATE_FROM, TABLE_KEYS.DATE_TO, "hasImages"],
+};
+/** Sorts that keep `createdAt` as the first ordering field. */
+const CREATED_AT_SORTS = [
+    sortBy(REVIEW_FIELDS.CREATED_AT),
+    sortBy(REVIEW_FIELDS.CREATED_AT, "ASC"),
+];
+export function ReviewsListingPanel({ source, pageSize, context = "general", stateMode = "url", initialData, showSummary = true, showSearch, variant = "public", emptyLabel = "No reviews found.", className = "", }) {
+    const filterKeys = FILTER_KEYS_BY_KIND[source.kind];
+    const effectivePageSize = pageSize ?? (stateMode === "local" ? REVIEWS_DETAIL_PAGE_SIZE : REVIEWS_PAGE_SIZE);
+    const searchEnabled = showSearch ?? source.kind !== "product";
+    // --- state backing: URL or local ------------------------------------------
+    const urlTable = useUrlTable({
+        defaults: { pageSize: String(effectivePageSize), sort: DEFAULT_SORT },
+    });
+    const [localState, setLocalState] = useState({});
+    const localTable = useMemo(() => {
+        const get = (key) => localState[key] ?? "";
+        const setMany = (updates) => setLocalState((prev) => ({ ...prev, ...updates }));
+        return {
+            get,
+            getNumber: (key, fallback = 0) => {
+                const raw = localState[key];
+                if (!raw)
+                    return fallback;
+                const n = Number(raw);
+                return Number.isNaN(n) ? fallback : n;
+            },
+            // Mirrors useUrlTable's NON_RESETTING_KEYS behaviour so paging semantics match
+            // between the two state modes.
+            set: (key, value) => setLocalState((prev) => ({
+                ...prev,
+                [key]: value,
+                ...(key === TABLE_KEYS.PAGE ||
+                    key === TABLE_KEYS.PAGE_SIZE ||
+                    key === TABLE_KEYS.VIEW
+                    ? {}
+                    : { [TABLE_KEYS.PAGE]: "1" }),
+            })),
+            setMany,
+            clear: (keys) => {
+                const ks = keys ?? filterKeys;
+                setMany(Object.fromEntries(ks.map((k) => [k, ""])));
+            },
+            setPage: (page) => setLocalState((prev) => ({ ...prev, [TABLE_KEYS.PAGE]: String(page) })),
+            setPageSize: (_) => { },
+            setSort: (value) => setLocalState((prev) => ({ ...prev, [TABLE_KEYS.SORT]: value, [TABLE_KEYS.PAGE]: "1" })),
+            buildSieveParams: () => "",
+            buildSearchParams: () => "",
+            params: new URLSearchParams(),
+        };
+    }, [localState, filterKeys]);
+    const table = stateMode === "url" ? urlTable : localTable;
+    const [searchInput, setSearchInput] = useState(() => table.get(TABLE_KEYS.QUERY) || "");
+    const [filterOpen, setFilterOpen] = useState(false);
+    const [view, setView] = useState(table.get(TABLE_KEYS.VIEW) || VIEW_MODE.GRID);
+    const sort = table.get(TABLE_KEYS.SORT) || DEFAULT_SORT;
+    const currentPage = table.getNumber(TABLE_KEYS.PAGE, 1);
+    const query = table.get(TABLE_KEYS.QUERY) || undefined;
+    const ratingRaw = table.get(TABLE_KEYS.RATING);
+    const dateFrom = table.get(TABLE_KEYS.DATE_FROM) || undefined;
+    const dateTo = table.get(TABLE_KEYS.DATE_TO) || undefined;
+    const hasImages = table.get("hasImages") === "true" ? true : undefined;
+    const isStore = source.kind === "store";
+    /**
+     * A date range is a Firestore inequality on `createdAt`, and Firestore requires the
+     * first `orderBy` to be that same field — so "Highest/Lowest rated" cannot be served
+     * while a date range is active. Withdraw those options and fall back to newest-first
+     * instead of letting the query throw FAILED_PRECONDITION. Store-sourced reviews are
+     * sorted in memory by their route, so they are exempt.
+     */
+    const dateRangeActive = !isStore && (!!dateFrom || !!dateTo);
+    const effectiveSort = dateRangeActive && !CREATED_AT_SORTS.includes(sort) ? DEFAULT_SORT : sort;
+    const activeFilterCount = filterKeys.filter((k) => !!table.get(k)).length;
+    const hasActiveState = !!query || sort !== DEFAULT_SORT || activeFilterCount > 0;
+    /**
+     * `useReviews` pins `staleTime: Infinity` whenever `initialData` is present, and its
+     * query key includes the full query string — so handing SSR page-1 rows to a filtered
+     * or later page would freeze the wrong rows into that key forever (Root Cause #30).
+     * Only seed the exact query the SSR builder actually ran.
+     */
+    const isDefaultQuery = currentPage === 1 && sort === DEFAULT_SORT && activeFilterCount === 0 && !query;
+    const seed = isDefaultQuery ? initialData : undefined;
+    const handleViewToggle = (next) => {
+        if (next === VIEW_MODE.TABLE)
+            return;
+        setView(next);
+        table.set(TABLE_KEYS.VIEW, next);
+    };
+    // --- pending (buffered) filter state for the drawer -----------------------
+    const [pendingFilters, setPendingFilters] = useState(() => Object.fromEntries(filterKeys.map((k) => [k, table.get(k)])));
+    const pendingTable = useMemo(() => ({
+        get: (key) => pendingFilters[key] ?? "",
+        getNumber: (key, fallback = 0) => {
+            const raw = pendingFilters[key];
+            if (!raw)
+                return fallback;
+            const n = Number(raw);
+            return Number.isNaN(n) ? fallback : n;
+        },
+        set: (key, value) => setPendingFilters((p) => ({ ...p, [key]: value })),
+        setMany: (updates) => setPendingFilters((p) => ({ ...p, ...updates })),
+        clear: (keys) => {
+            const ks = keys ?? filterKeys;
+            setPendingFilters((p) => ({
+                ...p,
+                ...Object.fromEntries(ks.map((k) => [k, ""])),
+            }));
+        },
+        setPage: (_) => { },
+        setPageSize: (_) => { },
+        setSort: (_) => { },
+        buildSieveParams: () => "",
+        buildSearchParams: () => "",
+        params: new URLSearchParams(),
+    }), [pendingFilters, filterKeys]);
+    const openFilters = useCallback(() => {
+        setPendingFilters(Object.fromEntries(filterKeys.map((k) => [k, table.get(k)])));
+        setFilterOpen(true);
+    }, [table, filterKeys]);
+    const applyFilters = useCallback(() => {
+        const updates = { [TABLE_KEYS.PAGE]: "1" };
+        for (const k of filterKeys)
+            updates[k] = pendingFilters[k] ?? "";
+        table.setMany(updates);
+        setFilterOpen(false);
+    }, [pendingFilters, table, filterKeys]);
+    const clearFilters = useCallback(() => {
+        setPendingFilters(Object.fromEntries(filterKeys.map((k) => [k, ""])));
+    }, [filterKeys]);
+    const resetAll = useCallback(() => {
+        const updates = {
+            [TABLE_KEYS.QUERY]: "",
+            [TABLE_KEYS.SORT]: "",
+            [TABLE_KEYS.PAGE]: "1",
+        };
+        for (const k of filterKeys)
+            updates[k] = "";
+        table.setMany(updates);
+        setSearchInput("");
+    }, [table, filterKeys]);
+    const commitSearch = useCallback(() => {
+        table.set(TABLE_KEYS.QUERY, searchInput.trim());
+    }, [searchInput, table]);
+    // --- data -----------------------------------------------------------------
+    // Both hooks are always called (hooks can't be conditional); the inactive one is
+    // disabled, so react-query never fires its request.
+    const reviewsQuery = useReviews({
+        productId: source.kind === "product" ? source.productId : undefined,
+        status: source.kind === "product" ? "approved" : undefined,
+        q: query,
+        rating: ratingRaw || undefined,
+        dateFrom,
+        dateTo,
+        minVotes: table.get("minVotes") ? Number(table.get("minVotes")) : undefined,
+        maxVotes: table.get("maxVotes") ? Number(table.get("maxVotes")) : undefined,
+        hasImages,
+        sort: effectiveSort,
+        page: currentPage,
+        pageSize: effectivePageSize,
+    }, { initialData: seed, enabled: !isStore });
+    const storeQuery = useStoreReviews(isStore ? source.storeSlug : "", {
+        rating: ratingRaw ? Number(ratingRaw.split("|")[0]) : undefined,
+        page: currentPage,
+        pageSize: effectivePageSize,
+        sort,
+        q: query,
+        dateFrom,
+        dateTo,
+        hasImages,
+    }, { enabled: isStore });
+    const reviews = (isStore ? storeQuery.reviews : reviewsQuery.reviews);
+    const totalPages = isStore ? storeQuery.totalPages : reviewsQuery.totalPages;
+    const isLoading = isStore ? storeQuery.isLoading : reviewsQuery.isLoading;
+    const averageRating = isStore ? storeQuery.averageRating : reviewsQuery.averageRating;
+    const totalReviews = isStore
+        ? storeQuery.totalReviews
+        : (reviewsQuery.totalApproved ?? reviewsQuery.total);
+    const sortOptions = REVIEW_PUBLIC_SORT_OPTIONS.filter((opt) => !dateRangeActive || CREATED_AT_SORTS.includes(opt.value)).map((opt) => ({
+        value: opt.value,
+        label: SORT_OPTION_LABELS[opt.key] ?? opt.key,
+    }));
+    const paginationBlock = totalPages > 1 ? (_jsx(Row, { justify: "center", children: _jsx(Pagination, { currentPage: currentPage, totalPages: totalPages, onPageChange: (p) => table.setPage(p) }) })) : null;
+    return (_jsxs(Div, { className: className, children: [showSummary && (totalReviews ?? 0) > 0 && (_jsxs(Row, { border: "default", align: "center", gap: "sm", className: "border-b", padding: "inline", children: [_jsx(Span, { weight: "bold", size: "2xl", color: "primary", children: (averageRating ?? 0).toFixed(1) }), _jsxs(Span, { size: "sm", color: "muted", children: ["/ 5 \u00B7 ", totalReviews, " review", totalReviews === 1 ? "" : "s"] })] })), _jsx(ListingToolbar, { filterCount: activeFilterCount, onFiltersClick: openFilters, searchValue: searchEnabled ? searchInput : undefined, searchPlaceholder: "Search reviews by product name...", onSearchChange: searchEnabled ? setSearchInput : undefined, onSearchCommit: searchEnabled ? commitSearch : undefined, sortValue: effectiveSort, sortOptions: sortOptions, onSortChange: (v) => {
+                    table.set(TABLE_KEYS.SORT, v);
+                }, view: view, onViewChange: handleViewToggle, onResetAll: resetAll, hasActiveState: hasActiveState }), stateMode === "url" && paginationBlock && (_jsx(StickyToolbar, { offset: "header+pagination", tone: "translucent", border: true, padding: "toolbar", children: paginationBlock })), _jsx(Div, { padding: "y-lg", children: isLoading ? (_jsx(Div, { layout: "grid", gap: "6", className: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", children: Array.from({ length: 6 }).map((_, i) => (_jsx(Div, { className: `${__O.hidden} animate-pulse`, border: "subtle", rounded: "xl", children: _jsxs(Stack, { className: `${__P.p4}`, gap: "3", children: [_jsx(Div, { className: "h-4 w-3/4", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-full", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-2/3", surface: "subtle", rounded: "default" })] }) }, i))) })) : reviews.length === 0 ? (_jsx(Text, { paddingY: "3xl", color: "muted", size: "sm", align: "start", children: emptyLabel })) : view === "list" ? (_jsx(Stack, { className: "divide-y divide-zinc-100 divide-[var(--appkit-color-border-subtle)]", border: "subtle", rounded: "xl", children: reviews.map((review) => (_jsx(ReviewCard, { review: review, context: context }, review.id))) })) : (_jsx(Div, { layout: "grid", gap: "6", className: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", children: reviews.map((review) => (_jsx(ReviewCard, { review: review, context: context }, review.id))) })) }), stateMode === "local" && paginationBlock, _jsx(ListingFilterDrawer, { open: filterOpen, onClose: () => setFilterOpen(false), onApply: applyFilters, onClear: clearFilters, activeCount: activeFilterCount, children: _jsx(ReviewFilters, { table: pendingTable, variant: variant, keys: filterKeys }) })] }));
+}

package/dist/features/reviews/components/index.d.ts

@@ -8,4 +8,6 @@ export type { ViewReviewModalProps } from "./ReviewModal";
 export { ViewReviewModal } from "./ReviewModal";
 export { ReviewsIndexListing } from "./ReviewsIndexListing";
 export type { ReviewsIndexListingProps } from "./ReviewsIndexListing";
+export { ReviewsListingPanel } from "./ReviewsListingPanel";
+export type { ReviewsListingPanelProps, ReviewsSource } from "./ReviewsListingPanel";
 export type { ReviewDetailPageViewProps } from "./ReviewDetailPageView";

package/dist/features/reviews/components/index.js

@@ -3,3 +3,4 @@ export { ReviewFilters, REVIEW_SORT_OPTIONS, REVIEW_FILTER_KEYS, REVIEW_ADMIN_SO
 export { ReviewSummary } from "./ReviewSummary";
 export { ViewReviewModal } from "./ReviewModal";
 export { ReviewsIndexListing } from "./ReviewsIndexListing";
+export { ReviewsListingPanel } from "./ReviewsListingPanel";

package/dist/features/reviews/hooks/useReviews.d.ts

@@ -12,6 +12,7 @@ export declare function useReviews(params?: ReviewListParams, opts?: UseReviewsO
     hasMore: boolean;
     averageRating: number | undefined;
     ratingDistribution: Record<number, number> | undefined;
+    totalApproved: number | undefined;
     isLoading: boolean;
     error: Error | null;
     refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<ReviewListResponse>, Error>>;
@@ -19,7 +20,13 @@ export declare function useReviews(params?: ReviewListParams, opts?: UseReviewsO
 interface UseProductReviewsOptions {
     page?: number;
     pageSize?: number;
+    sort?: string;
+    rating?: number | string;
+    dateFrom?: string;
+    dateTo?: string;
+    hasImages?: boolean;
     enabled?: boolean;
+    initialData?: ReviewListResponse;
 }
 export declare function useProductReviews(productId: string, opts?: UseProductReviewsOptions): {
     reviews: import("..").Review[];
@@ -28,6 +35,7 @@ export declare function useProductReviews(productId: string, opts?: UseProductRe
     hasMore: boolean;
     averageRating: number | undefined;
     ratingDistribution: Record<number, number> | undefined;
+    totalApproved: number | undefined;
     isLoading: boolean;
     error: Error | null;
     refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<NoInfer<ReviewListResponse>, Error>>;

package/dist/features/reviews/hooks/useReviews.js

@@ -15,8 +15,8 @@ export function useReviews(params = {}, opts) {
         sp.set("featured", String(params.featured));
     if (params.page)
         sp.set("page", String(params.page));
-    if (params.perPage)
-        sp.set("perPage", String(params.perPage));
+    if (params.pageSize)
+        sp.set("pageSize", String(params.pageSize));
     if (params.sort)
         sp.set("sort", params.sort);
     if (params.q)
@@ -31,8 +31,10 @@ export function useReviews(params = {}, opts) {
         sp.set("maxVotes", String(params.maxVotes));
     if (params.hasImages)
         sp.set("hasImages", "true");
-    // General listing mode (no productId)
-    if (!params.productId && !params.userId && !params.storeId) {
+    // General listing mode (no productId). Store-scoped reads go through
+    // useStoreReviews / `/api/stores/[slug]/reviews`, not this endpoint — `/api/reviews`
+    // has no storeId branch, so a storeId here would 400 on the productId guard.
+    if (!params.productId && !params.userId) {
         sp.set("latest", "true");
     }
     const qs = sp.toString();
@@ -50,6 +52,7 @@ export function useReviews(params = {}, opts) {
         hasMore: query.data?.hasMore ?? false,
         averageRating: query.data?.averageRating,
         ratingDistribution: query.data?.ratingDistribution,
+        totalApproved: query.data?.totalApproved,
         isLoading: query.isLoading,
         error: query.error,
         refetch: query.refetch,
@@ -60,6 +63,11 @@ export function useProductReviews(productId, opts) {
         productId,
         status: "approved",
         page: opts?.page,
-        perPage: opts?.pageSize,
-    }, { enabled: opts?.enabled });
+        pageSize: opts?.pageSize,
+        sort: opts?.sort,
+        rating: opts?.rating,
+        dateFrom: opts?.dateFrom,
+        dateTo: opts?.dateTo,
+        hasImages: opts?.hasImages,
+    }, { enabled: opts?.enabled, initialData: opts?.initialData });
 }

package/dist/features/reviews/repository/reviews.repository.d.ts

@@ -14,7 +14,16 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     create(input: ReviewCreateInput): Promise<ReviewDocument>;
     update(reviewId: string, data: Partial<ReviewDocument>): Promise<ReviewDocument>;
     findByProduct(productId: string): Promise<ReviewDocument[]>;
-    findApprovedByProduct(productId: string): Promise<ReviewDocument[]>;
+    /**
+     * Approved reviews for a product, newest first.
+     *
+     * `limit` is optional and deliberately has no default — callers that page or aggregate
+     * should use `listForProduct` / `getApprovedRatingSummary` instead, and the remaining
+     * callers each pass their own explicit bound. Silently capping here would truncate
+     * consumers that expect the full set (Rule #6 wants the bound at the call site, where
+     * it can be reasoned about).
+     */
+    findApprovedByProduct(productId: string, limit?: number): Promise<ReviewDocument[]>;
     findApprovedByStore(storeId: string): Promise<ReviewDocument[]>;
     findByUser(userId: string): Promise<ReviewDocument[]>;
     findApprovedByUser(userId: string): Promise<ReviewDocument[]>;
@@ -25,10 +34,25 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
     reject(reviewId: string, moderatorId: string, rejectionReason: string, moderatorNote?: string): Promise<ReviewDocument>;
     incrementHelpful(reviewId: string): Promise<void>;
     incrementReportCount(reviewId: string): Promise<void>;
+    /**
+     * Approved-review count, average and per-star distribution for one product.
+     *
+     * Built from Firestore *aggregation* queries (one `count()` per star bucket, run in
+     * parallel) rather than reading the documents. Ratings are `z.number().int().min(1).max(5)`
+     * at the write path, so the five buckets are exhaustive and the average derived from them
+     * is exact. This replaces an unbounded `findApprovedByProduct()` scan that used to sit on
+     * the hot path of every product render and every `/api/reviews?productId=` call (Rule #6).
+     */
+    getApprovedRatingSummary(productId: string): Promise<{
+        total: number;
+        averageRating: number;
+        ratingDistribution: Record<number, number>;
+    }>;
     getAverageRating(productId: string): Promise<number>;
     getRatingDistribution(productId: string): Promise<Record<number, number>>;
     /**
      * Cloud Functions compatibility: approved review count + average by product.
+     * Return shape is load-bearing for the Functions callers — do not change it.
      */
     getApprovedRatingAggregate(productId: string): Promise<ReviewRatingAggregate>;
     /**
@@ -92,6 +116,10 @@ declare class ReviewRepository extends BaseRepository<ReviewDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        hasImages: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         helpfulCount: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/reviews/repository/reviews.repository.js

@@ -1,4 +1,5 @@
-import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
+import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
+import { REVIEW_MAX_RATING, REVIEW_MIN_RATING } from "../../../_internal/shared/features/reviews/config";
 import { addPiiIndices, decryptPiiFields, encryptPiiFields, REVIEW_PII_FIELDS, REVIEW_PII_INDEX_MAP, } from "../../../security";
 import { createReviewId, REVIEW_COLLECTION, } from "../schemas";
 const REVIEW_FIELDS = {
@@ -10,6 +11,7 @@ const REVIEW_FIELDS = {
     CREATED_AT: "createdAt",
     REVIEWEE_ID: "revieweeId",
     REVIEWER_ROLE: "reviewerRole",
+    RATING: "rating",
 };
 class ReviewRepository extends BaseRepository {
     constructor() {
@@ -64,13 +66,23 @@ class ReviewRepository extends BaseRepository {
     async findByProduct(productId) {
         return this.findBy(REVIEW_FIELDS.PRODUCT_ID, productId);
     }
-    async findApprovedByProduct(productId) {
-        const snapshot = await this.db
-            .collection(this.collection)
+    /**
+     * Approved reviews for a product, newest first.
+     *
+     * `limit` is optional and deliberately has no default — callers that page or aggregate
+     * should use `listForProduct` / `getApprovedRatingSummary` instead, and the remaining
+     * callers each pass their own explicit bound. Silently capping here would truncate
+     * consumers that expect the full set (Rule #6 wants the bound at the call site, where
+     * it can be reasoned about).
+     */
+    async findApprovedByProduct(productId, limit) {
+        let query = this.getCollection()
             .where(REVIEW_FIELDS.PRODUCT_ID, "==", productId)
             .where(REVIEW_FIELDS.STATUS, "==", "approved")
-            .orderBy(REVIEW_FIELDS.CREATED_AT, "desc")
-            .get();
+            .orderBy(REVIEW_FIELDS.CREATED_AT, "desc");
+        if (limit !== undefined)
+            query = query.limit(limit);
+        const snapshot = await query.get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
     }
     async findApprovedByStore(storeId) {
@@ -147,57 +159,77 @@ class ReviewRepository extends BaseRepository {
             });
         }
     }
+    /**
+     * Approved-review count, average and per-star distribution for one product.
+     *
+     * Built from Firestore *aggregation* queries (one `count()` per star bucket, run in
+     * parallel) rather than reading the documents. Ratings are `z.number().int().min(1).max(5)`
+     * at the write path, so the five buckets are exhaustive and the average derived from them
+     * is exact. This replaces an unbounded `findApprovedByProduct()` scan that used to sit on
+     * the hot path of every product render and every `/api/reviews?productId=` call (Rule #6).
+     */
+    async getApprovedRatingSummary(productId) {
+        const base = this.getCollection()
+            .where(REVIEW_FIELDS.PRODUCT_ID, "==", productId)
+            .where(REVIEW_FIELDS.STATUS, "==", "approved");
+        const buckets = [];
+        for (let r = REVIEW_MIN_RATING; r <= REVIEW_MAX_RATING; r++)
+            buckets.push(r);
+        const counts = await Promise.all(buckets.map((rating) => getFirestoreCount(base.where(REVIEW_FIELDS.RATING, "==", rating))));
+        const ratingDistribution = {};
+        let total = 0;
+        let weighted = 0;
+        buckets.forEach((rating, i) => {
+            const count = counts[i] ?? 0;
+            ratingDistribution[rating] = count;
+            total += count;
+            weighted += count * rating;
+        });
+        return {
+            total,
+            averageRating: total > 0 ? weighted / total : 0,
+            ratingDistribution,
+        };
+    }
     async getAverageRating(productId) {
-        const reviews = await this.findApprovedByProduct(productId);
-        if (reviews.length === 0)
-            return 0;
-        const sum = reviews.reduce((acc, review) => acc + review.rating, 0);
-        return sum / reviews.length;
+        const { averageRating } = await this.getApprovedRatingSummary(productId);
+        return averageRating;
     }
     async getRatingDistribution(productId) {
-        const reviews = await this.findApprovedByProduct(productId);
-        const distribution = {
-            1: 0,
-            2: 0,
-            3: 0,
-            4: 0,
-            5: 0,
-        };
-        reviews.forEach((review) => {
-            distribution[review.rating]++;
-        });
-        return distribution;
+        const { ratingDistribution } = await this.getApprovedRatingSummary(productId);
+        return ratingDistribution;
     }
     /**
      * Cloud Functions compatibility: approved review count + average by product.
+     * Return shape is load-bearing for the Functions callers — do not change it.
      */
     async getApprovedRatingAggregate(productId) {
-        const reviews = await this.findApprovedByProduct(productId);
-        if (reviews.length === 0) {
+        const { total, averageRating } = await this.getApprovedRatingSummary(productId);
+        if (total === 0)
             return { count: 0, avgRating: 0 };
-        }
-        const sum = reviews.reduce((acc, review) => acc + review.rating, 0);
-        const count = reviews.length;
-        const avgRating = Math.round((sum / count) * 10) / 10;
-        return { count, avgRating };
+        return { count: total, avgRating: Math.round(averageRating * 10) / 10 };
     }
     /**
      * Cloud Functions compatibility: approved review count + average by store.
      */
     async getApprovedRatingAggregateByStore(storeId) {
-        const snapshot = await this.db
-            .collection(this.collection)
+        // Same aggregation-query approach as getApprovedRatingSummary — no document reads.
+        const base = this.getCollection()
             .where(REVIEW_FIELDS.STORE_ID, "==", storeId)
-            .where(REVIEW_FIELDS.STATUS, "==", "approved")
-            .get();
-        if (snapshot.empty) {
+            .where(REVIEW_FIELDS.STATUS, "==", "approved");
+        const buckets = [];
+        for (let r = REVIEW_MIN_RATING; r <= REVIEW_MAX_RATING; r++)
+            buckets.push(r);
+        const counts = await Promise.all(buckets.map((rating) => getFirestoreCount(base.where(REVIEW_FIELDS.RATING, "==", rating))));
+        let count = 0;
+        let weighted = 0;
+        buckets.forEach((rating, i) => {
+            count += counts[i] ?? 0;
+            weighted += (counts[i] ?? 0) * rating;
+        });
+        if (count === 0)
             return { count: 0, avgRating: 0 };
-        }
-        const reviews = snapshot.docs.map((doc) => this.mapDoc(doc));
-        const sum = reviews.reduce((acc, review) => acc + review.rating, 0);
-        const count = reviews.length;
-        const avgRating = Math.round((sum / count) * 10) / 10;
-        return { count, avgRating };
+        return { count, avgRating: Math.round((weighted / count) * 10) / 10 };
     }
     /** Find reviews where this user is the reviewee (seller→buyer reviews received by a buyer). */
     async findByReviewee(revieweeId) {
@@ -259,6 +291,10 @@ ReviewRepository.SIEVE_FIELDS = {
     status: { canFilter: true, canSort: true },
     rating: { canFilter: true, canSort: true },
     verified: { canFilter: true, canSort: false },
+    // Denormalised flag that exists specifically to make `hasImages==true` queryable —
+    // it was missing here, so the sieve whitelist silently dropped the clause and the
+    // "with photos only" filter did nothing.
+    hasImages: { canFilter: true, canSort: false },
     helpfulCount: { canFilter: true, canSort: true },
     featured: { canFilter: true, canSort: false },
     reportCount: { canFilter: true, canSort: true },

package/dist/features/reviews/types/index.d.ts

@@ -43,6 +43,12 @@ export interface ReviewListResponse {
     hasMore: boolean;
     averageRating?: number;
     ratingDistribution?: Record<number, number>;
+    /**
+     * Total approved reviews ignoring any active filters — `total` above is the filtered
+     * count and changes as the user narrows by rating/date, which makes it wrong for the
+     * "N reviews" summary line next to the average.
+     */
+    totalApproved?: number;
 }
 export interface ReviewListParams {
     productId?: string;
@@ -52,7 +58,8 @@ export interface ReviewListParams {
     rating?: number | string;
     featured?: boolean;
     page?: number;
-    perPage?: number;
+    /** Must stay named `pageSize` — that is the query param `/api/reviews` actually reads. */
+    pageSize?: number;
     sort?: string;
     q?: string;
     dateFrom?: string;

package/dist/features/seller/components/SellerProductsCards.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Badge, Button, Checkbox, Div, Grid, Row, Stack, Text, TextLink } from "../../../ui";
 import { MediaImage } from "../../media/MediaImage";
 import { ROW_ACTION_META, ROW_ACTION_ID } from "../../../features/products/constants/action-defs";
-import { LISTING_BADGE_VARIANT } from "../../products/utils/listing-badge-variant";
+import { listingBadgeVariant } from "../../products/utils/listing-badge-variant";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
@@ -25,6 +25,6 @@ export function SellerProductsCards({ view, rows, isLoading, listingKind, select
     return (_jsxs(Container, { ...containerProps, children: [rows.length === 0 && !isLoading && (_jsx(Text, { className: "text-[var(--appkit-color-text-muted)] col-span-full", size: "sm", children: listingKind !== "all" ? `No ${listingKind} listings found` : "No products listed yet" })), rows.map((row) => {
                 const isSelected = selectedIds.has(row.id);
                 const href = buildHref(row);
-                return view === "grid" ? (_jsxs(Div, { className: "group relative bg-[var(--appkit-color-surface)] overflow-hidden", shadow: "hover-md", rounded: "xl", border: isSelected ? "strong" : "default", children: [_jsx(Div, { className: "absolute top-2 left-2 z-10", children: _jsx(Checkbox, { bare: true, checked: isSelected, onChange: () => toggle(row.id), className: "h-4 w-4 rounded border-[var(--appkit-color-border)]", onClick: (e) => e.stopPropagation(), "aria-label": "Select" }) }), _jsxs(TextLink, { href: href, className: "block", children: [_jsx(Div, { className: "w-full aspect-square", children: _jsx(MediaImage, { src: row.imageUrl, alt: row.primary, size: "card" }) }), _jsxs(Stack, { className: `${__P.p3}`, gap: "xs", children: [_jsx(Text, { className: "line-clamp-1", size: "sm", weight: "medium", children: row.primary }), _jsxs(Row, { gap: "sm", children: [_jsx(Badge, { variant: LISTING_BADGE_VARIANT[row.listingKind] ?? "default", children: row.listingKind }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] line-clamp-1", size: "xs", children: row.secondary })] })] })] }), _jsxs(Row, { className: "border-t border-[var(--appkit-color-border)]", justify: "end", gap: "xs", padding: "xs", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: (e) => { e.stopPropagation(); onEdit(row); }, "aria-label": "Edit", children: ROW_ACTION_META[ROW_ACTION_ID.EDIT].label }), _jsx(Button, { variant: "ghost", size: "sm", onClick: (e) => { e.stopPropagation(); onDuplicate(row); }, "aria-label": "Duplicate", children: ROW_ACTION_META[ROW_ACTION_ID.DUPLICATE].label }), onDelete && (_jsx(Button, { variant: "ghost", size: "sm", onClick: (e) => { e.stopPropagation(); onDelete(row); }, "aria-label": "Delete", children: ROW_ACTION_META[ROW_ACTION_ID.DELETE].label }))] })] }, row.id)) : (_jsxs(Row, { className: "bg-[var(--appkit-color-surface)] hover:bg-[var(--appkit-color-surface-raised)]", align: "center", gap: "3", rounded: "lg", padding: "inlineSm", border: isSelected ? "strong" : "default", children: [_jsx(Checkbox, { bare: true, checked: isSelected, onChange: () => toggle(row.id), className: "h-4 w-4 rounded border-[var(--appkit-color-border)]", "aria-label": "Select" }), _jsx(Div, { className: `w-12 h-12 ${__O.hidden}`, rounded: "default", children: _jsx(MediaImage, { src: row.imageUrl, alt: row.primary, size: "thumbnail" }) }), _jsxs(TextLink, { href: href, className: "flex-1 min-w-0", children: [_jsx(Text, { className: "line-clamp-1", size: "sm", weight: "medium", children: row.primary }), _jsxs(Row, { gap: "sm", children: [_jsx(Badge, { variant: LISTING_BADGE_VARIANT[row.listingKind] ?? "default", children: row.listingKind }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] line-clamp-1", size: "xs", children: row.secondary })] })] }), _jsxs(Row, { className: "flex-shrink-0", gap: "xs", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => onEdit(row), "aria-label": "Edit", children: ROW_ACTION_META[ROW_ACTION_ID.EDIT].label }), _jsx(Button, { variant: "ghost", size: "sm", onClick: () => onDuplicate(row), "aria-label": "Duplicate", children: ROW_ACTION_META[ROW_ACTION_ID.DUPLICATE].label }), onDelete && (_jsx(Button, { variant: "ghost", size: "sm", onClick: () => onDelete(row), "aria-label": "Delete", children: ROW_ACTION_META[ROW_ACTION_ID.DELETE].label }))] })] }, row.id));
+                return view === "grid" ? (_jsxs(Div, { className: "group relative bg-[var(--appkit-color-surface)] overflow-hidden", shadow: "hover-md", rounded: "xl", border: isSelected ? "strong" : "default", children: [_jsx(Div, { className: "absolute top-2 left-2 z-10", children: _jsx(Checkbox, { bare: true, checked: isSelected, onChange: () => toggle(row.id), className: "h-4 w-4 rounded border-[var(--appkit-color-border)]", onClick: (e) => e.stopPropagation(), "aria-label": "Select" }) }), _jsxs(TextLink, { href: href, className: "block", children: [_jsx(Div, { className: "w-full aspect-square", children: _jsx(MediaImage, { src: row.imageUrl, alt: row.primary, size: "card" }) }), _jsxs(Stack, { className: `${__P.p3}`, gap: "xs", children: [_jsx(Text, { className: "line-clamp-1", size: "sm", weight: "medium", children: row.primary }), _jsxs(Row, { gap: "sm", children: [_jsx(Badge, { variant: listingBadgeVariant(row.listingKind), children: row.listingKind }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] line-clamp-1", size: "xs", children: row.secondary })] })] })] }), _jsxs(Row, { className: "border-t border-[var(--appkit-color-border)]", justify: "end", gap: "xs", padding: "xs", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: (e) => { e.stopPropagation(); onEdit(row); }, "aria-label": "Edit", children: ROW_ACTION_META[ROW_ACTION_ID.EDIT].label }), _jsx(Button, { variant: "ghost", size: "sm", onClick: (e) => { e.stopPropagation(); onDuplicate(row); }, "aria-label": "Duplicate", children: ROW_ACTION_META[ROW_ACTION_ID.DUPLICATE].label }), onDelete && (_jsx(Button, { variant: "ghost", size: "sm", onClick: (e) => { e.stopPropagation(); onDelete(row); }, "aria-label": "Delete", children: ROW_ACTION_META[ROW_ACTION_ID.DELETE].label }))] })] }, row.id)) : (_jsxs(Row, { className: "bg-[var(--appkit-color-surface)] hover:bg-[var(--appkit-color-surface-raised)]", align: "center", gap: "3", rounded: "lg", padding: "inlineSm", border: isSelected ? "strong" : "default", children: [_jsx(Checkbox, { bare: true, checked: isSelected, onChange: () => toggle(row.id), className: "h-4 w-4 rounded border-[var(--appkit-color-border)]", "aria-label": "Select" }), _jsx(Div, { className: `w-12 h-12 ${__O.hidden}`, rounded: "default", children: _jsx(MediaImage, { src: row.imageUrl, alt: row.primary, size: "thumbnail" }) }), _jsxs(TextLink, { href: href, className: "flex-1 min-w-0", children: [_jsx(Text, { className: "line-clamp-1", size: "sm", weight: "medium", children: row.primary }), _jsxs(Row, { gap: "sm", children: [_jsx(Badge, { variant: listingBadgeVariant(row.listingKind), children: row.listingKind }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)] line-clamp-1", size: "xs", children: row.secondary })] })] }), _jsxs(Row, { className: "flex-shrink-0", gap: "xs", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => onEdit(row), "aria-label": "Edit", children: ROW_ACTION_META[ROW_ACTION_ID.EDIT].label }), _jsx(Button, { variant: "ghost", size: "sm", onClick: () => onDuplicate(row), "aria-label": "Duplicate", children: ROW_ACTION_META[ROW_ACTION_ID.DUPLICATE].label }), onDelete && (_jsx(Button, { variant: "ghost", size: "sm", onClick: () => onDelete(row), "aria-label": "Delete", children: ROW_ACTION_META[ROW_ACTION_ID.DELETE].label }))] })] }, row.id));
             })] }));
 }