From c90c5f9532b87e5d50fae35564207356a3f3a8c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20Valverd=C3=A9?= <julien.valverde@mailo.com>
Date: Tue, 9 Jun 2026 21:44:08 +0200
Subject: [PATCH] Docs

---
 packages/docs/docs/state-management.md | 35 ++++++++------------------
 1 file changed, 10 insertions(+), 25 deletions(-)

diff --git a/packages/docs/docs/state-management.md b/packages/docs/docs/state-management.md
index 8fa58ea..2bc1280 100644
--- a/packages/docs/docs/state-management.md
+++ b/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
-write to it with `Lens.set` or `Lens.update` from an Effect-FC callback:
+When you need to modify state, write to the Lens with `Lens.set` or
+`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
-only needs to display the value, keep using `Subscribable.useAll`.
+`Lens.useState` is useful when React needs the familiar `[value, setValue]`
+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
-that require synchronous updates such as controlled text inputs.
+If a component only needs to display the value, prefer `Subscribable.useAll`.
+`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).