@base-framework/base 3.7.76 → 3.7.78

package/dist/types/modules/component/component.d.ts

@@ -64,13 +64,9 @@ export class Component extends Unit {
     /**
      * This will resume the data during persistence.
      *
-     * For components with externally-provided data (temp components
-     * created by { data: localVar } in layouts), we use the fresh
-     * data instance from setData() so closure references stay valid.
-     *
-     * For regular components, the persisted data is the source of
-     * truth — it holds accumulated state (list items, filters, etc.)
-     * that should be preserved until the component fetches updates.
+     * Delegates to DataResumeHelper which owns the fresh-vs-persisted
+     * reconciliation, retain/refresh-state policy, silent stage writes,
+     * and stale-publish queue draining.
      *
      * @protected
      * @param {Data|null} persistedData

package/dist/types/modules/component/data-resume-helper.d.ts

@@ -0,0 +1,125 @@
+/** @typedef {import('../data/data.js').Data} Data */
+/**
+ * DataResumeHelper
+ *
+ * Owns the data-merge logic used when a persisted component is
+ * resumed (e.g. when the router re-activates a cached route).
+ *
+ * The component delegates here so its own surface stays focused
+ * on lifecycle, leaving all of the
+ *   - fresh-vs-persisted reconciliation,
+ *   - retain/refresh-state policy,
+ *   - silent stage writes, and
+ *   - batched-publish queue draining
+ * in one auditable place.
+ *
+ * @class
+ */
+export class DataResumeHelper {
+    /**
+     * This will resume the data for a component during persistence.
+     *
+     * @param {object} component - host component (mutated: component.data is set)
+     * @param {Data|null} persistedData
+     * @returns {void}
+     */
+    static resume(component: object, persistedData: Data | null): void;
+    /**
+     * Refresh the host component's data with fresh prop-derived
+     * values from setData(), then refresh context data from parent.
+     *
+     * @param {object} component
+     * @returns {void}
+     */
+    static refresh(component: object): void;
+    /**
+     * Push parent-context changes into the persisted context data.
+     * Only reference-changed keys are written, via the silent API,
+     * to avoid republishing the entire context tree on resume.
+     *
+     * @param {object} component
+     * @returns {void}
+     */
+    static refreshContext(component: object): void;
+    /**
+     * Resume path for temp components created by
+     * `{ data: localVar }` in layouts.
+     *
+     * The fresh data instance must win as the *reference*
+     * so closures in the parent atom still point at the
+     * same Data object, but the persisted *values* are the
+     * source of truth (the user's prior interactions —
+     * activeFilter, scroll position, etc.). Merging the
+     * persisted stage onto the fresh instance preserves
+     * both.
+     *
+     * Policy matches `_resumeOwned`:
+     *  - retainState: persisted wins for ALL keys (incl. null).
+     *  - refreshState: fresh wins; only persisted keys missing
+     *    from fresh are copied.
+     *  - default: persisted non-null values win on changed keys;
+     *    null/undefined persisted values are ignored so fresh
+     *    defaults stay and async refetches can repopulate.
+     *
+     * @protected
+     * @param {object} component
+     * @param {Data|null} persistedData
+     * @returns {void}
+     */
+    protected static _resumeExternal(component: object, persistedData: Data | null): void;
+    /**
+     * Diff persisted stage against fresh stage for external data.
+     *
+     * - retain=true: persisted values win for every key.
+     * - refresh=true: only persisted keys missing from fresh are
+     *   copied (so async-added properties survive).
+     * - default: persisted non-null values win on changed keys;
+     *   null/undefined persisted values are ignored.
+     *
+     * Reference-equal values are skipped to avoid the deep
+     * Publisher.publish cascade on unchanged subtrees.
+     *
+     * @protected
+     * @param {object} old
+     * @param {object} freshStage
+     * @param {boolean} retain
+     * @param {boolean} refresh
+     * @returns {Object<string, *>}
+     */
+    protected static _buildExternalUpdates(old: object, freshStage: object, retain: boolean, refresh: boolean): {
+        [x: string]: any;
+    };
+    /**
+     * Resume path for regular components: fresh data from
+     * setData() (already in component.data via _setupData)
+     * is the base; persisted values are merged in silently
+     * unless retainState is flagged (then persisted wins
+     * outright) or refreshState is flagged (then only keys
+     * missing from fresh are copied).
+     *
+     * @protected
+     * @param {object} component
+     * @param {Data|null} persistedData
+     * @returns {void}
+     */
+    protected static _resumeOwned(component: object, persistedData: Data | null): void;
+    /**
+     * Diff persisted stage against the fresh owned-data stage.
+     *
+     * - refresh=true: fresh values are authoritative; only
+     *   persisted keys missing from fresh are copied.
+     * - refresh=false: persisted non-null values win on changed
+     *   keys; null/undefined are ignored so fresh defaults stay,
+     *   allowing the component to re-fetch on resume.
+     *
+     * @protected
+     * @param {object} old
+     * @param {object} currentStage
+     * @param {boolean} refresh
+     * @returns {Object<string, *>}
+     */
+    protected static _buildOwnedUpdates(old: object, currentStage: object, refresh: boolean): {
+        [x: string]: any;
+    };
+}
+export type Data = import("../data/data.js").Data;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@base-framework/base",
-	"version": "3.7.76",
+	"version": "3.7.78",
 	"description": "This is a javascript framework.",
 	"main": "./dist/base.js",
 	"type": "module",