Docs

packages/docs/docs/state-management.md

@@ -106,8 +106,8 @@ const CounterReadOnlyView = Component.make("CounterReadOnly")(
 
 `Subscribable.useAll` reads the current values during render and uses scoped subscriptions to update React state when changes arrive.
 
-When the state is a `Lens`, keep binding it with `Subscribable.useAll` and
+When you need to modify state, write to the Lens with `Lens.set` or
-write to it with `Lens.set` or `Lens.update` from an Effect-FC callback:
+`Lens.update` from an Effect-FC callback:
 
 ```tsx
 const CounterControlsView = Component.make("CounterControls")(
@@ -135,13 +135,16 @@ const CounterControlsView = Component.make("CounterControls")(
 )
 ```
 
-## Lenses
+## Lens.useState
 
-A `Lens<A>` is a `Subscribable<A>` that can also be written to. If a component
+`Lens.useState` is useful when React needs the familiar `[value, setValue]`
-only needs to display the value, keep using `Subscribable.useAll`.
+tuple, backed by a Lens. Reach for it when the JSX API expects a synchronous
+setter, especially controlled inputs such as text fields, checkboxes, selects,
+or third-party components with `value` / `onChange` props.
 
-Use `Lens.useState` when React needs a read/write tuple, especially for inputs
+If a component only needs to display the value, prefer `Subscribable.useAll`.
-that require synchronous updates such as controlled text inputs.
+`Lens.useState` is for places where reading and writing need to be wired
+together in React's local-state shape.
 
 ```tsx
 import { Effect, SubscriptionRef } from "effect"
@@ -172,24 +175,6 @@ const NameInputView = Component.make("NameInput")(function* () {
 the setter writes through the Lens, so every other component subscribed to the
 same Lens sees the update.
 
-## Choosing One
-
-Use `Subscribable.useAll` when render needs to read values:
-
-```tsx
-const [count, doubled] = yield* Subscribable.useAll([
-  state.count,
-  state.doubled,
-])
-```
-
-Use `Lens.useState` when JSX needs both the current value and a synchronous
-setter:
-
-```tsx
-const [name, setName] = yield* Lens.useState(state.name)
-```
-
 For focusing into nested state, deriving lenses, custom write behavior, and the
 complete API, refer to the
 [`effect-lens` documentation](https://github.com/Thiladev/effect-lens).