@beppla/tapas-ui 1.4.35 → 1.5.2

package/package/module/AnimatedNavItem/README.md

@@ -1,520 +0,0 @@
-# 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` 属性以便跟踪