react-native-x-components 0.1.0

package/dist/XProviders/XImagePreview/index.js

@@ -0,0 +1,164 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XImagePreview —— 命令式图片预览（X 系列，复刻自 components/ImagePreview）
+ * ============================================================================
+ *
+ * 由四部分组成（单文件聚合，避免目录过碎）：
+ * - XGalleryImage          单图渲染（fitContainer 适配屏幕）
+ * - XImagePreview          预览 UI（Gallery 翻页 + 页码 + 关闭按钮）
+ * - XImagePreviewProvider  状态宿主，App 根部挂载一次
+ * - XImagePreviewService   命令式入口，任意地方调用
+ *
+ * 用法：
+ *   XImagePreviewService.show({images: urls, initialIndex: 0});
+ *   XImagePreviewService.hide();
+ *
+ * 实现要点：
+ * - 全局句柄 useEffect 注册/清理（无 render 副作用）；
+ * - 关闭时清空 images，及时释放大图列表引用；
+ * - DEV 环境未挂载时给出 console.warn；
+ * - Modal 使用 transparent + fade，浮在原页面上（系统相册同款观感）；
+ * - GestureHandlerRootView 是 react-native-zoom-toolkit 手势正常工作的必要包裹。
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Image, Modal, StyleSheet, Text, useWindowDimensions, View } from 'react-native';
+import { stackTransition, Gallery, fitContainer } from 'react-native-zoom-toolkit';
+import { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler';
+import AntDesign from '@react-native-vector-icons/ant-design';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+const XGalleryImage = ({ uri }) => {
+    const { width, height } = useWindowDimensions();
+    const [resolution, setResolution] = useState({ width: 1, height: 1 });
+    const size = fitContainer(resolution.width / resolution.height, { width, height });
+    return (_jsx(Image, { source: { uri }, style: size, resizeMethod: 'scale', resizeMode: 'cover', onLoad: e => {
+            setResolution({
+                width: e.nativeEvent.source.width,
+                height: e.nativeEvent.source.height,
+            });
+        } }));
+};
+export const XImagePreview = ({ initialIndex = 0, imageList, onClose }) => {
+    const ref = useRef(null);
+    const [currentIndex, setCurrentIndex] = useState(initialIndex);
+    const insets = useSafeAreaInsets();
+    const renderItem = useCallback((item, index) => {
+        return _jsx(XGalleryImage, { uri: item, index: index });
+    }, []);
+    const keyExtractor = useCallback((item, index) => {
+        return `${item}-${index}`;
+    }, []);
+    const onIndexChange = useCallback((index) => {
+        setCurrentIndex(index);
+    }, []);
+    const transition = useCallback(stackTransition, []);
+    // 关闭按钮的手势：必须用 RNGH 的 Gesture.Tap，因为 Gallery 内部有一个全屏
+    // + zIndex 最大 + 带 Tap 的手势探测器，RN 的 TouchableOpacity 会被它抢走 touch。
+    // 关键：必须用 useMemo 真正稳定为一个 Gesture 对象，传函数 / useCallback(返回新对象) 会让 GestureDetector 反复重新注册识别器，导致手势永远识别失败。
+    const closeTap = useMemo(() => Gesture.Tap()
+        .runOnJS(true)
+        .onEnd((_e, success) => {
+        if (success)
+            onClose?.();
+    }), [onClose]);
+    // 下拉关闭手势（iOS 相册标配）：垂直下拉超过 80px 触发关闭。
+    const verticalPullClose = useMemo(() => Gesture.Pan()
+        .activeOffsetY([10, 10])
+        .onEnd((e, success) => {
+        if (success && e.translationY > 80)
+            onClose?.();
+    }), [onClose]);
+    return (_jsxs(View, { style: styles.root, children: [_jsx(Gallery, { ref: ref, data: imageList, keyExtractor: keyExtractor, renderItem: renderItem, initialIndex: initialIndex, onIndexChange: onIndexChange, customTransition: transition, tapOnEdgeToItem: false }), _jsx(View, { pointerEvents: 'box-none', style: [styles.topOverlay, { paddingTop: insets.top + 20, paddingRight: 10 }], children: _jsx(GestureDetector, { gesture: closeTap, children: _jsx(View, { style: styles.closeButton, children: _jsx(AntDesign, { name: 'close', size: 22, color: 'rgba(255,255,255,0.92)' }) }) }) }), _jsx(View, { pointerEvents: 'box-none', style: [styles.bottomOverlay, { paddingBottom: insets.bottom + 24 }], children: _jsxs(Text, { style: styles.counter, children: [currentIndex + 1, " / ", imageList.length] }) })] }));
+};
+const styles = StyleSheet.create({
+    root: {
+        flex: 1,
+        backgroundColor: 'rgba(0,0,0,0.92)',
+    },
+    modalRoot: {
+        ...{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 },
+        backgroundColor: 'rgba(0,0,0,0.92)',
+    },
+    topOverlay: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        flexDirection: 'row',
+        justifyContent: 'flex-end',
+        alignItems: 'flex-start',
+        paddingHorizontal: 16,
+        // paddingTop 在组件渲染时动态设置（insets.top + 8）
+    },
+    closeButton: {
+        width: 34,
+        height: 34,
+        borderRadius: 17,
+        backgroundColor: 'rgba(0,0,0,0.45)',
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+    bottomOverlay: {
+        position: 'absolute',
+        bottom: 0,
+        left: 0,
+        right: 0,
+        flexDirection: 'row',
+        justifyContent: 'center',
+        alignItems: 'center',
+        zIndex: 10,
+    },
+    counter: {
+        color: '#fff',
+        fontSize: 15,
+        fontWeight: '600',
+        backgroundColor: 'rgba(0,0,0,0.45)',
+        paddingHorizontal: 14,
+        paddingVertical: 5,
+        borderRadius: 999,
+        overflow: 'hidden',
+    },
+});
+// ================= Provider + Service =================
+/** 全局句柄：Provider 挂载时写入，卸载时清空 */
+let handle = null;
+export const XImagePreviewProvider = ({ children }) => {
+    const [visible, setVisible] = useState(false);
+    const [images, setImages] = useState([]);
+    const [initialIndex, setInitialIndex] = useState(0);
+    const show = useCallback(({ images: list, initialIndex: index = 0 }) => {
+        setImages(list);
+        setInitialIndex(index);
+        setVisible(true);
+    }, []);
+    const hide = useCallback(() => {
+        setVisible(false);
+        setImages([]); // 释放图片列表引用
+    }, []);
+    useEffect(() => {
+        handle = { show, hide };
+        return () => {
+            if (handle?.show === show) {
+                handle = null;
+            }
+        };
+    }, [show, hide]);
+    return (_jsxs(_Fragment, { children: [children, _jsx(Modal, { visible: visible, transparent: true, animationType: 'fade', statusBarTranslucent: true, hardwareAccelerated: true, onRequestClose: hide, children: _jsx(View, { style: styles.modalRoot, children: _jsx(GestureHandlerRootView, { style: styles.modalRoot, children: _jsx(XImagePreview, { imageList: images, initialIndex: initialIndex, onClose: hide }) }) }) })] }));
+};
+/**
+ * XImagePreviewService —— 命令式调用入口（可在组件外使用）
+ */
+export const XImagePreviewService = {
+    show: (params) => {
+        if (__DEV__ && !handle) {
+            console.warn('[XImagePreviewService] XImagePreviewProvider 未挂载，本次 show 调用被忽略');
+        }
+        handle?.show(params);
+    },
+    hide: () => {
+        if (__DEV__ && !handle) {
+            console.warn('[XImagePreviewService] XImagePreviewProvider 未挂载，本次 hide 调用被忽略');
+        }
+        handle?.hide();
+    },
+};

package/dist/XProviders/XLoadingModal/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ============================================================================
+ * XLoadingModal —— 命令式 Loading（X 系列，复刻自 components/LoadingModal）
+ * ============================================================================
+ *
+ * 由三部分组成：
+ * - XLoadingModal          纯 UI 组件（Modal + 转圈 + 文案）
+ * - XLoadingModalProvider  状态宿主，App 根部挂载一次
+ * - XLoadingModalService   命令式入口，任意地方（含非组件环境）调用
+ *
+ * 用法：
+ *   App 根部挂载一次 XLoadingModalProvider，然后任意地方：
+ *   XLoadingModalService.show({title: '上传中...'});
+ *   XLoadingModalService.hide();
+ *
+ * 实现要点：
+ * - 全局句柄 useEffect 注册/清理，Provider 卸载后调用自动失效（无 render 副作用）；
+ * - show/hide 引用计数，并发多次 show 时全部 hide 后才关闭；
+ * - show 传参为 Partial 合并，只改传入的字段；
+ * - DEV 环境未挂载时给出 console.warn，不再静默吞掉调用。
+ */
+import React, { type ReactNode } from 'react';
+export interface XLoadingModalProps {
+    title?: string;
+    visible: boolean;
+    color?: string;
+    size?: number | 'small' | 'large';
+    transparent?: boolean;
+}
+export interface XLoadingModalConfig {
+    title?: string;
+    color?: string;
+    size?: number | 'small' | 'large';
+    transparent?: boolean;
+}
+export declare const XLoadingModal: React.FC<XLoadingModalProps>;
+export declare const XLoadingModalProvider: ({ children }: {
+    children: ReactNode;
+}) => React.JSX.Element;
+/**
+ * XLoadingModalService —— 命令式调用入口（可在 axios 拦截器等非组件环境使用）
+ */
+export declare const XLoadingModalService: {
+    show: (params?: Partial<XLoadingModalConfig>) => void;
+    hide: () => void;
+};

package/dist/XProviders/XLoadingModal/index.js

@@ -0,0 +1,119 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XLoadingModal —— 命令式 Loading（X 系列，复刻自 components/LoadingModal）
+ * ============================================================================
+ *
+ * 由三部分组成：
+ * - XLoadingModal          纯 UI 组件（Modal + 转圈 + 文案）
+ * - XLoadingModalProvider  状态宿主，App 根部挂载一次
+ * - XLoadingModalService   命令式入口，任意地方（含非组件环境）调用
+ *
+ * 用法：
+ *   App 根部挂载一次 XLoadingModalProvider，然后任意地方：
+ *   XLoadingModalService.show({title: '上传中...'});
+ *   XLoadingModalService.hide();
+ *
+ * 实现要点：
+ * - 全局句柄 useEffect 注册/清理，Provider 卸载后调用自动失效（无 render 副作用）；
+ * - show/hide 引用计数，并发多次 show 时全部 hide 后才关闭；
+ * - show 传参为 Partial 合并，只改传入的字段；
+ * - DEV 环境未挂载时给出 console.warn，不再静默吞掉调用。
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { ActivityIndicator, Modal, StyleSheet, Text, View } from 'react-native';
+import { useXTheme } from '../../theme';
+import { useXLocale } from '../../XLocale';
+// ================= 纯 UI 组件 =================
+export const XLoadingModal = ({ title, visible, color, size = 'large', transparent = false, }) => {
+    const theme = useXTheme();
+    const { t: i18n } = useXLocale();
+    const styles = useMemo(() => StyleSheet.create({
+        mask: {
+            flex: 1,
+            justifyContent: 'center',
+            alignItems: 'center',
+            backgroundColor: 'rgba(0,0,0,0.35)',
+        },
+        box: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            gap: 10,
+            paddingHorizontal: 24,
+            paddingVertical: 18,
+            borderRadius: theme.borderRadiusLG,
+            // 深色半透明胶囊：明暗两种模式都压在暗色遮罩上，保持固定深色
+            backgroundColor: 'rgba(17,20,26,0.85)',
+            shadowColor: '#000',
+            shadowOpacity: 0.2,
+            shadowRadius: 16,
+            shadowOffset: { width: 0, height: 8 },
+            elevation: 10,
+        },
+        boxTransparent: {
+            backgroundColor: 'transparent',
+            shadowOpacity: 0,
+            elevation: 0,
+        },
+        title: {
+            // 浅色实底文字：深色胶囊上的固定对比色
+            color: theme.colorTextLightSolid,
+            fontSize: theme.fontSize,
+            lineHeight: 22,
+        },
+    }), [theme]);
+    const resolvedTitle = title ?? i18n('loading');
+    const resolvedColor = color ?? theme.colorTextLightSolid;
+    return (_jsx(Modal, { visible: visible, transparent: true, animationType: 'fade', statusBarTranslucent: true, presentationStyle: 'overFullScreen', hardwareAccelerated: true, children: _jsx(View, { style: styles.mask, children: _jsxs(View, { style: [styles.box, transparent && styles.boxTransparent], children: [_jsx(ActivityIndicator, { size: size, color: resolvedColor }), !!resolvedTitle && _jsx(Text, { style: styles.title, children: resolvedTitle })] }) }) }));
+};
+// ================= Provider + Service =================
+/** 全局句柄：Provider 挂载时写入，卸载时清空 */
+let handle = null;
+const DEFAULT_CONFIG = {
+    // title / color 不在此写死：未传时由 XLoadingModal 解析为当前语言的 loading 文案与浅色实底色
+    size: 'large',
+    transparent: false,
+};
+export const XLoadingModalProvider = ({ children }) => {
+    const [visible, setVisible] = useState(false);
+    const [config, setConfig] = useState(DEFAULT_CONFIG);
+    /** 引用计数：并发 show 的次数，hide 到 0 才真正关闭 */
+    const countRef = useRef(0);
+    const show = useCallback((params = {}) => {
+        countRef.current += 1;
+        setConfig(prev => ({ ...prev, ...params }));
+        setVisible(true);
+    }, []);
+    const hide = useCallback(() => {
+        countRef.current = Math.max(0, countRef.current - 1);
+        if (countRef.current === 0) {
+            setVisible(false);
+        }
+    }, []);
+    useEffect(() => {
+        handle = { show, hide };
+        return () => {
+            if (handle?.show === show) {
+                handle = null;
+            }
+        };
+    }, [show, hide]);
+    return (_jsxs(_Fragment, { children: [children, _jsx(XLoadingModal, { visible: visible, title: config.title, color: config.color, size: config.size, transparent: config.transparent })] }));
+};
+/**
+ * XLoadingModalService —— 命令式调用入口（可在 axios 拦截器等非组件环境使用）
+ */
+export const XLoadingModalService = {
+    show: (params = {}) => {
+        if (__DEV__ && !handle) {
+            console.warn('[XLoadingModalService] XLoadingModalProvider 未挂载，本次 show 调用被忽略');
+        }
+        handle?.show(params);
+    },
+    hide: () => {
+        if (__DEV__ && !handle) {
+            console.warn('[XLoadingModalService] XLoadingModalProvider 未挂载，本次 hide 调用被忽略');
+        }
+        handle?.hide();
+    },
+};

package/dist/XProviders/XToast/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ============================================================================
+ * XToast —— 全局轻提示（X 系列，复刻自 components/Toast 并现代化）
+ * ============================================================================
+ *
+ * 由三部分组成：
+ * - XToast          单条 UI（深色胶囊：图标 + 文案）
+ * - XToastProvider  状态宿主，App 根部挂载一次（必须在 SafeAreaProvider 内）
+ * - XToastService   命令式入口，任意地方调用
+ *
+ * 用法：
+ *   XToastService.show('保存成功');                                   // 纯文本
+ *   XToastService.show({message: '保存成功', type: 'success'});        // 带图标
+ *   XToastService.show({message: '网络错误', type: 'error', position: 'top'});
+ *
+ * 视觉：iOS 风格深色胶囊，淡入 + 弹簧位移动画；top / center / bottom
+ * 三个位置独立堆叠，同屏最多 3 条（新的顶掉最旧的）。
+ *
+ * 实现要点：
+ * - 全局句柄 useEffect 注册/清理（无 render 副作用）；
+ * - id 由自增计数器生成，避免同一毫秒多条 Toast 的 key 冲突；
+ * - 位移方向按位置自适应（top 从上滑入，其余从下滑入）；
+ * - duration 传 0 表示不自动消失，适配手动控制场景。
+ */
+import React, { type ReactNode } from 'react';
+export type XToastType = 'success' | 'error' | 'info' | 'warning' | 'loading' | 'text';
+export type XToastPosition = 'top' | 'center' | 'bottom';
+export interface XToastOptions {
+    message: string;
+    /** 显示时长（毫秒），默认 2000；0 表示不自动消失 */
+    duration?: number;
+    type?: XToastType;
+    position?: XToastPosition;
+}
+/** 组件内获取 addToast 的 Hook */
+export declare const useXToast: () => {
+    addToast: (options: XToastOptions) => void;
+};
+export declare const XToastProvider: ({ children }: {
+    children: ReactNode;
+}) => React.JSX.Element;
+/**
+ * XToastService —— 命令式调用入口（可在组件外使用）
+ * show 支持两种签名：
+ *   show('保存成功')                            纯文本
+ *   show({message, type, duration, position})   完整配置
+ */
+export declare const XToastService: {
+    show: (messageOrOptions: string | XToastOptions, duration?: number) => void;
+};

package/dist/XProviders/XToast/index.js

@@ -0,0 +1,183 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XToast —— 全局轻提示（X 系列，复刻自 components/Toast 并现代化）
+ * ============================================================================
+ *
+ * 由三部分组成：
+ * - XToast          单条 UI（深色胶囊：图标 + 文案）
+ * - XToastProvider  状态宿主，App 根部挂载一次（必须在 SafeAreaProvider 内）
+ * - XToastService   命令式入口，任意地方调用
+ *
+ * 用法：
+ *   XToastService.show('保存成功');                                   // 纯文本
+ *   XToastService.show({message: '保存成功', type: 'success'});        // 带图标
+ *   XToastService.show({message: '网络错误', type: 'error', position: 'top'});
+ *
+ * 视觉：iOS 风格深色胶囊，淡入 + 弹簧位移动画；top / center / bottom
+ * 三个位置独立堆叠，同屏最多 3 条（新的顶掉最旧的）。
+ *
+ * 实现要点：
+ * - 全局句柄 useEffect 注册/清理（无 render 副作用）；
+ * - id 由自增计数器生成，避免同一毫秒多条 Toast 的 key 冲突；
+ * - 位移方向按位置自适应（top 从上滑入，其余从下滑入）；
+ * - duration 传 0 表示不自动消失，适配手动控制场景。
+ */
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { ActivityIndicator, Animated, StyleSheet, Text, View } from 'react-native';
+import AntDesign from '@react-native-vector-icons/ant-design';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useXTheme } from '../../theme';
+/** 同屏最多保留的 Toast 条数 */
+const MAX_VISIBLE = 3;
+/** 深色底上的语义图标色（比 antd 默认色提亮一档，保证对比度）；as const 保留图标名字面量类型 */
+const TYPE_ICON = {
+    success: { name: 'check-circle', color: '#4ADE80' },
+    error: { name: 'close-circle', color: '#F87171' },
+    info: { name: 'info-circle', color: '#60A5FA' },
+    warning: { name: 'warning', color: '#FBBF24' },
+};
+// ================= 单条 Toast UI =================
+const XToastItem = ({ toast, onClose }) => {
+    const theme = useXTheme();
+    const opacity = useRef(new Animated.Value(0)).current;
+    const fromTop = toast.position === 'top';
+    const translateY = useRef(new Animated.Value(fromTop ? -24 : 24)).current;
+    useEffect(() => {
+        // 入场：淡入 + 弹簧位移
+        Animated.parallel([
+            Animated.timing(opacity, { toValue: 1, duration: 180, useNativeDriver: true }),
+            Animated.spring(translateY, { toValue: 0, useNativeDriver: true, friction: 9, tension: 80 }),
+        ]).start();
+        // 定时退场（duration 为 0 时不自动消失，由调用方手动控制）
+        let timer;
+        if (toast.duration > 0) {
+            timer = setTimeout(() => {
+                Animated.timing(opacity, { toValue: 0, duration: 200, useNativeDriver: true }).start(({ finished }) => {
+                    if (finished)
+                        onClose();
+                });
+            }, toast.duration);
+        }
+        return () => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const icon = TYPE_ICON[toast.type];
+    return (_jsxs(Animated.View, { style: [styles.toast, { opacity, transform: [{ translateY }] }], children: [toast.type === 'loading' ? (_jsx(ActivityIndicator, { size: 'small', color: theme.colorTextLightSolid })) : (icon && _jsx(AntDesign, { name: icon.name, size: 18, color: icon.color })), !!toast.message && (_jsx(Text, { style: [styles.text, { color: theme.colorTextLightSolid, fontSize: theme.fontSize }], children: toast.message }))] }));
+};
+const styles = StyleSheet.create({
+    toast: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        gap: 8,
+        maxWidth: '82%',
+        paddingHorizontal: 18,
+        paddingVertical: 12,
+        borderRadius: 999,
+        // 深色胶囊：明暗两种模式都保持固定深色底，保证语义图标对比度
+        backgroundColor: 'rgba(23,26,31,0.94)',
+        shadowColor: '#000',
+        shadowOpacity: 0.25,
+        shadowRadius: 16,
+        shadowOffset: { width: 0, height: 8 },
+        elevation: 8,
+    },
+    text: {
+        lineHeight: 20,
+        flexShrink: 1,
+    },
+});
+const styles_overlay = StyleSheet.create({
+    top: {
+        ...{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 },
+        justifyContent: 'flex-start',
+        alignItems: 'center',
+        gap: 8,
+    },
+    center: {
+        ...{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 },
+        justifyContent: 'center',
+        alignItems: 'center',
+        gap: 8,
+    },
+    bottom: {
+        ...{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 },
+        justifyContent: 'flex-end',
+        alignItems: 'center',
+        gap: 8,
+    },
+});
+// ================= Context =================
+const XToastContext = createContext({
+    addToast: () => { },
+});
+/** 组件内获取 addToast 的 Hook */
+export const useXToast = () => useContext(XToastContext);
+// ================= Provider + Service =================
+/** 全局句柄：Provider 挂载时写入，卸载时清空 */
+let addToastHandle = null;
+export const XToastProvider = ({ children }) => {
+    const [toasts, setToasts] = useState([]);
+    const nextIdRef = useRef(0);
+    const insets = useSafeAreaInsets();
+    const addToast = useCallback((options) => {
+        const id = ++nextIdRef.current;
+        setToasts(prev => {
+            const next = [
+                ...prev,
+                {
+                    id,
+                    message: options.message,
+                    duration: options.duration ?? 2000,
+                    type: options.type ?? 'text',
+                    position: options.position ?? 'bottom',
+                },
+            ];
+            // 超出上限时丢最旧的
+            return next.slice(-MAX_VISIBLE);
+        });
+    }, []);
+    const removeToast = useCallback((id) => {
+        setToasts(prev => prev.filter(toast => toast.id !== id));
+    }, []);
+    useEffect(() => {
+        addToastHandle = addToast;
+        return () => {
+            if (addToastHandle === addToast) {
+                addToastHandle = null;
+            }
+        };
+    }, [addToast]);
+    const byPosition = (position) => toasts.filter(toast => toast.position === position);
+    const renderPosition = (position) => {
+        const list = byPosition(position);
+        if (list.length === 0) {
+            return null;
+        }
+        return (_jsx(View, { pointerEvents: 'box-none', style: [
+                styles_overlay[position],
+                position === 'top' ? { paddingTop: insets.top + 56 } : null,
+                position === 'bottom' ? { paddingBottom: insets.bottom + 80 } : null,
+            ], children: list.map(toast => (_jsx(XToastItem, { toast: toast, onClose: () => removeToast(toast.id) }, toast.id))) }, position));
+    };
+    return (_jsxs(XToastContext.Provider, { value: { addToast }, children: [children, ['top', 'center', 'bottom'].map(renderPosition)] }));
+};
+/**
+ * XToastService —— 命令式调用入口（可在组件外使用）
+ * show 支持两种签名：
+ *   show('保存成功')                            纯文本
+ *   show({message, type, duration, position})   完整配置
+ */
+export const XToastService = {
+    show: (messageOrOptions, duration) => {
+        const options = typeof messageOrOptions === 'string' ? { message: messageOrOptions, duration } : messageOrOptions;
+        if (__DEV__ && !addToastHandle) {
+            console.warn('[XToastService] XToastProvider 未挂载，本次 show 调用被忽略');
+        }
+        addToastHandle?.(options);
+    },
+};

package/dist/XProviders/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ============================================================================
+ * XProviders —— X 系列命令式全局组件（Provider 类）统一出口
+ * ============================================================================
+ *
+ * 这个目录专门存放"Provider 类型"的 X 组件：需要在 App 根部挂载一次 Provider，
+ * 之后通过 Service 在任意位置（含非组件环境，如 axios 拦截器）命令式调用。
+ *
+ * 目前三件套：
+ * - XLoadingModal   全局 Loading（show/hide，引用计数，支持并发）
+ * - XImagePreview   全屏图片预览（缩放/翻页手势，微信相册同款交互）
+ * - XToast          全局轻提示（success/error/info/warning/loading，三位置）
+ *
+ * 统一挂载（App 根部，放 GestureHandlerRootView 内、SafeAreaProvider 内）：
+ *
+ *   <XLoadingModalProvider>
+ *     <XImagePreviewProvider>
+ *       <XToastProvider>
+ *         {children}
+ *       </XToastProvider>
+ *     </XImagePreviewProvider>
+ *   </XLoadingModalProvider>
+ *
+ * 完整可运行示例见同目录 usageExample.tsx。
+ */
+export { XLoadingModal, XLoadingModalProvider, XLoadingModalService } from './XLoadingModal';
+export type { XLoadingModalProps, XLoadingModalConfig } from './XLoadingModal';
+export { XImagePreview, XImagePreviewProvider, XImagePreviewService } from './XImagePreview';
+export type { XImagePreviewParams } from './XImagePreview';
+export { XToastProvider, XToastService, useXToast } from './XToast';
+export type { XToastOptions, XToastType, XToastPosition } from './XToast';

package/dist/XProviders/index.js

@@ -0,0 +1,28 @@
+/**
+ * ============================================================================
+ * XProviders —— X 系列命令式全局组件（Provider 类）统一出口
+ * ============================================================================
+ *
+ * 这个目录专门存放"Provider 类型"的 X 组件：需要在 App 根部挂载一次 Provider，
+ * 之后通过 Service 在任意位置（含非组件环境，如 axios 拦截器）命令式调用。
+ *
+ * 目前三件套：
+ * - XLoadingModal   全局 Loading（show/hide，引用计数，支持并发）
+ * - XImagePreview   全屏图片预览（缩放/翻页手势，微信相册同款交互）
+ * - XToast          全局轻提示（success/error/info/warning/loading，三位置）
+ *
+ * 统一挂载（App 根部，放 GestureHandlerRootView 内、SafeAreaProvider 内）：
+ *
+ *   <XLoadingModalProvider>
+ *     <XImagePreviewProvider>
+ *       <XToastProvider>
+ *         {children}
+ *       </XToastProvider>
+ *     </XImagePreviewProvider>
+ *   </XLoadingModalProvider>
+ *
+ * 完整可运行示例见同目录 usageExample.tsx。
+ */
+export { XLoadingModal, XLoadingModalProvider, XLoadingModalService } from './XLoadingModal';
+export { XImagePreview, XImagePreviewProvider, XImagePreviewService } from './XImagePreview';
+export { XToastProvider, XToastService, useXToast } from './XToast';

package/dist/XProviders/usageExample.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ============================================================================
+ * XProviders 使用示例（可运行演示页）
+ * ============================================================================
+ *
+ * 演示 XLoadingModal / XImagePreview / XToast 三件套的完整用法。
+ * 页面自身演示了正确的挂载层级（生产环境应挂到 App 根部，这里为了独立可跑
+ * 直接包在本页内；SafeAreaProvider / GestureHandlerRootView 已由 App 根部
+ * 提供时无需重复包裹，本页包一层是为了单独调试也能正常运行）。
+ *
+ * 快速上手（别处使用）：
+ *   XLoadingModalService.show({title: '上传中...'});
+ *   XLoadingModalService.hide();
+ *   XImagePreviewService.show({images: urls, initialIndex: 0});
+ *   XToastService.show({message: '保存成功', type: 'success'});
+ */
+import React from 'react';
+declare const XProvidersDemo: () => React.JSX.Element;
+export default XProvidersDemo;