@beppla/tapas-ui 1.1.0 → 1.1.2

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` 管理内部状态
+- 支持受控和非受控模式
+- 自动边界检查和约束
+- 响应式按钮状态管理
+- 完整的类型安全支持
+- 主题集成和样式自定义

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 环境