
Blockstudio 7.5 melengkapi alur kerja yang mengutamakan file milik Blockstudio: tipe field kustom, templat Site Editor berbasis file, pulau blok, penyimpanan database Storh, sumber penemuan logis, tag blok yang dapat dikomposisikan, serta jalur deployment dan runtime yang lebih cepat.

Field kustom yang dapat digunakan ulang memungkinkan proyek mendefinisikan sekali grup field yang sudah ada dan menggunakannya kembali dengan `type: "custom/{name}"`. Tipe field kustom menyelesaikan masalah yang berbeda. Fitur ini memungkinkan tema atau plugin mendaftarkan tipe field baru dengan namespace, menyediakan kontrol editornya sendiri, dan menyimpan nilainya sebagai data Blockstudio biasa.

Singkatnya:

- **Sumber penemuan logis**: runtime dapat menyediakan inventaris tema logis gabungan, termasuk asal-usul dan identitas cache, sementara Blockstudio tetap menangani penemuan, resolusi file sejajar, aset yang dihasilkan, Canvas, dan perilaku Tailwind.
- **Registry jenis field PHP**: tema dan plugin dapat mendaftarkan jenis field bernamespace seperti `acme/dimensions` dengan `bs_register_field_type()` atau filter `blockstudio/field_types`.
- **Registry kontrol editor**: skrip editor kustom dapat memanggil `window.blockstudio.registerFieldType()` dan merender kontrol React yang sesuai di Blockstudio field UI biasa.
- **Nilai terstruktur**: field kustom dapat menyimpan string, angka, boolean, array, atau objek tanpa memaksa nilai objek melalui normalisasi field opsi.
- **Dukungan penyimpanan**: meta postingan dan field kustom berbasis opsi dapat mendeklarasikan jenis nilainya dan skema REST, termasuk nilai objek dan array.
- **Integrasi native**: jenis field kustom berfungsi di dalam grup, tab, repeater, field kustom yang dapat digunakan kembali, templat, dan jalur templat ekstensi.
- **Templat Site Editor**: tema dapat menentukan sumber `wp_template` dan `wp_template_part` dari file templat `template.json`, `part.json`, dan Blockstudio.
- **Islands blok**: blok dapat merender shell yang aman untuk cache terlebih dahulu, lalu melakukan hidrasi atau mengambil fragmen khusus permintaan secara batch setelah halaman dimuat.
- **Penyimpanan database Storh**: `bs.db` dapat menggunakan penyimpanan terindeks satu file per rekaman di uploads, dengan ID integer publik tetap dipertahankan dan migrasi JSONC ke Storh melalui WP-CLI.
- **Penyempurnaan parser dan bsui**: paragraf richtext yang dipetakan memerlukan lebih sedikit kode penghubung parser kustom, `InnerBlocks` dapat menggunakan `allowedBlocks` bertoken, output `bs_render_block()` bertingkat sesuai dengan rendering frontend di pratinjau editor, dan `bsui/button` dilengkapi ikon serta hook penataan gaya yang lebih mudah.
- **Tag blok yang dapat dikomposisikan**: tag prefix dapat diresolusikan melalui prefix lain (`<theme-ui-input>` menjadi `bsui/input`), dan tag prefix serta alias dirender dalam output templat blok, bukan hanya di konten halaman.
- **Cache build yang aman untuk host**: cache runtime dan editor kini secara default disimpan di luar uploads, mendukung lokasi yang dapat dikonfigurasi, dan menghapus entri lama agar proyek yang berjalan lama tidak menumpuk file cache.
- **Rekonsiliasi halaman inkremental**: alat deployment dapat merekonsiliasi seluruh inventaris halaman berbasis file, melewati postingan yang tidak berubah, melaporkan perubahan secara persis, dan menyimpan identitas sumber terverifikasi setelah aktivasi.
- **Rendering hangat yang lebih cepat**: cache runtime yang valid dimuat sebelum penemuan, permintaan dingin yang berjalan bersamaan menerbitkan satu hasil atomik, dan Tailwind menyimpan cache sebesar situs dengan status compiler yang dapat digunakan kembali.
- **Rendering batch yang aman**: eksportir dapat mereset status rendering cakupan permintaan di antara dokumen tanpa membangun ulang penemuan, serta mengumpulkan dependensi sumber selama blok dirender.

## Fitur baru

Versi 7.5 menghadirkan beragam kemampuan baru untuk penemuan, templat, dan penyimpanan.

### Sumber penemuan logis

Blockstudio biasanya menemukan file dari direktori tema fisik. Versi 7.5 menambahkan sumber tingkat lebih rendah API untuk runtime yang menyusun tema dari overlay, pratinjau, file yang dihasilkan, mount jarak jauh, atau inventaris gabungan lainnya.

Integrasi dapat menyediakan pohon file logis final, sementara Blockstudio tetap menangani blok, field, halaman, pola, Site Editor, Canvas, aset, dan perilaku Tailwind:

```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
);
```

Jalur logis tetap stabil meskipun file sejajar berasal dari root fisik yang berbeda. ID sumber dan sidik jari menjadi bagian dari identitas cache runtime dan Tailwind, input pemantauan membatalkan cache tersebut, dan asal-usul menentukan lokasi penulisan file yang dihasilkan. Sumber sistem file default tidak berubah untuk tema biasa.

### Templat Site Editor berbasis file

Halaman dan pola memungkinkan tim menyimpan struktur konten dalam file. Versi 7.5 memperluas pendekatan ini ke Site Editor itu sendiri.

```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 mengompilasi sumber dengan parser yang sama seperti untuk halaman dan pola, lalu menyajikan hasilnya kepada WordPress sebagai templat Site Editor atau bagian templat biasa. Site Editor menampilkan templat tersebut, frontend dapat merendernya, dan WordPress tetap menangani kustomisasi.

Bagian terakhir itu penting. Templat berbasis file menjadi sumber cadangan. Jika pengguna menyimpan templat di Site Editor, WordPress membuat kustomisasi database `wp_template` atau `wp_template_part` seperti biasa dan versi tersebut yang digunakan. Hapus kustomisasinya, maka sumber file terbaru akan terlihat kembali.

### Deployment halaman inkremental

Halaman berbasis file memperoleh API rekonsiliasi deployment di versi 7.5. Sejak 7.6.2, hanya API dan `wp bs pages sync` eksplisit yang menjadi titik masuk sinkronisasi; permintaan biasa tidak pernah menerapkan perubahan sumber:

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

Proses ini menemukan seluruh inventaris halaman yang diinginkan, membandingkan konten dan sidik jari mesin sinkronisasi, lalu melaporkan halaman yang dibuat, diperbarui, tidak berubah, dihapus, dan gagal. Halaman dengan sidik jari yang sama tidak memicu penulisan post atau postmeta. Halaman terkelola yang hilang hanya dihapus setelah penemuan selesai tanpa kesalahan.

Rekonsiliasi mengembalikan identitas sumber deterministik, tetapi tidak menandai deployment sebagai berhasil. Alat deployment hanya menyimpan identitas tersebut setelah file dan rute yang sesuai aktif dan terverifikasi. Bootstrap WP-CLI biasa mendaftarkan jenis post koleksi dan rewrite yang tersimpan di cache tanpa menemukan dan menyinkronkan setiap halaman.

### Islands blok

Sebagian besar blok Blockstudio dirender di server. Ini cocok untuk WordPress, tetapi menimbulkan masalah cache yang umum: satu blok yang dipersonalisasi dapat menyulitkan caching seluruh halaman.

Islands blok memisahkan batas tersebut pada tingkat blok.

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

Island dinamis hanya merender placeholder yang aman untuk cache pada respons pertama. Browser kemudian mengirim satu permintaan gabungan untuk semua island dinamis yang siap di halaman, lalu Blockstudio merender fragmen tersebut dalam konteks permintaan asli pengunjung.

Artinya, cache halaman penuh dapat menyimpan shell halaman, sementara jumlah item di keranjang, kontrol akun, UI yang dibatasi izin, atau bagian lain per pengguna tetap diperbarui.

```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>
```

Untuk blok yang sudah merender HTML yang aman untuk cache dan hanya memerlukan sinyal mount frontend, gunakan island terhidrasi:

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

Island terhidrasi tidak membuat permintaan REST. Island dirender seperti biasa dan menerima event `blockstudio:island:hydrate` di frontend.

Island dinamis juga berfungsi melalui jalur rendering terprogram:

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

Juga melalui tag blok:

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

Endpoint ini sengaja dibuat terbatas. Endpoint hanya merender blok Blockstudio terdaftar yang bersifat dinamis dan secara eksplisit ditandai sebagai island dinamis. Atribut difilter berdasarkan skema blok dan daftar izin island, dan setiap marker membawa tanda tangan yang dihasilkan oleh situs WordPress yang melayaninya.

### Penyimpanan database Storh

Lapisan database Blockstudio sudah mendukung tabel, SQLite, JSONC, meta post, dan jenis post kustom. Versi 7.5 menambahkan `storage: "storh"` bagi proyek yang menginginkan penyimpanan berbasis file dengan penulisan konkuren yang lebih aman dan indeks turunan skema, tetapi tidak ingin rekaman aktif disimpan bersama file sumber blok.

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

Rekaman Storh disimpan di uploads:

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

API publik tetap sama. `bs.db()`, REST, dan `Db::get()` tetap mengembalikan nilai integer `id`. Secara internal, Blockstudio memetakan ID tersebut ke ID dokumen UUIDv7 milik Storh, sehingga kode klien yang ada tidak perlu diubah.

Setiap field skema yang dideklarasikan diindeks untuk filter kesetaraan; field numerik dan yang menyerupai tanggal memperoleh indeks rentang, dan petunjuk unik eksplisit diteruskan. Untuk proyek yang dimulai dengan file seed JSONC, migrasi CLI baru mempertahankan file sumber di tempatnya dan menulis penyimpanan Storh yang setara:

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

Dengan begitu, JSONC memiliki peran yang lebih jelas sebagai format seed/konfigurasi sederhana yang dapat di-commit, sementara Storh menjadi backend file default yang lebih baik untuk data produksi yang dapat ditulis.

### Penyempurnaan parser dan bsui

Versi 7.5 juga menyempurnakan bagian-bagian kecil yang mulai terasa penting ketika proyek lebih banyak mengandalkan templat berbasis file dan UI yang dibundel.

Pemetaan elemen kini dapat menangani kasus paragraf richtext umum tanpa builder kustom. Jika `<p>` dipetakan ke blok Blockstudio non-core yang terdaftar dengan atribut richtext `content`, teks biasa di dalam elemen akan disalin ke atribut tersebut. Tag bertingkat dan elemen anak yang dipetakan tetap diurai sebagai blok dalam.

`InnerBlocks` menerima `allowedBlocks` bertoken di dalam templat:

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

Token yang didukung adalah `namespace/*`, `category:<slug>`, dan `@theme`. Token diperluas di server sebelum editor menerima templat, sehingga jalur rendering frontend tetap sama.

Embed terprogram juga lebih dapat diprediksi. `bs_render_block()` dan `bs_block()` kini merender blok embed sebagai HTML yang diresolusikan frontend, bahkan saat dipanggil dari dalam pratinjau editor blok lain. Dengan demikian, blok bertingkat tidak membocorkan `<RichText />` mentah atau pseudo-komponen `<InnerBlocks />` ke markup pratinjau.

Untuk UI yang dibundel, `bsui/button` kini mendukung atribut `icon` dan `iconPosition`. Gaya inline `bsui/*` yang dibundel dikeluarkan dalam lapisan kaskade `@layer bsui`, dan varian tombol dapat diperluas dengan `blockstudio/ui/button/variants-style` serta filter `blockstudio/blocks/attributes` yang sudah ada.

Tag blok juga dapat dikomposisikan lebih lanjut. Sebuah prefix dapat diresolusikan melalui prefix lain, sehingga `<theme-ui-input />` dengan prefix proyek `theme` di atas namespace `ui` diresolusikan menjadi `bsui/input`. Tag prefix dan alias terdaftar kini juga dirender dalam output templat blok, bukan hanya konten halaman, sehingga templat dapat mengeluarkannya secara langsung tanpa memanggil `bs_render_block()`.

Builder blok kustom yang didaftarkan melalui `blockstudio/block_tags/builders` juga berpartisipasi secara konsisten dalam penguraian tag dan elemen yang dipetakan. Filter renderer eksplisit tetap dijalankan sesudahnya dan dapat menggantikan builder.

### Permintaan hangat dan ekspor lebih cepat

Cache runtime dan editor kini secara default disimpan di `wp-content/blockstudio/cache`, bukan uploads. Lokasinya dapat diubah melalui `cache.path` atau `blockstudio/cache/dir`, sehingga caching persisten tetap tersedia pada host yang memblokir payload PHP di uploads. Cache runtime, aset editor, dan Tailwind juga secara otomatis menghapus entri lama, sehingga proyek yang berjalan lama tidak lagi menumpuk file cache di disk tanpa batas.

Permintaan frontend hangat kini memuat registry runtime yang valid sebelum membangun sumber penemuan. Ini melewati penemuan sumber rekursif, konstruksi blok, penguraian field, dan penelusuran ulang pohon kunci cache. Secara default, permintaan produksi dan staging memercayai snapshot pemantauan yang telah divalidasi selama 20 detik, sedangkan lingkungan lokal dan pengembangan tetap memeriksa pada setiap permintaan.

Pembuatan cache dingin kini menggunakan mekanisme single-flight. Satu permintaan membangun dan menerbitkan payload secara atomik sementara permintaan lain yang berjalan bersamaan menunggu hasilnya selesai. Tailwind kini menyimpan hingga 1,000 entri terkompilasi selama 30 hari secara default dan menggunakan kembali status konstruksi compiler yang hangat, sehingga kumpulan rute sebesar situs tidak lagi terus-menerus mengganti isi cache yang kecil.

Eksportir yang berjalan lama dapat memanggil `Blockstudio\Batch_Render::reset()` di antara dokumen. Fungsi ini menghapus penghitung, aset, island, tata letak, dan pembuatan Tailwind yang tercakup dalam permintaan tanpa membangun ulang penemuan. Filter `blockstudio/render/dependencies` menampilkan jalur templat dan aset yang digunakan setiap blok yang dirender untuk membuat grafik dependensi.

## Keandalan dan kompatibilitas

Beberapa perbaikan melengkapi rilis ini:

- Definisi field yang diubah melalui `blockstudio/blocks/attributes` kini juga mengatur validasi opsi saat rendering, selain skema editor. Nilai opsi numerik dan boolean bertipe juga diresolusikan secara konsisten.
- Wrapper blok editor menggunakan kelas yang sama dengan hasil rendering frontend, dan Canvas dapat menyalin kelas body frontend yang dikonfigurasi melalui filter `blockstudio/editor/canvas/body_class` baru.
- Content Sync memvalidasi seluruh rencana sumber sebelum penulisan destruktif, membatasi operasi pembersihan pada kumpulan konten yang dikonfigurasi, dan melaporkan kegagalan penulisan file tanpa memajukan status sinkronisasi entitas tersebut.
- Paket Composer yang dibundel dalam tema aktif atau tema induk yang disymlink kini mengresolusikan aset editor dari URL tema publik.
- Halaman file berkunci mempertahankan nilai field Blockstudio yang dikelola editor, memigrasikan bentuk kunci bertingkat lama saat sinkronisasi, dan menerima nol numerik sebagai kunci yang valid.
- Island dinamis memverifikasi tanda tangan sebelum filter atribut permintaan, mengabaikan konteks permintaan tanpa tanda tangan, memulihkan pengunjung login dari origin yang sama, dan menghindari benturan cache anonim per pengguna.
- Endpoint halaman Markdown mentah kini mematuhi visibilitas post dan perlindungan kata sandi.
- Kontrol editor kini lebih andal dalam menangani kondisi kosong, nilai centang semua pada checkbox, pembaruan opsi asinkron, urutan rendering dinamis, dan status RichText atau WYSIWYG repeater.

## Jenis field kustom

Selengkapnya tentang jenis field kustom yang diperkenalkan di atas.

### Mengapa jenis field kustom?

Blockstudio sebaiknya tetap bermanfaat langsung setelah dipasang, tetapi proyek nyata sering memerlukan kontrol khusus domain: pemilih token spasi, peran warna sistem desain, dimensi responsif, sumber ikon, pemilih produk, atau kontrol editorial yang dipetakan ke nilai terstruktur.

Sebelum versi 7.5, proyek semacam itu dapat menggabungkan beberapa field bawaan atau melakukan fork pada editor. Versi 7.5 menyediakan jalan tengah yang didukung: Blockstudio menangani siklus hidup field, sementara proyek menangani kontrolnya.

```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,
            });
          },
        }),
      ),
    );
  },
});
```

Setelah itu, field dapat digunakan di `block.json` seperti field native:

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

### Nilai templat biasa

Nilai yang disimpan tersedia di PHP, Twig, dan Blade seperti atribut Blockstudio lainnya.

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

Jalur objek yang sama juga berfungsi di templat ekstensi:

```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}"
          }
        ]
      }
    ]
  }
}
```

## Catatan kompatibilitas

Jenis field bawaan yang sudah ada tidak berubah. Grup field dapat digunakan kembali `custom/{name}` yang sudah ada juga tidak berubah. Nama jenis field kustom harus menggunakan huruf kecil dan namespace, misalnya `acme/dimensions`; namespace `custom/` dan `blockstudio/` tetap dicadangkan.

Jika PHP mendaftarkan jenis field tetapi skrip editornya tidak mendaftarkan kontrol yang sesuai, Blockstudio mempertahankan nilai tersimpan dan menampilkan pemberitahuan yang tidak dapat diedit di editor. Jika jenis field tidak terdaftar di PHP, Blockstudio tidak menyertakannya dalam atribut WordPress yang dihasilkan.

## Pembaruan pemeliharaan 7.5.1

7.5.1 menghapus peringatan konversi array ke string yang muncul saat menyiapkan nilai pilihan ganda untuk dirender. Nilai yang disimpan dan dirender sebelumnya sudah benar, tetapi log debug dapat menerima satu peringatan untuk setiap rendering field.

Pembaruan `blockstudio/phpstan` v0.1.7 yang menyertainya juga mengenali field yang berada di dalam grup anonim pada PHP, Twig, Blade, serta bentuk atribut templat hasil inferensi. Proyek yang ada dapat memperoleh perbaikan paket tersebut melalui `composer update blockstudio/phpstan`.
