@unif/react-native-design 0.19.0 → 0.21.0

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>
   );
 }

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;
 };