@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/CheckBox/README.md

@@ -0,0 +1,147 @@
+# CheckBox / CheckBoxItem / GroupCheckBox
+
+复选框组件系列，包含三个子组件：CheckBox（单个复选框）、CheckBoxItem（列表项复选框）、GroupCheckBox（分组复选框）。
+
+## 功能特性
+
+- ✅ CheckBox 支持 light 和 dark 两种主题模式
+- ✅ CheckBox 支持全选和半选（indeterminate）图标
+- ✅ Web 端 hover 交互效果
+- ✅ 支持禁用状态
+- ✅ 受控模式，通过 checked 属性控制选中状态
+- ✅ CheckBoxItem 适用于列表场景，带完整的列表项样式
+- ✅ GroupCheckBox 支持分组展示，自动管理多选状态
+- ✅ GroupCheckBox 支持分组名称显示
+- ✅ 支持无障碍访问（accessibilityRole="checkbox"）
+- ✅ 使用 React.memo 优化渲染性能
+
+## 安装使用
+
+```tsx
+import CheckBox from '@beppla/tapas-ui/components/CheckBox/CheckBox';
+import CheckBoxItem from '@beppla/tapas-ui/components/CheckBox/CheckBoxItem';
+import GroupCheckBox from '@beppla/tapas-ui/components/CheckBox/GroupCheckBox';
+```
+
+## Props
+
+### CheckBox Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| label | `string` | - | 复选框标签文字 |
+| checked | `boolean` | `false` | 是否选中 |
+| disabled | `boolean` | - | 是否禁用 |
+| onPress | `() => void` | - | 点击回调 |
+| hoverStyle | `StyleProp<ViewStyle>` | - | hover 时的自定义样式 |
+| type | `'checkbox' \| 'radio'` | - | 复选框类型 |
+| mode | `'dark' \| 'light'` | - | 主题模式 |
+| full | `boolean` | `true` | 是否全选图标，false 时显示半选图标 |
+| children | `React.ReactNode` | - | 子内容 |
+| style | - | - | 自定义容器样式（继承自 TextProps） |
+
+### CheckBoxItem Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| selected | `boolean` | - | 是否选中 |
+| item | `CheckBoxItemProps` | - | 选项数据（含 value、title、disabled） |
+| key | `number \| string` | - | 唯一标识 |
+| onItemPress | `(item: { value: string; title: string; disabled?: boolean }) => void` | - | 点击回调 |
+| disabled | `boolean` | - | 是否禁用 |
+
+### CheckBoxItemProps 数据类型
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | `string` | 选项值 |
+| title | `string` | 选项标题 |
+| disabled | `boolean` | 是否禁用 |
+
+### GroupCheckBox Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| options | `OptionItem[]` | - | 分组选项数据 |
+| selectedValues | `string[]` | - | 已选中的值数组 |
+| onChange | `(value: string[]) => void` | - | 选中值变化回调 |
+
+### OptionItem / item 数据类型
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| groupName | `string` | 分组名称（可选） |
+| items | `item[]` | 分组下的选项列表 |
+
+## 使用示例
+
+### 基础 CheckBox
+
+```tsx
+<CheckBox label="Hello" checked={false} mode="light" onPress={() => {}} />
+```
+
+### 半选状态
+
+```tsx
+<CheckBox label="部分选中" checked={true} full={false} mode="light" />
+```
+
+### Dark 模式
+
+```tsx
+<CheckBox label="Dark Mode" checked={false} mode="dark" />
+```
+
+### CheckBoxItem 列表
+
+```tsx
+const data = [
+  { title: 'Jone', value: 'Jone', disabled: false },
+  { title: 'Bob', value: 'Bob', disabled: true },
+];
+
+{data.map((item, index) => (
+  <CheckBoxItem
+    key={index}
+    item={item}
+    selected={selectedItems.includes(item.value)}
+    disabled={item.disabled}
+    onItemPress={(value) => handleSelect(value)}
+  />
+))}
+```
+
+### 分组复选框
+
+```tsx
+const options = [
+  {
+    groupName: 'Group 1',
+    items: [
+      { title: 'Jone', value: 'Jone', disabled: false, id: '1' },
+      { title: 'Bob', value: 'Bob', disabled: true, id: '2' },
+    ],
+  },
+  {
+    groupName: 'Group 2',
+    items: [
+      { title: 'Anan', value: 'Anan', disabled: false, id: '3' },
+    ],
+  },
+];
+
+<GroupCheckBox
+  options={options}
+  selectedValues={[]}
+  onChange={(selectedValues) => console.log(selectedValues)}
+/>
+```
+
+## 注意事项
+
+- CheckBox 的 hover 效果仅在 Web 平台生效
+- GroupCheckBox 的 selectedValues 格式为 `groupName__value__id` 或 `value__id`
+- CheckBoxItem 的 `selected` 属性为布尔值，需要外部管理选中状态
+- GroupCheckBox 内置了选中状态管理，通过 onChange 回调通知外部
+- item 数据类型中 `id` 字段在 GroupCheckBox 中是必须的

package/package/module/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/package/module/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/package/module/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 数组长度一致