@molecule/app-react 3.3.1 → 3.4.1

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-11-04T14:20:06.747Z
+Generated: 2026-11-06T00:14:54.331Z
 -->
 
 # @molecule/app-react
@@ -36,12 +36,75 @@ also render and can still have a null user. Synchronous SSR renders the
 fallback for a loading client: initialize a request-scoped client first,
 or leave the opt-in hold disabled for SSR.
 
+**Server-backed toggles:** use `useOptimisticValue` for a favorite/follow/like,
+bookmark or settings switch that changes immediately. Keep its flag and count
+in one value. Render that value, update it with a functional updater, and return
+both server fields from `commit`. Do not add a second `useState`, a prop-copy
+effect, or an `if (pending) return`/disabled-on-pending guard: the hook accepts
+taps while saving and serializes saves. It coalesces waiting changes to the
+newest value. Let commit reject on failure so the hook can roll back.
+Mount a keyed control only after its record loads. Keep it mounted through
+refetches of that record. The hook protects pending intent from refetches and
+unchanged old props after a save; it cannot order different server snapshots
+received after saving finishes, or make a missing record ready for a click.
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
 
 ## Quick Start
 
+```tsx
+import { useHttpClient, useOptimisticValue, useTranslation } from '@molecule/app-react'
+
+interface FavoriteRecord {
+  slug: string
+  favorited: boolean
+  favoritesCount: number
+}
+
+function FavoriteButton({
+  article,
+  onChanged,
+}: {
+  article: FavoriteRecord
+  onChanged?: (saved: FavoriteRecord) => void
+}) {
+  const http = useHttpClient()
+  const { t } = useTranslation()
+  const favorite = useOptimisticValue({
+    value: { favorited: article.favorited, count: article.favoritesCount },
+    commit: async (next) => {
+      const path = `/articles/${article.slug}/favorite`
+      const response = next.favorited
+        ? await http.post<{ article: FavoriteRecord }>(path)
+        : await http.delete<{ article: FavoriteRecord }>(path)
+      const saved = response.data.article
+      onChanged?.(saved)
+      return { favorited: saved.favorited, count: saved.favoritesCount }
+    },
+  })
+  return (
+    <button
+      aria-pressed={favorite.value.favorited}
+      aria-label={t('article.favorite', undefined, { defaultValue: 'Favorite article' })}
+      onClick={() =>
+        favorite.update((current) => ({
+          favorited: !current.favorited,
+          count: current.count + (current.favorited ? -1 : 1),
+        }))
+      }
+    >
+      {favorite.value.count}
+    </button>
+  )
+}
+
+function FavoriteControl({ article }: { article: FavoriteRecord | null }) {
+  return article ? <FavoriteButton key={article.slug} article={article} /> : null
+}
+```
+
 ```tsx
 const profile = useProfileForm<User, { name: string; email: string }>({
   defaultValues: { name: '', email: '' },
@@ -2431,7 +2494,8 @@ function useOAuth(config?: {
 
 A server-backed value — a favorite, follow, like or bookmark button, a rating, a quantity, a
 setting switch — that changes on the first render after a tap and is saved one change at a
-time, in order. A tap during a save is saved right after it; only a failure of the newest
+time, in order. Taps during a save update the desired value; the newest waiting value is
+saved after it (intermediate waiting values coalesce). Only a failure of the newest
 change puts the server value back. See `createOptimisticValue` in `@molecule/app-state`.
 
 `value` is the server's value from props or a query. A new `value` is taken only when it
@@ -2439,6 +2503,18 @@ differs (by `equals`) from the one the hook last received, and only while nothin
 saved, so a parent re-render or a refetch of older data never flips the button mid-save. The
 latest `commit` and `onError` are always used. Give the component a `key` per record, so one
 record's pending change never shows on another.
+Keep related fields, such as a favorite flag and its count, in the SAME value. Return both
+from the server response in `commit`, and publish that response to parent/query caches there
+if needed. Let commit reject on failure: a catch that returns old data hides the failure.
+Replace display-state setters and prop-copy effects with this hook's value and `update`.
+`pending` is for feedback, never a reason to disable the toggle or drop a tap.
+
+Render/enable the keyed control only once its initial record exists. Keep that control
+mounted through refetches of the same record. This hook does not fix a click handler that
+returns on a still-null profile, or a remount that throws its controller away. Refetches
+during a save cannot replace pending intent; changed server snapshots arriving AFTER saving
+finishes are accepted and need query-layer ordering if they can be stale. See the module
+quickstart for a complete favorite button with a server-confirmed count.
 
 ```typescript
 function useOptimisticValue<T>(options: OptimisticValueOptions<T>): UseOptimisticValueResult<T>
@@ -3326,7 +3402,7 @@ Peer dependencies:
 - `@molecule/app-i18n` ^1.0.1
 - `@molecule/app-logger` ^1.0.1
 - `@molecule/app-routing` ^1.0.1
-- `@molecule/app-state` ^1.1.0
+- `@molecule/app-state` ^1.2.0
 - `@molecule/app-storage` ^1.0.1
 - `@molecule/app-theme` ^1.0.1
 - `@molecule/app-ui` ^1.0.1
@@ -3364,6 +3440,10 @@ Peer dependencies:
 - `@molecule/app-version`
 - `react`
 
+- Server-backed switches and counters use `useOptimisticValue`. When one commit saves
+  several records, call its third argument after each accepted request:
+  `confirm((current) => ({ ...current, [id]: saved }))`, then return nothing. A later
+  rejection keeps those accepted records while rolling back the unsaved changes.
 - `useProfileForm` needs `AuthProvider` (or `MoleculeProvider auth={client}`)
   and uses the bonded forms provider, just like `useForm`. `defaultValues`
   and `toValues` must cover every registered control; map nullable text to

package/dist/hooks/useOptimisticValue.d.ts

@@ -19,7 +19,8 @@ export interface UseOptimisticValueResult<T> extends OptimisticValueState<T> {
 /**
  * A server-backed value — a favorite, follow, like or bookmark button, a rating, a quantity, a
  * setting switch — that changes on the first render after a tap and is saved one change at a
- * time, in order. A tap during a save is saved right after it; only a failure of the newest
+ * time, in order. Taps during a save update the desired value; the newest waiting value is
+ * saved after it (intermediate waiting values coalesce). Only a failure of the newest
  * change puts the server value back. See `createOptimisticValue` in `@molecule/app-state`.
  *
  * `value` is the server's value from props or a query. A new `value` is taken only when it
@@ -27,6 +28,18 @@ export interface UseOptimisticValueResult<T> extends OptimisticValueState<T> {
  * saved, so a parent re-render or a refetch of older data never flips the button mid-save. The
  * latest `commit` and `onError` are always used. Give the component a `key` per record, so one
  * record's pending change never shows on another.
+ * Keep related fields, such as a favorite flag and its count, in the SAME value. Return both
+ * from the server response in `commit`, and publish that response to parent/query caches there
+ * if needed. Let commit reject on failure: a catch that returns old data hides the failure.
+ * Replace display-state setters and prop-copy effects with this hook's value and `update`.
+ * `pending` is for feedback, never a reason to disable the toggle or drop a tap.
+ *
+ * Render/enable the keyed control only once its initial record exists. Keep that control
+ * mounted through refetches of the same record. This hook does not fix a click handler that
+ * returns on a still-null profile, or a remount that throws its controller away. Refetches
+ * during a save cannot replace pending intent; changed server snapshots arriving AFTER saving
+ * finishes are accepted and need query-layer ordering if they can be stale. See the module
+ * quickstart for a complete favorite button with a server-confirmed count.
  *
  * @param options - The server's current value and how to save a change.
  * @returns The value to render, whether a save is pending, the newest failure, and `set`/`update`.

package/dist/hooks/useOptimisticValue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOptimisticValue.d.ts","sourceRoot":"","sources":["../../src/hooks/useOptimisticValue.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAGvF;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;IAC1E;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;IAEtB;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAA;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAClC,SAAS,sBAAsB,CAAC,CAAC,CAAC,KACjC,wBAAwB,CAAC,CAAC,CA2B5B,CAAA"}
+{"version":3,"file":"useOptimisticValue.d.ts","sourceRoot":"","sources":["../../src/hooks/useOptimisticValue.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAGvF;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;IAC1E;;;;OAIG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAA;IAEtB;;;;OAIG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAA;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,EAClC,SAAS,sBAAsB,CAAC,CAAC,CAAC,KACjC,wBAAwB,CAAC,CAAC,CA2B5B,CAAA"}

package/dist/hooks/useOptimisticValue.js

@@ -8,7 +8,8 @@ import { createOptimisticValue, shallowEqual } from '@molecule/app-state';
 /**
  * A server-backed value — a favorite, follow, like or bookmark button, a rating, a quantity, a
  * setting switch — that changes on the first render after a tap and is saved one change at a
- * time, in order. A tap during a save is saved right after it; only a failure of the newest
+ * time, in order. Taps during a save update the desired value; the newest waiting value is
+ * saved after it (intermediate waiting values coalesce). Only a failure of the newest
  * change puts the server value back. See `createOptimisticValue` in `@molecule/app-state`.
  *
  * `value` is the server's value from props or a query. A new `value` is taken only when it
@@ -16,6 +17,18 @@ import { createOptimisticValue, shallowEqual } from '@molecule/app-state';
  * saved, so a parent re-render or a refetch of older data never flips the button mid-save. The
  * latest `commit` and `onError` are always used. Give the component a `key` per record, so one
  * record's pending change never shows on another.
+ * Keep related fields, such as a favorite flag and its count, in the SAME value. Return both
+ * from the server response in `commit`, and publish that response to parent/query caches there
+ * if needed. Let commit reject on failure: a catch that returns old data hides the failure.
+ * Replace display-state setters and prop-copy effects with this hook's value and `update`.
+ * `pending` is for feedback, never a reason to disable the toggle or drop a tap.
+ *
+ * Render/enable the keyed control only once its initial record exists. Keep that control
+ * mounted through refetches of the same record. This hook does not fix a click handler that
+ * returns on a still-null profile, or a remount that throws its controller away. Refetches
+ * during a save cannot replace pending intent; changed server snapshots arriving AFTER saving
+ * finishes are accepted and need query-layer ordering if they can be stale. See the module
+ * quickstart for a complete favorite button with a server-confirmed count.
  *
  * @param options - The server's current value and how to save a change.
  * @returns The value to render, whether a save is pending, the newest failure, and `set`/`update`.
@@ -61,7 +74,7 @@ export const useOptimisticValue = (options) => {
     });
     const [controller] = useState(() => createOptimisticValue({
         value: options.value,
-        commit: (next, previous) => latest.current.commit(next, previous),
+        commit: (next, previous, confirm) => latest.current.commit(next, previous, confirm),
         equals: (a, b) => (latest.current.equals ?? shallowEqual)(a, b),
         onError: (error, value) => latest.current.onError?.(error, value),
     }));

package/dist/hooks/useOptimisticValue.js.map

@@ -1 +1 @@
-{"version":3,"file":"useOptimisticValue.js","sourceRoot":"","sources":["../../src/hooks/useOptimisticValue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAG7F,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAqBzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,OAAkC,EACL,EAAE;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAC9B,mFAAmF;IACnF,uFAAuF;IACvF,kBAAkB,CAAC,GAAG,EAAE;QACtB,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;IAC1B,CAAC,CAAC,CAAA;IAEF,MAAM,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CACjC,qBAAqB,CAAI;QACvB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC;QACjE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC;KAClE,CAAC,CACH,CAAA;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACtC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACjC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;YAAE,OAAM;QAC7D,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAA;QACxB,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IAE/B,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;IAClG,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAA;AACrE,CAAC,CAAA"}
+{"version":3,"file":"useOptimisticValue.js","sourceRoot":"","sources":["../../src/hooks/useOptimisticValue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAG7F,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAqBzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,OAAkC,EACL,EAAE;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAC9B,mFAAmF;IACnF,uFAAuF;IACvF,kBAAkB,CAAC,GAAG,EAAE;QACtB,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;IAC1B,CAAC,CAAC,CAAA;IAEF,MAAM,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CACjC,qBAAqB,CAAI;QACvB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC;QACnF,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/D,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC;KAClE,CAAC,CACH,CAAA;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACtC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACjC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;YAAE,OAAM;QAC7D,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAA;QACxB,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IAE/B,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;IAClG,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAA;AACrE,CAAC,CAAA"}

package/dist/index.d.ts

@@ -27,6 +27,63 @@
  * fallback for a loading client: initialize a request-scoped client first,
  * or leave the opt-in hold disabled for SSR.
  *
+ * **Server-backed toggles:** use `useOptimisticValue` for a favorite/follow/like,
+ * bookmark or settings switch that changes immediately. Keep its flag and count
+ * in one value. Render that value, update it with a functional updater, and return
+ * both server fields from `commit`. Do not add a second `useState`, a prop-copy
+ * effect, or an `if (pending) return`/disabled-on-pending guard: the hook accepts
+ * taps while saving and serializes saves. It coalesces waiting changes to the
+ * newest value. Let commit reject on failure so the hook can roll back.
+ * Mount a keyed control only after its record loads. Keep it mounted through
+ * refetches of that record. The hook protects pending intent from refetches and
+ * unchanged old props after a save; it cannot order different server snapshots
+ * received after saving finishes, or make a missing record ready for a click.
+ *
+ * @example
+ * ```tsx
+ * import { useHttpClient, useOptimisticValue, useTranslation } from '@molecule/app-react'
+ *
+ * interface FavoriteRecord {
+ *   slug: string
+ *   favorited: boolean
+ *   favoritesCount: number
+ * }
+ *
+ * function FavoriteButton({ article, onChanged }: {
+ *   article: FavoriteRecord
+ *   onChanged?: (saved: FavoriteRecord) => void
+ * }) {
+ *   const http = useHttpClient()
+ *   const { t } = useTranslation()
+ *   const favorite = useOptimisticValue({
+ *     value: { favorited: article.favorited, count: article.favoritesCount },
+ *     commit: async (next) => {
+ *       const path = `/articles/${article.slug}/favorite`
+ *       const response = next.favorited
+ *         ? await http.post<{ article: FavoriteRecord }>(path)
+ *         : await http.delete<{ article: FavoriteRecord }>(path)
+ *       const saved = response.data.article
+ *       onChanged?.(saved)
+ *       return { favorited: saved.favorited, count: saved.favoritesCount }
+ *     },
+ *   })
+ *   return (
+ *     <button
+ *       aria-pressed={favorite.value.favorited}
+ *       aria-label={t('article.favorite', undefined, { defaultValue: 'Favorite article' })}
+ *       onClick={() => favorite.update((current) => ({
+ *         favorited: !current.favorited,
+ *         count: current.count + (current.favorited ? -1 : 1),
+ *       }))}
+ *     >{favorite.value.count}</button>
+ *   )
+ * }
+ *
+ * function FavoriteControl({ article }: { article: FavoriteRecord | null }) {
+ *   return article ? <FavoriteButton key={article.slug} article={article} /> : null
+ * }
+ * ```
+ *
  * @example
  * ```tsx
  * const profile = useProfileForm<User, { name: string; email: string }>({
@@ -90,6 +147,10 @@
  * ```
  *
  * @remarks
+ * - Server-backed switches and counters use `useOptimisticValue`. When one commit saves
+ *   several records, call its third argument after each accepted request:
+ *   `confirm((current) => ({ ...current, [id]: saved }))`, then return nothing. A later
+ *   rejection keeps those accepted records while rolling back the unsaved changes.
  * - `useProfileForm` needs `AuthProvider` (or `MoleculeProvider auth={client}`)
  *   and uses the bonded forms provider, just like `useForm`. `defaultValues`
  *   and `toValues` must cover every registered control; map nullable text to

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6KG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0OG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -27,6 +27,63 @@
  * fallback for a loading client: initialize a request-scoped client first,
  * or leave the opt-in hold disabled for SSR.
  *
+ * **Server-backed toggles:** use `useOptimisticValue` for a favorite/follow/like,
+ * bookmark or settings switch that changes immediately. Keep its flag and count
+ * in one value. Render that value, update it with a functional updater, and return
+ * both server fields from `commit`. Do not add a second `useState`, a prop-copy
+ * effect, or an `if (pending) return`/disabled-on-pending guard: the hook accepts
+ * taps while saving and serializes saves. It coalesces waiting changes to the
+ * newest value. Let commit reject on failure so the hook can roll back.
+ * Mount a keyed control only after its record loads. Keep it mounted through
+ * refetches of that record. The hook protects pending intent from refetches and
+ * unchanged old props after a save; it cannot order different server snapshots
+ * received after saving finishes, or make a missing record ready for a click.
+ *
+ * @example
+ * ```tsx
+ * import { useHttpClient, useOptimisticValue, useTranslation } from '@molecule/app-react'
+ *
+ * interface FavoriteRecord {
+ *   slug: string
+ *   favorited: boolean
+ *   favoritesCount: number
+ * }
+ *
+ * function FavoriteButton({ article, onChanged }: {
+ *   article: FavoriteRecord
+ *   onChanged?: (saved: FavoriteRecord) => void
+ * }) {
+ *   const http = useHttpClient()
+ *   const { t } = useTranslation()
+ *   const favorite = useOptimisticValue({
+ *     value: { favorited: article.favorited, count: article.favoritesCount },
+ *     commit: async (next) => {
+ *       const path = `/articles/${article.slug}/favorite`
+ *       const response = next.favorited
+ *         ? await http.post<{ article: FavoriteRecord }>(path)
+ *         : await http.delete<{ article: FavoriteRecord }>(path)
+ *       const saved = response.data.article
+ *       onChanged?.(saved)
+ *       return { favorited: saved.favorited, count: saved.favoritesCount }
+ *     },
+ *   })
+ *   return (
+ *     <button
+ *       aria-pressed={favorite.value.favorited}
+ *       aria-label={t('article.favorite', undefined, { defaultValue: 'Favorite article' })}
+ *       onClick={() => favorite.update((current) => ({
+ *         favorited: !current.favorited,
+ *         count: current.count + (current.favorited ? -1 : 1),
+ *       }))}
+ *     >{favorite.value.count}</button>
+ *   )
+ * }
+ *
+ * function FavoriteControl({ article }: { article: FavoriteRecord | null }) {
+ *   return article ? <FavoriteButton key={article.slug} article={article} /> : null
+ * }
+ * ```
+ *
  * @example
  * ```tsx
  * const profile = useProfileForm<User, { name: string; email: string }>({
@@ -90,6 +147,10 @@
  * ```
  *
  * @remarks
+ * - Server-backed switches and counters use `useOptimisticValue`. When one commit saves
+ *   several records, call its third argument after each accepted request:
+ *   `confirm((current) => ({ ...current, [id]: saved }))`, then return nothing. A later
+ *   rejection keeps those accepted records while rolling back the unsaved changes.
  * - `useProfileForm` needs `AuthProvider` (or `MoleculeProvider auth={client}`)
  *   and uses the bonded forms provider, just like `useForm`. `defaultValues`
  *   and `toValues` must cover every registered control; map nullable text to

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6KG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0OG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "React framework bindings for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "@molecule/app-i18n": "^1.0.1",
     "@molecule/app-logger": "^1.0.1",
     "@molecule/app-routing": "^1.0.1",
-    "@molecule/app-state": "^1.1.0",
+    "@molecule/app-state": "^1.2.0",
     "@molecule/app-storage": "^1.0.1",
     "@molecule/app-theme": "^1.0.1",
     "@molecule/app-ui": "^1.0.1",