@unif/react-native-design 0.8.2 → 0.10.0

package/src/theme/colors.ts

@@ -1,8 +1,12 @@
 // Role-based color tokens —— role 名固定,亮/暗主题切的是 role 指向哪个 hex。
 
+/** 品牌橙 hex —— 跨文件(colors 亮/暗 primary、glassActiveFg、avatarGradient、shadow BRAND)
+ *  共用同一来源,改品牌色只改这一处。 */
+export const BRAND_ORANGE = '#EB6E00';
+
 export const lightColors = {
   // Brand
-  primary: '#EB6E00',
+  primary: BRAND_ORANGE,
   primaryPressed: '#D06200',
   primaryContainer: '#FFF5EB',
   primaryContainerSubtle: '#FFF8F0',
@@ -48,6 +52,7 @@ export const lightColors = {
   inverseOnSurface: '#FFFFFF',
 
   // Misc
+  /** 亮色 0.5:标准遮挡强度,背景内容隐退但保留可感知轮廓,符合 iOS/MD 规范建议。 */
   scrim: 'rgba(0,0,0,0.5)',
   /** Sheet backdrop —— sheet 之下浅灰 tint,合规态高对比度让 sheet 焦点突出。
    *  跟通用 scrim(黑半透"普通遮挡")区分:这是"焦点引导"。 */
@@ -57,11 +62,11 @@ export const lightColors = {
   /** 玻璃容器内部分隔线 —— 暗色翻成对应低透白,保证暗底可见。 */
   glassSeparator: 'rgba(0,0,0,0.08)',
   /** 浮动玻璃胶囊外区 tint(TabBar 滚动玻璃门)。
-   *  数值配合 blurAmount=25 让"玻璃门外区滚动内容透过模糊显示"达成。
+   *  数值配合 blur.strong(blurAmount=40) 让"玻璃门外区滚动内容透过模糊显示"达成。
    *  跟 glassTintLight 区分:此 token 给"玻璃门外区"语义。 */
   glassSurface: 'rgba(255,255,255,0.20)',
   /** TabBar 玻璃门 tint —— 跟 glassSurface 区分,真机实测 0.20 太厚看不清滚动内容,
-   *  TabBar 场景配合 blurAmount=15 主导,语义不同不可复用同一个 alpha。 */
+   *  TabBar 场景配合 blur.soft(blurAmount=10) 主导,语义不同不可复用同一个 alpha。 */
   tabBarGlassTint: 'rgba(255,255,255,0.10)',
   /** 玻璃胶囊边框(亮 0.18 / 暗 0.14 白透)。 */
   glassBorder: 'rgba(255,255,255,0.18)',
@@ -72,7 +77,7 @@ export const lightColors = {
   glassStatsHighlight: 'rgba(255,255,255,0.65)',
   /** 玻璃胶囊 active 段文字 / icon 色。亮色同 primary;暗色 #FFB068
    *  更浅一档的橙,在半透深灰玻璃上分量更轻。 */
-  glassActiveFg: '#EB6E00',
+  glassActiveFg: BRAND_ORANGE,
   /** 品牌橙 active 容器底 —— TabBar active 段比 brandTint10 多 2% 视觉权重。 */
   brandTint12: 'rgba(235,110,0,0.12)',
 
@@ -89,7 +94,10 @@ export const lightColors = {
   /** Me 屏 QR / 扫码按钮背景 —— scanBtn 要在 hero 上"凸起被看到"。 */
   qrBg: 'rgba(255,255,255,0.55)',
 
-  // Hero gradient stops —— Me 屏顶部暖橙 → 浅黄 → background 三段渐变
+  // Hero gradient stops —— Me 屏顶部暖橙 → 浅黄 → background 三段渐变。
+  // 历史驻留:渐变序列按约定应进 palettes.ts,但 heroGradient 驻 ColorTokens 可随主题
+  // 自动切换(消费方无需手动 scheme 分支);迁 palettes 会让消费方须手写 scheme 判断,
+  // 属人体工程学回退。新渐变序列一律进 palettes.ts,不要往 colors.ts 追加。
   /** Hero 渐变第 1 段:暖橙起色。 */
   heroGradient0: '#FFE3C8',
   /** Hero 渐变第 2 段(0.55 offset):浅黄过渡。 */
@@ -108,7 +116,7 @@ export type ColorTokens = { [K in keyof typeof lightColors]: string };
 
 export const darkColors: ColorTokens = {
   // Brand
-  primary: '#EB6E00',
+  primary: BRAND_ORANGE,
   primaryPressed: '#D06200',
   primaryContainer: '#3D1F00',
   primaryContainerSubtle: '#2A1500',
@@ -153,6 +161,8 @@ export const darkColors: ColorTokens = {
   inverseOnSurface: '#000000',
 
   // Misc
+  /** 暗色加深至 0.7(亮色 0.5):暗色环境底图对比度低、亮部元素更"抢眼",
+   *  scrim 需更重才能有效压住背景,让前景 sheet / modal 焦点突出。 */
   scrim: 'rgba(0,0,0,0.7)',
   /** Sheet backdrop 暗色:沿用亮色同值,合规态保持浅 tint(打破暗色默认深底)让焦点
    *  聚焦在协议 sheet 上。 */
@@ -160,15 +170,21 @@ export const darkColors: ColorTokens = {
   // 暗色 0.06 白透,凸起感由 glassBar 暗色黑 0.35 shadow 补
   glassTintLight: 'rgba(255,255,255,0.06)',
   glassSeparator: 'rgba(255,255,255,0.10)',
-  // 深灰半透 0.30,配合 blurAmount=25 让"玻璃门"语义达成
+  // 深灰半透 0.30,配合 blur.strong(blurAmount=40) 让"玻璃门"语义达成
   glassSurface: 'rgba(28,28,30,0.30)',
-  // 配合 blurAmount=15 让内容透过模糊带 alpha 染色
+  // 配合 blur.soft(blurAmount=10) 让内容透过模糊带 alpha 染色
   tabBarGlassTint: 'rgba(28,28,30,0.18)',
   glassBorder: 'rgba(255,255,255,0.14)',
   glassHighlight: 'rgba(255,255,255,0.24)',
+  // 暗色降至 0.10(亮色 0.65):暗色 BlurView 背景本身已深,顶部高光过强会破坏玻璃质感
+  // 的"透视感"——0.10 轻轻描出上沿即足以传达"凸起"层级。
+  // 注:亮色"比 glassHighlight 更强(0.65>0.28)"在暗色刻意反转(0.10<0.24),
+  // 两端各自以视觉效果为准,非笔误。
   glassStatsHighlight: 'rgba(255,255,255,0.10)',
   // 浅橙,半透深灰玻璃上品牌色更亮起,视觉重量比纯品牌橙轻一档
   glassActiveFg: '#FFB068',
+  // 暗色 brandTint12 与 brandTint14 同值(0.22):亮色 10/12/14 三档在暗底视觉差微弱,
+  // 两档合一后对比度差异仍可感知;若后续设计需要恢复阶梯可将 brandTint12 改为 0.18-0.20。
   brandTint12: 'rgba(235,110,0,0.22)',
 
   // Icon faint —— 暗底反相成白色 alpha,数值跟亮色一致
@@ -183,6 +199,7 @@ export const darkColors: ColorTokens = {
 
   // Hero gradient stops —— 品牌橙 alpha 渐变。
   // react-native-svg <Stop stopColor> 支持 rgba 字符串,最终 alpha = rgba.a × stopOpacity。
+  // 历史驻留(同亮色注释):新渐变序列一律进 palettes.ts。
   heroGradient0: 'rgba(235,110,0,0.18)',
   heroGradient1: 'rgba(235,110,0,0.06)',
   heroGradient2: '#0A0A0A',
@@ -192,5 +209,7 @@ export const darkColors: ColorTokens = {
   glassPillBorder: 'rgba(255,255,255,0.12)',
 };
 
-/** 头像品牌渐变 —— 浅橙 → 主品牌橙,135° 对角线渐变。亮 / 暗共用。 */
-export const avatarGradient = ['#F49443', '#EB6E00'] as const;
+/** 头像品牌渐变 —— 浅橙 → 主品牌橙,135° 对角线渐变。亮 / 暗共用。
+ *  历史驻留:渐变序列按约定应进 palettes.ts,但亮/暗共用无需 scheme 分支且消费面稳定,
+ *  迁移无收益。新渐变序列一律进 palettes.ts。 */
+export const avatarGradient = ['#F49443', BRAND_ORANGE] as const;

package/src/theme/index.ts

@@ -1,4 +1,9 @@
-export { lightColors, darkColors, avatarGradient } from './colors';
+export {
+  lightColors,
+  darkColors,
+  avatarGradient,
+  BRAND_ORANGE,
+} from './colors';
 export type { ColorTokens } from './colors';
 
 export { warmOrangePalette } from './palettes';
@@ -8,10 +13,13 @@ export type { ShadowTokens } from './shadow';
 
 export { ThemeProvider, ThemeContext } from './ThemeProvider';
 export type { ColorScheme, ThemeContextValue } from './ThemeProvider';
+// ThemeContext 为内部用途导出:若需子树强制主题,优先用 <ThemeProvider forceScheme> 嵌套。
+// 直接自挂 Provider 须保证 value 引用稳定(每渲染新对象会打穿 useThemedStyles 缓存)。
 
 export { useTheme, useColors, useShadow } from './useTheme';
 export { useThemedStyles } from './useThemedStyles';
 export type { StylesMaker } from './useThemedStyles';
+export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 
 export {
   fontMono,
@@ -25,6 +33,7 @@ export {
   dim,
   fixed,
   motion,
+  pressedOpacity,
 } from './tokens';
 
 export { blur } from './blur';

package/src/theme/scale.ts

@@ -7,10 +7,14 @@ const DESIGN_WIDTH = 402;
  *  0.3 对中文字号最友好(避免大屏字过大、小屏字过小)。 */
 const FONT_FACTOR = 0.3;
 
+// 取短边而非宽度:横屏/iPad 启动时 width 会是长边(iPhone 17 Pro 874pt),
+// 导致所有 r() 尺寸约翻倍。Math.min(w, h) 使竖屏行为完全不变,
+// 同时收口横屏启动与 iPad Split View(window 宽可能小于 DESIGN_WIDTH)两个场景。
+const { width: _w, height: _h } = Dimensions.get('window');
 const w =
   Platform.OS === 'web'
     ? DESIGN_WIDTH
-    : Dimensions.get('window').width || DESIGN_WIDTH;
+    : Math.min(_w || DESIGN_WIDTH, _h || DESIGN_WIDTH) || DESIGN_WIDTH;
 
 /** 实际缩放比。 */
 const ratio = w / DESIGN_WIDTH;

package/src/theme/shadow.ts

@@ -4,7 +4,10 @@
 // 暗色下中性阴影 shadowOpacity / elevation 全部置 0:视觉层次靠 surface 5 层
 // 明度差表达(layered surface 替代 shadow)。
 
-const BRAND = '#EB6E00';
+import { BRAND_ORANGE } from './colors';
+
+// 模块级别名保持历史可读性,同时指向 colors.ts 单一来源。
+const BRAND = BRAND_ORANGE;
 
 export const lightShadow = {
   /** 轻提示浮起 —— Segmented active 段 */
@@ -106,28 +109,34 @@ export const lightShadow = {
   },
 } as const;
 
+// readonly 加到嵌套字段:顶层 key 经同态映射已只读,但嵌套 shadowOffset 字段
+// 在运行时仍可合法赋值(t.card.shadowOffset.height = 5 会静默串改全部共享引用)。
+// 此处显式声明 readonly 让 tsc 在编译期捕获误改。
 export type ShadowTokens = {
-  [K in keyof typeof lightShadow]: {
-    shadowColor: string;
-    shadowOffset: { width: number; height: number };
-    shadowOpacity: number;
-    shadowRadius: number;
-    elevation: number;
+  readonly [K in keyof typeof lightShadow]: {
+    readonly shadowColor: string;
+    readonly shadowOffset: { readonly width: number; readonly height: number };
+    readonly shadowOpacity: number;
+    readonly shadowRadius: number;
+    readonly elevation: number;
   };
 };
 
-/** 暗色统一置零 —— dark theme 用 surface 明度差替代 shadow */
-const darkZero = {
-  shadowOffset: { width: 0, height: 0 },
-  shadowOpacity: 0,
-  shadowRadius: 0,
-  elevation: 0,
-};
+// darkZero 辅助函数:每次调用返回独立 offset 对象,消除多 token 共享同一 shadowOffset
+// 引用的隐患——虽然 ShadowTokens readonly 已在类型层阻止赋值,防御深度更好。
+const darkZero = (shadowColor: string) =>
+  ({
+    shadowColor,
+    shadowOffset: { width: 0, height: 0 },
+    shadowOpacity: 0,
+    shadowRadius: 0,
+    elevation: 0,
+  }) as const;
 
 export const darkShadow: ShadowTokens = {
-  subtle: { ...darkZero, shadowColor: '#000' },
-  card: { ...darkZero, shadowColor: '#000' },
-  /** floating 暗色不走 darkZero:浮动胶囊在暗 bg 上需要黑色 drop shadow,
+  subtle: darkZero('#000'),
+  card: darkZero('#000'),
+  /** floating 暗色不置零:浮动胶囊在暗 bg 上需要黑色 drop shadow,
    *  否则跟暗背景贴平,视觉无层级。 */
   floating: {
     shadowColor: '#000',
@@ -136,12 +145,12 @@ export const darkShadow: ShadowTokens = {
     shadowRadius: 60,
     elevation: 16,
   },
-  brandSm: { ...darkZero, shadowColor: BRAND },
-  brandMd: { ...darkZero, shadowColor: BRAND },
-  brandLg: { ...darkZero, shadowColor: BRAND },
-  brandXl: { ...darkZero, shadowColor: BRAND },
-  brandAbout: { ...darkZero, shadowColor: BRAND },
-  brandAssistant: { ...darkZero, shadowColor: BRAND },
+  brandSm: darkZero(BRAND),
+  brandMd: darkZero(BRAND),
+  brandLg: darkZero(BRAND),
+  brandXl: darkZero(BRAND),
+  brandAbout: darkZero(BRAND),
+  brandAssistant: darkZero(BRAND),
   /** brandAvatar 暗色不置零:暗色 ring 0.10 几乎隐去,靠橙光晕(0.40 比亮色 0.28 更强)
    *  托起头像。 */
   brandAvatar: {
@@ -160,5 +169,5 @@ export const darkShadow: ShadowTokens = {
     shadowRadius: 18,
     elevation: 6,
   },
-  none: { ...darkZero, shadowColor: 'transparent' },
+  none: darkZero('transparent'),
 };

package/src/theme/tokens.ts

@@ -17,9 +17,9 @@ export const type = {
   xs: rf(13),
   xxs: rf(12),
   micro: rf(11),
-  nano: rf(10), // TabBar/Grid/Citation/Sources 角标/小标签 10pt
+  nano: rf(10), // TabBar/Grid 角标/小标签 10pt
   // ── 半档微调(0.5 step,加于"近似 token + delta"反模式收敛) ──
-  /** micro(11)与 xxs(12)之间:VersionPill / profileCard / Splash / carousel 副标题。 */
+  /** micro(11)与 xxs(12)之间:VersionPill / Splash / carousel 副标题。 */
   microPlus: rf(11.5),
   /** xs(13)与 sm(14)之间:Privacy 长文阅读字号。 */
   xsPlus: rf(13.5),
@@ -28,7 +28,7 @@ export const type = {
   smPlus: rf(14.5),
   /** Hero 区主标题档(一级 brand hero,带 Logo,Login 屏)。 */
   heroLg: rf(26),
-  /** Hero 区中等档(独立屏 + NavBar 的二级 hero,ForgotPassword)。 */
+  /** Hero 区中等档(独立屏 + NavBar 的二级 hero)。 */
   heroMd: rf(22),
   /** Hero 区小档(承接式 hero,Group 选组/选角色子区)。 */
   heroSm: rf(18),
@@ -57,7 +57,7 @@ export const space = {
 } as const;
 
 export const radius = {
-  'xs': r(4), // Radio/Checkbox/Tag/Citation 内圈 4pt
+  'xs': r(4), // Radio/Checkbox 内圈 4pt
   'sm': r(6),
   'md': r(8),
   'lg': r(10),
@@ -98,7 +98,7 @@ export const control = {
 
 /** 散尺寸 —— 未归到 avatar/icon/control 阶梯的单点常量。 */
 export const dim = {
-  /** 发送按钮 32px —— chat PromptInput / 主送出按钮专用,与 avatar.md 同值 */
+  /** 发送按钮 32px —— 主送出/发送按钮专用,与 avatar.md 同值 */
   sendBtn: r(32),
 } as const;
 
@@ -117,3 +117,8 @@ export const motion = {
   slow: 300,
   pulse: 1600,
 } as const;
+
+/** 按压态透明度 —— Pressable pressed 时 opacity 的共享常量。
+ *  ButtonBase、Chip、Cell、Grid、EntryCard、Tabs、Segmented、TabBar 等
+ *  凡需要「按压反馈」的组件统一引用此值,避免散落多处手写 0.7 后不同步。 */
+export const pressedOpacity = 0.7;

package/src/theme/usePrefersReducedMotion.ts

@@ -0,0 +1,9 @@
+/**
+ * 系统「减弱动态效果」开关。
+ *
+ * native 端的动画由 reanimated 默认 `ReduceMotion.System` 处理(reduce-motion 下自动
+ * 跳到端值),此 hook 只有 web 平台的 CSS/JS 动画需要 —— native 恒返回 false,见 `.web.ts`。
+ */
+export function usePrefersReducedMotion(): boolean {
+  return false;
+}

package/src/theme/usePrefersReducedMotion.web.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+
+const QUERY = '(prefers-reduced-motion: reduce)';
+
+// tsconfig 不带 DOM lib(库本体是 RN),用 globalThis 兜底访问浏览器 matchMedia,
+// 类型用 any 通过 strict(本文件只在 web bundle 命中,window 一定有)。
+const win: any = globalThis as any;
+
+/**
+ * web:监听系统「减弱动态效果」开关,返回当前是否开启;开关变化时自动更新。
+ * native 端走 reanimated 的 `ReduceMotion.System`,对应 `.ts` 版恒返回 false。
+ */
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState<boolean>(() =>
+    typeof win.matchMedia === 'function' ? win.matchMedia(QUERY).matches : false
+  );
+
+  useEffect(() => {
+    if (typeof win.matchMedia !== 'function') return;
+    const mq = win.matchMedia(QUERY);
+    const onChange = () => setReduced(mq.matches);
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, []);
+
+  return reduced;
+}

package/src/theme/useTheme.ts

@@ -9,8 +9,23 @@ const FALLBACK: ThemeContextValue = {
   shadow: lightShadow,
 };
 
+// 静默回退而非 throw:FALLBACK 是模块级稳定引用,useThemedStyles 缓存契约不受影响。
+// 缺点:漏包 ThemeProvider 时整 app 永远 light、暗色失效且零信号——
+// 因此在 dev 下一次性告警提示接入方补 Provider。
+// 用 typeof __DEV__ 守卫:裸 __DEV__ 在非 Metro 打包器(Webpack/Next.js)下会 ReferenceError,
+// logger.ts:12 已有同等先例。
+let _warnedMissingProvider = false;
+
 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;
 }
 

package/src/utils/logger/logger.ts

@@ -61,9 +61,13 @@ export function getLogLevel(): LogLevel {
 
 export function addTransport(t: LogTransport): void {
   removeTransport(t.id);
-  state.transports.push(t);
+  // push 后立即赋新数组:保证 emit 的 for-of 迭代期间若调用 addTransport,
+  // 迭代的旧快照不受影响(重入安全)。
+  state.transports = [...state.transports, t];
 }
 
 export function removeTransport(id: string): void {
+  // filter 返回新数组,不原地变更 —— 保证 emit 的 for-of 迭代期间若调用
+  // removeTransport(自移除等场景),迭代的旧快照仍完整走完(重入安全)。
   state.transports = state.transports.filter((t) => t.id !== id);
 }

package/src/utils/testID/testID.ts

@@ -1,17 +1,20 @@
 /**
  * `childTestID` —— 把"父 testID + 子 id → 子 testID"的拼接逻辑收口。
  *
- * 业务侧 7 处 list-like 组件(Tabs / Segmented / TabBar / Grid / Task /
- * Sources / ChainOfThought)重复同一三元:
+ * 本仓已接入的 list-like 组件(Tabs / Segmented / TabBar / Grid)原来各自重复:
  *
  * ```ts
  * const itemTestID = item.testID ?? (testID ? `${testID}-${item.id}` : undefined);
  * ```
  *
  * 抽 helper:
- * - `override` 命中 → 用 caller 显式指定
+ * - `override` 命中(truthy)→ 用 caller 显式指定
  * - 父 `parent` 缺失 → undefined(testID 不强制)
  * - 都没问题 → `{parent}-{id}` 拼接
+ *
+ * 注意:与旧式 `??` 不同,**空串 override 视为未提供、回落拼接**。
+ * 这是刻意设计:空 testID 没有语义价值,用例已钉死此边界
+ * (`__tests__/utils/testID.test.ts:31-33`),勿改回 `??` 判定。
  */
 export function childTestID(
   parent: string | undefined,

package/lib/module/components/index.js

@@ -1,5 +0,0 @@
-"use strict";
-
-export * from "./ui/index.js";
-export * from "./business/index.js";
-//# sourceMappingURL=index.js.map

package/lib/module/components/index.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../src","sources":["components/index.ts"],"mappings":";;AAAA,cAAc,eAAM;AACpB,cAAc,qBAAY","ignoreList":[]}

package/lib/typescript/src/components/index.d.ts

@@ -1,3 +0,0 @@
-export * from './ui';
-export * from './business';
-//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/components/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,MAAM,CAAC;AACrB,cAAc,YAAY,CAAC"}

package/src/components/index.ts

@@ -1,2 +0,0 @@
-export * from './ui';
-export * from './business';