@unif/react-native-design 0.19.0 → 0.21.0

package/src/components/ui/Toast/ToastHost.tsx

@@ -11,15 +11,31 @@ import Animated, {
 import { useColors, useThemedStyles, motion, space } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
 import { dotColorFor, makeStyles } from './styles';
-import { _subs } from './toast';
-import type { Subscriber, ToastEntry, ToastHostProps } from './types';
+import {
+  completeToast,
+  isCurrentToastDelivery,
+  registerToastHost,
+} from './toast';
+import type { ToastDelivery } from './store';
+import type { ToastHostProps } from './types';
+
+/** Host 侧的同步身份副本 —— 迟到回调据此在动 UI 前自证「我还是当前那一次投递」。 */
+type DeliveryIdentity = {
+  ownerToken: symbol;
+  leaseId: number;
+  entryId: number;
+};
 
 /**
- * 在根附近挂一次。监听 toast() 调用并渲染当前 toast。
- * 同一时间只显示一条 —— 新的会替换旧的。
+ * 在根附近挂**一次**。监听 toast() 调用并渲染当前 toast。
+ * 同一时间只显示一条 —— 新的会替换旧的(latest-wins)。
  *
  * 位置由 `entry.position`('top' / 'bottom' / 'center')决定,top/bottom 自动避让
  * safe-area;进入动画方向随位置(top 从上滑、bottom/center 从下滑)。
+ *
+ * 竞态纪律:每个 timer / 动画完成回调在改 UI 或上报完成前,都要同时通过同步 ref
+ * 与 `isCurrentToastDelivery(delivery)` 两道校验 —— 只靠其中之一都不够:ref 挡不住
+ * 「Host 重挂后同一 entry 的新投递」,Store 挡不住 React 批处理造成的 state 滞后。
  */
 export function ToastHost({
   testID,
@@ -27,34 +43,70 @@ export function ToastHost({
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
   const insets = useSafeAreaInsets();
-  const [entry, setEntry] = useState<ToastEntry | null>(null);
+  const [delivery, setDelivery] = useState<ToastDelivery | null>(null);
+  const [inert, setInert] = useState(false);
   const op = useSharedValue(0);
   const ty = useSharedValue(8);
   const dismissTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const currentDeliveryRef = useRef<DeliveryIdentity | null>(null);
 
   useEffect(() => {
-    const sub: Subscriber = (next) => {
-      if (dismissTimer.current) clearTimeout(dismissTimer.current);
-      setEntry(next);
+    const subscriber = (next: ToastDelivery) => {
+      // 顺序固定:先撤销旧回调 → 再写同步身份 ref → 最后才动 React state。
+      if (dismissTimer.current) {
+        clearTimeout(dismissTimer.current);
+        dismissTimer.current = null;
+      }
+      cancelAnimation(op);
+      cancelAnimation(ty);
+      currentDeliveryRef.current = {
+        ownerToken: next.ownerToken,
+        leaseId: next.leaseId,
+        entryId: next.entry.id,
+      };
+      setDelivery(next);
     };
-    _subs.add(sub);
+    const lease = registerToastHost(subscriber);
+    if (!lease) {
+      setInert(true);
+      return;
+    }
     return () => {
-      _subs.delete(sub);
+      // 顺序固定:先清身份 ref(让所有在途回调立刻失效)→ 撤销 timer/动画 → 最后释放 owner。
+      currentDeliveryRef.current = null;
+      if (dismissTimer.current) {
+        clearTimeout(dismissTimer.current);
+        dismissTimer.current = null;
+      }
+      cancelAnimation(op);
+      cancelAnimation(ty);
+      lease.release();
     };
-  }, []);
+  }, [op, ty]);
 
-  // 退场完成只清「仍是自己」的 entry:withTiming 完成回调经 runOnJS 跨线程异步投递,
-  // 投递到执行之间若来了新 toast,无 id 守卫的 setEntry(null) 会把新 toast 瞬时清掉([M-14])。
-  const dismissIfCurrent = useCallback((id: number) => {
-    setEntry((cur) => (cur?.id === id ? null : cur));
+  /** 退场完成:双重校验通过才清 UI 并上报完成,避免抹掉竞态期到达的新 toast([M-14])。 */
+  const finishIfCurrent = useCallback((finished: ToastDelivery) => {
+    const identity = currentDeliveryRef.current;
+    if (
+      !identity ||
+      identity.ownerToken !== finished.ownerToken ||
+      identity.leaseId !== finished.leaseId ||
+      identity.entryId !== finished.entry.id
+    ) {
+      return;
+    }
+    if (!isCurrentToastDelivery(finished)) return;
+    completeToast(finished.ownerToken, finished.leaseId, finished.entry.id);
+    currentDeliveryRef.current = null;
+    setDelivery((current) => (current === finished ? null : current));
   }, []);
 
   useEffect(() => {
-    if (!entry) return;
+    if (!delivery) return;
+    const entry = delivery.entry;
     // [M-15] toast 出现时主动播报 —— 容器 pointerEvents="none" + 3s 自动消失,
     // SR 用户对一闪而过的反馈本无任何感知通道。
     AccessibilityInfo.announceForAccessibility(entry.message);
-    const id = entry.id;
     // 进入方向:top 从上(-8)滑入,bottom / center 从下(8)滑入
     const from = entry.position === 'top' ? -8 : 8;
     cancelAnimation(op);
@@ -65,25 +117,32 @@ export function ToastHost({
     ty.value = withTiming(0, { duration: motion.base });
 
     dismissTimer.current = setTimeout(() => {
+      // 定时器触发时可能早已不是当前投递(新 toast 抢先)—— 先自证再播退场动画。
+      if (!isCurrentToastDelivery(delivery)) return;
       op.value = withTiming(0, { duration: motion.base });
-      ty.value = withTiming(from, { duration: motion.base }, (finished) => {
-        if (finished) runOnJS(dismissIfCurrent)(id);
+      ty.value = withTiming(from, { duration: motion.base }, (done) => {
+        if (done) runOnJS(finishIfCurrent)(delivery);
       });
     }, entry.duration);
 
     return () => {
-      if (dismissTimer.current) clearTimeout(dismissTimer.current);
+      if (dismissTimer.current) {
+        clearTimeout(dismissTimer.current);
+        dismissTimer.current = null;
+      }
       cancelAnimation(op);
       cancelAnimation(ty);
     };
-  }, [entry, op, ty, dismissIfCurrent]);
+  }, [delivery, op, ty, finishIfCurrent]);
 
   const animatedStyle = useAnimatedStyle(() => ({
     opacity: op.value,
     transform: [{ translateY: ty.value }],
   }));
 
-  if (!entry) return null;
+  if (inert || !delivery) return null;
+
+  const entry = delivery.entry;
 
   // 位置:top=顶部(safe-area + 间距)/ center=屏幕居中 / bottom=底部(默认)
   const posStyle =

package/src/components/ui/Toast/ToastHost.web.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { AccessibilityInfo, Text, View } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import {
@@ -8,19 +8,35 @@ import {
   usePrefersReducedMotion,
   useThemedStyles,
 } from '../../../theme';
+import { childTestID } from '../../../utils/testID';
 import { dotColorFor, makeStyles } from './styles';
-import { _subs } from './toast';
-import type { Subscriber, ToastEntry, ToastHostProps } from './types';
+import {
+  completeToast,
+  isCurrentToastDelivery,
+  registerToastHost,
+} from './toast';
+import type { ToastDelivery } from './store';
+import type { ToastHostProps } from './types';
+
+/** Host 侧的同步身份副本 —— 迟到回调据此在动 UI 前自证「我还是当前那一次投递」。 */
+type DeliveryIdentity = {
+  ownerToken: symbol;
+  leaseId: number;
+  entryId: number;
+};
 
 /**
- * Web 端 ToastHost —— RN-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle
- * 链路会在 _updatePropsJS 里 Object.keys 抛 TypeError(点击就崩),走纯 React + CSS
- * transition 实现 fade + slide,native 端仍走 ToastHost.tsx 的 reanimated 实现。
+ * Web 端 ToastHost —— RN-Web 上 reanimated 的 useAnimatedStyle 链路会在
+ * `_updatePropsJS` 里 `Object.keys` 抛 TypeError(点击就崩),故走纯 React + CSS
+ * transition 实现 fade + slide;native 端仍走 ToastHost.tsx 的 reanimated 实现。
  *
  * 行为复刻 native 版:
  * - opacity 0→1 + translateY 8→0 入场(motion.base ms)
  * - 停留 entry.duration ms
  * - opacity 1→0 + translateY 0→8 退场后 unmount
+ *
+ * 竞态纪律与 native 版一致:timer / RAF 在改 UI 或上报完成前,都要同时通过同步 ref
+ * 与 `isCurrentToastDelivery(delivery)` 两道校验。
  */
 export function ToastHost({
   testID,
@@ -29,64 +45,113 @@ export function ToastHost({
   const styles = useThemedStyles(makeStyles);
   const insets = useSafeAreaInsets();
   const reduced = usePrefersReducedMotion();
-  const [entry, setEntry] = useState<ToastEntry | null>(null);
+  const [delivery, setDelivery] = useState<ToastDelivery | null>(null);
+  const [inert, setInert] = useState(false);
   const [visible, setVisible] = useState(false);
   const dismissTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const exitTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const enterRafRef = useRef<number | null>(null);
+  const currentDeliveryRef = useRef<DeliveryIdentity | null>(null);
+
+  const cancelCallbacks = useCallback(() => {
+    if (dismissTimerRef.current) {
+      clearTimeout(dismissTimerRef.current);
+      dismissTimerRef.current = null;
+    }
+    if (exitTimerRef.current) {
+      clearTimeout(exitTimerRef.current);
+      exitTimerRef.current = null;
+    }
+    if (enterRafRef.current != null) {
+      cancelAnimationFrame(enterRafRef.current);
+      enterRafRef.current = null;
+    }
+  }, []);
 
   useEffect(() => {
-    const sub: Subscriber = (next) => {
-      setEntry(next);
+    const subscriber = (next: ToastDelivery) => {
+      // 顺序固定:先撤销旧回调 → 再写同步身份 ref → 最后才动 React state。
+      cancelCallbacks();
+      currentDeliveryRef.current = {
+        ownerToken: next.ownerToken,
+        leaseId: next.leaseId,
+        entryId: next.entry.id,
+      };
+      setDelivery(next);
     };
-    _subs.add(sub);
+    const lease = registerToastHost(subscriber);
+    if (!lease) {
+      setInert(true);
+      return;
+    }
     return () => {
-      _subs.delete(sub);
+      // 顺序固定:先清身份 ref(让所有在途回调立刻失效)→ 撤销 timer/RAF → 最后释放 owner。
+      currentDeliveryRef.current = null;
+      cancelCallbacks();
+      lease.release();
     };
+  }, [cancelCallbacks]);
+
+  /** 退场完成:双重校验通过才清 UI 并上报完成。 */
+  const finishIfCurrent = useCallback((finished: ToastDelivery) => {
+    const identity = currentDeliveryRef.current;
+    if (
+      !identity ||
+      identity.ownerToken !== finished.ownerToken ||
+      identity.leaseId !== finished.leaseId ||
+      identity.entryId !== finished.entry.id
+    ) {
+      return;
+    }
+    if (!isCurrentToastDelivery(finished)) return;
+    completeToast(finished.ownerToken, finished.leaseId, finished.entry.id);
+    currentDeliveryRef.current = null;
+    setDelivery((current) => (current === finished ? null : current));
   }, []);
 
   useEffect(() => {
-    // entry=null:上一轮 effect 的 cleanup 已清 timer/RAF,这里无需重复。
-    if (!entry) return;
+    // delivery=null:上一轮 effect 的 cleanup 已清 timer/RAF,这里无需重复。
+    if (!delivery) return;
+    const entry = delivery.entry;
     // [M-15] web 同样主动播报(RN-Web announceForAccessibility 注入 aria-live region)。
     AccessibilityInfo.announceForAccessibility(entry.message);
 
-    // cancelled 标志:entry 快速连续切换 / 组件卸载时,cleanup 置 true。RAF 与
+    // cancelled 标志:delivery 快速连续切换 / 组件卸载时,cleanup 置 true。RAF 与
     // timer 回调执行前都检查它 —— cancelAnimationFrame 在部分浏览器不保证取消
     // 已排队回调,且双 RAF 的外层回调可能在 cleanup 后仍跑并 queue 内层,光靠
     // cancel 防不住。cancelled 兜底,杜绝 unmount 后 setState 警告 + 状态错位。
     let cancelled = false;
-    // 进场:每次 entry 切换都从 visible=false 开始,确保 CSS transition 有起点
+    // 进场:每次切换都从 visible=false 开始,确保 CSS transition 有起点
     setVisible(false);
     // 双 RAF 才能稳过 React commit/paint 一帧 —— 否则同一 microtask 内 visible
     // 还是 true(未刷),CSS transition 没起点。
     enterRafRef.current = requestAnimationFrame(() => {
       if (cancelled) return;
       enterRafRef.current = requestAnimationFrame(() => {
-        if (cancelled) return;
+        if (cancelled || !isCurrentToastDelivery(delivery)) return;
+        enterRafRef.current = null;
         setVisible(true);
       });
     });
-    // 停留时长:从 setEntry 到关闭 = entry.duration ms。
+    // 停留时长:从投递到关闭 = entry.duration ms。
     dismissTimerRef.current = setTimeout(() => {
-      if (cancelled) return;
+      if (cancelled || !isCurrentToastDelivery(delivery)) return;
       setVisible(false);
       exitTimerRef.current = setTimeout(() => {
         if (cancelled) return;
-        setEntry(null);
+        finishIfCurrent(delivery);
       }, motion.base);
     }, entry.duration);
 
     return () => {
       cancelled = true;
-      if (dismissTimerRef.current) clearTimeout(dismissTimerRef.current);
-      if (exitTimerRef.current) clearTimeout(exitTimerRef.current);
-      if (enterRafRef.current != null)
-        cancelAnimationFrame(enterRafRef.current);
+      cancelCallbacks();
     };
-  }, [entry]);
+  }, [delivery, cancelCallbacks, finishIfCurrent]);
+
+  if (inert || !delivery) return null;
 
-  if (!entry) return null;
+  const entry = delivery.entry;
 
   // 位置:top=顶部(safe-area + 间距)/ center=屏幕居中 / bottom=底部(默认),复刻 native 版。
   // 此前 web 完全未注入定位,position 参数被静默忽略、垂直位置随挂载次序漂移([H-6])。
@@ -113,10 +178,7 @@ export function ToastHost({
           {dotColor ? (
             <View style={[styles.dot, { backgroundColor: dotColor }]} />
           ) : null}
-          <Text
-            style={styles.text}
-            testID={testID ? `${testID}-text` : undefined}
-          >
+          <Text style={styles.text} testID={childTestID(testID, 'text')}>
             {entry.message}
           </Text>
         </View>

package/src/components/ui/Toast/store.ts

@@ -0,0 +1,148 @@
+import type { Logger } from '../../../utils/logger';
+import type { ToastEntry } from './types';
+
+/**
+ * Toast 的纯状态机 —— 不含任何 React / 渲染依赖,可直接单测。
+ *
+ * 与 Confirm 的语义**不同**,故意不抽成泛型事件总线:
+ * - Confirm 是「一次决策」,需要 active entry + Promise;
+ * - Toast 是「最新一条覆盖旧的」,需要 pending / delivery 双态。
+ *
+ * 双态模型:
+ * - `pending` —— 还没有 Host 接住的最新一条消息。**latest-wins**:后来的直接覆盖,
+ *   不排队(toast 是瞬时反馈,补投一串历史消息毫无意义)。
+ * - `delivered` —— 已交给当前 Host 的那一条,带 `ownerToken` + `leaseId` + `entry.id`
+ *   三重身份。Host 的每个 timer / RAF / 动画完成回调在动 UI 前都必须用这三项做 CAS,
+ *   否则旧回调会把新 toast 提前抹掉(经典竞态:A 的 3s 定时器在 B 显示后才触发)。
+ *
+ * `leaseId` 单调递增,同一 entry 被重新投递(Host 重挂)也会拿到新的 leaseId ——
+ * 仅比较 entry.id 不足以区分「同一条消息的两次投递」。
+ */
+
+export type ToastDelivery = {
+  entry: ToastEntry;
+  ownerToken: symbol;
+  leaseId: number;
+};
+
+export type ToastSubscriber = (delivery: ToastDelivery) => void;
+
+export type ToastHostLease = {
+  readonly ownerToken: symbol;
+  release(): void;
+};
+
+export type ToastStore = {
+  publish(entry: ToastEntry): void;
+  registerHost(subscriber: ToastSubscriber): ToastHostLease | null;
+  complete(ownerToken: symbol, leaseId: number, entryId: number): boolean;
+  isCurrent(delivery: ToastDelivery): boolean;
+  pendingEntry(): ToastEntry | null;
+  currentDelivery(): ToastDelivery | null;
+};
+
+type Owner = { token: symbol; subscriber: ToastSubscriber | null };
+
+export function createToastStore(log: Logger): ToastStore {
+  let pending: ToastEntry | null = null;
+  let delivered: ToastDelivery | null = null;
+  let owner: Owner | null = null;
+  let leaseCounter = 0;
+
+  function beginDelivery(entry: ToastEntry, capturedOwner: Owner): void {
+    const delivery: ToastDelivery = {
+      entry,
+      ownerToken: capturedOwner.token,
+      leaseId: ++leaseCounter,
+    };
+    // 先原子地把 pending 取走并落 delivered,再调 subscriber:subscriber 内同步
+    // 再 publish 时看到的必须是「已投递」而不是「还在 pending」的半状态。
+    pending = null;
+    delivered = delivery;
+    try {
+      capturedOwner.subscriber?.(delivery);
+    } catch (error) {
+      log.error('ToastHost subscriber 抛错', error);
+      // 期间若 owner 已换人 / 已被作废,这次抛错不能牵连新 owner 或覆盖更新的 pending。
+      if (owner?.token !== capturedOwner.token) return;
+      owner = null;
+      if (delivered?.ownerToken === capturedOwner.token) {
+        // 回存的是 delivered 而非 entry:subscriber 内可能已同步投递了更新的一条,
+        // 那条才是当前逻辑消息(latest-wins)。已 complete 的则 delivered 为 null,不复活。
+        pending = delivered.entry;
+        delivered = null;
+      }
+    }
+  }
+
+  function publish(entry: ToastEntry): void {
+    const current = owner;
+    // 未挂 Host 是**受支持路径**,不告警:启动早期的 toast 应当在 Host 挂上后补投。
+    if (!current?.subscriber) {
+      pending = entry;
+      return;
+    }
+    beginDelivery(entry, current);
+  }
+
+  function registerHost(subscriber: ToastSubscriber): ToastHostLease | null {
+    if (owner) {
+      log.warn(
+        '检测到多个 <ToastHost />。只有第一个生效,重复挂载的实例保持惰性 —— 请在 app 根只挂一次。'
+      );
+      return null;
+    }
+    const token = Symbol('ToastHostOwner');
+    const self: Owner = { token, subscriber };
+    owner = self;
+    if (pending) beginDelivery(pending, self);
+    // 首投期间 subscriber 抛错会把 owner 作废 —— 此时不能发出可用的 lease。
+    if (owner?.token !== token) return null;
+    return {
+      ownerToken: token,
+      release(): void {
+        if (owner?.token !== token) return;
+        self.subscriber = null;
+        owner = null;
+        if (delivered?.ownerToken === token) {
+          // 未完成的投递退回 pending,让下一个 Host 能补投;但更新的 pending 优先。
+          if (!pending) pending = delivered.entry;
+          delivered = null;
+        }
+      },
+    };
+  }
+
+  function complete(
+    ownerToken: symbol,
+    leaseId: number,
+    entryId: number
+  ): boolean {
+    const current = delivered;
+    if (!current) return false;
+    if (current.ownerToken !== ownerToken) return false;
+    if (current.leaseId !== leaseId) return false;
+    if (current.entry.id !== entryId) return false;
+    delivered = null;
+    return true;
+  }
+
+  function isCurrent(delivery: ToastDelivery): boolean {
+    const current = delivered;
+    return (
+      current !== null &&
+      current.ownerToken === delivery.ownerToken &&
+      current.leaseId === delivery.leaseId &&
+      current.entry.id === delivery.entry.id
+    );
+  }
+
+  return {
+    publish,
+    registerHost,
+    complete,
+    isCurrent,
+    pendingEntry: () => pending,
+    currentDelivery: () => delivered,
+  };
+}

package/src/components/ui/Toast/toast.ts

@@ -2,14 +2,19 @@
  * 命令式 `toast()` API —— 与 `<ToastHost />` 配对使用。
  *
  * 文件名故意小写 `toast.ts`,host 组件叫 `ToastHost.tsx`,避免 APFS 大小写冲突。
+ *
+ * 本文件只做公共入参归一化(kind / duration / position),投递与身份仲裁全部在
+ * `store.ts`。下面三个内部导出只给两个 Host 用,**不进公共 barrel**。
  */
 import { createLogger } from '../../../utils/logger';
-import type { Subscriber, ToastEntry, ToastInput, ToastKind } from './types';
+import { createToastStore } from './store';
+import type { ToastEntry, ToastInput, ToastKind } from './types';
 
 const log = createLogger('toast');
 
+const store = createToastStore(log);
+
 let _id = 0;
-export const _subs = new Set<Subscriber>();
 
 const DEFAULT_DURATION = 3000;
 // [L-55] duration 合法域:[1, 2^31)。INT32_MAX = 2^31-1 = 2147483647,
@@ -45,14 +50,9 @@ function emit(input: ToastInput, kind: ToastKind = 'info') {
           duration: clampDuration(input.duration),
           position: input.position ?? 'bottom',
         };
-  // 未挂 <ToastHost />:消息无人接收,告警提示集成漏挂(对照 confirm 重入告警的纪律)。
-  if (_subs.size === 0) {
-    log.warn(
-      'toast() 调用时未挂载 <ToastHost />,消息被丢弃。请在 app 根附近挂一次 <ToastHost />。'
-    );
-    return;
-  }
-  _subs.forEach((s) => s(entry));
+  // 未挂 <ToastHost /> 是**受支持路径**:消息留在 pending,Host 挂上后立即补投。
+  // 故这里不告警 —— 启动早期的 toast 本来就可能先于 Host。
+  store.publish(entry);
 }
 
 /**
@@ -68,3 +68,12 @@ export const toast = Object.assign((input: ToastInput) => emit(input, 'info'), {
   success: (input: ToastInput) => emit(input, 'success'),
   error: (input: ToastInput) => emit(input, 'error'),
 });
+
+/** 内部:ToastHost 挂载时注册唯一 owner;重复挂载得到 null。 */
+export const registerToastHost = store.registerHost;
+
+/** 内部:三重身份 CAS —— owner token + leaseId + entry id 全对才算完成。 */
+export const completeToast = store.complete;
+
+/** 内部:timer / RAF / 动画回调动 UI 前的守卫。 */
+export const isCurrentToastDelivery = store.isCurrent;

package/src/components/ui/Toast/types.ts

@@ -22,8 +22,12 @@ export type ToastInput =
       position?: ToastPosition;
     };
 
+/**
+ * 归一化后的一条 toast。`id` 是**内部身份**,与 `ToastDelivery` 的 ownerToken /
+ * leaseId 一起构成竞态守卫,不保证跨版本稳定 —— 业务不要依赖它的具体取值。
+ */
 export type ToastEntry = {
-  /** 唯一 id（自增）—— 退场守卫用:ToastHost 只清「仍是当前」的 toast,避免清掉竞态期到达的新 toast */
+  /** 内部自增 id —— 竞态守卫的一环,Host 只处理「仍是当前投递」的回调 */
   id: number;
   /** 消息文本 */
   message: string;
@@ -35,8 +39,8 @@ export type ToastEntry = {
   position: ToastPosition;
 };
 
-/** Toast 订阅者函数签名（ToastHost 内部用） */
-export type Subscriber = (entry: ToastEntry) => void;
+// delivery / lease / subscriber 类型都在 `store.ts` —— 它们是 Host 与 Store 之间的
+// 内部协议,不进公共 barrel。
 
 export type ToastHostProps = {
   /** E2E / 测试定位（业务读 toast 文本时用） */

package/src/components/ui/index.ts

@@ -7,9 +7,15 @@ export type { ButtonProps, ButtonSize, ButtonVariant } from './Button';
 export { Card } from './Card';
 export type { CardProps, CardVariant } from './Card';
 export { Carousel } from './Carousel';
-export type { CarouselProps } from './Carousel';
+export type { CarouselProps, CarouselRef } from './Carousel';
 export { Cell, List } from './Cell';
-export type { CellProps, ListProps } from './Cell';
+export type {
+  CellExtra,
+  CellLeading,
+  CellProps,
+  CellTextValue,
+  ListProps,
+} from './Cell';
 export { Checkbox } from './Checkbox';
 export type { CheckboxProps } from './Checkbox';
 export { Chip } from './Chip';
@@ -31,11 +37,16 @@ export type { IconName, IconProps } from './Icon';
 export { IconButton } from './IconButton';
 export type { IconButtonProps } from './IconButton';
 export { Input } from './Input';
-export type { InputProps } from './Input';
+export type {
+  InputProps,
+  TextFieldContainerStyle,
+  TextFieldHandle,
+  TextFieldSlot,
+} from './Input';
 export { Logo } from './Logo';
 export type { LogoProps } from './Logo';
 export { NavBar } from './NavBar';
-export type { NavBarProps, NavBarSlotConfig } from './NavBar';
+export type { NavBarAction, NavBarProps, NavBarSlot } from './NavBar';
 export { PasswordInput } from './PasswordInput';
 export type { PasswordInputProps } from './PasswordInput';
 export { Pulse, PulseDot, usePulse } from './Pulse';
@@ -71,7 +82,11 @@ export type { TagProps, TagSize, TagVariant } from './Tag';
 export { Textarea } from './Textarea';
 export type { TextareaProps } from './Textarea';
 export { Thumbnail } from './Thumbnail';
-export type { ThumbnailProps, ThumbnailSize } from './Thumbnail';
+export type {
+  ThumbnailImageStyle,
+  ThumbnailProps,
+  ThumbnailSize,
+} from './Thumbnail';
 export { toast, ToastHost } from './Toast';
 export type {
   ToastEntry,

package/src/components/ui/shared/ImageAttempt.tsx

@@ -0,0 +1,30 @@
+import React, { useCallback, useState } from 'react';
+import { Image } from 'react-native';
+import type { ImageProps, ImageSourcePropType } from 'react-native';
+import { selectImageAttemptSource } from './selectImageAttemptSource';
+
+type ImageAttemptProps = Omit<ImageProps, 'onError' | 'source'> & {
+  source: ImageSourcePropType;
+  fallback: React.ReactNode;
+};
+
+/**
+ * 每个 keyed 挂载实例只拥有自己的失败状态。source identity 变化时由父级 key
+ * 同步换实例，旧 onError 无法写入新 attempt。
+ */
+export function ImageAttempt({
+  source,
+  fallback,
+  ...imageProps
+}: ImageAttemptProps): React.JSX.Element {
+  const [failed, setFailed] = useState(false);
+  // RNW 的加载 effect 依赖 onError identity；等价 render 不应中止并重发请求。
+  const handleError = useCallback(() => setFailed(true), []);
+  const selectedSource = selectImageAttemptSource(source);
+
+  return failed || selectedSource === undefined ? (
+    <>{fallback}</>
+  ) : (
+    <Image {...imageProps} source={selectedSource} onError={handleError} />
+  );
+}

package/src/components/ui/shared/a11y.ts

@@ -0,0 +1,18 @@
+/**
+ * 装饰性节点从 a11y 树里隐藏所需的**全套**属性 —— 四个平台各认一个,少一个就漏。
+ *
+ * - `accessible: false` —— iOS/Android 都不把该节点合并成可聚焦元素
+ * - `accessibilityElementsHidden` —— iOS 连同后代一起移出 a11y 树
+ * - `importantForAccessibility: 'no-hide-descendants'` —— Android 同上
+ * - `aria-hidden` —— react-native-web 映射到 DOM 的 `aria-hidden`
+ *
+ * **只能**落在库内本地的 RN `View` / `Image` / `Text` 上。绝不要展开给未知第三方组件:
+ * 它们可能把未识别的 props 原样透传到原生层,或者干脆用同名 prop 表达别的语义。
+ * 需要隐藏第三方子树时,用一个本地 View 包住它,把这些属性挂在包装层。
+ */
+export const A11Y_HIDDEN_PROPS = {
+  'accessible': false,
+  'accessibilityElementsHidden': true,
+  'importantForAccessibility': 'no-hide-descendants',
+  'aria-hidden': true,
+} as const;