@beppla/tapas-ui 1.4.32 → 1.4.34

package/package/module/MultiSelector/README.md

@@ -0,0 +1,246 @@
+# TapasMultiSelector
+
+一个功能完整的多选下拉组件，支持搜索、验证、动画标签和丰富的自定义选项。
+
+## 功能特性
+
+- ✅ 多选支持：可以选择多个选项
+- ✅ 搜索功能：内置搜索栏，支持过滤选项
+- ✅ 动画标签：平滑的标签动画效果
+- ✅ 状态管理：支持正常和错误状态
+- ✅ 验证支持：必填字段验证和状态消息
+- ✅ 动态定位：智能计算弹出位置和方向
+- ✅ 自定义样式：支持多种样式类型和尺寸
+- ✅ 操作按钮：清除和确认按钮
+- ✅ 响应式设计：适配不同屏幕尺寸
+- ✅ 无障碍支持：完整的可访问性支持
+
+## 安装使用
+
+```tsx
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasMultiSelector
+  label="选择水果"
+  dropdownItems={fruitOptions}
+  onSelect={(keys) => console.log('选中:', keys)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `label` | `string` | - | 标签文本 |
+| `title` | `string` | - | 弹出框标题 |
+| `dropdownItems` | `TapasMultiSelectorItem[]` | `[]` | 选项列表 |
+| `selected` | `number[]` | `[]` | 当前选中的选项键值数组 |
+| `onSelect` | `(keys: number[]) => void` | - | 选择变化回调 |
+| `placeholder` | `string` | - | 占位符文本 |
+| `required` | `boolean` | `false` | 是否必填 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `state` | `"normal" \| "error"` | `"normal"` | 状态类型 |
+| `stateMsg` | `string` | - | 状态消息 |
+| `showStateMsg` | `boolean` | `false` | 是否显示状态消息 |
+| `showSelectedValue` | `boolean` | `false` | 是否显示选中值 |
+| `showSearchBar` | `boolean` | `false` | 是否显示搜索栏 |
+| `type` | `"clear" \| "solid"` | `"clear"` | 按钮类型 |
+| `width` | `number` | - | 组件宽度 |
+| `height` | `number` | - | 组件高度 |
+| `radius` | `number` | `12` | 圆角半径 |
+| `icon` | `string` | `"arrow_drop_down"` | 图标名称 |
+| `iconStyle` | `ViewStyle \| TextStyle` | - | 图标样式 |
+| `backgroundColor` | `string` | - | 背景颜色 |
+| `noLabelAnim` | `boolean` | `false` | 是否禁用标签动画 |
+| `offsetWidth` | `number` | `0` | 位置偏移宽度 |
+| `dropdownSubWidth` | `number` | `151` | 弹出框宽度 |
+| `dropdownSubHeight` | `number` | - | 弹出框最大高度 |
+| `visible` | `boolean` | - | 控制弹出框可见性 |
+| `setVisible` | `(val: boolean) => void` | - | 设置弹出框可见性 |
+| `searchPlaceholder` | `string` | `"Search"` | 搜索框占位符 |
+| `clearButtonText` | `string` | `"Clear"` | 清除按钮文本 |
+| `confirmButtonText` | `string` | `"Done"` | 确认按钮文本 |
+
+## TapasMultiSelectorItem 接口
+
+```tsx
+interface TapasMultiSelectorItem {
+  key: number;           // 唯一标识
+  value: string;         // 显示文本
+  secondaryValue?: string; // 次要文本（可选）
+}
+```
+
+## 使用示例
+
+### 基础多选
+
+```tsx
+import React, { useState } from 'react';
+import { TapasMultiSelector, TapasMultiSelectorItem } from '@beppla/tapas-ui';
+
+const MultiSelectDemo = () => {
+  const [selectedFruits, setSelectedFruits] = useState<number[]>([]);
+
+  const fruitOptions: TapasMultiSelectorItem[] = [
+    { key: 1, value: '苹果' },
+    { key: 2, value: '香蕉' },
+    { key: 3, value: '橙子' },
+    { key: 4, value: '葡萄' },
+  ];
+
+  const handleSelection = (keys: number[]) => {
+    setSelectedFruits(keys);
+    console.log('选中的水果:', keys);
+  };
+
+  return (
+    <TapasMultiSelector
+      label="选择水果"
+      dropdownItems={fruitOptions}
+      selected={selectedFruits}
+      onSelect={handleSelection}
+      placeholder="请选择您喜欢的水果"
+      showSelectedValue={true}
+    />
+  );
+};
+```
+
+### 带搜索和验证
+
+```tsx
+import React, { useState } from 'react';
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+const ValidatedMultiSelect = () => {
+  const [selectedTags, setSelectedTags] = useState<number[]>([]);
+  const [isValid, setIsValid] = useState(true);
+
+  const tagOptions = [
+    { key: 1, value: '新上市', secondaryValue: '最近添加的产品' },
+    { key: 2, value: '热销', secondaryValue: '销量最高的产品' },
+    { key: 3, value: '促销', secondaryValue: '打折产品' },
+    { key: 4, value: '推荐', secondaryValue: '精选产品' },
+  ];
+
+  const handleSelection = (keys: number[]) => {
+    setSelectedTags(keys);
+    setIsValid(keys.length > 0);
+  };
+
+  return (
+    <TapasMultiSelector
+      label="产品标签"
+      title="选择产品标签"
+      dropdownItems={tagOptions}
+      selected={selectedTags}
+      onSelect={handleSelection}
+      required={true}
+      showSearchBar={true}
+      showStateMsg={true}
+      state={isValid ? 'normal' : 'error'}
+      stateMsg={isValid ? '已选择标签' : '请至少选择一个标签'}
+      searchPlaceholder="搜索标签..."
+      placeholder="选择产品标签"
+      clearButtonText="清除所有"
+      confirmButtonText="应用标签"
+    />
+  );
+};
+```
+
+### 自定义样式
+
+```tsx
+import React from 'react';
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+const CustomStyledMultiSelect = () => {
+  const categoryOptions = [
+    { key: 1, value: '电子产品' },
+    { key: 2, value: '服装' },
+    { key: 3, value: '图书' },
+    { key: 4, value: '运动' },
+  ];
+
+  return (
+    <TapasMultiSelector
+      label="产品分类"
+      dropdownItems={categoryOptions}
+      type="solid"
+      radius={20}
+      width={350}
+      height={70}
+      backgroundColor="#f8f9fa"
+      iconStyle={{ color: '#007bff' }}
+      clearButtonText="重置"
+      confirmButtonText="确认选择"
+    />
+  );
+};
+```
+
+### 带次要文本的选项
+
+```tsx
+import React from 'react';
+import { TapasMultiSelector } from '@beppla/tapas-ui';
+
+const SecondaryValueDemo = () => {
+  const departmentOptions = [
+    { key: 1, value: '技术部', secondaryValue: '负责产品开发和维护' },
+    { key: 2, value: '市场部', secondaryValue: '负责品牌推广和销售' },
+    { key: 3, value: '人事部', secondaryValue: '负责人员招聘和管理' },
+    { key: 4, value: '财务部', secondaryValue: '负责财务核算和预算' },
+  ];
+
+  return (
+    <TapasMultiSelector
+      label="选择部门"
+      title="部门选择"
+      dropdownItems={departmentOptions}
+      showSearchBar={true}
+      searchPlaceholder="搜索部门..."
+      placeholder="请选择您感兴趣的部门"
+    />
+  );
+};
+```
+
+## 最佳实践
+
+1. **合理的选项数量**：建议选项数量控制在 5-20 个之间，过多选项考虑分页
+2. **清晰的标签文案**：标签和选项文案应该简洁明确，避免歧义
+3. **适当的验证**：对于重要选择，使用 `required` 和状态消息
+4. **搜索功能**：当选项较多时，启用搜索功能提升用户体验
+5. **自定义按钮文案**：根据业务场景自定义清除和确认按钮文案
+
+## 使用场景
+
+- 产品分类选择
+- 用户权限配置
+- 标签管理系统
+- 兴趣爱好选择
+- 技能评估表单
+- 多选问卷调查
+- 文件类型过滤
+- 用户分组管理
+
+## 注意事项
+
+1. `dropdownItems` 数组为空时，组件仍会正常渲染，但不会显示任何选项
+2. 当 `required` 为 `true` 且没有选择任何选项时，建议显示错误状态
+3. 组件会自动计算弹出位置，确保在屏幕边界内显示
+4. 支持 React Native 和 React Native Web 环境
+5. 动画效果在测试环境中可能需要特殊处理
+
+## 技术实现
+
+- 使用 `Modal` 实现弹出效果
+- 动态计算弹出位置和方向
+- 支持标签动画效果
+- 集成搜索和过滤功能
+- 完整的键盘导航支持
+- 响应式布局设计

package/package/module/Notification/README.md

@@ -0,0 +1,158 @@
+# TapasNotification
+
+A side notification panel component with expand/collapse animation and item selection functionality.
+
+## Features
+
+- **Expandable Side Panel**: Smooth expand/collapse animation
+- **Notification List**: Display multiple notification items with icons
+- **Item Selection**: Highlight selected items with visual feedback
+- **Customizable**: Configurable title, empty state, and animations
+- **Responsive**: Adapts to different screen sizes and orientations
+
+## Usage
+
+```tsx
+import { TapasNotification, NotificationItem } from '@beppla/tapas-ui';
+
+const notifications: NotificationItem[] = [
+  { id: 1, title: 'System Update Available', icon: 'system_update' },
+  { id: 2, title: 'New Message from John', icon: 'message' },
+];
+
+const MyComponent = () => {
+  const [open, setOpen] = useState(false);
+  const [selectedItem, setSelectedItem] = useState<number | string>();
+
+  const handleSelectItem = (item: NotificationItem) => {
+    setSelectedItem(item.id);
+    console.log('Selected:', item);
+  };
+
+  return (
+    <TapasNotification
+      open={open}
+      title="Notifications"
+      items={notifications}
+      selectedItem={selectedItem}
+      onSelectItem={handleSelectItem}
+      onHeaderButtonPress={() => setOpen(!open)}
+    />
+  );
+};
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | `false` | Controls whether the notification panel is expanded |
+| `title` | `string` | `'Notification'` | The title displayed in the header |
+| `emptyText` | `string` | `'No Data'` | Text displayed when there are no notification items |
+| `headerTitleStyle` | `StyleProp<TextStyle>` | `undefined` | Custom styles for the header title |
+| `hideHeaderButton` | `boolean` | `false` | Whether to hide the header action button |
+| `items` | `NotificationItem[]` | `[]` | Array of notification items to display |
+| `selectedItem` | `number \| string` | `undefined` | ID of the currently selected item |
+| `onSelectItem` | `(item: NotificationItem) => void` | `undefined` | Callback when an item is selected |
+| `onHeaderButtonPress` | `() => void` | `undefined` | Callback when header button is pressed |
+| `animationDuration` | `number` | `500` | Duration of expand/collapse animation in milliseconds |
+| `expandedWidth` | `number` | `288` | Width of the expanded notification panel |
+
+## NotificationItem Interface
+
+```tsx
+interface NotificationItem {
+  id: number | string;        // Unique identifier
+  title: string;              // Display text
+  icon?: string;              // Optional icon name
+  [key: string]: any;         // Additional custom properties
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<TapasNotification
+  open={true}
+  title="System Alerts"
+  items={[
+    { id: 1, title: 'Server Maintenance', icon: 'warning' },
+    { id: 2, title: 'Backup Complete', icon: 'check_circle' }
+  ]}
+/>
+```
+
+### With Selection
+
+```tsx
+<TapasNotification
+  open={true}
+  title="Messages"
+  items={messages}
+  selectedItem={selectedMessageId}
+  onSelectItem={handleMessageSelect}
+/>
+```
+
+### Custom Styling
+
+```tsx
+<TapasNotification
+  open={true}
+  title="Custom Title"
+  headerTitleStyle={{ color: '#FF6B6B', fontSize: 18 }}
+  style={{ backgroundColor: '#2C3E50' }}
+/>
+```
+
+### Hidden Header Button
+
+```tsx
+<TapasNotification
+  open={true}
+  title="Read Only"
+  hideHeaderButton={true}
+  items={notifications}
+/>
+```
+
+### Custom Animation
+
+```tsx
+<TapasNotification
+  open={true}
+  animationDuration={300}
+  expandedWidth={400}
+  items={notifications}
+/>
+```
+
+## Styling
+
+The component uses the theme system for consistent styling. Key style properties include:
+
+- **Container**: Uses `theme.colors.colorSurface2` for background
+- **Header Title**: Uses `theme.colors.white` for text color
+- **Selected Row**: Uses `theme.colors.secondary` for background
+- **Empty State**: Uses `theme.colors.colorSurface11` for text color
+
+## Accessibility
+
+- Supports screen readers with proper text labels
+- Keyboard navigation support
+- High contrast mode compatible
+- Scalable text sizes
+
+## Browser Support
+
+- React Native Web compatible
+- Modern browser support (ES6+)
+- Responsive design for mobile and desktop
+
+## Dependencies
+
+- `react-native-gesture-handler` for ScrollView
+- `@rneui/themed` for theming and styling
+- React Native core components

package/package/module/Pagination/BACKGROUND_COLOR.md

@@ -0,0 +1,173 @@
+# Pagination 背景色自定义
+
+## 概述
+
+TapasPagination 组件现在支持自定义背景色，允许您根据应用的设计需求灵活调整分页器的外观。
+
+## 新增属性
+
+### `backgroundColor`
+
+自定义分页器的背景色。
+
+```typescript
+backgroundColor?: string;
+```
+
+**类型**: `string` (可选)  
+**默认值**: 使用主题的 `theme.colors.background`  
+**支持格式**: 
+- 十六进制颜色：`#FFFFFF`、`#FFF`
+- RGB/RGBA：`rgb(255, 255, 255)`、`rgba(255, 255, 255, 0.5)`
+- 颜色名称：`white`、`blue` 等
+
+## 使用示例
+
+### 基础用法
+
+```typescript
+import Pagination from '@beppla/tapas-ui';
+
+<Pagination
+  totalCount="Total: 20"
+  pageParams={{
+    page: 1,
+    pageSize: 10,
+    totalItems: 60,
+    totalPage: 6,
+  }}
+  backgroundColor="#E3F2FD"  // 浅蓝色背景
+  onPageChange={(page) => console.log('Page:', page)}
+/>
+```
+
+### 不同场景的颜色示例
+
+```typescript
+// 浅色背景（适合深色文字）
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="#F5F5F5"  // 浅灰色
+/>
+
+// 品牌色背景
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="#E8F5E9"  // 浅绿色
+/>
+
+// 透明背景
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  backgroundColor="transparent"
+/>
+
+// 使用主题默认背景（不设置 backgroundColor）
+<Pagination
+  totalCount="Total: 100"
+  pageParams={pageParams}
+  // backgroundColor 未设置时自动使用主题背景色
+/>
+```
+
+### 与其他样式组合
+
+```typescript
+<Pagination
+  totalCount="Total: 50"
+  pageParams={pageParams}
+  backgroundColor="#FFF9C4"  // 自定义背景色
+  paginationContainerStyle={{
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: '#E0E0E0',
+    paddingHorizontal: 32,
+  }}
+/>
+```
+
+## 推荐颜色方案
+
+### 浅色主题推荐
+
+```typescript
+const lightThemeColors = {
+  default: '#FFFFFF',      // 纯白
+  subtle: '#F5F5F5',       // 浅灰
+  info: '#E3F2FD',         // 浅蓝
+  success: '#E8F5E9',      // 浅绿
+  warning: '#FFF9C4',      // 浅黄
+  error: '#FFEBEE',        // 浅红
+};
+```
+
+### 深色主题推荐
+
+```typescript
+const darkThemeColors = {
+  default: '#1E1E1E',      // 深灰
+  subtle: '#2C2C2C',       // 较浅深灰
+  info: '#1A237E',         // 深蓝
+  success: '#1B5E20',      // 深绿
+  warning: '#F57F17',      // 深黄
+};
+```
+
+## 注意事项
+
+1. **文字对比度**: 确保背景色与文字颜色有足够的对比度，以保证可读性
+2. **品牌一致性**: 建议使用与应用整体设计语言一致的颜色
+3. **可访问性**: 遵循 WCAG 2.1 标准，确保颜色对比度至少为 4.5:1
+4. **主题集成**: 如果不设置 `backgroundColor`，组件会自动使用主题的背景色
+
+## 完整 Props
+
+```typescript
+interface Props {
+  totalCount: string;
+  pageSizeOptions?: ItemProps[];
+  visibleTotalCount?: boolean;
+  visiblePageSizeOptions?: boolean;
+  pageParams?: TPageParams;
+  onPageChange?: (page: TPageParams) => void;
+  onPageSizeChange?: (item: ItemProps) => void;
+  paginationContainerStyle?: StyleProp<ViewStyle>;
+  pageSizePosition?: TDropdownPosition;
+  backgroundColor?: string;  // ✨ 新增
+}
+```
+
+## Storybook 示例
+
+在 Storybook 中查看以下示例：
+
+- **Basic**: 默认样式
+- **CustomBackgroundColor**: 单一自定义背景色示例
+- **DifferentBackgroundColors**: 多种背景色对比展示
+
+## 常见问题
+
+### Q: 为什么我设置的背景色不生效？
+
+A: 请检查：
+1. `backgroundColor` 属性是否正确传递
+2. `paginationContainerStyle` 中是否有覆盖性的背景色设置
+3. 颜色值格式是否正确
+
+### Q: 可以使用渐变背景吗？
+
+A: 原生 `backgroundColor` 不支持渐变。如需渐变背景，请使用 `paginationContainerStyle` 配合其他库实现。
+
+### Q: 如何实现半透明背景？
+
+A: 使用 RGBA 格式：
+```typescript
+backgroundColor="rgba(255, 255, 255, 0.8)"  // 80% 不透明度
+```
+
+## 版本历史
+
+- **v1.4.17**: 新增 `backgroundColor` 属性支持