@unif/react-native-design 0.20.0 → 0.21.1

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

@@ -17,6 +17,17 @@ export const makeStyles = (c: ColorTokens) =>
       paddingVertical: space[4],
       alignItems: 'flex-start',
     },
+    /** Search 的可见底色/边框绝不承载命中区域。 */
+    searchInteractiveRow: {
+      borderWidth: 0,
+    },
+    searchVisibleSurface: {
+      position: 'absolute',
+      left: 0,
+      right: 0,
+      borderRadius: radius.md,
+      borderWidth: 1,
+    },
     wrapIdle: {
       backgroundColor: c.surfaceContainerHigh,
       borderColor: 'transparent',
@@ -48,6 +59,23 @@ export const makeStyles = (c: ColorTokens) =>
     inputMultiline: {
       textAlignVertical: 'top' as const,
     },
+    slotDisplay: {
+      alignItems: 'center',
+      justifyContent: 'center',
+      minWidth: 18,
+      minHeight: 18,
+    },
+    slotText: {
+      color: c.foregroundMuted,
+      fontSize: t.sm,
+    },
+    // 固定命中框不走 r()/fontScale:它是手指可达性约束,不是视觉 token。
+    actionFrame: {
+      width: 44,
+      height: 44,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
     errorMsg: {
       fontSize: t.micro,
       color: c.error,
@@ -58,4 +86,7 @@ export const makeStyles = (c: ColorTokens) =>
     containerDisabled: {
       opacity: 0.5,
     },
+    rootCentered: {
+      justifyContent: 'center',
+    },
   });

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

@@ -1,27 +1,123 @@
-import type { ReactNode } from 'react';
 import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
+import type { IconName } from '../Icon';
 
-/** internal — Input / Textarea 共享 props。
- *  caller 不直接消费,通过 InputProps / TextareaProps 间接传入。 */
-export type TextFieldBaseProps = TextInputProps & {
-  /** false(默认)= Input 行为(单行,固定 height);true = Textarea 行为
-   *  (multiline,minHeight/maxHeight 控高,文字顶对齐) */
-  multiline?: boolean;
-  /** 单行 height(multiline=false 时生效),默认 control.lg */
-  height?: number;
-  /** 最小高度(multiline=true 时生效),默认 96 */
-  minHeight?: number;
-  /** 最大高度(multiline=true 时生效);超出 ScrollView 内滚 */
-  maxHeight?: number;
-  /** 左侧 slot —— Icon / 装饰 */
-  leading?: ReactNode;
-  /** 右侧 slot —— Icon / 操作按钮 */
-  trailing?: ReactNode;
-  /** 错误文案 —— 非空字符串时 wrap border 切 error 色,下方显示文本。
-   *  空串 `""` / undefined 都不进 error 态(truthy 判定)。 */
+/**
+ * 受控:必须同时给 `value` 和 `onChangeText`。
+ *
+ * `defaultValue?: never` 让「同时传 value 和 defaultValue」在类型层就报错 ——
+ * 那是最常见的受控/非受控混用写法,运行时表现为「defaultValue 被静默忽略」。
+ */
+export type ControlledTextValueProps = {
+  value: string;
+  onChangeText: (value: string) => void;
+  defaultValue?: never;
+};
+
+/** 非受控:内部持值,`defaultValue` 只在首次 render 读一次。 */
+export type UncontrolledTextValueProps = {
+  value?: never;
+  defaultValue?: string;
+  onChangeText?: (value: string) => void;
+};
+
+/** internal —— 由 InputProps / TextareaProps / SearchProps 组合进公共类型。 */
+export type TextFieldValueProps =
+  | ControlledTextValueProps
+  | UncontrolledTextValueProps;
+
+/**
+ * 输入类组件对外暴露的 ref。**只有** focus / blur。
+ *
+ * 为什么不暴露原生 TextInput —— `clear()` 会绕过值状态机(受控下把 UI 清空但调用方
+ * state 不变),`setNativeProps()` 能直接改任意原生属性,两者都会让公共契约失效。
+ */
+export type TextFieldHandle = {
+  focus: () => void;
+  blur: () => void;
+};
+
+/**
+ * 左右 slot 的可验证配置。**不接受任意 ReactNode** ——
+ * 任意节点意味着库无法判断它是装饰还是操作,也无法保证它有可访问名称与 44pt 命中框。
+ */
+export type TextFieldSlot =
+  | { kind: 'icon'; icon: IconName; size?: number; color?: string }
+  | { kind: 'text'; value: string | number }
+  | {
+      kind: 'action';
+      icon: IconName;
+      onPress: () => void;
+      accessibilityLabel: string;
+      disabled?: boolean;
+    };
+
+/**
+ * containerStyle 的可用字段。六个尺寸/裁剪字段被排除 ——
+ * 它们会覆盖 TextField 自持的最小命中框,让输入框缩到碰不到。
+ */
+export type TextFieldContainerStyle = Omit<
+  ViewStyle,
+  'height' | 'minHeight' | 'maxHeight' | 'minWidth' | 'maxWidth' | 'overflow'
+>;
+
+/** internal:Search 把真实交互行与仅作视觉的 surface 明确分层。 */
+export type SearchFieldLayout = {
+  interactiveHeight: number;
+  visibleHeight: number;
+  verticalInset: number;
+};
+
+/** TextField 家族共享的非值 props(内部)。 */
+export type TextFieldCommonProps = {
+  /** 左侧 slot —— 图标 / 文本 / 带 handler 与名称的操作 */
+  leading?: TextFieldSlot;
+  /** 右侧 slot —— 图标 / 文本 / 带 handler 与名称的操作 */
+  trailing?: TextFieldSlot;
+  /** 错误文案 —— 非空字符串时进入 error 态并在下方显示 */
   error?: string;
-  /** 整体禁用 —— opacity 0.5 + TextInput editable=false,优先级高于 editable */
+  /** 整体禁用 —— opacity 0.5 + 不可编辑,优先级高于原生 `editable` */
   disabled?: boolean;
-  /** 外层 View 附加 style */
-  containerStyle?: StyleProp<ViewStyle>;
+  /** 外层容器样式;不接受会破坏最小 frame 的尺寸字段 */
+  containerStyle?: StyleProp<TextFieldContainerStyle>;
 };
+
+/**
+ * 这些原生 TextInput props 从公共类型删除:
+ * - `style` / `multiline` / `numberOfLines`:由组件自己决定,单行多行分属 Input / Textarea
+ * - `value` / `defaultValue` / `onChangeText`:改由严格判别联合提供
+ * - `aria-disabled` / `readOnly` / `role`:与 `disabled` / `editable` / `accessibilityRole` 重复,
+ *   两条入口同时存在时优先级不可预测
+ * - `enterKeyHint`:与 `returnKeyType` 重复
+ * - `clearTextOnFocus`:绕过值状态机静默清值
+ */
+export type RemovedTextInputProps =
+  | 'style'
+  | 'multiline'
+  | 'numberOfLines'
+  | 'value'
+  | 'defaultValue'
+  | 'onChangeText'
+  | 'aria-disabled'
+  | 'readOnly'
+  | 'role'
+  | 'enterKeyHint'
+  | 'clearTextOnFocus';
+
+/**
+ * internal — TextFieldBase 的严格形状。公开组件在此基础上固定单/多行布局,
+ * 因此不能由未类型化的 native prop 反向覆盖 value、slot 或命中框规则。
+ */
+export type TextFieldBaseProps = Omit<TextInputProps, RemovedTextInputProps> &
+  TextFieldCommonProps &
+  TextFieldValueProps & {
+    /** internal:由 Input / Textarea / Search 固定,不作为公共可选入口。 */
+    multiline: boolean;
+    /** 单行 height(multiline=false 时生效),默认 control.lg */
+    height?: number;
+    /** 最小高度(multiline=true 时生效),默认 96 */
+    minHeight?: number;
+    /** 最大高度(multiline=true 时生效);超出 ScrollView 内滚 */
+    maxHeight?: number;
+    /** internal:Search 的 44pt interactive row + 36pt decorative surface。 */
+    searchLayout?: SearchFieldLayout;
+  };

package/src/components/ui/TextField/useErrorAnnouncement.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from 'react';
+import { AccessibilityInfo, Platform } from 'react-native';
+
+/** iOS 不会像 Android live region 一样自动播报动态错误,仅播报真实的后续变更。 */
+export function useErrorAnnouncement(error: string | undefined): void {
+  const previousError = useRef('');
+  const didCommit = useRef(false);
+
+  useEffect(() => {
+    const nextError = error ?? '';
+    const previous = previousError.current;
+    previousError.current = nextError;
+
+    if (!didCommit.current) {
+      didCommit.current = true;
+      return undefined;
+    }
+    if (Platform.OS !== 'ios' || nextError === '' || nextError === previous) {
+      return undefined;
+    }
+
+    const timer = setTimeout(() => {
+      AccessibilityInfo.announceForAccessibility(nextError);
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [error]);
+}

package/src/components/ui/TextField/useTextFieldValue.ts

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createLogger } from '../../../utils/logger';
+import {
+  applyTextChange,
+  createValueState,
+  reconcileValueState,
+  resolveCanUpdate,
+} from './valueState';
+import type {
+  TextFieldValueController,
+  ValueDiagnostic,
+  ValueState,
+} from './valueState';
+
+const log = createLogger('TextField');
+
+const DIAGNOSTIC_MESSAGE: Record<ValueDiagnostic, string> = {
+  'controlled-to-uncontrolled':
+    '受控输入的 value 变成了 undefined。mode 已在首次 render 锁定为受控,本次沿用上一个合法值 —— 请始终传字符串(清空用 "")。',
+  'uncontrolled-to-controlled':
+    '非受控输入后来收到了 value。mode 已在首次 render 锁定为非受控,该 value 被忽略 —— 请从一开始就同时传 value 与 onChangeText。',
+  'invalid-controlled-value':
+    '受控输入的 value 必须是字符串。已保持最后一个合法值,不会切换到非受控 mode。',
+};
+
+export type UseTextFieldValueInput = {
+  value?: unknown;
+  defaultValue?: unknown;
+  onChangeText?: ((value: string) => void) | undefined;
+};
+
+/**
+ * 把纯值状态机接到 React 上。
+ *
+ * state 放在 ref 而不是 useState:mode 与受控值必须在**本次 render 内**就正确,
+ * 不能等下一次提交 —— 否则受控组件会先渲染一帧旧值。非受控写入用一个递增 tick
+ * 触发重渲染,值本身仍以 ref 为准。
+ *
+ * 诊断只在 effect 里打:render 期打日志在 StrictMode 双调用下会重复,
+ * 且违反 render 必须纯净的约束。
+ */
+export function useTextFieldValue(
+  { value, defaultValue, onChangeText }: UseTextFieldValueInput,
+  scope: string
+): TextFieldValueController {
+  const stateRef = useRef<ValueState | null>(null);
+  if (stateRef.current === null) {
+    stateRef.current = createValueState(value, defaultValue);
+  }
+  const [, bumpTick] = useState(0);
+
+  const transition = reconcileValueState(stateRef.current, value);
+  stateRef.current = transition.state;
+  const mode = transition.state.mode;
+  const canUpdate = resolveCanUpdate(mode, onChangeText);
+
+  const diagnostic = transition.diagnostic;
+  useEffect(() => {
+    if (diagnostic) log.warn(`${scope}: ${DIAGNOSTIC_MESSAGE[diagnostic]}`);
+  }, [diagnostic, scope]);
+
+  useEffect(() => {
+    if (!canUpdate) {
+      log.warn(
+        `${scope}: 受控输入缺少 onChangeText,输入将无法生效。请补上回调,或改用非受控(不传 value)。`
+      );
+    }
+  }, [canUpdate, scope]);
+
+  const handleChangeText = useCallback(
+    (next: string) => {
+      const current = stateRef.current;
+      if (!current) return;
+      if (current.mode === 'uncontrolled') {
+        stateRef.current = applyTextChange(current, next);
+        bumpTick((tick) => tick + 1);
+        onChangeText?.(next);
+        return;
+      }
+      // 受控:内部永不写值,只把输入交给调用方。没有回调时直接 no-op ——
+      // 若照旧透传给原生,UI 会显示一个 state 里并不存在的值。
+      if (!canUpdate) return;
+      onChangeText?.(next);
+    },
+    [canUpdate, onChangeText]
+  );
+
+  return {
+    mode,
+    value: transition.value,
+    canUpdate,
+    onChangeText: handleChangeText,
+  };
+}

package/src/components/ui/TextField/valueState.ts

@@ -0,0 +1,125 @@
+/**
+ * TextField 家族的**纯值状态机** —— 无 React 依赖,可直接单测。
+ *
+ * 核心规则:**mode 在首次 render 锁定,之后永不切换**。
+ *
+ * 为什么 —— 受控 / 非受控中途互换是 React 里最难查的一类 bug:光标跳位、输入被回滚、
+ * 表单提交拿到过期值。与其在每次 render 猜测调用方意图,不如锁定一次并在偏离时报诊断。
+ *
+ * mode 判据是 `value !== undefined`,**不是** `'value' in props` 也不是
+ * `typeof value === 'string'`:前者会把 `<Input value={maybeUndefined} />` 这种
+ * 常见写法误判为受控(值一旦为 undefined 就锁死输入),后者对显式 `undefined` 与
+ * 缺省无法区分。显式 `undefined` 一律按非受控处理。
+ */
+
+export type ValueState =
+  | {
+      mode: 'controlled';
+      value: string;
+      /** controlled 下 value 短暂变成 undefined 时用来兜底的最后一个合法字符串。 */
+      lastValidControlledValue: string;
+    }
+  | {
+      mode: 'uncontrolled';
+      value: string;
+      lastValidControlledValue?: never;
+    };
+
+export type ValueDiagnostic =
+  | 'controlled-to-uncontrolled'
+  | 'uncontrolled-to-controlled'
+  | 'invalid-controlled-value';
+
+export type ValueTransition = {
+  state: ValueState;
+  value: string;
+  diagnostic?: ValueDiagnostic;
+};
+
+export type TextFieldValueController = {
+  mode: ValueState['mode'];
+  value: string;
+  /** 是否存在真正能落地的更新入口;false 时 onChangeText 是 no-op。 */
+  canUpdate: boolean;
+  onChangeText: (value: string) => void;
+};
+
+export function createValueState(
+  value: unknown,
+  defaultValue: unknown
+): ValueState {
+  if (value !== undefined) {
+    const safeValue = typeof value === 'string' ? value : '';
+    return {
+      mode: 'controlled',
+      value: safeValue,
+      lastValidControlledValue: safeValue,
+    };
+  }
+  return {
+    mode: 'uncontrolled',
+    value: typeof defaultValue === 'string' ? defaultValue : '',
+  };
+}
+
+/**
+ * 用本轮 render 的 `value` 与已锁定的 state 对账。返回新 state(不原地修改)、
+ * 本轮应当显示的值,以及偏离锁定 mode 时的诊断。
+ */
+export function reconcileValueState(
+  state: ValueState,
+  incomingValue: unknown
+): ValueTransition {
+  if (state.mode === 'controlled') {
+    if (incomingValue === undefined) {
+      // 受控组件的 value 变成 undefined:保持受控,显示最后一个合法值。
+      // 若直接透传 undefined 给 TextInput,RN 会把它当成非受控并保留用户输入 —— 静默换 mode。
+      return {
+        state,
+        value: state.lastValidControlledValue,
+        diagnostic: 'controlled-to-uncontrolled',
+      };
+    }
+    if (typeof incomingValue !== 'string') {
+      return {
+        state,
+        value: state.lastValidControlledValue,
+        diagnostic: 'invalid-controlled-value',
+      };
+    }
+    return {
+      state: {
+        mode: 'controlled',
+        value: incomingValue,
+        lastValidControlledValue: incomingValue,
+      },
+      value: incomingValue,
+    };
+  }
+  if (incomingValue !== undefined) {
+    // 非受控组件后来又传了 value:忽略它,继续用内部值,只报诊断。
+    return {
+      state,
+      value: state.value,
+      diagnostic: 'uncontrolled-to-controlled',
+    };
+  }
+  return { state, value: state.value };
+}
+
+/** 用户输入。只有非受控才写内部值;受控的值永远来自调用方。 */
+export function applyTextChange(state: ValueState, text: string): ValueState {
+  if (state.mode === 'controlled') return state;
+  return { mode: 'uncontrolled', value: text };
+}
+
+/**
+ * 非受控恒可更新(内部持值);受控只有拿到 `onChangeText` 才可更新 ——
+ * 类型层已要求受控必须带回调,这里兜住未走类型的 JS 调用方。
+ */
+export function resolveCanUpdate(
+  mode: ValueState['mode'],
+  onChangeText: ((value: string) => void) | undefined
+): boolean {
+  return mode === 'uncontrolled' || typeof onChangeText === 'function';
+}

package/src/components/ui/Textarea/Textarea.tsx

@@ -1,5 +1,7 @@
 import { forwardRef } from 'react';
-import { TextFieldBase, type TextInputRef } from '../TextField/TextFieldBase';
+import { TextFieldBase } from '../TextField/TextFieldBase';
+import { sanitizeTextFieldWrapperProps } from '../TextField/normalize';
+import type { TextFieldHandle } from '../TextField/types';
 import type { TextareaProps } from './types';
 
 /**
@@ -12,11 +14,16 @@ import type { TextareaProps } from './types';
  *
  * 实现层走 `<TextFieldBase multiline>`,本组件是薄 wrap。
  *
- * Ref:forwardRef<TextInput>,业务可调 `ref.current?.focus()`。
+ * Ref:forwardRef<TextFieldHandle>,业务只可调 `focus()` / `blur()`。
  */
-export const Textarea = forwardRef<TextInputRef, TextareaProps>(
+export const Textarea = forwardRef<TextFieldHandle, TextareaProps>(
   function Textarea(props, ref) {
-    return <TextFieldBase ref={ref} multiline {...props} />;
+    const { props: safeProps } = sanitizeTextFieldWrapperProps(
+      props as TextareaProps & Record<string, unknown>
+    );
+    return (
+      <TextFieldBase ref={ref} {...(safeProps as TextareaProps)} multiline />
+    );
   }
 );
 

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

@@ -1,2 +1,7 @@
 export { Textarea } from './Textarea';
 export type { TextareaProps } from './types';
+export type {
+  TextFieldContainerStyle,
+  TextFieldHandle,
+  TextFieldSlot,
+} from '../TextField/types';

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

@@ -1,5 +1,9 @@
-import type { ReactNode } from 'react';
-import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
+import type { TextInputProps } from 'react-native';
+import type {
+  RemovedTextInputProps,
+  TextFieldCommonProps,
+  TextFieldValueProps,
+} from '../TextField/types';
 
 /**
  * 多行文本输入框（评论 / 长备注 / 多行说明）。单行用 `<Input />`。
@@ -7,23 +11,11 @@ import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
  * 内部固定 `multiline=true`；高度在 `[minHeight, maxHeight]` 之间根据内容增长。
  * 继承除 `style` / `multiline` / `numberOfLines` 之外的 RN `TextInputProps`。
  */
-export type TextareaProps = Omit<
-  TextInputProps,
-  'style' | 'multiline' | 'numberOfLines'
-> & {
-  /** 可选的前置插槽（图标、label 等） */
-  leading?: ReactNode;
-  /** 可选的后置插槽（如字符计数器） */
-  trailing?: ReactNode;
-  /** 错误信息 —— 容器进入错误态并在下方显示。
-   *  空串 `""` / undefined 都不进 error 态(truthy 判定),与 TextFieldBase 保持一致。[L-96] */
-  error?: string;
-  /** 最小高度，默认 96（约 5 行） */
-  minHeight?: number;
-  /** 最大高度（超过后内部滚动），默认不限制 */
-  maxHeight?: number;
-  /** 容器外层样式（含 leading/trailing 整个 wrap） */
-  containerStyle?: StyleProp<ViewStyle>;
-  /** 整体禁用：editable=false + 视觉变灰；优先级高于 RN 原生 `editable` */
-  disabled?: boolean;
-};
+export type TextareaProps = Omit<TextInputProps, RemovedTextInputProps> &
+  TextFieldCommonProps &
+  TextFieldValueProps & {
+    /** 最小高度，默认 96（约 5 行） */
+    minHeight?: number;
+    /** 最大高度（超过后内部滚动），默认不限制 */
+    maxHeight?: number;
+  };

package/src/components/ui/Thumbnail/Thumbnail.tsx

@@ -1,62 +1,97 @@
-import React from 'react';
-import { Image, View } from 'react-native';
-import { useThemedStyles } from '../../../theme';
+import React, { useEffect } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { useColors, useThemedStyles } from '../../../theme';
+import { resolveImageSource } from '../../../utils/imageSource';
 import { createLogger } from '../../../utils/logger';
-import { makeStyles, RING_EXTRA_RADIUS, sizingFor } from './styles';
+import { ImageAttempt } from '../shared/ImageAttempt';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { sanitizeThumbnailImageStyle } from './normalize';
+import { makeStyles, sizingFor } from './styles';
 import type { ThumbnailProps } from './types';
 
 const log = createLogger('Thumbnail');
+const hasOwn = (value: object, key: PropertyKey): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
 
-/** 缩略图基础组件 —— 列表 / 卡片 / chat 行内通用 16:9.5 小图。
- *
- *  尺寸阶梯:sm / md(默认 113×67)/ lg,与 NewsList / NewsArea 历史一致。
- *  bg 占位 = c.surfaceContainer(图加载中 / 失败时不至于空白)。
- *  `selected` 时外层套 View 画 2pt 品牌色 ring;不选中保持纯 Image 结构。
- *
- *  用法:
- *  - 远程 URL:`<Thumbnail uri={item.coverUrl} />`
- *  - 本地资源:`<Thumbnail source={require('./fallback.png')} />`
- *  - 自定义尺寸:`<Thumbnail uri={...} size="lg" />`
- *  - 选中态:`<Thumbnail uri={...} selected />` */
-export function Thumbnail({
-  uri,
-  source,
-  size = 'md',
-  selected,
-  style,
-  resizeMode = 'cover',
-  accessibilityLabel,
-  testID,
-}: ThumbnailProps): React.JSX.Element | null {
+/**
+ * 稳定两层缩略图：outer 只管 caller layout，inner visual frame 固定尺寸并始终
+ * 保留 ring。无效 / 加载失败 source 只显示 frame placeholder，不改变布局结构。
+ */
+export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
+  const {
+    uri,
+    source,
+    size = 'md',
+    selected,
+    containerStyle,
+    imageStyle,
+    resizeMode = 'cover',
+    accessibilityLabel,
+    testID,
+  } = props;
+  const colors = useColors();
   const styles = useThemedStyles(makeStyles);
-  if (!uri && !source) {
-    // [L-18] uri/source 均未传:一次性告警,返回 null 而非空白区域。
-    // types 注释已说明二选一语义;此 warn 用于开发期快速定位漏传。
-    log.warn('Thumbnail: uri 和 source 均未提供,组件将渲染为 null');
-    return null;
-  }
   const dim = sizingFor(size);
-  const image = (
-    <Image
-      source={uri ? { uri } : (source as NonNullable<typeof source>)}
-      style={[styles.base, dim, style]}
-      resizeMode={resizeMode}
-      accessibilityLabel={accessibilityLabel}
-      accessible={!!accessibilityLabel}
-      testID={selected ? undefined : testID}
-    />
-  );
-  if (!selected) return image;
-  // ring 容器:borderRadius 比 image 大 (border + padding) 才能贴合包裹外圈
+  const hasUri = hasOwn(props, 'uri');
+  const hasSource = hasOwn(props, 'source');
+  const sourceCandidate =
+    hasUri !== hasSource
+      ? hasUri && typeof uri === 'string'
+        ? { uri: uri.trim() }
+        : source
+      : undefined;
+  const resolvedSource = resolveImageSource(sourceCandidate);
+  const sanitizedImageStyle = sanitizeThumbnailImageStyle(imageStyle);
+  const diagnostics = [
+    ...(resolvedSource === undefined ? ['source'] : []),
+    ...sanitizedImageStyle.diagnostics.map((field) =>
+      field === 'style' ? 'imageStyle' : `imageStyle.${field}`
+    ),
+  ];
+  const diagnosticKey = diagnostics.join(',');
+
+  useEffect(() => {
+    if (__DEV__ && diagnosticKey.length > 0) {
+      log.warn(`Thumbnail: 非法运行时输入(${diagnosticKey})已回退。`);
+    }
+  }, [diagnosticKey]);
+
+  const normalizedLabel =
+    typeof accessibilityLabel === 'string'
+      ? accessibilityLabel.trim()
+      : undefined;
+  const imageAccessibilityProps =
+    normalizedLabel && normalizedLabel.length > 0
+      ? {
+          accessible: true,
+          accessibilityLabel: normalizedLabel,
+          accessibilityRole: 'image' as const,
+        }
+      : A11Y_HIDDEN_PROPS;
+  const ringStyle = {
+    borderRadius: dim.borderRadius,
+    borderColor: selected ? colors.primary : 'transparent',
+  };
+
   return (
-    <View
-      style={[
-        styles.ring,
-        { borderRadius: dim.borderRadius + RING_EXTRA_RADIUS },
-      ]}
-      testID={testID}
-    >
-      {image}
+    <View style={containerStyle} testID={testID}>
+      <View style={[styles.visualFrame, dim]}>
+        {resolvedSource === undefined ? null : (
+          <ImageAttempt
+            {...imageAccessibilityProps}
+            key={resolvedSource.key}
+            source={resolvedSource.source}
+            fallback={null}
+            style={[sanitizedImageStyle.style, StyleSheet.absoluteFill]}
+            resizeMode={resizeMode}
+          />
+        )}
+        <View
+          {...A11Y_HIDDEN_PROPS}
+          pointerEvents="none"
+          style={[StyleSheet.absoluteFill, styles.ring, ringStyle]}
+        />
+      </View>
     </View>
   );
 }