frontend/docs/CONVENTIONS.md

Conventions

Must

• Использовать Biome: npm run lint; табы и двойные кавычки определяет biome.json.
• Для type-only импортов использовать import type; не использовать enum и namespace.
• UI-строки хранить в src/shared/i18n/locales/ru.ts и получать через useTranslation().
• Zod-схемы не содержат пользовательских строк: использовать validationMessage(key) из src/shared/i18n/zod.ts.
• Публичный импорт слайса идёт через его index.ts.
• Тесты лежат рядом с исходником как *.test.tsx.
• Зависимости используют exact versions; не добавлять semver ranges.
• Полный локальный gate: npm run verify. Pre-commit запускает staged formatting и FSD dependency checks; commit message должен следовать Conventional Commits.

React component style

Biome-enforced guardrails:

• Named React components объявлять как const-valued components, а не function declarations.
• Не использовать default exports.
• Export statements держать после declarations тела module.

Storybook CSF-файлы *.stories.tsx используют штатный export default meta и прямые export const для stories: статический indexer должен видеть их метаданные и названия. Biome разрешает эти два исключения только для stories; .storybook/main.ts и preview.tsx разрешают только обязательный default export. Synthetic fixtures и Storybook descriptions являются данными/документацией истории; продуктовые UI-строки по-прежнему принадлежат i18n.

Mandatory review conventions:

• React components типизировать через FC: const Component: FC<Props> = (props) => { ... }; если props нет — const Component: FC = () => { ... }.
• Props описывать named type рядом с component либо в Component.types.ts, если type переиспользуется или file становится крупным.
• Не использовать inline props typing в component parameters.
• Для components только с children использовать FC<PropsWithChildren> без отдельного props alias. Если кроме children есть другие props, использовать named props type на основе PropsWithChildren<{ ... }>.
• Не destructure props в component parameters; принимать props и destructure внутри component body.
• Обычный module export surface сводить к одному нижнему named export block, когда это выражается читаемо без потери public API.
• Чистые barrel files должны использовать прямой re-export без промежуточного import: export { Component } from "./Component";.

File roles

• Component.tsx - контейнер или публичный компонент; для data-driven pages вызывает page VM hook и выбирает top-level state view.
• Component.vm.ts - hook с данными, действиями, state selection и derived presentation data.
• Component.view.tsx - чистое представление: получает props, рендерит JSX и не вызывает data/auth/router/navigation/VM hooks.
• Component.types.ts - props и локальные типы.
• Component.module.css - локальные стили.

Самостоятельный top-level state или именуемый section обычно выносится в соседний *.view.tsx, когда у него есть отдельная responsibility, reuse либо change cadence или он скрывает principal component. Небольшой tightly-coupled renderer остаётся рядом с parent. Предпочтительный flat pattern — components/AccountOperationsPageLoaded.view.tsx без отдельной директории, barrel, test и stylesheet для каждого компонента.