@molecule/app-react-native 1.0.4 → 2.0.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-10-23T14:59:33.332Z
+Generated: 2026-10-26T04:14:39.672Z
 -->
 
 # @molecule/app-react-native
@@ -208,9 +208,12 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
     confirmPasswordReset(data: PasswordResetConfirm): Promise<void>;
     /**
      * Updates the current user's profile.
-     * Returns the saved response. If the session is explicitly replaced or ended
-     * while the request is pending, that response does not replace the current
-     * session's user or persisted cache.
+     * Returns the saved profile: the answer applied onto the signed-in user field
+     * by field, with or without an `id` — a field it carries replaces the value
+     * (`null` clears it), one it omits or leaves `undefined` is kept, so a field
+     * cleared by omission must arrive as `null`. A non-object answer is returned
+     * as it came. An answer for a replaced or ended session leaves the current one
+     * untouched.
      */
     updateProfile(data: Partial<T>): Promise<T>;
     /**
@@ -266,9 +269,6 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * Resolves when the session restore started by `initialize()` has settled — the point
      * after which the client knows whether this visitor is signed in.
      *
-     * Resolves IMMEDIATELY when no restore is in flight: before `initialize()` is ever
-     * called, and after it has finished. A restore that failed resolves too (it settled the
-     * question), so an HTTP client can await this before every request without risking one
 // … truncated — the full declaration is in node_modules/@molecule/app-react-native/dist
 ```
 
@@ -476,12 +476,50 @@ interface HttpClient {
   addErrorInterceptor(interceptor: ErrorInterceptor): () => void
   /**
    * Sets the authorization token.
+   *
+   * A static token: every request carries it until the next `setAuthToken` call. A client
+   * that has a {@link HttpClient.setAuthTokenResolver | resolver} (registered through
+   * `@molecule/app-http`'s `setAuthTokenSource`) ignores this value when it assembles a
+   * request — the resolver IS the session, and reading it per request is what keeps a
+   * session adopted without an auth event from sending the previous account's bearer. Once
+   * the resolver is removed, the static token is sent again.
    */
   setAuthToken(token: string | null): void
   /**
-   * Returns the current authorization token, or `null` if not set.
+   * Returns the token the client applies to its next request: the resolver's answer when one
+   * is registered, else the static token from `setAuthToken`.
    */
   getAuthToken(): string | null
+  /**
+   * Registers the LIVE token resolver every request of this client reads, or clears it with
+   * `null`.
+   *
+   * `@molecule/app-http`'s `setAuthTokenSource()` calls this on every client it bonds, and the
+   * client MUST consult the resolver again each time it assembles a request (and report it from
+   * `getAuthToken()`). A session can change with no auth event and no observable state change —
+   * `authClient.setSession()` with the same profile data, or the OAuth callback's
+   * `setAccessToken()` — so a token pushed only at bond time or on `login`/`logout` events
+   * leaves every later request carrying the PREVIOUS session's bearer while the UI shows the
+   * new one.
+   *
+   * The resolved token takes the static token's place, with the same precedence: an
+   * `Authorization` header passed per request or in the client's default headers wins over it
+   * exactly where it won over a static token in this transport.
+   *
+   * A resolver that returns `null` (or `undefined`) means "this session has no body token": the
+   * request carries no `Authorization` header of the client's own. A cookie-session API issues
+   * no bearer, and the server prefers the header over the fresh cookie, so a kept bearer
+   * authenticates as the prior — possibly deleted — session.
+   *
+   * Optional, so an implementation written against the previous interface still conforms.
+   * `setAuthTokenSource()` follows such a client through a request interceptor instead, pushing
+   * the source with `setAuthToken` before each request: that request carries the change only
+   * when the transport applies its token after running its interceptors, so a transport that
+   * applies it earlier sends a session adopted mid-page from the following request on.
+   *
+   * @param resolver - Returns the current access token (or null/undefined), or `null` to clear.
+   */
+  setAuthTokenResolver?(resolver: AuthTokenResolver | null): void
   /**
    * Registers a handler for authentication errors (401).
    *
@@ -1405,7 +1443,7 @@ interface UseAuthResult<
    *
    * `setUser` alone does NOT sign the client in, and `setAccessToken` changes
    * storage only — using those two for a caller-issued session leaves every
-   * `authenticated` read signed out (xr-molecule-flash-m178).
+   * `authenticated` read signed out.
    */
   setSession: AuthClient<T>['setSession']
   isAuthenticated: boolean
@@ -1806,6 +1844,34 @@ How far the return-page verification has got.
 type VerifyPaymentReturnStatus = 'idle' | 'verifying' | 'verified' | 'failed'
 ```
 
+#### `UseTShorthandOptions`
+
+Options for the shorthand form of {@link UseTFunction}: the fallback text is
+passed positionally, so only `count` remains here.
+
+```typescript
+type UseTShorthandOptions = Omit<TranslateOptions, 'defaultValue'>
+```
+
+#### `UseTFunction`
+
+Translation function returned by `useT()`.
+
+Two compatible call forms:
+
+- `t(key, values?, options?)` — the {@link I18nProvider.t} signature.
+- `t(key, fallback, options?)` — a string second argument is the inline
+  English `defaultValue`, with optional `count` for pluralization.
+
+Its identity is stable while the i18n provider instance is unchanged, so it
+can be used directly as an effect dependency.
+
+```typescript
+type UseTFunction = I18nProvider['t'] & {
+  (key: string, fallback: string, options?: UseTShorthandOptions): string
+}
+```
+
 ### Functions
 
 #### `useAppState()`
@@ -1893,7 +1959,10 @@ Pass the same generics the client was created with —
 the app's own fields.
 
 ```typescript
-function useAuthClient(): AuthClient<T, TRegister>
+function useAuthClient<
+  T = unknown,
+  TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
+>(): AuthClient<T, TRegister>
 ```
 
 **Returns:** The auth client from context
@@ -1923,7 +1992,10 @@ call (and `requestBody` receives the same payload). Without it, `register`
 accepts only the base fields.
 
 ```typescript
-function useAuth(options?: UseAuthOptions): UseAuthResult<T, TRegister>
+function useAuth<
+  T = unknown,
+  TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
+>(options?: UseAuthOptions): UseAuthResult<T, TRegister>
 ```
 
 - `options` — Hook options
@@ -1935,7 +2007,7 @@ function useAuth(options?: UseAuthOptions): UseAuthResult<T, TRegister>
 Hook to get just the authenticated user.
 
 ```typescript
-function useUser(): T | null
+function useUser<T = unknown>(): T | null
 ```
 
 **Returns:** The authenticated user or null
@@ -2097,7 +2169,7 @@ wires a form library once (`setProvider` from `@molecule/app-forms`) and
 every form picks it up. Passing `createForm` overrides that for one form.
 
 ```typescript
-function useForm(options?: UseFormOptions<T>): UseFormResult<T>
+function useForm<T extends Record<string, unknown>>(options?: UseFormOptions<T>): 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.
@@ -2109,7 +2181,10 @@ function useForm(options?: UseFormOptions<T>): UseFormResult<T>
 Hook to watch a specific field value.
 
 ```typescript
-function useWatch(form: FormController<T>, name: K): T[K]
+function useWatch<T extends Record<string, unknown>, K extends keyof T>(
+  form: FormController<T>,
+  name: K,
+): T[K]
 ```
 
 - `form` — Form controller
@@ -2122,7 +2197,10 @@ function useWatch(form: FormController<T>, name: K): T[K]
 Hook to get field-level state.
 
 ```typescript
-function useFieldState(form: FormController<T>, name: keyof T): FieldState<T[keyof T]>
+function useFieldState<T extends Record<string, unknown>>(
+  form: FormController<T>,
+  name: keyof T,
+): FieldState<T[keyof T]>
 ```
 
 - `form` — Form controller
@@ -2154,7 +2232,7 @@ the client does replace `execute` (it selects a different request) and
 re-runs such an effect.
 
 ```typescript
-function useHttp(
+function useHttp<T>(
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
   url: string,
   options?: UseHttpOptions<T>,
@@ -2172,7 +2250,7 @@ function useHttp(
 Hook for GET requests.
 
 ```typescript
-function useGet(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useGet<T>(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
 - `url` — Request URL to fetch from.
@@ -2185,7 +2263,7 @@ function useGet(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 Hook for POST requests.
 
 ```typescript
-function usePost(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function usePost<T>(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
 - `url` — Request URL to post to.
@@ -2198,7 +2276,7 @@ function usePost(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 Hook for PUT requests.
 
 ```typescript
-function usePut(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function usePut<T>(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
 - `url` — Request URL to send the PUT request to.
@@ -2211,7 +2289,7 @@ function usePut(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 Hook for PATCH requests.
 
 ```typescript
-function usePatch(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function usePatch<T>(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
 - `url` — Request URL to send the PATCH request to.
@@ -2224,7 +2302,7 @@ function usePatch(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 Hook for DELETE requests.
 
 ```typescript
-function useDelete(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
+function useDelete<T>(url: string, options?: UseHttpOptions<T>): UseHttpResult<T>
 ```
 
 - `url` — Request URL of the resource to delete.
@@ -2287,7 +2365,7 @@ no separate `useRegister` hook. Use `usePromise(register)` when the form
 needs the same pending/error tracking as this login hook.
 
 ```typescript
-function useLogin(): UseLoginReturn<T>
+function useLogin<T = unknown>(): UseLoginReturn<T>
 ```
 
 **Returns:** Login state and action
@@ -2382,7 +2460,7 @@ the clean baseline; edits made while saving remain dirty. No request is made
 for a patch with no fields. A failed request retains the edits and shared user.
 
 ```typescript
-function useProfileForm(
+function useProfileForm<TUser, TValues extends Record<string, unknown>>(
   options: UseProfileFormOptions<TUser, TValues>,
 ): UseProfileFormResult<TUser, TValues>
 ```
@@ -2440,7 +2518,7 @@ function useLocation(): RouteLocation
 Hook to get route parameters.
 
 ```typescript
-function useParams(): T
+function useParams<T extends Record<string, string> = RouteParams>(): T
 ```
 
 **Returns:** The current route parameters
@@ -2450,7 +2528,7 @@ function useParams(): T
 Hook to get query parameters.
 
 ```typescript
-function useQuery(): T
+function useQuery<T extends QueryParams = QueryParams>(): T
 ```
 
 **Returns:** The current query parameters
@@ -2483,7 +2561,10 @@ function useIsActive(path: string, exact?: boolean): boolean
 Hook for user registration with async state tracking.
 
 ```typescript
-function useSignup(): UseSignupReturn<T, TRegister>
+function useSignup<
+  T = unknown,
+  TRegister extends RegisterExtraShape<TRegister> = Record<never, never>,
+>(): UseSignupReturn<T, TRegister>
 ```
 
 **Returns:** Signup state and action
@@ -2503,7 +2584,10 @@ function useStorageProvider(): StorageProvider
 Hook to manage a single storage value with React state sync.
 
 ```typescript
-function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseStorageValueResult<T>
+function useStorageValue<T>(
+  key: string,
+  options?: UseStorageValueOptions<T>,
+): UseStorageValueResult<T>
 ```
 
 - `key` — Storage key
@@ -2555,7 +2639,7 @@ the state context. A store minted outside the `state` bond — the direct
 therefore as valid here as one `@molecule/app-state`'s `createStore()` made.
 
 ```typescript
-function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
+function useStore<T, S = T>(store: Store<T>, options?: UseStoreOptions<T, S>): S
 ```
 
 - `store` — The store to subscribe to
@@ -2568,7 +2652,7 @@ function useStore(store: Store<T>, options?: UseStoreOptions<T, S>): S
 Hook to get the store's setState function.
 
 ```typescript
-function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Partial<T>)) => void
+function useSetStore<T>(store: Store<T>): Store<T>['setState']
 ```
 
 - `store` — The store to get setState from
@@ -2580,7 +2664,7 @@ function useSetStore(store: Store<T>): (partial: Partial<T> | ((state: T) => Par
 Hook to create a bound action for a store.
 
 ```typescript
-function useStoreAction(
+function useStoreAction<T, Args extends unknown[], R>(
   store: Store<T>,
   action: (setState: Store<T>['setState'], getState: Store<T>['getState']) => (...args: Args) => R,
 ): (...args: Args) => R
@@ -2636,7 +2720,7 @@ function useThemeMode(): 'light' | 'dark'
 Hook to get theme colors.
 
 ```typescript
-function useThemeColors(): ThemeColors
+function useThemeColors(): Theme['colors']
 ```
 
 **Returns:** The current theme colors
@@ -2665,15 +2749,32 @@ function useTranslation(): UseTranslationResult
 
 Hook to get just the translation function.
 
+The returned function keeps ONE identity for as long as the provider
+instance is unchanged, so it is safe as an effect dependency: an effect
+written as `useEffect(..., [t])` does not re-run on ordinary re-renders or on
+a locale change. The hook still re-renders the calling component on every
+locale notification (including `addTranslations` for the active locale), so
+text it reads while rendering is current. A value memoized on `[t]` alone
+keeps the old text after a locale switch: `useMemo(() => t(...), [t])`, or a
+`React.memo` child that receives `t` as a prop. Call `useT()` inside that
+child, or add `useLocale()` to the dependencies.
+
+Call it in either of two compatible forms:
+
+- `t(key, values?, options?)` — the provider signature from
+  `@molecule/app-i18n`, e.g. `t('cart.total', { total })`.
+- `t(key, fallback, options?)` — a shorthand for the common inline-English
+  call: a string second argument is the `defaultValue`, so
+  `t('cart.empty', 'Your cart is empty')` equals
+  `t('cart.empty', undefined, { defaultValue: 'Your cart is empty' })`.
+  Interpolation and pluralization still work:
+  `t('cart.items', '{{count}} items', { count: 3 })`.
+
 ```typescript
-function useT(): (
-  key: string,
-  values?: InterpolationValues,
-  options?: { defaultValue?: string; count?: number },
-) => string
+function useT(): UseTFunction
 ```
 
-**Returns:** The translation function
+**Returns:** The translation function (stable identity while the provider is unchanged).
 
 #### `useLocale()`
 
@@ -2780,10 +2881,7 @@ function useWorkspace(): UseWorkspaceResult
 Provider for state management.
 
 ```typescript
-function StateProvider({
-  provider,
-  children,
-}: StateProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function StateProvider({ provider, children }: StateProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link StateProviderProps}).
@@ -2795,10 +2893,7 @@ function StateProvider({
 Provider for authentication.
 
 ```typescript
-function AuthProvider({
-  client,
-  children,
-}: AuthProviderProps<T>): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function AuthProvider<T = unknown>({ client, children }: AuthProviderProps<T>): React.ReactElement
 ```
 
 - `props` — Component props (see {@link AuthProviderProps}).
@@ -2810,10 +2905,7 @@ function AuthProvider({
 Provider for theming.
 
 ```typescript
-function ThemeProvider({
-  provider,
-  children,
-}: ThemeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function ThemeProvider({ provider, children }: ThemeProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link ThemeProviderProps}).
@@ -2825,10 +2917,7 @@ function ThemeProvider({
 Provider for routing.
 
 ```typescript
-function RouterProvider({
-  router,
-  children,
-}: RouterProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function RouterProvider({ router, children }: RouterProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link RouterProviderProps}).
@@ -2840,10 +2929,7 @@ function RouterProvider({
 Provider for internationalization.
 
 ```typescript
-function I18nProvider({
-  provider,
-  children,
-}: I18nProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function I18nProvider({ provider, children }: I18nProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link I18nProviderProps}).
@@ -2855,10 +2941,7 @@ function I18nProvider({
 Provider for HTTP client.
 
 ```typescript
-function HttpProvider({
-  client,
-  children,
-}: HttpProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function HttpProvider({ client, children }: HttpProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link HttpProviderProps}).
@@ -2870,10 +2953,7 @@ function HttpProvider({
 Provider for storage.
 
 ```typescript
-function StorageProvider({
-  provider,
-  children,
-}: StorageProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function StorageProvider({ provider, children }: StorageProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link StorageProviderProps}).
@@ -2885,10 +2965,7 @@ function StorageProvider({
 Provider for logging.
 
 ```typescript
-function LoggerProvider({
-  provider,
-  children,
-}: LoggerProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function LoggerProvider({ provider, children }: LoggerProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link LoggerProviderProps}).
@@ -2900,10 +2977,7 @@ function LoggerProvider({
 Provider for AI chat.
 
 ```typescript
-function ChatProvider({
-  provider,
-  children,
-}: ChatProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function ChatProvider({ provider, children }: ChatProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link ChatProviderProps}).
@@ -2915,10 +2989,7 @@ function ChatProvider({
 Provider for IDE workspace.
 
 ```typescript
-function WorkspaceProvider({
-  provider,
-  children,
-}: WorkspaceProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function WorkspaceProvider({ provider, children }: WorkspaceProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link WorkspaceProviderProps}).
@@ -2930,10 +3001,7 @@ function WorkspaceProvider({
 Provider for code editor.
 
 ```typescript
-function EditorProvider({
-  provider,
-  children,
-}: EditorProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function EditorProvider({ provider, children }: EditorProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link EditorProviderProps}).
@@ -2945,10 +3013,7 @@ function EditorProvider({
 Provider for live preview.
 
 ```typescript
-function PreviewProvider({
-  provider,
-  children,
-}: PreviewProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+function PreviewProvider({ provider, children }: PreviewProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link PreviewProviderProps}).
@@ -2980,7 +3045,7 @@ function MoleculeProvider({
   workspace,
   editor,
   preview,
-}: MoleculeProviderProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>
+}: MoleculeProviderProps): React.ReactElement
 ```
 
 - `props` — Component props (see {@link MoleculeProviderProps}) — each service is optional, and ONLY the services passed are provided to the tree.
@@ -3148,7 +3213,7 @@ Peer dependencies:
 
 - `@molecule/app-keyboard` ^1.0.1
 - `@molecule/app-lifecycle` ^1.0.1
-- `@molecule/app-react` ^1.0.1
+- `@molecule/app-react` ^2.0.0
 - `react` ^18.0.0 || ^19.0.0
 - `react-native` >=0.72.0
 - `react-native-safe-area-context` >=4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react-native",
-  "version": "1.0.4",
+  "version": "2.0.1",
   "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": "1.10.1",
+    "@molecule/app-react": "2.0.1",
     "@types/node": "26.6.5",
     "react": "19.3.1",
     "typescript": "6.0.3",
@@ -42,7 +42,7 @@
   "peerDependencies": {
     "@molecule/app-keyboard": "^1.0.1",
     "@molecule/app-lifecycle": "^1.0.1",
-    "@molecule/app-react": "^1.0.1",
+    "@molecule/app-react": "^2.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.72.0",
     "react-native-safe-area-context": ">=4.0.0"