sync

OLD_parts/12-components.md

@@ -0,0 +1,88 @@
+---
+title: Компоненты
+---
+
+# Компоненты
+
+## Правила создания и работы с компонентами.
+
+### 1. Структура компонента
+Ассистент при создании/рефакторинге компонента должен **строго** придерживаться следующей структуры файлов и папок: 
+
+```
+component-name/
+  index.ts
+  component-name.tsx
+  styles/
+    component-name.module.css 
+  locales/
+    ru.json
+    en.json
+  types/
+    component-name.interface.ts
+    component-name.type.ts
+    component-name.enum.ts
+  schemas/
+    schema-name.schema.ts
+  utils/
+    util-name.util.ts
+  hooks/
+    use-hook-name.hook.ts
+  stores/
+    store-name.store.ts
+  ui/
+    ... # вложенные компоненты для component-name
+```
+
+Пояснения к структуре компонента:
+**Обязательные файлы** обязательны для всех компонентов, даже если они пустые.
+  - component-name/: Папка компонента корень для всего компонента.
+  - index.ts: экспортирует главный компонент, интерфейс и всё, что может быть переиспользовано.
+  - component-name.tsx: главный компонент.
+  - styles/component-name.module.css: стили компонента.
+  - locales/ru.json: локализация на русском языке.
+  - locales/en.json: локализация на английском языке.
+  - types/component-name.interface.ts: интерфейс пропсов компонента.
+**Не обязательные файлы** добавляются только при необходимости
+  - types/component-name.type.ts: типы компонента.
+  - types/component-name.enum.ts: enum компонента.
+  - schemas/schema-name.schema.ts: схемы валидации.
+  - utils/util-name.util.ts: утилиты компонента.
+  - hooks/use-hook-name.hook.ts: хуки компонента.
+  - stores/store-name.store.ts: хранилища состояния компонента.
+  - ui/: Папка для вложенных компонентов.
+
+### Требования к компоненту
+- Использовать `memo()` для всех компонентов, которые принимают пропсы.
+- Использовать `useMemo` для всех вычислений, которые передаются в пропсы других компонентов.
+- Использовать `useCallback` для всех функций/методов, которые передаются в пропсы других компонентов.
+
+### Требования к вложенным компонентам
+- Вложенный компонент — это полноценный компонент, который обязан полностью соблюдать все правила, описанные для компонентов (структура, именование, документация, типизация, стилизация и т.д.).
+- Все вложенные компоненты размещаются только в папке ui/ основного компонента.
+
+**Пояснение**
+Нет необходимости повторять структуру и требования — вложенный компонент подчиняется тем же правилам, что и любой другой компонент, только располагается в папке ui/ родительского компонента.
+
+### Требования к локализации
+- Все добавленные локализации обязательно подключать в экземпляр `app/i18n` (чтобы новые namespace были доступны для i18next).
+
+---
+
+### Чек-лист для создания нового компонента
+- [ ] Главный компонент размещён в корне и назван по правилу PascalCase.
+- [ ] Создан файл стилей в папке `styles/`, имя в kebab-case, используется BEM.
+- [ ] Все классы применяются через `className={styles['component-name']}`.
+- [ ] Создана папка `locales/` с файлами `ru.json` и `en.json`.
+- [ ] Создан файл интерфейса пропсов в папке `types/`, даже если интерфейс пустой.
+- [ ] Создан файл `index.ts` с экспортом главного компонента и интерфейса.
+- [ ] Внутренние компоненты (если есть) размещены в папке `ui/`.
+- [ ] Все важные части кода документированы по TSDoc (см. раздел 16).
+- [ ] Остальные файлы (schemas, дополнительные типы, enum) добавлены только при необходимости.
+- [ ] Именование файлов и папок соответствует правилам (см. выше).
+- [ ] Нет неиспользуемого или невалидного кода.
+- [ ] Для компонентов с пропсами используется `React.memo`.
+- [ ] Для вычислений, передаваемых в пропсы, используется `useMemo`.
+- [ ] Для функций, передаваемых в пропсы, используется `useCallback`.
+- [ ] Все тексты вынесены в локализационные файлы и используются через i18n.
+- [ ] Новые namespace подключены в экземпляр i18n.