@unif/react-native-design 0.20.0 → 0.21.1

package/src/components/ui/NavBar/NavBar.tsx

@@ -1,38 +1,35 @@
-import React from 'react';
+import React, { useEffect, useRef } from 'react';
 import { Text, View } from 'react-native';
 import { useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
 import { IconButton } from '../IconButton';
-import { isSlot } from './isSlot';
+import { classifyNavBarSlot, type NavBarSlotClassification } from './isSlot';
 import { makeStyles } from './styles';
-import type { NavBarProps, NavBarSlotConfig } from './types';
+import type { NavBarAction, NavBarProps } from './types';
 
-/** NavBarSlotConfig → IconButton(variant='ghost' + 外部 tint)。 */
-function renderSlot(slot: NavBarSlotConfig, tint: string) {
-  // [L-50] 缺 accessibilityLabel 时 dev 告警 —— 回退读英文 icon 名(如 "menu")体验不佳。
-  if (!slot.accessibilityLabel && typeof __DEV__ !== 'undefined' && __DEV__) {
-    console.warn(
-      `NavBar slot(icon="${slot.icon}")未传 accessibilityLabel,SR 将读出 icon 名,请传人类可读短语。`
-    );
-  }
+const log = createLogger('NavBar');
+
+/** NavBarAction → IconButton(variant='ghost' + 外部 tint)。 */
+function renderSlot(slot: NavBarAction, tint: string) {
   return (
     <IconButton
       icon={slot.icon}
       onPress={slot.onPress}
       variant="ghost"
       color={tint}
-      accessibilityLabel={slot.accessibilityLabel ?? slot.icon}
+      accessibilityLabel={slot.accessibilityLabel}
     />
   );
 }
 
-/** left / right slot:NavBarSlotConfig → IconButton,ReactNode → 原样。 */
+/** left / right slot:NavBarAction → IconButton,已归一化 display node → 原样。 */
 function resolveSlot(
-  slot: NavBarProps['left'] | NavBarProps['right'],
+  slot: NavBarSlotClassification,
   tint: string
 ): React.ReactNode {
-  if (!slot) return null;
-  if (isSlot(slot)) return renderSlot(slot, tint);
-  return slot;
+  if (slot.kind === 'action') return renderSlot(slot.action, tint);
+  if (slot.kind === 'node') return slot.node;
+  return null;
 }
 
 /**
@@ -55,6 +52,17 @@ export function NavBar({
   const styles = useThemedStyles(makeStyles);
   const isBrand = variant === 'brand';
   const isTransparent = variant === 'transparent';
+  const leftSlot = classifyNavBarSlot(left);
+  const rightSlot = classifyNavBarSlot(right);
+  const warnedInvalidSlot = useRef(false);
+  const hasInvalidSlot =
+    leftSlot.kind === 'invalid' || rightSlot.kind === 'invalid';
+  useEffect(() => {
+    if (hasInvalidSlot && !warnedInvalidSlot.current) {
+      warnedInvalidSlot.current = true;
+      log.warn('忽略无效的 NavBar action；请传 NavBarAction 或 ReactNode');
+    }
+  }, [hasInvalidSlot]);
   // brand 实底白字;default + transparent 都走深字(transparent 用在浅色
   // hero 渐变之上,白字看不清)。后续若有"相机 / 地图"等深色浮层场景需要
   // 白字 transparent navbar,再加 'transparentLight' variant。
@@ -70,7 +78,7 @@ export function NavBar({
       ]}
       testID={testID}
     >
-      <View style={styles.side}>{resolveSlot(left, tint)}</View>
+      <View style={styles.side}>{resolveSlot(leftSlot, tint)}</View>
       <View style={styles.center}>
         <Text style={[styles.title, { color: tint }]} numberOfLines={1}>
           {title}
@@ -82,7 +90,7 @@ export function NavBar({
         ) : null}
       </View>
       <View style={[styles.side, styles.sideRight]}>
-        {resolveSlot(right, tint)}
+        {resolveSlot(rightSlot, tint)}
       </View>
     </View>
   );

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

@@ -1,2 +1,2 @@
 export { NavBar } from './NavBar';
-export type { NavBarProps, NavBarSlotConfig } from './types';
+export type { NavBarAction, NavBarProps, NavBarSlot } from './types';

package/src/components/ui/NavBar/isSlot.ts

@@ -1,9 +1,376 @@
-import type { NavBarSlotConfig } from './types';
+import React, { type ReactNode } from 'react';
+import { Text } from 'react-native';
+import { ICONS, type IconName } from '../../../icons';
+import type { NavBarAction } from './types';
+
+export type NavBarSlotClassification =
+  | { kind: 'empty' }
+  | { kind: 'action'; action: NavBarAction }
+  | { kind: 'node'; node: ReactNode }
+  | { kind: 'invalid' };
+
+type NormalizedNode = { kind: 'node'; node: ReactNode } | { kind: 'invalid' };
+
+type IteratorFactoryResult =
+  | { kind: 'none' }
+  | { kind: 'factory'; factory: () => unknown }
+  | { kind: 'invalid' };
+
+type ThenableResolutionRecord = {
+  node: ReactNode;
+  dependencies: Set<ThenableResolutionRecord>;
+};
+
+const mappedThenables = new WeakMap<object, ThenableResolutionRecord>();
+
+function isIconName(value: unknown): value is IconName {
+  return (
+    typeof value === 'string' &&
+    Object.prototype.hasOwnProperty.call(ICONS, value)
+  );
+}
+
+/**
+ * Type guard：action 的 icon 必须真实存在于生成的 registry，且有 handler 与非空名称。
+ */
+export function isNavBarAction(v: unknown): v is NavBarAction {
+  if (typeof v !== 'object' || v === null) return false;
+  const slot = v as Record<string, unknown>;
+  return (
+    isIconName(slot.icon) &&
+    typeof slot.onPress === 'function' &&
+    typeof slot.accessibilityLabel === 'string' &&
+    slot.accessibilityLabel.trim().length > 0
+  );
+}
+
+function hasElementShape(value: React.ReactElement): boolean {
+  const element = value as unknown as { type: unknown; props: unknown };
+  return (
+    Object.prototype.hasOwnProperty.call(value, 'type') &&
+    Object.prototype.hasOwnProperty.call(value, 'props') &&
+    element.type !== null &&
+    element.type !== undefined &&
+    typeof element.props === 'object' &&
+    element.props !== null
+  );
+}
+
+function isThenable(value: unknown): value is ReactNode {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  try {
+    return typeof (value as { then?: unknown }).then === 'function';
+  } catch {
+    return false;
+  }
+}
+
+function normalizeFragment(
+  value: React.ReactElement,
+  activeIterables: WeakSet<object>,
+  path: string,
+  owner?: ThenableResolutionRecord
+): NormalizedNode {
+  try {
+    const props = value.props as { children?: unknown };
+    const normalized = normalizeReactNode(
+      props.children,
+      activeIterables,
+      `${path}.fragment`,
+      owner
+    );
+    if (normalized.kind === 'invalid') return normalized;
+    return {
+      kind: 'node',
+      node: React.cloneElement(value, undefined, normalized.node),
+    };
+  } catch {
+    return { kind: 'invalid' };
+  }
+}
+
+function recordReaches(
+  from: ThenableResolutionRecord,
+  target: ThenableResolutionRecord,
+  visited = new Set<ThenableResolutionRecord>()
+): boolean {
+  if (from === target) return true;
+  if (visited.has(from)) return false;
+  visited.add(from);
+  for (const dependency of from.dependencies) {
+    if (recordReaches(dependency, target, visited)) return true;
+  }
+  return false;
+}
+
+function addThenableDependency(
+  owner: ThenableResolutionRecord,
+  dependency: ThenableResolutionRecord
+): boolean {
+  // dependency 已能走回 owner 时再加边会闭环；不加边并让当前 resolution 失败关闭。
+  if (recordReaches(dependency, owner)) return false;
+  owner.dependencies.add(dependency);
+  return true;
+}
+
+function createThenableRecord(
+  value: object,
+  path: string
+): ThenableResolutionRecord {
+  let resolveMapped: (node: unknown) => void = () => {};
+  let rejectMapped: (reason?: unknown) => void = () => {};
+  const mappedPromise = new Promise<unknown>((resolve, reject) => {
+    resolveMapped = resolve;
+    rejectMapped = reject;
+  });
+  const mappedNode = mappedPromise as ReactNode;
+  const record: ThenableResolutionRecord = {
+    node: mappedNode,
+    dependencies: new Set(),
+  };
+  // 先入 cache 再调用用户 then：同步 thenable 可复用同一 record，并由依赖图识别闭环。
+  mappedThenables.set(value, record);
+
+  let claimed = false;
+  const resolveOnce = (resolved: unknown) => {
+    if (claimed) return;
+    claimed = true;
+    if (resolved === value || resolved === mappedPromise) {
+      resolveMapped(null);
+      return;
+    }
+    try {
+      const normalized = normalizeReactNode(
+        resolved,
+        new WeakSet<object>(),
+        `${path}.then`,
+        record
+      );
+      resolveMapped(normalized.kind === 'invalid' ? null : normalized.node);
+    } catch {
+      resolveMapped(null);
+    }
+  };
+  const rejectOnce = (reason: unknown) => {
+    if (claimed) return;
+    claimed = true;
+    rejectMapped(reason);
+  };
+
+  try {
+    const then = (value as { then?: unknown }).then;
+    if (typeof then !== 'function') {
+      resolveOnce(null);
+      return record;
+    }
+    then.call(value, resolveOnce, rejectOnce);
+  } catch (error) {
+    rejectOnce(error);
+  }
+
+  return record;
+}
+
+function normalizeThenable(
+  value: object,
+  path: string,
+  owner?: ThenableResolutionRecord
+): NormalizedNode {
+  const record =
+    mappedThenables.get(value) ?? createThenableRecord(value, path);
+  if (owner !== undefined && !addThenableDependency(owner, record)) {
+    return { kind: 'invalid' };
+  }
+  return { kind: 'node', node: record.node };
+}
+
+function getIteratorFactory(value: object): IteratorFactoryResult {
+  try {
+    const iterator = (value as { [Symbol.iterator]?: unknown })[
+      Symbol.iterator
+    ];
+    if (iterator === undefined || iterator === null) return { kind: 'none' };
+    if (typeof iterator !== 'function') return { kind: 'none' };
+    return { kind: 'factory', factory: iterator as () => unknown };
+  } catch {
+    return { kind: 'invalid' };
+  }
+}
+
+function isReactPortal(value: object): value is React.ReactPortal {
+  const portal = value as {
+    key?: unknown;
+    containerInfo?: unknown;
+  };
+  const hasPortalShape =
+    Object.prototype.hasOwnProperty.call(value, 'key') &&
+    Object.prototype.hasOwnProperty.call(value, 'children') &&
+    Object.prototype.hasOwnProperty.call(value, 'containerInfo') &&
+    Object.prototype.hasOwnProperty.call(value, 'implementation') &&
+    (portal.key === null || typeof portal.key === 'string') &&
+    portal.containerInfo !== null &&
+    portal.containerInfo !== undefined;
+  if (!hasPortalShape) return false;
+  try {
+    // React 没有公开 portal guard；只调用公开 Children API，且该分支已排除 iterable/
+    // thenable，避免消费 generator 或改变 Promise 语义。
+    return React.Children.count(value as ReactNode) === 1;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeArray(
+  value: unknown[],
+  activeIterables: WeakSet<object>,
+  path: string,
+  owner?: ThenableResolutionRecord
+): NormalizedNode {
+  if (activeIterables.has(value)) return { kind: 'invalid' };
+  activeIterables.add(value);
+  try {
+    const nodes: ReactNode[] = [];
+    for (let index = 0; index < value.length; index += 1) {
+      const normalized = normalizeReactNode(
+        value[index],
+        activeIterables,
+        `${path}.${index}`,
+        owner
+      );
+      if (normalized.kind === 'invalid') return normalized;
+      nodes.push(normalized.node);
+    }
+    return { kind: 'node', node: nodes };
+  } catch {
+    return { kind: 'invalid' };
+  } finally {
+    activeIterables.delete(value);
+  }
+}
+
+function normalizeIterable(
+  value: object,
+  factory: () => unknown,
+  activeIterables: WeakSet<object>,
+  path: string,
+  owner?: ThenableResolutionRecord
+): NormalizedNode {
+  if (activeIterables.has(value)) return { kind: 'invalid' };
+  activeIterables.add(value);
+  let iterator: object | undefined;
+  let completed = false;
+  try {
+    const candidate = factory.call(value);
+    if (typeof candidate !== 'object' || candidate === null) {
+      return { kind: 'invalid' };
+    }
+    iterator = candidate;
+    const next = (iterator as { next?: unknown }).next;
+    if (typeof next !== 'function') return { kind: 'invalid' };
+
+    const nodes: ReactNode[] = [];
+    let index = 0;
+    for (;;) {
+      const step = next.call(iterator);
+      if (typeof step !== 'object' || step === null) {
+        return { kind: 'invalid' };
+      }
+      const result = step as { done?: unknown; value?: unknown };
+      // Iterator protocol 的 done 走 ToBoolean，而不是限制为 boolean primitive。
+      if (result.done) {
+        completed = true;
+        return { kind: 'node', node: nodes };
+      }
+
+      const normalized = normalizeReactNode(
+        result.value,
+        activeIterables,
+        `${path}.${index}`,
+        owner
+      );
+      if (normalized.kind === 'invalid') return normalized;
+      nodes.push(normalized.node);
+      index += 1;
+    }
+  } catch {
+    return { kind: 'invalid' };
+  } finally {
+    if (!completed && iterator !== undefined) {
+      try {
+        const close = (iterator as { return?: unknown }).return;
+        if (typeof close === 'function') close.call(iterator);
+      } catch {
+        // 分类已失败；关闭时的异常不能逃逸到 NavBar render。
+      }
+    }
+    activeIterables.delete(value);
+  }
+}
+
+function normalizeReactNode(
+  value: unknown,
+  activeIterables: WeakSet<object>,
+  path: string,
+  owner?: ThenableResolutionRecord
+): NormalizedNode {
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'bigint'
+  ) {
+    return {
+      kind: 'node',
+      node: React.createElement(Text, { key: path }, String(value)),
+    };
+  }
+  if (value === undefined || value === null || typeof value === 'boolean') {
+    return { kind: 'node', node: value };
+  }
+  if (React.isValidElement(value)) {
+    if (!hasElementShape(value)) return { kind: 'invalid' };
+    return value.type === React.Fragment
+      ? normalizeFragment(value, activeIterables, path, owner)
+      : { kind: 'node', node: value };
+  }
+  if (typeof value !== 'object' || value === null) {
+    return { kind: 'invalid' };
+  }
+  if (Array.isArray(value)) {
+    return normalizeArray(value, activeIterables, path, owner);
+  }
+
+  const iterator = getIteratorFactory(value);
+  if (iterator.kind === 'invalid') return iterator;
+  if (iterator.kind === 'factory') {
+    return normalizeIterable(
+      value,
+      iterator.factory,
+      activeIterables,
+      path,
+      owner
+    );
+  }
+  if (isThenable(value)) return normalizeThenable(value, path, owner);
+  if (typeof value !== 'object') return { kind: 'invalid' };
+  return isReactPortal(value)
+    ? { kind: 'node', node: value }
+    : { kind: 'invalid' };
+}
 
 /**
- * Type guard：判断 left/right 是否为 NavBarSlotConfig 对象（含 icon 字段）。
- * 不是的话视为 ReactNode 自定义内容。
+ * 未类型化边界的单一分类器。React 的公开 API 无法证明 object 不可伪造；这里拒绝
+ * 结构不成立的 marker-only element 与普通 plain object，同时保留 React 19 声明的
+ * bigint、Iterable、portal、Promise/thenable 等合法 ReactNode。Fragment/Iterable
+ * 会递归验证 primitive 叶子；thenable 映射按源对象缓存，避免每次 render 制造新的
+ * suspend identity；resolution record 的依赖可达性同时拦截 direct/indirect cycle，
+ * 并把 cycle 或非法 resolved value 确定性失败关闭为 null。
  */
-export function isSlot(v: unknown): v is NavBarSlotConfig {
-  return typeof v === 'object' && v !== null && 'icon' in v;
+export function classifyNavBarSlot(value: unknown): NavBarSlotClassification {
+  if (value === undefined || value === null || typeof value === 'boolean') {
+    return { kind: 'empty' };
+  }
+  if (isNavBarAction(value)) return { kind: 'action', action: value };
+  return normalizeReactNode(value, new WeakSet<object>(), 'slot');
 }

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

@@ -2,23 +2,24 @@ import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 import type { IconName } from '../Icon';
 
-export type NavBarSlotConfig = {
+export type NavBarAction = {
   icon: IconName;
-  onPress?: () => void;
-  /** 屏幕阅读器读出的功能描述。强烈建议传 —— icon-only 按钮无文字,缺省时 SR 回退
-   *  读英文 icon 名(如 "menu")且 dev 下告警。请传人类可读短语(如「返回」「更多」)。 */
-  accessibilityLabel?: string;
+  onPress: () => void;
+  /** 屏幕阅读器读出的非空功能描述。 */
+  accessibilityLabel: string;
 };
 
+export type NavBarSlot = NavBarAction | ReactNode;
+
 export type NavBarProps = {
   /** 主标题 */
   title: string;
   /** 副标题（可选，主标题下方一行） */
   subtitle?: string;
-  /** 左侧槽位：传 NavBarSlotConfig 自动用 IconButton 渲染 / 传 ReactNode 自定义 */
-  left?: ReactNode | NavBarSlotConfig;
+  /** 左侧槽位：传 NavBarAction 自动用 IconButton 渲染 / 传 ReactNode 自定义 */
+  left?: NavBarSlot;
   /** 右侧槽位：同 left */
-  right?: ReactNode | NavBarSlotConfig;
+  right?: NavBarSlot;
   /**
    * 视觉变体，默认 'default'：
    * - `default`：白底 + hairline 底边

package/src/components/ui/PasswordInput/PasswordInput.tsx

@@ -1,81 +1,79 @@
-import React, { forwardRef, useState } from 'react';
-import { Pressable } from 'react-native-gesture-handler';
-import { Icon } from '../Icon';
+import React, { forwardRef, useEffect, useState } from 'react';
 import { Input } from '../Input';
-import { control, fixed, r, useColors } from '../../../theme';
-import { childTestID } from '../../../utils/testID';
-import { styles } from './styles';
-import type { TextInputRef } from '../TextField/TextFieldBase';
+import type { TextFieldHandle, TextFieldSlot } from '../TextField/types';
+import { createLogger } from '../../../utils/logger';
 import type { PasswordInputProps } from './types';
 
-/**
- * 密码 Input —— Input + leading lock + trailing eye 切换明文 / 密文。
- *
- * [L-32] 增强:
- * - forwardRef<TextInput> —— 业务表单 focus() 聚焦
- * - inputProps 类型改为 Omit<TextInputProps,'secureTextEntry'>
- * - 补 textContentType='password' / autoComplete='current-password' / autoCapitalize='none' 默认值
- * - 暴露 error / disabled 透传给底层 Input
- *
- * showPw 内部 useState,caller 只关心 value/onChangeText。
- * a11y:label 已表达"显示/隐藏密码"意图,不再加 accessibilityHint(避免 SR 朗读 over-hint)。
- */
-export const PasswordInput = forwardRef<TextInputRef, PasswordInputProps>(
-  function PasswordInput(
-    {
-      value,
-      onChangeText,
-      placeholder = '请输入密码',
-      testID,
-      error,
-      disabled,
-      inputProps,
-    },
-    ref
-  ): React.JSX.Element {
-    const c = useColors();
-    const [showPw, setShowPw] = useState(false);
+const log = createLogger('PasswordInput');
+
+/** 密码输入:只切换 secureTextEntry,不改变调用方持有的受控文本或焦点。 */
+export const PasswordInput = forwardRef<TextFieldHandle, PasswordInputProps>(
+  function PasswordInput(props, ref): React.JSX.Element {
+    const {
+      textContentType: rawTextContentType,
+      autoComplete: rawAutoComplete,
+      autoCapitalize: rawAutoCapitalize,
+      value: rawValue,
+      onChangeText: rawOnChangeText,
+      disabled: rawDisabled,
+      editable: rawEditable,
+      placeholder: rawPlaceholder,
+      defaultValue: _defaultValue,
+      inputProps: _inputProps,
+      secureTextEntry: _secureTextEntry,
+      leading: _leading,
+      trailing: _trailing,
+      ...rest
+    } = props as PasswordInputProps & Record<string, unknown>;
+    const value = typeof rawValue === 'string' ? rawValue : '';
+    const onChangeText =
+      typeof rawOnChangeText === 'function'
+        ? (rawOnChangeText as (next: string) => void)
+        : undefined;
+    const disabled = rawDisabled === true;
+    const editable = rawEditable === false ? false : undefined;
+    const placeholder =
+      typeof rawPlaceholder === 'string' ? rawPlaceholder : '请输入密码';
+    const removedNativeAliasKey = Object.entries({
+      defaultValue: _defaultValue,
+      inputProps: _inputProps,
+      secureTextEntry: _secureTextEntry,
+      leading: _leading,
+      trailing: _trailing,
+    })
+      .filter(([, entry]) => entry !== undefined)
+      .map(([name]) => name)
+      .join(',');
+    useEffect(() => {
+      if (removedNativeAliasKey.length > 0) {
+        log.warn(`已忽略 PasswordInput 自管 props(${removedNativeAliasKey})。`);
+      }
+    }, [removedNativeAliasKey]);
+    const [showPassword, setShowPassword] = useState(false);
+    const effectiveEditable = disabled !== true && editable !== false;
+    const trailing: TextFieldSlot = {
+      kind: 'action',
+      icon: showPassword ? 'eye' : 'eye-off',
+      onPress: () => setShowPassword((visible) => !visible),
+      accessibilityLabel: showPassword ? '隐藏密码' : '显示密码',
+      disabled: !effectiveEditable,
+    };
 
     return (
       <Input
         ref={ref}
-        testID={testID}
+        {...(rest as PasswordInputProps)}
         value={value}
-        onChangeText={onChangeText}
-        placeholder={placeholder}
-        error={error}
+        onChangeText={onChangeText as (next: string) => void}
         disabled={disabled}
-        // [L-32] 补 textContentType / autoComplete / autoCapitalize 默认值 —— 提升密码自动填充体验
-        textContentType="password"
-        autoComplete="current-password"
-        autoCapitalize="none"
-        {...inputProps}
-        // secureTextEntry 在 inputProps spread 之后覆盖,确保组件自管不被 caller 干扰
-        secureTextEntry={!showPw}
-        leading={<Icon name="lock" size={r(18)} color={c.iconFaint40} />}
-        trailing={
-          <Pressable
-            testID={childTestID(testID, 'toggle')}
-            style={styles.eyeBtn}
-            onPress={() => setShowPw((v) => !v)}
-            accessibilityRole="button"
-            accessibilityLabel={showPw ? '隐藏密码' : '显示密码'}
-            // [M-7] eye icon r(16)≈16pt;Input 高 control.md≈36pt 限制垂直扩展
-            // vertical 走 (44-control.md)/2≈4;horizontal 走 (44-16)/2=14
-            hitSlop={{
-              top: Math.round((fixed.hitTarget - control.md) / 2),
-              bottom: Math.round((fixed.hitTarget - control.md) / 2),
-              left: Math.round((fixed.hitTarget - r(16)) / 2),
-              right: Math.round((fixed.hitTarget - r(16)) / 2),
-            }}
-          >
-            <Icon
-              name={showPw ? 'eye' : 'eye-off'}
-              size={r(16)}
-              color={c.iconFaint40}
-            />
-          </Pressable>
-        }
+        editable={editable}
+        placeholder={placeholder}
+        textContentType={rawTextContentType ?? 'password'}
+        autoComplete={rawAutoComplete ?? 'current-password'}
+        autoCapitalize={rawAutoCapitalize ?? 'none'}
+        secureTextEntry={!showPassword}
+        leading={{ kind: 'icon', icon: 'lock', size: 18 }}
+        trailing={trailing}
       />
     );
   }