# Хуки (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` слоя/компонента.

## Примеры

```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.
- [ ] Документировано только назначение хука (см. [правила документирования кода](#правило-для-документирования-кода)).
- [ ] Нет неиспользуемого или невалидного кода.
- [ ] Экспорт только именованный через индексный файл.