@effect/atom-react 4.0.0-beta.8 → 4.0.0-beta.81

package/dist/Hooks.d.ts

@@ -3,78 +3,279 @@ import type * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import * as Atom from "effect/unstable/reactivity/Atom";
 import type * as AtomRef from "effect/unstable/reactivity/AtomRef";
 /**
- * @since 1.0.0
+ * Seeds initial atom values in the current React atom registry.
+ *
+ * **When to use**
+ *
+ * Use to seed atom values from a React component after the current registry
+ * already exists.
+ *
+ * **Gotchas**
+ *
+ * Each atom is initialized at most once for a given registry by this hook, so
+ * later calls for the same atom in that registry are ignored.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomInitialValues: (initialValues: Iterable<readonly [Atom.Atom<any>, any]>) => void;
 /**
- * @since 1.0.0
+ * Subscribes to an atom in the current React registry and returns its current
+ * value, optionally mapped through a selector.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to render from an atom value without also
+ * returning a setter.
+ *
+ * **Details**
+ *
+ * When a selector is provided, the hook maps the atom before subscribing so the
+ * component reads the selected value from the current `RegistryContext`.
+ *
+ * @see {@link useAtom} for reading and updating a writable atom from one component
+ * @see {@link useAtomRef} for reading an `AtomRef` directly
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomValue: {
     /**
-     * @since 1.0.0
+     * Subscribes to an atom in the current React registry and returns its current
+     * value, optionally mapped through a selector.
+     *
+     * **When to use**
+     *
+     * Use when a React component needs to render from an atom value without also
+     * returning a setter.
+     *
+     * **Details**
+     *
+     * When a selector is provided, the hook maps the atom before subscribing so the
+     * component reads the selected value from the current `RegistryContext`.
+     *
+     * @see {@link useAtom} for reading and updating a writable atom from one component
+     * @see {@link useAtomRef} for reading an `AtomRef` directly
+     *
      * @category hooks
+     * @since 4.0.0
      */
     <A>(atom: Atom.Atom<A>): A;
     /**
-     * @since 1.0.0
+     * Subscribes to an atom in the current React registry and returns its current
+     * value, optionally mapped through a selector.
+     *
+     * **When to use**
+     *
+     * Use when a React component needs to render from an atom value without also
+     * returning a setter.
+     *
+     * **Details**
+     *
+     * When a selector is provided, the hook maps the atom before subscribing so the
+     * component reads the selected value from the current `RegistryContext`.
+     *
+     * @see {@link useAtom} for reading and updating a writable atom from one component
+     * @see {@link useAtomRef} for reading an `AtomRef` directly
+     *
      * @category hooks
+     * @since 4.0.0
      */
     <A, B>(atom: Atom.Atom<A>, f: (_: A) => B): B;
 };
 /**
- * @since 1.0.0
+ * Mounts an atom in the current React registry for the lifetime of the
+ * component.
+ *
+ * **When to use**
+ *
+ * Use to keep an atom mounted from a React component without reading, writing,
+ * or refreshing it.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext` and releases the mount through
+ * React effect cleanup when the component unmounts or when the registry or atom
+ * dependency changes.
+ *
+ * @see {@link useAtomSet} for mounting a writable atom while returning a setter
+ * @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomMount: <A>(atom: Atom.Atom<A>) => void;
 /**
- * @since 1.0.0
+ * Mounts a writable atom and returns a setter without subscribing to its value.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to update a writable atom without rendering
+ * from that atom's value.
+ *
+ * **Details**
+ *
+ * The hook mounts the atom and returns a setter. In value mode the setter
+ * accepts a write value or updater function; for `AsyncResult` atoms, `promise`
+ * and `promiseExit` modes return a promise for the success value or full `Exit`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomSet: <R, W, Mode extends "value" | "promise" | "promiseExit" = never>(atom: Atom.Writable<R, W>, options?: {
     readonly mode?: ([R] extends [AsyncResult.AsyncResult<any, any>] ? Mode : "value") | undefined;
 }) => "promise" extends Mode ? ((value: W) => Promise<AsyncResult.AsyncResult.Success<R>>) : "promiseExit" extends Mode ? ((value: W) => Promise<Exit.Exit<AsyncResult.AsyncResult.Success<R>, AsyncResult.AsyncResult.Failure<R>>>) : ((value: W | ((value: R) => W)) => void);
 /**
- * @since 1.0.0
+ * Mounts an atom and returns a callback that refreshes it in the current React
+ * registry.
+ *
+ * **When to use**
+ *
+ * Use to expose a React callback that requests a refresh for an atom without
+ * reading or writing its value.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext`, mounts the atom for the
+ * component lifetime, and returns a callback that calls `registry.refresh`.
+ *
+ * @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomRefresh: <A>(atom: Atom.Atom<A>) => () => void;
 /**
- * @since 1.0.0
+ * Subscribes to a writable atom and returns its current value together with a
+ * setter for updating it.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs both to render the current value of a
+ * writable atom and update it from the same component.
+ *
+ * @see {@link useAtomValue} for subscribing to an atom without a setter
+ * @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtom: <R, W, const Mode extends "value" | "promise" | "promiseExit" = never>(atom: Atom.Writable<R, W>, options?: {
     readonly mode?: ([R] extends [AsyncResult.AsyncResult<any, any>] ? Mode : "value") | undefined;
 }) => readonly [value: R, write: "promise" extends Mode ? ((value: W) => Promise<AsyncResult.AsyncResult.Success<R>>) : "promiseExit" extends Mode ? ((value: W) => Promise<Exit.Exit<AsyncResult.AsyncResult.Success<R>, AsyncResult.AsyncResult.Failure<R>>>) : ((value: W | ((value: R) => W)) => void)];
 /**
- * @since 1.0.0
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
+ * result is initial or configured as waiting.
+ *
+ * **When to use**
+ *
+ * Use when a React component should render only after an `AsyncResult` atom has
+ * left its initial state, with loading delegated to a Suspense boundary.
+ *
+ * **Details**
+ *
+ * `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+ * failure result is returned instead of being thrown.
+ *
+ * **Gotchas**
+ *
+ * Without `includeFailure`, failure results are thrown with
+ * `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+ *
+ * @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomSuspense: <A, E, const IncludeFailure extends boolean = false>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>, options?: {
     readonly suspendOnWaiting?: boolean | undefined;
     readonly includeFailure?: IncludeFailure | undefined;
 }) => AsyncResult.Success<A, E> | (IncludeFailure extends true ? AsyncResult.Failure<A, E> : never);
 /**
- * @since 1.0.0
+ * Subscribes a callback to an atom in the current React registry for the
+ * component lifetime.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to run a callback for atom changes without
+ * reading the atom value during render.
+ *
+ * **Details**
+ *
+ * The subscription is installed in a React effect and cleaned up on unmount or
+ * dependency change. When `options.immediate` is enabled, the callback receives
+ * the current value when the effect subscribes.
+ *
+ * @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomSubscribe: <A>(atom: Atom.Atom<A>, f: (_: A) => void, options?: {
     readonly immediate?: boolean;
 }) => void;
 /**
- * @since 1.0.0
+ * Subscribes to an atom ref and returns its latest value.
+ *
+ * **When to use**
+ *
+ * Use when a React component should render from an `AtomRef.ReadonlyRef`
+ * directly instead of reading an atom through the current registry.
+ *
+ * **Details**
+ *
+ * The hook subscribes with `ref.subscribe`, triggers re-renders through React
+ * state, and returns the current `ref.value`.
+ *
+ * @see {@link useAtomValue} for reading an `Atom` from the current registry
+ * @see {@link useAtomRefPropValue} for reading a property ref value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomRef: <A>(ref: AtomRef.ReadonlyRef<A>) => A;
 /**
- * @since 1.0.0
+ * Returns a memoized atom ref for a property of another atom ref.
+ *
+ * **When to use**
+ *
+ * Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+ *
+ * **Details**
+ *
+ * The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+ * returns the property ref so callers can read, set, update, or subscribe to
+ * that nested property.
+ *
+ * @see {@link useAtomRef} for subscribing to an atom ref value
+ * @see {@link useAtomRefPropValue} for subscribing directly to a property value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => AtomRef.AtomRef<A[K]>;
 /**
- * @since 1.0.0
+ * Subscribes to a property ref derived from an atom ref and returns its current
+ * value.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs only the current value of one property from
+ * an object-shaped `AtomRef`.
+ *
+ * **Details**
+ *
+ * The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+ * property ref is memoized for the `[ref, prop]` pair and then subscribed
+ * through `ref.subscribe`.
+ *
+ * @see {@link useAtomRefProp} for returning the property ref directly
+ * @see {@link useAtomRef} for subscribing to a whole atom ref value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export declare const useAtomRefPropValue: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => A[K];
 //# sourceMappingURL=Hooks.d.ts.map

package/dist/Hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Hooks.d.ts","sourceRoot":"","sources":["../src/Hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Hooks.d.ts","sourceRoot":"","sources":["../src/Hooks.ts"],"names":[],"mappings":"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"}

package/dist/Hooks.js

@@ -1,5 +1,10 @@
 /**
- * @since 1.0.0
+ * React hooks for working with Effect atoms from components. The hooks read,
+ * write, mount, refresh, and subscribe to atoms from `RegistryContext`, handle
+ * `AsyncResult` atoms with React Suspense, and expose helpers for reading and
+ * deriving `AtomRef` values.
+ *
+ * @since 4.0.0
  */
 "use client";
 
@@ -41,8 +46,20 @@ function useStore(registry, atom) {
 }
 const initialValuesSet = /*#__PURE__*/new WeakMap();
 /**
- * @since 1.0.0
+ * Seeds initial atom values in the current React atom registry.
+ *
+ * **When to use**
+ *
+ * Use to seed atom values from a React component after the current registry
+ * already exists.
+ *
+ * **Gotchas**
+ *
+ * Each atom is initialized at most once for a given registry by this hook, so
+ * later calls for the same atom in that registry are ignored.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomInitialValues = initialValues => {
   const registry = React.useContext(RegistryContext);
@@ -59,8 +76,24 @@ export const useAtomInitialValues = initialValues => {
   }
 };
 /**
- * @since 1.0.0
+ * Subscribes to an atom in the current React registry and returns its current
+ * value, optionally mapped through a selector.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to render from an atom value without also
+ * returning a setter.
+ *
+ * **Details**
+ *
+ * When a selector is provided, the hook maps the atom before subscribing so the
+ * component reads the selected value from the current `RegistryContext`.
+ *
+ * @see {@link useAtom} for reading and updating a writable atom from one component
+ * @see {@link useAtomRef} for reading an `AtomRef` directly
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomValue = (atom, f) => {
   const registry = React.useContext(RegistryContext);
@@ -92,16 +125,48 @@ const flattenExit = exit => {
   throw Cause.squash(exit.cause);
 };
 /**
- * @since 1.0.0
+ * Mounts an atom in the current React registry for the lifetime of the
+ * component.
+ *
+ * **When to use**
+ *
+ * Use to keep an atom mounted from a React component without reading, writing,
+ * or refreshing it.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext` and releases the mount through
+ * React effect cleanup when the component unmounts or when the registry or atom
+ * dependency changes.
+ *
+ * @see {@link useAtomSet} for mounting a writable atom while returning a setter
+ * @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomMount = atom => {
   const registry = React.useContext(RegistryContext);
   mountAtom(registry, atom);
 };
 /**
- * @since 1.0.0
+ * Mounts a writable atom and returns a setter without subscribing to its value.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to update a writable atom without rendering
+ * from that atom's value.
+ *
+ * **Details**
+ *
+ * The hook mounts the atom and returns a setter. In value mode the setter
+ * accepts a write value or updater function; for `AsyncResult` atoms, `promise`
+ * and `promiseExit` modes return a promise for the success value or full `Exit`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSet = (atom, options) => {
   const registry = React.useContext(RegistryContext);
@@ -109,8 +174,23 @@ export const useAtomSet = (atom, options) => {
   return setAtom(registry, atom, options);
 };
 /**
- * @since 1.0.0
+ * Mounts an atom and returns a callback that refreshes it in the current React
+ * registry.
+ *
+ * **When to use**
+ *
+ * Use to expose a React callback that requests a refresh for an atom without
+ * reading or writing its value.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext`, mounts the atom for the
+ * component lifetime, and returns a callback that calls `registry.refresh`.
+ *
+ * @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefresh = atom => {
   const registry = React.useContext(RegistryContext);
@@ -120,8 +200,19 @@ export const useAtomRefresh = atom => {
   }, [registry, atom]);
 };
 /**
- * @since 1.0.0
+ * Subscribes to a writable atom and returns its current value together with a
+ * setter for updating it.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs both to render the current value of a
+ * writable atom and update it from the same component.
+ *
+ * @see {@link useAtomValue} for subscribing to an atom without a setter
+ * @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtom = (atom, options) => {
   const registry = React.useContext(RegistryContext);
@@ -158,8 +249,28 @@ function atomResultOrSuspend(registry, atom, suspendOnWaiting) {
   return value;
 }
 /**
- * @since 1.0.0
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
+ * result is initial or configured as waiting.
+ *
+ * **When to use**
+ *
+ * Use when a React component should render only after an `AsyncResult` atom has
+ * left its initial state, with loading delegated to a Suspense boundary.
+ *
+ * **Details**
+ *
+ * `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+ * failure result is returned instead of being thrown.
+ *
+ * **Gotchas**
+ *
+ * Without `includeFailure`, failure results are thrown with
+ * `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+ *
+ * @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSuspense = (atom, options) => {
   const registry = React.useContext(RegistryContext);
@@ -170,16 +281,47 @@ export const useAtomSuspense = (atom, options) => {
   return result;
 };
 /**
- * @since 1.0.0
+ * Subscribes a callback to an atom in the current React registry for the
+ * component lifetime.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs to run a callback for atom changes without
+ * reading the atom value during render.
+ *
+ * **Details**
+ *
+ * The subscription is installed in a React effect and cleaned up on unmount or
+ * dependency change. When `options.immediate` is enabled, the callback receives
+ * the current value when the effect subscribes.
+ *
+ * @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSubscribe = (atom, f, options) => {
   const registry = React.useContext(RegistryContext);
   React.useEffect(() => registry.subscribe(atom, f, options), [registry, atom, f, options?.immediate]);
 };
 /**
- * @since 1.0.0
+ * Subscribes to an atom ref and returns its latest value.
+ *
+ * **When to use**
+ *
+ * Use when a React component should render from an `AtomRef.ReadonlyRef`
+ * directly instead of reading an atom through the current registry.
+ *
+ * **Details**
+ *
+ * The hook subscribes with `ref.subscribe`, triggers re-renders through React
+ * state, and returns the current `ref.value`.
+ *
+ * @see {@link useAtomValue} for reading an `Atom` from the current registry
+ * @see {@link useAtomRefPropValue} for reading a property ref value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRef = ref => {
   const [, setValue] = React.useState(ref.value);
@@ -187,13 +329,45 @@ export const useAtomRef = ref => {
   return ref.value;
 };
 /**
- * @since 1.0.0
+ * Returns a memoized atom ref for a property of another atom ref.
+ *
+ * **When to use**
+ *
+ * Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+ *
+ * **Details**
+ *
+ * The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+ * returns the property ref so callers can read, set, update, or subscribe to
+ * that nested property.
+ *
+ * @see {@link useAtomRef} for subscribing to an atom ref value
+ * @see {@link useAtomRefPropValue} for subscribing directly to a property value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefProp = (ref, prop) => React.useMemo(() => ref.prop(prop), [ref, prop]);
 /**
- * @since 1.0.0
+ * Subscribes to a property ref derived from an atom ref and returns its current
+ * value.
+ *
+ * **When to use**
+ *
+ * Use when a React component needs only the current value of one property from
+ * an object-shaped `AtomRef`.
+ *
+ * **Details**
+ *
+ * The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+ * property ref is memoized for the `[ref, prop]` pair and then subscribed
+ * through `ref.subscribe`.
+ *
+ * @see {@link useAtomRefProp} for returning the property ref directly
+ * @see {@link useAtomRef} for subscribing to a whole atom ref value
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefPropValue = (ref, prop) => useAtomRef(useAtomRefProp(ref, prop));
 //# sourceMappingURL=Hooks.js.map

package/dist/Hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"Hooks.js","names":["Cause","Effect","Exit","Atom","AtomRegistry","React","RegistryContext","storeRegistry","WeakMap","makeStore","registry","atom","stores","get","undefined","set","store","newStore","subscribe","f","snapshot","getServerSnapshot","getServerValue","useStore","useSyncExternalStore","initialValuesSet","useAtomInitialValues","initialValues","useContext","WeakSet","value","has","add","ensureNode","setValue","useAtomValue","atomB","useMemo","map","mountAtom","useEffect","mount","setAtom","options","mode","useCallback","promise","runPromiseExit","getResult","suspendOnWaiting","then","flattenExit","exit","isSuccess","squash","cause","useAtomMount","useAtomSet","useAtomRefresh","refresh","useAtom","atomPromiseMap","Map","default","atomToPromise","Promise","resolve","dispose","result","_tag","waiting","setTimeout","delete","atomResultOrSuspend","useAtomSuspense","includeFailure","useAtomSubscribe","immediate","useAtomRef","ref","useState","useAtomRefProp","prop","useAtomRefPropValue"],"sources":["../src/Hooks.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"Hooks.js","names":["Cause","Effect","Exit","Atom","AtomRegistry","React","RegistryContext","storeRegistry","WeakMap","makeStore","registry","atom","stores","get","undefined","set","store","newStore","subscribe","f","snapshot","getServerSnapshot","getServerValue","useStore","useSyncExternalStore","initialValuesSet","useAtomInitialValues","initialValues","useContext","WeakSet","value","has","add","ensureNode","setValue","useAtomValue","atomB","useMemo","map","mountAtom","useEffect","mount","setAtom","options","mode","useCallback","promise","runPromiseExit","getResult","suspendOnWaiting","then","flattenExit","exit","isSuccess","squash","cause","useAtomMount","useAtomSet","useAtomRefresh","refresh","useAtom","atomPromiseMap","Map","default","atomToPromise","Promise","resolve","dispose","result","_tag","waiting","setTimeout","delete","atomResultOrSuspend","useAtomSuspense","includeFailure","useAtomSubscribe","immediate","useAtomRef","ref","useState","useAtomRefProp","prop","useAtomRefPropValue"],"sources":["../src/Hooks.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/ReactHydration.d.ts

@@ -1,16 +1,36 @@
 import * as Hydration from "effect/unstable/reactivity/Hydration";
 import * as React from "react";
 /**
- * @since 1.0.0
+ * Props for a boundary that applies dehydrated Atom values to the nearest
+ * {@link RegistryContext} while rendering its children.
+ *
  * @category components
+ * @since 4.0.0
  */
 export interface HydrationBoundaryProps {
     state?: Iterable<Hydration.DehydratedAtom>;
     children?: React.ReactNode;
 }
 /**
- * @since 1.0.0
+ * Provides a React hydration boundary that loads dehydrated Atom values into
+ * the current Atom registry.
+ *
+ * **When to use**
+ *
+ * Use to apply dehydrated Atom state to a React subtree that reads from the
+ * nearest `RegistryContext`.
+ *
+ * **Details**
+ *
+ * New Atom values are hydrated during render so descendants can read them
+ * immediately, while values for existing Atoms are deferred until after commit
+ * so transition data does not update the current UI before React accepts it.
+ *
+ * @see {@link Hydration.dehydrate} for producing dehydrated Atom state
+ * @see {@link Hydration.hydrate} for lower-level non-React hydration
+ *
  * @category components
+ * @since 4.0.0
  */
 export declare const HydrationBoundary: React.FC<HydrationBoundaryProps>;
 //# sourceMappingURL=ReactHydration.d.ts.map

package/dist/ReactHydration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReactHydration.d.ts","sourceRoot":"","sources":["../src/ReactHydration.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAA;AACjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6D9D,CAAA"}
+{"version":3,"file":"ReactHydration.d.ts","sourceRoot":"","sources":["../src/ReactHydration.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAA;AACjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6D9D,CAAA"}