
Blockstudio 7.5 täiustab Blockstudio failikeskset töövoogu: kohandatud väljatüübid, failipõhised saidiredaktori mallid, plokisaared, Storh andmebaasi salvestus, loogilised avastusallikad, kombineeritavad plokisildid ning kiiremad juurutus- ja käitusteed.

Korduvkasutatavad kohandatud väljad võimaldavad projektidel olemasolevate väljade rühma korra määratleda ja seda `type: "custom/{name}"` abil uuesti kasutada. Kohandatud väljatüübid lahendavad teistsuguse probleemi. Need võimaldavad teemal või pluginal registreerida uue nimeruumiga väljatüübi, pakkuda sellele oma redaktorijuhiku ning salvestada väärtuse tavapäraste Blockstudio andmetena.

Lühidalt:

- **Loogilise avastamise allikad**: käituskeskkonnad saavad pakkuda koondatud loogilist teemainventari, sealhulgas päritolu ja vahemälu identiteeti, samal ajal kui Blockstudio haldab avastamist, sõsarüksuste lahendamist, loodud varasid, Canvast ja Tailwind käitumist.
- **PHP väljatüüpide register**: teemad ja pluginad saavad registreerida nimeruumiga väljatüüpe, näiteks `acme/dimensions` koos `bs_register_field_type()` või filtriga `blockstudio/field_types`.
- **Redaktori juhtelementide register**: kohandatud redaktori skriptid saavad kutsuda `window.blockstudio.registerFieldType()` ja kuvada tavalises Blockstudio välja UI sobiva juhtelemendi React.
- **Struktureeritud väärtused**: kohandatud väljad saavad salvestada stringe, arve, tõeväärtusi, massiive või objekte, teisendamata objektiväärtusi valikuväljade normaliseerimise kaudu.
- **Salvestuse tugi**: post meta ja suvanditel põhinevad kohandatud väljad saavad määrata oma väärtuse tüübi ja REST skeemi, sealhulgas objekti- ja massiiviväärtused.
- **Natiivne integratsioon**: kohandatud väljatüübid toimivad rühmades, vahekaartidel, kordajates, korduvkasutatavates kohandatud väljades, mallides ja laienduste malliteedes.
- **Site Editori mallid**: teemad saavad määrata `wp_template` ja `wp_template_part` allikad failidest `template.json`, `part.json` ja Blockstudio.
- **Plokisaared**: plokid saavad esmalt kuvada vahemällu sobiva kesta ning seejärel lehe laadimise järel päringu jaoks vajalikud osad laadida või pakipäringuga hankida.
- **Storh andmebaasisalvestus**: `bs.db` saab kasutada üleslaadimiste kaustas indekseeritud failipõhist kirjesalvestit, säilitades avalikud täisarvulised ID-d ning võimaldades migreerimist JSONC-ist Storh-i läbi WP-CLI.
- **Parseri ja bsui täiustused**: vastendatud rikasteksti lõigud vajavad vähem kohandatud parseri sidumisloogikat, `InnerBlocks` saab kasutada tokeniseeritud `allowedBlocks`-i, pesastatud `bs_render_block()` väljund vastab redaktori eelvaadetes kasutajaliidese renderdusele ning `bsui/button` saab ikoonid ja hõlpsamini kasutatavad stiilimisvõimalused.
- **Kombineeritavad plokisildid**: eesliitesildid saavad lahenduda teise eesliite kaudu (`<theme-ui-input>` väärtuseks `bsui/input`) ning eesliite- ja aliassildid kuvatakse plokimalli väljundis, mitte ainult lehe sisus.
- **Hosti jaoks ohutud ehitusvahemälud**: käitusaja ja redaktori vahemälude vaikeasukoht on nüüd väljaspool üleslaadimisi; asukohti saab seadistada ja vananenud kirjeid kärbitakse, et pikaajalistesse projektidesse vahemälufaile ei koguneks.
- **Järk-järguline lehtede kooskõlastamine**: juurutustööriistad saavad kooskõlastada failipõhiste lehtede täieliku inventari, jätta muutmata postitused vahele, teatada täpselt tehtud muudatustest ja salvestada pärast aktiveerimist kinnitatud allika identiteedi.
- **Kiirem soe renderdus**: kehtivad käitusaja vahemälud laaditakse enne avastamist, samaaegsed külmad päringud avaldavad ühe atomaarse tulemuse ning Tailwind hoiab saidi suurusele vastavat vahemälu taaskasutatava kompilaatori olekuga.
- **Turvaline pakkrenderdus**: eksportijad saavad lähtestada päringupõhise renderdusoleku dokumentide vahel ilma avastamist uuesti loomata ning koguda plokkide renderdamise ajal allikasõltuvusi.

## Uued funktsioonid

Versioon 7.5 toob avastamise, mallide ja salvestuse valdkonda hulga uusi võimalusi.

### Loogilise avastamise allikad

Blockstudio avastab failid tavaliselt füüsilistest teemakaustadest. Versioon 7.5 lisab madalama taseme allika API käituskeskkondadele, mis koostavad teema kihtidest, eelvaadetest, loodud failidest, kaugühendusega haakepunktidest või muudest koondatud inventaridest.

Integratsioon saab pakkuda lõplikku loogilist failipuud, samal ajal kui Blockstudio haldab plokkide, väljade, lehtede, mustrite, Site Editori, Canvase, varade ja Tailwind käitumist:

```php title="functions.php"
use Blockstudio\Inventory_Discovery_Source;

add_filter(
    'blockstudio/discovery/sources',
    function (array $sources, string $context): array {
        if ('blocks' !== $context) {
            return $sources;
        }

        return [
            new Inventory_Discovery_Source(
                'preview:feature-card',
                '/runtime-preview/feature-card/blockstudio',
                [
                    'card/block.json' => [
                        'path' => '/theme/blockstudio/card/block.json',
                        'provenance' => ['layer' => 'parent'],
                    ],
                    'card/index.php' => [
                        'path' => '/runtime-preview/feature-card/blockstudio/card/index.php',
                        'provenance' => ['layer' => 'preview'],
                    ],
                ],
                'preview-fingerprint'
            ),
        ];
    },
    10,
    2
);
```

Loogilised teed jäävad stabiilseks ka siis, kui sõsarfailid pärinevad eri füüsilistest juurtest. Allika ID-d ja sõrmejäljed määravad käitusaja ja Tailwind vahemälude identiteedi, jälgitavate sisendite muutumine muudab need kehtetuks ning päritolu määrab, kuhu loodud faile võib kirjutada. Tavaliste teemade vaikefailisüsteemi allikas jääb muutmata.

### Failipõhised Site Editori mallid

Lehed ja mustrid võimaldavad tiimidel sisu struktuure juba failides hoida. Versioon 7.5 laiendab selle mudeli ka Site Editorile.

```text
theme/
  templates/
    front-page/
      template.json
      index.php
  parts/
    header/
      part.json
      index.php
```

```json title="templates/front-page/template.json"
{
  "slug": "front-page",
  "title": "Front Page"
}
```

```php title="templates/front-page/index.php"
<div class="site-shell">
  <block name="core/template-part" slug="header" />

  <main>
    <h1>Welcome</h1>
    <block name="core/post-content" />
  </main>
</div>
```

Blockstudio kompileerib allika sama parseriga, mida kasutatakse lehtede ja mustrite jaoks, ning teeb tulemuse WordPress-ile kättesaadavaks tavalise Site Editori mallina või malliosana. Site Editor kuvab malli, kasutajaliides saab seda renderdada ning WordPress haldab endiselt kohandusi.

Viimane asjaolu on oluline. Failipõhised mallid on varuallikas. Kui kasutaja salvestab Site Editoris malli, loob WordPress andmebaasis tavalise kohanduse `wp_template` või `wp_template_part` ning see versioon jääb kehtima. Kohanduse lähtestamisel kuvatakse taas uusim failiallikas.

### Järk-järguline lehtede juurutamine

Failipõhised lehed said versioonis 7.5 juurutuse kooskõlastamise API. Alates versioonist 7.6.2 on ainsad sünkroonimise käivituskohad selgesõnalised API ja `wp bs pages sync`; tavalised päringud ei rakenda kunagi allikamuudatusi:

```php
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);
```

Protsess avastab kõigi soovitud lehtede inventari, võrdleb sisu ja sünkroonimismootori sõrmejälgi ning teatab loodud, uuendatud, muutmata, eemaldatud ja nurjunud lehtedest. Võrdsete sõrmejälgedega lehtede postitusi ega post meta andmeid ei kirjutata. Puuduolevad hallatavad lehed eemaldatakse ainult siis, kui avastamine lõpeb vigadeta.

Kooskõlastamine tagastab deterministliku allika identiteedi, kuid ei märgi juurutust õnnestunuks. Juurutustööriist salvestab selle identiteedi alles siis, kui vastavad failid ja marsruudid on aktiivsed ning kontrollitud. Tavaline WP-CLI alglaadimine registreerib vahemällu salvestatud kogumi postitustüübid ja ümberkirjutusreeglid, avastamata ja sünkroonimata kõiki lehti.

### Plokisaared

Enamik Blockstudio plokke renderdatakse serveris. See sobib hästi WordPress-iga, kuid tekitab tuttava vahemäluprobleemi: üks isikupärastatud plokk võib muuta kogu lehe vahemällu salvestamise keeruliseks.

Plokisaared eraldavad selle piiri plokitasemel.

```json title="block.json"
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}
```

Dünaamiline saar renderdab esimeses vastuses ainult vahemällu sobiva kohatäitja. Seejärel saadab brauser ühe koondpäringu kõigi lehel valmis olevate dünaamiliste saarte kohta ning Blockstudio renderdab need osad külastaja tegelikus päringukontekstis.

See tähendab, et kogu lehe vahemälu saab salvestada lehe kesta, samal ajal kui ostukorvi arv, konto juhtelemendid, õigustega piiratud UI ja muud kasutajapõhised osad jäävad ajakohaseks.

```php title="placeholder.php"
<div class="cart-count-placeholder">Loading cart...</div>
```

```php title="index.php"
<div class="cart-count">
  <?php echo esc_html(acme_cart_count()); ?>
</div>
```

Plokkide jaoks, mis juba renderdavad vahemällu sobivat HTML ja vajavad ainult kasutajaliidese paigaldussignaali, kasutage hüdratiseeritud saart:

```json title="block.json"
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}
```

Hüdratiseeritud saared ei saada päringut REST. Need renderdatakse tavapäraselt ja saavad kasutajaliideses sündmuse `blockstudio:island:hydrate`.

Dünaamilised saared toimivad ka programmiliste renderdusteede kaudu:

```php
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);
```

Ja plokisiltide kaudu:

```html
<bs:acme-cart-count product-id="42" />
```

Lõpp-punkt on teadlikult piiratud. See renderdab ainult registreeritud Blockstudio plokke, mis on dünaamilised ja selgesõnaliselt dünaamilisteks saarteks märgitud. Atribuudid filtreeritakse ploki skeemi ja saare lubatud väärtuste loendi järgi ning igal markeril on seda teenindava saidi WordPress loodud allkiri.

### Storh andmebaasisalvestus

Blockstudio andmebaasikiht toetab juba tabeleid, SQLite, JSONC, post meta andmeid ja kohandatud postitustüüpe. Versioon 7.5 lisab `storage: "storh"` projektidele, mis soovivad failipõhist salvestit turvalisemate samaaegsete kirjutuste ja skeemist tuletatud indeksitega, kuid ei soovi aktiivseid kirjeid plokkide lähtefailide kõrvale salvestada.

```php title="db.php"
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];
```

Storh kirjed asuvad üleslaadimiste kaustas:

```text
wp-content/uploads/blockstudio/db/my-theme-my-block/default/
```

Avalik API jääb muutmata. `bs.db()`, REST ja `Db::get()` tagastavad endiselt täisarvulised `id` väärtused. Sisemiselt vastendab Blockstudio need ID-d Storh dokumendi ID-dega UUIDv7-is, seega ei pea olemasolevat kliendikoodi muutma.

Iga skeemis määratletud väli indekseeritakse võrdusfiltrite jaoks; arvulised ja kuupäevalaadse väärtusega väljad saavad vahemikuindeksid ning selgesõnalised unikaalsussoovid edastatakse edasi. Projektide jaoks, mis alustasid JSONC seemnefailidega, säilitab uus CLI migreerimine lähtefaili paigas ja kirjutab samaväärse Storh salvesti:

```bash
wp bs db migrate my-theme/app subscribers --to=storh
```

See annab JSONC-ile selgema rolli lihtsa sissekandmiseks sobiva seemne- ja konfiguratsioonivorminguna, samal ajal kui Storh saab paremaks vaikefailipõhiseks taustsüsteemiks kirjutatavate tootmisandmete jaoks.

### Parseri ja bsui täiustused

Versioon 7.5 lihvib ka väiksemaid detaile, mis kipuvad esile tulema, kui projekt kasutab rohkem failipõhiseid malle ja komplekteeritud UI-i.

Elementide vastendus saab nüüd hakkama tavapärase rikasteksti lõigu juhtumiga ilma kohandatud koostajata. Kui `<p>` vastendatakse registreeritud mitte-tuumse Blockstudio plokiga, millel on rikasteksti atribuut `content`, kopeeritakse lihttekst selle atribuudi väärtuseks. Pesastatud sildid ja vastendatud alamelemendid parsitakse endiselt sisemisteks plokkideks.

`InnerBlocks` toetab mallides tokeniseeritud `allowedBlocks`-i:

```php title="index.php"
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />
```

Toetatud tokenid on `namespace/*`, `category:<slug>` ja `@theme`. Need laiendatakse serveris enne malli redaktorile edastamist, seega kasutajaliidese renderdustee jääb muutmata.

Programmilised põimimised on nüüd etteaimatavamad. `bs_render_block()` ja `bs_block()` renderdavad manustatud plokid nüüd kasutajaliideses lahendatud kujul HTML ka siis, kui neid kutsutakse teise ploki redaktori eelvaate sees. Nii ei leki pesastatud plokkidest eelvaate märgendusse toorväärtused `<RichText />` ega `<InnerBlocks />` pseudokomponendid.

Komplekteeritud UI puhul toetab `bsui/button` nüüd atribuuti `icon` ja `iconPosition`. Komplekteeritud `bsui/*` tekstisisesed stiilid väljastatakse kaskaadikihis `@layer bsui` ning nupuvariante saab laiendada `blockstudio/ui/button/variants-style` ja olemasoleva filtri `blockstudio/blocks/attributes` abil.

Plokisildid võivad samuti olla omavahel seotud. Eesliide võib lahenduda teise eesliite kaudu, nii et `<theme-ui-input />` koos projekti eesliitega `theme` nimeruumi eesliite `ui` korral lahendub kujule `bsui/input`. Registreeritud eesliite- ja aliassildid kuvatakse nüüd ka plokimalli väljundis, mitte ainult lehe sisus, nii et mall saab need otse väljastada, selle asemel et kutsuda välja `bs_render_block()`.

Kaudselt `blockstudio/block_tags/builders` kaudu registreeritud kohandatud plokikoostajad osalevad nüüd ühtselt siltide ja vastendatud elementide parsimisel. Selgesõnalised renderdusfiltrid käivituvad endiselt hiljem ja saavad koostaja tulemuse üle kirjutada.

### Kiiremad soojad päringud ja ekspordid

Käituskeskkonna ja redaktori vahemälude vaikeasukoht on nüüd `wp-content/blockstudio/cache`, mitte üleslaadimiste kaust. Asukohta saab muuta seadistusega `cache.path` või `blockstudio/cache/dir`, nii jääb püsiv vahemällusalvestus kättesaadavaks ka hostides, mis blokeerivad PHP koormad üleslaadimiste kaustas. Käitusaja, redaktori varade ja Tailwind vahemälud eemaldavad nüüd automaatselt ka vananenud kirjed, nii et pikaajalistesse projektidesse ei kogune enam piiramatult vahemälufaile.

Kasutajaliidese soojad päringud laadivad nüüd kehtiva käitusaja registri enne avastusallikate loomist. Nii jäävad ära rekursiivne allikate avastamine, plokkide loomine, väljade parsimine ja korduvad vahemäluvõtmete puu läbimised. Tootmis- ja testkeskkonna päringud usaldavad vaikimisi valideeritud jälgimishetktõmmist 20 sekundit, kohalikus ja arenduskeskkonnas kontrollitakse endiselt iga päringu korral.

Külma vahemälu loomine toimub ühe päringuna. Üks päring koostab ja avaldab koorma atomaarse toiminguna, samal ajal kui samaaegsed päringud ootavad tulemust. Tailwind säilitab nüüd vaikimisi kuni 1,000 kompileeritud kirjet 30 päeva ning kasutab uuesti kompilaatori sooja loomise olekut, nii et saidisuurune marsruutide komplekt ei pea enam pisikest vahemälu pidevalt läbi käima.

Pikaealised eksportijad saavad dokumentide vahel kutsuda `Blockstudio\Batch_Render::reset()`. See tühjendab päringupõhised loendurid, varad, saared, paigutused ja Tailwind loomise, ilma avastamist uuesti üles ehitamata. Filter `blockstudio/render/dependencies` avaldab iga renderdatud ploki kasutatud malli- ja varateed sõltuvusgraafikute jaoks.

## Töökindlus ja ühilduvus

Väljalaske lõpetavad mitu parandust:

- `blockstudio/blocks/attributes` kaudu muudetud väljade määratlused juhivad nüüd nii renderdusaegset suvandite valideerimist kui ka redaktori skeemi. Tüübitud arvulised ja tõeväärtusega suvandiväärtused lahendatakse samuti järjepidevalt.
- Redaktori plokiümbrised kasutavad samu loodud klasse mis kasutajaliidese renderdused ning Canvas saab uue filtri `blockstudio/editor/canvas/body_class` kaudu kopeerida seadistatud kasutajaliidese body-klassid.
- Content Sync valideerib enne hävitavaid kirjutustoiminguid kogu lähteplaani, hoiab kärpimistoimingud seadistatud sisukogumi piires ning teatab faili kirjutamise tõrgetest, muutmata selle üksuse sünkroonimisolekut.
- Sümbollingitud aktiivsetesse või ülemteemadesse komplekteeritud Composer paketid lahendavad redaktori varade asukohad avaliku teema URL alusel.
- Võtmega failipõhised lehed säilitavad redaktori hallatavad Blockstudio väljaväärtused, migreerivad sünkroonimisel vanema pesastatud võtmekuju ning aktsepteerivad kehtiva võtmena arvulist nulli.
- Dünaamilised saared kontrollivad allkirju enne päringu atribuutide filtreid, eiravad allkirjastamata päringukonteksti, taastavad sama päritoluga sisselogitud külastajad ning väldivad anonüümsete kasutajate vahemälu kokkupõrkeid.
- Toorväärtusega Markdown lehe lõpp-punktid arvestavad nüüd postituse nähtavuse ja paroolikaitsega.
- Redaktori juhtelemendid käsitlevad nüüd tühje tingimusi, märkeruutude kõigi väärtuste lülitamist, asünkroonseid suvandite värskendusi, dünaamilist renderdusjärjestust ning kordaja RichTexti või WYSIWYG olekut töökindlamalt.

## Kohandatud väljatüübid

Lisateavet eespool tutvustatud kohandatud väljatüüpide kohta.

### Milleks kohandatud väljatüübid?

Blockstudio peaks olema kasulik kohe kasutusele võttes, kuid päris projektides on sageli vaja valdkonnapõhiseid juhtelemente: vahetokeni valijaid, disainisüsteemi värvirolle, kohanduvaid mõõtmeid, ikooniallikaid, tootevalijaid või toimetuslikke juhtelemente, mis vastenduvad struktureeritud väärtuseks.

Enne versiooni 7.5 said sellised projektid kas ühendada mitu sisseehitatud välja või redaktori oma versiooniks teha. Versioon 7.5 pakub toetatud vahevarianti: Blockstudio haldab välja elutsüklit ja projekt juhtelementi.

```php title="functions.php"
add_action('init', function () {
    wp_register_script(
        'acme-field-dimensions',
        get_stylesheet_directory_uri() . '/fields/dimensions.js',
        ['blockstudio-blocks', 'wp-components', 'wp-element'],
        '1.0.0',
        true
    );

    bs_register_field_type('acme/dimensions', [
        'attribute'     => 'object',
        'default'       => [],
        'editor_script' => 'acme-field-dimensions',
        'storage'       => [
            'type'        => 'object',
            'rest_schema' => [
                'type'                 => 'object',
                'additionalProperties' => ['type' => 'string'],
            ],
        ],
    ]);
});
```

```js title="fields/dimensions.js"
const { createElement: el } = wp.element;
const { TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/dimensions', {
  component(props) {
    const value =
      props.value &&
      typeof props.value === 'object' &&
      !Array.isArray(props.value)
        ? props.value
        : {};
    const sides = props.sides || ['top', 'right', 'bottom', 'left'];

    return el(
      'div',
      {},
      sides.map((side) =>
        el(TextControl, {
          key: side,
          label: side,
          value: value[side] || '',
          onChange(nextValue) {
            props.onChange({
              ...value,
              [side]: nextValue,
            });
          },
        }),
      ),
    );
  },
});
```

Seejärel saab välja kasutada `block.json`-is nagu natiivset välja:

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "label": "Margin",
        "sides": ["top", "bottom"],
        "default": {
          "top": "md",
          "bottom": "md"
        }
      }
    ]
  }
}
```

### Tavalised malliväärtused

Salvestatud väärtus on kättesaadav PHP-is, Twig-is ja Blade-is nagu iga teine Blockstudio atribuut.

```php title="index.php"
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
  <?php echo esc_html($a['title'] ?? ''); ?>
</div>
```

Samad objektiteed toimivad ka laienduste mallides:

```json title="extend.json"
{
  "blockstudio": {
    "extend": "core/group",
    "attributes": [
      {
        "id": "margin",
        "type": "acme/dimensions",
        "set": [
          {
            "attribute": "class",
            "value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
          }
        ]
      }
    ]
  }
}
```

## Ühilduvuse märkused

Olemasolevad sisseehitatud väljatüübid jäävad muutmata. Ka olemasolevad `custom/{name}` korduvkasutatavad väljarühmad jäävad muutmata. Kohandatud väljatüüpide nimed peavad olema väiketähtedega ja nimeruumiga, näiteks `acme/dimensions`; nimeruumid `custom/` ja `blockstudio/` jäävad reserveerituks.

Kui PHP registreerib väljatüübi, kuid selle redaktori skript ei registreeri vastavat juhtelementi, säilitab Blockstudio salvestatud väärtuse ja kuvab redaktoris muutmatu teate. Kui väljatüüp pole registreeritud kohas PHP, jätab Blockstudio selle loodud WordPress atribuutide hulgast välja.

## 7.5.1 hooldusuuendus

7.5.1 eemaldab massiivi stringiks teisendamise hoiatuse, mis väljastati mitme valiku väärtuste renderdamiseks ettevalmistamisel. Salvestatud ja renderdatud väärtused olid juba õiged, kuid silumislogides võis iga välja renderdamise kohta olla üks hoiatus.

Ka kaasnev `blockstudio/phpstan` v0.1.7 uuendus tunneb ära anonüümsetesse rühmadesse pesastatud väljad asukohtades PHP, Twig, Blade ning tuletatud malli atribuudikujudes. Olemasolevad projektid saavad selle pakiparanduse versiooniga `composer update blockstudio/phpstan`.
