@molecule/app-react-native 2.0.0 → 3.0.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-10-25T20:03:36.978Z
+Generated: 2026-10-27T23:36:39.690Z
 -->
 
 # @molecule/app-react-native
@@ -279,7 +279,7 @@ Form controller interface.
 All form providers must implement this interface.
 
 ```typescript
-interface FormController<T extends Record<string, unknown> = Record<string, unknown>> {
+interface FormController<T extends FormValuesConstraint<T> = Record<string, unknown>> {
   /**
    * Gets the current form state.
    */
@@ -387,7 +387,7 @@ interface FormController<T extends Record<string, unknown> = Record<string, unkn
 Form creation options.
 
 ```typescript
-interface FormOptions<T extends Record<string, unknown>> {
+interface FormOptions<T extends FormValuesConstraint<T>> {
   /**
    * Default values, captured as the form's clean baseline when the controller
    * is created. Mutating this object afterwards does not change the baseline.
@@ -839,7 +839,7 @@ provider (`createForm` from `@molecule/app-forms`), which uses the built-in
 native provider until the app bonds its own.
 
 ```typescript
-interface UseFormOptions<T extends Record<string, unknown>> extends FormOptions<T> {
+interface UseFormOptions<T extends FormValuesConstraint<T>> extends FormOptions<T> {
   /**
    * Explicit form factory for this one form. Defaults to the bonded forms
    * provider; pass it only to pin a specific provider instance.
@@ -853,7 +853,7 @@ interface UseFormOptions<T extends Record<string, unknown>> extends FormOptions<
 Result of useForm hook.
 
 ```typescript
-interface UseFormResult<T extends Record<string, unknown>> {
+interface UseFormResult<T extends FormValuesConstraint<T>> {
   formState: FormState<T>
   isValid: boolean
   isDirty: boolean
@@ -1002,8 +1002,11 @@ interface UsePlatformResult {
 
 Configuration for a profile form; transport stays in the auth bond.
 
+`TValues` is the page's own controlled-values type, named once as an
+`interface` or a type alias — both satisfy the shared form-values constraint.
+
 ```typescript
-interface UseProfileFormOptions<TUser, TValues extends Record<string, unknown>> extends Omit<
+interface UseProfileFormOptions<TUser, TValues extends FormValuesConstraint<TValues>> extends Omit<
   UseFormOptions<TValues>,
   'defaultValues'
 > {
@@ -1038,7 +1041,7 @@ interface UseProfileFormOptions<TUser, TValues extends Record<string, unknown>>
 Controlled profile form state and native form bindings.
 
 ```typescript
-interface UseProfileFormResult<TUser, TValues extends Record<string, unknown>> extends Omit<
+interface UseProfileFormResult<TUser, TValues extends FormValuesConstraint<TValues>> extends Omit<
   UseFormResult<TValues>,
   'register' | 'handleSubmit' | 'reset'
 > {
@@ -1167,6 +1170,43 @@ interface UseStorageValueResult<T> {
 }
 ```
 
+#### `UseStoragePreferenceOptions`
+
+Options for {@link useStoragePreference}.
+
+```typescript
+interface UseStoragePreferenceOptions<T> {
+  /**
+   * Value reported until the provider supplies one. It is NEVER written to
+   * storage: a default is a display fallback, not a decision the user made.
+   */
+  defaultValue?: T
+}
+```
+
+#### `UseStoragePreferenceResult`
+
+Result of {@link useStoragePreference}.
+
+```typescript
+interface UseStoragePreferenceResult<T> {
+  /** The persisted value, or `defaultValue` while none is known. */
+  value: T | undefined
+  /**
+   * Writes the value through the preference store: subscribers update
+   * immediately and persistence is best-effort.
+   */
+  setValue: (next: T | ((previous: T | undefined) => T)) => void
+  /** Removes the key through the preference store. */
+  removeValue: () => void
+  /**
+   * `true` once the store has a definite answer — the synchronous snapshot on
+   * a synchronous provider, or the hydration result on an asynchronous one.
+   */
+  ready: boolean
+}
+```
+
 #### `UseVerifyPaymentReturnOptions`
 
 Options for {@link useVerifyPaymentReturn}.
@@ -1959,7 +1999,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
@@ -1989,7 +2032,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
@@ -2001,7 +2047,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
@@ -2163,7 +2209,9 @@ 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 FormValuesConstraint<T> = 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.
@@ -2175,7 +2223,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 FormValuesConstraint<T>, K extends keyof T>(
+  form: FormController<T>,
+  name: K,
+): T[K]
 ```
 
 - `form` — Form controller
@@ -2188,7 +2239,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 FormValuesConstraint<T>>(
+  form: FormController<T>,
+  name: keyof T,
+): FieldState<T[keyof T]>
 ```
 
 - `form` — Form controller
@@ -2220,7 +2274,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>,
@@ -2238,7 +2292,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.
@@ -2251,7 +2305,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.
@@ -2264,7 +2318,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.
@@ -2277,7 +2331,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.
@@ -2290,7 +2344,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.
@@ -2353,7 +2407,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
@@ -2448,7 +2502,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 FormValuesConstraint<TValues>>(
   options: UseProfileFormOptions<TUser, TValues>,
 ): UseProfileFormResult<TUser, TValues>
 ```
@@ -2506,7 +2560,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
@@ -2516,7 +2570,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
@@ -2549,7 +2603,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
@@ -2569,7 +2626,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
@@ -2577,6 +2637,33 @@ function useStorageValue(key: string, options?: UseStorageValueOptions<T>): UseS
 
 **Returns:** Storage value state (value, loading, error) and mutators (setValue, removeValue).
 
+#### `useStoragePreference(key, options)`
+
+Subscribes React state to ONE persisted preference.
+
+This is the component-side half of `getPreferenceStore()`: a render-time value
+is available immediately when the bonded provider can answer synchronously,
+and an asynchronous provider's hydration CONVERGES onto the same component
+without a remount. Ordering is the store's: a read that started before a
+newer write, remove or external change is discarded, so a slow hydration
+never overwrites an edit the user already made.
+
+Pass `null` for `key` while the real key is unknown (no project selected
+yet): the hook then behaves as local state around `defaultValue` and persists
+nothing.
+
+```typescript
+function useStoragePreference<T = unknown>(
+  key: string | null | undefined,
+  options?: UseStoragePreferenceOptions<T>,
+): UseStoragePreferenceResult<T>
+```
+
+- `key` — The storage key, or `null` when there is nothing to persist.
+- `options` — `defaultValue`, reported until the provider supplies one.
+
+**Returns:** The current value, its mutators, and whether it is definite yet.
+
 #### `useStorage()`
 
 Hook for simple storage operations without React state sync.
@@ -2621,7 +2708,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
@@ -2634,7 +2721,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
@@ -2646,7 +2733,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
@@ -2702,7 +2789,7 @@ function useThemeMode(): 'light' | 'dark'
 Hook to get theme colors.
 
 ```typescript
-function useThemeColors(): ThemeColors
+function useThemeColors(): Theme['colors']
 ```
 
 **Returns:** The current theme colors
@@ -2863,10 +2950,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}).
@@ -2878,10 +2962,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}).
@@ -2893,10 +2974,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}).
@@ -2908,10 +2986,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}).
@@ -2923,10 +2998,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}).
@@ -2938,10 +3010,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}).
@@ -2953,10 +3022,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}).
@@ -2968,10 +3034,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}).
@@ -2983,10 +3046,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}).
@@ -2998,10 +3058,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}).
@@ -3013,10 +3070,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}).
@@ -3028,10 +3082,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}).
@@ -3063,7 +3114,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.
@@ -3231,7 +3282,7 @@ Peer dependencies:
 
 - `@molecule/app-keyboard` ^1.0.1
 - `@molecule/app-lifecycle` ^1.0.1
-- `@molecule/app-react` ^2.0.0
+- `@molecule/app-react` ^3.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": "2.0.0",
+  "version": "3.0.0",
   "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": "2.0.0",
+    "@molecule/app-react": "3.0.0",
     "@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": "^2.0.0",
+    "@molecule/app-react": "^3.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.72.0",
     "react-native-safe-area-context": ">=4.0.0"