@flagdown/react 0.0.3 → 0.0.4

package/README.md

@@ -1,32 +1,50 @@
 # @flagdown/react
 
-Read boolean feature flags from a Flagdown project in React 18+.
+Use the `Feature` component to switch between new UI and a fallback in React 18+.
 
-```tsx
-import { FlagdownProvider, useFlag } from '@flagdown/react';
+```sh
+npm install @flagdown/react@0.0.4
+```
 
-function Checkout() {
-  const enabled = useFlag('new-checkout');
-  return enabled ? <NewCheckout /> : <CurrentCheckout />;
+```tsx
+import { Feature } from '@flagdown/react';
+
+export function Checkout() {
+  return (
+    <Feature
+      flag="new-checkout"
+      fallback={<OldCheckout />}
+    >
+      <NewCheckout />
+    </Feature>
+  );
 }
+```
+
+`Feature` renders its children when the named flag is on. When it is off, unknown,
+still loading, or unavailable, it renders `fallback`. Omit `fallback` to render
+nothing in those cases. Only the selected branch mounts; `Feature` adds no DOM
+wrapper.
+
+Configure the project once at your app root:
+
+```tsx
+import { FlagdownProvider } from '@flagdown/react';
 
 <FlagdownProvider
-  apiUrl="https://your-flagdown-api.example.com"
+  apiUrl="https://api.flagdown.dev"
   clientToken="COPY_PUBLIC_CLIENT_TOKEN_FROM_DASHBOARD"
 >
-  <Checkout />
+  <App />
 </FlagdownProvider>
 ```
 
-Create a project and flag in the dashboard, then copy the generated integration
-snippet. `apiUrl` is the Worker base URL without `/v1`. Install the SDK build that
-includes the remote adapter; the previously published 0.0.2 build only provides
-an injectable evaluator. This source must be released before registry installs
-can use remote reads.
+Create a project and flag in the dashboard, then copy its integration snippet.
+`apiUrl` is the API base URL without `/v1`. `Feature` must be inside the provider.
 
 Flags refresh every 10 seconds, without reloading the page. Set
 `refreshIntervalMs` to change this (minimum 1000ms). Requests time out after 10
-seconds. Initial values, unknown flags and refresh failures evaluate `false`;
+seconds. Initial values, unknown flags and refresh failures evaluate off;
 a successful later refresh restores values. An optional `onError(error)` callback
 can report failures. Changing project configuration immediately discards the
 previous project's values. Unmounting cancels in-flight work and future refreshes.
@@ -35,14 +53,7 @@ Client tokens are public, project-scoped read configuration. They cannot manage
 flags. Replacing a token in the dashboard invalidates the previous token; update
 apps using it. Client-side flags are not an authorization boundary.
 
-For tests or local values, the existing evaluator port remains available:
-
-```tsx
-<FlagdownProvider evaluator={{ isEnabled: key => key === 'new-checkout' }}>
-  <Checkout />
-</FlagdownProvider>
-```
-
-An explicit evaluator takes precedence over remote configuration. A provider
-without either configuration evaluates every flag off. `useFlag` must be called
-inside a provider.
+`Feature` is the SDK's flag consumption API. The evaluation context and evaluator
+are internal; the package exposes no flag hooks or direct evaluation functions.
+Use `FlagdownProvider` to configure your project. A provider without project
+configuration renders each feature's fallback.

package/dist/index.d.ts

@@ -1,20 +1,15 @@
 import * as react from 'react';
-import { PropsWithChildren } from 'react';
+import { PropsWithChildren, ReactNode } from 'react';
 
-/** A port for resolving a feature flag's enabled state. */
-interface FlagEvaluator {
-    isEnabled(flagKey: string): boolean;
-}
-/**
- * Temporary adapter used until the SDK is connected to the Flagdown API.
- *
- * It deliberately keeps every flag disabled so applications can install the
- * provider and hook safely before remote evaluation is available.
- */
-declare const disabledFlagEvaluator: FlagEvaluator;
+type FeatureProps = PropsWithChildren<{
+    /** Key of the flag controlling this feature. */
+    flag: string;
+    /** Rendered while the flag is off, unknown, loading, or unavailable. */
+    fallback?: ReactNode;
+}>;
+declare function Feature({ flag, fallback, children }: FeatureProps): react.JSX.Element;
 
 interface FlagdownProviderProps extends PropsWithChildren {
-    evaluator?: FlagEvaluator;
     apiUrl?: string;
     /** Public, read-only project token copied from the dashboard. */
     clientToken?: string;
@@ -22,8 +17,6 @@ interface FlagdownProviderProps extends PropsWithChildren {
     refreshIntervalMs?: number;
     onError?: (error: Error) => void;
 }
-declare function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshIntervalMs, onError }: FlagdownProviderProps): react.JSX.Element;
-
-declare function useFlag(flagKey: string): boolean;
+declare function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs, onError }: FlagdownProviderProps): react.JSX.Element;
 
-export { type FlagEvaluator, FlagdownProvider, type FlagdownProviderProps, disabledFlagEvaluator, useFlag };
+export { Feature, type FeatureProps, FlagdownProvider, type FlagdownProviderProps };

package/dist/index.js

@@ -1,17 +1,21 @@
-// src/FlagdownProvider.tsx
-import { useEffect, useMemo, useState, useRef } from "react";
+// src/Feature.tsx
+import { useContext } from "react";
 
 // src/FlagdownContext.tsx
-import { createContext, useContext } from "react";
+import { createContext } from "react";
 var FlagdownContext = createContext(void 0);
-function useFlag(flagKey) {
+
+// src/Feature.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function Feature({ flag, fallback = null, children }) {
   const evaluator = useContext(FlagdownContext);
-  if (!evaluator) {
-    throw new Error("useFlag must be used within a FlagdownProvider");
-  }
-  return evaluator.isEnabled(flagKey);
+  if (!evaluator) throw new Error("Feature must be used within a FlagdownProvider");
+  return /* @__PURE__ */ jsx(Fragment, { children: evaluator.isEnabled(flag) ? children : fallback });
 }
 
+// src/FlagdownProvider.tsx
+import { useEffect, useMemo, useState, useRef } from "react";
+
 // src/flags.ts
 var disabledFlagEvaluator = {
   isEnabled: () => false
@@ -33,15 +37,15 @@ async function fetchFlagState(apiUrl, clientToken, signal) {
 }
 
 // src/FlagdownProvider.tsx
-import { jsx } from "react/jsx-runtime";
-function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshIntervalMs = 1e4, onError }) {
+import { jsx as jsx2 } from "react/jsx-runtime";
+function FlagdownProvider({ children, apiUrl, clientToken, refreshIntervalMs = 1e4, onError }) {
   const errorHandler = useRef(onError);
   useEffect(() => {
     errorHandler.current = onError;
   }, [onError]);
   const [snapshot, setSnapshot] = useState();
   useEffect(() => {
-    if (evaluator || !apiUrl || !clientToken) return;
+    if (!apiUrl || !clientToken) return;
     let active = true;
     let timer;
     let controller;
@@ -70,12 +74,11 @@ function FlagdownProvider({ children, evaluator, apiUrl, clientToken, refreshInt
       clearTimeout(timer);
       controller?.abort();
     };
-  }, [apiUrl, clientToken, evaluator, refreshIntervalMs]);
-  const value = useMemo(() => evaluator || (snapshot && snapshot.apiUrl === apiUrl && snapshot.clientToken === clientToken ? { isEnabled: (key) => Object.hasOwn(snapshot.flags, key) && snapshot.flags[key] === true } : disabledFlagEvaluator), [evaluator, snapshot, apiUrl, clientToken]);
-  return /* @__PURE__ */ jsx(FlagdownContext.Provider, { value, children });
+  }, [apiUrl, clientToken, refreshIntervalMs]);
+  const value = useMemo(() => snapshot && snapshot.apiUrl === apiUrl && snapshot.clientToken === clientToken ? { isEnabled: (key) => Object.hasOwn(snapshot.flags, key) && snapshot.flags[key] === true } : disabledFlagEvaluator, [snapshot, apiUrl, clientToken]);
+  return /* @__PURE__ */ jsx2(FlagdownContext.Provider, { value, children });
 }
 export {
-  FlagdownProvider,
-  disabledFlagEvaluator,
-  useFlag
+  Feature,
+  FlagdownProvider
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flagdown/react",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "license": "MIT",
   "type": "module",
   "description": "React SDK for evaluating Flagdown feature flags.",