@unif/react-native-design 0.19.0 → 0.21.0

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

@@ -0,0 +1,280 @@
+import { StyleSheet } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { fixed } from '../../../theme';
+import { ICONS, type IconName } from '../../../icons';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+import type {
+  SearchFieldLayout,
+  TextFieldContainerStyle,
+  TextFieldSlot,
+} from './types';
+
+/**
+ * TextField 家族的**纯布局归一化** —— 无 React 依赖,可直接单测。
+ *
+ * 纪律与 Pulse 一致:非法值**整体回退默认值并记诊断**,不做 clamp、不做取整。
+ * 悄悄把 `height: 20` 夹成 44 会让调用方永远发现不了自己传了一个碰不到的输入框。
+ */
+
+/** slot 图标的默认与合法上界。18 是 body 字号下视觉平衡的取值;>32 会撑破 44pt frame。 */
+const DEFAULT_SLOT_ICON_SIZE = 18;
+const MAX_SLOT_ICON_SIZE = 32;
+/** Textarea 默认最小高度(约 5 行)。 */
+const DEFAULT_TEXTAREA_MIN_HEIGHT = 96;
+const DEFAULT_SEARCH_VISIBLE_HEIGHT = 36;
+
+/** 这六个字段会破坏 TextField 自持的最小命中框,一律从 containerStyle 剥离。 */
+const RESERVED_CONTAINER_KEYS = [
+  'height',
+  'minHeight',
+  'maxHeight',
+  'minWidth',
+  'maxWidth',
+  'overflow',
+] as const;
+
+const isFiniteAtLeast = (value: unknown, min: number): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= min;
+
+const isFiniteWithin = (
+  value: unknown,
+  min: number,
+  max: number
+): value is number =>
+  typeof value === 'number' &&
+  Number.isFinite(value) &&
+  value >= min &&
+  value <= max;
+
+export type NormalizedNumber = {
+  value: number;
+  diagnostics: readonly string[];
+};
+
+/** 单行高度 —— 不得低于 `fixed.hitTarget`(44pt),否则整行都碰不满一个手指。 */
+export function normalizeInputHeight(value: unknown): NormalizedNumber {
+  return isFiniteAtLeast(value, fixed.hitTarget)
+    ? { value, diagnostics: [] }
+    : { value: fixed.hitTarget, diagnostics: ['height'] };
+}
+
+export type NormalizedTextareaHeights = {
+  minHeight: number;
+  maxHeight: number | undefined;
+  diagnostics: readonly string[];
+};
+
+/** 多行高度 —— `maxHeight` 只有在有限且不小于归一化后的 `minHeight` 时才保留。 */
+export function normalizeTextareaHeights(
+  minHeight: unknown,
+  maxHeight: unknown
+): NormalizedTextareaHeights {
+  const diagnostics: string[] = [];
+  let safeMin: number;
+  if (minHeight === undefined) {
+    safeMin = DEFAULT_TEXTAREA_MIN_HEIGHT;
+  } else if (isFiniteAtLeast(minHeight, fixed.hitTarget)) {
+    safeMin = minHeight;
+  } else {
+    safeMin = DEFAULT_TEXTAREA_MIN_HEIGHT;
+    diagnostics.push('minHeight');
+  }
+  if (maxHeight === undefined) {
+    return { minHeight: safeMin, maxHeight: undefined, diagnostics };
+  }
+  // 注意用**归一化后**的 min 比较:min 被回退时 max 必须跟着重新判定,
+  // 否则会留下一个比实际 min 还小的 max,直接把内容压没。
+  if (isFiniteAtLeast(maxHeight, safeMin)) {
+    return { minHeight: safeMin, maxHeight, diagnostics };
+  }
+  diagnostics.push('maxHeight');
+  return { minHeight: safeMin, maxHeight: undefined, diagnostics };
+}
+
+/** slot 图标尺寸 —— 只接受有限的 `[1, 32]`。 */
+export function normalizeSlotIconSize(value: unknown): NormalizedNumber {
+  return isFiniteWithin(value, 1, MAX_SLOT_ICON_SIZE)
+    ? { value, diagnostics: [] }
+    : { value: DEFAULT_SLOT_ICON_SIZE, diagnostics: ['slot.size'] };
+}
+
+export type NormalizedTextFieldSlot = {
+  slot: TextFieldSlot | undefined;
+  diagnostics: readonly string[];
+};
+
+function isIconName(value: unknown): value is IconName {
+  return (
+    typeof value === 'string' &&
+    Object.prototype.hasOwnProperty.call(ICONS, value)
+  );
+}
+
+/** 未类型化 JS 必须完整匹配一个受支持分支，不能靠 discriminant 后 cast 绕过校验。 */
+export function normalizeTextFieldSlot(slot: unknown): NormalizedTextFieldSlot {
+  if (slot === undefined) {
+    return { slot: undefined, diagnostics: [] };
+  }
+  if (typeof slot !== 'object' || slot === null) {
+    return { slot: undefined, diagnostics: ['slot'] };
+  }
+  const candidate = slot as Record<string, unknown>;
+  switch (candidate.kind) {
+    case 'icon': {
+      const size =
+        typeof candidate.size === 'number' && Number.isFinite(candidate.size)
+          ? candidate.size
+          : undefined;
+      const color =
+        typeof candidate.color === 'string' ? candidate.color : undefined;
+      const hasValidSize = candidate.size === undefined || size !== undefined;
+      const hasValidColor =
+        candidate.color === undefined || color !== undefined;
+      if (!isIconName(candidate.icon) || !hasValidSize || !hasValidColor) {
+        return { slot: undefined, diagnostics: ['slot.icon'] };
+      }
+      return {
+        slot: {
+          kind: 'icon',
+          icon: candidate.icon,
+          ...(size !== undefined && { size }),
+          ...(color !== undefined && { color }),
+        },
+        diagnostics: [],
+      };
+    }
+    case 'text':
+      if (
+        typeof candidate.value !== 'string' &&
+        typeof candidate.value !== 'number'
+      ) {
+        return { slot: undefined, diagnostics: ['slot.text'] };
+      }
+      return {
+        slot: { kind: 'text', value: candidate.value },
+        diagnostics: [],
+      };
+    case 'action': {
+      const accessibilityLabel = normalizeNonBlankText(
+        candidate.accessibilityLabel
+      );
+      const hasValidDisabled =
+        candidate.disabled === undefined ||
+        typeof candidate.disabled === 'boolean';
+      const slotDisabled =
+        typeof candidate.disabled === 'boolean'
+          ? candidate.disabled
+          : undefined;
+      if (
+        !isIconName(candidate.icon) ||
+        typeof candidate.onPress !== 'function' ||
+        accessibilityLabel === undefined ||
+        !hasValidDisabled
+      ) {
+        return { slot: undefined, diagnostics: ['slot.action'] };
+      }
+      return {
+        slot: {
+          kind: 'action',
+          icon: candidate.icon,
+          onPress: candidate.onPress as () => void,
+          accessibilityLabel,
+          ...(slotDisabled !== undefined && { disabled: slotDisabled }),
+        },
+        diagnostics: [],
+      };
+    }
+    default:
+      return { slot: undefined, diagnostics: ['slot.kind'] };
+  }
+}
+
+export type NormalizedSearchLayout = SearchFieldLayout & {
+  diagnostics: readonly string[];
+};
+
+/** 搜索框的可见面可为 36pt,但承载输入/操作的实际行永远不得小于 44pt。 */
+export function normalizeSearchLayout(
+  interactiveHeight: unknown,
+  visibleHeight: unknown
+): NormalizedSearchLayout {
+  const diagnostics: string[] = [];
+  const safeInteractive = isFiniteAtLeast(interactiveHeight, fixed.hitTarget)
+    ? interactiveHeight
+    : fixed.hitTarget;
+  if (safeInteractive !== interactiveHeight) {
+    diagnostics.push('interactiveHeight');
+  }
+  const safeVisible =
+    typeof visibleHeight === 'number' &&
+    Number.isFinite(visibleHeight) &&
+    visibleHeight > 0 &&
+    visibleHeight <= safeInteractive
+      ? visibleHeight
+      : DEFAULT_SEARCH_VISIBLE_HEIGHT;
+  if (safeVisible !== visibleHeight) {
+    diagnostics.push('visibleHeight');
+  }
+  return {
+    interactiveHeight: safeInteractive,
+    visibleHeight: safeVisible,
+    verticalInset: (safeInteractive - safeVisible) / 2,
+    diagnostics,
+  };
+}
+
+export type SanitizedContainerStyle = {
+  style: TextFieldContainerStyle;
+  diagnostics: readonly string[];
+};
+
+export type SanitizedTextFieldWrapperProps = {
+  props: Record<string, unknown>;
+  diagnostics: readonly string[];
+};
+
+/**
+ * 公开 Input / Textarea 不允许未类型化 JS 覆盖内部 layout 开关。
+ *
+ * 返回新对象而不是 delete 原 props，既不改变调用方对象，也让 wrapper 能在安全 spread
+ * 后由可信边界写入自己的 `multiline`。
+ */
+export function sanitizeTextFieldWrapperProps(
+  props: Record<string, unknown>
+): SanitizedTextFieldWrapperProps {
+  const { multiline, searchLayout, ...safeProps } = props;
+  const diagnostics: string[] = [];
+  if (multiline !== undefined) {
+    diagnostics.push('multiline');
+  }
+  if (searchLayout !== undefined) {
+    diagnostics.push('searchLayout');
+  }
+  return { props: safeProps, diagnostics };
+}
+
+/**
+ * 剥掉 containerStyle 里会覆盖最小 frame 的六个字段。
+ *
+ * 先 `StyleSheet.flatten` 再解构到新对象 —— 绝不原地修改调用方对象或已注册的
+ * StyleSheet 条目(那会污染同一 sheet 的其他使用者)。
+ */
+export function sanitizeTextFieldContainerStyle(
+  style: StyleProp<ViewStyle> | undefined
+): SanitizedContainerStyle {
+  const flattened = (StyleSheet.flatten(style) ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const reserved: readonly string[] = RESERVED_CONTAINER_KEYS;
+  const sanitized: Record<string, unknown> = {};
+  const diagnostics: string[] = [];
+  for (const [key, entry] of Object.entries(flattened)) {
+    if (reserved.includes(key)) {
+      diagnostics.push(key);
+      continue;
+    }
+    sanitized[key] = entry;
+  }
+  return { style: sanitized as TextFieldContainerStyle, diagnostics };
+}

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