@umituz/react-native-settings 4.20.58 → 4.20.60

package/src/domains/video-tutorials/README.md

@@ -1,475 +1,82 @@
 # Video Tutorials Domain
 
-The Video Tutorials domain provides components for displaying and managing video tutorials in your React Native app. It supports featured tutorials, categorized lists, and external video linking.
-
-## Features
-
-- **Video Tutorials Screen**: Full-screen viewer for tutorial collections
-- **Featured Tutorials**: Horizontal scrolling list for featured content
-- **Tutorial Cards**: Rich cards with thumbnails, titles, and metadata
-- **Categorized Sections**: Organize tutorials by topic or category
-- **Loading States**: Built-in loading and empty states
-- **External Video Support**: Link to YouTube, Vimeo, and other platforms
-
-## Installation
-
-This domain is part of `@umituz/react-native-settings`. Install the package to use it:
-
-```bash
-npm install @umituz/react-native-settings
-```
-
-## Components
-
-### VideoTutorialsScreen
-
-Main screen for displaying video tutorials with featured and all tutorials sections.
-
-```tsx
-import { VideoTutorialsScreen } from '@umituz/react-native-settings';
-
-function MyVideoTutorials() {
-  const tutorials = [
-    {
-      id: '1',
-      title: 'Getting Started',
-      description: 'Learn the basics',
-      thumbnailUrl: 'https://example.com/thumb1.jpg',
-      videoUrl: 'https://youtube.com/watch?v=xxx',
-      duration: '5:30',
-      category: 'Basics',
-    },
-    // ... more tutorials
-  ];
-
-  return (
-    <VideoTutorialsScreen
-      tutorials={tutorials}
-      featuredTutorials={tutorials.slice(0, 3)}
-      title="Video Tutorials"
-      onTutorialPress={(tutorial) => {
-        // Open video player or navigate
-        openVideo(tutorial.videoUrl);
-      }}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `tutorials` | `VideoTutorial[]` | **Required** | All tutorials to display |
-| `featuredTutorials` | `VideoTutorial[]` | `undefined` | Featured tutorials |
-| `title` | `string` | `'Video Tutorials'` | Screen title |
-| `featuredTitle` | `string` | `'Featured'` | Featured section title |
-| `allTutorialsTitle` | `string` | `'All Tutorials'` | All tutorials section title |
-| `emptyMessage` | `string` | `'No tutorials available'` | Empty state message |
-| `isLoading` | `boolean` | `false` | Loading state |
-| `onTutorialPress` | `(tutorial) => void` | `undefined` | Tutorial press handler |
-
-### VideoTutorialCard
-
-Individual tutorial card with thumbnail, title, and metadata.
-
-```tsx
-import { VideoTutorialCard } from '@umituz/react-native-settings';
-
-function MyTutorialCard() {
-  const tutorial = {
-    id: '1',
-    title: 'Tutorial Title',
-    description: 'Tutorial description',
-    thumbnailUrl: 'https://example.com/thumb.jpg',
-    videoUrl: 'https://youtube.com/watch?v=xxx',
-    duration: '10:25',
-    views: 1500,
-  };
-
-  return (
-    <VideoTutorialCard
-      tutorial={tutorial}
-      onPress={() => console.log('Play video')}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `tutorial` | `VideoTutorial` | **Required** | Tutorial data |
-| `onPress` | `() => void` | **Required** | Press handler |
-| `horizontal` | `boolean` | `false` | Horizontal card variant |
-
-### VideoTutorialSection
-
-Section component for grouping tutorials by category.
-
-```tsx
-import { VideoTutorialSection } from '@umituz/react-native-settings';
-
-function MyTutorialSection() {
-  const tutorials = [ /* tutorial data */ ];
-
-  return (
-    <VideoTutorialSection
-      title="Getting Started"
-      tutorials={tutorials}
-      onTutorialPress={(tutorial) => playVideo(tutorial)}
-    />
-  );
-}
-```
-
-#### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | **Required** | Section title |
-| `tutorials` | `VideoTutorial[]` | **Required** | Tutorials in section |
-| `onTutorialPress` | `(tutorial) => void` | **Required** | Tutorial press handler |
-
-## Types
-
-### VideoTutorial
-
-```typescript
-interface VideoTutorial {
-  id: string;
-  title: string;
-  description?: string;
-  thumbnailUrl?: string;
-  videoUrl: string;
-  duration?: string;
-  views?: number;
-  category?: string;
-  publishedAt?: string;
-  author?: string;
-}
-```
-
-## Examples
-
-### Basic Video Tutorials Screen
-
-```tsx
-import React from 'react';
-import { VideoTutorialsScreen } from '@umituz/react-native-settings';
-
-const TUTORIALS = [
-  {
-    id: '1',
-    title: 'Introduction to the App',
-    description: 'Learn the basic features',
-    thumbnailUrl: 'https://picsum.photos/300/200?random=1',
-    videoUrl: 'https://youtube.com/watch?v=abc123',
-    duration: '5:30',
-    category: 'Getting Started',
-    views: 12500,
-  },
-  {
-    id: '2',
-    title: 'Advanced Features',
-    description: 'Master advanced functionality',
-    thumbnailUrl: 'https://picsum.photos/300/200?random=2',
-    videoUrl: 'https://youtube.com/watch?v=def456',
-    duration: '12:45',
-    category: 'Advanced',
-    views: 8300,
-  },
-  {
-    id: '3',
-    title: 'Tips and Tricks',
-    description: 'Helpful tips for power users',
-    thumbnailUrl: 'https://picsum.photos/300/200?random=3',
-    videoUrl: 'https://youtube.com/watch?v=ghi789',
-    duration: '8:15',
-    category: 'Tips',
-    views: 15600,
-  },
-];
-
-export default function TutorialsScreen() {
-  return (
-    <VideoTutorialsScreen
-      tutorials={TUTORIALS}
-      featuredTutorials={TUTORIALS.slice(0, 2)}
-      title="Help & Tutorials"
-      featuredTitle="Featured Videos"
-      allTutorialsTitle="All Tutorials"
-      onTutorialPress={(tutorial) => {
-        // Open in WebView or navigate to video player
-        navigation.navigate('VideoPlayer', { tutorial });
-      }}
-    />
-  );
-}
-```
-
-### With Loading State
-
-```tsx
-function TutorialsScreenWithLoading() {
-  const [tutorials, setTutorials] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    loadTutorials();
-  }, []);
-
-  const loadTutorials = async () => {
-    try {
-      const data = await api.fetchTutorials();
-      setTutorials(data);
-    } catch (error) {
-      console.error('Failed to load tutorials:', error);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <VideoTutorialsScreen
-      tutorials={tutorials}
-      isLoading={loading}
-      onTutorialPress={handleTutorialPress}
-    />
-  );
-}
-```
-
-### Custom Empty State
-
-```tsx
-function EmptyTutorialsScreen() {
-  return (
-    <VideoTutorialsScreen
-      tutorials={[]}
-      emptyMessage="No tutorials available right now. Check back later!"
-      onTutorialPress={() => {}}
-    />
-  );
-}
-```
-
-### With Video Player Integration
-
-```tsx
-import { VideoTutorialsScreen } from '@umituz/react-native-settings';
-import { WebView } from 'react-native-webview';
-
-function TutorialsWithPlayer() {
-  const [selectedTutorial, setSelectedTutorial] = useState(null);
-
-  if (selectedTutorial) {
-    return (
-      <WebView
-        source={{ uri: selectedTutorial.videoUrl }}
-        style={{ flex: 1 }}
-      />
-    );
-  }
-
-  return (
-    <VideoTutorialsScreen
-      tutorials={TUTORIALS}
-      onTutorialPress={setSelectedTutorial}
-    />
-  );
-}
-```
-
-### Using Tutorial Cards Directly
-
-```tsx
-import { VideoTutorialCard } from '@umituz/react-native-settings';
-import { ScrollView } from 'react-native';
-
-function CustomTutorialsList() {
-  return (
-    <ScrollView>
-      {TUTORIALS.map((tutorial) => (
-        <VideoTutorialCard
-          key={tutorial.id}
-          tutorial={tutorial}
-          onPress={() => playVideo(tutorial)}
-        />
-      ))}
-    </ScrollView>
-  );
-}
-```
-
-### Horizontal Featured Section
-
-```tsx
-function FeaturedSection() {
-  const featuredTutorials = TUTORIALS.filter(t => t.featured);
-
-  return (
-    <View>
-      <Text style={{ fontSize: 20, fontWeight: 'bold', marginBottom: 12 }}>
-        Featured Tutorials
-      </Text>
-      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
-        {featuredTutorials.map((tutorial) => (
-          <View key={tutorial.id} style={{ marginRight: 12 }}>
-            <VideoTutorialCard
-              tutorial={tutorial}
-              horizontal={true}
-              onPress={() => playVideo(tutorial)}
-            />
-          </View>
-        ))}
-      </ScrollView>
-    </View>
-  );
-}
-```
-
-### Categorized Tutorials
-
-```tsx
-function CategorizedTutorialsScreen() {
-  const categories = {
-    'Getting Started': TUTORIALS.filter(t => t.category === 'Getting Started'),
-    'Advanced': TUTORIALS.filter(t => t.category === 'Advanced'),
-    'Tips': TUTORIALS.filter(t => t.category === 'Tips'),
-  };
-
-  return (
-    <ScrollView>
-      {Object.entries(categories).map(([category, tutorials]) => (
-        <VideoTutorialSection
-          key={category}
-          title={category}
-          tutorials={tutorials}
-          onTutorialPress={playVideo}
-        />
-      ))}
-    </ScrollView>
-  );
-}
-```
-
-### With Search
-
-```tsx
-function SearchableTutorials() {
-  const [searchQuery, setSearchQuery] = useState('');
-  const [filteredTutorials, setFilteredTutorials] = useState(TUTORIALS);
-
-  useEffect(() => {
-    if (searchQuery.trim() === '') {
-      setFilteredTutorials(TUTORIALS);
-    } else {
-      const filtered = TUTORIALS.filter(t =>
-        t.title.toLowerCase().includes(searchQuery.toLowerCase()) ||
-        t.description?.toLowerCase().includes(searchQuery.toLowerCase())
-      );
-      setFilteredTutorials(filtered);
-    }
-  }, [searchQuery]);
-
-  return (
-    <View>
-      <TextInput
-        value={searchQuery}
-        onChangeText={setSearchQuery}
-        placeholder="Search tutorials..."
-        style={{ padding: 12, backgroundColor: '#FFF' }}
-      />
-
-      <VideoTutorialsScreen
-        tutorials={filteredTutorials}
-        onTutorialPress={playVideo}
-      />
-    </View>
-  );
-}
-```
-
-## Architecture
-
-```
-src/domains/video-tutorials/
-├── types/
-│   └── index.ts                    # VideoTutorial types
-├── presentation/
-│   ├── screens/
-│   │   └── VideoTutorialsScreen.tsx
-│   └── components/
-│       ├── VideoTutorialCard.tsx
-│       └── VideoTutorialSection.tsx
-└── index.ts                        # Public API exports
-```
-
-## Best Practices
-
-1. **Quality Thumbnails**: Use high-quality, consistent thumbnail sizes
-2. **Accurate Metadata**: Keep duration and view counts up to date
-3. **Categorization**: Organize tutorials logically for easy browsing
-4. **Featured Content**: Highlight important or new tutorials
-5. **Loading States**: Show proper loading indicators for better UX
-6. **Error Handling**: Handle video playback errors gracefully
-7. **Offline Support**: Consider caching video information for offline viewing
-8. **Progress Tracking**: Track which tutorials users have watched
-
-## Testing
-
-```tsx
-import { render, fireEvent } from '@testing-library/react-native';
-import { VideoTutorialsScreen } from '@umituz/react-native-settings';
-
-describe('VideoTutorialsScreen', () => {
-  const tutorials = [
-    {
-      id: '1',
-      title: 'Test Tutorial',
-      videoUrl: 'https://youtube.com/watch?v=test',
-    },
-  ];
-
-  it('renders tutorials list', () => {
-    const { getByText } = render(
-      <VideoTutorialsScreen
-        tutorials={tutorials}
-        onTutorialPress={() => {}}
-      />
-    );
-
-    expect(getByText('Test Tutorial')).toBeTruthy();
-  });
-
-  it('calls onTutorialPress when tutorial is pressed', () => {
-    const mockPress = jest.fn();
-    const { getByText } = render(
-      <VideoTutorialsScreen
-        tutorials={tutorials}
-        onTutorialPress={mockPress}
-      />
-    );
-
-    fireEvent.press(getByText('Test Tutorial'));
-    expect(mockPress).toHaveBeenCalledWith(tutorials[0]);
-  });
-
-  it('shows empty state when no tutorials', () => {
-    const { getByText } = render(
-      <VideoTutorialsScreen
-        tutorials={[]}
-        emptyMessage="No tutorials found"
-        onTutorialPress={() => {}}
-      />
-    );
-
-    expect(getByText('No tutorials found')).toBeTruthy();
-  });
-});
-```
+## Purpose
+
+Provides components for displaying and managing video tutorials with featured sections, categorized lists, thumbnails, and external video linking.
+
+## File Paths
+
+**Screens:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/video-tutorials/presentation/screens/VideoTutorialsScreen.tsx`
+
+**Components:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/video-tutorials/presentation/components/VideoTutorialCard.tsx`
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/video-tutorials/presentation/components/VideoTutorialSection.tsx`
+
+**Types:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/video-tutorials/types/index.ts`
+
+**Index:**
+- `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/domains/video-tutorials/index.ts`
+
+## Strategy
+
+1. **Featured Content**: Display featured tutorials in horizontal scrolling section for prominence
+2. **Categorization**: Organize tutorials by category for better navigation
+3. **Rich Metadata**: Include thumbnails, duration, views, and descriptions for better UX
+4. **External Linking**: Support linking to YouTube, Vimeo, and other platforms
+5. **Loading States**: Show proper loading and empty states for better UX
+
+## Restrictions (Forbidden)
+
+### DO NOT
+- ❌ DO NOT use VideoTutorialsScreen without providing tutorials array
+- ❌ DO NOT display tutorials without proper thumbnails
+- ❌ DO NOT bypass loading states when tutorials are being fetched
+- ❌ DO NOT mix video tutorial logic with other business logic
+
+### NEVER
+- ❌ NEVER use VideoTutorialCard without required tutorial data (id, title, videoUrl)
+- ❌ NEVER embed video players directly - link to external platforms
+- ❌ NEVER show tutorials without proper error handling
+- ❌ NEVER create custom tutorial card components when VideoTutorialCard exists
+
+### AVOID
+- ❌ AVOID hardcoding tutorial data in components - always pass as props
+- ❌ AVOID using inconsistent thumbnail sizes
+- ❌ AVOID creating custom tutorial lists when VideoTutorialsScreen can be configured
+- ❌ AVOID mixing video playback logic with tutorial display logic
+
+## Rules
+
+### ALWAYS
+- ✅ ALWAYS provide tutorials array with at least id, title, and videoUrl
+- ✅ ALWAYS provide onTutorialPress handler for tutorial cards
+- ✅ ALWAYS handle loading states with isLoading prop
+- ✅ ALWAYS provide empty state message when no tutorials available
+- ✅ ALWAYS use consistent thumbnail sizes across all tutorials
+
+### MUST
+- ✅ MUST provide unique id for each tutorial
+- ✅ MUST include videoUrl for all tutorials
+- ✅ MUST provide proper metadata (thumbnailUrl, duration, views, category)
+- ✅ MUST handle video playback errors gracefully
+- ✅ MUST use VideoTutorial types for type safety
+
+### SHOULD
+- ✅ SHOULD use high-quality, consistent thumbnail sizes
+- ✅ SHOULD keep metadata accurate and up to date
+- ✅ SHOULD organize tutorials logically by category
+- ✅ SHOULD highlight important or new tutorials in featured section
+- ✅ SHOULD support offline viewing by caching tutorial information
+
+## AI Agent Guidelines
+
+1. **Component Selection**: Use VideoTutorialsScreen for full screens, VideoTutorialCard for individual cards, VideoTutorialSection for categorized sections
+2. **Data Structure**: Always structure tutorial data with id, title, videoUrl, and optional metadata
+3. **External Playback**: Always link to external platforms (YouTube, Vimeo) - never embed players directly
+4. **Loading States**: Always show proper loading indicators when fetching tutorials
+5. **Metadata**: Always include rich metadata (thumbnails, duration, views) for better UX
 
 ## Related