@beppla/tapas-ui 1.4.13 → 1.4.15

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/Quantity/README.md

@@ -0,0 +1,251 @@
+# TapasQuantity
+
+一个简洁高效的数量选择器组件，支持增减操作、范围限制和自定义步长。
+
+## 功能特性
+
+- ✅ 数量增减：支持增加和减少操作
+- ✅ 范围限制：支持最大值和最小值设置
+- ✅ 自定义步长：支持自定义每次增减的数量
+- ✅ 状态管理：支持禁用状态和边界状态
+- ✅ 边界提示：可选的数值范围提示
+- ✅ 自定义样式：支持按钮大小和样式自定义
+- ✅ 响应式设计：适配不同屏幕尺寸
+- ✅ 无障碍支持：完整的可访问性支持
+
+## 安装使用
+
+```tsx
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasQuantity
+  value={5}
+  onChange={(value) => console.log('数量:', value)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `number` | - | 当前数量值（必填） |
+| `onChange` | `(value: number) => void` | - | 数量变化回调 |
+| `min` | `number` | `0` | 最小值 |
+| `max` | `number` | `99999` | 最大值 |
+| `step` | `number` | `1` | 每次增减的步长 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `showValue` | `boolean` | `true` | 是否显示当前值 |
+| `showBoundaryHint` | `boolean` | `false` | 是否显示边界提示 |
+| `buttonSize` | `number` | `32` | 增减按钮的大小 |
+| `style` | `ViewStyle` | - | 容器样式 |
+| `buttonStyle` | `ViewStyle` | - | 按钮样式 |
+| `valueStyle` | `ViewStyle` | - | 值显示区域样式 |
+
+## 使用示例
+
+### 基础数量选择
+
+```tsx
+import React, { useState } from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const QuantityDemo = () => {
+  const [quantity, setQuantity] = useState(1);
+
+  const handleQuantityChange = (value: number) => {
+    setQuantity(value);
+    console.log('数量变化:', value);
+  };
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={handleQuantityChange}
+      min={1}
+      max={99}
+    />
+  );
+};
+```
+
+### 带范围提示的数量选择
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const RangeQuantityDemo = () => {
+  const [quantity, setQuantity] = useState(5);
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={setQuantity}
+      min={1}
+      max={10}
+      showBoundaryHint={true}
+    />
+  );
+};
+```
+
+### 自定义步长
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const StepQuantityDemo = () => {
+  const [quantity, setQuantity] = useState(10);
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={setQuantity}
+      min={0}
+      max={100}
+      step={5}
+      showBoundaryHint={true}
+    />
+  );
+};
+```
+
+### 禁用状态
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const DisabledQuantityDemo = () => {
+  return (
+    <TapasQuantity
+      value={5}
+      onChange={() => {}}
+      disabled={true}
+    />
+  );
+};
+```
+
+### 自定义按钮大小
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const CustomSizeQuantityDemo = () => {
+  const [quantity, setQuantity] = useState(5);
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={setQuantity}
+      buttonSize={40}
+      min={0}
+      max={10}
+    />
+  );
+};
+```
+
+### 隐藏数值显示
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const HiddenValueDemo = () => {
+  const [quantity, setQuantity] = useState(5);
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={setQuantity}
+      showValue={false}
+      min={0}
+      max={10}
+    />
+  );
+};
+```
+
+### 负数值范围
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const NegativeRangeDemo = () => {
+  const [quantity, setQuantity] = useState(0);
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={setQuantity}
+      min={-10}
+      max={10}
+      showBoundaryHint={true}
+    />
+  );
+};
+```
+
+### 小数步长
+
+```tsx
+import React from 'react';
+import { TapasQuantity } from '@beppla/tapas-ui';
+
+const DecimalStepDemo = () => {
+  const [quantity, setQuantity] = useState(0.5);
+
+  return (
+    <TapasQuantity
+      value={quantity}
+      onChange={setQuantity}
+      min={0}
+      max={1}
+      step={0.1}
+      showBoundaryHint={true}
+    />
+  );
+};
+```
+
+## 最佳实践
+
+1. **合理的范围设置**：根据业务需求设置合适的最大值和最小值
+2. **适当的步长**：根据实际使用场景选择合适的步长值
+3. **边界提示**：当范围较大或需要用户了解限制时，启用边界提示
+4. **禁用状态**：在数据加载或操作不可用时，使用禁用状态
+5. **回调处理**：在 onChange 回调中处理数量变化，避免直接修改状态
+
+## 使用场景
+
+- 商品数量选择
+- 表单数量输入
+- 购物车数量调整
+- 库存数量管理
+- 评分系统
+- 配置参数调整
+- 游戏数值设置
+- 数据筛选范围
+
+## 注意事项
+
+1. `value` 属性是必填的，必须提供初始值
+2. 当 `value` 超出 `min` 和 `max` 范围时，组件会自动调整到有效范围内
+3. `step` 值应该合理设置，避免过大的步长导致用户体验不佳
+4. 组件会自动处理边界情况，当达到最小值时减少按钮会被禁用，达到最大值时增加按钮会被禁用
+5. 支持 React Native 和 React Native Web 环境
+
+## 技术实现
+
+- 使用 `useState` 管理内部状态
+- 支持受控和非受控模式
+- 自动边界检查和约束
+- 响应式按钮状态管理
+- 完整的类型安全支持
+- 主题集成和样式自定义