@beppla/tapas-ui 1.5.12 → 1.5.13

package/package/module/SheetTitle/README.md

@@ -1,89 +0,0 @@
-# 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

@@ -1,152 +0,0 @@
-# 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

@@ -1,129 +0,0 @@
-# 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

@@ -1,287 +0,0 @@
-# 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 检查
-