@trackunit/react-components 3.5.3 → 3.5.4-alpha-cb9408e01a9.0

package/index.cjs.js

@@ -14126,6 +14126,12 @@ const rawLocalStorage = {
  * `toUrlValue` + encoding). Duplicate writes where the state has not
  * changed (deep equality) are skipped.
  *
+ * `commitHydratedState` writes the hydrated value to localStorage only,
+ * when it came from the URL and differs from what this identity has stored.
+ * It does not update the URL. It returns `false` while the snapshot is
+ * still for a previous read, so the caller can retry after identity
+ * resolution. The caller decides which identity is allowed to commit.
+ *
  * `clearState` removes the entry from localStorage and from the URL slot,
  * rather than writing an empty value. Use it when the state a consumer
  * derives has become empty, so no leftover entry is stored for a value the
@@ -14216,7 +14222,11 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             try {
                 const { value } = unwrapUrlOwner(decode(raw));
                 const transformed = transformFromUrlValue ? transformFromUrlValue(value) : value;
-                return validateState(transformed);
+                const state = validateState(transformed);
+                if (state === undefined) {
+                    return undefined;
+                }
+                return { state, payload: value };
             }
             catch {
                 return undefined;
@@ -14238,17 +14248,21 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             }
         };
         let urlState;
+        let decodedPayload;
         let canonicalUrlValid = false;
         let usedLegacyUrl = false;
         if (enabled && valueFromUrl) {
-            urlState = tryDecode(valueFromUrl);
-            if (urlState !== undefined) {
+            const decoded = tryDecode(valueFromUrl);
+            if (decoded !== undefined) {
+                urlState = decoded.state;
+                decodedPayload = decoded.payload;
                 canonicalUrlValid = true;
             }
         }
         if (urlState === undefined && enabled && legacyValueFromUrl) {
-            urlState = tryDecode(legacyValueFromUrl);
-            if (urlState !== undefined) {
+            const decoded = tryDecode(legacyValueFromUrl);
+            if (decoded !== undefined) {
+                urlState = decoded.state;
                 usedLegacyUrl = true;
             }
         }
@@ -14258,6 +14272,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
                 needsUrlRestore: usedLegacyUrl,
             };
         }
@@ -14268,6 +14283,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: { ...storageState, ...urlState },
                 canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
                 needsUrlRestore: usedLegacyUrl,
             };
         }
@@ -14275,6 +14291,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
                 needsUrlRestore: usedLegacyUrl,
             };
         }
@@ -14282,12 +14299,14 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: storageState,
                 canonicalUrlHasValidState: false,
+                canonicalUrlPayload: undefined,
                 needsUrlRestore: true,
             };
         }
         return {
             initialState: undefined,
             canonicalUrlHasValidState: false,
+            canonicalUrlPayload: undefined,
             needsUrlRestore: false,
         };
     }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
@@ -14297,27 +14316,33 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
         return encode(currentUrlOwner === undefined ? urlValue : wrapUrlOwner(urlValue, currentUrlOwner));
     }, [encode, currentUrlOwner]);
-    const [persistedStateSnapshot, setPersistedStateSnapshot] = react.useState(() => readPersistedState({
-        valueFromUrl: searchValue,
-        legacyValueFromUrl: legacySearchValue,
-        validateState: validate,
-        transformFromUrlValue: fromUrlValue,
-    }));
     const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${urlLocation}:${storageKey}`;
+    const [persistedStateSnapshot, setPersistedStateSnapshot] = react.useState(() => ({
+        ...readPersistedState({
+            valueFromUrl: searchValue,
+            legacyValueFromUrl: legacySearchValue,
+            validateState: validate,
+            transformFromUrlValue: fromUrlValue,
+        }),
+        readKey: persistedStateReadKey,
+    }));
     const persistedStateReadKeyRef = react.useRef(persistedStateReadKey);
     react.useEffect(() => {
         if (persistedStateReadKeyRef.current === persistedStateReadKey) {
             return;
         }
         persistedStateReadKeyRef.current = persistedStateReadKey;
-        setPersistedStateSnapshot(readPersistedState({
-            valueFromUrl: searchValueRef.current,
-            legacyValueFromUrl: legacySearchValueRef.current,
-            validateState: validateRef.current,
-            transformFromUrlValue: fromUrlValueRef.current,
-        }));
+        setPersistedStateSnapshot({
+            ...readPersistedState({
+                valueFromUrl: searchValueRef.current,
+                legacyValueFromUrl: legacySearchValueRef.current,
+                validateState: validateRef.current,
+                transformFromUrlValue: fromUrlValueRef.current,
+            }),
+            readKey: persistedStateReadKey,
+        });
     }, [persistedStateReadKey, readPersistedState]);
-    const { initialState, canonicalUrlHasValidState, needsUrlRestore } = persistedStateSnapshot;
+    const { initialState, canonicalUrlHasValidState, canonicalUrlPayload, needsUrlRestore } = persistedStateSnapshot;
     // Late-hydration recovery: TanStack Router's `useSearch` can return an
     // empty object on the very first render of a route that's still in a
     // loader-driven pending phase. The `useState` initializer above runs
@@ -14338,13 +14363,16 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         if (legacySearchValue === undefined) {
             return;
         }
-        setPersistedStateSnapshot(readPersistedState({
-            valueFromUrl: searchValueRef.current,
-            legacyValueFromUrl: legacySearchValue,
-            validateState: validateRef.current,
-            transformFromUrlValue: fromUrlValueRef.current,
-        }));
-    }, [legacySearchValue, initialState, canonicalUrlHasValidState, readPersistedState]);
+        setPersistedStateSnapshot({
+            ...readPersistedState({
+                valueFromUrl: searchValueRef.current,
+                legacyValueFromUrl: legacySearchValue,
+                validateState: validateRef.current,
+                transformFromUrlValue: fromUrlValueRef.current,
+            }),
+            readKey: persistedStateReadKey,
+        });
+    }, [legacySearchValue, initialState, canonicalUrlHasValidState, persistedStateReadKey, readPersistedState]);
     const lastPersistedRef = react.useRef(initialState);
     react.useEffect(() => {
         lastPersistedRef.current = initialState;
@@ -14414,7 +14442,52 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         }
         updateSearchParam(undefined);
     }, [localStorageEnabled, storageKey, updateSearchParam]);
-    return react.useMemo(() => ({ initialState, persistState, clearState }), [initialState, persistState, clearState]);
+    const snapshotIsCurrent = persistedStateSnapshot.readKey === persistedStateReadKey;
+    // Opening a shared URL should become this identity's saved layout. The
+    // caller decides which identity is allowed to commit: this only writes
+    // when the snapshot was read for the current storage key, so a late
+    // identity resolution cannot persist the pre-merge value and drop fields
+    // that live only in localStorage. A hash that is only the shareable
+    // projection of what is already stored is left alone, so reloading this
+    // account's own link does not replace hidden columns with the shorter URL form.
+    const commitHydratedState = react.useCallback(() => {
+        if (!snapshotIsCurrent || !localStorageEnabled) {
+            return false;
+        }
+        if (!canonicalUrlHasValidState || initialState === undefined) {
+            return true;
+        }
+        let stored;
+        try {
+            const raw = rawLocalStorage.read(storageKey);
+            if (raw) {
+                stored = validateRef.current(sharedUtils.storageSerializer.deserialize(raw));
+            }
+        }
+        catch {
+            stored = undefined;
+        }
+        if (stored !== undefined) {
+            const projected = toUrlValueRef.current ? toUrlValueRef.current(stored) : stored;
+            if (dequal.dequal(projected, canonicalUrlPayload)) {
+                return true;
+            }
+        }
+        const serialized = serializeRef.current
+            ? serializeRef.current(initialState)
+            : sharedUtils.storageSerializer.serialize(initialState);
+        rawLocalStorage.write(storageKey, serialized);
+        lastPersistedRef.current = initialState;
+        return true;
+    }, [
+        canonicalUrlHasValidState,
+        canonicalUrlPayload,
+        initialState,
+        localStorageEnabled,
+        snapshotIsCurrent,
+        storageKey,
+    ]);
+    return react.useMemo(() => ({ initialState, persistState, clearState, commitHydratedState }), [initialState, persistState, clearState, commitHydratedState]);
 };
 
 /**

package/index.esm.js

@@ -14125,6 +14125,12 @@ const rawLocalStorage = {
  * `toUrlValue` + encoding). Duplicate writes where the state has not
  * changed (deep equality) are skipped.
  *
+ * `commitHydratedState` writes the hydrated value to localStorage only,
+ * when it came from the URL and differs from what this identity has stored.
+ * It does not update the URL. It returns `false` while the snapshot is
+ * still for a previous read, so the caller can retry after identity
+ * resolution. The caller decides which identity is allowed to commit.
+ *
  * `clearState` removes the entry from localStorage and from the URL slot,
  * rather than writing an empty value. Use it when the state a consumer
  * derives has become empty, so no leftover entry is stored for a value the
@@ -14215,7 +14221,11 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             try {
                 const { value } = unwrapUrlOwner(decode(raw));
                 const transformed = transformFromUrlValue ? transformFromUrlValue(value) : value;
-                return validateState(transformed);
+                const state = validateState(transformed);
+                if (state === undefined) {
+                    return undefined;
+                }
+                return { state, payload: value };
             }
             catch {
                 return undefined;
@@ -14237,17 +14247,21 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             }
         };
         let urlState;
+        let decodedPayload;
         let canonicalUrlValid = false;
         let usedLegacyUrl = false;
         if (enabled && valueFromUrl) {
-            urlState = tryDecode(valueFromUrl);
-            if (urlState !== undefined) {
+            const decoded = tryDecode(valueFromUrl);
+            if (decoded !== undefined) {
+                urlState = decoded.state;
+                decodedPayload = decoded.payload;
                 canonicalUrlValid = true;
             }
         }
         if (urlState === undefined && enabled && legacyValueFromUrl) {
-            urlState = tryDecode(legacyValueFromUrl);
-            if (urlState !== undefined) {
+            const decoded = tryDecode(legacyValueFromUrl);
+            if (decoded !== undefined) {
+                urlState = decoded.state;
                 usedLegacyUrl = true;
             }
         }
@@ -14257,6 +14271,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
                 needsUrlRestore: usedLegacyUrl,
             };
         }
@@ -14267,6 +14282,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: { ...storageState, ...urlState },
                 canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
                 needsUrlRestore: usedLegacyUrl,
             };
         }
@@ -14274,6 +14290,7 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: urlState,
                 canonicalUrlHasValidState: canonicalUrlValid,
+                canonicalUrlPayload: decodedPayload,
                 needsUrlRestore: usedLegacyUrl,
             };
         }
@@ -14281,12 +14298,14 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             return {
                 initialState: storageState,
                 canonicalUrlHasValidState: false,
+                canonicalUrlPayload: undefined,
                 needsUrlRestore: true,
             };
         }
         return {
             initialState: undefined,
             canonicalUrlHasValidState: false,
+            canonicalUrlPayload: undefined,
             needsUrlRestore: false,
         };
     }, [decode, enabled, localStorageEnabled, storageKey, mergeWithStorageOnRead]);
@@ -14296,27 +14315,33 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
         return encode(currentUrlOwner === undefined ? urlValue : wrapUrlOwner(urlValue, currentUrlOwner));
     }, [encode, currentUrlOwner]);
-    const [persistedStateSnapshot, setPersistedStateSnapshot] = useState(() => readPersistedState({
-        valueFromUrl: searchValue,
-        legacyValueFromUrl: legacySearchValue,
-        validateState: validate,
-        transformFromUrlValue: fromUrlValue,
-    }));
     const persistedStateReadKey = `${enabled}:${localStorageEnabled}:${mergeWithStorageOnRead}:${urlLocation}:${storageKey}`;
+    const [persistedStateSnapshot, setPersistedStateSnapshot] = useState(() => ({
+        ...readPersistedState({
+            valueFromUrl: searchValue,
+            legacyValueFromUrl: legacySearchValue,
+            validateState: validate,
+            transformFromUrlValue: fromUrlValue,
+        }),
+        readKey: persistedStateReadKey,
+    }));
     const persistedStateReadKeyRef = useRef(persistedStateReadKey);
     useEffect(() => {
         if (persistedStateReadKeyRef.current === persistedStateReadKey) {
             return;
         }
         persistedStateReadKeyRef.current = persistedStateReadKey;
-        setPersistedStateSnapshot(readPersistedState({
-            valueFromUrl: searchValueRef.current,
-            legacyValueFromUrl: legacySearchValueRef.current,
-            validateState: validateRef.current,
-            transformFromUrlValue: fromUrlValueRef.current,
-        }));
+        setPersistedStateSnapshot({
+            ...readPersistedState({
+                valueFromUrl: searchValueRef.current,
+                legacyValueFromUrl: legacySearchValueRef.current,
+                validateState: validateRef.current,
+                transformFromUrlValue: fromUrlValueRef.current,
+            }),
+            readKey: persistedStateReadKey,
+        });
     }, [persistedStateReadKey, readPersistedState]);
-    const { initialState, canonicalUrlHasValidState, needsUrlRestore } = persistedStateSnapshot;
+    const { initialState, canonicalUrlHasValidState, canonicalUrlPayload, needsUrlRestore } = persistedStateSnapshot;
     // Late-hydration recovery: TanStack Router's `useSearch` can return an
     // empty object on the very first render of a route that's still in a
     // loader-driven pending phase. The `useState` initializer above runs
@@ -14337,13 +14362,16 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         if (legacySearchValue === undefined) {
             return;
         }
-        setPersistedStateSnapshot(readPersistedState({
-            valueFromUrl: searchValueRef.current,
-            legacyValueFromUrl: legacySearchValue,
-            validateState: validateRef.current,
-            transformFromUrlValue: fromUrlValueRef.current,
-        }));
-    }, [legacySearchValue, initialState, canonicalUrlHasValidState, readPersistedState]);
+        setPersistedStateSnapshot({
+            ...readPersistedState({
+                valueFromUrl: searchValueRef.current,
+                legacyValueFromUrl: legacySearchValue,
+                validateState: validateRef.current,
+                transformFromUrlValue: fromUrlValueRef.current,
+            }),
+            readKey: persistedStateReadKey,
+        });
+    }, [legacySearchValue, initialState, canonicalUrlHasValidState, persistedStateReadKey, readPersistedState]);
     const lastPersistedRef = useRef(initialState);
     useEffect(() => {
         lastPersistedRef.current = initialState;
@@ -14413,7 +14441,52 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
         }
         updateSearchParam(undefined);
     }, [localStorageEnabled, storageKey, updateSearchParam]);
-    return useMemo(() => ({ initialState, persistState, clearState }), [initialState, persistState, clearState]);
+    const snapshotIsCurrent = persistedStateSnapshot.readKey === persistedStateReadKey;
+    // Opening a shared URL should become this identity's saved layout. The
+    // caller decides which identity is allowed to commit: this only writes
+    // when the snapshot was read for the current storage key, so a late
+    // identity resolution cannot persist the pre-merge value and drop fields
+    // that live only in localStorage. A hash that is only the shareable
+    // projection of what is already stored is left alone, so reloading this
+    // account's own link does not replace hidden columns with the shorter URL form.
+    const commitHydratedState = useCallback(() => {
+        if (!snapshotIsCurrent || !localStorageEnabled) {
+            return false;
+        }
+        if (!canonicalUrlHasValidState || initialState === undefined) {
+            return true;
+        }
+        let stored;
+        try {
+            const raw = rawLocalStorage.read(storageKey);
+            if (raw) {
+                stored = validateRef.current(storageSerializer.deserialize(raw));
+            }
+        }
+        catch {
+            stored = undefined;
+        }
+        if (stored !== undefined) {
+            const projected = toUrlValueRef.current ? toUrlValueRef.current(stored) : stored;
+            if (dequal(projected, canonicalUrlPayload)) {
+                return true;
+            }
+        }
+        const serialized = serializeRef.current
+            ? serializeRef.current(initialState)
+            : storageSerializer.serialize(initialState);
+        rawLocalStorage.write(storageKey, serialized);
+        lastPersistedRef.current = initialState;
+        return true;
+    }, [
+        canonicalUrlHasValidState,
+        canonicalUrlPayload,
+        initialState,
+        localStorageEnabled,
+        snapshotIsCurrent,
+        storageKey,
+    ]);
+    return useMemo(() => ({ initialState, persistState, clearState, commitHydratedState }), [initialState, persistState, clearState, commitHydratedState]);
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "3.5.3",
+  "version": "3.5.4-alpha-cb9408e01a9.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,16 +14,16 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.17.2",
-    "@trackunit/css-class-variance-utilities": "2.2.2",
-    "@trackunit/shared-utils": "1.18.2",
-    "@trackunit/ui-icons": "1.16.2",
+    "@trackunit/ui-design-tokens": "1.17.3-alpha-cb9408e01a9.0",
+    "@trackunit/css-class-variance-utilities": "2.2.3-alpha-cb9408e01a9.0",
+    "@trackunit/shared-utils": "1.18.3-alpha-cb9408e01a9.0",
+    "@trackunit/ui-icons": "1.16.3-alpha-cb9408e01a9.0",
     "es-toolkit": "^1.52.0",
     "@tanstack/react-virtual": "^3.14.13",
     "dequal": "^2.0.3",
     "fflate": "^0.8.3",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.7.2"
+    "@trackunit/i18n-library-translation": "2.7.3-alpha-cb9408e01a9.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/hooks/persistence/usePersistedState.d.ts

@@ -58,6 +58,13 @@ type UsePersistedStateReturn<TState> = {
     readonly initialState: TState | undefined;
     readonly persistState: (state: TState) => void;
     readonly clearState: () => void;
+    /**
+     * Writes the hydrated state to localStorage when it came from the URL and
+     * differs from what this identity has stored. Returns `false` when the
+     * snapshot is still for a previous read (identity not resolved yet), so
+     * the caller can retry. A no-op success returns `true`.
+     */
+    readonly commitHydratedState: () => boolean;
 };
 /**
  * Generic persistence hook that loads state from a URL slot (search param
@@ -82,6 +89,12 @@ type UsePersistedStateReturn<TState> = {
  * `toUrlValue` + encoding). Duplicate writes where the state has not
  * changed (deep equality) are skipped.
  *
+ * `commitHydratedState` writes the hydrated value to localStorage only,
+ * when it came from the URL and differs from what this identity has stored.
+ * It does not update the URL. It returns `false` while the snapshot is
+ * still for a previous read, so the caller can retry after identity
+ * resolution. The caller decides which identity is allowed to commit.
+ *
  * `clearState` removes the entry from localStorage and from the URL slot,
  * rather than writing an empty value. Use it when the state a consumer
  * derives has become empty, so no leftover entry is stored for a value the