@thanhthi2895/luna-ai 2.16.2

package/agentic/opencode/.opencode/skills/frontend-development/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: lu:frontend-development
+description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense, lazy loading, useSuspenseQuery, MUI v7 styling, TanStack Router, performance optimization.
+argument-hint: "[component or feature]"
+---
+
+# Frontend Development Guidelines
+
+Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.
+
+## When to Use This Skill
+
+- Creating new components or pages
+- Building new features
+- Fetching data with TanStack Query
+- Setting up routing with TanStack Router
+- Styling components with MUI v7
+- Performance optimization
+- Organizing frontend code
+- TypeScript best practices
+
+---
+
+## Quick Start
+
+### New Component Checklist
+
+- [ ] Use `React.FC<Props>` pattern with TypeScript
+- [ ] Lazy load if heavy component: `React.lazy(() => import())`
+- [ ] Wrap in `<SuspenseLoader>` for loading states
+- [ ] Use `useSuspenseQuery` for data fetching
+- [ ] Styles: Inline if <100 lines, separate file if >100 lines
+- [ ] Use `useCallback` for event handlers passed to children
+- [ ] Default export at bottom
+- [ ] No early returns with loading spinners
+
+### New Feature Checklist
+
+- [ ] Create `features/{feature-name}/` directory
+- [ ] Create subdirectories: `api/`, `components/`, `hooks/`, `helpers/`, `types/`
+- [ ] Create API service file: `api/{feature}Api.ts`
+- [ ] Set up TypeScript types in `types/`
+- [ ] Create route in `routes/{feature-name}/index.tsx`
+- [ ] Lazy load feature components
+- [ ] Export public API from feature `index.ts`
+
+---
+
+## Core Principles
+
+1. **Lazy Load Everything Heavy**: Routes, DataGrid, charts, editors
+2. **Suspense for Loading**: Use SuspenseLoader, not early returns
+3. **useSuspenseQuery**: Primary data fetching pattern for new code
+4. **Features are Organized**: api/, components/, hooks/, helpers/ subdirs
+5. **Styles Based on Size**: <100 inline, >100 separate
+6. **No Early Returns**: Prevents layout shift
+7. **TypeScript Strict**: No `any`, explicit return types
+
+---
+
+## Component Pattern
+
+```typescript
+import React, { useState, useCallback } from 'react';
+import { Box, Paper } from '@mui/material';
+import { useSuspenseQuery } from '@tanstack/react-query';
+import { featureApi } from '../api/featureApi';
+import type { FeatureData } from '~types/feature';
+
+interface MyComponentProps {
+    id: number;
+    onAction?: () => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
+    const [state, setState] = useState<string>('');
+
+    const { data } = useSuspenseQuery({
+        queryKey: ['feature', id],
+        queryFn: () => featureApi.getFeature(id),
+    });
+
+    const handleAction = useCallback(() => {
+        setState('updated');
+        onAction?.();
+    }, [onAction]);
+
+    return (
+        <Box sx={{ p: 2 }}>
+            <Paper sx={{ p: 3 }}>
+                {/* Content */}
+            </Paper>
+        </Box>
+    );
+};
+
+export default MyComponent;
+```
+
+---
+
+## Data Fetching (PRIMARY: useSuspenseQuery)
+
+```typescript
+// ✅ Suspense-based (preferred)
+const { data } = useSuspenseQuery({
+    queryKey: ['items', id],
+    queryFn: () => api.getItems(id),
+});
+
+// ❌ Old pattern with isLoading
+const { data, isLoading } = useQuery(...);
+if (isLoading) return <Spinner />; // causes layout shift
+```
+
+---
+
+## Loading States (CRITICAL RULE: No Early Returns)
+
+```typescript
+// ❌ NEVER - Causes layout shift
+if (isLoading) return <LoadingSpinner />;
+
+// ✅ ALWAYS - Consistent layout
+<SuspenseLoader>
+    <Content />
+</SuspenseLoader>
+```
+
+---
+
+## MUI v7 Styling
+
+```typescript
+// ✅ v7 Grid syntax
+<Grid size={{ xs: 12, md: 6 }}>
+
+// ❌ Old syntax
+<Grid xs={12} md={6}>
+
+// Sx prop pattern
+<Box sx={{ p: 2, backgroundColor: (theme) => theme.palette.primary.main }}>
+```
+
+---
+
+## File Structure
+
+```
+src/
+  features/
+    my-feature/
+      api/
+        myFeatureApi.ts       # API service
+      components/
+        MyFeature.tsx         # Main component
+        SubComponent.tsx      # Related components
+      hooks/
+        useMyFeature.ts       # Custom hooks
+      helpers/
+        myFeatureHelpers.ts   # Utilities
+      types/
+        index.ts              # TypeScript types
+      index.ts                # Public exports
+
+  components/
+    SuspenseLoader/           # Reusable loader
+    CustomAppBar/             # Reusable app bar
+
+  routes/
+    my-route/
+      index.tsx               # Route component
+```
+
+---
+
+## Import Aliases
+
+| Alias | Resolves To |
+|-------|-------------|
+| `@/` | `src/` |
+| `~types` | `src/types` |
+| `~components` | `src/components` |
+| `~features` | `src/features` |
+
+---
+
+## Performance Optimization
+
+- `useMemo`: Expensive computations (filter, sort, map)
+- `useCallback`: Event handlers passed to children
+- `React.memo`: Expensive components
+- Debounced search (300-500ms)
+- Memory leak prevention (cleanup in useEffect)
+
+---
+
+## Routing (TanStack Router)
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router';
+import { lazy } from 'react';
+
+const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));
+
+export const Route = createFileRoute('/my-route/')({
+    component: MyPage,
+    loader: () => ({ crumb: 'My Route' }),
+});
+```

package/agentic/opencode/.opencode/skills/frontend-development/resources/common-patterns.md

@@ -0,0 +1,331 @@
+# Common Patterns
+
+Frequently used patterns for forms, authentication, DataGrid, dialogs, and other common UI elements.
+
+---
+
+## Authentication with useAuth
+
+### Getting Current User
+
+```typescript
+import { useAuth } from '@/hooks/useAuth';
+
+export const MyComponent: React.FC = () => {
+    const { user } = useAuth();
+
+    // Available properties:
+    // - user.id: string
+    // - user.email: string
+    // - user.username: string
+    // - user.roles: string[]
+
+    return (
+        <div>
+            <p>Logged in as: {user.email}</p>
+            <p>Username: {user.username}</p>
+            <p>Roles: {user.roles.join(', ')}</p>
+        </div>
+    );
+};
+```
+
+**NEVER make direct API calls for auth** - always use `useAuth` hook.
+
+---
+
+## Forms with React Hook Form
+
+### Basic Form
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { TextField, Button } from '@mui/material';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+// Zod schema for validation
+const formSchema = z.object({
+    username: z.string().min(3, 'Username must be at least 3 characters'),
+    email: z.string().email('Invalid email address'),
+    age: z.number().min(18, 'Must be 18 or older'),
+});
+
+type FormData = z.infer<typeof formSchema>;
+
+export const MyForm: React.FC = () => {
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
+        resolver: zodResolver(formSchema),
+        defaultValues: {
+            username: '',
+            email: '',
+            age: 18,
+        },
+    });
+
+    const onSubmit = async (data: FormData) => {
+        try {
+            await api.submitForm(data);
+            showSuccess('Form submitted successfully');
+        } catch (error) {
+            showError('Failed to submit form');
+        }
+    };
+
+    return (
+        <form onSubmit={handleSubmit(onSubmit)}>
+            <TextField
+                {...register('username')}
+                label='Username'
+                error={!!errors.username}
+                helperText={errors.username?.message}
+            />
+
+            <TextField
+                {...register('email')}
+                label='Email'
+                error={!!errors.email}
+                helperText={errors.email?.message}
+                type='email'
+            />
+
+            <TextField
+                {...register('age', { valueAsNumber: true })}
+                label='Age'
+                error={!!errors.age}
+                helperText={errors.age?.message}
+                type='number'
+            />
+
+            <Button type='submit' variant='contained'>
+                Submit
+            </Button>
+        </form>
+    );
+};
+```
+
+---
+
+## Dialog Component Pattern
+
+### Standard Dialog Structure
+
+From BEST_PRACTICES.md - All dialogs should have:
+- Icon in title
+- Close button (X)
+- Action buttons at bottom
+
+```typescript
+import { Dialog, DialogTitle, DialogContent, DialogActions, Button, IconButton } from '@mui/material';
+import { Close, Info } from '@mui/icons-material';
+
+interface MyDialogProps {
+    open: boolean;
+    onClose: () => void;
+    onConfirm: () => void;
+}
+
+export const MyDialog: React.FC<MyDialogProps> = ({ open, onClose, onConfirm }) => {
+    return (
+        <Dialog open={open} onClose={onClose} maxWidth='sm' fullWidth>
+            <DialogTitle>
+                <Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+                        <Info color='primary' />
+                        Dialog Title
+                    </Box>
+                    <IconButton onClick={onClose} size='small'>
+                        <Close />
+                    </IconButton>
+                </Box>
+            </DialogTitle>
+
+            <DialogContent>
+                {/* Content here */}
+            </DialogContent>
+
+            <DialogActions>
+                <Button onClick={onClose}>Cancel</Button>
+                <Button onClick={onConfirm} variant='contained'>
+                    Confirm
+                </Button>
+            </DialogActions>
+        </Dialog>
+    );
+};
+```
+
+---
+
+## DataGrid Wrapper Pattern
+
+### Wrapper Component Contract
+
+From BEST_PRACTICES.md - DataGrid wrappers should accept:
+
+**Required Props:**
+- `rows`: Data array
+- `columns`: Column definitions
+- Loading/error states
+
+**Optional Props:**
+- Toolbar components
+- Custom actions
+- Initial state
+
+```typescript
+import { DataGridPro } from '@mui/x-data-grid-pro';
+import type { GridColDef } from '@mui/x-data-grid-pro';
+
+interface DataGridWrapperProps {
+    rows: any[];
+    columns: GridColDef[];
+    loading?: boolean;
+    toolbar?: React.ReactNode;
+    onRowClick?: (row: any) => void;
+}
+
+export const DataGridWrapper: React.FC<DataGridWrapperProps> = ({
+    rows,
+    columns,
+    loading = false,
+    toolbar,
+    onRowClick,
+}) => {
+    return (
+        <DataGridPro
+            rows={rows}
+            columns={columns}
+            loading={loading}
+            slots={{ toolbar: toolbar ? () => toolbar : undefined }}
+            onRowClick={(params) => onRowClick?.(params.row)}
+            // Standard configuration
+            pagination
+            pageSizeOptions={[25, 50, 100]}
+            initialState={{
+                pagination: { paginationModel: { pageSize: 25 } },
+            }}
+        />
+    );
+};
+```
+
+---
+
+## Mutation Patterns
+
+### Update with Cache Invalidation
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+export const useUpdateEntity = () => {
+    const queryClient = useQueryClient();
+    const { showSuccess, showError } = useMuiSnackbar();
+
+    return useMutation({
+        mutationFn: ({ id, data }: { id: number; data: any }) =>
+            api.updateEntity(id, data),
+
+        onSuccess: (result, variables) => {
+            // Invalidate affected queries
+            queryClient.invalidateQueries({ queryKey: ['entity', variables.id] });
+            queryClient.invalidateQueries({ queryKey: ['entities'] });
+
+            showSuccess('Entity updated');
+        },
+
+        onError: () => {
+            showError('Failed to update entity');
+        },
+    });
+};
+
+// Usage
+const updateEntity = useUpdateEntity();
+
+const handleSave = () => {
+    updateEntity.mutate({ id: 123, data: { name: 'New Name' } });
+};
+```
+
+---
+
+## State Management Patterns
+
+### TanStack Query for Server State (PRIMARY)
+
+Use TanStack Query for **all server data**:
+- Fetching: useSuspenseQuery
+- Mutations: useMutation
+- Caching: Automatic
+- Synchronization: Built-in
+
+```typescript
+// ✅ CORRECT - TanStack Query for server data
+const { data: users } = useSuspenseQuery({
+    queryKey: ['users'],
+    queryFn: () => userApi.getUsers(),
+});
+```
+
+### useState for UI State
+
+Use `useState` for **local UI state only**:
+- Form inputs (uncontrolled)
+- Modal open/closed
+- Selected tab
+- Temporary UI flags
+
+```typescript
+// ✅ CORRECT - useState for UI state
+const [modalOpen, setModalOpen] = useState(false);
+const [selectedTab, setSelectedTab] = useState(0);
+```
+
+### Zustand for Global Client State (Minimal)
+
+Use Zustand only for **global client state**:
+- Theme preference
+- Sidebar collapsed state
+- User preferences (not from server)
+
+```typescript
+import { create } from 'zustand';
+
+interface AppState {
+    sidebarOpen: boolean;
+    toggleSidebar: () => void;
+}
+
+export const useAppState = create<AppState>((set) => ({
+    sidebarOpen: true,
+    toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+}));
+```
+
+**Avoid prop drilling** - use context or Zustand instead.
+
+---
+
+## Summary
+
+**Common Patterns:**
+- ✅ useAuth hook for current user (id, email, roles, username)
+- ✅ React Hook Form + Zod for forms
+- ✅ Dialog with icon + close button
+- ✅ DataGrid wrapper contracts
+- ✅ Mutations with cache invalidation
+- ✅ TanStack Query for server state
+- ✅ useState for UI state
+- ✅ Zustand for global client state (minimal)
+
+**See Also:**
+- [data-fetching.md](data-fetching.md) - TanStack Query patterns
+- [component-patterns.md](component-patterns.md) - Component structure
+- [loading-and-error-states.md](loading-and-error-states.md) - Error handling