frontend/.ai/conventions/typescript-react.md

TypeScript и React

Types и components

• Сохраняй strict TS profile и import type. Для недоверенного значения используй unknown с narrowing; any не заменяет DTO/validation. Локальное исключение на нетипизированной boundary должно быть узким и объяснённым.
• enum и namespace не используются: frontend имеет erasableSyntaxOnly. Для состояния с разными payload выбирай discriminated union; не добавляй необязательные поля, допускающие невозможные комбинации.
• Named components — const-valued FC<Props>; named props находятся рядом или в types-файле. Принимай props, destructure в body, без inline props typing. Только children — FC<PropsWithChildren>; дополнительные props — named type на основе PropsWithChildren<{ … }>; без props — FC.
• Обычные exports — нижний named block; barrel делает прямой re-export. CSF сохраняет default meta и прямые story exports; configuration exceptions заданы в Biome. Не распространяй их на application code.

Hooks и derived state

Hooks вызываются без условий и ранних выходов перед ними; custom hook нужен связному поведению, а не новому имени над одним вызовом. Derived value вычисляй при render/в VM. Пользовательское действие обрабатывай handler; useEffect оставляй синхронизации с внешней системой с корректным cleanup/dependencies.

useMemo, useCallback, memo нужны измеренной стоимости или конкретному контракту стабильной identity; не добавляй их ко всем значениям/handlers. React Compiler включён в Vite, но не доказывает выигрыш и не заменяет effect correctness. Не удаляй существующую memoization без понимания её consumers. Container/VM/view и state owners — в UI.

Domain literals and magic values

Общее правило ownership и символических значений — Domain values. Backend vocabulary бери из generated paths, не создавай ручную копию enum. Текущий schema.d.ts содержит только types: typed wire literals допустимы, когда generator не предоставляет runtime values.

ProblemDetailsDto.code сейчас string. Не объявляй закрытый frontend error enum и не превращай неизвестный code в известный через cast. Повторяющуюся обработку своди у ответственного owner; errors.

noMagicNumbers в Biome — error; fixtures/tests/stories исключены только из этого правила. Policy получает имя и единицы; подавление допустимо для incidental value с объяснением. Обычный UI-текст не превращай в constant: его owner — i18n. Semantic magic strings и props profile требуют review.

Проверка

npm run typecheck и npm run lint; behavior проверяй по Testing, placement — по FSD.