add ScopedAtom module to atom-react

closes #322

Author: tim-smart

.changeset/plain-pianos-poke.md

@@ -0,0 +1,5 @@
+---
+"@effect-atom/atom-react": patch
+---
+
+add ScopedAtom module to atom-react

docs/atom-react/ScopedAtom.ts.md

@@ -0,0 +1,78 @@
+---
+title: ScopedAtom.ts
+nav_order: 5
+parent: "@effect-atom/atom-react"
+---
+
+## ScopedAtom overview
+
+Added in v1.0.0
+
+---
+
+<h2 class="text-delta">Table of contents</h2>
+
+- [Type IDs](#type-ids)
+  - [TypeId](#typeid)
+  - [TypeId (type alias)](#typeid-type-alias)
+- [constructors](#constructors)
+  - [make](#make)
+- [models](#models)
+  - [ScopedAtom (interface)](#scopedatom-interface)
+
+---
+
+# Type IDs
+
+## TypeId
+
+**Signature**
+
+```ts
+export declare const TypeId: "~@effect-atom/atom-react/ScopedAtom"
+```
+
+Added in v1.0.0
+
+## TypeId (type alias)
+
+**Signature**
+
+```ts
+export type TypeId = "~@effect-atom/atom-react/ScopedAtom"
+```
+
+Added in v1.0.0
+
+# constructors
+
+## make
+
+**Signature**
+
+```ts
+export declare const make: <A extends Atom.Atom<any>, Input = never>(
+  f: (() => A) | ((input: Input) => A)
+) => ScopedAtom<A, Input>
+```
+
+Added in v1.0.0
+
+# models
+
+## ScopedAtom (interface)
+
+**Signature**
+
+```ts
+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 }>
+    : React.FC<{ readonly children?: React.ReactNode | undefined; readonly value: Input }>
+  Context: React.Context<A>
+}
+```
+
+Added in v1.0.0

docs/atom-react/index.ts.md

@@ -19,6 +19,7 @@ Added in v1.0.0
 - [hooks](#hooks)
   - [From "./Hooks.js"](#from-hooksjs)
 - [re-exports](#re-exports)
+  - [From "./ScopedAtom.js"](#from-scopedatomjs)
   - [From "@effect-atom/atom/AtomHttpApi"](#from-effect-atomatomatomhttpapi)
   - [From "@effect-atom/atom/AtomRef"](#from-effect-atomatomatomref)
   - [From "@effect-atom/atom/AtomRpc"](#from-effect-atomatomatomrpc)
@@ -72,6 +73,18 @@ Added in v1.0.0
 
 # re-exports
 
+## From "./ScopedAtom.js"
+
+Re-exports all named exports from the "./ScopedAtom.js" module as `ScopedAtom`.
+
+**Signature**
+
+```ts
+export * as ScopedAtom from "./ScopedAtom.js"
+```
+
+Added in v1.0.0
+
 ## From "@effect-atom/atom/AtomHttpApi"
 
 Re-exports all named exports from the "@effect-atom/atom/AtomHttpApi" module as `AtomHttpApi`.

packages/atom-react/src/ScopedAtom.ts

@@ -0,0 +1,66 @@
+/**
+ * @since 1.0.0
+ */
+"use client"
+import type * as Atom from "@effect-atom/atom/Atom"
+import * as React from "react"
+
+/**
+ * @since 1.0.0
+ * @category Type IDs
+ */
+export type TypeId = "~@effect-atom/atom-react/ScopedAtom"
+
+/**
+ * @since 1.0.0
+ * @category Type IDs
+ */
+export const TypeId: TypeId = "~@effect-atom/atom-react/ScopedAtom"
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+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 }>
+    : React.FC<{ readonly children?: React.ReactNode | undefined; readonly value: Input }>
+  Context: React.Context<A>
+}
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = <A extends Atom.Atom<any>, Input = never>(
+  f: (() => A) | ((input: Input) => A)
+): ScopedAtom<A, Input> => {
+  const Context = React.createContext<A>(undefined as unknown as A)
+
+  const use = (): A => {
+    const atom = React.useContext(Context)
+    if (atom === undefined) {
+      throw new Error("ScopedAtom used outside of its Provider")
+    }
+    return atom
+  }
+
+  const Provider: React.FC<{ readonly children?: React.ReactNode | undefined; readonly value: Input }> = ({
+    children,
+    value
+  }) => {
+    const atom = React.useRef<A | null>(null)
+    if (atom.current === null) {
+      atom.current = f(value)
+    }
+    return React.createElement(Context.Provider, { value: atom.current }, children)
+  }
+
+  return {
+    [TypeId]: TypeId,
+    use,
+    Provider: Provider as any,
+    Context
+  }
+}

packages/atom-react/src/index.ts

@@ -44,6 +44,12 @@ export * as AtomRpc from "@effect-atom/atom/AtomRpc"
  */
 export * as Hydration from "@effect-atom/atom/Hydration"
 
+/**
+ * @since 1.0.0
+ * @category re-exports
+ */
+export * as ScopedAtom from "./ScopedAtom.js"
+
 /**
  * @since 1.0.0
  * @category hooks