@ops-ai/react-router-toggly 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.2.1] - 2026-09-27
+
+### Fixed
+- Keep `RouterTogglyProvider` hook order stable when route selection changes while retaining loader and fallback context hydration [OPS-1451].
+- Surface invalid React Router context errors to the application's Error Boundary instead of intercepting loader hooks [OPS-1451].
+
+## [1.2.0] - 2026-09-26
+
+### Added
+- Opt-in `enableVariants` on `TogglyConfig`. When set, the browser client fetches
+  `/evaluated-variants-signed` instead of `/evaluated-signed`, and the server
+  client switches from `definitions-signed` local eval to remote variant
+  assignment. Exposes `getVariant` / `getVariantValue` on the provider context
+  and `TogglyServerClient` [OPS-1425].
+- Typed soft-null `getVariantValue<T>(…, isT?)` and exported `decodeVariantValue`
+  matching the JS/Vue SDK contract.
 
 ## [1.1.0] - 2026-09-18
 

package/dist/client.cjs

@@ -2,6 +2,7 @@
 
 var togglyHooksTypes = require('@ops-ai/toggly-hooks-types');
 require('@ops-ai/toggly-eval');
+var togglySignedDefs = require('@ops-ai/toggly-signed-defs');
 var react = require('react');
 var togglyClientTelemetry = require('@ops-ai/toggly-client-telemetry');
 var browser = require('@ops-ai/toggly-client-telemetry/browser');
@@ -52,12 +53,18 @@ function mergeConfig(config) {
   };
 }
 function buildDefinitionsUrl(config, context) {
-  const { baseUrl, appKey, environment, groups, claims, evaluationMode } = mergeConfig(config);
+  const { baseUrl, appKey, environment, groups, claims, evaluationMode, enableVariants } = mergeConfig(config);
   if (!appKey) {
     throw new Error("appKey is required");
   }
   const mode = evaluationMode ?? "remote";
-  const pathSegment = mode === "local" ? "definitions-signed" : "evaluated-signed";
+  const useVariants = mode !== "local" && enableVariants === true;
+  let pathSegment = "evaluated-signed";
+  if (mode === "local") {
+    pathSegment = "definitions-signed";
+  } else if (useVariants) {
+    pathSegment = "evaluated-variants-signed";
+  }
   const url = new URL(`${baseUrl}/${pathSegment}/${appKey}/${environment}`);
   if (mode === "local") {
     return url.toString();
@@ -70,10 +77,25 @@ function buildDefinitionsUrl(config, context) {
       groups: fromParam?.groups ?? groups,
       claims: fromParam?.claims ?? claims
     },
-    "evaluated"
+    useVariants ? "variants" : "evaluated"
   );
   return url.toString();
 }
+function parseVariantDefsPayload(parsed) {
+  return togglySignedDefs.asVariantDefsRecord(togglySignedDefs.unwrapDefsPayload(parsed));
+}
+function variantDefsToFlags(defs) {
+  const out = {};
+  for (const key of Object.keys(defs)) {
+    out[key] = defs[key]?.enabled === true;
+  }
+  return out;
+}
+function decodeVariantValue(value, isT) {
+  if (value === null || value === void 0) return null;
+  if (isT) return isT(value) ? value : null;
+  return value;
+}
 function isFeatureEnabled(flags, featureKey, defaultValue = false, entityContext) {
   if (!flags || Object.keys(flags).length === 0) {
     return defaultValue;
@@ -138,6 +160,12 @@ var HEADERS = {
   CACHE_CONTROL: "cache-control"
 };
 var TOGGLY_LOADER_KEY = "__toggly";
+function checkVariantLabel(result) {
+  if (typeof result === "string") {
+    return result;
+  }
+  return result ? "enabled" : "disabled";
+}
 function createBrowserTelemetry(config) {
   const enabled = globalThis.window !== void 0 && typeof document !== "undefined" && !!config.appKey?.trim() && config.enableTelemetry !== false;
   const usage = enabled && config.enableUsageTracking !== false;
@@ -266,13 +294,13 @@ function createBrowserTelemetry(config) {
       };
       if (active) {
         const record = getReporter().captureCheck();
-        return (key, result) => record(key, result ? "enabled" : "disabled");
+        return (key, result) => record(key, checkVariantLabel(result));
       }
       const attribution = context;
       const capturedPartition = partition;
-      return (key, result) => feature(key, result ? "enabled" : "disabled", 0, attribution, capturedPartition);
+      return (key, result) => feature(key, checkVariantLabel(result), 0, attribution, capturedPartition);
     },
-    recordCheck: (key, result) => feature(key, result ? "enabled" : "disabled", 0),
+    recordCheck: (key, result) => feature(key, checkVariantLabel(result), 0),
     activate() {
       if (disposed || active) return;
       active = true;
@@ -292,7 +320,7 @@ function createBrowserTelemetry(config) {
 
 // src/client/sdk-identity.ts
 var SDK_ID = "react-router";
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.2.1";
 function appendSdkQueryParams(params) {
   params.set("sdk", SDK_ID);
   params.set("sdkVersion", SDK_VERSION);
@@ -346,6 +374,7 @@ function TogglyProviderOwner({
     claims: { ...mergedConfig?.claims }
   });
   const flagsRef = react.useRef(serverContext?.flags ?? mergedConfig?.featureDefaults ?? {});
+  const variantsRef = react.useRef(null);
   const generationRef = react.useRef(0);
   const updateRevisionRef = react.useRef(0);
   const [telemetry] = react.useState(() => createBrowserTelemetry({ ...config, ...contextRef.current }));
@@ -483,6 +512,14 @@ function TogglyProviderOwner({
           throw new Error(`HTTP ${response.status}: ${response.statusText}`);
         }
         const payload = await response.json();
+        if (mergedConfig.enableVariants === true) {
+          const defs = parseVariantDefsPayload(payload);
+          variantsRef.current = defs;
+          const newFlags2 = variantDefsToFlags(defs);
+          logger.debug(`Fetched ${Object.keys(newFlags2).length} flags (variants).`);
+          return newFlags2;
+        }
+        variantsRef.current = null;
         const newFlags = payload && typeof payload === "object" ? payload : {};
         logger.debug(`Fetched ${Object.keys(newFlags).length} flags.`);
         return newFlags;
@@ -542,10 +579,34 @@ function TogglyProviderOwner({
     },
     [captureEvaluation]
   );
+  const getVariant = react.useCallback(
+    (featureKey) => {
+      if (!mergedConfig?.enableVariants) return null;
+      const entry = variantsRef.current?.[featureKey];
+      const enabled = togglyLocalGates.applyLocalGate(
+        entry?.enabled === true,
+        featureKey,
+        localGatesRef.current,
+        localGateIndexRef.current
+      );
+      const record = telemetry.captureCheck();
+      record(featureKey, enabled && entry?.variant ? entry.variant : "disabled");
+      if (!enabled || !entry?.variant) return null;
+      return { name: entry.variant, configurationValue: entry.configurationValue };
+    },
+    [mergedConfig?.enableVariants, localGatesRevision, telemetry, flags]
+  );
+  const getVariantValue = react.useCallback(
+    (featureKey, isT) => {
+      return decodeVariantValue(getVariant(featureKey)?.configurationValue, isT);
+    },
+    [getVariant]
+  );
   const installContext = react.useCallback((target) => {
     contextRef.current = target;
     telemetry.setContext(target);
     flagsRef.current = mergedConfig?.featureDefaults ?? {};
+    variantsRef.current = null;
     setFlags(flagsRef.current);
     setIdentity(target.identity);
   }, [mergedConfig?.featureDefaults, telemetry]);
@@ -816,6 +877,8 @@ function TogglyProviderOwner({
       isDisabled,
       evaluateGate,
       registerContext: registerContext2,
+      getVariant,
+      getVariantValue,
       identify,
       reset,
       refresh,
@@ -834,6 +897,8 @@ function TogglyProviderOwner({
       isDisabled,
       evaluateGate,
       registerContext2,
+      getVariant,
+      getVariantValue,
       identify,
       reset,
       refresh,
@@ -995,27 +1060,19 @@ function RouterTogglyProvider({
   config,
   ...props
 }) {
-  let serverContext;
-  try {
-    if (routeId) {
-      const routeData = reactRouter.useRouteLoaderData(routeId);
-      serverContext = routeData?.[TOGGLY_LOADER_KEY];
-    } else {
-      const loaderData = reactRouter.useLoaderData();
-      serverContext = loaderData?.[TOGGLY_LOADER_KEY];
-    }
-  } catch {
-    serverContext = fallbackContext;
-  }
-  serverContext = serverContext ?? fallbackContext;
-  const mergedConfig = config ?? (serverContext ? {
-    appKey: serverContext.appKey,
-    environment: serverContext.environment
+  const routeData = reactRouter.useRouteLoaderData(routeId ?? "");
+  const loaderData = reactRouter.useLoaderData();
+  const data = routeId ? routeData : loaderData;
+  const serverContext = data?.[TOGGLY_LOADER_KEY];
+  const resolvedServerContext = serverContext ?? fallbackContext;
+  const mergedConfig = config ?? (resolvedServerContext ? {
+    appKey: resolvedServerContext.appKey,
+    environment: resolvedServerContext.environment
   } : void 0);
   return /* @__PURE__ */ jsxRuntime.jsx(
     TogglyProvider,
     {
-      serverContext,
+      serverContext: resolvedServerContext,
       config: mergedConfig,
       ...props,
       children