@unif/react-native-ui 0.4.0 → 1.0.1

package/src/core/theme/hooks.ts

@@ -0,0 +1,98 @@
+import { createContext, useContext } from 'react';
+import { lightTokens, defaultStrings } from './tokens';
+import type {
+  Tokens,
+  StringsConfig,
+  ResolvedColorMode,
+  ColorMode,
+} from './types';
+
+/** ThemeContext 提供的所有值 */
+export interface ThemeContextValue {
+  /** 当前颜色模式下解析后的 token 对象（已应用 reduced motion 调整） */
+  tokens: Tokens;
+  /** 当前解析后的颜色模式（已将 'system' 转换为 'light' 或 'dark'） */
+  mode: ResolvedColorMode;
+  /** 设置颜色模式；'system' 表示跟随系统 */
+  setMode: (mode: ColorMode) => void;
+  /** 国际化字符串配置（可通过 ThemeProvider 的 strings prop 覆盖） */
+  strings: StringsConfig;
+  /** 触觉反馈回调（由应用层注入，库本身不依赖特定的触觉反馈库） */
+  hapticFeedback?: (type: 'light' | 'medium' | 'heavy' | 'selection') => void;
+  /** Toast 的默认弹出位置 */
+  toastPosition: 'top' | 'bottom';
+}
+
+/**
+ * 主题 Context，默认值为亮色模式 + 默认字符串。
+ * 组件通常不直接消费此 Context，而是通过 useTheme、useThemeMode 等派生 Hook。
+ */
+export const ThemeContext = createContext<ThemeContextValue>({
+  tokens: lightTokens,
+  mode: 'light',
+  setMode: () => {},
+  strings: defaultStrings,
+  toastPosition: 'bottom',
+});
+
+/**
+ * 获取当前主题 token 对象或其某个派生值。
+ *
+ * 重载一：`useTheme()` 返回完整的 Tokens 对象。
+ * 重载二：`useTheme(selector)` 返回 selector 的计算结果（建议使用此形式，
+ * 可减少因无关 token 变化引起的重渲染）。
+ *
+ * 使用示例：
+ * ```tsx
+ * const primary = useTheme((t) => t.primary);
+ * const { fontSize } = useTheme((t) => t.typography.body);
+ * ```
+ */
+export function useTheme(): Tokens;
+export function useTheme<T>(selector: (tokens: Tokens) => T): T;
+export function useTheme<T>(selector?: (tokens: Tokens) => T): Tokens | T {
+  const { tokens } = useContext(ThemeContext);
+  if (!selector) return tokens;
+  return selector(tokens);
+}
+
+/**
+ * 获取当前颜色模式及切换函数。
+ *
+ * @returns `{ mode, setMode }` — mode 为 'light' 或 'dark'（已解析，不含 'system'）
+ */
+export function useThemeMode(): {
+  mode: ResolvedColorMode;
+  setMode: (mode: ColorMode) => void;
+} {
+  const { mode, setMode } = useContext(ThemeContext);
+  return { mode, setMode };
+}
+
+/**
+ * 根据颜色模式返回对应的值，类似 CSS 的 prefers-color-scheme。
+ *
+ * @param lightValue 亮色模式下的值
+ * @param darkValue  暗色模式下的值
+ * @returns 当前模式对应的值
+ */
+export function useColorModeValue<T>(lightValue: T, darkValue: T): T {
+  const { mode } = useContext(ThemeContext);
+  return mode === 'dark' ? darkValue : lightValue;
+}
+
+/**
+ * 获取国际化字符串配置对象（由 ThemeProvider 的 strings prop 注入）。
+ * 组件通过此 Hook 访问无障碍标签、提示文字等本地化字符串。
+ */
+export function useStrings() {
+  return useContext(ThemeContext).strings;
+}
+
+/**
+ * 获取触觉反馈回调（若未注入则返回 undefined）。
+ * 调用前应检查是否为 undefined，以兼容未集成触觉反馈的环境。
+ */
+export function useHapticFeedback() {
+  return useContext(ThemeContext).hapticFeedback;
+}

package/src/core/theme/provider.tsx

@@ -0,0 +1,185 @@
+import React, {
+  createContext,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useColorScheme } from 'react-native';
+import { useReducedMotion } from '../hooks/useReducedMotion';
+import { lightTokens, darkTokens, defaultStrings } from './tokens';
+import { AnimationClockProvider } from './animationClock';
+import { ThemeContext, type ThemeContextValue } from './hooks';
+import type {
+  Tokens,
+  Theme,
+  StringsConfig,
+  ComponentRegistry,
+  ColorMode,
+  ResolvedColorMode,
+} from './types';
+
+/**
+ * Context Bridge Context：用于在 Portal 中透传自定义 Context。
+ *
+ * 当应用使用了第三方状态管理（如 React Navigation、自定义 Context），
+ * 且需要在 Portal 内（Dialog/Sheet 等）继续访问这些 Context 时，
+ * 通过 contextBridge prop 传入一个包裹所有 Context Provider 的组件，
+ * Portal 会自动将其应用到传送过去的节点上。
+ */
+export const ContextBridgeContext = createContext<
+  React.ComponentType<{ children: React.ReactNode }> | undefined
+>(undefined);
+
+export { ThemeContext };
+
+/** ThemeProvider 的 Props */
+export interface ThemeProviderProps {
+  /** 自定义主题（通过 createTheme 生成），未提供时使用内置默认主题 */
+  theme?: Theme;
+  /** 受控颜色模式；提供此 prop 时进入受控模式，需配合 onModeChange 使用 */
+  mode?: ColorMode;
+  /** 非受控模式下的初始颜色偏好；默认为 'system'（跟随系统） */
+  defaultMode?: ColorMode;
+  /** 颜色模式变化时的回调 */
+  onModeChange?: (mode: ColorMode) => void;
+  /** 直接覆盖特定 token（优先级高于 theme，低于组件级样式） */
+  tokens?: Partial<Tokens>;
+  /** 组件默认 Props 覆盖（通过 ComponentRegistry 声明合并扩展） */
+  components?: Partial<ComponentRegistry>;
+  /** 覆盖部分国际化字符串 */
+  strings?: Partial<StringsConfig>;
+  /** 触觉反馈回调注入，用于组件内触发震动反馈 */
+  hapticFeedback?: (type: 'light' | 'medium' | 'heavy' | 'selection') => void;
+  /**
+   * Context Bridge 组件，用于在 Portal 内透传自定义 Context。
+   * 应定义在组件外部（模块级常量），避免每次渲染产生新的引用。
+   */
+  contextBridge?: React.ComponentType<{ children: React.ReactNode }>;
+  /** Toast 默认弹出位置；默认为 'bottom' */
+  toastPosition?: 'top' | 'bottom';
+  children: React.ReactNode;
+}
+
+/**
+ * 主题提供者，应放置在应用根部（通常在 PortalHost 同级或外层）。
+ *
+ * 负责：
+ * 1. 颜色模式管理：支持受控/非受控，可跟随系统（'system'）
+ * 2. Token 解析：theme + tokens prop 覆盖 + reduced motion 调整
+ * 3. 国际化字符串合并
+ * 4. 将 AnimationClockProvider 和 ContextBridgeContext 注入子树
+ */
+export function ThemeProvider({
+  theme,
+  mode: modeProp,
+  defaultMode = 'system',
+  onModeChange,
+  tokens: tokensProp,
+  strings: stringsProp,
+  hapticFeedback,
+  contextBridge,
+  toastPosition = 'bottom',
+  children,
+}: ThemeProviderProps) {
+  // 监听系统颜色方案（iOS/Android）
+  const systemScheme = useColorScheme();
+  // 监听系统"减弱动效"无障碍设置
+  const reduced = useReducedMotion();
+
+  // 非受控内部状态，初始值由 defaultMode 决定（默认跟随系统）
+  const [internalMode, setInternalMode] = useState<ColorMode>(defaultMode);
+
+  // 受控优先：若外部传入 modeProp 则使用外部值，否则使用内部状态
+  const controlledMode = modeProp ?? internalMode;
+
+  // 将 'system' 解析为具体的 'light' 或 'dark'
+  // system scheme 不可用时（Android 某些情况）回退到 'light'
+  const resolvedMode: ResolvedColorMode = useMemo(() => {
+    if (controlledMode === 'light') return 'light';
+    if (controlledMode === 'dark') return 'dark';
+    return (systemScheme as ResolvedColorMode | null) ?? 'light';
+  }, [controlledMode, systemScheme]);
+
+  // 根据颜色模式和 theme/tokens prop 计算基础 token
+  const baseTokens = useMemo(() => {
+    const modeBase = theme
+      ? resolvedMode === 'dark'
+        ? theme.dark
+        : theme.light
+      : resolvedMode === 'dark'
+      ? darkTokens
+      : lightTokens;
+    if (!tokensProp) return modeBase;
+    // tokens prop 覆盖（浅合并，优先级高于 theme）
+    return Object.freeze({ ...modeBase, ...tokensProp }) as Tokens;
+  }, [theme, resolvedMode, tokensProp]);
+
+  // 应用 reduced motion：将 animation.scale 设为 0，使所有动画瞬间完成
+  const effectiveTokens = useMemo(() => {
+    if (!reduced) return baseTokens;
+    return Object.freeze({
+      ...baseTokens,
+      animation: Object.freeze({ ...baseTokens.animation, scale: 0 }),
+    }) as Tokens;
+  }, [baseTokens, reduced]);
+
+  // 合并国际化字符串：defaultStrings + 用户覆盖
+  const effectiveStrings = useMemo(
+    () =>
+      stringsProp
+        ? Object.freeze({ ...defaultStrings, ...stringsProp })
+        : defaultStrings,
+    [stringsProp]
+  );
+
+  // setMode：受控模式下只触发回调，非受控模式下同时更新内部状态
+  const setMode = useCallback(
+    (newMode: ColorMode) => {
+      if (modeProp === undefined) setInternalMode(newMode);
+      onModeChange?.(newMode);
+    },
+    [modeProp, onModeChange]
+  );
+
+  // 检测 contextBridge 是否在每次渲染时产生新引用（常见错误：定义在组件内部）
+  const contextBridgeRef = useRef(contextBridge);
+  if (__DEV__ && contextBridge !== contextBridgeRef.current) {
+    contextBridgeRef.current = contextBridge;
+    if (contextBridgeRef.current !== undefined) {
+      console.warn(
+        '[@unif/react-native-ui] contextBridge received a new component reference on every render. Define it outside your component.'
+      );
+    }
+  }
+
+  // 将所有主题相关值汇聚为 Context 值；useMemo 避免无关变化触发子树重渲染
+  const ctx = useMemo<ThemeContextValue>(
+    () => ({
+      tokens: effectiveTokens,
+      mode: resolvedMode,
+      setMode,
+      strings: effectiveStrings,
+      hapticFeedback,
+      toastPosition,
+    }),
+    [
+      effectiveTokens,
+      resolvedMode,
+      setMode,
+      effectiveStrings,
+      hapticFeedback,
+      toastPosition,
+    ]
+  );
+
+  return (
+    <AnimationClockProvider>
+      <ThemeContext.Provider value={ctx}>
+        <ContextBridgeContext.Provider value={contextBridge}>
+          {children}
+        </ContextBridgeContext.Provider>
+      </ThemeContext.Provider>
+    </AnimationClockProvider>
+  );
+}

package/src/core/theme/tokens.ts

@@ -0,0 +1,186 @@
+import { Easing } from 'react-native-reanimated';
+import type { Tokens, StringsConfig } from './types';
+
+/**
+ * 根据基础圆角值生成全套圆角 token。
+ * 与 createTheme.ts 中的 deriveRadius 保持一致的比例关系。
+ */
+function makeRadius(base: number) {
+  return {
+    radiusSm: Math.round(base * 0.5),
+    radius: base,
+    radiusMd: Math.round(base * 1.33),
+    radiusLg: Math.round(base * 1.67),
+    radiusXl: Math.round(base * 2),
+    radiusFull: 999,
+  };
+}
+
+/** 间距 token：4px 基准，8 档递增 */
+const spacing = {
+  space1: 4,
+  space2: 8,
+  space3: 12,
+  space4: 16,
+  space5: 20,
+  space6: 24,
+  space7: 28,
+  space8: 32,
+};
+
+/**
+ * 字体排版预设集合。
+ * 参考 Apple HIG 字体规范，覆盖展示、标题、正文、标签、等宽五类场景。
+ * 所有预设均被 Object.freeze 保护，防止意外修改。
+ */
+const typography = Object.freeze({
+  displayLg: Object.freeze({ fontSize: 28, lineHeight: 34, fontWeight: '700' }),
+  displaySm: Object.freeze({ fontSize: 22, lineHeight: 28, fontWeight: '700' }),
+  headingLg: Object.freeze({ fontSize: 17, lineHeight: 22, fontWeight: '600' }),
+  headingSm: Object.freeze({ fontSize: 15, lineHeight: 20, fontWeight: '600' }),
+  bodyLg: Object.freeze({ fontSize: 15, lineHeight: 22, fontWeight: '400' }),
+  body: Object.freeze({ fontSize: 13, lineHeight: 18, fontWeight: '400' }),
+  bodySm: Object.freeze({ fontSize: 12, lineHeight: 16, fontWeight: '400' }),
+  label: Object.freeze({ fontSize: 13, lineHeight: 18, fontWeight: '500' }),
+  labelSm: Object.freeze({ fontSize: 11, lineHeight: 14, fontWeight: '500' }),
+  mono: Object.freeze({
+    fontSize: 13,
+    lineHeight: 18,
+    fontWeight: '400',
+    fontFamily: 'monospace',
+  }),
+});
+
+/**
+ * 动画配置。
+ * 三档时长（fast/normal/slow）+ scale 系数（reduced motion 时为 0）。
+ * easing 曲线参考 Material Design：
+ * - default：标准缓动（cubic-bezier(0.25, 0.1, 0.25, 1)）
+ * - in：加速进入（cubic-bezier(0.4, 0, 1, 1)）
+ * - out：减速退出（cubic-bezier(0, 0, 0.2, 1)）
+ * - inOut：先加速后减速（cubic-bezier(0.4, 0, 0.2, 1)）
+ */
+const animation = Object.freeze({
+  durationFast: 150,
+  durationNormal: 250,
+  durationSlow: 350,
+  scale: 1,
+  easing: Object.freeze({
+    default: Easing.bezier(0.25, 0.1, 0.25, 1),
+    in: Easing.bezier(0.4, 0, 1, 1),
+    out: Easing.bezier(0, 0, 0.2, 1),
+    inOut: Easing.bezier(0.4, 0, 0.2, 1),
+  }),
+});
+
+/**
+ * 亮色模式默认 token。
+ * 颜色参考 shadcn/ui 的 zinc 色板，主色为近黑（#18181b）。
+ * boxShadow 值兼容 RN 0.84+ 的 CSS-style boxShadow API。
+ */
+export const lightTokens: Tokens = Object.freeze({
+  background: '#ffffff',
+  foreground: '#09090b',
+  card: '#ffffff',
+  cardForeground: '#09090b',
+  popover: '#ffffff',
+  popoverForeground: '#09090b',
+  overlay: 'rgba(0,0,0,0.5)',
+  primary: '#18181b',
+  primaryForeground: '#fafafa',
+  secondary: '#f4f4f5',
+  secondaryForeground: '#18181b',
+  muted: '#f4f4f5',
+  mutedForeground: '#71717a',
+  destructive: '#ef4444',
+  destructiveForeground: '#fafafa',
+  success: '#22c55e',
+  successForeground: '#fafafa',
+  warning: '#f59e0b',
+  warningForeground: '#000000',
+  border: '#e4e4e7',
+  input: '#e4e4e7',
+  placeholder: '#a1a1aa',
+  ring: '#18181b',
+  ...spacing,
+  ...makeRadius(6),
+  typography,
+  animation,
+  shadowSm: Object.freeze({ boxShadow: '0 1px 2px rgba(0,0,0,0.05)' }),
+  shadow: Object.freeze({ boxShadow: '0 2px 4px rgba(0,0,0,0.10)' }),
+  shadowMd: Object.freeze({ boxShadow: '0 4px 8px rgba(0,0,0,0.15)' }),
+});
+
+/**
+ * 暗色模式默认 token。
+ * 基于 zinc 暗色色板，背景近黑（#09090b），前景近白（#fafafa）。
+ * 阴影透明度相比亮色模式更高，以补偿暗色背景对阴影的视觉削弱。
+ */
+export const darkTokens: Tokens = Object.freeze({
+  background: '#09090b',
+  foreground: '#fafafa',
+  card: '#18181b',
+  cardForeground: '#fafafa',
+  popover: '#18181b',
+  popoverForeground: '#fafafa',
+  overlay: 'rgba(0,0,0,0.7)',
+  primary: '#fafafa',
+  primaryForeground: '#18181b',
+  secondary: '#27272a',
+  secondaryForeground: '#fafafa',
+  muted: '#27272a',
+  mutedForeground: '#a1a1aa',
+  destructive: '#7f1d1d',
+  destructiveForeground: '#fafafa',
+  success: '#166534',
+  successForeground: '#fafafa',
+  warning: '#78350f',
+  warningForeground: '#fafafa',
+  border: '#27272a',
+  input: '#27272a',
+  placeholder: '#52525b',
+  ring: '#d4d4d8',
+  ...spacing,
+  ...makeRadius(6),
+  typography,
+  animation,
+  shadowSm: Object.freeze({ boxShadow: '0 1px 2px rgba(0,0,0,0.30)' }),
+  shadow: Object.freeze({ boxShadow: '0 2px 4px rgba(0,0,0,0.40)' }),
+  shadowMd: Object.freeze({ boxShadow: '0 4px 8px rgba(0,0,0,0.50)' }),
+});
+
+/**
+ * 默认国际化字符串（中文）。
+ * 应用层可通过 ThemeProvider 的 strings prop 覆盖全部或部分字符串，
+ * 以实现多语言或品牌定制文案。
+ */
+export const defaultStrings: StringsConfig = Object.freeze({
+  spinnerLabel: '加载中',
+  progressIndeterminate: '加载中',
+  avatarGroupOverflow: (n: number) => `+${n}`,
+  actionSheetCancel: '取消',
+  dialogClose: '关闭',
+  bottomSheetClose: '关闭',
+  bottomSheetHandle: '拖动以关闭',
+  selectPlaceholder: '请选择',
+  selectSearchPlaceholder: '搜索',
+  inputShowPassword: '显示密码',
+  inputHidePassword: '隐藏密码',
+  inputClear: '清空',
+  inputReadOnlyHint: '只读',
+  sliderValueText: (v: number) => String(v),
+  sliderIncrement: '增加',
+  sliderDecrement: '减少',
+  sliderRangeStartLabel: '范围起始值',
+  sliderRangeEndLabel: '范围结束值',
+  accordionExpand: '展开',
+  accordionCollapse: '折叠',
+  stepsItemLabel: (
+    step: number,
+    total: number,
+    status: 'wait' | 'process' | 'finish' | 'error',
+    title: string
+  ) => `第 ${step}/${total} 步，${status}：${title}`,
+  selectConfirm: '确认',
+  buttonLoading: '，加载中',
+});

package/src/core/theme/types.ts

@@ -0,0 +1,151 @@
+export type { EasingFunction } from 'react-native-reanimated';
+import type {
+  EasingFunction,
+  EasingFunctionFactory,
+} from 'react-native-reanimated';
+import type { TextStyle } from 'react-native';
+
+/** 颜色模式：'light'=亮色，'dark'=暗色，'system'=跟随系统 */
+export type ColorMode = 'light' | 'dark' | 'system';
+
+/** 已解析的颜色模式（'system' 已转换为具体值，供组件内部使用） */
+export type ResolvedColorMode = 'light' | 'dark';
+
+export interface TypographyPreset {
+  fontSize: number;
+  lineHeight: number;
+  fontWeight: TextStyle['fontWeight'];
+  letterSpacing?: number;
+  fontFamily?: string;
+}
+
+export interface ShadowStyle {
+  boxShadow: string;
+}
+
+export interface Tokens {
+  // 语义颜色
+  background: string;
+  foreground: string;
+  card: string;
+  cardForeground: string;
+  popover: string;
+  popoverForeground: string;
+  overlay: string;
+  primary: string;
+  primaryForeground: string;
+  secondary: string;
+  secondaryForeground: string;
+  muted: string;
+  mutedForeground: string;
+  destructive: string;
+  destructiveForeground: string;
+  success: string;
+  successForeground: string;
+  warning: string;
+  warningForeground: string;
+  border: string;
+  input: string;
+  placeholder: string;
+  ring: string;
+
+  // 间距（4–32，4px 递增）
+  space1: number; // 4
+  space2: number; // 8
+  space3: number; // 12
+  space4: number; // 16
+  space5: number; // 20
+  space6: number; // 24
+  space7: number; // 28
+  space8: number; // 32
+
+  // 圆角（由基础值派生）
+  radiusSm: number; // base * 0.5
+  radius: number; // base (default 6)
+  radiusMd: number; // base * 1.33
+  radiusLg: number; // base * 1.67
+  radiusXl: number; // base * 2
+  radiusFull: number; // 999
+
+  // 字体排版预设
+  typography: {
+    displayLg: TypographyPreset; // 28/34/700
+    displaySm: TypographyPreset; // 22/28/700
+    headingLg: TypographyPreset; // 17/22/600
+    headingSm: TypographyPreset; // 15/20/600
+    bodyLg: TypographyPreset; // 15/22/400
+    body: TypographyPreset; // 13/18/400
+    bodySm: TypographyPreset; // 12/16/400
+    label: TypographyPreset; // 13/18/500
+    labelSm: TypographyPreset; // 11/14/500
+    mono: TypographyPreset; // 13/18/400/monospace
+  };
+
+  // 动画
+  animation: {
+    durationFast: number; // 150
+    durationNormal: number; // 250
+    durationSlow: number; // 350
+    scale: number; // 1 (0 = reduced motion)
+    easing: {
+      default: EasingFunction | EasingFunctionFactory;
+      in: EasingFunction | EasingFunctionFactory;
+      out: EasingFunction | EasingFunctionFactory;
+      inOut: EasingFunction | EasingFunctionFactory;
+    };
+  };
+
+  // 阴影
+  shadowSm: ShadowStyle;
+  shadow: ShadowStyle;
+  shadowMd: ShadowStyle;
+}
+
+export interface Theme {
+  light: Tokens;
+  dark: Tokens;
+}
+
+export interface StringsConfig {
+  spinnerLabel: string;
+  progressIndeterminate: string;
+  avatarGroupOverflow: (count: number) => string;
+  actionSheetCancel: string;
+  dialogClose: string;
+  bottomSheetClose: string;
+  bottomSheetHandle: string;
+  selectPlaceholder: string;
+  selectSearchPlaceholder: string;
+  inputShowPassword: string;
+  inputHidePassword: string;
+  inputClear: string;
+  inputReadOnlyHint: string;
+  sliderValueText: (value: number) => string;
+  sliderIncrement: string;
+  sliderDecrement: string;
+  sliderRangeStartLabel: string;
+  sliderRangeEndLabel: string;
+  accordionExpand: string;
+  accordionCollapse: string;
+  stepsItemLabel: (
+    step: number,
+    total: number,
+    status: 'wait' | 'process' | 'finish' | 'error',
+    title: string
+  ) => string;
+  selectConfirm: string;
+  buttonLoading: string;
+}
+
+/** 按组件合并的默认 Props。通过声明合并进行扩展。*/
+
+export interface ComponentRegistry {}
+
+export interface CreateThemeInput {
+  /** 品牌主色（亮色模式）*/
+  primary?: string;
+  /** 暗色模式下品牌主色的覆盖值；若省略则沿用亮色模式的主色 */
+  dark?: { primary?: string };
+  /** 基础圆角倍率；所有圆角 token 均由此派生 */
+  radius?: number;
+}

package/src/core/utils/dev.ts

@@ -0,0 +1,39 @@
+// 所有运行时警告/断言的日志前缀，方便在控制台中快速定位来源
+const PREFIX = '[@unif/react-native-ui]';
+
+/**
+ * 断言函数：若 condition 为 false，在 DEV 模式下抛出 Error。
+ *
+ * 适用于"正确使用时绝不应发生"的编程错误，例如缺少必填 prop、
+ * 子组件在父组件 Context 之外使用等。生产包中此函数为空操作，不影响性能。
+ *
+ * TypeScript 的 `asserts condition` 签名可让编译器在此调用后
+ * 将 condition 类型收窄（去除 null/undefined）。
+ *
+ * @param condition 断言表达式，为 false 时触发错误
+ * @param message   错误描述（无需包含前缀，函数会自动附加）
+ */
+export function invariant(
+  condition: boolean,
+  message: string
+): asserts condition {
+  if (__DEV__ && !condition) {
+    throw new Error(`${PREFIX} ${message}`);
+  }
+}
+
+/**
+ * 软断言函数：若 condition 为 false，在 DEV 模式下输出 console.warn。
+ *
+ * 适用于"仍能运行但可能产生非预期行为"的次优用法，例如
+ * 传入了超出范围的数值、缺少无障碍标签等。
+ * 与 invariant 的区别：不中断执行，仅提示开发者。
+ *
+ * @param condition 断言表达式，为 false 时触发警告
+ * @param message   警告描述（无需包含前缀，函数会自动附加）
+ */
+export function warning(condition: boolean, message: string): void {
+  if (__DEV__ && !condition) {
+    console.warn(`${PREFIX} ${message}`);
+  }
+}