@vodailoc/kilo-kit-mcp 1.1.0 → 1.2.0

package/skills/engineering/frontend-development/resources/complete-examples.md

@@ -1,872 +1,872 @@
-# Complete Examples
-
-Full working examples combining all modern patterns: React.FC, lazy loading, Suspense, useSuspenseQuery, styling, routing, and error handling.
-
----
-
-## Example 1: Complete Modern Component
-
-Combines: React.FC, useSuspenseQuery, cache-first, useCallback, styling, error handling
-
-```typescript
-/**
- * User profile display component
- * Demonstrates modern patterns with Suspense and TanStack Query
- */
-import React, { useState, useCallback, useMemo } from 'react';
-import { Box, Paper, Typography, Button, Avatar } from '@mui/material';
-import type { SxProps, Theme } from '@mui/material';
-import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { userApi } from '../api/userApi';
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-import type { User } from '~types/user';
-
-// Styles object
-const componentStyles: Record<string, SxProps<Theme>> = {
-    container: {
-        p: 3,
-        maxWidth: 600,
-        margin: '0 auto',
-    },
-    header: {
-        display: 'flex',
-        alignItems: 'center',
-        gap: 2,
-        mb: 3,
-    },
-    content: {
-        display: 'flex',
-        flexDirection: 'column',
-        gap: 2,
-    },
-    actions: {
-        display: 'flex',
-        gap: 1,
-        mt: 2,
-    },
-};
-
-interface UserProfileProps {
-    userId: string;
-    onUpdate?: () => void;
-}
-
-export const UserProfile: React.FC<UserProfileProps> = ({ userId, onUpdate }) => {
-    const queryClient = useQueryClient();
-    const { showSuccess, showError } = useMuiSnackbar();
-    const [isEditing, setIsEditing] = useState(false);
-
-    // Suspense query - no isLoading needed!
-    const { data: user } = useSuspenseQuery({
-        queryKey: ['user', userId],
-        queryFn: () => userApi.getUser(userId),
-        staleTime: 5 * 60 * 1000,
-    });
-
-    // Update mutation
-    const updateMutation = useMutation({
-        mutationFn: (updates: Partial<User>) =>
-            userApi.updateUser(userId, updates),
-
-        onSuccess: () => {
-            queryClient.invalidateQueries({ queryKey: ['user', userId] });
-            showSuccess('Profile updated');
-            setIsEditing(false);
-            onUpdate?.();
-        },
-
-        onError: () => {
-            showError('Failed to update profile');
-        },
-    });
-
-    // Memoized computed value
-    const fullName = useMemo(() => {
-        return `${user.firstName} ${user.lastName}`;
-    }, [user.firstName, user.lastName]);
-
-    // Event handlers with useCallback
-    const handleEdit = useCallback(() => {
-        setIsEditing(true);
-    }, []);
-
-    const handleSave = useCallback(() => {
-        updateMutation.mutate({
-            firstName: user.firstName,
-            lastName: user.lastName,
-        });
-    }, [user, updateMutation]);
-
-    const handleCancel = useCallback(() => {
-        setIsEditing(false);
-    }, []);
-
-    return (
-        <Paper sx={componentStyles.container}>
-            <Box sx={componentStyles.header}>
-                <Avatar sx={{ width: 64, height: 64 }}>
-                    {user.firstName[0]}{user.lastName[0]}
-                </Avatar>
-                <Box>
-                    <Typography variant='h5'>{fullName}</Typography>
-                    <Typography color='text.secondary'>{user.email}</Typography>
-                </Box>
-            </Box>
-
-            <Box sx={componentStyles.content}>
-                <Typography>Username: {user.username}</Typography>
-                <Typography>Roles: {user.roles.join(', ')}</Typography>
-            </Box>
-
-            <Box sx={componentStyles.actions}>
-                {!isEditing ? (
-                    <Button variant='contained' onClick={handleEdit}>
-                        Edit Profile
-                    </Button>
-                ) : (
-                    <>
-                        <Button
-                            variant='contained'
-                            onClick={handleSave}
-                            disabled={updateMutation.isPending}
-                        >
-                            {updateMutation.isPending ? 'Saving...' : 'Save'}
-                        </Button>
-                        <Button onClick={handleCancel}>
-                            Cancel
-                        </Button>
-                    </>
-                )}
-            </Box>
-        </Paper>
-    );
-};
-
-export default UserProfile;
-```
-
-**Usage:**
-```typescript
-<SuspenseLoader>
-    <UserProfile userId='123' onUpdate={() => console.log('Updated')} />
-</SuspenseLoader>
-```
-
----
-
-## Example 2: Complete Feature Structure
-
-Real example based on `features/posts/`:
-
-```
-features/
-  users/
-    api/
-      userApi.ts                # API service layer
-    components/
-      UserProfile.tsx           # Main component (from Example 1)
-      UserList.tsx              # List component
-      UserBlog.tsx              # Blog component
-      modals/
-        DeleteUserModal.tsx     # Modal component
-    hooks/
-      useSuspenseUser.ts        # Suspense query hook
-      useUserMutations.ts       # Mutation hooks
-      useUserPermissions.ts     # Feature-specific hook
-    helpers/
-      userHelpers.ts            # Utility functions
-      validation.ts             # Validation logic
-    types/
-      index.ts                  # TypeScript interfaces
-    index.ts                    # Public API exports
-```
-
-### API Service (userApi.ts)
-
-```typescript
-import apiClient from '@/lib/apiClient';
-import type { User, CreateUserPayload, UpdateUserPayload } from '../types';
-
-export const userApi = {
-    getUser: async (userId: string): Promise<User> => {
-        const { data } = await apiClient.get(`/users/${userId}`);
-        return data;
-    },
-
-    getUsers: async (): Promise<User[]> => {
-        const { data } = await apiClient.get('/users');
-        return data;
-    },
-
-    createUser: async (payload: CreateUserPayload): Promise<User> => {
-        const { data } = await apiClient.post('/users', payload);
-        return data;
-    },
-
-    updateUser: async (userId: string, payload: UpdateUserPayload): Promise<User> => {
-        const { data } = await apiClient.put(`/users/${userId}`, payload);
-        return data;
-    },
-
-    deleteUser: async (userId: string): Promise<void> => {
-        await apiClient.delete(`/users/${userId}`);
-    },
-};
-```
-
-### Suspense Hook (useSuspenseUser.ts)
-
-```typescript
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { userApi } from '../api/userApi';
-import type { User } from '../types';
-
-export function useSuspenseUser(userId: string) {
-    return useSuspenseQuery<User, Error>({
-        queryKey: ['user', userId],
-        queryFn: () => userApi.getUser(userId),
-        staleTime: 5 * 60 * 1000,
-        gcTime: 10 * 60 * 1000,
-    });
-}
-
-export function useSuspenseUsers() {
-    return useSuspenseQuery<User[], Error>({
-        queryKey: ['users'],
-        queryFn: () => userApi.getUsers(),
-        staleTime: 1 * 60 * 1000,  // Shorter for list
-    });
-}
-```
-
-### Types (types/index.ts)
-
-```typescript
-export interface User {
-    id: string;
-    username: string;
-    email: string;
-    firstName: string;
-    lastName: string;
-    roles: string[];
-    createdAt: string;
-    updatedAt: string;
-}
-
-export interface CreateUserPayload {
-    username: string;
-    email: string;
-    firstName: string;
-    lastName: string;
-    password: string;
-}
-
-export type UpdateUserPayload = Partial<Omit<User, 'id' | 'createdAt' | 'updatedAt'>>;
-```
-
-### Public Exports (index.ts)
-
-```typescript
-// Export components
-export { UserProfile } from './components/UserProfile';
-export { UserList } from './components/UserList';
-
-// Export hooks
-export { useSuspenseUser, useSuspenseUsers } from './hooks/useSuspenseUser';
-export { useUserMutations } from './hooks/useUserMutations';
-
-// Export API
-export { userApi } from './api/userApi';
-
-// Export types
-export type { User, CreateUserPayload, UpdateUserPayload } from './types';
-```
-
----
-
-## Example 3: Complete Route with Lazy Loading
-
-```typescript
-/**
- * User profile route
- * Path: /users/:userId
- */
-
-import { createFileRoute } from '@tanstack/react-router';
-import { lazy } from 'react';
-import { SuspenseLoader } from '~components/SuspenseLoader';
-
-// Lazy load the UserProfile component
-const UserProfile = lazy(() =>
-    import('@/features/users/components/UserProfile').then(
-        (module) => ({ default: module.UserProfile })
-    )
-);
-
-export const Route = createFileRoute('/users/$userId')({
-    component: UserProfilePage,
-    loader: ({ params }) => ({
-        crumb: `User ${params.userId}`,
-    }),
-});
-
-function UserProfilePage() {
-    const { userId } = Route.useParams();
-
-    return (
-        <SuspenseLoader>
-            <UserProfile
-                userId={userId}
-                onUpdate={() => console.log('Profile updated')}
-            />
-        </SuspenseLoader>
-    );
-}
-
-export default UserProfilePage;
-```
-
----
-
-## Example 4: List with Search and Filtering
-
-```typescript
-import React, { useState, useMemo } from 'react';
-import { Box, TextField, List, ListItem } from '@mui/material';
-import { useDebounce } from 'use-debounce';
-import { useSuspenseQuery } from '@tanstack/react-query';
-import { userApi } from '../api/userApi';
-
-export const UserList: React.FC = () => {
-    const [searchTerm, setSearchTerm] = useState('');
-    const [debouncedSearch] = useDebounce(searchTerm, 300);
-
-    const { data: users } = useSuspenseQuery({
-        queryKey: ['users'],
-        queryFn: () => userApi.getUsers(),
-    });
-
-    // Memoized filtering
-    const filteredUsers = useMemo(() => {
-        if (!debouncedSearch) return users;
-
-        return users.filter(user =>
-            user.name.toLowerCase().includes(debouncedSearch.toLowerCase()) ||
-            user.email.toLowerCase().includes(debouncedSearch.toLowerCase())
-        );
-    }, [users, debouncedSearch]);
-
-    return (
-        <Box>
-            <TextField
-                value={searchTerm}
-                onChange={(e) => setSearchTerm(e.target.value)}
-                placeholder='Search users...'
-                fullWidth
-                sx={{ mb: 2 }}
-            />
-
-            <List>
-                {filteredUsers.map(user => (
-                    <ListItem key={user.id}>
-                        {user.name} - {user.email}
-                    </ListItem>
-                ))}
-            </List>
-        </Box>
-    );
-};
-```
-
----
-
-## Example 5: Blog with Validation
-
-```typescript
-import React from 'react';
-import { Box, TextField, Button, Paper } from '@mui/material';
-import { useBlog } from 'react-hook-blog';
-import { zodResolver } from '@hookblog/resolvers/zod';
-import { z } from 'zod';
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { userApi } from '../api/userApi';
-import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
-
-const userSchema = z.object({
-    username: z.string().min(3).max(50),
-    email: z.string().email(),
-    firstName: z.string().min(1),
-    lastName: z.string().min(1),
-});
-
-type UserBlogData = z.infer<typeof userSchema>;
-
-interface CreateUserBlogProps {
-    onSuccess?: () => void;
-}
-
-export const CreateUserBlog: React.FC<CreateUserBlogProps> = ({ onSuccess }) => {
-    const queryClient = useQueryClient();
-    const { showSuccess, showError } = useMuiSnackbar();
-
-    const { register, handleSubmit, blogState: { errors }, reset } = useBlog<UserBlogData>({
-        resolver: zodResolver(userSchema),
-        defaultValues: {
-            username: '',
-            email: '',
-            firstName: '',
-            lastName: '',
-        },
-    });
-
-    const createMutation = useMutation({
-        mutationFn: (data: UserBlogData) => userApi.createUser(data),
-
-        onSuccess: () => {
-            queryClient.invalidateQueries({ queryKey: ['users'] });
-            showSuccess('User created successfully');
-            reset();
-            onSuccess?.();
-        },
-
-        onError: () => {
-            showError('Failed to create user');
-        },
-    });
-
-    const onSubmit = (data: UserBlogData) => {
-        createMutation.mutate(data);
-    };
-
-    return (
-        <Paper sx={{ p: 3, maxWidth: 500 }}>
-            <blog onSubmit={handleSubmit(onSubmit)}>
-                <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
-                    <TextField
-                        {...register('username')}
-                        label='Username'
-                        error={!!errors.username}
-                        helperText={errors.username?.message}
-                        fullWidth
-                    />
-
-                    <TextField
-                        {...register('email')}
-                        label='Email'
-                        type='email'
-                        error={!!errors.email}
-                        helperText={errors.email?.message}
-                        fullWidth
-                    />
-
-                    <TextField
-                        {...register('firstName')}
-                        label='First Name'
-                        error={!!errors.firstName}
-                        helperText={errors.firstName?.message}
-                        fullWidth
-                    />
-
-                    <TextField
-                        {...register('lastName')}
-                        label='Last Name'
-                        error={!!errors.lastName}
-                        helperText={errors.lastName?.message}
-                        fullWidth
-                    />
-
-                    <Button
-                        type='submit'
-                        variant='contained'
-                        disabled={createMutation.isPending}
-                    >
-                        {createMutation.isPending ? 'Creating...' : 'Create User'}
-                    </Button>
-                </Box>
-            </blog>
-        </Paper>
-    );
-};
-
-export default CreateUserBlog;
-```
-
----
-
-## Example 2: Parent Container with Lazy Loading
-
-```typescript
-import React from 'react';
-import { Box } from '@mui/material';
-import { SuspenseLoader } from '~components/SuspenseLoader';
-
-// Lazy load heavy components
-const UserList = React.lazy(() => import('./UserList'));
-const UserStats = React.lazy(() => import('./UserStats'));
-const ActivityFeed = React.lazy(() => import('./ActivityFeed'));
-
-export const UserDashboard: React.FC = () => {
-    return (
-        <Box sx={{ p: 2 }}>
-            <SuspenseLoader>
-                <UserStats />
-            </SuspenseLoader>
-
-            <Box sx={{ display: 'flex', gap: 2, mt: 2 }}>
-                <Box sx={{ flex: 2 }}>
-                    <SuspenseLoader>
-                        <UserList />
-                    </SuspenseLoader>
-                </Box>
-
-                <Box sx={{ flex: 1 }}>
-                    <SuspenseLoader>
-                        <ActivityFeed />
-                    </SuspenseLoader>
-                </Box>
-            </Box>
-        </Box>
-    );
-};
-
-export default UserDashboard;
-```
-
-**Benefits:**
-- Each section loads independently
-- User sees partial content sooner
-- Better perceived perblogance
-
----
-
-## Example 3: Cache-First Strategy Implementation
-
-Complete example based on useSuspensePost.ts:
-
-```typescript
-import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
-import { postApi } from '../api/postApi';
-import type { Post } from '../types';
-
-/**
- * Smart post hook with cache-first strategy
- * Reuses data from grid cache when available
- */
-export function useSuspensePost(blogId: number, postId: number) {
-    const queryClient = useQueryClient();
-
-    return useSuspenseQuery<Post, Error>({
-        queryKey: ['post', blogId, postId],
-        queryFn: async () => {
-            // Strategy 1: Check grid cache first (avoids API call)
-            const gridCache = queryClient.getQueryData<{ rows: Post[] }>([
-                'posts-v2',
-                blogId,
-                'summary'
-            ]) || queryClient.getQueryData<{ rows: Post[] }>([
-                'posts-v2',
-                blogId,
-                'flat'
-            ]);
-
-            if (gridCache?.rows) {
-                const cached = gridCache.rows.find(
-                    (row) => row.S_ID === postId
-                );
-
-                if (cached) {
-                    return cached;  // Return from cache - no API call!
-                }
-            }
-
-            // Strategy 2: Not in cache, fetch from API
-            return postApi.getPost(blogId, postId);
-        },
-        staleTime: 5 * 60 * 1000,       // Fresh for 5 minutes
-        gcTime: 10 * 60 * 1000,          // Cache for 10 minutes
-        refetchOnWindowFocus: false,     // Don't refetch on focus
-    });
-}
-```
-
-**Why this pattern:**
-- Checks grid cache before API
-- Instant data if user came from grid
-- Falls back to API if not cached
-- Configurable cache times
-
----
-
-## Example 4: Complete Route File
-
-```typescript
-/**
- * Project catalog route
- * Path: /project-catalog
- */
-
-import { createFileRoute } from '@tanstack/react-router';
-import { lazy } from 'react';
-
-// Lazy load the PostTable component
-const PostTable = lazy(() =>
-    import('@/features/posts/components/PostTable').then(
-        (module) => ({ default: module.PostTable })
-    )
-);
-
-// Route constants
-const PROJECT_CATALOG_FORM_ID = 744;
-const PROJECT_CATALOG_PROJECT_ID = 225;
-
-export const Route = createFileRoute('/project-catalog/')({
-    component: ProjectCatalogPage,
-    loader: () => ({
-        crumb: 'Projects',  // Breadcrumb title
-    }),
-});
-
-function ProjectCatalogPage() {
-    return (
-        <PostTable
-            blogId={PROJECT_CATALOG_FORM_ID}
-            projectId={PROJECT_CATALOG_PROJECT_ID}
-            tableType='active_projects'
-            title='Blog Dashboard'
-        />
-    );
-}
-
-export default ProjectCatalogPage;
-```
-
----
-
-## Example 5: Dialog with Blog
-
-```typescript
-import React from 'react';
-import {
-    Dialog,
-    DialogTitle,
-    DialogContent,
-    DialogActions,
-    Button,
-    TextField,
-    Box,
-    IconButton,
-} from '@mui/material';
-import { Close, PersonAdd } from '@mui/icons-material';
-import { useBlog } from 'react-hook-blog';
-import { zodResolver } from '@hookblog/resolvers/zod';
-import { z } from 'zod';
-
-const blogSchema = z.object({
-    name: z.string().min(1),
-    email: z.string().email(),
-});
-
-type BlogData = z.infer<typeof blogSchema>;
-
-interface AddUserDialogProps {
-    open: boolean;
-    onClose: () => void;
-    onSubmit: (data: BlogData) => Promise<void>;
-}
-
-export const AddUserDialog: React.FC<AddUserDialogProps> = ({
-    open,
-    onClose,
-    onSubmit,
-}) => {
-    const { register, handleSubmit, blogState: { errors }, reset } = useBlog<BlogData>({
-        resolver: zodResolver(blogSchema),
-    });
-
-    const handleClose = () => {
-        reset();
-        onClose();
-    };
-
-    const handleBlogSubmit = async (data: BlogData) => {
-        await onSubmit(data);
-        handleClose();
-    };
-
-    return (
-        <Dialog open={open} onClose={handleClose} maxWidth='sm' fullWidth>
-            <DialogTitle>
-                <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
-                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
-                        <PersonAdd color='primary' />
-                        Add User
-                    </Box>
-                    <IconButton onClick={handleClose} size='small'>
-                        <Close />
-                    </IconButton>
-                </Box>
-            </DialogTitle>
-
-            <blog onSubmit={handleSubmit(handleBlogSubmit)}>
-                <DialogContent>
-                    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
-                        <TextField
-                            {...register('name')}
-                            label='Name'
-                            error={!!errors.name}
-                            helperText={errors.name?.message}
-                            fullWidth
-                            autoFocus
-                        />
-
-                        <TextField
-                            {...register('email')}
-                            label='Email'
-                            type='email'
-                            error={!!errors.email}
-                            helperText={errors.email?.message}
-                            fullWidth
-                        />
-                    </Box>
-                </DialogContent>
-
-                <DialogActions>
-                    <Button onClick={handleClose}>Cancel</Button>
-                    <Button type='submit' variant='contained'>
-                        Add User
-                    </Button>
-                </DialogActions>
-            </blog>
-        </Dialog>
-    );
-};
-```
-
----
-
-## Example 6: Parallel Data Fetching
-
-```typescript
-import React from 'react';
-import { Box, Grid, Paper } from '@mui/material';
-import { useSuspenseQueries } from '@tanstack/react-query';
-import { userApi } from '../api/userApi';
-import { statsApi } from '../api/statsApi';
-import { activityApi } from '../api/activityApi';
-
-export const Dashboard: React.FC = () => {
-    // Fetch all data in parallel with Suspense
-    const [statsQuery, usersQuery, activityQuery] = useSuspenseQueries({
-        queries: [
-            {
-                queryKey: ['stats'],
-                queryFn: () => statsApi.getStats(),
-            },
-            {
-                queryKey: ['users', 'active'],
-                queryFn: () => userApi.getActiveUsers(),
-            },
-            {
-                queryKey: ['activity', 'recent'],
-                queryFn: () => activityApi.getRecent(),
-            },
-        ],
-    });
-
-    return (
-        <Box sx={{ p: 2 }}>
-            <Grid container spacing={2}>
-                <Grid size={{ xs: 12, md: 4 }}>
-                    <Paper sx={{ p: 2 }}>
-                        <h3>Stats</h3>
-                        <p>Total: {statsQuery.data.total}</p>
-                    </Paper>
-                </Grid>
-
-                <Grid size={{ xs: 12, md: 4 }}>
-                    <Paper sx={{ p: 2 }}>
-                        <h3>Active Users</h3>
-                        <p>Count: {usersQuery.data.length}</p>
-                    </Paper>
-                </Grid>
-
-                <Grid size={{ xs: 12, md: 4 }}>
-                    <Paper sx={{ p: 2 }}>
-                        <h3>Recent Activity</h3>
-                        <p>Events: {activityQuery.data.length}</p>
-                    </Paper>
-                </Grid>
-            </Grid>
-        </Box>
-    );
-};
-
-// Usage with Suspense
-<SuspenseLoader>
-    <Dashboard />
-</SuspenseLoader>
-```
-
----
-
-## Example 7: Optimistic Update
-
-```typescript
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import type { User } from '../types';
-
-export const useToggleUserStatus = () => {
-    const queryClient = useQueryClient();
-
-    return useMutation({
-        mutationFn: (userId: string) => userApi.toggleStatus(userId),
-
-        // Optimistic update
-        onMutate: async (userId) => {
-            // Cancel outgoing refetches
-            await queryClient.cancelQueries({ queryKey: ['users'] });
-
-            // Snapshot previous value
-            const previousUsers = queryClient.getQueryData<User[]>(['users']);
-
-            // Optimistically update UI
-            queryClient.setQueryData<User[]>(['users'], (old) => {
-                return old?.map(user =>
-                    user.id === userId
-                        ? { ...user, active: !user.active }
-                        : user
-                ) || [];
-            });
-
-            return { previousUsers };
-        },
-
-        // Rollback on error
-        onError: (err, userId, context) => {
-            queryClient.setQueryData(['users'], context?.previousUsers);
-        },
-
-        // Refetch after mutation
-        onSettled: () => {
-            queryClient.invalidateQueries({ queryKey: ['users'] });
-        },
-    });
-};
-```
-
----
-
-## Summary
-
-**Key Takeaways:**
-
-1. **Component Pattern**: React.FC + lazy + Suspense + useSuspenseQuery
-2. **Feature Structure**: Organized subdirectories (api/, components/, hooks/, etc.)
-3. **Routing**: Folder-based with lazy loading
-4. **Data Fetching**: useSuspenseQuery with cache-first strategy
-5. **Blogs**: React Hook Blog + Zod validation
-6. **Error Handling**: useMuiSnackbar + onError callbacks
-7. **Perblogance**: useMemo, useCallback, React.memo, debouncing
-8. **Styling**: Inline <100 lines, sx prop, MUI v7 syntax
-
+# Complete Examples
+
+Full working examples combining all modern patterns: React.FC, lazy loading, Suspense, useSuspenseQuery, styling, routing, and error handling.
+
+---
+
+## Example 1: Complete Modern Component
+
+Combines: React.FC, useSuspenseQuery, cache-first, useCallback, styling, error handling
+
+```typescript
+/**
+ * User profile display component
+ * Demonstrates modern patterns with Suspense and TanStack Query
+ */
+import React, { useState, useCallback, useMemo } from 'react';
+import { Box, Paper, Typography, Button, Avatar } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material';
+import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { userApi } from '../api/userApi';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+import type { User } from '~types/user';
+
+// Styles object
+const componentStyles: Record<string, SxProps<Theme>> = {
+    container: {
+        p: 3,
+        maxWidth: 600,
+        margin: '0 auto',
+    },
+    header: {
+        display: 'flex',
+        alignItems: 'center',
+        gap: 2,
+        mb: 3,
+    },
+    content: {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 2,
+    },
+    actions: {
+        display: 'flex',
+        gap: 1,
+        mt: 2,
+    },
+};
+
+interface UserProfileProps {
+    userId: string;
+    onUpdate?: () => void;
+}
+
+export const UserProfile: React.FC<UserProfileProps> = ({ userId, onUpdate }) => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+    const [isEditing, setIsEditing] = useState(false);
+
+    // Suspense query - no isLoading needed!
+    const { data: user } = useSuspenseQuery({
+        queryKey: ['user', userId],
+        queryFn: () => userApi.getUser(userId),
+        staleTime: 5 * 60 * 1000,
+    });
+
+    // Update mutation
+    const updateMutation = useMutation({
+        mutationFn: (updates: Partial<User>) =>
+            userApi.updateUser(userId, updates),
+
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: ['user', userId] });
+            showSuccess('Profile updated');
+            setIsEditing(false);
+            onUpdate?.();
+        },
+
+        onError: () => {
+            showError('Failed to update profile');
+        },
+    });
+
+    // Memoized computed value
+    const fullName = useMemo(() => {
+        return `${user.firstName} ${user.lastName}`;
+    }, [user.firstName, user.lastName]);
+
+    // Event handlers with useCallback
+    const handleEdit = useCallback(() => {
+        setIsEditing(true);
+    }, []);
+
+    const handleSave = useCallback(() => {
+        updateMutation.mutate({
+            firstName: user.firstName,
+            lastName: user.lastName,
+        });
+    }, [user, updateMutation]);
+
+    const handleCancel = useCallback(() => {
+        setIsEditing(false);
+    }, []);
+
+    return (
+        <Paper sx={componentStyles.container}>
+            <Box sx={componentStyles.header}>
+                <Avatar sx={{ width: 64, height: 64 }}>
+                    {user.firstName[0]}{user.lastName[0]}
+                </Avatar>
+                <Box>
+                    <Typography variant='h5'>{fullName}</Typography>
+                    <Typography color='text.secondary'>{user.email}</Typography>
+                </Box>
+            </Box>
+
+            <Box sx={componentStyles.content}>
+                <Typography>Username: {user.username}</Typography>
+                <Typography>Roles: {user.roles.join(', ')}</Typography>
+            </Box>
+
+            <Box sx={componentStyles.actions}>
+                {!isEditing ? (
+                    <Button variant='contained' onClick={handleEdit}>
+                        Edit Profile
+                    </Button>
+                ) : (
+                    <>
+                        <Button
+                            variant='contained'
+                            onClick={handleSave}
+                            disabled={updateMutation.isPending}
+                        >
+                            {updateMutation.isPending ? 'Saving...' : 'Save'}
+                        </Button>
+                        <Button onClick={handleCancel}>
+                            Cancel
+                        </Button>
+                    </>
+                )}
+            </Box>
+        </Paper>
+    );
+};
+
+export default UserProfile;
+```
+
+**Usage:**
+```typescript
+<SuspenseLoader>
+    <UserProfile userId='123' onUpdate={() => console.log('Updated')} />
+</SuspenseLoader>
+```
+
+---
+
+## Example 2: Complete Feature Structure
+
+Real example based on `features/posts/`:
+
+```
+features/
+  users/
+    api/
+      userApi.ts                # API service layer
+    components/
+      UserProfile.tsx           # Main component (from Example 1)
+      UserList.tsx              # List component
+      UserBlog.tsx              # Blog component
+      modals/
+        DeleteUserModal.tsx     # Modal component
+    hooks/
+      useSuspenseUser.ts        # Suspense query hook
+      useUserMutations.ts       # Mutation hooks
+      useUserPermissions.ts     # Feature-specific hook
+    helpers/
+      userHelpers.ts            # Utility functions
+      validation.ts             # Validation logic
+    types/
+      index.ts                  # TypeScript interfaces
+    index.ts                    # Public API exports
+```
+
+### API Service (userApi.ts)
+
+```typescript
+import apiClient from '@/lib/apiClient';
+import type { User, CreateUserPayload, UpdateUserPayload } from '../types';
+
+export const userApi = {
+    getUser: async (userId: string): Promise<User> => {
+        const { data } = await apiClient.get(`/users/${userId}`);
+        return data;
+    },
+
+    getUsers: async (): Promise<User[]> => {
+        const { data } = await apiClient.get('/users');
+        return data;
+    },
+
+    createUser: async (payload: CreateUserPayload): Promise<User> => {
+        const { data } = await apiClient.post('/users', payload);
+        return data;
+    },
+
+    updateUser: async (userId: string, payload: UpdateUserPayload): Promise<User> => {
+        const { data } = await apiClient.put(`/users/${userId}`, payload);
+        return data;
+    },
+
+    deleteUser: async (userId: string): Promise<void> => {
+        await apiClient.delete(`/users/${userId}`);
+    },
+};
+```
+
+### Suspense Hook (useSuspenseUser.ts)
+
+```typescript
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { userApi } from '../api/userApi';
+import type { User } from '../types';
+
+export function useSuspenseUser(userId: string) {
+    return useSuspenseQuery<User, Error>({
+        queryKey: ['user', userId],
+        queryFn: () => userApi.getUser(userId),
+        staleTime: 5 * 60 * 1000,
+        gcTime: 10 * 60 * 1000,
+    });
+}
+
+export function useSuspenseUsers() {
+    return useSuspenseQuery<User[], Error>({
+        queryKey: ['users'],
+        queryFn: () => userApi.getUsers(),
+        staleTime: 1 * 60 * 1000,  // Shorter for list
+    });
+}
+```
+
+### Types (types/index.ts)
+
+```typescript
+export interface User {
+    id: string;
+    username: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    roles: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface CreateUserPayload {
+    username: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    password: string;
+}
+
+export type UpdateUserPayload = Partial<Omit<User, 'id' | 'createdAt' | 'updatedAt'>>;
+```
+
+### Public Exports (index.ts)
+
+```typescript
+// Export components
+export { UserProfile } from './components/UserProfile';
+export { UserList } from './components/UserList';
+
+// Export hooks
+export { useSuspenseUser, useSuspenseUsers } from './hooks/useSuspenseUser';
+export { useUserMutations } from './hooks/useUserMutations';
+
+// Export API
+export { userApi } from './api/userApi';
+
+// Export types
+export type { User, CreateUserPayload, UpdateUserPayload } from './types';
+```
+
+---
+
+## Example 3: Complete Route with Lazy Loading
+
+```typescript
+/**
+ * User profile route
+ * Path: /users/:userId
+ */
+
+import { createFileRoute } from '@tanstack/react-router';
+import { lazy } from 'react';
+import { SuspenseLoader } from '~components/SuspenseLoader';
+
+// Lazy load the UserProfile component
+const UserProfile = lazy(() =>
+    import('@/features/users/components/UserProfile').then(
+        (module) => ({ default: module.UserProfile })
+    )
+);
+
+export const Route = createFileRoute('/users/$userId')({
+    component: UserProfilePage,
+    loader: ({ params }) => ({
+        crumb: `User ${params.userId}`,
+    }),
+});
+
+function UserProfilePage() {
+    const { userId } = Route.useParams();
+
+    return (
+        <SuspenseLoader>
+            <UserProfile
+                userId={userId}
+                onUpdate={() => console.log('Profile updated')}
+            />
+        </SuspenseLoader>
+    );
+}
+
+export default UserProfilePage;
+```
+
+---
+
+## Example 4: List with Search and Filtering
+
+```typescript
+import React, { useState, useMemo } from 'react';
+import { Box, TextField, List, ListItem } from '@mui/material';
+import { useDebounce } from 'use-debounce';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { userApi } from '../api/userApi';
+
+export const UserList: React.FC = () => {
+    const [searchTerm, setSearchTerm] = useState('');
+    const [debouncedSearch] = useDebounce(searchTerm, 300);
+
+    const { data: users } = useSuspenseQuery({
+        queryKey: ['users'],
+        queryFn: () => userApi.getUsers(),
+    });
+
+    // Memoized filtering
+    const filteredUsers = useMemo(() => {
+        if (!debouncedSearch) return users;
+
+        return users.filter(user =>
+            user.name.toLowerCase().includes(debouncedSearch.toLowerCase()) ||
+            user.email.toLowerCase().includes(debouncedSearch.toLowerCase())
+        );
+    }, [users, debouncedSearch]);
+
+    return (
+        <Box>
+            <TextField
+                value={searchTerm}
+                onChange={(e) => setSearchTerm(e.target.value)}
+                placeholder='Search users...'
+                fullWidth
+                sx={{ mb: 2 }}
+            />
+
+            <List>
+                {filteredUsers.map(user => (
+                    <ListItem key={user.id}>
+                        {user.name} - {user.email}
+                    </ListItem>
+                ))}
+            </List>
+        </Box>
+    );
+};
+```
+
+---
+
+## Example 5: Blog with Validation
+
+```typescript
+import React from 'react';
+import { Box, TextField, Button, Paper } from '@mui/material';
+import { useBlog } from 'react-hook-blog';
+import { zodResolver } from '@hookblog/resolvers/zod';
+import { z } from 'zod';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { userApi } from '../api/userApi';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+const userSchema = z.object({
+    username: z.string().min(3).max(50),
+    email: z.string().email(),
+    firstName: z.string().min(1),
+    lastName: z.string().min(1),
+});
+
+type UserBlogData = z.infer<typeof userSchema>;
+
+interface CreateUserBlogProps {
+    onSuccess?: () => void;
+}
+
+export const CreateUserBlog: React.FC<CreateUserBlogProps> = ({ onSuccess }) => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    const { register, handleSubmit, blogState: { errors }, reset } = useBlog<UserBlogData>({
+        resolver: zodResolver(userSchema),
+        defaultValues: {
+            username: '',
+            email: '',
+            firstName: '',
+            lastName: '',
+        },
+    });
+
+    const createMutation = useMutation({
+        mutationFn: (data: UserBlogData) => userApi.createUser(data),
+
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: ['users'] });
+            showSuccess('User created successfully');
+            reset();
+            onSuccess?.();
+        },
+
+        onError: () => {
+            showError('Failed to create user');
+        },
+    });
+
+    const onSubmit = (data: UserBlogData) => {
+        createMutation.mutate(data);
+    };
+
+    return (
+        <Paper sx={{ p: 3, maxWidth: 500 }}>
+            <blog onSubmit={handleSubmit(onSubmit)}>
+                <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+                    <TextField
+                        {...register('username')}
+                        label='Username'
+                        error={!!errors.username}
+                        helperText={errors.username?.message}
+                        fullWidth
+                    />
+
+                    <TextField
+                        {...register('email')}
+                        label='Email'
+                        type='email'
+                        error={!!errors.email}
+                        helperText={errors.email?.message}
+                        fullWidth
+                    />
+
+                    <TextField
+                        {...register('firstName')}
+                        label='First Name'
+                        error={!!errors.firstName}
+                        helperText={errors.firstName?.message}
+                        fullWidth
+                    />
+
+                    <TextField
+                        {...register('lastName')}
+                        label='Last Name'
+                        error={!!errors.lastName}
+                        helperText={errors.lastName?.message}
+                        fullWidth
+                    />
+
+                    <Button
+                        type='submit'
+                        variant='contained'
+                        disabled={createMutation.isPending}
+                    >
+                        {createMutation.isPending ? 'Creating...' : 'Create User'}
+                    </Button>
+                </Box>
+            </blog>
+        </Paper>
+    );
+};
+
+export default CreateUserBlog;
+```
+
+---
+
+## Example 2: Parent Container with Lazy Loading
+
+```typescript
+import React from 'react';
+import { Box } from '@mui/material';
+import { SuspenseLoader } from '~components/SuspenseLoader';
+
+// Lazy load heavy components
+const UserList = React.lazy(() => import('./UserList'));
+const UserStats = React.lazy(() => import('./UserStats'));
+const ActivityFeed = React.lazy(() => import('./ActivityFeed'));
+
+export const UserDashboard: React.FC = () => {
+    return (
+        <Box sx={{ p: 2 }}>
+            <SuspenseLoader>
+                <UserStats />
+            </SuspenseLoader>
+
+            <Box sx={{ display: 'flex', gap: 2, mt: 2 }}>
+                <Box sx={{ flex: 2 }}>
+                    <SuspenseLoader>
+                        <UserList />
+                    </SuspenseLoader>
+                </Box>
+
+                <Box sx={{ flex: 1 }}>
+                    <SuspenseLoader>
+                        <ActivityFeed />
+                    </SuspenseLoader>
+                </Box>
+            </Box>
+        </Box>
+    );
+};
+
+export default UserDashboard;
+```
+
+**Benefits:**
+- Each section loads independently
+- User sees partial content sooner
+- Better perceived perblogance
+
+---
+
+## Example 3: Cache-First Strategy Implementation
+
+Complete example based on useSuspensePost.ts:
+
+```typescript
+import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
+import { postApi } from '../api/postApi';
+import type { Post } from '../types';
+
+/**
+ * Smart post hook with cache-first strategy
+ * Reuses data from grid cache when available
+ */
+export function useSuspensePost(blogId: number, postId: number) {
+    const queryClient = useQueryClient();
+
+    return useSuspenseQuery<Post, Error>({
+        queryKey: ['post', blogId, postId],
+        queryFn: async () => {
+            // Strategy 1: Check grid cache first (avoids API call)
+            const gridCache = queryClient.getQueryData<{ rows: Post[] }>([
+                'posts-v2',
+                blogId,
+                'summary'
+            ]) || queryClient.getQueryData<{ rows: Post[] }>([
+                'posts-v2',
+                blogId,
+                'flat'
+            ]);
+
+            if (gridCache?.rows) {
+                const cached = gridCache.rows.find(
+                    (row) => row.S_ID === postId
+                );
+
+                if (cached) {
+                    return cached;  // Return from cache - no API call!
+                }
+            }
+
+            // Strategy 2: Not in cache, fetch from API
+            return postApi.getPost(blogId, postId);
+        },
+        staleTime: 5 * 60 * 1000,       // Fresh for 5 minutes
+        gcTime: 10 * 60 * 1000,          // Cache for 10 minutes
+        refetchOnWindowFocus: false,     // Don't refetch on focus
+    });
+}
+```
+
+**Why this pattern:**
+- Checks grid cache before API
+- Instant data if user came from grid
+- Falls back to API if not cached
+- Configurable cache times
+
+---
+
+## Example 4: Complete Route File
+
+```typescript
+/**
+ * Project catalog route
+ * Path: /project-catalog
+ */
+
+import { createFileRoute } from '@tanstack/react-router';
+import { lazy } from 'react';
+
+// Lazy load the PostTable component
+const PostTable = lazy(() =>
+    import('@/features/posts/components/PostTable').then(
+        (module) => ({ default: module.PostTable })
+    )
+);
+
+// Route constants
+const PROJECT_CATALOG_FORM_ID = 744;
+const PROJECT_CATALOG_PROJECT_ID = 225;
+
+export const Route = createFileRoute('/project-catalog/')({
+    component: ProjectCatalogPage,
+    loader: () => ({
+        crumb: 'Projects',  // Breadcrumb title
+    }),
+});
+
+function ProjectCatalogPage() {
+    return (
+        <PostTable
+            blogId={PROJECT_CATALOG_FORM_ID}
+            projectId={PROJECT_CATALOG_PROJECT_ID}
+            tableType='active_projects'
+            title='Blog Dashboard'
+        />
+    );
+}
+
+export default ProjectCatalogPage;
+```
+
+---
+
+## Example 5: Dialog with Blog
+
+```typescript
+import React from 'react';
+import {
+    Dialog,
+    DialogTitle,
+    DialogContent,
+    DialogActions,
+    Button,
+    TextField,
+    Box,
+    IconButton,
+} from '@mui/material';
+import { Close, PersonAdd } from '@mui/icons-material';
+import { useBlog } from 'react-hook-blog';
+import { zodResolver } from '@hookblog/resolvers/zod';
+import { z } from 'zod';
+
+const blogSchema = z.object({
+    name: z.string().min(1),
+    email: z.string().email(),
+});
+
+type BlogData = z.infer<typeof blogSchema>;
+
+interface AddUserDialogProps {
+    open: boolean;
+    onClose: () => void;
+    onSubmit: (data: BlogData) => Promise<void>;
+}
+
+export const AddUserDialog: React.FC<AddUserDialogProps> = ({
+    open,
+    onClose,
+    onSubmit,
+}) => {
+    const { register, handleSubmit, blogState: { errors }, reset } = useBlog<BlogData>({
+        resolver: zodResolver(blogSchema),
+    });
+
+    const handleClose = () => {
+        reset();
+        onClose();
+    };
+
+    const handleBlogSubmit = async (data: BlogData) => {
+        await onSubmit(data);
+        handleClose();
+    };
+
+    return (
+        <Dialog open={open} onClose={handleClose} maxWidth='sm' fullWidth>
+            <DialogTitle>
+                <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                        <PersonAdd color='primary' />
+                        Add User
+                    </Box>
+                    <IconButton onClick={handleClose} size='small'>
+                        <Close />
+                    </IconButton>
+                </Box>
+            </DialogTitle>
+
+            <blog onSubmit={handleSubmit(handleBlogSubmit)}>
+                <DialogContent>
+                    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+                        <TextField
+                            {...register('name')}
+                            label='Name'
+                            error={!!errors.name}
+                            helperText={errors.name?.message}
+                            fullWidth
+                            autoFocus
+                        />
+
+                        <TextField
+                            {...register('email')}
+                            label='Email'
+                            type='email'
+                            error={!!errors.email}
+                            helperText={errors.email?.message}
+                            fullWidth
+                        />
+                    </Box>
+                </DialogContent>
+
+                <DialogActions>
+                    <Button onClick={handleClose}>Cancel</Button>
+                    <Button type='submit' variant='contained'>
+                        Add User
+                    </Button>
+                </DialogActions>
+            </blog>
+        </Dialog>
+    );
+};
+```
+
+---
+
+## Example 6: Parallel Data Fetching
+
+```typescript
+import React from 'react';
+import { Box, Grid, Paper } from '@mui/material';
+import { useSuspenseQueries } from '@tanstack/react-query';
+import { userApi } from '../api/userApi';
+import { statsApi } from '../api/statsApi';
+import { activityApi } from '../api/activityApi';
+
+export const Dashboard: React.FC = () => {
+    // Fetch all data in parallel with Suspense
+    const [statsQuery, usersQuery, activityQuery] = useSuspenseQueries({
+        queries: [
+            {
+                queryKey: ['stats'],
+                queryFn: () => statsApi.getStats(),
+            },
+            {
+                queryKey: ['users', 'active'],
+                queryFn: () => userApi.getActiveUsers(),
+            },
+            {
+                queryKey: ['activity', 'recent'],
+                queryFn: () => activityApi.getRecent(),
+            },
+        ],
+    });
+
+    return (
+        <Box sx={{ p: 2 }}>
+            <Grid container spacing={2}>
+                <Grid size={{ xs: 12, md: 4 }}>
+                    <Paper sx={{ p: 2 }}>
+                        <h3>Stats</h3>
+                        <p>Total: {statsQuery.data.total}</p>
+                    </Paper>
+                </Grid>
+
+                <Grid size={{ xs: 12, md: 4 }}>
+                    <Paper sx={{ p: 2 }}>
+                        <h3>Active Users</h3>
+                        <p>Count: {usersQuery.data.length}</p>
+                    </Paper>
+                </Grid>
+
+                <Grid size={{ xs: 12, md: 4 }}>
+                    <Paper sx={{ p: 2 }}>
+                        <h3>Recent Activity</h3>
+                        <p>Events: {activityQuery.data.length}</p>
+                    </Paper>
+                </Grid>
+            </Grid>
+        </Box>
+    );
+};
+
+// Usage with Suspense
+<SuspenseLoader>
+    <Dashboard />
+</SuspenseLoader>
+```
+
+---
+
+## Example 7: Optimistic Update
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { User } from '../types';
+
+export const useToggleUserStatus = () => {
+    const queryClient = useQueryClient();
+
+    return useMutation({
+        mutationFn: (userId: string) => userApi.toggleStatus(userId),
+
+        // Optimistic update
+        onMutate: async (userId) => {
+            // Cancel outgoing refetches
+            await queryClient.cancelQueries({ queryKey: ['users'] });
+
+            // Snapshot previous value
+            const previousUsers = queryClient.getQueryData<User[]>(['users']);
+
+            // Optimistically update UI
+            queryClient.setQueryData<User[]>(['users'], (old) => {
+                return old?.map(user =>
+                    user.id === userId
+                        ? { ...user, active: !user.active }
+                        : user
+                ) || [];
+            });
+
+            return { previousUsers };
+        },
+
+        // Rollback on error
+        onError: (err, userId, context) => {
+            queryClient.setQueryData(['users'], context?.previousUsers);
+        },
+
+        // Refetch after mutation
+        onSettled: () => {
+            queryClient.invalidateQueries({ queryKey: ['users'] });
+        },
+    });
+};
+```
+
+---
+
+## Summary
+
+**Key Takeaways:**
+
+1. **Component Pattern**: React.FC + lazy + Suspense + useSuspenseQuery
+2. **Feature Structure**: Organized subdirectories (api/, components/, hooks/, etc.)
+3. **Routing**: Folder-based with lazy loading
+4. **Data Fetching**: useSuspenseQuery with cache-first strategy
+5. **Blogs**: React Hook Blog + Zod validation
+6. **Error Handling**: useMuiSnackbar + onError callbacks
+7. **Perblogance**: useMemo, useCallback, React.memo, debouncing
+8. **Styling**: Inline <100 lines, sx prop, MUI v7 syntax
+
 **See other resources for detailed explanations of each pattern.**