panelui-native 0.66.1 → 0.71.0

package/src/components/marquee/index.tsx

@@ -0,0 +1,232 @@
+/**
+ * Marquee — content that travels across its container and never runs out.
+ *
+ * For a strip of logos, a ticker of prices, a row of testimonials: anything
+ * whose job is to keep moving past a boundary rather than to be scrolled.
+ *
+ * ```tsx
+ * <Marquee spacing={24} speed={40}>
+ *   <View className="flex-row gap-6">
+ *     {sponsors.map((s) => <Logo key={s.id} src={s.logo} />)}
+ *   </View>
+ * </Marquee>
+ * ```
+ *
+ * ## How it loops
+ *
+ * The content is measured once, then laid out end to end enough times to cover
+ * the container twice over. One track holds every copy and it is that track,
+ * not the copies, that moves — a single animated node for any amount of
+ * content. It travels exactly one copy-and-gap and starts over, so the state it
+ * ends on is the state it began on and the seam never shows.
+ *
+ * The travel is a linear timing driven on the UI thread, so it costs nothing
+ * per frame in JavaScript and keeps running while the thread is busy.
+ *
+ * ## Measurement needs room
+ *
+ * The copy that gets measured sits in a hidden scroller, because that is what
+ * lets the content report the width it *wants* rather than the width the
+ * container would give it. Content with no intrinsic size of its own — a child
+ * stretched to `flex-1`, an image with no dimensions — measures as nothing and
+ * the marquee will not start.
+ *
+ * ## Reading direction and reduced motion
+ *
+ * A horizontal marquee travels toward the end of the line, so it reverses in a
+ * right-to-left subtree. `reverse` flips it again from wherever it landed.
+ *
+ * With the operating system set to reduce motion the content is rendered once
+ * and held still. A ticker that never stops is the exact thing that setting is
+ * there to turn off, so this is not a shorter animation — it is none.
+ *
+ * Screen readers get one copy. The rest are duplicates of content already
+ * announced, and hearing a sponsor list four times over is not thoroughness.
+ */
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
+import {
+  ScrollView,
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
+import Animated, {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import { useDirectionSign } from '../../hooks/use-direction';
+import { cn } from '../../utils/cn';
+
+/**
+ * Points per second. Slow enough that a word stays readable as it crosses,
+ * which is the speed a ticker is actually for.
+ */
+const DEFAULT_SPEED = 40;
+
+export type MarqueeDirection = 'horizontal' | 'vertical';
+
+export interface MarqueeProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /** The content to repeat. Measured once, then tiled along the axis. */
+  children: ReactNode;
+  /**
+   * Travel speed in points per second. 40 by default, which is slow enough
+   * that a word stays readable as it crosses. The cycle time follows from this
+   * and the measured content, so longer content takes proportionally longer
+   * rather than moving faster.
+   */
+  speed?: number;
+  /** Gap between the end of one copy and the start of the next. */
+  spacing?: number;
+  /** Axis the content travels along. */
+  direction?: MarqueeDirection;
+  /**
+   * Send it the other way: toward the start of the line, or upward. Applied
+   * after the reading direction, not instead of it.
+   */
+  reverse?: boolean;
+  /** Set false to hold the content where it is. */
+  playing?: boolean;
+}
+
+export function Marquee({
+  className,
+  children,
+  speed = DEFAULT_SPEED,
+  spacing = 0,
+  direction = 'horizontal',
+  reverse = false,
+  playing = true,
+  style,
+  onLayout,
+  ...props
+}: MarqueeProps) {
+  const horizontal = direction === 'horizontal';
+  const reducedMotion = useReducedMotion();
+  // Only the horizontal axis has a reading direction to follow; up is up.
+  const sign = useDirectionSign();
+  const flip = horizontal ? sign : 1;
+
+  const [viewport, setViewport] = useState(0);
+  const [content, setContent] = useState(0);
+
+  // The distance from one copy to the same point on the next, and therefore
+  // both the layout step and the exact loop length. They are the same number
+  // on purpose: taking the gap from anywhere else is how a seam appears.
+  const period = content > 0 ? content + spacing : 0;
+
+  const copies = useMemo(() => {
+    if (period <= 0 || viewport <= 0) return [];
+    // Enough to span the container, plus one trailing into view and one
+    // already past it — the two the travel consumes before the loop restarts.
+    const count = Math.ceil(viewport / period) + 2;
+    return Array.from({ length: count }, (_, index) => index);
+  }, [period, viewport]);
+
+  const offset = useSharedValue(0);
+
+  useEffect(() => {
+    cancelAnimation(offset);
+    offset.value = 0;
+    if (reducedMotion || !playing || period <= 0 || speed <= 0) return undefined;
+    offset.value = withRepeat(
+      withTiming(period, {
+        duration: (period / speed) * 1000,
+        easing: Easing.linear,
+      }),
+      -1,
+      false
+    );
+    return () => cancelAnimation(offset);
+  }, [offset, period, playing, reducedMotion, speed]);
+
+  const trackStyle = useAnimatedStyle(() => {
+    const travel = (reverse ? offset.value : -offset.value) * flip;
+    return {
+      transform: [horizontal ? { translateX: travel } : { translateY: travel }],
+    };
+  }, [horizontal, reverse, flip]);
+
+  // The container's own measurement is what sizes the loop, so an `onLayout`
+  // passed in is called alongside it rather than replacing it.
+  const onContainerLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setViewport(horizontal ? width : height);
+    onLayout?.(event);
+  };
+
+  const onContentLayout = (event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setContent(horizontal ? width : height);
+  };
+
+  // Nothing to loop, so nothing to clip or clone: render the content plainly
+  // and let it sit where it falls.
+  if (reducedMotion) {
+    return (
+      <View
+        className={cn('overflow-hidden', className)}
+        style={style}
+        onLayout={onLayout}
+        {...props}
+      >
+        {children}
+      </View>
+    );
+  }
+
+  return (
+    <View
+      className={cn('overflow-hidden', className)}
+      style={style}
+      onLayout={onContainerLayout}
+      {...props}
+    >
+      {/* Measured, never seen. A scroller on this axis is what frees the
+          content to report its own size instead of the container's. */}
+      <ScrollView
+        horizontal={horizontal}
+        scrollEnabled={false}
+        style={styles.measure}
+        pointerEvents="none"
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
+        <View onLayout={onContentLayout}>{children}</View>
+      </ScrollView>
+
+      <Animated.View style={[StyleSheet.absoluteFill, trackStyle]} pointerEvents="box-none">
+        {copies.map((index) => {
+          // Index 1 is the copy that starts flush with the container's edge,
+          // and it is the one a screen reader is given.
+          const spoken = index === 1;
+          const at = (index - 1) * period;
+          return (
+            <View
+              key={index}
+              style={[styles.copy, horizontal ? { left: at } : { top: at }]}
+              pointerEvents="box-none"
+              accessibilityElementsHidden={!spoken}
+              importantForAccessibility={spoken ? 'auto' : 'no-hide-descendants'}
+            >
+              {children}
+            </View>
+          );
+        })}
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  /* Laid out so it measures, hidden so it does not draw, and behind everything
+     so it can never intercept anything. */
+  measure: { opacity: 0, zIndex: -1 },
+  copy: { position: 'absolute' },
+});

package/src/components/message-scroller/index.tsx

@@ -39,9 +39,18 @@ import {
   useMemo,
   useRef,
   useState,
+  type ReactElement,
   type ReactNode,
 } from 'react';
-import { View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  FlatList,
+  View,
+  type FlatListProps,
+  type LayoutChangeEvent,
+  type ListRenderItemInfo,
+  type ViewProps,
+  type ViewToken,
+} from 'react-native';
 import Animated, {
   runOnJS,
   useAnimatedRef,
@@ -59,7 +68,10 @@ import { cn } from '../../utils/cn';
 import { textChildren } from '../../primitives/text';
 import {
   distanceFromMessageScrollerTarget,
+  initialMessageScrollerIndex,
   isMessageScrollerTargetVisible,
+  messageScrollerAnchorAt,
+  messageScrollerIndex,
   MESSAGE_SCROLLER_EDGE_THRESHOLD,
 } from './message-scroller-math';
 
@@ -72,8 +84,15 @@ const ANCHOR_PEEK = 24;
 
 export type MessageScrollerPosition = 'start' | 'end' | 'last-anchor';
 
+interface MessageScrollerDriver {
+  scrollToEnd: (animated: boolean) => void;
+  scrollToStart: (animated: boolean) => void;
+  scrollToMessage: (id: string, animated: boolean) => boolean;
+}
+
 interface MessageScrollerContextValue {
   scrollRef: ReturnType<typeof useAnimatedRef<Animated.ScrollView>>;
+  registerDriver: (driver: MessageScrollerDriver | null) => void;
   /** 1 while the reader is at the live edge, 0 otherwise. Drives follow state. */
   atEnd: ReturnType<typeof useSharedValue<number>>;
   /** Live distance from each edge, used by target-specific jump controls. */
@@ -167,6 +186,10 @@ function MessageScrollerRoot({
   const itemY = useRef(new Map<string, number>());
   const anchors = useRef<string[]>([]);
   const following = useRef(autoScroll);
+  const driver = useRef<MessageScrollerDriver | null>(null);
+  const registerDriver = useCallback((next: MessageScrollerDriver | null) => {
+    driver.current = next;
+  }, []);
 
   const registerItem = useCallback((id: string, y: number, anchor: boolean) => {
     itemY.current.set(id, y);
@@ -183,7 +206,8 @@ function MessageScrollerRoot({
   const scrollToEnd = useCallback(
     (animated = true) => {
       following.current = true;
-      scrollRef.current?.scrollToEnd({ animated });
+      if (driver.current) driver.current.scrollToEnd(animated);
+      else scrollRef.current?.scrollToEnd({ animated });
     },
     [scrollRef]
   );
@@ -191,17 +215,23 @@ function MessageScrollerRoot({
   const scrollToStart = useCallback(
     (animated = true) => {
       following.current = false;
-      scrollRef.current?.scrollTo({ y: 0, animated });
+      if (driver.current) driver.current.scrollToStart(animated);
+      else scrollRef.current?.scrollTo({ y: 0, animated });
     },
     [scrollRef]
   );
 
   const scrollToMessage = useCallback(
     (id: string, animated = true) => {
+      if (driver.current) {
+        if (driver.current.scrollToMessage(id, animated)) following.current = false;
+        return;
+      }
       const y = itemY.current.get(id);
-      if (y === undefined) return;
-      following.current = false;
-      scrollRef.current?.scrollTo({ y: Math.max(0, y - ANCHOR_PEEK), animated });
+      if (y !== undefined) {
+        following.current = false;
+        scrollRef.current?.scrollTo({ y: Math.max(0, y - ANCHOR_PEEK), animated });
+      }
     },
     [scrollRef]
   );
@@ -209,6 +239,7 @@ function MessageScrollerRoot({
   const context = useMemo<MessageScrollerContextValue>(
     () => ({
       scrollRef,
+      registerDriver,
       atEnd,
       distanceFromStart,
       distanceFromEnd,
@@ -230,6 +261,7 @@ function MessageScrollerRoot({
     }),
     [
       scrollRef,
+      registerDriver,
       atEnd,
       distanceFromStart,
       distanceFromEnd,
@@ -439,6 +471,201 @@ function MessageScrollerViewport({
 }
 MessageScrollerViewport.displayName = 'MessageScroller.Viewport';
 
+export interface MessageScrollerListItem {
+  /** Stable id used by `scrollToMessage` and as the default React key. */
+  messageId: string;
+  /** Marks the start of a turn for `last-anchor` and visibility reporting. */
+  scrollAnchor?: boolean;
+}
+
+export interface MessageScrollerListProps<T extends MessageScrollerListItem = MessageScrollerListItem>
+  extends Omit<
+    FlatListProps<T>,
+    | 'data'
+    | 'renderItem'
+    | 'keyExtractor'
+    | 'onScroll'
+    | 'onContentSizeChange'
+    | 'onViewableItemsChanged'
+    | 'maintainVisibleContentPosition'
+    | 'onScrollToIndexFailed'
+    | 'onScrollEndDrag'
+    | 'onMomentumScrollEnd'
+    | 'CellRendererComponent'
+  > {
+  className?: string;
+  /** Classes on the virtualized list's padded transcript column. */
+  contentContainerClassName?: string;
+  /**
+   * The complete transcript. Rows outside the native render window stay
+   * unmounted; each item therefore carries its stable navigation metadata.
+   */
+  data: readonly T[];
+  /** Draw one turn from the native list window. */
+  renderItem: (info: ListRenderItemInfo<T>) => ReactElement | null;
+}
+
+/**
+ * The real virtualized transcript path. Only its render window mounts; native
+ * visible-content maintenance keeps prepends still without measuring offscreen
+ * rows in JavaScript.
+ */
+function MessageScrollerList<T extends MessageScrollerListItem>({
+  className,
+  contentContainerClassName,
+  data,
+  renderItem,
+  initialNumToRender = 12,
+  maxToRenderPerBatch = 8,
+  windowSize = 7,
+  ...props
+}: MessageScrollerListProps<T>) {
+  const {
+    atEnd,
+    distanceFromStart,
+    distanceFromEnd,
+    setAtEndJS,
+    autoScroll,
+    preserveScrollOnPrepend,
+    defaultScrollPosition,
+    following,
+    registerDriver,
+    setCurrentAnchorId,
+  } = useScroller('MessageScroller.List');
+  const listRef = useRef<FlatList<T>>(null);
+  const items = useRef(data);
+  items.current = data;
+  const opened = useRef(false);
+  const firstVisibleIndex = useRef<number | null>(null);
+
+  const publishAtEnd = useCallback(
+    (next: boolean) => {
+      following.current = autoScroll && next;
+      setAtEndJS(next);
+    },
+    [autoScroll, following, setAtEndJS]
+  );
+
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      const { contentOffset, contentSize, layoutMeasurement } = event;
+      distanceFromStart.value = distanceFromMessageScrollerTarget(
+        'start',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      distanceFromEnd.value = distanceFromMessageScrollerTarget(
+        'end',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      const next = isMessageScrollerTargetVisible(distanceFromEnd.value) ? 0 : 1;
+      if (next !== atEnd.value) {
+        atEnd.value = next;
+        runOnJS(publishAtEnd)(next === 1);
+      }
+    },
+  });
+
+  const scrollToIndex = useCallback((index: number, animated: boolean) => {
+    listRef.current?.scrollToIndex({ index, viewOffset: ANCHOR_PEEK, animated });
+  }, []);
+
+  const setAnchorAtIndex = useCallback(
+    (index: number) => setCurrentAnchorId(messageScrollerAnchorAt(items.current, index)),
+    [setCurrentAnchorId]
+  );
+
+  useEffect(() => {
+    registerDriver({
+      scrollToEnd: (animated) => {
+        listRef.current?.scrollToEnd({ animated });
+        setAnchorAtIndex(items.current.length - 1);
+      },
+      scrollToStart: (animated) => {
+        listRef.current?.scrollToOffset({ offset: 0, animated });
+        setAnchorAtIndex(0);
+      },
+      scrollToMessage: (id, animated) => {
+        const index = messageScrollerIndex(items.current, id);
+        if (index === undefined) return false;
+        scrollToIndex(index, animated);
+        setAnchorAtIndex(index);
+        return true;
+      },
+    });
+    return () => registerDriver(null);
+  }, [registerDriver, scrollToIndex, setAnchorAtIndex]);
+
+  useEffect(() => {
+    following.current = autoScroll && atEnd.value === 1;
+  }, [atEnd, autoScroll, following]);
+
+  const onContentSizeChange = () => {
+    if (!opened.current) {
+      opened.current = true;
+      const index = initialMessageScrollerIndex(data, defaultScrollPosition);
+      const target = index ?? data.length - 1;
+      if (index === undefined) listRef.current?.scrollToEnd({ animated: false });
+      else if (index > 0) scrollToIndex(index, false);
+      setAnchorAtIndex(target);
+      return;
+    }
+    if (following.current) listRef.current?.scrollToEnd({ animated: true });
+  };
+
+  const onViewableItemsChanged = useRef(
+    ({ viewableItems }: { viewableItems: ViewToken<T>[] }) => {
+      const first = viewableItems.reduce(
+        (best, token) => (token.index !== null && token.index < best ? token.index : best),
+        Infinity
+      );
+      firstVisibleIndex.current = Number.isFinite(first) ? first : null;
+    }
+  ).current;
+
+  const settleAnchor = () => {
+    if (firstVisibleIndex.current !== null) {
+      setCurrentAnchorId(messageScrollerAnchorAt(items.current, firstVisibleIndex.current));
+    }
+  };
+
+  return (
+    <Animated.FlatList
+      ref={listRef}
+      data={data}
+      renderItem={renderItem}
+      keyExtractor={(item) => item.messageId}
+      accessibilityRole="list"
+      accessibilityLabel="Messages"
+      accessibilityLiveRegion="polite"
+      scrollEventThrottle={16}
+      showsVerticalScrollIndicator={false}
+      initialNumToRender={initialNumToRender}
+      maxToRenderPerBatch={maxToRenderPerBatch}
+      windowSize={windowSize}
+      maintainVisibleContentPosition={
+        preserveScrollOnPrepend ? { minIndexForVisible: 0 } : undefined
+      }
+      className={cn('flex-1', className)}
+      contentContainerClassName={cn('gap-3 p-4 pb-16', contentContainerClassName)}
+      {...props}
+      onScroll={scrollHandler}
+      onContentSizeChange={onContentSizeChange}
+      onViewableItemsChanged={onViewableItemsChanged}
+      onScrollEndDrag={settleAnchor}
+      onMomentumScrollEnd={settleAnchor}
+      onScrollToIndexFailed={({ index, averageItemLength }) => {
+        listRef.current?.scrollToOffset({ offset: index * averageItemLength, animated: false });
+        setTimeout(() => scrollToIndex(index, false), 0);
+      }}
+    />
+  );
+}
+MessageScrollerList.displayName = 'MessageScroller.List';
+
 /**
  * How far the transcript shifted, measured on the message closest to the top
  * that was there before and is still there.
@@ -601,6 +828,7 @@ MessageScrollerButton.displayName = 'MessageScroller.Button';
 
 export const MessageScroller = Object.assign(MessageScrollerRoot, {
   Viewport: MessageScrollerViewport,
+  List: MessageScrollerList,
   Content: MessageScrollerContent,
   Item: MessageScrollerItem,
   Button: MessageScrollerButton,

package/src/components/message-scroller/message-scroller-math.ts

@@ -22,3 +22,41 @@ export function isMessageScrollerTargetVisible(distance: number): boolean {
 
   return distance > MESSAGE_SCROLLER_EDGE_THRESHOLD;
 }
+
+export interface MessageScrollerIndexedItem {
+  messageId: string;
+  scrollAnchor?: boolean;
+}
+
+/** Index used by initial positioning and id-addressed virtualized jumps. */
+export function messageScrollerIndex(
+  items: readonly MessageScrollerIndexedItem[],
+  id: string
+): number | undefined {
+  const index = items.findIndex((item) => item.messageId === id);
+  return index < 0 ? undefined : index;
+}
+
+/** Initial target for a list; `undefined` means use the physical end. */
+export function initialMessageScrollerIndex(
+  items: readonly MessageScrollerIndexedItem[],
+  position: 'start' | 'end' | 'last-anchor'
+): number | undefined {
+  if (position === 'end') return undefined;
+  if (position === 'start') return items.length ? 0 : undefined;
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    if (items[index]!.scrollAnchor) return index;
+  }
+  return undefined;
+}
+
+/** Anchor at or before the first visible virtualized row. */
+export function messageScrollerAnchorAt(
+  items: readonly MessageScrollerIndexedItem[],
+  firstVisibleIndex: number
+): string | null {
+  for (let index = Math.min(firstVisibleIndex, items.length - 1); index >= 0; index -= 1) {
+    if (items[index]!.scrollAnchor) return items[index]!.messageId;
+  }
+  return null;
+}