
Blockstudio 7.2 rozširuje framework dvoma smermi naraz.

Prvým je **prehľadnosť a pracovný postup** v rámci jedného projektu: nový
prehľad pre správcu, prehliadač databázy, prehliadač registra správcu a prelúdiá
SCSS pre zdieľané nastavenie Sass.

Druhým je **ekosystém okolo Blockstudio**: register CLI na distribúciu
blokov (ako shadcn pre WordPress) a rozšírenie PHPStan, ktoré prináša typovú
bezpečnosť v štýle TypeScript do šablón, značiek blokov, `db.php`, `rpc.php`,
`cron.php` a súvisiacich súborov schém.

Oba smery sledujú rovnaký cieľ: uľahčiť pochopenie väčších projektov Blockstudio,
ich rozširovanie a zdieľanie.

## Prostredie správcu

Dve novinky uľahčujú orientáciu vo väčšom projekte v prostredí wp-admin.

### Prehľad pre správcu

Blockstudio teraz obsahuje obrazovku správcu v časti **Nástroje > Blockstudio**.
Na jednom mieste si môžete prezrieť, čo systém zaregistroval zo súborového systému.

Prehľad obsahuje samostatné karty pre:

- Bloky
- Rozšírenia
- Polia
- Stránky
- Schémy

Okrem tohto prehľadu teraz administračná oblasť obsahuje aj samostatnú sekciu
**Databases**. Zobrazuje všetky zaregistrované schémy `Blockstudio\Db` a umožňuje
prehliadať skutočné záznamy priamo vo wp-admin.

Namiesto vytvárania vlastnej mriežky panelov obrazovka používa natívne tabuľky WordPress
DataViews. Vďaka tomu je UI v súlade s wp-admin a praktické aj vtedy, keď
projekt obsahuje desiatky alebo stovky registrácií.

Pri malej inštalácii si môžete stav za behu udržať v hlave. Pri väčšej
kódovej základni to prestáva fungovať. Začnete si klásť otázky ako:

- Ktoré bloky sú práve zaregistrované?
- Ktoré rozšírenia sa zameriavajú na `core/*` a ktoré na jednotlivé bloky?
- Ktoré stránky sú synchronizované a ku ktorým typom príspevkov patria?
- Ktoré opakovane použiteľné polia v tomto projekte existujú?
- Ktoré schémy sú zaregistrované a aké úložisko používajú?

Doteraz ste odpovede hľadali kombináciou prezerania priečinkov, otvárania súborov JSON
a sledovania vykonávania PHP. Prehľad to mení na skutočné rozhranie v administrácii.

Každá karta je navrhnutá tak, aby odpovedala na iné otázky:

- **Bloky** zobrazujú zaregistrované typy blokov, režim vykresľovania, verziu API a
  počet atribútov
- **Rozšírenia** zobrazujú, na ktoré bloky sa zameriavajú, spolu s prioritou a
  podrobnosťami vykresľovania
- **Polia** poskytujú rýchly prehľad opakovane použiteľných definícií vlastných polí
- **Stránky** zobrazujú synchronizované stránky založené na súboroch spolu s typom príspevku, stavom, šablónovým
  nástrojom a stavom synchronizácie
- **Schémy** zobrazujú zaregistrované schémy úložiska spolu s úložiskom, počtom polí
  a rozsahom oprávnení

Prehliadač databáz je zámerne oddelený od úvodných údajov prehľadu. Namiesto serializácie každého riadka pri načítaní stránky vopred lokalizuje iba dostupné schémy a záznamy načíta na požiadanie po otvorení karty databázy. Vďaka tomu zostáva rozhranie administrácie užitočné aj vtedy, keď sa za `db.php` nachádzajú väčšie súbory údajov.

Táto prvá verzia je zámerne zameraná na registrácie založené na schémach.
Nie je to stránka nastavení. Je to stránka na kontrolu.

Ak túto funkciu vôbec nechcete, úplne ju vypnite:

```php
add_filter('blockstudio/admin/enabled', '__return_false');
```

### Prehliadač registra v administrácii

Vedľa prehľadu sa nachádza druhá karta: **Register**. Je to prehliadač
vzdialených registrov blokov nakonfigurovaných vo vašom súbore `blocks.json` v téme a umožňuje
importovať bloky priamo z administrácie WordPress bez úprav súboru CLI.

```json title="blocks.json"
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

Prehliadač načíta každý nakonfigurovaný register, zobrazí všetky dostupné bloky a
ukáže, či sú už nainštalované lokálne alebo pripravené na import. Každý riadok
obsahuje tlačidlo Importovať, ktoré stiahne súbory bloku do nakonfigurovaného
priečinka témy. Pri už nainštalovaných blokoch sa namiesto toho zobrazí tlačidlo Znova importovať.

Podporované sú aj autentifikované registre, a to prostredníctvom objektového formátu s `headers`,
vrátane interpolácie `${ENV_VAR}`, takže tokeny sa nikdy nedostanú do systému správy verzií.

Vďaka tomu sa prehliadanie a používanie registrov stáva plnohodnotnou súčasťou práce v administrácii, nie
iba postupom cez CLI.

## Register CLI

Druhou časťou práce s registrami je samostatný CLI: `blockstudio/registry`.

Je to nástroj v štýle shadcn pre bloky WordPress. Bez balíka npm a bez kroku zostavenia.
Spustíte príkaz, zdrojový kód bloku sa skopíruje do vášho projektu a
získate nad ním úplnú kontrolu.

```bash
npx blockstudio init
npx blockstudio add ui/tabs
```

CLI funguje s akýmkoľvek typom bloku: blokmi Blockstudio, výstupom `@wordpress/create-block`,
bežnými blokmi PHP. Registru nezáleží na tom, čo sa nachádza v priečinku.
Načíta zoznam súborov z `registry.json` a skopíruje presne tieto súbory.

Autori blokov zverejnia `registry.json` na ľubovoľnom URL (GitHub surový obsah, S3, vlastný server),
ktorý uvádza dostupné bloky spolu s metadátami, závislosťami a zoznamami súborov. Používatelia pridajú URL do svojho `blocks.json` a sťahujú bloky podľa názvu.

CLI podporuje:

- **Riešenie závislostí**: bloky môžu deklarovať závislosti od iných blokov,
  ktoré sa vyriešia automaticky s detekciou cyklov
- **Riešenie konfliktov medzi viacerými registrami**: ak sa rovnaký názov bloku nachádza vo
  viacerých registroch, CLI vás vyzve, aby ste si jeden vybrali
- **Autentifikované registre**: tokeny typu bearer, základná autentifikácia a vlastné hlavičky
  s interpoláciou premenných prostredia
- **Interaktívne TUI**: vytvorené pomocou Ink, so spinnermi, výzvami na výber a
  indikátormi priebehu
- **Neinteraktívny režim**: príznak `--yes` a automatický náhradný režim pre CI a presmerovaný vstup/výstup
- **Vyhľadávanie a zoznam**: prehliadanie registrov z príkazového riadka

Balík obsahuje 130 testov pokrývajúcich schémy, riešenie závislostí,
načítavanie HTTP, zapisovanie súborov, priebeh každého príkazu a interaktívne UI vytvorené pomocou Ink.

Úplná dokumentácia je na [blockstudio.dev/registry](https://blockstudio.dev/sk/registry/).

## Rozšírenie PHPStan

Ďalším veľkým prírastkom je `blockstudio/phpstan`: rozšírenie PHPStan, ktoré
používateľom Blockstudio poskytuje typovú bezpečnosť, akú očakávajú vývojári TypeScript.

```bash
composer require --dev blockstudio/phpstan
```

Rozšírenie pri analýze načíta skutočné schémy vášho projektu a odovzdá
výsledné typy späť do PHPStan. Teraz pokrýva šablóny PHP, Twig,
Blade, značky blokov, typované databázové záznamy, cesty nastavení, názvy hákov a
validáciu schém naprieč `block.json`, `field.json`, rozšírením JSON,
`page.json`, `db.php`, `rpc.php`, `cron.php` a `blockstudio.json`.

### Typovo bezpečné šablóny blokov

Prístupy k poliam v `$a` sa overujú podľa súvisiacej `block.json`:

```php title="blockstudio/hero/index.php"
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
```

### Typovo bezpečné databázové záznamy

`Db::get()` vracia typovanú inštanciu podľa vašej schémy `db.php`. Tvar záznamu
sa vytvára zo skutočných polí:

```php title="db.php"
return [
  'storage' => 'table',
  'fields' => [
    'email' => ['type' => 'string', 'required' => true],
    'name'  => ['type' => 'string'],
  ],
];
```

```php
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
```

### Validácia schém

Neplatné súbory schém sa zachytia počas analýzy: `block.json`, `field.json`,
rozšírenie JSON, `page.json`, `db.php`, `rpc.php`, `cron.php` a
`blockstudio.json`. Chýbajúce názvy, nesprávne typy polí, chybne formátované definície,
zastarané skrátené booleovské hodnoty (`"tailwind": true` namiesto vnoreného
objektu) sa všetky nahlásia spolu s presným riadkom v zdrojovom súbore.

### Validácia ciest nastavení

Volania `Settings::get()` sa overujú podľa známej schémy nastavení:

```php
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
```

### Validácia názvov hákov

To isté platí pre názvy filtrov a akčných hákov:

```php
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
```

Rozšírenie obsahuje aj definície typu stub pre celé verejné API Blockstudio: `Db`,
`Settings`, `Field_Registry`, `Build` a globálne pomocné funkcie. Získate automatické dopĺňanie
kódu a kontrolu typov pre všetky rozhrania API Blockstudio bez potreby mať zdrojový kód doplnku na svojom vývojovom počítači.

## Uľahčenia pri tvorbe

Vydanie dopĺňajú dve menšie uľahčenia pri tvorbe.

### Globálne predpony SCSS

Blockstudio už podporoval kompiláciu SCSS, no mal jeden nepríjemný
problém: zdieľané nastavenie Sass.

Ak ste chceli používať spoločnú množinu premenných, funkcií alebo mixinov,
museli ste ich importovať v každom súbore SCSS. To sa rýchlo opakuje, najmä
pri väčších dizajnových systémoch alebo súboroch nástrojov Sass, ako je Bootstrap.

Verzia 7.2 pridáva predponový hák presne na tento účel:

```php
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

V kombinácii s existujúcim filtrom `blockstudio/assets/process/scss/import_paths` raz definujete zdieľané prostredie Sass
a bude dostupné v každom kompilovanom súbore.

Šablóna so štýlmi bloku sa tak môže sústrediť na skutočné štýly, ktoré potrebuje:

```scss title="style.scss"
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}
```

Žiadne opakované importy v každom súbore s prostriedkami bloku. Nejde o špeciálny režim „podpory Bootstrap“.
Je to všeobecný hák na zdieľanie Sass v rámci projektu, či už pochádzajú z Bootstrap alebo z vašej vlastnej internej súpravy nástrojov.

### Definície blokov PHP s natívnou syntaxou API

Verzia 7.2 pridáva aj voliteľnú syntax s natívnou podporou PHP pre rozhrania API blokov s plným zásobníkom.
Polia zostávajú predvolenou a plne podporovanou možnosťou. Nič ich nenahradilo. Ak však
uprednostňujete pomenované argumenty, výčtové typy a atribúty pred vnorenými konfiguračnými poľami,
teraz môžete zvoliť tento štýl.

Pre `rpc.php` vráťte objekt s metódami s atribútmi:

```php title="rpc.php"
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};
```

Pre `cron.php` funguje rovnaký prístup aj s `#[Cron]`:

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};
```

A pre `db.php` je teraz k dispozícii jednoduchá vrstva na tvorbu:

```php title="db.php"
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);
```

Pri väčších kódových základniach je to lepšie vyvážené riešenie. Keď chcete, zachováte si jednoduchosť formátu polí a pri rozrastajúcom sa bloku môžete prejsť na prehľadnejšie prostredie PHP, keď už obsahuje viac než niekoľko polí alebo koncových bodov.

## Prečo sú tieto veci súčasťou jedného vydania

Prehľad v administrácii, prehliadač registrov, register CLI a rozšírenie PHPStan
otvárajú rovnakú otázku: ako udržať projekt Blockstudio zrozumiteľný aj počas jeho rastu?

Nástroje v administrácii na ňu odpovedajú na úrovni projektu: poskytujú prehľad o tom, čo je
zaregistrované, umožňujú načítavať bloky z registrov a znižujú potrebu hádať.

CLI na ňu odpovedá na úrovni ekosystému: umožňuje zdieľať bloky medzi
projektmi a tímami bez ich zoskupovania do balíkov npm a zápasenia so systémami zostavovania.

Rozšírenie PHPStan na ňu odpovedá na úrovni kódu: zachytí nesprávne prístupy k poliam,
preklepy v schémach a nefunkčné spätné volania hákov ešte pred spustením programu.

Všeobecný smer verzie 7.2 je teda jasný: menej hádania, menej opakovania,
lepší prehľad a teraz aj skutočná typová bezpečnosť.

## Opravy chýb

- **Pole Classes**: vlastné názvy tried zadané používateľom sa po opustení poľa potichu zahodili, pretože validátor prijímal iba triedy z preddefinovaného zoznamu Tailwind/nastavení. Teraz prijíma ľubovoľný neprázdny reťazec.
- **Pole Attributes**: po odstránení dvojice atribútov zostali v uložených údajoch položky `null`. Nahradili sme lodash `unset()` (ktoré nastavuje prvky poľa na null) za `splice()` (ktoré ich odstraňuje).
- **Minifikátor CSS**: minifikátor TailwindPHP odstránil medzery okolo `+` vnútri `calc()` a `clamp()`, čím vytvoril neplatné CSS, napríklad `calc(1rem+0.5vw)`. Problém sa opravil v nadradenom projekte TailwindPHP v1.3.1 pomocou prechodu po znakoch, ktorý zohľadňuje hĺbku a odstraňuje medzery okolo kombinátorov selektorov iba pri hĺbke zátvoriek 0.
- **Náhľad v nástroji Block Inserter**: `$isPreview` sa v náhľade nástroja Block Inserter vždy zobrazovalo ako `false`, pretože vyrovnávacia pamäť vykresľovania nezahŕňala režim vykresľovania do svojho hashovacieho kľúča. Vykreslenia v editore a náhľade teraz používajú samostatné položky vyrovnávacej pamäte.
- **Vnorená šablóna InnerBlocks**: komponent `<InnerBlocks template="..."/>` zahodil tretí prvok (potomkov) z n-tíc šablóny, ako je `['core/group', {}, [['core/paragraph']]]`, a výsledkom boli prázdne bloky kontajnera. Teraz zachováva vnorených potomkov.
