frontend-style-guide/OLD_parts/13-hooks.md

Хуки (React Hooks)

В проекте для создания пользовательских хуков используется только React (функциональные компоненты и хуки).
В этом разделе собраны основные правила и рекомендации по созданию и оформлению хуков. Следуйте этим принципам, чтобы обеспечить чистую архитектуру, переиспользуемость и единый стиль работы с хуками в проекте.

Рекомендации по использованию сторонних хуков

• Если есть возможность, используйте хуки Mantine в компонентах и кастомных хуках для работы с состоянием, темизацией, медиа-запросами и другими возможностями библиотеки.
• Не дублируйте функциональность, уже реализованную в Mantine.

Структура

• Каждый хук размещается в отдельном файле с именем use-<hook-name>.hook.ts в папке hooks/ на своём уровне абстракции согласно архитектуре проекта.
• Имя хука — в стиле camelCase с префиксом use (например, useTodoFilter).
• Для сложных возвращаемых структур использовать отдельные типы или интерфейсы, размещая их в папке types/ на своём уровне абстракции.

Именование

• Соблюдайте правила именования файлов и папок:
  • Файл хука — use-<hook-name>.hook.ts (kebab-case).
  • Имя хука — camelCase с префиксом use.

Требования

• Хук должен быть строго типизирован: все параметры, возвращаемые значения и внутренние переменные должны иметь явные типы.
• Не хранить бизнес-логику, связанную с несколькими слоями — хук должен быть изолирован в рамках своего слоя/feature.
• Не дублировать логику между хуками — общие части выносить в shared.
• Не использовать side-effects вне useEffect/useLayoutEffect.
• Для мемоизации возвращаемых значений и функций использовать useMemo и useCallback.
• Не использовать устаревшие или неразрешённые паттерны React.

Типизация

• Всегда явно указывать типы для всех параметров, возвращаемых значений и состояния внутри хука.
• Не используйте неявное приведение типов и не полагайтесь на автоматический вывод, если это может снизить читаемость или безопасность.

Документирование

• Документируйте только назначение хука (описание), строго по правилам документирования кода.

Экспорт

• Экспортируйте хук только именованным экспортом через index.ts слоя/компонента.

Примеры

import { useMemo } from 'react';
import { TodoItem } from '../types/todo-item.interface';
import { TodoStatus } from '../types/todo-status.enum';

/**
 * Хук фильтрации задач по статусу.
 */
export const useTodoFilter = (items: TodoItem[], filter: TodoStatus): TodoItem[] => {
  return useMemo(() => {
    if (filter === TodoStatus.ALL) return items;
    if (filter === TodoStatus.ACTIVE) return items.filter((t) => !t.completed);
    return items.filter((t) => t.completed);
  }, [items, filter]);
};

Чек-лист

• Хук размещён в файле use-<hook-name>.hook.ts в папке hooks/ на своём уровне абстракции согласно архитектуре проекта.
• Именование файлов и сущностей соответствует правилам именования файлов и папок.
• Все параметры, возвращаемые значения и внутренние переменные строго типизированы.
• Вся бизнес-логика изолирована в рамках слоя/feature.
• Нет дублирования логики между хуками.
• Для мемоизации используется useMemo/useCallback.
• Не используются side-effects вне useEffect/useLayoutEffect.
• Документировано только назначение хука (см. правила документирования кода).
• Нет неиспользуемого или невалидного кода.
• Экспорт только именованный через индексный файл.