react-arborist 3.10.5 → 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

@@ -229,6 +229,21 @@ export declare class TreeApi<T> {
     openAll(): void;
     closeAll(): void;
     scrollTo(identity: Identity | T, align?: Align): Promise<void> | undefined;
+    /**
+     * Horizontally scroll the list so the node's indented content is in view.
+     * A no-op when the list doesn't overflow horizontally (the common case), so
+     * 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

@@ -683,11 +683,56 @@ class TreeApi {
             if (index === undefined)
                 return;
             (_a = this.list.current) === null || _a === void 0 ? void 0 : _a.scrollToItem(index, align);
+            /* react-window only scrolls vertically. A deeply nested node is
+               indented by level * indent and can sit past the right edge when rows
+               overflow horizontally, so bring it into view ourselves (#220). */
+            this.scrollToNodeHorizontally(this.get(id));
         })
             .catch(() => {
             // Id: ${id} never appeared in the list.
         });
     }
+    /**
+     * Horizontally scroll the list so the node's indented content is in view.
+     * A no-op when the list doesn't overflow horizontally (the common case), so
+     * it never disturbs scrolling for trees that fit their width.
+     */
+    scrollToNodeHorizontally(node) {
+        const el = this.listEl.current;
+        if (!node || !el)
+            return;
+        const maxScroll = el.scrollWidth - el.clientWidth;
+        if (maxScroll <= 0)
+            return; // nothing to scroll
+        const left = node.level * this.indent;
+        const viewLeft = el.scrollLeft;
+        const viewRight = el.scrollLeft + el.clientWidth;
+        /* The visible range is half-open [viewLeft, viewRight): a pixel at viewRight
+           is already clipped. Only move when the node's indentation falls outside
+           it, aligning its content start to the left edge so the label is revealed,
+           clamped to the list's scrollable range. */
+        if (left < viewLeft || left >= viewRight) {
+            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

@@ -167,3 +167,89 @@ describe("onSelect fires exactly once per selection method (#332)", () => {
         expect(onSelect).toHaveBeenCalledTimes(1);
     });
 });
+describe("scrollTo brings a deeply nested node into view horizontally (#220)", () => {
+    // A folder tree where "deep" sits at level 2 (indented 2 * 24 = 48px).
+    const nestedData = [{ id: "root", children: [{ id: "mid", children: [{ id: "deep" }] }] }];
+    // react-window's scrollToItem only scrolls vertically; the horizontal scroll
+    // happens on the outer list element, which we stub here.
+    function setupWithListEl(el) {
+        const store = (0, redux_1.createStore)(root_reducer_1.rootReducer);
+        const list = { current: { scrollToItem: jest.fn() } };
+        const listEl = { current: el };
+        return new tree_api_1.TreeApi(store, { data: nestedData }, list, listEl);
+    }
+    test("scrolls right when the node is past the right edge", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 500, clientWidth: 40, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        // Aligns the node's indentation start (level 2 * indent 24) to the left edge.
+        expect(el.scrollLeft).toBe(48);
+    }));
+    test("scrolls left when the node is past the left edge", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 500, clientWidth: 100, scrollLeft: 200 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(48);
+    }));
+    test("scrolls when the node's start sits exactly on the right edge", () => __awaiter(void 0, void 0, void 0, function* () {
+        // viewRight === left (48): the visible range is half-open, so the content
+        // start is already clipped and must be scrolled into view.
+        const el = { scrollWidth: 500, clientWidth: 48, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(48);
+    }));
+    test("clamps the target to the maximum scrollable distance", () => __awaiter(void 0, void 0, void 0, function* () {
+        // left (48) exceeds maxScroll (60 - 40 = 20), so scrollLeft is clamped.
+        const el = { scrollWidth: 60, clientWidth: 40, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(20);
+    }));
+    test("leaves scroll untouched when the node is already in view", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 500, clientWidth: 200, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(0);
+    }));
+    test("no-ops when the list does not overflow horizontally", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 100, clientWidth: 100, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        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

@@ -229,6 +229,21 @@ export declare class TreeApi<T> {
     openAll(): void;
     closeAll(): void;
     scrollTo(identity: Identity | T, align?: Align): Promise<void> | undefined;
+    /**
+     * Horizontally scroll the list so the node's indented content is in view.
+     * A no-op when the list doesn't overflow horizontally (the common case), so
+     * 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

@@ -657,11 +657,56 @@ export class TreeApi {
             if (index === undefined)
                 return;
             (_a = this.list.current) === null || _a === void 0 ? void 0 : _a.scrollToItem(index, align);
+            /* react-window only scrolls vertically. A deeply nested node is
+               indented by level * indent and can sit past the right edge when rows
+               overflow horizontally, so bring it into view ourselves (#220). */
+            this.scrollToNodeHorizontally(this.get(id));
         })
             .catch(() => {
             // Id: ${id} never appeared in the list.
         });
     }
+    /**
+     * Horizontally scroll the list so the node's indented content is in view.
+     * A no-op when the list doesn't overflow horizontally (the common case), so
+     * it never disturbs scrolling for trees that fit their width.
+     */
+    scrollToNodeHorizontally(node) {
+        const el = this.listEl.current;
+        if (!node || !el)
+            return;
+        const maxScroll = el.scrollWidth - el.clientWidth;
+        if (maxScroll <= 0)
+            return; // nothing to scroll
+        const left = node.level * this.indent;
+        const viewLeft = el.scrollLeft;
+        const viewRight = el.scrollLeft + el.clientWidth;
+        /* The visible range is half-open [viewLeft, viewRight): a pixel at viewRight
+           is already clipped. Only move when the node's indentation falls outside
+           it, aligning its content start to the left edge so the label is revealed,
+           clamped to the list's scrollable range. */
+        if (left < viewLeft || left >= viewRight) {
+            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

@@ -165,3 +165,89 @@ describe("onSelect fires exactly once per selection method (#332)", () => {
         expect(onSelect).toHaveBeenCalledTimes(1);
     });
 });
+describe("scrollTo brings a deeply nested node into view horizontally (#220)", () => {
+    // A folder tree where "deep" sits at level 2 (indented 2 * 24 = 48px).
+    const nestedData = [{ id: "root", children: [{ id: "mid", children: [{ id: "deep" }] }] }];
+    // react-window's scrollToItem only scrolls vertically; the horizontal scroll
+    // happens on the outer list element, which we stub here.
+    function setupWithListEl(el) {
+        const store = createStore(rootReducer);
+        const list = { current: { scrollToItem: jest.fn() } };
+        const listEl = { current: el };
+        return new TreeApi(store, { data: nestedData }, list, listEl);
+    }
+    test("scrolls right when the node is past the right edge", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 500, clientWidth: 40, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        // Aligns the node's indentation start (level 2 * indent 24) to the left edge.
+        expect(el.scrollLeft).toBe(48);
+    }));
+    test("scrolls left when the node is past the left edge", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 500, clientWidth: 100, scrollLeft: 200 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(48);
+    }));
+    test("scrolls when the node's start sits exactly on the right edge", () => __awaiter(void 0, void 0, void 0, function* () {
+        // viewRight === left (48): the visible range is half-open, so the content
+        // start is already clipped and must be scrolled into view.
+        const el = { scrollWidth: 500, clientWidth: 48, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(48);
+    }));
+    test("clamps the target to the maximum scrollable distance", () => __awaiter(void 0, void 0, void 0, function* () {
+        // left (48) exceeds maxScroll (60 - 40 = 20), so scrollLeft is clamped.
+        const el = { scrollWidth: 60, clientWidth: 40, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(20);
+    }));
+    test("leaves scroll untouched when the node is already in view", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 500, clientWidth: 200, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        expect(el.scrollLeft).toBe(0);
+    }));
+    test("no-ops when the list does not overflow horizontally", () => __awaiter(void 0, void 0, void 0, function* () {
+        const el = { scrollWidth: 100, clientWidth: 100, scrollLeft: 0 };
+        const api = setupWithListEl(el);
+        yield api.scrollTo("deep");
+        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.5",
+  "version": "3.11.0",
   "keywords": [
     "arborist",
     "dnd",

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

@@ -184,3 +184,104 @@ describe("onSelect fires exactly once per selection method (#332)", () => {
     expect(onSelect).toHaveBeenCalledTimes(1);
   });
 });
+
+describe("scrollTo brings a deeply nested node into view horizontally (#220)", () => {
+  // A folder tree where "deep" sits at level 2 (indented 2 * 24 = 48px).
+  const nestedData = [{ id: "root", children: [{ id: "mid", children: [{ id: "deep" }] }] }];
+
+  // react-window's scrollToItem only scrolls vertically; the horizontal scroll
+  // happens on the outer list element, which we stub here.
+  function setupWithListEl(el: Partial<HTMLDivElement>) {
+    const store = createStore(rootReducer);
+    const list = { current: { scrollToItem: jest.fn() } as any };
+    const listEl = { current: el as HTMLDivElement };
+    return new TreeApi(store, { data: nestedData }, list, listEl);
+  }
+
+  test("scrolls right when the node is past the right edge", async () => {
+    const el = { scrollWidth: 500, clientWidth: 40, scrollLeft: 0 };
+    const api = setupWithListEl(el);
+    await api.scrollTo("deep");
+    // Aligns the node's indentation start (level 2 * indent 24) to the left edge.
+    expect(el.scrollLeft).toBe(48);
+  });
+
+  test("scrolls left when the node is past the left edge", async () => {
+    const el = { scrollWidth: 500, clientWidth: 100, scrollLeft: 200 };
+    const api = setupWithListEl(el);
+    await api.scrollTo("deep");
+    expect(el.scrollLeft).toBe(48);
+  });
+
+  test("scrolls when the node's start sits exactly on the right edge", async () => {
+    // viewRight === left (48): the visible range is half-open, so the content
+    // start is already clipped and must be scrolled into view.
+    const el = { scrollWidth: 500, clientWidth: 48, scrollLeft: 0 };
+    const api = setupWithListEl(el);
+    await api.scrollTo("deep");
+    expect(el.scrollLeft).toBe(48);
+  });
+
+  test("clamps the target to the maximum scrollable distance", async () => {
+    // left (48) exceeds maxScroll (60 - 40 = 20), so scrollLeft is clamped.
+    const el = { scrollWidth: 60, clientWidth: 40, scrollLeft: 0 };
+    const api = setupWithListEl(el);
+    await api.scrollTo("deep");
+    expect(el.scrollLeft).toBe(20);
+  });
+
+  test("leaves scroll untouched when the node is already in view", async () => {
+    const el = { scrollWidth: 500, clientWidth: 200, scrollLeft: 0 };
+    const api = setupWithListEl(el);
+    await api.scrollTo("deep");
+    expect(el.scrollLeft).toBe(0);
+  });
+
+  test("no-ops when the list does not overflow horizontally", async () => {
+    const el = { scrollWidth: 100, clientWidth: 100, scrollLeft: 0 };
+    const api = setupWithListEl(el);
+    await api.scrollTo("deep");
+    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

@@ -675,12 +675,56 @@ export class TreeApi<T> {
         const index = this.idToIndex[id];
         if (index === undefined) return;
         this.list.current?.scrollToItem(index, align);
+        /* react-window only scrolls vertically. A deeply nested node is
+           indented by level * indent and can sit past the right edge when rows
+           overflow horizontally, so bring it into view ourselves (#220). */
+        this.scrollToNodeHorizontally(this.get(id));
       })
       .catch(() => {
         // Id: ${id} never appeared in the list.
       });
   }
 
+  /**
+   * Horizontally scroll the list so the node's indented content is in view.
+   * A no-op when the list doesn't overflow horizontally (the common case), so
+   * it never disturbs scrolling for trees that fit their width.
+   */
+  private scrollToNodeHorizontally(node: NodeApi<T> | null) {
+    const el = this.listEl.current;
+    if (!node || !el) return;
+    const maxScroll = el.scrollWidth - el.clientWidth;
+    if (maxScroll <= 0) return; // nothing to scroll
+    const left = node.level * this.indent;
+    const viewLeft = el.scrollLeft;
+    const viewRight = el.scrollLeft + el.clientWidth;
+    /* The visible range is half-open [viewLeft, viewRight): a pixel at viewRight
+       is already clipped. Only move when the node's indentation falls outside
+       it, aligning its content start to the left edge so the label is revealed,
+       clamped to the list's scrollable range. */
+    if (left < viewLeft || left >= viewRight) {
+      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: 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() {