react-native-system-ui 0.0.1-beta0 → 0.0.1

package/README.md

@@ -1,37 +1,127 @@
-# react-native-mobile
+# react-native-system-ui
 
-#### 介绍
-react native mobile 移动端组件库
+React Native 端的移动组件库，交互与 API 借鉴社区成熟方案，同时借鉴 **react-native-xiaoshu** 的原子化设计，目标是产出“极简、强韧、低心智”体验的系统化 UI 资产。
 
-#### 软件架构
-软件架构说明
+## 愿景 / Goals
 
+- ✅ 用统一的设计让成熟的移动端交互体验可以在原生端复用，同时尊重 React Native 的运行特性（无 less、依赖 StyleSheet）。
+- ✅ 提供轻量的设计系统（tokens + provider + hooks），组件不直接耦合具体样式，利于按需复用与主题定制。
+- ✅ 默认约束与 API 语义尽量贴近主流移动端组件库，保证迁移成本低。
+- ✅ 文档与示例聚焦“如何落地 + 如何扩展”，减少探索成本。
 
-#### 安装教程
+## 快速开始
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+```bash
+# 安装（推荐 pnpm/yarn）
+pnpm add react-native-system-ui react-native-svg
 
-#### 使用说明
+# 如需在业务中直接使用图标组件（可 Tree Shaking）
+pnpm add react-native-system-icon
 
-1.  xxxx
-2.  xxxx
-3.  xxxx
+# 同时保证项目已安装 react 和 react-native（>=19 / >=0.79）
+```
 
-#### 参与贡献
+```tsx
+import { ThemeProvider, Button } from 'react-native-system-ui'
 
-1.  Fork 本仓库
-2.  新建 Feat_xxx 分支
-3.  提交代码
-4.  新建 Pull Request
+export const Demo = () => (
+  <ThemeProvider>
+    <Button text="提交" type="primary" shadow />
+  </ThemeProvider>
+)
+```
 
+### 自定义 Tokens
 
-#### 特技
+```tsx
+import { ThemeProvider, createTokens } from 'react-native-system-ui'
 
-1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
-2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
-3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
-4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
-5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
-6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
+const foundations = createTokens({
+  palette: {
+    primary: {
+      500: '#111f8f',
+      600: '#0b1461',
+    },
+  },
+})
+
+export const App = ({ children }) => (
+  <ThemeProvider
+    value={{
+      foundations,
+      components: {
+        button: {
+          defaults: {
+            size: 'large',
+          },
+        },
+      },
+    }}
+  >
+    {children}
+  </ThemeProvider>
+)
+```
+
+### 主题预设
+
+```tsx
+import { ThemeProvider, themePresets } from 'react-native-system-ui'
+
+export const DarkPage = () => (
+  <ThemeProvider value={themePresets.dark}>
+    <Button text="夜间下单" type="primary" block />
+  </ThemeProvider>
+)
+
+export const AuroraBranding = () => (
+  <ThemeProvider value={themePresets.aurora}>
+    <Button text="Aurora" type="success" plain />
+  </ThemeProvider>
+)
+```
+
+`themePresets.light` 等价于默认主题，`themePresets.dark` 提供深色配色，`themePresets.aurora` 演示品牌化圆角/字体的组合，可直接交由 `ThemeProvider` 或 `ConfigProvider` 注入。
+
+## 架构总览
+
+| 层级 | 说明 |
+| --- | --- |
+| `src/design-system` | 仅承载基础设计变量（颜色、排版、间距、圆角等）与 `ThemeProvider`，只做公共部分。 |
+| `src/components/*` | 每个组件自带 `tokens.ts`/`useXXXTokens.ts` 等文件，负责自身的 token 推导与样式实现（Button 为首个示例）。 |
+
+> 这一层次化结构让“设计语言”与“交互实现”各司其职，可快速扩展到 40+ 组件而不失控。
+
+## 目前进度
+
+- ✳️ **Design System v0.1**：仅提供配色/间距/排版等基础变量与 `ThemeProvider` 通道，组件 token 由各自目录维护。
+- ✳️ **Button 组件**：完整覆盖常见按钮的 `type/size/plain/block/round/square/shadow` 语义，支持 `color`、`loading`、`icon` 等能力。
+- ✳️ **Flex 组件**：提供 24 栅格的 RN 封装，支持 `gutter`/`direction`/`wrap`/`Flex.Item span` 等能力。
+- ✳️ **Space 组件**：覆盖 `gap`、`divider`、`direction`、`wrap`、`align`、`justify` 等交互，并提供一套完整文档及 demo。
+- ✳️ **Cell 组件**：实现 `Cell`/`Cell.Group` 组合、`icon/isLink/arrowDirection/size` 等语义，兼容必填星号与自定义内容。
+- ✳️ **Divider 组件**：支持水平/垂直、虚线、细边框与文本定位 (`left/center/right`)，并开放 `lineColor` 与文本样式扩展。
+- ✳️ **Tag 组件**：支持 `type/size/plain/round/mark/closeable` API，可自定义 `color/textColor` 及关闭图标。
+- ✳️ **Checkbox 组件**：支持受控/非受控、`Checkbox.Group`、`shape/checkedColor/direction/max` 等能力。
+- ✳️ **Radio 组件**：基于 `Radio.Group` 实现单选分组，支持 `direction`、`checkedColor`、`labelPosition` 等配置。
+- ✳️ **Badge 组件**：提供数字/红点、`max` 截断、`offset` 偏移、自定义 `content`/`color` 与独立展示模式。
+- ✳️ **Grid 组件**：支持 `columnNum/gutter/square/border/direction/reverse` 等语义，`Grid.Item` 兼容 `badge/dot` 与 children 自定义内容。
+- ✳️ **Typography 组件**：提供 `Text/Title/Link`，支持 `type/size/ellipsis/strong/underline` 以及展开/收起、多语义排版。
+- ✳️ **图标**：使用 `react-native-system-icon` 按需引入图标组件（支持 Tree Shaking），支持 RN/Web。
+- ✳️ **Loading 组件**：实现 `circular/spinner` 两种指示器、`color/size/text/vertical` 等配置，满足过渡加载场景。
+- ✳️ **Empty 组件**：提供 `image/description/children` 语义，占位符支持默认/错误/网络/搜索以及自定义插画。
+- ✳️ **Progress 组件**：复刻 `percentage/strokeWidth/color/pivot` 语义，支持文案与置灰配置。
+- ✳️ **NoticeBar 组件**：支持滚动/换行、`mode=closeable|link`、自定义左右图标及配色。
+- ✳️ **Toast 组件**：提供受控与 `Toast.show/success/fail/loading/clear` 静态调用，支持遮罩、禁止点击与多种状态图标。
+- ✳️ **Dialog 组件**：封装确认/取消弹窗、圆角按钮主题、遮罩与关闭按钮，并提供 `Dialog.show/alert/confirm/clear` 静态调用。
+- ✳️ **Slider 组件**：支持单/双滑块、滚动/垂直/反向、步长与自定义按钮，拖动事件支持开始/结束回调。
+- ✳️ **ConfigProvider**：统一封装主题与多语言，支持 `theme` tokens 覆盖与 `locale` 切换。
+- ✳️ **文档**：Quick Start、架构说明、Aria Hooks、Button 指南已经上线（`docs/`）。
+
+## 路线图（下一步）
+
+1. **基础交互组件**：Cell、Space、Typography —— 打通排版体系；图标使用 `react-native-system-icon`。
+2. **反馈组件**：Toast、Loading、Dialog —— 依赖 Portal 能力（计划内）。
+3. **表单组件**：Field、Switch、Checkbox —— 与 rc-form 生态对接。
+4. **暗色模式**：扩展 tokens palette，支持按需切换。
+
+欢迎 issue / PR，一起把高质量的移动端交互体验带到原生世界。

package/dist/cjs/components/action-sheet/ActionSheet.js

@@ -0,0 +1,283 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+function _react() {
+  const data = _interopRequireDefault(require("react"));
+  _react = function () {
+    return data;
+  };
+  return data;
+}
+function _reactNative() {
+  const data = require("react-native");
+  _reactNative = function () {
+    return data;
+  };
+  return data;
+}
+function _reactNativeSystemIcon() {
+  const data = require("react-native-system-icon");
+  _reactNativeSystemIcon = function () {
+    return data;
+  };
+  return data;
+}
+var _hooks = require("../../hooks");
+var _hairline = require("../../utils/hairline");
+var _validate = require("../../utils/validate");
+var _loading = _interopRequireDefault(require("../loading"));
+var _popup = _interopRequireDefault(require("../popup"));
+var _tokens = require("./tokens");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+const defaultCloseIcon = /*#__PURE__*/_react().default.createElement(_reactNativeSystemIcon().Close, {
+  size: 18
+});
+const ActionSheetHeader = /*#__PURE__*/_react().default.memo(({
+  title,
+  closeable,
+  closeIcon,
+  tokens,
+  onClose
+}) => {
+  const closePress = (0, _hooks.useAriaPress)({
+    onPress: onClose
+  });
+  const {
+    colors,
+    typography
+  } = tokens;
+  return /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.header
+  }, /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.titleContainer
+  }, (0, _validate.isText)(title) ? /*#__PURE__*/_react().default.createElement(_reactNative().Text, {
+    style: [tokens.layout.title, {
+      color: colors.title,
+      fontSize: typography.title
+    }]
+  }, title) : /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.titleNode
+  }, title)), closeable ? /*#__PURE__*/_react().default.createElement(_reactNative().Pressable, _extends({
+    style: tokens.layout.closeButton,
+    accessibilityRole: "button",
+    hitSlop: 8
+  }, closePress.interactionProps), /*#__PURE__*/_react().default.isValidElement(closeIcon) ? /*#__PURE__*/_react().default.cloneElement(closeIcon, {
+    fill: colors.description,
+    color: colors.description
+  }) : closeIcon) : null);
+});
+ActionSheetHeader.displayName = 'ActionSheetHeader';
+const ActionSheetItem = /*#__PURE__*/_react().default.memo(({
+  action,
+  index,
+  tokens,
+  onPress
+}) => {
+  const disabled = !!action.disabled;
+  const loading = !!action.loading;
+  const {
+    colors,
+    spacing,
+    typography
+  } = tokens;
+  const actionPress = (0, _hooks.useAriaPress)({
+    disabled: disabled || loading,
+    onPress,
+    extraProps: {
+      accessibilityRole: 'button',
+      accessibilityState: {
+        disabled,
+        busy: loading
+      },
+      testID: `rv-action-sheet-item-${index}`
+    }
+  });
+  const color = action.color ?? colors.item;
+  const name = action.name;
+  const subname = action.subname;
+  const hasIcon = !!action.icon;
+  const hasName = (0, _validate.isRenderable)(name);
+  const hasSubname = (0, _validate.isRenderable)(subname);
+  return /*#__PURE__*/_react().default.createElement(_reactNative().Pressable, _extends({
+    style: ({
+      pressed
+    }) => [tokens.layout.item, hasIcon && tokens.layout.itemWithIcon, {
+      paddingVertical: spacing.vertical,
+      paddingHorizontal: spacing.horizontal,
+      backgroundColor: pressed && !disabled && !loading ? colors.itemPressedBackground : colors.itemBackground
+    }, action.style]
+  }, actionPress.interactionProps), hasIcon ? /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.icon
+  }, action.icon) : null, loading ? /*#__PURE__*/_react().default.createElement(_loading.default, {
+    size: 20
+  }) : hasName ? /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.itemTextWrapper
+  }, (0, _validate.isText)(name) ? /*#__PURE__*/_react().default.createElement(_reactNative().Text, {
+    style: [tokens.layout.itemText, {
+      color: disabled ? colors.disabled : color,
+      fontSize: typography.item
+    }]
+  }, name) : name, hasSubname ? (0, _validate.isText)(subname) ? /*#__PURE__*/_react().default.createElement(_reactNative().Text, {
+    style: [tokens.layout.subname, {
+      color: colors.subitem
+    }]
+  }, subname) : /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.subnameNode
+  }, subname) : null) : null);
+});
+ActionSheetItem.displayName = 'ActionSheetItem';
+const ActionSheetCancel = /*#__PURE__*/_react().default.memo(({
+  cancelText,
+  tokens,
+  onPress
+}) => {
+  const {
+    colors,
+    spacing,
+    typography
+  } = tokens;
+  const cancelPress = (0, _hooks.useAriaPress)({
+    onPress,
+    extraProps: {
+      accessibilityRole: 'button',
+      testID: 'rv-action-sheet-cancel'
+    }
+  });
+  return /*#__PURE__*/_react().default.createElement(_react().default.Fragment, null, /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: [tokens.layout.cancelGap, {
+      height: spacing.cancelGap,
+      backgroundColor: colors.cancelGapBackground
+    }]
+  }), /*#__PURE__*/_react().default.createElement(_reactNative().Pressable, _extends({
+    style: [tokens.layout.cancel, {
+      paddingVertical: spacing.vertical,
+      paddingHorizontal: spacing.horizontal,
+      backgroundColor: colors.cancelBackground
+    }]
+  }, cancelPress.interactionProps), (0, _validate.isText)(cancelText) ? /*#__PURE__*/_react().default.createElement(_reactNative().Text, {
+    style: [tokens.layout.cancelText, {
+      color: colors.cancel,
+      fontSize: typography.item
+    }]
+  }, cancelText) : cancelText));
+});
+ActionSheetCancel.displayName = 'ActionSheetCancel';
+const ActionSheet = props => {
+  const {
+    tokensOverride,
+    visible,
+    title,
+    description,
+    cancelText,
+    actions = [],
+    closeOnClickAction: closeOnClickActionProp,
+    closeOnSelect,
+    closeable: closeableProp,
+    closeIcon = defaultCloseIcon,
+    beforeClose,
+    onSelect,
+    onCancel,
+    onClose,
+    children,
+    round: roundProp,
+    safeAreaInsetBottom: safeAreaInsetBottomProp,
+    overlay: overlayProp,
+    lockScroll: lockScrollProp,
+    style: popupStyle,
+    ...popupProps
+  } = props;
+  const tokens = (0, _tokens.useActionSheetTokens)(tokensOverride);
+  const closeable = closeableProp ?? tokens.defaults.closeable;
+  const round = roundProp ?? tokens.defaults.round;
+  const safeAreaInsetBottom = safeAreaInsetBottomProp ?? tokens.defaults.safeAreaInsetBottom;
+  const overlay = overlayProp ?? tokens.defaults.overlay;
+  const lockScroll = lockScrollProp ?? tokens.defaults.lockScroll;
+  const shouldCloseOnClickAction = closeOnClickActionProp ?? closeOnSelect ?? tokens.defaults.closeOnClickAction;
+  const hasTitle = (0, _validate.isRenderable)(title);
+  const hasDescription = (0, _validate.isRenderable)(description);
+  const hasCancelText = (0, _validate.isRenderable)(cancelText);
+  const runBeforeClose = _react().default.useCallback(async action => {
+    if (!beforeClose) return true;
+    try {
+      return (await beforeClose(action)) !== false;
+    } catch (error) {
+      console.error(error);
+      return true;
+    }
+  }, [beforeClose]);
+  const requestClose = _react().default.useCallback(async action => {
+    const allowed = await runBeforeClose(action);
+    if (!allowed) return;
+    onClose?.();
+  }, [onClose, runBeforeClose]);
+  const handlePopupBeforeClose = _react().default.useCallback(reason => {
+    const action = reason === 'close-icon' ? 'close-icon' : reason === 'overlay' ? 'overlay' : 'close';
+    return runBeforeClose(action);
+  }, [runBeforeClose]);
+  const handleCancel = _react().default.useCallback(() => {
+    onCancel?.();
+    void requestClose('cancel');
+  }, [onCancel, requestClose]);
+  const handleCloseIcon = _react().default.useCallback(() => {
+    void requestClose('close-icon');
+  }, [requestClose]);
+  const handleActionPress = _react().default.useCallback((action, index) => {
+    if (action.disabled || action.loading) {
+      return;
+    }
+    action.onPress?.(action);
+    action.callback?.(action);
+    onSelect?.(action, index);
+    if (shouldCloseOnClickAction) {
+      void requestClose('action');
+    }
+  }, [onSelect, requestClose, shouldCloseOnClickAction]);
+  return /*#__PURE__*/_react().default.createElement(_popup.default, _extends({
+    visible: visible,
+    placement: "bottom",
+    round: round,
+    safeAreaInsetBottom: safeAreaInsetBottom,
+    overlay: overlay,
+    lockScroll: lockScroll,
+    beforeClose: handlePopupBeforeClose,
+    onClose: onClose,
+    style: [tokens.layout.popup, popupStyle]
+  }, popupProps), /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: [tokens.layout.panel, {
+      backgroundColor: tokens.colors.background
+    }]
+  }, hasTitle ? /*#__PURE__*/_react().default.createElement(ActionSheetHeader, {
+    title: title,
+    closeable: closeable,
+    closeIcon: closeIcon,
+    tokens: tokens,
+    onClose: handleCloseIcon
+  }) : null, hasDescription ? /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: [tokens.layout.descriptionContainer, (0, _hairline.createHairlineBorderBottom)(tokens.colors.border)]
+  }, (0, _validate.isText)(description) ? /*#__PURE__*/_react().default.createElement(_reactNative().Text, {
+    style: [tokens.layout.description, {
+      color: tokens.colors.description,
+      fontSize: tokens.typography.description
+    }]
+  }, description) : /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.descriptionNode
+  }, description)) : null, /*#__PURE__*/_react().default.createElement(_reactNative().View, {
+    style: tokens.layout.actions
+  }, actions.map((action, index) => /*#__PURE__*/_react().default.createElement(ActionSheetItem, {
+    key: action.key ?? index,
+    action: action,
+    index: index,
+    tokens: tokens,
+    onPress: () => handleActionPress(action, index)
+  }))), children, hasCancelText ? /*#__PURE__*/_react().default.createElement(ActionSheetCancel, {
+    cancelText: cancelText,
+    tokens: tokens,
+    onPress: handleCancel
+  }) : null));
+};
+ActionSheet.displayName = 'ActionSheet';
+var _default = exports.default = ActionSheet;

package/dist/cjs/components/action-sheet/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+Object.defineProperty(exports, "useActionSheetTokens", {
+  enumerable: true,
+  get: function () {
+    return _tokens.useActionSheetTokens;
+  }
+});
+var _ActionSheet = _interopRequireDefault(require("./ActionSheet"));
+var _tokens = require("./tokens");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = _ActionSheet.default;

package/dist/cjs/components/action-sheet/tokens.js

@@ -0,0 +1,144 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useActionSheetTokens = exports.createActionSheetTokens = void 0;
+var _designSystem = require("../../design-system");
+const createActionSheetTokens = foundations => {
+  const {
+    palette,
+    spacing,
+    fontSize
+  } = foundations;
+  return {
+    defaults: {
+      closeOnClickAction: false,
+      closeable: true,
+      round: true,
+      safeAreaInsetBottom: true,
+      overlay: true,
+      lockScroll: true
+    },
+    layout: {
+      popup: {
+        paddingLeft: 0,
+        paddingRight: 0,
+        paddingBottom: 0
+      },
+      panel: {
+        width: '100%',
+        maxHeight: '80%'
+      },
+      header: {
+        position: 'relative',
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'center',
+        paddingHorizontal: 16
+      },
+      titleContainer: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center'
+      },
+      title: {
+        fontWeight: '600',
+        textAlign: 'center'
+      },
+      titleNode: {
+        alignItems: 'center',
+        justifyContent: 'center'
+      },
+      closeButton: {
+        position: 'absolute',
+        top: 0,
+        right: 0,
+        width: 48,
+        height: 48,
+        alignItems: 'center',
+        justifyContent: 'center'
+      },
+      descriptionContainer: {
+        paddingTop: 12,
+        paddingBottom: 20,
+        paddingHorizontal: 16
+      },
+      description: {
+        textAlign: 'center',
+        lineHeight: 20
+      },
+      descriptionNode: {
+        alignItems: 'center',
+        justifyContent: 'center'
+      },
+      actions: {
+        width: '100%'
+      },
+      item: {
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: '100%'
+      },
+      itemWithIcon: {
+        flexDirection: 'row',
+        justifyContent: 'center'
+      },
+      itemTextWrapper: {
+        alignItems: 'center',
+        justifyContent: 'center'
+      },
+      itemText: {
+        lineHeight: 24
+      },
+      subname: {
+        marginTop: 4,
+        fontSize: 12,
+        lineHeight: 18
+      },
+      subnameNode: {
+        marginTop: 4
+      },
+      icon: {
+        marginRight: 12
+      },
+      cancelGap: {
+        width: '100%',
+        marginBottom: 0
+      },
+      cancel: {
+        alignItems: 'center',
+        justifyContent: 'center'
+      },
+      cancelText: {
+        lineHeight: 24
+      }
+    },
+    colors: {
+      background: '#ffffff',
+      title: palette.default[900],
+      description: palette.default[500],
+      item: palette.default[900],
+      subitem: palette.default[500],
+      cancel: palette.default[900],
+      disabled: palette.default[400],
+      border: palette.default[200],
+      itemBackground: '#ffffff',
+      itemPressedBackground: palette.default[100],
+      cancelBackground: '#ffffff',
+      cancelGapBackground: palette.default[100] ?? '#f1f2f5'
+    },
+    typography: {
+      title: fontSize.lg,
+      item: fontSize.md,
+      description: fontSize.sm
+    },
+    spacing: {
+      horizontal: spacing.md,
+      vertical: 14,
+      cancelGap: 8
+    }
+  };
+};
+exports.createActionSheetTokens = createActionSheetTokens;
+const useActionSheetTokens = exports.useActionSheetTokens = (0, _designSystem.createComponentTokensHook)('actionSheet', createActionSheetTokens);

package/dist/cjs/components/action-sheet/types.d.ts

@@ -0,0 +1,96 @@
+import type * as React from 'react'
+import type { StyleProp, TextStyle, ViewStyle } from 'react-native'
+
+import type { DeepPartial } from '../../types'
+import type { PopupProps } from '../popup/Popup'
+
+export type ActionSheetCloseAction = 'action' | 'cancel' | 'close' | 'close-icon' | 'overlay'
+
+export interface ActionSheetAction {
+  key?: React.Key
+  name?: React.ReactNode
+  subname?: React.ReactNode
+  color?: string
+  disabled?: boolean
+  loading?: boolean
+  icon?: React.ReactNode
+  style?: StyleProp<ViewStyle>
+  onPress?: (action: ActionSheetAction) => void
+  /** 对齐 Vant：callback */
+  callback?: (action: ActionSheetAction) => void
+}
+
+export interface ActionSheetTokens {
+  defaults: {
+    closeOnClickAction: boolean
+    closeable: boolean
+    round: boolean
+    safeAreaInsetBottom: boolean
+    overlay: boolean
+    lockScroll: boolean
+  }
+  layout: {
+    popup: ViewStyle
+    panel: ViewStyle
+    header: ViewStyle
+    titleContainer: ViewStyle
+    title: TextStyle
+    titleNode: ViewStyle
+    closeButton: ViewStyle
+    descriptionContainer: ViewStyle
+    description: TextStyle
+    descriptionNode: ViewStyle
+    actions: ViewStyle
+    item: ViewStyle
+    itemWithIcon: ViewStyle
+    itemTextWrapper: ViewStyle
+    itemText: TextStyle
+    subname: TextStyle
+    subnameNode: ViewStyle
+    icon: ViewStyle
+    cancelGap: ViewStyle
+    cancel: ViewStyle
+    cancelText: TextStyle
+  }
+  colors: {
+    background: string
+    title: string
+    description: string
+    item: string
+    subitem: string
+    cancel: string
+    disabled: string
+    border: string
+    itemBackground: string
+    itemPressedBackground: string
+    cancelBackground: string
+    cancelGapBackground: string
+  }
+  typography: {
+    title: number
+    item: number
+    description: number
+  }
+  spacing: {
+    horizontal: number
+    vertical: number
+    cancelGap: number
+  }
+}
+
+export interface ActionSheetProps extends Omit<PopupProps, 'children'> {
+  title?: React.ReactNode
+  description?: React.ReactNode
+  cancelText?: React.ReactNode
+  actions?: ActionSheetAction[]
+  /** 是否在点击选项后自动关闭（对齐 Vant：close-on-click-action，默认 false） */
+  closeOnClickAction?: boolean
+  /** @deprecated 请使用 closeOnClickAction */
+  closeOnSelect?: boolean
+  children?: React.ReactNode
+  onSelect?: (action: ActionSheetAction, index: number) => void
+  onCancel?: () => void
+  /** 关闭前拦截，返回 false 可阻止关闭，支持 Promise */
+  beforeClose?: (action: ActionSheetCloseAction) => boolean | Promise<boolean>
+  tokensOverride?: DeepPartial<ActionSheetTokens>
+}