fix: in-line docs, un-needed AbortController creation (#1291)

This PR:

- clarifies some doc around `useWhenProviderReady` (it really only works
with READY)
- moves AbortController instantiation so we don't create it every render
if we don't need to

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

packages/react/src/provider/use-open-feature-client-status.ts

@@ -5,14 +5,15 @@ import { ProviderEvents } from '@openfeature/web-sdk';
 
 /**
  * Get the {@link ProviderStatus} for the OpenFeatureClient.
+ * Reacts to changes in provider status.
  * @returns {ProviderStatus} status of the client for this scope
  */
 export function useOpenFeatureClientStatus(): ProviderStatus {
   const client = useOpenFeatureClient();
   const [status, setStatus] = useState<ProviderStatus>(client.providerStatus);
-  const controller = new AbortController();
 
   useEffect(() => {
+    const controller = new AbortController();
     const updateStatus = () => setStatus(client.providerStatus);
     client.addHandler(ProviderEvents.ConfigurationChanged, updateStatus, { signal: controller.signal });
     client.addHandler(ProviderEvents.ContextChanged, updateStatus, { signal: controller.signal });

packages/react/src/provider/use-when-provider-ready.ts

@@ -11,6 +11,9 @@ type Options = Pick<ReactFlagEvaluationOptions, 'suspendUntilReady'>;
  * Utility hook that triggers suspense until the provider is {@link ProviderStatus.READY}, without evaluating any flags.
  * Especially useful for React v16/17 "Legacy Suspense", in which siblings to suspending components are
  * initially mounted and then hidden (see: https://github.com/reactwg/react-18/discussions/7).
+ *
+ * NOTE: This hook returns true only when the provider status is {@link ProviderStatus.READY}.
+ * For other statuses (ERROR, STALE, FATAL, RECONCILING), use {@link useOpenFeatureClientStatus}.
  * @param {Options} options options for suspense
  * @returns {boolean} boolean indicating if provider is {@link ProviderStatus.READY}, useful if suspense is disabled and you want to handle loaders on your own
  */