@unif/react-native-design 0.28.0 → 0.30.0

package/src/components/ui/AvatarGroup/AvatarGroup.tsx

@@ -0,0 +1,147 @@
+import React, { useEffect } from 'react';
+import { Text, View, type ViewStyle } from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import {
+  pressedOpacity,
+  scaleFontMetric,
+  useColors,
+  useFontScale,
+  useThemedStyles,
+} from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
+import { Avatar } from '../Avatar';
+import { resolveAvatarBorderRadius, sizingFor } from '../Avatar/styles';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+import { resolveAvatarGroupLayout } from './layout';
+import { normalizeAvatarGroup } from './normalize';
+import { makeStyles } from './styles';
+import type { AvatarGroupProps } from './types';
+
+const log = createLogger('AvatarGroup');
+const warned = new Set<string>();
+
+function warnOnce(key: string, message: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  log.warn(message);
+}
+
+/** 重叠头像组；只拥有布局、溢出计数和可选溢出 action。 */
+export function AvatarGroup({
+  items,
+  size = 'md',
+  shape = 'circle',
+  max,
+  style,
+  testID,
+  onOverflowPress,
+  overflowAccessibilityLabel,
+  overflowAccessibilityHint,
+}: AvatarGroupProps): React.JSX.Element | null {
+  const colors = useColors();
+  const fontScale = useFontScale();
+  const styles = useThemedStyles(makeStyles);
+  const normalized = normalizeAvatarGroup(items, max);
+  const layout = resolveAvatarGroupLayout(size);
+  const avatarSizing = sizingFor(size);
+  const overflowFontSize = scaleFontMetric(avatarSizing.fs, fontScale);
+  const customOverflowLabel = normalizeNonBlankText(overflowAccessibilityLabel);
+  const hasBlankOverflowLabel =
+    normalized.overflowCount > 0 &&
+    onOverflowPress !== undefined &&
+    overflowAccessibilityLabel !== undefined &&
+    customOverflowLabel === undefined;
+
+  useEffect(() => {
+    if (typeof __DEV__ === 'undefined' || !__DEV__) return;
+    if (normalized.invalidMax) {
+      warnOnce(
+        `max:${String(max)}`,
+        `max 必须是大于等于 2 的有限整数，传入 ${String(max)}，已展示全部成员。`
+      );
+    }
+    if (hasBlankOverflowLabel) {
+      warnOnce(
+        'overflowAccessibilityLabel:blank',
+        'overflowAccessibilityLabel 不能为空白，已回退默认名称。'
+      );
+    }
+  }, [hasBlankOverflowLabel, max, normalized.invalidMax]);
+
+  if (items.length === 0) return null;
+
+  const slotStyle = (index: number): ViewStyle => ({
+    borderColor: colors.surface,
+    borderWidth: layout.borderWidth,
+    marginStart: index === 0 ? 0 : -layout.overlap,
+    zIndex: index,
+  });
+  const overflowCount = normalized.overflowCount;
+  const overflowLabel = `+${overflowCount}`;
+  const overflowA11yLabel =
+    onOverflowPress === undefined
+      ? `还有 ${overflowCount} 位成员`
+      : (customOverflowLabel ?? `查看其余 ${overflowCount} 位成员`);
+  const overflowStyle: ViewStyle = {
+    ...slotStyle(normalized.visibleItems.length),
+    width: layout.box,
+    height: layout.box,
+    borderRadius: resolveAvatarBorderRadius(size, shape),
+    backgroundColor: colors.primaryContainer,
+  };
+  const overflowText = (
+    <Text
+      style={[
+        styles.overflowText,
+        { color: colors.primary, fontSize: overflowFontSize },
+      ]}
+      numberOfLines={1}
+    >
+      {overflowLabel}
+    </Text>
+  );
+
+  return (
+    <View style={[styles.root, style]} testID={testID}>
+      {normalized.visibleItems.map((item, index) => (
+        <Avatar
+          key={item.key}
+          label={item.label}
+          source={item.source}
+          variant={item.variant}
+          size={size}
+          shape={shape}
+          style={slotStyle(index)}
+        />
+      ))}
+      {overflowCount === 0 ? null : onOverflowPress === undefined ? (
+        <View
+          accessible
+          accessibilityLabel={overflowA11yLabel}
+          style={[styles.overflow, overflowStyle]}
+          testID={childTestID(testID, 'overflow')}
+        >
+          {overflowText}
+        </View>
+      ) : (
+        <Pressable
+          accessible
+          accessibilityRole="button"
+          accessibilityLabel={overflowA11yLabel}
+          accessibilityHint={overflowAccessibilityHint}
+          onPress={onOverflowPress}
+          hitSlop={layout.hitSlop}
+          style={({ pressed }) => [
+            styles.overflow,
+            overflowStyle,
+            { opacity: pressed ? pressedOpacity : 1 },
+          ]}
+          testID={childTestID(testID, 'overflow')}
+        >
+          {overflowText}
+        </Pressable>
+      )}
+    </View>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { AvatarGroup } from './AvatarGroup';
+export type { AvatarGroupItem, AvatarGroupProps } from './types';

package/src/components/ui/AvatarGroup/layout.ts

@@ -0,0 +1,56 @@
+import { avatar, fixed, r, space } from '../../../theme';
+import type { AvatarSize } from '../Avatar';
+
+export type AvatarGroupHitSlop = Readonly<{
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}>;
+
+export type ResolvedAvatarGroupLayout = Readonly<{
+  box: number;
+  overlap: number;
+  borderWidth: number;
+  hitSlop: AvatarGroupHitSlop;
+}>;
+
+/** 五档尺寸共享的重叠、分隔边与 44pt 命中区几何。 */
+export function resolveAvatarGroupLayout(
+  size: AvatarSize
+): ResolvedAvatarGroupLayout {
+  const box = avatar[size];
+  let overlap: number;
+  let borderWidth: number;
+
+  switch (size) {
+    case 'xs':
+      overlap = space['1'];
+      borderWidth = r(1);
+      break;
+    case 'sm':
+      overlap = space['2'];
+      borderWidth = r(1);
+      break;
+    case 'md':
+      overlap = space['3'];
+      borderWidth = r(1);
+      break;
+    case 'lg':
+      overlap = space['4'];
+      borderWidth = r(2);
+      break;
+    case 'xl':
+      overlap = space['6'];
+      borderWidth = r(2);
+      break;
+  }
+
+  const inset = Math.max(0, (fixed.hitTarget - box) / 2);
+  return {
+    box,
+    overlap,
+    borderWidth,
+    hitSlop: { top: inset, right: inset, bottom: inset, left: inset },
+  };
+}

package/src/components/ui/AvatarGroup/normalize.ts

@@ -0,0 +1,28 @@
+import type { AvatarGroupItem } from './types';
+
+export type NormalizedAvatarGroup = Readonly<{
+  visibleItems: readonly AvatarGroupItem[];
+  overflowCount: number;
+  invalidMax: boolean;
+}>;
+
+/** AvatarGroup 唯一的 max 与可见成员归一化入口。 */
+export function normalizeAvatarGroup(
+  items: readonly AvatarGroupItem[],
+  max: number | undefined
+): NormalizedAvatarGroup {
+  const invalidMax =
+    max !== undefined &&
+    (!Number.isFinite(max) || !Number.isInteger(max) || max < 2);
+
+  if (max === undefined || invalidMax || items.length <= max) {
+    return { visibleItems: items, overflowCount: 0, invalidMax };
+  }
+
+  const visibleCount = max - 1;
+  return {
+    visibleItems: items.slice(0, visibleCount),
+    overflowCount: items.length - visibleCount,
+    invalidMax: false,
+  };
+}

package/src/components/ui/AvatarGroup/styles.ts

@@ -0,0 +1,19 @@
+import { StyleSheet } from 'react-native';
+import { fw, type ColorTokens } from '../../../theme';
+
+export const makeStyles = (_colors: ColorTokens) =>
+  StyleSheet.create({
+    root: {
+      alignItems: 'center',
+      flexDirection: 'row',
+    },
+    overflow: {
+      alignItems: 'center',
+      justifyContent: 'center',
+      overflow: 'hidden',
+    },
+    overflowText: {
+      fontWeight: fw.semi,
+      lineHeight: undefined,
+    },
+  });

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

@@ -0,0 +1,40 @@
+import type { ImageSourcePropType, StyleProp, ViewStyle } from 'react-native';
+import type { AvatarShape, AvatarSize, AvatarVariant } from '../Avatar';
+
+export type AvatarGroupItem = Readonly<{
+  /** 列表内唯一且稳定的身份键。 */
+  key: string;
+  /** 可见回退文字与 Avatar accessible name。 */
+  label: string;
+  source?: ImageSourcePropType;
+  variant?: AvatarVariant;
+}>;
+
+type SharedAvatarGroupProps = {
+  items: readonly AvatarGroupItem[];
+  /** 所有成员共用的尺寸，默认 'md'。 */
+  size?: AvatarSize;
+  /** 所有成员与溢出位共用的形态，默认 'circle'。 */
+  shape?: AvatarShape;
+  /** 最大视觉位数量，包含 +N 溢出位，必须是大于等于 2 的整数。 */
+  max?: number;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+};
+
+type StaticOverflowProps = {
+  onOverflowPress?: never;
+  overflowAccessibilityLabel?: never;
+  overflowAccessibilityHint?: never;
+};
+
+type ActionableOverflowProps = {
+  onOverflowPress: () => void;
+  /** 默认按实际数量生成“查看其余 N 位成员”。 */
+  overflowAccessibilityLabel?: string;
+  /** 描述打开弹层、抽屉或跳转等消费端结果。 */
+  overflowAccessibilityHint?: string;
+};
+
+export type AvatarGroupProps = SharedAvatarGroupProps &
+  (StaticOverflowProps | ActionableOverflowProps);

package/src/components/ui/CircularProgress/CircularProgress.tsx

@@ -0,0 +1,111 @@
+import { Text, View } from 'react-native';
+import type { TextStyle, ViewStyle } from 'react-native';
+import Svg, { Circle } from 'react-native-svg';
+import { r, type, useColors } from '../../../theme';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { normalizeCircularProgress } from './normalizeCircularProgress';
+import type { CircularProgressProps } from './types';
+
+const OUTER_CENTER_STYLE = {
+  alignItems: 'center',
+  justifyContent: 'center',
+} as const satisfies ViewStyle;
+
+const VISUAL_CONTAINER_STYLE = {
+  position: 'relative',
+} as const satisfies ViewStyle;
+
+const LABEL_CENTER_STYLE = {
+  fontWeight: '600',
+  left: 0,
+  position: 'absolute',
+  textAlign: 'center',
+  top: 0,
+} as const satisfies TextStyle;
+
+export function CircularProgress({
+  value,
+  size = r(32),
+  thickness = r(2),
+  color,
+  trackColor,
+  showLabel = false,
+  labelColor,
+  accessibilityLabel = '进度',
+  style,
+  testID,
+}: CircularProgressProps): React.JSX.Element {
+  const colors = useColors();
+  const normalized = normalizeCircularProgress({ value, size, thickness });
+  const {
+    circumference,
+    dashOffset,
+    percentage,
+    radius,
+    safeSize,
+    safeThickness,
+  } = normalized;
+  const center = safeSize / 2;
+
+  return (
+    <View
+      accessible
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="progressbar"
+      accessibilityValue={{
+        min: 0,
+        max: 100,
+        now: percentage,
+        text: `${percentage}%`,
+      }}
+      style={[{ height: safeSize, width: safeSize }, style, OUTER_CENTER_STYLE]}
+      testID={testID}
+    >
+      <View
+        style={[{ height: safeSize, width: safeSize }, VISUAL_CONTAINER_STYLE]}
+        {...A11Y_HIDDEN_PROPS}
+      >
+        <Svg height={safeSize} width={safeSize}>
+          <Circle
+            cx={center}
+            cy={center}
+            fill="none"
+            r={radius}
+            stroke={trackColor ?? colors.outline}
+            strokeWidth={safeThickness}
+          />
+          <Circle
+            cx={center}
+            cy={center}
+            fill="none"
+            r={radius}
+            rotation={-90}
+            originX={center}
+            originY={center}
+            stroke={color ?? colors.primary}
+            strokeDasharray={circumference}
+            strokeDashoffset={dashOffset}
+            strokeLinecap="round"
+            strokeWidth={safeThickness}
+          />
+        </Svg>
+        {showLabel ? (
+          <Text
+            style={[
+              {
+                color: labelColor ?? colors.foreground,
+                fontSize: type.nano,
+                height: safeSize,
+                lineHeight: safeSize,
+                width: safeSize,
+              },
+              LABEL_CENTER_STYLE,
+            ]}
+          >
+            {`${percentage}%`}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { CircularProgress } from './CircularProgress';
+export type { CircularProgressProps } from './types';

package/src/components/ui/CircularProgress/normalizeCircularProgress.ts

@@ -0,0 +1,64 @@
+import { createLogger } from '../../../utils/logger';
+
+const log = createLogger('CircularProgress');
+const warnedKeys = new Set<string>();
+
+export type NormalizedCircularProgress = Readonly<{
+  safeValue: number;
+  percentage: number;
+  safeSize: number;
+  safeThickness: number;
+  radius: number;
+  circumference: number;
+  dashOffset: number;
+}>;
+
+function warnOnce(key: string, message: string): void {
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  log.warn(message);
+}
+
+export function normalizeCircularProgress(input: {
+  value: number;
+  size: number;
+  thickness: number;
+}): NormalizedCircularProgress {
+  const { value, size, thickness } = input;
+
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    warnOnce(
+      `value:${value}`,
+      `value 应为 0..1 的有限数，传入 ${value}，已收敛到安全范围`
+    );
+  }
+  if (!Number.isFinite(size) || size < 16) {
+    warnOnce(`size:${size}`, `size 应为 ≥16 的有限数，传入 ${size}，已钳到 16`);
+  }
+  if (!Number.isFinite(thickness) || thickness <= 0) {
+    warnOnce(
+      `thickness:${thickness}`,
+      `thickness 应为正有限数，传入 ${thickness}，已 fallback 为 2`
+    );
+  }
+
+  const safeValue = Number.isFinite(value)
+    ? Math.min(1, Math.max(0, value))
+    : 0;
+  const safeSize = Number.isFinite(size) && size >= 16 ? size : 16;
+  const fallbackThickness =
+    Number.isFinite(thickness) && thickness > 0 ? thickness : 2;
+  const safeThickness = Math.min(fallbackThickness, safeSize / 2);
+  const radius = (safeSize - safeThickness) / 2;
+  const circumference = 2 * Math.PI * radius;
+
+  return {
+    safeValue,
+    percentage: Math.round(safeValue * 100),
+    safeSize,
+    safeThickness,
+    radius,
+    circumference,
+    dashOffset: circumference * (1 - safeValue),
+  };
+}

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

@@ -0,0 +1,24 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type CircularProgressProps = {
+  /** 当前进度，使用 0..1；越界值会收敛到边界，非有限值按 0 处理。 */
+  value: number;
+  /** 圆环直径，默认 32，最小 16。 */
+  size?: number;
+  /** 圆环描边宽度，默认 2，最大为半径。 */
+  thickness?: number;
+  /** 进度颜色，默认 c.primary。 */
+  color?: string;
+  /** 轨道颜色，默认 c.outline。 */
+  trackColor?: string;
+  /** 是否在圆环中央显示取整后的百分比，默认 false。 */
+  showLabel?: boolean;
+  /** 百分比文字颜色，默认 c.foreground。 */
+  labelColor?: string;
+  /** 进度条可访问性名称，默认“进度”。 */
+  accessibilityLabel?: string;
+  /** 外层布局样式。 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位。 */
+  testID?: string;
+};

package/src/components/ui/index.ts

@@ -1,5 +1,12 @@
 export { Avatar } from './Avatar';
-export type { AvatarProps, AvatarSize, AvatarVariant } from './Avatar';
+export type {
+  AvatarProps,
+  AvatarShape,
+  AvatarSize,
+  AvatarVariant,
+} from './Avatar';
+export { AvatarGroup } from './AvatarGroup';
+export type { AvatarGroupItem, AvatarGroupProps } from './AvatarGroup';
 export { BlurLayer } from './BlurLayer';
 export type { BlurLayerProps } from './BlurLayer';
 export { Button } from './Button';
@@ -20,6 +27,8 @@ export { Checkbox } from './Checkbox';
 export type { CheckboxProps } from './Checkbox';
 export { Chip } from './Chip';
 export type { ChipProps } from './Chip';
+export { CircularProgress } from './CircularProgress';
+export type { CircularProgressProps } from './CircularProgress';
 export { confirm, ConfirmHost } from './Confirm';
 export type { ConfirmOptions } from './Confirm';
 export { DrawerHeader } from './DrawerHeader';