@beppla/tapas-ui 1.5.10 → 1.5.11

package/package/module/SheetTitle/README.md

@@ -0,0 +1,89 @@
+# SheetTitle
+
+底部 Sheet 标题栏组件，用于底部弹窗或模态框的顶部区域。包含标题文本、关闭按钮和可选的清空按钮，适合筛选面板、选择器等场景的标题栏。
+
+## 功能特性
+
+- ✅ 标题文本展示，超长自动截断
+- ✅ 关闭按钮（默认显示，可隐藏）
+- ✅ 可选清空按钮（showClear）
+- ✅ 自定义关闭图标（字符串图标名或 ReactNode）
+- ✅ 自定义清空按钮文本
+- ✅ 底部分割线
+- ✅ 全面的样式自定义（标题栏、标题文本、清空按钮、关闭按钮）
+- ✅ React.memo 优化性能
+
+## 安装使用
+
+```tsx
+import { SheetTitle } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | - | 标题文本 |
+| icon | `React.ReactNode \| string` | `'close'` | 关闭按钮图标 |
+| showClear | `Boolean` | - | 是否显示清空按钮 |
+| showClose | `Boolean` | `true` | 是否显示关闭按钮 |
+| clearText | `string` | `'Clear'` | 清空按钮文本 |
+| onClear | `() => void` | - | 清空按钮回调 |
+| onClose | `() => void` | - | 关闭按钮回调 |
+| titleContainerStyle | `StyleProp<ViewStyle>` | - | 标题栏容器样式 |
+| titleStyle | `StyleProp<ViewStyle>` | - | 标题文本样式 |
+| clearStyle | `StyleProp<ViewStyle>` | - | 清空按钮样式 |
+| closeStyle | `StyleProp<ViewStyle>` | - | 关闭按钮样式 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<SheetTitle
+  title="Filter Options"
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 带清空按钮
+
+```tsx
+<SheetTitle
+  title="Select Category"
+  showClear
+  clearText="Reset"
+  onClear={() => handleReset()}
+  onClose={() => setVisible(false)}
+/>
+```
+
+### 自定义图标
+
+```tsx
+<SheetTitle
+  title="Settings"
+  icon="arrow_back"
+  onClose={() => navigation.goBack()}
+/>
+```
+
+### 自定义 ReactNode 图标
+
+```tsx
+<SheetTitle
+  title="Details"
+  icon={<CustomCloseIcon />}
+  onClose={() => setVisible(false)}
+/>
+```
+
+## 注意事项
+
+- 标题栏固定高度 40px，宽度 100%
+- 标题文本使用 `flex: 1` 自动撑满可用空间，超长文本截断
+- `icon` 为字符串时渲染 TapasIcon，为 ReactNode 时直接渲染
+- 清空按钮使用 Button 组件的 clear 类型
+- 底部有 1px 分割线（borderBottomColor: greyOutline）
+- 需在 `ThemeProvider` 内使用

package/package/module/Shell/README.md

@@ -0,0 +1,152 @@
+# Shell
+
+外壳布局组件，提供主内容区域和侧边抽屉的两栏布局，使用复合组件模式（Shell.Main + Shell.Drawer），抽屉支持弹簧动画展开/折叠。
+
+## 功能特性
+
+- 两栏布局：主内容区（Shell.Main）+ 侧边抽屉（Shell.Drawer）
+- 复合组件模式，声明式使用 Shell.Main 和 Shell.Drawer
+- 抽屉展开/折叠使用 `Animated.spring` 弹簧动画
+- 可自定义抽屉宽度（默认 150px）
+- 可选的顶部和左侧边框线
+- 支持受控模式（`openDrawer` 属性）
+- 支持自定义容器样式
+
+## 安装使用
+
+```tsx
+import { Shell } from '@beppla/tapas-ui';
+```
+
+## Props
+
+### Shell
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 必须包含 Shell.Main 和 Shell.Drawer 子组件 |
+| openDrawer | `boolean` | `false` | 抽屉是否展开 |
+| drawerWidth | `number` | `150` | 抽屉展开时的宽度（像素） |
+| border | `boolean` | `true` | 是否显示边框线（顶部和左侧） |
+| style | `any` | - | 容器自定义样式 |
+| testID | `string` | - | 测试 ID |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### Shell.Main
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 主内容区域 |
+| style | `any` | - | 自定义样式 |
+| theme | `any` | - | 主题对象（自动注入） |
+
+### Shell.Drawer
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| children | `React.ReactNode` | - | 侧边抽屉内容 |
+| style | `any` | - | 自定义样式 |
+| theme | `any` | - | 主题对象（自动注入） |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+import Shell from '@beppla/tapas-ui/components/Shell/Shell';
+import { useState } from 'react';
+import { View, Text, Button } from 'react-native';
+
+export default function App() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Shell openDrawer={open}>
+      <Shell.Main>
+        <View style={{ padding: 16 }}>
+          <Text>Main Content</Text>
+          <Button title="Toggle Drawer" onPress={() => setOpen(!open)} />
+        </View>
+      </Shell.Main>
+      <Shell.Drawer>
+        <View style={{ padding: 16 }}>
+          <Text>Drawer Content</Text>
+        </View>
+      </Shell.Drawer>
+    </Shell>
+  );
+}
+```
+
+### 自定义抽屉宽度
+
+```tsx
+<Shell openDrawer={open} drawerWidth={280}>
+  <Shell.Main>
+    <Text>Main content with wider drawer</Text>
+  </Shell.Main>
+  <Shell.Drawer>
+    <Text>280px wide drawer</Text>
+  </Shell.Drawer>
+</Shell>
+```
+
+### 无边框模式
+
+```tsx
+<Shell openDrawer={open} border={false} drawerWidth={200}>
+  <Shell.Main>
+    <Text>No border content</Text>
+  </Shell.Main>
+  <Shell.Drawer>
+    <Text>No border drawer</Text>
+  </Shell.Drawer>
+</Shell>
+```
+
+### POS 订单详情场景
+
+```tsx
+import Shell from '@beppla/tapas-ui/components/Shell/Shell';
+import { useState } from 'react';
+import { View, Text, ScrollView } from 'react-native';
+
+export default function OrderPage() {
+  const [showDetail, setShowDetail] = useState(false);
+
+  return (
+    <View style={{ height: 600 }}>
+      <Shell openDrawer={showDetail} drawerWidth={320}>
+        <Shell.Main>
+          <ScrollView style={{ padding: 16 }}>
+            <Text>Order List</Text>
+            <Button
+              title="View Details"
+              onPress={() => setShowDetail(true)}
+            />
+          </ScrollView>
+        </Shell.Main>
+        <Shell.Drawer>
+          <View style={{ padding: 16 }}>
+            <Text>Order #12345 Details</Text>
+            <Button
+              title="Close"
+              onPress={() => setShowDetail(false)}
+            />
+          </View>
+        </Shell.Drawer>
+      </Shell>
+    </View>
+  );
+}
+```
+
+## 注意事项
+
+- Shell 必须包含 `Shell.Main` 和 `Shell.Drawer` 作为直接子组件，组件通过 `React.Children.forEach` 匹配子组件类型
+- 抽屉动画使用 `Animated.spring`（tension: 300, friction: 20），关闭时宽度动画至 0
+- `openDrawer` 为受控属性，外部状态变化会触发动画
+- 默认抽屉宽度为 150px（`defaultDrawerWidth` 常量）
+- `border=true` 时，主内容区顶部有边框线，抽屉区顶部和左侧有边框线
+- 边框颜色使用主题的 `greyOutline` 色值，默认为 `rgba(0, 0, 0, 0.12)`
+- `ShellPorps` 为已废弃的拼写错误别名，请使用 `ShellProps`

package/package/module/StatisticCard/README.md

@@ -0,0 +1,129 @@
+# StatisticCard
+
+统计卡片组件，用于展示关键指标和数据，支持趋势指示、前缀/后缀、图标等功能。适用于仪表板、数据大屏和统计报表。
+
+## 功能特性
+
+- ✅ 数值展示，支持前缀（如 $）和后缀（如 %）
+- ✅ 趋势指示器：正向增长绿色（#00B894）、负向下降红色（#D63031）
+- ✅ 趋势百分比自动格式化（1 位小数，带 +/- 符号）
+- ✅ 支持自定义图标（React 节点，显示在右上角）
+- ✅ 支持描述文本
+- ✅ 加载状态（loading），显示 "Loading..." 替代数值
+- ✅ 可点击交互：有 onPress 时自动切换为 TouchableOpacity
+- ✅ 自定义数值颜色
+- ✅ 基于 Card 组件封装，最小高度 120px
+
+## 安装使用
+
+```tsx
+import { StatisticCard } from '@beppla/tapas-ui/components/StatisticCard';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | (必填) | 指标标题 |
+| value | `string \| number` | (必填) | 指标数值 |
+| prefix | `string` | `''` | 数值前缀（如 $、EUR） |
+| suffix | `string` | `''` | 数值后缀（如 %、单） |
+| trend | `{ value: number; isPositive?: boolean }` | - | 趋势数据 |
+| description | `string` | - | 描述文本 |
+| icon | `React.ReactNode` | - | 右上角图标（任意 React 节点） |
+| color | `string` | `'#FF6B00'` | 数值颜色 |
+| onPress | `() => void` | - | 点击回调 |
+| loading | `boolean` | `false` | 是否加载中 |
+| style | `any` | - | 自定义样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<StatisticCard title="Total Sales" value="1,234" />
+```
+
+### 带前缀和后缀
+
+```tsx
+<StatisticCard title="Revenue" value="12,345" prefix="$" />
+<StatisticCard title="Growth Rate" value="15.8" suffix="%" />
+```
+
+### 带趋势指示
+
+```tsx
+<StatisticCard
+  title="Monthly Revenue"
+  value="45,678"
+  prefix="$"
+  trend={{ value: 12.5, isPositive: true }}
+  description="Compared to last month"
+/>
+
+<StatisticCard
+  title="Error Rate"
+  value="2.3"
+  suffix="%"
+  trend={{ value: 5.2, isPositive: false }}
+  description="Compared to last week"
+  color="#D63031"
+/>
+```
+
+### 带图标
+
+```tsx
+import TapasIcon from '@beppla/tapas-ui/components/Icons/TapasIcon';
+
+<StatisticCard
+  title="Total Orders"
+  value="8,456"
+  icon={<TapasIcon name="shopping_cart" size={24} color="#FF6B00" />}
+  trend={{ value: 8.3, isPositive: true }}
+/>
+```
+
+### 仪表板组合
+
+```tsx
+<View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 16 }}>
+  <StatisticCard
+    title="Total Revenue"
+    value="123,456"
+    prefix="$"
+    trend={{ value: 15.3, isPositive: true }}
+    description="Last 30 days"
+    color="#FF6B00"
+  />
+  <StatisticCard
+    title="New Users"
+    value="1,234"
+    trend={{ value: 8.2, isPositive: true }}
+    color="#0066CC"
+  />
+  <StatisticCard
+    title="Conversion Rate"
+    value="3.45"
+    suffix="%"
+    trend={{ value: 2.1, isPositive: false }}
+    color="#00B894"
+  />
+</View>
+```
+
+### 加载中
+
+```tsx
+<StatisticCard title="Loading Data" value="0" loading />
+```
+
+## 注意事项
+
+- `title` 和 `value` 为必填属性
+- `trend.isPositive` 默认为 `true`（不传或传 `undefined` 时视为正向）
+- 趋势值显示精度为小数点后 1 位（`toFixed(1)`）
+- 加载状态显示 "Loading..." 文本，不渲染数值和趋势
+- 有 `onPress` 时容器变为 TouchableOpacity（activeOpacity=0.7），无 `onPress` 时为 View
+- 默认数值颜色为橙色（#FF6B00），可通过 `color` 自定义

package/package/module/StatisticsTable/PLACEHOLDER_FEATURE.md

@@ -0,0 +1,287 @@
+# StatisticsTable 占位功能说明
+
+## 概述
+
+为 StatisticsTable 组件添加了占位行和列的功能，当数据不足以撑满外层容器时，会自动添加占位行和列来填充空间。
+
+## 新增属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enablePlaceholder` | `boolean` | `false` | 是否启用占位功能 |
+| `minRows` | `number` | `0` | 最小行数（如果实际数据行数少于此值，会添加占位行） |
+| `minColumns` | `number` | `0` | 最小列数（如果实际数据列数少于此值，会添加占位列） |
+| `placeholderRowHeight` | `number` | `rowHeight` (56) | 占位行的高度 |
+| `placeholderColumnWidth` | `number \| number[]` | `150` | 占位列的宽度（可以是数字或数组为每列单独设置） |
+
+## 工作原理
+
+### 占位行
+- 当 `enablePlaceholder={true}` 且 `rows.length < minRows` 时
+- 会在实际数据行之后添加 `(minRows - rows.length)` 个占位行
+- 占位行的 key 格式为 `_placeholder_row_0`, `_placeholder_row_1` 等
+- 每个占位行使用 `placeholderRowHeight` 高度（未设置时使用 `rowHeight`，默认 56px）
+- 占位行内容为空，保持视觉整洁
+
+### 占位列
+- 当 `enablePlaceholder={true}` 且实际数据列数 `< minColumns` 时
+- 会在实际数据列之后添加 `(minColumns - currentDataColumns)` 个占位列
+- 占位列的 key 格式为 `_placeholder_col_0`, `_placeholder_col_1` 等
+- 每个占位列使用 `placeholderColumnWidth` 宽度（默认 150px）
+- 占位列内容为空，保持视觉整洁
+
+### 灵活性
+通过 `placeholderRowHeight` 和 `placeholderColumnWidth` 参数，可以精确控制占位元素的尺寸：
+- **小尺寸占位**：适用于需要更紧凑的表格布局
+- **大尺寸占位**：适用于需要更宽松的表格布局
+- **精确控制**：可以计算容器大小并设置精确的占位尺寸来完美填充
+
+### 与统计功能的兼容性
+- 占位行和列完全兼容 Row Stats 和 Column Stats 功能
+- 占位单元格会被正确识别并跳过内容渲染
+- 统计计算不会包含占位行列的数据
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<StatisticsTable
+  rows={rows}              // 假设只有 2 行数据
+  columns={columns}        // 假设只有 2 列数据
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}            // 确保至少显示 10 行
+  minColumns={5}          // 确保至少显示 5 列
+  maxHeight={600}         // 设置容器高度
+/>
+```
+
+### 仅填充行
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  maxHeight={600}
+/>
+```
+
+### 仅填充列
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minColumns={5}
+/>
+```
+
+### 自定义占位尺寸
+
+**统一设置所有占位列宽度：**
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  minColumns={5}
+  placeholderRowHeight={80}      // 占位行高度 80px
+  placeholderColumnWidth={200}   // 所有占位列宽度 200px
+  maxHeight={600}
+/>
+```
+
+**为每个占位列单独设置宽度（更好地适配屏幕宽度）：**
+
+```tsx
+<StatisticsTable
+  rows={rows}              // 假设有 2 列数据
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minColumns={5}           // 需要 3 个占位列
+  placeholderColumnWidth={[180, 250, 120]} // 为每个占位列单独设置宽度
+  // 占位列 1: 180px
+  // 占位列 2: 250px
+  // 占位列 3: 120px
+/>
+```
+
+如果数组长度少于所需的占位列数量，最后一个值会被重复使用：
+
+```tsx
+placeholderColumnWidth={[200, 150]}  // minColumns=5, 需要 3 个占位列
+// 结果: [200, 150, 150] - 最后的值 (150) 被重复使用
+```
+
+### 配合统计功能
+
+```tsx
+<StatisticsTable
+  rows={rows}
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={10}
+  minColumns={5}
+  placeholderRowHeight={70}
+  showRowStats={true}      // 可以同时使用行统计
+  maxHeight={600}
+/>
+```
+
+### 精确填充容器
+
+如果你知道容器的确切尺寸，可以计算需要的占位数量和尺寸：
+
+```tsx
+const containerHeight = 600;
+const headerHeight = 40;
+const columnStatsHeight = showColumnStats ? 120 : 0;
+const availableHeight = containerHeight - headerHeight - columnStatsHeight;
+
+const dataRowsCount = 3;
+const desiredTotalRows = Math.floor(availableHeight / 56);
+
+<StatisticsTable
+  rows={rows}              // 3 rows
+  columns={columns}
+  cells={cells}
+  enablePlaceholder={true}
+  minRows={desiredTotalRows}
+  placeholderRowHeight={56}
+  maxHeight={containerHeight}
+/>
+```
+
+## 使用场景
+
+1. **固定大小表格**：需要表格保持固定的视觉大小，不随数据量变化
+2. **数据加载中**：在数据还在加载但想保持布局稳定时
+3. **预留空间**：为可能增加的数据预留视觉空间
+4. **对齐要求**：多个表格需要保持相同的尺寸对齐
+
+## 实现细节
+
+### 内部实现
+
+组件内部通过 `useMemo` 生成 `displayRows` 和 `displayColumns`：
+
+```typescript
+const { displayRows, displayColumns } = useMemo(() => {
+  if (!enablePlaceholder) {
+    return { displayRows: rows, displayColumns: columns };
+  }
+
+  // 处理列：如果当前列数少于最小列数，添加占位列
+  let finalColumns = [...columns];
+  const currentDataColumns = columns.filter(col => !col.isAction).length;
+  
+  if (minColumns > 0 && currentDataColumns < minColumns) {
+    const missingColumns = minColumns - currentDataColumns;
+    const placeholderColumns = Array.from({ length: missingColumns }, (_, i) => ({
+      key: `_placeholder_col_${i}`,
+      title: '',
+      width: 150, // 使用默认宽度
+    }));
+    finalColumns = [...columns, ...placeholderColumns];
+  }
+
+  // 处理行：如果当前行数少于最小行数，添加占位行
+  let finalRows = [...rows];
+  if (minRows > 0 && rows.length < minRows) {
+    const missingRows = minRows - rows.length;
+    const placeholderRows = Array.from({ length: missingRows }, (_, i) => ({
+      key: `_placeholder_row_${i}`,
+      label: '',
+      height: rowHeight, // 使用默认行高
+    }));
+    finalRows = [...rows, ...placeholderRows];
+  }
+
+  return { displayRows: finalRows, displayColumns: finalColumns };
+}, [rows, columns, enablePlaceholder, minRows, minColumns, rowHeight]);
+```
+
+### 渲染处理
+
+在渲染时，组件会检测占位行列并跳过内容渲染：
+
+```typescript
+const isPlaceholder = row.key.startsWith('_placeholder_row_');
+const isColPlaceholder = column.key.startsWith('_placeholder_col_');
+
+// 占位单元格不渲染内容
+<View style={[styles.cell, { width: colWidth }]}>
+  {!isColPlaceholder && !isPlaceholder && renderCellContent(column, cell, row.data)}
+</View>
+```
+
+## 测试覆盖
+
+新增了以下测试用例：
+
+1. ✅ 禁用占位功能时不添加占位符
+2. ✅ 数据列少于 minColumns 时添加占位列
+3. ✅ 数据行少于 minRows 时添加占位行
+4. ✅ 同时添加占位行和列
+5. ✅ 数据满足最小要求时不添加占位符
+6. ✅ 与 Row Stats 配合使用
+7. ✅ 与 Column Stats 配合使用
+8. ✅ 使用自定义占位行高度
+9. ✅ 使用自定义占位列宽度
+10. ✅ 同时使用自定义占位行高度和列宽度
+
+## Storybook 示例
+
+### 占位功能示例
+
+添加了 6 个新的 Story 来展示占位功能：
+
+1. `WithPlaceholderRows` - 仅占位行
+2. `WithPlaceholderColumns` - 仅占位列
+3. `WithPlaceholderRowsAndColumns` - 同时占位行列
+4. `WithPlaceholderAndRowStats` - 占位行配合行统计
+5. `WithPlaceholderAndColumnStats` - 占位行配合列统计
+6. `WithCustomPlaceholderSize` - 自定义占位行列尺寸（80px行高 × 200px列宽）
+
+### 滚动阴影示例
+
+添加了 4 个新的 Story 来展示滚动阴影功能：
+
+1. `WithScrollShadow` - 展示滚动阴影效果（上下左右四个方向）
+2. `WithoutScrollShadow` - 对比：不使用滚动阴影（使用滚动条）
+3. `ScrollShadowWithRowStats` - 滚动阴影配合行统计
+4. `ScrollShadowWithColumnStats` - 滚动阴影配合列统计
+
+## 注意事项
+
+1. **性能考虑**：占位功能使用 `flex: 1`，不会增加额外的行列，性能影响极小
+2. **视觉一致性**：占位单元格没有边框，保持视觉上的整洁
+3. **数据完整性**：占位行列不会影响统计计算和数据导出
+4. **互不干扰**：占位功能与现有所有功能完全兼容（统计、分页、虚拟化等）
+
+## 更新日志
+
+- ✅ 在 `StatisticsTable.tsx` 中添加占位行列逻辑
+- ✅ 更新 `StatisticsTableProps` 接口，添加新属性
+  - `enablePlaceholder` - 启用占位功能
+  - `minRows` - 最小行数
+  - `minColumns` - 最小列数
+  - `placeholderRowHeight` - 自定义占位行高度
+  - `placeholderColumnWidth` - 自定义占位列宽度
+- ✅ 更新 README.md，添加功能说明和使用示例
+- ✅ 添加完整的测试用例（10个测试）
+- ✅ 添加 Storybook 示例（6个 Stories）
+- ✅ 添加滚动阴影 Storybook 示例（4个 Stories）
+- ✅ 所有代码通过 Linter 检查
+