sync

DRAFT/architecture/components.md

@@ -0,0 +1,65 @@
+# Компоненты SLM
+
+> Пояснение нормативной модели компонентов SLM.
+
+Компонент является строительным элементом интерфейса, а не самостоятельной архитектурной единицей.
+
+## Связанные правила
+
+- [`SLM-COMPONENT-R009`](../rules/registry.md#slm-component-r009)
+- [`SLM-LAYER-A002`](../rules/registry.md#slm-layer-a002)
+- [`SLM-MODULE-A004`](../rules/registry.md#slm-module-a004)
+- [`SLM-DEPENDENCY-A005`](../rules/registry.md#slm-dependency-a005)
+- [`SLM-MODULE-R011`](../rules/registry.md#slm-module-r011)
+- [`SLM-LIFECYCLE-R013`](../rules/registry.md#slm-lifecycle-r013)
+
+## Файловая форма
+
+Файловую форму компонента определяет стайлгайд. Компонент может быть одним файлом фреймворка или каталогом со вспомогательными файлами.
+
+```text
+landing/
+└── ui/
+    └── hero.tsx
+```
+
+```text
+landing/
+└── ui/
+    └── hero/
+        ├── hero.tsx
+        ├── styles/
+        │   └── hero.module.css
+        └── types/
+            └── hero-props.type.ts
+```
+
+Наличие каталога, типов, стилей или локального `index.ts` не превращает компонент в модуль.
+
+## Реализация
+
+Компонент может отображать входные данные, вызывать переданные обработчики, условно строить интерфейс и хранить локальное состояние представления.
+
+SLM не вводит отдельного запрета на импорты, выполняемые кодом компонента. Каждый такой импорт считается зависимостью родительского модуля и должен соблюдать направление слоёв, публичные фасеты и запрет циклов.
+
+Доступ к данным, состояние, контекст или код жизненного цикла внутри компонента сами по себе не создают новую архитектурную границу. Их источники, зависимости и область жизни определяет родительский модуль.
+
+Провайдер может технически реализовывать контекст и жизненный цикл фреймворка, но владельцем состояния и ресурсов остаётся родительский модуль.
+
+Файл в `app` может технически быть компонентом React или Vue. Архитектурно он является точкой входа фреймворка, а не компонентом SLM.
+
+## Компонент и модуль
+
+| Признак | Компонент | Модуль |
+|---|---|---|
+| Самостоятельная ответственность | Нет | Да |
+| Собственный публичный API | Нет | Да |
+| Собственная граница зависимостей | Нет | Да |
+| Вспомогательные файлы | Может иметь | Может иметь |
+| Сегменты и вложенные модули | Нет | Может иметь |
+
+Модуль может состоять всего из одного корневого компонента. Различие определяется владением, а не количеством файлов.
+
+## Когда нужен вложенный модуль
+
+Если часть интерфейса получает самостоятельную ответственность, публичный API, собственную границу зависимостей, область жизни или внутреннюю модульную декомпозицию, она является модулем. При локальном использовании такой модуль может размещаться как вложенный.