@multiplatform.one/components 7.10.0 → 7.15.0

package/src/views/TreeView.reveal.spec.tsx

@@ -27,6 +27,13 @@ describe("TreeView public expansion contract", () => {
     expectTypeOf<TreeViewProps["revealRequest"]>().toEqualTypeOf<
       { id: string; requestId: number } | undefined
     >();
+    expectTypeOf<TreeViewProps["onRevealComplete"]>().toEqualTypeOf<
+      ((request: { id: string; requestId: number }) => void) | undefined
+    >();
+    expectTypeOf<TreeViewProps["initialScrollOffset"]>().toEqualTypeOf<number | undefined>();
+    expectTypeOf<TreeViewProps["onScrollOffsetChange"]>().toEqualTypeOf<
+      ((offset: number) => void) | undefined
+    >();
     expectTypeOf<TreeViewProps["expandedIds"]>().toEqualTypeOf<string[] | undefined>();
     expectTypeOf<TreeViewProps["onExpandedIdsChange"]>().toEqualTypeOf<
       ((ids: string[]) => void) | undefined

package/src/views/TreeView.reveal.stories.tsx

@@ -36,6 +36,10 @@ function RevealFixture(args: TreeViewProps) {
   const [expandedIds, setExpandedIds] = useState<string[]>(["other"]);
   const [selectedId, setSelectedId] = useState<string>();
   const [revealRequest, setRevealRequest] = useState<TreeViewProps["revealRequest"]>();
+  const [completion, setCompletion] = useState<{
+    request: NonNullable<TreeViewProps["revealRequest"]>;
+    count: number;
+  }>();
   const [deferExpansion, setDeferExpansion] = useState(false);
   const [pendingExpansion, setPendingExpansion] = useState<string[]>();
   const [hidden, setHidden] = useState(false);
@@ -77,6 +81,11 @@ function RevealFixture(args: TreeViewProps) {
       <Text>
         Target: {revealRequest?.id ?? "none"}. Expanded: {expandedIds.join(", ")}
       </Text>
+      <Text>
+        Measured completion:{" "}
+        {completion ? `${completion.request.id} (${completion.request.requestId})` : "none"}.
+        Callback count: {completion?.count ?? 0}
+      </Text>
       <YStack display={hidden ? "none" : "flex"}>
         <TreeView
           {...args}
@@ -88,6 +97,10 @@ function RevealFixture(args: TreeViewProps) {
           }}
           selectedId={selectedId}
           revealRequest={revealRequest}
+          onRevealComplete={(request) => {
+            setCompletion((previous) => ({ request, count: (previous?.count ?? 0) + 1 }));
+            args.onRevealComplete?.(request);
+          }}
           onNodeSelect={(node) => setSelectedId(node.id)}
           renderNode={(node) => {
             const index = Number(node.id.replace("item-", ""));
@@ -113,3 +126,124 @@ export const ControlledReveal: Story = {
   name: "Controlled reveal with 500 variable-height items",
   render: (args) => <RevealFixture {...args} />,
 };
+
+function RetainedScrollFixture(args: TreeViewProps) {
+  const [mounted, setMounted] = useState(true);
+  const [generation, setGeneration] = useState(0);
+  const [nodes, setNodes] = useState(folders);
+  const [hidden, setHidden] = useState(false);
+  const [taller, setTaller] = useState(false);
+  const [savedOffset, setSavedOffset] = useState<number>();
+  const [observations, setObservations] = useState(0);
+  const [expandedIds, setExpandedIds] = useState(["folders", "archive", "other"]);
+  const [revealRequest, setRevealRequest] = useState<TreeViewProps["revealRequest"]>();
+  const [completion, setCompletion] = useState<string>();
+  const sequence = useRef(0);
+  const revealLast = () => setRevealRequest({ id: "item-499", requestId: ++sequence.current });
+  return (
+    <YStack gap="$3" width="100%" maxWidth={700}>
+      <Text>
+        Scroll manually, unmount, then mount. The observed offset and expansion survive outside the
+        tree. Remount with delayed data or a hidden host to check deferred restoration.
+      </Text>
+      <XStack gap="$2" flexWrap="wrap">
+        <Button onPress={() => setMounted((value) => !value)}>
+          {mounted ? "Unmount tree" : "Mount tree"}
+        </Button>
+        <Button
+          onPress={() => {
+            setNodes([]);
+            setMounted(true);
+            setGeneration((value) => value + 1);
+          }}
+        >
+          Remount without data
+        </Button>
+        <Button onPress={() => setNodes(folders)}>Deliver data</Button>
+        <Button
+          onPress={() => {
+            setHidden(true);
+            setMounted(true);
+            setGeneration((value) => value + 1);
+          }}
+        >
+          Remount hidden
+        </Button>
+        <Button onPress={() => setHidden((value) => !value)}>
+          {hidden ? "Show tree" : "Hide tree"}
+        </Button>
+      </XStack>
+      <XStack gap="$2" flexWrap="wrap">
+        <Button onPress={revealLast}>Reveal last item</Button>
+        <Button
+          onPress={() => {
+            revealLast();
+            setMounted(true);
+            setGeneration((value) => value + 1);
+          }}
+        >
+          Remount with reveal
+        </Button>
+        <Button onPress={() => setTaller((value) => !value)}>
+          {taller ? "Use configured height" : "Double viewport height"}
+        </Button>
+      </XStack>
+      <Text>
+        Retained observed offset: {savedOffset ?? "none"}. Observations: {observations}.
+      </Text>
+      <Text>
+        Initial fallback: {args.initialScrollOffset ?? "none"}. Mounted: {String(mounted)}.
+      </Text>
+      <Text>
+        Pending reveal: {revealRequest?.requestId ?? "none"}. Measured completion:{" "}
+        {completion ?? "none"}.
+      </Text>
+      <YStack display={hidden ? "none" : "flex"}>
+        {mounted && (
+          <TreeView
+            {...args}
+            key={generation}
+            nodes={nodes}
+            height={taller ? (args.height ?? 240) * 2 : args.height}
+            expandedIds={expandedIds}
+            onExpandedIdsChange={setExpandedIds}
+            initialScrollOffset={savedOffset ?? args.initialScrollOffset}
+            onScrollOffsetChange={(offset) => {
+              setSavedOffset(offset);
+              setObservations((value) => value + 1);
+              args.onScrollOffsetChange?.(offset);
+            }}
+            revealRequest={revealRequest}
+            onRevealComplete={(request) => {
+              setCompletion(`${request.id} (${request.requestId})`);
+              setRevealRequest((pending) =>
+                pending?.requestId === request.requestId ? undefined : pending,
+              );
+              args.onRevealComplete?.(request);
+            }}
+            renderNode={(node) => {
+              const index = Number(node.id.replace("item-", ""));
+              return (
+                <YStack
+                  minHeight={Number.isFinite(index) && index % 2 ? 80 : 32}
+                  justifyContent="center"
+                >
+                  <Text>{node.label}</Text>
+                  {Number.isFinite(index) && index % 2 === 1 && (
+                    <Text fontSize="$2">Additional detail</Text>
+                  )}
+                </YStack>
+              );
+            }}
+          />
+        )}
+      </YStack>
+    </YStack>
+  );
+}
+
+export const RetainedScroll: Story = {
+  name: "Retained scroll across unmount and delayed layout",
+  args: { initialScrollOffset: 640.5, ariaLabel: "Retained scroll fixture" },
+  render: (args) => <RetainedScrollFixture {...args} />,
+};

package/src/views/TreeView.scroll-index.spec.tsx

@@ -0,0 +1,246 @@
+import type { FlashListProps, FlashListRef } from "@shopify/flash-list";
+import { act, cleanup, fireEvent, screen, waitFor } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, expect, it, vi } from "vitest";
+import { TreeView } from "./TreeView";
+
+const observed = vi.hoisted(() => ({ list: null as FlashListRef<unknown> | null }));
+vi.mock("@shopify/flash-list", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@shopify/flash-list")>();
+  const React = await import("react");
+  return {
+    ...actual,
+    FlashList: React.forwardRef<FlashListRef<unknown>, FlashListProps<unknown>>((props, ref) => {
+      const captureRef = React.useCallback(
+        (list: FlashListRef<unknown> | null) => {
+          observed.list = list;
+          if (typeof ref === "function") ref(list);
+          else if (ref) ref.current = list;
+        },
+        [ref],
+      );
+      return React.createElement(actual.FlashList, { ...props, ref: captureRef });
+    }),
+  };
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+it("reports no preparatory index offset while the actual scroll transport is deferred", async () => {
+  vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockReturnValue(320);
+  vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(240);
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+    x: 0,
+    y: 0,
+    top: 0,
+    left: 0,
+    right: 320,
+    bottom: 240,
+    width: 320,
+    height: 240,
+    toJSON: () => ({}),
+  });
+  const change = vi.fn();
+  renderWithProviders(
+    <TreeView
+      nodes={Array.from({ length: 100 }, (_, i) => ({ id: `row-${i}`, label: `Row ${i}` }))}
+      height={240}
+      onScrollOffsetChange={change}
+    />,
+  );
+  await waitFor(() => expect(observed.list?.getChildContainerDimensions().height).toBe(24000));
+  await waitFor(() => expect(change).toHaveBeenCalledWith(0));
+  expect(observed.list?.getWindowSize().height).toBe(240);
+  expect(observed.list?.getLayout(99)?.y).toBe(23760);
+  const native = observed.list!.getNativeScrollRef()!;
+  const transport = vi.spyOn(native, "scrollTo").mockImplementation(() => {});
+  const scroller = native.getScrollableNode();
+  const index = vi.spyOn(observed.list!, "scrollToIndex");
+  change.mockClear();
+  fireEvent.keyDown(screen.getByRole("tree"), { key: "End" });
+  expect(index).toHaveBeenCalledExactlyOnceWith({ index: 99, animated: true });
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 40));
+  });
+  expect(transport).toHaveBeenCalled();
+  expect(observed.list!.getAbsoluteLastScrollOffset()).toBeGreaterThan(0);
+  expect(scroller.scrollTop).toBe(0);
+  expect(change).not.toHaveBeenCalled();
+  await act(async () => {
+    await index.mock.results[0].value;
+  });
+  expect(change).not.toHaveBeenCalled();
+  fireEvent.scroll(scroller, { target: { scrollTop: 96.5 } });
+  await waitFor(() => expect(change).toHaveBeenCalledExactlyOnceWith(96.5));
+  change.mockClear();
+  fireEvent.keyDown(screen.getByRole("tree"), { key: "Home" });
+  expect(index).toHaveBeenLastCalledWith({ index: 0, animated: true });
+  await act(async () => {
+    await index.mock.results[1].value;
+  });
+  expect(change).not.toHaveBeenCalled();
+  fireEvent.scroll(scroller, { target: { scrollTop: 0 } });
+  await waitFor(() => expect(change).toHaveBeenCalledExactlyOnceWith(0));
+});
+
+it("positive control: actual scroll delivery reports the transported offset", async () => {
+  vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockReturnValue(320);
+  vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(240);
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+    x: 0,
+    y: 0,
+    top: 0,
+    left: 0,
+    right: 320,
+    bottom: 240,
+    width: 320,
+    height: 240,
+    toJSON: () => ({}),
+  });
+  const change = vi.fn();
+  renderWithProviders(
+    <TreeView
+      nodes={Array.from({ length: 100 }, (_, i) => ({ id: `row-${i}`, label: `Row ${i}` }))}
+      height={240}
+      onScrollOffsetChange={change}
+    />,
+  );
+  await waitFor(() => expect(observed.list?.getChildContainerDimensions().height).toBe(24000));
+  await waitFor(() => expect(change).toHaveBeenCalledWith(0));
+  change.mockClear();
+  const native = observed.list!.getNativeScrollRef()!;
+  const scroller = native.getScrollableNode();
+  fireEvent.scroll(scroller, { target: { scrollTop: 96.5 } });
+  await waitFor(() => expect(change).toHaveBeenCalledWith(96.5));
+});
+
+function dimensions() {
+  vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockReturnValue(320);
+  vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(240);
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(
+    function (this: HTMLElement) {
+      let y = 0;
+      for (let ancestor = this.parentElement; ancestor; ancestor = ancestor.parentElement) {
+        y -= ancestor.scrollTop;
+      }
+      return {
+        x: 0,
+        y,
+        top: y,
+        left: 0,
+        right: 320,
+        bottom: y + 240,
+        width: 320,
+        height: 240,
+        toJSON: () => ({}),
+      };
+    },
+  );
+}
+
+it.each([false, true])(
+  "acknowledges index-prepared reveal only after physical delivery (delivered: %s)",
+  async (delivered) => {
+    dimensions();
+    const nodes = Array.from({ length: 100 }, (_, i) => ({ id: `row-${i}`, label: `Row ${i}` }));
+    const change = vi.fn();
+    const complete = vi.fn();
+    const tree = renderWithProviders(
+      <TreeView
+        nodes={nodes}
+        height={240}
+        onScrollOffsetChange={change}
+        onRevealComplete={complete}
+      />,
+    );
+    await waitFor(() => expect(observed.list?.getChildContainerDimensions().height).toBe(24000));
+    await waitFor(() => expect(change).toHaveBeenCalledWith(0));
+    const native = observed.list!.getNativeScrollRef()!;
+    const transport = vi.spyOn(native, "scrollTo").mockImplementation(() => {});
+    const scroller = native.getScrollableNode();
+    const index = vi.spyOn(observed.list!, "scrollToIndex");
+    fireEvent.keyDown(screen.getByRole("tree"), { key: "End" });
+    await act(async () => {
+      await index.mock.results[0].value;
+    });
+    expect(transport).toHaveBeenCalled();
+    expect(scroller.scrollTop).toBe(0);
+    const offset = observed.list!.getAbsoluteLastScrollOffset();
+    const visible = observed.list!.computeVisibleIndices();
+    const id = `row-${visible.startIndex}`;
+    const layout = observed.list!.getLayout(visible.startIndex)!;
+    expect(offset).toBeGreaterThan(0);
+    expect(layout.isHeightMeasured).toBe(true);
+    expect(screen.queryByText(`Row ${visible.startIndex}`)).not.toBeNull();
+    if (delivered) {
+      fireEvent.scroll(scroller, { target: { scrollTop: offset } });
+      expect(scroller.scrollTop).toBe(offset);
+      await waitFor(() => expect(change).toHaveBeenCalledWith(offset));
+    }
+    transport.mockClear();
+    tree.rerender(
+      <TreeView
+        nodes={nodes}
+        height={240}
+        onScrollOffsetChange={change}
+        onRevealComplete={complete}
+        revealRequest={{ id, requestId: 71 }}
+      />,
+    );
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 60));
+    });
+    if (!delivered) {
+      expect(complete).not.toHaveBeenCalled();
+      expect(scroller.scrollTop).toBe(0);
+      expect(transport).toHaveBeenCalledWith({ x: 0, y: offset, animated: false });
+    } else {
+      expect(complete).toHaveBeenCalledExactlyOnceWith({ id, requestId: 71 });
+    }
+    fireEvent.scroll(scroller, { target: { scrollTop: offset } });
+    await waitFor(() => expect(complete).toHaveBeenCalledExactlyOnceWith({ id, requestId: 71 }));
+  },
+);
+
+it("reveals an observed keyboard destination without a retention callback", async () => {
+  dimensions();
+  const nodes = Array.from({ length: 100 }, (_, i) => ({ id: `row-${i}`, label: `Row ${i}` }));
+  const complete = vi.fn();
+  const tree = renderWithProviders(
+    <TreeView nodes={nodes} height={240} onRevealComplete={complete} />,
+  );
+  await waitFor(() => expect(observed.list?.getChildContainerDimensions().height).toBe(24000));
+  const list = observed.list!;
+  const native = list.getNativeScrollRef()!;
+  const transport = vi.spyOn(native, "scrollTo").mockImplementation(() => {});
+  const scroller = native.getScrollableNode();
+  const index = vi.spyOn(list, "scrollToIndex");
+  fireEvent.keyDown(screen.getByRole("tree"), { key: "End" });
+  await act(async () => {
+    await index.mock.results[0].value;
+  });
+  const target = list.computeVisibleIndices().endIndex;
+  const layout = list.getLayout(target)!;
+  const offset = layout.y + list.getFirstItemOffset();
+  expect(offset).toBeGreaterThan(list.getAbsoluteLastScrollOffset());
+  expect(layout.isHeightMeasured).toBe(true);
+  expect(screen.getByText(`Row ${target}`)).toBeTruthy();
+  fireEvent.scroll(scroller, { target: { scrollTop: offset } });
+  await waitFor(() => expect(list.getAbsoluteLastScrollOffset()).toBe(offset));
+  transport.mockClear();
+  const revealScroll = vi.spyOn(list, "scrollToOffset");
+  tree.rerender(
+    <TreeView
+      nodes={nodes}
+      height={240}
+      onRevealComplete={complete}
+      revealRequest={{ id: `row-${target}`, requestId: 72 }}
+    />,
+  );
+  await waitFor(() =>
+    expect(complete).toHaveBeenCalledExactlyOnceWith({ id: `row-${target}`, requestId: 72 }),
+  );
+  expect(revealScroll).not.toHaveBeenCalled();
+});