[trees][wip] Create a new /scroll export for a self-virtualizable file tree

[SlexAxton]

Summary

This PR introduces a dedicated @pierre/trees/scroll entry point for the
external-scroll integration.

The goal is to keep the normal @pierre/trees path focused on the built-in internal
scroller, while moving caller-owned scroll-container support behind an explicit
advanced import.

With this change:

• regular tree users stay on @pierre/trees
• external-scroll users opt into @pierre/trees/scroll
• React rendering stays reusable through @pierre/trees/react
• SSR preload for external-scroll trees also moves behind the scroll entry point
• the common DOM-scroller case now has a built-in helper: createDomScrollSource(...)

What this adds

New public entry point

@pierre/trees/scroll

It exports:

• FileTree
• preloadFileTree
• serializeFileTreeSsrPayload
• createDomScrollSource
• external-scroll types such as:
  • FileTreeExternalScrollSource
  • FileTreeExternalScrollSnapshot
  • FileTreeExternalScrollRequestContext
  • FileTreeExternalScrollModel

New external-scroll helper

createDomScrollSource(...)

This covers the common “tree inside a normal page scroller” case:

• tracks viewportTop relative to the tree host
• reports viewportHeight, topInset, and bottomInset
• subscribes to scroll/resize changes
• updates synchronously for programmatic reveal requests

React reuse without a separate /scroll/react

External-scroll models created from @pierre/trees/scroll can still render through:

• @pierre/trees/react
• existing selector/search/selection hooks

That means the advanced model is new, but the React view layer stays shared.

Behavioral change

External-scroll setup is no longer part of the root @pierre/trees surface.

If you were previously doing this through the root package:

• new FileTree({ externalScroll: ... })
• root SSR preload with externalScroll
• root exports of external-scroll types

you now need to move those integrations to @pierre/trees/scroll.

Normal internal-scroll trees are unchanged in how they are created and rendered.

How to use it

Vanilla / imperative usage

  import { FileTree, createDomScrollSource } from '@pierre/trees/scroll';

  const source = createDomScrollSource({
    scrollContainer: parentScroller,
    topInset: () => toolbar.getBoundingClientRect().height,
  });

  const tree = new FileTree({
    paths,
    stickyFolders: true,
    externalScroll: {
      initialSnapshot: source.getSnapshot(),
      source,
    },
  });

  tree.render({ containerWrapper: mount });

  const host = tree.getFileTreeContainer();
  source.setHost(host ?? null);

Cleanup:

  source.destroy();
  tree.cleanUp();

React usage

Create the model from @pierre/trees/scroll, but keep using the shared React component
from @pierre/trees/react.

  import {
    FileTree as ScrollFileTree,
    createDomScrollSource,
  } from '@pierre/trees/scroll';
  import { FileTree } from '@pierre/trees/react';

  const hostRef = useRef<HTMLElement>(null);

  const source = useMemo(
    () => createDomScrollSource({ scrollContainer: parentScroller }),
    [parentScroller]
  );

  const model = useMemo(
    () =>
      new ScrollFileTree({
        paths,
        stickyFolders: true,
        externalScroll: {
          initialSnapshot: source.getSnapshot(),
        },
      }),
    [paths, source]
  );

  useEffect(() => {
    return () => {
      model.cleanUp();
      source.destroy();
    };
  }, [model, source]);

  useLayoutEffect(() => {
    source.setHost(hostRef.current);
    model.setExternalScrollSource(source);
    return () => model.setExternalScrollSource(undefined);
  }, [model, source]);

  return <FileTree ref={hostRef} model={model} />;

SSR usage

Use the scroll entry point for preloading too:

  import { preloadFileTree } from '@pierre/trees/scroll';

  const payload = preloadFileTree({
    preparedInput,
    externalScroll: {
      initialSnapshot: {
        viewportTop: 0,
        viewportHeight: 480,
        topInset: 48,
      },
    },
    initialVisibleRowCount: 16,
  });

Contract for custom sources

If you implement your own FileTreeExternalScrollSource, the important contract is:

• viewportTop must be host-local
• scrollToViewportTop(nextTop, context) must update getSnapshot() synchronously before
  returning

That synchronous update matters because the tree recalculates layout immediately after
requesting scroll movement.

Why this split exists

This keeps the advanced external-scroll feature explicit and opt-in:

• normal users keep the simpler root API
• external-scroll users get a focused entry point and helper
• docs/tests/examples now show one consistent integration path

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pierrejs-diff-demo	Ready	Preview	Apr 28, 2026 4:03am
pierrejs-docs	Ready	Preview	Apr 28, 2026 4:03am

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f66cbbe8b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Compute viewportTop from the scrollport edge

createDomScrollSource currently derives viewportTop from scrollContainer.getBoundingClientRect().top, which is the container’s border-box top. For scroll containers with a non-zero top border, this reports a viewport that is shifted upward by the border width, so virtualization/sticky math and scrollToViewportTop(...) requests are consistently off by that amount. This shows up in common bordered panels and causes reveal positioning drift; use the scrollport edge (e.g. include clientTop) when computing the host-local viewport top.

Useful? React with 👍 / 👎.