@unif/react-native-design 0.20.0 → 0.21.0

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;

package/src/components/ui/Confirm/ConfirmHost.tsx

@@ -11,20 +11,24 @@ import {
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { space, useThemedStyles } from '../../../theme';
 import { Button } from '../Button';
-import { _subs } from './confirm';
+import { registerConfirmHost, settleConfirm } from './confirm';
+import { resolveConfirmLabels } from './labels';
 import { makeStyles } from './styles';
-import type { ConfirmEntry, Subscriber } from './types';
+import type { ConfirmEntry, ConfirmEvent } from './store';
 
 /** 遮罩淡入 / 淡出时长(ms)—— 出场略长于入场,与 Modal slide 退场(~300ms)大致同步收完。 */
 const SCRIM_IN_MS = 220;
 const SCRIM_OUT_MS = 260;
 
 /**
- * Confirm 对话框宿主 —— App 根挂一次,监听 `confirm()` 调用并渲染。
+ * Confirm 对话框宿主 —— App 根挂**一次**,监听 `confirm()` 调用并渲染。
  *
  * 原生 RN `Modal`(transparent + animationType slide)从底部滑入,backdrop 点击
- * 取消、内层 sheet 拦截点击不冒泡。**不依赖 @gorhom**(0.6.0 去 @gorhom 后改为
- * 纯 RN Modal + pub/sub 实现)。
+ * 取消、内层 sheet 拦截点击不冒泡。**不依赖 @gorhom**。
+ *
+ * 唯一 owner:重复挂载的实例拿到 `null` lease,永久惰性、不渲染 —— 不会出现两个
+ * Host 争抢同一个对话框。所有关闭路径统一走 `settleConfirm(entry, result)`,
+ * 组件内不直接调用 entry 的 resolver。
  */
 export function ConfirmHost(): React.JSX.Element | null {
   const styles = useThemedStyles(makeStyles);
@@ -32,36 +36,55 @@ export function ConfirmHost(): React.JSX.Element | null {
   const { height: screenH } = useWindowDimensions();
   const [entry, setEntry] = useState<ConfirmEntry | null>(null);
 
-  // 跟踪当前未决 entry,供 unmount cleanup resolve(false)。
+  // 同步权威副本:effect cleanup 与迟到回调都读它,不受 React state 批处理延迟影响。
   const pendingRef = useRef<ConfirmEntry | null>(null);
-  pendingRef.current = entry;
+
+  // 注册失败(已有 owner)时保持惰性:不订阅、不渲染。
+  const [inert, setInert] = useState(false);
 
   // 保留最后一次显示的 entry:关闭时 entry 立即置 null,但 slide 退场动画期 Modal 仍可见,
   // 渲染 lastEntry 才不会滑出一个只剩 padding 的空 sheet([M-17])。
   const lastEntryRef = useRef<ConfirmEntry | null>(null);
   if (entry) lastEntryRef.current = entry;
   const display = entry ?? lastEntryRef.current;
+  const labels = resolveConfirmLabels({
+    confirmLabel: display?.options.confirmLabel,
+    cancelLabel: display?.options.cancelLabel,
+  });
 
   useEffect(() => {
-    // [L-101] Subscriber 不再接收 null —— 收到新 entry 即显示;关闭路径由 resolve() 驱动
-    const sub: Subscriber = (next) => setEntry(next);
-    _subs.add(sub);
+    const subscriber = (event: ConfirmEvent) => {
+      // 先写同步 ref 再置 React state —— cleanup 与迟到回调依赖 ref 的即时正确性。
+      if (event.type === 'show') {
+        pendingRef.current = event.entry;
+        setEntry(event.entry);
+        return;
+      }
+      if (pendingRef.current?.id === event.id) {
+        pendingRef.current = null;
+        setEntry((current) => (current?.id === event.id ? null : current));
+      }
+    };
+    const lease = registerConfirmHost(subscriber);
+    if (!lease) {
+      setInert(true);
+      return;
+    }
     return () => {
-      _subs.delete(sub);
-      // Host 卸载时若对话框仍未决(error boundary 重置 / 根 re-key 切语言主题等),
-      // resolve(false) —— 否则 confirm() 的 Promise 永久悬挂、_activeEntry 锁死([H-5])。
-      pendingRef.current?.resolve(false);
+      // 卸载时若对话框仍未决(error boundary 重置 / 根 re-key 切语言主题等),
+      // Store 把它 settle(false) —— 否则 confirm() 的 Promise 永久悬挂并锁死单例([H-5])。
+      const held = pendingRef.current;
+      pendingRef.current = null;
+      lease.release(held);
     };
   }, []);
 
   const handleConfirm = useCallback(() => {
-    entry?.resolve(true);
-    setEntry(null);
+    if (entry) settleConfirm(entry, true);
   }, [entry]);
 
   const handleCancel = useCallback(() => {
-    entry?.resolve(false);
-    setEntry(null);
+    if (entry) settleConfirm(entry, false);
   }, [entry]);
 
   // 遮罩自持淡入 / 淡出(不蹭 Modal 的位移动画,理由见下方 scrim 注释)。退场也要淡:
@@ -76,6 +99,8 @@ export function ConfirmHost(): React.JSX.Element | null {
     }).start();
   }, [entry, scrimOpacity]);
 
+  if (inert) return null;
+
   return (
     <Modal
       visible={!!entry}
@@ -113,25 +138,25 @@ export function ConfirmHost(): React.JSX.Element | null {
             <>
               <View style={styles.body}>
                 <Text style={styles.title} accessibilityRole="header">
-                  {display.title}
+                  {display.options.title}
                 </Text>
-                {display.message ? (
-                  <Text style={styles.message}>{display.message}</Text>
+                {display.options.message ? (
+                  <Text style={styles.message}>{display.options.message}</Text>
                 ) : null}
               </View>
               <View style={styles.actions}>
                 <Button
                   testID="confirm-cancel"
-                  label={display.cancelLabel ?? '取消'}
+                  label={labels.cancelLabel}
                   variant="secondary"
-                  block
+                  style={styles.action}
                   onPress={handleCancel}
                 />
                 <Button
                   testID="confirm-ok"
-                  label={display.confirmLabel ?? '确认'}
-                  variant={display.destructive ? 'danger' : 'primary'}
-                  block
+                  label={labels.confirmLabel}
+                  variant={display.options.destructive ? 'danger' : 'primary'}
+                  style={styles.action}
                   onPress={handleConfirm}
                 />
               </View>

package/src/components/ui/Confirm/confirm.ts

@@ -4,21 +4,24 @@
  * 业务任意位置 `const ok = await confirm({title, message, ...})`,
  * 不用维护 useState / open / onClose。
  *
- * 同一时间只允许 1 个 confirm 活跃;若已有正在显示,新请求立即 resolve(false) 并 warn。
+ * 状态机全部在 `store.ts`(纯逻辑、可单测);本文件只持有唯一的模块级实例,
+ * 并把内部入口暴露给 `ConfirmHost.tsx`。这两个内部导出**不进公共 barrel**。
  */
 import { createLogger } from '../../../utils/logger';
-import type { ConfirmOptions, ConfirmEntry, Subscriber } from './types';
+import { createConfirmStore } from './store';
+import type { ConfirmOptions } from './types';
 
 const log = createLogger('confirm');
 
-let _id = 0;
-let _activeEntry: ConfirmEntry | null = null;
-export const _subs = new Set<Subscriber>();
+const store = createConfirmStore(log);
 
 /**
  * 弹出确认对话框,返回 Promise<boolean>。
  * - 用户点确认 → resolve(true)
- * - 用户点取消 / 点 backdrop / 拖关闭 → resolve(false)
+ * - 用户点取消 / 点 backdrop / 系统返回 → resolve(false)
+ * - 未挂 `<ConfirmHost />`、已有对话框在显示、Host 渲染抛错、Host 卸载 → resolve(false)
+ *
+ * 任何路径都必然 settle,不会悬挂。
  *
  * 示例:
  * ```ts
@@ -31,31 +34,11 @@ export const _subs = new Set<Subscriber>();
  * if (ok) doLogout();
  * ```
  */
-export function confirm(options: ConfirmOptions): Promise<boolean> {
-  if (_activeEntry) {
-    log.warn(
-      'confirm() 已有一个对话框在显示,新请求被拒绝(同一时间只 1 个,避免叠加)。'
-    );
-    return Promise.resolve(false);
-  }
-  // 没有 ConfirmHost 订阅 → entry 无人接收,Promise 会永久悬挂、调用方 await 卡死。
-  // 立即 resolve(false) 并告警,且不占 _activeEntry(否则后续 confirm 全被重入分支锁死)。
-  if (_subs.size === 0) {
-    log.warn(
-      'confirm() 调用时未挂载 <ConfirmHost />,对话框无法显示,已 resolve(false)。请在 app 根附近挂一次 <ConfirmHost />。'
-    );
-    return Promise.resolve(false);
-  }
-  return new Promise<boolean>((resolve) => {
-    const entry: ConfirmEntry = {
-      id: ++_id,
-      ...options,
-      resolve: (confirmed: boolean) => {
-        _activeEntry = null;
-        resolve(confirmed);
-      },
-    };
-    _activeEntry = entry;
-    _subs.forEach((s) => s(entry));
-  });
-}
+export const confirm = (options: ConfirmOptions): Promise<boolean> =>
+  store.request(options);
+
+/** 内部:ConfirmHost 挂载时注册唯一 owner;重复挂载得到 null。 */
+export const registerConfirmHost = store.registerHost;
+
+/** 内部:所有关闭路径的唯一出口(identity-guarded + 幂等)。 */
+export const settleConfirm = store.settle;

package/src/components/ui/Confirm/labels.ts

@@ -0,0 +1,14 @@
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+import type { ConfirmOptions } from './types';
+
+export function resolveConfirmLabels(
+  options: Pick<ConfirmOptions, 'confirmLabel' | 'cancelLabel'>
+): {
+  confirmLabel: string;
+  cancelLabel: string;
+} {
+  return {
+    confirmLabel: normalizeNonBlankText(options.confirmLabel) ?? '确认',
+    cancelLabel: normalizeNonBlankText(options.cancelLabel) ?? '取消',
+  };
+}