
# Полотно

Полотно показує всі сторінки під керуванням Blockstudio у вигляді зменшеного огляду, схожого на Figma. Кожна сторінка відображається як інтерактивна монтажна область в iframe в одному горизонтальному рядку. Переміщуйте полотно трекпадом, масштабуйте жестом зведення пальців або прокручуванням із Ctrl.

## Активація

Полотно доступне як прихована сторінка адміністрування. Перейдіть за адресою:

```
/wp-admin/admin.php?page=blockstudio-canvas
```

Сторінка доступна лише тоді, коли `dev.canvas.enabled` має значення `true`, а поточний користувач має дозвіл `edit_posts`.

## Налаштування

Увімкніть полотно та налаштуйте його роботу у файлі `blockstudio.json` вашої теми:

```json title="blockstudio.json"
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
```

| Властивість | Тип | За замовчуванням | Опис |
|----------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Увімкнути функцію полотна. |
| `adminBar` | `boolean` | `true` | Показувати панель адміністрування WordPress в iframe монтажної області. Установіть `false` для чистішого попереднього перегляду. |

Обидва налаштування також доступні як фільтри:

```php
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');
```

## Подання

Перемикайте подання за допомогою спадного меню у верхньому правому куті.

- **Сторінки**: усі сторінки під керуванням Blockstudio у вигляді повноширинних монтажних областей в одному рядку.
- **Блоки**: усі зареєстровані блоки Blockstudio у вигляді сітки, кожен із початковими значеннями атрибутів.

## Загальнодоступний інвентар і документ API

`Canvas` надає версійований контракт PHP, незалежний від споживача, для інструментів, яким потрібен той самий зареєстрований вміст без повторної реалізації логіки виявлення чи рендерингу Blockstudio:

```php
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);
```

Поточна версія доступна як `Canvas::SCHEMA_VERSION`. Результати інвентаризації містять:

- `inventory`: нормалізовані `pages`, `blocks`, `patterns`, `templates`, `parts` і приклади загальнодоступної сім’ї `ui`
- `order`: стабільний порядок відображення між типами
- `sources`: точні вибрані шляхи до джерел із походженням кожного запису; `source` запису сторінки — це стабільний ідентифікатор джерела, а `path` — фізичний шлях до шаблону рендерингу
- `warnings` і `errors`: структуровані проблеми замість згенерованого виводу
- `deleted`: запитані ідентифікатори, яких більше не існує
- `selection`: нормалізований вибір і вказівка, чи було його націлено

`Canvas::documents()` додає повний документ рендерингу для кожного вибраного запису.
Кожен документ містить основний вміст, зібраний HTML, залежності та назви блоків, а також точні CSS, JavaScript, модулі, ініціалізацію інтерактивності, глобальні змінні UI у складі пакета та вивід Tailwind. У документах сторінок використовується семантична обгортка вмісту `<main>`; викликачі можуть перевизначити або вимкнути її через спільні параметри документа Render.
Кожна вибрана сторінка рендериться у власному відновленому контексті фронтенду WordPress, тож умовні перевірки запиту, фільтри класів body, шорткоди, макети, перенаправлення та зворотні виклики `wp_enqueue_scripts` працюють у контексті цієї сторінки, а не адміністративного запиту чи запиту REST, що ініціював отримання результату Canvas. Класи body, передані викликачем, об’єднуються з контекстними класами сторінки, а реєстри підключень фронтенду ізольовано між документами. Canvas знаходить ці зворотні виклики життєвого циклу за їхніми публічними назвами функцій WordPress, тому той самий контекст зберігається, коли Blockstudio завантажується через Composer або переміщений простір імен застосунку.

### Точна семантика вибору

Вибір працює строго:

- Якщо ключі розпізнаних типів відсутні, завантажуються всі типи.
- `true`, `null` або `"*"` завантажує всі записи відповідного типу.
- Рядок або список завантажує лише точні ідентифікатори, назви, слаги, шляхи чи шляхи до джерел.
- Порожній рядок/список або `false` не завантажує записів цього типу.
- Щойно присутній ключ будь-якого типу, відсутні типи не виявляються, не синхронізуються, не рендеряться й не компілюються.

Завдяки цьому запити лише для змінених елементів безпечні для великих проєктів. Наявні блоки й сторінки знаходяться через канонічні реєстри. Якщо в запиті фронтенду завантажено лише збережену проєкцію сторінки, Canvas виконує пошук джерел лише для читання й об’єднує відповідні ідентифікатори записів і постійні посилання, не синхронізуючи вміст. Таке саме об’єднання ідентифікаторів відбувається, якщо логічне джерело виявлення спершу заповнює реєстр, пов’язаний із джерелом, тож під час контекстного рендерингу сторінки використовується відповідний керований запис WordPress. Нова структура активного сеансу виявляється лише навколо зміненого каталогу, а вибрані джерела шаблонів редактора шаблонів і патернів компілюються лише після вибору.

Кінцева точка оновлення REST дотримується того самого правила для наявних параметрів запиту `blocks` і `pages`. Наприклад, `?blocks=theme/hero` повертає цей блок без сторінок; для змішаної відповіді використовуйте обидва параметри. Виклик кінцевої точки без жодного з них зберігає повну застарілу відповідь.

## Режим реального часу

Режим реального часу використовує Server-Sent Events (SSE), щоб виявляти зміни файлів і оновлювати полотно. Коли ви редагуєте шаблон блоку, шаблон сторінки або таблицю стилів, відповідні монтажні області автоматично оновлюються приблизно за секунду.

Увімкніть або вимкніть режим реального часу через спадне меню. Коли він активний, з’являється зелений індикатор, що пульсує. Налаштування зберігається між сеансами в localStorage.

Режим реального часу відстежує зміни файлів `.php`, `.json`, `.css`, `.scss`, `.js`, `.twig` і `.html` у каталогах блоків і сторінок. Відомі зміни оновлюють лише зареєстрований для них блок або сторінку. Для нового блоку чи сторінки виконується один прохід виявлення структури в межах відповідного каталогу, тож створення вмісту під час активного сеансу й далі працює без повторного сканування не пов’язаних із ним джерел.

## Режим фокусування

Клацніть мітку будь-якої монтажної області, щоб перейти в режим фокусування. Вибрана область заповнить вікно на всю ширину, і її можна буде прокручувати вертикально. Натисніть Escape або кнопку закриття, щоб повернутися до огляду.

## Керування

| Дія | Введення |
|--------|-------|
| Переміщення полотна | Прокручування / перетягування двома пальцями на трекпаді |
| Масштабування | Ctrl+прокручування або зведення пальців |
| Умістити в область перегляду | Спадне меню |
| Масштаб до 100% | Спадне меню |
| Фокусування монтажної області | Клацніть її мітку |
| Вихід із фокусування | Escape / кнопка закриття |

## Безпека

Скрипт полотна й дані сторінок завантажуються лише за виконання всіх умов:

- Налаштування `dev.canvas.enabled` — `true`.
- Поточний користувач має можливість `edit_posts`.

Публічні відвідувачі ніколи не бачать скрипт Canvas або метадані сторінки.
