@molecule/app-react 1.8.0 → 1.9.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-22T07:22:55.793Z
+Generated: 2026-10-22T08:55:49.342Z
 -->
 
 # @molecule/app-react
@@ -15,12 +15,38 @@ core interfaces (auth, i18n, theme, routing, state, http, storage, logger,
 chat, workspace, editor, preview), so framework-agnostic providers plug
 into React idioms.
 
+**Editable account/profile forms:** `useProfileForm` composes the bonded form
+and auth clients. It hydrates asynchronous user data without erasing dirty
+fields, snapshots controlled values on native form submission, submits only
+changed fields through an app-supplied adapter, and persists/publishes the
+server's saved user. Use its `onSaved` callback to update other query caches
+from that response before navigating. Configure the endpoint, method and JSON
+envelope once in `AuthClientConfig`; no page-local session store is needed.
+
 > **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
+const profile = useProfileForm<User, { name: string; email: string }>({
+  defaultValues: { name: '', email: '' },
+  getIdentity: (user) => user.id,
+  toValues: (user) => ({ name: user.name ?? '', email: user.email ?? '' }),
+  toPatch: (changes) => changes,
+  onSaved: async (user) => {
+    // Set/invalidate the app's profile query keys using the saved response.
+    // Navigate only after those writes complete.
+  },
+})
+<form {...profile.formProps}>
+  <input {...profile.register('name')} />
+  <input {...profile.register('email', { email: true })} type="email" />
+  <button type="submit" disabled={!profile.ready || profile.isSubmitting}>Save</button>
+</form>
+```
+
 ```tsx
 import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
 import { provider as stateProvider } from '@molecule/app-state-zustand'
@@ -215,6 +241,9 @@ 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.
      */
     updateProfile(data: Partial<T>): Promise<T>;
     /**
@@ -281,8 +310,6 @@ interface AuthClient<T = UserProfile, TRegister extends RegisterExtraShape<TRegi
      * HTTP client bonded to that provider sends first-paint requests unauthenticated.
      *
      * A provider whose restore sends a request THROUGH the gated HTTP client must send that
-     * request with `skipAuthGate: true` (`RequestConfig` in `@molecule/app-http`): the gate
-     * waits on this promise, so holding the restore's own request makes the gate wait on
 // … truncated — the full declaration is in node_modules/@molecule/app-react/dist
 ```
 
@@ -940,6 +967,71 @@ interface UsePlatformResult {
 }
 ```
 
+#### `UseProfileFormOptions`
+
+Configuration for a profile form; transport stays in the auth bond.
+
+```typescript
+interface UseProfileFormOptions<TUser, TValues extends Record<string, unknown>> extends Omit<
+  UseFormOptions<TValues>,
+  'defaultValues'
+> {
+  /** Complete controlled-field defaults, including blank write-only fields. */
+  defaultValues: TValues
+  /** Stable account identity; changing accounts discards the previous account's edits. */
+  getIdentity: (user: TUser) => string
+  /** Maps the current/saved user into controlled values, e.g. nullable text to ''. */
+  toValues: (user: TUser) => TValues
+  /**
+   * Maps ONLY changed fields into an API patch. Omit blank optional credentials
+   * here; preserve undefined/absent fields rather than turning them into null.
+   * The second argument is the complete value snapshot taken at submit time.
+   */
+  toPatch: (changes: Partial<TValues>, values: Readonly<TValues>) => Partial<TUser>
+  /**
+   * Propagates the server's saved user to other caches, then navigates if needed.
+   * Awaited before submission finishes. The auth client already persists and
+   * publishes the saved user; never seed caches from the submitted patch.
+   */
+  onSaved?: (user: TUser) => void | Promise<void>
+}
+```
+
+#### `UseProfileFormResult`
+
+Controlled profile form state and native form bindings.
+
+```typescript
+interface UseProfileFormResult<TUser, TValues extends Record<string, unknown>> extends Omit<
+  UseFormResult<TValues>,
+  'register' | 'handleSubmit' | 'reset'
+> {
+  /** The shared auth user's current profile. */
+  user: TUser | null
+  /** A user has been loaded; disable submission until this is true. */
+  ready: boolean
+  /**
+   * The latest save/propagation failure. Rejected saves retain edits; a failed
+   * onSaved callback can be retried by submit without repeating the mutation.
+   */
+  error: unknown
+  /** Native input/textarea bindings with the field's concrete value type. */
+  register: <K extends keyof TValues>(
+    name: K,
+    options?: Parameters<UseFormResult<TValues>['register']>[1],
+  ) => Omit<FieldRegistration, 'value'> & { value: TValues[K] }
+  /** Bind to the native form, with a type="submit" button inside it. */
+  formProps: { onSubmit: (event: React.FormEvent<HTMLFormElement>) => void }
+  /**
+   * Validates and saves one submit-time snapshot. Concurrent submits share the
+   * same promise. Resolves undefined on validation, save or propagation failure.
+   */
+  submit: () => Promise<TUser | undefined>
+  /** Discards edits and restores the newest loaded/saved profile baseline. */
+  reset: () => void
+}
+```
+
 #### `UsePromiseState`
 
 Extended promise state with actions.
@@ -2239,6 +2331,27 @@ function usePreview(): UsePreviewResult
 
 **Returns:** Preview state and controls: state (url, isLoading, device, error, isConnected), setUrl, refresh, setDevice, and openExternal.
 
+#### `useProfileForm(options)`
+
+Owns load → edit → submit → publish for the signed-in user's profile.
+
+Same-account background updates refresh untouched fields but preserve dirty
+controls. Submission snapshots the registered values before asynchronous
+validation, sends only changed fields through `toPatch`, and uses the auth
+client's configured updateProfile transport. The saved server response becomes
+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(
+  options: UseProfileFormOptions<TUser, TValues>,
+): UseProfileFormResult<TUser, TValues>
+```
+
+- `options` — Controlled defaults, identity and wire adapters, optional cache/navigation callback.
+
+**Returns:** Form state, typed control bindings, native submit binding and save error.
+
 #### `usePromise(asyncFn)`
 
 Hook that wraps an async function with state tracking.
@@ -3028,6 +3141,23 @@ Peer dependencies:
 - `@molecule/app-version`
 - `react`
 
+- `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
+  `''` there. Add optional write-only controls such as `password: ''` to both,
+  then omit a blank password in `toPatch`: `({ password, ...changes }) =>
+({ ...changes, ...(password?.trim() ? { password } : {}) })`. `changes`
+  contains only edited fields, so do not fill omitted fields with null or
+  copy every property of the auth user into the request. `reset()` discards
+  edits to the newest baseline. A changed `getIdentity(user)` clears the old
+  account's edits. Field comparisons are shallow, matching form providers.
+  A submission whose account or auth client changes, or whose form unmounts,
+  during asynchronous validation is discarded before any mutation or saved
+  callback. Same-account background hydration does not discard the submit.
+  The hook captures save failures in `error`; render that error with the
+  app's normal API-error presentation. Use native `<form>` submit semantics,
+  and pass the typed `register()` props through custom controls to their
+  actual input/textarea elements.
 - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
   services you pass as props — it is a convenience wrapper, not a default registry. The map:
   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,

package/dist/hooks/useProfileForm.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Profile editing over the app's bonded form and auth clients.
+ *
+ * @module
+ */
+import type { FieldRegistration } from '@molecule/app-forms';
+import { type UseFormOptions, type UseFormResult } from './useForm.js';
+/** Configuration for a profile form; transport stays in the auth bond. */
+export interface UseProfileFormOptions<TUser, TValues extends Record<string, unknown>> extends Omit<UseFormOptions<TValues>, 'defaultValues'> {
+    /** Complete controlled-field defaults, including blank write-only fields. */
+    defaultValues: TValues;
+    /** Stable account identity; changing accounts discards the previous account's edits. */
+    getIdentity: (user: TUser) => string;
+    /** Maps the current/saved user into controlled values, e.g. nullable text to ''. */
+    toValues: (user: TUser) => TValues;
+    /**
+     * Maps ONLY changed fields into an API patch. Omit blank optional credentials
+     * here; preserve undefined/absent fields rather than turning them into null.
+     * The second argument is the complete value snapshot taken at submit time.
+     */
+    toPatch: (changes: Partial<TValues>, values: Readonly<TValues>) => Partial<TUser>;
+    /**
+     * Propagates the server's saved user to other caches, then navigates if needed.
+     * Awaited before submission finishes. The auth client already persists and
+     * publishes the saved user; never seed caches from the submitted patch.
+     */
+    onSaved?: (user: TUser) => void | Promise<void>;
+}
+/** Controlled profile form state and native form bindings. */
+export interface UseProfileFormResult<TUser, TValues extends Record<string, unknown>> extends Omit<UseFormResult<TValues>, 'register' | 'handleSubmit' | 'reset'> {
+    /** The shared auth user's current profile. */
+    user: TUser | null;
+    /** A user has been loaded; disable submission until this is true. */
+    ready: boolean;
+    /**
+     * The latest save/propagation failure. Rejected saves retain edits; a failed
+     * onSaved callback can be retried by submit without repeating the mutation.
+     */
+    error: unknown;
+    /** Native input/textarea bindings with the field's concrete value type. */
+    register: <K extends keyof TValues>(name: K, options?: Parameters<UseFormResult<TValues>['register']>[1]) => Omit<FieldRegistration, 'value'> & {
+        value: TValues[K];
+    };
+    /** Bind to the native form, with a type="submit" button inside it. */
+    formProps: {
+        onSubmit: (event: React.FormEvent<HTMLFormElement>) => void;
+    };
+    /**
+     * Validates and saves one submit-time snapshot. Concurrent submits share the
+     * same promise. Resolves undefined on validation, save or propagation failure.
+     */
+    submit: () => Promise<TUser | undefined>;
+    /** Discards edits and restores the newest loaded/saved profile baseline. */
+    reset: () => void;
+}
+/**
+ * Owns load → edit → submit → publish for the signed-in user's profile.
+ *
+ * Same-account background updates refresh untouched fields but preserve dirty
+ * controls. Submission snapshots the registered values before asynchronous
+ * validation, sends only changed fields through `toPatch`, and uses the auth
+ * client's configured updateProfile transport. The saved server response becomes
+ * 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.
+ *
+ * @param options - Controlled defaults, identity and wire adapters, optional cache/navigation callback.
+ * @returns Form state, typed control bindings, native submit binding and save error.
+ */
+export declare function useProfileForm<TUser, TValues extends Record<string, unknown>>(options: UseProfileFormOptions<TUser, TValues>): UseProfileFormResult<TUser, TValues>;
+//# sourceMappingURL=useProfileForm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useProfileForm.d.ts","sourceRoot":"","sources":["../../src/hooks/useProfileForm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAG5D,OAAO,EAAW,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAE/E,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,IAAI,CACjG,cAAc,CAAC,OAAO,CAAC,EACvB,eAAe,CAChB;IACC,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAA;IACtB,wFAAwF;IACxF,WAAW,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAA;IACpC,oFAAoF;IACpF,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAA;IAClC;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;IACjF;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChD;AAED,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,IAAI,CAChG,aAAa,CAAC,OAAO,CAAC,EACtB,UAAU,GAAG,cAAc,GAAG,OAAO,CACtC;IACC,8CAA8C;IAC9C,IAAI,EAAE,KAAK,GAAG,IAAI,CAAA;IAClB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAA;IACd,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAChC,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,KACxD,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,CAAA;IAC7D,sEAAsE;IACtE,SAAS,EAAE;QAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,eAAe,CAAC,KAAK,IAAI,CAAA;KAAE,CAAA;IAC1E;;;OAGG;IACH,MAAM,EAAE,MAAM,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAA;IACxC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,OAAO,EAAE,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,GAC7C,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAsLtC"}

package/dist/hooks/useProfileForm.js

@@ -0,0 +1,188 @@
+/**
+ * Profile editing over the app's bonded form and auth clients.
+ *
+ * @module
+ */
+import { useCallback, useInsertionEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useAuth, useAuthClient } from './useAuth.js';
+import { useForm } from './useForm.js';
+/**
+ * Owns load → edit → submit → publish for the signed-in user's profile.
+ *
+ * Same-account background updates refresh untouched fields but preserve dirty
+ * controls. Submission snapshots the registered values before asynchronous
+ * validation, sends only changed fields through `toPatch`, and uses the auth
+ * client's configured updateProfile transport. The saved server response becomes
+ * 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.
+ *
+ * @param options - Controlled defaults, identity and wire adapters, optional cache/navigation callback.
+ * @returns Form state, typed control bindings, native submit binding and save error.
+ */
+export function useProfileForm(options) {
+    const { defaultValues, getIdentity: _identity, toValues: _values, toPatch: _patch, onSaved: _saved, ...formOptions } = options;
+    const form = useForm({ ...formOptions, defaultValues });
+    const client = useAuthClient();
+    const { user } = useAuth();
+    const [error, setError] = useState();
+    const [isSaving, setIsSaving] = useState(false);
+    const optionsRef = useRef(options);
+    const committedClient = useRef(client);
+    const baseline = useRef({ ...defaultValues });
+    const owner = useRef(null);
+    const activeSave = useRef(null);
+    const pendingPropagation = useRef(undefined);
+    const mounted = useRef(false);
+    // Actions use committed configuration, never an abandoned concurrent render.
+    useInsertionEffect(() => {
+        optionsRef.current = options;
+        committedClient.current = client;
+    }, [options, client]);
+    useLayoutEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const readValues = useCallback(() => {
+        const values = { ...baseline.current };
+        for (const key of Object.keys(values))
+            values[key] = form.getValue(key);
+        return values;
+    }, [form.getValue]);
+    const rebase = useCallback((next, preserveAgainst) => {
+        const current = readValues();
+        baseline.current = { ...next };
+        form.reset(next);
+        if (preserveAgainst) {
+            for (const key of Object.keys(current)) {
+                if (!Object.is(current[key], preserveAgainst[key]))
+                    form.setValue(key, current[key]);
+            }
+        }
+    }, [readValues, form.reset, form.setValue]);
+    useLayoutEffect(() => {
+        const config = optionsRef.current;
+        if (!user) {
+            if (owner.current) {
+                owner.current = null;
+                pendingPropagation.current = undefined;
+                rebase({ ...config.defaultValues });
+                setError(undefined);
+            }
+            return;
+        }
+        const identity = config.getIdentity(user);
+        const previous = owner.current;
+        const sameAccount = !previous || (previous.client === client && previous.identity === identity);
+        const previousBaseline = baseline.current;
+        // Keep this token across same-account hydration, but replace it when the
+        // account/client changes. A pending validation belongs to that exact owner.
+        if (!previous || !sameAccount)
+            owner.current = { client, identity };
+        rebase(config.toValues(user), sameAccount ? previousBaseline : undefined);
+        if (!sameAccount) {
+            pendingPropagation.current = undefined;
+            setError(undefined);
+        }
+    }, [user, client, rebase]);
+    const submit = useCallback(() => {
+        if (activeSave.current)
+            return activeSave.current;
+        const currentUser = client.getUser();
+        if (!mounted.current || !currentUser)
+            return Promise.resolve(undefined);
+        const config = optionsRef.current;
+        const identity = config.getIdentity(currentUser);
+        const submissionOwner = owner.current;
+        const ownsProfile = () => {
+            const current = client.getUser();
+            return (mounted.current &&
+                committedClient.current === client &&
+                owner.current === submissionOwner &&
+                current !== null &&
+                config.getIdentity(current) === identity);
+        };
+        const snapshot = readValues();
+        const before = { ...baseline.current };
+        const changes = {};
+        for (const key of Object.keys(snapshot)) {
+            if (!Object.is(snapshot[key], before[key]))
+                changes[key] = snapshot[key];
+        }
+        setError(undefined);
+        setIsSaving(true);
+        let saved;
+        const run = async () => {
+            try {
+                await form.handleSubmit(async () => {
+                    // Validation can await arbitrary app work. Check BEFORE toPatch and
+                    // again immediately before the mutation: its credentials are read by
+                    // updateProfile now, not when the reader originally clicked Save.
+                    if (!ownsProfile())
+                        return;
+                    const patch = config.toPatch(changes, snapshot);
+                    if (Object.keys(patch).length > 0) {
+                        if (!ownsProfile())
+                            return;
+                        saved = await client.updateProfile(patch);
+                        if (!ownsProfile()) {
+                            saved = undefined;
+                            return;
+                        }
+                        if (mounted.current)
+                            rebase(config.toValues(saved), snapshot);
+                        pendingPropagation.current = saved;
+                    }
+                    if (pendingPropagation.current !== undefined) {
+                        if (!ownsProfile()) {
+                            saved = undefined;
+                            return;
+                        }
+                        const propagated = pendingPropagation.current;
+                        await config.onSaved?.(propagated);
+                        pendingPropagation.current = undefined;
+                        saved = propagated;
+                    }
+                })();
+                return saved;
+            }
+            catch (failure) {
+                if (mounted.current)
+                    setError(failure);
+                return undefined;
+            }
+            finally {
+                activeSave.current = null;
+                if (mounted.current)
+                    setIsSaving(false);
+            }
+        };
+        activeSave.current = run();
+        return activeSave.current;
+    }, [client, readValues, form.handleSubmit, rebase]);
+    const register = useCallback((name, registerOptions) => {
+        return form.register(name, registerOptions);
+    }, [form.register]);
+    const reset = useCallback(() => {
+        form.reset(baseline.current);
+        setError(undefined);
+    }, [form.reset]);
+    const onSubmit = useCallback((event) => {
+        event.preventDefault();
+        void submit();
+    }, [submit]);
+    return {
+        ...form,
+        formState: { ...form.formState, isSubmitting: isSaving || form.isSubmitting },
+        isSubmitting: isSaving || form.isSubmitting,
+        user,
+        ready: user !== null,
+        error,
+        register,
+        reset,
+        submit,
+        formProps: { onSubmit },
+    };
+}
+//# sourceMappingURL=useProfileForm.js.map

package/dist/hooks/useProfileForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useProfileForm.js","sourceRoot":"","sources":["../../src/hooks/useProfileForm.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -6,6 +6,33 @@
  * chat, workspace, editor, preview), so framework-agnostic providers plug
  * into React idioms.
  *
+ * **Editable account/profile forms:** `useProfileForm` composes the bonded form
+ * and auth clients. It hydrates asynchronous user data without erasing dirty
+ * fields, snapshots controlled values on native form submission, submits only
+ * changed fields through an app-supplied adapter, and persists/publishes the
+ * server's saved user. Use its `onSaved` callback to update other query caches
+ * from that response before navigating. Configure the endpoint, method and JSON
+ * envelope once in `AuthClientConfig`; no page-local session store is needed.
+ *
+ * @example
+ * ```tsx
+ * const profile = useProfileForm<User, { name: string; email: string }>({
+ *   defaultValues: { name: '', email: '' },
+ *   getIdentity: (user) => user.id,
+ *   toValues: (user) => ({ name: user.name ?? '', email: user.email ?? '' }),
+ *   toPatch: (changes) => changes,
+ *   onSaved: async (user) => {
+ *     // Set/invalidate the app's profile query keys using the saved response.
+ *     // Navigate only after those writes complete.
+ *   },
+ * })
+ * <form {...profile.formProps}>
+ *   <input {...profile.register('name')} />
+ *   <input {...profile.register('email', { email: true })} type="email" />
+ *   <button type="submit" disabled={!profile.ready || profile.isSubmitting}>Save</button>
+ * </form>
+ * ```
+ *
  * @example
  * ```tsx
  * import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
@@ -48,6 +75,23 @@
  * ```
  *
  * @remarks
+ * - `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
+ *   `''` there. Add optional write-only controls such as `password: ''` to both,
+ *   then omit a blank password in `toPatch`: `({ password, ...changes }) =>
+ *   ({ ...changes, ...(password?.trim() ? { password } : {}) })`. `changes`
+ *   contains only edited fields, so do not fill omitted fields with null or
+ *   copy every property of the auth user into the request. `reset()` discards
+ *   edits to the newest baseline. A changed `getIdentity(user)` clears the old
+ *   account's edits. Field comparisons are shallow, matching form providers.
+ *   A submission whose account or auth client changes, or whose form unmounts,
+ *   during asynchronous validation is discarded before any mutation or saved
+ *   callback. Same-account background hydration does not discard the submit.
+ *   The hook captures save failures in `error`; render that error with the
+ *   app's normal API-error presentation. Use native `<form>` submit semantics,
+ *   and pass the typed `register()` props through custom controls to their
+ *   actual input/textarea elements.
  * - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
  *   services you pass as props — it is a convenience wrapper, not a default registry. The map:
  *   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,
@@ -104,6 +148,7 @@
 export * from './agent-identity.js';
 export * from './contexts.js';
 export * from './hooks/index.js';
+export * from './hooks/useProfileForm.js';
 export * from './providers.js';
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -6,6 +6,33 @@
  * chat, workspace, editor, preview), so framework-agnostic providers plug
  * into React idioms.
  *
+ * **Editable account/profile forms:** `useProfileForm` composes the bonded form
+ * and auth clients. It hydrates asynchronous user data without erasing dirty
+ * fields, snapshots controlled values on native form submission, submits only
+ * changed fields through an app-supplied adapter, and persists/publishes the
+ * server's saved user. Use its `onSaved` callback to update other query caches
+ * from that response before navigating. Configure the endpoint, method and JSON
+ * envelope once in `AuthClientConfig`; no page-local session store is needed.
+ *
+ * @example
+ * ```tsx
+ * const profile = useProfileForm<User, { name: string; email: string }>({
+ *   defaultValues: { name: '', email: '' },
+ *   getIdentity: (user) => user.id,
+ *   toValues: (user) => ({ name: user.name ?? '', email: user.email ?? '' }),
+ *   toPatch: (changes) => changes,
+ *   onSaved: async (user) => {
+ *     // Set/invalidate the app's profile query keys using the saved response.
+ *     // Navigate only after those writes complete.
+ *   },
+ * })
+ * <form {...profile.formProps}>
+ *   <input {...profile.register('name')} />
+ *   <input {...profile.register('email', { email: true })} type="email" />
+ *   <button type="submit" disabled={!profile.ready || profile.isSubmitting}>Save</button>
+ * </form>
+ * ```
+ *
  * @example
  * ```tsx
  * import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
@@ -48,6 +75,23 @@
  * ```
  *
  * @remarks
+ * - `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
+ *   `''` there. Add optional write-only controls such as `password: ''` to both,
+ *   then omit a blank password in `toPatch`: `({ password, ...changes }) =>
+ *   ({ ...changes, ...(password?.trim() ? { password } : {}) })`. `changes`
+ *   contains only edited fields, so do not fill omitted fields with null or
+ *   copy every property of the auth user into the request. `reset()` discards
+ *   edits to the newest baseline. A changed `getIdentity(user)` clears the old
+ *   account's edits. Field comparisons are shallow, matching form providers.
+ *   A submission whose account or auth client changes, or whose form unmounts,
+ *   during asynchronous validation is discarded before any mutation or saved
+ *   callback. Same-account background hydration does not discard the submit.
+ *   The hook captures save failures in `error`; render that error with the
+ *   app's normal API-error presentation. Use native `<form>` submit semantics,
+ *   and pass the typed `register()` props through custom controls to their
+ *   actual input/textarea elements.
  * - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
  *   services you pass as props — it is a convenience wrapper, not a default registry. The map:
  *   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,
@@ -104,6 +148,7 @@
 export * from './agent-identity.js';
 export * from './contexts.js';
 export * from './hooks/index.js';
+export * from './hooks/useProfileForm.js';
 export * from './providers.js';
 export * from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-react",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "React framework bindings for molecule.dev",
   "type": "module",
   "main": "dist/index.js",