@beppla/tapas-ui 1.5.10 → 1.5.11

package/package/module/Steps/README.md

@@ -0,0 +1,76 @@
+# Steps
+
+步骤条组件，用于展示多步骤流程的当前进度。步骤编号以圆形展示，已完成步骤显示对勾图标，步骤之间以连接线相连，支持点击已完成和当前步骤进行导航。
+
+## 功能特性
+
+- ✅ 多步骤流程展示
+- ✅ 三种步骤状态：完成（对勾图标）、当前（高亮）、待完成（灰色编号）
+- ✅ 步骤间连接线颜色跟随状态变化
+- ✅ 支持点击已完成/当前步骤进行导航
+- ✅ 待完成步骤不可点击
+- ✅ 横向排列布局
+- ✅ 主题色适配（品牌色高亮）
+- ✅ React.memo 优化性能
+
+## 安装使用
+
+```tsx
+import { Steps } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| steps | `{ title: string; description?: string }[]` | `[]` | 步骤配置数组（必填） |
+| currentStep | `number` | - | 当前步骤索引，从 0 开始（必填） |
+| onPressStep | `(step: number) => void` | - | 步骤点击回调，参数为步骤编号（从 1 开始）（必填） |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const steps = [
+  { title: 'Step 1' },
+  { title: 'Step 2' },
+  { title: 'Step 3' },
+];
+
+<Steps
+  steps={steps}
+  currentStep={1}
+  onPressStep={(step) => console.log('Navigate to step:', step)}
+/>
+```
+
+### 全部完成
+
+```tsx
+<Steps
+  steps={[{ title: 'Info' }, { title: 'Payment' }, { title: 'Done' }]}
+  currentStep={3}
+  onPressStep={handleStepPress}
+/>
+```
+
+### 第一步
+
+```tsx
+<Steps
+  steps={[{ title: 'Cart' }, { title: 'Checkout' }, { title: 'Confirm' }]}
+  currentStep={0}
+  onPressStep={handleStepPress}
+/>
+```
+
+## 注意事项
+
+- `currentStep` 从 0 开始索引，0 表示第一步为当前步骤
+- `onPressStep` 回调参数为步骤编号（从 1 开始），与界面展示一致
+- 仅已完成和当前步骤可点击，待完成步骤点击无响应
+- 步骤圆形尺寸固定 28x28，连接线宽度 76px
+- `title` 和 `description` 在当前实现中仅用于数据传递，界面展示为编号/对勾
+- 需在 `ThemeProvider` 内使用

package/package/module/Tab/README.md

@@ -0,0 +1,161 @@
+# TapasTab
+
+Tab 标签页组件，扩展 `@rneui/themed` 的 Tab 组件，新增 `content` 宽度模式，支持根据标签文本内容自适应宽度，而非默认的平分容器宽度。
+
+## 功能特性
+
+- 两种宽度模式：`fill`（平分容器宽度）和 `content`（内容自适应宽度）
+- `content` 模式下自动启用水平滚动（`scrollable`）
+- 可配置标签最小宽度（`minTabWidth`）和最大宽度（`maxTabWidth`）
+- 可配置内容模式下的水平内边距（`contentPadding`）
+- 底部分隔线显示控制和颜色自定义
+- 文本超出时自动省略号处理（Web 端 `text-overflow: ellipsis`）
+- 完全兼容 `@rneui/themed` Tab 的所有原生属性
+- `TapasTab.Item` 直接复用 `@rneui Tab.Item`
+
+## 安装使用
+
+```tsx
+import { TapasTab } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| value | `number` | - | 当前选中标签索引（受控，必填） |
+| onChange | `(value: number) => void` | - | 标签切换回调（必填） |
+| widthMode | `'fill' \| 'content'` | `'fill'` | 宽度模式 |
+| minTabWidth | `number` | - | content 模式下标签最小宽度（像素） |
+| maxTabWidth | `number` | - | content 模式下标签最大宽度（像素） |
+| contentPadding | `number` | `16` | content 模式下标签水平内边距 |
+| showDivider | `boolean` | `true` | 是否显示底部分隔线（仅 content 模式） |
+| dividerColor | `string` | `'#e0e0e0'` | 底部分隔线颜色 |
+| containerStyle | `StyleProp<ViewStyle>` | - | 容器自定义样式 |
+| buttonStyle | `StyleProp<ViewStyle>` | - | 按钮自定义样式 |
+| indicatorStyle | `StyleProp<ViewStyle>` | - | 指示器自定义样式 |
+| titleStyle | `StyleProp<TextStyle>` | - | 标题文本自定义样式 |
+| children | `React.ReactElement<TabItemProps>[]` | - | TapasTab.Item 子组件 |
+
+## 使用示例
+
+### 基础平分模式（默认）
+
+```tsx
+import { TapasTab } from '@beppla/tapas-ui';
+import { useState } from 'react';
+
+export default function App() {
+  const [index, setIndex] = useState(0);
+
+  return (
+    <TapasTab value={index} onChange={setIndex}>
+      <TapasTab.Item title="Tab 1" />
+      <TapasTab.Item title="Tab 2" />
+      <TapasTab.Item title="Tab 3" />
+    </TapasTab>
+  );
+}
+```
+
+### 内容自适应模式
+
+```tsx
+<TapasTab value={index} onChange={setIndex} widthMode="content">
+  <TapasTab.Item title="Short" />
+  <TapasTab.Item title="Medium Length" />
+  <TapasTab.Item title="This is a very long tab label" />
+</TapasTab>
+```
+
+### 带最小/最大宽度控制
+
+```tsx
+<TapasTab
+  value={index}
+  onChange={setIndex}
+  widthMode="content"
+  minTabWidth={80}
+  maxTabWidth={180}
+>
+  <TapasTab.Item title="Short" />
+  <TapasTab.Item title="Medium" />
+  <TapasTab.Item title="Very long label text here" />
+</TapasTab>
+```
+
+### 自定义内边距
+
+```tsx
+<TapasTab
+  value={index}
+  onChange={setIndex}
+  widthMode="content"
+  contentPadding={30}
+>
+  <TapasTab.Item title="Home" />
+  <TapasTab.Item title="Products" />
+  <TapasTab.Item title="Orders" />
+</TapasTab>
+```
+
+### 实际应用场景（商品管理导航）
+
+```tsx
+import { TapasTab } from '@beppla/tapas-ui';
+import { useState } from 'react';
+import { View, Text } from 'react-native';
+
+const tabs = ['All', 'Pending', 'Published', 'Unpublished', 'Low Stock'];
+
+export default function ProductTabs() {
+  const [index, setIndex] = useState(0);
+
+  return (
+    <View>
+      <TapasTab
+        value={index}
+        onChange={setIndex}
+        widthMode="content"
+        minTabWidth={60}
+        contentPadding={20}
+      >
+        {tabs.map((tab, i) => (
+          <TapasTab.Item key={i} title={tab} />
+        ))}
+      </TapasTab>
+      <View style={{ padding: 16 }}>
+        <Text>{tabs[index]} content here</Text>
+      </View>
+    </View>
+  );
+}
+```
+
+### 自定义样式
+
+```tsx
+<TapasTab
+  value={index}
+  onChange={setIndex}
+  widthMode="fill"
+  containerStyle={{ backgroundColor: '#f5f5f5' }}
+  buttonStyle={{ paddingVertical: 12 }}
+  titleStyle={{ fontSize: 14, fontWeight: '600' }}
+  indicatorStyle={{ backgroundColor: '#1976d2', height: 3 }}
+>
+  <TapasTab.Item title="Tab 1" />
+  <TapasTab.Item title="Tab 2" />
+</TapasTab>
+```
+
+## 注意事项
+
+- `fill` 模式（默认）将标签平均分配容器宽度，与原生 `@rneui Tab` 行为一致
+- `content` 模式根据文本内容动态调整每个标签宽度，自动启用水平滚动
+- `minTabWidth` 和 `maxTabWidth` 仅在 `widthMode='content'` 时生效
+- `content` 模式下，`buttonStyle` 和 `titleStyle` 会自动注入到每个 `TapasTab.Item`
+- `showDivider` 仅在 `content` 模式下生效，通过外层 View 的 `borderBottomWidth` 实现
+- 在 `content` 模式下，文本自动设置为不换行（Web `whiteSpace: nowrap`）并显示省略号
+- `TapasTab.Item` 是 `@rneui Tab.Item` 的直接引用，支持所有 `TabItemProps`
+- `containerStyle` 在 `content` 模式下会自动追加 `width: '100%'`

package/package/module/TabTitle/README.md

@@ -0,0 +1,399 @@
+# TapasTabTitle
+
+一个专用于Tab标题的组件，支持文本显示和可选的通知指示器，适用于标签导航、页面标题和需要状态提示的场景。
+
+## 功能特性
+
+- ✅ 清晰的文本显示，支持自动截断
+- ✅ 可选的通知指示器（红点提示）
+- ✅ 可自定义指示器颜色、大小和位置
+- ✅ 灵活的文本样式配置
+- ✅ 完整的可访问性支持
+- ✅ 向后兼容的导出别名
+- ✅ 主题集成，自动适配应用主题
+
+## 安装使用
+
+```tsx
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasTabTitle text="Home" />
+
+// 带通知指示器
+<TapasTabTitle 
+  text="Messages" 
+  showIndicator={true}
+  indicatorColor="#FF4444"
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `text` | `string` | - | 显示的文本内容 |
+| `showIndicator` | `boolean` | `false` | 是否显示通知指示器 |
+| `indicatorColor` | `string` | `"#FF4444"` | 指示器颜色 |
+| `indicatorSize` | `number` | `5` | 指示器大小（像素） |
+| `textStyle` | `StyleProp<TextStyle>` | - | 自定义文本样式 |
+| `textProps` | `Partial<TextProps>` | - | 传递给Text组件的属性 |
+| `indicatorOffset` | `{top?: number, right?: number}` | `{top: 0, right: -8}` | 指示器相对文本的偏移位置 |
+| `style` | `StyleProp<ViewStyle>` | - | 容器样式 |
+
+## 使用示例
+
+### 基础文本显示
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const BasicExample = () => {
+  return (
+    <TapasTabTitle text="Home" />
+  );
+};
+```
+
+### 带通知指示器
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const WithIndicatorExample = () => {
+  return (
+    <TapasTabTitle 
+      text="Messages" 
+      showIndicator={true}
+      indicatorColor="#FF4444"
+    />
+  );
+};
+```
+
+### Tab导航示例
+
+```tsx
+import React, { useState } from 'react';
+import { View, TouchableOpacity } from 'react-native';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const TabNavigationExample = () => {
+  const [activeTab, setActiveTab] = useState(0);
+  
+  const tabs = [
+    { title: 'Home', hasNotification: false },
+    { title: 'Messages', hasNotification: true },
+    { title: 'Notifications', hasNotification: true },
+    { title: 'Settings', hasNotification: false },
+  ];
+
+  return (
+    <View style={{ flexDirection: 'row' }}>
+      {tabs.map((tab, index) => (
+        <TouchableOpacity 
+          key={index}
+          style={{
+            flex: 1,
+            padding: 12,
+            backgroundColor: activeTab === index ? '#E3F2FD' : 'transparent',
+          }}
+          onPress={() => setActiveTab(index)}
+        >
+          <TapasTabTitle
+            text={tab.title}
+            showIndicator={tab.hasNotification}
+            textStyle={{
+              color: activeTab === index ? '#007AFF' : '#8E8E93',
+              fontWeight: activeTab === index ? 'bold' : 'normal',
+            }}
+          />
+        </TouchableOpacity>
+      ))}
+    </View>
+  );
+};
+```
+
+### 自定义指示器样式
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const CustomIndicatorExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 不同颜色的指示器 */}
+      <TapasTabTitle 
+        text="Alerts" 
+        showIndicator={true}
+        indicatorColor="#FF9500"
+        indicatorSize={6}
+      />
+      
+      {/* 绿色指示器 */}
+      <TapasTabTitle 
+        text="Updates" 
+        showIndicator={true}
+        indicatorColor="#00C851"
+        indicatorSize={8}
+      />
+      
+      {/* 大尺寸指示器 */}
+      <TapasTabTitle 
+        text="Important" 
+        showIndicator={true}
+        indicatorColor="#FF4444"
+        indicatorSize={12}
+      />
+    </View>
+  );
+};
+```
+
+### 自定义指示器位置
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const CustomPositionExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 默认位置 */}
+      <TapasTabTitle 
+        text="Default Position" 
+        showIndicator={true}
+        indicatorOffset={{ top: 0, right: -8 }}
+      />
+      
+      {/* 右上角 */}
+      <TapasTabTitle 
+        text="Top Right Corner" 
+        showIndicator={true}
+        indicatorOffset={{ top: -2, right: -2 }}
+      />
+      
+      {/* 远离文本 */}
+      <TapasTabTitle 
+        text="Far Right" 
+        showIndicator={true}
+        indicatorOffset={{ top: 0, right: -15 }}
+      />
+      
+      {/* 偏下位置 */}
+      <TapasTabTitle 
+        text="Lower Position" 
+        showIndicator={true}
+        indicatorOffset={{ top: 5, right: -8 }}
+      />
+    </View>
+  );
+};
+```
+
+### 自定义文本样式
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const CustomTextExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 大号文字 */}
+      <TapasTabTitle 
+        text="Large Text" 
+        showIndicator={true}
+        textStyle={{
+          fontSize: 20,
+          fontWeight: 'bold',
+          color: '#0066CC',
+        }}
+      />
+      
+      {/* 自定义颜色和字体 */}
+      <TapasTabTitle 
+        text="Custom Style" 
+        showIndicator={true}
+        textStyle={{
+          fontSize: 16,
+          fontWeight: '500',
+          color: '#8B5CF6',
+          letterSpacing: 0.5,
+        }}
+        indicatorColor="#8B5CF6"
+      />
+    </View>
+  );
+};
+```
+
+### 长文本处理
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const LongTextExample = () => {
+  return (
+    <View style={{ width: 150 }}>
+      <TapasTabTitle 
+        text="Very Long Tab Title That Will Be Truncated"
+        showIndicator={true}
+        textProps={{
+          numberOfLines: 1,
+          ellipsizeMode: 'tail'
+        }}
+      />
+    </View>
+  );
+};
+```
+
+### 动态通知状态
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+import { TapasButton } from '@beppla/tapas-ui';
+
+const DynamicNotificationExample = () => {
+  const [hasNotification, setHasNotification] = useState(false);
+
+  return (
+    <View style={{ alignItems: 'center', gap: 16 }}>
+      <TapasTabTitle 
+        text="Dynamic Notification" 
+        showIndicator={hasNotification}
+        indicatorColor="#FF4444"
+      />
+      
+      <TapasButton
+        title={hasNotification ? "Clear Notification" : "Add Notification"}
+        onPress={() => setHasNotification(!hasNotification)}
+      />
+    </View>
+  );
+};
+```
+
+### 可访问性支持
+
+```tsx
+import React from 'react';
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+const AccessibilityExample = () => {
+  return (
+    <TapasTabTitle 
+      text="Accessible Tab"
+      showIndicator={true}
+      accessible={true}
+      accessibilityRole="tab"
+      accessibilityState={{ selected: true }}
+      accessibilityLabel="Home tab with notifications"
+      accessibilityHint="Double tap to open home section"
+    />
+  );
+};
+```
+
+## 指示器配置详解
+
+### 颜色选择
+- **红色 (#FF4444)**: 用于重要通知、错误提示
+- **橙色 (#FF9500)**: 用于警告、待处理事项
+- **绿色 (#00C851)**: 用于成功状态、完成提示
+- **蓝色 (#007AFF)**: 用于信息提示、一般通知
+- **紫色 (#AF52DE)**: 用于特殊状态、VIP提示
+
+### 尺寸建议
+- **小尺寸 (3-4px)**: 适用于密集布局、小字体
+- **标准尺寸 (5-6px)**: 适用于大多数场景
+- **中等尺寸 (8-10px)**: 适用于需要突出显示的场景
+- **大尺寸 (12px+)**: 适用于重要提示、显著标记
+
+### 位置配置
+```tsx
+// 默认位置（文本右上角稍微偏右）
+indicatorOffset={{ top: 0, right: -8 }}
+
+// 紧贴右上角
+indicatorOffset={{ top: -2, right: -2 }}
+
+// 远离文本
+indicatorOffset={{ top: 0, right: -15 }}
+
+// 垂直居中
+indicatorOffset={{ top: 8, right: -8 }}
+```
+
+## 主题集成
+
+组件会自动使用应用主题的以下属性：
+
+```tsx
+// 文本样式
+fontSize: theme.fonts?.sizeM || 16
+fontWeight: "600"
+color: theme.colors.colorTextPrimary || theme.colors.primary
+
+// 容器样式
+alignItems: "flex-start"
+justifyContent: "center"
+```
+
+可以通过 `textStyle` 覆盖默认主题样式：
+
+```tsx
+<TapasTabTitle 
+  text="Custom Theme"
+  textStyle={{
+    fontSize: 18,
+    color: '#custom-color',
+    fontFamily: 'custom-font'
+  }}
+/>
+```
+
+## 最佳实践
+
+1. **文本长度控制**: 保持Tab标题简洁，一般不超过10个字符
+2. **指示器颜色**: 在应用中保持一致的颜色语义
+3. **通知及时清除**: 提供清除通知的机制，避免永久显示
+4. **可访问性**: 为指示器提供合适的可访问性描述
+5. **响应式设计**: 在不同屏幕尺寸下测试显示效果
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasTabTitle } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { TabTitle } from '@beppla/tapas-ui';
+```
+
+## 使用场景
+
+- Tab导航栏标题
+- 页面section标题
+- 菜单项标签
+- 状态指示标签
+- 通知提示文本
+- 分类标签
+
+## 注意事项
+
+1. 指示器位置基于文本元素的相对定位，确保父容器有足够空间
+2. 长文本会自动截断，建议设置合适的容器宽度
+3. 指示器颜色应该与应用整体色彩方案保持一致
+4. 在深色主题下，注意指示器颜色的对比度
+5. 组件支持React Native和React Native Web环境