@molecule/app-angular 2.0.1 → 3.1.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-26T04:14:37.536Z
+Generated: 2026-10-31T13:49:31.073Z
 -->
 
 # @molecule/app-angular
@@ -94,7 +94,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
   /**
@@ -102,11 +105,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
   /**
@@ -160,12 +166,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;
     /**
@@ -180,10 +197,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;
     /**
@@ -208,7 +228,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>;
     /**
@@ -260,37 +289,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-angular/dist
 ```
 
@@ -301,7 +299,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.
    */
@@ -379,9 +377,20 @@ interface FormController<T extends Record<string, unknown> = 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.
    */
@@ -409,12 +418,20 @@ 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.
    */
   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.
    */
@@ -1067,6 +1084,31 @@ interface StorageProvider {
    * Removes multiple values from storage.
    */
   removeMany?(keys: string[]): Promise<void>
+  /**
+   * Reads a value synchronously.
+   *
+   * Optional: only a provider backed by a SYNCHRONOUS store (browser
+   * `localStorage`, an in-memory map) can answer without I/O. A render-time
+   * caller reads through `getPreferenceStore()`, which uses this method to see
+   * the persisted value on the first paint; a provider without it is read
+   * through {@link StorageProvider.get} and subscribers update when the value
+   * lands.
+   * @param key - The storage key.
+   * @returns The stored value, or `null` when it is absent, unreadable or corrupt.
+   */
+  getSync?<T = unknown>(key: string): T | null
+  /**
+   * Subscribes to changes made to a key OUTSIDE this provider instance — for
+   * example another browser tab's `localStorage` write.
+   *
+   * Writes made through the same provider instance do not re-emit here; a
+   * synchronous caller observes them through `getPreferenceStore()`'s own
+   * subscribers.
+   * @param key - The storage key.
+   * @param listener - Called with the new value, or `null` when it was removed.
+   * @returns A function that stops the subscription.
+   */
+  subscribe?(key: string, listener: (value: unknown) => void): () => void
 }
 ```
 
@@ -1605,7 +1647,7 @@ Wrapper around a FormController that provides RxJS observables and
 synchronous accessors for use in Angular components.
 
 ```typescript
-class MoleculeFormInstance<T extends Record<string, unknown>> {
+class MoleculeFormInstance<T extends FormValuesConstraint<T>> {
   private stateSubject: BehaviorSubject<FormState<T>>
   private unsubscribe: (() => void) | null = null
 
@@ -1637,9 +1679,9 @@ class MoleculeFormInstance<T extends Record<string, unknown>> {
   constructor(private controller: FormController<T>) {
     this.stateSubject = new BehaviorSubject<FormState<T>>(controller.getState())
 
-    this.unsubscribe = controller.subscribe((state: FormState<T>) => {
-      this.stateSubject.next(state)
-    })
+    const refresh = (): void => this.stateSubject.next(controller.getState())
+    this.unsubscribe = controller.subscribe(refresh)
+    refresh()
 
     this.state$ = this.stateSubject.asObservable()
 
@@ -1775,6 +1817,16 @@ class MoleculeFormInstance<T extends Record<string, unknown>> {
     return this.controller.handleSubmit(onSubmit, onError)
   }
 
+  /**
+   * Apply a newly loaded record without clearing submission state.
+   *
+   * @param values - The newly loaded record.
+   * @param resetOptions - Set `keepDirtyValues` to retain edits and fill pristine fields.
+   */
+  updateValues(values: Partial<T>, resetOptions: FormResetOptions = {}): void {
+    this.controller.updateValues(values, resetOptions)
+  }
+
   /**
    * Reset the form to initial values.
    *
@@ -1823,12 +1875,15 @@ export class MoleculeFormsService implements OnDestroy {
    * Create a form instance from a provider.
    *
    * @param provider - The form provider that creates form controllers.
-   * @param options - Form configuration including default values and validation mode.
-   * @returns A new form instance with RxJS observables for reactive state tracking.
+   * @param options - Narrowed `FormOptions` without `values` or `resetOptions`;
+   * includes default values and validation mode.
+   * @returns A new form instance with RxJS observables and explicit
+   * `updateValues(values, { keepDirtyValues })` delivery. The option defaults to
+   * false; pass true to retain edited fields while pristine fields take the record.
    */
-  createForm<T extends Record<string, unknown>>(
+  createForm<T extends FormValuesConstraint<T>>(
     provider: FormProvider,
-    options: FormOptions<T>,
+    options: AngularFormOptions<T>,
   ): MoleculeFormInstance<T> {
     const controller = provider.createForm(options)
     const instance = new MoleculeFormInstance<T>(controller)
@@ -3032,7 +3087,7 @@ Peer dependencies:
 - `@angular/core` 22.0.0
 - `@molecule/app-auth` ^3.0.0
 - `@molecule/app-device` ^1.0.1
-- `@molecule/app-forms` ^1.0.1
+- `@molecule/app-forms` ^2.0.0
 - `@molecule/app-http` ^1.0.1
 - `@molecule/app-i18n` ^1.0.1
 - `@molecule/app-logger` ^1.0.1

package/dist/services/forms.service.d.ts

@@ -5,8 +5,16 @@
  */
 import { type OnDestroy } from '@angular/core';
 import { type Observable } from 'rxjs';
-import type { FieldRegistration, FormController, FormOptions, FormProvider, FormState, RegisterOptions } from '@molecule/app-forms';
+import type { FieldRegistration, FormController, FormOptions, FormProvider, FormResetOptions, FormState, FormValuesConstraint, RegisterOptions } from '@molecule/app-forms';
 import * as i0 from "@angular/core";
+/**
+ * Angular form creation options. Unlike `FormOptions`, this narrowed type does
+ * not accept `values` or `resetOptions`: signal-backed getters are not observed.
+ * Deliver records after creation through the returned instance's
+ * `updateValues(values, { keepDirtyValues })` method. The option defaults to
+ * false; pass true to retain edited fields while pristine fields take the record.
+ */
+type AngularFormOptions<T extends FormValuesConstraint<T>> = Omit<FormOptions<T>, 'values' | 'resetOptions'>;
 /**
  * Wrapper around a FormController that provides RxJS observables and
  * synchronous accessors for use in Angular components.
@@ -55,7 +63,7 @@ import * as i0 from "@angular/core";
  * }
  * ```
  */
-export declare class MoleculeFormInstance<T extends Record<string, unknown>> {
+export declare class MoleculeFormInstance<T extends FormValuesConstraint<T>> {
     private controller;
     private stateSubject;
     private unsubscribe;
@@ -150,6 +158,13 @@ export declare class MoleculeFormInstance<T extends Record<string, unknown>> {
     handleSubmit(onSubmit: (values: T) => void | Promise<void>, onError?: (errors: Partial<Record<keyof T, string>>) => void): (event?: {
         preventDefault?: () => void;
     }) => Promise<void>;
+    /**
+     * Apply a newly loaded record without clearing submission state.
+     *
+     * @param values - The newly loaded record.
+     * @param resetOptions - Set `keepDirtyValues` to retain edits and fill pristine fields.
+     */
+    updateValues(values: Partial<T>, resetOptions?: FormResetOptions): void;
     /**
      * Reset the form to initial values.
      *
@@ -223,10 +238,13 @@ export declare class MoleculeFormsService implements OnDestroy {
      * Create a form instance from a provider.
      *
      * @param provider - The form provider that creates form controllers.
-     * @param options - Form configuration including default values and validation mode.
-     * @returns A new form instance with RxJS observables for reactive state tracking.
+     * @param options - Narrowed `FormOptions` without `values` or `resetOptions`;
+     * includes default values and validation mode.
+     * @returns A new form instance with RxJS observables and explicit
+     * `updateValues(values, { keepDirtyValues })` delivery. The option defaults to
+     * false; pass true to retain edited fields while pristine fields take the record.
      */
-    createForm<T extends Record<string, unknown>>(provider: FormProvider, options: FormOptions<T>): MoleculeFormInstance<T>;
+    createForm<T extends FormValuesConstraint<T>>(provider: FormProvider, options: AngularFormOptions<T>): MoleculeFormInstance<T>;
     /**
      * Destroy all managed form instances on service destruction.
      */
@@ -234,4 +252,5 @@ export declare class MoleculeFormsService implements OnDestroy {
     static ɵfac: i0.ɵɵFactoryDeclaration<MoleculeFormsService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<any>;
 }
+export {};
 //# sourceMappingURL=forms.service.d.ts.map

package/dist/services/forms.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forms.service.d.ts","sourceRoot":"","sources":["../../src/services/forms.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"forms.service.d.ts","sourceRoot":"","sources":["../../src/services/forms.service.ts"],"names":[],"mappings":"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"}

package/dist/services/forms.service.js

@@ -59,9 +59,9 @@ export class MoleculeFormInstance {
         this.controller = controller;
         this.unsubscribe = null;
         this.stateSubject = new BehaviorSubject(controller.getState());
-        this.unsubscribe = controller.subscribe((state) => {
-            this.stateSubject.next(state);
-        });
+        const refresh = () => this.stateSubject.next(controller.getState());
+        this.unsubscribe = controller.subscribe(refresh);
+        refresh();
         this.state$ = this.stateSubject.asObservable();
         this.isValid$ = this.state$.pipe(map((state) => state.isValid), distinctUntilChanged());
         this.isDirty$ = this.state$.pipe(map((state) => state.isDirty), distinctUntilChanged());
@@ -166,6 +166,15 @@ export class MoleculeFormInstance {
     handleSubmit(onSubmit, onError) {
         return this.controller.handleSubmit(onSubmit, onError);
     }
+    /**
+     * Apply a newly loaded record without clearing submission state.
+     *
+     * @param values - The newly loaded record.
+     * @param resetOptions - Set `keepDirtyValues` to retain edits and fill pristine fields.
+     */
+    updateValues(values, resetOptions = {}) {
+        this.controller.updateValues(values, resetOptions);
+    }
     /**
      * Reset the form to initial values.
      *
@@ -250,8 +259,11 @@ export class MoleculeFormsService {
      * Create a form instance from a provider.
      *
      * @param provider - The form provider that creates form controllers.
-     * @param options - Form configuration including default values and validation mode.
-     * @returns A new form instance with RxJS observables for reactive state tracking.
+     * @param options - Narrowed `FormOptions` without `values` or `resetOptions`;
+     * includes default values and validation mode.
+     * @returns A new form instance with RxJS observables and explicit
+     * `updateValues(values, { keepDirtyValues })` delivery. The option defaults to
+     * false; pass true to retain edited fields while pristine fields take the record.
      */
     createForm(provider, options) {
         const controller = provider.createForm(options);

package/dist/services/forms.service.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/app-angular",
-  "version": "2.0.1",
+  "version": "3.1.0",
   "description": "Angular framework bindings for molecule.dev",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
     "@angular/core": "22.0.0",
     "@molecule/app-auth": "^3.0.0",
     "@molecule/app-device": "^1.0.1",
-    "@molecule/app-forms": "^1.0.1",
+    "@molecule/app-forms": "^2.0.0",
     "@molecule/app-http": "^1.0.1",
     "@molecule/app-i18n": "^1.0.1",
     "@molecule/app-logger": "^1.0.1",