@beppla/tapas-ui 1.5.13 → 1.5.15

package/package/module/Popover/Popover.js

@@ -0,0 +1,159 @@
+"use strict";
+
+import React from 'react';
+import { View } from 'react-native';
+import { makeStyles, withTheme } from '@rneui/themed';
+import Icon from '../Icons/TapasIcon';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const useStyles = makeStyles(theme => ({
+  container: {
+    position: 'absolute',
+    backgroundColor: theme.colors.white,
+    borderRadius: theme.radius.rounded,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 0,
+      height: 12
+    },
+    shadowOpacity: 0.58,
+    shadowRadius: 24,
+    elevation: 8,
+    zIndex: 9999
+  },
+  arrow: {
+    position: 'absolute',
+    color: theme.colors.white,
+    width: 12,
+    height: 27
+  },
+  arrowTop: {
+    top: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 0,
+      height: -2
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  arrowBottom: {
+    bottom: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 0,
+      height: 2
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  arrowLeft: {
+    left: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: -2,
+      height: 0
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  arrowRight: {
+    right: -6,
+    shadowColor: theme.colors.grey4,
+    shadowOffset: {
+      width: 2,
+      height: 0
+    },
+    shadowOpacity: 0.3,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  content: {
+    flex: 1,
+    borderRadius: theme.radius.rounded,
+    overflow: 'hidden'
+  }
+}));
+const Popover = ({
+  isVisible,
+  children,
+  position = 'bottom',
+  arrowPosition = 'center',
+  width = 392,
+  height = 696,
+  containerStyle,
+  contentStyle,
+  ...props
+}) => {
+  const styles = useStyles(props);
+  if (!isVisible) return null;
+  const getArrowStyle = () => {
+    let arrowPositionStyle = {};
+    switch (position) {
+      case 'top':
+        arrowPositionStyle = styles.arrowTop;
+        break;
+      case 'bottom':
+        arrowPositionStyle = styles.arrowBottom;
+        break;
+      case 'left':
+        arrowPositionStyle = styles.arrowLeft;
+        break;
+      case 'right':
+        arrowPositionStyle = styles.arrowRight;
+        break;
+    }
+
+    // 根据箭头位置调整left/top值
+    const positionStyle = {};
+    if (position === 'top' || position === 'bottom') {
+      switch (arrowPosition) {
+        case 'start':
+          positionStyle.left = 20;
+          break;
+        case 'center':
+          positionStyle.left = width / 2 - 6;
+          break;
+        case 'end':
+          positionStyle.right = 20;
+          break;
+      }
+    } else {
+      switch (arrowPosition) {
+        case 'start':
+          positionStyle.top = 20;
+          break;
+        case 'center':
+          positionStyle.top = height / 2 - 6;
+          break;
+        case 'end':
+          positionStyle.bottom = 20;
+          break;
+      }
+    }
+    return {
+      ...styles.arrow,
+      ...arrowPositionStyle,
+      ...positionStyle
+    };
+  };
+  return /*#__PURE__*/_jsxs(View, {
+    style: [styles.container, {
+      width,
+      height
+    }, containerStyle],
+    testID: "popover",
+    children: [/*#__PURE__*/_jsx(Icon, {
+      name: "left_arrow",
+      size: 17,
+      style: getArrowStyle()
+    }), /*#__PURE__*/_jsx(View, {
+      style: [styles.content, contentStyle],
+      children: children
+    })]
+  });
+};
+export default withTheme(Popover);
+//# sourceMappingURL=Popover.js.map

package/package/module/Popover/Popover.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","View","makeStyles","withTheme","Icon","jsx","_jsx","jsxs","_jsxs","useStyles","theme","container","position","backgroundColor","colors","white","borderRadius","radius","rounded","shadowColor","grey4","shadowOffset","width","height","shadowOpacity","shadowRadius","elevation","zIndex","arrow","color","arrowTop","top","arrowBottom","bottom","arrowLeft","left","arrowRight","right","content","flex","overflow","Popover","isVisible","children","arrowPosition","containerStyle","contentStyle","props","styles","getArrowStyle","arrowPositionStyle","positionStyle","style","testID","name","size"],"sourceRoot":"../../../components","sources":["Popover/Popover.tsx"],"mappings":"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","ignoreList":[]}

package/package/module/Popover/README.md

@@ -0,0 +1,82 @@
+# Popover
+
+气泡弹出层组件，用于显示与触发元素相对定位的内容面板。支持四个方向（top/bottom/left/right）和三种箭头位置（start/center/end），适合工具提示、操作菜单等场景。
+
+## 功能特性
+
+- ✅ 四个弹出方向：top、bottom、left、right
+- ✅ 三种箭头位置：start、center、end
+- ✅ 自定义宽高尺寸
+- ✅ 带阴影的浮层效果（elevation: 8）
+- ✅ 箭头自动跟随方向和位置调整
+- ✅ 通过 isVisible 控制显隐
+- ✅ 支持自定义容器和内容区样式
+- ✅ 主题色适配（withTheme HOC）
+
+## 安装使用
+
+```tsx
+import { Popover } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| isVisible | `boolean` | - | 是否显示（必填） |
+| children | `React.ReactNode` | - | 弹出层内容 |
+| position | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 弹出方向 |
+| arrowPosition | `'start' \| 'center' \| 'end'` | `'center'` | 箭头在边上的位置 |
+| width | `number` | `392` | 弹出层宽度 |
+| height | `number` | `696` | 弹出层高度 |
+| containerStyle | `StyleProp<ViewStyle>` | - | 外层容器样式 |
+| contentStyle | `StyleProp<ViewStyle>` | - | 内容区域样式 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const [isVisible, setIsVisible] = useState(false);
+
+<Button onPress={() => setIsVisible(true)}>Show Popover</Button>
+<Popover isVisible={isVisible} position="bottom">
+  <Text>Popover content here</Text>
+</Popover>
+```
+
+### 左侧弹出 + 箭头末端
+
+```tsx
+<Popover
+  isVisible={isVisible}
+  position="left"
+  arrowPosition="end"
+  width={392}
+  height={396}
+>
+  <Text>Left popover with end arrow</Text>
+</Popover>
+```
+
+### 自定义尺寸
+
+```tsx
+<Popover
+  isVisible={isVisible}
+  position="top"
+  arrowPosition="start"
+  width={280}
+  height={200}
+>
+  <Text>Compact popover</Text>
+</Popover>
+```
+
+## 注意事项
+
+- 组件使用 `position: absolute` 定位，需要父容器提供合适的定位上下文
+- `isVisible` 为 `false` 时组件返回 `null`，不占据布局空间
+- 箭头使用 TapasIcon 的 `left_arrow` 图标，通过旋转适配不同方向
+- `arrowPosition` 的 `center` 值根据 `width` 或 `height` 自动计算居中位置
+- 需在 `ThemeProvider` 内使用

package/package/module/Progress/README.md

@@ -0,0 +1,106 @@
+# Progress
+
+进度条组件，用于显示文件上传或图片处理等任务的进度状态。支持 image 和 file 两种布局类型，可展示进行中（progress）、完成（done）和失败（failed）三种状态。
+
+## 功能特性
+
+- ✅ 两种展示类型：image（图片进度条）和 file（文件进度条）
+- ✅ 三种状态：progress（进行中）、done（完成）、failed（失败）
+- ✅ 状态自动匹配图标和颜色（success / error）
+- ✅ 自定义起始和结束内容区域（支持 ReactNode）
+- ✅ 进度百分比展示
+- ✅ file 类型支持文件名展示
+- ✅ 主题色适配
+- ✅ React.memo 优化渲染性能
+
+## 安装使用
+
+```tsx
+import { Progress } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| type | `'image' \| 'file'` | - | 展示类型（必填） |
+| data | `ProgressData` | - | 进度数据（必填） |
+| testID | `string` | - | 测试标识 |
+
+### ProgressData
+
+```tsx
+interface ProgressData {
+  start: React.ReactNode | string;   // 左侧内容（如缩略图、图标）
+  end?: React.ReactNode | string;    // 右侧内容（状态文本）
+  status: 'progress' | 'done' | 'failed';  // 当前状态
+  progress?: number;                  // 进度值（0-100）
+  file?: string;                      // 文件名（file 类型使用）
+}
+```
+
+## 使用示例
+
+### 图片上传进度
+
+```tsx
+<Progress
+  type="image"
+  data={{
+    start: <Image source={{ uri: thumbnail }} style={{ width: 40, height: 40 }} />,
+    status: 'progress',
+    progress: 65,
+  }}
+/>
+```
+
+### 上传完成
+
+```tsx
+<Progress
+  type="image"
+  data={{
+    start: <Image source={{ uri: thumbnail }} style={{ width: 40, height: 40 }} />,
+    status: 'done',
+    end: 'Uploaded',
+  }}
+/>
+```
+
+### 文件上传
+
+```tsx
+<Progress
+  type="file"
+  data={{
+    start: <TapasIcon name="file" size={20} />,
+    file: 'document.pdf',
+    status: 'progress',
+    progress: 42,
+  }}
+/>
+```
+
+### 上传失败
+
+```tsx
+<Progress
+  type="file"
+  data={{
+    start: <TapasIcon name="file" size={20} />,
+    file: 'report.xlsx',
+    status: 'failed',
+    end: 'Upload failed',
+  }}
+/>
+```
+
+## 注意事项
+
+- `data` 为 null 或 undefined 时组件返回 null
+- `image` 类型为左右布局，进度条位于中间
+- `file` 类型为上下布局，文件名在上方，进度条在下方
+- `end` 属性不存在时，默认显示 `progress%` 文本
+- 进度条宽度通过 CSS `width: ${progress}%` 实现
+- 使用 `withTheme` + `React.memo` 双重优化
+- 需在 `ThemeProvider` 内使用

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

@@ -0,0 +1,85 @@
+# RadioButton
+
+单选按钮组件，用于在一组选项中选择一个值。采用圆形指示器和文字标签的经典单选样式。
+
+## 功能特性
+
+- ✅ 支持多个选项的单选功能
+- ✅ 受控模式，通过 selected 属性指定默认选中项
+- ✅ 自动跟踪外部 selected 属性变化
+- ✅ 圆形选中指示器，使用主题色渲染
+- ✅ 垂直排列布局，每个选项固定高度 40px
+- ✅ 使用 React.memo 优化渲染性能
+- ✅ 支持 testID 属性用于测试
+
+## 安装使用
+
+```tsx
+import RadioButton from '@beppla/tapas-ui/components/RadioButton/RadioButton';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| options | `Option[]` | - | 选项列表 |
+| onPress | `(option: Option) => void` | - | 选中回调，返回被选中的选项 |
+| selected | `string` | `""` | 默认选中项的 key 值 |
+| testID | `string` | - | 测试标识 |
+
+### Option 数据类型
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| key | `string` | 选项唯一标识 |
+| text | `string` | 选项显示文字 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<RadioButton
+  options={[
+    { key: 'a', text: '选项 A' },
+    { key: 'b', text: '选项 B' },
+    { key: 'c', text: '选项 C' },
+  ]}
+  onPress={(option) => console.log('选中:', option.key)}
+/>
+```
+
+### 指定默认选中
+
+```tsx
+<RadioButton
+  options={[
+    { key: 'male', text: '男' },
+    { key: 'female', text: '女' },
+  ]}
+  selected="male"
+  onPress={(option) => setGender(option.key)}
+/>
+```
+
+### 受控模式
+
+```tsx
+const [selected, setSelected] = useState('option1');
+
+<RadioButton
+  options={[
+    { key: 'option1', text: '立即配送' },
+    { key: 'option2', text: '预约配送' },
+  ]}
+  selected={selected}
+  onPress={(option) => setSelected(option.key)}
+/>
+```
+
+## 注意事项
+
+- 组件通过 `withTheme` HOC 注入主题，圆形指示器颜色使用 `theme.colors.primary`
+- 选项文字颜色也使用主题主色，与指示器保持一致
+- 组件不支持禁用单个选项，如需此功能需自行扩展
+- `selected` 属性变化时会自动同步内部状态