@onekeyfe/react-native-native-list 3.0.157-alpha.253 → 3.0.157-alpha.255

package/src/NativeList.tsx

@@ -4,6 +4,7 @@ import React, {
   useImperativeHandle,
   useMemo,
   useRef,
+  useState,
 } from 'react';
 import {
   OneKeyImageCache,
@@ -13,6 +14,7 @@ import {
   NativeAvatarPrefetchModel,
   NativeAvatarPrefetchQueue,
 } from './avatarPrefetch';
+import { View } from 'react-native';
 import { callback, getHostComponent } from 'react-native-nitro-modules';
 import type {
   NativeListMethods,
@@ -96,6 +98,10 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
   function NativeList(
     {
       snapshot,
+      listHeader,
+      listFooter,
+      listEmpty,
+      scrollPositionThresholds,
       webVirtualizationEnabled: _webVirtualizationEnabled,
       webSectionIndexContainerRef: _webSectionIndexContainerRef,
       keyboardDismissMode = 'none',
@@ -106,6 +112,7 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       onReorder,
       onEndReached,
       onVisibleRangeChanged,
+      onScrollPositionThresholdChange,
       onRefresh,
       onScrollToIndexFailed,
       initialScrollIndex,
@@ -116,6 +123,21 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
     },
     forwardedRef
   ) {
+    const [slotHeights, setSlotHeights] = useState([0, 0, 0]);
+    const containerSlotHeightsJson = JSON.stringify(slotHeights);
+    const slotInset =
+      snapshot.layout.contentPaddingHorizontal ??
+      snapshot.layout.contentPadding ??
+      0;
+    if (
+      snapshot.layout.orientation === 'horizontal' &&
+      (listHeader || listEmpty || listFooter)
+    ) {
+      throw new Error(
+        'NativeList container slots require vertical orientation'
+      );
+    }
+    const slotContents = [listHeader, listEmpty, listFooter];
     const normalizedKeyboardShouldPersistTaps =
       keyboardShouldPersistTaps === true
         ? 'always'
@@ -130,6 +152,7 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       onReorder,
       onEndReached,
       onVisibleRangeChanged,
+      onScrollPositionThresholdChange,
       onRefresh,
       onScrollToIndexFailed,
     });
@@ -140,9 +163,29 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
       onReorder,
       onEndReached,
       onVisibleRangeChanged,
+      onScrollPositionThresholdChange,
       onRefresh,
       onScrollToIndexFailed,
     };
+    const scrollPositionThresholdsJson = useMemo(() => {
+      if (
+        !scrollPositionThresholds ||
+        scrollPositionThresholds.enabled === false
+      )
+        return '';
+      const { start, end } = scrollPositionThresholds;
+      if (
+        !Number.isFinite(start) ||
+        !Number.isFinite(end) ||
+        start < 0 ||
+        end <= start
+      ) {
+        throw new Error(
+          'scrollPositionThresholds requires 0 <= start < end and finite values'
+        );
+      }
+      return JSON.stringify({ start, end });
+    }, [scrollPositionThresholds]);
     const snapshotJson = useMemo(() => serializeSnapshot(snapshot), [snapshot]);
     const snapshotRef = useRef(snapshot);
     const previousSnapshotJsonRef = useRef(snapshotJson);
@@ -391,8 +434,13 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
         }),
         onRowAction: callback((payloadJson: string) => {
           const payload = parsePayload<RowActionEvent>(payloadJson);
-          if (payload.actionKey === 'nativeList.refresh')
+          if (
+            payload.actionKey === 'nativeList.refresh' &&
+            payload.rowKey === undefined
+          ) {
             callbacksRef.current.onRefresh?.();
+            return;
+          }
           callbacksRef.current.onRowAction?.(payload);
         }),
         onActionAnchorInvalidated: callback((payloadJson: string) => {
@@ -427,6 +475,13 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
             parsePayload<EndReachedEvent>(payloadJson)
           );
         }),
+        onScrollPositionThresholdChange: callback(
+          (isBeyondThreshold: boolean) => {
+            callbacksRef.current.onScrollPositionThresholdChange?.({
+              isBeyondThreshold,
+            });
+          }
+        ),
         onVisibleRangeChanged: callback((payloadJson: string) => {
           const payload = parsePayload<VisibleRangeChangedEvent>(payloadJson);
           const previous = avatarRangeRef.current;
@@ -450,9 +505,36 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
         {...viewProps}
         {...nativeCallbacks}
         snapshotJson={snapshotJson}
+        containerSlotHeightsJson={containerSlotHeightsJson}
+        scrollPositionThresholdsJson={scrollPositionThresholdsJson}
         keyboardDismissMode={keyboardDismissMode}
         keyboardShouldPersistTaps={normalizedKeyboardShouldPersistTaps}
-      />
+      >
+        {slotContents.map((content, index) => (
+          <View
+            key={index}
+            collapsable={false}
+            style={{
+              position: 'absolute',
+              left: slotInset,
+              right: slotInset,
+              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
+                    )
+              );
+            }}
+          >
+            {content}
+          </View>
+        ))}
+      </NativeListHost>
     );
   }
 );

package/src/NativeList.types.ts

@@ -1,4 +1,4 @@
-import type { RefObject } from 'react';
+import type { ReactNode, RefObject } from 'react';
 import type { View, ViewProps } from 'react-native';
 import type {
   ActionAnchorInvalidatedEvent,
@@ -119,6 +119,10 @@ export type NativeListRef = Readonly<{
 export type NativeListProps = Omit<ViewProps, 'children'> &
   Readonly<{
     snapshot: NativeListSnapshot;
+    /** Native-only, container-owned scroll content. Never rendered as a data row. */
+    listHeader?: ReactNode;
+    listFooter?: ReactNode;
+    listEmpty?: ReactNode;
     /** Web only. Defaults to true and is ignored by the native host. */
     webVirtualizationEnabled?: boolean;
     /** Web only. Hosts the section index inside this container. */
@@ -136,6 +140,15 @@ export type NativeListProps = Omit<ViewProps, 'children'> &
     onReorder?: (event: ReorderEvent) => void;
     onEndReached?: (event: EndReachedEvent) => void;
     onVisibleRangeChanged?: (event: VisibleRangeChangedEvent) => void;
+    /** Native only. Emits initial state and hysteresis transitions, not scroll frames. */
+    scrollPositionThresholds?: Readonly<{
+      start: number;
+      end: number;
+      enabled?: boolean;
+    }>;
+    onScrollPositionThresholdChange?: (
+      event: Readonly<{ isBeyondThreshold: boolean }>
+    ) => void;
     onRefresh?: () => void;
     onScrollToIndexFailed?: (info: ScrollToIndexFailedInfo) => void;
   }> &

package/src/NativeList.web.tsx

@@ -82,6 +82,11 @@ export const NativeList = forwardRef<NativeListRef, NativeListProps>(
   function NativeList(
     {
       snapshot,
+      listHeader: _listHeader,
+      listEmpty: _listEmpty,
+      listFooter: _listFooter,
+      scrollPositionThresholds: _scrollPositionThresholds,
+      onScrollPositionThresholdChange: _onScrollPositionThresholdChange,
       webVirtualizationEnabled = true,
       webSectionIndexContainerRef,
       keyboardDismissMode: _keyboardDismissMode,

package/src/models.ts

@@ -517,6 +517,16 @@ export type RailRow = RowBase &
     style?: RailRowStyle;
   }>;
 
+export type ActivityAmount = Readonly<{
+  key: string;
+  text: string;
+  textSegments?: readonly ValueTextSegment[];
+  leading?: LeadingVisual;
+  tone?: TextTone;
+  secondaryText?: string;
+  secondaryTextSegments?: readonly ValueTextSegment[];
+}>;
+
 export type ActivityRow = RowBase &
   Readonly<{
     type: 'activity';
@@ -527,6 +537,18 @@ export type ActivityRow = RowBase &
     status?: string;
     primaryAmount?: string;
     secondaryAmount?: string;
+    amounts?: readonly ActivityAmount[];
+    badges?: readonly BadgeModel[];
+    presentation?: 'stacked' | 'table';
+    fee?: Readonly<{
+      label?: string;
+      primary: string;
+      primaryTextSegments?: readonly ValueTextSegment[];
+      secondary?: string;
+      secondaryTextSegments?: readonly ValueTextSegment[];
+      hidden?: boolean;
+    }>;
+    descriptionActionKey?: string;
     footerActions?: readonly FooterAction[];
     style?: ActivityRowStyle;
   }>;
@@ -601,6 +623,11 @@ export type MediaTileRow = RowBase &
   Readonly<{
     type: 'mediaTile';
     variant: 'gallery' | 'browserPreview';
+    /** Native preview; video candidates display a silent first frame, never autoplay. */
+    media?: Readonly<{
+      source: ImageSource;
+      probeOrder: readonly ('image' | 'video')[];
+    }>;
     image?: ImageSource;
     imageState?: 'empty' | 'error';
     networkImage?: ImageSource;
@@ -650,6 +677,7 @@ export type SectionHeaderRow = RowBase &
     indexTitle?: string;
     variant?: 'summary' | 'gallery' | 'history';
     title: string;
+    titleLoading?: boolean;
     subtitle?: string;
     value?: string;
     valueActionKey?: string;
@@ -795,7 +823,7 @@ export type NativeListSnapshot = Readonly<{
   layout: Readonly<{
     kind: NativeListLayout;
     orientation?: NativeListOrientation;
-    gridColumns?: 2 | 3 | 4;
+    gridColumns?: 2 | 3 | 4 | 5 | 6 | 7;
     stickyHeaders?: boolean;
     contentPadding?: number;
     contentPaddingHorizontal?: number;
@@ -813,6 +841,7 @@ export type NativeListSnapshot = Readonly<{
     reorderable?: boolean;
     pullToRefresh?: boolean;
     refreshing?: boolean;
+    refreshTriggerDistance?: number;
     loadMore?: boolean;
     endReachedThreshold?: number;
     sectionIndex?: SectionIndexConfig;
@@ -882,6 +911,11 @@ export type RowPatch =
           | 'title'
           | 'description'
           | 'status'
+          | 'amounts'
+          | 'badges'
+          | 'presentation'
+          | 'fee'
+          | 'descriptionActionKey'
           | 'primaryAmount'
           | 'secondaryAmount'
           | 'leading'
@@ -957,6 +991,7 @@ export type RowPatch =
           | CommonPatchFields
           | 'image'
           | 'imageState'
+          | 'media'
           | 'networkImage'
           | 'title'
           | 'subtitle'
@@ -993,6 +1028,7 @@ export type RowPatch =
           SectionHeaderRow,
           | CommonPatchFields
           | 'variant'
+          | 'titleLoading'
           | 'title'
           | 'subtitle'
           | 'value'
@@ -1036,6 +1072,7 @@ export type NativeListActionSource =
   | 'leadingAction'
   | 'trailingAccessory'
   | 'footerAction'
+  | 'description'
   | 'mediaClose';
 
 export type NativeListWindowRect = Readonly<{

package/src/validation.ts

@@ -175,6 +175,11 @@ const TEXT_STYLE_KEYS_BY_ROW_TYPE: Readonly<
     'title',
     'description',
     'status',
+    'amounts',
+    'badges',
+    'presentation',
+    'fee',
+    'descriptionActionKey',
     'primaryAmount',
     'secondaryAmount',
   ],
@@ -183,7 +188,7 @@ const TEXT_STYLE_KEYS_BY_ROW_TYPE: Readonly<
   market: ['title', 'subtitle', 'price', 'change'],
   mediaTile: ['title', 'subtitle', 'badge'],
   metricCard: ['title', 'value', 'subtitle', 'trend'],
-  sectionHeader: ['title', 'subtitle', 'value'],
+  sectionHeader: ['titleLoading', 'title', 'subtitle', 'value'],
   action: ['title', 'value'],
   system: ['title', 'message', 'actionText'],
 };
@@ -917,7 +922,84 @@ function assertVisual(row: RowModel, path: string): void {
   });
 }
 
-function assertActivity(row: ActivityRow, path: string): void {
+function assertActivity(row: Partial<ActivityRow>, path: string): void {
+  assertText(row.title, `${path}.title`);
+  assertText(row.description, `${path}.description`);
+  if (
+    row.presentation !== undefined &&
+    !['stacked', 'table'].includes(row.presentation)
+  )
+    fail(`${path}.presentation`, 'must be stacked or table');
+  if (row.descriptionActionKey !== undefined)
+    assertKey(row.descriptionActionKey, `${path}.descriptionActionKey`);
+  if ((row.amounts?.length ?? 0) > 32)
+    fail(`${path}.amounts`, 'supports at most 32 amount lines');
+  const amountKeys = new Set<string>();
+  row.amounts?.forEach((amount, index) => {
+    const amountPath = `${path}.amounts[${index}]`;
+    assertKey(amount.key, `${amountPath}.key`);
+    if (amountKeys.has(amount.key)) fail(amountPath, 'duplicate amount key');
+    amountKeys.add(amount.key);
+    assertText(amount.text, `${amountPath}.text`);
+    assertLeadingVisual(amount.leading, `${amountPath}.leading`);
+    assertText(amount.secondaryText, `${amountPath}.secondaryText`);
+    if (
+      amount.tone !== undefined &&
+      !['primary', 'secondary', 'positive', 'negative'].includes(amount.tone)
+    )
+      fail(`${amountPath}.tone`, 'invalid text tone');
+    amount.textSegments?.forEach((segment, segmentIndex) => {
+      assertText(
+        segment.text,
+        `${amountPath}.textSegments[${segmentIndex}].text`
+      );
+      if (segment.style !== undefined && segment.style !== 'subscript')
+        fail(amountPath, 'invalid text segment style');
+    });
+  });
+  const assertActivitySegments = (
+    segments: readonly { text: string; style?: string }[] | undefined,
+    segmentPath: string
+  ) =>
+    segments?.forEach((segment, index) => {
+      assertText(segment.text, `${segmentPath}[${index}].text`);
+      if (segment.style !== undefined && segment.style !== 'subscript')
+        fail(segmentPath, 'invalid text segment style');
+    });
+  row.amounts?.forEach((amount, index) =>
+    assertActivitySegments(
+      amount.secondaryTextSegments,
+      `${path}.amounts[${index}].secondaryTextSegments`
+    )
+  );
+  assertActivitySegments(
+    row.fee?.primaryTextSegments,
+    `${path}.fee.primaryTextSegments`
+  );
+  assertActivitySegments(
+    row.fee?.secondaryTextSegments,
+    `${path}.fee.secondaryTextSegments`
+  );
+  assertText(row.fee?.label, `${path}.fee.label`);
+  assertText(row.fee?.primary, `${path}.fee.primary`);
+  assertText(row.fee?.secondary, `${path}.fee.secondary`);
+  if ((row.badges?.length ?? 0) > 4)
+    fail(`${path}.badges`, 'supports at most 4 activity badges');
+  const badgeKeys = new Set<string>();
+  row.badges?.forEach((badge, index) => {
+    assertKey(badge.key, `${path}.badges[${index}].key`);
+    if (badgeKeys.has(badge.key)) fail(`${path}.badges`, 'duplicate badge key');
+    badgeKeys.add(badge.key);
+    assertText(badge.text, `${path}.badges[${index}].text`);
+    if (
+      badge.tone !== undefined &&
+      !['neutral', 'info', 'success', 'warning', 'danger'].includes(badge.tone)
+    )
+      fail(`${path}.badges`, 'invalid badge tone');
+  });
+  if (row.fee?.hidden !== undefined && typeof row.fee.hidden !== 'boolean')
+    fail(`${path}.fee.hidden`, 'must be boolean');
+
   if ((row.footerActions?.length ?? 0) > MAX_FOOTER_ACTIONS) {
     fail(
       `${path}.footerActions`,
@@ -1119,6 +1201,7 @@ function assertRow(
       assertMarketRow(row, path);
       break;
     case 'mediaTile':
+      assertMediaPreview(row.media, `${path}.media`);
       assertImage(row.image, `${path}.image`);
       if (
         row.imageState !== undefined &&
@@ -1126,10 +1209,14 @@ function assertRow(
       ) {
         fail(`${path}.imageState`, 'must be empty or error when provided');
       }
-      if (row.imageState === undefined && row.image === undefined) {
+      if (
+        row.imageState === undefined &&
+        row.image === undefined &&
+        row.media === undefined
+      ) {
         fail(
           `${path}.image`,
-          'is required unless imageState is empty or error'
+          'is required unless media is provided or imageState is empty or error'
         );
       }
       assertImage(row.networkImage, `${path}.networkImage`);
@@ -1168,6 +1255,11 @@ function assertRow(
       }
       break;
     case 'sectionHeader':
+      if (
+        row.titleLoading !== undefined &&
+        typeof row.titleLoading !== 'boolean'
+      )
+        fail(`${path}.titleLoading`, 'must be boolean');
       assertKey(row.sectionKey, `${path}.sectionKey`);
       if (
         row.presentation !== undefined &&
@@ -1292,14 +1384,57 @@ function assertGroups(rows: readonly RowModel[]): void {
   }
 }
 
+function assertMediaPreview(value: unknown, path: string) {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    fail(path, 'must be a media descriptor');
+  const media = value as {
+    source?: import('./models').ImageSource;
+    probeOrder?: unknown;
+  };
+  assertImage(media.source, `${path}.source`);
+  if (!media.source) fail(`${path}.source`, 'is required');
+  const order = media.probeOrder;
+  if (
+    !Array.isArray(order) ||
+    order.length < 1 ||
+    order.length > 2 ||
+    order.some((kind) => kind !== 'image' && kind !== 'video') ||
+    new Set(order).size !== order.length
+  ) {
+    fail(
+      `${path}.probeOrder`,
+      'must contain one or two distinct image/video candidates'
+    );
+  }
+}
+
 export function validateSnapshot(
   snapshot: NativeListSnapshot
 ): NativeListSnapshot {
+  if (
+    snapshot.capabilities?.refreshTriggerDistance !== undefined &&
+    (!Number.isFinite(snapshot.capabilities.refreshTriggerDistance) ||
+      snapshot.capabilities.refreshTriggerDistance <= 0)
+  )
+    fail(
+      'capabilities.refreshTriggerDistance',
+      'must be a positive finite number'
+    );
+
   assertPlainSerializable(snapshot, 'snapshot', new Set<object>());
   if (snapshot.schemaVersion !== 1) fail('snapshot.schemaVersion', 'must be 1');
   if (!Number.isSafeInteger(snapshot.generation) || snapshot.generation < 0) {
     fail('snapshot.generation', 'must be a non-negative safe integer');
   }
+  if (
+    snapshot.layout.gridColumns !== undefined &&
+    (!Number.isInteger(snapshot.layout.gridColumns) ||
+      snapshot.layout.gridColumns < 2 ||
+      snapshot.layout.gridColumns > 7)
+  ) {
+    fail('snapshot.layout.gridColumns', 'must be an integer from 2 to 7');
+  }
   if (snapshot.layout.kind === 'grid' && !snapshot.layout.gridColumns) {
     fail('snapshot.layout.gridColumns', 'is required for grid layout');
   }
@@ -1508,6 +1643,7 @@ function assertPatchChanges(patch: RowPatch, index: number): void {
       assertLeadingVisual(patch.changes.visual, `${path}.visual`);
       break;
     case 'activity':
+      assertActivity(patch.changes, path);
       assertText(patch.changes.title, `${path}.title`);
       assertText(patch.changes.description, `${path}.description`);
       assertText(patch.changes.status, `${path}.status`);
@@ -1576,6 +1712,7 @@ function assertPatchChanges(patch: RowPatch, index: number): void {
       );
       break;
     case 'mediaTile':
+      assertMediaPreview(patch.changes.media, `${path}.media`);
       assertImage(patch.changes.image, `${path}.image`);
       if (
         patch.changes.imageState !== undefined &&
@@ -1623,6 +1760,11 @@ function assertPatchChanges(patch: RowPatch, index: number): void {
       }
       break;
     case 'sectionHeader':
+      if (
+        patch.changes.titleLoading !== undefined &&
+        typeof patch.changes.titleLoading !== 'boolean'
+      )
+        fail(`${path}.titleLoading`, 'must be boolean');
       assertSectionHeaderVariant(patch.changes.variant, `${path}.variant`);
       assertText(patch.changes.title, `${path}.title`);
       assertText(patch.changes.subtitle, `${path}.subtitle`);