@beppla/tapas-ui 1.5.2 → 1.5.7

package/commonjs/DeviceSelectionModal/README.md

@@ -0,0 +1,124 @@
+# DeviceSelectionModal
+
+设备选择模态对话框组件，用于从设备列表中选择一个设备。支持加载状态、错误处理、重试机制和文本国际化，适合打印机选择、终端绑定等硬件设备关联场景。
+
+## 功能特性
+
+- ✅ 单选设备列表（Radio Button 样式）
+- ✅ 加载中状态展示（ActivityIndicator）
+- ✅ 错误状态展示 + 重试按钮
+- ✅ 空列表提示
+- ✅ 设备描述信息展示
+- ✅ 未选择时确认按钮自动禁用
+- ✅ 关闭时恢复原始选中状态
+- ✅ 全部文本支持国际化（i18n props）
+- ✅ 淡入淡出动画
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { DeviceSelectionModal } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| visible | `boolean` | - | 是否显示（必填） |
+| devices | `Device[]` | - | 设备列表（必填） |
+| selectedDeviceId | `string` | - | 当前选中的设备 ID |
+| onClose | `() => void` | - | 关闭回调（必填） |
+| onConfirm | `(deviceId: string) => void` | - | 确认选择回调（必填） |
+| title | `string` | - | 对话框标题 |
+| isLoading | `boolean` | `false` | 是否加载中 |
+| error | `string \| null` | `null` | 错误信息 |
+| onRetry | `() => void` | - | 重试按钮回调 |
+| selectDeviceText | `string` | `'Select Device'` | 标题文本 |
+| pleaseSelectDeviceText | `string` | `'Please select a device'` | 副标题文本 |
+| loadingDevicesText | `string` | `'Loading devices...'` | 加载中文本 |
+| noDevicesAvailableText | `string` | `'No devices available'` | 空列表文本 |
+| closeText | `string` | `'Close'` | 关闭按钮文本 |
+| confirmText | `string` | `'Confirm'` | 确认按钮文本 |
+| retryText | `string` | `'Retry'` | 重试按钮文本 |
+| testID | `string` | - | 测试标识 |
+
+### Device 接口
+
+```tsx
+interface Device {
+  id: string;
+  name: string;
+  description?: string;
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [visible, setVisible] = useState(false);
+const devices = [
+  { id: '1', name: 'Printer A', description: 'Kitchen printer' },
+  { id: '2', name: 'Printer B', description: 'Receipt printer' },
+];
+
+<DeviceSelectionModal
+  visible={visible}
+  devices={devices}
+  onClose={() => setVisible(false)}
+  onConfirm={(deviceId) => {
+    console.log('Selected:', deviceId);
+    setVisible(false);
+  }}
+/>
+```
+
+### 加载状态
+
+```tsx
+<DeviceSelectionModal
+  visible={true}
+  devices={[]}
+  isLoading={true}
+  onClose={() => setVisible(false)}
+  onConfirm={() => {}}
+/>
+```
+
+### 错误状态 + 重试
+
+```tsx
+<DeviceSelectionModal
+  visible={true}
+  devices={[]}
+  error="Failed to load devices"
+  onRetry={() => fetchDevices()}
+  onClose={() => setVisible(false)}
+  onConfirm={() => {}}
+/>
+```
+
+### 国际化
+
+```tsx
+<DeviceSelectionModal
+  visible={true}
+  devices={devices}
+  selectDeviceText="Select Printer"
+  pleaseSelectDeviceText="Choose a printer for this station"
+  confirmText="Bind"
+  closeText="Cancel"
+  onClose={() => setVisible(false)}
+  onConfirm={handleConfirm}
+/>
+```
+
+## 注意事项
+
+- 关闭对话框时会将内部选中状态恢复为 `selectedDeviceId`（即取消未确认的选择）
+- 未选中设备时确认按钮禁用（灰色样式）
+- 对话框最大宽度 400px，设备列表最大高度 300px
+- `title` 和 `selectDeviceText` 同时存在时，`title` 优先
+- 需在 `ThemeProvider` 内使用

package/commonjs/DraggableFlatList/README.md

@@ -0,0 +1,35 @@
+# DraggableFlatList
+
+可拖拽列表组件占位符。当前为空实现，预留用于后续开发支持拖拽排序的列表功能。
+
+## 功能特性
+
+- ✅ 组件骨架已搭建，导出可用
+- (待开发) 拖拽排序
+- (待开发) 拖拽动画
+- (待开发) 自定义渲染
+
+## 安装使用
+
+```tsx
+import { DraggableFlatList } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<DraggableFlatList testID="draggable-list" />
+```
+
+## 注意事项
+
+- 当前为空 View 占位实现，无实际拖拽功能
+- 后续计划集成 `react-native-draggable-flatlist` 或自定义实现

package/commonjs/Drawer/README.md

@@ -0,0 +1,175 @@
+# Drawer
+
+抽屉面板组件，从屏幕右侧滑出的浮层面板，支持自定义头部、内容区域和页脚，常用于筛选、详情展示等场景。
+
+## 功能特性
+
+- 从右侧滑出的 Overlay 抽屉面板
+- 响应式宽度（桌面端 55%，移动端 100%）
+- 可自定义标题、标题图标和状态标签（Status 组件）
+- 支持 showHeader / showFooter 控制头部和页脚显示
+- 支持自定义 headerComponent 和 footerComponent 完全替换
+- 点击背景遮罩自动关闭（onBackdropPress）
+- 内容区域自动 ScrollView 滚动
+- 移动端自动适配 Safe Area（useSafeAreaInsets）
+- 页脚包含左侧文本按钮和右侧主按钮
+
+## 安装使用
+
+```tsx
+import { Drawer } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| visible | `boolean` | `false` | 抽屉是否可见 |
+| title | `string` | - | 抽屉标题 |
+| titleIcon | `string` | - | 标题左侧图标名称 |
+| titleIconOnPress | `() => void` | - | 标题图标点击回调 |
+| titleStatus | `string` | - | 状态标签文本 |
+| statusType | `STATUS_TYPE` | `'unavailable'` | 状态类型（success/warning/unavailable 等） |
+| showHeader | `boolean` | `true` | 是否显示头部 |
+| showFooter | `boolean` | `false` | 是否显示页脚 |
+| onClose | `() => void` | - | 关闭回调（背景遮罩点击时触发） |
+| onClear | `() => void` | - | 清空按钮回调（未设时回退到 onClose） |
+| clearText | `string` | - | 清空按钮文本 |
+| clearDisable | `boolean` | `true` | 清空按钮是否禁用 |
+| overlayStyle | `StyleProp<ViewStyle>` | - | 抽屉覆盖层自定义样式 |
+| middleSectionStyle | `StyleProp<ViewStyle>` | - | 内容区域自定义样式 |
+| leftButtonText | `string` | - | 页脚左侧按钮文本 |
+| leftButtonTextStyle | `StyleProp<ViewStyle>` | - | 页脚左侧按钮文本样式 |
+| leftButtonOnPress | `() => void` | - | 页脚左侧按钮回调 |
+| rightButtonText | `string` | - | 页脚右侧按钮文本 |
+| rightButtonStyle | `StyleProp<ViewStyle>` | - | 页脚右侧按钮样式 |
+| rightButtonOnPress | `() => void` | - | 页脚右侧按钮回调 |
+| component | `React.ReactNode` | - | 内容组件（渲染在 children 之前） |
+| children | `React.ReactNode` | - | 内容子组件 |
+| headerComponent | `React.ReactNode` | - | 自定义头部组件（替换默认头部） |
+| footerComponent | `React.ReactNode` | - | 自定义页脚组件（额外渲染在 showFooter 之后） |
+| testID | `string` | - | 测试 ID |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+import { Drawer } from '@beppla/tapas-ui';
+import { useState } from 'react';
+import { Text, Button } from 'react-native';
+
+export default function App() {
+  const [visible, setVisible] = useState(false);
+
+  return (
+    <>
+      <Button title="Open Drawer" onPress={() => setVisible(true)} />
+      <Drawer
+        visible={visible}
+        title="Filters"
+        onClose={() => setVisible(false)}
+      >
+        <Text>Drawer content here</Text>
+      </Drawer>
+    </>
+  );
+}
+```
+
+### 带状态标签和图标
+
+```tsx
+<Drawer
+  visible={visible}
+  title="Order Details"
+  titleIcon="back"
+  titleIconOnPress={() => setVisible(false)}
+  titleStatus="Active"
+  statusType="success"
+  onClose={() => setVisible(false)}
+>
+  <Text>Order information</Text>
+</Drawer>
+```
+
+### 完整功能（头部 + 内容 + 页脚）
+
+```tsx
+<Drawer
+  visible={visible}
+  title="Filters"
+  titleIcon="back"
+  titleIconOnPress={() => setVisible(false)}
+  clearText="Clear"
+  clearDisable={false}
+  onClear={() => resetFilters()}
+  onClose={() => setVisible(false)}
+  showFooter={true}
+  leftButtonText="Close"
+  leftButtonOnPress={() => setVisible(false)}
+  rightButtonText="Show all results"
+  rightButtonOnPress={() => applyFilters()}
+>
+  <Text>Filter options here</Text>
+</Drawer>
+```
+
+### 自定义头部和页脚
+
+```tsx
+<Drawer
+  visible={visible}
+  headerComponent={
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between', padding: 16 }}>
+      <Text style={{ fontSize: 18, fontWeight: 'bold' }}>Custom Header</Text>
+      <Button title="X" onPress={() => setVisible(false)} />
+    </View>
+  }
+  footerComponent={
+    <View style={{ flexDirection: 'row', justifyContent: 'flex-end', gap: 8 }}>
+      <Button title="Cancel" onPress={() => setVisible(false)} />
+      <Button title="Save" onPress={() => handleSave()} />
+    </View>
+  }
+  onClose={() => setVisible(false)}
+>
+  <Text>Content with custom header and footer</Text>
+</Drawer>
+```
+
+### 通过 DrawerContext 使用
+
+```tsx
+import { useContext } from 'react';
+import { DrawerContext } from '@beppla/tapas-ui/components/Layout/DrawerContext';
+
+function MyComponent() {
+  const { open, close } = useContext(DrawerContext);
+
+  const showDrawer = () => {
+    open({
+      title: 'Dynamic Drawer',
+      component: <Text>Dynamic content</Text>,
+      showFooter: true,
+      rightButtonText: 'Confirm',
+      rightButtonOnPress: () => {
+        handleConfirm();
+        close();
+      },
+    });
+  };
+
+  return <Button title="Open" onPress={showDrawer} />;
+}
+```
+
+## 注意事项
+
+- 桌面端抽屉宽度为屏幕的 55%，移动端为 100%
+- `clearDisable` 默认为 `true`（禁用状态），需显式设为 `false` 才能启用清空按钮
+- `onClear` 未设置时，清空按钮会回退使用 `onClose` 回调
+- `showFooter` 默认为 `false`，需显式设为 `true` 以显示页脚按钮区域
+- `footerComponent` 独立于 `showFooter`，即使 `showFooter=false`，`footerComponent` 仍会渲染
+- 内容区域使用 ScrollView 包裹，`contentContainerStyle` 设置了 `flexGrow: 1`
+- 移动端会通过 `useSafeAreaInsets` 自动添加顶部安全区域间距

package/commonjs/Dropdown/Dropdown.js

@@ -235,6 +235,7 @@ const Dropdown = ({
   dropdownType = "clear",
   arrowIcon: _arrowIcon = false,
   onSelect,
+  attachSelect,
   backgroundColor,
   labelColor,
   state = "normal",
@@ -246,17 +247,34 @@ const Dropdown = ({
   extendBtnIcon,
   emptyText,
   onExtendBtnPress,
+  attachExtendBtn,
   noLabelAnim = false,
   radius = 12,
   modalVisible,
   customPopoverContent,
   setModalVisible,
+  visible,
+  setVisible,
+  dropdownSubWidth,
+  dropdownSubHeight,
+  empytText,
+  leftIcon,
+  marginTopOffset = 0,
+  height,
   iconStyle,
   label,
   required,
   testID,
   ...props
 }) => {
+  // 向下兼容：deprecated props 优先级低于新 props
+  const resolvedOnSelect = onSelect ?? attachSelect;
+  const resolvedOnExtendBtnPress = onExtendBtnPress ?? attachExtendBtn;
+  const resolvedModalVisible = modalVisible ?? visible;
+  const resolvedSetModalVisible = setModalVisible ?? setVisible;
+  const resolvedSubWidth = subWidth ?? dropdownSubWidth;
+  const resolvedSubHeight = subHeight ?? dropdownSubHeight;
+  const resolvedEmptyText = emptyText ?? empytText;
   const styles = useStyles(props);
   const theme = (0, _themed.useTheme)();
   const [selected_old, selectedItem] = _react.default.useState(value);
@@ -269,7 +287,7 @@ const Dropdown = ({
     top: 0,
     left: 0
   });
-  const [dropdownWidthCalc, setDropdownWidthCalc] = (0, _react.useState)(subWidth ?? 151);
+  const [dropdownWidthCalc, setDropdownWidthCalc] = (0, _react.useState)(resolvedSubWidth ?? 151);
   const [selectedItemKey, setSelectedItemKey] = (0, _react.useState)(selected ?? "");
   const [top, setTop] = (0, _react.useState)(18);
   const [optionListHeight, setOptionListHeight] = (0, _react.useState)(0);
@@ -286,17 +304,17 @@ const Dropdown = ({
     setSelectedItemKey(selected ?? "");
   }, [selected]);
   (0, _react.useEffect)(() => {
-    if (typeof modalVisible === "boolean" && modalVisible !== undefined) {
-      setInternalModalVisible(modalVisible);
+    if (typeof resolvedModalVisible === "boolean" && resolvedModalVisible !== undefined) {
+      setInternalModalVisible(resolvedModalVisible);
     }
-  }, [modalVisible]);
+  }, [resolvedModalVisible]);
 
   // 动态更新下拉容器宽度（支持运行时宽度变化）
   (0, _react.useEffect)(() => {
-    if (subWidth && internalModalVisible) {
-      setDropdownWidthCalc(subWidth);
+    if (resolvedSubWidth && internalModalVisible) {
+      setDropdownWidthCalc(resolvedSubWidth);
     }
-  }, [subWidth, internalModalVisible]);
+  }, [resolvedSubWidth, internalModalVisible]);
 
   // 标签动画效果
   (0, _react.useEffect)(() => {
@@ -326,8 +344,8 @@ const Dropdown = ({
     if (buttonRef.current) {
       buttonRef.current.measure((_fx, _fy, width, height, px, py) => {
         const window = _reactNative.Dimensions.get("window");
-        const dropdownHeight = subHeight ?? Math.min(40 * dropdownItems.length + 24, 224);
-        const dropdownWidth = Math.max(width, subWidth ?? 151);
+        const dropdownHeight = resolvedSubHeight ?? Math.min(40 * dropdownItems.length + 24, 224);
+        const dropdownWidth = Math.max(width, resolvedSubWidth ?? 151);
         setDropdownWidthCalc(dropdownWidth);
 
         // 计算显示位置
@@ -341,8 +359,8 @@ const Dropdown = ({
           top,
           left
         });
-        if (setModalVisible) {
-          setModalVisible(true);
+        if (resolvedSetModalVisible) {
+          resolvedSetModalVisible(true);
         } else {
           setInternalModalVisible(true);
         }
@@ -350,8 +368,8 @@ const Dropdown = ({
     }
   };
   const closeModal = () => {
-    if (setModalVisible) {
-      setModalVisible(false);
+    if (resolvedSetModalVisible) {
+      resolvedSetModalVisible(false);
     } else {
       setInternalModalVisible(false);
     }
@@ -369,8 +387,10 @@ const Dropdown = ({
       style: [styles.modalContainer, width ? {
         width: width
       } : null, {
-        minHeight: 40 + (label ? 7 : 0) + (showStateMsg ? 15 : 0)
-      }],
+        minHeight: (height || 40) + (label ? 7 : 0) + (showStateMsg ? 15 : 0)
+      }, height ? {
+        maxHeight: height + (label ? 7 : 0) + (showStateMsg ? 15 : 0)
+      } : null],
       children: [label && !noLabelAnim && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Animated.View, {
         style: [styles.labelCon, {
           top: topAnim
@@ -402,22 +422,32 @@ const Dropdown = ({
           borderRadius: radius
         } : null,
         // 统一主体容器的位置，无论是否使用 customPopoverContent
-        label && !noLabelAnim ? {
-          marginTop: 7
+        label ? {
+          marginTop: 7 + marginTopOffset
         } : null, noLabelAnim && label && backgroundColor ? {
           backgroundColor
         } : null, state === "error" ? {
           borderColor: theme.theme.colors.error
         } : null, props.disabled ? {
           borderColor: theme.theme.colors.grey3
-        } : null,
+        } : null, leftIcon && {
+          gap: 8,
+          paddingLeft: 8,
+          paddingRight: 12
+        },
         // 确保主体容器始终有统一的垂直对齐
         {
           alignItems: "center"
         }],
         disabled: props.disabled,
         onPress: openDropdown,
-        children: [showSelectedValue ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        children: [leftIcon && /*#__PURE__*/(0, _jsxRuntime.jsx)(_TapasIcon.default, {
+          size: 20,
+          style: [styles.alignCenter, styles.modalIcon, props.disabled && {
+            color: theme.theme.colors.grey3
+          }],
+          name: leftIcon
+        }), showSelectedValue ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
           style: [styles.alignCenter, {
             flexGrow: 1,
             marginRight: 12
@@ -471,8 +501,8 @@ const Dropdown = ({
               top: dropdownPosition.top,
               left: dropdownPosition.left,
               width: dropdownWidthCalc
-            }, subHeight ? {
-              maxHeight: subHeight
+            }, resolvedSubHeight ? {
+              maxHeight: resolvedSubHeight
             } : null],
             onLayout: handleConLayout,
             children: customPopoverContent ? customPopoverContent : /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
@@ -506,8 +536,8 @@ const Dropdown = ({
                   } : null],
                   onPress: () => {
                     closeModal();
-                    if (onSelect) {
-                      onSelect(item);
+                    if (resolvedOnSelect) {
+                      resolvedOnSelect(item);
                     } else {
                       setSelectedItemKey(item.key);
                     }
@@ -553,7 +583,7 @@ const Dropdown = ({
                   numberOfLines: 1,
                   ellipsizeMode: "tail",
                   style: [styles.modalOptionText, styles.modalNoOptions],
-                  children: emptyText || "No options"
+                  children: resolvedEmptyText || "No options"
                 })
               })
             })
@@ -561,7 +591,7 @@ const Dropdown = ({
             onPress: () => {
               closeModal();
               setTimeout(() => {
-                onExtendBtnPress?.();
+                resolvedOnExtendBtnPress?.();
               }, 300);
             },
             style: [styles.extendBtnCon, {
@@ -590,8 +620,8 @@ const Dropdown = ({
     value: `${prefix}${selected_old?.name}`,
     isVisible: isVisible,
     width: width,
-    subWidth: subWidth,
-    subHeight: subHeight,
+    subWidth: resolvedSubWidth,
+    subHeight: resolvedSubHeight,
     testID: testID,
     ...props,
     onClose: () => {
@@ -615,7 +645,7 @@ const Dropdown = ({
           borderEndWidth: 1,
           borderTopWidth: 0,
           borderRightWidth: 0,
-          width: subWidth
+          width: resolvedSubWidth
         },
         inputContainerStyle: styles.inputContainer,
         placeholder: props.placeholder,
@@ -645,8 +675,8 @@ const Dropdown = ({
       })
     }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
       style: {
-        width: subWidth,
-        height: subHeight
+        width: resolvedSubWidth,
+        height: resolvedSubHeight
       },
       keyboardShouldPersistTaps: "handled",
       keyboardDismissMode: "none",