@onekeyfe/react-native-native-list 6.7.0-alpha.378 → 6.7.0-alpha.383

package/src/NativeList.tsx

@@ -32,7 +32,11 @@ import type {
   EndReachedEvent,
   VisibleRangeChangedEvent,
 } from './models';
-import type { NativeListProps, NativeListRef } from './NativeList.types';
+import type {
+  NativeListProps,
+  NativeListRef,
+  StructuralTransitionSettledEvent,
+} from './NativeList.types';
 import { isSelectableRow } from './selection';
 import {
   normalizeIndexScroll,
@@ -44,15 +48,19 @@ import {
   type NormalizedPositionScroll,
 } from './scrolling';
 import {
-  applyRowPatches,
+  applyOwnedNativePatches,
+  captureNativeListInput,
   containNativeListInput,
   emptyNativeListSnapshot,
-  serializePatches,
-  validatePatches,
+  ownValidatedNativeSnapshot,
   validateSnapshot,
 } from './validation';
 
-export type { NativeListProps, NativeListRef } from './NativeList.types';
+export type {
+  NativeListProps,
+  NativeListRef,
+  StructuralTransitionSettledEvent,
+} from './NativeList.types';
 export type {
   ActionAnchorState,
   NativeListKeyboardDismissMode,
@@ -74,6 +82,8 @@ const NativeListHost = getHostComponent<
   NativeListNativeProps,
   NativeListMethods
 >('NativeList', () => NativeListConfig);
+const clearedStructuralTransitionSettled = { f: undefined } as const;
+const disclosureSlotMeasurementStyle = { alignSelf: 'stretch' } as const;
 
 export function preloadNativeListAvatarImages(
   sources: readonly ImageSource[]
@@ -107,6 +117,10 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       listHeader,
       listFooter,
       listEmpty,
+      listSidecar,
+      listExpandedContent,
+      listStructureToggle,
+      sidecarLayout,
       topOverlay,
       topScrollEdgeEffect,
       scrollPositionThresholds,
@@ -122,6 +136,7 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       onReorder,
       onEndReached,
       onVisibleRangeChanged,
+      onStructuralTransitionSettled,
       onScrollPositionThresholdChange,
       onRefresh,
       onScrollToIndexFailed,
@@ -134,27 +149,171 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
     forwardedRef
   ) {
     const snapshotRef = useRef<NativeListSnapshot>(emptyNativeListSnapshot());
+    const renderedSnapshotRef = useRef<NativeListSnapshot | undefined>(
+      undefined
+    );
     const initializedSnapshot = useRef(false);
-    const hasContainerSlots = Boolean(listHeader || listEmpty || listFooter);
-    const prepareSnapshot = useCallback(
-      (next: NativeListSnapshot) => {
-        const accepted = validateSnapshot(next);
+    const pendingDisclosureSnapshotRef = useRef<
+      | {
+          source: 'prop' | 'imperative';
+          input: NativeListSnapshot;
+          owned: NativeListSnapshot;
+          expandedEpoch: number;
+          toggleEpoch: number;
+        }
+      | undefined
+    >(undefined);
+    const previousPropInputRef = useRef(inputSnapshot);
+    const [pendingDisclosureRevision, setPendingDisclosureRevision] =
+      useState(0);
+    const disclosureSlotMounts = useRef({
+      expandedPresent: false,
+      togglePresent: false,
+      expandedEpoch: 0,
+      toggleEpoch: 0,
+    });
+    const expandedPresent = listExpandedContent != null;
+    const togglePresent = listStructureToggle != null;
+    if (disclosureSlotMounts.current.expandedPresent !== expandedPresent) {
+      disclosureSlotMounts.current.expandedPresent = expandedPresent;
+      disclosureSlotMounts.current.expandedEpoch += 1;
+    }
+    if (disclosureSlotMounts.current.togglePresent !== togglePresent) {
+      disclosureSlotMounts.current.togglePresent = togglePresent;
+      disclosureSlotMounts.current.toggleEpoch += 1;
+    }
+    const expandedEpoch = disclosureSlotMounts.current.expandedEpoch;
+    const toggleEpoch = disclosureSlotMounts.current.toggleEpoch;
+    const [slotMeasurements, setSlotMeasurements] = useState({
+      heights: [0, 0, 0, 0, 0, 0],
+      readyEpochs: [-1, -1, -1, -1, -1, -1],
+    });
+    const hasSidecar = listSidecar !== undefined;
+    const sidecarWidth = sidecarLayout?.width;
+    const sidecarGap = sidecarLayout?.gap;
+    const sidecarMaxContentWidth = sidecarLayout?.maxContentWidth;
+    const hasContainerSlots = Boolean(
+      listHeader ||
+        listEmpty ||
+        listFooter ||
+        listSidecar ||
+        listExpandedContent ||
+        listStructureToggle
+    );
+    const validateContainerConfiguration = useCallback(
+      (accepted: NativeListSnapshot) => {
         if (hasContainerSlots && accepted.layout.orientation === 'horizontal')
           throw new Error(
             'NativeList container slots require vertical orientation'
           );
-        return accepted;
+        if (hasSidecar !== (sidecarWidth !== undefined))
+          throw new Error(
+            'listSidecar and sidecarLayout must be supplied together'
+          );
+        if (sidecarWidth !== undefined) {
+          const width = sidecarWidth;
+          const gap = sidecarGap ?? NaN;
+          const maxContentWidth = sidecarMaxContentWidth ?? NaN;
+          if (
+            accepted.layout.kind !== 'linear' ||
+            !Number.isFinite(width) ||
+            width <= 0 ||
+            !Number.isFinite(gap) ||
+            gap < 0 ||
+            !Number.isFinite(maxContentWidth) ||
+            maxContentWidth <= width + gap
+          )
+            throw new Error('Invalid NativeList sidecar layout');
+        }
       },
-      [hasContainerSlots]
+      [
+        hasContainerSlots,
+        hasSidecar,
+        sidecarWidth,
+        sidecarGap,
+        sidecarMaxContentWidth,
+      ]
     );
-    const snapshot = useMemo(
-      () =>
-        containNativeListInput(() => prepareSnapshot(inputSnapshot)) ??
-        snapshotRef.current,
-      [inputSnapshot, prepareSnapshot]
+    const prepareSnapshot = useCallback(
+      (next: NativeListSnapshot) => {
+        const accepted = validateSnapshot(captureNativeListInput(next));
+        validateContainerConfiguration(accepted);
+        return ownValidatedNativeSnapshot(accepted);
+      },
+      [validateContainerConfiguration]
     );
+    const expandedReadyEpoch = slotMeasurements.readyEpochs[4];
+    const toggleReadyEpoch = slotMeasurements.readyEpochs[5];
+    const snapshot = useMemo(() => {
+      // Imperative pending snapshots use this revision to retry the readiness gate.
+      // eslint-disable-next-line no-void -- Reading this revision invalidates the readiness memo.
+      void pendingDisclosureRevision;
+      const propReplaced = previousPropInputRef.current !== inputSnapshot;
+      previousPropInputRef.current = inputSnapshot;
+      const pending = pendingDisclosureSnapshotRef.current;
+      const retained =
+        pending &&
+        !propReplaced &&
+        (pending.source === 'imperative' || pending.input === inputSnapshot) &&
+        pending.expandedEpoch === expandedEpoch &&
+        pending.toggleEpoch === toggleEpoch
+          ? pending
+          : undefined;
+      const candidate =
+        retained?.owned ??
+        (!propReplaced && initializedSnapshot.current
+          ? renderedSnapshotRef.current ?? snapshotRef.current
+          : containNativeListInput(() => prepareSnapshot(inputSnapshot)) ??
+            snapshotRef.current);
+      const acceptedCandidate =
+        !propReplaced && initializedSnapshot.current
+          ? containNativeListInput(() => {
+              validateContainerConfiguration(candidate);
+              return candidate;
+            })
+          : candidate;
+      if (!acceptedCandidate) {
+        pendingDisclosureSnapshotRef.current = undefined;
+        return renderedSnapshotRef.current ?? snapshotRef.current;
+      }
+      const transitionId = acceptedCandidate.structuralTransition?.id;
+      const newDisclosureCommand =
+        initializedSnapshot.current &&
+        acceptedCandidate.disclosure !== undefined &&
+        transitionId !== undefined &&
+        transitionId !== snapshotRef.current.structuralTransition?.id;
+      if (
+        newDisclosureCommand &&
+        ((expandedPresent && expandedReadyEpoch !== expandedEpoch) ||
+          (togglePresent && toggleReadyEpoch !== toggleEpoch))
+      ) {
+        pendingDisclosureSnapshotRef.current = retained ?? {
+          source: 'prop',
+          input: inputSnapshot,
+          owned: acceptedCandidate,
+          expandedEpoch,
+          toggleEpoch,
+        };
+        return snapshotRef.current;
+      }
+      pendingDisclosureSnapshotRef.current = undefined;
+      return acceptedCandidate;
+    }, [
+      inputSnapshot,
+      prepareSnapshot,
+      validateContainerConfiguration,
+      expandedPresent,
+      togglePresent,
+      expandedEpoch,
+      toggleEpoch,
+      expandedReadyEpoch,
+      toggleReadyEpoch,
+      pendingDisclosureRevision,
+    ]);
+    renderedSnapshotRef.current = snapshot;
     const fontFamiliesJson = useNativeListFontFamiliesJson();
-    const [slotHeights, setSlotHeights] = useState([0, 0, 0]);
+    const slotHeights = slotMeasurements.heights;
+    const [viewportWidth, setViewportWidth] = useState(0);
     const [topOverlayHeight, setTopOverlayHeight] = useState(0);
     const hasTopOverlay =
       Platform?.OS === 'ios' &&
@@ -162,11 +321,51 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       (topScrollEdgeEffect === 'hard' || topScrollEdgeEffect === 'soft') &&
       topOverlay != null;
     const containerSlotHeightsJson = JSON.stringify(slotHeights);
-    const slotInset =
+    const defaultSlotInset =
       snapshot.layout.contentPaddingHorizontal ??
       snapshot.layout.contentPadding ??
       0;
-    const slotContents = [listHeader, listEmpty, listFooter];
+    const bandWidth = sidecarLayout
+      ? Math.min(viewportWidth, sidecarLayout.maxContentWidth)
+      : 0;
+    const slotInset = sidecarLayout
+      ? Math.max(0, (viewportWidth - bandWidth) / 2) + defaultSlotInset
+      : defaultSlotInset;
+    const sidecarSpace = sidecarLayout
+      ? sidecarLayout.width + sidecarLayout.gap
+      : 0;
+    const slotContents = [
+      listHeader,
+      listEmpty,
+      listFooter,
+      listSidecar,
+      listExpandedContent,
+      listStructureToggle,
+    ];
+    const recordSlotLayout = (index: number, height: number, epoch: number) => {
+      if (
+        (index === 4 && epoch !== disclosureSlotMounts.current.expandedEpoch) ||
+        (index === 5 && epoch !== disclosureSlotMounts.current.toggleEpoch)
+      ) {
+        return;
+      }
+      setSlotMeasurements((previous) => {
+        if (
+          previous.heights[index] === height &&
+          previous.readyEpochs[index] === epoch
+        ) {
+          return previous;
+        }
+        const heights = [...previous.heights];
+        const readyEpochs = [...previous.readyEpochs];
+        heights[index] = height;
+        readyEpochs[index] = epoch;
+        return { heights, readyEpochs };
+      });
+    };
+    const sidecarLayoutJson = sidecarLayout
+      ? JSON.stringify(sidecarLayout)
+      : '';
     const normalizedKeyboardShouldPersistTaps =
       keyboardShouldPersistTaps === true
         ? 'always'
@@ -181,6 +380,7 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       onReorder,
       onEndReached,
       onVisibleRangeChanged,
+      onStructuralTransitionSettled,
       onScrollPositionThresholdChange,
       onRefresh,
       onScrollToIndexFailed,
@@ -192,6 +392,7 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       onReorder,
       onEndReached,
       onVisibleRangeChanged,
+      onStructuralTransitionSettled,
       onScrollPositionThresholdChange,
       onRefresh,
       onScrollToIndexFailed,
@@ -367,6 +568,26 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
           prepareSnapshot(nextSnapshot)
         );
         if (!accepted) return;
+        const transitionId = accepted.structuralTransition?.id;
+        const waitsForSlots =
+          accepted.disclosure !== undefined &&
+          transitionId !== undefined &&
+          transitionId !== snapshotRef.current.structuralTransition?.id &&
+          ((expandedPresent &&
+            slotMeasurements.readyEpochs[4] !== expandedEpoch) ||
+            (togglePresent && slotMeasurements.readyEpochs[5] !== toggleEpoch));
+        if (waitsForSlots) {
+          pendingDisclosureSnapshotRef.current = {
+            source: 'imperative',
+            input: nextSnapshot,
+            owned: accepted,
+            expandedEpoch,
+            toggleEpoch,
+          };
+          setPendingDisclosureRevision((value) => value + 1);
+          return;
+        }
+        pendingDisclosureSnapshotRef.current = undefined;
         const nextSnapshotJson = JSON.stringify(accepted);
         nativeRef.current?.applySnapshot(nextSnapshotJson);
         snapshotRef.current = accepted;
@@ -376,16 +597,22 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
         }
       },
       applyPatches(patches) {
-        const accepted = containNativeListInput(() => {
-          const normalized = validatePatches(patches);
-          return {
-            patches: normalized,
-            snapshot: applyRowPatches(snapshotRef.current, normalized),
-            json: serializePatches(normalized),
-          };
-        });
+        const pending = pendingDisclosureSnapshotRef.current;
+        const accepted = containNativeListInput(() =>
+          applyOwnedNativePatches(
+            pending?.owned ?? snapshotRef.current,
+            patches
+          )
+        );
         if (!accepted || accepted.patches.length === 0) return;
         const nextSnapshot = accepted.snapshot;
+        if (pending) {
+          pendingDisclosureSnapshotRef.current = {
+            ...pending,
+            owned: nextSnapshot,
+          };
+          return;
+        }
         const native = nativeRef.current;
         const dispatch = native
           ? () => {
@@ -401,19 +628,25 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
           updateAvatarPrefetchRef.current();
       },
       reconcileSelection(selectedKeys) {
-        nativeRef.current?.reconcileSelection(JSON.stringify(selectedKeys));
-        const current = snapshotRef.current;
+        const capturedKeys = captureNativeListInput(selectedKeys);
+        const pending = pendingDisclosureSnapshotRef.current;
+        if (!pending)
+          nativeRef.current?.reconcileSelection(JSON.stringify(capturedKeys));
+        const current = pending?.owned ?? snapshotRef.current;
         if (
           current.selection &&
-          (current.selection.mode !== 'single' || selectedKeys.length <= 1) &&
-          selectedKeys.every((key) =>
+          (current.selection.mode !== 'single' || capturedKeys.length <= 1) &&
+          capturedKeys.every((key) =>
             current.rows.some((row) => row.key === key && isSelectableRow(row))
           )
         ) {
-          snapshotRef.current = {
+          const next = {
             ...current,
-            selection: { ...current.selection, selectedKeys },
+            selection: { ...current.selection, selectedKeys: capturedKeys },
           };
+          if (pending)
+            pendingDisclosureSnapshotRef.current = { ...pending, owned: next };
+          else snapshotRef.current = next;
         }
       },
       scrollToKey(paramsOrKey, animated, alignment) {
@@ -546,6 +779,11 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
           updateAvatarPrefetchRef.current();
           callbacksRef.current.onVisibleRangeChanged?.(payload);
         }),
+        onStructuralTransitionSettled: callback((payloadJson: string) => {
+          callbacksRef.current.onStructuralTransitionSettled?.(
+            parsePayload<StructuralTransitionSettledEvent>(payloadJson)
+          );
+        }),
       }),
       []
     );
@@ -553,10 +791,20 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
     return (
       <NativeListHost
         {...viewProps}
+        onLayout={(event) => {
+          setViewportWidth(event.nativeEvent.layout.width);
+          viewProps.onLayout?.(event);
+        }}
         {...nativeCallbacks}
+        onStructuralTransitionSettled={
+          onStructuralTransitionSettled
+            ? nativeCallbacks.onStructuralTransitionSettled
+            : clearedStructuralTransitionSettled
+        }
         fontFamiliesJson={fontFamiliesJson}
         snapshotJson={snapshotJson}
         containerSlotHeightsJson={containerSlotHeightsJson}
+        sidecarLayoutJson={sidecarLayoutJson}
         topScrollEdgeEffect={
           hasTopOverlay ? topScrollEdgeEffect ?? 'none' : 'none'
         }
@@ -571,22 +819,43 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
             collapsable={false}
             style={{
               position: 'absolute',
-              left: slotInset,
-              right: slotInset,
+              start: index === 3 ? 0 : slotInset,
+              end: index === 3 ? undefined : slotInset + sidecarSpace,
+              width: index === 3 ? sidecarLayout?.width : undefined,
               top: 0,
             }}
             onLayout={(event) => {
-              const height = Math.ceil(event.nativeEvent.layout.height);
-              setSlotHeights((previous) =>
-                previous[index] === height
-                  ? previous
-                  : previous.map((value, slot) =>
-                      slot === index ? height : value
-                    )
-              );
+              if (index < 4) {
+                recordSlotLayout(
+                  index,
+                  Math.ceil(event.nativeEvent.layout.height),
+                  0
+                );
+              }
             }}
           >
-            {content}
+            {index >= 4 ? (
+              <View
+                key={
+                  index === 4
+                    ? `expanded-${expandedEpoch}`
+                    : `toggle-${toggleEpoch}`
+                }
+                collapsable={false}
+                style={disclosureSlotMeasurementStyle}
+                onLayout={(event) =>
+                  recordSlotLayout(
+                    index,
+                    Math.ceil(event.nativeEvent.layout.height),
+                    index === 4 ? expandedEpoch : toggleEpoch
+                  )
+                }
+              >
+                {content}
+              </View>
+            ) : (
+              content
+            )}
           </View>
         ))}
         {hasTopOverlay ? (

package/src/NativeList.types.ts

@@ -78,6 +78,18 @@ export type NativeListWebScrollHost = Readonly<{
   scrollTop: number;
 }>;
 
+export type NativeListSidecarLayout = Readonly<{
+  width: number;
+  gap: number;
+  maxContentWidth: number;
+}>;
+
+export type StructuralTransitionSettledEvent = Readonly<{
+  transitionId: string;
+  status: 'completed' | 'interrupted';
+  settledExpanded: boolean;
+}>;
+
 type InitialScrollProps =
   | Readonly<{
       initialScrollIndex?: never;
@@ -131,6 +143,13 @@ export type NativeListProps = Omit<ViewProps, 'children'> &
     listHeader?: ReactNode;
     listFooter?: ReactNode;
     listEmpty?: ReactNode;
+    /** Native disclosure content, retained until its transition settles. */
+    listExpandedContent?: ReactNode;
+    /** Stable native disclosure toggle after expanded content. */
+    listStructureToggle?: ReactNode;
+    /** Scrolling right column for a vertical linear list. Requires sidecarLayout. */
+    listSidecar?: ReactNode;
+    sidecarLayout?: NativeListSidecarLayout;
     /** Fixed overlay above scrolling rows on iOS 26 and newer. */
     topOverlay?: ReactNode;
     /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
@@ -156,6 +175,9 @@ export type NativeListProps = Omit<ViewProps, 'children'> &
     onReorder?: (event: ReorderEvent) => void;
     onEndReached?: (event: EndReachedEvent) => void;
     onVisibleRangeChanged?: (event: VisibleRangeChangedEvent) => void;
+    onStructuralTransitionSettled?: (
+      event: StructuralTransitionSettledEvent
+    ) => void;
     /** Native only. Emits initial state and hysteresis transitions, not scroll frames. */
     scrollPositionThresholds?: Readonly<{
       start: number;