panelui-native 0.89.0 → 0.90.0

package/src/hooks/index.ts

@@ -37,6 +37,7 @@ export {
 } from './use-skeleton-handoff';
 export {
   useScrollSections,
+  type ScrollSectionsPosition,
   type UseScrollSectionsOptions,
   type UseScrollSectionsResult,
 } from './use-scroll-sections';

package/src/hooks/use-scroll-sections.ts

@@ -23,6 +23,11 @@
  *
  * <SectionRail value={sections.active} onValueChange={sections.scrollTo}>…</SectionRail>
  * ```
+ *
+ * It also publishes the scroll position itself, as `scroll`, so a component
+ * that wants a percentage as well as a section name does not need a second
+ * scroll listener to get one. The three values are everything a fraction is
+ * made of, and they come out of the event this hook is already handling.
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type {
@@ -31,6 +36,7 @@ import type {
   NativeSyntheticEvent,
   ScrollView,
 } from 'react-native';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
 
 export interface UseScrollSectionsOptions {
   /** Section ids, in the order they appear down the page. */
@@ -46,15 +52,39 @@ export interface UseScrollSectionsOptions {
   scrollPadding?: number;
 }
 
+/**
+ * Where the scroller is, as shared values.
+ *
+ * Written from the scroll handler on the JavaScript thread, which is where the
+ * section tracking already runs — so they arrive at `scrollEventThrottle`
+ * rather than every frame, and anything reading them should ease towards the
+ * value rather than jumping to it.
+ */
+export interface ScrollSectionsPosition {
+  /** Distance scrolled, in points. */
+  offset: SharedValue<number>;
+  /** Height of the visible area. */
+  viewport: SharedValue<number>;
+  /** Total height of the content. */
+  content: SharedValue<number>;
+}
+
 export interface UseScrollSectionsResult {
   /** Attach to the ScrollView, so `scrollTo` has something to drive. */
   ref: React.RefObject<ScrollView | null>;
   /** The section being read. */
   active: string | undefined;
+  /**
+   * The scroll position, for anything that needs how far through the page the
+   * reader is rather than which part of it they are in.
+   */
+  scroll: ScrollSectionsPosition;
   /** Spread onto the ScrollView. */
   scrollProps: {
     onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     onMomentumScrollEnd: () => void;
+    onLayout: (event: LayoutChangeEvent) => void;
+    onContentSizeChange: (width: number, height: number) => void;
     scrollEventThrottle: number;
   };
   /** `onLayout` for a section's wrapper: `onLayout={measure(id)}`. */
@@ -81,6 +111,10 @@ export function useScrollSections({
   const settle = useRef<ReturnType<typeof setTimeout> | null>(null);
   const [active, setActive] = useState<string | undefined>(ids[0]);
 
+  const scrollOffset = useSharedValue(0);
+  const viewport = useSharedValue(0);
+  const content = useSharedValue(0);
+
   // Read inside the scroll handler, which must not be re-created on every
   // render — a new handler each frame would defeat the throttle.
   const idsRef = useRef(ids);
@@ -107,10 +141,24 @@ export function useScrollSections({
 
   const onScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
+
+      /*
+       * The position is published before the jump guard, not after it.
+       *
+       * A jump is still travel: the page really is moving under the reader, and
+       * a progress indicator that froze for the length of the animation would
+       * be reporting something that is not true. What the guard protects is the
+       * *section*, which the reader chose and which should not flicker through
+       * every heading the scroll passes on the way there.
+       */
+      scrollOffset.value = contentOffset.y;
+      viewport.value = layoutMeasurement.height;
+      content.value = contentSize.height;
+
       // Mid-jump, the position is the animation's and not the reader's.
       if (jumpingTo.current !== null) return;
 
-      const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
       const list = idsRef.current;
       if (!list.length) return;
 
@@ -129,7 +177,27 @@ export function useScrollSections({
       }
       setActive(current);
     },
-    [offset, endThreshold]
+    [offset, endThreshold, scrollOffset, viewport, content]
+  );
+
+  /*
+   * Seeded at layout as well as on scroll, so a page that has not been touched
+   * yet still reports a viewport and a content height. Without these the
+   * fraction is zero over zero until the first scroll event, and anything
+   * drawing it starts by being wrong rather than by being empty.
+   */
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      viewport.value = event.nativeEvent.layout.height;
+    },
+    [viewport]
+  );
+
+  const onContentSizeChange = useCallback(
+    (_width: number, height: number) => {
+      content.value = height;
+    },
+    [content]
   );
 
   const scrollTo = useCallback(
@@ -168,9 +236,20 @@ export function useScrollSections({
   );
 
   const scrollProps = useMemo(
-    () => ({ onScroll, onMomentumScrollEnd, scrollEventThrottle: 16 }),
-    [onScroll, onMomentumScrollEnd]
+    () => ({
+      onScroll,
+      onMomentumScrollEnd,
+      onLayout,
+      onContentSizeChange,
+      scrollEventThrottle: 16,
+    }),
+    [onScroll, onMomentumScrollEnd, onLayout, onContentSizeChange]
+  );
+
+  const scroll = useMemo<ScrollSectionsPosition>(
+    () => ({ offset: scrollOffset, viewport, content }),
+    [scrollOffset, viewport, content]
   );
 
-  return { ref, active, scrollProps, measure, scrollTo };
+  return { ref, active, scroll, scrollProps, measure, scrollTo };
 }

package/src/index.ts

@@ -386,6 +386,14 @@ export {
   type SectionRailPlacement,
   type SectionRailAlign,
 } from './components/section-rail';
+export {
+  SectionProgress,
+  type SectionProgressProps,
+  type SectionProgressItemProps,
+  type SectionProgressPlacement,
+  type SectionProgressColor,
+  type SectionProgressScroll,
+} from './components/section-progress';
 export {
   Tabs,
   type TabsProps,