@unif/react-native-design 0.31.3 → 0.32.0

package/src/components/ui/TextField/TextFieldBase.tsx

@@ -7,7 +7,7 @@ import React, {
 } from 'react';
 import { Platform, Text, TextInput, View } from 'react-native';
 import type { TextInputProps } from 'react-native';
-import { fixed, space, useColors, useThemedStyles } from '../../../theme';
+import { fixed, useColors, useThemedStyles } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
 import { createLogger } from '../../../utils/logger';
 import {
@@ -20,6 +20,7 @@ import { TextFieldSlot } from './TextFieldSlot';
 import type { TextFieldBaseProps, TextFieldHandle } from './types';
 import { useErrorAnnouncement } from './useErrorAnnouncement';
 import { useTextFieldValue } from './useTextFieldValue';
+import { useMultilineLayout } from './useMultilineLayout';
 
 const log = createLogger('TextField');
 
@@ -49,6 +50,9 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
       placeholderTextColor: callerPlaceholder,
       onFocus,
       onBlur,
+      onContentSizeChange,
+      onLayout,
+      scrollEnabled,
       testID,
       style: _style,
       numberOfLines: _numberOfLines,
@@ -94,6 +98,15 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
       minHeight,
       maxHeight
     );
+    const multilineLayout = useMultilineLayout({
+      enabled: multiline,
+      value: controller.value,
+      minHeight: normalizedTextareaHeights.minHeight,
+      maxHeight: normalizedTextareaHeights.maxHeight,
+      fontSize: styles.input.fontSize,
+      placeholder: allowedNativeProps.placeholder as string | undefined,
+      inputRef: nativeRef,
+    });
     const sanitizedContainer = sanitizeTextFieldContainerStyle(containerStyle);
     const effectiveEditable = disabled !== true && editable !== false;
     const mergedAccessibilityState = {
@@ -193,6 +206,15 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
             onChangeText={controller.onChangeText}
             editable={effectiveEditable}
             multiline={multiline}
+            onContentSizeChange={onContentSizeChange}
+            onLayout={(event) => {
+              if (multiline) multilineLayout.onLayout?.(event);
+              onLayout?.(event);
+            }}
+            scrollEnabled={
+              scrollEnabled ??
+              (multiline ? multilineLayout.scrollEnabled : undefined)
+            }
             onFocus={(event) => {
               setFocused(true);
               onFocus?.(event);
@@ -204,9 +226,11 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
             style={[
               styles.input,
               multiline && styles.inputMultiline,
-              multiline && {
-                minHeight: Math.max(0, normalizedHeight - space[4] * 2),
-              },
+              multiline &&
+                (multilineLayout.scrollEnabled
+                  ? styles.inputScrolling
+                  : styles.inputClipped),
+              multiline && multilineLayout.inputStyle,
               searchLayout !== undefined && {
                 minHeight: searchLayout.interactiveHeight,
               },

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

@@ -0,0 +1,6 @@
+import { space } from '../../../theme';
+
+export const TEXT_FIELD_BORDER_WIDTH = 1;
+export const TEXTAREA_VERTICAL_PADDING = space[4];
+export const TEXTAREA_VERTICAL_INSET =
+  2 * (TEXTAREA_VERTICAL_PADDING + TEXT_FIELD_BORDER_WIDTH);

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

@@ -1,6 +1,10 @@
 import { StyleSheet } from 'react-native';
 import { fw, radius, space, type as t } from '../../../theme';
 import type { ColorTokens } from '../../../theme';
+import {
+  TEXTAREA_VERTICAL_PADDING,
+  TEXT_FIELD_BORDER_WIDTH,
+} from './constants';
 
 /** TextField primitive styles —— Input + Textarea 共享。 */
 export const makeStyles = (c: ColorTokens) =>
@@ -11,10 +15,10 @@ export const makeStyles = (c: ColorTokens) =>
       gap: space[3],
       paddingHorizontal: space[5],
       borderRadius: radius.md,
-      borderWidth: 1,
+      borderWidth: TEXT_FIELD_BORDER_WIDTH,
     },
     wrapMultiline: {
-      paddingVertical: space[4],
+      paddingVertical: TEXTAREA_VERTICAL_PADDING,
       alignItems: 'flex-start',
     },
     /** Search 的可见底色/边框绝不承载命中区域。 */
@@ -59,6 +63,8 @@ export const makeStyles = (c: ColorTokens) =>
     inputMultiline: {
       textAlignVertical: 'top' as const,
     },
+    inputScrolling: { overflow: 'scroll' },
+    inputClipped: { overflow: 'hidden' },
     slotDisplay: {
       alignItems: 'center',
       justifyContent: 'center',

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

@@ -1,4 +1,11 @@
-import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
+import type { ComponentRef, RefObject } from 'react';
+import type { TextInput } from 'react-native';
+import type {
+  StyleProp,
+  TextInputProps,
+  TextStyle,
+  ViewStyle,
+} from 'react-native';
 import type { IconName } from '../Icon';
 
 /**
@@ -7,18 +14,18 @@ import type { IconName } from '../Icon';
  * `defaultValue?: never` 让「同时传 value 和 defaultValue」在类型层就报错 ——
  * 那是最常见的受控/非受控混用写法,运行时表现为「defaultValue 被静默忽略」。
  */
-export type ControlledTextValueProps = {
+export interface ControlledTextValueProps {
   value: string;
   onChangeText: (value: string) => void;
   defaultValue?: never;
-};
+}
 
 /** 非受控:内部持值,`defaultValue` 只在首次 render 读一次。 */
-export type UncontrolledTextValueProps = {
+export interface UncontrolledTextValueProps {
   value?: never;
   defaultValue?: string;
   onChangeText?: (value: string) => void;
-};
+}
 
 /** internal —— 由 InputProps / TextareaProps / SearchProps 组合进公共类型。 */
 export type TextFieldValueProps =
@@ -31,10 +38,10 @@ export type TextFieldValueProps =
  * 为什么不暴露原生 TextInput —— `clear()` 会绕过值状态机(受控下把 UI 清空但调用方
  * state 不变),`setNativeProps()` 能直接改任意原生属性,两者都会让公共契约失效。
  */
-export type TextFieldHandle = {
+export interface TextFieldHandle {
   focus: () => void;
   blur: () => void;
-};
+}
 
 /**
  * 左右 slot 的可验证配置。**不接受任意 ReactNode** ——
@@ -67,14 +74,14 @@ export type TextFieldContainerStyle = Omit<
 >;
 
 /** internal:Search 把真实交互行与仅作视觉的 surface 明确分层。 */
-export type SearchFieldLayout = {
+export interface SearchFieldLayout {
   interactiveHeight: number;
   visibleHeight: number;
   verticalInset: number;
-};
+}
 
 /** TextField 家族共享的非值 props(内部)。 */
-export type TextFieldCommonProps = {
+export interface TextFieldCommonProps {
   /** 左侧 slot —— 图标 / 文本 / 带 handler 与名称的操作 */
   leading?: TextFieldSlot;
   /** 右侧 slot —— 图标 / 文本 / 带 handler 与名称的操作 */
@@ -85,7 +92,7 @@ export type TextFieldCommonProps = {
   disabled?: boolean;
   /** 外层容器样式;不接受会破坏最小 frame 的尺寸字段 */
   containerStyle?: StyleProp<TextFieldContainerStyle>;
-};
+}
 
 /**
  * 这些原生 TextInput props 从公共类型删除:
@@ -127,3 +134,26 @@ export type TextFieldBaseProps = Omit<TextInputProps, RemovedTextInputProps> &
     /** internal:Search 的 44pt interactive row + 36pt decorative surface。 */
     searchLayout?: SearchFieldLayout;
   };
+
+export interface MultilineLayoutInput {
+  enabled: boolean;
+  value: string;
+  minHeight: number;
+  maxHeight: number | undefined;
+  fontSize: number | undefined;
+  placeholder: string | undefined;
+  inputRef: RefObject<ComponentRef<typeof TextInput> | null>;
+}
+
+export interface MultilineLayout {
+  inputStyle: Pick<TextStyle, 'height' | 'minHeight' | 'maxHeight'>;
+  scrollEnabled: boolean;
+  onLayout?: TextInputProps['onLayout'];
+}
+
+/** RN Web 的公开 host ref 仅在平台实现内使用这两个 DOM 测量属性。 */
+export interface WebTextInputMeasurement {
+  scrollHeight: number;
+  scrollTop: number;
+  style: { height: string; minHeight: string };
+}

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

@@ -0,0 +1,20 @@
+import { TEXTAREA_VERTICAL_INSET } from './constants';
+import type { MultilineLayout, MultilineLayoutInput } from './types';
+
+/** 原生 Yoga 直接测量文本；固定 height 会阻断 iOS Fabric 的后续内容尺寸通知。 */
+export function useMultilineLayout({
+  minHeight,
+  maxHeight,
+}: MultilineLayoutInput): MultilineLayout {
+  return {
+    inputStyle: {
+      minHeight: Math.max(0, minHeight - TEXTAREA_VERTICAL_INSET),
+      maxHeight:
+        maxHeight === undefined
+          ? undefined
+          : Math.max(0, maxHeight - TEXTAREA_VERTICAL_INSET),
+    },
+    // 原生仅在内容溢出时滚动；min=max 时也不等待不会再变化的框高事件。
+    scrollEnabled: true,
+  };
+}

package/src/components/ui/TextField/useMultilineLayout.web.ts

@@ -0,0 +1,59 @@
+import { useCallback, useLayoutEffect, useState } from 'react';
+import { TEXTAREA_VERTICAL_INSET } from './constants';
+import type {
+  MultilineLayout,
+  MultilineLayoutInput,
+  WebTextInputMeasurement,
+} from './types';
+
+/** RNW 的 contentSize 使用 scrollHeight，固定高度会阻止缩短，须临时解除高度后测量。 */
+export function useMultilineLayout({
+  enabled,
+  value,
+  minHeight,
+  maxHeight,
+  fontSize,
+  placeholder,
+  inputRef,
+}: MultilineLayoutInput): MultilineLayout {
+  const [contentHeight, setContentHeight] = useState(0);
+  const [width, setWidth] = useState(0);
+  const minimum = Math.max(0, minHeight - TEXTAREA_VERTICAL_INSET);
+  const maximum =
+    maxHeight === undefined
+      ? Infinity
+      : Math.max(0, maxHeight - TEXTAREA_VERTICAL_INSET);
+  useLayoutEffect(() => {
+    if (!enabled || inputRef.current === null) return;
+    const node = inputRef.current as unknown as WebTextInputMeasurement;
+    const { height, minHeight: previousMinimum } = node.style;
+    const scrollTop = node.scrollTop;
+    node.style.height = '0px';
+    node.style.minHeight = '0px';
+    const measured = node.scrollHeight;
+    node.style.height = height;
+    node.style.minHeight = previousMinimum;
+    node.scrollTop = scrollTop;
+    if (Number.isFinite(measured)) setContentHeight(measured);
+  }, [
+    enabled,
+    value,
+    width,
+    fontSize,
+    placeholder,
+    minHeight,
+    maxHeight,
+    inputRef,
+  ]);
+  const onLayout = useCallback<NonNullable<MultilineLayout['onLayout']>>(
+    (event) => setWidth(event.nativeEvent.layout.width),
+    []
+  );
+  return {
+    inputStyle: {
+      height: Math.min(maximum, Math.max(minimum, contentHeight)),
+    },
+    scrollEnabled: contentHeight > maximum,
+    onLayout,
+  };
+}

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

@@ -13,9 +13,12 @@ import type {
  */
 export type TextareaProps = Omit<TextInputProps, RemovedTextInputProps> &
   TextFieldCommonProps &
-  TextFieldValueProps & {
-    /** 最小高度，默认 96（约 5 行） */
-    minHeight?: number;
-    /** 最大高度（超过后内部滚动），默认不限制 */
-    maxHeight?: number;
-  };
+  TextFieldValueProps &
+  TextareaHeightProps;
+
+interface TextareaHeightProps {
+  /** 最小高度，默认 96（约 5 行） */
+  minHeight?: number;
+  /** 最大高度（超过后内部滚动），默认不限制 */
+  maxHeight?: number;
+}

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

@@ -5,8 +5,11 @@ import { resolveImageSource } from '../../../utils/imageSource';
 import { createLogger } from '../../../utils/logger';
 import { ImageAttempt } from '../shared/ImageAttempt';
 import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
-import { sanitizeThumbnailImageStyle } from './normalize';
-import { makeStyles, sizingFor } from './styles';
+import {
+  normalizeThumbnailDimensions,
+  sanitizeThumbnailImageStyle,
+} from './normalize';
+import { makeStyles } from './styles';
 import type { ThumbnailProps } from './types';
 
 const log = createLogger('Thumbnail');
@@ -22,6 +25,7 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
     uri,
     source,
     size = 'md',
+    fallback,
     selected,
     containerStyle,
     imageStyle,
@@ -31,7 +35,8 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
   } = props;
   const colors = useColors();
   const styles = useThemedStyles(makeStyles);
-  const dim = sizingFor(size);
+  const normalizedDimensions = normalizeThumbnailDimensions(size);
+  const dim = normalizedDimensions.dimensions;
   const hasUri = hasOwn(props, 'uri');
   const hasSource = hasOwn(props, 'source');
   const sourceCandidate =
@@ -43,6 +48,7 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
   const resolvedSource = resolveImageSource(sourceCandidate);
   const sanitizedImageStyle = sanitizeThumbnailImageStyle(imageStyle);
   const diagnostics = [
+    ...normalizedDimensions.diagnostics,
     ...(resolvedSource === undefined ? ['source'] : []),
     ...sanitizedImageStyle.diagnostics.map((field) =>
       field === 'style' ? 'imageStyle' : `imageStyle.${field}`
@@ -72,16 +78,24 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
     borderRadius: dim.borderRadius,
     borderColor: selected ? colors.primary : 'transparent',
   };
+  const fallbackContent =
+    fallback === undefined ? null : (
+      <View {...imageAccessibilityProps} style={styles.fallback}>
+        {fallback}
+      </View>
+    );
 
   return (
     <View style={containerStyle} testID={testID}>
       <View style={[styles.visualFrame, dim]}>
-        {resolvedSource === undefined ? null : (
+        {resolvedSource === undefined ? (
+          fallbackContent
+        ) : (
           <ImageAttempt
             {...imageAccessibilityProps}
             key={resolvedSource.key}
             source={resolvedSource.source}
-            fallback={null}
+            fallback={fallbackContent}
             style={[sanitizedImageStyle.style, StyleSheet.absoluteFill]}
             resizeMode={resizeMode}
           />

package/src/components/ui/Thumbnail/constants.ts

@@ -0,0 +1,24 @@
+import { r } from '../../../theme';
+import type { ThumbnailDimensions, ThumbnailSize } from './types';
+
+export const THUMBNAIL_DIMENSIONS: Readonly<
+  Record<ThumbnailSize, Required<ThumbnailDimensions>>
+> = {
+  sm: { width: r(64), height: r(40), borderRadius: r(6) },
+  md: { width: r(113), height: r(67), borderRadius: r(8) },
+  lg: { width: r(160), height: r(96), borderRadius: r(10) },
+};
+
+export const RESERVED_IMAGE_STYLE_KEYS = [
+  'position',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'width',
+  'height',
+  'minWidth',
+  'minHeight',
+  'maxWidth',
+  'maxHeight',
+] as const;

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

@@ -1,5 +1,6 @@
 export { Thumbnail } from './Thumbnail';
 export type {
+  ThumbnailDimensions,
   ThumbnailImageStyle,
   ThumbnailProps,
   ThumbnailSize,

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

@@ -1,25 +1,44 @@
 import { StyleSheet } from 'react-native';
 import type { StyleProp } from 'react-native';
-import type { ThumbnailImageStyle } from './types';
+import type {
+  NormalizedThumbnailDimensions,
+  SanitizedThumbnailImageStyle,
+  ThumbnailImageStyle,
+} from './types';
+import { RESERVED_IMAGE_STYLE_KEYS, THUMBNAIL_DIMENSIONS } from './constants';
 
-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[];
-};
+export function normalizeThumbnailDimensions(
+  size: unknown
+): NormalizedThumbnailDimensions {
+  if (size === undefined || size === 'sm' || size === 'md' || size === 'lg') {
+    return { dimensions: THUMBNAIL_DIMENSIONS[size ?? 'md'], diagnostics: [] };
+  }
+  if (typeof size === 'object' && size !== null && !Array.isArray(size)) {
+    const { width, height, borderRadius } = size as Record<string, unknown>;
+    if (
+      typeof width === 'number' &&
+      Number.isFinite(width) &&
+      width > 0 &&
+      typeof height === 'number' &&
+      Number.isFinite(height) &&
+      height > 0 &&
+      (borderRadius === undefined ||
+        (typeof borderRadius === 'number' &&
+          Number.isFinite(borderRadius) &&
+          borderRadius >= 0))
+    ) {
+      return {
+        dimensions: {
+          width,
+          height,
+          borderRadius: borderRadius ?? THUMBNAIL_DIMENSIONS.md.borderRadius,
+        },
+        diagnostics: [],
+      };
+    }
+  }
+  return { dimensions: THUMBNAIL_DIMENSIONS.md, diagnostics: ['size'] };
+}
 
 function invalidStyle(): SanitizedThumbnailImageStyle {
   return { style: {}, diagnostics: ['style'] };

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

@@ -1,6 +1,5 @@
 import { StyleSheet } from 'react-native';
-import { r, type ColorTokens } from '../../../theme';
-import type { ThumbnailSize } from './types';
+import { type ColorTokens } from '../../../theme';
 
 /** Thumbnail 静态样式 ——
  *  - `visualFrame`:固定尺寸、裁切、加载失败 placeholder
@@ -14,19 +13,9 @@ export const makeStyles = (c: ColorTokens) =>
     ring: {
       borderWidth: 2,
     },
+    fallback: {
+      ...StyleSheet.absoluteFill,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
   });
-
-/** Thumbnail size 阶梯 —— width / height / borderRadius 全 r() 缩放。
- *  新增 size 在 types.ts 加 union + 这里加 case,两处同步。 */
-export const sizingFor = (size: ThumbnailSize) => {
-  switch (size) {
-    case 'sm':
-      return { width: r(64), height: r(40), borderRadius: r(6) };
-    case 'lg':
-      return { width: r(160), height: r(96), borderRadius: r(10) };
-    case 'md':
-    default:
-      // 113×67 与 NewsList / NewsArea 历史一致,16:9.5 接近视频宽高比
-      return { width: r(113), height: r(67), borderRadius: r(8) };
-  }
-};

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

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import type {
   ImageProps,
   ImageSourcePropType,
@@ -6,12 +7,29 @@ import type {
   ViewStyle,
 } from 'react-native';
 
-/** 缩略图尺寸阶梯 —— 跨场景统一,新增 size 在这里 + sizingFor.ts 同步。
+/** 缩略图尺寸阶梯 —— 跨场景统一,新增阶梯在这里与 constants.ts 同步。
  *  - sm:64×40 chat 行内、列表二级图缩略
  *  - md:113×67 NewsList / NewsArea 公告右侧缩略(默认)
  *  - lg:160×96 详情顶部 hero 小图、卡片头图缩略 */
 export type ThumbnailSize = 'sm' | 'md' | 'lg';
 
+/** 已计算好的 RN 布局尺寸；组件不再调用 r() 缩放。 */
+export interface ThumbnailDimensions {
+  width: number;
+  height: number;
+  borderRadius?: number;
+}
+
+export interface NormalizedThumbnailDimensions {
+  dimensions: Required<ThumbnailDimensions>;
+  diagnostics: readonly string[];
+}
+
+export interface SanitizedThumbnailImageStyle {
+  style: ThumbnailImageStyle;
+  diagnostics: readonly string[];
+}
+
 export type ThumbnailImageStyle = Omit<
   ImageStyle,
   | 'position'
@@ -39,9 +57,11 @@ type ThumbnailSource =
       uri?: never;
     };
 
-export type ThumbnailProps = ThumbnailSource & {
-  /** 视觉尺寸阶梯,默认 'md'。 */
-  size?: ThumbnailSize;
+interface ThumbnailCommonProps {
+  /** 原三档或实际图像框尺寸，默认 md；非法对象整体回退 md。 */
+  size?: ThumbnailSize | Readonly<ThumbnailDimensions>;
+  /** 无有效 source 或当前图片失败时居中显示；加载中不显示。 */
+  fallback?: ReactNode;
   /** 选中态:在固定 visual frame 内显示 2pt 品牌色 ring。 */
   selected?: boolean;
   /** 完整外部布局样式，只落到稳定根 View。 */
@@ -54,4 +74,6 @@ export type ThumbnailProps = ThumbnailSource & {
   accessibilityLabel?: string;
   /** E2E / 测试定位，只落到外层 layout View。 */
   testID?: string;
-};
+}
+
+export type ThumbnailProps = ThumbnailSource & ThumbnailCommonProps;

package/src/components/ui/index.ts

@@ -97,6 +97,7 @@ export type { TextareaProps } from './Textarea';
 export { Thumbnail } from './Thumbnail';
 export type {
   ThumbnailImageStyle,
+  ThumbnailDimensions,
   ThumbnailProps,
   ThumbnailSize,
 } from './Thumbnail';

package/src/components/ui/shared/pulse/constants.ts

@@ -0,0 +1,2 @@
+// 平台计时器使用 int32，达到 2^31 会溢出。
+export const MAX_TIMER = 2 ** 31;

package/src/components/ui/shared/pulse/normalizePulseOptions.ts

@@ -0,0 +1,48 @@
+import type { PulseOptions } from '../../Pulse/types';
+import type {
+  NormalizedPulseOptions,
+  PulseDefaults,
+  PulseDiagnostic,
+} from './types';
+import { MAX_TIMER } from './constants';
+
+/** 共用的参数校验：非法字段采用所属组件默认值并报告诊断，不夹值或取整。 */
+export function normalizePulseOptions(
+  input: PulseOptions = {},
+  defaults: Readonly<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/shared/pulse/types.ts

@@ -0,0 +1,18 @@
+export interface PulseDefaults {
+  duration: number;
+  delay: number;
+  from: number;
+  to: number;
+}
+
+export interface PulseDiagnostic {
+  field: keyof PulseDefaults;
+  received: unknown;
+  fallback: number;
+}
+
+export interface NormalizedPulseOptions extends PulseDefaults {
+  /** 两端相等 —— 没有可播的动画,driver 直接停在 `to`。 */
+  isStatic: boolean;
+  diagnostics: readonly PulseDiagnostic[];
+}