React-обертки в экосистеме Atomico представляют собой инструмент интеграции кастомных элементов Web Components с существующей React-логикой без дублирования бизнес-слоя. Основной принцип: компоненты Atomico остаются нативными кастомными элементами, а React лишь предоставляет тонкий прокси-слой для корректной передачи свойств, событий и слотов.
Кастомные элементы Atomico принимают свойства, объявленные через
композицию хука useProps, useState или через
статическое описание. Однако React по умолчанию не умеет корректно
передавать нестроковые значения в нативные элементы. Для обхода
используется маппинг: обертка ловит переданные пропсы и устанавливает их
непосредственно на DOM-элемент.
Atomico генерирует пользовательские события через
EventTarget.dispatchEvent. В React события на DOM-элементах
работают иначе. Поэтому React-обертка регистрирует слушателей событий на
реальном DOM-узле, а затем вызывает соответствующие колбэки из пропсов,
синхронизируя модели реактивности.
Слотинг в Atomico работает так же, как в Web Components: через
<slot> и slot="name". React корректно
рендерит вложенные элементы, однако именованные слоты требуют установки
атрибута slot на вложенный JSX-узел. Обертка лишь следит за
тем, чтобы React-дерево не нарушало структуру.
При генерации React-обертки Atomico обеспечивает типизацию пропсов из TypeScript-определений самого компонента. Это позволяет использовать строгую типовую сигнализацию внутри React-кода без явного дублирования интерфейсов.
События описываются через CustomEvent<T>, где
T задаёт тип полезной нагрузки. React-слой маппит такие
события на пропсы вида onEventName(payload), сохраняет
типизацию и снижает шанс логических ошибок при передаче данных вверх по
дереву.
customElements.define.React-обёртка решает три проблемы: корректное обновление пропсов,
консистентная подписка на события и выравнивание JSX-структуры для
слотинга. Без неё React часто неправильно сериализует значения
(object, function, boolean) и
некорректно создаёт слушателей событий.
DOM-элемент создаётся один раз, а React-обновления приводят лишь к установке изменённых свойств. Это предотвращает ненужные операции detach/attach и удешевляет рендер.
Использование ref позволяет React-коду напрямую
управлять узлом кастомного элемента, что облегчает интеграцию с
существующей логикой и сторонними библиотеками.
Стили внутри Atomico могут быть инкапсулированы через Shadow DOM, что
препятствует прямой стилизации из React-окружения. Для интеграции
используется CSS Custom Properties, shadowParts или
параметризация через пропсы.
При серверном рендеринге кастомные элементы ведут себя как неизвестные теги. Контент будет отображён, но интерактивность включится лишь после инициализации на клиенте. Обёртка не снимает это ограничение, но делает миграцию менее болезненной.
React-порталы можно использовать, однако именованные слоты требуют
явного указания slot, что требует аккуратного
проектирования UI-дерева.
В больших проектах Web Components позволяют инкапсулировать функциональные блоки (таблицы, редакторы, визуализаторы) и использовать их через React-слой. Atomico делает такую инкапсуляцию компактной, а обёртки обеспечивают совместимость без переписывания UI-стека.
Компоненты на Atomico могут быть распространены как независимая библиотека UI-элементов, а React-обертки — как адаптерный пакет. Такой подход снижает стоимость поддержки при использовании в нескольких фреймворках одновременно.
Web Components служат основой для интеграции независимых фрагментов интерфейса. React-обертки позволяют микрофронтендам на React использовать атомико-компоненты как часть собственного дерева.
React-слой становится тонкой прослойкой без логики. Оно облегчает тестирование, повторное использование и переносимость.
Интерфейсы Atomico выступают источником API-контракта. React-обёртка не определяет новых свойств, а отражает существующий контракт.
Переименование и адаптация CustomEvent в
onSomething(payload) делает API привычным для
React-разработчиков и снижает когнитивную нагрузку.
Инкапсуляция — Atomico скрывает детали реализации под Web Components.
Совместимость — React-обертки дают возможность использовать Atomico в крупной экосистеме React без ломки архитектуры.
Типобезопасность — TypeScript-контракты остаются едиными независимо от UI-движка.
Миграция — проекты React могут постепенно переходить на Web Components или миксовать их без переписывания всего дерева.
Межфреймворковость — после создания Web Components на Atomico адаптеры можно написать для Vue, Svelte или Angular, что позволяет библиотекам жить дольше и шире.