@effect/atom-react 4.0.0-beta.7 → 4.0.0-beta.70

package/src/ScopedAtom.ts

@@ -1,5 +1,22 @@
 /**
- * @since 1.0.0
+ * The `ScopedAtom` module provides a small React integration for creating atom
+ * instances that are scoped to a component subtree. A scoped atom bundles a
+ * React provider, context, and `use` accessor so each mounted provider owns its
+ * own atom instance instead of sharing a single module-level atom.
+ *
+ * Use `ScopedAtom` when an atom needs to be isolated per feature, route,
+ * component instance, test harness, or provider input. The provider may receive
+ * an initial `value` that is passed to the atom factory, making it useful for
+ * state that should be seeded from React props while still being consumed by the
+ * atom hooks in descendants.
+ *
+ * **Gotchas**
+ *
+ * - `use` must be called under the matching provider or it throws.
+ * - The provider creates the atom once for its lifetime; changing the provider
+ *   `value` prop after mount does not recreate the atom.
+ *
+ * @since 4.0.0
  */
 "use client"
 
@@ -7,39 +24,36 @@ import type * as Atom from "effect/unstable/reactivity/Atom"
 import * as React from "react"
 
 /**
- * @since 1.0.0
- * @category Type IDs
- *
  * Type identifier for ScopedAtom.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~@effect/atom-react/ScopedAtom"
 
 /**
- * @since 1.0.0
- * @category Type IDs
- *
  * Type identifier for ScopedAtom.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
 
 /**
- * @since 1.0.0
- * @category models
- *
  * Scoped Atom interface with a provider-backed instance.
  *
- * @example
+ * **Example** (Providing and reading a scoped atom)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import * as AtomReact from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const Counter = ScopedAtom.make(() => Atom.make(0))
+ * const Counter = AtomReact.make(() => Atom.make(0))
  *
  * function View() {
  *   const atom = Counter.use()
- *   const value = useAtomValue(atom)
+ *   const value = AtomReact.useAtomValue(atom)
  *   return React.createElement("div", null, value)
  * }
  *
@@ -47,33 +61,33 @@ export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
  *   return React.createElement(Counter.Provider, null, React.createElement(View))
  * }
  * ```
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
   readonly [TypeId]: TypeId
   use(): A
-  Provider: Input extends never ? React.FC<{ readonly children?: React.ReactNode | undefined }>
+  Provider: [Input] extends [never] ? React.FC<{ readonly children?: React.ReactNode | undefined }>
     : React.FC<{ readonly children?: React.ReactNode | undefined; readonly value: Input }>
   Context: React.Context<A>
 }
 
 /**
- * @since 1.0.0
- * @category constructors
- *
  * Creates a ScopedAtom from a factory function.
  *
- * @example
+ * **Example** (Creating a scoped atom with input)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import * as AtomReact from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
+ * const User = AtomReact.make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
- *   const value = useAtomValue(atom)
+ *   const value = AtomReact.useAtomValue(atom)
  *   return React.createElement("span", null, value)
  * }
  *
@@ -85,6 +99,9 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
  *   )
  * }
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = <A extends Atom.Atom<any>, Input = never>(
   f: (() => A) | ((input: Input) => A)

package/src/index.ts

@@ -1,23 +1,23 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./Hooks.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./RegistryContext.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ReactHydration.ts"
 
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ScopedAtom.ts"