@unif/react-native-design 0.20.0 → 0.21.1

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

@@ -1,17 +1,15 @@
-import type { TextInputProps } from 'react-native';
+import type { InputProps } from '../Input';
 
-export type PasswordInputProps = {
+/** 密码必须受控,且所有可用 TextInput 选项都以顶层 props 提供。 */
+export type PasswordInputProps = Omit<
+  InputProps,
+  | 'value'
+  | 'defaultValue'
+  | 'onChangeText'
+  | 'secureTextEntry'
+  | 'leading'
+  | 'trailing'
+> & {
   value: string;
-  onChangeText: (v: string) => void;
-  /** 默认 "请输入密码" */
-  placeholder?: string;
-  testID?: string;
-  /** 错误信息 —— 传入时 Input 进入 error 态并在下方显示 */
-  error?: string;
-  /** 整体禁用:等价于 editable=false + 视觉变灰 */
-  disabled?: boolean;
-  /** 透传给底层 Input 的其他 RN TextInput 属性(maxLength / autoFocus 等)。
-   *  ⚠ 不要传 secureTextEntry,组件自管;传了会被组件内部覆盖。
-   *  [L-32] 类型显式 Omit<TextInputProps,'secureTextEntry'> 封堵传入歧义 */
-  inputProps?: Omit<TextInputProps, 'secureTextEntry'>;
+  onChangeText: (value: string) => void;
 };

package/src/components/ui/Pulse/PulseDot.tsx

@@ -1,21 +1,22 @@
 import React from 'react';
 import Animated from 'react-native-reanimated';
 import { r, useColors } from '../../../theme';
-import { usePulse } from './usePulse';
+import { DOT_DEFAULTS, usePulseWithDefaults } from './usePulse';
 import type { PulseDotProps } from './types';
 
 export function PulseDot({
   size = r(6),
   color,
-  from = 0.5,
   style,
   testID,
   ...opts
 }: PulseDotProps = {}): React.JSX.Element {
   const c = useColors();
   const fill = color ?? c.primary;
-  // [L-93] 只显式覆盖 from(默认 0.5 与 usePulse 的 0.6 不同),其余 opts 透传 usePulse。
-  const animatedStyle = usePulse({ from, ...opts });
+  // [L-93] 圆点的 from 默认 0.5(比 <Pulse> 的 0.6 更淡)。默认值交给共享的
+  // DOT_DEFAULTS,不再在解构里写 `from = 0.5` —— 那样 from 会先被默认值填满,
+  // 归一化层再也分不清「调用方没传」和「调用方传了 0.5」。
+  const animatedStyle = usePulseWithDefaults(opts, DOT_DEFAULTS, 'PulseDot');
   return (
     <Animated.View
       style={[

package/src/components/ui/Pulse/normalizePulseOptions.ts

@@ -0,0 +1,76 @@
+import type { PulseOptions } from './types';
+
+export type { PulseOptions };
+
+/**
+ * Pulse 参数的**唯一**归一化入口 —— 公共 hook 先跑完这里,平台 driver 只消费产物。
+ *
+ * 为什么要单独一层:此前 native / web 两份 `usePulse` 各自读原始 props 并各自解释
+ * 默认值,web 侧甚至把未校验的 `duration` 直接喂给 `setInterval`(0 或 2^31 会退化成
+ * 「每帧触发」)。归一化收口后,两端拿到的一定是同一组已验证数值。
+ *
+ * 纪律:**不做 clamp、不做取整**。非法值一律整体回退到 defaults 并记一条诊断 ——
+ * 悄悄把 `duration: 0` 夹成 `1` 会让调用方永远发现不了自己传错了。
+ */
+
+export type PulseDefaults = {
+  duration: number;
+  delay: number;
+  from: number;
+  to: number;
+};
+
+export type PulseDiagnostic = {
+  field: keyof PulseDefaults;
+  received: unknown;
+  fallback: number;
+};
+
+export type NormalizedPulseOptions = PulseDefaults & {
+  /** 两端相等 —— 没有可播的动画,driver 直接停在 `to`。 */
+  isStatic: boolean;
+  diagnostics: readonly PulseDiagnostic[];
+};
+
+// setTimeout / setInterval 内部用 int32 存时长,>= 2^31 会溢出成 0 变「每帧触发」。
+const MAX_TIMER = 2 ** 31;
+
+export function normalizePulseOptions(
+  input: PulseOptions = {},
+  defaults: PulseDefaults
+): NormalizedPulseOptions {
+  const diagnostics: PulseDiagnostic[] = [];
+  const pick = (
+    field: keyof PulseDefaults,
+    valid: (value: number) => boolean
+  ): number => {
+    const received = input[field];
+    if (received === undefined) return defaults[field];
+    if (typeof received === 'number' && valid(received)) return received;
+    diagnostics.push({ field, received, fallback: defaults[field] });
+    return defaults[field];
+  };
+  const duration = pick(
+    'duration',
+    (value) => Number.isFinite(value) && value >= 1 && value < MAX_TIMER
+  );
+  const delay = pick(
+    'delay',
+    (value) => Number.isFinite(value) && value >= 0 && value < MAX_TIMER
+  );
+  const from = pick(
+    'from',
+    (value) => Number.isFinite(value) && value >= 0 && value <= 1
+  );
+  const to = pick(
+    'to',
+    (value) => Number.isFinite(value) && value >= 0 && value <= 1
+  );
+  return { duration, delay, from, to, isStatic: from === to, diagnostics };
+}
+
+/** driver 是否应当启动循环。静态或系统开启减弱动效时都不启动。 */
+export const shouldAnimatePulse = (
+  options: NormalizedPulseOptions,
+  reducedMotion: boolean
+): boolean => !reducedMotion && !options.isStatic;

package/src/components/ui/Pulse/usePulse.ts

@@ -1,41 +1,87 @@
-import { useEffect } from 'react';
-import {
-  cancelAnimation,
-  useAnimatedStyle,
-  useSharedValue,
-  withDelay,
-  withRepeat,
-  withSequence,
-  withTiming,
-} from 'react-native-reanimated';
+import { useEffect, useMemo } from 'react';
+import { createLogger } from '../../../utils/logger';
+import { normalizePulseOptions } from './normalizePulseOptions';
+import type { PulseDefaults } from './normalizePulseOptions';
+import { usePulseDriver } from './usePulseDriver';
 import type { PulseOptions } from './types';
 
 /**
- * 在两个 opacity 值之间无限循环，返回可直接拼到 Animated.View 上的 style。
- * 走 reanimated 4 的 worklet，整个动画在 UI 线程跑、不占 JS 桥。
+ * 在两个 opacity 值之间无限循环,返回可直接拼到 Animated.View 上的 style。
+ *
+ * 这是**唯一**的公共实现:参数校验、默认值与 dev 诊断全在这里完成,平台差异只下沉到
+ * `usePulseDriver(.web).ts`。此前 native / web 各有一份 `usePulse`,两边各自读原始
+ * props、各自解释默认值,web 侧还把未校验的 duration 直接喂给 `setInterval`。
  */
-export function usePulse({
-  from = 0.6,
-  to = 1,
-  duration = 700,
-  delay = 0,
-}: PulseOptions = {}) {
-  const op = useSharedValue(from);
 
+const BASE_DEFAULTS: PulseDefaults = {
+  duration: 700,
+  delay: 0,
+  from: 0.6,
+  to: 1,
+};
+
+/** PulseDot / Skeleton 的默认值 —— 只有 from 更低,圆点 / 骨架淡到 0.5。 */
+export const DOT_DEFAULTS: PulseDefaults = {
+  duration: 700,
+  delay: 0,
+  from: 0.5,
+  to: 1,
+};
+
+// logger 在模块加载时一次性建好 —— render 期创建每次都会产生新对象。
+const pulseLog = createLogger('Pulse');
+const pulseDotLog = createLogger('PulseDot');
+const skeletonLog = createLogger('Skeleton');
+
+/** 诊断告警的固定 scope 集合。 */
+export type PulseScope = 'Pulse' | 'PulseDot' | 'Skeleton';
+
+function loggerForScope(scope: PulseScope) {
+  switch (scope) {
+    case 'Pulse':
+      return pulseLog;
+    case 'PulseDot':
+      return pulseDotLog;
+    case 'Skeleton':
+      return skeletonLog;
+  }
+}
+
+/** 内部:让 PulseDot / Skeleton 复用同一条归一化 + 诊断 + driver 链路。 */
+export function usePulseWithDefaults(
+  options: PulseOptions | undefined,
+  defaults: PulseDefaults,
+  scope: PulseScope
+) {
+  // 依赖列表**故意**拆到 primitive:options / defaults 对象每次 render 都可能是新引用
+  // (调用方常写内联字面量),直接依赖对象会让 memo 恒失效、并连带每帧重启 driver 的 effect。
+  // 这八个 primitive 就是归一化的全部输入,拆开后覆盖完整、无遗漏。
+  const normalized = useMemo(
+    () => normalizePulseOptions(options, defaults),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      options?.duration,
+      options?.delay,
+      options?.from,
+      options?.to,
+      defaults.duration,
+      defaults.delay,
+      defaults.from,
+      defaults.to,
+    ]
+  );
   useEffect(() => {
-    // from 变化时把 baseline 拉到新值，再启动循环；否则首帧会闪一下旧 baseline。
-    op.value = from;
-    const cycle = withRepeat(
-      withSequence(
-        withTiming(to, { duration }),
-        withTiming(from, { duration })
-      ),
-      -1,
-      false
-    );
-    op.value = delay > 0 ? withDelay(delay, cycle) : cycle;
-    return () => cancelAnimation(op);
-  }, [op, from, to, duration, delay]);
-
-  return useAnimatedStyle(() => ({ opacity: op.value }));
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      for (const item of normalized.diagnostics) {
+        loggerForScope(scope).warn(
+          `${item.field}=${String(item.received)} 无效,已回退为 ${item.fallback}`
+        );
+      }
+    }
+  }, [normalized.diagnostics, scope]);
+  return usePulseDriver(normalized);
+}
+
+export function usePulse(options: PulseOptions = {}) {
+  return usePulseWithDefaults(options, BASE_DEFAULTS, 'Pulse');
 }

package/src/components/ui/Pulse/usePulseDriver.ts

@@ -0,0 +1,49 @@
+import { useEffect } from 'react';
+import {
+  cancelAnimation,
+  useAnimatedStyle,
+  useSharedValue,
+  withDelay,
+  withRepeat,
+  withSequence,
+  withTiming,
+} from 'react-native-reanimated';
+import { usePrefersReducedMotion } from '../../../theme';
+import { shouldAnimatePulse } from './normalizePulseOptions';
+import type { NormalizedPulseOptions } from './normalizePulseOptions';
+
+/**
+ * native Pulse driver —— reanimated 4 worklet,整个动画在 UI 线程跑、不占 JS 桥。
+ *
+ * **只接受归一化产物**:duration / delay / from / to 都已验证过,这里不再读原始 props,
+ * 也不再解释默认值。平台差异只到这一层为止。
+ */
+export function usePulseDriver(options: NormalizedPulseOptions) {
+  const reduced = usePrefersReducedMotion();
+  const animate = shouldAnimatePulse(options, reduced);
+  const { from, to, duration, delay } = options;
+  const op = useSharedValue(animate ? from : to);
+
+  useEffect(() => {
+    if (!animate) {
+      // 静态 / 减弱动效:停在完全显示的一端(to),骨架与圆点静态呈现。
+      cancelAnimation(op);
+      op.value = to;
+      return;
+    }
+    // from 变化时把 baseline 拉到新值,再启动循环;否则首帧会闪一下旧 baseline。
+    op.value = from;
+    const cycle = withRepeat(
+      withSequence(
+        withTiming(to, { duration }),
+        withTiming(from, { duration })
+      ),
+      -1,
+      false
+    );
+    op.value = delay > 0 ? withDelay(delay, cycle) : cycle;
+    return () => cancelAnimation(op);
+  }, [op, animate, from, to, duration, delay]);
+
+  return useAnimatedStyle(() => ({ opacity: op.value }));
+}

package/src/components/ui/Pulse/usePulseDriver.web.ts

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react';
+import type { ImageStyle, TextStyle, ViewStyle } from 'react-native';
+import { usePrefersReducedMotion } from '../../../theme';
+import { shouldAnimatePulse } from './normalizePulseOptions';
+import type { NormalizedPulseOptions } from './normalizePulseOptions';
+
+/**
+ * Web Pulse driver —— RN-Web 上 reanimated 的 `useAnimatedStyle` 链路会在
+ * `_updatePropsJS` 里对 undefined 取 `Object.keys` 而抛 TypeError,pulse 卡死在初始值。
+ * 故 web 走 **CSS transition 降级**(零 rAF JS 帧):
+ *
+ * - `setInterval` 每隔 `duration` ms 只在 from / to 两档翻转 opacity
+ *   —— setState 频率从 ~60fps 降到 1 次/duration ms(参 ToastHost.web.tsx)
+ * - 补间交给浏览器 CSS transition,JS 侧零插值
+ *
+ * **只接受归一化产物**:duration 已被验证在 `[1, 2^31)`,不会出现 `setInterval(0)`
+ * 那种「每帧触发」的退化。web 端**不跑 worklet** —— 别在文档里宣称它跑。
+ */
+export function usePulseDriver(options: NormalizedPulseOptions) {
+  const reduced = usePrefersReducedMotion();
+  const animate = shouldAnimatePulse(options, reduced);
+  const { from, to, duration, delay } = options;
+  const [opacity, setOpacity] = useState(animate ? from : to);
+
+  useEffect(() => {
+    if (!animate) {
+      // 静态 / 减弱动效:停在完全显示的一端(to),与 native driver 语义一致。
+      setOpacity(to);
+      return;
+    }
+
+    setOpacity(from);
+    let timer: ReturnType<typeof setInterval> | null = null;
+    let delayTimer: ReturnType<typeof setTimeout> | null = null;
+    let current = from;
+
+    const start = () => {
+      timer = setInterval(() => {
+        current = current === from ? to : from;
+        setOpacity(current);
+      }, duration);
+    };
+
+    if (delay > 0) {
+      delayTimer = setTimeout(start, delay);
+    } else {
+      start();
+    }
+
+    // 两个 timer 都要清:delay 期间卸载时 interval 还没建立,反之亦然。
+    return () => {
+      if (delayTimer != null) clearTimeout(delayTimer);
+      if (timer != null) clearInterval(timer);
+    };
+  }, [animate, from, to, duration, delay]);
+
+  // RN-Web 把 transition 字段透传到 DOM style,实现 CSS 级平滑过渡。
+  // RN 的 style typedef 没有 transition 字段,故用交叉类型补一个窄声明 ——
+  // 比整块 `as any` 精确:仍然保留 opacity 的类型检查。
+  return {
+    opacity,
+    ...(animate
+      ? { transition: `opacity ${duration}ms ease-in-out` }
+      : undefined),
+  } as (ViewStyle | TextStyle | ImageStyle) & { transition?: string };
+}

package/src/components/ui/Radio/Radio.tsx

@@ -1,4 +1,4 @@
-import React, { useContext } from 'react';
+import React, { useContext, useEffect } from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
 import {
@@ -11,6 +11,8 @@ import {
 } from '../../../theme';
 import { createLogger } from '../../../utils/logger';
 import { childTestID } from '../../../utils/testID';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
 import { RadioContext } from './RadioContext';
 import { RadioGroup } from './RadioGroup';
 import { makeStyles } from './styles';
@@ -27,22 +29,39 @@ const _warnedCtx = new Set<string>();
 export function Radio({
   value,
   label,
+  accessibilityLabel,
   disabled,
   testID,
 }: RadioProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
   const ctx = useContext(RadioContext);
-  if (!ctx) {
-    // [L-30] 去重:同一 value 的 warn 只打一次,避免渲染阶段反复刷屏
-    const warnKey = `no-ctx:${String(value)}`;
-    if (!_warnedCtx.has(warnKey)) {
-      _warnedCtx.add(warnKey);
-      log.warn('<Radio> must be used inside <Radio.Group>');
+  const accessibleName =
+    normalizeNonBlankText(accessibilityLabel) ?? normalizeNonBlankText(label);
+  const hasMissingName = accessibleName === undefined;
+
+  useEffect(() => {
+    if (!ctx) {
+      const warnKey = `no-ctx:${String(value)}`;
+      if (!_warnedCtx.has(warnKey)) {
+        _warnedCtx.add(warnKey);
+        log.warn('<Radio> must be used inside <Radio.Group>');
+      }
+    }
+  }, [ctx, value]);
+  useEffect(() => {
+    if (hasMissingName) {
+      log.warn(
+        'Radio 需要非空的 accessibilityLabel 或可见 label，当前 action 已禁用。'
+      );
     }
+  }, [hasMissingName]);
+
+  if (!ctx) {
     return <View />;
   }
   const checked = ctx.value === value;
+  const isDisabled = disabled === true || hasMissingName;
   // [L-92] 改用 childTestID:收口 parent+id 拼接逻辑,保持空串 override 回落拼接语义
   const resolvedTestID = childTestID(ctx.groupTestID, value, testID);
 
@@ -55,22 +74,32 @@ export function Radio({
 
   return (
     <Pressable
-      onPress={() => !disabled && ctx.onChange(value)}
-      disabled={disabled}
+      accessible={!hasMissingName}
+      onPress={isDisabled ? undefined : () => ctx.onChange(value)}
+      disabled={isDisabled}
       hitSlop={hitSlopV}
-      accessibilityRole="radio"
-      accessibilityState={{ checked, disabled: !!disabled }}
-      accessibilityLabel={label}
+      accessibilityRole={hasMissingName ? undefined : 'radio'}
+      accessibilityState={
+        hasMissingName ? undefined : { checked, disabled: isDisabled }
+      }
+      accessibilityLabel={accessibleName}
       testID={resolvedTestID}
       style={({ pressed }) => [
         styles.row,
-        { opacity: disabled ? 0.5 : pressed ? pressedOpacity : 1 },
+        { opacity: isDisabled ? 0.5 : pressed ? pressedOpacity : 1 },
       ]}
     >
-      <View style={[styles.circle, checked && { borderColor: c.primary }]}>
+      <View
+        {...A11Y_HIDDEN_PROPS}
+        style={[styles.circle, checked && { borderColor: c.primary }]}
+      >
         {checked ? <View style={styles.dot} /> : null}
       </View>
-      {label ? <Text style={styles.label}>{label}</Text> : null}
+      {label ? (
+        <Text {...A11Y_HIDDEN_PROPS} style={styles.label}>
+          {label}
+        </Text>
+      ) : null}
     </Pressable>
   );
 }

package/src/components/ui/Radio/RadioGroup.tsx

@@ -1,14 +1,18 @@
-import React, { useMemo } from 'react';
+import React, { useEffect, useMemo } from 'react';
 import { View } from 'react-native';
 import { useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
 import { RadioContext } from './RadioContext';
 import { makeStyles } from './styles';
 import type { GroupProps } from './types';
 
+const log = createLogger('Radio.Group');
+
 /**
  * Radio 组 —— 单选。把若干 `<Radio>` 作为 children 放进来。
  *
- * <Radio.Group value={tier} onChange={setTier}>
+ * <Radio.Group value={tier} onChange={setTier} accessibilityLabel="客户等级">
  *   <Radio value="vip"     label="VIP 客户" />
  *   <Radio value="normal"  label="普通客户" />
  * </Radio.Group>
@@ -16,20 +20,34 @@ import type { GroupProps } from './types';
 export function RadioGroup({
   value,
   onChange,
+  accessibilityLabel,
   children,
   testID,
 }: GroupProps): React.JSX.Element {
   const styles = useThemedStyles(makeStyles);
+  const accessibleName = normalizeNonBlankText(accessibilityLabel);
+  const hasBlankLabel = accessibleName === undefined;
   // [L-80b] useMemo 稳定 context value —— 避免每次渲染都产生新对象引用,
   // 防止所有 Radio 子项因 context 变化而不必要 re-render。
   const ctx = useMemo(
     () => ({ value, onChange, groupTestID: testID }),
     [value, onChange, testID]
   );
+  useEffect(() => {
+    if (hasBlankLabel) {
+      log.warn('Radio.Group accessibilityLabel 不能为空白。');
+    }
+  }, [hasBlankLabel]);
+
   return (
     <RadioContext.Provider value={ctx}>
       {/* [L-34] accessibilityRole="radiogroup" —— SR 宣读"单选按钮组" */}
-      <View style={styles.group} testID={testID} accessibilityRole="radiogroup">
+      <View
+        style={styles.group}
+        testID={testID}
+        accessibilityRole="radiogroup"
+        accessibilityLabel={accessibleName}
+      >
         {children}
       </View>
     </RadioContext.Provider>

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

@@ -3,6 +3,18 @@ import type { ReactNode } from 'react';
 /** Radio 选项值类型 */
 export type Value = string | number;
 
+type AccessibleName =
+  | {
+      /** 可见旁标同时提供 accessible name；可显式覆盖读屏文案 */
+      label: string;
+      accessibilityLabel?: string;
+    }
+  | {
+      /** 无可见旁标时必须显式提供 accessible name */
+      label?: never;
+      accessibilityLabel: string;
+    };
+
 export type GroupContext = {
   /** 当前选中值 */
   value: Value;
@@ -17,17 +29,17 @@ export type GroupProps = {
   value: Value;
   /** 选中变化回调 */
   onChange: (value: Value) => void;
+  /** 单选组自身的读屏名称 */
+  accessibilityLabel: string;
   /** 若干个 Radio 子项 */
   children: ReactNode;
   /** E2E / 测试定位 */
   testID?: string;
 };
 
-export type RadioProps = {
+type RadioBehaviorProps = {
   /** 此项的值 */
   value: Value;
-  /** 此项右侧文字 */
-  label?: string;
   /** 禁用 */
   disabled?: boolean;
   /**
@@ -36,3 +48,5 @@ export type RadioProps = {
    */
   testID?: string;
 };
+
+export type RadioProps = RadioBehaviorProps & AccessibleName;

package/src/components/ui/Reveal/Reveal.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import Animated, { FadeIn, FadeOut } from 'react-native-reanimated';
-import { motion } from '../../../theme';
+import { motion, usePrefersReducedMotion } from '../../../theme';
 import type { RevealProps } from './types';
 
 /**
@@ -16,10 +16,12 @@ export function Reveal({
   duration = motion.base,
   testID,
 }: RevealProps): React.JSX.Element {
+  const reduced = usePrefersReducedMotion();
+
   return (
     <Animated.View
-      entering={FadeIn.duration(duration)}
-      exiting={FadeOut.duration(duration)}
+      entering={reduced ? undefined : FadeIn.duration(duration)}
+      exiting={reduced ? undefined : FadeOut.duration(duration)}
       style={style}
       testID={testID}
     >