devendra-skill-package 1.0.2

package/.github/skills/feature-generator/references/screen-logic-patterns.md

@@ -0,0 +1,399 @@
+# Screen Logic Patterns Reference
+
+Used by Phase 7.3 of feature-generator.
+Each pattern below corresponds to a phrase in the spec `Screen Logic` section.
+Patterns are combined in the screen component — they are not mutually exclusive.
+
+---
+
+## Pattern: Fetch on screen mount
+
+**Spec phrase**: "Fetch data on screen mount", "Load data when screen opens"
+
+```typescript
+const dispatch = useDispatch<AppDispatch>();
+
+useEffect(() => {
+  dispatch(fetch<ScreenName>Thunk({ clientCode, sessionId }));
+}, [dispatch, clientCode, sessionId]);
+```
+
+**For Zustand:**
+```typescript
+const fetch<ScreenName> = use<ScreenName>Store((state) => state.fetch<ScreenName>);
+
+useEffect(() => {
+  void fetch<ScreenName>({ clientCode, sessionId });
+}, [fetch<ScreenName>, clientCode, sessionId]);
+```
+
+**For React Query / RTK Query:**
+```typescript
+// No useEffect needed — the query hook fetches automatically on mount
+const { data, isLoading, error, refetch } = use<ScreenName>({ clientCode, sessionId });
+```
+
+---
+
+## Pattern: Pull to refresh
+
+**Spec phrase**: "Support pull-to-refresh", "Refresh on pull"
+
+```typescript
+// State
+const isRefreshing = useSelector(select<ScreenName>IsRefreshing);
+
+const handleRefresh = useCallback(() => {
+  dispatch(refresh<ScreenName>Thunk({ clientCode, sessionId }));
+}, [dispatch, clientCode, sessionId]);
+
+// JSX — add to FlatList or ScrollView
+<FlatList
+  data={items}
+  refreshControl={
+    <RefreshControl
+      refreshing={isRefreshing}
+      onRefresh={handleRefresh}
+      tintColor="#02168b"
+      colors={['#02168b']}
+    />
+  }
+  // ...
+/>
+```
+
+**Notes:**
+- The `refresh<ScreenName>Thunk` sets `isRefreshing` (not `isLoading`) in the slice.
+- The thunk body is identical to `fetch<ScreenName>Thunk` — only the pending handler differs.
+- If the state lib has no separate refresh thunk (Zustand, Context, MobX), use a
+  local boolean state for `isRefreshing` and call the same fetch action.
+
+---
+
+## Pattern: Navigate to detail on tap
+
+**Spec phrase**: "Navigate to DetailScreen when user taps a row",
+"Tap a row to open detail"
+
+```typescript
+// For react-navigation (fingerprint.navLib = "react-navigation")
+import { useNavigation } from '@react-navigation/native';
+import type { NativeStackNavigationProp } from '@react-navigation/native-stack';
+import type { <NavParamsPattern> } from '<relative-path-to-routes>';
+
+type NavProp = NativeStackNavigationProp<<NavParamsPattern>>;
+
+// Inside component:
+const navigation = useNavigation<NavProp>();
+
+const handleItemPress = useCallback((item: <ScreenName>Item) => {
+  navigation.navigate('<TargetScreenName>', { itemId: item.id });
+}, [navigation]);
+
+// In FlatList renderItem:
+<Pressable onPress={() => handleItemPress(item)}>
+  {/* row content */}
+</Pressable>
+```
+
+```typescript
+// For expo-router (fingerprint.navLib = "expo-router")
+import { useRouter } from 'expo-router';
+
+const router = useRouter();
+
+const handleItemPress = useCallback((item: <ScreenName>Item) => {
+  router.push({ pathname: '/<featureName>/[id]', params: { id: item.id } });
+}, [router]);
+```
+
+**Notes:**
+- The target screen name and params come from the spec screenLogic description.
+  If not specified, use `<ScreenName>DetailScreen` and pass `itemId`.
+- Add a TODO comment if the target screen does not yet exist.
+
+---
+
+## Pattern: Empty state
+
+**Spec phrase**: "Show empty state when list is empty",
+"Display 'No items found' message"
+
+```typescript
+// Derive in component:
+const isEmpty = !isLoading && items.length === 0;
+
+// In FlatList:
+<FlatList
+  data={items}
+  ListEmptyComponent={
+    isEmpty ? (
+      <View style={styles.emptyContainer}>
+        <Text style={styles.emptyText}>
+          {/* Use exact message from spec, or default below */}
+          No items found
+        </Text>
+      </View>
+    ) : null
+  }
+  // ...
+/>
+```
+
+**Styles:**
+```typescript
+emptyContainer: {
+  flex: 1,
+  alignItems: 'center',
+  justifyContent: 'center',
+  paddingVertical: 64,
+},
+emptyText: {
+  fontSize: 14,
+  color: '#71789d',
+  textAlign: 'center',
+},
+```
+
+---
+
+## Pattern: Loading skeleton / loading state
+
+**Spec phrase**: "Show loading skeleton while fetching", "Loading indicator",
+"Show shimmer placeholder"
+
+```typescript
+const isLoading = useSelector(select<ScreenName>IsLoading);
+
+if (isLoading) {
+  return (
+    <View style={styles.loadingContainer}>
+      {/* If a Skeleton component exists in the project, use it. Otherwise use ActivityIndicator. */}
+      <ActivityIndicator size="large" color="#02168b" />
+    </View>
+  );
+}
+```
+
+**Notes:**
+- Detect whether the project has a custom Skeleton/Shimmer component
+  by scanning the `presentation/components/` folder. If found, use it.
+- Do NOT use `<ActivityIndicator>` if a Skeleton component is already present —
+  use the existing pattern for visual consistency.
+
+---
+
+## Pattern: Error state
+
+**Spec phrase**: "Show error message if fetch fails", "Display error state"
+
+```typescript
+const error = useSelector(select<ScreenName>Error);
+const isLoading = useSelector(select<ScreenName>IsLoading);
+
+// Define handleRefetch alongside the initial fetch dispatch
+const handleRefetch = useCallback(() => {
+  dispatch(fetch<ScreenName>Thunk({ clientCode, sessionId }));
+}, [dispatch, clientCode, sessionId]);
+
+if (error !== null && !isLoading) {
+  return (
+    <View style={styles.errorContainer}>
+      <Text style={styles.errorText}>{error}</Text>
+      <Pressable onPress={handleRefetch} style={styles.retryButton}>
+        <Text style={styles.retryButtonText}>Retry</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+---
+
+## Pattern: Auth error + logout
+
+**Spec phrase**: "Display auth error and logout button if session expires",
+"Handle 401 / session expiry"
+
+```typescript
+const isAuthError = useSelector(select<ScreenName>IsAuthError);
+
+if (isAuthError) {
+  return (
+    <View style={styles.errorContainer}>
+      <Text style={styles.errorText}>Your session has expired. Please log in again.</Text>
+      <Pressable
+        onPress={() => {
+          // Navigate to login. Use detected nav pattern.
+          navigation.reset({ index: 0, routes: [{ name: 'Login' }] });
+        }}
+        style={styles.retryButton}
+      >
+        <Text style={styles.retryButtonText}>Log In Again</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+---
+
+## Pattern: Tab switcher
+
+**Spec phrase**: "Tab bar to switch between views", "Filter by tab",
+"Tab switcher between Asset classes"
+
+```typescript
+// State (added to slice or local state)
+const [activeTab, setActiveTab] = useState('<first tab value from spec>');
+
+// Derived data
+const filteredItems = useMemo(
+  () => items.filter((item) => item.category === activeTab || activeTab === 'All'),
+  [items, activeTab],
+);
+
+// JSX — horizontal scrollable tab bar
+<ScrollView horizontal showsHorizontalScrollIndicator={false} style={styles.tabBar}>
+  {tabOptions.map((tab) => (
+    <Pressable
+      key={tab}
+      onPress={() => setActiveTab(tab)}
+      style={[styles.tab, activeTab === tab && styles.tabActive]}
+    >
+      <Text style={[styles.tabText, activeTab === tab && styles.tabTextActive]}>
+        {tab}
+      </Text>
+    </Pressable>
+  ))}
+</ScrollView>
+```
+
+---
+
+## Pattern: Filter list (search/query)
+
+**Spec phrase**: "Filter list by search query", "Search functionality"
+
+```typescript
+// State
+const [searchQuery, setSearchQuery] = useState('');
+
+// Derived
+const filteredItems = useMemo(
+  () =>
+    searchQuery.trim() === ''
+      ? items
+      : items.filter((item) =>
+          item.name.toLowerCase().includes(searchQuery.toLowerCase()),
+        ),
+  [items, searchQuery],
+);
+
+// JSX
+<TextInput
+  value={searchQuery}
+  onChangeText={setSearchQuery}
+  placeholder="Search..."
+  style={styles.searchInput}
+/>
+<FlatList data={filteredItems} /* ... */ />
+```
+
+---
+
+## Pattern: Summary card at top of list
+
+**Spec phrase**: "Summary card at the top", "Header card with totals"
+
+Use `ListHeaderComponent` on FlatList — never render the header above FlatList
+as a sibling view when the list scrolls, to avoid nested scroll issues.
+
+```typescript
+const SummaryCard = useMemo(() => (
+  <View style={styles.summaryCard}>
+    {/* map spec responseMappings that are not list-row fields */}
+    <Text style={styles.summaryLabel}>Total Value</Text>
+    <Text style={styles.summaryValue}>{totalValue}</Text>
+  </View>
+), [totalValue]);
+
+<FlatList
+  data={items}
+  ListHeaderComponent={SummaryCard}
+  // ...
+/>
+```
+
+---
+
+## Pattern: Pagination / load more
+
+**Spec phrase**: "Pagination", "Load more on scroll end", "Infinite scroll"
+
+```typescript
+// State
+const [page, setPage] = useState(1);
+const hasMore = useSelector(select<ScreenName>HasMore);
+
+const handleEndReached = useCallback(() => {
+  if (!isLoading && hasMore) {
+    const nextPage = page + 1;
+    setPage(nextPage);
+    dispatch(fetch<ScreenName>PageThunk({ clientCode, sessionId, page: nextPage }));
+  }
+}, [dispatch, isLoading, hasMore, page, clientCode, sessionId]);
+
+<FlatList
+  data={items}
+  onEndReached={handleEndReached}
+  onEndReachedThreshold={0.3}
+  ListFooterComponent={isLoading && page > 1 ? <ActivityIndicator /> : null}
+  // ...
+/>
+```
+
+---
+
+## FlatList scaffold (base template — all list screens)
+
+Combine patterns above by composing into this base FlatList structure:
+
+```typescript
+<FlatList
+  data={filteredItems}
+  keyExtractor={(item) => String(item.<idField>)}
+  renderItem={({ item }) => (
+    <Pressable onPress={() => handleItemPress(item)}>
+      {/* Row content using responseMappings */}
+    </Pressable>
+  )}
+  ListHeaderComponent={<SummaryCard />}      // if "summary card" in spec
+  ListEmptyComponent={<EmptyState />}        // if "empty state" in spec
+  ListFooterComponent={<FooterLoader />}     // if "pagination" in spec
+  refreshControl={<RefreshControl ... />}    // if "pull to refresh" in spec
+  showsVerticalScrollIndicator={false}
+  contentContainerStyle={styles.listContent}
+/>
+```
+
+---
+
+## Screen file structure (always follow this order)
+
+```typescript
+// 1. React imports
+// 2. React Native imports
+// 3. Third-party library imports (react-redux, react-navigation, etc.)
+// 4. Feature-local imports (state, selectors, thunks)
+// 5. Shared imports (assets, design tokens, shared components)
+// 6. Type-only imports (import type {...})
+
+// Component function
+// ---- hooks (useSelector, useDispatch, useCallback, useEffect) ----
+// ---- derived values (useMemo) ----
+// ---- conditional early returns (loading, auth error, error) ----
+// ---- main render ----
+
+// StyleSheet.create() — always at bottom of file
+```