@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/DataTable/README.md

@@ -0,0 +1,159 @@
+# DataTable 数据表格组件
+
+简洁高效的数据表格组件，用于展示和管理结构化数据。支持列排序、分页、自定义单元格渲染和行点击事件，适合后台管理、报表展示等场景。
+
+## 功能特性
+
+- ✅ 声明式列定义（columns 配置）
+- ✅ 列排序功能（sortable），升序/降序切换
+- ✅ 内置分页组件集成（Pagination）
+- ✅ 自定义单元格渲染（column.render）
+- ✅ 行点击事件（onRow）
+- ✅ 列对齐配置（left / center / right）
+- ✅ 列宽自定义
+- ✅ 加载中和空数据状态
+- ✅ 水平滚动支持（ScrollView）
+- ✅ 最大高度限制（maxHeight）
+- ✅ 跨平台（Web + React Native）
+
+## 安装使用
+
+```tsx
+import { DataTable } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| columns | `DataTableColumn<T>[]` | - | 列定义数组（必填） |
+| dataSource | `T[]` | - | 数据源（必填） |
+| rowKey | `string \| ((record: T) => string \| number)` | `'id'` | 行唯一标识字段或函数 |
+| loading | `boolean` | `false` | 是否显示加载状态 |
+| pagination | `PaginationConfig \| false` | - | 分页配置，false 禁用 |
+| onRow | `(record: T, index: number) => { onPress?: () => void }` | - | 行事件配置 |
+| emptyText | `string` | `'No data'` | 空数据提示文本 |
+| style | `any` | - | 容器样式 |
+| headerStyle | `any` | - | 表头行样式 |
+| rowStyle | `any` | - | 数据行样式 |
+| maxHeight | `number` | - | 表格最大高度 |
+
+### DataTableColumn
+
+```tsx
+interface DataTableColumn<T = any> {
+  key: string;           // 列唯一标识（必填）
+  title: string;         // 列标题（必填）
+  dataIndex?: string;    // 数据字段名（默认为 key）
+  width?: number;        // 列宽（默认 150）
+  align?: 'left' | 'center' | 'right';  // 对齐方式
+  sortable?: boolean;    // 是否可排序
+  render?: (text: any, record: T, index: number) => React.ReactNode;  // 自定义渲染
+  fixed?: 'left' | 'right';  // 固定列（预留）
+}
+```
+
+### PaginationConfig
+
+```tsx
+interface PaginationConfig {
+  current: number;       // 当前页码
+  pageSize: number;      // 每页条数
+  total: number;         // 总数
+  onChange?: (page: number, pageSize: number) => void;  // 页码变化回调
+}
+```
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const columns = [
+  { key: 'name', title: 'Name', width: 200, sortable: true },
+  { key: 'age', title: 'Age', width: 100, align: 'center' as const },
+  { key: 'email', title: 'Email', width: 250 },
+];
+
+const dataSource = [
+  { id: 1, name: 'Alice', age: 28, email: 'alice@example.com' },
+  { id: 2, name: 'Bob', age: 32, email: 'bob@example.com' },
+];
+
+<DataTable columns={columns} dataSource={dataSource} />
+```
+
+### 自定义渲染 + 排序
+
+```tsx
+const columns = [
+  { key: 'name', title: 'Name', width: 200, sortable: true },
+  {
+    key: 'status',
+    title: 'Status',
+    width: 120,
+    render: (text: string) => (
+      <View style={{ flexDirection: 'row', alignItems: 'center' }}>
+        <View style={{
+          width: 8, height: 8, borderRadius: 4,
+          backgroundColor: text === 'active' ? '#57B07B' : '#B81F1E',
+          marginRight: 8,
+        }} />
+        <Text>{text}</Text>
+      </View>
+    ),
+  },
+];
+
+<DataTable columns={columns} dataSource={data} />
+```
+
+### 分页
+
+```tsx
+<DataTable
+  columns={columns}
+  dataSource={pageData}
+  pagination={{
+    current: page,
+    pageSize: 10,
+    total: 100,
+    onChange: (newPage, newPageSize) => {
+      setPage(newPage);
+      fetchData(newPage, newPageSize);
+    },
+  }}
+/>
+```
+
+### 行点击
+
+```tsx
+<DataTable
+  columns={columns}
+  dataSource={data}
+  onRow={(record) => ({
+    onPress: () => navigation.navigate('Detail', { id: record.id }),
+  })}
+/>
+```
+
+### 限制高度
+
+```tsx
+<DataTable
+  columns={columns}
+  dataSource={longList}
+  maxHeight={400}
+/>
+```
+
+## 注意事项
+
+- 排序为前端排序（内存排序），大数据量建议后端排序
+- `pagination` 设为 `false` 可完全禁用分页
+- 列宽默认 150px，未设置 `width` 的列统一使用此默认值
+- 排序图标使用箭头字符（ ↑ / ↓）
+- Web 端显示水平滚动条，移动端隐藏
+- `maxHeight` 会同时限制表体高度（maxHeight - 50）
+- `dataIndex` 缺省时自动使用 `key` 作为数据字段名

package/package/module/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/package/module/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/package/module/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/package/module/Drawer/SCROLLVIEW_FIX.md

@@ -0,0 +1,127 @@
+# Drawer ScrollView 布局修复
+
+## 问题描述
+
+之前 Drawer 组件的 ScrollView 在某些情况下，内容高度不足时无法填充整个可用空间，导致布局不理想。
+
+## 解决方案
+
+### 修改内容
+
+为 ScrollView 添加 `contentContainerStyle`，使用 `flexGrow: 1` 确保内容容器能够填充整个 ScrollView。
+
+```typescript
+<ScrollView 
+  style={[styles.middleSection, middleSectionStyle]}
+  contentContainerStyle={styles.containerStyle}  // ✨ 新增
+>
+  {component}
+  {children}
+</ScrollView>
+```
+
+### 样式定义
+
+```typescript
+containerStyle: {
+  flexGrow: 1,  // 让内容容器至少填充整个 ScrollView
+}
+```
+
+## 技术说明
+
+### `flex: 1` vs `flexGrow: 1`
+
+在 ScrollView 的 `contentContainerStyle` 中：
+
+- ❌ **不要使用 `flex: 1`**
+  - `flex: 1` 是 `flex-grow: 1`, `flex-shrink: 1`, `flex-basis: 0` 的简写
+  - 会让内容容器强制占据固定高度，可能破坏滚动行为
+  - 在内容超出时会导致布局问题
+
+- ✅ **使用 `flexGrow: 1`**
+  - 允许内容容器增长以填充可用空间
+  - 当内容少时，容器会扩展填充 ScrollView
+  - 当内容多时，容器自然增长，保持滚动功能正常
+  - 不会影响 `flex-shrink` 和 `flex-basis` 的默认行为
+
+### ScrollView 的两个样式属性
+
+```typescript
+// 外层容器样式（ScrollView 本身）
+style={{
+  flex: 1,           // ✅ 正确：让 ScrollView 占满可用空间
+  paddingHorizontal: 16,
+}}
+
+// 内层内容容器样式（包裹 children）
+contentContainerStyle={{
+  flexGrow: 1,       // ✅ 正确：让内容至少填充 ScrollView
+  paddingBottom: 20, // 内容的 padding
+}}
+```
+
+## 使用场景
+
+这个修复特别适用于：
+
+1. **内容较少时**: 确保内容垂直居中或填充整个抽屉
+2. **动态内容**: 内容高度可能变化的场景
+3. **表单布局**: 需要底部按钮始终在底部的情况
+4. **空状态**: 显示空状态提示时保持良好布局
+
+## 示例
+
+### 修复前
+
+```typescript
+// 内容少时，ScrollView 内容不填充，底部有空白
+<Drawer visible={true}>
+  <Text>少量内容</Text>
+</Drawer>
+```
+
+### 修复后
+
+```typescript
+// 内容少时，ScrollView 内容填充整个可用空间
+<Drawer visible={true}>
+  <Text>少量内容</Text>
+  {/* 内容会填充整个抽屉高度 */}
+</Drawer>
+```
+
+## React Native ScrollView 官方文档
+
+根据 React Native 官方文档：
+
+> `contentContainerStyle`: These styles will be applied to the scroll view content container which wraps all of the child views.
+
+推荐使用：
+- `flexGrow: 1` - 让内容至少填充容器
+- `paddingBottom` - 内容底部间距
+- `alignItems` - 内容对齐方式
+
+## 注意事项
+
+1. **不要在 contentContainerStyle 中使用 `flex: 1`**
+   - 会导致滚动行为异常
+   - 在 Web 上可能引起布局问题
+
+2. **保持 style 中的 `flex: 1`**
+   - ScrollView 本身需要 `flex: 1` 来占据可用空间
+   - 这是在 `middleSection` 样式中定义的
+
+3. **Web 平台兼容性**
+   - 使用 `flexGrow: 1` 在 Web 和原生平台都能正常工作
+   - 确保跨平台一致性
+
+## 相关资源
+
+- [React Native ScrollView 文档](https://reactnative.dev/docs/scrollview)
+- [Flexbox 布局指南](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)
+- [React Native 布局最佳实践](https://reactnative.dev/docs/flexbox)
+
+## 版本历史
+
+- **v1.4.18**: 修复 ScrollView 内容容器布局，使用 `flexGrow: 1`