@ai-matrx/design-system 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.17.2 — 2026-09-12
+
+`MatrxDataTable` now resets the vertical scroll position of both its desktop
+table and mobile card scrollers before paint when a non-initial
+`controlled-append` source key changes. Same-source appends and horizontal
+scroll position remain untouched in both automatic and manual modes.
+
+### Consumer action
+
+Update to 0.17.2 so refreshed or replaced append sources begin at their first
+row instead of retaining the previous source's bottom position. No API or
+configuration change is required.
+
+## 0.17.1 — 2026-09-12
+
+`useScrollPagination` now retains each container's last observed scroll position
+across listener reattachment. This lets a trusted passive wheel append when
+Chromium's compositor has advanced the scroller before JavaScript receives its
+asynchronous scroll notification, while preserving the fresh-input, actual-
+movement, one-gesture, manual-mode, error, and programmatic-scroll guards.
+
+### Consumer action
+
+Update to 0.17.1 for reliable wheel-driven append on `controlled-append` tables.
+No API or configuration change is required.
+
 ## 0.17.0 — 2026-09-12
 
 - `MatrxDataTable` accepts opt-in controlled `columnState` and `reorderableColumns`, allowing URL-backed order/visibility and package-owned header drag without a host renderer fork. Header grips and the column manager use the existing pointer sensor for mouse/touch ordering; the manager retains arrow controls and protected visibility. Headers show insertion feedback and cancel edge scrolling when the drag ends or leaves a valid target.

package/dist/data-table/index.cjs

@@ -1197,6 +1197,7 @@ function useScrollPagination({
   const inFlightGenerationRef = (0, import_react.useRef)(null);
   const requestErrorRef = (0, import_react.useRef)(null);
   const mountedRef = (0, import_react.useRef)(false);
+  const observedTopRef = (0, import_react.useRef)(/* @__PURE__ */ new WeakMap());
   const effectiveError = error ?? requestError;
   (0, import_react.useEffect)(() => {
     mountedRef.current = true;
@@ -1230,6 +1231,7 @@ function useScrollPagination({
   };
   (0, import_react.useEffect)(() => {
     intentRef.current = null;
+    observedTopRef.current = /* @__PURE__ */ new WeakMap();
     consumedSequenceRef.current = inputSequenceRef.current;
     requestErrorRef.current = null;
     setRequestError(null);
@@ -1239,14 +1241,18 @@ function useScrollPagination({
   (0, import_react.useEffect)(() => {
     if (mode !== "scroll" || !enabled || typeof window === "undefined") return;
     const attachable = containers.map(resolveContainer).filter((container) => container !== null);
-    const setIntent = (container) => {
+    const setIntent = (container, startTop) => {
       const current = latestRef.current;
       if (!isVisibleContainer(container) || current.loading || current.isFetchingNextPage || inFlightGenerationRef.current !== null) return;
       inputSequenceRef.current += 1;
       intentRef.current = {
         queryKey: latestRef.current.queryKey,
         container,
-        startTop: container.scrollTop,
+        // The compositor can advance downward before the passive input
+        // listener, while DOM/test callers can move upward before its scroll
+        // notification. Either way, the lower position is the only safe
+        // baseline for proving that this downward intent caused movement.
+        startTop: Math.min(startTop, container.scrollTop),
         sequence: inputSequenceRef.current,
         expiresAt: Date.now() + intentTimeoutMs
       };
@@ -1261,9 +1267,11 @@ function useScrollPagination({
       void requestNextPage();
     };
     const cleanups = attachable.map((container) => {
+      if (!observedTopRef.current.has(container)) observedTopRef.current.set(container, container.scrollTop);
+      const lastObservedTop = () => observedTopRef.current.get(container) ?? container.scrollTop;
       const onWheel = (event) => {
         if (event.deltaY > 0 && Math.abs(event.deltaY) > Math.abs(event.deltaX)) {
-          setIntent(container);
+          setIntent(container, lastObservedTop());
         }
       };
       const onTouchStart = (event) => {
@@ -1274,19 +1282,22 @@ function useScrollPagination({
         const touch = event.touches.item(0);
         const startY = Number(container.dataset.matrxPaginationTouchY);
         if (touch && Number.isFinite(startY) && startY - touch.clientY > 0) {
-          setIntent(container);
+          setIntent(container, lastObservedTop());
         }
       };
       const onTouchEnd = () => {
         delete container.dataset.matrxPaginationTouchY;
       };
       const onKeyDown = (event) => {
-        if (isDownwardKeyboardInput(event)) setIntent(container);
+        if (isDownwardKeyboardInput(event)) setIntent(container, lastObservedTop());
       };
       const onPointerDown = (event) => {
-        if (isNativeScrollbarPointer(event, container)) setIntent(container);
+        if (isNativeScrollbarPointer(event, container)) setIntent(container, lastObservedTop());
+      };
+      const onScroll = () => {
+        handleScroll(container);
+        observedTopRef.current.set(container, container.scrollTop);
       };
-      const onScroll = () => handleScroll(container);
       container.addEventListener("wheel", onWheel, { passive: true });
       container.addEventListener("touchstart", onTouchStart, { passive: true });
       container.addEventListener("touchmove", onTouchMove, { passive: true });
@@ -5458,6 +5469,16 @@ function MatrxDataTableCore({
   ]);
   const scrollRef = (0, import_react14.useRef)(null);
   const cardsScrollRef = (0, import_react14.useRef)(null);
+  const previousAppendKeyForScrollReset = (0, import_react14.useRef)(appendQueryKey);
+  (0, import_react14.useLayoutEffect)(() => {
+    const previous = previousAppendKeyForScrollReset.current;
+    previousAppendKeyForScrollReset.current = appendQueryKey;
+    if (previous === null || appendQueryKey === null || previous === appendQueryKey) {
+      return;
+    }
+    if (scrollRef.current) scrollRef.current.scrollTop = 0;
+    if (cardsScrollRef.current) cardsScrollRef.current.scrollTop = 0;
+  }, [appendQueryKey]);
   const scrollPagination = useScrollPagination({
     containers: [scrollRef, cardsScrollRef],
     queryKey: appendQuery?.pagination.queryKey ?? "",