The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * React helpers for creating Atom instances that belong to one component |
| 3 | * subtree. `make` returns a scoped atom with a provider, context, and `use` |
| 4 | * accessor. Each provider creates its own Atom once, so different subtrees can |
| 5 | * use the same scoped atom definition without sharing state. |
| 6 | * |
| 7 | * @stability unstable |
| 8 | * @since 4.0.0 |
| 9 | */ |
| 10 | "use client" |
| 11 | |
| 12 | import type * as Atom from "effect/reactivity/Atom" |
| 13 | import * as React from "react" |
| 14 | |
| 15 | /** |
| 16 | * Literal type used as the `ScopedAtom` type identifier. |
| 17 | * |
| 18 | * **Details** |
| 19 | * |
| 20 | * Used as the computed property key and marker value stored on `ScopedAtom` |
| 21 | * objects. |
| 22 | * |
| 23 | * @stability unstable |
| 24 | * @category type IDs |
| 25 | * @since 4.0.0 |
| 26 | */ |
| 27 | export type TypeId = "~@effect/atom-react/ScopedAtom" |
| 28 | |
| 29 | /** |
| 30 | * Type identifier for ScopedAtom. |
| 31 | * |
| 32 | * **Details** |
| 33 | * |
| 34 | * Used as the computed property key and marker value stored on `ScopedAtom` |
| 35 | * objects. |
| 36 | * |
| 37 | * @stability unstable |
| 38 | * @category type IDs |
| 39 | * @since 4.0.0 |
| 40 | */ |
| 41 | export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom" |
| 42 | |
| 43 | /** |
| 44 | * Scoped Atom interface with a provider-backed instance. |
| 45 | * |
| 46 | * **Example** (Providing and reading a scoped atom) |
| 47 | * |
| 48 | * ```ts import.meta.vitest |
| 49 | * import { make, useAtomValue } from "@effect/atom-react" |
| 50 | * import { Atom } from "effect/reactivity" |
| 51 | * import * as React from "react" |
| 52 | * import { renderToStaticMarkup } from "react-dom/server" |
| 53 | * |
| 54 | * const Counter = make(() => Atom.make(0)) |
| 55 | * |
| 56 | * function View() { |
| 57 | * const atom = Counter.use() |
| 58 | * const value = useAtomValue(atom) |
| 59 | * return React.createElement("div", null, value) |
| 60 | * } |
| 61 | * |
| 62 | * export function App() { |
| 63 | * return React.createElement(Counter.Provider, null, React.createElement(View)) |
| 64 | * } |
| 65 | * |
| 66 | * renderToStaticMarkup(React.createElement(App)) // => "<div>0</div>" |
| 67 | * ``` |
| 68 | * |
| 69 | * @stability unstable |
| 70 | * @category models |
| 71 | * @since 4.0.0 |
| 72 | */ |
| 73 | export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> { |
| 74 | readonly [TypeId]: TypeId |
| 75 | use(): A |
| 76 | Provider: [Input] extends [never] ? React.FC<{ readonly children?: React.ReactNode | undefined }> |
| 77 | : React.FC<{ readonly children?: React.ReactNode | undefined; readonly value: Input }> |
| 78 | Context: React.Context<A> |
| 79 | } |
| 80 | |
| 81 | /** |
| 82 | * Creates a ScopedAtom from a factory function. |
| 83 | * |
| 84 | * **When to use** |
| 85 | * |
| 86 | * Use to create an atom instance that is owned by a React provider and scoped |
| 87 | * to a component subtree. |
| 88 | * |
| 89 | * **Details** |
| 90 | * |
| 91 | * The returned scoped atom includes a `Provider`, `Context`, and `use` |
| 92 | * accessor. The provider creates the atom once for its lifetime, passing the |
| 93 | * `value` prop to the factory when the scoped atom expects input. |
| 94 | * |
| 95 | * **Gotchas** |
| 96 | * |
| 97 | * `use` must run under the matching provider. Changing the provider `value` |
| 98 | * prop after mount does not recreate the atom. |
| 99 | * |
| 100 | * **Example** (Creating a scoped atom with input) |
| 101 | * |
| 102 | * ```ts import.meta.vitest |
| 103 | * import { make, useAtomValue } from "@effect/atom-react" |
| 104 | * import { Atom } from "effect/reactivity" |
| 105 | * import * as React from "react" |
| 106 | * import { renderToStaticMarkup } from "react-dom/server" |
| 107 | * |
| 108 | * const User = make((name: string) => Atom.make(name)) |
| 109 | * |
| 110 | * function UserName() { |
| 111 | * const atom = User.use() |
| 112 | * const value = useAtomValue(atom) |
| 113 | * return React.createElement("span", null, value) |
| 114 | * } |
| 115 | * |
| 116 | * export function App() { |
| 117 | * return React.createElement( |
| 118 | * User.Provider, |
| 119 | * { value: "Ada" }, |
| 120 | * React.createElement(UserName) |
| 121 | * ) |
| 122 | * } |
| 123 | * |
| 124 | * renderToStaticMarkup(React.createElement(App)) // => "<span>Ada</span>" |
| 125 | * ``` |
| 126 | * |
| 127 | * @stability unstable |
| 128 | * @category constructors |
| 129 | * @since 4.0.0 |
| 130 | */ |
| 131 | export const make = <A extends Atom.Atom<any>, Input = never>( |
| 132 | f: (() => A) | ((input: Input) => A) |
| 133 | ): ScopedAtom<A, Input> => { |
| 134 | const Context = React.createContext<A>(undefined as unknown as A) |
| 135 | |
| 136 | const use = (): A => { |
| 137 | const atom = React.useContext(Context) |
| 138 | if (atom === undefined) { |
| 139 | throw new Error("ScopedAtom used outside of its Provider") |
| 140 | } |
| 141 | return atom |
| 142 | } |
| 143 | |
| 144 | const Provider: React.FC<{ readonly children?: React.ReactNode | undefined; readonly value?: Input }> = (props) => { |
| 145 | const atom = React.useRef<A | null>(null) |
| 146 | if (atom.current === null) { |
| 147 | if ("value" in props) { |
| 148 | atom.current = (f as (input: Input) => A)(props.value as Input) |
| 149 | } else { |
| 150 | atom.current = (f as () => A)() |
| 151 | } |
| 152 | } |
| 153 | return React.createElement(Context.Provider, { value: atom.current }, props.children) |
| 154 | } |
| 155 | |
| 156 | return { |
| 157 | [TypeId]: TypeId, |
| 158 | use, |
| 159 | Provider: Provider as any, |
| 160 | Context |
| 161 | } |
| 162 | } |