@molecule/app-react 3.2.0 → 3.3.0

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-03T18:02:49.265Z
+Generated: 2026-11-03T23:48:33.627Z
 -->
 
 # @molecule/app-react
@@ -1029,6 +1029,28 @@ interface UseOAuthReturn {
 }
 ```
 
+#### `UseOptimisticValueResult`
+
+What {@link useOptimisticValue} returns: the state to render and the two ways to change it.
+
+```typescript
+interface UseOptimisticValueResult<T> extends OptimisticValueState<T> {
+  /**
+   * Shows `next` at once and saves it, after any save already running.
+   *
+   * @param next - The value the person chose.
+   */
+  set: (next: T) => void
+
+  /**
+   * Like `set`, computed from the value shown now (`update((on) => !on)`).
+   *
+   * @param change - Computes the next value from the value shown now.
+   */
+  update: (change: (current: T) => T) => void
+}
+```
+
 #### `UsePasswordResetReturn`
 
 Return type for usePasswordReset hook.
@@ -2505,6 +2527,27 @@ function useOAuth(config?: {
 
 **Returns:** OAuth helpers: providers, getOAuthUrl, redirect, and loginViaPopup.
 
+#### `useOptimisticValue(options)`
+
+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
+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
+differs (by `equals`) from the one the hook last received, and only while nothing is being
+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.
+
+```typescript
+function useOptimisticValue<T>(options: OptimisticValueOptions<T>): UseOptimisticValueResult<T>
+```
+
+- `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`.
+
 #### `usePasswordReset()`
 
 Hook for password reset flow with async state tracking.
@@ -3383,7 +3426,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.0.1
+- `@molecule/app-state` ^1.1.0
 - `@molecule/app-storage` ^1.0.1
 - `@molecule/app-theme` ^1.0.1
 - `@molecule/app-ui` ^1.0.1

package/dist/hooks/index.d.ts

@@ -16,6 +16,7 @@ export * from './useHttp.js';
 export * from './useLogger.js';
 export * from './useLogin.js';
 export * from './useOAuth.js';
+export * from './useOptimisticValue.js';
 export * from './usePasswordReset.js';
 export * from './usePlatform.js';
 export * from './usePreview.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA"}

package/dist/hooks/index.js

@@ -16,6 +16,7 @@ export * from './useHttp.js';
 export * from './useLogger.js';
 export * from './useLogin.js';
 export * from './useOAuth.js';
+export * from './useOptimisticValue.js';
 export * from './usePasswordReset.js';
 export * from './usePlatform.js';
 export * from './usePreview.js';

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,sBAAsB,CAAA;AACpC,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA"}

package/dist/hooks/useOptimisticValue.d.ts

@@ -0,0 +1,67 @@
+import type { OptimisticValueOptions, OptimisticValueState } from '@molecule/app-state';
+/**
+ * What {@link useOptimisticValue} returns: the state to render and the two ways to change it.
+ */
+export interface UseOptimisticValueResult<T> extends OptimisticValueState<T> {
+    /**
+     * Shows `next` at once and saves it, after any save already running.
+     *
+     * @param next - The value the person chose.
+     */
+    set: (next: T) => void;
+    /**
+     * Like `set`, computed from the value shown now (`update((on) => !on)`).
+     *
+     * @param change - Computes the next value from the value shown now.
+     */
+    update: (change: (current: T) => T) => void;
+}
+/**
+ * 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
+ * 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
+ * differs (by `equals`) from the one the hook last received, and only while nothing is being
+ * 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.
+ *
+ * @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`.
+ *
+ * @example
+ * ```tsx
+ * import { useOptimisticValue } from '@molecule/app-react'
+ *
+ * function StarButton({ repository }: { repository: Repository }) {
+ *   const star = useOptimisticValue({
+ *     value: { starred: repository.starred, stars: repository.stars },
+ *     equals: (a, b) => a.starred === b.starred && a.stars === b.stars,
+ *     commit: async (next) => {
+ *       const response = next.starred
+ *         ? await http.put(`/repositories/${repository.id}/star`)
+ *         : await http.delete(`/repositories/${repository.id}/star`)
+ *       return { starred: response.data.starred, stars: response.data.stars }
+ *     },
+ *   })
+ *   // Never disable the button or return early while `star.pending` is true.
+ *   return (
+ *     <button
+ *       aria-pressed={star.value.starred}
+ *       onClick={() =>
+ *         star.update((current) => ({
+ *           starred: !current.starred,
+ *           stars: current.stars + (current.starred ? -1 : 1),
+ *         }))
+ *       }
+ *     >
+ *       {star.value.stars}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare const useOptimisticValue: <T>(options: OptimisticValueOptions<T>) => UseOptimisticValueResult<T>;
+//# sourceMappingURL=useOptimisticValue.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useOptimisticValue.js

@@ -0,0 +1,79 @@
+/**
+ * React hook for a server-backed value that the UI changes at once and saves in order.
+ *
+ * @module
+ */
+import { useEffect, useInsertionEffect, useRef, useState, useSyncExternalStore } from 'react';
+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
+ * 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
+ * differs (by `equals`) from the one the hook last received, and only while nothing is being
+ * 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.
+ *
+ * @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`.
+ *
+ * @example
+ * ```tsx
+ * import { useOptimisticValue } from '@molecule/app-react'
+ *
+ * function StarButton({ repository }: { repository: Repository }) {
+ *   const star = useOptimisticValue({
+ *     value: { starred: repository.starred, stars: repository.stars },
+ *     equals: (a, b) => a.starred === b.starred && a.stars === b.stars,
+ *     commit: async (next) => {
+ *       const response = next.starred
+ *         ? await http.put(`/repositories/${repository.id}/star`)
+ *         : await http.delete(`/repositories/${repository.id}/star`)
+ *       return { starred: response.data.starred, stars: response.data.stars }
+ *     },
+ *   })
+ *   // Never disable the button or return early while `star.pending` is true.
+ *   return (
+ *     <button
+ *       aria-pressed={star.value.starred}
+ *       onClick={() =>
+ *         star.update((current) => ({
+ *           starred: !current.starred,
+ *           stars: current.stars + (current.starred ? -1 : 1),
+ *         }))
+ *       }
+ *     >
+ *       {star.value.stars}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export const useOptimisticValue = (options) => {
+    const latest = useRef(options);
+    // Exposed actions may run in a descendant's layout effect, before this component's
+    // layout/passive effects. Publish options from committed renders before those actions.
+    useInsertionEffect(() => {
+        latest.current = options;
+    });
+    const [controller] = useState(() => createOptimisticValue({
+        value: options.value,
+        commit: (next, previous) => latest.current.commit(next, previous),
+        equals: (a, b) => (latest.current.equals ?? shallowEqual)(a, b),
+        onError: (error, value) => latest.current.onError?.(error, value),
+    }));
+    const received = useRef(options.value);
+    const { value, equals } = options;
+    useEffect(() => {
+        if ((equals ?? shallowEqual)(received.current, value))
+            return;
+        received.current = value;
+        controller.sync(value);
+    }, [controller, value, equals]);
+    const state = useSyncExternalStore(controller.subscribe, controller.getState, controller.getState);
+    return { ...state, set: controller.set, update: controller.update };
+};
+//# sourceMappingURL=useOptimisticValue.js.map

package/dist/hooks/useOptimisticValue.js.map

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "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.0.1",
+    "@molecule/app-state": "^1.1.0",
     "@molecule/app-storage": "^1.0.1",
     "@molecule/app-theme": "^1.0.1",
     "@molecule/app-ui": "^1.0.1",