@beppla/tapas-ui 1.5.9 → 1.5.11

package/package/module/Grid/README.md

@@ -0,0 +1,197 @@
+# Grid 虚拟滚动网格组件
+
+高性能虚拟滚动网格组件，支持固定尺寸和可变尺寸的行列，可处理数千行列的大型数据集。包含三个变体：**StaticFixedSizeGrid**（粘性列 + 列头）、**FixedSizeGrid**（等宽等高）、**VariableSizeGrid**（动态行列尺寸），满足从简单表格到复杂数据面板的各种场景。
+
+## 功能特性
+
+- ✅ 虚拟滚动渲染：仅渲染可视区域内的单元格，支持数千行列
+- ✅ 三种 Grid 变体：StaticFixedSizeGrid / FixedSizeGrid / VariableSizeGrid
+- ✅ 粘性列（Sticky Columns）：指定列固定在右侧，水平滚动时不跟随
+- ✅ 粘性列头（Sticky Headers）：列头固定在顶部，垂直滚动时不跟随
+- ✅ 可变行高和列宽：VariableSizeGrid 支持通过函数动态返回尺寸
+- ✅ 滚动同步：多个 Grid 实例间的滚动联动
+- ✅ 滚动阴影指示器：左右边缘滚动时显示阴影
+- ✅ RTL（右到左）布局支持
+- ✅ Overscan 预渲染：提前渲染可视区外的行列，减少滚动白屏
+- ✅ scrollTo / scrollToItem 命令式滚动 API
+- ✅ 自定义边框和圆角控制
+- ✅ hasActions 支持：特定单元格允许 overflow visible（下拉菜单不被裁切）
+
+## 安装使用
+
+```tsx
+import {
+  StaticFixedSizeGrid,
+  FixedSizeGrid,
+  VariableSizeGrid,
+} from '@beppla/tapas-ui';
+```
+
+## StaticFixedSizeGrid Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| columnCount | `number` | - | 总列数（必填） |
+| columnWidth | `(index: number) => number` | - | 列宽函数（必填） |
+| rowCount | `number` | - | 总行数（必填） |
+| rowHeight | `(index: number) => number` | - | 行高函数（必填） |
+| width | `number` | - | 容器宽度（必填） |
+| height | `number` | - | 容器高度（必填） |
+| children | `(props: ChildrenProps) => ReactNode` | - | 单元格渲染函数（必填） |
+| headersRender | `(props: ChildrenProps) => JSX.Element` | - | 列头渲染函数 |
+| columnHeaderHeight | `number` | `40` | 列头高度 |
+| columnHeaderBackgroundColor | `string` | 主题 grey4 | 列头背景色 |
+| stickyColumnIndices | `number[]` | - | 粘性列索引数组 |
+| border | `boolean` | `false` | 是否显示边框 |
+| onScroll | `(event) => void` | - | 滚动回调 |
+| hideBorder | `string[]` | - | 隐藏指定方向边框（top/bottom/left/right） |
+| hideborderRadius | `string[]` | - | 隐藏指定角的圆角（topLeft/topRight） |
+| hasActions | `(columnIndex, rowIndex) => boolean` | - | 判断单元格是否有下拉操作菜单 |
+| gridRef | `React.MutableRefObject<any>` | - | Grid 实例引用 |
+| style | `Object` | - | 自定义容器样式 |
+
+### ChildrenProps
+
+```tsx
+interface ChildrenProps {
+  columnIndex: number;
+  rowIndex: number;
+  style: CSSProperties;
+}
+```
+
+## FixedSizeGrid Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| columnCount | `number` | - | 总列数（必填） |
+| columnWidth | `number` | - | 固定列宽（必填） |
+| rowCount | `number` | - | 总行数（必填） |
+| rowHeight | `number` | - | 固定行高（必填） |
+| width | `number` | - | 容器宽度（必填） |
+| height | `number` | - | 容器高度（必填） |
+| children | `RenderComponent<T>` | - | 单元格渲染组件（必填） |
+| itemData | `T` | - | 传递给子组件的数据 |
+| direction | `'ltr' \| 'rtl'` | `'ltr'` | 文本方向 |
+| overscanColumnCount | `number` | `1` | 列预渲染数量 |
+| overscanRowCount | `number` | `1` | 行预渲染数量 |
+| onScroll | `OnScrollCallback` | - | 滚动回调 |
+| onItemsRendered | `OnItemsRenderedCallback` | - | 可见区域变化回调 |
+
+## VariableSizeGrid Props
+
+与 FixedSizeGrid 相同，但 `columnWidth` 和 `rowHeight` 为函数类型：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| columnWidth | `(index: number) => number` | 根据索引返回列宽 |
+| rowHeight | `(index: number) => number` | 根据索引返回行高 |
+
+## 使用示例
+
+### StaticFixedSizeGrid（粘性列 + 列头）
+
+```tsx
+const columnWidths = [100, 150, 200, 120, 80];
+
+const Cell = ({ columnIndex, rowIndex, style }: ChildrenProps) => (
+  <div style={style}>
+    Item {rowIndex},{columnIndex}
+  </div>
+);
+
+const ColumnHeaders = ({ columnIndex, style }: ChildrenProps) => (
+  <div style={style}>Header {columnIndex}</div>
+);
+
+<StaticFixedSizeGrid
+  columnCount={5}
+  columnWidth={(index) => columnWidths[index]}
+  rowCount={1000}
+  rowHeight={() => 56}
+  width={650}
+  height={400}
+  border={true}
+  headersRender={ColumnHeaders}
+  stickyColumnIndices={[4]}
+>
+  {Cell}
+</StaticFixedSizeGrid>
+```
+
+### FixedSizeGrid（等宽等高）
+
+```tsx
+<FixedSizeGrid
+  columnCount={1000}
+  columnWidth={75}
+  rowCount={1000}
+  rowHeight={40}
+  width={300}
+  height={300}
+>
+  {Cell}
+</FixedSizeGrid>
+```
+
+### VariableSizeGrid（动态尺寸）
+
+```tsx
+<VariableSizeGrid
+  columnCount={1000}
+  columnWidth={(index) => 75 + Math.round(Math.random() * 50)}
+  rowCount={1000}
+  rowHeight={(index) => (index % 2 === 0 ? 40 : 56)}
+  width={300}
+  height={300}
+>
+  {Cell}
+</VariableSizeGrid>
+```
+
+### 多 Grid 滚动联动
+
+```tsx
+const gridRef = useRef(null);
+
+<StaticFixedSizeGrid
+  columnCount={20}
+  columnWidth={(i) => widths[i]}
+  rowCount={100}
+  rowHeight={() => 56}
+  width={650}
+  height={400}
+  onScroll={(event) => {
+    gridRef.current?.scrollTo({
+      ...event,
+      scrollTop: gridRef.current.state.scrollTop,
+    });
+  }}
+  headersRender={Headers}
+>
+  {Cell}
+</StaticFixedSizeGrid>
+
+<StaticFixedSizeGrid
+  gridRef={gridRef}
+  columnCount={20}
+  columnWidth={(i) => widths[i]}
+  rowCount={50}
+  rowHeight={() => 56}
+  width={650}
+  height={300}
+>
+  {Cell}
+</StaticFixedSizeGrid>
+```
+
+## 注意事项
+
+- StaticFixedSizeGrid 内部基于 VariableSizeGrid + StickyListContext 实现
+- 粘性列通过独立的 VariableSizeGrid 实例渲染，使用 `position: sticky` 固定
+- 滚动同步使用 RAF（requestAnimationFrame）节流优化性能
+- `hasActions` 为 true 的单元格设置 `overflow: visible` 允许下拉菜单溢出
+- 列头同步滚动通过 `headerRef.scrollTo()` 实现
+- FixedSizeGrid 的 `columnWidth` 和 `rowHeight` 必须是 number 类型
+- VariableSizeGrid 的 `columnWidth` 和 `rowHeight` 必须是函数类型
+- 组件基于 Web DOM（div），仅适用于 `Platform.OS === 'web'`

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/IconText.js

@@ -0,0 +1,113 @@
+"use strict";
+
+import React from 'react';
+import { View, Text, TouchableOpacity } from 'react-native';
+import { makeStyles, withTheme, useTheme } from '@rneui/themed';
+import TapasIcon from '../Icons/TapasIcon';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const IconText = ({
+  onPress,
+  type = 'text',
+  title,
+  index,
+  icon,
+  style,
+  titleStyle,
+  onLayout,
+  iconColor,
+  backgroundColor,
+  size = 'medium',
+  testID,
+  ...props
+}) => {
+  const theme = useTheme();
+  const styles = useStyles({
+    size,
+    backgroundColor
+  });
+  const content = /*#__PURE__*/_jsxs(View, {
+    style: [styles.labelIconContainer, style],
+    children: [icon && /*#__PURE__*/_jsx(TapasIcon, {
+      name: icon,
+      style: styles.labelIcon,
+      size: 16,
+      color: iconColor || theme.theme.colors.secondary
+    }), /*#__PURE__*/_jsx(Text, {
+      style: [styles.labelTitle, titleStyle],
+      ...props,
+      onLayout: e => onLayout && onLayout(e),
+      children: title
+    })]
+  }, index);
+  if (type === 'text') {
+    return /*#__PURE__*/_jsx(View, {
+      testID: testID,
+      style: [styles.container, style],
+      children: content
+    });
+  }
+  return /*#__PURE__*/_jsx(TouchableOpacity, {
+    testID: testID,
+    onPress: onPress,
+    children: content
+  });
+};
+const useStyles = makeStyles((theme, props) => {
+  const {
+    size = 'medium',
+    backgroundColor
+  } = props || {};
+  let fontSize = theme.fonts?.sizeM || 16;
+  let iconSize = 16;
+  let pdh = 4;
+  let pdv = 4;
+  switch (size) {
+    case 'small':
+      fontSize = theme.fonts?.sizeXs || 12;
+      iconSize = 12;
+      pdv = 2;
+      break;
+    case 'medium':
+      fontSize = theme.fonts?.sizeS || 14;
+      iconSize = 16;
+      break;
+    case 'large':
+      fontSize = theme.fonts?.sizeM || 16;
+      iconSize = 20;
+      pdh = 8;
+      pdv = 8;
+      break;
+  }
+  return {
+    container: {
+      marginTop: 4,
+      marginRight: 8,
+      width: 'auto',
+      paddingHorizontal: 4,
+      paddingVertical: 2,
+      backgroundColor: backgroundColor || theme.colors.grey5,
+      color: theme.colors.grey1,
+      borderRadius: 4
+    },
+    labelIconContainer: {
+      display: 'flex',
+      flexDirection: 'row',
+      alignItems: 'center',
+      paddingVertical: pdv,
+      paddingHorizontal: pdh,
+      marginBottom: 8
+    },
+    labelIcon: {
+      marginRight: 4,
+      width: iconSize,
+      height: iconSize
+    },
+    labelTitle: {
+      fontSize: fontSize,
+      letterSpacing: 0.1,
+      color: theme.colors.grey1
+    }
+  };
+});
+export default withTheme(/*#__PURE__*/React.memo(IconText));
+//# sourceMappingURL=IconText.js.map

package/package/module/IconText/IconText.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","View","Text","TouchableOpacity","makeStyles","withTheme","useTheme","TapasIcon","jsx","_jsx","jsxs","_jsxs","IconText","onPress","type","title","index","icon","style","titleStyle","onLayout","iconColor","backgroundColor","size","testID","props","theme","styles","useStyles","content","labelIconContainer","children","name","labelIcon","color","colors","secondary","labelTitle","e","container","fontSize","fonts","sizeM","iconSize","pdh","pdv","sizeXs","sizeS","marginTop","marginRight","width","paddingHorizontal","paddingVertical","grey5","grey1","borderRadius","display","flexDirection","alignItems","marginBottom","height","letterSpacing","memo"],"sourceRoot":"../../../components","sources":["IconText/IconText.tsx"],"mappings":"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","ignoreList":[]}

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 内使用