marketplaces/docs/platform/05-widget-system.md

05. Widget System

Назначение

Widget System предоставляет переиспользуемые UI-блоки для сборки страниц из конфигурации без дублирования логики и без tenant-specific кода.

Поведение системы

• Widget Engine выбирает компонент по widget.type и version.
• Виджет получает входные props и resolved data.
• В случае отсутствия регистрации используется fallback unknown-widget.

Обязательные свойства JSON

• widget.id
• widget.type
• widget.version

Опциональные свойства JSON

• widget.props
• widget.dataSource
• widget.featureFlag
• widget.visible
• widget.events

Строгие правила

• Виджеты не вызывают API напрямую.
• Виджеты не управляют page-level margin/padding/layout.
• Виджет может управлять только внутренней разметкой и презентацией.
• Любой новый widget.type должен быть зарегистрирован в реестре.

Пример JSON виджета

{
  "id": "widget-categories-main",
  "type": "categories",
  "version": "1.0.0",
  "props": {
    "title": "Категории",
    "emptyMessage": "Категории скоро появятся"
  },
  "dataSource": {
    "name": "categories",
    "params": {
      "rootOnly": true,
      "limit": 12
    }
  }
}

Ответственность Frontend

• Разрешать тип виджета через registry/manifest.
• Передавать только подготовленные данные в компонент виджета.
• Блокировать прямые API-вызовы из слоя UI-виджета.

Ответственность Backend

• Поставлять данные в форматах, ожидаемых data resolvers.
• Обеспечивать консистентность ID и ссылок между сущностями.
• Не внедрять frontend-специфичные инструкции в props виджетов.