@beppla/tapas-ui 1.5.13 → 1.5.15

package/package/module/AnimatedNavItem/README.md

@@ -0,0 +1,520 @@
+# TapasAnimatedNavItem
+
+一个支持动画宽度变化的导航项组件，可以在展开和收缩状态之间平滑切换，适用于导航菜单、标签栏和交互式按钮。
+
+## 功能特性
+
+- ✅ 平滑的宽度动画过渡效果
+- ✅ 支持图标和文本的组合显示
+- ✅ 可配置的展开/收缩状态
+- ✅ 丰富的自定义样式选项
+- ✅ 完整的交互支持（点击、长按）
+- ✅ 响应式尺寸和颜色配置
+- ✅ 主题集成和无障碍访问
+- ✅ 向后兼容的导出别名
+
+## 安装使用
+
+```tsx
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+// 基础用法
+<TapasAnimatedNavItem 
+  icon="home" 
+  text="Home"
+  expanded={true}
+/>
+
+// 导航菜单
+<TapasAnimatedNavItem 
+  id="dashboard"
+  icon="dashboard" 
+  text="Dashboard"
+  expanded={isExpanded}
+  selected={selectedId === 'dashboard'}
+  onPress={(id) => setSelectedId(id)}
+/>
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `id` | `number \| string` | - | 唯一标识符 |
+| `icon` | `string` | - | 图标名称 |
+| `text` | `string` | - | 显示文本 |
+| `minWidth` | `number` | `40` | 最小宽度（收缩状态） |
+| `maxWidth` | `number` | 自动计算 | 最大宽度（展开状态） |
+| `expanded` | `boolean` | `false` | 是否展开状态 |
+| `selected` | `boolean` | `false` | 是否被选中 |
+| `iconSize` | `number` | `20` | 图标大小 |
+| `iconColor` | `string` | 主题色 | 图标颜色（未展开时） |
+| `expandedIconColor` | `string` | 白色 | 图标颜色（展开时） |
+| `textColor` | `string` | 白色 | 文本颜色 |
+| `backgroundColor` | `string` | 透明 | 背景颜色（未展开时） |
+| `expandedBackgroundColor` | `string` | 主题色 | 背景颜色（展开时） |
+| `animationDuration` | `number` | `200` | 动画持续时间（毫秒） |
+| `textStyle` | `StyleProp<TextStyle>` | - | 文本样式 |
+| `containerStyle` | `StyleProp<ViewStyle>` | - | 容器样式 |
+| `onPress` | `(id?: number \| string) => void` | - | 点击回调 |
+| `onLongPress` | `(id?: number \| string) => void` | - | 长按回调 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `height` | `number` | `40` | 组件高度 |
+| `padding` | `{horizontal?: number, vertical?: number}` | `{horizontal: 12, vertical: 0}` | 内边距配置 |
+
+## 使用示例
+
+### 基础导航项
+
+```tsx
+import React, { useState } from 'react';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const BasicExample = () => {
+  const [expanded, setExpanded] = useState(false);
+  
+  return (
+    <TapasAnimatedNavItem 
+      icon="home" 
+      text="Home"
+      expanded={expanded}
+      onPress={() => setExpanded(!expanded)}
+    />
+  );
+};
+```
+
+### 导航菜单
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const NavigationMenu = () => {
+  const [selectedItem, setSelectedItem] = useState('home');
+  const [menuExpanded, setMenuExpanded] = useState(true);
+  
+  const navItems = [
+    { id: 'home', icon: 'home', text: 'Home' },
+    { id: 'dashboard', icon: 'dashboard', text: 'Dashboard' },
+    { id: 'analytics', icon: 'analytics', text: 'Analytics' },
+    { id: 'settings', icon: 'settings', text: 'Settings' },
+  ];
+
+  const handleItemPress = (id: string) => {
+    setSelectedItem(id);
+  };
+
+  return (
+    <View style={{ padding: 16, gap: 8 }}>
+      {navItems.map((item) => (
+        <TapasAnimatedNavItem
+          key={item.id}
+          id={item.id}
+          icon={item.icon}
+          text={item.text}
+          expanded={menuExpanded}
+          selected={selectedItem === item.id}
+          onPress={handleItemPress}
+        />
+      ))}
+    </View>
+  );
+};
+```
+
+### 标签栏
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const TabBar = () => {
+  const [activeTab, setActiveTab] = useState('home');
+  
+  const tabs = [
+    { id: 'home', icon: 'home', text: 'Home' },
+    { id: 'search', icon: 'search', text: 'Search' },
+    { id: 'favorites', icon: 'favorite', text: 'Favorites' },
+    { id: 'profile', icon: 'person', text: 'Profile' },
+  ];
+
+  return (
+    <View style={{ 
+      flexDirection: 'row', 
+      backgroundColor: 'white',
+      borderRadius: 12,
+      padding: 8,
+      gap: 4 
+    }}>
+      {tabs.map((tab) => (
+        <TapasAnimatedNavItem
+          key={tab.id}
+          id={tab.id}
+          icon={tab.icon}
+          text={tab.text}
+          expanded={activeTab === tab.id}
+          selected={activeTab === tab.id}
+          onPress={(id) => setActiveTab(id as string)}
+          height={48}
+          minWidth={48}
+          style={{ flex: 1 }}
+        />
+      ))}
+    </View>
+  );
+};
+```
+
+### 自定义样式
+
+```tsx
+import React from 'react';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const CustomStyledExample = () => {
+  return (
+    <View style={{ gap: 16 }}>
+      {/* 自定义颜色 */}
+      <TapasAnimatedNavItem 
+        icon="star" 
+        text="Custom Colors"
+        expanded={true}
+        iconColor="#FF6B6B"
+        expandedIconColor="#FFFFFF"
+        textColor="#FFFFFF"
+        expandedBackgroundColor="#FF6B6B"
+      />
+      
+      {/* 自定义尺寸 */}
+      <TapasAnimatedNavItem 
+        icon="apps" 
+        text="Large Size"
+        expanded={true}
+        height={60}
+        iconSize={28}
+        minWidth={60}
+        textStyle={{ fontSize: 16 }}
+      />
+      
+      {/* 自定义动画 */}
+      <TapasAnimatedNavItem 
+        icon="speed" 
+        text="Slow Animation"
+        expanded={true}
+        animationDuration={800}
+      />
+    </View>
+  );
+};
+```
+
+### 响应式导航
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { Dimensions } from 'react-native';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const ResponsiveNavigation = () => {
+  const [isWideScreen, setIsWideScreen] = useState(false);
+  const [selectedItem, setSelectedItem] = useState('home');
+  
+  useEffect(() => {
+    const updateLayout = () => {
+      const { width } = Dimensions.get('window');
+      setIsWideScreen(width > 768);
+    };
+    
+    updateLayout();
+    const subscription = Dimensions.addEventListener('change', updateLayout);
+    
+    return () => subscription?.remove();
+  }, []);
+
+  const navItems = [
+    { id: 'home', icon: 'home', text: 'Home' },
+    { id: 'projects', icon: 'work', text: 'Projects' },
+    { id: 'team', icon: 'group', text: 'Team' },
+    { id: 'settings', icon: 'settings', text: 'Settings' },
+  ];
+
+  return (
+    <View style={{ padding: 16, gap: 8 }}>
+      {navItems.map((item) => (
+        <TapasAnimatedNavItem
+          key={item.id}
+          id={item.id}
+          icon={item.icon}
+          text={item.text}
+          expanded={isWideScreen}
+          selected={selectedItem === item.id}
+          onPress={(id) => setSelectedItem(id as string)}
+          height={isWideScreen ? 48 : 40}
+          iconSize={isWideScreen ? 24 : 20}
+        />
+      ))}
+    </View>
+  );
+};
+```
+
+### 长按菜单
+
+```tsx
+import React, { useState } from 'react';
+import { Alert } from 'react-native';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const LongPressMenuExample = () => {
+  const [expanded, setExpanded] = useState(true);
+  
+  const handlePress = (id: string) => {
+    console.log(`Item ${id} pressed`);
+  };
+  
+  const handleLongPress = (id: string) => {
+    Alert.alert(
+      'Context Menu',
+      `Long pressed ${id}`,
+      [
+        { text: 'Edit', onPress: () => console.log('Edit', id) },
+        { text: 'Delete', onPress: () => console.log('Delete', id) },
+        { text: 'Cancel', style: 'cancel' },
+      ]
+    );
+  };
+
+  return (
+    <TapasAnimatedNavItem 
+      id="contextual"
+      icon="more_vert" 
+      text="Long Press Me"
+      expanded={expanded}
+      onPress={handlePress}
+      onLongPress={handleLongPress}
+    />
+  );
+};
+```
+
+### 禁用状态
+
+```tsx
+import React from 'react';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const DisabledExample = () => {
+  return (
+    <View style={{ gap: 12 }}>
+      <TapasAnimatedNavItem 
+        icon="check" 
+        text="Enabled"
+        expanded={true}
+        disabled={false}
+      />
+      
+      <TapasAnimatedNavItem 
+        icon="block" 
+        text="Disabled"
+        expanded={true}
+        disabled={true}
+      />
+    </View>
+  );
+};
+```
+
+### 动态宽度计算
+
+```tsx
+import React, { useState } from 'react';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const DynamicWidthExample = () => {
+  const [expanded, setExpanded] = useState(false);
+  
+  const items = [
+    { text: 'Short', icon: 'home' },
+    { text: 'Medium Length', icon: 'dashboard' },
+    { text: 'Very Long Text Content', icon: 'analytics' },
+  ];
+
+  return (
+    <View style={{ gap: 12 }}>
+      {items.map((item, index) => (
+        <TapasAnimatedNavItem
+          key={index}
+          icon={item.icon}
+          text={item.text}
+          expanded={expanded}
+          onPress={() => setExpanded(!expanded)}
+          // 让组件自动计算最大宽度
+        />
+      ))}
+    </View>
+  );
+};
+```
+
+### 自定义内边距
+
+```tsx
+import React from 'react';
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+const CustomPaddingExample = () => {
+  return (
+    <View style={{ gap: 12 }}>
+      {/* 紧凑型 */}
+      <TapasAnimatedNavItem 
+        icon="compress" 
+        text="Compact"
+        expanded={true}
+        padding={{ horizontal: 8, vertical: 0 }}
+        height={32}
+        iconSize={16}
+      />
+      
+      {/* 标准型 */}
+      <TapasAnimatedNavItem 
+        icon="crop_free" 
+        text="Standard"
+        expanded={true}
+        padding={{ horizontal: 12, vertical: 0 }}
+        height={40}
+        iconSize={20}
+      />
+      
+      {/* 宽松型 */}
+      <TapasAnimatedNavItem 
+        icon="open_in_full" 
+        text="Spacious"
+        expanded={true}
+        padding={{ horizontal: 20, vertical: 4 }}
+        height={56}
+        iconSize={24}
+      />
+    </View>
+  );
+};
+```
+
+## 动画机制
+
+组件使用 React Native 的 `Animated.timing` 实现平滑的宽度过渡：
+
+### 宽度计算
+- **收缩状态**: 使用 `minWidth` 属性
+- **展开状态**: 使用 `maxWidth` 属性，或自动计算（文本宽度 + 图标宽度 + 内边距）
+
+### 动画配置
+```tsx
+Animated.timing(widthAnim, {
+  toValue: expanded ? maxWidth : minWidth,
+  duration: animationDuration,
+  useNativeDriver: false, // 宽度动画不支持原生驱动
+}).start();
+```
+
+### 性能优化
+- 使用 `useRef` 缓存动画值
+- 使用 `useCallback` 优化事件处理函数
+- 支持 `useNativeDriver: false` 的宽度动画
+
+## 主题集成
+
+组件会自动使用应用主题的以下属性：
+
+```tsx
+// 默认样式
+{
+  iconColor: theme?.colors?.primary,
+  expandedIconColor: theme?.colors?.white,
+  textColor: theme?.colors?.white,
+  expandedBackgroundColor: theme?.colors?.primary,
+}
+```
+
+可以通过相应的props覆盖主题样式：
+
+```tsx
+<TapasAnimatedNavItem 
+  icon="star"
+  text="Custom Theme"
+  iconColor="#custom-color"
+  expandedBackgroundColor="#custom-bg"
+/>
+```
+
+## 可访问性支持
+
+组件继承了 `Pressable` 的所有可访问性属性：
+
+```tsx
+<TapasAnimatedNavItem 
+  icon="accessibility"
+  text="Accessible Item"
+  expanded={true}
+  accessible={true}
+  accessibilityRole="button"
+  accessibilityLabel="Navigate to accessibility settings"
+  accessibilityHint="Double tap to open accessibility settings"
+  accessibilityState={{ selected: isSelected }}
+/>
+```
+
+## 最佳实践
+
+1. **性能优化**
+   - 为频繁切换的导航项设置合理的 `animationDuration`
+   - 避免在动画期间频繁更新其他状态
+
+2. **用户体验**
+   - 保持一致的动画速度（推荐 200-400ms）
+   - 为重要操作提供视觉反馈（selected 状态）
+   - 合理设置最小宽度，确保图标完全可见
+
+3. **响应式设计**
+   - 在小屏幕设备上考虑使用更小的图标和高度
+   - 根据屏幕宽度动态调整展开状态
+
+4. **颜色搭配**
+   - 确保文本和背景色有足够的对比度
+   - 在深色主题下测试颜色效果
+
+5. **交互设计**
+   - 为重要操作同时提供点击和长按选项
+   - 合理使用禁用状态，并提供视觉反馈
+
+## 向后兼容
+
+为了确保向后兼容，组件同时导出了以下别名：
+
+```tsx
+// 新的推荐用法
+import { TapasAnimatedNavItem } from '@beppla/tapas-ui';
+
+// 向后兼容的用法
+import { AnimatedNavItem } from '@beppla/tapas-ui';
+```
+
+## 使用场景
+
+- 侧边导航菜单
+- 底部标签栏
+- 工具栏按钮
+- 面包屑导航
+- 快速操作按钮
+- 状态切换器
+
+## 注意事项
+
+1. 文本只在展开状态下显示，收缩时仅显示图标
+2. 组件会自动计算最大宽度，但也可以手动指定
+3. 动画使用宽度变化，不支持原生驱动
+4. 长文本会自动截断并显示省略号
+5. 组件支持React Native和React Native Web环境
+6. 建议为每个导航项设置唯一的 `id` 属性以便跟踪

package/package/module/BarChart/README.md

@@ -0,0 +1,172 @@
+# BarChart
+
+柱状图组件，支持垂直/水平方向、堆叠/分组模式、柱线混合图等多种展示方式。采用**双平台渲染**策略：Web 端使用 recharts，Native 端使用 react-native-svg-charts。
+
+## 功能特性
+
+- ✅ **双平台渲染**：Web 使用 recharts（功能完整），Native 使用 react-native-svg-charts（基础功能）
+- ✅ 支持垂直和水平方向柱状图
+- ✅ 支持堆叠（stacked）和分组（grouped）模式
+- ✅ 支持柱状图 + 折线图混合展示（lineSeries，自动切换 ComposedChart）
+- ✅ 自定义颜色：单色、多色方案、每柱独立颜色
+- ✅ 显示网格线和数值标签
+- ✅ 图例支持 top / bottom / left / right 四个位置
+- ✅ X 轴标签旋转角度和显示间隔控制
+- ✅ Y 轴 / X 轴格式化函数
+- ✅ 柱条点击事件（Web 和 Native 均支持）
+- ✅ 响应式容器（Web 端 ResponsiveContainer）
+- ✅ 空数据友好提示
+
+## 安装使用
+
+```tsx
+import { BarChart } from '@beppla/tapas-ui/components/BarChart';
+```
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| data | `BarChartData[] \| { categories: string[]; series: BarChartSeriesData[] }` | (必填) | 数据源，简单数组或多系列格式 |
+| width | `number` | - | 图表宽度，不设时为 100% |
+| height | `number` | `300` | 图表高度 |
+| color | `string` | `'#FF6B00'` | 单色模式下的柱条颜色 |
+| colors | `string[]` | - | 多色方案 |
+| showGrid | `boolean` | `true` | 是否显示网格线 |
+| showLabels | `boolean` | `true` | 是否显示 X 轴标签 |
+| showValues | `boolean` | `false` | 是否在柱条上显示数值 |
+| horizontal | `boolean` | `false` | 是否横向显示（条形图） |
+| stacked | `boolean` | `false` | 是否堆叠显示（多系列数据） |
+| showLegend | `boolean` | `false` | 是否显示图例 |
+| legendPosition | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 图例位置 |
+| lineSeries | `BarChartLineSeriesData[]` | - | 折线图数据系列，实现柱线混合 |
+| xAxisAngle | `number` | `0` | X 轴标签旋转角度（负数逆时针） |
+| xAxisInterval | `number \| 'preserveStartEnd' \| 'preserveStart' \| 'preserveEnd'` | - | X 轴标签显示间隔 |
+| contentInset | `{ top?: number; bottom?: number; left?: number; right?: number }` | `{ top: 20, bottom: 20, left: 20, right: 20 }` | 内容边距 |
+| yAxisFormat | `(value: number) => string` | `(value) => value.toString()` | Y 轴格式化函数 |
+| xAxisFormat | `(value: number, index: number) => string` | - | X 轴格式化函数（Native 端） |
+| onBarPress | `(data: BarChartData, index: number) => void` | - | 柱条点击回调 |
+| style | `any` | - | 容器样式 |
+| testID | `string` | - | 测试标识 |
+
+### BarChartData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| value | `number` | 数值（必填） |
+| label | `string` | 标签 |
+| color | `string` | 单柱自定义颜色 |
+
+### BarChartSeriesData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | `string` | 系列名称（必填） |
+| data | `number[]` | 数据数组（必填） |
+| color | `string` | 系列颜色 |
+
+### BarChartLineSeriesData
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | `string` | 系列名称（必填） |
+| data | `number[]` | 数据数组（必填） |
+| color | `string` | 线条颜色 |
+| strokeWidth | `number` | 线条宽度（默认 2） |
+| dotRadius | `number` | 数据点半径（默认 4） |
+| activeDotRadius | `number` | 活动数据点半径（默认 6） |
+| hideDot | `boolean` | 是否隐藏数据点 |
+
+## 使用示例
+
+### 基础柱状图
+
+```tsx
+<BarChart
+  data={[
+    { value: 50, label: 'Jan' },
+    { value: 75, label: 'Feb' },
+    { value: 100, label: 'Mar' },
+  ]}
+  height={300}
+  color="#FF6B00"
+/>
+```
+
+### 堆叠柱状图
+
+```tsx
+<BarChart
+  data={{
+    categories: ['Store A', 'Store B', 'Store C'],
+    series: [
+      { name: 'Cash', data: [50000, 75000, 100000], color: '#8B4513' },
+      { name: 'Card', data: [20000, 30000, 40000], color: '#4A90E2' },
+    ],
+  }}
+  stacked
+  showLegend
+  height={400}
+/>
+```
+
+### 柱状图 + 折线图组合
+
+```tsx
+<BarChart
+  data={[
+    { value: 850000, label: 'Store A' },
+    { value: 680000, label: 'Store B' },
+  ]}
+  lineSeries={[
+    {
+      name: 'Consumption costs',
+      data: [15000, 12000],
+      color: '#D63031',
+      strokeWidth: 2,
+      dotRadius: 4,
+    },
+  ]}
+  showLegend
+  color="#FFB800"
+  height={400}
+/>
+```
+
+### 长标签旋转 + Y 轴格式化
+
+```tsx
+<BarChart
+  data={{
+    categories: ['Store name A', 'Store name B', 'Store name C'],
+    series: [{ name: 'Revenue', data: [850000, 680000, 730000], color: '#FFB800' }],
+  }}
+  xAxisAngle={-45}
+  yAxisFormat={(v) => v >= 1000 ? `${(v / 1000).toFixed(0)}k` : v.toString()}
+  height={500}
+/>
+```
+
+### 柱条点击事件
+
+```tsx
+<BarChart
+  data={[
+    { value: 50, label: 'Item 1' },
+    { value: 75, label: 'Item 2' },
+  ]}
+  onBarPress={(data, index) => {
+    console.log(`Clicked: ${data.label} = ${data.value}`);
+  }}
+/>
+```
+
+## 注意事项
+
+- **双平台渲染**：Web 端使用 recharts（完整功能），Native 端使用 react-native-svg-charts（基础功能）
+- Native 端**不支持**堆叠数据格式（`{ categories, series }`），会显示提示信息
+- Native 端**不支持** lineSeries 混合折线图
+- `lineSeries` 存在时自动切换为 recharts ComposedChart 渲染
+- 堆叠数据或有 lineSeries 时自动显示图例（无需设置 showLegend）
+- X 轴标签旋转时，底部 margin 会自动调整以避免标签被截断
+- 需安装对应平台依赖：Web 需要 `recharts`，Native 需要 `react-native-svg-charts` + `react-native-svg`