@variantlab/react-native 0.1.2 → 0.1.3

package/README.md

@@ -23,96 +23,405 @@ npm install @variantlab/core@alpha @variantlab/react@alpha @variantlab/react-nat
 - `react-native-safe-area-context` — safe area for debug overlay
 - `react-native-svg` — QR code rendering
 
-## Quick start
+---
+
+## Complete example
+
+Here's a full working setup — from config to rendering variants:
+
+### `experiments.json`
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "card-layout",
+      "name": "Card layout experiment",
+      "type": "render",
+      "default": "standard",
+      "variants": [
+        { "id": "standard" },
+        { "id": "compact" },
+        { "id": "pip-thumbnail" }
+      ]
+    },
+    {
+      "id": "cta-copy",
+      "name": "CTA button text",
+      "type": "value",
+      "default": "buy-now",
+      "variants": [
+        { "id": "buy-now", "value": "Buy now" },
+        { "id": "get-started", "value": "Get started" },
+        { "id": "try-free", "value": "Try it free" }
+      ]
+    },
+    {
+      "id": "onboarding-flow",
+      "name": "Onboarding flow",
+      "type": "render",
+      "default": "classic",
+      "assignment": { "strategy": "sticky-hash" },
+      "variants": [
+        { "id": "classic" },
+        { "id": "quick-start" }
+      ]
+    }
+  ]
+}
+```
 
-### 1. Create the engine with auto-context
+### `variantlab.ts` — engine setup
 
-```tsx
+```ts
 import { createEngine } from "@variantlab/core";
 import { getAutoContext, createAsyncStorageAdapter } from "@variantlab/react-native";
 import AsyncStorage from "@react-native-async-storage/async-storage";
 import experiments from "./experiments.json";
 
-const engine = createEngine(experiments, {
-  context: getAutoContext(), // auto-detects platform, screenSize, locale
+export const engine = createEngine(experiments, {
+  context: {
+    ...getAutoContext(), // auto-detects platform, screenSize, locale
+    userId: "user-123", // your authenticated user ID
+  },
   storage: createAsyncStorageAdapter(AsyncStorage),
 });
 ```
 
-### 2. Wrap your app
+### `app/_layout.tsx` — wrap your app
 
 ```tsx
 import { VariantLabProvider } from "@variantlab/react-native";
+import { VariantDebugOverlay } from "@variantlab/react-native/debug";
+import { engine } from "./variantlab";
 
-export default function App() {
+export default function RootLayout() {
   return (
     <VariantLabProvider engine={engine}>
-      <YourApp />
+      <Slot />
+      {__DEV__ && <VariantDebugOverlay />}
     </VariantLabProvider>
   );
 }
 ```
 
-### 3. Use hooks (same API as @variantlab/react)
+---
+
+## Hooks
+
+### `useVariant(experimentId)` — get the active variant ID
+
+Use this for **render experiments** where you switch between different components.
+
+```tsx
+import { View } from "react-native";
+import { useVariant } from "@variantlab/react-native";
+
+function CardSection() {
+  const layout = useVariant("card-layout");
+  // Returns: "standard" | "compact" | "pip-thumbnail"
+
+  switch (layout) {
+    case "compact":
+      return <CompactCard />;
+    case "pip-thumbnail":
+      return <PipThumbnailCard />;
+    default:
+      return <StandardCard />;
+  }
+}
+```
+
+### `useVariantValue<T>(experimentId)` — get the experiment value
+
+Use this for **value experiments** where variants carry data (strings, numbers, objects).
 
 ```tsx
-import { useVariant, useVariantValue, Variant } from "@variantlab/react-native";
+import { Text, TouchableOpacity } from "react-native";
+import { useVariantValue } from "@variantlab/react-native";
+
+function CheckoutButton() {
+  const buttonText = useVariantValue<string>("cta-copy");
+  // Returns: "Buy now" | "Get started" | "Try it free"
+
+  return (
+    <TouchableOpacity style={styles.button}>
+      <Text>{buttonText}</Text>
+    </TouchableOpacity>
+  );
+}
+
+function PricingDisplay() {
+  const price = useVariantValue<number>("pricing-tier");
+  // Returns: 9.99 | 14.99 | 19.99
+
+  return <Text>${price}/month</Text>;
+}
+```
+
+### `useExperiment(experimentId)` — get full experiment state
+
+Returns the variant ID, the experiment config, and whether it's been manually overridden.
+
+```tsx
+import { Text, View } from "react-native";
+import { useExperiment } from "@variantlab/react-native";
+
+function DebugBanner() {
+  const { variantId, experiment, isOverridden } = useExperiment("card-layout");
+
+  return (
+    <View>
+      <Text>Experiment: {experiment.name}</Text>
+      <Text>Active variant: {variantId}</Text>
+      {isOverridden && <Text style={{ color: "orange" }}>⚠ Manually overridden</Text>}
+    </View>
+  );
+}
+```
+
+### `useSetVariant()` — override a variant (for testing/QA)
+
+Returns a function to force-assign a variant. Useful for building your own debug UI or testing different variants during development.
+
+```tsx
+import { Button, View } from "react-native";
+import { useSetVariant, useVariant } from "@variantlab/react-native";
+
+function VariantPicker() {
+  const setVariant = useSetVariant();
+  const current = useVariant("card-layout");
+
+  return (
+    <View>
+      <Text>Current: {current}</Text>
+      <Button title="Standard" onPress={() => setVariant("card-layout", "standard")} />
+      <Button title="Compact" onPress={() => setVariant("card-layout", "compact")} />
+      <Button title="PiP" onPress={() => setVariant("card-layout", "pip-thumbnail")} />
+    </View>
+  );
+}
+```
+
+### `useVariantLabEngine()` — access the engine directly
+
+Returns the engine instance for advanced operations like resetting all overrides or updating context.
+
+```tsx
+import { Button } from "react-native";
+import { useVariantLabEngine } from "@variantlab/react-native";
+
+function ResetButton() {
+  const engine = useVariantLabEngine();
+
+  return (
+    <Button
+      title="Reset all experiments"
+      onPress={() => engine.resetAll()}
+    />
+  );
+}
+
+function ContextUpdater() {
+  const engine = useVariantLabEngine();
+
+  const onLogin = (userId: string) => {
+    engine.updateContext({ userId });
+  };
 
-function CardLayout() {
-  const variant = useVariant("card-layout");
   // ...
 }
+```
+
+### `useRouteExperiments()` — get experiments targeting the current route
+
+Returns only the experiments whose targeting rules match the current route (useful with Expo Router).
+
+```tsx
+import { Text, FlatList } from "react-native";
+import { useRouteExperiments } from "@variantlab/react-native";
+
+function RouteExperimentsList() {
+  const experiments = useRouteExperiments();
+
+  return (
+    <FlatList
+      data={experiments}
+      renderItem={({ item }) => (
+        <Text>{item.name}: {item.variantId}</Text>
+      )}
+    />
+  );
+}
+```
+
+---
+
+## Components
+
+### `<Variant>` — render-swap by variant ID
+
+Renders the child matching the active variant. Cleaner than a switch statement when you have distinct JSX per variant.
+
+```tsx
+import { Variant } from "@variantlab/react-native";
+
+function OnboardingScreen() {
+  return (
+    <Variant experimentId="onboarding-flow" fallback={<ClassicOnboarding />}>
+      {{
+        classic: <ClassicOnboarding />,
+        "quick-start": <QuickStartOnboarding />,
+      }}
+    </Variant>
+  );
+}
+```
+
+### `<VariantValue>` — render-prop for value experiments
+
+Passes the experiment value to a render function.
+
+```tsx
+import { Text } from "react-native";
+import { VariantValue } from "@variantlab/react-native";
+
+function WelcomeBanner() {
+  return (
+    <VariantValue experimentId="welcome-message">
+      {(message) => <Text style={styles.banner}>{message}</Text>}
+    </VariantValue>
+  );
+}
+```
+
+### `<VariantErrorBoundary>` — crash-safe experiments
+
+Wraps an experiment in an error boundary. If a variant crashes repeatedly, the engine auto-rolls back to the default variant and renders the fallback.
+
+```tsx
+import { Text } from "react-native";
+import { VariantErrorBoundary } from "@variantlab/react-native";
 
-function PriceDisplay() {
-  const price = useVariantValue<number>("pricing");
-  return <Text>${price}</Text>;
+function SafeCardSection() {
+  return (
+    <VariantErrorBoundary
+      experimentId="card-layout"
+      fallback={<Text>Something went wrong. Showing default layout.</Text>}
+    >
+      <CardSection />
+    </VariantErrorBoundary>
+  );
 }
 ```
 
+### `<VariantLabProvider>` — context provider
+
+Wraps your app and provides the engine to all hooks and components. Must be at the top of your component tree.
+
+```tsx
+import { VariantLabProvider } from "@variantlab/react-native";
+import { engine } from "./variantlab";
+
+export default function App() {
+  return (
+    <VariantLabProvider engine={engine}>
+      {/* All hooks and components work inside here */}
+      <Navigation />
+    </VariantLabProvider>
+  );
+}
+```
+
+---
+
 ## Auto-context detection
 
-`getAutoContext()` automatically detects:
+`getAutoContext()` reads device info automatically so your targeting rules just work:
 
-| Field | Source |
-|-------|--------|
-| `platform` | `Platform.OS` (`ios`, `android`, `web`) |
-| `screenSize` | `Dimensions.get("window").width` bucketed to `small` / `medium` / `large` |
-| `locale` | `expo-localization` or `NativeModules` |
-| `appVersion` | `expo-constants` or `DeviceInfo` |
+| Field | Source | Example |
+|-------|--------|---------|
+| `platform` | `Platform.OS` | `"ios"`, `"android"`, `"web"` |
+| `screenSize` | `Dimensions.get("window").width` | `"small"` (<375), `"medium"` (375-767), `"large"` (768+) |
+| `locale` | `expo-localization` or `NativeModules` | `"en"`, `"bn"`, `"fr"` |
+| `appVersion` | `expo-constants` or `DeviceInfo` | `"2.1.0"` |
 
 ```tsx
 import { getAutoContext } from "@variantlab/react-native";
 
 const context = getAutoContext();
-// { platform: "ios", screenSize: "medium", locale: "en", ... }
+// { platform: "ios", screenSize: "medium", locale: "en", appVersion: "2.1.0" }
 ```
 
+You can merge it with your own context:
+
+```ts
+const engine = createEngine(experiments, {
+  context: {
+    ...getAutoContext(),
+    userId: "user-123",
+    attributes: { plan: "pro", country: "BD" },
+  },
+});
+```
+
+---
+
 ## Storage adapters
 
-Choose the storage backend that fits your app:
+Persist variant assignments across app restarts. Pick the one that fits your stack:
+
+### AsyncStorage (most common)
 
 ```tsx
+import AsyncStorage from "@react-native-async-storage/async-storage";
 import { createAsyncStorageAdapter } from "@variantlab/react-native";
-import { createMMKVStorageAdapter } from "@variantlab/react-native";
-import { createSecureStoreAdapter } from "@variantlab/react-native";
-import { createMemoryStorage } from "@variantlab/react-native";
 
-// AsyncStorage — most common, works everywhere
 const storage = createAsyncStorageAdapter(AsyncStorage);
+```
+
+### MMKV (fastest — synchronous reads)
 
-// MMKV — faster, synchronous reads
+```tsx
+import { MMKV } from "react-native-mmkv";
+import { createMMKVStorageAdapter } from "@variantlab/react-native";
+
+const mmkv = new MMKV();
 const storage = createMMKVStorageAdapter(mmkv);
+```
+
+### SecureStore (encrypted — for sensitive data)
+
+```tsx
+import * as SecureStore from "expo-secure-store";
+import { createSecureStoreAdapter } from "@variantlab/react-native";
 
-// SecureStore — encrypted, for sensitive experiment data
 const storage = createSecureStoreAdapter(SecureStore);
+```
+
+### Memory (no persistence — for tests)
+
+```tsx
+import { createMemoryStorage } from "@variantlab/react-native";
 
-// Memory — no persistence, resets on restart (good for tests)
 const storage = createMemoryStorage();
 ```
 
+Pass the storage to your engine:
+
+```ts
+const engine = createEngine(experiments, {
+  context: getAutoContext(),
+  storage, // variant assignments persist here
+});
+```
+
+---
+
 ## Debug overlay
 
-A built-in bottom-sheet UI for viewing and overriding experiments on device.
+A floating button that opens a bottom-sheet for viewing and overriding experiments on device. Only use in development.
 
 ```tsx
 import { VariantDebugOverlay } from "@variantlab/react-native/debug";
@@ -127,48 +436,81 @@ export default function App() {
 }
 ```
 
-The overlay shows:
-- All active experiments and current assignments
-- Tap to override any variant
-- Current targeting context
-- Assignment source (default, hash, override, etc.)
+What the overlay shows:
+- All active experiments with their current variant
+- Tap any experiment to switch variants
+- Current targeting context (platform, screenSize, locale, etc.)
+- Assignment source for each experiment (default, sticky-hash, override, etc.)
+- Search/filter experiments
+
+Customize the trigger position:
+
+```tsx
+<VariantDebugOverlay corner="bottom-left" />
+```
+
+---
 
 ## Deep link overrides
 
-Allow QA to force variants via deep links:
+Let your QA team force variants by opening a URL:
 
 ```
-myapp://variantlab?set=hero-layout:split
+myapp://variantlab?set=card-layout:compact
 ```
 
+### Setup
+
 ```tsx
 import { registerDeepLinkHandler } from "@variantlab/react-native";
+import { engine } from "./variantlab";
 
-// In your app setup
+// Call once during app initialization
 registerDeepLinkHandler(engine);
 ```
 
+Now opening `myapp://variantlab?set=card-layout:compact` will force the `card-layout` experiment to the `compact` variant.
+
+---
+
 ## QR sharing
 
-Share experiment state with teammates via QR codes:
+Share your current experiment state with teammates — they scan the QR and get the exact same variants.
 
 ```tsx
 import { buildQrUrl, parseQrUrl } from "@variantlab/react-native/qr";
+import { encodeSharePayload, decodeSharePayload } from "@variantlab/react-native";
 
-// Encode current state into a URL
+// Build a shareable URL from current assignments
+const payload = encodeSharePayload({
+  v: 1,
+  u: "user-123",
+  a: { "card-layout": "compact", "cta-copy": "try-free" },
+});
 const url = buildQrUrl(payload);
+// "variantlab://apply?p=..."
 
-// Parse a scanned QR URL
-const result = parseQrUrl(url);
+// Parse a received QR URL
+const result = parseQrUrl(scannedUrl);
+if (result.ok) {
+  // Apply the assignments to the engine
+  applyPayload(engine, result.payload);
+}
 ```
 
-## All re-exported hooks and components
+---
 
-This package re-exports everything from `@variantlab/react`:
+## Codegen (type safety)
+
+Generate TypeScript types so experiment IDs and variant IDs are checked at compile time:
+
+```bash
+npx @variantlab/cli@alpha generate
+```
 
-**Hooks:** `useVariant`, `useVariantValue`, `useExperiment`, `useSetVariant`, `useVariantLabEngine`, `useRouteExperiments`
+After codegen, `useVariant("card-layout")` returns `"standard" | "compact" | "pip-thumbnail"` as a literal type. Typos become compile errors.
 
-**Components:** `<Variant>`, `<VariantValue>`, `<VariantErrorBoundary>`, `<VariantLabProvider>`
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variantlab/react-native",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "React Native and Expo bindings for variantlab.",
   "license": "MIT",
   "type": "module",
@@ -71,8 +71,8 @@
     "node": ">=18.17"
   },
   "dependencies": {
-    "@variantlab/core": "0.1.2",
-    "@variantlab/react": "0.1.2"
+    "@variantlab/core": "0.1.3",
+    "@variantlab/react": "0.1.3"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "*",