@unif/react-native-design 0.19.0 → 0.21.0

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

@@ -3,7 +3,7 @@ import type { StyleProp, ViewStyle } from 'react-native';
 
 export type RevealProps = {
   children: ReactNode;
-  /** 容器样式 */
+  /** 唯一公开容器样式；Web 动画完成后保留 caller opacity。 */
   style?: StyleProp<ViewStyle>;
   /** 入/出场时长（毫秒，默认 motion.base = 200） */
   duration?: number;

package/src/components/ui/Reveal/webTransition.ts

@@ -0,0 +1,206 @@
+import { StyleSheet } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type WebTransitionStyle = ViewStyle & {
+  transitionProperty?: 'opacity';
+  transitionDuration?: string;
+  transitionTimingFunction?: 'ease-out';
+};
+
+type RevealWebStyleResolution = {
+  callerStyle: StyleProp<ViewStyle> | undefined;
+  targetOpacity: number;
+};
+
+type RevealWebAnimatedStyleOptions = {
+  targetOpacity: number;
+  visible: boolean;
+  animate: boolean;
+  duration: number;
+};
+
+export type RevealAnimationFrameApi = {
+  requestAnimationFrame: (callback: () => void) => number;
+  cancelAnimationFrame: (id: number) => void;
+};
+
+type RevealAnimationFrameOptions = {
+  api: RevealAnimationFrameApi | undefined;
+  isCurrent: () => boolean;
+  onVisible: () => void;
+};
+
+function isEmptyStyleInput(value: unknown): boolean {
+  if (value === undefined || value === null || value === false) return true;
+  if (!Array.isArray(value)) return false;
+  return value.every(isEmptyStyleInput);
+}
+
+function interpolateLikeReactNativeWeb(value: unknown): string {
+  // String(Symbol()) 不抛错，但 RNW 的 `${value}` 会抛错，必须使用同一 coercion。
+  return `${value}`;
+}
+
+/**
+ * RNW 会对 transform array 做深层 Object.keys / join / string coercion；
+ * StyleSheet.flatten 只做浅合并，不能证明这条后续路径安全。
+ */
+function isSafeWebTransform(transform: unknown): boolean {
+  if (transform === undefined || typeof transform === 'string') return true;
+  if (!Array.isArray(transform)) return false;
+
+  try {
+    return transform.every((operation) => {
+      if (
+        operation === null ||
+        typeof operation !== 'object' ||
+        Array.isArray(operation)
+      ) {
+        return false;
+      }
+
+      const keys = Object.keys(operation);
+      if (keys.length !== 1) return false;
+      const key = keys[0];
+      if (key === undefined) return false;
+      const value = (operation as Record<string, unknown>)[key];
+
+      if (key === 'matrix' || key === 'matrix3d') {
+        if (!Array.isArray(value)) return false;
+        interpolateLikeReactNativeWeb(value.join(','));
+      } else {
+        interpolateLikeReactNativeWeb(value);
+      }
+      return true;
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Web Reveal 只读取 caller 最终 opacity，不修改合法 caller style。
+ * flatten 或 RNW transform preprocessing 不安全时丢弃整份 hostile style。
+ */
+export function resolveRevealWebStyle(
+  style: unknown
+): RevealWebStyleResolution {
+  try {
+    if (isEmptyStyleInput(style)) {
+      return { callerStyle: undefined, targetOpacity: 1 };
+    }
+
+    const flattened = StyleSheet.flatten(
+      style as StyleProp<ViewStyle>
+    ) as unknown;
+    if (
+      flattened === undefined ||
+      flattened === null ||
+      typeof flattened !== 'object' ||
+      Array.isArray(flattened)
+    ) {
+      return { callerStyle: undefined, targetOpacity: 1 };
+    }
+
+    const flattenedStyle = flattened as ViewStyle;
+    if (!isSafeWebTransform(flattenedStyle.transform)) {
+      return { callerStyle: undefined, targetOpacity: 1 };
+    }
+
+    const opacity = flattenedStyle.opacity;
+    return {
+      callerStyle: style as StyleProp<ViewStyle>,
+      targetOpacity:
+        typeof opacity === 'number' &&
+        Number.isFinite(opacity) &&
+        opacity >= 0 &&
+        opacity <= 1
+          ? opacity
+          : 1,
+    };
+  } catch {
+    return { callerStyle: undefined, targetOpacity: 1 };
+  }
+}
+
+export function createRevealWebAnimatedStyle({
+  targetOpacity,
+  visible,
+  animate,
+  duration,
+}: RevealWebAnimatedStyleOptions): WebTransitionStyle {
+  return {
+    opacity: visible ? targetOpacity : 0,
+    ...(animate
+      ? {
+          transitionProperty: 'opacity' as const,
+          transitionDuration: `${duration}ms`,
+          transitionTimingFunction: 'ease-out' as const,
+        }
+      : {}),
+  };
+}
+
+/**
+ * 两个 RAF id 独立保存；cleanup 即使发生在任意一帧之间，也会取消已知 id。
+ * cancelled + generation 双重保护保证旧回调不能写入新一轮 Reveal。
+ */
+export function scheduleRevealAnimationFrames({
+  api,
+  isCurrent,
+  onVisible,
+}: RevealAnimationFrameOptions): () => void {
+  let firstFrameId: number | undefined;
+  let secondFrameId: number | undefined;
+  let cancelled = false;
+
+  const isActive = () => {
+    if (cancelled) return false;
+    try {
+      return isCurrent();
+    } catch {
+      return false;
+    }
+  };
+  const show = () => {
+    if (isActive()) onVisible();
+  };
+
+  if (api === undefined) {
+    show();
+    return () => {
+      cancelled = true;
+    };
+  }
+
+  try {
+    firstFrameId = api.requestAnimationFrame(() => {
+      if (!isActive()) return;
+      try {
+        secondFrameId = api.requestAnimationFrame(show);
+      } catch {
+        show();
+      }
+    });
+  } catch {
+    show();
+  }
+
+  return () => {
+    cancelled = true;
+    if (firstFrameId !== undefined) {
+      try {
+        api.cancelAnimationFrame(firstFrameId);
+      } catch {
+        // cancel 失败时仍由 cancelled / generation guard 阻止旧回调写状态。
+      }
+    }
+    if (secondFrameId !== undefined) {
+      try {
+        api.cancelAnimationFrame(secondFrameId);
+      } catch {
+        // 同上。
+      }
+    }
+  };
+}

package/src/components/ui/Search/Search.tsx

@@ -1,65 +1,134 @@
-import React, { forwardRef } from 'react';
-import { Pressable } from 'react-native-gesture-handler';
-
-import { control, fixed, r, useColors } from '../../../theme';
-import { childTestID } from '../../../utils/testID';
-import { Icon } from '../Icon';
-import { Input } from '../Input';
-import type { TextInputRef } from '../TextField/TextFieldBase';
+import React, { forwardRef, useEffect } from 'react';
+import { fixed } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { TextFieldBase } from '../TextField/TextFieldBase';
+import { normalizeSearchLayout } from '../TextField/normalize';
+import type {
+  TextFieldBaseProps,
+  TextFieldHandle,
+  TextFieldSlot,
+} from '../TextField/types';
+import { useTextFieldValue } from '../TextField/useTextFieldValue';
 import type { SearchProps } from './types';
 
+const log = createLogger('Search');
+
 /**
- * 搜索输入框 —— `<Input>` 的预设：前置搜索图标、清除按钮、
- * 高 control.md、键盘 return 键为「搜索」。
- *
- * Ref 透传到 Input 内部 TextInput，业务可调 `searchRef.current?.focus()`。
+ * 搜索输入框:值状态只在本层 controller 持有一次,下层 base 始终以受控形状渲染。
  */
-export const Search = forwardRef<TextInputRef, SearchProps>(function Search(
-  { onSubmit, placeholder = '搜索…', value, onChangeText, testID, ...rest },
-  ref
-): React.JSX.Element {
-  const c = useColors();
-  const filled = typeof value === 'string' && value.length > 0;
-  return (
-    <Input
-      ref={ref}
-      {...rest}
-      value={value}
-      onChangeText={onChangeText}
-      placeholder={placeholder}
-      // [L-81] 高度裸 36 → control.md(r(36),随设备缩放)
-      height={control.md}
-      returnKeyType="search"
-      accessibilityRole="search"
-      testID={testID}
-      onSubmitEditing={(e) => {
-        // [M-9] 改读 e.nativeEvent.text —— 不再依赖受控 value,非受控场景也能触发
-        const text = e.nativeEvent.text;
-        onSubmit?.(text);
-      }}
-      leading={<Icon name="search" size={r(18)} color={c.foregroundSubtle} />}
-      trailing={
-        filled ? (
-          <Pressable
-            onPress={() => onChangeText?.('')}
-            // [M-7] 清除按钮 icon r(14)≈14pt;Input 高 control.md≈36pt 限制垂直扩展
-            // horizontal 走 (44-14)/2=15;vertical 走 (44-control.md)/2≈4
-            hitSlop={{
-              top: Math.round((fixed.hitTarget - control.md) / 2),
-              bottom: Math.round((fixed.hitTarget - control.md) / 2),
-              left: Math.round((fixed.hitTarget - r(14)) / 2),
-              right: Math.round((fixed.hitTarget - r(14)) / 2),
-            }}
-            accessibilityRole="button"
-            accessibilityLabel="清除"
-            testID={childTestID(testID, 'clear')}
-          >
-            <Icon name="close" size={r(14)} color={c.foregroundSubtle} />
-          </Pressable>
-        ) : null
+export const Search = forwardRef<TextFieldHandle, SearchProps>(
+  function Search(props, ref): React.JSX.Element {
+    const {
+      value: rawValue,
+      defaultValue: rawDefaultValue,
+      onChangeText: rawOnChangeText,
+      onSubmit: rawOnSubmit,
+      onSubmitEditing: rawOnSubmitEditing,
+      disabled: rawDisabled,
+      editable: rawEditable,
+      placeholder: rawPlaceholder,
+      leading: _leading,
+      trailing: _trailing,
+      height: _height,
+      returnKeyType: _returnKeyType,
+      accessibilityRole: _accessibilityRole,
+      role: _role,
+      clearButtonMode: _clearButtonMode,
+      enterKeyHint: _enterKeyHint,
+      ...rest
+    } = props as SearchProps & Record<string, unknown>;
+    const value = rawValue;
+    const defaultValue = rawDefaultValue;
+    const onChangeText =
+      typeof rawOnChangeText === 'function'
+        ? (rawOnChangeText as (next: string) => void)
+        : undefined;
+    const onSubmit =
+      typeof rawOnSubmit === 'function'
+        ? (rawOnSubmit as (next: string) => void)
+        : undefined;
+    const onSubmitEditing =
+      typeof rawOnSubmitEditing === 'function'
+        ? (rawOnSubmitEditing as NonNullable<SearchProps['onSubmitEditing']>)
+        : undefined;
+    const disabled = rawDisabled === true;
+    const editable = rawEditable === false ? false : undefined;
+    const placeholder =
+      typeof rawPlaceholder === 'string' ? rawPlaceholder : '搜索…';
+    const allowedNativeProps = rest as Omit<
+      TextFieldBaseProps,
+      | 'value'
+      | 'defaultValue'
+      | 'onChangeText'
+      | 'multiline'
+      | 'leading'
+      | 'trailing'
+      | 'height'
+      | 'searchLayout'
+      | 'returnKeyType'
+      | 'accessibilityRole'
+      | 'onSubmitEditing'
+      | 'disabled'
+      | 'editable'
+      | 'placeholder'
+    >;
+    const removedNativeAliasKey = Object.entries({
+      leading: _leading,
+      trailing: _trailing,
+      height: _height,
+      returnKeyType: _returnKeyType,
+      accessibilityRole: _accessibilityRole,
+      role: _role,
+      clearButtonMode: _clearButtonMode,
+      enterKeyHint: _enterKeyHint,
+    })
+      .filter(([, entry]) => entry !== undefined)
+      .map(([name]) => name)
+      .join(',');
+    useEffect(() => {
+      if (removedNativeAliasKey.length > 0) {
+        log.warn(`已忽略 Search 自管 props(${removedNativeAliasKey})。`);
       }
-    />
-  );
-});
+    }, [removedNativeAliasKey]);
+    const controller = useTextFieldValue(
+      { value, defaultValue, onChangeText },
+      'Search'
+    );
+    const searchLayout = normalizeSearchLayout(fixed.hitTarget, 36);
+    const effectiveEditable = disabled !== true && editable !== false;
+    const trailing: TextFieldSlot | undefined =
+      controller.value.length > 0 && effectiveEditable && controller.canUpdate
+        ? {
+            kind: 'action',
+            icon: 'close',
+            onPress: () => controller.onChangeText(''),
+            accessibilityLabel: '清除搜索内容',
+          }
+        : undefined;
+
+    return (
+      <TextFieldBase
+        ref={ref}
+        {...allowedNativeProps}
+        multiline={false}
+        value={controller.value}
+        onChangeText={controller.onChangeText}
+        disabled={disabled}
+        editable={editable}
+        placeholder={placeholder}
+        height={fixed.hitTarget}
+        searchLayout={searchLayout}
+        returnKeyType="search"
+        accessibilityRole="search"
+        onSubmitEditing={(event) => {
+          onSubmitEditing?.(event);
+          onSubmit?.(controller.value);
+        }}
+        leading={{ kind: 'icon', icon: 'search', size: 18 }}
+        trailing={trailing}
+      />
+    );
+  }
+);
 
 Search.displayName = 'Search';

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

@@ -1,14 +1,35 @@
 import type { TextInputProps } from 'react-native';
+import type { InputProps } from '../Input';
 
-// [L-36] Omit 扩 'multiline'/'numberOfLines' —— 搜索框固定单行,这两属性无意义
-export type SearchProps = Omit<
-  TextInputProps,
-  'style' | 'multiline' | 'numberOfLines'
+type SearchBaseProps = Omit<
+  InputProps,
+  | 'value'
+  | 'defaultValue'
+  | 'onChangeText'
+  | 'leading'
+  | 'trailing'
+  | 'height'
+  | 'returnKeyType'
+  | 'accessibilityRole'
+  | 'role'
+  | 'onSubmitEditing'
+  | 'clearButtonMode'
+  | 'enterKeyHint'
 > & {
-  /** 提交回调（按下 return 键时触发） */
+  onSubmitEditing?: TextInputProps['onSubmitEditing'];
   onSubmit?: (value: string) => void;
-  /** 覆盖 placeholder（默认：搜索…） */
-  placeholder?: string;
-  /** E2E / 测试定位 */
-  testID?: string;
 };
+
+export type SearchProps = SearchBaseProps &
+  (
+    | {
+        value: string;
+        onChangeText: (value: string) => void;
+        defaultValue?: never;
+      }
+    | {
+        value?: never;
+        defaultValue?: string;
+        onChangeText?: (value: string) => void;
+      }
+  );

package/src/components/ui/Segmented/Segmented.tsx

@@ -1,7 +1,13 @@
 import React, { useMemo } from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { fw, useTheme, useThemedStyles } from '../../../theme';
+import {
+  fw,
+  scaleFontMetric,
+  useFontScale,
+  useTheme,
+  useThemedStyles,
+} from '../../../theme';
 import { childTestID } from '../../../utils/testID';
 import { makeStyles, sizingFor } from './styles';
 import type { SegmentedProps } from './types';
@@ -24,7 +30,9 @@ export function Segmented({
 }: SegmentedProps): React.JSX.Element {
   const { colors: c, scheme, shadow } = useTheme();
   const styles = useThemedStyles(makeStyles);
+  const fontScale = useFontScale();
   const sizing = useMemo(() => sizingFor(size), [size]);
+  const textSize = scaleFontMetric(sizing.fs, fontScale);
   const activeBg = scheme === 'dark' ? c.surfaceContainerHighest : c.surface;
   const activeShadow = scheme === 'dark' ? null : shadow.subtle;
 
@@ -55,7 +63,7 @@ export function Segmented({
           >
             <Text
               style={{
-                fontSize: sizing.fs,
+                fontSize: textSize,
                 color: on ? c.foreground : c.foregroundSubtle,
                 fontWeight: on ? fw.semi : fw.medium,
               }}

package/src/components/ui/Skeleton/Skeleton.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import Animated from 'react-native-reanimated';
-import { usePulse } from '../Pulse';
+import { DOT_DEFAULTS, usePulseWithDefaults } from '../Pulse/usePulse';
 import { r, useColors } from '../../../theme';
 import type { SkeletonProps } from './types';
 
@@ -13,9 +13,9 @@ import type { SkeletonProps } from './types';
  * <Skeleton shape="circle" size={40} />        // 头像占位
  * ```
  *
- * `usePulse({ from: 0.5 })` 每实例独立脉冲 —— native 端走 Reanimated 4 worklet,
- * web 端走 CSS transition + setInterval(零 rAF JS 帧),opacity 在 0.5~1 循环。
- * 区别于沿 X 横扫高光的流式 shimmer。 */
+ * 每实例独立脉冲(默认 `from: 0.5`)—— native 端走 Reanimated 4 worklet,web 端走
+ * CSS transition + setInterval(零 rAF JS 帧),opacity 在 0.5~1 循环。系统开启
+ * 减弱动效时静止在 `to`(完全显示)。区别于沿 X 横扫高光的流式 shimmer。 */
 export function Skeleton({
   shape = 'rect',
   width,
@@ -26,7 +26,11 @@ export function Skeleton({
   testID,
 }: SkeletonProps): React.JSX.Element {
   const c = useColors();
-  const animatedStyle = usePulse({ from: 0.5 });
+  const animatedStyle = usePulseWithDefaults(
+    undefined,
+    DOT_DEFAULTS,
+    'Skeleton'
+  );
 
   // 按形状推默认尺寸 + 圆角;caller 显式传 width / height / radius 时 override
   const dim = (() => {

package/src/components/ui/Spinner/Spinner.tsx

@@ -1,4 +1,5 @@
 import { useEffect } from 'react';
+import { View } from 'react-native';
 import Animated, {
   cancelAnimation,
   Easing,
@@ -9,16 +10,17 @@ import Animated, {
   withTiming,
 } from 'react-native-reanimated';
 import { r, useColors } from '../../../theme';
-import { sanitizeSpinnerProps } from './shared';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { sanitizeSpinnerProps, SPINNER_CENTER_STYLE } from './shared';
 import type { SpinnerProps } from './types';
 
 export function Spinner({
   size = r(18),
   color,
   thickness = r(2),
-  style,
+  style: outerStyle,
   testID,
-}: SpinnerProps) {
+}: SpinnerProps): React.JSX.Element {
   const c = useColors();
   const angle = useSharedValue(0);
   const stroke = color ?? c.primary;
@@ -47,22 +49,28 @@ export function Spinner({
   }));
 
   return (
-    <Animated.View
+    <View
       style={[
-        {
-          width: safeSize,
-          height: safeSize,
-          borderRadius: safeSize / 2,
-          borderWidth: safeThickness,
-          borderColor: c.outline,
-          borderTopColor: stroke,
-        },
-        animatedStyle,
-        style,
+        { width: safeSize, height: safeSize },
+        outerStyle,
+        SPINNER_CENTER_STYLE,
       ]}
       testID={testID}
-      accessibilityElementsHidden
-      importantForAccessibility="no-hide-descendants"
-    />
+      {...A11Y_HIDDEN_PROPS}
+    >
+      <Animated.View
+        style={[
+          {
+            width: safeSize,
+            height: safeSize,
+            borderRadius: safeSize / 2,
+            borderWidth: safeThickness,
+            borderColor: c.outline,
+            borderTopColor: stroke,
+          },
+          animatedStyle,
+        ]}
+      />
+    </View>
   );
 }

package/src/components/ui/Spinner/Spinner.web.tsx

@@ -1,7 +1,8 @@
 import React, { useEffect, useRef } from 'react';
 import { View } from 'react-native';
 import { r, useColors } from '../../../theme';
-import { sanitizeSpinnerProps } from './shared';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { sanitizeSpinnerProps, SPINNER_CENTER_STYLE } from './shared';
 import type { SpinnerProps } from './types';
 
 // React-Native-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle 链路在
@@ -34,13 +35,11 @@ export function Spinner({
   size = r(18),
   color,
   thickness = r(2),
-  style,
+  style: outerStyle,
   testID,
 }: SpinnerProps): React.JSX.Element {
   const c = useColors();
-  // ref 用 any —— RN View ref 在 web bundle 实际拿到 HTMLDivElement,
-  // RN 端拿到 View 实例,统一 any 兼容两端。
-
+  // tsconfig 不带 DOM lib；Web View ref 实际拿到带 style 的 HTMLElement。
   const ref = useRef<any>(null);
   const stroke = color ?? c.primary;
   const { safeSize, safeThickness } = sanitizeSpinnerProps(size, thickness);
@@ -59,21 +58,27 @@ export function Spinner({
 
   return (
     <View
-      ref={ref}
       style={[
-        {
-          width: safeSize,
-          height: safeSize,
-          borderRadius: safeSize / 2,
-          borderWidth: safeThickness,
-          borderColor: c.outline,
-          borderTopColor: stroke,
-        },
-        style,
+        { width: safeSize, height: safeSize },
+        outerStyle,
+        SPINNER_CENTER_STYLE,
       ]}
       testID={testID}
-      accessibilityElementsHidden
-      importantForAccessibility="no-hide-descendants"
-    />
+      {...A11Y_HIDDEN_PROPS}
+    >
+      <View
+        ref={ref}
+        style={[
+          {
+            width: safeSize,
+            height: safeSize,
+            borderRadius: safeSize / 2,
+            borderWidth: safeThickness,
+            borderColor: c.outline,
+            borderTopColor: stroke,
+          },
+        ]}
+      />
+    </View>
   );
 }

package/src/components/ui/Spinner/shared.ts

@@ -1,3 +1,4 @@
+import type { ViewStyle } from 'react-native';
 import { createLogger } from '../../../utils/logger';
 
 const log = createLogger('Spinner');
@@ -11,6 +12,12 @@ const log = createLogger('Spinner');
 
 const warnedKeys = new Set<string>();
 
+/** caller 的 alignItems / justifyContent 不能改变固定视觉环的居中位置。 */
+export const SPINNER_CENTER_STYLE = {
+  alignItems: 'center',
+  justifyContent: 'center',
+} as const satisfies ViewStyle;
+
 function warnOnce(key: string, msg: string) {
   if (warnedKeys.has(key)) return;
   warnedKeys.add(key);

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

@@ -7,7 +7,7 @@ export type SpinnerProps = {
   color?: string;
   /** 描边宽度，默认 2 */
   thickness?: number;
-  /** 额外样式 */
+  /** 外层 layout 样式；width/height 可扩容，transform 不会覆盖内层旋转。 */
   style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;