@trackunit/react-components 1.21.17 → 1.22.0

package/index.cjs.js

@@ -9128,10 +9128,11 @@ const useSheetMotionOverflow = ({ panelEl, isDragging, scrollAreaEl, separatorEl
  * CSS transitions on transform; the component stays mounted during the
  * close animation and unmounts after the transition completes.
  */
-const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor = "center", snapping = true, resizable = true, variant = "default", trapFocus = true, container, dockedContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation = "subsequent", children, }) => {
+const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor = "center", snapping = true, resizable = true, variant = "default", trapFocus = true, container, dockedContent, persistentContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation = "subsequent", children, }) => {
     const isFirstRender = useIsFirstRender();
     const skipEntryAnimation = entryAnimation === "never" || (entryAnimation === "subsequent" && isFirstRender);
     const effectiveSnapping = resizable && snapping;
+    const dockingEnabled = dockedContent !== undefined || persistentContent !== undefined;
     const [animState, animDispatch] = react.useReducer(sheetAnimationReducer, INITIAL_ANIMATION_STATE);
     if (isOpen !== animState.prevIsOpen) {
         animDispatch({
@@ -9143,7 +9144,7 @@ const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, o
     const measurements = useSheetMeasurements({
         shouldRender: animState.shouldRender,
         state,
-        dockingEnabled: dockedContent !== undefined,
+        dockingEnabled,
         snapping: effectiveSnapping,
         externalRef: ref,
         onGeometryChange,
@@ -9218,7 +9219,7 @@ const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, o
         ? `${state.effectiveDockedHeight}px`
         : fitHeightMeasured
             ? `${cappedFitHeight}px`
-            : getSnapLevelCssHeight(state.level, state.totalLevels, dockedContent !== undefined, state.effectiveDockedHeight);
+            : getSnapLevelCssHeight(state.level, state.totalLevels, dockingEnabled, state.effectiveDockedHeight);
     const fitMaxHeight = state.sizingMode === "fit" ? `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)` : undefined;
     if (!animState.shouldRender)
         return null;
@@ -9242,7 +9243,7 @@ const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, o
             snapHeight: snapHeightCss,
             suppressTransition: skipEntryAnimation && animState.visuallyOpen,
             variant,
-        }), children: [resizable ? (jsxRuntime.jsx(SheetHandle, { "data-testid": dataTestId !== undefined ? `${dataTestId}-handle` : undefined, isDragging: gestures.isDragging, onClick: handleClick, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ...gestureHandlers })) : null, jsxRuntime.jsx("div", { className: "h-px shrink-0 bg-neutral-200 opacity-0 transition-opacity duration-200", ref: setSeparatorEl }), jsxRuntime.jsx("div", { className: cvaSheetScrollArea({ fillHeight: state.sizingMode !== "fit" }), "data-sheet-scroll-area": true, ref: setScrollAreaEl, children: state.sizingMode === "docked" ? dockedContent : children })] }));
+        }), children: [resizable ? (jsxRuntime.jsx(SheetHandle, { "data-testid": dataTestId !== undefined ? `${dataTestId}-handle` : undefined, isDragging: gestures.isDragging, onClick: handleClick, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ...gestureHandlers })) : null, jsxRuntime.jsx("div", { className: "h-px shrink-0 bg-neutral-200 opacity-0 transition-opacity duration-200", ref: setSeparatorEl }), jsxRuntime.jsxs("div", { className: cvaSheetScrollArea({ fillHeight: state.sizingMode !== "fit" }), "data-sheet-scroll-area": true, ref: setScrollAreaEl, children: [persistentContent, state.sizingMode === "docked" ? dockedContent : children] })] }));
     return (jsxRuntime.jsx(Portal, { root: container, children: jsxRuntime.jsxs("div", { className: cvaSheetContainer({
                 docked: state.sizingMode === "docked",
             }), "data-testid": dataTestId !== undefined ? `${dataTestId}-container` : undefined, ref: containerRef, children: [jsxRuntime.jsx(SheetOverlay, { "data-testid": dataTestId !== undefined ? `${dataTestId}-overlay` : undefined, visible: showOverlay }), shouldTrapFocus === true ? (jsxRuntime.jsx(react$1.FloatingFocusManager, { context: floatingUi.context, children: panel })) : (panel)] }) }));
@@ -11047,7 +11048,7 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
         const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
         return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
     }, [location]);
-    const updateSearchParam = react.useCallback((encodedValue) => {
+    const updateSearchParam = react.useCallback((encodedValue, options) => {
         if (!enabled) {
             return;
         }
@@ -11059,7 +11060,7 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
             return;
         }
         requestAnimationFrame(() => {
-            const shouldReplace = replaceOption ?? !Boolean(currentSearchValue);
+            const shouldReplace = options?.replace ?? replaceOption ?? !Boolean(currentSearchValue);
             void navigate({
                 to: ".",
                 search: (prev) => {
@@ -11140,14 +11141,14 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     react.useEffect(() => {
         serializeRef.current = serialize;
     }, [serialize]);
-    const [initialState] = react.useState(() => {
+    const [{ initialState, loadedFromStorage }] = react.useState(() => {
         if (enabled && searchValue) {
             try {
                 const decoded = decode(searchValue);
                 const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
                 const validated = validate(transformed);
                 if (validated !== undefined) {
-                    return validated;
+                    return { initialState: validated, loadedFromStorage: false };
                 }
             }
             catch {
@@ -11158,15 +11159,28 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             const raw = localStorage.getItem(storageKey);
             if (raw) {
                 const parsed = storageSerializer.deserialize(raw);
-                return validate(parsed);
+                const validated = validate(parsed);
+                return { initialState: validated, loadedFromStorage: validated !== undefined };
             }
         }
         catch {
             // no valid stored state
         }
-        return undefined;
+        return { initialState: undefined, loadedFromStorage: false };
     });
     const lastPersistedRef = react.useRef(initialState);
+    const hasRestoredUrlRef = react.useRef(false);
+    react.useEffect(() => {
+        if (hasRestoredUrlRef.current) {
+            return;
+        }
+        if (!enabled || !loadedFromStorage || initialState === undefined || searchValue !== undefined) {
+            return;
+        }
+        hasRestoredUrlRef.current = true;
+        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
+        updateSearchParam(encode(urlValue), { replace: true });
+    }, [enabled, loadedFromStorage, initialState, searchValue, updateSearchParam, encode]);
     const persistState = react.useCallback((state) => {
         if (dequal.dequal(lastPersistedRef.current, state)) {
             return;

package/index.esm.js

@@ -9126,10 +9126,11 @@ const useSheetMotionOverflow = ({ panelEl, isDragging, scrollAreaEl, separatorEl
  * CSS transitions on transform; the component stays mounted during the
  * close animation and unmounts after the transition completes.
  */
-const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor = "center", snapping = true, resizable = true, variant = "default", trapFocus = true, container, dockedContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation = "subsequent", children, }) => {
+const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor = "center", snapping = true, resizable = true, variant = "default", trapFocus = true, container, dockedContent, persistentContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation = "subsequent", children, }) => {
     const isFirstRender = useIsFirstRender();
     const skipEntryAnimation = entryAnimation === "never" || (entryAnimation === "subsequent" && isFirstRender);
     const effectiveSnapping = resizable && snapping;
+    const dockingEnabled = dockedContent !== undefined || persistentContent !== undefined;
     const [animState, animDispatch] = useReducer(sheetAnimationReducer, INITIAL_ANIMATION_STATE);
     if (isOpen !== animState.prevIsOpen) {
         animDispatch({
@@ -9141,7 +9142,7 @@ const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, o
     const measurements = useSheetMeasurements({
         shouldRender: animState.shouldRender,
         state,
-        dockingEnabled: dockedContent !== undefined,
+        dockingEnabled,
         snapping: effectiveSnapping,
         externalRef: ref,
         onGeometryChange,
@@ -9216,7 +9217,7 @@ const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, o
         ? `${state.effectiveDockedHeight}px`
         : fitHeightMeasured
             ? `${cappedFitHeight}px`
-            : getSnapLevelCssHeight(state.level, state.totalLevels, dockedContent !== undefined, state.effectiveDockedHeight);
+            : getSnapLevelCssHeight(state.level, state.totalLevels, dockingEnabled, state.effectiveDockedHeight);
     const fitMaxHeight = state.sizingMode === "fit" ? `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)` : undefined;
     if (!animState.shouldRender)
         return null;
@@ -9240,7 +9241,7 @@ const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, o
             snapHeight: snapHeightCss,
             suppressTransition: skipEntryAnimation && animState.visuallyOpen,
             variant,
-        }), children: [resizable ? (jsx(SheetHandle, { "data-testid": dataTestId !== undefined ? `${dataTestId}-handle` : undefined, isDragging: gestures.isDragging, onClick: handleClick, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ...gestureHandlers })) : null, jsx("div", { className: "h-px shrink-0 bg-neutral-200 opacity-0 transition-opacity duration-200", ref: setSeparatorEl }), jsx("div", { className: cvaSheetScrollArea({ fillHeight: state.sizingMode !== "fit" }), "data-sheet-scroll-area": true, ref: setScrollAreaEl, children: state.sizingMode === "docked" ? dockedContent : children })] }));
+        }), children: [resizable ? (jsx(SheetHandle, { "data-testid": dataTestId !== undefined ? `${dataTestId}-handle` : undefined, isDragging: gestures.isDragging, onClick: handleClick, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ...gestureHandlers })) : null, jsx("div", { className: "h-px shrink-0 bg-neutral-200 opacity-0 transition-opacity duration-200", ref: setSeparatorEl }), jsxs("div", { className: cvaSheetScrollArea({ fillHeight: state.sizingMode !== "fit" }), "data-sheet-scroll-area": true, ref: setScrollAreaEl, children: [persistentContent, state.sizingMode === "docked" ? dockedContent : children] })] }));
     return (jsx(Portal, { root: container, children: jsxs("div", { className: cvaSheetContainer({
                 docked: state.sizingMode === "docked",
             }), "data-testid": dataTestId !== undefined ? `${dataTestId}-container` : undefined, ref: containerRef, children: [jsx(SheetOverlay, { "data-testid": dataTestId !== undefined ? `${dataTestId}-overlay` : undefined, visible: showOverlay }), shouldTrapFocus === true ? (jsx(FloatingFocusManager, { context: floatingUi.context, children: panel })) : (panel)] }) }));
@@ -11045,7 +11046,7 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
         const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
         return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
     }, [location]);
-    const updateSearchParam = useCallback((encodedValue) => {
+    const updateSearchParam = useCallback((encodedValue, options) => {
         if (!enabled) {
             return;
         }
@@ -11057,7 +11058,7 @@ const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: re
             return;
         }
         requestAnimationFrame(() => {
-            const shouldReplace = replaceOption ?? !Boolean(currentSearchValue);
+            const shouldReplace = options?.replace ?? replaceOption ?? !Boolean(currentSearchValue);
             void navigate({
                 to: ".",
                 search: (prev) => {
@@ -11138,14 +11139,14 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
     useEffect(() => {
         serializeRef.current = serialize;
     }, [serialize]);
-    const [initialState] = useState(() => {
+    const [{ initialState, loadedFromStorage }] = useState(() => {
         if (enabled && searchValue) {
             try {
                 const decoded = decode(searchValue);
                 const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
                 const validated = validate(transformed);
                 if (validated !== undefined) {
-                    return validated;
+                    return { initialState: validated, loadedFromStorage: false };
                 }
             }
             catch {
@@ -11156,15 +11157,28 @@ const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue,
             const raw = localStorage.getItem(storageKey);
             if (raw) {
                 const parsed = storageSerializer.deserialize(raw);
-                return validate(parsed);
+                const validated = validate(parsed);
+                return { initialState: validated, loadedFromStorage: validated !== undefined };
             }
         }
         catch {
             // no valid stored state
         }
-        return undefined;
+        return { initialState: undefined, loadedFromStorage: false };
     });
     const lastPersistedRef = useRef(initialState);
+    const hasRestoredUrlRef = useRef(false);
+    useEffect(() => {
+        if (hasRestoredUrlRef.current) {
+            return;
+        }
+        if (!enabled || !loadedFromStorage || initialState === undefined || searchValue !== undefined) {
+            return;
+        }
+        hasRestoredUrlRef.current = true;
+        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(initialState) : initialState;
+        updateSearchParam(encode(urlValue), { replace: true });
+    }, [enabled, loadedFromStorage, initialState, searchValue, updateSearchParam, encode]);
     const persistState = useCallback((state) => {
         if (dequal(lastPersistedRef.current, state)) {
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.21.17",
+  "version": "1.22.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/components/Sheet/Sheet.d.ts

@@ -26,4 +26,4 @@ import type { SheetProps } from "./sheet-types";
  * CSS transitions on transform; the component stays mounted during the
  * close animation and unmounts after the transition completes.
  */
-export declare const Sheet: ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor, snapping, resizable, variant, trapFocus, container, dockedContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation, children, }: SheetProps) => ReactElement | null;
+export declare const Sheet: ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor, snapping, resizable, variant, trapFocus, container, dockedContent, persistentContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation, children, }: SheetProps) => ReactElement | null;

package/src/components/Sheet/sheet-types.d.ts

@@ -187,6 +187,15 @@ export type SheetProps = {
     readonly container: HTMLElement | null;
     /** Content rendered when in docked mode. Presence enables docking behavior. */
     readonly dockedContent?: ReactNode;
+    /**
+     * Content rendered above `dockedContent`/`children` in every sizing mode.
+     * Use this when the same subtree (e.g. a filter bar with an input) must
+     * stay mounted across snap transitions so its DOM — and any focused
+     * element inside it — is preserved. Presence alone also enables docking
+     * behavior even when `dockedContent` is omitted; in that case the docked
+     * mode shows only `persistentContent`.
+     */
+    readonly persistentContent?: ReactNode;
     /** Custom class name. */
     readonly className?: string;
     /** Test ID for the sheet. */

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

@@ -7,7 +7,9 @@ type UseSearchParamSyncOptions = {
 };
 type UseSearchParamSyncReturn = {
     readonly searchValue: string | undefined;
-    readonly updateSearchParam: (encodedValue: string | undefined) => void;
+    readonly updateSearchParam: (encodedValue: string | undefined, options?: {
+        readonly replace?: boolean;
+    }) => void;
 };
 /**
  * Syncs an encoded string value with a URL search parameter via Tanstack Router.