@beppla/tapas-ui 1.5.9 → 1.5.11

package/package/module/Card/README.md

@@ -0,0 +1,126 @@
+# Card
+
+通用卡片组件，支持图标、状态指示、导航按钮和更多选项菜单，适用于仪表板入口、功能模块展示等场景。
+
+## 功能特性
+
+- ✅ 支持自定义图标显示（TapasIcon）
+- ✅ 状态指示器（normal / warning / error / success），带对应颜色背景标签
+- ✅ 可选的导航按钮（showNavBtn），带圆形边框样式
+- ✅ 更多选项按钮（showMore），支持自定义图标
+- ✅ 鼠标悬停阴影效果
+- ✅ 自定义卡片宽度，固定高度 128px
+- ✅ 标题与副标题显示，自动单行截断
+- ✅ 点击事件回调，返回 `path--cardId` 格式
+- ✅ 继承 ViewProps，支持自定义样式
+- ✅ 基于 @rneui/themed 主题系统
+
+## 安装使用
+
+```tsx
+import Card from '@beppla/tapas-ui/components/Card/Card';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| cardId | `string` | (必填) | 卡片唯一标识 |
+| title | `string` | - | 卡片标题 |
+| subTitle | `string` | - | 卡片副标题 |
+| icon | `string` | - | 卡片图标名称（TapasIcon） |
+| showMore | `boolean` | - | 是否显示更多选项按钮 |
+| moreBtnIcon | `string` | `'more_vert'` | 更多按钮图标名称 |
+| showMoreOptions | `(key: string) => void` | - | 更多选项按钮点击回调，参数为 cardId |
+| path | `string` | - | 路径标识，拼接到 onPress 回调参数中 |
+| showNavBtn | `boolean` | - | 是否显示导航按钮 |
+| navBtnIcon | `string` | `'back'` | 导航按钮图标名称 |
+| state | `'normal' \| 'warning' \| 'error' \| 'success'` | - | 卡片状态 |
+| stateText | `string` | - | 状态指示文本 |
+| width | `number` | `285` | 卡片宽度（像素） |
+| onPress | `(key: string) => void` | - | 卡片点击回调，参数为 `${path}--${cardId}` |
+| actions | `Action[]` | - | 操作按钮数组 |
+| style | `ViewStyle` | - | 自定义样式（继承自 ViewProps） |
+
+### Action 接口
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| key | `string` | 操作唯一标识 |
+| name | `string` | 操作名称 |
+| icon | `string` | 操作图标名称 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<Card
+  cardId="card-1"
+  title="示例卡片"
+  subTitle="这是一个示例卡片"
+  icon="dashboard"
+  showNavBtn
+  width={285}
+/>
+```
+
+### 带状态指示
+
+```tsx
+<Card
+  cardId="card-2"
+  title="运行状态"
+  subTitle="服务器状态"
+  icon="dashboard"
+  state="success"
+  stateText="运行正常"
+/>
+```
+
+### 带更多选项
+
+```tsx
+<Card
+  cardId="card-3"
+  title="功能模块"
+  subTitle="点击查看更多"
+  icon="restaurant_menu"
+  showMore
+  showMoreOptions={(cardId) => console.log(`More: ${cardId}`)}
+/>
+```
+
+### 不同尺寸
+
+```tsx
+<Card cardId="small-card" width={200} title="小尺寸卡片" />
+<Card cardId="standard-card" width={285} title="标准尺寸卡片" />
+<Card cardId="large-card" width={350} title="大尺寸卡片" />
+```
+
+### 交互卡片
+
+```tsx
+<Card
+  cardId="card-4"
+  title="可点击卡片"
+  subTitle="点击触发事件"
+  icon="dashboard"
+  showMore
+  showNavBtn
+  state="warning"
+  stateText="需要注意"
+  onPress={(key) => console.log(`Pressed: ${key}`)}
+  showMoreOptions={(cardId) => console.log(`More: ${cardId}`)}
+/>
+```
+
+## 注意事项
+
+- `cardId` 属性是必填项，用于唯一标识卡片
+- `onPress` 回调返回的 key 格式为 `${path}--${cardId}`
+- `state` 和 `stateText` 需同时设置才会显示状态标签
+- 卡片固定高度为 128px，宽度通过 `width` 属性控制，默认 285px
+- 更多选项按钮点击事件通过 `stopPropagation` 阻止冒泡到卡片点击
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用

package/package/module/CheckBox/CheckBox.js

@@ -0,0 +1,135 @@
+"use strict";
+
+import React, { useEffect, useState } from 'react';
+import { makeStyles, withTheme, Text as RNText } from "@rneui/themed";
+import { Platform, TouchableOpacity } from "react-native";
+import Icon from '../Icons/TapasIcon';
+import Hoverable from '../Hoverable/Hoverable';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const useStyles = makeStyles((theme, ...props) => {
+  const {
+    disabled,
+    mode
+  } = props[0];
+  return {
+    textItem: {
+      fontFamily: theme.fonts.fontFamily,
+      fontSize: theme.fonts.sizeM,
+      fontWeight: theme.fonts.weightR,
+      color: theme.colors.colorTextPrimary,
+      // textOverflow: 'ellipsis', // Not supported in React Native
+      // whiteSpace: 'nowrap', // Not supported in React Native
+      justifyContent: "center",
+      alignItems: "center",
+      display: "flex",
+      minWidth: 80
+    },
+    checkBoxContainer: {
+      backgroundColor: mode === 'dark' ? theme.colors.grey4 : theme.colors.white,
+      paddingLeft: 12,
+      paddingRight: 16,
+      paddingVertical: 8,
+      height: 40,
+      minWidth: 80,
+      borderRadius: theme.radius.rounded,
+      marginBottom: 8,
+      display: "flex",
+      justifyContent: "center",
+      alignItems: "center"
+    },
+    disabledText: {
+      color: theme.colors.disabled
+    },
+    hovered: {
+      backgroundColor: mode === 'dark' ? theme.colors.grey3 : undefined
+    },
+    selected: {
+      backgroundColor: mode === 'dark' ? theme.colors.primary : undefined
+    },
+    textHovered: {
+      color: mode === 'light' ? theme.colors.grey1 : undefined
+    },
+    textSelected: {
+      color: mode === 'dark' ? theme.colors.white : theme.colors.primary
+    },
+    checkBox: {
+      marginRight: 8,
+      color: disabled ? theme.colors.disabled : theme.colors.colorTextPrimary
+    },
+    checkedBox: {
+      color: mode === 'dark' ? theme.colors.white : theme.colors.primary
+    },
+    uncheckedBox: {
+      color: theme.colors.colorTextPrimary
+    },
+    disabledBox: {
+      color: theme.colors.disabled
+    }
+  };
+});
+const CheckBox = props => {
+  const styles = useStyles(props);
+  const {
+    children,
+    label,
+    checked = false,
+    disabled,
+    style,
+    onPress,
+    hoverStyle,
+    full = true,
+    testID
+  } = props;
+  const [isHovered, setIsHovered] = useState(false);
+  const [isSelected, setIsSelected] = useState(checked);
+  const handleItemPress = () => {
+    setIsSelected(!isSelected);
+    onPress && onPress();
+  };
+  const handleMouseEnter = () => {
+    setIsHovered(true);
+  };
+  const handleMouseLeave = () => {
+    setIsHovered(false);
+  };
+  useEffect(() => {
+    setIsSelected(checked);
+  }, [checked]);
+  const renderText = () => {
+    return !disabled ? /*#__PURE__*/_jsx(TouchableOpacity, {
+      testID: testID,
+      style: [styles.checkBoxContainer, isHovered && styles.hovered, isHovered && hoverStyle, isSelected && styles.selected, style],
+      onPress: handleItemPress,
+      accessibilityRole: "checkbox",
+      accessibilityLabel: label || (typeof children === 'string' ? children : 'Checkbox'),
+      children: /*#__PURE__*/_jsxs(RNText, {
+        style: [styles.textItem, isHovered && styles.textHovered, isSelected && styles.textSelected],
+        numberOfLines: 1,
+        ellipsizeMode: "tail",
+        ...props,
+        children: [/*#__PURE__*/_jsx(Icon, {
+          style: [styles.checkBox, isSelected && styles.checkedBox, !isSelected && styles.uncheckedBox],
+          name: isSelected ? full ? 'check_box' : 'indeterminate_check_box' : 'check_box_outline_blank',
+          size: 20
+        }), label, children]
+      })
+    }) : /*#__PURE__*/_jsxs(RNText, {
+      style: [styles.checkBoxContainer, styles.textItem, disabled && styles.disabledText, style],
+      numberOfLines: 1,
+      ellipsizeMode: "tail",
+      ...props,
+      children: [/*#__PURE__*/_jsx(Icon, {
+        style: [styles.checkBox],
+        name: isSelected ? 'check_box' : 'check_box_outline_blank',
+        size: 24
+      }), label, children]
+    });
+  };
+  return Platform.OS === 'web' ? /*#__PURE__*/_jsx(Hoverable, {
+    onHoverIn: handleMouseEnter,
+    onHoverOut: handleMouseLeave,
+    children: renderText()
+  }) : renderText();
+};
+export default withTheme(/*#__PURE__*/React.memo(CheckBox));
+//# sourceMappingURL=CheckBox.js.map

package/package/module/CheckBox/CheckBox.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","useEffect","useState","makeStyles","withTheme","Text","RNText","Platform","TouchableOpacity","Icon","Hoverable","jsx","_jsx","jsxs","_jsxs","useStyles","theme","props","disabled","mode","textItem","fontFamily","fonts","fontSize","sizeM","fontWeight","weightR","color","colors","colorTextPrimary","justifyContent","alignItems","display","minWidth","checkBoxContainer","backgroundColor","grey4","white","paddingLeft","paddingRight","paddingVertical","height","borderRadius","radius","rounded","marginBottom","disabledText","hovered","grey3","undefined","selected","primary","textHovered","grey1","textSelected","checkBox","marginRight","checkedBox","uncheckedBox","disabledBox","CheckBox","styles","children","label","checked","style","onPress","hoverStyle","full","testID","isHovered","setIsHovered","isSelected","setIsSelected","handleItemPress","handleMouseEnter","handleMouseLeave","renderText","accessibilityRole","accessibilityLabel","numberOfLines","ellipsizeMode","name","size","OS","onHoverIn","onHoverOut","memo"],"sourceRoot":"../../../components","sources":["CheckBox/CheckBox.tsx"],"mappings":"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","ignoreList":[]}

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 变化时重新渲染