@variantlab/react 0.1.1 → 0.1.3

package/README.md

@@ -13,50 +13,92 @@ npm install @variantlab/core@alpha @variantlab/react@alpha
 
 **Peer dependencies:** `react ^18.2.0 || ^19.0.0`
 
-## Quick start
+---
+
+## Complete example
+
+### `experiments.json`
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "hero-layout",
+      "name": "Hero section layout",
+      "type": "render",
+      "default": "centered",
+      "variants": [
+        { "id": "centered" },
+        { "id": "split" }
+      ]
+    },
+    {
+      "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": "pricing",
+      "name": "Pricing tier",
+      "type": "value",
+      "default": "low",
+      "assignment": { "strategy": "sticky-hash" },
+      "variants": [
+        { "id": "low", "value": 9.99, "weight": 50 },
+        { "id": "high", "value": 14.99, "weight": 50 }
+      ]
+    }
+  ]
+}
+```
 
-### 1. Create the engine and wrap your app
+### `App.tsx`
 
 ```tsx
 import { createEngine } from "@variantlab/core";
 import { VariantLabProvider } from "@variantlab/react";
 import experiments from "./experiments.json";
 
-const engine = createEngine(experiments);
+const engine = createEngine(experiments, {
+  context: {
+    userId: "user-123",
+    platform: "web",
+    locale: "en",
+  },
+});
 
 export default function App() {
   return (
     <VariantLabProvider engine={engine}>
-      <YourApp />
+      <HomePage />
     </VariantLabProvider>
   );
 }
 ```
 
-### 2. Use hooks
+### `HomePage.tsx`
 
 ```tsx
-import { useVariant, useVariantValue } from "@variantlab/react";
-
-function HeroSection() {
-  // Get the assigned variant ID
-  const variant = useVariant("hero-layout"); // "centered" | "split"
-
-  return variant === "split" ? <SplitHero /> : <CenteredHero />;
-}
+import { useVariant, useVariantValue, Variant, VariantErrorBoundary } from "@variantlab/react";
 
-function CheckoutButton() {
-  // Get a value experiment's value directly
-  const copy = useVariantValue<string>("cta-copy"); // "Buy now" | "Get started"
-
-  return <button>{copy}</button>;
+function HomePage() {
+  return (
+    <main>
+      <VariantErrorBoundary experimentId="hero-layout" fallback={<p>Error loading hero</p>}>
+        <HeroSection />
+      </VariantErrorBoundary>
+      <CheckoutButton />
+      <PricingDisplay />
+    </main>
+  );
 }
-```
-
-### 3. Or use components
-
-```tsx
-import { Variant, VariantValue } from "@variantlab/react";
 
 function HeroSection() {
   return (
@@ -70,105 +112,229 @@ function HeroSection() {
 }
 
 function CheckoutButton() {
-  return (
-    <VariantValue experimentId="cta-copy">
-      {(value) => <button>{value}</button>}
-    </VariantValue>
-  );
+  const copy = useVariantValue<string>("cta-copy");
+  return <button>{copy}</button>;
+}
+
+function PricingDisplay() {
+  const price = useVariantValue<number>("pricing");
+  return <span>${price}/month</span>;
 }
 ```
 
-## Hooks API
+---
+
+## Hooks
 
-### `useVariant(experimentId)`
+### `useVariant(experimentId)` — get the active variant ID
 
-Returns the assigned variant ID for a render experiment.
+Use this for **render experiments** where you switch between different components or layouts.
 
 ```tsx
-const variantId = useVariant("hero-layout"); // "centered" | "split"
+import { useVariant } from "@variantlab/react";
+
+function HeroSection() {
+  const layout = useVariant("hero-layout");
+  // Returns: "centered" | "split"
+
+  if (layout === "split") {
+    return <SplitHero />;
+  }
+  return <CenteredHero />;
+}
 ```
 
-### `useVariantValue<T>(experimentId)`
+### `useVariantValue<T>(experimentId)` — get the experiment value
 
-Returns the value of a value experiment.
+Use this for **value experiments** where variants carry data (strings, numbers, booleans, objects).
 
 ```tsx
-const copy = useVariantValue<string>("cta-copy"); // "Buy now"
-const price = useVariantValue<number>("pricing"); // 9.99
+import { useVariantValue } from "@variantlab/react";
+
+function CheckoutButton() {
+  const buttonText = useVariantValue<string>("cta-copy");
+  // Returns: "Buy now" | "Get started" | "Try it free"
+  return <button>{buttonText}</button>;
+}
+
+function PricingDisplay() {
+  const price = useVariantValue<number>("pricing");
+  // Returns: 9.99 | 14.99
+  return <span>${price}/month</span>;
+}
 ```
 
-### `useExperiment(experimentId)`
+### `useExperiment(experimentId)` — get full experiment state
 
-Returns the full experiment state including metadata.
+Returns the variant ID, experiment config, and whether it's been manually overridden. Useful for debug UIs or analytics.
 
 ```tsx
-const { variantId, experiment, isOverridden } = useExperiment("hero-layout");
+import { useExperiment } from "@variantlab/react";
+
+function ExperimentInfo() {
+  const { variantId, experiment, isOverridden } = useExperiment("hero-layout");
+
+  return (
+    <div>
+      <p>Experiment: {experiment.name}</p>
+      <p>Current variant: {variantId}</p>
+      {isOverridden && <p style={{ color: "orange" }}>⚠ Manually overridden</p>}
+    </div>
+  );
+}
 ```
 
-### `useSetVariant()`
+### `useSetVariant()` — override a variant
 
-Returns a function to override variant assignments (useful for debug UIs).
+Returns a function to force-assign a variant. Useful for building debug UIs, admin panels, or testing during development.
 
 ```tsx
-const setVariant = useSetVariant();
-setVariant("hero-layout", "split"); // force split variant
+import { useSetVariant, useVariant } from "@variantlab/react";
+
+function VariantPicker() {
+  const setVariant = useSetVariant();
+  const current = useVariant("hero-layout");
+
+  return (
+    <div>
+      <p>Current: {current}</p>
+      <button onClick={() => setVariant("hero-layout", "centered")}>Centered</button>
+      <button onClick={() => setVariant("hero-layout", "split")}>Split</button>
+    </div>
+  );
+}
 ```
 
-### `useVariantLabEngine()`
+### `useVariantLabEngine()` — access the engine directly
 
-Returns the engine instance directly.
+Returns the raw engine instance for advanced operations like resetting all overrides, updating context, or subscribing to changes.
 
 ```tsx
-const engine = useVariantLabEngine();
-engine.resetAll();
+import { useVariantLabEngine } from "@variantlab/react";
+
+function SettingsPanel() {
+  const engine = useVariantLabEngine();
+
+  return (
+    <div>
+      <button onClick={() => engine.resetAll()}>Reset all experiments</button>
+      <button onClick={() => engine.updateContext({ locale: "bn" })}>
+        Switch to Bengali
+      </button>
+    </div>
+  );
+}
 ```
 
-### `useRouteExperiments()`
+### `useRouteExperiments()` — get experiments targeting the current route
 
-Returns experiments that target the current route.
+Returns only experiments whose targeting rules match the current URL path. Useful for showing relevant experiments in a debug panel.
 
 ```tsx
-const experiments = useRouteExperiments();
+import { useRouteExperiments } from "@variantlab/react";
+
+function RouteDebugPanel() {
+  const experiments = useRouteExperiments();
+
+  return (
+    <ul>
+      {experiments.map((exp) => (
+        <li key={exp.id}>{exp.name}: {exp.variantId}</li>
+      ))}
+    </ul>
+  );
+}
 ```
 
+---
+
 ## Components
 
-### `<Variant>`
+### `<Variant>` — render-swap by variant ID
+
+Renders the child matching the active variant. Cleaner than if/switch when you have distinct JSX per variant.
+
+```tsx
+import { Variant } from "@variantlab/react";
+
+function OnboardingPage() {
+  return (
+    <Variant experimentId="onboarding-flow" fallback={<ClassicOnboarding />}>
+      {{
+        classic: <ClassicOnboarding />,
+        "quick-start": <QuickStartOnboarding />,
+        guided: <GuidedOnboarding />,
+      }}
+    </Variant>
+  );
+}
+```
+
+### `<VariantValue>` — render-prop for value experiments
 
-Renders the matching variant child by ID.
+Passes the experiment value to a render function. Useful when you want to keep the value inline.
 
 ```tsx
-<Variant experimentId="hero-layout" fallback={<Default />}>
-  {{
-    centered: <CenteredHero />,
-    split: <SplitHero />,
-  }}
-</Variant>
+import { VariantValue } from "@variantlab/react";
+
+function WelcomeBanner() {
+  return (
+    <VariantValue experimentId="cta-copy">
+      {(value) => <h2>{value}</h2>}
+    </VariantValue>
+  );
+}
 ```
 
-### `<VariantValue>`
+### `<VariantErrorBoundary>` — crash-safe experiments
 
-Render-prop component for value experiments.
+Wraps an experiment in an error boundary. If a variant crashes N times within a time window, the engine automatically rolls back to the default variant.
 
 ```tsx
-<VariantValue experimentId="cta-copy">
-  {(value) => <span>{value}</span>}
-</VariantValue>
+import { VariantErrorBoundary } from "@variantlab/react";
+
+function SafeHeroSection() {
+  return (
+    <VariantErrorBoundary
+      experimentId="hero-layout"
+      fallback={<p>Something went wrong. Showing default layout.</p>}
+    >
+      <HeroSection />
+    </VariantErrorBoundary>
+  );
+}
 ```
 
-### `<VariantErrorBoundary>`
+### `<VariantLabProvider>` — context provider
 
-Error boundary with crash-rollback integration. If a variant crashes N times, the engine auto-reverts to the default variant.
+Wraps your app and provides the engine to all hooks and components. Must be near the top of your component tree.
 
 ```tsx
-<VariantErrorBoundary experimentId="hero-layout" fallback={<ErrorFallback />}>
-  <HeroSection />
-</VariantErrorBoundary>
+import { VariantLabProvider } from "@variantlab/react";
+
+export default function App() {
+  return (
+    <VariantLabProvider engine={engine}>
+      {/* All useVariant/useVariantValue/etc. hooks work inside here */}
+      <Router />
+    </VariantLabProvider>
+  );
+}
 ```
 
+---
+
 ## Type safety with codegen
 
-Run `npx variantlab generate` to generate TypeScript types from your `experiments.json`. Experiment IDs and variant IDs become literal types — typos become compile errors.
+Generate TypeScript types from your config so typos become compile errors:
+
+```bash
+npx @variantlab/cli@alpha generate
+```
+
+After running, `useVariant("hero-layout")` returns `"centered" | "split"` as a literal union type. Passing a non-existent experiment ID like `useVariant("typo")` is a compile error.
+
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variantlab/react",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React hooks and components for variantlab.",
   "license": "MIT",
   "type": "module",
@@ -40,18 +40,18 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/variantlab/variantlab.git",
+    "url": "git+https://github.com/Minhaj-Rabby/variantlab.git",
     "directory": "packages/react"
   },
   "bugs": {
-    "url": "https://github.com/variantlab/variantlab/issues"
+    "url": "https://github.com/Minhaj-Rabby/variantlab/issues"
   },
-  "homepage": "https://github.com/variantlab/variantlab#readme",
+  "homepage": "https://github.com/Minhaj-Rabby/variantlab#readme",
   "engines": {
     "node": ">=18.17"
   },
   "dependencies": {
-    "@variantlab/core": "0.1.1"
+    "@variantlab/core": "0.1.3"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"