@lotics/ui 17.0.2 → 18.1.0

package/src/use_section_nav.test.ts

@@ -4,7 +4,13 @@ import { act, renderHook } from "@testing-library/react";
 import { useSectionNav } from "./use_section_nav";
 import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent } from "react-native";
 
-const layoutAt = (y: number) => ({ nativeEvent: { layout: { y } } }) as LayoutChangeEvent;
+// RN-web's layout event carries the measured node as `nativeEvent.target`; RN's
+// own (native-only) types don't model it, so it goes on after the cast.
+const layoutAt = (y: number, target?: Element) => {
+  const e = { nativeEvent: { layout: { y } } } as LayoutChangeEvent;
+  if (target) Object.assign(e.nativeEvent, { target });
+  return e;
+};
 const scrollTo = (y: number) => ({ nativeEvent: { contentOffset: { y } } }) as NativeSyntheticEvent<NativeScrollEvent>;
 
 function mounted() {
@@ -17,6 +23,68 @@ function mounted() {
   return hook;
 }
 
+const rect = (top: number): DOMRect => ({
+  top,
+  bottom: top,
+  left: 0,
+  right: 0,
+  width: 0,
+  height: 0,
+  x: 0,
+  y: top,
+  toJSON: () => ({}),
+});
+
+/**
+ * A web page in miniature: a scroll container pinned at the viewport top plus
+ * section nodes sitting at live content offsets. `scrolledTo` moves the scroll
+ * position and every rect together (as a browser does), `shift` is the async
+ * content growth that moves sections WITHOUT an `onLayout` — the case a cached
+ * offset cannot see. A detached node measures as 0, like a real one.
+ */
+function webPage<K extends string>(keys: readonly K[], contentY: Record<K, number>) {
+  let scrollY = 0;
+  let live: Record<K, number> = { ...contentY };
+  const node = document.createElement("div");
+  document.body.appendChild(node);
+  Object.defineProperty(node, "scrollTop", { get: () => scrollY });
+  node.getBoundingClientRect = () => rect(0);
+  const els = {} as Record<K, HTMLElement>;
+  for (const key of keys) {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    el.getBoundingClientRect = () => (el.isConnected ? rect(live[key] - scrollY) : rect(0));
+    els[key] = el;
+  }
+  return {
+    node,
+    els,
+    shift: (next: Partial<Record<K, number>>) => {
+      live = { ...live, ...next };
+    },
+    scrolledTo: (y: number) => {
+      scrollY = y;
+      return scrollTo(y);
+    },
+  };
+}
+
+/** The registered page above, wired to a hook whose `scrollTo` calls are recorded. */
+function webMounted(contentY: Record<"a" | "b" | "c", number>) {
+  const keys = ["a", "b", "c"] as const;
+  const page = webPage(keys, contentY);
+  const calls: { y: number }[] = [];
+  const hook = renderHook(() => useSectionNav(keys));
+  (hook.result.current.scrollRef as { current: unknown }).current = {
+    getScrollableNode: () => page.node,
+    scrollTo: (opts: { y: number }) => calls.push(opts),
+  };
+  act(() => {
+    for (const key of keys) hook.result.current.register(key)(layoutAt(contentY[key], page.els[key]));
+  });
+  return { result: hook.result, page, calls };
+}
+
 describe("useSectionNav", () => {
   it("starts on the first key", () => {
     const { result } = renderHook(() => useSectionNav(["a", "b"] as const));
@@ -66,4 +134,38 @@ describe("useSectionNav", () => {
     act(() => result.current.jumpTo("a"));
     expect(calls[1]?.y).toBe(0);
   });
+
+  it("on web the highlight follows content that shifted after layout", () => {
+    const { result, page } = webMounted({ a: 0, b: 400, c: 900 });
+    act(() => result.current.onScroll(page.scrolledTo(321)));
+    expect(result.current.activeKey).toBe("b");
+
+    // a table above b finishes loading and pushes everything below it down 300px
+    page.shift({ b: 700, c: 1200 });
+    act(() => result.current.onScroll(page.scrolledTo(321)));
+    expect(result.current.activeKey).toBe("a");
+    act(() => result.current.onScroll(page.scrolledTo(700)));
+    expect(result.current.activeKey).toBe("b");
+
+    // and back: content above collapses, pulling the sections up again
+    page.shift({ b: 200, c: 500 });
+    act(() => result.current.onScroll(page.scrolledTo(450)));
+    expect(result.current.activeKey).toBe("c");
+  });
+
+  it("on web jumpTo lands on the section's shifted position", () => {
+    const { result, page, calls } = webMounted({ a: 0, b: 400, c: 900 });
+    page.shift({ b: 700 });
+    act(() => result.current.jumpTo("b"));
+    expect(calls[0]?.y).toBe(688);
+  });
+
+  it("a section removed from the DOM keeps its last offset instead of measuring as the page top", () => {
+    const { result, page } = webMounted({ a: 0, b: 400, c: 900 });
+    page.els.c.remove();
+    // 500 + 80 = 580: past b, still short of c — a detached c measured live
+    // would read as the current scroll position and steal the highlight.
+    act(() => result.current.onScroll(page.scrolledTo(500)));
+    expect(result.current.activeKey).toBe("b");
+  });
 });

package/src/use_section_nav.ts

@@ -4,7 +4,7 @@ import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, Scroll
 export interface SectionNavHandle<K extends string> {
   /** Attach to the content `ScrollView` (with `onScroll` + `scrollEventThrottle={16}`). */
   scrollRef: RefObject<ScrollView | null>;
-  /** The section the scroll currently sits in — drives the rail's `selected`. */
+  /** The section the scroll currently sits in — drives the rail item's `current`. */
   activeKey: K;
   /** `onLayout={register(key)}` on each section wrapper. The wrapper must be a
    *  DIRECT child of the ScrollView content (layout.y is content-relative). */
@@ -21,28 +21,30 @@ export interface SectionNavHandle<K extends string> {
  * top has passed the viewport edge is the active one).
  *
  *   const nav = useSectionNav(["details", "gatein", "gateout"] as const);
- *   <MenuButton title="Gate in" selected={nav.activeKey === "gatein"}
+ *   <MenuButton title="Gate in" current={nav.activeKey === "gatein"}
  *               onPress={() => nav.jumpTo("gatein")} />
  *   <ScrollView ref={nav.scrollRef} onScroll={nav.onScroll} scrollEventThrottle={16}>
  *     <View onLayout={nav.register("gatein")}>…</View>
  *
+ * A rail item is the CURRENT item in a set of navigation links, so it takes
+ * `current` (→ `aria-current`), never `selected` (that is listbox selection).
+ *
  * Pass the keys in PAGE ORDER — the spy walks them top-down. Hide the rail on
  * narrow containers (the page still scrolls; the rail is a wide-screen aid).
  *
  * Contract: every key's section stays MOUNTED (an unmounted section leaves its
  * last offset registered — conditional sections belong inside an always-mounted
- * wrapper that carries the `onLayout`). On WEB, `jumpTo` re-measures the live
- * DOM position, so async content growing ABOVE a section (a photo grid, a
- * late-loading table) can never stale a jump; the cached offsets only drive
- * the scroll-spy highlight, which self-corrects as jumps refresh them. On
- * native there is no re-measure — content above should settle before precision
- * matters (`onLayout` won't refire on a pure position shift).
+ * wrapper that carries the `onLayout`). On WEB both the jump AND the highlight
+ * read the live DOM position, so async content growing ABOVE a section (a photo
+ * grid, a late-loading table) can never stale either. On native there is no
+ * re-measure — content above should settle before precision matters
+ * (`onLayout` won't refire on a pure position shift).
  */
 export function useSectionNav<K extends string>(keys: readonly [K, ...K[]]): SectionNavHandle<K> {
   const scrollRef = useRef<ScrollView>(null);
   const sectionY = useRef<Partial<Record<K, number>>>({});
   // The registered wrapper's DOM node (web only) — RN-web's layout event
-  // exposes it as `nativeEvent.target`, which lets jumpTo re-measure live.
+  // exposes it as `nativeEvent.target`, which lets us re-measure live.
   const sectionEl = useRef<Partial<Record<K, Element>>>({});
   const [activeKey, setActiveKey] = useState<K>(keys[0]);
   const register = (key: K) => (e: LayoutChangeEvent) => {
@@ -50,27 +52,52 @@ export function useSectionNav<K extends string>(keys: readonly [K, ...K[]]): Sec
     const target: unknown = (e.nativeEvent as { target?: unknown }).target;
     if (typeof Element !== "undefined" && target instanceof Element) sectionEl.current[key] = target;
   };
-  /** The section's CURRENT content-relative offset — measured live on web
-   *  (immune to async content shifting the page), cached `layout.y` otherwise. */
-  const currentY = (key: K): number => {
-    const el = sectionEl.current[key];
+  /**
+   * The sections' CURRENT content-relative offsets: refreshed from the live DOM
+   * on web, the cached `layout.y` otherwise. THE source of truth for both the
+   * jump and the highlight — a spy reading a different number than the jump is
+   * a spy that points at the wrong section.
+   *
+   * WHY measure on every scroll event rather than trust the cache: `onLayout`
+   * does not refire when a section merely MOVES, so any async shift above it (a
+   * table finishing load, a disclosure opening, an image settling) strands the
+   * cache and the rail highlights the wrong section until something re-measures.
+   *
+   * WHY that is not the per-frame layout thrash it looks like: reading a rect
+   * forces a reflow only while layout is DIRTY — which is exactly the case where
+   * the cache would have lied. A pure scroll dirties no layout, so these reads
+   * hit a clean tree and cost about a property access. The pass only READS
+   * (container once, then each section), so a dirty frame costs ONE flush for
+   * all sections, not one per section. Coalescing behind rAF was rejected: it
+   * cannot beat "free when nothing changed", and it would make the highlight
+   * lag the scroll by a frame while adding a cancel-on-unmount lifecycle.
+   */
+  const measure = (): Partial<Record<K, number>> => {
     const sv = scrollRef.current as (ScrollView & { getScrollableNode?: () => unknown }) | null;
     const sc = typeof sv?.getScrollableNode === "function" ? sv.getScrollableNode() : null;
-    if (typeof Element !== "undefined" && el instanceof Element && sc instanceof Element) {
-      const y = el.getBoundingClientRect().top - sc.getBoundingClientRect().top + sc.scrollTop;
-      sectionY.current[key] = y; // refresh the spy's cache while we're here
-      return y;
+    if (typeof Element === "undefined" || !(sc instanceof Element)) return sectionY.current;
+    // The content origin in viewport coordinates; a section's top minus it is
+    // the content-relative offset both `scrollTo` and the spy speak in.
+    const origin = sc.getBoundingClientRect().top - sc.scrollTop;
+    for (const k of keys) {
+      const el = sectionEl.current[k];
+      // A detached node measures as 0, which would pin the spy to the last
+      // section — a section that broke the mounted contract keeps its last
+      // known offset instead, exactly as it does on native.
+      if (el?.isConnected) sectionY.current[k] = el.getBoundingClientRect().top - origin;
     }
-    return sectionY.current[key] ?? 0;
+    return sectionY.current;
   };
   const jumpTo = (key: K) => {
-    scrollRef.current?.scrollTo({ y: Math.max(0, currentY(key) - 12), animated: true });
+    const y = measure()[key] ?? 0;
+    scrollRef.current?.scrollTo({ y: Math.max(0, y - 12), animated: true });
   };
   const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
     const y = e.nativeEvent.contentOffset.y + 80;
+    const offsets = measure();
     let cur: K = keys[0];
     for (const k of keys) {
-      const sy = sectionY.current[k];
+      const sy = offsets[k];
       if (sy != null && sy <= y) cur = k;
     }
     if (cur !== activeKey) setActiveKey(cur);