@beppla/tapas-ui 1.5.2 → 1.5.6

package/commonjs/CircularProgress/README.md

@@ -0,0 +1,70 @@
+# CircularProgress
+
+圆形进度条组件，用于显示任务进度、加载状态或完成百分比。基于 `react-native-circular-progress` 库封装，提供简洁的圆形进度展示，自动适配主题颜色。
+
+## 功能特性
+
+- ✅ 圆形进度条展示
+- ✅ 自定义尺寸（size）和线宽（width）
+- ✅ 自定义填充百分比（fill: 0-100）
+- ✅ 自定义进度色（tintColor）和背景色（backgroundColor）
+- ✅ 圆角端点（lineCap: round）
+- ✅ 可调起始角度（rotation）
+- ✅ 主题色自动适配（成功色 / 灰色背景）
+- ✅ React.memo 优化性能
+
+## 安装使用
+
+```tsx
+import { CircularProgress } from '@beppla/tapas-ui';
+```
+
+## Props
+
+继承 `react-native-circular-progress` 的 `CircularProgressProps`，额外属性如下：
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| size | `number` | - | 圆形直径（必填） |
+| fill | `number` | - | 填充百分比 0-100（必填） |
+| width | `number` | - | 进度线宽度（必填） |
+| backgroundColor | `string` | 主题 grey3 | 背景圆环颜色 |
+| tintColor | `string` | 主题 success 色 | 进度圆环颜色 |
+| rotation | `number` | `0` | 起始角度 |
+| lineCap | `string` | `'round'` | 端点样式 |
+| showFillText | `boolean` | - | 是否显示百分比文本（预留） |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<CircularProgress size={80} fill={75} width={8} />
+```
+
+### 自定义颜色
+
+```tsx
+<CircularProgress
+  size={100}
+  fill={60}
+  width={10}
+  tintColor="#F55523"
+  backgroundColor="#E0E0E0"
+/>
+```
+
+### 小尺寸
+
+```tsx
+<CircularProgress size={40} fill={100} width={4} />
+```
+
+## 注意事项
+
+- 依赖 `react-native-circular-progress` 库，请确保已安装
+- `fill` 值范围为 0-100，表示百分比
+- 默认 `backgroundColor` 使用主题 `grey3`，`tintColor` 使用主题 `success` 色
+- `showFillText` 属性已定义但尚未在渲染中实现
+- 需在 `ThemeProvider` 内使用

package/commonjs/Collapsible/README.md

@@ -0,0 +1,140 @@
+# Collapsible
+
+可折叠面板组件，点击标题行可展开或折叠内容区域。适用于 FAQ、设置面板、内容分组等场景。
+
+## 功能特性
+
+- 点击标题行切换展开/折叠状态
+- 支持初始状态控制（`initialOpen`）
+- 展开/折叠状态变化回调（`onToggle`）
+- 折叠时内容不渲染，优化性能
+- 展开/折叠图标指示器（`expand_less` / `expand_more`）
+- 可自定义标题样式和内容区域样式
+- 可自定义图标大小和颜色
+- 使用 `React.memo` 优化避免不必要的重渲染
+
+## 安装使用
+
+```tsx
+import { Collapsible } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | - | 面板标题文本（必填） |
+| children | `React.ReactNode` | - | 可折叠的内容区域 |
+| initialOpen | `boolean` | `false` | 初始是否展开 |
+| onToggle | `(isOpen: boolean) => void` | - | 展开/折叠状态变化回调 |
+| titleStyle | `any` | - | 标题文本自定义样式 |
+| contentStyle | `any` | - | 内容区域自定义样式 |
+| iconColor | `string` | `theme.colors.grey1` | 指示器图标颜色 |
+| iconSize | `number` | `18` | 指示器图标大小 |
+| testID | `string` | - | 测试 ID |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+import { Collapsible } from '@beppla/tapas-ui';
+import { Text } from 'react-native';
+
+<Collapsible title="Basic Panel">
+  <Text>This is the collapsible content.</Text>
+</Collapsible>
+```
+
+### 初始展开
+
+```tsx
+<Collapsible title="Initially Open" initialOpen={true}>
+  <Text>This panel starts in the open state.</Text>
+</Collapsible>
+```
+
+### 带状态回调
+
+```tsx
+<Collapsible
+  title="With Callback"
+  onToggle={(isOpen) => {
+    console.log('Panel is now', isOpen ? 'open' : 'closed');
+  }}
+>
+  <Text>Toggle me and check the console.</Text>
+</Collapsible>
+```
+
+### 多个面板组合
+
+```tsx
+import { Collapsible } from '@beppla/tapas-ui';
+import { View, Text } from 'react-native';
+
+<View style={{ gap: 8 }}>
+  <Collapsible title="Section 1" initialOpen={true}>
+    <Text>First section content</Text>
+  </Collapsible>
+  <Collapsible title="Section 2">
+    <Text>Second section content</Text>
+  </Collapsible>
+  <Collapsible title="Section 3">
+    <Text>Third section content</Text>
+  </Collapsible>
+</View>
+```
+
+### 自定义样式
+
+```tsx
+<Collapsible
+  title="Styled Panel"
+  titleStyle={{ fontSize: 18, fontWeight: 'bold', color: '#1976d2' }}
+  contentStyle={{ backgroundColor: '#f5f5f5', padding: 12, borderRadius: 4 }}
+  iconSize={24}
+  iconColor="#ff6b6b"
+>
+  <Text>Customized collapsible panel</Text>
+</Collapsible>
+```
+
+### FAQ 页面场景
+
+```tsx
+import { Collapsible } from '@beppla/tapas-ui';
+import { ScrollView, View, Text } from 'react-native';
+
+const faqs = [
+  { q: 'How to register?', a: 'Click the register button and fill in your details.' },
+  { q: 'How to reset password?', a: 'Click "Forgot Password" on the login page.' },
+  { q: 'How to contact support?', a: 'Use the chat button in the bottom right.' },
+];
+
+export default function FAQPage() {
+  return (
+    <ScrollView style={{ padding: 16 }}>
+      <Text style={{ fontSize: 20, fontWeight: 'bold', marginBottom: 16 }}>FAQ</Text>
+      <View style={{ gap: 8 }}>
+        {faqs.map((faq, i) => (
+          <Collapsible key={i} title={faq.q}>
+            <Text style={{ color: '#555', lineHeight: 20 }}>{faq.a}</Text>
+          </Collapsible>
+        ))}
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+## 注意事项
+
+- 标题点击区域包含整行（图标 + 标题文本），使用 `TouchableOpacity` 实现
+- `initialOpen` 仅在组件首次挂载时生效，后续状态由内部 `useState` 管理
+- 折叠状态下内容不渲染（条件渲染 `{isOpen && ...}`），有助于性能优化
+- 展开时图标为 `expand_less`（向上箭头），折叠时为 `expand_more`（向下箭头）
+- `iconColor` 未指定时默认使用主题的 `grey1` 颜色
+- `titleStyle` 会与默认样式合并（默认 fontSize: 16, fontWeight: '600'）
+- 内容区域默认左缩进 24px（`marginLeft: 24`），可通过 `contentStyle` 覆盖
+- 组件使用 `React.memo` 包装，仅在 props 变化时重新渲染

package/commonjs/ComboChart/README.md

@@ -0,0 +1,124 @@
+# ComboChart
+
+组合图表组件，支持在同一图表中混合展示柱状图和折线图。**仅支持 Web 平台**，基于 recharts 的 ComposedChart 实现。Native 端会显示提示信息，建议分别使用 BarChart 和 LineChart。
+
+## 功能特性
+
+- ✅ 柱状图和折线图混合展示
+- ✅ 支持多个柱状图系列和折线图系列
+- ✅ 支持双 Y 轴（left / right），展示不同量级数据
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ 网格线显示控制
+- ✅ X 轴标签旋转角度和显示间隔控制
+- ✅ Y 轴格式化函数
+- ✅ 折线图样式配置（线宽、数据点大小、隐藏数据点）
+- ✅ 响应式容器（ResponsiveContainer）
+- ✅ Tooltip 悬停提示
+- ✅ 空数据友好提示
+- ✅ **仅支持 Web 平台**（使用 recharts 库）
+
+## 安装使用
+
+```tsx
+import { ComboChart } from '@beppla/tapas-ui/components/ComboChart';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| categories | `string[]` | (必填) | X 轴分类标签数组 |
+| series | `ComboChartDataSeries[]` | (必填) | 数据系列数组 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | `350` | 图表高度 |
+| showGrid | `boolean` | `true` | 是否显示网格线 |
+| showLabels | `boolean` | `true` | 是否显示 X 轴标签 |
+| showLegend | `boolean` | `true` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 图例位置 |
+| xAxisAngle | `number` | `-45` | X 轴标签旋转角度（负数逆时针） |
+| xAxisInterval | `number \| 'preserveStartEnd' \| 'preserveStart' \| 'preserveEnd'` | `0` | X 轴标签显示间隔 |
+| yAxisFormat | `(value: number) => string` | `(value) => value.toString()` | Y 轴格式化函数 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### ComboChartDataSeries
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | `string` | 系列名称（必填），显示在图例中 |
+| data | `number[]` | 数据数组（必填），长度应与 categories 一致 |
+| type | `'bar' \| 'line'` | 图表类型（必填） |
+| color | `string` | 系列颜色 |
+| yAxisId | `'left' \| 'right'` | 绑定的 Y 轴，默认 left |
+| strokeWidth | `number` | 折线宽度（默认 2，仅 line 类型） |
+| dotRadius | `number` | 数据点半径（默认 4，仅 line 类型） |
+| activeDotRadius | `number` | 活动数据点半径（默认 6，仅 line 类型） |
+| hideDot | `boolean` | 隐藏数据点（仅 line 类型） |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<ComboChart
+  categories={['Store A', 'Store B', 'Store C', 'Store D', 'Store E']}
+  series={[
+    { name: 'Revenue', data: [58000, 73000, 68000, 48000, 80000], type: 'bar', color: '#FFB800' },
+    { name: 'Cost', data: [25000, 35000, 45000, 30000, 40000], type: 'line', color: '#E91E63' },
+  ]}
+  height={350}
+/>
+```
+
+### 多系列组合
+
+```tsx
+<ComboChart
+  categories={['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']}
+  series={[
+    { name: 'Revenue', data: [50000, 60000, 70000, 55000, 65000, 75000], type: 'bar', color: '#FF6B00' },
+    { name: 'Cost', data: [30000, 35000, 40000, 32000, 38000, 42000], type: 'bar', color: '#0066CC' },
+    { name: 'Profit', data: [20000, 25000, 30000, 23000, 27000, 33000], type: 'line', color: '#00B894' },
+    { name: 'Target', data: [22000, 24000, 28000, 25000, 29000, 35000], type: 'line', color: '#6C5CE7' },
+  ]}
+  height={400}
+/>
+```
+
+### 双 Y 轴
+
+```tsx
+<ComboChart
+  categories={['Q1', 'Q2', 'Q3', 'Q4']}
+  series={[
+    { name: 'Revenue', data: [150000, 180000, 210000, 240000], type: 'bar', color: '#FF6B00', yAxisId: 'left' },
+    { name: 'Growth (%)', data: [15, 20, 17, 14], type: 'line', color: '#0066CC', yAxisId: 'right' },
+  ]}
+  height={350}
+/>
+```
+
+### 长标签旋转 + Y 轴格式化
+
+```tsx
+<ComboChart
+  categories={['Store name A', 'Store name B', 'Store name C']}
+  series={[
+    { name: 'Revenue', data: [850000, 680000, 730000], type: 'bar', color: '#FFB800' },
+    { name: 'Cost', data: [15000, 12000, 18000], type: 'line', color: '#D63031', strokeWidth: 2, dotRadius: 4 },
+  ]}
+  xAxisAngle={-90}
+  yAxisFormat={(v) => v >= 1000 ? `${(v / 1000).toFixed(0)}k` : v.toString()}
+  height={500}
+/>
+```
+
+## 注意事项
+
+- **仅支持 Web 平台**，Native 端显示提示信息，建议在移动端分别使用 BarChart 和 LineChart
+- 依赖 `recharts` 库，需确保项目已安装
+- 设置 `yAxisId: 'right'` 的系列会自动启用右侧 Y 轴
+- 默认 X 轴标签旋转 -45 度以避免长标签重叠，`xAxisAngle` 为 0 时不旋转
+- 底部 margin 会根据 `xAxisAngle` 自动调整以避免标签被截断
+- 折线图样式属性（strokeWidth、dotRadius 等）使用 `??` 运算符设默认值，传 `0` 有效
+- 所有 series 的 data 数组长度应与 categories 数组长度一致

package/commonjs/DashboardCard/README.md

@@ -0,0 +1,120 @@
+# DashboardCard
+
+仪表板卡片组件，支持 Header / Content / Footer 三段式布局，适用于数据概览、功能模块入口等场景。
+
+## 功能特性
+
+- ✅ 三段式布局：Header（图标+标题+描述标签+操作区）、Content、Footer
+- ✅ 鼠标悬停阴影效果（Web 端 Hoverable 实现）
+- ✅ 支持禁用状态，自动调整所有文本和图标颜色
+- ✅ Header 支持自定义操作区域（React 节点），带独立点击事件
+- ✅ Header 支持多个描述标签数组
+- ✅ Footer 支持标题+描述+图标按钮
+- ✅ 整卡可点击，支持 onCardPress 回调
+- ✅ 标题单行截断，防止溢出
+- ✅ 高度自定义样式：cardContainerStyle / cardStyle / contentStyle / headerStyle / titleStyle
+
+## 安装使用
+
+```tsx
+import DashboardCard from '@beppla/tapas-ui/components/DashboardCard/DashboardCard';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| header | `{ icon?: string; title?: string; description?: string[]; action?: ReactNode; onPressAction?: (value: any) => void; actionStyle?: StyleProp<ViewStyle> }` | - | 头部配置 |
+| content | `string` | - | 内容区域文本 |
+| footer | `{ title?: string; description?: string; onPress?: () => void; icon?: string }` | - | 底部配置 |
+| onCardPress | `() => void` | - | 卡片点击回调 |
+| disabled | `boolean` | - | 是否禁用 |
+| testID | `string` | - | 测试标识 |
+| cardContainerStyle | `StyleProp<ViewStyle>` | - | 卡片外层容器样式（Hoverable 层） |
+| cardStyle | `StyleProp<ViewStyle>` | - | 卡片主体样式 |
+| contentStyle | `StyleProp<ViewStyle>` | - | 内容区域样式 |
+| headerStyle | `StyleProp<ViewStyle>` | - | 头部区域样式 |
+| titleStyle | `StyleProp<ViewStyle>` | - | 标题区域样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<DashboardCard
+  header={{
+    icon: 'restaurant_menu',
+    title: '订单管理',
+    description: ['今日订单', '待处理'],
+  }}
+  content="查看订单详情"
+  footer={{
+    title: '总计',
+    description: '128 单',
+    icon: 'back',
+    onPress: () => console.log('Footer pressed'),
+  }}
+  onCardPress={() => console.log('Card pressed')}
+/>
+```
+
+### 带操作按钮
+
+```tsx
+<DashboardCard
+  header={{
+    icon: 'dashboard',
+    title: '数据概览',
+    action: <Text>...</Text>,
+    onPressAction: (value) => console.log('Action:', value),
+  }}
+  footer={{
+    title: '更新时间',
+    description: '5 分钟前',
+  }}
+/>
+```
+
+### 禁用状态
+
+```tsx
+<DashboardCard
+  disabled
+  header={{
+    icon: 'lock',
+    title: '功能暂不可用',
+  }}
+  contentStyle={{ padding: 16 }}
+  cardStyle={{ width: 400 }}
+/>
+```
+
+### 自定义宽度和内容
+
+```tsx
+<DashboardCard
+  cardStyle={{ width: 400 }}
+  contentStyle={{ padding: 16 }}
+  header={{
+    icon: 'restaurant_menu',
+    title: '自定义宽度卡片',
+    description: ['标签1', '标签2'],
+  }}
+  content="自定义内容区域"
+  footer={{
+    title: '底部标题',
+    description: '底部描述',
+    icon: 'back',
+    onPress: () => console.log('Navigate'),
+  }}
+/>
+```
+
+## 注意事项
+
+- 禁用状态下 `onCardPress` 和 `footer.onPress` 均不会触发
+- `header.description` 为字符串数组，每项显示为独立标签，空值会被过滤
+- `footer.icon` 设置后才会渲染底部图标按钮（带旋转 180 度样式）
+- `content` 属性为 string 时自动渲染为 Text，也支持传入 ReactNode
+- 悬停效果在禁用状态下不会显示
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用

package/commonjs/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` 作为数据字段名