Admin

name	type	size	perms	modified	actions
[parent directory]
checkout-plan/	dir	-	0775	2026-08-24 19:20:23
api-1.md	file	21,803 B	0664	2025-07-29 09:30:17	edit
api-2.md	file	24,042 B	0664	2025-07-30 16:27:58	edit
api-3.md	file	17,087 B	0664	2025-07-29 09:30:17	edit
api-table.md	file	15,279 B	0664	2025-07-29 09:30:17	edit
backlog.md	file	5,761 B	0664	2025-07-29 09:30:17	edit
environment-variables.md	file	6,234 B	0664	2025-07-29 09:30:17	edit
error-response-standard.md	file	10,066 B	0664	2025-07-29 09:30:17	edit
implementation-improvements-summary.md	file	8,114 B	0664	2025-07-29 09:30:17	edit
midtrans-integration.md	file	18,835 B	0664	2025-07-29 09:30:17	edit
profile-completion-implementation.md	file	18,073 B	0664	2025-07-29 09:30:17	edit
sql-2.md	file	28,518 B	0664	2025-07-29 09:30:17	edit
sql-3.md	file	24,303 B	0664	2025-07-29 09:30:17	edit
sql.md	file	15,240 B	0664	2025-07-29 09:30:17	edit
web-coding-standard.md	file	10,747 B	0664	2025-07-29 09:30:17	edit

editing: web-coding-standard.md

# Frontend Coding Standards

## 1. File Structure and Naming

### File Naming Conventions
- **Components**: PascalCase with descriptive names
  - `LoginPage.tsx`, `EventDetailPage.tsx`, `UserProfileCard.tsx`
- **Hooks**: camelCase starting with "use"
  - `useAuth.ts`, `useEventQueries.ts`, `useFormValidation.ts`
- **Utils**: camelCase
  - `api.ts`, `validation.ts`, `dateHelpers.ts`
- **Types**: camelCase
  - `auth.ts`, `events.ts`, `common.ts`
- **Constants**: camelCase
  - `urls.ts`, `ticketOptions.ts`, `apiEndpoints.ts`

### Directory Structure
```
src/
├── components/          # Custom reusable components
│   ├── ui/             # Custom UI components (our own)
│   ├── auth/           # Authentication-specific components
│   └── [feature]/      # Feature-specific components
├── ui/                 # Subframe UI components (external)
├── pages/              # Page components
├── hooks/              # Custom hooks
│   └── queries/        # React Query hooks
├── contexts/           # React contexts
├── types/              # TypeScript type definitions
├── utils/              # Utility functions
├── constants/          # Application constants
└── i18n/              # Internationalization
    └── locales/        # Translation files
```

## 2. Import/Export Standards

### Export Conventions
- **Default exports only** for all components, pages, and main modules
- Use named exports only for utility functions and constants that are meant to be imported selectively

```tsx
// ✅ Correct - Default export
export default function LoginPage() {
  // component code
}

// ✅ Correct - Named exports for utilities
export const formatDate = (date: Date) => { /* */ };
export const validateEmail = (email: string) => { /* */ };
```

### Import Order
1. React and React-related imports
2. Third-party library imports (alphabetical)
3. Internal imports using path aliases (alphabetical)
4. Relative imports (alphabetical)
5. Type-only imports (at the end)

```tsx
// 1. React imports
import React, { useState, useEffect } from 'react';
import { useNavigate } from 'react-router-dom';

// 2. Third-party libraries (alphabetical)
import { useTranslation } from 'react-i18next';
import { useMutation } from '@tanstack/react-query';

// 3. Internal imports with path aliases (alphabetical)
import Button from '@/ui/components/Button';
import TextField from '@/ui/components/TextField';

// 4. Relative imports (alphabetical)
import useAuth from '../hooks/useAuth';
import { validateForm } from '../utils/validation';

// 5. Type-only imports
import type { LoginCredentials } from '../types/auth';
import type { ApiResponse } from '../types/api';
```

### Path Aliases
- Use `@/ui/*` for Subframe UI components
- Use relative imports for everything else
- Be consistent within each file

```tsx
// ✅ Correct
import Button from '@/ui/components/Button';
import useAuth from '../hooks/useAuth';

// ❌ Incorrect - mixing patterns
import Button from '../ui/components/Button';
import useAuth from 'src/hooks/useAuth';
```

## 3. Component Standards

### Component Structure
```tsx
// 1. Imports (following import order)
import React, { useState } from 'react';
import { useTranslation } from 'react-i18next';
import Button from '@/ui/components/Button';
import type { ComponentProps } from '../types/common';

// 2. Types/Interfaces
interface LoginFormProps {
  onSubmit: (data: LoginCredentials) => Promise<void>;
  error?: string;
}

// 3. Component
export default function LoginForm({ onSubmit, error }: LoginFormProps) {
  // 4. Hooks
  const { t } = useTranslation();
  const [isLoading, setIsLoading] = useState(false);

// 5. Event handlers
  const handleSubmit = async (data: LoginCredentials) => {
    setIsLoading(true);
    try {
      await onSubmit(data);
    } catch (error) {
      console.error('Login failed:', error);
    } finally {
      setIsLoading(false);
    }
  };

// 6. Render
  return (
    <form onSubmit={handleSubmit}>
      {/* JSX */}
    </form>
  );
}
```

### Component Naming
- Use PascalCase for component names
- Use descriptive names that indicate purpose
- Avoid abbreviations unless they're widely understood

```tsx
// ✅ Good
export default function UserProfileCard() {}
export default function EventDetailPage() {}
export default function TicketOrderForm() {}

// ❌ Bad
export default function UPC() {}
export default function EventDtl() {}
export default function TktForm() {}
```

## 4. Internationalization (i18n)

### Translation Usage
- **Always use `useTranslation` from react-i18next** (not custom hooks)
- **Never hardcode user-facing strings**
- Use descriptive translation keys with dot notation

```tsx
// ✅ Correct
import { useTranslation } from 'react-i18next';

export default function LoginPage() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('auth.signInToAccount')}</h1>
      <p>{t('auth.loginTagline')}</p>
    </div>
  );
}

// ❌ Incorrect
export default function LoginPage() {
  return (
    <div>
      <h1>Sign in to your account</h1>
      <p>Welcome back!</p>
    </div>
  );
}
```

### Translation Key Structure
- Use feature-based namespacing
- Use camelCase for keys
- Be descriptive and consistent

```json
{
  "auth": {
    "signIn": "Sign In",
    "signUp": "Sign Up",
    "signInToAccount": "Sign in to your account",
    "loginTagline": "Welcome back!"
  },
  "navigation": {
    "dashboard": "Dashboard",
    "profile": "Profile",
    "settings": "Settings",
    "logout": "Logout",
    "myTickets": "My Tickets"
  },
  "common": {
    "save": "Save",
    "cancel": "Cancel",
    "loading": "Loading...",
    "error": "Error",
    "success": "Success"
  }
}
```

## 5. TypeScript Standards

### Environment Variables
- Define all environment variables in `vite-env.d.ts`
- Use descriptive names with VITE_ prefix
- Include JSDoc comments for documentation

```typescript
/// <reference types="vite/client" />

interface ImportMetaEnv {
  /** Backend API base URL */
  readonly VITE_API_BASE_URL: string;
  /** Web admin application URL */
  readonly VITE_WEB_ADMIN_URL: string;
  /** Web ticketing application URL */
  readonly VITE_WEB_TICKETING_URL: string;
  /** Backend server URL */
  readonly VITE_BACKEND_URL: string;
  /** Application environment */
  readonly VITE_APP_ENV: 'development' | 'staging' | 'production';
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

### Type Definitions
- Use `type` instead of `interface` for simple type definitions
- Use `interface` for objects that might be extended
- Export types from centralized type files

```typescript
// ✅ Preferred for simple types
export type UserRole = 'admin' | 'user';
export type OrderStatus = 'cart' | 'locked' | 'pending' | 'paid';

// ✅ Use interface for extensible objects
export interface User {
  id: string;
  email: string;
  name: string;
  role: UserRole;
}

// ✅ Extending interfaces
export interface AdminUser extends User {
  permissions: string[];
}
```

## 6. Error Handling

### Consistent Error Handling Pattern
```tsx
import { useTranslation } from 'react-i18next';
import { ApiError } from '../utils/api';

export default function MyComponent() {
  const { t } = useTranslation();
  const [error, setError] = useState<string | null>(null);

return (
    <div>
      {error && <ErrorMessage message={error} />}
      {/* component content */}
    </div>
  );
}
```

### Error Boundaries
- Use ErrorBoundary components for catching React errors
- Provide fallback UI with translation support
- Log errors appropriately

## 7. State Management

### React Query
- Use React Query for server state
- Follow consistent query key patterns
- Handle loading and error states consistently

```tsx
// Query keys
export const eventKeys = {
  all: ['events'] as const,
  lists: () => [...eventKeys.all, 'list'] as const,
  list: (filters: EventFilters) => [...eventKeys.lists(), filters] as const,
  details: () => [...eventKeys.all, 'detail'] as const,
  detail: (id: string) => [...eventKeys.details(), id] as const,
};

// Hook usage
export function useEvent(eventId: string) {
  return useQuery({
    queryKey: eventKeys.detail(eventId),
    queryFn: () => api.get(`/events/${eventId}`),
    enabled: !!eventId,
  });
}
```

### Local State
- Use useState for simple local state
- Use useReducer for complex state logic
- Keep state as close to where it's used as possible

## 8. Styling Standards

### Tailwind CSS
- Use Tailwind utility classes
- Follow mobile-first responsive design
- Use consistent spacing and sizing scales

```tsx
// ✅ Good - mobile-first, consistent spacing
<div className="flex flex-col gap-4 p-4 md:flex-row md:gap-6 md:p-6">
  <button className="w-full rounded-md bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 md:w-auto">
    {t('common.submit')}
  </button>
</div>
```

### Component Styling
- Use Subframe components for consistent design system
- Extend with custom classes when needed
- Avoid inline styles

## 9. Performance Standards

### Code Splitting
- Use React.lazy for route-based code splitting
- Implement proper loading states

### Optimization
- Use React.memo for expensive components
- Implement proper dependency arrays for hooks
- Avoid unnecessary re-renders

## 10. Testing Standards

### Component Testing
- Test user interactions, not implementation details
- Use React Testing Library
- Test with translation keys

### API Testing
- Mock API calls in tests
- Test error scenarios
- Verify loading states

## 11. Documentation

### Code Comments
- Use JSDoc for functions and complex logic
- Explain "why" not "what"
- Keep comments up to date

### README Files
- Include setup instructions
- Document environment variables
- Provide usage examples

## 12. Git Standards

### Commit Messages
- Use conventional commit format
- Be descriptive and specific
- Reference issue numbers when applicable

```
feat(auth): add profile completion flow
fix(events): resolve ticket quantity validation
docs(readme): update environment setup instructions
```

### Branch Naming
- Use descriptive branch names
- Include issue numbers when applicable
- Use kebab-case

```
feature/user-profile-completion
bugfix/ticket-validation-error
hotfix/login-redirect-issue
```

This coding standard should be followed consistently across all frontend development to ensure maintainable, scalable, and readable code.

cancel