@beppla/tapas-ui 1.4.13 → 1.4.15

package/package/init.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Tapas UI 初始化脚本
+ * 自动配置项目所需的资源文件和目录结构
+ * 参考 tapas-orderly-client 标准模板
+ */
+
+console.log('🚀 正在初始化 Tapas UI 项目...');
+
+// 获取当前工作目录
+const cwd = process.cwd();
+
+// 检查是否在正确的项目目录中
+function validateProjectStructure() {
+  const requiredFiles = ['package.json'];
+  const missingFiles = requiredFiles.filter(file => !fs.existsSync(path.join(cwd, file)));
+  
+  if (missingFiles.length > 0) {
+    console.error('❌ 错误：请在项目根目录中运行此脚本');
+    console.error(`   缺少文件: ${missingFiles.join(', ')}`);
+    process.exit(1);
+  }
+  
+  // 检查 package.json 是否包含必要的依赖
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    const hasReactNative = packageJson.dependencies?.['react-native'] || packageJson.devDependencies?.['react-native'];
+    const hasExpo = packageJson.dependencies?.['expo'] || packageJson.devDependencies?.['expo'];
+    
+    if (!hasReactNative && !hasExpo) {
+      console.warn('⚠️  警告：未检测到 React Native 或 Expo 依赖');
+      console.warn('   请确保在 React Native 或 Expo 项目中使用 Tapas UI');
+    }
+  } catch (error) {
+    console.warn('⚠️  警告：无法解析 package.json');
+  }
+}
+
+// 创建目录结构
+function createDirectoryStructure() {
+  const directories = [
+    'public',
+    'public/assets',
+    'public/assets/fonts',
+    'src',
+    'src/components',
+    'src/screens',
+    'src/hooks',
+    'src/utils',
+    'src/types',
+    'src/constants',
+    'src/services',
+    'src/state',
+    'src/styles',
+    'src/__tests__',
+    'src/__tests__/components',
+    'src/__tests__/hooks',
+    'src/__tests__/utils',
+    'src/__tests__/integration',
+    'src/__tests__/e2e',
+    'assets',
+    'assets/fonts',
+    'assets/images',
+    'assets/icons',
+    'config',
+    'locales',
+    'docs',
+    'scripts'
+  ];
+  
+  console.log('📁 创建项目目录结构...');
+  
+  directories.forEach(dir => {
+    const fullPath = path.join(cwd, dir);
+    if (!fs.existsSync(fullPath)) {
+      fs.mkdirSync(fullPath, { recursive: true });
+      console.log(`   ✅ 创建目录: ${dir}`);
+    } else {
+      console.log(`   📁 目录已存在: ${dir}`);
+    }
+  });
+}
+
+// 复制资源文件
+function copyResourceFiles() {
+  const resourceFiles = [
+    {
+      source: path.join(__dirname, 'assets', 'fonts', 'customfont.ttf'),
+      dest: path.join(cwd, 'public', 'customfont.ttf'),
+      description: 'Tapas UI 图标字体文件'
+    },
+    {
+      source: path.join(__dirname, 'assets', 'assets', 'fonts', 'customfont.ttf'),
+      dest: path.join(cwd, 'public', 'assets', 'fonts', 'customfont.ttf'),
+      description: 'Tapas UI 图标字体文件（备用路径）'
+    },
+    {
+      source: path.join(__dirname, 'assets', 'fonts', 'customfont.ttf'),
+      dest: path.join(cwd, 'assets', 'fonts', 'customfont.ttf'),
+      description: 'Tapas UI 图标字体文件（本地资源）'
+    }
+  ];
+  
+  console.log('📦 复制资源文件...');
+  
+  let successCount = 0;
+  resourceFiles.forEach(file => {
+    if (copyFile(file.source, file.dest, file.description)) {
+      successCount++;
+    }
+  });
+  
+  return successCount;
+}
+
+// 复制文件
+function copyFile(source, dest, description) {
+  try {
+    if (!fs.existsSync(source)) {
+      console.warn(`   ⚠️  源文件不存在: ${source}`);
+      return false;
+    }
+    
+    // 确保目标目录存在
+    const destDir = path.dirname(dest);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+    
+    fs.copyFileSync(source, dest);
+    console.log(`   ✅ 复制 ${description}: ${path.relative(cwd, dest)}`);
+    return true;
+  } catch (error) {
+    console.error(`   ❌ 复制失败 ${description}:`, error.message);
+    return false;
+  }
+}
+
+// 主初始化流程
+async function initializeTapasUIProject() {
+  try {
+    console.log('🔍 验证项目结构...');
+    validateProjectStructure();
+    
+    console.log('📁 创建目录结构...');
+    createDirectoryStructure();
+    
+    console.log('📦 复制资源文件...');
+    const resourceSuccessCount = copyResourceFiles();
+    
+    console.log('\n🎉 Tapas UI 项目初始化完成！');
+    console.log('\n📋 下一步操作:');
+    console.log('1. 运行 yarn install 安装依赖');
+    console.log('2. 开始使用 Tapas UI 组件开发');
+    console.log('\n🔍 故障排除:');
+    console.log('- 如果图标不显示，请检查字体文件是否正确复制');
+    console.log('- 确保在 React Native 或 Expo 项目中使用');
+    console.log('\n📚 文档链接:');
+    console.log('- Tapas UI Storybook: https://dev.tapas-ui.dev/storybook');
+    console.log('- React Native 文档: https://reactnative.dev/');
+    console.log('- Expo 文档: https://docs.expo.dev/');
+    
+    if (resourceSuccessCount === 0) {
+      console.log('\n⚠️  警告：资源文件复制失败');
+      console.log('请手动复制字体文件到 public/ 目录');
+    }
+    
+  } catch (error) {
+    console.error('💥 初始化过程中发生错误:', error);
+    process.exit(1);
+  }
+}
+
+// 运行初始化
+initializeTapasUIProject();

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` 属性以便跟踪