@klyftig/mobile-ui 1.5.0 → 1.7.0

package/README.md

@@ -0,0 +1,80 @@
+# @klyftig/mobile-ui
+
+Shared UI for Klyftig's React Native / Expo apps (Kaelo, Nagger, Sleepwise,
+Clev, Stampic). It ships TypeScript source (`main: src/index.ts`), so each app's
+Metro/Babel compiles it. Apps' jest configs must keep `@klyftig/.*` in
+`transformIgnorePatterns`.
+
+Exports: theme tokens (`colors`, `typography`, `spacing`, …), glass components
+(`GlassButton`, `GlassCard`, `CenterDialog`, `WheelPicker`, …) and the
+**review ("Rate Us") module** described below. See `CHANGELOG.md` for the
+version history.
+
+## Peer dependencies
+
+`expo`, `react`, `react-native`, `@expo/vector-icons`, `expo-blur`,
+`expo-glass-effect`, `expo-linear-gradient`, `react-native-svg`,
+`react-native-safe-area-context`, `expo-store-review` (native module, needs a
+dev-client rebuild when added), and `zustand` (>= 5).
+
+## Review ("Rate Us") module
+
+This is a sentiment gate. 4–5★ asks for a store review and 1–3★ opens a feedback
+email. The prompt appears at milestone counts of a happy-moment event the app
+chooses. Each app configures it once:
+
+```ts
+// src/utils/storeLinks.ts — the ONE place the App Store id lives
+export const STORE_TARGET: StoreTarget = { iosAppId: '6759951153', androidPackage: 'com.klyftig.kaelo' };
+
+// src/features/review/review.ts
+export const review = createReviewPrompt({
+  ...STORE_TARGET,
+  appName: 'Kaelo',
+  supportEmail: 'support@klyftig.co',
+  storageKey: 'review.prompt.v1',   // keep stable once shipped
+  storage: AsyncStorage,
+  defaultMilestones: [3, 6],        // optional, this is the default
+  haptics,                          // optional { selection() }
+});
+```
+
+Then:
+
+- **Count** the happy moment with `review.recordEvent(reason?)`. For a once-ever
+  trigger (e.g. "2nd habit created"), use `review.recordOneTimeTrigger(id, reason?)`.
+  Both are async, hydrate first, and never throw.
+- **Mount** the modal once, globally:
+  `<RateAppModal review={review} strings={reviewStringsFromT(t)} />`. Without
+  `strings` it shows English defaults built from `appName`. `strings.thankYou`
+  may be a `(reason) => string` function.
+- **Surface** the prompt by calling `review.showIfPending()` from a screen where
+  a modal is safe (not over a sheet, a tour, the camera or a recording).
+- **Remote config** goes through `review.configure({ enabled, milestones })`.
+  Invalid or missing fields keep the current value.
+- **Tests** reset state with `review.resetForTests()`. Set
+  `review.useStore.setState({ visible: true })` to render the modal.
+
+Store behaviour (`requestStoreReview`):
+
+| Platform | Condition | Action |
+|---|---|---|
+| iOS | numeric `iosAppId` | `itms-apps://apps.apple.com/app/id<id>?action=write-review` (native prompt if it can't open) |
+| iOS | unset / placeholder / any non-numeric id | `StoreReview.requestReview()` after `isAvailableAsync()`. No URL is ever opened |
+| Android | always | Play In-App Review, then `market://details?id=…`, then `https://play.google.com/store/apps/details?id=…` |
+
+`openStoreListing(target, androidUrl?)` opens the listing (e.g. on a
+force-update screen). On iOS without a numeric id it opens nothing and resolves
+`false`.
+
+## Development
+
+```bash
+npm test            # jest (jest-expo); tests live next to the source, excluded from the tarball
+npm run sync        # rsync src/ into Kaelo's node_modules for a quick dev loop (not a release)
+npm pack            # build the tarball; install it into an app with `npm i --no-save <tgz>` to verify
+```
+
+Release: bump `version` and add a `CHANGELOG.md` entry, commit, run
+`npm publish` (public), then bump `@klyftig/mobile-ui` in each app and run
+`npm install`.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@klyftig/mobile-ui",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "scripts": {
+    "test": "jest",
     "sync": "bash scripts/sync-to-kaelo.sh",
     "pack-install": "npm pack && mv klyftig-mobile-ui-*.tgz /tmp/klyftig-mobile-ui-local.tgz && cd ../kaelo/mobile && npm install /tmp/klyftig-mobile-ui-local.tgz"
   },
@@ -9,7 +10,9 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "files": [
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
   ],
   "keywords": [
     "react-native",
@@ -19,22 +22,43 @@
   ],
   "license": "MIT",
   "peerDependencies": {
+    "@expo/vector-icons": "*",
     "expo": "*",
-    "react": ">=19.0.0",
-    "react-native": ">=0.83.0",
+    "expo-blur": "*",
     "expo-glass-effect": "*",
     "expo-linear-gradient": "*",
-    "expo-blur": "*",
-    "@expo/vector-icons": "*",
+    "expo-store-review": "*",
+    "react": ">=19.0.0",
+    "react-native": ">=0.83.0",
+    "react-native-safe-area-context": "*",
     "react-native-svg": "*",
-    "react-native-safe-area-context": "*"
+    "zustand": ">=5.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^29.5.14",
+    "@types/react": "~19.2.0",
     "expo": "~55.0.11",
+    "expo-store-review": "~55.0.14",
+    "jest": "^29.7.0",
+    "jest-expo": "~55.0.14",
     "react": "19.2.0",
-    "react-native": "0.83.4"
+    "react-native": "0.83.4",
+    "react-test-renderer": "^19.2.0",
+    "typescript": "^6.0.3",
+    "zustand": "^5.0.15"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "testMatch": [
+      "**/*.test.ts",
+      "**/*.test.tsx"
+    ],
+    "transformIgnorePatterns": [
+      "node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|react-native-svg|zustand)"
+    ]
   }
 }

package/src/components/WheelPicker.tsx

@@ -13,12 +13,23 @@ import { colors } from '../theme/colors';
 export interface WheelPickerProps {
   values: number[];
   selected: number;
-  onChange: (value: number) => void;
+  /**
+   * `wraps` (only with `loop`): how many times this scroll went past the end
+   * of the list — +1 for 59 → 00 going down, -1 for 00 → 59 going up. A
+   * caller can carry it, e.g. bump the hour when the minutes wrap.
+   */
+  onChange: (value: number, info: { wraps: number }) => void;
   formatLabel?: (value: number) => string;
   itemHeight?: number;
   visibleCount?: number;
   width?: number;
   flex?: number;
+  /**
+   * Wrap around (59 → 00 → 01, and back from 00 to 59), like a clock. The
+   * values are laid out LOOP_COPIES times and the wheel recentres on the
+   * middle copy after every scroll, so it never reaches an end in practice.
+   */
+  loop?: boolean;
 }
 
 const DEFAULT_ITEM_HEIGHT = 48;
@@ -32,6 +43,9 @@ const DEFAULT_VISIBLE_COUNT = 3;
 // and momentum behave normally, but we don't mount 600 <Text> nodes on first
 // paint of MeasurementsStep.
 const WINDOW_OVERSCAN = 8;
+// Odd, so there is a middle copy to start in and snap back to. 21 copies of
+// 60 minutes is 1260 rows — only the overscan window is mounted.
+const LOOP_COPIES = 21;
 
 export function WheelPicker({
   values,
@@ -42,6 +56,7 @@ export function WheelPicker({
   visibleCount = DEFAULT_VISIBLE_COUNT,
   width,
   flex,
+  loop = false,
 }: WheelPickerProps) {
   const { colors } = useTheme();
   const scrollRef = useRef<ScrollView>(null);
@@ -49,10 +64,18 @@ export function WheelPicker({
   const padding = (containerHeight - itemHeight) / 2;
   const lastIndexRef = useRef<number>(-1);
 
-  const selectedIndex = useMemo(() => {
+  // Rows are virtual indices; with `loop` they span LOOP_COPIES copies of
+  // `values` and row i shows values[i mod n].
+  const n = values.length;
+  const rowCount = loop ? n * LOOP_COPIES : n;
+  const middleStart = loop ? Math.floor(LOOP_COPIES / 2) * n : 0;
+  const valueIndexOf = useCallback((row: number) => ((row % n) + n) % n, [n]);
+
+  const valueIndex = useMemo(() => {
     const idx = values.indexOf(selected);
     return idx >= 0 ? idx : 0;
   }, [values, selected]);
+  const selectedIndex = middleStart + valueIndex;
 
   // Track the row currently centered under the selection overlay during scroll
   // so the rendered window follows the user's drag, not just the committed
@@ -73,38 +96,49 @@ export function WheelPicker({
     (e: NativeSyntheticEvent<NativeScrollEvent>) => {
       const offsetY = e.nativeEvent.contentOffset.y;
       const index = Math.round(offsetY / itemHeight);
-      const clamped = Math.max(0, Math.min(values.length - 1, index));
+      const clamped = Math.max(0, Math.min(rowCount - 1, index));
       setWindowCenter((prev) => (Math.abs(prev - clamped) >= 2 ? clamped : prev));
     },
-    [itemHeight, values.length],
+    [itemHeight, rowCount],
   );
 
   const handleMomentumEnd = useCallback(
     (e: NativeSyntheticEvent<NativeScrollEvent>) => {
       const offsetY = e.nativeEvent.contentOffset.y;
       const index = Math.round(offsetY / itemHeight);
-      const clamped = Math.max(0, Math.min(values.length - 1, index));
-      setWindowCenter(clamped);
-      if (values[clamped] !== selected) {
-        onChange(values[clamped]);
+      const clamped = Math.max(0, Math.min(rowCount - 1, index));
+      const value = values[valueIndexOf(clamped)];
+      // Every scroll starts in the middle copy, so copies crossed = wraps.
+      const wraps = loop ? Math.floor(clamped / n) - Math.floor(LOOP_COPIES / 2) : 0;
+      let row = clamped;
+      if (loop) {
+        // Jump back to the same value in the middle copy (invisible: the rows
+        // look identical) so the next fling has room either way.
+        row = middleStart + valueIndexOf(clamped);
+        if (row !== clamped) scrollRef.current?.scrollTo({ y: row * itemHeight, animated: false });
+        lastIndexRef.current = row;
+      }
+      setWindowCenter(row);
+      if (value !== selected || wraps !== 0) {
+        onChange(value, { wraps });
       }
     },
-    [itemHeight, values, selected, onChange],
+    [itemHeight, n, rowCount, values, valueIndexOf, loop, middleStart, selected, onChange],
   );
 
   const windowStart = Math.max(0, windowCenter - WINDOW_OVERSCAN);
-  const windowEnd = Math.min(values.length - 1, windowCenter + WINDOW_OVERSCAN);
+  const windowEnd = Math.min(rowCount - 1, windowCenter + WINDOW_OVERSCAN);
 
   const dimColor = colors.text.tertiary;
   const activeColor = colors.text.primary;
 
   const items = [];
   for (let i = windowStart; i <= windowEnd; i++) {
-    const value = values[i];
+    const value = values[valueIndexOf(i)];
     const isSelected = i === selectedIndex;
     items.push(
       <View
-        key={value}
+        key={i}
         style={[
           styles.item,
           {
@@ -128,7 +162,7 @@ export function WheelPicker({
     );
   }
 
-  const totalContentHeight = values.length * itemHeight + padding * 2;
+  const totalContentHeight = rowCount * itemHeight + padding * 2;
 
   return (
     <View style={[styles.wrapper, { height: containerHeight, width, flex }]}>

package/src/index.ts

@@ -56,3 +56,6 @@ export { CircularProgress } from './components/progress/CircularProgress';
 export type { CircularProgressMode } from './components/progress/CircularProgress';
 export { CArcProgress } from './components/progress/CArcProgress';
 export { MacroBar } from './components/progress/MacroBar';
+
+// Review (Rate Us)
+export * from './review';

package/src/review/RateAppModal.tsx

@@ -0,0 +1,143 @@
+import React, { useEffect, useState } from 'react';
+import { View, Text, StyleSheet, TouchableOpacity, Linking } from 'react-native';
+import { MaterialCommunityIcons as Icon } from '@expo/vector-icons';
+import { CenterDialog } from '../components/CenterDialog';
+import { colors } from '../theme/colors';
+import type { ReviewPrompt } from './createReviewPrompt';
+import { requestStoreReview } from './storeLinks';
+import { defaultReviewStrings, type RateAppStrings } from './strings';
+
+export interface RateAppModalProps {
+  review: ReviewPrompt;
+  /** Overrides for the default English strings (see `reviewStringsFromT`). */
+  strings?: Partial<RateAppStrings>;
+}
+
+const STARS = [1, 2, 3, 4, 5];
+const STAR_ON = '#F5A623';
+const STAR_OFF = '#C5C5C5';
+
+/** Lowest rating sent to the store; anything below goes to private feedback. */
+export const POSITIVE_RATING_THRESHOLD = 4;
+
+/**
+ * Sentiment gate: 4–5★ → store review (`requestStoreReview`), 1–3★ → feedback
+ * email to the configured support address. Either way the user counts as rated.
+ * Mount once, globally; it shows itself when the review store is visible.
+ */
+export const RateAppModal: React.FC<RateAppModalProps> = ({ review, strings }) => {
+  const visible = review.useStore((s) => s.visible);
+  const reason = review.useStore((s) => s.reason);
+  const [selected, setSelected] = useState(0);
+  const s: RateAppStrings = { ...defaultReviewStrings(review.config.appName), ...strings };
+  const thankYou = typeof s.thankYou === 'function' ? s.thankYou(reason) : s.thankYou;
+
+  // A fresh prompt never shows the stars from a previous one.
+  useEffect(() => {
+    if (visible) setSelected(0);
+  }, [visible]);
+
+  const handleSelect = (rating: number) => {
+    review.config.haptics?.selection?.();
+    setSelected(rating);
+    if (rating >= POSITIVE_RATING_THRESHOLD) {
+      void requestStoreReview(review.config);
+    } else {
+      const subject = encodeURIComponent(s.feedbackSubject);
+      Linking.openURL(`mailto:${review.config.supportEmail}?subject=${subject}`).catch(() => {});
+    }
+    review.markRated();
+  };
+
+  return (
+    <CenterDialog
+      visible={visible}
+      onDismiss={review.dismiss}
+      backdropAccessibilityLabel={s.close}
+      contentStyle={styles.content}
+    >
+      <TouchableOpacity
+        style={styles.closeButton}
+        onPress={review.dismiss}
+        hitSlop={{ top: 12, bottom: 12, left: 12, right: 12 }}
+        accessibilityRole="button"
+        accessibilityLabel={s.close}
+      >
+        <Icon name="close" size={22} color={colors.text.tertiary} />
+      </TouchableOpacity>
+
+      <Text style={styles.thankYou}>{thankYou}</Text>
+      <Text style={styles.title}>{s.title}</Text>
+      <Text style={styles.subtitle}>{s.subtitle}</Text>
+
+      <View style={styles.stars}>
+        {STARS.map((rating) => (
+          <TouchableOpacity
+            key={rating}
+            onPress={() => handleSelect(rating)}
+            hitSlop={{ top: 8, bottom: 8, left: 4, right: 4 }}
+            accessibilityRole="button"
+            accessibilityLabel={s.star(rating)}
+          >
+            <Icon
+              name={rating <= selected ? 'star' : 'star-outline'}
+              size={40}
+              color={rating <= selected ? STAR_ON : STAR_OFF}
+            />
+          </TouchableOpacity>
+        ))}
+      </View>
+
+      <TouchableOpacity style={styles.later} onPress={review.dismiss} accessibilityRole="button">
+        <Text style={styles.laterText}>{s.later}</Text>
+      </TouchableOpacity>
+    </CenterDialog>
+  );
+};
+
+const styles = StyleSheet.create({
+  content: {
+    alignItems: 'center',
+  },
+  closeButton: {
+    position: 'absolute',
+    top: 14,
+    right: 14,
+  },
+  thankYou: {
+    fontSize: 13,
+    fontWeight: '600',
+    color: colors.accent.warning,
+    textAlign: 'center',
+    marginTop: 8,
+  },
+  title: {
+    fontSize: 19,
+    fontWeight: '700',
+    color: colors.text.primary,
+    textAlign: 'center',
+    marginTop: 4,
+  },
+  subtitle: {
+    fontSize: 14,
+    color: colors.text.secondary,
+    textAlign: 'center',
+    marginTop: 8,
+  },
+  stars: {
+    flexDirection: 'row',
+    gap: 6,
+    marginTop: 20,
+    marginBottom: 8,
+  },
+  later: {
+    marginTop: 12,
+    paddingVertical: 8,
+    paddingHorizontal: 16,
+  },
+  laterText: {
+    fontSize: 14,
+    fontWeight: '600',
+    color: colors.text.tertiary,
+  },
+});

package/src/review/createReviewPrompt.ts

@@ -0,0 +1,221 @@
+import { create, type StoreApi, type UseBoundStore } from 'zustand';
+import type { StoreTarget } from './storeLinks';
+
+/** AsyncStorage-compatible key/value storage (pass `AsyncStorage` itself). */
+export interface ReviewStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+export interface ReviewPromptConfig extends StoreTarget {
+  /** Shown in the default English strings ("How do you like Kaelo?"). */
+  appName: string;
+  /** 1–3★ feedback goes to `mailto:<supportEmail>`. */
+  supportEmail: string;
+  /** Persistence key, e.g. `review.prompt.v1`. Keep it stable once shipped. */
+  storageKey: string;
+  storage: ReviewStorage;
+  /** Event counts that surface the prompt until {@link ReviewPrompt.configure} overrides them. Default {@link DEFAULT_REVIEW_MILESTONES}. */
+  defaultMilestones?: number[];
+  /** Fired on every star tap. */
+  haptics?: { selection?: () => void };
+}
+
+/** Shown at the 3rd happy-moment event; if dismissed, once more at the 6th; then never. */
+export const DEFAULT_REVIEW_MILESTONES: readonly number[] = [3, 6];
+
+/** Reason recorded by {@link ReviewPrompt.recordEvent} when the caller gives none. */
+export const DEFAULT_REVIEW_REASON = 'milestone';
+
+export interface PersistedReviewState {
+  /** Cumulative happy-moment events. */
+  logCount: number;
+  /** Highest milestone already surfaced. */
+  lastMilestoneShown: number;
+  /** Rated (any sentiment) → never prompt again. */
+  rated: boolean;
+  /** One-time triggers ({@link ReviewPrompt.recordOneTimeTrigger}) already surfaced. */
+  triggersShown: string[];
+}
+
+export interface ReviewPromptState extends PersistedReviewState {
+  /** Modal is on screen. */
+  visible: boolean;
+  /** A trigger fired; waiting for {@link ReviewPrompt.showIfPending} at a safe moment. */
+  pending: boolean;
+  /** What surfaced the current prompt — lets the modal pick its thank-you line. */
+  reason: string;
+  /** Remote kill-switch. Not persisted. */
+  enabled: boolean;
+  /** Active milestones. Not persisted. */
+  milestones: number[];
+}
+
+export interface RemoteReviewConfig {
+  enabled?: unknown;
+  milestones?: unknown;
+}
+
+export interface ReviewPrompt {
+  readonly config: ReviewPromptConfig;
+  /** Zustand hook + `getState`/`setState`/`subscribe`. */
+  readonly useStore: UseBoundStore<StoreApi<ReviewPromptState>>;
+  /** Load persisted counters. Idempotent: every caller awaits the same load. */
+  hydrate(): Promise<void>;
+  /** Apply remote overrides (fail-open: missing/invalid fields keep the current value). */
+  configure(remote: RemoteReviewConfig): void;
+  /** Count one happy-moment event; at a not-yet-shown milestone the prompt goes pending. */
+  recordEvent(reason?: string): Promise<void>;
+  /** Mark the prompt pending for `triggerId`, once ever per trigger (e.g. "2nd habit created"). */
+  recordOneTimeTrigger(triggerId: string, reason?: string): Promise<void>;
+  /** Promote a pending prompt to visible. Call from a screen where a modal is safe. */
+  showIfPending(): void;
+  /** User finished the flow (any rating). Never prompt again. */
+  markRated(): void;
+  /** User closed without rating. Eligible again at the next milestone only. */
+  dismiss(): void;
+  /** Test-only: back to defaults and forget hydration. */
+  resetForTests(): void;
+}
+
+/** Positive, ascending, unique integers; null when nothing valid remains. */
+export function sanitizeMilestones(input: unknown): number[] | null {
+  if (!Array.isArray(input)) return null;
+  const clean = [
+    ...new Set(
+      input
+        .filter((m): m is number => typeof m === 'number' && Number.isFinite(m) && m >= 1)
+        .map((m) => Math.floor(m))
+    ),
+  ].sort((a, b) => a - b);
+  return clean.length > 0 ? clean : null;
+}
+
+const PERSISTED_DEFAULTS: PersistedReviewState = {
+  logCount: 0,
+  lastMilestoneShown: 0,
+  rated: false,
+  triggersShown: [],
+};
+
+function parsePersisted(raw: string): PersistedReviewState {
+  const parsed: unknown = JSON.parse(raw);
+  if (typeof parsed !== 'object' || parsed === null) return PERSISTED_DEFAULTS;
+  const p = parsed as Record<string, unknown>;
+  const count = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0);
+  return {
+    logCount: count(p.logCount),
+    lastMilestoneShown: count(p.lastMilestoneShown),
+    rated: p.rated === true,
+    triggersShown: Array.isArray(p.triggersShown)
+      ? p.triggersShown.filter((t): t is string => typeof t === 'string')
+      : [],
+  };
+}
+
+/**
+ * Create an app's review-prompt store. Call once per app (module scope) and
+ * share the returned object; render `<RateAppModal review={…} />` with it.
+ */
+export function createReviewPrompt(config: ReviewPromptConfig): ReviewPrompt {
+  const baseMilestones = sanitizeMilestones(config.defaultMilestones) ?? [...DEFAULT_REVIEW_MILESTONES];
+  const initialState = (): ReviewPromptState => ({
+    ...PERSISTED_DEFAULTS,
+    triggersShown: [],
+    visible: false,
+    pending: false,
+    reason: DEFAULT_REVIEW_REASON,
+    enabled: true,
+    milestones: baseMilestones,
+  });
+
+  const useStore = create<ReviewPromptState>(initialState);
+  let hydration: Promise<void> | null = null;
+
+  async function load(): Promise<void> {
+    try {
+      const raw = await config.storage.getItem(config.storageKey);
+      if (raw) useStore.setState(parsePersisted(raw));
+    } catch {
+      // Unreadable or corrupt — keep defaults.
+    }
+  }
+
+  function persist(): void {
+    const { logCount, lastMilestoneShown, rated, triggersShown } = useStore.getState();
+    const snapshot: PersistedReviewState = { logCount, lastMilestoneShown, rated, triggersShown };
+    try {
+      config.storage.setItem(config.storageKey, JSON.stringify(snapshot)).catch(() => {});
+    } catch {
+      // Synchronous storage failure — the counters live on in memory.
+    }
+  }
+
+  const hydrate = (): Promise<void> => {
+    if (!hydration) hydration = load();
+    return hydration;
+  };
+
+  return {
+    config,
+    useStore,
+    hydrate,
+
+    configure(remote) {
+      const next: Partial<ReviewPromptState> = {};
+      if (typeof remote.enabled === 'boolean') next.enabled = remote.enabled;
+      const milestones = sanitizeMilestones(remote.milestones);
+      if (milestones) next.milestones = milestones;
+      if (Object.keys(next).length > 0) useStore.setState(next);
+    },
+
+    // Hydrates first: a cold launch can record an event before anything else
+    // loaded the counters, and persisting in-memory defaults then would erase
+    // a stored "rated".
+    async recordEvent(reason = DEFAULT_REVIEW_REASON) {
+      await hydrate();
+      const state = useStore.getState();
+      const logCount = state.logCount + 1;
+      const next: Partial<ReviewPromptState> = { logCount };
+      if (state.enabled && !state.rated) {
+        const reached = state.milestones.filter((m) => logCount >= m && m > state.lastMilestoneShown);
+        if (reached.length > 0) {
+          next.lastMilestoneShown = Math.max(...reached);
+          next.pending = true;
+          next.reason = reason;
+        }
+      }
+      useStore.setState(next);
+      persist();
+    },
+
+    async recordOneTimeTrigger(triggerId, reason = triggerId) {
+      await hydrate();
+      const state = useStore.getState();
+      if (!state.enabled || state.rated || state.triggersShown.includes(triggerId)) return;
+      useStore.setState({ triggersShown: [...state.triggersShown, triggerId], pending: true, reason });
+      persist();
+    },
+
+    showIfPending() {
+      const { pending, visible, rated, enabled } = useStore.getState();
+      if (pending && !visible && !rated && enabled) {
+        useStore.setState({ visible: true, pending: false });
+      }
+    },
+
+    markRated() {
+      useStore.setState({ rated: true, visible: false, pending: false });
+      persist();
+    },
+
+    dismiss() {
+      useStore.setState({ visible: false, pending: false });
+    },
+
+    resetForTests() {
+      hydration = null;
+      useStore.setState(initialState(), true);
+    },
+  };
+}

package/src/review/index.ts

@@ -0,0 +1,25 @@
+export {
+  createReviewPrompt,
+  sanitizeMilestones,
+  DEFAULT_REVIEW_MILESTONES,
+  DEFAULT_REVIEW_REASON,
+} from './createReviewPrompt';
+export type {
+  ReviewPrompt,
+  ReviewPromptConfig,
+  ReviewPromptState,
+  PersistedReviewState,
+  RemoteReviewConfig,
+  ReviewStorage,
+} from './createReviewPrompt';
+export {
+  isValidIosAppId,
+  getStoreUrls,
+  requestStoreReview,
+  openStoreListing,
+} from './storeLinks';
+export type { StoreTarget, StoreUrls, StoreReviewOutcome } from './storeLinks';
+export { RateAppModal, POSITIVE_RATING_THRESHOLD } from './RateAppModal';
+export type { RateAppModalProps } from './RateAppModal';
+export { defaultReviewStrings, reviewStringsFromT } from './strings';
+export type { RateAppStrings, ReviewTranslate } from './strings';

package/src/review/storeLinks.ts

@@ -0,0 +1,122 @@
+import { Linking, Platform } from 'react-native';
+import * as StoreReview from 'expo-store-review';
+
+/** Where an app lives in the stores. One per app, defined once in its review config. */
+export interface StoreTarget {
+  /**
+   * Numeric App Store id (App Store Connect → App Information → Apple ID).
+   * Anything non-numeric — unset, empty, or a `SET_…` placeholder — is treated
+   * as "no id": no App Store URL is ever built from it.
+   */
+  iosAppId?: string | null;
+  /** Android applicationId, e.g. `com.klyftig.kaelo`. */
+  androidPackage: string;
+}
+
+export interface StoreUrls {
+  /** `itms-apps://` listing, or null when no valid iOS id is configured. */
+  iosListing: string | null;
+  /** `itms-apps://…?action=write-review`, or null when no valid iOS id is configured. */
+  iosWriteReview: string | null;
+  /** `market://` deep link into the Play Store app. */
+  androidMarket: string;
+  /** https Play listing — works without the Play Store app installed. */
+  androidWeb: string;
+}
+
+/** How a {@link requestStoreReview} call was satisfied. */
+export type StoreReviewOutcome =
+  /** iOS: opened the App Store's write-review sheet via the numeric id. */
+  | 'ios-write-review'
+  /** `expo-store-review` `requestReview()` (SKStoreReviewController / Play In-App Review). */
+  | 'native-prompt'
+  /** Android: opened the Play Store app via `market://`. */
+  | 'android-market'
+  /** Android: opened the https Play listing. */
+  | 'android-web'
+  /** Nothing could be opened (simulator, no store, every fallback failed). */
+  | 'unavailable';
+
+const IOS_APP_ID_PATTERN = /^[0-9]+$/;
+
+/** True only for a purely numeric App Store id; placeholders such as `SET_NAGGER_IOS_APP_ID` are rejected. */
+export function isValidIosAppId(id: string | null | undefined): id is string {
+  return typeof id === 'string' && IOS_APP_ID_PATTERN.test(id);
+}
+
+// itms-apps:// opens the App Store app directly. https://apps.apple.com/ is a
+// universal link that React Native's Linking rejects, because the calling app
+// is not associated with that domain.
+export function getStoreUrls(target: StoreTarget): StoreUrls {
+  const iosId = isValidIosAppId(target.iosAppId) ? target.iosAppId : null;
+  return {
+    iosListing: iosId ? `itms-apps://apps.apple.com/app/id${iosId}` : null,
+    iosWriteReview: iosId ? `itms-apps://apps.apple.com/app/id${iosId}?action=write-review` : null,
+    androidMarket: `market://details?id=${target.androidPackage}`,
+    androidWeb: `https://play.google.com/store/apps/details?id=${target.androidPackage}`,
+  };
+}
+
+async function tryOpen(url: string): Promise<boolean> {
+  try {
+    await Linking.openURL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function tryNativePrompt(): Promise<boolean> {
+  try {
+    if (!(await StoreReview.isAvailableAsync())) return false;
+    await StoreReview.requestReview();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function openAndroidStore(urls: StoreUrls): Promise<StoreReviewOutcome> {
+  // market:// fails on devices without the Play Store app; https always has a handler.
+  if (await tryOpen(urls.androidMarket)) return 'android-market';
+  if (await tryOpen(urls.androidWeb)) return 'android-web';
+  return 'unavailable';
+}
+
+/**
+ * Ask the user for a store review — the positive branch of the sentiment gate.
+ *
+ * - iOS with a numeric id → App Store write-review deep link (native prompt if
+ *   the URL cannot be opened).
+ * - iOS without one → `requestReview()` after `isAvailableAsync()`. A URL is
+ *   never built from a placeholder id.
+ * - Android → Play In-App Review via `requestReview()`, falling back to
+ *   `market://`, then the https listing.
+ *
+ * Never throws.
+ */
+export async function requestStoreReview(target: StoreTarget): Promise<StoreReviewOutcome> {
+  const urls = getStoreUrls(target);
+  if (Platform.OS === 'ios') {
+    if (urls.iosWriteReview && (await tryOpen(urls.iosWriteReview))) return 'ios-write-review';
+    return (await tryNativePrompt()) ? 'native-prompt' : 'unavailable';
+  }
+  if (await tryNativePrompt()) return 'native-prompt';
+  return openAndroidStore(urls);
+}
+
+/**
+ * Open the app's store listing (e.g. a force-update screen).
+ *
+ * iOS needs a numeric id — without one this resolves false and opens nothing.
+ * Android opens `androidUrl` when given (e.g. a backend-supplied listing),
+ * else `market://` with the https listing as fallback. Never throws.
+ */
+export async function openStoreListing(target: StoreTarget, androidUrl?: string | null): Promise<boolean> {
+  const urls = getStoreUrls(target);
+  if (Platform.OS === 'ios') {
+    return urls.iosListing ? tryOpen(urls.iosListing) : false;
+  }
+  if (androidUrl && (await tryOpen(androidUrl))) return true;
+  return (await openAndroidStore(urls)) !== 'unavailable';
+}

package/src/review/strings.ts

@@ -0,0 +1,47 @@
+/** Every user-visible string in {@link RateAppModal}. */
+export interface RateAppStrings {
+  /** Small line above the title; a function picks a line per prompt reason. */
+  thankYou: string | ((reason: string) => string);
+  title: string;
+  subtitle: string;
+  later: string;
+  /** Accessibility label of the close button and the backdrop. */
+  close: string;
+  /** Accessibility label of each star. */
+  star: (stars: number) => string;
+  /** Subject of the 1–3★ feedback email. */
+  feedbackSubject: string;
+}
+
+/** English fallbacks for apps without translations. */
+export function defaultReviewStrings(appName: string): RateAppStrings {
+  return {
+    thankYou: `Thank you for using ${appName}!`,
+    title: `How do you like ${appName}?`,
+    subtitle: 'Tap a star to rate your experience.',
+    later: 'Maybe later',
+    close: 'Close',
+    star: (stars) => `Rate ${stars} stars`,
+    feedbackSubject: `${appName} feedback`,
+  };
+}
+
+/** Minimal translate signature — an i18next `t` bound to the review namespace fits. */
+export type ReviewTranslate = (key: string, options?: { stars: number }) => string;
+
+/**
+ * Build strings from a translate function using the shared Klyftig `review`
+ * namespace keys: `thankYou`, `title`, `subtitle`, `later`, `a11yClose`,
+ * `a11yStar` (`{{stars}}`), `feedbackSubject`.
+ */
+export function reviewStringsFromT(t: ReviewTranslate): RateAppStrings {
+  return {
+    thankYou: t('thankYou'),
+    title: t('title'),
+    subtitle: t('subtitle'),
+    later: t('later'),
+    close: t('a11yClose'),
+    star: (stars) => t('a11yStar', { stars }),
+    feedbackSubject: t('feedbackSubject'),
+  };
+}