@unif/react-native-chat 3.2.4 → 3.3.0

package/src/components/MessageList/useMessageListScroll.ts

@@ -1,14 +1,21 @@
 import { useCallback, useLayoutEffect, useRef, useState } from 'react';
 import type { RefObject } from 'react';
 import type {
+  DimensionValue,
   FlatList,
+  FlatListProps,
   LayoutChangeEvent,
+  LayoutRectangle,
   NativeScrollEvent,
   NativeSyntheticEvent,
 } from 'react-native';
 import { DEFAULT_END_THRESHOLD } from './constants';
 import type {
   ListMeasurements,
+  MessageListAnchorOptions,
+  MessageListAnchorRequest,
+  MessageListItemLayout,
+  MessageListPendingScroll,
   MessageListProps,
   MessageListScrollOptions,
 } from './types';
@@ -19,10 +26,24 @@ interface MessageListScrollInput<T> extends Pick<
 > {
   listRef: RefObject<FlatList<T> | null>;
   keys: readonly string[];
+  contentMinimumHeight?: DimensionValue;
+  contentBottomPadding?: DimensionValue;
+  hasFooter?: boolean;
   preservingPrependRef: RefObject<boolean>;
   cancelPrependPreservation(): void;
 }
 
+function layoutValue(value: DimensionValue | undefined, extent: number) {
+  if (typeof value === 'number' && Number.isFinite(value))
+    return Math.max(0, value);
+  if (typeof value === 'string' && value.endsWith('%')) {
+    const percentage = Number.parseFloat(value);
+    if (Number.isFinite(percentage))
+      return Math.max(0, (extent * percentage) / 100);
+  }
+  return 0;
+}
+
 export function useMessageListScroll<T>({
   listRef,
   keys,
@@ -30,10 +51,14 @@ export function useMessageListScroll<T>({
   followOutput,
   endThreshold = DEFAULT_END_THRESHOLD,
   onAtEndChange,
+  contentMinimumHeight,
+  contentBottomPadding,
+  hasFooter,
   preservingPrependRef,
   cancelPrependPreservation,
 }: MessageListScrollInput<T>) {
   const measurements = useRef<ListMeasurements>({
+    width: 0,
     viewport: 0,
     content: 0,
     offset: 0,
@@ -42,29 +67,27 @@ export function useMessageListScroll<T>({
   const initial = useRef(initialPosition);
   const initialized = useRef(false);
   const previousKeys = useRef<readonly string[]>([]);
+  const currentKeys = useRef(keys);
+  currentKeys.current = keys;
+  const contentStyle = useRef({ contentMinimumHeight, contentBottomPadding });
+  contentStyle.current = { contentMinimumHeight, contentBottomPadding };
   const prependPending = useRef(false);
-  const pendingScroll = useRef<MessageListScrollOptions | undefined>(undefined);
+  const pendingScroll = useRef<MessageListPendingScroll | undefined>(undefined);
   const userScrolling = useRef(false);
   const atEndRef = useRef<boolean | undefined>(undefined);
   const [atEnd, setAtEnd] = useState(true);
+  const anchor = useRef<MessageListAnchorRequest | undefined>(undefined);
+  const layouts = useRef(new Map<string, MessageListItemLayout>());
+  const layoutRevision = useRef(0);
+  const footerHeight = useRef(0);
+  if (!hasFooter) footerHeight.current = 0;
+  const layoutChanged = useRef<() => void>(() => {});
+  const [anchorMinimumHeight, setAnchorMinimumHeight] = useState<number>();
+  const minimumRef = useRef<number | undefined>(undefined);
   const threshold = Number.isFinite(endThreshold)
     ? Math.max(0, endThreshold)
     : DEFAULT_END_THRESHOLD;
 
-  useLayoutEffect(() => {
-    const previous = previousKeys.current;
-    const added = keys.length - previous.length;
-    const onlyPrepended =
-      previous.length > 0 &&
-      added > 0 &&
-      previous.every((key, index) => keys[index + added] === key);
-    const changed =
-      keys.length !== previous.length ||
-      keys.some((key, index) => key !== previous[index]);
-    if (changed) prependPending.current = onlyPrepended;
-    previousKeys.current = keys;
-  }, [keys]);
-
   const ready = useCallback(() => {
     const current = measurements.current;
     return current.viewport > 0 && current.hasContentSize;
@@ -81,11 +104,192 @@ export function useMessageListScroll<T>({
     }
   }, [onAtEndChange, ready, threshold]);
 
+  const cancelAnchor = useCallback(() => {
+    anchor.current = undefined;
+    minimumRef.current = undefined;
+    setAnchorMinimumHeight(undefined);
+  }, []);
+
+  const naturalContentHeight = useCallback(() => {
+    const last = currentKeys.current.at(-1);
+    const cell =
+      last === undefined ? undefined : layouts.current.get(last)?.cell;
+    if (!cell) return undefined;
+    const { width, viewport } = measurements.current;
+    return Math.max(
+      cell.y +
+        cell.height +
+        footerHeight.current +
+        layoutValue(contentStyle.current.contentBottomPadding, width),
+      layoutValue(contentStyle.current.contentMinimumHeight, viewport)
+    );
+  }, []);
+
+  const applyAnchor = useCallback(() => {
+    const request = anchor.current;
+    if (!request || !ready()) return;
+    const index = currentKeys.current.indexOf(request.key);
+    if (index < 0) return;
+    request.seen = true;
+    const position = layouts.current.get(request.key);
+    if (!position?.cell || position.itemY === undefined) {
+      // An offscreen row first needs to enter FlatList's render window. This
+      // estimate only reveals it; success still requires its actual layouts.
+      if (request.locatedAt !== layoutRevision.current) {
+        request.locatedAt = layoutRevision.current;
+        listRef.current?.scrollToIndex({
+          index,
+          animated: false,
+          viewPosition: 0,
+        });
+      }
+      return;
+    }
+    const { viewport, content } = measurements.current;
+    const offset = Math.max(
+      0,
+      position.cell.y + position.itemY - request.topOffset
+    );
+    const minimum = Math.max(
+      offset + viewport,
+      layoutValue(contentStyle.current.contentMinimumHeight, viewport)
+    );
+    minimumRef.current = minimum;
+    setAnchorMinimumHeight(minimum);
+    // Yoga's requested minimum is not yet native scroll space. Wait for the
+    // content-size event; otherwise native scrolling can clamp the target.
+    if (content + 0.5 < minimum) return;
+    if (request.offset === offset && request.viewport === viewport) return;
+    request.offset = offset;
+    request.viewport = viewport;
+    request.settled = false;
+    initialized.current = true;
+    listRef.current?.scrollToOffset({ offset, animated: request.animated });
+    measurements.current.offset = offset;
+    publishPosition();
+  }, [listRef, publishPosition, ready]);
+
+  const onCellLayout = useCallback(
+    (key: string, index: number, cell: LayoutRectangle) => {
+      if (
+        currentKeys.current[index] !== key ||
+        !Number.isFinite(cell.y) ||
+        !Number.isFinite(cell.height)
+      )
+        return;
+      const previous = layouts.current.get(key);
+      if (
+        previous?.index !== index ||
+        previous.cell?.x !== cell.x ||
+        previous.cell.y !== cell.y ||
+        previous.cell.width !== cell.width ||
+        previous.cell.height !== cell.height
+      )
+        layoutRevision.current++;
+      layouts.current.set(key, { ...previous, index, cell });
+      layoutChanged.current();
+    },
+    []
+  );
+  const onItemLayout = useCallback(
+    (key: string, index: number, itemY: number) => {
+      if (currentKeys.current[index] !== key || !Number.isFinite(itemY)) return;
+      const previous = layouts.current.get(key);
+      if (previous?.index !== index || previous.itemY !== itemY)
+        layoutRevision.current++;
+      layouts.current.set(key, { ...previous, index, itemY });
+      layoutChanged.current();
+    },
+    []
+  );
+  const onCellUnmount = useCallback((key: string, index: number) => {
+    if (layouts.current.get(key)?.index === index) {
+      layouts.current.delete(key);
+      layoutRevision.current++;
+    }
+  }, []);
+  const onFooterLayout = useCallback((event: LayoutChangeEvent) => {
+    footerHeight.current = event.nativeEvent.layout.height;
+    layoutChanged.current();
+  }, []);
+
+  const anchorToItem = useCallback(
+    (key: string, options: MessageListAnchorOptions = {}) => {
+      pendingScroll.current = undefined;
+      cancelPrependPreservation();
+      userScrolling.current = false;
+      anchor.current = {
+        key,
+        topOffset: Number.isFinite(options.topOffset)
+          ? Math.max(0, options.topOffset!)
+          : 0,
+        animated: options.animated ?? true,
+        seen: currentKeys.current.includes(key),
+      };
+      minimumRef.current = 0;
+      setAnchorMinimumHeight(0);
+      applyAnchor();
+    },
+    [applyAnchor, cancelPrependPreservation]
+  );
+
+  useLayoutEffect(() => {
+    const previous = previousKeys.current;
+    const added = keys.length - previous.length;
+    const onlyPrepended =
+      previous.length > 0 &&
+      added > 0 &&
+      previous.every((key, index) => keys[index + added] === key);
+    const changed =
+      keys.length !== previous.length ||
+      keys.some((key, index) => key !== previous[index]);
+    if (changed) {
+      layoutRevision.current++;
+      prependPending.current = onlyPrepended;
+      const indices = new Map(keys.map((key, index) => [key, index]));
+      for (const [key, layout] of layouts.current) {
+        const index = indices.get(key);
+        if (index === undefined) layouts.current.delete(key);
+        else if (index !== layout.index) {
+          // A moved cell gets a new natural y; the row's local separator
+          // offset remains valid until an actual layout change replaces it.
+          layouts.current.set(key, { index, itemY: layout.itemY });
+        }
+      }
+    }
+    previousKeys.current = keys;
+    const request = anchor.current;
+    if (request) {
+      if (keys.includes(request.key)) request.seen = true;
+      else if (request.seen) {
+        cancelAnchor();
+        return;
+      }
+      // Explicit positioning and native/Web prepend preservation must never
+      // compensate the same layout twice.
+      cancelPrependPreservation();
+      applyAnchor();
+    }
+  }, [applyAnchor, cancelAnchor, cancelPrependPreservation, keys]);
+
   const scrollToEnd = useCallback(
     (options: MessageListScrollOptions = {}) => {
       cancelPrependPreservation();
-      const request = { animated: options.animated ?? true };
-      if (!ready()) {
+      const request: MessageListPendingScroll = {
+        animated: options.animated ?? true,
+      };
+      const natural = naturalContentHeight();
+      const minimum = minimumRef.current;
+      if (
+        minimum !== undefined &&
+        natural !== undefined &&
+        measurements.current.content <= minimum + 0.5 &&
+        natural + 0.5 < measurements.current.content
+      ) {
+        request.contentBeforeRelease = measurements.current.content;
+      }
+      cancelAnchor();
+      if (!ready() || request.contentBeforeRelease !== undefined) {
         pendingScroll.current = request;
         return;
       }
@@ -100,14 +304,31 @@ export function useMessageListScroll<T>({
       if (measurements.current.content <= measurements.current.viewport)
         publishPosition();
     },
-    [cancelPrependPreservation, listRef, publishPosition, ready]
+    [
+      cancelAnchor,
+      cancelPrependPreservation,
+      listRef,
+      naturalContentHeight,
+      publishPosition,
+      ready,
+    ]
   );
 
   const itemCount = keys.length;
   const reconcileLayout = useCallback(
     (contentChanged: boolean) => {
       if (!ready()) return;
+      if (anchor.current) {
+        applyAnchor();
+        return;
+      }
       const request = pendingScroll.current;
+      if (
+        request?.contentBeforeRelease !== undefined &&
+        measurements.current.content === request.contentBeforeRelease &&
+        (naturalContentHeight() ?? 0) < request.contentBeforeRelease
+      )
+        return;
       if (itemCount > 0 && !initialized.current) {
         initialized.current = true;
         if (request || initial.current === 'end') {
@@ -134,8 +355,10 @@ export function useMessageListScroll<T>({
       else publishPosition();
     },
     [
+      applyAnchor,
       followOutput,
       itemCount,
+      naturalContentHeight,
       preservingPrependRef,
       publishPosition,
       ready,
@@ -143,19 +366,36 @@ export function useMessageListScroll<T>({
     ]
   );
 
+  layoutChanged.current = () => {
+    if (anchor.current) applyAnchor();
+    else if (pendingScroll.current) reconcileLayout(false);
+  };
+
   const onScroll = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
       const { contentOffset, contentSize, layoutMeasurement } =
         event.nativeEvent;
       const movedUp = contentOffset.y < measurements.current.offset;
+      const geometryChanged =
+        measurements.current.content !== contentSize.height ||
+        measurements.current.viewport !== layoutMeasurement.height;
+      const request = anchor.current;
+      if (request?.offset !== undefined) {
+        if (Math.abs(contentOffset.y - request.offset) <= 0.5)
+          request.settled = true;
+        // RN Web wheel scrolling need not dispatch scrollBeginDrag. Once a
+        // requested scroll has settled, a user move at unchanged geometry wins.
+        else if (request.settled && !geometryChanged) cancelAnchor();
+      }
       const resizingAtEnd =
+        !anchor.current &&
         atEndRef.current &&
         !movedUp &&
         !userScrolling.current &&
         followOutput === 'whenAtEnd' &&
-        (measurements.current.content !== contentSize.height ||
-          measurements.current.viewport !== layoutMeasurement.height);
+        geometryChanged;
       measurements.current = {
+        width: layoutMeasurement.width,
         offset: contentOffset.y,
         content: contentSize.height,
         viewport: layoutMeasurement.height,
@@ -163,12 +403,13 @@ export function useMessageListScroll<T>({
       };
       if (!resizingAtEnd) publishPosition();
     },
-    [followOutput, publishPosition]
+    [cancelAnchor, followOutput, publishPosition]
   );
 
   const onLayout = useCallback(
     ({ nativeEvent: { layout } }: LayoutChangeEvent) => {
       measurements.current.viewport = layout.height;
+      measurements.current.width = layout.width;
       reconcileLayout(false);
     },
     [reconcileLayout]
@@ -183,6 +424,11 @@ export function useMessageListScroll<T>({
   );
   const onUserScrollBegin = useCallback(() => {
     userScrolling.current = true;
+    pendingScroll.current = undefined;
+    cancelAnchor();
+  }, [cancelAnchor]);
+  const onMomentumScrollBegin = useCallback(() => {
+    userScrolling.current = true;
   }, []);
   const onScrollEndDrag = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
@@ -202,14 +448,43 @@ export function useMessageListScroll<T>({
     },
     [onScroll, publishPosition]
   );
+  const onScrollToIndexFailed = useCallback(
+    (
+      failure: Parameters<
+        NonNullable<FlatListProps<T>['onScrollToIndexFailed']>
+      >[0]
+    ) => {
+      const request = anchor.current;
+      if (
+        !request ||
+        currentKeys.current.indexOf(request.key) !== failure.index ||
+        !Number.isFinite(failure.averageItemLength) ||
+        failure.averageItemLength <= 0
+      )
+        return;
+      listRef.current?.scrollToOffset({
+        offset: failure.index * failure.averageItemLength,
+        animated: false,
+      });
+    },
+    [listRef]
+  );
 
   return {
     atEnd,
+    anchorMinimumHeight,
+    anchorToItem,
+    onCellLayout,
+    onItemLayout,
+    onCellUnmount,
+    onFooterLayout,
+    onScrollToIndexFailed,
     scrollToEnd,
     onLayout,
     onContentSizeChange,
     onScroll,
     onUserScrollBegin,
+    onMomentumScrollBegin,
     onScrollEndDrag,
     onMomentumScrollEnd,
   };

package/src/components/Process/Process.tsx

@@ -9,6 +9,7 @@ import {
 import { PROCESS_STATUS_ICONS, PROCESS_STATUS_LABELS } from './constants';
 import { createStyles } from './styles';
 import { ProcessCompactStep } from './ProcessCompactStep';
+import { ProcessTimelineStep } from './ProcessTimelineStep';
 import type { ProcessProps, ProcessStep } from './types';
 
 function idsWithDetails(
@@ -45,6 +46,10 @@ function formatElapsedMs(elapsedMs: number | undefined): string | undefined {
 
 export function Process(props: ProcessProps): React.JSX.Element {
   const { steps, title, identity, style, testID, variant = 'card' } = props;
+  const inlineIdentity =
+    variant === 'compact' &&
+    steps.length === 1 &&
+    props.identityPlacement === 'inline';
   const styles = useThemedStyles(createStyles);
   const colors = useColors();
   const isControlled = props.expandedIds !== undefined;
@@ -73,25 +78,53 @@ export function Process(props: ProcessProps): React.JSX.Element {
 
   return (
     <View
-      style={[variant === 'compact' ? styles.compactRoot : styles.root, style]}
+      style={[
+        variant === 'compact'
+          ? styles.compactRoot
+          : variant === 'timeline'
+            ? styles.timelineRoot
+            : styles.root,
+        style,
+      ]}
       testID={testID}
     >
-      {title || identity ? (
+      {title || (identity && !inlineIdentity) ? (
         <View style={styles.heading}>
-          {identity}
+          {!inlineIdentity ? identity : null}
           {title ? <Text style={styles.headingTitle}>{title}</Text> : null}
         </View>
       ) : null}
-      <View style={variant === 'compact' ? styles.compactSteps : styles.steps}>
+      <View
+        style={
+          variant === 'compact'
+            ? styles.compactSteps
+            : variant === 'timeline'
+              ? undefined
+              : styles.steps
+        }
+      >
         {steps.map((step, index) => {
-          const statusLabel = PROCESS_STATUS_LABELS[step.status];
+          const statusLabel =
+            step.statusText ?? PROCESS_STATUS_LABELS[step.status];
           const elapsed = formatElapsedMs(step.elapsedMs);
           const isExpanded = expandedIds.includes(step.id);
+          if (variant === 'timeline')
+            return (
+              <ProcessTimelineStep
+                key={step.id}
+                step={step}
+                last={index === steps.length - 1}
+                expanded={isExpanded}
+                elapsed={elapsed}
+                onToggle={() => toggleDetails(step.id)}
+              />
+            );
           if (variant === 'compact')
             return (
               <ProcessCompactStep
                 key={step.id}
                 step={step}
+                identity={inlineIdentity ? identity : undefined}
                 expanded={isExpanded}
                 elapsed={elapsed}
                 onToggle={() => toggleDetails(step.id)}

package/src/components/Process/ProcessCompactStep.tsx

@@ -4,8 +4,8 @@ import {
   Icon,
   Pulse,
   Reveal,
+  motion,
   pressedOpacity,
-  r,
   useColors,
   useThemedStyles,
 } from '@unif/react-native-design';
@@ -15,6 +15,7 @@ import type { ProcessCompactStepProps } from './types';
 
 export function ProcessCompactStep({
   step,
+  identity,
   expanded,
   elapsed,
   onToggle,
@@ -23,6 +24,7 @@ export function ProcessCompactStep({
   const colors = useColors();
   const hasDetails = step.details != null;
   const running = step.status === 'running';
+  const statusText = step.statusText ?? PROCESS_STATUS_LABELS[step.status];
   const color = running
     ? colors.primary
     : step.status === 'completed'
@@ -37,7 +39,7 @@ export function ProcessCompactStep({
           ? 'spark'
           : PROCESS_STATUS_ICONS[step.status]
       }
-      size={r(14)}
+      size={14}
       color={color}
     />
   );
@@ -47,31 +49,44 @@ export function ProcessCompactStep({
         testID={`process-step-${step.id}-toggle`}
         accessible
         accessibilityRole={hasDetails ? 'button' : undefined}
-        accessibilityLabel={`${step.title}，${PROCESS_STATUS_LABELS[step.status]}${elapsed ? `，${elapsed}` : ''}`}
+        accessibilityLabel={`${step.title}，${statusText}${elapsed ? `，${elapsed}` : ''}`}
         accessibilityState={hasDetails ? { expanded } : undefined}
         disabled={!hasDetails}
+        hitSlop={10}
         onPress={onToggle}
         style={({ pressed }) => [
           styles.compactHeader,
           pressed && { opacity: pressedOpacity },
         ]}
       >
-        {running ? <Pulse>{icon}</Pulse> : icon}
-        <Text
-          style={styles.compactTitle}
-          testID={`process-step-title-${step.id}`}
-          numberOfLines={1}
-        >
-          {step.title}
-        </Text>
-        <Text style={[styles.statusText, { color }]}>
-          {PROCESS_STATUS_LABELS[step.status]}
-        </Text>
+        {identity ? (
+          <>
+            {identity}
+            <View style={styles.spacer} />
+          </>
+        ) : null}
+        {running ? (
+          <Pulse from={0.4} duration={motion.pulse / 2}>
+            {icon}
+          </Pulse>
+        ) : (
+          icon
+        )}
+        {!identity ? (
+          <Text
+            style={styles.compactTitle}
+            testID={`process-step-title-${step.id}`}
+            numberOfLines={1}
+          >
+            {step.title}
+          </Text>
+        ) : null}
+        <Text style={styles.compactStatus}>{statusText}</Text>
         {elapsed ? <Text style={styles.elapsed}>{elapsed}</Text> : null}
         {hasDetails ? (
           <Icon
             name={expanded ? 'chevron-up' : 'chevron-down'}
-            size={r(14)}
+            size={14}
             color={colors.foregroundSubtle}
           />
         ) : null}
@@ -80,11 +95,12 @@ export function ProcessCompactStep({
         <Text style={styles.compactDescription}>{step.description}</Text>
       ) : null}
       {hasDetails && expanded ? (
-        <Reveal>
+        <Reveal style={styles.compactDetailsContainer}>
           <ScrollView
             testID={`process-step-${step.id}-details`}
             style={styles.compactDetails}
             nestedScrollEnabled
+            showsVerticalScrollIndicator={false}
             keyboardShouldPersistTaps="handled"
           >
             {step.details}