@beppla/tapas-ui 1.5.10 → 1.5.11

package/package/module/ReasonModal/README.md

@@ -0,0 +1,320 @@
+# TapasReasonModal
+
+一个用于选择原因的模态框组件，内置单选按钮组，适用于取消原因、退货原因、反馈类型等场景。
+
+## 功能特性
+
+- ✅ 内置单选按钮组，单选体验优化
+- ✅ 支持预选择和空选择状态控制
+- ✅ 可自定义模态框尺寸和按钮文案
+- ✅ 完整的回调事件支持
+- ✅ 响应式设计，适配不同屏幕尺寸
+- ✅ 支持长文本选项的良好显示
+- ✅ 向后兼容的导出别名
+
+## 安装使用
+
+```tsx
+import { TapasReasonModal } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasReasonModal
+  visible={isVisible}
+  title="选择取消原因"
+  options={reasonOptions}
+  onConfirm={(reason) => console.log('确认:', reason)}
+  onClose={() => setIsVisible(false)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `visible` | `boolean` | `false` | 是否显示模态框 |
+| `title` | `string` | `"Select Reason"` | 模态框标题 |
+| `subtitle` | `string` | - | 副标题或说明文字 |
+| `options` | `ReasonOption[]` | `[]` | 可选择的原因选项数组 |
+| `selectedReason` | `string` | - | 当前选中的原因key |
+| `confirmText` | `string` | `"Confirm"` | 确认按钮文字 |
+| `cancelText` | `string` | `"Cancel"` | 取消按钮文字 |
+| `width` | `number` | `480` | 模态框宽度（像素） |
+| `disableConfirmWhenEmpty` | `boolean` | `true` | 没有选择时是否禁用确认按钮 |
+| `onClose` | `() => void` | - | 关闭模态框的回调 |
+| `onConfirm` | `(reason: ReasonOption) => void` | - | 确认选择的回调 |
+| `onSelectionChange` | `(reason: ReasonOption \| null) => void` | - | 选择改变的回调 |
+| `onRequestClose` | `() => void` | - | 模态框请求关闭的回调 |
+
+## ReasonOption 接口
+
+```tsx
+interface ReasonOption {
+  key: string;    // 唯一标识
+  text: string;   // 显示文本
+}
+```
+
+## 使用示例
+
+### 基础取消原因选择
+
+```tsx
+import React, { useState } from 'react';
+import { TapasReasonModal, ReasonOption } from '@beppla/tapas-ui';
+
+const CancelReasonDemo = () => {
+  const [visible, setVisible] = useState(false);
+  const [selectedReason, setSelectedReason] = useState<string>('');
+
+  const cancelReasons: ReasonOption[] = [
+    { key: '1', text: '商品质量问题' },
+    { key: '2', text: '订单信息错误' },
+    { key: '3', text: '改变主意了' },
+    { key: '4', text: '其他原因' },
+  ];
+
+  const handleConfirm = (reason: ReasonOption) => {
+    console.log('用户选择的取消原因:', reason);
+    // 处理取消逻辑
+    setVisible(false);
+  };
+
+  return (
+    <TapasReasonModal
+      visible={visible}
+      title="取消订单"
+      subtitle="请选择取消此订单的原因"
+      options={cancelReasons}
+      selectedReason={selectedReason}
+      confirmText="确认取消"
+      cancelText="保留订单"
+      onConfirm={handleConfirm}
+      onClose={() => setVisible(false)}
+      onSelectionChange={(reason) => setSelectedReason(reason?.key || '')}
+    />
+  );
+};
+```
+
+### 预选择状态
+
+```tsx
+import React, { useState } from 'react';
+import { TapasReasonModal } from '@beppla/tapas-ui';
+
+const PreselectedDemo = () => {
+  const [visible, setVisible] = useState(false);
+  // 预设选中第二个选项
+  const [selectedReason, setSelectedReason] = useState<string>('2');
+
+  return (
+    <TapasReasonModal
+      visible={visible}
+      title="修改选择"
+      subtitle="您可以修改之前的选择"
+      options={reasons}
+      selectedReason={selectedReason}
+      confirmText="更新"
+      cancelText="取消"
+      onConfirm={handleUpdate}
+      onClose={() => setVisible(false)}
+    />
+  );
+};
+```
+
+### 反馈类型选择
+
+```tsx
+import React from 'react';
+import { TapasReasonModal, ReasonOption } from '@beppla/tapas-ui';
+
+const FeedbackDemo = () => {
+  const feedbackTypes: ReasonOption[] = [
+    { key: 'bug', text: '发现了Bug' },
+    { key: 'feature', text: '功能建议' },
+    { key: 'improvement', text: '改进建议' },
+    { key: 'complaint', text: '投诉问题' },
+    { key: 'praise', text: '表扬赞赏' },
+  ];
+
+  return (
+    <TapasReasonModal
+      title="反馈类型"
+      subtitle="请选择您要提供的反馈类型"
+      options={feedbackTypes}
+      confirmText="继续"
+      cancelText="取消"
+      disableConfirmWhenEmpty={false} // 允许不选择
+      width={400}
+      onConfirm={(reason) => {
+        // 跳转到对应的反馈页面
+        navigateToFeedbackPage(reason.key);
+      }}
+    />
+  );
+};
+```
+
+### 退货原因选择
+
+```tsx
+import React from 'react';
+import { TapasReasonModal, ReasonOption } from '@beppla/tapas-ui';
+
+const ReturnReasonDemo = () => {
+  const returnReasons: ReasonOption[] = [
+    { key: 'defective', text: '商品有缺陷或损坏' },
+    { key: 'not-as-described', text: '与描述不符' },
+    { key: 'wrong-size', text: '尺寸不合适' },
+    { key: 'damaged-shipping', text: '运输过程中损坏' },
+    { key: 'not-needed', text: '不再需要' },
+  ];
+
+  return (
+    <TapasReasonModal
+      title="申请退货"
+      subtitle="请说明您申请退货的原因"
+      options={returnReasons}
+      confirmText="提交申请"
+      cancelText="取消"
+      width={500}
+      onConfirm={(reason) => {
+        // 提交退货申请
+        submitReturnRequest(reason);
+      }}
+    />
+  );
+};
+```
+
+### 紧凑尺寸选择
+
+```tsx
+import React from 'react';
+import { TapasReasonModal, ReasonOption } from '@beppla/tapas-ui';
+
+const CompactDemo = () => {
+  const options: ReasonOption[] = [
+    { key: 'yes', text: '是' },
+    { key: 'no', text: '否' },
+    { key: 'maybe', text: '稍后再说' },
+  ];
+
+  return (
+    <TapasReasonModal
+      title="确认操作"
+      options={options}
+      confirmText="确定"
+      cancelText="取消"
+      width={320} // 紧凑宽度
+      onConfirm={(reason) => {
+        handleConfirmation(reason.key);
+      }}
+    />
+  );
+};
+```
+
+## 回调事件详解
+
+### onSelectionChange
+当用户选择或取消选择某个选项时触发：
+
+```tsx
+<TapasReasonModal
+  onSelectionChange={(reason) => {
+    if (reason) {
+      console.log('用户选择了:', reason.text);
+      // 可以在这里实时更新UI或保存草稿
+    } else {
+      console.log('用户取消了选择');
+    }
+  }}
+/>
+```
+
+### onConfirm
+当用户点击确认按钮时触发：
+
+```tsx
+<TapasReasonModal
+  onConfirm={(reason) => {
+    console.log('确认选择:', reason);
+    // 执行最终的业务逻辑
+    processReason(reason);
+  }}
+/>
+```
+
+### onClose
+当用户点击取消按钮或其他方式关闭模态框时触发：
+
+```tsx
+<TapasReasonModal
+  onClose={() => {
+    console.log('模态框已关闭');
+    setModalVisible(false);
+  }}
+/>
+```
+
+### onRequestClose
+处理系统级的关闭请求（如Android返回键）：
+
+```tsx
+<TapasReasonModal
+  onRequestClose={() => {
+    console.log('系统请求关闭模态框');
+    // 可以在这里处理特殊的关闭逻辑
+    handleSystemClose();
+  }}
+/>
+```
+
+## 自定义样式
+
+组件支持通过 `style` 属性自定义容器样式：
+
+```tsx
+<TapasReasonModal
+  style={{ backgroundColor: 'rgba(0, 0, 0, 0.8)' }}
+  width={600}
+  // 其他props...
+/>
+```
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasReasonModal } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { ReasonModal } from '@beppla/tapas-ui';
+```
+
+## 最佳实践
+
+1. **合理的选项数量**：建议选项数量控制在 3-8 个之间，过多选项考虑分页或搜索
+2. **清晰的文案**：选项文案应该简洁明确，避免歧义
+3. **合适的宽度**：根据文案长度调整模态框宽度，确保良好的阅读体验
+4. **一致的交互**：在应用中保持一致的确认/取消按钮文案和行为
+
+## 使用场景
+
+- 订单取消原因选择
+- 商品退货/退款原因
+- 用户反馈类型选择
+- 调查问卷单选题
+- 设置选项配置
+- 错误报告分类
+
+## 注意事项
+
+1. `options` 数组为空时，组件仍会正常渲染，但不会显示任何选项
+2. 当 `disableConfirmWhenEmpty` 为 `true` 时，未选择任何选项时确认按钮会被禁用
+3. 组件会在显示/隐藏时自动重置选择状态到 `selectedReason` 的值
+4. 支持 React Native 和 React Native Web 环境

package/package/module/ScanButton/README.md

@@ -0,0 +1,72 @@
+# ScanButton
+
+浮动扫描按钮组件，用于快速启动二维码扫描等功能。支持五个定位位置，可自定义文本、图标和颜色，以悬浮按钮形式固定在页面指定位置。
+
+## 功能特性
+
+- ✅ 五种定位位置：bottom-right / bottom-left / top-right / top-left / center
+- ✅ 自定义按钮文本
+- ✅ 自定义图标（TapasIcon 图标名）
+- ✅ 自定义图标大小
+- ✅ 自定义背景色、文字色、图标色
+- ✅ 悬浮定位（position: absolute）
+- ✅ 圆角胶囊按钮样式 + 阴影效果
+- ✅ 主题色适配
+
+## 安装使用
+
+```tsx
+import { ScanButton } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| onPress | `() => void` | - | 按钮点击回调 |
+| text | `string` | `'Scan QR Code'` | 按钮文本 |
+| icon | `string` | `'qr_code_scan'` | 图标名称 |
+| size | `number` | `20` | 图标大小 |
+| position | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'center'` | `'bottom-right'` | 按钮定位位置 |
+| backgroundColor | `string` | 主题 primary | 背景色 |
+| textColor | `string` | 主题 white | 文字颜色 |
+| iconColor | `string` | 主题 white | 图标颜色 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<ScanButton onPress={() => navigation.navigate('Scanner')} />
+```
+
+### 左下角定位
+
+```tsx
+<ScanButton
+  position="bottom-left"
+  onPress={() => handleScan()}
+/>
+```
+
+### 自定义样式
+
+```tsx
+<ScanButton
+  text="Scan Barcode"
+  icon="barcode_scanner"
+  position="top-right"
+  backgroundColor="#895F38"
+  textColor="#FFF"
+  onPress={() => handleBarcodeScan()}
+/>
+```
+
+## 注意事项
+
+- 组件使用 `position: absolute` 定位，需要父容器具备定位上下文
+- 按钮固定高度 40px，圆角 20px（胶囊形状）
+- 文本超长会自动截断（numberOfLines=1, ellipsizeMode=tail）
+- `center` 位置通过负 margin 实现居中，可能需要根据内容宽度调整
+- 需在 `ThemeProvider` 内使用

package/package/module/SearchInput/README.md

@@ -0,0 +1,304 @@
+# TapasSearchInput
+
+一个专门用于搜索的输入组件，内置搜索图标和优化的样式，支持多种回调接口。
+
+## 功能特性
+
+- ✅ 内置搜索图标，点击触发搜索
+- ✅ 支持实时搜索回调
+- ✅ 可自定义尺寸和样式
+- ✅ 圆角设计，适合搜索场景
+- ✅ 支持双回调接口（`onSearch` 和 `attachSearch`）
+- ✅ 向后兼容客户端项目的接口
+- ✅ 支持搜索结果列表显示
+- ✅ 支持搜索历史记录
+- ✅ 支持加载状态显示
+- ✅ 支持自定义占位符（激活/未激活状态）
+- ✅ 支持自定义结果项渲染
+
+## 安装使用
+
+```tsx
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasSearchInput 
+  placeholder="搜索..."
+  onSearch={(text) => console.log('搜索:', text)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `placeholder` | `string` | - | 占位符文本（当未设置 activePlaceholder/inactivePlaceholder 时使用） |
+| `activePlaceholder` | `string` | - | 搜索激活时的占位符 |
+| `inactivePlaceholder` | `string` | - | 搜索未激活时的占位符 |
+| `value` | `string` | - | 输入框的值 |
+| `width` | `number` | `168` | 组件宽度 |
+| `height` | `number` | `40` | 组件高度 |
+| `onSearch` | `(keyword: string) => void` | - | 搜索回调函数（关键词变化时触发） |
+| `attachSearch` | `(val?: string) => void` | - | 搜索回调函数（兼容客户端接口） |
+| `onSelectResult` | `(item: any) => void` | - | 选择搜索结果时的回调 |
+| `onSelectHistory` | `(historyEntry: SearchHistoryEntry) => void` | - | 选择搜索历史时的回调 |
+| `renderResultItem` | `(item: any, index: number, isHistory: boolean) => React.ReactNode` | - | 自定义搜索结果项渲染函数 |
+| `searchResults` | `any[]` | `[]` | 搜索结果数据数组 |
+| `isLoading` | `boolean` | `false` | 搜索加载状态 |
+| `style` | `ViewStyle` | - | 自定义样式 |
+
+## 使用示例
+
+### 基础搜索
+
+```tsx
+import React, { useState } from 'react';
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+const SearchDemo = () => {
+  const [results, setResults] = useState('');
+
+  return (
+    <TapasSearchInput
+      placeholder="输入搜索关键词"
+      onSearch={(text) => {
+        setResults(`搜索结果: ${text}`);
+      }}
+    />
+  );
+};
+```
+
+### 使用 attachSearch（兼容客户端接口）
+
+```tsx
+import React from 'react';
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+const ClientCompatibleSearch = () => {
+  return (
+    <TapasSearchInput
+      placeholder="搜索..."
+      attachSearch={(text) => {
+        // 兼容客户端项目的 attachSearch 接口
+        console.log('客户端搜索:', text);
+      }}
+    />
+  );
+};
+```
+
+### 双回调模式
+
+```tsx
+import React from 'react';
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+const DualCallbackSearch = () => {
+  return (
+    <TapasSearchInput
+      placeholder="搜索..."
+      onSearch={(text) => {
+        console.log('onSearch 触发:', text);
+      }}
+      attachSearch={(text) => {
+        console.log('attachSearch 触发:', text);
+      }}
+    />
+  );
+};
+```
+
+### 自定义尺寸
+
+```tsx
+import React from 'react';
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+const CustomSizeSearch = () => {
+  return (
+    <TapasSearchInput
+      placeholder="大尺寸搜索框"
+      width={300}
+      height={48}
+      onSearch={(text) => console.log('搜索:', text)}
+    />
+  );
+};
+```
+
+### 搜索结果列表
+
+```tsx
+import React, { useState } from 'react';
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+const SearchWithResults = () => {
+  const [results, setResults] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  const handleSearch = (keyword) => {
+    setLoading(true);
+    // 模拟搜索
+    setTimeout(() => {
+      setResults([
+        { id: 1, name: `结果 1: ${keyword}` },
+        { id: 2, name: `结果 2: ${keyword}` },
+      ]);
+      setLoading(false);
+    }, 500);
+  };
+
+  return (
+    <TapasSearchInput
+      placeholder="搜索..."
+      onSearch={handleSearch}
+      searchResults={results}
+      isLoading={loading}
+      onSelectResult={(item) => {
+        console.log('选择了结果:', item);
+      }}
+    />
+  );
+};
+```
+
+### 搜索历史记录
+
+```tsx
+import React, { useState } from 'react';
+import { TapasSearchInput, SearchHistoryEntry } from '@beppla/tapas-ui';
+
+const SearchWithHistory = () => {
+  const [history, setHistory] = useState<SearchHistoryEntry[]>([
+    { id: 1, keyword: 'React Native', timestamp: Date.now() },
+    { id: 2, keyword: 'TypeScript', timestamp: Date.now() },
+  ]);
+
+  return (
+    <TapasSearchInput
+      placeholder="搜索..."
+      searchResults={history}
+      onSelectHistory={(entry) => {
+        console.log('选择了历史:', entry.keyword);
+      }}
+    />
+  );
+};
+```
+
+### 自定义占位符
+
+```tsx
+import React from 'react';
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+const CustomPlaceholder = () => {
+  return (
+    <TapasSearchInput
+      activePlaceholder="正在搜索..."
+      inactivePlaceholder="请输入关键词"
+      onSearch={(keyword) => console.log('搜索:', keyword)}
+    />
+  );
+};
+```
+
+### 自定义结果项渲染
+
+```tsx
+import React from 'react';
+import { TapasSearchInput, View, Text } from '@beppla/tapas-ui';
+
+const CustomRender = () => {
+  const results = [
+    { id: 1, title: '结果 1', description: '这是结果 1 的描述' },
+    { id: 2, title: '结果 2', description: '这是结果 2 的描述' },
+  ];
+
+  return (
+    <TapasSearchInput
+      placeholder="搜索..."
+      searchResults={results}
+      renderResultItem={(item, index, isHistory) => (
+        <View style={{ padding: 16, borderBottomWidth: 1 }}>
+          <Text style={{ fontWeight: 'bold' }}>{item.title}</Text>
+          <Text style={{ color: '#666', marginTop: 4 }}>{item.description}</Text>
+        </View>
+      )}
+    />
+  );
+};
+```
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasSearchInput } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { SearchInput } from '@beppla/tapas-ui';
+```
+
+## 样式定制
+
+组件使用 `makeStyles` 创建样式，可以通过传入 `style` 属性来覆盖默认样式：
+
+```tsx
+<TapasSearchInput
+  style={{ margin: 10 }}
+  placeholder="自定义样式搜索框"
+  onSearch={handleSearch}
+/>
+```
+
+## 类型定义
+
+```tsx
+/**
+ * 搜索历史记录项类型
+ */
+export interface SearchHistoryEntry {
+  id?: string | number;
+  keyword: string;
+  timestamp?: number;
+  [key: string]: any;
+}
+
+export interface SearchInputProps extends ViewProps {
+  placeholder?: string;
+  activePlaceholder?: string;  // 搜索激活时的占位符
+  inactivePlaceholder?: string;  // 搜索未激活时的占位符
+  value?: string;
+  height?: number;
+  width?: number;
+  onSearch?: (keyword: string) => void;  // 搜索回调（必需 keyword 参数）
+  attachSearch?: (val?: string) => void;  // 兼容旧接口
+  onSelectResult?: (item: any) => void;  // 选择结果回调
+  onSelectHistory?: (historyEntry: SearchHistoryEntry) => void;  // 选择历史回调
+  renderResultItem?: (item: any, index: number, isHistory: boolean) => React.ReactNode;  // 自定义渲染
+  searchResults?: any[];  // 搜索结果数据
+  isLoading?: boolean;  // 加载状态
+}
+```
+
+## 使用场景
+
+- 页面顶部搜索栏
+- 列表过滤搜索
+- 数据查找输入框
+- 客户端项目迁移（使用 `attachSearch` 接口）
+
+## 注意事项
+
+1. 当同时提供 `onSearch` 和 `attachSearch` 时，两个回调都会被触发
+2. 组件会自动处理搜索图标的点击事件
+3. 输入框的实际宽度会比设置的 `width` 小 56px（为搜索图标留空间）
+4. 组件支持 React Native 和 React Native Web 环境
+5. `onSearch` 回调的参数类型已更新为 `(keyword: string)`，不再支持可选参数（向后兼容通过 `attachSearch` 保持）
+6. 搜索结果列表会在输入框获得焦点且有搜索结果时自动显示
+7. 移动端使用 Modal 显示结果列表，桌面端使用绝对定位
+8. 历史记录项需要包含 `keyword` 字段才会被识别为历史记录