@molecule/app-react-native 3.0.0 → 3.0.2

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-10-27T23:36:39.690Z
+Generated: 2026-10-31T13:49:36.606Z
 -->
 
 # @molecule/app-react-native
@@ -72,7 +72,10 @@ Reactive authentication state snapshot (initialized, authenticated, user, loadin
 interface AuthState<T = UserProfile> {
   /**
    * The session's state as one value — render from this instead of combining
-   * `initialized`/`authenticated`/`loading`. See {@link AuthStatus}.
+   * `initialized`/`authenticated`/`loading`. `'loading'` is undecided, so wait
+   * and redirect only on `'unauthenticated'`; `'unavailable'` keeps the candidate
+   * for retry and can have a null profile. A restore failure other than 401/403
+   * never signs out. See {@link AuthStatus}.
    */
   status: AuthStatus
   /**
@@ -80,11 +83,14 @@ interface AuthState<T = UserProfile> {
    */
   initialized: boolean
   /**
-   * Whether the user is authenticated.
+   * Whether the client has an authenticated session. This is not a server
+   * confirmation flag: during `'unavailable'` it can be false for a retained
+   * token/cookie-only candidate with no cached profile. Use `status` for redirects.
    */
   authenticated: boolean
   /**
-   * Current user (if authenticated).
+   * Current user, or null when none is cached. In particular, an `'unavailable'`
+   * token/cookie-only restore has a retained candidate but no profile yet.
    */
   user: T | null
   /**
@@ -138,12 +144,23 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * Updates the cached user object (state + persistent storage) without
      * hitting the network. Intended for local refreshes after a per-app
      * mutation (e.g., the user just PATCHed their own profile and the
-     * server returned the canonical row). Does NOT change tokens.
+     * server returned the canonical row). A non-null profile does NOT change
+     * tokens or sign the client in: `authenticated` and `status` are unchanged,
+     * so an anonymous client stays anonymous. Use {@link login} /
+     * {@link register} for a credential exchange, or {@link setSession} when
+     * the token was issued outside the client.
      *
-     * This does not sign the client in: `authenticated` and `status` are
-     * unchanged, so an anonymous client stays anonymous. Use
-     * {@link login} / {@link register} for a credential exchange, or
-     * {@link setSession} when the token was issued outside the client.
+     * Passing `null` on a signed-in client, or while any session operation is
+     * pending, ends the local session: it clears the access token, refresh token
+     * and cached user, stops automatic refresh, and settles `authenticated: false`
+     * with `status: 'unauthenticated'` in one notification. Every older operation
+     * loses session ownership, and a persistent sign-out marker prevents a reload
+     * from restoring its credentials or a late cookie. A late credential exchange
+     * is revoked best-effort when a logout endpoint is configured, without blocking
+     * the caller. This method does not otherwise call the server for a settled
+     * session; use {@link logout} for explicit server revocation. On a settled
+     * anonymous client, `null` only clears the cached profile and leaves tokens
+     * and auth state unchanged.
      */
     setUser(user: T | null): void;
     /**
@@ -158,10 +175,13 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * which would violate the storage contract and make a stored bearer token
      * JS-readable (XSS-exfiltratable). Pass `null` to clear it.
      *
-     * This changes token storage only; it does not sign the client in
-     * (`authenticated` and `status` are unchanged). Use {@link login} /
-     * {@link register} for a credential exchange, or call {@link setSession}
-     * with the token and the user to establish an already-issued session.
+     * This changes token storage only: passing `null` does not by itself sign a
+     * signed-in client out, and a non-null token does not sign an anonymous
+     * client in (`authenticated` and `status` are unchanged). Use {@link logout}
+     * to end a session, or {@link setUser} with `null` for local-only sign-out.
+     * Use {@link login} / {@link register} for a credential exchange, or call
+     * {@link setSession} with the token and user to establish an already-issued
+     * session.
      */
     setAccessToken(token: string | null): void;
     /**
@@ -186,7 +206,16 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      */
     login(credentials: LoginCredentials): Promise<AuthResult<T>>;
     /**
-     * Logs out the current user.
+     * Logs out the current user. The server request is best-effort: a missing
+     * logout route (404), any other HTTP failure, or a network error never makes
+     * this method reject. It always clears the access token, refresh token and
+     * cached user, stops automatic refresh, and publishes one settled
+     * `authenticated: false`, `status: 'unauthenticated'` transition. Every pending
+     * session operation loses ownership; a persistent marker prevents reload from
+     * restoring an older session, and late credentials are revoked best-effort.
+     *
+     * When the API has no logout route, set {@link AuthClientConfigOptions.logoutEndpoint}
+     * to `null` (or `''`) to skip the request. Local sign-out still happens.
      */
     logout(): Promise<void>;
     /**
@@ -238,37 +267,6 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * until the cookie restore decides.
      *
      * Do not put this call (or a `/me` request of your own) in front of the first
-     * render, and do not render a loading screen over a session it just restored:
-     * `whenRestored()` already resolves as soon as the restore has settled, and the
-     * HTTP gate built on it holds requests for exactly that window.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Re-checks a restored session against the server, in the background — the
-     * boot-time validation an app with a stored token needs when a revoked or
-     * expired token must sign the user out. Call it AFTER the first render
-     * (`initialize()` restores synchronously from storage; this costs one request).
-     *
-     * - The server confirms the user: the session is refreshed and {@link AuthState.status}
-     *   stays `'authenticated'`.
-     * - The server answers 401 or 403: the token is dead — the stored session is
-     *   cleared and the status becomes `'unauthenticated'`.
-     * - The server cannot confirm the session — a network failure, a 5xx, or a 404
-     *   from a misconfigured {@link AuthClientConfig.currentUserEndpoint}: the
-     *   session (token AND user) is KEPT and the status becomes `'unavailable'`, so
-     *   the app can retry instead of signing the user out over a bad connection or a
-     *   route that does not exist. The 404 error names `currentUserEndpoint`.
-     *
-     * Do not hand-write this beside the client: a parallel token/user store for a
-     * "validating"/"unavailable" flag is the race this method removes.
-     *
-     * Optional: a provider with no restorable session has nothing to validate.
-     */
-    validateSession?(): Promise<void>;
-    /**
-     * Resolves when the session restore started by `initialize()` has settled — the point
-     * after which the client knows whether this visitor is signed in.
-     *
 // … truncated — the full declaration is in node_modules/@molecule/app-react-native/dist
 ```
 
@@ -357,9 +355,20 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
    * `defaultValues`, or the values a previous `reset(values)` established.
    * Passing `values` merges them over the current baseline and makes the
    * result the new baseline, so a form reset to freshly loaded or saved data
-   * reads clean (`isDirty === false`).
+   * reads clean (`isDirty === false`). A changed non-null `id` replaces the
+   * record and cancels a pending submit.
    */
   reset(values?: Partial<T>): void
+  /**
+   * Applies externally loaded values without clearing submission state.
+   *
+   * The new clean baseline is the original `defaultValues` plus this latest
+   * record, never a merge of earlier records. With `keepDirtyValues`, edited
+   * fields retain their values while pristine fields take the loaded values.
+   * A changed non-null `id` still replaces the record and cancels a pending
+   * submit. Equal-content baselines cause no update.
+   */
+  updateValues(values: Partial<T>, resetOptions?: FormResetOptions): void
   /**
    * Handles form submission.
    */
@@ -382,6 +391,21 @@ interface FormController<T extends FormValuesConstraint<T> = Record<string, unkn
 }
 ```
 
+#### `FormResetOptions`
+
+Options controlling how externally supplied values replace a form's baseline.
+
+```typescript
+interface FormResetOptions {
+  /**
+   * Keep fields whose current value differs from their baseline when `values`
+   * changes. Pristine fields still take the new values. False by default, so a
+   * new record can replace edits from the previous record.
+   */
+  keepDirtyValues?: boolean
+}
+```
+
 #### `FormOptions`
 
 Form creation options.
@@ -393,6 +417,14 @@ interface FormOptions<T extends FormValuesConstraint<T>> {
    * is created. Mutating this object afterwards does not change the baseline.
    */
   defaultValues?: Partial<T>
+  /**
+   * Externally loaded values, merged over `defaultValues` as the clean
+   * baseline. Framework bindings also apply later content changes; use
+   * `resetOptions.keepDirtyValues` to preserve edits while pristine fields fill.
+   */
+  values?: Partial<T>
+  /** Controls how framework bindings apply changed `values`. */
+  resetOptions?: FormResetOptions
   /**
    * Validation mode.
    */
@@ -869,8 +901,11 @@ interface UseFormResult<T extends FormValuesConstraint<T>> {
   getError: (name: keyof T) => string | undefined
   setError: (name: keyof T, error: string | undefined) => void
   clearErrors: () => void
-  handleSubmit: (onSubmit: (values: T) => void | Promise<void>) => (event?: React.FormEvent) => void
+  handleSubmit: (
+    onSubmit: (values: T) => void | Promise<void>,
+  ) => (event?: React.FormEvent) => Promise<void>
   reset: (values?: Partial<T>) => void
+  updateValues: (values: Partial<T>, resetOptions?: FormResetOptions) => void
   validate: () => Promise<boolean>
 }
 ```
@@ -1466,7 +1501,9 @@ interface UseAuthResult<
    * The session state as one value — render from this instead of combining
    * `initialized`/`authenticated`/`loading`. A stored token AND user make it
    * `'authenticated'` on the first render; only `'loading'` means "no decision
-   * yet", so a route guard waits on that and nothing else.
+   * yet", so a route guard waits on that and nothing else. `'unavailable'` keeps
+   * a session candidate for retry and can have a null profile; redirect only on
+   * `'unauthenticated'`.
    */
   status: AuthState<T>['status']
   state: AuthState<T>
@@ -1486,8 +1523,10 @@ interface UseAuthResult<
    * `authenticated` read signed out.
    */
   setSession: AuthClient<T>['setSession']
+  /** Whether a session is authenticated locally; this can be false while unavailable. */
   isAuthenticated: boolean
   isLoading: boolean
+  /** The cached profile, which can be null while an unavailable candidate is retained. */
   user: T | null
 }
 ```
@@ -2011,6 +2050,12 @@ function useAuthClient<
 
 Hook for authentication state and actions.
 
+`status === 'loading'` is undecided: wait for it and redirect only on
+`status === 'unauthenticated'`. `'unavailable'` keeps the session candidate
+for retry, but `isAuthenticated` can be false and `user` can be null while a
+token/cookie-only restore has no cached profile. A restore failure other than
+401/403 never signs out.
+
 Pass the app's user type — the SAME type used for the auth client and its
 config (`createJWTAuthClient<MyUser>`, `AuthClientConfig<MyUser>`) — so
 `user` and `setSession`/`setUser` are typed for the pages:
@@ -2214,7 +2259,7 @@ function useForm<T extends FormValuesConstraint<T> = Record<string, unknown>>(
 ): UseFormResult<T>
 ```
 
-- `options` — Form options. `defaultValues`, `mode` and the form-level `validate` are forwarded to the provider; omit the options entirely for a form whose fields are registered with their own defaults.
+- `options` — Form options. `defaultValues`, `mode` and the form-level `validate` are forwarded to the provider. When `values` changes by content, it becomes the new baseline; `resetOptions.keepDirtyValues` retains edited fields while pristine fields take the loaded values. Omit the options entirely for a form whose fields are registered with their own defaults.
 
 **Returns:** Form state and methods
 
@@ -3261,6 +3306,17 @@ const useAsyncState: <T>(initialState: T) => [T, AsyncSetState<T>, AsyncExtendSt
 
 Hook that wraps an async function with state tracking.
 
+For one UI action, pass `state.status === 'pending'` to `Button loading`
+from `@molecule/app-ui-react` (or to a native control's `disabled` prop).
+The control then refuses input while the request is pending and re-enables
+when the tracked call settles. Handle the returned promise's rejection;
+the hook also records the failure in `state.error`.
+
+This hook tracks the latest call: it does not serialize invocations or
+cancel their network requests. An explicit reset/cancel changes the tracked
+state, so it is not proof that an outstanding request has stopped. Use an
+app-owned queue when every click must be accepted in order.
+
 ```typescript
 const usePromise: <T extends (...args: any[]) => Promise<any>>(
   asyncFn: T,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react-native",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "React Native framework bindings for molecule.dev",
   "homepage": "https://www.molecule.dev/packages/app-react-native",
   "type": "module",
@@ -33,7 +33,7 @@
     "directory": "packages/app/frameworks/react-native"
   },
   "devDependencies": {
-    "@molecule/app-react": "3.0.0",
+    "@molecule/app-react": "3.1.0",
     "@types/node": "26.6.5",
     "react": "19.3.1",
     "typescript": "6.0.3",