@beppla/tapas-ui 1.5.10 → 1.5.12

package/package/module/Header/README.md

@@ -0,0 +1,109 @@
+# Header
+
+应用页眉组件，提供顶部导航栏功能，包含标题显示、左侧菜单/返回按钮、搜索框和用户头像。自动适配桌面端和移动端的不同展示形式。
+
+## 功能特性
+
+- 自适应响应式设计（桌面端和移动端标题字号、搜索框形态自动切换）
+- 支持左侧菜单按钮（`showLeftIcon`）和返回按钮（`hasBack`）
+- 桌面端搜索框为完整输入框（168px），移动端为圆形搜索图标
+- 用户头像显示（圆形 Avatar）并支持点击事件
+- 标题长文本自动省略号处理（桌面端 `text-overflow: ellipsis`）
+- 搜索文本变化实时回调
+- 可自定义左侧图标名称
+- 固定高度 72px
+
+## 安装使用
+
+```tsx
+import { Header } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | - | 页眉标题文本 |
+| hasBack | `boolean` | `false` | 是否显示返回按钮 |
+| showLeftIcon | `boolean` | `false` | 是否显示左侧菜单按钮 |
+| leftIcon | `string` | `'menu'` | 左侧图标名称 |
+| onLeftIconPress | `() => void` | - | 左侧按钮/返回按钮点击回调 |
+| backIconStyle | `any` | - | 返回按钮图标自定义样式 |
+| isShowSearch | `boolean` | `false` | 是否显示搜索框 |
+| searchPlaceholderText | `string` | - | 搜索框占位符文本 |
+| searchOnChangeText | `(text: string) => void` | - | 搜索文本变化回调 |
+| avatarSource | `string` | - | 头像图片 URI |
+| avatarOnPress | `() => void` | - | 头像点击回调 |
+| headerContainerStyle | `StyleProp<ViewStyle>` | - | 容器自定义样式 |
+| theme | `any` | - | 主题对象（自动注入） |
+
+> Header 继承 `@rneui/themed` 的 `HeaderProps`，支持所有 RNE Header 原生属性。
+
+## 使用示例
+
+### 基础标题
+
+```tsx
+<Header title="Home" />
+```
+
+### 带返回按钮
+
+```tsx
+<Header
+  title="Order Details"
+  hasBack={true}
+  onLeftIconPress={() => navigation.goBack()}
+/>
+```
+
+### 带菜单按钮
+
+```tsx
+<Header
+  title="Dashboard"
+  showLeftIcon={true}
+  leftIcon="menu"
+  onLeftIconPress={() => toggleNav()}
+/>
+```
+
+### 完整功能（搜索 + 头像）
+
+```tsx
+<Header
+  title="Products"
+  showLeftIcon={true}
+  isShowSearch={true}
+  searchPlaceholderText="Search products..."
+  searchOnChangeText={(text) => handleSearch(text)}
+  avatarSource="https://randomuser.me/api/portraits/men/36.jpg"
+  avatarOnPress={() => alert('Avatar clicked')}
+  onLeftIconPress={() => alert('Menu clicked')}
+/>
+```
+
+### 自定义容器样式
+
+```tsx
+<Header
+  title="Custom Styled Header"
+  hasBack={true}
+  onLeftIconPress={() => goBack()}
+  headerContainerStyle={{
+    backgroundColor: '#1a1a1a',
+    paddingHorizontal: 20,
+  }}
+/>
+```
+
+## 注意事项
+
+- 页眉高度固定为 72px，背景色跟随主题 `theme.colors.background`
+- 标题在桌面端使用 `h2` 字号和 `weightL` 字重，移动端使用 `h3` 字号
+- `hasBack` 和 `showLeftIcon` 可同时设置，但通常二选一使用
+- 桌面端标题占据整行（`flexGrow: 1`），自动省略号处理长文本
+- 搜索框仅在 `isShowSearch=true` 时显示；桌面端为输入框，移动端为图标
+- 搜索文本变化通过 `useEffect` 延迟触发 `searchOnChangeText` 回调
+- 头像使用 `Avatar` 组件，大小为 `small`，圆形显示
+- 左侧图标大小为 20px，颜色使用主题 `grey1`

package/package/module/HelloWave/README.md

@@ -0,0 +1,28 @@
+# HelloWave
+
+挥手动画组件，使用 Animated API 实现简单的摆动效果，默认展示挥手 emoji。
+
+## 安装使用
+
+```tsx
+import { HelloWave } from '@beppla/tapas-ui';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| emoji | `string` | `'👋'` | 显示的 emoji |
+| duration | `number` | `150` | 单次摆动时长（毫秒） |
+| repeatCount | `number` | `4` | 重复次数 |
+| style | `any` | - | 容器样式 |
+| textStyle | `any` | - | 文本样式 |
+| testID | `string` | - | 测试标识 |
+
+## 使用示例
+
+```tsx
+<HelloWave />
+
+<HelloWave emoji="🎉" duration={200} repeatCount={6} />
+```

package/package/module/IconText/README.md

@@ -0,0 +1,99 @@
+# IconText
+
+图标文本组合组件，支持图标与文本的水平排列展示，可作为标签或可点击元素使用。
+
+## 功能特性
+
+- ✅ 图标 + 文本水平排列
+- ✅ 两种类型：text（纯展示，外层 View）和 label（可点击，外层 TouchableOpacity）
+- ✅ 三种尺寸：small (12px) / medium (14px) / large (16px)
+- ✅ 自定义图标颜色（iconColor）
+- ✅ 自定义背景颜色（backgroundColor）
+- ✅ 文本截断控制（numberOfLines / ellipsizeMode）
+- ✅ 自定义最大宽度（maxWidth）
+- ✅ 支持 onLayout 事件回调
+- ✅ 基于 @rneui/themed 主题系统
+
+## 安装使用
+
+```tsx
+import IconText from '@beppla/tapas-ui/components/IconText/IconText';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | `string` | (必填) | 文本内容 |
+| icon | `string` | - | 图标名称（TapasIcon） |
+| index | `number` | - | 索引值，作为 key |
+| type | `'text' \| 'label'` | `'text'` | 类型：text 纯展示，label 可点击 |
+| size | `'small' \| 'medium' \| 'large'` | `'medium'` | 尺寸 |
+| style | `StyleProp<ViewStyle>` | - | 自定义容器样式 |
+| titleStyle | `StyleProp<TextStyle>` | - | 自定义文本样式 |
+| maxWidth | `number` | - | 最大宽度 |
+| numberOfLines | `number` | - | 文本最大行数 |
+| ellipsizeMode | `'head' \| 'middle' \| 'tail' \| 'clip'` | - | 文本截断模式 |
+| onPress | `() => void` | - | 点击回调（仅 label 类型生效） |
+| onLayout | `(e: any) => void` | - | 布局事件回调 |
+| iconColor | `string` | 主题 secondary 色 | 图标颜色 |
+| backgroundColor | `string` | 主题 grey5 色 | 背景颜色 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<IconText title="示例文本" icon="home" />
+```
+
+### 不同尺寸
+
+```tsx
+<IconText title="小号" icon="info" size="small" />
+<IconText title="中号" icon="info" size="medium" />
+<IconText title="大号" icon="info" size="large" />
+```
+
+### 可点击标签
+
+```tsx
+<IconText
+  title="点击我"
+  icon="star"
+  type="label"
+  onPress={() => console.log('Clicked')}
+/>
+```
+
+### 自定义颜色
+
+```tsx
+<IconText
+  title="自定义颜色"
+  icon="warning"
+  iconColor="#FF6B00"
+  backgroundColor="#FFF3E0"
+/>
+```
+
+### 文本截断
+
+```tsx
+<IconText
+  title="这是一个很长的文本需要截断处理"
+  icon="info"
+  maxWidth={150}
+  numberOfLines={1}
+  ellipsizeMode="tail"
+/>
+```
+
+## 注意事项
+
+- `type='text'` 时外层包裹 View 容器（带 grey5 背景），不可点击
+- `type='label'` 时外层包裹 TouchableOpacity，可触发 onPress
+- 不同尺寸对应不同的字号和图标大小：small (12px/12px)、medium (14px/16px)、large (16px/20px)
+- 图标固定在文本左侧，间距为 4px
+- 不传 `icon` 时只渲染文本部分
+- 组件使用 `@rneui/themed` 主题系统，需在 ThemeProvider 内使用

package/package/module/Icons/README.md

@@ -0,0 +1,182 @@
+# TapasIcon
+
+优雅的图标组件，支持自定义字体图标。
+
+## 特性
+
+- 🎨 **自动字体加载检测** - 智能检测字体是否可用
+- 🔄 **优雅的降级处理** - 字体不可用时显示备用图标
+- 📱 **跨平台兼容** - 支持React Native和Web环境
+- 🎯 **完整的TypeScript支持** - 完整的类型定义
+- 🎨 **主题集成** - 与@rneui/themed完美集成
+- 🚀 **高性能** - 使用useMemo优化渲染性能
+
+## 安装
+
+```bash
+yarn add @beppla/tapas-ui
+```
+
+## 使用方法
+
+### 基本使用
+
+```tsx
+import { TapasIcon } from '@beppla/tapas-ui';
+
+// 基本图标
+<TapasIcon name="home" />
+
+// 自定义大小和颜色
+<TapasIcon name="settings" size={32} color="#007AFF" />
+
+// 带点击事件
+<TapasIcon name="heart" onPress={() => console.log('喜欢')} />
+
+// 禁用状态
+<TapasIcon name="delete" disabled />
+```
+
+### 图标名称
+
+组件支持以下图标名称：
+
+#### 导航类
+- `home` - 首页
+- `back` - 返回
+- `forward` - 前进
+- `menu` - 菜单
+
+#### 功能类
+- `search` - 搜索
+- `settings` - 设置
+- `add` - 添加
+- `edit` - 编辑
+- `delete` - 删除
+- `close` - 关闭
+- `check` - 确认
+
+#### 状态类
+- `loading` - 加载中
+- `error` - 错误
+- `warning` - 警告
+- `info` - 信息
+
+#### 业务类
+- `user` - 用户
+- `store` - 商店
+- `warehouse` - 仓库
+- `shipping` - 物流
+- `order` - 订单
+
+## API
+
+### Props
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `name` | `string` | - | 图标名称（必需） |
+| `size` | `number` | `24` | 图标大小 |
+| `color` | `string` | `#000` | 图标颜色 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `style` | `StyleProp<TextStyle>` | - | 自定义样式 |
+| `onPress` | `() => void` | - | 点击事件 |
+
+### 继承的属性
+
+组件继承了 `@rneui/themed` 的 `IconProps` 类型，支持所有标准的图标属性。
+
+## 字体加载
+
+组件会自动检测字体是否可用：
+
+1. **Web环境**：使用 `document.fonts.check()` 检测字体加载状态
+2. **原生环境**：假设字体已可用
+3. **降级处理**：字体不可用时显示备用图标
+
+### 字体文件
+
+确保以下文件存在于正确位置：
+
+```
+assets/
+  fonts/
+    customfont.ttf    # 字体文件
+components/
+  Icons/
+    real-icon-mapping.json  # 图标映射
+```
+
+## 备用图标
+
+当字体不可用或图标不存在时，组件会显示备用图标：
+
+- 使用Unicode字符作为备用
+- 支持表情符号作为备用
+- 提供默认的"❓"图标
+
+## 主题集成
+
+组件与 `@rneui/themed` 完美集成：
+
+```tsx
+import { useTheme } from '@rneui/themed';
+
+const MyComponent = () => {
+  const { theme } = useTheme();
+  
+  return (
+    <TapasIcon 
+      name="home" 
+      color={theme.colors.primary}
+      size={theme.spacing.lg}
+    />
+  );
+};
+```
+
+## 性能优化
+
+- 使用 `useMemo` 缓存图标信息
+- 字体检测结果缓存
+- 避免不必要的重新渲染
+
+## 浏览器兼容性
+
+- ✅ Chrome 60+
+- ✅ Firefox 55+
+- ✅ Safari 11+
+- ✅ Edge 79+
+
+## 故障排除
+
+### 图标不显示
+
+1. 检查字体文件是否存在
+2. 确认字体路径配置正确
+3. 查看浏览器控制台错误信息
+
+### 字体加载失败
+
+1. 检查网络请求是否成功
+2. 确认字体文件格式正确
+3. 验证CORS配置
+
+### 备用图标显示
+
+这是正常行为，表示：
+- 字体正在加载中
+- 字体加载失败
+- 图标名称不存在
+
+## 示例
+
+查看 [Storybook 故事](../../stories/Icons/TapasIcon.stories.tsx) 获取更多使用示例。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT License