react-native-x-components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# react-native-x-components
+
+Ant Design 风格的 React Native (Expo) 组件库。对齐 antd v5 设计 token，内置**暗黑模式**与**中英双语**，弹层体系基于自研 TopView（比 RN Modal 更快），覆盖表单、选择器、日历、录音、签名（Skia 逐字签名）、上传（MinIO 预签名适配器）、轻量图表等 40+ 组件。
+
+## 特性
+
+- 🌗 **暗黑模式**：`useXTheme()` 全组件自适应，`setXThemeMode('light' | 'dark' | 'system')` 一行切换
+- 🌐 **国际化**：内置 zh-CN / en-US 字典，`setXLocale('en-US')` 即时生效
+- ⚡ **TopView 弹层**：Reanimated UI 线程驱动，无原生 Modal 开销
+- 📝 **Skia 逐字签名**：一字一格可重写，结构化 value，中点二次贝塞尔平滑
+- 📤 **上传适配器**：UI 与上传彻底解耦，内置 MinIO 预签名直传 / multipart / Mock 三种适配器
+- 📊 **轻量图表**：react-native-svg 自研折线/柱状/环形，零重量级依赖
+
+## 安装
+
+```bash
+npm install react-native-x-components dayjs zustand
+# 必需 peer 依赖（Expo 项目推荐用 expo install 自动匹配版本）
+npx expo install react-native-reanimated react-native-safe-area-context react-native-svg
+# 可选（按需装）：
+# 签名: npx expo install @shopify/react-native-skia
+# 录音: npx expo install expo-audio
+# 上传: npx expo install expo-image-picker expo-image-manipulator expo-file-system
+```
+
+## 快速上手
+
+```tsx
+import {
+  XPopupProvider,   // 1. 根部挂弹层宿主（必需一次）
+  XButton,
+  XCalendarPopup,
+  setXThemeMode,    // 2. 暗黑模式
+  setXLocale,       // 3. 中英切换
+} from 'react-native-x-components';
+
+export default function App() {
+  return (
+    <XPopupProvider>
+      <XButton type="primary" onPress={() => setXThemeMode('dark')}>
+        切换暗黑
+      </XButton>
+    </XPopupProvider>
+  );
+}
+```
+
+## 组件总览
+
+| 分类 | 组件 |
+| --- | --- |
+| 基础 | XButton XDivider XInput XImage XTag XProgress XRadio XCheckbox |
+| 表单 | XForm XFormPro XCascadeSelect XMultiSelect XModalForm |
+| 弹层 | XPullView XActionSheet XPicker XPickerDate XConfirmForm XTopView XAnimatedView |
+| 全局 | XToast XLoadingModal XImagePreview |
+| 交互 | XCarousel XTabs XDropdownMenu XElevator XNumberKeyboard XLicensePlate |
+| 媒体 | XRecord XCalendar XCalendarPopup XSignature XSignatureSkia XUploadImage XUploadVideo |
+| 数据 | XChart(XLineChart/XBarChart/XPieChart) |
+| 基建 | useXTheme setXThemeMode useXLocale setXLocale XUploadProvider |
+
+## 上传适配器（MinIO 预签名直传）
+
+```tsx
+import { setXUploadAdapter, createMinioPresignedAdapter } from 'react-native-x-components';
+
+// App 入口注入一次（对接你的后端预签名接口）
+setXUploadAdapter(
+  createMinioPresignedAdapter({
+    getUploadUrl: async ({ name, mimeType }) => {
+      const res = await fetch(`${API}/file/getUploadUrl?fileName=${name}&contentType=${mimeType}`);
+      const { data } = await res.json();
+      return { objectKey: data.objectKey, preSignedUrl: data.preSignedUrl };
+    },
+    getPreviewUrl: async (objectKey) => {
+      const res = await fetch(`${API}/file/getPreviewUrl?objectKey=${objectKey}`);
+      const { data } = await res.json();
+      return data.preSignedUrl;
+    },
+  }),
+);
+```
+
+之后 `<XUploadImage />` / `<XUploadVideo />` / `uploadBase64()` 全部走该通道；换后端只换适配器。
+
+## 主题定制
+
+```ts
+// 修改浅色/暗黑 token（如品牌色）
+import { lightTokens, darkTokens } from 'react-native-x-components';
+lightTokens.colorPrimary = '#7C3AED';
+darkTokens.colorPrimary = '#A78BFA';
+```
+
+## License
+
+MIT

package/dist/XActionSheet/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ============================================================================
+ * XActionSheet —— 底部弹出菜单（duxui XActionSheet 移植）
+ * ============================================================================
+ *
+ * 【组合模式】
+ * 它本身不写任何动画代码 —— 只是给 XPullView 传 children（菜单内容），
+ * XPullView 负责"底部滑入 + 遮罩淡入"的整套动画。
+ * 这就是这套组件库的设计思路：XPullView 是动画引擎，业务组件是内容。
+ *
+ * 【交互】
+ * - 点选项 → onClose + onSelect(option)（先关再回调，保证动画和业务分离）
+ * - 点取消/遮罩 → onClose
+ * - danger 选项显示红色（危险操作）、disabled 选项置灰不可点
+ *
+ * 【安全区】
+ * useSafeAreaInsets() 取 iPhone 底部 Home 条高度，
+ * paddingBottom 保证取消按钮不被 Home 条挡住。
+ * ============================================================================
+ */
+import React from 'react';
+import { ViewStyle, StyleProp } from 'react-native';
+/** 菜单选项 */
+export interface XActionSheetOption<T = any> {
+    /** 显示文本 */
+    label: string;
+    /** 回传的值 */
+    value: T;
+    /** 危险操作：文字变红 */
+    danger?: boolean;
+    /** 禁用：置灰且不可点 */
+    disabled?: boolean;
+}
+interface XActionSheetProps<T = any> {
+    visible: boolean;
+    onClose: () => void;
+    options: XActionSheetOption<T>[];
+    /** 顶部标题（可选） */
+    title?: string;
+    cancelText?: string;
+    duration?: number;
+    /** 选中选项回调 */
+    onSelect?: (option: XActionSheetOption<T>) => void;
+    style?: StyleProp<ViewStyle>;
+}
+export declare function XActionSheet<T = any>({ visible, onClose, options, title, cancelText, duration, onSelect, style, }: XActionSheetProps<T>): React.JSX.Element;
+export {};

package/dist/XActionSheet/index.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XActionSheet —— 底部弹出菜单（duxui XActionSheet 移植）
+ * ============================================================================
+ *
+ * 【组合模式】
+ * 它本身不写任何动画代码 —— 只是给 XPullView 传 children（菜单内容），
+ * XPullView 负责"底部滑入 + 遮罩淡入"的整套动画。
+ * 这就是这套组件库的设计思路：XPullView 是动画引擎，业务组件是内容。
+ *
+ * 【交互】
+ * - 点选项 → onClose + onSelect(option)（先关再回调，保证动画和业务分离）
+ * - 点取消/遮罩 → onClose
+ * - danger 选项显示红色（危险操作）、disabled 选项置灰不可点
+ *
+ * 【安全区】
+ * useSafeAreaInsets() 取 iPhone 底部 Home 条高度，
+ * paddingBottom 保证取消按钮不被 Home 条挡住。
+ * ============================================================================
+ */
+import { useCallback, useMemo } from 'react';
+import { Pressable, StyleSheet, View, Text } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { XPullView } from '../XPullView';
+import { useXTheme } from '../theme';
+import { useXLocale } from '../XLocale';
+export function XActionSheet({ visible, onClose, options, title, cancelText, duration = 200, onSelect, style, }) {
+    const t = useXTheme();
+    const { t: i18n } = useXLocale();
+    const resolvedCancel = cancelText ?? i18n('cancel');
+    const insets = useSafeAreaInsets();
+    /** style sheet 置于组件内，按主题对象 t 构造（color 字段需跟随暗黑模式） */
+    const styles = useMemo(() => StyleSheet.create({
+        /** 面板整体：浅灰底 + 圆角，顶部裁圆角 */
+        panel: {
+            backgroundColor: t.colorBgLayout,
+            borderTopLeftRadius: 12,
+            borderTopRightRadius: 12,
+            overflow: 'hidden',
+        },
+        header: {
+            paddingVertical: 14,
+            backgroundColor: t.colorBgContainer,
+        },
+        title: {
+            textAlign: 'center',
+            fontSize: 13,
+            color: t.colorTextTertiary,
+        },
+        /** 选项区：白底，每个选项之间用 hairline 细线分隔 */
+        optionList: {
+            backgroundColor: t.colorBgContainer,
+        },
+        option: {
+            height: 52,
+            justifyContent: 'center',
+            alignItems: 'center',
+            borderTopWidth: StyleSheet.hairlineWidth,
+            borderTopColor: t.colorSplit,
+        },
+        /** 按压反馈底色 */
+        pressed: {
+            backgroundColor: t.colorBgLayout,
+        },
+        optionText: {
+            fontSize: 16,
+            color: t.colorText,
+        },
+        dangerText: {
+            color: t.colorError,
+        },
+        disabledText: {
+            color: t.colorTextQuaternary,
+        },
+        cancelGap: {
+            height: 8,
+        },
+        cancel: {
+            height: 54,
+            justifyContent: 'center',
+            alignItems: 'center',
+            backgroundColor: t.colorBgContainer,
+            borderTopLeftRadius: 12,
+            borderTopRightRadius: 12,
+        },
+        cancelText: {
+            fontSize: 16,
+            color: t.colorTextSecondary,
+        },
+    }), [t]);
+    /** 点选项：先关闭弹层，再通知业务方选中了谁 */
+    const handleSelect = useCallback((option) => {
+        onClose();
+        onSelect?.(option);
+    }, [onClose, onSelect]);
+    return (_jsx(XPullView, { visible: visible, onClose: onClose, side: 'bottom', duration: duration, overlayOpacity: 0.4, children: _jsxs(View, { style: [styles.panel, style, { paddingBottom: Math.max(insets.bottom, 10) }], children: [!!title && (_jsx(View, { style: styles.header, children: _jsx(Text, { style: styles.title, children: title }) })), _jsx(View, { style: styles.optionList, children: options.map(option => (_jsx(Pressable, { disabled: option.disabled, onPress: () => handleSelect(option), 
+                        // style 可以是函数：pressed 状态时换个底色，模拟按压反馈
+                        style: ({ pressed }) => [styles.option, pressed && !option.disabled && styles.pressed], children: _jsx(Text, { style: [styles.optionText, option.danger && styles.dangerText, option.disabled && styles.disabledText], children: option.label }) }, String(option.value)))) }), _jsx(View, { style: styles.cancelGap }), _jsx(Pressable, { onPress: onClose, style: ({ pressed }) => [styles.cancel, pressed && styles.pressed], children: _jsx(Text, { style: styles.cancelText, children: resolvedCancel }) })] }) }));
+}

package/dist/XAnimatedSearchPanel/index.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+interface XAnimatedSearchPanelProps {
+    children?: React.ReactNode;
+    /**
+     * 内容高度兜底值。
+     * 首帧 onLayout 还没回调时用它，测到真实高度后立刻被覆盖。
+     * 作用是避免「首次点击展开时高度是 0，动画看起来没反应」。
+     */
+    contentHeight?: number;
+    onSearch: () => void;
+    onReset: () => void;
+    /**
+     * 'spring'（默认）：收尾带极轻微回弹，手感更「活」；
+     * 'timing'：纯缓动，时长可控、绝对不过冲。
+     * 面板嵌在长列表头部、或对时序有严格要求时用 'timing'。
+     */
+    motion?: 'spring' | 'timing';
+    defaultExpanded?: boolean;
+    /**
+     * 注意：如果父组件在这里 setState，会在展开首帧引入一次 React 渲染，
+     * 可能造成第一帧轻微卡顿。只在真的需要同步外部状态时才传。
+     */
+    onToggle?: (expanded: boolean) => void;
+}
+export declare const XAnimatedSearchPanel: ({ children, contentHeight, onSearch, onReset, motion, defaultExpanded, onToggle, }: XAnimatedSearchPanelProps) => React.JSX.Element;
+/**
+ * 样式取值约定（同 X-Components 其他组件）：
+ * 颜色 / 圆角 / 字号一律从 theme token 取，组件内不写死色值；
+ * 仅阴影基色是纯黑中性值，theme 中无对应 token，故保留字面量。
+ * 因 color 字段需跟随暗黑模式，style sheet 在组件内按主题对象 t 构造。
+ */
+export type { XAnimatedSearchPanelProps };
+export default XAnimatedSearchPanel;

package/dist/XAnimatedSearchPanel/index.js

@@ -0,0 +1,295 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef } from 'react';
+import { View, StyleSheet, TouchableOpacity, Text } from 'react-native';
+import Animated, { Easing, Extrapolation, ReduceMotion, interpolate, useAnimatedStyle, useSharedValue, withSpring, withTiming, } from 'react-native-reanimated';
+import AntDesign from '@react-native-vector-icons/ant-design';
+import { useXTheme } from '../theme';
+import { useXLocale } from '../XLocale';
+/**
+ * ── 展开/收起的弹簧参数 ──────────────────────────────────────────────
+ * Reanimated 的 withSpring 是一个**阻尼谐振子**的数值积分：
+ *   加速度 = (-stiffness * 位移 - damping * 速度) / mass
+ *
+ *   stiffness 刚度：越大越急，动画越快到达目标；
+ *   damping   阻尼：越大越「粘」，越小越容易来回振荡；
+ *   mass      质量：越大惯性越强，起步慢、余振长。
+ *
+ * 阻尼比 ζ = damping / (2 * sqrt(stiffness * mass))
+ *   ζ < 1 欠阻尼（会过冲、有回弹）
+ *   ζ = 1 临界阻尼（最快到达且不过冲）
+ *   ζ > 1 过阻尼（慢慢爬过去，显得拖沓）
+ * 本配置 ζ = 22 / (2 * sqrt(240 * 0.75)) ≈ 0.82 —— 略欠阻尼，
+ * 收尾有一丝几乎察觉不到的回弹，这是「丝滑」的来源。
+ *
+ * ⚠️ rest 阈值必须调小：
+ * progress 归一化在 0~1，而 Reanimated 默认阈值是按「像素级数值」定的
+ * （restDisplacementThreshold 0.01 / restSpeedThreshold 2）。
+ * 对 0~1 的量来说 0.01 相当于面板高度的 1%，弹簧会在肉眼可见的位置
+ * 提前判定「已静止」而被直接吸附到终点，出现一次微小的跳变。
+ */
+const SPRING_CONFIG = {
+    damping: 22,
+    stiffness: 240,
+    mass: 0.75,
+    // 允许轻微过冲（true 会硬性截断，手感变「木」）
+    overshootClamping: false,
+    restDisplacementThreshold: 0.001,
+    restSpeedThreshold: 0.01,
+    // 跟随系统「减弱动效」无障碍开关：开启时 Reanimated 自动降级为瞬时到位
+    reduceMotion: ReduceMotion.System,
+};
+/**
+ * ── 纯缓动参数 ──────────────────────────────────────────────────────
+ * cubic-bezier(0.22, 1, 0.36, 1) 即 easeOutQuint：
+ * 起步极快、尾巴很长的减速曲线。
+ * 折叠面板最忌讳「匀速」（linear 会像机械百叶窗）和「先慢后快」，
+ * 人眼对「立刻响应 + 缓缓停住」的判断就是「顺滑」。
+ * 320ms 是折叠类交互的舒适区间：<200ms 会显得生硬突兀，>400ms 开始觉得慢。
+ */
+const TIMING_CONFIG = {
+    duration: 320,
+    easing: Easing.bezier(0.22, 1, 0.36, 1),
+    reduceMotion: ReduceMotion.System,
+};
+/**
+ * ── 内容自身高度变化时的补间 ─────────────────────────────────────────
+ * 场景：面板已展开，里面的下拉选项异步加载完成 / 校验错误提示出现，
+ * 内容高度从 240 变成 310。若直接赋值，用户会看到一次生硬跳变。
+ * 这里用一段更短更朴素的缓动（220ms + easeOutQuad）平滑过去——
+ * 它是「修正」而不是「主角」，所以不该比主动画更抢眼。
+ */
+const RESIZE_CONFIG = {
+    duration: 220,
+    easing: Easing.out(Easing.quad),
+    reduceMotion: ReduceMotion.System,
+};
+export const XAnimatedSearchPanel = ({ children, contentHeight = 300, onSearch, onReset, motion = 'spring', defaultExpanded = false, onToggle, }) => {
+    const t = useXTheme();
+    const { t: i18n } = useXLocale();
+    /**
+     * style sheet 置于组件内，按主题对象 t 构造（color 字段需跟随暗黑模式）。
+     * t 在 light/dark 间切换时引用改变，useMemo 仅在此处重算。
+     */
+    const styles = useMemo(() => StyleSheet.create({
+        card: {
+            backgroundColor: t.colorBgContainer,
+            borderRadius: t.borderRadiusXL,
+            marginHorizontal: 12,
+            paddingHorizontal: 12,
+            marginVertical: 12,
+            shadowColor: '#000',
+            shadowOffset: { width: 0, height: 1 },
+            shadowOpacity: 0.1,
+            shadowRadius: 2,
+            elevation: 1,
+        },
+        searchHeader: {
+            flexDirection: 'row',
+            justifyContent: 'space-between',
+            alignItems: 'center',
+            paddingVertical: 16,
+        },
+        /** 给交叉淡入的两层文案撑出固定尺寸，见 JSX 注释 */
+        titleWrap: {
+            width: 100,
+            height: 22,
+            justifyContent: 'center',
+        },
+        titleLayer: {
+            position: 'absolute',
+            left: 0,
+            right: 0,
+        },
+        searchTitle: {
+            fontSize: t.fontSizeLG,
+            width: 100,
+            fontWeight: '500',
+            color: t.colorText,
+        },
+        /** overflow 静态声明，动画只改 height —— 这是折叠效果的实现基础 */
+        body: {
+            overflow: 'hidden',
+        },
+        searchRow: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            marginBottom: 12,
+        },
+        searchLabel: {
+            width: 80,
+            fontSize: t.fontSize,
+            color: t.colorTextSecondary,
+        },
+        searchInput: {
+            flex: 1,
+            height: 40,
+            borderWidth: 1,
+            borderColor: t.colorBorder,
+            borderRadius: t.borderRadiusSM,
+            paddingHorizontal: 12,
+            paddingVertical: 2,
+            fontSize: t.fontSize,
+        },
+        dateText: {
+            fontSize: t.fontSize,
+            lineHeight: 34,
+            color: t.colorText,
+        },
+        placeholderText: {
+            lineHeight: 34,
+            fontSize: t.fontSize,
+            color: t.colorTextTertiary,
+        },
+        searchButtons: {
+            flexDirection: 'row',
+            justifyContent: 'flex-end',
+            marginVertical: 16,
+        },
+        searchButton: {
+            paddingHorizontal: 24,
+            height: t.controlHeightSM,
+            borderRadius: t.borderRadiusSM,
+            justifyContent: 'center',
+            alignItems: 'center',
+            marginLeft: 12,
+        },
+        resetButton: {
+            borderWidth: 1,
+            borderColor: t.colorPrimary,
+            backgroundColor: t.colorBgContainer,
+        },
+        resetButtonText: {
+            color: t.colorPrimary,
+            fontSize: t.fontSize,
+            fontWeight: '500',
+        },
+        submitButton: {
+            backgroundColor: t.colorPrimary,
+        },
+        submitButtonText: {
+            color: t.colorTextLightSolid,
+            fontSize: t.fontSize,
+            fontWeight: '500',
+        },
+    }), [t]);
+    /**
+     * progress：唯一的动画时间轴，0 = 完全收起，1 = 完全展开。
+     * SharedValue 是一块 JS 与 UI 线程共享的内存，写入它不会触发 React 渲染，
+     * 所以动画过程对 React 完全「透明」。
+     */
+    const progress = useSharedValue(defaultExpanded ? 1 : 0);
+    /**
+     * contentH：onLayout 量到的真实内容高度，同样放在 SharedValue 里。
+     * 关键点——不要用 useState 存高度：
+     * 那会让每次测量都触发一次 React 重渲染，而且 useAnimatedStyle 里
+     * 读 state 需要把它作为依赖重建 worklet，得不偿失。
+     */
+    const contentH = useSharedValue(0);
+    /**
+     * 展开状态用 ref 而非 state：
+     * 组件的视觉表现完全由 progress 决定，React 不需要为「展开与否」重渲染。
+     * ref 只是给 toggle 逻辑做方向判断用的普通变量。
+     */
+    const expandedRef = useRef(defaultExpanded);
+    /** 上一次量到的高度，用于去重，避免 onLayout 抖动导致反复触发补间 */
+    const measuredRef = useRef(0);
+    const toggle = useCallback(() => {
+        // 先算目标值，再翻转 ref，顺序反了会拿到错误的方向
+        const next = expandedRef.current ? 0 : 1;
+        expandedRef.current = !expandedRef.current;
+        /**
+         * 这一行是整个组件的核心：
+         * 只要给 progress 赋一个 withSpring/withTiming 包装的值，
+         * Reanimated 就会在 UI 线程按帧推进它，所有依赖它的
+         * useAnimatedStyle 自动重算。
+         *
+         * 打断行为天然正确：连点时新动画会从**当前中间值和当前速度**继续，
+         * 而不是从 0/1 重新开始——这就是不会出现「跳一下再动」的原因。
+         */
+        progress.value = motion === 'timing' ? withTiming(next, TIMING_CONFIG) : withSpring(next, SPRING_CONFIG);
+        onToggle?.(expandedRef.current);
+    }, [motion, onToggle, progress]);
+    const onContentLayout = useCallback((e) => {
+        // 取整：亚像素高度会让去重判断永远不相等，从而反复触发补间
+        const h = Math.round(e.nativeEvent.layout.height);
+        // h <= 0 是布局过程中的中间态（例如父容器高度为 0 时），直接丢弃
+        if (h <= 0 || h === measuredRef.current)
+            return;
+        const isFirstMeasure = measuredRef.current === 0;
+        measuredRef.current = h;
+        /**
+         * 两种赋值策略：
+         *  - 首次测量 或 当前是收起态：用户看不见这层内容，直接硬赋值，
+         *    省掉一次无意义的动画（也避免首帧出现一次「自己长出来」的动作）；
+         *  - 已展开状态下高度变了：走 RESIZE_CONFIG 补间，避免跳变。
+         */
+        if (isFirstMeasure || !expandedRef.current) {
+            contentH.value = h;
+        }
+        else {
+            contentH.value = withTiming(h, RESIZE_CONFIG);
+        }
+    }, [contentH]);
+    /**
+     * ── 派生样式 1：容器高度 ──────────────────────────────────────────
+     * useAnimatedStyle 的回调是一个 worklet：它被编译后直接在 UI 线程执行，
+     * 每帧读取 SharedValue 并返回样式对象，然后由原生侧直接改视图属性，
+     * 完全不经过 JS 线程和 React 的 diff。
+     *
+     * Math.max(0, ...)：spring 欠阻尼在收起方向会短暂冲到负值，
+     * 负高度在 Android 上会报警告/表现异常，这里 clamp 住，
+     * 保证收起只有减速、不会「反向溢出」。
+     *
+     * contentH.value || contentHeight：真实高度还没量到时退回兜底值。
+     */
+    const bodyStyle = useAnimatedStyle(() => {
+        const target = contentH.value || contentHeight;
+        return { height: Math.max(0, progress.value * target) };
+    });
+    /**
+     * ── 派生样式 2：内容淡入 + 轻微下滑 ───────────────────────────────
+     * 只做高度变化会像「拉幕布」，因为内容是被裁切出来的，缺少自身的运动。
+     * 叠一层 opacity + translateY 之后，内容像是「跟着容器一起落下来」，
+     * 层次感来自这两条曲线的时间差（错峰，staggering）：
+     *
+     *   opacity   在 progress 0.12~0.7 之间完成 → 容器先开一点点，内容才开始显现
+     *   translateY 在 0~1 全程从 -14 走到 0     → 位移贯穿整段，收尾最平缓
+     *
+     * Extrapolation.CLAMP：超出输入区间时保持端点值，
+     * 否则 spring 过冲到 1.03 时 opacity 会被线性外推成 >1（部分平台异常）。
+     */
+    const contentStyle = useAnimatedStyle(() => ({
+        opacity: interpolate(progress.value, [0.12, 0.7], [0, 1], Extrapolation.CLAMP),
+        transform: [{ translateY: interpolate(progress.value, [0, 1], [-14, 0], Extrapolation.CLAMP) }],
+    }));
+    /**
+     * ── 派生样式 3：箭头旋转 ──────────────────────────────────────────
+     * 直接线性映射到 0~180deg。它和高度共享同一 progress，
+     * 所以弹簧的回弹也会同步体现在箭头上——这种「一起动、一起停」
+     * 的一致性是廉价但极有效的高级感来源。
+     */
+    const iconStyle = useAnimatedStyle(() => ({
+        transform: [{ rotate: `${progress.value * 180}deg` }],
+    }));
+    /**
+     * ── 派生样式 4/5：标题文案交叉淡入（cross-fade）────────────────────
+     * 「展开搜索 / 收起搜索」两段文字**同时存在**，用绝对定位叠在一起，
+     * 靠透明度和位移交替出没，而不是 progress > 0.5 ? A : B 的条件渲染。
+     *
+     * 为什么不用条件渲染：那会在中途产生一次 React 重渲染 + 文字节点增删，
+     * 视觉上是硬切换，且会让这一帧比其他帧更耗时（掉帧就发生在这一帧）。
+     *
+     * 两段区间刻意不重叠（0~0.45 与 0.55~1），中间留出 0.1 的空档，
+     * 避免两行字同时半透明地重影在一起。
+     */
+    const expandTextStyle = useAnimatedStyle(() => ({
+        opacity: interpolate(progress.value, [0, 0.45], [1, 0], Extrapolation.CLAMP),
+        transform: [{ translateY: interpolate(progress.value, [0, 0.45], [0, -8], Extrapolation.CLAMP) }],
+    }));
+    const collapseTextStyle = useAnimatedStyle(() => ({
+        opacity: interpolate(progress.value, [0.55, 1], [0, 1], Extrapolation.CLAMP),
+        transform: [{ translateY: interpolate(progress.value, [0.55, 1], [8, 0], Extrapolation.CLAMP) }],
+    }));
+    return (_jsxs(View, { style: styles.card, children: [_jsxs(TouchableOpacity, { style: styles.searchHeader, onPress: toggle, activeOpacity: 0.7, children: [_jsxs(View, { style: styles.titleWrap, children: [_jsx(Animated.View, { style: [styles.titleLayer, expandTextStyle], children: _jsx(Text, { style: styles.searchTitle, children: i18n('expandSearch') }) }), _jsx(Animated.View, { style: [styles.titleLayer, collapseTextStyle], children: _jsx(Text, { style: styles.searchTitle, children: i18n('collapseSearch') }) })] }), _jsx(Animated.View, { style: iconStyle, children: _jsx(AntDesign, { name: 'down', size: 20, color: t.colorText }) })] }), _jsx(Animated.View, { style: [styles.body, bodyStyle], collapsable: false, children: _jsx(Animated.View, { style: contentStyle, children: _jsxs(View, { onLayout: onContentLayout, children: [children, _jsxs(View, { style: styles.searchButtons, children: [_jsx(TouchableOpacity, { style: [styles.searchButton, styles.resetButton], onPress: onReset, activeOpacity: 0.7, children: _jsx(Text, { style: styles.resetButtonText, children: i18n('reset') }) }), _jsx(TouchableOpacity, { style: [styles.searchButton, styles.submitButton], onPress: onSearch, activeOpacity: 0.7, children: _jsx(Text, { style: styles.submitButtonText, children: i18n('search') }) })] })] }) }) })] }));
+};
+export default XAnimatedSearchPanel;

package/dist/XAnimatedView/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * ============================================================================
+ * XAnimatedView —— 通用动画视图（duxapp Animated.View 的 RN 移植版）
+ * ============================================================================
+ *
+ * 【它是干什么的？】
+ * XPullView 内部直接用了 useSharedValue + withTiming 写动画；而这里提供的
+ * XAnimatedView + anim() 是更通用的"动画引擎"，可以给任意自定义组件用，
+ * 用法和 duxapp 的 Animated.create() 完全一致（链式声明多段动画）。
+ *
+ * 【动画声明格式】
+ *   anim(200, 'ease-out')        // 默认时长 200ms、缓动 ease-out
+ *     .translateY(300)           // 第 1 步：Y 移到 300（屏外）
+ *     .opacity(0)                //        同时透明
+ *     .step()                    // 把上面这两个"动作"打包成一段
+ *     .translateY(0)             // 第 2 步：Y 移回 0
+ *     .opacity(1)                //        同时不透明
+ *     .step()                    // 打包成第二段
+ *     .export()                  // 输出 XAnimStep[] 交给 XAnimatedView
+ *
+ * 【多段动画如何播放？】
+ * 用一个 0→N 的 progress（withSequence 顺序播放 N 段 withTiming），
+ * 每段把 progress 推向 1、2、3……N。useAnimatedStyle 里用 interpolate
+ * 把 progress 映射成每个属性的具体值（inputRange: [0,1,2..N]）。
+ *
+ * 【为什么动画在 UI 线程？】
+ * useAnimatedStyle 的函数会被 Reanimated 编译成 worklet，运行在 UI 线程。
+ * JS 线程只需要发一次"开始动画"的指令，之后每一帧的插值计算
+ * 都在 UI 线程完成 → 即使 JS 线程忙（网络请求、列表渲染），动画也不掉帧。
+ * ============================================================================
+ */
+import React from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+/** 支持的缓动函数（与 CSS / duxapp 命名一致） */
+export type TimingFunction = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
+/** 一段动画：option 是时长/缓动配置，action 是这一段的属性目标值 */
+export interface XAnimStep {
+    option?: {
+        duration?: number;
+        timingFunction?: TimingFunction;
+        delay?: number;
+    };
+    action: Record<string, number>;
+}
+/** 动画构建器的链式 API */
+interface XAnimBuilder {
+    /** 把当前累积的"动作"打包成一段动画 */
+    step(option?: Partial<XAnimStep['option']>): XAnimBuilder;
+    /** 通用：直接设置某个属性目标值 */
+    set(name: string, value: number): XAnimBuilder;
+    translateY(v: number): XAnimBuilder;
+    translateX(v: number): XAnimBuilder;
+    scale(v: number): XAnimBuilder;
+    opacity(v: number): XAnimBuilder;
+    rotate(v: number): XAnimBuilder;
+    /** 导出所有动画段 */
+    export(): XAnimStep[];
+}
+/**
+ * 动画构建器（链式调用）
+ *
+ * 实现思路：
+ * - `current` 暂存当前累积的动作（{translateY: 300, opacity: 0}）；
+ * - `.step()` 把 current 打包成 {option, action} 推入 steps，然后清空 current；
+ * - `.export()` 把最后一段也打包并返回 steps 数组。
+ */
+export declare function anim(duration?: number, timingFunction?: TimingFunction, delay?: number): XAnimBuilder;
+interface XAnimatedViewProps {
+    /** 动画段数组（anim().export() 的结果） */
+    animation?: XAnimStep[];
+    style?: StyleProp<ViewStyle>;
+    children?: React.ReactNode;
+    /** 透传其余 View 属性（onPress 等） */
+    [key: string]: any;
+}
+export declare const XAnimatedView: ({ animation, style, children, ...props }: XAnimatedViewProps) => React.JSX.Element;
+export {};