@unif/react-native-design 0.20.0 → 0.21.0

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;

package/src/components/ui/Stepper/Stepper.tsx

@@ -1,9 +1,19 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { Text, View } from 'react-native';
-import { Pressable } from 'react-native-gesture-handler';
-import { fixed, pressedOpacity, useThemedStyles } from '../../../theme';
+import {
+  pressedOpacity,
+  scaleFontMetric,
+  useFontScale,
+  useThemedStyles,
+} 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 { getStepperValueAccessibilityProps } from './accessibility';
+import { resolveStepperLayout } from './layout';
+import { nextStepperValue, normalizeStepper } from './normalizeStepper';
+import { StepperPressable } from './StepperPressable';
 import { makeStyles, sizingFor } from './styles';
 import type { StepperProps } from './types';
 
@@ -16,115 +26,185 @@ const _warned = new Set<string>();
  * 数字步进器 [−][ N ][+]。
  * 按钮自动夹到 min/max；越界的按钮透明度变 0.4。
  *
- * 健壮性：value 为 NaN/Infinity 时显示为 min；step <=0 或非有限数时回退 1；
- * min > max 时整体按 min（避免 onChange 写出乱序值）。
+ * 健壮性：value/min/max 的非法或非有限输入均折叠到安全范围；step <=0 或
+ * 非有限数时回退 1；min > max 时折叠为 min 的零范围。
  */
 export function Stepper({
   value,
   onChange,
-  min = 0,
-  max = 99,
-  step = 1,
+  accessibilityLabel,
+  min,
+  max,
+  step,
   size = 'md',
   disabled = false,
   testID,
 }: StepperProps): React.JSX.Element {
   const styles = useThemedStyles(makeStyles);
+  const fontScale = useFontScale();
   const dims = sizingFor(size);
+  const valueFontSize = scaleFontMetric(dims.fs, fontScale);
+  const layout = resolveStepperLayout(dims);
+  const accessibleName = normalizeNonBlankText(accessibilityLabel);
+  const hasBlankLabel = accessibleName === undefined;
+  const normalized = normalizeStepper({
+    value,
+    min,
+    max,
+    step,
+    disabled: disabled === true || hasBlankLabel,
+  });
+  const { safeMin, safeStep, safeValue, canDecrement, canIncrement } =
+    normalized;
+  const decrementValue = nextStepperValue(normalized, 'decrement');
+  const incrementValue = nextStepperValue(normalized, 'increment');
+  const valueAccessibilityProps = getStepperValueAccessibilityProps({
+    normalized,
+    onChange,
+  });
 
   // [L-30] step 口径对齐:非有限数(NaN/Infinity)也告警,与 min>max 告警保持一致
-  // 模块级 Set 去重:每个异常组合只打一次告警,避免渲染阶段重复刷屏
-  if (!Number.isFinite(step) || step <= 0) {
-    const k = `step:${step}`;
-    if (!_warned.has(k)) {
-      _warned.add(k);
-      log.warn(`step 必须是有限正数，传入 ${step}，已 fallback 为 1`);
+  // 告警也读取归一化结果,避免提示 fallback 与实际 render/action 使用不同数值。
+  const hasInvalidStep = step !== undefined && safeStep !== step;
+  const hasInvalidRange =
+    min !== undefined &&
+    max !== undefined &&
+    typeof min === 'number' &&
+    Number.isFinite(min) &&
+    typeof max === 'number' &&
+    Number.isFinite(max) &&
+    min > max;
+
+  useEffect(() => {
+    if (hasInvalidStep) {
+      const k = `step:${String(step)}`;
+      if (!_warned.has(k)) {
+        _warned.add(k);
+        log.warn(
+          `step 必须是有限正数，传入 ${String(step)}，已 fallback 为 ${safeStep}`
+        );
+      }
+    }
+  }, [hasInvalidStep, safeStep, step]);
+  useEffect(() => {
+    if (hasInvalidRange) {
+      const k = `minmax:${String(min)}:${String(max)}`;
+      if (!_warned.has(k)) {
+        _warned.add(k);
+        log.warn(
+          `min(${String(min)}) 不能大于 max(${String(max)})，已折叠为 ${safeMin} 的零范围`
+        );
+      }
     }
-  }
-  if (Number.isFinite(min) && Number.isFinite(max) && min > max) {
-    const k = `minmax:${min}:${max}`;
-    if (!_warned.has(k)) {
-      _warned.add(k);
-      log.warn(`min(${min}) 不能大于 max(${max})，已按 min 渲染`);
+  }, [hasInvalidRange, max, min, safeMin]);
+  useEffect(() => {
+    if (hasBlankLabel) {
+      log.warn('Stepper accessibilityLabel 不能为空白，当前 action 已禁用。');
     }
-  }
-  const safeStep = Number.isFinite(step) && step > 0 ? step : 1;
-  const safeMin = Number.isFinite(min) ? min : 0;
-  const safeMax = Number.isFinite(max) && max >= safeMin ? max : safeMin;
-  // value 处理:NaN → min;±Infinity → 钳到 [min, max];有限数 → 正常 clamp
-  const safeValue = Number.isNaN(value)
-    ? safeMin
-    : Math.min(safeMax, Math.max(safeMin, value));
-  const decDisabled = disabled || safeValue <= safeMin;
-  const incDisabled = disabled || safeValue >= safeMax;
+  }, [hasBlankLabel]);
 
-  // [M-7] 按钮高 sm=28 / md=32 均低于 fixed.hitTarget=44;hitSlop 不越父边界,
-  // 须让容器一并扩展:wrap 加垂直 padding 把命中区撑到 44pt。
-  const wrapPaddingV = Math.max(0, Math.round((fixed.hitTarget - dims.h) / 2));
+  const decrementTestID = childTestID(testID, 'decrement');
+  const valueTestID = childTestID(testID, 'value');
+  const incrementTestID = childTestID(testID, 'increment');
 
   return (
-    <View
-      style={[styles.wrap, { paddingVertical: wrapPaddingV }]}
-      testID={testID}
-    >
-      <Pressable
-        onPress={() => onChange(Math.max(safeMin, safeValue - safeStep))}
-        disabled={decDisabled}
-        accessibilityRole="button"
-        accessibilityLabel="减少"
-        accessibilityState={{ disabled: decDisabled }}
-        accessibilityHint={`当前值 ${safeValue}，减 ${safeStep}`}
-        testID={childTestID(testID, 'decrement')}
+    <View style={styles.wrap} testID={testID}>
+      <StepperPressable
+        accessible={!hasBlankLabel}
+        onPress={
+          decrementValue === undefined
+            ? undefined
+            : () => onChange(decrementValue)
+        }
+        disabled={!canDecrement}
+        accessibilityRole={hasBlankLabel ? undefined : 'button'}
+        accessibilityLabel={
+          accessibleName === undefined ? undefined : `${accessibleName}，减少`
+        }
+        accessibilityState={
+          hasBlankLabel ? undefined : { disabled: !canDecrement }
+        }
+        accessibilityHint={
+          hasBlankLabel ? undefined : `当前值 ${safeValue}，减 ${safeStep}`
+        }
+        testID={decrementTestID}
         style={({ pressed }) => [
-          styles.cell,
-          styles.btnLeft,
-          { width: dims.btn, height: dims.h },
-          { opacity: decDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
+          styles.actionFrame,
+          layout.decrementFrame,
+          {
+            opacity: !canDecrement ? 0.4 : pressed ? pressedOpacity : 1,
+          },
         ]}
       >
-        <Text style={styles.btnText}>−</Text>
-      </Pressable>
-      {/* [L-29] adjustable 需配 accessible + accessibilityActions + onAccessibilityAction,
-          否则 iOS VoiceOver 宣读"可调节"但滑动手势无响应。*/}
+        <View
+          {...A11Y_HIDDEN_PROPS}
+          style={[
+            styles.cell,
+            styles.btnLeft,
+            { width: dims.btn, height: dims.h },
+          ]}
+          testID={childTestID(testID, 'decrement-visual')}
+        >
+          <Text style={styles.btnText}>−</Text>
+        </View>
+      </StepperPressable>
       <View
-        accessible
-        accessibilityRole="adjustable"
-        accessibilityValue={{ min: safeMin, max: safeMax, now: safeValue }}
-        accessibilityActions={[
-          { name: 'increment', label: '增加' },
-          { name: 'decrement', label: '减少' },
-        ]}
-        onAccessibilityAction={(e) => {
-          if (e.nativeEvent.actionName === 'increment' && !incDisabled) {
-            onChange(Math.min(safeMax, safeValue + safeStep));
-          } else if (e.nativeEvent.actionName === 'decrement' && !decDisabled) {
-            onChange(Math.max(safeMin, safeValue - safeStep));
-          }
-        }}
-        style={[styles.cell, { minWidth: dims.w, height: dims.h }]}
-        testID={childTestID(testID, 'value')}
+        accessible={!hasBlankLabel}
+        accessibilityRole={hasBlankLabel ? undefined : 'adjustable'}
+        accessibilityLabel={accessibleName}
+        {...(hasBlankLabel ? {} : valueAccessibilityProps)}
+        style={[styles.valueFrame, layout.valueFrame]}
+        testID={valueTestID}
       >
-        <Text style={[styles.valueText, { fontSize: dims.fs }]}>
-          {safeValue}
-        </Text>
+        <View
+          {...A11Y_HIDDEN_PROPS}
+          style={[styles.cell, { width: dims.w, height: dims.h }]}
+          testID={childTestID(testID, 'value-visual')}
+        >
+          <Text style={[styles.valueText, { fontSize: valueFontSize }]}>
+            {safeValue}
+          </Text>
+        </View>
       </View>
-      <Pressable
-        onPress={() => onChange(Math.min(safeMax, safeValue + safeStep))}
-        disabled={incDisabled}
-        accessibilityRole="button"
-        accessibilityLabel="增加"
-        accessibilityState={{ disabled: incDisabled }}
-        accessibilityHint={`当前值 ${safeValue}，加 ${safeStep}`}
-        testID={childTestID(testID, 'increment')}
+      <StepperPressable
+        accessible={!hasBlankLabel}
+        onPress={
+          incrementValue === undefined
+            ? undefined
+            : () => onChange(incrementValue)
+        }
+        disabled={!canIncrement}
+        accessibilityRole={hasBlankLabel ? undefined : 'button'}
+        accessibilityLabel={
+          accessibleName === undefined ? undefined : `${accessibleName}，增加`
+        }
+        accessibilityState={
+          hasBlankLabel ? undefined : { disabled: !canIncrement }
+        }
+        accessibilityHint={
+          hasBlankLabel ? undefined : `当前值 ${safeValue}，加 ${safeStep}`
+        }
+        testID={incrementTestID}
         style={({ pressed }) => [
-          styles.cell,
-          styles.btnRight,
-          { width: dims.btn, height: dims.h },
-          { opacity: incDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
+          styles.actionFrame,
+          layout.incrementFrame,
+          {
+            opacity: !canIncrement ? 0.4 : pressed ? pressedOpacity : 1,
+          },
         ]}
       >
-        <Text style={styles.btnText}>+</Text>
-      </Pressable>
+        <View
+          {...A11Y_HIDDEN_PROPS}
+          style={[
+            styles.cell,
+            styles.btnRight,
+            { width: dims.btn, height: dims.h },
+          ]}
+          testID={childTestID(testID, 'increment-visual')}
+        >
+          <Text style={styles.btnText}>+</Text>
+        </View>
+      </StepperPressable>
     </View>
   );
 }

package/src/components/ui/Stepper/StepperPressable.tsx

@@ -0,0 +1 @@
+export { Pressable as StepperPressable } from 'react-native-gesture-handler';

package/src/components/ui/Stepper/StepperPressable.web.tsx

@@ -0,0 +1 @@
+export { Pressable as StepperPressable } from 'react-native';

package/src/components/ui/Stepper/accessibility.ts

@@ -0,0 +1,32 @@
+import { nextStepperValue } from './normalizeStepper';
+import type {
+  StepperAccessibilityInput,
+  StepperValueAccessibilityProps,
+} from './accessibility.types';
+
+export function getStepperValueAccessibilityProps({
+  normalized,
+  onChange,
+}: StepperAccessibilityInput): StepperValueAccessibilityProps {
+  const base = {
+    accessibilityState: { disabled: normalized.rangeDisabled },
+    accessibilityValue: {
+      min: normalized.safeMin,
+      max: normalized.safeMax,
+      now: normalized.safeValue,
+    },
+  };
+
+  if (normalized.rangeDisabled) return base;
+
+  return {
+    ...base,
+    accessibilityActions: normalized.accessibilityActions,
+    onAccessibilityAction: (event) => {
+      const name = event.nativeEvent.actionName;
+      if (name !== 'increment' && name !== 'decrement') return;
+      const nextValue = nextStepperValue(normalized, name);
+      if (nextValue !== undefined) onChange(nextValue);
+    },
+  };
+}

package/src/components/ui/Stepper/accessibility.types.ts

@@ -0,0 +1,22 @@
+import type { NativeSyntheticEvent, ViewProps } from 'react-native';
+import type { NormalizedStepper } from './normalizeStepper';
+
+export type StepperAccessibilityInput = {
+  normalized: NormalizedStepper;
+  onChange: (value: number) => void;
+};
+
+type StepperKeyDownEvent = NativeSyntheticEvent<Readonly<{ key: string }>>;
+
+export type StepperValueAccessibilityProps = {
+  'accessibilityState'?: ViewProps['accessibilityState'];
+  'accessibilityValue'?: ViewProps['accessibilityValue'];
+  'accessibilityActions'?: ViewProps['accessibilityActions'];
+  'onAccessibilityAction'?: ViewProps['onAccessibilityAction'];
+  'aria-disabled'?: ViewProps['aria-disabled'];
+  'aria-valuemin'?: ViewProps['aria-valuemin'];
+  'aria-valuemax'?: ViewProps['aria-valuemax'];
+  'aria-valuenow'?: ViewProps['aria-valuenow'];
+  'tabIndex'?: ViewProps['tabIndex'];
+  'onKeyDown'?: (event: StepperKeyDownEvent) => void;
+};

package/src/components/ui/Stepper/accessibility.web.ts

@@ -0,0 +1,65 @@
+import { nextStepperValue } from './normalizeStepper';
+import type {
+  StepperAccessibilityInput,
+  StepperValueAccessibilityProps,
+} from './accessibility.types';
+import type { NormalizedStepper, StepperDirection } from './normalizeStepper';
+
+export type StepperWebKeyResult = {
+  handled: boolean;
+  nextValue?: number;
+};
+
+export function resolveStepperWebKey(
+  key: string,
+  normalized: NormalizedStepper
+): StepperWebKeyResult {
+  const direction: StepperDirection | undefined =
+    key === 'ArrowUp' || key === 'ArrowRight'
+      ? 'increment'
+      : key === 'ArrowDown' || key === 'ArrowLeft'
+        ? 'decrement'
+        : undefined;
+
+  if (direction) {
+    const nextValue = nextStepperValue(normalized, direction);
+    return nextValue === undefined
+      ? { handled: true }
+      : { handled: true, nextValue };
+  }
+  if (key === 'Home') {
+    return normalized.canDecrement
+      ? { handled: true, nextValue: normalized.safeMin }
+      : { handled: true };
+  }
+  if (key === 'End') {
+    return normalized.canIncrement
+      ? { handled: true, nextValue: normalized.safeMax }
+      : { handled: true };
+  }
+  return { handled: false };
+}
+
+export function getStepperValueAccessibilityProps({
+  normalized,
+  onChange,
+}: StepperAccessibilityInput): StepperValueAccessibilityProps {
+  const base = {
+    'aria-disabled': normalized.rangeDisabled,
+    'aria-valuemin': normalized.safeMin,
+    'aria-valuemax': normalized.safeMax,
+    'aria-valuenow': normalized.safeValue,
+    'tabIndex': normalized.rangeDisabled ? (-1 as const) : (0 as const),
+  };
+  if (normalized.rangeDisabled) return base;
+
+  return {
+    ...base,
+    onKeyDown: (event) => {
+      const result = resolveStepperWebKey(event.nativeEvent.key, normalized);
+      if (!result.handled) return;
+      event.preventDefault();
+      if (result.nextValue !== undefined) onChange(result.nextValue);
+    },
+  };
+}

package/src/components/ui/Stepper/layout.ts

@@ -0,0 +1,44 @@
+import { fixed } from '../../../theme';
+
+export type ResolvedStepperLayout = {
+  decrementFrame: {
+    width: number;
+    height: number;
+    alignItems: 'flex-end';
+  };
+  valueFrame: { width: number; height: number };
+  incrementFrame: {
+    width: number;
+    height: number;
+    alignItems: 'flex-start';
+  };
+};
+
+export function resolveStepperLayout({
+  h,
+  btn,
+  w,
+}: {
+  h: number;
+  btn: number;
+  w: number;
+}): ResolvedStepperLayout {
+  const sideWidth = Math.max(fixed.hitTarget, btn);
+  const outerHeight = Math.max(fixed.hitTarget, h);
+  return {
+    decrementFrame: {
+      width: sideWidth,
+      height: outerHeight,
+      alignItems: 'flex-end',
+    },
+    valueFrame: {
+      width: Math.max(fixed.hitTarget, w),
+      height: outerHeight,
+    },
+    incrementFrame: {
+      width: sideWidth,
+      height: outerHeight,
+      alignItems: 'flex-start',
+    },
+  };
+}