
Blockstudio 7.1 — перший випуск із новими функціями після переписування v7. Якщо v7 відбудував основу, то версія 7.1 додає компоненти, що перетворюють блоки на щось більше: рівень бази даних, серверні функції, заплановані завдання та CLI. Тепер папка блока може бути повноцінним застосунком.

Ось усе нове.

## Компоненти

Завжди існувала напруга між блоками, які редактори використовують у вставлячі, і блоками, які розробники використовують як будівельні елементи для інших речей. Картка, значок, віджет статистики, поле форми. Їм потрібен повний конвеєр Blockstudio (атрибути, шаблони, ресурси, Tailwind), але їм не місце у вставлячі.

У версії 7.1 з’явилися компоненти, що розв’язують цю проблему. Установіть `"component": true` у своєму block.json, і блок пройде весь конвеєр збирання, але не буде зареєстрований у реєстрі типів блоків WordPress. Він не з’явиться у вставлячі й не потрапить до даних редактора, надісланих до JavaScript, але буде повністю доступний для програмного рендерингу.

```json title="block.json"
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "component": true,
    "attributes": [
      { "id": "title", "type": "text" },
      { "id": "description", "type": "textarea" }
    ]
  }
}
```

Рендерте їх із PHP:

```php
bs_render_block([
  'name' => 'my-theme/card',
  'data' => ['title' => 'My Card', 'description' => 'Card content.'],
]);
```

Або використовуйте новий синтаксис тегів HTML:

```html
<bs:my-theme-card title="My Card" description="Card content." />
```

## Теги блоків

Тепер блоки можна вбудовувати як теги HTML, використовуючи один із двох взаємозамінних синтаксисів:

```html
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
```

Обидва варіанти дають однаковий результат. Обидва працюють із блоками Blockstudio та основними блоками WordPress. У шаблонах блоків вони рендеряться автоматично, без додаткового налаштування. Це означає, що можна складати цілі макети з інших блоків безпосередньо у своєму шаблоні:

```twig title="index.twig"
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-heading level="2">Section Title</bs:core-heading>
  <block name="core/group">
    <block name="core/paragraph">Inside a core group block.</block>
    <bs:mytheme-cta variant="primary" />
  </block>
</div>
```

Обидва синтаксиси можна вільно вкладати один в одного. Блоки Blockstudio проходять повний конвеєр (шаблони, Tailwind, ресурси). Основні блоки рендеряться через WordPress за допомогою тих самих рендерерів, що й для [Сторінок і патернів](https://blockstudio.dev/uk/docs/pages-and-patterns/).

Щоб рендерити на рівні сторінки (вміст допису, області віджетів), увімкніть цю функцію в `blockstudio.json`:

```json
{ "blockTags": { "enabled": true } }
```

Списки дозволених і заборонених блоків керують тим, які блоки можуть рендеритися через теги, використовуючи шаблони з підстановними символами. Атрибути `data-*` і `html-*` передаються кореневому елементу HTML рендереного блока. Власні рендерери можна зареєструвати через фільтр `blockstudio/block_tags/renderers`.

Під капотом парсер тегів — це новий легкий сканер рядків, який повністю замінює DOMDocument. Він обробляє вкладені теги з відстеженням глибини, рекурсивні блоки-контейнери та змішаний синтаксис за один прохід. У тестах він розбирає 1,000 плоских тегів за 2.4ms і 100 рівнів вкладеності за 3.7ms, стабільно випереджаючи DOMDocument і WordPress `WP_HTML_Tag_Processor`. Той самий парсер також обробляє розбір необроблених елементів HTML для [Сторінок і патернів](https://blockstudio.dev/uk/docs/pages-and-patterns/), замінюючи парсер на основі DOMDocument, який раніше обробляв `<p>`, `<div>` та інші елементи HTML.

## Нові типи полів

### Блок

Новий тип поля `block` дає змогу посилатися на інший блок Blockstudio як на атрибут. Поля блока, на який посилаємося, розгортаються безпосередньо, використовуючи `idStructure` і `overrides`, як і власні поля. Різниця в тому, що в шаблоні звернення до значення повертає результат рендерингу блока.

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "card",
        "type": "block",
        "block": "mytheme/card",
        "idStructure": "card_{id}"
      }
    ]
  }
}
```

Якщо `mytheme/card` має поля `heading` і `content`, у блоці-контейнері на бічній панелі з’являться `card_heading` і `card_content`. У шаблоні `{{ a.card }}` виводить рендерену картку. Працює і зі звичайними блоками, і з компонентами.

### Тег HTML

У кожній темі є блоки, для яких рівень заголовка має змінюватися залежно від контексту. H1 на головній сторінці, H2 на внутрішніх. Замість того, щоб щоразу створювати поле вибору із жорстко заданими параметрами, тепер є спеціальний тип поля `html-tag` із вбудованими наборами параметрів.

```json
{
  "id": "tag",
  "type": "html-tag",
  "default": "h2",
  "tags": "heading",
  "exclude": ["h5", "h6"]
}
```

Набори параметрів: `heading` (h1-h6), `text` (заголовки + p, span, div), `structural` (div, section, article, aside, main, header, footer, nav), `all`. Або передайте власний масив. `exclude` вилучає певні теги з будь-якого набору параметрів.

```twig
<{{ a.tag }}>{{ a.title }}</{{ a.tag }}>
```

## База даних

Це ключова частина випуску. Додайте файл `db.php` до будь-якої папки блока, і Blockstudio згенерує п’ять кінцевих точок CRUD REST, перевірить кожен запис відповідно до схеми, автоматично керуватиме сховищем і надасть клієнт JavaScript (`bs.db()`) та PHP API (`Db::get()`). Без файлів міграцій, класів контролерів і реєстрації маршрутів.

```php title="db.php"
return [
    'subscribers' => [
        'storage'    => 'table',
        'capability' => [
            'create' => true,
            'read'   => true,
            'update' => 'edit_posts',
            'delete' => 'manage_options',
        ],
        'fields' => [
            'email' => [
                'type'     => 'string',
                'format'   => 'email',
                'required' => true,
                'validate' => function ($value) {
                    if (str_ends_with($value, '@spam.com')) {
                        return 'This domain is blocked.';
                    }
                    return true;
                },
            ],
            'name' => ['type' => 'string', 'maxLength' => 100],
            'plan' => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
];
```

Лише ця схема створює повністю робочий API із кінцевими точками створення, списку, отримання, оновлення та видалення, кожна з перевіркою вхідних даних.

### Сховище

П’ять типів сховищ для різних сценаріїв використання:

- **`table`**: власна таблиця MySQL, якою керує `dbDelta()`. Додавання полів до схеми додає стовпці під час наступного завантаження сторінки. Типове значення для робочого середовища.
- **`sqlite`**: один файл SQLite у папці `db/` блока. Справжні запити SQL, режим WAL для паралельного читання та повна переносимість. Скопіюйте папку — скопіюєте базу даних.
- **`jsonc`**: один об’єкт JSON у кожному рядку звичайного файла. Зручний для читання, контролю версій і git.
- **`meta`**: масив JSON у метаданих допису WordPress, прив’язаний до певного допису.
- **`post_type`**: кожен запис стає дописом WordPress у власному типі дописів. Поля зберігаються як окремі записи метаданих допису, їх можна повністю запитувати за допомогою `WP_Query`.

### Клієнти

На боці JavaScript `bs.db()` надає повноцінний CRUD-клієнт:

```js
const db = bs.db('my-theme/block', 'subscribers');
const record = await db.create({ email: 'a@b.com', plan: 'pro' });
const pros = await db.list({ plan: 'pro' });
await db.update(record.id, { plan: 'free' });
await db.delete(record.id);
```

Разом із ним постачаються три допоміжні утиліти:

- **`bs.cache`**: кеш запитів у пам’яті з `get`, `set`, `invalidate` і `clear`. Спільний для всіх викликів запитів і мутацій.
- **`bs.query(key, fn, options)`**: додає кешування, дедуплікацію запитів і налаштовувані `staleTime` до будь-якої асинхронної функції. Кілька викликів з однаковим ключем, поки запит виконується, повертають той самий проміс.
- **`bs.mutate(options)`**: обробляє оптимістичні мутації з автоматичним відкатом. Передайте реактивний об’єкт стану, дію (`create`, `update`, `delete`) і оптимістичні дані. UI оновлюється миттєво. Якщо виклик сервера завершується помилкою, стан повертається до знімка до мутації.

Разом ці засоби охоплюють повний цикл читання й запису: `bs.query` для кешованого читання, `bs.mutate` для оптимістичного запису, `bs.cache` для ручного керування.

На боці PHP клас `Db` надає ті самі операції:

```php
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');
$db->create(['email' => 'a@b.com', 'plan' => 'pro']);
$db->list(['plan' => 'pro']);
```

### Перевірка даних

Помилки перевірки повертаються як масиви помилок для кожного поля за зразком формату `fieldErrors` у Zod. Для одного поля можуть не пройти кілька правил, а структура спрощує зіставлення помилок із полями форми на фронтенді:

```json
{
  "data": {
    "status": 400,
    "errors": {
      "email": ["Must be a valid email address.", "This domain is blocked."],
      "plan": ["Must be one of: free, pro."]
    }
  }
}
```

Власні функції зворотного виклику `validate` виконуються на сервері, щоб обробляти випадки, які не охоплюють вбудовані правила: блокування доменів, перевірку кількох полів і зовнішні запити.

### Дані користувачів

Для даних окремих користувачів, як-от списків справ, вибраного чи чернеток, задайте `userScoped` значення `true`, а Blockstudio подбає про решту. Він додає стовпець `user_id`, автоматично встановлює його під час створення та фільтрує кожен запит за поточним користувачем. Оновлення й видалення перевіряють власника. Без поля `user_id` вручну, без хуку `before_create` і без фільтрації в RPC. Усього один рядок конфігурації. Якщо використовується сховище `post_type`, `userScoped` зіставляється з `post_author` замість окремого стовпця.

```php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [ /* ... */ ],
];
```

### Опитування в реальному часі

Укажіть `'realtime' => true` у схемі, і клієнт автоматично опитуватиме сервер на наявність змін. Коли на сервері щось змінюється, оновлюється сховище Interactivity API, а UI рендериться повторно без жодних змін JavaScript з вашого боку. Налаштуйте параметри через `'realtime' => ['key' => 'todos', 'interval' => 5000]`, щоб задати власні ключі стану й інтервали. Опитування використовує порівняння хешів, щоб зменшити обсяг запитів, і призупиняється, коли вкладка браузера прихована.

### Безпека, хуки та переносимість

Публічні кінцеві точки захищені автоматично доданим заголовком CSRF `X-BS-Token`. Використовуйте `'open'`, коли справді потрібен доступ без автентифікації, наприклад для вхідних вебхуків.

Хуки життєвого циклу спрацьовують перед кожною операцією запису та після неї. Визначайте їх у `db.php` або глобально через дії WordPress.

Поля можуть визначати ключ `component` для створення форм на основі схеми через `bs_db_form()`.

Зі сховищем SQLite або JSONC увесь застосунок розміщується в одній папці: код, логіка, контроль доступу й дані. Скопіюйте її, щоб розгорнути застосунок.

## RPC

Іноді CRUD недостатньо. Потрібна власна серверна логіка: перемикання стану завдання, надсилання сповіщення, обчислення статистики. Для цього призначений `rpc.php`. Визначте функцію PHP, викличте її з фронтенду через `bs.fn()`, а Blockstudio подбає про кінцеву точку REST, автентифікацію, захист CSRF і серіалізацію JSON. Цей підхід натхненний [tRPC](https://trpc.io): процедури визначаються на сервері, а з клієнта викликаються за назвою.

```php title="rpc.php"
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        return ['success' => true];
    },
];
```

```js
const result = await bs.fn('subscribe', { email: 'user@example.com' });
```

Вбудовані скрипти (`script-inline.js`) автоматично визначають назву блока з атрибута `data-block` у своєму тегу script, тож передавати її вручну не потрібно. Модульні скрипти отримують її третім аргументом.

Параметри контролю доступу включають `public` (із CSRF), `'open'` (без захисту), рядки можливостей або масиви. Також підтримуються керування методом HTTP для кожної функції, хуки життєвого циклу та виклики між блоками з JS і PHP.

## Cron

Фонові завдання визначаються у файлі `cron.php`. Задайте розклад і функцію зворотного виклику, і Blockstudio зареєструє їх у WordPress Cron під час ініціалізації. Після деактивації плагіна всі завдання коректно скасовуються.

```php title="cron.php"
return [
    'cleanup' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db = Db::get('my-theme/app', 'logs');
            // delete old entries
        },
    ],
    'sync' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // pull from external API
        },
    ],
];
```

Підтримуються всі вбудовані розклади WordPress, а також власні інтервали через фільтр `cron_schedules`.

## CLI

Нова команда `wp bs` охоплює весь набір функцій Blockstudio: блоки, базу даних, RPC, cron, налаштування, компіляцію Tailwind, компіляцію SCSS, власні поля та керування ресурсами.

```bash
wp bs blocks list --components
wp bs db schemas
wp bs db create my-theme/app subs --email=a@b.com
wp bs db list my-theme/app subs --plan=pro --format=json
wp bs rpc call my-theme/app subscribe --email=a@b.com
wp bs cron run my-theme/app cleanup
wp bs tailwind compile --file=template.html
wp bs scss compile --file=style.scss
wp bs fields list
wp bs assets list --type=global
wp bs settings get tailwind/enabled
```

Усі команди підтримують `--format=json` для сценаріїв автоматизації.

## Покращення повторювача

### textMinimized для полів-об’єктів

Згорнуті рядки повторювача тепер коректно обробляють значення полів-об’єктів. Раніше, якщо для поля посилання вказати `textMinimized`, відображалося `[object Object]`. Тепер Blockstudio автоматично зчитує потрібну властивість залежно від типу поля: `title` для посилань, `value` для кольорів і градієнтів, `icon` для піктограм. Також можна вказати властивість `key`, щоб зчитати будь-яку потрібну вкладену властивість.

```json
{
  "type": "repeater",
  "textMinimized": { "id": "href", "fallback": "Add a link" },
  "attributes": [{ "id": "href", "type": "link" }]
}
```

### RichText і MediaPlaceholder

Обидва компоненти шаблонів тепер працюють усередині полів повторювача; за допомогою квадратних дужок можна вибрати потрібний рядок. У кожному рядку повторювача доступні заголовки й абзаци з вбудованим редагуванням, а також області завантаження медіафайлів.

```twig
{% for item in a.items %}
  <div class="card">
    <MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
    <RichText tag="h2" attribute="items[{{ loop.index0 }}].heading" />
    <RichText tag="p" attribute="items[{{ loop.index0 }}].content" />
  </div>
{% endfor %}
```

## Умови власних полів з idStructure

Якщо власне поле використовує `idStructure`, ідентифікатори умов у його визначенні тепер автоматично змінюються відповідно до розгорнутих назв. Якщо в групі полів розміру шрифту є умова для `enable`, а ви розгортаєте її за допомогою `idStructure: "title_font_{id}"`, тепер ця умова правильно посилається на `title_font_enable` замість початкового `enable`.

Також підтримуються умови на рівні посилання. Додайте `conditions` до посилання на власне поле, щоб застосувати їх одразу до всіх розгорнутих полів.

## Динамічні аргументи заповнення

Тепер аргументи заповнення можуть посилатися на атрибути інших блоків за допомогою синтаксису `{attributes.*}`. Коли значення атрибута змінюється, поле вибору автоматично повторно завантажує параметри. Об’єднуйте поля вибору в ланцюжок: одне для вибору типу допису, інше — для завантаження дописів цього типу.

```json
{
  "id": "selected_post",
  "type": "select",
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "{attributes.post_type}"
    }
  }
}
```

Змініть `post_type` на "page", і друге поле вибору завантажить сторінки. Змініть на "post" — і воно завантажить дописи. Працює з будь-яким типом заповнення й будь-яким атрибутом.

## Composer

Blockstudio тепер працює, якщо його завантажено з будь-якого місця всередині `wp-content/`, а не лише з каталогу плагінів. URL ресурсів визначаються через константу `BLOCKSTUDIO_URL` замість `plugins_url()`, тож встановлення в комплекті з темою працює одразу:

```php title="functions.php"
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/vendor/blockstudio/blockstudio/blockstudio.php';
```

Залежності `composer.json`, потрібні під час виконання, упорядковано. Пакети з областю дії (TailwindPHP, ScssPhp, Minify), які вже входять до `lib/`, більше не перелічуються як залежності під час виконання. Залишилися лише `php >= 8.2` і `plugin-update-checker`.

Усі три способи встановлення (архів плагіна, плагін через Composer, тема з вбудованим Composer) дають однаковий результат: повну активацію WordPress, реєстрацію блоків і рендеринг на фронтенді.

Інструкції з налаштування дивіться в документації [Composer](https://blockstudio.dev/uk/docs/dev/composer/).

## Профайлер продуктивності

Додайте `?blockstudio-perf` до будь-якої сторінки URL, і внизу з’явиться панель налагодження з часом рендерингу кожного блока, деталізацією за фазами та частотою влучань у кеш. Дані про час також надсилаються в заголовках Server-Timing і доступні на вкладці Network у DevTools браузера.

```json title="blockstudio.json"
{ "dev": { "perf": true } }
```

Увімкніть цю функцію в налаштуваннях, щоб постійно профілювати завантаження сторінок. Вона видима лише авторизованим користувачам із можливістю `edit_posts`.

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

## Виправлення помилок

- **Попередження про застарілість PHP 8.4**: виправлено попередження про застарілість `strpos()` і `str_replace()`, спричинені передаванням `null` до `add_submenu_page()`.

## Інше

- **Поля коду SCSS**: поля коду підтримують `language: "scss"`. Значення компілюються через ScssPhp і в редакторі, і на фронтенді.
- **Стандартні блоки WordPress**: каталоги Blockstudio можуть містити вивід `@wordpress/create-block` поряд із блоками Blockstudio. Вони реєструються автоматично, без окремого коду плагіна.

---

Якщо хочете побачити повноцінний підхід на практиці, у посібнику [Повноцінні блоки](https://blockstudio.dev/uk/guides/full-stack-blocks/) показано, як із нуля створити застосунок зі списком справ для кожного користувача та форму підписки на публічну розсилку.
