docs: отказаться от FC и interface в пропсах компонентов

- переписана типизация: type вместо interface, убран FC - введена система типов: Params + RootAttrs + Props - добавлены обоснования: почему type, почему не FC, почему types/ - обновлены примеры в components, page-level, templates, documentation - убраны упоминания FC из таблиц index.md и README - перегенерированы RULES.md
2026-04-02 16:01:29 +03:00
parent 6ccc4a0d06
commit fbac3e1a55
10 changed files with 91 additions and 189 deletions
--- a/generated/ru/RULES.md
+++ b/generated/ru/RULES.md
@@ -36,7 +36,7 @@
 | Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
 | Именование | Как называть файлы, переменные, компоненты, хуки? |
 | Документирование | Как писать JSDoc: что документировать, а что нет? |
-| Типизация | Как типизировать: type vs interface, any/unknown, FC? |
+| Типизация | Как типизировать: type vs interface, any/unknown? |

 ### Прикладные разделы

@@ -46,7 +46,7 @@
 |--------|-------------------|
 | Настройка VS Code | Как настроить редактор для проекта? |
 | Структура проекта | Как организованы папки и файлы по FSD? |
-| Компоненты | Как устроен компонент: файлы, пропсы, clsx, FC? |
+| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
 | Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
 | Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
 | Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
@@ -616,7 +616,7 @@ export const buildCategoryTree = (categories: Category[]): CategoryTree[] => { .
 *  - обёртки контента страниц с ограничением ширины
 *  - центрирования блоков в лейауте
 */
-export const Container: FC<ContainerProps> = (props) => { ... }
+export const Container = (props: ContainerProps) => { ... }
 ```

 **Плохо**
@@ -627,7 +627,7 @@ export const Container: FC<ContainerProps> = (props) => { ... }
 */

 // Плохо: нет описания вообще.
-export const Container: FC<ContainerProps> = (props) => { ... }
+export const Container = (props: ContainerProps) => { ... }
 ```

 ### Типы, интерфейсы, enum
@@ -845,7 +845,7 @@ container/
 ├── styles/
 │   └── container.module.css
 ├── types/
-│   └── container.interface.ts
+│   └── container.type.ts
 ├── container.tsx
 └── index.ts
 ```
@@ -853,13 +853,17 @@ container/
 ### Именования

 - Имя корневого css класса всегда `.root`
- Интерфейс именуется `{ComponentName}Props`.
+- Тип пропсов именуется `{ComponentName}Props`.
+- Тип пользовательских параметров именуется `{ComponentName}Params`.

 ### Типизация

- Компонент типизируется через `FC<Props>`.
- Интерфейс пропсов наследует HTML-атрибуты своего корневого элемента.
- `children` отдельно не объявляется — приходит из `HTMLAttributes`.
+Структура типов компонента показана в [примере](#пример). Ниже — обоснования ключевых решений.
+
+- **`type` вместо `interface`** — гибче для пропсов: поддерживает union, intersection, mapped types. Declaration merging пропсам не нужно.
+- **Без `FC`** — неявно добавляет `children`, усложняет дженерики, не даёт преимуществ перед аннотацией параметра.
+- **Типы в `types/`, а не в `.tsx`** — предотвращает циклические зависимости (компонент импортирует хук, хук импортирует тип из компонента) и разделяет ответственность: `.tsx` для рендера, `.type.ts` для данных.
+- **Без возвращаемого типа** — TypeScript выводит из JSX. Осознанное исключение из [базового правила](/basics/typing).

 ### Реализация

@@ -870,7 +874,7 @@ container/

 ### Пример

-`container/types/container.interface.ts`
+`container/types/container.type.ts`

 ```ts
 import type { HTMLAttributes } from 'react'
@@ -878,7 +882,12 @@ import type { HTMLAttributes } from 'react'
 /**
 * Параметры компонента Container.
 */
-export interface ContainerProps extends HTMLAttributes<HTMLDivElement> {}
+export type ContainerParams = {}
+
+/** HTML-атрибуты корневого элемента. */
+type RootAttrs = HTMLAttributes<HTMLDivElement>
+
+export type ContainerProps = RootAttrs & ContainerParams
 ```

 `container/styles/container.module.css`
@@ -894,9 +903,8 @@ export interface ContainerProps extends HTMLAttributes<HTMLDivElement> {}
 `container/container.tsx`

 ```tsx
-import type { FC } from 'react'
 import cl from 'clsx'
-import type { ContainerProps } from './types/container.interface'
+import type { ContainerProps } from './types/container.type'
 import styles from './styles/container.module.css'

 /**
@@ -906,7 +914,7 @@ import styles from './styles/container.module.css'
 *  - обёртки контента страниц с ограничением ширины
 *  - центрирования блоков в лейауте
 */
-export const Container: FC<ContainerProps> = (props) => {
+export const Container = (props: ContainerProps) => {
  const { children, className, ...htmlAttr } = props

  return (
@@ -924,100 +932,25 @@ export { Container } from './container'
 ```

 <!-- /applied/page-level -->
-## Страницы (App Router)
+## Файлы роутинга

-Специальные файлы Next.js App Router, которые фреймворк использует по соглашению: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`, `template.tsx`.
+Правила для специальных файлов App Router (`page.tsx`, `layout.tsx`, `error.tsx`, `not-found.tsx` и др.) — чем наш подход отличается от дефолтного.

-### Общие правила
+### Организация

- Экспорт через `export default function` — конвенция Next.js.
- Типизация через `PropsWithChildren` или явный интерфейс.
- Каждая страница (`page.tsx`) должна содержать `metadata` с `title` и `description`.
- Минимум логики — page-level компоненты делегируют работу экранам, виджетам и фичам.
- Стили в page-level компонентах не используются — стилизация внутри вызываемых компонентов.
+- `page.tsx` — тонкий файл: только `metadata` и рендер экрана. Логика, стили и зависимости живут в экране, не в `page.tsx`.
+- `error.tsx` и `not-found.tsx` делегируют разметку экранам по тому же принципу.
+- `layout.tsx` — точка подключения провайдеров и глобальных стилей. Вёрстка layout-обёрток выносится в слой `layouts/`.
+- Стили в файлах роутинга не используются — стилизация только внутри вызываемых компонентов.

-### layout.tsx
+### Реализация

-Корневой layout — точка подключения провайдеров, глобальных стилей и метаданных.
+- Каждый `page.tsx` экспортирует `metadata` с `title` — он подставляется в шаблон корневого layout (`%s | App`).
+- Корневой `layout.tsx` задаёт `metadata` с `title.template`, `description`, `metadataBase` и OpenGraph-настройками.

-```tsx
-import type { PropsWithChildren } from 'react'
-import type { Metadata } from 'next'
-import { Providers } from './providers'
-import './styles/index.css'
+### Примеры

-export const metadata: Metadata = {
-  title: {
-    default: 'App',
-    template: '%s | App',
-  },
-  description: 'Описание приложения',
-  metadataBase: new URL('https://example.com'),
-  openGraph: {
-    type: 'website',
-    locale: 'ru_RU',
-    siteName: 'App',
-    images: [
-      {
-        url: '/og-image.png',
-        width: 1200,
-        height: 630,
-        alt: 'App',
-      },
-    ],
-  },
-  twitter: {
-    card: 'summary_large_image',
-  },
-}
-
-export default function RootLayout({ children }: PropsWithChildren) {
-  return (
-    <html lang="ru" suppressHydrationWarning>
-      <body>
-        <Providers>
-          {children}
-        </Providers>
-      </body>
-    </html>
-  )
-}
-```
-
-Вложенный layout — для секции с общей обёрткой (sidebar, header):
-
-```tsx
-import type { PropsWithChildren } from 'react'
-import { DashboardLayout } from '@/shared/ui/dashboard-layout'
-
-export default function Layout({ children }: PropsWithChildren) {
-  return (
-    <DashboardLayout>
-      {children}
-    </DashboardLayout>
-  )
-}
-```
-
-### page.tsx
-
-Тонкий файл — только импорт и рендер экрана. Логика, стили и зависимости размещаются в экране, не в `page.tsx`.
-
-```tsx
-import type { Metadata } from 'next'
-import { HomeScreen } from '@/screens/home'
-
-export const metadata: Metadata = {
-  title: 'Главная',
-  description: 'Главная страница приложения',
-}
-
-export default function HomePage() {
-  return <HomeScreen />
-}
-```
-
-С параметрами маршрута:
+`src/app/profile/[id]/page.tsx`

 ```tsx
 import type { Metadata } from 'next'
@@ -1028,7 +961,7 @@ export const metadata: Metadata = {
  description: 'Страница профиля пользователя',
 }

-interface ProfilePageProps {
+type ProfilePageProps = {
  params: Promise<{ id: string }>
 }

@@ -1039,70 +972,25 @@ export default async function ProfilePage({ params }: ProfilePageProps) {
 }
 ```

-Каждая страница должна содержать `metadata` с `title` — он подставится в шаблон из корневого layout: `Профиль | App`.
-
-### loading.tsx
-
-Состояние загрузки. Показывается пока загружается контент страницы.
-
-```tsx
-export default function Loading() {
-  return <div>Загрузка...</div>
-}
-```
-
-### error.tsx
-
-Обработка ошибок. Обязательно `'use client'` — error boundary работает только на клиенте. Разметку выносим в экран.
+`src/app/error.tsx`

 ```tsx
 'use client'

-import type { FC } from 'react'
 import { ErrorScreen } from '@/screens/error'

-interface ErrorPageProps {
+type ErrorPageProps = {
  error: Error & { digest?: string }
  reset: () => void
 }

-const ErrorPage: FC<ErrorPageProps> = ({ error, reset }) => {
+const ErrorPage = ({ error, reset }: ErrorPageProps) => {
  return <ErrorScreen error={error} reset={reset} />
 }

 export default ErrorPage
 ```

-### not-found.tsx
-
-Страница 404. Показывается когда маршрут не найден. Разметку выносим в экран.
-
-```tsx
-import type { Metadata } from 'next'
-import { NotFoundScreen } from '@/screens/not-found'
-
-export const metadata: Metadata = {
-  title: 'Страница не найдена',
-  description: 'Запрашиваемая страница не существует',
-}
-
-export default function NotFound() {
-  return <NotFoundScreen />
-}
-```
-
-### template.tsx
-
-Аналог layout, но пересоздаётся при каждой навигации (не сохраняет состояние). Используется редко — для анимаций переходов между страницами.
-
-```tsx
-import type { PropsWithChildren } from 'react'
-
-export default function Template({ children }: PropsWithChildren) {
-  return <div>{children}</div>
-}
-```
-
 <!-- /applied/templates-generation -->
 <!-- @formatter:off -->
 ::: v-pre
@@ -1122,7 +1010,7 @@ export default function Template({ children }: PropsWithChildren) {
 │       ├── styles/
 │       │   └── {{name.kebabCase}}.module.css
 │       ├── types/
-│       │   └── {{name.kebabCase}}.interface.ts
+│       │   └── {{name.kebabCase}}.type.ts
 │       ├── {{name.kebabCase}}.tsx
 │       └── index.ts
 └── store/                      # шаблон Zustand стора
@@ -1188,26 +1076,30 @@ export { {{name.pascalCase}} } from './{{name.kebabCase}}'
 ```

 ```ts
-// .templates/component/types/{{name.kebabCase}}.interface.ts
+// .templates/component/types/{{name.kebabCase}}.type.ts
 import type { HTMLAttributes } from 'react'

 /**
 * Параметры {{name.pascalCase}}.
 */
-export interface {{name.pascalCase}}Props extends HTMLAttributes<HTMLDivElement> {}
+export type {{name.pascalCase}}Params = {}
+
+/** HTML-атрибуты корневого элемента. */
+type RootAttrs = HTMLAttributes<HTMLDivElement>
+
+export type {{name.pascalCase}}Props = RootAttrs & {{name.pascalCase}}Params
 ```

 ```tsx
 // .templates/component/{{name.kebabCase}}.tsx
-import type { FC } from 'react'
 import cl from 'clsx'
-import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.interface'
+import type { {{name.pascalCase}}Props } from './types/{{name.kebabCase}}.type'
 import styles from './styles/{{name.kebabCase}}.module.css'

 /**
 * {{name.pascalCase}}.
 */
-export const {{name.pascalCase}}: FC<{{name.pascalCase}}Props> = (props) => {
+export const {{name.pascalCase}} = (props: {{name.pascalCase}}Props) => {
  const { children, className, ...htmlAttr } = props

  return (