Add Site Studio themes and Theme Manager
Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview. Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
This commit is contained in:
@@ -0,0 +1,143 @@
|
||||
# Runtime 002 — файловая тема и ширина блоков
|
||||
|
||||
Реализованы этапы 1–3. Версия схемы сайта, страниц и темы — 1. Интерфейс Theme Manager, его endpoints и новый `examples/site-studio` относятся к этапам 4–5 и пока отсутствуют.
|
||||
|
||||
## Загрузка и источник истины
|
||||
|
||||
`site.yaml` содержит `theme: {file: theme.yaml}`; путь относительный, внутри корня сайта. Файл темы обязателен при явной ссылке. Неверные YAML/тип/путь, symlink наружу и inline-настройки дают диагностику с путём; ошибка блокирует build/preview. Если настройка темы вообще отсутствует, используется minimal@1 в памяти, файл не создаётся.
|
||||
|
||||
```yaml
|
||||
schema: 1
|
||||
preset: minimal
|
||||
preset_version: 1
|
||||
overrides:
|
||||
colors:
|
||||
primary: '#4255b9'
|
||||
ui:
|
||||
container:
|
||||
mode: boxed
|
||||
max_width: 1080
|
||||
gutter: {desktop: 36, tablet: 24, mobile: 16}
|
||||
```
|
||||
|
||||
`core/theme.py` предоставляет dataclass `ThemeDocument`, `EffectiveTheme`, `ContainerSettings`, `Gutters`, функции `preset_catalog`, `font_catalog`, `resolve_theme`, `load_theme`, `theme_css`. Ядро не требует Pydantic. Registry содержит вычисленную `theme`; `Site` содержит только ссылку `theme_file`.
|
||||
|
||||
Пресеты minimal/dark/editorial/bold/natural/custom и каталог шрифтов скопированы из `design/assets/theme-studio.js` в `builtin/themes/v1/*.json`. Runtime не читает design и не хранит отдельную палитру в БД/JS. Каталог отдаёт независимые копии; определения опубликованной версии не изменяются. Будущие изменения пресета требуют отдельной версии и поддержки этой версии в resolver.
|
||||
|
||||
Переопределения объединяются глубоко, поэтому изменение mobile gutter сохраняет desktop/tablet. `custom_colors` и явно заданный `gradients.definitions` заменяют соответствующую карту целиком: удалённые определения не возвращаются из defaults. Custom требует полный набор colors/type/ui, включая вложенный container/gutter. Дополнительные цвета и градиенты необязательны.
|
||||
|
||||
## Валидация
|
||||
|
||||
| Поле | Контракт |
|
||||
|---|---|
|
||||
| colors | background/surface/text/muted/primary/secondary/accent/border, HEX #RRGGBB |
|
||||
| type | pair из каталога или custom, heading/body только разрешённые системные стеки |
|
||||
| type.scale / line | числа 0.85–1.3 / 1.3–1.9 |
|
||||
| type.headingWeight | целое 100–900 |
|
||||
| ui.radius / spacing | числа 0–24 px / 0.8–1.4 |
|
||||
| ui.shadow / button | none/soft/medium и solid/outline |
|
||||
| ui.container | объект mode/max_width/gutter; старое число отклоняется |
|
||||
| max_width / gutters | целое 720–1920 / целые 0–96 px |
|
||||
| custom_colors | до 24 HEX; имена `[a-z][a-z0-9_]{1,31}`, без конфликтов с зарезервированными токенами |
|
||||
| gradients | enabled: boolean, до 12 именованных linear definitions |
|
||||
| definition | angle 0–360, 2–5 stops `{at: 0..100, color: HEX}`, позиции строго возрастают |
|
||||
|
||||
Неизвестные ключи, null вместо объекта, boolean вместо числа, строки с CSS/URL/Jinja и нечисловые/бесконечные значения отклоняются. Ошибки используют коды `E_THEME_*`. Проверяются контрасты text/background, text/surface, muted/surface; `W_THEME_CONTRAST` не блокирует публикацию. Включённые градиенты добавляют предупреждение о проверке контраста по всей поверхности.
|
||||
|
||||
## CSS и релиз
|
||||
|
||||
Порядок общего бандла: base.css → стили использованных фрагментов → вычисленные переменные → containers.css. Встроенные компоненты используют семантические переменные; дополнительных CSS из пользовательских данных нет.
|
||||
|
||||
| Токены | CSS |
|
||||
|---|---|
|
||||
| colors.name | `--color-name`; background также `--color-bg` |
|
||||
| custom_colors.hero_ink | `--color-hero-ink`, адресное использование шаблоном |
|
||||
| type | `--font-heading`, `--font-body`, `--type-scale`, `--type-line`, `--heading-weight` |
|
||||
| ui | `--radius`, `--spacing`, `--shadow`, `--button-background`, `--button-text` |
|
||||
| container/gutter | `--container`, `--container-max`, `--gutter-desktop/tablet/mobile`, responsive `--active-gutter` |
|
||||
| gradients.definitions.name | `--gradient-name`; для hero/button/cta также `--hero-gradient`, `--button-gradient`, `--cta-gradient` |
|
||||
|
||||
Градиенты применяются адресно: тёмный Hero, основная solid-кнопка и CTA используют соответствующие роли. При отключении возвращаются однотонные значения, outline-кнопка остаётся прозрачной. Публичные CSS находятся в релизе/iframe, на skin админки не влияют.
|
||||
|
||||
Manifest содержит прежние source_hash/routes/fragments/page_sources и новые `render_hash`, `fingerprint`, `theme: {document, effective_tokens}`. ID строится из времени и общего fingerprint файлов сайта, кода ядра/сборки/парсинга, builtin-ресурсов, пресетов и загруженных фрагментов. При одинаковом ID существующий релиз переиспользуется только при побайтово одинаковом результате; несовпадение даёт `E_RELEASE_COLLISION` и сохраняет историю. Ошибка не переключает current. Rollback переключает готовый релиз и не меняет theme.yaml/контент workspace.
|
||||
|
||||
## Layout блока и конструктор
|
||||
|
||||
```yaml
|
||||
- id: hero_home
|
||||
fragment: hero
|
||||
layout:
|
||||
section_width: full
|
||||
content_width: boxed
|
||||
props:
|
||||
title: Пример
|
||||
```
|
||||
|
||||
Оба поля допускают inherit/boxed/fluid/full. Отсутствующий layout у hero/cta_banner/site_header/site_footer означает full/inherit; у остальных — inherit/inherit. Явный пустой объект или явно заданный inherit наследует глобальную ширину. Неизвестные ключи и режимы дают `E_BLOCK_LAYOUT`; молчаливого исправления нет.
|
||||
|
||||
Boxed ограничивает секцию до `min(available - 2*gutter, max_width)`, fluid убирает max_width, full занимает всю доступную ширину без gutter. Внутренний boxed-контейнер имеет max_width и padding, fluid — только padding, full — без ограничения и padding. Внешняя секция ограничивает внутреннюю. Gutters переключаются на 700 и 1024 px; для слишком узкого вложенного контейнера padding ограничен его доступной шириной.
|
||||
|
||||
Renderer ставит `data-engine-block`, `data-section-width`, `data-content-width` на существующие корни и `data-engine-container` на собственные `.f-container`/`.container`. Область вложенного блока исключается из обработки родителем. Для разделения фона и содержимого собственный шаблон должен иметь внешний корень и внутренний контейнер. Richtext/image/columns builtin получили собственные внутренние контейнеры; общий wrapper вокруг всех фрагментов не добавляется, sticky-header остаётся корнем. Preview markers добавляются отдельно; публикация их не содержит.
|
||||
|
||||
Один парсер применяется к Page, Display, Entry regions, fixed и slots. Снимки передают layout без потери данных. Transform меняет сырой YAML; props edit, duplicate, move, toggle, Save и reopen сохраняют layout. На API-границе `BlockLayoutDTO` объявляет enum в OpenAPI, `BlockValues` ограничивает поля, явный null для anchor/note сохраняет значение очистки. `schema.container` отдаёт глобальные настройки.
|
||||
|
||||
Контролы инспектора перенесены из `design/assets/builder.js:blockWidthControls`: те же названия, варианты, классы и пояснение. Обновление использует существующий HTML → внутренний JSON API → DocumentService; debounce и preview остаются асинхронными. Выбор секции локальный; изменение до Save не создаёт черновик на диске. Выделение и scroll preview сохраняются.
|
||||
|
||||
## Проверка и запуск
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_theme.py' -v
|
||||
PYTHONPATH=src python -m unittest discover -s tests -p 'test_block_layout.py' -v
|
||||
PYTHONPATH=src python scripts/qa_theme_002.py
|
||||
PYTHONPATH=src python scripts/verify_package_001.py --site /path/to/isolated-site
|
||||
```
|
||||
|
||||
Нужна пересборка образа/установка нового пакета. Рабочий SITE_ROOT не переключается автоматически; примеры обновлены только в исходниках. Root examples не коммитятся. Проверки и артефакты — в [отчёте](verification-stages-2-3.md).
|
||||
|
||||
## Этап 4: публичный builtin и отдельный Site Studio
|
||||
|
||||
Источник разметки/CSS — design/examples/site-studio/fragments и assets/site.css. Общие примитивы перенесены в builtin/base.css, правила компонентов — в их style.css. Служебные f-классы сохранены для существующих локальных шаблонов. Штатный сборщик добавляет тему и containers.css после этих правил. Готовый пакет не читает design/.
|
||||
|
||||
Добавлены content/steps (прежний title/items из ai-studio, локальный дубликат удалён) и data/entry_card. `entry_header` дополнен summary/image/image_alt, `form` — title/description. Метки Hero, шапки, записи, заголовок richtext и описание collection_list задаются опциональными props; тексты нового примера не захардкожены в общие шаблоны. Списки произвольной длины, slots, columns/page_header и card_grid.variant:steps сохранены.
|
||||
|
||||
`ref` с `to: '*'` использует collection/slug. Парсер/валидатор проверяют форму; Resolver различает E_REF_FORMAT, E_REF_COLLECTION, E_REF_MISSING, E_REF_UNPUBLISHED. Опубликованная карточка с недоступной целью блокирует build; preview показывает диагностику. Универсальные ссылки в данных коллекций проверяются и без использования в display, включая вложенные group/list/refs. Обычные ref/refs сохраняют slug и прежнюю семантику. Document schema предоставляет дополнительный choices.published_entries; generic datalist включает только эти записи, fixed datalist использует прежний choices.entries. Save/ETag/буфер не изменены.
|
||||
|
||||
Collection теперь поддерживает необязательный `requires: [feature.<имя>]` (schema остаётся 1). Неизвестное требование — E_REQUIRES_UNKNOWN. При выключенной feature записи сохраняются в workspace, не публикуются, не попадают в query или generic choices и не требуют release-полноты. Маршрут такой записи недоступен для generic ref. Без requires поведение прежнее. В новом примере courses/posts связаны с features courses/blog.
|
||||
|
||||
`examples/site-studio/` содержит адаптированные данные/ассеты/пять layouts с seo/assets hooks; штатный build создаёт 13 страниц и два редиректа. Сохранены 8 записей, 4 из которых draft. Намеренно отсутствующая обложка booking диагностируется в preview, не мешает live. Форма выполняет настоящий POST и показывает HTTP 501 без очистки ввода или перехода на thank-you. Нового FormService/доставки нет.
|
||||
|
||||
Отдельный запуск — examples/site-studio/README.md; QA — scripts/qa_site_studio_002.py; результаты — [verification-stage-4.md](verification-stage-4.md). Рабочие SITE_ROOT/data не изменяются.
|
||||
|
||||
|
||||
## Этап 5: Theme Manager, API и мастер первого входа
|
||||
|
||||
Экран `/admin/theme` («Дизайн сайта») и `/admin/setup/theme` используют исходные HTML-композицию, CSS и контролы `design/theme-studio-antirion.html` / `design/assets/theme-studio.{css,js}`. Сохраняется принятый shell админки. Стили исходного экрана и его импортированные button/chip-примитивы ограничены `.theme-content`; публичные CSS остаются в iframe. Палитра темы сайта не меняет skin админки. Нативных browser dialogs и palette-localStorage нет.
|
||||
|
||||
JSON API (внутренние credentials, существующая request-scoped авторизация UI):
|
||||
|
||||
| Метод | `/admin/api/v1` | Результат |
|
||||
|---|---|---|
|
||||
| GET | `/theme` | ThemeSnapshot |
|
||||
| GET | `/theme/presets` | 6 preset definitions, их документы/effective tokens, font catalog |
|
||||
| PATCH | `/theme` | Save: `{document, if_match, revision}` → ThemeSnapshot |
|
||||
| POST | `/theme/validate` | `{document, revision}` → ThemeSnapshot или 422 с diagnostics в error.issues |
|
||||
| POST | `/theme/preview` | `{document, revision, target: sample\|page, page_id?, device: desktop\|phone, viewport_width?: 320..3840}` → immutable Preview |
|
||||
| GET | `/theme/onboarding` | `{status, needs_setup, can_manage}` |
|
||||
| POST | `/theme/onboarding/skip` | skipped |
|
||||
| POST | `/theme/onboarding/restart` | in_progress |
|
||||
|
||||
HTML-адаптер принимает обычные form POST с `csrf` и `payload` (JSON DTO): `/admin/theme/save|validate|preview`; workflow — `/admin/setup/theme/skip|restart`. Он возвращает JSON-проекцию результата внутреннего AdminApi, не обращаясь к сервису/файлам напрямую. Внешние credentials браузеру не выдаются. Вход в экран выполняется обычной навигацией; htmx-переход получает HX-Redirect для корректной загрузки исходных ресурсов.
|
||||
|
||||
ThemeSnapshot: document, etag, effective_tokens, diagnostics, workspace_revision, live_build_id, revision; также path, yaml, css и contrast для UI. workspace_revision — хеш конфигурации сайта и ETag темы; это версия темы в workspace, не счётчик правок всех страниц. `revision` относится к состоянию текущей вкладки. Контракт экспортирован в `specs/001-antirion-admin/openapi.json` штатной командой export-openapi.
|
||||
|
||||
Клиент получает пресеты/шрифты/effective tokens с backend. Он редактирует доступные поля, отправляет полный документ (полный overrides допустим и для обычных пресетов). Второго JS resolver/валидатора/CSS-генератора темы нет. После паузы ввода идут серверная проверка и preview; это не Save. Переключение шага сохраняет iframe и не записывает контент. Desktop/Mobile и выбор реальной страницы создают новый snapshot. Устаревшие ответы отбрасываются по sequence/revision/target/device; ошибочная revision ответа также отклоняется. Неверная тема оставляет последнее корректное превью с явным статусом. YAML/export формирует и проверяет сервер.
|
||||
|
||||
Сохранение ограничено точным `site.yaml.theme.file`; разрешён отдельный относительный YAML внутри root без symlink alias/escape, не site.yaml. Если тема не настроена, используется minimal в памяти, target — theme.yaml. GET/preview не создают тему. Save получает `if_match: absent` при создании. ContentService.update_files под SiteLock перечитывает/проверяет версии и путь, валидирует весь документ, сохраняет историю и атомарно пишет файл. При первом Save также сохраняется ссылка в site.yaml с проверкой его версии. Все версии/валидация проверяются до записи; обычный отказ второго файла восстанавливает первый. Несколько rename не являются общей crash-atomic транзакцией: аварийное завершение процесса между ними может оставить несвязанный theme.yaml, который не применяется до появления ссылки. Настроенная тема сохраняется одним файлом.
|
||||
|
||||
409 возвращает `error.current: ThemeSnapshot`. UI оставляет пользовательские значения и предлагает принять новую основу либо явно загрузить серверную тему. Принятие основы само не пишет файл; повторный Save снова проверяет ETag. 5xx/сеть/401/403 видимы с code/message/request_id. Сбой аудита или workflow после успешной записи возвращает 500 `theme_after_commit` с `error.committed`: UI учитывает новую версию и сообщает проблему. Неожиданные исключения логируются общей границей со стеком и request_id.
|
||||
|
||||
PreviewStore хранит immutable HTML и необходимые ассеты вне canonical workspace. Стенд Hero/Buttons/Cards/Typography перенесён из исходника; его CSS использует core.theme.theme_css через алиасы переменных. Фактическая страница рендерится штатным Renderer с reg.theme overlay. Для стенда ассеты сайта не копируются. viewport_width передаёт только ширину окна редактора для responsive-правил оригинального стенда; числовые границы проверяются API, это не токен темы. Пассивный iframe не разрешает scripts; при настроенных разных origin действуют прежние signature/TTL/auth_epoch, CSP, nonce bridge, immutable assets. Скрипты сайта не исполняются. Текст/контролы админки не получают CSS публичной темы.
|
||||
|
||||
OnboardingService атомарно хранит только `{schema: 1, status}` в SITE_STATE_DIR/theme-onboarding.json под SiteLock. Без state тема в конфигурации или live-релиз означают existing; без обоих — new и redirect с обзора на setup. Текущий single-admin имеет право управления. Skip → skipped, Repeat → in_progress и первый шаг, Save → completed. Skip/Repeat не меняют тему и live; workflow переживает рестарт. Сессия не создаёт персональный мастер для каждого редактора. Повтор доступен на экране дизайна из навигации настроек.
|
||||
|
||||
Визуальная и функциональная приёмка — `scripts/qa_theme_manager_002.py`; серверные отказы/ETag/workflow/release — `tests/test_theme_manager.py`; отчёт — [verification-stage-5.md](verification-stage-5.md). Рабочий SITE_ROOT и live не переключались.
|
||||
Reference in New Issue
Block a user