@betterreviews/react-native 1.0.0

package/src/sections/ReviewsSummarySection.tsx

@@ -0,0 +1,47 @@
+/**
+ * Renders the `reviews_summary` section. v1 displays a placeholder
+ * — the partner host app is expected to supply the live aggregate
+ * (star rating, count, top quote) by mounting its own review-summary
+ * component as a child or sibling.
+ *
+ * The presence of this section in the metafield blob is the merchant's
+ * "show me the reviews summary on this product" toggle. Absence means
+ * "don't render this section." A future PR may expand this to render
+ * `betterreviews.summary` data directly when supplied via
+ * `BetterReviewsProvider`'s `summary` prop.
+ */
+
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { useBetterReviews } from '../BetterReviewsProvider.js';
+import { applyTheme } from '../theme/applyTheme.js';
+
+export function ReviewsSummarySection(): React.ReactElement {
+  const { theme } = useBetterReviews();
+  const resolved = applyTheme(theme);
+
+  return (
+    // Flat — no background fill / box; reads as normal page text.
+    <View style={styles.container}>
+      <Text
+        style={[
+          styles.label,
+          resolved.textColor ? { color: resolved.textColor } : null,
+          resolved.fontFamily ? { fontFamily: resolved.fontFamily } : null,
+        ]}
+      >
+        Customer reviews
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    paddingVertical: 8,
+  },
+  label: {
+    fontSize: 16,
+    fontWeight: '600',
+  },
+});

package/src/telemetry.ts

@@ -0,0 +1,52 @@
+/**
+ * Telemetry event types emitted by the package. Per SECURITY.md, all
+ * events are pre-redacted — no customer email, name, IP, transcript,
+ * or review content appears in any payload.
+ *
+ * Consumers (partner host apps) wire `onTelemetryEvent` on the
+ * `<BetterReviewsProvider>` to forward events to their own
+ * observability stack.
+ */
+
+export type TelemetryEvent =
+  | { type: 'betterreviews.fetch.success'; block_id?: string; latency_ms?: number; cache_hit?: boolean }
+  | { type: 'betterreviews.fetch.failure'; block_id?: string; error_code: string; retry_attempt?: number }
+  | { type: 'betterreviews.signature.invalid'; endpoint?: string; source_ip_hash?: string }
+  | {
+      type: 'betterreviews.schema.violation';
+      schema_version: number;
+      violation_path?: string;
+      // Count of rows/items dropped in one response (one event per response,
+      // not one per row). Paths + counts only — never row contents.
+      dropped_count?: number;
+    }
+  | { type: 'betterreviews.webview.error'; error_code: string; url_origin?: string };
+
+export type TelemetryHandler = (event: TelemetryEvent) => void;
+
+const noopHandler: TelemetryHandler = () => {};
+
+/**
+ * Returns a handler that swallows all events. Used as the default
+ * when the partner host app doesn't supply `onTelemetryEvent`.
+ */
+export function noopTelemetry(): TelemetryHandler {
+  return noopHandler;
+}
+
+/**
+ * Wraps a handler so synchronous exceptions in the partner's
+ * implementation can't crash the renderer. Partner-side bugs become
+ * silent failures rather than UI outages.
+ */
+export function safeTelemetry(handler: TelemetryHandler | undefined): TelemetryHandler {
+  if (!handler) return noopHandler;
+
+  return (event) => {
+    try {
+      handler(event);
+    } catch {
+      // Telemetry must never crash render. Swallow.
+    }
+  };
+}

package/src/theme/applyTheme.ts

@@ -0,0 +1,72 @@
+/**
+ * Maps a `betterreviews_reactiv.theme` JSON blob to a flat StyleSheet
+ * record consumed by the section renderers. All fields are optional —
+ * absent fields fall back to RN's platform defaults.
+ *
+ * The shape matches `PPO.Reactiv.ContentResolver.build_theme/1` —
+ * flat color keys + corner_style enum + font_family enum.
+ */
+
+import type { Theme } from '../../../schemas/src/theme.js';
+
+// Maps `corner_style` enum to a numeric `borderRadius` value usable
+// directly in RN style props.
+const cornerRadiusMap: Record<string, number> = {
+  sharp: 0,
+  'slightly-rounded': 8,
+  rounded: 20,
+  'extra-rounded': 28,
+};
+
+// Maps `font_family` enum to an RN-friendly font family string.
+// `'system'` resolves to platform default at render time (RN's null
+// `fontFamily` already does this, so we omit the key entirely for
+// 'system' to let RN fall back naturally).
+const fontFamilyMap: Record<string, string | null> = {
+  system: null,
+  serif: 'Georgia',
+  'sans-serif': 'System',
+  mono: 'Courier',
+};
+
+export interface ResolvedTheme {
+  primaryColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  accentColor?: string;
+  borderRadius?: number;
+  fontFamily?: string;
+}
+
+/**
+ * Pure function — no React, no platform calls. Maps a Theme blob to a
+ * ResolvedTheme suitable for spreading into style props.
+ *
+ * Unknown enum values for `corner_style` / `font_family` resolve to
+ * `undefined` (the schema validator at the write boundary already
+ * rejects unknown values, but defensive in case of a malformed
+ * payload landing in the read path).
+ */
+export function applyTheme(theme: Theme | null | undefined): ResolvedTheme {
+  if (!theme) return {};
+
+  const out: ResolvedTheme = {};
+
+  if (theme.primary_color) out.primaryColor = theme.primary_color;
+  if (theme.background_color) out.backgroundColor = theme.background_color;
+  if (theme.text_color) out.textColor = theme.text_color;
+  if (theme.accent_color) out.accentColor = theme.accent_color;
+
+  if (theme.corner_style && theme.corner_style in cornerRadiusMap) {
+    out.borderRadius = cornerRadiusMap[theme.corner_style];
+  }
+
+  if (theme.font_family && theme.font_family in fontFamilyMap) {
+    const resolved = fontFamilyMap[theme.font_family];
+    if (resolved !== null && resolved !== undefined) {
+      out.fontFamily = resolved;
+    }
+  }
+
+  return out;
+}

package/src/theme/widgetTheme.ts

@@ -0,0 +1,67 @@
+/**
+ * Resolved theme for the review widget.
+ *
+ * v1 policy (locked): the merchant's `betterreviews_reactiv.theme` supplies
+ * background / text / accent / corner-radius / font (via the existing
+ * `applyTheme`); everything else — star, verified, muted, border, scrim — is
+ * a FIXED neutral. Per-surface theming of those is a later additive schema
+ * bump, so widening this resolver is non-breaking.
+ *
+ * Color set mirrors the prototype's `THEME` constant.
+ */
+import { applyTheme } from './applyTheme.js';
+import type { Theme } from '../../../schemas/src/theme.js';
+
+// Neutral defaults — zinc grayscale + a black CTA. The widget shows NO brand
+// color unless the host passes `accent_color`/`background_color`/`text_color`.
+// The only non-grayscale defaults are the gold star/bars and the green
+// "Verified Buyer" badge (universal review conventions, fixed in v1).
+export const WIDGET_NEUTRALS = {
+  bg: '#ffffff',
+  text: '#18181b', // zinc-900
+  accent: '#18181b', // black CTA
+  card: '#fafafa', // zinc-50
+  muted: '#f4f4f5', // zinc-100
+  mutedFg: '#71717a', // zinc-500
+  border: '#e4e4e7', // zinc-200
+  star: '#e8a808', // gold — fixed
+  verified: '#1c8c4d', // green — fixed Verified Buyer badge
+  verifiedBg: '#e2f1e9',
+  mark: 'rgba(228,228,231,0.6)', // zinc highlight
+  overflowScrim: 'rgba(0,0,0,0.55)',
+} as const;
+
+export interface WidgetTheme {
+  bg: string;
+  text: string;
+  accent: string;
+  card: string;
+  muted: string;
+  mutedFg: string;
+  border: string;
+  star: string;
+  verified: string;
+  verifiedBg: string;
+  mark: string;
+  overflowScrim: string;
+  /** From `corner_style` — applied to cards/buttons; undefined = RN default. */
+  cornerRadius?: number;
+  /** From `font_family`; undefined = platform default. */
+  fontFamily?: string;
+}
+
+/**
+ * Merge the merchant theme (bg/text/accent/corner/font) over the fixed
+ * neutrals. Pure — safe to call during render.
+ */
+export function resolveWidgetTheme(theme: Theme | null | undefined): WidgetTheme {
+  const r = applyTheme(theme);
+  return {
+    ...WIDGET_NEUTRALS,
+    bg: r.backgroundColor ?? WIDGET_NEUTRALS.bg,
+    text: r.textColor ?? WIDGET_NEUTRALS.text,
+    accent: r.accentColor ?? WIDGET_NEUTRALS.accent,
+    cornerRadius: r.borderRadius,
+    fontFamily: r.fontFamily,
+  };
+}

package/src/webviewMessage.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure helpers for messages posted from the embedded WebView page. Kept free
+ * of `react-native` / `react-native-webview` imports so it is unit-testable in
+ * plain Node (vitest), unlike `WebViewHost.tsx` itself.
+ */
+
+/**
+ * True when the embedded page posted `{ "type": "close" }` (the chat's
+ * "Back to store" / done signal). Safe on any string — non-JSON, `null`, and
+ * primitives all return false.
+ */
+export function isCloseSignal(data: string): boolean {
+  try {
+    const parsed: unknown = JSON.parse(data);
+    return (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      (parsed as { type?: unknown }).type === 'close'
+    );
+  } catch {
+    return false;
+  }
+}

package/src/widget/ReviewWidget.tsx

@@ -0,0 +1,230 @@
+/**
+ * `<ReviewWidget>` — the public, stateful review-browsing surface.
+ *
+ * Renders INLINE — it owns no scroll container, so it drops into a host's
+ * product-page `ScrollView` as one section (below the product info /
+ * `ProductContentBlock`) and scrolls with the page. Paging is a "Load more"
+ * button, so no virtualization is needed.
+ *
+ * Theme + telemetry flow from `<BetterReviewsProvider>` context (same
+ * convention as `ProductContentBlock`); transport/auth flow from the host via
+ * the injected `client` (or `fetcher` + ids). Schema violations are emitted as
+ * telemetry from the client's async callback (post-render, so the b9357c30
+ * "no emit during render" rule holds).
+ */
+import React, { useMemo, useState } from 'react';
+import { ActivityIndicator, Pressable, Text, View } from 'react-native';
+import { useBetterReviews } from '../BetterReviewsProvider.js';
+import { createBetterReviewsClient, createMemoryVoteStore } from '../client/createBetterReviewsClient.js';
+import type {
+  BetterReviewsClient,
+  Fetcher,
+  VoteStateStore,
+  WidgetReview,
+  WidgetSortValue,
+} from '../client/types.js';
+import { resolveWidgetTheme } from '../theme/widgetTheme.js';
+import { MediaGallery, type GalleryPhoto } from './components/MediaGallery.js';
+import { FilterToolbar, SortBar, WriteReviewBtn } from './components/FilterToolbar.js';
+import { PulseMetrics, PulseSummary, SectionTitle } from './components/PulseSection.js';
+import { ReviewCard } from './components/ReviewCard.js';
+import { SortDrawer } from './components/SortDrawer.js';
+import { StaleListOverlay } from './components/StaleListOverlay.js';
+import { useReviewList } from './hooks/useReviewList.js';
+import { useReviewSummary } from './hooks/useReviewSummary.js';
+import { makeWidgetStyles } from './styles.js';
+import { MediaReviewViewer } from './viewer/MediaReviewViewer.js';
+import { WidgetProvider, type WidgetContextValue } from './WidgetContext.js';
+
+export interface ReviewWidgetProps {
+  /** Primary: a client built via `createBetterReviewsClient`. */
+  client?: BetterReviewsClient;
+  /** Convenience: supply transport + ids and the widget builds the client. */
+  fetcher?: Fetcher;
+  storeId?: string;
+  productId?: string;
+  /** Persist "already voted" across launches; defaults to in-memory. */
+  voteStateStore?: VoteStateStore;
+  /** Host-owned write-review action; the CTA hides if omitted. */
+  onWriteReview?: () => void;
+  initialSort?: WidgetSortValue;
+}
+
+export function ReviewWidget(props: ReviewWidgetProps): React.ReactElement {
+  const { client: clientProp, fetcher, storeId, productId, voteStateStore, onWriteReview, initialSort } = props;
+  const { theme: rawTheme, emit } = useBetterReviews();
+
+  const client = useMemo<BetterReviewsClient>(() => {
+    if (clientProp) return clientProp;
+    if (!fetcher || !storeId || !productId) {
+      throw new Error(
+        '<ReviewWidget> requires either a `client` or `fetcher` + `storeId` + `productId`.',
+      );
+    }
+    return createBetterReviewsClient({
+      fetcher,
+      storeId,
+      productId,
+      onSchemaViolation: (info) =>
+        emit({
+          type: 'betterreviews.schema.violation',
+          schema_version: 1,
+          violation_path: info.firstBadPath,
+          dropped_count: info.droppedCount,
+        }),
+    });
+  }, [clientProp, fetcher, storeId, productId, emit]);
+
+  const theme = useMemo(() => resolveWidgetTheme(rawTheme), [rawTheme]);
+  const styles = useMemo(() => makeWidgetStyles(theme), [theme]);
+  const fallbackStore = useMemo(() => createMemoryVoteStore(), []);
+  const voteStore = voteStateStore ?? fallbackStore;
+
+  const list = useReviewList(client, emit, initialSort);
+  const summary = useReviewSummary(client);
+  const [viewer, setViewer] = useState<{ reviewId: number; mediaIndex: number } | null>(null);
+  const [sortOpen, setSortOpen] = useState(false);
+
+  const ctx = useMemo<WidgetContextValue>(
+    () => ({ client, voteStore, theme, styles, emit, onWriteReview }),
+    [client, voteStore, theme, styles, emit, onWriteReview],
+  );
+
+  const onOpenPhoto = (reviewId: number, mediaIndex: number) => setViewer({ reviewId, mediaIndex });
+
+  // Flatten reviews[].media → gallery photos (images, deduped by URL, capped).
+  const galleryPhotos = useMemo<GalleryPhoto[]>(() => {
+    const seen = new Set<string>();
+    const out: GalleryPhoto[] = [];
+    for (const r of list.reviews) {
+      const imgs = r.media.filter((m) => m.type === 'image');
+      imgs.forEach((m, i) => {
+        const key = m.full || m.thumbnail;
+        if (!key || seen.has(key)) return;
+        seen.add(key);
+        out.push({ thumbnail: m.thumbnail, full: m.full, reviewId: r.id, mediaIndex: i });
+      });
+      if (out.length >= 24) break;
+    }
+    return out.slice(0, 24);
+  }, [list.reviews]);
+
+  const reviewsWithMedia = useMemo<WidgetReview[]>(
+    () => list.reviews.filter((r) => r.media.some((m) => m.type === 'image')),
+    [list.reviews],
+  );
+
+  const header = (
+    <View>
+      <SectionTitle>Customer Reviews</SectionTitle>
+      {summary && (
+        <View style={styles.pulse}>
+          <PulseSummary summary={summary} />
+          <MediaGallery photos={galleryPhotos} onOpen={onOpenPhoto} />
+          <WriteReviewBtn />
+          <PulseMetrics summary={summary} />
+        </View>
+      )}
+      <FilterToolbar
+        rating={list.rating}
+        mediaOnly={list.mediaOnly}
+        search={list.searchInput}
+        onChange={list.onFilterChange}
+      />
+      <SortBar sort={list.sort} onOpenSort={() => setSortOpen(true)} />
+      <StaleListOverlay active={list.refetching} />
+    </View>
+  );
+
+  // Initial spinner.
+  if (list.loading && list.reviews.length === 0) {
+    return (
+      <WidgetProvider value={ctx}>
+        <View style={styles.center}>
+          <ActivityIndicator color={theme.accent} />
+          <Text style={styles.muted}>Loading reviews…</Text>
+        </View>
+      </WidgetProvider>
+    );
+  }
+
+  if (list.error && list.reviews.length === 0) {
+    return (
+      <WidgetProvider value={ctx}>
+        <View style={styles.center}>
+          <Text style={styles.errorLine}>Reviews unavailable</Text>
+          <Pressable onPress={list.reload} accessibilityHint="Tap to try loading reviews again">
+            <Text style={styles.retryLink}>Try again</Text>
+          </Pressable>
+        </View>
+      </WidgetProvider>
+    );
+  }
+
+  // total>0 but nothing rendered ⇒ rows failed to parse (contract break),
+  // distinct from a genuinely empty/filtered product.
+  const allDropped = list.reviews.length === 0 && (list.pagination?.total ?? 0) > 0;
+
+  return (
+    <WidgetProvider value={ctx}>
+      {/* Inline — no scroll container. The host's product-page ScrollView owns
+          the scroll; this is one section that flows with the page. */}
+      <View style={styles.list}>
+        {header}
+        {list.reviews.length === 0 ? (
+          <View style={styles.emptyState}>
+            <Text style={styles.emptyStateText}>
+              {allDropped ? 'Reviews could not be displayed.' : 'No reviews match your filter.'}
+            </Text>
+            {!allDropped && (
+              <Pressable onPress={() => list.onFilterChange({ rating: null, mediaOnly: false, search: '' })}>
+                <Text style={styles.emptyStateClear}>Clear filters</Text>
+              </Pressable>
+            )}
+          </View>
+        ) : (
+          list.reviews.map((item) => (
+            <View key={item.id} style={list.refetching ? { opacity: 0.5 } : undefined}>
+              <ReviewCard review={item} onOpenPhoto={onOpenPhoto} />
+            </View>
+          ))
+        )}
+        {list.pagination?.has_next && (
+          <View style={styles.footerWrap}>
+            <Pressable
+              onPress={list.onLoadMore}
+              disabled={list.loadingMore}
+              style={({ pressed }: { pressed: boolean }) => [
+                styles.showMore,
+                list.loadingMore && styles.showMoreDisabled,
+                pressed && { borderColor: theme.text },
+              ]}
+              accessibilityRole="button"
+              accessibilityLabel="Load more reviews"
+            >
+              {list.loadingMore ? (
+                <ActivityIndicator color={theme.text} />
+              ) : (
+                <Text style={styles.showMoreText}>Load more</Text>
+              )}
+            </Pressable>
+          </View>
+        )}
+      </View>
+      <SortDrawer
+        visible={sortOpen}
+        current={list.sort}
+        onSelect={list.setSort}
+        onClose={() => setSortOpen(false)}
+      />
+      {viewer && reviewsWithMedia.length > 0 && (
+        <MediaReviewViewer
+          reviews={reviewsWithMedia}
+          initialReviewId={viewer.reviewId}
+          initialMediaIndex={viewer.mediaIndex}
+          onClose={() => setViewer(null)}
+        />
+      )}
+    </WidgetProvider>
+  );
+}

package/src/widget/WidgetContext.tsx

@@ -0,0 +1,43 @@
+/**
+ * Internal widget-scoped context. Threads the resolved client, vote-state
+ * store, resolved theme, the memoized StyleSheet, the telemetry emitter, and
+ * the host's write-review handler down to deeply-nested children (ReviewCard,
+ * ViewerPage) without prop-drilling through FlatList `renderItem`.
+ *
+ * This does NOT replace `BetterReviewsProvider` — it is mounted internally at
+ * the top of `<ReviewWidget>`.
+ */
+import React, { createContext, useContext } from 'react';
+import type { BetterReviewsClient, VoteStateStore } from '../client/types.js';
+import type { TelemetryHandler } from '../telemetry.js';
+import type { WidgetTheme } from '../theme/widgetTheme.js';
+import type { WidgetStyles } from './styles.js';
+
+export interface WidgetContextValue {
+  client: BetterReviewsClient;
+  voteStore: VoteStateStore;
+  theme: WidgetTheme;
+  styles: WidgetStyles;
+  emit: TelemetryHandler;
+  onWriteReview?: () => void;
+}
+
+const WidgetContext = createContext<WidgetContextValue | null>(null);
+
+export function WidgetProvider({
+  value,
+  children,
+}: {
+  value: WidgetContextValue;
+  children: React.ReactNode;
+}) {
+  return <WidgetContext.Provider value={value}>{children}</WidgetContext.Provider>;
+}
+
+export function useWidget(): WidgetContextValue {
+  const ctx = useContext(WidgetContext);
+  if (!ctx) {
+    throw new Error('useWidget must be used within <ReviewWidget>');
+  }
+  return ctx;
+}

package/src/widget/components/FilterToolbar.tsx

@@ -0,0 +1,146 @@
+import React from 'react';
+import { Pressable, ScrollView, Text, TextInput, View } from 'react-native';
+import {
+  IconArrowUpDown,
+  IconCamera,
+  IconChevronDown,
+  IconSearch,
+  IconStar,
+  IconXClose,
+} from '../../icons/BRIcons.js';
+import type { WidgetSortValue } from '../../client/types.js';
+import { useWidget } from '../WidgetContext.js';
+import { SORT_OPTIONS } from '../util.js';
+
+export interface FilterPatch {
+  rating?: 1 | 2 | 3 | 4 | 5 | null;
+  mediaOnly?: boolean;
+  search?: string;
+}
+
+export interface FilterToolbarProps {
+  rating: 1 | 2 | 3 | 4 | 5 | null;
+  mediaOnly: boolean;
+  search: string;
+  onChange: (patch: FilterPatch) => void;
+}
+
+export function FilterToolbar({ rating, mediaOnly, search, onChange }: FilterToolbarProps) {
+  const { styles, theme } = useWidget();
+  const ratings: Array<1 | 2 | 3 | 4 | 5> = [5, 4, 3, 2, 1];
+  const showClear = !!(rating || mediaOnly || search);
+  return (
+    <View style={styles.toolbar}>
+      <ScrollView horizontal showsHorizontalScrollIndicator={false} contentContainerStyle={styles.pillsRow}>
+        {ratings.map((r) => {
+          const active = rating === r;
+          return (
+            <Pressable
+              key={r}
+              onPress={() => onChange({ rating: active ? null : r })}
+              style={({ pressed }: { pressed: boolean }) => [
+                styles.pill,
+                pressed && !active && { borderColor: theme.text },
+                active && styles.pillActive,
+              ]}
+              accessibilityRole="button"
+              accessibilityState={{ selected: active }}
+              accessibilityLabel={`${r} stars filter`}
+            >
+              <Text style={[styles.pillText, active && styles.pillTextActive]}>{r}</Text>
+              <IconStar
+                size={10}
+                fillPercentage={100}
+                fillColor={active ? theme.bg : theme.star}
+                uid={`pill-${r}`}
+              />
+            </Pressable>
+          );
+        })}
+        <Pressable
+          onPress={() => onChange({ mediaOnly: !mediaOnly })}
+          style={({ pressed }: { pressed: boolean }) => [
+            styles.pill,
+            styles.pillWithIcon,
+            pressed && !mediaOnly && { borderColor: theme.text },
+            mediaOnly && styles.pillActive,
+          ]}
+          accessibilityRole="button"
+          accessibilityState={{ selected: mediaOnly }}
+          accessibilityLabel="Show only reviews with photos"
+        >
+          <IconCamera size={12} color={mediaOnly ? theme.bg : theme.text} />
+          <Text style={[styles.pillText, mediaOnly && styles.pillTextActive]}>Photos</Text>
+        </Pressable>
+        {showClear && (
+          <Pressable
+            onPress={() => onChange({ rating: null, mediaOnly: false, search: '' })}
+            style={({ pressed }: { pressed: boolean }) => [styles.clearBtn, pressed && { opacity: 0.6 }]}
+          >
+            <IconXClose size={12} color={theme.mutedFg} />
+            <Text style={styles.clearBtnText}>Clear</Text>
+          </Pressable>
+        )}
+      </ScrollView>
+      <View style={styles.searchWrap}>
+        <IconSearch size={14} color={theme.mutedFg} style={{ marginRight: 8 }} />
+        <TextInput
+          style={styles.searchInput}
+          placeholder="Search reviews..."
+          placeholderTextColor={theme.mutedFg}
+          value={search}
+          onChangeText={(t) => onChange({ search: t })}
+          maxLength={100}
+          autoCorrect={false}
+          autoCapitalize="none"
+          returnKeyType="search"
+        />
+        {!!search && (
+          <Pressable
+            onPress={() => onChange({ search: '' })}
+            hitSlop={8}
+            style={({ pressed }: { pressed: boolean }) => [styles.searchClear, pressed && { opacity: 0.5 }]}
+            accessibilityLabel="Clear search"
+          >
+            <IconXClose size={14} color={theme.mutedFg} />
+          </Pressable>
+        )}
+      </View>
+      {search.length > 0 && search.length < 2 && <Text style={styles.searchHint}>Keep typing…</Text>}
+    </View>
+  );
+}
+
+export function SortBar({ sort, onOpenSort }: { sort: WidgetSortValue; onOpenSort: () => void }) {
+  const { styles, theme } = useWidget();
+  const label = SORT_OPTIONS.find((o) => o.value === sort)?.label ?? 'Most relevant';
+  return (
+    <Pressable
+      onPress={onOpenSort}
+      style={({ pressed }: { pressed: boolean }) => [styles.sortBtn, pressed && { borderColor: theme.text }]}
+      accessibilityRole="button"
+      accessibilityLabel={`Sort: ${label}. Tap to change.`}
+    >
+      <IconArrowUpDown size={13} color={theme.text} />
+      <Text style={styles.sortBtnText}>{label}</Text>
+      <IconChevronDown size={12} color={theme.text} />
+    </Pressable>
+  );
+}
+
+// Solid pill CTA. Renders only when the host supplies `onWriteReview` — no
+// dead button if the host hasn't wired the write-review action.
+export function WriteReviewBtn({ label = 'Write a review' }: { label?: string }) {
+  const { styles, onWriteReview } = useWidget();
+  if (!onWriteReview) return null;
+  return (
+    <Pressable
+      onPress={onWriteReview}
+      style={({ pressed }: { pressed: boolean }) => [styles.writeReviewBtn, pressed && { opacity: 0.85 }]}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+    >
+      <Text style={styles.writeReviewBtnText}>{label}</Text>
+    </Pressable>
+  );
+}