@unif/react-native-design 0.19.0 → 0.21.0

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

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

@@ -0,0 +1,85 @@
+export type NormalizedStepper = {
+  safeMin: number;
+  safeMax: number;
+  safeStep: number;
+  safeValue: number;
+  rangeDisabled: boolean;
+  canDecrement: boolean;
+  canIncrement: boolean;
+  accessibilityActions: Array<{
+    name: 'increment' | 'decrement';
+    label: '增加' | '减少';
+  }>;
+};
+
+type StepperNormalizationInput = {
+  value: unknown;
+  min?: unknown;
+  max?: unknown;
+  step?: unknown;
+  disabled?: unknown;
+};
+
+export type StepperDirection = 'increment' | 'decrement';
+
+/**
+ * Stepper 唯一的范围与 action 归一化入口。
+ *
+ * 组件的视觉状态、handler 和 a11y 都消费同一份结果，避免边界按钮已禁用但
+ * adjustable 仍暴露无效 action。
+ */
+export function normalizeStepper({
+  value,
+  min = 0,
+  max = 99,
+  step = 1,
+  disabled = false,
+}: StepperNormalizationInput): NormalizedStepper {
+  const safeMin = typeof min === 'number' && Number.isFinite(min) ? min : 0;
+  const safeMax =
+    typeof max === 'number' && Number.isFinite(max) && max >= safeMin
+      ? max
+      : safeMin;
+  const safeStep =
+    typeof step === 'number' && Number.isFinite(step) && step > 0 ? step : 1;
+  const safeValue =
+    typeof value === 'number' && Number.isFinite(value)
+      ? Math.min(safeMax, Math.max(safeMin, value))
+      : safeMin;
+  const rangeDisabled = disabled === true || safeMin === safeMax;
+  const canDecrement = !rangeDisabled && safeValue > safeMin;
+  const canIncrement = !rangeDisabled && safeValue < safeMax;
+  const accessibilityActions: NormalizedStepper['accessibilityActions'] = [];
+
+  if (canIncrement) {
+    accessibilityActions.push({ name: 'increment', label: '增加' });
+  }
+  if (canDecrement) {
+    accessibilityActions.push({ name: 'decrement', label: '减少' });
+  }
+
+  return {
+    safeMin,
+    safeMax,
+    safeStep,
+    safeValue,
+    rangeDisabled,
+    canDecrement,
+    canIncrement,
+    accessibilityActions,
+  };
+}
+
+export function nextStepperValue(
+  normalized: NormalizedStepper,
+  direction: StepperDirection
+): number | undefined {
+  if (direction === 'increment') {
+    return normalized.canIncrement
+      ? Math.min(normalized.safeMax, normalized.safeValue + normalized.safeStep)
+      : undefined;
+  }
+  return normalized.canDecrement
+    ? Math.max(normalized.safeMin, normalized.safeValue - normalized.safeStep)
+    : undefined;
+}

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

@@ -4,7 +4,7 @@ import type { ColorTokens } from '../../../theme';
 import type { StepperSize } from './types';
 
 /** Stepper 静态 + themed base —— btn / value 容器共用 cell 基底,radius / border 走 token。
- *  尺寸(高 / 宽 / 字号)由 sizingFor 派生,sm 走 control.sm,md 走 r(32)(介于
+ *  尺寸(高 / 宽 / 字号)由 sizingFor 派生,sm 走 control.sm (`r(28)`),md 走 r(32)(介于
  *  control.sm 与 control.md 之间,与 avatar.md / dim.sendBtn 同值但语义独立)。 */
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
@@ -13,6 +13,13 @@ export const makeStyles = (c: ColorTokens) =>
       alignItems: 'center',
       alignSelf: 'flex-start',
     },
+    actionFrame: {
+      justifyContent: 'center',
+    },
+    valueFrame: {
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
     /** btn / value 共用的 cell 基底 —— 居中 + surface 背景 + 上下边框。
      *  左右边框 / 圆角由 btnLeft / btnRight 增量补齐;value 中间无侧边框。 */
     cell: {
@@ -45,7 +52,7 @@ export const makeStyles = (c: ColorTokens) =>
     },
   });
 
-/** Stepper 尺寸推导:sm(control.sm=28 高 / 28 按钮 / 40 值宽 / xs 字)/
+/** Stepper 尺寸推导:sm(control.sm=`r(28)` 高 / `r(28)` 按钮 / r(40) 值宽 / xs 字)/
  *  md(r(32) 高 / r(32) 按钮 / r(48) 值宽 / sm 字)。
  *  新增 size 在 types.ts 加 union + 这里加 case。 */
 export function sizingFor(size: StepperSize): {

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

@@ -6,6 +6,8 @@ export type StepperProps = {
   value: number;
   /** 值变化回调（已自动夹到 [min, max] 区间） */
   onChange: (value: number) => void;
+  /** 中央 adjustable 的上下文名称，左右按钮自动组合“${label}，减少 / 增加” */
+  accessibilityLabel: string;
   /** 最小值，默认 0 */
   min?: number;
   /** 最大值，默认 99 */
@@ -14,7 +16,7 @@ export type StepperProps = {
   step?: number;
   /** 尺寸，默认 'md' */
   size?: StepperSize;
-  /** 整体禁用（两个按钮都不可点） */
+  /** 整体禁用（三个操作节点都不暴露 action） */
   disabled?: boolean;
   /** E2E / 测试定位 */
   testID?: string;