@beppla/tapas-ui 1.5.9 → 1.5.11

package/package/module/LineChart/README.md

@@ -0,0 +1,181 @@
+# LineChart
+
+折线图组件，支持单系列/多系列数据、多种曲线类型、自定义图例和 Tooltip。采用**双平台渲染**策略：Web 端使用 recharts，Native 端使用 react-native-svg-charts。
+
+## 功能特性
+
+- ✅ **双平台渲染**：Web 使用 recharts（功能完整），Native 使用 react-native-svg-charts（基础功能）
+- ✅ 支持单系列和多系列数据
+- ✅ 多种曲线类型：monotone / linear / step / natural / basis
+- ✅ 可显示/隐藏数据点（showDots）
+- ✅ 可独立控制 X 轴和 Y 轴的显示/隐藏
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ 自定义图例图标类型：circle / rect / square / line
+- ✅ 自定义图例图标尺寸和文本样式
+- ✅ 自定义 Tooltip：完全自定义渲染（customTooltip）或数据格式化（tooltipFormatter）
+- ✅ 数据点点击事件回调（onLineClick）
+- ✅ Y 轴 / X 轴格式化函数
+- ✅ 响应式容器（Web 端 ResponsiveContainer）
+
+## 安装使用
+
+```tsx
+import { LineChart } from '@beppla/tapas-ui/components/LineChart';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `LineChartDataPoint[] \| LineChartSeriesData[]` | (必填) | 数据源 |
+| width | `number` | - | 图表宽度 |
+| height | `number` | `300` | 图表高度 |
+| color | `string` | `'#0066CC'` | 单系列线条颜色 |
+| colors | `string[]` | - | 多系列颜色方案 |
+| showGrid | `boolean` | `true` | 是否显示网格线 |
+| showLabels | `boolean` | `true` | 是否显示标签 |
+| showXAxis | `boolean` | `true` | 是否显示 X 轴 |
+| showYAxis | `boolean` | `true` | 是否显示 Y 轴 |
+| showLegend | `boolean` | `true` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 图例位置 |
+| legendIconType | `'circle' \| 'rect' \| 'square' \| 'line'` | `'rect'` | 图例图标类型 |
+| legendIconSize | `{ width: number; height: number }` | `{ width: 18, height: 8 }` | 图例图标尺寸 |
+| legendTextStyle | `{ fontFamily?: string; fontSize?: number; fontWeight?: string \| number; letterSpacing?: number }` | Bricolage Grotesque 10px | 图例文本样式 |
+| curveType | `'monotone' \| 'linear' \| 'step' \| 'natural' \| 'basis'` | `'monotone'` | 曲线类型 |
+| showDots | `boolean` | `true` | 是否显示数据点 |
+| showArea | `boolean` | - | 是否显示面积填充 |
+| customTooltip | `(data: TooltipData) => ReactElement \| null` | - | 自定义 Tooltip 渲染函数 |
+| tooltipFormatter | `(data: TooltipData) => { title?: string; items?: Array<{ label: string; value: string \| number }> }` | - | Tooltip 数据格式化函数 |
+| contentInset | `{ top?: number; bottom?: number; left?: number; right?: number }` | `{ top: 20, bottom: 20, left: 20, right: 20 }` | 内容边距 |
+| yAxisFormat | `(value: number) => string` | - | Y 轴格式化 |
+| xAxisFormat | `(value: number, index: number) => string` | - | X 轴格式化 |
+| onLineClick | `(seriesLabel: string, dataPoint: LineChartDataPoint, dataIndex: number) => void` | - | 数据点点击回调 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### LineChartDataPoint
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | `number` | 数值（必填） |
+| label | `string` | 标签 |
+
+### LineChartSeriesData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| data | `LineChartDataPoint[]` | 数据点数组（必填） |
+| color | `string` | 线条颜色 |
+| label | `string` | 系列标签（显示在图例中） |
+
+### TooltipData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| label | `string` | 当前数据点标签 |
+| value | `number` | 当前数据点值 |
+| dataIndex | `number` | 数据索引 |
+| seriesLabel | `string` | 系列标签 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+<LineChart
+  data={[
+    { value: 50, label: 'Jan' },
+    { value: 75, label: 'Feb' },
+    { value: 65, label: 'Mar' },
+    { value: 90, label: 'Apr' },
+  ]}
+  height={300}
+  color="#0066CC"
+/>
+```
+
+### 多系列数据
+
+```tsx
+<LineChart
+  data={[
+    {
+      label: 'Product A',
+      color: '#00BFA5',
+      data: [
+        { value: 120, label: 'Mon' },
+        { value: 150, label: 'Tue' },
+        { value: 110, label: 'Wed' },
+      ],
+    },
+    {
+      label: 'Product B',
+      color: '#FF6B00',
+      data: [
+        { value: 100, label: 'Mon' },
+        { value: 110, label: 'Tue' },
+        { value: 90, label: 'Wed' },
+      ],
+    },
+  ]}
+  showLegend
+  legendPosition="top"
+  height={400}
+/>
+```
+
+### 极简设计图风格
+
+```tsx
+<LineChart
+  data={multiSeriesData}
+  curveType="linear"
+  showDots={false}
+  showYAxis={false}
+  showLegend
+  legendPosition="top"
+  legendIconType="rect"
+  legendIconSize={{ width: 18, height: 8 }}
+  legendTextStyle={{
+    fontFamily: 'Bricolage Grotesque, sans-serif',
+    fontSize: 10,
+    fontWeight: 400,
+    letterSpacing: 0.1,
+  }}
+/>
+```
+
+### 自定义 Tooltip
+
+```tsx
+<LineChart
+  data={storeData}
+  tooltipFormatter={(data) => ({
+    title: data.label,
+    items: [
+      { label: 'Stores', value: data.value },
+      { label: 'Revenue', value: `$${revenue[data.dataIndex]}` },
+    ],
+  })}
+/>
+```
+
+### 数据点点击事件
+
+```tsx
+<LineChart
+  data={sampleData}
+  onLineClick={(seriesLabel, dataPoint, dataIndex) => {
+    console.log(`${seriesLabel}: ${dataPoint.label} = ${dataPoint.value}`);
+  }}
+/>
+```
+
+## 注意事项
+
+- **双平台渲染**：Web 端使用 recharts（功能完整），Native 端使用 react-native-svg-charts（功能受限）
+- Native 端多系列数据**仅渲染第一个系列**
+- Native 端不支持自定义 Tooltip、图例自定义、曲线类型选择
+- 图例仅在多系列数据时显示
+- `customTooltip` 和 `tooltipFormatter` 仅 Web 端有效（鼠标悬停触发）
+- 需安装对应平台依赖：Web 需要 `recharts`，Native 需要 `react-native-svg-charts` + `react-native-svg`

package/package/module/ListItem/README.md

@@ -0,0 +1,122 @@
+# ListItem
+
+列表项组件，基于 @rneui/themed ListItem 封装，支持选中状态、搜索高亮、描述文本、数量角标等功能，适合构建可交互的选择列表。
+
+## 功能特性
+
+- ✅ 选中状态指示（背景色变化 + 勾选图标）
+- ✅ 搜索关键字高亮显示（name 和 desc 同时高亮）
+- ✅ 支持主标题和描述文本
+- ✅ 数量角标（number 属性，圆形背景主题色）
+- ✅ 鼠标悬停效果（Web 端 Hoverable）
+- ✅ 禁用状态，颜色置灰且不可点击
+- ✅ 首末项圆角支持（isFirst / isLast，12px 圆角）
+- ✅ 高度自定义样式：容器、标题、描述、搜索高亮
+- ✅ 文本自适应宽度，自动单行截断
+
+## 安装使用
+
+```tsx
+import ListItem from '@beppla/tapas-ui/components/ListItem/ListItem';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| item | `ItemProps` | (必填) | 列表项数据 |
+| selected | `ItemProps` | (必填) | 当前选中项（通过 value 比较） |
+| key | `number \| string` | (必填) | 唯一标识 |
+| onItemPress | `(item: ItemProps) => void` | (必填) | 点击回调 |
+| disabled | `boolean` | - | 是否禁用 |
+| isFirst | `boolean` | - | 是否为第一项（添加顶部圆角） |
+| isLast | `boolean` | - | 是否为最后一项（添加底部圆角） |
+| search | `string` | - | 搜索关键字，匹配部分高亮 |
+| containerStyle | `StyleProp<ViewStyle>` | - | 外层容器样式 |
+| itemContainerStyle | `StyleProp<ViewStyle>` | - | 项容器样式 |
+| titleContainerStyle | `StyleProp<ViewStyle>` | - | 标题容器样式 |
+| searchHighlightStyle | `StyleProp<TextStyle>` | - | 搜索高亮文本样式 |
+| titleStyle | `StyleProp<TextStyle>` | - | 标题文本样式 |
+| descStyle | `StyleProp<TextStyle>` | - | 描述文本样式 |
+| testID | `string` | - | 测试标识 |
+
+### ItemProps 接口
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | `string` | 显示名称（必填） |
+| value | `string \| number` | 值（必填），用于比较选中状态 |
+| id | `string \| number` | 唯一标识 |
+| hide | `boolean` | 是否隐藏 |
+| desc | `string` | 描述文本 |
+| number | `number` | 数量角标 |
+
+## 使用示例
+
+### 基础用法
+
+```tsx
+const data = [
+  { name: 'Apple', value: 'apple' },
+  { name: 'Banana', value: 'banana' },
+  { name: 'Cherry', value: 'cherry' },
+];
+
+const [selected, setSelected] = useState(data[0]);
+
+{data.map((item, index) => (
+  <ListItem
+    key={index}
+    item={item}
+    selected={selected}
+    onItemPress={(value) => setSelected(value)}
+    isFirst={index === 0}
+    isLast={index === data.length - 1}
+  />
+))}
+```
+
+### 带描述和搜索高亮
+
+```tsx
+<ListItem
+  key={0}
+  item={{ name: 'John', value: 'john', desc: 'Manager' }}
+  selected={selected}
+  onItemPress={setSelected}
+  search="jo"
+  searchHighlightStyle={{ color: 'red' }}
+/>
+```
+
+### 带数量角标
+
+```tsx
+<ListItem
+  key={0}
+  item={{ name: 'Orders', value: 'orders', number: 5 }}
+  selected={selected}
+  onItemPress={setSelected}
+/>
+```
+
+### 禁用状态
+
+```tsx
+<ListItem
+  key={0}
+  item={{ name: 'Unavailable', value: 'unavailable' }}
+  selected={selected}
+  onItemPress={setSelected}
+  disabled
+/>
+```
+
+## 注意事项
+
+- 选中状态通过比较 `selected.value === item.value` 判断
+- 当 `item.number` 存在时显示数量角标（白字主题色背景），否则选中时显示勾选图标
+- 禁用状态下点击不会触发 `onItemPress`
+- `isFirst` / `isLast` 用于列表首末项圆角（12px），需手动传入
+- 搜索高亮使用正则分割文本，大小写不敏感，同时作用于 name 和 desc 字段
+- 列表项固定高度 48px

package/package/module/Loading/Loading.js

@@ -0,0 +1,95 @@
+"use strict";
+
+import React, { useEffect, useRef } from "react";
+import { View, Modal, Image, Animated, Easing } from "react-native";
+import { withTheme, makeStyles } from "@rneui/themed";
+import { jsx as _jsx } from "react/jsx-runtime";
+const Loading = ({
+  visible,
+  logo,
+  backgroundColor,
+  defaultLogo,
+  size = 200,
+  testID
+}) => {
+  const styles = useStyles();
+  const opacity = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    if (!visible) return;
+    opacity.setValue(0);
+    const animation = Animated.loop(Animated.sequence([Animated.timing(opacity, {
+      toValue: 0.3,
+      duration: 800,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver: true
+    }), Animated.timing(opacity, {
+      toValue: 0.05,
+      duration: 1000,
+      easing: Easing.inOut(Easing.ease),
+      useNativeDriver: true
+    })]));
+    animation.start();
+    return () => animation.stop();
+  }, [visible, opacity]);
+  if (!visible) return null;
+
+  // 图片优先级：1. 传入的 logo 2. 传入的 defaultLogo 3. 内置默认图片
+  // 使用 try-catch 来安全地引用图片，避免打包后的路径问题
+  let imageSource;
+  try {
+    if (logo) {
+      imageSource = logo;
+    } else if (defaultLogo) {
+      imageSource = defaultLogo;
+    } else {
+      // 直接使用占位符，避免路径问题
+      imageSource = {
+        uri: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAwIiBoZWlnaHQ9IjIwMCIgdmlld0JveD0iMCAwIDIwMCAyMDAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHdpZHRoPSIyMDAiIGhlaWdodD0iMjAwIiBmaWxsPSIjRjVGNUY1Ii8+Cjx0ZXh0IHg9IjEwMCIgeT0iMTAwIiBmb250LWZhbWlseT0iQXJpYWwiIGZvbnQtc2l6ZT0iMTYiIGZpbGw9IiM5OTk5OTkiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGR5PSIuM2VtIj5UYXBhcyBVSTwvdGV4dD4KPC9zdmc+'
+      };
+    }
+  } catch (error) {
+    // 如果出现任何错误，使用占位符
+    imageSource = {
+      uri: 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAwIiBoZWlnaHQ9IjIwMCIgdmlld0JveD0iMCAwIDIwMCAyMDAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxyZWN0IHdpZHRoPSIyMDAiIGhlaWdodD0iMjAwIiBmaWxsPSIjRjVGNUY1Ii8+Cjx0ZXh0IHg9IjEwMCIgeT0iMTAwIiBmb250LWZhbWlseT0iQXJpYWwiIGZvbnQtc2l6ZT0iMTYiIGZpbGw9IiM5OTk5OTkiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGR5PSIuM2VtIj5UYXBhcyBVSTwvdGV4dD4KPC9zdmc+'
+    };
+  }
+  return /*#__PURE__*/_jsx(Modal, {
+    statusBarTranslucent: true,
+    transparent: true,
+    visible: visible,
+    testID: testID ?? "loading",
+    children: /*#__PURE__*/_jsx(View, {
+      style: [styles.bg, backgroundColor ? {
+        backgroundColor
+      } : undefined],
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        style: [{
+          opacity,
+          width: size,
+          height: size
+        }],
+        children: /*#__PURE__*/_jsx(Image, {
+          style: {
+            width: size,
+            height: size
+          },
+          source: imageSource,
+          resizeMode: "contain"
+        })
+      })
+    })
+  });
+};
+const useStyles = makeStyles(theme => ({
+  bg: {
+    display: "flex",
+    flexDirection: "column",
+    justifyContent: "center",
+    alignContent: "center",
+    alignItems: "center",
+    flex: 1,
+    backgroundColor: theme?.colors?.grey1
+  }
+}));
+export default withTheme(Loading);
+//# sourceMappingURL=Loading.js.map

package/package/module/Loading/Loading.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","useEffect","useRef","View","Modal","Image","Animated","Easing","withTheme","makeStyles","jsx","_jsx","Loading","visible","logo","backgroundColor","defaultLogo","size","testID","styles","useStyles","opacity","Value","current","setValue","animation","loop","sequence","timing","toValue","duration","easing","inOut","ease","useNativeDriver","start","stop","imageSource","uri","error","statusBarTranslucent","transparent","children","style","bg","undefined","width","height","source","resizeMode","theme","display","flexDirection","justifyContent","alignContent","alignItems","flex","colors","grey1"],"sourceRoot":"../../../components","sources":["Loading/Loading.tsx"],"mappings":"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","ignoreList":[]}

package/package/module/Loading/README.md

@@ -0,0 +1,160 @@
+# Loading 组件
+
+一个全屏加载组件，提供优雅的加载动画效果。
+
+## 功能特性
+
+- 全屏模态展示
+- 淡入淡出动画效果
+- 可自定义Logo和背景色
+- 支持自定义默认Logo和尺寸
+- 自动循环动画
+- 支持透明背景
+
+## 基本用法
+
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+
+// 基础用法
+<Loading visible={isLoading} />
+
+// 自定义背景色
+<Loading 
+  visible={isLoading} 
+  backgroundColor="rgba(0, 0, 0, 0.8)" 
+/>
+
+// 自定义Logo
+<Loading 
+  visible={isLoading} 
+  logo={require('./custom-logo.png')} 
+/>
+```
+
+## 避免硬编码图片引用问题
+
+### 问题描述
+之前的版本中，Loading 组件内部硬编码了 `require("../../assets/logo.png")`，这会导致在使用组件库时出现模块解析错误。
+
+### 解决方案
+现在提供了多种方式来解决这个问题：
+
+#### 1. 使用 `defaultLogo` 属性（推荐）
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import customLogo from './assets/custom-logo.png';
+
+<Loading 
+  visible={isLoading} 
+  defaultLogo={customLogo}
+/>
+```
+
+#### 2. 使用 `logo` 属性
+```tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import customLogo from './assets/custom-logo.png';
+
+<Loading 
+  visible={isLoading} 
+  logo={customLogo}
+/>
+```
+
+#### 3. 在应用初始化时设置全局默认Logo
+```tsx
+// 在应用入口处
+import { initTapasUI } from '@beppla/tapas-ui';
+import defaultLogo from './assets/default-logo.png';
+
+initTapasUI({
+  defaultLoadingLogo: defaultLogo
+});
+
+// 在组件中使用
+<Loading visible={isLoading} />
+```
+
+## API 参考
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `visible` | `boolean` | `false` | 是否显示加载状态 |
+| `logo` | `ImageSourcePropType` | `undefined` | 自定义Logo图片（最高优先级） |
+| `defaultLogo` | `ImageSourcePropType` | `undefined` | 默认Logo图片（优先级高于内置默认） |
+| `backgroundColor` | `string` | `theme.colors.grey1` | 背景颜色 |
+| `size` | `number` | `200` | Logo尺寸（像素） |
+
+### 图片优先级说明
+
+1. **`logo`** - 最高优先级，直接使用传入的图片
+2. **`defaultLogo`** - 中等优先级，使用传入的默认图片
+3. **内置默认图片** - 最低优先级，作为最后的回退选项
+
+## 使用场景
+
+- 应用启动加载
+- 数据请求等待
+- 页面切换过渡
+- 长时间操作提示
+
+## 注意事项
+
+1. **避免硬编码引用**：不要依赖组件内部的默认图片，建议使用 `defaultLogo` 属性
+2. **图片格式支持**：支持 PNG、JPG、SVG 等常见图片格式
+3. **性能考虑**：Logo 图片建议使用适当尺寸，避免过大的图片文件
+4. **主题适配**：背景色会自动适配主题，也可以手动覆盖
+
+## 迁移指南
+
+### 从旧版本迁移
+
+**旧版本（有问题）：**
+```tsx
+// 直接使用，可能报错
+<Loading visible={isLoading} />
+```
+
+**新版本（推荐）：**
+```tsx
+// 设置自定义默认Logo
+<Loading 
+  visible={isLoading} 
+  defaultLogo={require('./assets/logo.png')}
+/>
+
+// 或者使用自定义Logo
+<Loading 
+  visible={isLoading} 
+  logo={require('./assets/logo.png')}
+/>
+```
+
+### 批量替换示例
+
+如果您的项目中有多个地方使用了 Loading 组件，可以创建一个包装组件：
+
+```tsx
+// components/AppLoading.tsx
+import Loading from '@beppla/tapas-ui/components/Loading';
+import appLogo from '../assets/app-logo.png';
+
+export const AppLoading = (props) => (
+  <Loading 
+    {...props} 
+    defaultLogo={appLogo}
+  />
+);
+
+// 在项目中使用
+import { AppLoading } from './components/AppLoading';
+
+<AppLoading visible={isLoading} />
+```
+
+## 示例代码
+
+完整的示例项目可以参考 Storybook 中的演示，或者查看 `stories/Loading/Loading.stories.tsx` 文件。