Правила форматирования и структуры проекта

1. Структура проекта

src/
├── app/              # Next.js App Router
├── entities/         # Бизнес-сущности
│   └── user/
│       ├── user.dto.ts           # Типы данных и схемы
│       ├── user.builder.ts       # Билдеры для трансформации данных
│       ├── user.repository.ts    # Работа с API
│       └── user.role.tsx         # Связанные константы и типы
├── features/         # Функциональные компоненты
│   └── user/
│       ├── user.form.tsx         # Формы
│       ├── user.search.tsx       # Поиск
│       └── user.table.tsx        # Таблицы
├── widgets/          # Композиционные компоненты
│   └── user-management/
│       └── user-management.panel.tsx
└── shared/          # Общие утилиты и типы

2. Правила именования

Файлы

• Используйте kebab-case для директорий: user-management/
• Используйте точечную нотацию для файлов: user-search.form.tsx
• Добавляйте суффиксы по типу файла:
  • .dto.ts - типы данных
  • .builder.ts - билдеры
  • .repository.ts - API
  • .panel.tsx - страницы/панели
  • .form.tsx - формы
  • .table.tsx - таблицы

Компоненты

• PascalCase для имен компонентов: UserTable
• Используйте суффиксы по типу:
  • *Panel - для страниц/панелей
  • *Form - для форм
  • *Table - для таблиц
  • *Modal - для модальных окон

3. Структура файла компонента

'use client';  // Для клиентских компонентов

// 1. Импорты
import { ... } from '@mantine/core';          // UI библиотеки
import { ... } from '@tanstack/react-query';  // Утилиты
import { z } from 'zod';                      // Типизация

import { ... } from '@/features/user/...';    // Локальные импорты
import { ... } from '@/entities/user/...';
import { ... } from '@/shared/...';

// 2. Типы и схемы
const SomeSchema = z.object({ ... });

// 3. Вспомогательные функции и хуки
function useHelper() { ... }

// 4. Основной компонент
export function ComponentName() {
  // 4.1 Хуки и состояния
  const [state, setState] = useState();
  const query = useQuery({ ... });

  // 4.2 Обработчики
  function handleAction() { ... }

  // 4.3 Рендер
  return ( ... );
}

4. Декомпозиция компонентов

Паттерны композиции

• Используйте паттерн композиции через объект:

export const UserTable = {
	Root,
	Actions: {
		Root: ActionsRoot,
		Edit,
		Delete,
	},
};

Формы

• Создавайте отдельные контексты для форм с помощью createFormContext
• Выносите логику валидации в схемы
• Разделяйте форму на отдельные компоненты для каждого поля
• Используйте кастомные хуки для работы с формой

Таблицы

• Выносите конфигурацию колонок в отдельный хук
• Разделяйте действия (Actions) на отдельные компоненты
• Используйте контекст для передачи данных в действия
• Обрабатывайте состояния загрузки и мутации

Поиск и фильтрация

• Используйте дебаунс для поисковых запросов
• Разделяйте логику фильтрации на отдельные компоненты
• Храните состояние фильтров в форме

5. Типизация и валидация

• Используйте Zod для валидации данных:

const schema = z.object({
	id: z.number(),
	name: z.string(),
});

• Выносите типы в отдельные .dto.ts файлы
• Используйте строгую типизацию для пропсов
• Документируйте обязательные и опциональные параметры

6. Работа с данными

Билдеры

export class UserBuilder {
    static fromDTO(dto: UserDTO) { ... }
    buildTableRecord() { ... }
    buildFormValues() { ... }
}

Репозитории

export class UserRepository {
    async getList(params: ListParams) { ... }
    async getById(id: number) { ... }
    async create(data: CreateDTO) { ... }
}

7. Стилизация и UI

• Используйте компоненты UI библиотеки последовательно
• Группируйте стилевые пропсы в конце списка пропсов
• Используйте константы для повторяющихся значений
• Поддерживайте единообразие в использовании компонентов

8. Обработка ошибок и состояний

• Добавляйте проверки на существование контекста
• Обрабатывайте все возможные состояния:
  • Загрузка данных
  • Ошибки
  • Пустые данные
  • Мутации
• Используйте типизированные схемы для валидации данных

9. Переиспользование кода

• Создавайте общие компоненты для повторяющихся элементов
• Выносите общую логику в хуки
• Используйте константы для повторяющихся значений
• Следуйте DRY принципу

10. Правила импортов

• Группируйте импорты с пустой строкой между группами:
  1. React и клиентские директивы
  2. Внешние библиотеки
  3. Next.js/маршрутизация
  4. Локальные импорты (features, entities, shared)

11. Форматирование кода

• Используйте табы для отступов
• Максимальная длина строки: 80 символов
• Используйте точку с запятой в конце строк
• Используйте одинарные кавычки для строк
• Деструктуризация пропсов в параметрах функции

12. Документация

• Добавляйте JSDoc для публичных функций и типов
• Документируйте неочевидные решения
• Указывайте типы для всех параметров функций
• Добавляйте примеры использования для сложных компонентов