@unif/react-native-design 0.20.0 → 0.21.0

package/src/components/ui/Thumbnail/index.ts

@@ -1,2 +1,6 @@
 export { Thumbnail } from './Thumbnail';
-export type { ThumbnailProps, ThumbnailSize } from './types';
+export type {
+  ThumbnailImageStyle,
+  ThumbnailProps,
+  ThumbnailSize,
+} from './types';

package/src/components/ui/Thumbnail/normalize.ts

@@ -0,0 +1,78 @@
+import { StyleSheet } from 'react-native';
+import type { StyleProp } from 'react-native';
+import type { ThumbnailImageStyle } from './types';
+
+const RESERVED_IMAGE_STYLE_KEYS = [
+  'position',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'width',
+  'height',
+  'minWidth',
+  'minHeight',
+  'maxWidth',
+  'maxHeight',
+] as const;
+
+type SanitizedThumbnailImageStyle = {
+  style: ThumbnailImageStyle;
+  diagnostics: readonly string[];
+};
+
+function invalidStyle(): SanitizedThumbnailImageStyle {
+  return { style: {}, diagnostics: ['style'] };
+}
+
+function isEmptyStyleInput(value: unknown): boolean {
+  if (value === undefined || value === null || value === false) return true;
+  if (!Array.isArray(value)) return false;
+  return value.every(isEmptyStyleInput);
+}
+
+/**
+ * 先 flatten 再复制允许字段，兼容 registered / array style，同时不修改 caller。
+ * 任意异常或非对象产物都失败关闭，避免宽类型 JS 值穿透到原生 Image。
+ */
+export function sanitizeThumbnailImageStyle(
+  style: StyleProp<ThumbnailImageStyle> | undefined
+): SanitizedThumbnailImageStyle {
+  try {
+    if (isEmptyStyleInput(style)) {
+      return { style: {}, diagnostics: [] };
+    }
+    if (typeof style !== 'object' && typeof style !== 'number') {
+      return invalidStyle();
+    }
+
+    const flattened = StyleSheet.flatten(style) as unknown;
+    if (flattened === undefined || flattened === null || flattened === false) {
+      return invalidStyle();
+    }
+    if (typeof flattened !== 'object' || Array.isArray(flattened)) {
+      return invalidStyle();
+    }
+
+    const source = flattened as Record<string, unknown>;
+    const reserved = new Set<string>(RESERVED_IMAGE_STYLE_KEYS);
+    const foundReserved = new Set<string>();
+    const sanitized: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(source)) {
+      if (reserved.has(key)) {
+        foundReserved.add(key);
+      } else {
+        sanitized[key] = value;
+      }
+    }
+
+    return {
+      style: sanitized as ThumbnailImageStyle,
+      diagnostics: RESERVED_IMAGE_STYLE_KEYS.filter((key) =>
+        foundReserved.has(key)
+      ),
+    };
+  } catch {
+    return invalidStyle();
+  }
+}

package/src/components/ui/Thumbnail/styles.ts

@@ -2,22 +2,17 @@ import { StyleSheet } from 'react-native';
 import { r, type ColorTokens } from '../../../theme';
 import type { ThumbnailSize } from './types';
 
-/** [L-94] ring 圆角外展量:border(2) + padding(1) = 3pt,让外圈圆角贴合内圆角。
- *  Thumbnail.tsx 侧用此常量替代魔数 `+ 3`。 */
-export const RING_EXTRA_RADIUS = r(2) + r(1); // border + padding
-
 /** Thumbnail 静态样式 ——
- *  - `base`:Image 占位色,加载中 / 失败时不至于空白
- *  - `ring`:`selected` 态的外圈品牌色描边,padding 抵消 ring 与 image 之间留 1pt gap */
+ *  - `visualFrame`:固定尺寸、裁切、加载失败 placeholder
+ *  - `ring`:始终存在的 2pt visual overlay，selected 只切颜色 */
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
-    base: {
+    visualFrame: {
       backgroundColor: c.surfaceContainer,
+      overflow: 'hidden',
     },
     ring: {
-      borderWidth: r(2),
-      borderColor: c.primary,
-      padding: r(1),
+      borderWidth: 2,
     },
   });
 

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

@@ -1,4 +1,10 @@
-import type { StyleProp, ImageStyle, ImageSourcePropType } from 'react-native';
+import type {
+  ImageProps,
+  ImageSourcePropType,
+  ImageStyle,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
 
 /** 缩略图尺寸阶梯 —— 跨场景统一,新增 size 在这里 + sizingFor.ts 同步。
  *  - sm:64×40 chat 行内、列表二级图缩略
@@ -6,22 +12,46 @@ import type { StyleProp, ImageStyle, ImageSourcePropType } from 'react-native';
  *  - lg:160×96 详情顶部 hero 小图、卡片头图缩略 */
 export type ThumbnailSize = 'sm' | 'md' | 'lg';
 
-export type ThumbnailProps = {
-  /** 远程 URL(http/https/data URI)。和 source 二选一,优先 uri。 */
-  uri?: string;
-  /** RN Image source —— 本地 require('...') / { uri:... } 完整对象。 */
-  source?: ImageSourcePropType;
+export type ThumbnailImageStyle = Omit<
+  ImageStyle,
+  | 'position'
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+  | 'width'
+  | 'height'
+  | 'minWidth'
+  | 'minHeight'
+  | 'maxWidth'
+  | 'maxHeight'
+>;
+
+type ThumbnailSource =
+  | {
+      /** 远程 URL(http/https/data URI)，运行时 trim 后必须非空。 */
+      uri: string;
+      source?: never;
+    }
+  | {
+      /** RN Image source —— 本地 require / URI object / URI candidate 数组。 */
+      source: ImageSourcePropType;
+      uri?: never;
+    };
+
+export type ThumbnailProps = ThumbnailSource & {
   /** 视觉尺寸阶梯,默认 'md'。 */
   size?: ThumbnailSize;
-  /** 选中态:在缩略图外侧画 2pt 品牌色 ring。
-   *  用于"图片多选 / picker 选中" —— 不再需要 caller 自行套 TouchableOpacity + borderColor。 */
+  /** 选中态:在固定 visual frame 内显示 2pt 品牌色 ring。 */
   selected?: boolean;
-  /** 自定义样式覆盖(尺寸 / 圆角 / bg 由 size 决定,style 仅做微调如 marginLeft)。 */
-  style?: StyleProp<ImageStyle>;
+  /** 完整外部布局样式，只落到稳定根 View。 */
+  containerStyle?: StyleProp<ViewStyle>;
+  /** 图片表面样式；不能覆盖 frame 的 position / inset / size geometry。 */
+  imageStyle?: StyleProp<ThumbnailImageStyle>;
   /** Image.resizeMode,默认 'cover'(裁切撑满)。 */
-  resizeMode?: 'cover' | 'contain' | 'stretch' | 'center';
-  /** a11y 描述,SR 朗读;不传 RN Image 默认 hidden。 */
+  resizeMode?: NonNullable<ImageProps['resizeMode']>;
+  /** trim 后非空时作为图片名称；缺省或空白时图片从 a11y tree 隐藏。 */
   accessibilityLabel?: string;
-  /** 测试 testID */
+  /** E2E / 测试定位，只落到外层 layout View。 */
   testID?: string;
 };

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>