@unif/react-native-design 0.8.1 → 0.9.0

package/lib/typescript/src/theme/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../../src/theme/tokens.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ,QAInB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;IAYf,8EAA8E;;IAE9E,uCAAuC;;IAEvC;2DACuD;;IAEvD,gDAAgD;;IAEhD,uDAAuD;;IAEvD,yCAAyC;;CAEjC,CAAC;AAEX,eAAO,MAAM,EAAE;;;;;;CAML,CAAC;AAEX,eAAO,MAAM,KAAK;;;;;;;;;;;;CAYR,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AAEX;4DAC4D;AAC5D,eAAO,MAAM,IAAI;;;;;;;CAOP,CAAC;AAEX;;YAEY;AACZ,eAAO,MAAM,OAAO;;;;CAIV,CAAC;AAEX,8CAA8C;AAC9C,eAAO,MAAM,GAAG;IACd,6DAA6D;;CAErD,CAAC;AAEX;+BAC+B;AAC/B,eAAO,MAAM,KAAK;;;;;CAKR,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../../src/theme/tokens.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ,QAInB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;;;;;IAYf,gEAAgE;;IAEhE,uCAAuC;;IAEvC;2DACuD;;IAEvD,gDAAgD;;IAEhD,wCAAwC;;IAExC,yCAAyC;;CAEjC,CAAC;AAEX,eAAO,MAAM,EAAE;;;;;;CAML,CAAC;AAEX,eAAO,MAAM,KAAK;;;;;;;;;;;;CAYR,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AAEX;4DAC4D;AAC5D,eAAO,MAAM,IAAI;;;;;;;CAOP,CAAC;AAEX;;YAEY;AACZ,eAAO,MAAM,OAAO;;;;CAIV,CAAC;AAEX,8CAA8C;AAC9C,eAAO,MAAM,GAAG;IACd,6CAA6C;;CAErC,CAAC;AAEX;+BAC+B;AAC/B,eAAO,MAAM,KAAK;;;;;CAKR,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAEX;;4CAE4C;AAC5C,eAAO,MAAM,cAAc,MAAM,CAAC"}

package/lib/typescript/src/theme/usePrefersReducedMotion.d.ts

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

package/lib/typescript/src/theme/usePrefersReducedMotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePrefersReducedMotion.d.ts","sourceRoot":"","sources":["../../../../src/theme/usePrefersReducedMotion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD"}

package/lib/typescript/src/theme/usePrefersReducedMotion.web.d.ts

@@ -0,0 +1,6 @@
+/**
+ * web:监听系统「减弱动态效果」开关,返回当前是否开启;开关变化时自动更新。
+ * native 端走 reanimated 的 `ReduceMotion.System`,对应 `.ts` 版恒返回 false。
+ */
+export declare function usePrefersReducedMotion(): boolean;
+//# sourceMappingURL=usePrefersReducedMotion.web.d.ts.map

package/lib/typescript/src/theme/usePrefersReducedMotion.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePrefersReducedMotion.web.d.ts","sourceRoot":"","sources":["../../../../src/theme/usePrefersReducedMotion.web.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAcjD"}

package/lib/typescript/src/theme/useTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../../../src/theme/useTheme.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAUvE,wBAAgB,QAAQ,IAAI,iBAAiB,CAG5C;AAED,wBAAgB,SAAS,mCAExB;AAED,wBAAgB,SAAS,oCAExB"}
+{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../../../src/theme/useTheme.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAiBvE,wBAAgB,QAAQ,IAAI,iBAAiB,CAW5C;AAED,wBAAgB,SAAS,mCAExB;AAED,wBAAgB,SAAS,oCAExB"}

package/lib/typescript/src/utils/logger/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../../src/utils/logger/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAa,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAuCzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAGlD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEhD"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../../src/utils/logger/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAa,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAuCzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,CAKlD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAIhD"}

package/lib/typescript/src/utils/testID/testID.d.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 declare function childTestID(parent: string | undefined, id: string | number, override?: string): string | undefined;
 //# sourceMappingURL=testID.d.ts.map

package/lib/typescript/src/utils/testID/testID.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testID.d.ts","sourceRoot":"","sources":["../../../../../src/utils/testID/testID.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAGpB"}
+{"version":3,"file":"testID.d.ts","sourceRoot":"","sources":["../../../../../src/utils/testID/testID.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAGpB"}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@unif/react-native-design",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Unif 设计系统:theme + icons + utils + components",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
       "source": "./src/index.tsx",

package/src/components/business/AvatarWithRing/AvatarWithRing.tsx

@@ -1,4 +1,4 @@
-import React, { useId, useMemo } from 'react';
+import React, { useMemo } from 'react';
 import { StyleSheet, Text, View } from 'react-native';
 import Svg, {
   Defs,
@@ -7,6 +7,7 @@ import Svg, {
   Stop,
 } from 'react-native-svg';
 import { avatarGradient, useTheme } from '../../../theme';
+import { useSvgId } from '../useSvgId';
 import { makeAvatarStyles } from './styles';
 import type { AvatarWithRingProps } from './types';
 
@@ -22,17 +23,17 @@ export function AvatarWithRing({
   size = 64,
   ringColor,
   style,
+  testID,
 }: AvatarWithRingProps): React.JSX.Element {
   const { colors: c, shadow } = useTheme();
-  const autoId = useId();
-  const id = `av-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const id = useSvgId('av');
   const { inner, styles } = useMemo(
     () =>
       makeAvatarStyles(size, ringColor ?? c.avatarRing, shadow.brandAvatar, c),
     [size, ringColor, c, shadow.brandAvatar]
   );
   return (
-    <View style={[styles.shell, style]}>
+    <View style={[styles.shell, style]} testID={testID}>
       <View style={styles.avatarCore}>
         <Svg width={inner} height={inner} style={StyleSheet.absoluteFill}>
           <Defs>

package/src/components/business/AvatarWithRing/styles.ts

@@ -1,5 +1,8 @@
 import { StyleSheet, type ViewStyle } from 'react-native';
 import { fw, r, type ColorTokens } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+
+const log = createLogger('AvatarWithRing');
 
 /**
  * 头像样式工厂 —— **非标 maker 签名**:`(size, ringColor, shadowStyle, c)` 4 参,
@@ -26,9 +29,24 @@ export const makeAvatarStyles = (
   shadowStyle: ViewStyle,
   c: ColorTokens
 ) => {
-  const dim = r(size);
+  // 防御非法 size:NaN / 负数 / 0 会导致 inner 为负传入 SVG。
+  // 最小合理值 = ringWidth*2 + 1(至少 1pt 圆心可见)。
+  // ringWidth 下限为 2(见下方 Math.max),所以 size 至少要大于 4pt。
+  const MIN_SIZE = 5;
+  const safeSize =
+    Number.isFinite(size) && size >= MIN_SIZE
+      ? size
+      : (() => {
+          if (__DEV__) {
+            log.warn(
+              `AvatarWithRing: size=${size} 无效(须 ≥ ${MIN_SIZE}),已钳制为 ${MIN_SIZE}。`
+            );
+          }
+          return MIN_SIZE;
+        })();
+  const dim = r(safeSize);
   const half = dim / 2;
-  const ringWidth = Math.max(2, r(Math.round(size * 0.0625)));
+  const ringWidth = Math.max(2, r(Math.round(safeSize * 0.0625)));
   const inner = dim - ringWidth * 2;
   const innerHalf = inner / 2;
   const styles = StyleSheet.create({
@@ -50,7 +68,7 @@ export const makeAvatarStyles = (
       justifyContent: 'center',
     },
     label: {
-      fontSize: r(Math.round(size * 0.4)),
+      fontSize: r(Math.round(safeSize * 0.4)),
       fontWeight: fw.bold,
       color: c.onPrimary,
       letterSpacing: -0.5,

package/src/components/business/AvatarWithRing/types.ts

@@ -8,8 +8,10 @@ export type AvatarWithRingProps = {
    * 视觉占比:label 字号约 size * 0.40,ring 宽度约 size * 0.0625。
    */
   size?: number;
-  /** ring + 填充背景色,默认 c.primary。 */
+  /** ring 颜色,默认 c.avatarRing(白系半透明)。 */
   ringColor?: string;
   /** 容器附加样式(margin / position 等定位)。 */
   style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
 };

package/src/components/business/Decorations/GradientWash.tsx

@@ -1,4 +1,4 @@
-import React, { useId } from 'react';
+import React from 'react';
 import { View } from 'react-native';
 import Svg, {
   Defs,
@@ -6,8 +6,48 @@ import Svg, {
   Rect,
   Stop,
 } from 'react-native-svg';
+import { useSvgId } from '../useSvgId';
 import type { GradientWashProps } from './types';
 
+/** 解析 rgba(r,g,b,a) 或 #RRGGBBAA 字符串拆出 alpha,返回 { color: rgb/hex, opacity }。
+ *  非支持格式(rgb / hex / named / hsl 等)原样返回 + opacity=1。
+ *
+ *  支持格式:
+ *  - 逗号式 rgba(r,g,b,a)       → 拆出 alpha
+ *  - 8 位 hex #RRGGBBAA          → 末两位转 alpha
+ *  - 其它(rgb / hex6 / named)   → 原样 + opacity=1
+ *
+ *  Why:react-native-svg `<Stop stopColor>` 接 rgba 时 alpha 可能被忽略
+ *  (stopColor 只解析 RGB,需要 stopOpacity 分离),拆分后跨平台一致。 */
+export function parseRgba(color: string): { color: string; opacity: number } {
+  // 逗号式 rgba(r,g,b,a)
+  const mRgba = color.match(/^rgba\(([^)]+)\)$/);
+  if (mRgba?.[1]) {
+    const parts = mRgba[1].split(',').map((s) => s.trim());
+    if (parts.length === 4) {
+      const alphaStr = parts[3];
+      if (alphaStr !== undefined) {
+        const alpha = parseFloat(alphaStr);
+        if (!Number.isNaN(alpha)) {
+          return {
+            color: `rgb(${parts.slice(0, 3).join(',')})`,
+            opacity: alpha,
+          };
+        }
+      }
+    }
+  }
+  // 8 位 hex #RRGGBBAA
+  const mHex8 = color.match(
+    /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/
+  );
+  if (mHex8?.[1] && mHex8[2] && mHex8[3] && mHex8[4]) {
+    const alpha = parseInt(mHex8[4], 16) / 255;
+    return { color: `#${mHex8[1]}${mHex8[2]}${mHex8[3]}`, opacity: alpha };
+  }
+  return { color, opacity: 1 };
+}
+
 /**
  * 垂直线性渐变 wash —— 全宽矩形 + 顶到底的 SVG LinearGradient。
  *
@@ -17,30 +57,11 @@ import type { GradientWashProps } from './types';
  *
  * `pointerEvents="none"` 透传,装饰层不捕事件。
  *
- * gradientId 不传时用 `useId()` 自动唯一;React 19 useId 返回含冒号 `:r0:`,
- * 不是合法 SVG id 字符,sanitize 后再用。
+ * gradientId 不传时由 useSvgId 自动生成唯一合法 id(消毒 React 19 useId 的冒号)。
  */
-/** 解析 rgba(r,g,b,a) 字符串拆出 alpha,返回 { color: rgb(...), opacity }。
- *  非 rgba 输入(hex / rgb / named)原样返回 + opacity=1。
- *
- *  Why:react-native-svg `<Stop stopColor>` 接 rgba 时 alpha 可能被忽略
- *  (stopColor 只解析 RGB,需要 stopOpacity 分离),拆分后跨平台一致。 */
-function parseRgba(color: string): { color: string; opacity: number } {
-  const m = color.match(/^rgba\(([^)]+)\)$/);
-  if (!m || !m[1]) return { color, opacity: 1 };
-  const parts = m[1].split(',').map((s) => s.trim());
-  if (parts.length !== 4) return { color, opacity: 1 };
-  const alphaStr = parts[3];
-  if (alphaStr === undefined) return { color, opacity: 1 };
-  const alpha = parseFloat(alphaStr);
-  if (Number.isNaN(alpha)) return { color, opacity: 1 };
-  return { color: `rgb(${parts.slice(0, 3).join(',')})`, opacity: alpha };
-}
-
 export function GradientWash(props: GradientWashProps): React.JSX.Element {
   const { height, style, gradientId } = props;
-  const autoId = useId();
-  const id = gradientId ?? `gw-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const id = useSvgId('gw', gradientId);
   const stops = props.stops ?? [
     { offset: 0, color: props.color, opacity: props.fromOpacity ?? 0.1 },
     { offset: 1, color: props.color, opacity: props.toOpacity ?? 0 },
@@ -62,6 +83,9 @@ export function GradientWash(props: GradientWashProps): React.JSX.Element {
           >
             {stops.map((s, i) => {
               const parsed = parseRgba(s.color);
+              // s.opacity 显式传入时优先;未传(undefined)时使用 parseRgba 解出的值。
+              // 注:这里是替换而非相乘 —— stops 里的 opacity 字段语义是"最终不透明度",
+              // 若需要与解析色 alpha 相乘请在构建 stops 时预先合并。
               const opacity = s.opacity ?? parsed.opacity;
               return (
                 <Stop

package/src/components/business/Decorations/RadialHalo.tsx

@@ -1,4 +1,4 @@
-import React, { useId } from 'react';
+import React from 'react';
 import { View } from 'react-native';
 import Svg, {
   Defs,
@@ -6,6 +6,8 @@ import Svg, {
   RadialGradient as SvgRadialGradient,
   Stop,
 } from 'react-native-svg';
+import { useSvgId } from '../useSvgId';
+import { parseRgba } from './GradientWash';
 import type { RadialHaloProps } from './types';
 
 const DEFAULT_MAX_OPACITY = 0.16;
@@ -35,13 +37,15 @@ export function RadialHalo({
 }: RadialHaloProps): React.JSX.Element {
   const w = size;
   const h = height ?? size;
-  const autoId = useId();
-  const id = gradientId ?? `rh-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const id = useSvgId('rh', gradientId);
   const resolvedStops = stops ?? buildStops(maxOpacity);
   const cx = w / 2;
   const cy = h / 2;
   // farthest-corner:r = 中心到最远角的距离
   const r = Math.sqrt(cx * cx + cy * cy);
+  // parseRgba:react-native-svg stopColor 只解析 RGB,rgba/8位hex 的 alpha 会被忽略;
+  // 拆分为 stopColor(rgb/hex6) + stopOpacity 后跨平台一致(与 GradientWash 同理)。
+  const { color: stopColor } = parseRgba(color);
   return (
     <View pointerEvents="none" style={[{ width: w, height: h }, style]}>
       <Svg width={w} height={h}>
@@ -61,7 +65,7 @@ export function RadialHalo({
               <Stop
                 key={`${s.offset}-${i}`}
                 offset={s.offset}
-                stopColor={color}
+                stopColor={stopColor}
                 stopOpacity={s.opacity}
               />
             ))}

package/src/components/business/Decorations/ScreenBackdrop.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { StyleSheet, useWindowDimensions, View } from 'react-native';
-import { useColors, useTheme, warmOrangePalette } from '../../../theme';
+import { r, useColors, useTheme, warmOrangePalette } from '../../../theme';
 import { GradientWash } from './GradientWash';
 import { RadialHalo } from './RadialHalo';
 import type {
@@ -39,9 +39,22 @@ const PRESETS: Record<ScreenBackdropPreset, PresetConfig> = {
     light: buildStops(warmOrangePalette.light, WARM_ORANGE_OFFSETS),
     dark: buildStops(warmOrangePalette.dark, WARM_ORANGE_OFFSETS),
     halos: [
-      { size: 520, height: 420, maxOpacity: 0.22, top: -120, centerX: true },
-      { size: 560, height: 380, maxOpacity: 0.18, bottom: -160, centerX: true },
-      { size: 220, maxOpacity: 0.16, top: 180, right: -80 },
+      // [L-88] halo 几何走 r() 对齐缩放纪律;maxOpacity / centerX 是无单位值,不缩放。
+      {
+        size: r(520),
+        height: r(420),
+        maxOpacity: 0.22,
+        top: r(-120),
+        centerX: true,
+      },
+      {
+        size: r(560),
+        height: r(380),
+        maxOpacity: 0.18,
+        bottom: r(-160),
+        centerX: true,
+      },
+      { size: r(220), maxOpacity: 0.16, top: r(180), right: r(-80) },
     ],
   },
 };
@@ -70,6 +83,7 @@ export function ScreenBackdrop({
   halos,
   children,
   style,
+  testID,
 }: ScreenBackdropProps): React.JSX.Element {
   const c = useColors();
   const { scheme } = useTheme();
@@ -84,6 +98,7 @@ export function ScreenBackdrop({
   return (
     <View
       style={[backdropStyles.root, { backgroundColor: c.background }, style]}
+      testID={testID}
     >
       {resolvedStops ? (
         <GradientWash
@@ -102,7 +117,10 @@ export function ScreenBackdrop({
             height={h.height}
             color={h.color ?? c.primary}
             maxOpacity={h.maxOpacity}
-            gradientId={`screen-backdrop-halo-${i}`}
+            // [L-60] 不传 gradientId —— 让 RadialHalo 走自己的 useSvgId(useId) 默认值。
+            // 实例内同名在多 ScreenBackdrop 同挂(keep-mounted 栈、导航页)时会导致
+            // web DOM SVG 的 url(#id) 命中文档首个同名渐变,造成跨实例渐变串台。
+            // useId 保证每次挂载唯一,「实例内多 halo 不同 id」也由 useSvgId 前缀+'rh' 保证。
             style={[
               backdropStyles.haloAbsolute,
               { top: h.top, bottom: h.bottom, left, right },

package/src/components/business/Decorations/index.ts

@@ -1,7 +1,11 @@
+// Decorations 族:GradientWash / RadialHalo / ScreenBackdrop 三件强内聚,
+// 共享 GradientStop 类型 + parseRgba 工具 —— 刻意共居一目录、共享 types.ts,
+// 不拆单组件目录;CLAUDE.md 组件约定的族式聚合例外。
 export { GradientWash } from './GradientWash';
 export { RadialHalo } from './RadialHalo';
 export { ScreenBackdrop } from './ScreenBackdrop';
 export type {
+  GradientStop,
   GradientWashProps,
   RadialHaloProps,
   ScreenBackdropHalo,

package/src/components/business/Decorations/types.ts

@@ -100,4 +100,6 @@ export type ScreenBackdropProps = {
   children?: ReactNode;
   /** 外层附加样式 */
   style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
 };

package/src/components/business/GlassStats/GlassStats.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { Text, View } from 'react-native';
-import { BlurLayer } from '../../ui';
+import { BlurLayer } from '../../ui/BlurLayer';
 import { useThemedStyles } from '../../../theme';
 import { makeGlassStatsStyles } from './styles';
 import type { GlassStatsProps } from './types';
@@ -11,20 +11,24 @@ import type { GlassStatsProps } from './types';
  * BlurLayer 接管 backdrop 双层结构(BlurView soft + glassTintLight tint),
  * blurType 跟 scheme 自动切。
  */
-export function GlassStats({ items }: GlassStatsProps): React.JSX.Element {
+export function GlassStats({
+  items,
+  style,
+  testID,
+}: GlassStatsProps): React.JSX.Element {
   const styles = useThemedStyles(makeGlassStatsStyles);
   return (
     // 外层 shell 承担 shadow(无 overflow,iOS Core Animation masksToBounds=true
     // 会裁掉 outer shadow);内层 glass 承担 overflow:hidden + border 裁圆角。
     // 单层 overflow + shadow 在 iOS 上 shadow 完全不可见。
-    <View style={styles.glassShell}>
+    <View style={[styles.glassShell, style]} testID={testID}>
       <View style={styles.glass}>
         <BlurLayer intensity="soft" />
         {/* 顶部 1px inset 白高光,让数据条顶部"凸起" */}
         <View style={styles.topHighlight} pointerEvents="none" />
         <View style={styles.inner}>
           {items.map(([count, label], i) => (
-            <React.Fragment key={label}>
+            <React.Fragment key={`${label}-${i}`}>
               {i > 0 ? <View style={styles.sep} /> : null}
               <View style={styles.col}>
                 <Text style={styles.countText}>{count}</Text>

package/src/components/business/GlassStats/types.ts

@@ -1,7 +1,13 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
 /** 单元格元组 —— [count, label] —— count 已格式化好(如 '12' / '¥2,016') */
 export type GlassStatItem = readonly [count: string, label: string];
 
 export type GlassStatsProps = {
   /** 数据列。一般 2~4 列均可,不强制数量。 */
   items: ReadonlyArray<GlassStatItem>;
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
 };

package/src/components/business/VersionPill/VersionPill.tsx

@@ -9,19 +9,59 @@ export function VersionPill({
   version,
   build,
   statusColor,
+  versionPrefix = '版本 ',
+  buildPrefix = 'build ',
   style,
+  testID,
 }: VersionPillProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeVersionPillStyles);
   const dotColor = statusColor ?? c.success;
+  // build 的「省略」契约:undefined / null / "" 均视为空;字符串 "0" 不省略。
+  const hasBuild = build != null && build !== '';
+  // 状态点用颜色传达语义,SR 无法感知;整个 pill 作为分组提供无障碍合并读出。
+  const a11yLabel = hasBuild
+    ? `${versionPrefix}${version},${buildPrefix}${build}`
+    : `${versionPrefix}${version}`;
   return (
-    <View style={[styles.pill, style]}>
-      <View style={[styles.dot, { backgroundColor: dotColor }]} />
-      <Text style={styles.version}>版本 {version}</Text>
-      {build ? (
+    <View
+      accessible
+      accessibilityLabel={a11yLabel}
+      style={[styles.pill, style]}
+      testID={testID}
+    >
+      {/* 状态点仅颜色通道,屏幕阅读器由外层容器统一朗读,此处隐藏 */}
+      <View
+        style={[styles.dot, { backgroundColor: dotColor }]}
+        accessibilityElementsHidden
+        importantForAccessibility="no"
+      />
+      <Text
+        style={styles.version}
+        accessibilityElementsHidden
+        importantForAccessibility="no"
+      >
+        {versionPrefix}
+        {version}
+      </Text>
+      {hasBuild ? (
         <>
-          <Text style={styles.sep}>·</Text>
-          <Text style={styles.build}>build {build}</Text>
+          {/* 分隔符「·」无语义,隐藏于无障碍树 */}
+          <Text
+            style={styles.sep}
+            accessibilityElementsHidden
+            importantForAccessibility="no"
+          >
+            ·
+          </Text>
+          <Text
+            style={styles.build}
+            accessibilityElementsHidden
+            importantForAccessibility="no"
+          >
+            {buildPrefix}
+            {build}
+          </Text>
         </>
       ) : null}
     </View>

package/src/components/business/VersionPill/styles.ts

@@ -9,7 +9,7 @@ import {
 } from '../../../theme';
 
 /** VersionPill 样式工厂 —— hairline 描边 + surface 底胶囊。
- *  字号走 type.microPlus(11.5),与 SplashScreen / profileCard / carousel 共用。 */
+ *  字号走 type.microPlus(11.5),现仓内仅 VersionPill 消费。 */
 export const makeVersionPillStyles = (c: ColorTokens) =>
   StyleSheet.create({
     pill: {

package/src/components/business/VersionPill/types.ts

@@ -3,10 +3,22 @@ import type { StyleProp, ViewStyle } from 'react-native';
 export type VersionPillProps = {
   /** 版本号,如 "2.8.0"。 */
   version: string;
-  /** 可选 build 号;为空时省略分点与 build 字。 */
+  /** 可选 build 号;值为 null/undefined/"" 时省略分点与 build 字。 */
   build?: string;
   /** 状态点颜色,默认 c.success。 */
   statusColor?: string;
+  /**
+   * 版本号前缀文案,默认 "版本 "。
+   * 消费者可传 "v" / "Version " 等覆盖(含末尾空格)。
+   */
+  versionPrefix?: string;
+  /**
+   * build 号前缀文案,默认 "build "。
+   * 消费者可传 "Build " / "#" 等覆盖。
+   */
+  buildPrefix?: string;
   /** 容器附加样式覆盖。 */
   style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
 };

package/src/components/business/index.ts

@@ -5,6 +5,7 @@
 //   SmsCodeInput)留在 consumer 仓库
 export { GradientWash, RadialHalo, ScreenBackdrop } from './Decorations';
 export type {
+  GradientStop,
   GradientWashProps,
   RadialHaloProps,
   ScreenBackdropHalo,

package/src/components/business/useSvgId.ts

@@ -0,0 +1,17 @@
+import { useId } from 'react';
+
+/**
+ * SVG 渐变 id 生成 hook —— 消毒 React 19 useId 中的冒号字符。
+ *
+ * Why:React 19 的 useId() 返回含冒号(`:r0:`)的字符串,不是合法的 SVG id 字符
+ * (XML NCName 规则),直接用在 `<LinearGradient id>` / `<RadialGradient id>`
+ * 会导致 SVG 引用失败。sanitize 后拼上 prefix 保证唯一且合法。
+ *
+ * @param prefix  短前缀,区分同屏多 gradient(如 "gw" / "rh" / "av")。
+ * @param override 可选:外部传入的 gradientId;有值时直接返回,跳过 useId 分配。
+ */
+export function useSvgId(prefix: string, override?: string): string {
+  const autoId = useId();
+  if (override !== undefined) return override;
+  return `${prefix}-${autoId.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+}

package/src/components/ui/Avatar/Avatar.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useEffect, useState } from 'react';
 import { Image, Text, View } from 'react-native';
 import { useColors } from '../../../theme';
 import { paletteFor, sizingFor, styles } from './styles';
@@ -15,20 +15,25 @@ export function Avatar({
   size = 'md',
   variant = 'neutral',
   source,
+  style,
   testID,
 }: AvatarProps): React.JSX.Element {
   const c = useColors();
   const [imageFailed, setImageFailed] = useState(false);
-  // 避免 unmount 后 Image 网络回包仍调 setState 的 React warning
-  const mountedRef = useRef(true);
-  useEffect(
-    () => () => {
-      mountedRef.current = false;
-    },
-    []
-  );
+
+  // [M-20] React 18+ 已移除 unmount 后 setState 的 warning,mountedRef 守卫为死码,删除。
+  // [L-44] source 变化时重置 imageFailed,否则换图 URL 后仍展示 fallback 文字。
+  // source 可能是对象形态({ uri }),按 uri 字段做细粒度比较。
+  const uri =
+    source != null && typeof source === 'object' && 'uri' in source
+      ? (source as { uri?: string }).uri
+      : null;
+  useEffect(() => {
+    setImageFailed(false);
+  }, [uri, source]);
+
   const handleImageError = () => {
-    if (mountedRef.current) setImageFailed(true);
+    setImageFailed(true);
   };
   const dims = sizingFor(size);
   const palette = paletteFor(variant, c);
@@ -45,7 +50,9 @@ export function Avatar({
           borderRadius: dims.box / 2,
           backgroundColor: palette.bg,
         },
+        style,
       ]}
+      accessible={!!label}
       accessibilityLabel={label}
       testID={testID}
     >