@unif/react-native-ui 0.4.0 → 1.0.1

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,27 @@
+import { memo } from 'react';
+import { useControllable } from '../../core';
+import { TooltipProvider } from './context';
+import type { TooltipProps } from './types';
+
+const Tooltip = memo(function Tooltip({
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  children,
+}: TooltipProps) {
+  const [isOpen, setIsOpen] = useControllable({
+    value: open,
+    defaultValue: defaultOpen,
+    onChange: onOpenChange,
+  });
+
+  return (
+    <TooltipProvider value={{ open: isOpen, onOpenChange: setIsOpen }}>
+      {children}
+    </TooltipProvider>
+  );
+});
+
+Tooltip.displayName = 'Tooltip';
+
+export { Tooltip };

package/src/components/Tooltip/TooltipContent.tsx

@@ -0,0 +1,60 @@
+import { memo } from 'react';
+import { View, Pressable, Modal, StyleSheet } from 'react-native';
+import { useTheme } from '../../core';
+import { useTooltipCtx } from './context';
+import type { TooltipContentProps } from './types';
+
+const TooltipContent = memo(function TooltipContent({
+  children,
+  testID,
+  backdropTestID,
+  style,
+}: TooltipContentProps) {
+  const { open, onOpenChange } = useTooltipCtx();
+  // bg 使用 foreground token（深色气泡）
+  const bg = useTheme((t) => t.foreground);
+
+  if (!open) return null;
+
+  return (
+    <Modal
+      visible
+      transparent
+      animationType="fade"
+      onRequestClose={() => onOpenChange(false)}
+    >
+      <Pressable
+        testID={backdropTestID}
+        style={StyleSheet.absoluteFill}
+        onPress={() => onOpenChange(false)}
+      >
+        <View style={styles.overlay}>
+          <View
+            testID={testID}
+            style={[styles.tooltip, { backgroundColor: bg }, style]}
+          >
+            {children}
+          </View>
+        </View>
+      </Pressable>
+    </Modal>
+  );
+});
+
+TooltipContent.displayName = 'TooltipContent';
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  tooltip: {
+    borderRadius: 6,
+    paddingHorizontal: 10,
+    paddingVertical: 6,
+    maxWidth: 200,
+  },
+});
+
+export { TooltipContent };

package/src/components/Tooltip/TooltipTrigger.tsx

@@ -0,0 +1,24 @@
+import { memo } from 'react';
+import { Pressable } from 'react-native';
+import { useTooltipCtx } from './context';
+import type { TooltipTriggerProps } from './types';
+
+const TooltipTrigger = memo(function TooltipTrigger({
+  children,
+  testID,
+}: TooltipTriggerProps) {
+  const { onOpenChange } = useTooltipCtx();
+  return (
+    <Pressable
+      testID={testID}
+      onLongPress={() => onOpenChange(true)}
+      accessibilityRole="button"
+    >
+      {children}
+    </Pressable>
+  );
+});
+
+TooltipTrigger.displayName = 'TooltipTrigger';
+
+export { TooltipTrigger };

package/src/components/Tooltip/context.ts

@@ -0,0 +1,10 @@
+import { createCompound } from '../../core';
+
+/** Tooltip 根组件向 Trigger/Content 共享的展开状态 */
+export interface TooltipCtx {
+  open: boolean;
+  onOpenChange: (v: boolean) => void;
+}
+
+export const [TooltipProvider, useTooltipCtx] =
+  createCompound<TooltipCtx>('Tooltip');

package/src/components/Tooltip/index.tsx

@@ -0,0 +1,8 @@
+export { Tooltip } from './Tooltip';
+export { TooltipTrigger } from './TooltipTrigger';
+export { TooltipContent } from './TooltipContent';
+export type {
+  TooltipProps,
+  TooltipTriggerProps,
+  TooltipContentProps,
+} from './types';

package/src/components/Tooltip/types.ts

@@ -0,0 +1,24 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export interface TooltipProps {
+  /** 受控展开状态 */
+  open?: boolean;
+  /** 非受控初始展开状态；默认为 false */
+  defaultOpen?: boolean;
+  /** 展开状态变化时的回调 */
+  onOpenChange?: (open: boolean) => void;
+  children?: React.ReactNode;
+}
+
+export interface TooltipTriggerProps {
+  children?: React.ReactNode;
+  testID?: string;
+}
+
+export interface TooltipContentProps {
+  children?: React.ReactNode;
+  testID?: string;
+  /** 遮罩层的 testID，用于测试点击遮罩关闭行为 */
+  backdropTestID?: string;
+  style?: StyleProp<ViewStyle>;
+}

package/src/components/index.tsx

@@ -0,0 +1,179 @@
+// src/components/index.tsx — 所有组件的统一导出入口
+
+export {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from './Accordion';
+export type {
+  AccordionProps,
+  AccordionItemProps,
+  AccordionTriggerProps,
+  AccordionContentProps,
+  AccordionType,
+} from './Accordion';
+
+export { Alert } from './Alert';
+export type { AlertProps, AlertVisual } from './Alert';
+
+export { Avatar } from './Avatar';
+export type { AvatarProps, AvatarSize, AvatarShape } from './Avatar';
+
+export { Badge } from './Badge';
+export type { BadgeProps } from './Badge';
+
+export { Button } from './Button';
+export type { ButtonProps, ButtonVisual, ButtonSize } from './Button';
+
+export {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+} from './Card';
+export type {
+  CardProps,
+  CardHeaderProps,
+  CardTitleProps,
+  CardDescriptionProps,
+  CardContentProps,
+  CardFooterProps,
+} from './Card';
+
+export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './Checkbox';
+
+export {
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from './Collapsible';
+export type {
+  CollapsibleProps,
+  CollapsibleTriggerProps,
+  CollapsibleContentProps,
+} from './Collapsible';
+
+export {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+} from './Dialog';
+export type {
+  DialogProps,
+  DialogTriggerProps,
+  DialogContentProps,
+  DialogHeaderProps,
+  DialogFooterProps,
+} from './Dialog';
+
+export { Divider } from './Divider';
+export type { DividerProps } from './Divider';
+
+export { Empty } from './Empty';
+export type { EmptyProps } from './Empty';
+
+export { Form, FormField, FormLabel, FormMessage } from './Form';
+export type {
+  FormProps,
+  FormFieldProps,
+  FormLabelProps,
+  FormMessageProps,
+} from './Form';
+
+export { Input } from './Input';
+export type { InputProps, InputSize } from './Input';
+
+export { List, ListItem } from './List';
+export type { ListProps, ListItemProps } from './List';
+
+export { Menu, MenuItem, MenuSeparator } from './Menu';
+export type { MenuProps, MenuItemProps, MenuSeparatorProps } from './Menu';
+
+export { Popover, PopoverTrigger, PopoverContent } from './Popover';
+export type {
+  PopoverProps,
+  PopoverTriggerProps,
+  PopoverContentProps,
+} from './Popover';
+
+export { Progress } from './Progress';
+export type { ProgressProps } from './Progress';
+
+export { RadioGroup, Radio } from './RadioGroup';
+export type { RadioGroupProps, RadioProps } from './RadioGroup';
+
+export { SegmentedControl } from './SegmentedControl';
+export type { SegmentedControlProps, SegmentedItem } from './SegmentedControl';
+
+export { Select } from './Select';
+export type { SelectProps, SelectItem } from './Select';
+
+export { Sheet } from './Sheet';
+export type { SheetProps } from './Sheet';
+
+export { Skeleton } from './Skeleton';
+export type { SkeletonProps } from './Skeleton';
+
+export { Slider } from './Slider';
+export type { SliderProps } from './Slider';
+
+export { Spinner } from './Spinner';
+export type { SpinnerProps } from './Spinner';
+
+export { Steps, StepsItem } from './Steps';
+export type { StepsProps, StepsItemProps, StepStatus } from './Steps';
+
+export { Switch } from './Switch';
+export type { SwitchProps } from './Switch';
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableRow,
+  TableHead,
+  TableCell,
+} from './Table';
+export type {
+  TableProps,
+  TableHeaderProps,
+  TableBodyProps,
+  TableRowProps,
+  TableHeadProps,
+  TableCellProps,
+} from './Table';
+
+export { Tabs, TabsList, TabsTrigger, TabsContent } from './Tabs';
+export type {
+  TabsProps,
+  TabsListProps,
+  TabsTriggerProps,
+  TabsContentProps,
+} from './Tabs';
+
+export { Text } from './Text';
+export type { TextProps, VisualPreset } from './Text';
+
+export { Textarea } from './Textarea';
+export type { TextareaProps } from './Textarea';
+
+export { ToastProvider, useToast } from './Toast';
+export type {
+  ToastProviderProps,
+  ToastOptions,
+  ToastVisual,
+  ToastCtxValue,
+} from './Toast';
+
+export { Tooltip, TooltipTrigger, TooltipContent } from './Tooltip';
+export type {
+  TooltipProps,
+  TooltipTriggerProps,
+  TooltipContentProps,
+} from './Tooltip';

package/src/core/compound.tsx

@@ -0,0 +1,53 @@
+import React, { createContext, useContext } from 'react';
+import { invariant } from './utils/dev';
+
+// 哨兵值：用于区分"Context 未被提供"和"值为 undefined"两种情况
+const UNSET = Symbol('compound.unset');
+
+/**
+ * 创建复合组件（Compound Component）模式所需的 Provider + useContext 对。
+ *
+ * 复合组件模式的典型场景：Tabs、Accordion、Select 等，
+ * 由父组件维护状态并通过 Context 向子组件传递，子组件无需 prop drilling。
+ *
+ * 此工厂函数解决了两个常见问题：
+ * 1. Context displayName：自动设置为 `${displayName}.Context`，便于 React DevTools 识别
+ * 2. 缺少 Provider 的防御性检查：子组件未包裹在父组件内时，
+ *    useCtx 会通过 invariant 抛出明确的错误提示，而非 `undefined is not an object`
+ *
+ * @param displayName 组件名称，用于 Context.displayName 和错误信息
+ * @returns [Provider, useCtx] 元组
+ *   - Provider: 接受 value 和 children 的 React 组件
+ *   - useCtx: 消费 Context 的 Hook，在 Provider 外调用时抛出错误
+ */
+export function createCompound<T>(
+  displayName: string
+): [
+  Provider: React.FC<{ value: T; children: React.ReactNode }>,
+  useCtx: () => T
+] {
+  const Ctx = createContext<T | typeof UNSET>(UNSET);
+  Ctx.displayName = `${displayName}.Context`;
+
+  const Provider: React.FC<{ value: T; children: React.ReactNode }> = ({
+    value,
+    children,
+  }) => <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+  Provider.displayName = `${displayName}.Provider`;
+
+  function useCtx(): T {
+    const value = useContext(Ctx);
+    // 检测到 UNSET 哨兵值说明子组件在对应 Provider 之外被使用
+    invariant(
+      value !== UNSET,
+      `${displayName} sub-component must be used within <${displayName}>`
+    );
+    return value as T;
+  }
+  // 通过 defineProperty 修正函数名，使其在 React DevTools 和错误栈中显示为 use${displayName}Context
+  Object.defineProperty(useCtx, 'name', {
+    value: `use${displayName}Context`,
+  });
+
+  return [Provider, useCtx];
+}

package/src/core/hooks/useBackHandler.ts

@@ -0,0 +1,26 @@
+import { useEffect } from 'react';
+import { BackHandler, Platform } from 'react-native';
+
+/**
+ * 监听 Android 实体返回键，仅在 Android 平台生效（iOS 无实体返回键）。
+ *
+ * 典型用途：Dialog / Sheet 打开时拦截返回键以执行关闭逻辑，
+ * 而非触发默认的页面返回行为。
+ *
+ * 注意：handler 应返回 true 表示"已处理，阻止冒泡"，
+ * 返回 false 表示"未处理，继续冒泡给下一个监听器"。
+ *
+ * @param handler 按下实体返回键时的回调；返回 true 阻止默认行为，返回 false 不拦截
+ */
+export function useBackHandler(handler: () => boolean): void {
+  useEffect(() => {
+    // iOS 无实体返回键，直接跳过
+    if (Platform.OS !== 'android') return;
+    const subscription = BackHandler.addEventListener(
+      'hardwareBackPress',
+      handler
+    );
+    // 组件卸载时移除监听，防止内存泄漏
+    return () => subscription.remove();
+  }, [handler]);
+}

package/src/core/hooks/useControllable.ts

@@ -0,0 +1,62 @@
+import { useCallback, useRef, useState } from 'react';
+
+/**
+ * useControllable 的配置项。
+ *
+ * 受控模式：传入 `value`，组件不维护内部状态，所有变化通过 `onChange` 通知外部。
+ * 非受控模式：传入 `defaultValue`，组件用 useState 自行管理状态，`onChange` 仅作通知。
+ */
+interface UseControllableOptions<T> {
+  /** 受控值。传入时进入受控模式；undefined 时进入非受控模式。 */
+  value?: T;
+  /** 非受控模式的初始值。受控模式下会被忽略。 */
+  defaultValue?: T;
+  /** 值变化时的回调。受控模式下必须在此回调里更新 value，否则 UI 不会刷新。 */
+  onChange?: (value: T) => void;
+}
+
+// 函数重载：提供 defaultValue 时返回类型收窄为 T（排除 undefined）
+export function useControllable<T>(
+  options: UseControllableOptions<T> & { defaultValue: T }
+): [T, (value: T) => void];
+export function useControllable<T>(
+  options: UseControllableOptions<T>
+): [T | undefined, (value: T) => void];
+
+export function useControllable<T>(
+  options: UseControllableOptions<T>
+): [T | undefined, (value: T) => void] {
+  const { value, defaultValue, onChange } = options;
+
+  // 非受控模式的内部状态。用惰性初始化避免每次渲染重新计算。
+  // 受控模式下此状态永远不会被读取，但 Hook 规则要求无条件调用。
+  const [internalValue, setInternalValue] = useState<T | undefined>(
+    () => defaultValue
+  );
+
+  // 用 ref 存储"当前是否受控"，使 setter 能读到最新状态而无需重新创建
+  const isControlledRef = useRef(value !== undefined);
+  isControlledRef.current = value !== undefined;
+
+  // 用 ref 持有最新的 onChange，使 setter 始终调用最新版本，
+  // 同时避免 setter（useCallback）因 onChange 变化而重新创建。
+  // 注意：不能用 useEffectEvent，因为 setter 在事件处理器中调用，不在 Effect 中。
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  const setter = useCallback((newValue: T) => {
+    if (isControlledRef.current) {
+      // 受控模式：不更新内部状态，只通知外部。
+      // 外部必须响应 onChange 并更新 value prop，视图才会刷新。
+      onChangeRef.current?.(newValue);
+    } else {
+      // 非受控模式：更新内部状态触发重渲染，同时通知外部（可选监听）。
+      setInternalValue(newValue);
+      onChangeRef.current?.(newValue);
+    }
+  }, []);
+
+  // 受控模式读外部 value，非受控模式读内部状态
+  const currentValue = isControlledRef.current ? value : internalValue;
+  return [currentValue, setter];
+}

package/src/core/hooks/useOverlayAnimation.ts

@@ -0,0 +1,150 @@
+// 动画方案：使用 Reanimated 4 的 withTiming/withSpring。
+// 对于简单的状态驱动浮层，Reanimated 4 CSS Transitions
+// （transitionProperty / transitionDuration）是一种声明式的替代方案，
+// 但 useOverlayAnimation 使用命令式 withTiming 以实现更精细的生命周期控制
+// （进入/退出时序，退出动画完成后触发 onClosed 回调）。
+import { useCallback, useContext, useRef, useState } from 'react';
+import { useSharedValue, withTiming } from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+import { ThemeContext } from '../theme/hooks';
+
+/** 浮层支持的动画模式 */
+export type OverlayAnimationMode = 'fade' | 'slideUp' | 'scale';
+
+/** useOverlayAnimation 的返回值 */
+export interface UseOverlayAnimationResult {
+  /**
+   * 组件是否应当挂载到 DOM。
+   * 进入时立即变为 true；退出动画完成后才变为 false，
+   * 确保退出动画能正常播放而不被提前卸载。
+   */
+  mounted: boolean;
+  /** 背景遮罩的不透明度，所有模式均有此动画 */
+  backdropOpacity: ReturnType<typeof useSharedValue<number>>;
+  /** slideUp 模式：内容面板的垂直偏移（0 = 就位，300 = 屏幕外） */
+  translateY: ReturnType<typeof useSharedValue<number>>;
+  /** scale 模式：内容面板的缩放比例（1 = 正常，0.95 = 缩小） */
+  scale: ReturnType<typeof useSharedValue<number>>;
+  /** fade / scale 模式：内容面板的不透明度 */
+  contentOpacity: ReturnType<typeof useSharedValue<number>>;
+  /** 触发进入动画：先挂载组件，再播放动画 */
+  open: () => void;
+  /**
+   * 触发退出动画：先播放动画，完成后卸载组件并调用 onClosed。
+   * @param onClosed 卸载完成后的回调，通常用于通知父组件关闭状态
+   */
+  close: (onClosed?: () => void) => void;
+}
+
+/**
+ * 管理浮层（Dialog / Sheet / Toast 等）的动画生命周期。
+ *
+ * 解决的核心问题：退出动画播完之前不能卸载组件，否则动画会被中断。
+ * 通过 `mounted` 状态延迟卸载：动画回调里才执行 setMounted(false)。
+ *
+ * 调用方将返回的 SharedValue 绑定到 `useAnimatedStyle`，
+ * 用 `mounted` 控制是否 render，无需自行管理动画时序。
+ *
+ * @param initialVisible 初始显隐状态，仅用于初始化，后续变化需调用 open()/close()
+ * @param mode           动画模式，默认 'fade'
+ */
+export function useOverlayAnimation(
+  initialVisible: boolean,
+  mode: OverlayAnimationMode = 'fade'
+): UseOverlayAnimationResult {
+  const { tokens } = useContext(ThemeContext);
+
+  // mounted 控制组件是否渲染。进入时立即挂载；
+  // 退出时等动画结束再卸载，避免动画被中断。
+  const [mounted, setMounted] = useState(initialVisible);
+
+  // 用 ref 标记"当前是否处于退出动画中"，防止快速开关时旧回调误触卸载
+  const isAnimatingClose = useRef(false);
+
+  // 各动画维度的 SharedValue，初始值取决于 initialVisible
+  const backdropOpacity = useSharedValue(initialVisible ? 1 : 0);
+  const translateY = useSharedValue(initialVisible ? 0 : 300);
+  const scale = useSharedValue(initialVisible ? 1 : 0.95);
+  const contentOpacity = useSharedValue(initialVisible ? 1 : 0);
+
+  // 动画时长乘以 scale 系数（减弱动效模式下 scale=0，动画瞬间完成）
+  const duration = tokens.animation.durationNormal * tokens.animation.scale;
+  const easingOut = tokens.animation.easing.out;
+  const easingIn = tokens.animation.easing.in;
+
+  /** 挂载组件并播放进入动画 */
+  const open = useCallback(() => {
+    isAnimatingClose.current = false;
+    setMounted(true);
+    const cfg = { duration, easing: easingOut };
+    backdropOpacity.value = withTiming(1, cfg);
+    if (mode === 'slideUp') translateY.value = withTiming(0, cfg);
+    if (mode === 'scale') {
+      scale.value = withTiming(1, cfg);
+      contentOpacity.value = withTiming(1, cfg);
+    }
+    if (mode === 'fade') contentOpacity.value = withTiming(1, cfg);
+  }, [
+    mode,
+    duration,
+    easingOut,
+    backdropOpacity,
+    translateY,
+    scale,
+    contentOpacity,
+  ]);
+
+  /**
+   * 播放退出动画，完成后卸载组件。
+   * withTiming 回调在 UI 线程执行，unmount 标注 'worklet' 使其可在 UI 线程调用，
+   * 再通过 scheduleOnRN 切回 JS 线程执行 setMounted/onClosed。
+   */
+  const close = useCallback(
+    (onClosed?: () => void) => {
+      isAnimatingClose.current = true;
+      // 退出使用 easing.in（先慢后快），与进入的 easing.out 形成对称
+      const cfg = { duration, easing: easingIn };
+
+      const unmount = () => {
+        'worklet';
+        // 检查标志防止动画中途被 open() 打断后仍执行卸载
+        if (isAnimatingClose.current) {
+          scheduleOnRN(setMounted, false);
+          if (onClosed) scheduleOnRN(onClosed);
+        }
+      };
+
+      backdropOpacity.value = withTiming(0, cfg);
+      if (mode === 'slideUp')
+        // slideUp 以面板滑出为主动画，滑出结束时触发卸载
+        translateY.value = withTiming(300, cfg, () => unmount());
+      else if (mode === 'scale') {
+        scale.value = withTiming(0.95, cfg);
+        // scale 模式以内容渐隐为主动画
+        contentOpacity.value = withTiming(0, cfg, () => unmount());
+      } else {
+        // fade 模式以内容渐隐为主动画
+        contentOpacity.value = withTiming(0, cfg, () => unmount());
+      }
+    },
+    [
+      mode,
+      duration,
+      easingIn,
+      backdropOpacity,
+      translateY,
+      scale,
+      contentOpacity,
+    ]
+  );
+
+  return {
+    mounted,
+    backdropOpacity,
+    translateY,
+    scale,
+    contentOpacity,
+    open,
+    close,
+  };
+}

package/src/core/hooks/useReducedMotion.ts

@@ -0,0 +1,4 @@
+// 直接重导出 react-native-reanimated 的 useReducedMotion。
+// 当系统级"减弱动效"无障碍选项开启时返回 true，
+// 动画相关组件应据此将动画时长设为 0 或跳过动画。
+export { useReducedMotion } from 'react-native-reanimated';

package/src/core/index.ts

@@ -0,0 +1,55 @@
+// src/core/index.ts
+// 内部导出——不属于 @unif/react-native-ui 的公共 API。
+// 组件从此文件导入；终端用户从 src/index.ts 导入。
+
+export { invariant, warning } from './utils/dev';
+export { recipe } from './styles/recipe';
+export type {
+  Recipe,
+  SlotMap,
+  VariantProps,
+  SlotStyles,
+} from './styles/recipe';
+export { useStyles } from './styles/useStyles';
+export { createCompound } from './compound';
+export { useControllable } from './hooks/useControllable';
+export { Portal, PortalHost } from './portal';
+export {
+  pushBarStyle,
+  popBarStyle,
+  getCurrentBarStyle,
+} from './utils/statusBarManager';
+export { useOverlayAnimation } from './hooks/useOverlayAnimation';
+export type { OverlayAnimationMode } from './hooks/useOverlayAnimation';
+export { useBackHandler } from './hooks/useBackHandler';
+export { useReducedMotion } from './hooks/useReducedMotion';
+
+// 主题
+export { lightTokens, darkTokens, defaultStrings } from './theme/tokens';
+export { createTheme } from './theme/createTheme';
+export { ThemeProvider } from './theme/provider';
+export {
+  ThemeContext,
+  useTheme,
+  useThemeMode,
+  useColorModeValue,
+  useStrings,
+  useHapticFeedback,
+} from './theme/hooks';
+export type { ThemeContextValue } from './theme/hooks';
+export {
+  AnimationClockProvider,
+  useAnimationClock,
+} from './theme/animationClock';
+export type {
+  Tokens,
+  Theme,
+  TypographyPreset,
+  ShadowStyle,
+  EasingFunction,
+  ColorMode,
+  ResolvedColorMode,
+  StringsConfig,
+  ComponentRegistry,
+  CreateThemeInput,
+} from './theme/types';