Smart-компоненты Docara

Smart-компонент — переносимый UI-артефакт с проверяемым manifest, представлениями, шаблоном и assets. Все компоненты проходят один путь:

Markdown -> typed Document IR -> renderer registry
-> SmartComponentGateway -> LayoutComposer -> PageBuilder

Docara не выбирает renderer по имени компонента. Provider registry определяет владельца namespace, затем Gateway проверяет manifest, view, preset, props, template и assets. Неизвестное или небезопасное значение останавливает сборку.

Встроенные владельцы

ui.alert, ui.button, docara.brand, docara.navigation, docara.toc и docara.preferences разрешаются тем же Gateway. Deprecated aliases docara.header и docara.outline хранятся в artifact metadata, а не в PHP ветвлении.

Компонент проекта

Объявите один namespace в docara.json:

{"smart":{"namespace":"project"}}

Корень фиксирован: smart/. Config и Markdown не могут выбрать PHP-класс, callback или путь к template.

smart/project.notice/
├── manifest.json
├── view/default.json
├── template/default.php
└── assets/notice.css

Manifest использует tracked SIMAI Framework Smart artifact v1. Минимальный пример уже есть после docara init. В Markdown он вызывается так:

:::project.notice
{"title":"Компонент проекта","text":"Собран общим конвейером."}
:::

Добавление нового project.* артефакта не требует правок src/. Duplicate ID, чужой namespace, symlink, traversal, неизвестный view/preset/prop, template или asset завершают сборку ошибкой.

После docara init страница /ru/project-demos/ показывает два полезных локальных примера: project.install-builder только формирует и копирует Composer-команду, а project.product-configurator считает демонстрационный итог в браузере. Их совместимые authoring aliases — project.install_builder и project.product_configurator; канонические ABI IDs используют дефисы. Оба примера обходятся без fetch, backend, заказа, оплаты или выполнения команды.

project.install-builder использует принятые ui.input и ui.checkbox. project.product-configurator показывает заполненный ui.dropdown; варианты в его slot options — только принятые дочерние ui.list-item с type=text. Все четыре Framework-компонента проходят тот же registry, Gateway и renderer, что и остальные Smart-компоненты. Их manifest, view, preset, template, assets и hydration contract проверяются по exact lock до render.

Поддержка ui.list-item здесь намеренно узкая: это текстовый option для ui.dropdown. Icons, avatars, tags и самостоятельное использование ui.list-item не входят в контракт. Нельзя заменять options массивом items, raw-разметкой или локальной копией Framework-компонента.

View выбирается одинаково для любого provider: явно указанный view имеет приоритет; иначе named preset выбирает зарегистрированный view; если не задано ни то ни другое, используется default. Это данные артефакта, поэтому новый компонент или вариант не требует условия по component ID в engine.

Контекст шаблона и assets

Docara передаёт portable PHP-шаблону целевой array ABI SIMAI Framework 5 Smart v1 и не вводит собственный template dialect.

Например, безопасный шаблон читает <?= htmlspecialchars((string) ($props['title'] ?? ''), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') ?>. Объект $view и SmartTemplateContext относятся только к ограниченному legacy host-adapter старых package-owned шаблонов и не являются portable ABI.

Переносимый артефакт использует нейтральный Framework-owned контракт sf.smart_artifact_abi версии 1.0.0 и compatibility id sf-smart-artifact-abi-v1. Историческое имя sf5.smart.artifact.v1 обозначает только совместимый layout файлов, а не второй формат. Exact pin b3cdff87563ff78e7eddf044048a4b298fc69036 передаёт выбранные view, preset, slot и hydration одинаково под SIMAI Framework 5 и Docara. Не создавайте отдельный Docara template dialect.

Команда docara schema smart --json возвращает authoritative byte-exact Framework-owned smart.manifest.schema.json; неизменённый manifest из scaffold проходит её без преобразования. Дополнительные требования Docara проверяет отдельная policy docara.smart_admission.v1, а не альтернативная публичная схема. Manifest из docara scaffold smart ... --dry-run проходит именно эту схему. Команда inspect smart ... --json одинаково сообщает neutral contract identity для ui.*, docara.* и project namespace. Host-bound преобразование старых package manifests видно отдельно в provider_adapter, а форма template — в template_abi. Ни одно из этих полей не создаёт новый публичный dialect.

Project template считается trusted developer source. Его путь выводится только из фиксированного provider root и manifest/view записи. CSS/JavaScript также объявляются в manifest, проверяются по физическим файлам и публикуются через общий asset plan.

Интерфейсные подписи сайта приходят из content/<locale>/lang.json. Текст страниц остаётся в Markdown; manifest и project config не являются источником публичной документационной прозы.

Проверка

docara doctor
docara inspect smart project.notice --json
docara validate smart project.notice
php vendor/bin/phpunit tests/Unit/ProjectLocalSmartRuntimeTest.php
php vendor/bin/phpunit tests/Unit/SmartProviderRegistryTest.php
cd docs/site
php ../../docara build production
php ../../docara verify-static build_production

Для нового артефакта используйте hash-bound workflow docara scaffold smart project.name --dry-run, затем docara scaffold --apply=<plan_id>. Полный путь описан в Developer и AI SDK.

Full и --page используют один PageBuilder. После изменения структуры routes нужна full build; для содержимого существующей страницы доступен single-page rebuild.