react-arborist 3.10.6 → 3.11.0

package/README.md

@@ -745,6 +745,14 @@ _tree_.**scrollTo**(_id_, _[align]_)
 
 Scroll to the node with _id_. If this node is not visible, this method will open all its parents. The align argument can be _"auto" | "smart" | "center" | "end" | "start"_.
 
+_tree_.**scrollToOffset**(_offset_)
+
+Scroll the list vertically to an exact pixel _offset_ from the top — the offset-based counterpart to _scrollTo_, useful for saving and restoring a scroll position. Negative or non-finite values are clamped to the top, and react-window clamps the upper bound to the scrollable range.
+
+_tree_.**scrollOffset** : _number_
+
+Returns the list's current vertical scroll offset, in pixels from the top. Pairs with _scrollToOffset_ to persist and restore the scroll position.
+
 ### Properties
 
 _tree_.**isEditing** : _boolean_

package/dist/main/interfaces/tree-api.d.ts

@@ -235,6 +235,15 @@ export declare class TreeApi<T> {
      * it never disturbs scrolling for trees that fit their width.
      */
     private scrollToNodeHorizontally;
+    /**
+     * Scroll the list vertically to an exact pixel offset from the top. This is
+     * the offset-based counterpart to scrollTo(), handy for saving and restoring
+     * a scroll position (#194). Negative values are clamped to the top; react-
+     * window clamps the upper bound to the scrollable range.
+     */
+    scrollToOffset(offset: number): void;
+    /** The list's current vertical scroll offset, in pixels from the top. */
+    get scrollOffset(): number;
     get isEditing(): boolean;
     get isFiltered(): boolean;
     get hasFocus(): boolean;

package/dist/main/interfaces/tree-api.js

@@ -715,6 +715,24 @@ class TreeApi {
             el.scrollLeft = Math.max(0, Math.min(left, maxScroll));
         }
     }
+    /**
+     * Scroll the list vertically to an exact pixel offset from the top. This is
+     * the offset-based counterpart to scrollTo(), handy for saving and restoring
+     * a scroll position (#194). Negative values are clamped to the top; react-
+     * window clamps the upper bound to the scrollable range.
+     */
+    scrollToOffset(offset) {
+        var _a;
+        /* Coerce non-finite offsets (NaN/Infinity, easy to get from malformed
+           persisted state) to the top rather than forwarding them to the list. */
+        const safe = Number.isFinite(offset) ? Math.max(0, offset) : 0;
+        (_a = this.list.current) === null || _a === void 0 ? void 0 : _a.scrollTo(safe);
+    }
+    /** The list's current vertical scroll offset, in pixels from the top. */
+    get scrollOffset() {
+        var _a, _b;
+        return (_b = (_a = this.listEl.current) === null || _a === void 0 ? void 0 : _a.scrollTop) !== null && _b !== void 0 ? _b : 0;
+    }
     /* State Checks */
     get isEditing() {
         return this.state.nodes.edit.id !== null;

package/dist/main/interfaces/tree-api.test.js

@@ -219,3 +219,37 @@ describe("scrollTo brings a deeply nested node into view horizontally (#220)", (
         expect(el.scrollLeft).toBe(0);
     }));
 });
+describe("scrollToOffset / scrollOffset set and read the vertical position (#194)", () => {
+    const data = [{ id: "a" }, { id: "b" }, { id: "c" }];
+    function setup(el) {
+        const store = (0, redux_1.createStore)(root_reducer_1.rootReducer);
+        const list = { current: { scrollTo: jest.fn() } };
+        const listEl = { current: (el !== null && el !== void 0 ? el : null) };
+        return { api: new tree_api_1.TreeApi(store, { data }, list, listEl), list, listEl };
+    }
+    test("scrollToOffset forwards the offset to the underlying list", () => {
+        const { api, list } = setup();
+        api.scrollToOffset(120);
+        expect(list.current.scrollTo).toHaveBeenCalledWith(120);
+    });
+    test("scrollToOffset clamps negative offsets to the top", () => {
+        const { api, list } = setup();
+        api.scrollToOffset(-50);
+        expect(list.current.scrollTo).toHaveBeenCalledWith(0);
+    });
+    test("scrollToOffset coerces non-finite offsets to the top", () => {
+        const { api, list } = setup();
+        api.scrollToOffset(NaN);
+        api.scrollToOffset(Infinity);
+        expect(list.current.scrollTo).toHaveBeenNthCalledWith(1, 0);
+        expect(list.current.scrollTo).toHaveBeenNthCalledWith(2, 0);
+    });
+    test("scrollOffset reads the list element's scrollTop", () => {
+        const { api } = setup({ scrollTop: 80 });
+        expect(api.scrollOffset).toBe(80);
+    });
+    test("scrollOffset is 0 before the list element mounts", () => {
+        const { api } = setup();
+        expect(api.scrollOffset).toBe(0);
+    });
+});

package/dist/module/interfaces/tree-api.d.ts

@@ -235,6 +235,15 @@ export declare class TreeApi<T> {
      * it never disturbs scrolling for trees that fit their width.
      */
     private scrollToNodeHorizontally;
+    /**
+     * Scroll the list vertically to an exact pixel offset from the top. This is
+     * the offset-based counterpart to scrollTo(), handy for saving and restoring
+     * a scroll position (#194). Negative values are clamped to the top; react-
+     * window clamps the upper bound to the scrollable range.
+     */
+    scrollToOffset(offset: number): void;
+    /** The list's current vertical scroll offset, in pixels from the top. */
+    get scrollOffset(): number;
     get isEditing(): boolean;
     get isFiltered(): boolean;
     get hasFocus(): boolean;

package/dist/module/interfaces/tree-api.js

@@ -689,6 +689,24 @@ export class TreeApi {
             el.scrollLeft = Math.max(0, Math.min(left, maxScroll));
         }
     }
+    /**
+     * Scroll the list vertically to an exact pixel offset from the top. This is
+     * the offset-based counterpart to scrollTo(), handy for saving and restoring
+     * a scroll position (#194). Negative values are clamped to the top; react-
+     * window clamps the upper bound to the scrollable range.
+     */
+    scrollToOffset(offset) {
+        var _a;
+        /* Coerce non-finite offsets (NaN/Infinity, easy to get from malformed
+           persisted state) to the top rather than forwarding them to the list. */
+        const safe = Number.isFinite(offset) ? Math.max(0, offset) : 0;
+        (_a = this.list.current) === null || _a === void 0 ? void 0 : _a.scrollTo(safe);
+    }
+    /** The list's current vertical scroll offset, in pixels from the top. */
+    get scrollOffset() {
+        var _a, _b;
+        return (_b = (_a = this.listEl.current) === null || _a === void 0 ? void 0 : _a.scrollTop) !== null && _b !== void 0 ? _b : 0;
+    }
     /* State Checks */
     get isEditing() {
         return this.state.nodes.edit.id !== null;

package/dist/module/interfaces/tree-api.test.js

@@ -217,3 +217,37 @@ describe("scrollTo brings a deeply nested node into view horizontally (#220)", (
         expect(el.scrollLeft).toBe(0);
     }));
 });
+describe("scrollToOffset / scrollOffset set and read the vertical position (#194)", () => {
+    const data = [{ id: "a" }, { id: "b" }, { id: "c" }];
+    function setup(el) {
+        const store = createStore(rootReducer);
+        const list = { current: { scrollTo: jest.fn() } };
+        const listEl = { current: (el !== null && el !== void 0 ? el : null) };
+        return { api: new TreeApi(store, { data }, list, listEl), list, listEl };
+    }
+    test("scrollToOffset forwards the offset to the underlying list", () => {
+        const { api, list } = setup();
+        api.scrollToOffset(120);
+        expect(list.current.scrollTo).toHaveBeenCalledWith(120);
+    });
+    test("scrollToOffset clamps negative offsets to the top", () => {
+        const { api, list } = setup();
+        api.scrollToOffset(-50);
+        expect(list.current.scrollTo).toHaveBeenCalledWith(0);
+    });
+    test("scrollToOffset coerces non-finite offsets to the top", () => {
+        const { api, list } = setup();
+        api.scrollToOffset(NaN);
+        api.scrollToOffset(Infinity);
+        expect(list.current.scrollTo).toHaveBeenNthCalledWith(1, 0);
+        expect(list.current.scrollTo).toHaveBeenNthCalledWith(2, 0);
+    });
+    test("scrollOffset reads the list element's scrollTop", () => {
+        const { api } = setup({ scrollTop: 80 });
+        expect(api.scrollOffset).toBe(80);
+    });
+    test("scrollOffset is 0 before the list element mounts", () => {
+        const { api } = setup();
+        expect(api.scrollOffset).toBe(0);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-arborist",
-  "version": "3.10.6",
+  "version": "3.11.0",
   "keywords": [
     "arborist",
     "dnd",

package/src/interfaces/tree-api.test.ts

@@ -244,3 +244,44 @@ describe("scrollTo brings a deeply nested node into view horizontally (#220)", (
     expect(el.scrollLeft).toBe(0);
   });
 });
+
+describe("scrollToOffset / scrollOffset set and read the vertical position (#194)", () => {
+  const data = [{ id: "a" }, { id: "b" }, { id: "c" }];
+
+  function setup(el?: Partial<HTMLDivElement>) {
+    const store = createStore(rootReducer);
+    const list = { current: { scrollTo: jest.fn() } as any };
+    const listEl = { current: (el ?? null) as HTMLDivElement | null };
+    return { api: new TreeApi(store, { data }, list, listEl), list, listEl };
+  }
+
+  test("scrollToOffset forwards the offset to the underlying list", () => {
+    const { api, list } = setup();
+    api.scrollToOffset(120);
+    expect(list.current.scrollTo).toHaveBeenCalledWith(120);
+  });
+
+  test("scrollToOffset clamps negative offsets to the top", () => {
+    const { api, list } = setup();
+    api.scrollToOffset(-50);
+    expect(list.current.scrollTo).toHaveBeenCalledWith(0);
+  });
+
+  test("scrollToOffset coerces non-finite offsets to the top", () => {
+    const { api, list } = setup();
+    api.scrollToOffset(NaN);
+    api.scrollToOffset(Infinity);
+    expect(list.current.scrollTo).toHaveBeenNthCalledWith(1, 0);
+    expect(list.current.scrollTo).toHaveBeenNthCalledWith(2, 0);
+  });
+
+  test("scrollOffset reads the list element's scrollTop", () => {
+    const { api } = setup({ scrollTop: 80 });
+    expect(api.scrollOffset).toBe(80);
+  });
+
+  test("scrollOffset is 0 before the list element mounts", () => {
+    const { api } = setup();
+    expect(api.scrollOffset).toBe(0);
+  });
+});

package/src/interfaces/tree-api.ts

@@ -707,6 +707,24 @@ export class TreeApi<T> {
     }
   }
 
+  /**
+   * Scroll the list vertically to an exact pixel offset from the top. This is
+   * the offset-based counterpart to scrollTo(), handy for saving and restoring
+   * a scroll position (#194). Negative values are clamped to the top; react-
+   * window clamps the upper bound to the scrollable range.
+   */
+  scrollToOffset(offset: number) {
+    /* Coerce non-finite offsets (NaN/Infinity, easy to get from malformed
+       persisted state) to the top rather than forwarding them to the list. */
+    const safe = Number.isFinite(offset) ? Math.max(0, offset) : 0;
+    this.list.current?.scrollTo(safe);
+  }
+
+  /** The list's current vertical scroll offset, in pixels from the top. */
+  get scrollOffset(): number {
+    return this.listEl.current?.scrollTop ?? 0;
+  }
+
   /* State Checks */
 
   get isEditing() {