@unif/react-native-design 0.20.0 → 0.21.1

package/src/components/ui/Toast/store.ts

@@ -0,0 +1,148 @@
+import type { Logger } from '../../../utils/logger';
+import type { ToastEntry } from './types';
+
+/**
+ * Toast 的纯状态机 —— 不含任何 React / 渲染依赖,可直接单测。
+ *
+ * 与 Confirm 的语义**不同**,故意不抽成泛型事件总线:
+ * - Confirm 是「一次决策」,需要 active entry + Promise;
+ * - Toast 是「最新一条覆盖旧的」,需要 pending / delivery 双态。
+ *
+ * 双态模型:
+ * - `pending` —— 还没有 Host 接住的最新一条消息。**latest-wins**:后来的直接覆盖,
+ *   不排队(toast 是瞬时反馈,补投一串历史消息毫无意义)。
+ * - `delivered` —— 已交给当前 Host 的那一条,带 `ownerToken` + `leaseId` + `entry.id`
+ *   三重身份。Host 的每个 timer / RAF / 动画完成回调在动 UI 前都必须用这三项做 CAS,
+ *   否则旧回调会把新 toast 提前抹掉(经典竞态:A 的 3s 定时器在 B 显示后才触发)。
+ *
+ * `leaseId` 单调递增,同一 entry 被重新投递(Host 重挂)也会拿到新的 leaseId ——
+ * 仅比较 entry.id 不足以区分「同一条消息的两次投递」。
+ */
+
+export type ToastDelivery = {
+  entry: ToastEntry;
+  ownerToken: symbol;
+  leaseId: number;
+};
+
+export type ToastSubscriber = (delivery: ToastDelivery) => void;
+
+export type ToastHostLease = {
+  readonly ownerToken: symbol;
+  release(): void;
+};
+
+export type ToastStore = {
+  publish(entry: ToastEntry): void;
+  registerHost(subscriber: ToastSubscriber): ToastHostLease | null;
+  complete(ownerToken: symbol, leaseId: number, entryId: number): boolean;
+  isCurrent(delivery: ToastDelivery): boolean;
+  pendingEntry(): ToastEntry | null;
+  currentDelivery(): ToastDelivery | null;
+};
+
+type Owner = { token: symbol; subscriber: ToastSubscriber | null };
+
+export function createToastStore(log: Logger): ToastStore {
+  let pending: ToastEntry | null = null;
+  let delivered: ToastDelivery | null = null;
+  let owner: Owner | null = null;
+  let leaseCounter = 0;
+
+  function beginDelivery(entry: ToastEntry, capturedOwner: Owner): void {
+    const delivery: ToastDelivery = {
+      entry,
+      ownerToken: capturedOwner.token,
+      leaseId: ++leaseCounter,
+    };
+    // 先原子地把 pending 取走并落 delivered,再调 subscriber:subscriber 内同步
+    // 再 publish 时看到的必须是「已投递」而不是「还在 pending」的半状态。
+    pending = null;
+    delivered = delivery;
+    try {
+      capturedOwner.subscriber?.(delivery);
+    } catch (error) {
+      log.error('ToastHost subscriber 抛错', error);
+      // 期间若 owner 已换人 / 已被作废,这次抛错不能牵连新 owner 或覆盖更新的 pending。
+      if (owner?.token !== capturedOwner.token) return;
+      owner = null;
+      if (delivered?.ownerToken === capturedOwner.token) {
+        // 回存的是 delivered 而非 entry:subscriber 内可能已同步投递了更新的一条,
+        // 那条才是当前逻辑消息(latest-wins)。已 complete 的则 delivered 为 null,不复活。
+        pending = delivered.entry;
+        delivered = null;
+      }
+    }
+  }
+
+  function publish(entry: ToastEntry): void {
+    const current = owner;
+    // 未挂 Host 是**受支持路径**,不告警:启动早期的 toast 应当在 Host 挂上后补投。
+    if (!current?.subscriber) {
+      pending = entry;
+      return;
+    }
+    beginDelivery(entry, current);
+  }
+
+  function registerHost(subscriber: ToastSubscriber): ToastHostLease | null {
+    if (owner) {
+      log.warn(
+        '检测到多个 <ToastHost />。只有第一个生效,重复挂载的实例保持惰性 —— 请在 app 根只挂一次。'
+      );
+      return null;
+    }
+    const token = Symbol('ToastHostOwner');
+    const self: Owner = { token, subscriber };
+    owner = self;
+    if (pending) beginDelivery(pending, self);
+    // 首投期间 subscriber 抛错会把 owner 作废 —— 此时不能发出可用的 lease。
+    if (owner?.token !== token) return null;
+    return {
+      ownerToken: token,
+      release(): void {
+        if (owner?.token !== token) return;
+        self.subscriber = null;
+        owner = null;
+        if (delivered?.ownerToken === token) {
+          // 未完成的投递退回 pending,让下一个 Host 能补投;但更新的 pending 优先。
+          if (!pending) pending = delivered.entry;
+          delivered = null;
+        }
+      },
+    };
+  }
+
+  function complete(
+    ownerToken: symbol,
+    leaseId: number,
+    entryId: number
+  ): boolean {
+    const current = delivered;
+    if (!current) return false;
+    if (current.ownerToken !== ownerToken) return false;
+    if (current.leaseId !== leaseId) return false;
+    if (current.entry.id !== entryId) return false;
+    delivered = null;
+    return true;
+  }
+
+  function isCurrent(delivery: ToastDelivery): boolean {
+    const current = delivered;
+    return (
+      current !== null &&
+      current.ownerToken === delivery.ownerToken &&
+      current.leaseId === delivery.leaseId &&
+      current.entry.id === delivery.entry.id
+    );
+  }
+
+  return {
+    publish,
+    registerHost,
+    complete,
+    isCurrent,
+    pendingEntry: () => pending,
+    currentDelivery: () => delivered,
+  };
+}

package/src/components/ui/Toast/toast.ts

@@ -2,14 +2,19 @@
  * 命令式 `toast()` API —— 与 `<ToastHost />` 配对使用。
  *
  * 文件名故意小写 `toast.ts`,host 组件叫 `ToastHost.tsx`,避免 APFS 大小写冲突。
+ *
+ * 本文件只做公共入参归一化(kind / duration / position),投递与身份仲裁全部在
+ * `store.ts`。下面三个内部导出只给两个 Host 用,**不进公共 barrel**。
  */
 import { createLogger } from '../../../utils/logger';
-import type { Subscriber, ToastEntry, ToastInput, ToastKind } from './types';
+import { createToastStore } from './store';
+import type { ToastEntry, ToastInput, ToastKind } from './types';
 
 const log = createLogger('toast');
 
+const store = createToastStore(log);
+
 let _id = 0;
-export const _subs = new Set<Subscriber>();
 
 const DEFAULT_DURATION = 3000;
 // [L-55] duration 合法域:[1, 2^31)。INT32_MAX = 2^31-1 = 2147483647,
@@ -45,14 +50,9 @@ function emit(input: ToastInput, kind: ToastKind = 'info') {
           duration: clampDuration(input.duration),
           position: input.position ?? 'bottom',
         };
-  // 未挂 <ToastHost />:消息无人接收,告警提示集成漏挂(对照 confirm 重入告警的纪律)。
-  if (_subs.size === 0) {
-    log.warn(
-      'toast() 调用时未挂载 <ToastHost />,消息被丢弃。请在 app 根附近挂一次 <ToastHost />。'
-    );
-    return;
-  }
-  _subs.forEach((s) => s(entry));
+  // 未挂 <ToastHost /> 是**受支持路径**:消息留在 pending,Host 挂上后立即补投。
+  // 故这里不告警 —— 启动早期的 toast 本来就可能先于 Host。
+  store.publish(entry);
 }
 
 /**
@@ -68,3 +68,12 @@ export const toast = Object.assign((input: ToastInput) => emit(input, 'info'), {
   success: (input: ToastInput) => emit(input, 'success'),
   error: (input: ToastInput) => emit(input, 'error'),
 });
+
+/** 内部:ToastHost 挂载时注册唯一 owner;重复挂载得到 null。 */
+export const registerToastHost = store.registerHost;
+
+/** 内部:三重身份 CAS —— owner token + leaseId + entry id 全对才算完成。 */
+export const completeToast = store.complete;
+
+/** 内部:timer / RAF / 动画回调动 UI 前的守卫。 */
+export const isCurrentToastDelivery = store.isCurrent;

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

@@ -22,8 +22,12 @@ export type ToastInput =
       position?: ToastPosition;
     };
 
+/**
+ * 归一化后的一条 toast。`id` 是**内部身份**,与 `ToastDelivery` 的 ownerToken /
+ * leaseId 一起构成竞态守卫,不保证跨版本稳定 —— 业务不要依赖它的具体取值。
+ */
 export type ToastEntry = {
-  /** 唯一 id（自增）—— 退场守卫用:ToastHost 只清「仍是当前」的 toast,避免清掉竞态期到达的新 toast */
+  /** 内部自增 id —— 竞态守卫的一环,Host 只处理「仍是当前投递」的回调 */
   id: number;
   /** 消息文本 */
   message: string;
@@ -35,8 +39,8 @@ export type ToastEntry = {
   position: ToastPosition;
 };
 
-/** Toast 订阅者函数签名（ToastHost 内部用） */
-export type Subscriber = (entry: ToastEntry) => void;
+// delivery / lease / subscriber 类型都在 `store.ts` —— 它们是 Host 与 Store 之间的
+// 内部协议,不进公共 barrel。
 
 export type ToastHostProps = {
   /** E2E / 测试定位（业务读 toast 文本时用） */

package/src/components/ui/index.ts

@@ -9,7 +9,13 @@ export type { CardProps, CardVariant } from './Card';
 export { Carousel } from './Carousel';
 export type { CarouselProps, CarouselRef } from './Carousel';
 export { Cell, List } from './Cell';
-export type { CellProps, ListProps } from './Cell';
+export type {
+  CellExtra,
+  CellLeading,
+  CellProps,
+  CellTextValue,
+  ListProps,
+} from './Cell';
 export { Checkbox } from './Checkbox';
 export type { CheckboxProps } from './Checkbox';
 export { Chip } from './Chip';
@@ -31,11 +37,16 @@ export type { IconName, IconProps } from './Icon';
 export { IconButton } from './IconButton';
 export type { IconButtonProps } from './IconButton';
 export { Input } from './Input';
-export type { InputProps } from './Input';
+export type {
+  InputProps,
+  TextFieldContainerStyle,
+  TextFieldHandle,
+  TextFieldSlot,
+} from './Input';
 export { Logo } from './Logo';
 export type { LogoProps } from './Logo';
 export { NavBar } from './NavBar';
-export type { NavBarProps, NavBarSlotConfig } from './NavBar';
+export type { NavBarAction, NavBarProps, NavBarSlot } from './NavBar';
 export { PasswordInput } from './PasswordInput';
 export type { PasswordInputProps } from './PasswordInput';
 export { Pulse, PulseDot, usePulse } from './Pulse';
@@ -71,7 +82,11 @@ export type { TagProps, TagSize, TagVariant } from './Tag';
 export { Textarea } from './Textarea';
 export type { TextareaProps } from './Textarea';
 export { Thumbnail } from './Thumbnail';
-export type { ThumbnailProps, ThumbnailSize } from './Thumbnail';
+export type {
+  ThumbnailImageStyle,
+  ThumbnailProps,
+  ThumbnailSize,
+} from './Thumbnail';
 export { toast, ToastHost } from './Toast';
 export type {
   ToastEntry,

package/src/components/ui/shared/ImageAttempt.tsx

@@ -0,0 +1,30 @@
+import React, { useCallback, useState } from 'react';
+import { Image } from 'react-native';
+import type { ImageProps, ImageSourcePropType } from 'react-native';
+import { selectImageAttemptSource } from './selectImageAttemptSource';
+
+type ImageAttemptProps = Omit<ImageProps, 'onError' | 'source'> & {
+  source: ImageSourcePropType;
+  fallback: React.ReactNode;
+};
+
+/**
+ * 每个 keyed 挂载实例只拥有自己的失败状态。source identity 变化时由父级 key
+ * 同步换实例，旧 onError 无法写入新 attempt。
+ */
+export function ImageAttempt({
+  source,
+  fallback,
+  ...imageProps
+}: ImageAttemptProps): React.JSX.Element {
+  const [failed, setFailed] = useState(false);
+  // RNW 的加载 effect 依赖 onError identity；等价 render 不应中止并重发请求。
+  const handleError = useCallback(() => setFailed(true), []);
+  const selectedSource = selectImageAttemptSource(source);
+
+  return failed || selectedSource === undefined ? (
+    <>{fallback}</>
+  ) : (
+    <Image {...imageProps} source={selectedSource} onError={handleError} />
+  );
+}

package/src/components/ui/shared/a11y.ts

@@ -0,0 +1,18 @@
+/**
+ * 装饰性节点从 a11y 树里隐藏所需的**全套**属性 —— 四个平台各认一个,少一个就漏。
+ *
+ * - `accessible: false` —— iOS/Android 都不把该节点合并成可聚焦元素
+ * - `accessibilityElementsHidden` —— iOS 连同后代一起移出 a11y 树
+ * - `importantForAccessibility: 'no-hide-descendants'` —— Android 同上
+ * - `aria-hidden` —— react-native-web 映射到 DOM 的 `aria-hidden`
+ *
+ * **只能**落在库内本地的 RN `View` / `Image` / `Text` 上。绝不要展开给未知第三方组件:
+ * 它们可能把未识别的 props 原样透传到原生层,或者干脆用同名 prop 表达别的语义。
+ * 需要隐藏第三方子树时,用一个本地 View 包住它,把这些属性挂在包装层。
+ */
+export const A11Y_HIDDEN_PROPS = {
+  'accessible': false,
+  'accessibilityElementsHidden': true,
+  'importantForAccessibility': 'no-hide-descendants',
+  'aria-hidden': true,
+} as const;

package/src/components/ui/shared/accessibilityName.ts

@@ -0,0 +1,6 @@
+/** 未类型化边界只接受 trim 后非空的 string 作为业务可访问名称。 */
+export function normalizeNonBlankText(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}

package/src/components/ui/shared/selectImageAttemptSource.shared.ts

@@ -0,0 +1,17 @@
+import type { ImageSourcePropType } from 'react-native';
+import { isValidImageSource } from '../../../utils/imageSource';
+
+export function selectNativeImageAttemptSource(
+  source: unknown
+): ImageSourcePropType | undefined {
+  return isValidImageSource(source) ? source : undefined;
+}
+
+export function selectWebImageAttemptSource(
+  source: unknown
+): ImageSourcePropType | undefined {
+  if (!isValidImageSource(source)) return undefined;
+
+  // RNW 0.21 不解析 native 的 candidate 数组；Web 明确使用第一候选项。
+  return Array.isArray(source) ? source[0] : source;
+}

package/src/components/ui/shared/selectImageAttemptSource.ts

@@ -0,0 +1,3 @@
+import { selectNativeImageAttemptSource } from './selectImageAttemptSource.shared';
+
+export const selectImageAttemptSource = selectNativeImageAttemptSource;

package/src/components/ui/shared/selectImageAttemptSource.web.ts

@@ -0,0 +1,3 @@
+import { selectWebImageAttemptSource } from './selectImageAttemptSource.shared';
+
+export const selectImageAttemptSource = selectWebImageAttemptSource;

package/src/icons/data.ts

@@ -679,7 +679,7 @@ export const ICONS: Record<IconName, IconDef> = {
     ],
   },
   'check': {
-    strokeWidth: 2,
+    strokeWidth: 1.75,
     elements: [
       {
         kind: 'path',

package/src/theme/ThemeProvider.tsx

@@ -1,7 +1,11 @@
-import React, { createContext, useMemo } from 'react';
+import React, { useEffect, useMemo } from 'react';
 import { useColorScheme } from 'react-native';
 import { lightColors, darkColors, type ColorTokens } from './colors';
+import { normalizeFontScale } from './fontScale';
 import { lightShadow, darkShadow, type ShadowTokens } from './shadow';
+import { ThemeContext } from './themeContext';
+import { createInvalidFontScaleDiagnostic } from './themeDiagnostics';
+import { createLogger } from '../utils/logger';
 
 export type ColorScheme = 'light' | 'dark';
 
@@ -10,21 +14,23 @@ export type ThemeContextValue = {
   colors: ColorTokens;
   shadow: ShadowTokens;
   /** 应用级字号缩放倍数(app 内字体大小档)。useThemedStyles 出口对
-   *  fontSize / lineHeight / letterSpacing 生效;1 = 不缩放。 */
+   *  fontSize / lineHeight / letterSpacing 生效;非法值回退 1。 */
   fontScale: number;
 };
 
-export const ThemeContext = createContext<ThemeContextValue | null>(null);
-
 type ThemeProviderProps = {
   children: React.ReactNode;
   /** 强制使用某个 scheme（覆盖 useColorScheme）。用于测试或 settingsStore 接入。 */
   forceScheme?: ColorScheme;
   /** 应用级字号缩放倍数,默认 1(不缩放)。接入方自持档位状态(persist
-   *  store 等)并传入;变更即触发全树 themed 样式重算。 */
+   *  store 等)并传入;仅接受有限正数,不设上限。 */
   fontScale?: number;
 };
 
+const isDev = typeof __DEV__ !== 'undefined' && __DEV__;
+const log = createLogger('ThemeProvider');
+const reportInvalidFontScale = createInvalidFontScaleDiagnostic(log.warn);
+
 export function ThemeProvider({
   children,
   forceScheme,
@@ -33,6 +39,11 @@ export function ThemeProvider({
   const sysScheme = useColorScheme();
   const scheme: ColorScheme =
     forceScheme ?? (sysScheme === 'dark' ? 'dark' : 'light');
+  const normalizedFontScale = normalizeFontScale(fontScale);
+
+  useEffect(() => {
+    reportInvalidFontScale(fontScale, normalizedFontScale, isDev);
+  }, [fontScale, normalizedFontScale]);
 
   // useMemo 必须依赖 scheme,不要依赖 light/dark 对象本身 —— 这是 useThemedStyles
   // 缓存生效的前提(每次渲染拿到稳定 colors / shadow 引用)。
@@ -41,9 +52,9 @@ export function ThemeProvider({
       scheme,
       colors: scheme === 'dark' ? darkColors : lightColors,
       shadow: scheme === 'dark' ? darkShadow : lightShadow,
-      fontScale,
+      fontScale: normalizedFontScale,
     }),
-    [scheme, fontScale]
+    [scheme, normalizedFontScale]
   );
 
   return (

package/src/theme/fontScale.ts

@@ -0,0 +1,15 @@
+import { useTheme } from './useTheme';
+
+export function normalizeFontScale(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : 1;
+}
+
+export function scaleFontMetric(value: number, fontScale: number): number {
+  return value * normalizeFontScale(fontScale);
+}
+
+export function useFontScale(): number {
+  return normalizeFontScale(useTheme().fontScale);
+}

package/src/theme/index.ts

@@ -11,12 +11,11 @@ export { warmOrangePalette } from './palettes';
 export { lightShadow, darkShadow } from './shadow';
 export type { ShadowTokens } from './shadow';
 
-export { ThemeProvider, ThemeContext } from './ThemeProvider';
+export { ThemeProvider } from './ThemeProvider';
 export type { ColorScheme, ThemeContextValue } from './ThemeProvider';
-// ThemeContext 为内部用途导出:若需子树强制主题,优先用 <ThemeProvider forceScheme> 嵌套。
-// 直接自挂 Provider 须保证 value 引用稳定(每渲染新对象会打穿 useThemedStyles 缓存)。
 
 export { useTheme, useColors, useShadow } from './useTheme';
+export { normalizeFontScale, scaleFontMetric, useFontScale } from './fontScale';
 export { useThemedStyles } from './useThemedStyles';
 export type { StylesMaker } from './useThemedStyles';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';

package/src/theme/themeContext.ts

@@ -0,0 +1,24 @@
+import { createContext } from 'react';
+import { lightColors } from './colors';
+import { lightShadow } from './shadow';
+import type { ThemeContextValue } from './ThemeProvider';
+
+export const FALLBACK_THEME: ThemeContextValue = {
+  scheme: 'light',
+  colors: lightColors,
+  shadow: lightShadow,
+  fontScale: 1,
+};
+
+export const ThemeContext = createContext<ThemeContextValue | undefined>(
+  undefined
+);
+
+export const resolveThemeContext = (
+  value: ThemeContextValue | undefined
+): ThemeContextValue => value ?? FALLBACK_THEME;
+
+export const shouldWarnMissingThemeProvider = (
+  value: ThemeContextValue | undefined,
+  isDev: boolean
+): boolean => value === undefined && isDev;

package/src/theme/themeDiagnostics.ts

@@ -0,0 +1,41 @@
+type DiagnosticWarn = (message: string) => void;
+type DiagnosticFormatter = (value: unknown) => string;
+
+const formatDiagnosticValue: DiagnosticFormatter = (value) => {
+  try {
+    return String(value);
+  } catch {
+    return '<无法序列化>';
+  }
+};
+
+export function createInvalidFontScaleDiagnostic(
+  warn: DiagnosticWarn,
+  formatValue: DiagnosticFormatter = formatDiagnosticValue
+): (value: unknown, normalizedFontScale: number, isDev: boolean) => void {
+  const warnedValues = new Set<string>();
+
+  return (value, normalizedFontScale, isDev) => {
+    if (!isDev || normalizedFontScale === value) return;
+
+    const formattedValue = formatValue(value);
+    const warningKey = `${typeof value}:${formattedValue}`;
+    if (warnedValues.has(warningKey)) return;
+
+    warnedValues.add(warningKey);
+    warn(`fontScale=${formattedValue} 无效，已回退为 1`);
+  };
+}
+
+export function createMissingThemeProviderDiagnostic(
+  warn: DiagnosticWarn
+): (shouldWarn: boolean) => void {
+  let warned = false;
+
+  return (shouldWarn) => {
+    if (!shouldWarn || warned) return;
+
+    warned = true;
+    warn('缺少 ThemeProvider，已使用稳定 light fallback');
+  };
+}

package/src/theme/usePrefersReducedMotion.ts

@@ -1,9 +1,16 @@
+import { useReducedMotion } from 'react-native-reanimated';
+
 /**
- * 系统「减弱动态效果」开关。
+ * native:读取 iOS / Android 系统「减弱动态效果」设置。
  *
- * native 端的动画由 reanimated 默认 `ReduceMotion.System` 处理(reduce-motion 下自动
- * 跳到端值),此 hook 只有 web 平台的 CSS/JS 动画需要 —— native 恒返回 false,见 `.web.ts`。
+ * 为什么必须真读系统值 —— Reanimated 的 `ReduceMotion.System` 只覆盖它自己驱动的
+ * `withTiming` / `withSpring` 等动画;组件自己用 `setInterval`、RAF、Modal 转场或
+ * autoplay 做的动效完全不在它管辖内。本 hook 曾恒返回 `false`,导致 native 端
+ * Pulse、Carousel autoplay 等路径在系统开启减弱动效后仍继续动。
+ *
+ * 消费方(Pulse、Switch、Carousel、Reveal……)必须显式分支到这个 hook,不能假设
+ * 动画引擎已替自己处理了该偏好。
  */
 export function usePrefersReducedMotion(): boolean {
-  return false;
+  return useReducedMotion();
 }

package/src/theme/usePrefersReducedMotion.web.ts

@@ -7,8 +7,11 @@ const QUERY = '(prefers-reduced-motion: reduce)';
 const win: any = globalThis as any;
 
 /**
- * web:监听系统「减弱动态效果」开关,返回当前是否开启;开关变化时自动更新。
- * native 端走 reanimated 的 `ReduceMotion.System`,对应 `.ts` 版恒返回 false。
+ * web:监听系统「减弱动态效果」开关(`matchMedia`),返回当前是否开启;开关变化时自动更新。
+ *
+ * native 兄弟实现读 Reanimated 的系统信号(`useReducedMotion()`),两端语义一致 ——
+ * 都返回真实的系统偏好。Reanimated 只自动处理它自己驱动的动画,timer / RAF / CSS
+ * transition / autoplay 一律要由消费方显式分支到本 hook。
  */
 export function usePrefersReducedMotion(): boolean {
   const [reduced, setReduced] = useState<boolean>(() =>

package/src/theme/useTheme.ts

@@ -1,33 +1,25 @@
-import { useContext } from 'react';
-import { ThemeContext, type ThemeContextValue } from './ThemeProvider';
-import { lightColors } from './colors';
-import { lightShadow } from './shadow';
+import { useContext, useEffect } from 'react';
+import type { ThemeContextValue } from './ThemeProvider';
+import {
+  resolveThemeContext,
+  shouldWarnMissingThemeProvider,
+  ThemeContext,
+} from './themeContext';
+import { createMissingThemeProviderDiagnostic } from './themeDiagnostics';
+import { createLogger } from '../utils/logger';
 
-const FALLBACK: ThemeContextValue = {
-  scheme: 'light',
-  colors: lightColors,
-  shadow: lightShadow,
-  fontScale: 1,
-};
-
-// 静默回退而非 throw:FALLBACK 是模块级稳定引用,useThemedStyles 缓存契约不受影响。
-// 缺点:漏包 ThemeProvider 时整 app 永远 light、暗色失效且零信号——
-// 因此在 dev 下一次性告警提示接入方补 Provider。
-// 用 typeof __DEV__ 守卫:裸 __DEV__ 在非 Metro 打包器(Webpack/Next.js)下会 ReferenceError,
-// logger.ts:12 已有同等先例。
-let _warnedMissingProvider = false;
+const isDev = typeof __DEV__ !== 'undefined' && __DEV__;
+const log = createLogger('useTheme');
+const reportMissingProvider = createMissingThemeProviderDiagnostic(log.warn);
 
 export function useTheme(): ThemeContextValue {
-  const ctx = useContext(ThemeContext);
-  if (ctx === undefined && !_warnedMissingProvider) {
-    _warnedMissingProvider = true;
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      console.warn(
-        '[unif/theme] useTheme: ThemeContext 未找到 —— 请在 app 根部渲染 <ThemeProvider>，否则暗色切换不生效。'
-      );
-    }
-  }
-  return ctx ?? FALLBACK;
+  const context = useContext(ThemeContext);
+
+  useEffect(() => {
+    reportMissingProvider(shouldWarnMissingThemeProvider(context, isDev));
+  }, [context]);
+
+  return resolveThemeContext(context);
 }
 
 export function useColors() {