@unif/react-native-design 0.19.0 → 0.21.0

package/src/components/ui/Cell/Cell.tsx

@@ -1,36 +1,41 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { type StyleProp, Text, type TextStyle, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
 import { pressedOpacity, r, useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
 import { Icon } from '../Icon';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import {
+  resolveCellActionAccessibilityLabel,
+  stringifyCellText,
+} from './content';
 import { useListVariant } from './context';
 import { Leading } from './Leading';
 import { makeStyles } from './styles';
-import type { CellProps } from './types';
+import type { CellExtra, CellProps } from './types';
 
-/** extra 是否包含可交互控件(Switch/Stepper/Checkbox 等 ReactNode)。
- *  用于决定 Pressable 外壳是否关闭 accessible —— 若外壳 accessible=true 且 extra 也是
- *  独立 accessible 控件,SR 会产生「双播报 + 控件被遮挡无法直接激活」的体验缺陷。
- *  规则:extra 是 ReactNode(非 string / null / undefined)时判定为「可能含控件」。
- *  使用方若明确 extra 是纯展示 ReactNode,可通过 accessibilityHint='none' 绕过(暂不加 prop)。*/
-function extraHasInteractiveNode(extra: CellProps['extra']): boolean {
-  return extra != null && typeof extra !== 'string';
-}
+const log = createLogger('Cell');
 
-function renderSlot(
-  value: React.ReactNode,
-  textStyle: StyleProp<TextStyle>,
-  numberOfLines: number
-): React.ReactNode {
-  if (value == null) return null;
-  if (typeof value === 'string') {
-    return (
-      <Text style={textStyle} numberOfLines={numberOfLines}>
-        {value}
-      </Text>
-    );
+function CellExtraContent({
+  extra,
+  textStyle,
+}: {
+  extra: CellExtra | undefined;
+  textStyle: StyleProp<TextStyle>;
+}): React.JSX.Element | null {
+  if (!extra) return null;
+  switch (extra.kind) {
+    case 'text':
+      return (
+        <Text style={textStyle} numberOfLines={1}>
+          {stringifyCellText(extra.value)}
+        </Text>
+      );
+    case 'display':
+      return <View {...A11Y_HIDDEN_PROPS}>{extra.node}</View>;
+    case 'control':
+      return extra.node;
   }
-  return value;
 }
 
 /**
@@ -40,34 +45,38 @@ function renderSlot(
  * - `grouped`(默认):独立白卡片 + 8px 间距
  * - `flush`(嵌在 Card 内):紧凑列表,28×28 橙色 icon 盒子,行间 inset hairline 分隔
  */
-export function Cell({
-  title,
-  titleLines,
-  desc,
-  extra,
-  arrow,
-  leading,
-  onPress,
-  disabled,
-  danger,
-  style,
-  testID,
-  accessibilityLabel,
-  accessibilityHint,
-}: CellProps): React.JSX.Element {
+export function Cell(props: CellProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
   const variant = useListVariant();
   const flush = variant === 'flush';
+  const requestedAction = typeof props.onPress === 'function';
+  const accessibilityLabel = requestedAction
+    ? resolveCellActionAccessibilityLabel({
+        accessibilityLabel: props.accessibilityLabel,
+        title: props.title,
+        desc: props.desc,
+        extra: props.extra,
+      })
+    : undefined;
+  const hasEffectiveAction =
+    requestedAction && accessibilityLabel !== undefined;
+  const hasMissingActionName = requestedAction && !hasEffectiveAction;
+
+  useEffect(() => {
+    if (hasMissingActionName) {
+      log.warn('Cell action 缺少非空业务名称，已按 display-only 渲染。');
+    }
+  }, [hasMissingActionName]);
 
   const cellStyle = [
     styles.cell,
     flush && styles.cellFlush,
-    flush && desc != null && styles.cellFlushWithDesc,
-    style,
+    flush && props.desc !== undefined && styles.cellFlushWithDesc,
+    props.style,
   ];
 
-  const titleColor = danger ? c.error : undefined;
+  const titleColor = props.danger ? c.error : undefined;
   const titleStyle = [
     flush ? styles.titleFlush : styles.title,
     titleColor && { color: titleColor },
@@ -76,51 +85,53 @@ export function Cell({
   const extraStyle = flush ? styles.extraFlush : styles.extra;
 
   const inner = (
-    <View style={cellStyle} testID={onPress ? undefined : testID}>
-      {leading != null ? <Leading slot={leading} danger={danger} /> : null}
+    <View
+      style={cellStyle}
+      testID={hasEffectiveAction ? undefined : props.testID}
+    >
+      {props.leading !== undefined ? (
+        <Leading slot={props.leading} danger={props.danger} />
+      ) : null}
       <View style={styles.body}>
-        {renderSlot(title, titleStyle, titleLines ?? 1)}
-        {renderSlot(desc, descStyle, 2)}
+        <Text style={titleStyle} numberOfLines={props.titleLines ?? 1}>
+          {stringifyCellText(props.title)}
+        </Text>
+        {props.desc !== undefined ? (
+          <Text style={descStyle} numberOfLines={2}>
+            {stringifyCellText(props.desc)}
+          </Text>
+        ) : null}
       </View>
-      {renderSlot(extra, extraStyle, 1)}
-      {arrow && !danger ? (
-        <Icon
-          name="chevron-right"
-          size={r(flush ? 18 : 20)}
-          color={c.foregroundSubtle}
+      <CellExtraContent extra={props.extra} textStyle={extraStyle} />
+      {hasEffectiveAction && props.arrow && !props.danger ? (
+        <View
+          {...A11Y_HIDDEN_PROPS}
           style={flush ? styles.chevronFlush : undefined}
-        />
+        >
+          <Icon
+            name="chevron-right"
+            size={r(flush ? 18 : 20)}
+            color={c.foregroundSubtle}
+          />
+        </View>
       ) : null}
     </View>
   );
 
-  if (onPress) {
-    // 若 extra 含交互控件(Switch/Stepper 等),外壳 Pressable 关闭 accessible,
-    // 让 SR 直接穿透读取控件本身,避免双播报和控件被遮挡无法激活的体验缺陷。
-    const hasInteractiveExtra = extraHasInteractiveNode(extra);
-
-    // 默认 a11y label:title + desc 拼接,给 SR 用户同时听到主副信息。
-    // 有 accessibilityLabel 显式覆盖时走 prop,否则组合 title+desc。
-    const defaultLabel =
-      typeof title === 'string'
-        ? typeof desc === 'string' && desc
-          ? `${title},${desc}`
-          : title
-        : undefined;
+  if (hasEffectiveAction) {
+    const isDisabled = props.disabled === true;
 
     return (
       <Pressable
-        onPress={onPress}
-        disabled={disabled}
+        onPress={isDisabled ? undefined : props.onPress}
+        disabled={isDisabled}
         accessibilityRole="button"
-        accessibilityLabel={accessibilityLabel ?? defaultLabel}
-        accessibilityHint={accessibilityHint}
-        accessibilityState={disabled ? { disabled: true } : undefined}
-        // extra 含控件时外壳不作为独立 a11y 元素,让 SR 穿透到 extra 控件
-        accessible={hasInteractiveExtra ? false : undefined}
-        testID={testID}
+        accessibilityLabel={accessibilityLabel}
+        accessibilityHint={props.accessibilityHint}
+        accessibilityState={{ disabled: isDisabled }}
+        testID={props.testID}
         style={({ pressed }) => [
-          { opacity: disabled ? 0.5 : pressed ? pressedOpacity : 1 },
+          { opacity: isDisabled ? 0.5 : pressed ? pressedOpacity : 1 },
         ]}
       >
         {inner}

package/src/components/ui/Cell/Leading.tsx

@@ -1,8 +1,9 @@
-import { type ReactNode } from 'react';
 import { StyleSheet, View } from 'react-native';
 import { r, useColors } from '../../../theme';
-import { Icon, type IconName } from '../Icon';
+import { Icon } from '../Icon';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
 import { useListVariant } from './context';
+import type { CellLeading } from './types';
 
 const FLUSH_BOX_SIZE = r(28);
 const FLUSH_BOX_RADIUS = r(7);
@@ -21,7 +22,7 @@ export function Leading({
   slot,
   danger,
 }: {
-  slot: IconName | ReactNode;
+  slot: CellLeading;
   danger?: boolean;
 }) {
   const c = useColors();
@@ -32,6 +33,7 @@ export function Leading({
     if (variant === 'flush') {
       return (
         <View
+          {...A11Y_HIDDEN_PROPS}
           style={[
             sharedStyles.flushBox,
             {
@@ -39,21 +41,19 @@ export function Leading({
             },
           ]}
         >
-          <Icon
-            name={slot as IconName}
-            size={r(16)}
-            color={danger ? c.error : c.primary}
-          />
+          <Icon name={slot} size={r(16)} color={danger ? c.error : c.primary} />
         </View>
       );
     }
     return (
-      <Icon
-        name={slot as IconName}
-        size={r(22)}
-        color={danger ? c.error : c.foregroundMuted}
-      />
+      <View {...A11Y_HIDDEN_PROPS}>
+        <Icon
+          name={slot}
+          size={r(22)}
+          color={danger ? c.error : c.foregroundMuted}
+        />
+      </View>
     );
   }
-  return <View>{slot}</View>;
+  return <View {...A11Y_HIDDEN_PROPS}>{slot.node}</View>;
 }

package/src/components/ui/Cell/content.ts

@@ -0,0 +1,53 @@
+import type { CellExtra, CellTextValue } from './types';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+
+type CellAccessibilityExtra = Exclude<CellExtra, { kind: 'control' }>;
+
+export function stringifyCellText(value: CellTextValue): string {
+  return String(value);
+}
+
+function appendNonBlank(parts: string[], value: string): void {
+  const normalized = normalizeNonBlankText(value);
+  if (normalized !== undefined) parts.push(normalized);
+}
+
+export function buildCellAccessibilityLabel({
+  title,
+  desc,
+  extra,
+}: {
+  title: CellTextValue;
+  desc?: CellTextValue;
+  extra?: CellAccessibilityExtra;
+}): string {
+  const parts: string[] = [];
+  appendNonBlank(parts, stringifyCellText(title));
+
+  if (desc !== undefined) {
+    appendNonBlank(parts, stringifyCellText(desc));
+  }
+
+  if (extra?.kind === 'text') {
+    appendNonBlank(parts, stringifyCellText(extra.value));
+  } else if (extra?.kind === 'display') {
+    appendNonBlank(parts, extra.accessibilityText ?? '');
+  }
+
+  return parts.join('，');
+}
+
+export function resolveCellActionAccessibilityLabel({
+  accessibilityLabel,
+  ...content
+}: {
+  accessibilityLabel?: unknown;
+  title: CellTextValue;
+  desc?: CellTextValue;
+  extra?: CellAccessibilityExtra;
+}): string | undefined {
+  return (
+    normalizeNonBlankText(accessibilityLabel) ??
+    normalizeNonBlankText(buildCellAccessibilityLabel(content))
+  );
+}

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

@@ -1,3 +1,9 @@
 export { Cell } from './Cell';
 export { List } from './List';
-export type { CellProps, ListProps } from './types';
+export type {
+  CellExtra,
+  CellLeading,
+  CellProps,
+  CellTextValue,
+  ListProps,
+} from './types';

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

@@ -1,44 +1,78 @@
-import type { ReactNode } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 import type { IconName } from '../Icon';
 
-export type CellProps = {
-  /** 标题（必填）；string 自动套 Text + numberOfLines=titleLines，传 ReactNode 完全自定义 */
-  title: ReactNode;
-  /** title 是 string 时的 numberOfLines（默认 1）。多行场景如新闻列表标题传 2。 */
+export type CellTextValue = string | number | bigint;
+
+export type CellLeading = IconName | { kind: 'display'; node: ReactElement };
+
+export type CellExtra =
+  | { kind: 'text'; value: CellTextValue }
+  | {
+      kind: 'display';
+      node: ReactElement;
+      accessibilityText?: string;
+    }
+  | { kind: 'control'; node: ReactElement };
+
+type ActionableExtra = Exclude<CellExtra, { kind: 'control' }>;
+type StaticExtra =
+  | Extract<CellExtra, { kind: 'text' }>
+  | {
+      kind: 'display';
+      node: ReactElement;
+      accessibilityText?: never;
+    };
+
+type SharedCellProps = {
+  /** 主标题由库内 Text 安全渲染。 */
+  title: CellTextValue;
+  /** 主标题的 numberOfLines（默认 1）。 */
   titleLines?: number;
-  /** 副标题；string 自动 numberOfLines=2，传 ReactNode 完全自定义 */
-  desc?: ReactNode;
-  /** 右侧 slot —— 字符串自动套 Text；传 ReactNode 放 Switch / Stepper / Tag 等控件。
-   *  **a11y 边界**：extra 为 ReactNode 时，外壳 Pressable 会关闭 `accessible`，
-   *  让 SR 直接穿透到 extra 控件（避免双播报）；extra 的 a11y 由其自身负责。
-   *  若 extra 是纯展示 ReactNode 且仍需外壳播报，请改用 string 或传 `accessibilityLabel`。 */
-  extra?: ReactNode;
-  /** 显示右侧 chevron-right 图标，常配合 onPress 表示「可进入下一级」 */
-  arrow?: boolean;
-  /** 前置 slot —— IconName 自动渲染 24×24 图标；传 ReactNode 放 Avatar / 自定义图形 */
-  leading?: IconName | ReactNode;
-  /** 点击回调 —— 不传则 cell 不可点（纯展示） */
-  onPress?: () => void;
-  /**
-   * 显式禁用：仅对带 onPress 的 cell 有效。
-   * disabled=true 时 onPress 不触发 + 整体半透明 + a11y disabled。
-   */
-  disabled?: boolean;
-  /** 危险态:icon 盒子 + 标题用 error 红色,且不渲染 arrow(常用于退出登录 / 删除等)。 */
+  /** 副标题由库内 Text 安全渲染。 */
+  desc?: CellTextValue;
+  /** 图标名或显式的纯展示前导节点。 */
+  leading?: CellLeading;
+  /** 危险态：icon 盒子与标题使用 error 色；action arrow 不显示。 */
   danger?: boolean;
-  /** 额外样式覆盖(合并到 cell 容器的 style 数组) */
+  /** 额外样式覆盖。 */
   style?: StyleProp<ViewStyle>;
-  /** E2E / 测试定位 */
+  /** E2E / 测试定位。 */
   testID?: string;
-  /** 显式 SR 朗读文案,覆盖 Cell 默认从 string title 推断的 fallback。
-   *  title 是 ReactNode(自定义渲染)时尤其需要,否则 SR 用户听不到任何内容。 */
+};
+
+type ActionableCellProps = {
+  onPress: () => void;
+  extra?: ActionableExtra;
+  arrow?: boolean;
+  disabled?: boolean;
+  /** 覆盖由 title、desc 与 extra 自动组合的 accessible name。 */
   accessibilityLabel?: string;
-  /** SR 朗读 hint —— 说明 tap 后行为(短 ≤8 字)。
-   *  常用:"查看详情" / "打开应用" 等;onPress 缺省时此 prop 无意义。 */
+  /** SR 操作结果说明。 */
   accessibilityHint?: string;
 };
 
+type ControlCellProps = {
+  extra: Extract<CellExtra, { kind: 'control' }>;
+  onPress?: never;
+  arrow?: never;
+  disabled?: never;
+  accessibilityLabel?: never;
+  accessibilityHint?: never;
+};
+
+type StaticCellProps = {
+  extra?: StaticExtra;
+  onPress?: never;
+  arrow?: never;
+  disabled?: never;
+  accessibilityLabel?: never;
+  accessibilityHint?: never;
+};
+
+export type CellProps = SharedCellProps &
+  (ActionableCellProps | ControlCellProps | StaticCellProps);
+
 export type ListProps = {
   /** 一组 Cell */
   children: ReactNode;

package/src/components/ui/Checkbox/Checkbox.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
 import {
@@ -8,10 +8,15 @@ import {
   useColors,
   useThemedStyles,
 } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
 import { Icon } from '../Icon';
 import { makeStyles } from './styles';
 import type { CheckboxProps } from './types';
 
+const log = createLogger('Checkbox');
+
 /**
  * 多选复选框。20×20 盒子。
  * 关：透明背景 + 细线边框。
@@ -23,28 +28,46 @@ export function Checkbox({
   checked,
   onChange,
   label,
+  accessibilityLabel,
   shape = 'square',
   disabled,
   testID,
 }: CheckboxProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
+  const accessibleName =
+    normalizeNonBlankText(accessibilityLabel) ?? normalizeNonBlankText(label);
+  const hasMissingName = accessibleName === undefined;
+  const isDisabled = disabled === true || hasMissingName;
+
+  useEffect(() => {
+    if (hasMissingName) {
+      log.warn(
+        'Checkbox 需要非空的 accessibilityLabel 或可见 label，当前 action 已禁用。'
+      );
+    }
+  }, [hasMissingName]);
+
   return (
     <Pressable
-      onPress={() => !disabled && onChange(!checked)}
-      disabled={disabled}
+      accessible={!hasMissingName}
+      onPress={isDisabled ? undefined : () => onChange(!checked)}
+      disabled={isDisabled}
       // [M-7] box 20pt → 垂直补 (44-20)/2=12 到 fixed.hitTarget
       hitSlop={Math.round((fixed.hitTarget - r(20)) / 2)}
-      accessibilityRole="checkbox"
-      accessibilityState={{ checked, disabled: !!disabled }}
-      accessibilityLabel={label}
+      accessibilityRole={hasMissingName ? undefined : 'checkbox'}
+      accessibilityState={
+        hasMissingName ? undefined : { checked, disabled: isDisabled }
+      }
+      accessibilityLabel={accessibleName}
       testID={testID}
       style={({ pressed }) => [
         styles.row,
-        { opacity: disabled ? 0.5 : pressed ? pressedOpacity : 1 },
+        { opacity: isDisabled ? 0.5 : pressed ? pressedOpacity : 1 },
       ]}
     >
       <View
+        {...A11Y_HIDDEN_PROPS}
         style={[
           styles.box,
           // [L-79] circle 形态改用 radius.pill —— sentinel 999 确保任何尺寸下都是真圆
@@ -64,7 +87,11 @@ export function Checkbox({
           style={checked ? undefined : styles.tickHidden}
         />
       </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/Checkbox/types.ts

@@ -1,10 +1,20 @@
-export type CheckboxProps = {
+type AccessibleName =
+  | {
+      /** 可见旁标同时提供 accessible name；可显式覆盖读屏文案 */
+      label: string;
+      accessibilityLabel?: string;
+    }
+  | {
+      /** 无可见旁标时必须显式提供 accessible name */
+      label?: never;
+      accessibilityLabel: string;
+    };
+
+type CheckboxBehaviorProps = {
   /** 当前选中状态（受控） */
   checked: boolean;
   /** 状态变化回调，传入新的 checked 值 */
   onChange: (checked: boolean) => void;
-  /** 旁标文字（不传则只渲染勾选方框） */
-  label?: string;
   /** 形状,默认方形;'circle' 用于需要强调的必勾项(如协议同意) */
   shape?: 'square' | 'circle';
   /** 禁用 */
@@ -12,3 +22,5 @@ export type CheckboxProps = {
   /** E2E / 测试定位 */
   testID?: string;
 };
+
+export type CheckboxProps = CheckboxBehaviorProps & AccessibleName;