@unif/react-native-design 0.33.1 → 0.35.0

package/src/components/ui/ActionMenuContent/ActionMenuContent.tsx

@@ -0,0 +1,118 @@
+import React, { useEffect, useState } from 'react';
+import { Pressable, Text, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { space, useThemedStyles } from '../../../theme';
+import { Button } from '../Button';
+import type { ActionMenuContentProps } from './types';
+import { makeStyles } from './styles';
+
+export function ActionMenuContent({
+  actions,
+  onClose,
+  presentation = 'dialog',
+  title,
+  cancelLabel = '取消',
+  style,
+  testID = 'action-menu',
+}: ActionMenuContentProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  const insets = useSafeAreaInsets();
+  const [confirmationId, setConfirmationId] = useState<string | null>(null);
+  const isSheet = presentation === 'sheet';
+  const confirming = actions.find(
+    (action) =>
+      action.id === confirmationId && action.confirmation !== undefined
+  );
+
+  useEffect(() => {
+    if (!confirming) setConfirmationId(null);
+  }, [confirming]);
+
+  const content = (
+    <Pressable
+      accessible={false}
+      testID={`${testID}-card`}
+      style={[
+        isSheet ? styles.sheetCard : styles.dialogCard,
+        isSheet && { paddingBottom: insets.bottom + space[5] },
+      ]}
+      onPress={(event) => event.stopPropagation()}
+    >
+      {title ? (
+        <Text
+          testID={`${testID}-title`}
+          style={styles.title}
+          numberOfLines={1}
+          ellipsizeMode="tail"
+        >
+          {title}
+        </Text>
+      ) : null}
+      {confirming?.confirmation ? (
+        <>
+          <Text style={styles.confirmation} accessibilityLiveRegion="polite">
+            {confirming.confirmation.message}
+          </Text>
+          <View style={styles.sheetActions}>
+            <Button
+              label={cancelLabel}
+              variant="neutral"
+              style={styles.sheetAction}
+              onPress={() => setConfirmationId(null)}
+            />
+            <Button
+              label={confirming.confirmation.confirmLabel}
+              variant="danger"
+              disabled={confirming.disabled}
+              loading={confirming.loading}
+              style={styles.sheetAction}
+              onPress={() => {
+                onClose();
+                confirming.onPress();
+              }}
+            />
+          </View>
+        </>
+      ) : (
+        <>
+          <View
+            testID={`${testID}-actions`}
+            style={isSheet ? styles.sheetActions : undefined}
+          >
+            {actions.map((action) => (
+              <Button
+                key={action.id}
+                label={action.label}
+                disabled={action.disabled}
+                loading={action.loading}
+                variant={isSheet ? (action.tone ?? 'neutral') : 'text'}
+                style={isSheet ? styles.sheetAction : undefined}
+                onPress={() => {
+                  if (action.confirmation) {
+                    setConfirmationId(action.id);
+                    return;
+                  }
+                  action.onPress();
+                }}
+              />
+            ))}
+          </View>
+          {!isSheet ? (
+            <Button label={cancelLabel} variant="text" onPress={onClose} />
+          ) : null}
+        </>
+      )}
+    </Pressable>
+  );
+
+  return (
+    <Pressable
+      accessible={false}
+      testID={testID}
+      style={[isSheet ? styles.sheetRoot : styles.dialogRoot, style]}
+      onPress={onClose}
+    >
+      {content}
+    </Pressable>
+  );
+}

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

@@ -0,0 +1,6 @@
+export { ActionMenuContent } from './ActionMenuContent';
+export type {
+  ActionMenuAction,
+  ActionMenuConfirmation,
+  ActionMenuContentProps,
+} from './types';

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

@@ -0,0 +1,47 @@
+import { StyleSheet } from 'react-native';
+import { fw, radius, space, type as typography } from '../../../theme';
+import type { ColorTokens } from '../../../theme';
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    dialogRoot: {
+      flex: 1,
+      justifyContent: 'center',
+      alignItems: 'center',
+      backgroundColor: c.scrim,
+    },
+    sheetRoot: {
+      flex: 1,
+      justifyContent: 'flex-end',
+      backgroundColor: c.scrim,
+    },
+    dialogCard: {
+      backgroundColor: c.surface,
+      borderRadius: radius.xl,
+      padding: space[4],
+      width: '80%',
+      maxWidth: 400,
+      gap: space[2],
+    },
+    sheetCard: {
+      backgroundColor: c.surface,
+      borderTopLeftRadius: radius.xl,
+      borderTopRightRadius: radius.xl,
+      paddingHorizontal: space[5],
+      paddingTop: space[5],
+      gap: space[3],
+    },
+    title: {
+      color: c.foreground,
+      fontSize: typography.sm,
+      fontWeight: fw.semi,
+      textAlign: 'center',
+      paddingVertical: space[3],
+    },
+    confirmation: {
+      color: c.foregroundMuted,
+      fontSize: typography.xs,
+      textAlign: 'center',
+    },
+    sheetActions: { flexDirection: 'row', flexWrap: 'wrap', gap: space[3] },
+    sheetAction: { flex: 1 },
+  });

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

@@ -0,0 +1,27 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export interface ActionMenuConfirmation {
+  message: string;
+  confirmLabel: string;
+}
+
+export interface ActionMenuAction {
+  id: string;
+  label: string;
+  onPress(): void;
+  disabled?: boolean;
+  loading?: boolean;
+  tone?: 'neutral' | 'danger';
+  confirmation?: ActionMenuConfirmation;
+}
+
+/** 操作、确认有效性和宿主关闭由调用方负责。 */
+export interface ActionMenuContentProps {
+  actions: readonly ActionMenuAction[];
+  presentation?: 'dialog' | 'sheet';
+  title?: string;
+  cancelLabel?: string;
+  onClose(): void;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/components/ui/Button/ButtonBase.tsx

@@ -29,6 +29,8 @@ export type ButtonBaseProps = {
   block?: boolean;
   /** 方形约束 — width=height=sizing.h,优先级高于 horizontal padding。IconButton 用。 */
   square?: boolean;
+  surfaceSize?: number;
+  loadingSize?: number;
   accessibilityLabel?: string;
   accessibilityRole?: AccessibilityRole;
   /** SR 朗读 label 后的行为说明 hint。仅在"行为不显然"时加。 */
@@ -53,6 +55,8 @@ export function ButtonBase({
   loading,
   block,
   square,
+  surfaceSize,
+  loadingSize,
   accessibilityLabel,
   accessibilityRole = 'button',
   accessibilityHint,
@@ -64,7 +68,12 @@ export function ButtonBase({
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
 
-  const sizing = useMemo(() => sizingFor(size), [size]);
+  const sizing = useMemo(() => {
+    const base = sizingFor(size);
+    return square && surfaceSize !== undefined
+      ? { ...base, h: surfaceSize }
+      : base;
+  }, [size, square, surfaceSize]);
   const palette = useMemo(() => paletteFor(variant, c), [variant, c]);
 
   const isText = variant === 'text';
@@ -128,7 +137,7 @@ export function ButtonBase({
       ]}
     >
       {loading ? (
-        <ActivityIndicator size="small" color={palette.fg} />
+        <ActivityIndicator size={loadingSize ?? 'small'} color={palette.fg} />
       ) : (
         children({ sizing, palette })
       )}

package/src/components/ui/GlassLayer/GlassLayer.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import {
+  LiquidGlassView,
+  isLiquidGlassSupported,
+} from '@callstack/liquid-glass';
+import { useColors, useTheme } from '../../../theme';
+import type { GlassLayerProps } from './types';
+
+/** 装饰玻璃层；不支持原生材质的平台使用主题半透明背景。 */
+export function GlassLayer({
+  effect = 'regular',
+  tintColor,
+  style,
+  testID,
+}: GlassLayerProps): React.JSX.Element {
+  const c = useColors();
+  const { scheme } = useTheme();
+  const resolvedTint =
+    tintColor ?? (effect === 'clear' ? c.glassTintLight : c.sheetBackdrop);
+
+  return (
+    <LiquidGlassView
+      // 支持标记也可能因宿主设计兼容设置关闭，必须显式禁用原生材质。
+      effect={isLiquidGlassSupported ? effect : 'none'}
+      tintColor={resolvedTint}
+      colorScheme={scheme}
+      // 纯装饰层无需材质切换动画，也不引入减少动态效果的额外状态。
+      animated={false}
+      style={[
+        StyleSheet.absoluteFill,
+        style,
+        !isLiquidGlassSupported && { backgroundColor: resolvedTint },
+      ]}
+      pointerEvents="none"
+      accessible={false}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      testID={testID}
+    />
+  );
+}

package/src/components/ui/GlassLayer/GlassLayer.web.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import { StyleSheet, View, type ViewStyle } from 'react-native';
+import { useColors, useTheme } from '../../../theme';
+import { webGlassBlur } from './constants';
+import type { GlassLayerProps } from './types';
+
+/** Web 保留 CSS 玻璃近似效果，不加载原生 Liquid Glass 模块。 */
+export function GlassLayer({
+  effect = 'regular',
+  tintColor,
+  style,
+  testID,
+}: GlassLayerProps): React.JSX.Element {
+  const c = useColors();
+  const { scheme } = useTheme();
+  const resolvedTint =
+    tintColor ?? (effect === 'clear' ? c.glassTintLight : c.sheetBackdrop);
+  // RN 类型不含 CSS backdrop-filter。保留原有饱和度和暗色透明度近似值。
+  const webGlassStyle: ViewStyle &
+    Pick<React.CSSProperties, 'backdropFilter' | 'WebkitBackdropFilter'> = {
+    backdropFilter: `blur(${webGlassBlur[effect]}px) saturate(180%)`,
+    WebkitBackdropFilter: `blur(${webGlassBlur[effect]}px) saturate(180%)`,
+    backgroundColor: resolvedTint,
+    opacity: scheme === 'dark' ? 0.96 : 1,
+  };
+
+  return (
+    <View
+      style={[StyleSheet.absoluteFill, style, webGlassStyle]}
+      pointerEvents="none"
+      accessible={false}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+      testID={testID}
+    />
+  );
+}

package/src/components/ui/GlassLayer/constants.ts

@@ -0,0 +1,2 @@
+/** 仅用于 Web CSS 近似效果的像素值，不表示原生材质的模糊半径。 */
+export const webGlassBlur = { clear: 10, regular: 40 } as const;

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

@@ -0,0 +1,2 @@
+export { GlassLayer } from './GlassLayer';
+export type { GlassEffect, GlassLayerProps } from './types';

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

@@ -0,0 +1,14 @@
+import type { ColorValue, StyleProp, ViewStyle } from 'react-native';
+
+export type GlassEffect = 'clear' | 'regular';
+
+export interface GlassLayerProps {
+  /** 玻璃材质，默认 regular；clear 更通透。Web 使用对应的 CSS 近似效果。 */
+  effect?: GlassEffect;
+  /** 默认 clear 使用 glassTintLight，regular 使用 sheetBackdrop；降级时作为背景色。 */
+  tintColor?: ColorValue;
+  /** 布局、定位与圆角；默认 absoluteFill，材质颜色通过 tintColor 设置。 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位。 */
+  testID?: string;
+}

package/src/components/ui/IconButton/IconButton.tsx

@@ -20,6 +20,8 @@ export function IconButton({
   icon,
   onPress,
   size = 'md',
+  iconSize,
+  surfaceSize,
   variant = 'ghost',
   color,
   disabled,
@@ -46,6 +48,8 @@ export function IconButton({
       square
       onPress={onPress}
       size={size}
+      surfaceSize={surfaceSize}
+      loadingSize={iconSize}
       variant={variant}
       loading={loading}
       disabled={disabled === true || hasBlankLabel}
@@ -56,7 +60,11 @@ export function IconButton({
       testID={testID}
     >
       {({ sizing, palette }) => (
-        <Icon name={icon} size={sizing.fs + 4} color={color ?? palette.fg} />
+        <Icon
+          name={icon}
+          size={iconSize ?? sizing.fs + 4}
+          color={color ?? palette.fg}
+        />
       )}
     </ButtonBase>
   );

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

@@ -12,6 +12,10 @@ export type IconButtonProps = {
   onPress: () => void;
   /** 尺寸,默认 'md'(28 / 36 / 44 方形) */
   size?: ButtonSize;
+  /** 独立图标及加载指示尺寸；默认沿用 size 对应值。 */
+  iconSize?: number;
+  /** 方形表面边长；同时据此补足 44pt 命中区。默认沿用 size。 */
+  surfaceSize?: number;
   /** 视觉变体,默认 'ghost'(透明底,适合 header right-tray 场景)。
    *  不支持 'text'——text variant 撕除高度,与 square 方形布局冲突。 */
   variant?: IconButtonVariant;

package/src/components/ui/ImagePreview/ImagePreview.tsx

@@ -0,0 +1,243 @@
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { Text, View } from 'react-native';
+import { radius, useThemedStyles } from '../../../theme';
+import { IconButton } from '../IconButton';
+import { Thumbnail } from '../Thumbnail';
+import { Carousel, type CarouselRef } from 'react-native-reanimated-carousel';
+import { DELETE_LABEL, IMAGE_UNAVAILABLE } from './constants';
+import { makeStyles } from './styles';
+import type {
+  ImagePreviewHandle,
+  ImagePreviewProps,
+  ImagePreviewSelection,
+  ImagePreviewScrollRequest,
+} from './types';
+
+export const ImagePreview = forwardRef<ImagePreviewHandle, ImagePreviewProps>(
+  function ImagePreviewInner(
+    {
+      items,
+      width,
+      height,
+      initialId,
+      onCurrentChange,
+      onRequestDelete,
+      style,
+      testID,
+    },
+    ref
+  ) {
+    const styles = useThemedStyles(makeStyles);
+    const carouselRef = useRef<CarouselRef>(null);
+    const mounted = useRef(false);
+    const moving = useRef(false);
+    const pendingScroll = useRef<ImagePreviewScrollRequest | undefined>(
+      undefined
+    );
+    const [selection, setSelection] = useState<ImagePreviewSelection>(() => ({
+      items,
+      index: Math.max(
+        0,
+        items.findIndex((item) => item.id === initialId)
+      ),
+      initialized: items.length > 0,
+      carouselRevision: 0,
+    }));
+
+    if (selection.items !== items) {
+      const retainedIndex = items.findIndex(
+        (item) => item.id === selection.items[selection.index]?.id
+      );
+      const identityChanged =
+        items.length !== selection.items.length ||
+        items.some((item, index) => item.id !== selection.items[index]?.id);
+      setSelection({
+        items,
+        // SDK 的非动画定位不能撤回已排队的旧完成；只重建在途且身份集合变化的轮播。
+        carouselRevision:
+          selection.carouselRevision +
+          (moving.current && identityChanged ? 1 : 0),
+        initialized: selection.initialized || items.length > 0,
+        index: !selection.initialized
+          ? Math.max(
+              0,
+              items.findIndex((item) => item.id === initialId)
+            )
+          : retainedIndex >= 0
+            ? retainedIndex
+            : Math.max(0, Math.min(selection.index, items.length - 1)),
+      });
+    }
+
+    const current = items[selection.index];
+    const committed = useRef(selection);
+    const currentChange = useRef(onCurrentChange);
+    useLayoutEffect(() => {
+      mounted.current = true;
+      committed.current = selection;
+      currentChange.current = onCurrentChange;
+      return () => {
+        mounted.current = false;
+      };
+    }, [selection, onCurrentChange]);
+
+    useLayoutEffect(() => {
+      moving.current = false;
+    }, [selection.carouselRevision]);
+
+    useEffect(() => {
+      const request = pendingScroll.current;
+      pendingScroll.current = undefined;
+      if (!request) return;
+      const index = committed.current.items.findIndex(
+        (item) => item.id === request.id
+      );
+      if (index >= 0)
+        carouselRef.current?.scrollTo({ index, animated: request.animated });
+    }, [selection.carouselRevision]);
+
+    const notifiedId = useRef<string | undefined>(undefined);
+    useEffect(() => {
+      // 待交接命令可能已同步完成，通知与句柄读取同一份已提交事实。
+      const displayed = committed.current.items[committed.current.index];
+      if (displayed?.id === notifiedId.current) return;
+      notifiedId.current = displayed?.id;
+      if (displayed) currentChange.current?.(displayed);
+    }, [current, onCurrentChange]);
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        getCurrent: () =>
+          mounted.current
+            ? committed.current.items[committed.current.index]
+            : undefined,
+        scrollTo: (id, animated = true) => {
+          if (!mounted.current) return;
+          const index = committed.current.items.findIndex(
+            (item) => item.id === id
+          );
+          if (index < 0) return;
+          if (moving.current || pendingScroll.current) {
+            // 新命令隔离旧完成投递；新 ref 就绪后原样交接 animated。
+            pendingScroll.current = { id, animated };
+            const next = {
+              ...committed.current,
+              carouselRevision: committed.current.carouselRevision + 1,
+            };
+            committed.current = next;
+            setSelection(next);
+          } else {
+            carouselRef.current?.scrollTo({ index, animated });
+          }
+        },
+      }),
+      []
+    );
+
+    // SDK 只协调身份变化；source、label、busy 更新不应打断当前动画。
+    const data = useMemo(() => items.map((item) => item.id), [items]);
+    if (!current) return null;
+
+    return (
+      <View style={[styles.container, style]} testID={testID}>
+        <Carousel
+          key={selection.carouselRevision}
+          ref={carouselRef}
+          data={data}
+          defaultIndex={selection.index}
+          loop={false}
+          itemSize={width}
+          style={{ width, height }}
+          keyExtractor={(id) => id}
+          testID={testID ? `${testID}-carousel` : undefined}
+          onScrollStart={() => {
+            if (
+              mounted.current &&
+              selection.carouselRevision === committed.current.carouselRevision
+            ) {
+              moving.current = true;
+            }
+          }}
+          onSnapToItem={(index) => {
+            const latest = committed.current;
+            if (
+              !mounted.current ||
+              selection.carouselRevision !== latest.carouselRevision ||
+              items.length !== latest.items.length ||
+              items.some(
+                (item, itemIndex) => item.id !== latest.items[itemIndex]?.id
+              )
+            )
+              return;
+            moving.current = false;
+            const id = items[index]?.id;
+            const nextIndex = latest.items.findIndex((item) => item.id === id);
+            if (nextIndex >= 0 && nextIndex !== latest.index) {
+              const next = { ...latest, index: nextIndex };
+              // SDK 已完成落位；句柄同步可读，不等待 React 下一次提交。
+              committed.current = next;
+              setSelection(next);
+              notifiedId.current = id;
+              currentChange.current?.(next.items[nextIndex]!);
+            }
+          }}
+          renderItem={({ item: id, index }) => {
+            const item = items.find((candidate) => candidate.id === id)!;
+            return (
+              <View style={[styles.media, { width, height }]}>
+                {item.source === undefined ? (
+                  <View style={styles.placeholder}>
+                    <Text style={styles.placeholderText}>
+                      {IMAGE_UNAVAILABLE}
+                    </Text>
+                  </View>
+                ) : (
+                  <Thumbnail
+                    source={item.source}
+                    size={{ width, height, borderRadius: radius.xl }}
+                    resizeMode="contain"
+                    imageStyle={styles.image}
+                    accessibilityLabel={item.label ?? `图片第 ${index + 1} 张`}
+                    fallback={
+                      <View style={styles.placeholder}>
+                        <Text style={styles.placeholderText}>
+                          {IMAGE_UNAVAILABLE}
+                        </Text>
+                      </View>
+                    }
+                  />
+                )}
+                <View pointerEvents="none" style={styles.border} />
+              </View>
+            );
+          }}
+        />
+        <View style={styles.counter}>
+          <Text style={styles.counterText}>
+            第{selection.index + 1}/{items.length}张
+          </Text>
+        </View>
+        {current.canDelete && onRequestDelete ? (
+          <IconButton
+            icon="trash"
+            size="sm"
+            variant="neutral"
+            disabled={current.deleting}
+            accessibilityLabel={DELETE_LABEL}
+            style={styles.deleteButton}
+            onPress={() => onRequestDelete(current)}
+          />
+        ) : null}
+      </View>
+    );
+  }
+);

package/src/components/ui/ImagePreview/constants.ts

@@ -0,0 +1,2 @@
+export const IMAGE_UNAVAILABLE = '图片暂不可预览';
+export const DELETE_LABEL = '删除当前照片';

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

@@ -0,0 +1,6 @@
+export { ImagePreview } from './ImagePreview';
+export type {
+  ImagePreviewItem,
+  ImagePreviewProps,
+  ImagePreviewHandle,
+} from './types';

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

@@ -0,0 +1,48 @@
+import { StyleSheet } from 'react-native';
+import { fontMono, radius, space, type as typography } from '../../../theme';
+import type { ColorTokens } from '../../../theme';
+
+export const makeStyles = (colors: ColorTokens) =>
+  StyleSheet.create({
+    container: { alignItems: 'center', gap: space[2] },
+    media: {
+      backgroundColor: 'black',
+      borderRadius: radius.xl,
+      overflow: 'hidden',
+    },
+    border: {
+      ...StyleSheet.absoluteFill,
+      borderColor: colors.outline,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderRadius: radius.xl,
+    },
+    image: { backgroundColor: 'black' },
+    placeholder: {
+      width: '100%',
+      height: '100%',
+      backgroundColor: 'black',
+      justifyContent: 'center',
+      alignItems: 'center',
+      paddingHorizontal: space[3],
+    },
+    placeholderText: {
+      color: 'white',
+      fontSize: typography.sm,
+      textAlign: 'center',
+    },
+    counter: {
+      alignSelf: 'center',
+      paddingVertical: space[1],
+      paddingHorizontal: space[3],
+      borderRadius: radius.pill,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: colors.glassPillBorder,
+      backgroundColor: colors.glassHighlight,
+    },
+    counterText: {
+      color: colors.foreground,
+      fontSize: typography.sm,
+      fontFamily: fontMono,
+    },
+    deleteButton: { borderRadius: radius.pill },
+  });